uvd-x402-sdk 2.95.0 → 2.97.0

package/dist/backend/index.js

@@ -1,5 +1,8 @@
 'use strict';
 
+var ed25519 = require('@noble/curves/ed25519');
+var sha256 = require('@noble/hashes/sha256');
+var utils = require('@noble/hashes/utils');
 var ethers = require('ethers');
 
 var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
@@ -8,6 +11,205 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   if (typeof require !== "undefined") return require.apply(this, arguments);
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
+var RECEIPT_ISSUER = "https://facilitator.ultravioletadao.xyz";
+var encoder = new TextEncoder();
+var decoder = new TextDecoder("utf-8", { fatal: true });
+var digest = (value) => utils.bytesToHex(sha256.sha256(value));
+function canonicalReceiptJson(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+  if (typeof value === "number" && Number.isSafeInteger(value) && value >= 0) return String(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalReceiptJson).join(",")}]`;
+  if (typeof value === "object" && value) {
+    const object = value;
+    const keys = Object.keys(object).sort();
+    if (keys.some((key) => !/^[\x00-\x7f]*$/.test(key))) throw new Error("non-ASCII canonical key");
+    return `{${keys.map((key) => `${JSON.stringify(key)}:${canonicalReceiptJson(object[key])}`).join(",")}}`;
+  }
+  throw new Error("unsupported canonical value");
+}
+function receiptCommitment(domain, value) {
+  return digest(encoder.encode(`${domain}
+${canonicalReceiptJson(value)}`));
+}
+function encode64(bytes) {
+  if (typeof Buffer !== "undefined") return Buffer.from(bytes).toString("base64");
+  return btoa(Array.from(bytes, (b) => String.fromCharCode(b)).join(""));
+}
+function decode64(value) {
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(value) || value.length % 4 !== 0) throw new Error("invalid base64");
+  if (typeof Buffer !== "undefined") return new Uint8Array(Buffer.from(value, "base64"));
+  return Uint8Array.from(atob(value), (c) => c.charCodeAt(0));
+}
+function decodeUrl64(value) {
+  const padded = value.replace(/-/g, "+").replace(/_/g, "/");
+  return decode64(padded + "=".repeat((4 - padded.length % 4) % 4));
+}
+function parseFacilitatorReceipt(value) {
+  if (value === null || value === void 0) return null;
+  const r = value;
+  if (r.schemaVersion !== 1 || !["verified", "pending", "confirmed", "rejected", "unknown"].includes(r.status)) throw new Error("unsupported receipt version or state");
+  for (const key of ["receiptId", "issuer", "operation", "network", "scheme", "asset", "amount", "payTo", "paymentRequestHash", "authorizationId"]) {
+    if (typeof r[key] !== "string" || !r[key]) throw new Error(`invalid receipt ${key}`);
+  }
+  if (!Number.isSafeInteger(r.revision) || r.revision < 1 || !r.request || !r.retry) throw new Error("incomplete receipt");
+  if (r.requestHashVersion !== "uvd-x402-request-v1" || r.requestHash !== receiptCommitment(r.requestHashVersion, r.request)) throw new Error("receipt request hash mismatch");
+  for (const key of ["network", "scheme", "asset", "amount", "payTo", "purchaseId"]) {
+    if (r[key] !== r.request[key]) throw new Error("receipt terms mismatch");
+  }
+  if (!/^[0-9]+$/.test(r.amount)) throw new Error("receipt amount must be an atomic integer string");
+  if (r.status === "confirmed" && (r.operation !== "settle" || !r.settlement?.id)) throw new Error("confirmation has no settlement");
+  return r;
+}
+function verifyFacilitatorReceipt(receipt, jwks, issuer = RECEIPT_ISSUER) {
+  try {
+    parseFacilitatorReceipt(receipt);
+    if (receipt.issuer !== issuer || receipt.proof?.type !== "jws" || !receipt.proof.jws) return false;
+    const parts = receipt.proof.jws.split(".");
+    if (parts.length !== 3) return false;
+    const [protectedHeader, payload, signature] = parts;
+    const header = JSON.parse(decoder.decode(decodeUrl64(protectedHeader)));
+    if (header.alg !== "EdDSA" || header.typ !== "uvd-facilitator-receipt+jws") return false;
+    const keys = jwks.keys.filter((k) => k.kid === header.kid && k.kty === "OKP" && k.crv === "Ed25519");
+    if (keys.length !== 1 || !keys[0].x) return false;
+    if (decoder.decode(decodeUrl64(payload)) !== canonicalReceiptJson({ ...receipt, proof: null })) return false;
+    return ed25519.ed25519.verify(decodeUrl64(signature), encoder.encode(`${protectedHeader}.${payload}`), decodeUrl64(keys[0].x));
+  } catch {
+    return false;
+  }
+}
+function createPurchaseContext() {
+  return { purchaseId: utils.bytesToHex(utils.randomBytes(16)), accessToken: utils.bytesToHex(utils.randomBytes(32)) };
+}
+function purchaseContextHeader(context) {
+  return encode64(encoder.encode(canonicalReceiptJson({
+    purchaseId: context.purchaseId,
+    accessToken: context.accessToken,
+    method: context.method,
+    url: context.url,
+    bodySha256: context.bodySha256
+  })));
+}
+function validatePurchaseContext(header, method, url, body) {
+  if (!header) return void 0;
+  if (header.length > 8192) throw new Error("invalid purchase context");
+  const context = JSON.parse(decoder.decode(decode64(header)));
+  if (typeof context.purchaseId !== "string" || !context.purchaseId || context.purchaseId.length > 128 || typeof context.accessToken !== "string" || !/^[0-9a-f]{64}$/.test(context.accessToken) || context.method !== method.toUpperCase() || context.url !== new URL(url).toString() || context.bodySha256 !== digest(body)) throw new Error("purchase context does not match the HTTP request");
+  return header;
+}
+function paymentResponseHeaders(result) {
+  const encoded = encode64(encoder.encode(JSON.stringify(result)));
+  if (encoded.length > 32768) throw new Error("payment response too large");
+  return {
+    "PAYMENT-RESPONSE": encoded,
+    "X-PAYMENT-RESPONSE": encoded,
+    "Access-Control-Expose-Headers": "PAYMENT-RESPONSE, X-PAYMENT-RESPONSE",
+    "Cache-Control": "no-store"
+  };
+}
+var LIST_HEADERS = ["Access-Control-Expose-Headers", "Cache-Control"];
+function mergeHeaderList(existing, additions) {
+  const name = (entry) => entry.split("=")[0].trim().toLowerCase();
+  const kept = (existing || "").split(",").map((entry) => entry.trim()).filter(Boolean);
+  const seen = new Set(kept.map(name));
+  for (const entry of additions.split(",").map((value) => value.trim()).filter(Boolean)) {
+    if (!seen.has(name(entry))) {
+      kept.push(entry);
+      seen.add(name(entry));
+    }
+  }
+  return kept.join(", ");
+}
+function mergePaymentResponseHeaders(result, current) {
+  const headers = paymentResponseHeaders(result);
+  for (const name of LIST_HEADERS) headers[name] = mergeHeaderList(current(name), headers[name]);
+  return headers;
+}
+function receiptFromResponse(response) {
+  const values = [response.headers.get("PAYMENT-RESPONSE"), response.headers.get("X-PAYMENT-RESPONSE")].filter((v) => v !== null);
+  if (!values.length) return null;
+  if (new Set(values).size !== 1 || values[0].includes(",") || values[0].length > 32768) throw new Error("ambiguous or oversized payment response header");
+  return parseFacilitatorReceipt(JSON.parse(decoder.decode(decode64(values[0]))).receipt);
+}
+function receiptFromErrorBody(body) {
+  try {
+    return parseFacilitatorReceipt(JSON.parse(body).receipt);
+  } catch {
+    return null;
+  }
+}
+async function fetchWithReceipt(fetchClient, url, options) {
+  const { context, persist, trustedKeys, issuer = RECEIPT_ISSUER } = options;
+  const transport = options.fetchImpl || globalThis.fetch;
+  const method = (options.method || "GET").toUpperCase();
+  const request = new Request(url, { ...options.init, method });
+  const bytes = new Uint8Array(await request.arrayBuffer());
+  const bodyHash = digest(bytes);
+  if (context.method && (context.method !== method || context.url !== request.url || context.bodySha256 !== bodyHash)) throw new Error("purchase context cannot be reused for another HTTP request");
+  context.method = method;
+  context.url = request.url;
+  context.bodySha256 = bodyHash;
+  const init = { ...options.init, method, headers: new Headers(request.headers), body: ["GET", "HEAD"].includes(method) ? void 0 : bytes };
+  let receipt = parseFacilitatorReceipt(context.receipt);
+  let transportError;
+  const persistCopy = async () => {
+    await persist(JSON.parse(JSON.stringify(context)));
+  };
+  const send = async (input, sendOptions) => {
+    const headers = new Headers(sendOptions?.headers);
+    const paid = headers.get("X-PAYMENT") || headers.get("PAYMENT-SIGNATURE");
+    if (paid) {
+      const paymentHeaders = {};
+      for (const name of ["X-PAYMENT", "PAYMENT-SIGNATURE"]) {
+        const value = headers.get(name);
+        if (value) paymentHeaders[name] = value;
+      }
+      if (context.paymentHeaders && JSON.stringify(context.paymentHeaders) !== JSON.stringify(paymentHeaders)) throw new Error("refusing a new authorization for an existing purchase");
+      context.paymentHeaders = paymentHeaders;
+      headers.set("X-UVD-Purchase", purchaseContextHeader(context));
+      await persistCopy();
+    }
+    try {
+      return await transport(input, { ...sendOptions, headers });
+    } catch (error) {
+      transportError = error;
+      throw error;
+    }
+  };
+  try {
+    let response;
+    if (context.paymentHeaders) {
+      const headers = new Headers(init.headers);
+      for (const [name, value] of Object.entries(context.paymentHeaders)) headers.set(name, value);
+      response = await send(request.url, { ...init, headers });
+    } else {
+      response = await fetchClient(request.url, { ...options, method, init, fetchImpl: send });
+    }
+    const incoming = receiptFromResponse(response);
+    if (incoming) {
+      if (incoming.issuer !== issuer || Object.entries({ purchaseId: context.purchaseId, method, url: context.url, bodySha256: bodyHash }).some(([key, value]) => incoming.request[key] !== value)) throw new Error("receipt does not bind this purchase");
+      if (receipt?.operation === "settle" && (incoming.receiptId !== receipt.receiptId || incoming.revision < receipt.revision)) throw new Error("receipt revision conflict");
+      if (trustedKeys && !verifyFacilitatorReceipt(incoming, trustedKeys, issuer)) throw new Error("receipt signature verification failed");
+      receipt = incoming;
+      context.receipt = incoming;
+      await persistCopy();
+    }
+    const proofVerified = !!(receipt && trustedKeys && verifyFacilitatorReceipt(receipt, trustedKeys, issuer));
+    if (receipt && trustedKeys && !proofVerified) throw new Error("receipt signature verification failed");
+    return { response, receipt, paymentState: receipt ? receipt.status : context.paymentHeaders ? "unknown" : "not_required", context, proofVerified };
+  } catch (error) {
+    if (!transportError) throw error;
+    return { response: null, receipt, paymentState: "unknown", context, proofVerified: false, error };
+  }
+}
+async function getFacilitatorReceipt(receiptId, context, options = {}) {
+  if (!/^[0-9a-f-]{36}$/.test(receiptId)) throw new Error("invalid receipt ID");
+  const issuer = options.issuer || RECEIPT_ISSUER;
+  const response = await (options.fetchImpl || globalThis.fetch)(`${issuer}/receipts/${receiptId}`, { headers: { Authorization: `Bearer ${context.accessToken}` } });
+  if (!response.ok) throw new Error(`receipt lookup failed: ${response.status}`);
+  const receipt = parseFacilitatorReceipt((await response.json()).receipt);
+  if (!receipt || receipt.issuer !== issuer || receipt.purchaseId !== context.purchaseId) throw new Error("receipt lookup mismatch");
+  return receipt;
+}
 
 // src/utils/base64.ts
 function decodeBase64Utf8(encoded) {
@@ -809,7 +1011,8 @@ var SUPPORTED_CHAINS = {
   // Pinned by src/arc-testnet.test.ts.
   //
   // Mainnet (5042) and testnet (5042002) were verified independently against
-  // their official RPCs on 2026-09-16. EURC domains checked on 2026-09-17; live payments pending.
+  // their official RPCs on 2026-09-16. EURC domains checked on 2026-09-17; funded EURC payments settled on Arc mainnet on
+  // 2026-09-22 (x402 v1/v2, docs/networks/arc.md); testnet pending.
   arc: {
     chainId: 5042,
     chainIdHex: "0x13b2",
@@ -1524,6 +1727,9 @@ var REPLAYABLE_LEASE_REASONS = [
 ];
 var AMBIGUOUS_LEASE_REASONS = ["forward_failed"];
 var SETTLEMENT_UNCONFIRMED = "settlement_unconfirmed";
+var AUTHORIZATION_ALREADY_SETTLED = "authorization_already_settled";
+var AUTHORIZATION_IN_FLIGHT = "authorization_in_flight";
+var RECEIPT_REQUEST_CONFLICT = "receipt_request_conflict";
 var MAX_RETRY_AFTER_SECONDS = 15;
 var DEFAULT_RETRY_AFTER_SECONDS = 5;
 var DEFAULT_FACILITATOR_RETRIES = 2;
@@ -1584,6 +1790,12 @@ function isDeclaredUnretryable(parsed) {
 function isSettlementUnconfirmed(failure) {
   return failure.errorCode === SETTLEMENT_UNCONFIRMED;
 }
+function isAuthorizationAlreadyUsed(failure) {
+  return failure.errorCode === AUTHORIZATION_ALREADY_SETTLED || failure.errorCode === RECEIPT_REQUEST_CONFLICT;
+}
+function isAuthorizationInFlight(failure) {
+  return failure.errorCode === AUTHORIZATION_IN_FLIGHT;
+}
 async function readFacilitatorError(response) {
   let body = "";
   try {
@@ -1595,7 +1807,8 @@ async function readFacilitatorError(response) {
   const parsed = parseFacilitatorErrorBody(body);
   const reason = parsed.reason;
   const transportRetryable = status === 429 || status === 502 || status === 503 || status === 504;
-  const retryable = transportRetryable && !isDeclaredUnretryable(parsed);
+  const inFlight = status === 409 && parsed.errorCode === AUTHORIZATION_IN_FLIGHT;
+  const retryable = inFlight || transportRetryable && !isDeclaredUnretryable(parsed);
   const retryAfterSeconds = retryable ? parseRetryAfterSeconds(response) ?? DEFAULT_RETRY_AFTER_SECONDS : void 0;
   const safeToReplay = retryable && (status === 429 || status === 503 && isReplayableLeaseReason(reason));
   return {
@@ -1853,7 +2066,7 @@ function buildSettleRequestForVersion(paymentHeader, requirements, version) {
   return buildSettleRequest(paymentHeader, requirements);
 }
 var X402_CORS_HEADERS = {
-  "Access-Control-Allow-Headers": "Content-Type, X-PAYMENT, PAYMENT-SIGNATURE, Authorization",
+  "Access-Control-Allow-Headers": "Content-Type, X-PAYMENT, PAYMENT-SIGNATURE, X-UVD-Purchase, Authorization",
   "Access-Control-Expose-Headers": "X-PAYMENT-RESPONSE, PAYMENT-RESPONSE, PAYMENT-REQUIRED",
   "Access-Control-Allow-Methods": "GET, POST, OPTIONS"
 };
@@ -1862,7 +2075,8 @@ var X402_HEADER_NAMES = [
   "PAYMENT-SIGNATURE",
   "X-PAYMENT-RESPONSE",
   "PAYMENT-RESPONSE",
-  "PAYMENT-REQUIRED"
+  "PAYMENT-REQUIRED",
+  "X-UVD-Purchase"
 ];
 function getCorsHeaders(origin = "*") {
   return {
@@ -1870,6 +2084,78 @@ function getCorsHeaders(origin = "*") {
     ...X402_CORS_HEADERS
   };
 }
+var IDEMPOTENCY_KEY_HEADER = "Idempotency-Key";
+var IDEMPOTENT_REPLAYED_HEADER = "Idempotent-Replayed";
+function createIdempotencyKey() {
+  return `x402-${utils.bytesToHex(utils.randomBytes(32))}`;
+}
+function checkIdempotencyKey(key) {
+  if (typeof key !== "string" || !/^[\x21-\x7e]{1,255}$/.test(key) || key.startsWith("receipt:")) {
+    throw new Error('idempotencyKey must be 1-255 visible ASCII characters and must not start with "receipt:"');
+  }
+  return key;
+}
+function isReplayed(response) {
+  try {
+    return response?.headers?.get?.(IDEMPOTENT_REPLAYED_HEADER)?.trim().toLowerCase() === "true";
+  } catch {
+    return false;
+  }
+}
+function refuseUnboundReplay(result) {
+  if (!result.replayed) return result;
+  const pending = result.receipt?.status === "pending" || result.receipt?.status === "unknown" || result.errorCode === "settlement_in_progress";
+  if (!result.success && !pending) return result;
+  const {
+    transactionHash: _tx,
+    proofOfPayment: _proof,
+    paymentId: _id,
+    transaction: _t,
+    retryAfterSeconds,
+    ...rest
+  } = result;
+  if (result.success) {
+    return {
+      ...rest,
+      success: false,
+      error: AUTHORIZATION_ALREADY_SETTLED,
+      errorCode: AUTHORIZATION_ALREADY_SETTLED,
+      retryable: false,
+      safeToReplay: false
+    };
+  }
+  return {
+    ...rest,
+    success: false,
+    error: AUTHORIZATION_IN_FLIGHT,
+    errorCode: AUTHORIZATION_IN_FLIGHT,
+    retryable: true,
+    safeToReplay: false,
+    retryAfterSeconds: retryAfterSeconds ?? DEFAULT_RETRY_AFTER_SECONDS
+  };
+}
+function facilitatorHeaders(idempotencyKey, receiptContext) {
+  return {
+    "Content-Type": "application/json",
+    [IDEMPOTENCY_KEY_HEADER]: idempotencyKey,
+    ...receiptContext ? { "X-UVD-Purchase": receiptContext } : {}
+  };
+}
+function admittedVerdict(result) {
+  if (result.isValid !== false) return {};
+  if (result.invalidReason === AUTHORIZATION_IN_FLIGHT) {
+    return {
+      errorCode: AUTHORIZATION_IN_FLIGHT,
+      retryable: true,
+      safeToReplay: false,
+      retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS
+    };
+  }
+  if (result.invalidReason === AUTHORIZATION_ALREADY_SETTLED) {
+    return { errorCode: AUTHORIZATION_ALREADY_SETTLED, retryable: false, safeToReplay: false };
+  }
+  return {};
+}
 var FacilitatorClient = class {
   baseUrl;
   timeout;
@@ -1902,11 +2188,19 @@ var FacilitatorClient = class {
    *
    * Call this before providing the paid resource to validate the payment.
    *
+   * An authorization the facilitator already admitted for another request
+   * comes back invalid with `errorCode` {@link AUTHORIZATION_ALREADY_SETTLED}
+   * (do not serve, do not ask for a new signature) or
+   * {@link AUTHORIZATION_IN_FLIGHT} (`retryable`: the same request learns the
+   * verdict later). Neither is a rejected payment: never answer them with 402.
+   *
    * @param paymentHeader - Parsed x402 payment header
    * @param requirements - Payment requirements
+   * @param options - Purchase context and the payment's `idempotencyKey`
    * @returns Verification result
    */
-  async verify(paymentHeader, requirements) {
+  async verify(paymentHeader, requirements, options = {}) {
+    const idempotencyKey = checkIdempotencyKey(options.idempotencyKey ?? createIdempotencyKey());
     const body = buildVerifyRequestForVersion(
       paymentHeader,
       requirements,
@@ -1917,7 +2211,7 @@ var FacilitatorClient = class {
         `${this.baseUrl}/verify`,
         {
           method: "POST",
-          headers: { "Content-Type": "application/json" },
+          headers: facilitatorHeaders(idempotencyKey, options.receiptContext),
           body: JSON.stringify(body)
         },
         { timeoutMs: this.timeout, retries: this.retries }
@@ -1926,17 +2220,21 @@ var FacilitatorClient = class {
         return {
           isValid: false,
           invalidReason: error.error,
-          ...failureFields(error)
+          ...failureFields(error),
+          receipt: receiptFromErrorBody(error.body),
+          idempotencyKey
         };
       }
-      return await response.json();
+      const result = await response.json();
+      return { ...result, ...admittedVerdict(result), receipt: parseFacilitatorReceipt(result.receipt), idempotencyKey };
     } catch (error) {
       return {
         isValid: false,
         invalidReason: error instanceof Error ? error.message : "Unknown error",
         retryable: true,
         safeToReplay: false,
-        retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS
+        retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS,
+        idempotencyKey
       };
     }
   }
@@ -1945,11 +2243,23 @@ var FacilitatorClient = class {
    *
    * Call this after providing the paid resource to execute the on-chain transfer.
    *
+   * Send the `idempotencyKey` the payment was verified with, and the same one
+   * on any retry: it is the binding that earns the original answer back after
+   * a lost response (`replayed: true`). Without it, or with another one, an
+   * authorization already admitted comes back `409`
+   * {@link AUTHORIZATION_ALREADY_SETTLED}, {@link AUTHORIZATION_IN_FLIGHT} or
+   * {@link RECEIPT_REQUEST_CONFLICT} -- the X-PAYMENT was used; do not serve it
+   * again. With no key and no context the call uses a fresh key, so a replay
+   * it receives is refused the same way.
+   *
    * @param paymentHeader - Parsed x402 payment header
    * @param requirements - Payment requirements
+   * @param options - Purchase context and the payment's `idempotencyKey`
    * @returns Settlement result with transaction hash
    */
-  async settle(paymentHeader, requirements) {
+  async settle(paymentHeader, requirements, options = {}) {
+    const unbound = options.idempotencyKey === void 0 && !options.receiptContext;
+    const idempotencyKey = checkIdempotencyKey(options.idempotencyKey ?? createIdempotencyKey());
     const body = buildSettleRequestForVersion(
       paymentHeader,
       requirements,
@@ -1961,7 +2271,8 @@ var FacilitatorClient = class {
         `${this.baseUrl}/settle`,
         {
           method: "POST",
-          headers: { "Content-Type": "application/json" },
+          // The same init, key included, goes out on every automatic retry.
+          headers: facilitatorHeaders(idempotencyKey, options.receiptContext),
           body: JSON.stringify(body)
         },
         { timeoutMs: settleTimeout, retries: this.retries }
@@ -1970,7 +2281,9 @@ var FacilitatorClient = class {
         return {
           success: false,
           error: error.error,
-          ...failureFields(error)
+          ...failureFields(error),
+          receipt: receiptFromErrorBody(error.body),
+          idempotencyKey
         };
       }
       const result = await response.json();
@@ -1980,7 +2293,7 @@ var FacilitatorClient = class {
           "[x402] settle reported success but carried no transaction hash under transaction/transactionHash/transaction_hash \u2014 treat delivery as unconfirmed"
         );
       }
-      return {
+      const settled = {
         // Read the facilitator's verdict instead of asserting one.
         //
         // This was the literal `true`, so a settle was reported successful
@@ -2008,15 +2321,24 @@ var FacilitatorClient = class {
         // facilitator returns it, and this method threw it away — so a seller
         // using the SDK end to end could only ever produce provisional anchors.
         proofOfPayment: result.proofOfPayment ?? result.proof_of_payment,
-        payer: result.payer
+        payer: result.payer,
+        receipt: parseFacilitatorReceipt(result.receipt),
+        paymentId: result.paymentId,
+        ...result.receipt?.status === "unknown" || result.receipt?.status === "pending" ? { retryable: true, safeToReplay: false } : {},
+        // `202 settlement_in_progress` and friends: a 2xx that names its state.
+        ...!result.success && typeof result.error === "string" && result.error ? { errorCode: result.error } : {},
+        ...isReplayed(response) ? { replayed: true } : {},
+        idempotencyKey
       };
+      return unbound ? refuseUnboundReplay(settled) : settled;
     } catch (error) {
       return {
         success: false,
         error: error instanceof Error ? error.message : "Unknown error",
         retryable: true,
         safeToReplay: false,
-        retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS
+        retryAfterSeconds: DEFAULT_RETRY_AFTER_SECONDS,
+        idempotencyKey
       };
     }
   }
@@ -2026,27 +2348,41 @@ var FacilitatorClient = class {
    * Convenience method that verifies first, then settles if valid.
    * Use this for simple payment flows where you don't need custom logic between verify and settle.
    *
+   * Both steps carry ONE `Idempotency-Key` (`options.idempotencyKey`, or a
+   * fresh one reported back as `idempotencyKey`). With a fresh key and no
+   * purchase context, a replay of an earlier settle is not this purchase and
+   * comes back `settled: false` with `errorCode`
+   * {@link AUTHORIZATION_ALREADY_SETTLED}.
+   *
    * @param paymentHeader - Parsed x402 payment header
    * @param requirements - Payment requirements
+   * @param options - Purchase context and the payment's `idempotencyKey`
    * @returns Combined result with verify and settle status
    */
-  async verifyAndSettle(paymentHeader, requirements) {
-    const verifyResult = await this.verify(paymentHeader, requirements);
+  async verifyAndSettle(paymentHeader, requirements, options = {}) {
+    const unbound = options.idempotencyKey === void 0 && !options.receiptContext;
+    const binding = { ...options, idempotencyKey: checkIdempotencyKey(options.idempotencyKey ?? createIdempotencyKey()) };
+    const { idempotencyKey } = binding;
+    const verifyResult = await this.verify(paymentHeader, requirements, binding);
     if (!verifyResult.isValid) {
       return {
         verified: false,
         settled: false,
         error: verifyResult.invalidReason,
-        ...carryFailureFields(verifyResult)
+        ...carryFailureFields(verifyResult),
+        idempotencyKey
       };
     }
-    const settleResult = await this.settle(paymentHeader, requirements);
+    const answered = await this.settle(paymentHeader, requirements, binding);
+    const settleResult = unbound ? refuseUnboundReplay(answered) : answered;
     return {
       verified: true,
       settled: settleResult.success,
       transactionHash: settleResult.transactionHash,
       error: settleResult.error,
-      ...carryFailureFields(settleResult)
+      ...carryFailureFields(settleResult),
+      ...settleResult.replayed ? { replayed: true } : {},
+      idempotencyKey
     };
   }
   /**
@@ -2434,20 +2770,51 @@ async function resolvePaymentRequirement(payment, requirements, resolver) {
   }
   return { requirement: matches[0] };
 }
-function createVerifiedPaymentState(client, payment, requirements, verifyResult) {
+function createVerifiedPaymentState(client, payment, requirements, verifyResult, binding, onSettled) {
   let settlePromise = null;
   return {
     payment,
     requirements,
     verifyResult,
+    idempotencyKey: binding.idempotencyKey,
     settle: () => {
       if (!settlePromise) {
-        settlePromise = client.settle(payment, requirements);
+        settlePromise = client.settle(payment, requirements, binding).then((answer) => {
+          const result = binding.receiptContext ? answer : refuseUnboundReplay(answer);
+          try {
+            onSettled?.(result);
+          } catch (error) {
+            console.warn("[x402] settled, but the payment response headers could not be attached:", error);
+          }
+          return result;
+        });
       }
       return settlePromise;
     }
   };
 }
+function propagatedResult(result) {
+  const { idempotencyKey: _key, ...propagated } = result;
+  return propagated;
+}
+function buildPaymentConflictResponse(failure) {
+  if (isAuthorizationInFlight(failure)) {
+    const { headers, body } = buildUnavailableResponse("Payment authorization in flight", failure);
+    return { status: 503, headers, body: { ...body, reason: AUTHORIZATION_IN_FLIGHT } };
+  }
+  const used = isAuthorizationAlreadyUsed(failure);
+  if (!used && failure.status !== 409) return null;
+  return {
+    status: 409,
+    headers: {},
+    body: {
+      error: used ? "Payment authorization already used" : "Payment request conflict",
+      reason: failure.errorCode ?? failure.invalidReason ?? failure.error,
+      retryable: false,
+      safeToReplay: false
+    }
+  };
+}
 function buildUnavailableResponse(message, failure) {
   const seconds = Math.max(1, Math.ceil(failure.retryAfterSeconds ?? DEFAULT_RETRY_AFTER_SECONDS));
   return {
@@ -2464,14 +2831,25 @@ function buildUnavailableResponse(message, failure) {
   };
 }
 function respondUnavailable(res, message, failure) {
-  const { status, headers, body } = buildUnavailableResponse(message, failure);
+  respondExpress(res, buildUnavailableResponse(message, failure));
+}
+function respondExpress(res, { status, headers, body }) {
   const staged = res.status(status);
-  if (typeof staged.set === "function") {
+  if (Object.keys(headers).length > 0 && typeof staged.set === "function") {
     staged.set(headers).json(body);
     return;
   }
   staged.json(body);
 }
+function setExpressPaymentHeaders(res, result) {
+  if (!result.receipt || !res.set || res.headersSent) return;
+  const current = (name) => {
+    const value = res.getHeader ? res.getHeader(name) : res.get?.(name);
+    if (value === void 0 || value === null) return void 0;
+    return Array.isArray(value) ? value.join(", ") : String(value);
+  };
+  res.set(mergePaymentResponseHeaders(propagatedResult(result), current));
+}
 function createPaymentMiddleware(getRequirements, options = {}) {
   const client = new FacilitatorClient({
     baseUrl: options.facilitatorUrl || options.baseUrl,
@@ -2489,8 +2867,28 @@ function createPaymentMiddleware(getRequirements, options = {}) {
     }
     const reqOptions = getRequirements(req);
     const requirements = buildPaymentRequirements(reqOptions);
-    const verifyResult = await client.verify(payment, requirements);
+    let receiptContext;
+    try {
+      const entry = Object.entries(req.headers).find(([name]) => name.toLowerCase() === "x-uvd-purchase")?.[1];
+      if (entry !== void 0) {
+        if (typeof entry !== "string" || !req.method || !["GET", "HEAD"].includes(req.method.toUpperCase()) && !req.rawBody) throw new Error("receipt context requires method and exact raw body");
+        const actualUrl = new URL(req.originalUrl || req.url || reqOptions.resource, reqOptions.resource).toString();
+        receiptContext = validatePurchaseContext(entry, req.method, actualUrl, req.rawBody || new Uint8Array());
+        requirements.resource = actualUrl;
+      }
+    } catch {
+      res.status(400).json({ error: "receipt_context_mismatch" });
+      return;
+    }
+    const binding = { idempotencyKey: createIdempotencyKey(), receiptContext };
+    const verifyResult = await client.verify(payment, requirements, binding);
+    setExpressPaymentHeaders(res, verifyResult);
     if (!verifyResult.isValid) {
+      const conflict = buildPaymentConflictResponse(verifyResult);
+      if (conflict) {
+        respondExpress(res, conflict);
+        return;
+      }
       if (verifyResult.retryable) {
         respondUnavailable(res, "Payment verification unavailable", verifyResult);
         return;
@@ -2501,10 +2899,22 @@ function createPaymentMiddleware(getRequirements, options = {}) {
       });
       return;
     }
-    req.x402 = createVerifiedPaymentState(client, payment, requirements, verifyResult);
+    req.x402 = createVerifiedPaymentState(
+      client,
+      payment,
+      requirements,
+      verifyResult,
+      binding,
+      (result) => setExpressPaymentHeaders(res, result)
+    );
     if (settlementStrategy === "before-handler") {
       const settleResult = await req.x402.settle();
       if (!settleResult.success) {
+        const conflict = buildPaymentConflictResponse(settleResult);
+        if (conflict) {
+          respondExpress(res, conflict);
+          return;
+        }
         if (settleResult.retryable) {
           respondUnavailable(res, "Payment settlement unavailable", settleResult);
           return;
@@ -2527,12 +2937,21 @@ function settlementFailureBody(failure, fallbackReason) {
   };
 }
 function honoUnavailable(c, message, failure) {
-  const { status, headers, body } = buildUnavailableResponse(message, failure);
+  return respondHono(c, buildUnavailableResponse(message, failure));
+}
+function respondHono(c, { status, headers, body }) {
   for (const [name, value] of Object.entries(headers)) {
     c.header?.(name, value);
   }
   return c.json(body, status);
 }
+function setHonoPaymentHeaders(c, result) {
+  if (!result.receipt || !c.header || c.finalized) return;
+  const current = (name) => c.res?.headers.get(name) ?? void 0;
+  for (const [name, value] of Object.entries(mergePaymentResponseHeaders(propagatedResult(result), current))) {
+    c.header(name, value);
+  }
+}
 function createHonoMiddleware(options) {
   const client = new FacilitatorClient({
     baseUrl: options.facilitatorUrl || options.baseUrl,
@@ -2544,7 +2963,7 @@ function createHonoMiddleware(options) {
     throw new Error("At least one accept entry is required");
   }
   return async (c, next) => {
-    const paymentHeader = c.req.header("X-PAYMENT") || c.req.header("x-payment");
+    const paymentHeader = c.req.header("PAYMENT-SIGNATURE") || c.req.header("X-PAYMENT") || c.req.header("x-payment");
     const advertisedVersion = resolveAdvertisedVersion(options.accepts, options.x402Version);
     const advertisedRequirements = options.accepts.map(
       (accept) => buildRequirementFromAcceptance(accept, c.req.url, advertisedVersion)
@@ -2575,8 +2994,24 @@ function createHonoMiddleware(options) {
         reason
       }, 402);
     }
-    const verifyResult = await client.verify(parsed, requirement);
+    let receiptContext;
+    try {
+      const header = c.req.header("X-UVD-Purchase");
+      if (header) {
+        const method = c.req.method || c.req.raw?.method;
+        if (!method || !["GET", "HEAD"].includes(method) && !c.req.raw) throw new Error("raw request required");
+        const bytes = c.req.raw ? new Uint8Array(await c.req.raw.clone().arrayBuffer()) : new Uint8Array();
+        receiptContext = validatePurchaseContext(header, method, c.req.url, bytes);
+      }
+    } catch {
+      return c.json({ error: "receipt_context_mismatch" }, 400);
+    }
+    const binding = { idempotencyKey: createIdempotencyKey(), receiptContext };
+    const verifyResult = await client.verify(parsed, requirement, binding);
+    setHonoPaymentHeaders(c, verifyResult);
     if (!verifyResult.isValid) {
+      const conflict = buildPaymentConflictResponse(verifyResult);
+      if (conflict) return respondHono(c, conflict);
       if (verifyResult.retryable) {
         return honoUnavailable(c, "Payment verification unavailable", verifyResult);
       }
@@ -2585,11 +3020,20 @@ function createHonoMiddleware(options) {
         reason: verifyResult.invalidReason
       }, 402);
     }
-    const verifiedPayment = createVerifiedPaymentState(client, parsed, requirement, verifyResult);
+    const verifiedPayment = createVerifiedPaymentState(
+      client,
+      parsed,
+      requirement,
+      verifyResult,
+      binding,
+      (result) => setHonoPaymentHeaders(c, result)
+    );
     c.set?.("x402", verifiedPayment);
     if (settlementStrategy === "before-handler") {
       const settleResult = await verifiedPayment.settle();
       if (!settleResult.success) {
+        const conflict = buildPaymentConflictResponse(settleResult);
+        if (conflict) return respondHono(c, conflict);
         if (settleResult.retryable) {
           return honoUnavailable(c, "Payment settlement unavailable", settleResult);
         }
@@ -5481,6 +5925,8 @@ var AdvancedEscrowClient = class {
 };
 
 exports.AMBIGUOUS_LEASE_REASONS = AMBIGUOUS_LEASE_REASONS;
+exports.AUTHORIZATION_ALREADY_SETTLED = AUTHORIZATION_ALREADY_SETTLED;
+exports.AUTHORIZATION_IN_FLIGHT = AUTHORIZATION_IN_FLIGHT;
 exports.AdvancedEscrowClient = AdvancedEscrowClient;
 exports.BASE_MAINNET_CONTRACTS = BASE_MAINNET_CONTRACTS;
 exports.BazaarClient = BazaarClient;
@@ -5496,11 +5942,15 @@ exports.Erc8004LookupError = Erc8004LookupError;
 exports.EscrowClient = EscrowClient;
 exports.FacilitatorClient = FacilitatorClient;
 exports.HEALTH_FILTERS = HEALTH_FILTERS;
+exports.IDEMPOTENCY_KEY_HEADER = IDEMPOTENCY_KEY_HEADER;
+exports.IDEMPOTENT_REPLAYED_HEADER = IDEMPOTENT_REPLAYED_HEADER;
 exports.MAX_RETRY_AFTER_SECONDS = MAX_RETRY_AFTER_SECONDS;
 exports.MAX_SEARCH_LEN = MAX_SEARCH_LEN;
 exports.OPERATOR_ABI = OPERATOR_ABI;
 exports.OPERATOR_ABI_CREATE3 = OPERATOR_ABI_CREATE3;
 exports.PAYMENT_INFO_TYPEHASH = PAYMENT_INFO_TYPEHASH;
+exports.RECEIPT_ISSUER = RECEIPT_ISSUER;
+exports.RECEIPT_REQUEST_CONFLICT = RECEIPT_REQUEST_CONFLICT;
 exports.RELAYED_FEEDBACK_NETWORKS = RELAYED_FEEDBACK_NETWORKS;
 exports.REPLAYABLE_LEASE_REASONS = REPLAYABLE_LEASE_REASONS;
 exports.RegistrationPendingError = RegistrationPendingError;
@@ -5514,6 +5964,7 @@ exports.X402_CORS_HEADERS = X402_CORS_HEADERS;
 exports.X402_HEADER_NAMES = X402_HEADER_NAMES;
 exports.ZERO_ADDRESS = ZERO_ADDRESS;
 exports.buildErc8004PaymentRequirements = buildErc8004PaymentRequirements;
+exports.buildPaymentConflictResponse = buildPaymentConflictResponse;
 exports.buildPaymentRequirements = buildPaymentRequirements;
 exports.buildSettleRequest = buildSettleRequest;
 exports.buildSettleRequestForVersion = buildSettleRequestForVersion;
@@ -5524,33 +5975,50 @@ exports.buildVerifyRequestForVersion = buildVerifyRequestForVersion;
 exports.buildVerifyRequestV2 = buildVerifyRequestV2;
 exports.canRefundEscrow = canRefundEscrow;
 exports.canReleaseEscrow = canReleaseEscrow;
+exports.canonicalReceiptJson = canonicalReceiptJson;
 exports.carryFailureFields = carryFailureFields;
 exports.create402Response = create402Response;
 exports.createHonoMiddleware = createHonoMiddleware;
+exports.createIdempotencyKey = createIdempotencyKey;
 exports.createPaymentMiddleware = createPaymentMiddleware;
+exports.createPurchaseContext = createPurchaseContext;
 exports.epochToDate = epochToDate;
 exports.escrowTimeRemaining = escrowTimeRemaining;
 exports.extractPaymentFromHeaders = extractPaymentFromHeaders;
 exports.facilitatorFetch = facilitatorFetch;
+exports.fetchWithReceipt = fetchWithReceipt;
 exports.getCorsHeaders = getCorsHeaders;
 exports.getEscrowContractsByChainId = getEscrowContractsByChainId;
 exports.getEscrowSupportedChainIds = getEscrowSupportedChainIds;
+exports.getFacilitatorReceipt = getFacilitatorReceipt;
 exports.isAlive = isAlive;
 exports.isAmbiguousLeaseReason = isAmbiguousLeaseReason;
+exports.isAuthorizationAlreadyUsed = isAuthorizationAlreadyUsed;
+exports.isAuthorizationInFlight = isAuthorizationInFlight;
 exports.isEscrowExpired = isEscrowExpired;
 exports.isEscrowSupportedOnChain = isEscrowSupportedOnChain;
 exports.isRegisterJobTerminal = isRegisterJobTerminal;
 exports.isReplayableLeaseReason = isReplayableLeaseReason;
 exports.isSettlementUnconfirmed = isSettlementUnconfirmed;
+exports.mergeHeaderList = mergeHeaderList;
+exports.mergePaymentResponseHeaders = mergePaymentResponseHeaders;
 exports.parseFacilitatorErrorBody = parseFacilitatorErrorBody;
+exports.parseFacilitatorReceipt = parseFacilitatorReceipt;
 exports.parsePaymentHeader = parsePaymentHeader;
 exports.parseRetryAfterSeconds = parseRetryAfterSeconds;
+exports.paymentResponseHeaders = paymentResponseHeaders;
+exports.purchaseContextHeader = purchaseContextHeader;
 exports.readFacilitatorError = readFacilitatorError;
+exports.receiptCommitment = receiptCommitment;
+exports.receiptFromErrorBody = receiptFromErrorBody;
+exports.receiptFromResponse = receiptFromResponse;
 exports.resolveEnvelopeVersion = resolveEnvelopeVersion;
 exports.supportsRelayedFeedback = supportsRelayedFeedback;
 exports.supportsSolanaFeedback = supportsSolanaFeedback;
 exports.toPaymentRequirementsV2 = toPaymentRequirementsV2;
 exports.toResourceInfoV2 = toResourceInfoV2;
+exports.validatePurchaseContext = validatePurchaseContext;
+exports.verifyFacilitatorReceipt = verifyFacilitatorReceipt;
 exports.wireNetwork = wireNetwork;
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map