@cloudflare/workers-oauth-provider 0.2.3 → 0.2.4

package/README.md

@@ -81,6 +81,12 @@ export default new OAuthProvider({
   // Defaults to false.
   allowImplicitFlow: false,
 
+  // Optional: Controls whether the plain PKCE code_challenge_method is allowed.
+  // OAuth 2.1 recommends using S256 exclusively as plain offers no cryptographic protection.
+  // When false, only S256 is accepted and advertised in the metadata endpoint.
+  // Defaults to true for backward compatibility.
+  allowPlainPKCE: true,
+
   // Optional: Controls whether public clients (clients without a secret, like SPAs)
   // can register via the dynamic client registration endpoint.
   // When true, only confidential clients can register.
@@ -304,6 +310,18 @@ new OAuthProvider({
 
 By default, the `onError` callback is set to ``({ status, code, description }) => console.warn(`OAuth error response: ${status} ${code} - ${description}`)``.
 
+## Standards Compliance
+
+This library implements the following OAuth and MCP specifications:
+
+- [OAuth 2.1 (draft-ietf-oauth-v2-1-13)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13) — Core authorization framework with PKCE
+- [OAuth 2.0 Authorization Server Metadata (RFC 8414)](https://datatracker.ietf.org/doc/html/rfc8414) — `/.well-known/oauth-authorization-server` discovery endpoint
+- [OAuth 2.0 Protected Resource Metadata (RFC 9728)](https://datatracker.ietf.org/doc/html/rfc9728) — `/.well-known/oauth-protected-resource` discovery endpoint
+- [OAuth 2.0 Dynamic Client Registration (RFC 7591)](https://datatracker.ietf.org/doc/html/rfc7591) — Dynamic client registration endpoint
+- [OAuth Client ID Metadata Documents (draft-ietf-oauth-client-id-metadata-document)](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document) — HTTPS URLs as client IDs
+
+These are the specifications required by the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).
+
 ## Implementation Notes
 
 ### End-to-end encryption

package/dist/oauth-provider.d.ts

@@ -13,8 +13,10 @@ declare enum GrantType {
 /**
  * Aliases for either type of Handler that makes .fetch required
  */
-type ExportedHandlerWithFetch = ExportedHandler & Pick<Required<ExportedHandler>, 'fetch'>;
-type WorkerEntrypointWithFetch = WorkerEntrypoint & Pick<Required<WorkerEntrypoint>, 'fetch'>;
+type ExportedHandlerWithFetch<Env = Cloudflare.Env> = ExportedHandler<Env> & Pick<Required<ExportedHandler<Env>>, 'fetch'>;
+type WorkerEntrypointWithFetch<Env = Cloudflare.Env> = WorkerEntrypoint<Env> & {
+  fetch: NonNullable<WorkerEntrypoint['fetch']>;
+};
 /**
  * Configuration options for the OAuth Provider
  */
@@ -119,7 +121,7 @@ interface ResolveExternalTokenResult {
    */
   audience?: string | string[];
 }
-interface OAuthProviderOptions {
+interface OAuthProviderOptions<Env = Cloudflare.Env> {
   /**
    * URL(s) for API routes. Requests with URLs starting with any of these prefixes
    * will be treated as API requests and require a valid access token.
@@ -137,7 +139,7 @@ interface OAuthProviderOptions {
    * Used with `apiRoute` for the single-handler configuration. This is incompatible with
    * the `apiHandlers` property. You must use either `apiRoute` + `apiHandler` OR `apiHandlers`, not both.
    */
-  apiHandler?: ExportedHandlerWithFetch | (new (ctx: ExecutionContext, env: any) => WorkerEntrypointWithFetch);
+  apiHandler?: ExportedHandlerWithFetch<Env> | (new (ctx: ExecutionContext, env: Env) => WorkerEntrypointWithFetch<Env>);
   /**
    * Map of API routes to their corresponding handlers for the multi-handler configuration.
    * The keys are the API routes (strings only, not arrays), and the values are the handlers.
@@ -148,12 +150,12 @@ interface OAuthProviderOptions {
    * `apiRoute` + `apiHandler` (single-handler configuration) OR `apiHandlers` (multi-handler
    * configuration), not both.
    */
-  apiHandlers?: Record<string, ExportedHandlerWithFetch | (new (ctx: ExecutionContext, env: any) => WorkerEntrypointWithFetch)>;
+  apiHandlers?: Record<string, ExportedHandlerWithFetch<Env> | (new (ctx: ExecutionContext, env: Env) => WorkerEntrypointWithFetch<Env>)>;
   /**
    * Handler for all non-API requests or API requests without a valid token.
    * Can be either an ExportedHandler object with a fetch method or a class extending WorkerEntrypoint.
    */
-  defaultHandler: ExportedHandler | (new (ctx: ExecutionContext, env: any) => WorkerEntrypointWithFetch);
+  defaultHandler: ExportedHandler<Env> | (new (ctx: ExecutionContext, env: Env) => WorkerEntrypointWithFetch<Env>);
   /**
    * URL of the OAuth authorization endpoint where users can grant permissions.
    * This URL is used in OAuth metadata and is not handled by the provider itself.
@@ -191,6 +193,13 @@ interface OAuthProviderOptions {
    * Defaults to false.
    */
   allowImplicitFlow?: boolean;
+  /**
+   * Controls whether the plain PKCE method is allowed.
+   * OAuth 2.1 recommends using S256 exclusively as plain offers no cryptographic protection.
+   * When set to false, only the S256 code_challenge_method will be accepted.
+   * Defaults to true for backward compatibility.
+   */
+  allowPlainPKCE?: boolean;
   /**
    * Controls whether OAuth 2.0 Token Exchange (RFC 8693) is allowed.
    * When false, the token exchange grant type will not be advertised in metadata
@@ -237,6 +246,40 @@ interface OAuthProviderOptions {
     status: number;
     headers: Record<string, string>;
   }) => Response | void;
+  /**
+   * Optional metadata for RFC 9728 OAuth 2.0 Protected Resource Metadata.
+   * Controls the response served at /.well-known/oauth-protected-resource.
+   *
+   * If not provided, the endpoint will be automatically generated using the request origin
+   * as the resource identifier, and the token endpoint's origin as the authorization server.
+   */
+  resourceMetadata?: {
+    /**
+     * The protected resource identifier URL (RFC 9728 `resource` field).
+     * If not set, defaults to the request URL's origin.
+     */
+    resource?: string;
+    /**
+     * List of authorization server issuer URLs that can issue tokens for this resource.
+     * If not set, defaults to the token endpoint's origin (consistent with the issuer
+     * in authorization server metadata).
+     */
+    authorization_servers?: string[];
+    /**
+     * Scopes supported by this protected resource.
+     * If not set, falls back to the top-level scopesSupported option.
+     */
+    scopes_supported?: string[];
+    /**
+     * Methods by which bearer tokens can be presented to this resource.
+     * Defaults to ["header"].
+     */
+    bearer_methods_supported?: string[];
+    /**
+     * Human-readable name for this resource.
+     */
+    resource_name?: string;
+  };
 }
 /**
  * Helper methods for OAuth operations provided to handler functions
@@ -714,13 +757,13 @@ interface GrantSummary {
  * Implements authorization code flow with support for refresh tokens
  * and dynamic client registration.
  */
-declare class OAuthProvider {
+declare class OAuthProvider<Env = Cloudflare.Env> {
   #private;
   /**
    * Creates a new OAuth provider instance
    * @param options - Configuration options for the provider
    */
-  constructor(options: OAuthProviderOptions);
+  constructor(options: OAuthProviderOptions<Env>);
   /**
    * Main fetch handler for the Worker
    * Routes requests to the appropriate handler based on the URL
@@ -729,7 +772,7 @@ declare class OAuthProvider {
    * @param ctx - Cloudflare Worker execution context
    * @returns A Promise resolving to an HTTP Response
    */
-  fetch(request: Request, env: any, ctx: ExecutionContext): Promise<Response>;
+  fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response>;
 }
 /**
  * Gets OAuthHelpers for the given environment
@@ -737,6 +780,6 @@ declare class OAuthProvider {
  * @param env - Cloudflare Worker environment variables
  * @returns An instance of OAuthHelpers
  */
-declare function getOAuthApi(options: OAuthProviderOptions, env: any): OAuthHelpers;
+declare function getOAuthApi<Env = Cloudflare.Env>(options: OAuthProviderOptions<Env>, env: Env): OAuthHelpers;
 //#endregion
 export { AuthRequest, ClientInfo, CompleteAuthorizationOptions, ExchangeTokenOptions, Grant, GrantSummary, GrantType, ListOptions, ListResult, OAuthHelpers, OAuthProvider, OAuthProvider as default, OAuthProviderOptions, ResolveExternalTokenInput, ResolveExternalTokenResult, Token, TokenBase, TokenExchangeCallbackOptions, TokenExchangeCallbackResult, TokenSummary, getOAuthApi };

package/dist/oauth-provider.js

@@ -141,7 +141,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	async fetch(request, env, ctx) {
 		const url = new URL(request.url);
 		if (request.method === "OPTIONS") {
-			if (this.isApiRequest(url) || url.pathname === "/.well-known/oauth-authorization-server" || this.isTokenEndpoint(url) || this.options.clientRegistrationEndpoint && this.isClientRegistrationEndpoint(url)) return this.addCorsHeaders(new Response(null, {
+			if (this.isApiRequest(url) || url.pathname === "/.well-known/oauth-authorization-server" || url.pathname === "/.well-known/oauth-protected-resource" || this.isTokenEndpoint(url) || this.options.clientRegistrationEndpoint && this.isClientRegistrationEndpoint(url)) return this.addCorsHeaders(new Response(null, {
 				status: 204,
 				headers: { "Content-Length": "0" }
 			}), request);
@@ -150,6 +150,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			const response = await this.handleMetadataDiscovery(url);
 			return this.addCorsHeaders(response, request);
 		}
+		if (url.pathname === "/.well-known/oauth-protected-resource") {
+			const response = this.handleProtectedResourceMetadata(url);
+			return this.addCorsHeaders(response, request);
+		}
 		if (this.isTokenEndpoint(url)) {
 			const parsed = await this.parseTokenEndpointRequest(request, env);
 			if (parsed instanceof Response) return this.addCorsHeaders(parsed, request);
@@ -287,8 +291,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	* @returns True if the URL matches the API route
 	*/
 	matchApiRoute(url, route) {
-		if (this.isPath(route)) return url.pathname.startsWith(route);
-		else {
+		if (this.isPath(route)) {
+			if (route === "/") return url.pathname === "/";
+			return url.pathname.startsWith(route);
+		} else {
 			const apiUrl = new URL(route);
 			return url.hostname === apiUrl.hostname && url.pathname.startsWith(apiUrl.pathname);
 		}
@@ -367,12 +373,31 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				"none"
 			],
 			revocation_endpoint: tokenEndpoint,
-			code_challenge_methods_supported: ["plain", "S256"],
+			code_challenge_methods_supported: this.options.allowPlainPKCE !== false ? ["plain", "S256"] : ["S256"],
 			client_id_metadata_document_supported: this.hasGlobalFetchStrictlyPublic()
 		};
 		return new Response(JSON.stringify(metadata), { headers: { "Content-Type": "application/json" } });
 	}
 	/**
+	* Handles the OAuth Protected Resource Metadata endpoint
+	* Implements RFC 9728 for OAuth Protected Resource Metadata
+	* @param requestUrl - The URL of the incoming request
+	* @returns Response with protected resource metadata
+	*/
+	handleProtectedResourceMetadata(requestUrl) {
+		const rm = this.options.resourceMetadata;
+		const tokenEndpointUrl = this.getFullEndpointUrl(this.options.tokenEndpoint, requestUrl);
+		const authServerOrigin = new URL(tokenEndpointUrl).origin;
+		const metadata = {
+			resource: rm?.resource ?? requestUrl.origin,
+			authorization_servers: rm?.authorization_servers ?? [authServerOrigin],
+			scopes_supported: rm?.scopes_supported ?? this.options.scopesSupported,
+			bearer_methods_supported: rm?.bearer_methods_supported ?? ["header"]
+		};
+		if (rm?.resource_name) metadata.resource_name = rm.resource_name;
+		return new Response(JSON.stringify(metadata), { headers: { "Content-Type": "application/json" } });
+	}
+	/**
 	* Handles client authentication and token issuance via the token endpoint
 	* Supports authorization_code and refresh_token grant types
 	* @param body - The parsed request body
@@ -411,7 +436,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		if (grantData.clientId !== clientInfo.clientId) return this.createErrorResponse("invalid_grant", "Client ID mismatch");
 		const isPkceEnabled = !!grantData.codeChallenge;
 		if (!redirectUri && !isPkceEnabled) return this.createErrorResponse("invalid_request", "redirect_uri is required when not using PKCE");
-		if (redirectUri && !clientInfo.redirectUris.includes(redirectUri)) return this.createErrorResponse("invalid_grant", "Invalid redirect URI");
+		if (redirectUri && !isValidRedirectUri(redirectUri, clientInfo.redirectUris)) return this.createErrorResponse("invalid_grant", "Invalid redirect URI");
 		if (!isPkceEnabled && codeVerifier) return this.createErrorResponse("invalid_request", "code_verifier provided for a flow that did not use PKCE");
 		if (isPkceEnabled) {
 			if (!codeVerifier) return this.createErrorResponse("invalid_request", "code_verifier is required for PKCE");
@@ -921,8 +946,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	* @returns Response from the API handler or error
 	*/
 	async handleApiRequest(request, env, ctx) {
+		const url = new URL(request.url);
+		const resourceMetadataUrl = `${url.origin}/.well-known/oauth-protected-resource`;
 		const authHeader = request.headers.get("Authorization");
-		if (!authHeader || !authHeader.startsWith("Bearer ")) return this.createErrorResponse("invalid_token", "Missing or invalid access token", 401, { "WWW-Authenticate": "Bearer realm=\"OAuth\", error=\"invalid_token\", error_description=\"Missing or invalid access token\"" });
+		if (!authHeader || !authHeader.startsWith("Bearer ")) return this.createErrorResponse("invalid_token", "Missing or invalid access token", 401, { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token", "Missing or invalid access token") });
 		const accessToken = authHeader.substring(7);
 		const parts = accessToken.split(":");
 		const isPossiblyInternalFormat = parts.length === 3;
@@ -934,14 +961,14 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			const id = await generateTokenId(accessToken);
 			tokenData = await env.OAUTH_KV.get(`token:${userId}:${grantId}:${id}`, { type: "json" });
 		}
-		if (!tokenData && !this.options.resolveExternalToken) return this.createErrorResponse("invalid_token", "Invalid access token", 401, { "WWW-Authenticate": "Bearer realm=\"OAuth\", error=\"invalid_token\"" });
+		if (!tokenData && !this.options.resolveExternalToken) return this.createErrorResponse("invalid_token", "Invalid access token", 401, { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") });
 		if (tokenData) {
 			const now = Math.floor(Date.now() / 1e3);
-			if (tokenData.expiresAt < now) return this.createErrorResponse("invalid_token", "Access token expired", 401, { "WWW-Authenticate": "Bearer realm=\"OAuth\", error=\"invalid_token\"" });
+			if (tokenData.expiresAt < now) return this.createErrorResponse("invalid_token", "Access token expired", 401, { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") });
 			if (tokenData.audience) {
 				const requestUrl = new URL(request.url);
 				const resourceServer = `${requestUrl.protocol}//${requestUrl.host}${requestUrl.pathname}`;
-				if (!(Array.isArray(tokenData.audience) ? tokenData.audience : [tokenData.audience]).some((aud) => audienceMatches(resourceServer, aud))) return this.createErrorResponse("invalid_token", "Token audience does not match resource server", 401, { "WWW-Authenticate": "Bearer realm=\"OAuth\", error=\"invalid_token\", error_description=\"Invalid audience\"" });
+				if (!(Array.isArray(tokenData.audience) ? tokenData.audience : [tokenData.audience]).some((aud) => audienceMatches(resourceServer, aud))) return this.createErrorResponse("invalid_token", "Token audience does not match resource server", 401, { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token", "Invalid audience") });
 			}
 			ctx.props = await decryptProps(await unwrapKeyWithToken(accessToken, tokenData.wrappedEncryptionKey), tokenData.grant.encryptedProps);
 		} else if (this.options.resolveExternalToken) {
@@ -950,16 +977,15 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				request,
 				env
 			});
-			if (!ext) return this.createErrorResponse("invalid_token", "Invalid access token", 401, { "WWW-Authenticate": "Bearer realm=\"OAuth\", error=\"invalid_token\"" });
+			if (!ext) return this.createErrorResponse("invalid_token", "Invalid access token", 401, { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") });
 			if (ext.audience) {
 				const requestUrl = new URL(request.url);
 				const resourceServer = `${requestUrl.protocol}//${requestUrl.host}${requestUrl.pathname}`;
-				if (!(Array.isArray(ext.audience) ? ext.audience : [ext.audience]).some((aud) => audienceMatches(resourceServer, aud))) return this.createErrorResponse("invalid_token", "Token audience does not match resource server", 401, { "WWW-Authenticate": "Bearer realm=\"OAuth\", error=\"invalid_token\", error_description=\"Invalid audience\"" });
+				if (!(Array.isArray(ext.audience) ? ext.audience : [ext.audience]).some((aud) => audienceMatches(resourceServer, aud))) return this.createErrorResponse("invalid_token", "Token audience does not match resource server", 401, { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token", "Invalid audience") });
 			}
 			ctx.props = ext.props;
 		}
 		if (!env.OAUTH_PROVIDER) env.OAUTH_PROVIDER = this.createOAuthHelpers(env);
-		const url = new URL(request.url);
 		const apiHandler = this.findApiHandlerForUrl(url);
 		if (!apiHandler) return this.createErrorResponse("invalid_request", "No handler found for API route", 404);
 		if (apiHandler.type === HandlerType.EXPORTED_HANDLER) return apiHandler.handler.fetch(request, env, ctx);
@@ -1183,6 +1209,14 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		return JSON.parse(text);
 	}
 	/**
+	* Builds a WWW-Authenticate header value with resource_metadata per RFC 9728 §5.1
+	*/
+	buildWwwAuthenticateHeader(resourceMetadataUrl, error, errorDescription) {
+		let header = `Bearer realm="OAuth", resource_metadata="${resourceMetadataUrl}", error="${error}"`;
+		if (errorDescription) header += `, error_description="${errorDescription}"`;
+		return header;
+	}
+	/**
 	* Helper function to create OAuth error responses
 	* @param code - OAuth error code (e.g., 'invalid_request', 'invalid_token')
 	* @param description - Human-readable error description
@@ -1338,6 +1372,37 @@ function validateRedirectUriScheme(redirectUri) {
 	for (const dangerousScheme of dangerousSchemes) if (scheme === dangerousScheme) throw new Error("Invalid redirect URI");
 }
 /**
+* Checks if a URI is a loopback redirect URI (127.0.0.0/8 or ::1)
+* Per RFC 8252 Section 7.3, these get special port handling
+*/
+function isLoopbackUri(uri) {
+	try {
+		const host = new URL(uri).hostname;
+		if (host.match(/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/)) return true;
+		if (host === "::1" || host === "[::1]") return true;
+		return false;
+	} catch {
+		return false;
+	}
+}
+/**
+* Validates a redirect URI against registered URIs with RFC 8252 loopback support.
+* For loopback URIs (127.x.x.x, ::1), any port is allowed as long as scheme, host, path, and query match.
+* For non-loopback URIs, exact match is required.
+*/
+function isValidRedirectUri(requestUri, registeredUris) {
+	return registeredUris.some((registered) => {
+		if (isLoopbackUri(requestUri) && isLoopbackUri(registered)) try {
+			const reqUrl = new URL(requestUri);
+			const regUrl = new URL(registered);
+			return reqUrl.protocol === regUrl.protocol && reqUrl.hostname === regUrl.hostname && reqUrl.pathname === regUrl.pathname && reqUrl.search === regUrl.search;
+		} catch {
+			return false;
+		}
+		return requestUri === registered;
+	});
+}
+/**
 * Encodes a string as base64url (URL-safe base64)
 * @param str - The string to encode
 * @returns The base64url encoded string
@@ -1506,11 +1571,12 @@ var OAuthHelpersImpl = class {
 		const resource = parseResourceParameter(resourceParam);
 		if (resourceParam && !resource) throw new Error("The resource parameter must be a valid absolute URI without a fragment");
 		if (responseType === "token" && !this.provider.options.allowImplicitFlow) throw new Error("The implicit grant flow is not enabled for this provider");
+		if (codeChallengeMethod === "plain" && this.provider.options.allowPlainPKCE === false) throw new Error("The plain PKCE method is not allowed. Use S256 instead.");
 		if (clientId) {
 			const clientInfo = await this.lookupClient(clientId);
 			if (!clientInfo) throw new Error(`Invalid client. The clientId provided does not match to this client.`);
 			if (clientInfo && redirectUri) {
-				if (!clientInfo.redirectUris.includes(redirectUri)) throw new Error(`Invalid redirect URI. The redirect URI provided does not match any registered URI for this client.`);
+				if (!isValidRedirectUri(redirectUri, clientInfo.redirectUris)) throw new Error(`Invalid redirect URI. The redirect URI provided does not match any registered URI for this client.`);
 			}
 		}
 		return {
@@ -1543,7 +1609,7 @@ var OAuthHelpersImpl = class {
 		const { clientId, redirectUri } = options.request;
 		if (!clientId || !redirectUri) throw new Error("Client ID and Redirect URI are required in the authorization request.");
 		const clientInfo = await this.lookupClient(clientId);
-		if (!clientInfo || !clientInfo.redirectUris.includes(redirectUri)) throw new Error("Invalid redirect URI. The redirect URI provided does not match any registered URI for this client.");
+		if (!clientInfo || !isValidRedirectUri(redirectUri, clientInfo.redirectUris)) throw new Error("Invalid redirect URI. The redirect URI provided does not match any registered URI for this client.");
 		const grantId = generateRandomString(16);
 		const { encryptedData, key: encryptionKey } = await encryptProps(options.props);
 		const now = Math.floor(Date.now() / 1e3);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/workers-oauth-provider",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "OAuth provider for Cloudflare Workers",
   "main": "dist/oauth-provider.js",
   "types": "dist/oauth-provider.d.ts",