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>

test-servers/src/composable-test-server.ts

@@ -573,6 +573,19 @@ export interface ServerConfig {
      */
     resource?: string;
 
+    /**
+     * Serve the RFC 9728 protected-resource metadata document from this
+     * non-default path *instead of* `/.well-known/oauth-protected-resource`,
+     * and advertise it via `WWW-Authenticate: Bearer resource_metadata="…"`
+     * on every 401.
+     *
+     * The default well-known routes are deliberately left unserved, so a
+     * client that ignores the advertised URL cannot discover the document at
+     * all — which is what makes this a regression test for #2071 rather than
+     * a path that merely happens to work.
+     */
+    resourceMetadataPath?: string;
+
     /**
      * OAuth authorization server issuer URL (combined mode AS metadata).
      * If not provided, defaults to the test server's base URL.

test-servers/src/load-config.ts

@@ -19,6 +19,8 @@ export interface ConfigFileOAuth {
   mode?: "combined" | "protected-resource";
   authorizationServers?: string[];
   resource?: string;
+  /** Serve RFC 9728 metadata from this path and advertise it on 401 (#2071). */
+  resourceMetadataPath?: string;
   issuerUrl?: string;
   accessTokenIssuers?: string[];
   jwksUri?: string;
@@ -200,6 +202,15 @@ function validateConfig(
         }
       }
     }
+    const metadataPath = oauth.resourceMetadataPath;
+    if (
+      metadataPath !== undefined &&
+      (typeof metadataPath !== "string" || !metadataPath.startsWith("/"))
+    ) {
+      throw new Error(
+        `Invalid config in ${filePath}: oauth.resourceMetadataPath must be an absolute path starting with "/"`,
+      );
+    }
     if (transportType === "stdio" && oauth.enabled === true) {
       throw new Error(
         `Invalid config in ${filePath}: oauth requires streamable-http or sse transport`,

test-servers/src/test-server-fixtures.ts

@@ -2902,6 +2902,11 @@ export function createOAuthTestServerConfig(options: {
   supportCIMD?: boolean;
   tokenExpirationSeconds?: number;
   supportRefreshTokens?: boolean;
+  /**
+   * Move the RFC 9728 metadata document off the well-known path and advertise
+   * it via `WWW-Authenticate: Bearer resource_metadata="…"` (#2071).
+   */
+  resourceMetadataPath?: string;
 }): Partial<ServerConfig> {
   return {
     oauth: {
@@ -2909,6 +2914,9 @@ export function createOAuthTestServerConfig(options: {
       mode: "combined",
       requireAuth: options.requireAuth ?? false,
       scopesSupported: options.scopesSupported ?? ["mcp"],
+      ...(options.resourceMetadataPath
+        ? { resourceMetadataPath: options.resourceMetadataPath }
+        : {}),
       staticClients: options.staticClients,
       supportDCR: options.supportDCR ?? false,
       supportCIMD: options.supportCIMD ?? false,

test-servers/src/test-server-oauth.ts

@@ -27,6 +27,23 @@ export function getOAuthMode(
   return config.mode ?? "combined";
 }
 
+/**
+ * The `WWW-Authenticate` challenge sent with every 401.
+ *
+ * RFC 9728 §5.1: a resource server advertises where its protected-resource
+ * metadata lives via the `resource_metadata` parameter. Only emitted when the
+ * config moves that document off the well-known path — otherwise the bare
+ * `Bearer` challenge keeps the existing fixtures byte-identical.
+ */
+function bearerChallenge(config: OAuthConfig, req: Request): string {
+  const path = config.resourceMetadataPath;
+  if (!path) {
+    return "Bearer";
+  }
+  const requestBaseUrl = `${req.protocol}://${req.get("host")}`;
+  return `Bearer resource_metadata="${new URL(path, requestBaseUrl).href}"`;
+}
+
 /**
  * Set up OAuth routes on an Express application
  * This adds all OAuth endpoints (authorization, token, metadata, etc.)
@@ -76,7 +93,7 @@ export function createBearerTokenMiddleware(
       // For streamable-http, the SDK checks response status and throws StreamableHTTPError with code 401
       res.status(401);
       res.setHeader("Content-Type", "application/json");
-      res.setHeader("WWW-Authenticate", "Bearer");
+      res.setHeader("WWW-Authenticate", bearerChallenge(config, req));
       // Return a JSON-RPC error response format that the SDK will recognize
       res.json({
         jsonrpc: "2.0",
@@ -113,7 +130,7 @@ export function createBearerTokenMiddleware(
       // Return 401 - the SDK's transport should detect this and throw an error
       res.status(401);
       res.setHeader("Content-Type", "application/json");
-      res.setHeader("WWW-Authenticate", "Bearer");
+      res.setHeader("WWW-Authenticate", bearerChallenge(config, req));
       // Return a JSON-RPC error response format that the SDK will recognize
       res.json({
         jsonrpc: "2.0",
@@ -184,9 +201,12 @@ function setupMetadataEndpoints(
     );
   }
 
-  // OAuth Protected Resource Metadata
+  // OAuth Protected Resource Metadata. `resourceMetadataPath` moves the
+  // document off the well-known path entirely (rather than serving both), so
+  // a client that ignores the advertised `resource_metadata` URL gets a 404
+  // — see the field's doc comment.
   app.get(
-    "/.well-known/oauth-protected-resource",
+    config.resourceMetadataPath ?? "/.well-known/oauth-protected-resource",
     (req: Request, res: Response) => {
       const requestBaseUrl = `${req.protocol}://${req.get("host")}`;
       const resourceUrl = config.resource ?? new URL("/", requestBaseUrl).href;