net-kingdom/workplans/archived/260702-NK-WP-0006-recursive-platform-identity-security-architecture.md

---
id: NK-WP-0006
type: workplan
title: Recursive platform identity and security architecture
domain: infotech
repo: net-kingdom
status: finished
owner: Bernd Worsch
topic_slug: netkingdom
created: 2026-05-17
updated: 2026-05-18
depends_on:
  - NK-WP-0001
  - NK-WP-0004
  - NK-WP-0005
state_hub_workstream_id: "2eb8a5e0-4e33-4ed3-8996-a2eec3aad862"
---

> **Terminology note:** Historical text in this archived workplan may use the legacy term "workstream". The fleet term is **workplan** (`canon/standards/workplan-terminology-fleet_v0.1.md`).

# 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,
OpenBao runtime secret authority, 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, OpenBao, 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
- deploying OpenBao itself
- designing customer-specific tenant policy
- replacing existing Railiance layer ownership

## Tasks

```task
id: NK-WP-0006-T1
status: done
priority: high
state_hub_task_id: "3e1c432a-f1ef-4c96-bb7a-79d1b955cd82"
```
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
state_hub_task_id: "194fe3d5-d47c-449e-a32d-50996fd39e66"
```
Record the architecture decision in an ADR so later repo work can point
to a stable decision.

```task
id: NK-WP-0006-T3
status: done
priority: high
state_hub_task_id: "842ba5a7-5199-490a-8af5-3150388e0d42"
```
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: done
priority: high
state_hub_task_id: "ce153339-f493-44ed-a2c5-befb578334fe"
```
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: done
priority: medium
state_hub_task_id: "6c9a3561-4e63-4acd-87a7-bf0f374fa6b2"
```
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: done
priority: medium
state_hub_task_id: "27760e30-f773-4552-97f4-7fbe56507f9e"
```
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: done
priority: medium
state_hub_task_id: "f09519ac-cf97-4f8b-8a7b-6ff828bbd8d9"
```
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.

## Implementation Review - 2026-05-18

The recursive architecture remains the right framing. The refinement from
the current stack is that OpenBao is now part of the platform control
plane as the runtime secret authority. SOPS/age and emergency bundles
remain bootstrap and recovery mechanisms; they must not become the
long-lived runtime authority for every workload secret once OpenBao is
available.

Implemented refinements:

- `docs/platform-identity-security-architecture.md` now includes explicit
  flex-auth/Topaz implications, Coulomb tenant onboarding, production
  readiness checks, and OpenBao secret authority boundaries.
- `docs/adr/ADR-0007-security-orchestration-boundary.md` records that
  orchestration stays in Railiance playbooks for now; a dedicated repo is
  deferred until sequencing has a stable, cross-repo product surface.
- `workplans/NK-WP-0007-object-storage-sts-credential-vending.md` now
  treats OpenBao as the runtime broker/audit option without letting it
  replace flex-auth authorization or storage-native STS semantics.
- `workplans/NK-WP-0004-credential-management-foundation.md`,
  `workplans/NK-WP-0005-agent-driven-credential-bootstrap.md`, and
  `canon/standards/credential-management_v0.2.md` now distinguish
  bootstrap credential handling from the OpenBao runtime-secret handoff.

State Hub task statuses should be synchronized to match this workplan.

## 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, OpenBao, 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.