OAuth Service

• Entity ID: ent-20260410-f459c845226e
• Type: service
• Scope: shared
• Status: active
• Aliases: OAuth, authentication, login, PKCE

Description

The OAuth service (src/services/oauth/) implements OAuth 2.0 Authorization Code flow with PKCE for authenticating with Claude.ai and the Anthropic Console API. It handles browser-based authorization, local callback server, token exchange, profile fetching, and supports both automatic (browser redirect) and manual (code paste) flows.

How it works

OAuth flow (OAuthService.startOAuthFlow())

1. Generate PKCE values: codeVerifier (base64url of 32 random bytes), codeChallenge (SHA-256 of verifier), state (32 random bytes for CSRF protection)
2. Create AuthCodeListener — local HTTP server on localhost, OS-assigned port, listening at /callback
3. Build two auth URLs:
4. automaticFlowUrl — includes redirect URI for browser redirect
5. manualFlowUrl — for environments where localhost is unreachable (user copies auth code)
6. Open browser to authorization endpoint
7. Wait for callback with ?code=AUTH_CODE&state=STATE
8. Validate state parameter (CSRF protection)
9. Exchange code for tokens
10. Fetch profile info (subscription type, rate limit tier)

Options

Token response

Returns OAuthTokens: accessToken, refreshToken, expiresAt (Date.now() + expires_in * 1000), scopes, subscriptionType, rateLimitTier, profile, tokenAccount (uuid, emailAddress, organizationUuid).

Auth endpoints

Two endpoint sets determined by shouldUseClaudeAIAuth(scopes): - Claude.ai: CLAUDE_AI_AUTHORIZE_URL — for Claude.ai inference scope - Console: CONSOLE_AUTHORIZE_URL — for API console access

PKCE crypto (crypto.ts)

• generateCodeVerifier() — base64URLEncode(randomBytes(32))
• generateCodeChallenge(verifier) — SHA-256 hash, base64url encoded
• generateState() — base64URLEncode(randomBytes(32))

Local callback server (auth-code-listener.ts)

AuthCodeListener class — HTTP server on localhost with OS-assigned port. Captures the ?code=&state= parameters from the OAuth redirect. hasPendingResponse() determines whether to use automatic (browser redirect) or manual (code paste) flow.

Trade-offs

1. PKCE only — no client secret required, standard for CLI/native apps. Relies entirely on PKCE for security.
2. Localhost callback — works on local machines but fails in remote/container environments. Manual code paste provides a fallback but is less convenient.
3. OS-assigned port — avoids port conflicts but means the callback URL includes a random port, requiring dynamic auth URL generation.
4. Two endpoint sets — supports both Claude.ai and Console auth but doubles the configuration surface.

Depends on

• entrypoint-system — auth command registered as CLI subcommand
• Node.js http module — local callback server
• Node.js crypto module — PKCE value generation

Key claims

• Uses OAuth 2.0 Authorization Code + PKCE (no client secret)
• Supports automatic (browser redirect) and manual (code paste) flows
• CSRF protection via random state parameter validation
• Two auth endpoint sets: Claude.ai and Console

Relations

• related_to mcp-auth (MCP uses its own OAuth flow)
• used_by entrypoint-system (auth login/logout/status commands)
• used_by service-layer

Sources

src-20260409-a5fc157bc756, source code analysis of src/services/oauth/