@astrasyncai/verification-gateway 2.4.12 → 2.5.0

package/dist/index.js

@@ -53,11 +53,14 @@ __export(src_exports, {
   extractCredentials: () => extractCredentials,
   extractMcpCredentials: () => extractMcpCredentials,
   getAccessLevelForScore: () => getAccessLevelForScore,
+  getCachedWellKnownUrls: () => getCachedWellKnownUrls,
   getCapabilities: () => getCapabilities,
   getTrustLevel: () => getTrustLevel,
+  getWellKnownUrls: () => getWellKnownUrls,
   hasCredentials: () => hasCredentials,
   hasMinimumAccess: () => hasMinimumAccess,
   nextjs: () => nextjs_exports,
+  prefetchWellKnown: () => prefetchWellKnown,
   quickVerify: () => quickVerify,
   recordDecision: () => recordDecision2,
   sdk: () => sdk_exports,
@@ -189,7 +192,66 @@ function getCapabilities(accessLevel) {
 }
 
 // src/version.ts
-var SDK_VERSION = "2.4.12";
+var SDK_VERSION = "2.4.13";
+
+// src/well-known.ts
+var CACHE_TTL_MS = 60 * 60 * 1e3;
+var cache = /* @__PURE__ */ new Map();
+var inflight = /* @__PURE__ */ new Map();
+function wellKnownUrl(apiBaseUrl) {
+  const base = apiBaseUrl.replace(/\/api\/?$/, "");
+  return `${base}/.well-known/agentic-commerce`;
+}
+async function fetchWellKnown(apiBaseUrl) {
+  const url = wellKnownUrl(apiBaseUrl);
+  const response = await fetch(url, {
+    method: "GET",
+    headers: { Accept: "application/json" },
+    signal: AbortSignal.timeout(5e3)
+  });
+  if (!response.ok) {
+    throw new Error(
+      `AstraSync platform must expose /.well-known/agentic-commerce; got ${response.status} from ${url}. SDK cannot initialise without it.`
+    );
+  }
+  const data = await response.json();
+  if (!data.registrationUrl || !data.documentationUrl || !data.verifyAccessUrl) {
+    throw new Error(
+      `/.well-known/agentic-commerce response missing required fields (registrationUrl, documentationUrl, verifyAccessUrl).`
+    );
+  }
+  return data;
+}
+function prefetchWellKnown(apiBaseUrl) {
+  const existing = inflight.get(apiBaseUrl);
+  if (existing) return existing;
+  const promise = fetchWellKnown(apiBaseUrl).then((data) => {
+    cache.set(apiBaseUrl, { data, fetchedAt: Date.now() });
+    inflight.delete(apiBaseUrl);
+    return data;
+  }).catch((err) => {
+    inflight.delete(apiBaseUrl);
+    throw err;
+  });
+  inflight.set(apiBaseUrl, promise);
+  return promise;
+}
+async function getWellKnownUrls(apiBaseUrl) {
+  const entry = cache.get(apiBaseUrl);
+  if (entry) {
+    if (Date.now() - entry.fetchedAt > CACHE_TTL_MS) {
+      prefetchWellKnown(apiBaseUrl).catch(() => {
+      });
+    }
+    return entry.data;
+  }
+  const pending = inflight.get(apiBaseUrl);
+  if (pending) return pending;
+  return prefetchWellKnown(apiBaseUrl);
+}
+function getCachedWellKnownUrls(apiBaseUrl) {
+  return cache.get(apiBaseUrl)?.data;
+}
 
 // src/verify.ts
 var DEFAULT_CONFIG = {
@@ -208,22 +270,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)}`);
     }
@@ -247,7 +314,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) {
@@ -276,9 +359,13 @@ function clearCache() {
 }
 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) {
@@ -287,9 +374,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) {
@@ -305,21 +394,22 @@ function extractCredentials(headers, query) {
 function hasCredentials(credentials) {
   return !!(credentials.astraId || credentials.apiKey || credentials.jwt);
 }
-function createGuidanceResponse(config, reason, options = {}) {
+function createGuidanceResponse(_config, reason, options = {}) {
   const source = options.source ?? "no_credentials";
   const isApiError = source === "api_error";
+  const urls = options.urls;
   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`,
-    documentationUrl: `${config.apiBaseUrl.replace("/api", "")}/docs/agent-access`,
+    registrationUrl: urls?.registrationUrl ?? "",
+    documentationUrl: urls?.documentationUrl ?? "",
     steps: [
       "Retry the request with exponential backoff",
       "If failures persist, share the correlationId with support"
     ]
   } : {
     message: "This service verifies AI agents before granting access. Please register your agent with AstraSync.",
-    registrationUrl: `${config.apiBaseUrl.replace("/api", "")}/register`,
-    documentationUrl: `${config.apiBaseUrl.replace("/api", "")}/docs/agent-access`,
+    registrationUrl: urls?.registrationUrl ?? "",
+    documentationUrl: urls?.documentationUrl ?? "",
     steps: [
       "Register for an AstraSync account",
       "Create and register your agent",
@@ -361,7 +451,7 @@ async function callVerifyAccessAPI(config, request) {
   const { credentials, ...requestData } = request;
   const body = {
     ...credentials.astraId && { agentId: credentials.astraId },
-    purpose: requestData.purpose || "general"
+    ...requestData.purpose && { purpose: requestData.purpose }
   };
   if (requestData.action) body.action = requestData.action;
   if (requestData.resourceType) body.resourceType = requestData.resourceType;
@@ -395,12 +485,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 {
@@ -445,8 +531,13 @@ async function callVerifyAccessAPI(config, request) {
 }
 async function verify(config, request) {
   const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+  const urls = mergedConfig.apiBaseUrl ? getCachedWellKnownUrls(mergedConfig.apiBaseUrl) : void 0;
   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;
@@ -477,7 +568,8 @@ async function verify(config, request) {
   if (!apiResponse.success) {
     return createGuidanceResponse(mergedConfig, apiResponse.error, {
       source: "api_error",
-      correlationId: apiResponse.correlationId
+      correlationId: apiResponse.correlationId,
+      urls
     });
   }
   if (!apiResponse.access?.allowed) {
@@ -500,8 +592,8 @@ 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`,
-        documentationUrl: `${mergedConfig.apiBaseUrl?.replace("/api", "")}/docs/pdlss`
+        registrationUrl: urls?.registrationUrl ?? "",
+        documentationUrl: urls?.documentationUrl ?? ""
       },
       verifiedAt: /* @__PURE__ */ new Date(),
       // Extract sessionId so decisions can be recorded for denials too
@@ -570,13 +662,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: urls?.registrationUrl ?? "",
+      documentationUrl: urls?.documentationUrl ?? ""
+    } : {
+      message: result.recommendationReasons?.[0] || "Access denied by AstraSync recommendation",
+      registrationUrl: urls?.registrationUrl ?? "",
+      documentationUrl: urls?.documentationUrl ?? ""
+    };
   } else if (result.recommendation === "step_up_required") {
     result.requiresStepUp = true;
     if (ACCESS_LEVEL_HIERARCHY[result.accessLevel] > ACCESS_LEVEL_HIERARCHY["read-only"]) {
@@ -825,18 +919,43 @@ function defaultExtractPurpose(req) {
       return "general";
   }
 }
-function matchRoute(pattern, path) {
+function matchRoute(pattern, path, opts) {
   const regexPattern = pattern.replace(/\*/g, ".*").replace(/\//g, "\\/");
-  const regex = new RegExp(`^${regexPattern}$`);
-  return regex.test(path);
+  const caseSensitiveRegex = new RegExp(`^${regexPattern}$`);
+  const caseSensitiveResult = caseSensitiveRegex.test(path);
+  if (!opts?.caseInsensitive && !opts?.logShadowDivergence) {
+    return caseSensitiveResult;
+  }
+  const caseInsensitiveRegex = new RegExp(`^${regexPattern}$`, "i");
+  const caseInsensitiveResult = caseInsensitiveRegex.test(path);
+  if (opts?.logShadowDivergence && caseSensitiveResult !== caseInsensitiveResult) {
+    console.warn(
+      `[SHADOW] matchRoute case-insensitive would change result: pattern=${pattern} path=${path} caseSensitive=${caseSensitiveResult} caseInsensitive=${caseInsensitiveResult} correlationId=${opts.correlationId ?? "unknown"}`
+    );
+  }
+  return opts?.caseInsensitive ? caseInsensitiveResult : caseSensitiveResult;
 }
-function findRouteConfig(routes, path, method) {
+function findRouteConfig(routes, path, method, opts) {
   return routes.find((route) => {
     const methodMatches = route.method === "*" || route.method.toUpperCase() === method.toUpperCase();
-    const pathMatches = matchRoute(route.pattern, path);
+    const pathMatches = matchRoute(route.pattern, path, opts);
     return methodMatches && pathMatches;
   });
 }
+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;
+    });
+  }
+  if (result.denialReasons && result.denialReasons.length > 1) {
+    result.denialReasons = [...new Set(result.denialReasons)];
+  }
+}
 function defaultOnDenied(result, _req, res) {
   const statusCode = !result.identityVerified ? 401 : 403;
   res.setHeader("X-Astra-Gateway-Mode", "enforced");
@@ -863,8 +982,14 @@ function createMiddleware(options) {
     recordDecisions,
     enableRuntimeChallenge = true,
     routesRefreshMs = DEFAULT_ROUTES_REFRESH_MS,
+    failOnError = "open",
+    caseInsensitiveRouteMatch = false,
     ...config
   } = options;
+  if (config.apiBaseUrl) {
+    prefetchWellKnown(config.apiBaseUrl).catch(() => {
+    });
+  }
   let cachedRoutes = [];
   let lastFetchAt = 0;
   let refreshing = null;
@@ -885,7 +1010,7 @@ function createMiddleware(options) {
       cachedRoutes = fetched;
       lastFetchAt = Date.now();
       if (cachedRoutes.length === 0 && !warnedEmptyRoutes) {
-        const dashboard = config.dashboardUrl ?? "https://app.astrasync.ai";
+        const dashboard = config.dashboardUrl ?? "https://astrasync.ai/dashboard";
         console.warn(
           `[VerificationGateway] No route policy configured for ${config.counterpartyId}. Gateway is in pass-through mode for ALL traffic until you add at least one route. Configure at ${dashboard}/dashboard/endpoints/${config.counterpartyId}/routes`
         );
@@ -911,7 +1036,12 @@ function createMiddleware(options) {
           refreshing = null;
         });
       }
-      const routeConfig = findRouteConfig(cachedRoutes, req.path, req.method);
+      const correlationId = req.headers["x-request-id"] || req.headers["x-correlation-id"];
+      const routeConfig = findRouteConfig(cachedRoutes, req.path, req.method, {
+        caseInsensitive: caseInsensitiveRouteMatch,
+        logShadowDivergence: true,
+        correlationId
+      });
       if (!routeConfig) {
         if (config.setPassThroughHeader) {
           res.setHeader("X-Astra-Gateway-Mode", "unenforced");
@@ -922,6 +1052,7 @@ function createMiddleware(options) {
         }
         return next();
       }
+      const wellKnownUrls = config.apiBaseUrl ? await getWellKnownUrls(config.apiBaseUrl).catch(() => void 0) : void 0;
       const credentials = customExtractCredentials ? customExtractCredentials(req) : defaultExtractCredentials(req);
       const shouldEnforce = routeConfig.minAccessLevel !== "none";
       if (routeConfig.minAccessLevel === "none" && (!config.evaluateAlwaysIfCredentialed || !credentials.astraId)) {
@@ -943,8 +1074,8 @@ function createMiddleware(options) {
           denialReasons: preCheckFailures.map((f) => f.message),
           guidance: {
             message: "Request exceeds counterparty-defined PDLSS limits.",
-            registrationUrl: `${config.apiBaseUrl?.replace("/api", "")}/register`,
-            documentationUrl: `${config.apiBaseUrl?.replace("/api", "")}/docs/pdlss`
+            registrationUrl: wellKnownUrls?.registrationUrl ?? "",
+            documentationUrl: wellKnownUrls?.documentationUrl ?? ""
           },
           verifiedAt: /* @__PURE__ */ new Date()
         };
@@ -958,13 +1089,19 @@ function createMiddleware(options) {
           requestMethod: req.method
         }).catch(() => {
         });
+        dedupeFailures(result2);
         onDenied(result2, req, res);
         return;
       }
       const shouldRecordDecisions = recordDecisions !== false;
       const forwardedFor = req.headers["x-forwarded-for"];
       const forwardedForStr = Array.isArray(forwardedFor) ? forwardedFor.join(", ") : forwardedFor;
-      const originalClientIp = forwardedForStr ? forwardedForStr.split(",")[0].trim() : req.ip;
+      const originalClientIp = req.ip ?? (forwardedForStr ? forwardedForStr.split(",")[0].trim() : void 0);
+      if (!req.ip && forwardedForStr) {
+        console.warn(
+          "[VerificationGateway] req.ip unset \u2014 falling back to leftmost X-Forwarded-For. Configure Express trust proxy correctly to avoid spoofable client IPs in audit logs."
+        );
+      }
       const agentCardUrl = typeof req.headers["x-astrasync-agent-card"] === "string" ? req.headers["x-astrasync-agent-card"] : void 0;
       const result = await verify(config, {
         credentials,
@@ -995,6 +1132,7 @@ function createMiddleware(options) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
           });
         }
+        dedupeFailures(result);
         onDenied(result, req, res);
         return;
       }
@@ -1017,10 +1155,18 @@ function createMiddleware(options) {
         };
         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 && sessionId) {
           recordDecision(config, sessionId, "denied", insufficientFailure.message).catch(() => {
           });
         }
+        dedupeFailures(result);
         onDenied(result, req, res);
         return;
       }
@@ -1033,10 +1179,18 @@ function createMiddleware(options) {
           };
           result.failures = [...result.failures ?? [], trustFailure];
           result.denialReasons = [trustFailure.message];
+          if (!result.guidance && wellKnownUrls) {
+            result.guidance = {
+              message: trustFailure.message,
+              registrationUrl: wellKnownUrls.registrationUrl,
+              documentationUrl: wellKnownUrls.documentationUrl
+            };
+          }
           if (shouldRecordDecisions && sessionId) {
             recordDecision(config, sessionId, "denied", trustFailure.message).catch(() => {
             });
           }
+          dedupeFailures(result);
           onDenied(result, req, res);
           return;
         }
@@ -1051,7 +1205,38 @@ function createMiddleware(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] 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: [`Verification middleware internal error: ${errorClass}`],
+          failures: [
+            {
+              dimension: "middleware.internal_error",
+              message: `Middleware threw ${errorClass} \u2014 failing closed`
+            }
+          ],
+          verifiedAt: /* @__PURE__ */ new Date(),
+          correlationId
+        };
+        const catchUrls = config.apiBaseUrl ? await getWellKnownUrls(config.apiBaseUrl).catch(() => void 0) : void 0;
+        if (catchUrls) {
+          result.guidance = {
+            message: `Middleware threw ${errorClass} \u2014 failing closed`,
+            registrationUrl: catchUrls.registrationUrl,
+            documentationUrl: catchUrls.documentationUrl
+          };
+        }
+        dedupeFailures(result);
+        return onDenied(result, req, res);
+      }
       next();
     }
   };
@@ -1063,6 +1248,18 @@ __export(nextjs_exports, {
   createMatcherConfig: () => createMatcherConfig,
   createMiddleware: () => createMiddleware2
 });
+function escapeHtml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function sanitizeUrl(value, fallback) {
+  if (typeof value !== "string" || value.length === 0) return escapeHtml(fallback);
+  const trimmed = value.trim();
+  if (/^javascript:|^data:|^vbscript:/i.test(trimmed)) return escapeHtml(fallback);
+  if (/^https?:\/\//i.test(trimmed) || trimmed.startsWith("/")) {
+    return escapeHtml(trimmed);
+  }
+  return escapeHtml(fallback);
+}
 function extractCredentialsFromNextRequest(request) {
   const credentials = {};
   const astraId = request.headers.get("x-astra-id") || request.headers.get("X-Astra-Id");
@@ -1134,10 +1331,18 @@ function extractPurpose(request) {
   }
 }
 function generateCommerceShieldHtml(result, options) {
-  const title = options.commerceShield?.title || "AstraSync Agent Verification";
-  const message = options.commerceShield?.message || result.guidance?.message || "This site verifies AI agents before granting access. We noticed you're visiting without AstraSync credentials.";
-  const registrationUrl = result.guidance?.registrationUrl || "https://astrasync.ai/register";
-  const docsUrl = result.guidance?.documentationUrl || "https://astrasync.ai/docs/agent-access";
+  const title = escapeHtml(options.commerceShield?.title || "AstraSync Agent Verification");
+  const message = escapeHtml(
+    options.commerceShield?.message || result.guidance?.message || "This site verifies AI agents before granting access. We noticed you're visiting without AstraSync credentials."
+  );
+  const registrationUrl = sanitizeUrl(
+    result.guidance?.registrationUrl,
+    "https://astrasync.ai/register"
+  );
+  const docsUrl = sanitizeUrl(
+    result.guidance?.documentationUrl,
+    "https://astrasync.ai/docs/agent-access"
+  );
   const allowGuest = options.commerceShield?.allowGuestAccess ?? true;
   return `
 <!DOCTYPE html>
@@ -1259,7 +1464,7 @@ function generateCommerceShieldHtml(result, options) {
     <div class="shield-steps">
       <h3>To get verified access:</h3>
       <ol>
-        <li>Register at <a href="${registrationUrl}">astrasync.ai/register</a></li>
+        <li>Register at <a href="${registrationUrl}">astrasync.ai/agents/register</a></li>
         <li>Create and register your agent</li>
         <li>Add your ASTRA-ID to request headers</li>
         <li>Refresh this page</li>
@@ -1347,7 +1552,7 @@ function createMiddleware2(options) {
         denialReasons: preCheckFailures.map((f) => f.message),
         guidance: {
           message: "Request exceeds counterparty-defined PDLSS limits.",
-          registrationUrl: `${config.apiBaseUrl?.replace("/api", "")}/register`,
+          registrationUrl: `${config.apiBaseUrl?.replace("/api", "")}/agents/register`,
           documentationUrl: `${config.apiBaseUrl?.replace("/api", "")}/docs/pdlss`
         },
         verifiedAt: /* @__PURE__ */ new Date()
@@ -2008,12 +2213,45 @@ function bufferToBase64(bytes) {
 
 // src/transport/rfc9421-verify.ts
 var import_http_message_signatures = require("http-message-signatures");
+
+// src/transport/nonce-store.ts
+var InMemoryNonceStore = class {
+  constructor(capacity = 1e4) {
+    this.entries = /* @__PURE__ */ new Map();
+    this.lastSweepMs = 0;
+    this.capacity = capacity;
+  }
+  seen(key, expiresAtMs) {
+    const nowMs = Date.now();
+    if (nowMs - this.lastSweepMs > 1e3) {
+      for (const [k, exp] of this.entries) {
+        if (exp <= nowMs) this.entries.delete(k);
+      }
+      this.lastSweepMs = nowMs;
+    }
+    const existing = this.entries.get(key);
+    if (existing !== void 0 && existing > nowMs) {
+      return true;
+    }
+    if (this.entries.size >= this.capacity) {
+      const oldest = this.entries.keys().next().value;
+      if (oldest !== void 0) this.entries.delete(oldest);
+    }
+    this.entries.set(key, expiresAtMs);
+    return false;
+  }
+};
+var defaultNonceStore = new InMemoryNonceStore();
+
+// src/transport/rfc9421-verify.ts
 async function verifyRFC9421(request, options) {
   const { resolver } = options;
-  const tolerance = options.clockSkewSec ?? 300;
+  const tolerance = options.clockSkewSec ?? 60;
   const nowSec = options.now ? options.now() : Math.floor(Date.now() / 1e3);
+  const nonceStore = options.nonceStore ?? defaultNonceStore;
   let resolvedKid;
   let resolvedAlg;
+  let replayDetected = false;
   const keyLookup = async (parameters) => {
     const kid = typeof parameters.keyid === "string" ? parameters.keyid : void 0;
     if (!kid) return null;
@@ -2027,6 +2265,14 @@ async function verifyRFC9421(request, options) {
     const expires = toUnixSeconds(parameters.expires);
     if (created !== void 0 && Math.abs(nowSec - created) > tolerance) return null;
     if (expires !== void 0 && nowSec > expires + tolerance) return null;
+    const nonce = typeof parameters.nonce === "string" ? parameters.nonce : void 0;
+    if (nonce) {
+      const expiresAtMs = (expires !== void 0 ? expires + tolerance : nowSec + tolerance) * 1e3;
+      if (nonceStore.seen(`rfc9421:${kid}:${nonce}`, expiresAtMs)) {
+        replayDetected = true;
+        return null;
+      }
+    }
     return jwkToVerifyingKey(kid, jwk, alg);
   };
   try {
@@ -2049,7 +2295,7 @@ async function verifyRFC9421(request, options) {
       kid: resolvedKid,
       registry: resolver.name,
       algorithm: resolvedAlg,
-      error: result === false ? "signature invalid" : "no signature found"
+      error: replayDetected ? "RFC9421 signature replay \u2014 already seen within tolerance window" : result === false ? "signature invalid" : "no signature found"
     };
   } catch (err) {
     return {
@@ -2874,14 +3120,26 @@ function sha256Sync2(data) {
 function verifyAP2Chain(input) {
   const { triple } = input;
   const errors = [];
+  const toleranceSec = input.clockSkewSec ?? 60;
+  const nonceStore = input.nonceStore ?? defaultNonceStore;
   const intentPresent = triple.intent !== void 0;
   const cartRefOk = checkCartRef(triple, errors);
   const paymentRefOk = checkPaymentRef(triple, errors);
   const { ok: agentIdContinuity, agentId } = checkAgentContinuity(triple, errors);
   const paymentMethodAllowed = checkPaymentMethod(triple, errors);
   const totalsConsistent = checkTotals(triple, errors);
-  const expiryOk = checkExpiries(triple, input.clockSkewSec ?? 300, input.now, errors);
-  const ok = cartRefOk && paymentRefOk && agentIdContinuity && paymentMethodAllowed && totalsConsistent && expiryOk;
+  const expiryOk = checkExpiries(triple, toleranceSec, input.now, errors);
+  let replayOk = true;
+  const replayId = triple.payment?.raw?.id ?? triple.cart?.raw?.id;
+  if (typeof replayId === "string" && replayId.length > 0) {
+    const now = input.now ? input.now() : Math.floor(Date.now() / 1e3);
+    const expiresAt = (now + toleranceSec) * 1e3;
+    if (nonceStore.seen(`ap2:${replayId}`, expiresAt)) {
+      errors.push(`AP2 chain replay \u2014 mandate ${replayId} already seen within tolerance window`);
+      replayOk = false;
+    }
+  }
+  const ok = cartRefOk && paymentRefOk && agentIdContinuity && paymentMethodAllowed && totalsConsistent && expiryOk && replayOk;
   return {
     ok,
     checks: {
@@ -2927,7 +3185,10 @@ function checkAgentContinuity(triple, errors) {
   const ids = [triple.intent?.agent_id, triple.cart?.agent_id, triple.payment?.agent_id].filter(
     (id) => typeof id === "string" && id.length > 0
   );
-  if (ids.length === 0) return { ok: true };
+  if (ids.length === 0) {
+    errors.push("agent_id missing across all three mandates (intent/cart/payment)");
+    return { ok: false };
+  }
   const unique = new Set(ids);
   if (unique.size > 1) {
     errors.push(`agent_id mismatch across mandates: ${Array.from(unique).join(", ")}`);
@@ -2936,9 +3197,16 @@ function checkAgentContinuity(triple, errors) {
   return { ok: true, agentId: ids[0] };
 }
 function checkPaymentMethod(triple, errors) {
-  const paymentMethod = triple.payment?.payment_method;
   const allowed = triple.intent?.paymentMethods;
-  if (!paymentMethod || !allowed || allowed.length === 0) return true;
+  if (!allowed || allowed.length === 0) return true;
+  if (!triple.payment) return true;
+  const paymentMethod = triple.payment.payment_method;
+  if (!paymentMethod) {
+    errors.push(
+      `payment.payment_method missing but intent declares allowlist [${allowed.join(", ")}]`
+    );
+    return false;
+  }
   if (!allowed.includes(paymentMethod)) {
     errors.push(
       `payment_method "${paymentMethod}" not in intent.paymentMethods [${allowed.join(", ")}]`
@@ -2972,19 +3240,24 @@ function checkTotals(triple, errors) {
 function checkExpiries(triple, toleranceSec, nowFn, errors) {
   const now = nowFn ? nowFn() : Math.floor(Date.now() / 1e3);
   let ok = true;
-  for (const [name, mandate] of [
-    ["intent", triple.intent],
-    ["cart", triple.cart]
-  ]) {
-    if (!mandate?.expires) continue;
-    const parsed = parseExpiry(mandate.expires);
+  const layers = [
+    ["intent", triple.intent?.expires],
+    ["cart", triple.cart?.expires],
+    [
+      "payment",
+      typeof triple.payment?.raw?.expires === "string" ? triple.payment.raw.expires : typeof triple.payment?.raw?.exp === "string" ? triple.payment.raw.exp : void 0
+    ]
+  ];
+  for (const [name, expires] of layers) {
+    if (!expires) continue;
+    const parsed = parseExpiry(expires);
     if (parsed === null) {
       errors.push(`${name}.expires unparseable`);
       ok = false;
       continue;
     }
     if (now > parsed + toleranceSec) {
-      errors.push(`${name} mandate expired at ${mandate.expires}`);
+      errors.push(`${name} mandate expired at ${expires}`);
       ok = false;
     }
   }
@@ -3011,10 +3284,21 @@ async function verifyACPSignature(input) {
   if (!input.signatureHeader) {
     return { ok: false, error: "missing Signature header" };
   }
-  const freshness = checkTimestamp(input.timestampHeader, input.clockSkewSec ?? 300, input.now);
+  const tolerance = input.clockSkewSec ?? 60;
+  const nonceStore = input.nonceStore ?? defaultNonceStore;
+  const freshness = checkTimestamp(input.timestampHeader, tolerance, input.now);
   if (!freshness.ok) {
     return { ok: false, error: freshness.error, timestampStale: true };
   }
+  const nowSec = input.now ? input.now() : Math.floor(Date.now() / 1e3);
+  const expiresAtMs = (nowSec + tolerance) * 1e3;
+  const replayKey = `acp:${input.signatureHeader}:${input.timestampHeader ?? ""}`;
+  if (nonceStore.seen(replayKey, expiresAtMs)) {
+    return {
+      ok: false,
+      error: "ACP signature replay \u2014 already seen within tolerance window"
+    };
+  }
   const signatureBytes = decodeBase64(input.signatureHeader);
   if (!signatureBytes) {
     return { ok: false, error: "signature header is not valid base64" };
@@ -3232,8 +3516,9 @@ function coerceString6(v) {
 var import_mppx2 = require("mppx");
 function verifyMPP(input) {
   const { context } = input;
-  const tolerance = input.clockSkewSec ?? 300;
+  const tolerance = input.clockSkewSec ?? 60;
   const nowSec = input.now ? input.now() : Math.floor(Date.now() / 1e3);
+  const nonceStore = input.nonceStore ?? defaultNonceStore;
   const challenge = context.credential?.challenge ?? (context.challenges && context.challenges[0]);
   const source = context.credential?.source;
   const method = challenge?.method;
@@ -3256,21 +3541,38 @@ function verifyMPP(input) {
     }
   }
   let bodyDigestOk = null;
-  if (challenge?.digest && input.rawBody !== void 0) {
-    try {
-      if (!/^sha-256=/.test(challenge.digest)) {
+  if (input.rawBody !== void 0) {
+    if (!challenge?.digest) {
+      bodyDigestOk = false;
+    } else {
+      try {
+        if (!/^sha-256=/.test(challenge.digest)) {
+          bodyDigestOk = false;
+        } else {
+          bodyDigestOk = import_mppx2.BodyDigest.verify(challenge.digest, input.rawBody);
+        }
+      } catch {
         bodyDigestOk = false;
-      } else {
-        bodyDigestOk = import_mppx2.BodyDigest.verify(challenge.digest, input.rawBody);
       }
-    } catch {
-      bodyDigestOk = false;
     }
   }
-  const ok = expiryOk && (bodyDigestOk === null || bodyDigestOk === true);
+  let replayOk = true;
+  if (challenge?.digest && expiryOk) {
+    const replayKey = `mpp:${challenge.digest}:${challenge.nonce ?? ""}`;
+    const expiresAt = (nowSec + tolerance) * 1e3;
+    if (nonceStore.seen(replayKey, expiresAt)) {
+      replayOk = false;
+    }
+  }
+  const ok = expiryOk && (bodyDigestOk === null || bodyDigestOk === true) && replayOk;
   const errors = [];
   if (!expiryOk) errors.push("challenge expired");
-  if (bodyDigestOk === false) errors.push("body digest mismatch");
+  if (bodyDigestOk === false) {
+    errors.push(
+      input.rawBody !== void 0 && !challenge?.digest ? "body digest required when rawBody present" : "body digest mismatch"
+    );
+  }
+  if (!replayOk) errors.push("MPP challenge replay \u2014 already seen within tolerance window");
   return {
     ok,
     expiryOk,
@@ -3431,14 +3733,32 @@ function readHeader4(headers, name) {
 var import_node_crypto4 = require("crypto");
 async function verifyVIChain(input) {
   const errors = [];
-  const tolerance = input.clockSkewSec ?? 300;
+  const tolerance = input.clockSkewSec ?? 60;
   const now = input.now ? input.now() : Math.floor(Date.now() / 1e3);
   const { l1, l2, l3a, l3b } = input.layers;
+  const nonceStore = input.nonceStore ?? defaultNonceStore;
+  if (!l1) {
+    if (!input.allowUnboundChain) {
+      errors.push(
+        "L1 missing \u2014 chain root unbound (set allowUnboundChain + expectedL2Key to override)"
+      );
+    } else if (!input.expectedL2Key) {
+      errors.push("allowUnboundChain set but expectedL2Key missing");
+    }
+  }
   const l1SigOk = l1 ? await input.verifySignature(l1, null) : null;
   if (l1 && !l1SigOk) errors.push("L1 signature invalid");
   const l1Cnf = extractCnfJwk(l1?.payload);
-  const l2SigOk = await input.verifySignature(l2, l1Cnf ?? null);
+  const l2ExpectedKey = l1Cnf ?? input.expectedL2Key ?? null;
+  const l2SigOk = await input.verifySignature(l2, l2ExpectedKey);
   if (!l2SigOk) errors.push("L2 signature invalid");
+  if (l2SigOk) {
+    const replayKey = `vi:l2:${l2.compact}`;
+    const expiresAt = now * 1e3 + tolerance * 1e3;
+    if (nonceStore.seen(replayKey, expiresAt)) {
+      errors.push("L2 signature replay \u2014 already seen within tolerance window");
+    }
+  }
   const l2Cnf = extractCnfJwk(l2.payload);
   const l3aSigOk = l3a ? await input.verifySignature(l3a, l2Cnf ?? null) : null;
   if (l3a && !l3aSigOk) errors.push("L3a signature invalid");
@@ -3482,7 +3802,10 @@ async function verifyVIChain(input) {
     }
   }
   const expiryOk = checkExpiryAcross([l1, l2, l3a, l3b], tolerance, now, errors);
-  const ok = l1SigOk !== false && l2SigOk && l3aSigOk !== false && l3bSigOk !== false && l1BindsL2 && l2BindsL3 && l3aL3bTxnIdMatch !== false && checkoutHashOk !== false && expiryOk;
+  const noUnboundChainOrReplayErrors = !errors.some(
+    (e) => e.startsWith("L1 missing") || e.startsWith("allowUnboundChain set") || e.startsWith("L2 signature replay")
+  );
+  const ok = l1SigOk !== false && l2SigOk && l3aSigOk !== false && l3bSigOk !== false && l1BindsL2 && l2BindsL3 && l3aL3bTxnIdMatch !== false && checkoutHashOk !== false && expiryOk && noUnboundChainOrReplayErrors;
   return {
     ok,
     checks: {
@@ -3915,7 +4238,7 @@ async function exportJwkFromKeyLike(keyLike) {
 
 // src/transport/registry/mastercard.ts
 function createMastercardRegistry(options = {}) {
-  const cache = /* @__PURE__ */ new Map();
+  const cache2 = /* @__PURE__ */ new Map();
   const ttlSec = options.cacheTtlSec ?? 3600;
   const fetchFn = options.fetch ?? globalThis.fetch;
   let warned = false;
@@ -3932,7 +4255,7 @@ function createMastercardRegistry(options = {}) {
         }
         return null;
       }
-      const cached = cache.get(kid);
+      const cached = cache2.get(kid);
       if (cached && cached.expiresAt > Date.now()) return cached.jwk;
       try {
         const res = await fetchFn(options.registryUrl);
@@ -3941,7 +4264,7 @@ function createMastercardRegistry(options = {}) {
         const keys = body.keys ?? [];
         for (const k of keys) {
           if (k.kid === kid) {
-            cache.set(kid, { jwk: k, expiresAt: Date.now() + ttlSec * 1e3 });
+            cache2.set(kid, { jwk: k, expiresAt: Date.now() + ttlSec * 1e3 });
             return k;
           }
         }
@@ -3956,7 +4279,7 @@ function createMastercardRegistry(options = {}) {
 // src/transport/registry/web-bot-auth.ts
 var DIRECTORY_PATH = "/.well-known/http-message-signatures-directory";
 function createWebBotAuthRegistry(options = {}) {
-  const cache = /* @__PURE__ */ new Map();
+  const cache2 = /* @__PURE__ */ new Map();
   const ttlSec = options.cacheTtlSec ?? 3600;
   const fetchFn = options.fetch ?? globalThis.fetch;
   return {
@@ -3965,7 +4288,7 @@ function createWebBotAuthRegistry(options = {}) {
       if (!kid) return null;
       const directoryUrl = resolveDirectoryUrl(options.directoryUrl, context?.origin);
       if (!directoryUrl) return null;
-      const cached = cache.get(directoryUrl);
+      const cached = cache2.get(directoryUrl);
       const now = Date.now();
       if (cached && cached.expiresAt > now) {
         return findKeyByKid(cached.keys, kid);
@@ -3975,7 +4298,7 @@ function createWebBotAuthRegistry(options = {}) {
         if (!res.ok) return null;
         const body = await res.json();
         const keys = body.keys ?? [];
-        cache.set(directoryUrl, { keys, expiresAt: now + ttlSec * 1e3 });
+        cache2.set(directoryUrl, { keys, expiresAt: now + ttlSec * 1e3 });
         return findKeyByKid(keys, kid);
       } catch {
         return null;
@@ -4114,19 +4437,22 @@ function extractFromMcpBody(astrasyncMeta, args, key) {
   }
   return { value: void 0, source: void 0 };
 }
-function mcpToPdlss(parsed, headerPurpose, headerAction) {
-  const resource = parsed.toolName ? `mcp:tool/${parsed.toolName}` : `mcp:method/${parsed.method}`;
+function mcpToPdlss(parsed, requestPath, headerPurpose, headerAction, toolGate) {
+  const resource = toolGate?.resource ?? requestPath;
   let purpose;
   let purposeSource;
-  if (headerPurpose) {
+  if (toolGate?.purpose !== void 0) {
+    purpose = toolGate.purpose;
+    purposeSource = "tool_gate";
+  } else if (headerPurpose) {
     purpose = headerPurpose;
     purposeSource = "header";
   } else if (parsed.purposeFromBody && parsed.purposeSourceFromBody) {
     purpose = parsed.purposeFromBody;
     purposeSource = parsed.purposeSourceFromBody;
   } else {
-    purpose = "mcp_invoke";
-    purposeSource = "default_mcp_invoke";
+    purpose = void 0;
+    purposeSource = void 0;
   }
   let action;
   let actionSource;
@@ -4137,7 +4463,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 };
@@ -4151,11 +4477,28 @@ function mcpRiskTier(parsed) {
 }
 
 // src/adapters/mcp.ts
+function normalizeToolGate(gate) {
+  return typeof gate === "string" ? { minAccessLevel: gate } : gate;
+}
 function readSingleHeader(value) {
   if (typeof value === "string") return value;
   if (Array.isArray(value)) return value[0];
   return void 0;
 }
+function dedupeFailures2(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;
+    });
+  }
+  if (result.denialReasons && result.denialReasons.length > 1) {
+    result.denialReasons = [...new Set(result.denialReasons)];
+  }
+}
 function defaultMcpDenied(result, req, res) {
   const id = req.body?.id ?? null;
   const status = !result.identityVerified ? 401 : 403;
@@ -4180,11 +4523,17 @@ function defaultMcpDenied(result, req, res) {
   });
 }
 function resolveMinAccessLevel(parsed, opts) {
-  if (parsed.toolName && opts.toolGates && opts.toolGates[parsed.toolName] !== void 0) {
-    return { level: opts.toolGates[parsed.toolName], source: "toolGate" };
+  if (!parsed.toolName) {
+    if (opts.methodGates && opts.methodGates[parsed.method] !== void 0) {
+      return { level: opts.methodGates[parsed.method], source: "methodGate" };
+    }
+    return { level: "none", source: "discovery_default" };
   }
-  if (opts.methodGates && opts.methodGates[parsed.method] !== void 0) {
-    return { level: opts.methodGates[parsed.method], source: "methodGate" };
+  if (opts.toolGates && opts.toolGates[parsed.toolName] !== void 0) {
+    return {
+      level: normalizeToolGate(opts.toolGates[parsed.toolName]).minAccessLevel,
+      source: "toolGate"
+    };
   }
   return { level: mcpRiskTier(parsed), source: "tier" };
 }
@@ -4195,12 +4544,17 @@ function createMcpMiddleware(options) {
     onAgentIdMismatch = "reject",
     skip = false,
     onDenied = defaultMcpDenied,
-    trustVerifiedHop = true,
+    trustVerifiedHop = false,
     verifiedHopMaxAgeMs,
     recordDecisions,
     enableRuntimeChallenge = true,
+    failOnError = "open",
     ...config
   } = options;
+  if (config.apiBaseUrl) {
+    prefetchWellKnown(config.apiBaseUrl).catch(() => {
+    });
+  }
   return async (req, res, next) => {
     try {
       if (skip) return next();
@@ -4213,6 +4567,7 @@ 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;
@@ -4266,9 +4621,17 @@ function createMcpMiddleware(options) {
         }
         return next();
       }
+      const rawGate = parsed.toolName && toolGates?.[parsed.toolName];
+      const gate = rawGate ? normalizeToolGate(rawGate) : void 0;
       const headerPurpose = readSingleHeader(req.headers["x-astra-purpose"]);
       const headerAction = readSingleHeader(req.headers["x-astra-action"]);
-      const pdlss = mcpToPdlss(parsed, headerPurpose, headerAction);
+      const pdlss = mcpToPdlss(
+        parsed,
+        req.path,
+        headerPurpose,
+        headerAction,
+        gate ? { purpose: gate.purpose, resource: gate.resource } : void 0
+      );
       if (config.debug) {
         console.debug("[mcp-middleware] pdlss resolved", {
           purpose_source: pdlss.purposeSource,
@@ -4306,6 +4669,7 @@ function createMcpMiddleware(options) {
           recordDecision(config, sessionId, "denied", result.denialReasons?.[0]).catch(() => {
           });
         }
+        dedupeFailures2(result);
         onDenied(result, req, res);
         return;
       }
@@ -4328,6 +4692,13 @@ function createMcpMiddleware(options) {
         };
         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 = {
@@ -4351,6 +4722,7 @@ function createMcpMiddleware(options) {
             });
           }
         }
+        dedupeFailures2(result);
         onDenied(result, req, res);
         return;
       }
@@ -4374,7 +4746,38 @@ 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
+        };
+        const catchUrls = config.apiBaseUrl ? await getWellKnownUrls(config.apiBaseUrl).catch(() => void 0) : void 0;
+        if (catchUrls) {
+          result.guidance = {
+            message: `Middleware threw ${errorClass} \u2014 failing closed`,
+            registrationUrl: catchUrls.registrationUrl,
+            documentationUrl: catchUrls.documentationUrl
+          };
+        }
+        dedupeFailures2(result);
+        return onDenied(result, req, res);
+      }
       next();
     }
   };
@@ -5082,11 +5485,14 @@ var VERSION = "2.0.0";
   extractCredentials,
   extractMcpCredentials,
   getAccessLevelForScore,
+  getCachedWellKnownUrls,
   getCapabilities,
   getTrustLevel,
+  getWellKnownUrls,
   hasCredentials,
   hasMinimumAccess,
   nextjs,
+  prefetchWellKnown,
   quickVerify,
   recordDecision,
   sdk,