@astrasyncai/verification-gateway 2.4.14 → 2.5.0

package/dist/index.d.mts

@@ -4,7 +4,7 @@ export { A as ACCESS_LEVEL_DESCRIPTIONS, a as ACCESS_LEVEL_HIERARCHY, b as Acces
 export { e as express } from './express-ienhAXps.mjs';
 export { n as nextjs } from './nextjs-DSpisQst.mjs';
 export { aR as extractMcpCredentials, bg as setMcpMeta, b1 as transport } from './index-CEg_WG6y.mjs';
-export { McpMiddlewareOptions, createMcpMiddleware } from './adapters/mcp.mjs';
+export { McpMiddlewareOptions, ToolGateConfig, createMcpMiddleware } from './adapters/mcp.mjs';
 export { AgentProtocol, AgentRecord, AstraSync, AstraSyncConfig, AstraSyncError, AuthenticationError, BuildGuidanceParams, FrameworkConfig, GuidanceEnvelope, HealthResponse, KYDRequiredError, ModelConfig, PDLSSConfig, PDLSSDuration, PDLSSLimits, PDLSSPurpose, PDLSSScope, PDLSSSelfInstantiation, PendingRegistrationResponse, PollRegistrationResult, RegisterOptions, RegisterResult, RegistrationDeniedError, RegistrationExpiredError, RegistrationResponse, RegistrationTimeoutError, VerifyResponse, WaitForApprovalOptions, buildGuidance } from './registration/index.mjs';
 export { A as AgentClient, C as ChallengeHandler, i as agent, r as recordDecision } from './index-B5e2IDWU.mjs';
 import 'express';
@@ -50,6 +50,36 @@ declare function quickVerify(config: GatewayConfig, credentials: AgentCredential
     reason?: string;
 }>;
 
+/**
+ * SDK-side discovery of canonical platform URLs via `/.well-known/agentic-commerce`.
+ *
+ * Fire-and-forget pre-fetch at middleware creation; first verify() awaits
+ * the in-flight promise if it hasn't resolved. 60-minute TTL with
+ * stale-while-revalidate background refresh.
+ */
+interface WellKnownAgenticCommerce {
+    registrationUrl: string;
+    documentationUrl: string;
+    verifyAccessUrl: string;
+}
+/**
+ * Start a background fetch. Returns the promise for callers that need
+ * to await it (first verify() call).
+ */
+declare function prefetchWellKnown(apiBaseUrl: string): Promise<WellKnownAgenticCommerce>;
+/**
+ * Get cached well-known URLs. If stale, triggers a background refresh
+ * and returns stale data (stale-while-revalidate). If no cache exists,
+ * awaits the in-flight fetch or starts a new one.
+ */
+declare function getWellKnownUrls(apiBaseUrl: string): Promise<WellKnownAgenticCommerce>;
+/**
+ * Synchronous cache read — returns cached URLs or undefined.
+ * Never triggers a fetch. Used by verify() to avoid extra HTTP calls
+ * in the hot path; adapters are responsible for prefetching.
+ */
+declare function getCachedWellKnownUrls(apiBaseUrl: string): WellKnownAgenticCommerce | undefined;
+
 /**
  * AstraSync Universal Verification Gateway
  *
@@ -77,4 +107,4 @@ declare function quickVerify(config: GatewayConfig, credentials: AgentCredential
 
 declare const VERSION = "2.0.0";
 
-export { AccessLevel, AgentCredentials, GatewayConfig, VERSION, VerificationRequest, VerificationResult, clearCache, extractCredentials, hasCredentials, quickVerify, verify };
+export { AccessLevel, AgentCredentials, GatewayConfig, VERSION, VerificationRequest, VerificationResult, type WellKnownAgenticCommerce, clearCache, extractCredentials, getCachedWellKnownUrls, getWellKnownUrls, hasCredentials, prefetchWellKnown, quickVerify, verify };

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { A as ACCESS_LEVEL_DESCRIPTIONS, a as ACCESS_LEVEL_HIERARCHY, b as Acces
 export { e as express } from './express-CrfwoNAR.js';
 export { n as nextjs } from './nextjs-66R1KW8e.js';
 export { aR as extractMcpCredentials, bg as setMcpMeta, b1 as transport } from './index-CCdZxvAr.js';
-export { McpMiddlewareOptions, createMcpMiddleware } from './adapters/mcp.js';
+export { McpMiddlewareOptions, ToolGateConfig, createMcpMiddleware } from './adapters/mcp.js';
 export { AgentProtocol, AgentRecord, AstraSync, AstraSyncConfig, AstraSyncError, AuthenticationError, BuildGuidanceParams, FrameworkConfig, GuidanceEnvelope, HealthResponse, KYDRequiredError, ModelConfig, PDLSSConfig, PDLSSDuration, PDLSSLimits, PDLSSPurpose, PDLSSScope, PDLSSSelfInstantiation, PendingRegistrationResponse, PollRegistrationResult, RegisterOptions, RegisterResult, RegistrationDeniedError, RegistrationExpiredError, RegistrationResponse, RegistrationTimeoutError, VerifyResponse, WaitForApprovalOptions, buildGuidance } from './registration/index.js';
 export { A as AgentClient, C as ChallengeHandler, i as agent, r as recordDecision } from './index-DC5f8eoQ.js';
 import 'express';
@@ -50,6 +50,36 @@ declare function quickVerify(config: GatewayConfig, credentials: AgentCredential
     reason?: string;
 }>;
 
+/**
+ * SDK-side discovery of canonical platform URLs via `/.well-known/agentic-commerce`.
+ *
+ * Fire-and-forget pre-fetch at middleware creation; first verify() awaits
+ * the in-flight promise if it hasn't resolved. 60-minute TTL with
+ * stale-while-revalidate background refresh.
+ */
+interface WellKnownAgenticCommerce {
+    registrationUrl: string;
+    documentationUrl: string;
+    verifyAccessUrl: string;
+}
+/**
+ * Start a background fetch. Returns the promise for callers that need
+ * to await it (first verify() call).
+ */
+declare function prefetchWellKnown(apiBaseUrl: string): Promise<WellKnownAgenticCommerce>;
+/**
+ * Get cached well-known URLs. If stale, triggers a background refresh
+ * and returns stale data (stale-while-revalidate). If no cache exists,
+ * awaits the in-flight fetch or starts a new one.
+ */
+declare function getWellKnownUrls(apiBaseUrl: string): Promise<WellKnownAgenticCommerce>;
+/**
+ * Synchronous cache read — returns cached URLs or undefined.
+ * Never triggers a fetch. Used by verify() to avoid extra HTTP calls
+ * in the hot path; adapters are responsible for prefetching.
+ */
+declare function getCachedWellKnownUrls(apiBaseUrl: string): WellKnownAgenticCommerce | undefined;
+
 /**
  * AstraSync Universal Verification Gateway
  *
@@ -77,4 +107,4 @@ declare function quickVerify(config: GatewayConfig, credentials: AgentCredential
 
 declare const VERSION = "2.0.0";
 
-export { AccessLevel, AgentCredentials, GatewayConfig, VERSION, VerificationRequest, VerificationResult, clearCache, extractCredentials, hasCredentials, quickVerify, verify };
+export { AccessLevel, AgentCredentials, GatewayConfig, VERSION, VerificationRequest, VerificationResult, type WellKnownAgenticCommerce, clearCache, extractCredentials, getCachedWellKnownUrls, getWellKnownUrls, hasCredentials, prefetchWellKnown, quickVerify, verify };

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,
@@ -191,6 +194,65 @@ function getCapabilities(accessLevel) {
 // src/version.ts
 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 = {
   apiBaseUrl: "https://astrasync.ai/api",
@@ -332,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", "")}/agents/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", "")}/agents/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",
@@ -388,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;
@@ -468,6 +531,7 @@ 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) {
     if (mergedConfig.strictInit) {
       await performInitCheck(mergedConfig.apiBaseUrl, mergedConfig.debug, true);
@@ -504,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) {
@@ -527,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", "")}/agents/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
@@ -599,12 +664,12 @@ async function verify(config, request) {
     ];
     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`
+      registrationUrl: urls?.registrationUrl ?? "",
+      documentationUrl: urls?.documentationUrl ?? ""
     } : {
       message: result.recommendationReasons?.[0] || "Access denied by AstraSync recommendation",
-      registrationUrl: `${mergedConfig.apiBaseUrl?.replace("/api", "")}/agents/register`,
-      documentationUrl: `${mergedConfig.apiBaseUrl?.replace("/api", "")}/docs/pdlss`
+      registrationUrl: urls?.registrationUrl ?? "",
+      documentationUrl: urls?.documentationUrl ?? ""
     };
   } else if (result.recommendation === "step_up_required") {
     result.requiresStepUp = true;
@@ -887,6 +952,9 @@ function dedupeFailures(result) {
       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;
@@ -918,6 +986,10 @@ function createMiddleware(options) {
     caseInsensitiveRouteMatch = false,
     ...config
   } = options;
+  if (config.apiBaseUrl) {
+    prefetchWellKnown(config.apiBaseUrl).catch(() => {
+    });
+  }
   let cachedRoutes = [];
   let lastFetchAt = 0;
   let refreshing = null;
@@ -980,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)) {
@@ -1001,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", "")}/agents/register`,
-            documentationUrl: `${config.apiBaseUrl?.replace("/api", "")}/docs/pdlss`
+            registrationUrl: wellKnownUrls?.registrationUrl ?? "",
+            documentationUrl: wellKnownUrls?.documentationUrl ?? ""
           },
           verifiedAt: /* @__PURE__ */ new Date()
         };
@@ -1082,6 +1155,13 @@ 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(() => {
           });
@@ -1099,6 +1179,13 @@ 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(() => {
             });
@@ -1139,6 +1226,14 @@ function createMiddleware(options) {
           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);
       }
@@ -4143,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;
@@ -4160,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);
@@ -4169,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;
           }
         }
@@ -4184,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 {
@@ -4193,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);
@@ -4203,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;
@@ -4342,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;
@@ -4379,6 +4477,9 @@ 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];
@@ -4394,6 +4495,9 @@ function dedupeFailures2(result) {
       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;
@@ -4419,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" };
 }
@@ -4441,6 +4551,10 @@ function createMcpMiddleware(options) {
     failOnError = "open",
     ...config
   } = options;
+  if (config.apiBaseUrl) {
+    prefetchWellKnown(config.apiBaseUrl).catch(() => {
+    });
+  }
   return async (req, res, next) => {
     try {
       if (skip) return next();
@@ -4453,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;
@@ -4506,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,
@@ -4569,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 = {
@@ -4637,6 +4767,14 @@ function createMcpMiddleware(options) {
           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);
       }
@@ -5347,11 +5485,14 @@ var VERSION = "2.0.0";
   extractCredentials,
   extractMcpCredentials,
   getAccessLevelForScore,
+  getCachedWellKnownUrls,
   getCapabilities,
   getTrustLevel,
+  getWellKnownUrls,
   hasCredentials,
   hasMinimumAccess,
   nextjs,
+  prefetchWellKnown,
   quickVerify,
   recordDecision,
   sdk,