@better-auth/core 1.7.2 → 1.7.3

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 };
+}

package/src/db/adapter/factory.ts

@@ -8,6 +8,7 @@ import { BetterAuthError } from "../../error";
 import type { BetterAuthOptions } from "../../types";
 import { safeJSONParse } from "../../utils/json";
 import { getAuthTables } from "../get-tables";
+import { createAtomicFallbacks } from "./atomic-fallback";
 import { initGetDefaultFieldName } from "./get-default-field-name";
 import { initGetDefaultModelName } from "./get-default-model-name";
 import { initGetFieldAttributes } from "./get-field-attributes";
@@ -841,6 +842,16 @@ export const createAdapterFactory =
 		});
 
 		let lazyLoadTransaction: DBAdapter<Options>["transaction"] | null = null;
+		const atomicFallbacks = createAtomicFallbacks({
+			adapter: adapterInstance,
+			adapterId: config.adapterId,
+			mapKeysTransformInput: config.mapKeysTransformInput,
+			mapKeysTransformOutput: config.mapKeysTransformOutput,
+			getFieldName,
+			transformOutput,
+			transformWhereClause,
+		});
+
 		const adapter: DBAdapter<Options> = {
 			transaction: async (cb) => {
 				if (!lazyLoadTransaction) {
@@ -1366,18 +1377,20 @@ export const createAdapterFactory =
 					{ model, where },
 				);
 
-				if (typeof adapterInstance.consumeOne !== "function") {
-					throw new BetterAuthError(
-						`Adapter "${config.adapterId}" must implement consumeOne for atomic single-use credential consumption.`,
-					);
-				}
 				const res = await withSpan(
 					`db consumeOne ${model}`,
 					{
 						[ATTR_DB_OPERATION_NAME]: "consumeOne",
 						[ATTR_DB_COLLECTION_NAME]: model,
 					},
-					() => adapterInstance.consumeOne<T>({ model, where }),
+					() =>
+						adapterInstance.consumeOne
+							? adapterInstance.consumeOne<T>({ model, where })
+							: atomicFallbacks.consumeOne({
+									model,
+									logicalModel: unsafeModel,
+									where,
+								}),
 				);
 
 				debugLog(
@@ -1440,11 +1453,6 @@ export const createAdapterFactory =
 					{ 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)) {
@@ -1473,12 +1481,20 @@ export const createAdapterFactory =
 						[ATTR_DB_COLLECTION_NAME]: model,
 					},
 					() =>
-						adapterInstance.incrementOne<T>({
-							model,
-							where,
-							increment,
-							set,
-						}),
+						adapterInstance.incrementOne
+							? adapterInstance.incrementOne<T>({
+									model,
+									where,
+									increment,
+									set,
+								})
+							: atomicFallbacks.incrementOne({
+									model,
+									logicalModel: unsafeModel,
+									where,
+									increment,
+									set,
+								}),
 				);
 
 				debugLog(

package/src/db/adapter/index.ts

@@ -466,9 +466,9 @@ 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. The underlying
-	 * `CustomAdapter` must implement this natively; there is no portable
-	 * fallback that can guarantee cross-process single-use semantics.
+	 * Always defined on the factory-wrapped adapter. Without a native method,
+	 * the factory uses a snapshot-guarded delete and requires an exact affected
+	 * row count. The adapter must evaluate the condition and deletion atomically.
 	 */
 	consumeOne: <T>(data: { model: string; where: Where[] }) => Promise<T | null>;
 	/**
@@ -490,9 +490,11 @@ export type DBAdapter<Options extends BetterAuthOptions = BetterAuthOptions> = {
 	 * 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.
+	 * Always defined on the factory-wrapped adapter. Without a native method,
+	 * the factory uses bounded compare-and-swap retries. Contention exhaustion
+	 * throws rather than returning null. Conditional writes must be atomic.
+	 * A no-op may return the read snapshot without writing. A non-null result
+	 * alone does not establish exclusive ownership of the row.
 	 */
 	incrementOne: <T>(data: {
 		model: string;
@@ -587,19 +589,21 @@ export interface CustomAdapter {
 		where: CleanedWhere[];
 	}) => Promise<number>;
 	/**
-	 * Native atomic single-row consume.
+	 * Optional 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.
 	 */
-	consumeOne: <T>(data: {
+	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
+	 * Optional 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.
@@ -608,7 +612,7 @@ export interface CustomAdapter {
 	 * RETURNING *`) gives one round trip and the strongest race-safety
 	 * guarantee.
 	 */
-	incrementOne: <T>(data: {
+	incrementOne?: <T>(data: {
 		model: string;
 		where: CleanedWhere[];
 		increment: Record<string, number>;

package/src/db/get-tables.ts

@@ -250,21 +250,8 @@ const buildAuthTables = (options: BetterAuthOptions): BetterAuthDBSchema => {
 			: {}),
 		account: {
 			modelName: options.account?.modelName || "account",
-			indexes: mergeTableIndexes(
-				[
-					{
-						fields: ["issuer", "accountId"],
-						unique: true,
-					},
-				],
-				account?.indexes,
-			),
+			indexes: account?.indexes,
 			fields: {
-				issuer: {
-					type: "string",
-					required: true,
-					fieldName: options.account?.fields?.issuer || "issuer",
-				},
 				accountId: {
 					type: "string",
 					required: true,

package/src/db/index.ts

@@ -5,8 +5,6 @@ export {
 	type AccountKey,
 	accountSchema,
 	type BaseAccount,
-	createLocalAccountIssuer,
-	createOAuthAccountIssuer,
 } from "./schema/account";
 export {
 	type BaseRateLimit,

package/src/db/internal.ts

@@ -10,3 +10,22 @@ export {
 	resolveDatabaseTableIndexes,
 } from "./database-index";
 export { getAuthTablesWithResolvedIndexes } from "./get-tables";
+export {
+	checksSchema,
+	createSchemaCheck,
+	invalidateSchemaChecks,
+	registerSchemaCheck,
+	type SchemaCheck,
+	schemaCheckFor,
+} from "./schema-check";
+export {
+	diffSchema,
+	type ExpectedSchema,
+	formatSchemaFinding,
+	getExpectedSchema,
+	type IntrospectedColumn,
+	type IntrospectedTable,
+	type SchemaFinding,
+	SchemaMismatchError,
+	type SchemaSource,
+} from "./schema-diff";

package/src/db/schema/account.ts

@@ -9,7 +9,6 @@ import { coreSchema } from "./shared";
 
 export const accountSchema = coreSchema.extend({
 	providerId: z.string(),
-	issuer: z.string(),
 	accountId: z.string(),
 	userId: z.coerce.string(),
 	accessToken: z.string().nullish(),
@@ -39,27 +38,9 @@ export const accountSchema = coreSchema.extend({
 export type BaseAccount = z.infer<typeof accountSchema>;
 
 /** The stable provider-side key used to recognize an account. */
-export type AccountKey = Readonly<Pick<BaseAccount, "issuer" | "accountId">>;
-
-function encodeAccountIssuerProviderId(providerId: string): string {
-	return encodeURIComponent(providerId);
-}
-
-/**
- * Creates the synthetic issuer used by providers without an issuer of their own.
- */
-export function createLocalAccountIssuer(providerId: string): string {
-	return `local:${encodeAccountIssuerProviderId(providerId)}`;
-}
-
-/**
- * Creates the synthetic issuer used by OAuth providers without an issuer of
- * their own. OAuth identities use a distinct namespace so a provider ID
- * cannot collide with an internal local authentication method.
- */
-export function createOAuthAccountIssuer(providerId: string): string {
-	return `local:oauth:${encodeAccountIssuerProviderId(providerId)}`;
-}
+export type AccountKey = Readonly<
+	Pick<BaseAccount, "providerId" | "accountId">
+>;
 
 /**
  * Account schema type used by better-auth, note that it's possible that account could have additional fields

package/src/db/schema/user.ts

@@ -9,7 +9,7 @@ import { coreSchema } from "./shared";
 export const userSchema = coreSchema.extend({
 	// TODO(#9124): widen to nullish in v2. OAuth providers (Discord phone-only,
 	// Apple subsequent sign-ins, etc.) can legitimately omit email; identity
-	// must key on (issuer, accountId) per OpenID Connect Core §5.7.
+	// must key on (providerId, accountId) per OpenID Connect Core §5.7.
 	email: z.string().transform((val) => val.toLowerCase()),
 	emailVerified: z.boolean().default(false),
 	name: z.string(),

package/src/db/schema-check.ts

@@ -0,0 +1,107 @@
+/**
+ * Internal schema validation infrastructure for built-in adapters.
+ *
+ * Intended to become a public core extension point for community database
+ * adapter authors once the registration and lifecycle contracts are stabilized.
+ */
+
+import type { BetterAuthOptions } from "../types";
+import type { SchemaFinding, SchemaSource } from "./schema-diff";
+import { SchemaMismatchError } from "./schema-diff";
+
+/**
+ * Whether the adapter validates its schema. Enabled in every environment
+ * unless explicitly disabled.
+ */
+export function checksSchema(options: BetterAuthOptions): boolean {
+	return options.advanced?.database?.validateSchema !== false;
+}
+
+/**
+ * Resolves when the schema can hold what Better Auth writes. Returns nothing
+ * once that is known and the database schema revision is unchanged.
+ */
+export type SchemaCheck = () => Promise<void> | undefined;
+
+const schemaChecks = new WeakMap<object, SchemaCheck>();
+const schemaRevisions = new WeakMap<object, { value: number }>();
+
+/** Invalidates cached checks after Better Auth changes this database's schema. */
+export function invalidateSchemaChecks(database: object): void {
+	const revision = schemaRevisions.get(database);
+	if (revision) revision.value++;
+}
+
+/**
+ * Attaches a check to the adapter it verifies. The adapter object itself is
+ * left untouched, so this works for adapters Better Auth does not own.
+ */
+export function registerSchemaCheck(adapter: object, check: SchemaCheck): void {
+	schemaChecks.set(adapter, check);
+}
+
+/**
+ * The check registered for an adapter, if its store is checked at all.
+ */
+export function schemaCheckFor(adapter: object): SchemaCheck | undefined {
+	return schemaChecks.get(adapter);
+}
+
+/**
+ * Turns a schema comparison into a check shared by one adapter instance.
+ *
+ * The first call runs `find` and every concurrent call shares that promise. A
+ * clean result is cached until invalidation. A mismatch is kept as one
+ * {@link SchemaMismatchError} and rethrown on every later call without asking
+ * the store again, until a migration invalidates it. When a database identity is supplied,
+ * checks for that identity share its schema revision. Pending callers follow
+ * the new check if their revision is invalidated. A failure to reach
+ * the store is not kept, so the next call asks again.
+ *
+ * @example
+ * ```ts
+ * const checkSchema = createSchemaCheck(
+ *   () => findSchemaProblems(db, "postgres", expected),
+ *   "database",
+ * );
+ * const pending = checkSchema();
+ * if (pending) await pending;
+ * ```
+ */
+export function createSchemaCheck(
+	find: () => Promise<SchemaFinding[]>,
+	source: SchemaSource,
+	database?: object,
+): SchemaCheck {
+	let revision = database ? schemaRevisions.get(database) : undefined;
+	if (database && !revision) {
+		revision = { value: 0 };
+		schemaRevisions.set(database, revision);
+	}
+	let checkedRevision = revision?.value;
+	let clean = false;
+	let verdict: Promise<void> | undefined;
+	return function checkSchema(): Promise<void> | undefined {
+		const currentRevision = revision?.value;
+		if (checkedRevision !== currentRevision) {
+			checkedRevision = currentRevision;
+			clean = false;
+			verdict = undefined;
+		}
+		if (clean) return;
+		return (verdict ??= Promise.resolve()
+			.then(find)
+			.then(
+				(findings) => {
+					if (revision?.value !== currentRevision) return checkSchema();
+					if (findings.length) throw new SchemaMismatchError(findings, source);
+					if (checkedRevision === currentRevision) clean = true;
+				},
+				(error: unknown) => {
+					if (revision?.value !== currentRevision) return checkSchema();
+					if (checkedRevision === currentRevision) verdict = undefined;
+					throw error;
+				},
+			));
+	};
+}