workers-oauth-provider

@cloudflare/workers-oauth-provider is an OAuth 2.1 authorization server library purpose-built for Cloudflare Workers. It wraps an existing Workers fetch handler (either a plain ExportedHandler or a WorkerEntrypoint class) and inserts a complete authorization server in front of it — parsing and validating authorization requests, issuing and refreshing tokens, and enforcing bearer-token authentication on protected API routes — while leaving user authentication and consent screens entirely to the application.

It’s designed around the needs of remote MCP (Model Context Protocol) servers as well as ordinary OAuth-protected APIs: it implements RFC 8414 authorization server metadata, RFC 9728 protected resource metadata, RFC 9207 issuer identification, PKCE enforcement, resource indicators, Dynamic Client Registration, and the newer Client ID Metadata Document (CIMD) mechanism for zero-registration clients. All state — clients, grants, and tokens — is persisted in a single Workers KV namespace, with end-to-end encryption of application-specific token props.

What You Get

• A complete OAuth 2.1 authorization server (authorize, token, revoke, well-known metadata) implemented for the Workers runtime, requiring only a bound KV namespace.
• Automatic protection of one or more API route prefixes via apiRoute/apiHandler or apiHandlers, injecting authenticated ctx.props into the downstream handler.
• Support for pre-registered clients, Dynamic Client Registration, and Client ID Metadata Documents (CIMD) so MCP clients can authenticate without manual client setup.
• RFC 8414 and RFC 9728 metadata endpoints plus RFC 9207 issuer identification generated automatically, matching the MCP authorization-discovery specification.
• Configurable grant lifecycle: PKCE enforcement, resource indicators, refresh-token rotation, and automatic revocation of prior grants on re-authorization.

Common Use Cases

• Adding OAuth 2.1 login and token issuance to a remote MCP server hosted on Cloudflare Workers so MCP clients can authenticate.
• Protecting a Workers-hosted HTTP API behind bearer tokens without hand-rolling token validation, expiry, and refresh logic.
• Supporting third-party OAuth clients that use Dynamic Client Registration or CIMD instead of a pre-shared client_id/secret.
• Building a multi-tenant service on Workers where each authenticated request needs typed application data (userId, tenant, scopes) injected via ctx.props.

Under The Hood

Architecture The library exports a single OAuthProvider class (src/oauth-provider.ts, ~6,000 lines) that wraps either an ExportedHandler or a WorkerEntrypoint subclass; it routes incoming requests through internal handlers for the authorize endpoint, token endpoint, well-known metadata paths, and protected API routes (apiRoute/apiHandler/apiHandlers), falling back to a defaultHandler for everything else. Core logic composes dedicated modules — oauth-capabilities.ts (scope/PKCE/response-type validation, AuthorizationError, capability negotiation), oauth-client-metadata.ts (CIMD fetch/validation, redirect-URI scheme checks, DCR metadata resolution), and an ema/ subdirectory (constants, JTI store, JWKS provider, parser, signature verification, validators) implementing a separate JWT-bearer/id_jag external-token-exchange grant. All state — clients, grants, and tokens — is persisted through a single OAUTH_KV KVNamespace binding using prefixed keys with TTL-based expiry, so the storage schema itself is the core abstraction; changing it would require a coordinated migration across every stored object type.

Tech Stack Written entirely in TypeScript and targeted at the Cloudflare Workers runtime, built with tsdown, typechecked with tsc, and tested with vitest (separate unit and conformance suites). Tooling includes wrangler for local development and @changesets/cli with changelog-github for release management. The package ships with zero third-party runtime dependencies beyond the Workers platform’s own KVNamespace and WorkerEntrypoint globals, compiling to a single dist/oauth-provider.js with generated type declarations.

Code Quality An extensive test suite spans several files covering the provider core, CIMD flows, EMA/id_jag validation, and capability negotiation, using mock KV and execution-context helpers to exercise PKCE, dynamic registration, grant revocation, and RFC 9207 issuer propagation. CI runs typechecking, the full test suite, and a semgrep static-analysis pass. Errors are modeled as typed classes (AuthorizationError, OAuthError, ExternalTokenError, CimdFetchError) rather than ad hoc thrown strings, naming is consistent and descriptive, and the public API surface (Grant, Token, OAuthHelpers) is fully typed under TypeScript strict mode.

API Design The public API is a single constructor call — new OAuthProvider({ apiHandler, defaultHandler, ... }) — that requires minimal boilerplate to get an OAuth-protected Worker running, with well-documented options for scopes, resource metadata, CIMD, and grant revocation batching. Documentation is unusually thorough for a package this size: a detailed README quick-start, a dedicated advanced-configuration doc, and a storage-schema reference describing every KV key format, all of which lowers onboarding effort for a protocol as intricate as OAuth 2.1.