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

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;
@@ -185,6 +240,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 +283,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 +335,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 +369,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/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,

package/src/social-providers/facebook.ts

@@ -9,7 +9,7 @@ import {
 	refreshAccessToken,
 	validateAuthorizationCode,
 } from "../oauth2";
-export interface FacebookProfile {
+export interface FacebookGraphProfile {
 	id: string;
 	name: string;
 	email?: string;
@@ -24,6 +24,17 @@ export interface FacebookProfile {
 	};
 }
 
+export interface FacebookLimitedLoginProfile {
+	sub: string;
+	email: string;
+	name: string;
+	picture: string;
+}
+
+export type FacebookProfile =
+	| FacebookGraphProfile
+	| FacebookLimitedLoginProfile;
+
 interface FacebookDebugTokenData {
 	app_id?: string;
 	is_valid?: boolean;
@@ -95,6 +106,9 @@ export const facebook = (options: FacebookOptions) => {
 	return {
 		id: "facebook",
 		name: "Facebook",
+		accountSubject: ({ profile }) =>
+			"sub" in profile ? profile.sub : profile.id,
+		accountIssuer: "https://www.facebook.com",
 		async createAuthorizationURL({
 			state,
 			scopes,
@@ -167,38 +181,18 @@ export const facebook = (options: FacebookOptions) => {
 			}
 
 			if (token.idToken && token.idToken.split(".").length === 3) {
-				const profile = decodeJwt(token.idToken) as {
-					sub: string;
-					email: string;
-					name: string;
-					picture: string;
-				};
-
-				const user = {
-					id: profile.sub,
-					name: profile.name,
-					email: profile.email,
-					picture: {
-						data: {
-							url: profile.picture,
-							height: 100,
-							width: 100,
-							is_silhouette: false,
-						},
-					},
-				};
+				const profile = decodeJwt(token.idToken) as FacebookLimitedLoginProfile;
 
 				// https://developers.facebook.com/docs/facebook-login/limited-login/permissions
 				// Facebook ID token does not include email_verified claim.
 				// We default to false for security consistency.
-				const userMap = await options.mapProfileToUser?.({
-					...user,
-					email_verified: false,
-				});
+				const userMap = await options.mapProfileToUser?.(profile);
 
 				return {
 					user: {
-						...user,
+						name: profile.name,
+						email: profile.email,
+						image: profile.picture,
 						emailVerified: false,
 						...userMap,
 					},
@@ -228,7 +222,7 @@ export const facebook = (options: FacebookOptions) => {
 				"picture",
 				...(options?.fields || []),
 			];
-			const { data: profile, error } = await betterFetch<FacebookProfile>(
+			const { data: profile, error } = await betterFetch<FacebookGraphProfile>(
 				"https://graph.facebook.com/me?fields=" + fields.join(","),
 				{
 					auth: {
@@ -247,7 +241,6 @@ export const facebook = (options: FacebookOptions) => {
 			const userMap = await options.mapProfileToUser?.(profile);
 			return {
 				user: {
-					id: profile.id,
 					name: profile.name,
 					email: profile.email,
 					image: profile.picture.data.url,

package/src/social-providers/figma.ts

@@ -24,6 +24,7 @@ export const figma = (options: FigmaOptions) => {
 	return {
 		id: "figma",
 		name: "Figma",
+		accountSubject: ({ profile }) => profile.id,
 		async createAuthorizationURL({
 			state,
 			scopes,
@@ -106,7 +107,6 @@ export const figma = (options: FigmaOptions) => {
 
 				return {
 					user: {
-						id: profile.id,
 						name: profile.handle,
 						email: profile.email,
 						image: profile.img_url,

package/src/social-providers/github.ts

@@ -63,6 +63,7 @@ export const github = (options: GithubOptions) => {
 	return {
 		id: "github",
 		name: "GitHub",
+		accountSubject: ({ profile }) => profile.id,
 		createAuthorizationURL({
 			state,
 			scopes,
@@ -171,7 +172,6 @@ export const github = (options: GithubOptions) => {
 			const userMap = await options.mapProfileToUser?.(profile);
 			return {
 				user: {
-					id: profile.id,
 					name: profile.name || profile.login || "",
 					email: profile.email,
 					image: profile.avatar_url,

package/src/social-providers/gitlab.ts

@@ -81,6 +81,7 @@ export const gitlab = (options: GitlabOptions) => {
 	return {
 		id: issuerId,
 		name: issuerName,
+		accountSubject: ({ profile }) => profile.id,
 		createAuthorizationURL: async ({
 			state,
 			scopes,
@@ -142,7 +143,6 @@ export const gitlab = (options: GitlabOptions) => {
 			// We check for it first, then default to false for security consistency.
 			return {
 				user: {
-					id: profile.id,
 					name: profile.name ?? profile.username ?? "",
 					email: profile.email,
 					image: profile.avatar_url,

package/src/social-providers/google.ts

@@ -150,6 +150,8 @@ export const google = (options: GoogleOptions) => {
 	return {
 		id: "google",
 		name: "Google",
+		accountSubject: ({ profile }) => profile.sub,
+		accountIssuer: "https://accounts.google.com",
 		async createAuthorizationURL({
 			state,
 			scopes,
@@ -254,7 +256,6 @@ export const google = (options: GoogleOptions) => {
 			const userMap = await options.mapProfileToUser?.(user);
 			return {
 				user: {
-					id: user.sub,
 					name: user.name,
 					email: user.email,
 					image: user.picture,

package/src/social-providers/huggingface.ts

@@ -47,6 +47,7 @@ export const huggingface = (options: HuggingFaceOptions) => {
 	return {
 		id: "huggingface",
 		name: "Hugging Face",
+		accountSubject: ({ profile }) => profile.sub,
 		createAuthorizationURL({
 			state,
 			scopes,
@@ -111,7 +112,6 @@ export const huggingface = (options: HuggingFaceOptions) => {
 			const userMap = await options.mapProfileToUser?.(profile);
 			return {
 				user: {
-					id: profile.sub,
 					name: profile.name || profile.preferred_username || "",
 					email: profile.email,
 					image: profile.picture,

package/src/social-providers/kakao.ts

@@ -106,6 +106,7 @@ export const kakao = (options: KakaoOptions) => {
 	return {
 		id: "kakao",
 		name: "Kakao",
+		accountSubject: ({ profile }) => profile.id,
 		createAuthorizationURL({ state, scopes, redirectURI, additionalParams }) {
 			const _scopes = options.disableDefaultScope
 				? []
@@ -162,7 +163,6 @@ export const kakao = (options: KakaoOptions) => {
 			const account = profile.kakao_account || {};
 			const kakaoProfile = account.profile || {};
 			const user = {
-				id: String(profile.id),
 				name: kakaoProfile.nickname || account.name || "",
 				email: account.email,
 				image:

package/src/social-providers/kick.ts

@@ -33,6 +33,7 @@ export const kick = (options: KickOptions) => {
 	return {
 		id: "kick",
 		name: "Kick",
+		accountSubject: ({ profile }) => profile.user_id,
 		createAuthorizationURL({
 			state,
 			scopes,
@@ -101,7 +102,6 @@ export const kick = (options: KickOptions) => {
 			// We default to false for security consistency.
 			return {
 				user: {
-					id: profile.user_id,
 					name: profile.name,
 					email: profile.email,
 					image: profile.profile_picture,

package/src/social-providers/line.ts

@@ -50,6 +50,8 @@ export const line = (options: LineOptions) => {
 	return {
 		id: "line",
 		name: "LINE",
+		accountSubject: ({ profile }) => profile.sub,
+		accountIssuer: "https://access.line.me",
 		async createAuthorizationURL({
 			state,
 			scopes,
@@ -142,24 +144,17 @@ export const line = (options: LineOptions) => {
 				profile = data || null;
 			}
 			if (!profile) return null;
-			const userMap = await options.mapProfileToUser?.(profile as any);
-			// ID preference order
-			const id = (profile as any).sub || (profile as any).userId;
-			const name = (profile as any).name || (profile as any).displayName || "";
-			const image =
-				(profile as any).picture || (profile as any).pictureUrl || undefined;
-			const email = (profile as any).email;
+			const userMap = await options.mapProfileToUser?.(profile);
 			return {
 				user: {
-					id,
-					name,
-					email,
-					image,
+					name: profile.name || "",
+					email: profile.email,
+					image: profile.picture,
 					// LINE does not expose email verification status in ID token/userinfo
 					emailVerified: false,
 					...userMap,
 				},
-				data: profile as any,
+				data: profile,
 			};
 		},
 		options,

package/src/social-providers/linear.ts

@@ -31,6 +31,7 @@ export const linear = (options: LinearOptions) => {
 	return {
 		id: "linear",
 		name: "Linear",
+		accountSubject: ({ profile }) => profile.id,
 		createAuthorizationURL({
 			state,
 			scopes,
@@ -113,7 +114,6 @@ export const linear = (options: LinearOptions) => {
 			// We default to false for security consistency.
 			return {
 				user: {
-					id: profile.data.viewer.id,
 					name: profile.data.viewer.name,
 					email: profile.data.viewer.email,
 					image: profile.data.viewer.avatarUrl,

package/src/social-providers/linkedin.ts

@@ -32,6 +32,7 @@ export const linkedin = (options: LinkedInOptions) => {
 	return {
 		id: "linkedin",
 		name: "Linkedin",
+		accountSubject: ({ profile }) => profile.sub,
 		createAuthorizationURL: async ({
 			state,
 			scopes,
@@ -97,7 +98,6 @@ export const linkedin = (options: LinkedInOptions) => {
 			const userMap = await options.mapProfileToUser?.(profile);
 			return {
 				user: {
-					id: profile.sub,
 					name: profile.name,
 					email: profile.email,
 					emailVerified: profile.email_verified ?? false,

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

@@ -187,6 +187,8 @@ export const microsoft = (options: MicrosoftOptions) => {
 	return {
 		id: "microsoft",
 		name: "Microsoft EntraID",
+		accountSubject: ({ profile }) => profile.sub,
+		accountIssuer: ({ profile }) => profile.iss,
 		createAuthorizationURL(data) {
 			// Microsoft Entra supports public clients (SPA / native apps with
 			// PKCE only), so clientSecret is intentionally not required here.
@@ -319,7 +321,6 @@ export const microsoft = (options: MicrosoftOptions) => {
 						: false;
 			return {
 				user: {
-					id: user.sub,
 					name: user.name,
 					email: user.email,
 					image: user.picture,
@@ -351,7 +352,7 @@ export const microsoft = (options: MicrosoftOptions) => {
 					});
 				},
 		options,
-	} satisfies OAuthProvider;
+	} satisfies OAuthProvider<MicrosoftEntraIDProfile>;
 };
 
 export const getMicrosoftPublicKey = async (

package/src/social-providers/naver.ts

@@ -44,6 +44,7 @@ export const naver = (options: NaverOptions) => {
 	return {
 		id: "naver",
 		name: "Naver",
+		accountSubject: ({ profile }) => profile.response.id,
 		createAuthorizationURL({ state, scopes, redirectURI, additionalParams }) {
 			const _scopes = options.disableDefaultScope ? [] : ["profile", "email"];
 			if (options.scope) _scopes.push(...options.scope);
@@ -97,7 +98,6 @@ export const naver = (options: NaverOptions) => {
 			const userMap = await options.mapProfileToUser?.(profile);
 			const res = profile.response || {};
 			const user = {
-				id: res.id,
 				name: res.name || res.nickname || "",
 				email: res.email,
 				image: res.profile_image,

package/src/social-providers/notion.ts

@@ -28,6 +28,7 @@ export const notion = (options: NotionOptions) => {
 	return {
 		id: "notion",
 		name: "Notion",
+		accountSubject: ({ profile }) => profile.id,
 		createAuthorizationURL({
 			state,
 			scopes,
@@ -100,7 +101,6 @@ export const notion = (options: NotionOptions) => {
 			const userMap = await options.mapProfileToUser?.(userProfile);
 			return {
 				user: {
-					id: userProfile.id,
 					name: userProfile.name || "",
 					email: userProfile.person?.email || null,
 					image: userProfile.avatar_url,