@profullstack/x402-gateway 0.10.2 → 0.12.0

package/README.md

@@ -95,14 +95,18 @@ export const GET = robotsRoute(gateway, { disallow: ['/login', '/api/'] });
 | `aiIndex` | none | extra agents to charge and refuse in robots.txt. Since 0.10 the AI answer-engine indexers (`AI_INDEX_AGENTS`: meta-webindexer, YouBot, ExaSearchBot, AionBot) are welcome retrieval crawlers; pass `aiIndex: AI_INDEX_AGENTS` to charge them anyway |
 | `verifiedRetrieval` | `VERIFIED_RETRIEVAL` | retrieval crawlers believed only from their operator's published addresses (OAI-SearchBot, ChatGPT-User, PerplexityBot, Perplexity-User); from elsewhere they are metered. Other retrieval and AI chat fetchers (Claude-User, Claude-SearchBot, Meta-ExternalFetcher, DuckAssistBot, MistralAI-User, the AI indexers) publish no addresses and are believed by name |
 | `chargeImpostors` | `true` | a request wearing a `welcome` crawler's name (Googlebot, bingbot, Applebot, DuckDuckBot, Cloudflare-*) from an address outside that operator's published list is charged. Never judged without a readable address |
-| `challenge` | off | `{ paths: ['/i/'], cookie?: 'pf_js', when?: (request, url) => boolean }`: every GET to these paths (that `when` accepts, if given) must run a one-line script (sets a per-address, per-day HMAC cookie and reloads) or gets a 402. Welcome crawlers (address-verified search crawlers, retrieval crawlers, AI chat fetchers) skip it; a client that did not ask for HTML gets the JSON offer instead of the script; sessions and passes never see it. For residential swarms that wear a current browser string and never run the page |
+| `challenge` | off | `{ paths: ['/i/'], cookie?: 'pf_js', work?: 0, when?: (request, url) => boolean }`: every GET to these paths (that `when` accepts, if given) must run a one-line script (sets a per-address, per-day HMAC cookie and reloads) or gets a 402. Welcome crawlers (address-verified search crawlers, retrieval crawlers, AI chat fetchers) skip it; a client that did not ask for HTML gets the JSON offer instead of the script; sessions and passes never see it. For residential swarms that wear a current browser string and never run the page. Set `work` (bits; `true` = 16, max 24) to make the script also solve a SHA-256 proof of work before it sets the cookie (`<token>.<nonce>`): ~250 ms at 16 bits on a desktop, once per address per day, but per page for a swarm that drives real headless Chrome and rotates its address every page. `navigator.webdriver` browsers are not given the cookie. |
 | `chargeStaleBrowsers` | `true` | charge a desktop Chrome/Edge/Firefox string about two years behind its auto-updates. Scraper rotation pools copy old strings; people's browsers update themselves. Phones, Firefox ESRs and the last version an old OS can run are never judged |
 | `welcome` | `WELCOME_CRAWLERS` | Googlebot, bingbot and Applebot read unmetered when their address is in the operator's published range. A copied string from anywhere else is metered like everyone; `false` turns this off |
 | `training`, `retrieval` | the lists in `./agents` | |
 | `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 {
@@ -78,7 +105,7 @@ export interface GatewayOptions {
   chargeImpostors?: boolean;
   /** Require a one-line script (cookie + reload) on these paths before serving them. Off by default. */
   /** Only GETs to `paths` that `when` accepts (default: all of them), e.g. `(req, url) => url.search.length > 1` for faceted URLs. */
-  challenge?: { paths: string[]; cookie?: string; when?: (request: Request, url: URL) => boolean } | false;
+  challenge?: { paths: string[]; cookie?: string; /** Proof-of-work bits the script must solve; true = 16. Default 0 (cookie + reload only). */ work?: number | boolean; when?: (request: Request, url: URL) => boolean } | false;
   /** SEO resellers: charged, and refused in robots.txt. Default SCRAPER_AGENTS. */
   scrapers?: string[];
   /** Headless browsers that name themselves: charged. Default HEADLESS_AGENTS. */
@@ -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;
@@ -226,8 +276,10 @@ export const SCRAPER_AGENTS: string[];
 export const HEADLESS_AGENTS: string[];
 export const AI_INDEX_AGENTS: string[];
 export function challengeToken(secret: string, ip: string, day?: number): Promise<string>;
-export function passedChallenge(request: Request, options: { secret: string; cookie: string; ip: string; now?: number }): Promise<boolean>;
-export function challengePage(options: { token: string; cookie: string; buyUrl: string }): string;
+export function passedChallenge(request: Request, options: { secret: string; cookie: string; ip: string; work?: number; now?: number }): Promise<boolean>;
+export function challengePage(options: { token: string; cookie: string; buyUrl: string; work?: number }): string;
+export function solves(seed: string, nonce: string | undefined, work: number): Promise<boolean>;
+export function leadingZeros(bytes: Uint8Array, bits: number): boolean;
 export function cookieValue(request: Request, name: string): string | null;
 export interface WelcomeCrawler {
   token: string;
@@ -261,6 +313,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 +328,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.12.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/challenge.js

@@ -14,6 +14,15 @@
  * address. The page that asks is a 402 carrying a link to the sales page, so a
  * scraper that cannot run scripts learns what a pass costs, which is the same
  * answer every other refused crawler gets.
+ *
+ * That was not enough. On 2026-10-21 the slice of the swarm that drives a real
+ * Chrome ran the script and walked in: 402, then the same address in the same
+ * second, then a 200, then never again. It rotates its address on every page,
+ * so "once per address per day" is once per page and the script cost it one
+ * request. With `work` set the script must also find a nonce whose SHA-256
+ * starts with that many zero bits. A person pays about a second once a day; a
+ * swarm that changes address every page pays it on every page. The server
+ * checks the answer with one hash and keeps nothing.
  */
 
 const enc = new TextEncoder();
@@ -42,19 +51,48 @@ export function cookieValue(request, name) {
   return null;
 }
 
-/** Whether the request carries today's or yesterday's token for its address. */
-export async function passedChallenge(request, { secret, cookie, ip, now = Date.now() }) {
+/** Whether a SHA-256 digest starts with `bits` zero bits. */
+export function leadingZeros(bytes, bits) {
+  let i = 0;
+  for (; bits >= 8; bits -= 8) if (bytes[i++]) return false;
+  return !bits || !(bytes[i] >> (8 - bits));
+}
+
+/** Whether `nonce` answers the proof of work for `seed`. */
+export async function solves(seed, nonce, work) {
+  if (!work) return true;
+  if (!/^\d{1,12}$/.test(nonce ?? '')) return false;
+  const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', enc.encode(`${seed}.${nonce}`)));
+  return leadingZeros(digest, work);
+}
+
+/**
+ * Whether the request carries today's or yesterday's token for its address,
+ * and, with `work`, a nonce that answers it (cookie `<token>.<nonce>`).
+ */
+export async function passedChallenge(request, { secret, cookie, ip, work = 0, now = Date.now() }) {
   const got = cookieValue(request, cookie);
   if (!got) return false;
+  const [seed, nonce] = got.split('.');
   const day = Math.floor(now / DAY);
-  for (const d of [day, day - 1]) if (got === (await challengeToken(secret, ip, d))) return true;
+  for (const d of [day, day - 1]) if (seed === (await challengeToken(secret, ip, d))) return solves(seed, nonce, work);
   return false;
 }
 
+/** The script that finds the nonce, 256 digests at a time, then sets the cookie and reloads. */
+const solver = (token, cookie, work) => `(async()=>{const s=${JSON.stringify(token)},w=${work},e=new TextEncoder();
+if(navigator.webdriver){document.body.insertAdjacentHTML('beforeend','<p>Automated browsers need a pass.</p>');return}
+const ok=b=>{let n=w,i=0;for(;n>=8;n-=8)if(b[i++])return 0;return!n||!(b[i]>>(8-n))};
+for(let n=0;;n+=256){const h=await Promise.all(Array.from({length:256},(_,k)=>crypto.subtle.digest('SHA-256',e.encode(s+'.'+(n+k)))));
+for(let k=0;k<256;k++)if(ok(new Uint8Array(h[k]))){document.cookie=${JSON.stringify(`${cookie}=`)}+s+'.'+(n+k)+${JSON.stringify('; Max-Age=172800; Path=/; SameSite=Lax; Secure')};location.reload();return}}})();`;
+
 /** The page that asks. Tiny on purpose: answering it must cost us nothing. */
-export function challengePage({ token, cookie, buyUrl }) {
+export function challengePage({ token, cookie, buyUrl, work = 0 }) {
+  const script = work
+    ? solver(token, cookie, work)
+    : `document.cookie=${JSON.stringify(`${cookie}=${token}; Max-Age=172800; Path=/; SameSite=Lax; Secure`)};location.reload();`;
   return `<!doctype html><html><head><meta charset="utf-8"><meta name="robots" content="noindex"><title>One moment</title></head><body>
-<script>document.cookie=${JSON.stringify(`${cookie}=${token}; Max-Age=172800; Path=/; SameSite=Lax; Secure`)};location.reload();</script>
+${work ? '<p>Checking your browser. This takes about a second, once a day.</p>\n' : ''}<script>${script}</script>
 <noscript><p>This page needs JavaScript. Automated access is sold by the day: <a href="${buyUrl}">${buyUrl}</a></p></noscript>
 </body></html>`;
 }

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;
+}