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

package/dist/standing.js

@@ -0,0 +1,132 @@
+// STANDING WIRES — one capability, decided once (spec 397 `act-as-me`; the shape spec 400 W2a opened for a runtime's
+// standing grant). A standing wire is a delegation from a principal (a person, or her treasury for a payment) to a
+// DELEGATE KEY, caveated to ONE capability selector and a window — and, for a payment, to one payee, one asset and
+// a cap — with NO intent binding. That absence is what makes it standing: it is a capability, not a mandate
+// (`verifyMandateForStep` refuses it alone, `not-a-mandate`), and nothing acts on it directly.
+//
+// When a run parks `authority_required`, the holder of the delegate key DERIVES the mandate the run asked for: a
+// child of the standing wire bound to exactly that intent (`deriveMandate`, subset-checked by the capability's own
+// handler), signs it with the delegate key, and presents the chain [child, standing]. The harness verifies every
+// link — the standing wire's signature against the principal (ERC-1271 / approved digest), its revocation on chain,
+// the child ⊆ parent, the intent and plan binding — before the step acts. Revoke the standing wire on chain and the
+// next derivation is refused everywhere.
+//
+// What a standing wire is NOT: a session, a bearer, a wildcard (never `A2A_ANY_SKILL`), or a pre-approval of
+// anything but the named capability within the window and the cap. One wire, one capability selector.
+import { toHex } from 'viem';
+import { ROOT_AUTHORITY } from './types.js';
+import { hashDelegation } from './hash.js';
+import { readDigestBindings } from './caveats.js';
+import { deriveMandate, subsetHandlerFor } from './mandate.js';
+import { CAPABILITY_RAR_TYPE, DEFAULT_SUBSET_HANDLERS, PAYMENT_RAR_TYPE, PRESENTATION_RAR_TYPE, PRESENTATION_CAPABILITY } from './mandate-handlers.js';
+/** The RAR type a capability is bounded by — the verifier's own map. */
+export const standingRequirementType = (capability) => (capability === 'treasury.payment.execute' ? PAYMENT_RAR_TYPE : capability === PRESENTATION_CAPABILITY ? PRESENTATION_RAR_TYPE : CAPABILITY_RAR_TYPE);
+/**
+ * The UNSIGNED standing wire and its digest. The caller signs `ref` with the delegator's custodian (an off-chain
+ * signature, or the approved-digest sentinel after a batch approval) and sets `wire.signature`.
+ */
+export function buildStandingWire(i) {
+    if (!i.capability.trim())
+        throw new Error('a standing wire names one capability');
+    const type = standingRequirementType(i.capability);
+    if (type === PAYMENT_RAR_TYPE && !i.payment)
+        throw new Error('a standing payment wire needs its bounds: payee, asset, maxAmount');
+    if (type !== PAYMENT_RAR_TYPE && i.payment)
+        throw new Error(`${i.capability} is not a payment — it takes no cap`);
+    if (i.payment && i.payment.maxAmount <= 0n)
+        throw new Error('the cap must be above zero');
+    if (type === PRESENTATION_RAR_TYPE && !i.presentation)
+        throw new Error('a standing presentation wire needs its bounds: audiences, predicateDigests, issuerKeyIds');
+    if (type !== PRESENTATION_RAR_TYPE && i.presentation)
+        throw new Error(`${i.capability} is not a presentation — it takes no audiences`);
+    if (i.presentation && (!i.presentation.audiences.length || !i.presentation.predicateDigests.length || !i.presentation.issuerKeyIds.length))
+        throw new Error('a presentation wire names at least one audience, one predicate program and one issuer facet');
+    const h = subsetHandlerFor(type, i.handlers ?? DEFAULT_SUBSET_HANDLERS);
+    if (!h)
+        throw new Error(`no subset handler for ${type}`);
+    const now = Math.floor(Date.now() / 1000);
+    const requirement = {
+        type,
+        // A payment need arrives from the harness with `actions: [capability]` and `locations: [asset]` (the step's
+        // shape), and from a read-back wire as `actions: ['execute']` (the handler's shape). The parent names both, so
+        // `isSubset` holds for either child; the on-chain selectors are the handler's and do not depend on this list.
+        actions: type === PAYMENT_RAR_TYPE ? ['execute', i.capability] : type === PRESENTATION_RAR_TYPE ? ['present', i.capability] : [i.capability],
+        validAfter: now - 60,
+        validUntil: now + i.validForSeconds,
+        ...(i.payment ? { locations: [i.payment.asset.toLowerCase()], limits: {
+                payee: i.payment.payee.toLowerCase(), asset: i.payment.asset.toLowerCase(),
+                maxAmount: i.payment.maxAmount.toString(), maxAggregate: (i.payment.maxAggregate ?? i.payment.maxAmount).toString(),
+                maxRedemptionsPerWindow: i.payment.maxRedemptionsPerWindow ?? 1, windowSeconds: i.payment.windowSeconds ?? 86_400,
+            } } : {}),
+        ...(i.presentation ? { limits: {
+                audiences: JSON.stringify(i.presentation.audiences), predicateDigests: JSON.stringify(i.presentation.predicateDigests.map((d) => d.toLowerCase())),
+                issuerKeyIds: JSON.stringify(i.presentation.issuerKeyIds), maxPresentations: i.presentation.maxPresentations ?? 0,
+            } } : {}),
+    };
+    const caveats = h.toCaveats(requirement, i.enforcers);
+    const salt = i.salt ?? BigInt(toHex(crypto.getRandomValues(new Uint8Array(16))));
+    const delegation = { delegator: i.delegator, delegate: i.delegate, authority: ROOT_AUTHORITY, caveats, salt, signature: '0x' };
+    const ref = hashDelegation(delegation, i.chainId, i.delegationManager);
+    return {
+        delegation,
+        standing: { v: 1, template: i.template, capability: i.capability, wire: { ...delegation, salt: salt.toString() }, ref, requirement, enforcers: i.enforcers, chainId: i.chainId, delegationManager: i.delegationManager, grantedAt: new Date().toISOString() },
+    };
+}
+/** Attach the signature the custodian produced over `ref` (or the approved-digest sentinel). */
+export function signedStandingWire(s, signature) {
+    return { ...s, wire: { ...s.wire, signature } };
+}
+export function parkedNeedOf(data) {
+    const d = data;
+    if (!d?.requirement || typeof d.requirement !== 'object' || !d.delegator || !d.delegate)
+        return null;
+    if (typeof d.requirement.intentDigest !== 'string' || !Array.isArray(d.requirement.actions))
+        return null;
+    return { requirement: d.requirement, delegator: d.delegator, delegate: d.delegate };
+}
+/** Does this standing wire cover the capability a step needs? Type and capability, not yet the bounds. */
+export function standingCovers(s, capabilityId) {
+    return s.capability === capabilityId && s.requirement.type === standingRequirementType(capabilityId);
+}
+/** Pick the standing wire for a parked need: the one whose capability matches AND whose principal is the need's delegator. */
+export function standingFor(set, need, capabilityId) {
+    const want = need.delegator.toLowerCase();
+    return set.find((s) => standingCovers(s, capabilityId) && String(s.wire.delegator ?? '').toLowerCase() === want && s.requirement.type === need.requirement.type) ?? null;
+}
+/**
+ * The child for THIS intent, from the standing wire, signed with the delegate key — or why not. The need must be an
+ * act OF the wire's principal and ⊆ the wire (the capability's handler judges: for a payment, the amount against
+ * the cap, the payee and the asset against the wire's); its window is clamped into the wire's. Anything else stays
+ * parked for the person — the surface's `grant_link` still works.
+ */
+export async function deriveFromStanding(s, need, sign, handlers = DEFAULT_SUBSET_HANDLERS) {
+    if (String(s.wire.delegator ?? '').toLowerCase() !== need.delegator.toLowerCase())
+        return { ok: false, reason: `the run needs an act of ${need.delegator}; this wire is ${String(s.wire.delegator)}'s` };
+    if (need.requirement.type !== s.requirement.type)
+        return { ok: false, reason: `the run needs a ${need.requirement.type} mandate; this wire is ${s.requirement.type}` };
+    const parent = { ...s.wire, salt: BigInt(String(s.wire.salt)) };
+    const now = Math.floor(Date.now() / 1000);
+    const validAfter = Math.max(need.requirement.validAfter ?? 0, s.requirement.validAfter ?? 0);
+    const validUntil = Math.min(need.requirement.validUntil, s.requirement.validUntil);
+    if (validAfter > now || validUntil <= now)
+        return { ok: false, reason: `the standing wire's window (until ${new Date(s.requirement.validUntil * 1000).toISOString().slice(0, 16)}) does not cover now` };
+    const salt = BigInt(toHex(crypto.getRandomValues(new Uint8Array(16))));
+    const out = deriveMandate({
+        parent,
+        parentRequirement: { ...s.requirement, intentDigest: need.requirement.intentDigest },
+        requirement: { ...need.requirement, validAfter, validUntil },
+        grantee: need.delegate,
+        enforcers: s.enforcers, chainId: s.chainId, delegationManager: s.delegationManager, salt, handlers,
+    });
+    if (!out.ok)
+        return { ok: false, reason: out.reason };
+    const signature = await sign(out.digest);
+    const child = { ...out.delegation, signature, salt: salt.toString() };
+    return { ok: true, presented: [child, s.wire], childRef: out.digest, parentRef: s.ref };
+}
+/** Is this wire STANDING — no intent binding among its caveats? (A mandate always carries one.) */
+export function isStandingWire(wire, digestBindingEnforcer) {
+    const caveats = (wire.caveats ?? []).map((c) => ({ enforcer: c.enforcer, terms: c.terms, args: (c.args ?? '0x') }));
+    return !readDigestBindings(caveats, digestBindingEnforcer).intent;
+}
+//# sourceMappingURL=standing.js.map

package/dist/standing.js.map

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

package/dist/token.d.ts

@@ -1,5 +1,5 @@
 import { type Address, type Hex } from 'viem';
-import type { DelegationTokenClaims, VerifyError, VerifyOpts, DataScopeGrant } from './types';
+import type { Delegation, DelegationTokenClaims, VerifyError, VerifyOpts, DataScopeGrant, VaultRecordScopeGrant } from './types.js';
 import { type AuditSink } from '@agenticprimitives/audit';
 /** Sorted-key JSON; BigInt → numeric string. Both sides must produce the
  *  exact same bytes for the signature to round-trip.
@@ -67,6 +67,68 @@ export interface VerifyOptsExt extends VerifyOpts {
      *   `process.env.NODE_ENV` is undefined).
      */
     revocationFailMode?: 'closed' | 'open';
+    /**
+     * spec 289 §5 — optional injected revocation reader. When provided, the
+     * revocation check routes through it (resilient, multi-provider, evidence-
+     * bearing, with the bounded-freshness invariant) INSTEAD of the inline
+     * single-client `isRevoked` read. Structurally compatible with chain-state's
+     * `ChainAuthorityReader` (so delegation needs no chain-state dependency). A
+     * fail-closed reader result (evidence.source begins `fail-closed`) is treated
+     * exactly like the inline read's RPC-throw: rejected under `revocationFailMode:
+     * 'closed'` (default), tolerated under `'open'`. Omit ⇒ unchanged inline read.
+     */
+    chainRevocationReader?: {
+        isDelegationRevoked(hash: Hex): Promise<{
+            revoked: boolean;
+            evidence?: {
+                source: string;
+            };
+        }>;
+    };
+    /**
+     * spec 289 §5 (W2) — optional injected acceptance reader. When provided AND `requireAcceptedOnChain`,
+     * the `hasAcceptedSessionDelegation` high-risk gate routes through it (resilient, multi-provider,
+     * evidence-bearing) INSTEAD of the inline single-client read. Structurally compatible with chain-state's
+     * `ChainAuthorityReader` (so delegation needs no chain-state dependency). Acceptance is inherently
+     * fail-closed (the tier REQUIRES `accepted === true`): a fail-closed reader result (evidence.source
+     * begins `fail-closed`) or a throw is rejected, exactly like the inline read's RPC-throw. Omit ⇒
+     * unchanged inline read.
+     */
+    chainAcceptanceReader?: {
+        isSessionDelegationAccepted(principal: Address, hash: Hex): Promise<{
+            accepted: boolean;
+            evidence?: {
+                source: string;
+            };
+        }>;
+    };
+    /**
+     * spec 289 §5 (W3) — optional injected signature reader. When provided, BOTH signature-verify sites
+     * (the main delegator signature AND the DEL-001 session-delegation leaf) route through it (resilient,
+     * multi-provider, evidence-bearing) INSTEAD of the inline single-client USV/ERC-1271 read. Structurally
+     * compatible with chain-state's `ChainAuthorityReader.verifySmartAgentSignature` (so delegation needs no
+     * chain-state dependency). The reader validates via the UniversalSignatureValidator (connection-agnostic:
+     * ECDSA / ERC-1271 / ERC-6492) and reports `deployed` as a FACT; this verifier keeps the POLICY:
+     *   - a fail-closed reader result (evidence.source begins `fail-closed`) or a throw → reject (signature
+     *     is critical — fail closed, like the inline read's revert);
+     *   - `valid === false` → reject;
+     *   - `requireDeployed && !deployed` → reject (a counterfactual/undeployed SA; the caller must opt into
+     *     it explicitly with `requireDeployed: false`, exactly as the legacy inline path required).
+     * Omit ⇒ unchanged inline read (USV when `universalSignatureValidator` is set, else legacy ERC-1271).
+     */
+    chainSignatureReader?: {
+        verifySmartAgentSignature(input: {
+            signer: Address;
+            digest: Hex;
+            signature: Hex;
+        }): Promise<{
+            valid: boolean;
+            deployed: boolean;
+            evidence?: {
+                source: string;
+            };
+        }>;
+    };
     /**
      * Audit sink (audit C3 pass 3b). When provided, every verify outcome
      * emits a `delegation.verify.{accept,reject}` event. The principal
@@ -133,6 +195,17 @@ export interface VerifyOptsExt extends VerifyOpts {
         payloadHash: Hex;
         packedSignatures: Hex;
     };
+    /**
+     * Usage-accounting mode for the delegation token's `usageLimit`/JTI (spec 290 §3).
+     * - `'consume'` (DEFAULT — unchanged): atomically consume one use at verify.
+     * - `'reserve'`: reserve an in-flight use at verify and return a
+     *   `JtiReservation` on the success result; the caller `commit()`s ONLY after
+     *   the call is admitted + executed, and `release()`s on any later rejection
+     *   (rate limit, budget, policy) so a post-verify failure never burns a use.
+     *   Requires the `jtiStore` to implement `reserveUsage` (else verify fails
+     *   closed — no silent fallback to consume).
+     */
+    usageMode?: 'consume' | 'reserve';
     /**
      * When `true`, verify that the delegator's smart account has
      * pre-blessed this delegation hash on-chain via
@@ -147,12 +220,27 @@ export interface VerifyOptsExt extends VerifyOpts {
      */
     requireAcceptedOnChain?: boolean;
 }
+/**
+ * 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 declare function sessionDelegateBindingError(delegation: Delegation, sessionDelegation: Delegation | undefined, sessionKeyAddress: Address): string | null;
 /**
  * Full verification pipeline. Caller passes `toolName` in opts for tool-scope
  * caveat evaluation; without it the mcp-tool-scope caveat denies.
  */
 export declare function verifyDelegationToken(token: string, opts: VerifyOptsExt): Promise<{
     principal: Address;
+    sessionKeyAddress: Address;
     grants?: DataScopeGrant[];
+    recordScopes?: VaultRecordScopeGrant[];
+    usage?: import('./types.js').JtiReservation;
 } | VerifyError>;
 //# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAeA,OAAO,EAA4B,KAAK,OAAO,EAAE,KAAK,GAAG,EAAE,MAAM,MAAM,CAAC;AACxE,OAAO,KAAK,EAEV,qBAAqB,EACrB,WAAW,EACX,UAAU,EACV,cAAc,EACf,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAwBtE;;;;;;;gBAOgB;AAChB,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAsBpD;AAiDD,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,IAAI,CAAC,qBAAqB,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,EAClG,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,CAAC,EAC1C,IAAI,CAAC,EAAE;IACL,iEAAiE;IACjE,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B,GACA,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CA2EzC;AAuCD,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;;;;;;;;;OAYG;IACH,kBAAkB,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC;IACvC;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;IASvB;;;;;;;;;;;;;;OAcG;IACH,mBAAmB,CAAC,EAAE;QAAE,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC;IAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,WAAW,CAAC,EACR;QAAE,IAAI,EAAE,mBAAmB,CAAA;KAAE,GAC7B;QAAE,IAAI,EAAE,WAAW,CAAC;QAAC,WAAW,EAAE,GAAG,CAAC;QAAC,gBAAgB,EAAE,GAAG,CAAA;KAAE,CAAC;IAEnE;;;;;;;;;;;OAWG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AA+BD;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC;IAAE,SAAS,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,cAAc,EAAE,CAAA;CAAE,GAAG,WAAW,CAAC,CAgQ1E"}
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"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"}