x402-safe-fetch 0.2.0 → 0.3.0

package/README.md

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

@@ -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,9 +17,9 @@
 // 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 PREFLIGHT_CAP = "$0.002"; // the preflight costs $0.001; never more than twice that
@@ -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.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": {

package/receipt.js

@@ -17,8 +17,27 @@ import { keccak_256 } from "@noble/hashes/sha3";
 // 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 +75,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" };
   }