@duckmind/dm-windows-x64 0.63.6 → 0.63.9

package/extensions/dm-mcp-adapter/mcp-auth-flow.js

@@ -0,0 +1,824 @@
+import {
+  auth as runSdkAuth,
+  extractWWWAuthenticateParams,
+  LATEST_PROTOCOL_VERSION,
+  UnauthorizedError
+} from "@modelcontextprotocol/client";
+import open from "open";
+import { McpOAuthProvider } from "./mcp-oauth-provider.js";
+import {
+  ensureCallbackServer,
+  waitForCallback,
+  cancelPendingCallback,
+  stopCallbackServer,
+  stopCallbackServerIfIdle,
+  releaseCallbackServer
+} from "./mcp-callback-server.js";
+import {
+  getAuthForUrl,
+  isTokenExpired,
+  hasStoredTokens,
+  clearAllCredentials,
+  clearClientInfo,
+  clearTokens,
+  clearCodeVerifier,
+  getOAuthState,
+  clearOAuthState,
+  getAuthBaseDir,
+  OAuthCredentialStoreError
+} from "./mcp-auth.js";
+import { isServerDisabled } from "./types.js";
+import { formatTerminalError, interpolateEnvRecord, interpolateEnvVars } from "./utils.js";
+import { abortable, throwIfAborted } from "./abort.js";
+import { combineAbortSignals, isAbortError } from "./runtime-owner.js";
+function applyOAuthConfig(discovery, config) {
+  return {
+    ...discovery,
+    ...config.scope !== undefined ? { scope: config.scope } : {},
+    ...config.skipIssuerMetadataValidation === true ? { skipIssuerMetadataValidation: true } : {}
+  };
+}
+const runtimeStates = new WeakMap;
+const activeRuntimes = new Set;
+export function createOAuthRuntime(signal) {
+  const controller = new AbortController;
+  const runtime = { signal: combineAbortSignals(signal, controller.signal) };
+  runtimeStates.set(runtime, {
+    controller,
+    generation: 0,
+    pendingAuths: new Map,
+    pendingAuthStates: new Map,
+    pendingAuthCleanupTimers: new Map,
+    pendingAuthentications: new Map
+  });
+  activeRuntimes.add(runtime);
+  return runtime;
+}
+let legacyRuntime = createOAuthRuntime();
+activeRuntimes.delete(legacyRuntime);
+function getRuntime(options) {
+  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) {
+  const state = runtimeStates.get(runtime);
+  if (!state)
+    throw new Error("Unknown OAuth runtime");
+  return state;
+}
+function getPendingAuthKey(serverName, options) {
+  return `${serverName}|${getAuthBaseDir(options)}`;
+}
+export function hasPendingAuth(serverName, options, runtime) {
+  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);
+}
+const MANUAL_AUTH_TIMEOUT_MS = 5 * 60 * 1000;
+function generateState() {
+  return Array.from(crypto.getRandomValues(new Uint8Array(32))).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+export function extractOAuthConfig(definition) {
+  if (definition.oauth === false) {
+    return {};
+  }
+  const config = {};
+  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");
+    config.clientSecret = definition.oauth.clientSecret.startsWith("!") ? definition.oauth.clientSecret : interpolateEnvVars(definition.oauth.clientSecret);
+  }
+  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;
+  }
+  if (definition.oauth?.logoUri !== undefined) {
+    if (typeof definition.oauth.logoUri !== "string") {
+      throw new Error("OAuth logoUri must be a string");
+    }
+    const logoUri = interpolateEnvVars(definition.oauth.logoUri).trim();
+    if (!logoUri) {
+      throw new Error("OAuth logoUri must not be empty");
+    }
+    let parsed;
+    try {
+      parsed = new URL(logoUri);
+    } catch {
+      throw new Error("OAuth logoUri must be an absolute http(s) URL");
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+      throw new Error("OAuth logoUri must be an absolute http(s) URL");
+    }
+    config.logoUri = logoUri;
+  }
+  if (definition.oauth?.authServerMetadataUrl !== undefined) {
+    if (typeof definition.oauth.authServerMetadataUrl !== "string") {
+      throw new Error("OAuth authServerMetadataUrl must be a string");
+    }
+    const authServerMetadataUrl = interpolateEnvVars(definition.oauth.authServerMetadataUrl).trim();
+    if (!authServerMetadataUrl) {
+      throw new Error("OAuth authServerMetadataUrl must not be empty");
+    }
+    let parsed;
+    try {
+      parsed = new URL(authServerMetadataUrl);
+    } catch {
+      throw new Error("OAuth authServerMetadataUrl must be an absolute https:// URL");
+    }
+    if (parsed.protocol !== "https:") {
+      throw new Error("OAuth authServerMetadataUrl must be an absolute https:// URL");
+    }
+    config.authServerMetadataUrl = authServerMetadataUrl;
+  }
+  if (definition.oauth?.skipIssuerMetadataValidation !== undefined) {
+    if (typeof definition.oauth.skipIssuerMetadataValidation !== "boolean") {
+      throw new Error("OAuth skipIssuerMetadataValidation must be a boolean");
+    }
+    config.skipIssuerMetadataValidation = definition.oauth.skipIssuerMetadataValidation;
+  }
+  return config;
+}
+async function probeAuthDiscovery(serverUrl, definition, signal) {
+  const discoveryHeaders = definition?.headers ? Object.fromEntries(Object.entries(definition.headers).filter(([, value]) => !value.startsWith("!") || value.startsWith("!!"))) : undefined;
+  const headers = new Headers(interpolateEnvRecord(discoveryHeaders));
+  headers.set("content-type", "application/json");
+  const controller = new AbortController;
+  const discoverySignal = combineAbortSignals(signal, controller.signal);
+  const timer = setTimeout(() => controller.abort(), 5000);
+  try {
+    headers.set("accept", "application/json, text/event-stream");
+    const response = await fetch(new URL(serverUrl), {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 0,
+        method: "initialize",
+        params: {
+          protocolVersion: LATEST_PROTOCOL_VERSION,
+          capabilities: {},
+          clientInfo: { name: "dm-mcp-adapter", version: "2.11.0" }
+        }
+      }),
+      ...discoverySignal ? { signal: discoverySignal } : {}
+    });
+    const { resourceMetadataUrl, scope } = extractWWWAuthenticateParams(response);
+    await response.body?.cancel().catch(() => {});
+    return { ...resourceMetadataUrl ? { resourceMetadataUrl } : {}, ...scope ? { scope } : {} };
+  } catch (error) {
+    if (signal?.aborted)
+      throwIfAborted(signal);
+    return {};
+  } finally {
+    clearTimeout(timer);
+  }
+}
+function parseOAuthRedirectUri(redirectUri) {
+  let url;
+  try {
+    url = new URL(redirectUri);
+  } catch (error) {
+    throw new Error(`Invalid OAuth redirectUri: ${redirectUri}`, { cause: error });
+  }
+  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");
+  }
+  const hostname = url.hostname.toLowerCase();
+  const isLocalhost = hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1";
+  if (url.port) {
+    const parsedPort = Number.parseInt(url.port, 10);
+    if (!Number.isInteger(parsedPort) || parsedPort <= 0 || parsedPort > 65535) {
+      throw new Error("OAuth redirectUri port must be a positive numeric port");
+    }
+  }
+  if (url.protocol === "https:" && !isLocalhost) {
+    return { mode: "manual" };
+  }
+  if (url.protocol !== "http:" || !isLocalhost) {
+    throw new Error("OAuth redirectUri must be an https:// URI or an http:// localhost or loopback URI");
+  }
+  if (!url.port) {
+    throw new Error("OAuth localhost 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 localhost redirectUri must include an explicit numeric port");
+  }
+  const callbackHost = hostname === "[::1]" ? "::1" : hostname;
+  return { mode: "local", port, callbackHost, callbackPath: url.pathname };
+}
+export async function startAuth(serverName, serverUrl, definition, options = {}) {
+  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 (config.grantType === "client_credentials") {
+    const storedAuth = await getAuthForUrl(serverName, serverUrl, authStorageOptions);
+    if (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 client_credentials flow");
+      }
+    }, authStorageOptions, runtime.signal);
+    try {
+      const discovery = applyOAuthConfig(await probeAuthDiscovery(serverUrl, definition, signal), config);
+      throwIfAborted(signal);
+      const result = await abortable(runSdkAuth(authProvider, { serverUrl, ...discovery }), signal);
+      throwIfAborted(signal);
+      if (result !== "AUTHORIZED") {
+        throw new UnauthorizedError("Failed to authorize");
+      }
+      return { authorizationUrl: "" };
+    } finally {
+      authProvider.deactivate();
+    }
+  }
+  const existingPendingAuth = runtimeState.pendingAuths.get(getPendingAuthKey(serverName, authStorageOptions));
+  if (existingPendingAuth?.serverUrl === serverUrl) {
+    return { authorizationUrl: existingPendingAuth.authorizationUrl };
+  }
+  const redirectTarget = config.redirectUri !== undefined ? parseOAuthRedirectUri(config.redirectUri) : undefined;
+  const manualRedirect = redirectTarget?.mode === "manual";
+  const oauthState = generateState();
+  if (!manualRedirect) {
+    try {
+      await ensureCallbackServer({
+        strictPort: Boolean(config.clientId) || config.redirectUri !== undefined,
+        oauthState,
+        reserveState: true,
+        ...redirectTarget?.mode === "local" ? { port: redirectTarget.port, callbackHost: redirectTarget.callbackHost, callbackPath: redirectTarget.callbackPath } : {}
+      });
+      throwIfAborted(signal);
+    } catch (error) {
+      releaseCallbackServer(oauthState);
+      try {
+        await cleanupAndReleaseCallbackServerIfIdle(() => clearOAuthState(serverName, authStorageOptions));
+      } catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], "OAuth startup cleanup failed");
+      }
+      throw error;
+    }
+  }
+  let capturedUrl;
+  const authProvider = new McpOAuthProvider(serverName, serverUrl, config, {
+    onRedirect: async (url) => {
+      capturedUrl = url;
+    }
+  }, authStorageOptions, runtime.signal, oauthState);
+  try {
+    const storedAuth = await getAuthForUrl(serverName, serverUrl, authStorageOptions);
+    if (storedAuth?.clientInfo && !config.clientId) {
+      if (!storedAuth.tokens) {
+        clearClientInfo(serverName, authStorageOptions);
+        clearCodeVerifier(serverName, authStorageOptions);
+        await clearOAuthState(serverName, authStorageOptions);
+      } else {
+        const redirectUris = storedAuth.clientInfo.redirectUris;
+        if (!Array.isArray(redirectUris) || !redirectUris.includes(authProvider.redirectUrl ?? "")) {
+          clearClientInfo(serverName, authStorageOptions);
+          clearTokens(serverName, authStorageOptions);
+          clearCodeVerifier(serverName, authStorageOptions);
+          await clearOAuthState(serverName, authStorageOptions);
+        }
+      }
+    }
+    throwIfAborted(signal);
+    const discovery = applyOAuthConfig(await probeAuthDiscovery(serverUrl, definition, signal), config);
+    throwIfAborted(signal);
+    const result = await abortable(runSdkAuth(authProvider, { serverUrl, ...discovery }), signal);
+    throwIfAborted(signal);
+    if (result === "AUTHORIZED") {
+      authProvider.deactivate();
+      releaseCallbackServer(oauthState);
+      await clearOAuthState(serverName, authStorageOptions);
+      await stopCallbackServerIfIdle();
+      return { authorizationUrl: "" };
+    }
+    if (!capturedUrl) {
+      throw new UnauthorizedError("OAuth authorization URL was not provided");
+    }
+    await setPendingAuth(runtime, serverName, {
+      serverName,
+      authProvider,
+      serverUrl,
+      authorizationUrl: capturedUrl.toString(),
+      manualRedirect,
+      ...manualRedirect ? { manualCompletionController: new AbortController } : {},
+      discovery,
+      authStorageOptions
+    }, oauthState, signal, generation);
+    return { authorizationUrl: capturedUrl.toString() };
+  } catch (error) {
+    authProvider.deactivate();
+    try {
+      await clearPendingAuthAndReleaseIfIdle(runtime, serverName, oauthState, authStorageOptions);
+    } catch (cleanupError) {
+      throw new AggregateError([error, cleanupError], "OAuth startup cleanup failed");
+    }
+    throw error;
+  }
+}
+async function setPendingAuth(runtime, serverName, pendingAuth, oauthState, signal, generation = getRuntimeState(runtime).generation) {
+  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(() => {
+    clearPendingAuthAndReleaseIfIdle(runtime, serverName, oauthState, pendingAuth.authStorageOptions, new Error("OAuth authorization timeout - authorization took too long")).catch((error) => {
+      console.error(`MCP Auth: Timed-out flow cleanup failed: ${formatTerminalError(error)}`);
+    });
+  }, MANUAL_AUTH_TIMEOUT_MS);
+  cleanupTimer.unref?.();
+  state.pendingAuthCleanupTimers.set(key, cleanupTimer);
+}
+async function clearPendingAuth(runtime, serverName, oauthState, fallbackStorageOptions = {}, reason = new Error("Authorization cancelled")) {
+  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?.manualCompletionController?.abort(reason);
+  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);
+    }
+  }
+}
+async function clearPendingAuthAndReleaseIfIdle(runtime, serverName, oauthState, fallbackStorageOptions = {}, reason) {
+  await cleanupAndReleaseCallbackServerIfIdle(() => clearPendingAuth(runtime, serverName, oauthState, fallbackStorageOptions, reason));
+}
+async function cleanupAndReleaseCallbackServerIfIdle(cleanup) {
+  let cleanupFailure;
+  try {
+    await cleanup();
+  } catch (error) {
+    cleanupFailure = { error };
+  }
+  try {
+    await stopCallbackServerIfIdle();
+  } catch (releaseError) {
+    if (cleanupFailure) {
+      throw new AggregateError([cleanupFailure.error, releaseError], "OAuth callback cleanup failed");
+    }
+    throw releaseError;
+  }
+  if (cleanupFailure)
+    throw cleanupFailure.error;
+}
+function getSearchParamsFromInput(input) {
+  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;
+  }
+}
+export function parseAuthorizationRedirectInput(input, expectedState) {
+  const trimmed = input.trim();
+  if (!trimmed) {
+    throw new Error("Authorization code or redirect URL is required");
+  }
+  const params = getSearchParamsFromInput(trimmed);
+  if (params) {
+    const error = params.get("error");
+    if (error) {
+      const description = params.get("error_description");
+      throw new Error(description ? `${error}: ${description}` : error);
+    }
+    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 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");
+}
+export function parseAuthorizationCodeInput(input, expectedState) {
+  return parseAuthorizationRedirectInput(input, expectedState).code;
+}
+function waitForManualCompletionCancellation(signal) {
+  return new Promise((_, reject) => {
+    const rejectFromSignal = () => {
+      reject(signal.reason instanceof Error ? signal.reason : new Error("Authorization cancelled"));
+    };
+    if (signal.aborted) {
+      rejectFromSignal();
+      return;
+    }
+    signal.addEventListener("abort", rejectFromSignal, { once: true });
+  });
+}
+export async function waitForAuthorizationResponse(callbackPromise, authorizationUrl, expectedState, onAuthorizationInput, signal) {
+  if (!onAuthorizationInput) {
+    return {
+      input: await abortable(callbackPromise, signal),
+      source: "callback"
+    };
+  }
+  const inputController = new AbortController;
+  try {
+    const response = await abortable(Promise.race([
+      callbackPromise.then((input) => ({ input, source: "callback" })),
+      onAuthorizationInput(authorizationUrl, inputController.signal).then((input) => ({
+        input,
+        source: "manual"
+      }))
+    ]), signal);
+    if (response.source === "callback")
+      return response;
+    if (!response.input?.trim())
+      throw new Error("OAuth authentication cancelled");
+    if (!getSearchParamsFromInput(response.input.trim())) {
+      throw new Error("Paste the full OAuth callback URL, including its code and state parameters");
+    }
+    return {
+      input: parseAuthorizationRedirectInput(response.input, expectedState),
+      source: "manual"
+    };
+  } finally {
+    inputController.abort();
+  }
+}
+export async function completeAuthFromInput(serverName, input, options = {}) {
+  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);
+  const pendingAuth = runtimeState.pendingAuths.get(key);
+  throwIfAborted(signal);
+  if (pendingAuth?.manualRedirect && !getSearchParamsFromInput(input.trim())) {
+    throw new Error("Paste the full OAuth callback URL, including its code and state parameters");
+  }
+  const parsed = parseAuthorizationRedirectInput(input, oauthState);
+  return completeAuth(serverName, parsed, options);
+}
+export async function completeAuth(serverName, authorizationCode, options = {}) {
+  const runtime = getRuntime(options);
+  const runtimeState = getRuntimeState(runtime);
+  const { code, iss } = typeof authorizationCode === "string" ? { code: authorizationCode, iss: undefined } : authorizationCode;
+  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}`);
+  }
+  const oauthState = runtimeState.pendingAuthStates.get(key);
+  throwIfAborted(signal);
+  let keepPendingForRetry = false;
+  let caughtError;
+  try {
+    const discoveryState = await pendingAuth.authProvider.discoveryState();
+    const metadata = discoveryState?.authorizationServerMetadata;
+    const expectedIssuer = metadata?.issuer ?? discoveryState?.authorizationServerUrl;
+    const requiresIssuer = metadata?.authorization_response_iss_parameter_supported === true;
+    if (expectedIssuer !== undefined && iss === undefined && requiresIssuer) {
+      keepPendingForRetry = true;
+      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).");
+    }
+    if (expectedIssuer !== undefined && iss !== undefined && iss !== expectedIssuer) {
+      throw new Error(`The OAuth authorization response issuer does not match the discovered issuer for ${serverName}.`);
+    }
+    const result = await abortable(runSdkAuth(pendingAuth.authProvider, {
+      serverUrl: pendingAuth.serverUrl,
+      authorizationCode: code,
+      ...iss !== undefined ? { iss } : {},
+      ...pendingAuth.discovery
+    }), signal);
+    throwIfAborted(signal);
+    if (result !== "AUTHORIZED") {
+      throw new UnauthorizedError("Failed to authorize");
+    }
+    return "authenticated";
+  } catch (error) {
+    caughtError = error;
+    throw error;
+  } finally {
+    if (!keepPendingForRetry) {
+      try {
+        await clearPendingAuthAndReleaseIfIdle(runtime, serverName, oauthState, authStorageOptions);
+      } catch (cleanupError) {
+        if (caughtError !== undefined) {
+          throw new AggregateError([caughtError, cleanupError], "OAuth completion cleanup failed");
+        }
+        throw cleanupError;
+      }
+    }
+  }
+}
+export async function authenticate(serverName, serverUrl, definition, options = {}) {
+  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 = `${serverName}|${serverUrl}|${getAuthBaseDir(authStorageOptions)}`;
+  const inFlight = runtimeState.pendingAuthentications.get(authKey);
+  if (inFlight) {
+    return inFlight;
+  }
+  const operation = (async () => {
+    const { authorizationUrl } = await startAuth(serverName, serverUrl, definition, {
+      ...options,
+      ...signal ? { signal } : {},
+      runtime
+    });
+    if (!authorizationUrl) {
+      return "authenticated";
+    }
+    let oauthState;
+    try {
+      oauthState = runtimeState.pendingAuthStates.get(getPendingAuthKey(serverName, authStorageOptions));
+      throwIfAborted(signal);
+      if (!oauthState) {
+        throw new Error("OAuth state not found - this should not happen");
+      }
+      const pendingAuth = runtimeState.pendingAuths.get(getPendingAuthKey(serverName, authStorageOptions));
+      if (!pendingAuth) {
+        throw new Error(`No pending OAuth flow for server: ${serverName}`);
+      }
+      if (pendingAuth.manualRedirect && !options.onAuthorizationInput) {
+        throw new Error(`OAuth for ${serverName} uses a remote redirect URI. Complete it with auth-start/auth-complete or /mcp-auth.`);
+      }
+      const callbackPromise = pendingAuth.manualRedirect ? waitForManualCompletionCancellation(pendingAuth.manualCompletionController.signal) : waitForCallback(oauthState);
+      callbackPromise.catch(() => {});
+      if (options.onAuthorizationUrl) {
+        await abortable(Promise.resolve(options.onAuthorizationUrl(authorizationUrl)), signal);
+      } else {
+        console.log(`MCP Auth: Open this URL to authenticate ${serverName}:
+${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 });
+      }
+      const authorizationResponse = await waitForAuthorizationResponse(callbackPromise, authorizationUrl, oauthState, options.onAuthorizationInput, signal);
+      if (authorizationResponse.source === "manual") {
+        cancelPendingCallback(oauthState);
+      }
+      throwIfAborted(signal);
+      return await completeAuth(serverName, authorizationResponse.input, {
+        ...options,
+        ...signal ? { signal } : {},
+        runtime
+      });
+    } catch (error) {
+      if (oauthState)
+        cancelPendingCallback(oauthState);
+      try {
+        await clearPendingAuthAndReleaseIfIdle(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);
+    }
+  }
+}
+export async function getValidToken(serverName, serverUrl, options = {}) {
+  const runtime = getRuntime(options);
+  const authStorageOptions = options.authStorageOptions ?? {};
+  const signal = combineAbortSignals(runtime.signal, options.signal);
+  throwIfAborted(signal);
+  const entry = await getAuthForUrl(serverName, serverUrl, authStorageOptions);
+  throwIfAborted(signal);
+  if (!entry?.tokens) {
+    return null;
+  }
+  const expired = await isTokenExpired(serverName, authStorageOptions);
+  if (expired === false) {
+    return entry.tokens;
+  }
+  if (expired === true && entry.tokens.refreshToken) {
+    console.log(`MCP Auth: Token expired for ${serverName}, attempting refresh`);
+    try {
+      const authProvider = new McpOAuthProvider(serverName, serverUrl, {}, {
+        onRedirect: async () => {}
+      }, authStorageOptions, runtime.signal);
+      try {
+        const clientInfo = await authProvider.clientInformation();
+        throwIfAborted(signal);
+        if (!clientInfo) {
+          console.log(`MCP Auth: No client info for refresh for ${serverName}`);
+          return null;
+        }
+        const discovery = await probeAuthDiscovery(serverUrl, undefined, signal);
+        throwIfAborted(signal);
+        const result = await abortable(runSdkAuth(authProvider, {
+          serverUrl,
+          ...discovery,
+          ...options.skipIssuerMetadataValidation === true ? { skipIssuerMetadataValidation: true } : {}
+        }), signal);
+        throwIfAborted(signal);
+        if (result !== "AUTHORIZED") {
+          return null;
+        }
+        const refreshed = await getAuthForUrl(serverName, serverUrl, authStorageOptions);
+        throwIfAborted(signal);
+        return refreshed?.tokens ?? null;
+      } finally {
+        authProvider.deactivate();
+      }
+    } catch (error) {
+      if (isAbortError(error, signal) || error instanceof OAuthCredentialStoreError)
+        throw error;
+      console.error(`MCP Auth: Token refresh failed for ${serverName}`, { error });
+      return null;
+    }
+  }
+  return entry.tokens;
+}
+export async function getAuthStatus(serverName, options = {}) {
+  getRuntime(options);
+  const authStorageOptions = options.authStorageOptions ?? {};
+  const hasTokens = await hasStoredTokens(serverName, authStorageOptions);
+  if (!hasTokens)
+    return "not_authenticated";
+  const expired = await isTokenExpired(serverName, authStorageOptions);
+  return expired ? "expired" : "authenticated";
+}
+export async function removeAuth(serverName, options = {}) {
+  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 clearPendingAuthAndReleaseIfIdle(runtime, serverName, oauthState, authStorageOptions);
+  throwIfAborted(signal);
+  clearAllCredentials(serverName, authStorageOptions);
+  await clearOAuthState(serverName, authStorageOptions);
+  throwIfAborted(signal);
+  console.log(`MCP Auth: Removed credentials for ${serverName}`);
+}
+export function supportsOAuth(definition) {
+  if (!definition.url)
+    return false;
+  if (definition.auth === false)
+    return false;
+  if (definition.oauth === false)
+    return false;
+  if (definition.auth === "oauth")
+    return true;
+  if (definition.headers && Object.keys(definition.headers).length > 0)
+    return false;
+  return definition.auth === undefined;
+}
+export async function initializeOAuth(runtimeOrSignal) {
+  if (runtimeOrSignal && "signal" in runtimeOrSignal) {
+    runtimeOrSignal.signal.throwIfAborted();
+    activeRuntimes.add(runtimeOrSignal);
+    return runtimeOrSignal;
+  }
+  await shutdownOAuth(legacyRuntime);
+  legacyRuntime = createOAuthRuntime(runtimeOrSignal);
+  return legacyRuntime;
+}
+export async function shutdownOAuth(runtime = legacyRuntime) {
+  const state = getRuntimeState(runtime);
+  if (state.controller.signal.aborted)
+    return;
+  state.generation += 1;
+  state.controller.abort(new Error("OAuth runtime stopped"));
+  for (const callbackState of Array.from(state.pendingAuthStates.values()))
+    cancelPendingCallback(callbackState);
+  for (const pendingAuth of Array.from(state.pendingAuths.values())) {
+    await clearPendingAuth(runtime, pendingAuth.serverName, undefined, pendingAuth.authStorageOptions);
+  }
+  state.pendingAuthentications.clear();
+  activeRuntimes.delete(runtime);
+  if (activeRuntimes.size === 0) {
+    await stopCallbackServer();
+  }
+}