openzoo 0.49.16 → 0.49.17

package/lib/x402.js

@@ -1,8 +1,10 @@
+import crypto from 'node:crypto';
 import {
   ComputeBudgetProgram,
   Connection,
   PublicKey,
   Transaction,
+  TransactionInstruction,
 } from '@solana/web3.js';
 import {
   TOKEN_2022_PROGRAM_ID,
@@ -12,7 +14,7 @@ import {
 } from '@solana/spl-token';
 
 /**
- * x402 protocol client for openzoo.fun (x402Version 1, Solana "exact" scheme).
+ * x402 protocol client (x402Version 1 and 2, "exact" scheme).
  *
  * Captured live 402 shape (test/fixtures/live-402.json):
  *   { x402Version: 1,
@@ -22,33 +24,101 @@ import {
  *                  payTo: "<wallet>", resource, description, maxTimeoutSeconds,
  *                  extra: { facilitator, feePayer, symbol, billedUsd, tokenUsd,
  *                           pricedAt, pricing: "markup"|"counterfactual",
- *                           billedUsd, directUsd?, savedUsd?, savesVsDirect?,
- *                           acquire?: { method: "spl-token-wrap", steps: WRAP_ACQUIRE_STEPS } } } ],
- *     error: "payment required",
- *     help: "Wrap ix has 9 accounts. Program CPIs the deposit — do not send a separate TransferChecked. 0x6a = NotEnoughAccounts (old 5-account wrap is dead)." }
+ *                           billedUsd, directUsd?, savedUsd?, savesVsDirect? } } ],
+ *     error: "payment required" }
  *
- * Payment of the quoted (already-wrapped) mint: ONE Token-2022 TransferChecked
- * (payer ATA -> payTo ATA) for exactly maxAmountRequired, feePayer =
- * extra.feePayer (the gateway pays SOL fees), partial-signed by the payer,
- * serialized requireAllSignatures=false, base64.
- * Funding a short wrapped balance is a *separate* 9-account Wrap prepended as
- * preInstructions (lib/wrap.js WRAP_ACQUIRE_STEPS). Do not follow Wrap with a
- * deposit TransferChecked — the program pulls the underlying itself.
- * X-PAYMENT header = base64 of
- *   {"x402Version":1,"scheme":"exact","network":"<network>","payload":{"transaction":"<b64 tx>"}}
+ * `asset` is the RAW NATIVE MINT — canonical Circle USDC, or the project token
+ * as its own mint. It was briefly a NAV-wrapped Token-2022 twin the payer had
+ * to mint first, and the shim converted at payment time; the gateway dropped
+ * that because a stock x402 client will not run an approve+deposit into an
+ * unaudited vault to buy one API call. Nothing here converts anything: the
+ * wallet either holds the quoted mint or the row is unaffordable.
+ *
+ * Payment is a fixed four-instruction message — see buildPayment, where the
+ * order is the protocol. feePayer = extra.feePayer (the gateway pays SOL fees),
+ * partial-signed by the payer, serialized requireAllSignatures=false, base64.
+ *
+ * Both PAYMENT-SIGNATURE and X-PAYMENT carry base64 of paymentEnvelope().
  *
  * NOTE: decimals are NOT in the 402 payload and the site's pasted prompt
  * hardcoding "decimals = 6" is a known bug. We always read decimals from the
  * mint account on-chain (see getMintInfo) — never hardcode.
  */
 
+/**
+ * BOTH VERSIONS, OR A v2 CHALLENGE FAILS CLOSED.
+ *
+ * Pinning to `=== 1` threw before a single field was read, so an upstream that
+ * has moved to v2 — every CDP-facilitated one has — was indistinguishable from
+ * a malformed body. The version selects the ENVELOPE shape (see
+ * paymentEnvelope); it is not an admission test.
+ */
 export function parse402(body) {
-  if (!body || body.x402Version !== 1 || !Array.isArray(body.accepts) || body.accepts.length === 0) {
-    throw new Error('not an x402 v1 payment-required body');
+  const v = Number(body?.x402Version);
+  if (!body || (v !== 1 && v !== 2) || !Array.isArray(body.accepts) || body.accepts.length === 0) {
+    throw new Error('not an x402 v1/v2 payment-required body');
   }
   return body;
 }
 
+/**
+ * The network the VERIFIER enforces, which is not always the one accepts[]
+ * advertised.
+ *
+ * MEASURED 2026-08-25: surplusintelligence advertises `eip155:8453` and then
+ * rejects that exact string with `invalid_exact_evm_network_mismatch`, wanting
+ * "base". The payment had already LANDED ON CHAIN when the claim was refused —
+ * $0.004172 gone. When the challenge carries a top-level `x402` summary whose
+ * `.network` disagrees with the row, the summary is what gets enforced.
+ */
+export function verifyNetworkFor(body, accept) {
+  const advertised = String(accept?.network || '');
+  const summary = body?.x402;
+  const enforced = summary && typeof summary === 'object' ? String(summary.network || '') : '';
+  return enforced && enforced !== advertised ? enforced : advertised;
+}
+
+/**
+ * The payment envelope both rails send, base64 of this JSON.
+ *
+ * `resource` and `accepted` are the two fields a CDP facilitator validates the
+ * payload's SHAPE against: without them it answers "'paymentPayload' is
+ * invalid: must match one of [x402V2Pay…]" and never looks at the money.
+ * `accepted` is the accepts[] row VERBATIM — providers compare fields we do not
+ * model, so a normalised reconstruction is not the same document.
+ *
+ * The version is echoed rather than pinned to 2: the openzoo gateway still
+ * issues v1 challenges and a v1 verifier is entitled to reject a v2 envelope.
+ * The two extra fields are inert to a v1 verifier, so echoing is safe in the
+ * direction that costs money.
+ */
+export function paymentEnvelope(body, accept, payload) {
+  return {
+    x402Version: Number(body?.x402Version) === 1 ? 1 : 2,
+    resource: body?.resource,          // undefined drops out of JSON.stringify
+    accepted: accept,
+    scheme: accept?.scheme,
+    network: verifyNetworkFor(body, accept),
+    payload,
+  };
+}
+
+/** base64 of the envelope — the value of BOTH payment headers. */
+export function encodeEnvelope(envelope) {
+  return Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64');
+}
+
+/**
+ * BOTH HEADER NAMES, ALWAYS.
+ *
+ * PAYMENT-SIGNATURE is what the spec names; X-PAYMENT is what a large share of
+ * live implementations actually read. Sending one and guessing wrong is a 402
+ * loop against a server that would have served us.
+ */
+export function paymentHeaders(header) {
+  return { 'PAYMENT-SIGNATURE': header, 'X-PAYMENT': header };
+}
+
 const EVM_NAME_CHAINS = { base: 8453, 'base-sepolia': 84532 };
 
 /** Which rail an accepts[] row settles on: 'solana' | 'base' | 'robinhood' | 'evm' | null. */
@@ -78,8 +148,8 @@ export function evmChainId(network) {
  * Default order: Solana first (preferring extra.symbol === preferredSymbol),
  * then Base, then other EVM chains. Robinhood Chain (eip155:4663) is last and
  * only when allowRH: all three rails have settled real payments (2026-08-14),
- * but RH stays opt-in for DEFAULT selection because its settlement asset has
- * no auto-conversion path here.
+ * but RH stays opt-in for DEFAULT selection because USDG is the one asset that
+ * settles there and far fewer wallets are holding it.
  */
 /**
  * ALL payable rows from a 402, best-first. The wallet pays with whatever it
@@ -117,7 +187,7 @@ export function orderAccepts(body, preferredSymbol, { allowRH = false, forceRail
   ];
   if (!out.length) {
     throw new Error(rows.some((a) => railOf(a) === 'robinhood')
-      ? 'only Robinhood Chain rails offered — set OPENZOO_ENABLE_RH=1 or OPENZOO_RAIL=robinhood to use them (the rail settles; you must hold its settlement asset, see https://x402.accrue.fund/start)'
+      ? 'only Robinhood Chain rails offered — set OPENZOO_ENABLE_RH=1 or OPENZOO_RAIL=robinhood to use them (the rail settles; the wallet must hold USDG on Robinhood Chain)'
       : 'no payable rail in 402 accepts[]');
   }
   return out;
@@ -142,11 +212,36 @@ export async function getMintInfo(connection, mintStr) {
   return out;
 }
 
+export const MEMO_PROGRAM_ID = new PublicKey('MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr');
+
 /**
- * Build the partially-signed payment transaction + X-PAYMENT header value.
- * Pure given its inputs (no network) so it can be unit-tested offline.
+ * THE INSTRUCTION LAYOUT IS THE PROTOCOL — specs/schemes/exact/scheme_exact_svm.md.
+ * A facilitator checks it before it looks at the money, and the transaction
+ * SIMULATES CLEAN either way, so the chain gives no hint that anything is wrong.
+ * Required, in this order, 3..6 instructions total:
+ *
+ *   1. ComputeBudget SetComputeUnitLimit
+ *   2. ComputeBudget SetComputeUnitPrice   (<= 5 lamports/CU)
+ *   3. SPL TransferChecked                 <- MUST be third
+ *   4. Memo                                <- MANDATORY, not optional
+ *
+ * Every line below was bought by getting it wrong on mainnet 2026-08-25:
+ *  - ONE instruction -> "instructions length mismatch: 1 < 3 or 1 > 6"
+ *  - no SetComputeUnitPrice -> the same length mismatch, one short
+ *  - TransferChecked at #4, pushed down by prepended ATA-create/wrap
+ *    preInstructions -> `no_transfer_instruction`. The position is checked, not
+ *    searched, which is why funding can no longer ride inside this transaction.
+ *  - no Memo -> rejected outright.
+ *
+ * UNIQUENESS MOVED. It used to live in a randomised compute-unit limit here,
+ * because everything else is a pure function of (amount, accounts, decimals,
+ * blockhash) and two callers inside one blockhash window built a
+ * BYTE-IDENTICAL transaction — same signature, so the facilitator reported the
+ * second as `settle {success:false, "Simulation failed ... Logs: []"}` (8 of
+ * them in one window under 10 workers). The spec now puts uniqueness in the
+ * memo, so the CU limit is a plain constant and the nonce is the memo body.
  */
-export function buildPayment({ accept, decimals, programId, recentBlockhash, keypair, preInstructions = [] }) {
+export function buildPayment({ accept, decimals, programId, recentBlockhash, keypair }) {
   const mint = new PublicKey(accept.asset);
   const payTo = new PublicKey(accept.payTo);
   const feePayer = new PublicKey(accept.extra.feePayer);
@@ -155,43 +250,39 @@ export function buildPayment({ accept, decimals, programId, recentBlockhash, key
   const source = getAssociatedTokenAddressSync(mint, keypair.publicKey, false, programId);
   const dest = getAssociatedTokenAddressSync(mint, payTo, true, programId);
 
-  const ix = createTransferCheckedInstruction(
-    source, mint, dest, keypair.publicKey, amount, decimals, [], programId,
-  );
-
   const tx = new Transaction({ feePayer, recentBlockhash });
-  // UNIQUENESS. Everything else here is a pure function of (amount, accounts,
-  // decimals, blockhash), so two calls quoting the same price inside one
-  // blockhash window build a BYTE-IDENTICAL transaction — same signature, so
-  // the second is a duplicate and the facilitator reports it as
-  // `settle {success:false, "Simulation failed ... Logs: []"}`. Concurrent
-  // callers hit this constantly (a 10-worker run produced 8 failed_settle in
-  // one window) and each failure costs a full retry, which is most of the
-  // per-call latency.
-  //
-  // A random compute-unit LIMIT makes each message distinct at no cost: unlike
-  // setComputeUnitPrice it adds no priority fee, and an over-estimate is free
-  // — it only caps execution. The range sits far above what a transferChecked
-  // plus any funding preInstructions actually consume.
-  tx.add(ComputeBudgetProgram.setComputeUnitLimit({
-    units: 300_000 + Math.floor(Math.random() * 200_000),
+  tx.add(ComputeBudgetProgram.setComputeUnitLimit({ units: 200_000 }));
+  tx.add(ComputeBudgetProgram.setComputeUnitPrice({ microLamports: 1 }));
+  tx.add(createTransferCheckedInstruction(
+    source, mint, dest, keypair.publicKey, amount, decimals, [], programId,
+  ));
+  // The seller's memo when they set one — some price it into the settlement —
+  // else a random 16-byte hex nonce, which is what makes two concurrent
+  // identical payments distinct messages.
+  tx.add(new TransactionInstruction({
+    keys: [],
+    programId: MEMO_PROGRAM_ID,
+    data: Buffer.from(accept.extra?.memo || crypto.randomBytes(16).toString('hex'), 'utf8'),
   }));
-  for (const pre of preInstructions) tx.add(pre); // internal funding plumbing, if any
-  tx.add(ix);
+  if (tx.instructions.length < 3 || tx.instructions.length > 6) {
+    throw new Error(`x402 svm payment has ${tx.instructions.length} instructions, outside the required 3..6`);
+  }
+  // THE FEE PAYER MUST NOT APPEAR IN ANY INSTRUCTION'S ACCOUNTS. It is the
+  // facilitator's gas signer; letting it in means their signature can be made
+  // to fund something for us (an ATA create, say), which the spec bans outright.
+  for (const [i, ix] of tx.instructions.entries()) {
+    if (ix.keys.some((k) => k.pubkey.equals(feePayer))) {
+      throw new Error(`instruction ${i} names the facilitator feePayer in its accounts — forbidden by scheme_exact_svm`);
+    }
+  }
+
   tx.partialSign(keypair); // owner signs; feePayer slot left empty for the facilitator
   const txBase64 = tx.serialize({ requireAllSignatures: false, verifySignatures: false }).toString('base64');
 
-  const envelope = {
-    x402Version: 1,
-    scheme: accept.scheme,
-    network: accept.network,
-    payload: { transaction: txBase64 },
-  };
-  const header = Buffer.from(JSON.stringify(envelope), 'utf8').toString('base64');
   const ownerSig = tx.signatures.find((s) => s.publicKey.equals(keypair.publicKey) && s.signature);
   return {
-    header,
     txBase64,
+    payload: { transaction: txBase64 },
     ownerSignature: ownerSig ? base58encode(ownerSig.signature) : null,
     amount,
     source,
@@ -199,11 +290,11 @@ export function buildPayment({ accept, decimals, programId, recentBlockhash, key
   };
 }
 
-/** Resolve chain state (decimals, blockhash) and build the header. */
-export async function buildPaymentOnline(connection, keypair, accept, { preInstructions = [] } = {}) {
+/** Resolve chain state (decimals, blockhash) and build the payment payload. */
+export async function buildPaymentOnline(connection, keypair, accept) {
   const { programId, decimals } = await getMintInfo(connection, accept.asset);
   const { blockhash } = await connection.getLatestBlockhash('confirmed');
-  return buildPayment({ accept, decimals, programId, recentBlockhash: blockhash, keypair, preInstructions });
+  return buildPayment({ accept, decimals, programId, recentBlockhash: blockhash, keypair });
 }
 
 /** Token balance of our ATA for a mint. Returns { raw: bigint, ui: number|null }. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openzoo",
-  "version": "0.49.16",
-  "description": "Local x402-paying proxy + MCP server for openzoo.fun — point any OpenAI-compatible harness (Cursor, Claude Code, aider, SDKs) at localhost and it pays per call from a local burner wallet. Solana and Base rails live; Robinhood experimental.",
+  "version": "0.49.17",
+  "description": "Local x402-paying proxy + MCP server for openzoo.fun \u2014 point any OpenAI-compatible harness (Cursor, Claude Code, aider, SDKs) at localhost and it pays per call from a local burner wallet. Solana and Base rails live; Robinhood experimental.",
   "license": "MIT",
   "type": "module",
   "bin": {

package/lib/evmwrap.js

@@ -1,163 +0,0 @@
-import { createPublicClient, createWalletClient, http, formatEther } from 'viem';
-import { privateKeyToAccount } from 'viem/accounts';
-import { evmChainId } from './x402.js';
-
-/**
- * EVM auto-acquire — the Robinhood Chain mirror of wrap.js.
- *
- * The 402's settlement asset on eip155:4663 is an X402Wrapper twin: an
- * ERC-4626-shaped vault + EIP-3009 over the plain token the user actually
- * holds (source + deploy record: /Users/stacc/x402-wrappers, e.g. ODDBALLER /
- * IOU / ROBINHOODS twins, and wUSDGx over USDG). Users hold the PLAIN token;
- * this module converts exactly enough at payment time — approve + deposit —
- * so the wrapper never appears in anything user-facing. Copy in every error
- * names only the unwrapped token.
- *
- * Unlike Solana (where the gateway's feePayer can sponsor the conversion
- * inside the payment tx), the approve+deposit here are the wallet's own
- * transactions: the wallet must hold a sliver of native RH ETH. When it does
- * not, the error says EXACTLY what to send and where.
- */
-
-const WRAPPER_ABI = [
-  { type: 'function', name: 'asset', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
-  { type: 'function', name: 'previewMint', stateMutability: 'view', inputs: [{ type: 'uint256' }], outputs: [{ type: 'uint256' }] },
-  { type: 'function', name: 'deposit', stateMutability: 'nonpayable', inputs: [{ type: 'uint256' }, { type: 'address' }], outputs: [{ type: 'uint256' }] },
-  { type: 'function', name: 'balanceOf', stateMutability: 'view', inputs: [{ type: 'address' }], outputs: [{ type: 'uint256' }] },
-];
-
-const ERC20_ABI = [
-  { type: 'function', name: 'balanceOf', stateMutability: 'view', inputs: [{ type: 'address' }], outputs: [{ type: 'uint256' }] },
-  { type: 'function', name: 'allowance', stateMutability: 'view', inputs: [{ type: 'address' }, { type: 'address' }], outputs: [{ type: 'uint256' }] },
-  { type: 'function', name: 'approve', stateMutability: 'nonpayable', inputs: [{ type: 'address' }, { type: 'uint256' }], outputs: [{ type: 'bool' }] },
-  { type: 'function', name: 'symbol', stateMutability: 'view', inputs: [], outputs: [{ type: 'string' }] },
-];
-
-/** Rough ceiling for approve + deposit on an Arbitrum-Orbit chain. */
-const ACQUIRE_GAS_UNITS = 400_000n;
-
-export class NeedsGasError extends Error {
-  constructor({ address, shortWei, symbol }) {
-    // round the ask up to a friendly margin so one top-up is enough
-    const ask = (shortWei * 3n) / 2n;
-    super(
-      `openzoo: converting your ${symbol} for this payment takes two small on-chain steps, `
-      + `and the wallet is short of gas. Send at least ${formatEther(ask)} ETH on Robinhood Chain `
-      + `(eip155:4663) to ${address}, then retry.`,
-    );
-    this.name = 'NeedsGasError';
-    this.address = address;
-    this.shortWei = shortWei;
-  }
-}
-
-export class UnderlyingShortError extends Error {
-  constructor({ symbol, haveRaw, needRaw, decimals, address }) {
-    const ui = (raw) => {
-      const d = BigInt(10) ** BigInt(decimals ?? 18);
-      return `${raw / d}.${(raw % d).toString().padStart(Number(decimals ?? 18), '0').slice(0, 4)}`;
-    };
-    super(
-      `openzoo wallet underfunded: this call needs ≈${ui(needRaw)} ${symbol} but the wallet `
-      + `holds ${ui(haveRaw)} ${symbol} (${address} on Robinhood Chain).`,
-    );
-    this.name = 'UnderlyingShortError';
-    this.symbol = symbol;
-    this.haveRaw = haveRaw;
-    this.needRaw = needRaw;
-  }
-}
-
-function chainFor(chainId, rpcUrl) {
-  return {
-    id: chainId,
-    name: `eip155:${chainId}`,
-    nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
-    rpcUrls: { default: { http: [rpcUrl] } },
-  };
-}
-
-/**
- * Ensure the wallet holds >= `need` raw units of the 402's settlement asset,
- * converting the plain underlying token via approve + deposit when necessary.
- *
- * Resolution order:
- *  - already funded -> { acquired: false }
- *  - not a wrapper (no asset() view) -> { acquired: false, wrapper: false } —
- *    the caller falls back to its plain underfunded message
- *  - wrapper, wallet holds enough underlying + gas -> converts, waits for
- *    receipts, returns { acquired: true, txs: [approveHash?, depositHash] }
- *  - short of underlying -> UnderlyingShortError (names the plain token only)
- *  - short of native gas -> NeedsGasError (says exactly what to send where)
- */
-export async function acquireWrappedIfNeeded({ rpcUrl, accept, evmPrivateKey, onStage }) {
-  const chainId = evmChainId(accept.network);
-  const account = privateKeyToAccount(evmPrivateKey);
-  const pc = createPublicClient({ transport: http(rpcUrl) });
-  const need = BigInt(accept.maxAmountRequired);
-
-  const bal = await pc.readContract({ address: accept.asset, abi: WRAPPER_ABI, functionName: 'balanceOf', args: [account.address] });
-  if (bal >= need) return { acquired: false, wrapper: null };
-
-  let underlying;
-  try {
-    underlying = await pc.readContract({ address: accept.asset, abi: WRAPPER_ABI, functionName: 'asset', args: [] });
-  } catch {
-    return { acquired: false, wrapper: false }; // plain token — nothing to convert from
-  }
-
-  const short = need - bal;
-  // previewMint(short): underlying needed so the vault mints >= short shares
-  // (entry fee + rounding included by the contract itself — never re-derived here).
-  const assetsNeeded = await pc.readContract({ address: accept.asset, abi: WRAPPER_ABI, functionName: 'previewMint', args: [short] });
-
-  const symbol = await pc
-    .readContract({ address: underlying, abi: ERC20_ABI, functionName: 'symbol', args: [] })
-    .catch(() => 'underlying token');
-  const uBal = await pc.readContract({ address: underlying, abi: ERC20_ABI, functionName: 'balanceOf', args: [account.address] });
-  if (uBal < assetsNeeded) {
-    throw new UnderlyingShortError({
-      symbol,
-      haveRaw: uBal,
-      needRaw: assetsNeeded,
-      decimals: accept.extra?.decimals ?? 18,
-      address: account.address,
-    });
-  }
-
-  // Gas preflight — these two txs are the wallet's own, unlike the sponsored
-  // Solana path. Fail with the exact shortfall before signing anything.
-  const [gasPrice, native] = await Promise.all([pc.getGasPrice(), pc.getBalance({ address: account.address })]);
-  const gasBudget = ACQUIRE_GAS_UNITS * gasPrice;
-  if (native < gasBudget) {
-    throw new NeedsGasError({ address: account.address, shortWei: gasBudget - native, symbol });
-  }
-
-  onStage?.('funding');
-  const chain = chainFor(chainId, rpcUrl);
-  const wc = createWalletClient({ account, chain, transport: http(rpcUrl) });
-  const txs = [];
-
-  const allowance = await pc.readContract({
-    address: underlying, abi: ERC20_ABI, functionName: 'allowance', args: [account.address, accept.asset],
-  });
-  if (allowance < assetsNeeded) {
-    const approveHash = await wc.writeContract({
-      address: underlying, abi: ERC20_ABI, functionName: 'approve', args: [accept.asset, assetsNeeded],
-    });
-    await pc.waitForTransactionReceipt({ hash: approveHash });
-    txs.push(approveHash);
-  }
-
-  const depositHash = await wc.writeContract({
-    address: accept.asset, abi: WRAPPER_ABI, functionName: 'deposit', args: [assetsNeeded, account.address],
-  });
-  const receipt = await pc.waitForTransactionReceipt({ hash: depositHash });
-  txs.push(depositHash);
-  if (receipt.status !== 'success') throw new Error(`openzoo: converting ${symbol} for payment failed on-chain (tx ${depositHash})`);
-
-  const after = await pc.readContract({ address: accept.asset, abi: WRAPPER_ABI, functionName: 'balanceOf', args: [account.address] });
-  if (after < need) throw new Error(`openzoo: conversion landed but the balance still cannot cover the quote — retry, or fund more ${symbol}`);
-  if (process.env.OPENZOO_DEBUG) console.error(`[openzoo debug] evm acquire txs ${txs.join(', ')}`);
-  return { acquired: true, txs };
-}

package/lib/subscription.js

@@ -1,207 +0,0 @@
-/**
- * Stripe subscription keys for the zoo API — the other pay lane next to
- * wallet/x402. The live billing API is zoo.openzoo.fun; this file does not
- * invent a second backend.
- *
- * After checkout the site lands on /billing/done?session=<cs_…> and polls
- * GET /api/billing/key?session=… until Stripe confirms. That response is how
- * a desktop client receives the key (no Stripe cookie on Electron). A user
- * who already subscribed can paste the same key, or that success URL.
- *
- * Use: Authorization: Bearer <key> against x402-tokens.fly.dev — no 402
- * signing. Wallet/x402 stays if no key is stored.
- */
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-
-export const BILLING_ORIGIN = 'https://zoo.openzoo.fun';
-export const SUBSCRIPTIONS_PAGE = 'https://zoo.openzoo.fun/subscriptions';
-
-export function subscriptionFile(home = os.homedir()) {
-  return process.env.OPENZOO_SUBSCRIPTION_PATH
-    || path.join(home, '.openzoo', 'subscription.json');
-}
-
-function titleCase(id) {
-  const s = String(id || '').trim();
-  if (!s) return '';
-  return s.charAt(0).toUpperCase() + s.slice(1);
-}
-
-function asKey(v) {
-  return String(v || '').trim();
-}
-
-/** Persist a subscription key (chmod 600). Never log the value. */
-export function saveSubscription(rec, file = subscriptionFile()) {
-  const key = asKey(rec?.key);
-  if (!key) return null;
-  const payload = {
-    key,
-    tier: rec.tier ? String(rec.tier) : null,
-    tierName: rec.tierName ? String(rec.tierName) : (rec.tier ? titleCase(rec.tier) : null),
-    sessionId: rec.sessionId ? String(rec.sessionId) : null,
-    savedAt: Date.now(),
-  };
-  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
-  const tmp = `${file}.tmp`;
-  fs.writeFileSync(tmp, JSON.stringify(payload), { mode: 0o600 });
-  fs.renameSync(tmp, file);
-  cached = { file, mtime: fs.statSync(file).mtimeMs, data: payload };
-  return payload;
-}
-
-export function clearSubscription(file = subscriptionFile()) {
-  try { fs.unlinkSync(file); } catch { /* already gone */ }
-  if (cached.file === file) cached = { file: '', mtime: 0, data: null };
-}
-
-let cached = { file: '', mtime: 0, data: null };
-
-export function loadSubscription(file = subscriptionFile()) {
-  const envKey = asKey(process.env.OPENZOO_SUBSCRIPTION_KEY);
-  if (envKey) {
-    return {
-      key: envKey,
-      tier: process.env.OPENZOO_SUBSCRIPTION_TIER || null,
-      tierName: process.env.OPENZOO_SUBSCRIPTION_TIER
-        ? titleCase(process.env.OPENZOO_SUBSCRIPTION_TIER)
-        : null,
-      sessionId: null,
-      source: 'env',
-    };
-  }
-  try {
-    const st = fs.statSync(file);
-    if (cached.file === file && cached.mtime === st.mtimeMs && cached.data) return cached.data;
-    const data = JSON.parse(fs.readFileSync(file, 'utf8'));
-    if (!asKey(data?.key)) {
-      cached = { file, mtime: st.mtimeMs, data: null };
-      return null;
-    }
-    const rec = {
-      key: asKey(data.key),
-      tier: data.tier || null,
-      tierName: data.tierName || (data.tier ? titleCase(data.tier) : null),
-      sessionId: data.sessionId || null,
-      source: 'file',
-    };
-    cached = { file, mtime: st.mtimeMs, data: rec };
-    return rec;
-  } catch {
-    return null;
-  }
-}
-
-/** Public HUD/wallet view — never includes the secret. */
-export function subscriptionPublicView(sub = loadSubscription()) {
-  if (!asKey(sub?.key)) return { active: false };
-  const name = String(sub.tierName || titleCase(sub.tier) || '').trim();
-  return {
-    active: true,
-    tier: sub.tier || null,
-    tierName: name || null,
-    label: name ? `${name} · no x402` : 'Subscription key · no x402',
-  };
-}
-
-/**
- * A paste is either the bearer key itself, or the site's success URL
- * (`/billing/done?session=cs_…`). session_id is accepted too — Stripe's
- * default query name — but the live page uses `session`.
- */
-export function parseSubscriptionPaste(text) {
-  const raw = String(text || '').trim();
-  if (!raw) return { error: 'empty' };
-  let session = '';
-  try {
-    if (/^https?:\/\//i.test(raw) || raw.includes('session=')) {
-      const url = new URL(raw, BILLING_ORIGIN);
-      session = url.searchParams.get('session') || url.searchParams.get('session_id') || '';
-    }
-  } catch { /* not a URL */ }
-  if (!session) {
-    const m = /(?:session_id|session)=([A-Za-z0-9_]+)/.exec(raw);
-    if (m) session = m[1];
-  }
-  if (session) return { session };
-  if (/^https?:\/\//i.test(raw)) return { error: 'no session in URL' };
-  if (raw.length < 8 || /\s/.test(raw)) return { error: 'not a key' };
-  return { key: raw };
-}
-
-export function applySubscriptionHeaders(headers = {}, sub = loadSubscription()) {
-  const key = asKey(sub?.key);
-  if (!key) return headers;
-  return { ...headers, authorization: `Bearer ${key}` };
-}
-
-export function stripAuthorization(headers = {}) {
-  const out = { ...headers };
-  delete out.authorization;
-  delete out.Authorization;
-  return out;
-}
-
-async function billingJson(url, init) {
-  const r = await fetch(url, init);
-  const body = await r.json().catch(() => ({}));
-  return { http: r.status, body };
-}
-
-export async function billingTiers() {
-  const { http, body } = await billingJson(`${BILLING_ORIGIN}/api/billing/tiers`);
-  if (!body?.ok || !Array.isArray(body.tiers)) {
-    throw new Error(body?.error || `tiers HTTP ${http}`);
-  }
-  return body;
-}
-
-export async function billingCheckout(tier) {
-  const id = String(tier || '').trim();
-  if (!id) throw new Error('tier required');
-  const { http, body } = await billingJson(`${BILLING_ORIGIN}/api/billing/checkout`, {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ tier: id }),
-  });
-  if (!body?.ok || !body.url) {
-    throw new Error(body?.error || `checkout HTTP ${http}`);
-  }
-  return { ok: true, url: body.url, sessionId: body.sessionId || null, tier: id };
-}
-
-/** Poll the same endpoint the public /billing/done page uses. */
-export async function fetchBillingKey(session) {
-  const sid = String(session || '').trim();
-  if (!sid) return { ok: false, error: 'session required' };
-  const { body } = await billingJson(
-    `${BILLING_ORIGIN}/api/billing/key?session=${encodeURIComponent(sid)}`,
-  );
-  return body && typeof body === 'object' ? body : { ok: false, error: 'empty key response' };
-}
-
-/**
- * If the live key endpoint returned a key, persist it and return a public
- * view (the secret stays on disk). Pending/error bodies pass through.
- */
-export function ingestBillingKeyResponse(body, extra = {}, file = subscriptionFile()) {
-  const key = asKey(body?.key);
-  if (!key) {
-    if (body?.pending) return { ok: true, pending: true, saved: false };
-    return {
-      ok: false,
-      pending: false,
-      saved: false,
-      error: body?.error || 'no key yet',
-    };
-  }
-  const rec = saveSubscription({
-    key,
-    tier: body.tier || extra.tier || null,
-    tierName: body.tierName || body.name || extra.tierName || null,
-    sessionId: extra.sessionId || extra.session || null,
-  }, file);
-  return { ok: true, pending: false, saved: true, ...subscriptionPublicView(rec) };
-}