@cloudflare/workers-oauth-provider 0.2.4 → 0.3.1

package/README.md

@@ -100,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
@@ -310,6 +326,23 @@ 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:
@@ -343,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
 {
@@ -355,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

@@ -246,6 +246,13 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
     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.
@@ -510,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

package/dist/oauth-provider.js

@@ -374,7 +374,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			],
 			revocation_endpoint: tokenEndpoint,
 			code_challenge_methods_supported: this.options.allowPlainPKCE !== false ? ["plain", "S256"] : ["S256"],
-			client_id_metadata_document_supported: this.hasGlobalFetchStrictlyPublic()
+			client_id_metadata_document_supported: !!this.options.clientIdMetadataDocumentEnabled && this.hasGlobalFetchStrictlyPublic()
 		};
 		return new Response(JSON.stringify(metadata), { headers: { "Content-Type": "application/json" } });
 	}
@@ -431,7 +431,12 @@ 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;
@@ -932,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" }
@@ -1026,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" });
@@ -1372,14 +1390,16 @@ 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
+* Checks if a URI is a loopback redirect URI (127.0.0.0/8, ::1, or localhost).
+* Per RFC 8252 Section 7.3, loopback IPs get special port handling. This library
+* applies the same port flexibility to localhost for native apps (e.g., Claude Code).
 */
 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;
+		if (host.toLowerCase() === "localhost") return true;
 		return false;
 	} catch {
 		return false;
@@ -1387,7 +1407,7 @@ function isLoopbackUri(uri) {
 }
 /**
 * 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 loopback URIs (127.x.x.x, ::1, localhost), 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) {
@@ -1610,6 +1630,15 @@ var OAuthHelpersImpl = class {
 		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 || !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);
@@ -1658,6 +1687,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);
@@ -1683,6 +1715,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.4",
+  "version": "0.3.1",
   "description": "OAuth provider for Cloudflare Workers",
   "main": "dist/oauth-provider.js",
   "types": "dist/oauth-provider.d.ts",