@profullstack/x402-gateway 0.10.2 → 0.11.0

package/README.md

@@ -102,7 +102,11 @@ export const GET = robotsRoute(gateway, { disallow: ['/login', '/api/'] });
 | `secret` | the CoinPay key | pass signing secret |
 | `page` | built in | `(ctx) => html` |
 | `contact` | | mailto: or URL for bulk deals |
-| `onSale` | | `({ payer, ref, token, expiresAt, userAgent, priceCents, currency }) => …`, for accounting |
+| `onSale` | | `({ payer, ref, token, expiresAt, userAgent, priceCents, days, totalCents, currency, property, resourcePath, ipHash, source, ... }) => …`, for accounting. `source` is `'x402'` or `'checkout'` (which adds `email`, `accountId`, `checkoutSessionId`); a checkout sale can be reported by both the return page and the webhook, so dedupe on `ref` |
+| `property` | the siteUrl hostname | the site a sale is recorded for, sent to CoinPay with every settle. A function `(request) => string` reads it per request, e.g. from `Host` |
+| `ipSalt` | the pass secret | key for the address hash recorded with a sale (the address itself is never sent) |
+| `checkout` | on, with `coinpay.apiKey` | the human "Buy a day pass" button: `{ apiKey?, baseUrl?, account?: (request) => userId, expiresInMinutes? }`. `false` hides it. Shown only while CoinPay answers `/api/checkout/sessions` |
+| `passCookie` | `crawl_pass` | cookie a pass is also read from (the checkout return page sets it) |
 
 | `denyCidrs` | `[]` | IPv4 ranges answered with a tiny `403` before anything else. For a VPS fleet that spoofs a browser: hosting ranges serve no readers. |
 | `chargeSpoofedBrowsers` | `false` | charge a request that claims `Chrome/…` but sends no `Sec-Fetch-Mode`. Every Chromium since 76, headless included, sends it on every request and no script or extension can remove it, so its absence means an HTTP client with a copied string. Firefox and Safari are not judged. |
@@ -181,10 +185,28 @@ The lists catch crawlers that name themselves. Two do not: a VPS fleet wearing a
 
 ## How the money moves
 
-The offer is x402 v2 in CoinPay's dialect: USDC under the `exact` scheme on Base, Polygon or Ethereum, EIP-3009 `transferWithAuthorization`. The buyer signs, the gateway sends the proof to CoinPay's `/api/x402/verify` and `/api/x402/settle`, and CoinPay's relayer broadcasts the transfer, paying the gas. The USDC goes straight to `payTo`.
+The offer is x402 v2 in CoinPay's dialect (and in the spec's `PAYMENT-REQUIRED` header): USDC under the `exact` scheme on Base, Polygon or Ethereum, EIP-3009 `transferWithAuthorization`. The buyer signs, the gateway sends the proof to CoinPay's `/api/x402/verify` and `/api/x402/settle`, and CoinPay's relayer broadcasts the transfer, paying the gas. The USDC goes straight to `payTo`.
 
 A pass is `cp_<payload>.<hmac>`: its own expiry and the payment's nonce, signed with HMAC-SHA256. Verifying one is a hash, not a query. A proof is single-use; retrying with the same proof returns a pass bounded by the proof's own validity window, so a lost response is not a lost dollar and a replayed header is not a free day.
 
+## The x402 v2 headers
+
+Every 402 that carries an offer also carries it in `PAYMENT-REQUIRED`: the spec's `PaymentRequired` object, base64 JSON, with the resource at the top level. A proof is read from `PAYMENT-SIGNATURE` first and `X-PAYMENT` second, in either CoinPay's shape (`scheme` and `network` at the top) or the spec's (`accepted: { scheme, network, ... }`). A sale answers with `PAYMENT-RESPONSE` (`{ success, transaction, network, payer }`) beside the JSON receipt. Nothing old was removed: the body offer, `X-PAYMENT` and the receipt are unchanged.
+
+## Who paid, and where
+
+Every settle call sends CoinPay `metadata: { property, resource_path, payer, user_agent, ip_hash, source }`, which CoinPay keeps on the `x402_payments` row. `resource_path` is the page actually asked for: the gated URL itself, or `?from=` on the sales page (the buy button carries it). `ip_hash` is an HMAC of the address keyed by `ipSalt`, never the address. `onSale` gets the same fields.
+
+## People: Buy a day pass
+
+The sales page shows a **Buy a day pass** form (email, days) whenever CoinPay serves hosted checkout sessions. It posts to `/crawl/checkout`, which creates a session (`POST {coinpay}/api/checkout/sessions` with `amount`, `currency: 'USD'`, `customer_email`, `account_id`, `property`, `metadata`, `success_url`, `cancel_url`) and redirects to CoinPay, where the buyer pays with any coin the business takes or PayPal. The session id rides back in a signed cookie to `/crawl/checkout/return`, which reads the session from CoinPay, and once it is paid mints the same `cp_...` pass the x402 path mints, valid from when it was paid, and shows it with how to send it (header, bearer, or the `crawl_pass` cookie it also sets). Until CoinPay serves the endpoint (a 404 on the probe, rechecked every few minutes) the form is simply not shown.
+
+`account_id` is the buyer's email unless `checkout.account(request)` returns the signed-in user. CoinPay webhooks for checkout sessions can go to `/crawl/checkout/webhook`, or to a site's own route via `gateway.checkoutWebhook(request)` / `gateway.checkoutPaid(body)`: the body is only a hint, the session is re-read from CoinPay before anything is minted.
+
+## Which coins x402 offers
+
+USDC on Base, Polygon and Ethereum, and nothing else on purpose: CoinPay's v2 settle broadcasts EIP-3009 `transferWithAuthorization` only on chains 1, 137 and 8453, and USDC is the only EIP-3009 dollar token there (USDT has none). An offer for anything else would verify and never settle. Every other coin, and PayPal, is the checkout button's job.
+
 ## Who is on which list
 
 `TRAINING_AGENTS` is the documented corpus-crawl token of each operator; `RETRIEVAL_AGENTS` the search half of the same pairs: GPTBot / OAI-SearchBot, ClaudeBot / Claude-SearchBot, meta-externalagent / Meta-ExternalFetcher, Applebot-Extended / Applebot. Google-Extended stays welcome because Google documents it as also gating Gemini app grounding. Matching is a substring of the user agent, which identifies a self-declared crawler and nothing more: a crawler wearing a browser's user agent walks past this, and that one needs blocking at the edge.

package/index.d.ts

@@ -14,6 +14,31 @@ export interface Sale {
   /** `priceCents * days`. */
   totalCents: number;
   currency: string;
+  /** The site the sale is for (option `property`, default the siteUrl hostname). */
+  property?: string;
+  /** The page bought: the gated URL's path, or `?from=` on the sales page. */
+  resourcePath?: string | null;
+  /** Keyed hash of the buyer's address (never the address). */
+  ipHash?: string | null;
+  /** 'x402' for a proof, 'checkout' for a CoinPay hosted checkout. */
+  source?: 'x402' | 'checkout';
+  network?: string | null;
+  txHash?: string | null;
+  /** Checkout only. */
+  email?: string | null;
+  accountId?: string | null;
+  checkoutSessionId?: string;
+  /** What was sent to CoinPay with the sale. */
+  metadata?: Record<string, unknown>;
+}
+
+export interface CheckoutOptions {
+  /** Key for POST /api/checkout/sessions; defaults to `coinpay.apiKey`. */
+  apiKey?: string;
+  baseUrl?: string;
+  /** The signed-in site user, recorded as `account_id`; the buyer's email otherwise. */
+  account?: (request: Request) => string | null | undefined | Promise<string | null | undefined>;
+  expiresInMinutes?: number;
 }
 
 export interface PageContext {
@@ -36,6 +61,8 @@ export interface PageContext {
   contact: string;
   /** Where a Power Key is bought and the header it goes in, or null when they are switched off. */
   powerKey?: { shop: string; header: string } | null;
+  /** The "Buy a day pass" form, or null when CoinPay's hosted checkout is not available. */
+  checkout?: { action: string; from: string; days: number } | null;
 }
 
 export interface GatewayOptions {
@@ -93,6 +120,14 @@ export interface GatewayOptions {
   contact?: string;
   /** Awaited before the buyer's receipt is sent, and its errors are swallowed: a sale is recorded, and a recording failure never costs the buyer the pass. */
   onSale?: (sale: Sale) => void | Promise<void>;
+  /** The site a sale is recorded for; defaults to the siteUrl hostname. A function reads it per request (e.g. from Host). */
+  property?: string | ((request: Request) => string | null | undefined);
+  /** Key for the recorded address hash; defaults to the pass secret. */
+  ipSalt?: string;
+  /** The human checkout (CoinPay hosted, any coin or PayPal). On by default; `false` hides it. */
+  checkout?: CheckoutOptions | false;
+  /** Cookie a pass is also read from. Default 'crawl_pass'. */
+  passCookie?: string;
   /**
    * A free allowance for ordinary callers, after which the gateway answers 402
    * with the offer instead of letting the request through. A bare number means
@@ -196,7 +231,9 @@ export interface Gateway {
   handle: Handle;
   sell: (request: Request, context?: SellContext) => Promise<Response>;
   enabled: boolean;
-  options: Required<Omit<GatewayOptions, 'onSale' | 'fetch' | 'page' | 'isPaidAgent'>> & {
+  options: Required<Omit<GatewayOptions, 'onSale' | 'fetch' | 'page' | 'isPaidAgent' | 'property' | 'checkout'>> & {
+    property: GatewayOptions['property'] | null;
+    checkout: CheckoutOptions | null;
     onSale: GatewayOptions['onSale'] | null;
     fetch: typeof fetch;
     page: (ctx: PageContext) => string;
@@ -216,6 +253,19 @@ export interface Gateway {
   offer: (days?: number) => Offer;
   /** The full 402 body around that offer: the offer plus the pass terms. */
   receipt: (days?: number, extra?: Record<string, unknown>) => Offer & Record<string, unknown>;
+  /** The PAYMENT-REQUIRED header value (base64 JSON) for `days`, or null when payments are off. */
+  paymentRequired: (days?: number, error?: string) => string | null;
+  /** Who and where a request would be recorded as. */
+  saleContext: (request: Request, source: 'x402' | 'checkout') => Promise<{ property: string; resource_path: string; user_agent: string; ip_hash: string | null; source: string }>;
+  /** Whether the checkout button shows. */
+  checkoutAvailable: () => Promise<boolean>;
+  /** A webhook handler for CoinPay checkout events: re-reads the session from CoinPay and mints its pass. */
+  checkoutWebhook: (request: Request) => Promise<Response>;
+  /** Mint the pass for a paid session, from a webhook body or a session id. Null unless CoinPay says it is paid. */
+  checkoutPaid: (
+    bodyOrId: unknown,
+    request?: Request,
+  ) => Promise<{ token: string; expiresAt: string; days: number; email: string | null; accountId: string | null; ref: string } | null>;
 }
 
 export function createGateway(options: GatewayOptions): Gateway;
@@ -261,6 +311,13 @@ export const METHODS: Array<{ key: string; network: string; asset: string; label
 export const X402_METHODS: typeof METHODS;
 export function buildOffer(args: { payTo: string; priceCents: number; resource: string; description?: string; maxTimeoutSeconds?: number; methods?: typeof METHODS }): Offer;
 export function decodePayment(header: string | null | undefined): Record<string, unknown> | null;
+export function decodeHeader(header: string | null | undefined): Record<string, unknown> | null;
+export function encodeHeader(value: unknown): string;
+export function paymentRequiredHeader(offer: Offer, args?: { url?: string; description?: string; error?: string }): string;
+export function paymentResponseHeader(args: { transaction?: string | null; network?: string | null; payer?: string | null }): string;
+export function renderNotice(ctx: { siteName: string; siteUrl: string; buyUrl: string; title: string; body: string }): string;
+export function renderPassPage(ctx: { siteName: string; siteUrl: string; buyUrl: string; token: string; expiresAt: string; days: number; header: string; cookie: string; email?: string | null }): string;
+export function sessionIdFromWebhook(body: unknown): string | null;
 export function expectedFor(payment: unknown, offer: Offer): { amount: string; resource: string; payTo: string; asset: string } | null;
 /** The value a proof authorizes, in the token's smallest unit, or null. */
 export function paidValueOf(payment: unknown): bigint | null;
@@ -269,8 +326,8 @@ export function daysPaid(value: bigint | null, unit: string | number | bigint, m
 export function verifyAndSettle(
   payment: unknown,
   expected: { amount: string; resource: string; payTo: string; asset: string },
-  coinpay: { apiKey: string; baseUrl: string; fetch?: typeof fetch },
-): Promise<{ ok: true; payer: string | null; ref: string | null } | { ok: false; reason: string; replay: boolean }>;
+  coinpay: { apiKey: string; baseUrl: string; fetch?: typeof fetch; metadata?: Record<string, unknown> | null },
+): Promise<{ ok: true; payer: string | null; ref: string | null; txHash: string | null; network: string | null } | { ok: false; reason: string; replay: boolean }>;
 
 /** ./hono */
 export function x402Gateway(gatewayOrOptions: Gateway | GatewayOptions): (c: { req: { raw: Request } }, next: () => Promise<void>) => Promise<Response | undefined>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/x402-gateway",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "type": "module",
   "description": "Sell crawl access to AI training crawlers by the day over x402, settled by CoinPay. One middleware: 402 with an offer, a sales page with CLI instructions, signed passes, Profullstack Power Keys honoured as a pass, and a robots.txt that keeps search crawlers welcome.",
   "keywords": [

package/src/checkout.js

@@ -0,0 +1,199 @@
+/**
+ * The human way in: a day pass bought through CoinPay's hosted checkout.
+ *
+ * An x402 proof needs a wallet that signs EIP-3009, which is a program's
+ * tool. A person who landed on the sales page wants a button: pay with any
+ * coin CoinPay takes, or PayPal, and get the same pass the x402 path mints.
+ *
+ * CoinPay hosts the payment (`POST /api/checkout/sessions` -> `{ id, url }`),
+ * and the gateway stays stateless: the session id rides in a signed cookie to
+ * the return page, the return page asks CoinPay whether that session is paid,
+ * and the pass is minted from what CoinPay answers. Nothing the buyer's
+ * browser says is believed about money.
+ *
+ * The endpoint is new, so its absence is expected: `available()` probes it
+ * and the sales page shows the button only when it answers.
+ */
+
+const PAID = new Set(['paid', 'complete', 'completed', 'succeeded', 'success', 'confirmed', 'settled', 'forwarded']);
+const DEAD = new Set(['expired', 'cancelled', 'canceled', 'failed', 'void', 'voided', 'refunded']);
+
+/** How long a probe answer is believed, by outcome. */
+const PROBE_TTL_UP = 10 * 60 * 1000;
+const PROBE_TTL_DOWN = 5 * 60 * 1000;
+
+/** Probe answers shared by every gateway in the process that talks to one CoinPay. */
+const probes = new Map();
+
+/** A CoinPay checkout session id as the gateway will accept one: short, URL-safe. */
+export const isSessionId = (id) => typeof id === 'string' && /^[A-Za-z0-9_-]{6,128}$/.test(id);
+
+/** Whether a string looks like an email address, enough to send a receipt to. */
+export const isEmail = (s) => typeof s === 'string' && s.length <= 254 && /^[^\s@<>"']+@[^\s@<>"']+\.[^\s@<>"']+$/.test(s);
+
+/**
+ * @param {object} args
+ * @param {string} args.apiKey
+ * @param {string} args.baseUrl
+ * @param {typeof fetch} [args.fetch]
+ */
+export function checkoutClient({ apiKey, baseUrl, fetch: f = globalThis.fetch }) {
+  const root = `${baseUrl}/api/checkout/sessions`;
+  const headers = { authorization: `Bearer ${apiKey}`, accept: 'application/json' };
+
+  const readJson = async (res) => {
+    try {
+      return JSON.parse(await res.text());
+    } catch {
+      return {};
+    }
+  };
+
+  /** Mark the endpoint as missing, so the button hides until the next probe. */
+  const markDown = () => probes.set(root, { ok: false, at: Date.now() });
+
+  return {
+    /**
+     * Whether CoinPay serves checkout sessions yet. A 404 means the route is
+     * not deployed; any other answer below 500 (401, 405, 200) means it is.
+     * Errors and timeouts read as "not now" without being cached for long.
+     */
+    async available() {
+      const hit = probes.get(root);
+      const now = Date.now();
+      if (hit && now - hit.at < (hit.ok ? PROBE_TTL_UP : PROBE_TTL_DOWN)) return hit.ok;
+      let ok = false;
+      try {
+        const res = await f(root, { method: 'GET', headers, signal: AbortSignal.timeout(3000) });
+        ok = res.status !== 404 && res.status < 500;
+        if (res.status >= 500) {
+          // Up but unwell: believe it for a minute, not ten.
+          probes.set(root, { ok: false, at: now - PROBE_TTL_DOWN + 60_000 });
+          return false;
+        }
+      } catch {
+        probes.set(root, { ok: false, at: now - PROBE_TTL_DOWN + 60_000 });
+        return false;
+      }
+      probes.set(root, { ok, at: now });
+      return ok;
+    },
+
+    /** The last probe answer without asking again: for a renderer that cannot wait. */
+    known() {
+      return probes.get(root)?.ok ?? false;
+    },
+
+    /**
+     * Create a session. Resolves to `{ ok: true, id, url }`, or
+     * `{ ok: false, status, missing, reason }` where `missing` means the
+     * endpoint is not deployed.
+     */
+    async create(body) {
+      let res;
+      try {
+        res = await f(root, {
+          method: 'POST',
+          headers: { ...headers, 'content-type': 'application/json' },
+          body: JSON.stringify(body),
+          signal: AbortSignal.timeout(15000),
+        });
+      } catch (err) {
+        return { ok: false, status: 0, missing: false, reason: String(err?.message ?? err) };
+      }
+      const json = await readJson(res);
+      if (res.status === 404) {
+        markDown();
+        return { ok: false, status: 404, missing: true, reason: 'checkout sessions are not available' };
+      }
+      const s = json?.session ?? json?.data ?? json;
+      const id = s?.id ?? s?.session_id ?? s?.checkout_session_id;
+      const url = s?.url ?? s?.checkout_url ?? s?.hosted_url;
+      if (!res.ok || !isSessionId(String(id ?? '')) || !/^https:\/\//.test(String(url ?? ''))) {
+        return { ok: false, status: res.status, missing: false, reason: String(json?.error ?? `checkout failed (${res.status})`) };
+      }
+      return { ok: true, id: String(id), url: String(url) };
+    },
+
+    /** Read a session back from CoinPay. Null when it cannot be read. */
+    async get(id) {
+      if (!isSessionId(id)) return null;
+      try {
+        const res = await f(`${root}/${encodeURIComponent(id)}`, {
+          method: 'GET',
+          headers,
+          signal: AbortSignal.timeout(15000),
+        });
+        if (!res.ok) return null;
+        const json = await readJson(res);
+        const s = json?.session ?? json?.data ?? json;
+        return s && typeof s === 'object' ? s : null;
+      } catch {
+        return null;
+      }
+    },
+  };
+}
+
+const toSeconds = (v) => {
+  if (v === undefined || v === null || v === '') return null;
+  const n = typeof v === 'number' ? v : Date.parse(String(v));
+  if (!Number.isFinite(n)) return null;
+  // A number below 10^11 is already seconds; anything larger is milliseconds.
+  return Math.floor(n < 1e11 ? n : n / 1000);
+};
+
+/**
+ * What a session says, normalised: whether it is paid, still open, or dead,
+ * how much it was for, when it was paid, and who and where it was for.
+ *
+ * `amount` is read in dollars (the unit the session was created in) unless
+ * the session also names `amount_cents`.
+ */
+export function sessionState(session) {
+  const status = String(session?.status ?? session?.payment_status ?? '').toLowerCase();
+  const paid = session?.paid === true || PAID.has(status);
+  const dead = !paid && DEAD.has(status);
+  const metadata = session?.metadata && typeof session.metadata === 'object' ? session.metadata : {};
+  let cents = null;
+  if (Number.isFinite(Number(session?.amount_cents))) cents = Math.round(Number(session.amount_cents));
+  else if (session?.amount !== undefined && Number.isFinite(Number(session.amount))) cents = Math.round(Number(session.amount) * 100);
+  const currency = String(session?.currency ?? 'USD').toUpperCase();
+  const paidAt =
+    toSeconds(session?.paid_at) ??
+    toSeconds(session?.completed_at) ??
+    toSeconds(session?.confirmed_at) ??
+    toSeconds(session?.updated_at) ??
+    toSeconds(session?.created_at);
+  return {
+    id: session?.id ? String(session.id) : null,
+    status,
+    paid,
+    dead,
+    cents,
+    currency,
+    paidAt,
+    property: session?.property ?? metadata.property ?? null,
+    email: session?.customer_email ?? metadata.customer_email ?? null,
+    accountId: session?.account_id ?? metadata.account_id ?? null,
+    metadata,
+  };
+}
+
+/**
+ * The session id a CoinPay webhook is about. Webhook bodies are nested
+ * (`{ id: <event>, type, data: { ... } }`), so the top-level `id` is the
+ * EVENT and is never taken for the session.
+ */
+export function sessionIdFromWebhook(body) {
+  const candidates = [
+    body?.checkout_session_id,
+    body?.data?.checkout_session_id,
+    body?.data?.session_id,
+    body?.data?.object?.checkout_session_id,
+    body?.data?.object?.id,
+    body?.data?.id,
+  ];
+  for (const c of candidates) if (isSessionId(String(c ?? ''))) return String(c);
+  return null;
+}

package/src/index.js

@@ -2,8 +2,9 @@ import { HEADER as POWER_KEY_HEADER, isPowerKey, keyFrom, PROFULLSTACK_KEYS, SHO
 import { HEADLESS_AGENTS, isTrainingAgent, RETRIEVAL_AGENTS, SCRAPER_AGENTS, TRAINING_AGENTS, VERIFIED_RETRIEVAL, WELCOME_CRAWLERS } from './agents.js';
 import { clientIp, compileCidrs, impostorCrawler, inCidrs, isSpoofedBrowser, isStaleBrowser, welcomeCrawler } from './edge.js';
 import { memoryQuotaStore, meters, normaliseQuota, quotaHeaders, spend } from './quota.js';
-import { challengePage, challengeToken, passedChallenge } from './challenge.js';
-import { renderPage } from './page.js';
+import { challengePage, challengeToken, cookieValue, passedChallenge } from './challenge.js';
+import { checkoutClient, isEmail, isSessionId, sessionIdFromWebhook, sessionState } from './checkout.js';
+import { renderNotice, renderPage, renderPassPage } from './page.js';
 import { mintPass, readPass } from './pass.js';
 import { robotsTxt } from './robots.js';
 import {
@@ -12,6 +13,8 @@ import {
   expectedFor,
   METHODS,
   nonceOf,
+  paymentRequiredHeader,
+  paymentResponseHeader,
   settleAgain,
   validBeforeOf,
   verifyAndSettle,
@@ -39,10 +42,21 @@ export {
   welcomeCrawler,
 } from './edge.js';
 export { challengePage, challengeToken, cookieValue, passedChallenge } from './challenge.js';
-export { renderPage } from './page.js';
+export { renderNotice, renderPage, renderPassPage } from './page.js';
+export { checkoutClient, sessionIdFromWebhook, sessionState } from './checkout.js';
 export { mintPass, readPass } from './pass.js';
 export { robotsTxt } from './robots.js';
-export { buildOffer, decodePayment, expectedFor, METHODS, verifyAndSettle } from './x402.js';
+export {
+  buildOffer,
+  decodeHeader,
+  decodePayment,
+  encodeHeader,
+  expectedFor,
+  METHODS,
+  paymentRequiredHeader,
+  paymentResponseHeader,
+  verifyAndSettle,
+} from './x402.js';
 export { memoryQuotaStore, normaliseQuota, quotaHeaders, spend } from './quota.js';
 export { isPowerKey, keyFrom, PROFULLSTACK_KEYS, verifyKey } from '@profullstack/keys';
 
@@ -91,7 +105,11 @@ export { isPowerKey, keyFrom, PROFULLSTACK_KEYS, verifyKey } from '@profullstack
  * @param {Iterable<string>} [options.revokedKeys]  Power Key subjects no longer honoured
  * @param {(ctx: object) => string} [options.page] custom sales page renderer
  * @param {string} [options.contact]               mailto: or URL for bulk deals
- * @param {(sale: object) => void|Promise<void>} [options.onSale]   accounting hook; awaited before the receipt goes out, and its errors are swallowed
+ * @param {(sale: object) => void|Promise<void>} [options.onSale]   accounting hook; awaited before the receipt goes out, and its errors are swallowed. Carries `property`, `resourcePath`, `payer`, `userAgent`, `ipHash` and `source` ('x402' or 'checkout'); a checkout sale may be reported more than once (return page and webhook), so dedupe on `ref`
+ * @param {string|((request: Request) => string)} [options.property]  the site this sale is for, recorded with CoinPay; defaults to the siteUrl hostname
+ * @param {string} [options.ipSalt]                key for the address hash recorded with a sale; defaults to the pass secret
+ * @param {{apiKey?: string, baseUrl?: string, account?: (request: Request) => string|null|Promise<string|null>, expiresInMinutes?: number}|false} [options.checkout]  the human "Buy a day pass" button (CoinPay hosted checkout, any coin or PayPal); on by default with the CoinPay key, shown only once CoinPay serves checkout sessions
+ * @param {string} [options.passCookie='crawl_pass']  cookie a pass is also read from
  * @param {typeof fetch} [options.fetch]           for tests
  */
 export function createGateway(options = {}) {
@@ -114,6 +132,68 @@ export function createGateway(options = {}) {
    */
   const howUrl = `${buyUrl}?format=html`;
 
+  /** The site a sale is for: config, or what the host app says per request. */
+  const propertyOf = (request) => {
+    if (typeof o.property === 'function') {
+      try {
+        const p = o.property(request);
+        if (p) return String(p);
+      } catch {}
+    } else if (o.property) {
+      return o.property;
+    }
+    return new URL(o.siteUrl).hostname;
+  };
+
+  /**
+   * The page a sale bought. On a gated URL that is the URL itself; on the
+   * sales page it is whatever `?from=` says (the button and the 402 carry it),
+   * since "/crawl" names the shop rather than the page anyone wanted.
+   */
+  const resourcePathOf = (request) => {
+    const url = new URL(request.url);
+    const from = url.searchParams.get('from');
+    if (url.pathname === o.path || url.pathname.startsWith(`${o.path}/`)) {
+      if (from && from.startsWith('/') && !from.startsWith('//') && from.length <= 1024) return from;
+      return url.pathname;
+    }
+    const params = new URLSearchParams(url.search);
+    for (const k of ['days', 'format', 'from']) params.delete(k);
+    const q = params.toString();
+    return `${url.pathname}${q ? `?${q}` : ''}`.slice(0, 1024);
+  };
+
+  /** A keyed hash of the caller's address: enough to tell repeat buyers apart, never the address. */
+  const ipHashOf = async (request) => {
+    const ip = clientIp(request);
+    const key = o.ipSalt || secret;
+    if (!ip || !key) return null;
+    const k = await crypto.subtle.importKey('raw', new TextEncoder().encode(String(key)), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const sig = new Uint8Array(await crypto.subtle.sign('HMAC', k, new TextEncoder().encode(`ip:${ip}`)));
+    return Array.from(sig.slice(0, 16), (b) => b.toString(16).padStart(2, '0')).join('');
+  };
+
+  /** Who paid and where, as CoinPay's ledger and onSale both get it. */
+  const saleContext = async (request, source) => ({
+    property: propertyOf(request),
+    resource_path: resourcePathOf(request),
+    user_agent: (request.headers.get('user-agent') ?? '').slice(0, 512),
+    ip_hash: await ipHashOf(request),
+    source,
+  });
+
+  /*
+   * The human checkout. On whenever there is a key to create sessions with
+   * and a secret to sign the session cookie; shown only once CoinPay answers.
+   */
+  const checkoutPath = `${o.path}/checkout`;
+  const checkoutKey = o.checkout ? o.checkout.apiKey || o.coinpay.apiKey : '';
+  const cpCheckout =
+    o.checkout && checkoutKey && secret
+      ? checkoutClient({ apiKey: checkoutKey, baseUrl: o.checkout.baseUrl || o.coinpay.baseUrl, fetch: o.fetch })
+      : null;
+  const checkoutCookie = 'x402_checkout';
+
   /**
    * How many terms a request is asking to buy: `?days=N`, clamped to
    * [1, maxDays]. Anything unparseable is one day, which is what the offer
@@ -161,8 +241,24 @@ export function createGateway(options = {}) {
 
   const noStore = {
     'cache-control': 'no-store',
-    vary: 'Accept, User-Agent, X-Payment',
+    vary: 'Accept, User-Agent, X-Payment, Payment-Signature',
+    'access-control-expose-headers': 'PAYMENT-REQUIRED, PAYMENT-RESPONSE',
   };
+
+  /**
+   * The spec's PAYMENT-REQUIRED header for a 402: the same offer as the body,
+   * base64 JSON. Absent when payments are off, since an empty offer is no
+   * offer.
+   */
+  const required = (days = 1, error) =>
+    enabled
+      ? {
+          'payment-required': paymentRequiredHeader(offer(days), {
+            url: days > 1 ? `${buyUrl}?days=${days}` : buyUrl,
+            error,
+          }),
+        }
+      : {};
   const json = (body, status, headers = {}) =>
     new Response(JSON.stringify(body, null, 2), {
       status,
@@ -200,8 +296,18 @@ export function createGateway(options = {}) {
     retrieval: o.retrieval,
     contact: o.contact,
     powerKey: o.powerKeys ? { shop: SHOP_URL, header: POWER_KEY_HEADER } : null,
+    checkout: null,
   });
 
+  /** The page context with the checkout button, when CoinPay serves sessions. */
+  const pageCtxFor = async (request, days, usage, quota) => {
+    const ctx = pageCtx(days, usage, quota);
+    if (cpCheckout && (await cpCheckout.available())) {
+      ctx.checkout = { action: checkoutPath, from: resourcePathOf(request), days };
+    }
+    return ctx;
+  };
+
   /**
    * The pass a request presents: a day pass from the named header or a bearer
    * token, or a Power Key wherever @profullstack/keys reads one.
@@ -211,7 +317,10 @@ export function createGateway(options = {}) {
     if (direct) return direct.trim();
     const m = /^Bearer\s+(cp_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)$/i.exec(request.headers.get('authorization') ?? '');
     if (m) return m[1];
-    return o.powerKeys ? keyFrom(request) : null;
+    const pk = o.powerKeys ? keyFrom(request) : null;
+    if (pk) return pk;
+    const cookie = cookieValue(request, o.passCookie);
+    return cookie && cookie.startsWith('cp_') ? cookie : null;
   };
 
   /**
@@ -274,7 +383,8 @@ export function createGateway(options = {}) {
    */
   async function sell(request, context = {}) {
     const ua = request.headers.get('user-agent') ?? '';
-    const proofHeader = request.headers.get('x-payment');
+    // The spec's header first, then the one CoinPay's payer has always sent.
+    const proofHeader = request.headers.get('payment-signature') || request.headers.get('x-payment');
     const asked = daysFrom(request);
     // Present when the free allowance is what stopped this request, rather than
     // the crawler lists. It changes what the 402 says, not what it costs.
@@ -291,10 +401,11 @@ export function createGateway(options = {}) {
 
     if (proofHeader) {
       if (!enabled) return json(receipt(asked, { error: 'Payments are not switched on here.' }), 402);
+      const refuse = (days, error) => json(receipt(days, { error }), 402, required(days, error));
       const payment = decodePayment(proofHeader);
-      if (!payment) return json(receipt(asked, { error: 'X-PAYMENT is not base64 JSON.' }), 402);
+      if (!payment) return refuse(asked, 'The payment proof (PAYMENT-SIGNATURE or X-PAYMENT) is not base64 JSON.');
       const unit = expectedFor(payment, offer(1));
-      if (!unit) return json(receipt(asked, { error: 'Proof does not match an offered network.' }), 402);
+      if (!unit) return refuse(asked, 'Proof does not match an offered network.');
 
       /*
        * The money decides the term, not the URL. A proof is an authorization
@@ -307,11 +418,9 @@ export function createGateway(options = {}) {
        */
       const days = daysPaid(paidValueOf(payment), unit.amount, o.maxDays);
       if (!days) {
-        return json(
-          receipt(asked, {
-            error: `Pay a whole number of days: ${unit.amount} per day in the token's smallest unit, up to ${o.maxDays} days. Add ?days=<n> to ${buyUrl} for the offer.`,
-          }),
-          402,
+        return refuse(
+          asked,
+          `Pay a whole number of days: ${unit.amount} per day in the token's smallest unit, up to ${o.maxDays} days. Add ?days=<n> to ${buyUrl} for the offer.`,
         );
       }
       const expected = expectedFor(payment, offer(days));
@@ -319,7 +428,8 @@ export function createGateway(options = {}) {
 
       const now = Math.floor(Date.now() / 1000);
       const coinpay = { apiKey: o.coinpay.apiKey, baseUrl: o.coinpay.baseUrl, fetch: o.fetch };
-      const result = await verifyAndSettle(payment, expected, coinpay);
+      const sale = await saleContext(request, 'x402');
+      const result = await verifyAndSettle(payment, expected, { ...coinpay, metadata: sale });
 
       let expiresAt = null;
       let replayed = false;
@@ -342,7 +452,7 @@ export function createGateway(options = {}) {
         }
       }
       if (!expiresAt || expiresAt <= now) {
-        return json(receipt(days, { error: result.reason ?? 'Payment could not be settled.' }), 402);
+        return refuse(days, result.reason ?? 'Payment could not be settled.');
       }
 
       const ref = nonceOf(payment) ?? result.ref ?? null;
@@ -360,6 +470,13 @@ export function createGateway(options = {}) {
             days,
             totalCents: o.priceCents * days,
             currency: o.currency,
+            property: sale.property,
+            resourcePath: sale.resource_path,
+            ipHash: sale.ip_hash,
+            source: 'x402',
+            network: result.network ?? payment.network ?? null,
+            txHash: result.txHash ?? null,
+            metadata: { ...sale, ...(result.payer ? { payer: result.payer } : {}) },
           });
         } catch {
           // Accounting must never cost a buyer the pass it paid for.
@@ -377,12 +494,20 @@ export function createGateway(options = {}) {
           use: `curl -H "${o.header}: ${pass.token}" ${o.siteUrl}/`,
         },
         200,
-        { [o.header]: pass.token, [`${o.header}-expires`]: expires },
+        {
+          [o.header]: pass.token,
+          [`${o.header}-expires`]: expires,
+          'payment-response': paymentResponseHeader({
+            transaction: result.txHash ?? ref,
+            network: result.network ?? payment.network,
+            payer: result.payer,
+          }),
+        },
       );
     }
 
     if (wantsHtml(request.headers.get('accept')) || new URL(request.url).searchParams.get('format') === 'html') {
-      return html(o.page(pageCtx(asked, usage, quota)), 402, rateHeaders);
+      return html(o.page(await pageCtxFor(request, asked, usage, quota)), 402, { ...rateHeaders, ...required(asked) });
     }
 
     if (usage && quota) {
@@ -404,11 +529,237 @@ export function createGateway(options = {}) {
           ...(o.benefits ? { unlocks: o.benefits } : {}),
         }),
         402,
-        rateHeaders,
+        { ...rateHeaders, ...required(asked) },
       );
     }
 
-    return json(receipt(asked, { error: `Payment required for training crawlers. Read ${howUrl} for how.` }), 402);
+    return json(receipt(asked, { error: `Payment required for training crawlers. Read ${howUrl} for how.` }), 402, required(asked));
+  }
+
+  /* ------------------------------------------------------------ checkout -- */
+
+  /** Sign and read the cookie that carries a session id to the return page. */
+  const signId = async (id) => {
+    const k = await crypto.subtle.importKey('raw', new TextEncoder().encode(String(secret)), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const sig = new Uint8Array(await crypto.subtle.sign('HMAC', k, new TextEncoder().encode(`checkout:${id}`)));
+    return Array.from(sig.slice(0, 16), (b) => b.toString(16).padStart(2, '0')).join('');
+  };
+  const sessionFromCookie = async (request) => {
+    const raw = cookieValue(request, checkoutCookie);
+    if (!raw) return null;
+    const dot = raw.lastIndexOf('.');
+    if (dot < 0) return null;
+    const id = decodeURIComponent(raw.slice(0, dot));
+    if (!isSessionId(id)) return null;
+    return (await signId(id)) === raw.slice(dot + 1) ? id : null;
+  };
+
+  const notice = (status, title, body, headers = {}) =>
+    html(o.renderNotice({ siteName: o.siteName, siteUrl: o.siteUrl, buyUrl: howUrl, title, body }), status, headers);
+
+  /** Read a form or JSON body, whichever the buyer sent. */
+  const readForm = async (request) => {
+    const type = (request.headers.get('content-type') ?? '').toLowerCase();
+    try {
+      if (type.includes('application/json')) {
+        const j = await request.json();
+        return j && typeof j === 'object' ? j : {};
+      }
+      const text = await request.text();
+      return Object.fromEntries(new URLSearchParams(text.slice(0, 8192)));
+    } catch {
+      return {};
+    }
+  };
+
+  /** POST /crawl/checkout: create a CoinPay session for a pass and send the buyer to it. */
+  async function startCheckout(request) {
+    if (!cpCheckout || !enabled) return notice(404, 'Checkout is not available here', 'This site does not sell passes through checkout yet.');
+    if (request.method !== 'POST') return notice(405, 'Use the button', `Open <a href="${howUrl}">the pass page</a> and press Buy.`, { allow: 'POST' });
+    const form = await readForm(request);
+    const email = String(form.email ?? '').trim().toLowerCase();
+    if (!isEmail(email)) return notice(400, 'An email address is needed', `CoinPay sends the receipt there. <a href="${howUrl}">Go back</a> and enter one.`);
+    const n = Number.parseInt(String(form.days ?? '1'), 10);
+    const days = Number.isFinite(n) && n >= 1 ? Math.min(n, o.maxDays) : 1;
+    const fromRaw = String(form.from ?? '');
+    const from = fromRaw.startsWith('/') && !fromRaw.startsWith('//') ? fromRaw.slice(0, 1024) : o.path;
+
+    let account = null;
+    if (o.checkout.account) {
+      try {
+        account = (await o.checkout.account(request)) || null;
+      } catch {}
+    }
+    const property = propertyOf(request);
+    const ctx = await saleContext(request, 'checkout');
+    const cents = o.priceCents * days;
+    const minutes = o.checkout.expiresInMinutes ?? 60;
+    const created = await cpCheckout.create({
+      amount: Number((cents / 100).toFixed(2)),
+      currency: 'USD',
+      description: `${days === 1 ? 'Day pass' : `${days}-day pass`} for ${o.siteName}`,
+      customer_email: email,
+      account_id: account ? String(account) : email,
+      property,
+      metadata: {
+        kind: 'crawl_pass',
+        source: 'x402-gateway',
+        property,
+        resource_path: from,
+        days,
+        price_cents: o.priceCents,
+        user_agent: ctx.user_agent,
+        ip_hash: ctx.ip_hash,
+      },
+      success_url: `${o.siteUrl}${checkoutPath}/return?session_id={CHECKOUT_SESSION_ID}`,
+      cancel_url: howUrl,
+      expires_in_minutes: minutes,
+    });
+    if (!created.ok) {
+      return created.missing
+        ? notice(503, 'Checkout is not open yet', `Card-free checkout is still being switched on. Meanwhile a pass can be bought over x402: see <a href="${howUrl}">the pass page</a>.`)
+        : notice(502, 'Checkout could not start', `CoinPay did not create the payment (${esc(created.reason)}). Try again in a minute, or <a href="${howUrl}">go back</a>.`);
+    }
+    const cookie = `${checkoutCookie}=${encodeURIComponent(created.id)}.${await signId(created.id)}; Path=${checkoutPath}; Max-Age=${(minutes + 60) * 60}; HttpOnly; Secure; SameSite=Lax`;
+    if ((request.headers.get('accept') ?? '').includes('application/json')) {
+      return json({ id: created.id, url: created.url }, 200, { 'set-cookie': cookie });
+    }
+    return new Response(null, { status: 303, headers: { location: created.url, 'set-cookie': cookie, ...noStore } });
+  }
+
+  /**
+   * Mint the pass a paid session bought, from what CoinPay says about it.
+   * Resolves to `{ ok: true, token, expiresAt, days, state }`, or
+   * `{ ok: false, pending|dead, state }`.
+   *
+   * The pass runs from when the session was paid, so reloading the return
+   * page re-mints the same pass rather than a longer one.
+   */
+  async function passForSession(id) {
+    if (!cpCheckout || !isSessionId(id)) return { ok: false, state: null };
+    const session = await cpCheckout.get(id);
+    if (!session) return { ok: false, state: null };
+    const state = sessionState(session);
+    if (state.id && state.id !== id) return { ok: false, state };
+    if (!state.paid) return { ok: false, pending: !state.dead, dead: state.dead, state };
+    // A session for another property of the same business opens nothing here.
+    const property = o.property && typeof o.property === 'string' ? o.property : new URL(o.siteUrl).hostname;
+    if (state.property && typeof o.property !== 'function' && String(state.property).toLowerCase() !== property.toLowerCase()) {
+      return { ok: false, foreign: true, state };
+    }
+    if (state.metadata?.kind && state.metadata.kind !== 'crawl_pass') return { ok: false, foreign: true, state };
+    if (state.currency !== 'USD' || !Number.isFinite(state.cents) || state.cents < o.priceCents) return { ok: false, state };
+    const days = Math.min(o.maxDays, Math.floor(state.cents / o.priceCents));
+    const now = Math.floor(Date.now() / 1000);
+    const from = state.paidAt && state.paidAt <= now ? state.paidAt : now;
+    const expiresAt = from + days * o.passMinutes * 60;
+    if (expiresAt <= now) return { ok: false, expired: true, state };
+    const pass = await mintPass({ secret, ref: `checkout:${id}`, expiresAt: expiresAt, now: Math.min(from, now) });
+    return { ok: true, token: pass.token, expiresAt: pass.expiresAt, days, state };
+  }
+
+  /** Tell onSale about a checkout sale. Swallows the hook's errors, like the x402 path. */
+  const reportCheckout = async (id, minted, request) => {
+    if (!o.onSale) return;
+    const st = minted.state;
+    try {
+      await o.onSale({
+        payer: st.email ?? null,
+        ref: `checkout:${id}`,
+        token: minted.token,
+        expiresAt: new Date(minted.expiresAt * 1000).toISOString(),
+        userAgent: st.metadata?.user_agent ?? request?.headers.get('user-agent') ?? '',
+        priceCents: o.priceCents,
+        days: minted.days,
+        totalCents: st.cents,
+        currency: 'USD',
+        property: st.property ?? propertyOf(request ?? new Request(o.siteUrl)),
+        resourcePath: st.metadata?.resource_path ?? null,
+        ipHash: st.metadata?.ip_hash ?? null,
+        source: 'checkout',
+        email: st.email ?? null,
+        accountId: st.accountId ?? null,
+        checkoutSessionId: id,
+        metadata: st.metadata,
+      });
+    } catch {}
+  };
+
+  /** GET /crawl/checkout/return: the buyer is back from CoinPay; show the pass. */
+  async function checkoutReturn(request) {
+    if (!cpCheckout) return notice(404, 'Checkout is not available here', 'This site does not sell passes through checkout yet.');
+    const fromCookie = await sessionFromCookie(request);
+    const q = new URL(request.url).searchParams;
+    const fromQuery = ['session_id', 'checkout_session_id', 'session'].map((k) => q.get(k)).find((v) => isSessionId(v ?? ''));
+    const id = fromCookie ?? fromQuery ?? null;
+    if (!id) return notice(400, 'No checkout to show', `This page opens after paying at CoinPay. <a href="${howUrl}">Buy a pass</a>.`);
+    const minted = await passForSession(id);
+    if (!minted.ok) {
+      if (minted.pending) {
+        return notice(
+          202,
+          'Waiting for the payment to confirm',
+          'CoinPay has not marked this payment paid yet. Crypto payments need a block or two; this page checks again every 15 seconds.',
+          { refresh: '15' },
+        );
+      }
+      if (minted.dead) return notice(410, 'This checkout closed unpaid', `Nothing was charged. <a href="${howUrl}">Start again</a>.`);
+      if (minted.expired) return notice(410, 'This pass has already run out', `<a href="${howUrl}">Buy another</a>.`);
+      return notice(502, 'Could not read this checkout', 'CoinPay did not answer for this payment. Reload in a minute; a paid pass is not lost.');
+    }
+    // Report the sale once per browser: the cookie is cleared on the way out.
+    if (fromCookie) await reportCheckout(id, minted, request);
+    const expires = new Date(minted.expiresAt * 1000).toISOString();
+    const maxAge = Math.max(0, minted.expiresAt - Math.floor(Date.now() / 1000));
+    const headers = new Headers({ 'content-type': 'text/html; charset=utf-8', ...noStore, [o.header]: minted.token, [`${o.header}-expires`]: expires });
+    headers.append('set-cookie', `${o.passCookie}=${minted.token}; Path=/; Max-Age=${maxAge}; HttpOnly; Secure; SameSite=Lax`);
+    headers.append('set-cookie', `${checkoutCookie}=; Path=${checkoutPath}; Max-Age=0; HttpOnly; Secure; SameSite=Lax`);
+    const body = o.renderPassPage({
+      siteName: o.siteName,
+      siteUrl: o.siteUrl,
+      buyUrl: howUrl,
+      token: minted.token,
+      expiresAt: expires,
+      days: minted.days,
+      header: o.header,
+      cookie: o.passCookie,
+      email: minted.state.email,
+    });
+    return new Response(body, { status: 200, headers });
+  }
+
+  /**
+   * A CoinPay webhook about a checkout session. The body is only a hint: the
+   * session is read back from CoinPay with this site's key, so a forged call
+   * mints nothing. Resolves to the minted pass (for a site that emails it) or
+   * null. Mount it on a site's existing webhook route, or let the gateway
+   * answer POST /crawl/checkout/webhook itself.
+   */
+  async function checkoutPaid(bodyOrId, request) {
+    const id = typeof bodyOrId === 'string' ? bodyOrId : sessionIdFromWebhook(bodyOrId);
+    if (!id) return null;
+    const minted = await passForSession(id);
+    if (!minted.ok) return null;
+    await reportCheckout(id, minted, request);
+    return { token: minted.token, expiresAt: new Date(minted.expiresAt * 1000).toISOString(), days: minted.days, email: minted.state.email, accountId: minted.state.accountId, ref: `checkout:${id}` };
+  }
+
+  async function checkoutWebhook(request) {
+    if (request.method !== 'POST') return json({ ok: false, error: 'POST only' }, 405, { allow: 'POST' });
+    let body = {};
+    try {
+      body = await request.json();
+    } catch {}
+    const minted = await checkoutPaid(body, request);
+    return json({ ok: true, minted: Boolean(minted) }, 200);
+  }
+
+  /** The routes under the sales page. Null for anything else. */
+  async function checkoutRoute(request, path) {
+    if (path === checkoutPath) return startCheckout(request);
+    if (path === `${checkoutPath}/return`) return checkoutReturn(request);
+    if (path === `${checkoutPath}/webhook`) return checkoutWebhook(request);
+    return null;
   }
 
   /**
@@ -434,6 +785,10 @@ export function createGateway(options = {}) {
 
     const path = new URL(request.url).pathname;
     if (path === o.path) return sell(request);
+    if (path.startsWith(`${checkoutPath}`) && (path === checkoutPath || path.startsWith(`${checkoutPath}/`))) {
+      const answer = await checkoutRoute(request, path);
+      if (answer) return answer;
+    }
     if (o.exempt && o.exempt(request)) return null;
 
     /*
@@ -482,10 +837,11 @@ export function createGateway(options = {}) {
               error: `${path} is read in a browser (it sets a cookie with one line of script) or with a pass. Read ${howUrl} for how.`,
             }),
             402,
+            required(1),
           );
         }
         const token = await challengeToken(secret, ip);
-        return html(challengePage({ token, cookie: o.challenge.cookie, buyUrl }), 402);
+        return html(challengePage({ token, cookie: o.challenge.cookie, buyUrl }), 402, required(1));
       }
     }
 
@@ -558,10 +914,31 @@ export function createGateway(options = {}) {
         ...extra,
       }),
     /** The sales page as HTML, for a site that mounts it on a route of its own. */
-    page: () => o.page(pageCtx()),
+    page: () => {
+      const ctx = pageCtx();
+      if (cpCheckout && cpCheckout.known()) ctx.checkout = { action: checkoutPath, from: o.path, days: 1 };
+      return o.page(ctx);
+    },
+    /** The PAYMENT-REQUIRED header value for `days`, for a site that answers its own 402. */
+    paymentRequired: (days = 1, error) => required(days, error)['payment-required'] ?? null,
+    /** The sale context (property, page, UA, address hash) a request would be recorded with. */
+    saleContext,
+    /** Whether the checkout button shows: CoinPay serves checkout sessions and a key is set. */
+    checkoutAvailable: async () => Boolean(cpCheckout && (await cpCheckout.available())),
+    /** A CoinPay webhook handler (Fetch Request -> Response) that mints a paid session's pass. */
+    checkoutWebhook,
+    /** Mint the pass for a paid checkout session, from a webhook body or a session id. */
+    checkoutPaid,
   };
 }
 
+const esc = (s) =>
+  String(s ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+
 /** Whether the caller would rather read a page than a JSON offer. */
 export const wantsHtml = (accept = '') => String(accept ?? '').toLowerCase().includes('text/html');
 
@@ -649,6 +1026,12 @@ function normalise(options) {
     page: options.page ?? renderPage,
     contact: options.contact ?? '',
     onSale: options.onSale ?? null,
+    property: typeof options.property === 'function' || typeof options.property === 'string' ? options.property : null,
+    ipSalt: options.ipSalt ?? '',
+    checkout: options.checkout === false ? null : { ...(options.checkout ?? {}) },
+    passCookie: String(options.passCookie ?? 'crawl_pass'),
+    renderNotice: options.renderNotice ?? renderNotice,
+    renderPassPage: options.renderPassPage ?? renderPassPage,
     freeQuota: normaliseQuota(options.freeQuota),
     benefits: Array.isArray(options.benefits) ? options.benefits : null,
     powerKeys: options.powerKeys === false ? null : (options.powerKeys ?? PROFULLSTACK_KEYS),

package/src/page.js

@@ -3,7 +3,8 @@
  *
  * Plain HTML with no script, because the reader is a program that renders
  * nothing, or a person who was sent the link by one. Every number on it comes
- * from the gateway's options; nothing is typed in twice.
+ * from the gateway's options; nothing is typed in twice. The one form on it,
+ * the checkout button, is a plain POST and works with scripts off.
  */
 
 const esc = (s) =>
@@ -24,6 +25,12 @@ pre{background:var(--code);border:1px solid var(--line);border-radius:6px;paddin
 code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:.92em}
 ol,ul{padding-left:1.3rem}li{margin:.3rem 0}
 .price{font-size:2.2rem;font-weight:700;color:var(--acc);margin:.25rem 0}
+.buy{border:1px solid var(--line);border-radius:8px;padding:1rem 1.1rem;margin:1.25rem 0}
+.buy h2{margin-top:0}.buy form{display:flex;flex-wrap:wrap;gap:.5rem;align-items:center;margin:.6rem 0 .2rem}
+.buy input{font:inherit;padding:.5rem .6rem;border:1px solid var(--line);border-radius:6px;background:var(--bg);color:var(--fg);min-width:0}
+.buy input[type=email]{flex:1 1 14rem}.buy input[type=number]{width:5rem}
+.buy button{font:inherit;font-weight:600;padding:.55rem 1rem;border:0;border-radius:6px;background:var(--acc);color:#fff;cursor:pointer}
+.token{word-break:break-all}
 table{border-collapse:collapse;margin:.5rem 0;font-size:.95rem}td,th{border-bottom:1px solid var(--line);padding:.35rem .6rem;text-align:left}
 footer{margin-top:3rem;color:var(--mut);font-size:.85rem}
 `;
@@ -61,6 +68,7 @@ export function renderPage(ctx) {
     quota = null,
     benefits = null,
     powerKey = null,
+    checkout = null,
   } = ctx;
 
   /*
@@ -112,6 +120,26 @@ export function renderPage(ctx) {
             : `${minutes} minutes`;
   const networks = (offer?.accepts ?? []).map((a) => a.network).join(', ');
 
+  /*
+   * The button for people. Shown only when CoinPay serves hosted checkout, so
+   * a site never offers a payment it cannot take.
+   */
+  const buyBox = checkout
+    ? `<section class="buy">
+<h2>Buy a day pass</h2>
+<p>Pay ${esc(price)} a day with any coin CoinPay takes or with PayPal. The pass appears on the next page and works with any HTTP client.</p>
+<form method="post" action="${esc(checkout.action)}">
+<input type="hidden" name="from" value="${esc(checkout.from ?? '')}">
+<label class="mut" for="pass-email">Email for the receipt</label>
+<input id="pass-email" type="email" name="email" required autocomplete="email" placeholder="you@example.com">
+<label class="mut" for="pass-days">Days</label>
+<input id="pass-days" type="number" name="days" min="1" max="${esc(String(maxDays))}" value="${esc(String(checkout.days ?? days ?? 1))}">
+<button type="submit">Buy a day pass</button>
+</form>
+<p class="mut">Checkout is hosted by CoinPay. Up to ${esc(String(maxDays))} days at once.</p>
+</section>`
+    : '';
+
   return `<!doctype html>
 <html lang="en">
 <head>
@@ -137,6 +165,7 @@ ${
     ? ''
     : '<p><strong>Payments are not switched on here yet.</strong> The offer below is empty until the operator configures a payout address, so for now this crawler is simply refused.</p>'
 }
+${enabled ? buyBox : ''}
 
 ${unlocks}
 ${powerKeyNote}
@@ -144,9 +173,9 @@ ${arithmetic}
 
 <h2>How it works</h2>
 <ol>
-  <li>Any page you fetch answers <code>402 Payment Required</code>. This page, fetched with <code>Accept: application/json</code>, returns the x402 offer: USDC, <code>exact</code> scheme, on ${esc(networks || 'Base, Polygon or Ethereum')}.</li>
-  <li>Sign the payment and retry with the proof in an <code>X-PAYMENT</code> header. The response is a JSON receipt carrying a pass.</li>
-  <li>Send the pass in <code>${esc(header)}</code> on every request until it expires — ${esc(window)} per day paid, so a proof for three times the price buys three. When it expires, buy another. The sale is the pass, not the page: fetch the page again with the pass.</li>
+  <li>Any page you fetch answers <code>402 Payment Required</code> with the x402 offer in a <code>PAYMENT-REQUIRED</code> header (base64 JSON). This page, fetched with <code>Accept: application/json</code>, also returns it as the body: USDC, <code>exact</code> scheme, on ${esc(networks || 'Base, Polygon or Ethereum')}.</li>
+  <li>Sign the payment and retry with the proof in a <code>PAYMENT-SIGNATURE</code> (or <code>X-PAYMENT</code>) header. The response is a JSON receipt carrying a pass, with the settlement in <code>PAYMENT-RESPONSE</code>.</li>
+  <li>Send the pass in <code>${esc(header)}</code> (or <code>Authorization: Bearer</code>) on every request until it expires: ${esc(window)} per day paid, so a proof for three times the price buys three. When it expires, buy another. The sale is the pass, not the page: fetch the page again with the pass.</li>
 </ol>
 
 <h2>Pay with the CoinPay CLI</h2>
@@ -187,3 +216,69 @@ curl -sS -H "X-PAYMENT: &lt;base64 proof&gt;" ${esc(buyUrl)}
 </html>
 `;
 }
+
+const shell = (siteName, title, inner) => `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="robots" content="noindex">
+<title>${esc(title)} · ${esc(siteName)}</title>
+<style>${CSS}</style>
+</head>
+<body>
+<main>
+${inner}
+<footer>Served by @profullstack/x402-gateway.</footer>
+</main>
+</body>
+</html>
+`;
+
+/**
+ * A short status page for the checkout routes: waiting, closed, refused.
+ * `body` is HTML the gateway wrote; nothing in it comes from the request.
+ *
+ * @param {{siteName: string, siteUrl: string, buyUrl: string, title: string, body: string}} ctx
+ */
+export function renderNotice({ siteName, title, body }) {
+  return shell(siteName, title, `<h1>${esc(title)}</h1>\n<p>${body}</p>`);
+}
+
+/**
+ * The page a buyer lands on after paying at CoinPay: the pass, and the three
+ * ways to send it.
+ *
+ * @param {object} ctx
+ * @param {string} ctx.siteName
+ * @param {string} ctx.siteUrl
+ * @param {string} ctx.buyUrl
+ * @param {string} ctx.token
+ * @param {string} ctx.expiresAt   ISO time
+ * @param {number} ctx.days
+ * @param {string} ctx.header      request header the pass goes in
+ * @param {string} ctx.cookie      cookie the pass is also read from
+ * @param {string|null} [ctx.email]
+ */
+export function renderPassPage({ siteName, siteUrl, token, expiresAt, days, header, cookie, email }) {
+  const term = days === 1 ? 'one day' : `${days} days`;
+  return shell(
+    siteName,
+    'Your pass',
+    `<h1>Paid. Here is your pass.</h1>
+<p class="mut">Good for ${esc(term)} on <a href="${esc(siteUrl)}">${esc(siteName)}</a>, until <strong>${esc(expiresAt)}</strong>.${email ? ` The receipt went to ${esc(email)}.` : ''} Copy it now: this page is the only place it is shown, and the pass is all a crawler needs.</p>
+<pre class="token"><code>${esc(token)}</code></pre>
+
+<h2>How to use it</h2>
+<p>Send it on every request, in whichever of these your client supports:</p>
+<pre><code># a header
+curl -H "${esc(header)}: ${esc(token)}" ${esc(siteUrl)}/
+
+# a bearer token
+curl -H "Authorization: Bearer ${esc(token)}" ${esc(siteUrl)}/
+
+# a cookie (this browser already has it)
+curl --cookie "${esc(cookie)}=${esc(token)}" ${esc(siteUrl)}/</code></pre>
+<p class="mut">When it runs out, buy another at the same page. Every Profullstack site sells its own pass; a Power Key opens them all.</p>`,
+  );
+}

package/src/x402.js

@@ -1,11 +1,17 @@
 /**
- * x402 v2, in CoinPayPortal's dialect.
+ * x402 v2, in CoinPayPortal's dialect, plus the spec's transport headers.
  *
  * Checked against @profullstack/coinpay/x402-v2 rather than remembered: the 402
  * body is JSON `{ x402Version: 2, accepts: [...] }`, the proof arrives as base64
- * JSON in an `X-PAYMENT` request header, and CoinPay's /api/x402/verify then
- * /api/x402/settle do the cryptography and the on-chain transfer (EIP-3009,
- * with CoinPay's relayer paying the gas, so the buyer needs no ETH).
+ * JSON, and CoinPay's /api/x402/verify then /api/x402/settle do the
+ * cryptography and the on-chain transfer (EIP-3009, with CoinPay's relayer
+ * paying the gas, so the buyer needs no ETH).
+ *
+ * The x402 v2 transport spec moves all three messages into headers:
+ * `PAYMENT-REQUIRED` (the offer, base64 JSON) on the 402, `PAYMENT-SIGNATURE`
+ * (the proof) on the retry, and `PAYMENT-RESPONSE` (the settlement) on the
+ * 200. The gateway speaks both: the body and `X-PAYMENT` stay for the clients
+ * that already pay this way, and the headers are there for spec-strict ones.
  *
  * Reimplemented here in a few dozen lines because the SDK also carries the
  * CLI's interactive-prompt dependency, which a web server has no business
@@ -22,6 +28,13 @@
  *
  * Base first. Merchant order is the payer's preference order, and Base is where
  * the relayer's gas is cheapest.
+ *
+ * Why not more: CoinPay's v2 settle broadcasts `transferWithAuthorization`
+ * only on chains its relayer has an RPC and a funded wallet for, which are
+ * exactly 1, 137 and 8453, and USDC is the only EIP-3009 dollar token on them
+ * (USDT has no EIP-3009). Advertising anything else would quote a payment
+ * that verifies and then never settles. Buyers who want another coin, or
+ * PayPal, use the hosted checkout on the sales page instead.
  */
 export const METHODS = [
   {
@@ -88,8 +101,16 @@ function fromBase64(s) {
   return new TextDecoder().decode(bytes);
 }
 
-/** The proof out of an X-PAYMENT header. Null if it is not base64 JSON. */
-export function decodePayment(header) {
+/** utf8 JSON -> base64, without Buffer, for the PAYMENT-* headers. */
+export function encodeHeader(value) {
+  const bytes = new TextEncoder().encode(JSON.stringify(value));
+  let bin = '';
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin);
+}
+
+/** A PAYMENT-* header back into an object. Null if it is not base64 JSON. */
+export function decodeHeader(header) {
   if (!header) return null;
   try {
     const parsed = JSON.parse(fromBase64(header));
@@ -99,6 +120,65 @@ export function decodePayment(header) {
   }
 }
 
+/**
+ * The proof out of a PAYMENT-SIGNATURE or X-PAYMENT header. Null if it is not
+ * base64 JSON.
+ *
+ * Two shapes arrive. CoinPay's payer puts `scheme` and `network` at the top
+ * level; a spec v2 client nests them in `accepted`, the requirement it chose.
+ * Both carry the same `payload`, so the spec shape is lifted into CoinPay's,
+ * which is what CoinPay's verify and settle read.
+ */
+export function decodePayment(header) {
+  const parsed = decodeHeader(header);
+  if (!parsed) return null;
+  const chosen = parsed.accepted && typeof parsed.accepted === 'object' ? parsed.accepted : null;
+  if (chosen) {
+    if (!parsed.network && chosen.network) parsed.network = chosen.network;
+    if (!parsed.scheme && chosen.scheme) parsed.scheme = chosen.scheme;
+    if (parsed.x402Version === undefined) parsed.x402Version = 2;
+  }
+  return parsed;
+}
+
+/**
+ * The PAYMENT-REQUIRED header for an offer: the spec's PaymentRequired object,
+ * base64 JSON. The resource moves to the top level, as the spec has it, and
+ * each requirement keeps only the spec's own fields, so a strict schema has
+ * nothing to choke on.
+ */
+export function paymentRequiredHeader(offer, { url, description, error } = {}) {
+  const first = offer?.accepts?.[0];
+  return encodeHeader({
+    x402Version: 2,
+    ...(error ? { error: String(error) } : {}),
+    resource: {
+      url: url ?? first?.resource ?? '',
+      description: description ?? first?.description ?? '',
+      mimeType: first?.mimeType ?? 'application/json',
+    },
+    accepts: (offer?.accepts ?? []).map((a) => ({
+      scheme: a.scheme,
+      network: a.network,
+      amount: a.amount,
+      asset: a.asset,
+      payTo: a.payTo,
+      maxTimeoutSeconds: a.maxTimeoutSeconds,
+      extra: a.extra,
+    })),
+  });
+}
+
+/** The PAYMENT-RESPONSE header for a settled payment: the spec's SettlementResponse. */
+export function paymentResponseHeader({ transaction, network, payer }) {
+  return encodeHeader({
+    success: true,
+    transaction: transaction ?? '',
+    network: network ?? '',
+    ...(payer ? { payer } : {}),
+  });
+}
+
 /**
  * What CoinPay must hold the proof to.
  *
@@ -132,7 +212,7 @@ export const validBeforeOf = (payment) => {
  * gateway answers that with a pass rather than a second charge, bounded by the
  * proof's own validity window so the same header cannot buy hour after hour.
  */
-export async function verifyAndSettle(payment, expected, { apiKey, baseUrl, fetch: f = globalThis.fetch }) {
+export async function verifyAndSettle(payment, expected, { apiKey, baseUrl, fetch: f = globalThis.fetch, metadata = null }) {
   const call = async (path, body) => {
     const res = await f(`${baseUrl}${path}`, {
       method: 'POST',
@@ -153,12 +233,20 @@ export async function verifyAndSettle(payment, expected, { apiKey, baseUrl, fetc
     const reason = String(v.json?.error ?? v.json?.reason ?? `verify failed (${v.status})`);
     return { ok: false, reason, replay: /already used|replay/i.test(reason) };
   }
-  const s = await call('/api/x402/settle', { payment });
+  const payer = v.json.payment?.from ?? null;
+  /*
+   * Who paid and where, for CoinPay's ledger: the property, the page, the
+   * payer, the user agent and a hash of the address. CoinPay keeps it on the
+   * x402_payments row (and ignores it where it does not), so a sale can be
+   * traced to the site and page it bought rather than only to the business.
+   */
+  const settleBody = metadata ? { payment, metadata: { ...metadata, ...(payer ? { payer } : {}) } } : { payment };
+  const s = await call('/api/x402/settle', settleBody);
   if (!s.json?.settled) {
     const reason = String(s.json?.error ?? `settle failed (${s.status})`);
     return { ok: false, reason, replay: /already settled|already being settled/i.test(reason) };
   }
-  return { ok: true, payer: v.json.payment?.from ?? null, ref: s.json.txHash ?? nonceOf(payment) };
+  return { ok: true, payer, ref: s.json.txHash ?? nonceOf(payment), txHash: s.json.txHash ?? null, network: s.json.network ?? payment?.network ?? null };
 }
 
 /** Whether the proof has already been paid, when a settle is asked about twice. */