@better-auth/core 1.6.19 → 1.6.21

package/dist/context/global.mjs

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

package/dist/db/adapter/factory.mjs

@@ -459,6 +459,7 @@ const createAdapterFactory = ({ adapter: customAdapter, config: cfg }) => (optio
 				where: unsafeWhere,
 				action: "update"
 			});
+			if (where.length === 0) return null;
 			debugLog({ method: "update" }, `${formatTransactionId(thisTransactionId)} ${formatStep(1, 4)}`, `${formatMethod("update")} ${formatAction("Unsafe Input")}:`, {
 				model,
 				data: unsafeData

package/dist/db/adapter/index.d.mts

@@ -396,8 +396,14 @@ 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/dist/db/get-tables.mjs

@@ -8,7 +8,8 @@ const getAuthTables = (options) => {
 				...acc[key]?.fields,
 				...value.fields
 			},
-			modelName: value.modelName || key
+			modelName: value.modelName || key,
+			disableMigrations: value.disableMigration ?? acc[key]?.disableMigrations
 		};
 		return acc;
 	}, {});

package/dist/error/index.d.mts

@@ -7,7 +7,14 @@ declare class BetterAuthError extends Error {
     cause?: unknown | undefined;
   });
 }
+type BaseAPIErrorInstance = InstanceType<typeof APIError$1>;
 declare class APIError extends APIError$1 {
+  status: BaseAPIErrorInstance["status"];
+  body: BaseAPIErrorInstance["body"];
+  headers: BaseAPIErrorInstance["headers"];
+  statusCode: BaseAPIErrorInstance["statusCode"];
+  message: string;
+  errorStack: BaseAPIErrorInstance["errorStack"];
   constructor(...args: ConstructorParameters<typeof APIError$1>);
   static fromStatus(status: ConstructorParameters<typeof APIError$1>[0], body?: ConstructorParameters<typeof APIError$1>[1]): APIError;
   static from(status: ConstructorParameters<typeof APIError$1>[0], error: {

package/dist/instrumentation/tracer.mjs

@@ -2,7 +2,7 @@ import { ATTR_HTTP_RESPONSE_STATUS_CODE } from "./attributes.mjs";
 import { getOpenTelemetryAPI } from "./api.mjs";
 //#region src/instrumentation/tracer.ts
 const INSTRUMENTATION_SCOPE = "better-auth";
-const INSTRUMENTATION_VERSION = "1.6.19";
+const INSTRUMENTATION_VERSION = "1.6.21";
 /**
 * Better-auth uses `throw ctx.redirect(url)` for flow control (e.g. OAuth
 * callbacks). These are APIErrors with 3xx status codes and should not be

package/dist/social-providers/google.d.mts

@@ -1,4 +1,6 @@
 import { OAuth2Tokens, ProviderOptions } from "../oauth2/oauth-provider.mjs";
+import { JWTPayload } from "jose";
+
 //#region src/social-providers/google.d.ts
 interface GoogleProfile {
   aud: string;
@@ -41,11 +43,30 @@ 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;
 }
+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.
+ */
+declare const verifyGoogleIdToken: ({
+  token,
+  audience,
+  nonce
+}: VerifyGoogleIdTokenOptions) => Promise<JWTPayload | null>;
+/**
+ * Checks whether Google's verified `hd` claim satisfies the configured hosted
+ * domain restriction. `hd: "*"` accepts any Google Workspace hosted domain.
+ */
+declare const isGoogleHostedDomainAllowed: (configuredHostedDomain: string | undefined, tokenHostedDomain: unknown) => boolean;
 declare const google: (options: GoogleOptions) => {
   id: "google";
   name: string;
@@ -99,4 +120,4 @@ declare const google: (options: GoogleOptions) => {
 };
 declare const getGooglePublicKey: (kid: string) => Promise<Uint8Array<ArrayBufferLike> | CryptoKey>;
 //#endregion
-export { GoogleOptions, GoogleProfile, getGooglePublicKey, google };
+export { GoogleOptions, GoogleProfile, VerifyGoogleIdTokenOptions, getGooglePublicKey, google, isGoogleHostedDomainAllowed, verifyGoogleIdToken };

package/dist/social-providers/google.mjs

@@ -7,6 +7,37 @@ import { validateAuthorizationCode } from "../oauth2/validate-authorization-code
 import { betterFetch } from "@better-fetch/fetch";
 import { decodeJwt, decodeProtectedHeader, importJWK, jwtVerify } from "jose";
 //#region src/social-providers/google.ts
+const GOOGLE_ID_TOKEN_MAX_AGE = "1h";
+/**
+* Verifies a Google ID token against Google's issuer, audience, signature,
+* expiry, and maximum token age.
+*/
+const verifyGoogleIdToken = async ({ token, audience, nonce }) => {
+	try {
+		const { kid, alg: jwtAlg } = decodeProtectedHeader(token);
+		if (!kid || !jwtAlg) return null;
+		const { payload: jwtClaims } = await jwtVerify(token, await getGooglePublicKey(kid), {
+			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.
+*/
+const isGoogleHostedDomainAllowed = (configuredHostedDomain, tokenHostedDomain) => {
+	if (!configuredHostedDomain) return true;
+	if (typeof tokenHostedDomain !== "string" || !tokenHostedDomain) return false;
+	if (configuredHostedDomain === "*") return true;
+	return tokenHostedDomain === configuredHostedDomain;
+};
 const google = (options) => {
 	return {
 		id: "google",
@@ -63,28 +94,20 @@ const google = (options) => {
 		async verifyIdToken(token, nonce) {
 			if (options.disableIdTokenSignIn) return false;
 			if (options.verifyIdToken) return options.verifyIdToken(token, nonce);
-			try {
-				const { kid, alg: jwtAlg } = decodeProtectedHeader(token);
-				if (!kid || !jwtAlg) return false;
-				const { payload: jwtClaims } = await jwtVerify(token, await getGooglePublicKey(kid), {
-					algorithms: [jwtAlg],
-					issuer: ["https://accounts.google.com", "accounts.google.com"],
-					audience: options.clientId,
-					maxTokenAge: "1h"
-				});
-				if (nonce && jwtClaims.nonce !== nonce) return false;
-				if (options.hd && jwtClaims.hd !== options.hd) return false;
-				return true;
-			} catch {
-				return false;
-			}
+			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) return options.getUserInfo(token);
 			if (!token.idToken) return null;
 			const user = decodeJwt(token.idToken);
-			if (options.hd && user.hd !== options.hd) {
-				logger.error(`Google sign-in rejected: id token hosted domain (hd) "${user.hd ?? "<missing>"}" does not match the configured "hd" option "${options.hd}".`);
+			if (!isGoogleHostedDomainAllowed(options.hd, user.hd)) {
+				logger.error(`Google sign-in rejected: id token hosted domain (hd) "${user.hd ?? "<missing>"}" does not satisfy the configured "hd" option "${options.hd}".`);
 				return null;
 			}
 			const userMap = await options.mapProfileToUser?.(user);
@@ -111,4 +134,4 @@ const getGooglePublicKey = async (kid) => {
 	return await importJWK(jwk, jwk.alg);
 };
 //#endregion
-export { getGooglePublicKey, google };
+export { getGooglePublicKey, google, isGoogleHostedDomainAllowed, verifyGoogleIdToken };

package/dist/social-providers/index.d.mts

@@ -6,7 +6,7 @@ import { FacebookOptions, FacebookProfile, facebook } from "./facebook.mjs";
 import { FigmaOptions, FigmaProfile, figma } from "./figma.mjs";
 import { GithubOptions, GithubProfile, github } from "./github.mjs";
 import { MicrosoftEntraIDProfile, MicrosoftOptions, getMicrosoftPublicKey, microsoft } from "./microsoft-entra-id.mjs";
-import { GoogleOptions, GoogleProfile, getGooglePublicKey, google } from "./google.mjs";
+import { GoogleOptions, GoogleProfile, VerifyGoogleIdTokenOptions, getGooglePublicKey, google, isGoogleHostedDomainAllowed, verifyGoogleIdToken } from "./google.mjs";
 import { HuggingFaceOptions, HuggingFaceProfile, huggingface } from "./huggingface.mjs";
 import { SlackOptions, SlackProfile, slack } from "./slack.mjs";
 import { SpotifyOptions, SpotifyProfile, spotify } from "./spotify.mjs";
@@ -1831,4 +1831,4 @@ type SocialProviders = { [K in SocialProviderList[number]]?: AwaitableFunction<P
 }> };
 type SocialProviderList = typeof socialProviderList;
 //#endregion
-export { AccountStatus, AppleNonConformUser, AppleOptions, AppleProfile, AtlassianOptions, AtlassianProfile, CognitoOptions, CognitoProfile, DiscordOptions, DiscordProfile, DropboxOptions, DropboxProfile, FacebookOptions, FacebookProfile, FigmaOptions, FigmaProfile, GithubOptions, GithubProfile, GitlabOptions, GitlabProfile, GoogleOptions, GoogleProfile, HuggingFaceOptions, HuggingFaceProfile, KakaoOptions, KakaoProfile, KickOptions, KickProfile, LineIdTokenPayload, LineOptions, LineUserInfo, LinearOptions, LinearProfile, LinearUser, LinkedInOptions, LinkedInProfile, LoginType, MicrosoftEntraIDProfile, MicrosoftOptions, NaverOptions, NaverProfile, NotionOptions, NotionProfile, PayPalOptions, PayPalProfile, PayPalTokenResponse, PaybinOptions, PaybinProfile, PhoneNumber, PolarOptions, PolarProfile, PronounOption, RailwayOptions, RailwayProfile, RedditOptions, RedditProfile, RobloxOptions, RobloxProfile, SalesforceOptions, SalesforceProfile, SlackOptions, SlackProfile, SocialProvider, SocialProviderList, SocialProviderListEnum, SocialProviders, SpotifyOptions, SpotifyProfile, TiktokOptions, TiktokProfile, TwitchOptions, TwitchProfile, TwitterOption, TwitterProfile, VercelOptions, VercelProfile, VkOption, VkProfile, WeChatOptions, WeChatProfile, ZoomOptions, ZoomProfile, apple, atlassian, cognito, discord, dropbox, facebook, figma, getApplePublicKey, getCognitoPublicKey, getGooglePublicKey, getMicrosoftPublicKey, getPayPalPublicKey, github, gitlab, google, huggingface, kakao, kick, line, linear, linkedin, microsoft, naver, notion, paybin, paypal, polar, railway, reddit, roblox, salesforce, slack, socialProviderList, socialProviders, spotify, tiktok, twitch, twitter, vercel, vk, wechat, zoom };
+export { AccountStatus, AppleNonConformUser, AppleOptions, AppleProfile, AtlassianOptions, AtlassianProfile, CognitoOptions, CognitoProfile, DiscordOptions, DiscordProfile, DropboxOptions, DropboxProfile, FacebookOptions, FacebookProfile, FigmaOptions, FigmaProfile, GithubOptions, GithubProfile, GitlabOptions, GitlabProfile, GoogleOptions, GoogleProfile, HuggingFaceOptions, HuggingFaceProfile, KakaoOptions, KakaoProfile, KickOptions, KickProfile, LineIdTokenPayload, LineOptions, LineUserInfo, LinearOptions, LinearProfile, LinearUser, LinkedInOptions, LinkedInProfile, LoginType, MicrosoftEntraIDProfile, MicrosoftOptions, NaverOptions, NaverProfile, NotionOptions, NotionProfile, PayPalOptions, PayPalProfile, PayPalTokenResponse, PaybinOptions, PaybinProfile, PhoneNumber, PolarOptions, PolarProfile, PronounOption, RailwayOptions, RailwayProfile, RedditOptions, RedditProfile, RobloxOptions, RobloxProfile, SalesforceOptions, SalesforceProfile, SlackOptions, SlackProfile, SocialProvider, SocialProviderList, SocialProviderListEnum, SocialProviders, SpotifyOptions, SpotifyProfile, TiktokOptions, TiktokProfile, TwitchOptions, TwitchProfile, TwitterOption, TwitterProfile, VercelOptions, VercelProfile, VerifyGoogleIdTokenOptions, VkOption, VkProfile, WeChatOptions, WeChatProfile, ZoomOptions, ZoomProfile, apple, atlassian, cognito, discord, dropbox, facebook, figma, getApplePublicKey, getCognitoPublicKey, getGooglePublicKey, getMicrosoftPublicKey, getPayPalPublicKey, github, gitlab, google, huggingface, isGoogleHostedDomainAllowed, kakao, kick, line, linear, linkedin, microsoft, naver, notion, paybin, paypal, polar, railway, reddit, roblox, salesforce, slack, socialProviderList, socialProviders, spotify, tiktok, twitch, twitter, vercel, verifyGoogleIdToken, vk, wechat, zoom };

package/dist/social-providers/index.mjs

@@ -7,7 +7,7 @@ import { facebook } from "./facebook.mjs";
 import { figma } from "./figma.mjs";
 import { github } from "./github.mjs";
 import { gitlab } from "./gitlab.mjs";
-import { getGooglePublicKey, google } from "./google.mjs";
+import { getGooglePublicKey, google, isGoogleHostedDomainAllowed, verifyGoogleIdToken } from "./google.mjs";
 import { huggingface } from "./huggingface.mjs";
 import { kakao } from "./kakao.mjs";
 import { kick } from "./kick.mjs";
@@ -75,4 +75,4 @@ const socialProviders = {
 const socialProviderList = Object.keys(socialProviders);
 const SocialProviderListEnum = z.enum(socialProviderList).or(z.string());
 //#endregion
-export { SocialProviderListEnum, apple, atlassian, cognito, discord, dropbox, facebook, figma, getApplePublicKey, getCognitoPublicKey, getGooglePublicKey, getMicrosoftPublicKey, getPayPalPublicKey, github, gitlab, google, huggingface, kakao, kick, line, linear, linkedin, microsoft, naver, notion, paybin, paypal, polar, railway, reddit, roblox, salesforce, slack, socialProviderList, socialProviders, spotify, tiktok, twitch, twitter, vercel, vk, wechat, zoom };
+export { SocialProviderListEnum, apple, atlassian, cognito, discord, dropbox, facebook, figma, getApplePublicKey, getCognitoPublicKey, getGooglePublicKey, getMicrosoftPublicKey, getPayPalPublicKey, github, gitlab, google, huggingface, isGoogleHostedDomainAllowed, kakao, kick, line, linear, linkedin, microsoft, naver, notion, paybin, paypal, polar, railway, reddit, roblox, salesforce, slack, socialProviderList, socialProviders, spotify, tiktok, twitch, twitter, vercel, verifyGoogleIdToken, vk, wechat, zoom };

package/dist/social-providers/paypal.d.mts

@@ -1,6 +1,7 @@
 import { OAuth2Tokens, ProviderOptions } from "../oauth2/oauth-provider.mjs";
 //#region src/social-providers/paypal.d.ts
 interface PayPalProfile {
+  sub?: string | undefined;
   user_id: string;
   name: string;
   given_name: string;

package/dist/social-providers/paypal.mjs

@@ -3,7 +3,7 @@ import { logger } from "../env/logger.mjs";
 import { createAuthorizationURL } from "../oauth2/create-authorization-url.mjs";
 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";
 //#region src/social-providers/paypal.ts
 /**
 * ID token signing algorithms advertised by PayPal's OpenID configuration.
@@ -143,6 +143,20 @@ const paypal = (options) => {
 					return null;
 				}
 				const userInfo = response.data;
+				if (token.idToken) {
+					let idTokenSubject;
+					try {
+						idTokenSubject = decodeJwt(token.idToken).sub;
+					} catch (error) {
+						logger.error("Failed to decode PayPal ID token:", error);
+						return null;
+					}
+					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);
 				return {
 					user: {

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

@@ -176,7 +176,7 @@ 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[];
     /**
@@ -193,6 +193,21 @@ 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;
   /**
    * Force cookies to always use the `Secure` attribute. By default,

package/dist/utils/ip.d.mts

@@ -1,3 +1,4 @@
+import { BetterAuthOptions } from "../types/init-options.mjs";
 //#region src/utils/ip.d.ts
 /**
  * Normalizes an IP address for consistent rate limiting.
@@ -42,6 +43,27 @@ declare function isValidIP(ip: string): boolean;
  * // -> "2001:0db8:0000:0000:0000:0000:0000:0000" (subnet /64)
  */
 declare function normalizeIP(ip: string, options?: NormalizeIPOptions): string;
+/**
+ * Trusted-proxy entries that are not a valid IP address or CIDR range.
+ */
+declare function findInvalidTrustedProxies(entries: string[]): string[];
+/**
+ * Resolves the client IP from a forwarded header. The leftmost token is spoofable,
+ * so with `trustedProxies` the chain is stripped from the right to the first
+ * untrusted hop. Otherwise only a single-value header is trusted. Returns `null`
+ * when no trustworthy client IP can be resolved.
+ */
+declare function getIPFromHeader(value: string, options?: {
+  ipv6Subnet?: number;
+  trustedProxies?: string[];
+}): string | null;
+/**
+ * Resolves the client IP for a request from the configured IP headers.
+ * Honors `disableIpTracking`, walks `ipAddressHeaders` in order (default
+ * `x-forwarded-for`), and falls back to localhost in development and test.
+ * Returns `null` when tracking is disabled or no trustworthy IP can be resolved.
+ */
+declare function getIp(req: Request | Headers, options: BetterAuthOptions): string | null;
 /**
  * Creates a rate limit key from IP and path
  * Uses a separator to prevent collision attacks
@@ -52,4 +74,4 @@ declare function normalizeIP(ip: string, options?: NormalizeIPOptions): string;
  */
 declare function createRateLimitKey(ip: string, path: string): string;
 //#endregion
-export { createRateLimitKey, isValidIP, normalizeIP };
+export { createRateLimitKey, findInvalidTrustedProxies, getIPFromHeader, getIp, isValidIP, normalizeIP };

package/dist/utils/ip.mjs

@@ -1,3 +1,4 @@
+import { isDevelopment, isTest } from "../env/env-impl.mjs";
 import * as z from "zod";
 //#region src/utils/ip.ts
 /**
@@ -102,6 +103,119 @@ function normalizeIP(ip, options = {}) {
 	return normalizeIPv6(ip, options.ipv6Subnet ?? 64);
 }
 /**
+* Raw bytes of an IP for CIDR comparison. Returns `null` for an invalid IP.
+*/
+function ipToBytes(ip) {
+	if (z.ipv4().safeParse(ip).success) return Uint8Array.from(ip.split(".").map((octet) => Number(octet)));
+	if (!isIPv6(ip)) return null;
+	const mapped = extractIPv4FromMapped(ip);
+	if (mapped) return Uint8Array.from(mapped.split(".").map((octet) => Number(octet)));
+	const groups = expandIPv6(ip);
+	const bytes = new Uint8Array(16);
+	for (let i = 0; i < 8; i++) {
+		const group = Number.parseInt(groups[i] ?? "0", 16);
+		bytes[i * 2] = group >> 8 & 255;
+		bytes[i * 2 + 1] = group & 255;
+	}
+	return bytes;
+}
+const CIDR_PREFIX_PATTERN = /^\d+$/;
+/**
+* Parses an IP or `IP/prefix` string into network bytes and a prefix length.
+* The prefix must be digits only and within the address family. `null` if the
+* value is not a valid IP or CIDR range, which keeps a malformed entry from
+* silently behaving like a non-match.
+*/
+function parseCIDR(value) {
+	const slash = value.lastIndexOf("/");
+	const bytes = ipToBytes(slash === -1 ? value : value.slice(0, slash));
+	if (!bytes) return null;
+	const maxBits = bytes.length * 8;
+	if (slash === -1) return {
+		bytes,
+		prefix: maxBits
+	};
+	const prefixPart = value.slice(slash + 1);
+	if (!CIDR_PREFIX_PATTERN.test(prefixPart)) return null;
+	const prefix = Number(prefixPart);
+	return prefix <= maxBits ? {
+		bytes,
+		prefix
+	} : null;
+}
+/**
+* Whether `ipBytes` falls inside an already-parsed CIDR network.
+*/
+function matchesCIDR(ipBytes, net) {
+	if (ipBytes.length !== net.bytes.length) return false;
+	let bitsRemaining = net.prefix;
+	for (let i = 0; i < ipBytes.length && bitsRemaining > 0; i++) {
+		const take = bitsRemaining >= 8 ? 8 : bitsRemaining;
+		const mask = take === 8 ? 255 : 255 << 8 - take & 255;
+		if (((ipBytes[i] ?? 0) & mask) !== ((net.bytes[i] ?? 0) & mask)) return false;
+		bitsRemaining -= 8;
+	}
+	return true;
+}
+/**
+* Trusted-proxy entries that are not a valid IP address or CIDR range.
+*/
+function findInvalidTrustedProxies(entries) {
+	return entries.filter((entry) => parseCIDR(entry) === null);
+}
+/**
+* Resolves the client IP from a forwarded header. The leftmost token is spoofable,
+* so with `trustedProxies` the chain is stripped from the right to the first
+* untrusted hop. Otherwise only a single-value header is trusted. Returns `null`
+* when no trustworthy client IP can be resolved.
+*/
+function getIPFromHeader(value, options = {}) {
+	const forwardedIps = value.split(",").map((ip) => ip.trim()).filter(Boolean);
+	if (forwardedIps.length === 0) return null;
+	const trustedProxies = (options.trustedProxies ?? []).map(parseCIDR).filter((proxy) => {
+		return proxy !== null;
+	});
+	if (trustedProxies.length > 0) {
+		for (let i = forwardedIps.length - 1; i >= 0; i--) {
+			const ip = forwardedIps[i];
+			const ipBytes = ip ? ipToBytes(ip) : null;
+			if (!ip || !ipBytes) return null;
+			if (trustedProxies.some((proxy) => matchesCIDR(ipBytes, proxy))) continue;
+			return normalizeIP(ip, { ipv6Subnet: options.ipv6Subnet });
+		}
+		return null;
+	}
+	if (forwardedIps.length !== 1) return null;
+	const selectedIp = forwardedIps[0];
+	if (!selectedIp || !isValidIP(selectedIp)) return null;
+	return normalizeIP(selectedIp, { ipv6Subnet: options.ipv6Subnet });
+}
+const LOCALHOST_IP = "127.0.0.1";
+const DEFAULT_IP_HEADERS = ["x-forwarded-for"];
+/**
+* Resolves the client IP for a request from the configured IP headers.
+* Honors `disableIpTracking`, walks `ipAddressHeaders` in order (default
+* `x-forwarded-for`), and falls back to localhost in development and test.
+* Returns `null` when tracking is disabled or no trustworthy IP can be resolved.
+*/
+function getIp(req, options) {
+	if (options.advanced?.ipAddress?.disableIpTracking) return null;
+	const headers = "headers" in req ? req.headers : req;
+	const ipHeaders = options.advanced?.ipAddress?.ipAddressHeaders || DEFAULT_IP_HEADERS;
+	for (const key of ipHeaders) {
+		const value = "get" in headers ? headers.get(key) : headers[key];
+		if (typeof value === "string") {
+			const ip = getIPFromHeader(value, {
+				ipv6Subnet: options.advanced?.ipAddress?.ipv6Subnet,
+				trustedProxies: options.advanced?.ipAddress?.trustedProxies
+			});
+			if (ip) return ip;
+		}
+	}
+	if (isTest() || isDevelopment()) return LOCALHOST_IP;
+	return null;
+}
+/**
 * Creates a rate limit key from IP and path
 * Uses a separator to prevent collision attacks
 *
@@ -113,4 +227,4 @@ function createRateLimitKey(ip, path) {
 	return `${ip}|${path}`;
 }
 //#endregion
-export { createRateLimitKey, isValidIP, normalizeIP };
+export { createRateLimitKey, findInvalidTrustedProxies, getIPFromHeader, getIp, isValidIP, normalizeIP };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/core",
-  "version": "1.6.19",
+  "version": "1.6.21",
   "description": "The most comprehensive authentication framework for TypeScript.",
   "type": "module",
   "license": "MIT",
@@ -157,7 +157,7 @@
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/sdk-trace-base": "^1.30.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",
-    "better-call": "1.3.6",
+    "better-call": "1.3.7",
     "@cloudflare/workers-types": "^4.20250121.0",
     "jose": "^6.1.3",
     "kysely": "^0.28.17 || ^0.29.0",
@@ -168,7 +168,7 @@
     "@better-auth/utils": "0.4.2",
     "@better-fetch/fetch": "1.3.1",
     "@opentelemetry/api": "^1.9.0",
-    "better-call": "1.3.6",
+    "better-call": "1.3.7",
     "@cloudflare/workers-types": ">=4",
     "jose": "^6.1.0",
     "kysely": "^0.28.5 || ^0.29.0",

package/src/db/adapter/factory.ts

@@ -967,6 +967,11 @@ export const createAdapterFactory =
 					where: unsafeWhere,
 					action: "update",
 				});
+				// `update` targets a single row. Empty predicates have no
+				// target, so fail closed and leave bulk writes to `updateMany`.
+				if (where.length === 0) {
+					return null;
+				}
 				debugLog(
 					{ method: "update" },
 					`${formatTransactionId(thisTransactionId)} ${formatStep(1, 4)}`,

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/error/index.ts

@@ -11,7 +11,16 @@ export class BetterAuthError extends Error {
 
 export { type APIErrorCode, BASE_ERROR_CODES } from "./codes";
 
+type BaseAPIErrorInstance = InstanceType<typeof BaseAPIError>;
+
 export class APIError extends BaseAPIError {
+	declare status: BaseAPIErrorInstance["status"];
+	declare body: BaseAPIErrorInstance["body"];
+	declare headers: BaseAPIErrorInstance["headers"];
+	declare statusCode: BaseAPIErrorInstance["statusCode"];
+	declare message: string;
+	declare errorStack: BaseAPIErrorInstance["errorStack"];
+
 	constructor(...args: ConstructorParameters<typeof BaseAPIError>) {
 		super(...args);
 	}

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