@better-auth/core 1.7.0-beta.5 → 1.7.0-beta.7

package/src/context/transaction.ts

@@ -1,11 +1,15 @@
 import type { AsyncLocalStorage } from "node:async_hooks";
 import { getAsyncLocalStorage } from "@better-auth/core/async_hooks";
 import type { DBAdapter, DBTransactionAdapter } from "../db/adapter";
+import type { BetterAuthOptions } from "../types";
 import { __getBetterAuthGlobal } from "./global";
 
+type StoredAdapter = DBTransactionAdapter<BetterAuthOptions>;
+
 type HookContext = {
-	adapter: DBTransactionAdapter;
+	adapter: StoredAdapter;
 	pendingHooks: Array<() => Promise<void>>;
+	isTransactionActive: boolean;
 };
 
 const ensureAsyncStorage = async () => {
@@ -27,21 +31,29 @@ export const getCurrentDBAdapterAsyncLocalStorage = async () => {
 	return ensureAsyncStorage();
 };
 
-export const getCurrentAdapter = async (
-	fallback: DBTransactionAdapter,
-): Promise<DBTransactionAdapter> => {
+export const getCurrentAdapter = async <
+	Options extends BetterAuthOptions = BetterAuthOptions,
+>(
+	fallback: DBTransactionAdapter<Options>,
+): Promise<DBTransactionAdapter<Options>> => {
 	return ensureAsyncStorage()
 		.then((als) => {
 			const store = als.getStore();
-			return store?.adapter || fallback;
+			return (
+				(store?.adapter as DBTransactionAdapter<Options> | undefined) ||
+				fallback
+			);
 		})
 		.catch(() => {
 			return fallback;
 		});
 };
 
-export const runWithAdapter = async <R>(
-	adapter: DBAdapter,
+export const runWithAdapter = async <
+	R,
+	Options extends BetterAuthOptions = BetterAuthOptions,
+>(
+	adapter: DBAdapter<Options>,
 	fn: () => R,
 ): Promise<R> => {
 	let called = false;
@@ -53,7 +65,14 @@ export const runWithAdapter = async <R>(
 			let error: unknown;
 			let hasError = false;
 			try {
-				result = await als.run({ adapter, pendingHooks }, fn);
+				result = await als.run(
+					{
+						adapter: adapter as unknown as StoredAdapter,
+						pendingHooks,
+						isTransactionActive: false,
+					},
+					fn,
+				);
 			} catch (err) {
 				error = err;
 				hasError = true;
@@ -75,21 +94,35 @@ export const runWithAdapter = async <R>(
 		});
 };
 
-export const runWithTransaction = async <R>(
-	adapter: DBAdapter,
+export const runWithTransaction = async <
+	R,
+	Options extends BetterAuthOptions = BetterAuthOptions,
+>(
+	adapter: DBAdapter<Options>,
 	fn: () => R,
 ): Promise<R> => {
-	let called = true;
+	let called = false;
 	return ensureAsyncStorage()
 		.then(async (als) => {
 			called = true;
+			const store = als.getStore();
+			if (store?.isTransactionActive) {
+				return fn();
+			}
 			const pendingHooks: Array<() => Promise<void>> = [];
 			let result: Awaited<R>;
 			let error: unknown;
 			let hasError = false;
 			try {
 				result = await adapter.transaction(async (trx) => {
-					return als.run({ adapter: trx, pendingHooks }, fn);
+					return als.run(
+						{
+							adapter: trx as unknown as StoredAdapter,
+							pendingHooks,
+							isTransactionActive: true,
+						},
+						fn,
+					);
 				});
 			} catch (e) {
 				hasError = true;

package/src/db/adapter/factory.ts

@@ -138,6 +138,11 @@ export const createAdapterFactory =
 							!config.debugLogs.consumeOne
 						) {
 							return;
+						} else if (
+							method === "incrementOne" &&
+							!config.debugLogs.incrementOne
+						) {
+							return;
 						} else if (method === "count" && !config.debugLogs.count) {
 							return;
 						}
@@ -491,6 +496,7 @@ export const createAdapterFactory =
 				| "delete"
 				| "deleteMany"
 				| "consumeOne"
+				| "incrementOne"
 				| "count";
 		}): W extends undefined ? undefined : CleanedWhere[] => {
 			if (!where) return undefined as any;
@@ -1057,6 +1063,14 @@ export const createAdapterFactory =
 							update: data,
 						}),
 				);
+				if (
+					typeof updatedCount !== "number" ||
+					!Number.isFinite(updatedCount)
+				) {
+					throw new BetterAuthError(
+						`Adapter "${config.adapterId}" updateMany must return a finite number affected row count.`,
+					);
+				}
 				debugLog(
 					{ method: "updateMany" },
 					`${formatTransactionId(thisTransactionId)} ${formatStep(3, 4)}`,
@@ -1341,75 +1355,19 @@ export const createAdapterFactory =
 					{ 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",
-										},
-									],
-								});
-								// `deleteMany` is typed `Promise<number>`. A non-number breaks
-								// the contract, so fail loud. A finite-number check then closes
-								// the NaN/Infinity hole: `NaN > 0` is false and `Infinity > 0`
-								// is true, so a bare `deleted > 0` would misclassify both. Only
-								// a finite positive count proves we won the delete race; any
-								// other value fails closed (returns null) so a single-use row
-								// is never reported consumed without proof.
-								if (typeof deleted !== "number") {
-									throw new BetterAuthError(
-										`Adapter "${config.adapterId}" returned a non-numeric value from deleteMany during the consumeOne fallback. Return the number of deleted rows, or implement a native consumeOne for atomic single-use consumption.`,
-									);
-								}
-								return Number.isFinite(deleted) && deleted > 0
-									? (target as T)
-									: null;
-							}),
+				if (typeof adapterInstance.consumeOne !== "function") {
+					throw new BetterAuthError(
+						`Adapter "${config.adapterId}" must implement consumeOne for atomic single-use credential consumption.`,
 					);
-					resultNeedsOutputTransform = false;
 				}
+				const res = await withSpan(
+					`db consumeOne ${model}`,
+					{
+						[ATTR_DB_OPERATION_NAME]: "consumeOne",
+						[ATTR_DB_COLLECTION_NAME]: model,
+					},
+					() => adapterInstance.consumeOne<T>({ model, where }),
+				);
 
 				debugLog(
 					{ method: "consumeOne" },
@@ -1418,11 +1376,7 @@ export const createAdapterFactory =
 					{ model, data: res },
 				);
 				let transformed: any = res;
-				if (
-					!config.disableTransformOutput &&
-					resultNeedsOutputTransform &&
-					res
-				) {
+				if (!config.disableTransformOutput && res) {
 					transformed = await transformOutput(
 						res as Record<string, any>,
 						unsafeModel,
@@ -1438,6 +1392,107 @@ export const createAdapterFactory =
 				);
 				return transformed as T | null;
 			},
+			incrementOne: async <T>({
+				model: unsafeModel,
+				where: unsafeWhere,
+				increment: unsafeIncrement,
+				set: unsafeSet,
+			}: {
+				model: string;
+				where: Where[];
+				increment: Record<string, number>;
+				set?: Record<string, unknown> | undefined;
+			}): Promise<T | null> => {
+				const hasIncrement = Object.keys(unsafeIncrement).length > 0;
+				const hasSet = !!unsafeSet && Object.keys(unsafeSet).length > 0;
+				if (!hasIncrement && !hasSet) {
+					// An empty `increment` and empty `set` compiles to `UPDATE ... SET `
+					// with no assignments, which is a syntax error on kysely, drizzle, and
+					// Prisma. Fail fast with an actionable message instead.
+					throw new BetterAuthError(
+						"incrementOne requires a non-empty `increment` or `set`; both were empty.",
+					);
+				}
+				transactionId++;
+				const thisTransactionId = transactionId;
+				const model = getModelName(unsafeModel);
+				const where = transformWhereClause({
+					model: unsafeModel,
+					where: unsafeWhere,
+					action: "incrementOne",
+				});
+				unsafeModel = getDefaultModelName(unsafeModel);
+				debugLog(
+					{ method: "incrementOne" },
+					`${formatTransactionId(thisTransactionId)} ${formatStep(1, 3)}`,
+					`${formatMethod("incrementOne")} ${formatAction("IncrementOne")}:`,
+					{ model, where, increment: unsafeIncrement, set: unsafeSet },
+				);
+
+				if (typeof adapterInstance.incrementOne !== "function") {
+					throw new BetterAuthError(
+						`Adapter "${config.adapterId}" must implement incrementOne for atomic guarded counter updates.`,
+					);
+				}
+				const mappedKeys = config.mapKeysTransformInput ?? {};
+				const increment: Record<string, number> = {};
+				for (const [field, delta] of Object.entries(unsafeIncrement)) {
+					increment[
+						mappedKeys[field] || getFieldName({ model: unsafeModel, field })
+					] = delta;
+				}
+				let set: Record<string, unknown> | undefined;
+				if (unsafeSet && !config.disableTransformInput) {
+					set = await transformInput(unsafeSet, unsafeModel, "update");
+				} else {
+					set = unsafeSet;
+				}
+				if (
+					Object.keys(increment).length === 0 &&
+					(!set || Object.keys(set).length === 0)
+				) {
+					throw new BetterAuthError(
+						"incrementOne resolved to an empty update: every increment/set field was unknown to the schema or transformed away.",
+					);
+				}
+				const res = await withSpan(
+					`db incrementOne ${model}`,
+					{
+						[ATTR_DB_OPERATION_NAME]: "incrementOne",
+						[ATTR_DB_COLLECTION_NAME]: model,
+					},
+					() =>
+						adapterInstance.incrementOne<T>({
+							model,
+							where,
+							increment,
+							set,
+						}),
+				);
+
+				debugLog(
+					{ method: "incrementOne" },
+					`${formatTransactionId(thisTransactionId)} ${formatStep(2, 3)}`,
+					`${formatMethod("incrementOne")} ${formatAction("DB Result")}:`,
+					{ model, data: res },
+				);
+				let transformed: any = res;
+				if (!config.disableTransformOutput && res) {
+					transformed = await transformOutput(
+						res as Record<string, any>,
+						unsafeModel,
+						undefined,
+						undefined,
+					);
+				}
+				debugLog(
+					{ method: "incrementOne" },
+					`${formatTransactionId(thisTransactionId)} ${formatStep(3, 3)}`,
+					`${formatMethod("incrementOne")} ${formatAction("Parsed Result")}:`,
+					{ model, data: transformed },
+				);
+				return transformed as T | null;
+			},
 			count: async ({
 				model: unsafeModel,
 				where: unsafeWhere,

package/src/db/adapter/index.ts

@@ -16,6 +16,7 @@ export type DBAdapterDebugLogOption =
 			delete?: boolean | undefined;
 			deleteMany?: boolean | undefined;
 			consumeOne?: boolean | undefined;
+			incrementOne?: boolean | undefined;
 			count?: boolean | undefined;
 	  }
 	| {
@@ -213,6 +214,7 @@ export interface DBAdapterFactoryConfig<
 					| "delete"
 					| "deleteMany"
 					| "consumeOne"
+					| "incrementOne"
 					| "count";
 				/**
 				 * The model name.
@@ -458,12 +460,40 @@ export type DBAdapter<Options extends BetterAuthOptions = BetterAuthOptions> = {
 	 * 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.
+	 * Always defined on the factory-wrapped adapter. The underlying
+	 * `CustomAdapter` must implement this natively; there is no portable
+	 * fallback that can guarantee cross-process single-use semantics.
 	 */
 	consumeOne: <T>(data: { model: string; where: Where[] }) => Promise<T | null>;
+	/**
+	 * Atomically apply signed numeric deltas to a single row matching the where
+	 * clause. For each entry in `increment`, the operation applies
+	 * `field = field + delta` in one atomic step; a negative delta decrements.
+	 *
+	 * The `where` clause is both the selector AND the guard: comparison
+	 * operators are honored, so passing `{ field: "remaining", operator: "gt",
+	 * value: 0 }` only mutates the row while `remaining` is still above zero.
+	 * When the guard matches no row, the operation makes no change and returns
+	 * `null`.
+	 *
+	 * The optional `set` map assigns absolute values to fields in the same
+	 * atomic operation, alongside the increments.
+	 *
+	 * Returns the updated row, or `null` when the guard matched no row. Under
+	 * concurrent invocation against the same row, this is the race-safe
+	 * primitive for guarded counter updates (e.g. decrementing a remaining-uses
+	 * counter only while it is still positive).
+	 *
+	 * Always defined on the factory-wrapped adapter. The underlying
+	 * `CustomAdapter` must implement this natively; there is no portable
+	 * fallback that can guarantee guarded counter semantics across runtimes.
+	 */
+	incrementOne: <T>(data: {
+		model: string;
+		where: Where[];
+		increment: Record<string, number>;
+		set?: Record<string, unknown> | undefined;
+	}) => Promise<T | null>;
 	/**
 	 * Execute multiple operations in a transaction.
 	 * If the adapter doesn't support transactions, operations will be executed sequentially.
@@ -551,17 +581,32 @@ export interface CustomAdapter {
 		where: CleanedWhere[];
 	}) => Promise<number>;
 	/**
-	 * Optional native atomic single-row consume. When omitted, the adapter
-	 * factory falls back to `transaction(findMany + deleteMany)`.
+	 * Native atomic single-row consume.
 	 * 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`.
+	 * one matching row.
+	 */
+	consumeOne: <T>(data: {
+		model: string;
+		where: CleanedWhere[];
+	}) => Promise<T | null>;
+	/**
+	 * Native atomic guarded counter mutation. Applies
+	 * `field = field + delta` for each entry in `increment` (negative deltas
+	 * decrement), with `where` acting as both selector and guard and `set`
+	 * assigning absolute values in the same operation. Returns the updated row,
+	 * or `null` when the guard matched no row.
+	 *
+	 * Implementing this natively (e.g. `UPDATE ... SET n = n + $delta WHERE ...
+	 * RETURNING *`) gives one round trip and the strongest race-safety
+	 * guarantee.
 	 */
-	consumeOne?: <T>(data: {
+	incrementOne: <T>(data: {
 		model: string;
 		where: CleanedWhere[];
+		increment: Record<string, number>;
+		set?: Record<string, unknown> | undefined;
 	}) => Promise<T | null>;
 	count: ({
 		model,

package/src/db/adapter/types.ts

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

package/src/db/type.ts

@@ -313,16 +313,21 @@ export interface SecondaryStorage {
 	get: (key: string) => Awaitable<unknown>;
 	/**
 	 * Atomically get a value and delete it from storage.
+	 */
+	getAndDelete: (key: string) => Awaitable<unknown>;
+	/**
+	 * Atomically increment the counter at `key` by one, returning the
+	 * post-increment value.
 	 *
-	 * 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.
+	 * When the key is absent, it is created with a value of `1` and the given
+	 * `ttl` (in SECONDS). The TTL is applied only on creation; later increments
+	 * never extend it, so the counter expires a fixed window after it was first
+	 * created.
 	 *
-	 * TODO(secondary-storage-atomic-consume): make this required in the next
-	 * breaking release, or require database-backed verification storage for
-	 * security-sensitive consume paths.
+	 * Required so secondary-storage-backed rate limiting can enforce the limit
+	 * in one distributed-safe operation.
 	 */
-	getAndDelete?: (key: string) => Awaitable<unknown>;
+	increment: (key: string, ttl: number) => Awaitable<number>;
 	set: (
 		/**
 		 * Key to store

package/src/oauth2/create-authorization-url.ts

@@ -15,6 +15,7 @@ export const RESERVED_AUTHORIZATION_PARAMS = [
 	"response_type",
 	"code_challenge",
 	"code_challenge_method",
+	"nonce",
 	"scope",
 ] as const;
 
@@ -37,6 +38,7 @@ export async function createAuthorizationURL({
 	responseType,
 	display,
 	loginHint,
+	nonce,
 	hd,
 	responseMode,
 	additionalParams,
@@ -56,6 +58,7 @@ export async function createAuthorizationURL({
 	responseType?: string | undefined;
 	display?: string | undefined;
 	loginHint?: string | undefined;
+	nonce?: string | undefined;
 	hd?: string | undefined;
 	responseMode?: string | undefined;
 	additionalParams?: Record<string, string> | undefined;
@@ -77,6 +80,7 @@ export async function createAuthorizationURL({
 	duration && url.searchParams.set("duration", duration);
 	display && url.searchParams.set("display", display);
 	loginHint && url.searchParams.set("login_hint", loginHint);
+	nonce && url.searchParams.set("nonce", nonce);
 	prompt && url.searchParams.set("prompt", prompt);
 	hd && url.searchParams.set("hd", hd);
 	accessType && url.searchParams.set("access_type", accessType);