# Anthropic OAuth Browser Flow — Design

**Goal:** Replace the manual auth-token paste in `/login anthropic` (option 2) and `flynn anthropic-auth --token` with a PKCE OAuth2 browser flow that obtains the token automatically via a local HTTP callback server.

**Date:** 2026-02-26

---

## OAuth Endpoints

| Field | Value |
|-------|-------|
| Authorization URL | `https://claude.ai/oauth/authorize` |
| Token URL | `https://console.anthropic.com/v1/oauth/token` |
| Client ID | `9d1c250a-e61b-44d9-88ed-5944d1962f5e` |
| Scopes | `user:inference user:profile` |
| PKCE method | S256 (SHA256) |

> **Note:** These endpoints and the client ID belong to Claude Code CLI. Anthropic has restricted third-party use of Pro subscription tokens as of early 2026; the flow may only complete for users with an active Claude Pro/Max session in the browser.

---

## Architecture

### Flow

1. Generate PKCE `code_verifier` (32 random bytes, base64url-encoded) and `code_challenge` (SHA256 of verifier, base64url-encoded).
2. Generate random `state` (16 bytes, hex) for CSRF protection.
3. Bind a one-shot HTTP server to `127.0.0.1:0` (OS picks a free port). Read the actual port from the server address.
4. Build the authorization URL with all required params and call `onOpen(url)`.
5. `onOpen` opens the browser using `child_process` + platform command (`xdg-open` / `open` / `start`). If launch fails, print the URL and instruct the user to open it manually — the server keeps running.
6. Wait for the browser to redirect to `http://127.0.0.1:{port}/callback?code=...&state=...`. Server validates `state`, responds with an HTML "Authentication complete — you can close this tab." page, then closes.
7. Exchange `code` + `code_verifier` at the token URL via POST.
8. Store the returned `access_token` as the `auth_token` field in `~/.config/flynn/auth.json`.

**Timeout:** 5 minutes. If the server receives no callback, it closes and throws `Error('Anthropic OAuth timed out after 5 minutes.')`.

---

## Components

### `src/auth/anthropic.ts` — new additions

```typescript
// PKCE
function generateCodeVerifier(): string
  // crypto.randomBytes(32).toString('base64url')

function generateCodeChallenge(verifier: string): string
  // createHash('sha256').update(verifier).digest('base64url')

// One-shot callback server
// Resolves with { code, state } when redirect arrives, rejects on timeout
function startCallbackServer(port: number, timeoutMs: number): Promise<{ code: string; state: string }>

// Token exchange
async function exchangeCodeForToken(
  code: string,
  codeVerifier: string,
  redirectUri: string,
): Promise<string>  // returns access_token

// Full public flow
export async function loginAnthropicOAuth(
  onOpen: (url: string) => void,
): Promise<string>
// Orchestrates all steps, calls storeAnthropicAuthToken() before returning
```

### `src/frontends/tui/minimal.ts` — Anthropic branch change

Option 2 ("Paste auth token") becomes "Browser OAuth":

```
Anthropic login:
  1) Paste API key
  2) Browser OAuth (Claude Pro/Max)
```

Option 2 flow:
```typescript
console.log(`${colors.gray}Starting Anthropic browser OAuth...${colors.reset}`);
await loginAnthropicOAuth((url) => {
  openBrowser(url);  // platform child_process call
  console.log(`${colors.gray}Opening browser. If it didn't open, visit:${colors.reset}`);
  console.log(url);
  console.log(`${colors.gray}Waiting for authentication...${colors.reset}`);
});
console.log(`${colors.gray}Anthropic auth token stored.${colors.reset}\n`);
```

The `credentialStored` flag pattern (already present) applies here too.

### `src/cli/anthropic-auth.ts` — new `--browser` flag

Add alongside the existing `--token` flag:

```
--browser    Obtain auth token via browser OAuth flow (Claude Pro/Max)
```

```typescript
if (mode === 'browser') {
  console.log('Starting Anthropic browser OAuth...');
  await loginAnthropicOAuth((url) => {
    openBrowser(url);
    console.log(`If browser didn't open, visit:\n${url}`);
    console.log('Waiting for authentication...');
  });
  console.log('Anthropic auth token stored in ~/.config/flynn/auth.json');
}
```

`parseAnthropicAuthMode` gains a third value: `'api' | 'token' | 'browser'`.

### Browser opening helper (inline, no new dependency)

```typescript
function openBrowser(url: string): void {
  const cmd = process.platform === 'win32' ? 'start'
    : process.platform === 'darwin' ? 'open'
    : 'xdg-open';
  spawn(cmd, [url], { detached: true, stdio: 'ignore' }).unref();
}
```

---

## Error Handling

| Scenario | Behaviour |
|----------|-----------|
| Port already in use | `127.0.0.1:0` avoids this — OS picks free port |
| Browser open fails | Print URL, keep server running, user opens manually |
| State mismatch | Throw `Error('OAuth state mismatch — possible CSRF attack.')` |
| Timeout (5 min) | Throw `Error('Anthropic OAuth timed out after 5 minutes.')` |
| Token exchange non-2xx | Throw `Error('Token exchange failed (${status}): ${body}')` |
| 403 from Anthropic | Surface message: "Anthropic OAuth requires an active Claude Pro/Max subscription." |

---

## Testing

### `src/auth/anthropic.test.ts` — new tests

- `generateCodeVerifier()` returns 43-char base64url string (no padding, URL-safe chars only)
- `generateCodeChallenge(verifier)` returns correct SHA256 base64url digest
- `loginAnthropicOAuth()` with mocked `http.createServer` + mocked `fetch`:
  - Verifies auth URL contains correct `client_id`, `scope`, `code_challenge_method=S256`, `redirect_uri`, `state`
  - Verifies token exchange POST body contains `code`, `code_verifier`, `redirect_uri`
  - Verifies `storeAnthropicAuthToken` called with returned `access_token`
- State mismatch → throws
- Timeout (use fake timers) → throws
- Token exchange 403 → throws with subscription message
- Token exchange other non-2xx → throws with status + body

### `src/cli/anthropic-auth.test.ts` — new tests

- `--browser` flag triggers `loginAnthropicOAuth` (mock it)
- `--browser` with existing token: prompts for confirmation before re-authenticating
- Existing `--token` and default API key tests unchanged

### `src/frontends/tui/minimal.test.ts`

- Anthropic option 2: mock `loginAnthropicOAuth`, verify it's called
- `credentialStored` flag: verify auth_mode prompt only appears after successful OAuth

---

## Files Changed

| File | Change |
|------|--------|
| `src/auth/anthropic.ts` | Add PKCE helpers, callback server, token exchange, `loginAnthropicOAuth` |
| `src/auth/anthropic.test.ts` | New tests for all new functions |
| `src/frontends/tui/minimal.ts` | Replace option 2 paste with browser OAuth |
| `src/frontends/tui/minimal.test.ts` | Update/add Anthropic login tests |
| `src/cli/anthropic-auth.ts` | Add `--browser` flag, `browser` auth mode |
| `src/cli/anthropic-auth.test.ts` | Tests for `--browser` flag |