@cloudflare/workers-oauth-provider 0.10.4 → 1.0.0

package/dist/oauth-provider.js

@@ -911,6 +911,96 @@ async function verifyIdJagSignature(input) {
 	}
 }
 
+//#endregion
+//#region src/oauth-resource.ts
+/**
+* Loopback hosts where a plain `http` scheme is accepted for local development.
+* Matches RFC 8252 §7.3 loopback handling: 127.0.0.0/8, ::1, and `localhost`.
+*/
+function isLoopbackHostname(hostname) {
+	const host = hostname.toLowerCase();
+	if (host === "localhost" || host === "::1" || host === "[::1]") return true;
+	const ipv4 = /^127\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+	return ipv4 !== null && ipv4.slice(1).every((octet) => Number(octet) <= 255);
+}
+/**
+* Whether a canonical resource, issuer, or endpoint URL uses an accepted
+* scheme: `https`, or `http` on a loopback host so `wrangler dev` works on
+* http://localhost. Workers are always served over `https`, so there is no
+* deployment in which cleartext OAuth traffic to a remote host is correct,
+* and no option exists to allow it.
+*/
+function hasAcceptedCanonicalScheme(url) {
+	return url.protocol === "https:" || url.protocol === "http:" && isLoopbackHostname(url.hostname);
+}
+/** Validate an RFC 3986-safe HTTP(S) resource identifier for RFC 8707. */
+function validateResourceUri(uri) {
+	if (!uri || typeof uri !== "string") return false;
+	if (!/^[\x21-\x7e]+$/.test(uri) || /["\\#]/.test(uri) || !/^[A-Za-z][A-Za-z0-9+.-]*:\/\/[^/?#]+(?:\/[^?#]*)?(?:\?[^#]*)?$/.test(uri) || /%(?![0-9A-Fa-f]{2})/.test(uri) || !/^[A-Za-z0-9:/?@!$&'()*+,;=._~%\[\]-]+$/.test(uri)) return false;
+	try {
+		const parsed = new URL(uri);
+		return parsed.protocol === "http:" || parsed.protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+/**
+* Whether a requested resource identifies a granted or configured resource.
+* Only ASCII case in the URI scheme and host is ignored, and an empty path is
+* equivalent to `/` (RFC 3986 §6.2.3), so a client that round-trips
+* `https://example.com` through a URL parser as `https://example.com/` still
+* names it. Port, path, query, a trailing slash after a path segment, user
+* information, and every other byte remain significant.
+*/
+function resourceMatches(requested, granted) {
+	const foldedRequested = foldResourceSchemeAndHost(requested);
+	const foldedGranted = foldResourceSchemeAndHost(granted);
+	if (foldedRequested === void 0 || foldedGranted === void 0) return false;
+	return normalizeEmptyPath(foldedRequested) === normalizeEmptyPath(foldedGranted);
+}
+/**
+* Fold only the URI components whose comparison is ASCII case-insensitive: the
+* scheme and the host. A configured identifier is canonical when folding it is
+* the identity.
+*/
+function foldResourceSchemeAndHost(resource) {
+	const schemeSeparator = resource.indexOf("://");
+	if (schemeSeparator <= 0) return void 0;
+	const authorityStart = schemeSeparator + 3;
+	const authorityEndOffset = resource.slice(authorityStart).search(/[/?#]/);
+	const authorityEnd = authorityEndOffset === -1 ? resource.length : authorityStart + authorityEndOffset;
+	const authority = resource.slice(authorityStart, authorityEnd);
+	const hostStart = authority.lastIndexOf("@") + 1;
+	let hostEnd;
+	if (authority[hostStart] === "[") {
+		const closingBracket = authority.indexOf("]", hostStart + 1);
+		if (closingBracket === -1) return void 0;
+		hostEnd = closingBracket + 1;
+	} else {
+		const portSeparator = authority.indexOf(":", hostStart);
+		hostEnd = portSeparator === -1 ? authority.length : portSeparator;
+	}
+	const asciiLower = (value) => value.replace(/[A-Z]/g, (character) => character.toLowerCase());
+	return asciiLower(resource.slice(0, schemeSeparator)) + "://" + authority.slice(0, hostStart) + asciiLower(authority.slice(hostStart, hostEnd)) + authority.slice(hostEnd) + resource.slice(authorityEnd);
+}
+/** RFC 3986 §6.2.3: for http and https an empty path is equivalent to "/". */
+function normalizeEmptyPath(resource) {
+	const authorityStart = resource.indexOf("://") + 3;
+	const pathOffset = resource.slice(authorityStart).search(/[/?#]/);
+	if (pathOffset === -1) return `${resource}/`;
+	const pathStart = authorityStart + pathOffset;
+	return resource[pathStart] === "/" ? resource : `${resource.slice(0, pathStart)}/${resource.slice(pathStart)}`;
+}
+/**
+* Whether a request carries every query parameter of a canonical resource. A
+* query-bearing resource identifier names a more specific resource: a request
+* may add parameters of its own but must preserve the resource's.
+*/
+function requestCarriesResourceQuery(requestUrl, resourceUrl) {
+	for (const [name, value] of resourceUrl.searchParams) if (!requestUrl.searchParams.getAll(name).includes(value)) return false;
+	return true;
+}
+
 //#endregion
 //#region src/ema/validators.ts
 /**
@@ -1036,7 +1126,7 @@ function isWellFormedTrustedIssuer(issuer) {
 *   - `scope` (if present) conforms to RFC 6749 §3.3 grammar
 */
 function validateIdJagClaims(input) {
-	const { rawClaims, trustedIssuer, expectedAudience, clientId, configuredResource, matchOriginOnly } = input;
+	const { rawClaims, trustedIssuer, expectedAudience, clientId, configuredResource } = input;
 	const { now, clockSkewSeconds, maxAssertionLifetimeSeconds } = input;
 	const iss = readRequiredString(rawClaims, "iss");
 	if (!iss.ok) return iss;
@@ -1076,7 +1166,7 @@ function validateIdJagClaims(input) {
 		reason: "resource_invalid",
 		resource: resource.value
 	});
-	if (!resourceMatches(resource.value, configuredResource, matchOriginOnly)) return err({
+	if (!resourceMatches(resource.value, configuredResource)) return err({
 		reason: "resource_mismatch",
 		expected: configuredResource,
 		got: resource.value
@@ -1228,6 +1318,237 @@ function readNumericDateClaim(claims, claimName) {
 	return ok(value);
 }
 
+//#endregion
+//#region src/oauth-resource-server.ts
+const PROTECTED_RESOURCE_WELL_KNOWN_PREFIX$1 = "/.well-known/oauth-protected-resource";
+const NO_CACHE_HEADERS$1 = {
+	"Cache-Control": "no-store",
+	Pragma: "no-cache"
+};
+/**
+* The response for a valid token that lacks the scopes an operation needs (RFC 6750 §3.1,
+* MCP scope challenge handling): `403` with `WWW-Authenticate: Bearer error="insufficient_scope"`,
+* the `scope` the operation requires and the `resource_metadata` URL the client already knows.
+* Name every scope the operation needs in one response; clients treat the list as complete.
+*
+* ```ts
+* if (!ctx.auth.scope.includes('calendar:write')) return insufficientScope(ctx.auth, ['calendar:write']);
+* ```
+*/
+function insufficientScope(auth, scope, description) {
+	if (!Array.isArray(scope) || scope.length === 0 || scope.some((value) => !isValidScopeToken(value))) throw new TypeError("insufficientScope requires at least one valid OAuth scope token");
+	let challenge = `Bearer realm="OAuth", error="insufficient_scope", scope="${[...new Set(scope)].join(" ")}"`;
+	challenge += `, resource_metadata="${getResourceMetadataUrl(auth.audience)}"`;
+	if (description !== void 0) {
+		const quotable = description.replace(/["\\]/g, "").replace(/[^\x21-\x7e]+/g, " ").trim();
+		if (quotable) challenge += `, error_description="${quotable}"`;
+	}
+	return new Response(JSON.stringify({
+		error: "insufficient_scope",
+		...description !== void 0 ? { error_description: description } : {}
+	}), {
+		status: 403,
+		headers: {
+			...NO_CACHE_HEADERS$1,
+			"Content-Type": "application/json",
+			"WWW-Authenticate": challenge
+		}
+	});
+}
+/**
+* One OAuth protected resource, in the authorization server's Worker or its own. Publishes
+* RFC 9728 metadata, challenges unauthenticated requests, validates the bearer token through
+* the configured `validateToken`, enforces audience and expiry on what it returns, and routes
+* only the canonical resource and its descendants to the application handler.
+*
+* `export default new OAuthResourceServer({ … })`, or dispatch to `fetch()` from your own
+* router, exactly as with `OAuthAuthorizationServer`.
+*/
+var OAuthResourceServer = class {
+	#options;
+	#validated;
+	constructor(options) {
+		this.#validated = validateOptions(options);
+		this.#options = options;
+	}
+	async fetch(request, env, ctx) {
+		const options = this.#options;
+		const validated = this.#validated;
+		const url = new URL(request.url);
+		if (isProtectedResourceMetadataPath(url)) {
+			if (request.method === "OPTIONS") return addCorsHeaders(new Response(null, {
+				status: 204,
+				headers: { "Content-Length": "0" }
+			}), request);
+			if (!isMetadataUrlRequest(url, validated.metadataUrl)) return addCorsHeaders(new Response(null, { status: 404 }), request);
+			if (request.method !== "GET" && request.method !== "HEAD") return addCorsHeaders(new Response(null, {
+				status: 405,
+				headers: { Allow: "GET, HEAD, OPTIONS" }
+			}), request);
+			const metadata = Response.json(validated.metadata, { headers: NO_CACHE_HEADERS$1 });
+			return addCorsHeaders(request.method === "HEAD" ? new Response(null, {
+				status: 200,
+				headers: metadata.headers
+			}) : metadata, request);
+		}
+		if (!isCanonicalResourceRequest(url, validated.resourceUrl)) return new Response(null, { status: 404 });
+		if (request.method === "OPTIONS") return addCorsHeaders(new Response(null, {
+			status: 204,
+			headers: { "Content-Length": "0" }
+		}), request);
+		const token = parseBearerToken(request.headers.get("Authorization"));
+		if (!token) return addCorsHeaders(createBearerChallenge(url, validated, false), request);
+		let validation;
+		try {
+			validation = await options.validateToken(env, request)(validated.resource, token);
+		} catch {
+			return addCorsHeaders(createValidationUnavailableResponse(), request);
+		}
+		if (!isValidTokenValidation(validation, validated.resource)) return addCorsHeaders(createBearerChallenge(url, validated, true), request);
+		const context = ctx;
+		context.props = validation.props;
+		context.auth = {
+			token,
+			audience: validated.resource,
+			...validation.expiresAt !== void 0 ? { expiresAt: validation.expiresAt } : {},
+			scope: [...validation.scope ?? []],
+			...validation.userId !== void 0 ? { userId: validation.userId } : {},
+			...validation.clientId !== void 0 ? { clientId: validation.clientId } : {}
+		};
+		const handler = options.handler;
+		return addCorsHeaders(isEntrypointClass(handler) ? await new handler(context, env).fetch(request) : await handler.fetch(request, env, context), request);
+	}
+};
+function validateOptions(options) {
+	if (!options || typeof options !== "object") throw new TypeError("OAuth resource server options are required");
+	if (!options.handler || !isEntrypointClass(options.handler) && typeof options.handler.fetch !== "function") throw new TypeError("handler must provide a fetch function or extend WorkerEntrypoint");
+	if (typeof options.validateToken !== "function") throw new TypeError("validateToken must be a function");
+	const resource = options.resourceMetadata?.resource;
+	const resourceUrl = parseCanonicalUrl(resource);
+	if (!resourceUrl) throw new TypeError("resourceMetadata.resource must be a canonical absolute HTTPS URI without a fragment (http is accepted only on a loopback host)");
+	if (isProtectedResourceMetadataPath(resourceUrl)) throw new TypeError(`resourceMetadata.resource must not be inside the ${PROTECTED_RESOURCE_WELL_KNOWN_PREFIX$1} namespace`);
+	const authorizationServers = options.resourceMetadata.authorization_servers;
+	if (!Array.isArray(authorizationServers) || authorizationServers.length === 0) throw new TypeError("resourceMetadata.authorization_servers must contain at least one issuer");
+	for (const issuer of authorizationServers) {
+		const issuerUrl = parseCanonicalUrl(issuer);
+		if (!issuerUrl || issuerUrl.search || issuerUrl.hash) throw new TypeError("resourceMetadata.authorization_servers must contain canonical HTTPS issuer URLs (http is accepted only on a loopback host)");
+	}
+	const bearerMethods = options.resourceMetadata.bearer_methods_supported;
+	if (bearerMethods !== void 0 && (bearerMethods.length !== 1 || bearerMethods[0] !== "header")) throw new TypeError("resourceMetadata.bearer_methods_supported only supports 'header'");
+	const configuredScopes = options.resourceMetadata.scopes_supported ?? [];
+	if (configuredScopes.some((scope) => !isValidScopeToken(scope))) throw new TypeError("resourceMetadata.scopes_supported must contain valid OAuth scope tokens");
+	const resourceScopes = [...new Set(configuredScopes)].filter((scope) => scope !== "offline_access");
+	return {
+		resource,
+		resourceUrl,
+		metadataUrl: new URL(getResourceMetadataUrl(resource)),
+		metadata: {
+			resource,
+			authorization_servers: [...authorizationServers],
+			...resourceScopes.length ? { scopes_supported: resourceScopes } : {},
+			bearer_methods_supported: bearerMethods ? [...bearerMethods] : ["header"],
+			...options.resourceMetadata.resource_name !== void 0 ? { resource_name: options.resourceMetadata.resource_name } : {}
+		}
+	};
+}
+function parseCanonicalUrl(value) {
+	if (typeof value !== "string" || !validateResourceUri(value)) return null;
+	let parsed;
+	try {
+		parsed = new URL(value);
+	} catch {
+		return null;
+	}
+	if (!hasAcceptedCanonicalScheme(parsed) || parsed.username || parsed.password || parsed.protocol !== parsed.protocol.toLowerCase() || parsed.hostname !== parsed.hostname.toLowerCase()) return null;
+	if (parsed.href !== value && parsed.origin !== value) return null;
+	return parsed;
+}
+function isValidScopeToken(scope) {
+	return typeof scope === "string" && scope.length > 0 && /^[\x21\x23-\x5b\x5d-\x7e]+$/.test(scope);
+}
+function getResourceMetadataUrl(resource) {
+	const parsed = new URL(resource);
+	const suffix = parsed.pathname === "/" ? "" : parsed.pathname;
+	return `${parsed.origin}${PROTECTED_RESOURCE_WELL_KNOWN_PREFIX$1}${suffix}${parsed.search}`;
+}
+/** The same test the combined provider applies to its handlers. */
+function isEntrypointClass(handler) {
+	return typeof handler === "function" && handler.prototype instanceof WorkerEntrypoint;
+}
+function isProtectedResourceMetadataPath(url) {
+	return url.pathname === PROTECTED_RESOURCE_WELL_KNOWN_PREFIX$1 || url.pathname.startsWith(`${PROTECTED_RESOURCE_WELL_KNOWN_PREFIX$1}/`);
+}
+function isMetadataUrlRequest(requestUrl, metadataUrl) {
+	return requestUrl.origin === metadataUrl.origin && requestUrl.pathname === metadataUrl.pathname && requestCarriesResourceQuery(requestUrl, metadataUrl);
+}
+function isCanonicalResourceRequest(requestUrl, resourceUrl) {
+	if (requestUrl.origin !== resourceUrl.origin) return false;
+	if (!requestCarriesResourceQuery(requestUrl, resourceUrl)) return false;
+	const resourcePath = resourceUrl.pathname;
+	if (requestUrl.pathname === resourcePath) return true;
+	if (resourcePath === "/") return requestUrl.pathname.startsWith("/");
+	const descendantPrefix = resourcePath.endsWith("/") ? resourcePath : `${resourcePath}/`;
+	return requestUrl.pathname.startsWith(descendantPrefix);
+}
+function parseBearerToken(authorization) {
+	if (!authorization) return null;
+	return /^Bearer[\t ]+([^\s,]+)$/i.exec(authorization)?.[1] || null;
+}
+function isValidTokenValidation(validation, canonicalResource) {
+	if (!validation || typeof validation !== "object") return false;
+	if (typeof validation.audience !== "string" || !resourceMatches(validation.audience, canonicalResource)) return false;
+	if (!Object.prototype.hasOwnProperty.call(validation, "props")) return false;
+	if (validation.expiresAt !== void 0) {
+		if (typeof validation.expiresAt !== "number" || !Number.isFinite(validation.expiresAt)) return false;
+		if (validation.expiresAt <= Date.now() / 1e3) return false;
+	}
+	if (validation.scope !== void 0) {
+		if (!Array.isArray(validation.scope)) return false;
+		if (validation.scope.some((scope) => typeof scope !== "string" || !isValidScopeToken(scope))) return false;
+	}
+	if (validation.userId !== void 0 && typeof validation.userId !== "string") return false;
+	if (validation.clientId !== void 0 && typeof validation.clientId !== "string") return false;
+	return true;
+}
+function createBearerChallenge(requestUrl, validated, invalidToken) {
+	let challenge = "Bearer realm=\"OAuth\"";
+	if (isCanonicalResourceRequest(requestUrl, validated.resourceUrl)) challenge += `, resource_metadata="${validated.metadataUrl.href}"`;
+	if (invalidToken) challenge += ", error=\"invalid_token\"";
+	const scopes = validated.metadata.scopes_supported;
+	if (scopes && scopes.length > 0) challenge += `, scope="${scopes.join(" ")}"`;
+	return new Response(null, {
+		status: 401,
+		headers: {
+			...NO_CACHE_HEADERS$1,
+			"WWW-Authenticate": challenge
+		}
+	});
+}
+function createValidationUnavailableResponse() {
+	return new Response(null, {
+		status: 503,
+		headers: NO_CACHE_HEADERS$1
+	});
+}
+function addCorsHeaders(response, request) {
+	const origin = request.headers.get("Origin");
+	if (!origin) return response;
+	const withCors = new Response(response.body, response);
+	withCors.headers.set("Access-Control-Allow-Origin", origin);
+	withCors.headers.set("Access-Control-Allow-Methods", "*");
+	withCors.headers.set("Access-Control-Allow-Headers", "Authorization, *");
+	appendHeaderValue$1(withCors.headers, "Vary", "Origin");
+	appendHeaderValue$1(withCors.headers, "Access-Control-Expose-Headers", "WWW-Authenticate");
+	appendHeaderValue$1(withCors.headers, "Access-Control-Expose-Headers", "Retry-After");
+	withCors.headers.set("Access-Control-Max-Age", "86400");
+	return withCors;
+}
+function appendHeaderValue$1(headers, name, value) {
+	const values = (headers.get(name) ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+	if (!values.some((item) => item.toLowerCase() === value.toLowerCase())) values.push(value);
+	headers.set(name, values.join(", "));
+}
+
 //#endregion
 //#region src/oauth-provider.ts
 const PROTECTED_RESOURCE_WELL_KNOWN_PREFIX = "/.well-known/oauth-protected-resource";
@@ -1256,7 +1577,7 @@ let GrantType = /* @__PURE__ */ function(GrantType$1) {
 	return GrantType$1;
 }({});
 function toPublicClientInfo(client) {
-	const { authMethodExplicit: _explicit, ...publicClient } = client;
+	const { authMethodExplicit: _explicit, registrationExpiresAt: _expiry, ...publicClient } = client;
 	return publicClient;
 }
 function isClientAuthMethodAllowed(client, presentedMethod, isClientMetadataDocument) {
@@ -1302,6 +1623,66 @@ var OAuthProvider = class {
 	}
 };
 /**
+* The authorization-server role on its own. It serves discovery, token, revocation and
+* registration endpoints from `fetch()`, exposes the interactive authorization flow through
+* `getOAuthApi()`, and validates its access tokens for any declared resource through
+* `validateToken()`. Resources are hosted, in this Worker or another, by
+* `OAuthResourceServer`, whose `validateToken` points back here.
+*/
+var OAuthAuthorizationServer = class {
+	#impl;
+	constructor(options) {
+		const { issuer, resources, defaultResource, legacyGrantResource, authorizeEndpoint, tokenEndpoint, clientRegistrationEndpoint, ...commonOptions } = options;
+		this.#impl = new OAuthProviderImpl({
+			...commonOptions,
+			defaultHandler: { fetch: () => new Response(null, { status: 404 }) },
+			authorizationServer: {
+				issuer,
+				resources,
+				authorizeEndpoint,
+				tokenEndpoint,
+				clientRegistrationEndpoint,
+				defaultResource,
+				legacyGrantResource
+			}
+		});
+	}
+	/**
+	* Validate an access token for one declared resource: the token's KV record is loaded, its
+	* audience checked against `resource`, and its props decrypted. Resolves `null` for a token
+	* that is not valid for that resource, and rejects for a resource this server does not
+	* declare.
+	*
+	* This is what a resource server calls, whether it shares this Worker or reaches it over a
+	* Service Binding. For the latter, expose it from a `WorkerEntrypoint`:
+	*
+	* ```ts
+	* export default class AuthServer extends WorkerEntrypoint<Env> {
+	*   fetch(request: Request) {
+	*     return authorizationServer.fetch(request, this.env, this.ctx);
+	*   }
+	*   validateToken(resource: string, token: string) {
+	*     return authorizationServer.validateToken(resource, token, this.env);
+	*   }
+	* }
+	* ```
+	*/
+	validateToken(resource, token, env) {
+		return this.#impl.validateAccessToken(token, resource, env);
+	}
+	/** Serve protocol-owned authorization-server endpoints, excluding the application authorization UI. */
+	fetch(request, env, ctx) {
+		return this.#impl.fetchAuthorizationServer(request, env, ctx);
+	}
+	/** Obtain helpers for scheduled jobs or custom code outside a fetch dispatch. */
+	getOAuthApi(env) {
+		return this.#impl.createOAuthHelpers(env);
+	}
+	purgeExpiredData(env, options) {
+		return this.#impl.createOAuthHelpers(env).purgeExpiredData(options);
+	}
+};
+/**
 * Gets OAuthHelpers for the given environment
 * @param options - Configuration options for the OAuth provider
 * @param env - Cloudflare Worker environment variables
@@ -1324,37 +1705,95 @@ var OAuthProviderImpl = class {
 	* @param options - Configuration options for the provider
 	*/
 	constructor(options) {
+		this.errorResponses = /* @__PURE__ */ new WeakSet();
 		this.typedApiHandlers = [];
-		const hasSingleHandlerConfig = !!(options.apiRoute && options.apiHandler);
-		const hasMultiHandlerConfig = !!options.apiHandlers;
-		if (hasSingleHandlerConfig && hasMultiHandlerConfig) throw new TypeError("Cannot use both apiRoute/apiHandler and apiHandlers. Use either apiRoute + apiHandler OR apiHandlers, not both.");
-		if (!hasSingleHandlerConfig && !hasMultiHandlerConfig) throw new TypeError("Must provide either apiRoute + apiHandler OR apiHandlers. No API route configuration provided.");
 		this.typedDefaultHandler = this.validateHandler(options.defaultHandler, "defaultHandler");
-		if (hasSingleHandlerConfig) {
-			const apiHandler = this.validateHandler(options.apiHandler, "apiHandler");
-			if (Array.isArray(options.apiRoute)) options.apiRoute.forEach((route, index) => {
-				this.validateEndpoint(route, `apiRoute[${index}]`);
-				this.typedApiHandlers.push([route, apiHandler]);
-			});
-			else {
-				this.validateEndpoint(options.apiRoute, "apiRoute");
-				this.typedApiHandlers.push([options.apiRoute, apiHandler]);
-			}
-		} else for (const [route, handler] of Object.entries(options.apiHandlers)) {
-			this.validateEndpoint(route, `apiHandlers key: ${route}`);
-			this.typedApiHandlers.push([route, this.validateHandler(handler, `apiHandlers[${route}]`)]);
+		const roleBased = "authorizationServer" in options;
+		if (!roleBased && "resourceMatchOriginOnly" in options) throw new TypeError("resourceMatchOriginOnly was removed in 1.0. Configure resourceMetadata.resource; audiences are compared exactly against that canonical resource. See the migration guide.");
+		let normalizedOptions;
+		let configuredResourceServers;
+		if (roleBased) {
+			const { authorizationServer: authorizationServer$1, ...commonOptions } = options;
+			this.validateAuthorizationServerIssuer(authorizationServer$1.issuer);
+			this.explicitIssuer = authorizationServer$1.issuer;
+			normalizedOptions = {
+				...commonOptions,
+				authorizeEndpoint: authorizationServer$1.authorizeEndpoint,
+				tokenEndpoint: authorizationServer$1.tokenEndpoint,
+				clientRegistrationEndpoint: authorizationServer$1.clientRegistrationEndpoint
+			};
+			const declared = authorizationServer$1.resources;
+			if (!Array.isArray(declared) || declared.length === 0 || declared.some((value) => typeof value !== "string")) throw new TypeError("resources must list at least one canonical protected resource identifier");
+			const duplicate = declared.find((resource, index) => declared.slice(0, index).some((earlier) => isExactResource(earlier, resource)));
+			if (duplicate !== void 0) throw new TypeError(`resources must be unique; duplicate ${duplicate}`);
+			configuredResourceServers = declared.map((resource) => ({ resourceMetadata: { resource } }));
+		} else {
+			this.explicitIssuer = void 0;
+			normalizedOptions = options;
+			configuredResourceServers = [{
+				resourceMetadata: options.resourceMetadata,
+				resolveExternalToken: options.resolveExternalToken
+			}];
 		}
-		this.validateEndpoint(options.authorizeEndpoint, "authorizeEndpoint");
-		this.validateEndpoint(options.tokenEndpoint, "tokenEndpoint");
-		if (options.clientRegistrationEndpoint) this.validateEndpoint(options.clientRegistrationEndpoint, "clientRegistrationEndpoint");
 		this.options = {
 			accessTokenTTL: DEFAULT_ACCESS_TOKEN_TTL,
 			refreshTokenTTL: DEFAULT_REFRESH_TOKEN_TTL,
 			clientRegistrationTTL: DEFAULT_CLIENT_REGISTRATION_TTL,
 			onError: ({ status, code, description }) => console.warn(`OAuth error response: ${status} ${code} - ${description}`),
-			...options
+			...normalizedOptions
 		};
-		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.validateEndpoint(this.options.authorizeEndpoint, "authorizeEndpoint");
+		this.validateEndpoint(this.options.tokenEndpoint, "tokenEndpoint");
+		if (this.options.clientRegistrationEndpoint) this.validateEndpoint(this.options.clientRegistrationEndpoint, "clientRegistrationEndpoint");
+		if (roleBased) this.validateAuthorizationServerRouteIsolation();
+		this.resourceServers = configuredResourceServers.map(({ resourceMetadata, resolveExternalToken }) => {
+			const metadata = this.snapshotResourceMetadata(resourceMetadata);
+			this.validateResourceMetadataOptions(metadata);
+			return {
+				resourceMetadata: metadata,
+				resolveExternalToken
+			};
+		});
+		for (const [index, server] of this.resourceServers.entries()) if (this.resourceServers.slice(0, index).some((other) => isExactResource(other.resourceMetadata.resource, server.resourceMetadata.resource))) throw new TypeError(`resources must be unique; duplicate ${server.resourceMetadata.resource}`);
+		if (!roleBased) {
+			const legacyOptions = options;
+			const hasSingleHandlerConfig = !!(legacyOptions.apiRoute && legacyOptions.apiHandler);
+			const hasMultiHandlerConfig = !!legacyOptions.apiHandlers;
+			if (hasSingleHandlerConfig && hasMultiHandlerConfig) throw new TypeError("Cannot use both apiRoute/apiHandler and apiHandlers. Use either apiRoute + apiHandler OR apiHandlers, not both.");
+			if (!hasSingleHandlerConfig && !hasMultiHandlerConfig) throw new TypeError("Must provide either apiRoute + apiHandler OR apiHandlers. No API route configuration provided.");
+			const resourceServer = this.resourceServers[0];
+			if (hasSingleHandlerConfig) {
+				const handler = this.validateHandler(legacyOptions.apiHandler, "apiHandler");
+				(Array.isArray(legacyOptions.apiRoute) ? legacyOptions.apiRoute : [legacyOptions.apiRoute]).forEach((route, index) => {
+					this.validateEndpoint(route, Array.isArray(legacyOptions.apiRoute) ? `apiRoute[${index}]` : "apiRoute");
+					this.typedApiHandlers.push({
+						route,
+						handler,
+						resourceServer
+					});
+				});
+			} else for (const [route, rawHandler] of Object.entries(legacyOptions.apiHandlers)) {
+				this.validateEndpoint(route, `apiHandlers key: ${route}`);
+				const handler = this.validateHandler(rawHandler, `apiHandlers[${route}]`);
+				this.typedApiHandlers.push({
+					route,
+					handler,
+					resourceServer
+				});
+			}
+			for (const { route } of this.typedApiHandlers) this.assertRouteCoveredByResource(route, resourceServer.resourceMetadata.resource);
+		}
+		const resources = this.resourceServers.map((server) => server.resourceMetadata.resource);
+		const soleResource = resources.length === 1 ? resources[0] : void 0;
+		const authorizationServer = roleBased ? options.authorizationServer : void 0;
+		this.configuredDefaultAuthorizationResource = authorizationServer?.defaultResource ?? soleResource;
+		this.configuredLegacyGrantResource = authorizationServer?.legacyGrantResource ?? soleResource;
+		if (roleBased) {
+			this.getDefaultAuthorizationResource();
+			this.getLegacyGrantResource();
+		}
+		if (!isValidAccessTokenTTL(this.options.accessTokenTTL)) throw new TypeError(`accessTokenTTL must be an integer of at least ${KV_MIN_EXPIRATION_TTL_SECONDS} seconds (Cloudflare KV's minimum expiration window).`);
+		if (this.options.refreshTokenIdleTTL !== void 0 && !isValidAccessTokenTTL(this.options.refreshTokenIdleTTL)) throw new TypeError(`refreshTokenIdleTTL 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,
@@ -1362,7 +1801,6 @@ var OAuthProviderImpl = class {
 			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 });
@@ -1378,11 +1816,90 @@ var OAuthProviderImpl = class {
 	validateEndpoint(endpoint, name) {
 		if (this.isPath(endpoint)) {
 			if (!endpoint.startsWith("/")) throw new TypeError(`${name} path must be an absolute path starting with /`);
-		} else try {
-			new URL(endpoint);
-		} catch (e) {
-			throw new TypeError(`${name} must be either an absolute path starting with / or a valid URL`);
+			if (this.explicitIssuer && new URL(endpoint, new URL(this.explicitIssuer).origin).hash) throw new TypeError(`${name} must not contain a fragment`);
+		} else {
+			let parsed;
+			try {
+				parsed = new URL(endpoint);
+			} catch (e) {
+				throw new TypeError(`${name} must be either an absolute path starting with / or a valid URL`);
+			}
+			if (this.explicitIssuer && (!hasAcceptedCanonicalScheme(parsed) || parsed.username || parsed.password || parsed.hash)) throw new TypeError(`${name} must be an absolute HTTPS URL without userinfo or a fragment (http is accepted only on a loopback host)`);
+		}
+	}
+	/** Validate the explicit issuer used to host-gate the role-based AS. */
+	validateAuthorizationServerIssuer(issuer) {
+		let parsed;
+		try {
+			parsed = new URL(issuer);
+		} catch {
+			throw new TypeError("authorizationServer.issuer must be a canonical absolute HTTPS URL");
 		}
+		if (!validateResourceUri(issuer) || !hasAcceptedCanonicalScheme(parsed) || parsed.username || parsed.password || parsed.search || parsed.hash || foldResourceSchemeAndHost(issuer) !== issuer || parsed.href !== issuer && parsed.origin !== issuer) throw new TypeError("authorizationServer.issuer must be a canonical absolute HTTPS URL (http is accepted only on a loopback host)");
+	}
+	/** Reject exact collisions between protocol endpoints owned by the AS fetch surface. */
+	validateAuthorizationServerRouteIsolation() {
+		const issuerUrl = new URL(this.explicitIssuer);
+		const discoveryEndpoint = this.getAuthorizationServerMetadataUrl(issuerUrl);
+		const tokenUrl = new URL(this.getFullEndpointUrl(this.options.tokenEndpoint, issuerUrl));
+		if (this.matchEndpoint(tokenUrl, discoveryEndpoint)) throw new TypeError("tokenEndpoint must not collide with the authorization server metadata endpoint");
+		if (!this.options.clientRegistrationEndpoint) return;
+		const registrationUrl = new URL(this.getFullEndpointUrl(this.options.clientRegistrationEndpoint, issuerUrl));
+		if (this.matchEndpoint(registrationUrl, this.options.tokenEndpoint)) throw new TypeError("clientRegistrationEndpoint must not collide with tokenEndpoint");
+		if (this.matchEndpoint(registrationUrl, discoveryEndpoint)) throw new TypeError("clientRegistrationEndpoint must not collide with the authorization server metadata endpoint");
+	}
+	/**
+	* A protected route must be the canonical resource path or a path-boundary descendant of
+	* it. Anything else can never validate a token, because every token is bound to the
+	* canonical resource, so it would be a permanently 401 zone.
+	*/
+	assertRouteCoveredByResource(route, resource) {
+		const resourceUrl = new URL(resource);
+		let routePath;
+		if (this.isPath(route)) routePath = route.split("?")[0];
+		else {
+			const routeUrl = new URL(route);
+			if (routeUrl.origin !== resourceUrl.origin) throw new TypeError(`API route ${route} is not covered by resourceMetadata.resource ${resource}. An absolute protected route must be on the resource's origin.`);
+			for (const [name, value] of resourceUrl.searchParams) {
+				const routeValues = routeUrl.searchParams.getAll(name);
+				if (routeValues.length > 0 && !routeValues.includes(value)) throw new TypeError(`API route ${route} is not covered by resourceMetadata.resource ${resource}. An absolute protected route must carry the resource's query parameters.`);
+			}
+			routePath = routeUrl.pathname;
+		}
+		if (isPathDescendant(routePath, resourceUrl.pathname)) return;
+		throw new TypeError(`API route ${route} is not covered by resourceMetadata.resource ${resource}. Protected routes must be the canonical resource path or a descendant of it; use ${resourceUrl.origin} as the resource to cover every path on that origin.`);
+	}
+	/** Resolve a configured policy value to the registry's canonical spelling. */
+	resolveConfiguredResourceDefault(resource, name) {
+		if (resource === void 0) return void 0;
+		const configured = this.findConfiguredResource(resource);
+		if (!configured) throw new TypeError(`${name} must name one of the configured protected resources`);
+		return configured;
+	}
+	getDefaultAuthorizationResource() {
+		const sole = this.resourceServers.length === 1 ? this.resourceServers[0].resourceMetadata.resource : void 0;
+		return this.resolveConfiguredResourceDefault(this.configuredDefaultAuthorizationResource ?? sole, "defaultResource");
+	}
+	getLegacyGrantResource() {
+		const sole = this.resourceServers.length === 1 ? this.resourceServers[0].resourceMetadata.resource : void 0;
+		return this.resolveConfiguredResourceDefault(this.configuredLegacyGrantResource ?? sole, "legacyGrantResource");
+	}
+	/**
+	* The audience a stored access token is treated as bound to.
+	*
+	* A token issued before resource binding has no stored audience. It keeps
+	* working at the server-selected migration resource (the sole resource, or
+	* `legacyGrantResource` in a multi-resource deployment) until it expires;
+	* refresh binds its grant and returns a bound replacement. The client never
+	* chooses this destination. Without a migration resource the token is
+	* treated as unbound and rejected.
+	*
+	* The destination is deployment policy, not an issuance-time claim: changing
+	* `legacyGrantResource` re-targets every surviving unbound token and grant.
+	* Keep it fixed for the length of the migration window.
+	*/
+	resolveStoredTokenAudience(audience) {
+		return audience === void 0 ? this.getLegacyGrantResource() : audience;
 	}
 	/**
 	* Validates that a handler is either an ExportedHandler or a class extending WorkerEntrypoint
@@ -1402,10 +1919,22 @@ var OAuthProviderImpl = class {
 		};
 		throw new TypeError(`${name} must be either an ExportedHandler object with a fetch method or a class extending WorkerEntrypoint`);
 	}
+	/** Snapshot caller-owned metadata so later mutation cannot change routing or policy. */
+	snapshotResourceMetadata(metadata) {
+		return {
+			...metadata,
+			...metadata?.authorization_servers ? { authorization_servers: [...metadata.authorization_servers] } : {},
+			...metadata?.scopes_supported ? { scopes_supported: [...metadata.scopes_supported] } : {},
+			...metadata?.bearer_methods_supported ? { bearer_methods_supported: [...metadata.bearer_methods_supported] } : {}
+		};
+	}
 	/** Validate configured RFC 9728 protected resource metadata. */
 	validateResourceMetadataOptions(options) {
-		if (!options) return;
-		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 || !validateResourceUri(options.resource) || !hasAcceptedCanonicalScheme(new URL(options.resource))) throw new TypeError("resourceMetadata.resource is required and must be an absolute HTTPS URI without a fragment (http is accepted only on a loopback host)");
+		if (foldResourceSchemeAndHost(options.resource) !== options.resource) throw new TypeError("resourceMetadata.resource must use a lowercase scheme and lowercase host");
+		const parsedResource = new URL(options.resource);
+		if (parsedResource.username || parsedResource.password || parsedResource.href !== options.resource && parsedResource.origin !== options.resource) throw new TypeError("resourceMetadata.resource must use canonical URL serialization without userinfo, a default port, or dot segments");
+		if (parsedResource.pathname === PROTECTED_RESOURCE_WELL_KNOWN_PREFIX || parsedResource.pathname.startsWith(`${PROTECTED_RESOURCE_WELL_KNOWN_PREFIX}/`)) throw new TypeError(`resourceMetadata.resource must not be inside the ${PROTECTED_RESOURCE_WELL_KNOWN_PREFIX} namespace`);
 		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) {
@@ -1415,7 +1944,7 @@ var OAuthProviderImpl = class {
 				} 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 (!validateResourceUri(issuer) || !hasAcceptedCanonicalScheme(parsed) || parsed.username || parsed.password || foldResourceSchemeAndHost(issuer) !== issuer || parsed.href !== issuer && parsed.origin !== issuer || issuer.includes("?") || issuer.includes("#")) throw new TypeError("resourceMetadata.authorization_servers must contain valid HTTPS issuer URLs (http is accepted only on a loopback host)");
 			}
 		}
 		if (options.scopes_supported?.some((scope) => !isValidOAuthScopeToken(scope))) throw new TypeError("resourceMetadata.scopes_supported must contain valid OAuth scope tokens");
@@ -1433,7 +1962,6 @@ var OAuthProviderImpl = class {
 		if (!options) return;
 		if (typeof options.trustedIssuers !== "function") throw new TypeError("enterpriseManagedAuthorization.trustedIssuers must be a resolver function: (input) => EmaTrustedIssuer | null");
 		if (typeof options.mapClaims !== "function") throw new TypeError("enterpriseManagedAuthorization.mapClaims must be a function");
-		if (!this.options.resourceMetadata?.resource) throw new TypeError("enterpriseManagedAuthorization requires resourceMetadata.resource to be configured");
 		if (options.jwksCacheTtlSeconds !== void 0 && options.jwksCacheTtlSeconds <= 0) throw new TypeError("enterpriseManagedAuthorization.jwksCacheTtlSeconds must be greater than 0");
 		if (options.clockSkewSeconds !== void 0 && options.clockSkewSeconds < 0) throw new TypeError("enterpriseManagedAuthorization.clockSkewSeconds must be non-negative");
 		if (options.maxAssertionLifetimeSeconds !== void 0 && options.maxAssertionLifetimeSeconds <= 0) throw new TypeError("enterpriseManagedAuthorization.maxAssertionLifetimeSeconds must be greater than 0");
@@ -1447,20 +1975,38 @@ var OAuthProviderImpl = class {
 	* @returns A Promise resolving to an HTTP Response
 	*/
 	async fetch(request, env, ctx) {
+		return this.fetchForRoles(request, env, ctx, "combined");
+	}
+	async fetchAuthorizationServer(request, env, ctx) {
+		return this.fetchForRoles(request, env, ctx, "authorization-server");
+	}
+	async fetchForRoles(request, env, ctx, role) {
 		const url = new URL(request.url);
+		const servesProtectedResources = role === "combined";
+		const metadataResourceServer = servesProtectedResources ? this.findResourceServerForMetadataUrl(url) : void 0;
+		const apiRoute = servesProtectedResources ? this.findApiRouteForUrl(url) : void 0;
 		if (request.method === "OPTIONS") {
-			if (this.isApiRequest(url) || url.pathname === "/.well-known/oauth-authorization-server" || this.isProtectedResourceMetadataRequest(url) || this.isTokenEndpoint(url) || this.options.clientRegistrationEndpoint && this.isClientRegistrationEndpoint(url)) return this.addCorsHeaders(new Response(null, {
+			if (apiRoute !== void 0 || this.isAuthorizationServerMetadataRequest(url) || servesProtectedResources && this.isProtectedResourceMetadataPath(url) || this.isTokenEndpoint(url) || this.options.clientRegistrationEndpoint && this.isClientRegistrationEndpoint(url)) return this.addCorsHeaders(new Response(null, {
 				status: 204,
 				headers: { "Content-Length": "0" }
 			}), request);
 		}
-		if (url.pathname === "/.well-known/oauth-authorization-server") {
+		if (this.isAuthorizationServerMetadataRequest(url)) {
+			if (request.method !== "GET" && request.method !== "HEAD") return this.addCorsHeaders(new Response(null, {
+				status: 405,
+				headers: { Allow: "GET, HEAD, OPTIONS" }
+			}), request);
 			const response = await this.handleMetadataDiscovery(url);
-			return this.addCorsHeaders(response, request);
+			return this.addCorsHeaders(withoutBodyForHead(request, response), request);
 		}
-		if (this.isProtectedResourceMetadataRequest(url)) {
-			const response = this.handleProtectedResourceMetadata(url);
-			return this.addCorsHeaders(response, request);
+		if (servesProtectedResources && this.isProtectedResourceMetadataPath(url)) {
+			if (!metadataResourceServer) return this.addCorsHeaders(new Response(null, { status: 404 }), request);
+			if (request.method !== "GET" && request.method !== "HEAD") return this.addCorsHeaders(new Response(null, {
+				status: 405,
+				headers: { Allow: "GET, HEAD, OPTIONS" }
+			}), request);
+			const response = this.handleProtectedResourceMetadata(url, metadataResourceServer);
+			return this.addCorsHeaders(withoutBodyForHead(request, response), request);
 		}
 		if (this.isTokenEndpoint(url)) {
 			const parsed = await this.parseTokenEndpointRequest(request, env);
@@ -1468,16 +2014,18 @@ var OAuthProviderImpl = class {
 			let response;
 			if (parsed.isRevocationRequest) response = await this.handleRevocationRequest(parsed.body, parsed.clientInfo, env);
 			else response = await this.handleTokenRequest(parsed.body, parsed.clientInfo, env, url, request);
+			if (response.ok && !this.errorResponses.has(response)) await this.renewClientRegistrationIfDue(env, parsed.clientInfo, Math.floor(Date.now() / 1e3));
 			return this.addCorsHeaders(response, request);
 		}
 		if (this.options.clientRegistrationEndpoint && this.isClientRegistrationEndpoint(url)) {
 			const response = await this.handleClientRegistration(request, env);
 			return this.addCorsHeaders(response, request);
 		}
-		if (this.isApiRequest(url)) {
-			const response = await this.handleApiRequest(request, env, ctx);
+		if (apiRoute) {
+			const response = await this.handleApiRequest(request, env, ctx, apiRoute);
 			return this.addCorsHeaders(response, request);
 		}
+		if (typeof role === "object") return new Response(null, { status: 404 });
 		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);
 		return new this.typedDefaultHandler.handler(ctx, env).fetch(request);
@@ -1514,6 +2062,20 @@ var OAuthProviderImpl = class {
 			}
 		};
 	}
+	async validateAccessToken(token, resource, env) {
+		const configuredResource = this.findConfiguredResource(resource);
+		if (!configuredResource) throw new TypeError("resource must name one registered protected resource");
+		const summary = await this.unwrapToken(token, env);
+		if (!summary || !isExactResource(this.resolveStoredTokenAudience(summary.audience), configuredResource)) return null;
+		return {
+			props: summary.grant.props,
+			audience: configuredResource,
+			expiresAt: summary.expiresAt,
+			scope: summary.scope,
+			userId: summary.userId,
+			clientId: summary.grant.clientId
+		};
+	}
 	/**
 	* Determines if an endpoint configuration is a path or a full URL
 	* @param endpoint - The endpoint configuration
@@ -1528,12 +2090,26 @@ var OAuthProviderImpl = class {
 	* @param endpoint - The endpoint pattern (full URL or path)
 	* @returns True if the URL matches the endpoint pattern
 	*/
-	matchEndpoint(url, endpoint) {
-		if (this.isPath(endpoint)) return url.pathname === endpoint;
-		else {
-			const endpointUrl = new URL(endpoint);
-			return url.hostname === endpointUrl.hostname && url.pathname === endpointUrl.pathname;
+	matchEndpoint(url, endpoint, allowAdditionalQuery = false) {
+		if (!this.explicitIssuer) {
+			if (this.isPath(endpoint)) return url.pathname === endpoint;
+			const legacyEndpoint = new URL(endpoint);
+			return url.hostname === legacyEndpoint.hostname && url.pathname === legacyEndpoint.pathname;
+		}
+		const endpointUrl = new URL(this.getFullEndpointUrl(endpoint, url));
+		if (url.origin !== endpointUrl.origin || url.pathname !== endpointUrl.pathname) return false;
+		const unmatchedActualQuery = [...url.searchParams.entries()];
+		const configuredQueryNames = /* @__PURE__ */ new Set();
+		for (const [name, value] of endpointUrl.searchParams) {
+			configuredQueryNames.add(name);
+			const match = unmatchedActualQuery.findIndex(([actualName, actualValue]) => {
+				return actualName === name && actualValue === value;
+			});
+			if (match === -1) return false;
+			unmatchedActualQuery.splice(match, 1);
 		}
+		if (!allowAdditionalQuery) return unmatchedActualQuery.length === 0;
+		return unmatchedActualQuery.every(([name]) => !configuredQueryNames.has(name));
 	}
 	/**
 	* Checks if a URL matches the configured token endpoint
@@ -1541,7 +2117,10 @@ var OAuthProviderImpl = class {
 	* @returns True if the URL matches the token endpoint
 	*/
 	isTokenEndpoint(url) {
-		return this.matchEndpoint(url, this.options.tokenEndpoint);
+		return this.matchEndpoint(url, this.options.tokenEndpoint, true);
+	}
+	isAuthorizationEndpointRequest(url) {
+		return this.matchEndpoint(url, this.options.authorizeEndpoint, true);
 	}
 	/**
 	* Checks if a URL matches the configured client registration endpoint
@@ -1550,28 +2129,37 @@ var OAuthProviderImpl = class {
 	*/
 	isClientRegistrationEndpoint(url) {
 		if (!this.options.clientRegistrationEndpoint) return false;
-		return this.matchEndpoint(url, this.options.clientRegistrationEndpoint);
+		return this.matchEndpoint(url, this.options.clientRegistrationEndpoint, true);
 	}
 	/**
 	* Checks if a URL is a request for OAuth Protected Resource Metadata (RFC 9728).
-	* Matches both the root well-known path and path-suffixed variants per RFC 9728 §3.1.
+	* Only the well-known URL constructed from the configured canonical resource
+	* may return its document; aliases would violate RFC 9728 §3.3.
 	*/
-	isProtectedResourceMetadataRequest(url) {
-		return url.pathname === PROTECTED_RESOURCE_WELL_KNOWN_PREFIX || url.pathname.startsWith(PROTECTED_RESOURCE_WELL_KNOWN_PREFIX + "/");
+	findResourceServerForMetadataUrl(url) {
+		return this.resourceServers.find((server) => {
+			const expected = new URL(this.getConfiguredResourceMetadataUrl(server.resourceMetadata.resource));
+			return url.origin === expected.origin && url.pathname === expected.pathname && requestCarriesResourceQuery(url, expected);
+		});
 	}
-	/**
-	* Derives the resource identifier from a protected resource metadata well-known URL.
-	* Per RFC 9728 §3.1, the well-known URI is inserted after the authority and before the path,
-	* so the resource identifier is reconstructed by removing the well-known prefix.
-	*
-	* Examples:
-	*   /.well-known/oauth-protected-resource       → origin (e.g. https://example.com)
-	*   /.well-known/oauth-protected-resource/mcp   → origin + /mcp (e.g. https://example.com/mcp)
-	*/
-	deriveResourceIdentifier(requestUrl) {
-		const suffix = requestUrl.pathname.slice(37);
-		if (!suffix || suffix === "/") return requestUrl.origin;
-		return `${requestUrl.origin}${suffix}`;
+	/** Exact RFC 8414 discovery location for the configured issuer. */
+	getAuthorizationServerMetadataUrl(requestUrl) {
+		if (!this.explicitIssuer) return `${requestUrl.origin}/.well-known/oauth-authorization-server`;
+		const issuer = new URL(this.explicitIssuer);
+		const issuerPath = issuer.pathname === "/" ? "" : issuer.pathname.replace(/\/+$/, "");
+		return `${issuer.origin}/.well-known/oauth-authorization-server${issuerPath}`;
+	}
+	isAuthorizationServerMetadataRequest(url) {
+		const expected = new URL(this.getAuthorizationServerMetadataUrl(url));
+		return url.origin === expected.origin && url.pathname === expected.pathname;
+	}
+	/** Whether this instance is the role-based authorization server with a fixed issuer. */
+	get hasExplicitIssuer() {
+		return this.explicitIssuer !== void 0;
+	}
+	/** Whether a URL is in the RFC 9728 protected-resource metadata namespace. */
+	isProtectedResourceMetadataPath(url) {
+		return url.pathname === PROTECTED_RESOURCE_WELL_KNOWN_PREFIX || url.pathname.startsWith(PROTECTED_RESOURCE_WELL_KNOWN_PREFIX + "/");
 	}
 	createInvalidClientResponse(description, basicAuthenticationAttempted, internal, request) {
 		return this.createErrorResponse("invalid_client", {
@@ -1588,13 +2176,20 @@ var OAuthProviderImpl = class {
 	async parseTokenEndpointRequest(request, env) {
 		if (request.method !== "POST") return this.createErrorResponse("invalid_request", {
 			description: "Method not allowed",
-			statusCode: 405
+			statusCode: 405,
+			headers: { Allow: "POST, OPTIONS" }
+		}, {
+			category: "token-endpoint-request",
+			reason: "method_not_allowed"
 		});
 		const contentType = request.headers.get("Content-Type") || "";
 		let body = {};
 		if (contentType.split(";")[0].trim().toLowerCase() !== "application/x-www-form-urlencoded") return this.createErrorResponse("invalid_request", {
 			description: "Content-Type must be application/x-www-form-urlencoded",
 			statusCode: 400
+		}, {
+			category: "token-endpoint-request",
+			reason: "unsupported_content_type"
 		});
 		let formData;
 		try {
@@ -1603,6 +2198,9 @@ var OAuthProviderImpl = class {
 			return this.createErrorResponse("invalid_request", {
 				description: "Request body must be valid application/x-www-form-urlencoded data",
 				statusCode: 400
+			}, {
+				category: "token-endpoint-request",
+				reason: "malformed_request_body"
 			});
 		}
 		const processedKeys = /* @__PURE__ */ new Set();
@@ -1613,6 +2211,10 @@ var OAuthProviderImpl = class {
 			if (key !== "resource" && allValues.length > 1) return this.createErrorResponse("invalid_request", {
 				description: `Request parameter "${key}" must not be repeated`,
 				statusCode: 400
+			}, {
+				category: "token-endpoint-request",
+				reason: "repeated_parameter",
+				detail: { parameter: key }
 			});
 			body[key] = allValues.length > 1 ? allValues : value;
 		}
@@ -1624,15 +2226,24 @@ var OAuthProviderImpl = class {
 			if (formData.has("client_id") || formData.has("client_secret")) return this.createErrorResponse("invalid_request", {
 				description: "Client must not use multiple authentication methods",
 				statusCode: 400
+			}, {
+				category: "client-authentication",
+				reason: "multiple_authentication_methods"
+			});
+			if (basicAuthorization.kind === "malformed") return this.createInvalidClientResponse("Client authentication failed: invalid Basic credentials", basicAuthenticationAttempted, {
+				category: "client-authentication",
+				reason: "malformed_basic_credentials"
 			});
-			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.createInvalidClientResponse("Client ID is required", basicAuthenticationAttempted);
+		if (!clientId) return this.createInvalidClientResponse("Client ID is required", basicAuthenticationAttempted, {
+			category: "client-authentication",
+			reason: "client_id_missing"
+		});
 		let clientInfo;
 		try {
 			clientInfo = await this.getClient(env, clientId);
@@ -1647,7 +2258,10 @@ var OAuthProviderImpl = class {
 			}, request);
 			throw error;
 		}
-		if (!clientInfo) return this.createInvalidClientResponse("Client not found", basicAuthenticationAttempted);
+		if (!clientInfo) return this.createInvalidClientResponse("Client not found", basicAuthenticationAttempted, {
+			category: "client-authentication",
+			reason: "client_not_found"
+		});
 		const presentedAuthMethod = basicAuthenticationAttempted ? "client_secret_basic" : formData.has("client_secret") ? "client_secret_post" : "none";
 		const registeredAuthMethod = clientInfo.tokenEndpointAuthMethod;
 		if (!isClientAuthMethodAllowed(clientInfo, presentedAuthMethod, !!this.options.clientIdMetadataDocumentEnabled && this.isClientMetadataUrl(clientInfo.clientId))) return this.createInvalidClientResponse("Client authentication failed", basicAuthenticationAttempted, {
@@ -1660,9 +2274,18 @@ var OAuthProviderImpl = class {
 			}
 		});
 		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);
+			if (!clientSecret) return this.createInvalidClientResponse("Client authentication failed: missing client_secret", basicAuthenticationAttempted, {
+				category: "client-authentication",
+				reason: "client_secret_missing"
+			});
+			if (!clientInfo.clientSecret) return this.createInvalidClientResponse("Client authentication failed: client has no registered secret", basicAuthenticationAttempted, {
+				category: "client-authentication",
+				reason: "client_secret_not_registered"
+			});
+			if (await hashSecret(clientSecret) !== clientInfo.clientSecret) return this.createInvalidClientResponse("Client authentication failed: invalid client_secret", basicAuthenticationAttempted, {
+				category: "client-authentication",
+				reason: "client_secret_mismatch"
+			});
 		}
 		const isRevocationRequest = !body.grant_type && !!body.token;
 		return {
@@ -1678,30 +2301,24 @@ var OAuthProviderImpl = class {
 	* @returns True if the URL matches the API route
 	*/
 	matchApiRoute(url, route) {
-		if (this.isPath(route)) {
-			if (route === "/") return url.pathname === "/";
-			return url.pathname.startsWith(route);
-		} else {
+		const pathMatches = (configuredPath, rootMatchesDescendants) => {
+			if (configuredPath === "/") return rootMatchesDescendants || url.pathname === "/";
+			const normalized = configuredPath.endsWith("/") ? configuredPath.slice(0, -1) : configuredPath;
+			return url.pathname === normalized || url.pathname.startsWith(normalized + "/");
+		};
+		if (this.isPath(route)) return pathMatches(route, false);
+		else {
 			const apiUrl = new URL(route);
-			return url.hostname === apiUrl.hostname && url.pathname.startsWith(apiUrl.pathname);
+			return url.origin === apiUrl.origin && pathMatches(apiUrl.pathname, true) && requestCarriesResourceQuery(url, apiUrl);
 		}
 	}
 	/**
-	* Checks if a URL is an API request based on the configured API route(s)
-	* @param url - The URL to check
-	* @returns True if the URL matches any of the API routes
-	*/
-	isApiRequest(url) {
-		for (const [route, _] of this.typedApiHandlers) if (this.matchApiRoute(url, route)) return true;
-		return false;
-	}
-	/**
 	* Finds the appropriate API handler for a URL
 	* @param url - The URL to find a handler for
 	* @returns The TypedHandler for the URL, or undefined if no handler matches
 	*/
-	findApiHandlerForUrl(url) {
-		for (const [route, handler] of this.typedApiHandlers) if (this.matchApiRoute(url, route)) return handler;
+	findApiRouteForUrl(url) {
+		return this.typedApiHandlers.filter(({ route }) => this.matchApiRoute(url, route)).sort((left, right) => new URL(right.route, url.origin).pathname.length - new URL(left.route, url.origin).pathname.length)[0];
 	}
 	/**
 	* Gets the full URL for an endpoint, using the provided request URL's
@@ -1711,13 +2328,14 @@ var OAuthProviderImpl = class {
 	* @returns The full URL for the endpoint
 	*/
 	getFullEndpointUrl(endpoint, requestUrl) {
-		if (this.isPath(endpoint)) return `${requestUrl.origin}${endpoint}`;
+		if (this.isPath(endpoint)) return `${this.explicitIssuer ? new URL(this.explicitIssuer).origin : requestUrl.origin}${endpoint}`;
 		else return endpoint;
 	}
 	/**
 	* Gets the authorization server issuer using the same derivation as RFC 8414 metadata.
 	*/
 	getAuthorizationServerIssuer(requestUrl) {
+		if (this.explicitIssuer) return this.explicitIssuer;
 		const tokenEndpoint = this.getFullEndpointUrl(this.options.tokenEndpoint, requestUrl);
 		return new URL(tokenEndpoint).origin;
 	}
@@ -1734,6 +2352,7 @@ var OAuthProviderImpl = class {
 		newResponse.headers.set("Access-Control-Allow-Origin", origin);
 		newResponse.headers.set("Access-Control-Allow-Methods", "*");
 		newResponse.headers.set("Access-Control-Allow-Headers", "Authorization, *");
+		appendHeaderValue(newResponse.headers, "Vary", "Origin");
 		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(", "));
@@ -1755,9 +2374,10 @@ var OAuthProviderImpl = class {
 		const grantTypesSupported = this.serverCapabilities.grantTypes;
 		const authorizationGrantProfilesSupported = this.options.enterpriseManagedAuthorization ? [EMA_ID_JAG_GRANT_PROFILE] : [];
 		const metadata = {
-			issuer: new URL(tokenEndpoint).origin,
+			issuer: this.getAuthorizationServerIssuer(requestUrl),
 			authorization_endpoint: authorizeEndpoint,
 			token_endpoint: tokenEndpoint,
+			...this.resourceServers.length > 0 ? { protected_resources: this.resourceServers.map((server) => server.resourceMetadata.resource) } : {},
 			registration_endpoint: registrationEndpoint,
 			scopes_supported: this.options.scopesSupported,
 			response_types_supported: responseTypesSupported,
@@ -1773,8 +2393,8 @@ var OAuthProviderImpl = class {
 		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 ?? []);
+	getProtectedResourceScopes(resourceServer) {
+		return this.normalizeProtectedResourceScopes(resourceServer.resourceMetadata.scopes_supported ?? []);
 	}
 	/** Deduplicate resource-facing scopes and remove authorization-server-only capabilities. */
 	normalizeProtectedResourceScopes(scopes) {
@@ -1786,18 +2406,17 @@ var OAuthProviderImpl = class {
 	* @param requestUrl - The URL of the incoming request
 	* @returns Response with protected resource metadata
 	*/
-	handleProtectedResourceMetadata(requestUrl) {
-		const rm = this.options.resourceMetadata;
-		const tokenEndpointUrl = this.getFullEndpointUrl(this.options.tokenEndpoint, requestUrl);
-		const authServerOrigin = new URL(tokenEndpointUrl).origin;
-		const resourceScopes = this.getProtectedResourceScopes();
+	handleProtectedResourceMetadata(requestUrl, resourceServer) {
+		const rm = resourceServer.resourceMetadata;
+		const authorizationServer = this.getAuthorizationServerIssuer(requestUrl);
+		const resourceScopes = this.getProtectedResourceScopes(resourceServer);
 		const metadata = {
-			resource: rm?.resource ?? this.deriveResourceIdentifier(requestUrl),
-			authorization_servers: rm?.authorization_servers ?? [authServerOrigin],
+			resource: rm.resource,
+			authorization_servers: rm.authorization_servers ?? [authorizationServer],
 			...resourceScopes.length > 0 ? { scopes_supported: resourceScopes } : {},
-			bearer_methods_supported: rm?.bearer_methods_supported ?? ["header"]
+			bearer_methods_supported: rm.bearer_methods_supported ?? ["header"]
 		};
-		if (rm?.resource_name) metadata.resource_name = rm.resource_name;
+		if (rm.resource_name) metadata.resource_name = rm.resource_name;
 		return new Response(JSON.stringify(metadata), { headers: { "Content-Type": "application/json" } });
 	}
 	/**
@@ -1811,11 +2430,23 @@ var OAuthProviderImpl = class {
 	async handleTokenRequest(body, clientInfo, env, requestUrl, request) {
 		try {
 			const grantType = body.grant_type;
+			if (!(grantType === GrantType.AUTHORIZATION_CODE || grantType === GrantType.REFRESH_TOKEN || grantType === GrantType.TOKEN_EXCHANGE && !!this.options.allowTokenExchangeGrant || grantType === GrantType.JWT_BEARER && !!this.options.enterpriseManagedAuthorization)) return this.createErrorResponse("unsupported_grant_type", { description: "Grant type not supported" }, {
+				category: "token-endpoint-request",
+				reason: "grant_type_not_supported"
+			});
+			if (grantType !== GrantType.JWT_BEARER && Array.isArray(clientInfo.grantTypes)) {
+				const registered = clientInfo.grantTypes;
+				if (!(registered.includes(grantType) || grantType === GrantType.REFRESH_TOKEN && registered.includes(GrantType.AUTHORIZATION_CODE))) return this.createErrorResponse("unauthorized_client", { description: "The client is not registered for this grant type" }, {
+					category: "token-endpoint-request",
+					reason: "grant_type_not_registered"
+				});
+			}
+			this.validateTokenRequestResourceIndicator(body.resource);
 			if (grantType === GrantType.AUTHORIZATION_CODE) return await this.handleAuthorizationCodeGrant(body, clientInfo, env);
 			else if (grantType === GrantType.REFRESH_TOKEN) return await this.handleRefreshTokenGrant(body, clientInfo, env);
 			else if (grantType === GrantType.TOKEN_EXCHANGE && this.options.allowTokenExchangeGrant) return await this.handleTokenExchangeGrant(body, clientInfo, env);
 			else if (grantType === GrantType.JWT_BEARER) return await this.handleJwtBearerGrant(body, clientInfo, env, requestUrl, request);
-			else return this.createErrorResponse("unsupported_grant_type", { description: "Grant type not supported" });
+			throw new Error("Unreachable supported grant type");
 		} catch (error) {
 			const response = this.createOAuthErrorResponse(error);
 			if (response) return response;
@@ -1831,7 +2462,11 @@ var OAuthProviderImpl = class {
 	*/
 	createOAuthErrorResponse(error) {
 		if (!(error instanceof OAuthError)) return void 0;
-		return this.createErrorResponse(error.code, error.options);
+		return this.createErrorResponse(error.code, error.options, error.options.internal ?? {
+			category: "token-exchange-callback",
+			reason: "callback_error",
+			detail: error
+		});
 	}
 	/**
 	* Build a structured protected-resource response from an external-token error.
@@ -1840,7 +2475,7 @@ var OAuthProviderImpl = class {
 	* 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) {
+	createExternalTokenErrorResponse(error, resourceMetadataUrl, resourceServer) {
 		if (!(error instanceof ExternalTokenError)) return void 0;
 		const headers = error.headers ?? {};
 		const hasChallenge = Object.keys(headers).some((name) => name.toLowerCase() === "www-authenticate");
@@ -1851,13 +2486,17 @@ var OAuthProviderImpl = class {
 			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)
+				"WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, error.code, void 0, requiredScopes, resourceServer)
 			};
 		}
 		return this.createErrorResponse(error.code, {
 			description: error.description,
 			statusCode: error.statusCode,
 			headers: challengeHeaders ?? headers
+		}, {
+			category: "protected-resource",
+			reason: "resolver_rejected",
+			detail: error
 		});
 	}
 	/**
@@ -1872,34 +2511,72 @@ var OAuthProviderImpl = class {
 		const code = body.code;
 		const redirectUri = body.redirect_uri;
 		const codeVerifier = body.code_verifier;
-		if (!code) return this.createErrorResponse("invalid_request", { description: "Authorization code is required" });
+		if (!code) return this.createErrorResponse("invalid_request", { description: "Authorization code is required" }, {
+			category: "authorization-code-grant",
+			reason: "code_missing"
+		});
 		const codeParts = code.split(":");
-		if (codeParts.length !== 3) return this.createErrorResponse("invalid_grant", { description: "Invalid authorization code format" });
+		if (codeParts.length !== 3) return this.createErrorResponse("invalid_grant", { description: "Invalid authorization code format" }, {
+			category: "authorization-code-grant",
+			reason: "code_malformed"
+		});
 		const [userId, grantId, _] = codeParts;
 		const grantKey = `grant:${userId}:${grantId}`;
 		const grantData = await env.OAUTH_KV.get(grantKey, { type: "json" });
-		if (!grantData) return this.createErrorResponse("invalid_grant", { description: "Grant not found or authorization code expired" });
+		if (!grantData) return this.createErrorResponse("invalid_grant", { description: "Grant not found or authorization code expired" }, {
+			category: "authorization-code-grant",
+			reason: "grant_not_found"
+		});
 		const codeHash = await hashSecret(code);
-		if (!grantData.authCodeId || codeHash !== grantData.authCodeId) return this.createErrorResponse("invalid_grant", { description: "Invalid authorization code" });
-		if (grantData.clientId !== clientInfo.clientId) return this.createErrorResponse("invalid_grant", { description: "Client ID mismatch" });
+		if (!grantData.authCodeId || codeHash !== grantData.authCodeId) return this.createErrorResponse("invalid_grant", { description: "Invalid authorization code" }, {
+			category: "authorization-code-grant",
+			reason: "code_mismatch"
+		});
+		if (grantData.clientId !== clientInfo.clientId) return this.createErrorResponse("invalid_grant", { description: "Client ID mismatch" }, {
+			category: "authorization-code-grant",
+			reason: "client_mismatch"
+		});
 		if (!grantData.authCodeWrappedKey) {
 			try {
 				await this.createOAuthHelpers(env).revokeGrant(grantId, userId);
 			} catch {}
-			return this.createErrorResponse("invalid_grant", { description: "Authorization code already used" });
+			return this.createErrorResponse("invalid_grant", { description: "Authorization code already used" }, {
+				category: "authorization-code-grant",
+				reason: "code_replayed"
+			});
 		}
 		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" });
+			return this.createErrorResponse("invalid_grant", { description: error instanceof Error ? error.message : "Invalid PKCE code_challenge_method" }, {
+				category: "authorization-code-grant",
+				reason: "pkce_method_invalid",
+				detail: error
+			});
 		}
 		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" });
-		if (!isPkceEnabled && codeVerifier) return this.createErrorResponse("invalid_request", { description: "code_verifier provided for a flow that did not use PKCE" });
+		if (!redirectUri && !isPkceEnabled) return this.createErrorResponse("invalid_request", { description: "redirect_uri is required when not using PKCE" }, {
+			category: "authorization-code-grant",
+			reason: "redirect_uri_missing"
+		});
+		if (redirectUri && !isValidRedirectUri(redirectUri, clientInfo.redirectUris)) return this.createErrorResponse("invalid_grant", { description: "Invalid redirect URI" }, {
+			category: "authorization-code-grant",
+			reason: "redirect_uri_invalid"
+		});
+		if (redirectUri && grantData.redirectUri !== void 0 && redirectUri !== grantData.redirectUri) return this.createErrorResponse("invalid_grant", { description: "redirect_uri does not match the authorization request" }, {
+			category: "authorization-code-grant",
+			reason: "redirect_uri_mismatch"
+		});
+		if (!isPkceEnabled && codeVerifier) return this.createErrorResponse("invalid_request", { description: "code_verifier provided for a flow that did not use PKCE" }, {
+			category: "authorization-code-grant",
+			reason: "unexpected_code_verifier"
+		});
 		if (isPkceEnabled) {
-			if (!codeVerifier) return this.createErrorResponse("invalid_request", { description: "code_verifier is required for PKCE" });
+			if (!codeVerifier) return this.createErrorResponse("invalid_request", { description: "code_verifier is required for PKCE" }, {
+				category: "authorization-code-grant",
+				reason: "code_verifier_missing"
+			});
 			let calculatedChallenge;
 			if (codeChallengeMethod === "S256") {
 				const data = new TextEncoder().encode(codeVerifier);
@@ -1907,9 +2584,13 @@ var OAuthProviderImpl = class {
 				const hashArray = Array.from(new Uint8Array(hashBuffer));
 				calculatedChallenge = base64UrlEncode(String.fromCharCode(...hashArray));
 			} else calculatedChallenge = codeVerifier;
-			if (calculatedChallenge !== grantData.codeChallenge) return this.createErrorResponse("invalid_grant", { description: "Invalid PKCE code_verifier" });
+			if (calculatedChallenge !== grantData.codeChallenge) return this.createErrorResponse("invalid_grant", { description: "Invalid PKCE code_verifier" }, {
+				category: "authorization-code-grant",
+				reason: "code_verifier_mismatch"
+			});
 		}
-		const audience = this.resolveTokenResource(body.resource, grantData.resource);
+		const resourceResolution = this.resolveTokenResource(body.resource, grantData);
+		const audience = resourceResolution.audience;
 		let accessTokenTTL = this.options.accessTokenTTL;
 		let refreshTokenTTL = this.options.refreshTokenTTL;
 		const encryptionKey = await unwrapKeyWithToken(code, grantData.authCodeWrappedKey);
@@ -1924,10 +2605,12 @@ var OAuthProviderImpl = class {
 			const callbackOptions = {
 				grantType: GrantType.AUTHORIZATION_CODE,
 				clientId: clientInfo.clientId,
+				subjectClientId: grantData.clientId,
 				userId,
 				grantId,
 				scope: grantData.scope,
 				requestedScope: tokenScopes,
+				resource: audience,
 				props: decryptedProps
 			};
 			const callbackResult = await Promise.resolve(this.options.tokenExchangeCallback(callbackOptions));
@@ -1939,6 +2622,10 @@ var OAuthProviderImpl = class {
 				if (callbackResult.accessTokenProps) accessTokenProps = callbackResult.accessTokenProps;
 				if (callbackResult.accessTokenTTL !== void 0) accessTokenTTL = callbackResult.accessTokenTTL;
 				if ("refreshTokenTTL" in callbackResult) refreshTokenTTL = callbackResult.refreshTokenTTL;
+				if (callbackResult.refreshTokenIdleTTL !== void 0) return this.createErrorResponse("invalid_request", { description: "refreshTokenIdleTTL is only honored during refresh token exchange" }, {
+					category: "authorization-code-grant",
+					reason: "refresh_token_idle_ttl_wrong_grant"
+				});
 				if (callbackResult.accessTokenScope) tokenScopes = this.downscope(callbackResult.accessTokenScope, grantData.scope);
 			}
 			const grantResult = await encryptProps(grantProps);
@@ -1953,6 +2640,10 @@ var OAuthProviderImpl = class {
 				accessTokenEncryptionKey = grantEncryptionKey;
 			}
 		}
+		if (!isValidAccessTokenTTL(accessTokenTTL)) return this.createErrorResponse("invalid_request", { description: "Requested token lifetime must be at least 60 seconds" }, {
+			category: "authorization-code-grant",
+			reason: "requested_ttl_too_short"
+		});
 		const now = Math.floor(Date.now() / 1e3);
 		const useRefreshToken = refreshTokenTTL !== 0;
 		delete grantData.codeChallenge;
@@ -1970,6 +2661,7 @@ var OAuthProviderImpl = class {
 			grantData.previousRefreshTokenWrappedKey = void 0;
 			grantData.expiresAt = expiresAt;
 		}
+		if (resourceResolution.grantResourceBackfill) grantData.resource = resourceResolution.grantResourceBackfill;
 		await this.saveGrantWithTTL(env, grantKey, grantData, now);
 		const tokenResponse = {
 			access_token: await this.createAccessToken({
@@ -1985,10 +2677,10 @@ var OAuthProviderImpl = class {
 			}),
 			token_type: "bearer",
 			expires_in: accessTokenTTL,
-			scope: tokenScopes.join(" ")
+			scope: tokenScopes.join(" "),
+			resource: audience
 		};
 		if (refreshToken) tokenResponse.refresh_token = refreshToken;
-		if (audience) tokenResponse.resource = audience;
 		return new Response(JSON.stringify(tokenResponse), { headers: {
 			"Content-Type": "application/json",
 			...NO_CACHE_HEADERS
@@ -2004,26 +2696,46 @@ var OAuthProviderImpl = class {
 	*/
 	async handleRefreshTokenGrant(body, clientInfo, env) {
 		const refreshToken = body.refresh_token;
-		if (!refreshToken) return this.createErrorResponse("invalid_request", { description: "Refresh token is required" });
+		if (!refreshToken) return this.createErrorResponse("invalid_request", { description: "Refresh token is required" }, {
+			category: "refresh-token-grant",
+			reason: "refresh_token_missing"
+		});
 		const tokenParts = refreshToken.split(":");
-		if (tokenParts.length !== 3) return this.createErrorResponse("invalid_grant", { description: "Invalid token format" });
+		if (tokenParts.length !== 3) return this.createErrorResponse("invalid_grant", { description: "Invalid token format" }, {
+			category: "refresh-token-grant",
+			reason: "refresh_token_malformed"
+		});
 		const [userId, grantId, _] = tokenParts;
 		const providedTokenHash = await generateTokenId(refreshToken);
 		const grantKey = `grant:${userId}:${grantId}`;
 		const grantData = await env.OAUTH_KV.get(grantKey, { type: "json" });
-		if (!grantData) return this.createErrorResponse("invalid_grant", { description: "Grant not found" });
+		if (!grantData) return this.createErrorResponse("invalid_grant", { description: "Grant not found" }, {
+			category: "refresh-token-grant",
+			reason: "grant_not_found"
+		});
 		const isCurrentToken = grantData.refreshTokenId === providedTokenHash;
 		const isPreviousToken = grantData.previousRefreshTokenId === providedTokenHash;
-		if (!isCurrentToken && !isPreviousToken) return this.createErrorResponse("invalid_grant", { description: "Invalid refresh token" });
-		if (grantData.clientId !== clientInfo.clientId) return this.createErrorResponse("invalid_grant", { description: "Client ID mismatch" });
+		if (!isCurrentToken && !isPreviousToken) return this.createErrorResponse("invalid_grant", { description: "Invalid refresh token" }, {
+			category: "refresh-token-grant",
+			reason: "refresh_token_mismatch"
+		});
+		if (grantData.clientId !== clientInfo.clientId) return this.createErrorResponse("invalid_grant", { description: "Client ID mismatch" }, {
+			category: "refresh-token-grant",
+			reason: "client_mismatch"
+		});
 		if (grantData.expiresAt !== void 0) {
 			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" });
+			if (grantData.expiresAt - now$1 < KV_MIN_EXPIRATION_TTL_SECONDS) return this.createErrorResponse("invalid_grant", { description: "Refresh token has expired" }, {
+				category: "refresh-token-grant",
+				reason: "refresh_token_expired"
+			});
 		}
-		const audience = this.resolveTokenResource(body.resource, grantData.resource);
+		const resourceResolution = this.resolveTokenResource(body.resource, grantData);
+		const audience = resourceResolution.audience;
 		const newAccessToken = `${userId}:${grantId}:${generateRandomString(TOKEN_LENGTH)}`;
 		const accessTokenId = await generateTokenId(newAccessToken);
 		let accessTokenTTL = this.options.accessTokenTTL;
+		let refreshTokenIdleTTL = this.options.refreshTokenIdleTTL;
 		let wrappedKeyToUse;
 		if (isCurrentToken) wrappedKeyToUse = grantData.refreshTokenWrappedKey;
 		else wrappedKeyToUse = grantData.previousRefreshTokenWrappedKey;
@@ -2040,10 +2752,12 @@ var OAuthProviderImpl = class {
 			const callbackOptions = {
 				grantType: GrantType.REFRESH_TOKEN,
 				clientId: clientInfo.clientId,
+				subjectClientId: grantData.clientId,
 				userId,
 				grantId,
 				scope: grantData.scope,
 				requestedScope: tokenScopes,
+				resource: audience,
 				props: decryptedProps
 			};
 			const callbackResult = await Promise.resolve(this.options.tokenExchangeCallback(callbackOptions));
@@ -2055,7 +2769,17 @@ var OAuthProviderImpl = class {
 				}
 				if (callbackResult.accessTokenProps) accessTokenProps = callbackResult.accessTokenProps;
 				if (callbackResult.accessTokenTTL !== void 0) accessTokenTTL = callbackResult.accessTokenTTL;
-				if ("refreshTokenTTL" in callbackResult) return this.createErrorResponse("invalid_request", { description: "refreshTokenTTL cannot be changed during refresh token exchange" });
+				if ("refreshTokenTTL" in callbackResult) return this.createErrorResponse("invalid_request", { description: "refreshTokenTTL cannot be changed during refresh token exchange" }, {
+					category: "refresh-token-grant",
+					reason: "refresh_token_ttl_immutable"
+				});
+				if (callbackResult.refreshTokenIdleTTL !== void 0) {
+					if (!isValidAccessTokenTTL(callbackResult.refreshTokenIdleTTL)) return this.createErrorResponse("invalid_request", { description: `refreshTokenIdleTTL must be an integer of at least ${KV_MIN_EXPIRATION_TTL_SECONDS} seconds` }, {
+						category: "refresh-token-grant",
+						reason: "refresh_token_idle_ttl_invalid"
+					});
+					refreshTokenIdleTTL = callbackResult.refreshTokenIdleTTL;
+				}
 				if (callbackResult.accessTokenScope) tokenScopes = this.downscope(callbackResult.accessTokenScope, grantData.scope);
 			}
 			if (grantPropsChanged) {
@@ -2076,12 +2800,19 @@ var OAuthProviderImpl = class {
 			}
 		}
 		const now = Math.floor(Date.now() / 1e3);
-		if (grantData.expiresAt !== void 0 && grantData.expiresAt - now < KV_MIN_EXPIRATION_TTL_SECONDS) return this.createErrorResponse("invalid_grant", { description: "Refresh token has expired" });
+		if (grantData.expiresAt !== void 0 && grantData.expiresAt - now < KV_MIN_EXPIRATION_TTL_SECONDS) return this.createErrorResponse("invalid_grant", { description: "Refresh token has expired" }, {
+			category: "refresh-token-grant",
+			reason: "refresh_token_expired"
+		});
+		if (refreshTokenIdleTTL !== void 0) grantData.expiresAt = now + refreshTokenIdleTTL;
 		if (grantData.expiresAt !== void 0) {
 			const remainingRefreshTokenLifetime = grantData.expiresAt - now;
 			if (remainingRefreshTokenLifetime > 0) accessTokenTTL = Math.min(accessTokenTTL, remainingRefreshTokenLifetime);
 		}
-		if (accessTokenTTL < KV_MIN_EXPIRATION_TTL_SECONDS) return this.createErrorResponse("invalid_request", { description: "Requested token lifetime must be at least 60 seconds" });
+		if (!isValidAccessTokenTTL(accessTokenTTL)) return this.createErrorResponse("invalid_request", { description: "Requested token lifetime must be at least 60 seconds" }, {
+			category: "refresh-token-grant",
+			reason: "requested_ttl_too_short"
+		});
 		const accessTokenExpiresAt = now + accessTokenTTL;
 		const accessTokenWrappedKey = await wrapKeyWithToken(newAccessToken, accessTokenEncryptionKey);
 		const newRefreshToken = `${userId}:${grantId}:${generateRandomString(TOKEN_LENGTH)}`;
@@ -2091,6 +2822,7 @@ var OAuthProviderImpl = class {
 		grantData.previousRefreshTokenWrappedKey = wrappedKeyToUse;
 		grantData.refreshTokenId = newRefreshTokenId;
 		grantData.refreshTokenWrappedKey = newRefreshTokenWrappedKey;
+		if (resourceResolution.grantResourceBackfill) grantData.resource = resourceResolution.grantResourceBackfill;
 		await this.saveGrantWithTTL(env, grantKey, grantData, now);
 		const accessTokenData = {
 			id: accessTokenId,
@@ -2118,9 +2850,9 @@ var OAuthProviderImpl = class {
 			token_type: "bearer",
 			expires_in: accessTokenTTL,
 			refresh_token: newRefreshToken,
-			scope: tokenScopes.join(" ")
+			scope: tokenScopes.join(" "),
+			resource: audience
 		};
-		if (audience) tokenResponse.resource = audience;
 		return new Response(JSON.stringify(tokenResponse), { headers: {
 			"Content-Type": "application/json",
 			...NO_CACHE_HEADERS
@@ -2134,7 +2866,7 @@ var OAuthProviderImpl = class {
 	* module-private.
 	* @param subjectToken - The subject token to exchange
 	* @param requestedScopes - Optional requested scopes, limited to the subject token's scopes
-	* @param requestedResource - Optional resource/audience (must be subset of original if original had resource)
+	* @param requestedResource - Optional resource/audience; when present, it must match the configured canonical resource
 	* @param expiresIn - Optional TTL override in seconds
 	* @param clientInfo - The client making the exchange request
 	* @param env - Cloudflare Worker environment variables
@@ -2143,24 +2875,61 @@ var OAuthProviderImpl = class {
 	*/
 	async exchangeToken(subjectToken, requestedScopes, requestedResource, expiresIn, clientInfo, env) {
 		const tokenSummary = await this.unwrapToken(subjectToken, env);
-		if (!tokenSummary) throw new OAuthError("invalid_grant", { description: "Invalid or expired subject token" });
+		if (!tokenSummary) throw new OAuthError("invalid_request", {
+			description: "Invalid or expired subject token",
+			internal: {
+				category: "token-exchange-grant",
+				reason: "subject_token_invalid"
+			}
+		});
 		const grantKey = `grant:${tokenSummary.userId}:${tokenSummary.grantId}`;
 		const grantData = await env.OAUTH_KV.get(grantKey, { type: "json" });
-		if (!grantData) throw new OAuthError("invalid_grant", { description: "Grant not found" });
+		if (!grantData) throw new OAuthError("invalid_request", {
+			description: "Grant not found",
+			internal: {
+				category: "token-exchange-grant",
+				reason: "grant_not_found"
+			}
+		});
+		const crossClientExchange = grantData.clientId !== clientInfo.clientId;
+		const crossClientRejection = () => new OAuthError("invalid_request", {
+			description: "The subject token was issued to a different client",
+			internal: {
+				category: "token-exchange-grant",
+				reason: "cross_client_subject_token"
+			}
+		});
+		if (crossClientExchange && !this.options.tokenExchangeCallback) throw crossClientRejection();
 		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 = requestedResource === void 0 ? tokenSummary.audience : this.resolveTokenResource(requestedResource, grantData.resource);
+		const newAudience = this.resolveTokenExchangeResource(requestedResource, tokenSummary.audience);
 		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" });
+		if (subjectTokenRemainingLifetime < KV_MIN_EXPIRATION_TTL_SECONDS) throw new OAuthError("invalid_request", {
+			description: "Subject token is too close to expiry to exchange",
+			internal: {
+				category: "token-exchange-grant",
+				reason: "subject_token_near_expiry"
+			}
+		});
 		let accessTokenTTL = this.options.accessTokenTTL ?? DEFAULT_ACCESS_TOKEN_TTL;
 		if (expiresIn !== void 0) {
-			if (expiresIn <= 0) throw new OAuthError("invalid_request", { description: "Invalid expires_in parameter" });
+			if (expiresIn <= 0) throw new OAuthError("invalid_request", {
+				description: "Invalid expires_in parameter",
+				internal: {
+					category: "token-exchange-grant",
+					reason: "expires_in_invalid"
+				}
+			});
 			accessTokenTTL = Math.min(expiresIn, subjectTokenRemainingLifetime);
 		} else accessTokenTTL = Math.min(accessTokenTTL, subjectTokenRemainingLifetime);
 		const subjectTokenData = await env.OAUTH_KV.get(`token:${tokenSummary.userId}:${tokenSummary.grantId}:${tokenSummary.id}`, { type: "json" });
-		if (!subjectTokenData) throw new OAuthError("invalid_grant", { description: "Subject token data not found" });
+		if (!subjectTokenData) throw new OAuthError("invalid_request", {
+			description: "Subject token data not found",
+			internal: {
+				category: "token-exchange-grant",
+				reason: "subject_token_data_missing"
+			}
+		});
 		const encryptionKey = await unwrapKeyWithToken(subjectToken, subjectTokenData.wrappedEncryptionKey);
 		let accessTokenEncryptionKey = encryptionKey;
 		let encryptedAccessTokenProps = subjectTokenData.grant.encryptedProps;
@@ -2169,13 +2938,16 @@ var OAuthProviderImpl = class {
 			const callbackOptions = {
 				grantType: GrantType.TOKEN_EXCHANGE,
 				clientId: clientInfo.clientId,
+				subjectClientId: grantData.clientId,
 				userId: tokenSummary.userId,
 				grantId: tokenSummary.grantId,
 				scope: tokenSummary.grant.scope,
 				requestedScope: tokenScopes,
+				resource: newAudience,
 				props: decryptedProps
 			};
 			const callbackResult = await Promise.resolve(this.options.tokenExchangeCallback(callbackOptions));
+			if (crossClientExchange && callbackResult?.allowCrossClientExchange !== true) throw crossClientRejection();
 			if (callbackResult) {
 				let accessTokenProps = decryptedProps;
 				if (callbackResult.newProps) {
@@ -2183,6 +2955,13 @@ var OAuthProviderImpl = class {
 				}
 				if (callbackResult.accessTokenProps) accessTokenProps = callbackResult.accessTokenProps;
 				if (callbackResult.accessTokenTTL !== void 0) accessTokenTTL = Math.min(callbackResult.accessTokenTTL, subjectTokenRemainingLifetime);
+				if (callbackResult.refreshTokenIdleTTL !== void 0) throw new OAuthError("invalid_request", {
+					description: "refreshTokenIdleTTL is only honored during refresh token exchange",
+					internal: {
+						category: "token-exchange-grant",
+						reason: "refresh_token_idle_ttl_wrong_grant"
+					}
+				});
 				if (accessTokenProps !== decryptedProps) {
 					const tokenResult = await encryptProps(accessTokenProps);
 					encryptedAccessTokenProps = tokenResult.encryptedData;
@@ -2191,8 +2970,14 @@ var OAuthProviderImpl = class {
 				if (callbackResult.accessTokenScope) tokenScopes = this.downscope(callbackResult.accessTokenScope, tokenSummary.scope);
 			}
 		}
-		if (accessTokenTTL < KV_MIN_EXPIRATION_TTL_SECONDS) throw new OAuthError("invalid_request", { description: "Requested token lifetime must be at least 60 seconds" });
-		const tokenResponse = {
+		if (!isValidAccessTokenTTL(accessTokenTTL)) throw new OAuthError("invalid_request", {
+			description: "Requested token lifetime must be at least 60 seconds",
+			internal: {
+				category: "token-exchange-grant",
+				reason: "requested_ttl_too_short"
+			}
+		});
+		return {
 			access_token: await this.createAccessToken({
 				userId: tokenSummary.userId,
 				grantId: tokenSummary.grantId,
@@ -2207,10 +2992,9 @@ var OAuthProviderImpl = class {
 			issued_token_type: "urn:ietf:params:oauth:token-type:access_token",
 			token_type: "bearer",
 			expires_in: accessTokenTTL,
-			scope: tokenScopes.join(" ")
+			scope: tokenScopes.join(" "),
+			resource: newAudience
 		};
-		if (newAudience) tokenResponse.resource = newAudience;
-		return tokenResponse;
 	}
 	/**
 	* Handles OAuth 2.0 token exchange requests (RFC 8693)
@@ -2226,18 +3010,36 @@ var OAuthProviderImpl = class {
 		const requestedTokenType = body.requested_token_type || "urn:ietf:params:oauth:token-type:access_token";
 		const requestedScope = body.scope;
 		const requestedResource = body.resource;
-		if (!subjectToken) return this.createErrorResponse("invalid_request", { description: "subject_token is required" });
-		if (!subjectTokenType) return this.createErrorResponse("invalid_request", { description: "subject_token_type is required" });
-		if (subjectTokenType !== "urn:ietf:params:oauth:token-type:access_token") return this.createErrorResponse("invalid_request", { description: "Only access_token subject_token_type is supported" });
-		if (requestedTokenType !== "urn:ietf:params:oauth:token-type:access_token") return this.createErrorResponse("invalid_request", { description: "Only access_token requested_token_type is supported" });
+		if (!subjectToken) return this.createErrorResponse("invalid_request", { description: "subject_token is required" }, {
+			category: "token-exchange-grant",
+			reason: "subject_token_missing"
+		});
+		if (!subjectTokenType) return this.createErrorResponse("invalid_request", { description: "subject_token_type is required" }, {
+			category: "token-exchange-grant",
+			reason: "subject_token_type_missing"
+		});
+		if (subjectTokenType !== "urn:ietf:params:oauth:token-type:access_token") return this.createErrorResponse("invalid_request", { description: "Only access_token subject_token_type is supported" }, {
+			category: "token-exchange-grant",
+			reason: "subject_token_type_unsupported"
+		});
+		if (requestedTokenType !== "urn:ietf:params:oauth:token-type:access_token") return this.createErrorResponse("invalid_request", { description: "Only access_token requested_token_type is supported" }, {
+			category: "token-exchange-grant",
+			reason: "requested_token_type_unsupported"
+		});
 		let requestedScopes;
 		if (requestedScope) if (typeof requestedScope === "string") requestedScopes = requestedScope.split(" ").filter(Boolean);
 		else if (Array.isArray(requestedScope)) requestedScopes = requestedScope;
-		else return this.createErrorResponse("invalid_request", { description: "Invalid scope parameter format" });
+		else return this.createErrorResponse("invalid_request", { description: "Invalid scope parameter format" }, {
+			category: "token-exchange-grant",
+			reason: "scope_malformed"
+		});
 		let expiresIn;
 		if (body.expires_in !== void 0) {
 			const requestedTTL = parseInt(body.expires_in, 10);
-			if (isNaN(requestedTTL) || requestedTTL <= 0) return this.createErrorResponse("invalid_request", { description: "Invalid expires_in parameter" });
+			if (isNaN(requestedTTL) || requestedTTL <= 0) return this.createErrorResponse("invalid_request", { description: "Invalid expires_in parameter" }, {
+				category: "token-exchange-grant",
+				reason: "expires_in_invalid"
+			});
 			expiresIn = requestedTTL;
 		}
 		try {
@@ -2262,10 +3064,16 @@ var OAuthProviderImpl = class {
 	*/
 	async handleJwtBearerGrant(body, clientInfo, env, requestUrl, request) {
 		const enterpriseOptions = this.options.enterpriseManagedAuthorization;
-		if (!enterpriseOptions) return this.createErrorResponse("unsupported_grant_type", { description: "Grant type not supported" });
+		if (!enterpriseOptions) return this.createErrorResponse("unsupported_grant_type", { description: "Grant type not supported" }, {
+			category: "enterprise-managed-authorization",
+			reason: "grant_disabled"
+		});
 		if (clientInfo.tokenEndpointAuthMethod === "none" && !enterpriseOptions.allowPublicClients) return this.createErrorResponse("invalid_client", {
 			description: "Enterprise-managed authorization requires client authentication",
 			statusCode: 401
+		}, {
+			category: "enterprise-managed-authorization",
+			reason: "client_authentication_required"
 		});
 		const result = await this.runEmaPipeline({
 			body,
@@ -2300,8 +3108,8 @@ var OAuthProviderImpl = class {
 	async runEmaPipeline(args) {
 		const { body, clientInfo, env, requestUrl, request, enterpriseOptions } = args;
 		const { jwksProvider, jtiStore } = this;
-		const configuredResource = this.options.resourceMetadata?.resource;
-		if (!jwksProvider || !jtiStore || !configuredResource) throw new Error("EMA pipeline invoked without configured adapters");
+		const configuredResource = this.resolveNewTokenResource(body.resource);
+		if (!jwksProvider || !jtiStore) throw new Error("EMA pipeline invoked without configured adapters");
 		const now = Math.floor(Date.now() / 1e3);
 		const parsed = parseIdJag(body.assertion, EMA_MAX_JWT_BYTES);
 		if (!parsed.ok) return parsed;
@@ -2331,7 +3139,6 @@ var OAuthProviderImpl = class {
 			expectedAudience: trustedIssuer.value.audience ?? this.getAuthorizationServerIssuer(requestUrl),
 			clientId: clientInfo.clientId,
 			configuredResource,
-			matchOriginOnly: !!this.options.resourceMatchOriginOnly,
 			now,
 			clockSkewSeconds: enterpriseOptions.clockSkewSeconds ?? EMA_DEFAULT_CLOCK_SKEW_SECONDS,
 			maxAssertionLifetimeSeconds: enterpriseOptions.maxAssertionLifetimeSeconds ?? EMA_DEFAULT_MAX_ASSERTION_LIFETIME_SECONDS
@@ -2353,7 +3160,7 @@ var OAuthProviderImpl = class {
 			mapperOutput = await enterpriseOptions.mapClaims({
 				claims: claims.value.claims,
 				clientInfo,
-				resource: claims.value.resource,
+				resource: configuredResource,
 				requestedScope: requestedScope.value,
 				request: args.request,
 				env
@@ -2379,7 +3186,7 @@ var OAuthProviderImpl = class {
 			mapperProps: mapped.value.props,
 			mapperMetadata: mapped.value.metadata,
 			assertionScopes: claims.value.assertionScopes,
-			resource: claims.value.resource,
+			resource: configuredResource,
 			accessTokenTTLSeconds: ttl.value,
 			env,
 			now: issueNow
@@ -2478,7 +3285,10 @@ var OAuthProviderImpl = class {
 	async revokeToken(body, clientInfo, env) {
 		const token = body.token;
 		const tokenTypeHint = body.token_type_hint;
-		if (!token) return this.createErrorResponse("invalid_request", { description: "Token parameter is required" });
+		if (!token) return this.createErrorResponse("invalid_request", { description: "Token parameter is required" }, {
+			category: "token-revocation",
+			reason: "token_missing"
+		});
 		const tokenParts = token.split(":");
 		if (tokenParts.length !== 3) return new Response("", { status: 200 });
 		const [userId, grantId, _] = tokenParts;
@@ -2533,14 +3343,24 @@ var OAuthProviderImpl = class {
 		if (!this.options.clientRegistrationEndpoint) return this.createErrorResponse("not_implemented", {
 			description: "Client registration is not enabled",
 			statusCode: 501
+		}, {
+			category: "client-registration",
+			reason: "registration_disabled"
 		});
 		if (request.method !== "POST") return this.createErrorResponse("invalid_request", {
 			description: "Method not allowed",
-			statusCode: 405
+			statusCode: 405,
+			headers: { Allow: "POST, OPTIONS" }
+		}, {
+			category: "client-registration",
+			reason: "method_not_allowed"
 		});
 		if (parseInt(request.headers.get("Content-Length") || "0", 10) > 1048576) return this.createErrorResponse("invalid_request", {
 			description: "Request payload too large, must be under 1 MiB",
 			statusCode: 413
+		}, {
+			category: "client-registration",
+			reason: "declared_payload_too_large"
 		});
 		const callbackRequest = request.clone();
 		let parsedJson;
@@ -2549,12 +3369,18 @@ var OAuthProviderImpl = class {
 			if (text.length > 1048576) return this.createErrorResponse("invalid_request", {
 				description: "Request payload too large, must be under 1 MiB",
 				statusCode: 413
+			}, {
+				category: "client-registration",
+				reason: "payload_too_large"
 			});
 			parsedJson = JSON.parse(text);
 		} catch {
 			return this.createErrorResponse("invalid_request", {
 				description: "Invalid JSON payload",
 				statusCode: 400
+			}, {
+				category: "client-registration",
+				reason: "json_malformed"
 			});
 		}
 		let clientMetadata;
@@ -2563,11 +3389,18 @@ var OAuthProviderImpl = class {
 			clientMetadata = requireJsonObject(parsedJson);
 			metadata = resolveDynamicClientRegistrationMetadata(clientMetadata, this.serverCapabilities);
 		} catch (error) {
-			return this.createErrorResponse("invalid_client_metadata", { description: error instanceof Error ? error.message : "Invalid client metadata" });
+			return this.createErrorResponse("invalid_client_metadata", { description: error instanceof Error ? error.message : "Invalid client metadata" }, {
+				category: "client-registration",
+				reason: "metadata_invalid",
+				detail: error
+			});
 		}
 		const authMethod = metadata.tokenEndpointAuthMethod;
 		const isPublicClient = authMethod === "none";
-		if (isPublicClient && this.options.disallowPublicClientRegistration) return this.createErrorResponse("invalid_client_metadata", { description: "Public client registration is not allowed" });
+		if (isPublicClient && this.options.disallowPublicClientRegistration) return this.createErrorResponse("invalid_client_metadata", { description: "Public client registration is not allowed" }, {
+			category: "client-registration",
+			reason: "public_client_forbidden"
+		});
 		const clientId = generateRandomString(16);
 		let clientSecret;
 		let hashedSecret;
@@ -2604,16 +3437,22 @@ var OAuthProviderImpl = class {
 				return this.createErrorResponse("server_error", {
 					description: error instanceof Error ? error.message : "Client registration callback failed",
 					statusCode: 500
+				}, {
+					category: "client-registration",
+					reason: "callback_failed",
+					detail: error
 				});
 			}
 			if (callbackResult !== void 0) return this.createErrorResponse(callbackResult.code || "invalid_client_metadata", {
 				description: callbackResult.description || "Client registration denied",
 				statusCode: callbackResult.status ?? 400
+			}, {
+				category: "client-registration",
+				reason: "callback_denied",
+				detail: callbackResult
 			});
 		}
-		const clientKvOptions = {};
-		if (this.options.clientRegistrationTTL !== void 0) clientKvOptions.expirationTtl = this.options.clientRegistrationTTL;
-		await env.OAUTH_KV.put(`client:${clientInfo.clientId}`, JSON.stringify(clientInfo), clientKvOptions);
+		await this.putRegisteredClient(env, clientInfo, clientInfo.registrationDate);
 		const response = {
 			client_id: clientInfo.clientId,
 			redirect_uris: clientInfo.redirectUris,
@@ -2652,18 +3491,23 @@ var OAuthProviderImpl = class {
 	* @param ctx - Cloudflare Worker execution context
 	* @returns Response from the API handler or error
 	*/
-	async handleApiRequest(request, env, ctx) {
+	async handleApiRequest(request, env, ctx, apiRoute) {
 		const url = new URL(request.url);
-		const resourceMetadataUrl = `${url.origin}/.well-known/oauth-protected-resource${url.pathname}`;
+		const { resourceServer } = apiRoute;
+		const configuredResource = resourceServer.resourceMetadata.resource;
+		const externalTokenResolver = resourceServer.resolveExternalToken;
+		const resourceMetadataUrl = this.getResourceMetadataUrlForRequest(url, resourceServer);
+		const challenge = (error, description, scopes = []) => this.buildWwwAuthenticateHeader(resourceMetadataUrl, error, description, scopes, resourceServer);
 		const authHeader = request.headers.get("Authorization");
-		if (!authHeader || !authHeader.startsWith("Bearer ")) return new Response(null, {
+		const bearerMatch = authHeader ? /^Bearer[\t ]+([^\s,]+)$/i.exec(authHeader) : null;
+		if (!bearerMatch) return new Response(null, {
 			status: 401,
 			headers: {
 				...NO_CACHE_HEADERS,
-				"WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl)
+				"WWW-Authenticate": challenge()
 			}
 		});
-		const accessToken = authHeader.substring(7);
+		const accessToken = bearerMatch[1];
 		const parts = accessToken.split(":");
 		const isPossiblyInternalFormat = parts.length === 3;
 		let tokenData = null;
@@ -2674,75 +3518,104 @@ var OAuthProviderImpl = class {
 			const id = await generateTokenId(accessToken);
 			tokenData = await env.OAUTH_KV.get(`token:${userId}:${grantId}:${id}`, { type: "json" });
 		}
-		if (!tokenData && !this.options.resolveExternalToken) return this.createErrorResponse("invalid_token", {
+		if (!tokenData && !externalTokenResolver) return this.createErrorResponse("invalid_token", {
 			description: "Invalid access token",
 			statusCode: 401,
-			headers: { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") }
+			headers: { "WWW-Authenticate": challenge("invalid_token") }
+		}, {
+			category: "protected-resource",
+			reason: "token_not_found"
 		});
 		if (tokenData) {
-			const configuredResource = this.options.resourceMetadata?.resource;
-			if (configuredResource && !isExactResource(tokenData.audience, configuredResource)) return this.createErrorResponse("invalid_token", {
+			const tokenAudience = this.resolveStoredTokenAudience(tokenData.audience);
+			if (!isExactResource(tokenAudience, 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") }
+				headers: { "WWW-Authenticate": challenge("invalid_token") }
+			}, {
+				category: "protected-resource",
+				reason: "token_audience_unbound"
 			});
 			const now = Math.floor(Date.now() / 1e3);
 			if (tokenData.expiresAt < now) return this.createErrorResponse("invalid_token", {
 				description: "Access token expired",
 				statusCode: 401,
-				headers: { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token") }
+				headers: { "WWW-Authenticate": challenge("invalid_token") }
+			}, {
+				category: "protected-resource",
+				reason: "token_expired"
 			});
-			if (tokenData.audience) {
+			if (tokenAudience) {
 				const requestUrl = new URL(request.url);
-				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", {
+				const resourceServer$1 = `${requestUrl.protocol}//${requestUrl.host}${requestUrl.pathname}${requestUrl.search}`;
+				if (!(Array.isArray(tokenAudience) ? tokenAudience : [tokenAudience]).some((aud) => audienceMatches(resourceServer$1, aud))) return this.createErrorResponse("invalid_token", {
 					description: "Token audience does not match resource server",
 					statusCode: 401,
-					headers: { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token", "Invalid audience") }
+					headers: { "WWW-Authenticate": challenge("invalid_token", "Invalid audience") }
+				}, {
+					category: "protected-resource",
+					reason: "audience_mismatch"
 				});
 			}
 			ctx.props = await decryptProps(await unwrapKeyWithToken(accessToken, tokenData.wrappedEncryptionKey), tokenData.grant.encryptedProps);
-		} else if (this.options.resolveExternalToken) {
+			ctx.auth = {
+				token: accessToken,
+				audience: configuredResource,
+				expiresAt: tokenData.expiresAt,
+				scope: [...tokenData.scope || tokenData.grant.scope],
+				userId: tokenData.userId,
+				clientId: tokenData.grant.clientId
+			};
+		} else if (externalTokenResolver) {
 			let ext;
 			try {
-				ext = await this.options.resolveExternalToken({
+				ext = await externalTokenResolver({
 					token: accessToken,
 					request,
 					env
 				});
 			} catch (error) {
-				const response = this.createExternalTokenErrorResponse(error, resourceMetadataUrl);
+				const response = this.createExternalTokenErrorResponse(error, resourceMetadataUrl, resourceServer);
 				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") }
+				headers: { "WWW-Authenticate": challenge("invalid_token") }
+			}, {
+				category: "protected-resource",
+				reason: "external_token_rejected"
 			});
-			const configuredResource = this.options.resourceMetadata?.resource;
-			if (configuredResource && !isExactResource(ext.audience, configuredResource)) return this.createErrorResponse("invalid_token", {
+			if (typeof ext.audience !== "string" || !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") }
+				headers: { "WWW-Authenticate": challenge("invalid_token") }
+			}, {
+				category: "protected-resource",
+				reason: "external_audience_unbound"
 			});
 			if (ext.audience) {
 				const requestUrl = new URL(request.url);
-				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", {
+				const resourceServer$1 = `${requestUrl.protocol}//${requestUrl.host}${requestUrl.pathname}${requestUrl.search}`;
+				if (!(Array.isArray(ext.audience) ? ext.audience : [ext.audience]).some((aud) => audienceMatches(resourceServer$1, aud))) return this.createErrorResponse("invalid_token", {
 					description: "Token audience does not match resource server",
 					statusCode: 401,
-					headers: { "WWW-Authenticate": this.buildWwwAuthenticateHeader(resourceMetadataUrl, "invalid_token", "Invalid audience") }
+					headers: { "WWW-Authenticate": challenge("invalid_token", "Invalid audience") }
+				}, {
+					category: "protected-resource",
+					reason: "external_audience_mismatch"
 				});
 			}
 			ctx.props = ext.props;
+			ctx.auth = {
+				token: accessToken,
+				audience: configuredResource,
+				scope: []
+			};
 		}
 		if (!env.OAUTH_PROVIDER) env.OAUTH_PROVIDER = this.createOAuthHelpers(env);
-		const apiHandler = this.findApiHandlerForUrl(url);
-		if (!apiHandler) return this.createErrorResponse("invalid_request", {
-			description: "No handler found for API route",
-			statusCode: 404
-		});
+		const apiHandler = apiRoute.handler;
 		if (apiHandler.type === HandlerType.EXPORTED_HANDLER) return apiHandler.handler.fetch(request, env, ctx);
 		else return new apiHandler.handler(ctx, env).fetch(request);
 	}
@@ -2766,7 +3639,7 @@ var OAuthProviderImpl = class {
 		const minExpiration = now + KV_MIN_EXPIRATION_TTL_SECONDS + KV_EXPIRATION_CLAMP_MARGIN_SECONDS;
 		const kvOptions = grantData.expiresAt !== void 0 ? { expiration: Math.max(grantData.expiresAt, minExpiration) } : {};
 		try {
-			await env.OAUTH_KV.put(grantKey, JSON.stringify(grantData), kvOptions);
+			await env.OAUTH_KV.put(grantKey, JSON.stringify(grantData), grantPutOptions(grantData, kvOptions));
 		} catch (error) {
 			this.throwRetryableTokenStorageErrorIfKvRateLimited(error);
 			throw error;
@@ -2777,7 +3650,12 @@ var OAuthProviderImpl = class {
 		throw new OAuthError("temporarily_unavailable", {
 			description: "Token issuance is temporarily unavailable; retry shortly",
 			statusCode: 429,
-			headers: { "Retry-After": "30" }
+			headers: { "Retry-After": "30" },
+			internal: {
+				category: "token-issuance",
+				reason: "kv_rate_limited",
+				detail: error
+			}
 		});
 	}
 	isKvRateLimitError(error) {
@@ -2800,6 +3678,51 @@ var OAuthProviderImpl = class {
 	* propagate, and a CIMD metadata fetch failure throws `CimdFetchError`), so an
 	* upstream outage is distinguishable from an unregistered client.
 	*/
+	/**
+	* Write a client record that is subject to `clientRegistrationTTL`. The record carries
+	* the expiry it was written with, so a later token request can tell a registration the
+	* provider may renew from a permanent one without listing KV. With the TTL unset the
+	* record is written to last, and any stamp from an earlier configuration is dropped.
+	*/
+	async putRegisteredClient(env, client, now) {
+		const ttl = this.options.clientRegistrationTTL;
+		const { registrationExpiresAt: _previous, ...record } = client;
+		if (ttl === void 0) {
+			await env.OAUTH_KV.put(`client:${client.clientId}`, JSON.stringify(record));
+			return;
+		}
+		await env.OAUTH_KV.put(`client:${client.clientId}`, JSON.stringify({
+			...record,
+			registrationExpiresAt: now + ttl
+		}), { expirationTtl: ttl });
+	}
+	/**
+	* Renew a dynamically registered client whose registration has passed half of
+	* `clientRegistrationTTL`, so a client still exchanging tokens does not vanish from
+	* under its live grants. Without this, a grant that outlives its registration fails
+	* every refresh with `invalid_client` although nothing was revoked. Only records
+	* stamped with `registrationExpiresAt` qualify: CIMD clients are never stored,
+	* `createClient()` records never expire, and a record from before the stamp existed
+	* cannot be told from a permanent one, so it keeps its original schedule and
+	* re-registers once. The half-life rule bounds this to one write per client per half
+	* TTL. Best effort: the token response it follows has already been produced.
+	*
+	* KV has no compare-and-set, so a `deleteClient()` that lands between the read below and
+	* the write is undone by it, as it would be by a concurrent `updateClient()`. The window
+	* is one KV round trip, once per client per half TTL; closing it needs the serialised
+	* storage of #237.
+	*/
+	async renewClientRegistrationIfDue(env, client, now) {
+		const ttl = this.options.clientRegistrationTTL;
+		if (ttl === void 0 || client.registrationExpiresAt === void 0) return;
+		if (client.registrationExpiresAt - now > ttl / 2) return;
+		try {
+			const current = await env.OAUTH_KV.get(`client:${client.clientId}`, { type: "json" });
+			if (current) await this.putRegisteredClient(env, current, now);
+		} catch (error) {
+			console.warn(`Failed to renew client registration ${client.clientId}:`, error);
+		}
+	}
 	async getClient(env, clientId) {
 		if (this.isClientMetadataUrl(clientId)) {
 			if (!this.options.clientIdMetadataDocumentEnabled) {
@@ -2817,33 +3740,140 @@ var OAuthProviderImpl = class {
 		const clientKey = `client:${clientId}`;
 		return env.OAUTH_KV.get(clientKey, { type: "json" });
 	}
+	/** Resolve a value to the registry's canonical spelling, requiring one value. */
+	/**
+	* Resolve a stored grant or token resource. A 0.x record may hold an array; it resolves
+	* when exactly one configured resource appears in it, so multi-audience grants for two
+	* resources this server still hosts are ambiguous and fail closed.
+	*/
+	findStoredConfiguredResource(value) {
+		if (!Array.isArray(value)) return this.findConfiguredResource(value);
+		const matches = /* @__PURE__ */ new Set();
+		for (const entry of value) {
+			const configured = this.findConfiguredResource(entry);
+			if (configured) matches.add(configured);
+		}
+		return matches.size === 1 ? [...matches][0] : void 0;
+	}
+	findConfiguredResource(value) {
+		const distinct = Array.isArray(value) ? [...new Set(value)] : [value];
+		const singular = distinct.length === 1 ? distinct[0] : void 0;
+		if (typeof singular !== "string" || !validateResourceUri(singular)) return void 0;
+		return this.resourceServers.map((server) => server.resourceMetadata.resource).find((configured) => isExactResource(singular, configured));
+	}
+	/** Select the audience for a new interactive authorization. */
+	resolveAuthorizationRequestResource(requestedResource) {
+		if (requestedResource === void 0) {
+			const defaultResource = this.getDefaultAuthorizationResource();
+			if (defaultResource) return defaultResource;
+			throw new AuthorizationError("invalid_target", { description: "The resource parameter is required when the authorization server has multiple resources" });
+		}
+		const configured = this.findConfiguredResource(requestedResource);
+		if (!configured) throw new AuthorizationError("invalid_target", { description: "The resource parameter must name exactly one configured protected resource" });
+		return configured;
+	}
+	/** Whether an existing grant belongs to the replacement bucket for a resource. */
+	shouldReplaceGrantForResource(grantResource, resource) {
+		if (grantResource === void 0) return this.getLegacyGrantResource() === resource;
+		return isExactResource(grantResource, resource);
+	}
+	/** Select the audience for a new non-interactive grant such as EMA. */
+	resolveNewTokenResource(requestedResource) {
+		try {
+			return this.resolveAuthorizationRequestResource(requestedResource);
+		} catch (error) {
+			if (error instanceof AuthorizationError) throw new OAuthError("invalid_target", {
+				description: error.description,
+				internal: {
+					category: "resource-indicator",
+					reason: "resource_invalid",
+					detail: error
+				}
+			});
+			throw error;
+		}
+	}
+	/** Validate explicit resource syntax and configured-resource policy. */
+	validateTokenRequestResourceIndicator(requestedResource) {
+		if (requestedResource === void 0) return;
+		if (!this.findConfiguredResource(requestedResource)) throw new OAuthError("invalid_target", {
+			description: "The resource parameter must name exactly one configured protected resource",
+			internal: {
+				category: "resource-indicator",
+				reason: "resource_not_configured"
+			}
+		});
+	}
+	/** Resolve token exchange strictly within the subject token's audience ceiling. */
+	resolveTokenExchangeResource(requestedResource, subjectResource) {
+		const subjectAudience = this.findStoredConfiguredResource(this.resolveStoredTokenAudience(subjectResource));
+		if (!subjectAudience) throw new OAuthError("invalid_target", {
+			description: "Subject token is not bound to a configured resource",
+			internal: {
+				category: "resource-indicator",
+				reason: "subject_token_audience_unbound"
+			}
+		});
+		const resourceWasProvided = requestedResource !== void 0;
+		const requestedAudience = resourceWasProvided ? this.findConfiguredResource(requestedResource) : void 0;
+		if (resourceWasProvided && (!requestedAudience || requestedAudience !== subjectAudience)) throw new OAuthError("invalid_target", {
+			description: "The requested resource must exactly match the subject token audience",
+			internal: {
+				category: "resource-indicator",
+				reason: "resource_subject_token_mismatch"
+			}
+		});
+		return subjectAudience;
+	}
 	/**
 	* Resolves an access-token audience from a token request and its authorization 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.
+	* The configured canonical resource is inherited when omitted and cannot be overridden.
 	*/
-	resolveTokenResource(requestedResource, grantedResource) {
+	resolveTokenResource(requestedResource, grant) {
+		const grantedResource = grant.resource;
 		const resourceWasProvided = requestedResource !== void 0;
-		const requestedAudience = parseResourceParameter(requestedResource);
-		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 (grantResourceWasStored && !grantedAudience) throw new OAuthError("invalid_target", { description: "The authorization grant contains an invalid resource" });
-		const configuredResource = this.options.resourceMetadata?.resource;
-		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" });
+		const canonicalGrantResource = this.findStoredConfiguredResource(grantedResource);
+		const canonicalRequestedResource = resourceWasProvided ? this.findConfiguredResource(requestedResource) : void 0;
+		if (grantResourceWasStored && !canonicalGrantResource) throw new OAuthError("invalid_grant", {
+			description: "The authorization grant is not bound to a configured resource",
+			internal: {
+				category: "resource-indicator",
+				reason: "grant_audience_unbound"
+			}
+		});
+		if (canonicalGrantResource) {
+			if (resourceWasProvided && canonicalRequestedResource !== canonicalGrantResource) throw new OAuthError("invalid_target", {
+				description: "The requested resource does not match the authorization grant",
+				internal: {
+					category: "resource-indicator",
+					reason: "resource_grant_mismatch"
+				}
+			});
+			return {
+				audience: canonicalGrantResource,
+				...grantedResource === canonicalGrantResource ? {} : { grantResourceBackfill: canonicalGrantResource }
+			};
 		}
-		return requestedAudience ?? grantedAudience;
+		const legacyGrantResource = this.getLegacyGrantResource();
+		if (!legacyGrantResource) throw new OAuthError("invalid_grant", {
+			description: "This legacy authorization grant has no resource binding and must be reauthorized",
+			internal: {
+				category: "resource-indicator",
+				reason: "legacy_grant_unbound"
+			}
+		});
+		if (resourceWasProvided && canonicalRequestedResource !== legacyGrantResource) throw new OAuthError("invalid_target", {
+			description: "The requested resource does not match the server legacy-grant migration policy",
+			internal: {
+				category: "resource-indicator",
+				reason: "legacy_grant_resource_mismatch"
+			}
+		});
+		return {
+			audience: legacyGrantResource,
+			grantResourceBackfill: legacyGrantResource
+		};
 	}
 	/**
 	* Creates and stores an access token
@@ -2852,7 +3882,13 @@ var OAuthProviderImpl = class {
 	*/
 	async createAccessToken(params) {
 		const { userId, grantId, clientId, scope, encryptedProps, encryptionKey, expiresIn, audience, env } = params;
-		if (expiresIn < KV_MIN_EXPIRATION_TTL_SECONDS) throw new OAuthError("invalid_request", { description: "Requested token lifetime must be at least 60 seconds" });
+		if (!isValidAccessTokenTTL(expiresIn)) throw new OAuthError("invalid_request", {
+			description: "Requested token lifetime must be at least 60 seconds",
+			internal: {
+				category: "token-issuance",
+				reason: "requested_ttl_too_short"
+			}
+		});
 		const accessToken = `${userId}:${grantId}:${generateRandomString(TOKEN_LENGTH)}`;
 		const now = Math.floor(Date.now() / 1e3);
 		const accessTokenId = await generateTokenId(accessToken);
@@ -2908,14 +3944,36 @@ var OAuthProviderImpl = class {
 	/**
 	* Builds a WWW-Authenticate header value with resource_metadata per RFC 9728 §5.1
 	*/
-	buildWwwAuthenticateHeader(resourceMetadataUrl, error, errorDescription, requiredScopes = []) {
-		let header = `Bearer realm="OAuth", resource_metadata="${resourceMetadataUrl}"`;
+	buildWwwAuthenticateHeader(resourceMetadataUrl, error, errorDescription, requiredScopes = [], resourceServer = this.resourceServers[0]) {
+		let header = "Bearer realm=\"OAuth\"";
+		if (resourceMetadataUrl) header += `, resource_metadata="${resourceMetadataUrl}"`;
 		if (error) header += `, error="${error}"`;
-		const challengeScopes = requiredScopes.length > 0 ? this.normalizeProtectedResourceScopes(requiredScopes) : this.getProtectedResourceScopes();
+		const challengeScopes = requiredScopes.length > 0 ? this.normalizeProtectedResourceScopes(requiredScopes) : this.getProtectedResourceScopes(resourceServer);
 		if (challengeScopes.length > 0) header += `, scope="${challengeScopes.join(" ")}"`;
 		if (errorDescription) header += `, error_description="${errorDescription}"`;
 		return header;
 	}
+	/** Build the RFC 9728 well-known URL for the configured canonical resource. */
+	getConfiguredResourceMetadataUrl(resource) {
+		const authorityStart = resource.indexOf("://") + 3;
+		const suffixOffset = resource.slice(authorityStart).search(/[/?]/);
+		const suffixStart = suffixOffset === -1 ? resource.length : authorityStart + suffixOffset;
+		let suffix = resource.slice(suffixStart);
+		if (suffix === "/") suffix = "";
+		if (suffix.startsWith("/?")) suffix = suffix.slice(1);
+		return resource.slice(0, suffixStart) + PROTECTED_RESOURCE_WELL_KNOWN_PREFIX + suffix;
+	}
+	/**
+	* RFC 9728 §3.3 requires metadata fetched from a challenge to identify the
+	* original protected-resource URL. Descendant and alias routes can still use
+	* a base audience, but must not advertise a document for a different URL.
+	*/
+	getResourceMetadataUrlForRequest(requestUrl, resourceServer) {
+		const configuredResource = resourceServer.resourceMetadata.resource;
+		if (isExactResource(requestUrl.href, configuredResource)) return this.getConfiguredResourceMetadataUrl(configuredResource);
+		const resourceUrl = new URL(configuredResource);
+		if (requestUrl.origin === resourceUrl.origin && requestCarriesResourceQuery(requestUrl, resourceUrl) && isPathDescendant(requestUrl.pathname, resourceUrl.pathname)) return this.getConfiguredResourceMetadataUrl(configuredResource);
+	}
 	/**
 	* Helper function to create OAuth error responses.
 	*
@@ -2936,21 +3994,22 @@ var OAuthProviderImpl = class {
 			description,
 			status: responseStatus,
 			headers: responseHeaders,
-			...internal ? { internal } : {},
+			internal,
 			...request ? { request } : {}
 		});
-		if (customErrorResponse) return customErrorResponse;
 		const body = JSON.stringify({
 			error: code,
 			error_description: description
 		});
-		return new Response(body, {
+		const response = customErrorResponse ?? new Response(body, {
 			status: responseStatus,
 			headers: {
 				"Content-Type": "application/json",
 				...responseHeaders
 			}
 		});
+		this.errorResponses.add(response);
+		return response;
 	}
 };
 /**
@@ -3081,6 +4140,9 @@ const DEFAULT_CLIENT_REGISTRATION_TTL = 2160 * 60 * 60;
 * to clamp absolute expirations when writing grants back to KV.
 */
 const KV_MIN_EXPIRATION_TTL_SECONDS = 60;
+function isValidAccessTokenTTL(value) {
+	return Number.isInteger(value) && value >= KV_MIN_EXPIRATION_TTL_SECONDS;
+}
 /**
 * Safety margin (seconds) added on top of `KV_MIN_EXPIRATION_TTL_SECONDS` when clamping an
 * absolute KV expiration. Absolute expirations are validated against KV's clock at the
@@ -3099,8 +4161,9 @@ const DEFAULT_PURGE_BATCH_SIZE = 50;
 */
 const MAX_KV_LIST_LIMIT = 1e3;
 /**
-* Default batch size for paginating existing grants when revoking them
-* during completeAuthorization. Conservative for each KV list page.
+* How many grants written without key metadata `completeAuthorization()` reads at
+* once while looking for grants to replace. Grants written with key metadata are
+* matched from `list()` alone and never read.
 */
 const DEFAULT_REVOKE_EXISTING_GRANTS_BATCH_SIZE = 50;
 function getRevokeExistingGrantsBatchSize(batchSize) {
@@ -3108,27 +4171,38 @@ function getRevokeExistingGrantsBatchSize(batchSize) {
 	if (!Number.isFinite(batchSize) || !Number.isInteger(batchSize) || batchSize < 1) throw new Error("revokeExistingGrantsBatchSize must be a positive integer.");
 	return Math.min(batchSize, MAX_KV_LIST_LIMIT);
 }
+/** KV serialises key metadata as JSON and rejects a write carrying more than this. */
+const MAX_KV_METADATA_BYTES = 1024;
 /**
-* Length of generated token strings
+* Key metadata for a grant record, or `undefined` when it would not fit. A grant
+* written without metadata is read individually when scanned, exactly like a grant
+* written before metadata existed; that only happens when a `client_id` and two URLs
+* together exceed a kilobyte.
 */
-const TOKEN_LENGTH = 32;
+function grantKeyMetadata(grant) {
+	const metadata = { clientId: grant.clientId };
+	if (grant.resource !== void 0) metadata.resource = grant.resource;
+	if (grant.redirectUri !== void 0) metadata.redirectUri = grant.redirectUri;
+	return new TextEncoder().encode(JSON.stringify(metadata)).byteLength <= MAX_KV_METADATA_BYTES ? metadata : void 0;
+}
+/** Every grant write goes through here so the key metadata cannot drift from the record. */
+function grantPutOptions(grant, expiry = {}) {
+	const metadata = grantKeyMetadata(grant);
+	return metadata ? {
+		...expiry,
+		metadata
+	} : expiry;
+}
+/** Whether a listed key carries metadata this version can match a grant on. */
+function isGrantKeyMetadata(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const { clientId, resource, redirectUri } = value;
+	return typeof clientId === "string" && (resource === void 0 || typeof resource === "string" || Array.isArray(resource)) && (redirectUri === void 0 || typeof redirectUri === "string");
+}
 /**
-* Validates a resource URI per RFC 8707 Section 2
-* @param uri - The URI string to validate
-* @returns true if valid, false otherwise
+* Length of generated token strings
 */
-function validateResourceUri(uri) {
-	if (!uri || typeof uri !== "string") return false;
-	try {
-		const parsed = new URL(uri);
-		if (!parsed.protocol) return false;
-		if (parsed.hash) return false;
-		if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return false;
-		return true;
-	} catch {
-		return false;
-	}
-}
+const TOKEN_LENGTH = 32;
 /**
 * Checks if a resource server matches an audience claim.
 * Uses origin comparison (case-insensitive hostname via URL normalization)
@@ -3142,42 +4216,37 @@ 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 (!requestCarriesResourceQuery(resource, audience)) return false;
 		if (audience.pathname === "/" || audience.pathname === "") return true;
-		return resource.pathname === audience.pathname || resource.pathname.startsWith(audience.pathname + "/");
+		const descendantPrefix = audience.pathname.endsWith("/") ? audience.pathname : audience.pathname + "/";
+		return resource.pathname === audience.pathname || resource.pathname.startsWith(descendantPrefix);
 	} catch {
 		return false;
 	}
 }
-/**
-* Parses and validates the resource parameter from a token request (RFC 8707)
-* Handles single string or array of strings (from multiple form parameters)
-* @param value - The resource parameter value from the request body
-* @returns The validated value as string, string array, or undefined if validation fails
-*/
-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;
+function appendHeaderValue(headers, name, value) {
+	const values = (headers.get(name) ?? "").split(",").map((item) => item.trim()).filter(Boolean);
+	if (!values.some((item) => item.toLowerCase() === value.toLowerCase())) values.push(value);
+	headers.set(name, values.join(", "));
 }
-/** Whether a request or audience names one exact configured resource. */
+/** Whether a request or audience names one canonical configured resource. */
 function isExactResource(value, configuredResource) {
-	return value === configuredResource || Array.isArray(value) && value.length === 1 && value[0] === configuredResource;
+	if (Array.isArray(value)) return value.some((entry) => typeof entry === "string" && resourceMatches(entry, configuredResource));
+	return typeof value === "string" && resourceMatches(value, configuredResource);
 }
-/**
-* Checks if a requested resource matches a granted resource.
-* When originOnly is true, compares only the origin (scheme + host + port),
-* allowing path-aware resources to match origin-only grants.
-*/
-function resourceMatches(requested, granted, originOnly) {
-	if (!originOnly) return requested === granted;
-	try {
-		return new URL(requested).origin === new URL(granted).origin;
-	} catch {
-		return requested === granted;
-	}
+/** RFC 9110 §9.3.2: a HEAD response carries the GET headers and no body. */
+function withoutBodyForHead(request, response) {
+	if (request.method !== "HEAD") return response;
+	return new Response(null, {
+		status: response.status,
+		headers: response.headers
+	});
+}
+/** Whether `candidate` is `base` or a path-boundary descendant of it (trailing slashes ignored). */
+function isPathDescendant(candidate, base) {
+	if (base === "" || base === "/") return true;
+	if (base.endsWith("/")) return candidate.startsWith(base);
+	return candidate === base || candidate.startsWith(`${base}/`);
 }
 /**
 * Hashes a secret value using SHA-256
@@ -3248,11 +4317,7 @@ async function generateTokenId(token) {
 */
 function isLoopbackUri(uri) {
 	try {
-		const host = new URL(uri).hostname;
-		if (host.match(/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/)) return true;
-		if (host === "::1" || host === "[::1]") return true;
-		if (host.toLowerCase() === "localhost") return true;
-		return false;
+		return isLoopbackHostname(new URL(uri).hostname);
 	} catch {
 		return false;
 	}
@@ -3482,6 +4547,7 @@ var OAuthHelpersImpl = class {
 	*/
 	async parseAuthRequest(request) {
 		const url = new URL(request.url);
+		if (this.provider.hasExplicitIssuer && !this.provider.isAuthorizationEndpointRequest(url)) throw new AuthorizationError("invalid_request", { description: "Authorization request was sent to an unconfigured endpoint" });
 		const responseType = url.searchParams.get("response_type") || "";
 		const clientId = url.searchParams.get("client_id") || "";
 		const redirectUri = url.searchParams.get("redirect_uri") || "";
@@ -3504,13 +4570,12 @@ var OAuthHelpersImpl = class {
 		const withRedirect = (error) => {
 			throw withAuthorizationRedirect(error, redirectUri, state || void 0, issuer);
 		};
-		const resourceWasProvided = resourceParam !== void 0;
-		let resource = parseResourceParameter(resourceParam);
-		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) {
-			if (resourceWasProvided && !isExactResource(resource, configuredResource)) withRedirect(new AuthorizationError("invalid_target", { description: `The resource parameter must exactly match ${configuredResource}` }));
-			resource = configuredResource;
+		let resource;
+		try {
+			resource = this.provider.resolveAuthorizationRequestResource(resourceParam);
+		} catch (error) {
+			if (error instanceof AuthorizationError) withRedirect(error);
+			throw error;
 		}
 		try {
 			validateAuthorizationResponseType(this.provider.serverCapabilities, responseType, clientInfo.responseTypes);
@@ -3565,26 +4630,13 @@ var OAuthHelpersImpl = class {
 		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;
-		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;
+		const effectiveResource = this.provider.resolveAuthorizationRequestResource(options.request.resource);
 		validateAuthorizationPkce(this.provider.serverCapabilities, options.request, clientInfo);
 		let grantsToRevoke = [];
 		if (options.revokeExistingGrants !== false) {
 			const isCimdClient = this.provider.isClientMetadataUrl(clientId);
-			const batchSize = getRevokeExistingGrantsBatchSize(options.revokeExistingGrantsBatchSize);
-			let cursor;
-			do {
-				const page = await this.listUserGrants(options.userId, {
-					cursor,
-					limit: batchSize
-				});
-				for (const grant of page.items) if (grant.clientId === clientId && (!isCimdClient || grant.redirectUri === options.request.redirectUri)) grantsToRevoke.push(grant.id);
-				cursor = page.cursor;
-			} while (cursor);
+			const readConcurrency = getRevokeExistingGrantsBatchSize(options.revokeExistingGrantsBatchSize);
+			grantsToRevoke = await this.findGrantIds(options.userId, (grant) => grant.clientId === clientId && (!isCimdClient || grant.redirectUri === options.request.redirectUri) && this.provider.shouldReplaceGrantForResource(grant.resource, effectiveResource), readConcurrency);
 		}
 		const grantId = generateRandomString(16);
 		const { encryptedData, key: encryptionKey } = await encryptProps(options.props);
@@ -3596,8 +4648,7 @@ 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(effectiveResource);
-			if (effectiveResource && !audience) throw new Error("The resource parameter must be a valid absolute URI without a fragment");
+			const audience = effectiveResource;
 			const grant = {
 				id: grantId,
 				clientId: options.request.clientId,
@@ -3610,7 +4661,7 @@ var OAuthHelpersImpl = class {
 				redirectUri: options.request.redirectUri
 			};
 			const grantKey = `grant:${options.userId}:${grantId}`;
-			await this.env.OAUTH_KV.put(grantKey, JSON.stringify(grant));
+			await this.env.OAUTH_KV.put(grantKey, JSON.stringify(grant), grantPutOptions(grant));
 			const accessTokenData = {
 				id: accessTokenId,
 				grantId,
@@ -3633,6 +4684,7 @@ var OAuthHelpersImpl = class {
 			fragment.set("token_type", "bearer");
 			fragment.set("expires_in", accessTokenTTL.toString());
 			fragment.set("scope", options.scope.join(" "));
+			fragment.set("resource", effectiveResource);
 			if (options.request.state) fragment.set("state", options.request.state);
 			if (options.request.issuer) fragment.set("iss", options.request.issuer);
 			redirectUrl.hash = fragment.toString();
@@ -3661,7 +4713,7 @@ var OAuthHelpersImpl = class {
 				redirectUri: options.request.redirectUri
 			};
 			const grantKey = `grant:${options.userId}:${grantId}`;
-			await this.env.OAUTH_KV.put(grantKey, JSON.stringify(grant), { expirationTtl: 600 });
+			await this.env.OAUTH_KV.put(grantKey, JSON.stringify(grant), grantPutOptions(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);
@@ -3673,6 +4725,39 @@ var OAuthHelpersImpl = class {
 		}
 	}
 	/**
+	* IDs of the user's grants that satisfy `matches`, judged from KV key metadata
+	* wherever a grant carries it. Only grants written without metadata, by a version
+	* before 1.0 or because theirs would not fit, are read, `readConcurrency` at a time.
+	*
+	* This runs on the interactive authorization path, where the pre-metadata cost of one
+	* `get()` per grant broke re-authorization for a user with more grants than a Worker
+	* has subrequests. The cost is now one `list()` per thousand grants plus one `get()`
+	* per legacy grant, and every refresh rewrites its grant with metadata, so the legacy
+	* share shrinks on its own.
+	*/
+	async findGrantIds(userId, matches, readConcurrency) {
+		const prefix = `grant:${userId}:`;
+		const found = [];
+		let cursor;
+		do {
+			const page = await this.env.OAUTH_KV.list({
+				prefix,
+				limit: MAX_KV_LIST_LIMIT,
+				cursor
+			});
+			const toRead = [];
+			for (const key of page.keys) if (isGrantKeyMetadata(key.metadata)) {
+				if (matches(key.metadata)) found.push(key.name.slice(prefix.length));
+			} else toRead.push(key.name);
+			for (let start = 0; start < toRead.length; start += readConcurrency) {
+				const grants = await Promise.all(toRead.slice(start, start + readConcurrency).map((name) => this.env.OAUTH_KV.get(name, { type: "json" })));
+				for (const grant of grants) if (grant && matches(grant)) found.push(grant.id);
+			}
+			cursor = page.list_complete ? void 0 : page.cursor;
+		} while (cursor);
+		return found;
+	}
+	/**
 	* Creates a new OAuth client
 	* @param clientInfo - Partial client information to create the client with
 	* @returns A Promise resolving to the created client info
@@ -3764,9 +4849,7 @@ var OAuthHelpersImpl = class {
 		};
 		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);
+		await this.provider.putRegisteredClient(this.env, updatedClient, Math.floor(Date.now() / 1e3));
 		const response = toPublicClientInfo(updatedClient);
 		if (!isPublicClient && originalSecret) response.clientSecret = originalSecret;
 		return response;
@@ -3816,7 +4899,8 @@ var OAuthHelpersImpl = class {
 					metadata: grantData.metadata,
 					createdAt: grantData.createdAt,
 					expiresAt: grantData.expiresAt,
-					redirectUri: grantData.redirectUri
+					redirectUri: grantData.redirectUri,
+					resource: grantData.resource
 				};
 				grantSummaries.push(summary);
 			}
@@ -3966,4 +5050,4 @@ var OAuthHelpersImpl = class {
 var oauth_provider_default = OAuthProvider;
 
 //#endregion
-export { AuthorizationError, CimdFetchError, ExternalTokenError, GrantType, OAuthError, OAuthProvider, base64UrlToBytes, oauth_provider_default as default, getJwtCryptoAlgorithms, getOAuthApi, isValidOAuthScopeToken, parseJwtJsonPart, resourceMatches, validateResourceUri };
+export { AuthorizationError, CimdFetchError, ExternalTokenError, GrantType, OAuthAuthorizationServer, OAuthError, OAuthProvider, OAuthResourceServer, base64UrlToBytes, oauth_provider_default as default, getJwtCryptoAlgorithms, getOAuthApi, insufficientScope, isValidOAuthScopeToken, parseJwtJsonPart, resourceMatches, validateResourceUri };