🎯 Use case
This file lives under “services/”, which covers long-lived services (LSP, MCP, OAuth, tool execution, memory, compaction, voice, settings sync, …). On the API surface it exposes normalizeOAuthErrorBody, AuthenticationCancelledError, getServerKey, hasMcpDiscoveryButNoToken, and revokeServerTokens (and more) — mainly functions, hooks, or classes. Dependencies touch @modelcontextprotocol, HTTP client, crypto, and Node filesystem. It composes internal code from constants, utils, analytics, oauthPort, and types (relative imports).
Generated from folder role, exports, dependency roots, and inline comments — not hand-reviewed for every path.
🧠 Inline summary
import { discoverAuthorizationServerMetadata, discoverOAuthServerInfo, type OAuthClientProvider, type OAuthDiscoveryState,
📤 Exports (heuristic)
normalizeOAuthErrorBodyAuthenticationCancelledErrorgetServerKeyhasMcpDiscoveryButNoTokenrevokeServerTokensclearServerTokensFromLocalStorageperformMCPOAuthFlowwrapFetchWithStepUpDetectionClaudeAuthProviderreadClientSecretsaveMcpClientSecretclearMcpClientConfiggetMcpClientConfig
📚 External import roots
Package roots from from "…" (relative paths omitted).
@modelcontextprotocolaxioscryptofshttppathurlxss
🖥️ Source preview
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
}