Skip to content

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.

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.js
index 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 exact
diff --git a/api/_lib/x402/spent-payments.js b/api/_lib/x402/spent-payments.js
index 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_at
FROM 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, la
RETURNING 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.js
index 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.js
index 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.js
index 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-identifi
expect(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.js
index 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();
+ });
+});