net-kingdom/docs/platform-root-custody.md

# Platform Root Custody

Status: active bootstrap policy
Date: 2026-05-24

## Purpose

This document defines the bootstrap trust model for NetKingdom platform-root
authority and the Railiance OpenBao bootstrap. It deliberately stores only
identity, policy, and procedure. It must never contain passwords, OpenBao
unseal keys, root tokens, recovery keys, one-time codes, private keys, or
screenshots of secret output.

The design goal is practical security: early infrastructure can be assembled
by a low-trust setup operator, then handed over to a dedicated king credential
when the control plane is ready. After handover, bootstrap-era material is
rotated, reset, or retired before live workloads depend on it.

## Bootstrap Roles

| Role | Purpose | Initial assignment |
| --- | --- | --- |
| Setup operator | Runs early MVP/prototype setup, receives notifications, operates Git/Gitea and day-to-day tooling | `tegwick` / `bernd.worsch@gmail.com` / Gitea `tegwick` |
| King credential | Dedicated platform-root break-glass and final custody credential, independent from day-to-day accounts | To be created before OpenBao live bootstrap |
| Future escrow holders | Later independent recovery control, preferably two-of-three custody | To be named after the first safe bootstrap path exists |

`tegwick` is the initial accountable setup operator and contact. That identity
is useful for notifications, work tracking, Git access, and early operations,
but it is not the desired long-term platform root of trust.

The king credential must be independent from ordinary Gitea and email access.
Email may receive notifications, but secrets, reset links, root tokens, unseal
shares, private keys, OTP seeds, and recovery codes must not travel through
email.

## King Credential

The king credential is the rare platform-root credential used to accept final
custody after the bootstrap substrate exists. It should be represented as a
dedicated identity such as `platform-root` or `king`, not as a personal
day-to-day account.

Minimum first version:

- stored in an offline or local password safe controlled by the human operator;
- protected by a separate strong passphrase;
- protected by an OTP factor or hardware-backed factor where the selected IAM
  implementation supports it; the QR code or setup key must come from that
  verifier, not from the local metadata console;
- not used for normal Git, browsing, chat, or daily administration;
- not recoverable through the day-to-day email account alone; and
- documented only by non-secret metadata in Git/State Hub.

Preferred later version:

- two-of-three independent custody or equivalent multisig-style approval;
- at least one independent human or institutional escrow holder;
- documented rotation and recovery drills; and
- break-glass use logged for review without exposing secret values.

## Custody Meaning

For this bootstrap, "master credential" means the offline recovery authority
needed to recover or administer the platform before normal identity,
authorization, and secret systems are fully online. It includes OpenBao
unseal/recovery material and, only if retained, the initial OpenBao root token.

The root token is not the normal admin credential. It is one-time bootstrap or
break-glass material. The preferred end state is:

- OpenBao is initialized and unsealed.
- Audit devices, mounts, auth methods, and policies are configured.
- A non-root `platform-admin` operator path exists.
- The initial root token is revoked, or is stored offline as sealed
  break-glass material under the king credential custody policy.
- Routine access flows through NetKingdom IAM claims and scoped OpenBao
  policies.

## Trust Progression

The platform moves through explicit trust stages:

| Stage | Name | Meaning |
| --- | --- | --- |
| S0 | MVP/prototype | Day-to-day accounts and local operator access may have created state. Nothing here is assumed clean enough for live custody. |
| S1 | Low-trust assembly | Setup operator can deploy infrastructure, but does not become platform root. No live secrets are stored. |
| S2 | King credential creation | Dedicated king credential, second factor, and offline recovery storage are created through guided UX. |
| S3 | OpenBao bootstrap | OpenBao is initialized, configured, and moved to non-root admin paths. |
| S4 | Cleanup and hardening | Bootstrap passwords, database credentials, tokens, and access paths are reset or rotated; hosts and workloads are scanned and reviewed. |
| S5 | Reopen under custody | The platform becomes usable under king credential oversight, with day-to-day admins delegated scoped access. |
| S6 | Multi-custodian upgrade | Custody moves to two-of-three or equivalent independent recovery control. |

This prevents early bootstrap convenience from silently becoming permanent
platform sovereignty.

## Required Bootstrap Use Cases

The guided bootstrap experience must cover at least:

- create or import the king credential;
- verify king credential second factor and recovery storage;
- initialize OpenBao without exposing secret output to unsafe channels;
- onboard a new user;
- temporarily lock a user;
- permanently lock and offboard a user;
- review and rotate user credentials;
- create a new fabric with its own admin;
- transfer a fabric to a new admin;
- perform break-glass access;
- rotate or rekey platform-root material;
- add later two-of-three custody; and
- run cleanup checks before reopening the platform for live use.

## Target IAM Claims

When key-cape or Keycloak provisions the first king/admin identity, it should
receive a platform-root identity envelope similar to:

| Claim or group | Value |
| --- | --- |
| `sub` | stable subject for `platform-root` or the selected king identity |
| `email` | notification address only; no secret transfer |
| `tenant` | `platform` |
| `principal_type` | `human` or `break_glass` depending on IAM support |
| `groups` | `platform-root`, `platform-admin`, `netkingdom-admin`, `railiance-platform-admin` |
| `roles` | `platform-root-custodian`, `openbao-admin`, `identity-admin` |
| `assurance` | MFA-backed for privileged actions |

The setup operator `tegwick` can receive scoped admin roles for day-to-day
operations later, but those roles must be delegated from the king custody model
and must be revocable without losing recovery authority.

Tenant administration must remain separate from platform-root claims. Being an
admin for `tenant:coulomb` or another tenant must not imply OpenBao root,
NetKingdom identity-admin, flex-auth platform-policy, or Railiance
platform-service authority.

## OpenBao Bootstrap Sequence

The Railiance OpenBao runbook owns the live commands. NetKingdom owns the
identity and custody semantics.

Before OpenBao initialization:

1. Use the guided bootstrap UX or checklist to decide the current trust stage.
2. Record `tegwick` as setup operator/contact, not as final root custodian.
3. Create or import the dedicated king credential and verify its second factor.
4. Prepare offline recovery bundle locations.
5. Choose whether this is temporary single-custodian king custody or preferred
   independent escrow.
6. Run Railiance `make openbao-status` and `make openbao-verify`.

During initialization:

1. Run the OpenBao init command only in the approved maintenance window.
2. Route each unseal share directly to the king credential custody bundle or
   approved escrow holder.
3. Use the initial root token only for audit, mounts, auth methods, policies,
   and creating the non-root admin path.
4. Do not persist secret output in shell history, Git, State Hub, chat, email,
   tickets, screenshots, or issue trackers.

After initialization:

1. Create and store a non-root `platform-admin` operator credential.
2. Revoke the initial root token, or seal it offline as break-glass material
   under king custody.
3. Reset or rotate bootstrap-era database credentials, admin passwords,
   service tokens, and access paths before live use.
4. Run host/workload checks, vulnerability scans where available, and the
   OpenBao snapshot plus isolated restore drill.
5. Log non-secret progress with the custody posture and verification outcome.

## Completion Gates

The platform-root custody path is ready for live secrets only when:

- `tegwick` is recorded as setup operator/contact, not root of trust;
- the dedicated king credential exists and is second-factor protected;
- OpenBao init/unseal ceremony is complete;
- routine admin access no longer depends on the initial root token;
- root token disposition is recorded without storing the token value;
- bootstrap-era credentials and databases have been reset or rotated as needed;
- backup, audit, restore, and scan evidence exists;
- NetKingdom IAM claims are ready to become the normal human admin path; and
- two-of-three custody remains an explicit, low-friction upgrade path.