net-kingdom/docs/contracts/root-grant-read-contract_v0.1.md

# Root-grant read contract v0.1

Owner: net-kingdom. Status: approved delivery design, 2026-10-03.
Tracks NK-WP-0045 and accepted [ADR-0017](../adr/ADR-0017-root-grant-custody-and-account-authority.md).
Schema: [custody-record v0.1](../../canon/schemas/custody-record_v0.1.schema.json).
Reference implementation and fixtures: [validator](../../tools/custody-record/README.md).

The founder accepted ADR-0017 and selected the OpenBao design below. Attended
reader admission, empty-record publication and live consumer integration are
verified in the [delivery evidence](../evidence/2026-10-03-root-grant-delivery-progress.md).
Independent producer recovery closure remains pending. No custodian has been
assigned and no real root grant established. Fixtures are
synthetic and must never seed the authoritative record.

## Read-surface decision (T04)

The founder explicitly accepted ADR-0017 and approved the proposed OpenBao
design. Scoped receipt: `c2cff929-91b9-4018-bfd6-fa04f7da8280`.
T01/T04 are done; bundled D10 `cef97ccd-4ee7-40fe-859e-1df9c9360ecb`
stays open for its separate MFA journey.

Selected delivery owner: **railiance-platform**, RPF-WP-0049. OpenBao KV v2
mount `platform`, API path `/v1/platform/data/custody/net-kingdom/platform-root`,
record ID `nk-custody:platform-root`, owner `net-kingdom-custody`. The complete
schema document is at response `data.data.document`; KV metadata version is
transport concurrency state, not the custody revision.

user-engine reads through an authenticated exact-path read-only identity;
separate attended human custody writes publish whole-document CAS updates.
The runtime owner declarations now confirm namespace and ServiceAccount
`user-engine` (`rapp-user-engine/manifests/runtime.yaml`). The reader admission
uses role `user-engine-root-custody-reader` on existing `auth/kubernetes`,
with a separate projected JWT audience `openbao`. Its short-lived OpenBao token
has no default policy and only the exact document read. The flex-auth JWT and
ESO credentials are separate and cannot substitute for this admission.

The founder subsequently approved going forward with implementation and the
approved delivery design. Actual admission and attended empty custody publication
succeeded, and controlled bootstrap/live empty-source acceptance succeeded.
Independent retained-history backup and producer recovery/audit evidence remain
owner execution requirements.
The producer packet is `railiance-platform/openbao/root-grant/README.md`.

user-engine retains its source/revision baseline atomically in its existing
PostgreSQL store. Runtime starts with initial-baseline bootstrap disabled;
controlled initialization must bind the authenticated owner read to retained
publisher provenance. A database or OpenBao restore requires reconciliation
against independently retained latest publication evidence before activation.

## Producer requirements (T05)

The selected owner must implement these requirements in its own repository,
link its workplan/task in NK-WP-0045-T05, and return non-secret delivery evidence:

1. Publish a complete schema-valid JSON document as one atomic revision. Bind
   its `record_id` and `owner_system` to the trusted configured source. A schema
   pass alone cannot authenticate its authority.
2. Admit a real reader identity through the existing owner routing procedure;
   deny unauthenticated readers and deny custody writes by reader identities.
   Keep credential material out of the document and delivery receipts.
3. Populate real entries only from human-controlled custody ceremony evidence,
   with exact issuer/subject and actor/time/reason. A directory or JWT projection
   cannot supply the grant. NetKingdom does not create a real entry from fixtures.
4. Validate every candidate document and its transition from the previous
   document before publication. Retain all entries and immutable grant facts;
   new grants, revocations and supersessions use revisions above the previous
   revision. Never reuse a revision for changed content. `updated_at` must not
   move backwards. Preserve revision history through backup/restore.
5. On read failure, incomplete publication or invalid data, report failure
   without returning a last-good document as a newly read authoritative result.
   Suppress raw documents, rejected values and credential errors in logs.
6. Document endpoint/path, authentication, timeouts/size limits, deployment
   revision, revocation procedure, recovery and audit owner. Supply positive and
   denial/outage/restore receipts before declaring the surface live.

## Consumer requirements (T06 / USER-WP-0037-T02)

user-engine owns the adapter and optional `AccountAuthority.root_grant` mapping.
Downstream workloads read that fact through user-engine's authenticated account
authority surface; they do not mint it from claims or configured root subjects.

1. Authenticate the source and bind the expected record ID before validating.
   Read with bounded timeout/size and preserve the actual successful owner read
   time. File mtime, document `updated_at`, HTTP proxy/cache hits, and viewing a
   cached observation do not establish a new authoritative read time.
2. Validate schema and semantics; compare with the last trusted document using
   `successor_errors`. Keep the last trusted revision/content across cache
   replacement and restart. Reject rollback and same-revision mutation; do not
   silently reset that baseline after a source/record change. The runtime owner
   must define the controlled rebootstrap procedure.
3. Call `observe_root_grant` with timezone-aware read/check times and the last
   trusted document (`previous_record`) when present. Match exact issuer and
   subject, without username, email, case folding, or issuer normalization.
   Only tenant `platform` and active `platform-root-custodian` entries qualify.
   Future records/grants, revoked/superseded entries and malformed reads yield
   no grant. An empty valid record also means no grant.
4. Cache read observations no longer than the record's `max_cache_seconds`
   (0–900 seconds). Re-check the owner for every root-grant-dependent write.
   Failed reads, stale data or rollback yield no grant for that action, even if
   a previous read granted it. Never extend expiry by re-reading local cache.
5. Retain only `subject`, fixed `grant`, `source.record_id/revision`,
   `observed_at`, and expiry/revocation time when known. No root grant for other
   tenants, unknown subjects, tenant admins, directory-only or JWT-only roots.
   The fact does not replace flex-auth authorization for the requested action.

## Acceptance receipts

| Receipt | Responsible repo | Unblocks |
| --- | --- | --- |
| ADR acceptance/amendment and surface/owner selection | net-kingdom records the founder's decision | T01, T04 |
| Owner workplan/task, authenticated read location, real ceremony provenance, atomic revision and denial/outage/recovery/audit evidence | Selected delivery repo; railiance-platform for OpenBao option | T05 |
| Adapter commit, exact mapping, retained source/time, and positive/negative integration tests against the delivered surface | user-engine, USER-WP-0037-T02 | T06 |

Integration evidence must cover grant, revocation, supersession, unknown/wrong
issuer, wrong tenant, projection-only input, expired cache, failed read,
rollback, same-revision mutation and no cache renewal on local reads. Local
fixtures establish algorithm behavior; they cannot satisfy live delivery or
real custody provenance. USER-WP-0037-T03's separate Hub credential admission
remains owned by user-engine/state-hub and is not delivery evidence for T05.