@adcp/sdk 14.0.0-beta.14 → 14.0.0-beta.15

package/dist/lib/signing/webhook-verifier.mjs

@@ -15,7 +15,8 @@ const WEBHOOK_MANDATORY_COMPONENTS = [
   "content-digest"
 ];
 async function verifyWebhookSignature(request, options) {
-  const now = options.now ? options.now() : Math.floor(Date.now() / 1e3);
+  const currentTime = options.now ?? (() => Date.now() / 1e3);
+  const now = currentTime();
   const requiredTag = options.requiredTag ?? WEBHOOK_SIGNING_TAG;
   const sigInputHeader = getHeaderValue(request.headers, "Signature-Input");
   const sigHeader = getHeaderValue(request.headers, "Signature");
@@ -56,7 +57,8 @@ async function verifyWebhookSignature(request, options) {
   validateWindow(parsedInput.params.created, parsedInput.params.expires, now);
   validateCoveredComponents(parsedInput.components);
   const canonicalWebhookTarget = validateTargetUri(request.url);
-  const jwk = await options.jwks.resolve(parsedInput.params.keyid);
+  const keyResolution = options.jwks.resolveWithMetadata ? await options.jwks.resolveWithMetadata(parsedInput.params.keyid) : { jwk: await options.jwks.resolve(parsedInput.params.keyid) };
+  const jwk = keyResolution.jwk;
   if (!jwk) {
     throw new WebhookSignatureError(
       "webhook_signature_key_unknown",
@@ -71,6 +73,9 @@ async function verifyWebhookSignature(request, options) {
       `JWKS resolver returned a JWK whose kid "${jwk.kid}" does not match requested keyid "${parsedInput.params.keyid}".`
     );
   }
+  if (keyResolution.operatorAuthorizationValidUntil !== void 0) {
+    assertDelegatedOperatorAuthorizationActive(keyResolution.operatorAuthorizationValidUntil, currentTime());
+  }
   if (jwk.adcp_use === void 0 || !jwk.key_ops?.includes("verify") || jwk.adcp_use !== "request-signing" && jwk.adcp_use !== "webhook-signing") {
     throw new WebhookSignatureError(
       "webhook_signature_key_purpose_invalid",
@@ -88,7 +93,7 @@ async function verifyWebhookSignature(request, options) {
     }
     throw err;
   }
-  const replayScope = canonicalWebhookTarget;
+  const replayScope = replayScopeForWebhook(canonicalWebhookTarget, options.replayScopeBinding);
   if (await options.replayStore.has(jwk.kid, replayScope, parsedInput.params.nonce, now)) {
     throw new WebhookSignatureError(
       "webhook_signature_replayed",
@@ -134,6 +139,9 @@ async function verifyWebhookSignature(request, options) {
       "Content-Digest header does not match recomputed body hash."
     );
   }
+  if (keyResolution.operatorAuthorizationValidUntil !== void 0) {
+    assertDelegatedOperatorAuthorizationActive(keyResolution.operatorAuthorizationValidUntil, currentTime());
+  }
   const remaining = parsedInput.params.expires - now + CLOCK_SKEW_TOLERANCE_SECONDS;
   const ttl = Math.max(remaining, MAX_SIGNATURE_WINDOW_SECONDS + CLOCK_SKEW_TOLERANCE_SECONDS);
   const insertResult = await options.replayStore.insert(jwk.kid, replayScope, parsedInput.params.nonce, ttl, now);
@@ -151,8 +159,34 @@ async function verifyWebhookSignature(request, options) {
       `Per-keyid replay cache cap exceeded on commit for keyid=${jwk.kid}.`
     );
   }
+  if (keyResolution.operatorAuthorizationValidUntil !== void 0) {
+    assertDelegatedOperatorAuthorizationActive(keyResolution.operatorAuthorizationValidUntil, currentTime());
+  }
   const agent_url = options.agentUrlForKeyid?.(jwk.kid);
-  return { status: "verified", keyid: jwk.kid, ...agent_url !== void 0 && { agent_url }, verified_at: now };
+  return {
+    status: "verified",
+    keyid: jwk.kid,
+    ...agent_url !== void 0 && { agent_url },
+    // Keep the established whole-second credential timestamp while using the
+    // fractional clock above for exact authorization-expiry enforcement.
+    verified_at: Math.floor(now)
+  };
+}
+function assertDelegatedOperatorAuthorizationActive(validUntil, now) {
+  if (validUntil !== void 0 && (!Number.isFinite(validUntil) || now >= validUntil)) {
+    throw new WebhookSignatureError(
+      "webhook_signature_key_unknown",
+      7,
+      "The signing key is no longer authorized for this webhook registration."
+    );
+  }
+}
+function replayScopeForWebhook(canonicalTarget, binding) {
+  if (binding === void 0) return canonicalTarget;
+  if (binding.length === 0 || binding.length > 1024 || binding.includes("\0")) {
+    throw new TypeError("replayScopeBinding must be a non-empty string of at most 1024 characters without NUL.");
+  }
+  return JSON.stringify([canonicalTarget, binding]);
 }
 function requireParams(parsed) {
   const required = ["created", "expires", "nonce", "keyid", "alg", "tag"];

package/dist/lib/testing/client.d.mts

@@ -94,6 +94,7 @@ export declare function discoverAgentProfile(client: TestClient, signal?: AbortS
 schemaAdcpVersion?: string): Promise<{
     profile: AgentProfile;
     step: TestStepResult;
+    caughtError?: unknown;
 }>;
 /**
  * Discover what channels, pricing models, formats the agent supports

package/dist/lib/testing/client.d.ts

@@ -94,6 +94,7 @@ export declare function discoverAgentProfile(client: TestClient, signal?: AbortS
 schemaAdcpVersion?: string): Promise<{
     profile: AgentProfile;
     step: TestStepResult;
+    caughtError?: unknown;
 }>;
 /**
  * Discover what channels, pricing models, formats the agent supports

package/dist/lib/testing/client.js

@@ -359,7 +359,11 @@ function describeVersionUnsupported(result, requestedVersion) {
   return `VERSION_UNSUPPORTED: ${requestedText}${supportedText}`;
 }
 async function discoverAgentProfile(client, signal, schemaAdcpVersion) {
-  const { result: agentInfo, step } = await runStep(
+  const {
+    result: agentInfo,
+    step,
+    caughtError
+  } = await runStep(
     "Discover agent capabilities",
     "getAgentInfo",
     () => raceWithSignal(client.getAgentInfo({ signal }), signal)
@@ -425,7 +429,7 @@ async function discoverAgentProfile(client, signal, schemaAdcpVersion) {
     }
   }
   seedTestClientSigningCapability(client, profile, schemaAdcpVersion);
-  return { profile, step };
+  return { profile, step, ...caughtError !== void 0 && { caughtError } };
 }
 async function discoverAgentCapabilities(client, profile, options) {
   const steps = [];

package/dist/lib/testing/client.mjs

@@ -321,7 +321,11 @@ function describeVersionUnsupported(result, requestedVersion) {
   return `VERSION_UNSUPPORTED: ${requestedText}${supportedText}`;
 }
 async function discoverAgentProfile(client, signal, schemaAdcpVersion) {
-  const { result: agentInfo, step } = await runStep(
+  const {
+    result: agentInfo,
+    step,
+    caughtError
+  } = await runStep(
     "Discover agent capabilities",
     "getAgentInfo",
     () => raceWithSignal(client.getAgentInfo({ signal }), signal)
@@ -387,7 +391,7 @@ async function discoverAgentProfile(client, signal, schemaAdcpVersion) {
     }
   }
   seedTestClientSigningCapability(client, profile, schemaAdcpVersion);
-  return { profile, step };
+  return { profile, step, ...caughtError !== void 0 && { caughtError } };
 }
 async function discoverAgentCapabilities(client, profile, options) {
   const steps = [];

package/dist/lib/testing/compliance/comply.d.mts

@@ -139,10 +139,10 @@ export declare function rotateStoryboardsForOffset<T>(items: readonly T[], offse
  * Centralized so the "run security.yaml against 401-happy agents" path and
  * the fallback "unreachable result" path share the same truth.
  *
- * Exported for direct unit tests of the keyword classifier — callers inside
+ * Exported for direct unit tests of the auth classifier — callers inside
  * the library should go through `comply()`, not this helper.
  */
-export declare function detectAuthRejection(agentUrl: string, errorMsg: string | undefined, signal?: AbortSignal, fetchFn?: typeof fetch): Promise<{
+export declare function detectAuthRejection(agentUrl: string, errorMsg: string | undefined, signal?: AbortSignal, fetchFn?: typeof fetch, caughtError?: unknown, allowPrivateIp?: boolean): Promise<{
     isAuth: boolean;
     observations: AdvisoryObservation[];
 }>;

package/dist/lib/testing/compliance/comply.d.ts

@@ -139,10 +139,10 @@ export declare function rotateStoryboardsForOffset<T>(items: readonly T[], offse
  * Centralized so the "run security.yaml against 401-happy agents" path and
  * the fallback "unreachable result" path share the same truth.
  *
- * Exported for direct unit tests of the keyword classifier — callers inside
+ * Exported for direct unit tests of the auth classifier — callers inside
  * the library should go through `comply()`, not this helper.
  */
-export declare function detectAuthRejection(agentUrl: string, errorMsg: string | undefined, signal?: AbortSignal, fetchFn?: typeof fetch): Promise<{
+export declare function detectAuthRejection(agentUrl: string, errorMsg: string | undefined, signal?: AbortSignal, fetchFn?: typeof fetch, caughtError?: unknown, allowPrivateIp?: boolean): Promise<{
     isAuth: boolean;
     observations: AdvisoryObservation[];
 }>;

package/dist/lib/testing/compliance/comply.js

@@ -1,9 +1,7 @@
 "use strict";
-var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -17,14 +15,6 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var comply_exports = {};
 __export(comply_exports, {
@@ -55,7 +45,8 @@ var import_schema_loader = require('../../validation/schema-loader.js');
 var import_oauth_metadata_graph = require('../storyboard/oauth-metadata-graph/index.js');
 var import_version = require('../../version.js');
 var import_validations = require('../storyboard/validations.js');
-var import_address_guards = require('../../net/address-guards.js');
+var import_agent_transport_fetch = require('../../net/agent-transport-fetch.js');
+var import_authorization_required = require('../../auth/oauth/authorization-required.js');
 var import_functional_dispatch = require('../storyboard/request-signing/functional-dispatch.js');
 (0, import_default_invariants.registerDefaultInvariants)();
 const TRACK_ORDER = [
@@ -816,11 +807,11 @@ async function complyImpl(agentUrl, options) {
     const allObservations = [];
     let discoveryOptions = effectiveOptions;
     let discoveryClient = (0, import_client.createTestClient)(agentUrl, effectiveOptions.protocol ?? "mcp", discoveryOptions);
-    let { profile, step: profileStep } = await (0, import_client.discoverAgentProfile)(
-      discoveryClient,
-      signal,
-      complianceIndex.adcp_version
-    );
+    let {
+      profile,
+      step: profileStep,
+      caughtError: profileCaughtError
+    } = await (0, import_client.discoverAgentProfile)(discoveryClient, signal, complianceIndex.adcp_version);
     if (testOptions.versionEnvelope === void 0 && profile.tools.includes("get_adcp_capabilities") && profile.raw_capabilities === void 0 && !profileStep.error?.startsWith("VERSION_UNSUPPORTED:")) {
       const legacyDiscoveryOptions = { ...effectiveOptions, versionEnvelope: "major-only" };
       const legacyDiscoveryClient = (0, import_client.createTestClient)(
@@ -834,6 +825,7 @@ async function complyImpl(agentUrl, options) {
         discoveryClient = legacyDiscoveryClient;
         profile = legacyDiscovery.profile;
         profileStep = legacyDiscovery.step;
+        profileCaughtError = legacyDiscovery.caughtError;
       }
     }
     effectiveOptions = applyNegotiatedComplianceVersionOptions(profile, effectiveOptions, {
@@ -889,7 +881,14 @@ async function complyImpl(agentUrl, options) {
     }
     if (!profileStep.passed) {
       const isVersionUnsupported = profileStep.error?.startsWith("VERSION_UNSUPPORTED:") === true;
-      const authCheck = isVersionUnsupported ? { isAuth: false, observations: [] } : await detectAuthRejection(agentUrl, profileStep.error, signal, effectiveOptions.transport?.trustedFetchFn);
+      const authCheck = isVersionUnsupported ? { isAuth: false, observations: [] } : await detectAuthRejection(
+        agentUrl,
+        profileStep.error,
+        signal,
+        effectiveOptions.transport?.trustedFetchFn,
+        profileCaughtError,
+        effectiveOptions.transport?.allowPrivateIp
+      );
       if (authCheck.isAuth) {
         const degraded = { name: profile.name || "Unknown (auth required)", tools: [] };
         const candidate = explicitStoryboards?.length ? resolveExplicitStoryboards(explicitStoryboards, resolveOptions) : resolveFromCapabilities(degraded, resolveOptions).storyboards;
@@ -917,6 +916,7 @@ async function complyImpl(agentUrl, options) {
         start,
         effectiveOptions,
         complianceIndex.adcp_version,
+        profileCaughtError,
         signal
       );
     }
@@ -1106,17 +1106,22 @@ function buildComplyTimeoutBudgetObservation(timeout_ms, storyboardsExecuted, st
     source: { kind: "profile", code: "timeout-budget-exceeded" }
   };
 }
-async function detectAuthRejection(agentUrl, errorMsg, signal, fetchFn) {
+async function detectAuthRejection(agentUrl, errorMsg, signal, fetchFn, caughtError, allowPrivateIp) {
   const err = errorMsg || "Unknown error";
   const observations = [];
   const lower = err.toLowerCase();
-  const hasOAuthSignal = lower.includes("oauth authorization") || lower.includes("requires oauth") || lower.includes("requires authorization") || lower.includes("oauth flow") || lower.includes("oauthflowhandler") || lower.includes("needsauthorizationerror") || lower.includes("www-authenticate") || lower.includes("bearer realm");
-  const isExplicitAuthError = lower.includes("401") || lower.includes("unauthorized") || lower.includes("authentication") || hasOAuthSignal || lower.includes("jws") || lower.includes("jwt") || lower.includes("signature verification");
+  const hasLegacyAuthSignal = lower.includes("oauth authorization") || lower.includes("requires oauth") || lower.includes("requires authorization") || lower.includes("oauth flow") || lower.includes("oauthflowhandler") || lower.includes("needsauthorizationerror") || lower.includes("www-authenticate") || lower.includes("bearer realm");
+  const hasValidatedOAuthSignal = caughtError instanceof import_authorization_required.NeedsAuthorizationError && (0, import_authorization_required.hasValidatedMcpAuthorizationRequirements)(caughtError.requirements, agentUrl);
+  const isExplicitAuthError = lower.includes("401") || lower.includes("unauthorized") || lower.includes("authentication") || hasLegacyAuthSignal || hasValidatedOAuthSignal || lower.includes("jws") || lower.includes("jwt") || lower.includes("signature verification");
   let isAuth = isExplicitAuthError;
   if (!isAuth) {
     try {
       const probeSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(5e3)]) : AbortSignal.timeout(5e3);
-      const probe = await (fetchFn ?? fetch)(agentUrl, {
+      const transportFetch = (0, import_agent_transport_fetch.createAgentTransportFetch)(agentUrl, {
+        trustedFetchFn: fetchFn,
+        allowPrivateIp: allowPrivateIp ?? false
+      });
+      const probe = await transportFetch(agentUrl, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         redirect: "manual",
@@ -1127,20 +1132,18 @@ async function detectAuthRejection(agentUrl, errorMsg, signal, fetchFn) {
     }
   }
   if (isAuth) {
-    const { discoverOAuthMetadata } = await import("../../auth/oauth/discovery.js");
-    const oauthMeta = await discoverOAuthMetadata(agentUrl, {
-      trustedFetchFn: fetchFn,
-      allowPrivateIp: (0, import_address_guards.isLikelyPrivateUrl)(agentUrl)
-    });
-    const looksOAuth = oauthMeta !== null || hasOAuthSignal;
+    const oauthRequirements = hasValidatedOAuthSignal ? caughtError.requirements : void 0;
+    const looksOAuth = oauthRequirements !== void 0;
     if (looksOAuth) {
-      const issuer = oauthMeta?.issuer ? fenceAgentText((0, import_oauth_metadata_graph.redactOAuthUrlForOutput)(oauthMeta.issuer), 200) : "(unknown)";
+      const issuer = oauthRequirements?.authorizationServer ? fenceAgentText((0, import_oauth_metadata_graph.redactOAuthUrlForOutput)(oauthRequirements.authorizationServer), 200) : "(unknown)";
       const safeAgentUrl = (0, import_oauth_metadata_graph.redactOAuthUrlForOutput)(agentUrl);
       observations.push({
         category: "auth",
         severity: "error",
         message: `Agent requires OAuth (issuer: ${issuer}). Inline: adcp storyboard run ${safeAgentUrl} --oauth (requires a saved alias). Save once: adcp --save-auth <alias> ${safeAgentUrl} --oauth.`,
-        ...oauthMeta?.issuer && { evidence: { oauth_issuer: (0, import_oauth_metadata_graph.redactOAuthUrlForOutput)(oauthMeta.issuer) } },
+        ...oauthRequirements?.authorizationServer && {
+          evidence: { oauth_issuer: (0, import_oauth_metadata_graph.redactOAuthUrlForOutput)(oauthRequirements.authorizationServer) }
+        },
         source: { kind: "probe", code: "auth-oauth-required" }
       });
     } else {
@@ -1256,9 +1259,16 @@ async function runWithDegradedProfile(agentUrl, profile, storyboards, options, e
     notices: []
   };
 }
-async function buildUnreachableResult(agentUrl, profile, errorMsg, start, effectiveOptions, adcpVersion, signal) {
+async function buildUnreachableResult(agentUrl, profile, errorMsg, start, effectiveOptions, adcpVersion, caughtError, signal) {
   const isVersionUnsupported = errorMsg?.startsWith("VERSION_UNSUPPORTED:") === true;
-  const { isAuth, observations } = isVersionUnsupported ? { isAuth: false, observations: [] } : await detectAuthRejection(agentUrl, errorMsg, signal, effectiveOptions.transport?.trustedFetchFn);
+  const { isAuth, observations } = isVersionUnsupported ? { isAuth: false, observations: [] } : await detectAuthRejection(
+    agentUrl,
+    errorMsg,
+    signal,
+    effectiveOptions.transport?.trustedFetchFn,
+    caughtError,
+    effectiveOptions.transport?.allowPrivateIp
+  );
   const err = (0, import_oauth_metadata_graph.redactOAuthUrlsInText)(errorMsg || "Unknown error");
   const headline = isAuth ? `Authentication required` : `Agent unreachable \u2014 ${err}`;
   return {

package/dist/lib/testing/compliance/comply.mjs

@@ -21,7 +21,11 @@ import { withExternalSchemaRoot } from "../../validation/schema-loader.mjs";
 import { redactOAuthUrlForOutput, redactOAuthUrlsInText } from "../storyboard/oauth-metadata-graph/index.mjs";
 import { LIBRARY_VERSION } from "../../version.mjs";
 import { validationFailsStep } from "../storyboard/validations.mjs";
-import { isLikelyPrivateUrl } from "../../net/address-guards.mjs";
+import { createAgentTransportFetch } from "../../net/agent-transport-fetch.mjs";
+import {
+  hasValidatedMcpAuthorizationRequirements,
+  NeedsAuthorizationError
+} from "../../auth/oauth/authorization-required.mjs";
 import { applyFunctionalRequestSigning } from "../storyboard/request-signing/functional-dispatch.mjs";
 const TRACK_ORDER = [
   "core",
@@ -781,11 +785,11 @@ async function complyImpl(agentUrl, options) {
     const allObservations = [];
     let discoveryOptions = effectiveOptions;
     let discoveryClient = createTestClient(agentUrl, effectiveOptions.protocol ?? "mcp", discoveryOptions);
-    let { profile, step: profileStep } = await discoverAgentProfile(
-      discoveryClient,
-      signal,
-      complianceIndex.adcp_version
-    );
+    let {
+      profile,
+      step: profileStep,
+      caughtError: profileCaughtError
+    } = await discoverAgentProfile(discoveryClient, signal, complianceIndex.adcp_version);
     if (testOptions.versionEnvelope === void 0 && profile.tools.includes("get_adcp_capabilities") && profile.raw_capabilities === void 0 && !profileStep.error?.startsWith("VERSION_UNSUPPORTED:")) {
       const legacyDiscoveryOptions = { ...effectiveOptions, versionEnvelope: "major-only" };
       const legacyDiscoveryClient = createTestClient(
@@ -799,6 +803,7 @@ async function complyImpl(agentUrl, options) {
         discoveryClient = legacyDiscoveryClient;
         profile = legacyDiscovery.profile;
         profileStep = legacyDiscovery.step;
+        profileCaughtError = legacyDiscovery.caughtError;
       }
     }
     effectiveOptions = applyNegotiatedComplianceVersionOptions(profile, effectiveOptions, {
@@ -854,7 +859,14 @@ async function complyImpl(agentUrl, options) {
     }
     if (!profileStep.passed) {
       const isVersionUnsupported = profileStep.error?.startsWith("VERSION_UNSUPPORTED:") === true;
-      const authCheck = isVersionUnsupported ? { isAuth: false, observations: [] } : await detectAuthRejection(agentUrl, profileStep.error, signal, effectiveOptions.transport?.trustedFetchFn);
+      const authCheck = isVersionUnsupported ? { isAuth: false, observations: [] } : await detectAuthRejection(
+        agentUrl,
+        profileStep.error,
+        signal,
+        effectiveOptions.transport?.trustedFetchFn,
+        profileCaughtError,
+        effectiveOptions.transport?.allowPrivateIp
+      );
       if (authCheck.isAuth) {
         const degraded = { name: profile.name || "Unknown (auth required)", tools: [] };
         const candidate = explicitStoryboards?.length ? resolveExplicitStoryboards(explicitStoryboards, resolveOptions) : resolveFromCapabilities(degraded, resolveOptions).storyboards;
@@ -882,6 +894,7 @@ async function complyImpl(agentUrl, options) {
         start,
         effectiveOptions,
         complianceIndex.adcp_version,
+        profileCaughtError,
         signal
       );
     }
@@ -1071,17 +1084,22 @@ function buildComplyTimeoutBudgetObservation(timeout_ms, storyboardsExecuted, st
     source: { kind: "profile", code: "timeout-budget-exceeded" }
   };
 }
-async function detectAuthRejection(agentUrl, errorMsg, signal, fetchFn) {
+async function detectAuthRejection(agentUrl, errorMsg, signal, fetchFn, caughtError, allowPrivateIp) {
   const err = errorMsg || "Unknown error";
   const observations = [];
   const lower = err.toLowerCase();
-  const hasOAuthSignal = lower.includes("oauth authorization") || lower.includes("requires oauth") || lower.includes("requires authorization") || lower.includes("oauth flow") || lower.includes("oauthflowhandler") || lower.includes("needsauthorizationerror") || lower.includes("www-authenticate") || lower.includes("bearer realm");
-  const isExplicitAuthError = lower.includes("401") || lower.includes("unauthorized") || lower.includes("authentication") || hasOAuthSignal || lower.includes("jws") || lower.includes("jwt") || lower.includes("signature verification");
+  const hasLegacyAuthSignal = lower.includes("oauth authorization") || lower.includes("requires oauth") || lower.includes("requires authorization") || lower.includes("oauth flow") || lower.includes("oauthflowhandler") || lower.includes("needsauthorizationerror") || lower.includes("www-authenticate") || lower.includes("bearer realm");
+  const hasValidatedOAuthSignal = caughtError instanceof NeedsAuthorizationError && hasValidatedMcpAuthorizationRequirements(caughtError.requirements, agentUrl);
+  const isExplicitAuthError = lower.includes("401") || lower.includes("unauthorized") || lower.includes("authentication") || hasLegacyAuthSignal || hasValidatedOAuthSignal || lower.includes("jws") || lower.includes("jwt") || lower.includes("signature verification");
   let isAuth = isExplicitAuthError;
   if (!isAuth) {
     try {
       const probeSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(5e3)]) : AbortSignal.timeout(5e3);
-      const probe = await (fetchFn ?? fetch)(agentUrl, {
+      const transportFetch = createAgentTransportFetch(agentUrl, {
+        trustedFetchFn: fetchFn,
+        allowPrivateIp: allowPrivateIp ?? false
+      });
+      const probe = await transportFetch(agentUrl, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         redirect: "manual",
@@ -1092,20 +1110,18 @@ async function detectAuthRejection(agentUrl, errorMsg, signal, fetchFn) {
     }
   }
   if (isAuth) {
-    const { discoverOAuthMetadata } = await import("../../auth/oauth/discovery.mjs");
-    const oauthMeta = await discoverOAuthMetadata(agentUrl, {
-      trustedFetchFn: fetchFn,
-      allowPrivateIp: isLikelyPrivateUrl(agentUrl)
-    });
-    const looksOAuth = oauthMeta !== null || hasOAuthSignal;
+    const oauthRequirements = hasValidatedOAuthSignal ? caughtError.requirements : void 0;
+    const looksOAuth = oauthRequirements !== void 0;
     if (looksOAuth) {
-      const issuer = oauthMeta?.issuer ? fenceAgentText(redactOAuthUrlForOutput(oauthMeta.issuer), 200) : "(unknown)";
+      const issuer = oauthRequirements?.authorizationServer ? fenceAgentText(redactOAuthUrlForOutput(oauthRequirements.authorizationServer), 200) : "(unknown)";
       const safeAgentUrl = redactOAuthUrlForOutput(agentUrl);
       observations.push({
         category: "auth",
         severity: "error",
         message: `Agent requires OAuth (issuer: ${issuer}). Inline: adcp storyboard run ${safeAgentUrl} --oauth (requires a saved alias). Save once: adcp --save-auth <alias> ${safeAgentUrl} --oauth.`,
-        ...oauthMeta?.issuer && { evidence: { oauth_issuer: redactOAuthUrlForOutput(oauthMeta.issuer) } },
+        ...oauthRequirements?.authorizationServer && {
+          evidence: { oauth_issuer: redactOAuthUrlForOutput(oauthRequirements.authorizationServer) }
+        },
         source: { kind: "probe", code: "auth-oauth-required" }
       });
     } else {
@@ -1221,9 +1237,16 @@ async function runWithDegradedProfile(agentUrl, profile, storyboards, options, e
     notices: []
   };
 }
-async function buildUnreachableResult(agentUrl, profile, errorMsg, start, effectiveOptions, adcpVersion, signal) {
+async function buildUnreachableResult(agentUrl, profile, errorMsg, start, effectiveOptions, adcpVersion, caughtError, signal) {
   const isVersionUnsupported = errorMsg?.startsWith("VERSION_UNSUPPORTED:") === true;
-  const { isAuth, observations } = isVersionUnsupported ? { isAuth: false, observations: [] } : await detectAuthRejection(agentUrl, errorMsg, signal, effectiveOptions.transport?.trustedFetchFn);
+  const { isAuth, observations } = isVersionUnsupported ? { isAuth: false, observations: [] } : await detectAuthRejection(
+    agentUrl,
+    errorMsg,
+    signal,
+    effectiveOptions.transport?.trustedFetchFn,
+    caughtError,
+    effectiveOptions.transport?.allowPrivateIp
+  );
   const err = redactOAuthUrlsInText(errorMsg || "Unknown error");
   const headline = isAuth ? `Authentication required` : `Agent unreachable \u2014 ${err}`;
   return {

package/dist/lib/testing/storyboard/oauth-metadata-graph/grader.d.mts

@@ -1,3 +1,4 @@
+export { buildProtectedResourceMetadataUrl, normalizeOAuthResourceForComparison, } from '../../../auth/oauth/resource-url.mjs';
 import type { OAuthMetadataGraphGrade } from './types.mjs';
 export interface GradeOAuthMetadataGraphOptions {
     /** Explicit local-development opt-in. Production grading remains HTTPS-only. */
@@ -6,16 +7,9 @@ export interface GradeOAuthMetadataGraphOptions {
     /** Trusted scoped fetch supplied by a hosted runner; it must enforce peer-address binding. */
     trustedFetchFn?: typeof fetch;
 }
-/**
- * Shared RFC 9728 comparison semantics used by security.yaml and oauth_setup.
- * Only scheme and host are case-folded and default ports are elided. The
- * path, query, fragment, userinfo, and trailing slash remain significant.
- */
-export declare function normalizeOAuthResourceForComparison(value: string): string;
 /** Redact sensitive URL components before including a URL in a report. */
 export declare function redactOAuthUrlForOutput(value: string): string;
 /** Redact absolute URLs embedded in diagnostic text before report serialization. */
 export declare function redactOAuthUrlsInText(value: string): string;
-export declare function buildProtectedResourceMetadataUrl(agentUrl: string): string;
 export declare function buildAuthorizationServerMetadataUrl(issuer: string): string;
 export declare function gradeOAuthMetadataGraph(agentUrl: string, options?: GradeOAuthMetadataGraphOptions): Promise<OAuthMetadataGraphGrade>;

package/dist/lib/testing/storyboard/oauth-metadata-graph/grader.d.ts

@@ -1,3 +1,4 @@
+export { buildProtectedResourceMetadataUrl, normalizeOAuthResourceForComparison, } from '../../../auth/oauth/resource-url';
 import type { OAuthMetadataGraphGrade } from './types';
 export interface GradeOAuthMetadataGraphOptions {
     /** Explicit local-development opt-in. Production grading remains HTTPS-only. */
@@ -6,16 +7,9 @@ export interface GradeOAuthMetadataGraphOptions {
     /** Trusted scoped fetch supplied by a hosted runner; it must enforce peer-address binding. */
     trustedFetchFn?: typeof fetch;
 }
-/**
- * Shared RFC 9728 comparison semantics used by security.yaml and oauth_setup.
- * Only scheme and host are case-folded and default ports are elided. The
- * path, query, fragment, userinfo, and trailing slash remain significant.
- */
-export declare function normalizeOAuthResourceForComparison(value: string): string;
 /** Redact sensitive URL components before including a URL in a report. */
 export declare function redactOAuthUrlForOutput(value: string): string;
 /** Redact absolute URLs embedded in diagnostic text before report serialization. */
 export declare function redactOAuthUrlsInText(value: string): string;
-export declare function buildProtectedResourceMetadataUrl(agentUrl: string): string;
 export declare function buildAuthorizationServerMetadataUrl(issuer: string): string;
 export declare function gradeOAuthMetadataGraph(agentUrl: string, options?: GradeOAuthMetadataGraphOptions): Promise<OAuthMetadataGraphGrade>;

package/dist/lib/testing/storyboard/oauth-metadata-graph/grader.js

@@ -19,16 +19,18 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var grader_exports = {};
 __export(grader_exports, {
   buildAuthorizationServerMetadataUrl: () => buildAuthorizationServerMetadataUrl,
-  buildProtectedResourceMetadataUrl: () => buildProtectedResourceMetadataUrl,
+  buildProtectedResourceMetadataUrl: () => import_resource_url.buildProtectedResourceMetadataUrl,
   gradeOAuthMetadataGraph: () => gradeOAuthMetadataGraph,
   gradeOAuthMetadataGraphWithTransport: () => gradeOAuthMetadataGraphWithTransport,
-  normalizeOAuthResourceForComparison: () => normalizeOAuthResourceForComparison,
+  normalizeOAuthResourceForComparison: () => import_resource_url.normalizeOAuthResourceForComparison,
   redactOAuthUrlForOutput: () => redactOAuthUrlForOutput,
   redactOAuthUrlsInText: () => redactOAuthUrlsInText
 });
 module.exports = __toCommonJS(grader_exports);
 var import_address_guards = require('../../../net/address-guards.js');
 var import_ssrf_fetch = require('../../../net/ssrf-fetch.js');
+var import_resource_url = require('../../../auth/oauth/resource-url.js');
+var import_resource_url2 = require('../../../auth/oauth/resource-url.js');
 const LIMITS = Object.freeze({
   authorizationServers: 16,
   uniqueUrls: 64,
@@ -53,40 +55,6 @@ const DIAGNOSTIC_ORDER = Object.freeze([
   "oauth_endpoint_unreachable",
   "oauth_jwks_unavailable"
 ]);
-function normalizeOAuthResourceForComparison(value) {
-  const match = /^([A-Za-z][A-Za-z\d+.-]*):\/\/([^/?#]*)([\s\S]*)$/.exec(value);
-  if (!match) return value;
-  const scheme = match[1].toLowerCase();
-  const authority = match[2];
-  const remainder = match[3];
-  const at = authority.lastIndexOf("@");
-  const userinfo = at >= 0 ? authority.slice(0, at + 1) : "";
-  const hostAndPort = at >= 0 ? authority.slice(at + 1) : authority;
-  let host;
-  let port = "";
-  if (hostAndPort.startsWith("[")) {
-    const bracket = hostAndPort.indexOf("]");
-    if (bracket < 0) return value;
-    host = hostAndPort.slice(0, bracket + 1).toLowerCase();
-    const suffix = hostAndPort.slice(bracket + 1);
-    if (suffix && !/^:\d+$/.test(suffix)) return value;
-    port = suffix.slice(1);
-  } else {
-    const colon = hostAndPort.lastIndexOf(":");
-    if (colon >= 0) {
-      const suffix = hostAndPort.slice(colon + 1);
-      if (!/^\d+$/.test(suffix)) return value;
-      host = hostAndPort.slice(0, colon).toLowerCase();
-      port = suffix;
-    } else {
-      host = hostAndPort.toLowerCase();
-    }
-  }
-  if (!host) return value;
-  const defaultPort = scheme === "https" ? "443" : scheme === "http" ? "80" : void 0;
-  const renderedPort = port && port !== defaultPort ? `:${port}` : "";
-  return `${scheme}://${userinfo}${host}${renderedPort}${remainder}`;
-}
 function redactOAuthUrlForOutput(value) {
   try {
     const u = new URL(value);
@@ -104,10 +72,6 @@ function redactOAuthUrlForOutput(value) {
 function redactOAuthUrlsInText(value) {
   return value.replace(/https?:\/\/[^\s"'<>]+/gi, (url) => redactOAuthUrlForOutput(url));
 }
-function buildProtectedResourceMetadataUrl(agentUrl) {
-  const u = new URL(agentUrl);
-  return `${u.origin}/.well-known/oauth-protected-resource${u.pathname}`;
-}
 function buildAuthorizationServerMetadataUrl(issuer) {
   const u = new URL(issuer);
   const issuerPath = u.pathname === "/" ? "" : u.pathname;
@@ -132,7 +96,7 @@ async function gradeOAuthMetadataGraphWithTransport(agentUrl, options = {}) {
   const findings = [];
   let protectedResourceUrl;
   try {
-    protectedResourceUrl = buildProtectedResourceMetadataUrl(agentUrl);
+    protectedResourceUrl = (0, import_resource_url2.buildProtectedResourceMetadataUrl)(agentUrl);
   } catch {
     protectedResourceUrl = redactOAuthUrlForOutput(agentUrl);
     findings.push(finding("oauth_protected_resource_metadata_invalid", "Agent URL is not an absolute URL."));
@@ -177,7 +141,7 @@ async function gradeOAuthMetadataGraphWithTransport(agentUrl, options = {}) {
         "resource"
       )
     );
-  } else if (normalizeOAuthResourceForComparison(resource) !== normalizeOAuthResourceForComparison(agentUrl)) {
+  } else if ((0, import_resource_url2.normalizeOAuthResourceForComparison)(resource) !== (0, import_resource_url2.normalizeOAuthResourceForComparison)(agentUrl)) {
     findings.push(
       finding(
         "oauth_resource_mismatch",