@astrasyncai/verification-gateway 5.17.2 → 5.18.0

package/README.md

@@ -575,7 +575,7 @@ Read `result.settlementOutcome.status` — never `success` alone:
 
 | status              | Meaning                                   | Your action                                                                                                                       |
 | ------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `pending_merchant`  | 5.14.1: order recorded — YOU settle it    | Charge the `settlementToken` (card) or redeem the `settlement` voucher (stablecoin), then `reportSettlement()`                    |
+| `pending_merchant`  | Order recorded — YOU settle it            | Charge the `settlementToken` (card) or redeem the `settlement` voucher (stablecoin), then `reportSettlement()`                    |
 | `settled`           | Money moved (reported / webhook)          | Fulfil / mark paid                                                                                                                |
 | `requires_approval` | Held for human step-up — not a failure    | Record as pending; a re-drive follows approval                                                                                    |
 | `failed`            | Charge declined (`failureCode`)           | Mark failed                                                                                                                       |
@@ -583,7 +583,7 @@ Read `result.settlementOutcome.status` — never `success` alone:
 | `no_instrument`     | Policy passed, no chargeable card on file | Terminal on autonomous; NON-terminal after approval — the human's approval survives; re-drive the same session once a card exists |
 | _anything else_     | A status newer than your SDK              | Treat as PENDING, never failed (open union, 5.5.0)                                                                                |
 
-**Every merchant settles (5.14.1 — AstraSync never charges):** a purchase
+**Every merchant settles (AstraSync never charges):** a purchase
 grant records the order and returns `settlementOutcome: { status:
 'pending_merchant', orderId }` with what you settle:
 
@@ -619,6 +619,124 @@ material (the bridge strips it from the agent plane). Shipping addresses
 never transit AstraSync: take them agent → your fulfilment endpoint
 directly, joined by `sessionId`.
 
+## UCP & ACP checkout kits
+
+`createUcpCheckoutKit()` (UCP 2026-08-25 REST) and `createAcpCheckoutKit()`
+(ACP 2026-04-17) do the protocol work of a checkout endpoint; you supply the
+catalog, settlement and fulfilment. Both are fetch-style
+(`kit.handle(request) → Response`).
+
+```ts
+import {
+  createUcpCheckoutKit,
+  expressHandler,
+  RedisIdempotencyStore,
+} from '@astrasyncai/verification-gateway';
+
+const ucp = createUcpCheckoutKit({
+  profile: {
+    endpoint: 'https://shop.example/ucp/v1',
+    paymentHandlers: ['ai.astrasync.card_token'],
+    ap2Mandates: true,
+    orders: true, // dev.ucp.shopping.order: GET /orders/{id} + order webhooks
+  },
+  currency: 'USD',
+  catalog: async (id) => db.items.find(id),
+  verifyPurchase: (ctx) =>
+    client.confirmCheckout({
+      astraId: ctx.astraId,
+      attemptId: ctx.attemptId,
+      checkoutSessionId: ctx.checkoutSessionId,
+      checkoutJwt: ctx.checkoutJwt,
+      transactionValue: ctx.valueMajor,
+      currency: 'USD',
+    }),
+  settle: async ({ result }) => chargeWithYourProcessor(result), // settled | pending | failed
+  reportSettlement: (r) => client.reportSettlement(r),
+  fulfil: async ({ session }) => ({ id: await createOrder(session) }),
+  signingKey: { privateKey, kid: 'merchant-1' },
+  store: myCheckoutStore, // get / put / claim (+ findByOrderId)
+  idempotencyStore: new RedisIdempotencyStore(redis),
+  links: [
+    { type: 'terms_of_service', url: 'https://shop.example/terms' },
+    { type: 'privacy_policy', url: 'https://shop.example/privacy' },
+  ],
+  permalinkBase: 'https://shop.example/orders',
+  webhook: {}, // URL from the platform profile; signed with signingKey
+});
+
+app.get('/.well-known/ucp', (_req, res) => res.json(ucp.profile));
+app.use('/ucp/v1', express.raw({ type: '*/*' }), expressHandler(ucp));
+```
+
+- **Stores.** The defaults are in-memory (one process, lost on restart); the
+  kits warn when they run on them outside `NODE_ENV=test`. In production pass
+  `store` and `idempotencyStore` (`RedisIdempotencyStore`).
+- **`claim(id, from, to)`** — an atomic compare-and-set of the session status
+  on your store (e.g. `UPDATE … SET status = $to WHERE id = $id AND status =
+$from`). `complete` claims `complete_in_progress` before it verifies, so two
+  concurrent completes never both charge: the loser gets the session back with
+  a recoverable `checkout_in_progress` message (UCP) or `409
+checkout_in_progress` (ACP). Without `claim` the kit warns once and the lock
+  is best-effort. `MemoryCheckoutStore` implements it.
+- **Holds never settle.** Any step-up signal (`requiresStepUp`,
+  `requiresApproval`, `recommendation: 'step_up_required'`, a
+  `requires_approval` outcome, or a `stepUpApproval` that isn't `consumed`)
+  returns UCP `requires_escalation` with `continue_url` = the buyer's approval
+  page, or ACP `pending_approval`. After approval the platform completes again;
+  the redeemed approval comes back `status: 'consumed'` and the purchase
+  proceeds.
+- **`kit.resolvePending(sessionId, { status, processorRef?, txHash?, chainId?, failureCode? })`**
+  — when `settle` returns `pending`, the session stays `complete_in_progress`
+  with no order. Call `resolvePending` from your processor's webhook:
+  `'settled'` reports the settlement, runs `fulfil` and completes the session
+  (sending the UCP order webhook); `'failed'` reports it and returns the
+  session to `ready_for_complete` / `ready_for_payment`. Calling it again is a
+  no-op. The stored result never contains the settlement token, voucher or
+  mandates.
+- **One instrument (UCP).** `complete` needs exactly one
+  `payment.instruments[]` entry whose `handler_id` is one of your
+  `payment_handlers`; anything else is `payment_failed`.
+- **`links`** (UCP) — `terms_of_service`, `privacy_policy`, `refund_policy`,
+  `shipping_policy`, `faq` (`{ type, url, title? }`), returned on every
+  checkout and covered by `ap2.merchant_authorization`. A GET returns the
+  stored authorization; it never re-signs or writes.
+- **Agent binding (UCP).** After `verifyPurchase`, the `UCP-Agent` profile is
+  checked against the verified agent's `protocolIdentities.ucpProfile`
+  (override with `resolveIdentities(req, result)`); a mismatch is
+  `ucp_agent_mismatch` and nothing settles. `ucpAgentBinding: 'registered'`
+  (default) lets agents with no registered profile through (e.g. the AstraSync
+  bridge's own profile); `'strict'` refuses them; `'off'` skips the check.
+- **Caller scope.** Sessions and idempotency keys belong to the caller: the
+  verified ASTRA-id (`ctx.callerId` from `expressHandler`, or your
+  `resolveCallerId(req)`), else the `Authorization` header, else `X-Astra-Id`.
+  UCP falls back to the platform profile; ACP refuses a request with none
+  (401). Another caller gets 404, and never another caller's replay.
+- **`expressHandler(kit, { callerId? })`** (also `/kit-express`) — mounts a
+  kit on Express. Give it the raw body (`express.raw()` on the kit's routes,
+  or `req.rawBody` from your JSON parser's `verify` hook): signatures and
+  idempotency fingerprints are computed over the exact bytes. When the
+  AstraSync middleware ran first, the verified ASTRA-id scopes the session.
+- **UCP orders.** `buildUcpOrder(session)` is the `dev.ucp.shopping.order`
+  entity; `GET /orders/{id}` serves it; `webhook` sends it, signed, when the
+  order is created, and `kit.sendOrderWebhook(sessionId)` sends it again after
+  you update it.
+- **ACP.** An `API-Version` other than `2026-04-17` is `400
+unsupported_api_version` with `supported_versions`; `Idempotency-Key` and
+  `Request-Id` are echoed; `order.line_items` mirrors the session;
+  `permalinkBase` fills `permalink_url`. `buildAcpWellKnown({ endpoint,
+paymentHandlers })` is a discovery document to serve at
+  `/.well-known/acp.json`.
+- Canceling a completed or canceled checkout is `405` on both.
+
+### Unmatched routes (Express)
+
+A request no configured route matches passes through by default
+(`defaultRoutePolicy: 'pass'`). With `evaluateAlwaysIfCredentialed` and an
+`X-Astra-Id`, or with `defaultRoutePolicy: 'observe'` and any AstraSync
+credential, it's evaluated in observe mode: `req.agentVerification` is set and
+the call is recorded, but the request always reaches your handler.
+
 ## Settlement Artifacts
 
 On a clean merchant-mediated grant where the owner has a verified payment instrument, verify-access returns a `settlement` object (wire format **v2**, versioned via the `ver: 2` claim — verify/redeem reject other versions):
@@ -660,11 +778,11 @@ interface FiatSettlementBinding {
 
 ### Voucher lifecycle (server-to-server)
 
-| Endpoint                                         | Purpose                                                                                                                                                                                                                                                                           |
-| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `POST /api/wallets/voucher/verify`               | Verify signature/issuer and return the decoded payload — proves authenticity only, no spend                                                                                                                                                                                       |
-| `POST /api/wallets/voucher/redeem`               | Atomic single-use spend: first caller gets `200 redeemed` (plus `order: { status: 'redeemed' }` when the voucher funds a recorded order — 5.14.1, no charge happens here), replays get `409 already_redeemed` (with first-redeemer forensics), revoked vouchers get `409 revoked` |
-| `GET /api/wallets/voucher/.well-known/jwks.json` | Public JWKS for offline signature verification                                                                                                                                                                                                                                    |
+| Endpoint                                         | Purpose                                                                                                                                                                                                                                                                    |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `POST /api/wallets/voucher/verify`               | Verify signature/issuer and return the decoded payload — proves authenticity only, no spend                                                                                                                                                                                |
+| `POST /api/wallets/voucher/redeem`               | Atomic single-use spend: first caller gets `200 redeemed` (plus `order: { status: 'redeemed' }` when the voucher funds a recorded order — no charge happens here) , replays get `409 already_redeemed` (with first-redeemer forensics), revoked vouchers get `409 revoked` |
+| `GET /api/wallets/voucher/.well-known/jwks.json` | Public JWKS for offline signature verification                                                                                                                                                                                                                             |
 
 Redeem accepts optional `expectedAmountMinor` / `expectedCurrency` — mismatches are rejected (`400 amount_mismatch` / `currency_mismatch`) **before** the voucher is spent, so a mismatch never burns the voucher. Vouchers carry `aud` = your merchant id; declare `merchantId` on verify/redeem to have the audience check enforced (standard JWT libraries give you the same check free on offline verification).
 
@@ -889,6 +1007,18 @@ answered by the checkpoint; the agent needs no `apiEndpoint` of its own.
 
 Newest first. Full detail for every release is in [CHANGELOG.md](./CHANGELOG.md).
 
+### v5.18.0 — checkout kit fixes, orders, Express mounting, MPP interop
+
+- UCP / ACP kits: holds never settle; `resolvePending()` finishes a pending settlement; `complete` claims the session (store `claim`) so concurrent completes can't both charge; sessions and idempotency keys are scoped to the caller.
+- UCP: exactly one payment instrument; `UCP-Agent` bound to the verified agent; `links` in the signed checkout; GETs don't re-sign; order capability (`GET /orders/{id}`, `buildUcpOrder`, signed order webhooks).
+- ACP: `unsupported_api_version`, echoed `Idempotency-Key` / `Request-Id`, 405 on canceling a finished session, order line items and `permalink_url`, `buildAcpWellKnown()`.
+- `expressHandler(kit)` mounts a kit on Express with the raw body kept; Express `defaultRoutePolicy` and observe-mode evaluation of unmatched routes for credentialed callers.
+- MPP challenge ids now match mppx; `buildMpp402Response()`; `verifyMppChallenge` checks the body digest and can accept each challenge once.
+
+### v5.17.2 — guard browse says where to approve
+
+- `astrasync guard browse` prints the approval link while it waits for the owner's passkey.
+
 ### v5.17.1 — one approval for a route that holds its own
 
 - `approvalHeldByRoute` (Express): a route that holds its own owner approval receives an approval-only result instead of a refusal, and verify-access creates no approval — the owner approves once.
@@ -909,6 +1039,10 @@ Newest first. Full detail for every release is in [CHANGELOG.md](./CHANGELOG.md)
   registers each call while it is in flight; otherwise call
   `registerPending()` / `removePending()` around each interaction.
 
+### v5.15.0 — agentic commerce protocols
+
+- AP2 v0.2 mandates, UCP (profile, negotiation, signatures, webhooks) and ACP checkout kits, KYAPay token verification, RFC 9421 request signing, request idempotency, and merchant helpers for x402 v2 and MPP.
+
 ### v4.1.0 — Trusted Agent Gateway naming + MCP metadata capture
 
 - The Next.js unverified-agent overlay is now the **verification interstitial**: `showInterstitial` option, `VerificationInterstitial` / `useVerificationInterstitial` / `VerificationInterstitialProps`. The old `showCommerceShield` / `CommerceShield` / `useCommerceShield` / `CommerceShieldProps` names keep working as deprecated aliases until the next major (`showInterstitial` wins when both options are set).

package/dist/adapters/express.d.mts

@@ -1,5 +1,5 @@
 import { RequestHandler, Request } from 'express';
-import { d as VerificationResult, E as ExpressMiddlewareOptions, a as AstraSyncCredentials } from '../types-DRb_plOh.mjs';
+import { d as VerificationResult, E as ExpressMiddlewareOptions, a as AstraSyncCredentials } from '../types-Cns4l8gX.mjs';
 
 /**
  * AstraSync Universal Verification Gateway - Express Middleware

package/dist/adapters/express.d.ts

@@ -1,5 +1,5 @@
 import { RequestHandler, Request } from 'express';
-import { d as VerificationResult, E as ExpressMiddlewareOptions, a as AstraSyncCredentials } from '../types-DRb_plOh.js';
+import { d as VerificationResult, E as ExpressMiddlewareOptions, a as AstraSyncCredentials } from '../types-Cns4l8gX.js';
 
 /**
  * AstraSync Universal Verification Gateway - Express Middleware

package/dist/adapters/express.js

@@ -316,6 +316,23 @@ function detectCommerce(req, host) {
   }
   const signature = headerValue(req, "signature");
   const signatureInput = headerValue(req, "signature-input");
+  if (/\/checkout[-_]sessions(\/|$)/.test(req.uri) && headerValue(req, "ucp-agent")) {
+    const signed = Boolean(signature && signatureInput);
+    return {
+      protocol: "ucp",
+      artifacts: {
+        ucpRequest: { method, url, ...jsonBody && { body: jsonBody } },
+        ...signed && {
+          rfc9421: { headers, method, url, ...req.bodyText && { body: req.bodyText } }
+        }
+      },
+      evidence: {
+        path: req.uri,
+        ...signed && { keyid: signatureInput.match(/keyid="([^"]+)"/)?.[1] },
+        ...truncated
+      }
+    };
+  }
   if (signature && signatureInput) {
     const signatureAgent = headerValue(req, "signature-agent");
     const registryHint = headerValue(req, "x-agent-registry");
@@ -350,13 +367,6 @@ function detectCommerce(req, host) {
       evidence: { hasTimestamp: Boolean(acpTimestamp), ...truncated }
     };
   }
-  if (/\/checkout[-_]sessions(\/|$)/.test(req.uri) && headerValue(req, "ucp-agent")) {
-    return {
-      protocol: "ucp",
-      artifacts: { ucpRequest: { method, url, ...jsonBody && { body: jsonBody } } },
-      evidence: { path: req.uri, ...truncated }
-    };
-  }
   if (jsonBody) {
     const intent = jsonBody.intent_mandate ?? jsonBody.intentMandate;
     const cart = jsonBody.cart_mandate ?? jsonBody.cartMandate;
@@ -469,7 +479,7 @@ function routePolicyOf(route) {
 }
 
 // src/version.ts
-var SDK_VERSION = "5.17.2";
+var SDK_VERSION = "5.18.0";
 
 // src/http.ts
 var SDK_USER_AGENT = `astrasync-sdk/${SDK_VERSION}`;
@@ -2361,6 +2371,7 @@ function createMiddleware(options) {
     anonymousBeacon = true,
     trustVerifiedHop = false,
     verifiedHopMaxAgeMs,
+    defaultRoutePolicy = "pass",
     ...config
   } = options;
   if (config.apiBaseUrl) {
@@ -2426,12 +2437,15 @@ function createMiddleware(options) {
         });
       }
       const correlationId = req.headers["x-request-id"] || req.headers["x-correlation-id"];
-      const routeConfig = findRouteConfig(cachedRoutes, req.path, req.method, {
+      const matchedRoute = findRouteConfig(cachedRoutes, req.path, req.method, {
         caseInsensitive: caseInsensitiveRouteMatch,
         logShadowDivergence: true,
         correlationId
       });
-      if (!routeConfig) {
+      const credentials = customExtractCredentials ? customExtractCredentials(req) : defaultExtractCredentials(req);
+      const credentialed = Boolean(credentials.astraId || credentials.apiKey || credentials.jwt);
+      const observeUnmatched = !matchedRoute && (config.evaluateAlwaysIfCredentialed === true && Boolean(credentials.astraId) || defaultRoutePolicy === "observe" && credentialed);
+      if (!matchedRoute && !observeUnmatched) {
         if (config.setPassThroughHeader) {
           res.setHeader("X-Astra-Gateway-Mode", "unenforced");
           res.setHeader(
@@ -2442,10 +2456,14 @@ function createMiddleware(options) {
         beaconPassThrough?.(req);
         return next();
       }
+      const routeConfig = matchedRoute ?? {
+        pattern: req.path,
+        method: req.method,
+        observe: true
+      };
       const wellKnownUrls = config.apiBaseUrl ? await getWellKnownUrls(config.apiBaseUrl).catch(() => void 0) : void 0;
-      const credentials = customExtractCredentials ? customExtractCredentials(req) : defaultExtractCredentials(req);
       const shouldEnforce = !routeConfig.observe;
-      if (routeConfig.observe && (!config.evaluateAlwaysIfCredentialed || !credentials.astraId)) {
+      if (routeConfig.observe && !observeUnmatched && (!config.evaluateAlwaysIfCredentialed || !credentials.astraId)) {
         if (config.setPassThroughHeader) {
           res.setHeader("X-Astra-Gateway-Mode", "unenforced");
           res.setHeader("X-Astra-Gateway-Reason", "route-observe");