@better-auth/cimd 1.7.0-beta.5 → 1.7.0-beta.7

package/dist/index.d.mts

@@ -30,6 +30,15 @@ interface CimdOptions {
    * @default ["redirect_uris", "post_logout_redirect_uris", "client_uri"]
    */
   originBoundFields?: string[];
+  /**
+   * Permit loopback `client_id` URLs (`localhost`, `127.0.0.0/8`, `::1`,
+   * `*.localhost`), including plain HTTP, so an auth server can fetch a
+   * metadata document hosted on the same machine. Off by default; enable
+   * only for local development.
+   *
+   * @default false
+   */
+  allowLoopback?: boolean;
   /**
    * Pre-fetch gate called before a metadata document is requested. Return
    * `false` to reject the `client_id` URL.
@@ -74,8 +83,9 @@ type CimdResolver = (ctx: GenericEndpointContext, clientId: string, existing: Sc
  * 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.
+ * {@link cimdClientDiscovery} (to contribute a complete discovery through
+ * `oauthProvider({ extensions: [{ clientDiscovery }] })`) or install the
+ * `cimd()` plugin.
  */
 declare function createCimdResolver(cimdOptions?: CimdOptions): CimdResolver;
 //#endregion
@@ -85,19 +95,31 @@ interface ClientIdMetadataDocumentResult {
   error?: string;
   warnings?: string[];
 }
-/** Hostnames that are considered "localhost" for development flows. */
-declare function isLocalhost(hostname: string): boolean;
+interface ClientIdUrlOptions {
+  /**
+   * Permit loopback `client_id` URLs (`localhost`, `127.0.0.0/8`, `::1`,
+   * `*.localhost`) and plain HTTP for them. Off by default.
+   */
+  allowLoopback?: 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.
+ * 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
+ * {@link validateClientIdUrl} (and a fetch-time policy) before fetching.
  */
-declare function isUrlClientId(clientId: string): boolean;
+declare function isUrlClientId(clientId: string, options?: ClientIdUrlOptions): boolean;
 /**
  * Validate a client_id URL per IETF draft §3.
- * Returns null on success, error string on failure.
+ * 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.
  */
-declare function validateClientIdUrl(url: string): string | null;
+declare function validateClientIdUrl(url: string, options?: ClientIdUrlOptions): string | null;
 /**
  * Validate a fetched Client ID Metadata Document per §4.1.
  *
@@ -118,12 +140,12 @@ declare module "@better-auth/core" {
 /**
  * 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.
+ * Users who prefer explicit composition can contribute the result through
+ * `oauthProvider({ extensions: [{ clientDiscovery }] })`; most users should
+ * install the {@link cimd} plugin instead, which contributes this discovery
+ * alongside whatever else is configured.
  */
-declare function cimdClientDiscovery(options?: CimdOptions): ClientDiscovery<Scope[]>;
+declare function cimdClientDiscovery(options?: CimdOptions): ClientDiscovery;
 /**
  * Client ID Metadata Document plugin.
  *
@@ -141,4 +163,4 @@ declare const cimd: (options?: CimdOptions) => {
   init(ctx: better_auth0.AuthContext): void;
 };
 //#endregion
-export { type CimdOptions, type ClientIdMetadataDocumentResult, cimd, cimdClientDiscovery, createCimdResolver, isLocalhost, isUrlClientId, validateCimdMetadata, validateClientIdUrl };
+export { type CimdOptions, type ClientIdMetadataDocumentResult, type ClientIdUrlOptions, cimd, cimdClientDiscovery, createCimdResolver, isUrlClientId, validateCimdMetadata, validateClientIdUrl };

package/dist/index.mjs

@@ -1,9 +1,10 @@
+import { checkOAuthClient, extendOAuthProvider, oauthToSchema } from "@better-auth/oauth-provider";
 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";
+import { isLoopbackHost, isPublicRoutableHost } from "@better-auth/core/utils/host";
 //#region src/validate-metadata-document.ts
-const DOT_SEGMENT_RE = /\/\.\.?(?:\/|$|#|\?)/;
+const DOT_SEGMENT_RE = /\/(?:\.|%2e)(?:\.|%2e)?(?:\/|$|#|\?)/i;
 const PROHIBITED_FIELDS = new Set(["client_secret", "client_secret_expires_at"]);
 const SYMMETRIC_AUTH_METHODS = new Set([
 	"client_secret_post",
@@ -12,80 +13,35 @@ const SYMMETRIC_AUTH_METHODS = new Set([
 ]);
 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.
+* Detect a URL-formatted client_id (Client ID Metadata Document pattern).
 *
-* 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.
+* 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
+* {@link validateClientIdUrl} (and a fetch-time policy) before fetching.
 */
-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;
+function isUrlClientId(clientId, options) {
+	let parsed;
 	try {
-		return isLocalhost(new URL(clientId).hostname);
+		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);
 }
 /**
 * Validate a client_id URL per IETF draft §3.
-* Returns null on success, error string on failure.
+* 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.
 */
-function validateClientIdUrl(url) {
+function validateClientIdUrl(url, options) {
 	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;
@@ -95,10 +51,14 @@ function validateClientIdUrl(url) {
 		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";
+	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. */
@@ -180,7 +140,7 @@ function validateCimdMetadata(fetchUrl, raw, originBoundFields) {
 				valid: false,
 				error: `${field} must use HTTP(S)`
 			};
-			if (!isLocalhost(parsed.hostname) && isPrivateHost(parsed.hostname)) return {
+			if (!isPublicRoutableHost(parsed.hostname)) return {
 				valid: false,
 				error: `${field} must not point to a private or reserved address`
 			};
@@ -234,7 +194,7 @@ function validateCimdMetadata(fetchUrl, raw, originBoundFields) {
 				valid: false,
 				error: `all values for ${key} must use HTTP(S)`
 			};
-			const localhostAllowed = (key === "redirect_uris" || key === "post_logout_redirect_uris") && isLocalhost(uri.hostname);
+			const localhostAllowed = (key === "redirect_uris" || key === "post_logout_redirect_uris") && isLoopbackHost(uri.hostname);
 			if (uri.origin !== clientIdOrigin && !localhostAllowed) return {
 				valid: false,
 				error: `${key} value "${val}" must have the same origin as client_id (${clientIdOrigin})`
@@ -448,7 +408,7 @@ async function refreshMetadataDocumentClient(ctx, clientIdUrl, existing, cimdOpt
 * and return the parsed metadata.
 */
 async function fetchAndValidateMetadataDocument(ctx, clientIdUrl, cimdOptions) {
-	const urlError = validateClientIdUrl(clientIdUrl);
+	const urlError = validateClientIdUrl(clientIdUrl, { allowLoopback: cimdOptions.allowLoopback });
 	if (urlError) throw new APIError("BAD_REQUEST", {
 		error: "invalid_client",
 		error_description: urlError
@@ -538,13 +498,14 @@ function isStale(existing, refreshRate) {
 * 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.
+* {@link cimdClientDiscovery} (to contribute a complete discovery through
+* `oauthProvider({ extensions: [{ clientDiscovery }] })`) or install the
+* `cimd()` plugin.
 */
 function createCimdResolver(cimdOptions = {}) {
 	const refreshRate = cimdOptions.refreshRate ?? "60m";
 	return async (ctx, clientId, existing) => {
-		if (!isUrlClientId(clientId)) return null;
+		if (!isUrlClientId(clientId, { allowLoopback: cimdOptions.allowLoopback })) 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;
@@ -555,22 +516,24 @@ function createCimdResolver(cimdOptions = {}) {
 }
 //#endregion
 //#region src/version.ts
-const PACKAGE_VERSION = "1.7.0-beta.5";
+const PACKAGE_VERSION = "1.7.0-beta.7";
 //#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.
+* Users who prefer explicit composition can contribute the result through
+* `oauthProvider({ extensions: [{ clientDiscovery }] })`; most users should
+* 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;
 	return {
 		id: "cimd",
-		matches: isUrlClientId,
-		resolve: createCimdResolver(options),
+		matches: (clientId) => isUrlClientId(clientId, { allowLoopback }),
+		resolve: resolver,
 		discoveryMetadata: { client_id_metadata_document_supported: true }
 	};
 }
@@ -591,12 +554,9 @@ const cimd = (options = {}) => {
 		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;
+			extendOAuthProvider(ctx, { clientDiscovery: discovery });
 		}
 	};
 };
 //#endregion
-export { cimd, cimdClientDiscovery, createCimdResolver, isLocalhost, isUrlClientId, validateCimdMetadata, validateClientIdUrl };
+export { cimd, cimdClientDiscovery, createCimdResolver, isUrlClientId, validateCimdMetadata, validateClientIdUrl };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/cimd",
-  "version": "1.7.0-beta.5",
+  "version": "1.7.0-beta.7",
   "description": "Client ID Metadata Document plugin for Better Auth",
   "type": "module",
   "license": "MIT",
@@ -48,15 +48,15 @@
   "devDependencies": {
     "listhen": "^1.9.0",
     "tsdown": "0.21.1",
-    "@better-auth/core": "1.7.0-beta.5",
-    "@better-auth/oauth-provider": "1.7.0-beta.5",
-    "better-auth": "1.7.0-beta.5"
+    "@better-auth/core": "1.7.0-beta.7",
+    "@better-auth/oauth-provider": "1.7.0-beta.7",
+    "better-auth": "1.7.0-beta.7"
   },
   "peerDependencies": {
     "better-call": "1.3.6",
-    "@better-auth/core": "^1.7.0-beta.5",
-    "@better-auth/oauth-provider": "^1.7.0-beta.5",
-    "better-auth": "^1.7.0-beta.5"
+    "@better-auth/core": "^1.7.0-beta.7",
+    "@better-auth/oauth-provider": "^1.7.0-beta.7",
+    "better-auth": "^1.7.0-beta.7"
   },
   "scripts": {
     "build": "tsdown",