@depup/better-auth__core 1.6.23-depup.2

package/src/utils/ip.ts

@@ -0,0 +1,395 @@
+import * as z from "zod";
+import { isDevelopment, isTest } from "../env";
+import type { BetterAuthOptions } from "../types";
+
+/**
+ * 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
+ */
+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?: number): string {
+	const groups = expandIPv6(ipv6);
+
+	if (subnetPrefix !== undefined && subnetPrefix < 128) {
+		// Clamp to a valid bit range so out-of-spec inputs degrade safely:
+		// negative or fractional values would otherwise produce malformed masks.
+		const prefix = Math.max(0, Math.floor(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. Use ?? so an explicit 0 (mask-all) is honoured.
+	const subnetPrefix = options.ipv6Subnet ?? 64;
+	return normalizeIPv6(ip, subnetPrefix);
+}
+
+/**
+ * Raw bytes of an IP for CIDR comparison. Returns `null` for an invalid IP.
+ */
+function ipToBytes(ip: string): Uint8Array | null {
+	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) & 0xff;
+		bytes[i * 2 + 1] = group & 0xff;
+	}
+	return bytes;
+}
+
+// A CIDR prefix length must be decimal digits only, so values like "8x" or
+// "1e3" that `Number()` would otherwise coerce are rejected.
+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: string,
+): { bytes: Uint8Array; prefix: number } | null {
+	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: Uint8Array,
+	net: { bytes: Uint8Array; prefix: number },
+): boolean {
+	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 ? 0xff : (0xff << (8 - take)) & 0xff;
+		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.
+ */
+export function findInvalidTrustedProxies(entries: string[]): string[] {
+	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.
+ */
+export function getIPFromHeader(
+	value: string,
+	options: {
+		ipv6Subnet?: number;
+		trustedProxies?: string[];
+	} = {},
+): string | null {
+	const forwardedIps = value
+		.split(",")
+		.map((ip) => ip.trim())
+		.filter(Boolean);
+	if (forwardedIps.length === 0) {
+		return null;
+	}
+
+	// Parse trusted proxies once, dropping malformed entries so a config typo
+	// cannot leave the chain enabled-but-empty and return a real proxy hop as
+	// the client. With no valid proxy the chain mode does not engage.
+	const trustedProxies = (options.trustedProxies ?? [])
+		.map(parseCIDR)
+		.filter((proxy): proxy is { bytes: Uint8Array; prefix: number } => {
+			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;
+			// A malformed hop breaks the chain: fail closed.
+			if (!ip || !ipBytes) {
+				return null;
+			}
+			if (trustedProxies.some((proxy) => matchesCIDR(ipBytes, proxy))) {
+				continue;
+			}
+			return normalizeIP(ip, { ipv6Subnet: options.ipv6Subnet });
+		}
+		return null;
+	}
+
+	// Without valid trusted proxies a multi-hop chain is unresolvable.
+	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.
+ */
+export function getIp(
+	req: Request | Headers,
+	options: BetterAuthOptions,
+): string | null {
+	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
+ */
+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/is-api-error.ts

@@ -0,0 +1,10 @@
+import { APIError as BaseAPIError } from "better-call";
+import { APIError } from "../error";
+
+export function isAPIError(error: unknown): error is APIError {
+	return (
+		error instanceof BaseAPIError ||
+		error instanceof APIError ||
+		(error as { name?: string })?.name === "APIError"
+	);
+}

package/src/utils/json.ts

@@ -0,0 +1,56 @@
+import { logger } from "../env";
+
+const iso8601Regex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;
+
+function reviveDate(value: unknown): any {
+	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: unknown): any {
+	if (value === null || value === undefined) {
+		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: Record<string, any> = {};
+		for (const key of Object.keys(value)) {
+			result[key] = reviveDates((value as Record<string, any>)[key]);
+		}
+		return result;
+	}
+	return value;
+}
+
+export function safeJSONParse<T>(data: unknown): T | null {
+	try {
+		if (typeof data !== "string") {
+			if (data === null || data === undefined) {
+				return null;
+			}
+			return reviveDates(data) as T;
+		}
+		return JSON.parse(data, (_, value) => reviveDate(value));
+	} catch (e) {
+		logger.error("Error parsing JSON", { error: e });
+		return null;
+	}
+}

package/src/utils/redirect-uri.ts

@@ -0,0 +1,54 @@
+import * as z from "zod";
+import { isLoopbackHost } from "./host";
+import { DANGEROUS_URL_SCHEMES } from "./url";
+
+/**
+ * Zod schema for OAuth redirect URIs and other developer-supplied URLs that the
+ * server stores and later hands back to a browser.
+ *
+ * - Rejects dangerous schemes (`javascript:`, `data:`, `vbscript:`).
+ * - Rejects URIs with a fragment component (`#...`) per RFC 6749 §3.1.2.
+ * - Requires HTTPS, except for loopback hosts (`127.0.0.0/8`, `[::1]`,
+ *   `*.localhost` per RFC 6761), where HTTP is allowed for local development.
+ * - Allows custom schemes for mobile apps (e.g. `myapp://callback`).
+ *
+ * This is the single source of truth for redirect-URI validation across the
+ * OAuth provider plugins. Consume it from `@better-auth/core/utils/redirect-uri`
+ * rather than re-implementing the scheme policy per plugin.
+ */
+export const SafeUrlSchema = z.url().superRefine((val, ctx) => {
+	let u: URL;
+	try {
+		u = new URL(val);
+	} catch {
+		ctx.addIssue({
+			code: "custom",
+			message: "URL must be parseable",
+			fatal: true,
+		});
+		return z.NEVER;
+	}
+
+	if (DANGEROUS_URL_SCHEMES.includes(u.protocol)) {
+		ctx.addIssue({
+			code: "custom",
+			message: "URL cannot use javascript:, data:, or vbscript: scheme",
+		});
+		return;
+	}
+
+	if (val.includes("#")) {
+		ctx.addIssue({
+			code: "custom",
+			message: "Redirect URI must not contain a fragment component",
+		});
+	}
+
+	if (u.protocol === "http:" && !isLoopbackHost(u.host)) {
+		ctx.addIssue({
+			code: "custom",
+			message:
+				"Redirect URI must use HTTPS (HTTP allowed only for loopback hosts)",
+		});
+	}
+});

package/src/utils/string.ts

@@ -0,0 +1,40 @@
+export function capitalizeFirstLetter(str: string) {
+	return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+const WORD_PATTERN =
+	/[\p{Ll}\d]+|\p{Lu}+(?!\p{Ll})|\p{Lu}[\p{Ll}\d]+|\p{Lo}+/gu;
+const APOSTROPHE_PATTERN = /['\u2019]/g;
+
+function splitWords(input: string): string[] {
+	return input.replace(APOSTROPHE_PATTERN, "").match(WORD_PATTERN) ?? [];
+}
+
+export function toSnakeCase(input: string): string {
+	return splitWords(input)
+		.map((word) => word.toLowerCase())
+		.join("_");
+}
+
+export function toKebabCase(input: string): string {
+	return splitWords(input)
+		.map((word) => word.toLowerCase())
+		.join("-");
+}
+
+export function toCamelCase(input: string): string {
+	return splitWords(input).reduce((acc, word, i) => {
+		return (
+			acc +
+			(i === 0
+				? word.toLowerCase()
+				: `${word[0]!.toUpperCase()}${word.slice(1)}`)
+		);
+	}, "");
+}
+
+export function toPascalCase(input: string): string {
+	return splitWords(input)
+		.map((word) => `${word[0]!.toUpperCase()}${word.slice(1).toLowerCase()}`)
+		.join("");
+}

package/src/utils/url.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 "/";
+	}
+
+	// Canonicalize the basePath the same way as the request pathname. A baseURL
+	// with a trailing slash yields a basePath like "/api/auth/"; without this it
+	// would never match the slash-stripped pathname and the prefix would leak
+	// through to disabledPaths and rate-limit special-rule matching.
+	const normalizedBasePath = basePath.replace(/\/+$/, "");
+
+	if (normalizedBasePath === "") {
+		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 === normalizedBasePath) {
+		return "/";
+	}
+
+	if (pathname.startsWith(normalizedBasePath + "/")) {
+		return pathname.slice(normalizedBasePath.length).replace(/\/+$/, "") || "/";
+	}
+
+	return pathname;
+}
+
+/**
+ * Schemes that execute or embed code when navigated to or accepted as a
+ * redirect target. These are never safe as an OAuth `redirect_uri` or as a
+ * client-side navigation target (`window.location.href`, `location.assign`, ...).
+ */
+export const DANGEROUS_URL_SCHEMES = ["javascript:", "data:", "vbscript:"];
+
+/**
+ * Returns `false` only when `value` is an absolute URL using a dangerous scheme
+ * (`javascript:`, `data:`, `vbscript:`). Relative URLs (e.g. `/dashboard`) and
+ * safe absolute schemes (`http`, `https`, custom app schemes such as
+ * `myapp://`) return `true`.
+ *
+ * Use this to guard browser navigation sinks and any redirect target that may
+ * originate from untrusted input. It is intentionally narrow: it blocks code
+ * execution schemes without rejecting relative paths or mobile deep links.
+ */
+export function isSafeUrlScheme(value: string): boolean {
+	let parsed: URL;
+	try {
+		parsed = new URL(value);
+	} catch {
+		// Relative URLs carry no scheme to abuse.
+		return true;
+	}
+	return !DANGEROUS_URL_SCHEMES.includes(parsed.protocol);
+}