@astrasyncai/verification-gateway 3.0.0 → 3.2.0

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-B3USs-Kx.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
@@ -137,7 +137,7 @@ interface McpPdlssMapping {
     action: string;
     resource: string;
     purposeSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | undefined;
-    actionSource: 'header' | 'meta' | 'tool_argument' | 'transport_layer';
+    actionSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | 'transport_layer';
 }
 /**
  * v2.5.0 — PDLSS field derivation for MCP requests.
@@ -149,14 +149,18 @@ interface McpPdlssMapping {
  * Resource precedence:
  *   - `toolGate.resource` if provided, else `requestPath`.
  *
- * Action precedence (unchanged from v2.4.14):
- *   - header → body `_meta` → body `arguments` → bare tool name / method.
+ * Action precedence (3.1.0, Bug 14 §4.6 — toolGate override added for
+ * symmetry with purpose):
+ *   - `toolGate.action` authoritative → header → body `_meta` → body
+ *     `arguments` → bare tool name / method (transport_layer, unchanged —
+ *     bare tool names are legitimate enumerated actions, never aliased).
  *
  * @param requestPath  The HTTP request path (e.g. '/mcp'). Required.
  * @param toolGate     Resolved per-tool config from `toolGates`, if present.
  */
 declare function mcpToPdlss(parsed: ParsedMcpRequest, requestPath: string, headerPurpose?: string, headerAction?: string, toolGate?: {
     purpose?: string;
+    action?: string;
     resource?: string;
 }): McpPdlssMapping;
 /**
@@ -234,18 +238,25 @@ declare global {
     }
 }
 /**
- * Extended per-tool gate with optional PDLSS purpose + resource overrides.
+ * Extended per-tool gate with optional PDLSS purpose + action + resource
+ * overrides.
  *
  * When `purpose` is set, it is authoritative for that tool — the agent's
  * `X-Astra-Purpose` header is ignored. This lets the merchant declare what
  * semantic purpose each tool fulfils rather than trusting agent self-declaration.
  *
+ * When `action` is set (Bug 14, §4.6 — symmetric with `purpose`), it is
+ * authoritative over `X-Astra-Action` / body declarations, letting the
+ * merchant pin a dotted-verb action (e.g. `shopping.search`) for a tool
+ * whose callers would otherwise fall to the bare tool-name transport default.
+ *
  * When `resource` is set, it overrides the default (`req.path`) for that
  * tool's verify-access call — e.g. mapping `list_products` to `/api/catalog`.
  */
 interface ToolGateConfig {
     minAccessLevel: AccessLevel;
     purpose?: string;
+    action?: string;
     resource?: string;
 }
 interface McpMiddlewareOptions extends GatewayConfig {
@@ -253,15 +264,22 @@ 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.search',
+     *   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.purchase',
+     *   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-B3USs-Kx.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
@@ -137,7 +137,7 @@ interface McpPdlssMapping {
     action: string;
     resource: string;
     purposeSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | undefined;
-    actionSource: 'header' | 'meta' | 'tool_argument' | 'transport_layer';
+    actionSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | 'transport_layer';
 }
 /**
  * v2.5.0 — PDLSS field derivation for MCP requests.
@@ -149,14 +149,18 @@ interface McpPdlssMapping {
  * Resource precedence:
  *   - `toolGate.resource` if provided, else `requestPath`.
  *
- * Action precedence (unchanged from v2.4.14):
- *   - header → body `_meta` → body `arguments` → bare tool name / method.
+ * Action precedence (3.1.0, Bug 14 §4.6 — toolGate override added for
+ * symmetry with purpose):
+ *   - `toolGate.action` authoritative → header → body `_meta` → body
+ *     `arguments` → bare tool name / method (transport_layer, unchanged —
+ *     bare tool names are legitimate enumerated actions, never aliased).
  *
  * @param requestPath  The HTTP request path (e.g. '/mcp'). Required.
  * @param toolGate     Resolved per-tool config from `toolGates`, if present.
  */
 declare function mcpToPdlss(parsed: ParsedMcpRequest, requestPath: string, headerPurpose?: string, headerAction?: string, toolGate?: {
     purpose?: string;
+    action?: string;
     resource?: string;
 }): McpPdlssMapping;
 /**
@@ -234,18 +238,25 @@ declare global {
     }
 }
 /**
- * Extended per-tool gate with optional PDLSS purpose + resource overrides.
+ * Extended per-tool gate with optional PDLSS purpose + action + resource
+ * overrides.
  *
  * When `purpose` is set, it is authoritative for that tool — the agent's
  * `X-Astra-Purpose` header is ignored. This lets the merchant declare what
  * semantic purpose each tool fulfils rather than trusting agent self-declaration.
  *
+ * When `action` is set (Bug 14, §4.6 — symmetric with `purpose`), it is
+ * authoritative over `X-Astra-Action` / body declarations, letting the
+ * merchant pin a dotted-verb action (e.g. `shopping.search`) for a tool
+ * whose callers would otherwise fall to the bare tool-name transport default.
+ *
  * When `resource` is set, it overrides the default (`req.path`) for that
  * tool's verify-access call — e.g. mapping `list_products` to `/api/catalog`.
  */
 interface ToolGateConfig {
     minAccessLevel: AccessLevel;
     purpose?: string;
+    action?: string;
     resource?: string;
 }
 interface McpMiddlewareOptions extends GatewayConfig {
@@ -253,15 +264,22 @@ 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.search',
+     *   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.purchase',
+     *   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.0.0";
+var SDK_VERSION = "3.2.0";
 
 // 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,36 +539,7 @@ 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
-      }
-    })
-  }).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
-    })
+    body: JSON.stringify({ decision, reason })
   }).catch(() => {
   });
 }
@@ -677,7 +642,10 @@ function mcpToPdlss(parsed, requestPath, headerPurpose, headerAction, toolGate)
   }
   let action;
   let actionSource;
-  if (headerAction) {
+  if (toolGate?.action !== void 0) {
+    action = toolGate.action;
+    actionSource = "tool_gate";
+  } else if (headerAction) {
     action = headerAction;
     actionSource = "header";
   } else if (parsed.actionFromBody && parsed.actionSourceFromBody) {
@@ -788,7 +756,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;
@@ -825,7 +792,7 @@ function createMcpMiddleware(options) {
           return next();
         }
       }
-      const { level: minAccessLevel, source: gateSource } = resolveMinAccessLevel(parsed, {
+      const { level: minAccessLevel } = resolveMinAccessLevel(parsed, {
         toolGates,
         methodGates
       });
@@ -851,7 +818,7 @@ function createMcpMiddleware(options) {
         req.path,
         headerPurpose,
         headerAction,
-        gate ? { purpose: gate.purpose, resource: gate.resource } : void 0
+        gate ? { purpose: gate.purpose, action: gate.action, resource: gate.resource } : void 0
       );
       if (config.debug) {
         console.debug("[mcp-middleware] pdlss resolved", {
@@ -861,6 +828,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, {
@@ -884,7 +868,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(() => {
@@ -905,48 +888,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,