@better-auth/core 1.6.4 → 1.6.6

package/dist/context/global.mjs

@@ -2,7 +2,7 @@
 const symbol = Symbol.for("better-auth:global");
 let bind = null;
 const __context = {};
-const __betterAuthVersion = "1.6.4";
+const __betterAuthVersion = "1.6.6";
 /**
 * We store context instance in the globalThis.
 *

package/dist/instrumentation/api.mjs

@@ -0,0 +1,42 @@
+//#region src/instrumentation/api.ts
+function createNoopSpan() {
+	return {
+		end() {},
+		setAttribute(_key, _value) {},
+		setStatus(_status) {},
+		recordException(_exception) {}
+	};
+}
+function createNoopTracer(noopSpanInstance) {
+	function startActiveSpan(_name, _options, fn) {
+		return fn(noopSpanInstance);
+	}
+	return { startActiveSpan };
+}
+function createNoopTraceAPI() {
+	const noopTracer = createNoopTracer(createNoopSpan());
+	return { getTracer(_name, _version) {
+		return noopTracer;
+	} };
+}
+function createNoopOpenTelemetryAPI() {
+	return {
+		SpanStatusCode: {
+			UNSET: 0,
+			OK: 1,
+			ERROR: 2
+		},
+		trace: createNoopTraceAPI()
+	};
+}
+const noopOpenTelemetryAPI = createNoopOpenTelemetryAPI();
+let openTelemetryAPIPromise;
+let openTelemetryAPI;
+function getOpenTelemetryAPI() {
+	if (!openTelemetryAPIPromise) openTelemetryAPIPromise = import("@opentelemetry/api").then((mod) => {
+		openTelemetryAPI = mod;
+	}).catch(() => void 0);
+	return openTelemetryAPI ?? noopOpenTelemetryAPI;
+}
+//#endregion
+export { getOpenTelemetryAPI };

package/dist/instrumentation/tracer.mjs

@@ -1,7 +1,8 @@
 import { ATTR_HTTP_RESPONSE_STATUS_CODE } from "./attributes.mjs";
-import { SpanStatusCode, trace } from "@opentelemetry/api";
+import { getOpenTelemetryAPI } from "./api.mjs";
 //#region src/instrumentation/tracer.ts
-const tracer = trace.getTracer("better-auth", "1.6.4");
+const INSTRUMENTATION_SCOPE = "better-auth";
+const INSTRUMENTATION_VERSION = "1.6.6";
 /**
 * Better-auth uses `throw ctx.redirect(url)` for flow control (e.g. OAuth
 * callbacks). These are APIErrors with 3xx status codes and should not be
@@ -15,6 +16,7 @@ function isRedirectError(err) {
 	return false;
 }
 function endSpanWithError(span, err) {
+	const { SpanStatusCode } = getOpenTelemetryAPI();
 	if (isRedirectError(err)) {
 		span.setAttribute(ATTR_HTTP_RESPONSE_STATUS_CODE, err.statusCode);
 		span.setStatus({ code: SpanStatusCode.OK });
@@ -28,7 +30,8 @@ function endSpanWithError(span, err) {
 	span.end();
 }
 function withSpan(name, attributes, fn) {
-	return tracer.startActiveSpan(name, { attributes }, (span) => {
+	const { trace } = getOpenTelemetryAPI();
+	return trace.getTracer(INSTRUMENTATION_SCOPE, INSTRUMENTATION_VERSION).startActiveSpan(name, { attributes }, (span) => {
 		try {
 			const result = fn();
 			if (result instanceof Promise) return result.then((value) => {

package/dist/utils/async.d.mts

@@ -0,0 +1,22 @@
+import { Awaitable } from "../types/helper.mjs";
+
+//#region src/utils/async.d.ts
+interface MapConcurrentOptions {
+  /**
+   * Max in-flight mappers. Non-integer values are floored, then clamped
+   * to the range `[1, items.length]`. `NaN` falls back to 1.
+   */
+  concurrency: number;
+  /**
+   * Rejects with `signal.reason` when aborted. In-flight mappers keep
+   * running but their results are not returned.
+   */
+  signal?: AbortSignal;
+}
+/**
+ * Run an async mapper over items with bounded concurrency.
+ * Preserves input order in the result. Fails fast on the first rejection.
+ */
+declare function mapConcurrent<T, R>(items: readonly T[], fn: (item: T, index: number) => Awaitable<R>, options: MapConcurrentOptions): Promise<R[]>;
+//#endregion
+export { MapConcurrentOptions, mapConcurrent };

package/dist/utils/async.mjs

@@ -0,0 +1,32 @@
+//#region src/utils/async.ts
+/**
+* Run an async mapper over items with bounded concurrency.
+* Preserves input order in the result. Fails fast on the first rejection.
+*/
+async function mapConcurrent(items, fn, options) {
+	const n = items.length;
+	if (n === 0) return [];
+	const { signal } = options;
+	if (signal?.aborted) throw signal.reason;
+	const raw = Math.floor(options.concurrency);
+	const width = Math.min(n, raw >= 1 ? raw : 1);
+	const results = new Array(n);
+	let idx = 0;
+	let failed = false;
+	const worker = async () => {
+		while (!failed && idx < n) {
+			if (signal?.aborted) throw signal.reason;
+			const i = idx++;
+			try {
+				results[i] = await fn(items[i], i);
+			} catch (error) {
+				failed = true;
+				throw error;
+			}
+		}
+	};
+	await Promise.all(Array.from({ length: width }, worker));
+	return results;
+}
+//#endregion
+export { mapConcurrent };

package/dist/utils/host.d.mts

@@ -0,0 +1,147 @@
+//#region src/utils/host.d.ts
+/**
+ * Host classification per RFC 6890 (Special-Purpose IP Address Registries),
+ * RFC 6761 (Special-Use Domain Names), and RFC 8252 §7.3 (loopback redirect URIs).
+ *
+ * This module is the single source of truth for "is this host public? private?
+ * loopback? link-local?" in the codebase. Consumers MUST prefer these predicates
+ * over bespoke regexes or substring matches; divergent checks are how bypass
+ * vulnerabilities get introduced (e.g. Oligo's "0.0.0.0 Day" 2024).
+ *
+ * Four user-facing primitives:
+ *
+ *   - `classifyHost(host)` — the workhorse. Returns a {@link HostClassification}
+ *     with `kind`, `literal`, and `canonical` fields.
+ *   - `isLoopbackIP(host)` — strict: IPv4 `127.0.0.0/8` or IPv6 `::1` only.
+ *     Use this for RFC 8252 §7.3 loopback redirect URI matching where IP
+ *     literals are REQUIRED.
+ *   - `isLoopbackHost(host)` — permissive: also accepts `localhost` and RFC 6761
+ *     `.localhost` subdomains. Use this for developer ergonomics (CORS, cookie
+ *     secure bypass, dev-mode HTTP allow-list).
+ *   - `isPublicRoutableHost(host)` — SSRF gate. Returns false for every
+ *     non-`public` kind. Use this before server-side fetches to user-controlled
+ *     URLs.
+ */
+/**
+ * The semantic kind of a host, derived from RFC 6890 special-purpose registries
+ * plus a few domain-name categories (localhost, cloud metadata FQDNs).
+ */
+type HostKind = /** IPv4 `127.0.0.0/8` or IPv6 `::1`. */"loopback" /** DNS name `localhost` or RFC 6761 `.localhost` TLD. */ | "localhost" /** IPv4 `0.0.0.0` or IPv6 `::` — "this host on this network", not loopback. */ | "unspecified" /** RFC 1918 `10/8`, `172.16/12`, `192.168/16`, or IPv6 ULA `fc00::/7`. */ | "private" /** IPv4 `169.254/16` or IPv6 `fe80::/10`. Includes AWS IMDS `169.254.169.254`. */ | "linkLocal" /** RFC 6598 carrier-grade NAT `100.64.0.0/10`. */ | "sharedAddressSpace" /** RFC 5737 `192.0.2/24`, `198.51.100/24`, `203.0.113/24`, or RFC 3849 `2001:db8::/32`. */ | "documentation" /** RFC 2544 `198.18.0.0/15`. */ | "benchmarking" /** IPv4 `224.0.0.0/4` or IPv6 `ff00::/8`. */ | "multicast" /** IPv4 limited broadcast `255.255.255.255`. */ | "broadcast" /** Other RFC 6890 special-purpose ranges (0/8, 192.0.0/24, 240/4, 2001::/32, etc.). */ | "reserved" /** Cloud metadata service FQDN (e.g. `metadata.google.internal`). */ | "cloudMetadata" /** Any host not matching a special-purpose range above. */ | "public";
+/**
+ * The syntactic form of the input host: an IPv4 literal, an IPv6 literal, or
+ * a domain name. IPv4-mapped IPv6 (`::ffff:192.0.2.1`) is reported as `ipv4`
+ * because it's unmapped during canonicalization.
+ */
+type HostLiteral = "ipv4" | "ipv6" | "fqdn";
+/**
+ * Result of {@link classifyHost}. All fields are readonly.
+ *
+ * @property kind - Semantic classification per RFC 6890 + RFC 6761.
+ * @property literal - Syntactic form of the input (IPv4, IPv6, or FQDN).
+ * @property canonical - Lowercase, port-stripped, bracket-stripped, zone-id-stripped
+ *   form suitable for equality comparison. IPv6 is expanded to full form.
+ *   IPv4-mapped IPv6 is collapsed to the underlying IPv4.
+ */
+interface HostClassification {
+  readonly kind: HostKind;
+  readonly literal: HostLiteral;
+  readonly canonical: string;
+}
+/**
+ * Classify a host string according to RFC 6890 / RFC 6761.
+ *
+ * Accepts inputs in any of these shapes and normalizes before classifying:
+ *
+ *   - Bare IPv4: `127.0.0.1`
+ *   - Bare IPv6: `::1`, `fe80::1%eth0`
+ *   - Bracketed IPv6: `[::1]`
+ *   - Host with port: `localhost:3000`, `127.0.0.1:443`, `[::1]:8080`
+ *   - FQDN: `example.com`, `tenant.localhost`
+ *   - IPv4-mapped IPv6: `::ffff:192.0.2.1` (reported as `literal: "ipv4"`)
+ *
+ * Invalid or non-resolvable FQDNs are returned as `{ kind: "public", literal: "fqdn" }`
+ * — this function never throws. Callers that need structural validation must
+ * combine this with a URL/hostname validator upstream.
+ *
+ * @example
+ * classifyHost("127.0.0.1")
+ * // { kind: "loopback", literal: "ipv4", canonical: "127.0.0.1" }
+ *
+ * @example
+ * classifyHost("[::1]:8080")
+ * // { kind: "loopback", literal: "ipv6", canonical: "0000:0000:...:0001" }
+ *
+ * @example
+ * classifyHost("::ffff:192.0.2.1")
+ * // { kind: "documentation", literal: "ipv4", canonical: "192.0.2.1" }
+ *
+ * @example
+ * classifyHost("tenant-a.localhost")
+ * // { kind: "localhost", literal: "fqdn", canonical: "tenant-a.localhost" }
+ */
+declare function classifyHost(host: string): HostClassification;
+/**
+ * Strict loopback-IP-literal check per RFC 8252 §7.3.
+ *
+ * Returns true ONLY for IPv4 `127.0.0.0/8` or IPv6 `::1`. The DNS name
+ * `localhost` returns false — RFC 8252 §8.3 explicitly recommends against
+ * relying on name resolution for loopback redirect URIs.
+ *
+ * Use this for OAuth redirect URI matching.
+ *
+ * @example
+ * isLoopbackIP("127.0.0.1")     // true
+ * isLoopbackIP("::1")           // true
+ * isLoopbackIP("[::1]:8080")    // true
+ * isLoopbackIP("localhost")     // false  (use isLoopbackHost for DNS names)
+ * isLoopbackIP("0.0.0.0")       // false  (unspecified, not loopback)
+ */
+declare function isLoopbackIP(host: string): boolean;
+/**
+ * Permissive loopback check for developer-ergonomics code paths.
+ *
+ * Returns true for IPv4 `127.0.0.0/8`, IPv6 `::1`, the literal name `localhost`,
+ * and any RFC 6761 `.localhost` subdomain (`tenant.localhost`, `app.localhost`).
+ *
+ * Use this for things like: allowing HTTP for dev servers, skipping Secure
+ * cookie requirements, browser-trust heuristics. Do NOT use this for OAuth
+ * redirect URI matching — use {@link isLoopbackIP} there.
+ *
+ * @example
+ * isLoopbackHost("localhost")         // true
+ * isLoopbackHost("tenant.localhost")  // true  (RFC 6761)
+ * isLoopbackHost("127.0.0.1")         // true
+ * isLoopbackHost("0.0.0.0")           // false (unspecified, NOT loopback)
+ */
+declare function isLoopbackHost(host: string): boolean;
+/**
+ * First-line SSRF gate: returns true ONLY for hosts that classify as `public`.
+ *
+ * Every RFC 6890 special-purpose range (loopback, private, link-local,
+ * unspecified, documentation, multicast, broadcast, reserved, shared address
+ * space, benchmarking) and cloud-metadata FQDN returns false.
+ *
+ * Use this BEFORE issuing a server-side fetch to a user-supplied URL, e.g.
+ * OAuth introspection endpoints, webhook targets, or metadata-document
+ * fetches (CIMD).
+ *
+ * Limitations (this is a syntactic check, not a complete SSRF mitigation):
+ * - No DNS resolution: a public-looking FQDN that resolves to a private IP
+ *   passes this check. Re-verify the resolved address before connecting, or
+ *   pin the socket to the resolved IP.
+ * - No DNS-rebinding defense: attackers can return a public IP on the first
+ *   lookup and a private IP on the second. Resolve once and reuse the IP.
+ * - No redirect following: HTTP 3xx responses can redirect to private hosts.
+ *   Re-run this check on every redirect target, or disable auto-follow.
+ *
+ * @example
+ * isPublicRoutableHost("example.com")            // true
+ * isPublicRoutableHost("127.0.0.1")              // false (loopback)
+ * isPublicRoutableHost("169.254.169.254")        // false (linkLocal / AWS IMDS)
+ * isPublicRoutableHost("metadata.google.internal") // false (cloudMetadata)
+ * isPublicRoutableHost("10.0.0.1")               // false (private)
+ * isPublicRoutableHost("::ffff:127.0.0.1")       // false (mapped loopback)
+ */
+declare function isPublicRoutableHost(host: string): boolean;
+//#endregion
+export { HostClassification, HostKind, HostLiteral, classifyHost, isLoopbackHost, isLoopbackIP, isPublicRoutableHost };

package/dist/utils/host.mjs

@@ -0,0 +1,291 @@
+import { isValidIP, normalizeIP } from "./ip.mjs";
+//#region src/utils/host.ts
+/**
+* Cloud provider instance metadata service FQDNs. These resolve to link-local
+* IPs (usually `169.254.169.254`) inside their respective clouds and are
+* prime SSRF targets.
+*
+* The IPs themselves are already caught by the `linkLocal` kind; this set
+* only exists for the FQDN form that a naive server-side fetch might resolve
+* via its own resolver.
+*/
+const CLOUD_METADATA_HOSTS = new Set([
+	"metadata.google.internal",
+	"metadata.goog",
+	"metadata",
+	"instance-data",
+	"instance-data.ec2.internal"
+]);
+/** Strip `[...]` if the entire input is bracketed (IPv6 literal form). */
+function stripBrackets(host) {
+	if (host.length >= 2 && host.startsWith("[") && host.endsWith("]")) return host.slice(1, -1);
+	return host;
+}
+/**
+* Strip trailing `:port` from host-with-port strings.
+*
+* - Bracketed IPv6 with port: `[::1]:8080` → `[::1]`
+* - IPv4/FQDN with port: `127.0.0.1:3000` / `example.com:443` → base form
+* - Bare IPv6: `::1` / `fe80::1` → unchanged (multiple colons means no port)
+*/
+function stripPort(host) {
+	if (host.startsWith("[")) {
+		const end = host.indexOf("]");
+		if (end === -1) return host;
+		return host.slice(0, end + 1);
+	}
+	const firstColon = host.indexOf(":");
+	if (firstColon === -1) return host;
+	if (host.indexOf(":", firstColon + 1) !== -1) return host;
+	return host.slice(0, firstColon);
+}
+/** Strip IPv6 zone identifier: `fe80::1%eth0` → `fe80::1`. */
+function stripZoneId(host) {
+	const zone = host.indexOf("%");
+	if (zone === -1) return host;
+	return host.slice(0, zone);
+}
+/**
+* Strip trailing dots (RFC 1034 absolute DNS form): `localhost.` → `localhost`.
+* Without this, `metadata.google.internal.` would fall through to `public` and
+* bypass the cloud-metadata / `.localhost` checks, since WHATWG URL parsing
+* preserves the trailing dot in `url.hostname`.
+*/
+function stripTrailingDot(host) {
+	return host.replace(/\.+$/, "");
+}
+/** Fast dotted-decimal shape check. Does NOT validate octet bounds. */
+function looksLikeIPv4(host) {
+	return /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+}
+/** Pack a validated dotted-decimal IPv4 into a 32-bit unsigned integer. */
+function ipv4ToUint32(ip) {
+	const parts = ip.split(".");
+	return (Number(parts[0]) << 24 | Number(parts[1]) << 16 | Number(parts[2]) << 8 | Number(parts[3])) >>> 0;
+}
+/** Check whether a 32-bit value matches `prefix/length` (both unsigned). */
+function inIPv4Range(value, prefix, length) {
+	if (length === 0) return true;
+	const mask = length === 32 ? 4294967295 : -1 << 32 - length >>> 0;
+	return (value & mask) === (prefix & mask);
+}
+function classifyIPv4(ip) {
+	if (ip === "0.0.0.0") return "unspecified";
+	if (ip === "255.255.255.255") return "broadcast";
+	const n = ipv4ToUint32(ip);
+	if (inIPv4Range(n, ipv4ToUint32("127.0.0.0"), 8)) return "loopback";
+	if (inIPv4Range(n, ipv4ToUint32("10.0.0.0"), 8)) return "private";
+	if (inIPv4Range(n, ipv4ToUint32("172.16.0.0"), 12)) return "private";
+	if (inIPv4Range(n, ipv4ToUint32("192.168.0.0"), 16)) return "private";
+	if (inIPv4Range(n, ipv4ToUint32("169.254.0.0"), 16)) return "linkLocal";
+	if (inIPv4Range(n, ipv4ToUint32("100.64.0.0"), 10)) return "sharedAddressSpace";
+	if (inIPv4Range(n, ipv4ToUint32("192.0.2.0"), 24)) return "documentation";
+	if (inIPv4Range(n, ipv4ToUint32("198.51.100.0"), 24)) return "documentation";
+	if (inIPv4Range(n, ipv4ToUint32("203.0.113.0"), 24)) return "documentation";
+	if (inIPv4Range(n, ipv4ToUint32("198.18.0.0"), 15)) return "benchmarking";
+	if (inIPv4Range(n, ipv4ToUint32("224.0.0.0"), 4)) return "multicast";
+	if (inIPv4Range(n, ipv4ToUint32("0.0.0.0"), 8)) return "reserved";
+	if (inIPv4Range(n, ipv4ToUint32("192.0.0.0"), 24)) return "reserved";
+	if (inIPv4Range(n, ipv4ToUint32("240.0.0.0"), 4)) return "reserved";
+	return "public";
+}
+/**
+* Extract an IPv4 address embedded in an expanded IPv6 literal.
+*
+* Used to recurse into tunnel/translation forms (6to4, NAT64, Teredo) so a
+* private destination cannot be smuggled behind a syntactically-public IPv6
+* literal. `startGroup` is the index of the first of two 16-bit groups in the
+* expanded form (`0000:0000:...`). With `xor: true`, the 32-bit value is XORed
+* with `0xffffffff` before decoding (Teredo obfuscates the client IPv4 this
+* way).
+*/
+function extractEmbeddedIPv4(expanded, startGroup, options = {}) {
+	const offset = startGroup * 5;
+	const g1 = Number.parseInt(expanded.slice(offset, offset + 4), 16);
+	const g2 = Number.parseInt(expanded.slice(offset + 5, offset + 9), 16);
+	if (!Number.isFinite(g1) || !Number.isFinite(g2)) return null;
+	let combined = (g1 << 16 | g2) >>> 0;
+	if (options.xor) combined = (combined ^ 4294967295) >>> 0;
+	return `${combined >>> 24 & 255}.${combined >>> 16 & 255}.${combined >>> 8 & 255}.${combined & 255}`;
+}
+/**
+* Classify an expanded, full-form, lowercase IPv6 address (no IPv4-mapped
+* input — those are unmapped to IPv4 before reaching here).
+*
+* 6to4 (`2002::/16`), NAT64 (`64:ff9b::/96`) and Teredo (`2001:0000::/32`)
+* embed an IPv4 that can route to private/loopback space. If the embedded
+* IPv4 classifies as non-`public`, return `reserved` — blocks SSRF without
+* advertising the address as a loopback literal for RFC 8252 §7.3 matching.
+*/
+function classifyIPv6(expanded) {
+	if (expanded === "0000:0000:0000:0000:0000:0000:0000:0000") return "unspecified";
+	if (expanded === "0000:0000:0000:0000:0000:0000:0000:0001") return "loopback";
+	const firstByte = Number.parseInt(expanded.slice(0, 2), 16);
+	const secondByte = Number.parseInt(expanded.slice(2, 4), 16);
+	if (firstByte === 255) return "multicast";
+	if (firstByte === 254 && (secondByte & 192) === 128) return "linkLocal";
+	if ((firstByte & 254) === 252) return "private";
+	if (expanded.startsWith("2001:0db8:")) return "documentation";
+	if (expanded.startsWith("2002:")) {
+		const embedded = extractEmbeddedIPv4(expanded, 1);
+		if (embedded && classifyIPv4(embedded) !== "public") return "reserved";
+		return "public";
+	}
+	if (expanded.startsWith("0064:ff9b:0000:0000:0000:0000:")) {
+		const embedded = extractEmbeddedIPv4(expanded, 6);
+		if (embedded && classifyIPv4(embedded) !== "public") return "reserved";
+		return "reserved";
+	}
+	if (expanded.startsWith("2001:0000:")) {
+		const embedded = extractEmbeddedIPv4(expanded, 6, { xor: true });
+		if (embedded && classifyIPv4(embedded) !== "public") return "reserved";
+		return "reserved";
+	}
+	if (expanded.startsWith("0100:0000:0000:0000:")) return "reserved";
+	return "public";
+}
+/**
+* Classify a host string according to RFC 6890 / RFC 6761.
+*
+* Accepts inputs in any of these shapes and normalizes before classifying:
+*
+*   - Bare IPv4: `127.0.0.1`
+*   - Bare IPv6: `::1`, `fe80::1%eth0`
+*   - Bracketed IPv6: `[::1]`
+*   - Host with port: `localhost:3000`, `127.0.0.1:443`, `[::1]:8080`
+*   - FQDN: `example.com`, `tenant.localhost`
+*   - IPv4-mapped IPv6: `::ffff:192.0.2.1` (reported as `literal: "ipv4"`)
+*
+* Invalid or non-resolvable FQDNs are returned as `{ kind: "public", literal: "fqdn" }`
+* — this function never throws. Callers that need structural validation must
+* combine this with a URL/hostname validator upstream.
+*
+* @example
+* classifyHost("127.0.0.1")
+* // { kind: "loopback", literal: "ipv4", canonical: "127.0.0.1" }
+*
+* @example
+* classifyHost("[::1]:8080")
+* // { kind: "loopback", literal: "ipv6", canonical: "0000:0000:...:0001" }
+*
+* @example
+* classifyHost("::ffff:192.0.2.1")
+* // { kind: "documentation", literal: "ipv4", canonical: "192.0.2.1" }
+*
+* @example
+* classifyHost("tenant-a.localhost")
+* // { kind: "localhost", literal: "fqdn", canonical: "tenant-a.localhost" }
+*/
+function classifyHost(host) {
+	const lowered = stripTrailingDot(stripZoneId(stripBrackets(stripPort(host.trim())))).toLowerCase();
+	if (lowered === "") return {
+		kind: "reserved",
+		literal: "fqdn",
+		canonical: ""
+	};
+	if (!isValidIP(lowered)) {
+		if (lowered === "localhost" || lowered.endsWith(".localhost")) return {
+			kind: "localhost",
+			literal: "fqdn",
+			canonical: lowered
+		};
+		if (CLOUD_METADATA_HOSTS.has(lowered)) return {
+			kind: "cloudMetadata",
+			literal: "fqdn",
+			canonical: lowered
+		};
+		return {
+			kind: "public",
+			literal: "fqdn",
+			canonical: lowered
+		};
+	}
+	if (looksLikeIPv4(lowered)) return {
+		kind: classifyIPv4(lowered),
+		literal: "ipv4",
+		canonical: lowered
+	};
+	const canonical = normalizeIP(lowered, { ipv6Subnet: 128 });
+	if (looksLikeIPv4(canonical)) return {
+		kind: classifyIPv4(canonical),
+		literal: "ipv4",
+		canonical
+	};
+	return {
+		kind: classifyIPv6(canonical),
+		literal: "ipv6",
+		canonical
+	};
+}
+/**
+* Strict loopback-IP-literal check per RFC 8252 §7.3.
+*
+* Returns true ONLY for IPv4 `127.0.0.0/8` or IPv6 `::1`. The DNS name
+* `localhost` returns false — RFC 8252 §8.3 explicitly recommends against
+* relying on name resolution for loopback redirect URIs.
+*
+* Use this for OAuth redirect URI matching.
+*
+* @example
+* isLoopbackIP("127.0.0.1")     // true
+* isLoopbackIP("::1")           // true
+* isLoopbackIP("[::1]:8080")    // true
+* isLoopbackIP("localhost")     // false  (use isLoopbackHost for DNS names)
+* isLoopbackIP("0.0.0.0")       // false  (unspecified, not loopback)
+*/
+function isLoopbackIP(host) {
+	return classifyHost(host).kind === "loopback";
+}
+/**
+* Permissive loopback check for developer-ergonomics code paths.
+*
+* Returns true for IPv4 `127.0.0.0/8`, IPv6 `::1`, the literal name `localhost`,
+* and any RFC 6761 `.localhost` subdomain (`tenant.localhost`, `app.localhost`).
+*
+* Use this for things like: allowing HTTP for dev servers, skipping Secure
+* cookie requirements, browser-trust heuristics. Do NOT use this for OAuth
+* redirect URI matching — use {@link isLoopbackIP} there.
+*
+* @example
+* isLoopbackHost("localhost")         // true
+* isLoopbackHost("tenant.localhost")  // true  (RFC 6761)
+* isLoopbackHost("127.0.0.1")         // true
+* isLoopbackHost("0.0.0.0")           // false (unspecified, NOT loopback)
+*/
+function isLoopbackHost(host) {
+	const kind = classifyHost(host).kind;
+	return kind === "loopback" || kind === "localhost";
+}
+/**
+* First-line SSRF gate: returns true ONLY for hosts that classify as `public`.
+*
+* Every RFC 6890 special-purpose range (loopback, private, link-local,
+* unspecified, documentation, multicast, broadcast, reserved, shared address
+* space, benchmarking) and cloud-metadata FQDN returns false.
+*
+* Use this BEFORE issuing a server-side fetch to a user-supplied URL, e.g.
+* OAuth introspection endpoints, webhook targets, or metadata-document
+* fetches (CIMD).
+*
+* Limitations (this is a syntactic check, not a complete SSRF mitigation):
+* - No DNS resolution: a public-looking FQDN that resolves to a private IP
+*   passes this check. Re-verify the resolved address before connecting, or
+*   pin the socket to the resolved IP.
+* - No DNS-rebinding defense: attackers can return a public IP on the first
+*   lookup and a private IP on the second. Resolve once and reuse the IP.
+* - No redirect following: HTTP 3xx responses can redirect to private hosts.
+*   Re-run this check on every redirect target, or disable auto-follow.
+*
+* @example
+* isPublicRoutableHost("example.com")            // true
+* isPublicRoutableHost("127.0.0.1")              // false (loopback)
+* isPublicRoutableHost("169.254.169.254")        // false (linkLocal / AWS IMDS)
+* isPublicRoutableHost("metadata.google.internal") // false (cloudMetadata)
+* isPublicRoutableHost("10.0.0.1")               // false (private)
+* isPublicRoutableHost("::ffff:127.0.0.1")       // false (mapped loopback)
+*/
+function isPublicRoutableHost(host) {
+	return classifyHost(host).kind === "public";
+}
+//#endregion
+export { classifyHost, isLoopbackHost, isLoopbackIP, isPublicRoutableHost };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/core",
-  "version": "1.6.4",
+  "version": "1.6.6",
   "description": "The most comprehensive authentication framework for TypeScript.",
   "type": "module",
   "license": "MIT",
@@ -170,6 +170,9 @@
   "peerDependenciesMeta": {
     "@cloudflare/workers-types": {
       "optional": true
+    },
+    "@opentelemetry/api": {
+      "optional": true
     }
   },
   "scripts": {

package/src/instrumentation/api.ts

@@ -0,0 +1,64 @@
+import type { Span, Tracer } from "@opentelemetry/api";
+
+type OpenTelemetryAPI = Pick<
+	typeof import("@opentelemetry/api"),
+	"trace" | "SpanStatusCode"
+>;
+
+function createNoopSpan(): Span {
+	return {
+		end(): void {},
+		setAttribute(_key: string, _value: unknown): void {},
+		setStatus(_status: unknown): void {},
+		recordException(_exception: unknown): void {},
+	} as Span;
+}
+
+function createNoopTracer(noopSpanInstance: Span): Tracer {
+	function startActiveSpan<F extends (span: Span) => unknown>(
+		_name: string,
+		_options: { attributes?: Record<string, string | number | boolean> },
+		fn: F,
+	): ReturnType<F> {
+		return fn(noopSpanInstance) as ReturnType<F>;
+	}
+
+	return { startActiveSpan } as Tracer;
+}
+
+function createNoopTraceAPI() {
+	const noopTracer = createNoopTracer(createNoopSpan());
+	return {
+		getTracer(_name?: string, _version?: string) {
+			return noopTracer;
+		},
+	};
+}
+
+function createNoopOpenTelemetryAPI(): OpenTelemetryAPI {
+	return {
+		SpanStatusCode: {
+			UNSET: 0,
+			OK: 1,
+			ERROR: 2,
+		},
+		trace: createNoopTraceAPI(),
+	} as OpenTelemetryAPI;
+}
+
+const noopOpenTelemetryAPI = createNoopOpenTelemetryAPI();
+
+let openTelemetryAPIPromise: Promise<void> | undefined;
+let openTelemetryAPI: OpenTelemetryAPI | undefined;
+
+export function getOpenTelemetryAPI(): OpenTelemetryAPI {
+	if (!openTelemetryAPIPromise) {
+		openTelemetryAPIPromise = import("@opentelemetry/api")
+			.then((mod) => {
+				openTelemetryAPI = mod;
+			})
+			.catch(() => /* ignore failures */ undefined);
+	}
+
+	return openTelemetryAPI ?? noopOpenTelemetryAPI;
+}

package/src/instrumentation/tracer.ts

@@ -1,12 +1,10 @@
 import type { Span } from "@opentelemetry/api";
-import { SpanStatusCode, trace } from "@opentelemetry/api";
+import { getOpenTelemetryAPI } from "./api";
 import { ATTR_HTTP_RESPONSE_STATUS_CODE } from "./attributes";
 
 const INSTRUMENTATION_SCOPE = "better-auth";
 const INSTRUMENTATION_VERSION = import.meta.env?.BETTER_AUTH_VERSION ?? "1.0.0";
 
-const tracer = trace.getTracer(INSTRUMENTATION_SCOPE, INSTRUMENTATION_VERSION);
-
 /**
  * Better-auth uses `throw ctx.redirect(url)` for flow control (e.g. OAuth
  * callbacks). These are APIErrors with 3xx status codes and should not be
@@ -27,6 +25,7 @@ function isRedirectError(err: unknown): boolean {
 }
 
 function endSpanWithError(span: Span, err: unknown) {
+	const { SpanStatusCode } = getOpenTelemetryAPI();
 	if (isRedirectError(err)) {
 		span.setAttribute(
 			ATTR_HTTP_RESPONSE_STATUS_CODE,
@@ -66,6 +65,12 @@ export function withSpan<T>(
 	attributes: Record<string, string | number | boolean>,
 	fn: () => T | Promise<T>,
 ): T | Promise<T> {
+	const { trace } = getOpenTelemetryAPI();
+	const tracer = trace.getTracer(
+		INSTRUMENTATION_SCOPE,
+		INSTRUMENTATION_VERSION,
+	);
+
 	return tracer.startActiveSpan(name, { attributes }, (span) => {
 		try {
 			const result = fn();

package/src/utils/async.ts

@@ -0,0 +1,53 @@
+import type { Awaitable } from "../types/helper";
+
+export interface MapConcurrentOptions {
+	/**
+	 * Max in-flight mappers. Non-integer values are floored, then clamped
+	 * to the range `[1, items.length]`. `NaN` falls back to 1.
+	 */
+	concurrency: number;
+	/**
+	 * Rejects with `signal.reason` when aborted. In-flight mappers keep
+	 * running but their results are not returned.
+	 */
+	signal?: AbortSignal;
+}
+
+/**
+ * Run an async mapper over items with bounded concurrency.
+ * Preserves input order in the result. Fails fast on the first rejection.
+ */
+export async function mapConcurrent<T, R>(
+	items: readonly T[],
+	fn: (item: T, index: number) => Awaitable<R>,
+	options: MapConcurrentOptions,
+): Promise<R[]> {
+	const n = items.length;
+	if (n === 0) return [];
+
+	const { signal } = options;
+	if (signal?.aborted) throw signal.reason;
+
+	const raw = Math.floor(options.concurrency);
+	const width = Math.min(n, raw >= 1 ? raw : 1);
+
+	const results = new Array<R>(n);
+	let idx = 0;
+	let failed = false;
+
+	const worker = async (): Promise<void> => {
+		while (!failed && idx < n) {
+			if (signal?.aborted) throw signal.reason;
+			const i = idx++;
+			try {
+				results[i] = await fn(items[i] as T, i);
+			} catch (error) {
+				failed = true;
+				throw error;
+			}
+		}
+	};
+
+	await Promise.all(Array.from({ length: width }, worker));
+	return results;
+}

package/src/utils/host.ts

@@ -0,0 +1,401 @@
+import { isValidIP, normalizeIP } from "./ip";
+
+/**
+ * Host classification per RFC 6890 (Special-Purpose IP Address Registries),
+ * RFC 6761 (Special-Use Domain Names), and RFC 8252 §7.3 (loopback redirect URIs).
+ *
+ * This module is the single source of truth for "is this host public? private?
+ * loopback? link-local?" in the codebase. Consumers MUST prefer these predicates
+ * over bespoke regexes or substring matches; divergent checks are how bypass
+ * vulnerabilities get introduced (e.g. Oligo's "0.0.0.0 Day" 2024).
+ *
+ * Four user-facing primitives:
+ *
+ *   - `classifyHost(host)` — the workhorse. Returns a {@link HostClassification}
+ *     with `kind`, `literal`, and `canonical` fields.
+ *   - `isLoopbackIP(host)` — strict: IPv4 `127.0.0.0/8` or IPv6 `::1` only.
+ *     Use this for RFC 8252 §7.3 loopback redirect URI matching where IP
+ *     literals are REQUIRED.
+ *   - `isLoopbackHost(host)` — permissive: also accepts `localhost` and RFC 6761
+ *     `.localhost` subdomains. Use this for developer ergonomics (CORS, cookie
+ *     secure bypass, dev-mode HTTP allow-list).
+ *   - `isPublicRoutableHost(host)` — SSRF gate. Returns false for every
+ *     non-`public` kind. Use this before server-side fetches to user-controlled
+ *     URLs.
+ */
+
+/**
+ * The semantic kind of a host, derived from RFC 6890 special-purpose registries
+ * plus a few domain-name categories (localhost, cloud metadata FQDNs).
+ */
+export type HostKind =
+	/** IPv4 `127.0.0.0/8` or IPv6 `::1`. */
+	| "loopback"
+	/** DNS name `localhost` or RFC 6761 `.localhost` TLD. */
+	| "localhost"
+	/** IPv4 `0.0.0.0` or IPv6 `::` — "this host on this network", not loopback. */
+	| "unspecified"
+	/** RFC 1918 `10/8`, `172.16/12`, `192.168/16`, or IPv6 ULA `fc00::/7`. */
+	| "private"
+	/** IPv4 `169.254/16` or IPv6 `fe80::/10`. Includes AWS IMDS `169.254.169.254`. */
+	| "linkLocal"
+	/** RFC 6598 carrier-grade NAT `100.64.0.0/10`. */
+	| "sharedAddressSpace"
+	/** RFC 5737 `192.0.2/24`, `198.51.100/24`, `203.0.113/24`, or RFC 3849 `2001:db8::/32`. */
+	| "documentation"
+	/** RFC 2544 `198.18.0.0/15`. */
+	| "benchmarking"
+	/** IPv4 `224.0.0.0/4` or IPv6 `ff00::/8`. */
+	| "multicast"
+	/** IPv4 limited broadcast `255.255.255.255`. */
+	| "broadcast"
+	/** Other RFC 6890 special-purpose ranges (0/8, 192.0.0/24, 240/4, 2001::/32, etc.). */
+	| "reserved"
+	/** Cloud metadata service FQDN (e.g. `metadata.google.internal`). */
+	| "cloudMetadata"
+	/** Any host not matching a special-purpose range above. */
+	| "public";
+
+/**
+ * The syntactic form of the input host: an IPv4 literal, an IPv6 literal, or
+ * a domain name. IPv4-mapped IPv6 (`::ffff:192.0.2.1`) is reported as `ipv4`
+ * because it's unmapped during canonicalization.
+ */
+export type HostLiteral = "ipv4" | "ipv6" | "fqdn";
+
+/**
+ * Result of {@link classifyHost}. All fields are readonly.
+ *
+ * @property kind - Semantic classification per RFC 6890 + RFC 6761.
+ * @property literal - Syntactic form of the input (IPv4, IPv6, or FQDN).
+ * @property canonical - Lowercase, port-stripped, bracket-stripped, zone-id-stripped
+ *   form suitable for equality comparison. IPv6 is expanded to full form.
+ *   IPv4-mapped IPv6 is collapsed to the underlying IPv4.
+ */
+export interface HostClassification {
+	readonly kind: HostKind;
+	readonly literal: HostLiteral;
+	readonly canonical: string;
+}
+
+/**
+ * Cloud provider instance metadata service FQDNs. These resolve to link-local
+ * IPs (usually `169.254.169.254`) inside their respective clouds and are
+ * prime SSRF targets.
+ *
+ * The IPs themselves are already caught by the `linkLocal` kind; this set
+ * only exists for the FQDN form that a naive server-side fetch might resolve
+ * via its own resolver.
+ */
+const CLOUD_METADATA_HOSTS: ReadonlySet<string> = new Set([
+	"metadata.google.internal",
+	"metadata.goog",
+	"metadata",
+	"instance-data",
+	"instance-data.ec2.internal",
+]);
+
+/** Strip `[...]` if the entire input is bracketed (IPv6 literal form). */
+function stripBrackets(host: string): string {
+	if (host.length >= 2 && host.startsWith("[") && host.endsWith("]")) {
+		return host.slice(1, -1);
+	}
+	return host;
+}
+
+/**
+ * Strip trailing `:port` from host-with-port strings.
+ *
+ * - Bracketed IPv6 with port: `[::1]:8080` → `[::1]`
+ * - IPv4/FQDN with port: `127.0.0.1:3000` / `example.com:443` → base form
+ * - Bare IPv6: `::1` / `fe80::1` → unchanged (multiple colons means no port)
+ */
+function stripPort(host: string): string {
+	if (host.startsWith("[")) {
+		const end = host.indexOf("]");
+		if (end === -1) return host;
+		return host.slice(0, end + 1);
+	}
+	const firstColon = host.indexOf(":");
+	if (firstColon === -1) return host;
+	if (host.indexOf(":", firstColon + 1) !== -1) return host;
+	return host.slice(0, firstColon);
+}
+
+/** Strip IPv6 zone identifier: `fe80::1%eth0` → `fe80::1`. */
+function stripZoneId(host: string): string {
+	const zone = host.indexOf("%");
+	if (zone === -1) return host;
+	return host.slice(0, zone);
+}
+
+/**
+ * Strip trailing dots (RFC 1034 absolute DNS form): `localhost.` → `localhost`.
+ * Without this, `metadata.google.internal.` would fall through to `public` and
+ * bypass the cloud-metadata / `.localhost` checks, since WHATWG URL parsing
+ * preserves the trailing dot in `url.hostname`.
+ */
+function stripTrailingDot(host: string): string {
+	return host.replace(/\.+$/, "");
+}
+
+/** Fast dotted-decimal shape check. Does NOT validate octet bounds. */
+function looksLikeIPv4(host: string): boolean {
+	return /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+}
+
+/** Pack a validated dotted-decimal IPv4 into a 32-bit unsigned integer. */
+function ipv4ToUint32(ip: string): number {
+	const parts = ip.split(".");
+	return (
+		((Number(parts[0]) << 24) |
+			(Number(parts[1]) << 16) |
+			(Number(parts[2]) << 8) |
+			Number(parts[3])) >>>
+		0
+	);
+}
+
+/** Check whether a 32-bit value matches `prefix/length` (both unsigned). */
+function inIPv4Range(value: number, prefix: number, length: number): boolean {
+	if (length === 0) return true;
+	const mask = length === 32 ? 0xffffffff : (~0 << (32 - length)) >>> 0;
+	return (value & mask) === (prefix & mask);
+}
+
+function classifyIPv4(ip: string): HostKind {
+	if (ip === "0.0.0.0") return "unspecified";
+	if (ip === "255.255.255.255") return "broadcast";
+
+	const n = ipv4ToUint32(ip);
+
+	if (inIPv4Range(n, ipv4ToUint32("127.0.0.0"), 8)) return "loopback";
+	if (inIPv4Range(n, ipv4ToUint32("10.0.0.0"), 8)) return "private";
+	if (inIPv4Range(n, ipv4ToUint32("172.16.0.0"), 12)) return "private";
+	if (inIPv4Range(n, ipv4ToUint32("192.168.0.0"), 16)) return "private";
+	if (inIPv4Range(n, ipv4ToUint32("169.254.0.0"), 16)) return "linkLocal";
+	if (inIPv4Range(n, ipv4ToUint32("100.64.0.0"), 10))
+		return "sharedAddressSpace";
+	if (inIPv4Range(n, ipv4ToUint32("192.0.2.0"), 24)) return "documentation";
+	if (inIPv4Range(n, ipv4ToUint32("198.51.100.0"), 24)) return "documentation";
+	if (inIPv4Range(n, ipv4ToUint32("203.0.113.0"), 24)) return "documentation";
+	if (inIPv4Range(n, ipv4ToUint32("198.18.0.0"), 15)) return "benchmarking";
+	if (inIPv4Range(n, ipv4ToUint32("224.0.0.0"), 4)) return "multicast";
+	if (inIPv4Range(n, ipv4ToUint32("0.0.0.0"), 8)) return "reserved";
+	if (inIPv4Range(n, ipv4ToUint32("192.0.0.0"), 24)) return "reserved";
+	if (inIPv4Range(n, ipv4ToUint32("240.0.0.0"), 4)) return "reserved";
+
+	return "public";
+}
+
+/**
+ * Extract an IPv4 address embedded in an expanded IPv6 literal.
+ *
+ * Used to recurse into tunnel/translation forms (6to4, NAT64, Teredo) so a
+ * private destination cannot be smuggled behind a syntactically-public IPv6
+ * literal. `startGroup` is the index of the first of two 16-bit groups in the
+ * expanded form (`0000:0000:...`). With `xor: true`, the 32-bit value is XORed
+ * with `0xffffffff` before decoding (Teredo obfuscates the client IPv4 this
+ * way).
+ */
+function extractEmbeddedIPv4(
+	expanded: string,
+	startGroup: number,
+	options: { xor?: boolean } = {},
+): string | null {
+	const offset = startGroup * 5;
+	const g1 = Number.parseInt(expanded.slice(offset, offset + 4), 16);
+	const g2 = Number.parseInt(expanded.slice(offset + 5, offset + 9), 16);
+	if (!Number.isFinite(g1) || !Number.isFinite(g2)) return null;
+	let combined = ((g1 << 16) | g2) >>> 0;
+	if (options.xor) combined = (combined ^ 0xffffffff) >>> 0;
+	return `${(combined >>> 24) & 0xff}.${(combined >>> 16) & 0xff}.${(combined >>> 8) & 0xff}.${combined & 0xff}`;
+}
+
+/**
+ * Classify an expanded, full-form, lowercase IPv6 address (no IPv4-mapped
+ * input — those are unmapped to IPv4 before reaching here).
+ *
+ * 6to4 (`2002::/16`), NAT64 (`64:ff9b::/96`) and Teredo (`2001:0000::/32`)
+ * embed an IPv4 that can route to private/loopback space. If the embedded
+ * IPv4 classifies as non-`public`, return `reserved` — blocks SSRF without
+ * advertising the address as a loopback literal for RFC 8252 §7.3 matching.
+ */
+function classifyIPv6(expanded: string): HostKind {
+	if (expanded === "0000:0000:0000:0000:0000:0000:0000:0000")
+		return "unspecified";
+	if (expanded === "0000:0000:0000:0000:0000:0000:0000:0001") return "loopback";
+
+	const firstByte = Number.parseInt(expanded.slice(0, 2), 16);
+	const secondByte = Number.parseInt(expanded.slice(2, 4), 16);
+
+	if (firstByte === 0xff) return "multicast";
+	if (firstByte === 0xfe && (secondByte & 0xc0) === 0x80) return "linkLocal";
+	if ((firstByte & 0xfe) === 0xfc) return "private";
+
+	if (expanded.startsWith("2001:0db8:")) return "documentation";
+
+	if (expanded.startsWith("2002:")) {
+		const embedded = extractEmbeddedIPv4(expanded, 1);
+		if (embedded && classifyIPv4(embedded) !== "public") return "reserved";
+		return "public";
+	}
+
+	if (expanded.startsWith("0064:ff9b:0000:0000:0000:0000:")) {
+		const embedded = extractEmbeddedIPv4(expanded, 6);
+		if (embedded && classifyIPv4(embedded) !== "public") return "reserved";
+		return "reserved";
+	}
+
+	if (expanded.startsWith("2001:0000:")) {
+		const embedded = extractEmbeddedIPv4(expanded, 6, { xor: true });
+		if (embedded && classifyIPv4(embedded) !== "public") return "reserved";
+		return "reserved";
+	}
+
+	if (expanded.startsWith("0100:0000:0000:0000:")) return "reserved";
+
+	return "public";
+}
+
+/**
+ * Classify a host string according to RFC 6890 / RFC 6761.
+ *
+ * Accepts inputs in any of these shapes and normalizes before classifying:
+ *
+ *   - Bare IPv4: `127.0.0.1`
+ *   - Bare IPv6: `::1`, `fe80::1%eth0`
+ *   - Bracketed IPv6: `[::1]`
+ *   - Host with port: `localhost:3000`, `127.0.0.1:443`, `[::1]:8080`
+ *   - FQDN: `example.com`, `tenant.localhost`
+ *   - IPv4-mapped IPv6: `::ffff:192.0.2.1` (reported as `literal: "ipv4"`)
+ *
+ * Invalid or non-resolvable FQDNs are returned as `{ kind: "public", literal: "fqdn" }`
+ * — this function never throws. Callers that need structural validation must
+ * combine this with a URL/hostname validator upstream.
+ *
+ * @example
+ * classifyHost("127.0.0.1")
+ * // { kind: "loopback", literal: "ipv4", canonical: "127.0.0.1" }
+ *
+ * @example
+ * classifyHost("[::1]:8080")
+ * // { kind: "loopback", literal: "ipv6", canonical: "0000:0000:...:0001" }
+ *
+ * @example
+ * classifyHost("::ffff:192.0.2.1")
+ * // { kind: "documentation", literal: "ipv4", canonical: "192.0.2.1" }
+ *
+ * @example
+ * classifyHost("tenant-a.localhost")
+ * // { kind: "localhost", literal: "fqdn", canonical: "tenant-a.localhost" }
+ */
+export function classifyHost(host: string): HostClassification {
+	const stripped = stripTrailingDot(
+		stripZoneId(stripBrackets(stripPort(host.trim()))),
+	);
+	const lowered = stripped.toLowerCase();
+
+	if (lowered === "") {
+		return { kind: "reserved", literal: "fqdn", canonical: "" };
+	}
+
+	if (!isValidIP(lowered)) {
+		if (lowered === "localhost" || lowered.endsWith(".localhost")) {
+			return { kind: "localhost", literal: "fqdn", canonical: lowered };
+		}
+		if (CLOUD_METADATA_HOSTS.has(lowered)) {
+			return { kind: "cloudMetadata", literal: "fqdn", canonical: lowered };
+		}
+		return { kind: "public", literal: "fqdn", canonical: lowered };
+	}
+
+	if (looksLikeIPv4(lowered)) {
+		return { kind: classifyIPv4(lowered), literal: "ipv4", canonical: lowered };
+	}
+
+	const canonical = normalizeIP(lowered, { ipv6Subnet: 128 });
+
+	if (looksLikeIPv4(canonical)) {
+		return {
+			kind: classifyIPv4(canonical),
+			literal: "ipv4",
+			canonical,
+		};
+	}
+
+	return { kind: classifyIPv6(canonical), literal: "ipv6", canonical };
+}
+
+/**
+ * Strict loopback-IP-literal check per RFC 8252 §7.3.
+ *
+ * Returns true ONLY for IPv4 `127.0.0.0/8` or IPv6 `::1`. The DNS name
+ * `localhost` returns false — RFC 8252 §8.3 explicitly recommends against
+ * relying on name resolution for loopback redirect URIs.
+ *
+ * Use this for OAuth redirect URI matching.
+ *
+ * @example
+ * isLoopbackIP("127.0.0.1")     // true
+ * isLoopbackIP("::1")           // true
+ * isLoopbackIP("[::1]:8080")    // true
+ * isLoopbackIP("localhost")     // false  (use isLoopbackHost for DNS names)
+ * isLoopbackIP("0.0.0.0")       // false  (unspecified, not loopback)
+ */
+export function isLoopbackIP(host: string): boolean {
+	return classifyHost(host).kind === "loopback";
+}
+
+/**
+ * Permissive loopback check for developer-ergonomics code paths.
+ *
+ * Returns true for IPv4 `127.0.0.0/8`, IPv6 `::1`, the literal name `localhost`,
+ * and any RFC 6761 `.localhost` subdomain (`tenant.localhost`, `app.localhost`).
+ *
+ * Use this for things like: allowing HTTP for dev servers, skipping Secure
+ * cookie requirements, browser-trust heuristics. Do NOT use this for OAuth
+ * redirect URI matching — use {@link isLoopbackIP} there.
+ *
+ * @example
+ * isLoopbackHost("localhost")         // true
+ * isLoopbackHost("tenant.localhost")  // true  (RFC 6761)
+ * isLoopbackHost("127.0.0.1")         // true
+ * isLoopbackHost("0.0.0.0")           // false (unspecified, NOT loopback)
+ */
+export function isLoopbackHost(host: string): boolean {
+	const kind = classifyHost(host).kind;
+	return kind === "loopback" || kind === "localhost";
+}
+
+/**
+ * First-line SSRF gate: returns true ONLY for hosts that classify as `public`.
+ *
+ * Every RFC 6890 special-purpose range (loopback, private, link-local,
+ * unspecified, documentation, multicast, broadcast, reserved, shared address
+ * space, benchmarking) and cloud-metadata FQDN returns false.
+ *
+ * Use this BEFORE issuing a server-side fetch to a user-supplied URL, e.g.
+ * OAuth introspection endpoints, webhook targets, or metadata-document
+ * fetches (CIMD).
+ *
+ * Limitations (this is a syntactic check, not a complete SSRF mitigation):
+ * - No DNS resolution: a public-looking FQDN that resolves to a private IP
+ *   passes this check. Re-verify the resolved address before connecting, or
+ *   pin the socket to the resolved IP.
+ * - No DNS-rebinding defense: attackers can return a public IP on the first
+ *   lookup and a private IP on the second. Resolve once and reuse the IP.
+ * - No redirect following: HTTP 3xx responses can redirect to private hosts.
+ *   Re-run this check on every redirect target, or disable auto-follow.
+ *
+ * @example
+ * isPublicRoutableHost("example.com")            // true
+ * isPublicRoutableHost("127.0.0.1")              // false (loopback)
+ * isPublicRoutableHost("169.254.169.254")        // false (linkLocal / AWS IMDS)
+ * isPublicRoutableHost("metadata.google.internal") // false (cloudMetadata)
+ * isPublicRoutableHost("10.0.0.1")               // false (private)
+ * isPublicRoutableHost("::ffff:127.0.0.1")       // false (mapped loopback)
+ */
+export function isPublicRoutableHost(host: string): boolean {
+	return classifyHost(host).kind === "public";
+}