08 — Security Architecture
Status: 🔧 Partial — confirmed principles from TD6 documented; implementation specifics pending Infrastructure and Security sessions
Prerequisite: TD6, 06 — Authentication Flow, 07 — Authorization Model
Full security design for the Miqaat Core Platform — network topology, TLS, secret management, API Gateway security, audit log design, encryption at rest, and incident response.
Sections marked ⏳ are blocked on the Dedicated Infrastructure session or Dedicated Security session. Confirmed principles from TD6 are written as fixed decisions.
1. Security Posture (Confirmed from TD6)
The following are confirmed security principles. They are not subject to revision without a TD6 amendment.
| Principle | Detail |
|---|---|
| Single entry point | All external traffic reaches Core through the API Gateway only. No Core engine is directly reachable from outside the private network. |
| Zero trust between modules and Core | Every module request is authenticated and authorised at the Gateway — no implicit trust based on network location. |
| Credentials never reach engines | The Identity Bridge strips all credentials before forwarding requests. Engines only see clean headers. |
| Read/write split enforced at Gateway | Module API keys are rejected on write endpoints at the Gateway — no write request from a module reaches an engine. |
| Immutable audit trail | Every state-changing operation across all Core engines is written to the Audit Log. Audit records cannot be modified or deleted — append only. |
| Secrets not in config files | API keys, database credentials, and signing keys are never stored in application config files or source code. Secrets are injected at runtime from a dedicated secrets store. |
| TLS everywhere | All traffic — external (module to Gateway) and internal (Gateway to engine, engine to engine) — is encrypted in transit. No unencrypted HTTP inside the platform network. |
| Principle of least privilege | Each Core engine only holds credentials and network access for the data stores and services it directly needs. No engine has blanket access to the full platform. |
2. Network Topology
⏳ Exact topology — pending Infrastructure session (cloud provider, VPC design, subnet layout)
Confirmed structure
Internet
│
▼
┌─────────────────┐
│ API Gateway │ ← Only component with public IP
│ (+ Identity │
│ Bridge) │
└────────┬────────┘
│ Private network only
▼
┌─────────────────────────────────────────────┐
│ Core Private Network │
│ │
│ RBAC Engine Eligibility Engine │
│ Config Cascade Miqaat Lifecycle │
│ Allocation Zone Mapping │
│ Vendor Registry HR Bank │
│ Capacity Balance Task Engine │
│ Audit Log Notification Dispatch │
│ ITS Sync Event Schema Registry │
│ │
│ Data stores (per-engine, not shared) │
│ Event Bus │
└─────────────────────────────────────────────┘
What this means:
- Modules call
https://core.miqaat.platform/v1/...— this resolves to the API Gateway's public endpoint - The API Gateway is the only component with an externally reachable address
- Core engines have no public IP or DNS — they are unreachable except from within the private network
- The event bus is also internal — modules do not connect to the event bus directly; they publish via the Gateway or consume via a managed subscription endpoint
⏳ TBC in Infrastructure session: whether the private network is a cloud VPC, an on-premises network segment, or a hybrid. Also: whether the Gateway is a managed cloud service or self-hosted, and what the high-availability configuration is.
3. TLS and Certificate Management
Confirmed: all traffic is TLS-encrypted. No plaintext HTTP anywhere.
| Segment | TLS requirement |
|---|---|
| Module → API Gateway | TLS 1.2 minimum, TLS 1.3 preferred |
| API Gateway → Core engines (internal) | TLS required — internal traffic is not exempt |
| Engine → data store | TLS required where the data store supports it |
| Engine → event bus | TLS required |
⏳ TBC in Infrastructure session:
- Certificate authority (managed cloud CA vs Let's Encrypt vs internal CA)
- Certificate rotation policy and tooling
- Whether mTLS (mutual TLS) is required on internal engine-to-engine calls
- TLS termination point — does the Gateway terminate and re-encrypt, or pass through?
4. Secret Management
Confirmed from TD6: secrets are never in config files or source code. All credentials are injected at runtime.
| Secret type | Examples |
|---|---|
| Database credentials | Engine-specific DB username and password |
| API keys (inbound) | Module API keys issued by Platform Admin |
| Signing keys | ITS token public key for JWT validation |
| Event bus credentials | Per-engine topic access credentials |
| Internal service credentials | Engine-to-engine call credentials |
Principle: each engine's runtime environment receives only the secrets it needs. No engine has access to another engine's database credentials or internal keys.
⏳ TBC in Infrastructure session:
- Secrets management tooling (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, or similar)
- Secret rotation schedule and automation
- Who has access to the secrets store (Core technical team only vs ops team access)
- Audit logging of secret access
5. API Gateway Security
The API Gateway is the security enforcement layer. Everything documented here is confirmed from TD2 and TD3.
Enforced at Gateway — no engine involvement needed
| Control | How it's enforced |
|---|---|
| ITS token validation | Identity Bridge validates signature and expiry on every user-initiated request |
| API key validation | Bridge checks key exists and is not revoked before routing |
| Read/write split | Module API keys rejected on write endpoints — AUTH_MODULE_NOT_PERMITTED (403) |
| Rate limiting | Per-module rate limits configured in Platform Admin — RATE_LIMIT_EXCEEDED (429) on breach |
X-Module-Id enforcement | Module's declared ID must match the API key — mismatch rejected |
| Credential stripping | Raw token and API key removed before request reaches any engine |
What the Gateway does NOT do
- RBAC permission evaluation — that is the RBAC Engine's job
- Business logic validation — that belongs in each engine
- Response content filtering — engines return what they return; the Gateway passes it through
6. Audit Log Design
The Audit Log Backbone is the immutable record of all state-changing operations across the platform. It is not a debugging log — it is a compliance and accountability record.
What is audited
Every write operation across all Core engines is recorded. This includes:
| Category | Examples |
|---|---|
| Role operations | Role assigned, role revoked |
| Allocation operations | Allocation confirmed, waitlisted, released |
| Miqaat operations | Miqaat created, phase changed, archived |
| Config operations | Config key set or overridden |
| Rule operations | Rule set created or modified |
| Registration and eligibility | Registration confirmed, eligibility status changed |
| Khidmat and HR | Khidmat assigned, completed |
| API key operations | Key issued, revoked, rotated |
| Platform Admin actions | Any write performed by a Platform Admin user |
Module-published events (registration, attendance, scanning, etc.) are also written to the Audit Log via the event bus subscription — the Audit Log is a subscriber to all events.
Audit record structure
Each audit record captures:
| Field | Description |
|---|---|
auditId | Unique record identifier |
engine | Which Core engine produced this record |
action | What happened (e.g. allocation.confirmed, role.assigned) |
miqaatId | Miqaat scope — present on all person or Miqaat-specific actions |
itsId | The Mumin the action concerns — absent on structural actions |
actorItsId | The person who triggered the action (Platform Admin user or module user) |
moduleId | The module that initiated the call, if applicable |
details | Engine-specific context (e.g. allocationId, roleId, ruleSetId) |
recordedAt | When the audit record was written — server time, UTC |
correlationId | The X-Correlation-Id of the originating request — links audit record to request trace |
Immutability
Audit records are append-only. There is no update or delete operation on the Audit Log — not even for Platform Admin. If a record needs to be corrected (e.g. a mis-attributed action), a new compensating record is appended, not an edit to the original.
⏳ TBC in Security session:
- Storage backend for the Audit Log (separate database, write-once object storage, or managed audit service)
- Retention period per record type (see Event Catalog Section 6 for initial tiers — subject to compliance review)
- Whether audit log access requires a separate credential beyond
PLATFORM_ADMIN- Export format for compliance reporting
7. Encryption at Rest
Confirmed principle from TD6: sensitive data is encrypted at rest. The exact scope and tooling are pending.
⏳ TBC in Infrastructure and Security sessions:
- Which data stores require encryption at rest (likely all of them — confirm scope)
- Encryption standard (AES-256 or equivalent)
- Key management for data-at-rest encryption keys (separate from secret management in Section 4)
- Whether encryption is handled at the storage layer (cloud-managed) or at the application layer
- ITS sync data — how personal data from ITS is stored and whether additional protection beyond standard encryption applies
8. Module Security Requirements
Modules integrating with Core must meet these security requirements before going live. These are enforced as part of the module onboarding checklist.
| Requirement | Detail |
|---|---|
| API key in secrets store | Module API key must not be in source code, config files, or .env files committed to version control |
| HTTPS only | Module must call Core over HTTPS — no HTTP fallback |
| RBAC caching implemented | Module must implement the permission caching pattern (see 03 — API Contracts, C-010) — not per-action calls |
X-Request-Id on every call | Modules must generate and pass a UUID per request for tracing |
| Idempotency key on mutations | Mutation calls must use X-Idempotency-Key to prevent duplicate operations on retry |
| Error handling — no credential exposure | Module must not surface Core error details (including error.details) directly in its UI — log internally only |
⏳ Full module security checklist — pending Security session (additional requirements around data handling, logging, and vulnerability disclosure may be added)
9. Incident Response
⏳ Pending Dedicated Security session
The incident response plan covers:
- Compromised API key procedure — revocation, audit log review, module notification
- Compromised Platform Admin account — immediate revocation, audit trail review, escalation path
- Data breach response — notification obligations, containment steps
- Core engine outage during a live Miqaat — escalation path and communication plan
- Event bus failure — fallback procedures for modules dependent on Core events
10. Open Questions
| Question | Blocked On |
|---|---|
| Cloud provider and network topology (VPC, subnets, AZs) | Infrastructure session |
| API Gateway product selection (managed vs self-hosted) | Infrastructure session |
| Whether mTLS is required on internal engine traffic | Infrastructure session + Security session |
| Certificate authority and rotation tooling | Infrastructure session |
| Secrets management tooling selection | Infrastructure session |
| Audit log storage backend and retention periods | Security session |
| Encryption at rest — scope, standard, and key management | Infrastructure + Security session |
| Whether ITS personal data requires additional protection beyond standard at-rest encryption | Security session + ITS Technical session |
| Full module security checklist | Security session |
| Incident response plan | Security session |
| Penetration testing schedule and scope | Security session |