fix(auth): accept RFC 8414 metadata served at the OIDC well-known path

The SDK's `discoverAuthorizationServerMetadata` picks its validation schema
from the well-known filename that resolved rather than from the document that
came back, so anything found at `/.well-known/openid-configuration` is
validated as an OpenID provider document — requiring `jwks_uri`,
`subject_types_supported` and `id_token_signing_alg_values_supported`, three
fields RFC 8414 does not define. RFC 8414 §5 permits that filename for general
OAuth metadata, so a conforming plain OAuth 2.0 authorization server is
rejected; and because the parse throws instead of continuing the candidate
loop, discovery aborts and the connection fails outright.

Filed upstream as modelcontextprotocol/typescript-sdk#2733.

`core/auth/oidcDiscoveryCompat.ts` works around it without fabricating a
field: on a failed RFC 8414 candidate it probes the OIDC candidates the SDK
would try next and, when one returns a document that satisfies
`OAuthMetadataSchema` but fails the OIDC schema, serves that body as the RFC
8414 response so the SDK picks the schema that describes it. A genuine OpenID
provider document is left to the SDK's own OIDC leg. Issuer validation runs
unchanged, since the substituted document is the one the server published.

It wraps `effectiveAuthFetch` — above the fetch tracker, the opposite of
`withOAuthEndpointOverrides` — so the Network tab still records the real 404
and the real probe rather than the substitution.

The candidate derivation mirrors the SDK's `buildDiscoveryUrls`, which a fetch
wrapper cannot call, and a test pins it against that export so the two cannot
drift.

Adds `oauth.asMetadataPath` to the composable test server (mirroring
`oauth.resourceMetadataPath`) and the `oauth-rfc8414-at-oidc-path-http.json`
showcase config that reproduces the failure.

Closes #2172

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UL9retfvAXRgvi6EWk4SY4
Signed-off-by: cliffhall <cliff@futurescale.com>

test-servers/configs/oauth-rfc8414-at-oidc-path-http.json

@@ -0,0 +1,19 @@
+{
+  "serverInfo": {
+    "name": "oauth-rfc8414-at-oidc-path",
+    "version": "1.0.0"
+  },
+  "tools": [{ "preset": "echo" }],
+  "oauth": {
+    "enabled": true,
+    "mode": "combined",
+    "requireAuth": true,
+    "asMetadataPath": "/.well-known/openid-configuration",
+    "scopesSupported": ["mcp"],
+    "supportDCR": true
+  },
+  "transport": {
+    "type": "streamable-http",
+    "port": 8083
+  }
+}

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

@@ -613,6 +613,21 @@ export interface ServerConfig {
      */
     resourceMetadataPath?: string;
 
+    /**
+     * Serve the RFC 8414 authorization-server metadata document from this
+     * non-default path *instead of* `/.well-known/oauth-authorization-server`
+     * (combined mode only).
+     *
+     * Set it to `/.well-known/openid-configuration` to reproduce #2172: a
+     * plain OAuth 2.0 authorization server — no `jwks_uri`, no
+     * `subject_types_supported`, no `id_token_signing_alg_values_supported` —
+     * publishing RFC 8414 metadata at the OIDC well-known path, which RFC 8414
+     * §5 permits. As with `resourceMetadataPath`, the default route is left
+     * unserved, so a client that cannot read the document where it actually
+     * lives fails outright rather than quietly succeeding elsewhere.
+     */
+    asMetadataPath?: 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

@@ -22,6 +22,8 @@ export interface ConfigFileOAuth {
   resource?: string;
   /** Serve RFC 9728 metadata from this path and advertise it on 401 (#2071). */
   resourceMetadataPath?: string;
+  /** Serve RFC 8414 AS metadata from this path instead of the default (#2172). */
+  asMetadataPath?: string;
   issuerUrl?: string;
   accessTokenIssuers?: string[];
   jwksUri?: string;
@@ -222,6 +224,12 @@ function validateConfig(
         `Invalid config in ${filePath}: oauth.resourceMetadataPath must be an origin-relative path (e.g. "/custom/protected-resource") — a value such as "//host/doc" would advertise a document the server does not serve`,
       );
     }
+    const asPath = oauth.asMetadataPath;
+    if (asPath !== undefined && !isOriginRelativePath(asPath)) {
+      throw new Error(
+        `Invalid config in ${filePath}: oauth.asMetadataPath must be an origin-relative path (e.g. "/.well-known/openid-configuration") — a value such as "//host/doc" would move the document off this server entirely`,
+      );
+    }
     if (transportType === "stdio" && oauth.enabled === true) {
       throw new Error(
         `Invalid config in ${filePath}: oauth requires streamable-http or sse transport`,

test-servers/src/test-helpers.ts

@@ -79,6 +79,13 @@ export interface WaitForOAuthWellKnownOptions {
   interval?: number;
   /** Max time per fetch attempt (so one hung request doesn't burn the whole timeout). Default 1000. */
   requestTimeout?: number;
+  /**
+   * Origin-relative path the AS metadata document is served from. Defaults to
+   * the RFC 8414 well-known path; pass the configured `oauth.asMetadataPath`
+   * when the fixture moved the document (#2172), since polling a route the
+   * server deliberately does not serve can only ever time out.
+   */
+  metadataPath?: string;
 }
 
 /**
@@ -97,8 +104,9 @@ export async function waitForOAuthWellKnown(
     timeout = 5000,
     interval = 50,
     requestTimeout = 1000,
+    metadataPath = "/.well-known/oauth-authorization-server",
   } = options ?? {};
-  const wellKnownUrl = `${serverBaseUrl.replace(/\/$/, "")}/.well-known/oauth-authorization-server`;
+  const wellKnownUrl = `${serverBaseUrl.replace(/\/$/, "")}${metadataPath}`;
   const start = Date.now();
   let lastStatus: number | undefined;
   let lastError: unknown;

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

@@ -2915,6 +2915,13 @@ export function createOAuthTestServerConfig(options: {
    * it via `WWW-Authenticate: Bearer resource_metadata="…"` (#2071).
    */
   resourceMetadataPath?: string;
+  /**
+   * Move the RFC 8414 authorization-server metadata document off the
+   * well-known path — set it to `/.well-known/openid-configuration` to serve
+   * plain OAuth 2.0 metadata where the SDK expects an OpenID provider
+   * document (#2172).
+   */
+  asMetadataPath?: string;
 }): Partial<ServerConfig> {
   return {
     oauth: {
@@ -2928,6 +2935,11 @@ export function createOAuthTestServerConfig(options: {
       ...(options.resourceMetadataPath !== undefined
         ? { resourceMetadataPath: options.resourceMetadataPath }
         : {}),
+      // Same `!== undefined` reasoning as above: an explicit `""` is invalid
+      // and must reach the server so it reports the bad fixture.
+      ...(options.asMetadataPath !== undefined
+        ? { asMetadataPath: options.asMetadataPath }
+        : {}),
       staticClients: options.staticClients,
       supportDCR: options.supportDCR ?? false,
       supportCIMD: options.supportCIMD ?? false,

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

@@ -83,6 +83,24 @@ function resourceMetadataPath(config: OAuthConfig): string | undefined {
   return path;
 }
 
+/**
+ * The path the RFC 8414 authorization-server metadata document is served from,
+ * validated the same way `resourceMetadataPath` is. Defaults to the well-known
+ * location; `asMetadataPath` moves it (see the field's doc comment).
+ */
+function asMetadataPath(config: OAuthConfig): string {
+  const path = config.asMetadataPath;
+  if (path === undefined) {
+    return "/.well-known/oauth-authorization-server";
+  }
+  if (!isOriginRelativePath(path)) {
+    throw new Error(
+      `oauth.asMetadataPath must be an origin-relative path (got ${JSON.stringify(path)})`,
+    );
+  }
+  return path;
+}
+
 /**
  * The `WWW-Authenticate` challenge sent with every 401.
  *
@@ -219,42 +237,36 @@ function setupMetadataEndpoints(
 
   if (mode === "combined") {
     // OAuth Authorization Server Metadata (local AS)
-    app.get(
-      "/.well-known/oauth-authorization-server",
-      (req: Request, res: Response) => {
-        const requestBaseUrl = `${req.protocol}://${req.get("host")}`;
-        const actualIssuerUrl = config.issuerUrl ?? new URL(requestBaseUrl);
-        const metadata = {
-          // RFC 8414 §3.3: the issuer MUST be identical to the base URL the
-          // well-known path was appended to — i.e. no trailing slash. SDK v2's
-          // client enforces this exactly (IssuerMismatchError otherwise).
-          issuer: actualIssuerUrl.href.replace(/\/$/, ""),
-          authorization_endpoint: new URL("/oauth/authorize", actualIssuerUrl)
+    app.get(asMetadataPath(config), (req: Request, res: Response) => {
+      const requestBaseUrl = `${req.protocol}://${req.get("host")}`;
+      const actualIssuerUrl = config.issuerUrl ?? new URL(requestBaseUrl);
+      const metadata = {
+        // RFC 8414 §3.3: the issuer MUST be identical to the base URL the
+        // well-known path was appended to — i.e. no trailing slash. SDK v2's
+        // client enforces this exactly (IssuerMismatchError otherwise).
+        issuer: actualIssuerUrl.href.replace(/\/$/, ""),
+        authorization_endpoint: new URL("/oauth/authorize", actualIssuerUrl)
+          .href,
+        token_endpoint: new URL("/oauth/token", actualIssuerUrl).href,
+        scopes_supported: scopes,
+        response_types_supported: ["code"],
+        grant_types_supported: ["authorization_code", "refresh_token"],
+        code_challenge_methods_supported: ["S256"],
+        token_endpoint_auth_methods_supported: ["client_secret_basic", "none"],
+        // RFC 9207 / SEP-2468: advertise iss on authorization responses so
+        // clients must validate (and our e2e can exercise reject paths).
+        authorization_response_iss_parameter_supported: true,
+        ...(config.supportDCR && {
+          registration_endpoint: new URL("/oauth/register", actualIssuerUrl)
             .href,
-          token_endpoint: new URL("/oauth/token", actualIssuerUrl).href,
-          scopes_supported: scopes,
-          response_types_supported: ["code"],
-          grant_types_supported: ["authorization_code", "refresh_token"],
-          code_challenge_methods_supported: ["S256"],
-          token_endpoint_auth_methods_supported: [
-            "client_secret_basic",
-            "none",
-          ],
-          // RFC 9207 / SEP-2468: advertise iss on authorization responses so
-          // clients must validate (and our e2e can exercise reject paths).
-          authorization_response_iss_parameter_supported: true,
-          ...(config.supportDCR && {
-            registration_endpoint: new URL("/oauth/register", actualIssuerUrl)
-              .href,
-          }),
-          ...(config.supportCIMD && {
-            client_id_metadata_document_supported: true,
-          }),
-        };
+        }),
+        ...(config.supportCIMD && {
+          client_id_metadata_document_supported: true,
+        }),
+      };
 
-        res.json(metadata);
-      },
-    );
+      res.json(metadata);
+    });
   }
 
   // OAuth Protected Resource Metadata. `resourceMetadataPath` moves the