@profullstack/x402-client 0.1.0

package/src/client.js

@@ -0,0 +1,230 @@
+/**
+ * The client: a `fetch` that pays.
+ *
+ * The shape of a paid request, as every x402 server does it:
+ *
+ *   1. ask for the resource; get 402 with an offer
+ *   2. pick an option the wallet can sign, sign an EIP-3009 authorization
+ *      for exactly that amount to exactly that address, and ask again with
+ *      the proof in a header
+ *   3. get the resource — or, from a gateway selling time rather than pages,
+ *      a receipt naming a pass, which then opens every page for a day
+ *
+ * Step 3 is the reason this is a client and not a function: a pass is worth
+ * remembering, and a crawler that forgets it pays for the same day on every
+ * page. Passes are filed by origin and presented automatically.
+ *
+ * Two rules keep a key-holding client from being a footgun. It never pays
+ * twice for one request: a second 402 after a proof means the payment was
+ * refused, and signing another authorization for a server that just refused
+ * one would be spending on a guess. And it never pays more than `maxUsd`,
+ * which defaults low enough that a misconfigured server or a hostile one
+ * cannot drain a wallet by asking.
+ */
+
+import { fileStore, memoryStore, originOf } from './passes.js';
+import { walletFromKey } from './wallet.js';
+import { amountUsd, readOffer, readReceipt, selectAccept, signPayment } from './x402.js';
+
+/**
+ * A failure with a name a program can switch on.
+ *
+ * `code` is one of `no-key` (nothing to sign with), `no-offer` (402 without
+ * x402 in it), `no-option` (nothing signable in the offer), `too-expensive`
+ * (over `maxUsd`, or unpriceable), `rejected` (the server refused the proof).
+ */
+export class X402Error extends Error {
+  /**
+   * @param {string} code
+   * @param {string} message
+   * @param {{ status?: number, body?: any, offer?: object|null, url?: string }} [detail]
+   */
+  constructor(code, message, detail = {}) {
+    super(message);
+    this.name = 'X402Error';
+    this.code = code;
+    this.status = detail.status ?? null;
+    this.body = detail.body ?? null;
+    this.offer = detail.offer ?? null;
+    this.url = detail.url ?? null;
+  }
+}
+
+/** The default ceiling on one payment, in dollars. A day of crawling costs one. */
+export const DEFAULT_MAX_USD = 5;
+
+/**
+ * @param {import('../index.d.ts').ClientOptions} [options]
+ * @returns {import('../index.d.ts').X402Client}
+ */
+export function createClient(options = {}) {
+  const {
+    key,
+    networks,
+    maxUsd = DEFAULT_MAX_USD,
+    validForSeconds,
+    userAgent,
+    fetch: f = globalThis.fetch,
+  } = options;
+
+  const wallet = options.wallet ?? (key ? walletFromKey(key) : null);
+  const store = options.store === 'file' ? fileStore() : (options.store ?? memoryStore());
+
+  const baseHeaders = (init) => {
+    const headers = new Headers(init?.headers ?? {});
+    if (userAgent && !headers.has('user-agent')) headers.set('user-agent', userAgent);
+    return headers;
+  };
+
+  /** The live pass for a URL's origin, if one is filed. */
+  const passFor = (url) => store.get(originOf(url));
+
+  /**
+   * Pay for a URL and file whatever pass comes back.
+   *
+   * With no `offer` given, the URL is asked first, as JSON, to get one. The
+   * proof is sent on the same request the offer came from: a gateway wants it
+   * on the page or on `/crawl`, a plain resource wants it on itself.
+   */
+  const pay = async (url, { offer: given, init = {} } = {}) => {
+    const target = String(url instanceof Request ? url.url : url);
+    if (!wallet) throw new X402Error('no-key', 'Nothing to pay with: create the client with a `key` or a `wallet`', { url: target });
+
+    let offer = given ?? null;
+    let body = null;
+    if (!offer) {
+      const headers = baseHeaders(init);
+      if (!headers.has('accept')) headers.set('accept', 'application/json');
+      const first = await f(target, { ...init, headers });
+      if (first.status !== 402) {
+        throw new X402Error('no-offer', `${target} answered ${first.status}, not 402; there is nothing to pay for`, {
+          status: first.status,
+          url: target,
+        });
+      }
+      ({ offer, body } = await readOffer(first));
+      if (!offer) {
+        throw new X402Error('no-offer', `${target} answered 402 without an x402 offer`, { status: 402, body, url: target });
+      }
+    }
+
+    const entry = selectAccept(offer.accepts, { networks });
+    if (!entry) {
+      const offered = (offer.accepts ?? []).map((a) => a?.network).filter(Boolean).join(', ') || 'nothing';
+      throw new X402Error('no-option', `The offer has no option this wallet can sign (offered: ${offered})`, { offer, url: target });
+    }
+
+    const usd = amountUsd(entry);
+    if (usd === null || usd > maxUsd) {
+      const price = usd === null ? 'a token this client cannot price' : `$${usd.toFixed(2)}`;
+      throw new X402Error('too-expensive', `Refusing to pay ${price} for ${target}; the ceiling is $${maxUsd} (maxUsd)`, {
+        offer,
+        url: target,
+      });
+    }
+
+    const { header, authorization, payment } = signPayment(entry, wallet, { validForSeconds });
+
+    const headers = baseHeaders(init);
+    // CoinPay's dialect reads the v1 name; v2 facilitators read the other.
+    // Sending both costs a few hundred bytes and works against either.
+    headers.set('x-payment', header);
+    headers.set('payment-signature', header);
+    if (!headers.has('accept')) headers.set('accept', 'application/json');
+
+    const paid = await f(target, { ...init, headers });
+    const text = await paid.text();
+    let json = null;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      json = null;
+    }
+
+    if (paid.status === 402) {
+      const reason = json?.error ?? (text.slice(0, 200) || String(paid.status));
+      throw new X402Error('rejected', `${target} refused the payment: ${reason}`, {
+        status: 402,
+        body: json ?? text,
+        offer,
+        url: target,
+      });
+    }
+
+    const receipt = readReceipt(paid, json);
+    if (receipt.pass) {
+      store.set(originOf(target), {
+        token: receipt.pass,
+        header: receipt.header,
+        expires: receipt.expires,
+        boughtAt: new Date().toISOString(),
+        url: target,
+      });
+    }
+
+    return {
+      status: paid.status,
+      body: json ?? text,
+      receipt,
+      payer: wallet.address,
+      network: entry.network,
+      amount: authorization.value,
+      amountUsd: usd,
+      payTo: entry.payTo,
+      nonce: authorization.nonce,
+      payment,
+    };
+  };
+
+  /**
+   * `fetch`, paying once if asked to.
+   *
+   * A filed pass is presented on the way in. On a 402 the offer is paid, and
+   * then: a pass means the original request is made again with it, since a
+   * gateway's receipt is not the page; no pass means the paid response was
+   * the resource and is returned as it came.
+   */
+  const paidFetch = async (input, init = {}, { pay: shouldPay = true } = {}) => {
+    const target = String(input instanceof Request ? input.url : input);
+    const headers = baseHeaders(init);
+
+    const filed = passFor(target);
+    if (filed) headers.set(filed.header, filed.token);
+
+    const first = await f(target, { ...init, headers });
+    if (first.status !== 402 || !shouldPay) return first;
+
+    const { offer, body } = await readOffer(first);
+    if (!offer) {
+      // A 402 that is not x402 is the server's to explain, so hand it back
+      // whole rather than as an exception about a protocol it does not speak.
+      return new Response(typeof body === 'string' ? body : JSON.stringify(body), {
+        status: 402,
+        statusText: first.statusText,
+        headers: first.headers,
+      });
+    }
+
+    const result = await pay(target, { offer, init });
+    if (!result.receipt.pass) {
+      return new Response(typeof result.body === 'string' ? result.body : JSON.stringify(result.body), {
+        status: result.status,
+        headers: { 'content-type': typeof result.body === 'string' ? 'text/plain' : 'application/json' },
+      });
+    }
+
+    const again = baseHeaders(init);
+    again.set(result.receipt.header, result.receipt.pass);
+    return f(target, { ...init, headers: again });
+  };
+
+  return {
+    get address() {
+      return wallet?.address ?? null;
+    },
+    store,
+    fetch: paidFetch,
+    pay,
+    passFor,
+  };
+}

package/src/eip712.js

@@ -0,0 +1,256 @@
+/**
+ * EIP-712 typed-data hashing and signing.
+ *
+ * x402's `exact` scheme on EVM is an EIP-3009 `TransferWithAuthorization`,
+ * and that is typed data rather than a transaction: the signature IS the
+ * payment, and whoever holds it can call `transferWithAuthorization` on the
+ * token and move the funds. So the one thing a payer has to get exactly right
+ * is this encoding.
+ *
+ * A port of the signer in CoinPay Wallet (`packages/extension/src/core/
+ * eip712.ts`), which was cross-checked byte for byte against ethers. The
+ * parity test in `test/eip712.test.js` holds this port to a digest and a
+ * signature produced by that original, so the two cannot drift.
+ *
+ * Built on `@noble/curves` and `@noble/hashes` rather than ethers or viem:
+ * one hash function and one signature do not justify a megabyte.
+ *
+ * Only the encodings EIP-3009 needs are implemented: atomic types plus
+ * `string` and `bytes`. Nested structs and arrays throw rather than encode
+ * wrongly, because a silently wrong encoding produces a signature that
+ * recovers to some other address, and the only symptom is an authorization
+ * nobody can spend.
+ */
+
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { keccak_256 } from '@noble/hashes/sha3.js';
+
+/** Fields of EIP712Domain, in the order the spec fixes. */
+const DOMAIN_FIELDS = [
+  { name: 'name', type: 'string' },
+  { name: 'version', type: 'string' },
+  { name: 'chainId', type: 'uint256' },
+  { name: 'verifyingContract', type: 'address' },
+  { name: 'salt', type: 'bytes32' },
+];
+
+const utf8 = new TextEncoder();
+
+/**
+ * @param {string} hex
+ * @returns {Uint8Array}
+ */
+export function hexToBytes(hex) {
+  const clean = hex.startsWith('0x') || hex.startsWith('0X') ? hex.slice(2) : hex;
+  if (clean.length % 2 !== 0) throw new Error(`Odd-length hex: ${hex}`);
+  if (clean.length > 0 && !/^[0-9a-fA-F]+$/.test(clean)) throw new Error(`Not hex: ${hex}`);
+  const out = new Uint8Array(clean.length / 2);
+  for (let i = 0; i < out.length; i++) out[i] = Number.parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+  return out;
+}
+
+/**
+ * @param {Uint8Array} bytes
+ * @returns {string} `0x`-prefixed lowercase hex
+ */
+export function bytesToHex(bytes) {
+  let hex = '';
+  for (const b of bytes) hex += b.toString(16).padStart(2, '0');
+  return `0x${hex}`;
+}
+
+/** A 32-byte big-endian encoding of a non-negative integer. */
+function encodeUint(value) {
+  let n;
+  try {
+    n = BigInt(value);
+  } catch {
+    throw new Error(`Not an integer: ${String(value)}`);
+  }
+  if (n < 0n) throw new Error(`Negative value for an unsigned field: ${n}`);
+  if (n >= 1n << 256n) throw new Error(`Value exceeds uint256: ${n}`);
+  const out = new Uint8Array(32);
+  for (let i = 31; i >= 0 && n > 0n; i--) {
+    out[i] = Number(n & 0xffn);
+    n >>= 8n;
+  }
+  return out;
+}
+
+/** A 20-byte address, left-padded into a 32-byte word. */
+function encodeAddress(value) {
+  const bytes = hexToBytes(String(value));
+  if (bytes.length !== 20) throw new Error(`Address must be 20 bytes, got ${bytes.length}: ${String(value)}`);
+  const out = new Uint8Array(32);
+  out.set(bytes, 12);
+  return out;
+}
+
+/** Encode one field to its 32-byte EIP-712 representation. */
+function encodeValue(type, value) {
+  if (type === 'string') return keccak_256(utf8.encode(String(value ?? '')));
+  if (type === 'bytes') return keccak_256(hexToBytes(String(value ?? '0x')));
+  if (type === 'address') return encodeAddress(value);
+  if (type === 'bool') {
+    const out = new Uint8Array(32);
+    out[31] = value ? 1 : 0;
+    return out;
+  }
+
+  const fixedBytes = /^bytes([0-9]{1,2})$/.exec(type);
+  if (fixedBytes) {
+    const width = Number(fixedBytes[1]);
+    if (width < 1 || width > 32) throw new Error(`Invalid fixed-bytes width: ${type}`);
+    const bytes = hexToBytes(String(value));
+    if (bytes.length !== width) throw new Error(`${type} must be ${width} bytes, got ${bytes.length}`);
+    const out = new Uint8Array(32);
+    out.set(bytes, 0); // fixed bytes are RIGHT-padded
+    return out;
+  }
+
+  if (/^uint([0-9]{1,3})?$/.test(type)) return encodeUint(value);
+
+  // Arrays and nested structs would need recursive encoding. Refusing is the
+  // only safe response: a wrong encoding still yields a valid-looking
+  // signature, for an authorization that recovers to the wrong signer.
+  throw new Error(`Unsupported EIP-712 type: ${type}`);
+}
+
+/**
+ * The canonical type string, e.g.
+ * `TransferWithAuthorization(address from,address to,...)`.
+ *
+ * @param {string} primaryType
+ * @param {Record<string, {name: string, type: string}[]>} types
+ */
+export function encodeType(primaryType, types) {
+  const fields = types[primaryType];
+  if (!fields) throw new Error(`Unknown type: ${primaryType}`);
+  return `${primaryType}(${fields.map((f) => `${f.type} ${f.name}`).join(',')})`;
+}
+
+export function typeHash(primaryType, types) {
+  return keccak_256(utf8.encode(encodeType(primaryType, types)));
+}
+
+/** `keccak256(typeHash ‖ encodeData(...))`. */
+export function hashStruct(primaryType, types, data) {
+  const fields = types[primaryType];
+  if (!fields) throw new Error(`Unknown type: ${primaryType}`);
+  const parts = [typeHash(primaryType, types)];
+  for (const field of fields) parts.push(encodeValue(field.type, data[field.name]));
+  const buf = new Uint8Array(parts.length * 32);
+  parts.forEach((p, i) => buf.set(p, i * 32));
+  return keccak_256(buf);
+}
+
+/**
+ * The domain separator.
+ *
+ * Only the fields actually present are included, and in the spec's order. A
+ * domain that lists a field the token omits (or vice versa) hashes to a
+ * different separator, and the signature is then rejected on-chain.
+ */
+export function hashDomain(domain) {
+  const present = DOMAIN_FIELDS.filter((f) => domain[f.name] !== undefined);
+  if (present.length === 0) throw new Error('EIP-712 domain is empty');
+  return hashStruct('EIP712Domain', { EIP712Domain: present }, domain);
+}
+
+/**
+ * The 32-byte digest a signature is made over:
+ * `keccak256(0x19 ‖ 0x01 ‖ domainSeparator ‖ hashStruct(message))`.
+ */
+export function eip712Digest(domain, types, primaryType, message) {
+  const preimage = new Uint8Array(2 + 32 + 32);
+  preimage[0] = 0x19;
+  preimage[1] = 0x01;
+  preimage.set(hashDomain(domain), 2);
+  preimage.set(hashStruct(primaryType, types, message), 34);
+  return keccak_256(preimage);
+}
+
+/**
+ * Sign typed data, returning a 65-byte `r ‖ s ‖ v` signature as hex.
+ *
+ * `v` is 27/28 rather than 0/1. Both conventions exist, but Solidity's
+ * `ecrecover` — which is what `transferWithAuthorization` calls — expects
+ * 27/28, and a signature with a raw recovery bit simply recovers to the zero
+ * address there.
+ *
+ * @param {object} domain
+ * @param {Record<string, {name: string, type: string}[]>} types
+ * @param {string} primaryType
+ * @param {Record<string, unknown>} message
+ * @param {Uint8Array} privateKey 32 bytes
+ * @returns {string}
+ */
+export function signTypedData(domain, types, primaryType, message, privateKey) {
+  const digest = eip712Digest(domain, types, primaryType, message);
+
+  // `format: 'recovered'` yields [recovery, r(32), s(32)]. `prehash: false`
+  // because the digest is already the hash to sign — hashing it again would
+  // sign the wrong thing.
+  const signed = secp256k1.sign(digest, privateKey, { format: 'recovered', prehash: false });
+  if (signed.length !== 65) throw new Error(`Expected a 65-byte recovered signature, got ${signed.length}`);
+
+  const out = new Uint8Array(65);
+  out.set(signed.slice(1, 65), 0); // r ‖ s
+  out[64] = signed[0] + 27;
+  return bytesToHex(out);
+}
+
+/**
+ * The address that produced a signature over typed data, for checking one.
+ *
+ * The inverse of {@link signTypedData}: accepts the same 27/28 `v`, and
+ * returns a checksummed address. Used by the tests and by anyone verifying a
+ * proof locally before forwarding it.
+ *
+ * @returns {string}
+ */
+export function recoverTypedDataSigner(domain, types, primaryType, message, signature) {
+  const sig = hexToBytes(signature);
+  if (sig.length !== 65) throw new Error(`Expected a 65-byte signature, got ${sig.length}`);
+  const v = sig[64];
+  const recovery = v >= 27 ? v - 27 : v;
+  if (recovery !== 0 && recovery !== 1) throw new Error(`Bad recovery id in signature: ${v}`);
+
+  const recovered = new Uint8Array(65);
+  recovered[0] = recovery;
+  recovered.set(sig.slice(0, 64), 1);
+
+  const digest = eip712Digest(domain, types, primaryType, message);
+  const publicKey = secp256k1.recoverPublicKey(recovered, digest, { prehash: false, format: 'recovered' });
+  return addressOfPublicKey(publicKey);
+}
+
+/**
+ * The EIP-55 checksummed address of a secp256k1 public key, compressed or not.
+ *
+ * @param {Uint8Array} publicKey
+ * @returns {string}
+ */
+export function addressOfPublicKey(publicKey) {
+  const point = secp256k1.Point.fromBytes(publicKey);
+  const uncompressed = point.toBytes(false); // 0x04 ‖ X ‖ Y
+  const hash = keccak_256(uncompressed.slice(1));
+  return checksumAddress(bytesToHex(hash.slice(12)));
+}
+
+/**
+ * EIP-55: uppercase the hex digits whose position hashes high.
+ *
+ * @param {string} address
+ * @returns {string}
+ */
+export function checksumAddress(address) {
+  const lower = address.toLowerCase().replace(/^0x/, '');
+  if (!/^[0-9a-f]{40}$/.test(lower)) throw new Error(`Not an address: ${address}`);
+  const hash = bytesToHex(keccak_256(utf8.encode(lower))).slice(2);
+  let out = '0x';
+  for (let i = 0; i < 40; i++) {
+    out += Number.parseInt(hash[i], 16) >= 8 ? lower[i].toUpperCase() : lower[i];
+  }
+  return out;
+}

package/src/index.js

@@ -0,0 +1,34 @@
+export { createClient, X402Error, DEFAULT_MAX_USD } from './client.js';
+export { walletFromKey, randomWallet } from './wallet.js';
+export { memoryStore, fileStore, defaultPassPath, originOf, isLive } from './passes.js';
+export {
+  X402_VERSION,
+  KNOWN_TOKEN_DOMAINS,
+  TRANSFER_WITH_AUTHORIZATION_TYPES,
+  evmChainId,
+  readOffer,
+  isOffer,
+  selectAccept,
+  domainFor,
+  requiredAmount,
+  amountUsd,
+  randomNonce,
+  buildAuthorization,
+  signPayment,
+  encodePaymentHeader,
+  decodePaymentHeader,
+  readReceipt,
+} from './x402.js';
+export {
+  eip712Digest,
+  signTypedData,
+  recoverTypedDataSigner,
+  addressOfPublicKey,
+  checksumAddress,
+  hashStruct,
+  hashDomain,
+  encodeType,
+  typeHash,
+  hexToBytes,
+  bytesToHex,
+} from './eip712.js';

package/src/passes.js

@@ -0,0 +1,117 @@
+/**
+ * Where passes live between requests.
+ *
+ * A gateway sells a day at a time, and a pass is a bearer token: whoever
+ * presents it gets in, and presenting it costs nothing. So the whole value of
+ * a client that remembers passes is that the second request to a site — and
+ * the thousandth, from a crawler — never pays again. Keyed by origin, because
+ * a pass opens a site rather than a page.
+ *
+ * Two stores. Memory for a process that lives as long as its passes are
+ * worth; a file for a CLI that is invoked once per URL and would otherwise
+ * buy the same day a thousand times.
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/**
+ * @typedef {{
+ *   token: string,
+ *   header: string,
+ *   expires: string|null,
+ *   boughtAt: string,
+ *   url: string|null,
+ * }} StoredPass
+ */
+
+/** Whether a pass is still worth presenting. Unknown expiry counts as live. */
+export function isLive(pass, now = Date.now()) {
+  if (!pass?.token) return false;
+  if (!pass.expires) return true;
+  const at = Date.parse(pass.expires);
+  return Number.isNaN(at) ? true : at > now;
+}
+
+/** The origin a URL's pass is filed under. */
+export function originOf(url) {
+  return new URL(String(url)).origin;
+}
+
+/**
+ * Passes kept in memory for the life of the process.
+ *
+ * @returns {import('../index.d.ts').PassStore}
+ */
+export function memoryStore() {
+  const passes = new Map();
+  return {
+    get: (origin) => {
+      const pass = passes.get(origin) ?? null;
+      return isLive(pass) ? pass : null;
+    },
+    set: (origin, pass) => {
+      passes.set(origin, pass);
+    },
+    delete: (origin) => {
+      passes.delete(origin);
+    },
+    all: () => Object.fromEntries(passes),
+  };
+}
+
+/**
+ * The default file: `$XDG_CONFIG_HOME/x402-client/passes.json`, or the same
+ * under `~/.config`.
+ */
+export function defaultPassPath() {
+  const base = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(base, 'x402-client', 'passes.json');
+}
+
+/**
+ * Passes kept in a JSON file, read on every get and rewritten on every set.
+ *
+ * The file is small — one line per site — and re-reading it is what lets two
+ * CLI invocations in a row, or two processes, share what one of them bought.
+ * Written with mode 0600 since a pass is a bearer token, and created with its
+ * directory when missing. A file that cannot be read is treated as empty
+ * rather than fatal: losing a cache costs a dollar, crashing costs the run.
+ *
+ * @param {string} [path]
+ * @returns {import('../index.d.ts').PassStore}
+ */
+export function fileStore(path = defaultPassPath()) {
+  const read = () => {
+    try {
+      const parsed = JSON.parse(readFileSync(path, 'utf8'));
+      return parsed && typeof parsed === 'object' ? parsed : {};
+    } catch {
+      return {};
+    }
+  };
+  const write = (all) => {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+  };
+
+  return {
+    get: (origin) => {
+      const pass = read()[origin] ?? null;
+      return isLive(pass) ? pass : null;
+    },
+    set: (origin, pass) => {
+      const all = read();
+      all[origin] = pass;
+      write(all);
+    },
+    delete: (origin) => {
+      const all = read();
+      delete all[origin];
+      write(all);
+    },
+    all: () => read(),
+    path,
+  };
+}

package/src/types.js

@@ -0,0 +1,18 @@
+/**
+ * EIP-3009 `TransferWithAuthorization`.
+ *
+ * This — not a bespoke `Payment` struct — is what x402's `exact` scheme signs
+ * on EVM. Whoever holds the signature can call `transferWithAuthorization` on
+ * the token and move the funds, which is why the facilitator can broadcast
+ * and pay the gas while the payer needs no native currency at all.
+ */
+export const TRANSFER_WITH_AUTHORIZATION_TYPES = {
+  TransferWithAuthorization: [
+    { name: 'from', type: 'address' },
+    { name: 'to', type: 'address' },
+    { name: 'value', type: 'uint256' },
+    { name: 'validAfter', type: 'uint256' },
+    { name: 'validBefore', type: 'uint256' },
+    { name: 'nonce', type: 'bytes32' },
+  ],
+};