AGENTS.md

1# src/features/mcp-oauth/ — OAuth 2.0 + PKCE + DCR for MCP Servers
2 
3**Generated:** 2026-05-15
4 
5## OVERVIEW
6 
7Full OAuth 2.0 authorization flow for MCP servers requiring authentication. Implements PKCE (RFC 7636) and Dynamic Client Registration (DCR, RFC 7591). Used by `bunx oh-my-opencode mcp-oauth login`.
8 
9## AUTHORIZATION FLOW
10 
11```
121. discovery.ts → fetch /.well-known/oauth-authorization-server
132. dcr.ts → Dynamic Client Registration (if server supports it)
143. oauth-authorization-flow.ts → generate PKCE verifier/challenge
154. callback-server.ts → local HTTP server on random port for redirect
165. Open browser → authorization URL
176. callback-server.ts → receive code + state
187. provider.ts → exchange code for token (with PKCE verifier)
198. storage.ts → persist token to ~/.config/opencode/mcp-oauth/
209. step-up.ts → handle step-up auth if initial token insufficient
21```
22 
23## KEY FILES
24 
25| File | Purpose |
26|------|---------|
27| `oauth-authorization-flow.ts` | PKCE helpers: `generateCodeVerifier()`, `generateCodeChallenge()`, `buildAuthorizationUrl()` |
28| `callback-server.ts` | Local HTTP redirect server — listens for OAuth callback |
29| `provider.ts` | `OAuthProvider` — token exchange, refresh, revoke |
30| `discovery.ts` | Fetch + parse OAuth server metadata from well-known endpoint |
31| `dcr.ts` | Dynamic Client Registration — register this app with OAuth server |
32| `step-up.ts` | Handle step-up authentication challenges |
33| `storage.ts` | Persist tokens to `~/.config/opencode/mcp-oauth/{server-hash}.json` |
34 
35## PKCE IMPLEMENTATION
36 
37- Code verifier: 32 random bytes → base64url (no padding)
38- Code challenge: SHA-256(verifier) → base64url
39- Method: `S256`
40 
41## TOKEN STORAGE
42 
43Location: `~/.config/opencode/mcp-oauth/` — one JSON file per MCP server (keyed by server URL hash).
44Fields: `access_token`, `refresh_token`, `expires_at`, `client_id`.
45 
46## CLI COMMANDS
47 
48```bash
49bunx oh-my-opencode mcp-oauth login <server-url>   # Full PKCE flow
50bunx oh-my-opencode mcp-oauth logout <server-url>  # Revoke + delete token
51bunx oh-my-opencode mcp-oauth status               # List stored tokens
52```
53