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