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.

## Where The King Credential Lives

The king credential is an identity and custody record, not an OpenBao password.
In the current lightweight NetKingdom stack, the practical placement is:

| Part | Current home | Notes |
| --- | --- | --- |
| User record | LLDAP | dedicated `platform-root` or `king` user, separate from `tegwick` |
| Password login | Authelia over LLDAP | day-to-day email is notification-only |
| TOTP / token enrollment | privacyIDEA | QR/setup key comes from privacyIDEA self-service |
| privacyIDEA administration | `pi-admin` | setup and repair account, not the king credential |
| IAM Profile / OIDC token | KeyCape | target issuer for normal platform identity claims |
| Secret custody and audit | OpenBao | initialized after custody approval; not the human identity provider |

OpenBao enters the story after custody approval: it holds platform secrets,
unseal/recovery material handling, audit, policies, and temporary or future
admin auth methods. It should not be used as the place where the human king
password or OTP seed lives.

LLDAP deliberately has no public registration flow. The first-user process is
administrator-provisioned:

1. Log in to `https://lldap.coulomb.social` as `admin`.
2. Retrieve `LLDAP_LDAP_USER_PASS` from operator custody —
   `operators/lldap/admin` in OpenBao (see *Operator Credential Custody*).
   Until 2026-08-28 this step named a password-safe entry that did not exist;
   see that section for what that cost.
3. Create the dedicated `platform-root` or `king` user.
4. Add the user to `net-kingdom-admins` for the current lightweight path.
5. Store the new account password in operator custody (`operators/`) or, for a
   bootstrap identity, in the offline packet — never only in a browser
   password manager.
6. Use `pi-admin` in privacyIDEA to confirm that the LLDAP resolver can see
   the new user and that self-enrollment is allowed.
7. Log in to privacyIDEA self-service as `platform-root` and enroll the TOTP
   token there. The QR/setup key belongs only in the authenticator and custody
   storage, never in this repo, State Hub, chat, or the local control surface.
8. Verify the OIDC login path through a registered KeyCape client. KeyCape is
   an issuer, not a dashboard; the root URL may return `404` while discovery,
   health, authorize, token, and userinfo endpoints are healthy.

The local control surface records this as non-secret progress: account
reference, group assignment confirmation, password-safe confirmation, and later
login-path verification. It does not read or store the password, OTP seed, QR
code, or recovery codes.

Do not use a successful `platform-admin` login as proof of `platform-root`
custody unless the recorded king credential was intentionally changed to
`platform-admin`. `platform-admin` is the later non-root operator path; it is
useful, but it is not the same as proving the platform-root custody identity.

## Operator Credential Custody

*Decided 2026-08-28, after `NK-WP-0033`.*

Every credential a human operator holds has exactly one recorded home. Before
this was written, this document named a password-safe entry
(`net-kingdom/LLDAP/admin`) that had never been created. The consequence was not
theoretical: the LLDAP admin credential was rotated on 2026-08-23 with nowhere
to put the new value, the outgoing value survived only in a browser password
manager, and it was destroyed on 2026-08-27 when that entry was overwritten with
the replacement. A full working session went into diagnosing a system whose
predecessor credential no longer existed anywhere.

### Two stores, and the line between them

**`operators/` in OpenBao — everything reachable once you are logged in.**
Service account passwords, provider PATs, the LLDAP admin bind, privacyIDEA
`pi-admin`, machine identities like `state-hub-svc`. Auditable, backed up with
the rest of the platform, reachable from any machine, and writable through
`warden desk --act paste_once_provision` so the value never reaches a terminal
or shell history.

Path convention: `operators/<subsystem>/<account>` — for example
`operators/lldap/admin`, `operators/privacyidea/pi-admin`,
`operators/forgejo/state-hub-svc`. Distinct from `platform/workloads/…`, which
holds credentials that *workloads* consume; `operators/` holds credentials that
*people* use.

**The offline packet — what you need when OpenBao is unreachable.** This list is
deliberately short, closed, and enumerated here rather than left to judgement:

- `platform-root`'s own password and TOTP recovery codes
- OpenBao unseal shares and root token
- the `break-glass` account password (`sso-mfa/k8s/lldap/break-glass.sh`)

Anything on that list in `operators/` would be a circular dependency: you would
need the store to reach the credential that opens the store. Anything *not* on
that list belongs in `operators/`, not in the packet — the packet is not a
general-purpose safe and does not scale.

### The rule that closes the gap

**Every rotation procedure must name, as a numbered step, where the outgoing and
incoming values go.** A rotation that changes a credential without saying what
happens to custody will lose one of the two, and which one it loses is a matter
of luck. `NK-WP-0033-T04` rotated four credential classes and had no such step;
that is the root cause of the session that followed, not any of the four
software defects it also surfaced.

The outgoing value is retained until its successor is verified *and* the
predecessor is proven rejected. Only then is it destroyed, and its destruction
is recorded.

### Every credential says what it is

A store of unlabelled values is the drawer of unmarked keys it was supposed to
replace. Every path — in `operators/` and in `platform/workloads/` alike —
carries five `custom_metadata` fields. They are not secret, so anyone orienting
themselves can read all of them without being granted a single value.

| Field | Answers |
| --- | --- |
| `description` | what this credential *is*, in a sentence, including what it is **not** — the distinction between an account's password and the token it issues has already cost a session |
| `owner` | which repo or subsystem decides about it |
| `used_by` | what breaks when it changes. Rotation without this list is how a resolver gets left holding a superseded value for four days |
| `rotation` | the procedure, by document path — not a description of one |
| `on_loss` | what you do when the value is gone: is it resettable, by whom, and what does the reset cost |

`on_loss` is the field this whole section exists for. On 2026-08-27 the LLDAP
admin predecessor was destroyed and the answer had to be reconstructed from
first principles under pressure. Written down in advance it is one line.

Read the inventory with `ops-mason/scripts/custody-inventory.py`, which walks
both mounts, prints these fields, and marks any path missing them. It reads
metadata only and runs under `ops-mason-build`, so it is safe to hand to anyone.

**As of 2026-08-28 that inventory reports 21 paths, 17 of them undescribed.**
The four that are described are the ones this session touched. The backlog is
real and is not urgent in the way a broken login is urgent — but each of those
seventeen is a credential nobody can identify without reading it.

### Not yet built

The `operators/` mount and its policy do not exist yet. Until they do, this
section describes intent rather than practice, and the same failure remains
available. Building it is a `railiance-platform` act, not an ops-mason one.

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

### Secret disclosure by stage

*Decided 2026-08-27, during `NK-WP-0033`.* Diagnosis stalls when two people
cannot establish whether they are discussing the same credential. What follows
is what may be said aloud — in a terminal, a transcript, a chat message, or a
ticket — about a secret's *value*, by stage.

| Stage | Permitted about a value |
| --- | --- |
| S0–S4 | A fingerprint: last three characters, optionally with length. Enough to confirm two parties hold the same credential and no more. |
| S5+ | Same, but only where the value is already in an automated pipeline may a hash (`sha256 \| head -c 8`) be used instead; a human comparing by eye still uses the last three. |
| Any | Never the whole value, never a working prefix, never a screenshot of one. |

**Last three characters, not a hash — decided deliberately.** A hash looks like
the stricter choice and is the worse one in practice. Browsers and secret stores
have a reveal button; none of them can show you a digest. To compare hashes you
must first extract the plaintext into a shell, where it lands in history, in a
process listing, or in a temporary file — so the "safer" convention forces a
plaintext handling step that reading three characters off a screen avoids
entirely. The rule exists to reduce exposure, and the hash form increases it.

Hashes remain the right form where the value is already flowing through a
pipeline — verifying a KV write from a script, comparing two stores
programmatically — because there the plaintext is in memory regardless and no
new handling step is created.

This is a disclosure rule, not a handling rule. It says what may be *spoken*
about a value; it does not license reading a value out of a store that a role is
not otherwise entitled to read.

## 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. Choose whether this is temporary single-custodian king custody or preferred
   independent escrow.
5. Prepare offline recovery bundle locations for that strategy.
6. Prepare the OpenBao custody packet for that strategy, including share
   assignment rows, quorum plan, root-token disposition, and signoff line.
7. Approve the selected custody strategy in the NetKingdom control surface.
8. 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.