OAuth 2.0 Authentication

import { createHash, randomBytes } from 'crypto'

function base64URLEncode(buffer: Buffer): string {
  return buffer
    .toString('base64')
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g,  '')   // RFC 4648 §5 — URL-safe, no padding
}

export function generateCodeVerifier(): string {
  return base64URLEncode(randomBytes(32))  // 256-bit entropy
}

export function generateCodeChallenge(verifier: string): string {
  const hash = createHash('sha256')
  hash.update(verifier)
  return base64URLEncode(hash.digest())  // S256 method
}

export function generateState(): string {
  return base64URLEncode(randomBytes(32))  // CSRF protection
}
crypto.ts

async startOAuthFlow(
  authURLHandler: (url: string, automaticUrl?: string) => Promise<void>,
  options?: { skipBrowserOpen?: boolean; inferenceOnly?: boolean; ... }
): Promise<OAuthTokens> {
  // 1. Start the localhost callback server
  this.authCodeListener = new AuthCodeListener()
  this.port = await this.authCodeListener.start()

  // 2. Build both URLs from same PKCE values
  const manualFlowUrl    = client.buildAuthUrl({ ...opts, isManual: true })
  const automaticFlowUrl = client.buildAuthUrl({ ...opts, isManual: false })

  // 3. Race: automatic (localhost) vs manual (paste)
  const authorizationCode = await this.waitForAuthorizationCode(state, async () => {
    if (options?.skipBrowserOpen) {
      await authURLHandler(manualFlowUrl, automaticFlowUrl)  // SDK mode
    } else {
      await authURLHandler(manualFlowUrl)   // Show manual to user
      await openBrowser(automaticFlowUrl)  // Try automatic
    }
  })

  // 4. Which flow won?
  const isAutomatic = this.authCodeListener?.hasPendingResponse() ?? false

  // 5. Exchange code for tokens
  const tokenResponse = await client.exchangeCodeForTokens(
    authorizationCode, state, this.codeVerifier, this.port!,
    !isAutomatic  // isManual = true if auto did NOT win
  )

  // 6. Fetch subscription/rate-limit tier from profile API
  const profileInfo = await client.fetchProfileInfo(tokenResponse.access_token)

  // 7. Redirect browser to success page, then cleanup
  if (isAutomatic) this.authCodeListener?.handleSuccessRedirect(scopes)
  return this.formatTokens(tokenResponse, profileInfo.subscriptionType, ...)
}
services/oauth/index.ts

Port assignment

Listening on port 0 lets the OS pick a free port. This avoids the "port already in use" class of errors entirely. The chosen port is embedded in the redirect_uri that the auth server uses for its callback.

State validation

When the callback arrives, validateAndRespond() checks that state === expectedState before resolving. A mismatch returns HTTP 400 and rejects the promise — protecting against CSRF.

Pending response pattern

The server stores the browser's ServerResponse object in pendingResponse before resolving the auth code promise. After the token exchange succeeds, handleSuccessRedirect() completes the browser request with a 302 to the success page. This keeps the browser tab from hanging.

Cleanup on close

If close() is called while a response is still pending (e.g., token exchange failed), the server automatically calls handleErrorRedirect() first, ensuring the browser always gets a response.

private validateAndRespond(
  authCode: string | undefined,
  state:    string | undefined,
  res:      ServerResponse,
): void {
  if (!authCode) {
    res.writeHead(400)
    res.end('Authorization code not found')
    this.reject(new Error('No authorization code received'))
    return
  }
  if (state !== this.expectedState) {
    res.writeHead(400)
    res.end('Invalid state parameter')
    this.reject(new Error('Invalid state parameter'))
    return
  }
  // Store response for later redirect — keeps browser from hanging
  this.pendingResponse = res
  this.resolve(authCode)
}
auth-code-listener.ts

const requestBody = {
  grant_type:    'authorization_code',
  code:           authorizationCode,
  redirect_uri:   useManualRedirect
    ? getOauthConfig().MANUAL_REDIRECT_URL    // https://platform.claude.com/oauth/code/callback
    : `http://localhost:${port}/callback`,    // must match what was in auth URL
  client_id:      getOauthConfig().CLIENT_ID, // '9d1c250a-e61b-44d9-88ed-5944d1962f5e'
  code_verifier:  codeVerifier,               // proves we started this flow
  state,
}

// POST https://platform.claude.com/v1/oauth/token
const response = await axios.post(TOKEN_URL, requestBody, {
  headers: { 'Content-Type': 'application/json' },
  timeout: 15000,
})
client.ts

export async function fetchProfileInfo(accessToken: string) {
  const profile = await getOauthProfileFromOauthToken(accessToken)
  const orgType = profile?.organization?.organization_type

  let subscriptionType: SubscriptionType | null = null
  switch (orgType) {
    case 'claude_max':        subscriptionType = 'max';        break
    case 'claude_pro':        subscriptionType = 'pro';        break
    case 'claude_enterprise': subscriptionType = 'enterprise'; break
    case 'claude_team':       subscriptionType = 'team';       break
    default: subscriptionType = null
  }
  return {
    subscriptionType,
    rateLimitTier:       profile?.organization?.rate_limit_tier ?? null,
    hasExtraUsageEnabled: profile?.organization?.has_extra_usage_enabled ?? null,
    billingType:         profile?.organization?.billing_type ?? null,
    displayName:         profile?.account?.display_name,
    accountCreatedAt:    profile?.account?.created_at,
    subscriptionCreatedAt: profile?.organization?.subscription_created_at,
    rawProfile:          profile,
  }
}
client.ts

The macOS security command is invoked to store credentials. Two notable security engineering decisions:

• Hex encoding: The JSON token payload is converted to hexadecimal before storage (-X flag). This avoids shell quoting issues and — more importantly — prevents process monitors like CrowdStrike from seeing the raw token value in ps output or system call logs.
• stdin preference (security -i): When the payload fits within 4032 bytes (4096 - 64 headroom), it is passed via stdin instead of as a command-line argument. This prevents the token from appearing in process argument lists. If the payload exceeds the limit, argv fallback is used with a debug warning.
• Stale-while-error: If a security subprocess fails transiently, the last known good value is served from cache rather than surfacing a "Not logged in" error to the user.

export async function installOAuthTokens(tokens: OAuthTokens): Promise<void> {
  // 1. Wipe old state first (clear keychain, reset caches)
  await performLogout({ clearOnboarding: false })

  // 2. Store account info in global config (non-sensitive, JSON)
  const profile = tokens.profile ?? await getOauthProfileFromOauthToken(tokens.accessToken)
  if (profile) {
    storeOAuthAccountInfo({ accountUuid, emailAddress, organizationUuid, ... })
  }

  // 3. Save tokens to secure storage (keychain on macOS)
  const storageResult = saveOAuthTokensIfNeeded(tokens)
  clearOAuthTokenCache()

  // 4. Fetch roles (org/workspace role) — non-critical, failure tolerated
  await fetchAndStoreUserRoles(tokens.accessToken).catch(logForDebugging)

  // 5. Console path: create a permanent API key via the token
  if (!shouldUseClaudeAIAuth(tokens.scopes)) {
    await createAndStoreApiKey(tokens.accessToken)
  }
}
cli/handlers/auth.ts

export function isOAuthTokenExpired(expiresAt: number | null): boolean {
  if (expiresAt === null) return false

  const bufferTime = 5 * 60 * 1000  // 5 minutes early
  const expiresWithBuffer = Date.now() + bufferTime
  return expiresWithBuffer >= expiresAt
}
client.ts

export async function refreshOAuthToken(
  refreshToken: string,
  { scopes: requestedScopes }: { scopes?: string[] } = {},
): Promise<OAuthTokens> {
  const requestBody = {
    grant_type:    'refresh_token',
    refresh_token: refreshToken,
    client_id:     getOauthConfig().CLIENT_ID,
    // Backend allows scope expansion on refresh (ALLOWED_SCOPE_EXPANSIONS)
    scope: (requestedScopes?.length ? requestedScopes : CLAUDE_AI_OAUTH_SCOPES).join(' '),
  }

  // Skip profile fetch if we already have all fields cached
  const haveProfileAlready =
    config.oauthAccount?.billingType !== undefined &&
    config.oauthAccount?.accountCreatedAt !== undefined &&
    existing?.subscriptionType != null  // must check secure storage too

  const profileInfo = haveProfileAlready ? null : await fetchProfileInfo(accessToken)

  return {
    accessToken,
    refreshToken: newRefreshToken,   // server may rotate refresh token
    expiresAt:    Date.now() + expiresIn * 1000,
    scopes,
    subscriptionType: profileInfo?.subscriptionType ?? existing?.subscriptionType ?? null,
    rateLimitTier:    profileInfo?.rateLimitTier    ?? existing?.rateLimitTier    ?? null,
  }
}
client.ts

export async function performLogout({ clearOnboarding = false }): Promise<void> {
  // 1. Flush telemetry BEFORE clearing credentials
  //    Prevents sending org-attributed events after account is wiped
  const { flushTelemetry } = await import('../../utils/telemetry/instrumentation.js')
  await flushTelemetry()

  await removeApiKey()

  // 2. Wipe secure storage (tokens from keychain)
  const secureStorage = getSecureStorage()
  secureStorage.delete()

  // 3. Clear all auth-dependent in-memory caches
  await clearAuthRelatedCaches()

  // 4. Update global config
  saveGlobalConfig(current => ({
    ...current,
    oauthAccount: undefined,        // clear account info
    ...(clearOnboarding && {
      hasCompletedOnboarding: false,
      subscriptionNoticeCount: 0,
      hasAvailableSubscription: false,
    }),
  }))
}
commands/logout/logout.ts

export function buildAuthUrl({ codeChallenge, state, port, isManual,
  loginWithClaudeAi, inferenceOnly, orgUUID, loginHint, loginMethod }) {

  // Choose authorization server based on account type
  const authUrlBase = loginWithClaudeAi
    ? 'https://claude.com/cai/oauth/authorize'   // 307s to claude.ai
    : 'https://platform.claude.com/oauth/authorize'

  const authUrl = new URL(authUrlBase)
  authUrl.searchParams.append('code',              'true')  // show Claude Max upsell
  authUrl.searchParams.append('client_id',         CLIENT_ID)
  authUrl.searchParams.append('response_type',     'code')
  authUrl.searchParams.append('redirect_uri',      isManual
    ? 'https://platform.claude.com/oauth/code/callback'
    : `http://localhost:${port}/callback`)
  authUrl.searchParams.append('scope',             scopesToUse.join(' '))
  authUrl.searchParams.append('code_challenge',    codeChallenge)
  authUrl.searchParams.append('code_challenge_method', 'S256')
  authUrl.searchParams.append('state',             state)

  // Optional: pre-fill login form (standard OIDC)
  if (loginHint)   authUrl.searchParams.append('login_hint',   loginHint)
  // Optional: request specific login method
  if (loginMethod) authUrl.searchParams.append('login_method', loginMethod)
  // Optional: target specific org
  if (orgUUID)     authUrl.searchParams.append('orgUUID',      orgUUID)

  return authUrl.toString()
}
client.ts

const ALLOWED_OAUTH_BASE_URLS = [
  'https://beacon.claude-ai.staging.ant.dev',
  'https://claude.fedstart.com',
  'https://claude-staging.fedstart.com',
]

const oauthBaseUrl = process.env.CLAUDE_CODE_CUSTOM_OAUTH_URL
if (oauthBaseUrl) {
  const base = oauthBaseUrl.replace(/\/$/, '')
  if (!ALLOWED_OAUTH_BASE_URLS.includes(base)) {
    throw new Error('CLAUDE_CODE_CUSTOM_OAUTH_URL is not an approved endpoint.')
  }
  // Override all OAuth URLs to point to FedStart deployment
  config = { ...config, BASE_API_URL: base, CONSOLE_AUTHORIZE_URL: `${base}/oauth/authorize`, ... }
}
constants/oauth.ts