@better-auth/core 1.4.15 → 1.4.16

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @better-auth/core@1.4.15 build /home/runner/work/better-auth/better-auth/packages/core
+> @better-auth/core@1.4.16 build /home/runner/work/better-auth/better-auth/packages/core
 > tsdown
 
 ℹ tsdown v0.17.2 powered by rolldown v1.0.0-beta.53
@@ -14,15 +14,16 @@
 ℹ dist/oauth2/index.mjs                            0.87 kB │ gzip: 0.27 kB
 ℹ dist/context/index.mjs                           0.79 kB │ gzip: 0.23 kB
 ℹ dist/db/adapter/index.mjs                        0.71 kB │ gzip: 0.22 kB
+ℹ dist/utils/index.mjs                             0.51 kB │ gzip: 0.22 kB
 ℹ dist/db/index.mjs                                0.50 kB │ gzip: 0.18 kB
 ℹ dist/env/index.mjs                               0.43 kB │ gzip: 0.21 kB
-ℹ dist/utils/index.mjs                             0.33 kB │ gzip: 0.16 kB
 ℹ dist/error/index.mjs                             0.33 kB │ gzip: 0.21 kB
 ℹ dist/index.mjs                                   0.01 kB │ gzip: 0.03 kB
 ℹ dist/db/adapter/factory.mjs                     30.11 kB │ gzip: 5.99 kB
 ℹ dist/db/get-tables.mjs                           6.89 kB │ gzip: 1.30 kB
 ℹ dist/social-providers/cognito.mjs                5.93 kB │ gzip: 1.93 kB
 ℹ dist/social-providers/paypal.mjs                 5.03 kB │ gzip: 1.48 kB
+ℹ dist/utils/ip.mjs                                3.81 kB │ gzip: 1.29 kB
 ℹ dist/social-providers/google.mjs                 3.79 kB │ gzip: 1.39 kB
 ℹ dist/oauth2/verify.mjs                           3.74 kB │ gzip: 1.32 kB
 ℹ dist/social-providers/apple.mjs                  3.71 kB │ gzip: 1.34 kB
@@ -71,6 +72,7 @@
 ℹ dist/context/endpoint-context.mjs                1.31 kB │ gzip: 0.53 kB
 ℹ dist/db/adapter/get-field-attributes.mjs         1.26 kB │ gzip: 0.46 kB
 ℹ dist/db/adapter/utils.mjs                        1.15 kB │ gzip: 0.46 kB
+ℹ dist/utils/url.mjs                               1.14 kB │ gzip: 0.51 kB
 ℹ dist/db/adapter/get-field-name.mjs               1.07 kB │ gzip: 0.47 kB
 ℹ dist/oauth2/utils.mjs                            0.98 kB │ gzip: 0.50 kB
 ℹ dist/context/global.mjs                          0.96 kB │ gzip: 0.47 kB
@@ -94,12 +96,12 @@
 ℹ dist/db/index.d.mts                              1.04 kB │ gzip: 0.34 kB
 ℹ dist/context/index.d.mts                         0.92 kB │ gzip: 0.27 kB
 ℹ dist/env/index.d.mts                             0.58 kB │ gzip: 0.27 kB
-ℹ dist/utils/index.d.mts                           0.33 kB │ gzip: 0.16 kB
+ℹ dist/utils/index.d.mts                           0.51 kB │ gzip: 0.22 kB
 ℹ dist/error/index.d.mts                           0.27 kB │ gzip: 0.21 kB
 ℹ dist/async_hooks/index.d.mts                     0.24 kB │ gzip: 0.16 kB
 ℹ dist/async_hooks/pure.index.d.mts                0.22 kB │ gzip: 0.16 kB
-ℹ dist/types/init-options.d.mts                   38.32 kB │ gzip: 8.50 kB
-ℹ dist/types/context.d.mts                         9.05 kB │ gzip: 2.65 kB
+ℹ dist/types/init-options.d.mts                   39.01 kB │ gzip: 8.77 kB
+ℹ dist/types/context.d.mts                         9.09 kB │ gzip: 2.66 kB
 ℹ dist/social-providers/zoom.d.mts                 6.71 kB │ gzip: 2.29 kB
 ℹ dist/oauth2/oauth-provider.d.mts                 5.92 kB │ gzip: 1.67 kB
 ℹ dist/social-providers/microsoft-entra-id.d.mts   5.59 kB │ gzip: 1.96 kB
@@ -136,6 +138,7 @@
 ℹ dist/social-providers/kick.d.mts                 1.62 kB │ gzip: 0.59 kB
 ℹ dist/social-providers/linkedin.d.mts             1.61 kB │ gzip: 0.60 kB
 ℹ dist/social-providers/linear.d.mts               1.60 kB │ gzip: 0.59 kB
+ℹ dist/utils/ip.d.mts                              1.58 kB │ gzip: 0.69 kB
 ℹ dist/oauth2/validate-authorization-code.d.mts    1.57 kB │ gzip: 0.49 kB
 ℹ dist/social-providers/notion.d.mts               1.56 kB │ gzip: 0.59 kB
 ℹ dist/social-providers/reddit.d.mts               1.54 kB │ gzip: 0.57 kB
@@ -153,6 +156,7 @@
 ℹ dist/oauth2/client-credentials-token.d.mts       0.91 kB │ gzip: 0.36 kB
 ℹ dist/context/transaction.d.mts                   0.86 kB │ gzip: 0.38 kB
 ℹ dist/utils/error-codes.d.mts                     0.84 kB │ gzip: 0.43 kB
+ℹ dist/utils/url.d.mts                             0.84 kB │ gzip: 0.40 kB
 ℹ dist/db/schema/session.d.mts                     0.75 kB │ gzip: 0.40 kB
 ℹ dist/types/index.d.mts                           0.74 kB │ gzip: 0.32 kB
 ℹ dist/db/adapter/get-field-attributes.d.mts       0.72 kB │ gzip: 0.34 kB
@@ -176,5 +180,5 @@
 ℹ dist/utils/json.d.mts                            0.13 kB │ gzip: 0.13 kB
 ℹ dist/utils/id.d.mts                              0.12 kB │ gzip: 0.12 kB
 ℹ dist/env/color-depth.d.mts                       0.12 kB │ gzip: 0.11 kB
-ℹ 169 files, total: 440.50 kB
-✔ Build complete in 6540ms
+ℹ 173 files, total: 448.95 kB
+✔ Build complete in 6430ms

package/dist/context/global.mjs

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

package/dist/types/context.d.mts

@@ -47,6 +47,7 @@ interface InternalAdapter<_Options extends BetterAuthOptions = BetterAuthOptions
   deleteSessions(userIdOrSessionTokens: string | string[]): Promise<void>;
   findOAuthUser(email: string, accountId: string, providerId: string): Promise<{
     user: User;
+    linkedAccount: Account | null;
     accounts: Account[];
   } | null>;
   findUserByEmail(email: string, options?: {

package/dist/types/init-options.d.mts

@@ -122,6 +122,25 @@ type BetterAuthAdvancedOptions = {
      * ⚠︎ This is a security risk and it may expose your application to abuse
      */
     disableIpTracking?: boolean;
+    /**
+     * IPv6 subnet prefix length for rate limiting.
+     *
+     * IPv6 addresses can be grouped by subnet to prevent attackers from
+     * bypassing rate limits by rotating through multiple addresses in
+     * their allocation.
+     *
+     * Common values:
+     * - 128 (default): Individual IPv6 address
+     * - 64: /64 subnet (typical home/business allocation)
+     * - 48: /48 subnet (larger network allocation)
+     * - 32: /32 subnet (ISP allocation)
+     *
+     * Note: This only affects IPv6 addresses. IPv4 addresses are always
+     * rate limited individually.
+     *
+     * @default 128 (individual address)
+     */
+    ipv6Subnet?: 128 | 64 | 48 | 32 | undefined;
   } | undefined;
   /**
    * Use secure cookies

package/dist/utils/index.d.mts

@@ -1,6 +1,8 @@
 import { deprecate } from "./deprecate.mjs";
 import { defineErrorCodes } from "./error-codes.mjs";
 import { generateId } from "./id.mjs";
+import { createRateLimitKey, isValidIP, normalizeIP } from "./ip.mjs";
 import { safeJSONParse } from "./json.mjs";
 import { capitalizeFirstLetter } from "./string.mjs";
-export { capitalizeFirstLetter, defineErrorCodes, deprecate, generateId, safeJSONParse };
+import { normalizePathname } from "./url.mjs";
+export { capitalizeFirstLetter, createRateLimitKey, defineErrorCodes, deprecate, generateId, isValidIP, normalizeIP, normalizePathname, safeJSONParse };

package/dist/utils/index.mjs

@@ -1,7 +1,9 @@
 import { deprecate } from "./deprecate.mjs";
 import { defineErrorCodes } from "./error-codes.mjs";
 import { generateId } from "./id.mjs";
+import { createRateLimitKey, isValidIP, normalizeIP } from "./ip.mjs";
 import { safeJSONParse } from "./json.mjs";
 import { capitalizeFirstLetter } from "./string.mjs";
+import { normalizePathname } from "./url.mjs";
 
-export { capitalizeFirstLetter, defineErrorCodes, deprecate, generateId, safeJSONParse };
+export { capitalizeFirstLetter, createRateLimitKey, defineErrorCodes, deprecate, generateId, isValidIP, normalizeIP, normalizePathname, safeJSONParse };

package/dist/utils/ip.d.mts

@@ -0,0 +1,54 @@
+//#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 {
+  /**
+   * 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
+ */
+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:0001"
+ *
+ * @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;
+/**
+ * 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, isValidIP, normalizeIP };

package/dist/utils/ip.mjs

@@ -0,0 +1,118 @@
+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 && subnetPrefix < 128) {
+		let bitsRemaining = 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:0001"
+*
+* @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 || 128);
+}
+/**
+* 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, isValidIP, normalizeIP };

package/dist/utils/url.d.mts

@@ -0,0 +1,20 @@
+//#region src/utils/url.d.ts
+/**
+ * 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"
+ */
+declare function normalizePathname(requestUrl: string, basePath: string): string;
+//#endregion
+export { normalizePathname };

package/dist/utils/url.mjs

@@ -0,0 +1,32 @@
+//#region src/utils/url.ts
+/**
+* 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"
+*/
+function normalizePathname(requestUrl, basePath) {
+	let pathname;
+	try {
+		pathname = new URL(requestUrl).pathname.replace(/\/+$/, "") || "/";
+	} catch {
+		return "/";
+	}
+	if (basePath === "/" || basePath === "") return pathname;
+	if (pathname === basePath) return "/";
+	if (pathname.startsWith(basePath + "/")) return pathname.slice(basePath.length).replace(/\/+$/, "") || "/";
+	return pathname;
+}
+
+//#endregion
+export { normalizePathname };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/core",
-  "version": "1.4.15",
+  "version": "1.4.16",
   "description": "The most comprehensive authentication framework for TypeScript.",
   "type": "module",
   "repository": {

package/src/types/context.ts

@@ -91,7 +91,11 @@ export interface InternalAdapter<
 		email: string,
 		accountId: string,
 		providerId: string,
-	): Promise<{ user: User; accounts: Account[] } | null>;
+	): Promise<{
+		user: User;
+		linkedAccount: Account | null;
+		accounts: Account[];
+	} | null>;
 
 	findUserByEmail(
 		email: string,

package/src/types/init-options.ts

@@ -142,6 +142,25 @@ export type BetterAuthAdvancedOptions = {
 				 * ⚠︎ This is a security risk and it may expose your application to abuse
 				 */
 				disableIpTracking?: boolean;
+				/**
+				 * IPv6 subnet prefix length for rate limiting.
+				 *
+				 * IPv6 addresses can be grouped by subnet to prevent attackers from
+				 * bypassing rate limits by rotating through multiple addresses in
+				 * their allocation.
+				 *
+				 * Common values:
+				 * - 128 (default): Individual IPv6 address
+				 * - 64: /64 subnet (typical home/business allocation)
+				 * - 48: /48 subnet (larger network allocation)
+				 * - 32: /32 subnet (ISP allocation)
+				 *
+				 * Note: This only affects IPv6 addresses. IPv4 addresses are always
+				 * rate limited individually.
+				 *
+				 * @default 128 (individual address)
+				 */
+				ipv6Subnet?: 128 | 64 | 48 | 32 | undefined;
 		  }
 		| undefined;
 	/**

package/src/utils/index.ts

@@ -1,5 +1,7 @@
 export { deprecate } from "./deprecate";
 export { defineErrorCodes } from "./error-codes";
 export { generateId } from "./id";
+export { createRateLimitKey, isValidIP, normalizeIP } from "./ip";
 export { safeJSONParse } from "./json";
 export { capitalizeFirstLetter } from "./string";
+export { normalizePathname } from "./url";

package/src/utils/ip.test.ts

@@ -0,0 +1,243 @@
+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")).toBe(
+				"2001:0db8:0000:0000:0000:0000:0000:0001",
+			);
+			expect(normalizeIP("::1")).toBe(
+				"0000:0000:0000:0000:0000:0000:0000:0001",
+			);
+			expect(normalizeIP("::")).toBe("0000:0000:0000:0000:0000:0000:0000:0000");
+		});
+
+		it("should normalize uppercase to lowercase", () => {
+			expect(normalizeIP("2001:DB8::1")).toBe(
+				"2001:0db8:0000:0000:0000:0000:0000:0001",
+			);
+			expect(normalizeIP("2001:0DB8:ABCD:EF00::1")).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")).toBe(normalized);
+			expect(normalizeIP("2001:0db8:0:0:0:0:0:1")).toBe(normalized);
+			expect(normalizeIP("2001:db8:0::1")).toBe(normalized);
+			expect(normalizeIP("2001:0db8::0:0:0:1")).toBe(normalized);
+		});
+
+		it("should handle IPv6 with :: at different positions", () => {
+			expect(normalizeIP("2001:db8:85a3::8a2e:370:7334")).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 /128 (full address) by default", () => {
+			const ip1 = normalizeIP("2001:db8::1");
+			const ip2 = normalizeIP("2001:db8::1", { ipv6Subnet: 128 });
+			expect(ip1).toBe(ip2);
+			expect(ip1).toBe("2001:0db8:0000:0000:0000:0000:0000:0001");
+		});
+
+		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));
+			// 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")).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("::")).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")).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:0001"
+ *
+ * @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 || 128;
+	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/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;
+}