@devlab.group/agent-commerce 1.3.0 → 1.4.1

package/README.md

@@ -12,6 +12,7 @@
   <img alt="x402" src="https://img.shields.io/badge/x402-supported-0052ff">
   <img alt="A2A" src="https://img.shields.io/badge/A2A-experimental-f0a30a">
   <img alt="ACP" src="https://img.shields.io/badge/ACP-experimental-f0a30a">
+  <img alt="AP2" src="https://img.shields.io/badge/AP2-experimental-f0a30a">
 </p>
 
 ## What it is, in ten seconds
@@ -23,13 +24,14 @@ Agent Commerce Gateway sits in front of your existing API, in **your**
 infrastructure, and does that for you. You describe an endpoint in a YAML file -
 or generate that description from an OpenAPI document you already have - and
 agents get an MCP tool and an x402 paywall. Switch on the experimental adapters
-and the same resource is also an A2A skill, or an ACP checkout session. The
-money goes straight to your wallet - the gateway never holds it, and never holds
-your keys.
+and the same resource is also an A2A skill, or an ACP checkout session. Switch
+on AP2 and a paid resource can also demand a signed mandate: proof the human
+behind the agent approved that exact purchase. The money goes straight to your
+wallet - the gateway never holds it, and never holds your keys.
 
 ```text
 Your existing API → Agent Commerce Gateway → AI Agent
-          MCP · A2A · ACP · x402 · receipts · doctor
+      MCP · A2A · ACP · x402 · AP2 · receipts · doctor
 ```
 
 ## Demo
@@ -54,11 +56,9 @@ Your existing API → Agent Commerce Gateway → AI Agent
 ```
 
 The dashboard at <http://localhost:5173> shows the same request as it happens.
-It polls the authenticated events route on a short interval rather than
-streaming: a browser `EventSource` cannot send the admin token, and the operator
-routes are closed without one - so the SSE endpoint is reachable by a
-header-capable client, never by a browser. Polling is the dashboard's intended
-path, not a degraded mode.
+It polls the authenticated events route rather than streaming, because a browser
+cannot send the admin token over `EventSource`; see
+[why the stream is polled](SECURITY.md#the-live-event-stream-is-polled-not-streamed).
 
 ## Install
 
@@ -79,9 +79,15 @@ onboarding an existing API is the CLI's main job.
 import { createGateway, loadConfig, receipts } from '@devlab.group/agent-commerce';
 
 const config = await loadConfig({ path: 'config.yaml' });
+const store = receipts({ path: './receipts.sqlite' });
+// Every ReceiptStore must be initialised before anything else touches it -
+// for the SQLite one this is where a schema written by a newer version is
+// caught, at boot rather than at the first query
+await store.init();
+
 const gateway = await createGateway({
   config,
-  store: receipts({ path: './receipts.sqlite' }),
+  store,
   paymentProviders: [],
   protocolAdapters: [],
 });
@@ -90,17 +96,18 @@ const { url } = await gateway.listen();
 
 ### Optional peers - install only the rails you use
 
-The MCP adapter and the x402 provider live on their own subpaths, because each
-needs a dependency the rest of the package does not - the x402 rail brings the
-whole EVM signing and RPC stack, which a gateway serving a free HTTP resource
-has no business installing.
+The MCP adapter, the x402 provider and AP2 verification live on their own
+subpaths, because each needs a dependency the rest of the package does not -
+the x402 rail brings the whole EVM signing and RPC stack, which a gateway
+serving a free HTTP resource has no business installing.
 
-| You want                          | Install                        | Import                                     |
-| --------------------------------- | ------------------------------ | ------------------------------------------ |
-| gateway, config, receipts, CLI    | `@devlab.group/agent-commerce` | `from '@devlab.group/agent-commerce'`      |
-| expose resources as MCP tools     | `+ @modelcontextprotocol/sdk`  | `from '@devlab.group/agent-commerce/mcp'`  |
-| accept x402 payments              | `+ @x402/core @x402/evm viem`  | `from '@devlab.group/agent-commerce/x402'` |
-| authenticate to a CDP facilitator | `+ @coinbase/x402`             | (no import - loaded on demand)             |
+| You want                                | Install                            | Import                                     |
+| --------------------------------------- | ---------------------------------- | ------------------------------------------ |
+| gateway, config, receipts, CLI          | `@devlab.group/agent-commerce`     | `from '@devlab.group/agent-commerce'`      |
+| expose resources as MCP tools           | `+ @modelcontextprotocol/sdk`      | `from '@devlab.group/agent-commerce/mcp'`  |
+| accept x402 payments                    | `+ @x402/core @x402/evm viem`      | `from '@devlab.group/agent-commerce/x402'` |
+| verify AP2 mandates, sign checkout JWTs | `+ jose @sd-jwt/core canonicalize` | `from '@devlab.group/agent-commerce/ap2'`  |
+| authenticate to a CDP facilitator       | `+ @coinbase/x402`                 | (no import - loaded on demand)             |
 
 ```bash
 npm install @devlab.group/agent-commerce @modelcontextprotocol/sdk @x402/core @x402/evm viem
@@ -109,8 +116,14 @@ npm install @devlab.group/agent-commerce @modelcontextprotocol/sdk @x402/core @x
 ```ts
 import { mcp } from '@devlab.group/agent-commerce/mcp';
 import { x402 } from '@devlab.group/agent-commerce/x402';
+import { ap2 } from '@devlab.group/agent-commerce/ap2';
 ```
 
+The AP2 three are small - about 1.3 MB installed between them, against roughly
+63 MB for the x402 stack - but they stay optional on the same principle: a
+deployment that gates nothing on a mandate should not carry a JOSE stack and an
+SD-JWT parser to serve a resource.
+
 Peers are pinned exactly: x402's schemas and EIP-712 domains cross this
 boundary, so a version skew is a correctness problem rather than a convenience
 one. Import a subpath without its
@@ -157,30 +170,33 @@ To stop and wipe state: `docker compose down -v`.
 ## How it works
 
 ```text
-        ┌──────────────────────────────────────────────────────┐
-        │ AI Agent │
-        └──────────────┬───────────────────────────────────────┘
-                       │ MCP · HTTP + PAYMENT-SIGNATURE
-        ┌──────────────▼───────────────────────────────────────┐
-        │ Agent Commerce Gateway (yours) │
-        │ │
-        │ protocol adapters → ExecutionPipeline → … │
-        │ │ │
-        │ ┌─────────────────────┼──────────────┐ │
-        │ ▼ ▼ ▼ │
-        │ PaymentProvider BackendExecutor ReceiptStore │
-        │ (x402) (bounded HTTP) (SQLite) │
-        └────────┬─────────────────────┬───────────────────────┘
-                 │ │
-        buyer → merchant ┌──────▼───────────────┐
-        (never through us) │ Your backend API │
-                                └───────────────────────┘
+┌──────────────────────────────────────────────────────────────────────────────┐
+│                                   AI Agent                                   │
+└───────────────────────────────────────┬──────────────────────────────────────┘
+                                        │  MCP · A2A · ACP · HTTP
+                                        │  PAYMENT-SIGNATURE
+                                        │  Agent-Authorization
+┌───────────────────────────────────────▼──────────────────────────────────────┐
+│                        Agent Commerce Gateway (yours)                        │
+│                                                                              │
+│                   protocol adapters  →  ExecutionPipeline                    │
+│                                                 │                            │
+│             ┌────────────────────┬──────────────┴──┬────────────────┐        │
+│             ▼                    ▼                 ▼                ▼        │
+│   AuthorizationProvider   PaymentProvider   BackendExecutor   ReceiptStore   │
+│           (ap2)               (x402)        (bounded HTTP)      (SQLite)     │
+└───────────────────────────────────────┬──────────────────────────────────────┘
+                                        │
+                             ┌──────────▼─────────┐
+                             │  Your backend API  │
+                             └────────────────────┘
 ```
 
 Every protocol adapter converges on **one execution pipeline**. That is what
 makes payment enforcement a property of the system rather than something each
-adapter has to remember. Full detail in
-[docs/architecture.md](docs/architecture.md).
+adapter has to remember. Money never passes through the box: the buyer pays the
+merchant directly on chain, and the gateway holds neither the funds nor a key.
+Full detail in [docs/architecture.md](docs/architecture.md).
 
 ## Configure a resource
 
@@ -219,33 +235,39 @@ It writes a reviewable `resources:` fragment - path, query and JSON body
 mapped, schemas converted to what the gateway actually enforces - and
 deliberately leaves `pricing` and `expose` out, because an OpenAPI document has
 no opinion on what an operation costs or who may see it. Credentials are never
-imported. See [docs/openapi-import.md](docs/openapi-import.md) for the exact
-supported subset.
+imported. See [OpenAPI import](docs/openapi-import.md) for the exact supported subset.
 
 See [docs/configuration.md](docs/configuration.md).
 
 ## Protocol support
 
-| Protocol        | Status       | Pinned revision                                          |
-| --------------- | ------------ | -------------------------------------------------------- |
-| **MCP**         | Supported    | `@modelcontextprotocol/sdk@1.30.0`                       |
-| **x402**        | Supported    | x402 v2 (`@x402/core`, `@x402/evm`), scheme `exact`, EVM |
-| **HTTP**        | Supported    | native routes                                            |
-| **A2A**         | Experimental | A2A v1.0.0, binding `JSONRPC`, method `SendMessage`      |
-| **ACP**         | Experimental | ACP `2026-04-17`, REST checkout + discovery              |
-| UCP · MPP · AP2 | Planned      | -                                                        |
+| Protocol  | Status       | Pinned revision                                          |
+| --------- | ------------ | -------------------------------------------------------- |
+| **MCP**   | Supported    | `@modelcontextprotocol/sdk@1.30.0`                       |
+| **x402**  | Supported    | x402 v2 (`@x402/core`, `@x402/evm`), scheme `exact`, EVM |
+| **HTTP**  | Supported    | native routes                                            |
+| **A2A**   | Experimental | A2A v1.0.0, binding `JSONRPC`, method `SendMessage`      |
+| **ACP**   | Experimental | ACP `2026-04-17`, REST checkout + discovery              |
+| **AP2**   | Experimental | AP2 `v0.2.0`, Direct Checkout Mandate verification       |
+| UCP · MPP | Planned      | -                                                        |
+
+[AP2](docs/ap2.md) is in that table because people look there, but it is an **authorization**
+method rather than a transport: it gates settlement on a resource that still
+takes a real payment, and it is the verifying half only - the gateway holds no
+signing key and issues no Checkout Receipt.
 
 "Planned" means **no code ships for it**. "Experimental" means the code ships,
 is tested against the protocol's own official artifacts, and serves a narrow
-named subset - A2A and ACP are both off by default and documented in full at
-[docs/protocols.md](docs/protocols.md#a2a) and
-[docs/protocols.md](docs/protocols.md#acp). ACP serves the five stable checkout
-operations and advertises `services: ["checkout"]` and nothing more; its
-`payment_data` stays with the merchant's own checkout and is never turned into
-an x402 payment. Each adapter reports its own
-`supportedSpec`, `capabilities` and `unsupported` list at runtime via
-`GET /.well-known/agent-commerce` and `agent-commerce doctor` - so the claim is
-checkable, not marketing. Detail: [docs/protocols.md](docs/protocols.md).
+named subset: [A2A](docs/protocols.md#a2a) and [ACP](docs/protocols.md#acp) are
+both off by default and documented in full there, as are
+[MCP](docs/protocols.md#mcp) and [x402](docs/protocols.md#x402). ACP serves the
+five stable checkout operations and advertises `services: ["checkout"]` and
+nothing more; its `payment_data` stays with the merchant's own checkout and is
+never turned into an x402 payment.
+
+Each adapter reports its own `supportedSpec`, `capabilities` and `unsupported`
+list at runtime through `GET /.well-known/agent-commerce` and
+`agent-commerce doctor`, so the claim is checkable rather than marketing.
 
 ## Payment model
 
@@ -260,8 +282,10 @@ checkable, not marketing. Detail: [docs/protocols.md](docs/protocols.md).
 - **Real settlement in CI.** The end-to-end test asserts the buyer's balance
   falls and the merchant's rises by exactly the price, with a real transaction
   hash in the receipt. A log line saying "payment successful" would not count.
-
-Detail: [docs/payment-flow.md](docs/payment-flow.md).
+- **Authorization is separate from payment.** A resource can also require an
+  AP2 mandate, verified before settlement and spendable exactly once. It never
+  moves money and never unlocks a resource on its own - the payment still has
+  to be real.
 
 ## Public networks
 
@@ -378,6 +402,7 @@ PASS  Backend              2/2 backend host(s) reachable
 PASS  Protocols            http=on mcp=on (/mcp) a2a=off acp=off
 INFO  A2A                  disabled
 INFO  ACP                  disabled
+INFO  AP2                  disabled
 PASS  Payments             x402 v2 (scheme=exact) enabled - LOCAL dev chain (eip155:84532, chain id shared with Base Sepolia), destination=0x7099…79C8, facilitator=local
 INFO  Payments (MPP)       planned - not implemented in this release
 PASS  Storage              sqlite schema v1 writable; receipts=2
@@ -398,8 +423,9 @@ Exits non-zero if anything fails. `--json` for machines.
 The demo binds everything to `127.0.0.1`. Before putting the gateway anywhere
 reachable by anyone else, know the split:
 
-- **Agent routes** (`/api/resources/:id/invoke`, `/mcp`) are unauthenticated by
-  design - paid resources are protected by payment, not by a password.
+- **Agent routes** (`/api/resources/:id/invoke`, `/mcp`, the A2A mount) are
+  unauthenticated by design - paid resources are protected by payment, not by a
+  password. ACP is the exception: its checkout routes require a bearer token.
 - **Operator routes** (`/api/receipts`, `/api/events`, `/api/events/stream`) are
   the merchant's commerce ledger: payer addresses, amounts, settlement hashes.
   They require `server.adminToken`, and return **404** if none is configured.
@@ -425,11 +451,13 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 **Now** - MCP, x402 v2, settlement on the local chain, Base Sepolia and Base
 mainnet, receipts, doctor, deterministic demo, experimental A2A v1.0.0 and ACP
-`2026-04-17` checkout adapters, and experimental OpenAPI import.
+`2026-04-17` checkout adapters, experimental AP2 v0.2.0 mandate verification,
+and experimental OpenAPI import.
 
-**Next** - a `doctor` GitHub Action · UCP · MPP · AP2 · more of ACP (carts,
-feed, delegated payment) · Shopify and WooCommerce examples · PostgreSQL ·
-richer observability · multi-file and remote OpenAPI sources.
+**Next** - a `doctor` GitHub Action · UCP · MPP · autonomous-mode AP2 (open
+mandates, agent key binding, constraint evaluation) · more of ACP (carts, feed,
+delegated payment) · Shopify and WooCommerce examples · PostgreSQL · richer
+observability · multi-file and remote OpenAPI sources.
 
 New protocols land only after the adapter model survives real use. Scope
 discipline is a release requirement, not a mood.
@@ -441,6 +469,7 @@ discipline is a release requirement, not a mood.
 | [Architecture](docs/architecture.md)           | how the pieces fit                          |
 | [Payment flow](docs/payment-flow.md)           | the paid round trip, and every way it fails |
 | [Protocols](docs/protocols.md)                 | exactly what is and is not supported        |
+| [AP2](docs/ap2.md)                             | mandate verification and the trust model    |
 | [Configuration](docs/configuration.md)         | `config.yaml` reference                     |
 | [OpenAPI import](docs/openapi-import.md)       | generate resources from an existing API     |
 | [Security model](docs/security.md)             | trust boundaries, and what we do not defend |

package/dist/ap2.d.ts

@@ -0,0 +1,164 @@
+import { E as EnabledAp2Config } from './types-CJtwLu1c.js';
+export { A as AP2_CHECKOUT_MANDATE_VCT, a as AP2_CHECKOUT_PROFILE, b as AP2_DEFAULT_CLOCK_SKEW_SECONDS, c as AP2_MAX_CLOCK_SKEW_SECONDS, d as AP2_SIGNING_ALGORITHM, e as AP2_SPEC_VERSION, f as Ap2AuthorizationConfig, g as Ap2Mode, h as Ap2TrustedIssuer, i as Ap2TrustedKey } from './types-CJtwLu1c.js';
+import { A as AuthorizationProvider } from './authorization-CPDcpJVa.js';
+import { C as Clock, L as Logger } from './runtime-CKq3d_3K.js';
+
+/**
+ * A private ES256 key: either a private JWK (the pair of the public one in the
+ * gateway's `checkoutIssuers`) or a PKCS#8 PEM, as `openssl` emits it.
+ */
+type Ap2SigningKey = Readonly<Record<string, unknown>> | string;
+interface CreateCheckoutJwtOptions {
+    readonly privateKey: Ap2SigningKey;
+    /** Must match a `kid` configured under the gateway's `checkoutIssuers` */
+    readonly kid: string;
+    /** Must match that issuer's configured `issuer` */
+    readonly issuer: string;
+    /** Must match that issuer's configured `audience` */
+    readonly audience: string;
+    readonly resourceId: string;
+    /**
+     * The resource input this purchase is for, exactly as the buyer will send
+     * it: no reserved fields, no request id, no transport metadata.
+     */
+    readonly input: unknown;
+    /**
+     * Decimal string, never a number, and compared as a string: `0.10` and `0.1`
+     * are different mandates. Take it from your own catalogue rather than from
+     * whatever the agent asked for.
+     */
+    readonly amount: string;
+    readonly currency: string;
+    /** The rail that will settle, e.g. `x402` */
+    readonly paymentMethod: string;
+    /**
+     * Settlement coordinates. Required whenever the gateway's requirement names
+     * them, which under x402 is always. A mandate silent about the chain will
+     * not unlock a settlement on one.
+     */
+    readonly destination?: string;
+    readonly network?: string;
+    readonly asset?: string;
+    /** Defaults to a random UUID. Recorded on the receipt and used for replay defence */
+    readonly jwtId?: string;
+    /** Defaults to 900: a human approval sits inside this window */
+    readonly expiresInSeconds?: number;
+    /** Injectable so a test need not move the wall clock */
+    readonly now?: Date;
+}
+/**
+ * Returns the compact JWT to hand to the agent, which wraps it in the Checkout
+ * Mandate the buyer signs.
+ */
+declare function createCheckoutJwt(options: CreateCheckoutJwtOptions): Promise<string>;
+
+/**
+ * Adapter self-description.
+ *
+ * Imports nothing but core types and the pins, so `doctor` can report AP2
+ * without pulling `jose` or `@sd-jwt/core` into the CLI bundle.
+ */
+
+/** What this provider actually verifies */
+declare const AP2_CAPABILITIES: readonly string[];
+/**
+ * Everything an AP2 client may reasonably expect and will not get here.
+ * Complete on purpose: a short list reads as "mostly compatible", which is the
+ * blanket claim alpha honesty forbids.
+ */
+declare const AP2_UNSUPPORTED: readonly string[];
+
+/**
+ * Every failure the AP2 verifier can report.
+ *
+ * `CommerceError.message` reaches the client, and a mandate carries the
+ * buyer's purchase and often personal data, so messages are fixed phrases from
+ * the list below. The machine-readable code goes in `details.reason` and the
+ * original exception on `cause`, which is never serialised.
+ *
+ * Three codes: AUTHORIZATION_INVALID when the buyer's mandate is bad,
+ * AUTHORIZATION_REPLAYED when it is good but spent, and
+ * AUTHORIZATION_PROVIDER_UNAVAILABLE when our verifier never reached a
+ * verdict. Blaming the buyer for our outage refuses a good mandate.
+ */
+
+/**
+ * Coarse on purpose: a client learns roughly where its mandate was refused,
+ * not which check failed. Finer detail is an oracle for probing trust policy.
+ */
+declare const AP2_REJECTION_REASONS: readonly ["malformed_presentation", "untrusted_issuer", "unknown_key", "invalid_signature", "unsupported_algorithm", "invalid_claims", "expired", "wrong_audience", "unsupported_mandate_type", "checkout_binding_failed", "purchase_mismatch"];
+type Ap2RejectionReason = (typeof AP2_REJECTION_REASONS)[number];
+
+/**
+ * `released` is "nothing happened" and the only state a mandate can be
+ * presented from again. `uncertain` is a settlement whose outcome we never
+ * learned: not reusable, but findable by an operator reconciling by hand.
+ */
+type Ap2AuthorizationState = 'reserved' | 'consumed' | 'released' | 'uncertain';
+/**
+ * A digest and a few identifiers: everything replay defence needs, and nothing
+ * a leaked database would hand an attacker
+ */
+interface Ap2ReservationRequest {
+    /**
+     * Digest of the ISSUER-SIGNED TOKEN, not of the presentation. Selective
+     * disclosure gives one mandate many presentation strings, so keying on the
+     * presentation would let it be spent once per disclosed subset.
+     */
+    readonly reference: string;
+    /** `jti` of the merchant checkout JWT the mandate binds */
+    readonly checkoutJti: string;
+    readonly mandateIssuer: string;
+    readonly checkoutIssuer: string;
+    readonly resourceId: string;
+    readonly requestId: string;
+}
+type Ap2ReservationResult = {
+    readonly kind: 'reserved';
+}
+/** Already reserved, consumed, or of uncertain outcome. Never re-spendable */
+ | {
+    readonly kind: 'replayed';
+    readonly state: Ap2AuthorizationState;
+};
+interface Ap2ReplayStore {
+    /** Atomically claim a mandate, or report that something already holds it */
+    reserve(request: Ap2ReservationRequest): Ap2ReservationResult;
+    /** Settlement succeeded: spend it permanently */
+    consume(reference: string): void;
+    /** Nothing happened: hand it back so a corrected retry can use it */
+    release(reference: string): void;
+    /** Settlement outcome unknown. Not reusable, and flagged for a human */
+    markUncertain(reference: string): void;
+    /** Current state, for tests and diagnostics */
+    stateOf(reference: string): Ap2AuthorizationState | undefined;
+    close(): void;
+}
+
+/**
+ * The AP2 authorization provider: the seam between core's generic contract and
+ * the mandate machinery.
+ *
+ * Owns the replay database, so the gateway owns this object's lifetime and
+ * closes it on shutdown.
+ */
+
+interface Ap2AuthorizationProviderOptions {
+    readonly config: EnabledAp2Config;
+    readonly clock?: Clock;
+    readonly logger?: Logger;
+    /** Injectable so tests need not touch the filesystem */
+    readonly replayStore?: Ap2ReplayStore;
+}
+interface Ap2AuthorizationProvider extends AuthorizationProvider {
+    /** Closes the replay database */
+    close(): void;
+}
+/**
+ * A reservation is keyed by the mandate reference, so the handle and the
+ * receipt's identity are the same digest. Kept as one name rather than two
+ * fields that must never disagree.
+ */
+declare function createAp2AuthorizationProvider(options: Ap2AuthorizationProviderOptions): Ap2AuthorizationProvider;
+
+export { AP2_CAPABILITIES, AP2_REJECTION_REASONS, AP2_UNSUPPORTED, type Ap2AuthorizationProvider, type Ap2AuthorizationProviderOptions, type Ap2RejectionReason, type Ap2SigningKey, type CreateCheckoutJwtOptions, EnabledAp2Config, createAp2AuthorizationProvider as ap2, createAp2AuthorizationProvider, createCheckoutJwt };