spec: runbook-pack/v0.1
id: nk.openbao-operating-path
title: "OpenBao: consume, attend, recover"
owner: net-kingdom
outcome: You can reach the already-deployed private OpenBao, know which owner serves a credential, know the custody model and the attended recovery path, and have seen the ceremony-record validator refuse a secret marker.
exercise_status: unexercised
engine: native
parameters:
  - {id: need, label: The credential you need, type: text, default: read a database password, help: Plain words; used only to look up the owner.}
  - {id: tunnel, label: OpenBao tunnel, type: string, default: openbao-ui-railiance01, pattern: "[a-z0-9-]+", help: The named ops-bridge tunnel; never a public Bao URL (bao.coulomb.social is retired).}
  - {id: evidence, label: Ceremony record path, type: path, default: .local/openbao-ceremony-record.json, help: Relative to the net-kingdom checkout. Only meaningful after an attended ceremony.}
  - {id: probe, label: Scratch path for the negative probe, type: path, default: .local/ceremony-negative-probe.json, help: Created and removed by the probe step.}
prerequisites:
  - {text: bridge CLI and the named tunnel definition, owner: ops-bridge}
  - {text: warden CLI for credential routing, owner: ops-warden}
  - {text: OpenBao already deployed and private. Greenfield deployment is a lab exercise only and never part of this pack, owner: railiance-platform}
  - {text: A net-kingdom checkout; commands run from its root, owner: net-kingdom}
steps:
  - id: route
    title: Find who owns the credential
    owner: ops-warden
    command: warden route find "{{need}}" --json | head -30
    verify:
      done_when: You know which repository owns the credential and that warden only routes, it does not vend
      expect: manual
    evidence: [owner_repo]
  - id: tunnel-status
    title: Check the OpenBao tunnel is connected
    owner: ops-bridge
    command: bridge status
    verify:
      done_when: The tunnel row shows connected
      command: bridge status | grep -E "{{tunnel}} +connected"
      expect: exit-0
  - id: tunnel-check
    title: Run the end-to-end tunnel diagnostic
    owner: ops-bridge
    command: bridge check {{tunnel}}
    verify:
      done_when: The diagnostic passes
      command: bridge check {{tunnel}}
      expect: exit-0
  - id: custody-models
    title: See the unseal custody models
    owner: net-kingdom
    command: python3 tools/security-bootstrap-console/security_bootstrap_console.py openbao-unseal-custody-models
    verify:
      done_when: attended-ceremony is listed as implemented
      command: python3 tools/security-bootstrap-console/security_bootstrap_console.py openbao-unseal-custody-models | grep -q attended-ceremony
      expect: exit-0
  - id: console-gates
    title: Read the custody gates for the selected model
    owner: net-kingdom
    command: make security-bootstrap-console
    verify:
      done_when: You have read every gate and know which are met and which are not
      expect: manual
  - id: recovery-read
    title: Read the attended recovery path
    owner: net-kingdom
    command: sed -n 1,82p docs/openbao-attended-ceremony-runbook.md
    verify:
      done_when: You can state who must be present, where each unseal share goes, and when the root token is revoked
      expect: manual
  - id: probe-refused
    title: Watch the ceremony-record validator refuse a secret marker
    owner: net-kingdom
    description: Writes a scratch file holding a fake token-shaped marker, runs the validator on it, and removes the file. The marker is assembled at run time so this pack never contains one.
    command: |
      printf '{"note":"%s%s"}\n' hvs. AAAAAAAAAAAAAAAA > {{probe}}
      make security-bootstrap-validate-openbao-ceremony-record EVIDENCE={{probe}} 2>&1 | grep "secret-looking marker present"
      rm -f {{probe}}
    risk: changes-state
    rollback: rm -f the probe file; nothing else is written.
    verify:
      done_when: The validator names a secret-looking marker as a reason for refusal
      command: |
        printf '{"note":"%s%s"}\n' hvs. AAAAAAAAAAAAAAAA > {{probe}}
        make security-bootstrap-validate-openbao-ceremony-record EVIDENCE={{probe}} 2>&1 | grep -q "secret-looking marker present"
        r=$?
        rm -f {{probe}}
        exit $r
      expect: exit-0
  - id: valid-record
    title: Validate a real ceremony record
    owner: net-kingdom
    description: Only possible after an attended ceremony has produced a record. Without one, skip this step; a run with a skipped step cannot exercise the pack.
    command: make security-bootstrap-validate-openbao-ceremony-record EVIDENCE={{evidence}}
    verify:
      done_when: The validator passes on the ceremony record
      command: make security-bootstrap-validate-openbao-ceremony-record EVIDENCE={{evidence}}
      expect: exit-0
  - id: read-secret
    title: Read one secret you are entitled to
    owner: railiance-platform
    description: Authenticate with your own identity and read only the path the routing result names, following railiance-platform/docs/openbao.md. Never paste the value anywhere.
    risk: attended
    rollback: Close the session; the read changes no state. If a value was exposed, treat it as compromised and rotate it through its owner.
    verify:
      done_when: You read only the routed path with your own identity and no value was pasted into chat, logs, State Hub or a checkout
      expect: manual
threat_checks:
  - Init output, unseal shares and tokens go to the operator's screen only, never to chat, State Hub, logs or a Git checkout.
  - Never use a public Bao URL; bao.coulomb.social is retired.
  - Never place the root token and unseal shares in one artifact outside a lab.
  - This pack never initializes or unseals the live estate.
ownership:
  - {concern: "OpenBao deployment, configuration and unseal execution", owner: railiance-platform}
  - {concern: Custody canon and the ceremony-record validator, owner: net-kingdom}
  - {concern: Tunnel, owner: ops-bridge}
  - {concern: Credential routing, owner: ops-warden}