Skip to main content

Module approval

Module approval 

Source
Expand description

The signed (UCAN, bundle_hash) approval binding (S5 / #571).

This is the containment backstop of the whole compiler design (#547, design §14): an approved UCAN is cryptographically tied to the hash of the bundle it compiles to, so a compiler bug can never produce a bundle that exceeds what was reviewed. The reviewer approves a specific (UCAN, lattice generation, bundle_hash) triple; the policy loader (S4 compiled::PolicyLoader) then accepts ONLY a compiled policy whose recomputed hash matches an approval for its generation.

§What this binds, and why those three things

  • ucan_cid — the content hash (BLAKE3 of canonical CBOR) of the approved UCAN. Ties the approval to the exact delegation that was reviewed; re-issuing or mutating the UCAN changes the CID.
  • generation — the [LatticeVersion] generation the bundle is valid for. Binding it prevents replaying an approval under a different lattice version whose compartment bits mean something else (the same desync guard S4 enforces; design §14 crypto/policy-agility).
  • bundle_hash — the [u8; 32] BLAKE3 hash of the compiled bundle. This is exactly the value S4’s CompiledPolicy::policy_hash() produces and compiled::PolicyApproval::approved_hash consumes, so an ApprovalBinding minted here drops straight into the S4 loader once bundle emission (milestone 2) is wired.

§Signing: hybrid COSE, NEVER Ed25519-only

The binding is signed with the project’s hybrid post-quantum COSE composite (EdDSA + ML-DSA-65) via crate::crypto::cose_sign::sign_composite and verified with require_pq = true. A classical-only signature is rejected (fail-closed) — an approval is a long-lived authority artifact and is exactly the kind of confidentiality/integrity-critical object the hybrid-PQC plan requires to resist harvest-now-decrypt-later forgery.

Structs§

ApprovalBinding
The reviewed binding: the approved UCAN’s CID, the lattice generation it is valid for, and the hash of the bundle it compiles to. These are the bytes the hybrid-COSE signature covers (see ApprovalBinding::signing_payload).
SignedApproval
A signed approval: the binding plus a detached hybrid-COSE composite signature over its ApprovalBinding::signing_payload. This is the artifact a reviewer/authority emits and the policy loader consumes.

Enums§

ApprovalError
Errors from approval construction / signing / verification. All fail-closed.

Constants§

APPROVAL_AAD
Domain-separation AAD for approval-binding signatures. Distinct from the UCAN payload AAD (hs-mac-ucan-payload-v1), the compiled-policy AAD (hs-mac-compiled-policy-v1), and envelope AADs, so an approval signature can never be confused with — or replayed as — any other signed object.

Functions§

ucan_cid
BLAKE3 content id of a UCAN: hash of its canonical CBOR encoding. The same codec the rest of the MAC stack uses, so the CID is stable across processes.