@cloudflare/workers-oauth-provider 0.8.3 → 0.9.1

package/dist/oauth-provider.js

@@ -1,5 +1,70 @@
 import { WorkerEntrypoint } from "cloudflare:workers";
 
+//#region src/oauth-capabilities.ts
+const OAUTH_SCOPE_TOKEN_PATTERN = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
+function buildOAuthServerCapabilities(options) {
+	return {
+		grantTypes: [
+			"authorization_code",
+			"refresh_token",
+			...options.allowImplicitFlow ? ["implicit"] : [],
+			...options.allowTokenExchangeGrant ? ["urn:ietf:params:oauth:grant-type:token-exchange"] : [],
+			...options.enterpriseManagedAuthorization ? ["urn:ietf:params:oauth:grant-type:jwt-bearer"] : []
+		],
+		responseTypes: options.allowImplicitFlow ? ["code", "token"] : ["code"],
+		tokenEndpointAuthMethods: [
+			"client_secret_basic",
+			"client_secret_post",
+			"none"
+		],
+		codeChallengeMethods: options.allowPlainPKCE ? ["plain", "S256"] : ["S256"]
+	};
+}
+function validateClientCapabilities(server, client) {
+	if (!server.tokenEndpointAuthMethods.includes(client.tokenEndpointAuthMethod)) throw new Error(`Unsupported token_endpoint_auth_method: ${client.tokenEndpointAuthMethod}`);
+	const unsupportedGrant = client.grantTypes.find((grantType) => !server.grantTypes.includes(grantType));
+	if (unsupportedGrant) throw new Error(`Unsupported grant_type: ${unsupportedGrant}`);
+	const unsupportedResponse = client.responseTypes.find((responseType) => !server.responseTypes.includes(responseType));
+	if (unsupportedResponse) throw new Error(`Unsupported response_type: ${unsupportedResponse}`);
+	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");
+}
+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}`);
+}
+/** 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}`);
+	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.");
+	return effectiveMethod;
+}
+/** Validate authorization-request PKCE against server and client capabilities. */
+function validateAuthorizationPkce(server, request, client) {
+	if (request.codeChallenge) {
+		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.");
+}
+function validateAuthorizationServerScopes(scopes) {
+	if (!scopes) return;
+	if (scopes.some((scope) => !isValidOAuthScopeToken(scope))) throw new TypeError("scopesSupported must contain valid OAuth scope tokens");
+	if (new Set(scopes).size !== scopes.length) throw new TypeError("scopesSupported must not contain duplicate values");
+}
+function isValidOAuthScopeToken(scopeToken) {
+	return OAUTH_SCOPE_TOKEN_PATTERN.test(scopeToken);
+}
+
+//#endregion
 //#region src/ema/constants.ts
 /**
 * Constants for MCP Enterprise-Managed Authorization (EMA).
@@ -105,6 +170,7 @@ function emaErrorToWire(e) {
 		case "jwks_fetch_failed":
 		case "invalid_claim":
 		case "aud_mismatch":
+		case "unsupported_claim":
 		case "expired":
 		case "iat_in_future":
 		case "nbf_in_future":
@@ -473,7 +539,8 @@ function isWellFormedTrustedIssuer(issuer) {
 *
 * Enforces (in order):
 *   - presence + type of `iss`, `sub`, `aud`, `client_id`, `jti`, `exp`, `iat`
-*   - `aud` contains the AS's expected audience
+*   - `aud` is the AS's expected audience, as a string or single-element array
+*   - unsupported authorization-bearing claims fail closed
 *   - `client_id` matches the authenticated client
 *   - optional `resource` is a valid RFC 8707 URI and matches the AS's configured resource
 *   - the configured resource is used when `resource` is omitted
@@ -496,6 +563,10 @@ function validateIdJagClaims(input) {
 	if (!sub.ok) return sub;
 	const aud = readAudienceClaim(rawClaims);
 	if (!aud.ok) return aud;
+	for (const claim of ["authorization_details", "cnf"]) if (rawClaims[claim] !== void 0) return err({
+		reason: "unsupported_claim",
+		claim
+	});
 	const resource = rawClaims.resource === void 0 ? ok(configuredResource) : readRequiredString(rawClaims, "resource");
 	if (!resource.ok) return resource;
 	const claimClientId = readRequiredString(rawClaims, "client_id");
@@ -506,7 +577,7 @@ function validateIdJagClaims(input) {
 	if (!exp.ok) return exp;
 	const iat = readNumericDateClaim(rawClaims, "iat");
 	if (!iat.ok) return iat;
-	if (!(Array.isArray(aud.value) ? aud.value : [aud.value]).includes(expectedAudience)) return err({
+	if ((Array.isArray(aud.value) ? aud.value[0] : aud.value) !== expectedAudience) return err({
 		reason: "aud_mismatch",
 		expected: expectedAudience,
 		got: aud.value
@@ -657,7 +728,7 @@ function readRequiredString(claims, claimName) {
 function readAudienceClaim(claims) {
 	const aud = claims.aud;
 	if (typeof aud === "string" && aud.length > 0) return ok(aud);
-	if (Array.isArray(aud) && aud.length > 0 && aud.every((v) => typeof v === "string" && v.length > 0)) return ok(aud);
+	if (Array.isArray(aud) && aud.length === 1 && typeof aud[0] === "string" && aud[0].length > 0) return ok(aud);
 	return err({
 		reason: "invalid_claim",
 		claim: "aud"
@@ -679,6 +750,7 @@ const NO_CACHE_HEADERS = {
 	"Cache-Control": "no-store",
 	Pragma: "no-cache"
 };
+const BASIC_AUTH_CHALLENGE = "Basic realm=\"OAuth\"";
 if (!(typeof Cloudflare !== "undefined" && Cloudflare.compatibilityFlags?.global_fetch_strictly_public === true)) console.warn("CIMD (Client ID Metadata Document) is disabled: add '\"compatibility_flags\": [\"global_fetch_strictly_public\"]' to your wrangler.jsonc to enable. See: https://developers.cloudflare.com/workers/configuration/compatibility-flags/#global-fetch-strictly-public");
 /**
 * Enum representing the type of handler (ExportedHandler or WorkerEntrypoint)
@@ -789,6 +861,14 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			...options
 		};
 		if (!Number.isInteger(this.options.accessTokenTTL) || this.options.accessTokenTTL < KV_MIN_EXPIRATION_TTL_SECONDS) throw new TypeError(`accessTokenTTL must be an integer of at least ${KV_MIN_EXPIRATION_TTL_SECONDS} seconds (Cloudflare KV's minimum expiration window).`);
+		this.serverCapabilities = buildOAuthServerCapabilities({
+			allowImplicitFlow: !!this.options.allowImplicitFlow,
+			allowPlainPKCE: this.options.allowPlainPKCE === true,
+			allowTokenExchangeGrant: !!this.options.allowTokenExchangeGrant,
+			enterpriseManagedAuthorization: !!this.options.enterpriseManagedAuthorization
+		});
+		validateAuthorizationServerScopes(this.options.scopesSupported);
+		this.validateResourceMetadataOptions(this.options.resourceMetadata);
 		this.validateEmaOptions(this.options.enterpriseManagedAuthorization);
 		if (this.options.enterpriseManagedAuthorization) {
 			this.jwksProvider = createDefaultJwksProvider({ cacheTtlSeconds: this.options.enterpriseManagedAuthorization.jwksCacheTtlSeconds });
@@ -828,6 +908,25 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		};
 		throw new TypeError(`${name} must be either an ExportedHandler object with a fetch method or a class extending WorkerEntrypoint`);
 	}
+	/** 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.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) {
+				let parsed;
+				try {
+					parsed = new URL(issuer);
+				} catch {
+					throw new TypeError("resourceMetadata.authorization_servers must contain valid HTTPS issuer URLs");
+				}
+				if (parsed.protocol !== "https:" || parsed.search || parsed.hash) throw new TypeError("resourceMetadata.authorization_servers must contain valid HTTPS issuer URLs");
+			}
+		}
+		if (options.scopes_supported?.some((scope) => !isValidOAuthScopeToken(scope))) throw new TypeError("resourceMetadata.scopes_supported must contain valid OAuth scope tokens");
+		if (options.bearer_methods_supported?.some((method) => method !== "header")) throw new TypeError("resourceMetadata.bearer_methods_supported only supports 'header'");
+	}
 	/**
 	* Validates MCP Enterprise-Managed Authorization configuration at construction time.
 	*
@@ -887,7 +986,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		}
 		if (!env.OAUTH_PROVIDER) env.OAUTH_PROVIDER = this.createOAuthHelpers(env);
 		if (this.typedDefaultHandler.type === HandlerType.EXPORTED_HANDLER) return this.typedDefaultHandler.handler.fetch(request, env, ctx);
-		else return new this.typedDefaultHandler.handler(ctx, env).fetch(request);
+		return new this.typedDefaultHandler.handler(ctx, env).fetch(request);
 	}
 	/**
 	* Decodes a token and returns token data with decrypted props
@@ -980,6 +1079,13 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		if (!suffix || suffix === "/") return requestUrl.origin;
 		return `${requestUrl.origin}${suffix}`;
 	}
+	createInvalidClientResponse(description, basicAuthenticationAttempted, internal, request) {
+		return this.createErrorResponse("invalid_client", {
+			description,
+			statusCode: 401,
+			...basicAuthenticationAttempted ? { headers: { "WWW-Authenticate": BASIC_AUTH_CHALLENGE } } : {}
+		}, internal, request);
+	}
 	/**
 	* Parses and validates a token endpoint request (used for both token exchange and revocation)
 	* @param request - The HTTP request to parse
@@ -1016,55 +1122,50 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			});
 			body[key] = allValues.length > 1 ? allValues : value;
 		}
-		const authHeader = request.headers.get("Authorization");
+		const basicAuthorization = parseBasicAuthorizationHeader(request.headers.get("Authorization"));
+		const basicAuthenticationAttempted = basicAuthorization.kind !== "not-basic";
 		let clientId = "";
 		let clientSecret = "";
-		if (authHeader && authHeader.startsWith("Basic ")) {
-			if (body.client_id || body.client_secret) return this.createErrorResponse("invalid_request", {
+		if (basicAuthenticationAttempted) {
+			if (formData.has("client_id") || formData.has("client_secret")) return this.createErrorResponse("invalid_request", {
 				description: "Client must not use multiple authentication methods",
 				statusCode: 400
 			});
-			const credentials = atob(authHeader.substring(6));
-			const separatorIndex = credentials.indexOf(":");
-			if (separatorIndex === -1) return this.createErrorResponse("invalid_client", {
-				description: "Client authentication failed: invalid Basic credentials",
-				statusCode: 401
-			});
-			const id = credentials.substring(0, separatorIndex);
-			const secret = credentials.substring(separatorIndex + 1);
-			clientId = decodeFormUrlEncodedComponent(id);
-			clientSecret = decodeFormUrlEncodedComponent(secret);
+			if (basicAuthorization.kind === "malformed") return this.createInvalidClientResponse("Client authentication failed: invalid Basic credentials", basicAuthenticationAttempted);
+			clientId = basicAuthorization.clientId;
+			clientSecret = basicAuthorization.clientSecret;
 		} else {
 			clientId = body.client_id;
 			clientSecret = body.client_secret || "";
 		}
-		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", {
-			description: "Client not found",
-			statusCode: 401
-		});
-		if (!(clientInfo.tokenEndpointAuthMethod === "none")) {
-			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
-			});
+		if (!clientId) return this.createInvalidClientResponse("Client ID is required", basicAuthenticationAttempted);
+		let clientInfo;
+		try {
+			clientInfo = await this.getClient(env, clientId);
+		} catch (error) {
+			if (error instanceof CimdFetchError) return this.createInvalidClientResponse("Client not found", basicAuthenticationAttempted, {
+				category: "client-id-metadata-document",
+				reason: error.reason,
+				detail: {
+					metadataUrl: error.metadataUrl,
+					message: error.detail
+				}
+			}, request);
+			throw error;
+		}
+		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);
+		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);
+			if (await hashSecret(clientSecret) !== clientInfo.clientSecret) return this.createInvalidClientResponse("Client authentication failed: invalid client_secret", basicAuthenticationAttempted);
 		}
+		const isRevocationRequest = !body.grant_type && !!body.token;
 		return {
 			body,
 			clientInfo,
-			isRevocationRequest: !body.grant_type && !!body.token
+			isRevocationRequest
 		};
 	}
 	/**
@@ -1130,6 +1231,9 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		newResponse.headers.set("Access-Control-Allow-Origin", origin);
 		newResponse.headers.set("Access-Control-Allow-Methods", "*");
 		newResponse.headers.set("Access-Control-Allow-Headers", "Authorization, *");
+		const exposedHeaders = (newResponse.headers.get("Access-Control-Expose-Headers") ?? "").split(",").map((name) => name.trim()).filter(Boolean);
+		for (const requiredHeader of ["WWW-Authenticate", "Retry-After"]) if (!exposedHeaders.some((name) => name.toLowerCase() === requiredHeader.toLowerCase())) exposedHeaders.push(requiredHeader);
+		newResponse.headers.set("Access-Control-Expose-Headers", exposedHeaders.join(", "));
 		newResponse.headers.set("Access-Control-Max-Age", "86400");
 		return newResponse;
 	}
@@ -1144,15 +1248,9 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		const authorizeEndpoint = this.getFullEndpointUrl(this.options.authorizeEndpoint, requestUrl);
 		let registrationEndpoint = void 0;
 		if (this.options.clientRegistrationEndpoint) registrationEndpoint = this.getFullEndpointUrl(this.options.clientRegistrationEndpoint, requestUrl);
-		const responseTypesSupported = ["code"];
-		if (this.options.allowImplicitFlow) responseTypesSupported.push("token");
-		const grantTypesSupported = [GrantType.AUTHORIZATION_CODE, GrantType.REFRESH_TOKEN];
-		if (this.options.allowTokenExchangeGrant) grantTypesSupported.push(GrantType.TOKEN_EXCHANGE);
-		const authorizationGrantProfilesSupported = [];
-		if (this.options.enterpriseManagedAuthorization) {
-			grantTypesSupported.push(GrantType.JWT_BEARER);
-			authorizationGrantProfilesSupported.push(EMA_ID_JAG_GRANT_PROFILE);
-		}
+		const responseTypesSupported = this.serverCapabilities.responseTypes;
+		const grantTypesSupported = this.serverCapabilities.grantTypes;
+		const authorizationGrantProfilesSupported = this.options.enterpriseManagedAuthorization ? [EMA_ID_JAG_GRANT_PROFILE] : [];
 		const metadata = {
 			issuer: new URL(tokenEndpoint).origin,
 			authorization_endpoint: authorizeEndpoint,
@@ -1163,17 +1261,22 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			response_modes_supported: this.options.allowImplicitFlow ? ["query", "fragment"] : ["query"],
 			grant_types_supported: grantTypesSupported,
 			...authorizationGrantProfilesSupported.length > 0 ? { authorization_grant_profiles_supported: authorizationGrantProfilesSupported } : {},
-			token_endpoint_auth_methods_supported: [
-				"client_secret_basic",
-				"client_secret_post",
-				"none"
-			],
+			token_endpoint_auth_methods_supported: this.serverCapabilities.tokenEndpointAuthMethods,
 			revocation_endpoint: tokenEndpoint,
-			code_challenge_methods_supported: this.options.allowPlainPKCE !== false ? ["plain", "S256"] : ["S256"],
+			code_challenge_methods_supported: this.serverCapabilities.codeChallengeMethods,
+			authorization_response_iss_parameter_supported: true,
 			client_id_metadata_document_supported: !!this.options.clientIdMetadataDocumentEnabled && this.hasGlobalFetchStrictlyPublic()
 		};
 		return new Response(JSON.stringify(metadata), { headers: { "Content-Type": "application/json" } });
 	}
+	/** Scopes that are baseline requirements of the protected resource itself. */
+	getProtectedResourceScopes() {
+		return this.normalizeProtectedResourceScopes(this.options.resourceMetadata?.scopes_supported ?? []);
+	}
+	/** Deduplicate resource-facing scopes and remove authorization-server-only capabilities. */
+	normalizeProtectedResourceScopes(scopes) {
+		return [...new Set(scopes)].filter((scope) => scope !== "offline_access");
+	}
 	/**
 	* Handles the OAuth Protected Resource Metadata endpoint
 	* Implements RFC 9728 for OAuth Protected Resource Metadata
@@ -1184,10 +1287,11 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		const rm = this.options.resourceMetadata;
 		const tokenEndpointUrl = this.getFullEndpointUrl(this.options.tokenEndpoint, requestUrl);
 		const authServerOrigin = new URL(tokenEndpointUrl).origin;
+		const resourceScopes = this.getProtectedResourceScopes();
 		const metadata = {
 			resource: rm?.resource ?? this.deriveResourceIdentifier(requestUrl),
 			authorization_servers: rm?.authorization_servers ?? [authServerOrigin],
-			scopes_supported: rm?.scopes_supported ?? this.options.scopesSupported,
+			...resourceScopes.length > 0 ? { scopes_supported: resourceScopes } : {},
 			bearer_methods_supported: rm?.bearer_methods_supported ?? ["header"]
 		};
 		if (rm?.resource_name) metadata.resource_name = rm.resource_name;
@@ -1216,20 +1320,44 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		}
 	}
 	/**
-	* Build a structured OAuth `/token` error response from an OAuth error.
+	* Build a structured OAuth token-endpoint 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).
+	* The supported form is throwing this package's exported `OAuthError` from
+	* token issuance or `tokenExchangeCallback`. Anything else is re-thrown so
+	* unexpected failures still surface as 500s.
 	*/
 	createOAuthErrorResponse(error) {
 		if (!(error instanceof OAuthError)) return void 0;
 		return this.createErrorResponse(error.code, error.options);
 	}
 	/**
+	* Build a structured protected-resource response from an external-token error.
+	*
+	* Only this package's exported `ExternalTokenError` is converted. Standard
+	* bearer failures receive an RFC 6750 / RFC 9728 challenge unless the caller
+	* supplied one. Other errors retain the pre-existing behavior and are re-thrown.
+	*/
+	createExternalTokenErrorResponse(error, resourceMetadataUrl) {
+		if (!(error instanceof ExternalTokenError)) return void 0;
+		const headers = error.headers ?? {};
+		const hasChallenge = Object.keys(headers).some((name) => name.toLowerCase() === "www-authenticate");
+		const isBearerError = error.code === "invalid_token" && error.statusCode === 401 || error.code === "insufficient_scope" && error.statusCode === 403;
+		let challengeHeaders;
+		if (isBearerError && !hasChallenge) {
+			const requiredScopes = [...new Set(error.requiredScopes ?? [])];
+			if (requiredScopes.some((scope) => !isValidOAuthScopeToken(scope))) throw new TypeError("ExternalTokenError requiredScopes must contain valid OAuth scope tokens");
+			challengeHeaders = {
+				...headers,
+				"WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, error.code, void 0, requiredScopes)
+			};
+		}
+		return this.createErrorResponse(error.code, {
+			description: error.description,
+			statusCode: error.statusCode,
+			headers: challengeHeaders ?? headers
+		});
+	}
+	/**
 	* Handles the authorization code grant type
 	* Exchanges an authorization code for access and refresh tokens
 	* @param body - The parsed request body
@@ -1257,6 +1385,12 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			} catch {}
 			return this.createErrorResponse("invalid_grant", { description: "Authorization code already used" });
 		}
+		let codeChallengeMethod;
+		try {
+			codeChallengeMethod = grantData.codeChallenge ? validatePkceCodeChallengeMethod(this.serverCapabilities, grantData.codeChallengeMethod) : normalizePkceCodeChallengeMethod(grantData.codeChallengeMethod);
+		} catch (error) {
+			return this.createErrorResponse("invalid_grant", { description: error instanceof Error ? error.message : "Invalid PKCE code_challenge_method" });
+		}
 		const isPkceEnabled = !!grantData.codeChallenge;
 		if (!redirectUri && !isPkceEnabled) return this.createErrorResponse("invalid_request", { description: "redirect_uri is required when not using PKCE" });
 		if (redirectUri && !isValidRedirectUri(redirectUri, clientInfo.redirectUris)) return this.createErrorResponse("invalid_grant", { description: "Invalid redirect URI" });
@@ -1264,7 +1398,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		if (isPkceEnabled) {
 			if (!codeVerifier) return this.createErrorResponse("invalid_request", { description: "code_verifier is required for PKCE" });
 			let calculatedChallenge;
-			if (grantData.codeChallengeMethod === "S256") {
+			if (codeChallengeMethod === "S256") {
 				const data = new TextEncoder().encode(codeVerifier);
 				const hashBuffer = await crypto.subtle.digest("SHA-256", data);
 				const hashArray = Array.from(new Uint8Array(hashBuffer));
@@ -1272,14 +1406,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			} else calculatedChallenge = codeVerifier;
 			if (calculatedChallenge !== grantData.codeChallenge) return this.createErrorResponse("invalid_grant", { description: "Invalid PKCE code_verifier" });
 		}
-		const originOnly = !!this.options.resourceMatchOriginOnly;
-		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", { 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", { description: "The resource parameter must be a valid absolute URI without a fragment" });
+		const audience = this.resolveTokenResource(body.resource, grantData.resource);
 		let accessTokenTTL = this.options.accessTokenTTL;
 		let refreshTokenTTL = this.options.refreshTokenTTL;
 		const encryptionKey = await unwrapKeyWithToken(code, grantData.authCodeWrappedKey);
@@ -1390,6 +1517,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			const now$1 = Math.floor(Date.now() / 1e3);
 			if (grantData.expiresAt - now$1 < KV_MIN_EXPIRATION_TTL_SECONDS) return this.createErrorResponse("invalid_grant", { description: "Refresh token has expired" });
 		}
+		const audience = this.resolveTokenResource(body.resource, grantData.resource);
 		const newAccessToken = `${userId}:${grantId}:${generateRandomString(TOKEN_LENGTH)}`;
 		const accessTokenId = await generateTokenId(newAccessToken);
 		let accessTokenTTL = this.options.accessTokenTTL;
@@ -1461,14 +1589,6 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		grantData.refreshTokenId = newRefreshTokenId;
 		grantData.refreshTokenWrappedKey = newRefreshTokenWrappedKey;
 		await this.saveGrantWithTTL(env, grantKey, grantData, now);
-		const originOnly = !!this.options.resourceMatchOriginOnly;
-		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", { 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", { description: "The resource parameter must be a valid absolute URI without a fragment" });
 		const accessTokenData = {
 			id: accessTokenId,
 			grantId,
@@ -1525,18 +1645,9 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		const grantData = await env.OAUTH_KV.get(grantKey, { type: "json" });
 		if (!grantData) throw new OAuthError("invalid_grant", { description: "Grant not found" });
 		let tokenScopes = this.downscope(requestedScopes, tokenSummary.scope);
-		const originOnly = !!this.options.resourceMatchOriginOnly;
-		let newAudience = tokenSummary.audience;
-		if (requestedResource) {
-			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", { description: "Requested resource was not included in the authorization request" });
-			}
-			const parsedResource = parseResourceParameter(requestedResource);
-			if (!parsedResource) throw new OAuthError("invalid_target", { description: "The resource parameter must be a valid absolute URI without a fragment" });
-			newAudience = parsedResource;
-		}
+		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 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" });
@@ -1943,7 +2054,21 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				statusCode: 400
 			});
 		}
-		const authMethod = OAuthProviderImpl.validateStringField(clientMetadata.token_endpoint_auth_method) || "client_secret_basic";
+		let authMethod;
+		let grantTypes;
+		let responseTypes;
+		try {
+			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"];
+			validateClientCapabilities(this.serverCapabilities, {
+				tokenEndpointAuthMethod: authMethod,
+				grantTypes,
+				responseTypes
+			});
+		} catch (error) {
+			return this.createErrorResponse("invalid_client_metadata", { description: error instanceof Error ? error.message : "Invalid client metadata" });
+		}
 		const isPublicClient = authMethod === "none";
 		if (isPublicClient && this.options.disallowPublicClientRegistration) return this.createErrorResponse("invalid_client_metadata", { description: "Public client registration is not allowed" });
 		const clientId = generateRandomString(16);
@@ -1969,12 +2094,8 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				jwksUri: OAuthProviderImpl.validateOptionalUriField(clientMetadata.jwks_uri, "jwks_uri"),
 				i18n: OAuthProviderImpl.extractI18nFields(clientMetadata),
 				contacts: OAuthProviderImpl.validateStringArray(clientMetadata.contacts),
-				grantTypes: OAuthProviderImpl.validateStringArray(clientMetadata.grant_types) || [
-					GrantType.AUTHORIZATION_CODE,
-					GrantType.REFRESH_TOKEN,
-					...this.options.allowTokenExchangeGrant ? [GrantType.TOKEN_EXCHANGE] : []
-				],
-				responseTypes: OAuthProviderImpl.validateStringArray(clientMetadata.response_types) || ["code"],
+				grantTypes,
+				responseTypes,
 				registrationDate: Math.floor(Date.now() / 1e3),
 				tokenEndpointAuthMethod: authMethod
 			};
@@ -2016,7 +2137,6 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			grant_types: clientInfo.grantTypes,
 			response_types: clientInfo.responseTypes,
 			token_endpoint_auth_method: clientInfo.tokenEndpointAuthMethod,
-			registration_client_uri: `${this.options.clientRegistrationEndpoint}/${clientId}`,
 			client_id_issued_at: clientInfo.registrationDate
 		};
 		if (clientInfo.i18n) {
@@ -2046,10 +2166,12 @@ 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", {
-			description: "Missing or invalid access token",
-			statusCode: 401,
-			headers: { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token", "Missing or invalid access token") }
+		if (!authHeader || !authHeader.startsWith("Bearer ")) return new Response(null, {
+			status: 401,
+			headers: {
+				...NO_CACHE_HEADERS,
+				"WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl)
+			}
 		});
 		const accessToken = authHeader.substring(7);
 		const parts = accessToken.split(":");
@@ -2068,6 +2190,12 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			headers: { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") }
 		});
 		if (tokenData) {
+			const configuredResource = this.options.resourceMetadata?.resource;
+			if (configuredResource && !isExactResource(tokenData.audience, configuredResource)) return this.createErrorResponse("invalid_token", {
+				description: "Access token is not bound to the configured resource",
+				statusCode: 401,
+				headers: { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") }
+			});
 			const now = Math.floor(Date.now() / 1e3);
 			if (tokenData.expiresAt < now) return this.createErrorResponse("invalid_token", {
 				description: "Access token expired",
@@ -2076,7 +2204,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			});
 			if (tokenData.audience) {
 				const requestUrl = new URL(request.url);
-				const resourceServer = `${requestUrl.protocol}//${requestUrl.host}${requestUrl.pathname}`;
+				const resourceServer = `${requestUrl.protocol}//${requestUrl.host}${requestUrl.pathname}${requestUrl.search}`;
 				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,
@@ -2085,19 +2213,32 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			}
 			ctx.props = await decryptProps(await unwrapKeyWithToken(accessToken, tokenData.wrappedEncryptionKey), tokenData.grant.encryptedProps);
 		} else if (this.options.resolveExternalToken) {
-			const ext = await this.options.resolveExternalToken({
-				token: accessToken,
-				request,
-				env
-			});
+			let ext;
+			try {
+				ext = await this.options.resolveExternalToken({
+					token: accessToken,
+					request,
+					env
+				});
+			} catch (error) {
+				const response = this.createExternalTokenErrorResponse(error, resourceMetadataUrl);
+				if (response) return response;
+				throw error;
+			}
 			if (!ext) return this.createErrorResponse("invalid_token", {
 				description: "Invalid access token",
 				statusCode: 401,
 				headers: { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") }
 			});
+			const configuredResource = this.options.resourceMetadata?.resource;
+			if (configuredResource && !isExactResource(ext.audience, configuredResource)) return this.createErrorResponse("invalid_token", {
+				description: "External access token is not bound to the configured resource",
+				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}`;
+				const resourceServer = `${requestUrl.protocol}//${requestUrl.host}${requestUrl.pathname}${requestUrl.search}`;
 				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,
@@ -2164,7 +2305,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	*
 	* @param env - Cloudflare Worker environment variables
 	* @param clientId - The client ID to look up (can be a regular ID or an HTTPS URL for CIMD)
-	* @returns The client information, or null if not found
+	* @returns The client information, or null if the client does not exist. Null means
+	* definitive absence; failures to determine the answer throw instead (KV errors
+	* propagate, and a CIMD metadata fetch failure throws `CimdFetchError`), so an
+	* upstream outage is distinguishable from an unregistered client.
 	*/
 	async getClient(env, clientId) {
 		if (this.isClientMetadataUrl(clientId)) {
@@ -2177,13 +2321,34 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				return await this.fetchClientMetadataDocument(clientId);
 			} catch (error) {
 				console.warn(`CIMD fetch failed for ${clientId}:`, error instanceof Error ? error.message : error);
-				return null;
+				throw new CimdFetchError(clientId, error);
 			}
 		}
 		const clientKey = `client:${clientId}`;
 		return env.OAUTH_KV.get(clientKey, { type: "json" });
 	}
 	/**
+	* 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.
+	*/
+	resolveTokenResource(requestedResource, grantedResource) {
+		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" });
+		const grantedAudience = parseResourceParameter(grantedResource);
+		if (grantedResource && !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) {
+			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" });
+		}
+		return requestedAudience ?? grantedAudience;
+	}
+	/**
 	* Creates and stores an access token
 	* @param params - Options for creating the access token
 	* @returns The access token string
@@ -2255,7 +2420,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 		this.CIMD_FETCH_TIMEOUT_MS = 1e4;
 	}
 	static {
-		this.CIMD_ALLOWED_AUTH_METHODS = ["none", "private_key_jwt"];
+		this.CIMD_ALLOWED_AUTH_METHODS = ["none"];
 	}
 	/**
 	* Validates that a field is a string or undefined
@@ -2372,15 +2537,27 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			if (contentLength && parseInt(contentLength, 10) > OAuthProviderImpl.CIMD_MAX_SIZE_BYTES) throw new Error(`Client metadata exceeds size limit: ${contentLength} bytes (max ${OAuthProviderImpl.CIMD_MAX_SIZE_BYTES})`);
 			const rawMetadata = await this.readJsonWithSizeLimit(response, OAuthProviderImpl.CIMD_MAX_SIZE_BYTES);
 			const clientId = OAuthProviderImpl.validateStringField(rawMetadata.client_id, "client_id");
+			const clientName = OAuthProviderImpl.validateStringField(rawMetadata.client_name, "client_name");
 			const redirectUris = OAuthProviderImpl.validateStringArray(rawMetadata.redirect_uris, "redirect_uris");
-			const tokenEndpointAuthMethod = OAuthProviderImpl.validateStringField(rawMetadata.token_endpoint_auth_method, "token_endpoint_auth_method");
+			const declaredAuthMethod = OAuthProviderImpl.validateStringField(rawMetadata.token_endpoint_auth_method, "token_endpoint_auth_method");
+			const authMethodChoices = OAuthProviderImpl.validateStringArray(rawMetadata.token_endpoint_auth_methods_supported, "token_endpoint_auth_methods_supported");
+			const tokenEndpointAuthMethod = declaredAuthMethod ?? (authMethodChoices?.includes("none") ? "none" : void 0);
 			if (clientId !== metadataUrl) throw new Error(`client_id "${clientId}" does not match metadata URL "${metadataUrl}"`);
+			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 (tokenEndpointAuthMethod && !OAuthProviderImpl.CIMD_ALLOWED_AUTH_METHODS.includes(tokenEndpointAuthMethod)) throw new Error(`token_endpoint_auth_method "${tokenEndpointAuthMethod}" is not allowed for CIMD clients. Allowed methods: ${OAuthProviderImpl.CIMD_ALLOWED_AUTH_METHODS.join(", ")}`);
+			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 effectiveAuthMethod = tokenEndpointAuthMethod || "none";
+			validateClientCapabilities(this.serverCapabilities, {
+				tokenEndpointAuthMethod: effectiveAuthMethod,
+				grantTypes,
+				responseTypes
+			});
 			return {
 				clientId,
 				redirectUris,
-				clientName: OAuthProviderImpl.validateStringField(rawMetadata.client_name, "client_name"),
+				clientName,
 				clientUri: OAuthProviderImpl.validateOptionalUriField(rawMetadata.client_uri, "client_uri"),
 				logoUri: OAuthProviderImpl.validateOptionalUriField(rawMetadata.logo_uri, "logo_uri"),
 				policyUri: OAuthProviderImpl.validateOptionalUriField(rawMetadata.policy_uri, "policy_uri"),
@@ -2388,9 +2565,9 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 				jwksUri: OAuthProviderImpl.validateOptionalUriField(rawMetadata.jwks_uri, "jwks_uri"),
 				i18n: OAuthProviderImpl.extractI18nFields(rawMetadata),
 				contacts: OAuthProviderImpl.validateStringArray(rawMetadata.contacts, "contacts"),
-				grantTypes: OAuthProviderImpl.validateStringArray(rawMetadata.grant_types, "grant_types") || ["authorization_code"],
-				responseTypes: OAuthProviderImpl.validateStringArray(rawMetadata.response_types, "response_types") || ["code"],
-				tokenEndpointAuthMethod: tokenEndpointAuthMethod || "none"
+				grantTypes,
+				responseTypes,
+				tokenEndpointAuthMethod: effectiveAuthMethod
 			};
 		} finally {
 			clearTimeout(timeoutId);
@@ -2434,8 +2611,11 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	/**
 	* Builds a WWW-Authenticate header value with resource_metadata per RFC 9728 §5.1
 	*/
-	buildWwwAuthenticateHeader(resourceMetadataUrl, error, errorDescription) {
-		let header = `Bearer realm="OAuth", resource_metadata="${resourceMetadataUrl}", error="${error}"`;
+	buildWwwAuthenticateHeader(resourceMetadataUrl, error, errorDescription, requiredScopes = []) {
+		let header = `Bearer realm="OAuth", resource_metadata="${resourceMetadataUrl}"`;
+		if (error) header += `, error="${error}"`;
+		const challengeScopes = requiredScopes.length > 0 ? this.normalizeProtectedResourceScopes(requiredScopes) : this.getProtectedResourceScopes();
+		if (challengeScopes.length > 0) header += `, scope="${challengeScopes.join(" ")}"`;
 		if (errorDescription) header += `, error_description="${errorDescription}"`;
 		return header;
 	}
@@ -2447,7 +2627,7 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	* so the public response stays RFC-compliant and free of information leak
 	* while the deployer can still observe which check failed.
 	*/
-	createErrorResponse(code, options, internal) {
+	createErrorResponse(code, options, internal, request) {
 		const { description } = options;
 		const responseStatus = options.statusCode ?? 400;
 		const responseHeaders = {
@@ -2459,7 +2639,8 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 			description,
 			status: responseStatus,
 			headers: responseHeaders,
-			...internal ? { internal } : {}
+			...internal ? { internal } : {},
+			...request ? { request } : {}
 		});
 		if (customErrorResponse) return customErrorResponse;
 		const body = JSON.stringify({
@@ -2476,11 +2657,10 @@ var OAuthProviderImpl = class OAuthProviderImpl {
 	}
 };
 /**
-* Structured OAuth 2.0 error.
+* Structured OAuth 2.0 token-endpoint 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
+* Throw from a `tokenExchangeCallback` or any code it calls to surface a
+* standard OAuth token response (`{ error, error_description }`) instead of a
 * generic `500 Internal Server Error`.
 *
 * Anything thrown that is **not** an `OAuthError` continues to surface as
@@ -2530,6 +2710,61 @@ var OAuthError = class extends Error {
 	}
 };
 /**
+* Intentional public error from an external bearer-token validator.
+*
+* Throw only from `resolveExternalToken` when an expected validation outcome
+* should become a structured protected-resource response. Ordinary errors and
+* {@link OAuthError} retain their pre-existing behavior and propagate as
+* unexpected failures.
+*/
+var ExternalTokenError = class extends Error {
+	/**
+	* Creates an intentional external-token validation error.
+	* @param code - Standard OAuth error code to return
+	* @param options - Public response details
+	*/
+	constructor(code, options) {
+		super(options.description);
+		this.name = "ExternalTokenError";
+		this.code = code;
+		this.description = options.description;
+		this.statusCode = options.statusCode;
+		this.headers = options.headers;
+		this.requiredScopes = options.requiredScopes;
+	}
+};
+/**
+* Thrown when fetching a Client ID Metadata Document (CIMD) fails — the
+* server-to-server fetch errored, timed out, or returned an invalid document.
+* Distinct from a client that simply does not exist, which is reported as a
+* null client lookup result.
+*
+* At the token endpoint the provider handles this itself: the wire response
+* stays a generic `invalid_client` / "Client not found", and the failure is
+* reported through the `onError` hook's `internal` field (category
+* `client-id-metadata-document`) together with the originating `request`.
+*
+* `OAuthHelpers` methods that look up clients (`lookupClient`, and methods
+* built on it such as `exchangeToken`) let this error propagate to the
+* caller. Callers that previously relied on a `null` result for these
+* failures should catch it to preserve their error contract.
+*/
+var CimdFetchError = class extends Error {
+	/**
+	* Creates an error for a failed CIMD fetch or validation.
+	* @param metadataUrl - The CIMD URL that could not be resolved
+	* @param cause - The underlying fetch or validation failure
+	*/
+	constructor(metadataUrl, cause) {
+		const detail = cause instanceof Error ? cause.message : String(cause);
+		super(`CIMD fetch failed for ${metadataUrl}: ${detail}`);
+		this.reason = "metadata_resolution_failed";
+		this.name = "CimdFetchError";
+		this.metadataUrl = metadataUrl;
+		this.detail = detail;
+	}
+};
+/**
 * Default expiration time for access tokens (1 hour in seconds)
 */
 const DEFAULT_ACCESS_TOKEN_TTL = 3600;
@@ -2581,10 +2816,6 @@ function getRevokeExistingGrantsBatchSize(batchSize) {
 */
 const TOKEN_LENGTH = 32;
 /**
-* RFC 6749 Section 3.3 scope-token grammar.
-*/
-const OAUTH_SCOPE_TOKEN_PATTERN = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
-/**
 * Validates a resource URI per RFC 8707 Section 2
 * @param uri - The URI string to validate
 * @returns true if valid, false otherwise
@@ -2614,6 +2845,7 @@ function audienceMatches(resourceServerUrl, audienceValue) {
 		const resource = new URL(resourceServerUrl);
 		const audience = new URL(audienceValue);
 		if (resource.origin !== audience.origin) return false;
+		if (audience.search && resource.search !== audience.search) return false;
 		if (audience.pathname === "/" || audience.pathname === "") return true;
 		return resource.pathname === audience.pathname || resource.pathname.startsWith(audience.pathname + "/");
 	} catch {
@@ -2632,6 +2864,10 @@ function parseResourceParameter(value) {
 	for (const uri of uris) if (typeof uri !== "string" || !validateResourceUri(uri)) return;
 	return value;
 }
+/** Whether a request or audience names one exact configured resource. */
+function isExactResource(value, configuredResource) {
+	return value === configuredResource || Array.isArray(value) && value.length === 1 && value[0] === configuredResource;
+}
 /**
 * Checks if a requested resource matches a granted resource.
 * When originOnly is true, compares only the origin (scheme + host + port),
@@ -2654,6 +2890,29 @@ async function hashSecret(secret) {
 	return generateTokenId(secret);
 }
 /**
+* Parses RFC 6749 HTTP Basic client credentials.
+*/
+function parseBasicAuthorizationHeader(header) {
+	if (!header) return { kind: "not-basic" };
+	const schemeEnd = header.search(/[ \t]/);
+	if ((schemeEnd === -1 ? header : header.slice(0, schemeEnd)).toLowerCase() !== "basic") return { kind: "not-basic" };
+	if (schemeEnd === -1) return { kind: "malformed" };
+	const encodedCredentials = header.slice(schemeEnd).trim();
+	if (!encodedCredentials || /[ \t]/.test(encodedCredentials)) return { kind: "malformed" };
+	try {
+		const credentials = atob(encodedCredentials);
+		const separatorIndex = credentials.indexOf(":");
+		if (separatorIndex === -1) return { kind: "malformed" };
+		return {
+			kind: "credentials",
+			clientId: decodeFormUrlEncodedComponent(credentials.slice(0, separatorIndex)),
+			clientSecret: decodeFormUrlEncodedComponent(credentials.slice(separatorIndex + 1))
+		};
+	} catch {
+		return { kind: "malformed" };
+	}
+}
+/**
 * Decodes an application/x-www-form-urlencoded component.
 * @param value - The encoded component value
 * @returns The decoded component value
@@ -2777,9 +3036,6 @@ function parseJwtJsonPart(encoded) {
 		throw new Error("Malformed JWT part");
 	}
 }
-function isValidOAuthScopeToken(scopeToken) {
-	return OAUTH_SCOPE_TOKEN_PATTERN.test(scopeToken);
-}
 /**
 * Gets WebCrypto import and verify parameters for supported JOSE algorithms.
 */
@@ -2951,6 +3207,8 @@ 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 CimdFetchError when the client ID is a CIMD URL whose document cannot be resolved
 	*/
 	async parseAuthRequest(request) {
 		const url = new URL(request.url);
@@ -2960,20 +3218,26 @@ var OAuthHelpersImpl = class {
 		const scope = (url.searchParams.get("scope") || "").split(" ").filter(Boolean);
 		const state = url.searchParams.get("state") || "";
 		const codeChallenge = url.searchParams.get("code_challenge") || void 0;
-		const codeChallengeMethod = url.searchParams.get("code_challenge_method") || "plain";
+		const codeChallengeMethod = url.searchParams.get("code_challenge_method") || void 0;
+		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);
-		const resource = parseResourceParameter(resourceParam);
+		let resource = parseResourceParameter(resourceParam);
 		if (resourceParam && !resource) throw new Error("The resource parameter must be a valid absolute URI without a fragment");
-		if (responseType === "token" && !this.provider.options.allowImplicitFlow) throw new Error("The implicit grant flow is not enabled for this provider");
-		if (codeChallengeMethod === "plain" && this.provider.options.allowPlainPKCE === false) throw new Error("The plain PKCE method is not allowed. Use S256 instead.");
+		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 (clientInfo && redirectUri) {
-				if (!isValidRedirectUri(redirectUri, clientInfo.redirectUris)) throw new Error(`Invalid redirect URI. The redirect URI provided does not match any registered URI for 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.`);
+			validateAuthorizationResponseType(this.provider.serverCapabilities, responseType, clientInfo.responseTypes);
+			validateAuthorizationPkce(this.provider.serverCapabilities, {
+				responseType,
+				codeChallenge,
+				codeChallengeMethod
+			}, clientInfo);
 		}
 		return {
 			responseType,
@@ -2983,13 +3247,20 @@ var OAuthHelpersImpl = class {
 			state,
 			codeChallenge,
 			codeChallengeMethod,
-			resource
+			resource,
+			issuer
 		};
 	}
 	/**
 	* Looks up a client by its client ID
 	* @param clientId - The client ID to look up
-	* @returns A Promise resolving to the client info, or null if not found
+	* @returns A Promise resolving to the client info, or null if the client does not
+	* exist. Null means definitive absence; failures to determine the answer throw
+	* instead (KV errors propagate, and a CIMD metadata fetch failure throws
+	* `CimdFetchError`), so an upstream outage cannot masquerade as an unregistered
+	* client.
+	* @throws CimdFetchError when the client ID is a CIMD URL and fetching or
+	* validating the metadata document fails.
 	*/
 	async lookupClient(clientId) {
 		return await this.provider.getClient(this.env, clientId);
@@ -3000,12 +3271,19 @@ var OAuthHelpersImpl = class {
 	* - For implicit flow: generating an access token directly
 	* @param options - Options specifying the grant details
 	* @returns A Promise resolving to an object containing the redirect URL
+	* @throws Error when the request's response type is not permitted
+	* @throws CimdFetchError when the client ID is a CIMD URL whose document cannot be resolved
 	*/
 	async completeAuthorization(options) {
 		const { clientId, redirectUri } = options.request;
 		if (!clientId || !redirectUri) throw new Error("Client ID and Redirect URI are required in the authorization request.");
 		const clientInfo = await this.lookupClient(clientId);
 		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;
+		validateAuthorizationPkce(this.provider.serverCapabilities, options.request, clientInfo);
 		let grantsToRevoke = [];
 		if (options.revokeExistingGrants !== false) {
 			const batchSize = getRevokeExistingGrantsBatchSize(options.revokeExistingGrantsBatchSize);
@@ -3029,8 +3307,8 @@ var OAuthHelpersImpl = class {
 			const accessTokenTTL = this.provider.options.accessTokenTTL || DEFAULT_ACCESS_TOKEN_TTL;
 			const accessTokenExpiresAt = now + accessTokenTTL;
 			const accessTokenWrappedKey = await wrapKeyWithToken(accessToken, encryptionKey);
-			const audience = parseResourceParameter(options.request.resource);
-			if (options.request.resource && !audience) throw new Error("The resource parameter must be a valid absolute URI without a fragment");
+			const audience = parseResourceParameter(effectiveResource);
+			if (effectiveResource && !audience) throw new Error("The resource parameter must be a valid absolute URI without a fragment");
 			const grant = {
 				id: grantId,
 				clientId: options.request.clientId,
@@ -3039,7 +3317,7 @@ var OAuthHelpersImpl = class {
 				metadata: options.metadata,
 				encryptedProps: encryptedData,
 				createdAt: now,
-				resource: options.request.resource
+				resource: effectiveResource
 			};
 			const grantKey = `grant:${options.userId}:${grantId}`;
 			await this.env.OAUTH_KV.put(grantKey, JSON.stringify(grant));
@@ -3066,6 +3344,7 @@ var OAuthHelpersImpl = class {
 			fragment.set("expires_in", accessTokenTTL.toString());
 			fragment.set("scope", options.scope.join(" "));
 			if (options.request.state) fragment.set("state", options.request.state);
+			if (options.request.issuer) fragment.set("iss", options.request.issuer);
 			redirectUrl.hash = fragment.toString();
 			try {
 				await Promise.allSettled(grantsToRevoke.map((oldGrantId) => this.revokeGrant(oldGrantId, options.userId)));
@@ -3088,13 +3367,14 @@ var OAuthHelpersImpl = class {
 				authCodeWrappedKey,
 				codeChallenge: options.request.codeChallenge,
 				codeChallengeMethod: options.request.codeChallengeMethod,
-				resource: options.request.resource
+				resource: effectiveResource
 			};
 			const grantKey = `grant:${options.userId}:${grantId}`;
 			await this.env.OAUTH_KV.put(grantKey, JSON.stringify(grant), { expirationTtl: 600 });
 			const redirectUrl = new URL(options.request.redirectUri);
 			redirectUrl.searchParams.set("code", authCode);
 			if (options.request.state) redirectUrl.searchParams.set("state", options.request.state);
+			if (options.request.issuer) redirectUrl.searchParams.set("iss", options.request.issuer);
 			try {
 				await Promise.allSettled(grantsToRevoke.map((oldGrantId) => this.revokeGrant(oldGrantId, options.userId)));
 			} catch {}
@@ -3287,6 +3567,7 @@ var OAuthHelpersImpl = class {
 	* Implements OAuth 2.0 Token Exchange (RFC 8693)
 	* @param options - Options for token exchange including subject token and optional modifications
 	* @returns Promise resolving to token response with new access token
+	* @throws CimdFetchError when the grant's client ID is a CIMD URL whose document cannot be resolved
 	*/
 	async exchangeToken(options) {
 		const tokenSummary = await this.unwrapToken(options.subjectToken);
@@ -3389,4 +3670,4 @@ var OAuthHelpersImpl = class {
 var oauth_provider_default = OAuthProvider;
 
 //#endregion
-export { GrantType, OAuthError, OAuthProvider, base64UrlToBytes, oauth_provider_default as default, getJwtCryptoAlgorithms, getOAuthApi, isValidOAuthScopeToken, parseJwtJsonPart, resourceMatches, validateResourceUri };
+export { CimdFetchError, ExternalTokenError, GrantType, OAuthError, OAuthProvider, base64UrlToBytes, oauth_provider_default as default, getJwtCryptoAlgorithms, getOAuthApi, isValidOAuthScopeToken, parseJwtJsonPart, resourceMatches, validateResourceUri };