@better-auth/core 1.7.1 → 1.7.3

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,

package/src/social-providers/paypal.ts

@@ -1,10 +1,17 @@
-import { base64 } from "@better-auth/utils/base64";
 import { betterFetch } from "@better-fetch/fetch";
 import { decodeJwt } from "jose";
 import { logger } from "../env";
 import { BetterAuthError } from "../error";
-import type { OAuthProvider, ProviderOptions } from "../oauth2";
-import { createAuthorizationURL } from "../oauth2";
+import type {
+	OAuthProvider,
+	ProviderOptions,
+	TokenEndpointAuth,
+} from "../oauth2";
+import {
+	createAuthorizationURL,
+	refreshAccessToken,
+	validateAuthorizationCode,
+} from "../oauth2";
 
 export interface PayPalProfile {
 	sub?: string | undefined;
@@ -75,6 +82,13 @@ export const paypal = (options: PayPalOptions) => {
 	const userInfoEndpoint = isSandbox
 		? "https://api-m.sandbox.paypal.com/v1/identity/oauth2/userinfo"
 		: "https://api-m.paypal.com/v1/identity/oauth2/userinfo";
+	const tokenRequestOptions = {
+		clientId: options.clientId,
+		clientSecret: options.clientSecret,
+	};
+	const tokenEndpointAuth = {
+		method: "client_secret_basic",
+	} satisfies TokenEndpointAuth;
 
 	return {
 		id: "paypal",
@@ -115,47 +129,16 @@ export const paypal = (options: PayPalOptions) => {
 			return url;
 		},
 
-		validateAuthorizationCode: async ({ code, redirectURI }) => {
-			/**
-			 * PayPal requires Basic Auth for token exchange
-			 **/
-
-			const credentials = base64.encode(
-				`${options.clientId}:${options.clientSecret}`,
-			);
-
+		validateAuthorizationCode: async ({ code, codeVerifier, redirectURI }) => {
 			try {
-				const response = await betterFetch(tokenEndpoint, {
-					method: "POST",
-					headers: {
-						Authorization: `Basic ${credentials}`,
-						Accept: "application/json",
-						"Accept-Language": "en_US",
-						"Content-Type": "application/x-www-form-urlencoded",
-					},
-					body: new URLSearchParams({
-						grant_type: "authorization_code",
-						code: code,
-						redirect_uri: redirectURI,
-					}).toString(),
+				return await validateAuthorizationCode({
+					code,
+					codeVerifier,
+					redirectURI: options.redirectURI || redirectURI,
+					options: tokenRequestOptions,
+					tokenEndpoint,
+					tokenEndpointAuth,
 				});
-
-				if (!response.data) {
-					throw new BetterAuthError("FAILED_TO_GET_ACCESS_TOKEN");
-				}
-
-				const data = response.data as PayPalTokenResponse;
-
-				const result = {
-					accessToken: data.access_token,
-					refreshToken: data.refresh_token,
-					accessTokenExpiresAt: data.expires_in
-						? new Date(Date.now() + data.expires_in * 1000)
-						: undefined,
-					idToken: data.id_token,
-				};
-
-				return result;
 			} catch (error) {
 				logger.error("PayPal token exchange failed:", error);
 				throw new BetterAuthError("FAILED_TO_GET_ACCESS_TOKEN");
@@ -165,37 +148,13 @@ export const paypal = (options: PayPalOptions) => {
 		refreshAccessToken: options.refreshAccessToken
 			? options.refreshAccessToken
 			: async (refreshToken) => {
-					const credentials = base64.encode(
-						`${options.clientId}:${options.clientSecret}`,
-					);
-
 					try {
-						const response = await betterFetch(tokenEndpoint, {
-							method: "POST",
-							headers: {
-								Authorization: `Basic ${credentials}`,
-								Accept: "application/json",
-								"Accept-Language": "en_US",
-								"Content-Type": "application/x-www-form-urlencoded",
-							},
-							body: new URLSearchParams({
-								grant_type: "refresh_token",
-								refresh_token: refreshToken,
-							}).toString(),
+						return await refreshAccessToken({
+							refreshToken,
+							options: tokenRequestOptions,
+							tokenEndpoint,
+							tokenEndpointAuth,
 						});
-
-						if (!response.data) {
-							throw new BetterAuthError("FAILED_TO_REFRESH_ACCESS_TOKEN");
-						}
-
-						const data = response.data as any;
-						return {
-							accessToken: data.access_token,
-							refreshToken: data.refresh_token,
-							accessTokenExpiresAt: data.expires_in
-								? new Date(Date.now() + data.expires_in * 1000)
-								: undefined,
-						};
 					} catch (error) {
 						logger.error("PayPal token refresh failed:", error);
 						throw new BetterAuthError("FAILED_TO_REFRESH_ACCESS_TOKEN");

package/src/social-providers/reddit.ts

@@ -1,11 +1,15 @@
-import { base64 } from "@better-auth/utils/base64";
 import { betterFetch } from "@better-fetch/fetch";
-import type { OAuthProvider, ProviderOptions } from "../oauth2";
+import type {
+	OAuthProvider,
+	ProviderOptions,
+	TokenEndpointAuth,
+} from "../oauth2";
 import {
 	createAuthorizationURL,
-	getOAuth2Tokens,
 	refreshAccessToken,
+	validateAuthorizationCode,
 } from "../oauth2";
+import { createPlaceholderEmail } from "../utils/email";
 
 export interface RedditProfile {
 	id: string;
@@ -22,6 +26,15 @@ export interface RedditOptions extends ProviderOptions<RedditProfile> {
 }
 
 export const reddit = (options: RedditOptions) => {
+	const tokenEndpoint = "https://www.reddit.com/api/v1/access_token";
+	const tokenRequestOptions = {
+		clientId: options.clientId,
+		clientSecret: options.clientSecret,
+	};
+	const tokenEndpointAuth = {
+		method: "client_secret_basic",
+	} satisfies TokenEndpointAuth;
+
 	return {
 		id: "reddit",
 		name: "Reddit",
@@ -42,34 +55,17 @@ export const reddit = (options: RedditOptions) => {
 			});
 		},
 		validateAuthorizationCode: async ({ code, redirectURI }) => {
-			const body = new URLSearchParams({
-				grant_type: "authorization_code",
+			return validateAuthorizationCode({
 				code,
-				redirect_uri: options.redirectURI || redirectURI,
-			});
-			const headers = {
-				"content-type": "application/x-www-form-urlencoded",
-				accept: "text/plain",
-				"user-agent": "better-auth",
-				Authorization: `Basic ${base64.encode(
-					`${options.clientId}:${options.clientSecret}`,
-				)}`,
-			};
-
-			const { data, error } = await betterFetch<object>(
-				"https://www.reddit.com/api/v1/access_token",
-				{
-					method: "POST",
-					headers,
-					body: body.toString(),
+				redirectURI: options.redirectURI || redirectURI,
+				options: tokenRequestOptions,
+				tokenEndpoint,
+				tokenEndpointAuth,
+				headers: {
+					accept: "text/plain",
+					"user-agent": "better-auth",
 				},
-			);
-
-			if (error) {
-				throw error;
-			}
-
-			return getOAuth2Tokens(data);
+			});
 		},
 
 		refreshAccessToken: options.refreshAccessToken
@@ -77,13 +73,9 @@ export const reddit = (options: RedditOptions) => {
 			: async (refreshToken) => {
 					return refreshAccessToken({
 						refreshToken,
-						options: {
-							clientId: options.clientId,
-							clientKey: options.clientKey,
-							clientSecret: options.clientSecret,
-						},
-						authentication: "basic",
-						tokenEndpoint: "https://www.reddit.com/api/v1/access_token",
+						options: tokenRequestOptions,
+						tokenEndpoint,
+						tokenEndpointAuth,
 					});
 				},
 		async getUserInfo(token) {
@@ -110,7 +102,12 @@ export const reddit = (options: RedditOptions) => {
 			// non-routable placeholder (RFC 2606 `.invalid`) keyed to the user's
 			// Reddit id rather than the routable `reddit.com`, which could collide
 			// with a real address. Left unverified; `mapProfileToUser` can override.
-			const email = userMap?.email || `${profile.id}@reddit.invalid`;
+			const email =
+				userMap?.email ||
+				createPlaceholderEmail({
+					identifier: profile.id,
+					namespace: "reddit",
+				});
 			return {
 				user: {
 					name: profile.name,

package/src/social-providers/roblox.ts

@@ -5,6 +5,7 @@ import {
 	refreshAccessToken,
 	validateAuthorizationCode,
 } from "../oauth2";
+import { createPlaceholderEmail } from "../utils/email";
 
 export interface RobloxProfile extends Record<string, any> {
 	/** the user's id */
@@ -97,13 +98,14 @@ export const roblox = (options: RobloxOptions) => {
 			}
 
 			const userMap = await options.mapProfileToUser?.(profile);
-			// Roblox does not provide email or email_verified claim.
-			// We default to false for security consistency.
 			return {
 				user: {
 					name: profile.nickname || profile.preferred_username || "",
 					image: profile.picture,
-					email: profile.preferred_username || null, // Roblox does not provide email
+					email: createPlaceholderEmail({
+						identifier: profile.sub,
+						namespace: "roblox",
+					}),
 					emailVerified: false,
 					...userMap,
 				},