@agenticprimitives/delegation 1.0.0-alpha.4 → 1.0.0-alpha.40

package/dist/token.js

@@ -1,3 +1,4 @@
+import { ERC1271_MAGIC_VALUE as ERC1271_MAGIC } from '@agenticprimitives/types';
 // DelegationToken envelope (per spec 202 §4):
 //   base64url(canonicalJSON(claims)) + '.' + base64url(sessionKeySig)
 //
@@ -10,30 +11,58 @@
 //   6. evaluateCaveats (fail-closed) — pass toolName via opts for tool-scope
 //   7. atomic JTI usage tracking
 //   8. return { principal: delegator }
-import { secp256k1 } from '@noble/curves/secp256k1';
-import { keccak_256 } from '@noble/hashes/sha3';
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { keccak_256 } from '@noble/hashes/sha3.js';
 import { createPublicClient, http } from 'viem';
-import { hashDelegation } from './hash';
-import { evaluateCaveats } from './evaluator';
+import { hashDelegation } from './hash.js';
+import { evaluateCaveats } from './evaluator.js';
+import { DATA_SCOPE_ENFORCER, decodeDataScopeTerms, VAULT_RECORD_SCOPE_ENFORCER, decodeVaultRecordScopeTerms, readSessionAudience } from './caveats.js';
+import { verifyUniversalSignature } from './onchain.js';
+import { verifyOffChainQuorum } from './quorum.js';
 import { buildEvent } from '@agenticprimitives/audit';
 // ─── base64url + canonical JSON helpers ──────────────────────────────────
-function base64urlEncode(s) {
-    return Buffer.from(s, 'utf8').toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+//
+// ISOMORPHIC base64 — `btoa`/`atob` + `TextEncoder/Decoder` are available in every target runtime
+// (browser, Cloudflare Workers, Node ≥16). Node's `Buffer` is NOT defined in the browser, and demo-jp
+// now mints tokens CLIENT-SIDE (spec 270 v4 client-mint), so a `Buffer.from(...)` here threw
+// `ReferenceError: Buffer is not defined` before any network call. The byte output is identical to the
+// old Buffer path (standard base64), so existing signatures still verify — byte-stability is a SECURITY
+// invariant (see `canonicalJSON`), and standard base64 is the same across all runtimes.
+function bytesToBase64url(bytes) {
+    let bin = '';
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
 }
-function base64urlDecodeStr(s) {
+function base64urlToBytes(s) {
     let padded = s.replace(/-/g, '+').replace(/_/g, '/');
     while (padded.length % 4)
         padded += '=';
-    return Buffer.from(padded, 'base64').toString('utf8');
+    const bin = atob(padded);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+function base64urlEncode(s) {
+    return bytesToBase64url(new TextEncoder().encode(s));
+}
+function base64urlDecodeStr(s) {
+    return new TextDecoder().decode(base64urlToBytes(s));
 }
 function base64urlEncodeBytes(b) {
-    return Buffer.from(b).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    return bytesToBase64url(b);
 }
 function base64urlDecodeBytes(s) {
-    let padded = s.replace(/-/g, '+').replace(/_/g, '/');
-    while (padded.length % 4)
-        padded += '=';
-    return new Uint8Array(Buffer.from(padded, 'base64'));
+    return base64urlToBytes(s);
+}
+/** Isomorphic hex → bytes (replaces `Buffer.from(hex, 'hex')`, which is Node-only). */
+function hexToBytes(hex) {
+    const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const out = new Uint8Array(clean.length >> 1);
+    for (let i = 0; i < out.length; i++)
+        out[i] = parseInt(clean.substr(i * 2, 2), 16);
+    return out;
 }
 /** Sorted-key JSON; BigInt → numeric string. Both sides must produce the
  *  exact same bytes for the signature to round-trip.
@@ -44,7 +73,19 @@ function base64urlDecodeBytes(s) {
  *  claims hash to different signatures, breaking token verification
  *  silently. */
 export function canonicalJSON(value) {
-    const seen = new WeakSet();
+    // The cycle guard tracks the ANCESTOR PATH, not everything ever visited. A value reachable twice through
+    // DIFFERENT branches is a shared reference — ordinary JSON that must serialize twice — while only a value
+    // containing ITSELF is circular. A visited-set conflates the two: it rejected a payload holding a card
+    // release beside the draft it was cut from (the release shallow-copies the card, so both share the same
+    // nested `capabilities` / `skills` / `supportedInterfaces` objects), which surfaced to the user as
+    // "circular reference" on a first release. Arrays are guarded too — an array containing itself would
+    // otherwise recurse until the stack died, which is a worse failure than the error it should raise.
+    const path = new WeakSet();
+    const enter = (v) => {
+        if (path.has(v))
+            throw new Error('canonicalJSON: circular reference');
+        path.add(v);
+    };
     const stringify = (v) => {
         if (v === null)
             return 'null';
@@ -57,16 +98,19 @@ export function canonicalJSON(value) {
         if (typeof v === 'string')
             return JSON.stringify(v);
         if (Array.isArray(v)) {
-            return '[' + v.map((x) => (x === undefined ? 'null' : stringify(x))).join(',') + ']';
+            enter(v);
+            const out = '[' + v.map((x) => (x === undefined ? 'null' : stringify(x))).join(',') + ']';
+            path.delete(v);
+            return out;
         }
         if (typeof v === 'object') {
-            if (seen.has(v))
-                throw new Error('canonicalJSON: circular reference');
-            seen.add(v);
             const obj = v;
+            enter(obj);
             // Drop undefined keys (standard JSON behavior).
             const keys = Object.keys(obj).filter((k) => obj[k] !== undefined).sort();
-            return '{' + keys.map((k) => JSON.stringify(k) + ':' + stringify(obj[k])).join(',') + '}';
+            const out = '{' + keys.map((k) => JSON.stringify(k) + ':' + stringify(obj[k])).join(',') + '}';
+            path.delete(obj);
+            return out;
         }
         throw new Error(`canonicalJSON: unsupported type ${typeof v}`);
     };
@@ -90,7 +134,7 @@ function recoverEoaFromEip191Sig(message, signature) {
     const recovery = v >= 27 ? v - 27 : v;
     const eipSig = new secp256k1.Signature(r, s).addRecoveryBit(recovery);
     const digest = eip191Digest(message);
-    const pub = eipSig.recoverPublicKey(digest).toRawBytes(false);
+    const pub = eipSig.recoverPublicKey(digest).toBytes(false);
     const hash = keccak_256(pub.slice(1));
     let hex = '0x';
     for (const b of hash.slice(12))
@@ -148,6 +192,8 @@ export async function mintDelegationToken(claims, signMessage, opts) {
         sub: claims.sub,
         delegation: claims.delegation,
         sessionKeyAddress: claims.sessionKeyAddress,
+        // DEL-001: carry the session-delegate-binding leaf when the minter produced one.
+        ...(claims.sessionDelegation ? { sessionDelegation: claims.sessionDelegation } : {}),
         jti,
         iat,
         exp,
@@ -156,31 +202,31 @@ export async function mintDelegationToken(claims, signMessage, opts) {
     const canonical = canonicalJSON(full);
     const sig = await signMessage(canonical);
     const sigHex = sig.startsWith('0x') ? sig.slice(2) : sig;
-    const sigBytes = new Uint8Array(Buffer.from(sigHex, 'hex'));
+    const sigBytes = hexToBytes(sigHex);
     const token = `${base64urlEncode(canonical)}.${base64urlEncodeBytes(sigBytes)}`;
-    // Audit emit (C3 pass 3c). Fail-soft. JTI is logged because it's the
+    // Audit emit (C3 pass 3c). R11.1 / N16: NO try/catch around the sink
+    // write — the sink composition (`composeSinks` fail-soft vs
+    // `composeFailHardSinks` fail-hard) expresses the caller's intent.
+    // For production callers using fail-hard sinks, a `delegation.mint`
+    // emission failure aborts the mint flow — the token is NOT returned
+    // without a recorded audit row. JTI is logged because it's the
     // correlation primitive for downstream verify events — not secret.
     if (opts?.auditSink) {
-        try {
-            await opts.auditSink.write(buildEvent({
-                action: 'delegation.mint',
-                outcome: 'success',
-                correlationId: opts.correlationId,
-                actor: { type: 'user', id: claims.delegation.delegator },
-                subject: { type: 'jti', id: jti },
-                audience: claims.aud,
-                context: {
-                    iss: claims.iss,
-                    sub: claims.sub,
-                    sessionKeyAddress: claims.sessionKeyAddress,
-                    ttlSeconds: ttl,
-                    usageLimit: claims.usageLimit ?? null,
-                },
-            }));
-        }
-        catch {
-            /* fail-soft */
-        }
+        await opts.auditSink.write(buildEvent({
+            action: 'delegation.mint',
+            outcome: 'success',
+            correlationId: opts.correlationId,
+            actor: { type: 'user', id: claims.delegation.delegator },
+            subject: { type: 'jti', id: jti },
+            audience: claims.aud,
+            context: {
+                iss: claims.iss,
+                sub: claims.sub,
+                sessionKeyAddress: claims.sessionKeyAddress,
+                ttlSeconds: ttl,
+                usageLimit: claims.usageLimit ?? null,
+            },
+        }));
     }
     return { token, jti };
 }
@@ -206,16 +252,34 @@ const ACCOUNT_ABI_ERC1271 = [
         outputs: [{ name: '', type: 'bytes4' }],
     },
 ];
+/** spec 270 v4 — the deployed UniversalSignatureValidator: ONE connection-agnostic surface that validates
+ *  a signature for a deployed SA (ERC-1271), a counterfactual SA (ERC-6492 deploy-on-verify), or a raw EOA
+ *  (ECDSA). `isValidSig` is state-changing on-chain (the 6492 path may deploy), but we call it via
+ *  `eth_call` — marking it `view` here makes viem `readContract` execute it ephemerally + decode the bool,
+ *  the standard off-chain ERC-6492 pattern. Routing the delegation + leaf checks through this is what makes
+ *  the verifier never branch on HOW the user connected — every credential strategy validates via one surface. */
+const UNIVERSAL_SIG_VALIDATOR_ABI = [
+    {
+        type: 'function',
+        name: 'isValidSig',
+        stateMutability: 'view',
+        inputs: [
+            { name: 'signer', type: 'address' },
+            { name: 'hash', type: 'bytes32' },
+            { name: 'sig', type: 'bytes' },
+        ],
+        outputs: [{ name: '', type: 'bool' }],
+    },
+];
 const ACCEPTED_SESSION_DELEGATION_ABI = [
     {
         type: 'function',
-        name: 'isAcceptedSessionDelegation',
+        name: 'hasAcceptedSessionDelegation',
         stateMutability: 'view',
         inputs: [{ name: 'sessionDelegationHash', type: 'bytes32' }],
         outputs: [{ name: '', type: 'bool' }],
     },
 ];
-const ERC1271_MAGIC = '0x1626ba7e';
 function decodeToken(token) {
     const parts = token.split('.');
     if (parts.length !== 2)
@@ -239,6 +303,37 @@ function decodeToken(token) {
         sigHex += b.toString(16).padStart(2, '0');
     return { claims, canonical, signature: sigHex };
 }
+/**
+ * DEL-001 (spec 270 v4) — the chain-free part of the session-key binding (testable without an RPC).
+ * Returns an error reason, or `null` when the leaf links correctly: `sessionDelegation` present, its
+ * delegator is the outer delegation's DELEGATOR (the principal's SA — the canonical identity every
+ * connection strategy signs for), and its delegate is the presenting session key. The signature proof
+ * (the delegator SA authorized the leaf — validated via the UniversalSignatureValidator, so any
+ * credential type works) is checked separately in `verifyDelegationToken`.
+ *
+ * v4 binds to the DELEGATOR (was the delegate in v3): the SA's own authority — recoverable at connect
+ * under every credential strategy alike — vouches for the session key.
+ */
+export function sessionDelegateBindingError(delegation, sessionDelegation, sessionKeyAddress) {
+    if (!sessionDelegation)
+        return 'session-delegation required (DEL-001)';
+    if (sessionDelegation.delegator.toLowerCase() !== delegation.delegator.toLowerCase()) {
+        return 'session-delegation delegator != delegation delegator (DEL-001)';
+    }
+    if (sessionDelegation.delegate.toLowerCase() !== sessionKeyAddress.toLowerCase()) {
+        return 'session key is not the session-delegation delegate (DEL-001)';
+    }
+    // Spec 408 §2.1 (R917-P-2) — THE ROOT'S DELEGATE IS BOUND. The leaf names the delegates this session key
+    // may present the principal's delegations to; a delegation to anyone else is refused, however valid it
+    // is on its own. A leaf that names nobody is refused outright: no knob re-admits the old shape.
+    const audience = readSessionAudience(sessionDelegation.caveats);
+    if (!audience)
+        return 'session-delegation names no audience — a leaf must say which delegates it may present to (spec 408 §2.1)';
+    if (!audience.includes(delegation.delegate.toLowerCase())) {
+        return `session-delegation does not admit presenting to ${delegation.delegate} — the leaf was issued for other delegates (spec 408 §2.1)`;
+    }
+    return null;
+}
 /**
  * Full verification pipeline. Caller passes `toolName` in opts for tool-scope
  * caveat evaluation; without it the mcp-tool-scope caveat denies.
@@ -249,27 +344,24 @@ export async function verifyDelegationToken(token, opts) {
     const emit = async (outcome, reason, principal, delegationDigest) => {
         if (!opts.auditSink)
             return;
-        try {
-            await opts.auditSink.write(buildEvent({
-                action: outcome === 'success'
-                    ? 'delegation.verify.accept'
-                    : 'delegation.verify.reject',
-                outcome,
-                correlationId: opts.correlationId,
-                actor: principal ? { type: 'user', id: principal } : { type: 'unknown' },
-                subject: delegationDigest
-                    ? { type: 'delegation', id: delegationDigest }
-                    : undefined,
-                audience: opts.audience,
-                chainId: opts.chainId,
-                digest: delegationDigest,
-                reason,
-                context: opts.toolName ? { tool: opts.toolName } : undefined,
-            }));
-        }
-        catch {
-            /* fail-soft */
-        }
+        // R11.1 / N16: NO try/catch — sink composition determines fail-hard
+        // vs fail-soft. See `mintDelegationToken` doc-comment for rationale.
+        await opts.auditSink.write(buildEvent({
+            action: outcome === 'success'
+                ? 'delegation.verify.accept'
+                : 'delegation.verify.reject',
+            outcome,
+            correlationId: opts.correlationId,
+            actor: principal ? { type: 'user', id: principal } : { type: 'unknown' },
+            subject: delegationDigest
+                ? { type: 'delegation', id: delegationDigest }
+                : undefined,
+            audience: opts.audience,
+            chainId: opts.chainId,
+            digest: delegationDigest,
+            reason,
+            context: opts.toolName ? { tool: opts.toolName } : undefined,
+        }));
     };
     const rejectWith = async (reason, principal, delegationDigest) => {
         await emit('denied', reason, principal, delegationDigest);
@@ -297,6 +389,14 @@ export async function verifyDelegationToken(token, opts) {
     }
     // 2. EIP-712 hash
     const eip712Hash = hashDelegation(claims.delegation, opts.chainId, opts.delegationManager);
+    // NEW-DELEGATION-JTI-AMP-1: short-circuit a REPLAYED token (already at its usage limit) BEFORE the on-chain
+    // read set (sig + isRevoked + acceptance) — otherwise a replay amplifies each verify into several eth_calls
+    // (DoS) only to be rejected by the JTI dedup below. Read-only peek; a store without it keeps the old order.
+    if (claims.jti && opts.jtiStore.peekConsumed) {
+        if (await opts.jtiStore.peekConsumed(claims.jti, claims.usageLimit ?? 10)) {
+            return rejectWith('jti already consumed');
+        }
+    }
     // 3. on-chain checks
     const requireDeployed = opts.requireDeployed ?? true;
     // H7-B.9 / XPKG-005: default fail-CLOSED regardless of runtime. The
@@ -305,46 +405,210 @@ export async function verifyDelegationToken(token, opts) {
     // permissive behavior MUST set `revocationFailMode: 'open'` explicitly.
     const revocationFailMode = opts.revocationFailMode ?? 'closed';
     const publicClient = createPublicClient({ transport: http(opts.rpcUrl) });
-    try {
-        const revoked = (await publicClient.readContract({
-            address: opts.delegationManager,
-            abi: DELEGATION_MANAGER_ABI,
-            functionName: 'isRevoked',
-            args: [eip712Hash],
-        }));
-        if (revoked) {
-            return rejectWith('delegation revoked', claims.delegation.delegator, eip712Hash);
+    // spec 270 v4 — validate an SA's signature through the UniversalSignatureValidator (one surface for
+    // ERC-1271 / ERC-6492 / ECDSA), called via eth_call. `null` when no USV is configured (legacy path).
+    const validateSaSig = opts.universalSignatureValidator
+        ? async (signer, hash, sig) => (await publicClient.readContract({
+            address: opts.universalSignatureValidator,
+            abi: UNIVERSAL_SIG_VALIDATOR_ABI,
+            functionName: 'isValidSig',
+            args: [signer, hash, sig],
+        }))
+        : null;
+    // spec 289 §5 (W3) — validate an SA signature through the resilient, evidence-bearing port when a
+    // `chainSignatureReader` is injected. The port surfaces FACTS ({valid, deployed}); this closure keeps
+    // the POLICY: fail-closed/throw → reject (signature is critical); !valid → reject; requireDeployed &&
+    // !deployed → reject (counterfactual needs explicit requireDeployed=false). Returns null on success,
+    // else a rejection reason. Used by BOTH signature sites below.
+    const validateSaSigViaReader = async (signer, hash, sig) => {
+        let valid = false;
+        let deployed = false;
+        let failClosed = false;
+        try {
+            const r = await opts.chainSignatureReader.verifySmartAgentSignature({ signer, digest: hash, signature: sig });
+            valid = r.valid;
+            deployed = r.deployed;
+            failClosed = r.evidence?.source?.startsWith('fail-closed') ?? false;
         }
-    }
-    catch (e) {
-        if (revocationFailMode === 'closed') {
-            return rejectWith('revocation check unavailable; refusing to verify (set revocationFailMode=open only for explicit dev/demo paths)', claims.delegation.delegator, eip712Hash);
+        catch {
+            // A throwing reader is itself an unconfirmable signature check.
+            failClosed = true;
         }
-        void e;
-    }
-    try {
-        const code = await publicClient.getCode({ address: claims.delegation.delegator });
-        const isDeployed = !!(code && code !== '0x' && code.length > 2);
-        if (!isDeployed) {
-            if (requireDeployed) {
-                return rejectWith(`delegator smart account ${claims.delegation.delegator} is not deployed — cannot verify ERC-1271. Set verifyDelegationToken opt requireDeployed=false only for explicit counterfactual-demo use cases.`, claims.delegation.delegator, eip712Hash);
+        if (failClosed)
+            return 'signature check unavailable; refusing to verify';
+        if (!valid)
+            return 'signature validation failed';
+        if (requireDeployed && !deployed) {
+            return 'delegator smart account is not deployed — cannot honor requireDeployed. Set verifyDelegationToken opt requireDeployed=false only for explicit counterfactual-demo use cases.';
+        }
+        return null;
+    };
+    // DEL-002 (seam audit): the SAME fail-closed revocation check, applied to a given delegation hash so it
+    // can gate BOTH the root delegation AND the DEL-001 session-delegation LEAF. Returns a rejection reason
+    // or null. spec 289 §5: the resilient reader is fail-closed by construction (an unconfirmable read comes
+    // back revoked:true with evidence.source='fail-closed:*'); map that to the inline read's RPC-throw —
+    // reject under 'closed', tolerate under 'open'.
+    const revocationRejection = async (hash) => {
+        if (opts.chainRevocationReader) {
+            let revoked = true;
+            let failClosed = false;
+            try {
+                const r = await opts.chainRevocationReader.isDelegationRevoked(hash);
+                revoked = r.revoked;
+                failClosed = r.evidence?.source?.startsWith('fail-closed') ?? false;
+            }
+            catch {
+                revoked = true;
+                failClosed = true;
             }
-            // Tolerated: caller opted into the undeployed path explicitly.
+            if (revoked) {
+                if (failClosed && revocationFailMode === 'open')
+                    return null; // dev/demo tolerates an unconfirmable read
+                return failClosed
+                    ? 'revocation check unavailable; refusing to verify (set revocationFailMode=open only for explicit dev/demo paths)'
+                    : 'delegation revoked';
+            }
+            return null;
         }
-        else {
+        try {
+            const revoked = (await publicClient.readContract({
+                address: opts.delegationManager,
+                abi: DELEGATION_MANAGER_ABI,
+                functionName: 'isRevoked',
+                args: [hash],
+            }));
+            return revoked ? 'delegation revoked' : null;
+        }
+        catch (e) {
+            void e;
+            return revocationFailMode === 'closed'
+                ? 'revocation check unavailable; refusing to verify (set revocationFailMode=open only for explicit dev/demo paths)'
+                : null;
+        }
+    };
+    // THE ROOT'S SIGNATURE — one of three surfaces, the same policy. Returns a rejection reason or null.
+    const rootSignatureRejection = async () => {
+        if (opts.chainSignatureReader) {
+            // spec 289 §5 (W3) — main delegator signature through the resilient port.
+            return validateSaSigViaReader(claims.delegation.delegator, eip712Hash, claims.delegation.signature);
+        }
+        if (validateSaSig) {
+            // spec 270 v4 — one connection-agnostic surface; counterfactual delegators verify via ERC-6492, so
+            // no requireDeployed hard-reject.
+            try {
+                if (!(await validateSaSig(claims.delegation.delegator, eip712Hash, claims.delegation.signature))) {
+                    return 'signature validation failed';
+                }
+                return null;
+            }
+            catch (e) {
+                return `signature validation reverted: ${e instanceof Error ? e.message : e}`;
+            }
+        }
+        try {
+            const code = await publicClient.getCode({ address: claims.delegation.delegator });
+            const isDeployed = !!(code && code !== '0x' && code.length > 2);
+            if (!isDeployed) {
+                if (requireDeployed) {
+                    return `delegator smart account ${claims.delegation.delegator} is not deployed — cannot verify ERC-1271. Set verifyDelegationToken opt requireDeployed=false only for explicit counterfactual-demo use cases.`;
+                }
+                return null; // Tolerated: caller opted into the undeployed path explicitly.
+            }
             const magic = (await publicClient.readContract({
                 address: claims.delegation.delegator,
                 abi: ACCOUNT_ABI_ERC1271,
                 functionName: 'isValidSignature',
                 args: [eip712Hash, claims.delegation.signature],
             }));
-            if (magic.toLowerCase() !== ERC1271_MAGIC) {
-                return rejectWith('erc1271 validation failed', claims.delegation.delegator, eip712Hash);
+            return magic.toLowerCase() !== ERC1271_MAGIC ? 'erc1271 validation failed' : null;
+        }
+        catch (e) {
+            return `erc1271 call reverted: ${e instanceof Error ? e.message : e}`;
+        }
+    };
+    // 3.5. DEL-001 (spec 270 v4) — session-key↔identity binding.
+    //
+    // The full signed `delegation` travels in cleartext inside every token, so a verifier that only
+    // checks "some session key signed these claims" lets anyone who OBSERVES a token re-mint it with their
+    // own session key and impersonate the delegator. We close that by requiring a `sessionDelegation` LEAF
+    // whose delegator is `delegation.delegator` (the principal's SA — the canonical identity, v4) and whose
+    // delegate IS the presenting session key, signed by that SA. The signature is validated through the
+    // UniversalSignatureValidator (ERC-1271 / ERC-6492 / ECDSA), so it works for ANY connection strategy and
+    // an attacker can't forge the SA's authorization of THEIR key. `principal` stays `delegation.delegator`.
+    // DEL-001 (ADR-0036): binding is ENFORCED BY DEFAULT — fail-closed. Only an explicit
+    // `allowUnboundSessionToken: true` (legacy / non-client-minted path) skips it.
+    //
+    // The chain-free binding checks (leaf present, delegator-link, delegate === presenting session key) are
+    // computed now and JUDGED after the root signature, where they always were; a leaf that fails them has
+    // no signature worth reading.
+    const bindErr = !opts.allowUnboundSessionToken ? sessionDelegateBindingError(claims.delegation, claims.sessionDelegation, recovered) : null;
+    const sd = !opts.allowUnboundSessionToken && !bindErr ? claims.sessionDelegation : null;
+    const sdHash = sd ? hashDelegation(sd, opts.chainId, opts.delegationManager) : null;
+    // The leaf's signature — the delegator SA (the principal's canonical identity) actually authorized THIS
+    // session key. Validated via the UniversalSignatureValidator when configured (v4 — connection-agnostic:
+    // every credential strategy passes through one surface), else legacy deployed-ERC-1271.
+    const leafSignatureRejection = async () => {
+        if (!sd || !sdHash)
+            return null;
+        try {
+            if (opts.chainSignatureReader) {
+                // spec 289 §5 (W3) — DEL-001 leaf signature through the resilient port.
+                const reason = await validateSaSigViaReader(sd.delegator, sdHash, sd.signature);
+                return reason ? `session-delegation ${reason} (DEL-001)` : null;
+            }
+            if (validateSaSig) {
+                return (await validateSaSig(sd.delegator, sdHash, sd.signature)) ? null : 'session-delegation signature validation failed (DEL-001)';
             }
+            const sdCode = await publicClient.getCode({ address: sd.delegator });
+            if (!sdCode || sdCode === '0x' || sdCode.length <= 2) {
+                return requireDeployed ? 'session-delegation delegator SA not deployed — cannot verify ERC-1271 (DEL-001)' : null;
+            }
+            const magic = (await publicClient.readContract({
+                address: sd.delegator,
+                abi: ACCOUNT_ABI_ERC1271,
+                functionName: 'isValidSignature',
+                args: [sdHash, sd.signature],
+            }));
+            return magic.toLowerCase() !== ERC1271_MAGIC ? 'session-delegation erc1271 validation failed (DEL-001)' : null;
         }
+        catch (e) {
+            return `session-delegation signature check reverted: ${e instanceof Error ? e.message : e}`;
+        }
+    };
+    // ONE ROUND TRIP, NOT FOUR. Root revocation, leaf revocation (DEL-002: the session-key binding is
+    // separately revocable and was once never checked — a revoked, e.g. compromised, session key is rejected
+    // as tightly as a revoked root), root signature and leaf signature are four independent reads; issued in
+    // series they were the verify's whole latency on every gated tool call — four provider round trips before
+    // a single record byte moved. They are issued together and JUDGED in the order they always were: root
+    // revocation, leaf revocation, root signature, the leaf's binding, leaf signature. A check that is not
+    // first to fail still ran, which it did before too; nothing is skipped and no verdict is weakened.
+    {
+        const leafRevocationHash = claims.sessionDelegation ? hashDelegation(claims.sessionDelegation, opts.chainId, opts.delegationManager) : null;
+        const [rootReason, leafReason, rootSig, leafSig] = await Promise.all([
+            revocationRejection(eip712Hash),
+            leafRevocationHash ? revocationRejection(leafRevocationHash) : Promise.resolve(null),
+            rootSignatureRejection(),
+            leafSignatureRejection(),
+        ]);
+        if (rootReason)
+            return rejectWith(rootReason, claims.delegation.delegator, eip712Hash);
+        if (leafReason)
+            return rejectWith(`session-delegation leaf: ${leafReason}`, claims.delegation.delegator, leafRevocationHash);
+        if (rootSig)
+            return rejectWith(rootSig, claims.delegation.delegator, eip712Hash);
+        if (bindErr)
+            return rejectWith(bindErr, claims.delegation.delegator, eip712Hash);
+        if (leafSig)
+            return rejectWith(leafSig, claims.delegation.delegator, eip712Hash);
     }
-    catch (e) {
-        return rejectWith(`erc1271 call reverted: ${e instanceof Error ? e.message : e}`, claims.delegation.delegator, eip712Hash);
+    if (sd) {
+        // Spec 408 §2.1 — THE LEAF'S OWN CAVEATS ARE JUDGED, strictly: its window (an expired leaf is refused as a
+        // leaf, not discovered as a root), its value (a token presentation moves nothing: 0), its audience
+        // (shape here; membership above). Before this, the leaf's caveats were never read.
+        const leafVerdicts = evaluateCaveats(sd.caveats, { timestamp: now, value: 0n }, opts.enforcerMap, {});
+        const leafDenied = leafVerdicts.find((v) => !v.allowed);
+        if (leafDenied)
+            return rejectWith(`session-delegation caveat denied: ${leafDenied.reason ?? 'denied'} (DEL-001)`, claims.delegation.delegator, eip712Hash);
     }
     // 4. caveat evaluation
     //
@@ -380,54 +644,113 @@ export async function verifyDelegationToken(token, opts) {
             return rejectWith('quorum caveat present but no quorumProof supplied — refusing to assume on-chain enforcement', claims.delegation.delegator, eip712Hash);
         }
         if (opts.quorumProof.mode === 'off-chain') {
-            // Off-chain verification is a planned mode; the wire-format
-            // (payloadHash + packedSignatures) is reserved here so consumers
-            // can migrate when the implementation lands. Failing closed
-            // until the spec'd off-chain payload format is implemented.
-            return rejectWith('quorum_off_chain_not_implemented', claims.delegation.delegator, eip712Hash);
+            // Spec 291 §6b — verify the QuorumCaveat off-chain (threshold + authorized
+            // signers + signatures bound to THIS delegation's hash). For tools that
+            // never redeem on chain. Requires the UniversalSignatureValidator surface
+            // so any signer credential strategy (EOA / ERC-1271 / ERC-6492) works.
+            if (!opts.universalSignatureValidator) {
+                return rejectWith('quorum_off_chain_requires_universalSignatureValidator', claims.delegation.delegator, eip712Hash);
+            }
+            const usv = opts.universalSignatureValidator;
+            const quorumCaveat = claims.delegation.caveats.find((c) => c.enforcer.toLowerCase() === target);
+            if (!quorumCaveat) {
+                // Defensive — hasQuorum above already guaranteed presence.
+                return rejectWith('quorum caveat vanished', claims.delegation.delegator, eip712Hash);
+            }
+            const quorumResult = await verifyOffChainQuorum({
+                caveatTerms: quorumCaveat.terms,
+                proof: opts.quorumProof,
+                // Bind the quorum to THIS delegation (its EIP-712 hash) — replay onto a
+                // different delegation fails the payload-binding check.
+                expectedPayloadHash: eip712Hash,
+                verifySignature: (signer, digest, signature) => verifyUniversalSignature({ signer, digest, signature, rpcUrl: opts.rpcUrl, universalSignatureValidator: usv }),
+            });
+            if (!quorumResult.ok) {
+                return rejectWith(`quorum_off_chain: ${quorumResult.reason}`, claims.delegation.delegator, eip712Hash);
+            }
+            // Verified — fall through to the rest of the pipeline.
         }
         // mode === 'on-chain-redeemed' — caller asserts the call will
         // pass through QuorumEnforcer.beforeHook on chain. Accept; the
         // on-chain layer is responsible for the actual signature check.
     }
-    //   - requireAcceptedOnChain: account.isAcceptedSessionDelegation(hash)
+    //   - requireAcceptedOnChain: account.hasAcceptedSessionDelegation(hash)
     //     must return true. Spec § 6 high-risk gate. Single extra chain
     //     read; only fires when the tool-policy decision flips this on
     //     (typically critical-tier tools).
     let acceptedOnChain = false;
     if (opts.requireAcceptedOnChain) {
-        try {
-            acceptedOnChain = (await publicClient.readContract({
-                address: claims.delegation.delegator,
-                abi: ACCEPTED_SESSION_DELEGATION_ABI,
-                functionName: 'isAcceptedSessionDelegation',
-                args: [eip712Hash],
-            }));
-        }
-        catch (e) {
-            return rejectWith(`acceptSessionDelegation check reverted: ${e instanceof Error ? e.message : e}`, claims.delegation.delegator, eip712Hash);
+        if (opts.chainAcceptanceReader) {
+            // spec 289 §5 (W2) — acceptance through the resilient, evidence-bearing port. Inherently
+            // fail-closed: not-accepted OR an unconfirmable read (fail-closed evidence / throw) both reject,
+            // mapping the inline read's RPC-throw → reject (this gate has no 'open' mode — the tier requires it).
+            let failClosed = false;
+            try {
+                const r = await opts.chainAcceptanceReader.isSessionDelegationAccepted(claims.delegation.delegator, eip712Hash);
+                acceptedOnChain = r.accepted;
+                failClosed = r.evidence?.source?.startsWith('fail-closed') ?? false;
+            }
+            catch {
+                acceptedOnChain = false;
+                failClosed = true;
+            }
+            if (!acceptedOnChain) {
+                return rejectWith(failClosed
+                    ? 'acceptSessionDelegation check unavailable; refusing to verify'
+                    : 'tier requires on-chain acceptSessionDelegation blessing; not present', claims.delegation.delegator, eip712Hash);
+            }
         }
-        if (!acceptedOnChain) {
-            return rejectWith('tier requires on-chain acceptSessionDelegation blessing; not present', claims.delegation.delegator, eip712Hash);
+        else {
+            try {
+                acceptedOnChain = (await publicClient.readContract({
+                    address: claims.delegation.delegator,
+                    abi: ACCEPTED_SESSION_DELEGATION_ABI,
+                    functionName: 'hasAcceptedSessionDelegation',
+                    args: [eip712Hash],
+                }));
+            }
+            catch (e) {
+                return rejectWith(`acceptSessionDelegation check reverted: ${e instanceof Error ? e.message : e}`, claims.delegation.delegator, eip712Hash);
+            }
+            if (!acceptedOnChain) {
+                return rejectWith('tier requires on-chain acceptSessionDelegation blessing; not present', claims.delegation.delegator, eip712Hash);
+            }
         }
     }
-    // 5. JTI replay
+    // 5. JTI replay + usage accounting.
     const limit = claims.usageLimit ?? 10;
-    const usage = await opts.jtiStore.trackUsage(claims.jti, limit);
-    if (!usage.allowed) {
-        return rejectWith('token usage limit exceeded', claims.delegation.delegator, eip712Hash);
+    let usageHandle;
+    if (opts.usageMode === 'reserve') {
+        // Two-phase (spec 290 §3): reserve in-flight now; caller commits on success,
+        // releases on a later reject so a post-verify failure doesn't burn a use.
+        if (!opts.jtiStore.reserveUsage) {
+            return rejectWith("usageMode='reserve' requires a JtiStore implementing reserveUsage", claims.delegation.delegator, eip712Hash);
+        }
+        const reserved = await opts.jtiStore.reserveUsage(claims.jti, limit);
+        if (!reserved.allowed) {
+            return rejectWith('token usage limit exceeded', claims.delegation.delegator, eip712Hash);
+        }
+        usageHandle = reserved.reservation;
+    }
+    else {
+        const usage = await opts.jtiStore.trackUsage(claims.jti, limit);
+        if (!usage.allowed) {
+            return rejectWith('token usage limit exceeded', claims.delegation.delegator, eip712Hash);
+        }
     }
     // Accept emit — extended context to capture the threshold-policy
     // outcome (`acceptedOnChain`) for forensics + dashboards. Reuses the
     // same `emit` shape as the reject path but with extra context fields.
+    // R11.1 / N16: NO try/catch — sink composition determines fail-hard
+    // vs fail-soft.
     if (opts.auditSink) {
+        const context = {};
+        if (opts.toolName)
+            context.tool = opts.toolName;
+        if (opts.requireAcceptedOnChain !== undefined) {
+            context.acceptedOnChain = acceptedOnChain;
+        }
         try {
-            const context = {};
-            if (opts.toolName)
-                context.tool = opts.toolName;
-            if (opts.requireAcceptedOnChain !== undefined) {
-                context.acceptedOnChain = acceptedOnChain;
-            }
             await opts.auditSink.write(buildEvent({
                 action: 'delegation.verify.accept',
                 outcome: 'success',
@@ -440,11 +763,50 @@ export async function verifyDelegationToken(token, opts) {
                 context: Object.keys(context).length > 0 ? context : undefined,
             }));
         }
-        catch {
-            /* fail-soft */
+        catch (e) {
+            // A fail-hard audit sink throwing AFTER we reserved must not leak the
+            // in-flight slot — release before propagating (spec 290 §3).
+            if (usageHandle) {
+                try {
+                    await usageHandle.release();
+                }
+                catch { /* best-effort */ }
+            }
+            throw e;
         }
     }
-    return { principal: claims.delegation.delegator };
+    // Off-chain DATA_SCOPE caveats (field-scoping, spec 291-A): decode any present into `grants` so the
+    // resource server (the vault/MCP runtime) can RESTRICT the field projection to what the issuer granted.
+    // The on-chain evaluator treats the sentinel as inert; enforcement is here, off-chain (ADR-0041 — the
+    // scope rides in the SAME signed delegation that conveys authority, so it can't be replayed without it).
+    // Authentic (decoded only AFTER the signature verified) — a malformed scope in a signed delegation throws.
+    const grants = [];
+    // Off-chain VAULT_RECORD_SCOPE caveats (spec 317 §3.2): decode any present into `recordScopes` so the
+    // resource server gates each vault OP (resource + op) against them, deny-by-default when present. Same
+    // authenticity guarantee as DATA_SCOPE — decoded only AFTER the signature verified, so it cannot be
+    // stripped or forged without invalidating the delegation.
+    const recordScopes = [];
+    for (const cav of claims.delegation.caveats ?? []) {
+        const enforcer = cav.enforcer.toLowerCase();
+        if (enforcer === DATA_SCOPE_ENFORCER.toLowerCase()) {
+            grants.push(...decodeDataScopeTerms(cav.terms));
+        }
+        else if (enforcer === VAULT_RECORD_SCOPE_ENFORCER.toLowerCase()) {
+            recordScopes.push(...decodeVaultRecordScopeTerms(cav.terms));
+        }
+    }
+    // `sessionKeyAddress` is surfaced (additive) so callers can cross-check a
+    // per-call proof's signer against the bound session key (spec 287 §6). It
+    // equals `recovered` (verified above to match `claims.sessionKeyAddress`).
+    // `usage` is present only in reserve mode — the caller commits on success,
+    // releases on a later reject (spec 290 §3).
+    return {
+        principal: claims.delegation.delegator,
+        sessionKeyAddress: claims.sessionKeyAddress,
+        ...(grants.length ? { grants } : {}),
+        ...(recordScopes.length ? { recordScopes } : {}),
+        ...(usageHandle ? { usage: usageHandle } : {}),
+    };
 }
 // H7-B.8 (XPKG-002 / EXT-024 closure) — `verifyCrossDelegation` was a
 // public stub that unconditionally returned a "not implemented" error