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

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

@@ -1,30 +1,25 @@
-import { resolveAssertionParams } from "./client-assertion.mjs";
-import { base64 } from "@better-auth/utils/base64";
+import { applyTokenEndpointAuth } from "./token-endpoint-auth.mjs";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/oauth2/client-credentials-token.ts
-async function clientCredentialsTokenRequest({ options, scope, authentication, clientAssertion, tokenEndpoint, resource }) {
+async function clientCredentialsTokenRequest({ options, scope, authentication, tokenEndpointAuth, 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({
+	const request = buildClientCredentialsTokenRequest({
 		options,
 		scope,
-		authentication,
-		resource,
-		extraParams
+		resource
 	});
+	await applyTokenEndpointAuth({
+		body: request.body,
+		headers: request.headers,
+		options,
+		tokenEndpoint: tokenEndpoint ?? "",
+		grantType: "client_credentials",
+		tokenEndpointAuth,
+		authentication
+	});
+	return request;
 }
-/**
-* @deprecated use async'd clientCredentialsTokenRequest instead
-*/
-function createClientCredentialsTokenRequest({ options, scope, authentication, resource, extraParams }) {
+function buildClientCredentialsTokenRequest({ options, scope, resource, extraParams }) {
 	const body = new URLSearchParams();
 	const headers = {
 		"content-type": "application/x-www-form-urlencoded",
@@ -34,12 +29,6 @@ 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);
-	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);
-		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);
 	}
@@ -48,12 +37,12 @@ function createClientCredentialsTokenRequest({ options, scope, authentication, r
 		headers
 	};
 }
-async function clientCredentialsToken({ options, tokenEndpoint, scope, authentication, clientAssertion, resource }) {
+async function clientCredentialsToken({ options, tokenEndpoint, scope, authentication, tokenEndpointAuth, resource }) {
 	const { body, headers } = await clientCredentialsTokenRequest({
 		options,
 		scope,
 		authentication,
-		clientAssertion,
+		tokenEndpointAuth,
 		tokenEndpoint,
 		resource
 	});
@@ -75,4 +64,4 @@ async function clientCredentialsToken({ options, tokenEndpoint, scope, authentic
 	return tokens;
 }
 //#endregion
-export { clientCredentialsToken, clientCredentialsTokenRequest, createClientCredentialsTokenRequest };
+export { clientCredentialsToken, clientCredentialsTokenRequest };

package/dist/oauth2/create-authorization-url.d.mts

@@ -1,6 +1,14 @@
 import { AwaitableFunction } from "../types/helper.mjs";
 import { ProviderOptions } from "./oauth-provider.mjs";
 //#region src/oauth2/create-authorization-url.d.ts
+/**
+ * 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.
+ */
+declare const RESERVED_AUTHORIZATION_PARAMS: readonly ["state", "client_id", "redirect_uri", "response_type", "code_challenge", "code_challenge_method", "scope"];
+declare const RESERVED_AUTHORIZATION_PARAMS_SET: ReadonlySet<string>;
 declare function createAuthorizationURL({
   id,
   options,
@@ -41,4 +49,4 @@ declare function createAuthorizationURL({
   scopeJoiner?: string | undefined;
 }): Promise<URL>;
 //#endregion
-export { createAuthorizationURL };
+export { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL };

package/dist/oauth2/create-authorization-url.mjs

@@ -1,10 +1,27 @@
-import { generateCodeChallenge } from "./utils.mjs";
+import { generateCodeChallenge, getPrimaryClientId } from "./utils.mjs";
 //#region src/oauth2/create-authorization-url.ts
+/**
+* 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.
+*/
+const RESERVED_AUTHORIZATION_PARAMS = [
+	"state",
+	"client_id",
+	"redirect_uri",
+	"response_type",
+	"code_challenge",
+	"code_challenge_method",
+	"scope"
+];
+const RESERVED_AUTHORIZATION_PARAMS_SET = new Set(RESERVED_AUTHORIZATION_PARAMS);
 async function createAuthorizationURL({ id, options, authorizationEndpoint, state, codeVerifier, scopes, claims, redirectURI, duration, prompt, accessType, responseType, display, loginHint, hd, responseMode, additionalParams, scopeJoiner }) {
 	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) url.searchParams.set("scope", scopes.join(scopeJoiner || " "));
@@ -32,10 +49,11 @@ async function createAuthorizationURL({ id, options, authorizationEndpoint, stat
 			...claimsObj
 		} }));
 	}
-	if (additionalParams) Object.entries(additionalParams).forEach(([key, value]) => {
+	if (additionalParams) for (const [key, value] of Object.entries(additionalParams)) {
+		if (RESERVED_AUTHORIZATION_PARAMS_SET.has(key)) continue;
 		url.searchParams.set(key, value);
-	});
+	}
 	return url;
 }
 //#endregion
-export { createAuthorizationURL };
+export { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL };

package/dist/oauth2/index.d.mts

@@ -1,9 +1,12 @@
-import { ASSERTION_SIGNING_ALGORITHMS, AssertionSigningAlgorithm, CLIENT_ASSERTION_TYPE, ClientAssertionConfig, resolveAssertionParams, signClientAssertion } from "./client-assertion.mjs";
+import { additionalAuthorizationParamsSchema } from "./authorization-params.mjs";
+import { decodeBasicCredentials, encodeBasicCredentials } from "./basic-credentials.mjs";
+import { CLIENT_ASSERTION_TYPE, ClientAssertionContext, ClientAssertionGetter, ClientAssertionGrantType, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, PrivateKeyJwtClientAssertionGetterOptions, PrivateKeyJwtSigningAlgorithm, createPrivateKeyJwtClientAssertionGetter, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion } 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";
-import { createRefreshAccessTokenRequest, refreshAccessToken, refreshAccessTokenRequest } from "./refresh-access-token.mjs";
-import { generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId } from "./utils.mjs";
-import { authorizationCodeRequest, createAuthorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
+import { TokenEndpointAuth, TokenEndpointAuthMethod, TokenEndpointSecretAuthentication } from "./token-endpoint-auth.mjs";
+import { clientCredentialsToken, clientCredentialsTokenRequest } from "./client-credentials-token.mjs";
+import { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL } from "./create-authorization-url.mjs";
+import { refreshAccessToken, refreshAccessTokenRequest } from "./refresh-access-token.mjs";
+import { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId } from "./utils.mjs";
+import { authorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
 import { getJwks, verifyAccessToken, verifyJwsAccessToken } from "./verify.mjs";
-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, getPrimaryClientId, refreshAccessToken, refreshAccessTokenRequest, resolveAssertionParams, signClientAssertion, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };
+export { CLIENT_ASSERTION_TYPE, type ClientAssertionContext, type ClientAssertionGetter, type ClientAssertionGrantType, type OAuth2Tokens, type OAuth2UserInfo, type OAuthProvider, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, type PrivateKeyJwtClientAssertionGetterOptions, type PrivateKeyJwtSigningAlgorithm, type ProviderOptions, RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, type TokenEndpointAuth, type TokenEndpointAuthMethod, type TokenEndpointSecretAuthentication, additionalAuthorizationParamsSchema, applyDefaultAccessTokenExpiry, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationURL, createPrivateKeyJwtClientAssertionGetter, decodeBasicCredentials, encodeBasicCredentials, generateCodeChallenge, getJwks, getOAuth2Tokens, getPrimaryClientId, refreshAccessToken, refreshAccessTokenRequest, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };

package/dist/oauth2/index.mjs

@@ -1,8 +1,10 @@
-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, getPrimaryClientId } 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 { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId } from "./utils.mjs";
+import { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, createAuthorizationURL } from "./create-authorization-url.mjs";
+import { additionalAuthorizationParamsSchema } from "./authorization-params.mjs";
+import { decodeBasicCredentials, encodeBasicCredentials } from "./basic-credentials.mjs";
+import { CLIENT_ASSERTION_TYPE, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, createPrivateKeyJwtClientAssertionGetter, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion } from "./client-assertion.mjs";
+import { clientCredentialsToken, clientCredentialsTokenRequest } from "./client-credentials-token.mjs";
+import { refreshAccessToken, refreshAccessTokenRequest } from "./refresh-access-token.mjs";
+import { authorizationCodeRequest, validateAuthorizationCode, validateToken } from "./validate-authorization-code.mjs";
 import { getJwks, verifyAccessToken, verifyJwsAccessToken } from "./verify.mjs";
-export { ASSERTION_SIGNING_ALGORITHMS, CLIENT_ASSERTION_TYPE, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationCodeRequest, createAuthorizationURL, createClientCredentialsTokenRequest, createRefreshAccessTokenRequest, generateCodeChallenge, getJwks, getOAuth2Tokens, getPrimaryClientId, refreshAccessToken, refreshAccessTokenRequest, resolveAssertionParams, signClientAssertion, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };
+export { CLIENT_ASSERTION_TYPE, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET, additionalAuthorizationParamsSchema, applyDefaultAccessTokenExpiry, authorizationCodeRequest, clientCredentialsToken, clientCredentialsTokenRequest, createAuthorizationURL, createPrivateKeyJwtClientAssertionGetter, decodeBasicCredentials, encodeBasicCredentials, generateCodeChallenge, getJwks, getOAuth2Tokens, getPrimaryClientId, refreshAccessToken, refreshAccessTokenRequest, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion, validateAuthorizationCode, validateToken, verifyAccessToken, verifyJwsAccessToken };

package/dist/oauth2/oauth-provider.d.mts

@@ -30,6 +30,13 @@ interface OAuthProvider<T extends Record<string, any> = Record<string, any>, O e
     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: {
@@ -81,6 +88,17 @@ interface OAuthProvider<T extends Record<string, any> = Record<string, any>, O e
    * 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
    */
@@ -90,9 +108,10 @@ 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/dist/oauth2/refresh-access-token.d.mts

@@ -1,61 +1,41 @@
-import { ClientAssertionConfig } from "./client-assertion.mjs";
 import { AwaitableFunction } from "../types/helper.mjs";
 import { OAuth2Tokens, ProviderOptions } from "./oauth-provider.mjs";
+import { TokenEndpointAuth, TokenEndpointSecretAuthentication } from "./token-endpoint-auth.mjs";
 
 //#region src/oauth2/refresh-access-token.d.ts
-declare function refreshAccessTokenRequest({
-  refreshToken,
-  options,
-  authentication,
-  clientAssertion,
-  tokenEndpoint,
-  extraParams,
-  resource
-}: {
+interface RefreshAccessTokenRequestInput {
   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. */
+  authentication?: TokenEndpointSecretAuthentication | undefined;
+  tokenEndpointAuth?: TokenEndpointAuth | undefined;
   tokenEndpoint?: string | undefined;
   extraParams?: Record<string, string> | undefined;
   resource?: (string | string[]) | undefined;
-}): Promise<{
-  body: URLSearchParams;
-  headers: Record<string, any>;
-}>;
-/**
- * @deprecated use async'd refreshAccessTokenRequest instead
- */
-declare function createRefreshAccessTokenRequest({
+}
+interface RefreshAccessTokenInput extends RefreshAccessTokenRequestInput {
+  options: Partial<ProviderOptions>;
+  tokenEndpoint: string;
+}
+declare function refreshAccessTokenRequest({
   refreshToken,
   options,
   authentication,
+  tokenEndpointAuth,
+  tokenEndpoint,
   extraParams,
   resource
-}: {
-  refreshToken: string;
-  options: ProviderOptions;
-  authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
-  extraParams?: Record<string, string> | undefined;
-  resource?: (string | string[]) | undefined;
-}): {
+}: RefreshAccessTokenRequestInput): Promise<{
   body: URLSearchParams;
-  headers: Record<string, any>;
-};
+  headers: Record<string, string>;
+}>;
 declare function refreshAccessToken({
   refreshToken,
   options,
   tokenEndpoint,
   authentication,
-  clientAssertion,
-  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>;
+  tokenEndpointAuth,
+  extraParams,
+  resource
+}: RefreshAccessTokenInput): Promise<OAuth2Tokens>;
 //#endregion
-export { createRefreshAccessTokenRequest, refreshAccessToken, refreshAccessTokenRequest };
+export { refreshAccessToken, refreshAccessTokenRequest };

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

@@ -1,33 +1,26 @@
-import { resolveAssertionParams } from "./client-assertion.mjs";
-import { base64 } from "@better-auth/utils/base64";
+import { applyTokenEndpointAuth } from "./token-endpoint-auth.mjs";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/oauth2/refresh-access-token.ts
-async function refreshAccessTokenRequest({ refreshToken, options, authentication, clientAssertion, tokenEndpoint, extraParams, resource }) {
+async function refreshAccessTokenRequest({ refreshToken, options, authentication, tokenEndpointAuth, 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({
+	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
-*/
-function createRefreshAccessTokenRequest({ refreshToken, options, authentication, extraParams, resource }) {
+function buildRefreshAccessTokenRequest({ refreshToken, options, extraParams, resource }) {
 	const body = new URLSearchParams();
 	const headers = {
 		"content-type": "application/x-www-form-urlencoded",
@@ -35,13 +28,6 @@ function createRefreshAccessTokenRequest({ refreshToken, options, authentication
 	};
 	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);
 	else for (const _resource of resource) body.append("resource", _resource);
 	if (extraParams) for (const [key, value] of Object.entries(extraParams)) body.set(key, value);
@@ -50,14 +36,15 @@ function createRefreshAccessTokenRequest({ refreshToken, options, authentication
 		headers
 	};
 }
-async function refreshAccessToken({ refreshToken, options, tokenEndpoint, authentication, clientAssertion, extraParams }) {
+async function refreshAccessToken({ refreshToken, options, tokenEndpoint, authentication, tokenEndpointAuth, extraParams, resource }) {
 	const { body, headers } = await refreshAccessTokenRequest({
 		refreshToken,
 		options,
 		authentication,
-		clientAssertion,
+		tokenEndpointAuth,
 		tokenEndpoint,
-		extraParams
+		extraParams,
+		resource
 	});
 	const { data, error } = await betterFetch(tokenEndpoint, {
 		method: "POST",
@@ -83,4 +70,4 @@ async function refreshAccessToken({ refreshToken, options, tokenEndpoint, authen
 	return tokens;
 }
 //#endregion
-export { createRefreshAccessTokenRequest, refreshAccessToken, refreshAccessTokenRequest };
+export { refreshAccessToken, refreshAccessTokenRequest };

package/dist/oauth2/token-endpoint-auth.d.mts

@@ -0,0 +1,17 @@
+import { ClientAssertionGetter } from "./client-assertion.mjs";
+
+//#region src/oauth2/token-endpoint-auth.d.ts
+type TokenEndpointAuth = {
+  method: "none";
+} | {
+  method: "client_secret_basic";
+} | {
+  method: "client_secret_post";
+} | {
+  method: "private_key_jwt";
+  getClientAssertion: ClientAssertionGetter;
+};
+type TokenEndpointAuthMethod = TokenEndpointAuth["method"];
+type TokenEndpointSecretAuthentication = "basic" | "post";
+//#endregion
+export { TokenEndpointAuth, TokenEndpointAuthMethod, TokenEndpointSecretAuthentication };

package/dist/oauth2/token-endpoint-auth.mjs

@@ -0,0 +1,89 @@
+import { getPrimaryClientId } from "./utils.mjs";
+import { encodeBasicCredentials } from "./basic-credentials.mjs";
+import { resolveClientAssertionParams } from "./client-assertion.mjs";
+//#region src/oauth2/token-endpoint-auth.ts
+function getDefaultTokenEndpointAuth(options, authentication) {
+	if (authentication === "basic") return { method: "client_secret_basic" };
+	if (options.clientSecret) return { method: "client_secret_post" };
+	return { method: "none" };
+}
+function assertNoClientSecret(method, options, body) {
+	if (options.clientSecret || body.has("client_secret")) throw new Error(`${method} token endpoint authentication cannot be combined with clientSecret`);
+}
+function setClientId(body, clientId) {
+	if (clientId) body.set("client_id", clientId);
+}
+function assertClientSecretConfigured(method, options) {
+	if (!options.clientSecret) throw new Error(`${method} token endpoint authentication requires clientSecret`);
+}
+function assertClientIdConfigured(method, clientId) {
+	if (!clientId) throw new Error(`${method} token endpoint authentication requires clientId`);
+}
+function setClientSecretPostAuth({ body, options, clientId, requireClientSecret }) {
+	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 }) {
+	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) {
+	if (body.has("client_assertion") !== body.has("client_assertion_type")) throw new Error("client_assertion and client_assertion_type must both be provided");
+}
+async function applyTokenEndpointAuth({ body, headers, options, tokenEndpoint, grantType, tokenEndpointAuth, authentication }) {
+	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"
+	});
+}
+//#endregion
+export { applyTokenEndpointAuth };

package/dist/oauth2/utils.d.mts

@@ -2,6 +2,14 @@ import { OAuth2Tokens } from "./oauth-provider.mjs";
 
 //#region src/oauth2/utils.d.ts
 declare 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.
+ */
+declare function applyDefaultAccessTokenExpiry(tokens: OAuth2Tokens, accessTokenExpiresIn: number | undefined): OAuth2Tokens;
 /**
  * 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
@@ -13,4 +21,4 @@ declare function getOAuth2Tokens(data: Record<string, any>): OAuth2Tokens;
 declare function getPrimaryClientId(clientId: unknown): string | undefined;
 declare function generateCodeChallenge(codeVerifier: string): Promise<string>;
 //#endregion
-export { generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId };
+export { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId };

package/dist/oauth2/utils.mjs

@@ -17,6 +17,17 @@ function getOAuth2Tokens(data) {
 	};
 }
 /**
+* 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.
+*/
+function applyDefaultAccessTokenExpiry(tokens, accessTokenExpiresIn) {
+	if (!tokens.accessTokenExpiresAt && accessTokenExpiresIn) tokens.accessTokenExpiresAt = new Date(Date.now() + accessTokenExpiresIn * 1e3);
+	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
 * verification. Index 0 is the designated primary and pairs with
@@ -34,4 +45,4 @@ async function generateCodeChallenge(codeVerifier) {
 	return base64Url.encode(new Uint8Array(hash), { padding: false });
 }
 //#endregion
-export { generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId };
+export { applyDefaultAccessTokenExpiry, generateCodeChallenge, getOAuth2Tokens, getPrimaryClientId };