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.