@better-auth/core 1.7.0-beta.2 → 1.7.0-beta.4

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

@@ -0,0 +1,221 @@
+import { encodeBasicCredentials } from "./basic-credentials";
+import type {
+	ClientAssertionGetter,
+	ClientAssertionGrantType,
+} from "./client-assertion";
+import { resolveClientAssertionParams } from "./client-assertion";
+import { getPrimaryClientId } from "./utils";
+
+export type TokenEndpointAuth =
+	| {
+			method: "none";
+	  }
+	| {
+			method: "client_secret_basic";
+	  }
+	| {
+			method: "client_secret_post";
+	  }
+	| {
+			method: "private_key_jwt";
+			getClientAssertion: ClientAssertionGetter;
+	  };
+
+export type TokenEndpointAuthMethod = TokenEndpointAuth["method"];
+
+export type TokenEndpointSecretAuthentication = "basic" | "post";
+
+export interface TokenEndpointClientOptions {
+	clientId?: string | string[] | undefined;
+	clientSecret?: string | undefined;
+}
+
+export interface ApplyTokenEndpointAuthInput {
+	body: URLSearchParams;
+	headers: Record<string, string>;
+	options: TokenEndpointClientOptions;
+	tokenEndpoint: string;
+	grantType: ClientAssertionGrantType;
+	tokenEndpointAuth?: TokenEndpointAuth | undefined;
+	authentication?: TokenEndpointSecretAuthentication | undefined;
+}
+
+function getDefaultTokenEndpointAuth(
+	options: TokenEndpointClientOptions,
+	authentication?: TokenEndpointSecretAuthentication,
+): TokenEndpointAuth {
+	if (authentication === "basic") {
+		return { method: "client_secret_basic" };
+	}
+	if (options.clientSecret) {
+		return { method: "client_secret_post" };
+	}
+	return { method: "none" };
+}
+
+function assertNoClientSecret(
+	method: "none" | "private_key_jwt",
+	options: TokenEndpointClientOptions,
+	body: URLSearchParams,
+) {
+	if (options.clientSecret || body.has("client_secret")) {
+		throw new Error(
+			`${method} token endpoint authentication cannot be combined with clientSecret`,
+		);
+	}
+}
+
+function setClientId(body: URLSearchParams, clientId: string | undefined) {
+	if (clientId) {
+		body.set("client_id", clientId);
+	}
+}
+
+function assertClientSecretConfigured(
+	method: "client_secret_basic" | "client_secret_post",
+	options: TokenEndpointClientOptions,
+): asserts options is TokenEndpointClientOptions & { clientSecret: string } {
+	if (!options.clientSecret) {
+		throw new Error(
+			`${method} token endpoint authentication requires clientSecret`,
+		);
+	}
+}
+
+function assertClientIdConfigured(
+	method: TokenEndpointAuthMethod,
+	clientId: string | undefined,
+): asserts clientId is string {
+	if (!clientId) {
+		throw new Error(
+			`${method} token endpoint authentication requires clientId`,
+		);
+	}
+}
+
+function setClientSecretPostAuth({
+	body,
+	options,
+	clientId,
+	requireClientSecret,
+}: {
+	body: URLSearchParams;
+	options: TokenEndpointClientOptions;
+	clientId: string | undefined;
+	requireClientSecret?: boolean | undefined;
+}) {
+	if (requireClientSecret) {
+		assertClientSecretConfigured("client_secret_post", options);
+	}
+	if (options.clientSecret) {
+		assertClientIdConfigured("client_secret_post", clientId);
+		setClientId(body, clientId);
+		body.set("client_secret", options.clientSecret);
+	}
+}
+
+function setClientSecretBasicAuth({
+	headers,
+	options,
+	clientId,
+	body,
+}: {
+	headers: Record<string, string>;
+	options: TokenEndpointClientOptions;
+	clientId: string | undefined;
+	body: URLSearchParams;
+}) {
+	if (body.has("client_secret")) {
+		throw new Error(
+			"client_secret_basic token endpoint authentication cannot be combined with client_secret body parameters",
+		);
+	}
+	assertClientSecretConfigured("client_secret_basic", options);
+	assertClientIdConfigured("client_secret_basic", clientId);
+	headers.authorization = encodeBasicCredentials(
+		clientId,
+		options.clientSecret,
+	);
+}
+
+function assertCompleteManualClientAssertion(body: URLSearchParams) {
+	if (body.has("client_assertion") !== body.has("client_assertion_type")) {
+		throw new Error(
+			"client_assertion and client_assertion_type must both be provided",
+		);
+	}
+}
+
+export async function applyTokenEndpointAuth({
+	body,
+	headers,
+	options,
+	tokenEndpoint,
+	grantType,
+	tokenEndpointAuth,
+	authentication,
+}: ApplyTokenEndpointAuthInput) {
+	assertCompleteManualClientAssertion(body);
+
+	const clientId = getPrimaryClientId(options.clientId);
+	if (body.has("client_assertion")) {
+		if (tokenEndpointAuth) {
+			throw new Error(
+				"client_assertion body parameters cannot be combined with tokenEndpointAuth",
+			);
+		}
+		assertNoClientSecret("private_key_jwt", options, body);
+		setClientId(body, clientId);
+		return;
+	}
+
+	const auth =
+		tokenEndpointAuth ?? getDefaultTokenEndpointAuth(options, authentication);
+
+	if (auth.method === "private_key_jwt") {
+		assertNoClientSecret(auth.method, options, body);
+		assertClientIdConfigured(auth.method, clientId);
+		if (!tokenEndpoint) {
+			throw new Error(
+				"private_key_jwt token endpoint authentication requires tokenEndpoint",
+			);
+		}
+		const assertionParams = await resolveClientAssertionParams({
+			getClientAssertion: auth.getClientAssertion,
+			context: {
+				clientId,
+				tokenEndpoint,
+				grantType,
+			},
+		});
+		setClientId(body, clientId);
+		for (const [key, value] of Object.entries(assertionParams)) {
+			body.set(key, value);
+		}
+		return;
+	}
+
+	if (auth.method === "none") {
+		assertNoClientSecret(auth.method, options, body);
+		if (grantType === "client_credentials") {
+			throw new Error(
+				"none token endpoint authentication cannot be used with client_credentials grant",
+			);
+		}
+		assertClientIdConfigured(auth.method, clientId);
+		setClientId(body, clientId);
+		return;
+	}
+
+	if (auth.method === "client_secret_basic") {
+		setClientSecretBasicAuth({ headers, options, clientId, body });
+		return;
+	}
+
+	setClientSecretPostAuth({
+		body,
+		options,
+		clientId,
+		requireClientSecret: tokenEndpointAuth?.method === "client_secret_post",
+	});
+}

package/src/oauth2/utils.ts

@@ -28,6 +28,25 @@ export function getOAuth2Tokens(data: Record<string, any>): OAuth2Tokens {
 	};
 }
 
+/**
+ * Fill in `accessTokenExpiresAt` from the provider's configured
+ * `accessTokenExpiresIn` when the token response omitted `expires_in`. Without a
+ * known expiry, `getAccessToken` cannot tell the token is expired and never
+ * refreshes it. No-op when the provider already supplied an expiry or no
+ * fallback is configured.
+ */
+export function applyDefaultAccessTokenExpiry(
+	tokens: OAuth2Tokens,
+	accessTokenExpiresIn: number | undefined,
+): OAuth2Tokens {
+	if (!tokens.accessTokenExpiresAt && accessTokenExpiresIn) {
+		tokens.accessTokenExpiresAt = new Date(
+			Date.now() + accessTokenExpiresIn * 1000,
+		);
+	}
+	return tokens;
+}
+
 /**
  * Return the provider's primary Client ID: the single string, or the entry at
  * array index 0 for the cross-platform form used by ID token audience

package/src/oauth2/validate-authorization-code.ts

@@ -1,11 +1,42 @@
-import { base64 } from "@better-auth/utils/base64";
 import { betterFetch } from "@better-fetch/fetch";
 import { createRemoteJWKSet, jwtVerify } from "jose";
 import type { AwaitableFunction } from "../types";
-import type { ClientAssertionConfig } from "./client-assertion";
-import { resolveAssertionParams } from "./client-assertion";
 import type { ProviderOptions } from "./index";
 import { getOAuth2Tokens } from "./index";
+import type {
+	TokenEndpointAuth,
+	TokenEndpointSecretAuthentication,
+} from "./token-endpoint-auth";
+import { applyTokenEndpointAuth } from "./token-endpoint-auth";
+
+interface AuthorizationCodeRequestInput {
+	code: string;
+	redirectURI: string;
+	options: AwaitableFunction<Partial<ProviderOptions>>;
+	codeVerifier?: string | undefined;
+	deviceId?: string | undefined;
+	authentication?: TokenEndpointSecretAuthentication | undefined;
+	tokenEndpointAuth?: TokenEndpointAuth | undefined;
+	tokenEndpoint?: string | undefined;
+	headers?: Record<string, string> | undefined;
+	additionalParams?: Record<string, string> | undefined;
+	resource?: (string | string[]) | undefined;
+}
+
+interface AuthorizationCodeRequestBaseInput {
+	code: string;
+	redirectURI: string;
+	options: Partial<ProviderOptions>;
+	codeVerifier?: string | undefined;
+	deviceId?: string | undefined;
+	headers?: Record<string, string> | undefined;
+	additionalParams?: Record<string, string> | undefined;
+	resource?: (string | string[]) | undefined;
+}
+
+interface ValidateAuthorizationCodeInput extends AuthorizationCodeRequestInput {
+	tokenEndpoint: string;
+}
 
 export async function authorizationCodeRequest({
 	code,
@@ -13,84 +44,50 @@ export async function authorizationCodeRequest({
 	redirectURI,
 	options,
 	authentication,
-	clientAssertion,
+	tokenEndpointAuth,
 	tokenEndpoint,
 	deviceId,
 	headers,
 	additionalParams = {},
 	resource,
-}: {
-	code: string;
-	redirectURI: string;
-	options: AwaitableFunction<Partial<ProviderOptions>>;
-	codeVerifier?: string | undefined;
-	deviceId?: string | undefined;
-	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
-	clientAssertion?: ClientAssertionConfig | undefined;
-	/** Token endpoint URL. Used as the JWT `aud` claim when signing assertions. */
-	tokenEndpoint?: string | undefined;
-	headers?: Record<string, string> | undefined;
-	additionalParams?: Record<string, string> | undefined;
-	resource?: (string | string[]) | undefined;
-}) {
+}: AuthorizationCodeRequestInput) {
 	options = typeof options === "function" ? await options() : options;
-
-	if (authentication === "private_key_jwt") {
-		if (!clientAssertion) {
-			throw new Error(
-				"private_key_jwt authentication requires a clientAssertion configuration",
-			);
-		}
-		const primaryClientId = Array.isArray(options.clientId)
-			? options.clientId[0]
-			: options.clientId;
-		const assertionParams = await resolveAssertionParams({
-			clientAssertion,
-			clientId: primaryClientId,
-			tokenEndpoint,
-		});
-		additionalParams = { ...additionalParams, ...assertionParams };
-	}
-
-	return createAuthorizationCodeRequest({
+	const request = buildAuthorizationCodeRequest({
 		code,
 		codeVerifier,
 		redirectURI,
 		options,
-		authentication,
 		deviceId,
 		headers,
 		additionalParams,
 		resource,
 	});
+
+	await applyTokenEndpointAuth({
+		body: request.body,
+		headers: request.headers,
+		options,
+		tokenEndpoint: tokenEndpoint ?? "",
+		grantType: "authorization_code",
+		tokenEndpointAuth,
+		authentication,
+	});
+
+	return request;
 }
 
-/**
- * @deprecated use async'd authorizationCodeRequest instead
- */
-export function createAuthorizationCodeRequest({
+function buildAuthorizationCodeRequest({
 	code,
 	codeVerifier,
 	redirectURI,
 	options,
-	authentication,
 	deviceId,
 	headers,
 	additionalParams = {},
 	resource,
-}: {
-	code: string;
-	redirectURI: string;
-	options: Partial<ProviderOptions>;
-	codeVerifier?: string | undefined;
-	deviceId?: string | undefined;
-	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
-	headers?: Record<string, string> | undefined;
-	additionalParams?: Record<string, string> | undefined;
-	resource?: (string | string[]) | undefined;
-}) {
+}: AuthorizationCodeRequestBaseInput) {
 	const body = new URLSearchParams();
-	const requestHeaders: Record<string, any> = {
+	const requestHeaders: Record<string, string> = {
 		"content-type": "application/x-www-form-urlencoded",
 		accept: "application/json",
 		...headers,
@@ -111,21 +108,6 @@ export function createAuthorizationCodeRequest({
 			}
 		}
 	}
-	const primaryClientId = Array.isArray(options.clientId)
-		? options.clientId[0]
-		: options.clientId;
-	if (authentication === "basic") {
-		const encodedCredentials = base64.encode(
-			`${primaryClientId}:${options.clientSecret ?? ""}`,
-		);
-		requestHeaders["authorization"] = `Basic ${encodedCredentials}`;
-	} else {
-		body.set("client_id", primaryClientId);
-		if (authentication !== "private_key_jwt" && options.clientSecret) {
-			body.set("client_secret", options.clientSecret);
-		}
-	}
-
 	for (const [key, value] of Object.entries(additionalParams)) {
 		if (!body.has(key)) body.append(key, value);
 	}
@@ -143,31 +125,19 @@ export async function validateAuthorizationCode({
 	options,
 	tokenEndpoint,
 	authentication,
-	clientAssertion,
+	tokenEndpointAuth,
 	deviceId,
 	headers,
 	additionalParams = {},
 	resource,
-}: {
-	code: string;
-	redirectURI: string;
-	options: AwaitableFunction<Partial<ProviderOptions>>;
-	codeVerifier?: string | undefined;
-	deviceId?: string | undefined;
-	tokenEndpoint: string;
-	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
-	clientAssertion?: ClientAssertionConfig | undefined;
-	headers?: Record<string, string> | undefined;
-	additionalParams?: Record<string, string> | undefined;
-	resource?: (string | string[]) | undefined;
-}) {
+}: ValidateAuthorizationCodeInput) {
 	const { body, headers: requestHeaders } = await authorizationCodeRequest({
 		code,
 		codeVerifier,
 		redirectURI,
 		options,
 		authentication,
-		clientAssertion,
+		tokenEndpointAuth,
 		tokenEndpoint,
 		deviceId,
 		headers,

package/src/oauth2/verify.ts

@@ -9,11 +9,22 @@ import type {
 import {
 	createLocalJWKSet,
 	decodeProtectedHeader,
+	errors as joseErrors,
 	jwtVerify,
 	UnsecuredJWT,
 } from "jose";
 import { logger } from "../env";
 
+const joseInfrastructureErrorCodes = new Set([
+	joseErrors.JWKSTimeout.code,
+	joseErrors.JWKSInvalid.code,
+	joseErrors.JWKSMultipleMatchingKeys.code,
+]);
+
+function isJoseInfrastructureError(error: joseErrors.JOSEError) {
+	return joseInfrastructureErrorCodes.has(error.code);
+}
+
 /** Last fetched jwks used locally in getJwks @internal */
 let jwks: JSONWebKeySet | undefined;
 
@@ -82,7 +93,9 @@ export async function getJwks(
 		throw new Error(error as unknown as string);
 	}
 
-	if (!jwtHeaders.kid) throw new Error("Missing jwt kid");
+	if (!jwtHeaders.kid) {
+		throw new APIError("UNAUTHORIZED", { message: "invalid access token" });
+	}
 
 	// Fetch jwks if not set or has a different kid than the one stored
 	if (!jwks || !jwks.keys.find((jwk) => jwk.kid === jwtHeaders.kid)) {
@@ -137,13 +150,16 @@ export async function verifyAccessToken(
 			if (error instanceof Error) {
 				if (error.name === "TypeError" || error.name === "JWSInvalid") {
 					// likely an opaque token (continue)
-				} else if (error.name === "JWTExpired") {
+				} else if (error instanceof joseErrors.JWTExpired) {
 					throw new APIError("UNAUTHORIZED", {
 						message: "token expired",
 					});
-				} else if (error.name === "JWTInvalid") {
+				} else if (error instanceof joseErrors.JOSEError) {
+					if (isJoseInfrastructureError(error)) {
+						throw error;
+					}
 					throw new APIError("UNAUTHORIZED", {
-						message: "token invalid",
+						message: "invalid access token",
 					});
 				} else {
 					throw error;

package/src/social-providers/apple.ts

@@ -22,7 +22,7 @@ export interface AppleProfile {
 	 * The email address is either the user's real email address or the proxy
 	 * address, depending on their status private email relay service.
 	 */
-	email: string;
+	email?: string;
 	/**
 	 * A string or Boolean value that indicates whether the service verifies
 	 * the email. The value can either be a string ("true" or "false") or a
@@ -77,12 +77,35 @@ export interface AppleOptions extends ProviderOptions<AppleProfile> {
 	audience?: (string | string[]) | undefined;
 }
 
+async function sha256Hex(value: string) {
+	const data = new TextEncoder().encode(value);
+	const digest = await crypto.subtle.digest("SHA-256", data);
+	return Array.from(new Uint8Array(digest))
+		.map((byte) => byte.toString(16).padStart(2, "0"))
+		.join("");
+}
+
+async function nonceMatches(jwtNonce: unknown, nonce: string) {
+	if (typeof jwtNonce !== "string") {
+		return false;
+	}
+	if (jwtNonce === nonce) {
+		return true;
+	}
+	return jwtNonce === (await sha256Hex(nonce));
+}
+
 export const apple = (options: AppleOptions) => {
 	const tokenEndpoint = "https://appleid.apple.com/auth/token";
 	return {
 		id: "apple",
 		name: "Apple",
-		async createAuthorizationURL({ state, scopes, redirectURI }) {
+		async createAuthorizationURL({
+			state,
+			scopes,
+			redirectURI,
+			additionalParams,
+		}) {
 			if (!getPrimaryClientId(options.clientId) || !options.clientSecret) {
 				logger.error(
 					"Client ID and client secret are required for Apple. Make sure to provide them in the options.",
@@ -101,6 +124,7 @@ export const apple = (options: AppleOptions) => {
 				redirectURI,
 				responseMode: "form_post",
 				responseType: "code id_token",
+				additionalParams,
 			});
 			return url;
 		},
@@ -141,7 +165,7 @@ export const apple = (options: AppleOptions) => {
 						jwtClaims[field] = Boolean(jwtClaims[field]);
 					}
 				});
-				if (nonce && jwtClaims.nonce !== nonce) {
+				if (nonce && !(await nonceMatches(jwtClaims.nonce, nonce))) {
 					return false;
 				}
 				return !!jwtClaims;

package/src/social-providers/atlassian.ts

@@ -35,7 +35,13 @@ export const atlassian = (options: AtlassianOptions) => {
 		id: "atlassian",
 		name: "Atlassian",
 
-		async createAuthorizationURL({ state, scopes, codeVerifier, redirectURI }) {
+		async createAuthorizationURL({
+			state,
+			scopes,
+			codeVerifier,
+			redirectURI,
+			additionalParams,
+		}) {
 			if (!options.clientId || !options.clientSecret) {
 				logger.error("Client Id and Secret are required for Atlassian");
 				throw new BetterAuthError("CLIENT_ID_AND_SECRET_REQUIRED");
@@ -59,6 +65,7 @@ export const atlassian = (options: AtlassianOptions) => {
 				codeVerifier,
 				redirectURI,
 				additionalParams: {
+					...(additionalParams ?? {}),
 					audience: "api.atlassian.com",
 				},
 				prompt: options.prompt,

package/src/social-providers/cognito.ts

@@ -42,6 +42,19 @@ export interface CognitoOptions extends ProviderOptions<CognitoProfile> {
 	region: string;
 	userPoolId: string;
 	requireClientSecret?: boolean | undefined;
+	/**
+	 * Skip the Cognito hosted-UI identity-provider picker by preselecting an
+	 * IdP (maps to the `identity_provider` query parameter on the authorize
+	 * request). Accepts `"COGNITO"`, a SAML/OIDC provider name configured on
+	 * the User Pool, or one of the social providers (`"Google"`, `"Facebook"`,
+	 * `"LoginWithAmazon"`, `"SignInWithApple"`).
+	 *
+	 * Per-request overrides via `signIn.social({ additionalParams: { identity_provider } })`
+	 * take precedence over this value.
+	 *
+	 * @see https://docs.aws.amazon.com/cognito/latest/developerguide/authorization-endpoint.html
+	 */
+	identityProvider?: string | undefined;
 }
 
 export const cognito = (options: CognitoOptions) => {
@@ -60,7 +73,13 @@ export const cognito = (options: CognitoOptions) => {
 	return {
 		id: "cognito",
 		name: "Cognito",
-		async createAuthorizationURL({ state, scopes, codeVerifier, redirectURI }) {
+		async createAuthorizationURL({
+			state,
+			scopes,
+			codeVerifier,
+			redirectURI,
+			additionalParams,
+		}) {
 			if (!getPrimaryClientId(options.clientId)) {
 				logger.error(
 					"ClientId is required for Amazon Cognito. Make sure to provide them in the options.",
@@ -91,6 +110,12 @@ export const cognito = (options: CognitoOptions) => {
 				codeVerifier,
 				redirectURI,
 				prompt: options.prompt,
+				additionalParams: {
+					...(options.identityProvider
+						? { identity_provider: options.identityProvider }
+						: {}),
+					...(additionalParams ?? {}),
+				},
 			});
 			// AWS Cognito requires scopes to be encoded with %20 instead of +
 			// URLSearchParams encodes spaces as + by default, so we need to fix this

package/src/social-providers/discord.ts

@@ -1,6 +1,10 @@
 import { betterFetch } from "@better-fetch/fetch";
 import type { OAuthProvider, ProviderOptions } from "../oauth2";
-import { refreshAccessToken, validateAuthorizationCode } from "../oauth2";
+import {
+	createAuthorizationURL,
+	refreshAccessToken,
+	validateAuthorizationCode,
+} from "../oauth2";
 export interface DiscordProfile extends Record<string, any> {
 	/** the user's id (i.e. the numerical snowflake) */
 	id: string;
@@ -41,7 +45,7 @@ export interface DiscordProfile extends Record<string, any> {
 	/** whether the email on this account has been verified */
 	verified: boolean;
 	/** the user's email */
-	email: string;
+	email?: string | null;
 	/**
 	 * the flags on a user's account:
 	 * https://discord.com/developers/docs/resources/user#user-object-user-flags
@@ -84,26 +88,26 @@ export const discord = (options: DiscordOptions) => {
 	return {
 		id: "discord",
 		name: "Discord",
-		createAuthorizationURL({ state, scopes, redirectURI }) {
+		createAuthorizationURL({ state, scopes, redirectURI, additionalParams }) {
 			const _scopes = options.disableDefaultScope ? [] : ["identify", "email"];
 			if (scopes) _scopes.push(...scopes);
 			if (options.scope) _scopes.push(...options.scope);
 			const hasBotScope = _scopes.includes("bot");
-			const permissionsParam =
-				hasBotScope && options.permissions !== undefined
-					? `&permissions=${options.permissions}`
-					: "";
-			return new URL(
-				`https://discord.com/api/oauth2/authorize?scope=${_scopes.join(
-					"+",
-				)}&response_type=code&client_id=${
-					options.clientId
-				}&redirect_uri=${encodeURIComponent(
-					options.redirectURI || redirectURI,
-				)}&state=${state}&prompt=${
-					options.prompt || "none"
-				}${permissionsParam}`,
-			);
+			return createAuthorizationURL({
+				id: "discord",
+				options,
+				authorizationEndpoint: "https://discord.com/api/oauth2/authorize",
+				scopes: _scopes,
+				state,
+				redirectURI,
+				prompt: options.prompt || "none",
+				additionalParams: {
+					...(hasBotScope && options.permissions !== undefined
+						? { permissions: String(options.permissions) }
+						: {}),
+					...(additionalParams ?? {}),
+				},
+			});
 		},
 		validateAuthorizationCode: async ({ code, redirectURI }) => {
 			return validateAuthorizationCode({