@astrasyncai/verification-gateway 3.1.0 → 3.2.1

package/dist/adapters/mcp.d.mts

@@ -1,5 +1,5 @@
 import { Request, Response, RequestHandler } from 'express';
-import { A as AccessLevel, G as GatewayConfig, i as VerificationResult } from '../types-Cuh7ELfr.mjs';
+import { A as AccessLevel, G as GatewayConfig, i as VerificationResult } from '../types-rFh4VMH4.mjs';
 
 /**
  * MCP server-side helpers — companion to `transport/mcp.ts` (which handles the
@@ -264,16 +264,21 @@ interface McpMiddlewareOptions extends GatewayConfig {
      * Per-tool gating for `tools/call` invocations. Tools not listed inherit
      * the default tier from `mcpRiskTier` (`tools/call` → `'standard'`).
      *
-     * Accepts both the shorthand access-level string and the full object shape:
+     * Accepts both the shorthand access-level string and the full object shape.
+     * NOTE (3.2.0): the access-level band no longer gates, and a gated `tools/call`
+     * must carry a resolvable PDLSS **purpose** (the backend requires it). So the
+     * bare string shorthand — which carries no purpose — only works if the caller
+     * supplies the purpose another way (an `X-Astra-Purpose` header, or
+     * `params._meta.astrasync.purpose`); otherwise the call fails fast with a
+     * `PDLSS_PURPOSE_REQUIRED` 400. Prefer the **object form with `purpose`**:
      * ```typescript
      * toolGates: {
-     *   browse_catalog: 'read-only',                // shorthand
-     *   list_products:  { minAccessLevel: 'none',    // full shape
-     *                     purpose: 'shopping',
+     *   browse_catalog: 'read-only',                 // shorthand — purpose must come
+     *                                                // from a header / _meta, else 400
+     *   list_products:  { purpose: 'shopping',       // object form (recommended)
      *                     action: 'shopping.search',
      *                     resource: '/api/catalog' },
-     *   start_checkout: { minAccessLevel: 'standard',
-     *                     purpose: 'shopping',
+     *   start_checkout: { purpose: 'shopping',
      *                     action: 'shopping.purchase',
      *                     resource: '/api/checkout/*' },
      * }

package/dist/adapters/mcp.d.ts

@@ -1,5 +1,5 @@
 import { Request, Response, RequestHandler } from 'express';
-import { A as AccessLevel, G as GatewayConfig, i as VerificationResult } from '../types-Cuh7ELfr.js';
+import { A as AccessLevel, G as GatewayConfig, i as VerificationResult } from '../types-rFh4VMH4.js';
 
 /**
  * MCP server-side helpers — companion to `transport/mcp.ts` (which handles the
@@ -264,16 +264,21 @@ interface McpMiddlewareOptions extends GatewayConfig {
      * Per-tool gating for `tools/call` invocations. Tools not listed inherit
      * the default tier from `mcpRiskTier` (`tools/call` → `'standard'`).
      *
-     * Accepts both the shorthand access-level string and the full object shape:
+     * Accepts both the shorthand access-level string and the full object shape.
+     * NOTE (3.2.0): the access-level band no longer gates, and a gated `tools/call`
+     * must carry a resolvable PDLSS **purpose** (the backend requires it). So the
+     * bare string shorthand — which carries no purpose — only works if the caller
+     * supplies the purpose another way (an `X-Astra-Purpose` header, or
+     * `params._meta.astrasync.purpose`); otherwise the call fails fast with a
+     * `PDLSS_PURPOSE_REQUIRED` 400. Prefer the **object form with `purpose`**:
      * ```typescript
      * toolGates: {
-     *   browse_catalog: 'read-only',                // shorthand
-     *   list_products:  { minAccessLevel: 'none',    // full shape
-     *                     purpose: 'shopping',
+     *   browse_catalog: 'read-only',                 // shorthand — purpose must come
+     *                                                // from a header / _meta, else 400
+     *   list_products:  { purpose: 'shopping',       // object form (recommended)
      *                     action: 'shopping.search',
      *                     resource: '/api/catalog' },
-     *   start_checkout: { minAccessLevel: 'standard',
-     *                     purpose: 'shopping',
+     *   start_checkout: { purpose: 'shopping',
      *                     action: 'shopping.purchase',
      *                     resource: '/api/checkout/*' },
      * }

package/dist/adapters/mcp.js

@@ -32,26 +32,15 @@ __export(mcp_exports, {
 module.exports = __toCommonJS(mcp_exports);
 
 // src/access-levels.ts
-var ACCESS_LEVEL_HIERARCHY = {
-  none: 0,
-  restricted: 1,
-  "read-only": 2,
-  standard: 3,
-  full: 4,
-  internal: 5
-};
 function getTrustLevel(score) {
   if (score >= 80) return "PLATINUM";
   if (score >= 60) return "GOLD";
   if (score >= 40) return "SILVER";
   return "BRONZE";
 }
-function hasMinimumAccess(actual, required) {
-  return ACCESS_LEVEL_HIERARCHY[actual] >= ACCESS_LEVEL_HIERARCHY[required];
-}
 
 // src/version.ts
-var SDK_VERSION = "3.1.0";
+var SDK_VERSION = "3.2.1";
 
 // src/well-known.ts
 var CACHE_TTL_MS = 60 * 60 * 1e3;
@@ -156,7 +145,7 @@ async function performInitCheck(apiBaseUrl, debug, strictInit) {
   }
 }
 var verificationCache = /* @__PURE__ */ new Map();
-function getCacheKey(request) {
+function getCacheKey(request, counterpartyId) {
   const c = request.credentials;
   return [
     c.astraId || "",
@@ -169,6 +158,14 @@ function getCacheKey(request) {
     request.jurisdiction || "",
     request.transactionValue ?? "",
     request.currency || "",
+    // SECURITY (cross-merchant cache leak): the merchant identity is sent via
+    // `config.counterpartyId`, NOT on the request, so it was previously absent
+    // from the key — two verifies for the SAME agent/purpose/action/value but
+    // DIFFERENT merchants collided, and a grant at a permissive merchant (low
+    // trust floor) was served for a stricter one. Same bug class as the
+    // duration omission (F-A1-07). counterpartyId affects the backend verdict
+    // (trust floor / per-route policy), so it MUST key the cache.
+    counterpartyId || "",
     request.counterpartyUrl || "",
     request.counterpartyType || "",
     request.isSubAgentRequest ? "1" : "0",
@@ -192,8 +189,8 @@ function getCacheKey(request) {
     request.callerMetadata?.agentCardUrl || ""
   ].join("|");
 }
-function getCachedResult(request) {
-  const key = getCacheKey(request);
+function getCachedResult(request, counterpartyId) {
+  const key = getCacheKey(request, counterpartyId);
   const cached = verificationCache.get(key);
   if (cached && cached.expiresAt > Date.now()) {
     return cached.result;
@@ -205,9 +202,9 @@ function getCachedResult(request) {
 }
 var DEFAULT_AUTONOMOUS_TTL_SECONDS = 60;
 var DEFAULT_STEP_UP_TTL_SECONDS = 300;
-function cacheResult(request, result, configuredTtl) {
+function cacheResult(request, result, configuredTtl, counterpartyId) {
   const ttlSeconds = configuredTtl && configuredTtl > 0 ? configuredTtl : result.requiresStepUp ? DEFAULT_STEP_UP_TTL_SECONDS : DEFAULT_AUTONOMOUS_TTL_SECONDS;
-  const key = getCacheKey(request);
+  const key = getCacheKey(request, counterpartyId);
   verificationCache.set(key, {
     result,
     expiresAt: Date.now() + ttlSeconds * 1e3
@@ -399,7 +396,7 @@ async function verify(config, request) {
     );
   }
   if (mergedConfig.cacheTtl !== 0) {
-    const cached = getCachedResult(request);
+    const cached = getCachedResult(request, mergedConfig.counterpartyId);
     if (cached) {
       if (mergedConfig.debug) {
         console.log("[VerificationGateway] Returning cached result");
@@ -451,8 +448,8 @@ async function verify(config, request) {
       verifiedAt: /* @__PURE__ */ new Date(),
       // Extract sessionId so decisions can be recorded for denials too
       sessionId: apiResponse.sessionId,
-      // v2.3.10 (defect #34, round-4): anonymous traffic has no session →
-      // correlationId is the linking key for paired local_override events.
+      // Anonymous traffic has no session → correlationId is the per-attempt
+      // linking key (the sessionId-equivalent for anonymous callers).
       correlationId: apiResponse.correlationId,
       recommendation: apiResponse.recommendation,
       recommendationReasons: apiResponse.recommendationReasons
@@ -526,17 +523,14 @@ async function verify(config, request) {
     };
   } else if (result.recommendation === "step_up_required") {
     result.requiresStepUp = true;
-    if (ACCESS_LEVEL_HIERARCHY[result.accessLevel] > ACCESS_LEVEL_HIERARCHY["read-only"]) {
-      result.accessLevel = "read-only";
-    }
     result.denialReasons = result.recommendationReasons || ["Step-up verification required"];
   }
   if (mergedConfig.cacheTtl !== 0 && result.recommendation !== "deny") {
-    cacheResult(request, result, mergedConfig.cacheTtl);
+    cacheResult(request, result, mergedConfig.cacheTtl, mergedConfig.counterpartyId);
   }
   return result;
 }
-async function recordDecision(config, sessionId, decision, reason, override) {
+async function recordDecision(config, sessionId, decision, reason) {
   const headers = { "Content-Type": "application/json" };
   if (config.apiKey) {
     headers["Authorization"] = `Bearer ${config.apiKey}`;
@@ -545,38 +539,22 @@ async function recordDecision(config, sessionId, decision, reason, override) {
   await fetch(`${config.apiBaseUrl}/agents/verify-access/${sessionId}/decision`, {
     method: "POST",
     headers,
-    body: JSON.stringify({
-      decision,
-      reason,
-      ...override && {
-        overriddenBy: override.overriddenBy,
-        toolName: override.toolName,
-        requestedLevel: override.requestedLevel,
-        grantedLevel: override.grantedLevel
-      }
-    })
+    body: JSON.stringify({ decision, reason })
   }).catch(() => {
   });
 }
-async function recordAnonymousLocalOverride(config, correlationId, override, reason) {
-  const headers = { "Content-Type": "application/json" };
-  if (config.apiKey) {
-    headers["Authorization"] = `Bearer ${config.apiKey}`;
-    headers["X-API-Key"] = config.apiKey;
-  }
-  await fetch(`${config.apiBaseUrl}/agents/verify-access/local-override`, {
-    method: "POST",
-    headers,
-    body: JSON.stringify({
-      correlationId,
-      reason,
-      overriddenBy: override.overriddenBy,
-      toolName: override.toolName,
-      requestedLevel: override.requestedLevel,
-      grantedLevel: override.grantedLevel
-    })
-  }).catch(() => {
-  });
+
+// src/adapters/approval-gate.ts
+var APPROVAL_REASON = "Transaction is above the autonomous limit and requires human approval, which is not yet available \u2014 it cannot be completed automatically.";
+function requiresHumanApproval(result) {
+  return result.requiresStepUp === true || result.requiresApproval === true;
+}
+function annotateApprovalRequired(result) {
+  result.failures = [
+    ...result.failures ?? [],
+    { dimension: "commerce.intent.approval_required", message: APPROVAL_REASON }
+  ];
+  result.denialReasons = [APPROVAL_REASON, ...result.denialReasons ?? []];
 }
 
 // src/transport/mcp-server.ts
@@ -791,7 +769,6 @@ function createMcpMiddleware(options) {
         return next();
       }
       req.mcpRequest = parsed;
-      const wellKnownUrls = config.apiBaseUrl ? await getWellKnownUrls(config.apiBaseUrl).catch(() => void 0) : void 0;
       const headerRaw = req.headers["x-astra-id"] ?? req.headers["x-astra-agentid"];
       const headerAstraId = typeof headerRaw === "string" ? headerRaw : Array.isArray(headerRaw) ? headerRaw[0] : void 0;
       const bodyAstraId = parsed.agentIdFromBody;
@@ -828,7 +805,7 @@ function createMcpMiddleware(options) {
           return next();
         }
       }
-      const { level: minAccessLevel, source: gateSource } = resolveMinAccessLevel(parsed, {
+      const { level: minAccessLevel } = resolveMinAccessLevel(parsed, {
         toolGates,
         methodGates
       });
@@ -864,6 +841,23 @@ function createMcpMiddleware(options) {
           resolved_action: pdlss.action
         });
       }
+      if (!pdlss.purpose) {
+        const id = req.body?.id ?? null;
+        res.status(400).json({
+          jsonrpc: "2.0",
+          id,
+          error: {
+            code: -32602,
+            message: "PDLSS_PURPOSE_REQUIRED",
+            data: {
+              dimension: "pdlss.purpose",
+              detail: "This tool is access-gated but the call declared no PDLSS purpose. Supply a bare-category purpose via the X-Astra-Purpose header or params._meta.astrasync.purpose, or have the merchant set the tool\u2019s purpose in its toolGate config.",
+              resolvedAction: pdlss.action
+            }
+          }
+        });
+        return;
+      }
       const counterpartyUrl = config.counterpartyUrl || `${req.protocol}://${req.get("host")}${req.path}`;
       const shouldRecordDecisions = recordDecisions !== false;
       const result = await verify(config, {
@@ -887,7 +881,6 @@ function createMcpMiddleware(options) {
       });
       req.agentVerification = result;
       const sessionId = result.sessionId;
-      const correlationId = result.correlationId;
       if (!result.identityVerified || !result.policyAllowed) {
         if (shouldRecordDecisions && sessionId) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
@@ -897,6 +890,16 @@ function createMcpMiddleware(options) {
         onDenied(result, req, res);
         return;
       }
+      if (requiresHumanApproval(result)) {
+        annotateApprovalRequired(result);
+        if (shouldRecordDecisions && sessionId) {
+          recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
+          });
+        }
+        dedupeFailures(result);
+        onDenied(result, req, res);
+        return;
+      }
       if (!shouldEnforce) {
         if (config.setPassThroughHeader) {
           res.setHeader("X-Astra-Gateway-Mode", "enforced");
@@ -908,48 +911,6 @@ function createMcpMiddleware(options) {
         }
         return next();
       }
-      if (!hasMinimumAccess(result.accessLevel, minAccessLevel)) {
-        const insufficientFailure = {
-          dimension: "access_level.insufficient",
-          message: `Tool requires accessLevel '${minAccessLevel}'; agent has '${result.accessLevel}'.`,
-          guidance: "Request elevated access via step-up verification (coming soon \u2014 ships this month). Step-up lets the agent owner approve a one-time elevation for this specific counterparty + purpose without changing the agent's baseline trust score."
-        };
-        result.failures = [...result.failures ?? [], insufficientFailure];
-        result.denialReasons = [...result.denialReasons ?? [], insufficientFailure.message];
-        if (!result.guidance && wellKnownUrls) {
-          result.guidance = {
-            message: insufficientFailure.message,
-            registrationUrl: wellKnownUrls.registrationUrl,
-            documentationUrl: wellKnownUrls.documentationUrl
-          };
-        }
-        if (shouldRecordDecisions) {
-          const overrideKind = gateSource === "toolGate" ? "toolGate" : gateSource === "methodGate" ? "methodGate" : "other";
-          const override = {
-            overriddenBy: overrideKind,
-            ...parsed.toolName && { toolName: parsed.toolName },
-            requestedLevel: minAccessLevel,
-            grantedLevel: result.accessLevel
-          };
-          if (sessionId) {
-            recordDecision(config, sessionId, "denied", result.denialReasons?.[0], override).catch(
-              () => {
-              }
-            );
-          } else if (correlationId) {
-            recordAnonymousLocalOverride(
-              config,
-              correlationId,
-              override,
-              result.denialReasons?.[0]
-            ).catch(() => {
-            });
-          }
-        }
-        dedupeFailures(result);
-        onDenied(result, req, res);
-        return;
-      }
       if (effectiveAstraId) {
         res.setHeader(
           MCP_VERIFIED_HOP_HEADER,