@better-auth/core 1.7.0-beta.3 → 1.7.0-beta.5

package/src/social-providers/facebook.ts

@@ -1,12 +1,13 @@
 import { betterFetch } from "@better-fetch/fetch";
-import { createRemoteJWKSet, decodeJwt, jwtVerify } from "jose";
+import { createRemoteJWKSet, decodeJwt } from "jose";
 import { logger } from "../env";
 import { BetterAuthError } from "../error";
-import type { OAuthProvider, ProviderOptions } from "../oauth2";
+import type { ProviderOptions, UpstreamProvider } from "../oauth2";
 import {
 	createAuthorizationURL,
 	getPrimaryClientId,
 	refreshAccessToken,
+	resolveRequestedScopes,
 	validateAuthorizationCode,
 } from "../oauth2";
 export interface FacebookProfile {
@@ -24,6 +25,58 @@ export interface FacebookProfile {
 	};
 }
 
+interface FacebookDebugTokenData {
+	app_id?: string;
+	is_valid?: boolean;
+	user_id?: string;
+}
+
+/**
+ * Validate an opaque Facebook access token against the configured app.
+ *
+ * Facebook access tokens are not audience-bound at the Graph `/me` endpoint: a
+ * token minted for any Facebook app returns that app's profile. Without this
+ * check, a token issued to an unrelated app could be presented to this
+ * app's direct sign-in path and accepted as proof of identity. We call the
+ * `debug_token` endpoint and require the token to be valid, bound to one of the
+ * configured client ids, and tied to a user.
+ *
+ * @see https://developers.facebook.com/docs/facebook-login/guides/access-tokens/debugging
+ *
+ * @returns the inspected token's `user_id` when the token is valid and bound to
+ * the configured app, otherwise `null`.
+ */
+async function verifyFacebookAccessToken(
+	accessToken: string,
+	options: FacebookOptions,
+): Promise<string | null> {
+	const primaryClientId = getPrimaryClientId(options.clientId);
+	if (!primaryClientId || !options.clientSecret) {
+		return null;
+	}
+	const clientIds = Array.isArray(options.clientId)
+		? options.clientId
+		: [options.clientId];
+	const appAccessToken = `${primaryClientId}|${options.clientSecret}`;
+	const { data, error } = await betterFetch<{ data?: FacebookDebugTokenData }>(
+		"https://graph.facebook.com/debug_token",
+		{
+			query: {
+				input_token: accessToken,
+				access_token: appAccessToken,
+			},
+		},
+	);
+	if (error || !data?.data) {
+		return null;
+	}
+	const { is_valid, app_id, user_id } = data.data;
+	if (is_valid !== true || !app_id || !clientIds.includes(app_id) || !user_id) {
+		return null;
+	}
+	return user_id;
+}
+
 export interface FacebookOptions extends ProviderOptions<FacebookProfile> {
 	clientId: string | string[];
 	/**
@@ -39,35 +92,43 @@ export interface FacebookOptions extends ProviderOptions<FacebookProfile> {
 	configId?: string | undefined;
 }
 
+const FACEBOOK_DEFAULT_SCOPES = ["email", "public_profile"];
+
 export const facebook = (options: FacebookOptions) => {
 	return {
 		id: "facebook",
 		name: "Facebook",
-		async createAuthorizationURL({ state, scopes, redirectURI, loginHint }) {
+		callbackPath: "/callback/facebook",
+		async createAuthorizationURL({
+			state,
+			scopes,
+			redirectURI,
+			loginHint,
+			additionalParams,
+		}) {
 			if (!getPrimaryClientId(options.clientId) || !options.clientSecret) {
 				logger.error(
 					"Client ID and client secret are required for Facebook. Make sure to provide them in the options.",
 				);
 				throw new BetterAuthError("CLIENT_ID_AND_SECRET_REQUIRED");
 			}
-			const _scopes = options.disableDefaultScope
-				? []
-				: ["email", "public_profile"];
-			if (options.scope) _scopes.push(...options.scope);
-			if (scopes) _scopes.push(...scopes);
-			return await createAuthorizationURL({
+			const requestedScopes = resolveRequestedScopes(
+				options,
+				FACEBOOK_DEFAULT_SCOPES,
+				scopes,
+			);
+			return createAuthorizationURL({
 				id: "facebook",
 				options,
 				authorizationEndpoint: "https://www.facebook.com/v24.0/dialog/oauth",
-				scopes: _scopes,
+				scopes: requestedScopes,
 				state,
 				redirectURI,
 				loginHint,
-				additionalParams: options.configId
-					? {
-							config_id: options.configId,
-						}
-					: {},
+				additionalParams: {
+					...(options.configId ? { config_id: options.configId } : {}),
+					...(additionalParams ?? {}),
+				},
 			});
 		},
 		validateAuthorizationCode: async ({ code, redirectURI }) => {
@@ -78,46 +139,17 @@ export const facebook = (options: FacebookOptions) => {
 				tokenEndpoint: "https://graph.facebook.com/v24.0/oauth/access_token",
 			});
 		},
-		async verifyIdToken(token, nonce) {
-			if (options.disableIdTokenSignIn) {
-				return false;
-			}
-
-			if (options.verifyIdToken) {
-				return options.verifyIdToken(token, nonce);
-			}
-
-			/* limited login */
-			// check is limited token
-			if (token.split(".").length === 3) {
-				try {
-					const { payload: jwtClaims } = await jwtVerify(
-						token,
-						createRemoteJWKSet(
-							// https://developers.facebook.com/docs/facebook-login/limited-login/token/#jwks
-							new URL(
-								"https://limited.facebook.com/.well-known/oauth/openid/jwks/",
-							),
-						),
-						{
-							algorithms: ["RS256"],
-							audience: options.clientId,
-							issuer: "https://www.facebook.com",
-						},
-					);
-
-					if (nonce && jwtClaims.nonce !== nonce) {
-						return false;
-					}
-
-					return !!jwtClaims;
-				} catch {
-					return false;
-				}
-			}
-
-			/* access_token */
-			return true;
+		idToken: {
+			// https://developers.facebook.com/docs/facebook-login/limited-login/token/#jwks
+			jwks: createRemoteJWKSet(
+				new URL("https://limited.facebook.com/.well-known/oauth/openid/jwks/"),
+			),
+			issuer: "https://www.facebook.com",
+			audience: options.clientId,
+			algorithms: ["RS256"],
+			// Facebook also accepts an opaque Graph access token on the client sign-in path;
+			// identity is then resolved by getUserInfo via the Graph API, which validates it.
+			allowOpaqueToken: true,
 		},
 		refreshAccessToken: options.refreshAccessToken
 			? options.refreshAccessToken
@@ -178,6 +210,21 @@ export const facebook = (options: FacebookOptions) => {
 				};
 			}
 
+			// The profile is fetched with `accessToken`, which is the credential
+			// that actually proves identity here. It is a separate request field
+			// from the `idToken` checked by the shared id_token verifier via the
+			// declarative `idToken` config. Since an opaque token is not app-bound
+			// at `/me`, validate this exact token against the configured app
+			// before trusting the profile it returns.
+			const accessToken = token.accessToken;
+			if (!accessToken) {
+				return null;
+			}
+			const tokenUserId = await verifyFacebookAccessToken(accessToken, options);
+			if (!tokenUserId) {
+				return null;
+			}
+
 			const fields = [
 				"id",
 				"name",
@@ -190,13 +237,17 @@ export const facebook = (options: FacebookOptions) => {
 				{
 					auth: {
 						type: "Bearer",
-						token: token.accessToken,
+						token: accessToken,
 					},
 				},
 			);
 			if (error) {
 				return null;
 			}
+			// Bind the validated token to the profile it returned.
+			if (profile.id !== tokenUserId) {
+				return null;
+			}
 			const userMap = await options.mapProfileToUser?.(profile);
 			return {
 				user: {
@@ -211,5 +262,5 @@ export const facebook = (options: FacebookOptions) => {
 			};
 		},
 		options,
-	} satisfies OAuthProvider<FacebookProfile>;
+	} satisfies UpstreamProvider<FacebookProfile>;
 };

package/src/social-providers/figma.ts

@@ -1,10 +1,11 @@
 import { betterFetch } from "@better-fetch/fetch";
 import { logger } from "../env";
 import { BetterAuthError } from "../error";
-import type { OAuthProvider, ProviderOptions } from "../oauth2";
+import type { ProviderOptions, UpstreamProvider } from "../oauth2";
 import {
 	createAuthorizationURL,
 	refreshAccessToken,
+	resolveRequestedScopes,
 	validateAuthorizationCode,
 } from "../oauth2";
 
@@ -19,12 +20,21 @@ export interface FigmaOptions extends ProviderOptions<FigmaProfile> {
 	clientId: string;
 }
 
+const FIGMA_DEFAULT_SCOPES = ["current_user:read"];
+
 export const figma = (options: FigmaOptions) => {
 	const tokenEndpoint = "https://api.figma.com/v1/oauth/token";
 	return {
 		id: "figma",
 		name: "Figma",
-		async createAuthorizationURL({ state, scopes, codeVerifier, redirectURI }) {
+		callbackPath: "/callback/figma",
+		async createAuthorizationURL({
+			state,
+			scopes,
+			codeVerifier,
+			redirectURI,
+			additionalParams,
+		}) {
 			if (!options.clientId || !options.clientSecret) {
 				logger.error(
 					"Client Id and Client Secret are required for Figma. Make sure to provide them in the options.",
@@ -35,21 +45,22 @@ export const figma = (options: FigmaOptions) => {
 				throw new BetterAuthError("codeVerifier is required for Figma");
 			}
 
-			const _scopes = options.disableDefaultScope ? [] : ["current_user:read"];
-			if (options.scope) _scopes.push(...options.scope);
-			if (scopes) _scopes.push(...scopes);
+			const requestedScopes = resolveRequestedScopes(
+				options,
+				FIGMA_DEFAULT_SCOPES,
+				scopes,
+			);
 
-			const url = await createAuthorizationURL({
+			return createAuthorizationURL({
 				id: "figma",
 				options,
 				authorizationEndpoint: "https://www.figma.com/oauth",
-				scopes: _scopes,
+				scopes: requestedScopes,
 				state,
 				codeVerifier,
 				redirectURI,
+				additionalParams,
 			});
-
-			return url;
 		},
 		validateAuthorizationCode: async ({ code, codeVerifier, redirectURI }) => {
 			return validateAuthorizationCode({
@@ -114,5 +125,5 @@ export const figma = (options: FigmaOptions) => {
 			}
 		},
 		options,
-	} satisfies OAuthProvider<FigmaProfile>;
+	} satisfies UpstreamProvider<FigmaProfile>;
 };

package/src/social-providers/github.ts

@@ -1,12 +1,13 @@
 import { betterFetch } from "@better-fetch/fetch";
 import { logger } from "../env";
-import type { OAuthProvider, ProviderOptions } from "../oauth2";
+import type { ProviderOptions, UpstreamProvider } from "../oauth2";
 import {
 	createAuthorizationURL,
 	getOAuth2Tokens,
 	refreshAccessToken,
+	resolveRequestedScopes,
 } from "../oauth2";
-import { createAuthorizationCodeRequest } from "../oauth2/validate-authorization-code";
+import { authorizationCodeRequest } from "../oauth2/validate-authorization-code";
 
 export interface GithubProfile {
 	login: string;
@@ -58,37 +59,42 @@ export interface GithubProfile {
 export interface GithubOptions extends ProviderOptions<GithubProfile> {
 	clientId: string;
 }
+const GITHUB_DEFAULT_SCOPES = ["read:user", "user:email"];
+
 export const github = (options: GithubOptions) => {
 	const tokenEndpoint = "https://github.com/login/oauth/access_token";
 	return {
 		id: "github",
 		name: "GitHub",
+		callbackPath: "/callback/github",
 		createAuthorizationURL({
 			state,
 			scopes,
 			loginHint,
 			codeVerifier,
 			redirectURI,
+			additionalParams,
 		}) {
-			const _scopes = options.disableDefaultScope
-				? []
-				: ["read:user", "user:email"];
-			if (options.scope) _scopes.push(...options.scope);
-			if (scopes) _scopes.push(...scopes);
+			const requestedScopes = resolveRequestedScopes(
+				options,
+				GITHUB_DEFAULT_SCOPES,
+				scopes,
+			);
 			return createAuthorizationURL({
 				id: "github",
 				options,
 				authorizationEndpoint: "https://github.com/login/oauth/authorize",
-				scopes: _scopes,
+				scopes: requestedScopes,
 				state,
 				codeVerifier,
 				redirectURI,
 				loginHint,
 				prompt: options.prompt,
+				additionalParams,
 			});
 		},
 		validateAuthorizationCode: async ({ code, codeVerifier, redirectURI }) => {
-			const { body, headers: requestHeaders } = createAuthorizationCodeRequest({
+			const { body, headers: requestHeaders } = await authorizationCodeRequest({
 				code,
 				codeVerifier,
 				redirectURI,
@@ -180,5 +186,5 @@ export const github = (options: GithubOptions) => {
 			};
 		},
 		options,
-	} satisfies OAuthProvider<GithubProfile>;
+	} satisfies UpstreamProvider<GithubProfile>;
 };

package/src/social-providers/gitlab.ts

@@ -1,8 +1,9 @@
 import { betterFetch } from "@better-fetch/fetch";
-import type { OAuthProvider, ProviderOptions } from "../oauth2";
+import type { ProviderOptions, UpstreamProvider } from "../oauth2";
 import {
 	createAuthorizationURL,
 	refreshAccessToken,
+	resolveRequestedScopes,
 	validateAuthorizationCode,
 } from "../oauth2";
 
@@ -73,6 +74,8 @@ const issuerToEndpoints = (issuer?: string | undefined) => {
 	};
 };
 
+const GITLAB_DEFAULT_SCOPES = ["read_user"];
+
 export const gitlab = (options: GitlabOptions) => {
 	const { authorizationEndpoint, tokenEndpoint, userinfoEndpoint } =
 		issuerToEndpoints(options.issuer);
@@ -81,25 +84,30 @@ export const gitlab = (options: GitlabOptions) => {
 	return {
 		id: issuerId,
 		name: issuerName,
-		createAuthorizationURL: async ({
+		callbackPath: "/callback/gitlab",
+		createAuthorizationURL: ({
 			state,
 			scopes,
 			codeVerifier,
 			loginHint,
 			redirectURI,
+			additionalParams,
 		}) => {
-			const _scopes = options.disableDefaultScope ? [] : ["read_user"];
-			if (options.scope) _scopes.push(...options.scope);
-			if (scopes) _scopes.push(...scopes);
-			return await createAuthorizationURL({
+			const requestedScopes = resolveRequestedScopes(
+				options,
+				GITLAB_DEFAULT_SCOPES,
+				scopes,
+			);
+			return createAuthorizationURL({
 				id: issuerId,
 				options,
 				authorizationEndpoint,
-				scopes: _scopes,
+				scopes: requestedScopes,
 				state,
 				redirectURI,
 				codeVerifier,
 				loginHint,
+				additionalParams,
 			});
 		},
 		validateAuthorizationCode: async ({ code, redirectURI, codeVerifier }) => {
@@ -151,5 +159,5 @@ export const gitlab = (options: GitlabOptions) => {
 			};
 		},
 		options,
-	} satisfies OAuthProvider<GitlabProfile>;
+	} satisfies UpstreamProvider<GitlabProfile>;
 };

package/src/social-providers/google.ts

@@ -1,12 +1,13 @@
 import { betterFetch } from "@better-fetch/fetch";
-import { decodeJwt, decodeProtectedHeader, importJWK, jwtVerify } from "jose";
+import { decodeJwt, importJWK } from "jose";
 import { logger } from "../env";
 import { APIError, BetterAuthError } from "../error";
-import type { OAuthProvider, ProviderOptions } from "../oauth2";
+import type { ProviderOptions, UpstreamProvider } from "../oauth2";
 import {
 	createAuthorizationURL,
 	getPrimaryClientId,
 	refreshAccessToken,
+	resolveRequestedScopes,
 	validateAuthorizationCode,
 } from "../oauth2";
 
@@ -48,15 +49,33 @@ export interface GoogleOptions extends ProviderOptions<GoogleProfile> {
 	 */
 	display?: ("page" | "popup" | "touch" | "wap") | undefined;
 	/**
-	 * The hosted domain of the user
+	 * The hosted domain (Google Workspace) the user must belong to.
+	 *
+	 * This is sent to Google as the `hd` authorization hint and, when set, is
+	 * also enforced against the `hd` claim of the returned id token/profile.
+	 * Sign-in is rejected when the claim is missing or does not match, so this
+	 * can be used to restrict sign-in to a Workspace domain.
 	 */
 	hd?: string | undefined;
+	/**
+	 * Enable incremental authorization via Google's `include_granted_scopes`
+	 * parameter. When enabled, Google reports the user's full granted scope set
+	 * in the token response.
+	 *
+	 * @default true
+	 */
+	includeGrantedScopes?: boolean | undefined;
 }
 
+const GOOGLE_DEFAULT_SCOPES = ["email", "profile", "openid"];
+
 export const google = (options: GoogleOptions) => {
 	return {
 		id: "google",
 		name: "Google",
+		callbackPath: "/callback/google",
+		grantAuthority:
+			options.includeGrantedScopes !== false ? "full-grant" : "projection",
 		async createAuthorizationURL({
 			state,
 			scopes,
@@ -64,6 +83,7 @@ export const google = (options: GoogleOptions) => {
 			redirectURI,
 			loginHint,
 			display,
+			additionalParams,
 		}) {
 			if (!getPrimaryClientId(options.clientId) || !options.clientSecret) {
 				logger.error(
@@ -74,16 +94,16 @@ export const google = (options: GoogleOptions) => {
 			if (!codeVerifier) {
 				throw new BetterAuthError("codeVerifier is required for Google");
 			}
-			const _scopes = options.disableDefaultScope
-				? []
-				: ["email", "profile", "openid"];
-			if (options.scope) _scopes.push(...options.scope);
-			if (scopes) _scopes.push(...scopes);
-			const url = await createAuthorizationURL({
+			const requestedScopes = resolveRequestedScopes(
+				options,
+				GOOGLE_DEFAULT_SCOPES,
+				scopes,
+			);
+			return createAuthorizationURL({
 				id: "google",
 				options,
 				authorizationEndpoint: "https://accounts.google.com/o/oauth2/v2/auth",
-				scopes: _scopes,
+				scopes: requestedScopes,
 				state,
 				codeVerifier,
 				redirectURI,
@@ -92,11 +112,17 @@ export const google = (options: GoogleOptions) => {
 				display: display || options.display,
 				loginHint,
 				hd: options.hd,
-				additionalParams: {
-					include_granted_scopes: "true",
-				},
+				additionalParams:
+					options.includeGrantedScopes === false
+						? { ...(additionalParams ?? {}) }
+						: {
+								...(additionalParams ?? {}),
+								// Not caller-overridable: the emitted param must stay in
+								// lockstep with `grantAuthority` (driven by the option), or
+								// the callback would treat a non-authoritative grant as full.
+								include_granted_scopes: "true",
+							},
 			});
-			return url;
 		},
 		validateAuthorizationCode: async ({ code, codeVerifier, redirectURI }) => {
 			return validateAuthorizationCode({
@@ -120,37 +146,20 @@ export const google = (options: GoogleOptions) => {
 						tokenEndpoint: "https://oauth2.googleapis.com/token",
 					});
 				},
-		async verifyIdToken(token, nonce) {
-			if (options.disableIdTokenSignIn) {
-				return false;
-			}
-			if (options.verifyIdToken) {
-				return options.verifyIdToken(token, nonce);
-			}
-
-			// Verify JWT integrity
-			// See https://developers.google.com/identity/sign-in/web/backend-auth#verify-the-integrity-of-the-id-token
-
-			try {
-				const { kid, alg: jwtAlg } = decodeProtectedHeader(token);
-				if (!kid || !jwtAlg) return false;
-
-				const publicKey = await getGooglePublicKey(kid);
-				const { payload: jwtClaims } = await jwtVerify(token, publicKey, {
-					algorithms: [jwtAlg],
-					issuer: ["https://accounts.google.com", "accounts.google.com"],
-					audience: options.clientId,
-					maxTokenAge: "1h",
-				});
-
-				if (nonce && jwtClaims.nonce !== nonce) {
-					return false;
-				}
-
-				return true;
-			} catch {
-				return false;
-			}
+		idToken: {
+			// https://developers.google.com/identity/sign-in/web/backend-auth#verify-the-integrity-of-the-id-token
+			jwks: (header) => getGooglePublicKey(header.kid!),
+			issuer: ["https://accounts.google.com", "accounts.google.com"],
+			audience: options.clientId,
+			maxTokenAge: "1h",
+			// Google's `hd` authorization parameter is only a UI hint and can be
+			// removed or changed by the user. When a hosted domain is configured,
+			// the `hd` claim in the verified id token is the authoritative value
+			// and must match, otherwise accounts outside the workspace domain would
+			// be accepted on the id_token sign-in path.
+			verifyClaims: options.hd
+				? (claims) => claims.hd === options.hd
+				: undefined,
 		},
 		async getUserInfo(token) {
 			if (options.getUserInfo) {
@@ -160,6 +169,18 @@ export const google = (options: GoogleOptions) => {
 				return null;
 			}
 			const user = decodeJwt(token.idToken) as GoogleProfile;
+			// Enforce the configured hosted domain on the callback profile path
+			// as well. The `hd` claim must be present and match, since the
+			// authorization-time `hd` hint does not restrict which account signs
+			// in.
+			if (options.hd && user.hd !== options.hd) {
+				logger.error(
+					`Google sign-in rejected: id token hosted domain (hd) "${
+						user.hd ?? "<missing>"
+					}" does not match the configured "hd" option "${options.hd}".`,
+				);
+				return null;
+			}
 			const userMap = await options.mapProfileToUser?.(user);
 			return {
 				user: {
@@ -174,7 +195,7 @@ export const google = (options: GoogleOptions) => {
 			};
 		},
 		options,
-	} satisfies OAuthProvider<GoogleProfile>;
+	} satisfies UpstreamProvider<GoogleProfile>;
 };
 
 export const getGooglePublicKey = async (kid: string) => {

package/src/social-providers/huggingface.ts

@@ -1,8 +1,9 @@
 import { betterFetch } from "@better-fetch/fetch";
-import type { OAuthProvider, ProviderOptions } from "../oauth2";
+import type { ProviderOptions, UpstreamProvider } from "../oauth2";
 import {
 	createAuthorizationURL,
 	refreshAccessToken,
+	resolveRequestedScopes,
 	validateAuthorizationCode,
 } from "../oauth2";
 
@@ -42,25 +43,35 @@ export interface HuggingFaceOptions
 	clientId: string;
 }
 
+const HUGGINGFACE_DEFAULT_SCOPES = ["openid", "profile", "email"];
+
 export const huggingface = (options: HuggingFaceOptions) => {
 	const tokenEndpoint = "https://huggingface.co/oauth/token";
 	return {
 		id: "huggingface",
 		name: "Hugging Face",
-		createAuthorizationURL({ state, scopes, codeVerifier, redirectURI }) {
-			const _scopes = options.disableDefaultScope
-				? []
-				: ["openid", "profile", "email"];
-			if (options.scope) _scopes.push(...options.scope);
-			if (scopes) _scopes.push(...scopes);
+		callbackPath: "/callback/huggingface",
+		createAuthorizationURL({
+			state,
+			scopes,
+			codeVerifier,
+			redirectURI,
+			additionalParams,
+		}) {
+			const requestedScopes = resolveRequestedScopes(
+				options,
+				HUGGINGFACE_DEFAULT_SCOPES,
+				scopes,
+			);
 			return createAuthorizationURL({
 				id: "huggingface",
 				options,
 				authorizationEndpoint: "https://huggingface.co/oauth/authorize",
-				scopes: _scopes,
+				scopes: requestedScopes,
 				state,
 				codeVerifier,
 				redirectURI,
+				additionalParams,
 			});
 		},
 		validateAuthorizationCode: async ({ code, codeVerifier, redirectURI }) => {
@@ -115,5 +126,5 @@ export const huggingface = (options: HuggingFaceOptions) => {
 			};
 		},
 		options,
-	} satisfies OAuthProvider<HuggingFaceProfile>;
+	} satisfies UpstreamProvider<HuggingFaceProfile>;
 };