@three-ws/x402-modal 0.2.0

package/docs/PROTOCOL.md

@@ -0,0 +1,102 @@
+# The x402 flow, as this modal drives it
+
+A reference for what happens between `pay()` and the resolved receipt. Useful
+when debugging an integration or building the server side.
+
+## The four steps
+
+```
+┌── 1. DISCOVER ──────────────────────────────────────────────────────────┐
+│  The modal sends the request you described (endpoint/method/body/headers) │
+│  with NO payment. It expects one of:                                      │
+│    • HTTP 402 with a JSON body containing `accepts[]`, or                  │
+│    • HTTP 401 with a base64-JSON `payment-required` header (MCP 2025-06-18)│
+│  Anything else (200, etc.) is surfaced as an error — pointing the modal at │
+│  a free endpoint must not silently "succeed".                             │
+└───────────────────────────────────────────────────────────────────────────┘
+                                   │  accepts[] = [{ scheme, network, asset,
+                                   │                payTo, amount, extra… }, …]
+                                   ▼
+┌── 2. CONNECT ───────────────────────────────────────────────────────────┐
+│  The modal picks accepts it can satisfy:                                  │
+│    • Solana (`solana:*`)  → Phantom (`window.solana` / `window.phantom`)  │
+│    • EVM    (`eip155:*`)  → `window.ethereum` (EIP-3009 entries only;      │
+│                              Permit2 siblings are skipped)                 │
+│  >1 viable → wallet picker.  Exactly 1 + `autoConnect` → straight through. │
+│  Spending caps (if set) are checked here, before any signature prompt.    │
+└───────────────────────────────────────────────────────────────────────────┘
+                                   ▼
+┌── 3. AUTHORIZE ─────────────────────────────────────────────────────────┐
+│  Solana:                                                                  │
+│    POST {apiOrigin}/api/x402-checkout?action=prepare {accept,buyer}        │
+│        → tx_base64   (built server-side; fee payer = facilitator)         │
+│    Phantom signs the VersionedTransaction                                 │
+│    POST …?action=encode {accept, signed_tx_base64, resource_url, …}        │
+│        → x_payment   (base64 paymentPayload)                              │
+│  EVM:                                                                      │
+│    wallet signs an EIP-3009 TransferWithAuthorization (typed data v4)     │
+│    the modal assembles x_payment locally — no backend, no gas, no tx       │
+└───────────────────────────────────────────────────────────────────────────┘
+                                   ▼
+┌── 4. VERIFY & SETTLE ───────────────────────────────────────────────────┐
+│  Re-send the original request with header `X-PAYMENT: <x_payment>`.        │
+│  The server VERIFIES the payment, RUNS the work, SETTLES on-chain, and     │
+│  returns 200 with an `x-payment-response` header (base64 receipt:          │
+│  network, payer, transaction). The modal renders the receipt + result.    │
+└───────────────────────────────────────────────────────────────────────────┘
+```
+
+## Why settlement-after-work makes retries safe
+
+x402 servers verify and *settle* the payment only **after** the protected work
+succeeds. So if the merchant returns a transient `429` (an upstream rate-limit
+hit *before* settlement), the exact same signed `X-PAYMENT` can be re-sent once
+the window resets with **no risk of a double charge**. The modal auto-retries a
+`429` up to twice, honoring `Retry-After`, with a live countdown, before falling
+back to a manual **Try again**.
+
+## SIWX re-entry (optional)
+
+If the `402` body includes an `extensions['sign-in-with-x']` block, the modal
+leads with **"Sign in with wallet"**: a buyer who already paid for this resource
+can re-enter by signing a CAIP-122 challenge (submitted via the
+`SIGN-IN-WITH-X` header) instead of paying again. If the server responds that
+this wallet hasn't actually paid (`401/402` + `siwx_not_paid`), the modal
+transparently falls back to the normal payment flow with a one-line notice.
+
+The message string the modal signs is byte-compatible with the
+[siwe](https://github.com/spruceid/siwe) (EVM) and SIWS (Solana) formats so the
+server's recovered signer matches `payload.address`. See `buildSiwxMessage` in
+`src/util.js`.
+
+## ERC-8021 builder codes
+
+When the `402` declares a builder code under
+`extensions['builder-code'].info.a`, the modal echoes it back (anti-tamper: the
+server checks the echoed `a` equals what it declared) and self-attributes its
+own wallet (`w`) and service (`s`) codes from
+[`configure({ builderCode })`](./CONFIGURATION.md). Set `builderCode: null` to
+disable the echo.
+
+## The `accept` object
+
+| field | meaning |
+|---|---|
+| `scheme` | payment scheme — `exact` for a fixed price |
+| `network` | CAIP-2 id: `solana:<genesis>` or `eip155:<chainId>` |
+| `asset` | token: SPL mint (Solana) or ERC-20 address (EVM) |
+| `payTo` | recipient wallet |
+| `amount` | atomic amount (the modal also reads spec-canonical `maxAmountRequired`) |
+| `maxTimeoutSeconds` | EVM EIP-3009 `validBefore` window (default 600) |
+| `extra.name` | display + stablecoin detection (`USDC`, `USDT`, `DAI`…) |
+| `extra.decimals` | token decimals (default 6) |
+| `extra.version` | EVM EIP-712 domain version (Base USDC = `"2"`) |
+| `extra.feePayer` | Solana facilitator fee-payer pubkey (Solana only) |
+| `extra.assetTransferMethod` | `eip3009` (default) or `permit2` (skipped by this modal) |
+
+## Spec references
+
+- x402 — <https://x402.org>
+- CAIP-2 network ids — <https://chainagnostic.org/CAIPs/caip-2>
+- EIP-3009 `transferWithAuthorization` — <https://eips.ethereum.org/EIPS/eip-3009>
+- CAIP-122 / Sign-In-With-X — <https://chainagnostic.org/CAIPs/caip-122>

package/package.json

@@ -0,0 +1,75 @@
+{
+	"name": "@three-ws/x402-modal",
+	"version": "0.2.0",
+	"description": "A drop-in, dependency-free payment modal for any x402 paid endpoint. One script tag turns a 402 challenge into a polished checkout: wallet connect (Phantom on Solana, MetaMask/EVM via EIP-3009), the 402 → sign → settle flow, SIWX re-entry, spending caps, and a receipt — vanilla JS, no bundler required. Powered by three.ws.",
+	"keywords": [
+		"x402",
+		"payments",
+		"micropayments",
+		"usdc",
+		"stablecoin",
+		"solana",
+		"base",
+		"evm",
+		"eip-3009",
+		"eip3009",
+		"phantom",
+		"metamask",
+		"paywall",
+		"pay-per-call",
+		"checkout",
+		"web3",
+		"siwx",
+		"agent-payments",
+		"402"
+	],
+	"author": "three.ws <support@three.ws> (https://three.ws)",
+	"license": "Apache-2.0",
+	"homepage": "https://three.ws",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/nirholas/three.ws.git",
+		"directory": "x402-modal-sdk"
+	},
+	"bugs": {
+		"url": "https://github.com/nirholas/three.ws/issues"
+	},
+	"type": "module",
+	"main": "./dist/x402-modal.mjs",
+	"module": "./dist/x402-modal.mjs",
+	"unpkg": "./dist/x402.global.js",
+	"jsdelivr": "./dist/x402.global.js",
+	"types": "./types/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./types/index.d.ts",
+			"import": "./dist/x402-modal.mjs",
+			"default": "./dist/x402-modal.mjs"
+		},
+		"./global": "./dist/x402.global.js",
+		"./src": "./src/x402-modal.js"
+	},
+	"files": [
+		"dist",
+		"src",
+		"types",
+		"docs",
+		"README.md",
+		"TUTORIAL.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"build": "node build.mjs",
+		"prepublishOnly": "node build.mjs",
+		"test": "node --test \"test/*.test.js\""
+	},
+	"devDependencies": {
+		"esbuild": "^0.21.0"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"publishConfig": {
+		"access": "public"
+	}
+}

package/src/global.js

@@ -0,0 +1,64 @@
+// @three-ws/x402-modal — global / CDN entry.
+//
+// This is the side-effectful build that ships as the drop-in <script>. It:
+//   1. reads `data-x402-*` config off its own <script> tag (apiOrigin, brand,
+//      builderCode) so a self-hosted deployment can repoint the backend without
+//      a line of JS,
+//   2. binds every `[data-x402-endpoint]` element and re-scans the DOM as
+//      merchants inject buttons,
+//   3. exposes `window.X402 = { pay, init, configure, version }`.
+//
+// For bundler / npm consumers, import the side-effect-free core instead:
+//   import { pay, configure } from '@three-ws/x402-modal';
+
+import { pay, init, configure, version } from './x402-modal.js';
+
+// Pull optional config off the script tag, e.g.
+//   <script src=".../x402.global.js"
+//           data-x402-api-origin="https://pay.example.com"
+//           data-x402-brand-label="Powered by Acme"
+//           data-x402-brand-href="https://acme.com"
+//           data-x402-builder-wallet="acme"
+//           data-x402-builder-service="acme_checkout"></script>
+function readScriptConfig() {
+	if (typeof document === 'undefined') return;
+	const el = document.currentScript || document.querySelector('script[src*="x402.global"], script[src*="/x402.js"]');
+	const ds = el?.dataset;
+	if (!ds) return;
+	const cfg = {};
+	if (ds.x402ApiOrigin !== undefined) cfg.apiOrigin = ds.x402ApiOrigin;
+	if (ds.x402BrandLabel !== undefined || ds.x402BrandHref !== undefined) {
+		cfg.brand = {};
+		if (ds.x402BrandLabel !== undefined) cfg.brand.label = ds.x402BrandLabel;
+		if (ds.x402BrandHref !== undefined) cfg.brand.href = ds.x402BrandHref;
+	}
+	if (ds.x402BuilderDisable === 'true' || ds.x402BuilderDisable === '') {
+		cfg.builderCode = null;
+	} else if (ds.x402BuilderWallet !== undefined || ds.x402BuilderService !== undefined) {
+		cfg.builderCode = {};
+		if (ds.x402BuilderWallet !== undefined) cfg.builderCode.wallet = ds.x402BuilderWallet;
+		if (ds.x402BuilderService !== undefined) cfg.builderCode.service = ds.x402BuilderService;
+	}
+	if (ds.x402SolanaWeb3Url) cfg.solanaWeb3Url = ds.x402SolanaWeb3Url;
+	if (ds.x402NobleHashesUrl) cfg.nobleHashesUrl = ds.x402NobleHashesUrl;
+	if (Object.keys(cfg).length) configure(cfg);
+}
+
+if (typeof document !== 'undefined') {
+	readScriptConfig();
+	if (document.readyState === 'loading') {
+		document.addEventListener('DOMContentLoaded', init, { once: true });
+	} else {
+		init();
+	}
+	// Re-scan when merchants dynamically inject buttons.
+	const mo = new MutationObserver(() => init());
+	mo.observe(document.documentElement, { childList: true, subtree: true });
+}
+
+// Expose to merchants' inline scripts.
+if (typeof window !== 'undefined') {
+	window.X402 = Object.freeze({ pay, init, configure, version });
+}
+
+export { pay, init, configure, version };

package/src/util.js

@@ -0,0 +1,147 @@
+// Pure, browser-API-free helpers shared by the modal. Kept in their own module
+// so they can be unit-tested in Node without a DOM, and so the core stays lean.
+
+// USDC EIP-3009 typed-data sig works against Base USDC. The domain `version`
+// must match the on-chain `EIP712_DOMAIN_SEPARATOR_VERSION` — Base USDC is "2".
+export const EVM_NETWORKS = {
+	'eip155:8453': { chainId: 8453, name: 'Base', explorer: 'https://basescan.org/tx/' },
+	'eip155:84532': { chainId: 84532, name: 'Base Sepolia', explorer: 'https://sepolia.basescan.org/tx/' },
+	'eip155:42161': { chainId: 42161, name: 'Arbitrum', explorer: 'https://arbiscan.io/tx/' },
+	'eip155:10': { chainId: 10, name: 'Optimism', explorer: 'https://optimistic.etherscan.io/tx/' },
+};
+
+// Stablecoins whose atomics are already 6-decimal USD-pegged (used by caps).
+export const STABLE_NAMES = new Set([
+	'usdc', 'usd coin', 'usdt', 'tether', 'binance-peg usd coin', 'dai',
+]);
+
+// Normalize a single 402 `accept` entry. The x402 spec's canonical atomic-price
+// field is `maxAmountRequired`; some merchants emit `amount`. We read `amount`
+// everywhere downstream, so coerce here once. Without this a spec-compliant
+// merchant yields `accept.amount === undefined` → "NaN USDC".
+export function normalizeAccept(accept) {
+	if (!accept || typeof accept !== 'object') return accept;
+	const amount = accept.amount ?? accept.maxAmountRequired;
+	return amount != null && accept.amount == null ? { ...accept, amount: String(amount) } : accept;
+}
+
+export function isSolanaNetwork(net) {
+	return typeof net === 'string' && (net === 'solana' || net.startsWith('solana:'));
+}
+export function isEvmNetwork(net) {
+	return typeof net === 'string' && net.startsWith('eip155:');
+}
+// The modal only signs EIP-3009 transferWithAuthorization for EVM. When the
+// server publishes both an EIP-3009 entry and a Permit2 sibling (the
+// gas-sponsoring path), pick the EIP-3009 one — the sibling carries
+// `extra.assetTransferMethod === 'permit2'`.
+export function isEip3009Accept(accept) {
+	if (!isEvmNetwork(accept?.network)) return false;
+	const method = accept?.extra?.assetTransferMethod;
+	return !method || method === 'eip3009';
+}
+export function networkLabel(net, accept) {
+	if (isSolanaNetwork(net)) return 'Solana';
+	const meta = EVM_NETWORKS[net];
+	return meta?.name || accept?.extra?.name || net;
+}
+export function explorerUrl(net, tx) {
+	if (!tx) return null;
+	if (isSolanaNetwork(net)) return `https://solscan.io/tx/${tx}`;
+	const meta = EVM_NETWORKS[net];
+	return meta ? `${meta.explorer}${tx}` : null;
+}
+
+export function formatAmount(rawAtomics, decimals = 6) {
+	const n = Number(rawAtomics) / 10 ** decimals;
+	if (n < 0.01) return n.toFixed(6).replace(/0+$/, '').replace(/\.$/, '');
+	if (n < 1) return n.toFixed(4).replace(/0+$/, '').replace(/\.$/, '');
+	return n.toFixed(2);
+}
+
+export function b64encode(obj) {
+	const json = JSON.stringify(obj);
+	if (typeof Buffer !== 'undefined') return Buffer.from(json, 'utf8').toString('base64');
+	return btoa(unescape(encodeURIComponent(json)));
+}
+export function b64decode(str) {
+	if (!str) return null;
+	try {
+		const bin = typeof Buffer !== 'undefined' ? Buffer.from(str, 'base64').toString('utf8') : decodeURIComponent(escape(atob(str)));
+		return JSON.parse(bin);
+	} catch (_) {
+		return null;
+	}
+}
+
+// Base58 (Bitcoin alphabet) — Solana's encoding for addresses and signatures.
+const BASE58_ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz';
+export function base58encode(bytes) {
+	if (!bytes || bytes.length === 0) return '';
+	let leadingZeros = 0;
+	while (leadingZeros < bytes.length && bytes[leadingZeros] === 0) leadingZeros++;
+	let n = 0n;
+	for (let i = 0; i < bytes.length; i++) n = (n << 8n) | BigInt(bytes[i]);
+	let out = '';
+	while (n > 0n) {
+		out = BASE58_ALPHABET[Number(n % 58n)] + out;
+		n /= 58n;
+	}
+	for (let i = 0; i < leadingZeros; i++) out = BASE58_ALPHABET[0] + out;
+	return out;
+}
+
+// Convert an asset's atomic amount to micro-USD for cap accounting. Stablecoins
+// pass through (scaled to 6 decimals); non-stable assets pass through atomic and
+// must be capped server-side (the browser modal fetches no prices).
+export function toMicroUsd(amount, accept) {
+	const atomic = BigInt(amount);
+	const decimals = Number(accept?.extra?.decimals ?? 6);
+	const name = String(accept?.extra?.name || '').toLowerCase();
+	if (STABLE_NAMES.has(name)) {
+		if (decimals === 6) return atomic;
+		if (decimals > 6) return atomic / 10n ** BigInt(decimals - 6);
+		return atomic * 10n ** BigInt(6 - decimals);
+	}
+	return atomic;
+}
+
+export function spendBuckets(timestamp = Date.now()) {
+	const hour = Math.floor(timestamp / 3_600_000);
+	const day = Math.floor(timestamp / 86_400_000);
+	return { hour, day };
+}
+
+// Build the CAIP-122 SIWX message string. The server rebuilds the same string
+// from payload fields when verifying — any line-by-line drift makes the
+// recovered signer mismatch payload.address and the signature is rejected.
+export function buildSiwxMessage(info, chain, address) {
+	const isEvm = chain.type === 'eip191';
+	const accountHeader = isEvm
+		? `${info.domain} wants you to sign in with your Ethereum account:`
+		: `${info.domain} wants you to sign in with your Solana account:`;
+	const [, chainTail = ''] = String(chain.chainId).split(':');
+	const chainRef = isEvm ? String(parseInt(chainTail, 10)) : chainTail;
+
+	const lines = [accountHeader, address, ''];
+	if (info.statement) {
+		lines.push(info.statement, '');
+	} else if (isEvm) {
+		// siwe's prepareMessage() reserves the statement block even when absent,
+		// emitting an extra blank line. SIWS does not.
+		lines.push('');
+	}
+	lines.push(`URI: ${info.uri}`);
+	lines.push(`Version: ${info.version || '1'}`);
+	lines.push(`Chain ID: ${chainRef}`);
+	lines.push(`Nonce: ${info.nonce}`);
+	lines.push(`Issued At: ${info.issuedAt}`);
+	if (info.expirationTime) lines.push(`Expiration Time: ${info.expirationTime}`);
+	if (info.notBefore) lines.push(`Not Before: ${info.notBefore}`);
+	if (info.requestId !== undefined && info.requestId !== null) lines.push(`Request ID: ${info.requestId}`);
+	if (Array.isArray(info.resources) && info.resources.length) {
+		lines.push('Resources:');
+		for (const r of info.resources) lines.push(`- ${r}`);
+	}
+	return lines.join('\n');
+}