OAuth 2.0 인증

import { createHash, randomBytes } from 'crypto'

function base64URLEncode(buffer: Buffer): string {
  return buffer
    .toString('base64')
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=/g,  '')   // RFC 4648 §5, URL 안전 형식, 패딩 없음
}

export function generateCodeVerifier(): string {
  return base64URLEncode(randomBytes(32))  // 256비트 엔트로피
}

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

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

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

  // 2. 같은 PKCE 값으로 두 URL 구성
  const manualFlowUrl    = client.buildAuthUrl({ ...opts, isManual: true })
  const automaticFlowUrl = client.buildAuthUrl({ ...opts, isManual: false })

  // 3. 경쟁: 자동(localhost) 대 수동(붙여 넣기)
  const authorizationCode = await this.waitForAuthorizationCode(state, async () => {
    if (options?.skipBrowserOpen) {
      await authURLHandler(manualFlowUrl, automaticFlowUrl)  // SDK 모드
    } else {
      await authURLHandler(manualFlowUrl)   // 사용자에게 수동 URL 표시
      await openBrowser(automaticFlowUrl)  // 자동 흐름 시도
    }
  })

  // 4. 어느 흐름이 이겼는가?
  const isAutomatic = this.authCodeListener?.hasPendingResponse() ?? false

  // 5. 코드를 토큰으로 교환
  const tokenResponse = await client.exchangeCodeForTokens(
    authorizationCode, state, this.codeVerifier, this.port!,
    !isAutomatic  // auto가 이기지 못했다면 isManual = true
  )

  // 6. 프로필 API에서 구독 및 rate-limit tier 조회
  const profileInfo = await client.fetchProfileInfo(tokenResponse.access_token)

  // 7. 브라우저를 성공 페이지로 리다이렉트한 뒤 정리
  if (isAutomatic) this.authCodeListener?.handleSuccessRedirect(scopes)
  return this.formatTokens(tokenResponse, profileInfo.subscriptionType, ...)
}
services/oauth/index.ts

포트 할당

포트 0으로 listen하면 OS가 빈 포트를 골라 줍니다. 그래서 "port already in use" 류의 오류를 아예 피할 수 있습니다. 선택된 포트는 인증 서버가 callback에 사용하는 redirect_uri 안에 포함됩니다.

State 검증

callback이 도착하면 validateAndRespond()는 resolve하기 전에 state === expectedState인지 확인합니다. 값이 다르면 HTTP 400을 반환하고 promise를 reject해서 CSRF를 막습니다.

대기 응답 패턴

서버는 auth code promise를 resolve하기 전에 브라우저의 ServerResponse 객체를 pendingResponse에 저장합니다. 토큰 교환이 성공하면 handleSuccessRedirect()가 성공 페이지로의 302 응답으로 브라우저 요청을 마무리합니다. 덕분에 브라우저 탭이 멈춘 채 남지 않습니다.

닫기 시 정리

응답이 아직 대기 중인 상태에서 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
  }
  // 나중에 리다이렉트할 수 있도록 response를 저장, 브라우저가 멈추지 않게 함
  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`,    // auth URL에 들어간 값과 정확히 일치해야 함
  client_id:      getOauthConfig().CLIENT_ID, // '9d1c250a-e61b-44d9-88ed-5944d1962f5e'
  code_verifier:  codeVerifier,               // 우리가 이 흐름을 시작했음을 증명
  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 명령을 호출합니다. 여기에는 눈에 띄는 보안 엔지니어링 결정이 두 가지 있습니다:

• Hex 인코딩: JSON 토큰 payload는 저장 전에 16진수로 변환됩니다 (-X 플래그). 이렇게 하면 셸 quoting 문제를 피할 수 있고, 더 중요하게는 CrowdStrike 같은 프로세스 모니터가 ps 출력이나 시스템 호출 로그에서 원시 토큰 값을 보지 못하게 합니다.
• stdin 우선 (security -i): payload가 4032바이트 이내에 들어오면 (4096 - 64 여유분), 명령행 인자 대신 stdin으로 전달합니다. 덕분에 토큰이 프로세스 인자 목록에 나타나지 않습니다. payload가 한도를 넘으면 debug 경고와 함께 argv 폴백을 사용합니다.
• Stale-while-error: security 서브프로세스가 일시적으로 실패하면, 사용자에게 "Not logged in" 오류를 보여주는 대신 마지막으로 정상적이었던 값을 캐시에서 제공합니다.

export async function installOAuthTokens(tokens: OAuthTokens): Promise<void> {
  // 1. 먼저 이전 상태를 삭제 (keychain 정리, 캐시 초기화)
  await performLogout({ clearOnboarding: false })

  // 2. 계정 정보를 global config에 저장 (민감하지 않은 JSON)
  const profile = tokens.profile ?? await getOauthProfileFromOauthToken(tokens.accessToken)
  if (profile) {
    storeOAuthAccountInfo({ accountUuid, emailAddress, organizationUuid, ... })
  }

  // 3. 토큰을 secure storage에 저장 (macOS에서는 keychain)
  const storageResult = saveOAuthTokensIfNeeded(tokens)
  clearOAuthTokenCache()

  // 4. 역할 조회 (org/workspace role), 중요하지 않으므로 실패 허용
  await fetchAndStoreUserRoles(tokens.accessToken).catch(logForDebugging)

  // 5. Console 경로, 토큰을 통해 영구 API key 생성
  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분 일찍
  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,
    // 백엔드는 refresh 시 scope 확장을 허용함 (ALLOWED_SCOPE_EXPANSIONS)
    scope: (requestedScopes?.length ? requestedScopes : CLAUDE_AI_OAUTH_SCOPES).join(' '),
  }

  // 이미 모든 필드가 캐시에 있으면 프로필 조회 생략
  const haveProfileAlready =
    config.oauthAccount?.billingType !== undefined &&
    config.oauthAccount?.accountCreatedAt !== undefined &&
    existing?.subscriptionType != null  // secure storage도 함께 확인해야 함

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

  return {
    accessToken,
    refreshToken: newRefreshToken,   // 서버가 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. 자격 증명을 지우기 전에 telemetry를 먼저 flush
  //    계정이 지워진 뒤에 조직 귀속 이벤트가 전송되는 일을 막음
  const { flushTelemetry } = await import('../../utils/telemetry/instrumentation.js')
  await flushTelemetry()

  await removeApiKey()

  // 2. secure storage 삭제 (keychain의 토큰 포함)
  const secureStorage = getSecureStorage()
  secureStorage.delete()

  // 3. 인증에 의존하는 모든 메모리 캐시 정리
  await clearAuthRelatedCaches()

  // 4. global config 업데이트
  saveGlobalConfig(current => ({
    ...current,
    oauthAccount: undefined,        // 계정 정보 제거
    ...(clearOnboarding && {
      hasCompletedOnboarding: false,
      subscriptionNoticeCount: 0,
      hasAvailableSubscription: false,
    }),
  }))
}
commands/logout/logout.ts

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

  // 계정 유형에 따라 인증 서버 선택
  const authUrlBase = loginWithClaudeAi
    ? 'https://claude.com/cai/oauth/authorize'   // 307으로 claude.ai로 이동
    : 'https://platform.claude.com/oauth/authorize'

  const authUrl = new URL(authUrlBase)
  authUrl.searchParams.append('code',              'true')  // Claude Max 업셀 표시
  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)

  // 선택 사항: 로그인 폼 미리 채우기 (표준 OIDC)
  if (loginHint)   authUrl.searchParams.append('login_hint',   loginHint)
  // 선택 사항: 특정 로그인 방식 요청
  if (loginMethod) authUrl.searchParams.append('login_method', loginMethod)
  // 선택 사항: 특정 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.')
  }
  // 모든 OAuth URL을 FedStart 배포를 가리키도록 재설정
  config = { ...config, BASE_API_URL: base, CONSOLE_AUTHORIZE_URL: `${base}/oauth/authorize`, ... }
}
constants/oauth.ts