Summary

Adds full OAuth 2.1 support for HTTP MCP servers, letting tomo connect to protected endpoints like Atlassian, GitHub, Slack, or internal APIs that sit behind a Bearer-auth wall. The SDK handles the protocol (discovery, PKCE, DCR, token exchange, refresh); tomo plugs in a disk-backed provider, a loopback callback catcher, a browser launcher, an Ink modal, and a UI store to surface the flow in-app.

GitHub Issue

Closes #203

What Changed

Seven milestones, one per commit, each leaving the branch mergeable:

• M1 — config schema. Optional auth: { clientId?, clientSecret?, scope? } block on mcpHttpConnectionSchema. A .refine rejects clientSecret without clientId. Static headers (API-key) auth still works unchanged because the SDK only kicks in OAuth on a 401.
• M2 — disk-backed OAuthClientProvider. src/mcp/oauth-storage.ts owns atomic 0600 file writes for per-server state under ~/.tomo/mcp-oauth/<server>.json with a 0700 parent dir. src/mcp/oauth-provider.ts implements every hook on the SDK's provider interface, including state() (generates a fresh randomUUID each flow — required for Atlassian and friends to echo state back on the callback), saveDiscoveryState, and scoped invalidateCredentials. Server names are sanitised to a filesystem-safe stem so URL-as-connection-key values like https://mcp.atlassian.com/v1/mcp don't produce nested paths.
• M3 — primitives. src/mcp/oauth-loopback.ts binds an HTTP server on 127.0.0.1 that waits for a single OAuth redirect, validates the state parameter, supports AbortSignal cancellation and a 5-minute timeout, and persists the bound port so DCR-registered redirect URIs survive restarts. src/utils/open-url.ts wraps macOS open via child_process.spawn (hand-rolled over the 50 kB open npm dep).
• M4 — wire it into createHttpMcpClient. The factory chain becomes async. Each createHttpMcpClient call eagerly binds the loopback, builds the provider, and hands both to the client's connect/listTools/callTool wrappers. The initial-connect path needs a special retry: both StreamableHTTPClientTransport.start and Client.connect refuse to run twice on the same instance, so on a 401 we exchange the code on the failed transport (which still holds the discovery state), close it, then build a fresh pair and connect with the saved tokens. Mid-session 401s on tools still retry on the live instance via a generic withAuthRetry helper.
• M5 — McpAuthModal Ink component. Pure presentational overlay. Displays the server name, the auth URL, a "waiting for browser" spinner, Esc-to-cancel. A headless variant replaces the spinner with a paste-URL text input. Shipped as a dead render path — the wiring comes in M6.
• M6 — in-progress auth prompt in the chat. src/mcp/mcp-auth-store.ts implements the prompt-queue-style store. useMcp owns a single store instance across effect runs and threads it into createMcpClient via an optional authUi context. createHttpMcpClient swaps its onRedirect for a UI-aware one that races the loopback against the store's pending promise — loopback wins dismiss the entry; Esc cancels reject with McpAuthCancelledError. chat.tsx renders the modal via useSyncExternalStore, slotting it ahead of confirm/ask prompts and the chat input.
• M7 — end-to-end integration test. A new mock-mcps/http-oauth.mjs implements the minimum subset of RFC 9728 + RFC 8414 + RFC 7591 plus a spec-compliant /authorize → /token flow, with a /__force_next_401 endpoint for mid-session reauth testing. src/mcp/oauth.integration.test.ts spawns the mock alongside the real provider + loopback + client, and mocks node:child_process.spawn (real spawn still available via importOriginal) so openUrl is intercepted and a "fake browser" drives /authorize via fetch-and-follow. Four scenarios covered: happy path, non-401 rethrow, mid-session 401 reauth, token persistence across restarts.

Notes for Reviewers

• Live-tested against Atlassian MCP during development. Three real-world bugs were found and folded into M4:
  1. URL-style server names exploded fs.writeFileSync with ENOENT because https:/... was being treated as a nested path. Fixed in oauth-storage.ts via filename sanitisation.
  2. /authorize callbacks arrived without a state param because the SDK only sends state when provider.state() is implemented. Added the hook — Atlassian echoes state back, loopback validates, flow completes.
  3. StreamableHTTPClientTransport already started! after a successful browser sign-in because the M4 v0 withAuthRetry naively retried connect() on the same transport instance. Verified via reading the SDK source that neither start() nor Client.connect() can be called twice on the same instance. Fixed with the fresh-pair pattern described above.
• Tokens persist across restarts. A second run against the same server skips the browser entirely — verified by both a live test and the M7 integration test asserting zero open spawn calls on the second connect.
• McpAuthCancelledError is thrown when the user presses Esc on the modal. It propagates through Promise.race → withAuthRetry → connect, and is surfaced via onConnectionError in useMcp as a readable "authorization cancelled" message.
• macOS-only. openUrl hard-codes open — matches tomo's current scope. If/when Linux/Windows support lands, the dispatch lives behind a single function.
• 1628 tests pass with 100% coverage across the repo. One narrow /* v8 ignore */ remains in client.ts on a defensive if (!pending) throw invariant guard — it's unreachable via the public API (our provider's onRedirect always sets pending before the SDK throws UnauthorizedError).
• headers and auth coexist. A user can set a static User-Agent (or anything else) in headers alongside an auth block. The SDK only activates OAuth on a 401 response, so the static header path is untouched.