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

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
Identity account home	lldap
Identity account reference	platform-root@lldap
Identity account created	true only after the dedicated account exists
Identity group reference	net-kingdom-admins
Identity group confirmed	true only after the account is assigned to the group
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
Password safe confirmed	true only after the credential is stored outside this UI
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.

1a. Create The Identity Account

In the current lightweight stack, create the dedicated account in LLDAP and record only a non-secret reference such as platform-root@lldap. The password belongs in the operator password safe or offline custody packet, not in the bootstrap metadata.

For the first lightweight path, assign the account to net-kingdom-admins. This is a non-secret membership fact and may be recorded as confirmed.

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.

In the current NetKingdom lightweight stack, pi-admin is the privacyIDEA administrator for checking the LLDAP resolver, realm, and self-enrollment policy. It is not the king credential. The preferred flow is to log in to the privacyIDEA self-service portal as platform-root and enroll the token there. If the self-service flow is not working yet, pi-admin may assign a token as an admin-assisted fallback, but the seed and recovery values still remain out of the bootstrap metadata.

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;
• the dedicated identity account exists;
• the required admin group assignment is confirmed;
• storage choice is recorded;
• the password is confirmed stored outside this UI;
• 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.