fix(auth): pass the challenge's resource_metadata URL to SDK auth()

An RFC 9728 `WWW-Authenticate: Bearer resource_metadata="…"` challenge was
parsed and then dropped by the normalized `AuthChallenge`, so every
challenge-driven `mcpAuth()` call ran discovery without it and probed
locations derived from the MCP server URL instead. OAuth failed outright
against any server whose metadata document lives off the well-known path.

The SDK handles this correctly inside its own transports, but the Inspector
never reaches that path — it intercepts the 401 and drives `auth()` itself
to capture the authorization URL and run the step-up scope union.

Carry the advertised URL on `AuthChallenge` as a string (it crosses the web
client's remote-backend boundary as JSON), convert it at the OAuth boundary,
and pass it to the standard challenge leg, the forced step-up leg, and CIMD
pre-registration — which runs before `auth()` and did its own discovery. A
malformed value is ignored rather than surfaced, matching the SDK's parser.
The callback leg needs nothing: SDK `auth()` persists the URL in its
discovery state.

Adds an `oauth.resourceMetadataPath` test-server mode that moves the
document off the well-known path entirely, so the integration test proves
discovery genuinely fails without the fix.

Closes #2071

Signed-off-by: cliffhall <cliff@futurescale.com>

core/auth/challenge.ts

@@ -26,6 +26,17 @@ export interface AuthChallenge {
   /** Resource authorization server audience when known. */
   audience?: string;
 
+  /**
+   * RFC 9728 `resource_metadata` advertised by the `WWW-Authenticate` challenge.
+   *
+   * Kept as a string so the challenge stays serializable — it crosses the web
+   * client's remote-backend boundary as JSON. Converted to a `URL` (and
+   * discarded if malformed) at the OAuth boundary, where it is handed to the
+   * SDK as `resourceMetadataUrl` so protected-resource discovery targets the
+   * advertised document instead of a location derived from the MCP server URL.
+   */
+  resourceMetadataUrl?: string;
+
   /** Optional human-readable detail from server or SDK (for UI, not parsing). */
   message?: string;
 
@@ -193,6 +204,30 @@ export function parseWwwAuthenticateBearer(
   };
 }
 
+/**
+ * Convert a challenge's advertised RFC 9728 `resource_metadata` value into the
+ * `URL` the SDK's `auth()` takes as `resourceMetadataUrl`.
+ *
+ * A malformed value is ignored rather than surfaced, matching the SDK's own
+ * `WWW-Authenticate` parser (`extractWWWAuthenticateParams`), which drops a
+ * value `new URL()` rejects. Discovery then falls back to the default
+ * RFC 9728 locations derived from the MCP server URL — the pre-existing
+ * behavior — instead of failing the whole authorization on a bad header.
+ */
+export function challengeResourceMetadataUrl(
+  challenge: Pick<AuthChallenge, "resourceMetadataUrl">,
+): URL | undefined {
+  const value = challenge.resourceMetadataUrl?.trim();
+  if (!value) {
+    return undefined;
+  }
+  try {
+    return new URL(value);
+  } catch {
+    return undefined;
+  }
+}
+
 /** Split an OAuth scope string into individual scopes (space-separated). */
 export function parseScopeString(scope: string | undefined): string[] {
   if (!scope?.trim()) {
@@ -275,6 +310,9 @@ export function parseAuthChallengeFromResponse(
   return {
     reason: reasonFromHttpResponse(status, bearer),
     ...(requiredScopes.length > 0 ? { requiredScopes } : {}),
+    ...(bearer.resourceMetadata
+      ? { resourceMetadataUrl: bearer.resourceMetadata }
+      : {}),
     ...(bearer.errorDescription ? { message: bearer.errorDescription } : {}),
     ...(context ? { context } : {}),
     raw: {
@@ -337,6 +375,9 @@ export function parseAuthChallengeFromError(
   return {
     reason: reasonFromHttpResponse(status, bearer),
     ...(requiredScopes.length > 0 ? { requiredScopes } : {}),
+    ...(bearer.resourceMetadata
+      ? { resourceMetadataUrl: bearer.resourceMetadata }
+      : {}),
     ...(context ? { context } : {}),
     raw: {
       httpStatus: status,

core/auth/cimd.ts

@@ -14,11 +14,18 @@ import type { BaseOAuthClientProvider } from "./providers.js";
  * accepts an already-stored `client_id` (including `http://` URLs used by local
  * dev/test metadata servers). Production CIMD metadata documents should still
  * use HTTPS per SEP-991.
+ *
+ * `resourceMetadataUrl` is the RFC 9728 document advertised by the
+ * `WWW-Authenticate` challenge, when the caller has one. It matters here and
+ * not only in `auth()`: this runs *before* SDK `auth()`, so without it the
+ * pre-registration probe would do its own default-location discovery and miss
+ * a document served from a non-default path (#2071).
  */
 export async function ensureCimdClientRegistration(params: {
   serverUrl: string;
   provider: BaseOAuthClientProvider;
   fetchFn?: typeof fetch;
+  resourceMetadataUrl?: URL;
 }): Promise<void> {
   const clientMetadataUrl = params.provider.clientMetadataUrl?.trim();
   if (!clientMetadataUrl) return;
@@ -30,6 +37,7 @@ export async function ensureCimdClientRegistration(params: {
   try {
     resourceMetadata = await discoverOAuthProtectedResourceMetadata(
       params.serverUrl,
+      { resourceMetadataUrl: params.resourceMetadataUrl },
     );
   } catch {
     resourceMetadata = undefined;

core/mcp/oauthManager.ts

@@ -39,6 +39,7 @@ import type {
   HandleAuthChallengeOptions,
 } from "../auth/challenge.js";
 import {
+  challengeResourceMetadataUrl,
   parseScopeString,
   unionAuthorizationScopes,
 } from "../auth/challenge.js";
@@ -729,10 +730,17 @@ export class OAuthManager {
 
     provider.clearCapturedAuthUrl();
 
+    // RFC 9728: honor the metadata document the challenge advertised rather
+    // than probing the default locations derived from the MCP server URL
+    // (#2071). The SDK persists it in its discovery state, so the callback leg
+    // recovers it without our passing it again.
+    const resourceMetadataUrl = challengeResourceMetadataUrl(enriched);
+
     await ensureCimdClientRegistration({
       serverUrl,
       provider,
       fetchFn: this.params.effectiveAuthFetch,
+      resourceMetadataUrl,
     });
 
     const scopeForAuth =
@@ -750,6 +758,7 @@ export class OAuthManager {
         serverUrl,
         scope: scopeForAuth,
         fetchFn: this.params.effectiveAuthFetch,
+        resourceMetadataUrl,
         ...(enriched.reason === "insufficient_scope" && {
           forceReauthorization: isStrictScopeSuperset(
             scopeForAuth,
@@ -879,6 +888,7 @@ export class OAuthManager {
         serverUrl,
         scope: scopeForAuth,
         fetchFn: this.params.effectiveAuthFetch,
+        resourceMetadataUrl: challengeResourceMetadataUrl(enriched),
         forceReauthorization: true,
       });
     } finally {