Document recursive platform security architecture

docs/adr/ADR-0006-recursive-multi-tenant-identity-authorization.md

@@ -0,0 +1,96 @@
+# ADR-0006 - Recursive Multi-Tenant Identity and Authorization Architecture
+
+**Status:** Accepted
+**Date:** 2026-05-17
+**Deciders:** Bernd Worsch
+
+## Context
+
+The Coulomb platform is being built from the same repositories and
+services that will later support other use cases. This creates a
+recursive architecture problem: Coulomb needs to use the shared identity,
+security, policy, and deployment capabilities, while those capabilities
+are themselves part of the infrastructure being built.
+
+If this recursion is left implicit, the first internal use case can drift
+into being treated as the platform root of trust. That would make future
+multi-tenant use harder, blur operational authority, and make secure
+bootstrap/recovery decisions harder to reason about.
+
+NetKingdom already owns identity and security architecture concerns.
+key-cape provides a lightweight IAM implementation of the NetKingdom IAM
+Profile. Keycloak remains the expanded production IAM option. privacyIDEA
+is relevant for MFA/token lifecycle. flex-auth is emerging as the
+canonical authorization control plane and practical reference
+implementation of CARING authorization semantics. Topaz is the most
+likely first delegated authorization runtime behind flex-auth.
+
+## Decision
+
+We will document and implement the platform security architecture as a
+recursive multi-tenant architecture with three explicit planes:
+
+- **Bootstrap plane** - establishes the first trusted runtime and recovery
+  authority before normal platform services exist.
+- **Platform control plane** - operates shared identity, MFA, secrets,
+  authorization, policy, audit, and explanation services.
+- **Tenant plane** - runs Coulomb and future workloads under scoped tenant
+  authority.
+
+Coulomb will be treated as the first internal/reference tenant, not as the
+platform root of trust.
+
+NetKingdom will own the canonical security architecture and standards.
+Railiance will own deployment layering and orchestration boundaries.
+flex-auth will own the canonical authorization interface and CARING-based
+policy/decision model. Topaz will be the first delegated PDP runtime,
+with other authorization engines treated as adapters where useful.
+
+## Consequences
+
+- Architecture documentation must separate platform-root authority from
+  tenant administration, even for Coulomb.
+- Workplans for identity, authorization, and bootstrapping must include
+  explicit tenant and control-plane boundaries.
+- Bootstrap design must include trust-state transitions and recovery
+  procedures rather than assuming the final IAM service already exists.
+- flex-auth should model tenants, platform resources, CARING descriptors,
+  decision envelopes, and runtime adapters in a provider-neutral way.
+- key-cape and Keycloak should be treated as implementations of the IAM
+  Profile, not as the canonical source of resource authorization
+  semantics.
+- A future orchestration repo may be useful, but only to coordinate safe
+  sequencing across Railiance and NetKingdom capabilities. It must not
+  bypass Railiance stack ownership.
+
+## Alternatives Considered
+
+### Treat Coulomb As The Platform Root
+
+This is simpler during early development but creates long-term coupling
+between one internal use case and the shared platform. It makes later
+multi-tenant operation and secure bootstrap harder.
+
+### Put All Security Semantics Into Keycloak
+
+Keycloak is useful for expanded IAM and can provide authorization
+features, but making it the canonical model would make lightweight mode
+and future authorization backends harder to support. The preferred model
+keeps identity provider concerns separate from canonical authorization
+semantics.
+
+### Create An Orchestration Repo Immediately
+
+A dedicated orchestration repo may become appropriate. Creating it before
+we define trust states and repo boundaries would risk encoding accidental
+sequence logic too early. The immediate step is to document the state
+machine and update workplans.
+
+## Follow-Up
+
+- Refine bootstrapping around explicit trust-state transitions.
+- Add tenant/control-plane language to flex-auth authorization workplans.
+- Define the first production Topaz integration boundary for flex-auth.
+- Decide when key-cape is sufficient and when Keycloak expanded mode is
+  required.
+- Decide what, if anything, should live in a future orchestration repo.