x402-safe-fetch 0.11.1 → 0.13.0

package/README.md

@@ -6,7 +6,7 @@ A free endpoint is answered as is. For a paid one (HTTP 402), your agent first p
 
 | Preflight | What `safeFetch` does |
 |---|---|
-| `go` | Pays the endpoint, never more than `maxUsd` |
+| `go` | Pays the endpoint, never more than `maxUsd`; with `onIncomplete: "stop"`, not when Doctor says a check couldn't run (`checks_complete: false`) |
 | `caution` | `onCaution`: `"stop"` (default, throws), `"pay"`, or your own function (e.g. ask the user) |
 | `no_go` | Throws `SafePayError`; the endpoint is not paid |
 
@@ -86,6 +86,32 @@ const safeFetch = createSafeFetch({
 
 When a seller offers both, the exact option is paid. The preflight and the budget apply the same way.
 
+## Already have an x402 client? One line
+
+If your agent already pays with the official x402 client (`x402Client` from `@x402/core`, used by `@x402/fetch`, `@x402/axios` and the other transports), you don't have to switch to `safeFetch`. Add the preflight as a hook, and every payment that client makes is checked first:
+
+```js
+import { x402Client } from "@x402/core/client";
+import { wrapFetchWithPayment } from "@x402/fetch";
+import { doctorPreflight } from "x402-safe-fetch/hook";
+
+const client = new x402Client();
+// … register your schemes as before (registerExactEvmScheme(client, { signer }), …)
+client.onBeforePaymentCreation(doctorPreflight({ client, maxUsd: 0.05 }));
+
+const fetchWithPayment = wrapFetchWithPayment(fetch, client); // unchanged
+```
+
+Before the client signs a payment, the hook asks x402 Doctor ($0.001, paid by the same client, or 1 prepaid credit with `creditKey`). Then:
+
+- `no_go`: the payment is aborted (`Payment creation aborted: x402 Doctor: …`). Nothing is signed.
+- `caution`: aborted, unless `onCaution` is `"pay"` or your function says yes.
+- `go`: the payment goes ahead. With `onIncomplete: "stop"`, a `go` whose `checks_complete` is false is aborted too.
+
+The verdict is signed by Doctor and checked, and reused while the endpoint asks the same thing (same payTo, amount, token and network). Doctor's own 402 for the preflight is never checked again and is paid only up to $0.002. Options: `client`, `pay` or `creditKey` (how the preflight is paid), `maxUsd`, `method`, `onCaution`, `onIncomplete`, `onError` (`"stop"` by default), `trusted`, `onPreflight`, `cacheMs`.
+
+The hook can't see your request, only the 402, so Doctor checks the endpoint with `method` (GET by default; it tries the other method too).
+
 ## Options
 
 | Option | Default | |
@@ -94,6 +120,7 @@ When a seller offers both, the exact option is paid. The preflight and the budge
 | `network` | `"base"` | `"base"`, `"solana"`, `"algorand"` (USDC), `"xrpl"` (RLUSD), `"stellar"` (USDC), `"xlayer"` (USD₮0 or USDC), their `-testnet` forms, or a CAIP-2 id; the preflight checks the option on this network |
 | `maxUsd` | `0.05` | Budget per endpoint call; the payment is capped at it and the preflight says `no_go` above it |
 | `onCaution` | `"stop"` | `"stop"`, `"pay"` or `async (preflight) => boolean` |
+| `onIncomplete` | `"pay"` | A `go` whose `checks_complete` is `false` (a check that applies couldn't run this time, named in `not_checked`): `"pay"`, `"stop"` (throws code `incomplete`; not reported to the seller as a refusal) or `async (preflight) => boolean`. Such a verdict is reused for at most 10 minutes |
 | `trusted` | `[]` | Hosts paid without a preflight |
 | `onPreflight` | | `(preflight, { url, method, cached }) => void`, e.g. for logging |
 | `cacheMs` | 1 hour | How long a verdict is reused per method and URL while the 402 offers the same thing (at most 10 minutes when the offer can't be read); any change in price, payout address, token or network means a new preflight |
@@ -146,7 +173,7 @@ With `tellSellers: true`, a refusal also goes straight to the seller, when its 4
 - the sha256 of the refused offer;
 - the endpoint without its query.
 
-No keys, no amounts from your wallet, nothing about you, and no `by` naming safe-fetch, so buyers aren't grouped by the client they use. A `screening_hit` (sanctioned payout address) isn't sent: the draft (0.2) takes it only signed, and safe-fetch holds no key to sign with. It goes only to the endpoint's own site, with redirects refused, at most once a day per endpoint and reason, and never delays the error you get. It works with or without `shareOutcomes`.
+No keys, no amounts from your wallet, nothing about you, and no `by` naming safe-fetch, so buyers aren't grouped by the client they use. A `screening_hit` (sanctioned payout address) isn't sent: the draft takes it only signed, and safe-fetch holds no key to sign with. It goes only to the endpoint's own site, with redirects refused, at most once a day per endpoint and reason, and never delays the error you get. It works with or without `shareOutcomes`.
 
 ## Signed verdicts
 

package/hook.d.ts

@@ -0,0 +1,34 @@
+import type { Preflight } from "./index.js";
+
+export interface DoctorPreflightOptions {
+  /** The x402Client the hook is added to: it pays the $0.001 preflight too (Doctor's own 402 is skipped by the hook). */
+  client?: unknown;
+  /** Or a fetch that pays x402, for the preflight. */
+  pay?: typeof fetch;
+  /** Or prepaid x402 Doctor credits (xdc_…): tried first, then pay or client. */
+  creditKey?: string;
+  /** Your budget per call in USD: Doctor says no_go above it. */
+  maxUsd?: number | string;
+  /** How your calls reach the endpoints. Default "GET"; Doctor tries the other method too. */
+  method?: "GET" | "POST";
+  /** On a caution verdict. Default "stop". */
+  onCaution?: "stop" | "pay" | ((preflight: Preflight) => boolean | Promise<boolean>);
+  /** On a go whose checks_complete is false. Default "pay". */
+  onIncomplete?: "pay" | "stop" | ((preflight: Preflight) => boolean | Promise<boolean>);
+  /** When Doctor can't be asked. Default "stop". */
+  onError?: "stop" | "pay";
+  /** Hosts paid without a preflight. */
+  trusted?: string[];
+  onPreflight?: (preflight: Preflight, info: { url: string; cached: boolean }) => void;
+  /** How long a verdict is reused while the endpoint asks the same thing, in ms. Default 1 hour (10 minutes for an incomplete one). */
+  cacheMs?: number;
+  doctorUrl?: string;
+  verifyReceipts?: "require" | "off";
+  doctorSigners?: string[];
+  authority?: string | null;
+  fetch?: typeof fetch;
+  now?: () => number;
+}
+
+/** A BeforePaymentCreationHook for any @x402/core x402Client: client.onBeforePaymentCreation(doctorPreflight({ client })). */
+export function doctorPreflight(options?: DoctorPreflightOptions): (context: { paymentRequired: unknown; selectedRequirements: unknown }) => Promise<void | { abort: true; reason: string }>;

package/hook.js

@@ -0,0 +1,145 @@
+// x402 Doctor's pre-payment check as a hook for any x402 client (@x402/core x402Client, which @x402/fetch,
+// @x402/axios and the other x402 transports use): one line, and every payment that client makes is checked first.
+//
+//   import { doctorPreflight } from "x402-safe-fetch/hook";
+//   client.onBeforePaymentCreation(doctorPreflight({ client }));
+//
+// Before the client signs a payment, the hook asks Doctor (GET /api/v1/preflight, $0.001, or 1 prepaid credit)
+// whether the endpoint is safe to pay: no_go stops the payment, caution stops it unless onCaution says otherwise,
+// go lets it through. The verdict is signed by Doctor and checked; it is reused while the endpoint asks the same
+// thing. Doctor's own 402 (for the preflight itself) is never checked again, and is paid only up to $0.002.
+import { wrapFetchWithPayment } from "@x402/fetch";
+import { DOCTOR_URL, preflightUrl, VERSION } from "./index.js";
+import { verifyReceipt, DOCTOR_SIGNERS, AUTHORITY } from "./receipt.js";
+
+const CREDIT_HEADER = "x-credit-key";
+const CREDIT_KEY = /^xdc_[A-Za-z0-9_-]{43}$/;
+// The preflight costs $0.001; its own payment is refused above twice that (USDC and the other dollar tokens Doctor
+// takes have 6 decimals; RLUSD on the XRP Ledger is a decimal amount).
+const PREFLIGHT_MAX_ATOMIC = 2000n;
+const PREFLIGHT_MAX_DECIMAL = 0.002;
+
+const hostOf = (u) => { try { return new URL(u).host; } catch { return null; } };
+const abort = (reason) => ({ abort: true, reason: String(reason).slice(0, 300) });
+
+// Within the preflight's price: atomic units (EVM, Solana, Algorand, Stellar) or a decimal amount (XRPL RLUSD).
+function withinPreflightPrice(amount) {
+  const s = String(amount ?? "");
+  if (/^\d+$/.test(s)) return BigInt(s) <= PREFLIGHT_MAX_ATOMIC;
+  const n = Number(s);
+  return Number.isFinite(n) && n > 0 && n <= PREFLIGHT_MAX_DECIMAL;
+}
+
+/**
+ * @param {object} options
+ * @param {object} [options.client]  the x402Client the hook is added to: it pays the preflight too (the hook skips Doctor's own 402)
+ * @param {typeof fetch} [options.pay]  or a fetch that pays x402, for the preflight
+ * @param {string} [options.creditKey]  or prepaid Doctor credits (xdc_…): tried first, then pay or client
+ * @param {number|string} [options.maxUsd]  your budget per call: Doctor says no_go above it
+ * @param {"GET"|"POST"} [options.method]  how your calls reach the endpoints (Doctor tries the other method too)
+ * @param {"stop"|"pay"|((preflight: object) => boolean|Promise<boolean>)} [options.onCaution]  default "stop"
+ * @param {"pay"|"stop"|((preflight: object) => boolean|Promise<boolean>)} [options.onIncomplete]  a go whose checks_complete is false; default "pay"
+ * @param {"stop"|"pay"} [options.onError]  when Doctor can't be asked; default "stop"
+ * @param {string[]} [options.trusted]  hosts paid without a preflight
+ * @param {(preflight: object, info: {url: string, cached: boolean}) => void} [options.onPreflight]
+ * @param {number} [options.cacheMs]  how long a verdict is reused while the endpoint asks the same thing (default 1 hour)
+ * @param {"require"|"off"} [options.verifyReceipts]  check Doctor's signature (default "require")
+ * @returns {(context: {paymentRequired: object, selectedRequirements: object}) => Promise<void|{abort: true, reason: string}>}
+ */
+export function doctorPreflight({
+  client,
+  pay,
+  creditKey,
+  maxUsd,
+  method = "GET",
+  onCaution = "stop",
+  onIncomplete = "pay",
+  onError = "stop",
+  trusted = [],
+  onPreflight,
+  cacheMs = 60 * 60 * 1000,
+  doctorUrl = DOCTOR_URL,
+  verifyReceipts = "require",
+  doctorSigners = DOCTOR_SIGNERS,
+  authority = AUTHORITY,
+  fetch: plainFetch = globalThis.fetch,
+  now = Date.now,
+} = {}) {
+  if (!client && typeof pay !== "function" && !creditKey) throw new TypeError("doctorPreflight needs a way to pay the $0.001 preflight: client, pay or creditKey");
+  if (creditKey !== undefined && !CREDIT_KEY.test(String(creditKey))) throw new TypeError("creditKey must be an x402 Doctor credit key (xdc_…)");
+  if (!["stop", "pay"].includes(onCaution) && typeof onCaution !== "function") throw new TypeError('onCaution must be "stop", "pay" or a function');
+  if (!["pay", "stop"].includes(onIncomplete) && typeof onIncomplete !== "function") throw new TypeError('onIncomplete must be "pay", "stop" or a function');
+  if (!["stop", "pay"].includes(onError)) throw new TypeError('onError must be "stop" or "pay"');
+  if (!["require", "off"].includes(verifyReceipts)) throw new TypeError('verifyReceipts must be "require" or "off"');
+  const doctorHost = hostOf(doctorUrl);
+  const trustedHosts = new Set(trusted.map((t) => hostOf(/^https?:/.test(t) ? t : `https://${t}`)).filter(Boolean));
+  let payingFetch = typeof pay === "function" ? pay : null;
+  const payer = () => (payingFetch ??= client ? wrapFetchWithPayment(plainFetch, client) : null);
+  const headers = { accept: "application/json", "user-agent": `x402-safe-fetch/${VERSION} (hook)` };
+  const verdicts = new Map();
+
+  async function ask(url, network) {
+    const pfUrl = preflightUrl(url, { method, maxUsd, network, doctorUrl });
+    let res = null;
+    if (creditKey) {
+      res = await plainFetch(pfUrl, { headers: { ...headers, [CREDIT_HEADER]: creditKey } });
+      if (res.status === 402) res = null; // credits used up or unknown: pay instead, if we can
+    }
+    if (!res) {
+      const f = payer();
+      if (!f) throw new Error("no prepaid credits left and nothing to pay the preflight with");
+      res = await f(pfUrl, { headers });
+    }
+    const preflight = await res.json().catch(() => null);
+    if (!res.ok || !preflight?.verdict) throw new Error(`preflight answered HTTP ${res.status}`);
+    if (verifyReceipts === "require") {
+      const input = Object.fromEntries(new URL(pfUrl).searchParams);
+      const check = verifyReceipt(preflight, { signers: doctorSigners, route: "GET /api/v1/preflight", input, authority, service: "x402-doctor" });
+      if (!check.valid) throw new Error(`preflight not trusted (${check.reason})`);
+    }
+    return preflight;
+  }
+
+  return async function doctorPreflightHook({ paymentRequired, selectedRequirements } = {}) {
+    const url = paymentRequired?.resource?.url;
+    const host = hostOf(url);
+    // Doctor's own 402, for the preflight we are paying: never checked again, and never more than its price.
+    if (host && host === doctorHost) {
+      return withinPreflightPrice(selectedRequirements?.amount ?? selectedRequirements?.maxAmountRequired) ? undefined : abort("x402 Doctor's preflight asked more than $0.002");
+    }
+    if (!url || (host && trustedHosts.has(host))) return undefined;
+
+    const r = selectedRequirements || {};
+    const key = JSON.stringify([url, r.network, r.asset, String(r.amount ?? r.maxAmountRequired ?? ""), r.payTo]);
+    const hit = verdicts.get(key);
+    const ttl = hit?.preflight?.checks_complete === false ? Math.min(cacheMs, 10 * 60 * 1000) : cacheMs;
+    let preflight;
+    let cached = false;
+    if (hit && hit.at + ttl > now()) {
+      preflight = hit.preflight;
+      cached = true;
+    } else {
+      try {
+        preflight = await ask(url, r.network);
+      } catch (err) {
+        return onError === "pay" ? undefined : abort(`x402 Doctor's preflight failed (${err.message}); not paid`);
+      }
+      verdicts.set(key, { preflight, at: now() });
+      if (verdicts.size > 1000) verdicts.delete(verdicts.keys().next().value);
+    }
+    onPreflight?.(preflight, { url, cached });
+
+    const why = preflight.summary || preflight.verdict;
+    if (preflight.verdict === "no_go") return abort(`x402 Doctor: ${why}`);
+    if (preflight.verdict === "caution") {
+      const ok = onCaution === "pay" || (typeof onCaution === "function" && (await onCaution(preflight)) === true);
+      return ok ? undefined : abort(`x402 Doctor (caution): ${why}`);
+    }
+    if (preflight.verdict !== "go") return abort(`x402 Doctor: unknown verdict ${preflight.verdict}`);
+    if (preflight.checks_complete === false && onIncomplete !== "pay") {
+      const ok = typeof onIncomplete === "function" && (await onIncomplete(preflight)) === true;
+      if (!ok) return abort("x402 Doctor: go, but not every check ran; try again in a few minutes");
+    }
+    return undefined;
+  };
+}

package/index.d.ts

@@ -26,6 +26,10 @@ export interface Preflight {
   summary?: string;
   reasons?: Array<{ level: string; code?: string; message: string }>;
   signals?: Record<string, unknown>;
+  checked?: Array<{ check: string; what: string }>;
+  not_checked?: Array<{ check: string; because: "unavailable" | "no_data" | "not_sent" | "out_of_scope"; why: string; send?: string }>;
+  /** false when a check that applies couldn't run this time */
+  checks_complete?: boolean;
   [key: string]: unknown;
 }
 
@@ -37,7 +41,7 @@ export interface Diagnosis {
 }
 
 export declare class SafePayError extends Error {
-  code: "no_go" | "caution" | "preflight_failed" | "bad_receipt" | "no_option";
+  code: "no_go" | "caution" | "incomplete" | "preflight_failed" | "bad_receipt" | "no_option";
   preflight: Preflight | null;
   url: string | null;
   /** Set when diagnoseOnFailure diagnosed a payment that failed. */
@@ -53,6 +57,8 @@ export interface SafeFetchOptions {
   maxUsd?: number | string;
   /** What to do on a caution verdict. Default "stop". */
   onCaution?: "stop" | "pay" | ((preflight: Preflight) => boolean | Promise<boolean>);
+  /** What to do on a "go" whose checks_complete is false (a check that applies couldn't run). Default "pay"; "stop" throws code "incomplete". */
+  onIncomplete?: "pay" | "stop" | ((preflight: Preflight) => boolean | Promise<boolean>);
   /** Hosts you already trust: paid without a preflight. */
   trusted?: string[];
   onPreflight?: (preflight: Preflight, info: { url: string; method: string; cached: boolean }) => void;

package/index.js

@@ -41,7 +41,7 @@ export { verifyReceipt, recoverSigner, canonicalJson, inputHash, certMessage, DO
 export const DOCTOR_URL = "https://x402-doctor.fizzl.eu";
 export const PREFLIGHT_CAP = "$0.002"; // the preflight costs $0.001; never more than twice that
 export const DIAGNOSE_CAP = "$0.02"; // the diagnosis costs $0.01; never more than twice that
-export const VERSION = "0.11.1";
+export const VERSION = "0.13.0";
 // 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";
@@ -230,6 +230,8 @@ function sameSite(a, b) {
  * @param {string} [options.network]  the network you pay on: "base", "solana", "algorand", "xrpl", "stellar" or a CAIP-2 id (default Base)
  * @param {number|string} [options.maxUsd]  budget per endpoint call (default 0.05)
  * @param {"stop"|"pay"|((preflight: object) => boolean|Promise<boolean>)} [options.onCaution]
+ * @param {"pay"|"stop"|((preflight: object) => boolean|Promise<boolean>)} [options.onIncomplete]  a "go" whose checks_complete
+ *   is false (a check that applies couldn't run): "pay" (default), "stop" throws code "incomplete", a function decides
  * @param {string[]} [options.trusted]  hosts you already trust: paid without a preflight
  * @param {(preflight: object, info: {url: string, method: string, cached: boolean}) => void} [options.onPreflight]
  * @param {number} [options.cacheMs]  how long a verdict is reused while the 402 offers the same thing (default 1 hour; at most 10 minutes when the offer can't be read)
@@ -250,6 +252,7 @@ export function createSafeFetch({
   network = BASE,
   maxUsd = 0.05,
   onCaution = "stop",
+  onIncomplete = "pay",
   trusted = [],
   onPreflight,
   cacheMs = 60 * 60 * 1000,
@@ -273,6 +276,9 @@ export function createSafeFetch({
   if (!["stop", "pay"].includes(onCaution) && typeof onCaution !== "function") {
     throw new TypeError('onCaution must be "stop", "pay" or a function');
   }
+  if (!["pay", "stop"].includes(onIncomplete) && typeof onIncomplete !== "function") {
+    throw new TypeError('onIncomplete must be "pay", "stop" or a function');
+  }
   if (!["require", "off"].includes(verifyReceipts)) throw new TypeError('verifyReceipts must be "require" or "off"');
   const trustedHosts = new Set(trusted.map(hostOf).filter(Boolean));
 
@@ -309,7 +315,9 @@ export function createSafeFetch({
   async function preflightFor(url, method, offer) {
     const key = `${method} ${url}`;
     const hit = verdicts.get(key);
-    const ttl = offer === null ? Math.min(cacheMs, UNREAD_OFFER_MS) : cacheMs;
+    // An unreadable offer, or a verdict on less than usual (checks_complete false), is reused for at most 10 minutes.
+    const short = offer === null || hit?.preflight?.checks_complete === false;
+    const ttl = short ? Math.min(cacheMs, UNREAD_OFFER_MS) : cacheMs;
     if (hit && hit.offer === offer && hit.at + ttl > now()) return { preflight: hit.preflight, cached: true };
     const pfUrl = preflightUrl(url, { method, maxUsd: budget, network: payNetwork, doctorUrl });
     const res = await payPreflight(pfUrl, { headers: DOCTOR_HEADERS });
@@ -391,7 +399,7 @@ export function createSafeFetch({
     if (target.protocol !== "https:" && !["localhost", "127.0.0.1"].includes(target.hostname)) return;
     if (!sameSite(target.hostname, endpoint.hostname)) return;
     if (refusal.report.resource !== `${endpoint.origin}${endpoint.pathname}`) return;
-    // The draft (0.2) takes a screening_hit only signed, and this client holds no key to sign with.
+    // The draft takes a screening_hit only signed, and this client holds no key to sign with.
     if (refusal.signature_required || (refusal.report.reason === "screening_hit" && !refusal.report.signature)) return;
     const key = `${refusal.report.resource} ${refusal.report.reason}`;
     if (now() - (toldSellers.get(key) ?? -Infinity) < 24 * 60 * 60 * 1000) return;
@@ -468,6 +476,12 @@ export function createSafeFetch({
       }
     } else if (preflight.verdict !== "go") {
       throw new SafePayError(`not paid: unknown verdict ${preflight.verdict}`, { code: "preflight_failed", preflight, url });
+    } else if (preflight.checks_complete === false && onIncomplete !== "pay") {
+      // "go" on less than usual: a check that applies couldn't run (Doctor's not_checked says which). Not the seller's
+      // doing, so no refusal is reported to it.
+      const ok = typeof onIncomplete === "function" && (await onIncomplete(preflight)) === true;
+      const missing = (preflight.not_checked || []).filter((n) => n?.because === "unavailable").map((n) => n.check).join(", ") || "unknown";
+      if (!ok) throw new SafePayError(`not paid: go, but not every check ran (${missing}); try again in a few minutes`, { code: "incomplete", preflight, url });
     }
     return payAfterPreflight();
   };

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "x402-safe-fetch",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "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": {
     ".": {
       "types": "./index.d.ts",
       "default": "./index.js"
+    },
+    "./hook": {
+      "types": "./hook.d.ts",
+      "default": "./hook.js"
     }
   },
   "main": "./index.js",
@@ -14,7 +18,9 @@
   "files": [
     "index.js",
     "receipt.js",
+    "hook.js",
     "index.d.ts",
+    "hook.d.ts",
     "README.md",
     "LICENSE"
   ],