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

package/src/db/get-tables.ts

@@ -261,10 +261,15 @@ export const getAuthTables = (
 						options.account?.fields?.refreshTokenExpiresAt ||
 						"refreshTokenExpiresAt",
 				},
-				scope: {
-					type: "string",
+				// Renamed from the legacy `scope` column. The migration generator
+				// only adds this column; it does not transform the legacy `scope`
+				// value. Upgrading installs need a manual data migration (split
+				// legacy `scope` on comma/space, trim, drop empties, dedupe). Order
+				// is insignificant per RFC 6749 §3.3.
+				grantedScopes: {
+					type: "string[]",
 					required: false,
-					fieldName: options.account?.fields?.scope || "scope",
+					fieldName: options.account?.fields?.grantedScopes || "grantedScopes",
 				},
 				password: {
 					type: "string",

package/src/db/schema/account.ts

@@ -23,9 +23,21 @@ export const accountSchema = coreSchema.extend({
 	 */
 	refreshTokenExpiresAt: z.date().nullish(),
 	/**
-	 * The scopes that the user has authorized
+	 * The scopes the user has granted, as last observed (durable, per-account,
+	 * the unit of revocation and the refresh ceiling). A native array, not a
+	 * delimited string: scope order is insignificant per RFC 6749 §3.3, so the
+	 * value is normalized (trimmed, deduped, sorted) on write.
+	 *
+	 * Renamed from the legacy comma-joined `scope` string. Breaking, with no
+	 * automatic data migration (and no read-time shim): the migration generator
+	 * only adds the new `grantedScopes` column, so legacy accounts read as empty
+	 * here until an upgrade backfills `grantedScopes` from the old `scope` values
+	 * (split on comma/space, trim, drop empties, dedupe). See the release
+	 * changeset for the backfill.
+	 *
+	 * @see https://www.rfc-editor.org/rfc/rfc6749#section-3.3
 	 */
-	scope: z.string().nullish(),
+	grantedScopes: z.array(z.string()).nullish(),
 	/**
 	 * Password is only stored in the credential provider
 	 */

package/src/db/type.ts

@@ -311,6 +311,18 @@ export interface SecondaryStorage {
 	 * @returns - Value of the key
 	 */
 	get: (key: string) => Awaitable<unknown>;
+	/**
+	 * Atomically get a value and delete it from storage.
+	 *
+	 * This is optional for backwards compatibility with existing secondary
+	 * storage implementations. Single-use credential consumers use it when
+	 * present to avoid a read-then-delete race.
+	 *
+	 * TODO(secondary-storage-atomic-consume): make this required in the next
+	 * breaking release, or require database-backed verification storage for
+	 * security-sensitive consume paths.
+	 */
+	getAndDelete?: (key: string) => Awaitable<unknown>;
 	set: (
 		/**
 		 * Key to store

package/src/env/env-impl.ts

@@ -46,8 +46,7 @@ function toBoolean(val: boolean | string | undefined) {
 	return val ? val !== "false" : false;
 }
 
-export const nodeENV =
-	(typeof process !== "undefined" && process.env && process.env.NODE_ENV) || "";
+export const nodeENV = env.NODE_ENV ?? "";
 
 /** Detect if `NODE_ENV` environment variable is `production` */
 export const isProduction = nodeENV === "production";

package/src/error/codes.ts

@@ -29,6 +29,11 @@ export const BASE_ERROR_CODES = defineErrorCodes({
 	TOKEN_EXPIRED: "Token expired",
 	ID_TOKEN_NOT_SUPPORTED: "id_token not supported",
 	FAILED_TO_GET_USER_INFO: "Failed to get user info",
+	PROVIDER_NOT_SUPPORTED: "Provider not supported",
+	TOKEN_REFRESH_NOT_SUPPORTED: "Token refresh not supported",
+	REFRESH_TOKEN_NOT_FOUND: "Refresh token not found",
+	FAILED_TO_GET_ACCESS_TOKEN: "Failed to get a valid access token",
+	FAILED_TO_REFRESH_ACCESS_TOKEN: "Failed to refresh access token",
 	USER_EMAIL_NOT_FOUND: "User email not found",
 	EMAIL_NOT_VERIFIED: "Email not verified",
 	PASSWORD_TOO_SHORT: "Password too short",
@@ -37,6 +42,7 @@ export const BASE_ERROR_CODES = defineErrorCodes({
 	USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL:
 		"User already exists. Use another email.",
 	EMAIL_CAN_NOT_BE_UPDATED: "Email can not be updated",
+	CHANGE_EMAIL_DISABLED: "Change email is disabled",
 	CREDENTIAL_ACCOUNT_NOT_FOUND: "Credential account not found",
 	SESSION_EXPIRED: "Session expired. Re-authenticate to perform this action.",
 	FAILED_TO_UNLINK_LAST_ACCOUNT: "You can't unlink your last account",

package/src/oauth2/authorization-params.ts

@@ -0,0 +1,28 @@
+import * as z from "zod";
+import {
+	RESERVED_AUTHORIZATION_PARAMS,
+	RESERVED_AUTHORIZATION_PARAMS_SET,
+} from "./create-authorization-url";
+
+/**
+ * Zod schema for the `additionalParams` field on social sign-in and
+ * account-linking request bodies. Rejects any key reserved by the
+ * authorization-URL builder (see `RESERVED_AUTHORIZATION_PARAMS`), so
+ * a caller cannot overwrite `state`, PKCE, `redirect_uri`, etc.
+ */
+export const additionalAuthorizationParamsSchema = z
+	.record(z.string(), z.string())
+	.refine(
+		(value) =>
+			!Object.keys(value).some((key) =>
+				RESERVED_AUTHORIZATION_PARAMS_SET.has(key),
+			),
+		{
+			message: `additionalParams cannot include reserved OAuth parameters: ${RESERVED_AUTHORIZATION_PARAMS.join(", ")}`,
+		},
+	)
+	.meta({
+		description:
+			"Extra query parameters to append to the provider authorization URL (e.g. Cognito identity_provider, Google hd).",
+	})
+	.optional();

package/src/oauth2/basic-credentials.ts

@@ -0,0 +1,87 @@
+import { base64 } from "@better-auth/utils/base64";
+
+// RFC 7235 §2.1: auth scheme is case-insensitive and is followed by one or
+// more SP before the credentials. The trailing capture is everything after
+// the whitespace (may be empty, which downstream checks reject).
+const BASIC_AUTHORIZATION_PATTERN = /^Basic +(.*)$/i;
+
+/**
+ * Encodes a value using `application/x-www-form-urlencoded` per the URL
+ * Living Standard. Differs from `encodeURIComponent` in two ways: it escapes
+ * `!`, `'`, `(`, and `)`, and it represents space as `+` rather than `%20`.
+ * `*` is left unescaped, matching the URL Standard's percent-encode set.
+ */
+function formUrlEncode(value: string): string {
+	return new URLSearchParams({ v: value }).toString().slice("v=".length);
+}
+
+/**
+ * Inverse of `formUrlEncode`: decodes a single `application/x-www-form-urlencoded`
+ * value, handling both `+` and `%20` as space.
+ */
+function formUrlDecode(value: string): string {
+	const decoded = new URLSearchParams(`v=${value}`).get("v");
+	if (decoded === null) {
+		throw new Error("form-url-encoded value could not be decoded");
+	}
+	return decoded;
+}
+
+/**
+ * Encodes an OAuth client id and secret as an HTTP Basic credential string.
+ *
+ * Follows RFC 6749 §2.3.1: both values are `application/x-www-form-urlencoded`
+ * prior to base64 encoding. The returned string is the full value of the
+ * `Authorization` header, including the `Basic ` prefix.
+ */
+export function encodeBasicCredentials(
+	clientId: string,
+	clientSecret: string,
+): string {
+	const payload = `${formUrlEncode(clientId)}:${formUrlEncode(clientSecret)}`;
+	return `Basic ${base64.encode(payload)}`;
+}
+
+/**
+ * Decodes an `Authorization: Basic …` header value into its OAuth client id
+ * and secret.
+ *
+ * Scheme matching is case-insensitive and tolerates one or more spaces
+ * between the scheme and credentials per RFC 7235 §2.1. The base64 payload
+ * is split on the first `:` only, so secrets containing colons round-trip
+ * correctly. Each half is form-url-decoded per RFC 6749 §2.3.1, accepting
+ * both `+` and `%20` as space. Per the URL Living Standard, invalid
+ * percent-escapes pass through as-is; downstream client lookup will fail
+ * with `invalid_client` for malformed credentials.
+ *
+ * Throws when the header is not a Basic credential, when the base64 payload
+ * contains no `:`, or when either half is empty.
+ */
+export function decodeBasicCredentials(authorization: string): {
+	clientId: string;
+	clientSecret: string;
+} {
+	const match = authorization.match(BASIC_AUTHORIZATION_PATTERN);
+	if (!match) {
+		throw new Error("Authorization header is not a Basic credential");
+	}
+	const encoded = match[1] ?? "";
+	const decoded = new TextDecoder().decode(base64.decode(encoded));
+	const separatorIndex = decoded.indexOf(":");
+	if (separatorIndex === -1) {
+		throw new Error(
+			"Basic credential is missing the client id/secret separator",
+		);
+	}
+	const rawClientId = decoded.slice(0, separatorIndex);
+	const rawClientSecret = decoded.slice(separatorIndex + 1);
+	if (!rawClientId || !rawClientSecret) {
+		throw new Error(
+			"Basic credential client id and secret must both be non-empty",
+		);
+	}
+	return {
+		clientId: formUrlDecode(rawClientId),
+		clientSecret: formUrlDecode(rawClientSecret),
+	};
+}

package/src/oauth2/client-assertion.ts

@@ -1,8 +1,9 @@
 import type { JWTHeaderParameters } from "jose";
 import { importJWK, importPKCS8, SignJWT } from "jose";
+import type { Awaitable } from "../types";
 
 /** Asymmetric signing algorithms compatible with private_key_jwt (RFC 7523). */
-export const ASSERTION_SIGNING_ALGORITHMS = [
+export const PRIVATE_KEY_JWT_SIGNING_ALGORITHMS = [
 	"RS256",
 	"RS384",
 	"RS512",
@@ -15,15 +16,79 @@ export const ASSERTION_SIGNING_ALGORITHMS = [
 	"EdDSA",
 ] as const;
 
-export type AssertionSigningAlgorithm =
-	(typeof ASSERTION_SIGNING_ALGORITHMS)[number];
+export type PrivateKeyJwtSigningAlgorithm =
+	(typeof PRIVATE_KEY_JWT_SIGNING_ALGORITHMS)[number];
+
+function assertSupportedPrivateKeyJwtAlgorithm(
+	candidate: string,
+): asserts candidate is PrivateKeyJwtSigningAlgorithm {
+	if (
+		!(PRIVATE_KEY_JWT_SIGNING_ALGORITHMS as readonly string[]).includes(
+			candidate,
+		)
+	) {
+		throw new Error(
+			`Unsupported private_key_jwt signing algorithm: ${candidate}. Use one of ${PRIVATE_KEY_JWT_SIGNING_ALGORITHMS.join(", ")}.`,
+		);
+	}
+}
+
+/**
+ * Validates `private_key_jwt` options eagerly and returns the algorithm to
+ * use for signing.
+ *
+ * Asserts that key material is configured, that any explicit `algorithm` is
+ * supported, that any JWK-embedded `alg` is supported, and that the two
+ * agree when both are set.
+ */
+function resolveValidPrivateKeyJwtOptions(options: {
+	privateKeyJwk?: JsonWebKey;
+	privateKeyPem?: string;
+	algorithm?: PrivateKeyJwtSigningAlgorithm;
+}): PrivateKeyJwtSigningAlgorithm {
+	if (!options.privateKeyJwk && !options.privateKeyPem) {
+		throw new Error(
+			"private_key_jwt requires either privateKeyJwk or privateKeyPem",
+		);
+	}
+	if (options.algorithm) {
+		assertSupportedPrivateKeyJwtAlgorithm(options.algorithm);
+	}
+	const jwkAlg = options.privateKeyJwk?.alg;
+	if (typeof jwkAlg === "string") {
+		assertSupportedPrivateKeyJwtAlgorithm(jwkAlg);
+	}
+	if (
+		options.algorithm &&
+		typeof jwkAlg === "string" &&
+		options.algorithm !== jwkAlg
+	) {
+		throw new Error(
+			`JWK alg "${jwkAlg}" does not match configured algorithm "${options.algorithm}". Remove the JWK alg field, or pass an algorithm that matches the JWK.`,
+		);
+	}
+	return options.algorithm ?? (typeof jwkAlg === "string" ? jwkAlg : "RS256");
+}
 
 export const CLIENT_ASSERTION_TYPE =
 	"urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
 
-export interface ClientAssertionConfig {
-	/** Pre-signed JWT assertion string. If provided, signing is skipped. */
-	assertion?: string;
+export type ClientAssertionGrantType =
+	| "authorization_code"
+	| "refresh_token"
+	| "client_credentials";
+
+export interface ClientAssertionContext {
+	clientId: string;
+	tokenEndpoint: string;
+	grantType: ClientAssertionGrantType;
+}
+
+export type ClientAssertionGetter = (
+	context: ClientAssertionContext,
+) => Awaitable<string>;
+
+export interface PrivateKeyJwtClientAssertionGetterOptions {
 	/** Private key in JWK format for signing. */
 	privateKeyJwk?: JsonWebKey;
 	/** Private key in PKCS#8 PEM format for signing. */
@@ -31,9 +96,7 @@ export interface ClientAssertionConfig {
 	/** Key ID to include in the JWT header. */
 	kid?: string;
 	/** Asymmetric signing algorithm. Symmetric algorithms (HS256) and "none" are not allowed. @default "RS256" */
-	algorithm?: AssertionSigningAlgorithm;
-	/** Token endpoint URL (used as the JWT `aud` claim). */
-	tokenEndpoint?: string;
+	algorithm?: PrivateKeyJwtSigningAlgorithm;
 	/** Assertion lifetime in seconds. @default 120 */
 	expiresIn?: number;
 }
@@ -41,10 +104,16 @@ export interface ClientAssertionConfig {
 /**
  * Signs an RFC 7523 client assertion JWT for `private_key_jwt` authentication.
  *
- * The JWT contains: iss=clientId, sub=clientId, aud=tokenEndpoint,
- * exp=now+120s, jti=unique, iat=now.
+ * The JWT contains these claims:
+ *
+ * - iss=clientId
+ * - sub=clientId
+ * - aud=tokenEndpoint
+ * - exp=now + 120s
+ * - jti=unique
+ * - iat=now
  */
-export async function signClientAssertion({
+export async function signPrivateKeyJwtClientAssertion({
 	clientId,
 	tokenEndpoint,
 	privateKeyJwk,
@@ -58,34 +127,30 @@ export async function signClientAssertion({
 	privateKeyJwk?: JsonWebKey;
 	privateKeyPem?: string;
 	kid?: string;
-	algorithm?: AssertionSigningAlgorithm;
+	algorithm?: PrivateKeyJwtSigningAlgorithm;
 	expiresIn?: number;
 }): Promise<string> {
-	// Fall back to JWK-embedded kid/alg when not explicitly provided (RFC 7517).
-	// JsonWebKey includes alg but not kid; access kid via index.
+	const resolvedAlg = resolveValidPrivateKeyJwtOptions({
+		privateKeyJwk,
+		privateKeyPem,
+		algorithm,
+	});
+	// Fall back to the JWK-embedded kid when not explicitly provided (RFC 7517).
+	// JsonWebKey types include alg but not kid; access kid via index.
 	const jwk = privateKeyJwk as Record<string, unknown> | undefined;
 	const resolvedKid = kid ?? (jwk?.kid as string | undefined);
-	const resolvedAlg =
-		algorithm ??
-		(privateKeyJwk?.alg as AssertionSigningAlgorithm | undefined) ??
-		"RS256";
-
-	let key: Awaited<ReturnType<typeof importJWK>>;
-	if (privateKeyJwk) {
-		key = await importJWK(privateKeyJwk, resolvedAlg);
-	} else if (privateKeyPem) {
-		key = await importPKCS8(privateKeyPem, resolvedAlg);
-	} else {
-		throw new Error(
-			"private_key_jwt requires either privateKeyJwk or privateKeyPem",
-		);
-	}
+
+	const key: Awaited<ReturnType<typeof importJWK>> = privateKeyJwk
+		? await importJWK(privateKeyJwk, resolvedAlg)
+		: await importPKCS8(privateKeyPem as string, resolvedAlg);
 
 	const now = Math.floor(Date.now() / 1000);
 	const jti = crypto.randomUUID();
 
 	const header: JWTHeaderParameters = { alg: resolvedAlg, typ: "JWT" };
-	if (resolvedKid) header.kid = resolvedKid;
+	if (resolvedKid) {
+		header.kid = resolvedKid;
+	}
 
 	return new SignJWT({})
 		.setProtectedHeader(header)
@@ -99,36 +164,44 @@ export async function signClientAssertion({
 }
 
 /**
- * Resolves a ClientAssertionConfig into `client_assertion` + `client_assertion_type`
- * params for injection into a token request body.
+ * Creates a client assertion getter for `private_key_jwt` authentication.
+ *
+ * Validates options eagerly (key material, supported algorithm, JWK alg
+ * agreement) so misconfiguration surfaces at construction rather than on the
+ * first token request. The returned function signs a fresh RFC 7523 JWT
+ * assertion for every token endpoint request.
  */
-export async function resolveAssertionParams({
-	clientAssertion,
-	clientId,
-	tokenEndpoint,
-}: {
-	clientAssertion: ClientAssertionConfig;
-	clientId: string;
-	tokenEndpoint?: string;
-}): Promise<Record<string, string>> {
-	let assertion = clientAssertion.assertion;
-	if (!assertion) {
-		const audEndpoint = tokenEndpoint ?? clientAssertion.tokenEndpoint;
-		if (!audEndpoint) {
-			throw new Error(
-				"private_key_jwt requires a tokenEndpoint for the JWT audience claim",
-			);
-		}
-		assertion = await signClientAssertion({
+export function createPrivateKeyJwtClientAssertionGetter(
+	options: PrivateKeyJwtClientAssertionGetterOptions,
+): ClientAssertionGetter {
+	resolveValidPrivateKeyJwtOptions({
+		privateKeyJwk: options.privateKeyJwk,
+		privateKeyPem: options.privateKeyPem,
+		algorithm: options.algorithm,
+	});
+	return ({ clientId, tokenEndpoint }) =>
+		signPrivateKeyJwtClientAssertion({
 			clientId,
-			tokenEndpoint: audEndpoint,
-			privateKeyJwk: clientAssertion.privateKeyJwk,
-			privateKeyPem: clientAssertion.privateKeyPem,
-			kid: clientAssertion.kid,
-			algorithm: clientAssertion.algorithm,
-			expiresIn: clientAssertion.expiresIn,
+			tokenEndpoint,
+			privateKeyJwk: options.privateKeyJwk,
+			privateKeyPem: options.privateKeyPem,
+			kid: options.kid,
+			algorithm: options.algorithm,
+			expiresIn: options.expiresIn,
 		});
-	}
+}
+
+/**
+ * Resolves a client assertion getter into `client_assertion` + `client_assertion_type` params for injection into a token request body.
+ */
+export async function resolveClientAssertionParams({
+	getClientAssertion,
+	context,
+}: {
+	getClientAssertion: ClientAssertionGetter;
+	context: ClientAssertionContext;
+}): Promise<Record<string, string>> {
+	const assertion = await getClientAssertion(context);
 	return {
 		client_assertion: assertion,
 		client_assertion_type: CLIENT_ASSERTION_TYPE,

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,12 +64,13 @@ 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) {
+	if (scopes?.length) {
 		url.searchParams.set("scope", scopes.join(scopeJoiner || " "));
 	}
 	url.searchParams.set("redirect_uri", options.redirectURI || redirectURI);
@@ -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;
+	return { url, requestedScopes: scopes ?? [] };
 }