runbook-tutorials/docs/console-mapping.md

Is v0.2 expressive enough? Mapping the security bootstrap console

Status: analysis, 2026-09-29 (RBT-WP-0009-T05; closes RBT-WP-0005-T03).

The plan for adopting runbook-pack/v0.2 said: use the NetKingdom security bootstrap console (net-kingdom/tools/security-bootstrap-console/, 5,300 lines, invented in NET-WP-0016) as the first real test. If the model can express its stages, gates and runbooks without special cases, it is expressive enough. This is that test, done from the console's own definitions (read from its running /api/status and its source, against a throwaway metadata file).

Verdict

The structure maps; the behaviour does not fully. v0.2 expresses the console's stages, gates, actors, dimensions, artefacts, evidence validators, typed approval and alternatives. It does not yet express five behaviours the console relies on: conditional applicability, re-evaluation of gates that can regress, outputs of one member feeding the next, local-only attributes, and gates satisfied by an automation path. So v0.2 is adequate for procedures (every runbook in the console, and the three NetKingdom packs) and not yet proven adequate for a long-lived staged bootstrap as a whole. Decision: the console stays a permanent legacy pack (RBT-WP-0005-T05); extracting its engine parts (T04) is moved to the backlog until the gaps below are closed.

What the console contains

Element	Count	Notes
Stages	6	S1 Low-trust assembly, S2 King credential preparation, S3 OpenBao bootstrap, S4 Admin identity integration, S5 Cleanup and hardening, S6 Reopen under custody
Top-level gates	14	statuses done, blocked, human, automation
Sub-checklists	11 + 4 + 4	king-credential kit items, key-custody items, admin-identity integrations
Section statuses	9	view-level completeness of the UI's own sections, not gates
Roles	6	setup-operator, platform-root-custodian, identity-admin, openbao-ceremony-operator, recovery-custodian, future-quorum-custodian; each with a designated contact
Subsystems, integrations	6 + 6	LLDAP, privacyIDEA, KeyCape, OpenBao, custodian age envelope, bootstrap bundle
Runbooks	7	all template state; 23 copyable command blocks in total
Artefacts	12	references only (a password-safe entry, an age key location, unseal shares held elsewhere); states nil, set, ok
Approval	1	typed phrase approve custody mode, two approvable modes

How the console works, which decides the mapping

1. A persistent fact document (.local/security-bootstrap.json, flat keys such as openbao_initialized). It lives for weeks.
2. The stage is derived from the facts (derive_stage: the most advanced fact wins), not from stepping through a list.
3. Gates are computed on every view, from the facts and from live probes (files present, a Secret deployed in the cluster). A gate can go back from done to blocked when the system changes.
4. Gate status is a small vocabulary: done; blocked (a precondition is missing); human (ready, waiting for a person); automation (satisfied by an unattended path, for example the SOPS-held init).
5. Applicability depends on choices: the unseal custody model (sops-held, attended ceremony, auto-unseal) changes which init gate applies, and the production profile forbids one of them.

The 14 gates

#	Gate	Stage (proposed)	v0.2 form	Verdict
1	King credential kit	S2	gate datapoints_ok over the 11 kit items (datapoints, confirmed by steps)	direct
2	Custody strategy approval	S2	irreversible step with confirm_phrase: approve custody mode; gate on the custody_mode datapoint	caveat G4: only some modes may approve live init; needs a value predicate, or an enum limited to the approvable modes
3	OpenBao preflight	S3	gate check command, exit 0 (make ... openbao-status)	direct
4	OpenBao unseal custody model	S3	enum datapoint custody_model; the production profile blocks one value	caveat G4 (cross-datapoint rule) and G1
5	OpenBao init ceremony	S3	step with alternatives (attended ceremony / automated init), recommended by custody_model	alternatives fit, but the automated path is executed by a script: needs execution (G6), and refusing live init under some profiles is G1
6	OpenBao initial configuration	S3	step, then gate on an evidence datapoint	direct
7	KeyCape OpenBao client definition	S4	gate check command probing the source	direct; G3 (recheck)
8	KeyCape OpenBao client deployed	S4	gate check command probing the live Secret	direct; G3
9	OpenBao OIDC auth	S4	step plus evidence datapoint	direct
10	OIDC admin login	S4	manual check (a browser login through KeyCape and MFA), plus a claims check by command	direct
11	Root-token disposition	S5	enum datapoint limited to revoked and offline-sealed; gate datapoints_ok	direct
12	Restore drill	S5	a separate pack (7 command blocks, evidence validator); gate check runs the validator	caveat: needs a dependency between runbooks (requires_packs, RBT-WP-0006-T04), or the drill inlined
13	Cleanup and rotation	S5	gate with several manual checks	direct
14	Platform reopen	S6	gate check by the custodian actor, with an irreversible confirmation	direct

Ten map directly, three with a caveat, one needs execution. The console does not tie gates to stages explicitly; v0.2 does, which is the improvement asked for in the UX review (each gate belongs to one stage and names its quality goal). The sub-checklists map to datapoints and steps in the stage they belong to.

The rest of the model

Console	v0.2	Fit
Stages S1 to S6	stages, completion derived from members	good; order by requires
Roles with designated contacts	actors, plus a datapoint per contact carrying the actor dimension	good; see G5 for the contacts
Subsystems	the subsystem dimension on datapoints	good; the data view already groups by it
Artefacts (nil, set, ok)	artefacts with a location datapoint	good; artefact state is derived from the location datapoint
The 7 runbooks	7 native packs	good and independent of the gaps: each is a linear procedure with commands
The 23 command blocks	step commands; the interactive read -rs prompts stay operator-run	good; nothing secret is ever entered into the engine
Typed approval phrase	confirm_phrase on an irreversible step	good
Evidence validators (validate-*)	gate or step checks by command, exit 0	good
Copyable command blocks, next action	the guided flow	the new UI does both

The gaps

These are candidates for a v0.3. None blocks closing the runbook-tutorials workplans, and none affects the procedures that exist today.

• G1 Conditional applicability. Stages, steps and gates that apply only for some choices (applies_when on a datapoint value). one_of chooses between alternatives inside a step; it cannot switch a whole gate on or off.
• G2 A longer horizon. A run untouched for seven days counts as abandoned. A multi-week ceremony needs a per-pack (or per-run) horizon.
• G3 Re-evaluating a gate. A passed gate is final in a run. The console's gates regress when the system changes. A gate needs a recheck, and a passed gate that fails a recheck needs a state of its own.
• G4 Value predicates. datapoints_ok only asks that a datapoint is ok. The console needs "this datapoint is one of these values" and rules across two datapoints (production excludes sops-held-automation).
• G5 Local-only attributes. The console keeps role contacts (email addresses) in an ignored .local file. Attribute sets and project files are meant to be committed, so personal data would land in git. An attribute needs a local visibility that is never written into a repository file.
• G6 Gates satisfied by an automation path. The console's automation status means an unattended script did the work. Auto-confirm only confirms; running the script is the opt-in execution level (RBT-WP-0006-T01).
• G7 Outputs feed later members. A project run snapshots its attributes at the start. Facts established by one member (the custody model chosen in S2, "OpenBao initialized" in S3) do not flow into the members after it. A staged bootstrap as a project needs that flow.

Consequences

• The seven runbooks and the three NetKingdom packs can be native v0.2 packs now. The three NetKingdom packs are ported in RBT-WP-0009-T06. The seven console runbooks are ready to port as a separate content task in net-kingdom; they need none of G1 to G7.
• The console stays. It is a permanent legacy pack, launched unchanged. What it does well and v0.2 cannot yet do (live probes, regression, a fact store that outlives a session, conditional gates) is exactly G1, G3, G5 and G7.
• The engine extraction (RBT-WP-0005-T04) waits for G1, G3 and G7. Extracting the generic parts first would freeze the console's workarounds into the engine.
• The console is a project, not a run. The right long-term shape is a project whose members are runbook packs per stage, with facts flowing between them (G7). That is a design task for a v0.3, not a migration.