132 lines
8.4 KiB
Markdown
132 lines
8.4 KiB
Markdown
|
# Hub access profile 1.0.0 — implementation candidate
|
|||
|
|
|
|||
|
|
HUB-WP-0012 source implementation, 2026-09-28. Owner review and live acceptance
|
|||
|
|
remain open. This profile does not grant platform access or enable public exposure.
|
|||
|
|
|
|||
|
|
## Runtime behavior
|
|||
|
|
|
|||
|
|
`HUB_CORE_ACCESS_MODE=auto` enables enforcement whenever `HUB_CORE_ENV` is not
|
|||
|
|
`development` or `test`. `enforce` also enables it locally. `development` is
|
|||
|
|
rejected in other environments. **Do not deploy this candidate as a routine
|
|||
|
|
upgrade:** the default production factory has no admitted owner adapters yet and
|
|||
|
|
returns 401 for missing credentials and 503 for credential-bearing requests.
|
|||
|
|
The current deployed image and its release configuration have not been changed.
|
|||
|
|
|
|||
|
|
Only exact `GET /healthz` is public, returning `{"status":"ok"}`. The shared
|
|||
|
|
ASGI boundary protects docs, readiness, native ports, projections, compatibility
|
|||
|
|
aliases and subsequently attached routes. Unknown method/route/handler combinations,
|
|||
|
|
WebSockets, mounts without admission, and slash redirects without catalog entries
|
|||
|
|
fail closed. Clients must use exact paths. Catalog admission does not override
|
|||
|
|
compatibility feature flags or single-writer/read-only gates. Legacy bearer checks
|
|||
|
|
remain in the development lane; production enforcement never falls back to them.
|
|||
|
|
|
|||
|
|
`hub_core/security/routes.json` is the candidate action catalog. It names each
|
|||
|
|
runtime method, path template and handler, with a stable action per handler/method.
|
|||
|
|
It is packaged in the wheel and tested against actual route construction. Source
|
|||
|
|
inventory generation does **not** auto-admit a new route. Duplicate docs handlers
|
|||
|
|
remain separately inventoried; the boundary selects the first effective route.
|
|||
|
|
These technical action names require flex-auth/owner review before policy delivery.
|
|||
|
|
|
|||
|
|
## Composition and trust
|
|||
|
|
|
|||
|
|
A host composes `create_app(access_controller=AccessController(...))` with:
|
|||
|
|
|
|||
|
|
- `OIDCVerifier`: an explicitly trusted HTTPS issuer and Hub audience, an owned
|
|||
|
|
`httpx.AsyncClient`, RS256 discovery/JWKS, token and assurance lifetime at most
|
|||
|
|
300 seconds, a 60-second key cache, and unknown-key rotation refresh (rate limited
|
|||
|
|
to once per second). Access tokens require `at+jwt` or the KeyCape `typ: Bearer`
|
|||
|
|
payload marker. ID tokens, local issuers/profiles, weak keys, AAL0 and delegated
|
|||
|
|
agents are refused. Strict integer NumericDates and assurance time are required.
|
|||
|
|
- `FactSource.resolve`: an **owner implementation still owed** that queries
|
|||
|
|
authoritative account, root entitlement, actor tenant and target tenant state.
|
|||
|
|
Its result binds issuer, subject, actor tenant, evidence reference and permitted
|
|||
|
|
producer addresses; its age may not exceed five seconds, including after policy
|
|||
|
|
and audit finish. No token role or incoming tenant/identity header supplies facts.
|
|||
|
|
- `FlexPolicy`: a dedicated HTTPS Hub PDP, exact admitted ServiceAccount principal,
|
|||
|
|
a rotating projected caller-token file and an owner-delivered trusted public-key
|
|||
|
|
set. The token is reread on every call and is separate from the end-user token.
|
|||
|
|
Remote `/v1/keys` responses never establish their own trust. Current/previous keys
|
|||
|
|
can coexist in the mounted trust file; removing a key takes effect next call.
|
|||
|
|
- `Audit.append`: an **owner implementation still owed** that returns only after
|
|||
|
|
durable acceptance. Every allow must reach this sink before handler execution;
|
|||
|
|
a failed sink blocks reads as well as writes. Authorization receipts say
|
|||
|
|
`authorized`, not “operation completed.” Domain commit/outcome audit remains a
|
|||
|
|
separate requirement; this source seam does not claim transactional audit.
|
|||
|
|
- The root's existing immutable issuer and subject, supplied after owner resolution.
|
|||
|
|
No username, email, first-login promotion or generic role establishes root.
|
|||
|
|
|
|||
|
|
Do not implement these missing adapters as a constant allow, in-memory audit sink,
|
|||
|
|
or an assertion copied from token claims. Tests use synthetic owners explicitly.
|
|||
|
|
The current CLI deliberately provides no fixture adapter or production bypass.
|
|||
|
|
A deployment composition factory and dependency health probes remain T02–T04 work.
|
|||
|
|
|
|||
|
|
For this candidate all Hub resources are explicitly **platform-owned**. Other
|
|||
|
|
target tenants are refused. Root requires AAL2/3, active account and tenants,
|
|||
|
|
current root entitlement, and a fresh policy allow for every action. Workloads
|
|||
|
|
receive no root shortcut: a policy grant and current authoritative facts are always
|
|||
|
|
required. Real workload admission remains unproven. Cross-tenant owner administration
|
|||
|
|
and Phase 2 storage/query isolation are not implemented by this classification.
|
|||
|
|
|
|||
|
|
## Policy interoperability and failure handling
|
|||
|
|
|
|||
|
|
The PDP request carries actor, target tenant, action, concrete resource path,
|
|||
|
|
assurance, root entitlement, authoritative evidence reference, and a digest of
|
|||
|
|
HTTP method/path/query/body. Client bodies and bearer tokens are not sent to the
|
|||
|
|
PDP or audit sink. Body size is bounded at 1 MiB. The controller's identity/facts/
|
|||
|
|
policy/audit chain has a ten-second timeout; individual HTTP calls have three seconds.
|
|||
|
|
A separate refusal-audit attempt is bounded at three seconds.
|
|||
|
|
|
|||
|
|
The verifier requires Ed25519 signing, the submitted request digest, matching
|
|||
|
|
request ID and structured actor/action/resource/tenant/context, enforced caller
|
|||
|
|
provenance, policy version/digest, a decision age at most 30 seconds and a valid
|
|||
|
|
allow lifetime. It never caches decisions. Every unimplemented obligation and
|
|||
|
|
non-allow/non-deny effect fails closed; approval requirements cannot be waived.
|
|||
|
|
A malformed/untrusted/unavailable decision returns 503, a verified denial 403,
|
|||
|
|
and invalid authentication 401. Responses are `no-store` and do not expose backend
|
|||
|
|
exceptions. There is no local allow fallback.
|
|||
|
|
|
|||
|
|
Interoperability tests retain flex-auth's real Go-signed fixture, tampered pair,
|
|||
|
|
public test key and original submitted request. Go `encoding/json` emits struct
|
|||
|
|
fields in declaration order and map keys in sorted order. The verifier retains
|
|||
|
|
wire order and HTML escaping for signatures and reproduces the request structs
|
|||
|
|
for `submitted_request_digest`. This is **not** RFC 8785. Duplicate JSON keys and
|
|||
|
|
non-integer decision numbers are outside this candidate profile and fail closed;
|
|||
|
|
a reordered envelope also fails signature verification. Agree broader canonical
|
|||
|
|
encoding with flex-auth before expanding this profile.
|
|||
|
|
|
|||
|
|
## Producers, MCP and embedded hosts
|
|||
|
|
|
|||
|
|
`from_address`, `from_agent` and `author`, when present in a top-level JSON command,
|
|||
|
|
must match the live owner's producer-address set. Native events get a reserved
|
|||
|
|
`payload._hub_access` record containing verified actor/tenant/correlation identity;
|
|||
|
|
client assertions under that key are overwritten. Domain `subject_refs` remain
|
|||
|
|
business data, never proof of origin. Compatibility event implementations and
|
|||
|
|
external publishers still need owner acceptance of equivalent attribution.
|
|||
|
|
|
|||
|
|
Embedded hosts can install `AccessBoundary` and an explicit host route catalog.
|
|||
|
|
Tests prove the common seam on an embedded host; each real host's mounted paths,
|
|||
|
|
features and routers still require inventory and admission. Do not treat the
|
|||
|
|
standalone runtime catalog as admission for every embedded API.
|
|||
|
|
|
|||
|
|
MCP hosts may supply `token_provider`, a callable resolving a **Hub-audience**
|
|||
|
|
credential from the current invocation, with `require_credentials=True`. Credentials
|
|||
|
|
are never retained on the server; requests do not follow redirects when carrying
|
|||
|
|
one. `trailing_slash=False` targets the standalone runtime's native paths. The
|
|||
|
|
standalone production MCP has no human flow/provider yet and fails closed.
|
|||
|
|
Many legacy tools target APIs the standalone Hub does not implement. They remain
|
|||
|
|
unsupported, not silently translated or authorized. Cross-audience delegation,
|
|||
|
|
browser PKCE sessions/logout and real MCP root login remain open.
|
|||
|
|
|
|||
|
|
## Remaining release gates
|
|||
|
|
|
|||
|
|
1. T01: cross-owner contract review, concrete policy vocabulary, effective host and
|
|||
|
|
service-route expansion; the 250-object snapshot is not full route discovery.
|
|||
|
|
2. T02: immutable root binding, registered audience/redirects, PKCE/MFA/recovery,
|
|||
|
|
admitted live facts adapters, attended login/logout and revocation receipts.
|
|||
|
|
3. T03: dedicated Hub policy and fact provenance review; authenticated deployment,
|
|||
|
|
credential/key custody, durable audit implementation and native rotation probes.
|
|||
|
|
4. T04–T05: composed deployable runtime, dependency health probes, all client/extension
|
|||
|
|
migrations, domain outcome audit, legacy lane rollback and full root journeys.
|
|||
|
|
5. T06–T08: every platform/Railiance receipt, separate public-enable approval and
|
|||
|
|
later role/delegation/tenant isolation. No milestone is closed by local fixtures.
|