@devlab.group/agent-commerce 1.3.0 → 1.4.1

package/dist/index.js

@@ -1,16 +1,15 @@
-import { resolveX402Deployment, resolveDeploymentMode, requireNetworkProfile } from './chunk-TBZA6Z5B.js';
-import { PROTOCOL_NAMES, CommerceError, PAYMENT_INPUT_FIELD, systemClock, NOOP_LOGGER, PACKAGE_VERSION, toCommerceError, DEFAULT_BACKEND_TIMEOUT_MS, toErrorEnvelope, isHttpProtocolAdapter, isCommerceError, PAYMENT_HEADER, toPaymentRequiredEnvelope, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER } from './chunk-N3DNLXGC.js';
-export { COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, COMMERCE_EVENT_TYPES, CommerceError, DEFAULT_BACKEND_TIMEOUT_MS, DELIVERY_SUMMARY_META_KEY, NOOP_LOGGER, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PROTOCOL_NAMES, RETRYABLE_ERROR_CODES, isCommerceError, isHttpProtocolAdapter, isPaymentRequiredEnvelope, systemClock, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope } from './chunk-N3DNLXGC.js';
-import { promises, accessSync, constants, existsSync, mkdirSync, closeSync, openSync, chmodSync } from 'fs';
+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-GF6KHHKL.js';
+import { resolveX402Deployment, resolveDeploymentMode, requireNetworkProfile } from './chunk-NWIQLJNU.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-ZEGFLRGV.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-ZEGFLRGV.js';
+import { promises, accessSync, constants } from 'fs';
 import * as path from 'path';
-import { dirname } from 'path';
 import { parse, YAMLError } from 'yaml';
 import { z } from 'zod';
 import { randomUUID, timingSafeEqual, createHash } from 'crypto';
 import { createRequire } from 'module';
 import pino from 'pino';
 import Fastify from 'fastify';
-import Database from 'better-sqlite3';
 import Ajv2020 from 'ajv/dist/2020.js';
 import addFormats from 'ajv-formats';
 
@@ -86,6 +85,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 {
@@ -127,6 +127,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)) {
@@ -335,6 +339,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) => {
@@ -599,6 +609,92 @@ function createExecutionPipeline(options) {
   function buildEvent(partial) {
     return { id: options.ids.next("evt"), at: options.clock.nowIso(), ...partial };
   }
+  async function authorizeAndReserve(request, resource, providers, requirement, input) {
+    if (providers.length === 0) return void 0;
+    const submission = request.authorization;
+    const provider = providers.find((candidate) => candidate.name === submission?.method);
+    const unmet = providers.filter((candidate) => candidate !== provider).map((c) => c.name);
+    if (submission === void 0 || provider === void 0 || unmet.length > 0) {
+      await safeEmit(
+        buildEvent({
+          type: "authorization.rejected",
+          requestId: request.requestId,
+          resourceId: resource.id,
+          adapter: request.protocol,
+          status: "error",
+          data: { reason: "AUTHORIZATION_REQUIRED", methods: unmet }
+        })
+      );
+      throw new CommerceError(
+        "AUTHORIZATION_REQUIRED",
+        `Resource "${resource.id}" requires authorization: ${unmet.join(", ")}`,
+        {
+          requestId: request.requestId,
+          resourceId: resource.id,
+          details: { required: providers.map((candidate) => candidate.name), missing: unmet }
+        }
+      );
+    }
+    let verification;
+    try {
+      verification = await provider.verifyAndReserve({
+        requestId: request.requestId,
+        resourceId: resource.id,
+        input,
+        submission,
+        requirement
+      });
+    } catch (error) {
+      const mapped = isCommerceError(error) ? error : new CommerceError(
+        "AUTHORIZATION_PROVIDER_UNAVAILABLE",
+        "Authorization provider is unavailable",
+        {
+          requestId: request.requestId,
+          resourceId: resource.id,
+          cause: error
+        }
+      );
+      await safeEmit(
+        buildEvent({
+          type: "authorization.rejected",
+          requestId: request.requestId,
+          resourceId: resource.id,
+          adapter: request.protocol,
+          status: "error",
+          data: { reason: mapped.code, method: provider.name }
+        })
+      );
+      throw mapped;
+    }
+    await safeEmit(
+      buildEvent({
+        type: "authorization.verified",
+        requestId: request.requestId,
+        resourceId: resource.id,
+        adapter: request.protocol,
+        status: "ok",
+        data: { method: verification.method, reference: verification.reference }
+      })
+    );
+    const context = { requestId: request.requestId, resourceId: resource.id };
+    return {
+      record: {
+        method: verification.method,
+        reference: verification.reference,
+        ...verification.metadata !== void 0 ? { metadata: verification.metadata } : {}
+      },
+      async finalize(action) {
+        try {
+          await provider[action](verification.reservationId, context);
+        } catch (error) {
+          options.logger.error(
+            { err: describeError2(error), requestId: request.requestId, action },
+            "Authorization finalization failed; the reservation stays reserved"
+          );
+        }
+      }
+    };
+  }
   async function execute(request) {
     const pipelineStart = options.clock.monotonicMs();
     const resource = options.resources.get(request.resourceId);
@@ -620,7 +716,7 @@ function createExecutionPipeline(options) {
         adapter: request.protocol
       })
     );
-    const strippedInput = stripPaymentField(request.input);
+    const strippedInput = stripReservedFields(request.input);
     const validation = getValidator(resource)(strippedInput);
     if (!validation.valid) {
       throw new CommerceError(
@@ -648,7 +744,18 @@ function createExecutionPipeline(options) {
         }
       );
     }
+    if (resource.pricing.type !== "fixed" && (resource.authorization?.required.length ?? 0) > 0) {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `Resource "${resource.id}" requires authorization but is not a paid resource`,
+        {
+          requestId: request.requestId,
+          resourceId: resource.id
+        }
+      );
+    }
     let paymentResult;
+    let authorization;
     if (resource.pricing.type === "fixed") {
       const pricing = resource.pricing;
       const provider = pickProvider(options.paymentProviders, resource.paymentMethods);
@@ -663,6 +770,11 @@ function createExecutionPipeline(options) {
           }
         );
       }
+      const authProviders = resolveAuthorizationProviders(
+        options.authorizationProviders ?? [],
+        resource,
+        request.requestId
+      );
       let requirement;
       try {
         requirement = await provider.createRequirement({
@@ -693,7 +805,8 @@ function createExecutionPipeline(options) {
           kind: "payment-required",
           requestId: request.requestId,
           resourceId: resource.id,
-          requirement
+          requirement,
+          ...authProviders.length > 0 ? { authorization: authProviders.map((p) => p.requirement) } : {}
         };
       }
       const payment = request.payment;
@@ -763,6 +876,14 @@ function createExecutionPipeline(options) {
         });
       }
       const replayKey = verification.replayKey;
+      const hold = await authorizeAndReserve(
+        request,
+        resource,
+        authProviders,
+        requirement,
+        validInput
+      );
+      authorization = hold?.record;
       try {
         await options.store.reservePaymentAttempt({
           requestId: request.requestId,
@@ -780,6 +901,7 @@ function createExecutionPipeline(options) {
           "STORAGE_ERROR",
           "Payment attempt could not be recorded"
         );
+        await hold?.finalize("release");
         await safeEmit(
           buildEvent({
             type: "payment.rejected",
@@ -813,16 +935,16 @@ function createExecutionPipeline(options) {
           verification
         });
       } catch (error) {
-        const uncertainTxHash = uncertainSettlementTxHash(error);
+        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(
@@ -833,21 +955,24 @@ 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");
         await safePersist(
           () => options.store.updatePaymentAttempt({
             replayKey,
@@ -877,6 +1002,7 @@ function createExecutionPipeline(options) {
           }
         );
       }
+      await hold?.finalize("consume");
       await safePersist(
         () => options.store.updatePaymentAttempt({
           replayKey,
@@ -904,7 +1030,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");
@@ -928,6 +1055,7 @@ function createExecutionPipeline(options) {
           backendStatus: backendErrorStatus(commerceError),
           protocol: request.protocol,
           payment: paymentResult,
+          ...authorization !== void 0 ? { authorization } : {},
           metadata: { delivered: false, backendErrorCode: commerceError.code }
         };
         await safePersist(
@@ -976,7 +1104,8 @@ function createExecutionPipeline(options) {
       backendStatus: backendResponse.status,
       durationMs: backendResponse.durationMs,
       protocol: request.protocol,
-      ...paymentResult !== void 0 ? { payment: paymentResult } : {}
+      ...paymentResult !== void 0 ? { payment: paymentResult } : {},
+      ...authorization !== void 0 ? { authorization } : {}
     };
     await safePersist(() => options.store.saveReceipt(receipt), "saveReceipt", request.requestId);
     const totalDurationMs = Math.round(options.clock.monotonicMs() - pipelineStart);
@@ -1008,11 +1137,24 @@ 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) {
+  const required = resource.authorization?.required ?? [];
+  return required.map((method) => {
+    const found = providers.find((provider) => provider.name === method);
+    if (!found) {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `Resource "${resource.id}" requires authorization method "${method}", which is not enabled`,
+        { requestId, resourceId: resource.id }
+      );
+    }
+    return found;
+  });
+}
 function pickProvider(providers, methods) {
   for (const method of methods) {
     const found = providers.find((provider) => provider.name === method);
@@ -1020,8 +1162,8 @@ function pickProvider(providers, methods) {
   }
   return void 0;
 }
-var RESERVED_INPUT_KEYS = /* @__PURE__ */ new Set([PAYMENT_INPUT_FIELD, "__proto__"]);
-function stripPaymentField(input) {
+var RESERVED_INPUT_KEYS = /* @__PURE__ */ new Set([...RESERVED_INPUT_FIELDS, "__proto__"]);
+function stripReservedFields(input) {
   if (typeof input !== "object" || input === null || Array.isArray(input)) return input;
   const record = input;
   const hasReserved = [...RESERVED_INPUT_KEYS].some((key) => Object.hasOwn(record, key));
@@ -1234,7 +1376,8 @@ var ResourceEntrySchema = z.object({
   backend: BackendHandlerSchema,
   pricing: PricingSchema,
   expose: z.array(z.string().min(1)).min(1),
-  payments: z.array(z.string().min(1)).optional()
+  payments: z.array(z.string().min(1)).optional(),
+  authorization: z.object({ required: z.array(z.string().min(1)).min(1) }).strict().optional()
 }).strict();
 var ResourcesMapSchema = z.record(z.string().min(1), ResourceEntrySchema);
 var FacilitatorAuthSchema = z.discriminatedUnion("type", [
@@ -1282,6 +1425,32 @@ var X402Schema = z.object({
 var PaymentsSchema = z.object({
   x402: X402Schema.optional()
 }).strict();
+var Ap2KeySchema = z.object({
+  kid: z.string().min(1),
+  jwk: z.record(z.string(), z.unknown())
+}).strict();
+var Ap2IssuerSchema = z.object({
+  issuer: z.string().min(1),
+  /**
+   * Required, not defaulted. Without it, a mandate minted for another
+   * merchant would verify here, and there is no value worth guessing for
+   * something that decides that.
+   */
+  audience: z.string().min(1),
+  keys: z.array(Ap2KeySchema).min(1)
+}).strict();
+var Ap2Schema = z.object({
+  enabled: BooleanOrString,
+  specVersion: z.string().min(1).optional(),
+  mode: z.string().min(1).optional(),
+  trust: z.object({
+    mandateIssuers: z.array(Ap2IssuerSchema).optional(),
+    checkoutIssuers: z.array(Ap2IssuerSchema).optional()
+  }).strict().optional(),
+  clockSkewSeconds: NumberOrString.optional(),
+  replay: z.object({ path: z.string().min(1) }).strict().optional()
+}).strict();
+var AuthorizationSchema = z.object({ ap2: Ap2Schema.optional() }).strict();
 var RawConfigSchema = z.object({
   version: z.literal(SUPPORTED_CONFIG_VERSION),
   merchant: MerchantSchema,
@@ -1289,7 +1458,8 @@ var RawConfigSchema = z.object({
   storage: StorageSchema,
   protocols: ProtocolsSchema,
   resources: ResourcesMapSchema,
-  payments: PaymentsSchema
+  payments: PaymentsSchema,
+  authorization: AuthorizationSchema.optional()
 }).strict();
 function parseConfig(raw, env) {
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
@@ -1390,6 +1560,7 @@ function toBoolean(value, path2) {
 }
 var SUPPORTED_PROTOCOLS = new Set(PROTOCOL_NAMES);
 var SUPPORTED_PAYMENT_METHODS = /* @__PURE__ */ new Set(["x402"]);
+var SUPPORTED_AUTHORIZATION_METHODS = /* @__PURE__ */ new Set(["ap2"]);
 function normalise(raw) {
   const protocols = {
     http: { enabled: toBoolean(raw.protocols.http.enabled, "protocols.http.enabled") },
@@ -1452,8 +1623,12 @@ function normalise(raw) {
       ...x402.allowUnauthenticatedFacilitator !== void 0 ? { allowUnauthenticatedFacilitator: x402.allowUnauthenticatedFacilitator } : {}
     });
   }
+  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)
+    ([id, entry]) => normaliseResource(id, entry, protocols, x402, ap2)
   );
   if (protocols.acp.enabled) validateAcpCheckoutMapping(protocols.acp, resources);
   return {
@@ -1476,7 +1651,8 @@ function normalise(raw) {
     resources,
     payments: {
       ...x402 !== void 0 ? { x402 } : {}
-    }
+    },
+    ...ap2 !== void 0 ? { authorization: { ap2 } } : {}
   };
 }
 function validateMountPaths(protocols) {
@@ -1499,6 +1675,194 @@ function validateMountPaths(protocols) {
     }
   }
 }
+function ap2Invalid(path2, message, extra = {}) {
+  return new CommerceError("CONFIG_INVALID", message, { details: { path: path2, ...extra } });
+}
+function normaliseAp2(raw) {
+  if (raw === void 0) return void 0;
+  if (!toBoolean(raw.enabled, "authorization.ap2.enabled")) return { enabled: false };
+  const specVersion = raw.specVersion ?? AP2_SPEC_VERSION;
+  if (specVersion !== AP2_SPEC_VERSION) {
+    throw ap2Invalid(
+      "authorization.ap2.specVersion",
+      `authorization.ap2.specVersion "${specVersion}" is not supported - this gateway verifies against the tagged AP2 release ${AP2_SPEC_VERSION} only`
+    );
+  }
+  const mode = raw.mode ?? AP2_MODES[0];
+  if (!AP2_MODES.includes(mode)) {
+    throw ap2Invalid(
+      "authorization.ap2.mode",
+      `authorization.ap2.mode "${mode}" is not supported. Supported: ${AP2_MODES.join(", ")}. Autonomous mode needs open mandates, agent key binding and constraint evaluation, none of which this release implements.`
+    );
+  }
+  if (raw.replay === void 0) {
+    throw ap2Invalid(
+      "authorization.ap2.replay",
+      "authorization.ap2.replay is required when AP2 is enabled - it names the SQLite file recording which mandates have been spent, and without it a verified mandate could authorise a second settlement"
+    );
+  }
+  const mandateIssuers = normaliseIssuers(
+    raw.trust?.mandateIssuers,
+    "authorization.ap2.trust.mandateIssuers"
+  );
+  const checkoutIssuers = normaliseIssuers(
+    raw.trust?.checkoutIssuers,
+    "authorization.ap2.trust.checkoutIssuers"
+  );
+  return {
+    enabled: true,
+    specVersion: AP2_SPEC_VERSION,
+    mode,
+    trust: { mandateIssuers, checkoutIssuers },
+    clockSkewSeconds: toNumber(
+      raw.clockSkewSeconds ?? AP2_DEFAULT_CLOCK_SKEW_SECONDS,
+      "authorization.ap2.clockSkewSeconds",
+      { min: 0, max: AP2_MAX_CLOCK_SKEW_SECONDS }
+    ),
+    replay: { path: raw.replay.path }
+  };
+}
+function normaliseIssuers(raw, path2) {
+  if (raw === void 0 || raw.length === 0) {
+    throw ap2Invalid(
+      path2,
+      `${path2} is required when AP2 is enabled and must name at least one issuer - trust is operator-configured and static, so an empty list means no mandate can ever verify`
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  return raw.map((entry, index) => {
+    const entryPath = `${path2}.${index}`;
+    if (seen.has(entry.issuer)) {
+      throw ap2Invalid(
+        `${entryPath}.issuer`,
+        `${entryPath}.issuer "${entry.issuer}" is listed twice - key lookup resolves by issuer, so a second entry for the same one is silently unreachable. Merge the keys into one entry instead (which is also how a rotation overlaps an old and a new key).`,
+        { issuer: entry.issuer }
+      );
+    }
+    seen.add(entry.issuer);
+    const kids = /* @__PURE__ */ new Set();
+    const keys = entry.keys.map((key, keyIndex) => {
+      const keyPath = `${entryPath}.keys.${keyIndex}`;
+      if (kids.has(key.kid)) {
+        throw ap2Invalid(
+          `${keyPath}.kid`,
+          `${keyPath}.kid "${key.kid}" is listed twice for issuer "${entry.issuer}" - a kid selects exactly one key, so which of the two verifies a signature would be undefined`,
+          { issuer: entry.issuer, kid: key.kid }
+        );
+      }
+      kids.add(key.kid);
+      return { kid: key.kid, jwk: validateJwk(key.jwk, key.kid, keyPath) };
+    });
+    return { issuer: entry.issuer, audience: entry.audience, keys };
+  });
+}
+function validateJwk(jwk, kid, path2) {
+  const fail = (detail) => {
+    throw ap2Invalid(`${path2}.jwk`, `${path2}.jwk (kid "${kid}") ${detail}`, { kid });
+  };
+  for (const member of Object.keys(jwk)) {
+    if (AP2_JWK_MEMBERS.includes(member)) continue;
+    if (member === "d" || member === "k") {
+      fail(
+        `carries private key material ("${member}"). The gateway verifies signatures and never produces them; publish only the public half. Treat the pasted key as compromised and rotate it.`
+      );
+    }
+    fail(
+      `has unsupported member "${member}". Allowed: ${AP2_JWK_MEMBERS.join(", ")}. Members naming a URL are refused on purpose - keys are configured inline and never fetched.`
+    );
+  }
+  const value = (member) => {
+    const raw = jwk[member];
+    if (typeof raw !== "string" || raw.length === 0) {
+      fail(`must give "${member}" as a non-empty string`);
+    }
+    return raw;
+  };
+  if (value("kty") !== AP2_KEY_TYPE) {
+    fail(
+      `must have kty "${AP2_KEY_TYPE}" (got "${value("kty")}") - ${AP2_SIGNING_ALGORITHM} is the only accepted algorithm`
+    );
+  }
+  if (value("crv") !== AP2_JWK_CURVE) {
+    fail(
+      `must be on curve "${AP2_JWK_CURVE}" (got "${value("crv")}") - ${AP2_SIGNING_ALGORITHM} is the only accepted algorithm`
+    );
+  }
+  for (const coordinate of ["x", "y"]) {
+    const encoded = value(coordinate);
+    if (!/^[A-Za-z0-9_-]+$/.test(encoded)) {
+      fail(`coordinate "${coordinate}" is not base64url (no padding, no "+" or "/")`);
+    }
+    if (Buffer.from(encoded, "base64url").length !== AP2_JWK_COORDINATE_BYTES) {
+      fail(
+        `coordinate "${coordinate}" decodes to ${Buffer.from(encoded, "base64url").length} bytes; a ${AP2_JWK_CURVE} coordinate is ${AP2_JWK_COORDINATE_BYTES}`
+      );
+    }
+  }
+  if (jwk["alg"] !== void 0 && value("alg") !== AP2_SIGNING_ALGORITHM) {
+    fail(`declares alg "${value("alg")}"; only ${AP2_SIGNING_ALGORITHM} is accepted`);
+  }
+  if (jwk["use"] !== void 0 && value("use") !== "sig") {
+    fail(`declares use "${value("use")}"; a verification key must be "sig"`);
+  }
+  if (jwk["kid"] !== void 0 && value("kid") !== kid) {
+    fail(`declares kid "${value("kid")}", which disagrees with the configured kid "${kid}"`);
+  }
+  const normalised = {};
+  for (const member of AP2_JWK_MEMBERS) {
+    if (jwk[member] !== void 0) normalised[member] = value(member);
+  }
+  return normalised;
+}
+function validateReplayStoreIsolated(replayPath, receiptsPath, acp) {
+  if (replayPath === ":memory:") return;
+  const others = [["storage.receipts.path", receiptsPath]];
+  if (acp.enabled) others.push(["protocols.acp.idempotency.path", acp.idempotency.path]);
+  for (const [otherPath, other] of others) {
+    if (replayPath !== other) continue;
+    throw ap2Invalid(
+      "authorization.ap2.replay.path",
+      `authorization.ap2.replay.path is the same file as ${otherPath} ("${replayPath}") - the AP2 replay store keeps its own schema and must not share a database with another store`
+    );
+  }
+}
+function normaliseResourceAuthorization(id, entry, pricing, ap2) {
+  const required = entry.authorization?.required;
+  if (required === void 0) return void 0;
+  const path2 = `resources.${id}.authorization.required`;
+  const methods = [];
+  for (const method of required) {
+    if (!SUPPORTED_AUTHORIZATION_METHODS.has(method)) {
+      throw ap2Invalid(
+        path2,
+        `Resource "${id}" requires unsupported authorization method "${method}". Supported: ${[...SUPPORTED_AUTHORIZATION_METHODS].join(", ")}.`,
+        { resourceId: id, method }
+      );
+    }
+    if (methods.includes(method)) {
+      throw ap2Invalid(path2, `Resource "${id}" lists authorization method "${method}" twice`, {
+        resourceId: id,
+        method
+      });
+    }
+    if (method === "ap2" && (ap2 === void 0 || !ap2.enabled)) {
+      throw ap2Invalid(
+        path2,
+        `Resource "${id}" requires authorization method "ap2", which is not configured or not enabled under authorization.ap2`,
+        { resourceId: id, method }
+      );
+    }
+    methods.push(method);
+  }
+  if (pricing.type !== "fixed") {
+    throw ap2Invalid(
+      path2,
+      `Resource "${id}" requires authorization but its pricing is "${pricing.type}" - authorization proves a purchase was approved and never replaces payment, so it applies to fixed-price paid resources only in this release`,
+      { resourceId: id }
+    );
+  }
+  return { required: methods };
+}
 function acpInvalid(path2, message, extra = {}) {
   return new CommerceError("CONFIG_INVALID", message, { details: { path: path2, ...extra } });
 }
@@ -1638,20 +2002,23 @@ function validateAcpOperationInput(path2, operation, resource) {
     }
   }
 }
-function normaliseResource(id, entry, protocols, x402) {
+function normaliseResource(id, entry, protocols, x402, ap2) {
   if (entry.input !== void 0) validateResourceSchemaKeywords(id, "input", entry.input);
   const inputProperties = entry.input?.["properties"];
-  if (inputProperties && typeof inputProperties === "object" && PAYMENT_INPUT_FIELD in inputProperties) {
-    throw new CommerceError(
-      "CONFIG_INVALID",
-      `Resource "${id}" declares an input property "${PAYMENT_INPUT_FIELD}", which is reserved for payment proofs`,
-      {
-        details: {
-          path: `resources.${id}.input.properties.${PAYMENT_INPUT_FIELD}`,
-          resourceId: id
+  if (inputProperties && typeof inputProperties === "object") {
+    for (const reserved of RESERVED_INPUT_FIELDS) {
+      if (!(reserved in inputProperties)) continue;
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `Resource "${id}" declares an input property "${reserved}", which is reserved by the gateway`,
+        {
+          details: {
+            path: `resources.${id}.input.properties.${reserved}`,
+            resourceId: id
+          }
         }
-      }
-    );
+      );
+    }
   }
   for (const protocol of entry.expose) {
     if (!SUPPORTED_PROTOCOLS.has(protocol)) {
@@ -1740,6 +2107,7 @@ function normaliseResource(id, entry, protocols, x402) {
     }
   }
   const pricing = entry.pricing.type === "free" ? { type: "free" } : { type: "fixed", amount: entry.pricing.amount, currency: entry.pricing.currency };
+  const authorization = normaliseResourceAuthorization(id, entry, pricing, ap2);
   return {
     id,
     name: entry.name,
@@ -1760,7 +2128,8 @@ function normaliseResource(id, entry, protocols, x402) {
     },
     pricing,
     exposedVia: entry.expose,
-    paymentMethods
+    paymentMethods,
+    ...authorization !== void 0 ? { authorization } : {}
   };
 }
 function defaultClosedObjectSchema(schema) {
@@ -1938,11 +2307,8 @@ function validateInputBindings(id, backend, input) {
     Array.isArray(input?.["required"]) ? input["required"].filter((value) => typeof value === "string") : []
   );
   for (const [location, property] of entries) {
-    if (property === PAYMENT_INPUT_FIELD) {
-      fail(
-        `binds "${location}" to "${PAYMENT_INPUT_FIELD}", which is reserved for payment proofs`,
-        { location }
-      );
+    if (RESERVED_INPUT_FIELDS.includes(property)) {
+      fail(`binds "${location}" to "${property}", which is reserved by the gateway`, { location });
     }
     const other = seen.get(property);
     if (other !== void 0) {
@@ -2163,9 +2529,9 @@ var SECRET_FIELD_NAMES = [
   "adminToken",
   "token"
 ];
+var SECRET_HEADERS = ["authorization", PAYMENT_HEADER, AUTHORIZATION_HEADER];
 var REDACT_PATHS = [
-  "req.headers.authorization",
-  'req.headers["payment-signature"]',
+  ...SECRET_HEADERS.map((name) => `req.headers[${JSON.stringify(name)}]`),
   ...SECRET_FIELD_NAMES,
   ...SECRET_FIELD_NAMES.map((name) => `*.${name}`)
 ];
@@ -2506,6 +2872,33 @@ var PAYMENT_PROVIDER_DETAIL = {
   warn: "payment-provider-degraded",
   fail: "payment-provider-unreachable"
 };
+var AUTHORIZATION_PROVIDER_DETAIL = {
+  pass: void 0,
+  warn: "authorization-provider-degraded",
+  fail: "authorization-provider-unreachable"
+};
+async function probeProvider(provider, kind, details, options) {
+  let health;
+  try {
+    health = await provider.health();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    options.logger.error({ err: message, provider: provider.name }, `${kind} health() threw`);
+    health = { status: "fail", checkedAt: options.clock.nowIso() };
+  }
+  if (health.detail !== void 0) {
+    options.logger.debug(
+      { provider: provider.name, detail: health.detail },
+      `${kind} health detail (not sent to the client)`
+    );
+  }
+  const detail = details[health.status];
+  return {
+    name: provider.name,
+    status: health.status,
+    ...detail !== void 0 ? { detail } : {}
+  };
+}
 async function checkReadiness(options) {
   let storeHealth;
   let storeThrew = false;
@@ -2541,45 +2934,32 @@ async function checkReadiness(options) {
     })
   );
   const paymentProviderChecks = await Promise.all(
-    options.paymentProviders.map(async (provider) => {
-      let health;
-      try {
-        health = await provider.health();
-      } catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        options.logger.error(
-          { err: message, provider: provider.name },
-          "payment provider health() threw"
-        );
-        health = { status: "fail", checkedAt: options.clock.nowIso() };
-      }
-      if (health.detail !== void 0) {
-        options.logger.debug(
-          { provider: provider.name, detail: health.detail },
-          "payment provider health detail (not sent to the client)"
-        );
-      }
-      const detail = PAYMENT_PROVIDER_DETAIL[health.status];
-      return {
-        name: provider.name,
-        status: health.status,
-        ...detail !== void 0 ? { detail } : {}
-      };
-    })
+    options.paymentProviders.map(
+      (provider) => probeProvider(provider, "payment provider", PAYMENT_PROVIDER_DETAIL, options)
+    )
+  );
+  const authorizationProviderChecks = await Promise.all(
+    options.authorizationProviders.map(
+      (provider) => probeProvider(provider, "authorization provider", AUTHORIZATION_PROVIDER_DETAIL, options)
+    )
   );
   const storeReady = storeHealth.status !== "fail";
   const adaptersReady = adapterChecks.every((check) => check.status !== "fail");
   const paymentProvidersReady = paymentProviderChecks.every((check) => check.status !== "fail");
+  const authorizationProvidersReady = authorizationProviderChecks.every(
+    (check) => check.status !== "fail"
+  );
   const storeDetail = storeThrew ? "store-unreachable" : STORE_DETAIL[storeHealth.status];
   return {
-    ready: storeReady && adaptersReady && paymentProvidersReady,
+    ready: storeReady && adaptersReady && paymentProvidersReady && authorizationProvidersReady,
     store: {
       name: "store",
       status: storeHealth.status,
       ...storeDetail !== void 0 ? { detail: storeDetail } : {}
     },
     adapters: adapterChecks,
-    paymentProviders: paymentProviderChecks
+    paymentProviders: paymentProviderChecks,
+    authorizationProviders: authorizationProviderChecks
   };
 }
 var READINESS_TTL_MS = 2e3;
@@ -2633,6 +3013,7 @@ async function buildWellKnownDocument(options) {
     protocols: publicProtocols(options.config.protocols),
     adapters,
     paymentProviders: options.paymentProviders.map((provider) => provider.descriptor),
+    authorizationProviders: options.authorizationProviders.map((provider) => provider.descriptor),
     store: options.store.descriptor,
     payments: {
       ...x402 !== void 0 ? {
@@ -2672,6 +3053,7 @@ function registerRoutes(options) {
     store: options.store,
     adapterRuntimes: options.adapterRuntimes,
     paymentProviders: options.paymentProviders,
+    authorizationProviders: options.authorizationProviders,
     clock: options.clock,
     logger: options.logger
   });
@@ -2686,6 +3068,7 @@ function registerRoutes(options) {
     async () => buildWellKnownDocument({
       config: options.config,
       paymentProviders: options.paymentProviders,
+      authorizationProviders: options.authorizationProviders,
       store: options.store,
       adapterRuntimes: options.adapterRuntimes,
       clock: options.clock
@@ -2781,13 +3164,18 @@ async function handleInvoke(request, reply, options) {
     const paymentValue = Array.isArray(paymentHeader) ? paymentHeader[0] : paymentHeader;
     const paymentMethod = resource.paymentMethods[0];
     const payment = paymentValue !== void 0 && paymentMethod !== void 0 ? { method: paymentMethod, payload: paymentValue } : void 0;
+    const authorization = parseAuthorizationHeader(
+      request.headers[AUTHORIZATION_HEADER],
+      request.id
+    );
     const canonicalRequest = {
       requestId: request.id,
       resourceId,
       input: request.body ?? {},
       protocol: "http",
       receivedAt: options.clock.nowIso(),
-      ...payment !== void 0 ? { payment } : {}
+      ...payment !== void 0 ? { payment } : {},
+      ...authorization !== void 0 ? { authorization } : {}
     };
     const outcome = await options.pipeline.execute(canonicalRequest);
     if (outcome.kind === "payment-required") {
@@ -2873,11 +3261,13 @@ async function createGateway(options) {
   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 eventBus = createEventBus({ store: options.store, logger });
   const pipeline = createExecutionPipeline({
     resources,
     paymentProviders: options.paymentProviders,
+    authorizationProviders,
     store: options.store,
     backend,
     events: eventBus,
@@ -2912,6 +3302,7 @@ async function createGateway(options) {
     resources,
     store: options.store,
     paymentProviders: options.paymentProviders,
+    authorizationProviders,
     eventBus,
     clock,
     adapterRuntimes,
@@ -2955,13 +3346,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) {
@@ -3069,8 +3461,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));
@@ -3087,54 +3479,9 @@ function canonicalize(value) {
 function sha256(value) {
   return createHash("sha256").update(value, "utf8").digest("hex");
 }
-function openSqliteDatabase(options) {
-  const { path: path2, label, logger } = options;
-  const isFileBacked = path2 !== ":memory:";
-  if (isFileBacked) {
-    const dir = dirname(path2);
-    if (dir !== "" && dir !== "." && !existsSync(dir)) {
-      mkdirSync(dir, { recursive: true, mode: 448 });
-    }
-  }
-  if (isFileBacked && existsSync(path2)) {
-    try {
-      accessSync(path2, constants.W_OK);
-    } catch {
-      throw new CommerceError(
-        "STORAGE_ERROR",
-        `${label} "${path2}" exists but is not writable by this process (uid ${typeof process.getuid === "function" ? process.getuid() : "unknown"}). If this is a container that recently changed user, an existing volume may still be owned by the previous one - recreate it (docker compose down -v) or fix its ownership.`,
-        { details: { path: path2 } }
-      );
-    }
-  }
-  if (isFileBacked) {
-    try {
-      closeSync(openSync(path2, "a", 384));
-    } catch {
-    }
-  }
-  const db = new Database(path2);
-  db.pragma("journal_mode = WAL");
-  db.pragma("foreign_keys = ON");
-  if (isFileBacked) restrictDatabasePermissions(path2, label, logger);
-  return db;
-}
-function restrictDatabasePermissions(path2, label, logger) {
-  for (const file of [path2, `${path2}-wal`, `${path2}-shm`]) {
-    try {
-      chmodSync(file, 384);
-    } catch (error) {
-      const code = error.code;
-      if (code === "ENOENT") continue;
-      logger.warn(
-        { file, label, error: code ?? "unknown" },
-        "could not restrict database permissions to owner-only"
-      );
-    }
-  }
-}
 
 // 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;
@@ -3145,33 +3492,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,
@@ -3181,6 +3534,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",
@@ -3196,15 +3550,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;
@@ -3213,13 +3574,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,
@@ -3228,12 +3599,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();
 }
@@ -7641,6 +8012,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;
@@ -7649,8 +8042,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();
@@ -7665,7 +8064,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 = [
@@ -7709,6 +8107,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,
@@ -7797,22 +8196,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":
@@ -7827,16 +8237,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()`.
@@ -7845,11 +8260,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",
@@ -7862,7 +8277,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);
@@ -7871,7 +8287,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",
@@ -7887,14 +8303,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)
+      };
     }
   }
   /**
@@ -7907,7 +8331,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) {
@@ -7934,6 +8358,7 @@ var AcpProtocolAdapter = class {
     this.resources = /* @__PURE__ */ new Map();
     this.idempotency?.close();
     this.idempotency = void 0;
+    this.deployment = void 0;
     this.context = void 0;
   }
 };
@@ -7975,12 +8400,14 @@ function receiptToRow(receipt) {
     backend_status: receipt.backendStatus,
     duration_ms: receipt.durationMs !== void 0 ? receipt.durationMs : null,
     protocol: receipt.protocol !== void 0 ? receipt.protocol : null,
-    metadata_json: receipt.metadata !== void 0 ? JSON.stringify(redact(receipt.metadata)) : null
+    metadata_json: receipt.metadata !== void 0 ? JSON.stringify(redact(receipt.metadata)) : null,
+    authorization_json: receipt.authorization !== void 0 ? JSON.stringify(redact(receipt.authorization)) : null
   };
 }
 function rowToReceipt(row) {
   const payment = row.payment_json !== null ? JSON.parse(row.payment_json) : void 0;
   const metadata = row.metadata_json !== null ? JSON.parse(row.metadata_json) : void 0;
+  const authorization = row.authorization_json !== null ? JSON.parse(row.authorization_json) : void 0;
   return {
     id: row.id,
     requestId: row.request_id,
@@ -7990,7 +8417,8 @@ function rowToReceipt(row) {
     ...payment !== void 0 ? { payment } : {},
     ...row.duration_ms !== null ? { durationMs: row.duration_ms } : {},
     ...row.protocol !== null ? { protocol: row.protocol } : {},
-    ...metadata !== void 0 ? { metadata } : {}
+    ...metadata !== void 0 ? { metadata } : {},
+    ...authorization !== void 0 ? { authorization } : {}
   };
 }
 function eventToRow(event) {
@@ -8099,9 +8527,15 @@ var MIGRATIONS = [
         CREATE INDEX IF NOT EXISTS idx_payment_attempts_created_at ON payment_attempts(created_at);
       `);
     }
+  },
+  {
+    version: 2,
+    up(db) {
+      db.exec(`ALTER TABLE receipts ADD COLUMN authorization_json TEXT;`);
+    }
   }
 ];
-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) {
@@ -8136,8 +8570,8 @@ function createSqliteReceiptStore(options) {
   const db = openSqliteDatabase({ path: path2, label: "Receipt database", logger });
   migrate2(db);
   const insertReceiptStmt = db.prepare(
-    `INSERT INTO receipts (id, request_id, resource_id, payment_json, delivered_at, backend_status, duration_ms, protocol, metadata_json)
-     VALUES (@id, @request_id, @resource_id, @payment_json, @delivered_at, @backend_status, @duration_ms, @protocol, @metadata_json)`
+    `INSERT INTO receipts (id, request_id, resource_id, payment_json, delivered_at, backend_status, duration_ms, protocol, metadata_json, authorization_json)
+     VALUES (@id, @request_id, @resource_id, @payment_json, @delivered_at, @backend_status, @duration_ms, @protocol, @metadata_json, @authorization_json)`
   );
   const getReceiptStmt = db.prepare("SELECT * FROM receipts WHERE id = ?");
   const listReceiptsStmt = db.prepare(
@@ -8187,17 +8621,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})`
         );
       }
     },
@@ -8331,9 +8765,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 {
@@ -8345,7 +8779,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
         };