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

package/dist/invocation-proof.js

@@ -0,0 +1,157 @@
+// Agentic Invocation Proof (spec 287). A per-call proof-of-possession: the
+// DEL-001-bound session key (spec 270) signs an EIP-712 digest over the EXACT
+// call so a public native MCP request is bound to its exact argument payload —
+// the property A2A already has via `hashA2aMessage` and the internal mesh has
+// via the service MAC, but which the direct public hop lacked.
+//
+// This module is the PURE crypto primitive: the type, the EIP-712 digest, the
+// canonical argument/token hashing, and a claims verifier that takes an INJECTED
+// signature verifier (the `UniversalSignatureValidator` surface — so any
+// credential strategy works) + an INJECTED `JtiStore` (one-shot requestId). It
+// imports no audit/transport — it returns a `{ ok, reason }` result and never
+// emits. The MCP-specific wiring (recompute argsHash from the received call,
+// cross-check against the delegation token, gate on `requireInvocationProof`,
+// emit audit) lives in `mcp-runtime`'s `with-delegation` — spec 287 §9.
+import { hashTypedData, keccak256, toBytes } from 'viem';
+import { canonicalJSON } from './token.js';
+export const INVOCATION_PROOF_VERSION = 'agentic-invocation-v1';
+/** Default bounded TTL window (spec 287 §5). */
+export const DEFAULT_MAX_PROOF_TTL_MS = 120_000;
+export const DEFAULT_PROOF_CLOCK_SKEW_MS = 30_000;
+export const INVOCATION_PROOF_EIP712_TYPES = {
+    AgenticInvocationProofV1: [
+        { name: 'audience', type: 'string' },
+        { name: 'operation', type: 'string' },
+        { name: 'argumentsHash', type: 'bytes32' },
+        { name: 'delegationTokenHash', type: 'bytes32' },
+        { name: 'requestId', type: 'string' },
+        { name: 'issuedAt', type: 'uint256' },
+        { name: 'expiresAt', type: 'uint256' },
+    ],
+};
+/** EIP-712 domain — no `verifyingContract` (this is an off-chain proof). */
+export function invocationProofDomain(chainId) {
+    return { name: 'AgenticInvocationProof', version: '1', chainId };
+}
+/**
+ * The digest the session key signs (and the verifier recomputes). Building it is
+ * pure — importable client-side to build + sign a proof.
+ */
+export function hashInvocationProof(p) {
+    return hashTypedData({
+        domain: invocationProofDomain(p.chainId),
+        types: INVOCATION_PROOF_EIP712_TYPES,
+        primaryType: 'AgenticInvocationProofV1',
+        message: {
+            audience: p.audience,
+            operation: p.operation,
+            argumentsHash: p.argumentsHash,
+            delegationTokenHash: p.delegationTokenHash,
+            requestId: p.requestId,
+            issuedAt: BigInt(p.issuedAt),
+            expiresAt: BigInt(p.expiresAt),
+        },
+    });
+}
+/**
+ * Canonical hash of the EXACT tool arguments (spec 287 §4). Uses the repo's
+ * cross-runtime-stable `canonicalJSON` so the client's signed hash and the
+ * runtime's recomputed hash are byte-identical. The runtime MUST recompute this
+ * from the args it actually received — never trust the client's stated value.
+ */
+export function canonicalArgumentsHash(args) {
+    return keccak256(toBytes(canonicalJSON(args)));
+}
+/** Bind the proof to the presented delegation token (spec 287 §4). */
+export function hashDelegationTokenString(rawToken) {
+    return keccak256(toBytes(rawToken));
+}
+/**
+ * Client-side builder: assemble + sign an invocation proof. The caller supplies
+ * a `sign(digest)` that produces the session key's signature over the EIP-712
+ * digest (e.g. `account.sign({ hash })` for an EOA session key, or any SA
+ * `Signer`). `args` MUST be the exact tool arguments the call will
+ * carry — the runtime recomputes `canonicalArgumentsHash(args)` from what it
+ * receives and rejects a mismatch. Pure (no chain); importable in the browser.
+ */
+export async function buildInvocationProof(input) {
+    const signed = {
+        chainId: input.chainId,
+        audience: input.audience,
+        operation: input.operation,
+        argumentsHash: canonicalArgumentsHash(input.args),
+        delegationTokenHash: hashDelegationTokenString(input.rawDelegationToken),
+        requestId: input.requestId,
+        issuedAt: input.issuedAt,
+        expiresAt: input.expiresAt,
+    };
+    const signature = await input.sign(hashInvocationProof(signed));
+    return {
+        version: INVOCATION_PROOF_VERSION,
+        principal: input.principal,
+        sessionKey: input.sessionKey,
+        signature,
+        ...signed,
+    };
+}
+function hexEq(a, b) {
+    return a.toLowerCase() === b.toLowerCase();
+}
+/**
+ * Verify an invocation proof. Cheap local checks gate first; the (potentially
+ * chain-bound) signature verify runs next; the one-shot `requestId` is reserved
+ * ONLY after the signature verifies (so an unauthenticated party can't burn a
+ * victim's requestId). Fail-closed: every failure returns `{ ok: false, reason }`.
+ * Callers MUST NOT echo `reason` to external clients — log it, return a generic
+ * error (spec 287 §5, ADR-0013).
+ */
+export async function verifyInvocationProofClaims(input) {
+    const { proof, expected } = input;
+    const now = (input.now ?? Date.now)();
+    const maxTtl = input.maxProofTtlMs ?? DEFAULT_MAX_PROOF_TTL_MS;
+    const skew = input.clockSkewMs ?? DEFAULT_PROOF_CLOCK_SKEW_MS;
+    if (proof.version !== INVOCATION_PROOF_VERSION)
+        return { ok: false, reason: 'version' };
+    if (proof.chainId !== expected.chainId)
+        return { ok: false, reason: 'chain_mismatch' };
+    if (proof.audience !== expected.audience)
+        return { ok: false, reason: 'audience_mismatch' };
+    if (proof.operation !== expected.operation)
+        return { ok: false, reason: 'operation_mismatch' };
+    if (!hexEq(proof.argumentsHash, expected.argumentsHash))
+        return { ok: false, reason: 'arguments_mismatch' };
+    if (!hexEq(proof.delegationTokenHash, expected.delegationTokenHash)) {
+        return { ok: false, reason: 'delegation_token_mismatch' };
+    }
+    // Bounded window (spec 287 §5).
+    if (!Number.isFinite(proof.issuedAt) || !Number.isFinite(proof.expiresAt)) {
+        return { ok: false, reason: 'window_malformed' };
+    }
+    if (proof.expiresAt <= proof.issuedAt)
+        return { ok: false, reason: 'window_inverted' };
+    if (proof.expiresAt - proof.issuedAt > maxTtl)
+        return { ok: false, reason: 'window_too_long' };
+    if (proof.issuedAt > now + skew)
+        return { ok: false, reason: 'not_yet_valid' };
+    if (now > proof.expiresAt)
+        return { ok: false, reason: 'expired' };
+    // Proof-of-possession over the exact digest. Injected verifier → any credential
+    // strategy (EOA ECDSA, ERC-1271, ERC-6492) via UniversalSignatureValidator.
+    const digest = hashInvocationProof(proof);
+    let sigOk = false;
+    try {
+        sigOk = await input.verifySignature({ signer: proof.sessionKey, digest, signature: proof.signature });
+    }
+    catch {
+        return { ok: false, reason: 'signature_error' };
+    }
+    if (!sigOk)
+        return { ok: false, reason: 'signature_invalid' };
+    // One-shot requestId reservation — ONLY after the signature verified.
+    const jti = `invproof:${proof.audience}:${proof.requestId}`;
+    const tracked = await input.jtiStore.trackUsage(jti, 1);
+    if (!tracked.allowed)
+        return { ok: false, reason: 'request_replayed' };
+    return { ok: true };
+}
+//# sourceMappingURL=invocation-proof.js.map

package/dist/invocation-proof.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation-proof.js","sourceRoot":"","sources":["../src/invocation-proof.ts"],"names":[],"mappings":"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"}

package/dist/lineage.d.ts

@@ -0,0 +1,70 @@
+import type { Address, Hex } from './types.js';
+/** The JSON-safe wire (salt as a string), as it travels and as a vault record holds it. */
+export interface LineageWire {
+    delegator: Address;
+    delegate: Address;
+    authority: Hex;
+    caveats: Array<{
+        enforcer: Address;
+        terms: Hex;
+        args?: Hex;
+    }>;
+    salt: string;
+    signature: Hex;
+}
+/** The account-level approved-digest sentinel (spec 253): the delegator's account has `approveDigest`ed the
+ *  wire's hash under its current custody epoch, and `isValidSignature` honours it. */
+export declare const APPROVED_DIGEST_SENTINEL: Hex;
+export interface DelegationLineageV1 {
+    type: 'ap.delegation-lineage.v1';
+    /** The re-issued wire's delegation hash — the record key's suffix. */
+    hash: Hex;
+    /** The hash this wire replaces; receipts citing it remain readable through this record. */
+    supersedes: Hex;
+    /** The re-issued wire itself: same terms, same salt, `0x03` signature. Returned to its delegate only. */
+    wire: LineageWire;
+    issuedAt: string;
+    /** Why it was re-issued. A rotation is the only reason today; a recovery re-issues NOTHING (spec 410 §1.2 step 6) —
+     *  the person issues NEW grants from a reviewed list, with new salts and no lineage, because a recovery is the
+     *  moment a planted grant would otherwise ride through. */
+    reason: 'rotation';
+}
+export declare const LINEAGE_RECORD_PREFIX: "delegation.lineage:";
+export declare const lineageRecordType: (hash: Hex) => string;
+/** Is this wire signed by the account's approved-digest sentinel (re-approved as-is on rotation) or by a key
+ *  (re-issued on rotation)? */
+export declare const wireSigning: (w: {
+    signature: string;
+}) => "approved-digest" | "key";
+/**
+ * Re-issue a KEY-SIGNED wire as an approved-digest wire for a rotation: identical terms, identical salt, the
+ * `0x03` sentinel as signature. The digest returned is what the rotation batch `approveDigest`s; the lineage
+ * record is what the delegator's vault keeps so the delegate can fetch the head. Refuses a wire that is
+ * already approved-digest (it needs re-approval, not re-issue) and one whose `supersedes` would be itself.
+ */
+export declare function reissueForRotation(old: LineageWire, chainId: number, delegationManager: Address, now?: () => Date): {
+    wire: LineageWire;
+    digest: Hex;
+    lineage: DelegationLineageV1;
+};
+export type WireLineageAnswer = {
+    status: 'current';
+    hash: Hex;
+    wire: LineageWire | null;
+} | {
+    status: 'superseded';
+    hash: Hex;
+    wire: LineageWire;
+    supersededFrom: Hex;
+} | {
+    status: 'unknown';
+};
+/**
+ * The HEAD of a wire's lineage, from the delegator's lineage records: follow `supersedes` links from `hash`
+ * forward until no record supersedes the current head. Pure; the caller supplies the records (a vault list) and
+ * the delegate asking, and a record whose wire names another delegate is never followed — a wire is returned to
+ * its delegate only. `unknown` when nothing in the records mentions the hash: the caller then decides whether
+ * the ORIGINAL is still current (it holds it) or was revoked (the chain says).
+ */
+export declare function currentWireOf(records: readonly DelegationLineageV1[], hash: Hex, delegate: Address): WireLineageAnswer;
+//# sourceMappingURL=lineage.d.ts.map

package/dist/lineage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineage.d.ts","sourceRoot":"","sources":["../src/lineage.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AAI/C,2FAA2F;AAC3F,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,GAAG,CAAC;IACf,OAAO,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,GAAG,CAAC;QAAC,IAAI,CAAC,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,GAAG,CAAC;CAChB;AAED;sFACsF;AACtF,eAAO,MAAM,wBAAwB,EAAE,GAAY,CAAC;AAEpD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,0BAA0B,CAAC;IACjC,sEAAsE;IACtE,IAAI,EAAE,GAAG,CAAC;IACV,2FAA2F;IAC3F,UAAU,EAAE,GAAG,CAAC;IAChB,yGAAyG;IACzG,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB;;+DAE2D;IAC3D,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,eAAO,MAAM,qBAAqB,EAAG,qBAA8B,CAAC;AACpE,eAAO,MAAM,iBAAiB,SAAU,GAAG,KAAG,MAAyD,CAAC;AAQxG;+BAC+B;AAC/B,eAAO,MAAM,WAAW,MAAO;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,KAAG,iBAAiB,GAAG,KACS,CAAC;AAErF;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,GAAG,GAAE,MAAM,IAAuB,GAAG;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,OAAO,EAAE,mBAAmB,CAAA;CAAE,CAUtM;AAED,MAAM,MAAM,iBAAiB,GACzB;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,GAC1D;IAAE,MAAM,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,GAAG,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,cAAc,EAAE,GAAG,CAAA;CAAE,GAC3E;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAE1B;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,SAAS,mBAAmB,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,GAAG,iBAAiB,CAqBtH"}

package/dist/lineage.js

@@ -0,0 +1,65 @@
+import { hashDelegation } from './hash.js';
+/** The account-level approved-digest sentinel (spec 253): the delegator's account has `approveDigest`ed the
+ *  wire's hash under its current custody epoch, and `isValidSignature` honours it. */
+export const APPROVED_DIGEST_SENTINEL = '0x03';
+export const LINEAGE_RECORD_PREFIX = 'delegation.lineage:';
+export const lineageRecordType = (hash) => `${LINEAGE_RECORD_PREFIX}${hash.toLowerCase()}`;
+const toDelegation = (w) => ({
+    delegator: w.delegator, delegate: w.delegate, authority: w.authority,
+    caveats: w.caveats.map((c) => ({ enforcer: c.enforcer, terms: c.terms, args: (c.args ?? '0x') })),
+    salt: BigInt(w.salt), signature: w.signature,
+});
+/** Is this wire signed by the account's approved-digest sentinel (re-approved as-is on rotation) or by a key
+ *  (re-issued on rotation)? */
+export const wireSigning = (w) => w.signature.toLowerCase() === APPROVED_DIGEST_SENTINEL ? 'approved-digest' : 'key';
+/**
+ * Re-issue a KEY-SIGNED wire as an approved-digest wire for a rotation: identical terms, identical salt, the
+ * `0x03` sentinel as signature. The digest returned is what the rotation batch `approveDigest`s; the lineage
+ * record is what the delegator's vault keeps so the delegate can fetch the head. Refuses a wire that is
+ * already approved-digest (it needs re-approval, not re-issue) and one whose `supersedes` would be itself.
+ */
+export function reissueForRotation(old, chainId, delegationManager, now = () => new Date()) {
+    if (wireSigning(old) === 'approved-digest')
+        throw new Error('reissueForRotation: an approved-digest wire is re-approved as-is on rotation, never re-issued');
+    const oldHash = hashDelegation(toDelegation(old), chainId, delegationManager);
+    const wire = { ...old, caveats: old.caveats.map((c) => ({ ...c })), signature: APPROVED_DIGEST_SENTINEL };
+    const digest = hashDelegation(toDelegation(wire), chainId, delegationManager);
+    // The EIP-712 hash excludes the signature, so the re-issued object HAS THE SAME DELEGATION HASH as the old one:
+    // what changes is how it validates (the sentinel, under the new epoch), not what it grants. The lineage still
+    // records the supersession so the delegate learns the object it holds is stale and which one to hold now.
+    const lineage = { type: 'ap.delegation-lineage.v1', hash: digest, supersedes: oldHash, wire, issuedAt: now().toISOString(), reason: 'rotation' };
+    return { wire, digest, lineage };
+}
+/**
+ * The HEAD of a wire's lineage, from the delegator's lineage records: follow `supersedes` links from `hash`
+ * forward until no record supersedes the current head. Pure; the caller supplies the records (a vault list) and
+ * the delegate asking, and a record whose wire names another delegate is never followed — a wire is returned to
+ * its delegate only. `unknown` when nothing in the records mentions the hash: the caller then decides whether
+ * the ORIGINAL is still current (it holds it) or was revoked (the chain says).
+ */
+export function currentWireOf(records, hash, delegate) {
+    const byPrev = new Map();
+    for (const r of records) {
+        if (r.type !== 'ap.delegation-lineage.v1')
+            continue;
+        if (r.wire.delegate.toLowerCase() !== delegate.toLowerCase())
+            continue;
+        byPrev.set(r.supersedes.toLowerCase(), r);
+    }
+    let head = hash.toLowerCase();
+    let last = null;
+    const seen = new Set();
+    while (byPrev.has(head)) {
+        if (seen.has(head))
+            break; // a cycle is a corrupt record set; stop at the last sound link
+        seen.add(head);
+        last = byPrev.get(head);
+        head = last.hash.toLowerCase();
+    }
+    if (!last) {
+        const known = records.some((r) => r.hash.toLowerCase() === hash.toLowerCase() && r.wire.delegate.toLowerCase() === delegate.toLowerCase());
+        return known ? { status: 'current', hash, wire: records.find((r) => r.hash.toLowerCase() === hash.toLowerCase()).wire } : { status: 'unknown' };
+    }
+    return { status: 'superseded', hash: last.hash, wire: last.wire, supersededFrom: hash };
+}
+//# sourceMappingURL=lineage.js.map

package/dist/lineage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lineage.js","sourceRoot":"","sources":["../src/lineage.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAY3C;sFACsF;AACtF,MAAM,CAAC,MAAM,wBAAwB,GAAQ,MAAM,CAAC;AAiBpD,MAAM,CAAC,MAAM,qBAAqB,GAAG,qBAA8B,CAAC;AACpE,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,IAAS,EAAU,EAAE,CAAC,GAAG,qBAAqB,GAAG,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;AAExG,MAAM,YAAY,GAAG,CAAC,CAAc,EAAc,EAAE,CAAC,CAAC;IACpD,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS;IACpE,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,IAAI,CAAQ,EAAE,CAAC,CAAC;IACxG,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS;CAC7C,CAAC,CAAC;AAEH;+BAC+B;AAC/B,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAwB,EAA6B,EAAE,CACjF,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE,KAAK,wBAAwB,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC;AAErF;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAgB,EAAE,OAAe,EAAE,iBAA0B,EAAE,MAAkB,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE;IAClI,IAAI,WAAW,CAAC,GAAG,CAAC,KAAK,iBAAiB;QAAE,MAAM,IAAI,KAAK,CAAC,+FAA+F,CAAC,CAAC;IAC7J,MAAM,OAAO,GAAG,cAAc,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAC9E,MAAM,IAAI,GAAgB,EAAE,GAAG,GAAG,EAAE,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,wBAAwB,EAAE,CAAC;IACvH,MAAM,MAAM,GAAG,cAAc,CAAC,YAAY,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC;IAC9E,gHAAgH;IAChH,8GAA8G;IAC9G,0GAA0G;IAC1G,MAAM,OAAO,GAAwB,EAAE,IAAI,EAAE,0BAA0B,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IACtK,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AACnC,CAAC;AAOD;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,OAAuC,EAAE,IAAS,EAAE,QAAiB;IACjG,MAAM,MAAM,GAAG,IAAI,GAAG,EAA+B,CAAC;IACtD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,CAAC,IAAI,KAAK,0BAA0B;YAAE,SAAS;QACpD,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC,WAAW,EAAE;YAAE,SAAS;QACvE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC;IAC5C,CAAC;IACD,IAAI,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IAC9B,IAAI,IAAI,GAA+B,IAAI,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,MAAM,CAAC,+DAA+D;QAC1F,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACf,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC;QACzB,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,CAAC;IACD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;QAC3I,OAAO,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,IAAI,CAAC,WAAW,EAAE,CAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IACnJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;AAC1F,CAAC"}

package/dist/mandate-handlers.d.ts

@@ -0,0 +1,15 @@
+import { type MandateSubsetHandler } from './mandate.js';
+export declare const CAPABILITY_RAR_TYPE = "urn:ap:rar:capability";
+export declare const capabilityHandler: MandateSubsetHandler;
+export declare const PAYMENT_RAR_TYPE = "urn:ap:rar:treasury.payment.execute";
+export declare const paymentHandler: MandateSubsetHandler;
+export declare const PRESENTATION_RAR_TYPE = "urn:ap:rar:credential.present";
+export declare const PRESENTATION_CAPABILITY = "credential.present";
+export declare const presentationHandler: MandateSubsetHandler;
+/** The defaults as an explicit set — pass this to `verifyMandateForStep({ handlers })` rather than relying
+ *  on ambient registration, which does not survive a bundle that duplicates the module. */
+export declare const DEFAULT_SUBSET_HANDLERS: ReadonlyMap<string, MandateSubsetHandler>;
+export declare function registerDefaultSubsetHandlers(): void;
+/** Test seam — pairs with `_resetSubsetHandlers`. */
+export declare function _resetDefaultRegistration(): void;
+//# sourceMappingURL=mandate-handlers.d.ts.map

package/dist/mandate-handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mandate-handlers.d.ts","sourceRoot":"","sources":["../src/mandate-handlers.ts"],"names":[],"mappings":"AAaA,OAAO,EAA0F,KAAK,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAYjJ,eAAO,MAAM,mBAAmB,0BAA0B,CAAC;AAE3D,eAAO,MAAM,iBAAiB,EAAE,oBAwC/B,CAAC;AAsBF,eAAO,MAAM,gBAAgB,wCAAwC,CAAC;AActE,eAAO,MAAM,cAAc,EAAE,oBAkE5B,CAAC;AAqBF,eAAO,MAAM,qBAAqB,kCAAkC,CAAC;AACrE,eAAO,MAAM,uBAAuB,uBAAuB,CAAC;AAkB5D,eAAO,MAAM,mBAAmB,EAAE,oBA+CjC,CAAC;AAEF;2FAC2F;AAC3F,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAI5E,CAAC;AAIH,wBAAgB,6BAA6B,IAAI,IAAI,CAMpD;AACD,qDAAqD;AACrD,wBAAgB,yBAAyB,IAAI,IAAI,CAAwB"}

package/dist/mandate-handlers.js

@@ -0,0 +1,279 @@
+// The first subset handlers — spec 350 §2.1. Each `type` owns its own "narrower-than", because RFC 9396
+// says no universal one exists. Two ship here: a GENERIC capability handler that covers every
+// non-financial action (membership, naming, registry), and the PAYMENT handler that reuses the
+// spec-272 `PaymentEnforcer` caveats so a treasury mandate is bounded on chain by the same terms the
+// off-chain verifier reads.
+import { decodeAbiParameters } from 'viem';
+import { buildCaveat, encodeTimestampTerms, decodeTimestampTerms, encodeAllowedMethodsTerms, decodeAllowedMethodsTerms, encodeAllowedTargetsTerms, decodeAllowedTargetsTerms, encodeValueTerms, encodePaymentTerms, PAYMENT_TRANSFER_SELECTOR, buildPayloadClassesCaveat, decodePayloadClassesTerms, PRESENTATION_SCOPE_ENFORCER, buildPresentationScopeCaveat, decodePresentationScopeTerms, } from './caveats.js';
+import { methodSelector } from './method-authorization.js';
+import { baseIsSubset, registerSubsetHandler } from './mandate.js';
+const lc = (s) => s.toLowerCase();
+const findCaveat = (caveats, enforcer) => enforcer ? caveats.find((c) => lc(c.enforcer) === lc(enforcer)) : undefined;
+// ─── Generic capability handler ────────────────────────────────────────────────────────────────────
+//
+// type: `urn:ap:rar:capability`. actions = capability ids (ADR-0051), each becoming an allowedMethods
+// selector; locations = the agent SAs this authority may be exercised AGAINST (allowedTargets); a window;
+// value pinned to 0. No type-specific limits — a membership add either is or is not in scope.
+export const CAPABILITY_RAR_TYPE = 'urn:ap:rar:capability';
+export const capabilityHandler = {
+    type: CAPABILITY_RAR_TYPE,
+    isSubset: baseIsSubset,
+    toCaveats(req, e) {
+        if (!req.actions.length)
+            throw new Error('capability mandate: at least one action (capability id) is required');
+        const caveats = [
+            buildCaveat(e.timestamp, encodeTimestampTerms(req.validAfter ?? 0, req.validUntil)),
+            // Capability selectors (what the off-chain verifier compares) AND the real EVM selectors this
+            // authority actually calls (what the enforcer sees). Both are "methods allowed"; omitting the
+            // second made every on-chain capability call revert MethodNotAllowed.
+            buildCaveat(e.allowedMethods, encodeAllowedMethodsTerms([...req.actions.map(methodSelector), ...(req.methods ?? [])])),
+            buildCaveat(e.value, encodeValueTerms(0n)),
+        ];
+        if (req.locations?.length)
+            caveats.push(buildCaveat(e.allowedTargets, encodeAllowedTargetsTerms(req.locations.map(asAddress))));
+        // Spec 410 §7 — what a write under this mandate may carry, pinned into the signed wire.
+        if (req.payloadClasses?.length) {
+            if (!e.payloadClasses)
+                throw new Error('capability mandate: payloadClasses named but this estate has no PayloadClassesEnforcer');
+            caveats.push(buildPayloadClassesCaveat(e.payloadClasses, req.payloadClasses));
+        }
+        return caveats;
+    },
+    fromCaveats(caveats, e) {
+        const ts = findCaveat(caveats, e.timestamp);
+        const methods = findCaveat(caveats, e.allowedMethods);
+        if (!ts || !methods)
+            return null;
+        const payload = e.payloadClasses ? findCaveat(caveats, e.payloadClasses) : undefined;
+        const { validAfter, validUntil } = decodeTimestampTerms(ts.terms);
+        const selectors = decodeAllowedMethodsTerms(methods.terms);
+        // Selectors are one-way; the reader keeps them as `sel:<hex>` unless it can name them. A verifier
+        // compares by selector (methodSelector(step.capability)), so this is lossless for its purpose.
+        const targets = findCaveat(caveats, e.allowedTargets);
+        return {
+            type: CAPABILITY_RAR_TYPE,
+            actions: selectors.map((s) => `sel:${s}`),
+            ...(targets ? { locations: [...decodeAllowedTargetsTerms(targets.terms)] } : {}),
+            ...(payload ? { payloadClasses: decodePayloadClassesTerms(payload.terms) } : {}),
+            validAfter: Number(validAfter),
+            validUntil: Number(validUntil),
+        };
+    },
+};
+/** A capability mandate grants capability IDS: a step exercising `organization.team.create` with the verb
+ *  `create` is judged on the id (the verb is the capability's own facet, not a separate grant). */
+capabilityHandler.stepActions = (step) => [step.capability];
+/** `isSubset` for the capability type must compare ACTIONS BY SELECTOR, because a read-back mandate
+ *  carries `sel:<hex>` while a step or a fresh requirement carries the capability id. */
+capabilityHandler.isSubset = (child, parent) => {
+    const norm = (a) => (a.startsWith('sel:') ? a.slice(4).toLowerCase() : methodSelector(a).toLowerCase());
+    return baseIsSubset({ ...child, actions: child.actions.map(norm) }, { ...parent, actions: parent.actions.map(norm) });
+};
+// ─── Payment handler ───────────────────────────────────────────────────────────────────────────────
+//
+// type: `urn:ap:rar:treasury.payment.execute`. limits = { payee, asset, maxAmount, maxAggregate,
+// maxRedemptionsPerWindow, windowSeconds }; the on-chain terms are the spec-272 PaymentEnforcer's.
+// "Pay Ligonier $250 but not Bob $250" is `payee` + `maxAmount`, not a different method.
+export const PAYMENT_RAR_TYPE = 'urn:ap:rar:treasury.payment.execute';
+function paymentLimits(req) {
+    const l = req.limits ?? {};
+    const need = (k) => { const v = l[k]; if (v === undefined)
+        throw new Error(`payment mandate: limits.${k} is required`); return String(v); };
+    return {
+        payee: asAddress(need('payee')), asset: asAddress(need('asset')),
+        maxAmount: BigInt(need('maxAmount')), maxAggregate: BigInt(l.maxAggregate ?? need('maxAmount')),
+        maxRedemptionsPerWindow: Number(l.maxRedemptionsPerWindow ?? 1), windowSeconds: Number(l.windowSeconds ?? 86_400),
+    };
+}
+export const paymentHandler = {
+    // Spec 408 §2.2 — the PaymentEnforcer's terms (payee, asset, per-charge and aggregate ceilings, window) are
+    // what `isSubset` below compares against the step; off chain there is no other judge of them.
+    judgesEnforcers: (e) => (e.payment ? [e.payment] : []),
+    type: PAYMENT_RAR_TYPE,
+    // The narrowest grant that covers this payment: THIS payee, THIS asset, THIS amount, once, within the
+    // hour. A person asked to authorize a payment is being asked for an amount — a requirement that omits
+    // it either cannot be minted (the enforcer needs the ceiling) or would have to invent one, and an
+    // invented ceiling is a bigger grant than anybody agreed to.
+    stepLimits(step) {
+        const a = step.args ?? {};
+        const amount = a.amount !== undefined ? String(a.amount).trim() : undefined;
+        if (amount === undefined || amount === '')
+            throw new Error('payment step: args.amount is required to bound the authority it needs');
+        // AND IT MUST BE A NUMBER. A planner asked for a payment with no figure filled the amount with the
+        // literal string "<UNKNOWN>", which is present, non-empty, and would have been encoded as the
+        // ceiling of a real mandate. A limit that cannot be read as a quantity does not bound anything, and
+        // the one thing a payment caveat exists to do is bound the quantity.
+        if (!/^\d+$/.test(amount)) {
+            throw new Error(`payment step: args.amount must be a whole number of the token's smallest units, got "${amount}"`);
+        }
+        return {
+            payee: String(a.payee ?? ''), asset: String(a.asset ?? step.resource ?? ''),
+            maxAmount: amount, maxAggregate: amount, maxRedemptionsPerWindow: 1, windowSeconds: 3600,
+        };
+    },
+    isSubset(child, parent) {
+        if (!baseIsSubset(child, parent))
+            return false;
+        // A STEP arrives with `amount` + `payee` (+ maybe `asset`); a REQUIREMENT with the full limit set.
+        // Compare what is present; anything the child leaves unstated inherits the parent's bound.
+        const p = paymentLimits(parent);
+        const cl = child.limits ?? {};
+        const amount = cl.amount !== undefined ? BigInt(String(cl.amount)) : cl.maxAmount !== undefined ? BigInt(String(cl.maxAmount)) : null;
+        if (amount !== null && amount > p.maxAmount)
+            return false;
+        if (cl.maxAggregate !== undefined && BigInt(String(cl.maxAggregate)) > p.maxAggregate)
+            return false;
+        if (cl.payee !== undefined && lc(String(cl.payee)) !== lc(p.payee))
+            return false;
+        if (cl.asset !== undefined && lc(String(cl.asset)) !== lc(p.asset))
+            return false;
+        if (cl.maxRedemptionsPerWindow !== undefined && Number(cl.maxRedemptionsPerWindow) > p.maxRedemptionsPerWindow)
+            return false;
+        return true;
+    },
+    toCaveats(req, e) {
+        if (!e.payment)
+            throw new Error('payment mandate: enforcers.payment (PaymentEnforcer) is required');
+        const p = paymentLimits(req);
+        return [
+            buildCaveat(e.payment, encodePaymentTerms({ payee: p.payee, asset: p.asset, maxAmountPerCharge: p.maxAmount, maxAggregate: p.maxAggregate, maxRedemptionsPerWindow: p.maxRedemptionsPerWindow, windowSeconds: p.windowSeconds })),
+            buildCaveat(e.timestamp, encodeTimestampTerms(req.validAfter ?? 0, req.validUntil)),
+            buildCaveat(e.allowedTargets, encodeAllowedTargetsTerms([p.asset])),
+            buildCaveat(e.allowedMethods, encodeAllowedMethodsTerms([PAYMENT_TRANSFER_SELECTOR, methodSelector('treasury.payment.execute')])),
+        ];
+    },
+    fromCaveats(caveats, e) {
+        const pay = findCaveat(caveats, e.payment);
+        const ts = findCaveat(caveats, e.timestamp);
+        if (!pay || !ts)
+            return null;
+        const [payee, asset, maxAmount, maxAggregate, perWindow, windowSeconds] = decodeAbiParameters([{ type: 'address' }, { type: 'address' }, { type: 'uint256' }, { type: 'uint256' }, { type: 'uint32' }, { type: 'uint32' }], pay.terms);
+        const { validAfter, validUntil } = decodeTimestampTerms(ts.terms);
+        return {
+            type: PAYMENT_RAR_TYPE,
+            actions: ['execute'],
+            locations: [asset],
+            limits: { payee, asset, maxAmount: maxAmount.toString(), maxAggregate: maxAggregate.toString(), maxRedemptionsPerWindow: perWindow, windowSeconds },
+            validAfter: Number(validAfter), validUntil: Number(validUntil),
+        };
+    },
+};
+function asAddress(s) {
+    const m = /0x[0-9a-fA-F]{40}$/.exec(s); // accepts a bare address or a CAIP-10 `eip155:<chain>:0x…`
+    if (!m)
+        throw new Error(`not an address or CAIP-10 account: ${s}`);
+    return m[0];
+}
+// ─── Presentation handler (spec 305 W2 / zkID alignment §3, wave Z2) ────────────────────────────────────────
+//
+// type: `urn:ap:rar:credential.present`. limits = { audiences, predicateDigests, issuerKeyIds (JSON arrays),
+// maxPresentations }. The port of smart-agent's `SessionGrantV1.scope` (verifiers, credentialTypes,
+// presentationDefinitionIds) + `evaluateProofPolicy` (requested predicates ⊆ allowed): what a delegate key may
+// cause the person's DEVICE KEY to sign a `Show` challenge for. A step arrives with ONE audience, ONE predicate
+// digest and ONE issuer keyId; the mandate carries sets. Nothing here reaches the chain — the sentinel terms are
+// in the signed hash, and the KEY RELEASE (`presentation-release.ts`) is the judge, before the signature exists.
+//
+// Why by digest and not by claim: "age ≥ 18 to venue.example" and "income ≥ 100k to lender.example" are two
+// predicate programs; a wire for the first must not sign the second (zkID alignment §3 rule 2). The digest is
+// over the compiled, canonical program the verifier itself recomputes, so a translated permission cannot widen.
+export const PRESENTATION_RAR_TYPE = 'urn:ap:rar:credential.present';
+export const PRESENTATION_CAPABILITY = 'credential.present';
+const list = (v, what) => {
+    if (Array.isArray(v))
+        return v.map(String);
+    if (typeof v === 'string') {
+        try {
+            const a = JSON.parse(v);
+            if (Array.isArray(a))
+                return a.map(String);
+        }
+        catch { /* a single value */ }
+        return v ? [v] : [];
+    }
+    throw new Error(`presentation mandate: limits.${what} must be a list`);
+};
+function presentationLimits(req) {
+    const l = req.limits ?? {};
+    const out = { audiences: list(l.audiences ?? l.audience, 'audiences'), predicateDigests: list(l.predicateDigests ?? l.predicateDigest, 'predicateDigests').map(lc), issuerKeyIds: list(l.issuerKeyIds ?? l.issuerKeyId, 'issuerKeyIds'), maxPresentations: Number(l.maxPresentations ?? 0) };
+    if (!out.audiences.length || !out.predicateDigests.length || !out.issuerKeyIds.length)
+        throw new Error('presentation mandate: audiences, predicateDigests and issuerKeyIds are each required and non-empty');
+    for (const d of out.predicateDigests)
+        if (!/^0x[0-9a-f]{64}$/.test(d))
+            throw new Error(`presentation mandate: predicateDigest ${d} is not a 32-byte hex digest`);
+    return out;
+}
+export const presentationHandler = {
+    type: PRESENTATION_RAR_TYPE,
+    // The scope sentinel's terms are what `isSubset` compares; no chain judge exists for them, and none is wanted.
+    judgesEnforcers: () => [PRESENTATION_SCOPE_ENFORCER],
+    stepActions: () => ['present'],
+    stepLimits(step) {
+        const a = step.args ?? {};
+        for (const k of ['audience', 'predicateDigest', 'issuerKeyId']) {
+            if (typeof a[k] !== 'string' || !a[k])
+                throw new Error(`presentation step: args.${k} is required to bound the authority it needs`);
+        }
+        return { audiences: String(a.audience), predicateDigests: lc(String(a.predicateDigest)), issuerKeyIds: String(a.issuerKeyId), maxPresentations: 1 };
+    },
+    isSubset(child, parent) {
+        if (!baseIsSubset(child, parent))
+            return false;
+        const p = presentationLimits(parent);
+        const cl = child.limits ?? {};
+        const want = { audiences: list(cl.audiences ?? cl.audience ?? [], 'audiences'), predicateDigests: list(cl.predicateDigests ?? cl.predicateDigest ?? [], 'predicateDigests').map(lc), issuerKeyIds: list(cl.issuerKeyIds ?? cl.issuerKeyId ?? [], 'issuerKeyIds') };
+        // A child that names nothing for a dimension inherits the parent's bound; one that names something must name
+        // a subset. Audiences are compared as exact strings — a verifier's origin is not a prefix of another's.
+        if (!want.audiences.every((x) => p.audiences.includes(x)))
+            return false;
+        if (!want.predicateDigests.every((x) => p.predicateDigests.includes(x)))
+            return false;
+        if (!want.issuerKeyIds.every((x) => p.issuerKeyIds.includes(x)))
+            return false;
+        if (cl.maxPresentations !== undefined && p.maxPresentations !== 0 && Number(cl.maxPresentations) > p.maxPresentations)
+            return false;
+        return true;
+    },
+    toCaveats(req, e) {
+        const p = presentationLimits(req);
+        return [
+            buildPresentationScopeCaveat({ audiences: p.audiences, predicateDigests: p.predicateDigests, issuerKeyIds: p.issuerKeyIds, maxPresentations: p.maxPresentations }),
+            buildCaveat(e.timestamp, encodeTimestampTerms(req.validAfter ?? 0, req.validUntil)),
+            buildCaveat(e.allowedMethods, encodeAllowedMethodsTerms([methodSelector(PRESENTATION_CAPABILITY)])),
+            buildCaveat(e.value, encodeValueTerms(0n)),
+        ];
+    },
+    fromCaveats(caveats, e) {
+        const scope = findCaveat(caveats, PRESENTATION_SCOPE_ENFORCER);
+        const ts = findCaveat(caveats, e.timestamp);
+        if (!scope || !ts)
+            return null;
+        const t = decodePresentationScopeTerms(scope.terms);
+        const { validAfter, validUntil } = decodeTimestampTerms(ts.terms);
+        return {
+            type: PRESENTATION_RAR_TYPE,
+            actions: ['present'],
+            limits: { audiences: JSON.stringify(t.audiences), predicateDigests: JSON.stringify(t.predicateDigests), issuerKeyIds: JSON.stringify(t.issuerKeyIds), maxPresentations: t.maxPresentations },
+            validAfter: Number(validAfter), validUntil: Number(validUntil),
+        };
+    },
+};
+/** The defaults as an explicit set — pass this to `verifyMandateForStep({ handlers })` rather than relying
+ *  on ambient registration, which does not survive a bundle that duplicates the module. */
+export const DEFAULT_SUBSET_HANDLERS = new Map([
+    [capabilityHandler.type, capabilityHandler],
+    [paymentHandler.type, paymentHandler],
+    [presentationHandler.type, presentationHandler],
+]);
+/** Register both into the ambient registry. Idempotent per process; a second call is a no-op. */
+let registered = false;
+export function registerDefaultSubsetHandlers() {
+    if (registered)
+        return;
+    registerSubsetHandler(capabilityHandler);
+    registerSubsetHandler(paymentHandler);
+    registerSubsetHandler(presentationHandler);
+    registered = true;
+}
+/** Test seam — pairs with `_resetSubsetHandlers`. */
+export function _resetDefaultRegistration() { registered = false; }
+//# sourceMappingURL=mandate-handlers.js.map