OAuth 认证

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

端口分配

监听端口 0 让操作系统选择一个空闲端口。 这完全避免了“端口已在使用”类别的错误。 所选端口嵌入在 redirect_uri 身份验证服务器用于其回调。

状态验证

当回调到来时， validateAndRespond() 检查 state === expectedState 解决之前。 不匹配会返回 HTTP 400 并拒绝承诺——防止 CSRF。

待处理响应模式

服务器存储浏览器的 ServerResponse 对象在 pendingResponse before 解决授权代码承诺。 代币兑换成功后， handleSuccessRedirect() 完成浏览器请求并返回 302 到成功页面。 这可以防止浏览器选项卡挂起。

关闭时清理

If close() 当响应仍在等待时被调用（例如，令牌交换失败），服务器自动调用 handleErrorRedirect() 首先，确保浏览器始终得到响应。

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

macOS security 调用命令来存储凭据。 两个值得注意的安全工程决策：

• 十六进制编码： JSON 令牌有效负载在存储之前转换为十六进制（-X 旗帜）。 这避免了 shell 引用问题，更重要的是，防止像 CrowdStrike 这样的进程监视器看到原始令牌值 ps 输出或系统调用日志。
• 标准输入首选项（security -i): 当有效负载在 4032 字节（4096 - 64 余量）内时，它会通过 stdin 传递，而不是作为命令行参数传递。 这可以防止令牌出现在进程参数列表中。 如果有效负载超过限制，则使用 argv 回退并发出调试警告。
• Stale-while-error: 如果一个 security 子进程暂时失败，最后一个已知的正确值是从缓存中提供的，而不是向用户显示“未登录”错误。

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