@devlab.group/agent-commerce 1.4.0 → 1.5.0

package/dist/index.js

@@ -1,7 +1,8 @@
-import { AP2_SPEC_VERSION, AP2_MODES, AP2_DEFAULT_CLOCK_SKEW_SECONDS, AP2_JWK_MEMBERS, AP2_KEY_TYPE, AP2_SIGNING_ALGORITHM, AP2_JWK_CURVE, AP2_JWK_COORDINATE_BYTES, openSqliteDatabase, AP2_MAX_CLOCK_SKEW_SECONDS } from './chunk-7NKWFGBY.js';
-import { resolveX402Deployment, resolveDeploymentMode, requireNetworkProfile } from './chunk-IUR3Q7DE.js';
-import { RESERVED_INPUT_FIELDS, PROTOCOL_NAMES, PAYMENT_HEADER, AUTHORIZATION_HEADER, CommerceError, systemClock, NOOP_LOGGER, PACKAGE_VERSION, toCommerceError, DEFAULT_BACKEND_TIMEOUT_MS, toErrorEnvelope, isHttpProtocolAdapter, isCommerceError, parseAuthorizationHeader, toPaymentRequiredEnvelope, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER } from './chunk-ZDVJ7EVL.js';
-export { AUTHORIZATION_HEADER, AUTHORIZATION_INPUT_FIELD, COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, COMMERCE_EVENT_TYPES, CommerceError, DEFAULT_BACKEND_TIMEOUT_MS, DELIVERY_SUMMARY_META_KEY, MAX_AUTHORIZATION_HEADER_BYTES, NOOP_LOGGER, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PROTOCOL_NAMES, RESERVED_INPUT_FIELDS, RETRYABLE_ERROR_CODES, extractReservedInputFields, isCommerceError, isHttpProtocolAdapter, isPaymentRequiredEnvelope, parseAuthorizationHeader, parseAuthorizationSubmission, systemClock, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope } from './chunk-ZDVJ7EVL.js';
+import { AP2_SPEC_VERSION, AP2_MODES, AP2_DEFAULT_CLOCK_SKEW_SECONDS, AP2_JWK_MEMBERS, AP2_KEY_TYPE, AP2_SIGNING_ALGORITHM, AP2_JWK_CURVE, AP2_JWK_COORDINATE_BYTES, openSqliteDatabase, AP2_MAX_CLOCK_SKEW_SECONDS } from './chunk-US622BKF.js';
+import { MPP_DEFAULT_NETWORK, isMppNetwork, MPP_NETWORKS, MPP_MIN_CHALLENGE_SECRET_LENGTH, MPP_PROFILE } from './chunk-6D2EZ5ME.js';
+import { resolveX402Deployment, resolveDeploymentMode, requireNetworkProfile } from './chunk-PBYN7EK2.js';
+import { RESERVED_INPUT_FIELDS, PROTOCOL_NAMES, PAYMENT_METHOD_NAMES, PAYMENT_HEADER, AUTHORIZATION_HEADER, CommerceError, systemClock, NOOP_LOGGER, PACKAGE_VERSION, toCommerceError, DEFAULT_BACKEND_TIMEOUT_MS, toErrorEnvelope, isHttpProtocolAdapter, isCommerceError, parseAuthorizationHeader, toPaymentRequiredEnvelope, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER } from './chunk-5GEWKNIH.js';
+export { AUTHORIZATION_HEADER, AUTHORIZATION_INPUT_FIELD, COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, COMMERCE_EVENT_TYPES, CommerceError, DEFAULT_BACKEND_TIMEOUT_MS, DELIVERY_SUMMARY_META_KEY, MAX_AUTHORIZATION_HEADER_BYTES, NOOP_LOGGER, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_METHOD_NAMES, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PROTOCOL_NAMES, RESERVED_INPUT_FIELDS, RETRYABLE_ERROR_CODES, extractReservedInputFields, isCommerceError, isHttpProtocolAdapter, isPaymentRequiredEnvelope, parseAuthorizationHeader, parseAuthorizationSubmission, systemClock, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope } from './chunk-5GEWKNIH.js';
 import { promises, accessSync, constants } from 'fs';
 import * as path from 'path';
 import { parse, YAMLError } from 'yaml';
@@ -85,6 +86,7 @@ var DEFAULT_CONFIG_FILENAME = "config.yaml";
 
 // src/core/execution/backend-http.ts
 var MAX_BODY_SNIPPET_LENGTH = 512;
+var IDEMPOTENCY_KEY_HEADER = "idempotency-key";
 var PATH_PARAM_PATTERN = /\{([a-zA-Z0-9_.-]+)\}/g;
 var MAX_RESPONSE_BODY_BYTES = 1024 * 1024;
 var HttpBackendExecutor = class {
@@ -126,6 +128,10 @@ var HttpBackendExecutor = class {
       if (error instanceof CommerceError) throw error;
     }
     const headers = { ...handler.headers ?? {} };
+    if (request.idempotencyKey !== void 0) {
+      deleteHeader(headers, IDEMPOTENCY_KEY_HEADER);
+      headers[IDEMPOTENCY_KEY_HEADER] = request.idempotencyKey;
+    }
     let body;
     checkQueryCollision(target, parts.query, context);
     for (const [key, value] of Object.entries(parts.query)) {
@@ -334,6 +340,12 @@ function hasHeader(headers, name) {
   const target = name.toLowerCase();
   return Object.keys(headers).some((key) => key.toLowerCase() === target);
 }
+function deleteHeader(headers, name) {
+  const target = name.toLowerCase();
+  for (const key of Object.keys(headers)) {
+    if (key.toLowerCase() === target) delete headers[key];
+  }
+}
 function headersToRecord(headers) {
   const record = {};
   headers.forEach((value, key) => {
@@ -811,7 +823,8 @@ function createExecutionPipeline(options) {
         const mapped = isCommerceError(error) ? error : new CommerceError("PAYMENT_INVALID", "Payment verification failed", {
           requestId: request.requestId,
           resourceId: resource.id,
-          cause: error
+          cause: error,
+          ...retryChallenge(requirement)
         });
         await safeEmit(
           buildEvent({
@@ -843,7 +856,8 @@ function createExecutionPipeline(options) {
           verification.rejectionReason ?? "Payment was rejected",
           {
             requestId: request.requestId,
-            resourceId: resource.id
+            resourceId: resource.id,
+            ...retryChallenge(requirement)
           }
         );
       }
@@ -924,17 +938,16 @@ function createExecutionPipeline(options) {
           verification
         });
       } catch (error) {
-        const uncertainTxHash = uncertainSettlementTxHash(error);
-        await hold?.finalize(uncertainTxHash !== void 0 ? "markUncertain" : "release");
+        const txHash = settlementTxHash(error);
+        await hold?.finalize("markUncertain");
         await safePersist(
-          () => options.store.updatePaymentAttempt(
-            uncertainTxHash !== void 0 ? { replayKey, status: "settlement-uncertain", externalReference: uncertainTxHash } : {
-              replayKey,
-              status: "failed",
-              ...error instanceof Error ? { rejectionReason: error.message } : {}
-            }
-          ),
-          uncertainTxHash !== void 0 ? "updatePaymentAttempt(settlement-uncertain)" : "updatePaymentAttempt(failed)",
+          () => options.store.updatePaymentAttempt({
+            replayKey,
+            status: "settlement-uncertain",
+            ...txHash !== void 0 ? { externalReference: txHash } : {},
+            ...error instanceof Error ? { rejectionReason: error.message } : {}
+          }),
+          "updatePaymentAttempt(settlement-uncertain)",
           request.requestId
         );
         await safeEmit(
@@ -945,19 +958,21 @@ function createExecutionPipeline(options) {
             adapter: request.protocol,
             paymentProvider: provider.name,
             status: "error",
-            data: uncertainTxHash !== void 0 ? { reason: "settlement-uncertain", transactionHash: uncertainTxHash } : { reason: "settlement-threw" }
+            data: {
+              reason: "settlement-uncertain",
+              ...txHash !== void 0 ? { transactionHash: txHash } : {}
+            }
           })
         );
-        throw new CommerceError(
-          "PAYMENT_SETTLEMENT_FAILED",
-          uncertainTxHash !== void 0 ? "Settlement could not be confirmed" : "Payment settlement failed",
-          {
-            requestId: request.requestId,
-            resourceId: resource.id,
-            cause: error,
-            ...uncertainTxHash !== void 0 ? { details: { settlementUncertain: true, transactionHash: uncertainTxHash } } : {}
+        throw new CommerceError("PAYMENT_SETTLEMENT_FAILED", "Settlement could not be confirmed", {
+          requestId: request.requestId,
+          resourceId: resource.id,
+          cause: error,
+          details: {
+            settlementUncertain: true,
+            ...txHash !== void 0 ? { transactionHash: txHash } : {}
           }
-        );
+        });
       }
       if (settlement.status !== "settled") {
         await hold?.finalize("release");
@@ -1018,7 +1033,8 @@ function createExecutionPipeline(options) {
       backendResponse = await options.backend.call(resource.handler, {
         requestId: request.requestId,
         resourceId: resource.id,
-        input: validInput
+        input: validInput,
+        ...request.idempotencyKey !== void 0 ? { idempotencyKey: request.idempotencyKey } : {}
       });
     } catch (error) {
       const commerceError = toCommerceError(error, "BACKEND_ERROR", "Backend call failed");
@@ -1064,7 +1080,8 @@ function createExecutionPipeline(options) {
                 amount: paymentResult.amount,
                 currency: paymentResult.currency,
                 ...paymentResult.network !== void 0 ? { network: paymentResult.network } : {},
-                ...paymentResult.externalReference !== void 0 ? { externalReference: paymentResult.externalReference } : {}
+                ...paymentResult.externalReference !== void 0 ? { externalReference: paymentResult.externalReference } : {},
+                ...typeof paymentResult.metadata?.["receipt"] === "string" ? { receipt: paymentResult.metadata["receipt"] } : {}
               }
             }
           }
@@ -1124,9 +1141,8 @@ function backendErrorStatus(error) {
   const status = error.details?.["status"];
   return typeof status === "number" ? status : 0;
 }
-function uncertainSettlementTxHash(error) {
-  if (!isCommerceError(error) || error.code !== "PAYMENT_PROVIDER_UNAVAILABLE") return void 0;
-  const hash = error.details?.["transactionHash"];
+function settlementTxHash(error) {
+  const hash = isCommerceError(error) ? error.details?.["transactionHash"] : void 0;
   return typeof hash === "string" ? hash : void 0;
 }
 function resolveAuthorizationProviders(providers, resource, requestId) {
@@ -1143,6 +1159,10 @@ function resolveAuthorizationProviders(providers, resource, requestId) {
     return found;
   });
 }
+function retryChallenge(requirement) {
+  const envelope = requirement.challenge.envelope;
+  return envelope === void 0 ? {} : { details: { challenge: envelope } };
+}
 function pickProvider(providers, methods) {
   for (const method of methods) {
     const found = providers.find((provider) => provider.name === method);
@@ -1410,8 +1430,26 @@ var X402Schema = z.object({
   /** Accepts a mainnet facilitator that takes no credential. Never defaulted. */
   allowUnauthenticatedFacilitator: BooleanOrString.optional()
 }).strict();
+var MppSchema = z.object({
+  enabled: BooleanOrString,
+  network: z.string().min(1).optional(),
+  rpcUrl: z.string().min(1),
+  asset: z.string().min(1),
+  assetName: z.string().min(1),
+  assetVersion: z.string().min(1),
+  recipient: z.string().min(1),
+  realm: z.string().min(1),
+  challengeSecret: z.string().min(1),
+  challengeTtlSeconds: NumberOrString.optional(),
+  facilitator: FacilitatorSchema,
+  // Real funds. Never defaulted - see src/payments/x402/guardrails.ts
+  allowMainnet: BooleanOrString.optional(),
+  // Accepts a mainnet facilitator that takes no credential. Never defaulted
+  allowUnauthenticatedFacilitator: BooleanOrString.optional()
+}).strict();
 var PaymentsSchema = z.object({
-  x402: X402Schema.optional()
+  x402: X402Schema.optional(),
+  mpp: MppSchema.optional()
 }).strict();
 var Ap2KeySchema = z.object({
   kid: z.string().min(1),
@@ -1547,7 +1585,7 @@ function toBoolean(value, path2) {
   );
 }
 var SUPPORTED_PROTOCOLS = new Set(PROTOCOL_NAMES);
-var SUPPORTED_PAYMENT_METHODS = /* @__PURE__ */ new Set(["x402"]);
+var SUPPORTED_PAYMENT_METHODS = new Set(PAYMENT_METHOD_NAMES);
 var SUPPORTED_AUTHORIZATION_METHODS = /* @__PURE__ */ new Set(["ap2"]);
 function normalise(raw) {
   const protocols = {
@@ -1564,12 +1602,7 @@ function normalise(raw) {
   };
   validateMountPaths(protocols);
   const x402Raw = raw.payments.x402;
-  const facilitator = x402Raw === void 0 ? void 0 : x402Raw.facilitator.mode === "local" ? { mode: "local", signerPrivateKey: x402Raw.facilitator.signerPrivateKey } : {
-    mode: "remote",
-    url: x402Raw.facilitator.url,
-    auth: x402Raw.facilitator.auth ?? { type: "none" }
-  };
-  const x402 = x402Raw && facilitator ? {
+  const x402 = x402Raw !== void 0 ? {
     enabled: toBoolean(x402Raw.enabled, "payments.x402.enabled"),
     network: x402Raw.network,
     rpcUrl: x402Raw.rpcUrl,
@@ -1588,7 +1621,7 @@ function normalise(raw) {
         min: 1
       }
     ),
-    facilitator,
+    facilitator: normaliseFacilitator(x402Raw.facilitator),
     ...x402Raw.allowMainnet !== void 0 ? { allowMainnet: toBoolean(x402Raw.allowMainnet, "payments.x402.allowMainnet") } : {},
     ...x402Raw.allowUnauthenticatedFacilitator !== void 0 ? {
       allowUnauthenticatedFacilitator: toBoolean(
@@ -1611,12 +1644,13 @@ function normalise(raw) {
       ...x402.allowUnauthenticatedFacilitator !== void 0 ? { allowUnauthenticatedFacilitator: x402.allowUnauthenticatedFacilitator } : {}
     });
   }
+  const mpp = normaliseMpp(raw.payments.mpp);
   const ap2 = normaliseAp2(raw.authorization?.ap2);
   if (ap2?.enabled) {
     validateReplayStoreIsolated(ap2.replay.path, raw.storage.receipts.path, protocols.acp);
   }
   const resources = Object.entries(raw.resources).map(
-    ([id, entry]) => normaliseResource(id, entry, protocols, x402, ap2)
+    ([id, entry]) => normaliseResource(id, entry, protocols, x402, mpp, ap2)
   );
   if (protocols.acp.enabled) validateAcpCheckoutMapping(protocols.acp, resources);
   return {
@@ -1638,7 +1672,8 @@ function normalise(raw) {
     protocols,
     resources,
     payments: {
-      ...x402 !== void 0 ? { x402 } : {}
+      ...x402 !== void 0 ? { x402 } : {},
+      ...mpp !== void 0 ? { mpp } : {}
     },
     ...ap2 !== void 0 ? { authorization: { ap2 } } : {}
   };
@@ -1990,7 +2025,74 @@ function validateAcpOperationInput(path2, operation, resource) {
     }
   }
 }
-function normaliseResource(id, entry, protocols, x402, ap2) {
+function normaliseFacilitator(raw) {
+  return raw.mode === "local" ? { mode: "local", signerPrivateKey: raw.signerPrivateKey } : { mode: "remote", url: raw.url, auth: raw.auth ?? { type: "none" } };
+}
+function normaliseMpp(raw) {
+  if (raw === void 0) return void 0;
+  const network = raw.network ?? MPP_DEFAULT_NETWORK;
+  if (!isMppNetwork(network)) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `payments.mpp.network must be one of ${MPP_NETWORKS.join(", ")}`,
+      { details: { path: "payments.mpp.network" } }
+    );
+  }
+  const mpp = {
+    enabled: toBoolean(raw.enabled, "payments.mpp.enabled"),
+    network,
+    rpcUrl: raw.rpcUrl,
+    asset: raw.asset,
+    assetName: raw.assetName,
+    assetVersion: raw.assetVersion,
+    recipient: raw.recipient,
+    realm: raw.realm,
+    challengeSecret: raw.challengeSecret,
+    ...raw.challengeTtlSeconds !== void 0 ? {
+      challengeTtlSeconds: toNumber(
+        raw.challengeTtlSeconds,
+        "payments.mpp.challengeTtlSeconds",
+        { min: 1 }
+      )
+    } : {},
+    facilitator: normaliseFacilitator(raw.facilitator),
+    ...raw.allowMainnet !== void 0 ? { allowMainnet: toBoolean(raw.allowMainnet, "payments.mpp.allowMainnet") } : {},
+    ...raw.allowUnauthenticatedFacilitator !== void 0 ? {
+      allowUnauthenticatedFacilitator: toBoolean(
+        raw.allowUnauthenticatedFacilitator,
+        "payments.mpp.allowUnauthenticatedFacilitator"
+      )
+    } : {}
+  };
+  validateAddress("payments.mpp.recipient", mpp.recipient);
+  validateAddress("payments.mpp.asset", mpp.asset);
+  if (/[\r\n]/.test(mpp.realm)) {
+    throw new CommerceError("CONFIG_INVALID", "payments.mpp.realm must be a single line", {
+      details: { path: "payments.mpp.realm" }
+    });
+  }
+  if (mpp.challengeSecret.length < MPP_MIN_CHALLENGE_SECRET_LENGTH) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `payments.mpp.challengeSecret must have length at least ${MPP_MIN_CHALLENGE_SECRET_LENGTH}`,
+      { details: { path: "payments.mpp.challengeSecret" } }
+    );
+  }
+  resolveX402Deployment({
+    network: mpp.network,
+    payTo: mpp.recipient,
+    asset: mpp.asset,
+    assetName: mpp.assetName,
+    assetVersion: mpp.assetVersion,
+    facilitator: mpp.facilitator,
+    ...mpp.allowMainnet !== void 0 ? { allowMainnet: mpp.allowMainnet } : {},
+    ...mpp.allowUnauthenticatedFacilitator !== void 0 ? { allowUnauthenticatedFacilitator: mpp.allowUnauthenticatedFacilitator } : {},
+    configPath: "payments.mpp",
+    payToField: "recipient"
+  });
+  return mpp;
+}
+function normaliseResource(id, entry, protocols, x402, mpp, ap2) {
   if (entry.input !== void 0) validateResourceSchemaKeywords(id, "input", entry.input);
   const inputProperties = entry.input?.["properties"];
   if (inputProperties && typeof inputProperties === "object") {
@@ -2066,7 +2168,7 @@ function normaliseResource(id, entry, protocols, x402, ap2) {
     );
   }
   if (entry.pricing.type === "fixed") {
-    validatePricingAmount(id, entry.pricing.amount, x402);
+    validatePricingAmount(id, entry.pricing.amount, x402?.assetDecimals);
   }
   const paymentMethods = entry.payments ?? [];
   if (entry.pricing.type === "fixed") {
@@ -2081,17 +2183,28 @@ function normaliseResource(id, entry, protocols, x402, ap2) {
       if (!SUPPORTED_PAYMENT_METHODS.has(method)) {
         throw new CommerceError(
           "CONFIG_INVALID",
-          `Resource "${id}" names unsupported payment method "${method}". Supported: x402.`,
+          `Resource "${id}" names unsupported payment method "${method}". Supported: ${PAYMENT_METHOD_NAMES.join(", ")}.`,
           { details: { path: `resources.${id}.payments`, resourceId: id, method } }
         );
       }
-      if (method === "x402" && (!x402 || !x402.enabled)) {
+    }
+    const enabledRails = [...x402?.enabled ? ["x402"] : [], ...mpp?.enabled ? ["mpp"] : []];
+    if (!paymentMethods.some((method) => enabledRails.includes(method))) {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `Resource "${id}" names payment method(s) "${paymentMethods.join(", ")}", none of which is configured and enabled under "payments"`,
+        { details: { path: `resources.${id}.payments`, resourceId: id, paymentMethods } }
+      );
+    }
+    if (mpp?.enabled && paymentMethods.includes("mpp")) {
+      if (entry.pricing.currency !== MPP_PROFILE.assetSymbol) {
         throw new CommerceError(
           "CONFIG_INVALID",
-          `Resource "${id}" names payment method "x402" which is not configured or not enabled under payments.x402`,
-          { details: { path: `resources.${id}.payments`, resourceId: id, method } }
+          `Resource "${id}" is priced in ${entry.pricing.currency}, but MPP charges ${MPP_PROFILE.assetSymbol}`,
+          { details: { path: `resources.${id}.pricing.currency`, resourceId: id } }
         );
       }
+      validatePricingAmount(id, entry.pricing.amount, MPP_PROFILE.assetDecimals);
     }
   }
   const pricing = entry.pricing.type === "free" ? { type: "free" } : { type: "fixed", amount: entry.pricing.amount, currency: entry.pricing.currency };
@@ -2233,7 +2346,7 @@ function validateResourceSchemaKeywords(id, path2, schema) {
 }
 var PRICING_AMOUNT_PATTERN = /^\d+(?:\.\d+)?$/;
 var ZERO_AMOUNT_PATTERN = /^0(?:\.0+)?$/;
-function validatePricingAmount(id, amount, x402) {
+function validatePricingAmount(id, amount, decimals) {
   const path2 = `resources.${id}.pricing.amount`;
   if (!PRICING_AMOUNT_PATTERN.test(amount)) {
     throw new CommerceError(
@@ -2249,12 +2362,12 @@ function validatePricingAmount(id, amount, x402) {
       { details: { path: path2, resourceId: id } }
     );
   }
-  if (x402 !== void 0) {
+  if (decimals !== void 0) {
     const fractionalDigits = amount.includes(".") ? amount.split(".")[1]?.length ?? 0 : 0;
-    if (fractionalDigits > x402.assetDecimals) {
+    if (fractionalDigits > decimals) {
       throw new CommerceError(
         "CONFIG_INVALID",
-        `Resource "${id}" has pricing.amount "${amount}" with more precision (${fractionalDigits} fractional digits) than the configured asset supports (${x402.assetDecimals} decimals)`,
+        `Resource "${id}" has pricing.amount "${amount}" with more precision (${fractionalDigits} fractional digits) than the configured asset supports (${decimals} decimals)`,
         { details: { path: path2, resourceId: id } }
       );
     }
@@ -2513,6 +2626,7 @@ var SECRET_FIELD_NAMES = [
   "seed",
   "mnemonic",
   "secret",
+  "challengeSecret",
   "apiKey",
   "adminToken",
   "token"
@@ -2578,7 +2692,7 @@ function wrapPino(instance) {
 }
 var CORS_METHODS = "GET,POST,DELETE,OPTIONS";
 var CORS_HEADERS = "content-type,payment-signature,x-request-id,authorization";
-var CORS_EXPOSED_HEADERS = "payment-required,payment-response,x-request-id";
+var CORS_EXPOSED_HEADERS = "payment-required,payment-response,www-authenticate,payment-receipt,x-request-id";
 function buildAccessControlHook(options) {
   const allowedOrigins = new Set(options.allowedOrigins.map((origin) => origin.toLowerCase()));
   const publicHostname = hostnameOf(options.publicBaseUrl);
@@ -2991,7 +3105,7 @@ async function buildWellKnownDocument(options) {
       return { ...runtime.adapter.descriptor, health: publicHealth(health) };
     })
   );
-  const x402 = options.config.payments.x402;
+  const { x402, mpp } = options.config.payments;
   return {
     gateway: {
       implementationVersion: PACKAGE_VERSION,
@@ -3027,6 +3141,22 @@ async function buildWellKnownDocument(options) {
             x402.facilitator.mode
           )
         }
+      } : {},
+      ...mpp !== void 0 ? {
+        mpp: {
+          enabled: mpp.enabled,
+          network: mpp.network,
+          asset: mpp.asset,
+          assetName: mpp.assetName,
+          assetVersion: mpp.assetVersion,
+          assetDecimals: MPP_PROFILE.assetDecimals,
+          recipient: mpp.recipient,
+          facilitator: { mode: mpp.facilitator.mode },
+          mode: resolveDeploymentMode(
+            requireNetworkProfile(mpp.network, "payments.mpp.network"),
+            mpp.facilitator.mode
+          )
+        }
       } : {}
     }
   };
@@ -3148,9 +3278,8 @@ async function handleInvoke(request, reply, options) {
         resourceId
       });
     }
-    const paymentHeader = request.headers[PAYMENT_HEADER];
-    const paymentValue = Array.isArray(paymentHeader) ? paymentHeader[0] : paymentHeader;
     const paymentMethod = resource.paymentMethods[0];
+    const paymentValue = paymentProof(request, paymentMethod);
     const payment = paymentValue !== void 0 && paymentMethod !== void 0 ? { method: paymentMethod, payload: paymentValue } : void 0;
     const authorization = parseAuthorizationHeader(
       request.headers[AUTHORIZATION_HEADER],
@@ -3168,7 +3297,10 @@ async function handleInvoke(request, reply, options) {
     const outcome = await options.pipeline.execute(canonicalRequest);
     if (outcome.kind === "payment-required") {
       const envelope = toPaymentRequiredEnvelope(outcome);
-      if (envelope.payment.envelope !== void 0) {
+      if (envelope.payment.provider === "mpp") {
+        const challenge = envelope.payment.envelope?.["wwwAuthenticate"];
+        if (typeof challenge === "string") reply.header("www-authenticate", challenge);
+      } else if (envelope.payment.envelope !== void 0) {
         reply.header(PAYMENT_REQUIRED_HEADER, encodeHeaderDocument(envelope.payment.envelope));
       }
       reply.header("cache-control", "no-store");
@@ -3177,6 +3309,10 @@ async function handleInvoke(request, reply, options) {
     }
     if (outcome.payment) {
       reply.header(PAYMENT_RESPONSE_HEADER, encodePaymentSummary(outcome.payment));
+      const receipt = outcome.payment.metadata?.["receipt"];
+      if (outcome.payment.provider === "mpp" && typeof receipt === "string") {
+        reply.header("payment-receipt", receipt);
+      }
     }
     reply.status(outcome.backendStatus).send(outcome.body);
   } catch (error) {
@@ -3184,15 +3320,31 @@ async function handleInvoke(request, reply, options) {
     const settledPayment = errorPaymentSummary(commerceError);
     if (settledPayment !== void 0) {
       reply.header(PAYMENT_RESPONSE_HEADER, encodePaymentSummary(settledPayment));
+      if (settledPayment.provider === "mpp" && settledPayment.receipt !== void 0) {
+        reply.header("payment-receipt", settledPayment.receipt);
+      }
+    }
+    const challenge = commerceError.details?.["challenge"];
+    if (commerceError.code === "PAYMENT_INVALID" && typeof challenge?.["wwwAuthenticate"] === "string") {
+      reply.header("www-authenticate", challenge["wwwAuthenticate"]);
+      reply.header("cache-control", "no-store");
     }
     reply.status(commerceError.httpStatus).send(toErrorEnvelope(commerceError));
   }
 }
+function paymentProof(request, method) {
+  if (method === "mpp") {
+    const value2 = request.headers.authorization;
+    return value2 !== void 0 && /^Payment\s+\S/i.test(value2) ? value2 : void 0;
+  }
+  const value = request.headers[PAYMENT_HEADER];
+  return Array.isArray(value) ? value[0] : value;
+}
 function errorPaymentSummary(error) {
   const payment = error.details?.["payment"];
   if (typeof payment !== "object" || payment === null) return void 0;
   const rec = payment;
-  const { status, provider, amount, currency, network, externalReference } = rec;
+  const { status, provider, amount, currency, network, externalReference, receipt } = rec;
   if (typeof status !== "string" || typeof provider !== "string" || typeof amount !== "string" || typeof currency !== "string") {
     return void 0;
   }
@@ -3202,7 +3354,8 @@ function errorPaymentSummary(error) {
     amount,
     currency,
     ...typeof network === "string" ? { network } : {},
-    ...typeof externalReference === "string" ? { externalReference } : {}
+    ...typeof externalReference === "string" ? { externalReference } : {},
+    ...typeof receipt === "string" ? { receipt } : {}
   };
 }
 function encodeHeaderDocument(document) {
@@ -3244,13 +3397,25 @@ function parseLimit(value) {
 // src/gateway/server.ts
 var REQUEST_ID_HEADER = "x-request-id";
 var CLIENT_REQUEST_ID_PATTERN = /^[A-Za-z0-9._:-]{1,64}$/;
+function withProviderBackedMethodsFirst(resource, providers) {
+  const backed = (method) => providers.some((provider) => provider.name === method);
+  const ordered = [
+    ...resource.paymentMethods.filter(backed),
+    ...resource.paymentMethods.filter((method) => !backed(method))
+  ];
+  return ordered.some((method, i) => method !== resource.paymentMethods[i]) ? { ...resource, paymentMethods: ordered } : resource;
+}
 async function createGateway(options) {
   const clock = options.clock ?? systemClock;
   const ids = options.ids ?? createDefaultIdGenerator();
   const logger = options.logger ?? createGatewayLogger({ name: options.config.merchant.id }).core;
   const backend = options.backend ?? new HttpBackendExecutor({ logger });
   const authorizationProviders = options.authorizationProviders ?? [];
-  const resources = createResourceRegistry(options.config.resources);
+  const resources = createResourceRegistry(
+    options.config.resources.map(
+      (resource) => withProviderBackedMethodsFirst(resource, options.paymentProviders)
+    )
+  );
   const eventBus = createEventBus({ store: options.store, logger });
   const pipeline = createExecutionPipeline({
     resources,
@@ -3334,13 +3499,14 @@ async function createGateway(options) {
 
 // src/protocols/acp/checkout-mapping.ts
 function toCanonicalRequest(options) {
-  const { request, resourceId, requestId, receivedAt } = options;
+  const { request, resourceId, requestId, receivedAt, idempotencyKey } = options;
   return {
     requestId,
     resourceId,
     input: canonicalInput(request),
     protocol: "acp",
-    receivedAt
+    receivedAt,
+    ...idempotencyKey !== void 0 ? { idempotencyKey } : {}
   };
 }
 function canonicalInput(request) {
@@ -3448,8 +3614,8 @@ function writeAcpJson(res, status, body, headers = {}) {
 function writeAcpFailure(res, failure, headers = {}) {
   writeAcpJson(res, failure.status, failure.error, headers);
 }
-function identityHash(token) {
-  return sha256(`acp-auth:${token}`);
+function operationKey(scope) {
+  return sha256(`acp-operation:${scope.deployment}:${scope.endpoint}:${scope.key}`);
 }
 function requestFingerprint(body) {
   return sha256(canonicalize(body));
@@ -3468,6 +3634,7 @@ function sha256(value) {
 }
 
 // src/protocols/acp/idempotency/store.ts
+var SCHEMA_VERSION = 2;
 var ACP_MAX_IDEMPOTENCY_KEY_LENGTH = 255;
 function createAcpIdempotencyStore(options) {
   const logger = options.logger ?? NOOP_LOGGER;
@@ -3478,33 +3645,39 @@ function createAcpIdempotencyStore(options) {
     label: "ACP idempotency database",
     logger
   });
-  migrate(db);
+  migrate(db, logger);
   const selectStmt = db.prepare(
     `SELECT state, fingerprint, status, body_json FROM acp_idempotency
-      WHERE identity_hash = ? AND endpoint = ? AND idempotency_key = ?`
+      WHERE deployment = ? AND endpoint = ? AND idempotency_key = ?`
   );
   const insertStmt = db.prepare(
     `INSERT INTO acp_idempotency
-       (identity_hash, endpoint, idempotency_key, fingerprint, state, created_at, expires_at)
-     VALUES (@identity_hash, @endpoint, @idempotency_key, @fingerprint, 'in_flight', @created_at, @expires_at)`
+       (deployment, endpoint, idempotency_key, fingerprint, state, created_at, expires_at)
+     VALUES (@deployment, @endpoint, @idempotency_key, @fingerprint, 'in_flight', @created_at, @expires_at)`
   );
   const completeStmt = db.prepare(
     `UPDATE acp_idempotency SET state = 'completed', status = @status, body_json = @body_json
-      WHERE identity_hash = @identity_hash AND endpoint = @endpoint AND idempotency_key = @idempotency_key`
+      WHERE deployment = @deployment AND endpoint = @endpoint AND idempotency_key = @idempotency_key`
   );
   const deleteStmt = db.prepare(
     `DELETE FROM acp_idempotency
-      WHERE identity_hash = ? AND endpoint = ? AND idempotency_key = ?`
+      WHERE deployment = ? AND endpoint = ? AND idempotency_key = ?`
+  );
+  const unresolvedStmt = db.prepare(
+    `UPDATE acp_idempotency SET state = 'unresolved'
+      WHERE deployment = @deployment AND endpoint = @endpoint AND idempotency_key = @idempotency_key`
+  );
+  const expireStmt = db.prepare(
+    "DELETE FROM acp_idempotency WHERE expires_at <= ? AND state = 'completed'"
   );
-  const expireStmt = db.prepare("DELETE FROM acp_idempotency WHERE expires_at <= ?");
   const claimTx = db.transaction(
     (scope, fingerprint) => {
       const at = now();
       expireStmt.run(new Date(at).toISOString());
-      const existing = selectStmt.get(scope.identityHash, scope.endpoint, scope.key);
+      const existing = selectStmt.get(scope.deployment, scope.endpoint, scope.key);
       if (existing === void 0) {
         insertStmt.run({
-          identity_hash: scope.identityHash,
+          deployment: scope.deployment,
           endpoint: scope.endpoint,
           idempotency_key: scope.key,
           fingerprint,
@@ -3514,6 +3687,7 @@ function createAcpIdempotencyStore(options) {
         return { kind: "reserved" };
       }
       if (existing.fingerprint !== fingerprint) return { kind: "conflict" };
+      if (existing.state === "unresolved") return { kind: "unresolved" };
       if (existing.state !== "completed") return { kind: "in-flight" };
       return {
         kind: "replay",
@@ -3529,15 +3703,22 @@ function createAcpIdempotencyStore(options) {
     },
     complete(scope, response) {
       completeStmt.run({
-        identity_hash: scope.identityHash,
+        deployment: scope.deployment,
         endpoint: scope.endpoint,
         idempotency_key: scope.key,
         status: response.status,
         body_json: JSON.stringify(response.body ?? null)
       });
     },
+    markUnresolved(scope) {
+      unresolvedStmt.run({
+        deployment: scope.deployment,
+        endpoint: scope.endpoint,
+        idempotency_key: scope.key
+      });
+    },
     release(scope) {
-      deleteStmt.run(scope.identityHash, scope.endpoint, scope.key);
+      deleteStmt.run(scope.deployment, scope.endpoint, scope.key);
     },
     close() {
       if (closed) return;
@@ -3546,13 +3727,23 @@ function createAcpIdempotencyStore(options) {
     }
   };
 }
-function migrate(db) {
+function migrate(db, logger) {
   const current = db.pragma("user_version", { simple: true });
-  if (current >= 1) return;
+  if (current >= SCHEMA_VERSION) return;
   const apply = db.transaction(() => {
+    if (current === 1) {
+      const carried = db.prepare("SELECT COUNT(*) AS count FROM acp_idempotency WHERE state != 'completed'").get();
+      if (carried.count > 0) {
+        logger.warn(
+          { unresolved: carried.count },
+          "acp idempotency: schema v1 -> v2 discards claims keyed by the old bearer-token digest; reconcile these operations against the merchant before trusting a retry"
+        );
+      }
+      db.exec("DROP TABLE acp_idempotency");
+    }
     db.exec(`
       CREATE TABLE IF NOT EXISTS acp_idempotency (
-        identity_hash    TEXT NOT NULL,
+        deployment       TEXT NOT NULL,
         endpoint         TEXT NOT NULL,
         idempotency_key  TEXT NOT NULL,
         fingerprint      TEXT NOT NULL,
@@ -3561,12 +3752,12 @@ function migrate(db) {
         body_json        TEXT,
         created_at       TEXT NOT NULL,
         expires_at       TEXT NOT NULL,
-        PRIMARY KEY (identity_hash, endpoint, idempotency_key)
+        PRIMARY KEY (deployment, endpoint, idempotency_key)
       );
       CREATE INDEX IF NOT EXISTS idx_acp_idempotency_expires_at
         ON acp_idempotency(expires_at);
     `);
-    db.pragma("user_version = 1");
+    db.pragma(`user_version = ${SCHEMA_VERSION}`);
   });
   apply();
 }
@@ -7974,6 +8165,28 @@ function asResponse(failure) {
 
 // src/protocols/acp/adapter.ts
 var DISCOVERY_CACHE_CONTROL = "public, max-age=3600";
+var PRE_BACKEND_ERROR_CODES = /* @__PURE__ */ new Set([
+  "CONFIG_INVALID",
+  "RESOURCE_NOT_FOUND",
+  "INPUT_INVALID",
+  "PROTOCOL_UNSUPPORTED",
+  "GATEWAY_BUSY",
+  "PAYMENT_REQUIRED",
+  "PAYMENT_INVALID",
+  "PAYMENT_REPLAYED",
+  "PAYMENT_PROVIDER_UNAVAILABLE",
+  "PAYMENT_SETTLEMENT_FAILED",
+  "AUTHORIZATION_REQUIRED",
+  "AUTHORIZATION_INVALID",
+  "AUTHORIZATION_REPLAYED",
+  "AUTHORIZATION_PROVIDER_UNAVAILABLE"
+]);
+function reachedFor(code) {
+  return PRE_BACKEND_ERROR_CODES.has(code) ? "no" : "unknown";
+}
+function notReached(failure) {
+  return { response: asResponse(failure), reached: "no" };
+}
 var AcpProtocolAdapter = class {
   name = "acp";
   mountPath;
@@ -7982,8 +8195,14 @@ var AcpProtocolAdapter = class {
   token;
   operations;
   idempotencyOptions;
-  /** Derived once: the token is fixed, and only its digest may be persisted. */
-  identityHash;
+  /**
+   * What an idempotency claim is scoped to, from `context.publicBaseUrl`.
+   *
+   * Not readonly because, unlike the token, it is known only once the adapter
+   * starts. Worth that: scoping by the credential meant a rotation freed
+   * every outstanding claim.
+   */
+  deployment;
   discoveryMetadata;
   idempotency;
   resources = /* @__PURE__ */ new Map();
@@ -7998,7 +8217,6 @@ var AcpProtocolAdapter = class {
     this.token = options.token;
     this.operations = options.operations;
     this.idempotencyOptions = options.idempotency;
-    this.identityHash = identityHash(options.token);
     this.discoveryMetadata = options.discovery;
     this.descriptor = buildDescriptor(PACKAGE_VERSION);
     this.additionalHttpRoutes = [
@@ -8042,6 +8260,7 @@ var AcpProtocolAdapter = class {
       resolved.set(operation, resource);
     }
     this.resources = resolved;
+    this.deployment = context.publicBaseUrl;
     this.idempotency = createAcpIdempotencyStore({
       path: this.idempotencyOptions.path,
       retentionHours: this.idempotencyOptions.retentionHours,
@@ -8130,22 +8349,33 @@ var AcpProtocolAdapter = class {
    */
   async dispatch(request) {
     const store = this.idempotency;
+    const deployment = this.deployment;
     const key = request.idempotencyKey;
-    if (store === void 0 || key === void 0) return this.runCheckout(request);
-    const scope = {
-      identityHash: this.identityHash,
-      endpoint: request.route.path,
-      key
-    };
+    if (store === void 0 || deployment === void 0 || key === void 0) {
+      return (await this.runCheckout(request)).response;
+    }
+    const scope = { deployment, endpoint: request.route.path, key };
     const claim = store.claim(scope, requestFingerprint(request.body));
     switch (claim.kind) {
       case "in-flight":
+        return {
+          ...asResponse(
+            acpFailure(
+              409,
+              "invalid_request",
+              "idempotency_in_flight",
+              "A request with this Idempotency-Key is still being processed."
+            )
+          ),
+          retryAfterSeconds: ACP_IN_FLIGHT_RETRY_AFTER_SECONDS
+        };
+      case "unresolved":
         return asResponse(
           acpFailure(
             409,
-            "invalid_request",
-            "idempotency_in_flight",
-            "A request with this Idempotency-Key is still being processed."
+            "processing_error",
+            "idempotency_unresolved",
+            "An earlier request with this Idempotency-Key reached the merchant and its outcome is unknown. Check the operation with the merchant before retrying."
           )
         );
       case "conflict":
@@ -8160,16 +8390,21 @@ var AcpProtocolAdapter = class {
       case "replay":
         return { status: claim.status, body: claim.body, replayed: true };
     }
-    let response;
+    let outcome;
     try {
-      response = await this.runCheckout(request);
+      outcome = await this.runCheckout(request, operationKey(scope));
     } catch (err) {
-      store.release(scope);
+      store.markUnresolved(scope);
       throw err;
     }
-    if (response.status >= 500) store.release(scope);
-    else store.complete(scope, response);
-    return response;
+    if (outcome.response.status < 500) {
+      store.complete(scope, outcome.response);
+    } else if (outcome.reached === "no") {
+      store.release(scope);
+    } else {
+      store.markUnresolved(scope);
+    }
+    return outcome.response;
   }
   /**
    * One accepted request, one `pipeline.execute()`.
@@ -8178,11 +8413,11 @@ var AcpProtocolAdapter = class {
    * merchant backend: the adapter builds a canonical request and reads back
    * what the pipeline decided.
    */
-  async runCheckout(request) {
+  async runCheckout(request, idempotencyKey) {
     const context = this.context;
     const resource = this.resources.get(request.route.operation);
     if (context === void 0 || resource === void 0) {
-      return asResponse(
+      return notReached(
         acpFailure(
           503,
           "service_unavailable",
@@ -8195,7 +8430,8 @@ var AcpProtocolAdapter = class {
       request,
       resourceId: resource.id,
       requestId: context.ids.next("acp"),
-      receivedAt: context.clock.nowIso()
+      receivedAt: context.clock.nowIso(),
+      ...idempotencyKey !== void 0 ? { idempotencyKey } : {}
     });
     try {
       const outcome = await context.pipeline.execute(canonical);
@@ -8204,7 +8440,7 @@ var AcpProtocolAdapter = class {
           { resourceId: resource.id, requestId: canonical.requestId },
           "acp adapter: mapped checkout resource returned payment-required - it must be priced free"
         );
-        return asResponse(
+        return notReached(
           acpFailure(
             500,
             "processing_error",
@@ -8220,14 +8456,22 @@ var AcpProtocolAdapter = class {
           "acp adapter: refusing to forward a non-conformant merchant response"
         );
       }
-      return mapped.response;
+      return { response: mapped.response, reached: "yes" };
     } catch (err) {
       const error = toCommerceError(err);
       context.logger.warn(
-        { resourceId: resource.id, requestId: canonical.requestId, err: error.toInfo() },
+        {
+          resourceId: resource.id,
+          requestId: canonical.requestId,
+          reached: reachedFor(error.code),
+          err: error.toInfo()
+        },
         "acp adapter: checkout execution failed"
       );
-      return asResponse(mapCommerceErrorToAcp(error, request.route.operation));
+      return {
+        response: asResponse(mapCommerceErrorToAcp(error, request.route.operation)),
+        reached: reachedFor(error.code)
+      };
     }
   }
   /**
@@ -8240,7 +8484,7 @@ var AcpProtocolAdapter = class {
       ...request.requestId !== void 0 ? { [ACP_REQUEST_ID_HEADER]: request.requestId } : {},
       ...request.idempotencyKey !== void 0 ? { [ACP_IDEMPOTENCY_KEY_HEADER]: request.idempotencyKey } : {},
       ...replayed ? { [ACP_IDEMPOTENT_REPLAYED_HEADER]: "true" } : {},
-      ...response?.status === 409 ? { "retry-after": String(ACP_IN_FLIGHT_RETRY_AFTER_SECONDS) } : {}
+      ...response?.retryAfterSeconds !== void 0 ? { "retry-after": String(response.retryAfterSeconds) } : {}
     };
   }
   fail(res, err, message) {
@@ -8267,6 +8511,7 @@ var AcpProtocolAdapter = class {
     this.resources = /* @__PURE__ */ new Map();
     this.idempotency?.close();
     this.idempotency = void 0;
+    this.deployment = void 0;
     this.context = void 0;
   }
 };
@@ -8443,7 +8688,7 @@ var MIGRATIONS = [
     }
   }
 ];
-var SCHEMA_VERSION = MIGRATIONS[MIGRATIONS.length - 1]?.version ?? 0;
+var SCHEMA_VERSION2 = MIGRATIONS[MIGRATIONS.length - 1]?.version ?? 0;
 function migrate2(db) {
   const current = db.pragma("user_version", { simple: true });
   for (const migration of MIGRATIONS) {
@@ -8529,17 +8774,17 @@ function createSqliteReceiptStore(options) {
     name: "sqlite-receipt-store",
     kind: "storage",
     implementationVersion: PACKAGE_VERSION,
-    supportedSpec: `sqlite-schema-v${SCHEMA_VERSION}`,
+    supportedSpec: `sqlite-schema-v${SCHEMA_VERSION2}`,
     capabilities: ["receipts", "events", "payment-attempts"],
     status: "stable"
   };
   const store = {
     async init() {
       const version = db.pragma("user_version", { simple: true });
-      if (version !== SCHEMA_VERSION) {
+      if (version !== SCHEMA_VERSION2) {
         throw new CommerceError(
           "STORAGE_ERROR",
-          `Receipt store schema version mismatch (found ${version}, expected ${SCHEMA_VERSION})`
+          `Receipt store schema version mismatch (found ${version}, expected ${SCHEMA_VERSION2})`
         );
       }
     },
@@ -8673,9 +8918,9 @@ function createSqliteReceiptStore(options) {
       }
       try {
         const version = db.pragma("user_version", { simple: true });
-        if (version !== SCHEMA_VERSION) {
+        if (version !== SCHEMA_VERSION2) {
           logger.warn(
-            { found: version, expected: SCHEMA_VERSION },
+            { found: version, expected: SCHEMA_VERSION2 },
             "receipt-store: health check failed (schema version mismatch)"
           );
           return {
@@ -8687,7 +8932,7 @@ function createSqliteReceiptStore(options) {
         }
         return {
           status: "pass",
-          detail: `sqlite schema v${SCHEMA_VERSION} writable`,
+          detail: `sqlite schema v${SCHEMA_VERSION2} writable`,
           checkedAt: clock.nowIso(),
           durationMs: clock.monotonicMs() - startedAt
         };