@better-auth/core 1.7.1 → 1.7.3

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

package/src/db/schema-diff.ts

@@ -0,0 +1,270 @@
+import { BetterAuthError } from "../error";
+import type { BetterAuthOptions } from "../types";
+import { getAuthTables } from "./get-tables";
+import type { DBFieldAttribute } from "./type";
+
+/**
+ * A column as the database, or an ORM schema definition, reports it.
+ */
+export interface IntrospectedColumn {
+	name: string;
+	nullable: boolean;
+	/**
+	 * The store fills the column when an insert omits it.
+	 */
+	hasDefault: boolean;
+}
+
+/**
+ * A table as the database, or an ORM schema definition, reports it.
+ */
+export interface IntrospectedTable {
+	name: string;
+	/**
+	 * The schema the table lives in, when the store has schemas.
+	 */
+	schema?: string | undefined;
+	columns: IntrospectedColumn[];
+}
+
+/**
+ * The tables Better Auth writes, keyed the way the store addresses them:
+ * physical table name, then physical column name. A table that manages its
+ * own storage is excluded from migrations and from this comparison.
+ */
+export type ExpectedSchema = Record<
+	string,
+	{
+		fields: Record<string, DBFieldAttribute>;
+		idColumn?: string | undefined;
+		disableMigrations?: boolean | undefined;
+		/**
+		 * The schema the table is addressed in. Unset when the store has no
+		 * schemas or the table is found by name alone.
+		 */
+		schema?: string | undefined;
+	}
+>;
+
+/**
+ * The tables this configuration writes, keyed the way the adapter addresses
+ * them. Tables that share a physical name are merged into one entry.
+ */
+export function getExpectedSchema(
+	options: BetterAuthOptions,
+	{ usePlural = false }: { usePlural?: boolean | undefined } = {},
+): ExpectedSchema {
+	const expected: ExpectedSchema = {};
+	for (const table of Object.values(getAuthTables(options))) {
+		const name = usePlural ? `${table.modelName}s` : table.modelName;
+		const entry = (expected[name] ??= { fields: {}, disableMigrations: true });
+		for (const [key, field] of Object.entries(table.fields)) {
+			entry.fields[field.fieldName || key] = field;
+		}
+		entry.disableMigrations =
+			entry.disableMigrations && !!table.disableMigrations;
+	}
+	return expected;
+}
+
+export type SchemaFinding =
+	| { kind: "missing-table"; table: string }
+	| { kind: "missing-column"; table: string; column: string }
+	| { kind: "unexpected-required-column"; table: string; column: string };
+
+/**
+ * How the schema reaches the store, which decides the fix each finding names.
+ */
+export type SchemaSource = "database" | "drizzle" | "prisma";
+
+/**
+ * Compares the tables Better Auth writes with what the store holds.
+ *
+ * A table or column Better Auth writes must exist. A column Better Auth does
+ * not write must accept an insert that omits it, so it is nullable or carries
+ * a default. Otherwise every insert into that table fails with a constraint
+ * error that says nothing about why the schema drifted.
+ */
+export function diffSchema(
+	expected: ExpectedSchema,
+	actual: readonly IntrospectedTable[],
+): SchemaFinding[] {
+	const findings: SchemaFinding[] = [];
+	for (const [tableName, table] of Object.entries(expected)) {
+		if (table.disableMigrations) continue;
+		const actualTable = actual.find(
+			(candidate) =>
+				candidate.name === tableName &&
+				(table.schema === undefined || candidate.schema === table.schema),
+		);
+		if (!actualTable) {
+			findings.push({ kind: "missing-table", table: tableName });
+			continue;
+		}
+		const written = new Set([
+			table.idColumn ?? "id",
+			...Object.keys(table.fields),
+		]);
+		for (const column of written) {
+			if (!actualTable.columns.some((candidate) => candidate.name === column)) {
+				findings.push({ kind: "missing-column", table: tableName, column });
+			}
+		}
+		for (const column of actualTable.columns) {
+			if (written.has(column.name) || column.nullable || column.hasDefault) {
+				continue;
+			}
+			findings.push({
+				kind: "unexpected-required-column",
+				table: tableName,
+				column: column.name,
+			});
+		}
+	}
+	return findings;
+}
+
+const applyHint: Record<SchemaSource, string> = {
+	database: "Run `npx auth migrate` to add it.",
+	drizzle:
+		"Run `npx auth generate` to refresh the Drizzle schema, then apply it with your migration tool.",
+	prisma:
+		"Run `npx auth generate` to refresh the Prisma schema, then run `prisma migrate`.",
+};
+
+const relaxHint: Record<SchemaSource, string> = {
+	database: "Drop the column, make it nullable, or give it a database default.",
+	drizzle:
+		"Remove it from the Drizzle schema, make it nullable, or give it a default, then apply the change with your migration tool.",
+	prisma:
+		"Remove it from the Prisma schema, make it optional, or give it a default, then run `prisma migrate`.",
+};
+
+const sourceLabel: Record<SchemaSource, string> = {
+	database: "Database",
+	drizzle: "Drizzle",
+	prisma: "Prisma",
+};
+
+/**
+ * One finding as a sentence that names the change resolving it.
+ */
+export function formatSchemaFinding(
+	finding: SchemaFinding,
+	source: SchemaSource,
+): string {
+	switch (finding.kind) {
+		case "missing-table":
+			return `Table "${finding.table}" is missing. ${applyHint[source]}`;
+		case "missing-column":
+			return `Column "${finding.column}" is missing from table "${finding.table}". ${applyHint[source]}`;
+		case "unexpected-required-column": {
+			const issuer =
+				finding.column === "issuer"
+					? " If this column came from Better Auth 1.7.0 through 1.7.2, follow the upgrade guide before removing it: https://www.better-auth.com/docs/guides/1-7-upgrade-guide"
+					: "";
+			return `Column "${finding.column}" on table "${finding.table}" is required but Better Auth never writes it, so every insert into "${finding.table}" fails. ${relaxHint[source]}${issuer}`;
+		}
+	}
+}
+
+const repairHint: Record<SchemaSource, string> = {
+	database:
+		"Make the listed columns nullable, give them defaults, or remove them.",
+	drizzle:
+		"Make the listed columns nullable in your Drizzle schema, give them defaults, or remove them.",
+	prisma:
+		"Make the listed fields optional in your Prisma schema, give them defaults, or remove them.",
+};
+
+const migrationHint: Record<SchemaSource, string> = {
+	...applyHint,
+	database: "Run `npx auth migrate` to add the missing tables and columns.",
+};
+
+function formatSchemaMismatch(
+	findings: readonly SchemaFinding[],
+	source: SchemaSource,
+): string {
+	const tables: string[] = [];
+	const columns: string[] = [];
+	const required: string[] = [];
+	const affectedTables = new Set<string>();
+	let hasIssuer = false;
+	for (const finding of findings) {
+		switch (finding.kind) {
+			case "missing-table":
+				tables.push(finding.table);
+				break;
+			case "missing-column":
+				columns.push(`${finding.table}.${finding.column}`);
+				break;
+			case "unexpected-required-column":
+				required.push(`${finding.table}.${finding.column}`);
+				affectedTables.add(finding.table);
+				hasIssuer ||= finding.column === "issuer";
+				break;
+		}
+	}
+
+	const sections = [`${sourceLabel[source]} schema mismatch`];
+	if (tables.length)
+		sections.push(`  Missing tables\n    ${tables.join(", ")}`);
+	if (columns.length)
+		sections.push(`  Missing columns\n    ${columns.join("\n    ")}`);
+	if (required.length) {
+		sections.push(
+			`  Required columns Better Auth never writes\n    ${required.join("\n    ")}`,
+		);
+		sections.push(
+			`  Inserts into ${[...affectedTables].join(", ")} will fail.`,
+		);
+	}
+
+	const help: string[] = [];
+	if (required.length) help.push(repairHint[source]);
+	if (
+		tables.length ||
+		columns.length ||
+		(required.length && source !== "database")
+	) {
+		help.push(migrationHint[source]);
+	}
+	if (help.length) sections.push(`  help: ${help.join("\n        ")}`);
+	if (hasIssuer) {
+		sections.push(
+			"  note: If this column came from Better Auth 1.7.0 through 1.7.2,\n" +
+				"        follow the upgrade guide before removing it:\n" +
+				"        https://www.better-auth.com/docs/guides/1-7-upgrade-guide",
+		);
+	}
+	return sections.join("\n\n");
+}
+
+/**
+ * The store cannot hold what this configuration writes.
+ *
+ * `findings` carries every problem as data; `message` lists each one with the
+ * change that resolves it. Reported during initialization and thrown when
+ * requests await validation, in every environment. Also thrown by
+ * `auth migrate` before it changes anything.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await auth.api.getSession({ headers });
+ * } catch (error) {
+ *   if (error instanceof SchemaMismatchError) console.error(error.findings);
+ * }
+ * ```
+ */
+export class SchemaMismatchError extends BetterAuthError {
+	readonly code = "SCHEMA_MISMATCH";
+
+	constructor(
+		readonly findings: readonly SchemaFinding[],
+		readonly source: SchemaSource,
+	) {
+		super(formatSchemaMismatch(findings, source));
+	}
+}

package/src/env/logger.ts

@@ -1,3 +1,5 @@
+import type { AuthEndpointContext } from "../context/endpoint-context";
+import { __getCurrentEndpointContext } from "../context/global";
 import { getColorDepth } from "./color-depth";
 
 export const TTY_COLORS = {
@@ -142,4 +144,23 @@ export const createLogger = (options?: Logger | undefined): InternalLogger => {
 	};
 };
 
-export const logger = createLogger();
+const defaultLogger = createLogger();
+
+const getCurrentLogger = (): InternalLogger => {
+	const currentLogger =
+		__getCurrentEndpointContext<AuthEndpointContext>()?.context.logger;
+	return currentLogger && currentLogger !== logger
+		? currentLogger
+		: defaultLogger;
+};
+
+export const logger: InternalLogger = {
+	debug: (...params) => getCurrentLogger().debug(...params),
+	info: (...params) => getCurrentLogger().info(...params),
+	success: (...params) => getCurrentLogger().success(...params),
+	warn: (...params) => getCurrentLogger().warn(...params),
+	error: (...params) => getCurrentLogger().error(...params),
+	get level() {
+		return getCurrentLogger().level;
+	},
+};

package/src/oauth2/index.ts

@@ -80,6 +80,8 @@ export {
 export type {
 	TokenEndpointAuth,
 	TokenEndpointAuthMethod,
+	TokenEndpointRequestContext,
+	TokenEndpointRequestHook,
 	TokenEndpointSecretAuthentication,
 } from "./token-endpoint-auth";
 export {