@cloudflare/workers-oauth-provider 0.5.0 → 0.6.0

package/README.md

@@ -306,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:

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.
@@ -889,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, PurgeOptions, PurgeResult, 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

@@ -285,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);
@@ -305,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,
@@ -441,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
@@ -459,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);
@@ -487,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;
@@ -554,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,
@@ -588,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);
@@ -636,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) {
@@ -675,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,
@@ -694,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",
@@ -722,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;
@@ -733,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;
@@ -811,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;
 		}
 	}
@@ -851,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;
@@ -909,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;
@@ -956,7 +1018,7 @@ 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" });
 		}
 		const clientKvOptions = {};
 		if (this.options.clientRegistrationTTL !== void 0) clientKvOptions.expirationTtl = this.options.clientRegistrationTTL;
@@ -998,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;
@@ -1010,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) {
@@ -1026,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);
 	}
@@ -1058,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)
@@ -1115,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;
 	}
 	/**
@@ -1278,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({
@@ -1296,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;
 	}
 };
 /**
@@ -2075,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.5.0",
+  "version": "0.6.0",
   "description": "OAuth provider for Cloudflare Workers",
   "main": "dist/oauth-provider.js",
   "types": "dist/oauth-provider.d.ts",