x402-safe-fetch 0.2.0 → 0.3.1

package/README.md

@@ -2,7 +2,7 @@
 
 A `fetch` for AI agents that checks an unknown x402 endpoint before paying it.
 
-A free endpoint is answered as is. For a paid one (HTTP 402), your agent first pays **$0.001** for an [x402 Doctor](https://x402-doctor.onrender.com) preflight and acts on it:
+A free endpoint is answered as is. For a paid one (HTTP 402), your agent first pays **$0.001** for an [x402 Doctor](https://x402-doctor.fizzl.eu) preflight and acts on it:
 
 | Preflight | What `safeFetch` does |
 |---|---|
@@ -35,7 +35,7 @@ const safeFetch = createSafeFetch({
 });
 
 try {
-  const res = await safeFetch("https://ichimoku-signal.onrender.com/signal/BTC-USDT");
+  const res = await safeFetch("https://ichimoku-signal.fizzl.eu/signal/BTC-USDT");
   console.log(await res.json());
 } catch (err) {
   if (err instanceof SafePayError) console.log(err.code, err.message, err.preflight?.reasons);
@@ -57,7 +57,8 @@ Solana works the same way: `network: "solana"` and register an `ExactSvmScheme`
 | `onPreflight` | | `(preflight, { url, method, cached }) => void`, e.g. for logging |
 | `cacheMs` | 10 minutes | How long a verdict is reused per method and URL |
 | `verifyReceipts` | `"require"` | Check Doctor's signed receipt on every preflight; `"off"` skips it |
-| `doctorSigners` | Doctor's published signer | Accepted signer addresses (for a self-hosted Doctor, or after a key rotation) |
+| `doctorSigners` | Doctor's published signer | Accepted signer addresses (for a self-hosted Doctor) |
+| `authority` | the Fizzl payout wallet | Wallet whose certificates also make a signer trusted (key rotation); `null` accepts only `doctorSigners` |
 
 The preflight itself is capped at $0.002 and paid with the same schemes. `receiptOf(response)` returns the payment receipt (transaction hash) of a paid response.
 
@@ -69,6 +70,8 @@ x402 Doctor signs every paid preflight (EIP-191 over canonical JSON, with the re
 - the signature must cover exactly this request: your endpoint, method, budget and network;
 - otherwise it throws `SafePayError` with code `bad_receipt` and **the endpoint is not paid**. A tampered "go", a missing receipt or a verdict for another request never turns into a payment.
 
+**Key rotation:** Doctor's signing key can change without a safe-fetch update. The Fizzl payout wallet (`0x6B0F4651eD42893ab58139938175E4a69f175F25`, the `payTo` of every payment) certifies each key, and the certificate travels inside the receipt (`receipt.cert`). safe-fetch accepts a key that is pinned *or* certified by that wallet for x402 Doctor, for signatures made on or after the certificate's date. Set `authority: null` to accept only `doctorSigners`.
+
 `verifyReceipt(body, { signers, route, input })`, `recoverSigner`, `canonicalJson` and `inputHash` are exported, so you can check any signed Doctor or presign-guard answer yourself.
 
 ## Costs and limits

package/index.d.ts

@@ -5,7 +5,7 @@ export declare const PREFLIGHT_CAP: string;
 export declare const BASE: "eip155:8453";
 export declare const SOLANA: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
 
-/** The x402 Doctor preflight: see https://x402-doctor.onrender.com/openapi.json */
+/** The x402 Doctor preflight: see https://x402-doctor.fizzl.eu/openapi.json */
 export interface Preflight {
   verdict: "go" | "caution" | "no_go";
   summary?: string;
@@ -39,6 +39,8 @@ export interface SafeFetchOptions {
   verifyReceipts?: "require" | "off";
   /** Accepted Doctor signer addresses. Default: the published signer (DOCTOR_SIGNERS). */
   doctorSigners?: string[];
+  /** Wallet whose certificates (receipt.cert) also make a signer trusted, so a rotated Doctor key keeps working. Default: the Fizzl payout wallet; null accepts only doctorSigners. */
+  authority?: string | null;
   fetch?: typeof globalThis.fetch;
   /** Advanced/testing: a paying fetch capped at `cap` (e.g. "$0.05"). */
   createPayingFetch?: (cap: string) => typeof globalThis.fetch;
@@ -54,4 +56,6 @@ export declare const DOCTOR_SIGNERS: string[];
 export declare function canonicalJson(value: unknown): string;
 export declare function inputHash(route: string, input: unknown): string;
 export declare function recoverSigner(message: string, signature: string): string | null;
-export declare function verifyReceipt(body: unknown, options?: { signers?: string[]; route?: string; input?: unknown }): { valid: boolean; signer?: string; reason?: string };
+export declare const AUTHORITY: string;
+export declare function certMessage(cert: { service: string; signer: string; valid_from: string }): string;
+export declare function verifyReceipt(body: unknown, options?: { signers?: string[]; route?: string; input?: unknown; authority?: string | null; service?: string }): { valid: boolean; signer?: string; reason?: string };

package/index.js

@@ -17,11 +17,11 @@
 // your code): register: (client) => client.register("eip155:8453", new ExactEvmScheme(account))
 
 import { wrapFetchWithPayment, x402Client, decodePaymentResponseHeader } from "@x402/fetch";
-import { verifyReceipt, DOCTOR_SIGNERS } from "./receipt.js";
+import { verifyReceipt, DOCTOR_SIGNERS, AUTHORITY } from "./receipt.js";
 
-export { verifyReceipt, recoverSigner, canonicalJson, inputHash, DOCTOR_SIGNERS } from "./receipt.js";
+export { verifyReceipt, recoverSigner, canonicalJson, inputHash, certMessage, DOCTOR_SIGNERS, AUTHORITY } from "./receipt.js";
 
-export const DOCTOR_URL = "https://x402-doctor.onrender.com";
+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 BASE = "eip155:8453";
 export const SOLANA = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
@@ -94,6 +94,7 @@ function requestOf(input, init) {
  * @param {string} [options.doctorUrl]
  * @param {"require"|"off"} [options.verifyReceipts]  check Doctor's signature on every preflight (default "require")
  * @param {string[]} [options.doctorSigners]  accepted Doctor signer addresses (default: the published signer)
+ * @param {string|null} [options.authority]  wallet whose certificates also make a signer trusted (default: the Fizzl payout wallet; null to accept only doctorSigners)
  * @param {typeof fetch} [options.fetch]  the underlying fetch (default globalThis.fetch)
  * @param {(cap: string) => typeof fetch} [options.createPayingFetch]  advanced/testing: a paying fetch capped at `cap`
  * @param {() => number} [options.now]
@@ -109,6 +110,7 @@ export function createSafeFetch({
   doctorUrl = DOCTOR_URL,
   verifyReceipts = "require",
   doctorSigners = DOCTOR_SIGNERS,
+  authority = AUTHORITY,
   fetch: baseFetch = globalThis.fetch,
   createPayingFetch,
   now = Date.now,
@@ -152,7 +154,7 @@ export function createSafeFetch({
     if (verifyReceipts === "require") {
       // Bound to this request: the query Doctor saw, as strings (see Doctor's input_sha256).
       const input = Object.fromEntries(new URL(pfUrl).searchParams);
-      const check = verifyReceipt(preflight, { signers: doctorSigners, route: "GET /api/v1/preflight", input });
+      const check = verifyReceipt(preflight, { signers: doctorSigners, route: "GET /api/v1/preflight", input, authority, service: "x402-doctor" });
       if (!check.valid) throw new SafePayError(`preflight not trusted (${check.reason}); the endpoint was not paid`, { code: "bad_receipt", preflight, url });
     }
     verdicts.set(key, { preflight, expires: now() + cacheMs });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-safe-fetch",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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/receipt.js

@@ -4,21 +4,42 @@
 // README). safe-fetch checks that receipt before acting on a preflight, so a
 // tampered or forged "go" never leads to a payment.
 //
-// Canonical JSON: keys sorted at every level, no whitespace, non-ASCII as
-// \uXXXX (the same bytes as Python's json.dumps(sort_keys=True,
-// separators=(",", ":"), ensure_ascii=True)).
+// Canonical JSON (profile js-json-stringify-sorted-utf16-ascii-v1): keys
+// sorted by UTF-16 code units at every level, no whitespace, every code unit
+// from U+007F up as lowercase \uXXXX, numbers as JSON.stringify writes them,
+// UTF-8 bytes. Python's json.dumps matches only for ASCII keys and integers; a
+// Python equivalent: github.com/Fizzl13/presign-guard/blob/main/examples/canonical.py
 
 import { createHash } from "node:crypto";
 import { secp256k1 } from "@noble/curves/secp256k1";
 import { keccak_256 } from "@noble/hashes/sha3";
 
-// Doctor's published signers (https://x402-doctor.onrender.com/.well-known/x402-doctor-signer.json).
+// Doctor's published signers (https://x402-doctor.fizzl.eu/.well-known/x402-doctor-signer.json).
 // Pinned here on purpose: a signer list fetched from the same server would not
 // protect against that server being compromised.
 export const DOCTOR_SIGNERS = ["0xAaE66eF9Ee234397df33901568c8FBc36d43277d"];
 
+// The payout wallet (the payTo of every Fizzl payment) certifies signing keys:
+// a key it authorised for the service is accepted too, so a rotated Doctor key
+// verifies without a new safe-fetch release. The certificate travels inside
+// the receipt (receipt.cert) as a personal_sign over certMessage.
+export const AUTHORITY = "0x6B0F4651eD42893ab58139938175E4a69f175F25";
+
+export function certMessage({ service, signer, valid_from }) {
+  return `fizzl receipt signer\nservice: ${service}\nsigner: ${signer}\nvalid_from: ${valid_from}`;
+}
+
+// A key the authority certified for `service`, used on or after valid_from.
+export function certifiedSigner(receipt, recovered, { authority = AUTHORITY, service = "x402-doctor" } = {}) {
+  const c = receipt && receipt.cert;
+  if (!c || c.service !== service || String(c.signer).toLowerCase() !== recovered) return false;
+  if (String(c.authority).toLowerCase() !== authority.toLowerCase()) return false;
+  if (!(String(receipt.signed_at).slice(0, 10) >= String(c.valid_from))) return false;
+  return recoverSigner(certMessage(c), c.signature) === authority.toLowerCase();
+}
+
 export function canonicalJson(value) {
-  const ascii = (s) => JSON.stringify(s).replace(/[\u007f-￿]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+  const ascii = (s) => JSON.stringify(s).replace(/[\u007f-\uffff]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
   const walk = (v) => {
     if (v === null || typeof v !== "object") return v === undefined ? undefined : typeof v === "string" ? ascii(v) : JSON.stringify(v);
     if (typeof v.toJSON === "function") return walk(v.toJSON());
@@ -56,13 +77,16 @@ export function recoverSigner(message, signature) {
  * and input) for exactly that request.
  * @returns {{ valid: boolean, signer?: string, reason?: string }}
  */
-export function verifyReceipt(body, { signers = DOCTOR_SIGNERS, route, input } = {}) {
+export function verifyReceipt(body, { signers = DOCTOR_SIGNERS, route, input, authority = AUTHORITY, service = "x402-doctor" } = {}) {
   const r = body && body.receipt;
   if (!r || typeof r.signature !== "string") return { valid: false, reason: "no signed receipt" };
   const { signature, ...rest } = r;
   const recovered = recoverSigner(canonicalJson({ ...body, receipt: rest }), signature);
   if (!recovered || recovered.toLowerCase() !== String(r.signer).toLowerCase()) return { valid: false, reason: "signature does not match: the answer was changed" };
-  if (!signers.some((s) => s.toLowerCase() === recovered)) return { valid: false, signer: recovered, reason: "signed by an unknown key, not x402 Doctor" };
+  const pinned = signers.some((s) => s.toLowerCase() === recovered);
+  if (!pinned && !(authority && certifiedSigner(r, recovered, { authority, service }))) {
+    return { valid: false, signer: recovered, reason: "signed by an unknown key, not x402 Doctor" };
+  }
   if (route !== undefined && input !== undefined && inputHash(route, input) !== r.input_sha256) {
     return { valid: false, signer: recovered, reason: "signed for a different request" };
   }