@cloudflare/workers-oauth-provider 0.9.1 → 0.10.0

package/README.md

@@ -36,7 +36,12 @@ See [Client registration](#client-registration) for the matching provider option
 The provider accepts either plain `ExportedHandler` objects or classes extending `WorkerEntrypoint`. This example uses both.
 
 ```ts
-import { OAuthProvider, type AuthRequest, type OAuthHelpers } from '@cloudflare/workers-oauth-provider';
+import {
+  AuthorizationError,
+  OAuthProvider,
+  type AuthRequest,
+  type OAuthHelpers,
+} from '@cloudflare/workers-oauth-provider';
 import { WorkerEntrypoint } from 'cloudflare:workers';
 
 interface AuthProps {
@@ -72,9 +77,18 @@ const defaultHandler: ExportedHandler<Env> = {
     let oauthRequest: AuthRequest;
     try {
       oauthRequest = await env.OAUTH_PROVIDER.parseAuthRequest(request);
-    } catch {
-      // Do not redirect until the client and redirect URI have been validated.
-      return new Response('Invalid authorization request', { status: 400 });
+    } catch (error) {
+      if (!(error instanceof AuthorizationError)) throw error;
+      if (!error.redirectUri) {
+        // Unknown clients and invalid redirects must be rendered locally.
+        return new Response(error.description, { status: 400 });
+      }
+      const redirect = new URL(error.redirectUri);
+      redirect.searchParams.set('error', error.code);
+      redirect.searchParams.set('error_description', error.description);
+      if (error.state) redirect.searchParams.set('state', error.state);
+      if (error.issuer) redirect.searchParams.set('iss', error.issuer);
+      return Response.redirect(redirect, 302);
     }
 
     const client = await env.OAUTH_PROVIDER.lookupClient(oauthRequest.clientId);
@@ -228,7 +242,9 @@ A typical flow has three steps:
 2. Authenticate the user, show consent, and decide which scopes to grant.
 3. Call `completeAuthorization()` and redirect to its returned `redirectTo` URL.
 
-`completeAuthorization()` repeats response-type validation before writing a grant or revoking existing grants. The application remains responsible for rendering local authorization errors and for constructing any terminal OAuth error redirect only after client and redirect URI validation.
+`parseAuthRequest()` throws an exported `AuthorizationError` for expected request validation failures. Its optional `redirectUri` is present only after the client and exact registered redirect URI have been validated. Without it, render the error locally and never redirect. With it, the application can safely construct an OAuth error redirect using the error's `code`, `description`, original `state`, and RFC 9207 `issuer`, as shown in the quick start.
+
+`completeAuthorization()` repeats response-type validation before writing a grant or revoking existing grants. Validation errors from reconstructed requests are also typed as `AuthorizationError`, but applications should not construct redirects from untrusted reconstructed values; the redirect context is attached only by `parseAuthRequest()`.
 
 `completeAuthorization()` stores a new grant and, by default, revokes existing grants for the same user and client after the new grant is safely stored. Set `revokeExistingGrants: false` only when the application intentionally allows concurrent grants for the same user and client.
 

package/dist/oauth-provider.d.ts

@@ -299,6 +299,29 @@ interface EmaOptions<Env = Cloudflare.Env> {
 }
 //#endregion
 //#region src/oauth-capabilities.d.ts
+type AuthorizationErrorCode = 'invalid_request' | 'unauthorized_client' | 'access_denied' | 'unsupported_response_type' | 'invalid_scope' | 'server_error' | 'temporarily_unavailable';
+interface AuthorizationErrorOptions {
+  /** Wire-safe OAuth authorization error description. */
+  description: string;
+  /** Exact registered redirect URI. Present only after client and redirect validation. */
+  redirectUri?: string;
+  /** Original client state, when supplied. */
+  state?: string;
+  /** Authorization server issuer for RFC 9207 error responses. */
+  issuer?: string;
+}
+/**
+ * Expected authorization-request validation failure. Absence of `redirectUri`
+ * means a caller MUST render locally and MUST NOT redirect.
+ */
+declare class AuthorizationError extends Error {
+  readonly code: AuthorizationErrorCode;
+  readonly description: string;
+  readonly redirectUri?: string;
+  readonly state?: string;
+  readonly issuer?: string;
+  constructor(code: AuthorizationErrorCode, options: AuthorizationErrorOptions);
+}
 declare function isValidOAuthScopeToken(scopeToken: string): boolean;
 //#endregion
 //#region src/oauth-provider.d.ts
@@ -1511,4 +1534,4 @@ declare function getJwtCryptoAlgorithms(alg: string): {
   verifyAlgorithm: Parameters<SubtleCrypto['verify']>[0];
 };
 //#endregion
-export { AuthRequest, CimdFetchError, ClientInfo, ClientRegistrationCallbackOptions, ClientRegistrationCallbackResult, CompleteAuthorizationOptions, type EmaClaimsMapper, type EmaClaimsMapperInput, type EmaClaimsMapperResult, type EmaIdJagClaims, type EmaOptions, type EmaTrustedIssuer, type EmaTrustedIssuerResolver, type EmaTrustedIssuerResolverInput, type EmaValidationError, ExchangeTokenOptions, ExternalTokenError, ExternalTokenErrorOptions, 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, AuthorizationError, type AuthorizationErrorCode, type AuthorizationErrorOptions, CimdFetchError, ClientInfo, ClientRegistrationCallbackOptions, ClientRegistrationCallbackResult, CompleteAuthorizationOptions, type EmaClaimsMapper, type EmaClaimsMapperInput, type EmaClaimsMapperResult, type EmaIdJagClaims, type EmaOptions, type EmaTrustedIssuer, type EmaTrustedIssuerResolver, type EmaTrustedIssuerResolverInput, type EmaValidationError, ExchangeTokenOptions, ExternalTokenError, ExternalTokenErrorOptions, 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

@@ -2,6 +2,30 @@ import { WorkerEntrypoint } from "cloudflare:workers";
 
 //#region src/oauth-capabilities.ts
 const OAUTH_SCOPE_TOKEN_PATTERN = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
+/**
+* Expected authorization-request validation failure. Absence of `redirectUri`
+* means a caller MUST render locally and MUST NOT redirect.
+*/
+var AuthorizationError = class extends Error {
+	constructor(code, options) {
+		super(options.description);
+		this.name = "AuthorizationError";
+		this.code = code;
+		this.description = options.description;
+		this.redirectUri = options.redirectUri;
+		this.state = options.state;
+		this.issuer = options.issuer;
+	}
+};
+/** @internal Attach context after exact client redirect validation succeeds. */
+function withAuthorizationRedirect(error, redirectUri, state, issuer) {
+	return new AuthorizationError(error.code, {
+		description: error.description,
+		redirectUri,
+		state,
+		issuer
+	});
+}
 function buildOAuthServerCapabilities(options) {
 	return {
 		grantTypes: [
@@ -30,20 +54,20 @@ function validateClientCapabilities(server, client) {
 	if (client.grantTypes.includes("implicit") !== client.responseTypes.includes("token")) throw new Error("grant_types implicit and response_types token must be registered together");
 }
 function validateAuthorizationResponseType(server, responseType, clientResponseTypes) {
-	if (!responseType) throw new Error("invalid_request: response_type is required");
-	if (!server.responseTypes.includes(responseType)) throw new Error(`unsupported_response_type: the authorization server does not support ${responseType}`);
-	if (!(clientResponseTypes ?? ["code"]).includes(responseType)) throw new Error(`unauthorized_client: the client is not registered for response_type ${responseType}`);
+	if (!responseType) throw new AuthorizationError("invalid_request", { description: "response_type is required" });
+	if (!server.responseTypes.includes(responseType)) throw new AuthorizationError("unsupported_response_type", { description: `The authorization server does not support response_type ${responseType}` });
+	if (!(clientResponseTypes ?? ["code"]).includes(responseType)) throw new AuthorizationError("unauthorized_client", { description: `The client is not registered for response_type ${responseType}` });
 }
 /** Parse a PKCE method, applying RFC 7636's default of `plain`. */
 function normalizePkceCodeChallengeMethod(method) {
 	const effectiveMethod = method ?? "plain";
-	if (effectiveMethod !== "plain" && effectiveMethod !== "S256") throw new Error(`Unsupported PKCE code_challenge_method: ${effectiveMethod}`);
+	if (effectiveMethod !== "plain" && effectiveMethod !== "S256") throw new AuthorizationError("invalid_request", { description: `Unsupported PKCE code_challenge_method: ${effectiveMethod}` });
 	return effectiveMethod;
 }
 /** Require a syntactically valid PKCE method that the server advertises. */
 function validatePkceCodeChallengeMethod(server, method) {
 	const effectiveMethod = normalizePkceCodeChallengeMethod(method);
-	if (!server.codeChallengeMethods.includes(effectiveMethod)) throw new Error("The plain PKCE method is not allowed. Use S256 instead.");
+	if (!server.codeChallengeMethods.includes(effectiveMethod)) throw new AuthorizationError("invalid_request", { description: "The plain PKCE method is not allowed. Use S256 instead." });
 	return effectiveMethod;
 }
 /** Validate authorization-request PKCE against server and client capabilities. */
@@ -52,8 +76,8 @@ function validateAuthorizationPkce(server, request, client) {
 		validatePkceCodeChallengeMethod(server, request.codeChallengeMethod);
 		return;
 	}
-	if (request.codeChallengeMethod) throw new Error("PKCE code_challenge is required when code_challenge_method is provided.");
-	if (request.responseType === "code" && client.tokenEndpointAuthMethod === "none") throw new Error("Public clients must use PKCE with the authorization code flow.");
+	if (request.codeChallengeMethod) throw new AuthorizationError("invalid_request", { description: "PKCE code_challenge is required when code_challenge_method is provided." });
+	if (request.responseType === "code" && client.tokenEndpointAuthMethod === "none") throw new AuthorizationError("invalid_request", { description: "Public clients must use PKCE with the authorization code flow." });
 }
 function validateAuthorizationServerScopes(scopes) {
 	if (!scopes) return;
@@ -3207,7 +3231,7 @@ var OAuthHelpersImpl = class {
 	* Parses an OAuth authorization request from the HTTP request
 	* @param request - The HTTP request containing OAuth parameters
 	* @returns The parsed authorization request parameters
-	* @throws Error when the response type is missing, unsupported, or not registered for the client
+	* @throws AuthorizationError for expected authorization-request validation failures
 	* @throws CimdFetchError when the client ID is a CIMD URL whose document cannot be resolved
 	*/
 	async parseAuthRequest(request) {
@@ -3222,22 +3246,33 @@ var OAuthHelpersImpl = class {
 		const issuer = this.provider.getAuthorizationServerIssuer(url);
 		const resourceParams = url.searchParams.getAll("resource");
 		const resourceParam = resourceParams.length > 0 ? resourceParams.length === 1 ? resourceParams[0] : resourceParams : void 0;
-		validateRedirectUriScheme(redirectUri);
+		if (!clientId) throw new AuthorizationError("invalid_request", { description: "client_id is required" });
+		const clientInfo = await this.lookupClient(clientId);
+		if (!clientInfo) throw new AuthorizationError("invalid_request", { description: "Invalid client_id" });
+		try {
+			validateRedirectUriScheme(redirectUri);
+		} catch {
+			throw new AuthorizationError("invalid_request", { description: "Invalid redirect URI" });
+		}
+		if (!redirectUri || !isValidRedirectUri(redirectUri, clientInfo.redirectUris)) throw new AuthorizationError("invalid_request", { description: "Invalid redirect URI" });
+		const withRedirect = (error) => {
+			throw withAuthorizationRedirect(error, redirectUri, state || void 0, issuer);
+		};
 		let resource = parseResourceParameter(resourceParam);
-		if (resourceParam && !resource) throw new Error("The resource parameter must be a valid absolute URI without a fragment");
+		if (resourceParam && !resource) withRedirect(new AuthorizationError("invalid_request", { description: "The resource parameter must be a valid absolute URI without a fragment" }));
 		const configuredResource = this.provider.options.resourceMetadata?.resource;
-		if (configuredResource && !isExactResource(resource, configuredResource)) throw new Error(`The resource parameter must exactly match ${configuredResource}`);
+		if (configuredResource && !isExactResource(resource, configuredResource)) withRedirect(new AuthorizationError("invalid_request", { description: `The resource parameter must exactly match ${configuredResource}` }));
 		resource ??= url.origin;
-		if (clientId) {
-			const clientInfo = await this.lookupClient(clientId);
-			if (!clientInfo) throw new Error(`Invalid client. The clientId provided does not match to this client.`);
-			if (!redirectUri || !isValidRedirectUri(redirectUri, clientInfo.redirectUris)) throw new Error(`Invalid redirect URI. The redirect URI provided does not match any registered URI for this client.`);
+		try {
 			validateAuthorizationResponseType(this.provider.serverCapabilities, responseType, clientInfo.responseTypes);
 			validateAuthorizationPkce(this.provider.serverCapabilities, {
 				responseType,
 				codeChallenge,
 				codeChallengeMethod
 			}, clientInfo);
+		} catch (error) {
+			if (error instanceof AuthorizationError) withRedirect(error);
+			throw error;
 		}
 		return {
 			responseType,
@@ -3670,4 +3705,4 @@ var OAuthHelpersImpl = class {
 var oauth_provider_default = OAuthProvider;
 
 //#endregion
-export { CimdFetchError, ExternalTokenError, GrantType, OAuthError, OAuthProvider, base64UrlToBytes, oauth_provider_default as default, getJwtCryptoAlgorithms, getOAuthApi, isValidOAuthScopeToken, parseJwtJsonPart, resourceMatches, validateResourceUri };
+export { AuthorizationError, CimdFetchError, ExternalTokenError, GrantType, OAuthError, OAuthProvider, base64UrlToBytes, oauth_provider_default as default, getJwtCryptoAlgorithms, getOAuthApi, isValidOAuthScopeToken, parseJwtJsonPart, resourceMatches, validateResourceUri };

package/package.json

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