Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
39.7 KB
Raw Blame
import { randomUUID } from "node:crypto"
import { Buffer } from "node:buffer"
import { Client } from "@modelcontextprotocol/sdk/client/index.js"
import { env } from "../env.js"
import { createGuardedFetch, createRealmSafeFetch } from "./url-guard.js"
import {
  type OAuthClientProvider,
  UnauthorizedError,
} from "@modelcontextprotocol/sdk/client/auth.js"
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js"
import type {
  OAuthClientInformationFull,
  OAuthClientInformationMixed,
  OAuthTokens,
} from "@modelcontextprotocol/sdk/shared/auth.js"
import type { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.js"
import type { DenTypeId } from "@omnirush-ee/utils/typeid"
import type { ExternalMcpConnectionRow } from "./external-mcp-connections.js"
import {
  clearExternalMcpTokensForIdentity,
  deleteOrgOAuthClientForExternalMcpIdentity,
  getExternalMcpConnection,
  readConnectedAccountForExternalMcpIdentity,
  readOrgOAuthClientForExternalMcpIdentity,
  saveExternalMcpPendingCodeVerifierForIdentity,
  saveExternalMcpTokensForIdentity,
  upsertConnectedAccountForExternalMcpIdentity,
  upsertOrgOAuthClientForExternalMcpIdentity,
} from "./external-mcp-connections.js"
import {
  ExternalMcpDiagnosticError,
  ExternalMcpDiagnosticTracker,
  catalogDiagnosticError,
  createExternalMcpDiagnosticFetch,
  type ExternalMcpDiagnosticPhase,
  lifecycleDeadlineDiagnosticError,
  providerToolDiagnosticError,
} from "./external-mcp-diagnostics.js"
import {
  withExternalMcpToolCallInspection,
  type ExternalMcpToolCallInspector,
} from "./external-mcp-tool-inspection.js"

/**
 * Real MCP client for "add any MCP server" (External MCP Connections) —
 * as opposed to generic-oauth.ts, which only fits native providers with a
 * FIXED, admin-configured OAuth app (Google Workspace). Third-party MCP
 * servers (Notion, Linear, ...) don't have a pre-shared client_id: they
 * need RFC 9728 discovery + RFC 7591 dynamic client registration, which is
 * exactly what the MCP SDK's own OAuthClientProvider/auth() machinery
 * implements. This file is the one OAuthClientProvider implementation,
 * backed by our own tables, that every external connection uses.
 *
 * Dynamically-registered client info is stored in OrgOAuthClientTable
 * (providerId = the connection's own row id) — the same table used for
 * admin-configured native-provider clients, since the shape (client id +
 * optional secret + free-form extras) is identical either way.
 */

const CLIENT_NAME = "OmniRush.ai"
const EXTERNAL_MCP_CALL_TIMEOUT_MS = 30_000
const EXTERNAL_MCP_LIFECYCLE_TIMEOUT_MS = 45_000
export const EXTERNAL_MCP_TOOL_CALL_TIMEOUT_MS = 120_000
export const EXTERNAL_MCP_TOOL_LIFECYCLE_TIMEOUT_MS = 150_000
const EXTERNAL_MCP_TOOL_PAGE_LIMIT = 20
const EXTERNAL_MCP_TOOL_ITEM_LIMIT = 2_000
const EXTERNAL_MCP_TOOL_NAME_LIMIT_BYTES = 512
const EXTERNAL_MCP_TOOL_TITLE_LIMIT_BYTES = 4 * 1024
const EXTERNAL_MCP_TOOL_DESCRIPTION_LIMIT_BYTES = 64 * 1024
const EXTERNAL_MCP_TOOL_SCHEMA_LIMIT_BYTES = 512 * 1024
const EXTERNAL_MCP_TOOL_SCHEMA_DEPTH_LIMIT = 64
const EXTERNAL_MCP_CURSOR_LIMIT_BYTES = 16 * 1024
const EXTERNAL_MCP_CATALOG_LIMIT_BYTES = 8 * 1024 * 1024

export type ExternalMcpLifecycleDeadline = {
  expiresAt: number
  signal: AbortSignal
  abort: (reason?: unknown) => void
}

export function createExternalMcpLifecycleDeadline(
  timeoutMs = EXTERNAL_MCP_LIFECYCLE_TIMEOUT_MS,
): ExternalMcpLifecycleDeadline {
  const controller = new AbortController()
  return {
    expiresAt: Date.now() + Math.max(1, timeoutMs),
    signal: controller.signal,
    abort: (reason?: unknown) => controller.abort(reason),
  }
}

function assertExternalMcpLifecycleActive(input: {
  deadline: ExternalMcpLifecycleDeadline
  diagnostic: ExternalMcpDiagnosticTracker
  phase: ExternalMcpDiagnosticPhase
}): void {
  if (!input.deadline.signal.aborted && Date.now() < input.deadline.expiresAt) return
  const reason = input.deadline.signal.reason
  if (reason instanceof ExternalMcpDiagnosticError) throw reason
  const error = lifecycleDeadlineDiagnosticError({ tracker: input.diagnostic, phase: input.phase })
  if (!input.deadline.signal.aborted) input.deadline.abort(error)
  throw error
}

/**
 * The MCP SDK owns OAuth discovery, registration, refresh, and finishAuth
 * fetches. finishAuth accepts no RequestOptions, so bind the transport fetch
 * itself to the lifecycle signal instead of relying on the outer promise race.
 */
export function bindExternalMcpFetchToLifecycle(
  baseFetch: (url: string | URL, init?: RequestInit) => Promise<Response>,
  deadline: ExternalMcpLifecycleDeadline,
  diagnostic: ExternalMcpDiagnosticTracker,
) {
  return async (url: string | URL, init?: RequestInit): Promise<Response> => {
    assertExternalMcpLifecycleActive({ deadline, diagnostic, phase: diagnostic.activePhase })
    const signal = init?.signal
      ? AbortSignal.any([init.signal, deadline.signal])
      : deadline.signal
    return baseFetch(url, { ...init, signal })
  }
}

export async function runExternalMcpRequestWithinDeadline<T>(input: {
  deadline: ExternalMcpLifecycleDeadline
  diagnostic: ExternalMcpDiagnosticTracker
  phase: ExternalMcpDiagnosticPhase
  requestTimeoutMs?: number
  operation: (options: RequestOptions) => Promise<T>
}): Promise<T> {
  input.diagnostic.begin(input.phase)
  const remaining = Math.floor(input.deadline.expiresAt - Date.now())
  assertExternalMcpLifecycleActive({ deadline: input.deadline, diagnostic: input.diagnostic, phase: input.phase })

  const controller = new AbortController()
  const options: RequestOptions = {
    signal: AbortSignal.any([controller.signal, input.deadline.signal]),
    timeout: Math.max(1, Math.min(input.requestTimeoutMs ?? EXTERNAL_MCP_CALL_TIMEOUT_MS, remaining)),
    maxTotalTimeout: remaining,
    resetTimeoutOnProgress: false,
  }
  return await new Promise<T>((resolve, reject) => {
    let settled = false
    const timer = setTimeout(() => {
      if (settled) return
      settled = true
      const error = lifecycleDeadlineDiagnosticError({
        tracker: input.diagnostic,
        phase: input.diagnostic.activePhase,
      })
      input.deadline.abort(error)
      controller.abort(error)
      reject(error)
    }, remaining)
    void Promise.resolve().then(() => input.operation(options)).then(
      (value) => {
        if (settled) return
        settled = true
        clearTimeout(timer)
        resolve(value)
      },
      (error: unknown) => {
        if (settled) return
        settled = true
        clearTimeout(timer)
        reject(error)
      },
    )
  })
}

/**
 * Which member's credential this session should use, for connections with
 * credentialMode "per_member". Absent for "shared" connections (tokens live
 * on the connection row itself).
 */
export type ExternalMcpMemberContext = {
  orgMembershipId: DenTypeId<"member">
}

export class ExternalMcpOAuthProvider implements OAuthClientProvider {
  private connection: ExternalMcpConnectionRow
  private readonly redirectUri: string
  private readonly signedState?: string
  private readonly member?: ExternalMcpMemberContext
  private readonly diagnostic: ExternalMcpDiagnosticTracker
  private readonly lifecycleDeadline?: ExternalMcpLifecycleDeadline
  private tokenExchangeCodeVerifier: string | null = null
  /** Captured by redirectToAuthorization so the HTTP route can hand it back to the admin's browser instead of actually redirecting anything server-side. */
  lastAuthorizeUrl: string | null = null

  constructor(
    connection: ExternalMcpConnectionRow,
    redirectUri: string,
    signedState: string | undefined,
    member: ExternalMcpMemberContext | undefined,
    diagnostic: ExternalMcpDiagnosticTracker,
    lifecycleDeadline?: ExternalMcpLifecycleDeadline,
  ) {
    this.connection = connection
    this.redirectUri = redirectUri
    this.signedState = signedState
    this.member = member
    this.diagnostic = diagnostic
    this.lifecycleDeadline = lifecycleDeadline
    if (connection.credentialMode === "per_member" && connection.authType === "oauth" && !member) {
      throw new Error(`Connection "${connection.id}" uses per-member credentials; a member context is required.`)
    }
  }

  private get isPerMember(): boolean {
    return this.connection.credentialMode === "per_member"
  }

  private async memberAccount() {
    if (!this.member) return null
    const result = await readConnectedAccountForExternalMcpIdentity({
      connection: this.connection,
      orgMembershipId: this.member.orgMembershipId,
    })
    if (!result.current) throw new Error("The external MCP connection identity changed during authorization.")
    return result.value
  }

  private assertLifecycleActive(phase: ExternalMcpDiagnosticPhase): void {
    if (!this.lifecycleDeadline) return
    assertExternalMcpLifecycleActive({ deadline: this.lifecycleDeadline, diagnostic: this.diagnostic, phase })
  }

  get redirectUrl(): string {
    return this.redirectUri
  }

  /**
   * The SDK includes whatever this returns as the standard OAuth `state`
   * param, and — critically — every spec-compliant authorization server
   * (real or our stand-in) echoes `state` back verbatim on redirect. Our
   * own signed state token (which encodes which connection this is for)
   * MUST travel as this standard param, not a custom one: a custom param
   * would simply be dropped by any real server, since only `state` is
   * required to be preserved.
   */
  state(): string {
    // Only reached when a fresh authorize URL is actually being built (i.e.
    // connect/start, which always supplies signedState); this fallback only
    // exists to satisfy the type when connect() is attempted opportunistically
    // with an existing valid token and no authorization step is needed.
    return this.signedState ?? randomUUID()
  }

  get clientMetadata() {
    return {
      redirect_uris: [this.redirectUri],
      client_name: CLIENT_NAME,
      grant_types: ["authorization_code", "refresh_token"],
      response_types: ["code"],
      token_endpoint_auth_method: "none",
      application_type: "web",
    }
  }

  async clientInformation(): Promise<OAuthClientInformationMixed | undefined> {
    this.assertLifecycleActive("AUTH_CLIENT_REGISTRATION")
    const result = await readOrgOAuthClientForExternalMcpIdentity(this.connection)
    if (!result.current) throw new Error("The external MCP connection identity changed during authorization.")
    const client = result.value
    this.assertLifecycleActive("AUTH_CLIENT_REGISTRATION")
    if (!client) return undefined
    this.diagnostic.passed("AUTH_CLIENT_REGISTRATION", "reachable")
    const extra = (client.extra ?? {}) as { clientInformation?: OAuthClientInformationFull }
    if (extra.clientInformation) return extra.clientInformation
    return { client_id: client.clientId, client_secret: client.clientSecret ?? undefined }
  }

  async saveClientInformation(clientInformation: OAuthClientInformationMixed): Promise<void> {
    this.assertLifecycleActive("AUTH_CLIENT_REGISTRATION")
    const saved = await upsertOrgOAuthClientForExternalMcpIdentity({
      connection: this.connection,
      clientId: clientInformation.client_id,
      clientSecret: clientInformation.client_secret ?? null,
      extra: {
        clientInformation,
        enterpriseMcpRegistrationSource: "dynamic",
        registrationContractVersion: 2,
        registeredRedirectUri: this.redirectUri,
        authorizationServerIssuer: this.connection.oauthConfiguration?.authorizationServerIssuer ?? undefined,
      },
    })
    if (!saved) throw new Error("The external MCP connection identity changed during client registration.")
    this.diagnostic.passed("AUTH_CLIENT_REGISTRATION", "reachable")
  }

  async tokens(): Promise<OAuthTokens | undefined> {
    this.assertLifecycleActive("CONTINUITY_REFRESH")
    if (this.isPerMember) {
      const account = await this.memberAccount()
      this.assertLifecycleActive("CONTINUITY_REFRESH")
      if (!account?.accessToken) return undefined
      return {
        access_token: account.accessToken,
        token_type: account.tokenType ?? "Bearer",
        refresh_token: account.refreshToken ?? undefined,
        scope: account.scopes?.join(" ") ?? undefined,
      }
    }
    if (!this.connection.accessToken) return undefined
    return {
      access_token: this.connection.accessToken,
      token_type: this.connection.tokenType ?? "Bearer",
      refresh_token: this.connection.refreshToken ?? undefined,
      scope: this.connection.scope ?? undefined,
    }
  }

  async saveTokens(tokens: OAuthTokens): Promise<void> {
    const expiresAt = tokens.expires_in ? new Date(Date.now() + tokens.expires_in * 1000) : null
    if (this.isPerMember && this.member) {
      const existing = await this.memberAccount()
      this.assertLifecycleActive(this.diagnostic.activePhase === "CONTINUITY_REFRESH" ? "CONTINUITY_REFRESH" : "AUTH_TOKEN_ACQUISITION")
      const saved = await upsertConnectedAccountForExternalMcpIdentity({
        connection: this.connection,
        orgMembershipId: this.member.orgMembershipId,
        ...(this.tokenExchangeCodeVerifier ? { expectedPendingCodeVerifier: this.tokenExchangeCodeVerifier } : {}),
        changes: {
          accessToken: tokens.access_token,
          // Most providers omit refresh_token on refresh responses; keep the existing one.
          refreshToken: tokens.refresh_token ?? existing?.refreshToken ?? null,
          tokenType: tokens.token_type ?? null,
          scopes: tokens.scope ? tokens.scope.split(" ") : null,
          expiresAt,
          pendingCodeVerifier: null,
        },
      })
      if (!saved) throw new Error("The external MCP connection identity changed during token persistence.")
      this.tokenExchangeCodeVerifier = null
      this.diagnostic.passed("AUTH_TOKEN_ACQUISITION")
      return
    }
    this.assertLifecycleActive(this.diagnostic.activePhase === "CONTINUITY_REFRESH" ? "CONTINUITY_REFRESH" : "AUTH_TOKEN_ACQUISITION")
    const saved = await saveExternalMcpTokensForIdentity({
      connection: this.connection,
      accessToken: tokens.access_token,
      refreshToken: tokens.refresh_token ?? this.connection.refreshToken ?? null,
      tokenType: tokens.token_type ?? null,
      scope: tokens.scope ?? null,
      expiresAt,
      ...(this.tokenExchangeCodeVerifier ? { expectedPendingCodeVerifier: this.tokenExchangeCodeVerifier } : {}),
    })
    if (!saved) throw new Error("The external MCP connection identity changed during token persistence.")
    this.tokenExchangeCodeVerifier = null
    // Refresh the in-memory row so a subsequent tokens()/refresh in the same
    // connection attempt sees the just-saved values.
    const refreshed = await getExternalMcpConnection({
      organizationId: this.connection.organizationId,
      connectionId: this.connection.id,
    })
    if (refreshed) this.connection = refreshed
    this.diagnostic.passed("AUTH_TOKEN_ACQUISITION")
  }

  async invalidateCredentials(scope: "all" | "client" | "tokens" | "verifier" | "discovery"): Promise<void> {
    if (scope === "all" || scope === "client") {
      const deleted = await deleteOrgOAuthClientForExternalMcpIdentity(this.connection)
      if (!deleted) throw new Error("The external MCP connection identity changed during credential invalidation.")
    }
    if (scope === "all" || scope === "tokens") {
      if (this.isPerMember && this.member) {
        const cleared = await upsertConnectedAccountForExternalMcpIdentity({
          connection: this.connection,
          orgMembershipId: this.member.orgMembershipId,
          changes: {
            accessToken: null,
            refreshToken: null,
            tokenType: null,
            scopes: null,
            expiresAt: null,
            ...(scope === "all" ? { pendingCodeVerifier: null } : {}),
          },
        })
        if (!cleared) throw new Error("The external MCP connection identity changed during credential invalidation.")
      } else {
        const cleared = await clearExternalMcpTokensForIdentity(this.connection)
        if (!cleared) throw new Error("The external MCP connection identity changed during credential invalidation.")
        const refreshed = await getExternalMcpConnection({
          organizationId: this.connection.organizationId,
          connectionId: this.connection.id,
        })
        if (refreshed) this.connection = refreshed
      }
    }
    if ((scope === "all" || scope === "verifier") && !this.isPerMember) {
      const cleared = await saveExternalMcpPendingCodeVerifierForIdentity({ connection: this.connection, codeVerifier: null })
      if (!cleared) throw new Error("The external MCP connection identity changed during verifier invalidation.")
    }
    if (scope === "verifier" && this.isPerMember && this.member) {
      const cleared = await upsertConnectedAccountForExternalMcpIdentity({
        connection: this.connection,
        orgMembershipId: this.member.orgMembershipId,
        changes: { pendingCodeVerifier: null },
      })
      if (!cleared) throw new Error("The external MCP connection identity changed during verifier invalidation.")
    }
  }

  redirectToAuthorization(authorizationUrl: URL): void {
    this.lastAuthorizeUrl = authorizationUrl.toString()
    this.diagnostic.begin("AUTH_USER_OR_WORKLOAD")
  }

  async saveCodeVerifier(codeVerifier: string): Promise<void> {
    this.assertLifecycleActive("AUTH_USER_OR_WORKLOAD")
    if (this.isPerMember && this.member) {
      const saved = await upsertConnectedAccountForExternalMcpIdentity({
        connection: this.connection,
        orgMembershipId: this.member.orgMembershipId,
        changes: { pendingCodeVerifier: codeVerifier },
      })
      if (!saved) throw new Error("The external MCP connection identity changed during verifier persistence.")
      return
    }
    const saved = await saveExternalMcpPendingCodeVerifierForIdentity({ connection: this.connection, codeVerifier })
    if (!saved) throw new Error("The external MCP connection identity changed during verifier persistence.")
  }

  async codeVerifier(): Promise<string> {
    this.assertLifecycleActive("AUTH_TOKEN_ACQUISITION")
    if (this.isPerMember) {
      const account = await this.memberAccount()
      this.assertLifecycleActive("AUTH_TOKEN_ACQUISITION")
      if (!account?.pendingCodeVerifier) {
        throw new Error("No pending PKCE code verifier for this member on this external MCP connection.")
      }
      this.tokenExchangeCodeVerifier = account.pendingCodeVerifier
      return account.pendingCodeVerifier
    }
    if (!this.connection.pendingCodeVerifier) {
      throw new Error("No pending PKCE code verifier for this external MCP connection.")
    }
    this.tokenExchangeCodeVerifier = this.connection.pendingCodeVerifier
    return this.connection.pendingCodeVerifier
  }
}

function buildTransport(
  connection: ExternalMcpConnectionRow,
  redirectUri: string,
  signedState?: string,
  member?: ExternalMcpMemberContext,
  diagnosticReferenceId?: string,
  lifecycleDeadline?: ExternalMcpLifecycleDeadline,
  toolCallInspector?: ExternalMcpToolCallInspector,
) {
  if (connection.kind !== "external_mcp") {
    throw new Error("Native provider connectors do not expose an MCP server.")
  }
  const diagnostic = new ExternalMcpDiagnosticTracker(diagnosticReferenceId ?? randomUUID(), {
    authType: connection.authType,
    credentialMode: connection.credentialMode,
  })
  const provider = connection.authType === "oauth"
    ? new ExternalMcpOAuthProvider(connection, redirectUri, signedState, member, diagnostic, lifecycleDeadline)
    : undefined
  const guardedFetch = env.allowPrivateMcpUrls ? createRealmSafeFetch() : createGuardedFetch()
  const lifecycleFetch = lifecycleDeadline
    ? bindExternalMcpFetchToLifecycle(guardedFetch, lifecycleDeadline, diagnostic)
    : guardedFetch
  const diagnosticFetch = createExternalMcpDiagnosticFetch({ fetch: lifecycleFetch, endpoint: connection.url, tracker: diagnostic })
  const transport = new StreamableHTTPClientTransport(new URL(connection.url), {
    authProvider: provider,
    // SSRF guard: every outbound request (the MCP endpoint itself, but also
    // discovery documents and token endpoints the SDK follows to OTHER
    // hosts) is checked against private/reserved address ranges at request
    // time. Hosted-deployment protection; self-hosted/dev opt out via env.
    fetch: toolCallInspector ? toolCallInspector.observeFetch(diagnosticFetch) : diagnosticFetch,
    requestInit: connection.authType === "apikey" && connection.apiKey
      ? { headers: { authorization: `Bearer ${connection.apiKey}` } }
      : undefined,
  })
  return { transport, provider, diagnostic }
}

function buildClient() {
  return new Client({ name: "omnirush-den", version: "1.0.0" }, { capabilities: {} })
}

type ExternalMcpToolPage = Awaited<ReturnType<Client["listTools"]>>

type SerializedMeasurement =
  | { ok: true; bytes: number }
  | { ok: false; reason: "size" | "depth" | "cycle" }

function utf8Bytes(value: string): number {
  return Buffer.byteLength(value, "utf8")
}

function serializedStringBytes(value: string): number {
  return utf8Bytes(JSON.stringify(value))
}

function measureSerializedJson(
  value: unknown,
  byteLimit: number,
  depthLimit: number,
): SerializedMeasurement {
  type Frame =
    | { kind: "value"; value: unknown; depth: number }
    | { kind: "leave"; value: object }
  const stack: Frame[] = [{ kind: "value", value, depth: 0 }]
  const active = new WeakSet<object>()
  let bytes = 0
  const add = (amount: number): boolean => {
    bytes += amount
    return bytes <= byteLimit
  }

  while (stack.length > 0) {
    const frame = stack.pop()
    if (!frame) break
    if (frame.kind === "leave") {
      active.delete(frame.value)
      continue
    }
    if (frame.depth > depthLimit) return { ok: false, reason: "depth" }
    const current = frame.value
    if (current === null) {
      if (!add(4)) return { ok: false, reason: "size" }
      continue
    }
    if (typeof current === "string") {
      // Two quote bytes plus the UTF-8 payload. Escaping can only make the
      // serialized value larger, so account for the exact JSON string when
      // it contains characters that need escaping.
      const serialized = JSON.stringify(current)
      if (!add(utf8Bytes(serialized))) return { ok: false, reason: "size" }
      continue
    }
    if (typeof current === "number" || typeof current === "boolean") {
      if (!add(utf8Bytes(JSON.stringify(current)))) return { ok: false, reason: "size" }
      continue
    }
    if (typeof current !== "object") {
      if (!add(4)) return { ok: false, reason: "size" }
      continue
    }
    if (active.has(current)) return { ok: false, reason: "cycle" }
    active.add(current)
    stack.push({ kind: "leave", value: current })

    if (Array.isArray(current)) {
      if (!add(2 + Math.max(0, current.length - 1))) return { ok: false, reason: "size" }
      for (let index = current.length - 1; index >= 0; index -= 1) {
        stack.push({ kind: "value", value: current[index], depth: frame.depth + 1 })
      }
      continue
    }

    const entries = Object.entries(current)
    if (!add(2 + Math.max(0, entries.length - 1))) return { ok: false, reason: "size" }
    for (let index = entries.length - 1; index >= 0; index -= 1) {
      const [key, child] = entries[index]!
      if (!add(utf8Bytes(JSON.stringify(key)) + 1)) return { ok: false, reason: "size" }
      stack.push({ kind: "value", value: child, depth: frame.depth + 1 })
    }
  }
  return { ok: true, bytes }
}

function fieldLimitError(input: {
  diagnostic: ExternalMcpDiagnosticTracker
  code: "MCP_CATALOG_TOOL_NAME_LIMIT" | "MCP_CATALOG_TOOL_DESCRIPTION_LIMIT" | "MCP_CATALOG_TOOL_TITLE_LIMIT"
  field: string
  limit: number
}): ExternalMcpDiagnosticError {
  return catalogDiagnosticError({
    tracker: input.diagnostic,
    code: input.code,
    operatorAction: `Reduce each serialized tool ${input.field} below ${input.limit} UTF-8 bytes.`,
  })
}

function validateToolCatalogField(input: {
  diagnostic: ExternalMcpDiagnosticTracker
  value: string | undefined
  limit: number
  field: string
  code: "MCP_CATALOG_TOOL_NAME_LIMIT" | "MCP_CATALOG_TOOL_DESCRIPTION_LIMIT" | "MCP_CATALOG_TOOL_TITLE_LIMIT"
}): void {
  if (input.value !== undefined && serializedStringBytes(input.value) > input.limit) {
    throw fieldLimitError(input)
  }
}

function validateToolSchema(input: {
  diagnostic: ExternalMcpDiagnosticTracker
  schema: unknown
}): void {
  const measurement = measureSerializedJson(
    input.schema,
    EXTERNAL_MCP_TOOL_SCHEMA_LIMIT_BYTES,
    EXTERNAL_MCP_TOOL_SCHEMA_DEPTH_LIMIT,
  )
  if (measurement.ok) return
  const code = measurement.reason === "depth"
    ? "MCP_CATALOG_SCHEMA_DEPTH_LIMIT"
    : measurement.reason === "cycle"
      ? "MCP_CATALOG_SCHEMA_CYCLE"
      : "MCP_CATALOG_SCHEMA_SIZE_LIMIT"
  const operatorAction = measurement.reason === "depth"
    ? `Flatten each tool schema below ${EXTERNAL_MCP_TOOL_SCHEMA_DEPTH_LIMIT} nested levels.`
    : measurement.reason === "cycle"
      ? "Return JSON-serializable, acyclic tool schemas."
      : `Reduce each serialized tool schema below ${EXTERNAL_MCP_TOOL_SCHEMA_LIMIT_BYTES} bytes.`
  throw catalogDiagnosticError({ tracker: input.diagnostic, code, operatorAction })
}

function measureCatalogTool(input: {
  diagnostic: ExternalMcpDiagnosticTracker
  tool: ExternalMcpToolPage["tools"][number]
  remainingBytes: number
}): number {
  validateToolCatalogField({
    diagnostic: input.diagnostic,
    value: input.tool.name,
    field: "name",
    limit: EXTERNAL_MCP_TOOL_NAME_LIMIT_BYTES,
    code: "MCP_CATALOG_TOOL_NAME_LIMIT",
  })
  validateToolCatalogField({
    diagnostic: input.diagnostic,
    value: input.tool.title,
    field: "title",
    limit: EXTERNAL_MCP_TOOL_TITLE_LIMIT_BYTES,
    code: "MCP_CATALOG_TOOL_TITLE_LIMIT",
  })
  validateToolCatalogField({
    diagnostic: input.diagnostic,
    value: input.tool.description,
    field: "description",
    limit: EXTERNAL_MCP_TOOL_DESCRIPTION_LIMIT_BYTES,
    code: "MCP_CATALOG_TOOL_DESCRIPTION_LIMIT",
  })
  validateToolSchema({ diagnostic: input.diagnostic, schema: input.tool.inputSchema })
  if (input.tool.outputSchema !== undefined) {
    validateToolSchema({ diagnostic: input.diagnostic, schema: input.tool.outputSchema })
  }

  const measurement = measureSerializedJson(
    input.tool,
    Math.max(0, input.remainingBytes),
    EXTERNAL_MCP_TOOL_SCHEMA_DEPTH_LIMIT + 4,
  )
  if (!measurement.ok) {
    throw catalogDiagnosticError({
      tracker: input.diagnostic,
      code: "MCP_CATALOG_BYTE_LIMIT",
      operatorAction: `Reduce the complete serialized tool catalog below ${EXTERNAL_MCP_CATALOG_LIMIT_BYTES} bytes.`,
    })
  }
  return measurement.bytes
}

export async function collectExternalMcpToolPages(input: {
  listPage: (cursor: string | undefined, options: RequestOptions) => Promise<ExternalMcpToolPage>
  diagnostic: ExternalMcpDiagnosticTracker
  pageLimit?: number
  itemLimit?: number
  deadline?: ExternalMcpLifecycleDeadline
}): Promise<ExternalMcpToolPage["tools"]> {
  const pageLimit = input.pageLimit ?? EXTERNAL_MCP_TOOL_PAGE_LIMIT
  const itemLimit = input.itemLimit ?? EXTERNAL_MCP_TOOL_ITEM_LIMIT
  const deadline = input.deadline ?? createExternalMcpLifecycleDeadline()
  const tools: ExternalMcpToolPage["tools"] = []
  const seenCursors = new Set<string>()
  const seenToolNames = new Set<string>()
  let catalogBytes = 0
  let cursor: string | undefined
  for (let page = 0; page < pageLimit; page += 1) {
    input.diagnostic.begin("MCP_TOOL_DISCOVERY")
    const result = await runExternalMcpRequestWithinDeadline({
      deadline,
      diagnostic: input.diagnostic,
      phase: "MCP_TOOL_DISCOVERY",
      operation: (options) => input.listPage(cursor, options),
    })
    if (tools.length + result.tools.length > itemLimit) {
      throw catalogDiagnosticError({
        tracker: input.diagnostic,
        code: "MCP_CATALOG_ITEM_LIMIT",
        operatorAction: `Reduce the provider catalog below ${itemLimit} tools or use a scoped MCP server.`,
      })
    }
    for (const tool of result.tools) {
      catalogBytes += measureCatalogTool({
        diagnostic: input.diagnostic,
        tool,
        remainingBytes: EXTERNAL_MCP_CATALOG_LIMIT_BYTES - catalogBytes,
      })
      if (seenToolNames.has(tool.name)) {
        throw catalogDiagnosticError({
          tracker: input.diagnostic,
          code: "MCP_CATALOG_DUPLICATE_TOOL",
          operatorAction: "Ensure every tools/list page uses a unique, stable tool name.",
        })
      }
      seenToolNames.add(tool.name)
      tools.push(tool)
    }
    if (!result.nextCursor) {
      input.diagnostic.passed("MCP_TOOL_DISCOVERY", "catalog_ready")
      return tools
    }
    if (serializedStringBytes(result.nextCursor) > EXTERNAL_MCP_CURSOR_LIMIT_BYTES) {
      throw catalogDiagnosticError({
        tracker: input.diagnostic,
        code: "MCP_CATALOG_CURSOR_SIZE_LIMIT",
        operatorAction: `Reduce each serialized tools/list cursor below ${EXTERNAL_MCP_CURSOR_LIMIT_BYTES} UTF-8 bytes.`,
      })
    }
    const cursorMeasurement = measureSerializedJson(
      result.nextCursor,
      EXTERNAL_MCP_CATALOG_LIMIT_BYTES - catalogBytes,
      1,
    )
    if (!cursorMeasurement.ok) {
      throw catalogDiagnosticError({
        tracker: input.diagnostic,
        code: "MCP_CATALOG_BYTE_LIMIT",
        operatorAction: `Reduce the complete serialized tool catalog below ${EXTERNAL_MCP_CATALOG_LIMIT_BYTES} bytes.`,
      })
    }
    catalogBytes += cursorMeasurement.bytes
    if (seenCursors.has(result.nextCursor)) {
      throw catalogDiagnosticError({
        tracker: input.diagnostic,
        code: "MCP_CATALOG_CURSOR_LOOP",
        operatorAction: "Fix the provider's tools/list pagination so each nextCursor advances.",
      })
    }
    seenCursors.add(result.nextCursor)
    cursor = result.nextCursor
  }
  throw catalogDiagnosticError({
    tracker: input.diagnostic,
    code: "MCP_CATALOG_PAGE_LIMIT",
    operatorAction: `Reduce the provider catalog to at most ${pageLimit} pages or use a scoped MCP server.`,
  })
}

export type ExternalMcpConnectResult =
  | { status: "connected" }
  | { status: "needs_auth"; authorizeUrl: string }

/**
 * Attempts to connect. For authType "none"/"apikey" this either succeeds or
 * throws. For "oauth", if there's no valid token yet, the SDK's transport
 * drives discovery (+ dynamic client registration if needed) and returns the
 * authorize URL to send the admin's browser to — no token exchange happens
 * yet, that's connect/callback's job. `signedState` (our own signed token
 * identifying which connection this is for) is passed through as the
 * standard OAuth `state` param, since that's the only param guaranteed to
 * round-trip back to connect/callback on any spec-compliant server.
 */
export async function connectExternalMcp(
  connection: ExternalMcpConnectionRow,
  redirectUri: string,
  signedState?: string,
  member?: ExternalMcpMemberContext,
  diagnosticReferenceId?: string,
): Promise<ExternalMcpConnectResult> {
  const client = buildClient()
  const deadline = createExternalMcpLifecycleDeadline()
  const { transport, provider, diagnostic } = buildTransport(
    connection,
    redirectUri,
    signedState,
    member,
    diagnosticReferenceId,
    deadline,
  )
  let result: ExternalMcpConnectResult | undefined
  let primaryError: unknown
  try {
    await runExternalMcpRequestWithinDeadline({
      deadline,
      diagnostic,
      phase: "MCP_INITIALIZE",
      operation: (options) => client.connect(transport, options),
    })
    diagnostic.passed("MCP_INITIALIZED", "protocol_ready")
    result = { status: "connected" }
  } catch (error) {
    if (error instanceof UnauthorizedError && provider?.lastAuthorizeUrl) {
      diagnostic.begin("AUTH_USER_OR_WORKLOAD")
      result = { status: "needs_auth", authorizeUrl: provider.lastAuthorizeUrl }
    } else {
      // Freeze the causal phase before close() can perform any additional
      // transport work and move the tracker to another lifecycle phase.
      primaryError = diagnostic.error(error)
    }
  } finally {
    try {
      await client.close()
    } catch (error) {
      // Never replace the causal handshake error. A close failure after a
      // successful connection is its own lifecycle diagnostic; closing an
      // unauthenticated transport is best-effort but still always attempted.
      if (!primaryError && result?.status === "connected") {
        primaryError = diagnostic.error(error, "SHUTDOWN")
      }
    }
  }
  if (primaryError) throw diagnostic.error(primaryError)
  if (!result) throw diagnostic.error(new Error("MCP connection ended without a result."), "MCP_INITIALIZE")
  return result
}

/** Completes the OAuth code exchange after the browser is redirected back with `code`. For per-member connections, `member` (from the signed state token) decides whose account the tokens are saved against. */
export async function runExternalMcpAuthCompletionLifecycle(input: {
  diagnostic: ExternalMcpDiagnosticTracker
  finishAuth: () => Promise<void>
  validateMcp: (options?: RequestOptions) => Promise<void>
  invalidateTokens: () => Promise<void>
  close: () => Promise<void>
  deadline?: ExternalMcpLifecycleDeadline
}): Promise<void> {
  const deadline = input.deadline ?? createExternalMcpLifecycleDeadline()
  input.diagnostic.begin("AUTH_TOKEN_ACQUISITION")
  let exchangedTokens = false
  let primaryError: ExternalMcpDiagnosticError | null = null
  try {
    await runExternalMcpRequestWithinDeadline({
      deadline,
      diagnostic: input.diagnostic,
      phase: "AUTH_TOKEN_ACQUISITION",
      operation: () => input.finishAuth(),
    })
    exchangedTokens = true
    input.diagnostic.passed("AUTH_TOKEN_ACQUISITION")
    await runExternalMcpRequestWithinDeadline({
      deadline,
      diagnostic: input.diagnostic,
      phase: "MCP_INITIALIZE",
      operation: (options) => input.validateMcp(options),
    })
    input.diagnostic.passed("MCP_INITIALIZED", "protocol_ready")
  } catch (error) {
    primaryError = input.diagnostic.error(error, exchangedTokens ? "MCP_INITIALIZE" : "AUTH_TOKEN_ACQUISITION")
    if (exchangedTokens) {
      try {
        await input.invalidateTokens()
      } catch {
        // Cleanup must not replace the causal validation diagnostic.
      }
    }
  } finally {
    try {
      await input.close()
    } catch (error) {
      if (!primaryError) primaryError = input.diagnostic.error(error, "SHUTDOWN")
    }
  }
  if (primaryError) throw primaryError
}

export async function completeExternalMcpAuth(
  connection: ExternalMcpConnectionRow,
  code: string,
  redirectUri: string,
  member?: ExternalMcpMemberContext,
  diagnosticReferenceId?: string,
): Promise<void> {
  const client = buildClient()
  const deadline = createExternalMcpLifecycleDeadline()
  const { transport, provider, diagnostic } = buildTransport(
    connection,
    redirectUri,
    undefined,
    member,
    diagnosticReferenceId,
    deadline,
  )
  await runExternalMcpAuthCompletionLifecycle({
    diagnostic,
    finishAuth: () => transport.finishAuth(code),
    // A token response alone does not prove audience, tenant, scopes, or MCP
    // readiness. Initialize with the newly stored credential before success.
    validateMcp: (options) => client.connect(transport, options),
    invalidateTokens: () => provider?.invalidateCredentials?.("tokens") ?? Promise.resolve(),
    close: () => client.close(),
    deadline,
  })
}

/**
 * Compatibility cleanup for a version-one authorization that was started by
 * the pre-enterprise runtime. Those flows stored one plaintext verifier slot,
 * so they cannot be consumed by the version-two state-hash transaction store.
 */
export async function abandonExternalMcpAuth(
  connection: ExternalMcpConnectionRow,
  _signedState: string,
  member?: ExternalMcpMemberContext,
  _diagnosticReferenceId?: string,
): Promise<void> {
  if (connection.credentialMode === "per_member") {
    if (!member) return
    const existing = await readConnectedAccountForExternalMcpIdentity({
      connection,
      orgMembershipId: member.orgMembershipId,
    })
    if (!existing.current) throw new Error("The external MCP connection identity changed during authorization cleanup.")
    if (!existing.value) return
    const cleared = await upsertConnectedAccountForExternalMcpIdentity({
      connection,
      orgMembershipId: member.orgMembershipId,
      changes: { pendingCodeVerifier: null },
    })
    if (!cleared) throw new Error("The external MCP connection identity changed during authorization cleanup.")
    return
  }
  const cleared = await saveExternalMcpPendingCodeVerifierForIdentity({ connection, codeVerifier: null })
  if (!cleared) throw new Error("The external MCP connection identity changed during authorization cleanup.")
}

export async function listExternalMcpTools(
  connection: ExternalMcpConnectionRow,
  redirectUri: string,
  member?: ExternalMcpMemberContext,
  diagnosticReferenceId?: string,
  lifecycleDeadline?: ExternalMcpLifecycleDeadline,
) {
  if (connection.kind !== "external_mcp") {
    throw new Error("Native provider connectors do not expose an MCP tool catalog.")
  }
  const client = buildClient()
  const deadline = lifecycleDeadline ?? createExternalMcpLifecycleDeadline()
  const { transport, diagnostic } = buildTransport(
    connection,
    redirectUri,
    undefined,
    member,
    diagnosticReferenceId,
    deadline,
  )
  let operationError: unknown
  try {
    await runExternalMcpRequestWithinDeadline({
      deadline,
      diagnostic,
      phase: "MCP_INITIALIZE",
      operation: (options) => client.connect(transport, options),
    })
    diagnostic.passed("MCP_INITIALIZED", "protocol_ready")
    return await collectExternalMcpToolPages({
      diagnostic,
      deadline,
      listPage: (cursor, options) => client.listTools(cursor ? { cursor } : undefined, options),
    })
  } catch (error) {
    operationError = error
    throw diagnostic.error(error)
  } finally {
    try {
      await client.close()
    } catch (error) {
      if (!operationError) throw diagnostic.error(error, "SHUTDOWN")
    }
  }
}

type ExternalMcpToolCallInput = {
  connection: ExternalMcpConnectionRow
  redirectUri: string
  toolName: string
  args: Record<string, unknown>
  member?: ExternalMcpMemberContext
  diagnosticReferenceId?: string
}

async function runExternalMcpToolCall(
  input: ExternalMcpToolCallInput,
  toolCallInspector?: ExternalMcpToolCallInspector,
) {
  if (input.connection.kind !== "external_mcp") {
    throw new Error("Native provider connectors do not expose MCP tools.")
  }
  const client = buildClient()
  const deadline = createExternalMcpLifecycleDeadline(EXTERNAL_MCP_TOOL_LIFECYCLE_TIMEOUT_MS)
  const { transport, diagnostic } = buildTransport(
    input.connection,
    input.redirectUri,
    undefined,
    input.member,
    input.diagnosticReferenceId,
    deadline,
    toolCallInspector,
  )
  let operationError: unknown
  try {
    await runExternalMcpRequestWithinDeadline({
      deadline,
      diagnostic,
      phase: "MCP_INITIALIZE",
      operation: (options) => client.connect(transport, options),
    })
    diagnostic.passed("MCP_INITIALIZED", "protocol_ready")
    diagnostic.begin("MCP_TOOL_EXECUTION")
    const result = await runExternalMcpRequestWithinDeadline({
      deadline,
      diagnostic,
      phase: "MCP_TOOL_EXECUTION",
      requestTimeoutMs: EXTERNAL_MCP_TOOL_CALL_TIMEOUT_MS,
      operation: (options) => client.callTool({ name: input.toolName, arguments: input.args }, undefined, options),
    })
    if (result.isError) {
      throw providerToolDiagnosticError({ tracker: diagnostic, result })
    }
    diagnostic.passed("PROVIDER_EXECUTION", "operation_ready")
    return result
  } catch (error) {
    operationError = error
    throw diagnostic.error(error)
  } finally {
    try {
      await client.close()
    } catch (error) {
      if (!operationError) throw diagnostic.error(error, "SHUTDOWN")
    }
  }
}

export function callExternalMcpTool(input: ExternalMcpToolCallInput) {
  return runExternalMcpToolCall(input)
}

export function inspectExternalMcpToolCall(input: ExternalMcpToolCallInput) {
  return withExternalMcpToolCallInspection((inspector) => runExternalMcpToolCall(input, inspector))
}