@better-auth/core 1.7.0-rc.1 → 1.7.0-rc.3

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/error/codes.ts

@@ -1,3 +1,4 @@
+import type {} from "@better-auth/core";
 import { defineErrorCodes } from "../utils/error-codes";
 
 declare module "@better-auth/core" {

package/src/oauth2/index.ts

@@ -65,7 +65,10 @@ export {
 export type {
 	OAuth2Tokens,
 	OAuth2UserInfo,
+	OAuthAccountKeyContext,
+	OAuthAccountSubject,
 	OAuthIdTokenConfig,
+	OAuthMappedUser,
 	OAuthProvider,
 	OAuthRefreshContext,
 	ProviderOptions,
@@ -97,7 +100,9 @@ export type {
 	VerifyAccessTokenRequestOptions,
 } from "./verify";
 export {
+	createInsufficientScopeError,
 	getJwks,
+	isInsufficientScopeError,
 	requestToResourceInput,
 	verifyAccessTokenRequest,
 	verifyBearerToken,

package/src/oauth2/oauth-provider.ts

@@ -1,5 +1,9 @@
 import type { JWTVerifyGetKey } from "jose";
-import type { Awaitable, LiteralString } from "../types";
+import type {
+	Awaitable,
+	GenericEndpointContext,
+	LiteralString,
+} from "../types";
 
 /**
  * id_token verification config for a social provider.
@@ -51,7 +55,11 @@ export type OAuthIdTokenConfig =
 			 * Custom verifier for providers that cannot verify against a local JWKS, such as a
 			 * remote verification endpoint (e.g. LINE).
 			 */
-			verify: (token: string, nonce?: string) => Promise<boolean>;
+			verify: (
+				token: string,
+				nonce?: string,
+				ctx?: GenericEndpointContext,
+			) => Promise<boolean>;
 	  };
 
 export interface OAuth2Tokens {
@@ -69,14 +77,52 @@ export interface OAuth2Tokens {
 	raw?: Record<string, unknown> | undefined;
 }
 
+/** Mutable local-user attributes normalized from an OAuth provider profile. */
 export type OAuth2UserInfo = {
-	id: string | number;
+	/** Provider identity belongs in raw profile data and `accountSubject`. */
+	id?: never;
 	name?: string | undefined;
 	email?: (string | null) | undefined;
 	image?: string | undefined;
 	emailVerified: boolean;
 };
 
+/**
+ * Verified provider data available when deriving a stable OAuth account key.
+ *
+ * Account-key resolvers must use the raw provider profile or verified token
+ * response. They never receive the mapped local user, so profile mapping
+ * cannot redefine provider identity.
+ */
+export interface OAuthAccountKeyContext<Profile extends object = object> {
+	tokens: OAuth2Tokens;
+	profile: Profile;
+}
+
+/**
+ * Resolves one part of an account key from a profile returned by the same
+ * provider. The method-derived callback keeps that profile pairing intact when
+ * providers with different profile shapes share an `OAuthProvider[]`.
+ */
+type OAuthAccountKeyResolver<Profile extends object, Value> = {
+	resolve(context: OAuthAccountKeyContext<Profile>): Awaitable<Value>;
+}["resolve"];
+
+/** Resolves the stable provider subject used to build an OAuth account key. */
+export type OAuthAccountSubject<Profile extends object = object> =
+	OAuthAccountKeyResolver<Profile, string | number>;
+
+/** Mutable local-user attributes returned by `mapProfileToUser`. */
+export type OAuthMappedUser = {
+	/** Provider identity is defined by `accountSubject`, not local user mapping. */
+	id?: never;
+	name?: string;
+	email?: string | null;
+	image?: string;
+	emailVerified?: boolean;
+	[key: string]: unknown;
+};
+
 /**
  * Request metadata available to provider refresh hooks.
  *
@@ -90,8 +136,8 @@ export interface OAuthRefreshContext {
 }
 
 export interface OAuthProvider<
-	T extends Record<string, any> = Record<string, any>,
-	O extends Record<string, any> = Partial<ProviderOptions>,
+	T extends object = object,
+	O extends object = Partial<ProviderOptions>,
 > {
 	id: LiteralString;
 	/**
@@ -127,6 +173,15 @@ export interface OAuthProvider<
 		additionalParams?: Record<string, string> | undefined;
 	}) => Awaitable<URL>;
 	name: string;
+	/**
+	 * Stable subject that identifies the provider account.
+	 *
+	 * Read this value from the raw, provider-verified profile. For OpenID
+	 * Connect providers, use the `sub` claim. For OAuth providers, use the
+	 * provider's documented immutable user identifier. Never derive this value
+	 * from `mapProfileToUser`.
+	 */
+	accountSubject: OAuthAccountSubject<T>;
 	validateAuthorizationCode: (data: {
 		code: string;
 		redirectURI: string;
@@ -173,6 +228,17 @@ export interface OAuthProvider<
 		  ) => Promise<OAuth2Tokens>)
 		| undefined;
 	revokeToken?: ((token: string) => Promise<void>) | undefined;
+	/**
+	 * Builds an OpenID Connect RP-Initiated Logout URL for this provider.
+	 * Returns `null` when provider logout is unavailable or disabled.
+	 */
+	createEndSessionURL?:
+		| ((data: {
+				idToken?: string | null | undefined;
+				postLogoutRedirectURI?: string | undefined;
+				state?: string | undefined;
+		  }) => Awaitable<URL | null>)
+		| undefined;
 	/**
 	 * Declarative id_token verification config consumed by the shared
 	 * `verifyProviderIdToken` verifier. Providers set this instead of implementing a boolean
@@ -185,6 +251,16 @@ 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`,
@@ -218,7 +294,15 @@ export interface OAuthProvider<
 	options?: O | undefined;
 }
 
-export type ProviderOptions<Profile extends Record<string, any> = any> = {
+/**
+ * Maps a provider-specific profile while remaining compatible with the erased
+ * profile type used by shared OAuth helpers.
+ */
+type OAuthProfileMapper<Profile extends object> = {
+	map(profile: Profile): Awaitable<OAuthMappedUser>;
+}["map"];
+
+export type ProviderOptions<Profile extends object = object> = {
 	/**
 	 * The client ID of your application.
 	 *
@@ -262,25 +346,28 @@ export type ProviderOptions<Profile extends Record<string, any> = any> = {
 	 */
 	disableIdTokenSignIn?: boolean | undefined;
 	/**
-	 * verifyIdToken function to verify the id token
+	 * verifyIdToken function to verify the id token.
+	 *
+	 * The optional endpoint context exposes request metadata to custom
+	 * verifiers without coupling built-in provider verification to a runtime.
 	 */
 	verifyIdToken?:
-		| ((token: string, nonce?: string) => Promise<boolean>)
+		| ((
+				token: string,
+				nonce?: string,
+				ctx?: GenericEndpointContext,
+		  ) => Promise<boolean>)
 		| undefined;
 	/**
 	 * Custom function to get user info from the provider
+	 *
+	 * `data` must preserve the declared raw profile shape because account-key
+	 * resolvers consume it after this hook returns.
 	 */
 	getUserInfo?:
 		| ((token: OAuth2Tokens) => Promise<{
-				user: {
-					id: string;
-					name?: string;
-					email?: string | null;
-					image?: string;
-					emailVerified: boolean;
-					[key: string]: any;
-				};
-				data: any;
+				user: OAuth2UserInfo & Record<string, unknown>;
+				data: Profile;
 		  } | null>)
 		| undefined;
 	/**
@@ -293,25 +380,7 @@ export type ProviderOptions<Profile extends Record<string, any> = any> = {
 	 * Custom function to map the provider profile to a
 	 * user.
 	 */
-	mapProfileToUser?:
-		| ((profile: Profile) =>
-				| {
-						id?: string;
-						name?: string;
-						email?: string | null;
-						image?: string;
-						emailVerified?: boolean;
-						[key: string]: any;
-				  }
-				| Promise<{
-						id?: string;
-						name?: string;
-						email?: string | null;
-						image?: string;
-						emailVerified?: boolean;
-						[key: string]: any;
-				  }>)
-		| undefined;
+	mapProfileToUser?: OAuthProfileMapper<Profile> | undefined;
 	/**
 	 * Disable implicit sign up for new users. When set to true for the provider,
 	 * sign-in need to be called with with requestSignUp as true to create new users.

package/src/oauth2/verify-id-token.ts

@@ -1,4 +1,5 @@
 import { decodeProtectedHeader, jwtVerify } from "jose";
+import type { GenericEndpointContext } from "../types";
 import type { OAuthProvider, ProviderOptions } from "./oauth-provider";
 
 type ProviderWithIdTokenConfig = Pick<OAuthProvider, "idToken" | "options">;
@@ -59,6 +60,7 @@ export async function verifyProviderIdToken(
 	provider: ProviderWithIdTokenConfig,
 	token: string,
 	nonce?: string,
+	ctx?: GenericEndpointContext,
 ): Promise<boolean> {
 	const options = (provider.options ?? {}) as Partial<ProviderOptions>;
 	if (options.disableIdTokenSignIn) {
@@ -69,14 +71,14 @@ export async function verifyProviderIdToken(
 	// escaping to the caller as a server error.
 	try {
 		if (options.verifyIdToken) {
-			return await options.verifyIdToken(token, nonce);
+			return await options.verifyIdToken(token, nonce, ctx);
 		}
 		const config = provider.idToken;
 		if (!config) {
 			return false;
 		}
 		if ("verify" in config) {
-			return await config.verify(token, nonce);
+			return await config.verify(token, nonce, ctx);
 		}
 		// Opaque (non-JWS) tokens carry no signature to check. They are accepted only when the
 		// provider opts in, in which case getUserInfo resolves identity from the access token via

package/src/oauth2/verify.ts

@@ -164,8 +164,16 @@ export interface VerifyAccessTokenOptions {
 	/** Verify options */
 	verifyOptions: JWTVerifyOptions &
 		Required<Pick<JWTVerifyOptions, "audience" | "issuer">>;
-	/** Scopes to additionally verify. Token must include all but not exact. */
-	scopes?: string[];
+	/** Scopes the token must satisfy. */
+	requiredScopes?: readonly string[];
+	/**
+	 * Determines whether a required scope is satisfied by the granted scope
+	 * set. Defaults to exact set membership.
+	 */
+	isScopeSatisfied?: (
+		requiredScope: string,
+		grantedScopes: ReadonlySet<string>,
+	) => boolean;
 	/** Required to verify access token locally */
 	jwksUrl?: string;
 	/** If provided, can verify a token remotely */
@@ -442,23 +450,122 @@ async function verifyAccessTokenPayload(
 			message: `no token payload`,
 		});
 
-	// Check scopes if provided
-	if (opts.scopes) {
-		const validScopes = new Set(
-			(payload.scope as string | undefined)?.split(" "),
+	const grantedScopes = parseGrantedScopes(payload.scope);
+
+	// Check scopes if provided.
+	if (opts.requiredScopes) {
+		const isScopeSatisfied =
+			opts.isScopeSatisfied ??
+			((requiredScope: string, scopes: ReadonlySet<string>) =>
+				scopes.has(requiredScope));
+		// RFC 6750 §3.1: report every missing scope at once. Challenging with one
+		// scope at a time costs the user a browser round-trip per scope.
+		const missingScopes = opts.requiredScopes.filter(
+			(scope) => !isScopeSatisfied(scope, grantedScopes),
 		);
-		for (const sc of opts.scopes) {
-			if (!validScopes.has(sc)) {
-				throw new APIError("FORBIDDEN", {
-					message: `invalid scope ${sc}`,
-				});
-			}
+		if (missingScopes.length > 0) {
+			throw createInsufficientScopeError(missingScopes);
 		}
 	}
 
 	return payload;
 }
 
+/**
+ * Build the RFC 6750 §3.1 insufficient-scope failure: the access token is valid
+ * but lacks scopes the operation needs.
+ *
+ * Resource-server challenge builders turn this into a `403` carrying a
+ * `WWW-Authenticate: Bearer error="insufficient_scope"` challenge that names
+ * `scopes`, so the client knows what to request when it re-authorizes. Throw it
+ * from a route handler to challenge for scopes only that operation needs; a
+ * plain `FORBIDDEN` stays a plain `403`, since a permission denial the client
+ * cannot fix by re-authorizing must not send the user through consent again.
+ *
+ * @param requiredScopes - Every scope the operation requires but the token lacks.
+ * @param description - RFC 6750 `error_description` text. It must use the
+ * printable ASCII character set allowed by the specification.
+ */
+const OAUTH_SCOPE_TOKEN_PATTERN = /^[\x21\x23-\x5b\x5d-\x7e]+$/;
+const OAUTH_ERROR_DESCRIPTION_PATTERN = /^[\x20-\x21\x23-\x5b\x5d-\x7e]+$/;
+const insufficientScopeErrors = new WeakSet<APIError>();
+
+function isOAuthScopeToken(value: string): boolean {
+	return OAUTH_SCOPE_TOKEN_PATTERN.test(value);
+}
+
+function validateScopeTokens(scopes: readonly string[], label: string): void {
+	for (const scope of scopes) {
+		if (!isOAuthScopeToken(scope)) {
+			throw new TypeError(`invalid ${label}: ${JSON.stringify(scope)}`);
+		}
+	}
+}
+
+function validateRequiredScopes(opts: VerifyAccessTokenOptions): void {
+	if (opts.requiredScopes) {
+		validateScopeTokens(opts.requiredScopes, "required scope");
+	}
+}
+
+function parseGrantedScopes(scope: unknown): ReadonlySet<string> {
+	if (scope === undefined) return new Set();
+	if (
+		typeof scope !== "string" ||
+		scope.length === 0 ||
+		scope.split(" ").some((token) => !isOAuthScopeToken(token))
+	) {
+		throw new APIError("UNAUTHORIZED", {
+			message: "access token scope claim is invalid",
+			error: "invalid_token",
+			error_description: "access token scope claim is invalid",
+		});
+	}
+	return new Set(scope.split(" "));
+}
+
+export function createInsufficientScopeError(
+	requiredScopes: readonly string[],
+	description = `access token is missing required scope: ${requiredScopes.join(" ")}`,
+): APIError {
+	if (requiredScopes.length === 0) {
+		throw new TypeError("requiredScopes must contain at least one scope");
+	}
+	validateScopeTokens(requiredScopes, "required scope");
+	if (
+		typeof description !== "string" ||
+		!OAUTH_ERROR_DESCRIPTION_PATTERN.test(description)
+	) {
+		throw new TypeError("invalid error_description");
+	}
+	const error = new APIError("FORBIDDEN", {
+		message: description,
+		error: "insufficient_scope",
+		error_description: description,
+		scope: [...new Set(requiredScopes)].join(" "),
+	});
+	insufficientScopeErrors.add(error);
+	return error;
+}
+
+/**
+ * Returns whether an error is a typed RFC 6750 insufficient-scope failure.
+ */
+export function isInsufficientScopeError(error: unknown): error is APIError {
+	if (
+		!(error instanceof APIError) ||
+		!insufficientScopeErrors.has(error) ||
+		error.status !== "FORBIDDEN"
+	)
+		return false;
+	const body = error.body as { error?: unknown; scope?: unknown } | undefined;
+	if (body?.error !== "insufficient_scope" || typeof body.scope !== "string") {
+		return false;
+	}
+	const scopes = body.scope.split(" ");
+	return scopes.length > 0 && scopes.every(isOAuthScopeToken);
+}
+
 function throwDpopUnauthorized(
 	message: string,
 	error?: "invalid_dpop_proof" | "invalid_token",
@@ -489,6 +596,7 @@ export async function verifyBearerToken(
 	token: string,
 	opts: VerifyAccessTokenOptions,
 ) {
+	validateRequiredScopes(opts);
 	const payload = await verifyAccessTokenPayload(token, opts);
 	if (getDpopJktFromPayload(payload)) {
 		throwDpopUnauthorized(
@@ -512,6 +620,7 @@ export async function verifyAccessTokenRequest(
 	request: ResourceRequestInput,
 	opts: VerifyAccessTokenRequestOptions,
 ) {
+	validateRequiredScopes(opts);
 	const authorization = parseAccessTokenAuthorization(
 		request.authorizationHeader,
 	);

package/src/social-providers/apple.ts

@@ -82,6 +82,8 @@ export const apple = (options: AppleOptions) => {
 	return {
 		id: "apple",
 		name: "Apple",
+		accountSubject: ({ profile }) => profile.sub,
+		accountIssuer: "https://appleid.apple.com",
 		async createAuthorizationURL({
 			state,
 			scopes,
@@ -174,7 +176,6 @@ export const apple = (options: AppleOptions) => {
 			const userMap = await options.mapProfileToUser?.(enrichedProfile);
 			return {
 				user: {
-					id: profile.sub,
 					name: enrichedProfile.name,
 					emailVerified: emailVerified,
 					email: profile.email,

package/src/social-providers/atlassian.ts

@@ -34,6 +34,7 @@ export const atlassian = (options: AtlassianOptions) => {
 	return {
 		id: "atlassian",
 		name: "Atlassian",
+		accountSubject: ({ profile }) => profile.account_id,
 
 		async createAuthorizationURL({
 			state,
@@ -120,7 +121,6 @@ export const atlassian = (options: AtlassianOptions) => {
 
 				return {
 					user: {
-						id: profile.account_id,
 						name: profile.name,
 						email: profile.email,
 						image: profile.picture,

package/src/social-providers/cognito.ts

@@ -73,6 +73,8 @@ export const cognito = (options: CognitoOptions) => {
 	return {
 		id: "cognito",
 		name: "Cognito",
+		accountSubject: ({ profile }) => profile.sub,
+		accountIssuer: `https://cognito-idp.${options.region}.amazonaws.com/${options.userPoolId}`,
 		async createAuthorizationURL({
 			state,
 			scopes,
@@ -184,7 +186,6 @@ export const cognito = (options: CognitoOptions) => {
 
 					return {
 						user: {
-							id: profile.sub,
 							name: enrichedProfile.name,
 							email: profile.email,
 							image: profile.picture,
@@ -213,7 +214,6 @@ export const cognito = (options: CognitoOptions) => {
 						const userMap = await options.mapProfileToUser?.(userInfo);
 						return {
 							user: {
-								id: userInfo.sub,
 								name:
 									userInfo.name ||
 									userInfo.given_name ||

package/src/social-providers/discord.ts

@@ -88,6 +88,7 @@ export const discord = (options: DiscordOptions) => {
 	return {
 		id: "discord",
 		name: "Discord",
+		accountSubject: ({ profile }) => profile.id,
 		createAuthorizationURL({ state, scopes, redirectURI, additionalParams }) {
 			const _scopes = options.disableDefaultScope ? [] : ["identify", "email"];
 			if (scopes) _scopes.push(...scopes);
@@ -159,7 +160,6 @@ export const discord = (options: DiscordOptions) => {
 			const userMap = await options.mapProfileToUser?.(profile);
 			return {
 				user: {
-					id: profile.id,
 					name: profile.global_name || profile.username || "",
 					email: profile.email,
 					emailVerified: profile.verified,

package/src/social-providers/dropbox.ts

@@ -31,6 +31,7 @@ export const dropbox = (options: DropboxOptions) => {
 	return {
 		id: "dropbox",
 		name: "Dropbox",
+		accountSubject: ({ profile }) => profile.account_id,
 		createAuthorizationURL: async ({
 			state,
 			scopes,
@@ -99,7 +100,6 @@ export const dropbox = (options: DropboxOptions) => {
 			const userMap = await options.mapProfileToUser?.(profile);
 			return {
 				user: {
-					id: profile.account_id,
 					name: profile.name?.display_name,
 					email: profile.email,
 					emailVerified: profile.email_verified || false,