@xelauvas/xela-cli 0.1.0

package/src/services/mcp/auth.ts

@@ -0,0 +1,2465 @@
+import {
+  discoverAuthorizationServerMetadata,
+  discoverOAuthServerInfo,
+  type OAuthClientProvider,
+  type OAuthDiscoveryState,
+  auth as sdkAuth,
+  refreshAuthorization as sdkRefreshAuthorization,
+} from '@modelcontextprotocol/sdk/client/auth.js'
+import {
+  InvalidGrantError,
+  OAuthError,
+  ServerError,
+  TemporarilyUnavailableError,
+  TooManyRequestsError,
+} from '@modelcontextprotocol/sdk/server/auth/errors.js'
+import {
+  type AuthorizationServerMetadata,
+  type OAuthClientInformation,
+  type OAuthClientInformationFull,
+  type OAuthClientMetadata,
+  OAuthErrorResponseSchema,
+  OAuthMetadataSchema,
+  type OAuthTokens,
+  OAuthTokensSchema,
+} from '@modelcontextprotocol/sdk/shared/auth.js'
+import type { FetchLike } from '@modelcontextprotocol/sdk/shared/transport.js'
+import axios from 'axios'
+import { createHash, randomBytes, randomUUID } from 'crypto'
+import { mkdir } from 'fs/promises'
+import { createServer, type Server } from 'http'
+import { join } from 'path'
+import { parse } from 'url'
+import xss from 'xss'
+import { MCP_CLIENT_METADATA_URL } from '../../constants/oauth.js'
+import { openBrowser } from '../../utils/browser.js'
+import { getClaudeConfigHomeDir } from '../../utils/envUtils.js'
+import { errorMessage, getErrnoCode } from '../../utils/errors.js'
+import * as lockfile from '../../utils/lockfile.js'
+import { logMCPDebug } from '../../utils/log.js'
+import { getPlatform } from '../../utils/platform.js'
+import { getSecureStorage } from '../../utils/secureStorage/index.js'
+import { clearKeychainCache } from '../../utils/secureStorage/macOsKeychainHelpers.js'
+import type { SecureStorageData } from '../../utils/secureStorage/types.js'
+import { sleep } from '../../utils/sleep.js'
+import { jsonParse, jsonStringify } from '../../utils/slowOperations.js'
+import { logEvent } from '../analytics/index.js'
+import type { AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS } from '../analytics/metadata.js'
+import { buildRedirectUri, findAvailablePort } from './oauthPort.js'
+import type { McpHTTPServerConfig, McpSSEServerConfig } from './types.js'
+import { getLoggingSafeMcpBaseUrl } from './utils.js'
+import { performCrossAppAccess, XaaTokenExchangeError } from './xaa.js'
+import {
+  acquireIdpIdToken,
+  clearIdpIdToken,
+  discoverOidc,
+  getCachedIdpIdToken,
+  getIdpClientSecret,
+  getXaaIdpSettings,
+  isXaaEnabled,
+} from './xaaIdpLogin.js'
+
+/**
+ * Timeout for individual OAuth requests (metadata discovery, token refresh, etc.)
+ */
+const AUTH_REQUEST_TIMEOUT_MS = 30000
+
+/**
+ * Failure reasons for the `tengu_mcp_oauth_refresh_failure` event. Values
+ * are emitted to analytics — keep them stable (do not rename; add new ones).
+ */
+type MCPRefreshFailureReason =
+  | 'metadata_discovery_failed'
+  | 'no_client_info'
+  | 'no_tokens_returned'
+  | 'invalid_grant'
+  | 'transient_retries_exhausted'
+  | 'request_failed'
+
+/**
+ * Failure reasons for the `tengu_mcp_oauth_flow_error` event. Values are
+ * emitted to analytics for attribution in BigQuery. Keep stable (do not
+ * rename; add new ones).
+ */
+type MCPOAuthFlowErrorReason =
+  | 'cancelled'
+  | 'timeout'
+  | 'provider_denied'
+  | 'state_mismatch'
+  | 'port_unavailable'
+  | 'sdk_auth_failed'
+  | 'token_exchange_failed'
+  | 'unknown'
+
+const MAX_LOCK_RETRIES = 5
+
+/**
+ * OAuth query parameters that should be redacted from logs.
+ * These contain sensitive values that could enable CSRF or session fixation attacks.
+ */
+const SENSITIVE_OAUTH_PARAMS = [
+  'state',
+  'nonce',
+  'code_challenge',
+  'code_verifier',
+  'code',
+]
+
+/**
+ * Redacts sensitive OAuth query parameters from a URL for safe logging.
+ * Prevents exposure of state, nonce, code_challenge, code_verifier, and authorization codes.
+ */
+function redactSensitiveUrlParams(url: string): string {
+  try {
+    const parsedUrl = new URL(url)
+    for (const param of SENSITIVE_OAUTH_PARAMS) {
+      if (parsedUrl.searchParams.has(param)) {
+        parsedUrl.searchParams.set(param, '[REDACTED]')
+      }
+    }
+    return parsedUrl.toString()
+  } catch {
+    // Return as-is if not a valid URL
+    return url
+  }
+}
+
+/**
+ * Some OAuth servers (notably Slack) return HTTP 200 for all responses,
+ * signaling errors via the JSON body instead. The SDK's executeTokenRequest
+ * only calls parseErrorResponse when !response.ok, so a 200 with
+ * {"error":"invalid_grant"} gets fed to OAuthTokensSchema.parse() and
+ * surfaces as a ZodError — which the refresh retry/invalidation logic
+ * treats as opaque request_failed instead of invalid_grant.
+ *
+ * This wrapper peeks at 2xx POST response bodies and rewrites ones that
+ * match OAuthErrorResponseSchema (but not OAuthTokensSchema) to a 400
+ * Response, so the SDK's normal error-class mapping applies. The same
+ * fetchFn is also used for DCR POSTs, but DCR success responses have no
+ * {error: string} field so they don't match the rewrite condition.
+ *
+ * Slack uses non-standard error codes (invalid_refresh_token observed live
+ * at oauth.v2.user.access; expired_refresh_token/token_expired per Slack's
+ * token rotation docs) where RFC 6749 specifies invalid_grant. We normalize
+ * those so OAUTH_ERRORS['invalid_grant'] → InvalidGrantError matches and
+ * token invalidation fires correctly.
+ */
+const NONSTANDARD_INVALID_GRANT_ALIASES = new Set([
+  'invalid_refresh_token',
+  'expired_refresh_token',
+  'token_expired',
+])
+
+/* eslint-disable eslint-plugin-n/no-unsupported-features/node-builtins --
+ * Response has been stable in Node since 18; the rule flags it as
+ * experimental-until-21 which is incorrect. Pattern matches existing
+ * createAuthFetch suppressions in this file. */
+export async function normalizeOAuthErrorBody(
+  response: Response,
+): Promise<Response> {
+  if (!response.ok) {
+    return response
+  }
+  const text = await response.text()
+  let parsed: unknown
+  try {
+    parsed = jsonParse(text)
+  } catch {
+    return new Response(text, response)
+  }
+  if (OAuthTokensSchema.safeParse(parsed).success) {
+    return new Response(text, response)
+  }
+  const result = OAuthErrorResponseSchema.safeParse(parsed)
+  if (!result.success) {
+    return new Response(text, response)
+  }
+  const normalized = NONSTANDARD_INVALID_GRANT_ALIASES.has(result.data.error)
+    ? {
+        error: 'invalid_grant',
+        error_description:
+          result.data.error_description ??
+          `Server returned non-standard error code: ${result.data.error}`,
+      }
+    : result.data
+  return new Response(jsonStringify(normalized), {
+    status: 400,
+    statusText: 'Bad Request',
+    headers: response.headers,
+  })
+}
+/* eslint-enable eslint-plugin-n/no-unsupported-features/node-builtins */
+
+/**
+ * Creates a fetch function with a fresh 30-second timeout for each OAuth request.
+ * Used by ClaudeAuthProvider for metadata discovery and token refresh.
+ * Prevents stale timeout signals from affecting auth operations.
+ */
+function createAuthFetch(): FetchLike {
+  return async (url: string | URL, init?: RequestInit) => {
+    const timeoutSignal = AbortSignal.timeout(AUTH_REQUEST_TIMEOUT_MS)
+    const isPost = init?.method?.toUpperCase() === 'POST'
+
+    // No existing signal - just use timeout
+    if (!init?.signal) {
+      // eslint-disable-next-line eslint-plugin-n/no-unsupported-features/node-builtins
+      const response = await fetch(url, { ...init, signal: timeoutSignal })
+      return isPost ? normalizeOAuthErrorBody(response) : response
+    }
+
+    // Combine signals: abort when either fires
+    const controller = new AbortController()
+    const abort = () => controller.abort()
+
+    init.signal.addEventListener('abort', abort)
+    timeoutSignal.addEventListener('abort', abort)
+
+    // Cleanup to prevent event listener leaks after fetch completes
+    const cleanup = () => {
+      init.signal?.removeEventListener('abort', abort)
+      timeoutSignal.removeEventListener('abort', abort)
+    }
+
+    if (init.signal.aborted) {
+      controller.abort()
+    }
+
+    try {
+      // eslint-disable-next-line eslint-plugin-n/no-unsupported-features/node-builtins
+      const response = await fetch(url, { ...init, signal: controller.signal })
+      cleanup()
+      return isPost ? normalizeOAuthErrorBody(response) : response
+    } catch (error) {
+      cleanup()
+      throw error
+    }
+  }
+}
+
+/**
+ * Fetches authorization server metadata, using a configured metadata URL if available,
+ * otherwise performing RFC 9728 → RFC 8414 discovery via the SDK.
+ *
+ * Discovery order when no configured URL:
+ * 1. RFC 9728: probe /.well-known/oauth-protected-resource on the MCP server,
+ *    read authorization_servers[0], then RFC 8414 against that URL.
+ * 2. Fallback: RFC 8414 directly against the MCP server URL (path-aware). Covers
+ *    legacy servers that co-host auth metadata at /.well-known/oauth-authorization-server/{path}
+ *    without implementing RFC 9728. The SDK's own fallback strips the path, so this
+ *    preserves the pre-existing path-aware probe for backward compatibility.
+ *
+ * Note: configuredMetadataUrl is user-controlled via .mcp.json. Project-scoped MCP
+ * servers require user approval before connecting (same trust level as the MCP server
+ * URL itself). The HTTPS requirement here is defense-in-depth beyond schema validation
+ * — RFC 8414 mandates OAuth metadata retrieval over TLS.
+ */
+async function fetchAuthServerMetadata(
+  serverName: string,
+  serverUrl: string,
+  configuredMetadataUrl: string | undefined,
+  fetchFn?: FetchLike,
+  resourceMetadataUrl?: URL,
+): Promise<Awaited<ReturnType<typeof discoverAuthorizationServerMetadata>>> {
+  if (configuredMetadataUrl) {
+    if (!configuredMetadataUrl.startsWith('https://')) {
+      throw new Error(
+        `authServerMetadataUrl must use https:// (got: ${configuredMetadataUrl})`,
+      )
+    }
+    const authFetch = fetchFn ?? createAuthFetch()
+    const response = await authFetch(configuredMetadataUrl, {
+      headers: { Accept: 'application/json' },
+    })
+    if (response.ok) {
+      return OAuthMetadataSchema.parse(await response.json())
+    }
+    throw new Error(
+      `HTTP ${response.status} fetching configured auth server metadata from ${configuredMetadataUrl}`,
+    )
+  }
+
+  try {
+    const { authorizationServerMetadata } = await discoverOAuthServerInfo(
+      serverUrl,
+      {
+        ...(fetchFn && { fetchFn }),
+        ...(resourceMetadataUrl && { resourceMetadataUrl }),
+      },
+    )
+    if (authorizationServerMetadata) {
+      return authorizationServerMetadata
+    }
+  } catch (err) {
+    // Any error from the RFC 9728 → RFC 8414 chain (5xx from the root or
+    // resolved-AS probe, schema parse failure, network error) — fall through
+    // to the legacy path-aware retry.
+    logMCPDebug(
+      serverName,
+      `RFC 9728 discovery failed, falling back: ${errorMessage(err)}`,
+    )
+  }
+
+  // Fallback only when the URL has a path component; for root URLs the SDK's
+  // own fallback already probed the same endpoints.
+  const url = new URL(serverUrl)
+  if (url.pathname === '/') {
+    return undefined
+  }
+  return discoverAuthorizationServerMetadata(url, {
+    ...(fetchFn && { fetchFn }),
+  })
+}
+
+export class AuthenticationCancelledError extends Error {
+  constructor() {
+    super('Authentication was cancelled')
+    this.name = 'AuthenticationCancelledError'
+  }
+}
+
+/**
+ * Generates a unique key for server credentials based on both name and config hash
+ * This prevents credentials from being reused across different servers
+ * with the same name or different configurations
+ */
+export function getServerKey(
+  serverName: string,
+  serverConfig: McpSSEServerConfig | McpHTTPServerConfig,
+): string {
+  const configJson = jsonStringify({
+    type: serverConfig.type,
+    url: serverConfig.url,
+    headers: serverConfig.headers || {},
+  })
+
+  const hash = createHash('sha256')
+    .update(configJson)
+    .digest('hex')
+    .substring(0, 16)
+
+  return `${serverName}|${hash}`
+}
+
+/**
+ * True when we have probed this server before (OAuth discovery state is
+ * stored) but hold no credentials to try. A connection attempt in this
+ * state is guaranteed to 401 — the only way out is the user running
+ * /mcp to authenticate.
+ */
+export function hasMcpDiscoveryButNoToken(
+  serverName: string,
+  serverConfig: McpSSEServerConfig | McpHTTPServerConfig,
+): boolean {
+  // XAA servers can silently re-auth via cached id_token even without an
+  // access/refresh token — tokens() fires the xaaRefresh path. Skipping the
+  // connection here would make that auto-auth branch unreachable after
+  // invalidateCredentials('tokens') clears the stored tokens.
+  if (isXaaEnabled() && serverConfig.oauth?.xaa) {
+    return false
+  }
+  const serverKey = getServerKey(serverName, serverConfig)
+  const entry = getSecureStorage().read()?.mcpOAuth?.[serverKey]
+  return entry !== undefined && !entry.accessToken && !entry.refreshToken
+}
+
+/**
+ * Revokes a single token on the OAuth server.
+ *
+ * Per RFC 7009, public clients (like Claude Code) should authenticate by including
+ * client_id in the request body, NOT via an Authorization header. The Bearer token
+ * in an Authorization header is meant for resource owner authentication, not client
+ * authentication.
+ *
+ * However, the MCP spec doesn't explicitly define token revocation behavior, so some
+ * servers may not be RFC 7009 compliant. As defensive programming, we:
+ * 1. First try the RFC 7009 compliant approach (client_id in body, no Authorization header)
+ * 2. If we get a 401, retry with Bearer auth as a fallback for non-compliant servers
+ *
+ * This fallback should rarely be needed - most servers either accept the compliant
+ * approach or ignore unexpected headers.
+ */
+async function revokeToken({
+  serverName,
+  endpoint,
+  token,
+  tokenTypeHint,
+  clientId,
+  clientSecret,
+  accessToken,
+  authMethod = 'client_secret_basic',
+}: {
+  serverName: string
+  endpoint: string
+  token: string
+  tokenTypeHint: 'access_token' | 'refresh_token'
+  clientId?: string
+  clientSecret?: string
+  accessToken?: string
+  authMethod?: 'client_secret_basic' | 'client_secret_post'
+}): Promise<void> {
+  const params = new URLSearchParams()
+  params.set('token', token)
+  params.set('token_type_hint', tokenTypeHint)
+
+  const headers: Record<string, string> = {
+    'Content-Type': 'application/x-www-form-urlencoded',
+  }
+
+  // RFC 7009 §2.1 requires client auth per RFC 6749 §2.3. XAA always uses a
+  // confidential client at the AS — strict ASes (Okta/Stytch) reject public-
+  // client revocation of confidential-client tokens.
+  if (clientId && clientSecret) {
+    if (authMethod === 'client_secret_post') {
+      params.set('client_id', clientId)
+      params.set('client_secret', clientSecret)
+    } else {
+      const basic = Buffer.from(
+        `${encodeURIComponent(clientId)}:${encodeURIComponent(clientSecret)}`,
+      ).toString('base64')
+      headers.Authorization = `Basic ${basic}`
+    }
+  } else if (clientId) {
+    params.set('client_id', clientId)
+  } else {
+    logMCPDebug(
+      serverName,
+      `No client_id available for ${tokenTypeHint} revocation - server may reject`,
+    )
+  }
+
+  try {
+    await axios.post(endpoint, params, { headers })
+    logMCPDebug(serverName, `Successfully revoked ${tokenTypeHint}`)
+  } catch (error: unknown) {
+    // Fallback for non-RFC-7009-compliant servers that require Bearer auth
+    if (
+      axios.isAxiosError(error) &&
+      error.response?.status === 401 &&
+      accessToken
+    ) {
+      logMCPDebug(
+        serverName,
+        `Got 401, retrying ${tokenTypeHint} revocation with Bearer auth`,
+      )
+      // RFC 6749 §2.3.1: must not send more than one auth method. The retry
+      // switches to Bearer — clear any client creds from the body.
+      params.delete('client_id')
+      params.delete('client_secret')
+      await axios.post(endpoint, params, {
+        headers: { ...headers, Authorization: `Bearer ${accessToken}` },
+      })
+      logMCPDebug(
+        serverName,
+        `Successfully revoked ${tokenTypeHint} with Bearer auth`,
+      )
+    } else {
+      throw error
+    }
+  }
+}
+
+/**
+ * Revokes tokens on the OAuth server if a revocation endpoint is available.
+ * Per RFC 7009, we revoke the refresh token first (the long-lived credential),
+ * then the access token. Revoking the refresh token prevents generation of new
+ * access tokens and many servers implicitly invalidate associated access tokens.
+ */
+export async function revokeServerTokens(
+  serverName: string,
+  serverConfig: McpSSEServerConfig | McpHTTPServerConfig,
+  { preserveStepUpState = false }: { preserveStepUpState?: boolean } = {},
+): Promise<void> {
+  const storage = getSecureStorage()
+  const existingData = storage.read()
+  if (!existingData?.mcpOAuth) return
+
+  const serverKey = getServerKey(serverName, serverConfig)
+  const tokenData = existingData.mcpOAuth[serverKey]
+
+  // Attempt server-side revocation if there are tokens to revoke (best-effort)
+  if (tokenData?.accessToken || tokenData?.refreshToken) {
+    try {
+      // For XAA (and any PRM-discovered auth), the AS is at a different host
+      // than the MCP URL — use the persisted discoveryState if we have it.
+      const asUrl =
+        tokenData.discoveryState?.authorizationServerUrl ?? serverConfig.url
+      const metadata = await fetchAuthServerMetadata(
+        serverName,
+        asUrl,
+        serverConfig.oauth?.authServerMetadataUrl,
+      )
+
+      if (!metadata) {
+        logMCPDebug(serverName, 'No OAuth metadata found')
+      } else {
+        const revocationEndpoint =
+          'revocation_endpoint' in metadata
+            ? metadata.revocation_endpoint
+            : null
+        if (!revocationEndpoint) {
+          logMCPDebug(serverName, 'Server does not support token revocation')
+        } else {
+          const revocationEndpointStr = String(revocationEndpoint)
+          // RFC 7009 defines revocation_endpoint_auth_methods_supported
+          // separately from the token endpoint's list; prefer it if present.
+          const authMethods =
+            ('revocation_endpoint_auth_methods_supported' in metadata
+              ? metadata.revocation_endpoint_auth_methods_supported
+              : undefined) ??
+            ('token_endpoint_auth_methods_supported' in metadata
+              ? metadata.token_endpoint_auth_methods_supported
+              : undefined)
+          const authMethod: 'client_secret_basic' | 'client_secret_post' =
+            authMethods &&
+            !authMethods.includes('client_secret_basic') &&
+            authMethods.includes('client_secret_post')
+              ? 'client_secret_post'
+              : 'client_secret_basic'
+          logMCPDebug(
+            serverName,
+            `Revoking tokens via ${revocationEndpointStr} (${authMethod})`,
+          )
+
+          // Revoke refresh token first (more important - prevents future access token generation)
+          if (tokenData.refreshToken) {
+            try {
+              await revokeToken({
+                serverName,
+                endpoint: revocationEndpointStr,
+                token: tokenData.refreshToken,
+                tokenTypeHint: 'refresh_token',
+                clientId: tokenData.clientId,
+                clientSecret: tokenData.clientSecret,
+                accessToken: tokenData.accessToken,
+                authMethod,
+              })
+            } catch (error: unknown) {
+              // Log but continue
+              logMCPDebug(
+                serverName,
+                `Failed to revoke refresh token: ${errorMessage(error)}`,
+              )
+            }
+          }
+
+          // Then revoke access token (may already be invalidated by refresh token revocation)
+          if (tokenData.accessToken) {
+            try {
+              await revokeToken({
+                serverName,
+                endpoint: revocationEndpointStr,
+                token: tokenData.accessToken,
+                tokenTypeHint: 'access_token',
+                clientId: tokenData.clientId,
+                clientSecret: tokenData.clientSecret,
+                accessToken: tokenData.accessToken,
+                authMethod,
+              })
+            } catch (error: unknown) {
+              logMCPDebug(
+                serverName,
+                `Failed to revoke access token: ${errorMessage(error)}`,
+              )
+            }
+          }
+        }
+      }
+    } catch (error: unknown) {
+      // Log error but don't throw - revocation is best-effort
+      logMCPDebug(serverName, `Failed to revoke tokens: ${errorMessage(error)}`)
+    }
+  } else {
+    logMCPDebug(serverName, 'No tokens to revoke')
+  }
+
+  // Always clear local tokens, regardless of server-side revocation result.
+  clearServerTokensFromLocalStorage(serverName, serverConfig)
+
+  // When re-authenticating, preserve step-up auth state (scope + discovery)
+  // so the next performMCPOAuthFlow can use cached scope instead of
+  // re-probing. For "Clear Auth" (default), wipe everything.
+  if (
+    preserveStepUpState &&
+    tokenData &&
+    (tokenData.stepUpScope || tokenData.discoveryState)
+  ) {
+    const freshData = storage.read() || {}
+    const updatedData: SecureStorageData = {
+      ...freshData,
+      mcpOAuth: {
+        ...freshData.mcpOAuth,
+        [serverKey]: {
+          ...freshData.mcpOAuth?.[serverKey],
+          serverName,
+          serverUrl: serverConfig.url,
+          accessToken: freshData.mcpOAuth?.[serverKey]?.accessToken ?? '',
+          expiresAt: freshData.mcpOAuth?.[serverKey]?.expiresAt ?? 0,
+          ...(tokenData.stepUpScope
+            ? { stepUpScope: tokenData.stepUpScope }
+            : {}),
+          ...(tokenData.discoveryState
+            ? {
+                // Strip legacy bulky metadata fields here too so users with
+                // existing overflowed blobs recover on next re-auth (#30337).
+                discoveryState: {
+                  authorizationServerUrl:
+                    tokenData.discoveryState.authorizationServerUrl,
+                  resourceMetadataUrl:
+                    tokenData.discoveryState.resourceMetadataUrl,
+                },
+              }
+            : {}),
+        },
+      },
+    }
+    storage.update(updatedData)
+    logMCPDebug(serverName, 'Preserved step-up auth state across revocation')
+  }
+}
+
+export function clearServerTokensFromLocalStorage(
+  serverName: string,
+  serverConfig: McpSSEServerConfig | McpHTTPServerConfig,
+): void {
+  const storage = getSecureStorage()
+  const existingData = storage.read()
+  if (!existingData?.mcpOAuth) return
+
+  const serverKey = getServerKey(serverName, serverConfig)
+  if (existingData.mcpOAuth[serverKey]) {
+    delete existingData.mcpOAuth[serverKey]
+    storage.update(existingData)
+    logMCPDebug(serverName, 'Cleared stored tokens')
+  }
+}
+
+type WWWAuthenticateParams = {
+  scope?: string
+  resourceMetadataUrl?: URL
+}
+
+type XaaFailureStage =
+  | 'idp_login'
+  | 'discovery'
+  | 'token_exchange'
+  | 'jwt_bearer'
+
+/**
+ * XAA (Cross-App Access) auth.
+ *
+ * One IdP browser login is reused across all XAA-configured MCP servers:
+ * 1. Acquire an id_token from the IdP (cached in keychain by issuer; if
+ *    missing/expired, runs a standard OIDC authorization_code+PKCE flow
+ *    — this is the one browser pop)
+ * 2. Run the RFC 8693 + RFC 7523 exchange (no browser)
+ * 3. Save tokens to the same keychain slot as normal OAuth
+ *
+ * IdP connection details come from settings.xaaIdp (configured once via
+ * `claude mcp xaa setup`). Per-server config is just `oauth.xaa: true`
+ * plus the AS clientId/clientSecret.
+ *
+ * No silent fallback: if `oauth.xaa` is set, XAA is the only path.
+ * All errors are actionable — they tell the user what to run.
+ */
+async function performMCPXaaAuth(
+  serverName: string,
+  serverConfig: McpSSEServerConfig | McpHTTPServerConfig,
+  onAuthorizationUrl: (url: string) => void,
+  abortSignal?: AbortSignal,
+  skipBrowserOpen?: boolean,
+): Promise<void> {
+  if (!serverConfig.oauth?.xaa) {
+    throw new Error('XAA: oauth.xaa must be set') // guarded by caller
+  }
+
+  // IdP config comes from user-level settings, not per-server.
+  const idp = getXaaIdpSettings()
+  if (!idp) {
+    throw new Error(
+      "XAA: no IdP connection configured. Run 'claude mcp xaa setup --issuer <url> --client-id <id> --client-secret' to configure.",
+    )
+  }
+
+  const clientId = serverConfig.oauth?.clientId
+  if (!clientId) {
+    throw new Error(
+      `XAA: server '${serverName}' needs an AS client_id. Re-add with --client-id.`,
+    )
+  }
+
+  const clientConfig = getMcpClientConfig(serverName, serverConfig)
+  const clientSecret = clientConfig?.clientSecret
+  if (!clientSecret) {
+    // Diagnostic context for serverKey mismatch debugging. Only computed
+    // on the error path so there's no perf cost on success.
+    const wantedKey = getServerKey(serverName, serverConfig)
+    const haveKeys = Object.keys(
+      getSecureStorage().read()?.mcpOAuthClientConfig ?? {},
+    )
+    const headersForLogging = Object.fromEntries(
+      Object.entries(serverConfig.headers ?? {}).map(([k, v]) =>
+        k.toLowerCase() === 'authorization' ? [k, '[REDACTED]'] : [k, v],
+      ),
+    )
+    logMCPDebug(
+      serverName,
+      `XAA: secret lookup miss. wanted=${wantedKey} have=[${haveKeys.join(', ')}] configHeaders=${jsonStringify(headersForLogging)}`,
+    )
+    throw new Error(
+      `XAA: AS client secret not found for '${serverName}'. Re-add with --client-secret.`,
+    )
+  }
+
+  logMCPDebug(serverName, 'XAA: starting cross-app access flow')
+
+  // IdP client secret lives in a separate keychain slot (keyed by IdP issuer),
+  // NOT the AS secret — different trust domain. Optional: if absent, PKCE-only.
+  const idpClientSecret = getIdpClientSecret(idp.issuer)
+
+  // Acquire id_token (cached or via one OIDC browser pop at the IdP).
+  // Peek the cache first so we can report idTokenCacheHit in analytics before
+  // acquireIdpIdToken potentially writes a fresh one.
+  const idTokenCacheHit = getCachedIdpIdToken(idp.issuer) !== undefined
+
+  let failureStage: XaaFailureStage = 'idp_login'
+  try {
+    let idToken
+    try {
+      idToken = await acquireIdpIdToken({
+        idpIssuer: idp.issuer,
+        idpClientId: idp.clientId,
+        idpClientSecret,
+        callbackPort: idp.callbackPort,
+        onAuthorizationUrl,
+        skipBrowserOpen,
+        abortSignal,
+      })
+    } catch (e) {
+      if (abortSignal?.aborted) throw new AuthenticationCancelledError()
+      throw e
+    }
+
+    // Discover the IdP's token endpoint for the RFC 8693 exchange.
+    failureStage = 'discovery'
+    const oidc = await discoverOidc(idp.issuer)
+
+    // Run the exchange. performCrossAppAccess throws XaaTokenExchangeError
+    // for the IdP leg and "jwt-bearer grant failed" for the AS leg.
+    failureStage = 'token_exchange'
+    let tokens
+    try {
+      tokens = await performCrossAppAccess(
+        serverConfig.url,
+        {
+          clientId,
+          clientSecret,
+          idpClientId: idp.clientId,
+          idpClientSecret,
+          idpIdToken: idToken,
+          idpTokenEndpoint: oidc.token_endpoint,
+        },
+        serverName,
+        abortSignal,
+      )
+    } catch (e) {
+      if (abortSignal?.aborted) throw new AuthenticationCancelledError()
+      const msg = errorMessage(e)
+      // If the IdP says the id_token is bad, drop it from the cache so the
+      // next attempt does a fresh IdP login. XaaTokenExchangeError carries
+      // shouldClearIdToken so we key off OAuth semantics (4xx / invalid body
+      // → clear; 5xx IdP outage → preserve) rather than substring matching.
+      if (e instanceof XaaTokenExchangeError) {
+        if (e.shouldClearIdToken) {
+          clearIdpIdToken(idp.issuer)
+          logMCPDebug(
+            serverName,
+            'XAA: cleared cached id_token after token-exchange failure',
+          )
+        }
+      } else if (
+        msg.includes('PRM discovery failed') ||
+        msg.includes('AS metadata discovery failed') ||
+        msg.includes('no authorization server supports jwt-bearer')
+      ) {
+        // performCrossAppAccess runs PRM + AS discovery before the actual
+        // exchange — don't attribute their failures to 'token_exchange'.
+        failureStage = 'discovery'
+      } else if (msg.includes('jwt-bearer')) {
+        failureStage = 'jwt_bearer'
+      }
+      throw e
+    }
+
+    // Save tokens via the same storage path as normal OAuth. We write directly
+    // (instead of ClaudeAuthProvider.saveTokens) to avoid instantiating the
+    // whole provider just to write the same keys.
+    const storage = getSecureStorage()
+    const existingData = storage.read() || {}
+    const serverKey = getServerKey(serverName, serverConfig)
+    const prev = existingData.mcpOAuth?.[serverKey]
+    storage.update({
+      ...existingData,
+      mcpOAuth: {
+        ...existingData.mcpOAuth,
+        [serverKey]: {
+          ...prev,
+          serverName,
+          serverUrl: serverConfig.url,
+          accessToken: tokens.access_token,
+          // AS may omit refresh_token on jwt-bearer — preserve any existing one
+          refreshToken: tokens.refresh_token ?? prev?.refreshToken,
+          expiresAt: Date.now() + (tokens.expires_in || 3600) * 1000,
+          scope: tokens.scope,
+          clientId,
+          clientSecret,
+          // Persist the AS URL so _doRefresh and revokeServerTokens can locate
+          // the token/revocation endpoints when MCP URL ≠ AS URL (the common
+          // XAA topology).
+          discoveryState: {
+            authorizationServerUrl: tokens.authorizationServerUrl,
+          },
+        },
+      },
+    })
+
+    logMCPDebug(serverName, 'XAA: tokens saved')
+    logEvent('tengu_mcp_oauth_flow_success', {
+      authMethod:
+        'xaa' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      idTokenCacheHit,
+    })
+  } catch (e) {
+    // User-initiated cancel (Esc during IdP browser pop) isn't a failure.
+    if (e instanceof AuthenticationCancelledError) {
+      throw e
+    }
+    logEvent('tengu_mcp_oauth_flow_failure', {
+      authMethod:
+        'xaa' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      xaaFailureStage:
+        failureStage as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      idTokenCacheHit,
+    })
+    throw e
+  }
+}
+
+export async function performMCPOAuthFlow(
+  serverName: string,
+  serverConfig: McpSSEServerConfig | McpHTTPServerConfig,
+  onAuthorizationUrl: (url: string) => void,
+  abortSignal?: AbortSignal,
+  options?: {
+    skipBrowserOpen?: boolean
+    onWaitingForCallback?: (submit: (callbackUrl: string) => void) => void
+  },
+): Promise<void> {
+  // XAA (SEP-990): if configured, bypass the per-server consent dance.
+  // If the IdP id_token isn't cached, this pops the browser once at the IdP
+  // (shared across all XAA servers for that issuer). Subsequent servers hit
+  // the cache and are silent. Tokens land in the same keychain slot, so the
+  // rest of CC's transport wiring (ClaudeAuthProvider.tokens() in client.ts)
+  // works unchanged.
+  //
+  // No silent fallback: if `oauth.xaa` is set, XAA is the only path. We
+  // never fall through to the consent flow — that would be surprising (the
+  // user explicitly asked for XAA) and security-relevant (consent flow may
+  // have a different trust/scope posture than the org's IdP policy).
+  //
+  // Servers with `oauth.xaa` but CLAUDE_CODE_ENABLE_XAA unset hard-fail with
+  // actionable copy rather than silently degrade to consent.
+  if (serverConfig.oauth?.xaa) {
+    if (!isXaaEnabled()) {
+      throw new Error(
+        `XAA is not enabled (set CLAUDE_CODE_ENABLE_XAA=1). Remove 'oauth.xaa' from server '${serverName}' to use the standard consent flow.`,
+      )
+    }
+    logEvent('tengu_mcp_oauth_flow_start', {
+      isOAuthFlow: true,
+      authMethod:
+        'xaa' as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      transportType:
+        serverConfig.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      ...(getLoggingSafeMcpBaseUrl(serverConfig)
+        ? {
+            mcpServerBaseUrl: getLoggingSafeMcpBaseUrl(
+              serverConfig,
+            ) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+          }
+        : {}),
+    })
+    // performMCPXaaAuth logs its own success/failure events (with
+    // idTokenCacheHit + xaaFailureStage).
+    await performMCPXaaAuth(
+      serverName,
+      serverConfig,
+      onAuthorizationUrl,
+      abortSignal,
+      options?.skipBrowserOpen,
+    )
+    return
+  }
+
+  // Check for cached step-up scope and resource metadata URL before clearing
+  // tokens. The transport-attached auth provider persists scope when it receives
+  // a step-up 401, so we can use it here instead of making an extra probe request.
+  const storage = getSecureStorage()
+  const serverKey = getServerKey(serverName, serverConfig)
+  const cachedEntry = storage.read()?.mcpOAuth?.[serverKey]
+  const cachedStepUpScope = cachedEntry?.stepUpScope
+  const cachedResourceMetadataUrl =
+    cachedEntry?.discoveryState?.resourceMetadataUrl
+
+  // Clear any existing stored credentials to ensure fresh client registration.
+  // Note: this deletes the entire entry (including discoveryState/stepUpScope),
+  // but we already read the cached values above.
+  clearServerTokensFromLocalStorage(serverName, serverConfig)
+
+  // Use cached step-up scope and resource metadata URL if available.
+  // The transport-attached auth provider caches these when it receives a
+  // step-up 401, so we don't need to probe the server again.
+  let resourceMetadataUrl: URL | undefined
+  if (cachedResourceMetadataUrl) {
+    try {
+      resourceMetadataUrl = new URL(cachedResourceMetadataUrl)
+    } catch {
+      logMCPDebug(
+        serverName,
+        `Invalid cached resourceMetadataUrl: ${cachedResourceMetadataUrl}`,
+      )
+    }
+  }
+  const wwwAuthParams: WWWAuthenticateParams = {
+    scope: cachedStepUpScope,
+    resourceMetadataUrl,
+  }
+
+  const flowAttemptId = randomUUID()
+
+  logEvent('tengu_mcp_oauth_flow_start', {
+    flowAttemptId:
+      flowAttemptId as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+    isOAuthFlow: true,
+    transportType:
+      serverConfig.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+    ...(getLoggingSafeMcpBaseUrl(serverConfig)
+      ? {
+          mcpServerBaseUrl: getLoggingSafeMcpBaseUrl(
+            serverConfig,
+          ) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        }
+      : {}),
+  })
+
+  // Track whether we reached the token-exchange phase so the catch block can
+  // attribute the failure reason correctly.
+  let authorizationCodeObtained = false
+
+  try {
+    // Use configured callback port for pre-configured OAuth, otherwise find an available port
+    const configuredCallbackPort = serverConfig.oauth?.callbackPort
+    const port = configuredCallbackPort ?? (await findAvailablePort())
+    const redirectUri = buildRedirectUri(port)
+    logMCPDebug(
+      serverName,
+      `Using redirect port: ${port}${configuredCallbackPort ? ' (from config)' : ''}`,
+    )
+
+    const provider = new ClaudeAuthProvider(
+      serverName,
+      serverConfig,
+      redirectUri,
+      true,
+      onAuthorizationUrl,
+      options?.skipBrowserOpen,
+    )
+
+    // Fetch and store OAuth metadata for scope information
+    try {
+      const metadata = await fetchAuthServerMetadata(
+        serverName,
+        serverConfig.url,
+        serverConfig.oauth?.authServerMetadataUrl,
+        undefined,
+        wwwAuthParams.resourceMetadataUrl,
+      )
+      if (metadata) {
+        // Store metadata in provider for scope information
+        provider.setMetadata(metadata)
+        logMCPDebug(
+          serverName,
+          `Fetched OAuth metadata with scope: ${getScopeFromMetadata(metadata) || 'NONE'}`,
+        )
+      }
+    } catch (error) {
+      logMCPDebug(
+        serverName,
+        `Failed to fetch OAuth metadata: ${errorMessage(error)}`,
+      )
+    }
+
+    // Get the OAuth state from the provider for validation
+    const oauthState = await provider.state()
+
+    // Store the server, timeout, and abort listener references for cleanup
+    let server: Server | null = null
+    let timeoutId: NodeJS.Timeout | null = null
+    let abortHandler: (() => void) | null = null
+
+    const cleanup = () => {
+      if (server) {
+        server.removeAllListeners()
+        // Defensive: removeAllListeners() strips the error handler, so swallow any late error during close
+        server.on('error', () => {})
+        server.close()
+        server = null
+      }
+      if (timeoutId) {
+        clearTimeout(timeoutId)
+        timeoutId = null
+      }
+      if (abortSignal && abortHandler) {
+        abortSignal.removeEventListener('abort', abortHandler)
+        abortHandler = null
+      }
+      logMCPDebug(serverName, `MCP OAuth server cleaned up`)
+    }
+
+    // Setup a server to receive the callback
+    const authorizationCode = await new Promise<string>((resolve, reject) => {
+      let resolved = false
+      const resolveOnce = (code: string) => {
+        if (resolved) return
+        resolved = true
+        resolve(code)
+      }
+      const rejectOnce = (error: Error) => {
+        if (resolved) return
+        resolved = true
+        reject(error)
+      }
+
+      if (abortSignal) {
+        abortHandler = () => {
+          cleanup()
+          rejectOnce(new AuthenticationCancelledError())
+        }
+        if (abortSignal.aborted) {
+          abortHandler()
+          return
+        }
+        abortSignal.addEventListener('abort', abortHandler)
+      }
+
+      // Allow manual callback URL paste for remote/browser-based environments
+      // where localhost is not reachable from the user's browser.
+      if (options?.onWaitingForCallback) {
+        options.onWaitingForCallback((callbackUrl: string) => {
+          try {
+            const parsed = new URL(callbackUrl)
+            const code = parsed.searchParams.get('code')
+            const state = parsed.searchParams.get('state')
+            const error = parsed.searchParams.get('error')
+
+            if (error) {
+              const errorDescription =
+                parsed.searchParams.get('error_description') || ''
+              cleanup()
+              rejectOnce(
+                new Error(`OAuth error: ${error} - ${errorDescription}`),
+              )
+              return
+            }
+
+            if (!code) {
+              // Not a valid callback URL, ignore so the user can try again
+              return
+            }
+
+            if (state !== oauthState) {
+              cleanup()
+              rejectOnce(
+                new Error('OAuth state mismatch - possible CSRF attack'),
+              )
+              return
+            }
+
+            logMCPDebug(
+              serverName,
+              `Received auth code via manual callback URL`,
+            )
+            cleanup()
+            resolveOnce(code)
+          } catch {
+            // Invalid URL, ignore so the user can try again
+          }
+        })
+      }
+
+      server = createServer((req, res) => {
+        const parsedUrl = parse(req.url || '', true)
+
+        if (parsedUrl.pathname === '/callback') {
+          const code = parsedUrl.query.code as string
+          const state = parsedUrl.query.state as string
+          const error = parsedUrl.query.error
+          const errorDescription = parsedUrl.query.error_description as string
+          const errorUri = parsedUrl.query.error_uri as string
+
+          // Validate OAuth state to prevent CSRF attacks
+          if (!error && state !== oauthState) {
+            res.writeHead(400, { 'Content-Type': 'text/html' })
+            res.end(
+              `<h1>Authentication Error</h1><p>Invalid state parameter. Please try again.</p><p>You can close this window.</p>`,
+            )
+            cleanup()
+            rejectOnce(new Error('OAuth state mismatch - possible CSRF attack'))
+            return
+          }
+
+          if (error) {
+            res.writeHead(200, { 'Content-Type': 'text/html' })
+            // Sanitize error messages to prevent XSS
+            const sanitizedError = xss(String(error))
+            const sanitizedErrorDescription = errorDescription
+              ? xss(String(errorDescription))
+              : ''
+            res.end(
+              `<h1>Authentication Error</h1><p>${sanitizedError}: ${sanitizedErrorDescription}</p><p>You can close this window.</p>`,
+            )
+            cleanup()
+            let errorMessage = `OAuth error: ${error}`
+            if (errorDescription) {
+              errorMessage += ` - ${errorDescription}`
+            }
+            if (errorUri) {
+              errorMessage += ` (See: ${errorUri})`
+            }
+            rejectOnce(new Error(errorMessage))
+            return
+          }
+
+          if (code) {
+            res.writeHead(200, { 'Content-Type': 'text/html' })
+            res.end(
+              `<h1>Authentication Successful</h1><p>You can close this window. Return to Claude Code.</p>`,
+            )
+            cleanup()
+            resolveOnce(code)
+          }
+        }
+      })
+
+      server.on('error', (err: NodeJS.ErrnoException) => {
+        cleanup()
+        if (err.code === 'EADDRINUSE') {
+          const findCmd =
+            getPlatform() === 'windows'
+              ? `netstat -ano | findstr :${port}`
+              : `lsof -ti:${port} -sTCP:LISTEN`
+          rejectOnce(
+            new Error(
+              `OAuth callback port ${port} is already in use — another process may be holding it. ` +
+                `Run \`${findCmd}\` to find it.`,
+            ),
+          )
+        } else {
+          rejectOnce(new Error(`OAuth callback server failed: ${err.message}`))
+        }
+      })
+
+      server.listen(port, '127.0.0.1', async () => {
+        try {
+          logMCPDebug(serverName, `Starting SDK auth`)
+          logMCPDebug(serverName, `Server URL: ${serverConfig.url}`)
+
+          // First call to start the auth flow - should redirect
+          // Pass the scope and resource_metadata from WWW-Authenticate header if available
+          const result = await sdkAuth(provider, {
+            serverUrl: serverConfig.url,
+            scope: wwwAuthParams.scope,
+            resourceMetadataUrl: wwwAuthParams.resourceMetadataUrl,
+          })
+          logMCPDebug(serverName, `Initial auth result: ${result}`)
+
+          if (result !== 'REDIRECT') {
+            logMCPDebug(
+              serverName,
+              `Unexpected auth result, expected REDIRECT: ${result}`,
+            )
+          }
+        } catch (error) {
+          logMCPDebug(serverName, `SDK auth error: ${error}`)
+          cleanup()
+          rejectOnce(new Error(`SDK auth failed: ${errorMessage(error)}`))
+        }
+      })
+
+      // Don't let the callback server or timeout pin the event loop — if the UI
+      // component unmounts without aborting (e.g. parent intercepts Esc), we'd
+      // rather let the process exit than stay alive for 5 minutes holding the
+      // port. The abortSignal is the intended lifecycle management.
+      server.unref()
+
+      timeoutId = setTimeout(
+        (cleanup, rejectOnce) => {
+          cleanup()
+          rejectOnce(new Error('Authentication timeout'))
+        },
+        5 * 60 * 1000, // 5 minutes
+        cleanup,
+        rejectOnce,
+      )
+      timeoutId.unref()
+    })
+
+    authorizationCodeObtained = true
+
+    // Now complete the auth flow with the received code
+    logMCPDebug(serverName, `Completing auth flow with authorization code`)
+    const result = await sdkAuth(provider, {
+      serverUrl: serverConfig.url,
+      authorizationCode,
+      resourceMetadataUrl: wwwAuthParams.resourceMetadataUrl,
+    })
+
+    logMCPDebug(serverName, `Auth result: ${result}`)
+
+    if (result === 'AUTHORIZED') {
+      // Debug: Check if tokens were properly saved
+      const savedTokens = await provider.tokens()
+      logMCPDebug(
+        serverName,
+        `Tokens after auth: ${savedTokens ? 'Present' : 'Missing'}`,
+      )
+      if (savedTokens) {
+        logMCPDebug(
+          serverName,
+          `Token access_token length: ${savedTokens.access_token?.length}`,
+        )
+        logMCPDebug(serverName, `Token expires_in: ${savedTokens.expires_in}`)
+      }
+
+      logEvent('tengu_mcp_oauth_flow_success', {
+        flowAttemptId:
+          flowAttemptId as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        transportType:
+          serverConfig.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+        ...(getLoggingSafeMcpBaseUrl(serverConfig)
+          ? {
+              mcpServerBaseUrl: getLoggingSafeMcpBaseUrl(
+                serverConfig,
+              ) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+            }
+          : {}),
+      })
+    } else {
+      throw new Error('Unexpected auth result: ' + result)
+    }
+  } catch (error) {
+    logMCPDebug(serverName, `Error during auth completion: ${error}`)
+
+    // Determine failure reason for attribution telemetry. The try block covers
+    // port acquisition, the callback server, the redirect flow, and token
+    // exchange. Map known failure paths to stable reason codes.
+    let reason: MCPOAuthFlowErrorReason = 'unknown'
+    let oauthErrorCode: string | undefined
+    let httpStatus: number | undefined
+
+    if (error instanceof AuthenticationCancelledError) {
+      reason = 'cancelled'
+    } else if (authorizationCodeObtained) {
+      reason = 'token_exchange_failed'
+    } else {
+      const msg = errorMessage(error)
+      if (msg.includes('Authentication timeout')) {
+        reason = 'timeout'
+      } else if (msg.includes('OAuth state mismatch')) {
+        reason = 'state_mismatch'
+      } else if (msg.includes('OAuth error:')) {
+        reason = 'provider_denied'
+      } else if (
+        msg.includes('already in use') ||
+        msg.includes('EADDRINUSE') ||
+        msg.includes('callback server failed') ||
+        msg.includes('No available port')
+      ) {
+        reason = 'port_unavailable'
+      } else if (msg.includes('SDK auth failed')) {
+        reason = 'sdk_auth_failed'
+      }
+    }
+
+    // sdkAuth uses native fetch and throws OAuthError subclasses (InvalidGrantError,
+    // ServerError, InvalidClientError, etc.) via parseErrorResponse. Extract the
+    // OAuth error code directly from the SDK error instance.
+    if (error instanceof OAuthError) {
+      oauthErrorCode = error.errorCode
+      // SDK does not attach HTTP status as a property, but the fallback ServerError
+      // embeds it in the message as "HTTP {status}:" when the response body was
+      // unparseable. Best-effort extraction.
+      const statusMatch = error.message.match(/^HTTP (\d{3}):/)
+      if (statusMatch) {
+        httpStatus = Number(statusMatch[1])
+      }
+      // If client not found, clear the stored client ID and suggest retry
+      if (
+        error.errorCode === 'invalid_client' &&
+        error.message.includes('Client not found')
+      ) {
+        const storage = getSecureStorage()
+        const existingData = storage.read() || {}
+        const serverKey = getServerKey(serverName, serverConfig)
+        if (existingData.mcpOAuth?.[serverKey]) {
+          delete existingData.mcpOAuth[serverKey].clientId
+          delete existingData.mcpOAuth[serverKey].clientSecret
+          storage.update(existingData)
+        }
+      }
+    }
+
+    logEvent('tengu_mcp_oauth_flow_error', {
+      flowAttemptId:
+        flowAttemptId as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      reason:
+        reason as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      error_code:
+        oauthErrorCode as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      http_status:
+        httpStatus?.toString() as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      transportType:
+        serverConfig.type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+      ...(getLoggingSafeMcpBaseUrl(serverConfig)
+        ? {
+            mcpServerBaseUrl: getLoggingSafeMcpBaseUrl(
+              serverConfig,
+            ) as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+          }
+        : {}),
+    })
+    throw error
+  }
+}
+
+/**
+ * Wraps fetch to detect 403 insufficient_scope responses and mark step-up
+ * pending on the provider BEFORE the SDK's 403 handler calls auth(). Without
+ * this, the SDK's authInternal sees refresh_token → refreshes (uselessly, since
+ * RFC 6749 §6 forbids scope elevation via refresh) → returns 'AUTHORIZED' →
+ * retry → 403 again → aborts with "Server returned 403 after trying upscoping",
+ * never reaching redirectToAuthorization where step-up scope is persisted.
+ * With this flag set, tokens() omits refresh_token so the SDK falls through
+ * to the PKCE flow. See github.com/anthropics/claude-code/issues/28258.
+ */
+export function wrapFetchWithStepUpDetection(
+  baseFetch: FetchLike,
+  provider: ClaudeAuthProvider,
+): FetchLike {
+  return async (url, init) => {
+    const response = await baseFetch(url, init)
+    if (response.status === 403) {
+      const wwwAuth = response.headers.get('WWW-Authenticate')
+      if (wwwAuth?.includes('insufficient_scope')) {
+        // Match both quoted and unquoted values (RFC 6750 §3 allows either).
+        // Same pattern as the SDK's extractFieldFromWwwAuth.
+        const match = wwwAuth.match(/scope=(?:"([^"]+)"|([^\s,]+))/)
+        const scope = match?.[1] ?? match?.[2]
+        if (scope) {
+          provider.markStepUpPending(scope)
+        }
+      }
+    }
+    return response
+  }
+}
+
+export class ClaudeAuthProvider implements OAuthClientProvider {
+  private serverName: string
+  private serverConfig: McpSSEServerConfig | McpHTTPServerConfig
+  private redirectUri: string
+  private handleRedirection: boolean
+  private _codeVerifier?: string
+  private _authorizationUrl?: string
+  private _state?: string
+  private _scopes?: string
+  private _metadata?: Awaited<
+    ReturnType<typeof discoverAuthorizationServerMetadata>
+  >
+  private _refreshInProgress?: Promise<OAuthTokens | undefined>
+  private _pendingStepUpScope?: string
+  private onAuthorizationUrlCallback?: (url: string) => void
+  private skipBrowserOpen: boolean
+
+  constructor(
+    serverName: string,
+    serverConfig: McpSSEServerConfig | McpHTTPServerConfig,
+    redirectUri: string = buildRedirectUri(),
+    handleRedirection = false,
+    onAuthorizationUrl?: (url: string) => void,
+    skipBrowserOpen?: boolean,
+  ) {
+    this.serverName = serverName
+    this.serverConfig = serverConfig
+    this.redirectUri = redirectUri
+    this.handleRedirection = handleRedirection
+    this.onAuthorizationUrlCallback = onAuthorizationUrl
+    this.skipBrowserOpen = skipBrowserOpen ?? false
+  }
+
+  get redirectUrl(): string {
+    return this.redirectUri
+  }
+
+  get authorizationUrl(): string | undefined {
+    return this._authorizationUrl
+  }
+
+  get clientMetadata(): OAuthClientMetadata {
+    const metadata: OAuthClientMetadata = {
+      client_name: `Claude Code (${this.serverName})`,
+      redirect_uris: [this.redirectUri],
+      grant_types: ['authorization_code', 'refresh_token'],
+      response_types: ['code'],
+      token_endpoint_auth_method: 'none', // Public client
+    }
+
+    // Include scope from metadata if available
+    const metadataScope = getScopeFromMetadata(this._metadata)
+    if (metadataScope) {
+      metadata.scope = metadataScope
+      logMCPDebug(
+        this.serverName,
+        `Using scope from metadata: ${metadata.scope}`,
+      )
+    }
+
+    return metadata
+  }
+
+  /**
+   * CIMD (SEP-991): URL-based client_id. When the auth server advertises
+   * client_id_metadata_document_supported: true, the SDK uses this URL as the
+   * client_id instead of performing Dynamic Client Registration.
+   * Override via MCP_OAUTH_CLIENT_METADATA_URL env var (e.g. for testing, FedStart).
+   */
+  get clientMetadataUrl(): string | undefined {
+    const override = process.env.MCP_OAUTH_CLIENT_METADATA_URL
+    if (override) {
+      logMCPDebug(this.serverName, `Using CIMD URL from env: ${override}`)
+      return override
+    }
+    return MCP_CLIENT_METADATA_URL
+  }
+
+  setMetadata(
+    metadata: Awaited<ReturnType<typeof discoverAuthorizationServerMetadata>>,
+  ): void {
+    this._metadata = metadata
+  }
+
+  /**
+   * Called by the fetch wrapper when a 403 insufficient_scope response is
+   * detected. Setting this causes tokens() to omit refresh_token, forcing
+   * the SDK's authInternal to skip its (useless) refresh path and fall through
+   * to startAuthorization → redirectToAuthorization → step-up persistence.
+   * RFC 6749 §6 forbids scope elevation via refresh, so refreshing would just
+   * return the same-scoped token and the retry would 403 again.
+   */
+  markStepUpPending(scope: string): void {
+    this._pendingStepUpScope = scope
+    logMCPDebug(this.serverName, `Marked step-up pending: ${scope}`)
+  }
+
+  async state(): Promise<string> {
+    // Generate state if not already generated for this instance
+    if (!this._state) {
+      this._state = randomBytes(32).toString('base64url')
+      logMCPDebug(this.serverName, 'Generated new OAuth state')
+    }
+    return this._state
+  }
+
+  async clientInformation(): Promise<OAuthClientInformation | undefined> {
+    const storage = getSecureStorage()
+    const data = storage.read()
+    const serverKey = getServerKey(this.serverName, this.serverConfig)
+
+    // Check session credentials first (from DCR or previous auth)
+    const storedInfo = data?.mcpOAuth?.[serverKey]
+    if (storedInfo?.clientId) {
+      logMCPDebug(this.serverName, `Found client info`)
+      return {
+        client_id: storedInfo.clientId,
+        client_secret: storedInfo.clientSecret,
+      }
+    }
+
+    // Fallback: pre-configured client ID from server config
+    const configClientId = this.serverConfig.oauth?.clientId
+    if (configClientId) {
+      const clientConfig = data?.mcpOAuthClientConfig?.[serverKey]
+      logMCPDebug(this.serverName, `Using pre-configured client ID`)
+      return {
+        client_id: configClientId,
+        client_secret: clientConfig?.clientSecret,
+      }
+    }
+
+    // If we don't have stored client info, return undefined to trigger registration
+    logMCPDebug(this.serverName, `No client info found`)
+    return undefined
+  }
+
+  async saveClientInformation(
+    clientInformation: OAuthClientInformationFull,
+  ): Promise<void> {
+    const storage = getSecureStorage()
+    const existingData = storage.read() || {}
+    const serverKey = getServerKey(this.serverName, this.serverConfig)
+
+    const updatedData: SecureStorageData = {
+      ...existingData,
+      mcpOAuth: {
+        ...existingData.mcpOAuth,
+        [serverKey]: {
+          ...existingData.mcpOAuth?.[serverKey],
+          serverName: this.serverName,
+          serverUrl: this.serverConfig.url,
+          clientId: clientInformation.client_id,
+          clientSecret: clientInformation.client_secret,
+          // Provide default values for required fields if not present
+          accessToken: existingData.mcpOAuth?.[serverKey]?.accessToken || '',
+          expiresAt: existingData.mcpOAuth?.[serverKey]?.expiresAt || 0,
+        },
+      },
+    }
+
+    storage.update(updatedData)
+  }
+
+  async tokens(): Promise<OAuthTokens | undefined> {
+    // Cross-process token changes (another CC instance refreshed or invalidated)
+    // are picked up via the keychain cache TTL (see macOsKeychainStorage.ts).
+    // In-process writes already invalidate the cache via storage.update().
+    // We do NOT clearKeychainCache() here — tokens() is called by the MCP SDK's
+    // _commonHeaders on every request, and forcing a cache miss would trigger
+    // a blocking spawnSync(`security find-generic-password`) 30-40x/sec.
+    // See CPU profile: spawnSync was 7.2% of total CPU after PR #19436.
+    const storage = getSecureStorage()
+    const data = await storage.readAsync()
+    const serverKey = getServerKey(this.serverName, this.serverConfig)
+
+    const tokenData = data?.mcpOAuth?.[serverKey]
+
+    // XAA: a cached id_token plays the same UX role as a refresh_token — run
+    // the silent exchange to get a fresh access_token without a browser. The
+    // id_token does expire (we re-acquire via `xaa login` when it does); the
+    // point is that while it's valid, re-auth is zero-interaction.
+    //
+    // Only fire when we don't have a refresh_token. If the AS returned one,
+    // the normal refresh path (below) is cheaper — 1 request vs the 4-request
+    // XAA chain. If that refresh is revoked, refreshAuthorization() clears it
+    // (invalidateCredentials('tokens')), and the next tokens() falls through
+    // to here.
+    //
+    // Fires on:
+    //   - never authed (!tokenData)                 → first connect, auto-auth
+    //   - SDK partial write {accessToken:''}        → stale from past session
+    //   - expired/expiring, no refresh_token        → proactive XAA re-auth
+    //
+    // No special-casing of {accessToken:'', expiresAt:0}. Yes, SDK auth()
+    // writes that mid-flow (saveClientInformation defaults). But with this
+    // auto-auth branch, the *first* tokens() call — before auth() writes
+    // anything — fires xaaRefresh. If id_token is cached, SDK short-circuits
+    // there and never reaches the write. If id_token isn't cached, xaaRefresh
+    // returns undefined in ~1 keychain read, auth() proceeds, writes the
+    // marker, calls tokens() again, xaaRefresh fails again identically.
+    // Harmless redundancy, not a wasted exchange. And guarding on `!==''`
+    // permanently bricks auto-auth when a *prior* session left that marker
+    // in keychain — real bug seen with xaa.dev.
+    //
+    // xaaRefresh() internally short-circuits to undefined when the id_token
+    // isn't cached (or settings.xaaIdp is gone) → we fall through to the
+    // existing needs-auth path → user runs `xaa login`.
+    //
+    if (
+      isXaaEnabled() &&
+      this.serverConfig.oauth?.xaa &&
+      !tokenData?.refreshToken &&
+      (!tokenData?.accessToken ||
+        (tokenData.expiresAt - Date.now()) / 1000 <= 300)
+    ) {
+      if (!this._refreshInProgress) {
+        logMCPDebug(
+          this.serverName,
+          tokenData
+            ? `XAA: access_token expiring, attempting silent exchange`
+            : `XAA: no access_token yet, attempting silent exchange`,
+        )
+        this._refreshInProgress = this.xaaRefresh().finally(() => {
+          this._refreshInProgress = undefined
+        })
+      }
+      try {
+        const refreshed = await this._refreshInProgress
+        if (refreshed) return refreshed
+      } catch (e) {
+        logMCPDebug(
+          this.serverName,
+          `XAA silent exchange failed: ${errorMessage(e)}`,
+        )
+      }
+      // Fall through. Either id_token isn't cached (xaaRefresh returned
+      // undefined) or the exchange errored. Normal path below handles both:
+      // !tokenData → undefined → 401 → needs-auth; expired → undefined → same.
+    }
+
+    if (!tokenData) {
+      logMCPDebug(this.serverName, `No token data found`)
+      return undefined
+    }
+
+    // Check if token is expired
+    const expiresIn = (tokenData.expiresAt - Date.now()) / 1000
+
+    // Step-up check: if a 403 insufficient_scope was detected and the current
+    // token doesn't have the requested scope, omit refresh_token below so the
+    // SDK skips refresh and falls through to the PKCE flow.
+    const currentScopes = tokenData.scope?.split(' ') ?? []
+    const needsStepUp =
+      this._pendingStepUpScope !== undefined &&
+      this._pendingStepUpScope.split(' ').some(s => !currentScopes.includes(s))
+    if (needsStepUp) {
+      logMCPDebug(
+        this.serverName,
+        `Step-up pending (${this._pendingStepUpScope}), omitting refresh_token`,
+      )
+    }
+
+    // If token is expired and we don't have a refresh token, return undefined
+    if (expiresIn <= 0 && !tokenData.refreshToken) {
+      logMCPDebug(this.serverName, `Token expired without refresh token`)
+      return undefined
+    }
+
+    // If token is expired or about to expire (within 5 minutes) and we have a refresh token, refresh it proactively.
+    // This proactive refresh is a UX improvement - it avoids the latency of a failed request followed by token refresh.
+    // While MCP servers should return 401 for expired tokens (which triggers SDK-level refresh), proactively refreshing
+    // before expiry provides a smoother user experience.
+    // Skip when step-up is pending — refreshing can't elevate scope (RFC 6749 §6).
+    if (expiresIn <= 300 && tokenData.refreshToken && !needsStepUp) {
+      // Reuse existing refresh promise if one is in progress to prevent concurrent refreshes
+      if (!this._refreshInProgress) {
+        logMCPDebug(
+          this.serverName,
+          `Token expires in ${Math.floor(expiresIn)}s, attempting proactive refresh`,
+        )
+        this._refreshInProgress = this.refreshAuthorization(
+          tokenData.refreshToken,
+        ).finally(() => {
+          this._refreshInProgress = undefined
+        })
+      } else {
+        logMCPDebug(
+          this.serverName,
+          `Token refresh already in progress, reusing existing promise`,
+        )
+      }
+
+      try {
+        const refreshed = await this._refreshInProgress
+        if (refreshed) {
+          logMCPDebug(this.serverName, `Token refreshed successfully`)
+          return refreshed
+        }
+        logMCPDebug(
+          this.serverName,
+          `Token refresh failed, returning current tokens`,
+        )
+      } catch (error) {
+        logMCPDebug(
+          this.serverName,
+          `Token refresh error: ${errorMessage(error)}`,
+        )
+      }
+    }
+
+    // Return current tokens (may be expired if refresh failed or not needed yet)
+    const tokens = {
+      access_token: tokenData.accessToken,
+      refresh_token: needsStepUp ? undefined : tokenData.refreshToken,
+      expires_in: expiresIn,
+      scope: tokenData.scope,
+      token_type: 'Bearer',
+    }
+
+    logMCPDebug(this.serverName, `Returning tokens`)
+    logMCPDebug(this.serverName, `Token length: ${tokens.access_token?.length}`)
+    logMCPDebug(this.serverName, `Has refresh token: ${!!tokens.refresh_token}`)
+    logMCPDebug(this.serverName, `Expires in: ${Math.floor(expiresIn)}s`)
+
+    return tokens
+  }
+
+  async saveTokens(tokens: OAuthTokens): Promise<void> {
+    this._pendingStepUpScope = undefined
+    const storage = getSecureStorage()
+    const existingData = storage.read() || {}
+    const serverKey = getServerKey(this.serverName, this.serverConfig)
+
+    logMCPDebug(this.serverName, `Saving tokens`)
+    logMCPDebug(this.serverName, `Token expires in: ${tokens.expires_in}`)
+    logMCPDebug(this.serverName, `Has refresh token: ${!!tokens.refresh_token}`)
+
+    const updatedData: SecureStorageData = {
+      ...existingData,
+      mcpOAuth: {
+        ...existingData.mcpOAuth,
+        [serverKey]: {
+          ...existingData.mcpOAuth?.[serverKey],
+          serverName: this.serverName,
+          serverUrl: this.serverConfig.url,
+          accessToken: tokens.access_token,
+          refreshToken: tokens.refresh_token,
+          expiresAt: Date.now() + (tokens.expires_in || 3600) * 1000,
+          scope: tokens.scope,
+        },
+      },
+    }
+
+    storage.update(updatedData)
+  }
+
+  /**
+   * XAA silent refresh: cached id_token → Layer-2 exchange → new access_token.
+   * No browser.
+   *
+   * Returns undefined if the id_token is gone from cache — caller treats this
+   * as needs-interactive-reauth (transport will 401, CC surfaces it).
+   *
+   * On exchange failure, clears the id_token cache so the next interactive
+   * auth does a fresh IdP login (the cached id_token is likely stale/revoked).
+   *
+   * TODO(xaa-ga): add cross-process lockfile before GA. `_refreshInProgress`
+   * only dedupes within one process — two CC instances with expiring tokens
+   * both fire the full 4-request XAA chain and race on storage.update().
+   * Unlike inc-4829 the id_token is not single-use so both access_tokens
+   * stay valid (wasted round-trips + keychain write race, not brickage),
+   * but this is the shape CLAUDE.md flags under "Token/auth caching across
+   * process boundaries". Mirror refreshAuthorization()'s lockfile pattern.
+   */
+  private async xaaRefresh(): Promise<OAuthTokens | undefined> {
+    const idp = getXaaIdpSettings()
+    if (!idp) return undefined // config was removed mid-session
+
+    const idToken = getCachedIdpIdToken(idp.issuer)
+    if (!idToken) {
+      logMCPDebug(
+        this.serverName,
+        'XAA: id_token not cached, needs interactive re-auth',
+      )
+      return undefined
+    }
+
+    const clientId = this.serverConfig.oauth?.clientId
+    const clientConfig = getMcpClientConfig(this.serverName, this.serverConfig)
+    if (!clientId || !clientConfig?.clientSecret) {
+      logMCPDebug(
+        this.serverName,
+        'XAA: missing clientId or clientSecret in config — skipping silent refresh',
+      )
+      return undefined // shouldn't happen if `mcp add` was correct
+    }
+
+    const idpClientSecret = getIdpClientSecret(idp.issuer)
+
+    // Discover IdP token endpoint. Could cache (fetchCache.ts already
+    // caches /.well-known/ requests), but OIDC metadata is cheap + idempotent.
+    // xaaRefresh is the silent tokens() path — soft-fail to undefined so the
+    // caller falls through to needs-authentication instead of throwing mid-connect.
+    let oidc
+    try {
+      oidc = await discoverOidc(idp.issuer)
+    } catch (e) {
+      logMCPDebug(
+        this.serverName,
+        `XAA: OIDC discovery failed in silent refresh: ${errorMessage(e)}`,
+      )
+      return undefined
+    }
+
+    try {
+      const tokens = await performCrossAppAccess(
+        this.serverConfig.url,
+        {
+          clientId,
+          clientSecret: clientConfig.clientSecret,
+          idpClientId: idp.clientId,
+          idpClientSecret,
+          idpIdToken: idToken,
+          idpTokenEndpoint: oidc.token_endpoint,
+        },
+        this.serverName,
+      )
+      // Write directly (not via saveTokens) so clientId + clientSecret land in
+      // storage even when this is the first write for serverKey. saveTokens
+      // only spreads existing data; if no prior performMCPXaaAuth ran,
+      // revokeServerTokens would later read tokenData.clientId as undefined
+      // and send a client_id-less RFC 7009 request that strict ASes reject.
+      const storage = getSecureStorage()
+      const existingData = storage.read() || {}
+      const serverKey = getServerKey(this.serverName, this.serverConfig)
+      const prev = existingData.mcpOAuth?.[serverKey]
+      storage.update({
+        ...existingData,
+        mcpOAuth: {
+          ...existingData.mcpOAuth,
+          [serverKey]: {
+            ...prev,
+            serverName: this.serverName,
+            serverUrl: this.serverConfig.url,
+            accessToken: tokens.access_token,
+            refreshToken: tokens.refresh_token ?? prev?.refreshToken,
+            expiresAt: Date.now() + (tokens.expires_in || 3600) * 1000,
+            scope: tokens.scope,
+            clientId,
+            clientSecret: clientConfig.clientSecret,
+            discoveryState: {
+              authorizationServerUrl: tokens.authorizationServerUrl,
+            },
+          },
+        },
+      })
+      return {
+        access_token: tokens.access_token,
+        token_type: 'Bearer',
+        expires_in: tokens.expires_in,
+        scope: tokens.scope,
+        refresh_token: tokens.refresh_token,
+      }
+    } catch (e) {
+      if (e instanceof XaaTokenExchangeError && e.shouldClearIdToken) {
+        clearIdpIdToken(idp.issuer)
+        logMCPDebug(
+          this.serverName,
+          'XAA: cleared id_token after exchange failure',
+        )
+      }
+      throw e
+    }
+  }
+
+  async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
+    // Store the authorization URL
+    this._authorizationUrl = authorizationUrl.toString()
+
+    // Extract and store scopes from the authorization URL for later use in token exchange
+    const scopes = authorizationUrl.searchParams.get('scope')
+    logMCPDebug(
+      this.serverName,
+      `Authorization URL: ${redactSensitiveUrlParams(authorizationUrl.toString())}`,
+    )
+    logMCPDebug(this.serverName, `Scopes in URL: ${scopes || 'NOT FOUND'}`)
+
+    if (scopes) {
+      this._scopes = scopes
+      logMCPDebug(
+        this.serverName,
+        `Captured scopes from authorization URL: ${scopes}`,
+      )
+    } else {
+      // If no scope in URL, try to get it from metadata
+      const metadataScope = getScopeFromMetadata(this._metadata)
+      if (metadataScope) {
+        this._scopes = metadataScope
+        logMCPDebug(
+          this.serverName,
+          `Using scopes from metadata: ${metadataScope}`,
+        )
+      } else {
+        logMCPDebug(this.serverName, `No scopes available from URL or metadata`)
+      }
+    }
+
+    // Persist scope for step-up auth: only when the transport-attached provider
+    // (handleRedirection=false) receives a step-up 401. The SDK calls auth()
+    // which calls redirectToAuthorization with the new scope. We persist it
+    // so the next performMCPOAuthFlow can use it without an extra probe request.
+    // Guard with !handleRedirection to avoid persisting during normal auth flows
+    // (where the scope may come from metadata scopes_supported rather than a 401).
+    if (this._scopes && !this.handleRedirection) {
+      const storage = getSecureStorage()
+      const existingData = storage.read() || {}
+      const serverKey = getServerKey(this.serverName, this.serverConfig)
+      const existing = existingData.mcpOAuth?.[serverKey]
+      if (existing) {
+        existing.stepUpScope = this._scopes
+        storage.update(existingData)
+        logMCPDebug(this.serverName, `Persisted step-up scope: ${this._scopes}`)
+      }
+    }
+
+    if (!this.handleRedirection) {
+      logMCPDebug(
+        this.serverName,
+        `Redirection handling is disabled, skipping redirect`,
+      )
+      return
+    }
+
+    // Validate URL scheme for security
+    const urlString = authorizationUrl.toString()
+    if (!urlString.startsWith('http://') && !urlString.startsWith('https://')) {
+      throw new Error(
+        'Invalid authorization URL: must use http:// or https:// scheme',
+      )
+    }
+
+    logMCPDebug(this.serverName, `Redirecting to authorization URL`)
+    const redactedUrl = redactSensitiveUrlParams(urlString)
+    logMCPDebug(this.serverName, `Authorization URL: ${redactedUrl}`)
+
+    // Notify the UI about the authorization URL BEFORE opening the browser,
+    // so users can see the URL as a fallback if the browser fails to open
+    if (this.onAuthorizationUrlCallback) {
+      this.onAuthorizationUrlCallback(urlString)
+    }
+
+    if (!this.skipBrowserOpen) {
+      logMCPDebug(this.serverName, `Opening authorization URL: ${redactedUrl}`)
+
+      const success = await openBrowser(urlString)
+      if (!success) {
+        logMCPDebug(
+          this.serverName,
+          `Browser didn't open automatically. URL is shown in UI.`,
+        )
+      }
+    } else {
+      logMCPDebug(
+        this.serverName,
+        `Skipping browser open (skipBrowserOpen=true). URL: ${redactedUrl}`,
+      )
+    }
+  }
+
+  async saveCodeVerifier(codeVerifier: string): Promise<void> {
+    logMCPDebug(this.serverName, `Saving code verifier`)
+    this._codeVerifier = codeVerifier
+  }
+
+  async codeVerifier(): Promise<string> {
+    if (!this._codeVerifier) {
+      logMCPDebug(this.serverName, `No code verifier saved`)
+      throw new Error('No code verifier saved')
+    }
+    logMCPDebug(this.serverName, `Returning code verifier`)
+    return this._codeVerifier
+  }
+
+  async invalidateCredentials(
+    scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery',
+  ): Promise<void> {
+    const storage = getSecureStorage()
+    const existingData = storage.read()
+    if (!existingData?.mcpOAuth) return
+
+    const serverKey = getServerKey(this.serverName, this.serverConfig)
+    const tokenData = existingData.mcpOAuth[serverKey]
+    if (!tokenData) return
+
+    switch (scope) {
+      case 'all':
+        delete existingData.mcpOAuth[serverKey]
+        break
+      case 'client':
+        tokenData.clientId = undefined
+        tokenData.clientSecret = undefined
+        break
+      case 'tokens':
+        tokenData.accessToken = ''
+        tokenData.refreshToken = undefined
+        tokenData.expiresAt = 0
+        break
+      case 'verifier':
+        this._codeVerifier = undefined
+        return
+      case 'discovery':
+        tokenData.discoveryState = undefined
+        tokenData.stepUpScope = undefined
+        break
+    }
+
+    storage.update(existingData)
+    logMCPDebug(this.serverName, `Invalidated credentials (scope: ${scope})`)
+  }
+
+  async saveDiscoveryState(state: OAuthDiscoveryState): Promise<void> {
+    const storage = getSecureStorage()
+    const existingData = storage.read() || {}
+    const serverKey = getServerKey(this.serverName, this.serverConfig)
+
+    logMCPDebug(
+      this.serverName,
+      `Saving discovery state (authServer: ${state.authorizationServerUrl})`,
+    )
+
+    // Persist only the URLs, NOT the full metadata blobs.
+    // authorizationServerMetadata alone is ~1.5-2KB per MCP server (every
+    // grant type, PKCE method, endpoint the IdP supports). On macOS the
+    // keychain write goes through `security -i` which has a 4096-byte stdin
+    // line limit — with hex encoding that's ~2013 bytes of JSON total. Two
+    // OAuth MCP servers persisting full metadata overflows it, corrupting
+    // the credential store (#30337). The SDK re-fetches missing metadata
+    // with one HTTP GET on the next auth — see node_modules/.../auth.js
+    // `cachedState.authorizationServerMetadata ?? await discover...`.
+    const updatedData: SecureStorageData = {
+      ...existingData,
+      mcpOAuth: {
+        ...existingData.mcpOAuth,
+        [serverKey]: {
+          ...existingData.mcpOAuth?.[serverKey],
+          serverName: this.serverName,
+          serverUrl: this.serverConfig.url,
+          accessToken: existingData.mcpOAuth?.[serverKey]?.accessToken || '',
+          expiresAt: existingData.mcpOAuth?.[serverKey]?.expiresAt || 0,
+          discoveryState: {
+            authorizationServerUrl: state.authorizationServerUrl,
+            resourceMetadataUrl: state.resourceMetadataUrl,
+          },
+        },
+      },
+    }
+
+    storage.update(updatedData)
+  }
+
+  async discoveryState(): Promise<OAuthDiscoveryState | undefined> {
+    const storage = getSecureStorage()
+    const data = storage.read()
+    const serverKey = getServerKey(this.serverName, this.serverConfig)
+
+    const cached = data?.mcpOAuth?.[serverKey]?.discoveryState
+    if (cached?.authorizationServerUrl) {
+      logMCPDebug(
+        this.serverName,
+        `Returning cached discovery state (authServer: ${cached.authorizationServerUrl})`,
+      )
+
+      return {
+        authorizationServerUrl: cached.authorizationServerUrl,
+        resourceMetadataUrl: cached.resourceMetadataUrl,
+        resourceMetadata:
+          cached.resourceMetadata as OAuthDiscoveryState['resourceMetadata'],
+        authorizationServerMetadata:
+          cached.authorizationServerMetadata as OAuthDiscoveryState['authorizationServerMetadata'],
+      }
+    }
+
+    // Check config hint for direct metadata URL
+    const metadataUrl = this.serverConfig.oauth?.authServerMetadataUrl
+    if (metadataUrl) {
+      logMCPDebug(
+        this.serverName,
+        `Fetching metadata from configured URL: ${metadataUrl}`,
+      )
+      try {
+        const metadata = await fetchAuthServerMetadata(
+          this.serverName,
+          this.serverConfig.url,
+          metadataUrl,
+        )
+        if (metadata) {
+          return {
+            authorizationServerUrl: metadata.issuer,
+            authorizationServerMetadata:
+              metadata as OAuthDiscoveryState['authorizationServerMetadata'],
+          }
+        }
+      } catch (error) {
+        logMCPDebug(
+          this.serverName,
+          `Failed to fetch from configured metadata URL: ${errorMessage(error)}`,
+        )
+      }
+    }
+
+    return undefined
+  }
+
+  async refreshAuthorization(
+    refreshToken: string,
+  ): Promise<OAuthTokens | undefined> {
+    const serverKey = getServerKey(this.serverName, this.serverConfig)
+    const claudeDir = getClaudeConfigHomeDir()
+    await mkdir(claudeDir, { recursive: true })
+    const sanitizedKey = serverKey.replace(/[^a-zA-Z0-9]/g, '_')
+    const lockfilePath = join(claudeDir, `mcp-refresh-${sanitizedKey}.lock`)
+
+    let release: (() => Promise<void>) | undefined
+    for (let retry = 0; retry < MAX_LOCK_RETRIES; retry++) {
+      try {
+        logMCPDebug(
+          this.serverName,
+          `Acquiring refresh lock (attempt ${retry + 1})`,
+        )
+        release = await lockfile.lock(lockfilePath, {
+          realpath: false,
+          onCompromised: () => {
+            logMCPDebug(this.serverName, `Refresh lock was compromised`)
+          },
+        })
+        logMCPDebug(this.serverName, `Acquired refresh lock`)
+        break
+      } catch (e: unknown) {
+        const code = getErrnoCode(e)
+        if (code === 'ELOCKED') {
+          logMCPDebug(
+            this.serverName,
+            `Refresh lock held by another process, waiting (attempt ${retry + 1}/${MAX_LOCK_RETRIES})`,
+          )
+          await sleep(1000 + Math.random() * 1000)
+          continue
+        }
+        logMCPDebug(
+          this.serverName,
+          `Failed to acquire refresh lock: ${code}, proceeding without lock`,
+        )
+        break
+      }
+    }
+    if (!release) {
+      logMCPDebug(
+        this.serverName,
+        `Could not acquire refresh lock after ${MAX_LOCK_RETRIES} retries, proceeding without lock`,
+      )
+    }
+
+    try {
+      // Re-read tokens after acquiring lock — another process may have refreshed
+      clearKeychainCache()
+      const storage = getSecureStorage()
+      const data = storage.read()
+      const tokenData = data?.mcpOAuth?.[serverKey]
+      if (tokenData) {
+        const expiresIn = (tokenData.expiresAt - Date.now()) / 1000
+        if (expiresIn > 300) {
+          logMCPDebug(
+            this.serverName,
+            `Another process already refreshed tokens (expires in ${Math.floor(expiresIn)}s)`,
+          )
+          return {
+            access_token: tokenData.accessToken,
+            refresh_token: tokenData.refreshToken,
+            expires_in: expiresIn,
+            scope: tokenData.scope,
+            token_type: 'Bearer',
+          }
+        }
+        // Use the freshest refresh token from storage
+        if (tokenData.refreshToken) {
+          refreshToken = tokenData.refreshToken
+        }
+      }
+      return await this._doRefresh(refreshToken)
+    } finally {
+      if (release) {
+        try {
+          await release()
+          logMCPDebug(this.serverName, `Released refresh lock`)
+        } catch {
+          logMCPDebug(this.serverName, `Failed to release refresh lock`)
+        }
+      }
+    }
+  }
+
+  private async _doRefresh(
+    refreshToken: string,
+  ): Promise<OAuthTokens | undefined> {
+    const MAX_ATTEMPTS = 3
+
+    const mcpServerBaseUrl = getLoggingSafeMcpBaseUrl(this.serverConfig)
+    const emitRefreshEvent = (
+      outcome: 'success' | 'failure',
+      reason?: MCPRefreshFailureReason,
+    ): void => {
+      logEvent(
+        outcome === 'success'
+          ? 'tengu_mcp_oauth_refresh_success'
+          : 'tengu_mcp_oauth_refresh_failure',
+        {
+          transportType: this.serverConfig
+            .type as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+          ...(mcpServerBaseUrl
+            ? {
+                mcpServerBaseUrl:
+                  mcpServerBaseUrl as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+              }
+            : {}),
+          ...(reason
+            ? {
+                reason:
+                  reason as AnalyticsMetadata_I_VERIFIED_THIS_IS_NOT_CODE_OR_FILEPATHS,
+              }
+            : {}),
+        },
+      )
+    }
+
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+      try {
+        logMCPDebug(this.serverName, `Starting token refresh`)
+        const authFetch = createAuthFetch()
+
+        // Reuse cached metadata from the initial OAuth flow if available,
+        // since metadata (token endpoint URL, etc.) is static per auth server.
+        // Priority:
+        // 1. In-memory cache (same-session refreshes)
+        // 2. Persisted discovery state from initial auth (cross-session) —
+        //    avoids re-running RFC 9728 discovery on every refresh.
+        // 3. Full RFC 9728 → RFC 8414 re-discovery via fetchAuthServerMetadata.
+        let metadata = this._metadata
+        if (!metadata) {
+          const cached = await this.discoveryState()
+          if (cached?.authorizationServerMetadata) {
+            logMCPDebug(
+              this.serverName,
+              `Using persisted auth server metadata for refresh`,
+            )
+            metadata = cached.authorizationServerMetadata
+          } else if (cached?.authorizationServerUrl) {
+            logMCPDebug(
+              this.serverName,
+              `Re-discovering metadata from persisted auth server URL: ${cached.authorizationServerUrl}`,
+            )
+            metadata = await discoverAuthorizationServerMetadata(
+              cached.authorizationServerUrl,
+              { fetchFn: authFetch },
+            )
+          }
+        }
+        if (!metadata) {
+          metadata = await fetchAuthServerMetadata(
+            this.serverName,
+            this.serverConfig.url,
+            this.serverConfig.oauth?.authServerMetadataUrl,
+            authFetch,
+          )
+        }
+        if (!metadata) {
+          logMCPDebug(this.serverName, `Failed to discover OAuth metadata`)
+          emitRefreshEvent('failure', 'metadata_discovery_failed')
+          return undefined
+        }
+        // Cache for future refreshes
+        this._metadata = metadata
+
+        const clientInfo = await this.clientInformation()
+        if (!clientInfo) {
+          logMCPDebug(this.serverName, `No client information available`)
+          emitRefreshEvent('failure', 'no_client_info')
+          return undefined
+        }
+
+        const newTokens = await sdkRefreshAuthorization(
+          new URL(this.serverConfig.url),
+          {
+            metadata,
+            clientInformation: clientInfo,
+            refreshToken,
+            resource: new URL(this.serverConfig.url),
+            fetchFn: authFetch,
+          },
+        )
+
+        if (newTokens) {
+          logMCPDebug(this.serverName, `Token refresh successful`)
+          await this.saveTokens(newTokens)
+          emitRefreshEvent('success')
+          return newTokens
+        }
+
+        logMCPDebug(this.serverName, `Token refresh returned no tokens`)
+        emitRefreshEvent('failure', 'no_tokens_returned')
+        return undefined
+      } catch (error) {
+        // Invalid grant means the refresh token itself is invalid/revoked/expired.
+        // But another process may have already refreshed successfully — check first.
+        if (error instanceof InvalidGrantError) {
+          logMCPDebug(
+            this.serverName,
+            `Token refresh failed with invalid_grant: ${error.message}`,
+          )
+          clearKeychainCache()
+          const storage = getSecureStorage()
+          const data = storage.read()
+          const serverKey = getServerKey(this.serverName, this.serverConfig)
+          const tokenData = data?.mcpOAuth?.[serverKey]
+          if (tokenData) {
+            const expiresIn = (tokenData.expiresAt - Date.now()) / 1000
+            if (expiresIn > 300) {
+              logMCPDebug(
+                this.serverName,
+                `Another process refreshed tokens, using those`,
+              )
+              // Not emitted as success: this process did not perform a
+              // refresh, and the winning process already emitted its own
+              // success event. Emitting here would double-count.
+              return {
+                access_token: tokenData.accessToken,
+                refresh_token: tokenData.refreshToken,
+                expires_in: expiresIn,
+                scope: tokenData.scope,
+                token_type: 'Bearer',
+              }
+            }
+          }
+          logMCPDebug(
+            this.serverName,
+            `No valid tokens in storage, clearing stored tokens`,
+          )
+          await this.invalidateCredentials('tokens')
+          emitRefreshEvent('failure', 'invalid_grant')
+          return undefined
+        }
+
+        // Retry on timeouts or transient server errors
+        const isTimeoutError =
+          error instanceof Error &&
+          /timeout|timed out|etimedout|econnreset/i.test(error.message)
+        const isTransientServerError =
+          error instanceof ServerError ||
+          error instanceof TemporarilyUnavailableError ||
+          error instanceof TooManyRequestsError
+        const isRetryable = isTimeoutError || isTransientServerError
+
+        if (!isRetryable || attempt >= MAX_ATTEMPTS) {
+          logMCPDebug(
+            this.serverName,
+            `Token refresh failed: ${errorMessage(error)}`,
+          )
+          emitRefreshEvent(
+            'failure',
+            isRetryable ? 'transient_retries_exhausted' : 'request_failed',
+          )
+          return undefined
+        }
+
+        const delayMs = 1000 * Math.pow(2, attempt - 1) // 1s, 2s, 4s
+        logMCPDebug(
+          this.serverName,
+          `Token refresh failed, retrying in ${delayMs}ms (attempt ${attempt}/${MAX_ATTEMPTS})`,
+        )
+        await sleep(delayMs)
+      }
+    }
+
+    return undefined
+  }
+}
+
+export async function readClientSecret(): Promise<string> {
+  const envSecret = process.env.MCP_CLIENT_SECRET
+  if (envSecret) {
+    return envSecret
+  }
+
+  if (!process.stdin.isTTY) {
+    throw new Error(
+      'No TTY available to prompt for client secret. Set MCP_CLIENT_SECRET env var instead.',
+    )
+  }
+
+  return new Promise((resolve, reject) => {
+    process.stderr.write('Enter OAuth client secret: ')
+    process.stdin.setRawMode?.(true)
+    let secret = ''
+    const onData = (ch: Buffer) => {
+      const c = ch.toString()
+      if (c === '\n' || c === '\r') {
+        process.stdin.setRawMode?.(false)
+        process.stdin.removeListener('data', onData)
+        process.stderr.write('\n')
+        resolve(secret)
+      } else if (c === '\u0003') {
+        process.stdin.setRawMode?.(false)
+        process.stdin.removeListener('data', onData)
+        reject(new Error('Cancelled'))
+      } else if (c === '\u007F' || c === '\b') {
+        secret = secret.slice(0, -1)
+      } else {
+        secret += c
+      }
+    }
+    process.stdin.on('data', onData)
+  })
+}
+
+export function saveMcpClientSecret(
+  serverName: string,
+  serverConfig: McpSSEServerConfig | McpHTTPServerConfig,
+  clientSecret: string,
+): void {
+  const storage = getSecureStorage()
+  const existingData = storage.read() || {}
+  const serverKey = getServerKey(serverName, serverConfig)
+  storage.update({
+    ...existingData,
+    mcpOAuthClientConfig: {
+      ...existingData.mcpOAuthClientConfig,
+      [serverKey]: { clientSecret },
+    },
+  })
+}
+
+export function clearMcpClientConfig(
+  serverName: string,
+  serverConfig: McpSSEServerConfig | McpHTTPServerConfig,
+): void {
+  const storage = getSecureStorage()
+  const existingData = storage.read()
+  if (!existingData?.mcpOAuthClientConfig) return
+  const serverKey = getServerKey(serverName, serverConfig)
+  if (existingData.mcpOAuthClientConfig[serverKey]) {
+    delete existingData.mcpOAuthClientConfig[serverKey]
+    storage.update(existingData)
+  }
+}
+
+export function getMcpClientConfig(
+  serverName: string,
+  serverConfig: McpSSEServerConfig | McpHTTPServerConfig,
+): { clientSecret?: string } | undefined {
+  const storage = getSecureStorage()
+  const data = storage.read()
+  const serverKey = getServerKey(serverName, serverConfig)
+  return data?.mcpOAuthClientConfig?.[serverKey]
+}
+
+/**
+ * Safely extracts scope information from AuthorizationServerMetadata.
+ * The metadata can be either OAuthMetadata or OpenIdProviderDiscoveryMetadata,
+ * and different providers use different fields for scope information.
+ */
+function getScopeFromMetadata(
+  metadata: AuthorizationServerMetadata | undefined,
+): string | undefined {
+  if (!metadata) return undefined
+  // Try 'scope' first (non-standard but used by some providers)
+  if ('scope' in metadata && typeof metadata.scope === 'string') {
+    return metadata.scope
+  }
+  // Try 'default_scope' (non-standard but used by some providers)
+  if (
+    'default_scope' in metadata &&
+    typeof metadata.default_scope === 'string'
+  ) {
+    return metadata.default_scope
+  }
+  // Fall back to scopes_supported (standard OAuth 2.0 field)
+  if (metadata.scopes_supported && Array.isArray(metadata.scopes_supported)) {
+    return metadata.scopes_supported.join(' ')
+  }
+  return undefined
+}