fix(connectors): register a new dynamic client when a connector's scopes grow
Bug
Connectors with "client": "dynamic" register an OAuth client once (RFC 7591) with the connector's scopes at that moment, store it in plugin_oauth_clients (unique on issuer + redirect_uri), and resolveClientIdentity reuses that row forever. When a connector's scope list grows, the provider rejects the authorize request. After #9176 added rewards:read/rewards:write to autumn_mcp, Autumn (better-auth oauth-provider, issuer https://api.useautumn.com/api/auth) answered:
error=invalid_scope&error_description=The following scopes are invalid: rewards:read, rewards:write
Autumn's /.well-known/oauth-authorization-server lists both scopes in scopes_supported; the stored client was just never registered for them.
Design
plugin_oauth_clients.scopes text[]: the scopes a client was registered for (what we asked for, not what the response echoes, so a server that grants less cannot send every connect into another registration).nullmeans a row from before this PR.- Several clients per issuer + redirect: the unique index is now
(issuer, redirect_uri, client_id). A registration inserts its own row and returns its own client; if the server hands back a client_id we already store, the row is updated from the new response. Two processes registering at once each get a valid client, and each grant records which one it used. connections.oauth_client_id: the client the grant was issued to. The connect route resolves the client once, puts its id in the signed OAuth state, and builds the authorize URL from the same endpoints; the callback redeems the code as that client, andupsertConnectionstores it (on insert and on reconnect).- Client choice (
ClientForinclient-identity.ts):- new grant: a stored, unexpired client whose
scopescover every requested scope; otherwise register one. - issued grant with
oauth_client_id: exactly that client. If its row is gone, refresh marks the connection needs-reauth without registering a client the refresh token could never work with. - issued grant with
oauth_client_id = null(every connection today, and flows started before the deploy): the oldest unexpired client for the issuer + redirect, which is the one they were issued to. Same behaviour as today. - CIMD connectors (client_id = metadata URL) are unchanged; the metadata URL is recorded as the client id.
- new grant: a stored, unexpired client whose
- Legacy rows cover no scope. We don't know what they were registered with, and the Autumn row is exactly a legacy row that is missing scopes, so treating legacy rows as covering would leave Autumn broken. A connector requesting no scopes is trivially covered by any row. Cost: each dynamic connector that requests scopes registers one new client on its next connect; existing connections keep the legacy row.
- Refresh and the proxy:
refresh.tsresolves the connection's own client; the plugin proxy (resolve-target.ts) only reaches tokens throughensureFreshConnection, so it needed no change.forgetClientstill deletes only the one client_id that answeredinvalid_client. - RFC 7592 client update is not used: Autumn does not advertise
registration_client_uri, and registering anew covers every server.
Migration
packages/db/drizzle/0180_dynamic_client_scopes.sql, generated with drizzle-kit generate:
DROP INDEX "plugin_oauth_clients_issuer_redirect_unique";
ALTER TABLE "plugin_oauth_clients" ADD COLUMN "scopes" text[];
ALTER TABLE "connections" ADD COLUMN "oauth_client_id" text;
CREATE UNIQUE INDEX "plugin_oauth_clients_issuer_redirect_client_unique" ON "plugin_oauth_clients" USING btree ("issuer","redirect_uri","client_id");
Safety checklist:
- Nullable ADD COLUMN with no default is metadata-only; no rewrite.
connectionstakes ACCESS EXCLUSIVE for a moment (within the deploy's 5s lock_timeout and retries). No FKs touched, so no lock-order concern. plugin_oauth_clientshas one row per dynamic issuer + redirect, so the index rebuild is instant.- No column type change; no reads move to a new table. No backfill is needed:
nullin both new columns means today's behaviour. - Not rehearsed under load: it touches no table from rule 4 and rewrites nothing. I did not run the production size query (I was asked not to touch production); worth a glance at
plugin_oauth_clientsandconnectionssizes before merging. - No tRPC input change; connection rows gain one nullable field.
- Between the migration and the new code going live, old code that registers a client would fail its
ON CONFLICT (issuer, redirect_uri)because that index is gone. That only affects a connector with no stored client at all, for the length of the deploy.
Rollout
- Existing connections are untouched and keep refreshing with the client they were authorized with.
- Each dynamic connector that requests scopes registers one new client on its next connect (Autumn included), and that connection records it.
Autumn scopes
This supersedes #9176 and replaces the revert in #9201. main still has rewards:read/rewards:write on autumn_mcp because #9201 is not merged yet, so this branch needs no change to connectors.json. If #9201 merges first (fine as an immediate mitigation), this branch must be rebased and the two scopes re-added after plans:write, or the merge silently keeps them removed.
Tests
client-identity.test.ts(new): a stored client missing a requested scope leads to a new registration with the full scope list; a legacy row is not trusted; a covering client is reused; an issued grant keeps its client; a legacy grant uses the oldest client; a forgotten client is not replaced.refresh.test.ts: a connection withoauth_client_idrefreshes as its own client; a legacy connection refreshes as the oldest (legacy) client; a forgotten client marks needs-reauth with no token request.bun run typecheck(42/42),bun run lint,packages/trpcbun test(829 pass),apps/apibun test src(240 pass).
🤖 Generated with Claude Code
Summary by cubic
Dynamic OAuth connectors now register a new OAuth client when a connector's scope list grows, instead of reusing one stored client forever. Previously the stored client kept its original scopes, so providers rejected the authorize request once scopes were added — Autumn answered invalid_scope for rewards:read/rewards:write even though its metadata lists both.
plugin_oauth_clients now records the scopes each client was registered for and allows several clients per issuer and redirect URI. A new grant reuses a stored client whose scopes cover the request, or registers one; a grant already issued refreshes as the client it was issued to, recorded in connections.oauth_client_id.
- Rows from before scopes were recorded cover no scope, so connectors that request scopes register one new client on their next connect.
- Connections from before client ids were recorded refresh only against the pre-scopes row; once that client is gone, refresh marks the connection needs-reauth rather than moving to a newer client its refresh token could never work with.
- New migration adds nullable
scopesandoauth_client_idcolumns and replaces the old unique index with one on(issuer, redirect_uri, client_id); no backfill is needed, but old code can fail on the dropped index between migration and deploy.
Summary by CodeRabbit
- New Features
- OAuth connections retain the client identity used during authorization so token exchanges and refreshes use the same client.
- New connections can reuse a registered client that covers the requested scopes or register a client when needed.
- Client registrations now record their supported scopes, allowing them to be selected for future connections.
- Bug Fixes
- If a connection’s registered client is unavailable, it is marked for reauthorization rather than refreshed with a different client.