@astrasyncai/verification-gateway 2.4.4 → 2.4.5

package/dist/adapters/mcp.d.ts

@@ -1,5 +1,5 @@
 import { Request, Response, RequestHandler } from 'express';
-import { a as AccessLevel, G as GatewayConfig, V as VerificationResult } from '../types-CVT-sorC.js';
+import { a as AccessLevel, G as GatewayConfig, V as VerificationResult } from '../types-CbZOkIr-.js';
 
 /**
  * MCP server-side helpers — companion to `transport/mcp.ts` (which handles the
@@ -80,12 +80,27 @@ interface ParsedMcpRequest {
      */
     agentIdFromBody?: string;
     /**
-     * Round-12 (F19): purpose from `params._meta.astrasync.purpose`.
-     * Mirrors the `agentIdFromBody` extraction. The adapter combines this
-     * with the `X-Astra-Purpose` header (header wins) before mapping; falls
-     * back to `'mcp_invoke'` if both are absent.
+     * Round-12 (F19) + round-13 (R13-1): purpose extracted from the MCP body
+     * with the symmetric precedence chain. Sourced from `_meta.astrasync.purpose`
+     * (canonical SDK location) OR `params.arguments.purpose` (legacy /
+     * conventional callers). The discriminator is on `purposeSourceFromBody`.
+     * Adapter combines this with the `X-Astra-Purpose` header (header wins)
+     * before mapping; final fallback at `mcpToPdlss` is `'mcp_invoke'`.
      */
     purposeFromBody?: string;
+    /** Which body location resolved `purposeFromBody`. */
+    purposeSourceFromBody?: 'meta' | 'tool_argument';
+    /**
+     * Round-13 (R13-2): action extracted from the MCP body with the same
+     * symmetric chain as purpose. Sourced from `_meta.astrasync.action`
+     * (canonical) OR `params.arguments.action` (legacy). Adapter combines
+     * with the `X-Astra-Action` header (header wins) before mapping; final
+     * fallback at `mcpToPdlss` is the transport-layer default
+     * (`tools/call:<toolname>` or just `<method>`).
+     */
+    actionFromBody?: string;
+    /** Which body location resolved `actionFromBody`. */
+    actionSourceFromBody?: 'meta' | 'tool_argument';
     /** True for handshake methods that must succeed before any tool call. */
     isInitialize: boolean;
     /** True for `tools/call`. */
@@ -121,23 +136,44 @@ interface McpPdlssMapping {
     action: string;
     resource: string;
     /**
-     * Round-12 (F19): the resolution channel — header / tool-arg / default.
-     * Adapters log this at debug level so partners can confirm header
-     * pass-through, support can triage tickets, and we can watch
-     * `default_mcp_invoke` decay over time.
+     * Round-13 (R13-1 / R13-2): the resolution channel for purpose and
+     * action — disjoint enums sharing the same structure per
+     * `feedback_symmetric_fallbacks_for_symmetric_concepts.md`. Adapters
+     * log both at debug level so partners can confirm header / body
+     * pass-through, support can triage tickets, and we can watch the
+     * `default_*` / `transport_layer` decay over time as integrations
+     * mature.
+     *
+     * Round-12 (F19) used a narrower `purposeSource: 'header' |
+     * 'tool_argument' | 'default_mcp_invoke'` — round-13 widens to also
+     * carry the `_meta` source distinct from `tool_argument`, so the round-13
+     * R13-1 fallback (which now reads both `_meta.astrasync.purpose` AND
+     * `params.arguments.purpose`) can report WHICH body location resolved.
      */
-    purposeSource: 'header' | 'tool_argument' | 'default_mcp_invoke';
+    purposeSource: 'header' | 'meta' | 'tool_argument' | 'default_mcp_invoke';
+    actionSource: 'header' | 'meta' | 'tool_argument' | 'transport_layer';
 }
 /**
- * Round-12 (F19): purpose resolution precedence — header > tool-arg meta >
- * `'mcp_invoke'` default. Pre-fix the purpose was hardcoded to `mcp_invoke`
- * for every MCP call, which forced every MCP-integrated agent's PDLSS to
- * include `mcp_invoke` as an allowed purpose category. Header pass-through
- * lets agents declare business purpose (e.g. `shopping.purchase`) per call.
- * `purposeSource` lets adapters log the resolution channel for adoption
- * tracking + support triage.
+ * Round-13 (R13-1 + R13-2) — canonical precedence chain documented ONCE,
+ * applied identically to both purpose and action. Per
+ * `feedback_symmetric_fallbacks_for_symmetric_concepts.md` — drift
+ * between two paired concepts generates the same support-ticket class
+ * repeatedly, so the resolution order is:
+ *
+ *   1. `X-Astra-<concept>` HTTP header (caller's explicit override)
+ *   2. `params._meta.astrasync.<concept>` body field (canonical SDK location)
+ *   3. `params.arguments.<concept>` body field (legacy / conventional)
+ *   4. Transport-layer default:
+ *        purpose → 'mcp_invoke'
+ *        action  → '<method>:<toolName>' (or just '<method>')
+ *
+ * The header tier is the adapter's job (it has `req.headers` access);
+ * this function takes the resolved `headerPurpose` / `headerAction`
+ * inputs and combines them with the body extraction already done in
+ * `parseMcpJsonRpc`. The discriminator is reported on `purposeSource` /
+ * `actionSource` for debug logging.
  */
-declare function mcpToPdlss(parsed: ParsedMcpRequest, headerPurpose?: string, toolArgumentPurpose?: string): McpPdlssMapping;
+declare function mcpToPdlss(parsed: ParsedMcpRequest, headerPurpose?: string, headerAction?: string): McpPdlssMapping;
 /**
  * Recommended minimum access level per method type. The MCP middleware uses
  * this to split low-risk handshake / introspection traffic from high-risk

package/dist/adapters/mcp.js

@@ -50,6 +50,9 @@ function hasMinimumAccess(actual, required) {
   return ACCESS_LEVEL_HIERARCHY[actual] >= ACCESS_LEVEL_HIERARCHY[required];
 }
 
+// src/version.ts
+var SDK_VERSION = "2.4.5";
+
 // src/verify.ts
 var DEFAULT_CONFIG = {
   apiBaseUrl: "https://astrasync.ai/api",
@@ -208,6 +211,7 @@ async function callVerifyAccessAPI(config, request) {
   if (requestData.runtimeChallengeOptions)
     body.runtimeChallengeOptions = requestData.runtimeChallengeOptions;
   if (requestData.invocationProtocol) body.invocationProtocol = requestData.invocationProtocol;
+  body.sdkVersion = SDK_VERSION;
   if (requestData.callerMetadata || requestData.clientIp || requestData.userAgent) {
     const meta = {
       ...requestData.clientIp && { sourceIp: requestData.clientIp },
@@ -491,16 +495,17 @@ function parseMcpJsonRpc(body) {
   if (method === "initialize" && params && typeof params.protocolVersion === "string") {
     protocolVersion = params.protocolVersion;
   }
-  let agentIdFromBody;
   const meta = params?._meta;
   const astrasyncMeta = meta?.astrasync;
+  const args = params?.arguments;
+  let agentIdFromBody;
   if (astrasyncMeta && typeof astrasyncMeta.agentId === "string") {
     agentIdFromBody = astrasyncMeta.agentId;
-  } else {
-    const args = params?.arguments;
-    if (args && typeof args.agent_id === "string") agentIdFromBody = args.agent_id;
+  } else if (args && typeof args.agent_id === "string") {
+    agentIdFromBody = args.agent_id;
   }
-  const purposeFromBody = astrasyncMeta && typeof astrasyncMeta.purpose === "string" ? astrasyncMeta.purpose : void 0;
+  const purposeBodyResult = extractFromMcpBody(astrasyncMeta, args, "purpose");
+  const actionBodyResult = extractFromMcpBody(astrasyncMeta, args, "action");
   const isInitialize = method === "initialize";
   const isToolCall = method === "tools/call";
   const isIntrospection = method === "tools/list" || method === "prompts/list" || method === "resources/list" || method === "ping" || method === "notifications/initialized";
@@ -509,22 +514,51 @@ function parseMcpJsonRpc(body) {
     ...toolName ? { toolName } : {},
     ...protocolVersion ? { protocolVersion } : {},
     ...agentIdFromBody ? { agentIdFromBody } : {},
-    ...purposeFromBody ? { purposeFromBody } : {},
+    ...purposeBodyResult.value ? { purposeFromBody: purposeBodyResult.value } : {},
+    ...purposeBodyResult.source ? { purposeSourceFromBody: purposeBodyResult.source } : {},
+    ...actionBodyResult.value ? { actionFromBody: actionBodyResult.value } : {},
+    ...actionBodyResult.source ? { actionSourceFromBody: actionBodyResult.source } : {},
     isInitialize,
     isToolCall,
     isIntrospection
   };
 }
-function mcpToPdlss(parsed, headerPurpose, toolArgumentPurpose) {
-  const action = parsed.toolName ? `${parsed.method}:${parsed.toolName}` : parsed.method;
+function extractFromMcpBody(astrasyncMeta, args, key) {
+  if (astrasyncMeta && typeof astrasyncMeta[key] === "string") {
+    return { value: astrasyncMeta[key], source: "meta" };
+  }
+  if (args && typeof args[key] === "string") {
+    return { value: args[key], source: "tool_argument" };
+  }
+  return { value: void 0, source: void 0 };
+}
+function mcpToPdlss(parsed, headerPurpose, headerAction) {
   const resource = parsed.toolName ? `mcp:tool/${parsed.toolName}` : `mcp:method/${parsed.method}`;
+  let purpose;
+  let purposeSource;
   if (headerPurpose) {
-    return { purpose: headerPurpose, action, resource, purposeSource: "header" };
+    purpose = headerPurpose;
+    purposeSource = "header";
+  } else if (parsed.purposeFromBody && parsed.purposeSourceFromBody) {
+    purpose = parsed.purposeFromBody;
+    purposeSource = parsed.purposeSourceFromBody;
+  } else {
+    purpose = "mcp_invoke";
+    purposeSource = "default_mcp_invoke";
   }
-  if (toolArgumentPurpose) {
-    return { purpose: toolArgumentPurpose, action, resource, purposeSource: "tool_argument" };
+  let action;
+  let actionSource;
+  if (headerAction) {
+    action = headerAction;
+    actionSource = "header";
+  } else if (parsed.actionFromBody && parsed.actionSourceFromBody) {
+    action = parsed.actionFromBody;
+    actionSource = parsed.actionSourceFromBody;
+  } else {
+    action = parsed.toolName ? `${parsed.method}:${parsed.toolName}` : parsed.method;
+    actionSource = "transport_layer";
   }
-  return { purpose: "mcp_invoke", action, resource, purposeSource: "default_mcp_invoke" };
+  return { purpose, action, resource, purposeSource, actionSource };
 }
 function mcpRiskTier(parsed) {
   if (parsed.isInitialize || parsed.method === "notifications/initialized") return "none";
@@ -535,6 +569,11 @@ function mcpRiskTier(parsed) {
 }
 
 // src/adapters/mcp.ts
+function readSingleHeader(value) {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return value[0];
+  return void 0;
+}
 function defaultMcpDenied(result, req, res) {
   const id = req.body?.id ?? null;
   const status = result.verified ? 403 : 401;
@@ -629,25 +668,28 @@ function createMcpMiddleware(options) {
         toolGates,
         methodGates
       });
-      if (minAccessLevel === "none") {
+      const credentials = extractCredentials(
+        req.headers,
+        req.query
+      );
+      if (effectiveAstraId) credentials.astraId = effectiveAstraId;
+      const shouldEnforce = minAccessLevel !== "none";
+      if (minAccessLevel === "none" && (!config.evaluateAlwaysIfCredentialed || !credentials.astraId)) {
         if (config.setPassThroughHeader) {
           res.setHeader("X-Astra-Gateway-Mode", "unenforced");
           res.setHeader("X-Astra-Gateway-Reason", "mcp-tier-none");
         }
         return next();
       }
-      const credentials = extractCredentials(
-        req.headers,
-        req.query
-      );
-      if (effectiveAstraId) credentials.astraId = effectiveAstraId;
-      const headerPurposeRaw = req.headers["x-astra-purpose"];
-      const headerPurpose = typeof headerPurposeRaw === "string" ? headerPurposeRaw : Array.isArray(headerPurposeRaw) ? headerPurposeRaw[0] : void 0;
-      const pdlss = mcpToPdlss(parsed, headerPurpose, parsed.purposeFromBody);
+      const headerPurpose = readSingleHeader(req.headers["x-astra-purpose"]);
+      const headerAction = readSingleHeader(req.headers["x-astra-action"]);
+      const pdlss = mcpToPdlss(parsed, headerPurpose, headerAction);
       if (config.debug) {
-        console.debug("[mcp-middleware] purpose resolved", {
+        console.debug("[mcp-middleware] pdlss resolved", {
           purpose_source: pdlss.purposeSource,
-          resolved_purpose: pdlss.purpose
+          resolved_purpose: pdlss.purpose,
+          action_source: pdlss.actionSource,
+          resolved_action: pdlss.action
         });
       }
       const counterpartyUrl = config.counterpartyUrl || `${req.protocol}://${req.get("host")}${req.path}`;
@@ -682,6 +724,17 @@ function createMcpMiddleware(options) {
         onDenied(result, req, res);
         return;
       }
+      if (!shouldEnforce) {
+        if (config.setPassThroughHeader) {
+          res.setHeader("X-Astra-Gateway-Mode", "enforced");
+          res.setHeader("X-Astra-Gateway-Reason", "evaluated-not-enforced");
+        }
+        if (shouldRecordDecisions && sessionId) {
+          recordDecision(config, sessionId, "granted").catch(() => {
+          });
+        }
+        return next();
+      }
       if (!hasMinimumAccess(result.accessLevel, minAccessLevel)) {
         const insufficientFailure = {
           dimension: "access_level.insufficient",