openbao king credential bootstrapping

docs/security-bootstrap-king-credential-kit.md

@@ -0,0 +1,168 @@
+# King Credential Kit
+
+Status: draft UX contract
+Date: 2026-05-24
+
+## Purpose
+
+This document defines the non-secret output for the king credential kit. It is
+the product contract for `NET-WP-0016-T03`.
+
+The king credential is a dedicated platform-root credential. It is separate
+from day-to-day Gitea, email, chat, and setup-operator accounts.
+
+## Kit Outputs
+
+The bootstrap console may generate or print these non-secret artifacts:
+
+| Artifact | Secret-free content |
+| --- | --- |
+| Credential checklist | Steps to create or import the credential |
+| Custody packet template | Blank fields for offline writing, not filled by software |
+| OTP setup checklist | Verifies factor was enrolled with its real verifier without recording seed |
+| Recovery checklist | Verifies recovery material exists without recording values |
+| Storage checklist | Confirms password safe/offline storage choice |
+| Metadata record | Label, date, operator, custody posture, review date |
+| Handover receipt | Non-secret statement that custody was accepted |
+
+## V1 Recommended Kit
+
+The first practical kit is intentionally simple. It is good enough for
+pre-production bootstrap, but it does not pretend to be the final
+multi-custodian posture.
+
+| Field | V1 value |
+| --- | --- |
+| Credential label | `platform-root` |
+| Setup operator/contact | `tegwick` |
+| Notification contact | `bernd.worsch@gmail.com` |
+| Primary storage | local password safe |
+| Offline recovery | printed or handwritten custody packet |
+| First second factor | TOTP or WebAuthn/hardware token |
+| Email role | notifications only, no secret transfer |
+| Day-to-day use | forbidden |
+| OpenBao init | still blocked until custody mode is approved |
+
+This kit defines the credential shape. It does not by itself approve the
+custody mode or authorize live OpenBao initialization.
+
+## Required Metadata
+
+The UI may record:
+
+| Field | Example |
+| --- | --- |
+| Credential label | `platform-root` |
+| Custody posture | `temporary-single-king` or `two-of-three-planned` |
+| Notification contact | `bernd.worsch@gmail.com` |
+| Setup operator | `tegwick` |
+| Created date | `2026-05-24` |
+| Review date | date for next custody review |
+| Storage class | `password-safe`, `offline-paper`, `hardware-token`, or similar |
+| MFA class | `totp`, `webauthn`, `hardware-token`, or similar |
+| MFA enrolled confirmed | `true` only after the factor is enrolled with its verifier |
+| MFA enrollment source | non-secret source label such as `identity-provider` or `hardware-registration` |
+| Recovery confirmed | `true` only after offline recovery material exists |
+| Custody packet prepared | `true` only after a blank packet is prepared offline |
+| No secret capture confirmed | `true` only after the operator confirms no secret values were entered into software |
+
+It must not record:
+
+- passwords;
+- OTP seeds;
+- recovery codes;
+- private keys;
+- OpenBao unseal shares;
+- OpenBao root tokens;
+- screenshots of secret output; or
+- reset links.
+
+## Guided Steps
+
+### 1. Name The Credential
+
+Suggested label: `platform-root`.
+
+The UI should explain that this is not a normal user and not a day-to-day admin
+account. It is rare root custody.
+
+### 2. Choose Storage
+
+Allowed first-version choices:
+
+| Choice | Meaning |
+| --- | --- |
+| Password safe | Stored in a local password manager controlled by the operator |
+| Offline packet | Written into an offline custody packet |
+| Hardware-backed | Protected by a hardware token or equivalent |
+
+The UI should permit a combination. It should not ask for secret values.
+
+### 3. Add A Second Factor
+
+Allowed first-version choices:
+
+| Choice | Meaning |
+| --- | --- |
+| TOTP | App-based one-time password |
+| WebAuthn | Hardware or platform authenticator |
+| Deferred | Only allowed before live OpenBao custody |
+
+`Deferred` blocks live OpenBao init.
+
+For TOTP, the QR code or setup key must come from the authority that will
+verify login, such as the selected identity provider. A local bootstrap console
+must not generate an orphan OTP seed because it would not authenticate
+anything. The console records only that enrollment completed and where,
+without storing the seed, QR code, recovery codes, or screenshots.
+
+### 4. Prepare Recovery
+
+The operator confirms that recovery codes or equivalent recovery material exist
+and are stored offline. The UI records only `confirmed` or `not confirmed`.
+
+### 5. Select Custody Mode
+
+First-version choices:
+
+| Mode | Meaning |
+| --- | --- |
+| `temporary-single-king` | One king custodian for pre-production only |
+| `two-of-three-planned` | Independent custody is planned but not ready |
+| `two-of-three-ready` | Independent custody holders are ready now |
+
+Only `temporary-single-king` and `two-of-three-ready` can unblock OpenBao init,
+and both still require human ceremony.
+
+### 6. Print Custody Packet
+
+The custody packet is a blank template for offline use. It should include:
+
+- credential label;
+- date;
+- custody mode;
+- storage location description;
+- second-factor location description;
+- recovery material location description;
+- OpenBao share assignment rows;
+- root-token disposition row; and
+- signature/date line.
+
+The software must not fill secret fields.
+
+## Completion Criteria
+
+The king credential kit is complete when:
+
+- the credential label exists;
+- storage choice is recorded;
+- second factor is enrolled with its real verifier and confirmed;
+- recovery material is confirmed;
+- custody mode is selected;
+- offline custody packet is printed or acknowledged; and
+- no secret value has been captured.
+
+For `NET-WP-0015-T02`, the kit can be considered defined when all fields except
+the final custody-mode approval have a concrete, non-secret value. `NET-WP-0015`
+keeps custody mode approval as T03 because that decision gates live OpenBao
+initialization.