@opengeni/api-router 2.6.4 → 2.10.0-canary.0

package/src/integrations/oauth-client.ts

@@ -31,12 +31,20 @@ import {
 import { createSignedState, readSignedState } from "@opengeni/github";
 import {
   DestinationPolicyError,
+  McpOAuthDiscoveryError,
   OAUTH_MAX_RESPONSE_BYTES,
   RequestDeadlineError,
   isLocalTestEnvironment,
+  parseMcpOAuthChallenge,
   pinnedFetch,
   readResponseJsonBounded,
+  resolveMcpOAuthDiscovery,
   validateHttpUrl,
+  type McpAuthorizationServerMetadata,
+  type McpOAuthChallenge,
+  type McpOAuthDiscoveryMode,
+  type McpOAuthMetadataFetchResult,
+  type McpProtectedResourceMetadata,
 } from "@opengeni/network";
 import { Buffer } from "node:buffer";
 import { createHash, randomBytes } from "node:crypto";
@@ -100,30 +108,9 @@ export type OAuthCallbackResult = {
   redirectTo: string;
 };
 
-type WwwAuthenticateChallenge = {
-  resourceMetadata?: string;
-  scope?: string[];
-  error?: string;
-};
-
-type ProtectedResourceMetadata = {
-  resource?: string;
-  authorizationServers: string[];
-  scopesSupported: string[];
-  raw: Record<string, unknown>;
-};
-
-type AuthorizationServerMetadata = {
-  issuer: string;
-  authorizationServer: string;
-  authorizationEndpoint: string;
-  tokenEndpoint: string;
-  registrationEndpoint?: string;
-  clientIdMetadataDocumentSupported: boolean;
-  tokenEndpointAuthMethodsSupported: string[];
-  codeChallengeMethodsSupported: string[];
-  raw: Record<string, unknown>;
-};
+type WwwAuthenticateChallenge = McpOAuthChallenge;
+type ProtectedResourceMetadata = McpProtectedResourceMetadata;
+type AuthorizationServerMetadata = McpAuthorizationServerMetadata;
 
 type OAuthClientRegistration = {
   method: "operator" | "manual" | "cimd" | "dcr";
@@ -151,6 +138,10 @@ type OAuthStatePayload = {
   tokenEndpoint: string;
   authorizationServer: string;
   issuer: string;
+  discoveryMode: McpOAuthDiscoveryMode;
+  discoveryMetadataSha256?: string;
+  protectedResourceMetadataUrl?: string;
+  authorizationServerMetadataUrl?: string;
   clientRegistrationMethod: OAuthClientRegistration["method"];
   tokenEndpointAuthMethod: OAuthClientRegistration["tokenEndpointAuthMethod"];
   resourceParameterSupported: boolean;
@@ -389,8 +380,9 @@ async function startMcpOAuthWithinDeadline(
 
   const discovery = await discoverMcpOAuth(mcpUrl, settings, deadline);
   assertDiscoveredAuthorizationServer(settings, discovery.as, profile, providerDomain);
-  const resourceParameterSupported = profile.sendResourceParameter;
-  const resource = discovery.prm.resource ? canonicalOAuthResource(discovery.prm.resource) : mcpUrl;
+  const resourceParameterSupported =
+    discovery.mode === "rfc9728_protected_resource" && profile.sendResourceParameter;
+  const resource = discovery.resource;
   const verifier = randomPkceVerifier();
   // A profile's exact scope override wins outright: the reviewed connector
   // never lets a caller widen the capability contract.
@@ -433,6 +425,14 @@ async function startMcpOAuthWithinDeadline(
     tokenEndpoint: discovery.as.tokenEndpoint,
     authorizationServer: client.authorizationServer,
     issuer: client.issuer,
+    discoveryMode: discovery.mode,
+    discoveryMetadataSha256: discovery.provenance.metadataSha256,
+    ...(discovery.provenance.protectedResourceMetadataUrl
+      ? {
+          protectedResourceMetadataUrl: discovery.provenance.protectedResourceMetadataUrl,
+        }
+      : {}),
+    authorizationServerMetadataUrl: discovery.provenance.authorizationServerMetadataUrl,
     clientRegistrationMethod: client.method,
     tokenEndpointAuthMethod: client.tokenEndpointAuthMethod,
     resourceParameterSupported,
@@ -711,6 +711,18 @@ async function completeMcpOAuthCallbackWithinDeadline(
       tokenEndpoint: state.tokenEndpoint,
       clientId: client.clientId,
       clientRegistrationMethod: state.clientRegistrationMethod,
+      oauthDiscovery: {
+        mode: state.discoveryMode,
+        resource: state.resource,
+        issuer: state.issuer,
+        ...(state.discoveryMetadataSha256 ? { metadataSha256: state.discoveryMetadataSha256 } : {}),
+        ...(state.protectedResourceMetadataUrl
+          ? { protectedResourceMetadataUrl: state.protectedResourceMetadataUrl }
+          : {}),
+        ...(state.authorizationServerMetadataUrl
+          ? { authorizationServerMetadataUrl: state.authorizationServerMetadataUrl }
+          : {}),
+      },
       mcpToolsVerification: verification.metadata,
       ...(verification.tools ? { mcpTools: verification.tools } : {}),
     };
@@ -835,28 +847,50 @@ async function discoverMcpOAuth(
   challenge: WwwAuthenticateChallenge;
   prm: ProtectedResourceMetadata;
   as: AuthorizationServerMetadata;
+  mode: McpOAuthDiscoveryMode;
+  resource: string;
+  provenance: {
+    protectedResourceMetadataUrl: string | null;
+    authorizationServerMetadataUrl: string;
+    metadataSha256: string;
+  };
 }> {
   const challenge = await deadline.run("mcp_challenge", (signal) =>
     probeMcpChallenge(resource, settings, signal),
   );
-  const prm = await deadline.run("protected_resource_metadata", (signal) =>
-    discoverProtectedResourceMetadata(resource, settings, challenge.resourceMetadata, signal),
-  );
-  const authorizationServer = prm.authorizationServers[0];
-  if (!authorizationServer) {
-    throw new HTTPException(422, {
-      message: "MCP protected resource metadata did not advertise an authorization server",
-    });
-  }
-  const as = await deadline.run("authorization_server_metadata", (signal) =>
-    discoverAuthorizationServerMetadata(authorizationServer, settings, signal),
-  );
-  if (!as.codeChallengeMethodsSupported.includes("S256")) {
-    throw new HTTPException(422, {
-      message: "authorization server does not support required PKCE S256",
+  try {
+    const discovery = await resolveMcpOAuthDiscovery({
+      resourceUrl: resource,
+      challenge,
+      fetchMetadata: ({ kind, url }) =>
+        deadline.run(
+          kind === "protected_resource"
+            ? "protected_resource_metadata"
+            : "authorization_server_metadata",
+          (signal) => fetchOAuthMetadata(url, settings, signal),
+        ),
+      validateEndpoint: (rawUrl, label) => oauthEndpointUrl(rawUrl, settings, label),
+      canonicalizeResource: canonicalOAuthResource,
     });
+    return {
+      challenge: discovery.challenge,
+      prm: discovery.protectedResourceMetadata,
+      as: discovery.authorizationServerMetadata,
+      mode: discovery.mode,
+      resource: discovery.resource,
+      provenance: discovery.provenance,
+    };
+  } catch (error) {
+    if (error instanceof OAuthStartStageError) throw error;
+    if (error instanceof McpOAuthDiscoveryError) {
+      throw new OAuthStartStageError(
+        error.stage,
+        error.classification,
+        new HTTPException(422, { message: error.message }),
+      );
+    }
+    throw error;
   }
-  return { challenge, prm, as };
 }
 
 async function probeMcpChallenge(
@@ -871,115 +905,45 @@ async function probeMcpChallenge(
   });
   try {
     if (response.status !== 401) {
-      return {};
+      return { scheme: null, scope: [] };
     }
-    return parseWwwAuthenticate(response.headers.get("www-authenticate"));
+    return parseMcpOAuthChallenge(response.headers.get("www-authenticate"));
   } finally {
     await cancelResponseBody(response);
   }
 }
 
-async function discoverProtectedResourceMetadata(
-  resource: string,
-  settings: Settings,
-  advertisedUrl?: string,
-  signal?: AbortSignal,
-): Promise<ProtectedResourceMetadata> {
-  const candidates = uniqueStrings([
-    ...(advertisedUrl ? [advertisedUrl] : []),
-    ...wellKnownCandidates(resource, "oauth-protected-resource"),
-  ]);
-  for (const candidate of candidates) {
-    const payload = await fetchJsonObject(candidate, settings, signal).catch((error) => {
-      if (error instanceof HTTPException) {
-        throw error;
-      }
-      return null;
-    });
-    if (!payload) {
-      continue;
-    }
-    const authorizationServers = stringArray(payload.authorization_servers);
-    if (authorizationServers.length === 0) {
-      continue;
-    }
-    return {
-      authorizationServers,
-      scopesSupported: stringArray(payload.scopes_supported),
-      raw: payload,
-      ...(stringValue(payload.resource) ? { resource: stringValue(payload.resource)! } : {}),
-    };
-  }
-  throw new HTTPException(422, {
-    message: "could not discover MCP protected resource metadata",
-  });
-}
-
-async function discoverAuthorizationServerMetadata(
-  authorizationServer: string,
+async function fetchOAuthMetadata(
+  url: string,
   settings: Settings,
   signal: AbortSignal,
-): Promise<AuthorizationServerMetadata> {
-  const safeAuthorizationServer = oauthEndpointUrl(
-    authorizationServer,
-    settings,
-    "OAuth authorization server",
-  ).replace(/\/+$/, "");
-  const candidates = uniqueStrings([
-    // Prefer the RFC metadata locations before probing the issuer itself. Some
-    // providers (including Linear) redirect their issuer root to a human docs
-    // page; following that redirect can leave discovery waiting on an unrelated
-    // streaming response even though the well-known metadata is immediately
-    // available.
-    ...wellKnownCandidates(safeAuthorizationServer, "oauth-authorization-server"),
-    ...wellKnownCandidates(safeAuthorizationServer, "openid-configuration"),
-    safeAuthorizationServer,
-  ]);
-  for (const candidate of candidates) {
-    const payload = await fetchJsonObject(candidate, settings, signal).catch((error) => {
-      if (error instanceof HTTPException) {
-        throw error;
-      }
-      return null;
-    });
-    if (!payload) {
-      continue;
-    }
-    const authorizationEndpoint = stringValue(payload.authorization_endpoint);
-    const tokenEndpoint = stringValue(payload.token_endpoint);
-    if (!authorizationEndpoint || !tokenEndpoint) {
-      continue;
-    }
-    const safeAuthorizationEndpoint = oauthEndpointUrl(
-      authorizationEndpoint,
-      settings,
-      "OAuth authorization endpoint",
-    );
-    const safeTokenEndpoint = oauthEndpointUrl(tokenEndpoint, settings, "OAuth token endpoint");
-    const registrationEndpoint = stringValue(payload.registration_endpoint);
-    const issuer = oauthEndpointUrl(
-      stringValue(payload.issuer) ?? safeAuthorizationServer,
-      settings,
-      "OAuth issuer",
-    );
-    const safeRegistrationEndpoint = registrationEndpoint
-      ? oauthEndpointUrl(registrationEndpoint, settings, "OAuth registration endpoint")
-      : undefined;
-    return {
-      issuer,
-      authorizationServer: safeAuthorizationServer,
-      authorizationEndpoint: safeAuthorizationEndpoint,
-      tokenEndpoint: safeTokenEndpoint,
-      clientIdMetadataDocumentSupported: payload.client_id_metadata_document_supported === true,
-      tokenEndpointAuthMethodsSupported: stringArray(payload.token_endpoint_auth_methods_supported),
-      codeChallengeMethodsSupported: stringArray(payload.code_challenge_methods_supported),
-      raw: payload,
-      ...(safeRegistrationEndpoint ? { registrationEndpoint: safeRegistrationEndpoint } : {}),
-    };
-  }
-  throw new HTTPException(422, {
-    message: "could not discover OAuth authorization server metadata",
+): Promise<McpOAuthMetadataFetchResult> {
+  const response = await fetchOAuth(url, settings, {
+    headers: { accept: "application/json" },
+    signal,
   });
+  if (response.status === 404 || response.status === 410) {
+    await cancelResponseBody(response);
+    return { status: "absent", url, httpStatus: response.status };
+  }
+  if (!response.ok) {
+    await cancelResponseBody(response);
+    throw new Error(`OAuth metadata endpoint returned HTTP ${response.status}`);
+  }
+  const payload = await readResponseJsonBounded<unknown>(
+    response,
+    OAUTH_MAX_RESPONSE_BYTES,
+    "OAuth metadata response",
+    { signal },
+  );
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error("OAuth metadata response was not a JSON object");
+  }
+  return {
+    status: "present",
+    url,
+    document: payload as Record<string, unknown>,
+  };
 }
 
 async function registerOAuthClient(
@@ -1433,6 +1397,29 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
     throw new HTTPException(400, { message: "invalid or expired OAuth state" });
   }
   const resource = requiredString(payload.resource, "state.resource");
+  const encodedDiscoveryMode = stringValue(payload.discoveryMode);
+  const discoveryMode = discoveryModeValue(encodedDiscoveryMode);
+  const discoveryMetadataSha256 = stringValue(payload.discoveryMetadataSha256);
+  if (
+    encodedDiscoveryMode &&
+    (!discoveryMetadataSha256 || !/^[0-9a-f]{64}$/.test(discoveryMetadataSha256))
+  ) {
+    throw new HTTPException(400, { message: "invalid OAuth discovery state" });
+  }
+  const protectedResourceMetadataUrl = stringValue(payload.protectedResourceMetadataUrl);
+  const authorizationServerMetadataUrl = stringValue(payload.authorizationServerMetadataUrl);
+  if (
+    encodedDiscoveryMode &&
+    (!authorizationServerMetadataUrl ||
+      (discoveryMode === "rfc9728_protected_resource" && !protectedResourceMetadataUrl) ||
+      (discoveryMode === "legacy_2025_03_26_metadata" && protectedResourceMetadataUrl))
+  ) {
+    throw new HTTPException(400, { message: "invalid OAuth discovery provenance state" });
+  }
+  const resourceParameterSupported = payload.resourceParameterSupported !== false;
+  if (discoveryMode === "legacy_2025_03_26_metadata" && resourceParameterSupported) {
+    throw new HTTPException(400, { message: "invalid legacy OAuth resource parameter state" });
+  }
   const parsed = {
     accountId: requiredString(payload.accountId, "state.accountId"),
     workspaceId: requiredString(payload.workspaceId, "state.workspaceId"),
@@ -1467,11 +1454,31 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
       settings,
       "OAuth issuer",
     ),
+    discoveryMode,
+    ...(discoveryMetadataSha256 ? { discoveryMetadataSha256 } : {}),
+    ...(protectedResourceMetadataUrl
+      ? {
+          protectedResourceMetadataUrl: oauthEndpointUrl(
+            protectedResourceMetadataUrl,
+            settings,
+            "OAuth protected resource metadata",
+          ),
+        }
+      : {}),
+    ...(authorizationServerMetadataUrl
+      ? {
+          authorizationServerMetadataUrl: oauthEndpointUrl(
+            authorizationServerMetadataUrl,
+            settings,
+            "OAuth authorization server metadata",
+          ),
+        }
+      : {}),
     clientRegistrationMethod: registrationMethod(payload.clientRegistrationMethod),
     tokenEndpointAuthMethod: tokenAuthMethod(stringValue(payload.tokenEndpointAuthMethod), false),
     // States minted before provider-specific compatibility was introduced used
     // the RFC 8707 resource parameter.
-    resourceParameterSupported: payload.resourceParameterSupported !== false,
+    resourceParameterSupported,
     ...(stringValue(payload.encryptedClientSecret)
       ? { encryptedClientSecret: stringValue(payload.encryptedClientSecret)! }
       : {}),
@@ -1484,6 +1491,13 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
   if (Boolean(connectionId) !== Boolean(connectionVersion)) {
     throw new HTTPException(400, { message: "invalid OAuth reconnect state" });
   }
+  if (
+    parsed.discoveryMode === "legacy_2025_03_26_metadata" &&
+    (normalizedIssuerKey(parsed.authorizationServer) !== normalizedIssuerKey(parsed.issuer) ||
+      new URL(parsed.resource).origin !== new URL(parsed.issuer).origin)
+  ) {
+    throw new HTTPException(400, { message: "invalid OAuth discovery binding state" });
+  }
   return {
     ...parsed,
     ...(connectionId ? { connectionId } : {}),
@@ -1491,6 +1505,17 @@ function readOAuthState(state: string, settings: Settings): OAuthStatePayload {
   };
 }
 
+function discoveryModeValue(value: string | undefined): McpOAuthDiscoveryMode {
+  if (!value) {
+    // Every state minted before discovery modes existed used RFC 9728 PRM.
+    return "rfc9728_protected_resource";
+  }
+  if (value === "rfc9728_protected_resource" || value === "legacy_2025_03_26_metadata") {
+    return value;
+  }
+  throw new HTTPException(400, { message: "invalid OAuth discovery mode state" });
+}
+
 function connectionOwnership(value: unknown): ConnectionOwnership | undefined {
   return value === "workspace" || value === "personal" ? value : undefined;
 }
@@ -2033,31 +2058,6 @@ function safeReturnPath(value: string): string {
   return `${parsed.pathname}${parsed.search}${parsed.hash}`;
 }
 
-async function fetchJsonObject(
-  url: string,
-  settings: Settings,
-  signal?: AbortSignal,
-): Promise<Record<string, unknown>> {
-  const response = await fetchOAuth(url, settings, {
-    headers: { accept: "application/json" },
-    ...(signal ? { signal } : {}),
-  });
-  if (!response.ok) {
-    await cancelResponseBody(response);
-    throw new Error(`HTTP ${response.status}`);
-  }
-  const payload = await readResponseJsonBounded<unknown>(
-    response,
-    OAUTH_MAX_RESPONSE_BYTES,
-    "OAuth metadata response",
-    { ...(signal ? { signal } : {}) },
-  );
-  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
-    throw new Error("metadata response was not a JSON object");
-  }
-  return payload as Record<string, unknown>;
-}
-
 async function fetchOAuth(
   rawUrl: string,
   settings: Settings,
@@ -2130,41 +2130,6 @@ async function cancelResponseBody(response: Response): Promise<void> {
   await response.body?.cancel().catch(() => undefined);
 }
 
-function parseWwwAuthenticate(header: string | null): WwwAuthenticateChallenge {
-  if (!header) {
-    return {};
-  }
-  const bearerIndex = header.toLowerCase().indexOf("bearer");
-  if (bearerIndex < 0) {
-    return {};
-  }
-  const paramsText = header.slice(bearerIndex + "bearer".length);
-  const params: Record<string, string> = {};
-  const re = /([a-zA-Z_][a-zA-Z0-9_-]*)\s*=\s*("(?:[^"\\]|\\.)*"|[^,\s]+)/g;
-  let match: RegExpExecArray | null;
-  while ((match = re.exec(paramsText)) !== null) {
-    const raw = match[2]!;
-    params[match[1]!.toLowerCase()] = raw.startsWith('"')
-      ? raw.slice(1, -1).replace(/\\"/g, '"')
-      : raw;
-  }
-  return {
-    ...(params.resource_metadata ? { resourceMetadata: params.resource_metadata } : {}),
-    ...(params.scope ? { scope: params.scope.split(/\s+/).filter(Boolean) } : {}),
-    ...(params.error ? { error: params.error } : {}),
-  };
-}
-
-function wellKnownCandidates(rawUrl: string, name: string): string[] {
-  const url = new URL(rawUrl);
-  const path = url.pathname.replace(/^\/+|\/+$/g, "");
-  return uniqueStrings([
-    `${url.origin}/.well-known/${name}${path ? `/${path}` : ""}`,
-    `${url.origin}${path ? `/${path}` : ""}/.well-known/${name}`,
-    `${url.origin}/.well-known/${name}`,
-  ]);
-}
-
 function chooseAuthorizeScopes(
   requested: string[] | undefined,
   challenged: string[] | undefined,