OpenBao Ceremony UX

Status: draft UX contract Date: 2026-05-24

Purpose

This document translates the Railiance OpenBao ceremony into a guided UX. It is the product contract for NET-WP-0016-T05.

The UI must make unsafe live initialization difficult to do accidentally. The first prototype should not execute bao operator init; it should show readiness, blocked gates, and the manual ceremony steps.

Ceremony States

State	Meaning
`not-ready`	Required gates are missing
`preflight-ready`	Safe checks pass, but human ceremony still required
`human-ceremony`	Operator is running the live init/unseal outside automation
`post-unseal-config`	Audit, mounts, auth, and policies are being configured
`root-disposition`	Root token is revoked or sealed offline
`restore-required`	Snapshot/restore drill still blocks live secrets
`ready-for-handover`	OpenBao is ready for cleanup and custody handover

Readiness Gates

Live initialization is blocked unless:

king credential kit is complete;
custody mode is selected;
recovery material is prepared for the selected custody mode;
offline custody packet is prepared for the selected custody mode;
selected custody mode is explicitly approved;
OpenBao pod and PVC preflight passes;
OpenBao reports Initialized: false and Sealed: true;
operator has acknowledged no secret output enters unsafe channels;
maintenance window is deliberate; and
human ceremony mode is selected.

Preflight Panel

The OpenBao panel should show:

Check	Source
Pod status	`make openbao-status`
PVC status	`make openbao-status`
Initialized/sealed state	`bao status` through Railiance target
Helper script readiness	`make openbao-verify`
Custody gates	NetKingdom bootstrap metadata
Restore gate	State Hub task/progress evidence

The UI should show command output as plain text and mark any unknown result as unknown, not success.

Human Ceremony Guide

When ready, the UI prints a guide:

Confirm no screen recording or shared terminal logging is active.
Confirm the offline custody packet is physically ready.
Run the Railiance command manually in the approved shell.
Route each unseal share directly to its approved custody location.
Unseal by prompt, not by command-line argument.
Use the root token only for first configuration.
Run initial configuration helper.
Create non-root admin path.
Revoke or offline-seal the root token.
Record only non-secret evidence.

The UI must not ask the operator to paste unseal shares or root tokens.

Post-Unseal Configuration

The UI may guide these safe commands:

make openbao-configure-initial
make openbao-verify-post-unseal

Token entry must remain prompt-based or local-file based as implemented by Railiance helpers. The UI should not store or echo the token.

Evidence Record

The UI may record:

ceremony date;
custody mode;
OpenBao initialized status;
audit enabled status;
initial mounts/policies loaded;
root-token disposition category: revoked, offline-sealed, or deferred;
snapshot taken status;
restore drill status; and
operator/contact.

It must not record secret values.

Failure Handling

If init output is accidentally exposed:

Stop the ceremony.
Mark the ceremony as compromised.
Do not migrate live secrets.
Rotate/rekey according to OpenBao procedure before proceeding.
Record non-secret incident evidence.

If post-unseal configuration fails:

Keep root token handling in human custody.
Do not create live secrets.
Fix the configuration issue.
Rerun the helper or manual command.
Record the failed step without secret output.

3.7 KiB Raw Permalink Blame History