agent402-client 0.8.12 → 0.8.14

package/README.md

@@ -351,6 +351,25 @@ const payFetch = wrapFetchWithPayment(fetch, client);
 Pairs with `maxPerCallUsd` / `dailyLimitUsd` (how much) and
 `withNetworkPreference` (which chain).
 
+## Distrusted certificate authorities (`distrustFetch`)
+
+Since 0.8.14 the SDK's own requests refuse a TLS chain that passes through one
+of the intermediate CAs listed in `DISTRUSTED_SPKI_SHA256` (keys reported
+recoverable in Mozilla bug 2083449, which still validate against Node's bundled
+store). The check is keyed on each certificate's SubjectPublicKeyInfo hash and
+runs on a dedicated dispatcher, so nothing changes for the rest of your process.
+Give your payment wrapper the same base fetch so the 402 and the paid retry go
+through it too:
+
+```js
+import { distrustFetch } from "agent402-client";
+const payFetch = wrapFetchWithPayment(distrustFetch(), client);
+```
+
+It applies on Node with the default dispatcher; with a proxy or custom
+dispatcher installed, requests go out through yours unchanged. Pass
+`{ tlsDistrust: false }` to send the default fetch as is.
+
 ## Legal
 
 Use of the hosted instance at agent402.tools is subject to its [Terms of Service](https://agent402.tools/terms) (acceptable-use policy included) and [Privacy Policy](https://agent402.tools/privacy). This package is MIT-licensed; the hosted server is AGPL-3.0. Both are provided as-is without warranty, and self-hosted deployments are their operator's responsibility.

package/index.js

@@ -18,12 +18,14 @@
 //   // paid tools: pass an x402-wrapped fetch (your wallet signs)
 //   const a = new Agent402({ fetch: payFetch });
 import { createHash, randomBytes } from "node:crypto";
+import { distrustFetch } from "./tls-distrust.js";
+export { distrustFetch, distrustDispatcher, distrustCheckServerIdentity, DISTRUSTED_SPKI_SHA256 } from "./tls-distrust.js";
 
 // Keep in lockstep with package.json. Every request the SDK issues carries
 // `User-Agent: agent402-client/<version>` - a standard header, no extra
 // network calls - so a seller can attribute traffic (and settled payments)
 // to this SDK. Product token only; nothing about the caller rides along.
-const VERSION = "0.8.12";
+const VERSION = "0.8.14";
 const USER_AGENT = `agent402-client/${VERSION}`;
 // 32MB: about a hundred times any realistic response from this catalog (the
 // largest is a base64 image at a few MB), so it cannot break a legitimate
@@ -33,13 +35,42 @@ const DEFAULT_MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
 
 const leadingZeroBits = (buf) => { let n = 0; for (const b of buf) { if (b === 0) { n += 8; continue; } n += Math.clz32(b) - 24; break; } return n; };
 
+// Discovery reads (catalog, find, route, skill packs, leaderboard, a
+// proof-of-work challenge) settle nothing, so a 503 the server sheds under
+// load is safe to repeat. It is retried only when it names its own delay
+// (a Retry-After header or a retryAfterSeconds body field), at most
+// DISCOVERY_ATTEMPTS tries in all, each wait capped at DISCOVERY_MAX_WAIT_MS.
+// A paid or priced call never goes through here: a repeat of one could settle
+// twice.
+const DISCOVERY_ATTEMPTS = 3;
+const DISCOVERY_MAX_WAIT_MS = 5000;
+
+/** The wait (ms) a shed 503 asks for, or null when `r` is not one. */
+async function shedRetryWaitMs(r, maxWaitMs = DISCOVERY_MAX_WAIT_MS) {
+  if (!r || r.status !== 503) return null;
+  const header = r.headers && typeof r.headers.get === "function" ? r.headers.get("retry-after") : null;
+  let seconds = header != null && String(header).trim() !== "" ? Number(header) : NaN;
+  if (!Number.isFinite(seconds)) {
+    try {
+      const body = await (typeof r.clone === "function" ? r.clone() : r).json();
+      seconds = Number(body && body.retryAfterSeconds);
+    } catch { seconds = NaN; }
+  }
+  if (!Number.isFinite(seconds) || seconds < 0) return null;
+  return Math.min(seconds * 1000, maxWaitMs);
+}
+
+const sleepMs = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
 export class Agent402 {
   /**
    * @param {object} [opts]
    * @param {string} [opts.baseUrl="https://agent402.tools"]
    * @param {typeof fetch} [opts.fetch]      an x402-wrapped fetch for wallet-only tools (optional)
    * @param {boolean} [opts.cache=true]      cache results in memory (deterministic tools)
-   * @param {typeof fetch} [opts.fetchImpl]  plain fetch (defaults to global fetch)
+   * @param {typeof fetch} [opts.fetchImpl]  plain fetch (defaults to global fetch through distrustFetch)
+   * @param {boolean} [opts.tlsDistrust=true] send the default fetch through distrustFetch (refuses a TLS
+   *                                         chain through a distrusted intermediate CA); false sends it as is
    * @param {number} [opts.maxPerCallUsd]    hard ceiling on a single paid call (USD); over → SpendingLimitError before paying
    * @param {number} [opts.dailyLimitUsd]    hard ceiling on rolling-24h paid spend (USD)
    * @param {number} [opts.maxPerHostUsd]    hard ceiling on rolling-24h paid spend to one seller host (USD)
@@ -51,10 +82,14 @@ export class Agent402 {
    *        Optional buyer-owned result validator. `id` namespaces cache entries;
    *        `validate` may return false or throw to reject delivery.
    */
-  constructor({ baseUrl = "https://agent402.tools", fetch: payFetch, cache = true, fetchImpl = globalThis.fetch,
+  constructor({ baseUrl = "https://agent402.tools", fetch: payFetch, cache = true, fetchImpl = undefined, tlsDistrust = true,
     maxPerCallUsd = null, dailyLimitUsd = null, maxPerHostUsd = null, creditsKey = null,
     maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES, outputValidator = null } = {}) {
     this.creditsKey = typeof creditsKey === "string" && /^a402_[A-Za-z0-9_-]{32,64}$/.test(creditsKey) ? creditsKey : null;
+    if (fetchImpl === undefined) {
+      fetchImpl = globalThis.fetch;
+      if (typeof fetchImpl === "function" && tlsDistrust !== false) fetchImpl = distrustFetch(fetchImpl);
+    }
     if (typeof fetchImpl !== "function") throw new Error("No fetch available - pass { fetchImpl } on Node < 18");
     this.baseUrl = String(baseUrl).replace(/\/$/, "");
     this.payFetch = payFetch || null;
@@ -62,6 +97,8 @@ export class Agent402 {
     // above). Caller-supplied init.headers still win on a key collision.
     this.f = (url, init = {}) => fetchImpl(url, { ...init, headers: { "User-Agent": USER_AGENT, ...(init.headers || {}) } });
     this._catalog = null;
+    // The wait between shed-503 retries of a discovery read (tests replace it).
+    this._sleep = sleepMs;
     this._cache = cache ? new Map() : null;
     // Salt for the default Idempotency-Key: one per client instance, so the key
     // for (slug, params) is stable across call() invocations on THIS client
@@ -147,10 +184,35 @@ export class Agent402 {
     return JSON.parse(Buffer.concat(chunks).toString("utf8"));
   }
 
+  /**
+   * GET a discovery surface, retrying a shed 503 (see DISCOVERY_ATTEMPTS).
+   * Returns the response once it is 2xx; otherwise throws an Error naming the
+   * operation, the surface and the last status, with `.status`, `.surface`
+   * and `.attempts` set.
+   */
+  async _discoveryGet(label, path) {
+    let r;
+    let attempts = 0;
+    for (;;) {
+      attempts++;
+      r = await this.f(`${this.baseUrl}${path}`);
+      if (r.ok) return r;
+      if (attempts >= DISCOVERY_ATTEMPTS) break;
+      const wait = await shedRetryWaitMs(r);
+      if (wait == null) break;
+      await this._sleep(wait);
+    }
+    const surface = path.split("?")[0];
+    const err = new Error(`${label} failed: HTTP ${r.status} from ${surface}${attempts > 1 ? ` after ${attempts} attempts` : ""}`);
+    err.status = r.status;
+    err.surface = surface;
+    err.attempts = attempts;
+    throw err;
+  }
+
   async _loadCatalog() {
     if (this._catalog) return this._catalog;
-    const r = await this.f(`${this.baseUrl}/api/pricing`);
-    if (!r.ok) throw new Error(`could not load catalog: HTTP ${r.status}`);
+    const r = await this._discoveryGet("could not load catalog", "/api/pricing");
     const j = await r.json();
     const m = new Map();
     for (const e of j.endpoints || []) m.set(e.slug, { method: e.method, path: e.path, computePayable: e.computePayable, price: e.price });
@@ -160,8 +222,7 @@ export class Agent402 {
 
   /** Resolve a plain-language task to the best-matching tools (route, price, schema, example). */
   async find(task, { k = 5 } = {}) {
-    const r = await this.f(`${this.baseUrl}/api/find?q=${encodeURIComponent(task)}&k=${k}`);
-    if (!r.ok) throw new Error(`find failed: HTTP ${r.status}`);
+    const r = await this._discoveryGet("find", `/api/find?q=${encodeURIComponent(task)}&k=${k}`);
     return (await r.json()).results || [];
   }
 
@@ -190,8 +251,7 @@ export class Agent402 {
     const includeParam = include === "external" || include === "local" ? include : "all";
     const qs = new URLSearchParams({ q: String(task ?? ""), k: String(top), include: includeParam });
     if (network) qs.set("network", String(network));
-    const r = await this.f(`${this.baseUrl}/api/route?${qs}`);
-    if (!r.ok) throw new Error(`route failed: HTTP ${r.status}`);
+    const r = await this._discoveryGet("route", `/api/route?${qs}`);
     return r.json();
   }
 
@@ -204,8 +264,7 @@ export class Agent402 {
    * to fetch the rendered prompt messages, or hand the slug to an MCP client.
    */
   async findWorkflows(task, { k = 2 } = {}) {
-    const r = await this.f(`${this.baseUrl}/api/find?q=${encodeURIComponent(task)}&k=${k}`);
-    if (!r.ok) throw new Error(`findWorkflows failed: HTTP ${r.status}`);
+    const r = await this._discoveryGet("findWorkflows", `/api/find?q=${encodeURIComponent(task)}&k=${k}`);
     return (await r.json()).packs || [];
   }
 
@@ -216,8 +275,7 @@ export class Agent402 {
    */
   async getWorkflowPrompt(slug, args = {}) {
     const qs = new URLSearchParams(Object.entries(args).map(([k, v]) => [k, String(v)])).toString();
-    const r = await this.f(`${this.baseUrl}/api/skill-packs/${encodeURIComponent(slug)}/prompt${qs ? `?${qs}` : ""}`);
-    if (!r.ok) throw new Error(`getWorkflowPrompt("${slug}") failed: HTTP ${r.status}`);
+    const r = await this._discoveryGet(`getWorkflowPrompt("${slug}")`, `/api/skill-packs/${encodeURIComponent(slug)}/prompt${qs ? `?${qs}` : ""}`);
     return r.json();
   }
 
@@ -238,9 +296,7 @@ export class Agent402 {
     const top = Math.min(Math.max(parseInt(limit, 10) || 10, 1), 50);
     const sortParam = sort === "calls" ? "calls" : "usd";
     const includeParam = include === "all" ? "all" : "external";
-    const url = `${this.baseUrl}/api/leaderboard?top=${top}&sort=${sortParam}&include=${includeParam}`;
-    const r = await this.f(url);
-    if (!r.ok) throw new Error(`topSellers failed: HTTP ${r.status}`);
+    const r = await this._discoveryGet("topSellers", `/api/leaderboard?top=${top}&sort=${sortParam}&include=${includeParam}`);
     const snap = await r.json();
     return {
       window: snap.windowLabel || snap.windowServed || "24h",
@@ -260,10 +316,10 @@ export class Agent402 {
    *
    * @param {string} walletAddress  the caller's wallet address (e.g. "0x...")
    * @param {object} [opts]
-   * @param {typeof fetch} [opts.fetchImpl]  plain fetch (defaults to global fetch)
+   * @param {typeof fetch} [opts.fetchImpl]  plain fetch (defaults to global fetch through distrustFetch)
    * @returns {Promise<{builderCode:string, walletAddress:string}>}
    */
-  static async registerBuilderCode(walletAddress, { fetchImpl = globalThis.fetch } = {}) {
+  static async registerBuilderCode(walletAddress, { fetchImpl = distrustFetch() } = {}) {
     if (!walletAddress || typeof walletAddress !== "string") throw new Error("walletAddress is required");
     const r = await fetchImpl("https://api.base.dev/v1/agents/builder-codes", {
       method: "POST",
@@ -436,8 +492,7 @@ export class Agent402 {
   }
 
   async _powChallenge(slug) {
-    const r = await this.f(`${this.baseUrl}/api/pow/challenge?slug=${encodeURIComponent(slug)}`);
-    if (!r.ok) throw new Error(`proof-of-work challenge for "${slug}" failed: HTTP ${r.status}`);
+    const r = await this._discoveryGet(`proof-of-work challenge for "${slug}"`, `/api/pow/challenge?slug=${encodeURIComponent(slug)}`);
     return r.json();
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-client",
-  "version": "0.8.12",
+  "version": "0.8.14",
   "description": "Agent402 buyer SDK: resolve a task to a tool across 500+ pay-per-call endpoints and call it with payment handled - free via proof-of-work, or over x402 or MPP (a stock mppx fetch works) with a wallet you keep; the buy side of Agentic Finance. Caching, idempotent retries (Idempotency-Key), non-custodial, zero dependencies.",
   "type": "module",
   "main": "index.js",
@@ -9,6 +9,7 @@
   },
   "files": [
     "index.js",
+    "tls-distrust.js",
     "README.md"
   ],
   "engines": {

package/tls-distrust.js

@@ -0,0 +1,110 @@
+// Refuse TLS chains through a distrusted intermediate CA, for this SDK's own
+// requests only (nothing global changes in the caller's process).
+//
+// The private keys of the intermediate CAs below are recoverable (Mozilla bug
+// 2083449). A cross-signed path makes them validate against "emSign ECC Root
+// CA - G3" in Node's bundled store, and Node checks no revocation by default,
+// so a certificate minted with one of these keys for a seller's host would be
+// accepted, and a forged 402 could name a different payTo. The check is keyed
+// on the SubjectPublicKeyInfo sha256 of every certificate in the presented
+// chain. It can be removed once the Node releases this SDK supports ship a CA
+// store that no longer builds the path.
+//
+// distrustFetch(baseFetch) returns a fetch that sends each request through a
+// dedicated undici Agent whose connect.checkServerIdentity refuses such a
+// chain, then runs Node's own hostname check. It applies only while the
+// process-wide dispatcher is still Node's own default; once the caller has
+// installed one (setGlobalDispatcher: a proxy, a custom CA, timeouts), the
+// request goes out through theirs unchanged and their TLS choices win.
+import tls from "node:tls";
+import { createHash, X509Certificate } from "node:crypto";
+
+export const DISTRUSTED_SPKI_SHA256 = Object.freeze({
+  "ebed6475c2c2d80fcb199f3fe8dd6e6b3ce60b77eb15d4e42c3dec0c6f5b5105": "EM DV TLS CA - G3B",
+  "43bffa19d6ef651451f6841e019931e96f6f2eaeff28ab4b6f1ce4576de2717b": "EM OV TLS CA - G3B",
+  "e0254c7fcdc265e2f0f8a428dabb75ab4ae039b4872d62f5ee57f0877d5a8a41": "EM EV TLS CA - G3B",
+  "49dd353dc2b919a3770645117d0e60c16115e7d1bc259eefe734b00ea434fe5f": "EM DV TLS CA - G3C",
+  "63ecefee431d49523bc1136c4e72d0206a477086caf606cd5cf025686c109cf8": "EM OV TLS CA - G3C",
+  "5c0660a2b164910d8ff589c18e14552e9e0ec237dcefe2cb736d41a4811f81a0": "EM EV TLS CA - G3C",
+  "ec4ffa1ad0ac88081314b7aaffef6a91f97cd57291bb5ba686c5415f5eb4f6b6": "EM OV CS CA - G3B",
+  "92c063d67e8f14db71d288e11266ffdaf69cbf115f7bab14f3bc2f68d25e0e30": "EM OV CS CA - G3C",
+});
+
+/** checkServerIdentity that refuses a chain through a listed key (plus any
+ *  `extraSpki` hex hashes), else defers to Node's hostname check. */
+export function distrustCheckServerIdentity(extraSpki = []) {
+  const extra = new Set([...extraSpki].map((h) => String(h).toLowerCase()));
+  const nodeCheck = tls.checkServerIdentity;
+  return (host, cert) => {
+    const seen = [];
+    for (let c = cert; c && typeof c === "object" && !seen.includes(c) && seen.length < 16; c = c.issuerCertificate === c ? null : c.issuerCertificate) {
+      seen.push(c);
+      if (!c.raw) continue;
+      let spki;
+      try {
+        spki = createHash("sha256").update(new X509Certificate(c.raw).publicKey.export({ type: "spki", format: "der" })).digest("hex");
+      } catch {
+        return Object.assign(new Error(`Refusing the TLS certificate for ${host}: distrusted intermediate check could not read the certificate chain`), { code: "ERR_TLS_DISTRUSTED_INTERMEDIATE" });
+      }
+      const name = DISTRUSTED_SPKI_SHA256[spki] || (extra.has(spki) ? "listed key" : null);
+      if (name) return Object.assign(new Error(`Refusing the TLS certificate for ${host}: distrusted intermediate (${name}) in the certificate chain`), { code: "ERR_TLS_DISTRUSTED_INTERMEDIATE" });
+    }
+    return nodeCheck(host, cert);
+  };
+}
+
+const GLOBAL_DISPATCHER = Symbol.for("undici.globalDispatcher.1");
+
+// Node's own default dispatcher, observed when this module loads. Node fills
+// the slot when fetch is first called (synchronously, before any connection),
+// so when the slot is still empty here a data: URL fetch fills it with Node's
+// instance and nothing else can have put it there. When the slot is already
+// filled at load, whoever filled it is unknown and it is treated as the
+// caller's (no dedicated dispatcher), unless another copy of this code (the
+// client and the MCP server share it) observed that same instance as Node's.
+const OBSERVED = Symbol.for("agent402.tlsDistrust.nodeDefaultDispatcher");
+function observeNodeDefault() {
+  if (typeof process !== "object" || !process?.versions?.node || process.versions.bun) return null;
+  const current = globalThis[GLOBAL_DISPATCHER];
+  if (current) return globalThis[OBSERVED] === current ? current : null;
+  if (typeof globalThis.fetch !== "function") return null;
+  try { globalThis.fetch("data:,").catch(() => {}); } catch { return null; }
+  const observed = globalThis[GLOBAL_DISPATCHER] || null;
+  if (observed) Object.defineProperty(globalThis, OBSERVED, { value: observed, configurable: false, enumerable: false, writable: false });
+  return observed;
+}
+const NODE_DEFAULT_DISPATCHER = observeNodeDefault();
+
+/** True when the process-wide dispatcher is not Node's own default: the
+ *  caller installed one, or its origin is unknown. */
+export function callerDispatcherInstalled() {
+  return !NODE_DEFAULT_DISPATCHER || globalThis[GLOBAL_DISPATCHER] !== NODE_DEFAULT_DISPATCHER;
+}
+
+/** A dedicated undici Agent carrying the refusal, or null when this platform
+ *  cannot take one or the caller installed their own global dispatcher (see
+ *  the header). */
+export async function distrustDispatcher({ extraSpki = [] } = {}) {
+  if (callerDispatcherInstalled()) return null;
+  const AgentClass = NODE_DEFAULT_DISPATCHER.constructor;
+  if (typeof AgentClass !== "function") return null;
+  return new AgentClass({ connect: { checkServerIdentity: distrustCheckServerIdentity(extraSpki) } });
+}
+
+/** Wrap a fetch so every request it makes goes through distrustDispatcher().
+ *  With no baseFetch it calls globalThis.fetch as it is at request time. A
+ *  caller's own init.dispatcher, or a global dispatcher the caller installed
+ *  (checked on every request), is left alone. Pass the result as the base
+ *  fetch of a payment wrapper (wrapFetchWithPayment(distrustFetch(), client))
+ *  so the 402 and the paid retry both go through it. */
+export function distrustFetch(baseFetch, opts = {}) {
+  if (baseFetch !== undefined && typeof baseFetch !== "function") throw new Error("distrustFetch needs a fetch function");
+  let pending = null;
+  return async (input, init = {}) => {
+    const f = baseFetch || globalThis.fetch;
+    if (callerDispatcherInstalled() || init?.dispatcher !== undefined) return f(input, init);
+    pending ||= distrustDispatcher(opts).catch(() => null);
+    const dispatcher = await pending;
+    return f(input, dispatcher ? { ...init, dispatcher } : init);
+  };
+}