import { Client, discoverAuthorizationServerMetadata, discoverOAuthProtectedResourceMetadata, extractWWWAuthenticateParams, IssuerMismatchError, StreamableHTTPClientTransport, } from "@modelcontextprotocol/client" import type { AuthorizationServerMetadata } from "@modelcontextprotocol/client" import type { DiscoverEnterpriseMcpConnectionRequirementsInput, EnterpriseMcpAuthorizationServerRequirement, EnterpriseMcpConnectionRequirements, EnterpriseMcpFetch, } from "./contracts.js" import { isEquivalentOAuthDiscoveryAlias } from "./oauth-resource-alias.js" const DEFAULT_TIMEOUT_MS = 15_000 const DEFAULT_MAX_AUTHORIZATION_SERVERS = 5 const DEFAULT_MAX_TOOLS = 100 const MAX_RESPONSE_BYTES = 1024 * 1024 const MAX_TOOL_PAGES = 5 /** * Select a canonical issuer only when fresh requirements discovery proves * that a stale configured value is either the same root issuer alias or the * protected resource's own discovery alias. Ambiguous and partially invalid * discovery results remain manual failures. */ export function selectRecoverableAuthorizationServerIssuer(input: { selectedIssuer: string requirements: Pick }): string | undefined { if ( input.requirements.authentication.kind !== "oauth" || input.requirements.authentication.authorizationServers.length !== 1 || input.requirements.warnings.some((warning) => warning.code === "oauth_issuer_mismatch") ) return undefined const canonicalIssuer = input.requirements.authentication.authorizationServers[0]?.issuer if (!canonicalIssuer || canonicalIssuer === input.selectedIssuer) return undefined if (isEquivalentOAuthDiscoveryAlias(input.selectedIssuer, canonicalIssuer)) return canonicalIssuer return isEquivalentOAuthDiscoveryAlias(input.selectedIssuer, input.requirements.authentication.resource) ? canonicalIssuer : undefined } function boundedResponse(response: Response): Response { const advertisedLength = Number(response.headers.get("content-length")) if (Number.isFinite(advertisedLength) && advertisedLength > MAX_RESPONSE_BYTES) { void response.body?.cancel() throw new Error("The MCP discovery response exceeded the 1 MiB limit.") } if (!response.body) return response const reader = response.body.getReader() let bytesRead = 0 const body = new ReadableStream({ async pull(controller) { const result = await reader.read() if (result.done) { controller.close() return } bytesRead += result.value.byteLength if (bytesRead > MAX_RESPONSE_BYTES) { await reader.cancel() controller.error(new Error("The MCP discovery response exceeded the 1 MiB limit.")) return } controller.enqueue(result.value) }, async cancel(reason) { await reader.cancel(reason) }, }) return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers, }) } function scopedFetch(input: { fetch: EnterpriseMcpFetch signal: AbortSignal observe: (response: Response) => void }): EnterpriseMcpFetch { return async (url, init) => { const signal = init?.signal ? AbortSignal.any([init.signal, input.signal]) : input.signal const response = boundedResponse(await input.fetch(url, { ...init, signal })) input.observe(response) return response } } function metadataRequirement(metadata: AuthorizationServerMetadata): EnterpriseMcpAuthorizationServerRequirement { return { issuer: metadata.issuer, authorizationEndpoint: metadata.authorization_endpoint, tokenEndpoint: metadata.token_endpoint, registrationEndpoint: metadata.registration_endpoint, clientIdMetadataDocumentSupported: metadata.client_id_metadata_document_supported === true, scopesSupported: metadata.scopes_supported, grantTypesSupported: metadata.grant_types_supported, codeChallengeMethodsSupported: metadata.code_challenge_methods_supported, tokenEndpointAuthMethodsSupported: metadata.token_endpoint_auth_methods_supported, } } async function discoverBoundAuthorizationServerMetadata(input: { advertisedIssuer: string resource: string | undefined fetch: EnterpriseMcpFetch }): Promise { let canonicalIssuer: string try { return await discoverAuthorizationServerMetadata(input.advertisedIssuer, { fetchFn: input.fetch }) ?? null } catch (error) { if ( !(error instanceof IssuerMismatchError) || !isEquivalentOAuthDiscoveryAlias(input.advertisedIssuer, input.resource) || typeof error.received !== "string" || !error.received ) throw error canonicalIssuer = error.received } // A few providers advertise the protected resource as a discovery alias. // The strict SDK mismatch exposes only the parsed issuer identifier. Treat // that value as a pointer, independently rediscover it with RFC 8414 issuer // validation enabled, and never consume endpoints from the alias document. return await discoverAuthorizationServerMetadata(canonicalIssuer, { fetchFn: input.fetch, }) ?? null } function uniqueScopes(value: string | undefined): string[] { if (!value) return [] return [...new Set(value.split(/\s+/).map((scope) => scope.trim()).filter(Boolean))] } function manualRequirements(input: { authorizationServers: EnterpriseMcpAuthorizationServerRequirement[] authenticationRequired: boolean }): EnterpriseMcpConnectionRequirements["manualRequirements"] { const requirements: EnterpriseMcpConnectionRequirements["manualRequirements"] = [ { code: "provider_access", label: "Provider access", reason: "Provider roles, licenses, tenant access, and administrator consent are not described by MCP OAuth metadata.", required: false, }, { code: "network_trust", label: "Network trust", reason: "Private routing, proxy, firewall, and private CA requirements must be confirmed in the Den deployment environment.", required: false, }, ] if (input.authorizationServers.length > 1) { requirements.unshift({ code: "authorization_server_selection", label: "Choose an authorization server", reason: "The protected resource advertises more than one issuer, so an administrator must bind this connection to one.", required: true, }) } if ( input.authenticationRequired && !input.authorizationServers.some((server) => server.clientIdMetadataDocumentSupported || server.registrationEndpoint) ) { requirements.unshift({ code: "oauth_client_registration", label: "Register an OAuth client", reason: "The authorization server does not advertise client metadata documents or dynamic registration.", required: true, }) } return requirements } export async function discoverConnectionRequirements( input: DiscoverEnterpriseMcpConnectionRequirementsInput, ): Promise { const serverUrl = new URL(input.serverUrl) if (serverUrl.protocol !== "http:" && serverUrl.protocol !== "https:") { throw new Error("An enterprise MCP server URL must use HTTP or HTTPS.") } if (serverUrl.username || serverUrl.password || serverUrl.hash) { throw new Error("An enterprise MCP server URL cannot contain credentials or a fragment.") } const controller = new AbortController() const timeout = setTimeout(() => controller.abort(new Error("MCP requirements discovery timed out.")), input.timeoutMs ?? DEFAULT_TIMEOUT_MS) let lastStatus: number | undefined let resourceMetadataUrl: URL | undefined let challengeScope: string | undefined const fetch = scopedFetch({ fetch: input.fetch, signal: controller.signal, observe: (response) => { lastStatus = response.status if (response.status !== 401 && response.status !== 403) return const challenge = extractWWWAuthenticateParams(response) resourceMetadataUrl = challenge.resourceMetadataUrl ?? resourceMetadataUrl challengeScope = challenge.scope ?? challengeScope }, }) const warnings: EnterpriseMcpConnectionRequirements["warnings"] = [] const tools: NonNullable = [] let initialize: EnterpriseMcpConnectionRequirements["server"]["initialize"] = "failed" let protocolEra: EnterpriseMcpConnectionRequirements["server"]["protocolEra"] let protocolVersion: string | undefined let authenticationRequired = false let client: Client | undefined try { client = new Client( { name: "OpenWork requirements discovery", version: "1.0.0" }, { capabilities: {}, versionNegotiation: { mode: "auto" } }, ) const transport = new StreamableHTTPClientTransport(serverUrl, { fetch }) await client.connect(transport, { signal: controller.signal }) initialize = "succeeded" protocolEra = client.getProtocolEra() protocolVersion = client.getNegotiatedProtocolVersion() let cursor: string | undefined const maxTools = input.maxTools ?? DEFAULT_MAX_TOOLS for (let page = 0; page < MAX_TOOL_PAGES && tools.length < maxTools; page += 1) { const result = await client.listTools(cursor ? { cursor } : undefined, { signal: controller.signal }) for (const tool of result.tools) { if (tools.length >= maxTools) break tools.push({ name: tool.name, readOnlyHint: tool.annotations?.readOnlyHint, destructiveHint: tool.annotations?.destructiveHint, openWorldHint: tool.annotations?.openWorldHint, }) } cursor = result.nextCursor if (!cursor) break } } catch (error) { authenticationRequired = lastStatus === 401 || lastStatus === 403 initialize = authenticationRequired ? "authentication_required" : "failed" if (!authenticationRequired) { warnings.push({ code: lastStatus ? `mcp_http_${lastStatus}` : "mcp_unreachable", message: error instanceof Error ? error.message : "The MCP endpoint could not be reached.", }) } } finally { try { await client?.close() } catch { // Discovery results remain useful even when best-effort transport cleanup fails. } } let resourceMetadata: Awaited> | undefined try { resourceMetadata = await discoverOAuthProtectedResourceMetadata( serverUrl, resourceMetadataUrl ? { resourceMetadataUrl } : undefined, fetch, ) } catch (error) { if (authenticationRequired) { warnings.push({ code: "oauth_resource_metadata_unavailable", message: error instanceof Error ? error.message : "Protected-resource metadata could not be discovered.", }) } } const advertisedIssuers = (resourceMetadata?.authorization_servers ?? []) .slice(0, input.maxAuthorizationServers ?? DEFAULT_MAX_AUTHORIZATION_SERVERS) const authorizationServers: EnterpriseMcpAuthorizationServerRequirement[] = [] for (const issuer of advertisedIssuers) { try { const metadata = await discoverBoundAuthorizationServerMetadata({ advertisedIssuer: issuer, resource: resourceMetadata?.resource, fetch, }) if (!metadata) { warnings.push({ code: "oauth_server_metadata_unavailable", message: `No OAuth metadata was found for issuer ${issuer}.` }) continue } authorizationServers.push(metadataRequirement(metadata)) } catch (error) { warnings.push({ code: error instanceof IssuerMismatchError ? "oauth_issuer_mismatch" : "oauth_server_metadata_unavailable", message: error instanceof Error ? error.message : `OAuth metadata could not be loaded for issuer ${issuer}.`, }) } } const requiredScopes = uniqueScopes(challengeScope) const refreshSupported = authorizationServers.some((server) => server.grantTypesSupported?.includes("refresh_token")) const offlineAccessSupported = authorizationServers.some((server) => server.scopesSupported?.includes("offline_access")) const recommendedScopes = requiredScopes.length > 0 ? [...requiredScopes] : [...new Set(resourceMetadata?.scopes_supported ?? [])] if (refreshSupported && offlineAccessSupported && !recommendedScopes.includes("offline_access")) { recommendedScopes.push("offline_access") } const supportsClientMetadata = authorizationServers.some((server) => server.clientIdMetadataDocumentSupported) const supportsDynamic = authorizationServers.some((server) => Boolean(server.registrationEndpoint)) const availableRegistrationMethods: EnterpriseMcpConnectionRequirements["authentication"]["availableRegistrationMethods"] = ["pre_registered"] if (supportsClientMetadata) availableRegistrationMethods.unshift("client_metadata") if (supportsDynamic) availableRegistrationMethods.push("dynamic") let recommendedRegistrationMethod: EnterpriseMcpConnectionRequirements["authentication"]["recommendedRegistrationMethod"] = "pre_registered" if (supportsClientMetadata) recommendedRegistrationMethod = "client_metadata" else if (supportsDynamic) recommendedRegistrationMethod = "dynamic" const oauthDetected = Boolean(resourceMetadata || authorizationServers.length > 0) const requirements = manualRequirements({ authorizationServers, authenticationRequired }) const status: EnterpriseMcpConnectionRequirements["status"] = initialize === "succeeded" ? "ready" : !authenticationRequired && lastStatus === undefined ? "unreachable" : oauthDetected && !requirements.some((requirement) => requirement.required) ? "ready" : authenticationRequired ? "manual_action_required" : "unsupported" try { return { status, server: { url: serverUrl.toString(), initialize, ...(protocolEra ? { protocolEra } : {}), ...(protocolVersion ? { protocolVersion } : {}), }, authentication: { kind: initialize === "succeeded" ? "none" : oauthDetected ? "oauth" : authenticationRequired ? "manual_bearer" : "unknown", resource: resourceMetadata?.resource, protectedResourceMetadataUrl: resourceMetadataUrl?.toString(), authorizationServers, requiredScopes, recommendedScopes, refreshSupport: refreshSupported ? "supported" : authorizationServers.length > 0 ? "not_advertised" : "unknown", availableRegistrationMethods, recommendedRegistrationMethod, }, tools: initialize === "succeeded" ? { visibility: "available_without_auth", count: tools.length, items: tools } : authenticationRequired ? { visibility: "requires_auth" } : { visibility: "unavailable" }, manualRequirements: requirements, warnings, } } finally { clearTimeout(timeout) } }