Scope

This is PR 1/4 adding an OAuth 2.1 authorization server to Directus so that MCP clients (like Claude Desktop) can authenticate through a standard OAuth flow instead of requiring a manually provisioned static token. The full stack:

1. Schema + auth plumbing (this PR) -- tables, types, env vars, token source tracking
2. Guards on existing code -- OAuth session isolation, MCP server auth checks
3. OAuth service + consent page -- the authorization server business logic
4. Controller wiring + app integration -- HTTP routes, app.ts, login redirect, integration tests

Future Work (should happen before release)

• Add Enable MCP OAuth to AI settings in the studio, disabled by default, then we could enable env by default (like MCP)
• Add Connected Clients listing to the Studio to give admins the ability to revoke individual clients (which are automatically registered because of DCR)
• Add CIMD (Client ID Metadata Document) support -- the MCP spec's preferred client registration mechanism (added in #27106)

The implementation follows OAuth 2.1 with mandatory PKCE (RFC 7636), Dynamic Client Registration (RFC 7591), Resource Indicators (RFC 8707), and the discovery metadata specs (RFC 8414, RFC 9728). Design docs and ADRs are included in this PR for context.

Key design constraints:

• Public and confidential clients -- public clients (token_endpoint_auth_method: none) self-register via DCR
  and are identified by client_id alone, with mandatory PKCE S256. Confidential client support
  (client_secret_basic, client_secret_post) for clients like Figma Make that require a client_secret was
  added in #27107.
• Single scope: mcp:access -- OAuth tokens are scoped exclusively to /mcp endpoints. A route guard (PR 2)
  enforces this, and existing Directus auth flows (session refresh, logout, WebSocket) reject OAuth sessions entirely.
  This keeps the blast radius tight: an OAuth token can't touch the rest of the API.
• Server-rendered consent -- the consent page is standalone HTML outside the Vue SPA. No JavaScript touches the
  authorization code. The user authenticates via their normal Directus session, approves on a native form, and the code
  goes straight to the client via 302 redirect.

This PR lays the foundation: database schema, type system changes, and low-level middleware plumbing that later PRs build on. Nothing is wired up yet -- purely additive with zero behavioral impact on existing functionality.

What's changed:

• Database migration creating four new system tables (directus_oauth_clients, directus_oauth_codes,
  directus_oauth_consents, directus_oauth_tokens) and adding an oauth_client FK column to directus_sessions
• System data registration so the schema introspection layer knows about these collections (field metadata YAMLs,
  collection entries, FK relations)
• tokenSource tracking on Request -- the extract-token middleware now records where the token came from
  ('cookie' | 'header' | 'query'), which later PRs use to enforce bearer-only transport for OAuth tokens per
  RFC 6750 Section 2
• oauth on Accountability -- getAccountabilityForToken now builds accountability.oauth: { client, scopes, aud } from the session DB (oauth_client column) and JWT claims (scope, aud). Downstream code uses this structured object to distinguish OAuth sessions and enforce scope/audience checks without re-decoding the JWT
• Environment variables (see table below)
• Design docs and ADRs covering token storage strategy, library choice (no library), and scope restriction rationale

Environment variables

Schema design

Four tables, created in FK-dependency order:

directus_oauth_clients -- registered MCP clients (RFC 7591). client_id is a string(255) primary key -- for DCR clients this is a server-assigned UUID, but the column uses string instead of uuid to support CIMD (Client ID Metadata Document) where the client_id is an HTTPS URL. This matches Keycloak's data model (VARCHAR(255)). client_id is public and not a secret since these are public clients (token_endpoint_auth_method: 'none'). redirect_uris and grant_types are stored as JSON arrays. No client_secret column -- confidential client support can be added via a future migration if needed.

directus_oauth_consents -- records that a user approved a specific client + redirect_uri combination. Unique on (user, client, redirect_uri). Used for potential future "remember this client" flows; currently a new consent record is created or updated on every approval.

directus_oauth_codes -- short-lived authorization codes. code_hash stores the SHA-256 hash (the raw code is never persisted). Two temporal columns serve distinct purposes: expires_at is the hard TTL (default 60s) after which the code is invalid regardless of state, while used_at tracks redemption -- NULL means unredeemed, non-NULL means already exchanged for tokens. This separation enables atomic burn-on-use (UPDATE WHERE used_at IS NULL) while keeping expired-but-unused codes around briefly for cleanup. code_challenge and code_challenge_method store the PKCE challenge for verification at token exchange time. Both temporal columns are indexed for the cleanup schedule.

directus_oauth_tokens -- active grants. UNIQUE(client, user) enforces one grant per client-user pair. This is a design choice, not an OAuth spec requirement -- RFC 6749 is silent on concurrent grants. With only one scope (mcp:access) and one resource, multiple concurrent grants to the same client would be redundant state. Easily reversible: dropping the unique constraint is a one-line migration, and the service code that replaces existing grants would just become a no-op. session is the SHA-256 hash of the current refresh token and points to a row in directus_sessions. previous_session stores the hash of the last-rotated-out refresh token for reuse detection -- if a client presents previous_session instead of session, it means the current token was stolen and the grant gets revoked entirely.

directus_sessions.oauth_client -- nullable string(255) FK to directus_oauth_clients. When set, the session belongs to an OAuth grant rather than a regular browser/API session. This single column is how the rest of Directus distinguishes OAuth sessions from regular ones (via accountability.oauth).

All user and client FKs use ON DELETE CASCADE, so deleting a user automatically revokes all their OAuth grants, consents, and codes, and deleting a client tears down everything issued to it (including sessions via directus_sessions.oauth_client). No application-level cleanup needed for these cases -- the scheduled cleanup job only handles expiration and orphan detection.

Potential Risks / Drawbacks

• New system tables are added regardless of MCP_OAUTH_ENABLED -- the migration always runs. This keeps the schema
  consistent and avoids conditional migration complexity.
• oauth_client column on directus_sessions is nullable and indexed. Existing sessions have NULL, so there's no
  data migration.

Tested Scenarios

• Env var defaults and type-map registration (unit tests)
• extract-token correctly sets tokenSource for all three sources (updated existing tests)
• verifySessionJWT returns oauth_client from session record (new test file)
• getAccountabilityForToken builds accountability.oauth from JWT claims + session DB (new tests including scope parsing and aud normalization)

Review Notes / Questions

• The migration creates tables in FK-dependency order and tears down in reverse. All FKs use ON DELETE CASCADE for the
  user/client references.
• tokenSource on Request is typed as the union 'cookie' | 'header' | 'query' | null (null when no token is present).
  This is a net-new field, not a modification of existing behavior.
• client_id uses string(255) instead of uuid to future-proof for CIMD support. DCR-assigned UUIDs fit in a varchar(255) with no behavioral change.

Trying it out

This PR is schema and plumbing only -- to test the full OAuth flow end-to-end, check out PR 4 which wires everything together. See the step-by-step guide in PR 4's description.

Checklist

• Added or updated tests
• Documentation PR created here or not required
• OpenAPI package PR created here or not required