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. Schema: custody-record v0.1. Reference implementation and fixtures: validator.

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. 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.