fix(connectors): register a new dynamic client when a connector's scopes grow

Merged
KI
16d ago
+17721-40

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). null means 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, and upsertConnection stores it (on insert and on reconnect).
  • Client choice (ClientFor in client-identity.ts):
    • new grant: a stored, unexpired client whose scopes cover 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.
  • 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.ts resolves the connection's own client; the plugin proxy (resolve-target.ts) only reaches tokens through ensureFreshConnection, so it needed no change. forgetClient still deletes only the one client_id that answered invalid_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. connections takes ACCESS EXCLUSIVE for a moment (within the deploy's 5s lock_timeout and retries). No FKs touched, so no lock-order concern.
  • plugin_oauth_clients has 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: null in 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_clients and connections sizes 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 with oauth_client_id refreshes 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/trpc bun test (829 pass), apps/api bun 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 scopes and oauth_client_id columns 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.