@better-auth/cimd 1.7.0-beta.0

package/LICENSE.md

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright (c) 2024 - present, Bereket Engida
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the “Software”), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# Better Auth CIMD Plugin
+
+Client ID Metadata Document plugin for [Better Auth](https://www.better-auth.com): unauthenticated dynamic client discovery over HTTPS, the mechanism [MCP](https://modelcontextprotocol.io/specification/draft/basic/authorization#client-id-metadata-documents-flow) uses for authorization servers to discover clients without prior registration.
+
+## Installation
+
+```bash
+npm install @better-auth/cimd
+```
+
+## Documentation
+
+For full documentation, visit [better-auth.com/docs/plugins/cimd](https://www.better-auth.com/docs/plugins/cimd).
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,144 @@
+import { ClientDiscovery, SchemaClient, Scope } from "@better-auth/oauth-provider";
+import * as better_auth0 from "better-auth";
+import { GenericEndpointContext } from "@better-auth/core";
+
+//#region src/types.d.ts
+/**
+ * Options for the Client ID Metadata Document plugin.
+ *
+ * @see https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/
+ */
+interface CimdOptions {
+  /**
+   * How frequently to re-fetch a client's metadata document to pick up
+   * changes from the client.
+   *
+   * Accepts a number of seconds or a duration string (e.g. `"60m"`,
+   * `"1d"`).
+   *
+   * @default "60m"
+   */
+  refreshRate?: number | string;
+  /**
+   * Metadata fields whose URL values must share the same origin as the
+   * `client_id` URL. Prevents a client from claiming URIs on a different
+   * domain.
+   *
+   * Pass an empty array to disable origin binding (not recommended for
+   * production).
+   *
+   * @default ["redirect_uris", "post_logout_redirect_uris", "client_uri"]
+   */
+  originBoundFields?: string[];
+  /**
+   * Pre-fetch gate called before a metadata document is requested. Return
+   * `false` to reject the `client_id` URL.
+   *
+   * Use this for origin allowlists, per-host rate limiting, or integrating
+   * with an external trust service. Hostname-based DNS defenses (beyond
+   * the built-in IP-literal check) belong here, since the plugin is
+   * runtime-agnostic and does not perform DNS resolution.
+   *
+   * @default always allow
+   */
+  allowFetch?: (url: string, ctx: GenericEndpointContext) => boolean | Promise<boolean>;
+  /**
+   * Called after a client is created from a metadata document for the
+   * first time. Use this to assign trust levels, prefetch logos, or
+   * perform other post-creation processing.
+   */
+  onClientCreated?: (data: {
+    client: SchemaClient<Scope[]>;
+    metadata: Record<string, unknown>;
+    ctx: GenericEndpointContext;
+  }) => void | Promise<void>;
+  /**
+   * Called after a client is refreshed from a re-fetched metadata
+   * document. Use this for change-detection logging or updating derived
+   * fields.
+   */
+  onClientRefreshed?: (data: {
+    client: SchemaClient<Scope[]>;
+    metadata: Record<string, unknown>;
+    ctx: GenericEndpointContext;
+  }) => void | Promise<void>;
+}
+//#endregion
+//#region src/resolver.d.ts
+/**
+ * Signature of the `resolve` function on a {@link ClientDiscovery}. Kept
+ * here to avoid a circular import back into `@better-auth/oauth-provider`.
+ */
+type CimdResolver = (ctx: GenericEndpointContext, clientId: string, existing: SchemaClient<Scope[]> | null) => Promise<SchemaClient<Scope[]> | null>;
+/**
+ * Build the `resolve` function for a CIMD {@link ClientDiscovery}.
+ *
+ * Exposed for advanced composition. Most users should call
+ * {@link cimdClientDiscovery} (to pass a complete discovery to
+ * `oauthProvider({ clientDiscovery })`) or install the `cimd()` plugin.
+ */
+declare function createCimdResolver(cimdOptions?: CimdOptions): CimdResolver;
+//#endregion
+//#region src/validate-metadata-document.d.ts
+interface ClientIdMetadataDocumentResult {
+  valid: boolean;
+  error?: string;
+  warnings?: string[];
+}
+/** Hostnames that are considered "localhost" for development flows. */
+declare function isLocalhost(hostname: string): boolean;
+/**
+ * Detect URL-formatted client_id (Client ID Metadata Document pattern).
+ * HTTPS always accepted; HTTP accepted for localhost variants
+ * (localhost, 127.0.0.1, [::1], *.localhost) for development.
+ */
+declare function isUrlClientId(clientId: string): boolean;
+/**
+ * Validate a client_id URL per IETF draft §3.
+ * Returns null on success, error string on failure.
+ */
+declare function validateClientIdUrl(url: string): string | null;
+/**
+ * Validate a fetched Client ID Metadata Document per §4.1.
+ *
+ * @param fetchUrl - 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.
+ */
+declare function validateCimdMetadata(fetchUrl: string, raw: unknown, originBoundFields?: string[]): ClientIdMetadataDocumentResult;
+//#endregion
+//#region src/index.d.ts
+declare module "@better-auth/core" {
+  interface BetterAuthPluginRegistry<AuthOptions, Options> {
+    cimd: {
+      creator: typeof cimd;
+    };
+  }
+}
+/**
+ * Build a {@link ClientDiscovery} for Client ID Metadata Documents.
+ *
+ * Users who prefer explicit composition can pass the result directly to
+ * `oauthProvider({ clientDiscovery })`; most users should install the
+ * {@link cimd} plugin instead, which appends this discovery to whatever
+ * is already configured.
+ */
+declare function cimdClientDiscovery(options?: CimdOptions): ClientDiscovery<Scope[]>;
+/**
+ * Client ID Metadata Document plugin.
+ *
+ * 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.
+ *
+ * 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}.
+ */
+declare const cimd: (options?: CimdOptions) => {
+  id: "cimd";
+  version: string;
+  init(ctx: better_auth0.AuthContext): void;
+};
+//#endregion
+export { type CimdOptions, type ClientIdMetadataDocumentResult, cimd, cimdClientDiscovery, createCimdResolver, isLocalhost, isUrlClientId, validateCimdMetadata, validateClientIdUrl };

package/dist/index.mjs

@@ -0,0 +1,602 @@
+import { BetterAuthError } from "@better-auth/core/error";
+import { toExpJWT } from "better-auth/plugins";
+import { checkOAuthClient, oauthToSchema } from "@better-auth/oauth-provider";
+import { APIError } from "better-call";
+//#region src/validate-metadata-document.ts
+const DOT_SEGMENT_RE = /\/\.\.?(?:\/|$|#|\?)/;
+const PROHIBITED_FIELDS = new Set(["client_secret", "client_secret_expires_at"]);
+const SYMMETRIC_AUTH_METHODS = new Set([
+	"client_secret_post",
+	"client_secret_basic",
+	"client_secret_jwt"
+]);
+const ALLOWED_GRANT_TYPES = new Set(["authorization_code", "refresh_token"]);
+const ALLOWED_RESPONSE_TYPES = new Set(["code"]);
+/** Hostnames that are considered "localhost" for development flows. */
+function isLocalhost(hostname) {
+	return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname === "::1" || hostname.endsWith(".localhost");
+}
+/**
+* Check whether a dotted-decimal IPv4 address is private, reserved, or
+* otherwise non-routable for a public SSRF target. Covers the subset of
+* RFC 6890 special-purpose ranges that an adversarial `client_id` URL
+* could point at to reach internal infrastructure or disrupt fetches.
+*/
+function isPrivateIpv4(host) {
+	const parts = host.split(".");
+	if (parts.length !== 4 || parts.some((p) => !/^\d{1,3}$/.test(p))) return false;
+	const a = Number(parts[0]);
+	const b = Number(parts[1]);
+	const c = Number(parts[2]);
+	return a === 127 || a === 10 || a === 0 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a === 169 && b === 254 || a === 100 && b >= 64 && b <= 127 || a === 198 && (b === 18 || b === 19) || a === 192 && b === 0 && c === 2 || a === 198 && b === 51 && c === 100 || a === 203 && b === 0 && c === 113 || a === 192 && b === 88 && c === 99 || a >= 224 && a <= 239 || a >= 240;
+}
+const V4_MAPPED_DOTTED_RE = /^(?:0{0,4}:){0,4}:?(?:0{0,4}:)?ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/;
+const V4_MAPPED_HEX_RE = /^(?:0{0,4}:){0,4}:?(?:0{0,4}:)?ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/;
+/**
+* Convert two hex groups from an IPv4-mapped IPv6 address to dotted-decimal IPv4.
+* e.g. "a9fe" "a9fe" -> "169.254.169.254"
+*/
+function hexGroupsToIpv4(hi, lo) {
+	const h = Number.parseInt(hi, 16);
+	const l = Number.parseInt(lo, 16);
+	return `${h >> 8 & 255}.${h & 255}.${l >> 8 & 255}.${l & 255}`;
+}
+/**
+* Check whether a hostname is private/reserved per RFC 6890.
+*
+* Handles bracketed IPv6 (as returned by URL.hostname), IPv4-mapped
+* IPv6 in both dotted-decimal and hex-normalized forms, and cloud
+* metadata hostnames. No DNS resolution, so it runs identically on
+* Node, Bun, Deno, and Workers.
+*/
+function isPrivateHost(hostname) {
+	const lower = hostname.toLowerCase();
+	const host = lower.startsWith("[") && lower.endsWith("]") ? lower.slice(1, -1) : lower;
+	if (host === "::1") return true;
+	if (isPrivateIpv4(host)) return true;
+	if (host.includes(":")) {
+		const dottedMatch = host.match(V4_MAPPED_DOTTED_RE);
+		if (dottedMatch && isPrivateIpv4(dottedMatch[1])) return true;
+		const hexMatch = host.match(V4_MAPPED_HEX_RE);
+		if (hexMatch) {
+			if (isPrivateIpv4(hexGroupsToIpv4(hexMatch[1], hexMatch[2]))) return true;
+		}
+		if (/^fe[89ab]/.test(host)) return true;
+		if (host.startsWith("fc") || host.startsWith("fd")) return true;
+	}
+	if (host === "metadata.google.internal") return true;
+	return false;
+}
+/**
+* Detect URL-formatted client_id (Client ID Metadata Document pattern).
+* HTTPS always accepted; HTTP accepted for localhost variants
+* (localhost, 127.0.0.1, [::1], *.localhost) for development.
+*/
+function isUrlClientId(clientId) {
+	if (clientId.startsWith("https://")) return true;
+	if (!clientId.startsWith("http://")) return false;
+	try {
+		return isLocalhost(new URL(clientId).hostname);
+	} catch {
+		return false;
+	}
+}
+/**
+* Validate a client_id URL per IETF draft §3.
+* Returns null on success, error string on failure.
+*/
+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;
+	try {
+		parsed = new URL(url);
+	} 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 === "http:" && !isLocalhost(parsed.hostname)) return "client_id URL must use HTTPS (HTTP allowed only for localhost)";
+	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 (!isLocalhost(parsed.hostname) && isPrivateHost(parsed.hostname)) return "client_id URL must not resolve to a private or reserved address";
+	return null;
+}
+/** Warning: §3 SHOULD NOT have a query string. */
+function checkUrlQueryWarning(url) {
+	try {
+		if (new URL(url).search) return "client_id URL SHOULD NOT contain a query string (§3)";
+	} catch {}
+	return null;
+}
+function isAbsoluteHttpUri(uri) {
+	try {
+		const parsed = new URL(uri);
+		return parsed.protocol === "http:" || parsed.protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+/**
+* Validate a fetched Client ID Metadata Document per §4.1.
+*
+* @param fetchUrl - 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.
+*/
+function validateCimdMetadata(fetchUrl, raw, originBoundFields) {
+	if (!raw || typeof raw !== "object") return {
+		valid: false,
+		error: "metadata document is not a JSON object"
+	};
+	const doc = raw;
+	const warnings = [];
+	if (doc.client_id !== fetchUrl) 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 {
+		valid: false,
+		error: `metadata document MUST NOT contain "${field}"`
+	};
+	const ALLOWED_AUTH_METHODS = new Set(["none", "private_key_jwt"]);
+	if (doc.token_endpoint_auth_method !== void 0 && typeof doc.token_endpoint_auth_method !== "string") return {
+		valid: false,
+		error: "token_endpoint_auth_method must be a string"
+	};
+	if (typeof doc.token_endpoint_auth_method === "string") {
+		if (SYMMETRIC_AUTH_METHODS.has(doc.token_endpoint_auth_method)) return {
+			valid: false,
+			error: `symmetric auth method "${doc.token_endpoint_auth_method}" is prohibited for Client ID Metadata Document clients`
+		};
+		if (!ALLOWED_AUTH_METHODS.has(doc.token_endpoint_auth_method)) return {
+			valid: false,
+			error: "token_endpoint_auth_method must be \"none\" or \"private_key_jwt\" for Client ID Metadata Document clients"
+		};
+		if (doc.token_endpoint_auth_method === "private_key_jwt" && !doc.jwks && !doc.jwks_uri) return {
+			valid: false,
+			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 {
+		valid: false,
+		error: `grant_types must be a subset of [${[...ALLOWED_GRANT_TYPES].map((g) => `"${g}"`).join(", ")}]`
+	};
+	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 {
+		valid: false,
+		error: "response_types must be a subset of [\"code\"]"
+	};
+	for (const field of ["client_uri", "logo_uri"]) {
+		if (doc[field] !== void 0 && typeof doc[field] !== "string") return {
+			valid: false,
+			error: `${field} must be a string`
+		};
+		if (typeof doc[field] === "string") try {
+			const parsed = new URL(doc[field]);
+			if (parsed.protocol !== "https:" && parsed.protocol !== "http:") return {
+				valid: false,
+				error: `${field} must use HTTP(S)`
+			};
+			if (!isLocalhost(parsed.hostname) && isPrivateHost(parsed.hostname)) return {
+				valid: false,
+				error: `${field} must not point to a private or reserved address`
+			};
+		} catch {
+			return {
+				valid: false,
+				error: `${field} is not a valid URL`
+			};
+		}
+	}
+	const fieldsToCheck = originBoundFields ?? [
+		"redirect_uris",
+		"post_logout_redirect_uris",
+		"client_uri"
+	];
+	let clientIdOrigin;
+	try {
+		clientIdOrigin = new URL(fetchUrl).origin;
+	} catch {
+		return {
+			valid: false,
+			error: "client_id is not a valid URL"
+		};
+	}
+	for (const key of fieldsToCheck) {
+		const value = doc[key];
+		if (value === void 0) continue;
+		let values;
+		if (typeof value === "string") values = [value];
+		else if (Array.isArray(value)) {
+			if (!value.every((v) => typeof v === "string")) return {
+				valid: false,
+				error: `${key} must be a string or an array of strings`
+			};
+			values = value;
+		} else return {
+			valid: false,
+			error: `${key} must be a string or an array of strings`
+		};
+		for (const val of values) {
+			let uri;
+			try {
+				uri = new URL(val);
+			} catch {
+				return {
+					valid: false,
+					error: `${key} contains an invalid URL: "${val}"`
+				};
+			}
+			if (uri.protocol !== "https:" && uri.protocol !== "http:") return {
+				valid: false,
+				error: `all values for ${key} must use HTTP(S)`
+			};
+			const localhostAllowed = (key === "redirect_uris" || key === "post_logout_redirect_uris") && isLocalhost(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);
+	return {
+		valid: true,
+		...warnings.length > 0 ? { warnings } : {}
+	};
+}
+//#endregion
+//#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() {
+	return new APIError("BAD_REQUEST", {
+		error: "invalid_client",
+		error_description: `Metadata document exceeds ${MAX_RESPONSE_BYTES / 1024}KB size limit`
+	});
+}
+/**
+* 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) {
+	const reader = response.body?.getReader();
+	if (!reader) {
+		const text = await response.text();
+		if (new TextEncoder().encode(text).byteLength > max) 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();
+		}
+		chunks.push(value);
+	}
+	const merged = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		merged.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return new TextDecoder().decode(merged);
+}
+/**
+* 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 = 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];
+	return {
+		...filtered,
+		token_endpoint_auth_method: filtered.token_endpoint_auth_method ?? "none"
+	};
+}
+/**
+* Create a new client from a Client ID Metadata Document.
+* Called when a URL-format client_id is encountered for the first time.
+*
+* 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).
+*/
+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;
+	try {
+		client = await ctx.context.adapter.create({
+			model,
+			data: {
+				...schema,
+				createdAt: /* @__PURE__ */ new Date(iat * 1e3),
+				updatedAt: /* @__PURE__ */ new Date(iat * 1e3)
+			}
+		});
+	} catch (err) {
+		const existing = await ctx.context.adapter.findOne({
+			model,
+			where: [{
+				field: "clientId",
+				value: clientIdUrl
+			}]
+		});
+		if (existing) return existing;
+		throw err;
+	}
+	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);
+	if (urlError) throw new APIError("BAD_REQUEST", {
+		error: "invalid_client",
+		error_description: urlError
+	});
+	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"
+		});
+	}
+	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)"
+		});
+	}
+	if (!response.ok) throw new APIError("BAD_REQUEST", {
+		error: "invalid_client",
+		error_description: `Metadata document fetch returned HTTP ${response.status}`
+	});
+	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)"}")`
+	});
+	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();
+		}
+	}
+	const bodyText = await readBodyWithLimit(response, MAX_RESPONSE_BYTES);
+	let data;
+	try {
+		data = JSON.parse(bodyText);
+	} catch {
+		throw new APIError("BAD_REQUEST", {
+			error: "invalid_client",
+			error_description: "Metadata document is not valid JSON"
+		});
+	}
+	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;
+	}
+	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 null;
+}
+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);
+}
+/**
+* Build the `resolve` function for a CIMD {@link ClientDiscovery}.
+*
+* Exposed for advanced composition. Most users should call
+* {@link cimdClientDiscovery} (to pass a complete discovery to
+* `oauthProvider({ clientDiscovery })`) or install the `cimd()` plugin.
+*/
+function createCimdResolver(cimdOptions = {}) {
+	const refreshRate = cimdOptions.refreshRate ?? "60m";
+	return async (ctx, clientId, existing) => {
+		if (!isUrlClientId(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;
+	};
+}
+//#endregion
+//#region src/version.ts
+const PACKAGE_VERSION = "1.7.0-beta.0";
+//#endregion
+//#region src/index.ts
+/**
+* Build a {@link ClientDiscovery} for Client ID Metadata Documents.
+*
+* Users who prefer explicit composition can pass the result directly to
+* `oauthProvider({ clientDiscovery })`; most users should install the
+* {@link cimd} plugin instead, which appends this discovery to whatever
+* is already configured.
+*/
+function cimdClientDiscovery(options = {}) {
+	return {
+		id: "cimd",
+		matches: isUrlClientId,
+		resolve: createCimdResolver(options),
+		discoveryMetadata: { client_id_metadata_document_supported: true }
+	};
+}
+/**
+* Client ID Metadata Document plugin.
+*
+* 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.
+*
+* 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}.
+*/
+const cimd = (options = {}) => {
+	const discovery = cimdClientDiscovery(options);
+	return {
+		id: "cimd",
+		version: PACKAGE_VERSION,
+		init(ctx) {
+			const provider = ctx.getPlugin("oauth-provider");
+			if (!provider) throw new BetterAuthError("The cimd plugin requires the oauth-provider plugin.");
+			const existing = provider.options.clientDiscovery;
+			provider.options.clientDiscovery = Array.isArray(existing) ? [...existing, discovery] : existing ? [existing, discovery] : discovery;
+		}
+	};
+};
+//#endregion
+export { cimd, cimdClientDiscovery, createCimdResolver, isLocalhost, isUrlClientId, validateCimdMetadata, validateClientIdUrl };

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@better-auth/cimd",
+  "version": "1.7.0-beta.0",
+  "description": "Client ID Metadata Document plugin for Better Auth",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://www.better-auth.com/docs/plugins/cimd",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/better-auth/better-auth.git",
+    "directory": "packages/cimd"
+  },
+  "keywords": [
+    "auth",
+    "cimd",
+    "client-id-metadata-document",
+    "mcp",
+    "oauth",
+    "oauth2",
+    "oidc",
+    "typescript",
+    "better-auth"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "dev-source": "./src/index.ts",
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./dist/index.d.mts"
+      ]
+    }
+  },
+  "devDependencies": {
+    "listhen": "^1.9.0",
+    "tsdown": "0.21.1",
+    "@better-auth/oauth-provider": "1.7.0-beta.1",
+    "@better-auth/core": "1.7.0-beta.1",
+    "better-auth": "1.7.0-beta.1"
+  },
+  "peerDependencies": {
+    "better-call": "1.3.5",
+    "@better-auth/oauth-provider": "^1.7.0-beta.1",
+    "@better-auth/core": "^1.7.0-beta.1",
+    "better-auth": "^1.7.0-beta.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint:package": "publint run --strict --pack false",
+    "lint:types": "attw --profile esm-only --pack .",
+    "typecheck": "tsc --project tsconfig.json",
+    "test": "vitest",
+    "coverage": "vitest run --coverage --coverage.provider=istanbul"
+  }
+}