Skip to main content

Module exchange

Module exchange 

Source
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::Escalate and returns insufficient_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 trusted now).
  • 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 (via hyprstream_rpc::auth::jwt).
  • Hybrid-PQC signing of the minted tokens → S8 (#574) landed: the mint_grant_token path 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_grant call 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§

GrantRequest
A resolved grant request: the principal’s desired access, parsed off the token-exchange resource/scope form fields into the S5 capability shape so the compiler’s authorize can evaluate it.
GrantedAccess
The minimum subset of the grant a minted token will carry — the ZSP output.

Enums§

GrantDecision
The outcome of evaluating a grant request: the fail-closed “mint” decision.
GrantError
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_ttl down 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 through sink before 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 plain evaluate_grant is the unaudited core the gate tests exercise directly.
audited_evaluate_refresh
As evaluate_refresh, with the same audit-then-decide wrapping as audited_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 SecurityContext for a UCAN grant’s audience from a SubjectContextClaims implementation.