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

package/src/oauth2/refresh-access-token.ts

@@ -1,99 +1,78 @@
-import { base64 } from "@better-auth/utils/base64";
 import { betterFetch } from "@better-fetch/fetch";
 import type { AwaitableFunction } from "../types";
-import type { ClientAssertionConfig } from "./client-assertion";
-import { resolveAssertionParams } from "./client-assertion";
 import type { OAuth2Tokens, ProviderOptions } from "./oauth-provider";
+import type {
+	TokenEndpointAuth,
+	TokenEndpointSecretAuthentication,
+} from "./token-endpoint-auth";
+import { applyTokenEndpointAuth } from "./token-endpoint-auth";
+
+interface RefreshAccessTokenRequestInput {
+	refreshToken: string;
+	options: AwaitableFunction<Partial<ProviderOptions>>;
+	authentication?: TokenEndpointSecretAuthentication | undefined;
+	tokenEndpointAuth?: TokenEndpointAuth | undefined;
+	tokenEndpoint?: string | undefined;
+	extraParams?: Record<string, string> | undefined;
+	resource?: (string | string[]) | undefined;
+}
+
+interface RefreshAccessTokenRequestBaseInput {
+	refreshToken: string;
+	options: ProviderOptions;
+	extraParams?: Record<string, string> | undefined;
+	resource?: (string | string[]) | undefined;
+}
+
+interface RefreshAccessTokenInput extends RefreshAccessTokenRequestInput {
+	options: Partial<ProviderOptions>;
+	tokenEndpoint: string;
+}
 
 export async function refreshAccessTokenRequest({
 	refreshToken,
 	options,
 	authentication,
-	clientAssertion,
+	tokenEndpointAuth,
 	tokenEndpoint,
 	extraParams,
 	resource,
-}: {
-	refreshToken: string;
-	options: AwaitableFunction<Partial<ProviderOptions>>;
-	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;
-	extraParams?: Record<string, string> | undefined;
-	resource?: (string | string[]) | undefined;
-}) {
+}: RefreshAccessTokenRequestInput) {
 	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,
-		});
-		extraParams = { ...extraParams, ...assertionParams };
-	}
-
-	return createRefreshAccessTokenRequest({
+	const request = buildRefreshAccessTokenRequest({
 		refreshToken,
 		options,
-		authentication,
 		extraParams,
 		resource,
 	});
+
+	await applyTokenEndpointAuth({
+		body: request.body,
+		headers: request.headers,
+		options,
+		tokenEndpoint: tokenEndpoint ?? "",
+		grantType: "refresh_token",
+		tokenEndpointAuth,
+		authentication,
+	});
+
+	return request;
 }
 
-/**
- * @deprecated use async'd refreshAccessTokenRequest instead
- */
-export function createRefreshAccessTokenRequest({
+function buildRefreshAccessTokenRequest({
 	refreshToken,
 	options,
-	authentication,
 	extraParams,
 	resource,
-}: {
-	refreshToken: string;
-	options: ProviderOptions;
-	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
-	extraParams?: Record<string, string> | undefined;
-	resource?: (string | string[]) | undefined;
-}) {
+}: RefreshAccessTokenRequestBaseInput) {
 	const body = new URLSearchParams();
-	const headers: Record<string, any> = {
+	const headers: Record<string, string> = {
 		"content-type": "application/x-www-form-urlencoded",
 		accept: "application/json",
 	};
 
 	body.set("grant_type", "refresh_token");
 	body.set("refresh_token", refreshToken);
-	const primaryClientId = Array.isArray(options.clientId)
-		? options.clientId[0]
-		: options.clientId;
-	if (authentication === "basic") {
-		if (primaryClientId) {
-			headers["authorization"] =
-				"Basic " +
-				base64.encode(`${primaryClientId}:${options.clientSecret ?? ""}`);
-		} else {
-			headers["authorization"] =
-				"Basic " + base64.encode(`:${options.clientSecret ?? ""}`);
-		}
-	} else {
-		body.set("client_id", primaryClientId);
-		if (authentication !== "private_key_jwt" && options.clientSecret) {
-			body.set("client_secret", options.clientSecret);
-		}
-	}
-
 	if (resource) {
 		if (typeof resource === "string") {
 			body.append("resource", resource);
@@ -120,23 +99,18 @@ export async function refreshAccessToken({
 	options,
 	tokenEndpoint,
 	authentication,
-	clientAssertion,
+	tokenEndpointAuth,
 	extraParams,
-}: {
-	refreshToken: string;
-	options: Partial<ProviderOptions>;
-	tokenEndpoint: string;
-	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
-	clientAssertion?: ClientAssertionConfig | undefined;
-	extraParams?: Record<string, string> | undefined;
-}): Promise<OAuth2Tokens> {
+	resource,
+}: RefreshAccessTokenInput): Promise<OAuth2Tokens> {
 	const { body, headers } = await refreshAccessTokenRequest({
 		refreshToken,
 		options,
 		authentication,
-		clientAssertion,
+		tokenEndpointAuth,
 		tokenEndpoint,
 		extraParams,
+		resource,
 	});
 
 	const { data, error } = await betterFetch<{

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;