net-kingdom/docs/openbao-unseal-custody-models.md

OpenBao Unseal Custody Models

Date: 2026-06-17
Status: framework — automation path active; production paths planned

NetKingdom bootstrap must support three OpenBao init/unseal custody models. Development starts with maximum automation for fast test cycles, then adds human custody gates as production trust increases.

This is separate from king custody mode (temporary-single-king, two-of-three-planned, two-of-three-ready) which governs who holds platform recovery authority. Unseal custody models govern how init/unseal executes during bootstrap and rebuild.

---

Models

Model ID	Label	Custody strength	Automation	Status
sops-held-automation	SOPS-held unseal	Lab / fast iteration	High	Implemented (console + creds agent path)
attended-ceremony	Attended ceremony	Production	Low	Planned
auto-unseal-transit	Auto-unseal (transit/KMS)	Production HA	High	Planned

sops-held-automation (default for greenfield dev)

• Init/unseal material lives in SOPS/age custody bundle (not Git plaintext).
• Applied by sso-mfa/bootstrap/creds-bootstrap-agent.sh and related creds-apply tooling after cluster + OpenBao pod exist.
• Enables unattended rebuild test cycles on a 3-node slate.
• Not production trust posture — use to prove S1→S3→SSH engine automation, then graduate to stronger models.

attended-ceremony (production target)

• Human-attended bao operator init, out-of-band unseal share escrow, root token retirement — per railiance-platform/docs/openbao.md.
• Matches first successful NetKingdom bootstrap (NET-WP-0015–0017).
• Console keeps refuse-live-init boundary; ceremony runbooks only.

auto-unseal-transit (production HA target)

• OpenBao seal configuration uses transit or cloud KMS auto-unseal.
• Pod restart without manual unseal threshold ceremony.
• Requires railiance-platform Helm seal stanza + KMS provisioning.

---

Development strategy

1. Implement automation path (sops-held-automation)
      → SSH engine, warden sign, host CA trust, 3-node rebuild loops
2. Add attended-ceremony gates (block automation defaults in production profile)
3. Add auto-unseal-transit for HA ThreePhoenix rebuilds

Each model is selectable in the security bootstrap console. Unimplemented models are blocked with a hint pointing to the active automation path.

---

Console integration

# List models and implementation status
python3 tools/security-bootstrap-console/security_bootstrap_console.py \
  openbao-unseal-custody-models

# Select active model (only implemented models succeed)
python3 tools/security-bootstrap-console/security_bootstrap_console.py \
  select-openbao-unseal-custody-model \
  --model sops-held-automation \
  --metadata .local/security-bootstrap.json

# Status shows gate: "OpenBao unseal custody model"
make security-bootstrap-console   # or: ... status --metadata .local/...

Metadata field: openbao_unseal_custody_model

---

Automation chain (after model selected)

Step	Owner	Target
S1 OS baseline	railiance-infra	3 nodes
S2 k3s HA	railiance-cluster	ThreePhoenix
S3 OpenBao deploy	railiance-platform	make openbao-deploy
Init/unseal apply	net-kingdom	creds-bootstrap-agent.sh (sops-held)
Platform config	railiance-platform	openbao-configure-initial
SSH engine	railiance-platform	openbao-configure-ssh (planned)
Host CA trust	railiance-infra	bootstrap-ssh-ca (planned)
Sign smoke	ops-warden	warden sign (WP-0008 T2)

---

Related docs

• docs/smooth-bootstrap-guide.md — Step 5 (OpenBao init/unseal)
• docs/platform-root-custody.md — king / quorum custody
• railiance-platform/docs/openbao.md — deploy and ceremony
• ops-warden/wiki/OpenBaoSshEngineChecklist.md — SSH engine verify
• ops-warden/history/2026-06-17-openbao-production-verify.md — current blockers