railiance-platform/openbao/root-grant/README.md

# Approved platform-root producer design

Prepared for NK-WP-0045-T05 / RPF-WP-0049, 2026-10-03. Founder approved:
"Accept ADR-0017 and approve the proposed OpenBao delivery design."
Scoped made decision receipt: `c2cff929-91b9-4018-bfd6-fa04f7da8280`.
This selects railiance-platform and the exact source below. Identity admission,
attended live provisioning, custody provenance and live readiness remain pending.
NetKingdom canon remains authoritative; reviewed baseline is net-kingdom commit
`db319335b27b61b855382ee5af5d690f06eeb010`. Deployments must pin the validator
and its schema together, and reconcile amendments before publication.

## Approved source and transport

- KV v2 mount: `platform` (existing owner convention; live suitability unverified).
- Exact API path: `/v1/platform/data/custody/net-kingdom/platform-root`.
- `record_id`: `nk-custody:platform-root`; `owner_system`: `net-kingdom-custody`.
- API response unwrap: `data.data.document` is the complete canon document.
  `data.metadata.version` is KV concurrency state, distinct from canon revision.
- Reader: owner manifests identify namespace `user-engine`, ServiceAccount
  `user-engine`. Role `user-engine-root-custody-reader` on `auth/kubernetes`
  binds exactly those values and audience `openbao`. Tokens last at most 60s,
  with no default policy. Dedicated projected JWT is owned by rapp-user-engine;
  the existing flex-auth JWT and ESO AppRole are not reused. Live admission
  remains unexecuted. Reader policy is exact-path read;
  no list, sibling read or write. Never distribute an attended writer token.
- Writer: separate human custody lane, bounded attended MFA operator login,
  reviewed exact-path policy. This packet does not grant a credential or role.
- Reader timeout 5 seconds, maximum document 256 KiB. A successful authenticated
  owner read, not document time or a cache read, sets observed_at. Failure means
  no grant. No raw server response/error logging.

## Offline implementation

`scripts/root_grant_publish.py` creates a single KV v2 CAS payload from a
candidate, previous document, exact previous KV version and the pinned
NetKingdom validator module. No network or publication is implemented here.
It validates both documents, exact source identity and successor semantics;
refuses missing existing baselines, same-revision changes and rollback. CAS=0
is bootstrap-only, CAS=current-version updates; a CAS conflict requires a fresh
owner read and revalidation, never blind retry. It never prints documents.

The attended executor is implemented in `scripts/root_grant_attended.py`:

- `provision` checks existing Kubernetes auth and active audit, admits only the
  exact reviewed reader policy/role, enables CAS on this key and verifies all
  readbacks. Differing existing policies/roles are refused without overwrite.
- `publish` reads current document and KV version together, validates pinned
  canon and the persisted high-water baseline, fsyncs a pending journal before
  CAS write, verifies exact readback, retains immutable local history and
  atomically advances state. Exact replay creates no new version. Ambiguous
  writes recover only after exact matching owner readback and durable history.
- `restore-check` requires the independently retained publisher baseline to
  match the restored source exactly. Missing/different baseline never resets
  authority or permits rollback. Off-host history backup is still an execution
  dependency; local files alone cannot prove safe disaster restoration.
- The silent child requires the existing warden attended-login envelope and
  exact loopback OpenBao tunnel. No raw process response/error is emitted.
  Every invocation requires a new receipt path: old success receipts are refused.

## Authorized attended execution packet

Founder approval to "go forward" authorizes continued implementation and bounded
provisioning of the approved design. No additional generic design approval is
requested. Attended OIDC/MFA must still run in the founder's own terminal:

```bash
BAO_ADDR=http://127.0.0.1:18200 VAULT_ADDR=http://127.0.0.1:18200 \
  warden access openbao-platform-admin-login --exec -- \
  /home/worsch/railiance-platform/scripts/root-grant-attended.sh provision \
  --receipt /tmp/platform-root-admission-UNIQUE-RUN.json
```

Replace UNIQUE-RUN with a fresh run identifier. The child is silent. Inspect the
new JSON receipt and warden's printed result; a shell exit code or previous
receipt cannot establish success. Provisioning does not create a custody grant.
Existing operator platform-admin identity provides the human writer lane;
this packet does not create another privileged identity or reuse its token in
user-engine. Deployment/network policy/consumer activation belongs to
rapp-user-engine and follows source image publication and admission receipts.

The founder reported that no actual custody ceremony is known. NetKingdom has
therefore prepared `examples/custody-record/initial-empty-record.json`, a
schema-valid first publication candidate with `entries: []`. It establishes no
root grant. The non-secret provenance is
`net-kingdom/docs/evidence/2026-10-03-root-grant-delivery-progress.md`.
Continued go-forward approval covers preparing and publishing this no-grant
baseline through the attended owner lane; no new generic approval is needed.
A future real grant still requires a genuine signed human ceremony with exact
issuer and subject; planned roster/LLDAP membership cannot supply it.

After successful admission, run this second attended step in the founder's
terminal. Create the operator-owned state directory first; it must persist
outside the checkout and outside warden's temporary attended-login home.

```bash
install -d -m 700 /home/worsch/.local/state/net-kingdom-root-custody
BAO_ADDR=http://127.0.0.1:18200 VAULT_ADDR=http://127.0.0.1:18200 \
  warden access openbao-platform-admin-login --exec -- \
  /home/worsch/railiance-platform/scripts/root-grant-attended.sh publish \
  --candidate /home/worsch/net-kingdom/examples/custody-record/initial-empty-record.json \
  --state /home/worsch/.local/state/net-kingdom-root-custody/baseline.json \
  --provenance-ref net-kingdom/docs/evidence/2026-10-03-root-grant-delivery-progress.md \
  --net-kingdom /home/worsch/net-kingdom \
  --validator-digest 9156e399c8d92a45b817bfc3738c89843487ce57e1718ed747f804f95cc719bb \
  --schema-digest bb6cd6da5dc48eddcf118ae78c2cacfafd5f860098fd8a8368fe6bc845776d07 \
  --receipt /tmp/platform-root-publish-UNIQUE-RUN.json
```

Inspect the new receipt. Existing source without independently retained state
is refused rather than overwritten; a failed/ambiguous write requires owner
readback and journal recovery. Bootstrap uses CAS=0. The publisher retains
baseline.json and immutable history/ receipts. Restore `baseline.json`, history/
and any pending journal from independently retained latest evidence before a
recovery check; restoring only an older OpenBao snapshot cannot establish
current authority. The operator-workstation state is already off-host and independent of
railiance01/OpenBao. Documenting backup and readback of that receipt holder
remains an explicit acceptance dependency; no new service is required merely
to duplicate it. Local state enables safe
publication but does not satisfy that independent recovery proof.

`restore-check` takes the same source pins and state but no candidate or
provenance argument, plus a fresh receipt path, via the same attended wrapper.
Source digests enforce the reviewed NetKingdom validator and schema without
importing an unreviewed path. Neither command should print document contents,
privileged tokens or raw backend errors.

Acceptance also needs revocation/supersession exercise and rollback/restore
receipts. Exercise real grant changes only under their own custody ceremony
approval. Use isolated synthetic paths for non-live algorithm exercises.

## History, recovery and audit

OpenBao audit is owned by railiance-platform; the custody fact and ceremony are
owned by net-kingdom-custody. Confirm mount backup owner and restoration before
calling this source live. Retain KV history and independent publication digest /
revision high-water receipts. Readers persist their own trusted baseline across
restart. A restored snapshot must not reactivate an older grant: suspend reads,
compare restored record with independently retained latest baseline, reconcile
all later custody actions, and re-enable only after owner receipts. Do not
reset baselines, destroy versions or recreate an old record under the same ID.
KV CAS prevents races, but is not proof against snapshot rollback. Retention and workstation receipt-holder backup/readback proof remain owner
acceptance requirements, alongside isolated OpenBao recovery evidence.

No control was relaxed and no live action was taken. Emergent knowledge 0.2.3
start was withheld/orientation-only (digest
60f8811c6b94b30d357a0d9e5022f2a8ea52e69b47138d3a536755f3295310b5);
source review read the-custodian agent-environment-orientation section 0 and
informed-decision README, plus the source NetKingdom contract/schema/validator.

Producer delivery receipts complete RPF-WP-0049-T05 / NK-WP-0045-T05.
Consumer integration and runtime acceptance follow in USER-WP-0037-T02 /
NK-WP-0045-T06; they do not block initial producer delivery.

## Attended execution outcome — 2026-10-03

The founder executed admission and empty publication. Fresh receipts, initial
revision 1/KV1/no-grant digest and exact residual recovery/reader evidence are
recorded in [delivery evidence](../../docs/evidence/2026-10-03-platform-root-custody-delivery.md).
This completes RPF-WP-0049-T04. T05 remains evidence-blocked; generic approval
is not pending. Old operator role configuration is not an execution receipt.