---
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.