@better-auth/core 1.7.0-rc.0 → 1.7.0-rc.2

package/src/db/database-index.ts

@@ -0,0 +1,351 @@
+import { BetterAuthError } from "../error";
+import type { DBFieldAttribute, DBTableIndex } from "./type";
+
+const MAX_DATABASE_INDEX_NAME_BYTES = 63;
+const MAX_DATABASE_INDEX_FIELDS = 16;
+
+export function getPortableDatabaseIdentifierKey(identifier: string) {
+	return identifier.toLowerCase();
+}
+
+function getUtf8ByteLength(value: string) {
+	return new TextEncoder().encode(value).length;
+}
+
+function truncateUtf8(value: string, maxBytes: number) {
+	let result = "";
+	let byteLength = 0;
+	for (const character of value) {
+		const characterByteLength = getUtf8ByteLength(character);
+		if (byteLength + characterByteLength > maxBytes) break;
+		result += character;
+		byteLength += characterByteLength;
+	}
+	return result;
+}
+
+function getStableIndexNameHash(value: string) {
+	let hash = 0x811c9dc5;
+	for (let index = 0; index < value.length; index++) {
+		hash ^= value.charCodeAt(index);
+		hash = Math.imul(hash, 0x01000193);
+	}
+	return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+/** A table-level index resolved to physical database columns. */
+export interface ResolvedDBTableIndex extends Omit<DBTableIndex, "fields"> {
+	/** Physical database column names, in index order. */
+	columns: readonly [string, ...string[]];
+	name: string;
+}
+
+export interface DBTableIndexSource {
+	fields: Readonly<Record<string, DBFieldAttribute>>;
+	indexes: readonly DBTableIndex[] | undefined;
+	tableName: string;
+}
+
+export type BoundedDatabaseIndexDialect = "mssql" | "mysql";
+
+/** Returns the stable database name for a table-level index. */
+export function getDatabaseIndexName(
+	tableName: string,
+	index: DBTableIndex,
+): string {
+	if (index.name !== undefined) {
+		if (index.name.trim().length === 0) {
+			throw new BetterAuthError(
+				"Database index names must contain at least one visible character.",
+			);
+		}
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(index.name)) {
+			throw new BetterAuthError(
+				"Database index names must start with a letter or underscore and contain only letters, numbers, and underscores.",
+			);
+		}
+		if (getUtf8ByteLength(index.name) > MAX_DATABASE_INDEX_NAME_BYTES) {
+			throw new BetterAuthError(
+				`Database index names must be at most ${MAX_DATABASE_INDEX_NAME_BYTES} UTF-8 bytes.`,
+			);
+		}
+		return index.name;
+	}
+
+	const indexKind = index.unique ? "uidx" : "idx";
+	const generatedName = `${tableName}_${index.fields.join("_")}_${indexKind}`;
+	if (getUtf8ByteLength(generatedName) <= MAX_DATABASE_INDEX_NAME_BYTES) {
+		return generatedName;
+	}
+
+	const suffix = `_${getStableIndexNameHash(generatedName)}_${indexKind}`;
+	return `${truncateUtf8(
+		generatedName.slice(0, -indexKind.length - 1),
+		MAX_DATABASE_INDEX_NAME_BYTES - getUtf8ByteLength(suffix),
+	)}${suffix}`;
+}
+
+/** Returns the database name used by legacy field-level index metadata. */
+export function getDatabaseFieldIndexName(
+	tableName: string,
+	columnName: string,
+	unique: boolean,
+) {
+	return getDatabaseIndexName(tableName, {
+		fields: [columnName],
+		unique,
+	});
+}
+
+/** Resolves logical index fields to their configured database column names. */
+export function resolveDatabaseTableIndexes({
+	fields,
+	indexes,
+	tableName,
+}: {
+	fields: Readonly<Record<string, DBFieldAttribute>>;
+	indexes: readonly DBTableIndex[] | undefined;
+	tableName: string;
+}): readonly ResolvedDBTableIndex[] {
+	const resolvedIndexes = (indexes ?? []).map((index) => {
+		if (index.fields.length === 0) {
+			throw new BetterAuthError(
+				`Index on table "${tableName}" must include at least one field.`,
+			);
+		}
+		if (index.fields.length > MAX_DATABASE_INDEX_FIELDS) {
+			throw new BetterAuthError(
+				`Index on table "${tableName}" can include at most ${MAX_DATABASE_INDEX_FIELDS} fields so it works across supported databases.`,
+			);
+		}
+		if (new Set(index.fields).size !== index.fields.length) {
+			throw new BetterAuthError(
+				`Index on table "${tableName}" contains the same field more than once.`,
+			);
+		}
+		if (
+			index.unique &&
+			index.fields.some((fieldName) => fields[fieldName]?.required === false)
+		) {
+			throw new BetterAuthError(
+				`Unique index on table "${tableName}" can only include required fields so its behavior is consistent across databases.`,
+			);
+		}
+		const unsupportedField = index.fields.find((fieldName) => {
+			const fieldType = fields[fieldName]?.type;
+			return (
+				fieldType === "json" ||
+				fieldType === "string[]" ||
+				fieldType === "number[]"
+			);
+		});
+		if (unsupportedField) {
+			throw new BetterAuthError(
+				`Index on table "${tableName}" references field "${unsupportedField}", whose type is not portably indexable.`,
+			);
+		}
+		const resolveFieldName = (fieldName: string) => {
+			const field = fields[fieldName];
+			if (!field) {
+				throw new BetterAuthError(
+					`Index on table "${tableName}" references unknown field "${fieldName}".`,
+				);
+			}
+			return field.fieldName || fieldName;
+		};
+		const [firstField, ...remainingFields] = index.fields;
+		const columns = [
+			resolveFieldName(firstField),
+			...remainingFields.map(resolveFieldName),
+		] as ResolvedDBTableIndex["columns"];
+		if (
+			new Set(columns.map(getPortableDatabaseIdentifierKey)).size !==
+			columns.length
+		) {
+			throw new BetterAuthError(
+				`Index on table "${tableName}" resolves more than one field to the same database column.`,
+			);
+		}
+
+		return {
+			columns,
+			name: getDatabaseIndexName(tableName, {
+				...index,
+				fields: columns,
+			}),
+			unique: index.unique,
+		} satisfies ResolvedDBTableIndex;
+	});
+
+	const definitionsByName = new Map<string, string>();
+	const deduplicatedIndexes: ResolvedDBTableIndex[] = [];
+	for (const index of resolvedIndexes) {
+		const definition = JSON.stringify([index.columns, index.unique ?? false]);
+		const identifierKey = getPortableDatabaseIdentifierKey(index.name);
+		const existingDefinition = definitionsByName.get(identifierKey);
+		if (existingDefinition && existingDefinition !== definition) {
+			throw new BetterAuthError(
+				`Database index name "${index.name}" identifies more than one index on table "${tableName}".`,
+			);
+		}
+		if (existingDefinition) continue;
+		definitionsByName.set(identifierKey, definition);
+		deduplicatedIndexes.push(index);
+	}
+	return deduplicatedIndexes;
+}
+
+/**
+ * Returns a safe generated string length for a column across all of its table
+ * indexes in byte-limited SQL dialects.
+ */
+export function getDatabaseIndexStringLength({
+	columnName,
+	dialect,
+	fields,
+	indexes,
+}: {
+	columnName: string;
+	dialect: BoundedDatabaseIndexDialect;
+	fields: Readonly<Record<string, DBFieldAttribute>>;
+	indexes: readonly ResolvedDBTableIndex[];
+}): number | undefined {
+	const fieldsByColumn = new Map(
+		Object.entries(fields).map(([fieldName, field]) => [
+			field.fieldName || fieldName,
+			field,
+		]),
+	);
+	const containingIndexes = indexes.filter((index) =>
+		index.columns.includes(columnName),
+	);
+	if (containingIndexes.length === 0) return undefined;
+
+	const byteBudget = dialect === "mysql" ? 3072 : 1700;
+	const bytesPerCharacter = dialect === "mysql" ? 4 : 1;
+	const defaultLength = dialect === "mysql" ? 191 : 255;
+	return containingIndexes.reduce((length, index) => {
+		const stringColumnCount = index.columns.filter((column) => {
+			const type = fieldsByColumn.get(column)?.type;
+			return type === "string" || Array.isArray(type);
+		}).length;
+		if (stringColumnCount === 0) return length;
+		const nonStringColumnBytes =
+			(index.columns.length - stringColumnCount) * 16;
+		const safeLength = Math.floor(
+			Math.max(1, byteBudget - nonStringColumnBytes) /
+				bytesPerCharacter /
+				stringColumnCount,
+		);
+		return Math.min(length, safeLength);
+	}, defaultLength);
+}
+
+/**
+ * Resolves and validates every table index as one portable database schema.
+ *
+ * Index names are schema-wide because SQLite and PostgreSQL do not scope them
+ * to an individual table.
+ */
+export function resolveDatabaseSchemaIndexes(
+	sources: readonly DBTableIndexSource[],
+): ReadonlyMap<string, readonly ResolvedDBTableIndex[]> {
+	const mergedSourcesByTable = new Map<
+		string,
+		{
+			fields: Record<string, DBFieldAttribute>;
+			indexes: DBTableIndex[];
+			tableName: string;
+		}
+	>();
+	for (const source of sources) {
+		const existingSource = mergedSourcesByTable.get(source.tableName);
+		if (existingSource) {
+			if (
+				existingSource.indexes.length > 0 ||
+				(source.indexes?.length ?? 0) > 0
+			) {
+				throw new BetterAuthError(
+					`Database schema resolves more than one indexed logical table to "${source.tableName}". Define table-level indexes through one logical schema key instead of aliasing multiple keys to the same database table.`,
+				);
+			}
+			Object.assign(existingSource.fields, source.fields);
+			continue;
+		}
+		const mergedSource: {
+			fields: Record<string, DBFieldAttribute>;
+			indexes: DBTableIndex[];
+			tableName: string;
+		} = {
+			fields: {},
+			indexes: [],
+			tableName: source.tableName,
+		};
+		Object.assign(mergedSource.fields, source.fields);
+		mergedSource.indexes.push(...(source.indexes ?? []));
+		mergedSourcesByTable.set(source.tableName, mergedSource);
+	}
+
+	const indexesByTable = new Map<string, ResolvedDBTableIndex[]>();
+	const indexOwnerByName = new Map<string, string>();
+	const tableNamesByIdentifier = new Map(
+		[...mergedSourcesByTable.keys()].map((tableName) => [
+			getPortableDatabaseIdentifierKey(tableName),
+			tableName,
+		]),
+	);
+	const fieldIndexOwnerByName = new Map<string, string>();
+
+	for (const source of mergedSourcesByTable.values()) {
+		for (const [fieldName, field] of Object.entries(source.fields)) {
+			if (!field.index && !field.unique) continue;
+			const indexName = getDatabaseFieldIndexName(
+				source.tableName,
+				field.fieldName || fieldName,
+				field.unique ?? false,
+			);
+			const identifierKey = getPortableDatabaseIdentifierKey(indexName);
+			if (tableNamesByIdentifier.has(identifierKey)) {
+				throw new BetterAuthError(
+					`Database index name "${indexName}" conflicts with a table name. Index and table names must be unique across the schema.`,
+				);
+			}
+			const existingOwner = fieldIndexOwnerByName.get(identifierKey);
+			if (existingOwner) {
+				throw new BetterAuthError(
+					`Database field-level index name "${indexName}" is used by both table "${existingOwner}" and table "${source.tableName}".`,
+				);
+			}
+			fieldIndexOwnerByName.set(identifierKey, source.tableName);
+		}
+	}
+
+	for (const source of mergedSourcesByTable.values()) {
+		const resolvedIndexes = resolveDatabaseTableIndexes(source);
+		indexesByTable.set(source.tableName, [...resolvedIndexes]);
+
+		for (const index of resolvedIndexes) {
+			const identifierKey = getPortableDatabaseIdentifierKey(index.name);
+			if (tableNamesByIdentifier.has(identifierKey)) {
+				throw new BetterAuthError(
+					`Database index name "${index.name}" conflicts with a table name. Index and table names must be unique across the schema.`,
+				);
+			}
+			const fieldIndexOwner = fieldIndexOwnerByName.get(identifierKey);
+			if (fieldIndexOwner) {
+				throw new BetterAuthError(
+					`Database index name "${index.name}" is already reserved by field-level index metadata on table "${fieldIndexOwner}". Remove the duplicate table-level index or give it a distinct name.`,
+				);
+			}
+			const indexOwner = indexOwnerByName.get(identifierKey);
+			if (indexOwner && indexOwner !== source.tableName) {
+				throw new BetterAuthError(
+					`Database index name "${index.name}" is used by both table "${indexOwner}" and table "${source.tableName}". Index names must be unique across the schema.`,
+				);
+			}
+			indexOwnerByName.set(identifierKey, source.tableName);
+		}
+	}
+
+	return indexesByTable;
+}

package/src/db/get-tables.ts

@@ -1,9 +1,32 @@
 import type { BetterAuthOptions } from "../types";
-import type { BetterAuthDBSchema, DBFieldAttribute } from "./type";
+import { resolveDatabaseSchemaIndexes } from "./database-index";
+import type {
+	BetterAuthDBSchema,
+	DBFieldAttribute,
+	DBTableIndex,
+} from "./type";
 
-export const getAuthTables = (
-	options: BetterAuthOptions,
-): BetterAuthDBSchema => {
+function mergeTableIndexes(
+	...indexCollections: ReadonlyArray<readonly DBTableIndex[] | undefined>
+) {
+	const indexes: DBTableIndex[] = [];
+	const seenIndexDefinitions = new Set<string>();
+	for (const index of indexCollections.flatMap(
+		(collection) => collection ?? [],
+	)) {
+		const definition = JSON.stringify([
+			index.name ?? null,
+			index.fields,
+			index.unique ?? false,
+		]);
+		if (seenIndexDefinitions.has(definition)) continue;
+		seenIndexDefinitions.add(definition);
+		indexes.push(index);
+	}
+	return indexes;
+}
+
+const buildAuthTables = (options: BetterAuthOptions): BetterAuthDBSchema => {
 	const pluginSchema = (options.plugins ?? []).reduce(
 		(acc, plugin) => {
 			const schema = plugin.schema;
@@ -14,6 +37,7 @@ export const getAuthTables = (
 						...acc[key]?.fields,
 						...value.fields,
 					},
+					indexes: mergeTableIndexes(acc[key]?.indexes, value.indexes),
 					modelName: value.modelName || key,
 					disableMigrations:
 						value.disableMigration ?? acc[key]?.disableMigrations,
@@ -25,6 +49,7 @@ export const getAuthTables = (
 			string,
 			{
 				fields: Record<string, DBFieldAttribute>;
+				indexes?: readonly DBTableIndex[] | undefined;
 				modelName: string;
 				disableMigrations?: boolean | undefined;
 			}
@@ -64,6 +89,7 @@ export const getAuthTables = (
 	const verificationTable = {
 		verification: {
 			modelName: options.verification?.modelName || "verification",
+			indexes: verification?.indexes,
 			fields: {
 				identifier: {
 					type: "string",
@@ -104,6 +130,7 @@ export const getAuthTables = (
 	const sessionTable = {
 		session: {
 			modelName: options.session?.modelName || "session",
+			indexes: session?.indexes,
 			fields: {
 				expiresAt: {
 					type: "date",
@@ -142,7 +169,18 @@ export const getAuthTables = (
 					type: "string",
 					fieldName: options.session?.fields?.userId || "userId",
 					references: {
-						model: options.user?.modelName || "user",
+						// Use the canonical user schema key here rather than
+						// `options.user.modelName`. Downstream consumers (e.g.
+						// `getSchema`, `getMigrations`, and the runtime adapter
+						// resolvers) treat `references.model` as a schema key
+						// and look it up via `tables[references.model]` /
+						// `getDefaultModelName`. Writing the modelName alias
+						// here would collide when a user picks a modelName that
+						// matches another schema key (for example
+						// `user.modelName = "account"`), causing the FK to
+						// resolve to the wrong table.
+						// @see https://github.com/better-auth/better-auth/issues/8111
+						model: "user",
 						field: "id",
 						onDelete: "cascade",
 					},
@@ -156,9 +194,10 @@ export const getAuthTables = (
 		},
 	} satisfies BetterAuthDBSchema;
 
-	return {
+	const authTables = {
 		user: {
 			modelName: options.user?.modelName || "user",
+			indexes: user?.indexes,
 			fields: {
 				name: {
 					type: "string",
@@ -211,11 +250,26 @@ export const getAuthTables = (
 			: {}),
 		account: {
 			modelName: options.account?.modelName || "account",
+			indexes: mergeTableIndexes(
+				[
+					{
+						fields: ["issuer", "providerAccountId"],
+						unique: true,
+					},
+				],
+				account?.indexes,
+			),
 			fields: {
-				accountId: {
+				issuer: {
+					type: "string",
+					required: true,
+					fieldName: options.account?.fields?.issuer || "issuer",
+				},
+				providerAccountId: {
 					type: "string",
 					required: true,
-					fieldName: options.account?.fields?.accountId || "accountId",
+					fieldName:
+						options.account?.fields?.providerAccountId || "providerAccountId",
 				},
 				providerId: {
 					type: "string",
@@ -225,7 +279,11 @@ export const getAuthTables = (
 				userId: {
 					type: "string",
 					references: {
-						model: options.user?.modelName || "user",
+						// See note on `session.userId.references.model` above:
+						// always use the canonical user schema key so the FK
+						// target survives `user.modelName` aliasing.
+						// @see https://github.com/better-auth/better-auth/issues/8111
+						model: "user",
 						field: "id",
 						onDelete: "cascade",
 					},
@@ -301,4 +359,26 @@ export const getAuthTables = (
 		...pluginTables,
 		...(shouldAddRateLimitTable ? rateLimitTable : {}),
 	} satisfies BetterAuthDBSchema;
+
+	return authTables;
 };
+
+export function getAuthTablesWithResolvedIndexes(options: BetterAuthOptions) {
+	const tables = buildAuthTables(options);
+	const indexesByTable = resolveDatabaseSchemaIndexes(
+		Object.values(tables)
+			.filter(
+				(table) => !("disableMigrations" in table) || !table.disableMigrations,
+			)
+			.map((table) => ({
+				fields: table.fields,
+				indexes: "indexes" in table ? table.indexes : undefined,
+				tableName: table.modelName,
+			})),
+	);
+
+	return { indexesByTable, tables };
+}
+
+export const getAuthTables = (options: BetterAuthOptions): BetterAuthDBSchema =>
+	getAuthTablesWithResolvedIndexes(options).tables;

package/src/db/index.ts

@@ -2,8 +2,11 @@ export { getAuthTables } from "./get-tables";
 export type { BetterAuthPluginDBSchema } from "./plugin";
 export {
 	type Account,
+	type AccountKey,
 	accountSchema,
 	type BaseAccount,
+	createLocalAccountIssuer,
+	createOAuthAccountIssuer,
 } from "./schema/account";
 export {
 	type BaseRateLimit,
@@ -29,6 +32,7 @@ export type {
 	DBFieldAttributeConfig,
 	DBFieldType,
 	DBPrimitive,
+	DBTableIndex,
 	InferDBFieldInput,
 	InferDBFieldOutput,
 	InferDBFieldsFromOptions,

package/src/db/internal.ts

@@ -0,0 +1,12 @@
+export {
+	type BoundedDatabaseIndexDialect,
+	type DBTableIndexSource,
+	getDatabaseFieldIndexName,
+	getDatabaseIndexName,
+	getDatabaseIndexStringLength,
+	getPortableDatabaseIdentifierKey,
+	type ResolvedDBTableIndex,
+	resolveDatabaseSchemaIndexes,
+	resolveDatabaseTableIndexes,
+} from "./database-index";
+export { getAuthTablesWithResolvedIndexes } from "./get-tables";

package/src/db/plugin.ts

@@ -1,10 +1,12 @@
-import type { DBFieldAttribute } from "./type";
+import type { DBFieldAttribute, DBTableIndex } from "./type";
 
 export type BetterAuthPluginDBSchema = {
 	[table in string]: {
 		fields: {
 			[field: string]: DBFieldAttribute;
 		};
+		/** Table-level indexes, including compound indexes. */
+		indexes?: readonly DBTableIndex[] | undefined;
 		disableMigration?: boolean | undefined;
 		modelName?: string | undefined;
 	};

package/src/db/schema/account.ts

@@ -9,7 +9,8 @@ import { coreSchema } from "./shared";
 
 export const accountSchema = coreSchema.extend({
 	providerId: z.string(),
-	accountId: z.string(),
+	issuer: z.string(),
+	providerAccountId: z.string(),
 	userId: z.coerce.string(),
 	accessToken: z.string().nullish(),
 	refreshToken: z.string().nullish(),
@@ -37,6 +38,31 @@ 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" | "providerAccountId">
+>;
+
+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)}`;
+}
+
 /**
  * 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 (providerId, accountId) per OpenID Connect Core §5.7.
+	// must key on (issuer, providerAccountId) per OpenID Connect Core §5.7.
 	email: z.string().transform((val) => val.toLowerCase()),
 	emailVerified: z.boolean().default(false),
 	name: z.string(),

package/src/db/type.ts

@@ -281,6 +281,16 @@ export type DBFieldAttribute<T extends DBFieldType = DBFieldType> = {
 	type: T;
 } & DBFieldAttributeConfig;
 
+/** A database index spanning one or more logical schema fields. */
+export interface DBTableIndex {
+	/** One to sixteen logical field names included in the index, in index order. */
+	fields: readonly [string, ...string[]];
+	/** Portable database index name of at most 63 UTF-8 bytes. */
+	name?: string | undefined;
+	/** Whether the indexed field tuple must be unique. */
+	unique?: boolean | undefined;
+}
+
 export type BetterAuthDBSchema = Record<
 	string,
 	{
@@ -292,6 +302,8 @@ export type BetterAuthDBSchema = Record<
 		 * The fields of the table
 		 */
 		fields: Record<string, DBFieldAttribute>;
+		/** Table-level indexes, including compound indexes. */
+		indexes?: readonly DBTableIndex[] | undefined;
 		/**
 		 * Whether to disable migrations for this table
 		 * @default false

package/src/oauth2/index.ts

@@ -65,7 +65,10 @@ export {
 export type {
 	OAuth2Tokens,
 	OAuth2UserInfo,
+	OAuthAccountKeyContext,
+	OAuthAccountSubject,
 	OAuthIdTokenConfig,
+	OAuthMappedUser,
 	OAuthProvider,
 	OAuthRefreshContext,
 	ProviderOptions,