@profullstack/x402-client 0.1.0

package/src/wallet.js

@@ -0,0 +1,59 @@
+/**
+ * A wallet is a private key and the address it controls.
+ *
+ * That is all an x402 payer needs: the `exact` scheme moves USDC with an
+ * EIP-3009 authorization that the facilitator broadcasts and pays the gas
+ * for, so the key never sends a transaction and never holds ETH. It signs
+ * typed data, and it does so offline.
+ *
+ * The key is held as bytes for the life of the wallet and never logged,
+ * serialized or returned. Anything that needs to identify the wallet uses
+ * the address.
+ */
+
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+
+import { addressOfPublicKey, hexToBytes, signTypedData } from './eip712.js';
+
+/**
+ * @typedef {{
+ *   address: string,
+ *   signTypedData: (domain: object, types: object, primaryType: string, message: object) => string,
+ * }} Wallet
+ */
+
+/**
+ * A wallet from a 32-byte secp256k1 private key, hex with or without `0x`.
+ *
+ * @param {string|Uint8Array} privateKey
+ * @returns {Wallet}
+ */
+export function walletFromKey(privateKey) {
+  const key = typeof privateKey === 'string' ? hexToBytes(privateKey.trim()) : privateKey;
+  if (!(key instanceof Uint8Array) || key.length !== 32) {
+    throw new Error('A private key is 32 bytes (64 hex characters)');
+  }
+  if (!secp256k1.utils.isValidSecretKey(key)) throw new Error('Not a valid secp256k1 private key');
+
+  const address = addressOfPublicKey(secp256k1.getPublicKey(key, false));
+
+  return Object.freeze({
+    address,
+    signTypedData: (domain, types, primaryType, message) => signTypedData(domain, types, primaryType, message, key),
+  });
+}
+
+/**
+ * A fresh random wallet, for tests and for a first run with nothing funded.
+ *
+ * Returns the key as well, since a wallet that cannot be saved cannot be
+ * funded: the caller stores it and never sees it here again.
+ *
+ * @returns {{ wallet: Wallet, privateKey: string }}
+ */
+export function randomWallet() {
+  const key = secp256k1.utils.randomSecretKey();
+  let hex = '0x';
+  for (const b of key) hex += b.toString(16).padStart(2, '0');
+  return { wallet: walletFromKey(key), privateKey: hex };
+}

package/src/x402.js

@@ -0,0 +1,278 @@
+/**
+ * x402 v2 on the wire, from the payer's side.
+ *
+ * Field shapes follow what servers actually emit, checked against
+ * @profullstack/x402-gateway and CoinPay's `x402-v2` rather than remembered
+ * from the spec: the 402 carries `{ x402Version: 2, accepts: [...] }` as its
+ * JSON body (the gateway) or base64 in a `PAYMENT-REQUIRED` header (the
+ * Coinbase-style facilitators), each `accepts` entry names a CAIP-2 network,
+ * an `amount` in the token's smallest unit, the `asset` contract, `payTo`,
+ * and the token's own EIP-712 domain in `extra`. The proof goes back as base64
+ * JSON in `X-PAYMENT` (CoinPay's dialect, the v1 header name) and
+ * `PAYMENT-SIGNATURE` (v2); both are sent, since a server reads one and
+ * ignores the other.
+ */
+
+import { TRANSFER_WITH_AUTHORIZATION_TYPES } from './types.js';
+
+export { TRANSFER_WITH_AUTHORIZATION_TYPES };
+
+/** The protocol version the ecosystem is on. */
+export const X402_VERSION = 2;
+
+/**
+ * EIP-712 domains for tokens a server might quote without saying so.
+ *
+ * A well-formed v2 entry carries `extra: { name, version }` and that is what
+ * is used. This table is the fallback for an entry that omits it, because the
+ * domain is not derivable: `version()` is not part of ERC-20. Every value was
+ * read from the deployed contract over JSON-RPC by CoinPay; all three USDC
+ * deployments answer "USD Coin" / "2".
+ */
+export const KNOWN_TOKEN_DOMAINS = {
+  'eip155:1:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48': { name: 'USD Coin', version: '2', decimals: 6 },
+  'eip155:137:0x3c499c542cef5e3811e1192ce70d8cc03d5c3359': { name: 'USD Coin', version: '2', decimals: 6 },
+  'eip155:8453:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913': { name: 'USD Coin', version: '2', decimals: 6 },
+};
+
+/** Numeric EVM chain id from a CAIP-2 id, or null if it is not an eip155 chain. */
+export function evmChainId(network) {
+  const match = /^eip155:(\d+)$/i.exec(String(network ?? ''));
+  return match ? Number(match[1]) : null;
+}
+
+/** base64 (standard or url-safe) -> utf8. */
+function fromBase64(s) {
+  const clean = String(s).trim().replace(/-/g, '+').replace(/_/g, '/');
+  return Buffer.from(clean, 'base64').toString('utf8');
+}
+
+/**
+ * The offer a 402 response carries, or null if it is a 402 without one.
+ *
+ * Reads the `PAYMENT-REQUIRED` header first and the JSON body second. The
+ * body is returned too, whatever it held: a gateway puts the price, the pass
+ * header name and the place to pay in there, which is worth showing a person.
+ *
+ * @param {Response} response
+ * @returns {Promise<{ offer: object|null, body: any }>}
+ */
+export async function readOffer(response) {
+  let body = null;
+  const text = await response.text();
+  try {
+    body = JSON.parse(text);
+  } catch {
+    body = text;
+  }
+
+  const header = response.headers.get('payment-required');
+  if (header) {
+    try {
+      const parsed = JSON.parse(fromBase64(header));
+      if (isOffer(parsed)) return { offer: parsed, body };
+    } catch {
+      /* fall through to the body */
+    }
+  }
+
+  return { offer: isOffer(body) ? body : null, body };
+}
+
+/** Whether a value has the shape of an x402 offer. */
+export function isOffer(value) {
+  return Boolean(value) && typeof value === 'object' && Array.isArray(value.accepts);
+}
+
+/**
+ * The first entry the payer can sign.
+ *
+ * The order of `accepts` is the server's preference and is kept: the first
+ * `exact`-scheme entry on an EVM chain wins, restricted to `networks` when
+ * the caller has funds on some chains and not others.
+ *
+ * @param {object[]} accepts
+ * @param {{ networks?: string[] }} [options]
+ * @returns {object|null}
+ */
+export function selectAccept(accepts, { networks } = {}) {
+  if (!Array.isArray(accepts)) return null;
+  const allowed = networks ? new Set(networks.map((n) => String(n).toLowerCase())) : null;
+  return (
+    accepts.find((entry) => {
+      if (!entry || (entry.scheme ?? 'exact') !== 'exact') return false;
+      if (evmChainId(entry.network) === null) return false;
+      return !allowed || allowed.has(String(entry.network).toLowerCase());
+    }) ?? null
+  );
+}
+
+/**
+ * The EIP-712 domain for an entry: the token's, never x402's.
+ *
+ * `verifyingContract` is the token's address and `name`/`version` are what
+ * that token returns from its own domain. Getting this wrong is not a soft
+ * failure: the recovered signer is simply some other address.
+ *
+ * @param {object} entry
+ * @returns {{ name: string, version: string, chainId: number, verifyingContract: string }}
+ */
+export function domainFor(entry) {
+  const chainId = evmChainId(entry?.network);
+  if (chainId === null) throw new Error(`Not an EVM network, cannot sign an EIP-3009 authorization: ${entry?.network}`);
+  if (!entry.asset) throw new Error('The offer names no token contract (`asset`)');
+
+  const known = KNOWN_TOKEN_DOMAINS[`${String(entry.network).toLowerCase()}:${String(entry.asset).toLowerCase()}`];
+  const name = entry.extra?.name ?? known?.name;
+  const version = entry.extra?.version ?? known?.version;
+  if (!name || !version) {
+    throw new Error(
+      `The offer carries no EIP-712 domain for ${entry.asset} on ${entry.network} and it is not a token this client knows`,
+    );
+  }
+  return { name, version, chainId, verifyingContract: entry.asset };
+}
+
+/**
+ * The amount an entry asks for, in the token's smallest unit, as a string.
+ * Reads v2's `amount` and the older `maxAmountRequired`.
+ */
+export function requiredAmount(entry) {
+  const raw = entry?.amount ?? entry?.maxAmountRequired;
+  if (raw === undefined || raw === null || raw === '') throw new Error('The offer names no amount');
+  const value = BigInt(raw);
+  if (value < 0n) throw new Error(`The offer names a negative amount: ${raw}`);
+  return String(value);
+}
+
+/**
+ * The entry's price in dollars, when the token is a dollar stablecoin this
+ * client knows the decimals of. Null for anything else, so a price cap can
+ * refuse what it cannot price rather than let it through.
+ *
+ * @param {object} entry
+ * @returns {number|null}
+ */
+export function amountUsd(entry) {
+  const known = KNOWN_TOKEN_DOMAINS[`${String(entry?.network).toLowerCase()}:${String(entry?.asset).toLowerCase()}`];
+  if (!known) return null;
+  return Number(requiredAmount(entry)) / 10 ** known.decimals;
+}
+
+/** A random 32-byte nonce, hex. EIP-3009 nonces are arbitrary bytes32. */
+export function randomNonce() {
+  const bytes = new Uint8Array(32);
+  globalThis.crypto.getRandomValues(bytes);
+  return `0x${Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('')}`;
+}
+
+/**
+ * The authorization to sign.
+ *
+ * `validAfter` is 0 rather than "now": clocks differ between the payer and the
+ * chain, and a validAfter in the payer's near future makes the authorization
+ * briefly unusable for no benefit. `validBefore` is bounded by the entry's
+ * own `maxTimeoutSeconds`, which is how long the server promises to settle
+ * within; signing for longer would leave a spendable authorization lying
+ * around after the server has given up on it.
+ *
+ * @param {object} args
+ * @param {string} args.from
+ * @param {string} args.to
+ * @param {string} args.value
+ * @param {number} [args.validForSeconds=600]
+ * @param {string} [args.nonce]
+ * @param {number} [args.now] unix seconds, for tests
+ */
+export function buildAuthorization({ from, to, value, validForSeconds = 600, nonce, now = Math.floor(Date.now() / 1000) }) {
+  if (!from) throw new Error('an authorization needs `from`');
+  if (!to) throw new Error('an authorization needs `to`');
+  return {
+    from,
+    to,
+    value: String(value),
+    validAfter: '0',
+    validBefore: String(now + Math.max(1, Math.floor(validForSeconds))),
+    nonce: nonce ?? randomNonce(),
+  };
+}
+
+/**
+ * Sign one `accepts` entry with a wallet.
+ *
+ * @param {object} entry
+ * @param {import('./wallet.js').Wallet} wallet
+ * @param {{ validForSeconds?: number, nonce?: string, now?: number }} [options]
+ * @returns {{ payment: object, header: string, authorization: object, domain: object }}
+ */
+export function signPayment(entry, wallet, options = {}) {
+  const domain = domainFor(entry);
+  if (!entry.payTo) throw new Error('The offer names nobody to pay (`payTo`)');
+
+  const authorization = buildAuthorization({
+    from: wallet.address,
+    to: entry.payTo,
+    value: requiredAmount(entry),
+    validForSeconds: options.validForSeconds ?? entry.maxTimeoutSeconds ?? 600,
+    nonce: options.nonce,
+    now: options.now,
+  });
+
+  const signature = wallet.signTypedData(domain, TRANSFER_WITH_AUTHORIZATION_TYPES, 'TransferWithAuthorization', authorization);
+
+  const payment = {
+    x402Version: X402_VERSION,
+    scheme: entry.scheme ?? 'exact',
+    network: entry.network,
+    payload: { signature, authorization },
+  };
+
+  return { payment, header: encodePaymentHeader(payment), authorization, domain };
+}
+
+/** base64 of a payment, as the proof headers carry it. */
+export function encodePaymentHeader(payment) {
+  return Buffer.from(JSON.stringify(payment), 'utf8').toString('base64');
+}
+
+/** Inverse of {@link encodePaymentHeader}. Null when the header is not base64 JSON. */
+export function decodePaymentHeader(header) {
+  if (!header) return null;
+  try {
+    const parsed = JSON.parse(fromBase64(header));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * What a paid response gives back that is worth keeping.
+ *
+ * A gateway answers a proof with a receipt naming a pass — a bearer token
+ * good for a while — and the header to present it in. A plain x402 resource
+ * answers with the resource itself and a `PAYMENT-RESPONSE` header holding the
+ * settlement. Both are read; only the pass is something to store.
+ *
+ * @param {Response} response
+ * @param {any} body the parsed JSON body, if there was one
+ * @returns {{ pass: string|null, header: string, expires: string|null, settlement: object|null }}
+ */
+export function readReceipt(response, body) {
+  const headerName = (typeof body?.header === 'string' && body.header) || 'x-crawl-pass';
+  const fromBody = typeof body?.pass === 'string' ? body.pass : (body?.pass?.token ?? body?.token ?? null);
+  const pass = fromBody ?? response.headers.get(headerName) ?? null;
+  const expires = body?.expires ?? body?.pass?.expires ?? response.headers.get(`${headerName}-expires`) ?? null;
+
+  let settlement = null;
+  const settled = response.headers.get('payment-response') ?? response.headers.get('x-payment-response');
+  if (settled) {
+    try {
+      settlement = JSON.parse(fromBase64(settled));
+    } catch {
+      settlement = null;
+    }
+  }
+
+  return { pass: typeof pass === 'string' ? pass : null, header: headerName, expires: expires ? String(expires) : null, settlement };
+}