Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

99.6 KB
Raw Blame
import { createHash } from 'crypto';
import { logger, getTenantId, tenantStorage } from '@librechat/data-schemas';
import type { OAuthClientInformation } from '@modelcontextprotocol/sdk/shared/auth.js';
import type { TokenMethods, TenantContext } from '@librechat/data-schemas';
import type { Tool } from '@modelcontextprotocol/sdk/types.js';
import type {
  MCPOAuthTokens,
  OAuthMetadata,
  MCPOAuthFlowMetadata,
  OAuthProtectedResourceMetadata,
  OAuthStoredClientMetadata,
  OAuthClientSource,
} from '~/mcp/oauth';
import type {
  OboTokenResolver,
  OboTrustChecker,
  UpstreamTokenProvider,
  UpstreamTokenProviderResolver,
} from '~/mcp/oauth/obo';
import type { AuthIdentityContext } from '~/utils/identity';
import type { FlowStateManager } from '~/flow/manager';
import type * as t from './types';
import {
  MCPTokenStorage,
  MCPTokenRefreshUnavailableError,
  MCPTokenStorageUnavailableError,
  MCPOAuthHandler,
  getMCPServerGeneration,
  getMCPOAuthLeaseId,
  OboTokenResolutionError,
  ReauthenticationRequiredError,
  resolveOboToken,
} from '~/mcp/oauth';
import {
  isOAuthAuthenticationError,
  isMCPTransportAuthenticationError,
  createScheduledMCPTransportError,
  MCPAuthenticationRejectedError,
  isMCPInitializationError,
} from './errors';
import {
  isOAuthServer,
  waitUntilDeadline,
  applyRequestHeaders,
  isClientRejectionMessage,
  createDeadlineAbortSignal,
  toCatalogConnectionConfig,
} from './utils';
import {
  resolveScheduledMCPBearerConfig,
  createScheduledMCPBearerHeaderResolver,
  isScheduledMCPBearer,
} from '~/schedules/bearer';
import {
  isDirectOpenIDBearerRecoveryEnabled,
  resolveDirectOpenIDBearerConfig,
  usesDirectOpenIDBearerRecovery,
} from './openid';
import { PENDING_STALE_MS, FlowStateNotFoundError, normalizeExpiresAt } from '~/flow/manager';
import { createLazyOboUpstreamTokenProvider, awaitOboOperation } from '~/mcp/oauth/obo';
import { preProcessGraphTokens } from '~/utils/graph';
import { isAbortError } from '~/utils/errors';
import { MCPConnection } from './connection';
import { processMCPEnv } from '~/utils';
import { mcpConfig } from './mcpConfig';

export interface ToolDiscoveryResult {
  tools: Tool[] | null;
  connection: MCPConnection | null;
  oauthRequired: boolean;
  oauthUrl: string | null;
  authenticationError?: unknown;
}

type OAuthRequiredEvent = {
  serverUrl?: string;
  error?: unknown;
  status?: number;
  statusCode?: number;
  skipSilentRefresh?: boolean;
  rejectedCredentialSetId?: string | null;
};

type OAuthRecoveryPhase = 'silent-refresh' | 'interactive' | 'terminal';

/**
 * Factory for creating MCP connections with optional OAuth authentication.
 * Handles OAuth flows, token management, and connection retry logic.
 * NOTE: Much of the OAuth logic was extracted from the old MCPManager class as is.
 */
export class MCPConnectionFactory {
  protected readonly serverName: string;
  protected readonly serverConfig: t.MCPOptions;
  /** Unresolved definition used for lifecycle fencing across request-specific substitutions. */
  protected readonly serverDefinition: t.MCPOptions;
  protected readonly logPrefix: string;
  protected readonly useOAuth: boolean;
  protected readonly useSSRFProtection: boolean;
  protected readonly allowedDomains?: string[] | null;
  protected readonly allowedAddresses?: string[] | null;
  protected readonly ephemeralConnection: boolean;
  protected readonly directBearerRecoveryEnabled: boolean;
  private readonly resolveRequestHeaders?: t.MCPRequestHeaderResolver;
  protected readonly capabilityProfile: t.BasicConnectionOptions['capabilityProfile'];
  protected readonly operationLimits: t.BasicConnectionOptions['operationLimits'];

  // OAuth-related properties (only set when useOAuth is true)
  protected readonly userId?: string;
  protected readonly user?: t.OAuthConnectionOptions['user'];
  protected readonly flowManager?: FlowStateManager<MCPOAuthTokens | null>;
  protected readonly tokenMethods?: TokenMethods;
  protected signal?: AbortSignal;
  protected oauthStart?: t.OAuthStartHandler;
  protected oauthEnd?: () => Promise<void>;
  protected returnOnOAuth?: boolean;
  protected readonly connectionTimeout?: number;
  protected readonly deadlineMs?: number;
  protected readonly onOAuthCredentialsChanged?: t.UserConnectionContext['onOAuthCredentialsChanged'];
  protected readonly onOAuthCredentialsChanging?: t.UserConnectionContext['onOAuthCredentialsChanging'];
  protected readonly onDiscoveryDetached?: t.UserConnectionContext['onDiscoveryDetached'];
  protected readonly onOAuthCredentialsAdopted?: t.UserConnectionContext['onOAuthCredentialsAdopted'];
  protected readonly onOAuthCredentialsInvalidated?: t.UserConnectionContext['onOAuthCredentialsInvalidated'];
  protected readonly oboTokenResolver?: OboTokenResolver;
  protected readonly oboTrustChecker?: OboTrustChecker;
  protected upstreamTokenProvider?: UpstreamTokenProvider;
  protected upstreamTokenProviderResolver?: UpstreamTokenProviderResolver;
  protected readonly oboIdentityContext?: AuthIdentityContext;
  /** Why the OBO re-exchange failed, when that is more actionable than the server's 401. */
  private oboRefreshError?: Error;
  private connectionReady = false;
  /**
   * Snapshot of the tenant context at factory construction time. Captured eagerly
   * because the OAuth handler runs later inside an EventEmitter callback,
   * outside the original request's async context - `getTenantId()` called
   * from the listener would return the wrong tenant (or none at all).
   */
  protected readonly tenantId?: string;
  protected readonly tenantContext?: TenantContext;

  /**
   * Process-local in-flight silent refresh promises, keyed by
   * `tenantId:userId:serverName:bindingDigest`. Coalesces concurrent `attemptSilentTokenRefresh`
   * calls within this process so a single refresh-token redemption serves every
   * waiter in the same tenant — important when multiple connections (or repeated
   * 401s) race the same refresh and the OAuth provider rotates refresh tokens.
   * The map only holds in-flight promises (no result caching), so each new 401
   * after the previous attempt resolves triggers a fresh redemption.
   *
   * NOTE: `MCPTokenStorage.forceRefreshTokens` additionally single-flights the
   * refresh-token redemption itself, covering the `mcp_get_tokens` and
   * reconnect paths that bypass this map. Both locks are process-local; the
   * cross-worker race is an inherent limitation and tracked separately.
   */
  private static inflightSilentRefreshes = new Map<string, Promise<MCPOAuthTokens | null>>();

  /**
   * Silent refresh is a best-effort optimization before interactive OAuth.
   * Keep the cap short so a stalled refresh still leaves most of the factory
   * connect budget for OAuth discovery, registration, and `oauthStart`.
   */
  private static readonly SILENT_REFRESH_TIMEOUT_MS = 5_000;
  private static readonly SILENT_REFRESH_ABORT_GRACE_MS = 1_000;

  /** Creates a new MCP connection with optional OAuth support */
  static async create(
    basic: t.BasicConnectionOptions,
    oauth?: t.OAuthConnectionOptions | t.UserConnectionContext,
  ): Promise<MCPConnection> {
    /** Chat-time entry point: the operator's `requestHeaders` join `headers`
     *  here, ahead of direct-bearer detection and Graph preprocessing, so an
     *  `Authorization` or `{{LIBRECHAT_GRAPH_*}}` template declared there gets
     *  exactly the handling it would get in `headers`. */
    const runtime: t.BasicConnectionOptions = {
      ...basic,
      serverConfig: applyRequestHeaders(basic.serverConfig),
      serverDefinition: basic.serverDefinition ?? basic.serverConfig,
    };
    const directBearerRecoveryState = runtime.directBearerRecoveryState ?? { attempted: false };
    const directBearerSourceConfig =
      runtime.directBearerSourceConfig ??
      (isDirectOpenIDBearerRecoveryEnabled(runtime.serverConfig)
        ? (runtime.serverConfig as t.ParsedServerConfig)
        : undefined);
    const create = async (candidate: t.BasicConnectionOptions): Promise<MCPConnection> => {
      const prepared = await this.prepareBasicConnectionOptions(
        { ...candidate, directBearerSourceConfig, directBearerRecoveryState },
        oauth,
      );
      if (directBearerSourceConfig && !directBearerRecoveryState.resolvedConfig) {
        directBearerRecoveryState.resolvedConfig = prepared.serverConfig;
      }
      const factory = new this(prepared, oauth);
      return factory.createConnection();
    };
    if (!directBearerSourceConfig) {
      return create(runtime);
    }

    try {
      return await create(runtime);
    } catch (error) {
      if (!isMCPTransportAuthenticationError(error) || this.isRequestCancelled(oauth)) {
        throw error;
      }
      if (directBearerRecoveryState.attempted) {
        throw new MCPAuthenticationRejectedError(basic.serverName, false, error);
      }
      if (isScheduledMCPBearer(oauth?.requestScopedConnections))
        throw createScheduledMCPTransportError(error, basic.serverName);
      directBearerRecoveryState.attempted = true;
      const refreshedConfig = await resolveDirectOpenIDBearerConfig({
        config: directBearerSourceConfig,
        upstreamTokenProvider: oauth?.upstreamTokenProvider,
        forceRefresh: true,
        signal: oauth?.signal,
      });
      directBearerRecoveryState.resolvedConfig = refreshedConfig;
      try {
        return await create({ ...runtime, serverConfig: refreshedConfig });
      } catch (refreshedError) {
        if (isMCPTransportAuthenticationError(refreshedError)) {
          throw new MCPAuthenticationRejectedError(basic.serverName, false, refreshedError);
        }
        throw refreshedError;
      }
    }
  }

  static attachRequestOAuthHandler(
    basic: t.BasicConnectionOptions,
    oauth: t.OAuthConnectionOptions,
    connection: MCPConnection,
  ): () => void {
    const factory = new this(basic, oauth);
    return factory.handleOAuthEvents(connection, 'oauthReauthenticationRequired');
  }

  /**
   * Discovers tools from an MCP server, even when OAuth is required.
   * Per MCP spec, tool listing should be possible without authentication.
   * Returns tools if discoverable, plus OAuth status for tool execution.
   */
  static async discoverTools(
    basic: t.BasicConnectionOptions,
    options?: Omit<t.OAuthConnectionOptions, 'returnOnOAuth'> | t.UserConnectionContext,
  ): Promise<ToolDiscoveryResult> {
    /** Checked before credential preparation begins: a spent budget or an already-cancelled
     *  caller must not start Graph preprocessing or token resolution it cannot cancel. */
    if (this.isRequestCancelled(options)) {
      logger.debug('[MCP] [Discovery] Cancelled or out of budget before discovery began');
      return { tools: null, connection: null, oauthRequired: false, oauthUrl: null };
    }
    const directBearerSourceConfig =
      basic.directBearerSourceConfig ??
      (usesDirectOpenIDBearerRecovery(basic.serverConfig)
        ? (basic.serverConfig as t.ParsedServerConfig)
        : undefined);
    const discover = async (candidate: t.BasicConnectionOptions): Promise<ToolDiscoveryResult> => {
      const prepared = await this.prepareBasicConnectionOptions(
        {
          ...candidate,
          /** Applied to every discovery attempt, not just the first: a config
           *  refreshed for direct-bearer recovery comes from the untouched
           *  definition and would otherwise carry the chat-only map back in. */
          serverConfig: toCatalogConnectionConfig(candidate.serverConfig),
          serverDefinition: basic.serverDefinition ?? basic.serverConfig,
          directBearerSourceConfig,
        },
        options,
      );
      if (options != null && 'useOAuth' in options) {
        const factory = new this(prepared, { ...options, returnOnOAuth: true });
        return factory.discoverToolsInternal();
      }
      const factory = new this(prepared, options);
      return factory.discoverToolsInternal();
    };

    const initial = await discover(basic);
    if (!directBearerSourceConfig || !this.hasDiscoveryAuthenticationRejection(initial)) {
      return initial;
    }

    if (initial.connection) {
      await initial.connection.dispose().catch(() => undefined);
    }
    if (isScheduledMCPBearer(options?.requestScopedConnections))
      throw createScheduledMCPTransportError(initial.authenticationError, basic.serverName);
    if (this.isRequestCancelled(options)) {
      return { tools: null, connection: null, oauthRequired: false, oauthUrl: null };
    }
    const refreshedConfig = await resolveDirectOpenIDBearerConfig({
      config: directBearerSourceConfig,
      upstreamTokenProvider: options?.upstreamTokenProvider,
      forceRefresh: true,
      signal: options?.signal,
    });
    const refreshed = await discover({ ...basic, serverConfig: refreshedConfig });
    if (this.hasDiscoveryAuthenticationRejection(refreshed)) {
      if (refreshed.connection) {
        await refreshed.connection.dispose().catch(() => undefined);
      }
      throw new MCPAuthenticationRejectedError(
        basic.serverName,
        false,
        refreshed.authenticationError,
      );
    }
    return refreshed;
  }

  private static hasDiscoveryAuthenticationRejection(result: ToolDiscoveryResult): boolean {
    return result.oauthRequired || result.authenticationError != null;
  }

  private static isRequestCancelled(options?: t.UserConnectionContext): boolean {
    return (
      options?.signal?.aborted === true ||
      (options?.deadlineMs != null && Date.now() >= options.deadlineMs)
    );
  }

  /**
   * Together with the constructor's processMCPEnv pass, this mirrors
   * UserConnectionManager.resolveRuntimeConfig — keep them in sync so the
   * config validated there matches the one connected with here.
   */
  private static async prepareBasicConnectionOptions(
    basic: t.BasicConnectionOptions,
    options?: t.OAuthConnectionOptions | t.UserConnectionContext,
  ): Promise<t.BasicConnectionOptions> {
    const resolveRequestHeaders = createScheduledMCPBearerHeaderResolver({
      user: options?.user,
      serverName: basic.serverName,
      config: (basic.serverDefinition ?? basic.serverConfig) as t.ParsedServerConfig,
      context: options?.requestScopedConnections,
    });
    const scheduledConfig = await resolveScheduledMCPBearerConfig({
      user: options?.user,
      serverName: basic.serverName,
      config: (basic.serverDefinition ?? basic.serverConfig) as t.ParsedServerConfig,
      context: options?.requestScopedConnections,
      signal: options?.signal,
    });
    const bearerConfig = await resolveDirectOpenIDBearerConfig({
      config:
        scheduledConfig === (basic.serverDefinition ?? basic.serverConfig)
          ? basic.serverConfig
          : applyRequestHeaders(scheduledConfig),
      upstreamTokenProvider: options?.upstreamTokenProvider,
      signal: options?.signal,
    });
    if (basic.directBearerRecoveryState && usesDirectOpenIDBearerRecovery(basic.serverConfig)) {
      basic.directBearerRecoveryState.resolvedConfig = bearerConfig;
    }
    const directBearerSourceConfig =
      basic.directBearerSourceConfig ??
      (usesDirectOpenIDBearerRecovery(basic.serverConfig)
        ? (basic.serverConfig as t.ParsedServerConfig)
        : undefined);
    const preparedBasic =
      bearerConfig === basic.serverConfig &&
      directBearerSourceConfig === basic.directBearerSourceConfig
        ? basic
        : {
            ...basic,
            serverConfig: bearerConfig,
            serverDefinition: basic.serverDefinition ?? basic.serverConfig,
            directBearerSourceConfig,
          };

    const connectionBasic = resolveRequestHeaders
      ? { ...preparedBasic, resolveRequestHeaders }
      : preparedBasic;
    if (basic.dbSourced || !options?.graphTokenResolver) {
      return connectionBasic;
    }

    const serverConfig = await preProcessGraphTokens(connectionBasic.serverConfig, {
      user: options.user,
      graphTokenResolver: options.graphTokenResolver,
      scopes: process.env.GRAPH_API_SCOPES,
    });

    return serverConfig === connectionBasic.serverConfig
      ? connectionBasic
      : {
          ...connectionBasic,
          serverConfig,
          serverDefinition: connectionBasic.serverDefinition ?? basic.serverConfig,
        };
  }

  protected async discoverToolsInternal(): Promise<ToolDiscoveryResult> {
    /** Rechecked here because credential preparation in `discoverTools` is uncancellable: a
     *  budget that expired or a caller that cancelled while it ran must not go on to token
     *  resolution or a connect. */
    if (this.isDiscoveryCancelled()) {
      logger.debug(
        `${this.logPrefix} [Discovery] Cancelled or out of budget before discovery began`,
      );
      return { tools: null, connection: null, oauthRequired: false, oauthUrl: null };
    }
    const oauthUrl: string | null = null;
    let oauthRequired = false;
    let shouldAttemptAuthenticatedDiscovery = true;
    const abortSignal = this.createDiscoveryAbortSignal();

    let oauthTokens: MCPOAuthTokens | null = null;
    if (this.usesObo) {
      try {
        oauthTokens = await this.getOboTokens();
      } catch (error) {
        if (!(error instanceof OboTokenResolutionError)) {
          throw error;
        }
        oauthRequired = true;
        shouldAttemptAuthenticatedDiscovery = false;
        logger.debug(
          `${this.logPrefix} [Discovery] OBO token resolution failed, attempting unauthenticated tool listing`,
          error,
        );
      }
    } else if (this.useOAuth) {
      /** The token flow is shared, and a refresh inside it may already be redeemed at the provider
       *  while its rotation persists. Stop waiting when the budget ends rather than cancelling that
       *  work, so the flow still stores the new tokens for the next caller, and hand the caller the
       *  work that keeps running so it can account for it. */
      const tokenLoad = this.getOAuthTokens();
      const loaded = await waitUntilDeadline(tokenLoad, this.deadlineMs, this.signal);
      if (!loaded.settled) {
        this.onDiscoveryDetached?.(tokenLoad);
        logger.debug(
          `${this.logPrefix} [Discovery] Cancelled or out of budget while loading OAuth tokens; leaving the token flow to finish`,
        );
        return { tools: null, connection: null, oauthRequired: false, oauthUrl: null };
      }
      oauthTokens = loaded.value;
      if (!oauthTokens && !this.usesObo && isOAuthServer(this.serverConfig)) {
        oauthRequired = true;
        shouldAttemptAuthenticatedDiscovery = false;
      }
    }

    let connection: MCPConnection | null = null;
    let oauthHandler: (() => void) | null = null;
    let rejectionRecorded: Promise<void> | undefined;
    if (shouldAttemptAuthenticatedDiscovery) {
      connection = new MCPConnection({
        serverName: this.serverName,
        serverConfig: this.serverConfig,
        userId: this.userId,
        oauthTokens,
        useSSRFProtection: this.useSSRFProtection,
        allowedAddresses: this.allowedAddresses,
        ephemeralConnection: this.ephemeralConnection,
        resolveRequestHeaders: this.resolveRequestHeaders,
        ...(this.capabilityProfile && { capabilityProfile: this.capabilityProfile }),
        ...(this.operationLimits && { operationLimits: this.operationLimits }),
        ...(this.directBearerRecoveryEnabled && { directBearerRecoveryEnabled: true }),
      });

      oauthHandler = () => {
        logger.info(
          `${this.logPrefix} [Discovery] OAuth required; skipping URL generation in discovery mode`,
        );
        oauthRequired = true;
        rejectionRecorded = this.recordRejectedOAuthAuthorization(oauthTokens?.credential_set_id);
        connection?.emit('oauthFailed', new Error('OAuth required during tool discovery'));
      };

      // Register unconditionally: non-OAuth servers that return 401 also emit 'oauthRequired',
      // and without this listener, connectClient()'s oauthHandledPromise hangs for 30s+.
      connection.once('oauthRequired', oauthHandler);

      try {
        await this.connectWithinBudget(connection, this.resolveConnectTimeout(30000), abortSignal);

        if (await connection.isConnected(abortSignal)) {
          const snapshot = await connection.fetchOrderedToolsSnapshot(this.deadlineMs, abortSignal);
          connection.removeListener('oauthRequired', oauthHandler);
          const rejectedOAuth = this.useOAuth && snapshot.authenticationError != null;
          if (rejectedOAuth) {
            await this.waitForDiscoveryRejection(
              this.recordRejectedOAuthAuthorization(oauthTokens?.credential_set_id),
            );
          }
          return {
            tools: snapshot.complete ? snapshot.tools : null,
            connection,
            oauthRequired: rejectedOAuth,
            oauthUrl: null,
            ...(snapshot.authenticationError != null && {
              authenticationError: snapshot.authenticationError,
            }),
          };
        }
      } catch (error) {
        if (isMCPInitializationError(error)) {
          connection.removeListener('oauthRequired', oauthHandler);
          await this.disposeQuietly(connection);
          throw error;
        }
        MCPConnection.decrementCycleCount(this.serverName);
        logger.debug(
          `${this.logPrefix} [Discovery] Connection failed, attempting unauthenticated tool listing`,
        );
      }

      /** The authenticated attempt is done with, but abandoning `connect()` does not cancel it —
       *  that socket stays open. Dispose before the fallback opens a second one so a single
       *  discovery never holds two concurrent connects to the same server. */
      connection.removeListener('oauthRequired', oauthHandler);
      await this.disposeQuietly(connection);
      await this.waitForDiscoveryRejection(rejectionRecorded);
      connection = null;
      oauthHandler = null;
    }

    if (this.isDiscoveryCancelled()) {
      logger.debug(
        `${this.logPrefix} [Discovery] Cancelled or out of budget; skipping unauthenticated tool listing`,
      );
      return { tools: null, connection: null, oauthRequired, oauthUrl };
    }

    try {
      const tools = await this.attemptUnauthenticatedToolListing(abortSignal);
      if (tools && tools.length > 0) {
        logger.info(
          `${this.logPrefix} [Discovery] Successfully discovered ${tools.length} tools without auth`,
        );
        return { tools, connection: null, oauthRequired, oauthUrl };
      }
      MCPConnection.decrementCycleCount(this.serverName);
    } catch (error) {
      if (isMCPInitializationError(error)) throw error;
      MCPConnection.decrementCycleCount(this.serverName);
      logger.debug(`${this.logPrefix} [Discovery] Unauthenticated tool listing failed`);
    }

    return { tools: null, connection: null, oauthRequired, oauthUrl };
  }

  /** Clamps a single `connect()` to whatever remains of the caller's overall discovery budget. */
  private resolveConnectTimeout(fallback: number): number {
    const configured = this.connectionTimeout ?? this.serverConfig.initTimeout ?? fallback;
    if (this.deadlineMs == null) {
      return configured;
    }
    return Math.max(1, Math.min(configured, this.deadlineMs - Date.now()));
  }

  private isPastDeadline(): boolean {
    return this.deadlineMs != null && Date.now() >= this.deadlineMs;
  }

  /** The ONE cancellation predicate for discovery gates. The budget and the caller's signal are
   *  two representations of the same fact; a gate that consults only one re-opens the class of
   *  bug where cancelled callers keep starting work. */
  private isDiscoveryCancelled(): boolean {
    return this.isPastDeadline() || this.signal?.aborted === true;
  }

  /**
   * Races `connect()` against the discovery signal as well as the timeout. `connect()` cannot
   * carry the signal itself, so an abort rejects this wait and the caller's normal cleanup
   * disposes the attempt — the connection's mid-connect disposal guard then discards whatever
   * the abandoned connect still constructs, instead of the socket living to the full timeout.
   */
  private async connectWithinBudget(
    connection: MCPConnection,
    timeoutMs: number,
    signal?: AbortSignal,
  ): Promise<void> {
    if (signal?.aborted === true) {
      throw new Error('Discovery cancelled before connect');
    }
    const connect = connection.connect();
    /** The abandoned attempt still settles eventually; swallow its rejection so losing the race
     *  never surfaces as an unhandled rejection. */
    connect.catch(() => undefined);
    let timer: NodeJS.Timeout | undefined;
    let onAbort: (() => void) | undefined;
    const interrupted = new Promise<never>((_, reject) => {
      timer = setTimeout(
        () => reject(new Error(`Connection timeout after ${timeoutMs}ms`)),
        timeoutMs,
      );
      timer.unref?.();
      if (signal != null) {
        onAbort = () => reject(new Error('Discovery cancelled during connect'));
        signal.addEventListener('abort', onAbort, { once: true });
      }
    });
    try {
      return await Promise.race([connect, interrupted]);
    } finally {
      clearTimeout(timer);
      if (onAbort != null) {
        signal?.removeEventListener('abort', onAbort);
      }
    }
  }

  /**
   * One abort signal for this discovery operation: the remaining budget and the caller's own
   * cancellation, whichever fires first. It reaches only work the SDK can genuinely cancel —
   * the health probe and `tools/list` requests. Teardown is deliberately exempt: `dispose()`
   * must finish, so cancelling it would trade a bounded overrun for a leaked session.
   */
  private createDiscoveryAbortSignal(): AbortSignal | undefined {
    return createDeadlineAbortSignal(this.deadlineMs, this.signal);
  }

  private async disposeQuietly(connection: MCPConnection): Promise<void> {
    try {
      await connection.dispose();
    } catch {
      // Ignore cleanup errors
    }
  }

  protected async attemptUnauthenticatedToolListing(signal?: AbortSignal): Promise<Tool[] | null> {
    const unauthConnection = new MCPConnection({
      serverName: this.serverName,
      serverConfig: this.serverConfig,
      userId: this.userId,
      oauthTokens: null,
      useSSRFProtection: this.useSSRFProtection,
      allowedAddresses: this.allowedAddresses,
      ephemeralConnection: this.ephemeralConnection,
      resolveRequestHeaders: this.resolveRequestHeaders,
      ...(this.capabilityProfile && { capabilityProfile: this.capabilityProfile }),
      ...(this.operationLimits && { operationLimits: this.operationLimits }),
    });

    unauthConnection.on('oauthRequired', () => {
      logger.debug(
        `${this.logPrefix} [Discovery] Unauthenticated connection requires OAuth, failing fast`,
      );
      unauthConnection.emit(
        'oauthFailed',
        new Error('OAuth not supported in unauthenticated discovery'),
      );
    });

    try {
      await this.connectWithinBudget(unauthConnection, this.resolveConnectTimeout(15000), signal);

      if (await unauthConnection.isConnected(signal)) {
        const snapshot = await unauthConnection.fetchOrderedToolsSnapshot(this.deadlineMs, signal);
        await this.disposeQuietly(unauthConnection);
        return snapshot.complete ? snapshot.tools : null;
      }
    } catch (error) {
      if (isMCPInitializationError(error)) {
        await this.disposeQuietly(unauthConnection);
        throw error;
      }
      logger.debug(`${this.logPrefix} [Discovery] Unauthenticated connection attempt failed`);
    }

    await this.disposeQuietly(unauthConnection);

    return null;
  }

  protected constructor(
    basic: t.BasicConnectionOptions,
    options?: t.OAuthConnectionOptions | t.UserConnectionContext,
  ) {
    this.serverDefinition = basic.serverDefinition ?? basic.serverConfig;
    this.resolveRequestHeaders = basic.resolveRequestHeaders;
    this.serverConfig = basic.skipEnvProcessing
      ? basic.serverConfig
      : processMCPEnv({
          user: options?.user,
          body: options?.requestBody,
          dbSourced: basic.dbSourced,
          options: basic.serverConfig,
          customUserVars: options?.customUserVars,
        });
    this.serverName = basic.serverName;
    this.useSSRFProtection = basic.useSSRFProtection === true;
    this.allowedDomains = basic.allowedDomains;
    this.allowedAddresses = basic.allowedAddresses;
    this.ephemeralConnection = basic.ephemeralConnection === true;
    this.directBearerRecoveryEnabled = isDirectOpenIDBearerRecoveryEnabled(
      basic.directBearerSourceConfig ?? basic.serverConfig,
    );
    this.capabilityProfile = basic.capabilityProfile;
    this.operationLimits = basic.operationLimits;
    this.connectionTimeout = options?.connectionTimeout;
    this.deadlineMs = options?.deadlineMs;
    this.onOAuthCredentialsChanged = options?.onOAuthCredentialsChanged;
    this.onOAuthCredentialsChanging = options?.onOAuthCredentialsChanging;
    this.onDiscoveryDetached = options?.onDiscoveryDetached;
    this.onOAuthCredentialsAdopted = options?.onOAuthCredentialsAdopted;
    this.onOAuthCredentialsInvalidated = options?.onOAuthCredentialsInvalidated;
    this.signal = options?.signal;
    this.tenantContext = tenantStorage?.getStore?.();
    this.tenantId = this.tenantContext?.tenantId ?? getTenantId();
    this.logPrefix = options?.user ? `[MCP][User: ${options.user.id}]` : '[MCP]';

    this.user = options?.user;
    this.userId = options?.user?.id;
    this.upstreamTokenProvider = options?.upstreamTokenProvider;
    this.upstreamTokenProviderResolver = options?.upstreamTokenProviderResolver;

    if (options != null && 'useOAuth' in options) {
      this.useOAuth = true;
      this.flowManager = options.flowManager;
      this.tokenMethods = options.tokenMethods;
      this.oauthStart = options.oauthStart;
      this.oauthEnd = options.oauthEnd;
      this.returnOnOAuth = options.returnOnOAuth;
      this.oboTokenResolver = options.oboTokenResolver;
      this.oboTrustChecker = options.oboTrustChecker;
      this.oboIdentityContext = options.oboIdentityContext;
    } else {
      this.useOAuth = false;
    }
  }

  /**
   * Resolves OBO tokens when the server config specifies obo, returns null otherwise.
   *
   * @param forceRefresh Bypasses the OBO token cache; used when the downstream server
   * has rejected the credential we currently hold.
   */
  protected async getOboTokens(forceRefresh = false): Promise<MCPOAuthTokens | null> {
    const oboConfig = this.serverConfig.obo;
    if (!oboConfig || !this.oboTokenResolver || !this.user) {
      return null;
    }

    if (!this.upstreamTokenProvider && this.upstreamTokenProviderResolver) {
      this.upstreamTokenProvider = createLazyOboUpstreamTokenProvider(
        this.upstreamTokenProviderResolver,
        this.signal,
        { mcpServer: this.serverName, scopes: oboConfig.scopes },
      );
    }
    if (!this.upstreamTokenProvider) {
      throw new OboTokenResolutionError(
        'missing_upstream_provider',
        'No upstream credential provider is configured for this OBO MCP connection.',
      );
    }

    if (this.oboTrustChecker) {
      const config = this.serverConfig as t.ParsedServerConfig;
      const trusted = await awaitOboOperation(
        this.oboTrustChecker({
          source: config.source,
          author: config.author,
          dbId: config.dbId,
        }),
        this.signal,
      );
      if (!trusted) {
        logger.warn(
          `${this.logPrefix} OBO config not trusted (author lacks CONFIGURE_OBO permission); skipping OBO token exchange`,
        );
        return null;
      }
    }

    logger.info(`${this.logPrefix} Resolving OBO token for scopes: ${oboConfig.scopes}`);
    return awaitOboOperation(
      resolveOboToken(
        this.user,
        oboConfig,
        this.oboTokenResolver,
        this.upstreamTokenProvider,
        this.oboIdentityContext,
        forceRefresh,
      ),
      this.signal,
    );
  }

  /** Returns true if this server uses OBO instead of standard OAuth */
  protected get usesObo(): boolean {
    return !!this.serverConfig.obo && !!this.oboTokenResolver && !!this.user;
  }

  protected createOboConnectionError(error: OboTokenResolutionError): OboTokenResolutionError {
    let recoveryHint = 'Re-authenticate the user and retry.';

    if (error.retryable) {
      recoveryHint = 'Please retry.';
    } else if (error.reason === 'exchange_failed') {
      recoveryHint = 'Re-authenticate the user or verify the configured OBO scopes and retry.';
    } else if (error.reason === 'missing_upstream_provider') {
      recoveryHint = 'Configure a renewable upstream credential provider before retrying.';
    }

    return new OboTokenResolutionError(
      error.reason,
      `${error.userMessage} Unable to connect to OBO server "${this.serverName}". ${recoveryHint}`,
      error.retryable,
      error,
    );
  }

  /** Creates the base MCP connection with OAuth tokens */
  protected async createConnection(): Promise<MCPConnection> {
    let oauthTokens: MCPOAuthTokens | null = null;

    if (this.usesObo) {
      try {
        oauthTokens = await this.getOboTokens();
      } catch (error) {
        if (error instanceof OboTokenResolutionError) {
          throw this.createOboConnectionError(error);
        }
        throw error;
      }
      if (!oauthTokens) {
        throw new Error(`OBO token exchange failed for "${this.serverName}".`);
      }
    } else if (this.useOAuth) {
      oauthTokens = await this.getOAuthTokens();
    }

    const connection = new MCPConnection({
      serverName: this.serverName,
      serverConfig: this.serverConfig,
      userId: this.userId,
      oauthTokens,
      useSSRFProtection: this.useSSRFProtection,
      allowedAddresses: this.allowedAddresses,
      ephemeralConnection: this.ephemeralConnection,
      resolveRequestHeaders: this.resolveRequestHeaders,
      ...(this.capabilityProfile && { capabilityProfile: this.capabilityProfile }),
      ...(this.operationLimits && { operationLimits: this.operationLimits }),
      ...(this.directBearerRecoveryEnabled && {
        directBearerRecoveryEnabled: true,
      }),
    });

    let cleanupOAuthHandlers: (() => void) | null = null;
    if (this.useOAuth && !this.usesObo) {
      cleanupOAuthHandlers = this.handleOAuthEvents(connection);
    } else if (this.usesObo) {
      cleanupOAuthHandlers = this.handleOboEvents(connection);
    } else {
      const nonOAuthHandler = () => {
        logger.info(
          `${this.logPrefix} Server does not use OAuth; treating 401/403 as auth failure`,
        );
        connection.emit('oauthFailed', new Error('Server does not use OAuth'));
      };
      connection.on('oauthRequired', nonOAuthHandler);
      cleanupOAuthHandlers = () => {
        connection.removeListener('oauthRequired', nonOAuthHandler);
      };
    }

    try {
      if (this.shouldInitiateOAuthBeforeConnect(oauthTokens)) {
        await this.initiateOAuthBeforeConnect(connection);
      }
      await this.attemptToConnect(connection);
      this.connectionReady = true;
      // Keep the `oauthRequired` listener for cached-connection 401 recovery,
      // but drop request-bound callbacks and credentials from the completed request.
      this.releaseRequestScopedOAuthState();
      return connection;
    } catch (error) {
      if (cleanupOAuthHandlers) {
        cleanupOAuthHandlers();
      }
      try {
        await connection.dispose();
      } catch {
        logger.warn(`${this.logPrefix} Failed to clean up rejected MCP connection`);
      }
      if (this.oboRefreshError) {
        throw this.oboRefreshError;
      }
      throw error;
    }
  }

  private shouldInitiateOAuthBeforeConnect(oauthTokens: MCPOAuthTokens | null): boolean {
    if (!this.useOAuth || oauthTokens) {
      return false;
    }
    return isOAuthServer(this.serverConfig);
  }

  protected releaseRequestScopedOAuthState(): void {
    this.signal = undefined;
    this.oauthStart = undefined;
    this.oauthEnd = undefined;
    this.returnOnOAuth = false;
    this.upstreamTokenProvider = undefined;
    this.upstreamTokenProviderResolver = undefined;
  }

  private getServerUrl(): string | undefined {
    return 'url' in this.serverConfig ? this.serverConfig.url : undefined;
  }

  private async initiateOAuthBeforeConnect(connection: MCPConnection): Promise<void> {
    const serverUrl = this.getServerUrl();
    if (!serverUrl) {
      throw new Error(`${this.logPrefix} OAuth required but server URL is missing from config`);
    }

    const oauthTimeout = mcpConfig.OAUTH_HANDLING_TIMEOUT;
    logger.info(
      `${this.logPrefix} No stored tokens, proactively triggering OAuth flow before connecting (timeout: ${oauthTimeout}ms)`,
    );

    await new Promise<void>((resolve, reject) => {
      let timeoutId: ReturnType<typeof setTimeout> | null = null;
      let oauthHandledListener: (() => void) | null = null;
      let oauthFailedListener: ((error: Error) => void) | null = null;

      const cleanup = () => {
        if (timeoutId) {
          clearTimeout(timeoutId);
        }
        if (oauthHandledListener) {
          connection.off('oauthHandled', oauthHandledListener);
        }
        if (oauthFailedListener) {
          connection.off('oauthFailed', oauthFailedListener);
        }
      };

      oauthHandledListener = () => {
        cleanup();
        resolve();
      };

      oauthFailedListener = (error: Error) => {
        cleanup();
        reject(error);
      };

      timeoutId = setTimeout(() => {
        cleanup();
        reject(new Error(`Proactive OAuth flow timeout after ${oauthTimeout}ms`));
      }, oauthTimeout);

      connection.once('oauthHandled', oauthHandledListener);
      connection.once('oauthFailed', oauthFailedListener);

      const emitted = connection.emit('oauthRequired', {
        serverName: this.serverName,
        error: new Error('OAuth tokens missing before connection'),
        serverUrl,
        userId: this.userId,
        /** `getOAuthTokens` just exhausted the stored-token/refresh path; go straight to interactive OAuth */
        skipSilentRefresh: true,
      });

      if (!emitted) {
        cleanup();
        reject(new Error('OAuth required but no handler is registered'));
      }
    });
  }

  private async runWithCapturedTenant<T>(fn: () => Promise<T>): Promise<T> {
    const context = this.tenantContext ?? (this.tenantId ? { tenantId: this.tenantId } : undefined);
    if (!context || !tenantStorage?.run) {
      return fn();
    }
    return tenantStorage.run(context, fn);
  }

  private getConnectionOAuthTimeoutMs(): number {
    const factoryConnectTimeout = this.connectionTimeout ?? this.serverConfig.initTimeout ?? 30000;
    const connectionOAuthTimeout = this.serverConfig.initTimeout ?? 60000 * 2;
    return Math.min(factoryConnectTimeout, connectionOAuthTimeout);
  }

  private getSilentRefreshTimeoutMs(): number {
    const oauthTimeout = this.getConnectionOAuthTimeoutMs();
    const silentRefreshBudgetMs = Math.floor(oauthTimeout * 0.4);
    return Math.max(
      1,
      Math.min(MCPConnectionFactory.SILENT_REFRESH_TIMEOUT_MS, silentRefreshBudgetMs),
    );
  }

  private getBaseFlowId(): string {
    return MCPOAuthHandler.generateFlowId(this.userId!, this.serverName, this.tenantId);
  }

  private getTokenFlowId(): string {
    // Before activation, keep joining legacy readers: splitting their flow would permit duplicate
    // redemption while some replicas still cannot take the coordination lease.
    if (this.serverConfig.oauthRefreshCoordination !== true) return this.getBaseFlowId();
    return MCPOAuthHandler.generateTokenFlowId(this.userId!, this.serverName, this.tenantId);
  }

  private getOAuthBindingDigest(): string {
    const oauth = this.serverConfig.oauth;
    return createHash('sha256')
      .update(
        JSON.stringify([
          (this.serverConfig as t.SSEOptions | t.StreamableHTTPOptions).url,
          oauth?.client_id,
          oauth?.client_secret,
          oauth?.authorization_url,
          oauth?.token_url,
          oauth?.token_exchange_method,
          oauth?.token_endpoint_auth_methods_supported,
        ]),
      )
      .digest('base64url');
  }

  /**
   * Reads tokens through the shared `mcp_get_tokens` flow. A flow that disappears while this call
   * waits on it was invalidated by a credential change, so the read runs once more against the
   * changed storage instead of reporting the tokens missing and prompting for authorization again.
   */
  private async loadOAuthTokens(): Promise<MCPOAuthTokens | null> {
    const flowId = this.getTokenFlowId();
    const readTokens = () =>
      this.flowManager!.createFlowWithHandler(
        flowId,
        'mcp_get_tokens',
        async () => {
          return await this.runWithCapturedTenant(async () =>
            MCPTokenStorage.getTokens({
              userId: this.userId!,
              serverName: this.serverName,
              findToken: this.tokenMethods!.findToken!,
              createToken: this.tokenMethods!.createToken,
              updateToken: this.tokenMethods!.updateToken,
              deleteTokens: this.tokenMethods!.deleteTokens,
              refreshTokens: this.createRefreshTokensFunction(),
              singleFlightScope: this.getOAuthBindingDigest(),
              refreshWaitTimeoutMs: this.serverConfig.oauthRefreshWaitTimeout,
              coordinateRefresh: this.serverConfig.oauthRefreshCoordination,
              persistenceWaitTimeoutMs: this.serverConfig.oauthPersistenceWaitTimeout,
              flowManager: this.flowManager,
              onRefreshSuccess: (refreshed) => this.handleOAuthRefreshSuccess(refreshed),
              onRefreshPreparing: () => this.prepareOAuthRefreshSuccess(),
              onTokensAdopted: (adopted) => this.handleAdoptedCredentials(adopted),
            }),
          );
        },
        this.signal,
      );

    try {
      return await readTokens();
    } catch (error) {
      if (!(error instanceof FlowStateNotFoundError)) {
        if (
          MCPConnectionFactory.isRefreshUnavailable(error) ||
          MCPConnectionFactory.isReauthenticationRequired(error)
        ) {
          throw error;
        }
        // Legacy flow records and cache failures carry no typed outcome. Retry storage first.
        throw new MCPTokenStorageUnavailableError(this.serverName, error);
      }
      logger.info(
        `${this.logPrefix} Token flow was invalidated while waiting on it; re-reading stored tokens`,
      );
      await this.onOAuthCredentialsInvalidated?.();
      try {
        return await readTokens();
      } catch (retryError) {
        if (
          MCPConnectionFactory.isRefreshUnavailable(retryError) ||
          MCPConnectionFactory.isReauthenticationRequired(retryError)
        ) {
          throw retryError;
        }
        throw new MCPTokenStorageUnavailableError(this.serverName, retryError);
      }
    }
  }

  /** Tokens released by another party's authorization or refresh carry the generation it published. */
  private async adoptPublishedCredentials(tokens: MCPOAuthTokens): Promise<void> {
    if (!tokens.publication_generation) {
      return;
    }
    await this.onOAuthCredentialsAdopted?.(tokens.publication_generation);
  }

  /**
   * Callback completion means credentials were persisted, not that their access token is still
   * usable. Both OAuth waiters and token-flow waiters can receive that exact completed result.
   * Re-read storage once instead of installing it or misclassifying expiry as a binding failure.
   */
  private async renewExpiredFlowResult(
    tokens: MCPOAuthTokens | null,
  ): Promise<MCPOAuthTokens | null> {
    const expiry = tokens?.expires_at;
    // Match storeTokens' whole-second persistence precision, including a rounded-to-zero TTL.
    if (
      expiry == null ||
      !Number.isFinite(expiry) ||
      Math.floor((expiry - Date.now()) / 1000) > 0
    ) {
      return tokens;
    }

    this.signal?.throwIfAborted();
    const leaseId = getMCPOAuthLeaseId(this.userId!, this.serverName, this.tenantId);
    try {
      const generation = await this.flowManager!.getLeaseGeneration(leaseId);
      const lease =
        generation == null
          ? null
          : await this.flowManager!.acquireLease(leaseId, {
              expectedGeneration: generation,
              waitMs: Math.min(
                this.serverConfig.oauthPersistenceWaitTimeout ?? Infinity,
                this.getSilentRefreshTimeoutMs(),
              ),
            });
      if (!lease) {
        throw new Error('OAuth publication is not settled');
      }
      // A callback settles waiters while its rollback journal is still live. Cross its persistence
      // fence before redeeming, then RELEASE it: refresh persistence acquires this same fence.
      await lease.release();
    } catch (error) {
      throw new MCPTokenStorageUnavailableError(this.serverName, error);
    }
    this.signal?.throwIfAborted();
    await this.invalidateGetTokensFlow();
    const renewed = await this.loadOAuthTokens();
    if (renewed?.expires_at != null && Math.floor((renewed.expires_at - Date.now()) / 1000) <= 0) {
      throw new MCPTokenRefreshUnavailableError(
        this.serverName,
        new Error('Refreshed access token has no usable lifetime'),
      );
    }
    return renewed;
  }

  /** Retrieves existing OAuth tokens from storage or returns null */
  protected async getOAuthTokens(): Promise<MCPOAuthTokens | null> {
    if (!this.tokenMethods?.findToken) return null;

    try {
      const tokens = await this.renewExpiredFlowResult(await this.loadOAuthTokens());

      if (tokens) {
        const [isCurrentAccessToken, storedClient] = await this.runWithCapturedTenant(() =>
          Promise.all([
            MCPTokenStorage.isCurrentAccessToken({
              userId: this.userId!,
              serverName: this.serverName,
              accessToken: tokens.access_token,
              credentialSetId: tokens.credential_set_id,
              findToken: this.tokenMethods!.findToken!,
            }),
            MCPTokenStorage.getClientInfoAndMetadata({
              userId: this.userId!,
              serverName: this.serverName,
              findToken: this.tokenMethods!.findToken!,
            }),
          ]).catch((error: unknown) => {
            throw new MCPTokenStorageUnavailableError(this.serverName, error);
          }),
        );
        if (!isCurrentAccessToken) {
          await this.invalidateGetTokensFlow();
          throw new MCPTokenStorageUnavailableError(
            this.serverName,
            new Error('Cached OAuth access token is stale'),
          );
        }
        MCPTokenStorage.assertCredentialSetBinding(
          this.serverName,
          tokens.credential_set_id,
          storedClient?.clientMetadata,
        );
        MCPOAuthHandler.assertStoredClientBinding(
          this.serverName,
          (this.serverConfig as t.SSEOptions | t.StreamableHTTPOptions).url,
          storedClient?.clientInfo,
          storedClient?.clientMetadata as Partial<OAuthStoredClientMetadata> | undefined,
          this.serverConfig.oauth,
        );
        await this.adoptPublishedCredentials(tokens);
        logger.info(`${this.logPrefix} Loaded OAuth tokens`);
      }
      return tokens;
    } catch (error) {
      if (this.signal?.aborted) {
        throw error;
      }
      if (MCPConnectionFactory.isReauthenticationRequired(error)) {
        logger.info(`${this.logPrefix} Reauthentication required; triggering OAuth flow`);
        return null;
      }
      if (
        error instanceof MCPTokenStorageUnavailableError ||
        error instanceof MCPTokenRefreshUnavailableError ||
        (error instanceof Error &&
          (error.name === 'MCPTokenStorageUnavailableError' ||
            error.name === 'MCPTokenRefreshUnavailableError'))
      ) {
        logger.warn(`${this.logPrefix} OAuth token loading failed; deferring connection recovery`);
        throw error;
      }
      logger.debug(`${this.logPrefix} No existing tokens found or token loading failed`);
      return null;
    }
  }

  /** Creates a function to refresh OAuth tokens when they expire */
  protected createRefreshTokensFunction(): (
    refreshToken: string,
    metadata: {
      userId: string;
      serverName: string;
      identifier: string;
      clientInfo?: OAuthClientInformation;
      storedTokenEndpoint?: string;
      storedAuthMethods?: string[];
      storedServerUrl?: string;
      clientSource?: OAuthClientSource;
      resource?: string;
    },
    signal?: AbortSignal,
  ) => Promise<MCPOAuthTokens> {
    return async (refreshToken, metadata, signal) => {
      return await MCPOAuthHandler.refreshOAuthTokens(
        refreshToken,
        {
          serverUrl: (this.serverConfig as t.SSEOptions | t.StreamableHTTPOptions).url,
          serverName: metadata.serverName,
          clientInfo: metadata.clientInfo,
          storedTokenEndpoint: metadata.storedTokenEndpoint,
          storedAuthMethods: metadata.storedAuthMethods,
          storedServerUrl: metadata.storedServerUrl,
          clientSource: metadata.clientSource,
          resource: metadata.resource,
        },
        this.serverConfig.oauth_headers ?? {},
        this.serverConfig.oauth,
        this.allowedDomains,
        this.allowedAddresses,
        signal,
      );
    };
  }

  /**
   * Attempts to silently refresh OAuth tokens using the stored refresh token,
   * bypassing the local `expires_at` check. Use this when the server has
   * signaled token invalidity (a 401 emitted as `oauthRequired`) to avoid
   * forcing the user through an interactive OAuth flow when the refresh token
   * is still valid.
   *
   * Coalesces via `inflightSilentRefreshes` rather than `FlowStateManager` —
   * the latter caches the completed result for the new token's TTL, which
   * would hand back stale tokens on a subsequent 401 (e.g. when the freshly
   * minted token is revoked before its local expiry). Caching only the
   * in-flight promise means every fresh 401 after settlement triggers a
   * fresh redemption. Token storage owns rejection persistence inside the
   * common flight shared with expired-token loading.
   */
  protected async attemptSilentTokenRefresh(
    rejectedCredentialSetId?: string | null,
  ): Promise<MCPOAuthTokens | null> {
    if (!this.tokenMethods?.findToken || !this.tokenMethods?.createToken) {
      return null;
    }

    // Scope the lock by tenant and OAuth binding so neither another tenant nor a
    // same-name server whose URL/client configuration changed can join the refresh.
    const bindingDigest = this.getOAuthBindingDigest();
    const lockKey = JSON.stringify([
      this.tenantId ?? '',
      this.userId ?? '',
      this.serverName,
      bindingDigest,
      ...(this.serverConfig.oauthRefreshCoordination === true
        ? [rejectedCredentialSetId === undefined ? ['unknown'] : ['known', rejectedCredentialSetId]]
        : []),
    ]);
    const inflight = MCPConnectionFactory.inflightSilentRefreshes.get(lockKey);
    if (inflight) {
      logger.debug(`${this.logPrefix} Joining in-flight silent refresh attempt`);
      return inflight;
    }

    const timeoutMs = this.getSilentRefreshTimeoutMs();
    const abortController = new AbortController();
    let timeoutId: ReturnType<typeof setTimeout> | null = null;
    let abortGraceTimeoutId: ReturnType<typeof setTimeout> | null = null;
    const refreshPromise = this.runSilentRefresh(
      abortController.signal,
      bindingDigest,
      rejectedCredentialSetId,
    );
    const promise = new Promise<MCPOAuthTokens | null>((resolve, reject) => {
      timeoutId = setTimeout(() => {
        abortController.abort();
        abortGraceTimeoutId = setTimeout(
          releaseLock,
          MCPConnectionFactory.SILENT_REFRESH_ABORT_GRACE_MS,
        );
        logger.info(
          `${this.logPrefix} Silent token refresh timed out after ${timeoutMs}ms; deferring recovery`,
        );
        reject(
          new MCPTokenRefreshUnavailableError(
            this.serverName,
            new Error('Silent refresh timed out'),
          ),
        );
      }, timeoutMs);

      refreshPromise.then(resolve, (error: unknown) => {
        /** Every joiner waits on this same contended credential, so they share the retry. */
        if (MCPConnectionFactory.isRefreshUnavailable(error)) {
          reject(error);
          return;
        }
        logger.info(
          `${this.logPrefix} Silent token refresh failed, falling back to interactive OAuth`,
        );
        resolve(null);
      });
    }).finally(() => {
      if (timeoutId) {
        clearTimeout(timeoutId);
      }
    });
    function releaseLock() {
      if (abortGraceTimeoutId) {
        clearTimeout(abortGraceTimeoutId);
        abortGraceTimeoutId = null;
      }
      if (MCPConnectionFactory.inflightSilentRefreshes.get(lockKey) === promise) {
        MCPConnectionFactory.inflightSilentRefreshes.delete(lockKey);
      }
    }
    MCPConnectionFactory.inflightSilentRefreshes.set(lockKey, promise);
    void refreshPromise.then(releaseLock, releaseLock);
    return await promise;
  }

  /**
   * Executes a single force-refresh attempt against the OAuth provider and
   * persists the new tokens. Called by `attemptSilentTokenRefresh` under the
   * `inflightSilentRefreshes` coalescing lock.
   */
  private async runSilentRefresh(
    signal: AbortSignal,
    singleFlightScope: string,
    rejectedCredentialSetId?: string | null,
  ): Promise<MCPOAuthTokens | null> {
    try {
      const tokens = await this.runWithCapturedTenant(async () =>
        MCPTokenStorage.forceRefreshTokens({
          userId: this.userId!,
          serverName: this.serverName,
          findToken: this.tokenMethods!.findToken!,
          createToken: this.tokenMethods!.createToken,
          updateToken: this.tokenMethods!.updateToken,
          deleteTokens: this.tokenMethods!.deleteTokens,
          refreshTokens: this.createRefreshTokensFunction(),
          singleFlightScope,
          rejectedCredentialSetId,
          refreshWaitTimeoutMs: this.serverConfig.oauthRefreshWaitTimeout,
          coordinateRefresh: this.serverConfig.oauthRefreshCoordination,
          persistenceWaitTimeoutMs: this.serverConfig.oauthPersistenceWaitTimeout,
          signal,
          /**
           * Drop any previously cached `mcp_get_tokens` result so the next
           * `getOAuthTokens` reads the freshly persisted tokens rather than the
           * now-stale flow-cached value. Attached to the shared redemption
           * (not this waiter) so a refresh that completes after this caller's
           * timeout still invalidates the cache.
           */
          onRefreshSuccess: (refreshed) => this.handleOAuthRefreshSuccess(refreshed),
          onRefreshPreparing: () => this.prepareOAuthRefreshSuccess(),
          onTokensAdopted: (adopted) => this.handleAdoptedCredentials(adopted),
          flowManager: this.flowManager,
        }),
      );

      if (tokens) {
        logger.info(`${this.logPrefix} Silent token refresh succeeded`);
      } else {
        logger.info(`${this.logPrefix} Silent token refresh returned no tokens`);
      }
      return tokens;
    } catch (error) {
      /**
       * Contention with another replica's redemption is retryable and must not read as a failed
       * refresh. Collapsing it to null sends this path to interactive OAuth, so a peer that merely
       * held the credential slightly too long would prompt the user to authorize the server again,
       * which is the outcome the cross-replica flight exists to prevent. The next request retries
       * once the peer releases, by which time its rotated credential is there to be adopted.
       */
      if (MCPConnectionFactory.isRefreshUnavailable(error)) {
        throw error;
      }
      if (error instanceof ReauthenticationRequiredError) {
        logger.info(
          `${this.logPrefix} Reauthentication required; falling back to interactive OAuth`,
        );
      } else {
        logger.info(
          `${this.logPrefix} Silent token refresh failed, falling back to interactive OAuth`,
        );
      }
      return null;
    }
  }

  /** Flow serialization preserves domain names, not class identity. */
  private static isReauthenticationRequired(error: unknown): boolean {
    return (
      error instanceof ReauthenticationRequiredError ||
      (error instanceof Error && error.name === 'ReauthenticationRequiredError')
    );
  }

  private static isRefreshUnavailable(error: unknown): boolean {
    return (
      error instanceof MCPTokenRefreshUnavailableError ||
      error instanceof MCPTokenStorageUnavailableError ||
      (error instanceof Error &&
        (error.name === 'MCPTokenRefreshUnavailableError' ||
          error.name === 'MCPTokenStorageUnavailableError'))
    );
  }

  /** Carries the peer's publication generation to every waiter without publishing it again. */
  private async handleAdoptedCredentials(adoptedTokens: MCPOAuthTokens): Promise<void> {
    const generation = await this.onOAuthCredentialsInvalidated?.();
    if (generation) {
      adoptedTokens.publication_generation = generation;
    }
    await this.invalidateGetTokensFlow(adoptedTokens, generation || undefined);
  }

  private async handleOAuthRefreshSuccess(freshTokens: MCPOAuthTokens): Promise<void> {
    if (this.userId != null) {
      await this.onOAuthCredentialsChanged?.({
        userId: this.userId,
        serverName: this.serverName,
      });
    }
    await this.invalidateGetTokensFlow(freshTokens);
  }

  private async prepareOAuthRefreshSuccess(): Promise<
    (freshTokens?: MCPOAuthTokens) => Promise<void>
  > {
    const publishPreparedMutation =
      this.userId == null
        ? undefined
        : await this.onOAuthCredentialsChanging?.({
            userId: this.userId,
            serverName: this.serverName,
          });
    return async (freshTokens) => {
      if (publishPreparedMutation != null) {
        const publicationGeneration = await publishPreparedMutation();
        await this.invalidateGetTokensFlow(freshTokens, publicationGeneration);
        return;
      }
      if (freshTokens != null) {
        await this.handleOAuthRefreshSuccess(freshTokens);
      } else {
        if (this.userId != null) {
          await this.onOAuthCredentialsChanged?.({
            userId: this.userId,
            serverName: this.serverName,
          });
        }
        await this.invalidateGetTokensFlow();
      }
    };
  }

  protected async invalidateGetTokensFlow(
    freshTokens?: MCPOAuthTokens,
    publicationGeneration?: string,
  ): Promise<void> {
    if (!this.flowManager || !this.userId) {
      return;
    }
    const flowManager = this.flowManager;
    // Both protocols remain valid cache readers across an enable/rollback transition.
    const flowIds = new Set([
      this.getBaseFlowId(),
      MCPOAuthHandler.generateTokenFlowId(this.userId, this.serverName, this.tenantId),
    ]);
    await Promise.all(
      [...flowIds].map(async (flowId) => {
        try {
          const state = await flowManager.getFlowState(flowId, 'mcp_get_tokens');
          if (!state) {
            return;
          }
          if (state.status === 'PENDING' && freshTokens) {
            await flowManager.completeFlow(
              flowId,
              'mcp_get_tokens',
              publicationGeneration
                ? { ...freshTokens, publication_generation: publicationGeneration }
                : freshTokens,
            );
            return;
          }
          if (state.status !== 'COMPLETED') {
            return;
          }
          await flowManager.deleteFlow(flowId, 'mcp_get_tokens');
        } catch {
          logger.debug(`${this.logPrefix} Failed to invalidate mcp_get_tokens cache`);
        }
      }),
    );
  }

  /**
   * Drops any cached COMPLETED `mcp_oauth` flow state so that
   * `handleOAuthRequired`'s recent-completion fast path can't re-serve the
   * tokens that the resource server just rejected.
   */
  protected async invalidateCompletedOAuthFlow(): Promise<void> {
    if (!this.flowManager || !this.userId) {
      return;
    }
    const flowId = this.getBaseFlowId();
    try {
      const existing = await this.flowManager.getFlowState(flowId, 'mcp_oauth');
      if (!existing || existing.status !== 'COMPLETED') {
        return;
      }
      const meta = existing.metadata as MCPOAuthFlowMetadata | undefined;
      if (!this.isCurrentTenantOAuthFlow(meta)) {
        logger.debug(
          `${this.logPrefix} Skipping completed mcp_oauth invalidation for a different tenant`,
        );
        return;
      }
      const oldState = meta?.state;
      await this.flowManager.deleteFlow(flowId, 'mcp_oauth');
      if (oldState) {
        await MCPOAuthHandler.deleteStateMapping(oldState, this.flowManager);
      }
    } catch {
      logger.debug(`${this.logPrefix} Failed to invalidate completed mcp_oauth cache`);
    }
  }

  private isCurrentTenantOAuthFlow(meta: MCPOAuthFlowMetadata | undefined): boolean {
    const flowTenantId = meta?.tenantId;
    if (!this.tenantId) {
      return !flowTenantId;
    }
    return flowTenantId === this.tenantId;
  }

  /**
   * A pending flow's authorization URL was already built with or without RFC 8707
   * `resource`, so replaying it after the operator changed `send_resource_parameter`
   * reissues the request they reconfigured away from.
   *
   * Deliberately separate from {@link isCurrentServerOAuthFlow}: that check also gates reuse
   * of a recent COMPLETED flow's tokens, and this setting must never invalidate tokens that
   * were already issued.
   */
  private isReplayablePendingOAuthFlow(meta: MCPOAuthFlowMetadata | undefined): boolean {
    if (!MCPOAuthHandler.matchesResourceParameterDecision(meta, this.serverConfig.oauth)) {
      logger.info(
        `${this.logPrefix} Pending OAuth flow predates a send_resource_parameter change; starting a new flow`,
      );
      return false;
    }
    return this.isCurrentServerOAuthFlow(meta);
  }

  /** Prevents server-name keyed OAuth flow cache entries from crossing config bindings. */
  private isCurrentServerOAuthFlow(meta: MCPOAuthFlowMetadata | undefined): boolean {
    const currentServerUrl = (this.serverConfig as t.SSEOptions | t.StreamableHTTPOptions).url;
    try {
      MCPOAuthHandler.assertStoredClientBinding(
        this.serverName,
        currentServerUrl,
        meta?.clientInfo,
        MCPOAuthHandler.buildStoredClientMetadata(
          meta?.metadata,
          meta?.resourceMetadata,
          meta?.serverUrl,
          meta?.clientSource,
        ),
        this.serverConfig.oauth,
      );
      return true;
    } catch (error) {
      logger.info(
        `${this.logPrefix} Cached OAuth flow binding is stale; starting a new flow`,
        error,
      );
      return false;
    }
  }

  private getOAuthRequiredStatusCode(data: OAuthRequiredEvent): number | undefined {
    if (typeof data.status === 'number') {
      return data.status;
    }
    if (typeof data.statusCode === 'number') {
      return data.statusCode;
    }

    const error = data.error;
    if (!error || typeof error !== 'object') {
      return undefined;
    }

    const errorLike = error as {
      code?: unknown;
      status?: unknown;
      statusCode?: unknown;
      message?: unknown;
    };
    for (const value of [errorLike.code, errorLike.status, errorLike.statusCode]) {
      if (typeof value === 'number' && Number.isInteger(value)) {
        return value;
      }
    }

    if (typeof errorLike.message === 'string') {
      const statusMatch = errorLike.message.match(/\b(4\d{2}|5\d{2})\b/);
      if (statusMatch) {
        return Number.parseInt(statusMatch[1], 10);
      }
    }

    return undefined;
  }

  private shouldAttemptSilentTokenRefresh(data: OAuthRequiredEvent): boolean {
    const statusCode = this.getOAuthRequiredStatusCode(data);
    if (statusCode === 403) {
      logger.info(
        `${this.logPrefix} OAuth server returned 403; skipping silent refresh and starting interactive OAuth`,
      );
      return false;
    }

    const error = data.error;
    if (error && typeof error === 'object' && 'message' in error) {
      const message = (error as { message?: unknown }).message;
      if (typeof message === 'string') {
        const normalized = message.toLowerCase();
        if (
          normalized.includes('insufficient_scope') ||
          normalized.includes('insufficient scope')
        ) {
          logger.info(
            `${this.logPrefix} OAuth server reported insufficient scope; skipping silent refresh`,
          );
          return false;
        }
      }
    }

    return true;
  }

  /**
   * Whether the server rejected the tokens a silent refresh issued during this connection attempt,
   * and they are still the stored credential. A provider can keep refreshing a grant its resource
   * server no longer accepts, so refreshing again would repeat the rejection on every connect
   * attempt and never ask the user to authorize. Tokens another request stored since then are not
   * a rejected renewal; the refresh path adopts them.
   */
  private async isRejectedRenewal(
    renewed: MCPOAuthTokens,
    rejectedCredentialSetId: string | null,
  ): Promise<boolean> {
    if (!this.tokenMethods?.findToken) {
      return false;
    }
    if ((renewed.credential_set_id ?? null) !== rejectedCredentialSetId) {
      return false;
    }
    return this.runWithCapturedTenant(() =>
      MCPTokenStorage.isCurrentAccessToken({
        userId: this.userId!,
        serverName: this.serverName,
        accessToken: renewed.access_token,
        credentialSetId: renewed.credential_set_id,
        findToken: this.tokenMethods!.findToken!,
      }),
    );
  }

  private getOAuthReplayExpiresAt(createdAt?: number): number | undefined {
    if (!createdAt) {
      return undefined;
    }

    const expiresAt = createdAt + PENDING_STALE_MS;
    return expiresAt > Date.now() ? expiresAt : undefined;
  }

  /**
   * Sets up the authentication handler for an OBO connection.
   *
   * An OBO server rejecting our bearer is recoverable in a way the non-OAuth
   * fallback cannot express: the downstream credential is minted from the user's
   * live upstream session, so a fresh exchange produces a working token without
   * any interactive step. What it needs is that live session, which only exists
   * while the request that created this connection is still running. Past that
   * point `upstreamTokenProvider` closes over a finished request, so a cached
   * connection stops reconnecting instead and its next borrower rebuilds it
   * against a live provider.
   */
  protected handleOboEvents(connection: MCPConnection): () => void {
    let refreshAttempted = false;

    const oboHandler = async (): Promise<void> => {
      if (this.connectionReady) {
        logger.info(
          `${this.logPrefix} Cached OBO connection was rejected; deferring to a live request for re-exchange`,
        );
        this.abandonOboConnection(connection, new Error('OBO re-exchange requires a live request'));
        return;
      }

      if (refreshAttempted) {
        logger.warn(`${this.logPrefix} Refreshed OBO token was rejected as well`);
        this.abandonOboConnection(connection, new Error('Refreshed OBO token was rejected'));
        return;
      }
      refreshAttempted = true;

      logger.info(`${this.logPrefix} OBO token rejected by server; re-running token exchange`);
      try {
        const tokens = await this.getOboTokens(true);
        if (!tokens?.access_token) {
          throw new Error(`OBO token exchange returned no token for "${this.serverName}".`);
        }
        connection.setOAuthTokens(tokens);
        connection.setAuthorizationHeader(tokens.access_token);
        logger.info(`${this.logPrefix} OBO token re-exchanged; retrying connection`);
        connection.emit('oauthHandled');
      } catch (error) {
        if (isAbortError(error)) {
          logger.debug(`${this.logPrefix} OBO token re-exchange cancelled`);
        } else {
          logger.error(`${this.logPrefix} OBO token re-exchange failed`, error);
        }
        /**
         * `connectClient` rejects its handling promise with this error and then
         * rethrows the server's original 401, so a diagnosis like an unrefreshable
         * sign-in session would be lost. `createConnection` reads it back and
         * surfaces it in place of the generic 401 — the same substitution the
         * initial OBO resolution already makes.
         */
        this.oboRefreshError = this.toOboRefreshError(error);
        this.abandonOboConnection(connection, this.oboRefreshError);
      }
    };

    connection.on('oauthRequired', oboHandler);

    return () => {
      connection.removeListener('oauthRequired', oboHandler);
    };
  }

  private toOboRefreshError(error: unknown): Error {
    if (error instanceof OboTokenResolutionError) {
      return this.createOboConnectionError(error);
    }
    if (error instanceof Error) {
      return error;
    }
    if (isAbortError(error)) {
      return Object.assign(new Error('The operation was aborted.', { cause: error }), {
        name: 'AbortError',
      });
    }
    return new Error(`OBO token re-exchange failed for "${this.serverName}".`);
  }

  /**
   * Ends recovery for an OBO connection holding a credential nothing can replace.
   * Reconnect attempts would replay the rejected bearer through every backoff step
   * and spend the circuit breaker's cycle budget, so the connection is retired and
   * left for its next borrower to dispose and rebuild.
   */
  private abandonOboConnection(connection: MCPConnection, error: Error): void {
    connection.stopReconnecting();
    connection.emit('oauthFailed', error);
  }

  /** Cancellation ends discovery's wait, never the generation-guarded persistence operation. */
  private async waitForDiscoveryRejection(pending?: Promise<void>): Promise<void> {
    if (!pending) return;
    const recorded = await waitUntilDeadline(pending, this.deadlineMs, this.signal);
    if (!recorded.settled) this.onDiscoveryDetached?.(pending);
  }

  private async recordRejectedOAuthAuthorization(credentialSetId?: string | null): Promise<void> {
    if (!credentialSetId || !this.tokenMethods?.findToken || !this.tokenMethods.updateToken) {
      return;
    }
    try {
      await this.runWithCapturedTenant(() =>
        MCPTokenStorage.markAuthorizationRejected({
          userId: this.userId!,
          serverName: this.serverName,
          credentialSetId,
          findToken: this.tokenMethods!.findToken!,
          updateToken: this.tokenMethods!.updateToken!,
          flowManager: this.flowManager,
          persistenceWaitTimeoutMs: this.serverConfig.oauthPersistenceWaitTimeout,
        }),
      );
    } catch (error) {
      logger.warn(`${this.logPrefix} Failed to record upstream OAuth rejection`, error);
    }
  }

  /** Sets up OAuth event handlers for the connection */
  protected handleOAuthEvents(
    connection: MCPConnection,
    eventName: 'oauthRequired' | 'oauthReauthenticationRequired' = 'oauthRequired',
  ): () => void {
    const isRequestRecovery = eventName === 'oauthReauthenticationRequired';
    let recoveryPhase: OAuthRecoveryPhase = 'silent-refresh';
    let eventHandling: Promise<void> | null = null;
    /** Tokens a silent refresh issued while this connection was being established. */
    let renewedTokens: MCPOAuthTokens | null = null;

    const handleOAuthEvent = async (data: OAuthRequiredEvent) => {
      logger.info(`${this.logPrefix} oauthRequired event received`);

      if (this.connectionReady) {
        const emitted = connection.emit('oauthReauthenticationRequired', {
          ...data,
          skipSilentRefresh: data.skipSilentRefresh,
        });
        if (emitted) {
          return;
        }
        logger.info(`${this.logPrefix} Cached connection requires a live OAuth request handler`);
        await this.recordRejectedOAuthAuthorization(
          data.rejectedCredentialSetId !== undefined
            ? data.rejectedCredentialSetId
            : connection.getOAuthCredentialSetId(),
        );
        connection.emit('oauthFailed', new Error('OAuth reauthentication required'));
        return;
      }

      const rejectedCredentialSetId =
        data.rejectedCredentialSetId !== undefined
          ? data.rejectedCredentialSetId
          : connection.getOAuthCredentialSetId();
      const oauthLeaseId = getMCPOAuthLeaseId(this.userId!, this.serverName, this.tenantId);
      let oauthLeaseGeneration: number | null;
      try {
        oauthLeaseGeneration = await this.flowManager!.getLeaseGeneration(oauthLeaseId);
      } catch {
        connection.emit('oauthFailed', new Error('OAuth teardown fence unavailable'));
        return;
      }
      if (oauthLeaseGeneration === null) {
        connection.emit('oauthFailed', new Error('OAuth teardown in progress'));
        return;
      }

      if (isRequestRecovery && recoveryPhase === 'terminal') {
        await this.recordRejectedOAuthAuthorization(rejectedCredentialSetId);
        logger.warn(`${this.logPrefix} OAuth recovery phase budget exhausted`);
        connection.emit('oauthFailed', new Error('OAuth recovery phase budget exhausted'));
        return;
      }

      if (!isRequestRecovery || recoveryPhase === 'silent-refresh') {
        recoveryPhase = 'interactive';
        if (
          !isRequestRecovery &&
          renewedTokens != null &&
          (await this.isRejectedRenewal(renewedTokens, rejectedCredentialSetId))
        ) {
          logger.info(
            `${this.logPrefix} Server rejected the tokens a silent refresh just issued; starting interactive OAuth`,
          );
        } else if (!data.skipSilentRefresh && this.shouldAttemptSilentTokenRefresh(data)) {
          let refreshedTokens: MCPOAuthTokens | null;
          try {
            refreshedTokens = await this.attemptSilentTokenRefresh(rejectedCredentialSetId);
          } catch (error) {
            if (!MCPConnectionFactory.isRefreshUnavailable(error)) {
              throw error;
            }
            /**
             * Another replica is redeeming this credential. Falling through would start a
             * replacement authorization while that redemption is still live, asking the user to
             * approve a server whose credential is about to be valid. Failing the connection
             * defers to the next request instead, matching how the stored-token path reports the
             * same error, and mirroring the teardown gate below in choosing not to prompt.
             */
            logger.info(
              `${this.logPrefix} Another replica is rotating this credential; deferring recovery`,
            );
            recoveryPhase = 'silent-refresh';
            connection.emit('oauthFailed', error);
            return;
          }
          if (refreshedTokens) {
            if (!isRequestRecovery) {
              renewedTokens = refreshedTokens;
            }
            connection.setOAuthTokens(refreshedTokens);
            connection.emit('oauthHandled', 'silent-refresh' satisfies t.OAuthHandledSource);
            return;
          }
        }
      }

      await this.recordRejectedOAuthAuthorization(rejectedCredentialSetId);

      if (isRequestRecovery) {
        recoveryPhase = 'terminal';
      }

      /** Teardown holds this gate until its credential and flow cleanup finishes. A refresh
       * suppressed by that gate must not fall through and create a replacement OAuth flow. */
      if (
        this.userId &&
        MCPTokenStorage.isRefreshTeardownActive(this.userId, this.serverName, this.tenantId)
      ) {
        connection.emit('oauthFailed', new Error('OAuth teardown in progress'));
        return;
      }

      // Silent refresh failed and we're about to fall through to interactive
      // OAuth. Invalidate any COMPLETED `mcp_oauth` flow first so
      // `handleOAuthRequired`'s recent-completion fast path can't re-serve the
      // tokens the resource server just rejected (see the `PENDING_STALE_MS`
      // window in `handleOAuthRequired`).
      await this.invalidateCompletedOAuthFlow();

      if (this.returnOnOAuth) {
        try {
          const config = this.serverConfig;
          const flowId = this.getBaseFlowId();
          const existingFlow = await this.flowManager!.getFlowState(flowId, 'mcp_oauth');

          if (existingFlow?.status === 'PENDING') {
            const pendingAge = existingFlow.createdAt
              ? Date.now() - existingFlow.createdAt
              : Infinity;
            const flowMeta = existingFlow.metadata as MCPOAuthFlowMetadata | undefined;

            if (pendingAge < PENDING_STALE_MS && this.isReplayablePendingOAuthFlow(flowMeta)) {
              logger.debug(
                `${this.logPrefix} Recent PENDING OAuth flow exists (${Math.round(pendingAge / 1000)}s old), skipping new initiation`,
              );
              const storedAuthUrl = flowMeta?.authorizationUrl;
              if (storedAuthUrl && typeof this.oauthStart === 'function') {
                const expiresAt = this.getOAuthReplayExpiresAt(existingFlow.createdAt);
                if (!expiresAt) {
                  logger.debug(`${this.logPrefix} PENDING OAuth flow expired before replay`);
                  connection.emit(
                    'oauthFailed',
                    new Error('Pending OAuth flow expired before replay'),
                  );
                  return;
                }
                logger.info(
                  `${this.logPrefix} Re-issuing stored authorization URL while reusing PENDING flow`,
                );
                const replayLease = await this.flowManager!.acquireLease(oauthLeaseId, {
                  expectedGeneration: oauthLeaseGeneration,
                });
                if (!replayLease) {
                  connection.emit('oauthFailed', new Error('OAuth replay superseded by teardown'));
                  return;
                }
                try {
                  await this.oauthStart(storedAuthUrl, { expiresAt });
                } finally {
                  await replayLease.release();
                }
              }
              connection.emit('oauthFailed', new Error('Pending OAuth flow reused - return early'));
              return;
            }

            logger.debug(
              `${this.logPrefix} Found stale PENDING OAuth flow (${Math.round(pendingAge / 1000)}s old), will replace`,
            );
          }

          const {
            authorizationUrl,
            flowId: newFlowId,
            flowMetadata,
          } = await this.runWithCapturedTenant(() =>
            MCPOAuthHandler.initiateOAuthFlow(
              this.serverName,
              data.serverUrl || '',
              this.userId!,
              config?.oauth_headers ?? {},
              config?.oauth,
              this.allowedDomains,
              // Only reuse stored client when deleteTokens is available for stale-client cleanup
              this.tokenMethods?.deleteTokens ? this.tokenMethods.findToken : undefined,
              this.allowedAddresses,
              this.tenantId,
            ),
          );

          if (existingFlow) {
            const oldMeta = existingFlow.metadata as MCPOAuthFlowMetadata | undefined;
            const oldState = oldMeta?.state;
            await this.flowManager!.deleteFlow(flowId, 'mcp_oauth');
            if (oldState) {
              await MCPOAuthHandler.deleteStateMapping(oldState, this.flowManager!);
            }
          }

          // Store flow state BEFORE redirecting so the callback can find it
          const metadataWithUrl = {
            ...flowMetadata,
            authorizationUrl,
            tenantId: this.tenantId,
            serverGeneration: getMCPServerGeneration(this.serverDefinition as t.ParsedServerConfig),
            oauthPersistenceWaitTimeout: this.serverConfig.oauthPersistenceWaitTimeout,
          };
          const publicationLease = await this.flowManager!.acquireLease(oauthLeaseId, {
            expectedGeneration: oauthLeaseGeneration,
          });
          if (!publicationLease) {
            connection.emit('oauthFailed', new Error('OAuth initiation superseded by teardown'));
            return;
          }
          try {
            await this.flowManager!.initFlow(newFlowId, 'mcp_oauth', metadataWithUrl);
            await MCPOAuthHandler.storeStateMapping(
              flowMetadata.state,
              newFlowId,
              this.flowManager!,
            );
          } finally {
            await publicationLease.release();
          }

          // Start monitoring in background — createFlow will find the existing PENDING state
          // written by initFlow above, so metadata arg is unused (pass {} to make that explicit)
          this.waitForSharedOAuthFlow(newFlowId).catch(async (error) => {
            logger.debug(`${this.logPrefix} OAuth flow monitor ended`);
            await this.clearStaleClientIfRejected(flowMetadata.reusedClientCredentialSetId, error);
          });

          if (this.oauthStart) {
            logger.info(`${this.logPrefix} OAuth flow started, issuing authorization URL`);
            await this.oauthStart(authorizationUrl);
          }

          connection.emit('oauthFailed', new Error('OAuth flow initiated - return early'));
          return;
        } catch {
          logger.error(`${this.logPrefix} Failed to initiate OAuth flow`);
          connection.emit('oauthFailed', new Error('OAuth initiation failed'));
          return;
        }
      }

      // Normal OAuth handling - wait for completion
      const result = await this.handleOAuthRequired(oauthLeaseGeneration);

      if (result?.tokens) {
        try {
          if (
            !this.tokenMethods?.findToken ||
            typeof result.tokens.credential_set_id !== 'string' ||
            !result.tokens.credential_set_id
          ) {
            throw new ReauthenticationRequiredError(this.serverName, 'binding');
          }
          const tokens = await this.renewExpiredFlowResult(result.tokens);
          if (!tokens) {
            throw new ReauthenticationRequiredError(this.serverName, 'expired');
          }
          if (
            !this.tokenMethods?.findToken ||
            typeof tokens.credential_set_id !== 'string' ||
            tokens.credential_set_id.length === 0
          ) {
            throw new ReauthenticationRequiredError(this.serverName, 'binding');
          }

          const [isCurrentAccessToken, storedClient] = await this.runWithCapturedTenant(() =>
            Promise.all([
              MCPTokenStorage.isCurrentAccessToken({
                userId: this.userId!,
                serverName: this.serverName,
                accessToken: tokens.access_token,
                credentialSetId: tokens.credential_set_id,
                findToken: this.tokenMethods!.findToken!,
              }),
              MCPTokenStorage.getClientInfoAndMetadata({
                userId: this.userId!,
                serverName: this.serverName,
                findToken: this.tokenMethods!.findToken!,
              }),
            ]),
          );
          if (!isCurrentAccessToken || !storedClient) {
            throw new ReauthenticationRequiredError(this.serverName, 'binding');
          }
          MCPTokenStorage.assertCredentialSetBinding(
            this.serverName,
            tokens.credential_set_id,
            storedClient.clientMetadata,
          );
          MCPOAuthHandler.assertStoredClientBinding(
            this.serverName,
            (this.serverConfig as t.SSEOptions | t.StreamableHTTPOptions).url,
            storedClient.clientInfo,
            storedClient.clientMetadata as Partial<OAuthStoredClientMetadata> | undefined,
            this.serverConfig.oauth,
          );

          connection.setOAuthTokens(tokens);
          await this.adoptPublishedCredentials(tokens);
          // Same rationale as the silent-refresh success path: invalidate the
          // `mcp_get_tokens` cache so the next `getOAuthTokens` reads the
          // freshly stored tokens rather than the just-rejected ones the
          // interactive flow replaced.
          await this.invalidateGetTokensFlow(tokens);
          logger.info(`${this.logPrefix} Verified OAuth callback tokens in storage`);
        } catch (error) {
          logger.error(`${this.logPrefix} Failed to verify OAuth callback tokens`);
          connection.emit(
            'oauthFailed',
            error instanceof Error ? error : new Error('OAuth token verification failed'),
          );
          return;
        }
      }

      // Only emit oauthHandled if we actually got tokens (OAuth succeeded)
      if (result?.tokens) {
        connection.emit('oauthHandled', 'interactive' satisfies t.OAuthHandledSource);
      } else {
        await this.clearStaleClientIfRejected(result?.reusedClientCredentialSetId, result?.error);
        logger.warn(`${this.logPrefix} OAuth failed, emitting oauthFailed event`);
        connection.emit('oauthFailed', new Error('OAuth authentication failed'));
      }
    };

    const oauthHandler = (data: OAuthRequiredEvent): Promise<void> => {
      if (!isRequestRecovery) {
        return handleOAuthEvent(data);
      }
      if (eventHandling) {
        return eventHandling;
      }

      const handling = handleOAuthEvent(data).finally(() => {
        if (eventHandling === handling) {
          eventHandling = null;
        }
      });
      eventHandling = handling;
      return handling;
    };

    connection.on(eventName, oauthHandler);

    return () => {
      connection.removeListener(eventName, oauthHandler);
    };
  }

  /** Attempts to establish connection with timeout handling */
  protected async attemptToConnect(connection: MCPConnection): Promise<void> {
    this.signal?.throwIfAborted();
    const baseTimeout = this.connectionTimeout ?? this.serverConfig.initTimeout ?? 30000;
    // OAuth servers may pause mid-connect to wait for the user to authorize in the browser.
    // The transport connect itself is still bounded by initTimeout inside connection.connect(),
    // so this floor only extends the window for an active OAuth wait, not ordinary failures.
    // The grace covers the reconnect after `oauthHandled` (retry backoff + transport connect),
    // which happens *after* the handling wait, so a user who authorizes near the deadline still
    // gets a connection instead of a timeout.
    const oauthHandlingTimeout = Number.isFinite(mcpConfig.OAUTH_HANDLING_TIMEOUT)
      ? mcpConfig.OAUTH_HANDLING_TIMEOUT
      : 10 * 60 * 1000;
    const connectTimeout = this.useOAuth
      ? Math.max(baseTimeout, oauthHandlingTimeout + 60000)
      : baseTimeout;
    const retryController = new AbortController();
    const callerSignal = this.signal;
    let onAbort: (() => void) | undefined;
    const cancelled = new Promise<never>((_, reject) => {
      if (callerSignal) {
        onAbort = () => {
          retryController.abort(callerSignal.reason);
          reject(callerSignal.reason);
        };
        callerSignal.addEventListener('abort', onAbort, { once: true });
      }
    });
    let timeoutId: NodeJS.Timeout | undefined;
    const timeout = new Promise<never>((_, reject) => {
      timeoutId = setTimeout(() => {
        retryController.abort();
        reject(new Error(`Connection timeout after ${connectTimeout}ms`));
      }, connectTimeout);
    });

    try {
      await Promise.race([this.connectTo(connection, retryController.signal), timeout, cancelled]);
    } finally {
      if (timeoutId) {
        clearTimeout(timeoutId);
      }
      retryController.abort();
      if (onAbort) {
        callerSignal?.removeEventListener('abort', onAbort);
      }
    }

    callerSignal?.throwIfAborted();
    const connected = await connection.isConnected(callerSignal);
    callerSignal?.throwIfAborted();
    if (connected) return;
    logger.error(`${this.logPrefix} Failed to establish connection.`);
  }

  private waitForRetry(delayMs: number, signal: AbortSignal): Promise<void> {
    return new Promise<void>((resolve, reject) => {
      if (signal.aborted) {
        reject(new Error('Connection retry cancelled'));
        return;
      }

      const onAbort = () => {
        clearTimeout(timeoutId);
        reject(new Error('Connection retry cancelled'));
      };
      const timeoutId = setTimeout(() => {
        signal.removeEventListener('abort', onAbort);
        resolve();
      }, delayMs);
      signal.addEventListener('abort', onAbort, { once: true });
    });
  }

  private async connectTo(connection: MCPConnection, signal: AbortSignal): Promise<void> {
    const maxAttempts = 3;
    let attempts = 0;

    while (attempts < maxAttempts) {
      if (signal.aborted) {
        throw new Error('Connection retry cancelled');
      }
      try {
        await connection.connect();
        if (await connection.isConnected()) {
          return;
        }
        throw new Error('Connection attempt succeeded but status is not connected');
      } catch (error) {
        attempts++;

        if (signal.aborted) {
          throw error;
        }

        if (
          (this.useOAuth || this.directBearerRecoveryEnabled) &&
          isOAuthAuthenticationError(error)
        ) {
          logger.info(`${this.logPrefix} OAuth required, stopping connection attempts`);
          throw error;
        }

        if (attempts === maxAttempts) {
          logger.error(`${this.logPrefix} Failed to connect after ${maxAttempts} attempts`);
          throw error;
        }
        await this.waitForRetry(2000 * attempts, signal);
      }
    }
  }

  /** Clears stored client registration if the error indicates client rejection */
  private async clearStaleClientIfRejected(
    reusedClientCredentialSetId: string | undefined,
    error: unknown,
  ): Promise<void> {
    if (!reusedClientCredentialSetId || !this.tokenMethods?.deleteTokens) {
      return;
    }
    if (!MCPConnectionFactory.isClientRejection(error)) {
      return;
    }
    await this.runWithCapturedTenant(() =>
      MCPTokenStorage.deleteClientRegistration({
        userId: this.userId!,
        serverName: this.serverName,
        deleteTokens: this.tokenMethods!.deleteTokens,
        credentialSetId: reusedClientCredentialSetId,
      }),
    ).catch(() => {
      logger.warn(`${this.logPrefix} Failed to clear stale client registration`);
    });
  }

  /**
   * Checks whether an error indicates the OAuth client registration was rejected.
   * Includes RFC 6749 §5.2 standard codes (`invalid_client`, `unauthorized_client`)
   * and known vendor-specific patterns (Okta: `client_id mismatch`, Auth0: `client not found`,
   * generic: `unknown client`).
   */
  static isClientRejection(error: unknown): boolean {
    if (!error || typeof error !== 'object') {
      return false;
    }
    if ('message' in error && typeof error.message === 'string') {
      return isClientRejectionMessage(error.message);
    }
    return false;
  }

  /** Manages OAuth flow initiation and completion */
  protected async handleOAuthRequired(expectedLeaseGeneration?: number): Promise<{
    tokens: MCPOAuthTokens | null;
    clientInfo?: OAuthClientInformation;
    metadata?: OAuthMetadata;
    resourceMetadata?: OAuthProtectedResourceMetadata;
    clientSource?: OAuthClientSource;
    reusedStoredClient?: boolean;
    reusedClientCredentialSetId?: string;
    error?: unknown;
  } | null> {
    const serverUrl = (this.serverConfig as t.SSEOptions | t.StreamableHTTPOptions).url;
    logger.debug(`${this.logPrefix} \`handleOAuthRequired\` called`, {
      hasServerUrl: Boolean(serverUrl),
    });

    if (!this.flowManager || !serverUrl) {
      logger.error(
        `${this.logPrefix} OAuth required but flow manager or server URL is unavailable`,
      );
      logger.warn(`${this.logPrefix} OAuth credentials must be configured`);
      return null;
    }

    const oauthLeaseId = getMCPOAuthLeaseId(this.userId!, this.serverName, this.tenantId);
    const oauthLeaseGeneration =
      expectedLeaseGeneration ?? (await this.flowManager.getLeaseGeneration(oauthLeaseId));
    if (oauthLeaseGeneration === null) {
      throw new Error('OAuth teardown in progress');
    }

    let reusedStoredClient = false;
    let reusedClientCredentialSetId: string | undefined;

    try {
      logger.debug(`${this.logPrefix} Checking for existing OAuth flow`);

      /** Flow ID to check if a flow already exists */
      const flowId = this.getBaseFlowId();

      /** Check if there's already an ongoing OAuth flow for this flowId */
      const existingFlow = await this.flowManager.getFlowState(flowId, 'mcp_oauth');

      if (existingFlow) {
        const flowMeta = existingFlow.metadata as MCPOAuthFlowMetadata | undefined;

        if (existingFlow.status === 'PENDING') {
          const pendingAge = existingFlow.createdAt
            ? Date.now() - existingFlow.createdAt
            : Infinity;

          if (pendingAge < PENDING_STALE_MS && this.isReplayablePendingOAuthFlow(flowMeta)) {
            logger.debug(
              `${this.logPrefix} Found recent PENDING OAuth flow (${Math.round(pendingAge / 1000)}s old), joining instead of creating new one`,
            );

            const storedAuthUrl = flowMeta?.authorizationUrl;
            if (storedAuthUrl && typeof this.oauthStart === 'function') {
              const expiresAt = this.getOAuthReplayExpiresAt(existingFlow.createdAt);
              if (!expiresAt) {
                throw new Error('Pending OAuth flow expired before replay');
              }
              logger.info(
                `${this.logPrefix} Re-issuing stored authorization URL to caller while joining PENDING flow`,
              );
              const replayLease = await this.flowManager.acquireLease(oauthLeaseId, {
                expectedGeneration: oauthLeaseGeneration,
              });
              if (!replayLease) {
                throw new Error('OAuth replay superseded by teardown');
              }
              try {
                await this.oauthStart(storedAuthUrl, { expiresAt });
              } finally {
                await replayLease.release();
              }
            }

            reusedStoredClient = flowMeta?.reusedStoredClient === true;
            reusedClientCredentialSetId = flowMeta?.reusedClientCredentialSetId;
            const tokens = await this.waitForSharedOAuthFlow(flowId);
            if (typeof this.oauthEnd === 'function') {
              await this.oauthEnd();
            }
            logger.info(`${this.logPrefix} Joined existing OAuth flow completed`);
            return {
              tokens,
              clientInfo: flowMeta?.clientInfo,
              metadata: flowMeta?.metadata,
              resourceMetadata: flowMeta?.resourceMetadata,
              clientSource: flowMeta?.clientSource,
              reusedStoredClient,
              reusedClientCredentialSetId,
            };
          }

          logger.debug(
            `${this.logPrefix} Found stale PENDING OAuth flow (${Math.round(pendingAge / 1000)}s old), will delete and start fresh`,
          );
        }

        if (existingFlow.status === 'COMPLETED') {
          const completedAge = existingFlow.completedAt
            ? Date.now() - existingFlow.completedAt
            : Infinity;
          const cachedTokens = existingFlow.result as MCPOAuthTokens | null | undefined;
          const isTokenExpired =
            cachedTokens?.expires_at != null &&
            normalizeExpiresAt(cachedTokens.expires_at) < Date.now();

          if (
            completedAge <= PENDING_STALE_MS &&
            cachedTokens !== undefined &&
            !isTokenExpired &&
            this.isCurrentServerOAuthFlow(flowMeta)
          ) {
            const reuseLease = await this.flowManager.acquireLease(oauthLeaseId, {
              expectedGeneration: oauthLeaseGeneration,
            });
            if (!reuseLease) {
              throw new Error('Cached OAuth result superseded by teardown');
            }
            logger.debug(
              `${this.logPrefix} Found non-stale COMPLETED OAuth flow, reusing cached tokens`,
            );
            try {
              return {
                tokens: cachedTokens,
                clientInfo: flowMeta?.clientInfo,
                metadata: flowMeta?.metadata,
                resourceMetadata: flowMeta?.resourceMetadata,
                clientSource: flowMeta?.clientSource,
                reusedStoredClient: flowMeta?.reusedStoredClient,
                reusedClientCredentialSetId: flowMeta?.reusedClientCredentialSetId,
              };
            } finally {
              await reuseLease.release();
            }
          }
        }

        logger.debug(
          `${this.logPrefix} Found existing OAuth flow (status: ${existingFlow.status}), cleaning up to start fresh`,
        );
        try {
          const oldState = flowMeta?.state;
          await this.flowManager.deleteFlow(flowId, 'mcp_oauth');
          if (oldState) {
            await MCPOAuthHandler.deleteStateMapping(oldState, this.flowManager);
          }
        } catch {
          logger.warn(`${this.logPrefix} Failed to clean up existing OAuth flow`);
        }
      }

      logger.debug(`${this.logPrefix} Initiating new OAuth flow`);
      const {
        authorizationUrl,
        flowId: newFlowId,
        flowMetadata,
      } = await this.runWithCapturedTenant(() =>
        MCPOAuthHandler.initiateOAuthFlow(
          this.serverName,
          serverUrl,
          this.userId!,
          this.serverConfig.oauth_headers ?? {},
          this.serverConfig.oauth,
          this.allowedDomains,
          this.tokenMethods?.deleteTokens ? this.tokenMethods.findToken : undefined,
          this.allowedAddresses,
          this.tenantId,
        ),
      );

      reusedStoredClient = flowMetadata.reusedStoredClient === true;
      reusedClientCredentialSetId = flowMetadata.reusedClientCredentialSetId;

      // Store flow state BEFORE redirecting so the callback can find it
      const metadataWithUrl = {
        ...flowMetadata,
        authorizationUrl,
        tenantId: this.tenantId,
        serverGeneration: getMCPServerGeneration(this.serverDefinition as t.ParsedServerConfig),
        oauthPersistenceWaitTimeout: this.serverConfig.oauthPersistenceWaitTimeout,
      };
      const publicationLease = await this.flowManager.acquireLease(oauthLeaseId, {
        expectedGeneration: oauthLeaseGeneration,
      });
      if (!publicationLease) {
        throw new Error('OAuth initiation superseded by teardown');
      }
      try {
        await this.flowManager.initFlow(newFlowId, 'mcp_oauth', metadataWithUrl);
        await MCPOAuthHandler.storeStateMapping(flowMetadata.state, newFlowId, this.flowManager);
      } finally {
        await publicationLease.release();
      }

      if (typeof this.oauthStart === 'function') {
        logger.info(`${this.logPrefix} OAuth flow started, issued authorization URL to user`);
        await this.oauthStart(authorizationUrl);
      } else {
        logger.info(
          `${this.logPrefix} OAuth flow started, no \`oauthStart\` handler defined, relying on callback endpoint`,
        );
      }

      // createFlow will find the existing PENDING state written by initFlow above,
      // so metadata arg is unused (pass {} to make that explicit)
      const tokens = await this.waitForSharedOAuthFlow(newFlowId);
      if (typeof this.oauthEnd === 'function') {
        await this.oauthEnd();
      }
      logger.info(`${this.logPrefix} OAuth flow completed; tokens received`);

      return {
        tokens,
        clientInfo: flowMetadata.clientInfo,
        metadata: flowMetadata.metadata,
        resourceMetadata: flowMetadata.resourceMetadata,
        clientSource: flowMetadata.clientSource,
        reusedStoredClient,
        reusedClientCredentialSetId,
      };
    } catch (error) {
      logger.error(`${this.logPrefix} Failed to complete OAuth flow`);
      return { tokens: null, reusedStoredClient, reusedClientCredentialSetId, error };
    }
  }

  private waitForSharedOAuthFlow(flowId: string): Promise<MCPOAuthTokens | null> {
    const flow = this.flowManager!.createFlow(flowId, 'mcp_oauth', {}, undefined, false);
    const signal = this.signal;
    if (!signal) {
      return flow;
    }

    return new Promise<MCPOAuthTokens | null>((resolve, reject) => {
      const cleanup = () => signal.removeEventListener('abort', onAbort);
      const onAbort = () => {
        cleanup();
        reject(
          signal.reason instanceof Error ? signal.reason : new Error('MCP OAuth flow wait aborted'),
        );
      };

      flow.then(
        (tokens) => {
          cleanup();
          resolve(tokens);
        },
        (error: unknown) => {
          cleanup();
          reject(error);
        },
      );

      if (signal.aborted) {
        onAbort();
        return;
      }

      signal.addEventListener('abort', onAbort, { once: true });
    });
  }
}