@astrasyncai/verification-gateway 2.4.12 → 2.4.14

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-L15pYd2c.js';
+import { A as AccessLevel, G as GatewayConfig, i as VerificationResult } from '../types-B3USs-Kx.js';
 
 /**
  * MCP server-side helpers — companion to `transport/mcp.ts` (which handles the
@@ -280,9 +280,22 @@ interface McpMiddlewareOptions extends GatewayConfig {
     /** Custom denied handler. Defaults to a structured JSON-RPC error response. */
     onDenied?: (result: VerificationResult, req: Request, res: Response) => void;
     /**
-     * If `false`, don't trust an inbound `X-Astra-Verified-Hop` header (always
-     * call verify-access). Default `true` — recommended for inner-hop endpoints
-     * called by your own MCP tools.
+     * If `true`, trust an inbound `X-Astra-Verified-Hop` header to skip
+     * verify-access when it carries a recent marker for the resolved agent.
+     *
+     * **DEFAULT FLIPPED TO `false` in SDK 2.4.13** (audit F-A1-01). The marker
+     * is plaintext semicolon-delimited with no HMAC, so any client that sets
+     * the header (with the right format + fresh timestamp + matching ASTRA-id)
+     * skipped verify-access entirely. The per-process verify-access result
+     * cache already dedupes legitimate repeat calls — this optimization
+     * provided no additional savings, only a bypass surface.
+     *
+     * Set this to `true` ONLY if you control every upstream MCP hop that sets
+     * the header AND you trust the network path between hops (mTLS, internal
+     * VPC, etc.). For most installs, leave at the safe default.
+     *
+     * Future SDK release will either remove this option entirely OR add HMAC
+     * signing to the marker. Tracked as round-19+ work.
      */
     trustVerifiedHop?: boolean;
     /** Window for accepting an upstream verified-hop marker. Default 60_000ms. */
@@ -294,6 +307,15 @@ interface McpMiddlewareOptions extends GatewayConfig {
     recordDecisions?: boolean;
     /** Forward runtime challenge (default `true`). */
     enableRuntimeChallenge?: boolean;
+    /**
+     * Posture when the MCP middleware itself throws an internal error.
+     * Default `'open'` for backward compatibility in SDK 2.4.13. Shadow logs
+     * record what WOULD be denied with `failOnError: 'closed'` so merchants
+     * can grep correlationId for impact analysis during the 1-week
+     * observation window. Default flips to `'closed'` in a follow-up release.
+     * Audit F-A1-06.
+     */
+    failOnError?: 'open' | 'closed';
 }
 /**
  * Create the MCP middleware. Attach AFTER `express.json()` — the body must

package/dist/adapters/mcp.js

@@ -51,7 +51,7 @@ function hasMinimumAccess(actual, required) {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.4.12";
+var SDK_VERSION = "2.4.13";
 
 // src/verify.ts
 var DEFAULT_CONFIG = {
@@ -70,22 +70,27 @@ var DEFAULT_CONFIG = {
 };
 var initCheckPerformed = false;
 var deprecationWarningShown = false;
-async function performInitCheck(apiBaseUrl, debug) {
+async function performInitCheck(apiBaseUrl, debug, strictInit) {
   initCheckPerformed = true;
   try {
     const probeUrl = `${apiBaseUrl}/agents/verify-access`;
     const response = await fetch(probeUrl, { method: "HEAD" });
     const contentType = response.headers.get("content-type") ?? "";
     if (contentType.startsWith("text/html")) {
-      console.warn(
-        `[VerificationGateway] apiBaseUrl '${apiBaseUrl}' returned HTML (content-type: ${contentType}). This usually means apiBaseUrl is pointing at a marketing site instead of the API. Expected: 'https://astrasync.ai/api' (prod) or 'https://staging.astrasync.ai/api' (staging). Set disableInitChecks: true on GatewayConfig to silence this warning.`
-      );
+      const message = `[VerificationGateway] apiBaseUrl '${apiBaseUrl}' returned HTML (content-type: ${contentType}). This usually means apiBaseUrl is pointing at a marketing site instead of the API. Expected: 'https://astrasync.ai/api' (prod) or 'https://staging.astrasync.ai/api' (staging).`;
+      if (strictInit) {
+        throw new Error(`${message} (strictInit=true)`);
+      }
+      console.warn(`${message} Set disableInitChecks: true on GatewayConfig to silence.`);
     } else if (debug) {
       console.log(
         `[VerificationGateway] init check passed for ${apiBaseUrl} (content-type: ${contentType})`
       );
     }
   } catch (err) {
+    if (strictInit) {
+      throw err;
+    }
     if (debug) {
       console.log(`[VerificationGateway] init check failed (non-blocking): ${String(err)}`);
     }
@@ -109,7 +114,23 @@ function getCacheKey(request) {
     request.counterpartyType || "",
     request.isSubAgentRequest ? "1" : "0",
     request.parentAgentId || "",
-    request.subAgentDepth ?? ""
+    request.subAgentDepth ?? "",
+    // Audit F-A1-07: previously-missing dimensions that DO affect the
+    // backend verdict. Without these, two requests with different
+    // durations (e.g. 60s vs 86400s) collided on the same cache key and
+    // the shorter-duration allow served the longer-duration request.
+    request.durationRequired ?? "",
+    request.invocationProtocol || "",
+    request.enableRuntimeChallenge ? "1" : "0",
+    // callerMetadata fields contribute to risk model; include the ones
+    // backend reads. sourceIp/userAgent/forwardedFor change per-request
+    // so their inclusion effectively forces a re-check for any varying
+    // client (the right behavior — IP-driven anomaly scoring shouldn't
+    // be cached across IPs).
+    request.callerMetadata?.sourceIp || "",
+    request.callerMetadata?.userAgent || "",
+    request.callerMetadata?.forwardedFor || "",
+    request.callerMetadata?.agentCardUrl || ""
   ].join("|");
 }
 function getCachedResult(request) {
@@ -135,9 +156,13 @@ function cacheResult(request, result, configuredTtl) {
 }
 function extractCredentials(headers, query) {
   const credentials = {};
+  const ASTRA_ID_PATTERN = /^ASTRAE?-[A-Za-z0-9_-]{1,64}$/;
   const astraIdHeader = headers["x-astra-id"] || headers["X-Astra-Id"] || headers["X-ASTRA-ID"] || headers["x-astra-agentid"] || headers["X-Astra-AgentId"] || headers["x-astra-agent-id"] || headers["X-Astra-Agent-Id"] || headers["X-ASTRA-AGENT-ID"];
   if (astraIdHeader) {
-    credentials.astraId = Array.isArray(astraIdHeader) ? astraIdHeader[0] : astraIdHeader;
+    const raw = Array.isArray(astraIdHeader) ? astraIdHeader[0] : typeof astraIdHeader === "string" ? astraIdHeader : void 0;
+    if (typeof raw === "string" && ASTRA_ID_PATTERN.test(raw)) {
+      credentials.astraId = raw;
+    }
   }
   const apiKeyHeader = headers["x-api-key"] || headers["X-Api-Key"] || headers["X-API-KEY"];
   if (apiKeyHeader) {
@@ -146,9 +171,11 @@ function extractCredentials(headers, query) {
   const authHeader = headers["authorization"] || headers["Authorization"];
   if (authHeader) {
     const authValue = Array.isArray(authHeader) ? authHeader[0] : authHeader;
-    credentials.authorizationHeader = authValue;
-    if (authValue.startsWith("Bearer ")) {
-      credentials.jwt = authValue.slice(7);
+    if (typeof authValue === "string") {
+      credentials.authorizationHeader = authValue;
+      if (authValue.startsWith("Bearer ")) {
+        credentials.jwt = authValue.slice(7);
+      }
     }
   }
   if (query) {
@@ -166,7 +193,7 @@ function createGuidanceResponse(config, reason, options = {}) {
   const isApiError = source === "api_error";
   const guidance = isApiError ? {
     message: "Verification is temporarily unavailable. Retry with exponential backoff; if the issue persists, contact support with the correlationId.",
-    registrationUrl: `${config.apiBaseUrl.replace("/api", "")}/register`,
+    registrationUrl: `${config.apiBaseUrl.replace("/api", "")}/agents/register`,
     documentationUrl: `${config.apiBaseUrl.replace("/api", "")}/docs/agent-access`,
     steps: [
       "Retry the request with exponential backoff",
@@ -174,7 +201,7 @@ function createGuidanceResponse(config, reason, options = {}) {
     ]
   } : {
     message: "This service verifies AI agents before granting access. Please register your agent with AstraSync.",
-    registrationUrl: `${config.apiBaseUrl.replace("/api", "")}/register`,
+    registrationUrl: `${config.apiBaseUrl.replace("/api", "")}/agents/register`,
     documentationUrl: `${config.apiBaseUrl.replace("/api", "")}/docs/agent-access`,
     steps: [
       "Register for an AstraSync account",
@@ -251,12 +278,8 @@ async function callVerifyAccessAPI(config, request) {
     "Content-Type": "application/json",
     ...config.customHeaders
   };
-  if (credentials.authorizationHeader) {
-    headers["Authorization"] = credentials.authorizationHeader;
-  } else if (config.apiKey) {
-    headers["Authorization"] = `Bearer ${config.apiKey}`;
-  }
   if (config.apiKey) {
+    headers["Authorization"] = `Bearer ${config.apiKey}`;
     headers["X-API-Key"] = config.apiKey;
   }
   try {
@@ -302,7 +325,11 @@ async function callVerifyAccessAPI(config, request) {
 async function verify(config, request) {
   const mergedConfig = { ...DEFAULT_CONFIG, ...config };
   if (!initCheckPerformed && !mergedConfig.disableInitChecks && mergedConfig.apiBaseUrl) {
-    void performInitCheck(mergedConfig.apiBaseUrl, mergedConfig.debug);
+    if (mergedConfig.strictInit) {
+      await performInitCheck(mergedConfig.apiBaseUrl, mergedConfig.debug, true);
+    } else {
+      void performInitCheck(mergedConfig.apiBaseUrl, mergedConfig.debug, false);
+    }
   }
   if (!deprecationWarningShown && (config.minTrustScore !== void 0 || config.minTrustScoreForFull !== void 0)) {
     deprecationWarningShown = true;
@@ -356,7 +383,7 @@ async function verify(config, request) {
       requiresApproval: apiResponse.access?.requiresApproval,
       guidance: {
         message: apiResponse.access?.reason || "Access denied by PDLSS policy",
-        registrationUrl: `${mergedConfig.apiBaseUrl?.replace("/api", "")}/register`,
+        registrationUrl: `${mergedConfig.apiBaseUrl?.replace("/api", "")}/agents/register`,
         documentationUrl: `${mergedConfig.apiBaseUrl?.replace("/api", "")}/docs/pdlss`
       },
       verifiedAt: /* @__PURE__ */ new Date(),
@@ -426,13 +453,15 @@ async function verify(config, request) {
     result.denialReasons = result.recommendationReasons || [
       "Access denied by AstraSync recommendation"
     ];
-    if (result.runtimeChallenge) {
-      result.guidance = {
-        message: `Verification failed: ${result.runtimeChallenge.reason || "runtime challenge failed"}`,
-        registrationUrl: `${mergedConfig.apiBaseUrl?.replace("/api", "")}/register`,
-        documentationUrl: `${mergedConfig.apiBaseUrl?.replace("/api", "")}/docs/runtime-challenge`
-      };
-    }
+    result.guidance = result.runtimeChallenge ? {
+      message: `Verification failed: ${result.runtimeChallenge.reason || "runtime challenge failed"}`,
+      registrationUrl: `${mergedConfig.apiBaseUrl?.replace("/api", "")}/agents/register`,
+      documentationUrl: `${mergedConfig.apiBaseUrl?.replace("/api", "")}/docs/runtime-challenge`
+    } : {
+      message: result.recommendationReasons?.[0] || "Access denied by AstraSync recommendation",
+      registrationUrl: `${mergedConfig.apiBaseUrl?.replace("/api", "")}/agents/register`,
+      documentationUrl: `${mergedConfig.apiBaseUrl?.replace("/api", "")}/docs/pdlss`
+    };
   } else if (result.recommendation === "step_up_required") {
     result.requiresStepUp = true;
     if (ACCESS_LEVEL_HIERARCHY[result.accessLevel] > ACCESS_LEVEL_HIERARCHY["read-only"]) {
@@ -590,7 +619,7 @@ function mcpToPdlss(parsed, headerPurpose, headerAction) {
     action = parsed.actionFromBody;
     actionSource = parsed.actionSourceFromBody;
   } else {
-    action = parsed.toolName ? `${parsed.method}:${parsed.toolName}` : parsed.method;
+    action = parsed.toolName ? parsed.method === "tools/call" ? parsed.toolName : `${parsed.method}:${parsed.toolName}` : parsed.method;
     actionSource = "transport_layer";
   }
   return { purpose, action, resource, purposeSource, actionSource };
@@ -609,6 +638,17 @@ function readSingleHeader(value) {
   if (Array.isArray(value)) return value[0];
   return void 0;
 }
+function dedupeFailures(result) {
+  if (result.failures && result.failures.length > 1) {
+    const seen = /* @__PURE__ */ new Set();
+    result.failures = result.failures.filter((f) => {
+      const key = `${f.dimension}|${f.message}|${f.guidance ?? ""}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  }
+}
 function defaultMcpDenied(result, req, res) {
   const id = req.body?.id ?? null;
   const status = !result.identityVerified ? 401 : 403;
@@ -648,10 +688,11 @@ function createMcpMiddleware(options) {
     onAgentIdMismatch = "reject",
     skip = false,
     onDenied = defaultMcpDenied,
-    trustVerifiedHop = true,
+    trustVerifiedHop = false,
     verifiedHopMaxAgeMs,
     recordDecisions,
     enableRuntimeChallenge = true,
+    failOnError = "open",
     ...config
   } = options;
   return async (req, res, next) => {
@@ -759,6 +800,7 @@ function createMcpMiddleware(options) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
           });
         }
+        dedupeFailures(result);
         onDenied(result, req, res);
         return;
       }
@@ -804,6 +846,7 @@ function createMcpMiddleware(options) {
             });
           }
         }
+        dedupeFailures(result);
         onDenied(result, req, res);
         return;
       }
@@ -827,7 +870,30 @@ function createMcpMiddleware(options) {
       }
       next();
     } catch (error) {
+      const errorClass = error instanceof Error ? error.constructor.name : typeof error;
+      const correlationId = req.headers["x-request-id"] || req.headers["x-correlation-id"] || `gen-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
       console.error("[VerificationGateway/MCP] Middleware error:", error);
+      console.warn(
+        `[SHADOW] would-have-denied: errorClass=${errorClass} route=${req.method}:${req.path} merchantId=${config.counterpartyId ?? "unknown"} correlationId=${correlationId}`
+      );
+      if (failOnError === "closed") {
+        const result = {
+          identityVerified: false,
+          policyAllowed: false,
+          accessLevel: "none",
+          denialReasons: [`MCP middleware internal error: ${errorClass}`],
+          failures: [
+            {
+              dimension: "middleware.internal_error",
+              message: `Middleware threw ${errorClass} \u2014 failing closed`
+            }
+          ],
+          verifiedAt: /* @__PURE__ */ new Date(),
+          correlationId
+        };
+        dedupeFailures(result);
+        return onDenied(result, req, res);
+      }
       next();
     }
   };