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

package/dist/guardrails-Di_yI_DW.d.ts

@@ -0,0 +1,25 @@
+/**
+ * How the gateway authenticates to a remote facilitator.
+ *
+ * Deliberately generic: x402 facilitators are not a Coinbase-only category,
+ * and a scheme that only fits one vendor's credentials would make the
+ * abstraction a fiction. `bearer` covers every facilitator that takes a static
+ * token; a facilitator needing per-request signed credentials (CDP's JWT among
+ * them) is not supported yet and is refused rather than silently sent nothing.
+ */
+type FacilitatorAuth = {
+    readonly type: 'none';
+} | {
+    readonly type: 'bearer';
+    readonly token: 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-Bie-9FAM.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-Bie-9FAM.js';
+import { X as X402FacilitatorConfig } from './guardrails-Di_yI_DW.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-CtB0sOnV.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-CtB0sOnV.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.
  */
@@ -353,13 +376,8 @@ 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;
         };
     };
 }
@@ -409,4 +427,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,5 +1,6 @@
-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 { resolveX402Deployment, resolveDeploymentMode, requireNetworkProfile } from './chunk-MQMKQGAB.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-ASK67X56.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-ASK67X56.js';
 import { promises, existsSync, mkdirSync, accessSync, constants, chmodSync } from 'fs';
 import * as path from 'path';
 import { dirname } from 'path';
@@ -952,6 +953,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 } : {}
               }
             }
@@ -1148,6 +1150,10 @@ 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()
+]);
 var FacilitatorSchema = z.discriminatedUnion("mode", [
   z.object({
     mode: z.literal("local"),
@@ -1155,7 +1161,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 +1179,9 @@ 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()
 }).strict();
 var PaymentsSchema = z.object({
   x402: X402Schema.optional()
@@ -1290,14 +1303,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 +1320,26 @@ 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") } : {}
   } : 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,
+      facilitator: x402.facilitator,
+      ...x402.allowMainnet !== void 0 ? { allowMainnet: x402.allowMainnet } : {}
+    });
   }
   const resources = Object.entries(raw.resources).map(
     ([id, entry]) => normaliseResource(id, entry, protocols, x402)
@@ -1365,7 +1384,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 +1420,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 } }
     );
   }
@@ -1755,7 +1774,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 +1832,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 +1852,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,7 +2163,7 @@ 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/v0.2.0-beta";
 async function buildWellKnownDocument(options) {
   const adapters = await Promise.all(
     options.adapterRuntimes.map(async (runtime) => ({
@@ -2172,9 +2193,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 +2339,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 +2364,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 +2373,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]);