TD6 — Security Recommendations
Decision Status Labels ✅ Decided — confirmed in a stakeholder session. Can be built against. 🔍 Under Analysis — options identified. Do not build against yet. 📅 Pending Session — requires a specific session or external input before a decision can be made.
1. Security Posture and Principles
Security for this platform is not a separate workstream bolted on at the end. Most of the foundational security decisions are already embedded in the architecture — the Authentication Policy, the Authorisation Policy, the Data Ownership Policy, the API key model, and the Audit Log Backbone are all security decisions, even though they were made as architectural ones.
This document surfaces those confirmed security properties, identifies what remains to be decided, and defines the specific threats this platform must defend against.
✅ Confirmed security principles
Defense in depth. No single mechanism is the sole protection. Authentication at the ITS layer, API key validation at the gateway, RBAC at the engine layer, write endpoint restriction, audit logging — these are independent layers. Compromising one does not compromise the platform.
Least privilege. Every actor — module, operator, Core engine — gets only the access it needs. Module API keys grant access only to read endpoints. Write endpoints are restricted to Platform Admin and Core-internal processes. Bus credentials grant access only to the module's registered event types.
Zero trust for all module-to-Core communication. No module is implicitly trusted. Every call to Core carries credentials (API key + optionally ITS token). Every call is validated at the gateway before any engine sees it. No trust by network location alone.
Breach containment by design. If one module's API key is compromised, it is revoked from Platform Admin immediately — no other module is affected, no Core restart required. The blast radius of a credential compromise is bounded to the module whose key was compromised.
Immutable audit trail. Every significant action on the platform is logged to the Audit Log Backbone. The log cannot be modified or deleted. If something goes wrong, there is always a record of what happened, when, and which actor triggered it.
2. Identity and Access Security
✅ ITS is the only identity provider — no parallel identity systems
No module creates its own user accounts, issues its own tokens, or maintains its own password store. Every human actor on the platform authenticates via ITS. This is the Authentication Policy. A credential database breach in a business module cannot expose user credentials — modules do not store them.
✅ Identity Bridge — token validation before any engine sees a request
Core's Identity Bridge validates the ITS token at the API Gateway before the request reaches any Core engine. Downstream engines receive only a verified itsId header — never the raw token. A malformed, expired, or forged ITS token is rejected at the gateway. No engine handles token validation logic — it is centralised in one place.
✅ API keys — module identity, not user identity
API keys authenticate the calling module, not the user. They are separate from ITS tokens and serve a separate purpose. A stolen API key tells an attacker which module they can impersonate — it does not give them a user identity. The combination of module identity (API key) and user identity (ITS token) is what Core engines use for attribution.
API key security properties confirmed:
- One key per module per environment — dev keys cannot be used against production
- Immediate revocation from Platform Admin — a compromised key is dead within seconds
- Dual-key grace period during rotation — modules can rotate without downtime
- Keys are never committed to source control — secret management is required (mechanism under analysis, Section 5)
- Keys grant read-only access to Core APIs — write endpoints rejected at gateway regardless of key validity
✅ Core RBAC — single permission authority, no local bypass
Every permission check across all 32 modules goes through Core RBAC. A module cannot bypass it by checking locally. There is no "I know this user is an admin so I'll skip the RBAC call" pattern — the call is always made. This means a compromised module cannot self-grant elevated permissions. The permission authority lives in Core, not in the module.
✅ Write endpoints — restricted at the gateway, not at the engine
Write endpoints (anything that mutates Core state) reject module API keys at the gateway layer — the request never reaches the engine. Even if a module has a valid API key and a valid ITS token, calling a write endpoint returns a gateway-level rejection. There is no engine-level configuration that can accidentally open a write endpoint to modules.
3. Communication Security
✅ All external communication over HTTPS
All communication between modules and Core's API Gateway is over HTTPS. All communication between modules and the event bus is encrypted in transit. Unencrypted communication to Core is not accepted. This applies regardless of whether the traffic is on a private network or the public internet.
✅ No direct module-to-module calls
The Communication Policy prohibits direct calls between modules. This is not only an architectural boundary — it is a security boundary. Direct module-to-module calls would mean a compromised module could impersonate itself to other modules with no platform-level oversight. All cross-module interactions route through Core APIs (audited) or the event bus (scoped by publish and subscribe authorization).
✅ Event publish authorization — sourceModule cannot be spoofed
The event publish authorization requirements (TD2 Section 3) include a check that the sourceModule field in the event envelope matches the calling module's verified identity. A module cannot publish an event and claim it came from a different module. The enforcement mechanism (Core gateway vs bus-level ACLs) is under analysis, but the requirement to prevent sourceModule spoofing is confirmed.
🔍 Internal service communication encryption — within Core
Within Core, FastAPI and Node.js services communicate with each other. Whether this internal traffic is encrypted (mutual TLS between services) or travels over a trusted internal network without additional encryption is under analysis. In a shared cloud environment, encrypting internal service-to-service traffic is best practice. Decision tied to the infrastructure and dedicated security sessions.
📅 Network security — firewall rules, VPC isolation, public vs private endpoints
Whether Core's API Gateway is publicly accessible or accessible only via a private network, and what firewall and security group rules govern traffic between Core services, modules, and ITS, is pending the ITS infrastructure session and the dedicated security session. The requirement is clear: modules must reach Core's Gateway and event bus; everything else Core runs should not be reachable from outside Core's own infrastructure.
4. Platform-Specific Threat Model
Generic security checklists miss the threats specific to this platform. These are the attack surfaces that matter here.
✅ Miqaat allocation fraud — mitigated by Core as the single allocator
Allocation decisions are made exclusively by Core's Allocation Engine. No module can self-grant an allocation. A compromised module UI can display false information but cannot create an allocation record in Core — it can only call Core's allocation API, which enforces all eligibility and capacity rules. Allocation fraud requires compromising Core itself, not a business module.
✅ Duplicate and fraudulent registration — mitigated by itsId as the universal identifier
Every actor on the platform is identified by a single itsId from ITS. Core's engines work with itsId — not with module-local user IDs. A user cannot have two itsIds. This makes duplicate registration attempts detectable at the Core layer (same itsId appearing in two conflicting allocations), not dependent on each module independently detecting the conflict.
✅ Privilege escalation via module — mitigated by gateway write restriction
A compromised module cannot escalate its own permissions or those of its users by calling Core write endpoints. Write endpoints are blocked at the gateway for module API keys. A module calling Core's role assignment endpoint is rejected before the request reaches the RBAC engine.
✅ Event impersonation — mitigated by publish authorization
A module cannot publish events that appear to come from another module. The sourceModule check in the event publish authorization confirms the publishing module's identity matches the envelope. A compromised AMS cannot publish volunteer.assigned events that appear to come from VMS.
🔍 API key theft — rate limiting and anomaly detection
If a module's API key is stolen and used by an external actor, the current confirmed mitigations are: immediate revocation capability, and the key being limited to read endpoints only. Rate limiting per module API key — to flag abnormal request volumes that might indicate key misuse — is under analysis. Anomaly detection on API Gateway traffic patterns is a future capability (aligned with the AI utilities in CoreUtilities.md).
📅 ITS token theft — dependent on ITS session management details
If an ITS token is stolen and presented to Core's Identity Bridge, Core would validate it as legitimate. The protection against this is ITS's own token security — short token lifetimes, single-session enforcement, and secure token transmission. The specific mitigations are defined in C-001 (the ITS SSO Token Contract), which is pending the ITS technical session.
5. Secret Management
✅ Secrets must not be committed to source control — confirmed requirement
No API key, database credential, bus credential, or any other secret is committed to any source code repository — Core's or any module's. This is a non-negotiable. Secrets discovered in source control are treated as compromised and rotated immediately.
✅ Secrets are environment-specific
Dev secrets cannot be used in staging. Staging secrets cannot be used in production. Every environment has its own set of secrets. This was confirmed in TD5 (three isolated environments). A leaked dev API key cannot affect the production platform.
🔍 Secret management technology
The tooling for storing, distributing, and rotating secrets — for Core services (database credentials, bus credentials, ITS integration keys) and for modules (their Core API keys) — is under analysis. Options include:
| Option | Description |
|---|---|
| Cloud provider secret manager (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager) | Managed, integrates with container orchestration, audit logging built in |
| HashiCorp Vault | Cloud-agnostic, self-hosted, more control — higher operational overhead |
| Kubernetes Secrets (with encryption at rest) | Simple for Kubernetes-hosted services, limited audit capability |
The decision is tied to the cloud provider choice (TD5). Whatever is chosen must support: automatic secret rotation, audit logging of secret access, and revocation without service restart.
6. Data Security
✅ Data Ownership Policy as a security boundary
The Data Ownership Policy (no cross-module database access) is also a data security boundary. A breach of one module's database does not expose any other module's data. Each module's operational data is siloed — the attack surface of a database breach is bounded to the module whose database was compromised.
✅ Core data — owned and operated by Core team only
Core's databases (role assignments, miqaat state, audit log, config cascade, ITS sync copy) are operated by the Core team only. No module team has direct access to Core's databases. Modules access Core data only through Core's read APIs.
🔍 Encryption at rest
Whether Core's databases, the audit log storage, and the event bus storage are encrypted at rest is under analysis and tied to the infrastructure decision. In a cloud environment, encryption at rest is typically enabled by default on managed services and is the expected standard. This will be confirmed in the dedicated security session.
📅 Data classification and PII handling
The platform processes Mumineen personal data — names, ITS IDs, attendance history, family details, accommodation assignments. A formal data classification policy (what is considered PII, how it is handled, retention periods, deletion rights) has not been defined. This requires a dedicated session covering both the platform's obligations and the community's expectations.
📅 Compliance requirements
Whether the platform is subject to specific data protection regulations (GDPR, local data protection laws, community-specific requirements) has not been assessed. This must be determined before the platform handles Mumineen data at scale. The dedicated security session should include this assessment.
7. Audit and Accountability
✅ Audit Log Backbone — immutable record of all significant actions
The Audit Log Backbone (TD1 Section 2) captures every allocation decision, permission check, role change, config override, and event publish attempt. It cannot be modified or deleted. It is searchable by itsId, module, action type, miqaat, and date range. This is the primary accountability mechanism for the platform.
What is always in the audit log:
- Every Core RBAC permission check — who asked, what they asked, what the answer was
- Every role assignment and revocation — who was assigned, by whom, at what scope
- Every miqaat lifecycle transition — which phase, triggered by which operator
- Every config cascade override — which value, at which level, by whom
- Every allocation decision — which itsId, which city, which engine run
- Every event publish attempt — module identity, event type, success or rejection
- Every API key revocation — which module, at what time
✅ Platform Admin access is itself audited
Every action taken in Platform Admin — role assignments, config overrides, allocation triggers, key revocations — is a permanent audit record. Irreversible actions require explicit confirmation with justification text. There are no silent overrides.
📅 Log retention policy
How long audit records are retained before archival or deletion is pending the data classification and compliance session. The requirement is: retention must be long enough to support any compliance review the community may require.
8. Module Security Requirements
These are the security requirements that apply to all business modules — not Core's internal security, but what every module must do to be considered secure on this platform.
✅ Confirmed module security requirements
- No local permission tables. All permission enforcement is through Core RBAC. A module that maintains its own permission table alongside Core RBAC creates a shadow access system that can diverge.
- No ITS data copies. Modules do not maintain their own ITS sync. Stale copies of sensitive ITS data in multiple module databases increases the data breach surface.
- No direct module-to-module calls. All cross-module interactions go through Core or the event bus, where they are audited.
- No secrets in source control. Applies to all modules, not just Core.
- Idempotent event consumers. Not a direct security requirement, but idempotency failures can produce duplicate records (duplicate registrations, duplicate payments) — a data integrity concern with security implications.
- HTTPS only for module APIs. Any API a module exposes to its own clients must be over HTTPS.
📅 Module-level penetration testing
Whether individual modules are required to undergo penetration testing before going live, and on what schedule, is pending the dedicated security session. The platform-level (Core + Gateway + event bus) penetration testing schedule is also pending.
9. Pending — Dedicated Security Session
The following items require a dedicated security session with the Core team, ITS team, and a security specialist. They cannot be addressed by architectural decisions alone.
| Topic | Why it needs a session |
|---|---|
| Network security model (firewall rules, VPC isolation, public vs private endpoints) | Depends on cloud provider and ITS network topology — both pending |
| Encryption at rest (databases, audit log, bus storage) | Technology and configuration choices — inform infrastructure selection |
| Internal service-to-service encryption within Core | Trade-off between security and operational complexity |
| Secret management tooling and rotation policy | Tied to cloud provider and orchestration decision |
| Data classification and PII handling policy | Community-specific, not a standard compliance template |
| Compliance requirements assessment | May impose hard constraints on data residency and retention |
| Log retention policy | Depends on compliance requirements |
| Penetration testing schedule (platform and module level) | Requires security specialist to scope |
| ITS token security (tied to C-001 technical session) | Token lifetime, refresh, theft mitigations |
| API Gateway rate limiting — thresholds and response | Threat modelling needed to set correct values |
| Incident response plan | Process, not technology — requires stakeholder alignment |
| Vulnerability scanning and dependency management policy | Process for Core team and module teams |
Decision Summary
| Decision | Status | Notes |
|---|---|---|
| Defense in depth — multiple independent security layers | ✅ Decided | Auth, gateway, RBAC, audit — independent layers |
| Least privilege — API keys grant read-only access only | ✅ Decided | Write endpoints blocked at gateway for all module keys |
| Zero trust — every module call carries credentials, validated at gateway | ✅ Decided | No implicit trust by network location |
| Breach containment — compromised key revoked without affecting other modules | ✅ Decided | Immediate revocation from Platform Admin |
| ITS is the only identity provider — no parallel credential stores in modules | ✅ Decided | Authentication Policy |
| Identity Bridge validates tokens before any engine sees the request | ✅ Decided | Engines receive only verified itsId |
| API keys are environment-specific (dev keys cannot access production) | ✅ Decided | Three isolated environments — TD5 |
| Secrets must not be committed to source control | ✅ Decided | Any discovered secret treated as compromised |
| Secrets are environment-specific | ✅ Decided | Leaked dev secret cannot affect production |
| Core RBAC is the only permission authority — no local bypass in modules | ✅ Decided | Authorisation Policy |
| Write endpoints blocked at gateway for module API keys | ✅ Decided | Engine never receives the request |
| All external communication over HTTPS | ✅ Decided | Modules to Gateway, modules to bus |
| No direct module-to-module calls | ✅ Decided | Communication Policy — also a security boundary |
| sourceModule cannot be spoofed in event publishing | ✅ Decided | Enforced by publish authorization mechanism |
| Audit Log Backbone — immutable, captures all significant actions | ✅ Decided | Cannot be modified or deleted |
| Platform Admin actions are themselves audited with justification | ✅ Decided | No silent overrides |
| Data Ownership Policy enforced as a security boundary | ✅ Decided | Module DB breach bounded to that module only |
| Core databases accessible to Core team only | ✅ Decided | No module team has direct DB access |
| Internal service-to-service encryption within Core | 🔍 Under Analysis | Dedicated security session |
| Rate limiting per module API key | 🔍 Under Analysis | Threat modelling needed for threshold values |
| Secret management technology | 🔍 Under Analysis | Tied to cloud provider decision |
| Encryption at rest | 🔍 Under Analysis | Dedicated security session |
| Network security model | 📅 Pending Session | ITS infrastructure + dedicated security session |
| Data classification and PII handling policy | 📅 Pending Session | Community-specific — dedicated session required |
| Compliance requirements | 📅 Pending Session | May impose hard constraints |
| Log retention policy | 📅 Pending Session | Depends on compliance requirements |
| Penetration testing schedule | 📅 Pending Session | Dedicated security session |
| ITS token security details | 📅 Pending Session | C-001 ITS technical session |
| Incident response plan | 📅 Pending Session | Stakeholder alignment required |