@better-auth/core 1.6.20 → 1.6.22

package/src/db/adapter/index.ts

@@ -434,8 +434,14 @@ export type DBAdapter<Options extends BetterAuthOptions = BetterAuthOptions> = {
 		where?: Where[] | undefined;
 	}) => Promise<number>;
 	/**
-	 * ⚠︎ Update may not return the updated data
-	 * if multiple where clauses are provided
+	 * Update a single row matching the where clause.
+	 *
+	 * Returns the updated row, or `null` when no row matched. Empty `where`
+	 * clauses return `null`; use `updateMany` for intentional bulk updates.
+	 *
+	 * This is not the race-safe primitive for guarded state transitions. Use
+	 * `incrementOne` when the predicate is both selector and guard, and use
+	 * `consumeOne` for single-use destructive reads.
 	 */
 	update: <T>(data: {
 		model: string;

package/src/db/get-tables.ts

@@ -15,13 +15,19 @@ export const getAuthTables = (
 						...value.fields,
 					},
 					modelName: value.modelName || key,
+					disableMigrations:
+						value.disableMigration ?? acc[key]?.disableMigrations,
 				};
 			}
 			return acc;
 		},
 		{} as Record<
 			string,
-			{ fields: Record<string, DBFieldAttribute>; modelName: string }
+			{
+				fields: Record<string, DBFieldAttribute>;
+				modelName: string;
+				disableMigrations?: boolean | undefined;
+			}
 		>,
 	);
 

package/src/oauth2/client-credentials-token.ts

@@ -1,7 +1,7 @@
 import { base64Url } from "@better-auth/utils/base64";
-import { betterFetch } from "@better-fetch/fetch";
 import type { AwaitableFunction } from "../types";
 import type { OAuth2Tokens, ProviderOptions } from "./oauth-provider";
+import { fetchRefusingRedirects } from "./reject-redirects";
 
 export async function clientCredentialsTokenRequest({
 	options,
@@ -96,7 +96,7 @@ export async function clientCredentialsToken({
 		resource,
 	});
 
-	const { data, error } = await betterFetch<{
+	const { data, error } = await fetchRefusingRedirects<{
 		access_token: string;
 		expires_in?: number | undefined;
 		token_type?: string | undefined;

package/src/oauth2/refresh-access-token.ts

@@ -1,7 +1,7 @@
 import { base64 } from "@better-auth/utils/base64";
-import { betterFetch } from "@better-fetch/fetch";
 import type { AwaitableFunction } from "../types";
 import type { OAuth2Tokens, ProviderOptions } from "./oauth-provider";
+import { fetchRefusingRedirects } from "./reject-redirects";
 
 export async function refreshAccessTokenRequest({
 	refreshToken,
@@ -115,7 +115,7 @@ export async function refreshAccessToken({
 		extraParams,
 	});
 
-	const { data, error } = await betterFetch<{
+	const { data, error } = await fetchRefusingRedirects<{
 		access_token: string;
 		refresh_token?: string | undefined;
 		expires_in?: number | undefined;

package/src/oauth2/reject-redirects.ts

@@ -0,0 +1,70 @@
+// cspell:ignore workerd
+import type { BetterFetchOption } from "@better-fetch/fetch";
+import { betterFetch } from "@better-fetch/fetch";
+import { BetterAuthError } from "../error";
+
+const HTTP_REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+
+/**
+ * Whether a response from a `redirect: "manual"` fetch is a redirect.
+ *
+ * Node/undici exposes the real 3xx status. Spec-compliant runtimes (Cloudflare
+ * Workers, Deno, browsers) return an opaque-redirect filtered response with
+ * status 0 and type `"opaqueredirect"`, so the status alone is not enough.
+ */
+function isRedirectResponse(response: Response): boolean {
+	return (
+		response.type === "opaqueredirect" ||
+		HTTP_REDIRECT_STATUSES.has(response.status)
+	);
+}
+
+function redirectRefused(endpoint: string): BetterAuthError {
+	return new BetterAuthError(
+		`The OAuth endpoint "${endpoint}" returned an HTTP redirect. Server-side OAuth fetches refuse redirects to prevent SSRF; configure the final endpoint URL.`,
+	);
+}
+
+/**
+ * Fetch option that refuses HTTP redirects portably.
+ *
+ * Cloudflare Workers (workerd) rejects `redirect: "error"`, so manual mode is
+ * used and the resolved response is checked with {@link assertResponseNotRedirect}
+ * (or, for betterFetch, with {@link fetchRefusingRedirects}).
+ */
+export const NO_FOLLOW_REDIRECT = { redirect: "manual" } as const;
+
+/**
+ * Throw when a native-`fetch` response (e.g. jose's JWKS loader) resolved to a
+ * redirect, so an attacker-influenced endpoint cannot bounce a server-side
+ * request to an internal address.
+ */
+export function assertResponseNotRedirect(
+	endpoint: string,
+	response: Response,
+): void {
+	if (isRedirectResponse(response)) throw redirectRefused(endpoint);
+}
+
+/**
+ * betterFetch that refuses HTTP redirects on a server-side OAuth fetch.
+ *
+ * Returns the betterFetch result and throws if the endpoint redirected, on both
+ * undici (real 3xx status) and spec-compliant runtimes (opaque redirect, where
+ * the error status is 0). The redirect is never followed on any runtime.
+ */
+export async function fetchRefusingRedirects<T>(
+	url: string,
+	options?: BetterFetchOption,
+) {
+	let redirected = false;
+	const result = await betterFetch<T>(url, {
+		...options,
+		...NO_FOLLOW_REDIRECT,
+		onError(context) {
+			if (isRedirectResponse(context.response)) redirected = true;
+		},
+	});
+	if (redirected) throw redirectRefused(url);
+	return result;
+}

package/src/oauth2/validate-authorization-code.ts

@@ -1,9 +1,13 @@
 import { base64 } from "@better-auth/utils/base64";
-import { betterFetch } from "@better-fetch/fetch";
-import { createRemoteJWKSet, jwtVerify } from "jose";
+import { createRemoteJWKSet, customFetch, jwtVerify } from "jose";
 import type { AwaitableFunction } from "../types";
 import type { ProviderOptions } from "./index";
 import { getOAuth2Tokens } from "./index";
+import {
+	assertResponseNotRedirect,
+	fetchRefusingRedirects,
+	NO_FOLLOW_REDIRECT,
+} from "./reject-redirects";
 
 export async function authorizationCodeRequest({
 	code,
@@ -151,7 +155,7 @@ export async function validateAuthorizationCode({
 		resource,
 	});
 
-	const { data, error } = await betterFetch<object>(tokenEndpoint, {
+	const { data, error } = await fetchRefusingRedirects<object>(tokenEndpoint, {
 		method: "POST",
 		body: body,
 		headers: requestHeaders,
@@ -171,7 +175,13 @@ export async function validateToken(
 		issuer?: string | string[];
 	},
 ) {
-	const jwks = createRemoteJWKSet(new URL(jwksEndpoint));
+	const jwks = createRemoteJWKSet(new URL(jwksEndpoint), {
+		[customFetch]: async (url, init) => {
+			const response = await fetch(url, { ...init, ...NO_FOLLOW_REDIRECT });
+			assertResponseNotRedirect(String(url), response);
+			return response;
+		},
+	});
 	const verified = await jwtVerify(token, jwks, {
 		audience: options?.audience,
 		issuer: options?.issuer,

package/src/oauth2/verify.ts

@@ -1,4 +1,3 @@
-import { betterFetch } from "@better-fetch/fetch";
 import { APIError } from "better-call";
 import type {
 	JSONWebKeySet,
@@ -15,6 +14,7 @@ import {
 	UnsecuredJWT,
 } from "jose";
 import { logger } from "../env";
+import { fetchRefusingRedirects } from "./reject-redirects";
 
 const joseInfrastructureErrorCodes = new Set([
 	joseErrors.JWKSTimeout.code,
@@ -107,7 +107,7 @@ async function fetchJwks(
 ): Promise<JSONWebKeySet> {
 	const jwks =
 		typeof jwksFetch === "string"
-			? await betterFetch<JSONWebKeySet>(jwksFetch, {
+			? await fetchRefusingRedirects<JSONWebKeySet>(jwksFetch, {
 					headers: {
 						Accept: "application/json",
 					},
@@ -332,23 +332,24 @@ export async function verifyAccessToken(
 
 	// Remote verify
 	if (opts?.remoteVerify) {
-		const { data: introspect, error: introspectError } = await betterFetch<
-			JWTPayload & {
-				active: boolean;
-			}
-		>(opts.remoteVerify.introspectUrl, {
-			method: "POST",
-			headers: {
-				Accept: "application/json",
-				"Content-Type": "application/x-www-form-urlencoded",
-			},
-			body: new URLSearchParams({
-				client_id: opts.remoteVerify.clientId,
-				client_secret: opts.remoteVerify.clientSecret,
-				token,
-				token_type_hint: "access_token",
-			}).toString(),
-		});
+		const { data: introspect, error: introspectError } =
+			await fetchRefusingRedirects<
+				JWTPayload & {
+					active: boolean;
+				}
+			>(opts.remoteVerify.introspectUrl, {
+				method: "POST",
+				headers: {
+					Accept: "application/json",
+					"Content-Type": "application/x-www-form-urlencoded",
+				},
+				body: new URLSearchParams({
+					client_id: opts.remoteVerify.clientId,
+					client_secret: opts.remoteVerify.clientSecret,
+					token,
+					token_type_hint: "access_token",
+				}).toString(),
+			});
 		if (introspectError)
 			logger.error(
 				`Introspection failed: ${introspectError.message ?? introspectError.statusText}`,

package/src/social-providers/google.ts

@@ -1,4 +1,5 @@
 import { betterFetch } from "@better-fetch/fetch";
+import type { JWTPayload } from "jose";
 import { decodeJwt, decodeProtectedHeader, importJWK, jwtVerify } from "jose";
 import { logger } from "../env";
 import { APIError, BetterAuthError } from "../error";
@@ -52,12 +53,67 @@ export interface GoogleOptions extends ProviderOptions<GoogleProfile> {
 	 *
 	 * This is sent to Google as the `hd` authorization hint and, when set, is
 	 * also enforced against the `hd` claim of the returned id token/profile.
-	 * Sign-in is rejected when the claim is missing or does not match, so this
-	 * can be used to restrict sign-in to a Workspace domain.
+	 * Set `hd: "*"` to require any Workspace hosted-domain claim. Sign-in is
+	 * rejected when the claim is missing or does not satisfy this restriction.
 	 */
 	hd?: string | undefined;
 }
 
+const GOOGLE_ID_TOKEN_MAX_AGE = "1h";
+
+export interface VerifyGoogleIdTokenOptions {
+	token: string;
+	audience: string | string[];
+	nonce?: string | undefined;
+}
+
+/**
+ * Verifies a Google ID token against Google's issuer, audience, signature,
+ * expiry, and maximum token age.
+ */
+export const verifyGoogleIdToken = async ({
+	token,
+	audience,
+	nonce,
+}: VerifyGoogleIdTokenOptions): Promise<JWTPayload | null> => {
+	try {
+		const { kid, alg: jwtAlg } = decodeProtectedHeader(token);
+		if (!kid || !jwtAlg) return null;
+
+		const publicKey = await getGooglePublicKey(kid);
+		const { payload: jwtClaims } = await jwtVerify(token, publicKey, {
+			algorithms: [jwtAlg],
+			issuer: ["https://accounts.google.com", "accounts.google.com"],
+			audience,
+			maxTokenAge: GOOGLE_ID_TOKEN_MAX_AGE,
+		});
+
+		if (nonce && jwtClaims.nonce !== nonce) {
+			return null;
+		}
+
+		return jwtClaims;
+	} catch {
+		return null;
+	}
+};
+
+/**
+ * Checks whether Google's verified `hd` claim satisfies the configured hosted
+ * domain restriction. `hd: "*"` accepts any Google Workspace hosted domain.
+ */
+export const isGoogleHostedDomainAllowed = (
+	configuredHostedDomain: string | undefined,
+	tokenHostedDomain: unknown,
+) => {
+	if (!configuredHostedDomain) return true;
+	if (typeof tokenHostedDomain !== "string" || !tokenHostedDomain) {
+		return false;
+	}
+	if (configuredHostedDomain === "*") return true;
+	return tokenHostedDomain === configuredHostedDomain;
+};
+
 export const google = (options: GoogleOptions) => {
 	return {
 		id: "google",
@@ -133,38 +189,16 @@ export const google = (options: GoogleOptions) => {
 				return options.verifyIdToken(token, nonce);
 			}
 
-			// Verify JWT integrity
-			// See https://developers.google.com/identity/sign-in/web/backend-auth#verify-the-integrity-of-the-id-token
-
-			try {
-				const { kid, alg: jwtAlg } = decodeProtectedHeader(token);
-				if (!kid || !jwtAlg) return false;
-
-				const publicKey = await getGooglePublicKey(kid);
-				const { payload: jwtClaims } = await jwtVerify(token, publicKey, {
-					algorithms: [jwtAlg],
-					issuer: ["https://accounts.google.com", "accounts.google.com"],
-					audience: options.clientId,
-					maxTokenAge: "1h",
-				});
-
-				if (nonce && jwtClaims.nonce !== nonce) {
-					return false;
-				}
-
-				// Google's `hd` authorization parameter is only a UI hint and can
-				// be removed or changed by the user. When a hosted domain is
-				// configured, the `hd` claim in the verified id token is the
-				// authoritative value and must match, otherwise accounts outside
-				// the workspace domain would be accepted.
-				if (options.hd && jwtClaims.hd !== options.hd) {
-					return false;
-				}
-
-				return true;
-			} catch {
+			const jwtClaims = await verifyGoogleIdToken({
+				token,
+				audience: options.clientId,
+				nonce,
+			});
+			if (!jwtClaims) {
 				return false;
 			}
+
+			return isGoogleHostedDomainAllowed(options.hd, jwtClaims.hd);
 		},
 		async getUserInfo(token) {
 			if (options.getUserInfo) {
@@ -174,15 +208,14 @@ export const google = (options: GoogleOptions) => {
 				return null;
 			}
 			const user = decodeJwt(token.idToken) as GoogleProfile;
-			// Enforce the configured hosted domain on the callback profile path
-			// as well. The `hd` claim must be present and match, since the
-			// authorization-time `hd` hint does not restrict which account signs
-			// in.
-			if (options.hd && user.hd !== options.hd) {
+			// Enforce the configured hosted domain on the callback profile path.
+			// The authorization-time `hd` value is only a UI hint; the verified
+			// token/profile claim is the authoritative Workspace signal.
+			if (!isGoogleHostedDomainAllowed(options.hd, user.hd)) {
 				logger.error(
 					`Google sign-in rejected: id token hosted domain (hd) "${
 						user.hd ?? "<missing>"
-					}" does not match the configured "hd" option "${options.hd}".`,
+					}" does not satisfy the configured "hd" option "${options.hd}".`,
 				);
 				return null;
 			}

package/src/social-providers/paypal.ts

@@ -1,6 +1,6 @@
 import { base64 } from "@better-auth/utils/base64";
 import { betterFetch } from "@better-fetch/fetch";
-import { decodeProtectedHeader, importJWK, jwtVerify } from "jose";
+import { decodeJwt, decodeProtectedHeader, importJWK, jwtVerify } from "jose";
 import { logger } from "../env";
 import { APIError, BetterAuthError } from "../error";
 import type { OAuthProvider, ProviderOptions } from "../oauth2";
@@ -16,6 +16,7 @@ import { createAuthorizationURL } from "../oauth2";
 const PAYPAL_ID_TOKEN_ALGORITHMS = ["RS256", "HS256"] as const;
 
 export interface PayPalProfile {
+	sub?: string | undefined;
 	user_id: string;
 	name: string;
 	given_name: string;
@@ -298,6 +299,26 @@ export const paypal = (options: PayPalOptions) => {
 				}
 
 				const userInfo = response.data;
+				if (token.idToken) {
+					let idTokenSubject: string | undefined;
+					try {
+						idTokenSubject = decodeJwt(token.idToken).sub;
+					} catch (error) {
+						logger.error("Failed to decode PayPal ID token:", error);
+						return null;
+					}
+
+					// OIDC binds UserInfo to the ID Token with `sub`. Keep `user_id`
+					// as the account id below for existing PayPal account mappings.
+					const userInfoSubject = userInfo.sub ?? userInfo.user_id;
+					if (!idTokenSubject || userInfoSubject !== idTokenSubject) {
+						logger.error(
+							"PayPal user info subject does not match ID token subject",
+						);
+						return null;
+					}
+				}
+
 				const userMap = await options.mapProfileToUser?.(userInfo);
 
 				const result = {

package/src/types/init-options.ts

@@ -223,7 +223,7 @@ export type BetterAuthAdvancedOptions = {
 				 * @example ["x-client-ip", "x-forwarded-for", "cf-connecting-ip"]
 				 *
 				 * @default
-				 * @link https://github.com/better-auth/better-auth/blob/main/packages/better-auth/src/utils/get-request-ip.ts#L8
+				 * @link https://github.com/better-auth/better-auth/blob/main/packages/core/src/utils/ip.ts
 				 */
 				ipAddressHeaders?: string[];
 				/**
@@ -240,6 +240,21 @@ export type BetterAuthAdvancedOptions = {
 				 * @default 64
 				 */
 				ipv6Subnet?: number;
+				/**
+				 * Trusted reverse-proxy IPs or CIDR ranges. When set, a forwarded IP
+				 * chain is walked right to left, trusted hops are skipped, and the
+				 * first untrusted address is the client IP. Unset trusts only
+				 * single-value IP headers. Use the actual address or subnet of your
+				 * proxies, not a broad private range that also covers clients.
+				 *
+				 * This only interprets the forwarded header chain and cannot verify
+				 * the direct sender. It is safe only when your origin is reachable
+				 * through these proxies and clients cannot set forwarded headers
+				 * directly.
+				 *
+				 * @example ["192.0.2.10", "10.0.0.0/24"]
+				 */
+				trustedProxies?: string[];
 		  }
 		| undefined;
 	/**

package/src/utils/ip.ts

@@ -1,4 +1,6 @@
 import * as z from "zod";
+import { isDevelopment, isTest } from "../env";
+import type { BetterAuthOptions } from "../types";
 
 /**
  * Normalizes an IP address for consistent rate limiting.
@@ -195,6 +197,189 @@ export function normalizeIP(
 	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