@devlab.group/agent-commerce 1.2.0 → 1.4.0

package/dist/index.d.ts

@@ -1,10 +1,13 @@
-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-Bqg9qW3t.js';
-export { e as BackendMethod, f as DEFAULT_BACKEND_TIMEOUT_MS, J as JsonSchema, N as NOOP_LOGGER, g as PROTOCOL_NAMES, h as PaymentChallenge, i as PaymentContext, j as PaymentRequirement, k as PaymentResult, l as PaymentSettlementContext, m as PaymentSubmission, n as PaymentVerificationContext, o as Pricing, p as ProtocolName, s as systemClock } from './runtime-Bqg9qW3t.js';
+import { f as Ap2AuthorizationConfig } from './types-CJtwLu1c.js';
+import { I as IsoTimestamp, D as DecimalAmount, P as PaymentMethodName, a as CommerceResource, b as PaymentSubmission, B as BackendHandler, A as AdapterDescriptor, c as AdapterHealth, R as ResourceRegistry, d as PaymentProvider, L as Logger, C as Clock, e as IdGenerator } from './runtime-CKq3d_3K.js';
+export { f as AuthorizationMethodName, g as BackendMethod, h as DEFAULT_BACKEND_TIMEOUT_MS, J as JsonSchema, N as NOOP_LOGGER, i as PROTOCOL_NAMES, j as PaymentChallenge, k as PaymentContext, l as PaymentRequirement, m as PaymentResult, n as PaymentSettlementContext, o as PaymentVerificationContext, p as Pricing, q as ProtocolName, s as systemClock } from './runtime-CKq3d_3K.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-BAKGnuZ4.js';
-export { A as AdapterHttpRoute, 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-BAKGnuZ4.js';
+import { a as AuthorizationRequirement, b as AuthorizationSubmission, A as AuthorizationProvider } from './authorization-CPDcpJVa.js';
+export { c as AuthorizationFinalizeContext, d as AuthorizationRecord, e as AuthorizationVerification, f as AuthorizationVerificationContext } from './authorization-CPDcpJVa.js';
+import { D as DeliveredOutcome, P as PaymentRequiredOutcome, C as CommerceEvent, a as PaymentAttempt, b as CommerceReceipt, E as ExecutionPipeline, c as ProtocolAdapter, H as HttpProtocolAdapter, A as AdapterHttpRoute, d as ProtocolAdapterContext } from './protocol-adapter-CaMZj6Wm.js';
+export { e as COMMERCE_EVENT_TYPES, f as CanonicalRequest, g as CommerceEventType, h as EventSink, i as ExecutionOutcome, j as isHttpProtocolAdapter } from './protocol-adapter-CaMZj6Wm.js';
 import { FastifyInstance } from 'fastify';
-import 'node:http';
+import { IncomingMessage, ServerResponse } from 'node:http';
 
 /**
  * Typed domain error codes.
@@ -12,7 +15,7 @@ import 'node:http';
  * FROZEN CONTRACT. Protocol adapters map these codes into their own response
  * format. Never throw a bare string or untyped Error across a package boundary.
  */
-declare const COMMERCE_ERROR_CODES: readonly ["CONFIG_INVALID", "RESOURCE_NOT_FOUND", "INPUT_INVALID", "PAYMENT_REQUIRED", "PAYMENT_INVALID", "PAYMENT_REPLAYED", "PAYMENT_PROVIDER_UNAVAILABLE", "PAYMENT_SETTLEMENT_FAILED", "BACKEND_TIMEOUT", "BACKEND_ERROR", "PROTOCOL_UNSUPPORTED", "GATEWAY_BUSY", "STORAGE_ERROR", "INTERNAL_ERROR"];
+declare const COMMERCE_ERROR_CODES: readonly ["CONFIG_INVALID", "RESOURCE_NOT_FOUND", "INPUT_INVALID", "PAYMENT_REQUIRED", "PAYMENT_INVALID", "PAYMENT_REPLAYED", "PAYMENT_PROVIDER_UNAVAILABLE", "PAYMENT_SETTLEMENT_FAILED", "AUTHORIZATION_REQUIRED", "AUTHORIZATION_INVALID", "AUTHORIZATION_REPLAYED", "AUTHORIZATION_PROVIDER_UNAVAILABLE", "BACKEND_TIMEOUT", "BACKEND_ERROR", "PROTOCOL_UNSUPPORTED", "GATEWAY_BUSY", "STORAGE_ERROR", "INTERNAL_ERROR"];
 type CommerceErrorCode = (typeof COMMERCE_ERROR_CODES)[number];
 /**
  * Canonical HTTP status for each error code.
@@ -109,6 +112,47 @@ declare const PAYMENT_INPUT_FIELD = "_payment";
 declare const PAYMENT_HEADER = "payment-signature";
 /** HTTP response header carrying the settlement result. */
 declare const PAYMENT_RESPONSE_HEADER = "payment-response";
+/**
+ * Reserved input property carrying an authorization proof, the authorization
+ * counterpart of {@link PAYMENT_INPUT_FIELD}.
+ *
+ * Unlike `_payment`, which is a bare string, this one carries an object:
+ * `{ method, payload }`. There is exactly one payment rail per resource, so a
+ * payment proof's method can be inferred from the resource; an authorization
+ * proof cannot lean on that, and guessing the method of a security control is
+ * not a thing to do implicitly.
+ */
+declare const AUTHORIZATION_INPUT_FIELD = "_authorization";
+/**
+ * Every input property name the gateway claims for itself.
+ *
+ * One list, read by the config loader (which rejects a resource declaring any
+ * of them), by the protocol adapters that lift them out of client input, and
+ * by the pipeline that strips them again as defence in depth. Those three
+ * agree by construction instead of by three copies of two strings.
+ */
+declare const RESERVED_INPUT_FIELDS: readonly string[];
+/**
+ * HTTP request header carrying the authorization proof, base64url-encoded
+ * JSON of the same `{ method, payload }` envelope the reserved input field
+ * carries.
+ *
+ * This is an Agent Commerce transport carrier, not a header defined by any
+ * authorization specification, so it is namespaced rather than borrowing
+ * `Authorization`, which already means something else on every one of these
+ * routes.
+ */
+declare const AUTHORIZATION_HEADER = "agent-authorization";
+/**
+ * Hard cap on the encoded `Agent-Authorization` header.
+ *
+ * Node's own limit is ~16 KiB across *all* request headers, so an
+ * authorization near that size would start evicting everything else and fail
+ * as an unreadable transport error rather than a legible one. Capping well
+ * below it means an oversized proof gets a deterministic
+ * AUTHORIZATION_INVALID naming the limit.
+ */
+declare const MAX_AUTHORIZATION_HEADER_BYTES = 8192;
 /**
  * HTTP response header carrying the base64 payment challenge on a 402.
  *
@@ -154,6 +198,19 @@ interface PaymentRequiredEnvelope {
          */
         readonly envelope?: Readonly<Record<string, unknown>>;
     };
+    /**
+     * Present only when the resource requires an authorization proof as well.
+     *
+     * Additive: a client that does not understand the field sees exactly the
+     * envelope it saw before. A client that does learns, before it spends
+     * anything, that paying alone will not get the resource delivered.
+     *
+     * This advertises a requirement; it does not issue anything. The proof is
+     * obtained from the merchant's own approval flow, outside the gateway.
+     */
+    readonly authorization?: {
+        readonly required: readonly AuthorizationRequirement[];
+    };
 }
 interface ErrorEnvelope {
     readonly status: 'error';
@@ -196,6 +253,42 @@ declare function toDeliverySummary(outcome: DeliveredOutcome): DeliverySummary;
 declare function toPaymentRequiredEnvelope(outcome: PaymentRequiredOutcome): PaymentRequiredEnvelope;
 declare function toErrorEnvelope(error: CommerceError): ErrorEnvelope;
 declare function isPaymentRequiredEnvelope(value: unknown): value is PaymentRequiredEnvelope;
+/**
+ * Parses the `{ method, payload }` authorization envelope, whichever carrier
+ * brought it.
+ *
+ * Absent is `undefined`. Present but malformed throws, rather than being
+ * dropped the way an unusable `_payment` is. A dropped payment leaves the
+ * buyer holding a 402 they can act on. A silently dropped authorization would
+ * come back as "not authorized" for a proof the client believes it sent, with
+ * no way to tell a rejected mandate from a typo in the envelope around it.
+ */
+declare function parseAuthorizationSubmission(value: unknown, requestId?: string): AuthorizationSubmission | undefined;
+/**
+ * Decodes the base64url-JSON `Agent-Authorization` header.
+ *
+ * The size check runs on the encoded value before any decoding, so an
+ * oversized header costs a length comparison rather than a base64 decode and
+ * a JSON parse of whatever a caller chose to send.
+ */
+declare function parseAuthorizationHeader(raw: string | readonly string[] | undefined, requestId?: string): AuthorizationSubmission | undefined;
+/**
+ * Splits raw client input into resource input plus the reserved fields the
+ * gateway claims, for every protocol that carries them in the input object
+ * (MCP tool arguments, A2A message data). HTTP carries both in headers and
+ * uses the two parse helpers directly.
+ *
+ * The payment method comes from the resource's own declaration. This is not
+ * the place that decides which rail a resource uses, so a proof for a
+ * resource with no configured rail is dropped rather than forwarded under an
+ * invented method. The pipeline then treats the request as unpaid and decides
+ * on its own terms.
+ */
+declare function extractReservedInputFields(rawInput: Record<string, unknown>, resource: CommerceResource | undefined, requestId?: string): {
+    input: Record<string, unknown>;
+    payment?: PaymentSubmission;
+    authorization?: AuthorizationSubmission;
+};
 
 /**
  * Merchant backend execution boundary.
@@ -309,6 +402,33 @@ interface ReceiptStore {
     close(): Promise<void>;
 }
 
+/**
+ * ACP protocol constants shared by the config layer and the adapter.
+ *
+ * Kept dependency-free: `src/config` reads the operation set at load time, so
+ * anything imported here would become a config-load dependency too.
+ */
+/**
+ * The ACP stable snapshot this adapter implements, and the only value accepted
+ * in the `API-Version` request header. Both name the same released snapshot;
+ * they are separate constants because ACP versions the wire contract and the
+ * header independently, and a future snapshot may accept more than one.
+ *
+ * Changing either means vendoring a new schema directory beside
+ * `spec/2026-04-17/` - never editing the vendored one in place.
+ */
+declare const ACP_SPEC_VERSION = "2026-04-17";
+declare const ACP_API_VERSION = "2026-04-17";
+/** Discovery path fixed by the ACP specification - never a configurable mount. */
+declare const ACP_WELL_KNOWN_PATH = "/.well-known/acp.json";
+/**
+ * The stable checkout operations, by ACP operation id. All five are required
+ * when ACP is enabled: a partially configured checkout lifecycle would be
+ * advertised as a whole service the seller cannot actually serve.
+ */
+declare const ACP_CHECKOUT_OPERATIONS: readonly ["createCheckoutSession", "updateCheckoutSession", "getCheckoutSession", "completeCheckoutSession", "cancelCheckoutSession"];
+type AcpCheckoutOperation = (typeof ACP_CHECKOUT_OPERATIONS)[number];
+
 /**
  * `config.yaml` schema, validation and normalisation into the
  * canonical `GatewayConfig` (docs/contracts.md).
@@ -335,6 +455,37 @@ interface ReceiptStore {
  * substitution rule, which this sentence exists to record.
  */
 
+/** Optional ACP discovery metadata. Absent fields are omitted from the document. */
+interface AcpDiscoveryConfig {
+    readonly documentationUrl?: string;
+    readonly supportedCurrencies?: readonly string[];
+    readonly supportedLocales?: readonly string[];
+    readonly interventionTypes?: readonly string[];
+}
+/**
+ * Discriminated on `enabled` so an enabled ACP config carries everything the
+ * adapter needs, with no optional-field assertions at the mount point: a
+ * half-configured checkout lifecycle is rejected at load instead.
+ */
+type AcpProtocolConfig = {
+    readonly enabled: false;
+    readonly mountPath: string;
+} | {
+    readonly enabled: true;
+    readonly mountPath: string;
+    readonly auth: {
+        readonly type: 'bearer';
+        readonly token: string;
+    };
+    readonly idempotency: {
+        readonly path: string;
+        readonly retentionHours: number;
+    };
+    readonly checkout: {
+        readonly operations: Readonly<Record<AcpCheckoutOperation, string>>;
+    };
+    readonly discovery?: AcpDiscoveryConfig;
+};
 interface GatewayConfig {
     readonly version: 1;
     readonly merchant: {
@@ -366,6 +517,7 @@ interface GatewayConfig {
             readonly enabled: boolean;
             readonly mountPath: string;
         };
+        readonly acp: AcpProtocolConfig;
     };
     /** Canonical resources, already normalised. */
     readonly resources: readonly CommerceResource[];
@@ -385,6 +537,13 @@ interface GatewayConfig {
             readonly allowUnauthenticatedFacilitator?: boolean;
         };
     };
+    /**
+     * Absent when no `authorization:` block is configured, which is how every
+     * config written before AP2 existed reads.
+     */
+    readonly authorization?: {
+        readonly ap2: Ap2AuthorizationConfig;
+    };
 }
 declare function parseConfig(raw: unknown, env: NodeJS.ProcessEnv): GatewayConfig;
 
@@ -404,6 +563,8 @@ interface GatewayOptions {
     readonly config: GatewayConfig;
     readonly store: ReceiptStore;
     readonly paymentProviders: readonly PaymentProvider[];
+    /** Absent means no resource requires authorization, which is the default */
+    readonly authorizationProviders?: readonly AuthorizationProvider[];
     readonly protocolAdapters: readonly ProtocolAdapter[];
     readonly logger?: Logger;
     readonly clock?: Clock;
@@ -423,6 +584,94 @@ interface GatewayInstance {
 }
 declare function createGateway(options: GatewayOptions): Promise<GatewayInstance>;
 
+/** Discovery metadata an operator may configure. Absent fields are omitted, never guessed. */
+interface AcpDiscoveryMetadata {
+    readonly documentationUrl?: string;
+    readonly supportedCurrencies?: readonly string[];
+    readonly supportedLocales?: readonly string[];
+    readonly interventionTypes?: readonly string[];
+}
+
+/**
+ * ACP (Agentic Commerce Protocol) adapter - experimental.
+ *
+ * Serves two paths: the configured mount (`/acp`), where the five stable
+ * checkout routes live, and the specification-fixed `/.well-known/acp.json`,
+ * declared through `additionalHttpRoutes` so the gateway needs no ACP-specific
+ * routing.
+ *
+ * Discovery and every protocol guard that must hold before canonical execution
+ * are implemented. A guarded request is not executed yet: until checkout
+ * operations reach the pipeline, a fully-valid request is answered with an
+ * honest "not implemented" rather than a fabricated session.
+ *
+ * This file never calls a merchant backend and never inspects a payment
+ * object.
+ */
+
+interface AcpAdapterOptions {
+    readonly mountPath: string;
+    /** The configured bearer token. Never logged, never echoed, never published. */
+    readonly token: string;
+    /** Which canonical resource implements each ACP checkout operation. */
+    readonly operations: Readonly<Record<AcpCheckoutOperation, string>>;
+    /** Where checkout idempotency records live, and how long they are kept. */
+    readonly idempotency: {
+        readonly path: string;
+        readonly retentionHours: number;
+    };
+    readonly discovery?: AcpDiscoveryMetadata;
+}
+declare class AcpProtocolAdapter implements HttpProtocolAdapter {
+    readonly name: "acp";
+    readonly mountPath: string;
+    readonly descriptor: AdapterDescriptor;
+    readonly additionalHttpRoutes: readonly AdapterHttpRoute[];
+    private readonly token;
+    private readonly operations;
+    private readonly idempotencyOptions;
+    /** Derived once: the token is fixed, and only its digest may be persisted. */
+    private readonly identityHash;
+    private readonly discoveryMetadata;
+    private idempotency;
+    private resources;
+    private context;
+    private started;
+    private discovery;
+    constructor(options: AcpAdapterOptions);
+    start(context: ProtocolAdapterContext): Promise<void>;
+    /** `GET /.well-known/acp.json` - public, unauthenticated, cacheable. */
+    handleDiscovery(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /** `<mountPath>/checkout_sessions...` - the five stable checkout routes. */
+    handleHttp(req: IncomingMessage, res: ServerResponse): Promise<void>;
+    /**
+     * One request, at most one execution.
+     *
+     * A body-bearing route claims its idempotency key *before* the work starts,
+     * so a retry that arrives while the first one is still running finds the
+     * claim instead of starting a second checkout. A route with no key (the GET)
+     * is read-only and needs none.
+     */
+    private dispatch;
+    /**
+     * One accepted request, one `pipeline.execute()`.
+     *
+     * Nothing here prices a resource, inspects a payment proof or calls a
+     * merchant backend: the adapter builds a canonical request and reads back
+     * what the pipeline decided.
+     */
+    private runCheckout;
+    /**
+     * Protocol-owned headers only. A merchant backend's own headers are never
+     * proxied onto an ACP response.
+     */
+    private responseHeaders;
+    private fail;
+    health(): Promise<AdapterHealth>;
+    stop(): Promise<void>;
+}
+declare function createAcpAdapter(options: AcpAdapterOptions): AcpProtocolAdapter;
+
 interface SqliteReceiptStoreOptions {
     /** File path, or ':memory:' for tests. Parent directory is created if missing. */
     readonly path: string;
@@ -432,4 +681,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_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 };
+export { ACP_API_VERSION, ACP_SPEC_VERSION, ACP_WELL_KNOWN_PATH, AUTHORIZATION_HEADER, AUTHORIZATION_INPUT_FIELD, type AcpAdapterOptions, AdapterDescriptor, AdapterHealth, AdapterHttpRoute, AuthorizationProvider, AuthorizationRequirement, AuthorizationSubmission, 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, HttpProtocolAdapter, IdGenerator, IsoTimestamp, type ListOptions, Logger, MAX_AUTHORIZATION_HEADER_BYTES, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PaymentAttempt, type PaymentAttemptReservation, type PaymentAttemptUpdate, PaymentMethodName, PaymentProvider, type PaymentRequiredEnvelope, PaymentRequiredOutcome, PaymentSubmission, ProtocolAdapter, ProtocolAdapterContext, RESERVED_INPUT_FIELDS, RETRYABLE_ERROR_CODES, type ReceiptStore, ResourceRegistry, createAcpAdapter, createGateway, createSqliteReceiptStore, extractReservedInputFields, isCommerceError, isPaymentRequiredEnvelope, loadConfig, parseAuthorizationHeader, parseAuthorizationSubmission, parseConfig, createSqliteReceiptStore as receipts, toCommerceError, toDeliverySummary, toErrorEnvelope, toPaymentRequiredEnvelope };