feat(oauth)!: serve the AuthKit OAuth server MCP clients sign in through

[gjtorikian]

Supersedes #127 by @flyinprogrammer. Main moved under that PR and its fork does not allow maintainer pushes, so this branch carries Alan's five commits unchanged (same SHAs, same authorship) plus two production-fidelity commits and a merge of main. The design, route table and the end-to-end MCP client spec are his; read #127 for the full write-up.

What #127 adds

An MCP client signs in to a WorkOS environment through its AuthKit domain acting as an OAuth 2.1 authorization server. The emulator now serves that flow: discovery at /.well-known/oauth-authorization-server and /.well-known/openid-configuration, dynamic client registration at POST /oauth2/register (RFC 7591), hosted sign-in through GET /oauth2/authorize with PKCE and RFC 8707 resource, public-client and refresh_token support at POST /oauth2/token, GET /oauth2/error, and the spec's /user_management/authkit_oauth_resources routes with a resourceIndicators seed key.

What this branch changes on top (d8e4c22, b1e72e1)

The rules #127 derived from observed responses or RFC reasoning are replaced with the ones the production authkit-idp handlers, guards and consent token service apply. Each commit message cites the monorepo file and line for every rule.

• Authorize failures never answer with an API body: the error page for invalid_query_params, application_not_found and invalid_redirect_uri, the callback for everything after, with descriptions only where production gives them. Both redirects are built from baseUrl like every other minted link.
• Scopes: an omitted scope grants nothing; the standard scopes are open to every OAuth application and a custom scope must be the application's own; a custom scope removed later drops out of tokens while the standard ones stay.
• PKCE is checked where production checks it: a challenge must name its method, a public client without one fails at the token endpoint, a bad verifier never spends the code, and the verifier's shape is not checked.
• Dynamic registration: client_name is required; application_type is echoed and defaults to web (native defaults to none); scopes the client could not be granted are dropped and the effective set echoed; scope is returned only when requested.
• Client authentication is the two token-endpoint guards: the body's client_id wins outright, Basic is decoded without further form-decoding, credentials come from the body or Basic alike, the guards run before the body is validated, and the messages are Missing client_secret., Unsupported client_secret. and Application not found.
• Refresh tokens follow shouldIssueRefreshToken: offline_access always earns one; otherwise a dynamically registered client gets one iff it did not ask for openid. Registered grant_types no longer gate it. Rotation applies to public clients only.
• Token responses carry production's shapes: lowercase bearer, an id_token on every code exchange with no scope field, id_token plus rotated refresh_token plus scope on refresh, auth_time on access tokens, a sorted scope that is absent rather than empty, bare invalid_grant for every code and refresh failure, and client_credentials omitting an empty scope.
• Resource indicators match by normalized URL. A dynamically registered client's resource is validated only once resources are registered; with none registered the parameter is ignored; a client bound to nothing takes the resource flagged default; a bound resource since deleted is invalid_target with no description. The aud fallback is documented as the one deviation on that claim.
• authkit_oauth_resource is registered in the response-shape catalogs.

BREAKING CHANGE

Answers on the existing /oauth2/authorize and /oauth2/token routes change to what production returns: authorize failures redirect to the error page or the callback instead of answering an API body, and a missing or unknown client at the token endpoint is 401 invalid_client with production's messages. An OAuth application with no login_url now gets the hosted sign-in instead of 400 unauthorized_client. Applications with a login_url keep Standalone Connect.

Merge order

Land #137 (refresh-token replay grace) first. It makes exchanged_at and exchanged_for_id required on WorkOSRefreshToken, so this branch's three refreshTokens.insert calls (src/workos/routes/oauth.ts and two specs) need those two fields added on rebase. Production applies the same replay grace on the OAuth refresh grant, so extending #137's chain logic to /oauth2/token is a follow-up.

Verification

Run locally on this head (no CI has run on the branch yet):

bun run typecheck
bun run lint
bun run gen:events && bun run gen:shapes && bun run gen:supported && git diff --exit-code -- src/workos/generated SUPPORTED.md
bun test        # 1532 pass, 0 fail across 80 files

[greptile-apps]

Confidence Score: 5/5

[Critical impact] The PR appears safe to merge, with no outstanding findings.

Summary

Adds the AuthKit OAuth server used by MCP clients, including discovery, client registration, hosted sign-in, PKCE, refresh tokens, and resource indicators.

• MCP clients can sign in through the emulator’s AuthKit domain.
• OAuth code and refresh grants return AuthKit-style tokens and errors.
• Registered resource servers can set the audience on OAuth tokens.

Diagram

sequenceDiagram
  participant Client as MCP client
  participant OAuth as AuthKit OAuth server
  participant Login as Hosted sign-in
  Client->>OAuth: Discover endpoints and register
  Client->>OAuth: Authorize with PKCE and resource
  OAuth->>Login: Redirect to sign-in
  Login-->>Client: Redirect to callback with code
  Client->>OAuth: Exchange code and verifier
  OAuth-->>Client: Access token, ID token, optional refresh token
  Client->>OAuth: Refresh
  OAuth-->>Client: New tokens

Loading

_{Reviews (2) · Last reviewed commit: "fix(oauth): Sweep a gone session's refre..." · Reviewed by Greptile}