@cloudflare/workers-oauth-provider 0.3.3 → 0.5.0

package/README.md

@@ -96,15 +96,21 @@ export default new OAuthProvider({
   disallowPublicClientRegistration: false,
 
   // Optional: Time-to-live for refresh tokens in seconds.
-  // If not specified, refresh tokens do not expire.
+  // Defaults to 30 days (2,592,000 seconds).
   // 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
+  // Set to `undefined` explicitly for refresh tokens that never expire.
+  refreshTokenTTL: 2592000, // 30 days (the default)
 
   // Optional: Time-to-live for access tokens in seconds.
   // Defaults to 1 hour (3600 seconds) if not specified.
   accessTokenTTL: 3600,
 
+  // Optional: Time-to-live for dynamically registered clients in seconds.
+  // Defaults to 90 days (7,776,000 seconds).
+  // Clients created via OAuthHelpers.createClient() are not affected.
+  // Set to `undefined` explicitly for clients that never expire.
+  clientRegistrationTTL: 7776000, // 90 days (the default)
+
   // 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.
@@ -226,6 +232,9 @@ The `env.OAUTH_PROVIDER` object available to the fetch handlers provides some me
 - Create, list, modify, and delete client_id registrations (in addition to `lookupClient()`, already shown in the example code).
 - List all active authorization grants for a particular user.
 - Revoke (delete) an authorization grant.
+- Purge expired and orphaned data from the KV namespace.
+
+Note that `deleteClient()` cascades: it revokes all grants (and their associated tokens) for the deleted client across all users.
 
 See the `OAuthHelpers` interface definition for full API details.
 
@@ -326,6 +335,33 @@ new OAuthProvider({
 
 By default, the `onError` callback is set to ``({ status, code, description }) => console.warn(`OAuth error response: ${status} ${code} - ${description}`)``.
 
+## KV Namespace Cleanup
+
+The library uses KV TTLs to automatically expire access tokens, refresh tokens (grants), and dynamically registered clients. As defense-in-depth, the library also provides a `purgeExpiredData()` method that cleans up orphaned and expired records. This is designed to be called from a [Cron Trigger](https://developers.cloudflare.com/workers/configuration/cron-triggers/) (scheduled handler):
+
+```ts
+const oauthProvider = new OAuthProvider({
+  // ... options ...
+});
+
+export default {
+  fetch(request, env, ctx) {
+    return oauthProvider.fetch(request, env, ctx);
+  },
+  async scheduled(event, env, ctx) {
+    const result = await oauthProvider.purgeExpiredData(env, { batchSize: 100 });
+    console.log(`Checked ${result.grantsChecked} grants, purged ${result.grantsPurged}`);
+  },
+};
+```
+
+The method processes records in configurable batches (default: 50) to stay within Cloudflare's subrequest limits. It performs two sweep phases:
+
+1. **Grant sweep**: Removes orphaned grants (whose client no longer exists) and expired grants.
+2. **Token sweep**: Removes orphaned tokens (whose grant no longer exists).
+
+Call it repeatedly via a cron trigger — deleted records disappear from KV, so subsequent invocations naturally process fresh records without needing a persisted cursor. The `result.done` field indicates whether the full key space was scanned in this invocation.
+
 ## 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:

package/dist/oauth-provider.d.ts

@@ -178,10 +178,20 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
   accessTokenTTL?: number;
   /**
    * Time-to-live for refresh tokens in seconds.
-   * If not specified, refresh tokens do not expire.
+   * Defaults to 30 days (2,592,000 seconds).
+   * Set to 0 to disable refresh tokens entirely.
+   * Set to `undefined` explicitly for refresh tokens that never expire.
    * For example: 3600 = 1 hour, 2592000 = 30 days
    */
   refreshTokenTTL?: number;
+  /**
+   * Time-to-live for dynamically registered clients in seconds.
+   * Defaults to 90 days (7,776,000 seconds).
+   * Clients created via the DCR endpoint will automatically expire after this duration.
+   * Clients created via `OAuthHelpers.createClient()` are not affected by this setting.
+   * Set to `undefined` explicitly for clients that never expire.
+   */
+  clientRegistrationTTL?: number;
   /**
    * List of scopes supported by this OAuth provider.
    * If not provided, the 'scopes_supported' field will be omitted from the OAuth metadata.
@@ -253,6 +263,16 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    * Defaults to false.
    */
   clientIdMetadataDocumentEnabled?: boolean;
+  /**
+   * When true, resource validation during token exchange compares origins only
+   * (scheme + host + port) instead of exact URI matching. This allows grants issued
+   * with an origin-only resource (e.g. `https://server.com`) to be used with
+   * path-aware resource requests (e.g. `https://server.com/mcp`), enabling seamless
+   * migration from pre-0.4.0 versions that stored origin-only resource URIs.
+   *
+   * Defaults to false (strict exact matching per RFC 8707).
+   */
+  resourceMatchOriginOnly?: boolean;
   /**
    * Optional metadata for RFC 9728 OAuth 2.0 Protected Resource Metadata.
    * Controls the response served at /.well-known/oauth-protected-resource.
@@ -365,6 +385,22 @@ interface OAuthHelpers {
    * @returns Promise resolving to token response with new access token
    */
   exchangeToken(options: ExchangeTokenOptions): Promise<TokenResponse>;
+  /**
+   * Purges expired and orphaned data from the KV namespace.
+   * Designed to be called from a scheduled handler (Cron Trigger) for periodic cleanup.
+   * Processes records in configurable batches to stay within Cloudflare's subrequest limits.
+   *
+   * Performs two sweep phases:
+   * 1. Grant sweep: removes orphaned grants (client deleted) and expired grants (defense-in-depth for KV TTL)
+   * 2. Token sweep: removes orphaned tokens (grant deleted) as defense-in-depth
+   *
+   * Safe to call repeatedly — deleted records disappear from KV, so subsequent invocations
+   * naturally process fresh records without needing a persisted cursor.
+   *
+   * @param options - Optional configuration for batch size and which purge types to enable
+   * @returns Statistics about what was checked and purged, and whether the full scan completed
+   */
+  purgeExpiredData(options?: PurgeOptions): Promise<PurgeResult>;
 }
 /**
  * Options for token exchange operations (RFC 8693)
@@ -732,6 +768,55 @@ interface ListResult<T> {
    */
   cursor?: string;
 }
+/**
+ * Options for the purgeExpiredData garbage collection method
+ */
+interface PurgeOptions {
+  /**
+   * Maximum number of KV keys to check per phase (grants and tokens) per invocation.
+   * Each phase (grant sweep, token sweep) gets its own budget of this size.
+   * Keep this conservative to stay within Cloudflare's 1000 subrequest limit per invocation,
+   * since each checked key requires at least one KV read, and orphaned grants trigger
+   * additional KV operations via revokeGrant().
+   * Defaults to 50.
+   */
+  batchSize?: number;
+  /**
+   * Whether to purge orphaned grants whose client no longer exists in KV.
+   * Grants for CIMD (Client ID Metadata Document) clients are always skipped
+   * since those clients are not stored in KV.
+   * Defaults to true.
+   */
+  purgeOrphanedGrants?: boolean;
+  /**
+   * Whether to purge expired grants as defense-in-depth for KV TTL.
+   * Normally KV auto-deletes expired entries, but this catches any stragglers.
+   * Defaults to true.
+   */
+  purgeExpiredGrants?: boolean;
+  /**
+   * Whether to purge orphaned tokens whose grant no longer exists.
+   * Tokens already auto-expire via KV TTL (default 1 hour), so this is
+   * defense-in-depth for partial revokeGrant() failures.
+   * Defaults to true.
+   */
+  purgeOrphanedTokens?: boolean;
+}
+/**
+ * Result of a purgeExpiredData garbage collection invocation
+ */
+interface PurgeResult {
+  /** Number of grant records checked in this invocation */
+  grantsChecked: number;
+  /** Number of grant records purged (orphaned or expired) */
+  grantsPurged: number;
+  /** Number of token records checked in this invocation */
+  tokensChecked: number;
+  /** Number of token records purged (orphaned) */
+  tokensPurged: number;
+  /** True if the full key space was scanned in this invocation (both grants and tokens) */
+  done: boolean;
+}
 /**
  * Public representation of a grant, with sensitive data removed
  * Used for list operations where the complete grant data isn't needed
@@ -787,6 +872,15 @@ declare class OAuthProvider<Env = Cloudflare.Env> {
    * @returns A Promise resolving to an HTTP Response
    */
   fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response>;
+  /**
+   * Purges expired and orphaned data from the KV namespace.
+   * Can be called directly from a scheduled handler without needing a request context.
+   *
+   * @param env - Cloudflare Worker environment variables (must include OAUTH_KV binding)
+   * @param options - Optional configuration for batch size and which purge types to enable
+   * @returns Statistics about what was checked and purged
+   */
+  purgeExpiredData(env: Env, options?: PurgeOptions): Promise<PurgeResult>;
 }
 /**
  * Gets OAuthHelpers for the given environment
@@ -796,4 +890,4 @@ declare class OAuthProvider<Env = Cloudflare.Env> {
  */
 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 };
+export { AuthRequest, ClientInfo, CompleteAuthorizationOptions, ExchangeTokenOptions, Grant, GrantSummary, GrantType, ListOptions, ListResult, OAuthHelpers, OAuthProvider, OAuthProvider as default, OAuthProviderOptions, PurgeOptions, PurgeResult, ResolveExternalTokenInput, ResolveExternalTokenResult, Token, TokenBase, TokenExchangeCallbackOptions, TokenExchangeCallbackResult, TokenSummary, getOAuthApi };

package/dist/oauth-provider.js

@@ -1,6 +1,7 @@
 import { WorkerEntrypoint } from "cloudflare:workers";
 
 //#region src/oauth-provider.ts
+const PROTECTED_RESOURCE_WELL_KNOWN_PREFIX = "/.well-known/oauth-protected-resource";
 if (!(typeof Cloudflare !== "undefined" && Cloudflare.compatibilityFlags?.global_fetch_strictly_public === true)) console.warn("CIMD (Client ID Metadata Document) is disabled: add '\"compatibility_flags\": [\"global_fetch_strictly_public\"]' to your wrangler.jsonc to enable. See: https://developers.cloudflare.com/workers/configuration/compatibility-flags/#global-fetch-strictly-public");
 /**
 * Enum representing the type of handler (ExportedHandler or WorkerEntrypoint)
@@ -44,6 +45,17 @@ var OAuthProvider = class {
 	fetch(request, env, ctx) {
 		return this.#impl.fetch(request, env, ctx);
 	}
+	/**
+	* Purges expired and orphaned data from the KV namespace.
+	* Can be called directly from a scheduled handler without needing a request context.
+	*
+	* @param env - Cloudflare Worker environment variables (must include OAUTH_KV binding)
+	* @param options - Optional configuration for batch size and which purge types to enable
+	* @returns Statistics about what was checked and purged
+	*/
+	purgeExpiredData(env, options) {
+		return this.#impl.createOAuthHelpers(env).purgeExpiredData(options);
+	}
 };
 /**
 * Gets OAuthHelpers for the given environment
@@ -93,6 +105,8 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		if (options.clientRegistrationEndpoint) this.validateEndpoint(options.clientRegistrationEndpoint, "clientRegistrationEndpoint");
 		this.options = {
 			accessTokenTTL: DEFAULT_ACCESS_TOKEN_TTL,
+			refreshTokenTTL: DEFAULT_REFRESH_TOKEN_TTL,
+			clientRegistrationTTL: DEFAULT_CLIENT_REGISTRATION_TTL,
 			onError: ({ status, code, description }) => console.warn(`OAuth error response: ${status} ${code} - ${description}`),
 			...options
 		};
@@ -141,7 +155,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" || url.pathname === "/.well-known/oauth-protected-resource" || 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" || this.isProtectedResourceMetadataRequest(url) || this.isTokenEndpoint(url) || this.options.clientRegistrationEndpoint && this.isClientRegistrationEndpoint(url)) return this.addCorsHeaders(new Response(null, {
 				status: 204,
 				headers: { "Content-Length": "0" }
 			}), request);
@@ -150,7 +164,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			const response = await this.handleMetadataDiscovery(url);
 			return this.addCorsHeaders(response, request);
 		}
-		if (url.pathname === "/.well-known/oauth-protected-resource") {
+		if (this.isProtectedResourceMetadataRequest(url)) {
 			const response = this.handleProtectedResourceMetadata(url);
 			return this.addCorsHeaders(response, request);
 		}
@@ -245,6 +259,27 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		return this.matchEndpoint(url, this.options.clientRegistrationEndpoint);
 	}
 	/**
+	* Checks if a URL is a request for OAuth Protected Resource Metadata (RFC 9728).
+	* Matches both the root well-known path and path-suffixed variants per RFC 9728 §3.1.
+	*/
+	isProtectedResourceMetadataRequest(url) {
+		return url.pathname === PROTECTED_RESOURCE_WELL_KNOWN_PREFIX || url.pathname.startsWith(PROTECTED_RESOURCE_WELL_KNOWN_PREFIX + "/");
+	}
+	/**
+	* Derives the resource identifier from a protected resource metadata well-known URL.
+	* Per RFC 9728 §3.1, the well-known URI is inserted after the authority and before the path,
+	* so the resource identifier is reconstructed by removing the well-known prefix.
+	*
+	* Examples:
+	*   /.well-known/oauth-protected-resource       → origin (e.g. https://example.com)
+	*   /.well-known/oauth-protected-resource/mcp   → origin + /mcp (e.g. https://example.com/mcp)
+	*/
+	deriveResourceIdentifier(requestUrl) {
+		const suffix = requestUrl.pathname.slice(37);
+		if (!suffix || suffix === "/") return requestUrl.origin;
+		return `${requestUrl.origin}${suffix}`;
+	}
+	/**
 	* Parses and validates a token endpoint request (used for both token exchange and revocation)
 	* @param request - The HTTP request to parse
 	* @returns Promise with parsed body and client info, or error response
@@ -389,7 +424,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		const tokenEndpointUrl = this.getFullEndpointUrl(this.options.tokenEndpoint, requestUrl);
 		const authServerOrigin = new URL(tokenEndpointUrl).origin;
 		const metadata = {
-			resource: rm?.resource ?? requestUrl.origin,
+			resource: rm?.resource ?? this.deriveResourceIdentifier(requestUrl),
 			authorization_servers: rm?.authorization_servers ?? [authServerOrigin],
 			scopes_supported: rm?.scopes_supported ?? this.options.scopesSupported,
 			bearer_methods_supported: rm?.bearer_methods_supported ?? ["header"]
@@ -515,10 +550,11 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			grantData.expiresAt = expiresAt;
 		}
 		await this.saveGrantWithTTL(env, grantKey, grantData, now);
+		const originOnly = !!this.options.resourceMatchOriginOnly;
 		if (body.resource && grantData.resource) {
 			const requestedResources = Array.isArray(body.resource) ? body.resource : [body.resource];
 			const grantedResources = Array.isArray(grantData.resource) ? grantData.resource : [grantData.resource];
-			for (const requested of requestedResources) if (!grantedResources.includes(requested)) return this.createErrorResponse("invalid_target", "Requested resource was not included in the authorization request");
+			for (const requested of requestedResources) if (!grantedResources.some((granted) => resourceMatches(requested, granted, originOnly))) return this.createErrorResponse("invalid_target", "Requested resource was not included in the authorization request");
 		}
 		const audience = parseResourceParameter(body.resource || grantData.resource);
 		if ((body.resource || grantData.resource) && !audience) return this.createErrorResponse("invalid_target", "The resource parameter must be a valid absolute URI without a fragment");
@@ -635,10 +671,11 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		grantData.refreshTokenId = newRefreshTokenId;
 		grantData.refreshTokenWrappedKey = newRefreshTokenWrappedKey;
 		await this.saveGrantWithTTL(env, grantKey, grantData, now);
+		const originOnly = !!this.options.resourceMatchOriginOnly;
 		if (body.resource && grantData.resource) {
 			const requestedResources = Array.isArray(body.resource) ? body.resource : [body.resource];
 			const grantedResources = Array.isArray(grantData.resource) ? grantData.resource : [grantData.resource];
-			for (const requested of requestedResources) if (!grantedResources.includes(requested)) return this.createErrorResponse("invalid_target", "Requested resource was not included in the authorization request");
+			for (const requested of requestedResources) if (!grantedResources.some((granted) => resourceMatches(requested, granted, originOnly))) return this.createErrorResponse("invalid_target", "Requested resource was not included in the authorization request");
 		}
 		const audience = parseResourceParameter(body.resource || grantData.resource);
 		if ((body.resource || grantData.resource) && !audience) return this.createErrorResponse("invalid_target", "The resource parameter must be a valid absolute URI without a fragment");
@@ -690,12 +727,13 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		const grantData = await env.OAUTH_KV.get(grantKey, { type: "json" });
 		if (!grantData) throw new OAuthError("invalid_grant", "Grant not found");
 		let tokenScopes = this.downscope(requestedScopes, grantData.scope);
+		const originOnly = !!this.options.resourceMatchOriginOnly;
 		let newAudience = tokenSummary.audience;
 		if (requestedResource) {
 			if (grantData.resource) {
 				const requestedResources = Array.isArray(requestedResource) ? requestedResource : [requestedResource];
 				const grantedResources = Array.isArray(grantData.resource) ? grantData.resource : [grantData.resource];
-				for (const requested of requestedResources) if (!grantedResources.includes(requested)) throw new OAuthError("invalid_target", "Requested resource was not included in the authorization request");
+				for (const requested of requestedResources) if (!grantedResources.some((granted) => resourceMatches(requested, granted, originOnly))) throw new OAuthError("invalid_target", "Requested resource was not included in the authorization request");
 			}
 			const parsedResource = parseResourceParameter(requestedResource);
 			if (!parsedResource) throw new OAuthError("invalid_target", "The resource parameter must be a valid absolute URI without a fragment");
@@ -920,7 +958,9 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		} catch (error) {
 			return this.createErrorResponse("invalid_client_metadata", error instanceof Error ? error.message : "Invalid client metadata");
 		}
-		await env.OAUTH_KV.put(`client:${clientId}`, JSON.stringify(clientInfo));
+		const clientKvOptions = {};
+		if (this.options.clientRegistrationTTL !== void 0) clientKvOptions.expirationTtl = this.options.clientRegistrationTTL;
+		await env.OAUTH_KV.put(`client:${clientId}`, JSON.stringify(clientInfo), clientKvOptions);
 		const response = {
 			client_id: clientInfo.clientId,
 			redirect_uris: clientInfo.redirectUris,
@@ -939,7 +979,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		};
 		if (clientSecret) {
 			response.client_secret = clientSecret;
-			response.client_secret_expires_at = 0;
+			response.client_secret_expires_at = this.options.clientRegistrationTTL && clientInfo.registrationDate ? clientInfo.registrationDate + this.options.clientRegistrationTTL : 0;
 			response.client_secret_issued_at = clientInfo.registrationDate;
 		}
 		return new Response(JSON.stringify(response), {
@@ -956,7 +996,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	*/
 	async handleApiRequest(request, env, ctx) {
 		const url = new URL(request.url);
-		const resourceMetadataUrl = `${url.origin}/.well-known/oauth-protected-resource`;
+		const resourceMetadataUrl = `${url.origin}/.well-known/oauth-protected-resource${url.pathname}`;
 		const authHeader = request.headers.get("Authorization");
 		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);
@@ -1098,7 +1138,8 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		return !!(typeof Cloudflare !== "undefined" && Cloudflare.compatibilityFlags ? Cloudflare.compatibilityFlags : null)?.global_fetch_strictly_public;
 	}
 	/**
-	* Checks if a client_id is a CIMD URL (HTTPS with non-root path)
+	* Checks if a client_id is a CIMD URL (HTTPS with non-root path).
+	* Not private because OAuthHelpersImpl needs access for purgeExpiredData.
 	*/
 	isClientMetadataUrl(clientId) {
 		try {
@@ -1279,6 +1320,19 @@ var OAuthError = class extends Error {
 */
 const DEFAULT_ACCESS_TOKEN_TTL = 3600;
 /**
+* Default expiration time for refresh tokens (30 days in seconds)
+*/
+const DEFAULT_REFRESH_TOKEN_TTL = 720 * 60 * 60;
+/**
+* Default expiration time for dynamically registered clients (90 days in seconds)
+*/
+const DEFAULT_CLIENT_REGISTRATION_TTL = 2160 * 60 * 60;
+/**
+* Default batch size for purgeExpiredData. Conservative to stay within
+* Cloudflare's 1000 subrequest limit per invocation.
+*/
+const DEFAULT_PURGE_BATCH_SIZE = 50;
+/**
 * Length of generated token strings
 */
 const TOKEN_LENGTH = 32;
@@ -1331,6 +1385,19 @@ function parseResourceParameter(value) {
 	return value;
 }
 /**
+* Checks if a requested resource matches a granted resource.
+* When originOnly is true, compares only the origin (scheme + host + port),
+* allowing path-aware resources to match origin-only grants.
+*/
+function resourceMatches(requested, granted, originOnly) {
+	if (!originOnly) return requested === granted;
+	try {
+		return new URL(requested).origin === new URL(granted).origin;
+	} catch {
+		return requested === granted;
+	}
+}
+/**
 * Hashes a secret value using SHA-256
 * @param secret - The secret value to hash
 * @returns A hex string representation of the hash
@@ -1808,17 +1875,32 @@ var OAuthHelpersImpl = class {
 		};
 		if (!isPublicClient && secretToStore) updatedClient.clientSecret = secretToStore;
 		else delete updatedClient.clientSecret;
-		await this.env.OAUTH_KV.put(`client:${clientId}`, JSON.stringify(updatedClient));
+		const clientKvOptions = {};
+		if (this.provider.options.clientRegistrationTTL !== void 0) clientKvOptions.expirationTtl = this.provider.options.clientRegistrationTTL;
+		await this.env.OAUTH_KV.put(`client:${clientId}`, JSON.stringify(updatedClient), clientKvOptions);
 		const response = { ...updatedClient };
 		if (!isPublicClient && originalSecret) response.clientSecret = originalSecret;
 		return response;
 	}
 	/**
-	* Deletes an OAuth client
+	* Deletes an OAuth client and revokes all associated grants across all users.
 	* @param clientId - The ID of the client to delete
 	* @returns A Promise resolving when the deletion is confirmed.
 	*/
 	async deleteClient(clientId) {
+		let cursor;
+		let allProcessed = false;
+		while (!allProcessed) {
+			const listOptions = { prefix: "grant:" };
+			if (cursor) listOptions.cursor = cursor;
+			const result = await this.env.OAUTH_KV.list(listOptions);
+			for (const key of result.keys) {
+				const grantData = await this.env.OAUTH_KV.get(key.name, { type: "json" });
+				if (grantData && grantData.clientId === clientId) await this.revokeGrant(grantData.id, grantData.userId);
+			}
+			if (result.list_complete) allProcessed = true;
+			else cursor = result.cursor;
+		}
 		await this.env.OAUTH_KV.delete(`client:${clientId}`);
 	}
 	/**
@@ -1899,6 +1981,92 @@ var OAuthHelpersImpl = class {
 		if (!clientInfo) throw new Error("Client not found");
 		return await this.provider.exchangeToken(options.subjectToken, options.scope, options.aud, options.expiresIn, clientInfo, this.env);
 	}
+	async purgeExpiredData(options) {
+		const batchSize = options?.batchSize ?? DEFAULT_PURGE_BATCH_SIZE;
+		const purgeOrphanedGrants = options?.purgeOrphanedGrants !== false;
+		const purgeExpiredGrants = options?.purgeExpiredGrants !== false;
+		const purgeOrphanedTokens = options?.purgeOrphanedTokens !== false;
+		const now = Math.floor(Date.now() / 1e3);
+		const result = {
+			grantsChecked: 0,
+			grantsPurged: 0,
+			tokensChecked: 0,
+			tokensPurged: 0,
+			done: false
+		};
+		if (purgeOrphanedGrants || purgeExpiredGrants) {
+			const knownGoodClients = /* @__PURE__ */ new Set();
+			const knownMissingClients = /* @__PURE__ */ new Set();
+			let grantCursor;
+			let grantsDone = false;
+			while (!grantsDone && result.grantsChecked < batchSize) {
+				const listOptions = {
+					prefix: "grant:",
+					limit: Math.min(1e3, batchSize - result.grantsChecked)
+				};
+				if (grantCursor) listOptions.cursor = grantCursor;
+				const page = await this.env.OAUTH_KV.list(listOptions);
+				for (const key of page.keys) {
+					if (result.grantsChecked >= batchSize) break;
+					result.grantsChecked++;
+					const grantData = await this.env.OAUTH_KV.get(key.name, { type: "json" });
+					if (!grantData) continue;
+					let shouldPurge = false;
+					if (purgeExpiredGrants && grantData.expiresAt !== void 0 && now >= grantData.expiresAt) shouldPurge = true;
+					if (!shouldPurge && purgeOrphanedGrants && !this.provider.isClientMetadataUrl(grantData.clientId)) {
+						if (knownMissingClients.has(grantData.clientId)) shouldPurge = true;
+						else if (!knownGoodClients.has(grantData.clientId)) if (await this.env.OAUTH_KV.get(`client:${grantData.clientId}`, { type: "json" })) knownGoodClients.add(grantData.clientId);
+						else {
+							knownMissingClients.add(grantData.clientId);
+							shouldPurge = true;
+						}
+					}
+					if (shouldPurge) {
+						await this.revokeGrant(grantData.id, grantData.userId);
+						result.grantsPurged++;
+					}
+				}
+				if (page.list_complete) grantsDone = true;
+				else grantCursor = page.cursor;
+			}
+			if (!grantsDone) return result;
+		}
+		if (purgeOrphanedTokens) {
+			const knownGoodGrants = /* @__PURE__ */ new Set();
+			const knownMissingGrants = /* @__PURE__ */ new Set();
+			let tokenCursor;
+			let tokensDone = false;
+			while (!tokensDone && result.tokensChecked < batchSize) {
+				const listOptions = {
+					prefix: "token:",
+					limit: Math.min(1e3, batchSize - result.tokensChecked)
+				};
+				if (tokenCursor) listOptions.cursor = tokenCursor;
+				const page = await this.env.OAUTH_KV.list(listOptions);
+				for (const key of page.keys) {
+					if (result.tokensChecked >= batchSize) break;
+					result.tokensChecked++;
+					const tokenData = await this.env.OAUTH_KV.get(key.name, { type: "json" });
+					if (!tokenData) continue;
+					const grantKey = `grant:${tokenData.userId}:${tokenData.grantId}`;
+					if (knownMissingGrants.has(grantKey)) {
+						await this.env.OAUTH_KV.delete(key.name);
+						result.tokensPurged++;
+					} else if (!knownGoodGrants.has(grantKey)) if (await this.env.OAUTH_KV.get(grantKey)) knownGoodGrants.add(grantKey);
+					else {
+						knownMissingGrants.add(grantKey);
+						await this.env.OAUTH_KV.delete(key.name);
+						result.tokensPurged++;
+					}
+				}
+				if (page.list_complete) tokensDone = true;
+				else tokenCursor = page.cursor;
+			}
+			if (!tokensDone) return result;
+		}
+		result.done = true;
+		return result;
+	}
 };
 /**
 * Default export of the OAuth provider

package/package.json

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