OAuth flow

For oauth_2 plugins, the Plugins detail page shows an OAuth flow panel below the credentials panel.

Prerequisites

Before clicking Start OAuth:

1. Set client_id in the integration credentials
2. Set client_secret in the integration credentials
3. Make sure the plugin is in Studio's OAuth registry (studio-oauth.ts)

The Studio registry covers: slack, gmail, google-calendar, hubspot, github, notion, linear, asana. To add another, append a config to OAUTH_REGISTRY.

Flow

1. Click Start OAuth — POST /api/auth/start generates the auth URL with a signed state nonce
2. The auth URL opens in a new browser tab
3. You complete the OAuth dance with the provider
4. Provider redirects to GET /api/auth/callback?code=...&state=...
5. Callback verifies state, calls exchangeCodeForTokens, writes the tokens to the KeyStore
6. Redirects to /studio/plugins/<id>?auth=success

A success banner appears at the top of the detail page. The newly-written access_token / refresh_token / expires_at / scope show up in the credentials panel (masked).

Why localhost-redirect, not ephemeral-listener

An ephemeral local-HTTP-listener model would work for CLI flows, but Studio doesn't need that — the dev server is already a long-running HTTP server the browser can reach on localhost:4317. The redirect target is just /api/auth/callback on Studio itself. Simpler, fewer moving parts.

Notes

State signing uses HMAC-SHA256 with STUDIO_OAUTH_STATE_SECRET (defaults to a dev value — set in prod). Pending sessions live in memory with a 10-minute TTL and one-shot consumption.