@better-auth/core 1.5.0-beta.8 → 1.5.0

package/src/types/init-options.ts

@@ -1,5 +1,6 @@
 import type { Database as BunDatabase } from "bun:sqlite";
 import type { DatabaseSync } from "node:sqlite";
+import type { D1Database } from "@cloudflare/workers-types";
 import type { CookieOptions } from "better-call";
 import type {
 	Dialect,
@@ -20,23 +21,79 @@ import type {
 	Verification,
 } from "../db";
 import type { DBAdapterDebugLogOption, DBAdapterInstance } from "../db/adapter";
+import type { BaseAccount } from "../db/schema/account";
+import type { BaseRateLimit } from "../db/schema/rate-limit";
+import type { BaseSession } from "../db/schema/session";
+import type { BaseUser } from "../db/schema/user";
+import type { BaseVerification } from "../db/schema/verification";
 import type { Logger } from "../env";
 import type { SocialProviderList, SocialProviders } from "../social-providers";
 import type { AuthContext, GenericEndpointContext } from "./context";
-import type { Awaitable, LiteralUnion } from "./helper";
+import type { Awaitable, LiteralString, LiteralUnion } from "./helper";
 import type { BetterAuthPlugin } from "./plugin";
 
 type KyselyDatabaseType = "postgres" | "mysql" | "sqlite" | "mssql";
-type OmitId<T extends { id: unknown }> = Omit<T, "id">;
 type Optional<T> = {
 	[P in keyof T]?: T[P] | undefined;
 };
 
+export type StoreIdentifierOption =
+	| "plain"
+	| "hashed"
+	| { hash: (identifier: string) => Promise<string> };
+
 export type GenerateIdFn = (options: {
 	model: ModelNames;
 	size?: number | undefined;
 }) => string | false;
 
+/**
+ * Configuration for dynamic base URL resolution.
+ * Allows Better Auth to work with multiple domains (e.g., Vercel preview deployments).
+ */
+export type DynamicBaseURLConfig = {
+	/**
+	 * List of allowed hostnames. Supports wildcard patterns.
+	 *
+	 * The derived host from the request will be validated against this list.
+	 * Uses the same wildcard matching as `trustedOrigins`.
+	 *
+	 * @example
+	 * ```ts
+	 * allowedHosts: [
+	 *   "myapp.com",           // Exact match
+	 *   "*.vercel.app",        // Any Vercel preview
+	 *   "preview-*.myapp.com"  // Pattern match
+	 * ]
+	 * ```
+	 */
+	allowedHosts: string[];
+
+	/**
+	 * Fallback URL to use if the derived host doesn't match any allowed host.
+	 * If not set, Better Auth will throw an error when the host doesn't match.
+	 *
+	 * @example "https://myapp.com"
+	 */
+	fallback?: string | undefined;
+
+	/**
+	 * Protocol to use when constructing the URL.
+	 * - `"https"`: Always use HTTPS (recommended for production)
+	 * - `"http"`: Always use HTTP (for local development)
+	 * - `"auto"`: Derive from `x-forwarded-proto` header or default to HTTPS
+	 *
+	 * @default "auto"
+	 */
+	protocol?: "http" | "https" | "auto" | undefined;
+};
+
+/**
+ * Base URL configuration.
+ * Can be a static string or a dynamic config for multi-domain deployments.
+ */
+export type BaseURLConfig = string | DynamicBaseURLConfig;
+
 export interface BetterAuthRateLimitStorage {
 	get: (key: string) => Promise<RateLimit | null | undefined>;
 	set: (
@@ -62,57 +119,70 @@ export type BetterAuthRateLimitRule = {
 	max: number;
 };
 
-export type BetterAuthRateLimitOptions = Optional<BetterAuthRateLimitRule> & {
+export type BetterAuthDBOptions<
+	ModelName extends string,
+	Keys extends string = string,
+> = {
 	/**
-	 * By default, rate limiting is only
-	 * enabled on production.
+	 * The name of the model. Defaults to the model name.
 	 */
-	enabled?: boolean | undefined;
+	modelName?: ModelName | LiteralString;
 	/**
-	 * Custom rate limit rules to apply to
-	 * specific paths.
+	 * Map fields to database columns
 	 */
-	customRules?:
-		| {
-				[key: string]:
-					| BetterAuthRateLimitRule
-					| false
-					| ((
-							request: Request,
-							currentRule: BetterAuthRateLimitRule,
-					  ) => Awaitable<false | BetterAuthRateLimitRule>);
-		  }
-		| undefined;
-	/**
-	 * Storage configuration
-	 *
-	 * By default, rate limiting is stored in memory. If you passed a
-	 * secondary storage, rate limiting will be stored in the secondary
-	 * storage.
-	 *
-	 * @default "memory"
-	 */
-	storage?: ("memory" | "database" | "secondary-storage") | undefined;
-	/**
-	 * If database is used as storage, the name of the table to
-	 * use for rate limiting.
-	 *
-	 * @default "rateLimit"
-	 */
-	modelName?: string | undefined;
-	/**
-	 * Custom field names for the rate limit table
-	 */
-	fields?: Partial<Record<keyof RateLimit, string>> | undefined;
+	fields?: Partial<Record<Exclude<Keys, "id">, string>>;
 	/**
-	 * custom storage configuration.
-	 *
-	 * NOTE: If custom storage is used storage
-	 * is ignored
+	 * Additional fields for the model
 	 */
-	customStorage?: BetterAuthRateLimitStorage;
+	additionalFields?: {
+		[Key in Exclude<string, Keys | "id">]: DBFieldAttribute;
+	};
 };
 
+export type BetterAuthRateLimitOptions = Optional<BetterAuthRateLimitRule> &
+	Omit<
+		BetterAuthDBOptions<"rateLimit", keyof BaseRateLimit>,
+		"additionalFields"
+	> & {
+		/**
+		 * By default, rate limiting is only
+		 * enabled on production.
+		 */
+		enabled?: boolean | undefined;
+		/**
+		 * Custom rate limit rules to apply to
+		 * specific paths.
+		 */
+		customRules?:
+			| {
+					[key: string]:
+						| BetterAuthRateLimitRule
+						| false
+						| ((
+								request: Request,
+								currentRule: BetterAuthRateLimitRule,
+						  ) => Awaitable<false | BetterAuthRateLimitRule>);
+			  }
+			| undefined;
+		/**
+		 * Storage configuration
+		 *
+		 * By default, rate limiting is stored in memory. If you passed a
+		 * secondary storage, rate limiting will be stored in the secondary
+		 * storage.
+		 *
+		 * @default "memory"
+		 */
+		storage?: ("memory" | "database" | "secondary-storage") | undefined;
+		/**
+		 * custom storage configuration.
+		 *
+		 * NOTE: If custom storage is used storage
+		 * is ignored
+		 */
+		customStorage?: BetterAuthRateLimitStorage;
+	};
+
 export type BetterAuthAdvancedOptions = {
 	/**
 	 * Ip address configuration
@@ -136,6 +206,13 @@ export type BetterAuthAdvancedOptions = {
 				 * ⚠︎ This is a security risk and it may expose your application to abuse
 				 */
 				disableIpTracking?: boolean;
+				/**
+				 * IPv6 subnet prefix length for rate limiting.
+				 * IPv6 addresses will be normalized to this subnet.
+				 *
+				 * @default 64
+				 */
+				ipv6Subnet?: 128 | 64 | 48 | 32;
 		  }
 		| undefined;
 	/**
@@ -237,17 +314,6 @@ export type BetterAuthAdvancedOptions = {
 				 * @default 100
 				 */
 				defaultFindManyLimit?: number;
-				/**
-				 * If your database auto increments number ids, set this to `true`.
-				 *
-				 * Note: If enabled, we will not handle ID generation (including if you use `generateId`), and it would be expected that your database will provide the ID automatically.
-				 *
-				 * @default false
-				 *
-				 * @deprecated Please use `generateId` instead. This will be removed in future
-				 * releases.
-				 */
-				useNumberId?: boolean;
 				/**
 				 * Custom generateId function.
 				 *
@@ -303,14 +369,17 @@ export type BetterAuthAdvancedOptions = {
 	 * }
 	 */
 	backgroundTasks?: {
-		handler: (promise: Promise<void>) => void;
+		handler: (promise: Promise<unknown>) => void;
 	};
 	/**
-	 * Skip trailing slash validation in route matching
+	 * Skip trailing slashes in API routes.
+	 *
+	 * When enabled, requests with trailing slashes (e.g., `/api/auth/session/`)
+	 * will be handled the same as requests without (e.g., `/api/auth/session`).
 	 *
 	 * @default false
 	 */
-	skipTrailingSlashes?: boolean | undefined;
+	skipTrailingSlashes?: boolean;
 };
 
 export type BetterAuthOptions = {
@@ -325,12 +394,27 @@ export type BetterAuthOptions = {
 	/**
 	 * Base URL for the Better Auth. This is typically the
 	 * root URL where your application server is hosted.
-	 * If not explicitly set,
-	 * the system will check the following environment variable:
 	 *
-	 * process.env.BETTER_AUTH_URL
+	 * Can be configured as:
+	 * - A static string: `"https://myapp.com"`
+	 * - A dynamic config with allowed hosts for multi-domain deployments
+	 *
+	 * If not explicitly set, the system will check environment variables:
+	 * `BETTER_AUTH_URL`, `NEXT_PUBLIC_BETTER_AUTH_URL`, etc.
+	 *
+	 * @example
+	 * ```ts
+	 * // Static URL
+	 * baseURL: "https://myapp.com"
+	 *
+	 * // Dynamic with allowed hosts (for Vercel, multi-domain, etc.)
+	 * baseURL: {
+	 *   allowedHosts: ["myapp.com", "*.vercel.app", "preview-*.myapp.com"],
+	 *   fallback: "https://myapp.com"
+	 * }
+	 * ```
 	 */
-	baseURL?: string | undefined;
+	baseURL?: BaseURLConfig | undefined;
 	/**
 	 * Base path for the Better Auth. This is typically
 	 * the path where the
@@ -363,6 +447,19 @@ export type BetterAuthOptions = {
 	 * ```
 	 */
 	secret?: string | undefined;
+	/**
+	 * Versioned secrets for non-destructive secret rotation.
+	 * When set, encryption uses an envelope format with key IDs.
+	 * First entry is the current key used for new encryption.
+	 * Remaining entries are decryption-only (previous rotations).
+	 *
+	 * Can also be set via BETTER_AUTH_SECRETS env var:
+	 * `BETTER_AUTH_SECRETS=2:base64secret,1:base64secret`
+	 *
+	 * When set, `secret` is only used as legacy fallback
+	 * for decrypting bare-hex payloads that predate the envelope format.
+	 */
+	secrets?: Array<{ version: number; value: string }> | undefined;
 	/**
 	 * Database configuration
 	 */
@@ -375,6 +472,7 @@ export type BetterAuthOptions = {
 				| DBAdapterInstance
 				| BunDatabase
 				| DatabaseSync
+				| D1Database
 				| {
 						dialect: Dialect;
 						type: KyselyDatabaseType;
@@ -466,10 +564,13 @@ export type BetterAuthOptions = {
 					request?: Request,
 				) => Promise<void>;
 				/**
-				 * Send a verification email automatically
-				 * after sign up
+				 * Send a verification email automatically after sign up.
 				 *
-				 * @default false
+				 * - `true`: Always send verification email on sign up
+				 * - `false`: Never send verification email on sign up
+				 * - `undefined`: Follows `requireEmailVerification` behavior
+				 *
+				 * @default undefined
 				 */
 				sendOnSignUp?: boolean;
 				/**
@@ -489,13 +590,6 @@ export type BetterAuthOptions = {
 				 * @default 3600 seconds (1 hour)
 				 */
 				expiresIn?: number;
-				/**
-				 * A function that is called when a user verifies their email
-				 * @param user the user that verified their email
-				 * @param request the request object
-				 * @deprecated Use `beforeEmailVerification` or `afterEmailVerification` instead. This will be removed in 1.5
-				 */
-				onEmailVerification?: (user: User, request?: Request) => Promise<void>;
 				/**
 				 * A function that is called before a user verifies their email
 				 * @param user the user that verified their email
@@ -610,6 +704,59 @@ export type BetterAuthOptions = {
 				 * @default false
 				 */
 				revokeSessionsOnPasswordReset?: boolean;
+				/**
+				 * A callback function that is triggered when a user tries to sign up
+				 * with an email that already exists. Useful for notifying the existing user
+				 * that someone attempted to register with their email.
+				 *
+				 * This is only called when `requireEmailVerification: true` or `autoSignIn: false`.
+				 */
+				onExistingUserSignUp?: (
+					/**
+					 * @param user the existing user from the database
+					 */
+					data: { user: User },
+					request?: Request,
+				) => Promise<void>;
+				/**
+				 * Build a custom synthetic user for email enumeration
+				 * protection. When a sign-up attempt is made with an
+				 * email that already exists, this function is called
+				 * to build the fake user response.
+				 *
+				 * Use this when plugins add fields to the user table
+				 * (e.g. admin plugin adds `role`, `banned`, etc.)
+				 * to ensure the fake response is indistinguishable
+				 * from a real sign-up.
+				 *
+				 * @example
+				 * ```ts
+				 * customSyntheticUser: ({ coreFields, additionalFields, id }) => ({
+				 *   ...coreFields,
+				 *   role: "user",
+				 *   banned: false,
+				 *   banReason: null,
+				 *   banExpires: null,
+				 *   ...additionalFields,
+				 *   id,
+				 * })
+				 * ```
+				 */
+				customSyntheticUser?: (params: {
+					/** Core user fields: name, email, emailVerified, image, createdAt, updatedAt */
+					coreFields: {
+						name: string;
+						email: string;
+						emailVerified: boolean;
+						image: string | null;
+						createdAt: Date;
+						updatedAt: Date;
+					};
+					/** Processed additional fields from options.user.additionalFields (with defaults applied) */
+					additionalFields: Record<string, unknown>;
+					/** Generated user ID */
+					id: string;
+				}) => Record<string, unknown>;
 		  }
 		| undefined;
 	/**
@@ -624,28 +771,7 @@ export type BetterAuthOptions = {
 	 * User configuration
 	 */
 	user?:
-		| {
-				/**
-				 * The model name for the user. Defaults to "user".
-				 */
-				modelName?: string;
-				/**
-				 * Map fields
-				 *
-				 * @example
-				 * ```ts
-				 * {
-				 *  userId: "user_id"
-				 * }
-				 * ```
-				 */
-				fields?: Partial<Record<keyof OmitId<User>, string>>;
-				/**
-				 * Additional fields for the user
-				 */
-				additionalFields?: {
-					[key: string]: DBFieldAttribute;
-				};
+		| (BetterAuthDBOptions<"user", keyof BaseUser> & {
 				/**
 				 * Changing email configuration
 				 */
@@ -655,21 +781,6 @@ export type BetterAuthOptions = {
 					 * @default false
 					 */
 					enabled: boolean;
-					/**
-					 * Send a verification email when the user changes their email.
-					 * @param data the data object
-					 * @param request the request object
-					 * @deprecated Use `sendChangeEmailConfirmation` instead
-					 */
-					sendChangeEmailVerification?: (
-						data: {
-							user: User;
-							newEmail: string;
-							url: string;
-							token: string;
-						},
-						request?: Request,
-					) => Promise<void>;
 					/**
 					 * Send a confirmation email to the old email address when the user changes their email.
 					 * @param data the data object
@@ -732,26 +843,10 @@ export type BetterAuthOptions = {
 					 */
 					deleteTokenExpiresIn?: number;
 				};
-		  }
+		  })
 		| undefined;
 	session?:
-		| {
-				/**
-				 * The model name for the session.
-				 *
-				 * @default "session"
-				 */
-				modelName?: string;
-				/**
-				 * Map fields
-				 *
-				 * @example
-				 * ```ts
-				 * {
-				 *  userId: "user_id"
-				 * }
-				 */
-				fields?: Partial<Record<keyof OmitId<Session>, string>>;
+		| (BetterAuthDBOptions<"session", keyof BaseSession> & {
 				/**
 				 * Expiration time for the session token. The value
 				 * should be in seconds.
@@ -773,11 +868,13 @@ export type BetterAuthOptions = {
 				 */
 				disableSessionRefresh?: boolean;
 				/**
-				 * Additional fields for the session
+				 * Defer session refresh writes to POST requests.
+				 * When enabled, GET is read-only and POST performs refresh.
+				 * Useful for read-replica database setups.
+				 *
+				 * @default false
 				 */
-				additionalFields?: {
-					[key: string]: DBFieldAttribute;
-				};
+				deferSessionRefresh?: boolean;
 				/**
 				 * By default if secondary storage is provided
 				 * the session is stored in the secondary storage.
@@ -887,24 +984,10 @@ export type BetterAuthOptions = {
 				 * @default 1 day (60 * 60 * 24)
 				 */
 				freshAge?: number;
-		  }
+		  })
 		| undefined;
 	account?:
-		| {
-				/**
-				 * The model name for the account. Defaults to "account".
-				 */
-				modelName?: string;
-				/**
-				 * Map fields
-				 */
-				fields?: Partial<Record<keyof OmitId<Account>, string>>;
-				/**
-				 * Additional fields for the account
-				 */
-				additionalFields?: {
-					[key: string]: DBFieldAttribute;
-				};
+		| (BetterAuthDBOptions<"account", keyof BaseAccount> & {
 				/**
 				 * When enabled (true), the user account data (accessToken, idToken, refreshToken, etc.)
 				 * will be updated on sign in with the latest data from the provider.
@@ -923,11 +1006,54 @@ export type BetterAuthOptions = {
 					 */
 					enabled?: boolean;
 					/**
-					 * List of trusted providers
+					 * Disable implicit account linking on sign-in.
+					 *
+					 * When enabled, accounts will not be automatically linked
+					 * during OAuth sign-in, even if the email is verified or
+					 * the provider is trusted. Users must explicitly link
+					 * accounts using `linkSocial()` while authenticated.
+					 *
+					 * @default false
+					 */
+					disableImplicitLinking?: boolean;
+					/**
+					 * List of trusted providers. Can be a static array or a function
+					 * that returns providers dynamically. The function is called
+					 * during context init (with `request` undefined) and again
+					 * on each request (with the incoming Request). It must be
+					 * resilient to `request` being undefined.
+					 *
+					 * @example
+					 * ```ts
+					 * trustedProviders: ["google", "github"]
+					 * ```
+					 *
+					 * @example
+					 * ```ts
+					 * trustedProviders: async (request) => {
+					 *   if (!request) return [];
+					 *   const providers = await getTrustedProvidersForTenant(request);
+					 *   return providers;
+					 * }
+					 * ```
 					 */
-					trustedProviders?: Array<
-						LiteralUnion<SocialProviderList[number] | "email-password", string>
-					>;
+					trustedProviders?:
+						| Array<
+								LiteralUnion<
+									SocialProviderList[number] | "email-password",
+									string
+								>
+						  >
+						| ((
+								request?: Request | undefined,
+						  ) => Awaitable<
+								Array<
+									LiteralUnion<
+										SocialProviderList[number] | "email-password",
+										string
+									>
+								>
+						  >);
 					/**
 					 * If enabled (true), this will allow users to manually linking accounts with different email addresses than the main user.
 					 *
@@ -989,33 +1115,34 @@ export type BetterAuthOptions = {
 				 * @note This is automatically set to true if you haven't passed a database
 				 */
 				storeAccountCookie?: boolean;
-		  }
+		  })
 		| undefined;
-	/**
-	 * Verification configuration
-	 */
 	verification?:
-		| {
+		| (BetterAuthDBOptions<"verification", keyof BaseVerification> & {
 				/**
-				 * Change the modelName of the verification table
-				 */
-				modelName?: string;
-				/**
-				 * Map verification fields
+				 * disable cleaning up expired values when a verification value is
+				 * fetched
 				 */
-				fields?: Partial<Record<keyof OmitId<Verification>, string>>;
+				disableCleanup?: boolean;
 				/**
-				 * Additional fields for the verification
+				 * How to store verification identifiers (tokens, OTPs, etc.)
+				 *
+				 * @example "hashed"
+				 *
+				 * @default "plain"
 				 */
-				additionalFields?: {
-					[key: string]: DBFieldAttribute;
-				};
+				storeIdentifier?:
+					| StoreIdentifierOption
+					| {
+							default: StoreIdentifierOption;
+							overrides?: Record<string, StoreIdentifierOption>;
+					  };
 				/**
-				 * disable cleaning up expired values when a verification value is
-				 * fetched
+				 * Store verification data in database even when secondary storage is configured.
+				 * @default false
 				 */
-				disableCleanup?: boolean;
-		  }
+				storeInDatabase?: boolean;
+		  })
 		| undefined;
 	/**
 	 * List of trusted origins.

package/src/types/plugin-client.ts

@@ -17,6 +17,7 @@ export interface ClientStore {
 export type ClientAtomListener = {
 	matcher: (path: string) => boolean;
 	signal: "$sessionSignal" | Omit<string, "$sessionSignal">;
+	callback?: (path: string) => void;
 };
 
 /**

package/src/types/plugin.ts

@@ -7,6 +7,7 @@ import type {
 import type { Migration } from "kysely";
 import type { AuthMiddleware } from "../api";
 import type { BetterAuthPluginDBSchema } from "../db";
+import type { RawError } from "../utils/error-codes";
 import type { AuthContext } from "./context";
 import type { Awaitable, LiteralString } from "./helper";
 import type { BetterAuthOptions } from "./init-options";
@@ -28,7 +29,14 @@ export type HookEndpointContext = Partial<
 	headers?: Headers | undefined;
 };
 
-export type BetterAuthPlugin = {
+export type BetterAuthPluginErrorCodePart = {
+	/**
+	 * The error codes returned by the plugin
+	 */
+	$ERROR_CODES?: Record<string, RawError>;
+};
+
+export type BetterAuthPlugin = BetterAuthPluginErrorCodePart & {
 	id: LiteralString;
 	/**
 	 * The init function is called when the plugin is initialized.
@@ -37,7 +45,8 @@ export type BetterAuthPlugin = {
 	init?:
 		| ((ctx: AuthContext) =>
 				| Awaitable<{
-						context?: DeepPartial<Omit<AuthContext, "options">>;
+						context?: DeepPartial<Omit<AuthContext, "options">> &
+							Record<string, unknown>;
 						options?: Partial<BetterAuthOptions>;
 				  }>
 				| void
@@ -142,10 +151,6 @@ export type BetterAuthPlugin = {
 				pathMatcher: (path: string) => boolean;
 		  }[]
 		| undefined;
-	/**
-	 * The error codes returned by the plugin
-	 */
-	$ERROR_CODES?: Record<string, { code: string; message: string }> | undefined;
 	/**
 	 * All database operations that are performed by the plugin
 	 *

package/src/types/secret.ts

@@ -0,0 +1,8 @@
+export interface SecretConfig {
+	/** Map of version number → secret value */
+	keys: Map<number, string>;
+	/** Version to use for new encryption (first entry in secrets array) */
+	currentVersion: number;
+	/** Legacy secret for bare-hex fallback (from BETTER_AUTH_SECRET) */
+	legacySecret?: string;
+}