Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
fix(x402): a buyer charged for a failed call retries with the same payment instead of being told to pay twice
nirholas3c519d528836
diff --git a/api/_lib/x402-paid-endpoint.js b/api/_lib/x402-paid-endpoint.jsindex ab1ef5908..a04585f15 100644--- a/api/_lib/x402-paid-endpoint.js+++ b/api/_lib/x402-paid-endpoint.js@@ -29,7 +29,7 @@// helper. Missing keys fall back to env (so a single override doesn't// disable the other networks).-import { cors, error, respondError, rateLimited, wrap } from './http.js';+import { cors, error, readBody, respondError, rateLimited, wrap } from './http.js';import { env } from './env.js';import { clientIp, limits } from './rate-limit.js';import { logPaymentEvent } from './x402/audit-log.js';@@ -75,7 +75,15 @@ import { normalizeBazaarEntry } from './x402/bazaar-helpers.js';import { buildOffersExtension, buildReceiptExtension } from './x402/offer-receipt-server.js';import { signReceipt } from './x402-offer-receipt.js';import { recordReceipt } from './x402/receipt-storage.js';-import { claimSpentPayment, isPaymentSpent, writeReplayed } from './x402/spent-payments.js';+import {+ claimPaidRetry,+ claimSpentPayment,+ isPaymentSpent,+ markDelivered,+ markFailedAfterSettle,+ paidFailureFields,+ writeReplayed,+} from './x402/spent-payments.js';import {authenticateAuthHintsRequest,declareAuthHintsExtension,@@ -104,6 +112,71 @@ function atomicsToUsd(atomics) {return Number.isFinite(n) ? n / 1e6 : undefined;}+// Largest request body the wrapper buffers to key the idempotency hash. Above+// the Cloud Run body-parser limit (8 MB) so every parsed body fits, with room+// for the raw-audio routes that read their own stream.+const PAID_BODY_HASH_LIMIT = 32 * 1024 * 1024;++// The request bytes a paid call is FOR, so the payment-identifier hash keys a+// cached response to the exact input. GET/HEAD carry no body. On Cloud Run the+// server's body parsers have already buffered the bytes (req.rawBody / req.body)+// and readBody returns them without touching the stream; anywhere the stream is+// still unread, the bytes are kept on req.rawBody so the handler's own+// readBody/readJson reads the same buffer instead of a drained stream.+async function paidRequestBody(req) {+ const m = String(req.method || 'GET').toUpperCase();+ if (m === 'GET' || m === 'HEAD') return null;+ const buffered = Buffer.isBuffer(req.rawBody) || req.body !== undefined;+ const buf = await readBody(req, PAID_BODY_HASH_LIMIT);+ if (!buffered) req.rawBody = buf;+ return buf;+}++// What the durable spent-payment row stores about a settlement: enough for a+// paid retry to answer with the original x-payment-response and rebuild the+// handler's `settled` / `requirement` context without a second settle, plus+// the request payload hash, so a retry can only re-run the request that was+// paid for.+function settlementRecord(settled, verified, paymentResponseHeader, payloadHash) {+ return {+ payload: payloadHash ?? null,+ transaction: settled?.transaction ?? null,+ network: settled?.network || verified?.requirement?.network || null,+ payer: settled?.payer || verified?.payer || null,+ asset: verified?.requirement?.asset ?? null,+ amount: verified?.requirement?.amount ?? null,+ status: settled?.status ?? null,+ header: paymentResponseHeader ?? null,+ };+}++function settledFromRecord(record) {+ return {+ success: true,+ transaction: record?.transaction ?? null,+ network: record?.network ?? null,+ payer: record?.payer ?? null,+ ...(record?.status ? { status: record.status } : {}),+ };+}++// A paid retry skips verify, so the requirement the buyer originally paid+// against is recovered from this request's accepts by network and asset.+function verifiedFromRecord(record, requirements) {+ const requirement = requirements.find(+ (r) => r.network === record?.network && (!record?.asset || r.asset === record.asset),+ ) || { network: record?.network ?? null, asset: record?.asset ?? null, amount: record?.amount ?? null };+ return { requirement, payer: record?.payer ?? null, paymentPayload: null };+}++// Any failure once the buyer was charged answers with `paid: true`, whether a+// retry with the same payment is safe, and the settlement transaction, so a+// client never reads it as "pay again".+function writePaidFailure(res, { status, code, err, record, state }) {+ if (record?.header) res.setHeader('x-payment-response', record.header);+ return respondError(res, status, code, err, paidFailureFields({ settlement: record, ...state }));+}+function buildAccept(network, priceAtomics, resourceUrl, payToOverride, selfPayOnly = false) {const common = {scheme: 'exact',@@ -872,15 +945,22 @@ export function paidEndpoint(spec) {throw err;}- // USE-15: deduplicate before /verify. Hashing the request URL is enough- // for our GET-only paid endpoints — none of them read request bodies.- // When/if a POST endpoint joins the family, the handler can buffer- // `req.body` and pass it in here.+ // USE-15: deduplicate before /verify. The hash covers method, URL and,+ // for every non-GET route, the request body: many paid routes are POST+ // (service proxies, pipelines, launches), and hashing the URL alone let+ // two different bodies under one payment identifier share a cached+ // response.const clientPaymentId = extractIdFromHeader(paymentHeader);+ let requestBody;+ try {+ requestBody = await paidRequestBody(req);+ } catch (err) {+ return respondError(res, err.status || 400, err.status === 413 ? 'payload_too_large' : 'bad_request', err);+ }const payloadHash = hashRequestPayload({method: req.method,url: req.url,- body: null,+ body: requestBody,});// Bind the idempotency cache to the signed payment proof so a stolen or// guessed payment-identifier can't redeem a prior paid response for free.@@ -952,11 +1032,74 @@ export function paidEndpoint(spec) {// the concurrent-race window runs at the end of settlement below. Fails// OPEN on a DB outage — see api/_lib/x402/spent-payments.js for why this// control's failure policy is the inverse of settle-credit's.+ //+ // A proof that settled but whose work then failed is NOT a replay: the+ // buyer was charged and got nothing. Such a proof takes the paid-retry+ // lane instead: no second verify, no second settle, the stored+ // settlement is re-emitted, and the work runs again.+ // `spentKey` is the hash the durable row lives under (the canonical hash,+ // or the legacy one for a row written before canonicalization).+ let spentKey = paymentHash;+ let paidRetry = null;if (paymentHash) {let spent = await isPaymentSpent(paymentHash);const legacyHash = legacyPaymentProofHash(paymentHeader);- if (!spent.spent && legacyHash && legacyHash !== paymentHash) spent = await isPaymentSpent(legacyHash);- if (spent.spent) {+ if (!spent.spent && legacyHash && legacyHash !== paymentHash) {+ const legacy = await isPaymentSpent(legacyHash);+ if (legacy.spent) {+ spent = legacy;+ spentKey = legacyHash;+ }+ }+ if (+ spent.spent &&+ spent.retryable &&+ spent.endpoint === route &&+ spent.settlement?.payload &&+ spent.settlement.payload !== payloadHash+ ) {+ // A paid retry re-runs the request that was paid for, never a+ // different one: same method, URL and body.+ if (ownsReservation) await releaseSlot({ route, paymentId });+ return error(res, 409, 'payment_retry_mismatch', 'a paid retry must repeat the original request exactly',+ paidFailureFields({ settlement: spent.settlement, retriesLeft: spent.retriesLeft }));+ }+ if (spent.spent && spent.retryable && spent.endpoint === route) {+ const retry = await claimPaidRetry({ paymentHash: spentKey, endpoint: route });+ // Lost the claim to a concurrent retry of the same header: re-read,+ // so the answer below is "in flight", not "exhausted".+ if (!retry.granted) spent = await isPaymentSpent(spentKey);+ if (retry.granted) {+ paidRetry = { record: retry.settlement || spent.settlement || {}, attempt: retry.attempt };+ logPaymentEvent({+ eventType: 'payment_paid_retry',+ route,+ resourceUrl,+ payer: paidRetry.record.payer || null,+ network: paidRetry.record.network || null,+ txHash: paidRetry.record.transaction || null,+ ipAddress: clientIp(req),+ userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,+ metadata: { attempt: retry.attempt },+ });+ }+ }+ if (spent.spent && !paidRetry && spent.running) {+ // The paid work for this proof is running right now on another+ // request. Same answer as an in-flight idempotency slot.+ if (ownsReservation) await releaseSlot({ route, paymentId });+ return writeInflight(res);+ }+ if (spent.spent && !paidRetry && spent.outcome !== 'delivered' && spent.endpoint === route) {+ // Charged, failed, and out of retries (or the window closed). Still+ // a 409, but one that says the buyer paid, so a client escalates+ // with the settlement instead of paying again.+ if (ownsReservation) await releaseSlot({ route, paymentId });+ res.setHeader('x-x402-idempotent', 'replayed');+ return error(res, 409, 'payment_retries_exhausted', 'this payment settled but its retries are used up',+ paidFailureFields({ settlement: spent.settlement, retriesLeft: 0 }));+ }+ if (spent.spent && !paidRetry) {logPaymentEvent({eventType: 'payment_replay_rejected',route,@@ -979,7 +1122,9 @@ export function paidEndpoint(spec) {let verified;try {- verified = await verifyPayment({ paymentHeader, requirements, builderCode });+ verified = paidRetry+ ? verifiedFromRecord(paidRetry.record, requirements)+ : await verifyPayment({ paymentHeader, requirements, builderCode });} catch (err) {// A failed verify is the amplification vector this family guards against: a// junk X-PAYMENT header turns one cheap inbound request into one outbound@@ -1027,47 +1172,65 @@ export function paidEndpoint(spec) {}// Settle the verified payment and build the x-payment-response header- // (SIWX grant + signed receipts). Invoked with the response NOT yet+ // (signed receipts + SIWX grant). Invoked with the response NOT yet// flushed in BOTH paths: settle-then-stream calls it before the handler// runs; deliver-then-settle calls it after the handler returned a value.// On any settle/SIWX fault it writes the error response and returns null,// and the caller returns immediately.- async function settleAndBuildResponse() {+ //+ // On a paid retry the settlement already happened on the first attempt:+ // nothing is settled again and no second receipt is issued; the stored+ // settlement and its original x-payment-response are reused, and only the+ // idempotent SIWX grant is re-run.+ //+ // `claimOutcome` is what the durable spent-payment claim records:+ // 'delivered' when the good ships right after this returns (default+ // path), 'running' when the handler still has to run (streaming path).+ async function settleAndBuildResponse({ claimOutcome = 'delivered' } = {}) {let settled;- try {- settled = await settlePayment({ verified });- } catch (err) {- logPaymentEvent({- eventType: 'payment_failed',- route,- resourceUrl,- payer: verified.payer || null,- network: verified.requirement?.network || null,- amountAtomics: verified.requirement?.amount || null,- asset: verified.requirement?.asset || null,- settlementStatus: 'failed',- durationMs: Date.now() - requestStartTime,- ipAddress: clientIp(req),- userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,- metadata: { error: err.message, code: err.code },- });- recordPaymentMetric({- kind: 'x402',- status: 'failed',- network: verified.requirement?.network,- amountUsd: atomicsToUsd(verified.requirement?.amount),- latencyMs: Date.now() - requestStartTime,- reason: err.code || 'settle_failed',- });- if (ownsReservation) await releaseSlot({ route, paymentId });- respondError(res, err.status || 502, err.code || 'settle_failed', err);- return null;+ let paymentResponseHeader;+ if (paidRetry) {+ settled = settledFromRecord(paidRetry.record);+ paymentResponseHeader = paidRetry.record.header || encodePaymentResponseHeader(settled);+ } else {+ try {+ settled = await settlePayment({ verified });+ } catch (err) {+ logPaymentEvent({+ eventType: 'payment_failed',+ route,+ resourceUrl,+ payer: verified.payer || null,+ network: verified.requirement?.network || null,+ amountAtomics: verified.requirement?.amount || null,+ asset: verified.requirement?.asset || null,+ settlementStatus: 'failed',+ durationMs: Date.now() - requestStartTime,+ ipAddress: clientIp(req),+ userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,+ metadata: { error: err.message, code: err.code },+ });+ recordPaymentMetric({+ kind: 'x402',+ status: 'failed',+ network: verified.requirement?.network,+ amountUsd: atomicsToUsd(verified.requirement?.amount),+ latencyMs: Date.now() - requestStartTime,+ reason: err.code || 'settle_failed',+ });+ if (ownsReservation) await releaseSlot({ route, paymentId });+ respondError(res, err.status || 502, err.code || 'settle_failed', err);+ return null;+ }+ paymentResponseHeader = encodePaymentResponseHeader(settled, await buildResponseExtensions(settled));}+ const record = settlementRecord(settled, verified, paymentResponseHeader, payloadHash);// Record the SIWX grant so the wallet can re-access via signature next// time. siwx-storage.recordPayment is idempotent (upsert on PK), so a- // retried settle is safe. The on-chain payment is final; if Neon- // hiccups we surface 502 — the buyer can retry without paying twice.+ // retried grant is safe. The on-chain payment is final; if Neon hiccups+ // the buyer gets a paid failure that says to retry with the same+ // payment, which re-runs this write without a second charge.if (siwx && verified.payer) {try {await recordSiwxPayment({@@ -1087,16 +1250,67 @@ export function paidEndpoint(spec) {metadata: { ttlSeconds: siwx.ttlSeconds ?? null },});} catch (err) {- respondError(res, 502, 'siwx_record_failed', err);+ if (ownsReservation) await releaseSlot({ route, paymentId });+ await failAfterSettle({ status: 502, code: 'siwx_record_failed', err, record, claimed: Boolean(paidRetry) });return null;}}- // USE-17: issue a signed receipt for the settled payment and stash it- // in the response extensions envelope. Persist asynchronously so the- // /api/x402/my-receipts buyer-lookup path can serve it later — the- // recordReceipt write is fire-and-forget so a Neon hiccup never- // surfaces as a 5xx on a payment that already settled on-chain.+ // Durable spent-payment claim. Runs LAST, once settlement and every+ // downstream step above succeeded. Atomic on the primary key: of any+ // set of concurrent requests carrying one X-PAYMENT header exactly one+ // claim wins, which closes the race the pre-handler lookup alone+ // cannot. A losing claim is a replay that got past the lookup: refuse+ // the response rather than deliver the good twice. Fails OPEN on a DB+ // outage (the cache guard and settle-credit still apply). A paid retry+ // already holds the row through claimPaidRetry.+ if (!paidRetry) {+ const claim = await claimSpentPayment({+ paymentHash,+ endpoint: route,+ amountAtomics: verified.requirement?.amount ?? null,+ outcome: claimOutcome,+ settlement: record,+ });+ if (claim.replay) {+ logPaymentEvent({+ eventType: 'payment_replay_rejected',+ route,+ resourceUrl,+ payer: settled.payer || verified.payer || null,+ network: settled.network || verified.requirement?.network || null,+ amountAtomics: verified.requirement?.amount || null,+ asset: verified.requirement?.asset || null,+ txHash: settled.transaction || null,+ settlementStatus: 'failed',+ durationMs: Date.now() - requestStartTime,+ ipAddress: clientIp(req),+ userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,+ metadata: { stage: 'post_settle' },+ });+ recordPaymentMetric({+ kind: 'x402',+ status: 'failed',+ network: verified.requirement?.network,+ amountUsd: atomicsToUsd(verified.requirement?.amount),+ latencyMs: Date.now() - requestStartTime,+ reason: 'payment_replayed',+ });+ if (ownsReservation) await releaseSlot({ route, paymentId });+ writeReplayed(res, { route });+ return null;+ }+ }++ return { settled, paymentResponseHeader, record };+ }++ // USE-17: issue a signed receipt for the settled payment and stash it in+ // the response extensions envelope. Persist asynchronously so the+ // /api/x402/my-receipts buyer-lookup path can serve it later: the+ // recordReceipt write is fire-and-forget so a Neon hiccup never surfaces+ // as a 5xx on a payment that already settled on-chain.+ async function buildResponseExtensions(settled) {let responseExtensions;if (offerReceipt !== false) {try {@@ -1161,52 +1375,66 @@ export function paidEndpoint(spec) {} catch (err) {console.error('x402_receipt_sign_failed', err);}+ return responseExtensions;+ }- // Durable spent-payment claim. Runs LAST, once settlement and every- // downstream step above succeeded, so a payment that settled but then- // failed (SIWX grant write, receipt sign) leaves no spent row and the- // payer's retry with the same header still works. Atomic on the primary- // key: of any set of concurrent requests carrying one X-PAYMENT header- // exactly one claim wins, which closes the race the pre-handler lookup- // alone cannot. A losing claim is a replay that got past the lookup —- // refuse the response rather than deliver the good twice. Fails OPEN on- // a DB outage (the cache guard and settle-credit still apply).- const claim = await claimSpentPayment({- paymentHash,- endpoint: route,- amountAtomics: verified.requirement?.amount ?? null,- });- if (claim.replay) {- logPaymentEvent({- eventType: 'payment_replay_rejected',- route,- resourceUrl,- payer: settled.payer || verified.payer || null,- network: settled.network || verified.requirement?.network || null,- amountAtomics: verified.requirement?.amount || null,- asset: verified.requirement?.asset || null,- txHash: settled.transaction || null,- settlementStatus: 'failed',- durationMs: Date.now() - requestStartTime,- ipAddress: clientIp(req),- userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,- metadata: { stage: 'post_settle' },- });- recordPaymentMetric({- kind: 'x402',- status: 'failed',- network: verified.requirement?.network,- amountUsd: atomicsToUsd(verified.requirement?.amount),- latencyMs: Date.now() - requestStartTime,- reason: 'payment_replayed',+ // The buyer was charged and the work did not complete. Record the failure+ // against the spent payment (opening its retry window), log it, and answer+ // with the paid-failure fields. `claimed` is false only on a first attempt+ // that failed before its claim was taken (the SIWX grant write), which+ // writes the row here.+ async function failAfterSettle({ status, code, err, record, claimed }) {+ if (!claimed) {+ const claim = await claimSpentPayment({+ paymentHash,+ endpoint: route,+ amountAtomics: verified.requirement?.amount ?? null,+ outcome: 'failed_after_settle',+ settlement: record,+ lastError: err?.message || code,});- if (ownsReservation) await releaseSlot({ route, paymentId });- writeReplayed(res, { route });- return null;+ // Another request already holds this proof's row; never overwrite+ // its outcome from here.+ if (claim.replay) {+ writeReplayed(res, { route });+ return;+ }}-- const paymentResponseHeader = encodePaymentResponseHeader(settled, responseExtensions);- return { settled, paymentResponseHeader };+ const state = await markFailedAfterSettle({+ paymentHash: spentKey,+ settlement: record,+ lastError: err?.message || code,+ });+ logPaymentEvent({+ eventType: 'payment_failed_after_settle',+ route,+ resourceUrl,+ payer: record.payer,+ network: record.network,+ amountAtomics: record.amount,+ asset: record.asset,+ txHash: record.transaction,+ settlementStatus: 'success',+ durationMs: Date.now() - requestStartTime,+ ipAddress: clientIp(req),+ userAgent: req.headers?.['user-agent']?.slice(0, 512) || null,+ metadata: { code, error: String(err?.message || '').slice(0, 300), retries_left: state.retriesLeft, retry: paidRetry?.attempt ?? 0 },+ });+ recordPaymentMetric({+ kind: 'x402',+ status: 'failed',+ network: record.network,+ amountUsd: atomicsToUsd(record.amount),+ latencyMs: Date.now() - requestStartTime,+ reason: 'failed_after_settle',+ });+ if (res.headersSent) {+ // A stream that already began cannot carry a JSON error; end it. The+ // row says failed, so the same payment can still be retried.+ if (!res.writableEnded) res.end();+ return;+ }+ writePaidFailure(res, { status, code, err, record, state });}// Success telemetry for a settled payment — logged once the good has been@@ -1274,9 +1502,9 @@ export function paidEndpoint(spec) {// body isn't buffered, so no idempotency cache entry is stored; the// reservation is released once the handler finishes.if (streaming) {- const outcome = await settleAndBuildResponse();+ const outcome = await settleAndBuildResponse({ claimOutcome: 'running' });if (!outcome) return;- const { settled, paymentResponseHeader } = outcome;+ const { settled, paymentResponseHeader, record } = outcome;res.setHeader('x-payment-response', paymentResponseHeader);res.setHeader('cache-control', 'no-store');@@ -1292,17 +1520,21 @@ export function paidEndpoint(spec) {});} catch (err) {if (ownsReservation) await releaseSlot({ route, paymentId });- // The payment already settled on-chain. If the handler already began- // streaming we can only record the settlement and stop; otherwise- // surface the fault so the buyer sees an actionable error.+ // The handler finished its body and then threw: the good shipped, so+ // the payment is spent like any delivered one.if (res.writableEnded) {+ await markDelivered(spentKey);recordSettledSuccess(settled);return;}- if (err instanceof X402Error && err.status === 402) {- return await send402(res, { ...challenge, error: err.message });- }- return respondError(res, err.status || 500, err.code || 'internal_error', err);+ // The payment already settled on-chain and the good did not ship.+ // Never answer "pay again": record the failure against this proof+ // and tell the buyer the same payment re-runs the work. A 402 thrown+ // by the handler is reported as a 500 here, because a 402 now would+ // prompt the client to pay a second time.+ const status = err?.status && err.status !== 402 ? err.status : 500;+ await failAfterSettle({ status, code: err?.code || 'internal_error', err, record, claimed: true });+ return;}if (ownsReservation) await releaseSlot({ route, paymentId });@@ -1313,6 +1545,7 @@ export function paidEndpoint(spec) {res.setHeader('content-type', `${mimeType}; charset=utf-8`);res.end(typeof result === 'string' ? result : JSON.stringify(result));}+ await markDelivered(spentKey);recordSettledSuccess(settled);return;}@@ -1327,10 +1560,21 @@ export function paidEndpoint(spec) {});} catch (err) {if (ownsReservation) await releaseSlot({ route, paymentId });+ // A paid retry is past settlement: the buyer paid on the first attempt,+ // so this failure keeps the retry lane open rather than asking for a+ // new payment.+ if (paidRetry) {+ const status = err?.status && err.status !== 402 ? err.status : 500;+ const record = settlementRecord(settledFromRecord(paidRetry.record), verified, paidRetry.record.header, payloadHash);+ await failAfterSettle({ status, code: err?.code || 'internal_error', err, record, claimed: true });+ return;+ }if (err instanceof X402Error && err.status === 402) {return await send402(res, { ...challenge, error: err.message });}- return respondError(res, err.status || 500, err.code || 'internal_error', err);+ // Deliver-then-settle: nothing was settled, so the buyer was not+ // charged and the same payment can be sent again.+ return respondError(res, err.status || 500, err.code || 'internal_error', err, { paid: false, retry_safe: true });}// Deliver-then-settle: the handler MUST return a value and leave the@@ -1372,6 +1616,7 @@ export function paidEndpoint(spec) {const outcome = await settleAndBuildResponse();if (!outcome) return;const { settled, paymentResponseHeader } = outcome;+ if (paidRetry) await markDelivered(spentKey);// Roadmap phase 4: per-job metering. The settlement already landed, so// the hook can bind the payment facts (payer, amount, tx) to the exactdiff --git a/api/_lib/x402/spent-payments.js b/api/_lib/x402/spent-payments.jsindex 72ad8be7d..442bb316c 100644--- a/api/_lib/x402/spent-payments.js+++ b/api/_lib/x402/spent-payments.js@@ -29,6 +29,12 @@// work anyway: the payment already landed on chain, so the facilitator rejects// it. Only a proof whose work was delivered (`delivered`) answers 409.//+// A streaming route settles BEFORE its handler runs, so its claim is taken with+// outcome `running` (stored as `retrying`: work is in progress after+// settlement) and flipped to `delivered` once the body ships. If the process+// dies mid-handler the row would sit at `retrying` forever; a row that has not+// moved for PAID_RUNNING_STALE_SECONDS is treated as failed and may be retried.+//// Failure policy: FAIL OPEN, deliberately. The in-cache guard, the payment// identifier reservation and the on-chain settle-credit gate all remain in// force, so a Neon outage degrades this control to "cache-window replay@@ -63,30 +69,43 @@ export const PAID_RETRY_WINDOW_SECONDS = Math.max(60,Number(process.env.X402_PAID_RETRY_WINDOW_SECONDS) || 24 * 3600,);+/** A run after settlement that has not finished in this long is presumed dead. */+export const PAID_RUNNING_STALE_SECONDS = Math.max(+ 60,+ Number(process.env.X402_PAID_RUNNING_STALE_SECONDS) || 15 * 60,+);++function isStaleRun(row) {+ if (row.outcome !== 'retrying' || !row.updated_at) return false;+ return new Date(row.updated_at).getTime() < Date.now() - PAID_RUNNING_STALE_SECONDS * 1000;+}/*** Has this payment proof already been honoured, and if it failed after the* buyer was charged, may it still be retried?** @param {string|null|undefined} paymentHash Hash of the signed X-PAYMENT proof.- * @returns {Promise<{ spent: boolean, unavailable: boolean, retryable: boolean, outcome: string|null, endpoint: string|null, settlement: object|null }>}+ * @returns {Promise<{ spent: boolean, unavailable: boolean, retryable: boolean, running: boolean, retriesLeft?: number, outcome: string|null, endpoint: string|null, settlement: object|null }>}* `spent` is true only on a positive, durable answer. `retryable` is true when- * the proof settled but its work failed, retries remain and the window is- * open. `unavailable` marks the fail-open path so the caller can log it rather- * than silently trusting a "not spent" that was never actually checked.+ * the proof settled but its work failed (or its run went stale), retries+ * remain and the window is open. `running` is true while another request is+ * doing the paid work for this proof right now. `unavailable` marks the+ * fail-open path so the caller can log it rather than silently trusting a+ * "not spent" that was never actually checked.*/export async function isPaymentSpent(paymentHash) {- const none = { spent: false, retryable: false, outcome: null, endpoint: null, settlement: null };+ const none = { spent: false, retryable: false, running: false, outcome: null, endpoint: null, settlement: null };if (!paymentHash) return { ...none, unavailable: false };try {const rows = await sql`- SELECT endpoint, outcome, retry_count, retry_until, settlement+ SELECT endpoint, outcome, retry_count, retry_until, settlement, updated_atFROM x402_spent_payments WHERE payment_hash = ${paymentHash} LIMIT 1`;const row = rows?.[0];if (!row) return { ...none, unavailable: false };+ const stale = isStaleRun(row);const retryable =- row.outcome === 'failed_after_settle' &&+ (row.outcome === 'failed_after_settle' || stale) &&Number(row.retry_count || 0) < PAID_RETRY_MAX &&(!row.retry_until || new Date(row.retry_until).getTime() > Date.now());const settlement = typeof row.settlement === 'string' ? JSON.parse(row.settlement) : row.settlement;@@ -94,6 +113,8 @@ export async function isPaymentSpent(paymentHash) {spent: true,unavailable: false,retryable,+ running: row.outcome === 'retrying' && !stale,+ retriesLeft: Math.max(0, PAID_RETRY_MAX - Number(row.retry_count || 0)),outcome: row.outcome || 'delivered',endpoint: row.endpoint ?? null,settlement: settlement || null,@@ -109,14 +130,16 @@ export async function isPaymentSpent(paymentHash) {* set of concurrent requests carrying one X-PAYMENT header exactly one claim* returns a row. Pass `outcome: 'failed_after_settle'` (with the settlement)* when the buyer was charged but the work did not complete, so the same header- * can retry through claimPaidRetry.+ * can retry through claimPaidRetry. Pass `outcome: 'running'` when the work+ * runs AFTER this claim (settle-then-stream); finish it with markDelivered or+ * markFailedAfterSettle.** @param {object} args* @param {string|null|undefined} args.paymentHash* @param {string} args.endpoint Route the proof was spent on (audit context).* @param {string|number|null} [args.amountAtomics] Price paid, in asset atomics.- * @param {'delivered'|'failed_after_settle'} [args.outcome]- * @param {object|null} [args.settlement] { transaction, network, payer, asset, amount, header }+ * @param {'delivered'|'failed_after_settle'|'running'} [args.outcome]+ * @param {object|null} [args.settlement] { transaction, network, payer, asset, amount, status, header }* @param {string|null} [args.lastError]* @returns {Promise<{ granted: boolean, replay: boolean, unavailable: boolean }>}*/@@ -133,12 +156,13 @@ export async function claimSpentPayment({// nothing that could double-deliver under this key either.if (!paymentHash) return { granted: true, replay: false, unavailable: false };const failed = outcome === 'failed_after_settle';+ const stored = failed ? 'failed_after_settle' : outcome === 'running' ? 'retrying' : 'delivered';try {const rows = await sql`INSERT INTO x402_spent_payments(payment_hash, endpoint, amount_atomics, outcome, settlement, last_error, retry_until)VALUES (${paymentHash}, ${endpoint}, ${amountAtomics == null ? null : String(amountAtomics)},- ${failed ? 'failed_after_settle' : 'delivered'},+ ${stored},${settlement ? JSON.stringify(settlement) : null}::jsonb,${lastError ? String(lastError).slice(0, 500) : null},${failed ? new Date(Date.now() + PAID_RETRY_WINDOW_SECONDS * 1000) : null})@@ -157,10 +181,15 @@ export async function claimSpentPayment({* Record that a claimed proof's work failed after settlement. Opens (or keeps)* the retry window and stores the settlement the retry will re-emit.*- * @returns {Promise<{ retriesLeft: number, retryUntil: string|null }>}+ * `recorded` is false when no row could be updated (DB outage, or a fail-open+ * claim that never wrote one): the same header then cannot be retried, and the+ * buyer must be told so rather than promised a retry that will 402.+ *+ * @returns {Promise<{ retriesLeft: number, retryUntil: string|null, recorded: boolean }>}*/export async function markFailedAfterSettle({ paymentHash, settlement = null, lastError = null }) {- if (!paymentHash) return { retriesLeft: 0, retryUntil: null };+ const unrecorded = { retriesLeft: 0, retryUntil: null, recorded: false };+ if (!paymentHash) return unrecorded;try {const rows = await sql`UPDATE x402_spent_payments@@ -173,21 +202,23 @@ export async function markFailedAfterSettle({ paymentHash, settlement = null, laRETURNING retry_count, retry_until`;const row = rows?.[0];- if (!row) return { retriesLeft: 0, retryUntil: null };+ if (!row) return unrecorded;const open = !row.retry_until || new Date(row.retry_until).getTime() > Date.now();return {retriesLeft: open ? Math.max(0, PAID_RETRY_MAX - Number(row.retry_count || 0)) : 0,retryUntil: row.retry_until ? new Date(row.retry_until).toISOString() : null,+ recorded: true,};} catch (err) {logDegraded('mark_failed', err);- return { retriesLeft: 0, retryUntil: null };+ return unrecorded;}}/**- * Take one retry for a proof that failed after settlement. Atomic: two- * concurrent retries of one header cannot both run. Returns the stored+ * Take one retry for a proof that failed after settlement, or whose run went+ * stale (the process died mid-handler). Atomic: two concurrent retries of one+ * header cannot both run. Returns the stored* settlement so the retry can answer with the original x-payment-response.** @returns {Promise<{ granted: boolean, settlement: object|null, attempt: number }>}@@ -200,7 +231,8 @@ export async function claimPaidRetry({ paymentHash, endpoint }) {SET outcome = 'retrying', retry_count = retry_count + 1, updated_at = now()WHERE payment_hash = ${paymentHash}AND endpoint = ${endpoint}- AND outcome = 'failed_after_settle'+ AND (outcome = 'failed_after_settle'+ OR (outcome = 'retrying' AND updated_at < now() - make_interval(secs => ${PAID_RUNNING_STALE_SECONDS})))AND retry_count < ${PAID_RETRY_MAX}AND (retry_until IS NULL OR retry_until > now())RETURNING settlement, retry_count@@ -233,15 +265,17 @@ export const PAID_RETRY_SENTENCE ='You were charged; repeat this exact request with the same payment to get your result.';export const PAID_EXHAUSTED_SENTENCE ='You were charged, and this payment has used up its retries. Contact support with the settlement transaction and it will be made right.';+export const PAID_UNRECORDED_SENTENCE =+ 'You were charged, but the retry record could not be saved, so this payment cannot be retried. Contact support with the settlement transaction and it will be made right.';/*** The fields every failure after settlement carries, so a buyer's client can* tell "you paid, retry safely" from "you were not charged".*- * @param {{ settlement: object|null, retriesLeft: number, retryUntil?: string|null }} ctx+ * @param {{ settlement: object|null, retriesLeft: number, retryUntil?: string|null, recorded?: boolean }} ctx*/-export function paidFailureFields({ settlement, retriesLeft, retryUntil = null }) {- const retrySafe = retriesLeft > 0;+export function paidFailureFields({ settlement, retriesLeft, retryUntil = null, recorded = true }) {+ const retrySafe = recorded && retriesLeft > 0;return {paid: true,retry_safe: retrySafe,@@ -249,9 +283,9 @@ export function paidFailureFields({ settlement, retriesLeft, retryUntil = null }transaction: settlement?.transaction ?? null,network: settlement?.network ?? null,},- retries_left: Math.max(0, retriesLeft),+ retries_left: retrySafe ? retriesLeft : 0,...(retryUntil ? { retry_until: retryUntil } : {}),- message: retrySafe ? PAID_RETRY_SENTENCE : PAID_EXHAUSTED_SENTENCE,+ message: retrySafe ? PAID_RETRY_SENTENCE : recorded ? PAID_EXHAUSTED_SENTENCE : PAID_UNRECORDED_SENTENCE,};}diff --git a/api/v1/ai/asr.js b/api/v1/ai/asr.jsindex 4ee1bbee1..3f541eef1 100644--- a/api/v1/ai/asr.js+++ b/api/v1/ai/asr.js@@ -181,6 +181,9 @@ export default wrap(async function handler(req, res) {return error(res, 400, 'bad_request', e?.message || 'could not read request body');}req._aiSpeechBody = buf;+ // The stream is drained now; leave the bytes where readBody looks first so+ // the paid wrapper hashes the real clip into its idempotency key.+ if (!Buffer.isBuffer(req.rawBody)) req.rawBody = buf;// A payment header means the caller is on the paid rail already.const paymentPresent = Boolean(req.headers['x-payment'] || req.headers['payment-signature']);diff --git a/api/v1/ai/tts.js b/api/v1/ai/tts.jsindex a3dc8bef0..cbe85446d 100644--- a/api/v1/ai/tts.js+++ b/api/v1/ai/tts.js@@ -197,6 +197,9 @@ export default wrap(async function handler(req, res) {return error(res, 400, 'bad_request', e?.message || 'could not read request body');}req._aiSpeechBody = raw;+ // The stream is drained now; leave the bytes where readBody looks first so+ // the paid wrapper hashes the real request into its idempotency key.+ if (!Buffer.isBuffer(req.rawBody)) req.rawBody = raw;// A payment header means the caller is on the paid rail already.const paymentPresent = Boolean(req.headers['x-payment'] || req.headers['payment-signature']);diff --git a/tests/api/x402-paid-endpoint-replay.test.js b/tests/api/x402-paid-endpoint-replay.test.jsindex 4ff20c1cf..194e8a9b4 100644--- a/tests/api/x402-paid-endpoint-replay.test.js+++ b/tests/api/x402-paid-endpoint-replay.test.js@@ -15,6 +15,8 @@ import { Readable } from 'node:stream';import { beforeAll, beforeEach, afterAll, describe, it, expect, vi } from 'vitest';+import { readJson } from '../../api/_lib/http.js';+// Mock only the facilitator-facing verify/settle; keep every other export real// so send402/build402Body/encodePaymentResponseHeader behave normally.const verifyPayment = vi.fn();@@ -44,7 +46,10 @@ const HANDLER_BAZAAR = {schema: { type: 'object' },};-function mockReqRes({ method = 'GET', headers = {}, url = ROUTE } = {}) {+// `body` is pushed onto the request stream, as on a server with no body parser.+// `rawBody` instead models the Cloud Run server, whose express.json() `verify`+// hook leaves the exact bytes on req.rawBody and drains the stream.+function mockReqRes({ method = 'GET', headers = {}, url = ROUTE, body, rawBody } = {}) {const lowerHeaders = {};for (const [k, v] of Object.entries(headers)) lowerHeaders[k.toLowerCase()] = v;const req = Object.assign(new Readable({ read() {} }), {@@ -54,6 +59,8 @@ function mockReqRes({ method = 'GET', headers = {}, url = ROUTE } = {}) {connection: { remoteAddress: '127.0.0.1' },socket: { remoteAddress: '127.0.0.1' },});+ if (rawBody !== undefined) req.rawBody = Buffer.from(rawBody);+ else if (body !== undefined) req.push(body);req.push(null);const chunks = [];const resHeaders = {};@@ -242,3 +249,68 @@ describe('paidEndpoint() always-on replay protection (no client payment-identifiexpect(handlerCalls).toBe(2);});});++describe('paidEndpoint() idempotency hash covers POST bodies', () => {+ const PID = 'pay_post_body_hash_0001';++ // A POST route whose good depends on the body, like the service proxies and+ // pipelines. The handler reads the body itself, after the wrapper hashed it.+ function postEndpoint(calls) {+ return makeEndpoint(+ async ({ req }) => {+ const input = await readJson(req);+ calls.push(input);+ return { ok: true, echo: input.prompt };+ },+ { method: 'POST' },+ );+ }++ for (const mode of ['stream', 'rawBody']) {+ it(`two different bodies under one payment identifier do not share a cached response (${mode})`, async () => {+ const calls = [];+ const endpoint = postEndpoint(calls);+ const header = paymentHeader({ withId: PID });+ const send = async (prompt) => {+ const bytes = JSON.stringify({ prompt });+ const { req, res } = mockReqRes({+ method: 'POST',+ headers: { 'x-payment': header, 'content-type': 'application/json' },+ ...(mode === 'rawBody' ? { rawBody: bytes } : { body: bytes }),+ });+ await endpoint(req, res);+ return res;+ };++ const first = await send('a red chair');+ expect(first.statusCode).toBe(200);+ // The handler still read the body after the wrapper hashed it.+ expect(JSON.parse(first.body)).toMatchObject({ ok: true, echo: 'a red chair' });++ // Same payment identifier, different body: a different good. Before the+ // body was hashed this was a cache hit that served the red chair.+ const second = await send('a blue lamp');+ expect(second.statusCode).toBe(409);+ expect(second.getHeader('x-x402-idempotent')).toBe('conflict');+ expect(second.body).not.toContain('a red chair');++ // Same identifier and the same body is a true replay: cached, not re-run.+ const third = await send('a red chair');+ expect(third.statusCode).toBe(200);+ expect(third.getHeader('x-x402-idempotent')).toBe('replay');+ expect(third.body).toBe(first.body);++ expect(calls).toEqual([{ prompt: 'a red chair' }]);+ expect(settlePayment).toHaveBeenCalledTimes(1);+ });+ }++ it('hashes the body into the payload hash for non-GET methods only', () => {+ const a = cacheMod.hashRequestPayload({ method: 'POST', url: ROUTE, body: Buffer.from('{"a":1}') });+ const b = cacheMod.hashRequestPayload({ method: 'POST', url: ROUTE, body: Buffer.from('{"a":2}') });+ expect(a).not.toBe(b);+ expect(cacheMod.hashRequestPayload({ method: 'GET', url: ROUTE, body: null })).toBe(+ cacheMod.hashRequestPayload({ method: 'GET', url: ROUTE }),+ );+ });+});diff --git a/tests/api/x402-spent-payments.test.js b/tests/api/x402-spent-payments.test.jsindex df25c2c0a..7c33536d9 100644--- a/tests/api/x402-spent-payments.test.js+++ b/tests/api/x402-spent-payments.test.js@@ -45,38 +45,40 @@ function fakeSql(strings, ...values) {if (dbDown) {return Promise.reject(Object.assign(new Error('connection refused'), { code: 'ECONNREFUSED' }));}- if (/SELECT endpoint, outcome, retry_count, retry_until, settlement\s+FROM x402_spent_payments/i.test(query)) {+ if (/SELECT endpoint, outcome, retry_count, retry_until, settlement, updated_at\s+FROM x402_spent_payments/i.test(query)) {const [hash] = values;const row = spentRows.get(hash);if (!row) return Promise.resolve([]);- return Promise.resolve([{ endpoint: row.endpoint, outcome: row.outcome || 'delivered', retry_count: row.retry_count || 0, retry_until: row.retry_until || null, settlement: row.settlement || null }]);+ return Promise.resolve([{ endpoint: row.endpoint, outcome: row.outcome || 'delivered', retry_count: row.retry_count || 0, retry_until: row.retry_until || null, settlement: row.settlement || null, updated_at: row.updated_at || new Date() }]);}if (/INSERT INTO x402_spent_payments/i.test(query)) {const [hash, endpoint, amount, outcome, settlement, lastError, retryUntil] = values;if (spentRows.has(hash)) return Promise.resolve([]); // ON CONFLICT DO NOTHING- spentRows.set(hash, { endpoint, amount_atomics: amount, outcome, settlement: settlement ? JSON.parse(settlement) : null, last_error: lastError, retry_until: retryUntil, retry_count: 0, created_at: new Date() });+ spentRows.set(hash, { endpoint, amount_atomics: amount, outcome, settlement: settlement ? JSON.parse(settlement) : null, last_error: lastError, retry_until: retryUntil, retry_count: 0, created_at: new Date(), updated_at: new Date() });return Promise.resolve([{ payment_hash: hash }]);}if (/SET outcome = 'failed_after_settle'/i.test(query)) {const [settlement, lastError, retryUntil, hash] = values;const row = spentRows.get(hash);if (!row) return Promise.resolve([]);- Object.assign(row, { outcome: 'failed_after_settle', settlement: row.settlement || (settlement ? JSON.parse(settlement) : null), last_error: lastError, retry_until: row.retry_until || retryUntil });+ Object.assign(row, { outcome: 'failed_after_settle', settlement: row.settlement || (settlement ? JSON.parse(settlement) : null), last_error: lastError, retry_until: row.retry_until || retryUntil, updated_at: new Date() });return Promise.resolve([{ retry_count: row.retry_count || 0, retry_until: row.retry_until }]);}if (/SET outcome = 'retrying'/i.test(query)) {- const [hash, endpoint, max] = values;+ const [hash, endpoint, staleSeconds, max] = values;const row = spentRows.get(hash);const open = row && (!row.retry_until || new Date(row.retry_until).getTime() > Date.now());- if (!row || row.endpoint !== endpoint || row.outcome !== 'failed_after_settle' || (row.retry_count || 0) >= max || !open) return Promise.resolve([]);+ const stale = row && row.outcome === 'retrying' && new Date(row.updated_at).getTime() < Date.now() - staleSeconds * 1000;+ if (!row || row.endpoint !== endpoint || !(row.outcome === 'failed_after_settle' || stale) || (row.retry_count || 0) >= max || !open) return Promise.resolve([]);row.outcome = 'retrying';row.retry_count = (row.retry_count || 0) + 1;+ row.updated_at = new Date();return Promise.resolve([{ settlement: row.settlement, retry_count: row.retry_count }]);}if (/SET outcome = 'delivered'/i.test(query)) {const [hash] = values;const row = spentRows.get(hash);- if (row) Object.assign(row, { outcome: 'delivered', last_error: null });+ if (row) Object.assign(row, { outcome: 'delivered', last_error: null, updated_at: new Date() });return Promise.resolve([]);}return Promise.resolve([]);@@ -88,6 +90,14 @@ vi.mock('../../api/_lib/db.js', async (importActual) => {vi.mock('@coinbase/x402', () => ({ createCdpAuthHeaders: vi.fn(async () => ({})) }));+// The SIWX grant write is the one post-settle step on the default path that can+// fail after the buyer was charged; make it controllable.+const recordSiwxPayment = vi.fn(async () => {});+vi.mock('../../api/_lib/siwx-server.js', async (importActual) => {+ const actual = await importActual();+ return { ...actual, recordSiwxPayment };+});+let paidEndpoint;let cacheMod;@@ -194,6 +204,8 @@ beforeEach(() => {cacheMod._resetMemoryStore();spentRows.clear();dbDown = false;+ recordSiwxPayment.mockReset();+ recordSiwxPayment.mockImplementation(async () => {});auditEvents.length = 0;verifyPayment.mockReset();settlePayment.mockReset();@@ -321,3 +333,169 @@ describe('paidEndpoint() durable spent-payment guard', () => {expect(res.getHeader('x-payment-response')).toBeTruthy();});});++describe('paidEndpoint() never asks a charged buyer to pay twice', () => {+ const streamOnce = (failures) => {+ let calls = 0;+ const handler = async ({ res }) => {+ calls += 1;+ if (calls <= failures) throw Object.assign(new Error('model backend unavailable'), { status: 503, code: 'upstream_unavailable' });+ res.setHeader('content-type', 'application/octet-stream');+ res.write('BINARY');+ res.end();+ };+ return { handler, calls: () => calls };+ };++ it('a streaming handler that fails after settlement answers paid:true and retry_safe:true with the settlement', async () => {+ const { handler } = streamOnce(1);+ const res = await callPaid(handler, { spec: { streaming: true } });++ expect(res.statusCode).toBe(503);+ const body = JSON.parse(res.body);+ expect(body).toMatchObject({+ error: 'upstream_unavailable',+ paid: true,+ retry_safe: true,+ settlement: { transaction: '0xdeadbeef', network: BASE },+ message: 'You were charged; repeat this exact request with the same payment to get your result.',+ });+ expect(body.retries_left).toBeGreaterThan(0);+ expect(res.getHeader('x-payment-response')).toBeTruthy();+ const [row] = [...spentRows.values()];+ expect(row.outcome).toBe('failed_after_settle');+ expect(auditEvents.some((e) => e.eventType === 'payment_failed_after_settle')).toBe(true);+ });++ it('the same payment re-runs a failed streaming handler and delivers without a second verify or charge', async () => {+ const { handler, calls } = streamOnce(1);+ const first = await callPaid(handler, { spec: { streaming: true } });+ expect(first.statusCode).toBe(503);+ const firstReceipt = first.getHeader('x-payment-response');++ const retry = await callPaid(handler, { spec: { streaming: true } });++ expect(retry.statusCode).toBe(200);+ expect(retry.body).toBe('BINARY');+ expect(calls()).toBe(2);+ expect(verifyPayment).toHaveBeenCalledTimes(1);+ expect(settlePayment).toHaveBeenCalledTimes(1);+ // The retry answers with the original settlement, not a new one.+ expect(retry.getHeader('x-payment-response')).toBe(firstReceipt);+ const [row] = [...spentRows.values()];+ expect(row).toMatchObject({ outcome: 'delivered', retry_count: 1 });+ expect(auditEvents.filter((e) => e.eventType === 'payment_settled')).toHaveLength(1);+ });++ it('a paid retry only re-runs the request that was paid for', async () => {+ const { handler, calls } = streamOnce(1);+ const endpoint = makeEndpoint(handler, { streaming: true });+ const send = async (url) => {+ const { req, res } = mockReqRes({ url, headers: { 'x-payment': paymentHeader() } });+ await endpoint(req, res);+ return res;+ };+ expect((await send(`${ROUTE}?item=cheap`)).statusCode).toBe(503);++ const swapped = await send(`${ROUTE}?item=expensive`);+ expect(swapped.statusCode).toBe(409);+ expect(JSON.parse(swapped.body)).toMatchObject({ error: 'payment_retry_mismatch', paid: true, retry_safe: true });+ expect(calls()).toBe(1);++ const same = await send(`${ROUTE}?item=cheap`);+ expect(same.statusCode).toBe(200);+ expect(same.body).toBe('BINARY');+ });++ it('a completed call replayed still answers 409 payment_replayed, including after a paid retry', async () => {+ const { handler } = streamOnce(1);+ await callPaid(handler, { spec: { streaming: true } });+ const retry = await callPaid(handler, { spec: { streaming: true } });+ expect(retry.statusCode).toBe(200);++ const replay = await callPaid(handler, { spec: { streaming: true } });+ expect(replay.statusCode).toBe(409);+ expect(JSON.parse(replay.body)).toMatchObject({ error: 'payment_replayed' });+ expect(replay.body).not.toContain('BINARY');+ });++ it('stops promising a retry once the retries are used up, and then answers 409 with paid:true', async () => {+ const { PAID_RETRY_MAX } = await import('../../api/_lib/x402/spent-payments.js');+ const { handler, calls } = streamOnce(Infinity);++ let last;+ for (let i = 0; i <= PAID_RETRY_MAX; i++) last = await callPaid(handler, { spec: { streaming: true } });+ expect(calls()).toBe(PAID_RETRY_MAX + 1);+ expect(JSON.parse(last.body)).toMatchObject({ paid: true, retry_safe: false, retries_left: 0 });++ const after = await callPaid(handler, { spec: { streaming: true } });+ expect(after.statusCode).toBe(409);+ expect(JSON.parse(after.body)).toMatchObject({+ error: 'payment_retries_exhausted',+ paid: true,+ retry_safe: false,+ settlement: { transaction: '0xdeadbeef' },+ });+ expect(calls()).toBe(PAID_RETRY_MAX + 1);+ expect(settlePayment).toHaveBeenCalledTimes(1);+ });++ it('a SIWX grant write that fails after settlement answers paid:true, and the same payment completes it', async () => {+ recordSiwxPayment.mockRejectedValueOnce(new Error('neon timeout'));+ let ran = 0;+ const spec = { siwx: { statement: 'Access the test resource' } };+ const first = await callPaid(async () => ({ ok: true, n: ++ran }), { spec });++ expect(first.statusCode).toBe(502);+ expect(JSON.parse(first.body)).toMatchObject({+ error: 'siwx_record_failed',+ paid: true,+ retry_safe: true,+ settlement: { transaction: '0xdeadbeef' },+ });++ cacheMod._resetMemoryStore();+ const retry = await callPaid(async () => ({ ok: true, n: ++ran }), { spec });+ expect(retry.statusCode).toBe(200);+ expect(JSON.parse(retry.body)).toMatchObject({ ok: true });+ expect(recordSiwxPayment).toHaveBeenCalledTimes(2);+ expect(settlePayment).toHaveBeenCalledTimes(1);+ expect([...spentRows.values()][0].outcome).toBe('delivered');+ });++ it('a run that died mid-handler is retryable once it goes stale; a live run answers in-flight', async () => {+ const { hashPaymentProof } = await import('../../api/_lib/x402/idempotency-cache.js');+ const hash = hashPaymentProof(paymentHeader());+ const settlement = { transaction: '0xdeadbeef', network: BASE, payer: 'PAYER', asset: ASSET_BASE, amount: '1000', header: null };+ spentRows.set(hash, { endpoint: ROUTE, outcome: 'retrying', retry_count: 0, settlement, updated_at: new Date() });++ const live = await callPaid(async () => ({ ok: true }), { spec: { streaming: true } });+ expect(live.statusCode).toBe(409);+ expect(live.getHeader('x-x402-idempotent')).toBe('in-flight');++ spentRows.get(hash).updated_at = new Date(Date.now() - 60 * 60 * 1000);+ const recovered = await callPaid(async () => ({ ok: true, recovered: true }), { spec: { streaming: true } });+ expect(recovered.statusCode).toBe(200);+ expect(JSON.parse(recovered.body)).toMatchObject({ recovered: true });+ expect(settlePayment).not.toHaveBeenCalled();+ });++ it('when the retry record cannot be saved, says so instead of promising a retry', async () => {+ const { handler } = streamOnce(1);+ dbDown = true;+ const res = await callPaid(handler, { spec: { streaming: true } });++ expect(res.statusCode).toBe(503);+ expect(JSON.parse(res.body)).toMatchObject({ paid: true, retry_safe: false, settlement: { transaction: '0xdeadbeef' } });+ expect(JSON.parse(res.body).message).toMatch(/could not be saved/);+ });++ it('a default-path handler failure says the buyer was not charged', async () => {+ const res = await callPaid(async () => {+ throw Object.assign(new Error('bad input'), { status: 400, code: 'bad_request' });+ });+ expect(res.statusCode).toBe(400);+ expect(JSON.parse(res.body)).toMatchObject({ paid: false, retry_safe: true });+ expect(settlePayment).not.toHaveBeenCalled();+ });+});