Document recursive platform security architecture

workplans/NK-WP-0006-recursive-platform-identity-security-architecture.md

@@ -0,0 +1,137 @@
+---
+id: NK-WP-0006
+type: workplan
+title: Recursive platform identity and security architecture
+domain: identity-security
+repo: net-kingdom
+status: proposed
+owner: Bernd Worsch
+topic_slug: recursive-platform-identity-security
+created: 2026-05-17
+updated: 2026-05-17
+depends_on:
+  - NK-WP-0001
+  - NK-WP-0004
+  - NK-WP-0005
+---
+
+# NK-WP-0006 - Recursive Platform Identity and Security Architecture
+
+## Goal
+
+Make the platform identity and security architecture explicit enough that
+Coulomb can be onboarded as the first internal/reference tenant without
+accidentally becoming the platform root of trust.
+
+The workplan turns the recursive insight into operational structure:
+bootstrap plane, platform control plane, tenant plane, IAM Profile,
+flex-auth authorization, Topaz runtime, privacyIDEA MFA/token handling,
+and safe orchestration boundaries.
+
+## Context
+
+The current platform work is both building the Coulomb infrastructure and
+creating reusable infrastructure for later use cases. That means Coulomb
+is tenant zero/reference tenant inside its own future platform. This is a
+useful design pressure, but only if the tenant/control-plane separation
+is made explicit.
+
+NetKingdom owns the canonical identity and security architecture.
+Railiance owns deployment layering. flex-auth provides the practical
+reference implementation for CARING authorization semantics. key-cape and
+Keycloak implement identity profiles in different operating modes.
+
+## Scope
+
+In scope:
+
+- document the three-plane architecture
+- define platform-root versus tenant authority
+- define how NetKingdom, key-cape, Keycloak, privacyIDEA, flex-auth,
+  Topaz, and Railiance relate
+- define bootstrap-to-runtime trust states
+- update related workplans and ADRs when implementation details become
+  concrete
+- identify whether a dedicated orchestration repo is justified
+
+Out of scope:
+
+- implementing flex-auth adapters
+- deploying Keycloak, key-cape, privacyIDEA, Topaz, or Railiance services
+- designing customer-specific tenant policy
+- replacing existing Railiance layer ownership
+
+## Tasks
+
+```task
+id: NK-WP-0006-T1
+status: done
+priority: high
+```
+Document the recursive multi-tenant identity/security architecture in
+`docs/platform-identity-security-architecture.md`.
+
+```task
+id: NK-WP-0006-T2
+status: done
+priority: high
+```
+Record the architecture decision in an ADR so later repo work can point
+to a stable decision.
+
+```task
+id: NK-WP-0006-T3
+status: pending
+priority: high
+```
+Review flex-auth workplans and add tenant/control-plane implications:
+CARING descriptors, policy packages, decision envelopes, Topaz adapter
+scope, audit/explain records, and platform-root guardrails.
+
+```task
+id: NK-WP-0006-T4
+status: pending
+priority: high
+```
+Review NetKingdom credential/bootstrap workplans and add explicit trust
+state transitions: bare host, cluster, secrets, bootstrap identity,
+runtime identity, runtime authorization, tenant onboarding.
+
+```task
+id: NK-WP-0006-T5
+status: pending
+priority: medium
+```
+Map the first Coulomb tenant onboarding path: identity claims, tenant id,
+resource registration, policy package import, Topaz initialization, and
+audit readiness.
+
+```task
+id: NK-WP-0006-T6
+status: pending
+priority: medium
+```
+Decide whether orchestration should stay as Railiance playbooks or become
+a dedicated repo. Capture the decision as an ADR before implementation.
+
+```task
+id: NK-WP-0006-T7
+status: pending
+priority: medium
+```
+Define production readiness checks for the security platform: MFA state,
+secret rotation state, flex-auth policy state, Topaz health, audit sink,
+and break-glass verification.
+
+## Acceptance Criteria
+
+- Architecture docs distinguish bootstrap plane, platform control plane,
+  and tenant plane.
+- Coulomb is represented as tenant zero/reference tenant, not platform
+  root.
+- The role of NetKingdom, key-cape, Keycloak, privacyIDEA, flex-auth,
+  Topaz, and Railiance is clear.
+- Follow-up workplans identify where flex-auth and bootstrap work need to
+  adapt.
+- Any future orchestration repo is justified by an ADR before it is
+  created.