Expand description
MAC S6 — runtime grant path: UCAN grant-request → access/refresh tokens. Part of the native-MAC program.
This is the runtime companion to S5’s compile-time UCAN→Casbin/TE compiler.
S5 compiles an approved UCAN into a ceiling (a CompiledPolicy +
SignedApproval binding) — that is the standing authorization-to-REQUEST.
S6 is the path a principal takes at runtime to turn a subset-UCAN grant
into ephemeral, sender-bound OAuth tokens (RFC 8693 token-exchange shape).
§The #547 MAC model this honours
- UCAN authors; Casbin/TE enforces. The grant presented here is a UCAN delegation chain; we never mint tokens wider than that grant.
- ZSP (Zero Standing Privilege). The ceiling is standing authorization-to-REQUEST, NOT access. Access is ephemeral (short-ttl), per-task (not per-op), and re-evaluated on refresh. There is no long-lived bearer that bypasses the grant.
- Ceiling = the grant itself. The subset-UCAN a principal presents is a
strict attenuated subset of an approved ceiling. The grant’s root
capabilities ARE the ceiling for this request;
authorize(grant, request)is the ceiling-subset check. - Fail-closed / single path. Every failure mode — bad chain, over-ceiling request, insufficient MAC clearance, missing sender-binding — denies. There is no fallback path: a fallback is a downgrade vector. Authority being unreachable is a denial, not a reason to mint a narrower token.
- Escalation ≠ auto-widen. A request beyond the grant’s ceiling is a
denial pending a ceiling amendment (the tiered decision — static Casbin
/ agentic / admin-UDF — which is authority-owned and MAC-bounded). S6 does
NOT auto-escalate; it routes to
Decision::Escalateand returnsinsufficient_scope. The amendment flow is deferred (TODO locations below).
§What this module owns (and what it does NOT)
Owns (the fail-closed core):
- Validate the presented UCAN grant chain (delegates to S5’s
hyprstream_rpc::auth::ucan::chain::validate— signatures + attenuation + temporal validity at the trustednow). - Ceiling-subset check: the access being requested now must be authorized
by the grant’s capabilities ([
mac::compiler::authorize]). - MAC clearance gate: the principal’s clearance (from verified key
material / S1
SubjectContextClaims) must dominate the request’s label. Insufficient clearance ⇒ deny (the S1 floor, reused — not reinvented). - Compose the subset of capabilities the token will actually carry (never the whole grant — ZSP: mint the least subset that covers the requested access).
Does NOT own (consumed from siblings — no parallel implementation):
- UCAN chain validation, attenuation, signature verification → S5
(
hyprstream_rpc::auth::ucan). - The grant-vs-request authorization relation → S5’s compiler
([
mac::compiler::authorize]). - Security labels, clearance, dominance → S1 (
hyprstream_rpc::auth::mac). - DPoP sender-binding (#514/#515) →
services::oauth::dpop. - JWT signing →
services::oauth(viahyprstream_rpc::auth::jwt). - Hybrid-PQC signing of the minted tokens → S8 (#574) landed: the
mint_grant_tokenpath now signs via the hybrid composite JWT (encode_composite_ml_dsa_65_ed25519) when an ML-DSA-65 key is provisioned, matching the hybrid signature on the UCAN/approval it consumes. Classical Ed25519 is the explicit policy-selected fallback.
§Scope of this PR (core, sound, tested) vs. deferred
In scope: the pure fail-closed core — grant validation, ceiling-subset
check, MAC clearance gate, sender-binding requirement, and the
GrantDecision it produces. Plus full negative-test coverage (over-ceiling,
bad chain, insufficient clearance, missing DPoP). The HTTP grant wiring and
token minting live in services::oauth::token_exchange and call into
evaluate_grant here.
Deferred (fail-closed until landed):
- Full escalation tiers (static Casbin / agentic / admin-UDF amendment) —
see
GrantDecision::Escalate. - Refresh-token rotation with re-evaluation plumbing end-to-end (the
evaluate_grantcall on refresh is wired; rotation storage is the OAuth layer’s job).
Revocation propagation into the grant path (the former
TODO(#572-revocation)) is closed by construction: every credential the
grant path mints carries an issuer-scoped jti and is checked against the
canonical revocation authority at every verification point; interactive
refresh chains carry a session ID whose revocation prevents refresh
without consuming the credential; and UCAN-grant refresh entries are
single-use, re-evaluated here, and deletable through /oauth/revoke.
Structs§
- Grant
Request - A resolved grant request: the principal’s desired access, parsed off the
token-exchange
resource/scopeform fields into the S5 capability shape so the compiler’sauthorizecan evaluate it. - Granted
Access - The minimum subset of the grant a minted token will carry — the ZSP output.
Enums§
- Grant
Decision - The outcome of evaluating a grant request: the fail-closed “mint” decision.
- Grant
Error - Why a grant request was denied. Every variant is fail-closed; there is no “best-effort” or “narrow-and-continue” outcome. The cardinal rule of #547: authority-unreachable ⇒ deny, never downgrade.
Constants§
- MAX_
ACCESS_ TOKEN_ TTL_ SECS - Hard ceiling on the access-token TTL minted from a UCAN grant. ZSP: grant
tokens are deliberately short-lived so the re-evaluation-on-refresh property
has teeth. The OAuth layer clamps its configured
token_ttldown to this. - UCAN_
GRANT_ TOKEN_ TYPE - The token-type URI identifying a UCAN grant as the RFC 8693
subject_token.
Functions§
- audited_
evaluate_ grant - As
evaluate_grant, but records a tamper-evident [AuditRecord] of the outcome throughsinkbefore returning — S7’s complete-mediation guarantee extended to the grant path (B2, #674). This is the mint-path entry point production code should call; the plainevaluate_grantis the unaudited core the gate tests exercise directly. - audited_
evaluate_ refresh - As
evaluate_refresh, with the same audit-then-decide wrapping asaudited_evaluate_grant. The refresh path’s audit records are indistinguishable in shape from the mint path’s (both are grant-path decisions); the caller distinguishes them by context if needed. - evaluate_
grant - Evaluate a UCAN grant request: the single fail-closed S6 path.
- evaluate_
refresh - Re-evaluate a grant on token refresh: the ZSP “access is re-evaluated on refresh” property.
- subject_
context - Resolve the S1
SecurityContextfor a UCAN grant’s audience from aSubjectContextClaimsimplementation.