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

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

@@ -24,7 +24,8 @@ declare const vk: (options: VkOption) => {
     state,
     scopes,
     codeVerifier,
-    redirectURI
+    redirectURI,
+    additionalParams
   }: {
     state: string;
     codeVerifier: string;
@@ -32,6 +33,8 @@ declare const vk: (options: VkOption) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
+    additionalParams?: Record<string, string> | undefined;
   }): Promise<URL>;
   validateAuthorizationCode: ({
     code,
@@ -46,6 +49,7 @@ declare const vk: (options: VkOption) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(data: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/vk.mjs

@@ -8,7 +8,7 @@ const vk = (options) => {
 	return {
 		id: "vk",
 		name: "VK",
-		async createAuthorizationURL({ state, scopes, codeVerifier, redirectURI }) {
+		async createAuthorizationURL({ state, scopes, codeVerifier, redirectURI, additionalParams }) {
 			const _scopes = options.disableDefaultScope ? [] : ["email", "phone"];
 			if (options.scope) _scopes.push(...options.scope);
 			if (scopes) _scopes.push(...scopes);
@@ -19,7 +19,8 @@ const vk = (options) => {
 				scopes: _scopes,
 				state,
 				redirectURI,
-				codeVerifier
+				codeVerifier,
+				additionalParams
 			});
 		},
 		validateAuthorizationCode: async ({ code, codeVerifier, redirectURI, deviceId }) => {

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

@@ -56,7 +56,8 @@ declare const wechat: (options: WeChatOptions) => {
   createAuthorizationURL({
     state,
     scopes,
-    redirectURI
+    redirectURI,
+    additionalParams
   }: {
     state: string;
     codeVerifier: string;
@@ -64,6 +65,8 @@ declare const wechat: (options: WeChatOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
+    additionalParams?: Record<string, string> | undefined;
   }): URL;
   validateAuthorizationCode: ({
     code
@@ -89,6 +92,7 @@ declare const wechat: (options: WeChatOptions) => {
     scopes: string[];
   }>);
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/wechat.mjs

@@ -1,10 +1,11 @@
+import { RESERVED_AUTHORIZATION_PARAMS_SET } from "../oauth2/create-authorization-url.mjs";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/social-providers/wechat.ts
 const wechat = (options) => {
 	return {
 		id: "wechat",
 		name: "WeChat",
-		createAuthorizationURL({ state, scopes, redirectURI }) {
+		createAuthorizationURL({ state, scopes, redirectURI, additionalParams }) {
 			const _scopes = options.disableDefaultScope ? [] : ["snsapi_login"];
 			options.scope && _scopes.push(...options.scope);
 			scopes && _scopes.push(...scopes);
@@ -15,6 +16,11 @@ const wechat = (options) => {
 			url.searchParams.set("redirect_uri", options.redirectURI || redirectURI);
 			url.searchParams.set("state", state);
 			url.searchParams.set("lang", options.lang || "cn");
+			if (additionalParams) for (const [key, value] of Object.entries(additionalParams)) {
+				if (RESERVED_AUTHORIZATION_PARAMS_SET.has(key)) continue;
+				if (key === "appid") continue;
+				url.searchParams.set(key, value);
+			}
 			url.hash = "wechat_redirect";
 			return url;
 		},
@@ -66,7 +72,7 @@ const wechat = (options) => {
 				user: {
 					id: profile.unionid || profile.openid || openid,
 					name: profile.nickname,
-					email: profile.email || null,
+					email: profile.email || `${profile.unionid || profile.openid || openid}@wechat.invalid`,
 					image: profile.headimgurl,
 					emailVerified: false,
 					...userMap

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

@@ -119,7 +119,8 @@ declare const zoom: (userOptions: ZoomOptions) => {
   createAuthorizationURL: ({
     state,
     redirectURI,
-    codeVerifier
+    codeVerifier,
+    additionalParams
   }: {
     state: string;
     codeVerifier: string;
@@ -127,6 +128,8 @@ declare const zoom: (userOptions: ZoomOptions) => {
     redirectURI: string;
     display?: string | undefined;
     loginHint?: string | undefined;
+    idTokenNonce?: string | undefined;
+    additionalParams?: Record<string, string> | undefined;
   }) => Promise<URL>;
   validateAuthorizationCode: ({
     code,
@@ -140,6 +143,7 @@ declare const zoom: (userOptions: ZoomOptions) => {
   }) => Promise<OAuth2Tokens>;
   refreshAccessToken: (refreshToken: string) => Promise<OAuth2Tokens>;
   getUserInfo(token: OAuth2Tokens & {
+    expectedIdTokenNonce?: string | undefined;
     user?: {
       name?: {
         firstName?: string;

package/dist/social-providers/zoom.mjs

@@ -1,4 +1,4 @@
-import { generateCodeChallenge } from "../oauth2/utils.mjs";
+import { createAuthorizationURL } from "../oauth2/create-authorization-url.mjs";
 import { refreshAccessToken } from "../oauth2/refresh-access-token.mjs";
 import { validateAuthorizationCode } from "../oauth2/validate-authorization-code.mjs";
 import { betterFetch } from "@better-fetch/fetch";
@@ -11,22 +11,15 @@ const zoom = (userOptions) => {
 	return {
 		id: "zoom",
 		name: "Zoom",
-		createAuthorizationURL: async ({ state, redirectURI, codeVerifier }) => {
-			const params = new URLSearchParams({
-				response_type: "code",
-				redirect_uri: options.redirectURI ? options.redirectURI : redirectURI,
-				client_id: options.clientId,
-				state
-			});
-			if (options.pkce) {
-				const codeChallenge = await generateCodeChallenge(codeVerifier);
-				params.set("code_challenge_method", "S256");
-				params.set("code_challenge", codeChallenge);
-			}
-			const url = new URL("https://zoom.us/oauth/authorize");
-			url.search = params.toString();
-			return url;
-		},
+		createAuthorizationURL: async ({ state, redirectURI, codeVerifier, additionalParams }) => createAuthorizationURL({
+			id: "zoom",
+			options,
+			authorizationEndpoint: "https://zoom.us/oauth/authorize",
+			state,
+			redirectURI,
+			codeVerifier: options.pkce ? codeVerifier : void 0,
+			additionalParams
+		}),
 		validateAuthorizationCode: async ({ code, redirectURI, codeVerifier }) => {
 			return validateAuthorizationCode({
 				code,

package/dist/types/context.d.mts

@@ -6,7 +6,7 @@ import { Verification } from "../db/schema/verification.mjs";
 import { createLogger } from "../env/logger.mjs";
 import { Awaitable, LiteralString } from "./helper.mjs";
 import { BetterAuthPlugin } from "./plugin.mjs";
-import { BetterAuthOptions, BetterAuthRateLimitOptions } from "./init-options.mjs";
+import { BetterAuthOptions, BetterAuthRateLimitOptions, UserProvisioningSource } from "./init-options.mjs";
 import { Account } from "../db/schema/account.mjs";
 import { BetterAuthCookie, BetterAuthCookies } from "./cookie.mjs";
 import { SecretConfig } from "./secret.mjs";
@@ -58,7 +58,13 @@ interface InternalAdapter<_Options extends BetterAuthOptions = BetterAuthOptions
     user: User;
     account: Account;
   }>;
-  createUser<T extends Record<string, any>>(user: Omit<User, "id" | "createdAt" | "updatedAt" | "emailVerified"> & Partial<User> & Record<string, any>): Promise<T & User>;
+  createUser<T extends Record<string, any>>(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>>(account: Omit<Account, "id" | "createdAt" | "updatedAt"> & Partial<Account> & T): Promise<T & Account>;
   listSessions(userId: string, options?: {
     onlyActiveSessions?: boolean | undefined;
@@ -83,8 +89,20 @@ interface InternalAdapter<_Options extends BetterAuthOptions = BetterAuthOptions
   updateSession(sessionToken: string, session: Partial<Session> & Record<string, any>): Promise<Session | null>;
   deleteSession(token: string): Promise<void>;
   deleteAccounts(userId: string): Promise<void>;
-  deleteAccount(accountId: string): Promise<void>;
-  deleteSessions(userIdOrSessionTokens: string | 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>;
+  /**
+   * 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, accountId: string, providerId: string): Promise<{
     user: User;
     linkedAccount: Account | null;
@@ -102,14 +120,45 @@ interface InternalAdapter<_Options extends BetterAuthOptions = BetterAuthOptions
   updateUserByEmail<T extends Record<string, any>>(email: string, data: Partial<User & Record<string, any>>): Promise<User & T>;
   updatePassword(userId: string, password: string): Promise<void>;
   findAccounts(userId: string): Promise<Account[]>;
-  findAccount(accountId: string): Promise<Account | null>;
   findAccountByProviderId(accountId: string, providerId: string): Promise<Account | null>;
   findAccountByUserId(userId: string): Promise<Account[]>;
   updateAccount(id: string, data: Partial<Account>): Promise<Account>;
   createVerificationValue(data: Omit<Verification, "createdAt" | "id" | "updatedAt"> & Partial<Verification>): Promise<Verification>;
   findVerificationValue(identifier: string): Promise<Verification | null>;
   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 = (cookieName: string, overrideAttributes?: Partial<CookieOptions> | undefined) => BetterAuthCookie;
 type CheckPasswordFn<Options extends BetterAuthOptions = BetterAuthOptions> = (userId: string, ctx: GenericEndpointContext<Options>) => Promise<boolean>;
@@ -165,7 +214,7 @@ type AuthContext<Options extends BetterAuthOptions = BetterAuthOptions> = Plugin
      * - "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/dist/types/index.d.mts

@@ -1,6 +1,6 @@
 import { Awaitable, AwaitableFunction, LiteralString, LiteralUnion, Prettify, Primitive, UnionToIntersection } from "./helper.mjs";
 import { BetterAuthPlugin, BetterAuthPluginErrorCodePart, HookEndpointContext } from "./plugin.mjs";
-import { BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthDBOptions, BetterAuthOptions, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, DynamicBaseURLConfig, GenerateIdFn, StoreIdentifierOption } from "./init-options.mjs";
+import { BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthDBOptions, BetterAuthOptions, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, DynamicBaseURLConfig, GenerateIdFn, StoreIdentifierOption, UserProvisioningSource, ValidateUserInfoAction, ValidateUserInfoMethod, ValidateUserInfoOAuthInfo, ValidateUserInfoResult, ValidateUserInfoSSOInfo, ValidateUserInfoSource } from "./init-options.mjs";
 import { BetterAuthCookie, BetterAuthCookies } from "./cookie.mjs";
 import { SecretConfig } from "./secret.mjs";
 import { AuthContext, BetterAuthPluginRegistry, BetterAuthPluginRegistryIdentifier, GenericEndpointContext, InfoContext, InternalAdapter, PluginContext } from "./context.mjs";

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

@@ -1,6 +1,6 @@
 import { DBFieldAttribute, ModelNames, SecondaryStorage } from "../db/type.mjs";
 import { DBAdapterDebugLogOption, DBAdapterInstance } from "../db/adapter/index.mjs";
-import { BaseRateLimit, RateLimit } from "../db/schema/rate-limit.mjs";
+import { BaseRateLimit } from "../db/schema/rate-limit.mjs";
 import { BaseSession, Session } from "../db/schema/session.mjs";
 import { BaseUser, User } from "../db/schema/user.mjs";
 import { BaseVerification, Verification } from "../db/schema/verification.mjs";
@@ -27,6 +27,73 @@ type GenerateIdFn = (options: {
   model: ModelNames;
   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.
+ */
+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"`).
+ */
+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"`. */
+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. */
+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}. */
+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" };
+ * }
+ * ```
+ */
+type ValidateUserInfoSource = UserProvisioningSource & {
+  action: ValidateUserInfoAction;
+};
+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).
@@ -71,8 +138,30 @@ type DynamicBaseURLConfig = {
  */
 type BaseURLConfig = string | DynamicBaseURLConfig;
 interface BetterAuthRateLimitStorage {
-  get: (key: string) => Promise<RateLimit | null | undefined>;
-  set: (key: string, value: RateLimit, update?: boolean | undefined) => Promise<void>;
+  /**
+   * 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, rule: {
+    window: number;
+    max: number;
+  }) => Promise<{
+    allowed: boolean;
+    retryAfter: number | null;
+  }>;
 }
 type BetterAuthRateLimitRule = {
   /**
@@ -147,7 +236,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[];
     /**
@@ -157,12 +246,28 @@ 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;
   /**
    * Force cookies to always use the `Secure` attribute. By default,
@@ -683,6 +788,30 @@ type BetterAuthOptions = {
    * User configuration
    */
   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
      */
@@ -824,6 +953,20 @@ 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.
        *
@@ -906,6 +1049,25 @@ 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
@@ -943,7 +1105,11 @@ 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
        */
@@ -976,13 +1142,17 @@ 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
      *
@@ -1355,4 +1525,4 @@ type BetterAuthOptions = {
   };
 };
 //#endregion
-export { BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthDBOptions, BetterAuthOptions, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, DynamicBaseURLConfig, GenerateIdFn, StoreIdentifierOption };
+export { BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthDBOptions, BetterAuthOptions, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, DynamicBaseURLConfig, GenerateIdFn, StoreIdentifierOption, UserProvisioningSource, ValidateUserInfoAction, ValidateUserInfoMethod, ValidateUserInfoOAuthInfo, ValidateUserInfoResult, ValidateUserInfoSSOInfo, ValidateUserInfoSource };

package/dist/types/plugin-client.d.mts

@@ -1,10 +1,20 @@
 import { LiteralString } from "./helper.mjs";
-import { BetterAuthPlugin } from "./plugin.mjs";
 import { BetterAuthOptions } from "./init-options.mjs";
 import { BetterFetch, BetterFetchOption, BetterFetchPlugin } from "@better-fetch/fetch";
 import { Atom, WritableAtom } from "nanostores";
 
 //#region src/types/plugin-client.d.ts
+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;
+};
 interface ClientStore {
   notify: (signal: string) => void;
   listen: (signal: string, listener: () => void) => void;
@@ -71,7 +81,7 @@ interface BetterAuthClientPlugin {
    * only used for type inference. don't pass the
    * actual plugin
    */
-  $InferServerPlugin?: BetterAuthPlugin | undefined;
+  $InferServerPlugin?: InferableServerPlugin | undefined;
   /**
    * Custom actions
    */

package/dist/utils/async.d.mts

@@ -0,0 +1,22 @@
+import { Awaitable } from "../types/helper.mjs";
+
+//#region src/utils/async.d.ts
+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.
+ */
+declare function mapConcurrent<T, R>(items: readonly T[], fn: (item: T, index: number) => Awaitable<R>, options: MapConcurrentOptions): Promise<R[]>;
+//#endregion
+export { MapConcurrentOptions, mapConcurrent };

package/dist/utils/async.mjs

@@ -0,0 +1,32 @@
+//#region src/utils/async.ts
+/**
+* Run an async mapper over items with bounded concurrency.
+* Preserves input order in the result. Fails fast on the first rejection.
+*/
+async function mapConcurrent(items, fn, options) {
+	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(n);
+	let idx = 0;
+	let failed = false;
+	const worker = async () => {
+		while (!failed && idx < n) {
+			if (signal?.aborted) throw signal.reason;
+			const i = idx++;
+			try {
+				results[i] = await fn(items[i], i);
+			} catch (error) {
+				failed = true;
+				throw error;
+			}
+		}
+	};
+	await Promise.all(Array.from({ length: width }, worker));
+	return results;
+}
+//#endregion
+export { mapConcurrent };