x402-safe-fetch 0.16.0 → 0.16.2

package/README.md

@@ -144,7 +144,9 @@ The preflight itself is capped at $0.002 and paid with the same schemes. `receip
 
 A seller can take the payment and still answer with an error: a 405, a 500, or another 402 asking to pay again. Paying the same request again then usually costs a second payment for nothing. In the agent exam at [exam.fizzl.eu](https://exam.fizzl.eu) this was the most common loss: every model we examined did it at least once, with or without a preflight, because a preflight only sees the 402 before paying.
 
-So safe-fetch remembers each paid request (method, URL and body) whose paid answer was not a success. Calling that same request again within 30 minutes throws `SafePayError` with code `paid_no_delivery` (and `error.earlier`: when it was paid and what it was answered with), without paying and without buying another preflight. A different request is not affected, and a success clears it.
+So safe-fetch remembers each paid endpoint (method, origin and path) whose paid answer was not a success. Calling that endpoint again within 30 minutes, with any query string or body, throws `SafePayError` with code `paid_no_delivery` (and `error.earlier`: when it was paid and what it was answered with), without paying and without buying another preflight. Another endpoint is not affected, and a success clears it.
+
+The query and the body are left out on purpose. Since 0.16.2: in the exam, an open model that was refused added `&nonce=1`, `&nonce=2`, … to the URL, and each "new" request was paid (eight times). A seller that took your money without delivering doesn't get paid again on that endpoint, whatever the agent changes in the request.
 
 ```js
 const safeFetch = createSafeFetch({

package/index.d.ts

@@ -152,7 +152,7 @@ export declare function verifyReceipt(body: unknown, options?: { signers?: strin
 /** The reason code reported with a refused outcome: the preflight's first reason at its verdict's level. */
 export function refusalReason(preflight: { verdict?: string; reasons?: { level?: string; code?: string }[] }): string;
 
-/** Remembers paid requests that weren't delivered, so the same request isn't paid again (used by createSafeFetch; usable on its own). */
+/** Remembers paid endpoints (method, origin and path) that took a payment without delivering, so they aren't paid again with any query or body (used by createSafeFetch; usable on its own). */
 export declare function createPaidGuard(options?: { windowMs?: number; now?: () => number }): {
   blocked(url: string, init?: { method?: string; body?: unknown }): { at: number; status: number } | null;
   record(url: string, init: { method?: string; body?: unknown } | undefined, status: number): void;

package/index.js

@@ -25,8 +25,8 @@
 // hash of the refused offer; no query, no keys, nothing about the buyer or this client), once a day per endpoint and
 // reason. A screening_hit isn't sent: the draft takes it only signed. Off by default.
 // A paid request answered without delivery (an error, or another 402) is never paid again on its own: the same
-// method, URL and body within paidErrorMs throws SafePayError code "paid_no_delivery" (onPaidError "stop", the
-// default). The most common loss in the agent exam (exam.fizzl.eu) was paying again after a seller took the payment
+// endpoint (method, origin and path; any query or body) within paidErrorMs throws SafePayError code
+// "paid_no_delivery" (onPaidError "stop", the default). The most common loss in the agent exam (exam.fizzl.eu) was paying again after a seller took the payment
 // and answered with an error; a preflight can't see that, it only reads the 402 before paying (paid-guard.js).
 // Every preflight must carry Doctor's signed receipt for exactly this request
 // (endpoint, method, budget, network), checked against Doctor's pinned signer:
@@ -51,7 +51,7 @@ export const PRESIGN_GUARD_URL = "https://presign-guard.fizzl.eu";
 export const INJECTION_CAP = "$0.02"; // presign-guard's injection check costs $0.01; never more than twice that
 // The header a checked answer carries: green, orange, red (only with onInjection "flag" or a function) or unchecked.
 export const ANSWER_CHECK_HEADER = "x-answer-check";
-export const VERSION = "0.16.0";
+export const VERSION = "0.16.1";
 // Doctor sees which calls come from this package (in its usage counts), nothing more.
 const DOCTOR_HEADERS = { accept: "application/json", "user-agent": `x402-safe-fetch/${VERSION}` };
 export const BASE = "eip155:8453";
@@ -159,8 +159,15 @@ export function payableOption(accepts, network, maxUsd) {
   // Base and other EVM chains: "exact" first (what most clients register), then "auth-capture" (Coinbase's escrow:
   // the buyer signs once, the USDC is held and only captured when the seller delivers, e.g. Atom's domain checkout).
   // Either is paid only if your register() added its scheme, and both stay within the budget (x402's spend controls
-  // read the amount, which for auth-capture is the most that can be captured).
-  return on.find((a) => a?.scheme === "exact") ?? on.find((a) => a?.scheme === "auth-capture") ?? on[0] ?? null;
+  // read the amount, which for auth-capture is the most that can be captured). Of several options of a scheme, the
+  // cheapest within the budget: a 402 that lists $0.50 before $0.01 to the same seller is paid a cent, not refused
+  // (or overpaid) because the first one costs more.
+  const cheapest = (scheme) => on
+    .filter((a) => a?.scheme === scheme)
+    .map((a) => ({ a, usd: usdOfOption(a, network) }))
+    .filter((x) => x.usd !== null && x.usd > 0 && !(x.usd > cap + 1e-9))
+    .sort((x, y) => x.usd - y.usd)[0]?.a;
+  return cheapest("exact") ?? cheapest("auth-capture") ?? on.find((a) => a?.scheme === "exact") ?? on.find((a) => a?.scheme === "auth-capture") ?? on[0] ?? null;
 }
 
 // The code that stopped the payment: the preflight's first reason at its verdict's level (no_go, then caution), as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-safe-fetch",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "description": "A fetch for AI agents that checks an unknown x402 endpoint ($0.001 x402 Doctor preflight) before paying it, and never pays above your budget.",
   "type": "module",
   "exports": {

package/paid-guard.js

@@ -4,32 +4,29 @@
 // (a 405, a 500, or another 402 asking to pay again), and the agent pays the same request again, and again. Every
 // model we examined did it at least once, with or without a preflight: the preflight only sees the 402 before paying.
 //
-// The guard remembers each paid request (method, URL and body) whose paid answer was not a success. Paying that same
-// request again within the window is refused, so the loss stops at one payment. A success clears it. A different
-// request (another URL, method or body) is not affected. No dependencies: it runs anywhere fetch does.
+// The guard remembers each paid endpoint (method, origin and path) whose paid answer was not a success. Paying that
+// endpoint again within the window is refused, so the loss stops at one payment. The query string and the body are
+// left out on purpose: in the exam, a model that was refused added "&nonce=1", "&nonce=2", ... to the URL and paid
+// eight more times. A success clears it. Another endpoint (another path, method or host) is not affected. No
+// dependencies: it runs anywhere fetch does.
 
 export const PAID_ERROR_MS = 30 * 60 * 1000;
 
-// A short, stable fingerprint of the body (FNV-1a, 32 bit): the key holds no request content.
-function bodyKey(body) {
-  if (body === undefined || body === null) return "";
-  const text = typeof body === "string" ? body : body instanceof URLSearchParams ? body.toString() : ArrayBuffer.isView(body) ? new TextDecoder().decode(body) : body instanceof ArrayBuffer ? new TextDecoder().decode(new Uint8Array(body)) : String(body);
-  let h = 0x811c9dc5;
-  for (let i = 0; i < text.length; i++) {
-    h ^= text.charCodeAt(i);
-    h = Math.imul(h, 0x01000193) >>> 0;
+/** The endpoint as the guard sees it: method, origin and path (no query, no body, no fragment). */
+export function purchaseKey(url, { method = "GET" } = {}) {
+  let endpoint = String(url);
+  try {
+    const u = new URL(endpoint);
+    endpoint = `${u.origin}${u.pathname.replace(/\/+$/, "") || "/"}`;
+  } catch {
+    endpoint = endpoint.split(/[?#]/)[0];
   }
-  return `${text.length}:${h.toString(16)}`;
-}
-
-/** The request as the guard sees it: method, URL and a fingerprint of the body. */
-export function purchaseKey(url, { method = "GET", body } = {}) {
-  return `${String(method).toUpperCase()} ${String(url)} ${bodyKey(body)}`;
+  return `${String(method).toUpperCase()} ${endpoint}`;
 }
 
 /**
  * @param {object} [options]
- * @param {number} [options.windowMs]  how long a paid request that wasn't delivered stays blocked (default 30 minutes)
+ * @param {number} [options.windowMs]  how long a paid endpoint that didn't deliver stays blocked (default 30 minutes)
  * @param {() => number} [options.now]
  */
 export function createPaidGuard({ windowMs = PAID_ERROR_MS, now = Date.now } = {}) {
@@ -60,5 +57,5 @@ export function createPaidGuard({ windowMs = PAID_ERROR_MS, now = Date.now } = {
 
 /** The refusal text, for an error or a tool answer. */
 export function paidTwiceMessage(url, earlier) {
-  return `not paid again: ${url} was already paid at ${new Date(earlier.at).toISOString()} and answered HTTP ${earlier.status} without delivering. Paying the same request again would most likely be charged again for nothing; ask the seller, or try a different request.`;
+  return `not paid again: ${purchaseKey(url).replace(/^GET /, "")} was already paid at ${new Date(earlier.at).toISOString()} and answered HTTP ${earlier.status} without delivering. Paying this endpoint again (with any query or body) would most likely be charged again for nothing; ask the seller, or use another seller.`;
 }