agent402-client 0.8.23 → 0.8.24

package/README.md

@@ -398,7 +398,10 @@ can still redeem until its `validBefore`, so the error carries `paid: "unknown"`
 and `heldUsd`, and `spendingSummary()` reports it under `heldUsd`. A held
 amount counts for the rolling 24 hours, and longer when the authorization
 stays valid longer (a seven-day Circle Gateway authorization is held until its
-`validBefore` passes). Pass your `x402Client` so the client sees exactly which
+`validBefore` passes). With an `x402Client`, an accept asking to stay valid for
+more than a day (`MAX_VALIDITY_SECONDS`) is refused before anything is signed,
+and a payload signed for longer is refused before it is sent, so no hold
+outlives a day after the send (seven days and an hour for a batched payment). Pass your `x402Client` so the client sees exactly which
 payments were signed; through a pre-wrapped `fetch` alone it cannot tell, so any
 failed paid call is held. A paid HTTP-success response that later fails byte,
 JSON, or output validation remains settled spend. Free proof-of-work calls are

package/index.js

@@ -19,8 +19,8 @@
 //   const a = new Agent402({ fetch: payFetch });
 import { createHash, randomBytes } from "node:crypto";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { quoteOf, guardSigning, networkIdsOf, acceptUsd } from "./known-assets.js";
-export { KNOWN_ASSETS, NETWORK_NAMES, knownAsset, acceptUsd, networkIdsOf } from "./known-assets.js";
+import { quoteOf, guardSigning, networkIdsOf, acceptUsd, signedExpirySeconds, MAX_VALIDITY_SECONDS } from "./known-assets.js";
+export { KNOWN_ASSETS, NETWORK_NAMES, knownAsset, acceptUsd, networkIdsOf, MAX_VALIDITY_SECONDS } from "./known-assets.js";
 import { distrustFetch } from "./tls-distrust.js";
 export { distrustFetch, distrustDispatcher, distrustCheckServerIdentity, DISTRUSTED_SPKI_SHA256 } from "./tls-distrust.js";
 export { resetRetryFetch, isConnectionReset } from "./reset-retry.js";
@@ -32,7 +32,7 @@ export { AsyncJobPendingError } from "./async-job.js";
 // `User-Agent: agent402-client/<version>` - a standard header, no extra
 // network calls - so a seller can attribute traffic (and settled payments)
 // to this SDK. Product token only; nothing about the caller rides along.
-const VERSION = "0.8.23";
+const VERSION = "0.8.24";
 const USER_AGENT = `agent402-client/${VERSION}`;
 // A package built on this SDK (an adapter) names itself first: its own
 // product token, then this one. Anything that is not one well-formed token
@@ -119,13 +119,15 @@ export const HOLD_SLACK_MS = 10 * 60 * 1000;
 
 /** When a signed payment payload can no longer settle, in ms since the epoch
  *  plus HOLD_SLACK_MS: an EIP-3009 `authorization.validBefore` or a Permit2
- *  `deadline`, in seconds. null when the payload names no expiry this reads
- *  (a Solana transaction, an unknown scheme). */
-export function signedValidUntilMs(paymentPayload) {
-  const p = paymentPayload?.payload;
-  const v = p?.authorization?.validBefore ?? p?.permit2Authorization?.deadline;
-  if (v == null || !/^\d{1,15}$/.test(String(v))) return null;
-  return Number(v) * 1000 + HOLD_SLACK_MS;
+ *  `deadline`, in seconds, never later than `maxSeconds` after `nowMs` (the
+ *  longest window this client signs: MAX_VALIDITY_SECONDS, or
+ *  GATEWAY_MAX_TIMEOUT_SECONDS for a batched payment), so no hold outlives
+ *  the ceiling a payload must pass to be sent. null when the payload names no
+ *  expiry this reads (a Solana transaction, an unknown scheme). */
+export function signedValidUntilMs(paymentPayload, { maxSeconds = MAX_VALIDITY_SECONDS, nowMs = Date.now() } = {}) {
+  const v = signedExpirySeconds(paymentPayload);
+  if (v == null || !Number.isFinite(v)) return null;
+  return Math.min(v * 1000, nowMs + maxSeconds * 1000) + HOLD_SLACK_MS;
 }
 
 /** A spend-log entry the caps still count at `now`: anything recorded inside
@@ -688,8 +690,10 @@ export class Agent402 {
             const d = ctx.refusal;
             throw new SpendingLimitError(d.reason === "unknown-asset"
               ? `refusing to pay for "${slug}" - no payment option it asked to sign is in a known asset, so none can be priced`
-              : d.reason === "signed-amount"
+              : d.reason === "signed-amount" || d.reason === "signed-validity"
               ? `refusing to pay for "${slug}" - ${d.detail}, so the payment was not sent`
+              : d.reason === "validity"
+              ? `refusing to pay for "${slug}" - ${d.detail}, so nothing was signed`
               : `refusing to pay $${d.priceUsd} for "${slug}" - the payment it asked to sign is over ${d.limit || "the cap"} ($${d.allowanceUsd} left to sign)`,
             { limit: d.limit || "signing", slug, priceUsd: d.priceUsd, cap: d.allowanceUsd, atSigning: true, cause: e, ...(e?.paid === "unknown" ? { paid: "unknown", heldUsd: e.heldUsd } : {}) });
           }
@@ -801,7 +805,7 @@ export class Agent402 {
     // claim on the deposit until its validBefore whatever the seller answers
     // (a refusal, a failure, a redirect, a job still running), so its signed
     // amount is held against the caps from the first send.
-    const sent = [{ usd: acceptedUsd, until: signedValidUntilMs(payload) }];
+    const sent = [{ usd: acceptedUsd, until: signedValidUntilMs(payload, { maxSeconds: GATEWAY_MAX_TIMEOUT_SECONDS }) }];
     const heldUsd = this._spendHold(reservation, sent);
     const paidHeaders = { "PAYMENT-SIGNATURE": header, ...asyncHeaders };
     let r;

package/known-assets.js

@@ -134,6 +134,51 @@ export function quoteOf(accepts, x402Version = undefined) {
   return { max, min, unknown, total: accepts.length };
 }
 
+// The longest a signed payment may stay redeemable. An EVM "exact" signer
+// sets validBefore (EIP-3009) or deadline (Permit2) to the moment of signing
+// plus the accept's maxTimeoutSeconds, and the signed payload is a bearer
+// claim until then, so a seller that quotes years gets an authorization it
+// could redeem for years and a held amount that never stops counting. Honest
+// accepts ask for minutes (Agent402's own ask 300 s); a day admits every
+// one of them. An accept that asks for longer is dropped before selection,
+// and a payload signed past it is refused before it is sent.
+export const MAX_VALIDITY_SECONDS = 24 * 3600;
+// Signing reads the clock a moment before the check after it does.
+const VALIDITY_CLOCK_SLACK_SECONDS = 60;
+
+/** True when an accept asks for a validity window past MAX_VALIDITY_SECONDS.
+ *  An accept with no readable maxTimeoutSeconds is left to the check of what
+ *  was signed (signedValidityProblem). */
+export function acceptValidityTooLong(accept, maxSeconds = MAX_VALIDITY_SECONDS) {
+  const raw = accept?.maxTimeoutSeconds;
+  if (raw == null || raw === "") return false;
+  const n = Number(raw);
+  return !Number.isFinite(n) || n > maxSeconds;
+}
+
+/** The expiry a signed payload carries, in unix seconds: an EIP-3009
+ *  `authorization.validBefore` or a Permit2 `deadline`. null when the payload
+ *  names none (a Solana transaction, an unknown scheme). NaN when it names
+ *  one that is not a whole number of seconds. */
+export function signedExpirySeconds(paymentPayload) {
+  const p = paymentPayload?.payload;
+  const v = p?.authorization?.validBefore ?? p?.permit2Authorization?.deadline;
+  if (v == null) return null;
+  return /^\d{1,15}$/.test(String(v)) ? Number(v) : NaN;
+}
+
+/** Why a created payment payload stays redeemable for too long, or null: its
+ *  expiry is past `nowMs` plus `maxSeconds` (and a minute of clock slack), or
+ *  it names an expiry that cannot be read. */
+export function signedValidityProblem(paymentPayload, { maxSeconds = MAX_VALIDITY_SECONDS, nowMs = Date.now() } = {}) {
+  const exp = signedExpirySeconds(paymentPayload);
+  if (exp == null) return null;
+  if (!Number.isFinite(exp)) return "the signed authorization's expiry cannot be read";
+  const left = exp - Math.floor(nowMs / 1000);
+  if (left > maxSeconds + VALIDITY_CLOCK_SLACK_SECONDS) return `the signed authorization stays valid for ${left} seconds, past the ${maxSeconds}-second ceiling`;
+  return null;
+}
+
 /** Enforce a USD allowance at signing on an @x402/core x402Client.
  *
  *  `allowance()` is the most this buyer may sign for the payment being built
@@ -141,8 +186,10 @@ export function quoteOf(accepts, x402Version = undefined) {
  *  for none). A registered policy drops every accept that cannot be priced or
  *  is over the allowance, so the client selects among the ones that fit, and a
  *  hook before payload creation checks the selected accept again and passes
- *  its USD value to `onSign`. A refusal throws (from the policy) or aborts
- *  (from the hook) before any signature exists; `onRefuse` hears why first. */
+ *  its USD value to `onSign`. An accept asking for a validity window past
+ *  MAX_VALIDITY_SECONDS is dropped and refused the same way. A refusal throws
+ *  (from the policy) or aborts (from the hook) before any signature exists;
+ *  `onRefuse` hears why first. */
 export function guardSigning(client, { allowance, onSign = null, onRefuse = null }) {
   if (!client || typeof client.registerPolicy !== "function" || typeof client.onBeforePaymentCreation !== "function") {
     throw new TypeError("guardSigning needs an @x402/core x402Client (registerPolicy and onBeforePaymentCreation)");
@@ -151,7 +198,12 @@ export function guardSigning(client, { allowance, onSign = null, onRefuse = null
   const refuse = (detail) => { try { onRefuse?.(detail); } catch { /* the refusal stands */ } return detail; };
   client.registerPolicy((version, accepts) => {
     const cap = allowance();
-    const kept = accepts.filter((a) => { const usd = acceptUsd(a, version); return usd != null && usd <= cap; });
+    const priced = accepts.filter((a) => { const usd = acceptUsd(a, version); return usd != null && usd <= cap; });
+    const kept = priced.filter((a) => !acceptValidityTooLong(a));
+    if (!kept.length && priced.length) {
+      const d = refuse({ reason: "validity", priceUsd: null, allowanceUsd: cap, detail: `every payment option it may sign asks to stay valid for more than ${MAX_VALIDITY_SECONDS} seconds` });
+      throw new Error(`spending guard: ${d.detail}; nothing was signed`);
+    }
     if (!kept.length) {
       const q = quoteOf(accepts, version);
       const d = refuse({ reason: q && q.min != null ? "over-allowance" : "unknown-asset", priceUsd: q ? q.min : null, allowanceUsd: cap });
@@ -172,6 +224,10 @@ export function guardSigning(client, { allowance, onSign = null, onRefuse = null
       refuse({ reason: "over-allowance", priceUsd: usd, allowanceUsd: cap });
       return { abort: true, reason: `spending guard: the selected payment option asks $${usd}, above the $${cap} this buyer may sign; nothing was signed` };
     }
+    if (acceptValidityTooLong(r)) {
+      const d = refuse({ reason: "validity", priceUsd: usd, allowanceUsd: cap, detail: `the selected payment option asks to stay valid for ${r.maxTimeoutSeconds} seconds, past the ${MAX_VALIDITY_SECONDS}-second ceiling` });
+      return { abort: true, reason: `spending guard: ${d.detail}; nothing was signed` };
+    }
     onSign?.(usd, r);
     return undefined;
   });
@@ -252,9 +308,10 @@ export async function signedPaymentProblem(paymentPayload, requirements, x402Ver
 }
 
 /** Refuse to send a payment payload whose signed amount is not the one the
- *  allowance passed: registered after payload creation, so the check reads
- *  what was actually signed, and a throw here stops the payment-aware fetch
- *  before the payload leaves the process. guardSigning registers it; a
+ *  allowance passed, or whose expiry is past MAX_VALIDITY_SECONDS from now
+ *  (signedValidityProblem): registered after payload creation, so the check
+ *  reads what was actually signed, and a throw here stops the payment-aware
+ *  fetch before the payload leaves the process. guardSigning registers it; a
  *  client with its own selector (and no guardSigning) can register it alone. */
 export function guardSignedAmount(client, { allowance = () => Infinity, onRefuse = null } = {}) {
   if (!client || typeof client.onAfterPaymentCreation !== "function") {
@@ -262,9 +319,10 @@ export function guardSignedAmount(client, { allowance = () => Infinity, onRefuse
   }
   client.onAfterPaymentCreation(async ({ paymentRequired, selectedRequirements: r, paymentPayload }) => {
     const cap = allowance();
-    const problem = await signedPaymentProblem(paymentPayload, r, paymentRequired?.x402Version, cap);
+    const amountProblem = await signedPaymentProblem(paymentPayload, r, paymentRequired?.x402Version, cap);
+    const problem = amountProblem || signedValidityProblem(paymentPayload);
     if (!problem) return;
-    try { onRefuse?.({ reason: "signed-amount", priceUsd: null, allowanceUsd: cap, detail: problem }); } catch { /* the refusal stands */ }
+    try { onRefuse?.({ reason: amountProblem ? "signed-amount" : "signed-validity", priceUsd: null, allowanceUsd: cap, detail: problem }); } catch { /* the refusal stands */ }
     throw new Error(`spending guard: ${problem}; the payment was not sent`);
   });
   return client;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-client",
-  "version": "0.8.23",
+  "version": "0.8.24",
   "description": "Agent402 buyer SDK: resolve a task to a tool across 500+ pay-per-call endpoints and call it with payment handled - free via proof-of-work, or over x402 or MPP (a stock mppx fetch works) with a wallet you keep; the buy side of Agentic Finance. Caching, idempotent retries (Idempotency-Key), non-custodial, zero dependencies.",
   "type": "module",
   "main": "index.js",