Implement authenticated custody observations and durable root-grant baseline

Assistant: codex
Assistant-Model: gpt-6.1-sol
Assistant-Session: 01a1029d-2c93-7500-a0e0-e3e089668b29

docs/root-custody-runtime.md

@@ -0,0 +1,82 @@
+# Root custody consumer delivery
+
+USER-WP-0037-T02 implements accepted NK-ADR-0017 without creating custody entries.
+The runtime remains disabled unless USER_ENGINE_CUSTODY_ENABLED=true. Optional
+AccountAuthority.root_grant is a source fact, never a flex-auth decision.
+
+## Configuration and owner boundary
+
+The deployment owner is rapp-user-engine: namespace user-engine, Deployment
+user-engine, ServiceAccount user-engine. A dedicated projected JWT with audience
+openbao must be supplied; the existing flex-auth audience token is unsuitable.
+railiance-platform supplies auth/kubernetes role user-engine-root-custody-reader,
+exact-path-only reader policy, no default policy, and maximum 60-second token TTL.
+No ESO AppRole or operator token is used. Login occurs on every read; revoke-self
+is best-effort and may be denied by the exact-path policy. TTL limits that residue;
+the consumer does not claim confirmed revocation.
+
+| Variable | Binding |
+| --- | --- |
+| USER_ENGINE_CUSTODY_ENABLED | true to opt in; unset defaults disabled |
+| USER_ENGINE_CUSTODY_BAO_URL | Owner-confirmed origin only; no path or credentials |
+| USER_ENGINE_CUSTODY_AUTH_MOUNT | kubernetes |
+| USER_ENGINE_CUSTODY_ROLE | user-engine-root-custody-reader |
+| USER_ENGINE_CUSTODY_JWT_FILE | Dedicated audience=openbao projected JWT file |
+| USER_ENGINE_CUSTODY_TIMEOUT | Total request deadline, default 3 seconds |
+| USER_ENGINE_CUSTODY_ALLOW_HTTP | Default false; true requires reviewed in-cluster transport trust and network controls |
+
+The path is fixed to /v1/platform/data/custody/net-kingdom/platform-root and the
+whole JSON document is data.data.document. Responses are bounded to 256 KiB;
+redirects, proxy environment settings, reported cache hits, compressed bodies,
+invalid records and source changes are rejected. Errors never print values.
+HTTPS uses system CA verification by default. The currently proposed in-cluster
+HTTP route has no TLS origin authentication; owner-approved network confinement
+and exact origin binding are required before enabling it. A configured origin
+alone does not prove live trust.
+
+The embedded custody_canon package contains validator/schema and provenance
+hashes, pinned to NetKingdom db319335b27b61b855382ee5af5d690f06eeb010. Only
+schema lookup is relocated. Policy updates require reviewing canon and refreshing
+pin/hashed provenance. No sibling checkout is used in production. root_grant
+retains exact subject, fixed grant, record id/revision, owner read observed_at,
+and expires_at from the record's tighter cache bound. Check time is sampled
+after I/O; local reads never renew owner read time.
+
+## Durable baseline and controlled initialization
+
+The existing USER_ENGINE_DATABASE_URL holds the singleton
+user_engine_custody_baseline table using a separate connection. Compare-and-swap
+prevents competing workers overwriting a newer baseline. Empty/revoked records
+also persist. Startup never creates an initial baseline from a record automatically.
+
+After the publisher has returned a reviewed source/read admission receipt, an
+attended owner may initialize an absent baseline. An explicitly approved empty
+entries[] document establishes no grant and needs no invented ceremony. Every
+non-empty grant still requires human custody-ceremony provenance. Initialize using:
+
+```sh
+python -m user_engine.custody_bootstrap --expected-sha256 <publisher-document-digest>
+```
+
+Run with the same secret-backed runtime environment and dedicated reader JWT.
+The non-secret digest must come from a reviewed publisher receipt, not fixtures;
+it hashes UTF-8 JSON with sorted keys, compact separators and ensure_ascii=True.
+The command performs a fresh authenticated read, validates record/id/time and
+digest, then atomically initializes only an absent baseline. It emits one boolean
+outcome and never resets an existing baseline. It creates no custody entry.
+
+Source/record changes and database restores require owner reconciliation; there
+is intentionally no automatic reset command. Preserve baseline high-water records
+outside the restored database and compare with publisher history/audit receipts.
+If both source and consumer databases restore backwards, their mutually agreeing
+old state cannot detect rollback by itself. Keep this feature disabled through
+restore until owner audit/history establishes the latest revision and a reviewed
+reconciliation updates the baseline. Never delete the row to make a read pass.
+
+## Remaining live acceptance
+
+The code and offline fixtures do not establish a real grant. Delivery requires
+publisher ceremony provenance, role/policy receipts, projected-token packaging,
+network trust, owner-reviewed baseline initialization, image digest promotion and
+positive/denial/outage/revocation/supersession/restore receipts through the actual
+Hub workload route. USER-WP-0037-T03 retains its separate Hub admission blocker.