x402-safe-fetch 0.12.0 → 0.13.0

package/README.md

@@ -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 | |

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.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.12.0";
+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";

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "x402-safe-fetch",
-  "version": "0.12.0",
+  "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"
   ],