@better-auth/core 1.7.1 → 1.7.3

package/dist/social-providers/tiktok.mjs

@@ -1,10 +1,18 @@
 import { RESERVED_AUTHORIZATION_PARAMS_SET } from "../oauth2/create-authorization-url.mjs";
 import { refreshAccessToken } from "../oauth2/refresh-access-token.mjs";
 import { validateAuthorizationCode } from "../oauth2/validate-authorization-code.mjs";
+import { createPlaceholderEmail } from "../utils/email.mjs";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/social-providers/tiktok.ts
 const tiktok = (options) => {
 	const tokenEndpoint = "https://open.tiktokapis.com/v2/oauth/token/";
+	const tokenEndpointAuth = {
+		method: "custom",
+		customizeRequest({ body }) {
+			body.set("client_key", options.clientKey);
+			body.set("client_secret", options.clientSecret);
+		}
+	};
 	return {
 		id: "tiktok",
 		name: "TikTok",
@@ -26,24 +34,22 @@ const tiktok = (options) => {
 			}
 			return url;
 		},
-		validateAuthorizationCode: async ({ code, redirectURI }) => {
+		validateAuthorizationCode: async ({ code, codeVerifier, redirectURI }) => {
 			return validateAuthorizationCode({
 				code,
+				codeVerifier,
 				redirectURI: options.redirectURI || redirectURI,
-				options: {
-					clientKey: options.clientKey,
-					clientSecret: options.clientSecret
-				},
-				tokenEndpoint
+				options: {},
+				tokenEndpoint,
+				tokenEndpointAuth
 			});
 		},
 		refreshAccessToken: options.refreshAccessToken ? options.refreshAccessToken : async (refreshToken) => {
 			return refreshAccessToken({
 				refreshToken,
-				options: { clientSecret: options.clientSecret },
+				options: {},
 				tokenEndpoint,
-				authentication: "post",
-				extraParams: { client_key: options.clientKey }
+				tokenEndpointAuth
 			});
 		},
 		async getUserInfo(token) {
@@ -57,7 +63,10 @@ const tiktok = (options) => {
 			if (error) return null;
 			return {
 				user: {
-					email: profile.data.user.email || profile.data.user.username,
+					email: profile.data.user.email || createPlaceholderEmail({
+						identifier: profile.data.user.open_id,
+						namespace: "tiktok"
+					}),
 					name: profile.data.user.display_name || profile.data.user.username || "",
 					image: profile.data.user.avatar_large_url,
 					emailVerified: false

package/dist/social-providers/twitter.mjs

@@ -1,6 +1,7 @@
 import { createAuthorizationURL } from "../oauth2/create-authorization-url.mjs";
 import { refreshAccessToken } from "../oauth2/refresh-access-token.mjs";
 import { validateAuthorizationCode } from "../oauth2/validate-authorization-code.mjs";
+import { createPlaceholderEmail } from "../utils/email.mjs";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/social-providers/twitter.ts
 const twitter = (options) => {
@@ -71,7 +72,10 @@ const twitter = (options) => {
 			return {
 				user: {
 					name: profile.data.name,
-					email: profile.data.email || profile.data.username || null,
+					email: profile.data.email || createPlaceholderEmail({
+						identifier: profile.data.id,
+						namespace: "twitter"
+					}),
 					image: profile.data.profile_image_url,
 					emailVerified,
 					...userMap

package/dist/social-providers/wechat.mjs

@@ -1,4 +1,5 @@
 import { RESERVED_AUTHORIZATION_PARAMS_SET } from "../oauth2/create-authorization-url.mjs";
+import { createPlaceholderEmail } from "../utils/email.mjs";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/social-providers/wechat.ts
 const wechat = (options) => {
@@ -69,10 +70,14 @@ const wechat = (options) => {
 			}).toString(), { method: "GET" });
 			if (error || !profile || profile.errcode) return null;
 			const userMap = await options.mapProfileToUser?.(profile);
+			const userId = profile.unionid || profile.openid || openid;
 			return {
 				user: {
 					name: profile.nickname,
-					email: profile.email || `${profile.unionid || profile.openid || openid}@wechat.invalid`,
+					email: profile.email || createPlaceholderEmail({
+						identifier: userId,
+						namespace: "wechat"
+					}),
 					image: profile.headimgurl,
 					emailVerified: false,
 					...userMap

package/dist/types/context.d.mts

@@ -8,6 +8,7 @@ import { Awaitable, LiteralString } from "./helper.mjs";
 import { BetterAuthPlugin } from "./plugin.mjs";
 import { BetterAuthOptions, BetterAuthRateLimitOptions, UserProvisioningSource } from "./init-options.mjs";
 import { Account, AccountKey } from "../db/schema/account.mjs";
+import { SchemaCheck } from "../db/schema-check.mjs";
 import { BetterAuthCookie, BetterAuthCookies, CookieCachePayload } from "./cookie.mjs";
 import { SecretConfig } from "./secret.mjs";
 import { OAuthProvider } from "../oauth2/oauth-provider.mjs";
@@ -263,6 +264,16 @@ type AuthContext<Options extends BetterAuthOptions = BetterAuthOptions> = Plugin
     storage: "memory" | "database" | "secondary-storage";
   } & Omit<BetterAuthRateLimitOptions, "enabled" | "window" | "max" | "storage">;
   adapter: DBAdapter<Options>;
+  /**
+   * Confirms the database can hold what this configuration writes.
+   *
+   * Shared by initialization and requests for this adapter instance;
+   * returns nothing once the schema is known to be clean.
+   * Context construction does not await the verdict, so migration
+   * tooling can still use a context whose schema needs repair.
+   * Absent when the check is disabled or the adapter registers none.
+   */
+  checkSchema?: SchemaCheck | undefined;
   internalAdapter: InternalAdapter<Options>;
   createAuthCookie: CreateCookieGetterFn;
   secret: string;

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

@@ -387,6 +387,17 @@ type BetterAuthAdvancedOptions = {
      * @default false
      */
     joins?: boolean;
+    /**
+     * Validate the schema during initialization and report problems
+     * through the configured logger. Authentication requests await
+     * the same check and fail when the schema does not match.
+     * Kysely introspects the database; Drizzle and Prisma inspect
+     * local schema metadata without opening a connection.
+     * Set `false` to disable runtime schema validation.
+     *
+     * @default true
+     */
+    validateSchema?: boolean;
   } | undefined;
   /**
    * Trusted proxy headers

package/dist/utils/ip.mjs

@@ -1,17 +1,19 @@
 import { isDevelopment, isTest } from "../env/env-impl.mjs";
 import * as z from "zod";
 //#region src/utils/ip.ts
+const ipv4Schema = z.ipv4();
+const ipv6Schema = z.ipv6();
 /**
 * Checks if an IP is valid IPv4 or IPv6
 */
 function isValidIP(ip) {
-	return z.ipv4().safeParse(ip).success || z.ipv6().safeParse(ip).success;
+	return isIPv4(ip) || isIPv6(ip);
+}
+function isIPv4(ip) {
+	return z.validate(ipv4Schema, ip);
 }
-/**
-* Checks if an IP is IPv6
-*/
 function isIPv6(ip) {
-	return z.ipv6().safeParse(ip).success;
+	return z.validate(ipv6Schema, ip);
 }
 /**
 * Converts IPv4-mapped IPv6 address to IPv4
@@ -21,12 +23,12 @@ function extractIPv4FromMapped(ipv6) {
 	const lower = ipv6.toLowerCase();
 	if (lower.startsWith("::ffff:")) {
 		const ipv4Part = lower.substring(7);
-		if (z.ipv4().safeParse(ipv4Part).success) return ipv4Part;
+		if (isIPv4(ipv4Part)) return ipv4Part;
 	}
 	const parts = ipv6.split(":");
 	if (parts.length === 7 && parts[5]?.toLowerCase() === "ffff") {
 		const ipv4Part = parts[6];
-		if (ipv4Part && z.ipv4().safeParse(ipv4Part).success) return ipv4Part;
+		if (ipv4Part && isIPv4(ipv4Part)) return ipv4Part;
 	}
 	if (lower.includes("::ffff:") || lower.includes(":ffff:")) {
 		const groups = expandIPv6(ipv6);
@@ -96,7 +98,7 @@ function normalizeIPv6(ipv6, subnetPrefix) {
 * // -> "2001:0db8:0000:0000:0000:0000:0000:0000" (subnet /64)
 */
 function normalizeIP(ip, options = {}) {
-	if (z.ipv4().safeParse(ip).success) return ip.toLowerCase();
+	if (isIPv4(ip)) return ip.toLowerCase();
 	if (!isIPv6(ip)) return ip.toLowerCase();
 	const ipv4 = extractIPv4FromMapped(ip);
 	if (ipv4) return ipv4.toLowerCase();
@@ -106,7 +108,7 @@ function normalizeIP(ip, options = {}) {
 * Raw bytes of an IP for CIDR comparison. Returns `null` for an invalid IP.
 */
 function ipToBytes(ip) {
-	if (z.ipv4().safeParse(ip).success) return Uint8Array.from(ip.split(".").map((octet) => Number(octet)));
+	if (isIPv4(ip)) return Uint8Array.from(ip.split(".").map((octet) => Number(octet)));
 	if (!isIPv6(ip)) return null;
 	const mapped = extractIPv4FromMapped(ip);
 	if (mapped) return Uint8Array.from(mapped.split(".").map((octet) => Number(octet)));

package/dist/utils/url.d.mts

@@ -16,6 +16,15 @@
  * // Returns: "/sso/saml2/callback/provider1"
  */
 declare function normalizePathname(requestUrl: string, basePath: string): string;
+/**
+ * Appends query parameters before the fragment of an absolute or root-relative URL.
+ * Existing query text is retained without parsing it into name-value pairs.
+ *
+ * This function only composes URLs. Callers must validate untrusted input.
+ *
+ * @throws TypeError if parsing fails or a relative input changes authority.
+ */
+declare function appendQueryParams(input: string, params: URLSearchParams): string;
 /**
  * Schemes that execute or embed code when navigated to or accepted as a
  * redirect target. These are never safe as an OAuth `redirect_uri` or as a
@@ -34,4 +43,4 @@ declare const DANGEROUS_URL_SCHEMES: string[];
  */
 declare function isSafeUrlScheme(value: string): boolean;
 //#endregion
-export { DANGEROUS_URL_SCHEMES, isSafeUrlScheme, normalizePathname };
+export { DANGEROUS_URL_SCHEMES, appendQueryParams, isSafeUrlScheme, normalizePathname };

package/dist/utils/url.mjs

@@ -28,6 +28,26 @@ function normalizePathname(requestUrl, basePath) {
 	if (pathname.startsWith(normalizedBasePath + "/")) return pathname.slice(normalizedBasePath.length).replace(/\/+$/, "") || "/";
 	return pathname;
 }
+const URL_REFERENCE_ORIGIN = "https://better-auth.invalid";
+/**
+* Appends query parameters before the fragment of an absolute or root-relative URL.
+* Existing query text is retained without parsing it into name-value pairs.
+*
+* This function only composes URLs. Callers must validate untrusted input.
+*
+* @throws TypeError if parsing fails or a relative input changes authority.
+*/
+function appendQueryParams(input, params) {
+	const relative = input.startsWith("/");
+	if (input.startsWith("//") || input.startsWith("/\\")) throw new TypeError("Expected an absolute or root-relative URL");
+	const parsedURL = relative ? new URL(input, URL_REFERENCE_ORIGIN) : new URL(input);
+	if (relative && parsedURL.origin !== URL_REFERENCE_ORIGIN) throw new TypeError("Expected an absolute or root-relative URL");
+	const query = params.toString();
+	if (!query) return input;
+	const separator = parsedURL.search.endsWith("&") ? "" : "&";
+	parsedURL.search = parsedURL.search ? `${parsedURL.search}${separator}${query}` : query;
+	return relative ? parsedURL.href.slice(parsedURL.origin.length) : parsedURL.href;
+}
 /**
 * Schemes that execute or embed code when navigated to or accepted as a
 * redirect target. These are never safe as an OAuth `redirect_uri` or as a
@@ -58,4 +78,4 @@ function isSafeUrlScheme(value) {
 	return !DANGEROUS_URL_SCHEMES.includes(parsed.protocol);
 }
 //#endregion
-export { DANGEROUS_URL_SCHEMES, isSafeUrlScheme, normalizePathname };
+export { DANGEROUS_URL_SCHEMES, appendQueryParams, isSafeUrlScheme, normalizePathname };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/core",
-  "version": "1.7.1",
+  "version": "1.7.3",
   "description": "The most comprehensive authentication framework for TypeScript.",
   "type": "module",
   "license": "MIT",
@@ -45,8 +45,8 @@
       "node": "./dist/async_hooks/index.mjs",
       "deno": "./dist/async_hooks/index.mjs",
       "bun": "./dist/async_hooks/index.mjs",
-      "edge": "./dist/async_hooks/pure.index.mjs",
       "workerd": "./dist/async_hooks/index.mjs",
+      "edge": "./dist/async_hooks/pure.index.mjs",
       "browser": "./dist/async_hooks/pure.index.mjs",
       "default": "./dist/async_hooks/index.mjs"
     },
@@ -157,7 +157,7 @@
   "dependencies": {
     "@opentelemetry/semantic-conventions": "^1.41.1",
     "@standard-schema/spec": "^1.1.0",
-    "zod": "^4.3.6"
+    "zod": "^4.5.4"
   },
   "devDependencies": {
     "@better-auth/utils": "0.4.2",

package/src/context/endpoint-context.ts

@@ -2,7 +2,7 @@ import type { AsyncLocalStorage } from "@better-auth/core/async_hooks";
 import { getAsyncLocalStorage } from "@better-auth/core/async_hooks";
 import type { EndpointContext, InputContext } from "better-call";
 import type { AuthContext } from "../types";
-import { __getBetterAuthGlobal } from "./global";
+import { __getBetterAuthGlobal, __getCurrentEndpointContext } from "./global";
 
 export type AuthEndpointContext = Partial<
 	InputContext<string, any> & EndpointContext<string, any>
@@ -10,43 +10,68 @@ export type AuthEndpointContext = Partial<
 	context: AuthContext;
 };
 
-const ensureAsyncStorage = async () => {
-	const betterAuthGlobal = __getBetterAuthGlobal();
-	const existing = betterAuthGlobal.context.endpointContextAsyncStorage;
+type AuthEndpointContextStorage = AsyncLocalStorage<AuthEndpointContext>;
+
+const getExistingEndpointContextStorage = () => {
+	return __getBetterAuthGlobal().context.endpointContextAsyncStorage as
+		| AuthEndpointContextStorage
+		| undefined;
+};
+
+const getOrCreateEndpointContextStorage = async () => {
+	const existing = getExistingEndpointContextStorage();
 	if (existing) {
-		return existing as AsyncLocalStorage<AuthEndpointContext>;
+		return existing;
 	}
 	const AsyncLocalStorage = await getAsyncLocalStorage();
-	betterAuthGlobal.context.endpointContextAsyncStorage ??=
-		new AsyncLocalStorage<AuthEndpointContext>();
-	return betterAuthGlobal.context
-		.endpointContextAsyncStorage as AsyncLocalStorage<AuthEndpointContext>;
+	const globalContext = __getBetterAuthGlobal().context;
+	const storage = (globalContext.endpointContextAsyncStorage ??=
+		new AsyncLocalStorage<AuthEndpointContext>()) as AuthEndpointContextStorage;
+	return storage;
 };
 
 /**
- * This is for internal use only. Most users should use `getCurrentAuthContext` instead.
- *
- * It is exposed for advanced use cases where you need direct access to the AsyncLocalStorage instance.
+ * @deprecated Use `getCurrentAuthEndpointContext`,
+ * `tryGetCurrentAuthEndpointContext`, or `runWithEndpointContext` instead.
  */
 export async function getCurrentAuthContextAsyncLocalStorage() {
-	return ensureAsyncStorage();
+	return getOrCreateEndpointContextStorage();
+}
+
+/**
+ * Returns the current auth endpoint context, or `undefined` when called outside
+ * of `runWithEndpointContext`.
+ */
+export function tryGetCurrentAuthEndpointContext() {
+	return __getCurrentEndpointContext<AuthEndpointContext>();
 }
 
-export async function getCurrentAuthContext(): Promise<AuthEndpointContext> {
-	const als = await ensureAsyncStorage();
-	const context = als.getStore();
-	if (!context) {
+/**
+ * Returns the current auth endpoint context.
+ *
+ * @throws When called outside of `runWithEndpointContext`.
+ */
+export function getCurrentAuthEndpointContext() {
+	const authEndpointContext = tryGetCurrentAuthEndpointContext();
+	if (!authEndpointContext) {
 		throw new Error(
 			"No auth context found. Please make sure you are calling this function within a `runWithEndpointContext` callback.",
 		);
 	}
-	return context;
+	return authEndpointContext;
+}
+
+/**
+ * @deprecated Use `getCurrentAuthEndpointContext` instead.
+ */
+export async function getCurrentAuthContext() {
+	return getCurrentAuthEndpointContext();
 }
 
 export async function runWithEndpointContext<T>(
-	context: AuthEndpointContext,
+	authEndpointContext: AuthEndpointContext,
 	fn: () => T,
 ): Promise<T> {
-	const als = await ensureAsyncStorage();
-	return als.run(context, fn);
+	const storage = await getOrCreateEndpointContextStorage();
+	return storage.run(authEndpointContext, fn);
 }

package/src/context/global.ts

@@ -52,6 +52,13 @@ export function __getBetterAuthGlobal(): BetterAuthGlobal {
 	return (globalThis as any)[symbol] as BetterAuthGlobal;
 }
 
+export function __getCurrentEndpointContext<T>(): T | undefined {
+	const storage = __getBetterAuthGlobal().context.endpointContextAsyncStorage as
+		| AsyncLocalStorage<T>
+		| undefined;
+	return storage?.getStore();
+}
+
 export function getBetterAuthVersion(): string {
 	return __getBetterAuthGlobal().version;
 }

package/src/context/index.ts

@@ -2,7 +2,9 @@ export {
 	type AuthEndpointContext,
 	getCurrentAuthContext,
 	getCurrentAuthContextAsyncLocalStorage,
+	getCurrentAuthEndpointContext,
 	runWithEndpointContext,
+	tryGetCurrentAuthEndpointContext,
 } from "./endpoint-context";
 export { getBetterAuthVersion } from "./global";
 export {

package/src/context/transaction.ts

@@ -1,6 +1,7 @@
 import type { AsyncLocalStorage } from "@better-auth/core/async_hooks";
 import { getAsyncLocalStorage } from "@better-auth/core/async_hooks";
 import type { DBAdapter, DBTransactionAdapter } from "../db/adapter";
+import { schemaCheckFor } from "../db/schema-check";
 import type { BetterAuthOptions } from "../types";
 import { __getBetterAuthGlobal } from "./global";
 
@@ -114,6 +115,10 @@ export const runWithTransaction = async <
 			if (store?.isTransactionActive) {
 				return fn();
 			}
+			// Settle the schema verdict before this transaction holds the
+			// connection a single-connection store would need for the lookup.
+			const pendingSchemaCheck = schemaCheckFor(adapter)?.();
+			if (pendingSchemaCheck) await pendingSchemaCheck;
 			const pendingHooks: Array<() => Promise<void>> = [];
 			let result: Awaited<R>;
 			let error: unknown;

package/src/db/adapter/atomic-fallback.ts

@@ -0,0 +1,237 @@
+import * as z from "zod";
+import { BetterAuthError } from "../../error";
+import type { CleanedWhere, CustomAdapter, Where } from "./index";
+
+const MAX_ATTEMPTS = 5;
+
+const scalar = z
+	.union([z.string(), z.number(), z.boolean(), z.date()])
+	.nullable();
+const rowSchema = z.record(z.string(), z.unknown());
+const readSchema = rowSchema.nullish();
+const setSchema = z.record(z.string(), z.unknown()).transform((values) => {
+	const assignments: z.output<typeof rowSchema> = {};
+	for (const [field, value] of Object.entries(values)) {
+		if (value !== undefined) assignments[field] = value;
+	}
+	return assignments;
+});
+const mutationSchema = z.object({
+	increment: z.record(z.string(), z.number()),
+	set: setSchema.optional(),
+});
+const counterSchema = z.number().nullish();
+
+type StoredRow = z.output<typeof rowSchema>;
+
+type FallbackContext = {
+	adapter: CustomAdapter;
+	adapterId: string;
+	mapKeysTransformInput?: Record<string, string> | undefined;
+	mapKeysTransformOutput?: Record<string, string> | undefined;
+	getFieldName: (input: { model: string; field: string }) => string;
+	transformOutput: (
+		row: StoredRow,
+		model: string,
+		select: string[],
+		join: undefined,
+	) => Promise<{ id?: unknown } | null>;
+	transformWhereClause: (input: {
+		model: string;
+		where: Where[];
+		action: "consumeOne" | "incrementOne";
+	}) => CleanedWhere[];
+};
+
+type FallbackRequest = {
+	model: string;
+	logicalModel: string;
+	where: CleanedWhere[];
+};
+
+// Read a snapshot, then conditionally mutate it. A write succeeds only when
+// an adapter checks and mutates atomically and reports exactly one affected row.
+export function createAtomicFallbacks(context: FallbackContext) {
+	const { adapter, adapterId } = context;
+	const outputId =
+		Object.entries(context.mapKeysTransformOutput ?? {}).find(
+			([, field]) => field === "id",
+		)?.[0] ?? "id";
+	async function idWhere(
+		row: StoredRow,
+		model: string,
+		action: "consumeOne" | "incrementOne",
+	): Promise<CleanedWhere> {
+		const mappedId =
+			context.mapKeysTransformInput?.id ||
+			context.getFieldName({ model, field: "id" });
+		if (row[mappedId] === undefined || row[mappedId] === null) {
+			throw new BetterAuthError(
+				`Adapter "${context.adapterId}" must return the row id for atomic fallbacks.`,
+			);
+		}
+		const output = await context.transformOutput(
+			row,
+			model,
+			[outputId],
+			undefined,
+		);
+		const id = output?.id;
+		if (typeof id !== "string" && typeof id !== "number") {
+			throw new BetterAuthError(
+				`Adapter "${context.adapterId}" must expose a logical string or number id through its output transform.`,
+			);
+		}
+		const [condition] = context.transformWhereClause({
+			model,
+			where: [{ field: "id", value: id }],
+			action,
+		});
+		if (!condition)
+			throw new BetterAuthError(
+				"The atomic fallback id condition was transformed away.",
+			);
+		return condition;
+	}
+	async function readRow({
+		model,
+		where,
+	}: FallbackRequest): Promise<StoredRow | null> {
+		const result = readSchema.safeParse(
+			await adapter.findOne<unknown>({ model, where }),
+		);
+		if (!result.success) {
+			throw new BetterAuthError(
+				`Adapter "${adapterId}" must return a row snapshot or null.`,
+			);
+		}
+		return result.data ?? null;
+	}
+
+	async function snapshotGuard(
+		row: StoredRow,
+		fields: readonly string[],
+		request: FallbackRequest,
+		action: "consumeOne" | "incrementOne",
+	): Promise<CleanedWhere[]> {
+		const id = await idWhere(row, request.logicalModel, action);
+		const hasOr = request.where.some((clause) => clause.connector === "OR");
+		const guard: CleanedWhere[] = hasOr ? [id] : [...request.where, id];
+		const keys = new Set(fields);
+		for (const field of keys) {
+			if (field === id.field) continue;
+			const value = scalar.safeParse(row[field] ?? null);
+			if (!value.success) {
+				if (hasOr && request.where.some((clause) => clause.field === field)) {
+					throw new BetterAuthError(
+						`Adapter "${adapterId}" must implement native atomic methods for OR predicates on structured values.`,
+					);
+				}
+				continue;
+			}
+			guard.push({
+				field,
+				value: value.data,
+				operator: "eq",
+				connector: "AND",
+				mode: "sensitive",
+			});
+		}
+		return guard;
+	}
+
+	function changedOne(count: number): boolean {
+		if (count !== 0 && count !== 1) {
+			throw new BetterAuthError(
+				`Adapter "${adapterId}" must return an affected row count of 0 or 1 from an atomic fallback.`,
+			);
+		}
+		return count === 1;
+	}
+
+	async function consumeOne(
+		request: FallbackRequest,
+	): Promise<StoredRow | null> {
+		const { model, where } = request;
+		const row = await readRow(request);
+		if (row === null) return null;
+		// Guard the selected snapshot with AND predicates, without widening an OR selector.
+		const guard = await snapshotGuard(
+			row,
+			[...Object.keys(row), ...where.map(({ field }) => field)],
+			request,
+			"consumeOne",
+		);
+		const count = await adapter.deleteMany({ model, where: guard });
+		return changedOne(count) ? row : null;
+	}
+
+	async function incrementOne(
+		request: FallbackRequest & {
+			increment: Record<string, number>;
+			set?: Record<string, unknown> | undefined;
+		},
+	): Promise<StoredRow | null> {
+		const { model, where } = request;
+		const mutation = mutationSchema.safeParse(request);
+		if (!mutation.success) {
+			throw new BetterAuthError(
+				"incrementOne requires finite increments and a set object for the atomic fallback.",
+			);
+		}
+		const { increment, set } = mutation.data;
+		const deltas = Object.entries(increment);
+		const fields = [
+			...where.map(({ field }) => field),
+			...Object.keys(increment),
+			...Object.keys(set ?? {}),
+		];
+		for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+			const row = await readRow(request);
+			if (row === null) return null;
+			const update: z.output<typeof setSchema> = { ...set };
+			for (const [field, delta] of deltas) {
+				const previous = counterSchema.safeParse(row[field]);
+				if (!previous.success) {
+					throw new BetterAuthError(
+						`Adapter "${adapterId}" must return finite numeric counter values or null for atomic increments.`,
+					);
+				}
+				const current = previous.data ?? 0;
+				const next = current + delta;
+				if (!Number.isFinite(next) || (delta !== 0 && next === current)) {
+					throw new BetterAuthError(
+						`Adapter "${adapterId}" cannot represent the requested counter increment safely.`,
+					);
+				}
+				update[field] = next;
+			}
+			const guard = await snapshotGuard(row, fields, request, "incrementOne");
+			// A no-op takes effect at the read. Stores counting changed rows would report zero.
+			if (
+				Object.entries(update).every(([field, value]) => {
+					const previous = row[field];
+					if (previous instanceof Date && value instanceof Date) {
+						return previous.getTime() === value.getTime();
+					}
+					return Object.is(previous, value);
+				})
+			)
+				return row;
+			const count = await adapter.updateMany({
+				model,
+				where: guard,
+				update,
+			});
+			if (changedOne(count)) {
+				// A second read could observe another writer's result instead of ours.
+				return { ...row, ...update };
+			}
+		}
+		throw new BetterAuthError(
+			`Adapter "${adapterId}" could not complete an atomic increment due to contention. Retry the operation or implement incrementOne natively.`,
+		);
+	}
+
+	return { consumeOne, incrementOne };
+}