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

package/dist/context/global.mjs

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

package/dist/db/adapter/factory.mjs

@@ -1,9 +1,7 @@
 import { BetterAuthError } from "../../error/index.mjs";
-import { getAuthTables } from "../get-tables.mjs";
 import { getColorDepth } from "../../env/color-depth.mjs";
 import { TTY_COLORS, createLogger } from "../../env/logger.mjs";
-import { ATTR_DB_COLLECTION_NAME, ATTR_DB_OPERATION_NAME } from "../../instrumentation/attributes.mjs";
-import { withSpan } from "../../instrumentation/tracer.mjs";
+import { getAuthTables } from "../get-tables.mjs";
 import { safeJSONParse } from "../../utils/json.mjs";
 import { initGetDefaultModelName } from "./get-default-model-name.mjs";
 import { initGetDefaultFieldName } from "./get-default-field-name.mjs";
@@ -12,6 +10,7 @@ import { initGetFieldAttributes } from "./get-field-attributes.mjs";
 import { initGetFieldName } from "./get-field-name.mjs";
 import { initGetModelName } from "./get-model-name.mjs";
 import { withApplyDefault } from "./utils.mjs";
+import { ATTR_DB_COLLECTION_NAME, ATTR_DB_OPERATION_NAME, withSpan } from "@better-auth/core/instrumentation";
 //#region src/db/adapter/factory.ts
 let debugLogs = [];
 let transactionId = -1;
@@ -58,6 +57,7 @@ const createAdapterFactory = ({ adapter: customAdapter, config: cfg }) => (optio
 					else if (method === "findMany" && !config.debugLogs.findMany) return;
 					else if (method === "delete" && !config.debugLogs.delete) return;
 					else if (method === "deleteMany" && !config.debugLogs.deleteMany) return;
+					else if (method === "consumeOne" && !config.debugLogs.consumeOne) return;
 					else if (method === "count" && !config.debugLogs.count) return;
 				}
 				logger.info(`[${config.adapterName}]`, ...args);
@@ -677,6 +677,67 @@ const createAdapterFactory = ({ adapter: customAdapter, config: cfg }) => (optio
 			});
 			return res;
 		},
+		consumeOne: async ({ model: unsafeModel, where: unsafeWhere }) => {
+			transactionId++;
+			const thisTransactionId = transactionId;
+			const model = getModelName(unsafeModel);
+			const where = transformWhereClause({
+				model: unsafeModel,
+				where: unsafeWhere,
+				action: "consumeOne"
+			});
+			unsafeModel = getDefaultModelName(unsafeModel);
+			debugLog({ method: "consumeOne" }, `${formatTransactionId(thisTransactionId)} ${formatStep(1, 3)}`, `${formatMethod("consumeOne")} ${formatAction("ConsumeOne")}:`, {
+				model,
+				where
+			});
+			let res;
+			let resultNeedsOutputTransform = true;
+			if (adapterInstance.consumeOne) res = await withSpan(`db consumeOne ${model}`, {
+				[ATTR_DB_OPERATION_NAME]: "consumeOne",
+				[ATTR_DB_COLLECTION_NAME]: model
+			}, () => adapterInstance.consumeOne({
+				model,
+				where
+			}));
+			else {
+				res = await withSpan(`db consumeOne ${model}`, {
+					[ATTR_DB_OPERATION_NAME]: "consumeOne",
+					[ATTR_DB_COLLECTION_NAME]: model
+				}, () => adapter.transaction(async (trx) => {
+					const target = (await trx.findMany({
+						model: unsafeModel,
+						where: unsafeWhere,
+						limit: 1
+					}))[0];
+					if (!target) return null;
+					const deleted = await trx.deleteMany({
+						model: unsafeModel,
+						where: [...unsafeWhere, {
+							field: "id",
+							value: target.id,
+							operator: "eq",
+							connector: "AND",
+							mode: "sensitive"
+						}]
+					});
+					if (typeof deleted !== "number") throw new BetterAuthError(`Adapter "${config.adapterId}" returned a non-numeric value from deleteMany during the consumeOne fallback. Return the number of deleted rows, or implement a native consumeOne for atomic single-use consumption.`);
+					return deleted > 0 ? target : null;
+				}));
+				resultNeedsOutputTransform = false;
+			}
+			debugLog({ method: "consumeOne" }, `${formatTransactionId(thisTransactionId)} ${formatStep(2, 3)}`, `${formatMethod("consumeOne")} ${formatAction("DB Result")}:`, {
+				model,
+				data: res
+			});
+			let transformed = res;
+			if (!config.disableTransformOutput && resultNeedsOutputTransform && res) transformed = await transformOutput(res, unsafeModel, void 0, void 0);
+			debugLog({ method: "consumeOne" }, `${formatTransactionId(thisTransactionId)} ${formatStep(3, 3)}`, `${formatMethod("consumeOne")} ${formatAction("Parsed Result")}:`, {
+				model,
+				data: transformed
+			});
+			return transformed;
+		},
 		count: async ({ model: unsafeModel, where: unsafeWhere }) => {
 			transactionId++;
 			const thisTransactionId = transactionId;

package/dist/db/adapter/index.d.mts

@@ -22,6 +22,7 @@ type DBAdapterDebugLogOption = boolean | {
   findMany?: boolean | undefined;
   delete?: boolean | undefined;
   deleteMany?: boolean | undefined;
+  consumeOne?: boolean | undefined;
   count?: boolean | undefined;
 } | {
   /**
@@ -197,7 +198,7 @@ interface DBAdapterFactoryConfig<Options extends BetterAuthOptions = BetterAuthO
     /**
      * The action which was called from the adapter.
      */
-    action: "create" | "update" | "findOne" | "findMany" | "updateMany" | "delete" | "deleteMany" | "count";
+    action: "create" | "update" | "findOne" | "findMany" | "updateMany" | "delete" | "deleteMany" | "consumeOne" | "count";
     /**
      * The model name.
      */
@@ -415,6 +416,26 @@ type DBAdapter<Options extends BetterAuthOptions = BetterAuthOptions> = {
     model: string;
     where: Where[];
   }) => Promise<number>;
+  /**
+   * Atomically consume a single row matching the where clause: delete it and
+   * return the deleted row, or return `null` if no row matched.
+   * Implementations MUST NOT delete any additional rows that also match a
+   * non-unique predicate.
+   *
+   * Under concurrent invocation against the same row, exactly one caller
+   * receives the row; subsequent racers receive `null`. This is the
+   * race-safe primitive for consuming single-use credentials
+   * (verification tokens, authorization codes, one-time tokens).
+   *
+   * Always defined on the factory-wrapped adapter. When the underlying
+   * `CustomAdapter` does not implement `consumeOne`, the factory provides
+   * a fallback that wraps `findMany + deleteMany` in `transaction(...)`
+   * and returns the row only when the delete reports an affected row.
+   */
+  consumeOne: <T>(data: {
+    model: string;
+    where: Where[];
+  }) => Promise<T | null>;
   /**
    * Execute multiple operations in a transaction.
    * If the adapter doesn't support transactions, operations will be executed sequentially.
@@ -496,6 +517,19 @@ interface CustomAdapter {
     model: string;
     where: CleanedWhere[];
   }) => Promise<number>;
+  /**
+   * Optional native atomic single-row consume. When omitted, the adapter
+   * factory falls back to `transaction(findMany + deleteMany)`.
+   * Implementing this method natively (e.g. `DELETE ... RETURNING *`,
+   * `findOneAndDelete`, `OUTPUT deleted.*`) gives one round trip and the
+   * strongest race-safety guarantee. Implementations must delete at most
+   * one matching row. TODO(consume-one-required): tighten to required in the
+   * next minor on `next`.
+   */
+  consumeOne?: <T>(data: {
+    model: string;
+    where: CleanedWhere[];
+  }) => Promise<T | null>;
   count: ({
     model,
     where

package/dist/db/adapter/types.d.mts

@@ -94,7 +94,7 @@ type AdapterFactoryCustomizeAdapterCreator = (config: {
   }: {
     where: W;
     model: string;
-    action: "create" | "update" | "findOne" | "findMany" | "updateMany" | "delete" | "deleteMany" | "count";
+    action: "create" | "update" | "findOne" | "findMany" | "updateMany" | "delete" | "deleteMany" | "consumeOne" | "count";
   }) => W extends undefined ? undefined : CleanedWhere[];
 }) => CustomAdapter;
 type AdapterTestDebugLogs = {

package/dist/db/type.d.mts

@@ -141,6 +141,18 @@ 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/dist/error/codes.d.mts

@@ -36,6 +36,7 @@ declare const BASE_ERROR_CODES: {
   USER_ALREADY_EXISTS: RawError<"USER_ALREADY_EXISTS">;
   USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL: RawError<"USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL">;
   EMAIL_CAN_NOT_BE_UPDATED: RawError<"EMAIL_CAN_NOT_BE_UPDATED">;
+  CHANGE_EMAIL_DISABLED: RawError<"CHANGE_EMAIL_DISABLED">;
   CREDENTIAL_ACCOUNT_NOT_FOUND: RawError<"CREDENTIAL_ACCOUNT_NOT_FOUND">;
   ACCOUNT_NOT_FOUND: RawError<"ACCOUNT_NOT_FOUND">;
   SESSION_EXPIRED: RawError<"SESSION_EXPIRED">;

package/dist/error/codes.mjs

@@ -23,6 +23,7 @@ const BASE_ERROR_CODES = defineErrorCodes({
 	USER_ALREADY_EXISTS: "User already exists.",
 	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/dist/instrumentation/tracer.mjs

@@ -2,7 +2,7 @@ import { ATTR_HTTP_RESPONSE_STATUS_CODE } from "./attributes.mjs";
 import { getOpenTelemetryAPI } from "./api.mjs";
 //#region src/instrumentation/tracer.ts
 const INSTRUMENTATION_SCOPE = "better-auth";
-const INSTRUMENTATION_VERSION = "1.7.0-beta.2";
+const INSTRUMENTATION_VERSION = "1.7.0-beta.4";
 /**
 * 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/authorization-params.d.mts

@@ -0,0 +1,12 @@
+import * as z from "zod";
+
+//#region src/oauth2/authorization-params.d.ts
+/**
+ * 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.
+ */
+declare const additionalAuthorizationParamsSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+//#endregion
+export { additionalAuthorizationParamsSchema };

package/dist/oauth2/authorization-params.mjs

@@ -0,0 +1,12 @@
+import { RESERVED_AUTHORIZATION_PARAMS, RESERVED_AUTHORIZATION_PARAMS_SET } from "./create-authorization-url.mjs";
+import * as z from "zod";
+//#region src/oauth2/authorization-params.ts
+/**
+* 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.
+*/
+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();
+//#endregion
+export { additionalAuthorizationParamsSchema };

package/dist/oauth2/basic-credentials.d.mts

@@ -0,0 +1,30 @@
+//#region src/oauth2/basic-credentials.d.ts
+/**
+ * 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.
+ */
+declare function encodeBasicCredentials(clientId: string, clientSecret: string): string;
+/**
+ * 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.
+ */
+declare function decodeBasicCredentials(authorization: string): {
+  clientId: string;
+  clientSecret: string;
+};
+//#endregion
+export { decodeBasicCredentials, encodeBasicCredentials };

package/dist/oauth2/basic-credentials.mjs

@@ -0,0 +1,64 @@
+import { base64 } from "@better-auth/utils/base64";
+//#region src/oauth2/basic-credentials.ts
+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) {
+	return new URLSearchParams({ v: value }).toString().slice(2);
+}
+/**
+* Inverse of `formUrlEncode`: decodes a single `application/x-www-form-urlencoded`
+* value, handling both `+` and `%20` as space.
+*/
+function formUrlDecode(value) {
+	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.
+*/
+function encodeBasicCredentials(clientId, clientSecret) {
+	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.
+*/
+function decodeBasicCredentials(authorization) {
+	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)
+	};
+}
+//#endregion
+export { decodeBasicCredentials, encodeBasicCredentials };

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

@@ -1,11 +1,17 @@
+import { Awaitable } from "../types/helper.mjs";
 //#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 PRIVATE_KEY_JWT_SIGNING_ALGORITHMS: readonly ["RS256", "RS384", "RS512", "PS256", "PS384", "PS512", "ES256", "ES384", "ES512", "EdDSA"];
+type PrivateKeyJwtSigningAlgorithm = (typeof PRIVATE_KEY_JWT_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;
+type ClientAssertionGrantType = "authorization_code" | "refresh_token" | "client_credentials";
+interface ClientAssertionContext {
+  clientId: string;
+  tokenEndpoint: string;
+  grantType: ClientAssertionGrantType;
+}
+type ClientAssertionGetter = (context: ClientAssertionContext) => Awaitable<string>;
+interface PrivateKeyJwtClientAssertionGetterOptions {
   /** Private key in JWK format for signing. */
   privateKeyJwk?: JsonWebKey;
   /** Private key in PKCS#8 PEM format for signing. */
@@ -13,19 +19,23 @@ 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;
 }
 /**
  * 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
  */
-declare function signClientAssertion({
+declare function signPrivateKeyJwtClientAssertion({
   clientId,
   tokenEndpoint,
   privateKeyJwk,
@@ -39,21 +49,27 @@ declare function signClientAssertion({
   privateKeyJwk?: JsonWebKey;
   privateKeyPem?: string;
   kid?: string;
-  algorithm?: AssertionSigningAlgorithm;
+  algorithm?: PrivateKeyJwtSigningAlgorithm;
   expiresIn?: number;
 }): Promise<string>;
 /**
- * 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.
  */
-declare function resolveAssertionParams({
-  clientAssertion,
-  clientId,
-  tokenEndpoint
+declare function createPrivateKeyJwtClientAssertionGetter(options: PrivateKeyJwtClientAssertionGetterOptions): ClientAssertionGetter;
+/**
+ * Resolves a client assertion getter into `client_assertion` + `client_assertion_type` params for injection into a token request body.
+ */
+declare function resolveClientAssertionParams({
+  getClientAssertion,
+  context
 }: {
-  clientAssertion: ClientAssertionConfig;
-  clientId: string;
-  tokenEndpoint?: string;
+  getClientAssertion: ClientAssertionGetter;
+  context: ClientAssertionContext;
 }): Promise<Record<string, string>>;
 //#endregion
-export { ASSERTION_SIGNING_ALGORITHMS, AssertionSigningAlgorithm, CLIENT_ASSERTION_TYPE, ClientAssertionConfig, resolveAssertionParams, signClientAssertion };
+export { CLIENT_ASSERTION_TYPE, ClientAssertionContext, ClientAssertionGetter, ClientAssertionGrantType, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, PrivateKeyJwtClientAssertionGetterOptions, PrivateKeyJwtSigningAlgorithm, createPrivateKeyJwtClientAssertionGetter, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion };

package/dist/oauth2/client-assertion.mjs

@@ -1,7 +1,7 @@
 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 = [
+const PRIVATE_KEY_JWT_SIGNING_ALGORITHMS = [
 	"RS256",
 	"RS384",
 	"RS512",
@@ -13,20 +13,46 @@ const ASSERTION_SIGNING_ALGORITHMS = [
 	"ES512",
 	"EdDSA"
 ];
+function assertSupportedPrivateKeyJwtAlgorithm(candidate) {
+	if (!PRIVATE_KEY_JWT_SIGNING_ALGORITHMS.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) {
+	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");
+}
 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.
+* The JWT contains these claims:
+*
+* - iss=clientId
+* - sub=clientId
+* - aud=tokenEndpoint
+* - exp=now + 120s
+* - jti=unique
+* - iat=now
 */
-async function signClientAssertion({ clientId, tokenEndpoint, privateKeyJwk, privateKeyPem, kid, algorithm, expiresIn = 120 }) {
+async function signPrivateKeyJwtClientAssertion({ clientId, tokenEndpoint, privateKeyJwk, privateKeyPem, kid, algorithm, expiresIn = 120 }) {
+	const resolvedAlg = resolveValidPrivateKeyJwtOptions({
+		privateKeyJwk,
+		privateKeyPem,
+		algorithm
+	});
 	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 key = privateKeyJwk ? await importJWK(privateKeyJwk, resolvedAlg) : await importPKCS8(privateKeyPem, resolvedAlg);
 	const now = Math.floor(Date.now() / 1e3);
 	const jti = crypto.randomUUID();
 	const header = {
@@ -37,28 +63,37 @@ async function signClientAssertion({ clientId, tokenEndpoint, privateKeyJwk, pri
 	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.
+* 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.
+*/
+function createPrivateKeyJwtClientAssertionGetter(options) {
+	resolveValidPrivateKeyJwtOptions({
+		privateKeyJwk: options.privateKeyJwk,
+		privateKeyPem: options.privateKeyPem,
+		algorithm: options.algorithm
+	});
+	return ({ clientId, tokenEndpoint }) => signPrivateKeyJwtClientAssertion({
+		clientId,
+		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.
 */
-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
-		});
-	}
+async function resolveClientAssertionParams({ getClientAssertion, context }) {
 	return {
-		client_assertion: assertion,
+		client_assertion: await getClientAssertion(context),
 		client_assertion_type: CLIENT_ASSERTION_TYPE
 	};
 }
 //#endregion
-export { ASSERTION_SIGNING_ALGORITHMS, CLIENT_ASSERTION_TYPE, resolveAssertionParams, signClientAssertion };
+export { CLIENT_ASSERTION_TYPE, PRIVATE_KEY_JWT_SIGNING_ALGORITHMS, createPrivateKeyJwtClientAssertionGetter, resolveClientAssertionParams, signPrivateKeyJwtClientAssertion };

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

@@ -1,59 +1,38 @@
-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/client-credentials-token.d.ts
-declare function clientCredentialsTokenRequest({
-  options,
-  scope,
-  authentication,
-  clientAssertion,
-  tokenEndpoint,
-  resource
-}: {
+interface ClientCredentialsTokenRequestInput {
   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. */
+  authentication?: TokenEndpointSecretAuthentication | undefined;
+  tokenEndpointAuth?: TokenEndpointAuth | undefined;
   tokenEndpoint?: string | undefined;
   resource?: (string | string[]) | undefined;
-}): Promise<{
-  body: URLSearchParams;
-  headers: Record<string, any>;
-}>;
-/**
- * @deprecated use async'd clientCredentialsTokenRequest instead
- */
-declare function createClientCredentialsTokenRequest({
+}
+interface ClientCredentialsTokenInput extends ClientCredentialsTokenRequestInput {
+  tokenEndpoint: string;
+  scope: string;
+}
+declare function clientCredentialsTokenRequest({
   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;
-}): {
+  tokenEndpointAuth,
+  tokenEndpoint,
+  resource
+}: ClientCredentialsTokenRequestInput): Promise<{
   body: URLSearchParams;
-  headers: Record<string, any>;
-};
+  headers: Record<string, string>;
+}>;
 declare function clientCredentialsToken({
   options,
   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>;
 //#endregion
-export { clientCredentialsToken, clientCredentialsTokenRequest, createClientCredentialsTokenRequest };
+export { clientCredentialsToken, clientCredentialsTokenRequest };