@cloudflare/workers-oauth-provider 0.4.0 → 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.
@@ -375,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)
@@ -742,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
@@ -797,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
@@ -806,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

@@ -45,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
@@ -94,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
 		};
@@ -945,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,
@@ -964,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), {
@@ -1123,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 {
@@ -1304,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;
@@ -1846,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}`);
 	}
 	/**
@@ -1937,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.4.0",
+  "version": "0.5.0",
   "description": "OAuth provider for Cloudflare Workers",
   "main": "dist/oauth-provider.js",
   "types": "dist/oauth-provider.d.ts",