@cloudflare/workers-oauth-provider 0.7.2 → 0.8.1

package/README.md

@@ -229,6 +229,15 @@ class ApiHandler extends WorkerEntrypoint {
 }
 ```
 
+By default, `completeAuthorization()` revokes existing grants for the same user and client after storing the new
+grant. This prevents stale tokens from continuing to use old `props` after a user re-authorizes. Set
+`revokeExistingGrants: false` only if your application intentionally allows multiple concurrent grants for the same
+user and client.
+
+For users with many grants, `revokeExistingGrantsBatchSize` controls the KV page size used while scanning existing
+grants for revocation. It defaults to `50`, must be a positive integer, and is capped at Cloudflare KV's maximum page
+size of `1000`.
+
 This implementation requires that your worker is configured with a Workers KV namespace binding called `OAUTH_KV`, which is used to store token information. See the file `storage-schema.md` for details on the schema of this namespace.
 
 The `env.OAUTH_PROVIDER` object available to the fetch handlers provides some methods to query the storage, including:

package/dist/oauth-provider.d.ts

@@ -393,6 +393,48 @@ interface TokenExchangeCallbackOptions {
    */
   props: any;
 }
+/**
+ * Options for the client registration callback (RFC 7591).
+ */
+interface ClientRegistrationCallbackOptions {
+  /**
+   * Parsed client metadata from the registration request body.
+   *
+   * Note: This is the raw JSON body. RFC 7591 §3.1.1 `software_statement` claims
+   * are NOT currently merged in by the library — if `software_statement` is present
+   * the callback is responsible for verifying the JWT and applying its claims.
+   */
+  clientMetadata: Record<string, unknown>;
+  /**
+   * A clone of the registration HTTP request. The body has not been consumed,
+   * so the callback may call `request.text()` / `request.json()` if needed
+   * (e.g. to validate a signature over the raw body).
+   */
+  request: Request;
+}
+/**
+ * Result of the client registration callback.
+ *
+ * Return `undefined`/nothing to allow registration. Return an object to reject
+ * registration. By default, rejection follows RFC 7591 §3.2.2:
+ * `invalid_client_metadata` with HTTP 400.
+ */
+interface ClientRegistrationCallbackResult {
+  /**
+   * OAuth error code when rejecting. Defaults to `invalid_client_metadata`.
+   * For non-metadata rejections (e.g. missing initial access token, untrusted
+   * origin), set this to a more specific code such as `access_denied` or
+   * `invalid_token`.
+   */
+  code?: string;
+  /** Error description when rejecting. */
+  description?: string;
+  /**
+   * HTTP status code when rejecting. Defaults to 400. Override for auth-style
+   * failures (e.g. 401 for missing IAT, 403 for policy denial).
+   */
+  status?: number;
+}
 /**
  * Input parameters for the resolveExternalToken callback function
  */
@@ -538,6 +580,11 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    * Defaults to false.
    */
   disallowPublicClientRegistration?: boolean;
+  /**
+   * Called during DCR (RFC 7591) before the client is stored. Return void/undefined
+   * to allow registration, or return an object to reject it.
+   */
+  clientRegistrationCallback?: (options: ClientRegistrationCallbackOptions) => Promise<ClientRegistrationCallbackResult | void> | ClientRegistrationCallbackResult | void;
   /**
    * Optional callback function that is called during token exchange.
    * This allows updating the props stored in both the access token and the grant.
@@ -896,6 +943,13 @@ interface CompleteAuthorizationOptions {
    * Set to false to allow multiple concurrent grants per user+client.
    */
   revokeExistingGrants?: boolean;
+  /**
+   * Maximum number of grants to fetch per page when revoking existing
+   * grants. Only used when revokeExistingGrants is not false.
+   * Must be a positive integer. Values above Cloudflare KV's 1000-key page
+   * limit are clamped to 1000. Defaults to 50.
+   */
+  revokeExistingGrantsBatchSize?: number;
 }
 /**
  * Authorization grant record
@@ -952,12 +1006,15 @@ interface Grant {
   previousRefreshTokenWrappedKey?: string;
   /**
    * The hash of the authorization code associated with this grant
-   * Only present during the authorization code exchange process
+   * Retained after exchange so that a replay of the same code can be
+   * verified before any action is taken on the grant. The code is
+   * considered already exchanged once authCodeWrappedKey is removed.
    */
   authCodeId?: string;
   /**
    * Wrapped encryption key for the authorization code
-   * Only present during the authorization code exchange process
+   * Present only until the authorization code is exchanged; its absence
+   * (with authCodeId still set) marks the code as already used.
    */
   authCodeWrappedKey?: string;
   /**
@@ -1335,4 +1392,4 @@ declare function getJwtCryptoAlgorithms(alg: string): {
   verifyAlgorithm: Parameters<SubtleCrypto['verify']>[0];
 };
 //#endregion
-export { AuthRequest, ClientInfo, CompleteAuthorizationOptions, type EmaClaimsMapper, type EmaClaimsMapperInput, type EmaClaimsMapperResult, type EmaIdJagClaims, type EmaOptions, type EmaTrustedIssuer, type EmaTrustedIssuerResolver, type EmaTrustedIssuerResolverInput, type EmaValidationError, ExchangeTokenOptions, Grant, GrantSummary, GrantType, ListOptions, ListResult, OAuthError, OAuthErrorOptions, OAuthHelpers, OAuthProvider, OAuthProvider as default, OAuthProviderOptions, OAuthTokenErrorCode, PurgeOptions, PurgeResult, ResolveExternalTokenInput, ResolveExternalTokenResult, Token, TokenBase, TokenExchangeCallbackOptions, TokenExchangeCallbackResult, TokenSummary, base64UrlToBytes, getJwtCryptoAlgorithms, getOAuthApi, isValidOAuthScopeToken, parseJwtJsonPart, resourceMatches, validateResourceUri };
+export { AuthRequest, ClientInfo, ClientRegistrationCallbackOptions, ClientRegistrationCallbackResult, CompleteAuthorizationOptions, type EmaClaimsMapper, type EmaClaimsMapperInput, type EmaClaimsMapperResult, type EmaIdJagClaims, type EmaOptions, type EmaTrustedIssuer, type EmaTrustedIssuerResolver, type EmaTrustedIssuerResolverInput, type EmaValidationError, ExchangeTokenOptions, Grant, GrantSummary, GrantType, ListOptions, ListResult, OAuthError, OAuthErrorOptions, OAuthHelpers, OAuthProvider, OAuthProvider as default, OAuthProviderOptions, OAuthTokenErrorCode, PurgeOptions, PurgeResult, ResolveExternalTokenInput, ResolveExternalTokenResult, Token, TokenBase, TokenExchangeCallbackOptions, TokenExchangeCallbackResult, TokenSummary, base64UrlToBytes, getJwtCryptoAlgorithms, getOAuthApi, isValidOAuthScopeToken, parseJwtJsonPart, resourceMatches, validateResourceUri };

package/dist/oauth-provider.js

@@ -639,9 +639,11 @@ function validateEmaMapperResult(result) {
 * TOCTOU window between claim validation and token mint.
 */
 function computeEmaAccessTokenTTL(input) {
-	const { configuredDefaultSeconds, assertionExp, mapperTtl, now } = input;
+	const { configuredDefaultSeconds, assertionExp, mapperTtl, now, minTtlSeconds } = input;
 	if (assertionExp - now <= 0) return err({ reason: "assertion_expired_after_processing" });
-	return ok(mapperTtl ?? configuredDefaultSeconds);
+	const ttl = mapperTtl ?? configuredDefaultSeconds;
+	if (ttl < minTtlSeconds) return err({ reason: "invalid_mapped_ttl" });
+	return ok(ttl);
 }
 function readRequiredString(claims, claimName) {
 	const value = claims[claimName];
@@ -672,6 +674,10 @@ function readNumericDateClaim(claims, claimName) {
 //#endregion
 //#region src/oauth-provider.ts
 const PROTECTED_RESOURCE_WELL_KNOWN_PREFIX = "/.well-known/oauth-protected-resource";
+const NO_CACHE_HEADERS = {
+	"Cache-Control": "no-store",
+	Pragma: "no-cache"
+};
 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)
@@ -781,6 +787,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			onError: ({ status, code, description }) => console.warn(`OAuth error response: ${status} ${code} - ${description}`),
 			...options
 		};
+		if (!Number.isInteger(this.options.accessTokenTTL) || this.options.accessTokenTTL < KV_MIN_EXPIRATION_TTL_SECONDS) throw new TypeError(`accessTokenTTL must be an integer of at least ${KV_MIN_EXPIRATION_TTL_SECONDS} seconds (Cloudflare KV's minimum expiration window).`);
 		this.validateEmaOptions(this.options.enterpriseManagedAuthorization);
 		if (this.options.enterpriseManagedAuthorization) {
 			this.jwksProvider = createDefaultJwksProvider({ cacheTtlSeconds: this.options.enterpriseManagedAuthorization.jwksCacheTtlSeconds });
@@ -865,7 +872,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			const parsed = await this.parseTokenEndpointRequest(request, env);
 			if (parsed instanceof Response) return this.addCorsHeaders(parsed, request);
 			let response;
-			if (parsed.isRevocationRequest) response = await this.handleRevocationRequest(parsed.body, env);
+			if (parsed.isRevocationRequest) response = await this.handleRevocationRequest(parsed.body, parsed.clientInfo, env);
 			else response = await this.handleTokenRequest(parsed.body, parsed.clientInfo, env, url, request);
 			return this.addCorsHeaders(response, request);
 		}
@@ -989,17 +996,35 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			statusCode: 400
 		});
 		const formData = await request.formData();
+		const processedKeys = /* @__PURE__ */ new Set();
 		for (const [key, value] of formData.entries()) {
+			if (processedKeys.has(key)) continue;
+			processedKeys.add(key);
 			const allValues = formData.getAll(key);
+			if (key !== "resource" && allValues.length > 1) return this.createErrorResponse("invalid_request", {
+				description: `Request parameter "${key}" must not be repeated`,
+				statusCode: 400
+			});
 			body[key] = allValues.length > 1 ? allValues : value;
 		}
 		const authHeader = request.headers.get("Authorization");
 		let clientId = "";
 		let clientSecret = "";
 		if (authHeader && authHeader.startsWith("Basic ")) {
-			const [id, secret] = atob(authHeader.substring(6)).split(":", 2);
-			clientId = decodeURIComponent(id);
-			clientSecret = decodeURIComponent(secret || "");
+			if (body.client_id || body.client_secret) return this.createErrorResponse("invalid_request", {
+				description: "Client must not use multiple authentication methods",
+				statusCode: 400
+			});
+			const credentials = atob(authHeader.substring(6));
+			const separatorIndex = credentials.indexOf(":");
+			if (separatorIndex === -1) return this.createErrorResponse("invalid_client", {
+				description: "Client authentication failed: invalid Basic credentials",
+				statusCode: 401
+			});
+			const id = credentials.substring(0, separatorIndex);
+			const secret = credentials.substring(separatorIndex + 1);
+			clientId = decodeFormUrlEncodedComponent(id);
+			clientSecret = decodeFormUrlEncodedComponent(secret);
 		} else {
 			clientId = body.client_id;
 			clientSecret = body.client_secret || "";
@@ -1126,7 +1151,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			registration_endpoint: registrationEndpoint,
 			scopes_supported: this.options.scopesSupported,
 			response_types_supported: responseTypesSupported,
-			response_modes_supported: ["query"],
+			response_modes_supported: this.options.allowImplicitFlow ? ["query", "fragment"] : ["query"],
 			grant_types_supported: grantTypesSupported,
 			...authorizationGrantProfilesSupported.length > 0 ? { authorization_grant_profiles_supported: authorizationGrantProfilesSupported } : {},
 			token_endpoint_auth_methods_supported: [
@@ -1214,14 +1239,15 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		const grantKey = `grant:${userId}:${grantId}`;
 		const grantData = await env.OAUTH_KV.get(grantKey, { type: "json" });
 		if (!grantData) return this.createErrorResponse("invalid_grant", { description: "Grant not found or authorization code expired" });
-		if (!grantData.authCodeId) {
+		const codeHash = await hashSecret(code);
+		if (!grantData.authCodeId || codeHash !== 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" });
+		if (!grantData.authCodeWrappedKey) {
 			try {
 				await this.createOAuthHelpers(env).revokeGrant(grantId, userId);
 			} catch {}
 			return this.createErrorResponse("invalid_grant", { description: "Authorization code already used" });
 		}
-		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", { description: "redirect_uri is required when not using PKCE" });
 		if (redirectUri && !isValidRedirectUri(redirectUri, clientInfo.redirectUris)) return this.createErrorResponse("invalid_grant", { description: "Invalid redirect URI" });
@@ -1282,7 +1308,6 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		}
 		const now = Math.floor(Date.now() / 1e3);
 		const useRefreshToken = refreshTokenTTL !== 0;
-		delete grantData.authCodeId;
 		delete grantData.codeChallenge;
 		delete grantData.codeChallengeMethod;
 		delete grantData.authCodeWrappedKey;
@@ -1325,7 +1350,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		};
 		if (refreshToken) tokenResponse.refresh_token = refreshToken;
 		if (audience) tokenResponse.resource = audience;
-		return new Response(JSON.stringify(tokenResponse), { headers: { "Content-Type": "application/json" } });
+		return new Response(JSON.stringify(tokenResponse), { headers: {
+			"Content-Type": "application/json",
+			...NO_CACHE_HEADERS
+		} });
 	}
 	/**
 	* Handles the refresh token grant type
@@ -1350,7 +1378,8 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		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", { description: "Refresh token has expired" });
+			const now$1 = Math.floor(Date.now() / 1e3);
+			if (grantData.expiresAt - now$1 < KV_MIN_EXPIRATION_TTL_SECONDS) return this.createErrorResponse("invalid_grant", { description: "Refresh token has expired" });
 		}
 		const newAccessToken = `${userId}:${grantId}:${generateRandomString(TOKEN_LENGTH)}`;
 		const accessTokenId = await generateTokenId(newAccessToken);
@@ -1407,10 +1436,12 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			}
 		}
 		const now = Math.floor(Date.now() / 1e3);
+		if (grantData.expiresAt !== void 0 && grantData.expiresAt - now < KV_MIN_EXPIRATION_TTL_SECONDS) return this.createErrorResponse("invalid_grant", { description: "Refresh token has expired" });
 		if (grantData.expiresAt !== void 0) {
 			const remainingRefreshTokenLifetime = grantData.expiresAt - now;
 			if (remainingRefreshTokenLifetime > 0) accessTokenTTL = Math.min(accessTokenTTL, remainingRefreshTokenLifetime);
 		}
+		if (accessTokenTTL < KV_MIN_EXPIRATION_TTL_SECONDS) return this.createErrorResponse("invalid_request", { description: "Requested token lifetime must be at least 60 seconds" });
 		const accessTokenExpiresAt = now + accessTokenTTL;
 		const accessTokenWrappedKey = await wrapKeyWithToken(newAccessToken, accessTokenEncryptionKey);
 		const newRefreshToken = `${userId}:${grantId}:${generateRandomString(TOKEN_LENGTH)}`;
@@ -1458,7 +1489,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			scope: tokenScopes.join(" ")
 		};
 		if (audience) tokenResponse.resource = audience;
-		return new Response(JSON.stringify(tokenResponse), { headers: { "Content-Type": "application/json" } });
+		return new Response(JSON.stringify(tokenResponse), { headers: {
+			"Content-Type": "application/json",
+			...NO_CACHE_HEADERS
+		} });
 	}
 	/**
 	* Core token exchange logic (RFC 8693)
@@ -1496,6 +1530,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		}
 		const now = Math.floor(Date.now() / 1e3);
 		const subjectTokenRemainingLifetime = tokenSummary.expiresAt - now;
+		if (subjectTokenRemainingLifetime < KV_MIN_EXPIRATION_TTL_SECONDS) throw new OAuthError("invalid_grant", { description: "Subject token is too close to expiry to exchange" });
 		let accessTokenTTL = this.options.accessTokenTTL ?? DEFAULT_ACCESS_TOKEN_TTL;
 		if (expiresIn !== void 0) {
 			if (expiresIn <= 0) throw new OAuthError("invalid_request", { description: "Invalid expires_in parameter" });
@@ -1533,6 +1568,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				if (callbackResult.accessTokenScope) tokenScopes = this.downscope(callbackResult.accessTokenScope, grantData.scope);
 			}
 		}
+		if (accessTokenTTL < KV_MIN_EXPIRATION_TTL_SECONDS) throw new OAuthError("invalid_request", { description: "Requested token lifetime must be at least 60 seconds" });
 		const tokenResponse = {
 			access_token: await this.createAccessToken({
 				userId: tokenSummary.userId,
@@ -1583,7 +1619,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		}
 		try {
 			const tokenResponse = await this.exchangeToken(subjectToken, requestedScopes, requestedResource, expiresIn, clientInfo, env);
-			return new Response(JSON.stringify(tokenResponse), { headers: { "Content-Type": "application/json" } });
+			return new Response(JSON.stringify(tokenResponse), { headers: {
+				"Content-Type": "application/json",
+				...NO_CACHE_HEADERS
+			} });
 		} catch (error) {
 			const response = this.createOAuthErrorResponse(error);
 			if (response) return response;
@@ -1613,16 +1652,9 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			request,
 			enterpriseOptions
 		});
-		const noCacheHeaders = {
-			"Cache-Control": "no-store",
-			Pragma: "no-cache"
-		};
 		if (!result.ok) {
 			const wire = emaErrorToWire(result.error);
-			return this.createErrorResponse(wire.code, {
-				description: wire.message,
-				headers: noCacheHeaders
-			}, {
+			return this.createErrorResponse(wire.code, { description: wire.message }, {
 				category: "enterprise-managed-authorization",
 				reason: result.error.reason,
 				detail: result.error
@@ -1630,7 +1662,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		}
 		return new Response(JSON.stringify(result.value), { headers: {
 			"Content-Type": "application/json",
-			...noCacheHeaders
+			...NO_CACHE_HEADERS
 		} });
 	}
 	/**
@@ -1713,7 +1745,8 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			configuredDefaultSeconds: this.options.accessTokenTTL ?? DEFAULT_ACCESS_TOKEN_TTL,
 			assertionExp: claims.value.claims.exp,
 			mapperTtl: mapped.value.accessTokenTTL,
-			now: issueNow
+			now: issueNow,
+			minTtlSeconds: KV_MIN_EXPIRATION_TTL_SECONDS
 		});
 		if (!ttl.ok) return ttl;
 		return ok(await this.issueEmaAccessToken({
@@ -1807,29 +1840,55 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	* @param env - Cloudflare Worker environment variables
 	* @returns Response confirming revocation or error
 	*/
-	async handleRevocationRequest(body, env) {
-		return this.revokeToken(body, env);
+	async handleRevocationRequest(body, clientInfo, env) {
+		return this.revokeToken(body, clientInfo, env);
 	}
 	/**
 	* - Access tokens: Revokes only the specific token
 	* - Refresh tokens: Revokes the entire grant (access + refresh tokens)
+	* Per RFC 7009 §2.1, the server MUST verify the token was issued to the client making the request.
 	* @param body - The parsed request body containing token parameter
+	* @param clientInfo - The authenticated client information
 	* @param env - Cloudflare Worker environment variables
 	* @returns Response confirming revocation or error
 	*/
-	async revokeToken(body, env) {
+	async revokeToken(body, clientInfo, env) {
 		const token = body.token;
+		const tokenTypeHint = body.token_type_hint;
 		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;
 		const tokenId = await generateTokenId(token);
-		const isAccessToken = await this.validateAccessToken(tokenId, userId, grantId, env);
-		const isRefreshToken = await this.validateRefreshToken(tokenId, userId, grantId, env);
-		if (isAccessToken) await this.revokeSpecificAccessToken(tokenId, userId, grantId, env);
-		else if (isRefreshToken) await this.createOAuthHelpers(env).revokeGrant(grantId, userId);
+		if (tokenTypeHint === "refresh_token") {
+			if (await this.revokeRefreshIfOwned(tokenId, userId, grantId, clientInfo, env)) return new Response("", { status: 200 });
+			if (await this.revokeAccessIfOwned(tokenId, userId, grantId, clientInfo, env)) return new Response("", { status: 200 });
+		} else {
+			if (await this.revokeAccessIfOwned(tokenId, userId, grantId, clientInfo, env)) return new Response("", { status: 200 });
+			if (await this.revokeRefreshIfOwned(tokenId, userId, grantId, clientInfo, env)) return new Response("", { status: 200 });
+		}
 		return new Response("", { status: 200 });
 	}
+	/** Revoke an access token if it exists and belongs to the requesting client. */
+	async revokeAccessIfOwned(tokenId, userId, grantId, clientInfo, env) {
+		const tokenData = await env.OAUTH_KV.get(`token:${userId}:${grantId}:${tokenId}`, { type: "json" });
+		if (!tokenData) return false;
+		const tokenClientId = tokenData.grant?.clientId;
+		if (tokenClientId !== void 0) {
+			if (tokenClientId !== clientInfo.clientId) return false;
+		} else if ((await env.OAUTH_KV.get(`grant:${userId}:${grantId}`, { type: "json" }))?.clientId !== clientInfo.clientId) return false;
+		await this.revokeSpecificAccessToken(tokenId, userId, grantId, env);
+		return true;
+	}
+	/** Revoke a refresh token (and its grant) if it exists and belongs to the requesting client. */
+	async revokeRefreshIfOwned(tokenId, userId, grantId, clientInfo, env) {
+		const grantData = await env.OAUTH_KV.get(`grant:${userId}:${grantId}`, { type: "json" });
+		if (!grantData) return false;
+		if (!(grantData.refreshTokenId === tokenId || grantData.previousRefreshTokenId === tokenId)) return false;
+		if (grantData.clientId !== clientInfo.clientId) return false;
+		await this.createOAuthHelpers(env).revokeGrant(grantId, userId);
+		return true;
+	}
 	/**
 	* Revokes a specific access token without affecting the refresh token
 	* @param tokenId - The hashed token ID
@@ -1842,35 +1901,6 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		await env.OAUTH_KV.delete(tokenKey);
 	}
 	/**
-	* Validates if a token is a valid access token
-	* @param tokenId - The hashed token ID
-	* @param userId - The user ID extracted from the token
-	* @param grantId - The grant ID extracted from the token
-	* @param env - Cloudflare Worker environment variables
-	* @returns Promise<boolean> indicating if the token is valid
-	*/
-	async validateAccessToken(tokenId, userId, grantId, env) {
-		const tokenKey = `token:${userId}:${grantId}:${tokenId}`;
-		const tokenData = await env.OAUTH_KV.get(tokenKey, { type: "json" });
-		if (!tokenData) return false;
-		const now = Math.floor(Date.now() / 1e3);
-		return tokenData.expiresAt >= now;
-	}
-	/**
-	* Validates if a token is a valid refresh token
-	* @param tokenId - The hashed token ID
-	* @param userId - The user ID extracted from the token
-	* @param grantId - The grant ID extracted from the token
-	* @param env - Cloudflare Worker environment variables
-	* @returns Promise<boolean> indicating if the token is valid
-	*/
-	async validateRefreshToken(tokenId, userId, grantId, env) {
-		const grantKey = `grant:${userId}:${grantId}`;
-		const grantData = await env.OAUTH_KV.get(grantKey, { type: "json" });
-		if (!grantData) return false;
-		return grantData.refreshTokenId === tokenId || grantData.previousRefreshTokenId === tokenId;
-	}
-	/**
 	* Handles the dynamic client registration endpoint (RFC 7591)
 	* @param request - The HTTP request
 	* @param env - Cloudflare Worker environment variables
@@ -1889,6 +1919,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			description: "Request payload too large, must be under 1 MiB",
 			statusCode: 413
 		});
+		const callbackRequest = request.clone();
 		let clientMetadata;
 		try {
 			const text = await request.text();
@@ -1942,6 +1973,24 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		} catch (error) {
 			return this.createErrorResponse("invalid_client_metadata", { description: error instanceof Error ? error.message : "Invalid client metadata" });
 		}
+		if (this.options.clientRegistrationCallback) {
+			let callbackResult;
+			try {
+				callbackResult = await Promise.resolve(this.options.clientRegistrationCallback({
+					clientMetadata,
+					request: callbackRequest
+				}));
+			} catch (error) {
+				return this.createErrorResponse("server_error", {
+					description: error instanceof Error ? error.message : "Client registration callback failed",
+					statusCode: 500
+				});
+			}
+			if (callbackResult !== void 0) return this.createErrorResponse(callbackResult.code || "invalid_client_metadata", {
+				description: callbackResult.description || "Client registration denied",
+				statusCode: callbackResult.status ?? 400
+			});
+		}
 		const clientKvOptions = {};
 		if (this.options.clientRegistrationTTL !== void 0) clientKvOptions.expirationTtl = this.options.clientRegistrationTTL;
 		await env.OAUTH_KV.put(`client:${clientId}`, JSON.stringify(clientInfo), clientKvOptions);
@@ -1971,7 +2020,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		}
 		return new Response(JSON.stringify(response), {
 			status: 201,
-			headers: { "Content-Type": "application/json" }
+			headers: {
+				"Content-Type": "application/json",
+				...NO_CACHE_HEADERS
+			}
 		});
 	}
 	/**
@@ -2071,7 +2123,8 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	* @param now - Current timestamp in seconds
 	*/
 	async saveGrantWithTTL(env, grantKey, grantData, now) {
-		const kvOptions = grantData.expiresAt !== void 0 ? { expiration: grantData.expiresAt } : {};
+		const minExpiration = now + KV_MIN_EXPIRATION_TTL_SECONDS + KV_EXPIRATION_CLAMP_MARGIN_SECONDS;
+		const kvOptions = grantData.expiresAt !== void 0 ? { expiration: Math.max(grantData.expiresAt, minExpiration) } : {};
 		try {
 			await env.OAUTH_KV.put(grantKey, JSON.stringify(grantData), kvOptions);
 		} catch (error) {
@@ -2128,6 +2181,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	*/
 	async createAccessToken(params) {
 		const { userId, grantId, clientId, scope, encryptedProps, encryptionKey, expiresIn, audience, env } = params;
+		if (expiresIn < KV_MIN_EXPIRATION_TTL_SECONDS) throw new OAuthError("invalid_request", { description: "Requested token lifetime must be at least 60 seconds" });
 		const accessToken = `${userId}:${grantId}:${generateRandomString(TOKEN_LENGTH)}`;
 		const now = Math.floor(Date.now() / 1e3);
 		const accessTokenId = await generateTokenId(accessToken);
@@ -2387,7 +2441,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	createErrorResponse(code, options, internal) {
 		const { description } = options;
 		const responseStatus = options.statusCode ?? 400;
-		const responseHeaders = options.headers ?? {};
+		const responseHeaders = {
+			...NO_CACHE_HEADERS,
+			...options.headers ?? {}
+		};
 		const customErrorResponse = this.options.onError?.({
 			code,
 			description,
@@ -2476,11 +2533,41 @@ const DEFAULT_REFRESH_TOKEN_TTL = 720 * 60 * 60;
 */
 const DEFAULT_CLIENT_REGISTRATION_TTL = 2160 * 60 * 60;
 /**
+* Minimum number of seconds an absolute KV expiration must be in the future.
+* Cloudflare KV rejects `put` calls whose `expiration` is less than 60 seconds
+* away with "400 Invalid expiration ... Expiration times must be at least 60
+* seconds in the future." We use this to treat near-expiry grants as expired and
+* to clamp absolute expirations when writing grants back to KV.
+*/
+const KV_MIN_EXPIRATION_TTL_SECONDS = 60;
+/**
+* Safety margin (seconds) added on top of `KV_MIN_EXPIRATION_TTL_SECONDS` when clamping an
+* absolute KV expiration. Absolute expirations are validated against KV's clock at the
+* moment the write is processed, so writing exactly `now + 60` can be rejected once
+* worker→KV latency or minor clock skew is accounted for. The margin keeps clamped writes
+* comfortably above KV's hard minimum without meaningfully extending a grant's lifetime.
+*/
+const KV_EXPIRATION_CLAMP_MARGIN_SECONDS = 5;
+/**
 * Default batch size for purgeExpiredData. Conservative to stay within
 * Cloudflare's 1000 subrequest limit per invocation.
 */
 const DEFAULT_PURGE_BATCH_SIZE = 50;
 /**
+* Maximum supported Cloudflare KV list page size.
+*/
+const MAX_KV_LIST_LIMIT = 1e3;
+/**
+* Default batch size for paginating existing grants when revoking them
+* during completeAuthorization. Conservative for each KV list page.
+*/
+const DEFAULT_REVOKE_EXISTING_GRANTS_BATCH_SIZE = 50;
+function getRevokeExistingGrantsBatchSize(batchSize) {
+	if (batchSize === void 0) return DEFAULT_REVOKE_EXISTING_GRANTS_BATCH_SIZE;
+	if (!Number.isFinite(batchSize) || !Number.isInteger(batchSize) || batchSize < 1) throw new Error("revokeExistingGrantsBatchSize must be a positive integer.");
+	return Math.min(batchSize, MAX_KV_LIST_LIMIT);
+}
+/**
 * Length of generated token strings
 */
 const TOKEN_LENGTH = 32;
@@ -2558,6 +2645,14 @@ async function hashSecret(secret) {
 	return generateTokenId(secret);
 }
 /**
+* Decodes an application/x-www-form-urlencoded component.
+* @param value - The encoded component value
+* @returns The decoded component value
+*/
+function decodeFormUrlEncodedComponent(value) {
+	return decodeURIComponent(value.replace(/\+/g, " "));
+}
+/**
 * Generates a cryptographically secure random string
 * @param length - The length of the string to generate
 * @returns A random string of the specified length
@@ -2904,9 +2999,13 @@ var OAuthHelpersImpl = class {
 		if (!clientInfo || !isValidRedirectUri(redirectUri, clientInfo.redirectUris)) throw new Error("Invalid redirect URI. The redirect URI provided does not match any registered URI for this client.");
 		let grantsToRevoke = [];
 		if (options.revokeExistingGrants !== false) {
+			const batchSize = getRevokeExistingGrantsBatchSize(options.revokeExistingGrantsBatchSize);
 			let cursor;
 			do {
-				const page = await this.listUserGrants(options.userId, { cursor });
+				const page = await this.listUserGrants(options.userId, {
+					cursor,
+					limit: batchSize
+				});
 				for (const grant of page.items) if (grant.clientId === clientId) grantsToRevoke.push(grant.id);
 				cursor = page.cursor;
 			} while (cursor);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/workers-oauth-provider",
-  "version": "0.7.2",
+  "version": "0.8.1",
   "description": "OAuth provider for Cloudflare Workers",
   "main": "dist/oauth-provider.js",
   "types": "dist/oauth-provider.d.ts",
@@ -32,7 +32,7 @@
     "prettier": "^3.7.4",
     "tsdown": "^0.18.1",
     "typescript": "^5.9.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.8"
   },
   "repository": {
     "type": "git",