better-auth 1.6.1 → 1.7.0-beta.0

package/dist/api/index.d.mts

@@ -249,7 +249,6 @@ declare function getEndpoints<Option extends BetterAuthOptions>(ctx: Awaitable<A
                 "application/json": {
                   schema: {
                     type: "object";
-                    nullable: boolean;
                     properties: {
                       session: {
                         $ref: string;
@@ -2239,7 +2238,6 @@ declare const router: <Option extends BetterAuthOptions>(ctx: AuthContext, optio
                 "application/json": {
                   schema: {
                     type: "object";
-                    nullable: boolean;
                     properties: {
                       session: {
                         $ref: string;

package/dist/api/routes/callback.mjs

@@ -104,7 +104,7 @@ const callbackOAuth = createAuthEndpoint("/callback/:id", {
 			return redirectOnError("unable_to_link_account");
 		}
 		if (userInfo.email?.toLowerCase() !== link.email.toLowerCase() && c.context.options.account?.accountLinking?.allowDifferentEmails !== true) return redirectOnError("email_doesn't_match");
-		const existingAccount = await c.context.internalAdapter.findAccount(String(userInfo.id));
+		const existingAccount = await c.context.internalAdapter.findAccountByProviderId(String(userInfo.id), provider.id);
 		if (existingAccount) {
 			if (existingAccount.userId.toString() !== link.userId.toString()) return redirectOnError("account_already_linked_to_different_user");
 			const updateData = Object.fromEntries(Object.entries({

package/dist/api/routes/password.mjs

@@ -82,7 +82,7 @@ const requestPasswordReset = createAuthEndpoint("/request-password-reset", {
 });
 const requestPasswordResetCallback = createAuthEndpoint("/reset-password/:token", {
 	method: "GET",
-	operationId: "forgetPasswordCallback",
+	operationId: "resetPasswordCallback",
 	query: z.object({ callbackURL: z.string().meta({ description: "The URL to redirect the user to reset their password" }) }),
 	use: [originCheck((ctx) => ctx.query.callbackURL)],
 	metadata: { openapi: {

package/dist/api/routes/session.d.mts

@@ -25,7 +25,6 @@ declare const getSession: <Option extends BetterAuthOptions>() => better_call0.S
             "application/json": {
               schema: {
                 type: "object";
-                nullable: boolean;
                 properties: {
                   session: {
                     $ref: string;

package/dist/api/routes/session.mjs

@@ -24,8 +24,7 @@ const getSession = () => createAuthEndpoint("/get-session", {
 		responses: { "200": {
 			description: "Success",
 			content: { "application/json": { schema: {
-				type: "object",
-				nullable: true,
+				type: ["object", "null"],
 				properties: {
 					session: { $ref: "#/components/schemas/Session" },
 					user: { $ref: "#/components/schemas/User" }

package/dist/integrations/next-js.mjs

@@ -24,20 +24,29 @@ const nextCookies = () => {
 				matcher(ctx) {
 					return ctx.path === "/get-session";
 				},
-				handler: createAuthMiddleware(async () => {
-					let cookieStore;
+				handler: createAuthMiddleware(async (ctx) => {
+					if ("_flag" in ctx && ctx._flag === "router") return;
+					let headersStore;
 					try {
-						const { cookies } = await import("next/headers.js");
-						cookieStore = await cookies();
+						const { headers } = await import("next/headers.js");
+						headersStore = await headers();
 					} catch {
 						return;
 					}
-					try {
-						cookieStore.set("__better-auth-cookie-store", "1", { maxAge: 0 });
-						cookieStore.delete("__better-auth-cookie-store");
-					} catch {
-						await setShouldSkipSessionRefresh(true);
-					}
+					/**
+					* Detect RSC via headers, NOT by probing cookies().set().
+					* In Next.js, cookies().set() unconditionally triggers router
+					* cache invalidation -- even if the value is unchanged.
+					*
+					* RSC sends `RSC: 1` without `next-action`. Only in that
+					* context cookies cannot be written -- skip session refresh
+					* to avoid DB/cookie mismatch.
+					*
+					* @see https://github.com/vercel/next.js/blob/8c5af211d580/packages/next/src/server/web/spec-extension/adapters/request-cookies.ts#L112-L157
+					*/
+					const isRSC = headersStore.get("RSC") === "1";
+					const isServerAction = !!headersStore.get("next-action");
+					if (isRSC && !isServerAction) await setShouldSkipSessionRefresh(true);
 				})
 			}],
 			after: [{
@@ -51,12 +60,12 @@ const nextCookies = () => {
 						const setCookies = returned?.get("set-cookie");
 						if (!setCookies) return;
 						const parsed = parseSetCookieHeader(setCookies);
-						const { cookies } = await import("next/headers.js");
 						let cookieHelper;
 						try {
+							const { cookies } = await import("next/headers.js");
 							cookieHelper = await cookies();
 						} catch (error) {
-							if (error instanceof Error && error.message.startsWith("`cookies` was called outside a request scope.")) return;
+							if (error instanceof Error && (error.message.startsWith("`cookies` was called outside a request scope.") || error.message.includes("Cannot find module"))) return;
 							throw error;
 						}
 						parsed.forEach((value, key) => {

package/dist/oauth2/state.d.mts

@@ -15,6 +15,7 @@ declare function parseState(c: GenericEndpointContext): Promise<{
   expiresAt: number;
   errorURL?: string | undefined;
   newUserURL?: string | undefined;
+  oauthState?: string | undefined;
   link?: {
     email: string;
     userId: string;

package/dist/package.mjs

@@ -1,4 +1,4 @@
 //#region package.json
-var version = "1.6.1";
+var version = "1.7.0-beta.0";
 //#endregion
 export { version };

package/dist/plugins/admin/admin.d.mts

@@ -775,11 +775,9 @@ declare const admin: <O extends AdminOptions>(options?: O | undefined) => {
       body: zod.ZodIntersection<zod.ZodObject<{
         userId: zod.ZodOptional<zod.ZodCoercedString<unknown>>;
         role: zod.ZodOptional<zod.ZodString>;
-      }, zod_v4_core0.$strip>, zod.ZodUnion<readonly [zod.ZodObject<{
+      }, zod_v4_core0.$strip>, zod.ZodXor<readonly [zod.ZodObject<{
         permission: zod.ZodRecord<zod.ZodString, zod.ZodArray<zod.ZodString>>;
-        permissions: zod.ZodUndefined;
       }, zod_v4_core0.$strip>, zod.ZodObject<{
-        permission: zod.ZodUndefined;
         permissions: zod.ZodRecord<zod.ZodString, zod.ZodArray<zod.ZodString>>;
       }, zod_v4_core0.$strip>]>>;
       metadata: {

package/dist/plugins/admin/routes.mjs

@@ -766,13 +766,7 @@ const setUserPassword = (opts) => createAuthEndpoint("/admin/set-user-password",
 const userHasPermissionBodySchema = z.object({
 	userId: z.coerce.string().optional().meta({ description: `The user id. Eg: "user-id"` }),
 	role: z.string().optional().meta({ description: `The role to check permission for. Eg: "admin"` })
-}).and(z.union([z.object({
-	permission: z.record(z.string(), z.array(z.string())),
-	permissions: z.undefined()
-}), z.object({
-	permission: z.undefined(),
-	permissions: z.record(z.string(), z.array(z.string()))
-})]));
+}).and(z.xor([z.object({ permission: z.record(z.string(), z.array(z.string())) }), z.object({ permissions: z.record(z.string(), z.array(z.string())) })]));
 /**
 * ### Endpoint
 *

package/dist/plugins/generic-oauth/index.mjs

@@ -14,6 +14,13 @@ import { APIError } from "@better-auth/core/error";
 import { createAuthorizationURL, refreshAccessToken, validateAuthorizationCode } from "@better-auth/core/oauth2";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/plugins/generic-oauth/index.ts
+function buildClientAssertion(config, tokenEndpoint) {
+	if (config.authentication !== "private_key_jwt" || !config.clientAssertion) return;
+	return {
+		...config.clientAssertion,
+		tokenEndpoint
+	};
+}
 /**
 * A generic OAuth plugin that can be used to add OAuth support to any provider
 */
@@ -87,7 +94,8 @@ const genericOAuth = (options) => {
 								redirectURI: c.redirectURI
 							},
 							tokenEndpoint: finalTokenUrl,
-							authentication: c.authentication
+							authentication: c.authentication,
+							clientAssertion: buildClientAssertion(c, finalTokenUrl)
 						});
 					},
 					async refreshAccessToken(refreshToken) {
@@ -107,6 +115,7 @@ const genericOAuth = (options) => {
 								clientSecret: c.clientSecret
 							},
 							authentication: c.authentication,
+							clientAssertion: buildClientAssertion(c, finalTokenUrl),
 							tokenEndpoint: finalTokenUrl
 						});
 					},

package/dist/plugins/generic-oauth/routes.mjs

@@ -195,6 +195,10 @@ const oAuth2Callback = (options) => createAuthEndpoint("/oauth2/callback/:provid
 				},
 				tokenEndpoint: finalTokenUrl,
 				authentication: providerConfig.authentication,
+				clientAssertion: providerConfig.authentication === "private_key_jwt" && providerConfig.clientAssertion ? {
+					...providerConfig.clientAssertion,
+					tokenEndpoint: finalTokenUrl
+				} : void 0,
 				additionalParams
 			});
 		}

package/dist/plugins/generic-oauth/types.d.mts

@@ -1,6 +1,6 @@
 import { GenericEndpointContext } from "@better-auth/core";
 import { User } from "@better-auth/core/db";
-import { OAuth2Tokens, OAuth2UserInfo } from "@better-auth/core/oauth2";
+import { ClientAssertionConfig, OAuth2Tokens, OAuth2UserInfo } from "@better-auth/core/oauth2";
 
 //#region src/plugins/generic-oauth/types.d.ts
 interface GenericOAuthOptions {
@@ -134,7 +134,12 @@ interface GenericOAuthConfig {
    * Authentication method for token requests.
    * @default "post"
    */
-  authentication?: ("basic" | "post") | undefined;
+  authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
+  /**
+   * Client assertion config for `private_key_jwt` authentication.
+   * Required when `authentication` is `"private_key_jwt"`.
+   */
+  clientAssertion?: ClientAssertionConfig | undefined;
   /**
    * Custom headers to include in the discovery request.
    * Useful for providers like Epic that require specific headers (e.g., Epic-Client-ID).

package/dist/plugins/jwt/utils.d.mts

@@ -16,7 +16,7 @@ declare function toExpJWT(expirationTime: number | Date | string, iat: number):
 declare function generateExportedKeyPair(options?: JwtOptions | undefined): Promise<{
   publicWebKey: jose.JWK;
   privateWebKey: jose.JWK;
-  alg: "EdDSA" | "ES256" | "ES512" | "PS256" | "RS256";
+  alg: "RS256" | "PS256" | "ES256" | "ES512" | "EdDSA";
   cfg: {
     crv?: "Ed25519" | undefined;
   } | {

package/dist/plugins/oauth-proxy/index.mjs

@@ -164,6 +164,10 @@ const oAuthProxy = (opts) => {
 						return;
 					}
 					const errorURL = stateData.errorURL || ctx.context.options.onAPIError?.errorURL || `${ctx.context.baseURL}/error`;
+					if (stateData.oauthState !== void 0 && stateData.oauthState !== statePackage.state) {
+						ctx.context.logger.error("OAuth proxy state binding mismatch");
+						throw redirectOnError(ctx, errorURL, "state_mismatch");
+					}
 					if (error) throw redirectOnError(ctx, errorURL, error);
 					if (!code) {
 						ctx.context.logger.error("OAuth callback missing authorization code");

package/dist/plugins/organization/organization.d.mts

@@ -99,11 +99,9 @@ declare const createHasPermission: <O extends OrganizationOptions>(options: O) =
   requireHeaders: true;
   body: z.ZodIntersection<z.ZodObject<{
     organizationId: z.ZodOptional<z.ZodString>;
-  }, z.core.$strip>, z.ZodUnion<readonly [z.ZodObject<{
+  }, z.core.$strip>, z.ZodXor<readonly [z.ZodObject<{
     permission: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
-    permissions: z.ZodUndefined;
   }, z.core.$strip>, z.ZodObject<{
-    permission: z.ZodUndefined;
     permissions: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
   }, z.core.$strip>]>>;
   use: ((inputContext: better_call0.MiddlewareInputContext<{

package/dist/plugins/organization/organization.mjs

@@ -18,13 +18,7 @@ import * as z from "zod";
 function parseRoles(roles) {
 	return Array.isArray(roles) ? roles.join(",") : roles;
 }
-const createHasPermissionBodySchema = z.object({ organizationId: z.string().optional() }).and(z.union([z.object({
-	permission: z.record(z.string(), z.array(z.string())),
-	permissions: z.undefined()
-}), z.object({
-	permission: z.undefined(),
-	permissions: z.record(z.string(), z.array(z.string()))
-})]));
+const createHasPermissionBodySchema = z.object({ organizationId: z.string().optional() }).and(z.xor([z.object({ permission: z.record(z.string(), z.array(z.string())) }), z.object({ permissions: z.record(z.string(), z.array(z.string())) })]));
 const createHasPermission = (options) => {
 	return createAuthEndpoint("/organization/has-permission", {
 		method: "POST",

package/dist/plugins/two-factor/client.d.mts

@@ -19,8 +19,18 @@ declare const twoFactorClient: (options?: {
   /**
    * a redirect function to call if a user needs to verify
    * their two factor
+   *
+   * @param context.twoFactorMethods - The list of
+   * enabled two factor providers (e.g. ["totp", "otp"]).
+   * Use this to determine which 2FA UI to show.
    */
-  onTwoFactorRedirect?: () => void | Promise<void>;
+  onTwoFactorRedirect?: (context: {
+    /**
+     * The list of enabled two factor providers
+     * for the user (e.g. ["totp", "otp"]).
+     */
+    twoFactorMethods?: string[];
+  }) => void | Promise<void>;
 } | undefined) => {
   id: "two-factor";
   version: string;
@@ -48,8 +58,10 @@ declare const twoFactorClient: (options?: {
   }[];
   $ERROR_CODES: {
     OTP_NOT_ENABLED: _better_auth_core_utils_error_codes0.RawError<"OTP_NOT_ENABLED">;
+    OTP_NOT_CONFIGURED: _better_auth_core_utils_error_codes0.RawError<"OTP_NOT_CONFIGURED">;
     OTP_HAS_EXPIRED: _better_auth_core_utils_error_codes0.RawError<"OTP_HAS_EXPIRED">;
     TOTP_NOT_ENABLED: _better_auth_core_utils_error_codes0.RawError<"TOTP_NOT_ENABLED">;
+    TOTP_NOT_CONFIGURED: _better_auth_core_utils_error_codes0.RawError<"TOTP_NOT_CONFIGURED">;
     TWO_FACTOR_NOT_ENABLED: _better_auth_core_utils_error_codes0.RawError<"TWO_FACTOR_NOT_ENABLED">;
     BACKUP_CODES_NOT_ENABLED: _better_auth_core_utils_error_codes0.RawError<"BACKUP_CODES_NOT_ENABLED">;
     INVALID_BACKUP_CODE: _better_auth_core_utils_error_codes0.RawError<"INVALID_BACKUP_CODE">;

package/dist/plugins/two-factor/client.mjs

@@ -26,7 +26,7 @@ const twoFactorClient = (options) => {
 			hooks: { async onSuccess(context) {
 				if (context.data?.twoFactorRedirect) {
 					if (options?.onTwoFactorRedirect) {
-						await options.onTwoFactorRedirect();
+						await options.onTwoFactorRedirect({ twoFactorMethods: context.data.twoFactorMethods });
 						return;
 					}
 					if (options?.twoFactorPage && typeof window !== "undefined") window.location.href = options.twoFactorPage;

package/dist/plugins/two-factor/error-code.d.mts

@@ -3,8 +3,10 @@ import * as _better_auth_core_utils_error_codes0 from "@better-auth/core/utils/e
 //#region src/plugins/two-factor/error-code.d.ts
 declare const TWO_FACTOR_ERROR_CODES: {
   OTP_NOT_ENABLED: _better_auth_core_utils_error_codes0.RawError<"OTP_NOT_ENABLED">;
+  OTP_NOT_CONFIGURED: _better_auth_core_utils_error_codes0.RawError<"OTP_NOT_CONFIGURED">;
   OTP_HAS_EXPIRED: _better_auth_core_utils_error_codes0.RawError<"OTP_HAS_EXPIRED">;
   TOTP_NOT_ENABLED: _better_auth_core_utils_error_codes0.RawError<"TOTP_NOT_ENABLED">;
+  TOTP_NOT_CONFIGURED: _better_auth_core_utils_error_codes0.RawError<"TOTP_NOT_CONFIGURED">;
   TWO_FACTOR_NOT_ENABLED: _better_auth_core_utils_error_codes0.RawError<"TWO_FACTOR_NOT_ENABLED">;
   BACKUP_CODES_NOT_ENABLED: _better_auth_core_utils_error_codes0.RawError<"BACKUP_CODES_NOT_ENABLED">;
   INVALID_BACKUP_CODE: _better_auth_core_utils_error_codes0.RawError<"INVALID_BACKUP_CODE">;

package/dist/plugins/two-factor/error-code.mjs

@@ -2,8 +2,10 @@ import { defineErrorCodes } from "@better-auth/core/utils/error-codes";
 //#region src/plugins/two-factor/error-code.ts
 const TWO_FACTOR_ERROR_CODES = defineErrorCodes({
 	OTP_NOT_ENABLED: "OTP not enabled",
+	OTP_NOT_CONFIGURED: "OTP is not available",
 	OTP_HAS_EXPIRED: "OTP has expired",
 	TOTP_NOT_ENABLED: "TOTP not enabled",
+	TOTP_NOT_CONFIGURED: "TOTP is not available",
 	TWO_FACTOR_NOT_ENABLED: "Two factor isn't enabled",
 	BACKUP_CODES_NOT_ENABLED: "Backup codes aren't enabled",
 	INVALID_BACKUP_CODE: "Invalid backup code",

package/dist/plugins/two-factor/index.d.mts

@@ -40,9 +40,17 @@ declare const twoFactor: <O extends TwoFactorOptions>(options?: O) => {
       method: "POST";
       body: z.ZodObject<{
         password: z.ZodOptional<z.ZodString>;
+        method: z.ZodDefault<z.ZodEnum<{
+          otp: "otp";
+          totp: "totp";
+        }>>;
         issuer: z.ZodOptional<z.ZodString>;
       }, z.core.$strip> | z.ZodObject<{
         password: z.ZodString;
+        method: z.ZodDefault<z.ZodEnum<{
+          otp: "otp";
+          totp: "totp";
+        }>>;
         issuer: z.ZodOptional<z.ZodString>;
       }, z.core.$strip>;
       use: ((inputContext: better_call0.MiddlewareInputContext<better_call0.MiddlewareOptions>) => Promise<{
@@ -80,6 +88,11 @@ declare const twoFactor: <O extends TwoFactorOptions>(options?: O) => {
                   schema: {
                     type: "object";
                     properties: {
+                      method: {
+                        type: string;
+                        enum: string[];
+                        description: string;
+                      };
                       totpURI: {
                         type: string;
                         description: string;
@@ -92,6 +105,7 @@ declare const twoFactor: <O extends TwoFactorOptions>(options?: O) => {
                         description: string;
                       };
                     };
+                    required: string[];
                   };
                 };
               };
@@ -100,6 +114,9 @@ declare const twoFactor: <O extends TwoFactorOptions>(options?: O) => {
         };
       };
     }, {
+      method: "otp";
+    } | {
+      method: "totp";
       totpURI: string;
       backupCodes: string[];
     }>;
@@ -618,6 +635,7 @@ declare const twoFactor: <O extends TwoFactorOptions>(options?: O) => {
       matcher(context: _better_auth_core0.HookEndpointContext): boolean;
       handler: (inputContext: better_call0.MiddlewareInputContext<better_call0.MiddlewareOptions>) => Promise<{
         twoFactorRedirect: boolean;
+        twoFactorMethods: string[];
       } | undefined>;
     }[];
   };
@@ -655,6 +673,12 @@ declare const twoFactor: <O extends TwoFactorOptions>(options?: O) => {
           };
           index: true;
         };
+        verified: {
+          type: "boolean";
+          required: false;
+          defaultValue: true;
+          input: false;
+        };
       };
     };
   };
@@ -665,8 +689,10 @@ declare const twoFactor: <O extends TwoFactorOptions>(options?: O) => {
   }[];
   $ERROR_CODES: {
     OTP_NOT_ENABLED: _better_auth_core_utils_error_codes0.RawError<"OTP_NOT_ENABLED">;
+    OTP_NOT_CONFIGURED: _better_auth_core_utils_error_codes0.RawError<"OTP_NOT_CONFIGURED">;
     OTP_HAS_EXPIRED: _better_auth_core_utils_error_codes0.RawError<"OTP_HAS_EXPIRED">;
     TOTP_NOT_ENABLED: _better_auth_core_utils_error_codes0.RawError<"TOTP_NOT_ENABLED">;
+    TOTP_NOT_CONFIGURED: _better_auth_core_utils_error_codes0.RawError<"TOTP_NOT_CONFIGURED">;
     TWO_FACTOR_NOT_ENABLED: _better_auth_core_utils_error_codes0.RawError<"TWO_FACTOR_NOT_ENABLED">;
     BACKUP_CODES_NOT_ENABLED: _better_auth_core_utils_error_codes0.RawError<"BACKUP_CODES_NOT_ENABLED">;
     INVALID_BACKUP_CODE: _better_auth_core_utils_error_codes0.RawError<"INVALID_BACKUP_CODE">;

package/dist/plugins/two-factor/index.mjs

@@ -36,12 +36,16 @@ const twoFactor = (options) => {
 	});
 	const otp = otp2fa(options?.otpOptions);
 	const passwordSchema = z.string().meta({ description: "User password" });
+	const methodField = z.enum(["otp", "totp"]).default("totp").meta({ description: "The 2FA method to enable. 'totp' generates an authenticator app secret (requires verification). 'otp' enables email/SMS-based codes immediately." });
+	const issuerField = z.string().meta({ description: "Custom issuer for the TOTP URI" }).optional();
 	const enableTwoFactorBodySchema = allowPasswordless ? z.object({
 		password: passwordSchema.optional(),
-		issuer: z.string().meta({ description: "Custom issuer for the TOTP URI" }).optional()
+		method: methodField,
+		issuer: issuerField
 	}) : z.object({
 		password: passwordSchema,
-		issuer: z.string().meta({ description: "Custom issuer for the TOTP URI" }).optional()
+		method: methodField,
+		issuer: issuerField
 	});
 	const disableTwoFactorBodySchema = allowPasswordless ? z.object({ password: passwordSchema.optional() }) : z.object({ password: passwordSchema });
 	return {
@@ -57,28 +61,34 @@ const twoFactor = (options) => {
 				use: [sessionMiddleware],
 				metadata: { openapi: {
 					summary: "Enable two factor authentication",
-					description: "Use this endpoint to enable two factor authentication. This will generate a TOTP URI and backup codes. Once the user verifies the TOTP URI, the two factor authentication will be enabled.",
+					description: "Enable two factor authentication. Pass method 'totp' (default) to set up an authenticator app (returns TOTP URI and backup codes), or 'otp' to enable email/SMS-based codes immediately.",
 					responses: { 200: {
 						description: "Successful response",
 						content: { "application/json": { schema: {
 							type: "object",
 							properties: {
+								method: {
+									type: "string",
+									enum: ["otp", "totp"],
+									description: "The 2FA method that was enabled."
+								},
 								totpURI: {
 									type: "string",
-									description: "TOTP URI"
+									description: "TOTP URI for authenticator app setup. Only present when method is 'totp'."
 								},
 								backupCodes: {
 									type: "array",
 									items: { type: "string" },
-									description: "Backup codes"
+									description: "Recovery backup codes. Only present when method is 'totp'."
 								}
-							}
+							},
+							required: ["method"]
 						} } }
 					} }
 				} }
 			}, async (ctx) => {
 				const user = ctx.context.session.user;
-				const { password, issuer } = ctx.body;
+				const { password, issuer, method } = ctx.body;
 				if (await shouldRequirePassword(ctx, user.id, allowPasswordless)) {
 					if (!password) throw APIError.from("BAD_REQUEST", BASE_ERROR_CODES.INVALID_PASSWORD);
 					if (!await validatePassword(ctx, {
@@ -86,35 +96,46 @@ const twoFactor = (options) => {
 						userId: user.id
 					})) throw APIError.from("BAD_REQUEST", BASE_ERROR_CODES.INVALID_PASSWORD);
 				}
-				const secret = generateRandomString(32);
-				const encryptedSecret = await symmetricEncrypt({
-					key: ctx.context.secretConfig,
-					data: secret
-				});
-				const backupCodes = await generateBackupCodes(ctx.context.secretConfig, backupCodeOptions);
-				if (options?.skipVerificationOnEnable) {
+				if (method === "otp" && !options?.otpOptions?.sendOTP) throw APIError.from("BAD_REQUEST", TWO_FACTOR_ERROR_CODES.OTP_NOT_CONFIGURED);
+				if (method === "totp" && options?.totpOptions?.disable) throw APIError.from("BAD_REQUEST", TWO_FACTOR_ERROR_CODES.TOTP_NOT_CONFIGURED);
+				if (method === "otp") {
 					const updatedUser = await ctx.context.internalAdapter.updateUser(user.id, { twoFactorEnabled: true });
-					/**
-					* Update the session cookie with the new user data
-					*/
 					await setSessionCookie(ctx, {
 						session: await ctx.context.internalAdapter.createSession(updatedUser.id, false, ctx.context.session.session),
 						user: updatedUser
 					});
 					await ctx.context.internalAdapter.deleteSession(ctx.context.session.session.token);
+					return ctx.json({ method: "otp" });
 				}
-				await ctx.context.adapter.deleteMany({
+				const backupCodes = await generateBackupCodes(ctx.context.secretConfig, backupCodeOptions);
+				const existingTwoFactor = await ctx.context.adapter.findOne({
 					model: opts.twoFactorTable,
 					where: [{
 						field: "userId",
 						value: user.id
 					}]
 				});
-				await ctx.context.adapter.create({
+				const secret = generateRandomString(32);
+				const totpData = {
+					secret: await symmetricEncrypt({
+						key: ctx.context.secretConfig,
+						data: secret
+					}),
+					backupCodes: backupCodes.encryptedBackupCodes,
+					verified: existingTwoFactor != null && existingTwoFactor.verified === true
+				};
+				if (existingTwoFactor) await ctx.context.adapter.update({
+					model: opts.twoFactorTable,
+					update: totpData,
+					where: [{
+						field: "id",
+						value: existingTwoFactor.id
+					}]
+				});
+				else await ctx.context.adapter.create({
 					model: opts.twoFactorTable,
 					data: {
-						secret: encryptedSecret,
-						backupCodes: backupCodes.encryptedBackupCodes,
+						...totpData,
 						userId: user.id
 					}
 				});
@@ -123,6 +144,7 @@ const twoFactor = (options) => {
 					period: options?.totpOptions?.period
 				}).url(issuer || options?.issuer || ctx.context.appName, user.email);
 				return ctx.json({
+					method: "totp",
 					totpURI,
 					backupCodes: backupCodes.backupCodes
 				});
@@ -225,7 +247,30 @@ const twoFactor = (options) => {
 					expiresAt: new Date(Date.now() + maxAge * 1e3)
 				});
 				await ctx.setSignedCookie(twoFactorCookie.name, identifier, ctx.context.secret, twoFactorCookie.attributes);
-				return ctx.json({ twoFactorRedirect: true });
+				const twoFactorMethods = [];
+				/**
+				* totp requires per-user setup, so we check
+				* that the user actually has a secret stored.
+				*/
+				if (!options?.totpOptions?.disable) {
+					const userTotpSecret = await ctx.context.adapter.findOne({
+						model: opts.twoFactorTable,
+						where: [{
+							field: "userId",
+							value: data.user.id
+						}]
+					});
+					if (userTotpSecret && userTotpSecret.verified !== false) twoFactorMethods.push("totp");
+				}
+				/**
+				* otp is server-level — if sendOTP is configured,
+				* any user with 2fa enabled can receive a code.
+				*/
+				if (options?.otpOptions?.sendOTP) twoFactorMethods.push("otp");
+				return ctx.json({
+					twoFactorRedirect: true,
+					twoFactorMethods
+				});
 			})
 		}] },
 		schema: mergeSchema(schema, {

package/dist/plugins/two-factor/otp/index.mjs

@@ -175,11 +175,11 @@ const otp2fa = (options) => {
 						if (!session.session) throw APIError.from("BAD_REQUEST", BASE_ERROR_CODES.FAILED_TO_CREATE_SESSION);
 						const updatedUser = await ctx.context.internalAdapter.updateUser(session.user.id, { twoFactorEnabled: true });
 						const newSession = await ctx.context.internalAdapter.createSession(session.user.id, false, session.session);
-						await ctx.context.internalAdapter.deleteSession(session.session.token);
 						await setSessionCookie(ctx, {
 							session: newSession,
 							user: updatedUser
 						});
+						await ctx.context.internalAdapter.deleteSession(session.session.token);
 						return ctx.json({
 							token: newSession.token,
 							user: parseUserOutput(ctx.context.options, updatedUser)

package/dist/plugins/two-factor/schema.d.mts

@@ -33,6 +33,12 @@ declare const schema: {
         };
         index: true;
       };
+      verified: {
+        type: "boolean";
+        required: false;
+        defaultValue: true;
+        input: false;
+      };
     };
   };
 };

package/dist/plugins/two-factor/schema.mjs

@@ -27,6 +27,12 @@ const schema = {
 				field: "id"
 			},
 			index: true
+		},
+		verified: {
+			type: "boolean",
+			required: false,
+			defaultValue: true,
+			input: false
 		}
 	} }
 };

package/dist/plugins/two-factor/totp/index.mjs

@@ -124,6 +124,7 @@ const totp2fa = (options) => {
 				}
 				const { session, valid, invalid } = await verifyTwoFactor(ctx);
 				const user = session.user;
+				const isSignIn = !session.session;
 				const twoFactor = await ctx.context.adapter.findOne({
 					model: twoFactorTable,
 					where: [{
@@ -132,6 +133,7 @@ const totp2fa = (options) => {
 					}]
 				});
 				if (!twoFactor) throw APIError.from("BAD_REQUEST", TWO_FACTOR_ERROR_CODES.TOTP_NOT_ENABLED);
+				if (isSignIn && twoFactor.verified === false) throw APIError.from("BAD_REQUEST", TWO_FACTOR_ERROR_CODES.TOTP_NOT_ENABLED);
 				if (!await createOTP(await symmetricDecrypt({
 					key: ctx.context.secretConfig,
 					data: twoFactor.secret
@@ -139,16 +141,23 @@ const totp2fa = (options) => {
 					period: opts.period,
 					digits: opts.digits
 				}).verify(ctx.body.code)) return invalid("INVALID_CODE");
-				if (!user.twoFactorEnabled) {
-					if (!session.session) throw APIError.from("BAD_REQUEST", BASE_ERROR_CODES.FAILED_TO_CREATE_SESSION);
-					const updatedUser = await ctx.context.internalAdapter.updateUser(user.id, { twoFactorEnabled: true });
-					const newSession = await ctx.context.internalAdapter.createSession(user.id, false, session.session).catch((e) => {
-						throw e;
-					});
-					await ctx.context.internalAdapter.deleteSession(session.session.token);
-					await setSessionCookie(ctx, {
-						session: newSession,
-						user: updatedUser
+				if (twoFactor.verified !== true) {
+					if (!user.twoFactorEnabled) {
+						const activeSession = session.session;
+						const updatedUser = await ctx.context.internalAdapter.updateUser(user.id, { twoFactorEnabled: true });
+						await setSessionCookie(ctx, {
+							session: await ctx.context.internalAdapter.createSession(user.id, false, activeSession),
+							user: updatedUser
+						});
+						await ctx.context.internalAdapter.deleteSession(activeSession.token);
+					}
+					await ctx.context.adapter.update({
+						model: twoFactorTable,
+						update: { verified: true },
+						where: [{
+							field: "id",
+							value: twoFactor.id
+						}]
 					});
 				}
 				return valid(ctx);

package/dist/plugins/two-factor/types.d.mts

@@ -31,11 +31,6 @@ interface TwoFactorOptions {
    * Backup code options
    */
   backupCodeOptions?: BackupCodeOptions | undefined;
-  /**
-   * Skip verification on enabling two factor authentication.
-   * @default false
-   */
-  skipVerificationOnEnable?: boolean | undefined;
   /**
    * Allow enabling and managing 2FA without a password when the user does not
    * have a credential account (e.g. passkey-only users).
@@ -80,7 +75,7 @@ interface TwoFactorTable {
   userId: string;
   secret: string;
   backupCodes: string;
-  enabled: boolean;
+  verified: boolean;
 }
 //#endregion
 export { TwoFactorOptions, TwoFactorProvider, TwoFactorTable, UserWithTwoFactor };

package/dist/state.d.mts

@@ -9,6 +9,11 @@ declare const stateDataSchema: z.ZodObject<{
   errorURL: z.ZodOptional<z.ZodString>;
   newUserURL: z.ZodOptional<z.ZodString>;
   expiresAt: z.ZodNumber;
+  /**
+   * CSRF nonce returned to the OAuth provider. When using cookie state storage,
+   * this must match the callback `state` query parameter.
+   */
+  oauthState: z.ZodOptional<z.ZodString>;
   link: z.ZodOptional<z.ZodObject<{
     email: z.ZodString;
     userId: z.ZodCoercedString<unknown>;
@@ -32,6 +37,7 @@ declare function parseGenericState(c: GenericEndpointContext, state: string, set
   expiresAt: number;
   errorURL?: string | undefined;
   newUserURL?: string | undefined;
+  oauthState?: string | undefined;
   link?: {
     email: string;
     userId: string;

package/dist/state.mjs

@@ -10,6 +10,7 @@ const stateDataSchema = z.looseObject({
 	errorURL: z.string().optional(),
 	newUserURL: z.string().optional(),
 	expiresAt: z.number(),
+	oauthState: z.string().optional(),
 	link: z.object({
 		email: z.string(),
 		userId: z.coerce.string()
@@ -28,9 +29,13 @@ var StateError = class extends BetterAuthError {
 async function generateGenericState(c, stateData, settings) {
 	const state = generateRandomString(32);
 	if (c.context.oauthConfig.storeStateStrategy === "cookie") {
+		const payload = {
+			...stateData,
+			oauthState: state
+		};
 		const encryptedData = await symmetricEncrypt({
 			key: c.context.secretConfig,
-			data: JSON.stringify(stateData)
+			data: JSON.stringify(payload)
 		});
 		const stateCookie = c.context.createAuthCookie(settings?.cookieName ?? "oauth_state", { maxAge: 600 });
 		c.setCookie(stateCookie.name, encryptedData, stateCookie.attributes);
@@ -44,7 +49,10 @@ async function generateGenericState(c, stateData, settings) {
 	const expiresAt = /* @__PURE__ */ new Date();
 	expiresAt.setMinutes(expiresAt.getMinutes() + 10);
 	if (!await c.context.internalAdapter.createVerificationValue({
-		value: JSON.stringify(stateData),
+		value: JSON.stringify({
+			...stateData,
+			oauthState: state
+		}),
 		identifier: state,
 		expiresAt
 	})) throw new StateError("Unable to create verification. Make sure the database adapter is properly working and there is a verification table in the database", { code: "state_generation_error" });
@@ -76,6 +84,10 @@ async function parseGenericState(c, state, settings) {
 				cause: error
 			});
 		}
+		if (!parsedData.oauthState || parsedData.oauthState !== state) throw new StateError("State mismatch: OAuth state parameter does not match stored state", {
+			code: "state_security_mismatch",
+			details: { state }
+		});
 		expireCookie(c, stateCookie);
 	} else {
 		const data = await c.context.internalAdapter.findVerificationValue(state);
@@ -84,6 +96,10 @@ async function parseGenericState(c, state, settings) {
 			details: { state }
 		});
 		parsedData = stateDataSchema.parse(JSON.parse(data.value));
+		if (parsedData.oauthState !== void 0 && parsedData.oauthState !== state) throw new StateError("State mismatch: OAuth state parameter does not match stored state", {
+			code: "state_security_mismatch",
+			details: { state }
+		});
 		const stateCookie = c.context.createAuthCookie(settings?.cookieName ?? "state");
 		const stateCookieValue = await c.getSignedCookie(stateCookie.name, c.context.secret);
 		if (!(settings?.skipStateCookieCheck ?? c.context.oauthConfig.skipStateCookieCheck) && (!stateCookieValue || stateCookieValue !== state)) throw new StateError("State mismatch: State not persisted correctly", {

package/dist/test-utils/test-instance.d.mts

@@ -261,7 +261,6 @@ declare function getTestInstance<O extends Partial<BetterAuthOptions>, C extends
                 "application/json": {
                   schema: {
                     type: "object";
-                    nullable: boolean;
                     properties: {
                       session: {
                         $ref: string;
@@ -2265,7 +2264,6 @@ declare function getTestInstance<O extends Partial<BetterAuthOptions>, C extends
                 "application/json": {
                   schema: {
                     type: "object";
-                    nullable: boolean;
                     properties: {
                       session: {
                         $ref: string;
@@ -4272,7 +4270,6 @@ declare function getTestInstance<O extends Partial<BetterAuthOptions>, C extends
                     "application/json": {
                       schema: {
                         type: "object";
-                        nullable: boolean;
                         properties: {
                           session: {
                             $ref: string;
@@ -6276,7 +6273,6 @@ declare function getTestInstance<O extends Partial<BetterAuthOptions>, C extends
                     "application/json": {
                       schema: {
                         type: "object";
-                        nullable: boolean;
                         properties: {
                           session: {
                             $ref: string;
@@ -8354,7 +8350,6 @@ declare function getTestInstance<O extends Partial<BetterAuthOptions>, C extends
                     "application/json": {
                       schema: {
                         type: "object";
-                        nullable: boolean;
                         properties: {
                           session: {
                             $ref: string;
@@ -10358,7 +10353,6 @@ declare function getTestInstance<O extends Partial<BetterAuthOptions>, C extends
                     "application/json": {
                       schema: {
                         type: "object";
-                        nullable: boolean;
                         properties: {
                           session: {
                             $ref: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "better-auth",
-  "version": "1.6.1",
+  "version": "1.7.0-beta.0",
   "description": "The most comprehensive authentication framework for TypeScript.",
   "type": "module",
   "license": "MIT",
@@ -489,13 +489,13 @@
     "kysely": "^0.28.14",
     "nanostores": "^1.1.1",
     "zod": "^4.3.6",
-    "@better-auth/core": "1.6.1",
-    "@better-auth/drizzle-adapter": "1.6.1",
-    "@better-auth/kysely-adapter": "1.6.1",
-    "@better-auth/memory-adapter": "1.6.1",
-    "@better-auth/mongo-adapter": "1.6.1",
-    "@better-auth/prisma-adapter": "1.6.1",
-    "@better-auth/telemetry": "1.6.1"
+    "@better-auth/core": "1.7.0-beta.0",
+    "@better-auth/drizzle-adapter": "1.7.0-beta.0",
+    "@better-auth/kysely-adapter": "1.7.0-beta.0",
+    "@better-auth/memory-adapter": "1.7.0-beta.0",
+    "@better-auth/mongo-adapter": "1.7.0-beta.0",
+    "@better-auth/prisma-adapter": "1.7.0-beta.0",
+    "@better-auth/telemetry": "1.7.0-beta.0"
   },
   "devDependencies": {
     "@lynx-js/react": "^0.116.3",