@devlab.group/agent-commerce 1.3.0 → 1.4.0

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-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 { 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';
 
@@ -599,6 +598,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 +705,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 +733,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 +759,11 @@ function createExecutionPipeline(options) {
           }
         );
       }
+      const authProviders = resolveAuthorizationProviders(
+        options.authorizationProviders ?? [],
+        resource,
+        request.requestId
+      );
       let requirement;
       try {
         requirement = await provider.createRequirement({
@@ -693,7 +794,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 +865,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 +890,7 @@ function createExecutionPipeline(options) {
           "STORAGE_ERROR",
           "Payment attempt could not be recorded"
         );
+        await hold?.finalize("release");
         await safeEmit(
           buildEvent({
             type: "payment.rejected",
@@ -814,6 +925,7 @@ function createExecutionPipeline(options) {
         });
       } catch (error) {
         const uncertainTxHash = uncertainSettlementTxHash(error);
+        await hold?.finalize(uncertainTxHash !== void 0 ? "markUncertain" : "release");
         await safePersist(
           () => options.store.updatePaymentAttempt(
             uncertainTxHash !== void 0 ? { replayKey, status: "settlement-uncertain", externalReference: uncertainTxHash } : {
@@ -848,6 +960,7 @@ function createExecutionPipeline(options) {
         );
       }
       if (settlement.status !== "settled") {
+        await hold?.finalize("release");
         await safePersist(
           () => options.store.updatePaymentAttempt({
             replayKey,
@@ -877,6 +990,7 @@ function createExecutionPipeline(options) {
           }
         );
       }
+      await hold?.finalize("consume");
       await safePersist(
         () => options.store.updatePaymentAttempt({
           replayKey,
@@ -928,6 +1042,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 +1091,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);
@@ -1013,6 +1129,20 @@ function uncertainSettlementTxHash(error) {
   const hash = error.details?.["transactionHash"];
   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 +1150,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 +1364,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 +1413,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 +1446,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 +1548,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 +1611,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 +1639,8 @@ function normalise(raw) {
     resources,
     payments: {
       ...x402 !== void 0 ? { x402 } : {}
-    }
+    },
+    ...ap2 !== void 0 ? { authorization: { ap2 } } : {}
   };
 }
 function validateMountPaths(protocols) {
@@ -1499,6 +1663,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 +1990,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 +2095,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 +2116,8 @@ function normaliseResource(id, entry, protocols, x402) {
     },
     pricing,
     exposedVia: entry.expose,
-    paymentMethods
+    paymentMethods,
+    ...authorization !== void 0 ? { authorization } : {}
   };
 }
 function defaultClosedObjectSchema(schema) {
@@ -1938,11 +2295,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 +2517,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 +2860,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 +2922,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 +3001,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 +3041,7 @@ function registerRoutes(options) {
     store: options.store,
     adapterRuntimes: options.adapterRuntimes,
     paymentProviders: options.paymentProviders,
+    authorizationProviders: options.authorizationProviders,
     clock: options.clock,
     logger: options.logger
   });
@@ -2686,6 +3056,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 +3152,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 +3249,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 +3290,7 @@ async function createGateway(options) {
     resources,
     store: options.store,
     paymentProviders: options.paymentProviders,
+    authorizationProviders,
     eventBus,
     clock,
     adapterRuntimes,
@@ -3087,52 +3466,6 @@ 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 ACP_MAX_IDEMPOTENCY_KEY_LENGTH = 255;
@@ -7975,12 +8308,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 +8325,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,6 +8435,12 @@ 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;
@@ -8136,8 +8478,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(