@astrasyncai/verification-gateway 5.19.0 → 5.21.0

package/CHANGELOG.md

@@ -8,6 +8,136 @@ 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.21.0] — 2026-10-26 — endpoint changes are dashboard-only, agent commerce studio rules
+
+### Removed (breaking, security — shops' item 48)
+
+- **`VerificationGatewayClient.updateEndpoint`** and the `EndpointOperationalPatch`
+  type. After registration, endpoint settings (checkout, catalogue, events,
+  skill and health check URLs) change in the dashboard only, behind the
+  owner's login and MFA; the platform now refuses API keys on
+  `PATCH /api/endpoints/:id` (403). Why: a merchant's API key lives in its
+  host's environment, and a host compromise must not let a leaked key point
+  agents at another checkout or catalogue under the merchant's verified
+  identity. Every dashboard change to one of these URLs alerts the owner.
+- **`sendTestEvent(id, { approvalId })`.** From code the test event is
+  synthetic only (an `approvalId` is no longer sent; the platform answers 403
+  `dashboard_only` to an API key that sends one). A real held approval's
+  payload releases or re-drives that checkout, so it is sent from the
+  endpoint page in the dashboard.
+
+### Changed
+
+- **The default AstraSync API base is `https://astrasync.ai/api`** (gateway
+  online mode, the transport's default verify URL, README examples), the same
+  as `verify()`'s documented base. `api.astrasync.ai` still answers; pass
+  `apiBaseUrl` explicitly as before if you set one.
+
+### Added — agent commerce studio rules
+
+- **`createAgentCommerce({ apiBaseUrl, apiKey, counterpartyId })`** fetches
+  the rules you set in the dashboard (endpoint → Agent commerce) every 5
+  minutes and keeps the last good copy when a fetch fails: product
+  visibility, agent price, the image agents get, a verified-agent discount,
+  and card issuer offers. AstraSync stores rules only; it hosts nothing.
+  `report({ catalogUrl, checkoutUrl, eventsUrl })` tells the dashboard where
+  your kit lives — shown as suggestions you confirm; it never sets a URL.
+- **`serveAgentCatalog({ commerce, products })`** serves your catalogue to
+  agents priced and filtered by those rules (`issuer_offer` marks a
+  cardholder-priced line). **`fromFeed(url)`** reads a Shopify
+  `products.json`, Google Merchant XML, CSV or JSON feed you already have.
+- **Kits: `agentCommerce`.** The UCP and ACP kits price lines with the same
+  rules, so the agent's price is the price you charge. A cardholder price
+  applies on `X-Astra-Issuer-Program` (sent by the AstraSync bridge) and the
+  confirm carries `metadata.issuerProgram`; AstraSync refuses the purchase
+  unless the buyer is that programme's cardholder. Pass `metadata` through
+  in your `verifyPurchase`.
+- `issuerOfferPrice` / `priceForAgent`: the shared price rule (percent off,
+  half up, clamped).
+
+## [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)

package/README.md

@@ -73,7 +73,7 @@ import { createMiddleware } from '@astrasyncai/verification-gateway/nextjs';
 // v2.3.7+ — per-route policy lives in the AstraSync dashboard.
 // The SDK fetches it on init via counterpartyId; do NOT pass routes here.
 export const middleware = createMiddleware({
-  apiBaseUrl: 'https://api.astrasync.ai',
+  apiBaseUrl: 'https://astrasync.ai/api', // always includes /api
   apiKey: process.env.ASTRASYNC_API_KEY,
   counterpartyId: 'ASTRAE-...',
   showInterstitial: true,
@@ -90,7 +90,7 @@ export const config = {
 import { createClient } from '@astrasyncai/verification-gateway/sdk';
 
 const gateway = createClient({
-  apiBaseUrl: 'https://api.astrasync.ai',
+  apiBaseUrl: 'https://astrasync.ai/api', // always includes /api
 });
 
 // Verify another agent before interacting
@@ -439,6 +439,27 @@ refresh, with no deploy.
 - 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)
 
@@ -766,7 +787,13 @@ falling back to `store.findByCheckoutSessionId(checkoutSessionId)`:
   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 a message.
+  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
@@ -784,7 +811,29 @@ 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).
+  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`,

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 { e as VerificationResult, E as ExpressMiddlewareOptions, b as AstraSyncCredentials } from '../types-DqWPkiYl.mjs';
+import { e as VerificationResult, E as ExpressMiddlewareOptions, b as AstraSyncCredentials } from '../types-DHHyXtuZ.mjs';
 
 /**
  * AstraSync Universal Verification Gateway - Express Middleware

package/dist/adapters/express.d.ts

@@ -1,5 +1,5 @@
 import { RequestHandler, Request } from 'express';
-import { e as VerificationResult, E as ExpressMiddlewareOptions, b as AstraSyncCredentials } from '../types-DqWPkiYl.js';
+import { e as VerificationResult, E as ExpressMiddlewareOptions, b as AstraSyncCredentials } from '../types-DHHyXtuZ.js';
 
 /**
  * AstraSync Universal Verification Gateway - Express Middleware

package/dist/adapters/express.js

@@ -479,7 +479,7 @@ function routePolicyOf(route) {
 }
 
 // src/version.ts
-var SDK_VERSION = "5.19.0";
+var SDK_VERSION = "5.21.0";
 
 // src/http.ts
 var SDK_USER_AGENT = `astrasync-sdk/${SDK_VERSION}`;
@@ -994,6 +994,9 @@ async function callVerifyAccessAPI(config, request) {
   if (requestData.enableRuntimeChallenge)
     body.enableRuntimeChallenge = requestData.enableRuntimeChallenge;
   if (requestData.routePolicy) body.routePolicy = requestData.routePolicy;
+  if (config.actingProof?.connectorToken) {
+    body.actingProof = { connectorToken: config.actingProof.connectorToken };
+  }
   if (requestData.approvalHeldByRoute) body.approvalHeldByRoute = true;
   if (requestData.createSession) body.createSession = requestData.createSession;
   if (requestData.durationRequired) body.durationRequired = requestData.durationRequired;
@@ -1161,22 +1164,46 @@ async function verify(config, request, options) {
       "[VerificationGateway] minTrustScore / minTrustScoreForFull are deprecated in v2.3.0 and have no effect. Server is now the single source of truth for access decisions (verified ID + runtime challenge + PDLSS + trust score). To gate access to an endpoint, configure the endpoint's trust_score_requirement server-side."
     );
   }
-  const uncacheable = Boolean(request.commerceArtifacts);
+  const uncacheable = Boolean(request.commerceArtifacts) || Boolean(mergedConfig.actingProof);
   if (mergedConfig.cacheTtl !== 0 && !options?.bypassCache && !uncacheable) {
     const cached = getCachedResult(request, mergedConfig.counterpartyId);
     if (cached) {
       if (mergedConfig.debug) {
         console.log("[VerificationGateway] Returning cached result");
       }
-      const hit = { ...cached };
-      if (request.attemptId) {
-        hit.attemptId = request.attemptId;
-      } else {
-        delete hit.attemptId;
-      }
-      return hit;
+      return sharedVerdict(cached, request);
+    }
+  }
+  if (mergedConfig.cacheTtl !== 0 && !options?.bypassCache && !uncacheable) {
+    const key = getCacheKey(request, mergedConfig.counterpartyId);
+    const pending = inflightVerifies.get(key);
+    if (pending) return sharedVerdict(await pending, request);
+    const flight = verifyViaApi(mergedConfig, request, urls, uncacheable);
+    inflightVerifies.set(key, flight);
+    try {
+      return await flight;
+    } finally {
+      inflightVerifies.delete(key);
     }
   }
+  return verifyViaApi(mergedConfig, request, urls, uncacheable);
+}
+var inflightVerifies = /* @__PURE__ */ new Map();
+var sharedVerdicts = /* @__PURE__ */ new WeakSet();
+function isSharedVerdict(result) {
+  return sharedVerdicts.has(result);
+}
+function sharedVerdict(source, request) {
+  const hit = { ...source };
+  if (request.attemptId) {
+    hit.attemptId = request.attemptId;
+  } else {
+    delete hit.attemptId;
+  }
+  sharedVerdicts.add(hit);
+  return hit;
+}
+async function verifyViaApi(mergedConfig, request, urls, uncacheable) {
   const enrichedRequest = { ...request };
   if (!enrichedRequest.counterpartyUrl && mergedConfig.counterpartyUrl) {
     enrichedRequest.counterpartyUrl = mergedConfig.counterpartyUrl;
@@ -1255,7 +1282,9 @@ async function verify(config, request, options) {
       fulfilment: apiResponse.fulfilment,
       mandates: apiResponse.mandates,
       kyaToken: apiResponse.kyaToken,
-      aep: apiResponse.aep
+      aep: apiResponse.aep,
+      // 5.20.0 (round 29.1): non-fatal integration warnings (e.g. events_url_missing).
+      warnings: apiResponse.warnings
     };
     return result2;
   }
@@ -1323,7 +1352,9 @@ async function verify(config, request, options) {
     // 5.15.0: merchant-lane AP2 mandates + KYAPay identity token.
     mandates: apiResponse.mandates,
     kyaToken: apiResponse.kyaToken,
-    aep: apiResponse.aep
+    aep: apiResponse.aep,
+    // 5.20.0 (round 29.1): non-fatal integration warnings (e.g. events_url_missing).
+    warnings: apiResponse.warnings
   };
   if (result.recommendation === "deny") {
     result.policyAllowed = false;
@@ -1349,8 +1380,18 @@ async function verify(config, request, options) {
       cacheResult(request, result, mergedConfig.cacheTtl, mergedConfig.counterpartyId);
     }
   }
+  notifyVerificationListeners(request, result);
   return result;
 }
+var verificationListeners = /* @__PURE__ */ new Set();
+function notifyVerificationListeners(request, result) {
+  for (const listener of verificationListeners) {
+    try {
+      listener(result, request);
+    } catch {
+    }
+  }
+}
 async function recordDecision(config, sessionId, decision, reason) {
   const headers = { "Content-Type": "application/json" };
   if (config.apiKey) {
@@ -1373,6 +1414,7 @@ async function fetchRoutes(config, counterpartyId, options = {}) {
     headers["X-API-Key"] = config.apiKey;
   }
   try {
+    headers["X-AstraSync-SDK-Version"] = SDK_VERSION;
     const response = await sdkFetch(
       `${config.apiBaseUrl}/endpoints/${encodeURIComponent(counterpartyId)}/routes` + (options.codeGates?.length ? `?codeGates=${options.codeGates.map(encodeURIComponent).join(",")}` : ""),
       { method: "GET", headers }
@@ -1387,6 +1429,13 @@ async function fetchRoutes(config, counterpartyId, options = {}) {
       return null;
     }
     const body = await response.json();
+    const type = body.data?.counterpartyType;
+    if (typeof type === "string" && options.onEndpointType) {
+      try {
+        options.onEndpointType(type);
+      } catch {
+      }
+    }
     return body.data?.routes ?? [];
   } catch {
     return null;
@@ -2665,14 +2714,14 @@ function createMiddleware(options) {
           res.setHeader("X-Astra-Gateway-Mode", "enforced");
           res.setHeader("X-Astra-Gateway-Reason", "evaluated-not-enforced");
         }
-        if (shouldRecordDecisions && sessionId) {
+        if (shouldRecordDecisions && sessionId && !isSharedVerdict(result)) {
           recordDecision(config, sessionId, "granted").catch(() => {
           });
         }
         return next();
       }
       if (!result.policyAllowed) {
-        if (shouldRecordDecisions && sessionId) {
+        if (shouldRecordDecisions && sessionId && !isSharedVerdict(result)) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
           });
         }
@@ -2685,7 +2734,7 @@ function createMiddleware(options) {
       }
       if (requiresHumanApproval(result)) {
         annotateApprovalRequired(result);
-        if (shouldRecordDecisions && sessionId) {
+        if (shouldRecordDecisions && sessionId && !isSharedVerdict(result)) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
           });
         }
@@ -2710,7 +2759,7 @@ function createMiddleware(options) {
               documentationUrl: wellKnownUrls.documentationUrl
             };
           }
-          if (shouldRecordDecisions && sessionId) {
+          if (shouldRecordDecisions && sessionId && !isSharedVerdict(result)) {
             recordDecision(config, sessionId, "denied", trustFailure.message).catch(() => {
             });
           }
@@ -2719,7 +2768,7 @@ function createMiddleware(options) {
           return;
         }
       }
-      if (shouldRecordDecisions && sessionId) {
+      if (shouldRecordDecisions && sessionId && !isSharedVerdict(result)) {
         recordDecision(config, sessionId, "granted").catch(() => {
         });
       }