hub-core/docs/access-readiness.md

Access dependency readiness

HUB-WP-0012 source candidate, 2026-09-28.

Protected GET /readyz now reports access_identity, access_facts, access_policy and access_audit, plus their aggregate access_profile. Controller configuration alone cannot mark these dependencies ready.

Each observation records the completion of a real verified dependency operation:

• Identity: the configured verifier returns a verified actor.
• Facts: the authoritative result matches that actor, includes evidence and is fresh. Revoked or inactive state is a valid owner response, not an outage.
• Policy: the configured evaluator returns a verified decision. A signed denial demonstrates usable policy evaluation while still denying the operation.
• Audit: the configured sink acknowledges authorization or refusal custody. Committed-outcome delivery has its separate durable backlog readiness check.

Before an observation exists, its status is unavailable. Dependency errors or cancellation mark it unavailable immediately. Successful observations expire to stale after ten seconds using a monotonic clock. Invalid user-token refusals neither poison a previously healthy identity sample nor refresh its age. Invalid facts and malformed policy adapter results do not count as success. A fact that expires while policy/audit run also becomes unavailable. A decision that expires before dispatch marks policy unavailable, even if audit custody succeeded. The aggregate is ok only when all four samples are fresh successes.

These process-local observations are diagnostics, never cached authorization. Every request continues through token verification, current facts, signed policy and durable audit. The controller itself now enforces a ten-second deadline, including for direct SDK callers; HTTP/browser deadlines remain in place. No credentials, owner URLs, token contents or raw exceptions appear in readiness.

/readyz remains protected: its own authorization refreshes the observations before the handler reads them. If that authorization fails, the boundary returns its normal 401/403/503 response instead of exposing dependency details to an unauthorized caller. AccessController.readiness_checks() provides the same read-only snapshot to an admitted host composition without making network calls. Only minimal /healthz remains publicly available in the default composition.

This is recent usability, not an independent promise of owner reachability. OIDC verification may use the admitted bounded JWKS cache; it does not prove that the issuer is reachable at that instant. Flex-auth's reviewed /healthz reports liveness only, and the facts adapter has no admitted independent health contract. Hub therefore does not invent health endpoints, send synthetic root requests or interpret liveness as an authorization grant. Independent owner probes, monitoring admission and live outage/recovery receipts remain integration work.

Local tests cover cold/stale state, named failures and recovery, invalid-token isolation, policy denial, bad facts/adapter results, cancellation/deadline behavior, protected readiness and unchanged liveness. Conformance checks include access and outcome-delivery dependencies when present, so correctly degraded readiness is recognized rather than mistaken for a healthy dependency set.

Validation on 2026-09-28: 372 ordinary tests, five disposable PostgreSQL tests and six owner-source Audit Core tests passed. Inventory, build and installed-wheel checks passed. These are local receipts, not deployed owner acceptance.