hub-core/docs/owner-facts-contract.md

Platform authority facts: owner review contract

HUB-WP-0012 T01/T02, reviewed 2026-10-04. Hub-side composition and User Engine HTTP client are implemented; no real Hub caller admission or complete live account/tenant composition is claimed. The current client contract and remaining owner requirements are in the October 4 update; the earlier sections preserve the initial review.

Historical source review — 2026-09-28

• User Engine b4cef6446bc10555b598ea74de1743bc9b03e7ba: service.py::me creates user/account/tenant-account/identity records for unknown (issuer, subject). It cannot be an authorization lookup. identity_context reads linked identity/account and membership evidence without this provisioning, but accepts an actor or target user ID, not an admitted Hub workload's lookup of an arbitrary immutable identity. It does not establish Hub's root entitlement. PLATFORM_TENANT is platform:root; token platform-operator roles are not evidence of a live root grant.
• Tenant Engine 4ce89969c0cc0ab4ba111f1b4009aa137c94a68b: GET /tenants/{tenant_id} exposes lifecycle/version and accepts an actor query for authorization. /roles/live returns tenant roles, not a person's root entitlement. These route handlers do not authenticate a Hub workload. An admitted authenticating gateway could supply that boundary, but no such composition is established by these sources.

These are source findings, not probes of deployed configurations. The follow-up User Engine commit 686da7c adds UserEngineService.lookup_account_authority: an authorized exact issuer/subject/tenant lookup that never provisions a missing identity, returns current global and scoped account status (missing scoped state is explicit), and separates caller from target. The new policy action is account.authority.read; existing generic read grants are not assumed sufficient. Its result includes source observation time, identity/account references and the policy decision reference, but no root entitlement or profile data.

This closes the read-only service primitive, not the wire contract or admitted Hub workload. USER-WP-0037 owns root-grant/mapping disposition and authenticated HTTP exposure/private acceptance. No database, live grant or credential changed.

Initial contract for owner disposition — 2026-09-28

Requirement	Owning decision
Side-effect-free lookup by exact issuer and subject	User Engine: existing identity only; unknown identity denies without provisioning
Current account state and explicit root grant	User Engine + NetKingdom: identity link, global and scoped account state, grant source/revocation/version, independent of JWT roles and Hub root-subject configuration
Platform naming	Both owners: explicit reviewed mapping of User Engine scope to canonical tenant:platform; no string substitution inferred by Hub
Current tenant lifecycle	Tenant Engine: canonical identifier bound to immutable record and version
Caller authentication	Each owner: dedicated Hub workload audience/identity and narrowly scoped read authorization; no end-user bearer forwarding
Freshness and evidence	Each owner: source observation timestamp and durable evidence/version reference; no stale cache on failure
Producer aliases	Account/identity owner: explicit current bindings, or an empty set; no aliases derived from display names

Owners must specify the actual route, request/response schema, authentication mechanism and scoped grants before HTTP reader implementations can be written. The Python types below are an internal normalization seam, not a proposed HTTP endpoint that already exists. Missing/unknown/ambiguous results must raise and deny; they must never synthesize an active account.

Initial composition — 2026-09-28

hub_core.security.facts.PlatformFacts implements FactSource with injected AccountReader and TenantReader. The account reader returns a typed AccountObservation; the tenant reader returns a TenantObservation. Readers own authentication and wire verification. account_active must include the current identity link, global account and required scoped-account validity; a globally active account alone is insufficient. They receive identity references only, not the end-user token. No concrete network reader or automatic environment activation is provided.

The host supplies the reviewed account-tenant identifier and mapping evidence reference explicitly. That mapping is not an entitlement grant. This candidate admits only human actors in tenant:platform; workload and cross-tenant lookups remain separately scoped work. The shared controller still verifies the exact root issuer/subject before consulting this source.

Every request rereads both owners within one three-second budget. Results must match exact identity/tenant bindings, contain strict booleans and nonempty evidence, and be no older than five seconds or in the future. The result retains the oldest source timestamp, so slow joining/policy/audit cannot refresh authority. Inactive or withdrawn state remains a valid observation and is denied by the controller. Failures expose only a sanitized 503 and never fall back to an earlier allow. Cancellation propagates to the pending lookup.

The evidence join is SHA-256 over canonical JSON containing the account, tenant and mapping references. Readers/owners must retain the referenced evidence for reconstruction; this hash is a join identifier, not a signature or independent proof of owner authenticity. No account payload or credential enters the join.

Initial acceptance cases and remaining work — 2026-09-28

Local tests cover exact bindings, malformed state, stale/future observations, oldest-timestamp preservation, bounded outages, repeated lookup, entitlement and account suspension, tenant inactivity, and refusal before policy after withdrawal. Fixtures implement the internal readers; they do not prove owner API acceptance.

T01/T02 remain open for owner disposition of the table above, implementation of real authenticated readers, and isolated owner-source integration tests proving unknown lookups create nothing. Private acceptance must then demonstrate root allow, ordinary/forged identity denial, next-request revocation and owner outages with real admitted callers. No public exposure follows from this contract.

Implemented account reader — 2026-10-04

The historical missing-endpoint assessment above is superseded by User Engine a9360842f84fae89857c2b1a298efc64d079ee7b, USER-WP-0037 and accepted NetKingdom ADR-0017 revision 2 (45a189a39167eef62709df0e857309f7ddc59029). UserEngineAccountReader implements the existing POST /api/v1/platform/account-authority/lookup wire contract. Its independently configured bearer maps to the fixed admitted workload at User Engine; it never forwards the human's Hub token or invents root entitlement.

A host injects a UserEngineAccountReader(base_url=..., token_file=Path(...), client=...) into PlatformFacts(accounts=..., tenants=reviewed_tenant_reader, account_tenant="platform", mapping_evidence="NK-ADR-0017:2"). The HTTP client must be lifecycle-owned, with trust_env=False and no ambient authorization or cookies (as in the existing security composition). The token file is dedicated to this User Engine caller, not the PDP/audit/browser credential. Nothing is automatically enabled by environment variables or this documentation example.

The reviewed custody adapter and its real service integration fixture require lookup tenant platform. This differs from User Engine's legacy operator context platform:root; neither is silently normalized by the reader. The canonical Hub actor/target remains tenant:platform. Before live enablement, owners must confirm the real account has the intended scoped account and that this exact mapping is admitted; a missing scoped account is inactive.

The response must bind issuer, subject and lookup tenant, identity/account/user references, decision reference, known global/scoped status, and timezone-aware observation time. root_grant:null means no entitlement. A non-null grant must match exact issuer/subject, scope_type:tenant, scope_id:platform, relation platform-root-custodian, owner net-kingdom-custody, source record nk-custody:platform-root, positive integer revision and valid timestamps. Unknown/expired/revoked or differently scoped observations fail closed.

Hub deliberately keeps its stricter five-second source age on every read/write, even though the canon permits up to fifteen minutes elsewhere. The earliest account/custody timestamp is retained, and the grant's absolute expiry travels through AccountObservation and LiveFacts to the final post-audit check. The reader trusts User Engine's authenticated observation; User Engine owns durable custody revision/rollback validation. A content digest identifies retained account/grant evidence but does not independently authenticate the publisher. No producer aliases are supplied by this contract, so the result has none.

Every call rereads a bounded workload credential, uses non-local HTTPS and a three-second total budget, limits the response to 64 KiB, rejects redirects, compressed responses and nonzero Age headers, and exposes sanitized failures. No caching or same-token fallback exists. User Engine's current environment-based receiver credential rotation still needs an owner rollout/revocation receipt.

Remaining dependencies — 2026-10-04

Hub tasks	Owner and required artifact	What unblocks Hub
0012-T01	net-kingdom, user-engine, tenant-engine, access-engine and platform surface owners: reviewed action/audience/tenant/enforcement matrix with disputed rows resolved	Signed-off source/profile mapping; executable per-owner acceptance cases
0012-T02	user-engine USER-WP-0037-T03 + railiance-platform/rapp-user-engine: actual Hub workload identity, dedicated credential delivery/rotation reference, TLS origin and scoped account mapping	Wire this implemented client to an admitted private endpoint and prove allow/deny/withdrawal/outage without owner payloads or credentials in evidence
0012-T02	tenant-engine + deployment owner: authenticated Hub caller binding for authoritative lifecycle read, canonical identifier/record version and observation time	Implement TenantReader against that admitted response; do not treat actor query text or roles/live as workload authentication
0012-T02	net-kingdom/KeyCape + custody owner: actual immutable root identity, approved nonempty custody grant where intended, Hub audience/redirect registration and attended AAL2/recovery/revocation receipts	Real positive root journey; the accepted empty custody source proves denial only
0012-T03	access-engine + platform owner: Hub protected-system policy, authenticated workload grant, pinned trusted public keys and credential delivery; audit-core + platform owner: Hub sender classes including hub.operation.committed, operational custody and rotation/failure receipts	Compose real PDP/audit dependencies; existing FLEX-WP-0024/0025 source completion does not admit Hub
0012-T04	rapp-core-hub plus T02/T03 owners: pinned private image/migration/composition, network boundary, explicit owner-bound messaging/event producer aliases and rollback	Execute real browser/API/MCP, direct-service bypass, revocation and audit-outage acceptance
0012-T05	ops-hub first, other inventoried extensions, activity-core/Repo Manager/inbox caller owners: per-audience identity/delegation/tenant contract and host enforcement	Root and workload allow plus anonymous/non-root/wrong-audience/tenant denial with separate attribution
0012-T06	platform/Railiance owners after T04/T05: attended per-surface management and audit receipts	M1 requires every inventory row, not a navigation link or broad provisioning decision
0012-T07	rapp-core-hub RAPPCOREHUB-WP-0002-T05 after M1: explicit public-enable authorization, TLS/bypass/rollback packet	Package and enable only the reviewed public release
0012-T08	identity/tenant/policy owners after M1: roles, delegated principals and stored tenant provenance	Phase 2 implementation can start without inferring tenant authority from legacy data

These requirements update the existing workplans; they are not messages claiming external owners have accepted new work. No control was relaxed or live credential retrieved in this review. Workplans 0006/0011 independently retain A5/A4 cutover and inbox source-feed/retention/reader-admission requirements.

Local verification: make ci-check covers normalization, transport refusal, rotation, withdrawal and post-audit expiry. To exercise the actual owner route and serializer with synthetic authority, run HUB_CORE_USER_ENGINE_SOURCE=/home/worsch/user-engine .venv/bin/python -m pytest -q tests/test_user_engine_owner_contract.py. The owner suite is explicit opt-in and does not contact a live endpoint.