@better-auth/core 1.7.0-beta.8 → 1.7.0-rc.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/core",
-  "version": "1.7.0-beta.8",
+  "version": "1.7.0-rc.0",
   "description": "The most comprehensive authentication framework for TypeScript.",
   "type": "module",
   "license": "MIT",
@@ -147,29 +147,29 @@
     }
   },
   "dependencies": {
-    "@opentelemetry/semantic-conventions": "^1.39.0",
+    "@opentelemetry/semantic-conventions": "^1.41.1",
     "@standard-schema/spec": "^1.1.0",
     "zod": "^4.3.6"
   },
   "devDependencies": {
     "@better-auth/utils": "0.4.2",
     "@better-fetch/fetch": "1.3.1",
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/sdk-trace-base": "^1.30.0",
-    "@opentelemetry/sdk-trace-node": "^1.30.0",
-    "better-call": "1.3.6",
     "@cloudflare/workers-types": "^4.20250121.0",
-    "jose": "^6.1.3",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/sdk-trace-base": "^2.8.0",
+    "@opentelemetry/sdk-trace-node": "^2.8.0",
+    "better-call": "1.3.7",
+    "jose": "^6.2.3",
     "kysely": "^0.28.17 || ^0.29.0",
-    "nanostores": "^1.1.1",
+    "nanostores": "^1.3.0",
     "tsdown": "0.21.1"
   },
   "peerDependencies": {
     "@better-auth/utils": "0.4.2",
     "@better-fetch/fetch": "1.3.1",
-    "@opentelemetry/api": "^1.9.0",
-    "better-call": "1.3.6",
     "@cloudflare/workers-types": ">=4",
+    "@opentelemetry/api": "^1.9.0",
+    "better-call": "1.3.7",
     "jose": "^6.1.0",
     "kysely": "^0.28.5 || ^0.29.0",
     "nanostores": "^1.0.1"

package/src/db/adapter/factory.ts

@@ -29,15 +29,15 @@ import type {
 } from "./types";
 import { withApplyDefault } from "./utils";
 
+export * from "./types";
 export {
-	initGetDefaultModelName,
 	initGetDefaultFieldName,
-	initGetModelName,
-	initGetFieldName,
+	initGetDefaultModelName,
 	initGetFieldAttributes,
+	initGetFieldName,
 	initGetIdField,
+	initGetModelName,
 };
-export * from "./types";
 
 let debugLogs: { instance: string; args: any[] }[] = [];
 let transactionId = -1;
@@ -963,6 +963,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/oauth2/client-credentials-token.ts

@@ -1,6 +1,6 @@
-import { betterFetch } from "@better-fetch/fetch";
 import type { AwaitableFunction } from "../types";
 import type { OAuth2Tokens, ProviderOptions } from "./oauth-provider";
+import { fetchRefusingRedirects } from "./reject-redirects";
 import type {
 	TokenEndpointAuth,
 	TokenEndpointSecretAuthentication,
@@ -109,7 +109,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,6 +1,6 @@
-import { betterFetch } from "@better-fetch/fetch";
 import type { AwaitableFunction } from "../types";
 import type { OAuth2Tokens, ProviderOptions } from "./oauth-provider";
+import { fetchRefusingRedirects } from "./reject-redirects";
 import type {
 	TokenEndpointAuth,
 	TokenEndpointSecretAuthentication,
@@ -138,7 +138,7 @@ export async function refreshAccessToken({
 		resource,
 	});
 
-	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,75 @@
+// cspell:ignore workerd
+import type { BetterFetchOption } from "@better-fetch/fetch";
+import { betterFetch } from "@better-fetch/fetch";
+import { BetterAuthError } from "../error";
+
+const httpRedirectStatuses = 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" ||
+		httpRedirectStatuses.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 noFollowRedirect = { 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 onError = options?.onError;
+	const result = await betterFetch<T>(url, {
+		...options,
+		...noFollowRedirect,
+		async onError(context) {
+			if (isRedirectResponse(context.response)) redirected = true;
+			await onError?.(context);
+		},
+	}).catch((error) => {
+		if (redirected) throw redirectRefused(url);
+		throw error;
+	});
+	if (redirected) throw redirectRefused(url);
+	return result;
+}

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

@@ -1,8 +1,12 @@
-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,
+	noFollowRedirect,
+} from "./reject-redirects";
 import type {
 	TokenEndpointAuth,
 	TokenEndpointSecretAuthentication,
@@ -145,7 +149,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,
@@ -165,7 +169,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, ...noFollowRedirect });
+			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,
@@ -23,6 +22,7 @@ import {
 	isDpopBindingError,
 	parseAccessTokenAuthorization,
 } from "./dpop";
+import { fetchRefusingRedirects } from "./reject-redirects";
 
 const joseInfrastructureErrorCodes = new Set([
 	joseErrors.JWKSTimeout.code,
@@ -115,7 +115,7 @@ async function fetchJwks(
 ): Promise<JSONWebKeySet> {
 	const jwks =
 		typeof jwksFetch === "string"
-			? await betterFetch<JSONWebKeySet>(jwksFetch, {
+			? await fetchRefusingRedirects<JSONWebKeySet>(jwksFetch, {
 					headers: {
 						Accept: "application/json",
 					},
@@ -384,23 +384,24 @@ async function verifyAccessTokenPayload(
 
 	// 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,5 +1,6 @@
 import { betterFetch } from "@better-fetch/fetch";
-import { decodeJwt, importJWK } from "jose";
+import type { JWTPayload } from "jose";
+import { decodeJwt, decodeProtectedHeader, importJWK, jwtVerify } from "jose";
 import { logger } from "../env";
 import { APIError, BetterAuthError } from "../error";
 import type { OAuthProvider, ProviderOptions } from "../oauth2";
@@ -52,8 +53,8 @@ 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;
 	/**
@@ -69,6 +70,82 @@ export interface GoogleOptions extends ProviderOptions<GoogleProfile> {
 	includeGrantedScopes?: boolean | undefined;
 }
 
+const GOOGLE_ID_TOKEN_MAX_AGE = "1h";
+const GOOGLE_ID_TOKEN_ALGORITHM = "RS256";
+type GoogleIdTokenAlgorithm = typeof GOOGLE_ID_TOKEN_ALGORITHM;
+const GOOGLE_ID_TOKEN_ALGORITHMS: GoogleIdTokenAlgorithm[] = [
+	GOOGLE_ID_TOKEN_ALGORITHM,
+];
+
+function isGoogleIdTokenAlgorithm(
+	algorithm: unknown,
+): algorithm is GoogleIdTokenAlgorithm {
+	return GOOGLE_ID_TOKEN_ALGORITHMS.includes(
+		algorithm as GoogleIdTokenAlgorithm,
+	);
+}
+
+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 } = decodeProtectedHeader(token);
+		if (!isGoogleIdTokenAlgorithm(alg)) return null;
+
+		const publicKeys = await getGooglePublicKeys(kid);
+		for (const publicKey of publicKeys) {
+			try {
+				const { payload: jwtClaims } = await jwtVerify(token, publicKey, {
+					algorithms: GOOGLE_ID_TOKEN_ALGORITHMS,
+					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 {
+				continue;
+			}
+		}
+
+		return null;
+	} 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",
@@ -145,14 +222,14 @@ export const google = (options: GoogleOptions) => {
 			jwks: (header) => getGooglePublicKey(header.kid!),
 			issuer: ["https://accounts.google.com", "accounts.google.com"],
 			audience: options.clientId,
-			maxTokenAge: "1h",
+			maxTokenAge: GOOGLE_ID_TOKEN_MAX_AGE,
 			// 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 on the id_token sign-in path.
+			// and must satisfy the configured restriction, otherwise accounts
+			// outside the workspace domain would be accepted on the id_token path.
 			verifyClaims: options.hd
-				? (claims) => claims.hd === options.hd
+				? (claims) => isGoogleHostedDomainAllowed(options.hd, claims.hd)
 				: undefined,
 		},
 		async getUserInfo(token) {
@@ -163,15 +240,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;
 			}
@@ -193,10 +269,18 @@ export const google = (options: GoogleOptions) => {
 };
 
 export const getGooglePublicKey = async (kid: string) => {
+	const [publicKey] = await getGooglePublicKeys(kid);
+	if (!publicKey) {
+		throw new Error(`JWK with kid ${kid} not found`);
+	}
+	return publicKey;
+};
+
+const getGooglePublicKeys = async (kid?: string) => {
 	const { data } = await betterFetch<{
 		keys: Array<{
 			kid: string;
-			alg: string;
+			alg?: string;
 			kty: string;
 			use: string;
 			n: string;
@@ -210,10 +294,12 @@ export const getGooglePublicKey = async (kid: string) => {
 		});
 	}
 
-	const jwk = data.keys.find((key) => key.kid === kid);
-	if (!jwk) {
+	const jwks = kid ? data.keys.filter((key) => key.kid === kid) : data.keys;
+	if (!jwks.length) {
 		throw new Error(`JWK with kid ${kid} not found`);
 	}
 
-	return await importJWK(jwk, jwk.alg);
+	return Promise.all(
+		jwks.map((jwk) => importJWK(jwk, GOOGLE_ID_TOKEN_ALGORITHM)),
+	);
 };

package/src/social-providers/paypal.ts

@@ -1,11 +1,13 @@
 import { base64 } from "@better-auth/utils/base64";
 import { betterFetch } from "@better-fetch/fetch";
+import { decodeJwt } from "jose";
 import { logger } from "../env";
 import { BetterAuthError } from "../error";
 import type { OAuthProvider, ProviderOptions } from "../oauth2";
 import { createAuthorizationURL } from "../oauth2";
 
 export interface PayPalProfile {
+	sub?: string | undefined;
 	user_id: string;
 	name: string;
 	given_name: string;
@@ -226,6 +228,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

@@ -303,7 +303,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[];
 				/**
@@ -320,6 +320,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;
 	/**