@better-auth/core 1.7.2 → 1.7.3

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/oauth2/index.ts

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

package/src/oauth2/oauth-provider.ts

@@ -251,16 +251,6 @@ export interface OAuthProvider<
 	 * against this value to prevent authorization server mix-up attacks.
 	 */
 	issuer?: string | undefined;
-	/**
-	 * Stable issuer used with the provider subject to recognize an account.
-	 *
-	 * Use the validated OpenID Connect issuer for OIDC providers. A resolver is
-	 * supported for tenant-specific issuers and receives only provider-verified
-	 * data. OAuth providers without an issuer omit this property and are scoped
-	 * to the synthetic `local:oauth:<encoded providerId>` issuer, where the
-	 * provider ID segment is percent-encoded.
-	 */
-	accountIssuer?: string | OAuthAccountKeyResolver<T, string> | undefined;
 	/**
 	 * Require shared OAuth redirect routes to bind ID-token verification to an
 	 * authorization request nonce. When true, routes generate `idTokenNonce`,

package/src/oauth2/token-endpoint-auth.ts

@@ -19,23 +19,44 @@ export type TokenEndpointAuth =
 	| {
 			method: "private_key_jwt";
 			getClientAssertion: ClientAssertionGetter;
+	  }
+	| {
+			method: "custom";
+			/**
+			 * Customize the token request after standard grant parameters are set.
+			 */
+			customizeRequest: TokenEndpointRequestHook;
 	  };
 
 export type TokenEndpointAuthMethod = TokenEndpointAuth["method"];
 
 export type TokenEndpointSecretAuthentication = "basic" | "post";
 
-export interface TokenEndpointClientOptions {
-	clientId?: string | string[] | undefined;
-	clientSecret?: string | undefined;
-}
-
-export interface ApplyTokenEndpointAuthInput {
+/**
+ * Mutable token request state passed to a custom authentication strategy.
+ */
+export interface TokenEndpointRequestContext {
 	body: URLSearchParams;
 	headers: Record<string, string>;
 	options: TokenEndpointClientOptions;
 	tokenEndpoint: string;
 	grantType: ClientAssertionGrantType;
+}
+
+/**
+ * Applies provider-specific authentication to a token request.
+ */
+export type TokenEndpointRequestHook = (
+	context: TokenEndpointRequestContext,
+) => void | Promise<void>;
+
+export interface TokenEndpointClientOptions {
+	clientId?: string | string[] | undefined;
+	clientSecret?: string | undefined;
+}
+
+export interface ApplyTokenEndpointAuthInput
+	extends TokenEndpointRequestContext {
 	tokenEndpointAuth?: TokenEndpointAuth | undefined;
 	authentication?: TokenEndpointSecretAuthentication | undefined;
 }
@@ -172,6 +193,18 @@ export async function applyTokenEndpointAuth({
 	const auth =
 		tokenEndpointAuth ?? getDefaultTokenEndpointAuth(options, authentication);
 
+	if (auth.method === "custom") {
+		await auth.customizeRequest({
+			body,
+			headers,
+			options,
+			tokenEndpoint,
+			grantType,
+		});
+		assertCompleteManualClientAssertion(body);
+		return;
+	}
+
 	if (auth.method === "private_key_jwt") {
 		assertNoClientSecret(auth.method, options, body);
 		assertClientIdConfigured(auth.method, clientId);

package/src/social-providers/apple.ts

@@ -83,7 +83,6 @@ export const apple = (options: AppleOptions) => {
 		id: "apple",
 		name: "Apple",
 		accountSubject: ({ profile }) => profile.sub,
-		accountIssuer: "https://appleid.apple.com",
 		async createAuthorizationURL({
 			state,
 			scopes,

package/src/social-providers/cloudflare.ts

@@ -0,0 +1,221 @@
+import { betterFetch } from "@better-fetch/fetch";
+import { logger } from "../env";
+import type {
+	OAuthProvider,
+	ProviderOptions,
+	TokenEndpointAuth,
+} from "../oauth2";
+import {
+	createAuthorizationURL,
+	refreshAccessToken,
+	validateAuthorizationCode,
+} from "../oauth2";
+
+const authorizationEndpoint = "https://dash.cloudflare.com/oauth2/auth";
+const tokenEndpoint = "https://dash.cloudflare.com/oauth2/token";
+
+/**
+ * Cloudflare's OIDC `userinfo` endpoint only returns the `sub` claim, so it
+ * cannot be used to build a user. The user's profile (email, name, ...) is
+ * read from the Cloudflare API `/user` endpoint instead, which the access
+ * token can call when the `user-details.read` scope is granted.
+ */
+const userEndpoint = "https://api.cloudflare.com/client/v4/user";
+
+/**
+ * The user profile returned by the Cloudflare API `/user` endpoint.
+ *
+ * @see https://developers.cloudflare.com/api/resources/user/methods/get/
+ */
+export interface CloudflareProfile {
+	/**
+	 * Identifier of the user.
+	 */
+	id: string;
+	/**
+	 * Current email address of the user.
+	 */
+	email: string;
+	/**
+	 * The user's first name.
+	 */
+	first_name?: string | null | undefined;
+	/**
+	 * The user's last name.
+	 */
+	last_name?: string | null | undefined;
+	/**
+	 * The country in which the user lives.
+	 */
+	country?: string | null | undefined;
+	/**
+	 * The user's telephone number.
+	 */
+	telephone?: string | null | undefined;
+	/**
+	 * The zipcode or postal code where the user lives.
+	 */
+	zipcode?: string | null | undefined;
+	/**
+	 * Indicates whether two-factor authentication is enabled for the user account.
+	 */
+	two_factor_authentication_enabled?: boolean | undefined;
+	/**
+	 * Indicates whether the user has been suspended.
+	 */
+	suspended?: boolean | undefined;
+}
+
+/**
+ * The standard Cloudflare API response envelope for the `/user` endpoint.
+ */
+interface CloudflareUserResponse {
+	success: boolean;
+	errors: { code: number; message: string }[];
+	result: CloudflareProfile | null;
+}
+
+/**
+ * Token endpoint authentication supported by Cloudflare OAuth clients.
+ *
+ * @see https://developers.cloudflare.com/fundamentals/oauth/create-an-oauth-client/#choose-a-flow
+ */
+type CloudflareClientAuthentication =
+	| {
+			/**
+			 * The client secret of a confidential Cloudflare OAuth client.
+			 */
+			clientSecret: string;
+			/**
+			 * The authentication method configured for the token endpoint.
+			 *
+			 * @default "client_secret_basic"
+			 */
+			tokenEndpointAuthMethod?:
+				| "client_secret_basic"
+				| "client_secret_post"
+				| undefined;
+	  }
+	| {
+			/**
+			 * Clients that use PKCE do not have a client secret.
+			 */
+			clientSecret?: undefined;
+			/**
+			 * Clients without a secret do not authenticate at the token endpoint.
+			 *
+			 * @default "none"
+			 */
+			tokenEndpointAuthMethod?: "none" | undefined;
+	  };
+
+interface CloudflareBaseOptions extends ProviderOptions<CloudflareProfile> {
+	/**
+	 * The client ID of the Cloudflare OAuth client.
+	 */
+	clientId: string;
+}
+
+/**
+ * Options for configuring the Cloudflare social provider.
+ */
+export type CloudflareOptions = CloudflareBaseOptions &
+	CloudflareClientAuthentication;
+
+const getTokenEndpointAuth = (
+	options: CloudflareOptions,
+): TokenEndpointAuth => {
+	const defaultMethod = options.clientSecret ? "client_secret_basic" : "none";
+	const method = options.tokenEndpointAuthMethod ?? defaultMethod;
+
+	return { method };
+};
+
+export const cloudflare = (options: CloudflareOptions) => {
+	return {
+		id: "cloudflare",
+		name: "Cloudflare",
+		accountSubject: ({ profile }) => profile.id,
+		createAuthorizationURL({ state, scopes, codeVerifier, redirectURI }) {
+			const _scopes = options.disableDefaultScope ? [] : ["user-details.read"];
+
+			if (options.scope?.length) {
+				_scopes.push(...options.scope);
+			}
+
+			if (scopes?.length) {
+				_scopes.push(...scopes);
+			}
+
+			return createAuthorizationURL({
+				id: "cloudflare",
+				options,
+				authorizationEndpoint,
+				scopes: _scopes.length ? [...new Set(_scopes)] : undefined,
+				state,
+				codeVerifier,
+				redirectURI,
+			});
+		},
+		validateAuthorizationCode: async ({ code, codeVerifier, redirectURI }) => {
+			return validateAuthorizationCode({
+				code,
+				codeVerifier,
+				redirectURI,
+				options,
+				tokenEndpoint,
+				tokenEndpointAuth: getTokenEndpointAuth(options),
+			});
+		},
+		refreshAccessToken: options.refreshAccessToken
+			? options.refreshAccessToken
+			: async (refreshToken) => {
+					return refreshAccessToken({
+						refreshToken,
+						options: {
+							clientId: options.clientId,
+							clientKey: options.clientKey,
+							clientSecret: options.clientSecret,
+						},
+						tokenEndpoint,
+						tokenEndpointAuth: getTokenEndpointAuth(options),
+					});
+				},
+		async getUserInfo(token) {
+			if (options.getUserInfo) {
+				return options.getUserInfo(token);
+			}
+
+			const { data, error } = await betterFetch<CloudflareUserResponse>(
+				userEndpoint,
+				{ headers: { authorization: `Bearer ${token.accessToken}` } },
+			);
+
+			if (error || !data?.success || !data.result) {
+				logger.error(
+					"Failed to fetch user info from Cloudflare:",
+					error ?? data?.errors,
+				);
+				return null;
+			}
+
+			const profile = data.result;
+			const name =
+				[profile.first_name, profile.last_name].filter(Boolean).join(" ") ||
+				profile.email;
+			const userMap = await options.mapProfileToUser?.(profile);
+
+			return {
+				user: {
+					name,
+					email: profile.email,
+					// Cloudflare does not expose email verification status
+					emailVerified: false,
+					...userMap,
+				},
+				data: profile,
+			};
+		},
+		options,
+	} satisfies OAuthProvider<CloudflareProfile>;
+};

package/src/social-providers/cognito.ts

@@ -74,7 +74,6 @@ export const cognito = (options: CognitoOptions) => {
 		id: "cognito",
 		name: "Cognito",
 		accountSubject: ({ profile }) => profile.sub,
-		accountIssuer: `https://cognito-idp.${options.region}.amazonaws.com/${options.userPoolId}`,
 		async createAuthorizationURL({
 			state,
 			scopes,

package/src/social-providers/facebook.ts

@@ -108,7 +108,6 @@ export const facebook = (options: FacebookOptions) => {
 		name: "Facebook",
 		accountSubject: ({ profile }) =>
 			"sub" in profile ? profile.sub : profile.id,
-		accountIssuer: "https://www.facebook.com",
 		async createAuthorizationURL({
 			state,
 			scopes,

package/src/social-providers/google.ts

@@ -151,7 +151,6 @@ export const google = (options: GoogleOptions) => {
 		id: "google",
 		name: "Google",
 		accountSubject: ({ profile }) => profile.sub,
-		accountIssuer: "https://accounts.google.com",
 		async createAuthorizationURL({
 			state,
 			scopes,

package/src/social-providers/index.ts

@@ -2,6 +2,7 @@ import * as z from "zod";
 import type { AwaitableFunction } from "../types";
 import { apple } from "./apple";
 import { atlassian } from "./atlassian";
+import { cloudflare } from "./cloudflare";
 import { cognito } from "./cognito";
 import { discord } from "./discord";
 import { dropbox } from "./dropbox";
@@ -39,6 +40,7 @@ import { zoom } from "./zoom";
 export const socialProviders = {
 	apple,
 	atlassian,
+	cloudflare,
 	cognito,
 	discord,
 	facebook,
@@ -95,6 +97,7 @@ export type SocialProviders = {
 
 export * from "./apple";
 export * from "./atlassian";
+export * from "./cloudflare";
 export * from "./cognito";
 export * from "./discord";
 export * from "./dropbox";

package/src/social-providers/line.ts

@@ -51,7 +51,6 @@ export const line = (options: LineOptions) => {
 		id: "line",
 		name: "LINE",
 		accountSubject: ({ profile }) => profile.sub,
-		accountIssuer: "https://access.line.me",
 		async createAuthorizationURL({
 			state,
 			scopes,

package/src/social-providers/microsoft-entra-id.ts

@@ -188,7 +188,6 @@ export const microsoft = (options: MicrosoftOptions) => {
 		id: "microsoft",
 		name: "Microsoft EntraID",
 		accountSubject: ({ profile }) => profile.oid,
-		accountIssuer: ({ profile }) => profile.iss,
 		createAuthorizationURL(data) {
 			// Microsoft Entra supports public clients (SPA / native apps with
 			// PKCE only), so clientSecret is intentionally not required here.

package/src/social-providers/paybin.ts

@@ -37,7 +37,6 @@ export const paybin = (options: PaybinOptions) => {
 		id: "paybin",
 		name: "Paybin",
 		accountSubject: ({ profile }) => profile.sub,
-		accountIssuer: issuer,
 		async createAuthorizationURL({
 			state,
 			scopes,