@better-auth/core 1.7.0-beta.0 → 1.7.0-beta.10

package/src/types/context.ts

@@ -16,6 +16,7 @@ import type { Awaitable, LiteralString } from "./helper";
 import type {
 	BetterAuthOptions,
 	BetterAuthRateLimitOptions,
+	UserProvisioningSource,
 } from "./init-options";
 import type { BetterAuthPlugin } from "./plugin";
 import type { SecretConfig } from "./secret";
@@ -97,6 +98,11 @@ export interface InternalAdapter<
 		user: Omit<User, "id" | "createdAt" | "updatedAt" | "emailVerified"> &
 			Partial<User> &
 			Record<string, any>,
+		/**
+		 * Provisioning source. The creation seam adds `action: "create-user"` and
+		 * runs the `user.validateUserInfo` gate.
+		 */
+		source: UserProvisioningSource,
 	): Promise<T & User>;
 
 	createAccount<T extends Record<string, any>>(
@@ -151,9 +157,22 @@ export interface InternalAdapter<
 
 	deleteAccounts(userId: string): Promise<void>;
 
-	deleteAccount(accountId: string): Promise<void>;
+	/**
+	 * Delete an account by its primary key.
+	 *
+	 * @param id - The account row's primary key (the `id` column, not the `accountId` column).
+	 */
+	deleteAccount(id: string): Promise<void>;
 
-	deleteSessions(userIdOrSessionTokens: string | string[]): Promise<void>;
+	/**
+	 * Delete every session belonging to a user.
+	 */
+	deleteUserSessions(userId: string): Promise<void>;
+
+	/**
+	 * Delete sessions by their session tokens.
+	 */
+	deleteSessions(sessionTokens: string[]): Promise<void>;
 
 	findOAuthUser(
 		email: string,
@@ -191,8 +210,6 @@ export interface InternalAdapter<
 
 	findAccounts(userId: string): Promise<Account[]>;
 
-	findAccount(accountId: string): Promise<Account | null>;
-
 	findAccountByProviderId(
 		accountId: string,
 		providerId: string,
@@ -211,10 +228,45 @@ export interface InternalAdapter<
 
 	deleteVerificationByIdentifier(identifier: string): Promise<void>;
 
+	/**
+	 * Atomically consume a single-use verification row by `identifier` and
+	 * return it. Only the first concurrent caller receives the latest row;
+	 * subsequent callers receive `null`. Consuming one row invalidates the
+	 * whole identifier so stale rows cannot be replayed. Rows past their
+	 * `expiresAt` are treated as already invalid: the row is deleted but
+	 * `null` is returned, so callers do not need to gate on `expiresAt`
+	 * themselves. Callers MUST gate any state change (issue session, mint
+	 * token, change password) on a non-null result.
+	 *
+	 * Replaces the racy `findVerificationValue` + `deleteVerificationByIdentifier`
+	 * pair at single-use credential consumption sites.
+	 */
+	consumeVerificationValue(identifier: string): Promise<Verification | null>;
+
+	/**
+	 * First-writer-wins create keyed by a deterministic primary key derived from
+	 * `identifier`. Returns `true` when this caller created the row and `false`
+	 * when a row for the same identifier already existed.
+	 *
+	 * The dual of `consumeVerificationValue`: reserve races to create a marker
+	 * exactly once, where consume races to delete one exactly once. Use it for
+	 * replay tombstones (a SAML assertion id, a JWT `jti`) where the first caller
+	 * wins. The database path is atomic via the primary key. Secondary-storage-only
+	 * verification is not supported for reservation and runtime implementations
+	 * should fail closed unless verification is backed by the database.
+	 */
+	reserveVerificationValue(data: {
+		identifier: string;
+		value: string;
+		expiresAt: Date;
+	}): Promise<boolean>;
+
 	updateVerificationByIdentifier(
 		identifier: string,
 		data: Partial<Verification>,
 	): Promise<Verification>;
+
+	refreshUserSessions(user: User): Promise<void>;
 }
 
 type CreateCookieGetterFn = (
@@ -299,7 +351,7 @@ export type AuthContext<Options extends BetterAuthOptions = BetterAuthOptions> =
 				 * - "cookie": Store state in an encrypted cookie (stateless)
 				 * - "database": Store state in the database
 				 *
-				 * @default "cookie"
+				 * @default "database" when `database` or `secondaryStorage` is configured, "cookie" otherwise
 				 */
 				storeStateStrategy: "database" | "cookie";
 			};

package/src/types/index.ts

@@ -24,6 +24,13 @@ export type {
 	DynamicBaseURLConfig,
 	GenerateIdFn,
 	StoreIdentifierOption,
+	UserProvisioningSource,
+	ValidateUserInfoAction,
+	ValidateUserInfoMethod,
+	ValidateUserInfoOAuthInfo,
+	ValidateUserInfoResult,
+	ValidateUserInfoSource,
+	ValidateUserInfoSSOInfo,
 } from "./init-options";
 export type {
 	BetterAuthPlugin,

package/src/types/init-options.ts

@@ -14,7 +14,6 @@ import type {
 	Account,
 	DBFieldAttribute,
 	ModelNames,
-	RateLimit,
 	SecondaryStorage,
 	Session,
 	User,
@@ -47,6 +46,98 @@ export type GenerateIdFn = (options: {
 	size?: number | undefined;
 }) => string | false;
 
+/**
+ * What Better Auth is about to do with an incoming identity when
+ * {@link BetterAuthOptions.user}'s `validateUserInfo` runs.
+ *
+ * - `create-user`: a brand-new user record is about to be created.
+ * - `link-account`: a new provider account is about to be linked to an
+ *   already-existing user.
+ * - `sign-in`: an existing OAuth or SSO user is signing in again. This is the
+ *   one case where the provider can assert *changed* data, so the hook receives
+ *   the fresh provider email and profile (not the stored row), letting a domain
+ *   or org policy reject a user whose provider identity moved out of bounds.
+ *
+ * Non-provider returning sign-ins are not re-validated: they carry only the
+ * stored row, which has not changed since `create-user` gated it. Use the admin
+ * plugin's ban controls or a `databaseHooks.session.create.before` hook to
+ * block those.
+ */
+export type ValidateUserInfoAction = "create-user" | "link-account" | "sign-in";
+
+/**
+ * The authentication method that produced the incoming user info. The named
+ * methods cover Better Auth's built-ins; the open `string` keeps it extensible
+ * for plugins (for example `"scim"`).
+ */
+export type ValidateUserInfoMethod =
+	| "oauth"
+	| "sso-oidc"
+	| "sso-saml"
+	| "email-password"
+	| "magic-link"
+	| "email-otp"
+	| "anonymous"
+	| "siwe"
+	| "phone-number"
+	| "admin"
+	| (string & {});
+
+/** OAuth-specific provisioning context; present only when `method` is `"oauth"`. */
+export type ValidateUserInfoOAuthInfo = {
+	/** The social or generic OAuth provider id (e.g. `"google"`). */
+	providerId: string;
+	/** The raw provider profile (userinfo or id-token claims), unmapped. */
+	profile?: Record<string, unknown> | undefined;
+};
+
+/** SSO-specific provisioning context; present for OIDC and SAML SSO methods. */
+export type ValidateUserInfoSSOInfo = {
+	/** The configured SSO provider id. */
+	providerId: string;
+	/** The raw OIDC claims or SAML assertion attributes, unmapped. */
+	profile?: Record<string, unknown> | undefined;
+};
+
+/** Provisioning origin passed to `createUser`; the creation seam adds `action: "create-user"` to build {@link ValidateUserInfoSource}. */
+export type UserProvisioningSource = {
+	method: ValidateUserInfoMethod;
+	/** Provider id and raw profile; present iff `method` is `"oauth"`. */
+	oauth?: ValidateUserInfoOAuthInfo | undefined;
+	/** Provider id and raw profile; present iff `method` is `"sso-oidc"` or `"sso-saml"`. */
+	sso?: ValidateUserInfoSSOInfo | undefined;
+};
+
+/**
+ * The context passed to `validateUserInfo`: the lifecycle
+ * {@link ValidateUserInfoAction}, the {@link ValidateUserInfoMethod}, and (for
+ * OAuth/SSO provider methods) protocol-specific provider metadata.
+ *
+ * ```ts
+ * // Scope to one OAuth provider:
+ * if (source.oauth?.providerId !== "google") return;
+ * // Branch on the method:
+ * if (source.method === "anonymous") return { error: "no_anonymous" };
+ * // Inspect SSO claims:
+ * if (source.method === "sso-saml" && source.sso?.profile?.department !== "eng") {
+ *   return { error: "invalid_department" };
+ * }
+ * ```
+ */
+export type ValidateUserInfoSource = UserProvisioningSource & {
+	action: ValidateUserInfoAction;
+};
+
+export type ValidateUserInfoResult = {
+	/** A short, machine-readable rejection code, surfaced to the client. */
+	error: string;
+	/**
+	 * A human-readable reason, surfaced to the client. Do not put sensitive
+	 * details here.
+	 */
+	errorDescription?: string | undefined;
+};
+
 /**
  * Configuration for dynamic base URL resolution.
  * Allows Better Auth to work with multiple domains (e.g., Vercel preview deployments).
@@ -95,12 +186,27 @@ export type DynamicBaseURLConfig = {
 export type BaseURLConfig = string | DynamicBaseURLConfig;
 
 export interface BetterAuthRateLimitStorage {
-	get: (key: string) => Promise<RateLimit | null | undefined>;
-	set: (
+	/**
+	 * Atomically records one request against `key` within the rolling `window`
+	 * (in seconds) and reports whether it is allowed.
+	 *
+	 * When `allowed` is true the count was incremented within the active window,
+	 * or the window had elapsed and was reset to start at 1. When `allowed` is
+	 * false the limit was already reached and `retryAfter` is the number of
+	 * seconds until the window frees up.
+	 *
+	 * Performing the check and the increment in a single step closes the
+	 * concurrent-bypass gap of the separate `get`/`set` path: N simultaneous
+	 * requests can no longer all pass a stale read before any increment lands.
+	 *
+	 * Custom storages must implement this operation directly. Better Auth no
+	 * longer accepts separate `get`/`set` rate-limit storage because that shape
+	 * cannot enforce a distributed limit under concurrent requests.
+	 */
+	consume: (
 		key: string,
-		value: RateLimit,
-		update?: boolean | undefined,
-	) => Promise<void>;
+		rule: { window: number; max: number },
+	) => Promise<{ allowed: boolean; retryAfter: number | null }>;
 }
 
 export type BetterAuthRateLimitRule = {
@@ -197,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[];
 				/**
@@ -207,12 +313,28 @@ export type BetterAuthAdvancedOptions = {
 				 */
 				disableIpTracking?: boolean;
 				/**
-				 * IPv6 subnet prefix length for rate limiting.
-				 * IPv6 addresses will be normalized to this subnet.
+				 * IPv6 prefix length used to collapse addresses before rate-limit keying.
+				 * Any integer from 0 to 128 is accepted; common values are 32, 48, 56, 64, 128.
+				 * Out-of-range values fall back to safe behavior (negative -> mask all, > 128 -> no mask).
 				 *
 				 * @default 64
 				 */
-				ipv6Subnet?: 128 | 64 | 48 | 32;
+				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;
 	/**
@@ -776,6 +898,33 @@ export type BetterAuthOptions = {
 	 */
 	user?:
 		| (BetterAuthDBOptions<"user", keyof BaseUser> & {
+				/**
+				 * Gate which identities Better Auth admits. Called just before
+				 * `create-user`, `link-account`, and (for OAuth) `sign-in`, across
+				 * every authentication method, including stateless setups with no
+				 * persistent database. On `sign-in` the hook receives the *fresh*
+				 * provider email and profile, so a domain policy can reject a user
+				 * whose provider identity moved out of bounds.
+				 *
+				 * Non-provider returning sign-ins are not re-validated; use the admin
+				 * plugin's ban controls or a `databaseHooks.session.create.before`
+				 * hook for those.
+				 *
+				 * Return nothing to allow; return `{ error }` to reject. Browser flows
+				 * redirect to the configured error URL; programmatic flows surface a
+				 * `403`.
+				 *
+				 * TODO: rename to `validateUser` (and the `ValidateUserInfo*` types).
+				 * "UserInfo" is the OIDC term and misleads for the email/password,
+				 * SIWE, phone, and admin methods.
+				 */
+				validateUserInfo?: (
+					data: {
+						user: Partial<User> & Record<string, unknown>;
+						source: ValidateUserInfoSource;
+					},
+					context: GenericEndpointContext,
+				) => Awaitable<void | ValidateUserInfoResult>;
 				/**
 				 * Changing email configuration
 				 */
@@ -925,6 +1074,20 @@ export type BetterAuthOptions = {
 					 * @default "compact"
 					 */
 					strategy?: "compact" | "jwt" | "jwe";
+					/**
+					 * JWT-specific configuration for `strategy: "jwt"`.
+					 */
+					jwt?: {
+						/**
+						 * Which signing key is used for cookie-cache JWTs.
+						 *
+						 * - `"secret"`: uses the Better Auth secret with HS256.
+						 * - `"jwt-plugin"`: uses the installed `jwt()` plugin's asymmetric signing keys.
+						 *
+						 * @default "secret"
+						 */
+						signingKey?: "secret" | "jwt-plugin";
+					};
 					/**
 					 * Controls stateless cookie cache refresh behavior.
 					 *
@@ -1020,6 +1183,25 @@ export type BetterAuthOptions = {
 					 * @default false
 					 */
 					disableImplicitLinking?: boolean;
+					/**
+					 * Require the existing local user row to have
+					 * `emailVerified: true` before implicit account linking
+					 * uses the IdP's `email_verified` claim as ownership
+					 * proof. Defaults to `true` so an attacker who
+					 * pre-registers an unverified account at a victim's
+					 * email cannot have the victim's OAuth identity linked
+					 * into the attacker-owned row on first sign-in. Set to
+					 * `false` for backward compatibility on apps whose
+					 * users sign up via OAuth without verifying their email
+					 * locally; understand the takeover risk before doing
+					 * so.
+					 *
+					 * @default true
+					 *
+					 * @deprecated The option will be removed on the next
+					 * minor; the gate will become unconditional.
+					 */
+					requireLocalEmailVerified?: boolean;
 					/**
 					 * List of trusted providers. Can be a static array or a function
 					 * that returns providers dynamically. The function is called
@@ -1073,7 +1255,11 @@ export type BetterAuthOptions = {
 					 */
 					allowUnlinkingAll?: boolean;
 					/**
-					 * If enabled (true), this will update the user information based on the newly linked account
+					 * When enabled, linking an account copies the provider's profile onto
+					 * the local user, matching the fields persisted on sign-up (`name`,
+					 * `image`, and any `mapProfileToUser` fields). The local `email` and
+					 * `emailVerified` are never changed, so a link cannot rebind the
+					 * account's identity.
 					 *
 					 * @default false
 					 */
@@ -1106,13 +1292,17 @@ export type BetterAuthOptions = {
 				 * - "cookie": Store state in an encrypted cookie (stateless)
 				 * - "database": Store state in the database
 				 *
-				 * @default "cookie"
+				 * @default "database" when `database` or `secondaryStorage` is configured, "cookie" otherwise
 				 */
 				storeStateStrategy?: "database" | "cookie";
 				/**
-				 * Store account data after oauth flow on a cookie
+				 * Store provider account data after an OAuth flow in an encrypted
+				 * cookie. This includes OAuth token material such as access tokens,
+				 * refresh tokens, ID tokens, scopes, and token expiry.
 				 *
-				 * This is useful for database-less flow
+				 * This is useful for database-less flows, but large provider tokens can
+				 * still hit browser or proxy cookie/header limits even though Better Auth
+				 * chunks oversized account cookies.
 				 *
 				 * @default false
 				 *

package/src/types/plugin-client.ts

@@ -6,7 +6,21 @@ import type {
 import type { Atom, WritableAtom } from "nanostores";
 import type { LiteralString } from "./helper";
 import type { BetterAuthOptions } from "./init-options";
-import type { BetterAuthPlugin } from "./plugin";
+
+type InferableServerPlugin = {
+	id?: LiteralString | undefined;
+	endpoints?: Record<string, unknown> | undefined;
+	schema?: Record<string, { fields: Record<string, unknown> }> | undefined;
+	$ERROR_CODES?:
+		| Record<
+				string,
+				{
+					readonly code: string;
+					message: string;
+				}
+		  >
+		| undefined;
+};
 
 export interface ClientStore {
 	notify: (signal: string) => void;
@@ -84,7 +98,7 @@ export interface BetterAuthClientPlugin {
 	 * only used for type inference. don't pass the
 	 * actual plugin
 	 */
-	$InferServerPlugin?: BetterAuthPlugin | undefined;
+	$InferServerPlugin?: InferableServerPlugin | undefined;
 	/**
 	 * Custom actions
 	 */

package/src/utils/async.ts

@@ -0,0 +1,53 @@
+import type { Awaitable } from "../types/helper";
+
+export interface MapConcurrentOptions {
+	/**
+	 * Max in-flight mappers. Non-integer values are floored, then clamped
+	 * to the range `[1, items.length]`. `NaN` falls back to 1.
+	 */
+	concurrency: number;
+	/**
+	 * Rejects with `signal.reason` when aborted. In-flight mappers keep
+	 * running but their results are not returned.
+	 */
+	signal?: AbortSignal;
+}
+
+/**
+ * Run an async mapper over items with bounded concurrency.
+ * Preserves input order in the result. Fails fast on the first rejection.
+ */
+export async function mapConcurrent<T, R>(
+	items: readonly T[],
+	fn: (item: T, index: number) => Awaitable<R>,
+	options: MapConcurrentOptions,
+): Promise<R[]> {
+	const n = items.length;
+	if (n === 0) return [];
+
+	const { signal } = options;
+	if (signal?.aborted) throw signal.reason;
+
+	const raw = Math.floor(options.concurrency);
+	const width = Math.min(n, raw >= 1 ? raw : 1);
+
+	const results = new Array<R>(n);
+	let idx = 0;
+	let failed = false;
+
+	const worker = async (): Promise<void> => {
+		while (!failed && idx < n) {
+			if (signal?.aborted) throw signal.reason;
+			const i = idx++;
+			try {
+				results[i] = await fn(items[i] as T, i);
+			} catch (error) {
+				failed = true;
+				throw error;
+			}
+		}
+	};
+
+	await Promise.all(Array.from({ length: width }, worker));
+	return results;
+}