@devlab.group/agent-commerce 1.3.0 → 1.4.1

package/dist/index.d.ts

@@ -1,8 +1,11 @@
-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-Plk5Peqi.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-Plk5Peqi.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, H as HttpProtocolAdapter, A as AdapterHttpRoute, d as ProtocolAdapterContext } from './protocol-adapter-DTFGWGXq.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-DTFGWGXq.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-Bebmggf_.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-Bebmggf_.js';
 import { FastifyInstance } from 'fastify';
 import { IncomingMessage, ServerResponse } from 'node:http';
 
@@ -12,7 +15,7 @@ import { IncomingMessage, ServerResponse } from '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.
@@ -210,6 +303,16 @@ interface BackendRequest {
     readonly resourceId: string;
     /** Validated resource input. */
     readonly input: unknown;
+    /**
+     * Names the *operation*, so the merchant can recognise a repeat of it.
+     *
+     * Not `requestId`, which is fresh per call and would make every retry look
+     * like new work. An adapter sets this only when it can derive a value that
+     * survives a client retry, a reconnect and a gateway restart; the HTTP
+     * executor forwards it as the `Idempotency-Key` request header. Absent
+     * means the protocol has no such notion, and the merchant sees no header.
+     */
+    readonly idempotencyKey?: string;
 }
 interface BackendResponse {
     readonly status: number;
@@ -444,6 +547,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;
 
@@ -463,6 +573,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;
@@ -528,8 +640,14 @@ declare class AcpProtocolAdapter implements HttpProtocolAdapter {
     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;
+    /**
+     * What an idempotency claim is scoped to, from `context.publicBaseUrl`.
+     *
+     * Not readonly because, unlike the token, it is known only once the adapter
+     * starts. Worth that: scoping by the credential meant a rotation freed
+     * every outstanding claim.
+     */
+    private deployment;
     private readonly discoveryMetadata;
     private idempotency;
     private resources;
@@ -579,4 +697,4 @@ interface SqliteReceiptStoreOptions {
 }
 declare function createSqliteReceiptStore(options: SqliteReceiptStoreOptions): ReceiptStore;
 
-export { ACP_API_VERSION, ACP_SPEC_VERSION, ACP_WELL_KNOWN_PATH, type AcpAdapterOptions, AdapterDescriptor, AdapterHealth, AdapterHttpRoute, 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, PAYMENT_HEADER, PAYMENT_INPUT_FIELD, PAYMENT_REQUIRED_HEADER, PAYMENT_RESPONSE_HEADER, PaymentAttempt, type PaymentAttemptReservation, type PaymentAttemptUpdate, PaymentMethodName, PaymentProvider, type PaymentRequiredEnvelope, PaymentRequiredOutcome, ProtocolAdapter, ProtocolAdapterContext, RETRYABLE_ERROR_CODES, type ReceiptStore, ResourceRegistry, createAcpAdapter, 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 };