Skip to main content

Module token

Module token 

Source
Expand description

The typed UCAN token model + structural validation + hybrid-COSE signature verification (S5 / #571, milestone 1).

We control both ends of this UCAN — issuance and consumption are internal to the MAC epic — so this is a minimal, typed model rather than a full JOSE/JWT UCAN. Crucially, UCAN signing is aligned with the project’s hybrid post-quantum COSE composite (EdDSA + ML-DSA-65), not a JWT ucan crate: a UCAN is a CBOR payload signed with crate::crypto::cose_sign::sign_composite and verified with crate::crypto::cose_sign::verify_composite (require_pq = true). This keeps the whole authority chain on the same HNDL-resistant signature suite the rest of the TCB uses.

§Shape

Ucan {
  payload: UcanPayload {        // the signed bytes (canonical CBOR)
    issuer:   Did,              // did:key of the signer
    audience: Did,              // did:key of the delegate
    capabilities: [Capability], // the granted authority
    not_before / expiration: Option<u64> (unix seconds),
    nonce: ...,
  },
  proofs: [Ucan],               // the delegation chain (delegator UCANs)
  signature: Vec<u8>,           // detached hybrid-COSE composite over payload
}

Signature verification lives here. Delegation-chain + attenuation validation lives in super::chain (it is the most security-critical piece and is isolated for that reason).

Re-exports§

pub use crate::identity::Did;

Structs§

Ucan
A UCAN: a signed payload plus the proof chain of delegator UCANs.
UcanPayload
The signed body of a UCAN: everything an issuer commits to with their signature. Serialized to canonical CBOR (UcanPayload::signing_bytes) to produce the exact bytes the hybrid-COSE composite signs/verifies.

Enums§

UcanError
Errors from UCAN parsing, structure, and signature verification. All map to a fail-closed rejection at the call site.

Constants§

UCAN_AAD
Domain-separation AAD for UCAN payload signatures (distinct from the compiled-policy, approval, audit, and envelope AADs so a UCAN signature can never be replayed as another message type). Signed and verified by every producer/consumer of UCANs — the test helpers, the chain validator, the production UcanVerifier (the HTTP grant path’s trust-store-backed verifier), and cross-process consumers. Promoted to a public non-test constant by S8 (#574) so the production verifier shares the exact AAD the signers use (a mismatch silently fails signature verification).

Traits§

UcanVerifier
Resolves a UCAN issuer’s verified key material and checks a detached hybrid-COSE signature over the payload bytes.