@devlab.group/agent-commerce 0.2.0-beta.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,8 +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-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 { 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';
 
@@ -286,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.
@@ -378,6 +378,7 @@ interface GatewayConfig {
             readonly maxTimeoutSeconds: number;
             readonly facilitator: X402FacilitatorConfig;
             readonly allowMainnet?: boolean;
+            readonly allowUnauthenticatedFacilitator?: boolean;
         };
     };
 }

package/dist/index.js

@@ -1,7 +1,7 @@
-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 { 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';
@@ -14,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);
@@ -31,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(
@@ -1111,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"]);
@@ -1152,7 +1187,14 @@ var ResourceEntrySchema = z.object({
 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()
+  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({
@@ -1181,7 +1223,9 @@ var X402Schema = z.object({
   maxTimeoutSeconds: NumberOrString,
   facilitator: FacilitatorSchema,
   /** Real funds. Never defaulted — see src/payments/x402/guardrails.ts. */
-  allowMainnet: BooleanOrString.optional()
+  allowMainnet: BooleanOrString.optional(),
+  /** Accepts a mainnet facilitator that takes no credential. Never defaulted. */
+  allowUnauthenticatedFacilitator: BooleanOrString.optional()
 }).strict();
 var PaymentsSchema = z.object({
   x402: X402Schema.optional()
@@ -1328,7 +1372,13 @@ function normalise(raw) {
       }
     ),
     facilitator,
-    ...x402Raw.allowMainnet !== void 0 ? { allowMainnet: toBoolean(x402Raw.allowMainnet, "payments.x402.allowMainnet") } : {}
+    ...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);
@@ -1337,8 +1387,11 @@ function normalise(raw) {
       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.allowMainnet !== void 0 ? { allowMainnet: x402.allowMainnet } : {},
+      ...x402.allowUnauthenticatedFacilitator !== void 0 ? { allowUnauthenticatedFacilitator: x402.allowUnauthenticatedFacilitator } : {}
     });
   }
   const resources = Object.entries(raw.resources).map(
@@ -1497,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 = {
@@ -1570,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);
@@ -1619,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"];
@@ -2163,13 +2241,17 @@ function createReadinessProbe(options, ttlMs = READINESS_TTL_MS) {
 }
 
 // src/gateway/well-known.ts
-var GATEWAY_SUPPORTED_SPEC = "agent-commerce/v0.2.0-beta";
+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 {
@@ -2724,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");