Skip to main content

Module chain

Module chain 

Source
Expand description

Delegation-chain + ceiling/attenuation validation — the core correctness component of S5 (#571).

Per the epic (#547, design “ceiling/attenuation”): every delegation in a UCAN chain must be a SUBSET (attenuation) of its delegator’s authority — a child can never widen. This module walks the proof chain of a UCAN and enforces, at each link, the two structural invariants that make the chain a genuine ceiling:

  1. Linkage: the delegate UCAN’s issuer must equal the delegator (proof) UCAN’s audience. Authority flows proof.audience → ucan.issuer; a chain where the issuer was not the party the proof delegated to is forged.
  2. Attenuation (⊆): every capability the delegate UCAN claims must be authorized by the delegator’s capability set (super::capability::set_attenuates). A delegate that widens on resource, ability, or caveats is rejected.

Plus the temporal and structural gates, which are TWO independent checks:

  • Relative window containment ([window_within]): a child cannot outlive its parent — its [not_before, expiration] window must be within the delegator’s. This bounds the chain shape but says nothing about the wall-clock.
  • Absolute validity at now (super::token::Ucan::is_valid_at): EVERY link must be live at the validation instant — not expired and not future-dated (not_before <= now <= expiration). Relative containment alone is NOT sufficient: a fully-attenuating, correctly-linked chain in which every link has already EXPIRED still satisfies window containment, so without the absolute check it would validate and could be replayed/compiled into a ceiling. Both gates are therefore enforced, per link.

And recursion to the root (a root has no proofs and grants whatever it self-asserts), with a bounded proof depth (MAX_PROOF_DEPTH) so a maliciously deep nested-proof chain cannot exhaust the stack (a DoS guard, not an authority concern).

Fail-closed everywhere. Any malformation, missing link, widening, out-of-window, expired/not-yet-valid, or over-depth condition rejects the entire chain. This is intentionally conservative TCB code: a false reject is a denied request; a false accept is a privilege escalation, so the asymmetry is always resolved toward rejection.

§Scope (milestone 1)

Signature verification is assumed already done by super::token::Ucan::verify_signatures — validate_chain covers linkage, attenuation, relative window containment, absolute validity at now, and the depth bound. Callers run signatures first, then this; the combined entry point validate does both in the correct order. Revocation lists and a richer multi-proof “any-path” model are milestone-2 seams; M1 validates the single-delegator-per-link chain (each UCAN’s proofs[i] is a delegator that must independently cover the claims).

Enums§

ChainError
Why a delegation chain was rejected. Every variant is a fail-closed denial.

Constants§

MAX_PROOF_DEPTH
Maximum delegation-chain (nested-proof) depth this validator will walk. A chain deeper than this is rejected fail-closed (ChainError::DepthExceeded) before recursion can exhaust the stack. UCAN delegation chains are short by construction (a handful of hops); this bound is generous for legitimate use while capping a hostile proofs-within-proofs nesting (a DoS vector at both parse time and walk time). The same bound is enforced at CBOR decode in super::token::Ucan::from_cbor so an over-deep token is refused before it is ever walked.

Functions§

validate
The full fail-closed validation a compiler front-end runs before lowering a UCAN into a ceiling: (1) structure, (2) signatures, (3) delegation chain + attenuation + temporal validity at now, in that order. Returns Ok(()) only if every link is structurally sound, correctly signed under the hybrid policy, properly linked, strictly attenuating, within its delegator’s window, AND live at now (not expired, not future-dated), with the chain no deeper than MAX_PROOF_DEPTH.
validate_chain
Recursively validate the delegation chain rooted at ucan (structural + temporal — run signatures separately, or use validate).