@profullstack/coinpay 0.6.11 → 0.9.0

package/src/x402-browser.js

@@ -0,0 +1,318 @@
+/**
+ * Browser-side x402 payer.
+ *
+ * Turns a 402 response into a paid retry, using whatever wallet the visitor
+ * actually has. CoinPay Wallet is preferred when present; otherwise any
+ * injected EIP-1193 wallet — MetaMask, Phantom's EVM provider, Rabby, Coinbase
+ * Wallet — can pay, because what gets signed is the standard EIP-3009
+ * authorization rather than anything CoinPay-specific.
+ *
+ * That interoperability is the whole point of signing the real structure. A
+ * bespoke payload would still be signable by MetaMask, but the resulting
+ * signature would authorise no transfer on-chain and only CoinPayPortal could
+ * interpret it — which is not a wallet integration, it is a lock-in.
+ *
+ * Usage:
+ *   const res = await fetchWithX402('https://api.example.com/premium');
+ *
+ * @module x402-browser
+ */
+
+import {
+  buildAuthorization,
+  buildEip3009Domain,
+  buildExactEvmPayment,
+  encodePaymentHeader,
+  evmChainId,
+  requiredAmount,
+  selectAcceptEntry,
+  toCaip2,
+  TRANSFER_WITH_AUTHORIZATION_TYPES,
+} from './x402-v2.js';
+
+/** How long a discovery sweep waits for EIP-6963 wallets to announce. */
+const EIP6963_ANNOUNCE_MS = 100;
+
+/**
+ * Enumerate injected EVM wallets via EIP-6963.
+ *
+ * Before EIP-6963 every wallet raced to own `window.ethereum`, so with two
+ * installed you got whichever won — the user could not choose, and a site
+ * could not tell which it had. EIP-6963 has each wallet announce itself with
+ * its own provider object instead.
+ *
+ * `window.ethereum` is still included as a last resort, for wallets that have
+ * not adopted the standard.
+ */
+export async function discoverEvmWallets({ timeoutMs = EIP6963_ANNOUNCE_MS } = {}) {
+  const found = new Map();
+
+  if (typeof window === 'undefined') return [];
+
+  const onAnnounce = (event) => {
+    const detail = event.detail;
+    if (!detail?.info?.uuid || !detail.provider) return;
+    found.set(detail.info.uuid, { info: detail.info, provider: detail.provider });
+  };
+
+  window.addEventListener('eip6963:announceProvider', onAnnounce);
+  window.dispatchEvent(new Event('eip6963:requestProvider'));
+  await new Promise((resolve) => setTimeout(resolve, timeoutMs));
+  window.removeEventListener('eip6963:announceProvider', onAnnounce);
+
+  const wallets = [...found.values()].map(({ info, provider }) => ({
+    id: info.rdns || info.uuid,
+    name: info.name,
+    icon: info.icon,
+    provider,
+  }));
+
+  // Legacy fallback: only if nothing announced, so a 6963-aware wallet is not
+  // listed twice under two different identities.
+  if (wallets.length === 0 && window.ethereum) {
+    wallets.push({ id: 'injected', name: detectLegacyName(window.ethereum), provider: window.ethereum });
+  }
+
+  return wallets;
+}
+
+function detectLegacyName(provider) {
+  if (provider.isMetaMask) return 'MetaMask';
+  if (provider.isPhantom) return 'Phantom';
+  if (provider.isCoinbaseWallet) return 'Coinbase Wallet';
+  if (provider.isRabby) return 'Rabby';
+  return 'Injected Wallet';
+}
+
+/**
+ * True when a CoinPay Wallet that can actually pay an x402 invoice is present.
+ *
+ * Checks for the method, not merely for the wallet. `payX402` shipped after
+ * the provider itself, so an installed-but-older extension has `isCoinPay`
+ * and no way to pay — treating that as "CoinPay is here" would hand the
+ * payment to a wallet that cannot take it and throw a TypeError, when the
+ * visitor may well have MetaMask sitting right there.
+ */
+export function hasCoinPayWallet() {
+  return (
+    typeof window !== 'undefined' &&
+    window.coinpay?.isCoinPay === true &&
+    typeof window.coinpay.payX402 === 'function'
+  );
+}
+
+/** True when CoinPay Wallet is installed but predates x402 support. */
+export function hasOutdatedCoinPayWallet() {
+  return (
+    typeof window !== 'undefined' &&
+    window.coinpay?.isCoinPay === true &&
+    typeof window.coinpay.payX402 !== 'function'
+  );
+}
+
+/**
+ * Choose a wallet to pay with.
+ *
+ * CoinPay Wallet first when installed — it is the only one that can pay on
+ * every rail CoinPayPortal accepts, including Bitcoin and Lightning, which no
+ * EVM wallet can touch. Otherwise the first injected EVM wallet, or one named
+ * explicitly by `preferWalletId`.
+ */
+export async function selectWallet({ preferWalletId, allowCoinPay = true } = {}) {
+  if (allowCoinPay && hasCoinPayWallet() && !preferWalletId) {
+    return { kind: 'coinpay', id: 'coinpay', name: 'CoinPay Wallet', provider: window.coinpay };
+  }
+
+  const evm = await discoverEvmWallets();
+  if (evm.length === 0) {
+    if (allowCoinPay && hasCoinPayWallet()) {
+      return { kind: 'coinpay', id: 'coinpay', name: 'CoinPay Wallet', provider: window.coinpay };
+    }
+    return null;
+  }
+
+  const chosen = preferWalletId ? evm.find((w) => w.id === preferWalletId) : evm[0];
+  if (!chosen) return null;
+  return { kind: 'evm', ...chosen };
+}
+
+/** Ask an EIP-1193 provider for the active account, prompting if needed. */
+async function requireEvmAccount(provider) {
+  const accounts = await provider.request({ method: 'eth_requestAccounts' });
+  if (!Array.isArray(accounts) || accounts.length === 0) {
+    throw new Error('Wallet returned no accounts');
+  }
+  return accounts[0];
+}
+
+/**
+ * Put an EIP-1193 wallet on the chain an `accepts` entry requires.
+ *
+ * Signing an EIP-712 payload whose domain names chain X while the wallet is on
+ * chain Y produces a signature that verifies against neither — wallets bind
+ * the domain's chainId to their active chain. So the switch is mandatory, not
+ * a nicety.
+ */
+async function ensureEvmChain(provider, network) {
+  const chainId = evmChainId(network);
+  if (chainId === null) throw new Error(`Not an EVM network: ${network}`);
+  const hexChainId = `0x${chainId.toString(16)}`;
+
+  const current = await provider.request({ method: 'eth_chainId' });
+  if (typeof current === 'string' && current.toLowerCase() === hexChainId) return;
+
+  try {
+    await provider.request({
+      method: 'wallet_switchEthereumChain',
+      params: [{ chainId: hexChainId }],
+    });
+  } catch (err) {
+    // 4902 = chain unknown to the wallet. Adding it needs RPC details we do
+    // not have here, so surface it rather than guessing an RPC URL.
+    if (err?.code === 4902) {
+      throw new Error(
+        `Your wallet does not have chain ${chainId} configured. Add it, then try again.`,
+      );
+    }
+    throw err;
+  }
+}
+
+/**
+ * Sign an EIP-3009 authorization with an EIP-1193 wallet.
+ *
+ * @returns {{signature: string, authorization: object, from: string}}
+ */
+export async function signExactEvm(provider, entry, { from } = {}) {
+  const payer = from ?? (await requireEvmAccount(provider));
+  await ensureEvmChain(provider, entry.network);
+
+  const domain = buildEip3009Domain({
+    network: entry.network,
+    asset: entry.asset,
+    name: entry.extra?.name,
+    version: entry.extra?.version,
+  });
+
+  const authorization = buildAuthorization({
+    from: payer,
+    to: entry.payTo,
+    value: requiredAmount(entry),
+    validForSeconds: entry.maxTimeoutSeconds ?? 600,
+  });
+
+  const typedData = {
+    types: {
+      EIP712Domain: [
+        { name: 'name', type: 'string' },
+        { name: 'version', type: 'string' },
+        { name: 'chainId', type: 'uint256' },
+        { name: 'verifyingContract', type: 'address' },
+      ],
+      ...TRANSFER_WITH_AUTHORIZATION_TYPES,
+    },
+    primaryType: 'TransferWithAuthorization',
+    domain,
+    message: authorization,
+  };
+
+  const signature = await provider.request({
+    method: 'eth_signTypedData_v4',
+    params: [payer, JSON.stringify(typedData)],
+  });
+
+  return { signature, authorization, from: payer };
+}
+
+/**
+ * Produce the `X-PAYMENT` header value for a 402 body.
+ *
+ * @param {object} paymentRequired  the parsed 402 JSON (`{x402Version, accepts}`)
+ * @param {object} [options]
+ * @param {string} [options.preferWalletId]
+ * @param {string[]} [options.capabilities] override which networks to consider
+ */
+export async function createPaymentHeader(paymentRequired, options = {}) {
+  const accepts = paymentRequired?.accepts;
+  if (!Array.isArray(accepts) || accepts.length === 0) {
+    throw new Error('402 response carried no `accepts` options');
+  }
+
+  const wallet = await selectWallet(options);
+  if (!wallet) {
+    if (hasOutdatedCoinPayWallet()) {
+      throw new Error(
+        'Your CoinPay Wallet is too old to pay x402 invoices and no other wallet is ' +
+          'available. Update it, or install MetaMask.',
+      );
+    }
+    throw new Error(
+      'No wallet available to pay. Install CoinPay Wallet, MetaMask, or another EVM wallet.',
+    );
+  }
+
+  if (wallet.kind === 'coinpay') {
+    // The extension picks among the offered options itself — it knows which
+    // chains the user actually holds funds on, which this page does not.
+    const header = await wallet.provider.payX402(paymentRequired);
+    return { header, wallet };
+  }
+
+  // An injected EVM wallet can only pay the EVM entries.
+  const evmCapable = accepts
+    .map((entry) => entry.network)
+    .filter((network) => evmChainId(network) !== null);
+
+  const entry = selectAcceptEntry(accepts, options.capabilities ?? evmCapable);
+  if (!entry) {
+    throw new Error(
+      `${wallet.name} cannot pay any of the offered options ` +
+        `(${accepts.map((a) => toCaip2(a.network)).join(', ')}). ` +
+        'CoinPay Wallet supports Bitcoin, Lightning and card rails as well.',
+    );
+  }
+
+  const { signature, authorization } = await signExactEvm(wallet.provider, entry);
+  const payment = buildExactEvmPayment({
+    network: entry.network,
+    signature,
+    authorization,
+    scheme: entry.scheme ?? 'exact',
+  });
+
+  return { header: encodePaymentHeader(payment), wallet, entry };
+}
+
+/**
+ * `fetch` that pays once if the resource asks for payment.
+ *
+ * Retries exactly one time. A second 402 after paying means the payment was
+ * rejected rather than missing, and retrying again would sign a fresh
+ * authorization for a resource that just refused one — at the user's expense.
+ *
+ * @param {string|URL|Request} input
+ * @param {RequestInit} [init]
+ * @param {object} [options] forwarded to {@link createPaymentHeader}
+ */
+export async function fetchWithX402(input, init = {}, options = {}) {
+  const first = await fetch(input, init);
+  if (first.status !== 402) return first;
+
+  let paymentRequired;
+  try {
+    paymentRequired = await first.clone().json();
+  } catch {
+    throw new Error('Resource returned 402 but its body was not valid x402 JSON');
+  }
+
+  const { header } = await createPaymentHeader(paymentRequired, options);
+
+  const headers = new Headers(init.headers ?? {});
+  headers.set('X-PAYMENT', header);
+
+  const paid = await fetch(input, { ...init, headers });
+  if (paid.status === 402) {
+    throw new Error('Payment was rejected by the resource; not retrying to avoid double-paying');
+  }
+  return paid;
+}

package/src/x402-pay-server.js

@@ -0,0 +1,272 @@
+/**
+ * A one-shot local payment page, for paying an x402 invoice from the CLI.
+ *
+ * A terminal cannot sign with a browser wallet: the extension lives in the
+ * browser process and exposes itself only to pages. So the CLI serves a page on
+ * loopback, opens it, and waits. The page signs with CoinPay Wallet (or
+ * MetaMask, or anything else injected), posts the `X-PAYMENT` header back, and
+ * the CLI retries the original request with it.
+ *
+ * Security posture, because this is a local server that can spend money:
+ *   * bound to 127.0.0.1, never a routable interface
+ *   * every request must carry a single-use token from the URL, so another
+ *     process on the box cannot drive it or read the invoice
+ *   * one payment, then the server closes — it is not a standing service
+ *   * the private key never comes near this process; it stays in the wallet
+ *
+ * @module x402-pay-server
+ */
+
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+/** SDK modules the page imports. Served from disk so the page can `import` them. */
+const MODULES = {
+  '/x402-browser.js': join(HERE, 'x402-browser.js'),
+  '/x402-v2.js': join(HERE, 'x402-v2.js'),
+};
+
+function renderPage() {
+  // Kept dependency-free and inline: this page is served from a temporary
+  // loopback server, so anything external would simply fail to load.
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>CoinPay — Approve payment</title>
+<style>
+  :root { color-scheme: light dark; --bg:#faf9f7; --fg:#1a1a1a; --muted:#6b6b6b; --card:#fff; --line:#e6e3de; --accent:#2f6f4f; }
+  @media (prefers-color-scheme: dark) {
+    :root { --bg:#141414; --fg:#f2f2f2; --muted:#9a9a9a; --card:#1e1e1e; --line:#333; --accent:#5ea37a; }
+  }
+  * { box-sizing: border-box; }
+  body { margin:0; min-height:100vh; display:grid; place-items:center; padding:24px;
+         background:var(--bg); color:var(--fg);
+         font:16px/1.5 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif; }
+  .card { width:100%; max-width:420px; background:var(--card); border:1px solid var(--line);
+          border-radius:14px; padding:28px; }
+  h1 { margin:0 0 4px; font-size:19px; }
+  .sub { color:var(--muted); font-size:14px; margin:0 0 20px; }
+  dl { display:grid; grid-template-columns:auto 1fr; gap:10px 16px; margin:0 0 22px;
+       padding:16px 0; border-top:1px solid var(--line); border-bottom:1px solid var(--line); }
+  dt { color:var(--muted); font-size:14px; }
+  dd { margin:0; text-align:right; font-variant-numeric:tabular-nums; overflow-wrap:anywhere; }
+  .amount { font-size:22px; font-weight:600; }
+  button { width:100%; padding:13px; font-size:15px; font-weight:600; border:0; border-radius:9px;
+           background:var(--accent); color:#fff; cursor:pointer; }
+  button:disabled { opacity:.55; cursor:default; }
+  .status { margin-top:16px; font-size:14px; color:var(--muted); min-height:1.5em; text-align:center; overflow-wrap:anywhere; }
+  .status.error { color:#b3261e; }
+  @media (prefers-color-scheme: dark) { .status.error { color:#f2b8b5; } }
+  .status.ok { color:var(--accent); }
+  code { font:13px ui-monospace,SFMono-Regular,Menlo,monospace; }
+</style>
+</head>
+<body>
+  <main class="card">
+    <h1>Approve payment</h1>
+    <p class="sub" id="resource"></p>
+    <dl>
+      <dt>Amount</dt><dd class="amount" id="amount">—</dd>
+      <dt>Network</dt><dd id="network">—</dd>
+      <dt>To</dt><dd><code id="payTo">—</code></dd>
+      <dt>Wallet</dt><dd id="wallet">looking…</dd>
+    </dl>
+    <button id="pay" disabled>Pay</button>
+    <p class="status" id="status"></p>
+  </main>
+
+<script type="module">
+import { fetchWithX402, createPaymentHeader, selectWallet } from './x402-browser.js';
+import { requiredAmount, evmChainId, selectAcceptEntry, toCaip2 } from './x402-v2.js';
+
+const token = new URLSearchParams(location.search).get('t') ?? '';
+const $ = (id) => document.getElementById(id);
+
+const setStatus = (text, kind = '') => {
+  $('status').textContent = text;
+  $('status').className = 'status ' + kind;
+};
+
+const CHAIN_NAMES = { 1: 'Ethereum', 137: 'Polygon', 8453: 'Base' };
+
+function scaled(raw, decimals = 6) {
+  const value = BigInt(raw);
+  const div = 10n ** BigInt(decimals);
+  const whole = value / div;
+  const frac = (value % div).toString().padStart(decimals, '0').replace(/0+$/, '');
+  return frac ? \`\${whole}.\${frac}\` : String(whole);
+}
+
+let invoice;
+
+async function init() {
+  const res = await fetch(\`/invoice?t=\${token}\`);
+  if (!res.ok) return setStatus('This payment link is no longer valid.', 'error');
+
+  const data = await res.json();
+  invoice = data.paymentRequired;
+  $('resource').textContent = data.resourceUrl;
+
+  // Show the option a browser wallet would actually take.
+  const evm = (invoice.accepts ?? [])
+    .map((a) => a.network)
+    .filter((n) => evmChainId(n) !== null);
+  const entry = selectAcceptEntry(invoice.accepts ?? [], evm) ?? invoice.accepts?.[0];
+
+  if (entry) {
+    $('amount').textContent = \`\${scaled(requiredAmount(entry))} \${entry.extra?.name ?? ''}\`.trim();
+    $('network').textContent = CHAIN_NAMES[evmChainId(entry.network)] ?? toCaip2(entry.network);
+    $('payTo').textContent = entry.payTo ?? '—';
+  }
+
+  const wallet = await selectWallet();
+  if (!wallet) {
+    $('wallet').textContent = 'none found';
+    return setStatus('No wallet found. Install CoinPay Wallet or MetaMask, then reload.', 'error');
+  }
+  $('wallet').textContent = wallet.name;
+  $('pay').disabled = false;
+  setStatus('');
+}
+
+$('pay').addEventListener('click', async () => {
+  $('pay').disabled = true;
+  setStatus('Waiting for your wallet…');
+  try {
+    const { header, wallet } = await createPaymentHeader(invoice);
+    setStatus('Signed. Handing back to the terminal…');
+    await fetch(\`/payment?t=\${token}\`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ header, wallet: wallet?.name }),
+    });
+    setStatus('Paid. You can close this tab.', 'ok');
+  } catch (err) {
+    $('pay').disabled = false;
+    setStatus(err?.message ?? String(err), 'error');
+  }
+});
+
+init().catch((err) => setStatus(err?.message ?? String(err), 'error'));
+</script>
+</body>
+</html>`;
+}
+
+/**
+ * Serve a one-shot payment page.
+ *
+ * @param {object} options
+ * @param {object} options.paymentRequired  parsed body of the 402 response
+ * @param {string} options.resourceUrl      what is being bought, for display
+ * @param {number} [options.port=0]         0 lets the OS pick a free port
+ * @returns {Promise<{url: string, waitForPayment: () => Promise<string>, close: () => Promise<void>}>}
+ */
+export async function startPaymentServer({ paymentRequired, resourceUrl, port = 0 }) {
+  // A single-use token, so another local process cannot read the invoice or
+  // post a payment into this session.
+  const token = randomBytes(24).toString('hex');
+
+  let resolvePayment;
+  let rejectPayment;
+  const payment = new Promise((resolve, reject) => {
+    resolvePayment = resolve;
+    rejectPayment = reject;
+  });
+
+  const server = createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://127.0.0.1');
+
+    const send = (status, body, type = 'text/plain; charset=utf-8') => {
+      res.writeHead(status, {
+        'Content-Type': type,
+        // The page must not be embeddable or reachable cross-origin: it can
+        // authorise a payment.
+        'X-Frame-Options': 'DENY',
+        'Cache-Control': 'no-store',
+      });
+      res.end(body);
+    };
+
+    if (url.pathname === '/' && req.method === 'GET') {
+      // The token is checked on the data routes rather than here, so a
+      // mistyped link shows the page and a clear error instead of a bare 403.
+      return send(200, renderPage(), 'text/html; charset=utf-8');
+    }
+
+    const modulePath = MODULES[url.pathname];
+    if (modulePath && req.method === 'GET') {
+      try {
+        const source = await readFile(modulePath, 'utf-8');
+        return send(200, source, 'text/javascript; charset=utf-8');
+      } catch {
+        return send(404, 'not found');
+      }
+    }
+
+    if (url.searchParams.get('t') !== token) {
+      return send(403, 'forbidden');
+    }
+
+    if (url.pathname === '/invoice' && req.method === 'GET') {
+      return send(200, JSON.stringify({ paymentRequired, resourceUrl }), 'application/json');
+    }
+
+    if (url.pathname === '/payment' && req.method === 'POST') {
+      let body = '';
+      req.on('data', (chunk) => {
+        body += chunk;
+        // A payment header is a few hundred bytes; anything larger is not one.
+        if (body.length > 64_000) req.destroy();
+      });
+      req.on('end', () => {
+        try {
+          const parsed = JSON.parse(body);
+          if (!parsed.header) throw new Error('No payment header supplied');
+          send(200, JSON.stringify({ ok: true }), 'application/json');
+          resolvePayment(parsed.header);
+        } catch (err) {
+          send(400, JSON.stringify({ error: err.message }), 'application/json');
+        }
+      });
+      return;
+    }
+
+    return send(404, 'not found');
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    // Loopback only. Binding 0.0.0.0 would expose a pay-me button to the LAN.
+    server.listen(port, '127.0.0.1', resolve);
+  });
+
+  const address = server.address();
+  const url = `http://127.0.0.1:${address.port}/?t=${token}`;
+
+  const close = () =>
+    new Promise((resolve) => {
+      server.close(() => resolve());
+      // Don't hold the process open on a browser tab that stayed connected.
+      server.closeAllConnections?.();
+    });
+
+  return {
+    url,
+    waitForPayment: (timeoutMs = 5 * 60 * 1000) => {
+      const timer = setTimeout(
+        () => rejectPayment(new Error('Timed out waiting for approval in the browser')),
+        timeoutMs,
+      );
+      return payment.finally(() => clearTimeout(timer));
+    },
+    close,
+  };
+}