@cloudflare/workers-oauth-provider 0.9.1 → 0.10.1

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.
 
@@ -305,6 +321,10 @@ MCP 2026-07-28 deprecates DCR for new implementations in favor of CIMD. The endp
 
 Registration accepts only authentication methods, grants, and response types implemented by the configured provider, and rejects inconsistent grant/response combinations before storage. Omitted metadata uses the RFC 7591 defaults: `client_secret_basic`, `grant_types: ["authorization_code"]`, and `response_types: ["code"]`.
 
+An explicitly supplied `token_endpoint_auth_method` is enforced exactly. When it is omitted, no explicit-method marker is stored and the client may use either `client_secret_basic` or `client_secret_post`, provided the same stored secret validates. Client records written by earlier releases have no marker and receive the same compatibility. This never crosses between `none` and a secret method and does not apply to CIMD clients.
+
+Calling `OAuthHelpers.updateClient()` with `tokenEndpointAuthMethod` adds the marker; unrelated updates leave it unchanged.
+
 Related options:
 
 - `clientRegistrationTTL` controls the lifetime of dynamically registered clients. The default is 90 days.
@@ -329,16 +349,11 @@ The provider owns `tokenEndpoint`. It exchanges authorization codes for tokens,
 
 ## Resources and token audiences
 
-MCP clients must send the canonical MCP server URI as `resource` in authorization and token requests. The provider parses RFC 8707 resource indicators, stores the authorized resource on the grant, uses it as the access-token audience, and rejects resource expansion or audience mismatch.
-
-Resource policy follows `resourceMetadata.resource`:
-
-- When configured, authorization requests, token requests, and externally resolved tokens must use that one exact resource. `resourceMatchOriginOnly` cannot weaken this policy.
-- When omitted, valid resources are accepted. Token requests may inherit the authorization resource. If the authorization request also omits it, the provider uses the request origin as the default and issues an origin-bound token.
+MCP clients are required to send the canonical MCP server URI as `resource` in authorization and token requests. The provider tolerates omission for compatibility: when `resourceMetadata.resource` is configured, it is used as the canonical default and inherited by later token requests; otherwise a token request inherits any resource already stored on the grant. An explicit resource that does not match a bound grant is rejected with `invalid_target`.
 
-Path-aware audiences use path-boundary prefix matching. A token for `https://example.com/mcp` can be used at `/mcp/tools`, but not at `/mcp-other`. Split deployments and deployments requiring path isolation should configure the canonical resource explicitly.
+Legacy grants may have no stored resource. With no configured canonical resource, omitting `resource` preserves that unbound state. If a client supplies a resource during code exchange or refresh, it applies to that issued token but is not persisted as a new grant binding. Path-aware audiences use path-boundary prefix matching, so a token for `https://example.com/mcp` can be used at `/mcp/tools`, but not at `/mcp-other`.
 
-`resourceMatchOriginOnly` remains a migration option for grants created before path-aware resources were introduced. Do not enable it for a new deployment.
+`resourceMatchOriginOnly` is deprecated; its existing behavior is unchanged. Prefer `resourceMetadata.resource` for new deployments.
 
 ## Scopes and step-up authorization
 
@@ -415,7 +430,7 @@ Deleting a client through `OAuthHelpers.deleteClient()` also revokes its grants
 | `allowTokenExchangeGrant`          | Enable RFC 8693                                          | `false`                                     |
 | `tokenExchangeCallback`            | Update props, scopes, or lifetimes during token exchange | None                                        |
 | `resolveExternalToken`             | Validate external bearer credentials (advanced)          | None                                        |
-| `resourceMatchOriginOnly`          | Migration mode for old origin-only resource grants       | `false`                                     |
+| `resourceMatchOriginOnly`          | Deprecated origin-only resource comparison               | `false`                                     |
 | `enterpriseManagedAuthorization`   | Enable experimental ID-JAG grant support                 | Disabled                                    |
 | `onError`                          | Observe or replace OAuth error responses                 | Logs a warning                              |
 

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' | 'invalid_target' | '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
@@ -662,14 +685,16 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
    */
   clientIdMetadataDocumentEnabled?: boolean;
   /**
-   * When true, resource validation during token exchange compares origins only
-   * (scheme + host + port) instead of exact URI matching. This allows grants issued
-   * with an origin-only resource (e.g. `https://server.com`) to be used with
-   * path-aware resource requests (e.g. `https://server.com/mcp`), enabling seamless
-   * migration from pre-0.4.0 versions that stored origin-only resource URIs.
-   * Explicit `resourceMetadata.resource` configuration always uses exact matching.
+   * When true, requested-vs-granted resource validation compares origins only
+   * (scheme + host + port) instead of exact URIs. This allows an origin-only
+   * grant such as `https://server.com` to accept `https://server.com/mcp`, but
+   * also ignores path and query differences. Configured canonical resources
+   * always use exact matching.
    *
    * Defaults to false (strict exact matching per RFC 8707).
+   *
+   * @deprecated This comparison is unsafe for shared-origin multi-path or
+   * multi-tenant deployments. Prefer configuring `resourceMetadata.resource`.
    */
   resourceMatchOriginOnly?: boolean;
   /**
@@ -683,10 +708,11 @@ interface OAuthProviderOptions<Env = Cloudflare.Env> {
     /**
      * The protected resource identifier URL (RFC 9728 `resource` field).
      *
-     * Configuring this value pins authorization requests, token requests, and
-     * access-token audiences to this exact resource. If omitted, the provider
-     * accepts valid RFC 8707 resource indicators and uses the authorization
-     * request origin as the default when the client does not send one.
+     * Configuring this value pins grants and access-token audiences to this
+     * exact resource. An omitted authorization resource defaults to this value,
+     * and an omitted token-request resource inherits it from the grant. Without
+     * configuration, explicit RFC 8707 resource indicators are accepted and
+     * omission remains unbound for backwards compatibility.
      */
     resource?: string;
     /**
@@ -1511,4 +1537,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: [
@@ -29,21 +53,40 @@ function validateClientCapabilities(server, client) {
 	if (client.grantTypes.includes("authorization_code") !== client.responseTypes.includes("code")) throw new Error("grant_types authorization_code and response_types code must be registered together");
 	if (client.grantTypes.includes("implicit") !== client.responseTypes.includes("token")) throw new Error("grant_types implicit and response_types token must be registered together");
 }
+/**
+* Selects the capabilities from a Client ID Metadata Document that this
+* authorization server supports. CIMD documents may advertise extension
+* capabilities alongside the flow used with this server, so unsupported grant
+* and response types are omitted from the effective client metadata instead of
+* invalidating an otherwise usable client.
+*
+* The effective subset is still checked for grant/response consistency, and
+* token endpoint authentication must have a mutually supported method.
+*/
+function negotiateCimdClientCapabilities(server, client) {
+	const effective = {
+		grantTypes: client.grantTypes.filter((grantType) => server.grantTypes.includes(grantType)),
+		responseTypes: client.responseTypes.filter((responseType) => server.responseTypes.includes(responseType)),
+		tokenEndpointAuthMethod: client.tokenEndpointAuthMethod
+	};
+	validateClientCapabilities(server, effective);
+	return effective;
+}
 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 +95,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;
@@ -770,6 +813,15 @@ let GrantType = /* @__PURE__ */ function(GrantType$1) {
 	GrantType$1["JWT_BEARER"] = "urn:ietf:params:oauth:grant-type:jwt-bearer";
 	return GrantType$1;
 }({});
+function toPublicClientInfo(client) {
+	const { authMethodExplicit: _explicit, ...publicClient } = client;
+	return publicClient;
+}
+function isClientAuthMethodAllowed(client, presentedMethod, isClientMetadataDocument) {
+	if (presentedMethod === client.tokenEndpointAuthMethod) return true;
+	const isSecretMethod = (method) => method === "client_secret_basic" || method === "client_secret_post";
+	return !isClientMetadataDocument && client.authMethodExplicit === void 0 && isSecretMethod(client.tokenEndpointAuthMethod) && isSecretMethod(presentedMethod);
+}
 /**
 * OAuth 2.0 Provider implementation for Cloudflare Workers
 * Implements authorization code flow with support for refresh tokens
@@ -911,7 +963,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	/** Validate configured RFC 9728 protected resource metadata. */
 	validateResourceMetadataOptions(options) {
 		if (!options) return;
-		if (options.resource && !validateResourceUri(options.resource)) throw new TypeError("resourceMetadata.resource must be an absolute HTTP(S) URI without a fragment");
+		if (options.resource !== void 0 && !validateResourceUri(options.resource)) throw new TypeError("resourceMetadata.resource must be an absolute HTTP(S) URI without a fragment");
 		if (options.authorization_servers !== void 0) {
 			if (options.authorization_servers.length === 0) throw new TypeError("resourceMetadata.authorization_servers must contain at least one issuer");
 			for (const issuer of options.authorization_servers) {
@@ -1155,7 +1207,16 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		}
 		if (!clientInfo) return this.createInvalidClientResponse("Client not found", basicAuthenticationAttempted);
 		const presentedAuthMethod = basicAuthenticationAttempted ? "client_secret_basic" : formData.has("client_secret") ? "client_secret_post" : "none";
-		if (presentedAuthMethod !== clientInfo.tokenEndpointAuthMethod) return this.createInvalidClientResponse("Client authentication failed", basicAuthenticationAttempted);
+		const registeredAuthMethod = clientInfo.tokenEndpointAuthMethod;
+		if (!isClientAuthMethodAllowed(clientInfo, presentedAuthMethod, !!this.options.clientIdMetadataDocumentEnabled && this.isClientMetadataUrl(clientInfo.clientId))) return this.createInvalidClientResponse("Client authentication failed", basicAuthenticationAttempted, {
+			category: "client-authentication",
+			reason: "token_endpoint_auth_method_mismatch",
+			detail: {
+				clientId: clientInfo.clientId,
+				registeredMethod: registeredAuthMethod,
+				presentedMethod: presentedAuthMethod
+			}
+		});
 		if (presentedAuthMethod !== "none") {
 			if (!clientSecret) return this.createInvalidClientResponse("Client authentication failed: missing client_secret", basicAuthenticationAttempted);
 			if (!clientInfo.clientSecret) return this.createInvalidClientResponse("Client authentication failed: client has no registered secret", basicAuthenticationAttempted);
@@ -1647,7 +1708,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		let tokenScopes = this.downscope(requestedScopes, tokenSummary.scope);
 		const configuredResource = this.options.resourceMetadata?.resource;
 		if (configuredResource && !isExactResource(tokenSummary.audience, configuredResource)) throw new OAuthError("invalid_target", { description: "Subject token is not bound to the configured resource" });
-		const newAudience = this.resolveTokenResource(requestedResource, grantData.resource);
+		const newAudience = requestedResource === void 0 ? tokenSummary.audience : this.resolveTokenResource(requestedResource, grantData.resource);
 		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" });
@@ -2054,10 +2115,12 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				statusCode: 400
 			});
 		}
+		let authMethodWasExplicit;
 		let authMethod;
 		let grantTypes;
 		let responseTypes;
 		try {
+			authMethodWasExplicit = clientMetadata.token_endpoint_auth_method !== void 0;
 			authMethod = OAuthProviderImpl.validateStringField(clientMetadata.token_endpoint_auth_method) || "client_secret_basic";
 			grantTypes = OAuthProviderImpl.validateStringArray(clientMetadata.grant_types, "grant_types") || [GrantType.AUTHORIZATION_CODE];
 			responseTypes = OAuthProviderImpl.validateStringArray(clientMetadata.response_types, "response_types") || ["code"];
@@ -2097,7 +2160,8 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				grantTypes,
 				responseTypes,
 				registrationDate: Math.floor(Date.now() / 1e3),
-				tokenEndpointAuthMethod: authMethod
+				tokenEndpointAuthMethod: authMethod,
+				...authMethodWasExplicit ? { authMethodExplicit: true } : {}
 			};
 			if (!isPublicClient && hashedSecret) clientInfo.clientSecret = hashedSecret;
 		} catch (error) {
@@ -2329,19 +2393,26 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	}
 	/**
 	* Resolves an access-token audience from a token request and its authorization grant.
-	* Explicit resource configuration requires one exact value in both places. Without
-	* configuration, RFC 8707 downscoping is allowed and omission inherits the grant.
+	* A configured canonical resource is inherited when omitted but cannot be overridden.
+	* Without configuration, RFC 8707 downscoping is allowed, omission inherits a
+	* bound grant, and a legacy unbound grant retains the v0.8.2 behavior.
 	*/
 	resolveTokenResource(requestedResource, grantedResource) {
+		const resourceWasProvided = requestedResource !== void 0;
 		const requestedAudience = parseResourceParameter(requestedResource);
-		if (requestedResource && !requestedAudience) throw new OAuthError("invalid_target", { description: "The resource parameter must be a valid absolute URI without a fragment" });
+		if (resourceWasProvided && !requestedAudience) throw new OAuthError("invalid_target", { description: "The resource parameter must be a valid absolute URI without a fragment" });
+		const grantResourceWasStored = grantedResource !== void 0;
 		const grantedAudience = parseResourceParameter(grantedResource);
-		if (grantedResource && !grantedAudience) throw new OAuthError("invalid_target", { description: "The authorization grant contains an invalid resource" });
+		if (grantResourceWasStored && !grantedAudience) throw new OAuthError("invalid_target", { description: "The authorization grant contains an invalid resource" });
 		const configuredResource = this.options.resourceMetadata?.resource;
-		if (configuredResource && (!isExactResource(grantedResource, configuredResource) || !isExactResource(requestedResource, configuredResource))) throw new OAuthError("invalid_target", { description: `The resource parameter must exactly match ${configuredResource}` });
-		if (!configuredResource && requestedResource && !grantedResource) throw new OAuthError("invalid_target", { description: "Requested resource was not included in the authorization request" });
-		const originOnly = configuredResource ? false : !!this.options.resourceMatchOriginOnly;
-		if (requestedResource && grantedResource) {
+		if (configuredResource) {
+			if (resourceWasProvided && !isExactResource(requestedResource, configuredResource)) throw new OAuthError("invalid_target", { description: `The resource parameter must exactly match ${configuredResource}` });
+			if (isExactResource(grantedResource, configuredResource)) return configuredResource;
+			if (!grantResourceWasStored) return configuredResource;
+			throw new OAuthError("invalid_target", { description: "The authorization grant is not bound to the configured resource" });
+		}
+		const originOnly = !!this.options.resourceMatchOriginOnly;
+		if (resourceWasProvided && grantResourceWasStored) {
 			const requestedResources = Array.isArray(requestedResource) ? requestedResource : [requestedResource];
 			const grantedResources = Array.isArray(grantedResource) ? grantedResource : [grantedResource];
 			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" });
@@ -2546,13 +2617,13 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			if (!clientName?.trim()) throw new Error("client_name is required and must not be empty");
 			if (!redirectUris || redirectUris.length === 0) throw new Error("redirect_uris is required and must not be empty");
 			if (declaredAuthMethod && !OAuthProviderImpl.CIMD_ALLOWED_AUTH_METHODS.includes(declaredAuthMethod) || authMethodChoices && !authMethodChoices.some((method) => OAuthProviderImpl.CIMD_ALLOWED_AUTH_METHODS.includes(method))) throw new Error(`CIMD client does not support an accepted token endpoint authentication method. Supported methods: ${OAuthProviderImpl.CIMD_ALLOWED_AUTH_METHODS.join(", ")}`);
-			const grantTypes = OAuthProviderImpl.validateStringArray(rawMetadata.grant_types, "grant_types") || [GrantType.AUTHORIZATION_CODE];
-			const responseTypes = OAuthProviderImpl.validateStringArray(rawMetadata.response_types, "response_types") || ["code"];
+			const advertisedGrantTypes = OAuthProviderImpl.validateStringArray(rawMetadata.grant_types, "grant_types") || [GrantType.AUTHORIZATION_CODE];
+			const advertisedResponseTypes = OAuthProviderImpl.validateStringArray(rawMetadata.response_types, "response_types") || ["code"];
 			const effectiveAuthMethod = tokenEndpointAuthMethod || "none";
-			validateClientCapabilities(this.serverCapabilities, {
+			const { grantTypes, responseTypes } = negotiateCimdClientCapabilities(this.serverCapabilities, {
 				tokenEndpointAuthMethod: effectiveAuthMethod,
-				grantTypes,
-				responseTypes
+				grantTypes: advertisedGrantTypes,
+				responseTypes: advertisedResponseTypes
 			});
 			return {
 				clientId,
@@ -2861,6 +2932,7 @@ function audienceMatches(resourceServerUrl, audienceValue) {
 function parseResourceParameter(value) {
 	if (!value) return;
 	const uris = Array.isArray(value) ? value : [value];
+	if (uris.length === 0) return;
 	for (const uri of uris) if (typeof uri !== "string" || !validateResourceUri(uri)) return;
 	return value;
 }
@@ -3207,7 +3279,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 +3294,36 @@ 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);
+		};
+		const resourceWasProvided = resourceParam !== void 0;
 		let resource = parseResourceParameter(resourceParam);
-		if (resourceParam && !resource) throw new Error("The resource parameter must be a valid absolute URI without a fragment");
+		if (resourceWasProvided && !resource) withRedirect(new AuthorizationError("invalid_target", { 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}`);
-		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.`);
+		if (configuredResource) {
+			if (resourceWasProvided && !isExactResource(resource, configuredResource)) withRedirect(new AuthorizationError("invalid_target", { description: `The resource parameter must exactly match ${configuredResource}` }));
+			resource = configuredResource;
+		}
+		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,
@@ -3263,7 +3349,8 @@ var OAuthHelpersImpl = class {
 	* validating the metadata document fails.
 	*/
 	async lookupClient(clientId) {
-		return await this.provider.getClient(this.env, clientId);
+		const client = await this.provider.getClient(this.env, clientId);
+		return client ? toPublicClientInfo(client) : null;
 	}
 	/**
 	* Completes an authorization request by creating a grant and either:
@@ -3281,8 +3368,11 @@ 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.");
 		validateAuthorizationResponseType(this.provider.serverCapabilities, options.request.responseType, clientInfo.responseTypes);
 		const configuredResource = this.provider.options.resourceMetadata?.resource;
-		if (configuredResource && !isExactResource(options.request.resource, configuredResource)) throw new Error(`The resource parameter must exactly match ${configuredResource}`);
-		const effectiveResource = options.request.resource ?? options.request.issuer;
+		const resourceWasProvided = options.request.resource !== void 0;
+		const parsedResource = parseResourceParameter(options.request.resource);
+		if (resourceWasProvided && !parsedResource) throw new AuthorizationError("invalid_target", { description: "The resource parameter must be a valid absolute URI without a fragment" });
+		if (configuredResource && resourceWasProvided && !isExactResource(parsedResource, configuredResource)) throw new AuthorizationError("invalid_target", { description: `The resource parameter must exactly match ${configuredResource}` });
+		const effectiveResource = configuredResource ?? parsedResource;
 		validateAuthorizationPkce(this.provider.serverCapabilities, options.request, clientInfo);
 		let grantsToRevoke = [];
 		if (options.revokeExistingGrants !== false) {
@@ -3388,6 +3478,7 @@ var OAuthHelpersImpl = class {
 	*/
 	async createClient(clientInfo) {
 		const clientId = generateRandomString(16);
+		const authMethodWasExplicit = clientInfo.tokenEndpointAuthMethod !== void 0;
 		const tokenEndpointAuthMethod = clientInfo.tokenEndpointAuthMethod || "client_secret_basic";
 		const isPublicClient = tokenEndpointAuthMethod === "none";
 		const newClient = {
@@ -3408,7 +3499,8 @@ var OAuthHelpersImpl = class {
 			],
 			responseTypes: clientInfo.responseTypes || ["code"],
 			registrationDate: Math.floor(Date.now() / 1e3),
-			tokenEndpointAuthMethod
+			tokenEndpointAuthMethod,
+			...authMethodWasExplicit ? { authMethodExplicit: true } : {}
 		};
 		for (const uri of newClient.redirectUris) validateRedirectUriScheme(uri);
 		let clientSecret;
@@ -3417,7 +3509,7 @@ var OAuthHelpersImpl = class {
 			newClient.clientSecret = await hashSecret(clientSecret);
 		}
 		await this.env.OAUTH_KV.put(`client:${clientId}`, JSON.stringify(newClient));
-		const clientResponse = { ...newClient };
+		const clientResponse = toPublicClientInfo(newClient);
 		if (!isPublicClient && clientSecret) clientResponse.clientSecret = clientSecret;
 		return clientResponse;
 	}
@@ -3435,7 +3527,7 @@ var OAuthHelpersImpl = class {
 		const promises = response.keys.map(async (key) => {
 			const clientId = key.name.substring(7);
 			const client = await this.provider.getClient(this.env, clientId);
-			if (client) clients.push(client);
+			if (client) clients.push(toPublicClientInfo(client));
 		});
 		await Promise.all(promises);
 		return {
@@ -3452,7 +3544,8 @@ var OAuthHelpersImpl = class {
 	async updateClient(clientId, updates) {
 		const client = await this.provider.getClient(this.env, clientId);
 		if (!client) return null;
-		let authMethod = updates.tokenEndpointAuthMethod || client.tokenEndpointAuthMethod || "client_secret_basic";
+		const authMethodWasExplicit = updates.tokenEndpointAuthMethod !== void 0;
+		const authMethod = updates.tokenEndpointAuthMethod || client.tokenEndpointAuthMethod || "client_secret_basic";
 		const isPublicClient = authMethod === "none";
 		let secretToStore = client.clientSecret;
 		let originalSecret = void 0;
@@ -3465,14 +3558,15 @@ var OAuthHelpersImpl = class {
 			...client,
 			...updates,
 			clientId: client.clientId,
-			tokenEndpointAuthMethod: authMethod
+			tokenEndpointAuthMethod: authMethod,
+			authMethodExplicit: authMethodWasExplicit ? true : client.authMethodExplicit
 		};
 		if (!isPublicClient && secretToStore) updatedClient.clientSecret = secretToStore;
 		else delete updatedClient.clientSecret;
 		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 };
+		const response = toPublicClientInfo(updatedClient);
 		if (!isPublicClient && originalSecret) response.clientSecret = originalSecret;
 		return response;
 	}
@@ -3670,4 +3764,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.1",
   "description": "OAuth provider for Cloudflare Workers",
   "main": "dist/oauth-provider.js",
   "types": "dist/oauth-provider.d.ts",