@better-auth/core 1.6.10 → 1.6.11

package/dist/context/global.mjs

@@ -2,7 +2,7 @@
 const symbol = Symbol.for("better-auth:global");
 let bind = null;
 const __context = {};
-const __betterAuthVersion = "1.6.10";
+const __betterAuthVersion = "1.6.11";
 /**
 * We store context instance in the globalThis.
 *

package/dist/db/adapter/factory.mjs

@@ -57,6 +57,7 @@ const createAdapterFactory = ({ adapter: customAdapter, config: cfg }) => (optio
 					else if (method === "findMany" && !config.debugLogs.findMany) return;
 					else if (method === "delete" && !config.debugLogs.delete) return;
 					else if (method === "deleteMany" && !config.debugLogs.deleteMany) return;
+					else if (method === "consumeOne" && !config.debugLogs.consumeOne) return;
 					else if (method === "count" && !config.debugLogs.count) return;
 				}
 				logger.info(`[${config.adapterName}]`, ...args);
@@ -676,6 +677,65 @@ const createAdapterFactory = ({ adapter: customAdapter, config: cfg }) => (optio
 			});
 			return res;
 		},
+		consumeOne: async ({ model: unsafeModel, where: unsafeWhere }) => {
+			transactionId++;
+			const thisTransactionId = transactionId;
+			const model = getModelName(unsafeModel);
+			const where = transformWhereClause({
+				model: unsafeModel,
+				where: unsafeWhere,
+				action: "consumeOne"
+			});
+			unsafeModel = getDefaultModelName(unsafeModel);
+			debugLog({ method: "consumeOne" }, `${formatTransactionId(thisTransactionId)} ${formatStep(1, 3)}`, `${formatMethod("consumeOne")} ${formatAction("ConsumeOne")}:`, {
+				model,
+				where
+			});
+			let res;
+			let resultNeedsOutputTransform = true;
+			if (adapterInstance.consumeOne) res = await withSpan(`db consumeOne ${model}`, {
+				[ATTR_DB_OPERATION_NAME]: "consumeOne",
+				[ATTR_DB_COLLECTION_NAME]: model
+			}, () => adapterInstance.consumeOne({
+				model,
+				where
+			}));
+			else {
+				res = await withSpan(`db consumeOne ${model}`, {
+					[ATTR_DB_OPERATION_NAME]: "consumeOne",
+					[ATTR_DB_COLLECTION_NAME]: model
+				}, () => adapter.transaction(async (trx) => {
+					const target = (await trx.findMany({
+						model: unsafeModel,
+						where: unsafeWhere,
+						limit: 1
+					}))[0];
+					if (!target) return null;
+					return await trx.deleteMany({
+						model: unsafeModel,
+						where: [...unsafeWhere, {
+							field: "id",
+							value: target.id,
+							operator: "eq",
+							connector: "AND",
+							mode: "sensitive"
+						}]
+					}) > 0 ? target : null;
+				}));
+				resultNeedsOutputTransform = false;
+			}
+			debugLog({ method: "consumeOne" }, `${formatTransactionId(thisTransactionId)} ${formatStep(2, 3)}`, `${formatMethod("consumeOne")} ${formatAction("DB Result")}:`, {
+				model,
+				data: res
+			});
+			let transformed = res;
+			if (!config.disableTransformOutput && resultNeedsOutputTransform && res) transformed = await transformOutput(res, unsafeModel, void 0, void 0);
+			debugLog({ method: "consumeOne" }, `${formatTransactionId(thisTransactionId)} ${formatStep(3, 3)}`, `${formatMethod("consumeOne")} ${formatAction("Parsed Result")}:`, {
+				model,
+				data: transformed
+			});
+			return transformed;
+		},
 		count: async ({ model: unsafeModel, where: unsafeWhere }) => {
 			transactionId++;
 			const thisTransactionId = transactionId;

package/dist/db/adapter/index.d.mts

@@ -22,6 +22,7 @@ type DBAdapterDebugLogOption = boolean | {
   findMany?: boolean | undefined;
   delete?: boolean | undefined;
   deleteMany?: boolean | undefined;
+  consumeOne?: boolean | undefined;
   count?: boolean | undefined;
 } | {
   /**
@@ -197,7 +198,7 @@ interface DBAdapterFactoryConfig<Options extends BetterAuthOptions = BetterAuthO
     /**
      * The action which was called from the adapter.
      */
-    action: "create" | "update" | "findOne" | "findMany" | "updateMany" | "delete" | "deleteMany" | "count";
+    action: "create" | "update" | "findOne" | "findMany" | "updateMany" | "delete" | "deleteMany" | "consumeOne" | "count";
     /**
      * The model name.
      */
@@ -415,6 +416,26 @@ type DBAdapter<Options extends BetterAuthOptions = BetterAuthOptions> = {
     model: string;
     where: Where[];
   }) => Promise<number>;
+  /**
+   * Atomically consume a single row matching the where clause: delete it and
+   * return the deleted row, or return `null` if no row matched.
+   * Implementations MUST NOT delete any additional rows that also match a
+   * non-unique predicate.
+   *
+   * Under concurrent invocation against the same row, exactly one caller
+   * receives the row; subsequent racers receive `null`. This is the
+   * race-safe primitive for consuming single-use credentials
+   * (verification tokens, authorization codes, one-time tokens).
+   *
+   * Always defined on the factory-wrapped adapter. When the underlying
+   * `CustomAdapter` does not implement `consumeOne`, the factory provides
+   * a fallback that wraps `findMany + deleteMany` in `transaction(...)`
+   * and returns the row only when the delete reports an affected row.
+   */
+  consumeOne: <T>(data: {
+    model: string;
+    where: Where[];
+  }) => Promise<T | null>;
   /**
    * Execute multiple operations in a transaction.
    * If the adapter doesn't support transactions, operations will be executed sequentially.
@@ -496,6 +517,19 @@ interface CustomAdapter {
     model: string;
     where: CleanedWhere[];
   }) => Promise<number>;
+  /**
+   * Optional native atomic single-row consume. When omitted, the adapter
+   * factory falls back to `transaction(findMany + deleteMany)`.
+   * Implementing this method natively (e.g. `DELETE ... RETURNING *`,
+   * `findOneAndDelete`, `OUTPUT deleted.*`) gives one round trip and the
+   * strongest race-safety guarantee. Implementations must delete at most
+   * one matching row. TODO(consume-one-required): tighten to required in the
+   * next minor on `next`.
+   */
+  consumeOne?: <T>(data: {
+    model: string;
+    where: CleanedWhere[];
+  }) => Promise<T | null>;
   count: ({
     model,
     where

package/dist/db/adapter/types.d.mts

@@ -94,7 +94,7 @@ type AdapterFactoryCustomizeAdapterCreator = (config: {
   }: {
     where: W;
     model: string;
-    action: "create" | "update" | "findOne" | "findMany" | "updateMany" | "delete" | "deleteMany" | "count";
+    action: "create" | "update" | "findOne" | "findMany" | "updateMany" | "delete" | "deleteMany" | "consumeOne" | "count";
   }) => W extends undefined ? undefined : CleanedWhere[];
 }) => CustomAdapter;
 type AdapterTestDebugLogs = {

package/dist/db/type.d.mts

@@ -141,6 +141,18 @@ interface SecondaryStorage {
    * @returns - Value of the key
    */
   get: (key: string) => Awaitable<unknown>;
+  /**
+   * Atomically get a value and delete it from storage.
+   *
+   * This is optional for backwards compatibility with existing secondary
+   * storage implementations. Single-use credential consumers use it when
+   * present to avoid a read-then-delete race.
+   *
+   * TODO(secondary-storage-atomic-consume): make this required in the next
+   * breaking release, or require database-backed verification storage for
+   * security-sensitive consume paths.
+   */
+  getAndDelete?: (key: string) => Awaitable<unknown>;
   set: (
   /**
    * Key to store

package/dist/error/codes.d.mts

@@ -36,6 +36,7 @@ declare const BASE_ERROR_CODES: {
   USER_ALREADY_EXISTS: RawError<"USER_ALREADY_EXISTS">;
   USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL: RawError<"USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL">;
   EMAIL_CAN_NOT_BE_UPDATED: RawError<"EMAIL_CAN_NOT_BE_UPDATED">;
+  CHANGE_EMAIL_DISABLED: RawError<"CHANGE_EMAIL_DISABLED">;
   CREDENTIAL_ACCOUNT_NOT_FOUND: RawError<"CREDENTIAL_ACCOUNT_NOT_FOUND">;
   ACCOUNT_NOT_FOUND: RawError<"ACCOUNT_NOT_FOUND">;
   SESSION_EXPIRED: RawError<"SESSION_EXPIRED">;

package/dist/error/codes.mjs

@@ -23,6 +23,7 @@ const BASE_ERROR_CODES = defineErrorCodes({
 	USER_ALREADY_EXISTS: "User already exists.",
 	USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL: "User already exists. Use another email.",
 	EMAIL_CAN_NOT_BE_UPDATED: "Email can not be updated",
+	CHANGE_EMAIL_DISABLED: "Change email is disabled",
 	CREDENTIAL_ACCOUNT_NOT_FOUND: "Credential account not found",
 	SESSION_EXPIRED: "Session expired. Re-authenticate to perform this action.",
 	FAILED_TO_UNLINK_LAST_ACCOUNT: "You can't unlink your last account",

package/dist/instrumentation/tracer.mjs

@@ -2,7 +2,7 @@ import { ATTR_HTTP_RESPONSE_STATUS_CODE } from "./attributes.mjs";
 import { getOpenTelemetryAPI } from "./api.mjs";
 //#region src/instrumentation/tracer.ts
 const INSTRUMENTATION_SCOPE = "better-auth";
-const INSTRUMENTATION_VERSION = "1.6.10";
+const INSTRUMENTATION_VERSION = "1.6.11";
 /**
 * Better-auth uses `throw ctx.redirect(url)` for flow control (e.g. OAuth
 * callbacks). These are APIErrors with 3xx status codes and should not be

package/dist/types/context.d.mts

@@ -114,6 +114,18 @@ interface InternalAdapter<_Options extends BetterAuthOptions = BetterAuthOptions
   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. 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>;
   updateVerificationByIdentifier(identifier: string, data: Partial<Verification>): Promise<Verification>;
   refreshUserSessions(user: User): Promise<void>;
 }

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

@@ -157,12 +157,13 @@ 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;
   } | undefined;
   /**
    * Force cookies to always use the `Secure` attribute. By default,
@@ -906,6 +907,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

package/dist/utils/ip.d.mts

@@ -10,12 +10,13 @@
  */
 interface NormalizeIPOptions {
   /**
-   * For IPv6 addresses, extract the subnet prefix instead of full address.
-   * Common values: 32, 48, 64, 128 (default: 128 = full address)
+   * Prefix length used to collapse IPv6 addresses before keying.
+   * Any integer from 0 to 128 is accepted. Common values: 32, 48, 56, 64, 128.
+   * Values outside 0-128 are clamped.
    *
-   * @default 128
+   * @default 64
    */
-  ipv6Subnet?: 128 | 64 | 48 | 32;
+  ipv6Subnet?: number;
 }
 /**
  * Checks if an IP is valid IPv4 or IPv6

package/dist/utils/ip.mjs

@@ -60,8 +60,8 @@ function expandIPv6(ipv6) {
 */
 function normalizeIPv6(ipv6, subnetPrefix) {
 	const groups = expandIPv6(ipv6);
-	if (subnetPrefix && subnetPrefix < 128) {
-		let bitsRemaining = subnetPrefix;
+	if (subnetPrefix !== void 0 && subnetPrefix < 128) {
+		let bitsRemaining = Math.max(0, Math.floor(subnetPrefix));
 		return groups.map((group) => {
 			if (bitsRemaining <= 0) return "0000";
 			if (bitsRemaining >= 16) {
@@ -99,7 +99,7 @@ function normalizeIP(ip, options = {}) {
 	if (!isIPv6(ip)) return ip.toLowerCase();
 	const ipv4 = extractIPv4FromMapped(ip);
 	if (ipv4) return ipv4.toLowerCase();
-	return normalizeIPv6(ip, options.ipv6Subnet || 64);
+	return normalizeIPv6(ip, options.ipv6Subnet ?? 64);
 }
 /**
 * Creates a rate limit key from IP and path

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/core",
-  "version": "1.6.10",
+  "version": "1.6.11",
   "description": "The most comprehensive authentication framework for TypeScript.",
   "type": "module",
   "license": "MIT",
@@ -93,12 +93,13 @@
     "./instrumentation": {
       "dev-source": "./src/instrumentation/index.ts",
       "types": "./dist/instrumentation/index.d.mts",
+      "workerd": "./dist/instrumentation/pure.index.mjs",
+      "edge": "./dist/instrumentation/pure.index.mjs",
+      "browser": "./dist/instrumentation/pure.index.mjs",
       "node": "./dist/instrumentation/index.mjs",
       "deno": "./dist/instrumentation/index.mjs",
       "bun": "./dist/instrumentation/index.mjs",
-      "edge": "./dist/instrumentation/pure.index.mjs",
-      "workerd": "./dist/instrumentation/pure.index.mjs",
-      "browser": "./dist/instrumentation/pure.index.mjs",
+      "import": "./dist/instrumentation/index.mjs",
       "default": "./dist/instrumentation/index.mjs"
     }
   },
@@ -159,7 +160,7 @@
     "better-call": "1.3.5",
     "@cloudflare/workers-types": "^4.20250121.0",
     "jose": "^6.1.3",
-    "kysely": "^0.28.14",
+    "kysely": "^0.28.17",
     "nanostores": "^1.1.1",
     "tsdown": "0.21.1"
   },

package/src/db/adapter/factory.ts

@@ -133,6 +133,11 @@ export const createAdapterFactory =
 							!config.debugLogs.deleteMany
 						) {
 							return;
+						} else if (
+							method === "consumeOne" &&
+							!config.debugLogs.consumeOne
+						) {
+							return;
 						} else if (method === "count" && !config.debugLogs.count) {
 							return;
 						}
@@ -485,6 +490,7 @@ export const createAdapterFactory =
 				| "updateMany"
 				| "delete"
 				| "deleteMany"
+				| "consumeOne"
 				| "count";
 		}): W extends undefined ? undefined : CleanedWhere[] => {
 			if (!where) return undefined as any;
@@ -1312,6 +1318,112 @@ export const createAdapterFactory =
 				);
 				return res;
 			},
+			consumeOne: async <T>({
+				model: unsafeModel,
+				where: unsafeWhere,
+			}: {
+				model: string;
+				where: Where[];
+			}): Promise<T | null> => {
+				transactionId++;
+				const thisTransactionId = transactionId;
+				const model = getModelName(unsafeModel);
+				const where = transformWhereClause({
+					model: unsafeModel,
+					where: unsafeWhere,
+					action: "consumeOne",
+				});
+				unsafeModel = getDefaultModelName(unsafeModel);
+				debugLog(
+					{ method: "consumeOne" },
+					`${formatTransactionId(thisTransactionId)} ${formatStep(1, 3)}`,
+					`${formatMethod("consumeOne")} ${formatAction("ConsumeOne")}:`,
+					{ model, where },
+				);
+
+				let res: T | null;
+				let resultNeedsOutputTransform = true;
+				if (adapterInstance.consumeOne) {
+					res = await withSpan(
+						`db consumeOne ${model}`,
+						{
+							[ATTR_DB_OPERATION_NAME]: "consumeOne",
+							[ATTR_DB_COLLECTION_NAME]: model,
+						},
+						() => adapterInstance.consumeOne!<T>({ model, where }),
+					);
+				} else {
+					// TODO(consume-one-required): adapters without native `consumeOne`
+					// fall back to `transaction(findMany + deleteMany)`. Race-safe on
+					// engines with real transaction isolation; race window narrows
+					// (does not close) on adapters that fall through to sequential
+					// execution. Remove this branch when consumeOne becomes required.
+					// FIXME(consume-one-nested-transaction): custom adapters without a
+					// native consumeOne have no portable signal for "already inside a
+					// transaction". First-party adapters mark transaction-scoped
+					// adapters as as-is; make that capability explicit in the next
+					// breaking adapter contract.
+					res = await withSpan(
+						`db consumeOne ${model}`,
+						{
+							[ATTR_DB_OPERATION_NAME]: "consumeOne",
+							[ATTR_DB_COLLECTION_NAME]: model,
+						},
+						() =>
+							adapter.transaction(async (trx) => {
+								const rows = await trx.findMany<Record<string, any>>({
+									model: unsafeModel,
+									where: unsafeWhere,
+									limit: 1,
+								});
+								const target = rows[0];
+								if (!target) return null;
+								const deleted = await trx.deleteMany({
+									model: unsafeModel,
+									where: [
+										...unsafeWhere,
+										{
+											field: "id",
+											value: target.id,
+											operator: "eq",
+											connector: "AND",
+											mode: "sensitive",
+										},
+									],
+								});
+								return deleted > 0 ? (target as T) : null;
+							}),
+					);
+					resultNeedsOutputTransform = false;
+				}
+
+				debugLog(
+					{ method: "consumeOne" },
+					`${formatTransactionId(thisTransactionId)} ${formatStep(2, 3)}`,
+					`${formatMethod("consumeOne")} ${formatAction("DB Result")}:`,
+					{ model, data: res },
+				);
+				let transformed: any = res;
+				if (
+					!config.disableTransformOutput &&
+					resultNeedsOutputTransform &&
+					res
+				) {
+					transformed = await transformOutput(
+						res as Record<string, any>,
+						unsafeModel,
+						undefined,
+						undefined,
+					);
+				}
+				debugLog(
+					{ method: "consumeOne" },
+					`${formatTransactionId(thisTransactionId)} ${formatStep(3, 3)}`,
+					`${formatMethod("consumeOne")} ${formatAction("Parsed Result")}:`,
+					{ model, data: transformed },
+				);
+				return transformed as T | null;
+			},
 			count: async ({
 				model: unsafeModel,
 				where: unsafeWhere,

package/src/db/adapter/index.ts

@@ -15,6 +15,7 @@ export type DBAdapterDebugLogOption =
 			findMany?: boolean | undefined;
 			delete?: boolean | undefined;
 			deleteMany?: boolean | undefined;
+			consumeOne?: boolean | undefined;
 			count?: boolean | undefined;
 	  }
 	| {
@@ -211,6 +212,7 @@ export interface DBAdapterFactoryConfig<
 					| "updateMany"
 					| "delete"
 					| "deleteMany"
+					| "consumeOne"
 					| "count";
 				/**
 				 * The model name.
@@ -445,6 +447,23 @@ export type DBAdapter<Options extends BetterAuthOptions = BetterAuthOptions> = {
 	}) => Promise<number>;
 	delete: <_T>(data: { model: string; where: Where[] }) => Promise<void>;
 	deleteMany: (data: { model: string; where: Where[] }) => Promise<number>;
+	/**
+	 * Atomically consume a single row matching the where clause: delete it and
+	 * return the deleted row, or return `null` if no row matched.
+	 * Implementations MUST NOT delete any additional rows that also match a
+	 * non-unique predicate.
+	 *
+	 * Under concurrent invocation against the same row, exactly one caller
+	 * receives the row; subsequent racers receive `null`. This is the
+	 * race-safe primitive for consuming single-use credentials
+	 * (verification tokens, authorization codes, one-time tokens).
+	 *
+	 * Always defined on the factory-wrapped adapter. When the underlying
+	 * `CustomAdapter` does not implement `consumeOne`, the factory provides
+	 * a fallback that wraps `findMany + deleteMany` in `transaction(...)`
+	 * and returns the row only when the delete reports an affected row.
+	 */
+	consumeOne: <T>(data: { model: string; where: Where[] }) => Promise<T | null>;
 	/**
 	 * Execute multiple operations in a transaction.
 	 * If the adapter doesn't support transactions, operations will be executed sequentially.
@@ -531,6 +550,19 @@ export interface CustomAdapter {
 		model: string;
 		where: CleanedWhere[];
 	}) => Promise<number>;
+	/**
+	 * Optional native atomic single-row consume. When omitted, the adapter
+	 * factory falls back to `transaction(findMany + deleteMany)`.
+	 * Implementing this method natively (e.g. `DELETE ... RETURNING *`,
+	 * `findOneAndDelete`, `OUTPUT deleted.*`) gives one round trip and the
+	 * strongest race-safety guarantee. Implementations must delete at most
+	 * one matching row. TODO(consume-one-required): tighten to required in the
+	 * next minor on `next`.
+	 */
+	consumeOne?: <T>(data: {
+		model: string;
+		where: CleanedWhere[];
+	}) => Promise<T | null>;
 	count: ({
 		model,
 		where,

package/src/db/adapter/types.ts

@@ -122,6 +122,7 @@ export type AdapterFactoryCustomizeAdapterCreator = (config: {
 			| "updateMany"
 			| "delete"
 			| "deleteMany"
+			| "consumeOne"
 			| "count";
 	}) => W extends undefined ? undefined : CleanedWhere[];
 }) => CustomAdapter;

package/src/db/type.ts

@@ -311,6 +311,18 @@ export interface SecondaryStorage {
 	 * @returns - Value of the key
 	 */
 	get: (key: string) => Awaitable<unknown>;
+	/**
+	 * Atomically get a value and delete it from storage.
+	 *
+	 * This is optional for backwards compatibility with existing secondary
+	 * storage implementations. Single-use credential consumers use it when
+	 * present to avoid a read-then-delete race.
+	 *
+	 * TODO(secondary-storage-atomic-consume): make this required in the next
+	 * breaking release, or require database-backed verification storage for
+	 * security-sensitive consume paths.
+	 */
+	getAndDelete?: (key: string) => Awaitable<unknown>;
 	set: (
 		/**
 		 * Key to store

package/src/error/codes.ts

@@ -37,6 +37,7 @@ export const BASE_ERROR_CODES = defineErrorCodes({
 	USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL:
 		"User already exists. Use another email.",
 	EMAIL_CAN_NOT_BE_UPDATED: "Email can not be updated",
+	CHANGE_EMAIL_DISABLED: "Change email is disabled",
 	CREDENTIAL_ACCOUNT_NOT_FOUND: "Credential account not found",
 	SESSION_EXPIRED: "Session expired. Re-authenticate to perform this action.",
 	FAILED_TO_UNLINK_LAST_ACCOUNT: "You can't unlink your last account",

package/src/types/context.ts

@@ -216,6 +216,19 @@ 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. 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>;
+
 	updateVerificationByIdentifier(
 		identifier: string,
 		data: Partial<Verification>,

package/src/types/init-options.ts

@@ -207,12 +207,13 @@ 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;
 		  }
 		| undefined;
 	/**
@@ -1020,6 +1021,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

package/src/utils/ip.ts

@@ -12,12 +12,13 @@ import * as z from "zod";
 
 interface NormalizeIPOptions {
 	/**
-	 * For IPv6 addresses, extract the subnet prefix instead of full address.
-	 * Common values: 32, 48, 64, 128 (default: 128 = full address)
+	 * Prefix length used to collapse IPv6 addresses before keying.
+	 * Any integer from 0 to 128 is accepted. Common values: 32, 48, 56, 64, 128.
+	 * Values outside 0-128 are clamped.
 	 *
-	 * @default 128
+	 * @default 64
 	 */
-	ipv6Subnet?: 128 | 64 | 48 | 32;
+	ipv6Subnet?: number;
 }
 
 /**
@@ -117,15 +118,13 @@ function expandIPv6(ipv6: string): string[] {
  * Normalizes an IPv6 address to canonical form
  * e.g., "2001:DB8::1" -> "2001:0db8:0000:0000:0000:0000:0000:0001"
  */
-function normalizeIPv6(
-	ipv6: string,
-	subnetPrefix?: 128 | 32 | 48 | 64,
-): string {
+function normalizeIPv6(ipv6: string, subnetPrefix?: number): string {
 	const groups = expandIPv6(ipv6);
 
-	if (subnetPrefix && subnetPrefix < 128) {
-		// Apply subnet mask
-		const prefix = subnetPrefix;
+	if (subnetPrefix !== undefined && subnetPrefix < 128) {
+		// Clamp to a valid bit range so out-of-spec inputs degrade safely:
+		// negative or fractional values would otherwise produce malformed masks.
+		const prefix = Math.max(0, Math.floor(subnetPrefix));
 		let bitsRemaining: number = prefix;
 
 		const maskedGroups = groups.map((group) => {
@@ -191,8 +190,8 @@ export function normalizeIP(
 		return ipv4.toLowerCase();
 	}
 
-	// Normalize IPv6
-	const subnetPrefix = options.ipv6Subnet || 64;
+	// Normalize IPv6. Use ?? so an explicit 0 (mask-all) is honoured.
+	const subnetPrefix = options.ipv6Subnet ?? 64;
 	return normalizeIPv6(ip, subnetPrefix);
 }