@astrasyncai/verification-gateway 5.18.1 → 5.20.0

package/CHANGELOG.md

@@ -8,6 +8,238 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 Full architectural context for each release lives in the platform spec at
 `docs/research/adapter-architecture-technical-requirements.md`.
 
+## [5.20.0] — 2026-10-19 — fewer backend calls, recoverable declined holds, endpoint ops from code
+
+### Changed (behaviour)
+
+- **Declined kit holds are `recoverable`.** After a `step_up.denied`,
+  `step_up.expired` or `step_up.lapsed` event the UCP kit's
+  `approval_<reason>` message has severity `recoverable` and the ACP kit's
+  resolution is `recoverable` (both were `requires_buyer_review`): the
+  session is back in `ready_for_complete` / `ready_for_payment` and payable
+  with no further buyer step, matching the 5.19.0 `payment_failed` fix. The
+  code is the signal — platforms must not auto-retry on `approval_denied`.
+  The held response keeps `requires_buyer_review`.
+- **No decision POST on a shared verdict.** The express and MCP middlewares
+  no longer record a second decision when the verdict came from the cache or
+  from a concurrent identical call (the session already has its decision).
+- **Single-flight verify.** Concurrent identical cache misses share one
+  verify-access call; followers get a copy with their own `attemptId`.
+  `bypassCache` re-verifies and uncacheable requests never join a flight.
+
+### Added
+
+- `createMcpMiddleware({ skipEvaluation: { tools?, methods? } })`: unenforced
+  listed tools / methods pass through with no verify-access call, even with
+  `evaluateAlwaysIfCredentialed` (handshake, listing, `resources/read`, and
+  observe tools that verify in their own handler).
+- `createMcpMiddleware` warns once when its `counterpartyId` is not an
+  `mcp_server` endpoint (the routes fetch now carries the endpoint's
+  `counterpartyType`; `fetchRoutes(…, { onEndpointType })`). Tool rules need a
+  separate `mcp_server` endpoint for the site's MCP server.
+- `isSharedVerdict(result)` and `onVerificationResult(listener)` (root
+  exports).
+- **MCP middleware carries the attempt chain** (express / Next.js / edge
+  parity): `X-Astra-Attempt-Id`, else `params._meta.astrasync.attemptId`, is
+  sent as the verify `attemptId` (malformed values dropped). A tool call the
+  AstraSync bridge proved (acting proof bound to the attempt) is no longer
+  held at an `mcp_server` venue.
+- `GatewayConfig.actingProof?: { connectorToken }` is sent as `actingProof`
+  in the verify-access body (honoured only from a first-party AstraSync
+  service caller; a verify carrying it is never cached).
+- `VerificationGatewayClient.updateEndpoint(id, { eventsUrl, healthCheckUrl,
+  skillUrl, catalogUrl, checkoutUrl })` → `PATCH /api/endpoints/:id`
+  (operational URLs only, API key of the owner or an org member) and
+  `sendTestEvent(id, { type, approvalId? })` → `POST
+  /api/endpoints/:id/events/test` (one signed step-up event delivered now;
+  returns `{ delivered, status, responseCode, error, eventId, type,
+  approvalId }`). Types `EndpointOperationalPatch`, `TestEventType`,
+  `TestEventResult`.
+- Kits' `pollHeldSessions` releases a `lapsed` approval (UCP and ACP);
+  `StepUpApprovalStatus` gains `'lapsed'`.
+- ACP: `approval_required` / `approval_denied` / `approval_expired` /
+  `approval_lapsed` join the passthrough message codes.
+- UCP profiles' `signing_keys` are accepted alongside `keys` (the kit's
+  platform-signature check and the profile parser read both, skipping
+  `use: "enc"` keys); `ucpProfileKeys(profile)` is exported from the root.
+- **Kits' catalog item carries the product image.** `CatalogItem` (exported
+  as `UcpCatalogItem`) gains optional `image_url` (an absolute http(s) URL)
+  and `description`. The UCP kit keeps them on `line_items[].item`; the ACP
+  kit carries them on each line's `item` and on the order's line items. A
+  relative or invalid `image_url` is dropped when the kit prices the line.
+- **`fetchRoutes` sends an `X-AstraSync-SDK-Version` header** on the routes
+  fetch, so the endpoint's SDK version on the dashboard updates from the
+  5-minute routes refresh (MCP traffic may never send a verify-access naming
+  the `mcp_server` endpoint). The URL is unchanged, so mocks matching
+  `…/routes` keep working. Round 29.1 backends also read the version from
+  the `User-Agent` for older SDKs.
+- `VerificationWarning` type (root export) for the result's `warnings[]`.
+
+### Fixed
+
+- **The verification result carries verify-access `warnings[]`** (e.g.
+  `events_url_missing`). It reached the wire, but both result builders
+  dropped it.
+- **The UCP kit verifies signed platform requests with `signing_keys` too.**
+  Only the mandate-key path read them, so a platform profile that published
+  only `signing_keys` got `key_not_found` on its request signatures.
+
+### Changed (types)
+
+- `registration/types.ts`: the trust-score fields on registration and
+  verification responses are optional — the platform no longer returns an
+  agent's score to the agent or the public (counterparties still see it in
+  verify-access).
+
+## [5.19.0] — 2026-10-18 — approval events for held kit checkouts, MCP tool rules, fail-closed default
+
+### Changed (behaviour)
+
+- **`failOnError` defaults to `'closed'`** in `createMcpMiddleware` and the
+  express `createMiddleware`. When the middleware itself throws, the request
+  now gets `503` + `Retry-After` + `VERIFICATION_UNAVAILABLE` (MCP: JSON-RPC
+  `-32003`) and the handler is not called. `'open'` (pass through unverified)
+  stays available as an explicit opt-in. The `[SHADOW] would-have-denied`
+  line is still logged on every throw. (Audit F-A1-06.)
+- **ACP `complete` validates `payment_data`.** It must be one object (not an
+  array) whose `handler_id` is a declared handler's `id` or `name` (e.g.
+  `voucher` / `ai.astrasync.voucher`); a missing handler id, an unknown handler
+  or an array is `400 invalid` with `param: '$.payment_data.handler_id'` and
+  nothing is verified.
+- **Checkout-kit `PUT` / update on a held session is refused** (`409
+checkout_awaiting_approval`): the owner is approving exactly that cart.
+- **A declined card leaves the kit session payable with a `recoverable`
+  message** — UCP `payment_failed` (a standard error; `requires_buyer_input`
+  implied a `requires_escalation` handoff) back in `ready_for_complete`, ACP
+  `payment_declined` back in `ready_for_payment`. Completing the same session
+  again (UCP: a fresh `Idempotency-Key`) verifies the same cart; the platform
+  records a new order beside the declined one and settles it once.
+- **Held kit responses are no longer stored under an `Idempotency-Key`**, so a
+  re-drive with the same key after the approval reaches the kit instead of
+  replaying the held response.
+
+### Added
+
+- **Owner approval completes a held checkout (UCP + ACP kits, item 27).** At a
+  hold the kit stores `_approvalId`, `_astraId`, `_attemptId`, the held
+  `line_items` / `totals` and the non-secret payment input. New:
+  - `kit.resumeApproved(sessionId)` — `validateCart` first (an invalid cart
+    returns before AstraSync: the approval is not redeemed, nothing charged),
+    then `verifyPurchase` with the same cart id and the stored held amount
+    (`catalog()` is never re-run), then settle → report → fulfil → order
+    webhook. No agent call.
+  - `kit.resumeDeclined(sessionId, reason)` — back to `ready_for_complete` /
+    `ready_for_payment` with a message.
+  - `handleApprovalEvents(rawBody, headers, secret | secret[], { kits, seen? })`
+    — verifies `X-AstraSync-Signature`, routes the event (`{ eventId, type:
+'step_up.approved' | 'step_up.denied' | 'step_up.expired' |
+'step_up.lapsed', approvalId, checkoutSessionId, kitSessionId?, protocol?,
+counterpartyId, agentAstraId, transactionValue, currency, decidedAt,
+redeemBy? }`) by `protocol` / `kitSessionId`, and answers `{ status, body
+}`: 2xx at a terminal outcome (the event id is marked seen only then), 503
+    on a transient failure or a non-terminal state, 401 on a bad signature.
+    `MemorySeenEvents` / `SeenEvents` for dedupe.
+  - `approvalEventsHandler({ secret, kits, seen? })` and
+    `expressHandler(kit, { approvalEventsPath, webhookSecret, approvalEventKits?,
+seenEvents? })` mount it on Express.
+  - `CheckoutStore.findByCheckoutSessionId?(id)` and `listHeld?()` (and the
+    ACP store equivalents); the memory stores implement them.
+  - `kit.pollHeldSessions({ sessionIds?, apiBaseUrl? })` — a fallback for
+    merchants that can't receive events.
+  - Card declined after redemption: the session is payable again with the
+    decline message; re-completing the same cart at the same amount re-sends
+    the same cart id and attempt id (the platform chain-passes the consumed
+    approval until its `redeemBy`).
+- **`agentArtifacts` and `metadata` on kit confirms (item 28).**
+  `verifyPurchase` receives `agentArtifacts` (UCP RFC 9421-signed: the covered
+  headers — never `authorization` / `cookie` — the method, the public URL and
+  the raw-body `contentDigest`; otherwise `{ unsigned: true }`; ACP always `{
+unsigned: true }`, its bearer is never forwarded) and `metadata: {
+kitSessionId, protocol }`. `confirmCheckout` forwards both on verify-access.
+  New types `AgentArtifacts`, `CheckoutMetadata`.
+- **`validateCart(session) → KitMessage[]`** on both kits (item 29) — runs on
+  create, update and complete before AstraSync; errors keep the session
+  `incomplete` (UCP, `recoverable` with `path`) / `not_ready_for_payment` (ACP,
+  `invalid` with `param`). `catalog(itemId, quantity)` also receives the
+  quantity.
+- **`publicOrigin`** on both kits (item 24), used by `expressHandler` to
+  rebuild the request URL (UCP default: the origin of `profile.endpoint`; ACP:
+  `X-Forwarded-Proto` / `X-Forwarded-Host` only under Express `trust proxy`).
+- **ACP `links`** option, rendered on every session (item 26).
+- **`reportRetry` and `onReportError`** on both kits (item 21): settlement
+  reports retry on network / 429 / 5xx (3 attempts with backoff); a final
+  failure — or an order webhook that fails after its retries — calls
+  `onReportError(err, { sessionId, orderId })` (default `console.error`).
+  Without an `orderId` the report uses the confirm's verification `sessionId`.
+- **MCP tool rules from the dashboard (item 18).** With `apiKey` +
+  `counterpartyId`, `createMcpMiddleware` fetches the endpoint's tool rules
+  (`{ tool, purpose, action, resource?, observe? }`) and refreshes them every
+  `routesRefreshMs` (default 5 min, shared cache helper with the express route
+  policy). A dashboard rule only tightens a code `toolGates` entry (`observe` /
+  no-purpose ignored; a differing purpose or action is checked in addition)
+  unless `toolGatePrecedence: 'dashboard'`; tools with no code gate follow the
+  dashboard rule; `legacy: true` path rules are ignored. Code-gated tool names
+  are sent on the fetch as `?codeGates=`. `fetchRoutes(config, id, {
+codeGates })`.
+- **`purposeSource`, `requestMethod`, `requestPath` on verify-access (item 20)** from the express and Next.js middlewares, so verify-access can keep a
+  dashboard route's purpose (e.g. `shopping.purchase`) on an MPP paid leg
+  after checking it against the endpoint's stored rules. `req.rawBody` (a
+  Buffer or string set by an `express.json({ verify })` hook) is documented as
+  the forwarded raw body.
+- **`client.quoteCheckout()`** — the quote leg (`commercePhase: 'quote'`: peek
+  only, no order, no approval redeemed). `verify()` accepts `commercePhase:
+'quote'`.
+- **`verifyAstraSyncWebhook` takes `secret | secret[]`** and accepts a `v1old`
+  signature value (the previous secret signs it for 24 h after a rotation);
+  `signAstraSyncWebhook(..., { previousSecret })`. `abandonIdempotent()`
+  releases a key without storing a non-terminal response.
+- The `behaviour.*` failure family (`behaviour.limit_probing`,
+  `behaviour.unattributed_limit_check`) is documented on `AccessFailure`.
+- **`result.agent.trustScore` is populated again** (the field existed; the
+  platform had stopped sending it). Rule: counterparties may see an agent's
+  trust score; the agent itself never does. verify-access returns the real
+  score (0–100) to an authenticated counterparty — merchant and service keys,
+  the kits, the edge adapter, AstraSync's bridge — and withholds it from a
+  keyless caller and from the agent itself (an agent session as that agent, or
+  its owner's key on a call that names no endpoint of the owner's). Never
+  relay it to the agent.
+
+### Fixed
+
+- **A verified agent's denied call keeps `result.agent`.** The deny branch
+  now maps the `agent` block the platform sends on a deny (as on a grant), so
+  a verified-but-denied agent is still identified (the MCP bridge keys its
+  per-agent budget on it); before, it fell back to the per-IP budget.
+- **A route's `minTrustScore` floor now gates on the real score and fails
+  closed when the score is absent** (express adapter). It had been passing
+  every agent since the platform stopped sending the score. The online-mode
+  decision `reason` no longer embeds the score (it is relayable text; the
+  number stays on `decision.trustScore`).
+
+- **A held kit checkout could never complete without the agent:** the bridge's
+  re-drive got the cached held response back, and nothing resumed the session
+  when the owner approved. See Added (item 27).
+- **`fulfil` now receives `settled`** (the processor's settled outcome),
+  including from `resolvePending` (item 22).
+- **MPP replay protection keyed on the challenge id.** The replay key was the
+  body digest plus a `nonce` that mppx challenges don't carry, so two distinct
+  challenges over identical bodies inside the 60 s window were refused as a
+  replay. The key now includes the challenge's `id`; presenting the same
+  challenge twice is still refused.
+- **`resolvePending` finishes a session once** (item 23): it claims
+  `complete_in_progress` → `finishing` (rendered as `complete_in_progress`);
+  the losing call is a no-op, and if finishing throws the session returns to
+  `complete_in_progress` with its pending settlement intact so the next call
+  retries.
+- **Kit settlement reports were dropped silently** on any error (item 21).
+
+### Deprecated
+
+- A `verify()` with a `transactionValue` and no `commercePhase` is a purchase
+  leg (it records a pending order and redeems a matching approval). 5.19.0
+  warns once per process; **6.0 changes the default to `'quote'`** — use
+  `quoteCheckout()` for checks and `confirmCheckout()` for purchases.
+
 ## [5.18.1] — 2026-10-17 — guard browse --open; proxy help page; browser command printed
 
 ### Added

package/README.md

@@ -285,7 +285,7 @@ mcp.use(
     apiBaseUrl: 'https://astrasync.ai/api',
     apiKey: process.env.ASTRASYNC_API_KEY,
     counterpartyId: 'ASTRAE-mcp...',
-    toolGates: { start_checkout: 'standard' },
+    toolGates: { start_checkout: { purpose: 'shopping', action: 'shopping.purchase' } },
   })
 );
 
@@ -408,6 +408,78 @@ dashboard session token authenticates. A request that offers only
 first-step sign-in tokens (before the second factor), refresh tokens and
 passkey elevation tokens are refused with 401.
 
+## Failure posture (`failOnError`, 5.19.0)
+
+When the middleware itself throws (a parsing failure, a proxy-state surprise),
+the express and MCP middlewares now **fail closed by default**: the request
+gets `503` + `Retry-After` + `VERIFICATION_UNAVAILABLE` (MCP: JSON-RPC
+`-32003`), never an identity-shaped 401, and your handler is not called. Set
+`failOnError: 'open'` explicitly to pass the request through unverified
+instead. A `[SHADOW] would-have-denied … correlationId=…` line is logged on
+every throw either way.
+
+## MCP tool rules (5.19.0)
+
+With `apiKey` + `counterpartyId` set, `createMcpMiddleware` fetches the
+endpoint's **tool rules** from the dashboard (`{ tool, purpose, action,
+resource?, observe? }`, refreshed every `routesRefreshMs`, default 5 minutes —
+the same cache the express route policy uses) and turns each into a gate for
+that `tools/call` tool. A rule edited in the dashboard takes effect after the
+refresh, with no deploy.
+
+- **Tighten-only by default.** For a tool you gate in code (`toolGates` object
+  form), a dashboard `observe` rule, or one with no purpose, is ignored; a
+  dashboard rule whose purpose or action differs is evaluated **in addition**
+  (both must pass). Tools with no code gate (or a code `'observe'`) follow the
+  dashboard rule.
+- `toolGatePrecedence: 'dashboard'` lets the dashboard rule win outright.
+- Path rules stored on an MCP endpoint before tool rules existed come back
+  `legacy: true` and are ignored — replace them with tool rules (a `* /mcp`
+  rule's `minAccessLevel` was removed in 5.0 and does nothing).
+- The middleware sends its code-gated tool names on the fetch
+  (`?codeGates=a,b`), so the dashboard marks those tools "gated in code — a
+  rule here can only add checks".
+- **One endpoint per surface (5.20.0).** Tool rules live on an `mcp_server`
+  endpoint. If your site and its MCP server share one (website) endpoint,
+  register a separate MCP endpoint for the MCP server — same owner; an API key
+  that operates your site endpoint may create it with `POST /api/endpoints` —
+  and use its id as the middleware's `counterpartyId`. The middleware warns
+  once (`console.warn`) when its `counterpartyId` is not an `mcp_server`
+  endpoint.
+
+## Fewer backend calls (5.20.0)
+
+- **Single-flight:** concurrent identical cache misses share one
+  verify-access call.
+- **No decision POST on a shared verdict:** a cache hit (or a single-flight
+  follower) no longer re-records the decision for the original session
+  (`isSharedVerdict(result)`).
+- **`skipEvaluation: { tools?, methods? }`** (MCP middleware): unenforced
+  listed calls pass through with no backend call — handshake / listing /
+  `resources/read`, and observe tools whose handler calls verify-access
+  itself.
+- **`onVerificationResult(listener)`** observes each verdict this process
+  fetched (the AstraSync bridge sizes its per-agent rate limit from it).
+
+## Route purpose on a paid leg (5.19.0)
+
+The express and Next.js middlewares send `purposeSource` (`'route_config'` |
+`'header'` | `'body'` | `'default'`) plus `requestMethod` / `requestPath` on
+every verify-access call. When a dashboard route rule set the purpose (e.g.
+`POST /api/checkout/* → shopping.purchase`), verify-access keeps it on an MPP
+paid leg (`Authorization: Payment …`) instead of replacing it with
+`commerce.payment.execute` — after checking that a **stored** rule on your
+endpoint matches that method and path with the same purpose and action. The
+claim is checked, never trusted.
+
+The gateway forwards the exact request bytes when your JSON parser keeps them
+on `req.rawBody` (a Buffer or string), so body digests match without mounting
+`express.raw`:
+
+```ts
+app.use(express.json({ verify: (req, _res, buf) => ((req as any).rawBody = buf) }));
+```
+
 ## Verification Response
 
 ```typescript
@@ -565,7 +637,15 @@ The first-party commerce rail: an agent shops under its ASTRA-id, holds NO
 payment credential, and the platform settles from the owner's saved
 instrument. Two phases discriminate quote from money movement:
 
-- `commercePhase: 'quote'` (or unphased) — verification only, never settles.
+- `commercePhase: 'quote'` — a price / limit check: peek only, no order, no
+  approval redeemed. Use `client.quoteCheckout({ astraId, transactionValue,
+currency, checkoutSessionId? })` (5.19.0). A plain `verify()` with a
+  `transactionValue` and no `commercePhase` is a **purchase leg** (it records
+  a pending order and redeems a matching approval); 5.19.0 warns once when you
+  call it that way, and the default becomes `'quote'` in 6.0. Quotes count
+  toward limit-probing detection (`behaviour.limit_probing` /
+  `behaviour.unattributed_limit_check`): quote what the buyer asked for, not a
+  ladder of values.
 - `commercePhase: 'confirm'` — the ONLY leg that can settle. Use
   `client.confirmCheckout({ astraId, transactionValue, currency,
 checkoutSessionId, checkoutItems, counterpartyUrl })`; `checkoutSessionId`
@@ -630,6 +710,7 @@ catalog, settlement and fulfilment. Both are fetch-style
 import {
   createUcpCheckoutKit,
   expressHandler,
+  approvalEventsHandler,
   RedisIdempotencyStore,
 } from '@astrasyncai/verification-gateway';
 
@@ -641,7 +722,9 @@ const ucp = createUcpCheckoutKit({
     orders: true, // dev.ucp.shopping.order: GET /orders/{id} + order webhooks
   },
   currency: 'USD',
-  catalog: async (id) => db.items.find(id),
+  catalog: async (id, quantity) => db.items.find(id),
+  // 5.19.0: cart-level checks (stock, caps) on create / update / complete.
+  validateCart: async (session) => stockMessages(session),
   verifyPurchase: (ctx) =>
     client.confirmCheckout({
       astraId: ctx.astraId,
@@ -650,6 +733,8 @@ const ucp = createUcpCheckoutKit({
       checkoutJwt: ctx.checkoutJwt,
       transactionValue: ctx.valueMajor,
       currency: 'USD',
+      agentArtifacts: ctx.agentArtifacts, // 5.19.0: attribution
+      metadata: ctx.metadata, // 5.19.0: { kitSessionId, protocol } for approval events
     }),
   settle: async ({ result }) => chargeWithYourProcessor(result), // settled | pending | failed
   reportSettlement: (r) => client.reportSettlement(r),
@@ -667,8 +752,99 @@ const ucp = createUcpCheckoutKit({
 
 app.get('/.well-known/ucp', (_req, res) => res.json(ucp.profile));
 app.use('/ucp/v1', express.raw({ type: '*/*' }), expressHandler(ucp));
+// 5.19.0: owner-approval events for held checkouts (both kits, one URL —
+// set it as the endpoint's Events URL in the dashboard).
+app.post(
+  '/astrasync/events',
+  express.raw({ type: '*/*' }),
+  approvalEventsHandler({ secret: process.env.ASTRASYNC_WEBHOOK_SECRET!, kits: [ucp, acp] })
+);
+```
+
+**Owner approval completes a held checkout (5.19.0).** When a purchase is
+held, the kit stores the approval id, the agent, the attempt chain, the held
+cart (`line_items` / `totals`) and the non-secret payment input (the UCP
+instrument descriptor, the ACP `payment_data` fields minus anything that looks
+like a credential). When the owner decides, AstraSync POSTs a signed event to
+your Events URL:
+
+```
+X-AstraSync-Signature: t=<unix>,v1=<hex>[,v1old=<hex>]
+{ "eventId", "type": "step_up.approved" | "step_up.denied" | "step_up.expired" | "step_up.lapsed",
+  "approvalId", "checkoutSessionId", "kitSessionId"?, "protocol"?: "ucp" | "acp",
+  "counterpartyId", "agentAstraId", "transactionValue", "currency", "decidedAt", "redeemBy"? }
 ```
 
+`handleApprovalEvents(rawBody, headers, secret | secret[], { kits, seen? })`
+(or `approvalEventsHandler` / `expressHandler(kit, { approvalEventsPath,
+webhookSecret })`) verifies it and routes it by `protocol` / `kitSessionId`,
+falling back to `store.findByCheckoutSessionId(checkoutSessionId)`:
+
+- **approved** → `kit.resumeApproved(sessionId)`: `validateCart` first (an
+  invalid cart returns with its message before AstraSync, so the approval is
+  not redeemed and nothing is charged), then `verifyPurchase` with the same
+  cart id and the **stored held amount** (`catalog()` is never re-run, so a
+  price change can't break the exact-value redemption), then settle → report
+  → fulfil → order webhook. No agent call.
+- **denied / expired / lapsed** → `kit.resumeDeclined(sessionId, reason)`:
+  back to `ready_for_complete` / `ready_for_payment` with an
+  `approval_denied` / `approval_expired` / `approval_lapsed` message. 5.20.0:
+  the message is `recoverable` (UCP severity, ACP resolution) — the session
+  is payable with no further buyer step. **Platforms should not auto-retry
+  on `approval_denied`** (the buyer said no; the code is the signal); after
+  `approval_expired` / `approval_lapsed` completing again requests a new
+  approval. The held response itself keeps `requires_buyer_review`.
+- **Card declined after redemption:** the session is payable again with the
+  decline message and the owner sees the failed outcome. Re-completing the
+  same cart at the same amount before the approval's `redeemBy` passes on the
+  consumed approval; after that, or for another cart, a new approval is needed.
+- **Retries:** `eventId` is stable; it is marked seen (`seen.add`) only when
+  the session reached a terminal state, answered 2xx (completed, card
+  declined, cart invalid, declined, already completed, canceled). A transient
+  failure (your store, your processor's 5xx) answers 503 so the platform
+  retries. Approved events retry for ~10½ minutes inside the 15-minute
+  `redeemBy`; an undelivered one is followed by `step_up.lapsed`.
+- **Secret rotation:** for 24 h after a rotation the previous secret signs a
+  second value, `v1old`; pass `[current, previous]` as the secret.
+- `PUT` (ACP: update) on a held session is refused (`409
+checkout_awaiting_approval`), and held responses are never stored under an
+  `Idempotency-Key`, so a re-drive after the approval reaches the kit.
+- `kit.pollHeldSessions({ sessionIds?, apiBaseUrl? })` polls held approvals
+  and resumes decided ones — a **fallback only** for merchants that can't
+  receive events (needs `store.listHeld()` when called without ids). 5.20.0:
+  a `lapsed` approval releases the session too.
+- **Set the Events URL and test it from code (5.20.0).** With the endpoint's
+  API key (the owner's, or a personal key of a member of the owning
+  organisation):
+
+  ```ts
+  import { createClient } from '@astrasyncai/verification-gateway/sdk';
+  const client = createClient({ apiBaseUrl, apiKey, counterpartyId: 'ASTRAE-…' });
+  await client.updateEndpoint(undefined, { eventsUrl: 'https://shop.example/astrasync/events' });
+  const r = await client.sendTestEvent(undefined, { type: 'step_up.lapsed' });
+  // r = { delivered, status: 'delivered'|'failed'|'not_configured', responseCode, error, eventId, … }
+  ```
+
+  `updateEndpoint` (`PATCH /api/endpoints/:id`) changes only operational
+  URLs — `eventsUrl`, `healthCheckUrl`, `skillUrl`, `catalogUrl`,
+  `checkoutUrl` (`null` clears); rules and other policy stay in the
+  dashboard. The owner is alerted when the Events URL changes.
+  `sendTestEvent` (`POST /api/endpoints/:id/events/test`) delivers one signed
+  event now, outside the retrying outbox. Pass `approvalId` (a held kit
+  approval at this endpoint) to get that approval's real payload so your
+  resume path runs: `approved` re-confirms (and is held again — nothing is
+  charged); the others release the session.
+
+**Agent attribution (5.19.0).** `verifyPurchase` receives `agentArtifacts`:
+for a UCP request signed with RFC 9421, the covered headers (`signature`,
+`signature-input`, `signature-agent`, `ucp-agent`, `content-digest`, … — never
+`authorization` or `cookie`), the method, the **public** URL (`publicOrigin` +
+path + query) and `contentDigest` (`sha-256=:…:` of the raw body); otherwise
+`{ unsigned: true }`. ACP confirms are always `{ unsigned: true }`: the ACP
+`Authorization` bearer is the platform's credential to you and is never
+forwarded, so ACP confirms are unattributable to the agent. Pass
+`agentArtifacts` and `metadata` straight to `confirmCheckout`.
+
 - **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`).
@@ -693,7 +869,30 @@ checkout_in_progress` (ACP). Without `claim` the kit warns once and the lock
   (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.
+  mandates. 5.19.0: it claims the session first (`complete_in_progress` →
+  `finishing`, rendered as `complete_in_progress`), so concurrent webhooks
+  finish it once; if finishing throws, the session goes back with its pending
+  settlement intact and the next call retries.
+- **`fulfil({ session, result, settled })`** (5.19.0) — `settled` is your
+  processor's settled outcome (`processorRef` / `txHash`).
+- **Settlement reports retry** (5.19.0) on network errors, 429 and 5xx
+  (`reportRetry`, default 3 attempts with backoff); a report that still fails
+  goes to `onReportError(err, { sessionId, orderId })` (default
+  `console.error`), as does an order webhook that fails after its retries.
+  Without an `orderId` the report identifies the order by the confirm's
+  verification `sessionId`.
+- **`validateCart(session) → KitMessage[]`** (5.19.0) — runs on create, update
+  and complete, before the session is claimed and before `verifyPurchase`. Any
+  error (`{ code, content, path? }`) keeps the session `incomplete` (UCP,
+  `recoverable` with `path`) / `not_ready_for_payment` (ACP, `invalid` with
+  `param`), and `complete` is refused without calling AstraSync. `catalog`
+  also receives the requested quantity.
+- **`publicOrigin`** (5.19.0, both kits) — the origin agents reach you at.
+  `expressHandler` rebuilds the request URL from it, so RFC 9421
+  `@target-uri` / `@authority` verify behind a TLS-terminating proxy. UCP
+  defaults to the origin of `profile.endpoint`; ACP falls back to
+  `X-Forwarded-Proto` / `X-Forwarded-Host` only when Express `trust proxy` is
+  set.
 - **One instrument (UCP).** `complete` needs exactly one
   `payment.instruments[]` entry whose `handler_id` is one of your
   `payment_handlers`; anything else is `payment_failed`.
@@ -721,6 +920,12 @@ checkout_in_progress` (ACP). Without `claim` the kit warns once and the lock
   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 `complete`** (5.19.0) — `payment_data` must be **one object** (not an
+  array) whose `handler_id` is a declared handler's `id` or `name` (e.g.
+  `voucher` / `ai.astrasync.voucher`); a missing handler id, an unknown handler
+  or an array is `400 invalid` with `param: '$.payment_data.handler_id'`, and
+  nothing is verified. `links` (`{ type, url, title? }`) are returned on every
+  session.
 - **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;
@@ -1007,6 +1212,14 @@ 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.19.0 — approval events for held kit checkouts, MCP tool rules, fail-closed default
+
+- **Behaviour change:** `failOnError` defaults to `'closed'` (express + MCP); `'open'` is opt-in.
+- Kits: owner approval completes a held checkout with no agent call (`handleApprovalEvents`, `resumeApproved` / `resumeDeclined`, `pollHeldSessions`); `validateCart`; `agentArtifacts` + `metadata` on confirms; `publicOrigin`; report retries + `onReportError`; `fulfil` gets `settled`; `resolvePending` claims the session; ACP `payment_data` rule and `links`.
+- MCP: dashboard tool rules (tighten-only, `toolGatePrecedence: 'dashboard'` opt-in).
+- Express / Next.js: `purposeSource` + `requestMethod` / `requestPath` keep a route purpose on an MPP paid leg; `req.rawBody` documented.
+- `quoteCheckout()`; one-time warning for a valued `verify()` with no `commercePhase` (default flips to quote in 6.0); `verifyAstraSyncWebhook` takes `secret[]` and `v1old`.
+
 ### 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.

package/dist/adapter-interface/interface.d.mts

@@ -1,6 +1,6 @@
 import { AstraSyncGateway } from '../gateway/gateway.mjs';
-import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-CfBpm3w5.mjs';
-import '../types-BfILnheI.mjs';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-Djpz-L0w.mjs';
+import '../types-CU17R4Nr.mjs';
 
 /**
  * PlatformAdapter Interface

package/dist/adapter-interface/interface.d.ts

@@ -1,6 +1,6 @@
 import { AstraSyncGateway } from '../gateway/gateway.js';
-import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-BRz2U0Pn.js';
-import '../types-BfILnheI.js';
+import { A as AgentAction, I as InterceptResult, P as PDLSSContext, V as VerificationDecision } from '../types-B_HLhZ9n.js';
+import '../types-CU17R4Nr.js';
 
 /**
  * PlatformAdapter Interface

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-Cns4l8gX.mjs';
+import { e as VerificationResult, E as ExpressMiddlewareOptions, b as AstraSyncCredentials } from '../types-CxjqmPl-.mjs';
 
 /**
  * AstraSync Universal Verification Gateway - Express Middleware
@@ -34,6 +34,14 @@ declare global {
     namespace Express {
         interface Request {
             agentVerification?: VerificationResult;
+            /**
+             * 5.19.0 (documented): the exact request bytes, when your JSON parser
+             * keeps them — `express.json({ verify: (req, _res, buf) => { req.rawBody = buf } })`.
+             * The gateway forwards these (not a re-serialised `req.body`) as the
+             * protocol artifacts' raw body, so body digests (MPP, RFC 9421
+             * content-digest) match without mounting `express.raw`.
+             */
+            rawBody?: Buffer | string;
         }
     }
 }

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-Cns4l8gX.js';
+import { e as VerificationResult, E as ExpressMiddlewareOptions, b as AstraSyncCredentials } from '../types-CxjqmPl-.js';
 
 /**
  * AstraSync Universal Verification Gateway - Express Middleware
@@ -34,6 +34,14 @@ declare global {
     namespace Express {
         interface Request {
             agentVerification?: VerificationResult;
+            /**
+             * 5.19.0 (documented): the exact request bytes, when your JSON parser
+             * keeps them — `express.json({ verify: (req, _res, buf) => { req.rawBody = buf } })`.
+             * The gateway forwards these (not a re-serialised `req.body`) as the
+             * protocol artifacts' raw body, so body digests (MPP, RFC 9421
+             * content-digest) match without mounting `express.raw`.
+             */
+            rawBody?: Buffer | string;
         }
     }
 }