@devlab.group/agent-commerce 0.1.0-alpha.0 → 1.0.0

package/dist/guardrails-Dmwi63KB.d.ts

@@ -0,0 +1,38 @@
+/**
+ * How the gateway authenticates to a remote facilitator.
+ *
+ * Deliberately a list, not a vendor: x402 facilitators are not a Coinbase-only
+ * category, and a scheme that only fitted one vendor's credentials would make
+ * the abstraction a fiction.
+ *
+ * - `none` — the facilitator takes no credential (the public testnet one).
+ * - `bearer` — a static token. Covers most self-hosted and third-party
+ * facilitators, and needs nothing installed.
+ * - `cdp` — Coinbase Developer Platform, which signs a fresh JWT per request
+ * over method + host + path, so a static header cannot express it. Handled by
+ * the optional peer `@coinbase/x402`, imported only when this type is
+ * configured. Anyone not using CDP never installs it.
+ *
+ * A facilitator whose scheme is none of these is refused at config load rather
+ * than sent nothing.
+ */
+type FacilitatorAuth = {
+    readonly type: 'none';
+} | {
+    readonly type: 'bearer';
+    readonly token: string;
+} | {
+    readonly type: 'cdp';
+    readonly apiKeyId: string;
+    readonly apiKeySecret: string;
+};
+type X402FacilitatorConfig = {
+    readonly mode: 'local';
+    readonly signerPrivateKey: string;
+} | {
+    readonly mode: 'remote';
+    readonly url: string;
+    readonly auth: FacilitatorAuth;
+};
+
+export type { FacilitatorAuth as F, X402FacilitatorConfig as X };

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import { I as IsoTimestamp, D as DecimalAmount, P as PaymentMethodName, B as BackendHandler, A as AdapterDescriptor, a as AdapterHealth, C as CommerceResource, R as ResourceRegistry, b as PaymentProvider, L as Logger, c as Clock, d as IdGenerator } from './runtime-LCk2TzGN.js';
-export { e as BackendMethod, f as DEFAULT_BACKEND_TIMEOUT_MS, J as JsonSchema, N as NOOP_LOGGER, g as PaymentChallenge, h as PaymentContext, i as PaymentRequirement, j as PaymentResult, k as PaymentSettlementContext, l as PaymentSubmission, m as PaymentVerificationContext, n as Pricing, o as ProtocolName, s as systemClock } from './runtime-LCk2TzGN.js';
-import { D as DeliveredOutcome, P as PaymentRequiredOutcome, C as CommerceEvent, a as PaymentAttempt, b as CommerceReceipt, E as ExecutionPipeline, c as ProtocolAdapter } from './protocol-adapter-C0goMgLK.js';
-export { d as COMMERCE_EVENT_TYPES, e as CanonicalRequest, f as CommerceEventType, g as EventSink, h as ExecutionOutcome, H as HttpProtocolAdapter, i as ProtocolAdapterContext, j as isHttpProtocolAdapter } from './protocol-adapter-C0goMgLK.js';
+import { I as IsoTimestamp, D as DecimalAmount, P as PaymentMethodName, B as BackendHandler, A as AdapterDescriptor, a as AdapterHealth, C as CommerceResource, R as ResourceRegistry, b as PaymentProvider, L as Logger, c as Clock, d as IdGenerator } from './runtime-B-9IjMbO.js';
+export { e as BackendMethod, f as DEFAULT_BACKEND_TIMEOUT_MS, J as JsonSchema, N as NOOP_LOGGER, g as PaymentChallenge, h as PaymentContext, i as PaymentRequirement, j as PaymentResult, k as PaymentSettlementContext, l as PaymentSubmission, m as PaymentVerificationContext, n as Pricing, o as ProtocolName, s as systemClock } from './runtime-B-9IjMbO.js';
+import { X as X402FacilitatorConfig } from './guardrails-Dmwi63KB.js';
+import { D as DeliveredOutcome, P as PaymentRequiredOutcome, C as CommerceEvent, a as PaymentAttempt, b as CommerceReceipt, E as ExecutionPipeline, c as ProtocolAdapter } from './protocol-adapter-CZPOb9uG.js';
+export { d as COMMERCE_EVENT_TYPES, e as CanonicalRequest, f as CommerceEventType, g as EventSink, h as ExecutionOutcome, H as HttpProtocolAdapter, i as ProtocolAdapterContext, j as isHttpProtocolAdapter } from './protocol-adapter-CZPOb9uG.js';
 import { FastifyInstance } from 'fastify';
 import 'node:http';
 
@@ -93,13 +94,29 @@ declare function toCommerceError(value: unknown, fallbackCode?: CommerceErrorCod
 
 /**
  * Reserved input property carrying a payment proof on protocols that have no
- * header channel (MCP tool calls). Over HTTP the `X-PAYMENT` header is used.
+ * header channel (MCP tool calls). Over HTTP the `PAYMENT-SIGNATURE` header is
+ * used.
  */
 declare const PAYMENT_INPUT_FIELD = "_payment";
-/** HTTP header carrying the payment proof. */
-declare const PAYMENT_HEADER = "x-payment";
-/** HTTP response header carrying the settlement reference. */
-declare const PAYMENT_RESPONSE_HEADER = "x-payment-response";
+/**
+ * HTTP request header carrying the payment proof.
+ *
+ * x402 v2 header names, lowercased because that is how Node presents incoming
+ * headers. v1's `X-PAYMENT` / `X-PAYMENT-RESPONSE` pair is not accepted: this
+ * gateway speaks one protocol version, and quietly honouring both would mean
+ * two verification paths for the same money.
+ */
+declare const PAYMENT_HEADER = "payment-signature";
+/** HTTP response header carrying the settlement result. */
+declare const PAYMENT_RESPONSE_HEADER = "payment-response";
+/**
+ * HTTP response header carrying the base64 payment challenge on a 402.
+ *
+ * The 402 body still carries {@link PaymentRequiredEnvelope} — richer, and the
+ * only channel MCP has — but an x402 v2 client reads the challenge from this
+ * header and ignores the body, so both are sent.
+ */
+declare const PAYMENT_REQUIRED_HEADER = "payment-required";
 /**
  * Key under which a protocol adapter attaches a {@link DeliverySummary} to its
  * result metadata — MCP's `CallToolResult._meta`, and anywhere else a protocol
@@ -130,6 +147,12 @@ interface PaymentRequiredEnvelope {
         readonly expiresAt?: IsoTimestamp;
         /** Provider-native requirement objects, passed through verbatim. */
         readonly accepts: readonly Readonly<Record<string, unknown>>[];
+        /**
+         * The provider's own challenge document, verbatim — see
+         * {@link PaymentChallenge.envelope}. Present for providers that have one;
+         * a buyer's protocol client can hand this straight to its SDK.
+         */
+        readonly envelope?: Readonly<Record<string, unknown>>;
     };
 }
 interface ErrorEnvelope {
@@ -150,7 +173,7 @@ interface ErrorEnvelope {
  * `/api/receipts` is an operator route behind `server.adminToken`.
  *
  * Before this existed the two surfaces disagreed: HTTP callers received a
- * settlement summary in `X-PAYMENT-RESPONSE` while MCP callers received
+ * settlement summary in the payment-response header while MCP callers received
  * nothing, so an MCP buyer's only route to their own receipt was the merchant's
  * ledger. Both surfaces now emit this same shape.
  */
@@ -263,7 +286,7 @@ interface ReceiptStore {
      * Receipts whose delivery did not succeed — `backendStatus` outside 2xx.
      *
      * A paid-but-undelivered purchase is the one row a merchant must notice:
-     * settlement is final and v0.1 has no refunds, so *seeing* it is the only
+     * settlement is final and this release has no refunds, so *seeing* it is the only
      * remedy available. Counted rather than listed for the same reason as
      * {@link countReceipts} — `listReceipts` is clamped, so counting by list
      * length silently saturates.
@@ -353,13 +376,9 @@ interface GatewayConfig {
             readonly assetDecimals: number;
             readonly payTo: string;
             readonly maxTimeoutSeconds: number;
-            readonly facilitator: {
-                readonly mode: 'local';
-                readonly signerPrivateKey: string;
-            } | {
-                readonly mode: 'remote';
-                readonly url: string;
-            };
+            readonly facilitator: X402FacilitatorConfig;
+            readonly allowMainnet?: boolean;
+            readonly allowUnauthenticatedFacilitator?: boolean;
         };
     };
 }
@@ -409,4 +428,4 @@ interface SqliteReceiptStoreOptions {
 }
 declare function createSqliteReceiptStore(options: SqliteReceiptStoreOptions): ReceiptStore;
 
-export { AdapterDescriptor, AdapterHealth, type BackendExecutor, BackendHandler, type BackendRequest, type BackendResponse, COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, Clock, CommerceError, type CommerceErrorCode, type CommerceErrorInfo, type CommerceErrorOptions, CommerceEvent, CommerceReceipt, CommerceResource, DELIVERY_SUMMARY_META_KEY, DecimalAmount, DeliveredOutcome, type DeliverySummary, type ErrorEnvelope, ExecutionPipeline, type GatewayConfig, type GatewayInstance, type GatewayOptions, IdGenerator, IsoTimestamp, type ListOptions, Logger, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_RESPONSE_HEADER, PaymentAttempt, type PaymentAttemptReservation, type PaymentAttemptUpdate, PaymentMethodName, PaymentProvider, type PaymentRequiredEnvelope, PaymentRequiredOutcome, ProtocolAdapter, RETRYABLE_ERROR_CODES, type ReceiptStore, ResourceRegistry, createGateway, createSqliteReceiptStore, isCommerceError, isPaymentRequiredEnvelope, loadConfig, parseConfig, createSqliteReceiptStore as receipts, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope };
+export { AdapterDescriptor, AdapterHealth, type BackendExecutor, BackendHandler, type BackendRequest, type BackendResponse, COMMERCE_ERROR_CODES, COMMERCE_ERROR_HTTP_STATUS, Clock, CommerceError, type CommerceErrorCode, type CommerceErrorInfo, type CommerceErrorOptions, CommerceEvent, CommerceReceipt, CommerceResource, DELIVERY_SUMMARY_META_KEY, DecimalAmount, DeliveredOutcome, type DeliverySummary, type ErrorEnvelope, ExecutionPipeline, type GatewayConfig, type GatewayInstance, type GatewayOptions, IdGenerator, IsoTimestamp, type ListOptions, Logger, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PaymentAttempt, type PaymentAttemptReservation, type PaymentAttemptUpdate, PaymentMethodName, PaymentProvider, type PaymentRequiredEnvelope, PaymentRequiredOutcome, ProtocolAdapter, RETRYABLE_ERROR_CODES, type ReceiptStore, ResourceRegistry, createGateway, createSqliteReceiptStore, isCommerceError, isPaymentRequiredEnvelope, loadConfig, parseConfig, createSqliteReceiptStore as receipts, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope };

package/dist/index.js

@@ -1,6 +1,7 @@
-import { CommerceError, PAYMENT_INPUT_FIELD, systemClock, NOOP_LOGGER, PACKAGE_VERSION, toCommerceError, DEFAULT_BACKEND_TIMEOUT_MS, toErrorEnvelope, isHttpProtocolAdapter, isCommerceError, PAYMENT_HEADER, toPaymentRequiredEnvelope, PAYMENT_RESPONSE_HEADER } from './chunk-CZ6ZDAYD.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_RESPONSE_HEADER, RETRYABLE_ERROR_CODES, isCommerceError, isHttpProtocolAdapter, isPaymentRequiredEnvelope, systemClock, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope } from './chunk-CZ6ZDAYD.js';
-import { promises, existsSync, mkdirSync, accessSync, constants, chmodSync } from 'fs';
+import { resolveX402Deployment, resolveDeploymentMode, requireNetworkProfile } from './chunk-MEPETSP6.js';
+import { 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-BQNE3A5H.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, RETRYABLE_ERROR_CODES, isCommerceError, isHttpProtocolAdapter, isPaymentRequiredEnvelope, systemClock, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope } from './chunk-BQNE3A5H.js';
+import { promises, existsSync, mkdirSync, accessSync, constants, closeSync, openSync, chmodSync } from 'fs';
 import * as path from 'path';
 import { dirname } from 'path';
 import { parse, YAMLError } from 'yaml';
@@ -13,6 +14,9 @@ import Database from 'better-sqlite3';
 
 // src/config/env.ts
 var PLACEHOLDER_PATTERN = /\$\{([A-Za-z_][A-Za-z0-9_]*)(:-([^}]*))?\}/g;
+var BRACE_TOKEN = /\$\{[^{}]*\}/g;
+var SUPPORTED_TOKEN = /^\$\{[A-Za-z_][A-Za-z0-9_]*(:-[^}]*)?\}$/;
+var NESTED_PLACEHOLDER = /\$\{[^{}]*\$\{/;
 function substituteEnv(value, env, path2 = "$") {
   if (typeof value === "string") {
     return substituteString(value, env, path2);
@@ -30,19 +34,26 @@ function substituteEnv(value, env, path2 = "$") {
   return value;
 }
 function substituteString(value, env, path2) {
-  const substituted = substituteOnce(value, env, path2);
-  PLACEHOLDER_PATTERN.lastIndex = 0;
-  if (PLACEHOLDER_PATTERN.test(substituted)) {
-    PLACEHOLDER_PATTERN.lastIndex = 0;
-    const residual = PLACEHOLDER_PATTERN.exec(substituted)?.[0] ?? "${\u2026}";
-    PLACEHOLDER_PATTERN.lastIndex = 0;
+  assertTemplateIsSupported(value, path2);
+  return substituteOnce(value, env, path2);
+}
+function assertTemplateIsSupported(value, path2) {
+  if (NESTED_PLACEHOLDER.test(value)) {
+    throw new CommerceError(
+      "CONFIG_INVALID",
+      `Configuration value at "${path2}" nests placeholders (e.g. "\${A:-\${B}}"), which is not supported \u2014 the inner one is not resolved and its closing brace ends up in the value. Use a plain default, or set the variable.`,
+      { details: { path: path2 } }
+    );
+  }
+  BRACE_TOKEN.lastIndex = 0;
+  for (const [token] of value.matchAll(BRACE_TOKEN)) {
+    if (SUPPORTED_TOKEN.test(token)) continue;
     throw new CommerceError(
       "CONFIG_INVALID",
-      `Configuration value at "${path2}" still contains the unresolved placeholder "${residual}" after substitution \u2014 nested placeholders (e.g. "\${A:-\${B}}") are not supported. Use a plain default, or set the variable.`,
-      { details: { path: path2, residual } }
+      `Configuration value at "${path2}" contains "${token}", which is not a supported placeholder. Only "\${VAR}" and "\${VAR:-default}" are recognised; shell forms such as "\${VAR-default}", "\${VAR:=default}" and "\${VAR:?message}" would load as literal text.`,
+      { details: { path: path2, token } }
     );
   }
-  return substituted;
 }
 function substituteOnce(value, env, path2) {
   return value.replace(
@@ -952,6 +963,7 @@ function createExecutionPipeline(options) {
                 provider: paymentResult.provider,
                 amount: paymentResult.amount,
                 currency: paymentResult.currency,
+                ...paymentResult.network !== void 0 ? { network: paymentResult.network } : {},
                 ...paymentResult.externalReference !== void 0 ? { externalReference: paymentResult.externalReference } : {}
               }
             }
@@ -1109,11 +1121,36 @@ var StorageSchema = z.object({
     path: z.string().min(1)
   }).strict()
 }).strict();
+var RESERVED_GATEWAY_PATHS = [
+  "/health",
+  "/ready",
+  "/.well-known/agent-commerce",
+  "/api/resources",
+  "/api/resources/:id/invoke",
+  "/api/receipts",
+  "/api/events",
+  "/api/events/stream"
+];
+var McpMountPathSchema = z.string().min(1).refine((value) => value.startsWith("/"), {
+  message: 'must start with "/" \u2014 it is an absolute gateway path, e.g. "/mcp".'
+}).refine((value) => !/[:*?\s]/.test(value), {
+  message: 'must not contain ":", "*", "?" or whitespace \u2014 the mount is a literal path prefix, not a Fastify route pattern, and registers its own wildcard.'
+}).refine(
+  (value) => {
+    const base = value.replace(/\/+$/, "");
+    return !RESERVED_GATEWAY_PATHS.some(
+      (reserved) => reserved === base || reserved.startsWith(`${base}/`)
+    );
+  },
+  {
+    message: `must not collide with a route the gateway already serves (${RESERVED_GATEWAY_PATHS.join(", ")}); pick a dedicated prefix such as "/mcp".`
+  }
+);
 var ProtocolsSchema = z.object({
   http: z.object({ enabled: BooleanOrString }).strict(),
   mcp: z.object({
     enabled: BooleanOrString,
-    mountPath: z.string().min(1)
+    mountPath: McpMountPathSchema
   }).strict()
 }).strict();
 var BackendMethodSchema = z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]);
@@ -1148,6 +1185,17 @@ var ResourceEntrySchema = z.object({
   payments: z.array(z.string().min(1)).optional()
 }).strict();
 var ResourcesMapSchema = z.record(z.string().min(1), ResourceEntrySchema);
+var FacilitatorAuthSchema = z.discriminatedUnion("type", [
+  z.object({ type: z.literal("none") }).strict(),
+  z.object({ type: z.literal("bearer"), token: z.string().min(1) }).strict(),
+  // Coinbase Developer Platform. Needs the optional peer `@coinbase/x402`,
+  // which signs a fresh JWT per request; a static header cannot express it.
+  z.object({
+    type: z.literal("cdp"),
+    apiKeyId: z.string().min(1),
+    apiKeySecret: z.string().min(1)
+  }).strict()
+]);
 var FacilitatorSchema = z.discriminatedUnion("mode", [
   z.object({
     mode: z.literal("local"),
@@ -1155,7 +1203,12 @@ var FacilitatorSchema = z.discriminatedUnion("mode", [
   }).strict(),
   z.object({
     mode: z.literal("remote"),
-    url: z.string().min(1)
+    url: z.string().min(1),
+    // Absent means "this facilitator takes no credential" — an explicit
+    // statement, normalised to `{ type: 'none' }` below. On a mainnet that
+    // combination is refused outright, so the default can never quietly
+    // become an unauthenticated production facilitator.
+    auth: FacilitatorAuthSchema.optional()
   }).strict()
 ]);
 var X402Schema = z.object({
@@ -1168,7 +1221,11 @@ var X402Schema = z.object({
   assetDecimals: NumberOrString,
   payTo: z.string().min(1),
   maxTimeoutSeconds: NumberOrString,
-  facilitator: FacilitatorSchema
+  facilitator: FacilitatorSchema,
+  /** Real funds. Never defaulted — see src/payments/x402/guardrails.ts. */
+  allowMainnet: BooleanOrString.optional(),
+  /** Accepts a mainnet facilitator that takes no credential. Never defaulted. */
+  allowUnauthenticatedFacilitator: BooleanOrString.optional()
 }).strict();
 var PaymentsSchema = z.object({
   x402: X402Schema.optional()
@@ -1290,14 +1347,12 @@ function normalise(raw) {
     }
   };
   const x402Raw = raw.payments.x402;
-  if (x402Raw?.facilitator.mode === "remote") {
-    throw new CommerceError(
-      "CONFIG_INVALID",
-      'payments.x402.facilitator.mode "remote" is not supported in v0.1.0-alpha; use "local" (the deterministic dev-chain facilitator)',
-      { details: { path: "payments.x402.facilitator.mode" } }
-    );
-  }
-  const x402 = x402Raw ? {
+  const facilitator = x402Raw === void 0 ? void 0 : x402Raw.facilitator.mode === "local" ? { mode: "local", signerPrivateKey: x402Raw.facilitator.signerPrivateKey } : {
+    mode: "remote",
+    url: x402Raw.facilitator.url,
+    auth: x402Raw.facilitator.auth ?? { type: "none" }
+  };
+  const x402 = x402Raw && facilitator ? {
     enabled: toBoolean(x402Raw.enabled, "payments.x402.enabled"),
     network: x402Raw.network,
     rpcUrl: x402Raw.rpcUrl,
@@ -1309,18 +1364,35 @@ function normalise(raw) {
       max: 36
     }),
     payTo: x402Raw.payTo,
-    maxTimeoutSeconds: toNumber(x402Raw.maxTimeoutSeconds, "payments.x402.maxTimeoutSeconds", {
-      min: 1
-    }),
-    // Only "local" can reach here — "remote" was rejected above.
-    facilitator: {
-      mode: "local",
-      signerPrivateKey: x402Raw.facilitator.signerPrivateKey
-    }
+    maxTimeoutSeconds: toNumber(
+      x402Raw.maxTimeoutSeconds,
+      "payments.x402.maxTimeoutSeconds",
+      {
+        min: 1
+      }
+    ),
+    facilitator,
+    ...x402Raw.allowMainnet !== void 0 ? { allowMainnet: toBoolean(x402Raw.allowMainnet, "payments.x402.allowMainnet") } : {},
+    ...x402Raw.allowUnauthenticatedFacilitator !== void 0 ? {
+      allowUnauthenticatedFacilitator: toBoolean(
+        x402Raw.allowUnauthenticatedFacilitator,
+        "payments.x402.allowUnauthenticatedFacilitator"
+      )
+    } : {}
   } : void 0;
   if (x402) {
     validateAddress("payments.x402.payTo", x402.payTo);
     validateAddress("payments.x402.asset", x402.asset);
+    resolveX402Deployment({
+      network: x402.network,
+      payTo: x402.payTo,
+      asset: x402.asset,
+      assetName: x402.assetName,
+      assetVersion: x402.assetVersion,
+      facilitator: x402.facilitator,
+      ...x402.allowMainnet !== void 0 ? { allowMainnet: x402.allowMainnet } : {},
+      ...x402.allowUnauthenticatedFacilitator !== void 0 ? { allowUnauthenticatedFacilitator: x402.allowUnauthenticatedFacilitator } : {}
+    });
   }
   const resources = Object.entries(raw.resources).map(
     ([id, entry]) => normaliseResource(id, entry, protocols, x402)
@@ -1365,7 +1437,7 @@ function normaliseResource(id, entry, protocols, x402) {
   }
   for (const protocol of entry.expose) {
     if (!SUPPORTED_PROTOCOLS.has(protocol)) {
-      const hint = protocol === "ucp" ? " (UCP is planned, not supported in v0.1.0-alpha)" : "";
+      const hint = protocol === "ucp" ? " (UCP is planned, not supported in this release)" : "";
       throw new CommerceError(
         "CONFIG_INVALID",
         `Resource "${id}" exposes unsupported protocol "${protocol}"${hint}. Supported: http, mcp.`,
@@ -1401,7 +1473,7 @@ function normaliseResource(id, entry, protocols, x402) {
   if (entry.pricing.type === "dynamic") {
     throw new CommerceError(
       "CONFIG_INVALID",
-      `Resource "${id}" uses pricing.type "dynamic", which is not supported in v0.1.0-alpha`,
+      `Resource "${id}" uses pricing.type "dynamic", which is not supported in this release`,
       { details: { path: `resources.${id}.pricing.type`, resourceId: id } }
     );
   }
@@ -1478,6 +1550,10 @@ function defaultClosedObjectSchema(schema) {
   if (isPlainObject4(items)) {
     result["items"] = defaultClosedObjectSchema(items);
   }
+  const additional = schema["additionalProperties"];
+  if (isPlainObject4(additional)) {
+    result["additionalProperties"] = defaultClosedObjectSchema(additional);
+  }
   return result;
 }
 var EMPTY_CLOSED_OBJECT_SCHEMA = {
@@ -1551,6 +1627,10 @@ function validateResourceSchemaKeywords(id, path2, schema) {
       if (isPlainObject4(sub)) validateResourceSchemaKeywords(id, `${path2}.properties.${key}`, sub);
     }
   }
+  const additional = schema["additionalProperties"];
+  if (isPlainObject4(additional)) {
+    validateResourceSchemaKeywords(id, `${path2}.additionalProperties`, additional);
+  }
   const items = schema["items"];
   if (isPlainObject4(items)) {
     validateResourceSchemaKeywords(id, `${path2}.items`, items);
@@ -1600,6 +1680,23 @@ function validatePathParametersDeclared(id, url, input) {
   }
   const params = extractPathParameterNames(url);
   if (params.length === 0) return;
+  const firstBrace = url.indexOf("{");
+  if (firstBrace !== -1) {
+    const prefix = url.slice(0, firstBrace);
+    let origin;
+    try {
+      const parsedPrefix = new URL(prefix);
+      origin = parsedPrefix.hostname === "" ? void 0 : parsedPrefix.origin;
+    } catch {
+    }
+    if (origin === void 0 || !prefix.startsWith(`${origin}/`)) {
+      throw new CommerceError(
+        "CONFIG_INVALID",
+        `Resource "${id}" has a backend.url parameter before the end of the host ("${url}"). A caller-supplied value would choose which host the gateway calls, which is request forgery with the gateway's own network position. Parameters are supported inside the path and query only`,
+        { details: { path: `resources.${id}.backend.url`, resourceId: id } }
+      );
+    }
+  }
   const propertiesRaw = input?.["properties"];
   const properties = isPlainObject4(propertiesRaw) ? propertiesRaw : {};
   const requiredRaw = input?.["required"];
@@ -1755,7 +1852,7 @@ var SECRET_FIELD_NAMES = [
 ];
 var REDACT_PATHS = [
   "req.headers.authorization",
-  'req.headers["x-payment"]',
+  'req.headers["payment-signature"]',
   ...SECRET_FIELD_NAMES,
   ...SECRET_FIELD_NAMES.map((name) => `*.${name}`)
 ];
@@ -1813,7 +1910,8 @@ function wrapPino(instance) {
   return logger;
 }
 var CORS_METHODS = "GET,POST,DELETE,OPTIONS";
-var CORS_HEADERS = "content-type,x-payment,x-request-id,authorization";
+var CORS_HEADERS = "content-type,payment-signature,x-request-id,authorization";
+var CORS_EXPOSED_HEADERS = "payment-required,payment-response,x-request-id";
 function buildAccessControlHook(options) {
   const allowedOrigins = new Set(options.allowedOrigins.map((origin) => origin.toLowerCase()));
   const publicHostname = hostnameOf(options.publicBaseUrl);
@@ -1832,6 +1930,7 @@ function buildAccessControlHook(options) {
       reply.header("access-control-allow-origin", origin);
       reply.header("access-control-allow-methods", CORS_METHODS);
       reply.header("access-control-allow-headers", CORS_HEADERS);
+      reply.header("access-control-expose-headers", CORS_EXPOSED_HEADERS);
       reply.header("vary", "Origin");
       if (request.method === "OPTIONS") {
         reply.status(204).send();
@@ -2142,13 +2241,17 @@ function createReadinessProbe(options, ttlMs = READINESS_TTL_MS) {
 }
 
 // src/gateway/well-known.ts
-var GATEWAY_SUPPORTED_SPEC = "agent-commerce/v0.1.0-alpha";
+var GATEWAY_SUPPORTED_SPEC = "agent-commerce/v1.0.0";
+function publicHealth(health) {
+  const { detail: _detail, ...rest } = health;
+  return rest;
+}
 async function buildWellKnownDocument(options) {
   const adapters = await Promise.all(
-    options.adapterRuntimes.map(async (runtime) => ({
-      ...runtime.adapter.descriptor,
-      health: await getAdapterHealth(runtime, options.clock)
-    }))
+    options.adapterRuntimes.map(async (runtime) => {
+      const health = await getAdapterHealth(runtime, options.clock);
+      return { ...runtime.adapter.descriptor, health: publicHealth(health) };
+    })
   );
   const x402 = options.config.payments.x402;
   return {
@@ -2172,9 +2275,18 @@ async function buildWellKnownDocument(options) {
           assetDecimals: x402.assetDecimals,
           payTo: x402.payTo,
           maxTimeoutSeconds: x402.maxTimeoutSeconds,
-          // Never the signerPrivateKey — only whether the facilitator is
-          // local (dev-chain only) or remote, plus its (non-secret) URL.
-          facilitator: x402.facilitator.mode === "local" ? { mode: "local" } : { mode: "remote", url: x402.facilitator.url }
+          // Never the signerPrivateKey, and never the facilitator URL:
+          // a facilitator endpoint is a per-deployment operational detail
+          // that can carry a tenant path or an API key, exactly like
+          // `rpcUrl` above. Only whether it is local or remote is public.
+          facilitator: { mode: x402.facilitator.mode },
+          // Chain id 84532 is shared between the local dev chain and
+          // public Base Sepolia, so the network id alone cannot say which
+          // one a client is talking to. This can.
+          mode: resolveDeploymentMode(
+            requireNetworkProfile(x402.network, "payments.x402.network"),
+            x402.facilitator.mode
+          )
         }
       } : {}
     }
@@ -2309,7 +2421,12 @@ async function handleInvoke(request, reply, options) {
     };
     const outcome = await options.pipeline.execute(canonicalRequest);
     if (outcome.kind === "payment-required") {
-      reply.status(402).send(toPaymentRequiredEnvelope(outcome));
+      const envelope = toPaymentRequiredEnvelope(outcome);
+      if (envelope.payment.envelope !== void 0) {
+        reply.header(PAYMENT_REQUIRED_HEADER, encodeHeaderDocument(envelope.payment.envelope));
+      }
+      reply.header("cache-control", "no-store");
+      reply.status(402).send(envelope);
       return;
     }
     if (outcome.payment) {
@@ -2329,7 +2446,7 @@ function errorPaymentSummary(error) {
   const payment = error.details?.["payment"];
   if (typeof payment !== "object" || payment === null) return void 0;
   const rec = payment;
-  const { status, provider, amount, currency, externalReference } = rec;
+  const { status, provider, amount, currency, network, externalReference } = rec;
   if (typeof status !== "string" || typeof provider !== "string" || typeof amount !== "string" || typeof currency !== "string") {
     return void 0;
   }
@@ -2338,18 +2455,24 @@ function errorPaymentSummary(error) {
     provider,
     amount,
     currency,
+    ...typeof network === "string" ? { network } : {},
     ...typeof externalReference === "string" ? { externalReference } : {}
   };
 }
+function encodeHeaderDocument(document) {
+  return Buffer.from(JSON.stringify(document), "utf8").toString("base64");
+}
 function encodePaymentSummary(payment) {
-  const summary = {
+  return encodeHeaderDocument({
+    success: payment.status === "settled",
+    transaction: payment.externalReference ?? "",
+    network: payment.network ?? "",
     status: payment.status,
     provider: payment.provider,
     amount: payment.amount,
     currency: payment.currency,
     ...payment.externalReference !== void 0 ? { externalReference: payment.externalReference } : {}
-  };
-  return Buffer.from(JSON.stringify(summary), "utf8").toString("base64");
+  });
 }
 function parseLimit(value) {
   if (Array.isArray(value)) return parseLimit(value[0]);
@@ -2683,6 +2806,12 @@ function createSqliteReceiptStore(options) {
       );
     }
   }
+  if (isFileBacked) {
+    try {
+      closeSync(openSync(path2, "a", 384));
+    } catch {
+    }
+  }
   const db = new Database(path2);
   db.pragma("journal_mode = WAL");
   db.pragma("foreign_keys = ON");