@astrasyncai/verification-gateway 2.4.14 → 2.5.1

package/dist/adapters/mcp.d.mts

@@ -85,7 +85,7 @@ interface ParsedMcpRequest {
      * (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'`.
+     * before mapping; final fallback at `mcpToPdlss` is `undefined`.
      */
     purposeFromBody?: string;
     /** Which body location resolved `purposeFromBody`. */
@@ -120,60 +120,45 @@ declare function parseMcpJsonRpc(body: unknown): ParsedMcpRequest | null;
 /**
  * PDLSS mapping for an MCP request. The platform's PDLSS taxonomy is
  * `purpose / action / resource`; for MCP traffic the audit-useful dimensions
- * are the JSON-RPC method and (for `tools/call`) the tool name. Doc-stable so
- * dashboards and audits can correlate consistently across cohort-3 partners.
+ * are the JSON-RPC method and (for `tools/call`) the tool name.
  *
- * Rules:
- *   - `purpose` is always `mcp_invoke` for MCP traffic — sets the high-level
- *     PDLSS bucket.
- *   - `action` is the JSON-RPC method, optionally `:tool_name` suffixed for
- *     `tools/call`. Lets PDLSS allowlist specific tools.
- *   - `resource` is `mcp:tool/<name>` for `tools/call`, `mcp:method/<method>`
- *     otherwise. Lets PDLSS scope on tool identity.
+ * v2.5.0 rules:
+ *   - `resource` defaults to the HTTP request path (e.g. `/mcp`). Per-tool
+ *     overrides via `toolGates` config let merchants map tools to specific
+ *     backend resources (e.g. `/api/catalog`).
+ *   - `purpose` defaults to `undefined` (backend evaluator applies
+ *     skip-when-undefined). Per-tool overrides via `toolGates` config let
+ *     merchants declare the semantic purpose each tool fulfils.
+ *   - `action` is the bare tool name for `tools/call`, the JSON-RPC method
+ *     otherwise. Header/body overrides available.
  */
 interface McpPdlssMapping {
-    purpose: string;
+    purpose: string | undefined;
     action: string;
     resource: string;
-    /**
-     * 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' | 'meta' | 'tool_argument' | 'default_mcp_invoke';
+    purposeSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | undefined;
     actionSource: 'header' | 'meta' | 'tool_argument' | 'transport_layer';
 }
 /**
- * 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:
+ * v2.5.0 — PDLSS field derivation for MCP requests.
+ *
+ * Purpose precedence:
+ *   - If `toolGate.purpose` is provided, it is authoritative (header/body ignored).
+ *   - Otherwise: header → body `_meta` → body `arguments` → `undefined`.
  *
- *   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>')
+ * Resource precedence:
+ *   - `toolGate.resource` if provided, else `requestPath`.
  *
- * 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.
+ * Action precedence (unchanged from v2.4.14):
+ *   - header → body `_meta` → body `arguments` → bare tool name / method.
+ *
+ * @param requestPath  The HTTP request path (e.g. '/mcp'). Required.
+ * @param toolGate     Resolved per-tool config from `toolGates`, if present.
  */
-declare function mcpToPdlss(parsed: ParsedMcpRequest, headerPurpose?: string, headerAction?: string): McpPdlssMapping;
+declare function mcpToPdlss(parsed: ParsedMcpRequest, requestPath: string, headerPurpose?: string, headerAction?: string, toolGate?: {
+    purpose?: string;
+    resource?: string;
+}): McpPdlssMapping;
 /**
  * Recommended minimum access level per method type. The MCP middleware uses
  * this to split low-risk handshake / introspection traffic from high-risk
@@ -200,10 +185,9 @@ declare function mcpRiskTier(parsed: ParsedMcpRequest): AccessLevel;
  *       from `tools/call start_checkout` (high risk). This middleware peels
  *       the JSON-RPC body and applies a per-method risk tier.
  *
- *   (b) **PDLSS mapping**.  Forwards `purpose=mcp_invoke`,
- *       `action=method[:tool]`, `resource=mcp:tool/<name>` so audit traces
- *       are stable across cohort-3 partners. See `transport/mcp-server.ts`
- *       for the exact mapping.
+ *   (b) **PDLSS mapping**.  Derives purpose, action, and resource from
+ *       `toolGates` config and request context. See `transport/mcp-server.ts`
+ *       `mcpToPdlss()` for the exact mapping.
  *
  *   (c) **Inner-hop dedupe**.  Outbound responses set
  *       `X-Astra-Verified-Hop` so a downstream REST endpoint that the tool
@@ -249,13 +233,51 @@ declare global {
         }
     }
 }
+/**
+ * Extended per-tool gate with optional PDLSS purpose + resource overrides.
+ *
+ * When `purpose` is set, it is authoritative for that tool — the agent's
+ * `X-Astra-Purpose` header is ignored. This lets the merchant declare what
+ * semantic purpose each tool fulfils rather than trusting agent self-declaration.
+ *
+ * When `resource` is set, it overrides the default (`req.path`) for that
+ * tool's verify-access call — e.g. mapping `list_products` to `/api/catalog`.
+ */
+interface ToolGateConfig {
+    minAccessLevel: AccessLevel;
+    purpose?: string;
+    resource?: string;
+}
 interface McpMiddlewareOptions extends GatewayConfig {
     /**
-     * Per-tool override for the minimum access level. Tools not listed inherit
-     * the default tier from `mcpRiskTier` (`tools/call` → `'standard'`). Use
-     * for high-risk tools that demand `'full'` or low-risk read-only tools.
+     * Per-tool gating for `tools/call` invocations. Tools not listed inherit
+     * the default tier from `mcpRiskTier` (`tools/call` → `'standard'`).
+     *
+     * Accepts both the shorthand access-level string and the full object shape:
+     * ```typescript
+     * toolGates: {
+     *   browse_catalog: 'read-only',                // shorthand
+     *   list_products:  { minAccessLevel: 'none',    // full shape
+     *                     purpose: 'shopping.search',
+     *                     resource: '/api/catalog' },
+     *   start_checkout: { minAccessLevel: 'standard',
+     *                     purpose: 'shopping.purchase',
+     *                     resource: '/api/checkout/*' },
+     * }
+     * ```
+     *
+     * When `tools/call` arrives for a tool not declared in `toolGates`, the SDK
+     * falls back to a risk-tier default based on the method classification
+     * (`mcpRiskTier`). For `tools/call` the fallback is `'standard'`. Best
+     * practice: declare every tool you expose explicitly.
+     *
+     * The action axis for non-tools/call MCP methods (`tools/list`,
+     * `resources/list`, `prompts/list`, etc.) is the literal JSON-RPC method
+     * name (e.g. `'tools/list'`). Merchants gating MCP traffic by action should
+     * declare per-tool gates in `toolGates`, not endpoint-level `allowedActions`
+     * — the latter applies to REST-style action values, not MCP method strings.
      */
-    toolGates?: Record<string, AccessLevel>;
+    toolGates?: Record<string, AccessLevel | ToolGateConfig>;
     /**
      * Per-method override (e.g. tighten `tools/list` to `'read-only'` if you
      * don't want unregistered probes seeing your tool catalogue). Matches by
@@ -323,4 +345,4 @@ interface McpMiddlewareOptions extends GatewayConfig {
  */
 declare function createMcpMiddleware(options: McpMiddlewareOptions): RequestHandler;
 
-export { MCP_VERIFIED_HOP_HEADER, type McpMiddlewareOptions, type ParsedMcpRequest, createMcpMiddleware, isVerifiedHopValidFor, mcpRiskTier, mcpToPdlss, parseMcpJsonRpc, parseVerifiedHop, serializeVerifiedHop };
+export { MCP_VERIFIED_HOP_HEADER, type McpMiddlewareOptions, type ParsedMcpRequest, type ToolGateConfig, createMcpMiddleware, isVerifiedHopValidFor, mcpRiskTier, mcpToPdlss, parseMcpJsonRpc, parseVerifiedHop, serializeVerifiedHop };

package/dist/adapters/mcp.d.ts

@@ -85,7 +85,7 @@ interface ParsedMcpRequest {
      * (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'`.
+     * before mapping; final fallback at `mcpToPdlss` is `undefined`.
      */
     purposeFromBody?: string;
     /** Which body location resolved `purposeFromBody`. */
@@ -120,60 +120,45 @@ declare function parseMcpJsonRpc(body: unknown): ParsedMcpRequest | null;
 /**
  * PDLSS mapping for an MCP request. The platform's PDLSS taxonomy is
  * `purpose / action / resource`; for MCP traffic the audit-useful dimensions
- * are the JSON-RPC method and (for `tools/call`) the tool name. Doc-stable so
- * dashboards and audits can correlate consistently across cohort-3 partners.
+ * are the JSON-RPC method and (for `tools/call`) the tool name.
  *
- * Rules:
- *   - `purpose` is always `mcp_invoke` for MCP traffic — sets the high-level
- *     PDLSS bucket.
- *   - `action` is the JSON-RPC method, optionally `:tool_name` suffixed for
- *     `tools/call`. Lets PDLSS allowlist specific tools.
- *   - `resource` is `mcp:tool/<name>` for `tools/call`, `mcp:method/<method>`
- *     otherwise. Lets PDLSS scope on tool identity.
+ * v2.5.0 rules:
+ *   - `resource` defaults to the HTTP request path (e.g. `/mcp`). Per-tool
+ *     overrides via `toolGates` config let merchants map tools to specific
+ *     backend resources (e.g. `/api/catalog`).
+ *   - `purpose` defaults to `undefined` (backend evaluator applies
+ *     skip-when-undefined). Per-tool overrides via `toolGates` config let
+ *     merchants declare the semantic purpose each tool fulfils.
+ *   - `action` is the bare tool name for `tools/call`, the JSON-RPC method
+ *     otherwise. Header/body overrides available.
  */
 interface McpPdlssMapping {
-    purpose: string;
+    purpose: string | undefined;
     action: string;
     resource: string;
-    /**
-     * 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' | 'meta' | 'tool_argument' | 'default_mcp_invoke';
+    purposeSource: 'header' | 'meta' | 'tool_argument' | 'tool_gate' | undefined;
     actionSource: 'header' | 'meta' | 'tool_argument' | 'transport_layer';
 }
 /**
- * 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:
+ * v2.5.0 — PDLSS field derivation for MCP requests.
+ *
+ * Purpose precedence:
+ *   - If `toolGate.purpose` is provided, it is authoritative (header/body ignored).
+ *   - Otherwise: header → body `_meta` → body `arguments` → `undefined`.
  *
- *   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>')
+ * Resource precedence:
+ *   - `toolGate.resource` if provided, else `requestPath`.
  *
- * 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.
+ * Action precedence (unchanged from v2.4.14):
+ *   - header → body `_meta` → body `arguments` → bare tool name / method.
+ *
+ * @param requestPath  The HTTP request path (e.g. '/mcp'). Required.
+ * @param toolGate     Resolved per-tool config from `toolGates`, if present.
  */
-declare function mcpToPdlss(parsed: ParsedMcpRequest, headerPurpose?: string, headerAction?: string): McpPdlssMapping;
+declare function mcpToPdlss(parsed: ParsedMcpRequest, requestPath: string, headerPurpose?: string, headerAction?: string, toolGate?: {
+    purpose?: string;
+    resource?: string;
+}): McpPdlssMapping;
 /**
  * Recommended minimum access level per method type. The MCP middleware uses
  * this to split low-risk handshake / introspection traffic from high-risk
@@ -200,10 +185,9 @@ declare function mcpRiskTier(parsed: ParsedMcpRequest): AccessLevel;
  *       from `tools/call start_checkout` (high risk). This middleware peels
  *       the JSON-RPC body and applies a per-method risk tier.
  *
- *   (b) **PDLSS mapping**.  Forwards `purpose=mcp_invoke`,
- *       `action=method[:tool]`, `resource=mcp:tool/<name>` so audit traces
- *       are stable across cohort-3 partners. See `transport/mcp-server.ts`
- *       for the exact mapping.
+ *   (b) **PDLSS mapping**.  Derives purpose, action, and resource from
+ *       `toolGates` config and request context. See `transport/mcp-server.ts`
+ *       `mcpToPdlss()` for the exact mapping.
  *
  *   (c) **Inner-hop dedupe**.  Outbound responses set
  *       `X-Astra-Verified-Hop` so a downstream REST endpoint that the tool
@@ -249,13 +233,51 @@ declare global {
         }
     }
 }
+/**
+ * Extended per-tool gate with optional PDLSS purpose + resource overrides.
+ *
+ * When `purpose` is set, it is authoritative for that tool — the agent's
+ * `X-Astra-Purpose` header is ignored. This lets the merchant declare what
+ * semantic purpose each tool fulfils rather than trusting agent self-declaration.
+ *
+ * When `resource` is set, it overrides the default (`req.path`) for that
+ * tool's verify-access call — e.g. mapping `list_products` to `/api/catalog`.
+ */
+interface ToolGateConfig {
+    minAccessLevel: AccessLevel;
+    purpose?: string;
+    resource?: string;
+}
 interface McpMiddlewareOptions extends GatewayConfig {
     /**
-     * Per-tool override for the minimum access level. Tools not listed inherit
-     * the default tier from `mcpRiskTier` (`tools/call` → `'standard'`). Use
-     * for high-risk tools that demand `'full'` or low-risk read-only tools.
+     * Per-tool gating for `tools/call` invocations. Tools not listed inherit
+     * the default tier from `mcpRiskTier` (`tools/call` → `'standard'`).
+     *
+     * Accepts both the shorthand access-level string and the full object shape:
+     * ```typescript
+     * toolGates: {
+     *   browse_catalog: 'read-only',                // shorthand
+     *   list_products:  { minAccessLevel: 'none',    // full shape
+     *                     purpose: 'shopping.search',
+     *                     resource: '/api/catalog' },
+     *   start_checkout: { minAccessLevel: 'standard',
+     *                     purpose: 'shopping.purchase',
+     *                     resource: '/api/checkout/*' },
+     * }
+     * ```
+     *
+     * When `tools/call` arrives for a tool not declared in `toolGates`, the SDK
+     * falls back to a risk-tier default based on the method classification
+     * (`mcpRiskTier`). For `tools/call` the fallback is `'standard'`. Best
+     * practice: declare every tool you expose explicitly.
+     *
+     * The action axis for non-tools/call MCP methods (`tools/list`,
+     * `resources/list`, `prompts/list`, etc.) is the literal JSON-RPC method
+     * name (e.g. `'tools/list'`). Merchants gating MCP traffic by action should
+     * declare per-tool gates in `toolGates`, not endpoint-level `allowedActions`
+     * — the latter applies to REST-style action values, not MCP method strings.
      */
-    toolGates?: Record<string, AccessLevel>;
+    toolGates?: Record<string, AccessLevel | ToolGateConfig>;
     /**
      * Per-method override (e.g. tighten `tools/list` to `'read-only'` if you
      * don't want unregistered probes seeing your tool catalogue). Matches by
@@ -323,4 +345,4 @@ interface McpMiddlewareOptions extends GatewayConfig {
  */
 declare function createMcpMiddleware(options: McpMiddlewareOptions): RequestHandler;
 
-export { MCP_VERIFIED_HOP_HEADER, type McpMiddlewareOptions, type ParsedMcpRequest, createMcpMiddleware, isVerifiedHopValidFor, mcpRiskTier, mcpToPdlss, parseMcpJsonRpc, parseVerifiedHop, serializeVerifiedHop };
+export { MCP_VERIFIED_HOP_HEADER, type McpMiddlewareOptions, type ParsedMcpRequest, type ToolGateConfig, createMcpMiddleware, isVerifiedHopValidFor, mcpRiskTier, mcpToPdlss, parseMcpJsonRpc, parseVerifiedHop, serializeVerifiedHop };

package/dist/adapters/mcp.js

@@ -53,6 +53,65 @@ function hasMinimumAccess(actual, required) {
 // 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",
@@ -188,21 +247,22 @@ function extractCredentials(headers, query) {
   }
   return credentials;
 }
-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",
@@ -244,7 +304,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;
@@ -324,6 +384,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);
@@ -360,7 +421,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) {
@@ -383,8 +445,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
@@ -455,12 +517,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;
@@ -596,19 +658,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;
@@ -633,6 +698,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];
@@ -648,6 +716,9 @@ function dedupeFailures(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;
@@ -673,11 +744,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" };
 }
@@ -695,6 +772,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();
@@ -707,6 +788,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;
@@ -760,9 +842,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,
@@ -823,6 +913,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 = {
@@ -891,6 +988,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
+          };
+        }
         dedupeFailures(result);
         return onDenied(result, req, res);
       }