@depup/better-auth__core 1.6.23-depup.2

package/dist/utils/host.mjs

@@ -0,0 +1,295 @@
+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("2001:0002:0000:")) return "benchmarking";
+	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("0064:ff9b:0001:")) 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";
+	if (expanded.startsWith("3fff:0")) return "documentation";
+	if (expanded.startsWith("5f00:")) 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/dist/utils/id.d.mts

@@ -0,0 +1,4 @@
+//#region src/utils/id.d.ts
+declare const generateId: (size?: number) => string;
+//#endregion
+export { generateId };

package/dist/utils/id.mjs

@@ -0,0 +1,7 @@
+import { createRandomStringGenerator } from "@better-auth/utils/random";
+//#region src/utils/id.ts
+const generateId = (size) => {
+	return createRandomStringGenerator("a-z", "A-Z", "0-9")(size || 32);
+};
+//#endregion
+export { generateId };

package/dist/utils/ip.d.mts

@@ -0,0 +1,77 @@
+import { BetterAuthOptions } from "../types/init-options.mjs";
+//#region src/utils/ip.d.ts
+/**
+ * Normalizes an IP address for consistent rate limiting.
+ *
+ * Features:
+ * - Normalizes IPv6 to canonical lowercase form
+ * - Converts IPv4-mapped IPv6 to IPv4
+ * - Supports IPv6 subnet extraction
+ * - Handles all edge cases (::1, ::, etc.)
+ */
+interface NormalizeIPOptions {
+  /**
+   * Prefix length used to collapse IPv6 addresses before keying.
+   * Any integer from 0 to 128 is accepted. Common values: 32, 48, 56, 64, 128.
+   * Values outside 0-128 are clamped.
+   *
+   * @default 64
+   */
+  ipv6Subnet?: number;
+}
+/**
+ * Checks if an IP is valid IPv4 or IPv6
+ */
+declare function isValidIP(ip: string): boolean;
+/**
+ * Normalizes an IP address (IPv4 or IPv6) for consistent rate limiting.
+ *
+ * @param ip - The IP address to normalize
+ * @param options - Normalization options
+ * @returns Normalized IP address
+ *
+ * @example
+ * normalizeIP("2001:DB8::1")
+ * // -> "2001:0db8:0000:0000:0000:0000:0000:0000"
+ *
+ * @example
+ * normalizeIP("::ffff:192.0.2.1")
+ * // -> "192.0.2.1" (converted to IPv4)
+ *
+ * @example
+ * normalizeIP("2001:db8::1", { ipv6Subnet: 64 })
+ * // -> "2001:0db8:0000:0000:0000:0000:0000:0000" (subnet /64)
+ */
+declare function normalizeIP(ip: string, options?: NormalizeIPOptions): string;
+/**
+ * Trusted-proxy entries that are not a valid IP address or CIDR range.
+ */
+declare function findInvalidTrustedProxies(entries: string[]): string[];
+/**
+ * Resolves the client IP from a forwarded header. The leftmost token is spoofable,
+ * so with `trustedProxies` the chain is stripped from the right to the first
+ * untrusted hop. Otherwise only a single-value header is trusted. Returns `null`
+ * when no trustworthy client IP can be resolved.
+ */
+declare function getIPFromHeader(value: string, options?: {
+  ipv6Subnet?: number;
+  trustedProxies?: string[];
+}): string | null;
+/**
+ * Resolves the client IP for a request from the configured IP headers.
+ * Honors `disableIpTracking`, walks `ipAddressHeaders` in order (default
+ * `x-forwarded-for`), and falls back to localhost in development and test.
+ * Returns `null` when tracking is disabled or no trustworthy IP can be resolved.
+ */
+declare function getIp(req: Request | Headers, options: BetterAuthOptions): string | null;
+/**
+ * Creates a rate limit key from IP and path
+ * Uses a separator to prevent collision attacks
+ *
+ * @param ip - The IP address (should be normalized)
+ * @param path - The request path
+ * @returns Rate limit key
+ */
+declare function createRateLimitKey(ip: string, path: string): string;
+//#endregion
+export { createRateLimitKey, findInvalidTrustedProxies, getIPFromHeader, getIp, isValidIP, normalizeIP };

package/dist/utils/ip.mjs

@@ -0,0 +1,230 @@
+import { isDevelopment, isTest } from "../env/env-impl.mjs";
+import * as z from "zod";
+//#region src/utils/ip.ts
+/**
+* Checks if an IP is valid IPv4 or IPv6
+*/
+function isValidIP(ip) {
+	return z.ipv4().safeParse(ip).success || z.ipv6().safeParse(ip).success;
+}
+/**
+* Checks if an IP is IPv6
+*/
+function isIPv6(ip) {
+	return z.ipv6().safeParse(ip).success;
+}
+/**
+* Converts IPv4-mapped IPv6 address to IPv4
+* e.g., "::ffff:192.0.2.1" -> "192.0.2.1"
+*/
+function extractIPv4FromMapped(ipv6) {
+	const lower = ipv6.toLowerCase();
+	if (lower.startsWith("::ffff:")) {
+		const ipv4Part = lower.substring(7);
+		if (z.ipv4().safeParse(ipv4Part).success) return ipv4Part;
+	}
+	const parts = ipv6.split(":");
+	if (parts.length === 7 && parts[5]?.toLowerCase() === "ffff") {
+		const ipv4Part = parts[6];
+		if (ipv4Part && z.ipv4().safeParse(ipv4Part).success) return ipv4Part;
+	}
+	if (lower.includes("::ffff:") || lower.includes(":ffff:")) {
+		const groups = expandIPv6(ipv6);
+		if (groups.length === 8 && groups[0] === "0000" && groups[1] === "0000" && groups[2] === "0000" && groups[3] === "0000" && groups[4] === "0000" && groups[5] === "ffff" && groups[6] && groups[7]) return `${Number.parseInt(groups[6].substring(0, 2), 16)}.${Number.parseInt(groups[6].substring(2, 4), 16)}.${Number.parseInt(groups[7].substring(0, 2), 16)}.${Number.parseInt(groups[7].substring(2, 4), 16)}`;
+	}
+	return null;
+}
+/**
+* Expands a compressed IPv6 address to full form
+* e.g., "2001:db8::1" -> ["2001", "0db8", "0000", "0000", "0000", "0000", "0000", "0001"]
+*/
+function expandIPv6(ipv6) {
+	if (ipv6.includes("::")) {
+		const sides = ipv6.split("::");
+		const left = sides[0] ? sides[0].split(":") : [];
+		const right = sides[1] ? sides[1].split(":") : [];
+		const missingGroups = 8 - left.length - right.length;
+		const zeros = Array(missingGroups).fill("0000");
+		const paddedLeft = left.map((g) => g.padStart(4, "0"));
+		const paddedRight = right.map((g) => g.padStart(4, "0"));
+		return [
+			...paddedLeft,
+			...zeros,
+			...paddedRight
+		];
+	}
+	return ipv6.split(":").map((g) => g.padStart(4, "0"));
+}
+/**
+* Normalizes an IPv6 address to canonical form
+* e.g., "2001:DB8::1" -> "2001:0db8:0000:0000:0000:0000:0000:0001"
+*/
+function normalizeIPv6(ipv6, subnetPrefix) {
+	const groups = expandIPv6(ipv6);
+	if (subnetPrefix !== void 0 && subnetPrefix < 128) {
+		let bitsRemaining = Math.max(0, Math.floor(subnetPrefix));
+		return groups.map((group) => {
+			if (bitsRemaining <= 0) return "0000";
+			if (bitsRemaining >= 16) {
+				bitsRemaining -= 16;
+				return group;
+			}
+			const masked = Number.parseInt(group, 16) & (65535 << 16 - bitsRemaining & 65535);
+			bitsRemaining = 0;
+			return masked.toString(16).padStart(4, "0");
+		}).join(":").toLowerCase();
+	}
+	return groups.join(":").toLowerCase();
+}
+/**
+* Normalizes an IP address (IPv4 or IPv6) for consistent rate limiting.
+*
+* @param ip - The IP address to normalize
+* @param options - Normalization options
+* @returns Normalized IP address
+*
+* @example
+* normalizeIP("2001:DB8::1")
+* // -> "2001:0db8:0000:0000:0000:0000:0000:0000"
+*
+* @example
+* normalizeIP("::ffff:192.0.2.1")
+* // -> "192.0.2.1" (converted to IPv4)
+*
+* @example
+* normalizeIP("2001:db8::1", { ipv6Subnet: 64 })
+* // -> "2001:0db8:0000:0000:0000:0000:0000:0000" (subnet /64)
+*/
+function normalizeIP(ip, options = {}) {
+	if (z.ipv4().safeParse(ip).success) return ip.toLowerCase();
+	if (!isIPv6(ip)) return ip.toLowerCase();
+	const ipv4 = extractIPv4FromMapped(ip);
+	if (ipv4) return ipv4.toLowerCase();
+	return normalizeIPv6(ip, options.ipv6Subnet ?? 64);
+}
+/**
+* Raw bytes of an IP for CIDR comparison. Returns `null` for an invalid IP.
+*/
+function ipToBytes(ip) {
+	if (z.ipv4().safeParse(ip).success) return Uint8Array.from(ip.split(".").map((octet) => Number(octet)));
+	if (!isIPv6(ip)) return null;
+	const mapped = extractIPv4FromMapped(ip);
+	if (mapped) return Uint8Array.from(mapped.split(".").map((octet) => Number(octet)));
+	const groups = expandIPv6(ip);
+	const bytes = new Uint8Array(16);
+	for (let i = 0; i < 8; i++) {
+		const group = Number.parseInt(groups[i] ?? "0", 16);
+		bytes[i * 2] = group >> 8 & 255;
+		bytes[i * 2 + 1] = group & 255;
+	}
+	return bytes;
+}
+const CIDR_PREFIX_PATTERN = /^\d+$/;
+/**
+* Parses an IP or `IP/prefix` string into network bytes and a prefix length.
+* The prefix must be digits only and within the address family. `null` if the
+* value is not a valid IP or CIDR range, which keeps a malformed entry from
+* silently behaving like a non-match.
+*/
+function parseCIDR(value) {
+	const slash = value.lastIndexOf("/");
+	const bytes = ipToBytes(slash === -1 ? value : value.slice(0, slash));
+	if (!bytes) return null;
+	const maxBits = bytes.length * 8;
+	if (slash === -1) return {
+		bytes,
+		prefix: maxBits
+	};
+	const prefixPart = value.slice(slash + 1);
+	if (!CIDR_PREFIX_PATTERN.test(prefixPart)) return null;
+	const prefix = Number(prefixPart);
+	return prefix <= maxBits ? {
+		bytes,
+		prefix
+	} : null;
+}
+/**
+* Whether `ipBytes` falls inside an already-parsed CIDR network.
+*/
+function matchesCIDR(ipBytes, net) {
+	if (ipBytes.length !== net.bytes.length) return false;
+	let bitsRemaining = net.prefix;
+	for (let i = 0; i < ipBytes.length && bitsRemaining > 0; i++) {
+		const take = bitsRemaining >= 8 ? 8 : bitsRemaining;
+		const mask = take === 8 ? 255 : 255 << 8 - take & 255;
+		if (((ipBytes[i] ?? 0) & mask) !== ((net.bytes[i] ?? 0) & mask)) return false;
+		bitsRemaining -= 8;
+	}
+	return true;
+}
+/**
+* Trusted-proxy entries that are not a valid IP address or CIDR range.
+*/
+function findInvalidTrustedProxies(entries) {
+	return entries.filter((entry) => parseCIDR(entry) === null);
+}
+/**
+* Resolves the client IP from a forwarded header. The leftmost token is spoofable,
+* so with `trustedProxies` the chain is stripped from the right to the first
+* untrusted hop. Otherwise only a single-value header is trusted. Returns `null`
+* when no trustworthy client IP can be resolved.
+*/
+function getIPFromHeader(value, options = {}) {
+	const forwardedIps = value.split(",").map((ip) => ip.trim()).filter(Boolean);
+	if (forwardedIps.length === 0) return null;
+	const trustedProxies = (options.trustedProxies ?? []).map(parseCIDR).filter((proxy) => {
+		return proxy !== null;
+	});
+	if (trustedProxies.length > 0) {
+		for (let i = forwardedIps.length - 1; i >= 0; i--) {
+			const ip = forwardedIps[i];
+			const ipBytes = ip ? ipToBytes(ip) : null;
+			if (!ip || !ipBytes) return null;
+			if (trustedProxies.some((proxy) => matchesCIDR(ipBytes, proxy))) continue;
+			return normalizeIP(ip, { ipv6Subnet: options.ipv6Subnet });
+		}
+		return null;
+	}
+	if (forwardedIps.length !== 1) return null;
+	const selectedIp = forwardedIps[0];
+	if (!selectedIp || !isValidIP(selectedIp)) return null;
+	return normalizeIP(selectedIp, { ipv6Subnet: options.ipv6Subnet });
+}
+const LOCALHOST_IP = "127.0.0.1";
+const DEFAULT_IP_HEADERS = ["x-forwarded-for"];
+/**
+* Resolves the client IP for a request from the configured IP headers.
+* Honors `disableIpTracking`, walks `ipAddressHeaders` in order (default
+* `x-forwarded-for`), and falls back to localhost in development and test.
+* Returns `null` when tracking is disabled or no trustworthy IP can be resolved.
+*/
+function getIp(req, options) {
+	if (options.advanced?.ipAddress?.disableIpTracking) return null;
+	const headers = "headers" in req ? req.headers : req;
+	const ipHeaders = options.advanced?.ipAddress?.ipAddressHeaders || DEFAULT_IP_HEADERS;
+	for (const key of ipHeaders) {
+		const value = "get" in headers ? headers.get(key) : headers[key];
+		if (typeof value === "string") {
+			const ip = getIPFromHeader(value, {
+				ipv6Subnet: options.advanced?.ipAddress?.ipv6Subnet,
+				trustedProxies: options.advanced?.ipAddress?.trustedProxies
+			});
+			if (ip) return ip;
+		}
+	}
+	if (isTest() || isDevelopment()) return LOCALHOST_IP;
+	return null;
+}
+/**
+* Creates a rate limit key from IP and path
+* Uses a separator to prevent collision attacks
+*
+* @param ip - The IP address (should be normalized)
+* @param path - The request path
+* @returns Rate limit key
+*/
+function createRateLimitKey(ip, path) {
+	return `${ip}|${path}`;
+}
+//#endregion
+export { createRateLimitKey, findInvalidTrustedProxies, getIPFromHeader, getIp, isValidIP, normalizeIP };

package/dist/utils/is-api-error.d.mts

@@ -0,0 +1,6 @@
+import { APIError } from "../error/index.mjs";
+
+//#region src/utils/is-api-error.d.ts
+declare function isAPIError(error: unknown): error is APIError;
+//#endregion
+export { isAPIError };

package/dist/utils/is-api-error.mjs

@@ -0,0 +1,8 @@
+import { APIError as APIError$1 } from "../error/index.mjs";
+import { APIError } from "better-call";
+//#region src/utils/is-api-error.ts
+function isAPIError(error) {
+	return error instanceof APIError || error instanceof APIError$1 || error?.name === "APIError";
+}
+//#endregion
+export { isAPIError };

package/dist/utils/json.d.mts

@@ -0,0 +1,4 @@
+//#region src/utils/json.d.ts
+declare function safeJSONParse<T>(data: unknown): T | null;
+//#endregion
+export { safeJSONParse };

package/dist/utils/json.mjs

@@ -0,0 +1,41 @@
+import { logger } from "../env/logger.mjs";
+//#region src/utils/json.ts
+const iso8601Regex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+function reviveDate(value) {
+	if (typeof value === "string" && iso8601Regex.test(value)) {
+		const date = new Date(value);
+		if (!isNaN(date.getTime())) return date;
+	}
+	return value;
+}
+/**
+* Recursively walk a pre-parsed object and convert ISO 8601 date strings
+* to Date instances. This handles the case where a Redis client (or similar)
+* returns already-parsed JSON objects whose date fields are still strings.
+*/
+function reviveDates(value) {
+	if (value === null || value === void 0) return value;
+	if (typeof value === "string") return reviveDate(value);
+	if (value instanceof Date) return value;
+	if (Array.isArray(value)) return value.map(reviveDates);
+	if (typeof value === "object") {
+		const result = {};
+		for (const key of Object.keys(value)) result[key] = reviveDates(value[key]);
+		return result;
+	}
+	return value;
+}
+function safeJSONParse(data) {
+	try {
+		if (typeof data !== "string") {
+			if (data === null || data === void 0) return null;
+			return reviveDates(data);
+		}
+		return JSON.parse(data, (_, value) => reviveDate(value));
+	} catch (e) {
+		logger.error("Error parsing JSON", { error: e });
+		return null;
+	}
+}
+//#endregion
+export { safeJSONParse };