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

package/src/oauth2/client-credentials-token.ts

@@ -1,72 +1,70 @@
-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 ClientCredentialsTokenRequestInput {
+	options: AwaitableFunction<ProviderOptions>;
+	scope?: string | undefined;
+	authentication?: TokenEndpointSecretAuthentication | undefined;
+	tokenEndpointAuth?: TokenEndpointAuth | undefined;
+	tokenEndpoint?: string | undefined;
+	resource?: (string | string[]) | undefined;
+}
+
+interface ClientCredentialsTokenRequestBaseInput {
+	options: ProviderOptions;
+	scope?: string | undefined;
+	resource?: (string | string[]) | undefined;
+	extraParams?: Record<string, string> | undefined;
+}
+
+interface ClientCredentialsTokenInput
+	extends ClientCredentialsTokenRequestInput {
+	tokenEndpoint: string;
+	scope: string;
+}
 
 export async function clientCredentialsTokenRequest({
 	options,
 	scope,
 	authentication,
-	clientAssertion,
+	tokenEndpointAuth,
 	tokenEndpoint,
 	resource,
-}: {
-	options: AwaitableFunction<ProviderOptions>;
-	scope?: 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;
-	resource?: (string | string[]) | undefined;
-}) {
+}: ClientCredentialsTokenRequestInput) {
 	options = typeof options === "function" ? await options() : options;
-
-	let extraParams: Record<string, string> | undefined;
-	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;
-		extraParams = await resolveAssertionParams({
-			clientAssertion,
-			clientId: primaryClientId,
-			tokenEndpoint,
-		});
-	}
-
-	return createClientCredentialsTokenRequest({
+	const request = buildClientCredentialsTokenRequest({
 		options,
 		scope,
-		authentication,
 		resource,
-		extraParams,
 	});
+
+	await applyTokenEndpointAuth({
+		body: request.body,
+		headers: request.headers,
+		options,
+		tokenEndpoint: tokenEndpoint ?? "",
+		grantType: "client_credentials",
+		tokenEndpointAuth,
+		authentication,
+	});
+
+	return request;
 }
 
-/**
- * @deprecated use async'd clientCredentialsTokenRequest instead
- */
-export function createClientCredentialsTokenRequest({
+function buildClientCredentialsTokenRequest({
 	options,
 	scope,
-	authentication,
 	resource,
 	extraParams,
-}: {
-	options: ProviderOptions;
-	scope?: string | undefined;
-	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
-	resource?: (string | string[]) | undefined;
-	extraParams?: Record<string, string> | undefined;
-}) {
+}: ClientCredentialsTokenRequestBaseInput) {
 	const body = new URLSearchParams();
-	const headers: Record<string, any> = {
+	const headers: Record<string, string> = {
 		"content-type": "application/x-www-form-urlencoded",
 		accept: "application/json",
 	};
@@ -82,21 +80,6 @@ export function createClientCredentialsTokenRequest({
 			}
 		}
 	}
-	const primaryClientId = Array.isArray(options.clientId)
-		? options.clientId[0]
-		: options.clientId;
-	if (authentication === "basic") {
-		const encodedCredentials = base64.encode(
-			`${primaryClientId}:${options.clientSecret ?? ""}`,
-		);
-		headers["authorization"] = `Basic ${encodedCredentials}`;
-	} else {
-		body.set("client_id", primaryClientId);
-		if (authentication !== "private_key_jwt" && options.clientSecret) {
-			body.set("client_secret", options.clientSecret);
-		}
-	}
-
 	if (extraParams) {
 		for (const [key, value] of Object.entries(extraParams)) {
 			if (!body.has(key)) body.append(key, value);
@@ -114,21 +97,14 @@ export async function clientCredentialsToken({
 	tokenEndpoint,
 	scope,
 	authentication,
-	clientAssertion,
+	tokenEndpointAuth,
 	resource,
-}: {
-	options: AwaitableFunction<ProviderOptions>;
-	tokenEndpoint: string;
-	scope: string;
-	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
-	clientAssertion?: ClientAssertionConfig | undefined;
-	resource?: (string | string[]) | undefined;
-}): Promise<OAuth2Tokens> {
+}: ClientCredentialsTokenInput): Promise<OAuth2Tokens> {
 	const { body, headers } = await clientCredentialsTokenRequest({
 		options,
 		scope,
 		authentication,
-		clientAssertion,
+		tokenEndpointAuth,
 		tokenEndpoint,
 		resource,
 	});

package/src/oauth2/create-authorization-url.ts

@@ -1,6 +1,26 @@
 import type { AwaitableFunction } from "../types";
 import type { ProviderOptions } from "./index";
-import { generateCodeChallenge } from "./utils";
+import { generateCodeChallenge, getPrimaryClientId } from "./utils";
+
+/**
+ * Query-parameter names that are populated by the framework as part of the
+ * authorization request and must not be overridden by caller-supplied
+ * `additionalParams`. Overriding `state`, PKCE, or `redirect_uri` would
+ * break the callback correlation and session pinning guarantees.
+ */
+export const RESERVED_AUTHORIZATION_PARAMS = [
+	"state",
+	"client_id",
+	"redirect_uri",
+	"response_type",
+	"code_challenge",
+	"code_challenge_method",
+	"scope",
+] as const;
+
+export const RESERVED_AUTHORIZATION_PARAMS_SET: ReadonlySet<string> = new Set(
+	RESERVED_AUTHORIZATION_PARAMS,
+);
 
 export async function createAuthorizationURL({
 	id,
@@ -44,9 +64,10 @@ export async function createAuthorizationURL({
 	options = typeof options === "function" ? await options() : options;
 	const url = new URL(options.authorizationEndpoint || authorizationEndpoint);
 	url.searchParams.set("response_type", responseType || "code");
-	const primaryClientId = Array.isArray(options.clientId)
-		? options.clientId[0]
-		: options.clientId;
+	const primaryClientId = getPrimaryClientId(options.clientId);
+	if (!primaryClientId) {
+		throw new Error("OAuth provider requires clientId");
+	}
 	url.searchParams.set("client_id", primaryClientId);
 	url.searchParams.set("state", state);
 	if (scopes) {
@@ -81,9 +102,10 @@ export async function createAuthorizationURL({
 		);
 	}
 	if (additionalParams) {
-		Object.entries(additionalParams).forEach(([key, value]) => {
+		for (const [key, value] of Object.entries(additionalParams)) {
+			if (RESERVED_AUTHORIZATION_PARAMS_SET.has(key)) continue;
 			url.searchParams.set(key, value);
-		});
+		}
 	}
 	return url;
 }

package/src/oauth2/index.ts

@@ -1,19 +1,31 @@
+export { additionalAuthorizationParamsSchema } from "./authorization-params";
+export {
+	decodeBasicCredentials,
+	encodeBasicCredentials,
+} from "./basic-credentials";
 export type {
-	AssertionSigningAlgorithm,
-	ClientAssertionConfig,
+	ClientAssertionContext,
+	ClientAssertionGetter,
+	ClientAssertionGrantType,
+	PrivateKeyJwtClientAssertionGetterOptions,
+	PrivateKeyJwtSigningAlgorithm,
 } from "./client-assertion";
 export {
-	ASSERTION_SIGNING_ALGORITHMS,
 	CLIENT_ASSERTION_TYPE,
-	resolveAssertionParams,
-	signClientAssertion,
+	createPrivateKeyJwtClientAssertionGetter,
+	PRIVATE_KEY_JWT_SIGNING_ALGORITHMS,
+	resolveClientAssertionParams,
+	signPrivateKeyJwtClientAssertion,
 } from "./client-assertion";
 export {
 	clientCredentialsToken,
 	clientCredentialsTokenRequest,
-	createClientCredentialsTokenRequest,
 } from "./client-credentials-token";
-export { createAuthorizationURL } from "./create-authorization-url";
+export {
+	createAuthorizationURL,
+	RESERVED_AUTHORIZATION_PARAMS,
+	RESERVED_AUTHORIZATION_PARAMS_SET,
+} from "./create-authorization-url";
 export type {
 	OAuth2Tokens,
 	OAuth2UserInfo,
@@ -21,18 +33,22 @@ export type {
 	ProviderOptions,
 } from "./oauth-provider";
 export {
-	createRefreshAccessTokenRequest,
 	refreshAccessToken,
 	refreshAccessTokenRequest,
 } from "./refresh-access-token";
+export type {
+	TokenEndpointAuth,
+	TokenEndpointAuthMethod,
+	TokenEndpointSecretAuthentication,
+} from "./token-endpoint-auth";
 export {
+	applyDefaultAccessTokenExpiry,
 	generateCodeChallenge,
 	getOAuth2Tokens,
 	getPrimaryClientId,
 } from "./utils";
 export {
 	authorizationCodeRequest,
-	createAuthorizationCodeRequest,
 	validateAuthorizationCode,
 	validateToken,
 } from "./validate-authorization-code";

package/src/oauth2/oauth-provider.ts

@@ -35,6 +35,13 @@ export interface OAuthProvider<
 		redirectURI: string;
 		display?: string | undefined;
 		loginHint?: string | undefined;
+		/**
+		 * Extra query parameters to append to the authorization URL.
+		 * Providers forward these to the shared `createAuthorizationURL` helper,
+		 * which drops any keys present in `RESERVED_AUTHORIZATION_PARAMS`
+		 * before applying them.
+		 */
+		additionalParams?: Record<string, string> | undefined;
 	}) => Awaitable<URL>;
 	name: string;
 	validateAuthorizationCode: (data: {
@@ -94,6 +101,17 @@ export interface OAuthProvider<
 	 * Disable sign up for new users.
 	 */
 	disableSignUp?: boolean | undefined;
+	/**
+	 * Accept callbacks that arrive without a `state` parameter. When true,
+	 * the shared OAuth callback handler restarts the flow server-side with
+	 * fresh `state` and PKCE instead of rejecting the request. Intended for
+	 * providers that initiate OAuth without RP-side flow kickoff (e.g.
+	 * Clever). Leave unset for any provider that always initiates from the
+	 * RP.
+	 *
+	 * @default false
+	 */
+	allowIdpInitiated?: boolean | undefined;
 	/**
 	 * Options for the provider
 	 */
@@ -104,9 +122,10 @@ export type ProviderOptions<Profile extends Record<string, any> = any> = {
 	/**
 	 * The client ID of your application.
 	 *
-	 * This is usually a string but can be any type depending on the provider.
+	 * Some providers accept multiple platform client IDs. The first entry is the
+	 * primary client ID used for token endpoint client authentication.
 	 */
-	clientId?: unknown | undefined;
+	clientId?: LiteralString | string[] | undefined;
 	/**
 	 * The client secret of your application
 	 */

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<{