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. Delivery and identity admission are pending; design acceptance does not assign a custodian or establish a real root grant. 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 actual user-engine runtime identity/auth binding, writer custody binding, bootstrap provenance and live acceptance are still owner delivery requirements. The producer packet is railiance-platform/openbao/root-grant/README.md.

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.