@better-auth/cimd 1.7.0-rc.2 → 1.7.0-rc.3

package/dist/index.mjs

@@ -1,47 +1,41 @@
-import { checkOAuthClient, extendOAuthProvider, oauthToSchema } from "@better-auth/oauth-provider";
-import { BetterAuthError } from "@better-auth/core/error";
-import { toExpJWT } from "better-auth/plugins";
+import { extendOAuthProvider, oauthClientMetadataSchema } from "@better-auth/oauth-provider";
+import { isForbiddenCimdClientMetadataField, registerClientMetadataDocument, validatePublicClientJwks } from "@better-auth/oauth-provider/internal";
 import { APIError } from "better-call";
 import { isLoopbackHost, isPublicRoutableHost } from "@better-auth/core/utils/host";
+import { isReverseDomainPrivateUseRedirectUri } from "@better-auth/core/utils/redirect-uri";
+import { BetterAuthError } from "@better-auth/core/error";
+import { toExpJWT } from "better-auth/plugins";
 //#region src/validate-metadata-document.ts
 const DOT_SEGMENT_RE = /\/(?:\.|%2e)(?:\.|%2e)?(?:\/|$|#|\?)/i;
-const PROHIBITED_FIELDS = /* @__PURE__ */ new Set(["client_secret", "client_secret_expires_at"]);
 const SYMMETRIC_AUTH_METHODS = /* @__PURE__ */ new Set([
 	"client_secret_post",
 	"client_secret_basic",
 	"client_secret_jwt"
 ]);
-const ALLOWED_GRANT_TYPES = /* @__PURE__ */ new Set(["authorization_code", "refresh_token"]);
-const ALLOWED_RESPONSE_TYPES = /* @__PURE__ */ new Set(["code"]);
 /**
 * Detect a URL-formatted client_id (Client ID Metadata Document pattern).
 *
-* HTTPS URLs always match; plain HTTP matches only loopback hosts, and only
-* when `allowLoopback` is set. This is a routing predicate, not a security
-* gate: it performs no DNS resolution, so callers MUST also run
+* HTTPS URLs match. This is a routing predicate, not a security gate: it
+* performs no DNS resolution, so callers MUST also run
 * {@link validateClientIdUrl} (and a fetch-time policy) before fetching.
 */
-function isUrlClientId(clientId, options) {
+function isCimdClientIdUrlCandidate(clientId) {
 	let parsed;
 	try {
 		parsed = new URL(clientId);
 	} catch {
 		return false;
 	}
-	if (parsed.protocol === "https:") return true;
-	if (parsed.protocol !== "http:") return false;
-	if (!options?.allowLoopback) return false;
-	return isLoopbackHost(parsed.hostname);
+	return parsed.protocol === "https:";
 }
 /**
-* Validate a client_id URL per IETF draft §3.
+* Validate a client_id URL per Client ID Metadata Document draft-02 §3.
 * Returns null on success, an error string on failure.
 *
-* Loopback hosts are rejected unless `allowLoopback` is set; every other
-* non-public host (private, link-local, cloud-metadata, IPv6 tunnels) is
-* rejected.
+* Loopback and every other non-public host (private, link-local,
+* cloud-metadata, IPv6 tunnels) are rejected.
 */
-function validateClientIdUrl(url, options) {
+function validateClientIdUrl(url) {
 	if (DOT_SEGMENT_RE.test(url)) return "client_id URL MUST NOT contain dot segments";
 	if (url.includes("#")) return "client_id URL MUST NOT contain a fragment";
 	let parsed;
@@ -50,28 +44,30 @@ function validateClientIdUrl(url, options) {
 	} catch {
 		return "client_id is not a valid URL";
 	}
-	if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return "client_id URL must use HTTPS";
+	if (parsed.protocol !== "https:") return "client_id URL must use HTTPS";
+	const httpsAuthorityPrefix = /^https:\/\//i.exec(url);
+	if (!httpsAuthorityPrefix || url.includes("\\")) return "client_id URL MUST use an explicit HTTPS authority form";
+	const authorityAndSuffix = url.slice(httpsAuthorityPrefix[0].length);
+	const firstPathOrSuffixDelimiter = authorityAndSuffix.search(/[/?#]/);
+	if (firstPathOrSuffixDelimiter === 0) return "client_id URL MUST use an explicit HTTPS authority form";
+	if (firstPathOrSuffixDelimiter < 0 || authorityAndSuffix[firstPathOrSuffixDelimiter] !== "/") return "client_id URL MUST contain an explicit path component";
 	if (parsed.username || parsed.password) return "client_id URL MUST NOT contain credentials";
-	if (parsed.pathname === "/" || parsed.pathname === "") return "client_id URL MUST contain a path component";
-	if (isLoopbackHost(parsed.hostname)) {
-		if (!options?.allowLoopback) return "client_id URL must not target a loopback address (set allowLoopback to enable local development)";
-		return null;
-	}
-	if (parsed.protocol !== "https:") return "client_id URL must use HTTPS (HTTP is allowed only for loopback in development)";
 	if (!isPublicRoutableHost(parsed.hostname)) return "client_id URL must not target a private or reserved address";
 	return null;
 }
-/** Warning: §3 SHOULD NOT have a query string. */
-function checkUrlQueryWarning(url) {
+function getClientIdUrlWarnings(url) {
+	const warnings = [];
 	try {
-		if (new URL(url).search) return "client_id URL SHOULD NOT contain a query string (§3)";
+		const parsed = new URL(url);
+		if (parsed.pathname === "/") warnings.push("client_id URL path / is NOT RECOMMENDED (§3)");
+		if (parsed.search) warnings.push("client_id URL SHOULD NOT contain a query string (§3)");
 	} catch {}
-	return null;
+	return warnings;
 }
-function isAbsoluteHttpUri(uri) {
+function isAbsoluteRedirectUri(uri) {
 	try {
 		const parsed = new URL(uri);
-		return parsed.protocol === "http:" || parsed.protocol === "https:";
+		return parsed.protocol === "http:" || parsed.protocol === "https:" || isReverseDomainPrivateUseRedirectUri(parsed);
 	} catch {
 		return false;
 	}
@@ -79,30 +75,42 @@ function isAbsoluteHttpUri(uri) {
 /**
 * Validate a fetched Client ID Metadata Document per §4.1.
 *
-* @param fetchUrl - The URL the document was fetched from.
+* @param clientIdUrl - The URL the document was fetched from.
 * @param raw - The parsed JSON body of the response.
-* @param originBoundFields - Fields whose URL values must share the same origin as the `client_id` URL.
+* @param options - Generic draft-02 validation options and an optional protocol profile.
 */
-function validateCimdMetadata(fetchUrl, raw, originBoundFields) {
+function validateCimdMetadata(clientIdUrl, raw, options = {}) {
 	if (!raw || typeof raw !== "object") return {
 		valid: false,
 		error: "metadata document is not a JSON object"
 	};
-	const doc = raw;
+	for (const field of Object.keys(raw)) if (isForbiddenCimdClientMetadataField(field)) return {
+		valid: false,
+		error: `metadata document MUST NOT contain "${field}"`
+	};
+	const parsedMetadata = oauthClientMetadataSchema.strip().safeParse(raw);
+	if (!parsedMetadata.success) {
+		const issue = parsedMetadata.error.issues[0];
+		return {
+			valid: false,
+			error: `${issue?.path.join(".") || "metadata document"}: ${issue?.message ?? "invalid client metadata"}`
+		};
+	}
+	const doc = parsedMetadata.data;
 	const warnings = [];
-	if (doc.client_id !== fetchUrl) return {
+	if (doc.client_id !== clientIdUrl) return {
 		valid: false,
 		error: `client_id "${String(doc.client_id)}" does not match the metadata document URL`
 	};
-	for (const field of PROHIBITED_FIELDS) if (field in doc) return {
+	if (options.metadataProfile === "mcp-2026-07-28" && !doc.client_name?.trim()) return {
 		valid: false,
-		error: `metadata document MUST NOT contain "${field}"`
+		error: "client_name must be a non-empty string"
 	};
-	const ALLOWED_AUTH_METHODS = /* @__PURE__ */ new Set(["none", "private_key_jwt"]);
-	if (doc.token_endpoint_auth_method !== void 0 && typeof doc.token_endpoint_auth_method !== "string") return {
+	for (const field of ["backchannel_logout_uri", "backchannel_logout_session_required"]) if (doc[field] !== void 0) return {
 		valid: false,
-		error: "token_endpoint_auth_method must be a string"
+		error: `metadata document MUST NOT contain "${field}"`
 	};
+	const ALLOWED_AUTH_METHODS = /* @__PURE__ */ new Set(["none", "private_key_jwt"]);
 	if (typeof doc.token_endpoint_auth_method === "string") {
 		if (SYMMETRIC_AUTH_METHODS.has(doc.token_endpoint_auth_method)) return {
 			valid: false,
@@ -117,19 +125,42 @@ function validateCimdMetadata(fetchUrl, raw, originBoundFields) {
 			error: "private_key_jwt requires either jwks or jwks_uri in the metadata document"
 		};
 	}
-	if (!Array.isArray(doc.redirect_uris) || doc.redirect_uris.length === 0 || !doc.redirect_uris.every((uri) => typeof uri === "string" && isAbsoluteHttpUri(uri))) return {
-		valid: false,
-		error: "redirect_uris must be a non-empty array of absolute HTTP(S) URIs"
-	};
-	if (doc.grant_types !== void 0 && !(Array.isArray(doc.grant_types) && doc.grant_types.every((g) => typeof g === "string" && ALLOWED_GRANT_TYPES.has(g)))) return {
+	if (doc.jwks) {
+		if (!validatePublicClientJwks(doc.jwks).valid) return {
+			valid: false,
+			error: "jwks must contain only structurally valid public keys"
+		};
+	}
+	if (doc.jwks_uri) try {
+		const jwksUri = new URL(doc.jwks_uri);
+		if (jwksUri.username || jwksUri.password) return {
+			valid: false,
+			error: "jwks_uri must not contain credentials"
+		};
+		if (doc.jwks_uri.includes("#")) return {
+			valid: false,
+			error: "jwks_uri must not contain a fragment"
+		};
+	} catch {
+		return {
+			valid: false,
+			error: "jwks_uri must be a valid URL"
+		};
+	}
+	if (options.metadataProfile === "mcp-2026-07-28" && !doc.redirect_uris) return {
 		valid: false,
-		error: `grant_types must be a subset of [${[...ALLOWED_GRANT_TYPES].map((g) => `"${g}"`).join(", ")}]`
+		error: "redirect_uris must be a non-empty array of absolute HTTP(S) or private-use URIs"
 	};
-	if (doc.response_types !== void 0 && !(Array.isArray(doc.response_types) && doc.response_types.every((r) => typeof r === "string" && ALLOWED_RESPONSE_TYPES.has(r)))) return {
+	if (doc.redirect_uris && !doc.redirect_uris.every((uri) => isAbsoluteRedirectUri(uri))) return {
 		valid: false,
-		error: "response_types must be a subset of [\"code\"]"
+		error: "redirect_uris must be a non-empty array of absolute HTTP(S) or private-use URIs"
 	};
-	for (const field of ["client_uri", "logo_uri"]) {
+	for (const field of [
+		"client_uri",
+		"logo_uri",
+		"tos_uri",
+		"policy_uri"
+	]) {
 		if (doc[field] !== void 0 && typeof doc[field] !== "string") return {
 			valid: false,
 			error: `${field} must be a string`
@@ -140,6 +171,10 @@ function validateCimdMetadata(fetchUrl, raw, originBoundFields) {
 				valid: false,
 				error: `${field} must use HTTP(S)`
 			};
+			if (parsed.username || parsed.password) return {
+				valid: false,
+				error: `${field} must not contain credentials`
+			};
 			if (!isPublicRoutableHost(parsed.hostname)) return {
 				valid: false,
 				error: `${field} must not point to a private or reserved address`
@@ -151,14 +186,10 @@ function validateCimdMetadata(fetchUrl, raw, originBoundFields) {
 			};
 		}
 	}
-	const fieldsToCheck = originBoundFields ?? [
-		"redirect_uris",
-		"post_logout_redirect_uris",
-		"client_uri"
-	];
+	const fieldsToCheck = options.originBoundFields ?? ["post_logout_redirect_uris", "client_uri"];
 	let clientIdOrigin;
 	try {
-		clientIdOrigin = new URL(fetchUrl).origin;
+		clientIdOrigin = new URL(clientIdUrl).origin;
 	} catch {
 		return {
 			valid: false,
@@ -190,21 +221,27 @@ function validateCimdMetadata(fetchUrl, raw, originBoundFields) {
 					error: `${key} contains an invalid URL: "${val}"`
 				};
 			}
-			if (uri.protocol !== "https:" && uri.protocol !== "http:") return {
+			const isRedirectField = key === "redirect_uris" || key === "post_logout_redirect_uris";
+			const isPrivateUseRedirect = isRedirectField && isReverseDomainPrivateUseRedirectUri(uri);
+			if (uri.protocol !== "https:" && uri.protocol !== "http:" && !isPrivateUseRedirect) return {
 				valid: false,
-				error: `all values for ${key} must use HTTP(S)`
+				error: `all values for ${key} must use HTTP(S) or an authority-free private-use scheme`
 			};
-			const localhostAllowed = (key === "redirect_uris" || key === "post_logout_redirect_uris") && isLoopbackHost(uri.hostname);
+			if (isPrivateUseRedirect) continue;
+			const localhostAllowed = isRedirectField && isLoopbackHost(uri.hostname);
 			if (uri.origin !== clientIdOrigin && !localhostAllowed) return {
 				valid: false,
 				error: `${key} value "${val}" must have the same origin as client_id (${clientIdOrigin})`
 			};
 		}
 	}
-	const queryWarning = checkUrlQueryWarning(fetchUrl);
-	if (queryWarning) warnings.push(queryWarning);
+	warnings.push(...getClientIdUrlWarnings(clientIdUrl));
 	return {
 		valid: true,
+		metadata: {
+			...doc,
+			token_endpoint_auth_method: doc.token_endpoint_auth_method ?? "none"
+		},
 		...warnings.length > 0 ? { warnings } : {}
 	};
 }
@@ -212,311 +249,463 @@ function validateCimdMetadata(fetchUrl, raw, originBoundFields) {
 //#region src/client-store.ts
 const FETCH_TIMEOUT_MS = 5e3;
 const MAX_RESPONSE_BYTES = 5 * 1024;
-/**
-* Accepts `application/json` and the draft's `application/<AS-defined>+json`
-* form. Parameters (charset, etc.) are allowed after the subtype.
-*/
 const JSON_CONTENT_TYPE_RE = /^application\/(?:[-\w.]+\+)?json\s*(?:;|$)/i;
-function tooLargeError() {
+const FETCH_FAILURE_DESCRIPTION = "Failed to fetch metadata document (network error or redirect blocked)";
+const CIMD_CLIENT_DISCOVERY_ID = "cimd";
+function invalidClient$1(description) {
 	return new APIError("BAD_REQUEST", {
 		error: "invalid_client",
-		error_description: `Metadata document exceeds ${MAX_RESPONSE_BYTES / 1024}KB size limit`
+		error_description: description
 	});
 }
-/**
-* Stream a Response body into a decoded string, aborting as soon as the
-* running byte count exceeds `max`. Guarantees no more than `max + one
-* chunk` bytes ever sit in memory before the request is canceled.
-*/
-async function readBodyWithLimit(response, max) {
+function tooLargeError() {
+	return invalidClient$1(`Metadata document exceeds ${MAX_RESPONSE_BYTES / 1024}KB size limit`);
+}
+async function readBodyWithLimit(response, maximumBytes, signal) {
 	const reader = response.body?.getReader();
 	if (!reader) {
 		const text = await response.text();
-		if (new TextEncoder().encode(text).byteLength > max) throw tooLargeError();
+		if (new TextEncoder().encode(text).byteLength > maximumBytes) throw tooLargeError();
 		return text;
 	}
 	const chunks = [];
-	let total = 0;
-	while (true) {
-		const { done, value } = await reader.read();
-		if (done) break;
-		total += value.byteLength;
-		if (total > max) {
-			await reader.cancel();
-			throw tooLargeError();
+	let byteLength = 0;
+	let rejectOnAbort;
+	const aborted = new Promise((_resolve, reject) => {
+		rejectOnAbort = reject;
+	});
+	const abortRead = () => {
+		rejectOnAbort?.(/* @__PURE__ */ new Error("Metadata document body read aborted"));
+		reader.cancel().catch(() => {});
+	};
+	if (signal.aborted) abortRead();
+	else signal.addEventListener("abort", abortRead, { once: true });
+	try {
+		while (true) {
+			const { done, value } = await Promise.race([reader.read(), aborted]);
+			if (done) break;
+			byteLength += value.byteLength;
+			if (byteLength > maximumBytes) {
+				await reader.cancel();
+				throw tooLargeError();
+			}
+			chunks.push(value);
 		}
-		chunks.push(value);
+	} finally {
+		signal.removeEventListener("abort", abortRead);
+		reader.releaseLock();
 	}
-	const merged = new Uint8Array(total);
+	const body = new Uint8Array(byteLength);
 	let offset = 0;
 	for (const chunk of chunks) {
-		merged.set(chunk, offset);
+		body.set(chunk, offset);
 		offset += chunk.byteLength;
 	}
-	return new TextDecoder().decode(merged);
+	return new TextDecoder().decode(body);
 }
-/**
-* RFC 7591 / CIMD fields accepted from external metadata documents.
-*
-* Security-sensitive fields — `require_pkce`, `disabled`, `skip_consent`,
-* `enable_end_session` — are deliberately excluded. An attacker-controlled
-* document MUST NOT be able to weaken the server's PKCE policy or escalate
-* admin-only flags.
-*/
-const ALLOWED_METADATA_FIELDS = /* @__PURE__ */ new Set([
-	"client_id",
-	"redirect_uris",
-	"token_endpoint_auth_method",
-	"grant_types",
-	"response_types",
-	"client_name",
-	"client_uri",
-	"logo_uri",
-	"scope",
-	"contacts",
-	"tos_uri",
-	"policy_uri",
-	"software_id",
-	"software_version",
-	"software_statement",
-	"post_logout_redirect_uris",
-	"subject_type",
-	"type",
-	"jwks",
-	"jwks_uri"
-]);
-/**
-* Extract only recognized RFC 7591 / CIMD fields from the metadata document.
-* Prevents arbitrary attacker-controlled fields from leaking into the DB.
-*/
-function toOAuthClientBody(metadata) {
-	const filtered = {};
-	for (const key of ALLOWED_METADATA_FIELDS) if (key in metadata) filtered[key] = metadata[key];
+function readResponseCacheHeaders(headers) {
 	return {
-		...filtered,
-		token_endpoint_auth_method: filtered.token_endpoint_auth_method ?? "none"
+		cacheControl: headers.get("cache-control") ?? void 0,
+		vary: headers.get("vary") ?? void 0,
+		expires: headers.get("expires") ?? void 0,
+		date: headers.get("date") ?? void 0,
+		age: headers.get("age") ?? void 0,
+		etag: headers.get("etag") ?? void 0,
+		lastModified: headers.get("last-modified") ?? void 0
 	};
 }
 /**
-* Create a new client from a Client ID Metadata Document.
-* Called when a URL-format client_id is encountered for the first time.
+* Fetch and validate one Client ID Metadata Document.
 *
-* Writes the DB record directly rather than routing through
-* `createOAuthClientEndpoint`, because CIMD clients must use the URL
-* as their `clientId` (not a generated random ID).
+* Conditional validators are accepted only from the resolver's previously
+* validated cache entry. A 304 response therefore carries no metadata and must
+* be joined with that entry by the caller.
 */
-async function createMetadataDocumentClient(ctx, clientIdUrl, cimdOptions, oauthOptions) {
-	const metadata = await fetchAndValidateMetadataDocument(ctx, clientIdUrl, cimdOptions);
-	const oauthClient = toOAuthClientBody(metadata);
-	await checkOAuthClient(oauthClient, oauthOptions, { isRegister: true });
-	const isPrivateKeyJwt = oauthClient.token_endpoint_auth_method === "private_key_jwt";
-	const iat = Math.floor(Date.now() / 1e3);
-	const schema = oauthToSchema({
-		...oauthClient,
-		disabled: void 0,
-		skip_consent: void 0,
-		enable_end_session: void 0,
-		jwks: isPrivateKeyJwt ? oauthClient.jwks : void 0,
-		jwks_uri: isPrivateKeyJwt ? oauthClient.jwks_uri : void 0,
-		client_id: clientIdUrl,
-		client_secret: void 0,
-		client_secret_expires_at: void 0,
-		client_id_issued_at: iat,
-		public: !isPrivateKeyJwt
-	});
-	const model = oauthOptions.schema?.oauthClient?.modelName ?? "oauthClient";
-	let client;
+async function fetchClientMetadataDocument(ctx, clientIdUrl, cimdOptions, validators) {
+	const urlError = validateClientIdUrl(clientIdUrl);
+	if (urlError) throw invalidClient$1(urlError);
+	if (cimdOptions.isMetadataDocumentUrlAllowed) {
+		if (!await cimdOptions.isMetadataDocumentUrlAllowed(clientIdUrl, ctx)) throw invalidClient$1("client_id URL is not permitted by the server's fetch policy");
+	}
+	const requestHeaders = new Headers({ Accept: "application/json" });
+	if (validators?.etag) requestHeaders.set("If-None-Match", validators.etag);
+	if (validators?.lastModified) requestHeaders.set("If-Modified-Since", validators.lastModified);
+	let response;
+	const controller = new AbortController();
+	let didTimeOut = false;
+	const timeout = setTimeout(() => {
+		didTimeOut = true;
+		controller.abort();
+	}, FETCH_TIMEOUT_MS);
 	try {
-		client = await ctx.context.adapter.create({
-			model,
-			data: {
-				...schema,
-				createdAt: /* @__PURE__ */ new Date(iat * 1e3),
-				updatedAt: /* @__PURE__ */ new Date(iat * 1e3)
+		try {
+			response = await cimdOptions.fetchClientMetadataResource(clientIdUrl, {
+				headers: requestHeaders,
+				redirect: "error",
+				signal: controller.signal
+			});
+		} catch {
+			throw invalidClient$1(didTimeOut ? `Metadata document fetch timed out after ${FETCH_TIMEOUT_MS}ms` : FETCH_FAILURE_DESCRIPTION);
+		}
+		if (response.redirected) throw invalidClient$1("Metadata document fetch must not follow redirects");
+		const cacheHeaders = readResponseCacheHeaders(response.headers);
+		if (response.status === 304) {
+			if (!validators?.etag && !validators?.lastModified) throw invalidClient$1("Metadata document returned 304 without a conditional validator");
+			return {
+				status: "not-modified",
+				cacheHeaders
+			};
+		}
+		if (response.status !== 200) throw invalidClient$1(`Metadata document fetch returned HTTP ${response.status}`);
+		const contentType = response.headers.get("content-type") ?? "";
+		if (!JSON_CONTENT_TYPE_RE.test(contentType)) throw invalidClient$1(`Metadata document must be JSON (got Content-Type "${contentType || "(none)"}")`);
+		let bodyText;
+		try {
+			const contentLength = response.headers.get("content-length");
+			if (contentLength) {
+				const declaredBytes = Number.parseInt(contentLength, 10);
+				if (Number.isFinite(declaredBytes) && declaredBytes > MAX_RESPONSE_BYTES) {
+					await response.body?.cancel();
+					throw tooLargeError();
+				}
 			}
+			bodyText = await readBodyWithLimit(response, MAX_RESPONSE_BYTES, controller.signal);
+		} catch (error) {
+			if (didTimeOut) throw invalidClient$1(`Metadata document fetch timed out after ${FETCH_TIMEOUT_MS}ms`);
+			if (error instanceof APIError) throw error;
+			throw invalidClient$1(FETCH_FAILURE_DESCRIPTION);
+		}
+		let rawMetadata;
+		try {
+			rawMetadata = JSON.parse(bodyText);
+		} catch {
+			throw invalidClient$1("Metadata document is not valid JSON");
+		}
+		const validation = validateCimdMetadata(clientIdUrl, rawMetadata, {
+			originBoundFields: cimdOptions.originBoundFields,
+			metadataProfile: cimdOptions.metadataProfile
 		});
-	} catch (err) {
-		const existing = await ctx.context.adapter.findOne({
-			model,
-			where: [{
-				field: "clientId",
-				value: clientIdUrl
-			}]
-		});
-		if (existing) return existing;
-		throw err;
+		if (!validation.valid) throw invalidClient$1(validation.error);
+		for (const warning of validation.warnings ?? []) ctx.context.logger.warn(`cimd metadata document warning: ${warning}`);
+		return {
+			status: "modified",
+			metadata: validation.metadata,
+			cacheHeaders
+		};
+	} finally {
+		clearTimeout(timeout);
 	}
-	await cimdOptions.onClientCreated?.({
-		client,
-		metadata,
-		ctx
-	});
-	return client;
-}
-/**
-* Refresh an existing client by re-fetching its metadata document.
-*
-* Admin-controlled fields (`disabled`, `skip_consent`, `enable_end_session`)
-* are never overwritten from the document — they are read from `existing`
-* and preserved so admin decisions survive a refresh.
-*/
-async function refreshMetadataDocumentClient(ctx, clientIdUrl, existing, cimdOptions, oauthOptions) {
-	const metadata = await fetchAndValidateMetadataDocument(ctx, clientIdUrl, cimdOptions);
-	const oauthClient = toOAuthClientBody(metadata);
-	await checkOAuthClient(oauthClient, oauthOptions, { isRegister: true });
-	const isPrivateKeyJwt = oauthClient.token_endpoint_auth_method === "private_key_jwt";
-	const schema = oauthToSchema({
-		...oauthClient,
-		jwks: isPrivateKeyJwt ? oauthClient.jwks : void 0,
-		jwks_uri: isPrivateKeyJwt ? oauthClient.jwks_uri : void 0,
-		client_id: clientIdUrl,
-		client_secret: void 0,
-		client_secret_expires_at: void 0,
-		public: !isPrivateKeyJwt
-	});
-	const preservedAdminFields = {
-		disabled: existing.disabled,
-		skipConsent: existing.skipConsent,
-		enableEndSession: existing.enableEndSession
-	};
-	const model = oauthOptions.schema?.oauthClient?.modelName ?? "oauthClient";
-	const client = await ctx.context.adapter.update({
-		model,
-		where: [{
-			field: "clientId",
-			value: clientIdUrl
-		}],
-		update: {
-			...schema,
-			...preservedAdminFields,
-			updatedAt: /* @__PURE__ */ new Date(Math.floor(Date.now() / 1e3) * 1e3)
-		}
-	});
-	if (!client) throw new APIError("BAD_REQUEST", {
-		error: "invalid_client",
-		error_description: "client no longer exists"
-	});
-	await cimdOptions.onClientRefreshed?.({
-		client,
-		metadata,
-		ctx
-	});
-	return client;
 }
-/**
-* Fetch a Client ID Metadata Document, validate it against the spec,
-* and return the parsed metadata.
-*/
-async function fetchAndValidateMetadataDocument(ctx, clientIdUrl, cimdOptions) {
-	const urlError = validateClientIdUrl(clientIdUrl, { allowLoopback: cimdOptions.allowLoopback });
-	if (urlError) throw new APIError("BAD_REQUEST", {
-		error: "invalid_client",
-		error_description: urlError
+async function persistMetadataDocumentClient(ctx, clientIdUrl, metadata, cimdOptions, oauthOptions, existingClient) {
+	const previousClient = existingClient ? { ...existingClient } : void 0;
+	const result = await registerClientMetadataDocument(ctx, oauthOptions, {
+		clientId: clientIdUrl,
+		clientDiscoveryId: CIMD_CLIENT_DISCOVERY_ID,
+		metadata: {
+			...metadata,
+			client_id: metadata.client_id,
+			redirect_uris: metadata.redirect_uris ?? []
+		},
+		existingClient
 	});
-	if (cimdOptions.allowFetch) {
-		if (!await cimdOptions.allowFetch(clientIdUrl, ctx)) throw new APIError("BAD_REQUEST", {
-			error: "invalid_client",
-			error_description: "client_id URL is not permitted by the server's fetch policy"
+	if (result.created) try {
+		await cimdOptions.onClientCreated?.({
+			client: result.client,
+			clientMetadataDocument: metadata,
+			context: ctx
 		});
+	} catch (error) {
+		ctx.context.logger.error("cimd onClientCreated notification failed", error);
 	}
-	let response;
-	try {
-		response = await fetch(clientIdUrl, {
-			headers: { Accept: "application/json" },
-			redirect: "error",
-			signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
-		});
-	} catch (err) {
-		throw new APIError("BAD_REQUEST", {
-			error: "invalid_client",
-			error_description: err instanceof DOMException && err.name === "TimeoutError" ? `Metadata document fetch timed out after ${FETCH_TIMEOUT_MS}ms` : "Failed to fetch metadata document (network error or redirect blocked)"
+	else try {
+		if (previousClient) await cimdOptions.onClientRefreshed?.({
+			client: result.client,
+			previousClient,
+			clientMetadataDocument: metadata,
+			context: ctx
 		});
+	} catch (error) {
+		ctx.context.logger.error("cimd onClientRefreshed notification failed", error);
 	}
-	if (!response.ok) throw new APIError("BAD_REQUEST", {
+	return result.client;
+}
+//#endregion
+//#region src/resolver.ts
+const FETCH_BUDGET_WINDOW_MS = 6e4;
+const DEFAULT_METADATA_FETCH_POLICY = {
+	minimumFetchInterval: 1,
+	maximumConcurrentFetches: 16,
+	maximumConcurrentFetchesPerOrigin: 4,
+	maximumFetchesPerMinute: 120,
+	maximumFetchesPerOriginPerMinute: 30
+};
+function invalidClient(description) {
+	return new APIError("BAD_REQUEST", {
 		error: "invalid_client",
-		error_description: `Metadata document fetch returned HTTP ${response.status}`
+		error_description: description
 	});
-	const contentType = response.headers.get("content-type") ?? "";
-	if (!JSON_CONTENT_TYPE_RE.test(contentType)) throw new APIError("BAD_REQUEST", {
-		error: "invalid_client",
-		error_description: `Metadata document must be JSON (got Content-Type "${contentType || "(none)"}")`
+}
+function createMetadataFetchUnavailableError(description) {
+	return new APIError("TOO_MANY_REQUESTS", {
+		error: "temporarily_unavailable",
+		error_description: description
 	});
-	const contentLengthHeader = response.headers.get("content-length");
-	if (contentLengthHeader) {
-		const declared = Number.parseInt(contentLengthHeader, 10);
-		if (Number.isFinite(declared) && declared > MAX_RESPONSE_BYTES) {
-			await response.body?.cancel();
-			throw tooLargeError();
-		}
+}
+function parseDurationMs(value, optionName) {
+	if (typeof value === "number") {
+		if (!Number.isFinite(value) || value < 0) throw new BetterAuthError(`cimd metadataFetchPolicy.${optionName} must be a non-negative number of seconds or duration string`);
+		return value * 1e3;
 	}
-	const bodyText = await readBodyWithLimit(response, MAX_RESPONSE_BYTES);
-	let data;
 	try {
-		data = JSON.parse(bodyText);
+		const nowSeconds = Math.floor(Date.now() / 1e3);
+		const durationMs = (toExpJWT(value, nowSeconds) - nowSeconds) * 1e3;
+		if (!Number.isFinite(durationMs) || durationMs < 0) throw new Error("negative duration");
+		return durationMs;
 	} catch {
-		throw new APIError("BAD_REQUEST", {
-			error: "invalid_client",
-			error_description: "Metadata document is not valid JSON"
-		});
+		throw new BetterAuthError(`cimd metadataFetchPolicy.${optionName} must be a non-negative number of seconds or duration string`);
 	}
-	const validation = validateCimdMetadata(clientIdUrl, data, cimdOptions.originBoundFields);
-	if (!validation.valid) throw new APIError("BAD_REQUEST", {
-		error: "invalid_client",
-		error_description: validation.error ?? "Invalid metadata document"
-	});
-	return data;
 }
-//#endregion
-//#region src/resolver.ts
-function toDate(value) {
-	if (value instanceof Date) return Number.isFinite(value.getTime()) ? value : null;
-	if (typeof value === "number" && Number.isFinite(value)) {
-		const parsed = new Date(value);
-		return Number.isFinite(parsed.getTime()) ? parsed : null;
-	}
-	if (typeof value === "bigint") {
-		const parsed = new Date(Number(value));
-		return Number.isFinite(parsed.getTime()) ? parsed : null;
+function requirePositiveInteger(value, optionName) {
+	if (!Number.isInteger(value) || value < 1) throw new BetterAuthError(`cimd metadataFetchPolicy.${optionName} must be a positive integer`);
+	return value;
+}
+function resolveMetadataFetchPolicy(options) {
+	const policy = options.metadataFetchPolicy;
+	return {
+		minimumFetchIntervalMs: parseDurationMs(policy?.minimumFetchInterval ?? DEFAULT_METADATA_FETCH_POLICY.minimumFetchInterval, "minimumFetchInterval"),
+		maximumConcurrentFetches: requirePositiveInteger(policy?.maximumConcurrentFetches ?? DEFAULT_METADATA_FETCH_POLICY.maximumConcurrentFetches, "maximumConcurrentFetches"),
+		maximumConcurrentFetchesPerOrigin: requirePositiveInteger(policy?.maximumConcurrentFetchesPerOrigin ?? DEFAULT_METADATA_FETCH_POLICY.maximumConcurrentFetchesPerOrigin, "maximumConcurrentFetchesPerOrigin"),
+		maximumFetchesPerMinute: requirePositiveInteger(policy?.maximumFetchesPerMinute ?? DEFAULT_METADATA_FETCH_POLICY.maximumFetchesPerMinute, "maximumFetchesPerMinute"),
+		maximumFetchesPerOriginPerMinute: requirePositiveInteger(policy?.maximumFetchesPerOriginPerMinute ?? DEFAULT_METADATA_FETCH_POLICY.maximumFetchesPerOriginPerMinute, "maximumFetchesPerOriginPerMinute")
+	};
+}
+function pruneFetchStartTimesMs(fetchStartTimesMs, nowMs) {
+	const windowStart = nowMs - FETCH_BUDGET_WINDOW_MS;
+	let firstRetainedIndex = 0;
+	while (firstRetainedIndex < fetchStartTimesMs.length && fetchStartTimesMs[firstRetainedIndex] <= windowStart) firstRetainedIndex += 1;
+	if (firstRetainedIndex > 0) fetchStartTimesMs.splice(0, firstRetainedIndex);
+}
+function resolveMetadataRevalidationIntervalMs(metadataRevalidationInterval, nowMs) {
+	if (typeof metadataRevalidationInterval === "number") return Math.max(0, metadataRevalidationInterval * 1e3);
+	const nowSeconds = Math.floor(nowMs / 1e3);
+	return Math.max(0, (toExpJWT(metadataRevalidationInterval, nowSeconds) - nowSeconds) * 1e3);
+}
+function parseCacheControl(value) {
+	const directives = /* @__PURE__ */ new Map();
+	const duplicates = /* @__PURE__ */ new Set();
+	for (const rawDirective of value?.split(",") ?? []) {
+		const [rawName, ...rawValue] = rawDirective.trim().split("=");
+		const name = rawName?.toLowerCase();
+		if (!name) continue;
+		if (directives.has(name)) duplicates.add(name);
+		const joinedValue = rawValue.join("=").trim();
+		directives.set(name, joinedValue ? joinedValue.replace(/^"|"$/g, "") : true);
 	}
-	if (typeof value === "string") {
-		const asNumber = Number(value);
-		if (Number.isFinite(asNumber)) {
-			const parsed = new Date(asNumber);
-			return Number.isFinite(parsed.getTime()) ? parsed : null;
-		}
-		const parsed = new Date(value);
-		return Number.isFinite(parsed.getTime()) ? parsed : null;
+	return {
+		directives,
+		duplicates
+	};
+}
+function parseNonNegativeSeconds(value) {
+	if (typeof value !== "string" || !/^\d+$/.test(value)) return null;
+	const seconds = Number(value);
+	return Number.isSafeInteger(seconds) ? seconds : null;
+}
+function computeExpiresAt(cacheHeaders, metadataRevalidationInterval, nowMs) {
+	const { directives, duplicates } = parseCacheControl(cacheHeaders.cacheControl);
+	const variesByEverything = cacheHeaders.vary?.split(",").some((field) => field.trim() === "*");
+	if (directives.has("no-store") || directives.has("private") || variesByEverything) return {
+		cacheable: false,
+		expiresAt: nowMs
+	};
+	const operatorLifetime = resolveMetadataRevalidationIntervalMs(metadataRevalidationInterval, nowMs);
+	if (directives.has("no-cache")) return {
+		cacheable: true,
+		expiresAt: nowMs
+	};
+	const ageSeconds = parseNonNegativeSeconds(cacheHeaders.age) ?? 0;
+	const responseDate = cacheHeaders.date ? Date.parse(cacheHeaders.date) : nowMs;
+	const apparentAge = Number.isFinite(responseDate) ? Math.max(0, nowMs - responseDate) : 0;
+	const currentAge = Math.max(apparentAge, ageSeconds * 1e3);
+	let originLifetime = null;
+	const hasSharedMaxAge = directives.has("s-maxage");
+	const sharedMaxAge = parseNonNegativeSeconds(directives.get("s-maxage"));
+	const hasMaxAge = directives.has("max-age");
+	const privateMaxAge = parseNonNegativeSeconds(directives.get("max-age"));
+	const applicableFreshnessIsInvalid = hasSharedMaxAge ? sharedMaxAge === null || duplicates.has("s-maxage") : hasMaxAge && (privateMaxAge === null || duplicates.has("max-age"));
+	const maxAge = hasSharedMaxAge ? sharedMaxAge : privateMaxAge;
+	if (applicableFreshnessIsInvalid) originLifetime = 0;
+	else if (maxAge !== null) originLifetime = Math.max(0, maxAge * 1e3 - currentAge);
+	else if (cacheHeaders.expires) {
+		const expires = Date.parse(cacheHeaders.expires);
+		if (Number.isFinite(expires)) originLifetime = Math.max(0, expires - (Number.isFinite(responseDate) ? responseDate : nowMs) - currentAge);
 	}
-	return null;
+	return {
+		cacheable: true,
+		expiresAt: nowMs + Math.min(operatorLifetime, originLifetime ?? operatorLifetime)
+	};
+}
+function mergeCacheHeaders(previous, revalidated) {
+	return {
+		cacheControl: revalidated.cacheControl ?? previous.cacheControl,
+		vary: revalidated.vary ?? previous.vary,
+		expires: revalidated.expires ?? previous.expires,
+		date: revalidated.date ?? previous.date,
+		age: revalidated.age ?? previous.age,
+		etag: revalidated.etag ?? previous.etag,
+		lastModified: revalidated.lastModified ?? previous.lastModified
+	};
 }
-function isStale(existing, refreshRate) {
-	const updatedAt = toDate(existing.updatedAt) ?? toDate(existing.createdAt) ?? /* @__PURE__ */ new Date(0);
-	const updatedSec = Math.floor(updatedAt.getTime() / 1e3);
-	return (typeof refreshRate === "number" ? updatedSec + refreshRate : toExpJWT(refreshRate, updatedSec)) < Math.floor(Date.now() / 1e3);
+function createCacheEntry(metadata, cacheHeaders, metadataRevalidationInterval, nowMs) {
+	const freshness = computeExpiresAt(cacheHeaders, metadataRevalidationInterval, nowMs);
+	if (!freshness.cacheable) return null;
+	return {
+		metadata,
+		expiresAt: freshness.expiresAt,
+		etag: cacheHeaders.etag,
+		lastModified: cacheHeaders.lastModified,
+		responseCacheHeaders: cacheHeaders
+	};
 }
 /**
-* Build the `resolve` function for a CIMD {@link ClientDiscovery}.
+* Build the resolver for one plugin-owned CIMD metadata cache.
 *
-* Exposed for advanced composition. Most users should call
-* {@link cimdClientDiscovery} (to contribute a complete discovery through
-* `oauthProvider({ extensions: [{ clientDiscovery }] })`) or install the
-* `cimd()` plugin.
+* The cache lives in this closure, so separate `cimd()` plugin instances never
+* share trust state or conditional validators.
 */
-function createCimdResolver(cimdOptions = {}) {
-	const refreshRate = cimdOptions.refreshRate ?? "60m";
-	return async (ctx, clientId, existing) => {
-		if (!isUrlClientId(clientId, { allowLoopback: cimdOptions.allowLoopback })) return null;
+function createCimdResolver(cimdOptions) {
+	const metadataRevalidationInterval = cimdOptions.metadataRevalidationInterval ?? "60m";
+	const maxCacheEntries = cimdOptions.maxCacheEntries ?? 1e3;
+	if (!Number.isInteger(maxCacheEntries) || maxCacheEntries < 1) throw new BetterAuthError("cimd maxCacheEntries must be a positive integer");
+	const fetchPolicy = resolveMetadataFetchPolicy(cimdOptions);
+	const metadataCache = /* @__PURE__ */ new Map();
+	const inFlightResolutionByClientId = /* @__PURE__ */ new Map();
+	const lastFetchStartAtMsByClientId = /* @__PURE__ */ new Map();
+	const fetchStateByOrigin = /* @__PURE__ */ new Map();
+	const globalFetchStartTimesMs = [];
+	let activeFetchCount = 0;
+	const readCacheEntry = (clientId) => {
+		const entry = metadataCache.get(clientId);
+		if (!entry) return void 0;
+		metadataCache.delete(clientId);
+		metadataCache.set(clientId, entry);
+		return entry;
+	};
+	const storeCacheEntry = (clientId, entry) => {
+		metadataCache.delete(clientId);
+		while (metadataCache.size >= maxCacheEntries) {
+			const leastRecentlyUsedClientId = metadataCache.keys().next().value;
+			if (typeof leastRecentlyUsedClientId !== "string") break;
+			metadataCache.delete(leastRecentlyUsedClientId);
+		}
+		metadataCache.set(clientId, entry);
+	};
+	const ensureClientFetchStateCapacity = (clientId, nowMs) => {
+		if (lastFetchStartAtMsByClientId.has(clientId)) return;
+		while (lastFetchStartAtMsByClientId.size >= maxCacheEntries) {
+			let evicted = false;
+			for (const [candidateClientId, candidateLastFetchStartAtMs] of lastFetchStartAtMsByClientId) {
+				if (fetchPolicy.minimumFetchIntervalMs > 0 && nowMs - candidateLastFetchStartAtMs < fetchPolicy.minimumFetchIntervalMs) continue;
+				lastFetchStartAtMsByClientId.delete(candidateClientId);
+				evicted = true;
+				break;
+			}
+			if (evicted) continue;
+			throw createMetadataFetchUnavailableError("metadata fetch client state is at capacity");
+		}
+	};
+	const readOrCreateOriginFetchState = (origin, nowMs) => {
+		const existingState = fetchStateByOrigin.get(origin);
+		if (existingState) {
+			pruneFetchStartTimesMs(existingState.fetchStartTimesMs, nowMs);
+			fetchStateByOrigin.delete(origin);
+			fetchStateByOrigin.set(origin, existingState);
+			return existingState;
+		}
+		while (fetchStateByOrigin.size >= maxCacheEntries) {
+			let evicted = false;
+			for (const [candidateOrigin, candidateState] of fetchStateByOrigin) {
+				pruneFetchStartTimesMs(candidateState.fetchStartTimesMs, nowMs);
+				if (candidateState.activeFetchCount > 0 || candidateState.fetchStartTimesMs.length > 0) continue;
+				fetchStateByOrigin.delete(candidateOrigin);
+				evicted = true;
+				break;
+			}
+			if (evicted) continue;
+			throw createMetadataFetchUnavailableError("metadata fetch origin state is at capacity");
+		}
+		const createdState = {
+			activeFetchCount: 0,
+			fetchStartTimesMs: []
+		};
+		fetchStateByOrigin.set(origin, createdState);
+		return createdState;
+	};
+	const acquireMetadataFetchPermit = (clientId) => {
+		const nowMs = Date.now();
+		const lastFetchStartAtMs = lastFetchStartAtMsByClientId.get(clientId);
+		if (fetchPolicy.minimumFetchIntervalMs > 0 && lastFetchStartAtMs !== void 0 && nowMs - lastFetchStartAtMs < fetchPolicy.minimumFetchIntervalMs) throw createMetadataFetchUnavailableError("metadata document fetch is within the per-client minimum interval");
+		ensureClientFetchStateCapacity(clientId, nowMs);
+		const origin = new URL(clientId).origin;
+		const originState = readOrCreateOriginFetchState(origin, nowMs);
+		pruneFetchStartTimesMs(globalFetchStartTimesMs, nowMs);
+		if (activeFetchCount >= fetchPolicy.maximumConcurrentFetches) throw createMetadataFetchUnavailableError("global metadata fetch concurrency limit exceeded");
+		if (originState.activeFetchCount >= fetchPolicy.maximumConcurrentFetchesPerOrigin) throw createMetadataFetchUnavailableError("metadata fetch concurrency limit exceeded for client origin");
+		if (globalFetchStartTimesMs.length >= fetchPolicy.maximumFetchesPerMinute) throw createMetadataFetchUnavailableError("global metadata fetch rate limit exceeded");
+		if (originState.fetchStartTimesMs.length >= fetchPolicy.maximumFetchesPerOriginPerMinute) throw createMetadataFetchUnavailableError("metadata fetch rate limit exceeded for client origin");
+		lastFetchStartAtMsByClientId.delete(clientId);
+		lastFetchStartAtMsByClientId.set(clientId, nowMs);
+		globalFetchStartTimesMs.push(nowMs);
+		originState.fetchStartTimesMs.push(nowMs);
+		activeFetchCount += 1;
+		originState.activeFetchCount += 1;
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			activeFetchCount -= 1;
+			originState.activeFetchCount -= 1;
+		};
+	};
+	return async (ctx, clientId, existingClient) => {
+		if (!isCimdClientIdUrlCandidate(clientId)) return null;
 		const provider = ctx.context.getPlugin("oauth-provider");
 		if (!provider) throw new BetterAuthError("cimd discovery invoked without the oauth-provider plugin installed");
 		const oauthOptions = provider.options;
-		if (!existing) return await createMetadataDocumentClient(ctx, clientId, cimdOptions, oauthOptions);
-		if (isStale(existing, refreshRate)) return await refreshMetadataDocumentClient(ctx, clientId, existing, cimdOptions, oauthOptions);
-		return existing;
+		const cachedEntry = readCacheEntry(clientId);
+		const nowMs = Date.now();
+		if (cachedEntry && cachedEntry.expiresAt > nowMs) {
+			if (existingClient) return existingClient;
+			return persistMetadataDocumentClient(ctx, clientId, cachedEntry.metadata, cimdOptions, oauthOptions);
+		}
+		const inFlightResolution = inFlightResolutionByClientId.get(clientId);
+		if (inFlightResolution) return inFlightResolution;
+		const releaseMetadataFetchPermit = acquireMetadataFetchPermit(clientId);
+		const resolution = (async () => {
+			const fetched = await fetchClientMetadataDocument(ctx, clientId, cimdOptions, cachedEntry ? {
+				etag: cachedEntry.etag,
+				lastModified: cachedEntry.lastModified
+			} : void 0);
+			if (fetched.status === "not-modified" && !cachedEntry) throw invalidClient("Metadata document returned 304 without a validated cached document");
+			const metadata = fetched.status === "modified" ? fetched.metadata : cachedEntry.metadata;
+			const storedClient = await persistMetadataDocumentClient(ctx, clientId, metadata, cimdOptions, oauthOptions, existingClient ?? void 0);
+			const nextEntry = createCacheEntry(metadata, fetched.status === "modified" ? fetched.cacheHeaders : mergeCacheHeaders(cachedEntry.responseCacheHeaders, fetched.cacheHeaders), metadataRevalidationInterval, Date.now());
+			if (nextEntry) storeCacheEntry(clientId, nextEntry);
+			else metadataCache.delete(clientId);
+			return storedClient;
+		})();
+		inFlightResolutionByClientId.set(clientId, resolution);
+		try {
+			return await resolution;
+		} finally {
+			if (inFlightResolutionByClientId.get(clientId) === resolution) inFlightResolutionByClientId.delete(clientId);
+			releaseMetadataFetchPermit();
+		}
 	};
 }
 //#endregion
 //#region src/version.ts
-const PACKAGE_VERSION = "1.7.0-rc.2";
+const PACKAGE_VERSION = "1.7.0-rc.3";
 //#endregion
 //#region src/index.ts
 /**
@@ -527,13 +716,12 @@ const PACKAGE_VERSION = "1.7.0-rc.2";
 * install the {@link cimd} plugin instead, which contributes this discovery
 * alongside whatever else is configured.
 */
-function cimdClientDiscovery(options = {}) {
-	const resolver = createCimdResolver(options);
-	const allowLoopback = options.allowLoopback ?? false;
+function createCimdClientDiscovery(options) {
 	return {
-		id: "cimd",
-		matches: (clientId) => isUrlClientId(clientId, { allowLoopback }),
-		resolve: resolver,
+		id: CIMD_CLIENT_DISCOVERY_ID,
+		matches: isCimdClientIdUrlCandidate,
+		resolve: createCimdResolver(options),
+		fetchClientMetadataResource: options.fetchClientMetadataResource,
 		discoveryMetadata: { client_id_metadata_document_supported: true }
 	};
 }
@@ -543,13 +731,14 @@ function cimdClientDiscovery(options = {}) {
 * Adds unauthenticated dynamic client discovery over HTTPS to an
 * `oauth-provider` instance. Clients identify themselves by providing
 * an HTTPS URL as their `client_id`; the plugin fetches and validates
-* the document at that URL, then creates a public client record.
+* the document at that URL, then creates a client record whose authentication
+* behavior is determined by `token_endpoint_auth_method`.
 *
-* See {@link https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/ | the IETF draft}
-* and {@link https://modelcontextprotocol.io/specification/draft/basic/authorization#client-id-metadata-documents-flow | the MCP authorization spec}.
+* See {@link https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-02 | Client ID Metadata Document draft-02}
+* and {@link https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/client-registration#client-id-metadata-documents | the MCP authorization spec}.
 */
-const cimd = (options = {}) => {
-	const discovery = cimdClientDiscovery(options);
+const cimd = (options) => {
+	const discovery = createCimdClientDiscovery(options);
 	return {
 		id: "cimd",
 		version: PACKAGE_VERSION,
@@ -559,4 +748,4 @@ const cimd = (options = {}) => {
 	};
 };
 //#endregion
-export { cimd, cimdClientDiscovery, createCimdResolver, isUrlClientId, validateCimdMetadata, validateClientIdUrl };
+export { cimd, createCimdClientDiscovery, isCimdClientIdUrlCandidate, validateCimdMetadata, validateClientIdUrl };