Skip to main content

Module ucan

Module ucan 

Source
Expand description

UCAN → Casbin/TE compiler foundation (S5, #571): the UCAN token model, delegation-chain + ceiling/attenuation validation, and the signed (UCAN, bundle_hash) approval binding (hybrid EdDSA + ML-DSA-65 COSE). UCAN → Casbin/TE compiler foundation — S5 / #571 of the native-MAC epic (#547), milestone 1: the vocabulary-INDEPENDENT core.

§The design (epic #547, decided)

UCAN is the authoring / delegation source language; Casbin/TE is the compiled enforcement. An approved UCAN compiles deterministically and faithfully into a Casbin/TE bundle that is a ceiling. A signed (UCAN, bundle_hash) binding ([approval]) cryptographically ties the bundle to the reviewed UCAN, so a compiler bug can never produce a bundle that exceeds what was reviewed (design §14 containment backstop). Object labels and the MAC floor come from manifests (S1), never from the UCAN — the compiler produces the grant ceiling, not object labels.

 authoring (control plane)                       enforcement (S4 data plane)
 ─────────────────────────                       ───────────────────────────
 UCAN delegation chain                            CompiledPolicy { TeMatrix, lattice, generation }
    │  verify_signatures (hybrid COSE)               ▲
    │  validate_chain (linkage + ATTENUATION ⊆)      │ PolicyLoader verifies ONCE
    ▼                                                │ + approval hash-match
 validated ceiling ──[emit, M2 seam]──► bundle ──► policy_hash (BLAKE3)
    │                                                ▲
    └──► SignedApproval{ ucan_cid, generation, ─────┘
         bundle_hash }   (hybrid EdDSA+ML-DSA-65)

§Module layout

  • [capability] — the typed Capability (resource, ability, caveats) and the attenuation (⊆) relation. Vocabulary-independent; structural.
  • [token] — the typed Ucan model, CBOR parse, structural validation, and hybrid-COSE signature verification (EdDSA + ML-DSA-65). Minimal model (we control both ends), aligned with the project crypto — NOT a JWT ucan crate.
  • [chain] — delegation-chain + ceiling/attenuation validation. The most security-critical component: walks the proof chain and rejects any widening, broken linkage, or window escape. Fail-closed.
  • [approval] — the signed (UCAN, bundle_hash) [approval::ApprovalBinding], binding the SecurityLabel lattice generation too, signed with hybrid COSE. Its bundle_hash is exactly S4’s CompiledPolicy::policy_hash() so it drops into the S4 loader’s PolicyApproval.

§Relationship to S4 (#570/#583)

S4’s PDP (in the hyprstream crate, mac::compiled::CompiledPolicy) is the consumer of the compiler’s output. The compiled policy is a hyprstream::mac::TeMatrix wrapped in a CompiledPolicy whose generation == LatticeVersion::generation() and whose policy_hash() is the hash this module’s approval binds. The compiler lives in the hyprstream crate because it needs the TE types; the UCAN model here needs only S1 + crypto.

Re-exports§

pub use approval::ucan_cid;
pub use approval::ApprovalBinding;
pub use approval::ApprovalError;
pub use approval::SignedApproval;
pub use approval::APPROVAL_AAD;
pub use capability::set_attenuates;
pub use capability::Ability;
pub use capability::Capability;
pub use capability::CaveatValue;
pub use capability::Caveats;
pub use capability::Resource;
pub use chain::validate;
pub use chain::validate_chain;
pub use chain::ChainError;
pub use token::Did;
pub use token::Ucan;
pub use token::UcanError;
pub use token::UcanPayload;
pub use token::UcanVerifier;

Modules§

approval
The signed (UCAN, bundle_hash) approval binding (S5 / #571).
capability
The typed capability — a single (resource, ability) grant — and the attenuation (⊆) relation that is the core ceiling invariant of S5 (#571).
chain
Delegation-chain + ceiling/attenuation validation — the core correctness component of S5 (#571).
token
The typed UCAN token model + structural validation + hybrid-COSE signature verification (S5 / #571, milestone 1).