@better-auth/core 1.6.1 → 1.7.0-beta.0

package/dist/context/global.mjs

@@ -2,7 +2,7 @@
 const symbol = Symbol.for("better-auth:global");
 let bind = null;
 const __context = {};
-const __betterAuthVersion = "1.6.1";
+const __betterAuthVersion = "1.7.0-beta.0";
 /**
 * We store context instance in the globalThis.
 *

package/dist/instrumentation/tracer.mjs

@@ -1,7 +1,7 @@
 import { ATTR_HTTP_RESPONSE_STATUS_CODE } from "./attributes.mjs";
 import { SpanStatusCode, trace } from "@opentelemetry/api";
 //#region src/instrumentation/tracer.ts
-const tracer = trace.getTracer("better-auth", "1.6.1");
+const tracer = trace.getTracer("better-auth", "1.7.0-beta.0");
 /**
 * Better-auth uses `throw ctx.redirect(url)` for flow control (e.g. OAuth
 * callbacks). These are APIErrors with 3xx status codes and should not be

package/dist/oauth2/client-assertion.d.mts

@@ -0,0 +1,59 @@
+//#region src/oauth2/client-assertion.d.ts
+/** Asymmetric signing algorithms compatible with private_key_jwt (RFC 7523). */
+declare const ASSERTION_SIGNING_ALGORITHMS: readonly ["RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512", "EdDSA"];
+type AssertionSigningAlgorithm = (typeof ASSERTION_SIGNING_ALGORITHMS)[number];
+declare const CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+interface ClientAssertionConfig {
+  /** Pre-signed JWT assertion string. If provided, signing is skipped. */
+  assertion?: string;
+  /** Private key in JWK format for signing. */
+  privateKeyJwk?: JsonWebKey;
+  /** Private key in PKCS#8 PEM format for signing. */
+  privateKeyPem?: string;
+  /** 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;
+  /** Assertion lifetime in seconds. @default 120 */
+  expiresIn?: number;
+}
+/**
+ * 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.
+ */
+declare function signClientAssertion({
+  clientId,
+  tokenEndpoint,
+  privateKeyJwk,
+  privateKeyPem,
+  kid,
+  algorithm,
+  expiresIn
+}: {
+  clientId: string;
+  tokenEndpoint: string;
+  privateKeyJwk?: JsonWebKey;
+  privateKeyPem?: string;
+  kid?: string;
+  algorithm?: AssertionSigningAlgorithm;
+  expiresIn?: number;
+}): Promise<string>;
+/**
+ * Resolves a ClientAssertionConfig into `client_assertion` + `client_assertion_type`
+ * params for injection into a token request body.
+ */
+declare function resolveAssertionParams({
+  clientAssertion,
+  clientId,
+  tokenEndpoint
+}: {
+  clientAssertion: ClientAssertionConfig;
+  clientId: string;
+  tokenEndpoint?: string;
+}): Promise<Record<string, string>>;
+//#endregion
+export { ASSERTION_SIGNING_ALGORITHMS, AssertionSigningAlgorithm, CLIENT_ASSERTION_TYPE, ClientAssertionConfig, resolveAssertionParams, signClientAssertion };

package/dist/oauth2/client-assertion.mjs

@@ -0,0 +1,64 @@
+import { SignJWT, importJWK, importPKCS8 } from "jose";
+//#region src/oauth2/client-assertion.ts
+/** Asymmetric signing algorithms compatible with private_key_jwt (RFC 7523). */
+const ASSERTION_SIGNING_ALGORITHMS = [
+	"RS256",
+	"RS384",
+	"RS512",
+	"PS256",
+	"PS384",
+	"PS512",
+	"ES256",
+	"ES384",
+	"ES512",
+	"EdDSA"
+];
+const CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer";
+/**
+* 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.
+*/
+async function signClientAssertion({ clientId, tokenEndpoint, privateKeyJwk, privateKeyPem, kid, algorithm, expiresIn = 120 }) {
+	const resolvedKid = kid ?? privateKeyJwk?.kid;
+	const resolvedAlg = algorithm ?? privateKeyJwk?.alg ?? "RS256";
+	let key;
+	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 now = Math.floor(Date.now() / 1e3);
+	const jti = crypto.randomUUID();
+	const header = {
+		alg: resolvedAlg,
+		typ: "JWT"
+	};
+	if (resolvedKid) header.kid = resolvedKid;
+	return new SignJWT({}).setProtectedHeader(header).setIssuer(clientId).setSubject(clientId).setAudience(tokenEndpoint).setIssuedAt(now).setExpirationTime(now + expiresIn).setJti(jti).sign(key);
+}
+/**
+* Resolves a ClientAssertionConfig into `client_assertion` + `client_assertion_type`
+* params for injection into a token request body.
+*/
+async function resolveAssertionParams({ clientAssertion, clientId, tokenEndpoint }) {
+	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({
+			clientId,
+			tokenEndpoint: audEndpoint,
+			privateKeyJwk: clientAssertion.privateKeyJwk,
+			privateKeyPem: clientAssertion.privateKeyPem,
+			kid: clientAssertion.kid,
+			algorithm: clientAssertion.algorithm,
+			expiresIn: clientAssertion.expiresIn
+		});
+	}
+	return {
+		client_assertion: assertion,
+		client_assertion_type: CLIENT_ASSERTION_TYPE
+	};
+}
+//#endregion
+export { ASSERTION_SIGNING_ALGORITHMS, CLIENT_ASSERTION_TYPE, resolveAssertionParams, signClientAssertion };

package/dist/oauth2/client-credentials-token.d.mts

@@ -1,3 +1,4 @@
+import { ClientAssertionConfig } from "./client-assertion.mjs";
 import { AwaitableFunction } from "../types/helper.mjs";
 import { OAuth2Tokens, ProviderOptions } from "./oauth-provider.mjs";
 
@@ -6,13 +7,15 @@ declare function clientCredentialsTokenRequest({
   options,
   scope,
   authentication,
+  clientAssertion,
+  tokenEndpoint,
   resource
 }: {
-  options: AwaitableFunction<ProviderOptions & {
-    clientSecret: string;
-  }>;
+  options: AwaitableFunction<ProviderOptions>;
   scope?: string | undefined;
-  authentication?: ("basic" | "post") | 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;
 }): Promise<{
   body: URLSearchParams;
@@ -25,14 +28,14 @@ declare function createClientCredentialsTokenRequest({
   options,
   scope,
   authentication,
-  resource
+  resource,
+  extraParams
 }: {
-  options: ProviderOptions & {
-    clientSecret: string;
-  };
+  options: ProviderOptions;
   scope?: string | undefined;
-  authentication?: ("basic" | "post") | undefined;
+  authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
   resource?: (string | string[]) | undefined;
+  extraParams?: Record<string, string> | undefined;
 }): {
   body: URLSearchParams;
   headers: Record<string, any>;
@@ -42,14 +45,14 @@ declare function clientCredentialsToken({
   tokenEndpoint,
   scope,
   authentication,
+  clientAssertion,
   resource
 }: {
-  options: AwaitableFunction<ProviderOptions & {
-    clientSecret: string;
-  }>;
+  options: AwaitableFunction<ProviderOptions>;
   tokenEndpoint: string;
   scope: string;
-  authentication?: ("basic" | "post") | undefined;
+  authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
+  clientAssertion?: ClientAssertionConfig | undefined;
   resource?: (string | string[]) | undefined;
 }): Promise<OAuth2Tokens>;
 //#endregion

package/dist/oauth2/client-credentials-token.mjs

@@ -1,19 +1,30 @@
-import { base64Url } from "@better-auth/utils/base64";
+import { resolveAssertionParams } from "./client-assertion.mjs";
+import { base64 } from "@better-auth/utils/base64";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/oauth2/client-credentials-token.ts
-async function clientCredentialsTokenRequest({ options, scope, authentication, resource }) {
+async function clientCredentialsTokenRequest({ options, scope, authentication, clientAssertion, tokenEndpoint, resource }) {
 	options = typeof options === "function" ? await options() : options;
+	let extraParams;
+	if (authentication === "private_key_jwt") {
+		if (!clientAssertion) throw new Error("private_key_jwt authentication requires a clientAssertion configuration");
+		extraParams = await resolveAssertionParams({
+			clientAssertion,
+			clientId: Array.isArray(options.clientId) ? options.clientId[0] : options.clientId,
+			tokenEndpoint
+		});
+	}
 	return createClientCredentialsTokenRequest({
 		options,
 		scope,
 		authentication,
-		resource
+		resource,
+		extraParams
 	});
 }
 /**
 * @deprecated use async'd clientCredentialsTokenRequest instead
 */
-function createClientCredentialsTokenRequest({ options, scope, authentication, resource }) {
+function createClientCredentialsTokenRequest({ options, scope, authentication, resource, extraParams }) {
 	const body = new URLSearchParams();
 	const headers = {
 		"content-type": "application/x-www-form-urlencoded",
@@ -23,24 +34,27 @@ function createClientCredentialsTokenRequest({ options, scope, authentication, r
 	scope && body.set("scope", scope);
 	if (resource) if (typeof resource === "string") body.append("resource", resource);
 	else for (const _resource of resource) body.append("resource", _resource);
-	if (authentication === "basic") {
-		const primaryClientId = Array.isArray(options.clientId) ? options.clientId[0] : options.clientId;
-		headers["authorization"] = `Basic ${base64Url.encode(`${primaryClientId}:${options.clientSecret}`)}`;
-	} else {
-		const primaryClientId = Array.isArray(options.clientId) ? options.clientId[0] : options.clientId;
+	const primaryClientId = Array.isArray(options.clientId) ? options.clientId[0] : options.clientId;
+	if (authentication === "basic") headers["authorization"] = `Basic ${base64.encode(`${primaryClientId}:${options.clientSecret ?? ""}`)}`;
+	else {
 		body.set("client_id", primaryClientId);
-		body.set("client_secret", options.clientSecret);
+		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);
 	}
 	return {
 		body,
 		headers
 	};
 }
-async function clientCredentialsToken({ options, tokenEndpoint, scope, authentication, resource }) {
+async function clientCredentialsToken({ options, tokenEndpoint, scope, authentication, clientAssertion, resource }) {
 	const { body, headers } = await clientCredentialsTokenRequest({
 		options,
 		scope,
 		authentication,
+		clientAssertion,
+		tokenEndpoint,
 		resource
 	});
 	const { data, error } = await betterFetch(tokenEndpoint, {

package/dist/oauth2/index.d.mts

@@ -1,3 +1,4 @@
+import { ASSERTION_SIGNING_ALGORITHMS, AssertionSigningAlgorithm, CLIENT_ASSERTION_TYPE, ClientAssertionConfig, resolveAssertionParams, signClientAssertion } from "./client-assertion.mjs";
 import { OAuth2Tokens, OAuth2UserInfo, OAuthProvider, ProviderOptions } from "./oauth-provider.mjs";
 import { clientCredentialsToken, clientCredentialsTokenRequest, createClientCredentialsTokenRequest } from "./client-credentials-token.mjs";
 import { createAuthorizationURL } from "./create-authorization-url.mjs";
@@ -5,4 +6,4 @@ import { createRefreshAccessTokenRequest, refreshAccessToken, refreshAccessToken
 import { generateCodeChallenge, getOAuth2Tokens } from "./utils.mjs";
 import { authorizationCodeRequest, createAuthorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
 import { getJwks, verifyAccessToken, verifyJwsAccessToken } from "./verify.mjs";
-export { type OAuth2Tokens, type OAuth2UserInfo, type OAuthProvider, type ProviderOptions, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationCodeRequest, createAuthorizationURL, createClientCredentialsTokenRequest, createRefreshAccessTokenRequest, generateCodeChallenge, getJwks, getOAuth2Tokens, refreshAccessToken, refreshAccessTokenRequest, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };
+export { ASSERTION_SIGNING_ALGORITHMS, type AssertionSigningAlgorithm, CLIENT_ASSERTION_TYPE, type ClientAssertionConfig, type OAuth2Tokens, type OAuth2UserInfo, type OAuthProvider, type ProviderOptions, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationCodeRequest, createAuthorizationURL, createClientCredentialsTokenRequest, createRefreshAccessTokenRequest, generateCodeChallenge, getJwks, getOAuth2Tokens, refreshAccessToken, refreshAccessTokenRequest, resolveAssertionParams, signClientAssertion, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };

package/dist/oauth2/index.mjs

@@ -1,7 +1,8 @@
+import { ASSERTION_SIGNING_ALGORITHMS, CLIENT_ASSERTION_TYPE, resolveAssertionParams, signClientAssertion } from "./client-assertion.mjs";
 import { clientCredentialsToken, clientCredentialsTokenRequest, createClientCredentialsTokenRequest } from "./client-credentials-token.mjs";
 import { generateCodeChallenge, getOAuth2Tokens } from "./utils.mjs";
 import { createAuthorizationURL } from "./create-authorization-url.mjs";
 import { createRefreshAccessTokenRequest, refreshAccessToken, refreshAccessTokenRequest } from "./refresh-access-token.mjs";
 import { authorizationCodeRequest, createAuthorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
 import { getJwks, verifyAccessToken, verifyJwsAccessToken } from "./verify.mjs";
-export { authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationCodeRequest, createAuthorizationURL, createClientCredentialsTokenRequest, createRefreshAccessTokenRequest, generateCodeChallenge, getJwks, getOAuth2Tokens, refreshAccessToken, refreshAccessTokenRequest, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };
+export { ASSERTION_SIGNING_ALGORITHMS, CLIENT_ASSERTION_TYPE, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationCodeRequest, createAuthorizationURL, createClientCredentialsTokenRequest, createRefreshAccessTokenRequest, generateCodeChallenge, getJwks, getOAuth2Tokens, refreshAccessToken, refreshAccessTokenRequest, resolveAssertionParams, signClientAssertion, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };

package/dist/oauth2/refresh-access-token.d.mts

@@ -1,3 +1,4 @@
+import { ClientAssertionConfig } from "./client-assertion.mjs";
 import { AwaitableFunction } from "../types/helper.mjs";
 import { OAuth2Tokens, ProviderOptions } from "./oauth-provider.mjs";
 
@@ -6,12 +7,16 @@ declare function refreshAccessTokenRequest({
   refreshToken,
   options,
   authentication,
+  clientAssertion,
+  tokenEndpoint,
   extraParams,
   resource
 }: {
   refreshToken: string;
   options: AwaitableFunction<Partial<ProviderOptions>>;
-  authentication?: ("basic" | "post") | 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;
   extraParams?: Record<string, string> | undefined;
   resource?: (string | string[]) | undefined;
 }): Promise<{
@@ -30,7 +35,7 @@ declare function createRefreshAccessTokenRequest({
 }: {
   refreshToken: string;
   options: ProviderOptions;
-  authentication?: ("basic" | "post") | undefined;
+  authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
   extraParams?: Record<string, string> | undefined;
   resource?: (string | string[]) | undefined;
 }): {
@@ -42,12 +47,14 @@ declare function refreshAccessToken({
   options,
   tokenEndpoint,
   authentication,
+  clientAssertion,
   extraParams
 }: {
   refreshToken: string;
   options: Partial<ProviderOptions>;
   tokenEndpoint: string;
-  authentication?: ("basic" | "post") | undefined;
+  authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
+  clientAssertion?: ClientAssertionConfig | undefined;
   extraParams?: Record<string, string> | undefined;
 }): Promise<OAuth2Tokens>;
 //#endregion

package/dist/oauth2/refresh-access-token.mjs

@@ -1,8 +1,21 @@
+import { resolveAssertionParams } from "./client-assertion.mjs";
 import { base64 } from "@better-auth/utils/base64";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/oauth2/refresh-access-token.ts
-async function refreshAccessTokenRequest({ refreshToken, options, authentication, extraParams, resource }) {
+async function refreshAccessTokenRequest({ refreshToken, options, authentication, clientAssertion, tokenEndpoint, extraParams, resource }) {
 	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 assertionParams = await resolveAssertionParams({
+			clientAssertion,
+			clientId: Array.isArray(options.clientId) ? options.clientId[0] : options.clientId,
+			tokenEndpoint
+		});
+		extraParams = {
+			...extraParams,
+			...assertionParams
+		};
+	}
 	return createRefreshAccessTokenRequest({
 		refreshToken,
 		options,
@@ -22,14 +35,12 @@ function createRefreshAccessTokenRequest({ refreshToken, options, authentication
 	};
 	body.set("grant_type", "refresh_token");
 	body.set("refresh_token", refreshToken);
-	if (authentication === "basic") {
-		const primaryClientId = Array.isArray(options.clientId) ? options.clientId[0] : options.clientId;
-		if (primaryClientId) headers["authorization"] = "Basic " + base64.encode(`${primaryClientId}:${options.clientSecret ?? ""}`);
-		else headers["authorization"] = "Basic " + base64.encode(`:${options.clientSecret ?? ""}`);
-	} else {
-		const primaryClientId = Array.isArray(options.clientId) ? options.clientId[0] : options.clientId;
+	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 (options.clientSecret) body.set("client_secret", options.clientSecret);
+		if (authentication !== "private_key_jwt" && options.clientSecret) body.set("client_secret", options.clientSecret);
 	}
 	if (resource) if (typeof resource === "string") body.append("resource", resource);
 	else for (const _resource of resource) body.append("resource", _resource);
@@ -39,11 +50,13 @@ function createRefreshAccessTokenRequest({ refreshToken, options, authentication
 		headers
 	};
 }
-async function refreshAccessToken({ refreshToken, options, tokenEndpoint, authentication, extraParams }) {
-	const { body, headers } = await createRefreshAccessTokenRequest({
+async function refreshAccessToken({ refreshToken, options, tokenEndpoint, authentication, clientAssertion, extraParams }) {
+	const { body, headers } = await refreshAccessTokenRequest({
 		refreshToken,
 		options,
 		authentication,
+		clientAssertion,
+		tokenEndpoint,
 		extraParams
 	});
 	const { data, error } = await betterFetch(tokenEndpoint, {

package/dist/oauth2/validate-authorization-code.d.mts

@@ -1,3 +1,4 @@
+import { ClientAssertionConfig } from "./client-assertion.mjs";
 import { AwaitableFunction } from "../types/helper.mjs";
 import { OAuth2Tokens, ProviderOptions } from "./oauth-provider.mjs";
 import * as jose from "jose";
@@ -9,6 +10,8 @@ declare function authorizationCodeRequest({
   redirectURI,
   options,
   authentication,
+  clientAssertion,
+  tokenEndpoint,
   deviceId,
   headers,
   additionalParams,
@@ -19,7 +22,9 @@ declare function authorizationCodeRequest({
   options: AwaitableFunction<Partial<ProviderOptions>>;
   codeVerifier?: string | undefined;
   deviceId?: string | undefined;
-  authentication?: ("basic" | "post") | 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;
@@ -46,7 +51,7 @@ declare function createAuthorizationCodeRequest({
   options: Partial<ProviderOptions>;
   codeVerifier?: string | undefined;
   deviceId?: string | undefined;
-  authentication?: ("basic" | "post") | undefined;
+  authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
   headers?: Record<string, string> | undefined;
   additionalParams?: Record<string, string> | undefined;
   resource?: (string | string[]) | undefined;
@@ -61,6 +66,7 @@ declare function validateAuthorizationCode({
   options,
   tokenEndpoint,
   authentication,
+  clientAssertion,
   deviceId,
   headers,
   additionalParams,
@@ -72,7 +78,8 @@ declare function validateAuthorizationCode({
   codeVerifier?: string | undefined;
   deviceId?: string | undefined;
   tokenEndpoint: string;
-  authentication?: ("basic" | "post") | undefined;
+  authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
+  clientAssertion?: ClientAssertionConfig | undefined;
   headers?: Record<string, string> | undefined;
   additionalParams?: Record<string, string> | undefined;
   resource?: (string | string[]) | undefined;

package/dist/oauth2/validate-authorization-code.mjs

@@ -1,10 +1,23 @@
+import { resolveAssertionParams } from "./client-assertion.mjs";
 import { getOAuth2Tokens } from "./utils.mjs";
+import { createRemoteJWKSet, jwtVerify } from "jose";
 import { base64 } from "@better-auth/utils/base64";
 import { betterFetch } from "@better-fetch/fetch";
-import { createRemoteJWKSet, jwtVerify } from "jose";
 //#region src/oauth2/validate-authorization-code.ts
-async function authorizationCodeRequest({ code, codeVerifier, redirectURI, options, authentication, deviceId, headers, additionalParams = {}, resource }) {
+async function authorizationCodeRequest({ code, codeVerifier, redirectURI, options, authentication, clientAssertion, tokenEndpoint, deviceId, headers, additionalParams = {}, resource }) {
 	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 assertionParams = await resolveAssertionParams({
+			clientAssertion,
+			clientId: Array.isArray(options.clientId) ? options.clientId[0] : options.clientId,
+			tokenEndpoint
+		});
+		additionalParams = {
+			...additionalParams,
+			...assertionParams
+		};
+	}
 	return createAuthorizationCodeRequest({
 		code,
 		codeVerifier,
@@ -35,13 +48,11 @@ function createAuthorizationCodeRequest({ code, codeVerifier, redirectURI, optio
 	body.set("redirect_uri", options.redirectURI || redirectURI);
 	if (resource) if (typeof resource === "string") body.append("resource", resource);
 	else for (const _resource of resource) body.append("resource", _resource);
-	if (authentication === "basic") {
-		const primaryClientId = Array.isArray(options.clientId) ? options.clientId[0] : options.clientId;
-		requestHeaders["authorization"] = `Basic ${base64.encode(`${primaryClientId}:${options.clientSecret ?? ""}`)}`;
-	} else {
-		const primaryClientId = Array.isArray(options.clientId) ? options.clientId[0] : options.clientId;
+	const primaryClientId = Array.isArray(options.clientId) ? options.clientId[0] : options.clientId;
+	if (authentication === "basic") requestHeaders["authorization"] = `Basic ${base64.encode(`${primaryClientId}:${options.clientSecret ?? ""}`)}`;
+	else {
 		body.set("client_id", primaryClientId);
-		if (options.clientSecret) body.set("client_secret", options.clientSecret);
+		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);
 	return {
@@ -49,13 +60,15 @@ function createAuthorizationCodeRequest({ code, codeVerifier, redirectURI, optio
 		headers: requestHeaders
 	};
 }
-async function validateAuthorizationCode({ code, codeVerifier, redirectURI, options, tokenEndpoint, authentication, deviceId, headers, additionalParams = {}, resource }) {
+async function validateAuthorizationCode({ code, codeVerifier, redirectURI, options, tokenEndpoint, authentication, clientAssertion, deviceId, headers, additionalParams = {}, resource }) {
 	const { body, headers: requestHeaders } = await authorizationCodeRequest({
 		code,
 		codeVerifier,
 		redirectURI,
 		options,
 		authentication,
+		clientAssertion,
+		tokenEndpoint,
 		deviceId,
 		headers,
 		additionalParams,

package/dist/oauth2/verify.mjs

@@ -1,7 +1,7 @@
 import { logger } from "../env/logger.mjs";
 import { APIError } from "better-call";
-import { betterFetch } from "@better-fetch/fetch";
 import { UnsecuredJWT, createLocalJWKSet, decodeProtectedHeader, jwtVerify } from "jose";
+import { betterFetch } from "@better-fetch/fetch";
 //#region src/oauth2/verify.ts
 /** Last fetched jwks used locally in getJwks @internal */
 let jwks;

package/dist/social-providers/apple.mjs

@@ -2,8 +2,8 @@ import { APIError } from "../error/index.mjs";
 import { createAuthorizationURL } from "../oauth2/create-authorization-url.mjs";
 import { refreshAccessToken } from "../oauth2/refresh-access-token.mjs";
 import { validateAuthorizationCode } from "../oauth2/validate-authorization-code.mjs";
-import { betterFetch } from "@better-fetch/fetch";
 import { decodeJwt, decodeProtectedHeader, importJWK, jwtVerify } from "jose";
+import { betterFetch } from "@better-fetch/fetch";
 //#region src/social-providers/apple.ts
 const apple = (options) => {
 	const tokenEndpoint = "https://appleid.apple.com/auth/token";

package/dist/social-providers/cognito.mjs

@@ -3,8 +3,8 @@ import { APIError, BetterAuthError } from "../error/index.mjs";
 import { createAuthorizationURL } from "../oauth2/create-authorization-url.mjs";
 import { refreshAccessToken } from "../oauth2/refresh-access-token.mjs";
 import { validateAuthorizationCode } from "../oauth2/validate-authorization-code.mjs";
-import { betterFetch } from "@better-fetch/fetch";
 import { decodeJwt, decodeProtectedHeader, importJWK, jwtVerify } from "jose";
+import { betterFetch } from "@better-fetch/fetch";
 //#region src/social-providers/cognito.ts
 const cognito = (options) => {
 	if (!options.domain || !options.region || !options.userPoolId) {

package/dist/social-providers/facebook.mjs

@@ -1,8 +1,8 @@
 import { createAuthorizationURL } from "../oauth2/create-authorization-url.mjs";
 import { refreshAccessToken } from "../oauth2/refresh-access-token.mjs";
 import { validateAuthorizationCode } from "../oauth2/validate-authorization-code.mjs";
-import { betterFetch } from "@better-fetch/fetch";
 import { createRemoteJWKSet, decodeJwt, jwtVerify } from "jose";
+import { betterFetch } from "@better-fetch/fetch";
 //#region src/social-providers/facebook.ts
 const facebook = (options) => {
 	return {

package/dist/social-providers/google.mjs

@@ -3,8 +3,8 @@ import { APIError, BetterAuthError } from "../error/index.mjs";
 import { createAuthorizationURL } from "../oauth2/create-authorization-url.mjs";
 import { refreshAccessToken } from "../oauth2/refresh-access-token.mjs";
 import { validateAuthorizationCode } from "../oauth2/validate-authorization-code.mjs";
-import { betterFetch } from "@better-fetch/fetch";
 import { decodeJwt, decodeProtectedHeader, importJWK, jwtVerify } from "jose";
+import { betterFetch } from "@better-fetch/fetch";
 //#region src/social-providers/google.ts
 const google = (options) => {
 	return {

package/dist/social-providers/line.mjs

@@ -1,8 +1,8 @@
 import { createAuthorizationURL } from "../oauth2/create-authorization-url.mjs";
 import { refreshAccessToken } from "../oauth2/refresh-access-token.mjs";
 import { validateAuthorizationCode } from "../oauth2/validate-authorization-code.mjs";
-import { betterFetch } from "@better-fetch/fetch";
 import { decodeJwt } from "jose";
+import { betterFetch } from "@better-fetch/fetch";
 //#region src/social-providers/line.ts
 /**
 * LINE Login v2.1

package/dist/social-providers/microsoft-entra-id.mjs

@@ -3,9 +3,9 @@ import { APIError } from "../error/index.mjs";
 import { createAuthorizationURL } from "../oauth2/create-authorization-url.mjs";
 import { refreshAccessToken } from "../oauth2/refresh-access-token.mjs";
 import { validateAuthorizationCode } from "../oauth2/validate-authorization-code.mjs";
+import { decodeJwt, decodeProtectedHeader, importJWK, jwtVerify } from "jose";
 import { base64 } from "@better-auth/utils/base64";
 import { betterFetch } from "@better-fetch/fetch";
-import { decodeJwt, decodeProtectedHeader, importJWK, jwtVerify } from "jose";
 //#region src/social-providers/microsoft-entra-id.ts
 const microsoft = (options) => {
 	const tenant = options.tenantId || "common";

package/dist/social-providers/paypal.mjs

@@ -1,9 +1,9 @@
 import { logger } from "../env/logger.mjs";
 import { BetterAuthError } from "../error/index.mjs";
 import { createAuthorizationURL } from "../oauth2/create-authorization-url.mjs";
+import { decodeJwt } from "jose";
 import { base64 } from "@better-auth/utils/base64";
 import { betterFetch } from "@better-fetch/fetch";
-import { decodeJwt } from "jose";
 //#region src/social-providers/paypal.ts
 const paypal = (options) => {
 	const isSandbox = (options.environment || "sandbox") === "sandbox";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/core",
-  "version": "1.6.1",
+  "version": "1.7.0-beta.0",
   "description": "The most comprehensive authentication framework for TypeScript.",
   "type": "module",
   "license": "MIT",

package/src/oauth2/client-assertion.ts

@@ -0,0 +1,136 @@
+import type { JWTHeaderParameters } from "jose";
+import { importJWK, importPKCS8, SignJWT } from "jose";
+
+/** Asymmetric signing algorithms compatible with private_key_jwt (RFC 7523). */
+export const ASSERTION_SIGNING_ALGORITHMS = [
+	"RS256",
+	"RS384",
+	"RS512",
+	"PS256",
+	"PS384",
+	"PS512",
+	"ES256",
+	"ES384",
+	"ES512",
+	"EdDSA",
+] as const;
+
+export type AssertionSigningAlgorithm =
+	(typeof ASSERTION_SIGNING_ALGORITHMS)[number];
+
+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;
+	/** Private key in JWK format for signing. */
+	privateKeyJwk?: JsonWebKey;
+	/** Private key in PKCS#8 PEM format for signing. */
+	privateKeyPem?: string;
+	/** 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;
+	/** Assertion lifetime in seconds. @default 120 */
+	expiresIn?: number;
+}
+
+/**
+ * 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.
+ */
+export async function signClientAssertion({
+	clientId,
+	tokenEndpoint,
+	privateKeyJwk,
+	privateKeyPem,
+	kid,
+	algorithm,
+	expiresIn = 120,
+}: {
+	clientId: string;
+	tokenEndpoint: string;
+	privateKeyJwk?: JsonWebKey;
+	privateKeyPem?: string;
+	kid?: string;
+	algorithm?: AssertionSigningAlgorithm;
+	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 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 now = Math.floor(Date.now() / 1000);
+	const jti = crypto.randomUUID();
+
+	const header: JWTHeaderParameters = { alg: resolvedAlg, typ: "JWT" };
+	if (resolvedKid) header.kid = resolvedKid;
+
+	return new SignJWT({})
+		.setProtectedHeader(header)
+		.setIssuer(clientId)
+		.setSubject(clientId)
+		.setAudience(tokenEndpoint)
+		.setIssuedAt(now)
+		.setExpirationTime(now + expiresIn)
+		.setJti(jti)
+		.sign(key);
+}
+
+/**
+ * Resolves a ClientAssertionConfig into `client_assertion` + `client_assertion_type`
+ * params for injection into a token request body.
+ */
+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({
+			clientId,
+			tokenEndpoint: audEndpoint,
+			privateKeyJwk: clientAssertion.privateKeyJwk,
+			privateKeyPem: clientAssertion.privateKeyPem,
+			kid: clientAssertion.kid,
+			algorithm: clientAssertion.algorithm,
+			expiresIn: clientAssertion.expiresIn,
+		});
+	}
+	return {
+		client_assertion: assertion,
+		client_assertion_type: CLIENT_ASSERTION_TYPE,
+	};
+}

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

@@ -1,25 +1,51 @@
-import { base64Url } from "@better-auth/utils/base64";
+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";
 
 export async function clientCredentialsTokenRequest({
 	options,
 	scope,
 	authentication,
+	clientAssertion,
+	tokenEndpoint,
 	resource,
 }: {
-	options: AwaitableFunction<ProviderOptions & { clientSecret: string }>;
+	options: AwaitableFunction<ProviderOptions>;
 	scope?: string | undefined;
-	authentication?: ("basic" | "post") | 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;
 }) {
 	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({
 		options,
 		scope,
 		authentication,
 		resource,
+		extraParams,
 	});
 }
 
@@ -31,11 +57,13 @@ export function createClientCredentialsTokenRequest({
 	scope,
 	authentication,
 	resource,
+	extraParams,
 }: {
-	options: ProviderOptions & { clientSecret: string };
+	options: ProviderOptions;
 	scope?: string | undefined;
-	authentication?: ("basic" | "post") | undefined;
+	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
 	resource?: (string | string[]) | undefined;
+	extraParams?: Record<string, string> | undefined;
 }) {
 	const body = new URLSearchParams();
 	const headers: Record<string, any> = {
@@ -54,20 +82,25 @@ export function createClientCredentialsTokenRequest({
 			}
 		}
 	}
+	const primaryClientId = Array.isArray(options.clientId)
+		? options.clientId[0]
+		: options.clientId;
 	if (authentication === "basic") {
-		const primaryClientId = Array.isArray(options.clientId)
-			? options.clientId[0]
-			: options.clientId;
-		const encodedCredentials = base64Url.encode(
-			`${primaryClientId}:${options.clientSecret}`,
+		const encodedCredentials = base64.encode(
+			`${primaryClientId}:${options.clientSecret ?? ""}`,
 		);
 		headers["authorization"] = `Basic ${encodedCredentials}`;
 	} else {
-		const primaryClientId = Array.isArray(options.clientId)
-			? options.clientId[0]
-			: options.clientId;
 		body.set("client_id", primaryClientId);
-		body.set("client_secret", options.clientSecret);
+		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);
+		}
 	}
 
 	return {
@@ -81,18 +114,22 @@ export async function clientCredentialsToken({
 	tokenEndpoint,
 	scope,
 	authentication,
+	clientAssertion,
 	resource,
 }: {
-	options: AwaitableFunction<ProviderOptions & { clientSecret: string }>;
+	options: AwaitableFunction<ProviderOptions>;
 	tokenEndpoint: string;
 	scope: string;
-	authentication?: ("basic" | "post") | undefined;
+	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
+	clientAssertion?: ClientAssertionConfig | undefined;
 	resource?: (string | string[]) | undefined;
 }): Promise<OAuth2Tokens> {
 	const { body, headers } = await clientCredentialsTokenRequest({
 		options,
 		scope,
 		authentication,
+		clientAssertion,
+		tokenEndpoint,
 		resource,
 	});
 

package/src/oauth2/index.ts

@@ -1,3 +1,13 @@
+export type {
+	AssertionSigningAlgorithm,
+	ClientAssertionConfig,
+} from "./client-assertion";
+export {
+	ASSERTION_SIGNING_ALGORITHMS,
+	CLIENT_ASSERTION_TYPE,
+	resolveAssertionParams,
+	signClientAssertion,
+} from "./client-assertion";
 export {
 	clientCredentialsToken,
 	clientCredentialsTokenRequest,

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

@@ -1,22 +1,47 @@
 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";
 
 export async function refreshAccessTokenRequest({
 	refreshToken,
 	options,
 	authentication,
+	clientAssertion,
+	tokenEndpoint,
 	extraParams,
 	resource,
 }: {
 	refreshToken: string;
 	options: AwaitableFunction<Partial<ProviderOptions>>;
-	authentication?: ("basic" | "post") | 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;
 	extraParams?: Record<string, string> | undefined;
 	resource?: (string | string[]) | undefined;
 }) {
 	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({
 		refreshToken,
 		options,
@@ -38,7 +63,7 @@ export function createRefreshAccessTokenRequest({
 }: {
 	refreshToken: string;
 	options: ProviderOptions;
-	authentication?: ("basic" | "post") | undefined;
+	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
 	extraParams?: Record<string, string> | undefined;
 	resource?: (string | string[]) | undefined;
 }) {
@@ -50,12 +75,10 @@ export function createRefreshAccessTokenRequest({
 
 	body.set("grant_type", "refresh_token");
 	body.set("refresh_token", refreshToken);
-	// Use standard Base64 encoding for HTTP Basic Auth (OAuth2 spec, RFC 7617)
-	// Fixes compatibility with providers like Notion, Twitter, etc.
+	const primaryClientId = Array.isArray(options.clientId)
+		? options.clientId[0]
+		: options.clientId;
 	if (authentication === "basic") {
-		const primaryClientId = Array.isArray(options.clientId)
-			? options.clientId[0]
-			: options.clientId;
 		if (primaryClientId) {
 			headers["authorization"] =
 				"Basic " +
@@ -65,11 +88,8 @@ export function createRefreshAccessTokenRequest({
 				"Basic " + base64.encode(`:${options.clientSecret ?? ""}`);
 		}
 	} else {
-		const primaryClientId = Array.isArray(options.clientId)
-			? options.clientId[0]
-			: options.clientId;
 		body.set("client_id", primaryClientId);
-		if (options.clientSecret) {
+		if (authentication !== "private_key_jwt" && options.clientSecret) {
 			body.set("client_secret", options.clientSecret);
 		}
 	}
@@ -100,18 +120,22 @@ export async function refreshAccessToken({
 	options,
 	tokenEndpoint,
 	authentication,
+	clientAssertion,
 	extraParams,
 }: {
 	refreshToken: string;
 	options: Partial<ProviderOptions>;
 	tokenEndpoint: string;
-	authentication?: ("basic" | "post") | undefined;
+	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
+	clientAssertion?: ClientAssertionConfig | undefined;
 	extraParams?: Record<string, string> | undefined;
 }): Promise<OAuth2Tokens> {
-	const { body, headers } = await createRefreshAccessTokenRequest({
+	const { body, headers } = await refreshAccessTokenRequest({
 		refreshToken,
 		options,
 		authentication,
+		clientAssertion,
+		tokenEndpoint,
 		extraParams,
 	});
 

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

@@ -2,6 +2,8 @@ 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";
 
@@ -11,6 +13,8 @@ export async function authorizationCodeRequest({
 	redirectURI,
 	options,
 	authentication,
+	clientAssertion,
+	tokenEndpoint,
 	deviceId,
 	headers,
 	additionalParams = {},
@@ -21,12 +25,33 @@ export async function authorizationCodeRequest({
 	options: AwaitableFunction<Partial<ProviderOptions>>;
 	codeVerifier?: string | undefined;
 	deviceId?: string | undefined;
-	authentication?: ("basic" | "post") | 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;
 }) {
 	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({
 		code,
 		codeVerifier,
@@ -59,7 +84,7 @@ export function createAuthorizationCodeRequest({
 	options: Partial<ProviderOptions>;
 	codeVerifier?: string | undefined;
 	deviceId?: string | undefined;
-	authentication?: ("basic" | "post") | undefined;
+	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
 	headers?: Record<string, string> | undefined;
 	additionalParams?: Record<string, string> | undefined;
 	resource?: (string | string[]) | undefined;
@@ -86,22 +111,17 @@ export function createAuthorizationCodeRequest({
 			}
 		}
 	}
-	// Use standard Base64 encoding for HTTP Basic Auth (OAuth2 spec, RFC 7617)
-	// Fixes compatibility with providers like Notion, Twitter, etc.
+	const primaryClientId = Array.isArray(options.clientId)
+		? options.clientId[0]
+		: options.clientId;
 	if (authentication === "basic") {
-		const primaryClientId = Array.isArray(options.clientId)
-			? options.clientId[0]
-			: options.clientId;
 		const encodedCredentials = base64.encode(
 			`${primaryClientId}:${options.clientSecret ?? ""}`,
 		);
 		requestHeaders["authorization"] = `Basic ${encodedCredentials}`;
 	} else {
-		const primaryClientId = Array.isArray(options.clientId)
-			? options.clientId[0]
-			: options.clientId;
 		body.set("client_id", primaryClientId);
-		if (options.clientSecret) {
+		if (authentication !== "private_key_jwt" && options.clientSecret) {
 			body.set("client_secret", options.clientSecret);
 		}
 	}
@@ -123,6 +143,7 @@ export async function validateAuthorizationCode({
 	options,
 	tokenEndpoint,
 	authentication,
+	clientAssertion,
 	deviceId,
 	headers,
 	additionalParams = {},
@@ -134,7 +155,8 @@ export async function validateAuthorizationCode({
 	codeVerifier?: string | undefined;
 	deviceId?: string | undefined;
 	tokenEndpoint: string;
-	authentication?: ("basic" | "post") | undefined;
+	authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
+	clientAssertion?: ClientAssertionConfig | undefined;
 	headers?: Record<string, string> | undefined;
 	additionalParams?: Record<string, string> | undefined;
 	resource?: (string | string[]) | undefined;
@@ -145,6 +167,8 @@ export async function validateAuthorizationCode({
 		redirectURI,
 		options,
 		authentication,
+		clientAssertion,
+		tokenEndpoint,
 		deviceId,
 		headers,
 		additionalParams,