@cloudflare/workers-oauth-provider 0.2.3 → 0.3.0

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.
@@ -94,6 +100,22 @@ export default new OAuthProvider({
   // Set to 0 to disable refresh tokens (only access tokens will be issued).
   // For example: 3600 = 1 hour, 86400 = 1 day, 2592000 = 30 days
   refreshTokenTTL: 2592000, // 30 days
+
+  // Optional: Time-to-live for access tokens in seconds.
+  // Defaults to 1 hour (3600 seconds) if not specified.
+  accessTokenTTL: 3600,
+
+  // Optional: Controls whether OAuth 2.0 Token Exchange (RFC 8693) is allowed.
+  // When false, the token exchange grant type will not be advertised in metadata
+  // and token exchange requests will be rejected.
+  // Defaults to false.
+  allowTokenExchangeGrant: false,
+
+  // Optional: Explicitly enable Client ID Metadata Document (CIMD) support.
+  // When true, URL-formatted client_ids will be fetched as metadata documents.
+  // Requires the 'global_fetch_strictly_public' compatibility flag.
+  // See the CIMD section below for details. Defaults to false.
+  clientIdMetadataDocumentEnabled: false,
 });
 
 // The default handler object - the OAuthProvider will pass through HTTP requests to this object's fetch method
@@ -304,6 +326,35 @@ new OAuthProvider({
 
 By default, the `onError` callback is set to ``({ status, code, description }) => console.warn(`OAuth error response: ${status} ${code} - ${description}`)``.
 
+## Protected Resource Metadata (RFC 9728)
+
+The library automatically serves a `/.well-known/oauth-protected-resource` endpoint. By default, it uses the request origin as the resource identifier and the token endpoint's origin as the authorization server. You can customize this with the `resourceMetadata` option:
+
+```ts
+new OAuthProvider({
+  // ... other options ...
+  resourceMetadata: {
+    resource: 'https://api.example.com',
+    authorization_servers: ['https://auth.example.com'],
+    scopes_supported: ['read', 'write'],
+    bearer_methods_supported: ['header'],
+    resource_name: 'My API',
+  },
+});
+```
+
+## 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
@@ -325,11 +376,22 @@ This library implements a compromise: At any particular time, a grant may have t
 
 ## Client ID Metadata Document (CIMD) Support
 
-This library supports [Client ID Metadata Documents](https://www.ietf.org/archive/id/draft-parecki-oauth-client-id-metadata-document-03.html), which allow clients to use HTTPS URLs as their `client_id`. When a client presents an HTTPS URL with a non-root path as its `client_id`, the library will fetch and validate the metadata document from that URL.
+This library supports [Client ID Metadata Documents](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document), which allow clients to use HTTPS URLs as their `client_id`. When a client presents an HTTPS URL with a non-root path as its `client_id`, the library will fetch and validate the metadata document from that URL.
 
 ### Enabling CIMD
 
-To enable CIMD support, you must add the `global_fetch_strictly_public` compatibility flag to your `wrangler.jsonc`:
+CIMD support is opt-in and requires two things:
+
+1. Set `clientIdMetadataDocumentEnabled: true` in your OAuthProvider options:
+
+```ts
+new OAuthProvider({
+  // ... other options ...
+  clientIdMetadataDocumentEnabled: true,
+});
+```
+
+2. Add the `global_fetch_strictly_public` compatibility flag to your `wrangler.jsonc`:
 
 ```jsonc
 {
@@ -337,9 +399,11 @@ To enable CIMD support, you must add the `global_fetch_strictly_public` compatib
 }
 ```
 
-This flag is required for SSRF (Server-Side Request Forgery) protection. Due to a legacy quirk, `fetch()` requests to URLs within your zone's domain are sent directly to the origin server, bypassing Cloudflare. The `global_fetch_strictly_public` flag disables this behavior. See [Cloudflare's blog post](https://blog.cloudflare.com/workers-environment-live-object-bindings/) and [documentation](https://developers.cloudflare.com/workers/configuration/compatibility-flags/#global-fetch-strictly-public) for more details.
+The compatibility flag is required for SSRF (Server-Side Request Forgery) protection. Due to a legacy quirk, `fetch()` requests to URLs within your zone's domain are sent directly to the origin server, bypassing Cloudflare. The `global_fetch_strictly_public` flag disables this behavior. See [Cloudflare's documentation](https://developers.cloudflare.com/workers/configuration/compatibility-flags/#global-fetch-strictly-public) for more details.
+
+When CIMD is not enabled (the default), URL-formatted `client_id` values fall through to standard KV lookup. When enabled, if fetching the metadata document fails, the library logs a warning and returns an `invalid_client` error, allowing MCP clients to recover by falling back to Dynamic Client Registration.
 
-When this flag is not enabled, the OAuth metadata endpoint will report `client_id_metadata_document_supported: false` and MCP Clients should use DCR instead.
+The OAuth metadata endpoint reports `client_id_metadata_document_supported: true` only when both the option is enabled and the compatibility flag is present.
 
 ## Written using Claude
 

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,47 @@ interface OAuthProviderOptions {
     status: number;
     headers: Record<string, string>;
   }) => Response | void;
+  /**
+   * Explicitly enable Client ID Metadata Document (CIMD) support.
+   * When true, URL-formatted client_ids will be fetched as metadata documents.
+   * Requires the 'global_fetch_strictly_public' compatibility flag.
+   * Defaults to false.
+   */
+  clientIdMetadataDocumentEnabled?: boolean;
+  /**
+   * 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
@@ -467,6 +517,13 @@ interface CompleteAuthorizationOptions {
    * authorized by this grant
    */
   props: any;
+  /**
+   * Revokes all existing grants for this user+client combination
+   * after storing the new grant. Defaults to true. This prevents stale
+   * tokens from causing infinite re-auth loops when props change.
+   * Set to false to allow multiple concurrent grants per user+client.
+   */
+  revokeExistingGrants?: boolean;
 }
 /**
  * Authorization grant record
@@ -714,13 +771,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 +786,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 +794,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,9 +373,28 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				"none"
 			],
 			revocation_endpoint: tokenEndpoint,
-			code_challenge_methods_supported: ["plain", "S256"],
-			client_id_metadata_document_supported: this.hasGlobalFetchStrictlyPublic()
+			code_challenge_methods_supported: this.options.allowPlainPKCE !== false ? ["plain", "S256"] : ["S256"],
+			client_id_metadata_document_supported: !!this.options.clientIdMetadataDocumentEnabled && 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" } });
 	}
 	/**
@@ -406,12 +431,17 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		const grantKey = `grant:${userId}:${grantId}`;
 		const grantData = await env.OAUTH_KV.get(grantKey, { type: "json" });
 		if (!grantData) return this.createErrorResponse("invalid_grant", "Grant not found or authorization code expired");
-		if (!grantData.authCodeId) return this.createErrorResponse("invalid_grant", "Authorization code already used");
+		if (!grantData.authCodeId) {
+			try {
+				await this.createOAuthHelpers(env).revokeGrant(grantId, userId);
+			} catch {}
+			return this.createErrorResponse("invalid_grant", "Authorization code already used");
+		}
 		if (await hashSecret(code) !== grantData.authCodeId) return this.createErrorResponse("invalid_grant", "Invalid authorization code");
 		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");
@@ -907,7 +937,11 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			registration_client_uri: `${this.options.clientRegistrationEndpoint}/${clientId}`,
 			client_id_issued_at: clientInfo.registrationDate
 		};
-		if (clientSecret) response.client_secret = clientSecret;
+		if (clientSecret) {
+			response.client_secret = clientSecret;
+			response.client_secret_expires_at = 0;
+			response.client_secret_issued_at = clientInfo.registrationDate;
+		}
 		return new Response(JSON.stringify(response), {
 			status: 201,
 			headers: { "Content-Type": "application/json" }
@@ -921,8 +955,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 +970,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 +986,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);
@@ -1000,8 +1035,17 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	*/
 	async getClient(env, clientId) {
 		if (this.isClientMetadataUrl(clientId)) {
-			if (!this.hasGlobalFetchStrictlyPublic()) throw new Error(`Client ID "${clientId}" appears to be a CIMD URL, but the 'global_fetch_strictly_public' compatibility flag is not enabled. Add this flag to your wrangler.jsonc to enable CIMD support.`);
-			return this.fetchClientMetadataDocument(clientId);
+			if (!this.options.clientIdMetadataDocumentEnabled) {
+				const clientKey$1 = `client:${clientId}`;
+				return env.OAUTH_KV.get(clientKey$1, { type: "json" });
+			}
+			if (!this.hasGlobalFetchStrictlyPublic()) throw new Error(`CIMD is enabled but 'global_fetch_strictly_public' compatibility flag is not set.`);
+			try {
+				return await this.fetchClientMetadataDocument(clientId);
+			} catch (error) {
+				console.warn(`CIMD fetch failed for ${clientId}:`, error instanceof Error ? error.message : error);
+				return null;
+			}
 		}
 		const clientKey = `client:${clientId}`;
 		return env.OAUTH_KV.get(clientKey, { type: "json" });
@@ -1183,6 +1227,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 +1390,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 +1589,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 +1627,16 @@ 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.");
+		let grantsToRevoke = [];
+		if (options.revokeExistingGrants !== false) {
+			let cursor;
+			do {
+				const page = await this.listUserGrants(options.userId, { cursor });
+				for (const grant of page.items) if (grant.clientId === clientId) grantsToRevoke.push(grant.id);
+				cursor = page.cursor;
+			} while (cursor);
+		}
 		const grantId = generateRandomString(16);
 		const { encryptedData, key: encryptionKey } = await encryptProps(options.props);
 		const now = Math.floor(Date.now() / 1e3);
@@ -1592,6 +1685,9 @@ var OAuthHelpersImpl = class {
 			fragment.set("scope", options.scope.join(" "));
 			if (options.request.state) fragment.set("state", options.request.state);
 			redirectUrl.hash = fragment.toString();
+			try {
+				await Promise.allSettled(grantsToRevoke.map((oldGrantId) => this.revokeGrant(oldGrantId, options.userId)));
+			} catch {}
 			return { redirectTo: redirectUrl.toString() };
 		} else {
 			const authCodeSecret = generateRandomString(32);
@@ -1617,6 +1713,9 @@ var OAuthHelpersImpl = class {
 			const redirectUrl = new URL(options.request.redirectUri);
 			redirectUrl.searchParams.set("code", authCode);
 			if (options.request.state) redirectUrl.searchParams.set("state", options.request.state);
+			try {
+				await Promise.allSettled(grantsToRevoke.map((oldGrantId) => this.revokeGrant(oldGrantId, options.userId)));
+			} catch {}
 			return { redirectTo: redirectUrl.toString() };
 		}
 	}

package/package.json

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