@hammadj/better-auth-core 1.5.0-beta.9

package/src/utils/ip.test.ts

@@ -0,0 +1,255 @@
+import { describe, expect, it } from "vitest";
+import { createRateLimitKey, isValidIP, normalizeIP } from "./ip";
+
+describe("IP Normalization", () => {
+	describe("isValidIP", () => {
+		it("should validate IPv4 addresses", () => {
+			expect(isValidIP("192.168.1.1")).toBe(true);
+			expect(isValidIP("127.0.0.1")).toBe(true);
+			expect(isValidIP("0.0.0.0")).toBe(true);
+			expect(isValidIP("255.255.255.255")).toBe(true);
+		});
+
+		it("should validate IPv6 addresses", () => {
+			expect(isValidIP("2001:db8::1")).toBe(true);
+			expect(isValidIP("::1")).toBe(true);
+			expect(isValidIP("::")).toBe(true);
+			expect(isValidIP("2001:0db8:0000:0000:0000:0000:0000:0001")).toBe(true);
+		});
+
+		it("should reject invalid IPs", () => {
+			expect(isValidIP("not-an-ip")).toBe(false);
+			expect(isValidIP("999.999.999.999")).toBe(false);
+			expect(isValidIP("gggg::1")).toBe(false);
+		});
+	});
+
+	describe("IPv4 Normalization", () => {
+		it("should return IPv4 addresses unchanged", () => {
+			expect(normalizeIP("192.168.1.1")).toBe("192.168.1.1");
+			expect(normalizeIP("127.0.0.1")).toBe("127.0.0.1");
+			expect(normalizeIP("10.0.0.1")).toBe("10.0.0.1");
+		});
+	});
+
+	describe("IPv6 Normalization", () => {
+		it("should normalize compressed IPv6 to full form", () => {
+			expect(normalizeIP("2001:db8::1", { ipv6Subnet: 128 })).toBe(
+				"2001:0db8:0000:0000:0000:0000:0000:0001",
+			);
+			expect(normalizeIP("::1", { ipv6Subnet: 128 })).toBe(
+				"0000:0000:0000:0000:0000:0000:0000:0001",
+			);
+			expect(normalizeIP("::", { ipv6Subnet: 128 })).toBe(
+				"0000:0000:0000:0000:0000:0000:0000:0000",
+			);
+		});
+
+		it("should normalize uppercase to lowercase", () => {
+			expect(normalizeIP("2001:DB8::1", { ipv6Subnet: 128 })).toBe(
+				"2001:0db8:0000:0000:0000:0000:0000:0001",
+			);
+			expect(normalizeIP("2001:0DB8:ABCD:EF00::1", { ipv6Subnet: 128 })).toBe(
+				"2001:0db8:abcd:ef00:0000:0000:0000:0001",
+			);
+		});
+
+		it("should handle various IPv6 formats consistently", () => {
+			// All these represent the same address
+			const normalized = "2001:0db8:0000:0000:0000:0000:0000:0001";
+			expect(normalizeIP("2001:db8::1", { ipv6Subnet: 128 })).toBe(normalized);
+			expect(normalizeIP("2001:0db8:0:0:0:0:0:1", { ipv6Subnet: 128 })).toBe(
+				normalized,
+			);
+			expect(normalizeIP("2001:db8:0::1", { ipv6Subnet: 128 })).toBe(
+				normalized,
+			);
+			expect(normalizeIP("2001:0db8::0:0:0:1", { ipv6Subnet: 128 })).toBe(
+				normalized,
+			);
+		});
+
+		it("should handle IPv6 with :: at different positions", () => {
+			expect(
+				normalizeIP("2001:db8:85a3::8a2e:370:7334", { ipv6Subnet: 128 }),
+			).toBe("2001:0db8:85a3:0000:0000:8a2e:0370:7334");
+			expect(normalizeIP("::ffff:192.0.2.1")).not.toContain("::");
+		});
+	});
+
+	describe("IPv4-mapped IPv6 Conversion", () => {
+		it("should convert IPv4-mapped IPv6 to IPv4", () => {
+			expect(normalizeIP("::ffff:192.0.2.1")).toBe("192.0.2.1");
+			expect(normalizeIP("::ffff:127.0.0.1")).toBe("127.0.0.1");
+			expect(normalizeIP("::FFFF:10.0.0.1")).toBe("10.0.0.1");
+		});
+
+		it("should handle hex-encoded IPv4 in mapped addresses", () => {
+			// ::ffff:c000:0201 = ::ffff:192.0.2.1 = 192.0.2.1
+			expect(normalizeIP("::ffff:c000:0201")).toBe("192.0.2.1");
+			// ::ffff:7f00:0001 = ::ffff:127.0.0.1 = 127.0.0.1
+			expect(normalizeIP("::ffff:7f00:0001")).toBe("127.0.0.1");
+		});
+
+		it("should handle full form IPv4-mapped IPv6", () => {
+			expect(normalizeIP("0:0:0:0:0:ffff:192.0.2.1")).toBe("192.0.2.1");
+		});
+	});
+
+	describe("IPv6 Subnet Support", () => {
+		it("should extract /64 subnet", () => {
+			/* cspell:disable-next-line */
+			const ip1 = normalizeIP("2001:db8:0:0:1234:5678:90ab:cdef", {
+				ipv6Subnet: 64,
+			});
+			const ip2 = normalizeIP("2001:db8:0:0:ffff:ffff:ffff:ffff", {
+				ipv6Subnet: 64,
+			});
+			// Both should have same /64 prefix
+			expect(ip1).toBe("2001:0db8:0000:0000:0000:0000:0000:0000");
+			expect(ip2).toBe("2001:0db8:0000:0000:0000:0000:0000:0000");
+			expect(ip1).toBe(ip2);
+		});
+
+		it("should extract /48 subnet", () => {
+			/* cspell:disable-next-line */
+			const ip1 = normalizeIP("2001:db8:1234:5678:90ab:cdef:1234:5678", {
+				ipv6Subnet: 48,
+			});
+			const ip2 = normalizeIP("2001:db8:1234:ffff:ffff:ffff:ffff:ffff", {
+				ipv6Subnet: 48,
+			});
+			// Both should have same /48 prefix
+			expect(ip1).toBe("2001:0db8:1234:0000:0000:0000:0000:0000");
+			expect(ip2).toBe("2001:0db8:1234:0000:0000:0000:0000:0000");
+			expect(ip1).toBe(ip2);
+		});
+
+		it("should extract /32 subnet", () => {
+			/* cspell:disable-next-line */
+			const ip1 = normalizeIP("2001:db8:1234:5678:90ab:cdef:1234:5678", {
+				ipv6Subnet: 32,
+			});
+			const ip2 = normalizeIP("2001:db8:ffff:ffff:ffff:ffff:ffff:ffff", {
+				ipv6Subnet: 32,
+			});
+			// Both should have same /32 prefix
+			expect(ip1).toBe("2001:0db8:0000:0000:0000:0000:0000:0000");
+			expect(ip2).toBe("2001:0db8:0000:0000:0000:0000:0000:0000");
+			expect(ip1).toBe(ip2);
+		});
+
+		it("should handle /64 subnet by default", () => {
+			const ip1 = normalizeIP("2001:db8::1");
+			const ip2 = normalizeIP("2001:db8::1", { ipv6Subnet: 64 });
+			expect(ip1).toBe(ip2);
+			expect(ip1).toBe("2001:0db8:0000:0000:0000:0000:0000:0000");
+		});
+
+		it("should not affect IPv4 addresses when ipv6Subnet is set", () => {
+			expect(normalizeIP("192.168.1.1", { ipv6Subnet: 64 })).toBe(
+				"192.168.1.1",
+			);
+		});
+	});
+
+	describe("Rate Limit Key Creation", () => {
+		it("should create keys with separator", () => {
+			expect(createRateLimitKey("192.168.1.1", "/sign-in")).toBe(
+				"192.168.1.1|/sign-in",
+			);
+			expect(createRateLimitKey("2001:db8::1", "/api/auth")).toBe(
+				"2001:db8::1|/api/auth",
+			);
+		});
+
+		it("should prevent collision attacks", () => {
+			// Without separator: "192.0.2.1" + "/sign-in" = "192.0.2.1/sign-in"
+			//                    "192.0.2" + ".1/sign-in" = "192.0.2.1/sign-in"
+			// With separator: they're different
+			const key1 = createRateLimitKey("192.0.2.1", "/sign-in");
+			const key2 = createRateLimitKey("192.0.2", ".1/sign-in");
+			expect(key1).not.toBe(key2);
+			expect(key1).toBe("192.0.2.1|/sign-in");
+			expect(key2).toBe("192.0.2|.1/sign-in");
+		});
+	});
+
+	describe("Security: Bypass Prevention", () => {
+		it("should prevent IPv6 representation bypass", () => {
+			// Attacker tries different representations of same address
+			const representations = [
+				"2001:db8::1",
+				"2001:DB8::1",
+				"2001:0db8::1",
+				"2001:db8:0::1",
+				"2001:0db8:0:0:0:0:0:1",
+				"2001:db8::0:1",
+			];
+
+			const normalized = representations.map((ip) =>
+				normalizeIP(ip, { ipv6Subnet: 128 }),
+			);
+			// All should normalize to the same value
+			const uniqueValues = new Set(normalized);
+			expect(uniqueValues.size).toBe(1);
+			expect(normalized[0]).toBe("2001:0db8:0000:0000:0000:0000:0000:0001");
+		});
+
+		it("should prevent IPv4-mapped bypass", () => {
+			// Attacker switches between IPv4 and IPv4-mapped IPv6
+			const ip1 = normalizeIP("192.0.2.1");
+			const ip2 = normalizeIP("::ffff:192.0.2.1");
+			const ip3 = normalizeIP("::FFFF:192.0.2.1");
+			const ip4 = normalizeIP("::ffff:c000:0201");
+
+			// All should normalize to the same IPv4
+			expect(ip1).toBe("192.0.2.1");
+			expect(ip2).toBe("192.0.2.1");
+			expect(ip3).toBe("192.0.2.1");
+			expect(ip4).toBe("192.0.2.1");
+		});
+
+		it("should group IPv6 subnet attacks", () => {
+			// Attacker rotates through addresses in their /64 allocation
+			const attackIPs = [
+				"2001:db8:abcd:1234:0000:0000:0000:0001",
+				"2001:db8:abcd:1234:1111:2222:3333:4444",
+				"2001:db8:abcd:1234:ffff:ffff:ffff:ffff",
+				"2001:db8:abcd:1234:aaaa:bbbb:cccc:dddd",
+			];
+
+			const normalized = attackIPs.map((ip) =>
+				normalizeIP(ip, { ipv6Subnet: 64 }),
+			);
+
+			// All should map to same /64 subnet
+			const uniqueValues = new Set(normalized);
+			expect(uniqueValues.size).toBe(1);
+			expect(normalized[0]).toBe("2001:0db8:abcd:1234:0000:0000:0000:0000");
+		});
+	});
+
+	describe("Edge Cases", () => {
+		it("should handle localhost addresses", () => {
+			expect(normalizeIP("127.0.0.1")).toBe("127.0.0.1");
+			expect(normalizeIP("::1", { ipv6Subnet: 128 })).toBe(
+				"0000:0000:0000:0000:0000:0000:0000:0001",
+			);
+		});
+
+		it("should handle all-zeros address", () => {
+			expect(normalizeIP("0.0.0.0")).toBe("0.0.0.0");
+			expect(normalizeIP("::", { ipv6Subnet: 128 })).toBe(
+				"0000:0000:0000:0000:0000:0000:0000:0000",
+			);
+		});
+
+		it("should handle link-local addresses", () => {
+			expect(normalizeIP("169.254.0.1")).toBe("169.254.0.1");
+			expect(normalizeIP("fe80::1", { ipv6Subnet: 128 })).toBe(
+				"fe80:0000:0000:0000:0000:0000:0000:0001",
+			);
+		});
+	});
+});

package/src/utils/ip.ts

@@ -0,0 +1,211 @@
+import * as z from "zod";
+
+/**
+ * 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 {
+	/**
+	 * For IPv6 addresses, extract the subnet prefix instead of full address.
+	 * Common values: 32, 48, 64, 128 (default: 128 = full address)
+	 *
+	 * @default 128
+	 */
+	ipv6Subnet?: 128 | 64 | 48 | 32;
+}
+
+/**
+ * Checks if an IP is valid IPv4 or IPv6
+ */
+export function isValidIP(ip: string): boolean {
+	return z.ipv4().safeParse(ip).success || z.ipv6().safeParse(ip).success;
+}
+
+/**
+ * Checks if an IP is IPv6
+ */
+function isIPv6(ip: string): boolean {
+	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: string): string | null {
+	const lower = ipv6.toLowerCase();
+
+	// Handle ::ffff:192.0.2.1 format
+	if (lower.startsWith("::ffff:")) {
+		const ipv4Part = lower.substring(7);
+		// Check if it's a valid IPv4
+		if (z.ipv4().safeParse(ipv4Part).success) {
+			return ipv4Part;
+		}
+	}
+
+	// Handle full form: 0:0:0:0:0:ffff:192.0.2.1
+	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;
+		}
+	}
+
+	// Handle hex-encoded IPv4 in mapped address
+	// e.g., ::ffff:c000:0201 -> 192.0.2.1
+	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]
+		) {
+			// Convert last two groups to IPv4
+			const byte1 = Number.parseInt(groups[6].substring(0, 2), 16);
+			const byte2 = Number.parseInt(groups[6].substring(2, 4), 16);
+			const byte3 = Number.parseInt(groups[7].substring(0, 2), 16);
+			const byte4 = Number.parseInt(groups[7].substring(2, 4), 16);
+			return `${byte1}.${byte2}.${byte3}.${byte4}`;
+		}
+	}
+
+	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: string): string[] {
+	// Handle :: notation (zero compression)
+	if (ipv6.includes("::")) {
+		const sides = ipv6.split("::");
+		const left = sides[0] ? sides[0].split(":") : [];
+		const right = sides[1] ? sides[1].split(":") : [];
+
+		// Calculate missing groups
+		const totalGroups = 8;
+		const missingGroups = totalGroups - left.length - right.length;
+		const zeros = Array(missingGroups).fill("0000");
+
+		// Pad existing groups to 4 digits
+		const paddedLeft = left.map((g) => g.padStart(4, "0"));
+		const paddedRight = right.map((g) => g.padStart(4, "0"));
+
+		return [...paddedLeft, ...zeros, ...paddedRight];
+	}
+
+	// No compression, just pad each group
+	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: string,
+	subnetPrefix?: 128 | 32 | 48 | 64,
+): string {
+	const groups = expandIPv6(ipv6);
+
+	if (subnetPrefix && subnetPrefix < 128) {
+		// Apply subnet mask
+		const prefix = subnetPrefix;
+		let bitsRemaining: number = prefix;
+
+		const maskedGroups = groups.map((group) => {
+			if (bitsRemaining <= 0) {
+				return "0000";
+			}
+			if (bitsRemaining >= 16) {
+				bitsRemaining -= 16;
+				return group;
+			}
+
+			// Partial mask for this group
+			const value = Number.parseInt(group, 16);
+			const mask = (0xffff << (16 - bitsRemaining)) & 0xffff;
+			const masked = value & mask;
+			bitsRemaining = 0;
+			return masked.toString(16).padStart(4, "0");
+		});
+
+		return maskedGroups.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)
+ */
+export function normalizeIP(
+	ip: string,
+	options: NormalizeIPOptions = {},
+): string {
+	// IPv4 addresses are already normalized
+	if (z.ipv4().safeParse(ip).success) {
+		return ip.toLowerCase();
+	}
+
+	// Check if it's IPv6
+	if (!isIPv6(ip)) {
+		// Return as-is if not valid (shouldn't happen due to prior validation)
+		return ip.toLowerCase();
+	}
+
+	// Check for IPv4-mapped IPv6
+	const ipv4 = extractIPv4FromMapped(ip);
+	if (ipv4) {
+		return ipv4.toLowerCase();
+	}
+
+	// Normalize IPv6
+	const subnetPrefix = options.ipv6Subnet || 64;
+	return normalizeIPv6(ip, subnetPrefix);
+}
+
+/**
+ * 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
+ */
+export function createRateLimitKey(ip: string, path: string): string {
+	// Use | as separator to prevent collision attacks
+	// e.g., "192.0.2.1" + "/sign-in" vs "192.0.2" + ".1/sign-in"
+	return `${ip}|${path}`;
+}

package/src/utils/json.ts

@@ -0,0 +1,25 @@
+import { logger } from "../env";
+
+export function safeJSONParse<T>(data: unknown): T | null {
+	function reviver(_: string, value: any): any {
+		if (typeof value === "string") {
+			const iso8601Regex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+			if (iso8601Regex.test(value)) {
+				const date = new Date(value);
+				if (!isNaN(date.getTime())) {
+					return date;
+				}
+			}
+		}
+		return value;
+	}
+	try {
+		if (typeof data !== "string") {
+			return data as T;
+		}
+		return JSON.parse(data, reviver);
+	} catch (e) {
+		logger.error("Error parsing JSON", { error: e });
+		return null;
+	}
+}

package/src/utils/string.ts

@@ -0,0 +1,3 @@
+export function capitalizeFirstLetter(str: string) {
+	return str.charAt(0).toUpperCase() + str.slice(1);
+}

package/src/utils/url.ts

@@ -0,0 +1,43 @@
+/**
+ * Normalizes a request pathname by removing the basePath prefix and trailing slashes.
+ * This is useful for matching paths against configured path lists.
+ *
+ * @param requestUrl - The full request URL
+ * @param basePath - The base path of the auth API (e.g., "/api/auth")
+ * @returns The normalized path without basePath prefix or trailing slashes,
+ *          or "/" if URL parsing fails
+ *
+ * @example
+ * normalizePathname("http://localhost:3000/api/auth/sso/saml2/callback/provider1", "/api/auth")
+ * // Returns: "/sso/saml2/callback/provider1"
+ *
+ * normalizePathname("http://localhost:3000/sso/saml2/callback/provider1/", "/")
+ * // Returns: "/sso/saml2/callback/provider1"
+ */
+export function normalizePathname(
+	requestUrl: string,
+	basePath: string,
+): string {
+	let pathname: string;
+	try {
+		pathname = new URL(requestUrl).pathname.replace(/\/+$/, "") || "/";
+	} catch {
+		return "/";
+	}
+
+	if (basePath === "/" || basePath === "") {
+		return pathname;
+	}
+
+	// Check for exact match or proper path boundary (basePath followed by "/" or end)
+	// This prevents "/api/auth" from matching "/api/authevil/..."
+	if (pathname === basePath) {
+		return "/";
+	}
+
+	if (pathname.startsWith(basePath + "/")) {
+		return pathname.slice(basePath.length).replace(/\/+$/, "") || "/";
+	}
+
+	return pathname;
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["esnext", "dom", "dom.iterable"],
+    "types": ["node"]
+  }
+}

package/tsdown.config.ts

@@ -0,0 +1,35 @@
+import { readFile } from "node:fs/promises";
+import { defineConfig } from "tsdown";
+
+const packageJson = JSON.parse(
+	await readFile(new URL("./package.json", import.meta.url), "utf-8"),
+);
+
+export default defineConfig({
+	dts: { build: true, incremental: true },
+	format: ["esm"],
+	entry: [
+		"./src/index.ts",
+		"./src/db/index.ts",
+		"./src/db/adapter/index.ts",
+		"./src/async_hooks/index.ts",
+		"./src/async_hooks/pure.index.ts",
+		"./src/context/index.ts",
+		"./src/env/index.ts",
+		"./src/oauth2/index.ts",
+		"./src/api/index.ts",
+		"./src/social-providers/index.ts",
+		"./src/utils/*.ts",
+		"!./src/utils/*.test.ts",
+		"./src/error/index.ts",
+	],
+	external: ["@better-auth/core/async_hooks"],
+	env: {
+		BETTER_AUTH_VERSION: packageJson.version,
+		BETTER_AUTH_TELEMETRY_ENDPOINT:
+			process.env.BETTER_AUTH_TELEMETRY_ENDPOINT ?? "",
+	},
+	sourcemap: true,
+	unbundle: true,
+	clean: true,
+});

package/vitest.config.ts

@@ -0,0 +1,3 @@
+import { defineProject } from "vitest/config";
+
+export default defineProject({});