@fitchmultz/pi-mcp-adapter 6.0.0 → 7.1.0

package/mcp-auth-flow.ts

@@ -1,975 +0,0 @@
-/**
- * MCP Auth Flow
- * 
- * High-level OAuth flow management using the MCP SDK's built-in auth functions.
- */
-
-import {
-  auth as runSdkAuth,
-  extractWWWAuthenticateParams,
-  UnauthorizedError,
-  Client,
-  StreamableHTTPClientTransport,
-  validateAuthorizationResponseIssuer,
-  InsufficientScopeError,
-  SdkHttpError,
-  computeScopeUnion,
-  isStrictScopeSuperset,
-} from "@modelcontextprotocol/client"
-import open from "open"
-import { McpOAuthProvider, issuersMatch, loopbackRedirectsMatch, validateOAuthClientMetadataUrl, validateOAuthPrivateKeyJwt, validateOAuthCrossAppAccess, type McpOAuthConfig } from "./mcp-oauth-provider.ts"
-import {
-  ensureCallbackServer,
-  waitForCallback,
-  cancelPendingCallback,
-  stopCallbackServer,
-  releaseCallbackServer,
-  takeCallbackResult,
-} from "./mcp-callback-server.ts"
-import {
-  getAuthForUrl,
-  clearAllCredentials,
-  clearClientInfo,
-  clearTokens,
-  clearCodeVerifier,
-  getOAuthState,
-  clearOAuthState,
-  getAuthBaseDir,
-  type AuthStorageOptions,
-} from "./mcp-auth.ts"
-import { isServerDisabled, isNonInteractiveOAuth, validateServerProtocolConfig, type ServerEntry } from "./types.ts"
-import { formatTerminalError, interpolateEnvRecord, interpolateEnvVars, normalizeRequestTimeoutMs } from "./utils.ts"
-import { abortable, throwIfAborted } from "./abort.ts"
-import { combineAbortSignals, isAbortError } from "./runtime-owner.ts"
-
-/** Auth status for a server */
-export type AuthStatus = "authenticated" | "expired" | "not_authenticated"
-
-import type { McpCheckpointEvent } from "./checkpoint.ts"
-
-export interface McpOAuthRuntime {
-  readonly signal: AbortSignal
-}
-
-export interface AuthenticateOptions {
-  onAuthorizationUrl?: (authorizationUrl: string) => void | Promise<void>
-  authStorageOptions?: AuthStorageOptions
-  signal?: AbortSignal
-  runtime?: McpOAuthRuntime
-}
-
-type AuthDiscovery = {
-  resourceMetadataUrl?: URL
-  scope?: string
-  skipIssuerMetadataValidation?: boolean
-}
-
-function applyConfiguredScope(discovery: AuthDiscovery, config: McpOAuthConfig): AuthDiscovery {
-  return {
-    ...discovery,
-    ...(config.scope !== undefined ? { scope: config.scope } : {}),
-    ...(config.skipIssuerMetadataValidation !== undefined ? { skipIssuerMetadataValidation: config.skipIssuerMetadataValidation } : {}),
-  }
-}
-
-type CallbackIssuer = { expectedIssuer?: string | undefined; fallbackIssuer?: string; issParameterSupported?: boolean }
-
-function validateCallbackIssuer(serverName: string, context: CallbackIssuer, response: { iss?: string; error?: string }): void {
-  if (response.error && context.expectedIssuer === undefined) {
-    throw new Error("Cannot verify the OAuth error callback issuer")
-  }
-  try {
-    validateAuthorizationResponseIssuer({ expectedIssuer: context.expectedIssuer ?? context.fallbackIssuer, issParameterSupported: context.issParameterSupported === true, iss: response.iss })
-  } catch {
-    if (response.iss === undefined && context.issParameterSupported) {
-      throw new Error(
-        `The authorization server for ${serverName} requires the RFC 9207 "iss" parameter. ` +
-        "Paste the full redirect URL from the browser address bar (not just the authorization code).",
-      )
-    }
-    throw new Error(`The OAuth authorization response issuer does not match the discovered issuer for ${serverName}.`)
-  }
-}
-
-type PendingAuth = {
-  serverName: string
-  authProvider: McpOAuthProvider
-  serverUrl: string
-  authorizationUrl: string
-  discovery: AuthDiscovery
-  callbackIssuer: CallbackIssuer
-  request?: OAuthRequest
-  authStorageOptions: AuthStorageOptions
-}
-
-type RuntimeState = {
-  controller: AbortController
-  generation: number
-  activeOperations: number
-  checkpoint?: McpCheckpointEvent | undefined
-  pendingAuths: Map<string, PendingAuth>
-  pendingAuthStates: Map<string, string>
-  pendingAuthCleanupTimers: Map<string, ReturnType<typeof setTimeout>>
-  pendingAuthentications: Map<string, Promise<AuthStatus>>
-  requests: Map<string, OAuthRequest>
-}
-
-const runtimeStates = new WeakMap<McpOAuthRuntime, RuntimeState>()
-const activeRuntimes = new Set<McpOAuthRuntime>()
-
-export function createOAuthRuntime(signal?: AbortSignal): McpOAuthRuntime {
-  const controller = new AbortController()
-  const runtime = { signal: combineAbortSignals(signal, controller.signal)! } satisfies McpOAuthRuntime
-  runtimeStates.set(runtime, {
-    controller,
-    generation: 0,
-    activeOperations: 0,
-    pendingAuths: new Map(),
-    pendingAuthStates: new Map(),
-    pendingAuthCleanupTimers: new Map(),
-    pendingAuthentications: new Map(),
-    requests: new Map(),
-  })
-  activeRuntimes.add(runtime)
-  return runtime
-}
-
-let legacyRuntime = createOAuthRuntime()
-activeRuntimes.delete(legacyRuntime)
-
-function getRuntime(options?: AuthenticateOptions): McpOAuthRuntime {
-  if (options?.runtime) {
-    options.runtime.signal.throwIfAborted()
-    activeRuntimes.add(options.runtime)
-    return options.runtime
-  }
-  if (legacyRuntime.signal.aborted) legacyRuntime = createOAuthRuntime()
-  activeRuntimes.add(legacyRuntime)
-  return legacyRuntime
-}
-
-function getRuntimeState(runtime: McpOAuthRuntime): RuntimeState {
-  const state = runtimeStates.get(runtime)
-  if (!state) throw new Error("Unknown OAuth runtime")
-  return state
-}
-
-export function holdOAuthCheckpoint(runtime: McpOAuthRuntime, event: McpCheckpointEvent): () => void {
-  const state = getRuntimeState(runtime)
-  if (state.checkpoint) throw new Error("MCP OAuth checkpoint is already held")
-  state.checkpoint = event
-  return () => { if (state.checkpoint === event) state.checkpoint = undefined }
-}
-
-export function getOAuthCheckpointBlocker(runtime: McpOAuthRuntime): string | undefined {
-  const state = getRuntimeState(runtime)
-  if (state.activeOperations || state.pendingAuthentications.size) return "MCP OAuth operation is active"
-  if (state.pendingAuths.size || state.pendingAuthStates.size || state.pendingAuthCleanupTimers.size) return "MCP browser OAuth callback/flow is pending"
-  // requests caches server challenges/discovery, not a pending user callback.
-  // Cold connect re-challenges; granted scopes and issuer bindings live in the
-  // native credential store. Actual interactive/auth operations veto above.
-  return undefined
-}
-
-async function withOAuthOperation<T>(runtime: McpOAuthRuntime, run: () => Promise<T>): Promise<T> {
-  const state = getRuntimeState(runtime)
-  state.checkpoint?.invalidate()
-  state.activeOperations++
-  try { return await run() } finally { state.activeOperations-- }
-}
-
-function getPendingAuthKey(serverName: string, options: AuthStorageOptions): string {
-  return JSON.stringify([serverName, getAuthBaseDir(options)])
-}
-
-type OAuthRequest = {
-  serverName: string
-  serverUrl: string
-  requestedScope?: string
-  challenge?: { requiredScope?: string; resourceMetadataUrl?: URL }
-  issuer?: string
-}
-
-export function isOAuthChallenge(error: unknown): error is InsufficientScopeError | UnauthorizedError | SdkHttpError {
-  return error instanceof InsufficientScopeError || error instanceof UnauthorizedError
-    || (error instanceof SdkHttpError && error.status === 401)
-}
-
-export function getOAuthRequest(serverName: string, serverUrl: string, storageBase: string, runtime: McpOAuthRuntime = legacyRuntime): OAuthRequest | undefined {
-  if (runtime.signal.aborted) return undefined
-  const request = getRuntimeState(runtime).requests.get(JSON.stringify([serverName, storageBase]))
-  return request?.serverUrl === serverUrl ? request : undefined
-}
-
-/** Observe native challenges only; no credential reads or auth work here. */
-export function recordOAuthChallenge(serverName: string, serverUrl: string, storageBase: string, error: unknown, runtime: McpOAuthRuntime = legacyRuntime): void {
-  if (runtime.signal.aborted || !isOAuthChallenge(error)) return
-  getRuntimeState(runtime).checkpoint?.invalidate()
-  const previous = getOAuthRequest(serverName, serverUrl, storageBase, runtime)
-  const request: OAuthRequest = { ...previous, serverName, serverUrl }
-  if (error instanceof InsufficientScopeError) {
-    const requiredScope = computeScopeUnion(previous?.challenge?.requiredScope, error.requiredScope)
-    const resourceMetadataUrl = error.resourceMetadataUrl ?? previous?.challenge?.resourceMetadataUrl
-    request.challenge = { ...(requiredScope ? { requiredScope } : {}), ...(resourceMetadataUrl ? { resourceMetadataUrl } : {}) }
-  }
-  getRuntimeState(runtime).requests.set(JSON.stringify([serverName, storageBase]), request)
-}
-
-export function bindOAuthRequestIssuer(serverName: string, serverUrl: string, storageBase: string, issuer: string, runtime: McpOAuthRuntime = legacyRuntime): void {
-  const request = getOAuthRequest(serverName, serverUrl, storageBase, runtime)
-  if (!request) return
-  if (request.issuer && !issuersMatch(request.issuer, issuer)) {
-    throw new Error(`OAuth authorization server issuer changed for ${serverName}; clear credentials before authenticating again`)
-  }
-  request.issuer = issuer
-}
-
-export function hasPendingAuth(serverName: string, options?: AuthStorageOptions, runtime?: McpOAuthRuntime): boolean {
-  const state = getRuntimeState(runtime ?? legacyRuntime)
-  if (options) {
-    return state.pendingAuths.has(getPendingAuthKey(serverName, options))
-  }
-  return Array.from(state.pendingAuths.values()).some(pendingAuth => pendingAuth.serverName === serverName)
-}
-
-/** Timeout for manual auth completion (5 minutes) */
-const MANUAL_AUTH_TIMEOUT_MS = 5 * 60 * 1000
-
-/**
- * Generate a cryptographically secure random state parameter.
- */
-function generateState(): string {
-  return Array.from(crypto.getRandomValues(new Uint8Array(32)))
-    .map((b) => b.toString(16).padStart(2, "0"))
-    .join("")
-}
-
-/**
- * Extract OAuth configuration from a ServerEntry.
- */
-export function extractOAuthConfig(definition: ServerEntry): McpOAuthConfig {
-  validateServerProtocolConfig(definition)
-  if (definition.oauth === false) {
-    return {}
-  }
-
-  const config: McpOAuthConfig = {}
-  if (definition.oauth?.skipIssuerMetadataValidation !== undefined) config.skipIssuerMetadataValidation = definition.oauth.skipIssuerMetadataValidation
-  if (definition.oauth?.grantType !== undefined) config.grantType = definition.oauth.grantType
-  if (definition.oauth?.clientId !== undefined) {
-    if (typeof definition.oauth.clientId !== "string") throw new Error("OAuth clientId must be a string")
-    config.clientId = interpolateEnvVars(definition.oauth.clientId)
-  }
-  if (definition.oauth?.clientSecret !== undefined) {
-    if (typeof definition.oauth.clientSecret !== "string") throw new Error("OAuth clientSecret must be a string")
-    // Preserve command expressions for the provider; interpolation remains eager for ordinary values.
-    config.clientSecret = definition.oauth.clientSecret.startsWith("!")
-      ? definition.oauth.clientSecret
-      : interpolateEnvVars(definition.oauth.clientSecret)
-  }
-  if (definition.oauth?.clientMetadataUrl !== undefined) {
-    const value = definition.oauth.clientMetadataUrl
-    if (value !== false && typeof value !== "string") throw new Error("OAuth clientMetadataUrl must be a string or false")
-    config.clientMetadataUrl = value === false ? false : interpolateEnvVars(value)
-    validateOAuthClientMetadataUrl(config.clientMetadataUrl)
-  }
-  if (definition.oauth?.privateKeyJwt !== undefined) {
-    // Keep environment and command sources lazy; each authentication resolves its own key.
-    config.privateKeyJwt = definition.oauth.privateKeyJwt
-  }
-  if (definition.oauth?.crossAppAccess !== undefined) config.crossAppAccess = definition.oauth.crossAppAccess
-  validateOAuthPrivateKeyJwt(config)
-  validateOAuthCrossAppAccess(config)
-  if (definition.oauth?.scope !== undefined) {
-    if (typeof definition.oauth.scope !== "string") throw new Error("OAuth scope must be a string")
-    config.scope = interpolateEnvVars(definition.oauth.scope)
-  }
-  if (definition.oauth?.authorizationParams !== undefined) {
-    const params = definition.oauth.authorizationParams
-    if (!params || typeof params !== "object" || Array.isArray(params)) {
-      throw new Error("OAuth authorizationParams must be an object")
-    }
-    config.authorizationParams = {}
-    for (const [key, value] of Object.entries(params)) {
-      if (!key) throw new Error("OAuth authorizationParams keys must not be empty")
-      if (typeof value !== "string") throw new Error(`OAuth authorizationParams.${key} must be a string`)
-      config.authorizationParams[key] = interpolateEnvVars(value)
-    }
-  }
-  if (definition.oauth?.redirectUri !== undefined) {
-    if (typeof definition.oauth.redirectUri !== "string") {
-      throw new Error("OAuth redirectUri must be a string")
-    }
-    const redirectUri = interpolateEnvVars(definition.oauth.redirectUri).trim()
-    if (!redirectUri) {
-      throw new Error("OAuth redirectUri must not be empty")
-    }
-    config.redirectUri = redirectUri
-  }
-  if (definition.oauth?.clientName !== undefined) {
-    if (typeof definition.oauth.clientName !== "string") {
-      throw new Error("OAuth clientName must be a string")
-    }
-    const clientName = interpolateEnvVars(definition.oauth.clientName).trim()
-    if (!clientName) {
-      throw new Error("OAuth clientName must not be empty")
-    }
-    config.clientName = clientName
-  }
-  if (definition.oauth?.clientUri !== undefined) {
-    if (typeof definition.oauth.clientUri !== "string") {
-      throw new Error("OAuth clientUri must be a string")
-    }
-    const clientUri = interpolateEnvVars(definition.oauth.clientUri).trim()
-    if (!clientUri) {
-      throw new Error("OAuth clientUri must not be empty")
-    }
-    config.clientUri = clientUri
-  }
-  return config
-}
-
-async function probeAuthDiscovery(serverUrl: string, definition?: ServerEntry, signal?: AbortSignal): Promise<AuthDiscovery> {
-  // Discovery must not execute config commands or send their source text.
-  const discoveryHeaders = definition?.headers
-    ? Object.fromEntries(Object.entries(definition.headers).filter(([, value]) => !value.startsWith("!") || value.startsWith("!!")))
-    : undefined
-  const headers = new Headers(interpolateEnvRecord(discoveryHeaders))
-  const timeout = normalizeRequestTimeoutMs(definition?.requestTimeoutMs) ?? 5000
-  const discoverySignal = combineAbortSignals(signal, AbortSignal.timeout(Math.ceil(timeout)))
-  let discovery: AuthDiscovery = {}
-  const client = new Client({ name: "pi-mcp-auth-discovery", version: "4.3.1" }, {
-    versionNegotiation: { mode: definition?.protocolVersion ?? "auto" },
-    ...(isNonInteractiveOAuth(definition?.oauth)
-      ? { capabilities: { extensions: { [definition?.oauth && definition.oauth.crossAppAccess
-        ? "io.modelcontextprotocol/enterprise-managed-authorization" : "io.modelcontextprotocol/oauth-client-credentials"]: {} } } } : {}),
-  })
-  const transport = new StreamableHTTPClientTransport(new URL(serverUrl), {
-    requestInit: { headers },
-    fetch: async (input, init) => {
-      const response = await fetch(input, init)
-      const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(response)
-      discovery = { ...(resourceMetadataUrl ? { resourceMetadataUrl } : {}), ...(scope ? { scope } : {}) }
-      return response
-    },
-  })
-  try {
-    await abortable(client.connect(transport, { timeout }), discoverySignal)
-  } catch (error) {
-    if (signal?.aborted) throwIfAborted(signal)
-  } finally {
-    await (client.transport ? client.close() : transport.close())
-  }
-  return discovery
-}
-
-function parseOAuthRedirectUri(redirectUri: string): { port: number; callbackHost: string; callbackPath: string } {
-  let url: URL
-  try {
-    url = new URL(redirectUri)
-  } catch (error) {
-    throw new Error(`Invalid OAuth redirectUri: ${redirectUri}`, { cause: error })
-  }
-
-  const hostname = url.hostname.toLowerCase()
-  const isLocalhost = hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1"
-  if (url.protocol !== "http:" || !isLocalhost) {
-    throw new Error("OAuth redirectUri must be an http:// localhost or loopback URI")
-  }
-
-  if (url.username || url.password) {
-    throw new Error("OAuth redirectUri must not include username or password")
-  }
-
-  if (url.hash) {
-    throw new Error("OAuth redirectUri must not include a fragment")
-  }
-
-  if (!url.port) {
-    throw new Error("OAuth redirectUri must include an explicit numeric port")
-  }
-
-  const port = Number.parseInt(url.port, 10)
-  if (!Number.isInteger(port) || port <= 0 || port > 65535) {
-    throw new Error("OAuth redirectUri must include an explicit numeric port")
-  }
-
-  const callbackHost = hostname === "[::1]" ? "::1" : hostname
-  return { port, callbackHost, callbackPath: url.pathname }
-}
-
-/**
- * Start OAuth authentication flow for a server.
- * Returns the authorization URL when browser authorization is required.
- */
-export const startAuth: typeof startAuthOperation = async (...args) =>
-  withOAuthOperation(getRuntime(args[3]), () => startAuthOperation(...args))
-
-async function startAuthOperation(
-  serverName: string,
-  serverUrl: string,
-  definition?: ServerEntry,
-  options: AuthenticateOptions = {},
-): Promise<{ authorizationUrl: string }> {
-  if (isServerDisabled(definition)) throw new Error(`MCP server "${serverName}" is disabled`)
-  const runtime = getRuntime(options)
-  const runtimeState = getRuntimeState(runtime)
-  const config = definition ? extractOAuthConfig(definition) : {}
-  const authStorageOptions = options.authStorageOptions ?? {}
-  const signal = combineAbortSignals(runtime.signal, options.signal)
-  const generation = runtimeState.generation
-  throwIfAborted(signal)
-
-  if (isNonInteractiveOAuth(config)) {
-    const storedAuth = await getAuthForUrl(serverName, serverUrl, authStorageOptions)
-    if (!config.crossAppAccess && storedAuth?.clientInfo && !storedAuth.tokens && !config.clientId) {
-      clearClientInfo(serverName, authStorageOptions)
-      clearCodeVerifier(serverName, authStorageOptions)
-      await clearOAuthState(serverName, authStorageOptions)
-    }
-
-    const authProvider = new McpOAuthProvider(serverName, serverUrl, config, {
-      onRedirect: async () => {
-        throw new Error("Browser redirect is not used for noninteractive OAuth flows")
-      },
-    }, authStorageOptions, signal)
-    try {
-      const discovery = applyConfiguredScope(await probeAuthDiscovery(serverUrl, definition, signal), config)
-      throwIfAborted(signal)
-      const result = await abortable(runSdkAuth(authProvider, { serverUrl, ...discovery, fetchFn: authProvider.fetch }), signal)
-      throwIfAborted(signal)
-      if (result !== "AUTHORIZED") {
-        throw new UnauthorizedError("Failed to authorize")
-      }
-      return { authorizationUrl: "" }
-    } finally {
-      authProvider.deactivate()
-    }
-  }
-
-  const storageBase = getAuthBaseDir(authStorageOptions)
-  const request = getOAuthRequest(serverName, serverUrl, storageBase, runtime)
-  const existingPendingAuth = runtimeState.pendingAuths.get(getPendingAuthKey(serverName, authStorageOptions))
-  if (existingPendingAuth?.serverUrl === serverUrl) {
-    return { authorizationUrl: existingPendingAuth.authorizationUrl }
-  }
-
-  const redirectCallback = config.redirectUri !== undefined ? parseOAuthRedirectUri(config.redirectUri) : undefined
-  const oauthState = generateState()
-  const callbackIssuer: CallbackIssuer = {}
-
-  try {
-    await ensureCallbackServer({
-      strictPort: Boolean(config.clientId) || config.redirectUri !== undefined,
-      oauthState,
-      reserveState: true,
-      validate: response => validateCallbackIssuer(serverName, callbackIssuer, response),
-      ...(redirectCallback ? { port: redirectCallback.port, callbackHost: redirectCallback.callbackHost, callbackPath: redirectCallback.callbackPath } : {}),
-    })
-    throwIfAborted(signal)
-  } catch (error) {
-    releaseCallbackServer(oauthState)
-    try {
-      await clearOAuthState(serverName, authStorageOptions)
-    } catch (cleanupError) {
-      throw new AggregateError([error, cleanupError], "OAuth startup cleanup failed")
-    }
-    throw error
-  }
-
-  let capturedUrl: URL | undefined
-  let authProvider: McpOAuthProvider | undefined
-  try {
-    const storedAuth = await getAuthForUrl(serverName, serverUrl, authStorageOptions)
-    let discovery = applyConfiguredScope(await probeAuthDiscovery(serverUrl, definition, signal), config)
-    if (request?.challenge) {
-      const scope = computeScopeUnion(discovery.scope, request.requestedScope, storedAuth?.tokens?.scope, request.challenge.requiredScope)
-      discovery = { ...discovery, ...(scope ? { scope } : {}), ...(request.challenge.resourceMetadataUrl ? { resourceMetadataUrl: request.challenge.resourceMetadataUrl } : {}) }
-    }
-    throwIfAborted(signal)
-    const flowConfig = { ...config, ...(request?.challenge && discovery.scope ? { scope: discovery.scope } : {}) }
-    authProvider = new McpOAuthProvider(serverName, serverUrl, flowConfig, {
-      onRedirect: url => {
-        capturedUrl = url
-        const requestedScope = url.searchParams.get("scope") ?? undefined
-        if (requestedScope) {
-          discovery = { ...discovery, scope: requestedScope }
-          if (request?.challenge) flowConfig.scope = requestedScope
-        }
-        const current = getOAuthRequest(serverName, serverUrl, storageBase, runtime)
-        const scope = computeScopeUnion(current?.requestedScope, requestedScope)
-        if (current && scope) current.requestedScope = scope
-      },
-      onDiscoveryState: state => {
-        callbackIssuer.expectedIssuer = state.authorizationServerMetadata?.issuer
-        callbackIssuer.fallbackIssuer = state.authorizationServerUrl
-        callbackIssuer.issParameterSupported = state.authorizationServerMetadata?.authorization_response_iss_parameter_supported === true
-        bindOAuthRequestIssuer(serverName, serverUrl, storageBase, callbackIssuer.expectedIssuer ?? state.authorizationServerUrl, runtime)
-      },
-    }, authStorageOptions, runtime.signal, oauthState)
-    if (storedAuth?.clientInfo && !config.clientId) {
-      if (!storedAuth.tokens) {
-        clearClientInfo(serverName, authStorageOptions)
-        clearCodeVerifier(serverName, authStorageOptions)
-        await clearOAuthState(serverName, authStorageOptions)
-      } else {
-        const redirectUris = storedAuth.clientInfo.redirectUris
-        const redirectUrl = authProvider.redirectUrl ?? ""
-        const matchesRedirect = Array.isArray(redirectUris) && (redirectUris.includes(redirectUrl)
-          || (storedAuth.clientInfo.registrationType === "cimd"
-            && redirectUris.some(uri => loopbackRedirectsMatch(redirectUrl, uri))))
-        if (!matchesRedirect) {
-          clearClientInfo(serverName, authStorageOptions)
-          clearTokens(serverName, authStorageOptions)
-          clearCodeVerifier(serverName, authStorageOptions)
-          await clearOAuthState(serverName, authStorageOptions)
-        }
-      }
-    }
-
-    throwIfAborted(signal)
-
-    const result = await abortable(runSdkAuth(authProvider, {
-      serverUrl, ...discovery,
-      ...(request?.challenge ? { forceReauthorization: isStrictScopeSuperset(discovery.scope, storedAuth?.tokens?.scope) } : {}),
-    }), signal)
-    throwIfAborted(signal)
-    if (result === "AUTHORIZED") {
-      authProvider.deactivate()
-      releaseCallbackServer(oauthState)
-      await clearOAuthState(serverName, authStorageOptions)
-      return { authorizationUrl: "" }
-    }
-    if (!capturedUrl) {
-      throw new UnauthorizedError("OAuth authorization URL was not provided")
-    }
-    await setPendingAuth(runtime, serverName, { serverName, authProvider, serverUrl, authorizationUrl: capturedUrl.toString(), discovery, callbackIssuer: { ...callbackIssuer }, authStorageOptions, ...(request ? { request } : {}) }, oauthState, signal, generation)
-    return { authorizationUrl: capturedUrl.toString() }
-  } catch (error) {
-    authProvider?.deactivate()
-    try {
-      await clearPendingAuth(runtime, serverName, oauthState, authStorageOptions)
-    } catch (cleanupError) {
-      throw new AggregateError([error, cleanupError], "OAuth startup cleanup failed")
-    }
-    throw error
-  }
-}
-
-async function setPendingAuth(
-  runtime: McpOAuthRuntime,
-  serverName: string,
-  pendingAuth: PendingAuth,
-  oauthState: string,
-  signal?: AbortSignal,
-  generation = getRuntimeState(runtime).generation,
-): Promise<void> {
-  const state = getRuntimeState(runtime)
-  const key = getPendingAuthKey(serverName, pendingAuth.authStorageOptions)
-  await clearPendingAuth(runtime, serverName, undefined, pendingAuth.authStorageOptions)
-  throwIfAborted(signal)
-  if (generation !== state.generation) throw new Error("OAuth runtime stopped")
-  state.pendingAuths.set(key, pendingAuth)
-  state.pendingAuthStates.set(key, oauthState)
-  const cleanupTimer = setTimeout(() => {
-    void clearPendingAuth(runtime, serverName, oauthState, pendingAuth.authStorageOptions).catch(error => {
-      console.error(`MCP Auth: Timed-out flow cleanup failed: ${formatTerminalError(error)}`)
-    })
-  }, MANUAL_AUTH_TIMEOUT_MS)
-  cleanupTimer.unref?.()
-  state.pendingAuthCleanupTimers.set(key, cleanupTimer)
-}
-
-function clearPendingAuth(...args: Parameters<typeof clearPendingAuthOperation>): Promise<void> {
-  return withOAuthOperation(args[0], () => clearPendingAuthOperation(...args))
-}
-
-async function clearPendingAuthOperation(runtime: McpOAuthRuntime, serverName: string, oauthState?: string, fallbackStorageOptions: AuthStorageOptions = {}): Promise<void> {
-  const state = getRuntimeState(runtime)
-  const key = getPendingAuthKey(serverName, fallbackStorageOptions)
-  const pendingAuth = state.pendingAuths.get(key)
-  const authStorageOptions = pendingAuth?.authStorageOptions ?? fallbackStorageOptions
-  const pendingState = state.pendingAuthStates.get(key)
-  if (oauthState && pendingState && pendingState !== oauthState) return
-
-  const timer = state.pendingAuthCleanupTimers.get(key)
-  if (timer) {
-    clearTimeout(timer)
-    state.pendingAuthCleanupTimers.delete(key)
-  }
-
-  pendingAuth?.authProvider.deactivate()
-  state.pendingAuths.delete(key)
-  state.pendingAuthStates.delete(key)
-  const stateToRelease = pendingState ?? oauthState
-  if (stateToRelease) {
-    cancelPendingCallback(stateToRelease)
-    const storedState = await getOAuthState(serverName, authStorageOptions)
-    if (storedState === stateToRelease) {
-      await clearOAuthState(serverName, authStorageOptions)
-    }
-  }
-}
-
-function getSearchParamsFromInput(input: string): URLSearchParams | undefined {
-  try {
-    const url = new URL(input)
-    const params = new URLSearchParams(url.search)
-    if (url.hash) {
-      const hash = url.hash.startsWith("#") ? url.hash.slice(1) : url.hash
-      const hashParams = new URLSearchParams(hash)
-      for (const [key, value] of hashParams) {
-        if (!params.has(key)) params.set(key, value)
-      }
-    }
-    return params
-  } catch {
-    const query = input.includes("?") ? input.slice(input.indexOf("?") + 1) : input
-    const params = new URLSearchParams(query.startsWith("#") ? query.slice(1) : query)
-    return params.has("code") || params.has("state") || params.has("error") ? params : undefined
-  }
-}
-
-/** Authorization code plus the optional RFC 9207 `iss` callback parameter. */
-export interface AuthorizationCodeInput {
-  code: string
-  iss?: string
-}
-
-/**
- * Extract an OAuth authorization code (and the RFC 9207 `iss` parameter, when
- * present) from either a raw code, a query string, or the full localhost
- * redirect URL copied from the browser address bar.
- */
-type AuthorizationResponseInput = AuthorizationCodeInput | { error: string; errorDescription?: string; iss?: string; code?: never }
-
-export function parseAuthorizationRedirectInput(input: string, expectedState?: string): AuthorizationResponseInput {
-  const trimmed = input.trim()
-  if (!trimmed) {
-    throw new Error("Authorization code or redirect URL is required")
-  }
-
-  const params = getSearchParamsFromInput(trimmed)
-  if (params) {
-    const state = params.get("state")
-    if (expectedState && !state) {
-      throw new Error("OAuth state missing from redirect URL")
-    }
-    if (expectedState && state !== expectedState) {
-      throw new Error("OAuth state mismatch - potential CSRF attack")
-    }
-
-    const error = params.get("error")
-    if (error) {
-      const description = params.get("error_description")
-      const iss = params.get("iss")
-      return { error, ...(description !== null ? { errorDescription: description } : {}), ...(iss !== null ? { iss } : {}) }
-    }
-    const code = params.get("code")
-    if (code) {
-      const iss = params.get("iss")
-      return { code, ...(iss !== null ? { iss } : {}) }
-    }
-  }
-
-  if (/^[A-Za-z0-9._~+/=-]+$/.test(trimmed)) {
-    return { code: trimmed }
-  }
-
-  throw new Error("Could not find an OAuth authorization code in the provided input")
-}
-
-/**
- * Complete OAuth authentication from pasted input or a captured browser callback.
- */
-export async function completeAuthFromInput(
-  serverName: string,
-  input?: string,
-  options: AuthenticateOptions = {},
-): Promise<AuthStatus> {
-  const runtime = getRuntime(options)
-  const runtimeState = getRuntimeState(runtime)
-  const fallbackAuthStorageOptions = options.authStorageOptions ?? {}
-  const signal = combineAbortSignals(runtime.signal, options.signal)
-  throwIfAborted(signal)
-  const key = getPendingAuthKey(serverName, fallbackAuthStorageOptions)
-  const oauthState = runtimeState.pendingAuthStates.get(key)
-  throwIfAborted(signal)
-  const parsed = input === undefined ? undefined : parseAuthorizationRedirectInput(input, oauthState)
-  return completeAuth(serverName, parsed, options)
-}
-
-/**
- * Complete OAuth authentication with an explicit code or a captured callback.
- */
-export const completeAuth: typeof completeAuthOperation = async (...args) =>
-  withOAuthOperation(getRuntime(args[2]), () => completeAuthOperation(...args))
-
-async function completeAuthOperation(
-  serverName: string,
-  authorizationCode?: string | AuthorizationResponseInput,
-  options: AuthenticateOptions = {},
-): Promise<AuthStatus> {
-  const runtime = getRuntime(options)
-  const runtimeState = getRuntimeState(runtime)
-  const fallbackAuthStorageOptions = options.authStorageOptions ?? {}
-  const signal = combineAbortSignals(runtime.signal, options.signal)
-  throwIfAborted(signal)
-  const key = getPendingAuthKey(serverName, fallbackAuthStorageOptions)
-  const pendingAuth = runtimeState.pendingAuths.get(key)
-  const authStorageOptions = pendingAuth?.authStorageOptions ?? fallbackAuthStorageOptions
-  if (!pendingAuth) {
-    throw new Error(`No pending OAuth flow for server: ${serverName}. Run auth-start for this server first.`)
-  }
-
-  const oauthState = runtimeState.pendingAuthStates.get(key)
-  throwIfAborted(signal)
-  const response: AuthorizationResponseInput | undefined = typeof authorizationCode === "string" ? { code: authorizationCode }
-    : authorizationCode ?? (oauthState ? takeCallbackResult(oauthState) : undefined)
-  if (!response) {
-    throw new Error(
-      `No OAuth callback received yet for ${serverName}. Finish authorization in the browser, then retry auth-complete. ` +
-      "If the browser cannot reach this Pi session's callback, pass args: { redirectUrl: \"FULL_REDIRECT_URL\" } instead.",
-    )
-  }
-  const { iss } = response
-
-  let keepPendingForRetry = false
-  let caughtError: unknown
-  try {
-    keepPendingForRetry = iss === undefined && pendingAuth.callbackIssuer.issParameterSupported === true
-    validateCallbackIssuer(serverName, pendingAuth.callbackIssuer, response)
-    if ("error" in response) {
-      keepPendingForRetry = true
-      throw new Error(response.errorDescription ? `${response.error}: ${response.errorDescription}` : response.error)
-    }
-
-    const result = await abortable(runSdkAuth(pendingAuth.authProvider, {
-      serverUrl: pendingAuth.serverUrl,
-      authorizationCode: response.code,
-      ...(iss !== undefined ? { iss } : {}),
-      ...pendingAuth.discovery,
-    }), signal)
-    throwIfAborted(signal)
-    if (result !== "AUTHORIZED") {
-      throw new UnauthorizedError("Failed to authorize")
-    }
-    const request = pendingAuth.request
-    if (request?.challenge?.requiredScope
-      && request === getOAuthRequest(serverName, pendingAuth.serverUrl, getAuthBaseDir(authStorageOptions), runtime)) {
-      const issuedScope = (await getAuthForUrl(serverName, pendingAuth.serverUrl, authStorageOptions))?.tokens?.scope
-      if (issuedScope !== undefined && !isStrictScopeSuperset(request.challenge.requiredScope, issuedScope)) delete request.challenge
-    }
-    return "authenticated"
-  } catch (error) {
-    caughtError = error
-    throw error
-  } finally {
-    if (!keepPendingForRetry) {
-      try {
-        await clearPendingAuth(runtime, serverName, oauthState, authStorageOptions)
-      } catch (cleanupError) {
-        if (caughtError !== undefined) {
-          throw new AggregateError([caughtError, cleanupError], "OAuth completion cleanup failed")
-        }
-        throw cleanupError
-      }
-    }
-  }
-}
-
-/**
- * Perform the complete OAuth authentication flow for a server.
- * 
- * @param serverName - The name of the MCP server
- * @param serverUrl - The URL of the MCP server  
- * @param definition - The server definition (optional)
- * @returns The final auth status
- */
-export async function authenticate(
-  serverName: string,
-  serverUrl: string,
-  definition?: ServerEntry,
-  options: AuthenticateOptions = {},
-): Promise<AuthStatus> {
-  if (isServerDisabled(definition)) throw new Error(`MCP server "${serverName}" is disabled`)
-  const runtime = getRuntime(options)
-  const runtimeState = getRuntimeState(runtime)
-  const authStorageOptions = options.authStorageOptions ?? {}
-  const signal = combineAbortSignals(runtime.signal, options.signal)
-  throwIfAborted(signal)
-  const authKey = JSON.stringify([serverName, serverUrl, getAuthBaseDir(authStorageOptions)])
-  const inFlight = runtimeState.pendingAuthentications.get(authKey)
-  if (inFlight) {
-    return inFlight
-  }
-
-  const operation = (async (): Promise<AuthStatus> => {
-    // Start auth flow
-    const { authorizationUrl } = await startAuth(serverName, serverUrl, definition, {
-      ...options,
-      ...(signal ? { signal } : {}),
-      runtime,
-    })
-
-    // If no auth URL needed, already authenticated
-    if (!authorizationUrl) {
-      return "authenticated"
-    }
-
-    let oauthState: string | undefined
-    try {
-      // Get the state that was already generated and stored in startAuth().
-      // Keep this lookup and its abort check inside the cleanup boundary because
-      // startAuth has already reserved callback state at this point.
-      oauthState = runtimeState.pendingAuthStates.get(getPendingAuthKey(serverName, authStorageOptions))
-      throwIfAborted(signal)
-      if (!oauthState) {
-        throw new Error("OAuth state not found - this should not happen")
-      }
-
-      // Register the callback BEFORE opening the browser.
-      const callbackPromise = waitForCallback(oauthState)
-      void callbackPromise.catch(() => {})
-
-      // Open browser. Always surface the URL first so remote/headless users can copy it
-      // even when the OS browser handoff is unavailable or invisible.
-      if (options.onAuthorizationUrl) {
-        await abortable(Promise.resolve(options.onAuthorizationUrl(authorizationUrl)), signal)
-      } else {
-        console.log(`MCP Auth: Open this URL to authenticate ${serverName}:\n${authorizationUrl}`)
-      }
-      try {
-        await abortable(open(authorizationUrl), signal)
-      } catch (error) {
-        if (isAbortError(error, signal)) throw error
-        console.warn(`MCP Auth: Failed to open browser for ${serverName}; waiting for manual callback`, { error })
-      }
-
-      // Wait for callback
-      const callbackResult = await abortable(callbackPromise, signal)
-
-      // The callback server accepted only the flow-local reserved state.
-      throwIfAborted(signal)
-
-      // Complete the auth
-      return await completeAuth(serverName, callbackResult, {
-        ...options,
-        ...(signal ? { signal } : {}),
-        runtime,
-      })
-    } catch (error) {
-      if (oauthState) cancelPendingCallback(oauthState)
-      try {
-        await clearPendingAuth(runtime, serverName, oauthState, authStorageOptions)
-      } catch (cleanupError) {
-        throw new AggregateError([error, cleanupError], "OAuth cancellation cleanup failed")
-      }
-      throw error
-    }
-  })()
-
-  runtimeState.pendingAuthentications.set(authKey, operation)
-
-  try {
-    return await operation
-  } finally {
-    if (runtimeState.pendingAuthentications.get(authKey) === operation) {
-      runtimeState.pendingAuthentications.delete(authKey)
-    }
-  }
-}
-
-/**
- * Remove all OAuth credentials for a server.
- * 
- * @param serverName - The name of the MCP server
- */
-export const removeAuth: typeof removeAuthOperation = async (...args) =>
-  withOAuthOperation(getRuntime(args[1]), () => removeAuthOperation(...args))
-
-async function removeAuthOperation(serverName: string, options: AuthenticateOptions = {}): Promise<void> {
-  const runtime = getRuntime(options)
-  const signal = combineAbortSignals(runtime.signal, options.signal)
-  throwIfAborted(signal)
-  const authStorageOptions = options.authStorageOptions ?? {}
-  const oauthState = await getOAuthState(serverName, authStorageOptions)
-  throwIfAborted(signal)
-  if (oauthState) {
-    cancelPendingCallback(oauthState)
-  }
-  await clearPendingAuth(runtime, serverName, oauthState, authStorageOptions)
-  throwIfAborted(signal)
-  for (const [key, request] of getRuntimeState(runtime).requests) {
-    if (request.serverName === serverName) getRuntimeState(runtime).requests.delete(key)
-  }
-  clearAllCredentials(serverName, authStorageOptions)
-  await clearOAuthState(serverName, authStorageOptions)
-  throwIfAborted(signal)
-  console.log(`MCP Auth: Removed credentials for ${serverName}`)
-}
-
-/**
- * Check if OAuth is supported for a server configuration.
- * OAuth is supported for HTTP servers unless explicitly disabled.
- * 
- * @param definition - The server definition
- * @returns True if OAuth is supported
- */
-export function supportsOAuth(definition: ServerEntry): boolean {
-  // OAuth requires a URL
-  if (!definition.url) return false
-  
-  // Explicitly disabled via auth: false or oauth: false
-  if (definition.auth === false) return false
-  if (definition.oauth === false) return false
-  if (definition.auth === "oauth") return true
-  
-  // Configured custom headers take precedence over implicit OAuth auto-detection.
-  if (definition.headers && Object.keys(definition.headers).length > 0) return false
-
-  // OAuth is enabled when auth is not specified (auto-detect)
-  return definition.auth === undefined
-}
-
-/**
- * Initialize the OAuth system on startup.
- * OAuth callback binding is lazy and starts from startAuth() only.
- */
-export async function initializeOAuth(
-  runtimeOrSignal?: McpOAuthRuntime | AbortSignal,
-): Promise<McpOAuthRuntime> {
-  if (runtimeOrSignal && "signal" in runtimeOrSignal) {
-    runtimeOrSignal.signal.throwIfAborted()
-    activeRuntimes.add(runtimeOrSignal)
-    return runtimeOrSignal
-  }
-
-  await shutdownOAuth(legacyRuntime)
-  legacyRuntime = createOAuthRuntime(runtimeOrSignal as AbortSignal | undefined)
-  return legacyRuntime
-}
-
-/**
- * Shutdown one OAuth runtime. The callback server remains process-shared while
- * another runtime has pending/reserved callback state or is still active.
- */
-export async function shutdownOAuth(runtime: McpOAuthRuntime = legacyRuntime): Promise<void> {
-  const state = getRuntimeState(runtime)
-  if (state.controller.signal.aborted) return
-  state.checkpoint?.invalidate()
-  state.generation += 1
-  state.controller.abort(new Error("OAuth runtime stopped"))
-  for (const callbackState of Array.from(state.pendingAuthStates.values())) cancelPendingCallback(callbackState)
-  const results = await Promise.allSettled(Array.from(state.pendingAuths.values(), pendingAuth =>
-    clearPendingAuth(runtime, pendingAuth.serverName, undefined, pendingAuth.authStorageOptions)))
-  const failures = results.flatMap(result => result.status === "rejected" ? [result.reason] : [])
-  state.pendingAuthentications.clear()
-  state.requests.clear()
-  activeRuntimes.delete(runtime)
-
-  if (activeRuntimes.size === 0) {
-    try { await stopCallbackServer() } catch (error) { failures.push(error) }
-  }
-  if (failures.length) throw new AggregateError(failures, "MCP OAuth cleanup failed")
-}