@cloudflare/workers-oauth-provider 0.4.0 → 0.6.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.
 
@@ -297,6 +306,52 @@ The `accessTokenTTL` override is particularly useful when the application is als
 
 The `props` values are end-to-end encrypted, so they can safely contain sensitive information.
 
+### Reporting errors from the callback
+
+Throw `OAuthError` from `tokenExchangeCallback` to return a structured OAuth `/token` error (`{ error, error_description }`) instead of a generic 500:
+
+```ts
+import { OAuthError, OAuthProvider } from '@cloudflare/workers-oauth-provider';
+
+new OAuthProvider({
+  // …
+  tokenExchangeCallback: async (options) => {
+    if (options.grantType === 'refresh_token') {
+      return { newProps: await refreshUpstream(options.props) };
+    }
+  },
+});
+
+async function refreshUpstream(props) {
+  const res = await fetch(/* upstream token endpoint */);
+
+  if (res.status === 401) {
+    throw new OAuthError('invalid_grant', {
+      description: 'upstream refresh token is invalid',
+    });
+  }
+
+  if (res.status === 429) {
+    throw new OAuthError('temporarily_unavailable', {
+      description: 'upstream rate limited',
+      statusCode: 429,
+      headers: { 'Retry-After': res.headers.get('retry-after') ?? '60' },
+    });
+  }
+
+  return await res.json();
+}
+```
+
+`OAuthError(code, options)` takes:
+
+- `code` — OAuth error code returned in the `error` field. This may be a standard code (`OAuthTokenErrorCode`) or an application-defined string.
+- `options.description` — human-readable text returned in `error_description`.
+- `options.statusCode` — HTTP status code (default `400`).
+- `options.headers` — additional response headers, such as `Retry-After` for transient failures. There is no implicit `Retry-After` default for callback-thrown errors.
+
+Only `OAuthError` from this package is converted into a structured `/token` response. Plain errors, plain objects with a `code` field, and app-local error classes continue to surface as 500s so unexpected failures stay visible. Import `OAuthError` from `@cloudflare/workers-oauth-provider` rather than copying or re-implementing it.
+
 ## Custom Error Responses
 
 By using the `onError` option, you can emit notifications or take other actions when an error response was to be emitted:
@@ -326,6 +381,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

@@ -20,6 +20,16 @@ type WorkerEntrypointWithFetch<Env = Cloudflare.Env> = WorkerEntrypoint<Env> & {
 /**
  * Configuration options for the OAuth Provider
  */
+/**
+ * Registered OAuth 2.0 error codes that the `/token` endpoint may return.
+ *
+ * Union of:
+ *   - RFC 6749 §5.2 (token endpoint)
+ *   - RFC 6750 §3.1 (bearer / resource server) — included so callbacks
+ *     doing audience validation can use them
+ *   - RFC 8693 §2.2.2 (token exchange)
+ */
+type OAuthTokenErrorCode = 'invalid_request' | 'invalid_client' | 'invalid_grant' | 'unauthorized_client' | 'unsupported_grant_type' | 'invalid_scope' | 'invalid_token' | 'insufficient_scope' | 'invalid_target' | 'server_error' | 'temporarily_unavailable';
 /**
  * Result of a token exchange callback function.
  * Allows updating the props stored in both the access token and the grant.
@@ -178,10 +188,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 +395,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 +778,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 +882,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
@@ -805,5 +899,86 @@ declare class OAuthProvider<Env = Cloudflare.Env> {
  * @returns An instance of OAuthHelpers
  */
 declare function getOAuthApi<Env = Cloudflare.Env>(options: OAuthProviderOptions<Env>, env: Env): OAuthHelpers;
+/**
+ * Error class for OAuth operations
+ * Carries OAuth error code and description for proper error responses
+ */
+/**
+ * Options accepted by the {@link OAuthError} constructor.
+ */
+interface OAuthErrorOptions {
+  /**
+   * Human-readable text returned in the `error_description` field.
+   */
+  description: string;
+  /**
+   * HTTP status code for the error response. Defaults to `400`.
+   */
+  statusCode?: number;
+  /**
+   * Additional response headers.
+   *
+   * For transient failures (e.g. upstream rate limits), set
+   * `Retry-After` here so well-behaved clients back off instead of
+   * retry-storming. Per RFC 7231 §7.1.3 the value may be either a
+   * number of seconds or an HTTP-date.
+   */
+  headers?: Record<string, string>;
+}
+/**
+ * Structured OAuth 2.0 error.
+ *
+ * Throw from a `tokenExchangeCallback` (or any code it calls — the error
+ * propagates naturally up through deep call stacks) to surface a standard
+ * `/token` error response (`{ error, error_description }`) instead of a
+ * generic `500 Internal Server Error`.
+ *
+ * Anything thrown that is **not** an `OAuthError` continues to surface as
+ * a 500 so unexpected failures remain visible — the provider does not
+ * catch-everything-and-return-400.
+ *
+ * @example
+ * ```ts
+ * import { OAuthError } from '@cloudflare/workers-oauth-provider';
+ *
+ * tokenExchangeCallback: async (options) => {
+ *   if (options.grantType === 'refresh_token') {
+ *     // refreshUpstream() may throw OAuthError from any depth
+ *     return { newProps: await refreshUpstream(options.props) };
+ *   }
+ * }
+ *
+ * async function refreshUpstream(props) {
+ *   const res = await fetch(...);
+ *   if (res.status === 401) {
+ *     throw new OAuthError('invalid_grant', { description: 'upstream refresh token is invalid' });
+ *   }
+ *   if (res.status === 429) {
+ *     // Mirror upstream's Retry-After if present, otherwise pick a default.
+ *     throw new OAuthError('temporarily_unavailable', {
+ *       description: 'upstream rate limited',
+ *       statusCode: 429,
+ *       headers: { 'Retry-After': res.headers.get('retry-after') ?? '60' },
+ *     });
+ *   }
+ *   return await res.json();
+ * }
+ * ```
+ */
+declare class OAuthError extends Error {
+  /** OAuth 2.0 error code. */
+  readonly code: string;
+  /** Options controlling the OAuth error response. */
+  readonly options: OAuthErrorOptions & {
+    statusCode: number;
+  };
+  /** Human-readable description sent in the `error_description` field. */
+  readonly description: string;
+  /** HTTP status code for the error response. */
+  readonly statusCode: number;
+  /** Additional response headers. */
+  readonly headers?: Record<string, string>;
+  constructor(code: string, options: OAuthErrorOptions);
+}
 //#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, OAuthError, OAuthErrorOptions, OAuthHelpers, OAuthProvider, OAuthProvider as default, OAuthProviderOptions, OAuthTokenErrorCode, 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
 		};
@@ -272,10 +285,16 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	* @returns Promise with parsed body and client info, or error response
 	*/
 	async parseTokenEndpointRequest(request, env) {
-		if (request.method !== "POST") return this.createErrorResponse("invalid_request", "Method not allowed", 405);
+		if (request.method !== "POST") return this.createErrorResponse("invalid_request", {
+			description: "Method not allowed",
+			statusCode: 405
+		});
 		let contentType = request.headers.get("Content-Type") || "";
 		let body = {};
-		if (!contentType.includes("application/x-www-form-urlencoded")) return this.createErrorResponse("invalid_request", "Content-Type must be application/x-www-form-urlencoded", 400);
+		if (!contentType.includes("application/x-www-form-urlencoded")) return this.createErrorResponse("invalid_request", {
+			description: "Content-Type must be application/x-www-form-urlencoded",
+			statusCode: 400
+		});
 		const formData = await request.formData();
 		for (const [key, value] of formData.entries()) {
 			const allValues = formData.getAll(key);
@@ -292,13 +311,28 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			clientId = body.client_id;
 			clientSecret = body.client_secret || "";
 		}
-		if (!clientId) return this.createErrorResponse("invalid_client", "Client ID is required", 401);
+		if (!clientId) return this.createErrorResponse("invalid_client", {
+			description: "Client ID is required",
+			statusCode: 401
+		});
 		const clientInfo = await this.getClient(env, clientId);
-		if (!clientInfo) return this.createErrorResponse("invalid_client", "Client not found", 401);
+		if (!clientInfo) return this.createErrorResponse("invalid_client", {
+			description: "Client not found",
+			statusCode: 401
+		});
 		if (!(clientInfo.tokenEndpointAuthMethod === "none")) {
-			if (!clientSecret) return this.createErrorResponse("invalid_client", "Client authentication failed: missing client_secret", 401);
-			if (!clientInfo.clientSecret) return this.createErrorResponse("invalid_client", "Client authentication failed: client has no registered secret", 401);
-			if (await hashSecret(clientSecret) !== clientInfo.clientSecret) return this.createErrorResponse("invalid_client", "Client authentication failed: invalid client_secret", 401);
+			if (!clientSecret) return this.createErrorResponse("invalid_client", {
+				description: "Client authentication failed: missing client_secret",
+				statusCode: 401
+			});
+			if (!clientInfo.clientSecret) return this.createErrorResponse("invalid_client", {
+				description: "Client authentication failed: client has no registered secret",
+				statusCode: 401
+			});
+			if (await hashSecret(clientSecret) !== clientInfo.clientSecret) return this.createErrorResponse("invalid_client", {
+				description: "Client authentication failed: invalid client_secret",
+				statusCode: 401
+			});
 		}
 		return {
 			body,
@@ -428,11 +462,31 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	* @returns Response with token data or error
 	*/
 	async handleTokenRequest(body, clientInfo, env) {
-		const grantType = body.grant_type;
-		if (grantType === GrantType.AUTHORIZATION_CODE) return this.handleAuthorizationCodeGrant(body, clientInfo, env);
-		else if (grantType === GrantType.REFRESH_TOKEN) return this.handleRefreshTokenGrant(body, clientInfo, env);
-		else if (grantType === GrantType.TOKEN_EXCHANGE && this.options.allowTokenExchangeGrant) return this.handleTokenExchangeGrant(body, clientInfo, env);
-		else return this.createErrorResponse("unsupported_grant_type", "Grant type not supported");
+		try {
+			const grantType = body.grant_type;
+			if (grantType === GrantType.AUTHORIZATION_CODE) return await this.handleAuthorizationCodeGrant(body, clientInfo, env);
+			else if (grantType === GrantType.REFRESH_TOKEN) return await this.handleRefreshTokenGrant(body, clientInfo, env);
+			else if (grantType === GrantType.TOKEN_EXCHANGE && this.options.allowTokenExchangeGrant) return await this.handleTokenExchangeGrant(body, clientInfo, env);
+			else return this.createErrorResponse("unsupported_grant_type", { description: "Grant type not supported" });
+		} catch (error) {
+			const response = this.createOAuthErrorResponse(error);
+			if (response) return response;
+			throw error;
+		}
+	}
+	/**
+	* Build a structured OAuth `/token` error response from an OAuth error.
+	*
+	* The supported form is throwing this package's exported `OAuthError`.
+	* Anything else is re-thrown so unexpected failures still surface as 500s.
+	*
+	* Use `headers['Retry-After']` for rate-limit / transient-failure backoff
+	* hints (see RFC 7231 §7.1.3 — either an integer seconds value or an
+	* HTTP-date is allowed).
+	*/
+	createOAuthErrorResponse(error) {
+		if (!(error instanceof OAuthError)) return void 0;
+		return this.createErrorResponse(error.code, error.options);
 	}
 	/**
 	* Handles the authorization code grant type
@@ -446,27 +500,27 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		const code = body.code;
 		const redirectUri = body.redirect_uri;
 		const codeVerifier = body.code_verifier;
-		if (!code) return this.createErrorResponse("invalid_request", "Authorization code is required");
+		if (!code) return this.createErrorResponse("invalid_request", { description: "Authorization code is required" });
 		const codeParts = code.split(":");
-		if (codeParts.length !== 3) return this.createErrorResponse("invalid_grant", "Invalid authorization code format");
+		if (codeParts.length !== 3) return this.createErrorResponse("invalid_grant", { description: "Invalid authorization code format" });
 		const [userId, grantId, _] = codeParts;
 		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) return this.createErrorResponse("invalid_grant", { description: "Grant not found or authorization code expired" });
 		if (!grantData.authCodeId) {
 			try {
 				await this.createOAuthHelpers(env).revokeGrant(grantId, userId);
 			} catch {}
-			return this.createErrorResponse("invalid_grant", "Authorization code already used");
+			return this.createErrorResponse("invalid_grant", { description: "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");
+		if (await hashSecret(code) !== grantData.authCodeId) return this.createErrorResponse("invalid_grant", { description: "Invalid authorization code" });
+		if (grantData.clientId !== clientInfo.clientId) return this.createErrorResponse("invalid_grant", { description: "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 && !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 (!redirectUri && !isPkceEnabled) return this.createErrorResponse("invalid_request", { description: "redirect_uri is required when not using PKCE" });
+		if (redirectUri && !isValidRedirectUri(redirectUri, clientInfo.redirectUris)) return this.createErrorResponse("invalid_grant", { description: "Invalid redirect URI" });
+		if (!isPkceEnabled && codeVerifier) return this.createErrorResponse("invalid_request", { description: "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");
+			if (!codeVerifier) return this.createErrorResponse("invalid_request", { description: "code_verifier is required for PKCE" });
 			let calculatedChallenge;
 			if (grantData.codeChallengeMethod === "S256") {
 				const data = new TextEncoder().encode(codeVerifier);
@@ -474,7 +528,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				const hashArray = Array.from(new Uint8Array(hashBuffer));
 				calculatedChallenge = base64UrlEncode(String.fromCharCode(...hashArray));
 			} else calculatedChallenge = codeVerifier;
-			if (calculatedChallenge !== grantData.codeChallenge) return this.createErrorResponse("invalid_grant", "Invalid PKCE code_verifier");
+			if (calculatedChallenge !== grantData.codeChallenge) return this.createErrorResponse("invalid_grant", { description: "Invalid PKCE code_verifier" });
 		}
 		let accessTokenTTL = this.options.accessTokenTTL;
 		let refreshTokenTTL = this.options.refreshTokenTTL;
@@ -541,10 +595,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		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.some((granted) => resourceMatches(requested, granted, originOnly))) 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", { description: "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");
+		if ((body.resource || grantData.resource) && !audience) return this.createErrorResponse("invalid_target", { description: "The resource parameter must be a valid absolute URI without a fragment" });
 		const tokenResponse = {
 			access_token: await this.createAccessToken({
 				userId,
@@ -575,20 +629,20 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	*/
 	async handleRefreshTokenGrant(body, clientInfo, env) {
 		const refreshToken = body.refresh_token;
-		if (!refreshToken) return this.createErrorResponse("invalid_request", "Refresh token is required");
+		if (!refreshToken) return this.createErrorResponse("invalid_request", { description: "Refresh token is required" });
 		const tokenParts = refreshToken.split(":");
-		if (tokenParts.length !== 3) return this.createErrorResponse("invalid_grant", "Invalid token format");
+		if (tokenParts.length !== 3) return this.createErrorResponse("invalid_grant", { description: "Invalid token format" });
 		const [userId, grantId, _] = tokenParts;
 		const providedTokenHash = await generateTokenId(refreshToken);
 		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");
+		if (!grantData) return this.createErrorResponse("invalid_grant", { description: "Grant not found" });
 		const isCurrentToken = grantData.refreshTokenId === providedTokenHash;
 		const isPreviousToken = grantData.previousRefreshTokenId === providedTokenHash;
-		if (!isCurrentToken && !isPreviousToken) return this.createErrorResponse("invalid_grant", "Invalid refresh token");
-		if (grantData.clientId !== clientInfo.clientId) return this.createErrorResponse("invalid_grant", "Client ID mismatch");
+		if (!isCurrentToken && !isPreviousToken) return this.createErrorResponse("invalid_grant", { description: "Invalid refresh token" });
+		if (grantData.clientId !== clientInfo.clientId) return this.createErrorResponse("invalid_grant", { description: "Client ID mismatch" });
 		if (grantData.expiresAt !== void 0) {
-			if (Math.floor(Date.now() / 1e3) >= grantData.expiresAt) return this.createErrorResponse("invalid_grant", "Refresh token has expired");
+			if (Math.floor(Date.now() / 1e3) >= grantData.expiresAt) return this.createErrorResponse("invalid_grant", { description: "Refresh token has expired" });
 		}
 		const newAccessToken = `${userId}:${grantId}:${generateRandomString(TOKEN_LENGTH)}`;
 		const accessTokenId = await generateTokenId(newAccessToken);
@@ -623,7 +677,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				}
 				if (callbackResult.accessTokenProps) accessTokenProps = callbackResult.accessTokenProps;
 				if (callbackResult.accessTokenTTL !== void 0) accessTokenTTL = callbackResult.accessTokenTTL;
-				if ("refreshTokenTTL" in callbackResult) return this.createErrorResponse("invalid_request", "refreshTokenTTL cannot be changed during refresh token exchange");
+				if ("refreshTokenTTL" in callbackResult) return this.createErrorResponse("invalid_request", { description: "refreshTokenTTL cannot be changed during refresh token exchange" });
 				if (callbackResult.accessTokenScope) tokenScopes = this.downscope(callbackResult.accessTokenScope, grantData.scope);
 			}
 			if (grantPropsChanged) {
@@ -662,10 +716,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		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.some((granted) => resourceMatches(requested, granted, originOnly))) 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", { description: "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");
+		if ((body.resource || grantData.resource) && !audience) return this.createErrorResponse("invalid_target", { description: "The resource parameter must be a valid absolute URI without a fragment" });
 		const accessTokenData = {
 			id: accessTokenId,
 			grantId,
@@ -681,7 +735,12 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				encryptedProps: encryptedAccessTokenProps
 			}
 		};
-		await env.OAUTH_KV.put(`token:${userId}:${grantId}:${accessTokenId}`, JSON.stringify(accessTokenData), { expirationTtl: accessTokenTTL });
+		try {
+			await env.OAUTH_KV.put(`token:${userId}:${grantId}:${accessTokenId}`, JSON.stringify(accessTokenData), { expirationTtl: accessTokenTTL });
+		} catch (error) {
+			this.throwRetryableTokenStorageErrorIfKvRateLimited(error);
+			throw error;
+		}
 		const tokenResponse = {
 			access_token: newAccessToken,
 			token_type: "bearer",
@@ -709,10 +768,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	*/
 	async exchangeToken(subjectToken, requestedScopes, requestedResource, expiresIn, clientInfo, env) {
 		const tokenSummary = await this.unwrapToken(subjectToken, env);
-		if (!tokenSummary) throw new OAuthError("invalid_grant", "Invalid or expired subject token");
+		if (!tokenSummary) throw new OAuthError("invalid_grant", { description: "Invalid or expired subject token" });
 		const grantKey = `grant:${tokenSummary.userId}:${tokenSummary.grantId}`;
 		const grantData = await env.OAUTH_KV.get(grantKey, { type: "json" });
-		if (!grantData) throw new OAuthError("invalid_grant", "Grant not found");
+		if (!grantData) throw new OAuthError("invalid_grant", { description: "Grant not found" });
 		let tokenScopes = this.downscope(requestedScopes, grantData.scope);
 		const originOnly = !!this.options.resourceMatchOriginOnly;
 		let newAudience = tokenSummary.audience;
@@ -720,21 +779,21 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			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.some((granted) => resourceMatches(requested, granted, originOnly))) 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", { description: "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");
+			if (!parsedResource) throw new OAuthError("invalid_target", { description: "The resource parameter must be a valid absolute URI without a fragment" });
 			newAudience = parsedResource;
 		}
 		const now = Math.floor(Date.now() / 1e3);
 		const subjectTokenRemainingLifetime = tokenSummary.expiresAt - now;
 		let accessTokenTTL = this.options.accessTokenTTL ?? DEFAULT_ACCESS_TOKEN_TTL;
 		if (expiresIn !== void 0) {
-			if (expiresIn <= 0) throw new OAuthError("invalid_request", "Invalid expires_in parameter");
+			if (expiresIn <= 0) throw new OAuthError("invalid_request", { description: "Invalid expires_in parameter" });
 			accessTokenTTL = Math.min(expiresIn, subjectTokenRemainingLifetime);
 		} else accessTokenTTL = Math.min(accessTokenTTL, subjectTokenRemainingLifetime);
 		const subjectTokenData = await env.OAUTH_KV.get(`token:${tokenSummary.userId}:${tokenSummary.grantId}:${tokenSummary.id}`, { type: "json" });
-		if (!subjectTokenData) throw new OAuthError("invalid_grant", "Subject token data not found");
+		if (!subjectTokenData) throw new OAuthError("invalid_grant", { description: "Subject token data not found" });
 		const encryptionKey = await unwrapKeyWithToken(subjectToken, subjectTokenData.wrappedEncryptionKey);
 		let accessTokenEncryptionKey = encryptionKey;
 		let encryptedAccessTokenProps = subjectTokenData.grant.encryptedProps;
@@ -798,25 +857,26 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		const requestedTokenType = body.requested_token_type || "urn:ietf:params:oauth:token-type:access_token";
 		const requestedScope = body.scope;
 		const requestedResource = body.resource;
-		if (!subjectToken) return this.createErrorResponse("invalid_request", "subject_token is required");
-		if (!subjectTokenType) return this.createErrorResponse("invalid_request", "subject_token_type is required");
-		if (subjectTokenType !== "urn:ietf:params:oauth:token-type:access_token") return this.createErrorResponse("invalid_request", "Only access_token subject_token_type is supported");
-		if (requestedTokenType !== "urn:ietf:params:oauth:token-type:access_token") return this.createErrorResponse("invalid_request", "Only access_token requested_token_type is supported");
+		if (!subjectToken) return this.createErrorResponse("invalid_request", { description: "subject_token is required" });
+		if (!subjectTokenType) return this.createErrorResponse("invalid_request", { description: "subject_token_type is required" });
+		if (subjectTokenType !== "urn:ietf:params:oauth:token-type:access_token") return this.createErrorResponse("invalid_request", { description: "Only access_token subject_token_type is supported" });
+		if (requestedTokenType !== "urn:ietf:params:oauth:token-type:access_token") return this.createErrorResponse("invalid_request", { description: "Only access_token requested_token_type is supported" });
 		let requestedScopes;
 		if (requestedScope) if (typeof requestedScope === "string") requestedScopes = requestedScope.split(" ").filter(Boolean);
 		else if (Array.isArray(requestedScope)) requestedScopes = requestedScope;
-		else return this.createErrorResponse("invalid_request", "Invalid scope parameter format");
+		else return this.createErrorResponse("invalid_request", { description: "Invalid scope parameter format" });
 		let expiresIn;
 		if (body.expires_in !== void 0) {
 			const requestedTTL = parseInt(body.expires_in, 10);
-			if (isNaN(requestedTTL) || requestedTTL <= 0) return this.createErrorResponse("invalid_request", "Invalid expires_in parameter");
+			if (isNaN(requestedTTL) || requestedTTL <= 0) return this.createErrorResponse("invalid_request", { description: "Invalid expires_in parameter" });
 			expiresIn = requestedTTL;
 		}
 		try {
 			const tokenResponse = await this.exchangeToken(subjectToken, requestedScopes, requestedResource, expiresIn, clientInfo, env);
 			return new Response(JSON.stringify(tokenResponse), { headers: { "Content-Type": "application/json" } });
 		} catch (error) {
-			if (error instanceof OAuthError) return this.createErrorResponse(error.code, error.message);
+			const response = this.createOAuthErrorResponse(error);
+			if (response) return response;
 			throw error;
 		}
 	}
@@ -838,7 +898,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	*/
 	async revokeToken(body, env) {
 		const token = body.token;
-		if (!token) return this.createErrorResponse("invalid_request", "Token parameter is required");
+		if (!token) return this.createErrorResponse("invalid_request", { description: "Token parameter is required" });
 		const tokenParts = token.split(":");
 		if (tokenParts.length !== 3) return new Response("", { status: 200 });
 		const [userId, grantId, _] = tokenParts;
@@ -896,20 +956,35 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	* @returns Response with client registration data or error
 	*/
 	async handleClientRegistration(request, env) {
-		if (!this.options.clientRegistrationEndpoint) return this.createErrorResponse("not_implemented", "Client registration is not enabled", 501);
-		if (request.method !== "POST") return this.createErrorResponse("invalid_request", "Method not allowed", 405);
-		if (parseInt(request.headers.get("Content-Length") || "0", 10) > 1048576) return this.createErrorResponse("invalid_request", "Request payload too large, must be under 1 MiB", 413);
+		if (!this.options.clientRegistrationEndpoint) return this.createErrorResponse("not_implemented", {
+			description: "Client registration is not enabled",
+			statusCode: 501
+		});
+		if (request.method !== "POST") return this.createErrorResponse("invalid_request", {
+			description: "Method not allowed",
+			statusCode: 405
+		});
+		if (parseInt(request.headers.get("Content-Length") || "0", 10) > 1048576) return this.createErrorResponse("invalid_request", {
+			description: "Request payload too large, must be under 1 MiB",
+			statusCode: 413
+		});
 		let clientMetadata;
 		try {
 			const text = await request.text();
-			if (text.length > 1048576) return this.createErrorResponse("invalid_request", "Request payload too large, must be under 1 MiB", 413);
+			if (text.length > 1048576) return this.createErrorResponse("invalid_request", {
+				description: "Request payload too large, must be under 1 MiB",
+				statusCode: 413
+			});
 			clientMetadata = JSON.parse(text);
 		} catch (error) {
-			return this.createErrorResponse("invalid_request", "Invalid JSON payload", 400);
+			return this.createErrorResponse("invalid_request", {
+				description: "Invalid JSON payload",
+				statusCode: 400
+			});
 		}
 		const authMethod = OAuthProviderImpl.validateStringField(clientMetadata.token_endpoint_auth_method) || "client_secret_basic";
 		const isPublicClient = authMethod === "none";
-		if (isPublicClient && this.options.disallowPublicClientRegistration) return this.createErrorResponse("invalid_client_metadata", "Public client registration is not allowed");
+		if (isPublicClient && this.options.disallowPublicClientRegistration) return this.createErrorResponse("invalid_client_metadata", { description: "Public client registration is not allowed" });
 		const clientId = generateRandomString(16);
 		let clientSecret;
 		let hashedSecret;
@@ -943,9 +1018,11 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			};
 			if (!isPublicClient && hashedSecret) clientInfo.clientSecret = hashedSecret;
 		} catch (error) {
-			return this.createErrorResponse("invalid_client_metadata", error instanceof Error ? error.message : "Invalid client metadata");
+			return this.createErrorResponse("invalid_client_metadata", { description: 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 +1041,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), {
@@ -983,7 +1060,11 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		const url = new URL(request.url);
 		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") });
+		if (!authHeader || !authHeader.startsWith("Bearer ")) return this.createErrorResponse("invalid_token", {
+			description: "Missing or invalid access token",
+			statusCode: 401,
+			headers: { "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;
@@ -995,14 +1076,26 @@ 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": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") });
+		if (!tokenData && !this.options.resolveExternalToken) return this.createErrorResponse("invalid_token", {
+			description: "Invalid access token",
+			statusCode: 401,
+			headers: { "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": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") });
+			if (tokenData.expiresAt < now) return this.createErrorResponse("invalid_token", {
+				description: "Access token expired",
+				statusCode: 401,
+				headers: { "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": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token", "Invalid audience") });
+				if (!(Array.isArray(tokenData.audience) ? tokenData.audience : [tokenData.audience]).some((aud) => audienceMatches(resourceServer, aud))) return this.createErrorResponse("invalid_token", {
+					description: "Token audience does not match resource server",
+					statusCode: 401,
+					headers: { "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) {
@@ -1011,17 +1104,28 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				request,
 				env
 			});
-			if (!ext) return this.createErrorResponse("invalid_token", "Invalid access token", 401, { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") });
+			if (!ext) return this.createErrorResponse("invalid_token", {
+				description: "Invalid access token",
+				statusCode: 401,
+				headers: { "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": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token", "Invalid audience") });
+				if (!(Array.isArray(ext.audience) ? ext.audience : [ext.audience]).some((aud) => audienceMatches(resourceServer, aud))) return this.createErrorResponse("invalid_token", {
+					description: "Token audience does not match resource server",
+					statusCode: 401,
+					headers: { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token", "Invalid audience") }
+				});
 			}
 			ctx.props = ext.props;
 		}
 		if (!env.OAUTH_PROVIDER) env.OAUTH_PROVIDER = this.createOAuthHelpers(env);
 		const apiHandler = this.findApiHandlerForUrl(url);
-		if (!apiHandler) return this.createErrorResponse("invalid_request", "No handler found for API route", 404);
+		if (!apiHandler) return this.createErrorResponse("invalid_request", {
+			description: "No handler found for API route",
+			statusCode: 404
+		});
 		if (apiHandler.type === HandlerType.EXPORTED_HANDLER) return apiHandler.handler.fetch(request, env, ctx);
 		else return new apiHandler.handler(ctx, env).fetch(request);
 	}
@@ -1043,7 +1147,24 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	*/
 	async saveGrantWithTTL(env, grantKey, grantData, now) {
 		const kvOptions = grantData.expiresAt !== void 0 ? { expiration: grantData.expiresAt } : {};
-		await env.OAUTH_KV.put(grantKey, JSON.stringify(grantData), kvOptions);
+		try {
+			await env.OAUTH_KV.put(grantKey, JSON.stringify(grantData), kvOptions);
+		} catch (error) {
+			this.throwRetryableTokenStorageErrorIfKvRateLimited(error);
+			throw error;
+		}
+	}
+	throwRetryableTokenStorageErrorIfKvRateLimited(error) {
+		if (!this.isKvRateLimitError(error)) return;
+		throw new OAuthError("temporarily_unavailable", {
+			description: "Token issuance is temporarily unavailable; retry shortly",
+			statusCode: 429,
+			headers: { "Retry-After": "30" }
+		});
+	}
+	isKvRateLimitError(error) {
+		if (!(error instanceof Error)) return false;
+		return /KV .*failed: 429 Too Many Requests/i.test(error.message) || /429 Too Many Requests/i.test(error.message);
 	}
 	/**
 	* Fetches client information from KV storage or via CIMD (Client ID Metadata Document)
@@ -1100,7 +1221,12 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				encryptedProps
 			}
 		};
-		await env.OAUTH_KV.put(`token:${userId}:${grantId}:${accessTokenId}`, JSON.stringify(accessTokenData), { expirationTtl: expiresIn });
+		try {
+			await env.OAUTH_KV.put(`token:${userId}:${grantId}:${accessTokenId}`, JSON.stringify(accessTokenData), { expirationTtl: expiresIn });
+		} catch (error) {
+			this.throwRetryableTokenStorageErrorIfKvRateLimited(error);
+			throw error;
+		}
 		return accessToken;
 	}
 	/**
@@ -1123,7 +1249,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 {
@@ -1262,17 +1389,18 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	/**
 	* Helper function to create OAuth error responses
 	* @param code - OAuth error code (e.g., 'invalid_request', 'invalid_token')
-	* @param description - Human-readable error description
-	* @param status - HTTP status code (default: 400)
-	* @param headers - Additional headers to include
+	* @param options - Error response options
 	* @returns A Response object with the error
 	*/
-	createErrorResponse(code, description, status = 400, headers = {}) {
+	createErrorResponse(code, options) {
+		const { description } = options;
+		const responseStatus = options.statusCode ?? 400;
+		const responseHeaders = options.headers ?? {};
 		const customErrorResponse = this.options.onError?.({
 			code,
 			description,
-			status,
-			headers
+			status: responseStatus,
+			headers: responseHeaders
 		});
 		if (customErrorResponse) return customErrorResponse;
 		const body = JSON.stringify({
@@ -1280,23 +1408,66 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			error_description: description
 		});
 		return new Response(body, {
-			status,
+			status: responseStatus,
 			headers: {
 				"Content-Type": "application/json",
-				...headers
+				...responseHeaders
 			}
 		});
 	}
 };
 /**
-* Error class for OAuth operations
-* Carries OAuth error code and description for proper error responses
+* Structured OAuth 2.0 error.
+*
+* Throw from a `tokenExchangeCallback` (or any code it calls — the error
+* propagates naturally up through deep call stacks) to surface a standard
+* `/token` error response (`{ error, error_description }`) instead of a
+* generic `500 Internal Server Error`.
+*
+* Anything thrown that is **not** an `OAuthError` continues to surface as
+* a 500 so unexpected failures remain visible — the provider does not
+* catch-everything-and-return-400.
+*
+* @example
+* ```ts
+* import { OAuthError } from '@cloudflare/workers-oauth-provider';
+*
+* tokenExchangeCallback: async (options) => {
+*   if (options.grantType === 'refresh_token') {
+*     // refreshUpstream() may throw OAuthError from any depth
+*     return { newProps: await refreshUpstream(options.props) };
+*   }
+* }
+*
+* async function refreshUpstream(props) {
+*   const res = await fetch(...);
+*   if (res.status === 401) {
+*     throw new OAuthError('invalid_grant', { description: 'upstream refresh token is invalid' });
+*   }
+*   if (res.status === 429) {
+*     // Mirror upstream's Retry-After if present, otherwise pick a default.
+*     throw new OAuthError('temporarily_unavailable', {
+*       description: 'upstream rate limited',
+*       statusCode: 429,
+*       headers: { 'Retry-After': res.headers.get('retry-after') ?? '60' },
+*     });
+*   }
+*   return await res.json();
+* }
+* ```
 */
 var OAuthError = class extends Error {
-	constructor(code, message) {
-		super(message);
-		this.code = code;
+	constructor(code, options) {
+		super(options.description);
 		this.name = "OAuthError";
+		this.code = code;
+		this.options = {
+			...options,
+			statusCode: options.statusCode ?? 400
+		};
+		this.description = this.options.description;
+		this.statusCode = this.options.statusCode;
+		this.headers = this.options.headers;
 	}
 };
 /**
@@ -1304,6 +1475,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 +2030,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 +2136,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
@@ -1945,4 +2230,4 @@ var OAuthHelpersImpl = class {
 var oauth_provider_default = OAuthProvider;
 
 //#endregion
-export { GrantType, OAuthProvider, oauth_provider_default as default, getOAuthApi };
+export { GrantType, OAuthError, OAuthProvider, oauth_provider_default as default, getOAuthApi };

package/package.json

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