Skip to main content

hyprstream_rpc/auth/ucan/
mod.rs

1//! **UCAN → Casbin/TE compiler foundation** — S5 / #571 of the native-MAC epic
2//! (#547), milestone 1: the vocabulary-INDEPENDENT core.
3//!
4//! ## The design (epic #547, decided)
5//!
6//! UCAN is the **authoring / delegation source language**; Casbin/TE is the
7//! **compiled enforcement**. An approved UCAN compiles *deterministically and
8//! faithfully* into a Casbin/TE bundle that is a **ceiling**. A signed
9//! `(UCAN, bundle_hash)` binding ([`approval`]) cryptographically ties the bundle
10//! to the reviewed UCAN, so a compiler bug can never produce a bundle that
11//! exceeds what was reviewed (design §14 containment backstop). Object labels and
12//! the MAC floor come from manifests (S1), **never** from the UCAN — the compiler
13//! produces the *grant ceiling*, not object labels.
14//!
15//! ```text
16//!  authoring (control plane)                       enforcement (S4 data plane)
17//!  ─────────────────────────                       ───────────────────────────
18//!  UCAN delegation chain                            CompiledPolicy { TeMatrix, lattice, generation }
19//!     │  verify_signatures (hybrid COSE)               ▲
20//!     │  validate_chain (linkage + ATTENUATION ⊆)      │ PolicyLoader verifies ONCE
21//!     ▼                                                │ + approval hash-match
22//!  validated ceiling ──[emit, M2 seam]──► bundle ──► policy_hash (BLAKE3)
23//!     │                                                ▲
24//!     └──► SignedApproval{ ucan_cid, generation, ─────┘
25//!          bundle_hash }   (hybrid EdDSA+ML-DSA-65)
26//! ```
27//!
28//! ## Module layout
29//!
30//! - [`capability`] — the typed [`Capability`] `(resource, ability, caveats)` and
31//!   the **attenuation (⊆)** relation. Vocabulary-independent; structural.
32//! - [`token`] — the typed [`Ucan`] model, CBOR parse, structural validation, and
33//!   **hybrid-COSE signature verification** (EdDSA + ML-DSA-65). Minimal model
34//!   (we control both ends), aligned with the project crypto — NOT a JWT `ucan`
35//!   crate.
36//! - [`chain`] — **delegation-chain + ceiling/attenuation validation**. The most
37//!   security-critical component: walks the proof chain and rejects any widening,
38//!   broken linkage, or window escape. Fail-closed.
39//! - [`approval`] — the signed `(UCAN, bundle_hash)` [`approval::ApprovalBinding`],
40//!   binding the [`SecurityLabel`](crate::auth::mac) lattice generation too,
41//!   signed with hybrid COSE. Its `bundle_hash` is exactly S4's
42//!   `CompiledPolicy::policy_hash()` so it drops into the S4 loader's
43//!   `PolicyApproval`.
44//!
45//! ## Relationship to S4 (#570/#583)
46//!
47//! S4's PDP (in the `hyprstream` crate, `mac::compiled::CompiledPolicy`) is the
48//! consumer of the compiler's output. The compiled policy is a
49//! `hyprstream::mac::TeMatrix` wrapped in a `CompiledPolicy` whose
50//! `generation == LatticeVersion::generation()` and whose `policy_hash()` is the
51//! hash this module's approval binds. The compiler lives in the `hyprstream` crate
52//! because it needs the TE types; the UCAN model here needs only S1 + crypto.
53
54pub mod approval;
55pub mod capability;
56pub mod chain;
57pub mod token;
58
59pub use approval::{ucan_cid, ApprovalBinding, ApprovalError, SignedApproval, APPROVAL_AAD};
60pub use capability::{set_attenuates, Ability, Capability, CaveatValue, Caveats, Resource};
61pub use chain::{validate, validate_chain, ChainError};
62pub use token::{Did, Ucan, UcanError, UcanPayload, UcanVerifier};