365 lines
15 KiB
TypeScript
365 lines
15 KiB
TypeScript
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<EnterpriseMcpConnectionRequirements, "authentication" | "warnings">
|
|
}): 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<Uint8Array>({
|
|
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<AuthorizationServerMetadata | null> {
|
|
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<EnterpriseMcpConnectionRequirements> {
|
|
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<EnterpriseMcpConnectionRequirements["tools"]["items"]> = []
|
|
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<ReturnType<typeof discoverOAuthProtectedResourceMetadata>> | 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)
|
|
}
|
|
}
|