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

package/dist/api/index.d.mts

@@ -2,7 +2,7 @@ import { BetterAuthDBSchema, ModelNames, SecondaryStorage } from "../db/type.mjs
 import { DBAdapter } from "../db/adapter/index.mjs";
 import { createLogger } from "../env/logger.mjs";
 import { AuthContext } from "../types/context.mjs";
-import { OAuthProvider } from "../oauth2/oauth-provider.mjs";
+import { UpstreamProvider } from "../oauth2/oauth-provider.mjs";
 import * as better_call0 from "better-call";
 import { EndpointContext, EndpointOptions, StrictEndpoint } from "better-call";
 import * as _better_auth_core0 from "@better-auth/core";
@@ -87,7 +87,7 @@ declare const createAuthMiddleware: {
         image?: string | null | undefined;
       } & Record<string, any>;
     } | null) => void;
-    socialProviders: OAuthProvider[];
+    socialProviders: UpstreamProvider[];
     authCookies: _better_auth_core0.BetterAuthCookies;
     logger: ReturnType<typeof createLogger>;
     rateLimit: {
@@ -216,7 +216,7 @@ declare const createAuthMiddleware: {
         image?: string | null | undefined;
       } & Record<string, any>;
     } | null) => void;
-    socialProviders: OAuthProvider[];
+    socialProviders: UpstreamProvider[];
     authCookies: _better_auth_core0.BetterAuthCookies;
     logger: ReturnType<typeof createLogger>;
     rateLimit: {

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.3";
+const __betterAuthVersion = "1.7.0-beta.5";
 /**
 * We store context instance in the globalThis.
 *

package/dist/db/adapter/factory.mjs

@@ -57,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);
@@ -676,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 Number.isFinite(deleted) && 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/get-tables.mjs

@@ -228,10 +228,10 @@ const getAuthTables = (options) => {
 					returned: false,
 					fieldName: options.account?.fields?.refreshTokenExpiresAt || "refreshTokenExpiresAt"
 				},
-				scope: {
-					type: "string",
+				grantedScopes: {
+					type: "string[]",
 					required: false,
-					fieldName: options.account?.fields?.scope || "scope"
+					fieldName: options.account?.fields?.grantedScopes || "grantedScopes"
 				},
 				password: {
 					type: "string",

package/dist/db/schema/account.d.mts

@@ -16,7 +16,7 @@ declare const accountSchema: z.ZodObject<{
   idToken: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   accessTokenExpiresAt: z.ZodOptional<z.ZodNullable<z.ZodDate>>;
   refreshTokenExpiresAt: z.ZodOptional<z.ZodNullable<z.ZodDate>>;
-  scope: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+  grantedScopes: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString>>>;
   password: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
 type BaseAccount = z.infer<typeof accountSchema>;

package/dist/db/schema/account.mjs

@@ -10,7 +10,7 @@ const accountSchema = coreSchema.extend({
 	idToken: z.string().nullish(),
 	accessTokenExpiresAt: z.date().nullish(),
 	refreshTokenExpiresAt: z.date().nullish(),
-	scope: z.string().nullish(),
+	grantedScopes: z.array(z.string()).nullish(),
 	password: z.string().nullish()
 });
 //#endregion

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/env/env-impl.mjs

@@ -27,7 +27,7 @@ const env = new Proxy(_envShim, {
 function toBoolean(val) {
 	return val ? val !== "false" : false;
 }
-const nodeENV = typeof process !== "undefined" && process.env && process.env.NODE_ENV || "";
+const nodeENV = env.NODE_ENV ?? "";
 /** Detect if `NODE_ENV` environment variable is `production` */
 const isProduction = nodeENV === "production";
 /** Detect if `NODE_ENV` environment variable is `dev` or `development` */

package/dist/error/codes.d.mts

@@ -29,6 +29,11 @@ declare const BASE_ERROR_CODES: {
   TOKEN_EXPIRED: RawError<"TOKEN_EXPIRED">;
   ID_TOKEN_NOT_SUPPORTED: RawError<"ID_TOKEN_NOT_SUPPORTED">;
   FAILED_TO_GET_USER_INFO: RawError<"FAILED_TO_GET_USER_INFO">;
+  PROVIDER_NOT_SUPPORTED: RawError<"PROVIDER_NOT_SUPPORTED">;
+  TOKEN_REFRESH_NOT_SUPPORTED: RawError<"TOKEN_REFRESH_NOT_SUPPORTED">;
+  REFRESH_TOKEN_NOT_FOUND: RawError<"REFRESH_TOKEN_NOT_FOUND">;
+  FAILED_TO_GET_ACCESS_TOKEN: RawError<"FAILED_TO_GET_ACCESS_TOKEN">;
+  FAILED_TO_REFRESH_ACCESS_TOKEN: RawError<"FAILED_TO_REFRESH_ACCESS_TOKEN">;
   USER_EMAIL_NOT_FOUND: RawError<"USER_EMAIL_NOT_FOUND">;
   EMAIL_NOT_VERIFIED: RawError<"EMAIL_NOT_VERIFIED">;
   PASSWORD_TOO_SHORT: RawError<"PASSWORD_TOO_SHORT">;
@@ -36,6 +41,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

@@ -16,6 +16,11 @@ const BASE_ERROR_CODES = defineErrorCodes({
 	TOKEN_EXPIRED: "Token expired",
 	ID_TOKEN_NOT_SUPPORTED: "id_token not supported",
 	FAILED_TO_GET_USER_INFO: "Failed to get user info",
+	PROVIDER_NOT_SUPPORTED: "Provider not supported",
+	TOKEN_REFRESH_NOT_SUPPORTED: "Token refresh not supported",
+	REFRESH_TOKEN_NOT_FOUND: "Refresh token not found",
+	FAILED_TO_GET_ACCESS_TOKEN: "Failed to get a valid access token",
+	FAILED_TO_REFRESH_ACCESS_TOKEN: "Failed to refresh access token",
 	USER_EMAIL_NOT_FOUND: "User email not found",
 	EMAIL_NOT_VERIFIED: "Email not verified",
 	PASSWORD_TOO_SHORT: "Password too short",
@@ -23,6 +28,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/index.d.mts

@@ -1,9 +1,9 @@
 import { Awaitable, AwaitableFunction, LiteralString, LiteralUnion, Prettify, Primitive, UnionToIntersection } from "./types/helper.mjs";
 import { BetterAuthPlugin, BetterAuthPluginErrorCodePart, HookEndpointContext } from "./types/plugin.mjs";
-import { BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthDBOptions, BetterAuthOptions, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, DynamicBaseURLConfig, GenerateIdFn, StoreIdentifierOption } from "./types/init-options.mjs";
+import { BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthDBOptions, BetterAuthOptions, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, DynamicBaseURLConfig, GenerateIdFn, StoreIdentifierOption, UserProvisioningSource, ValidateUserInfoAction, ValidateUserInfoMethod, ValidateUserInfoOAuthInfo, ValidateUserInfoResult, ValidateUserInfoSSOInfo, ValidateUserInfoSource } from "./types/init-options.mjs";
 import { BetterAuthCookie, BetterAuthCookies } from "./types/cookie.mjs";
 import { SecretConfig } from "./types/secret.mjs";
 import { AuthContext, BetterAuthPluginRegistry, BetterAuthPluginRegistryIdentifier, GenericEndpointContext, InfoContext, InternalAdapter, PluginContext } from "./types/context.mjs";
 import { BetterAuthClientOptions, BetterAuthClientPlugin, ClientAtomListener, ClientFetchOption, ClientStore } from "./types/plugin-client.mjs";
 import { StandardSchemaV1 } from "./types/index.mjs";
-export { AuthContext, Awaitable, AwaitableFunction, BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthClientOptions, BetterAuthClientPlugin, BetterAuthCookie, BetterAuthCookies, BetterAuthDBOptions, BetterAuthOptions, BetterAuthPlugin, BetterAuthPluginErrorCodePart, BetterAuthPluginRegistry, BetterAuthPluginRegistryIdentifier, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, ClientAtomListener, ClientFetchOption, ClientStore, DynamicBaseURLConfig, GenerateIdFn, GenericEndpointContext, HookEndpointContext, InfoContext, InternalAdapter, LiteralString, LiteralUnion, PluginContext, Prettify, Primitive, SecretConfig, StandardSchemaV1, StoreIdentifierOption, UnionToIntersection };
+export { AuthContext, Awaitable, AwaitableFunction, BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthClientOptions, BetterAuthClientPlugin, BetterAuthCookie, BetterAuthCookies, BetterAuthDBOptions, BetterAuthOptions, BetterAuthPlugin, BetterAuthPluginErrorCodePart, BetterAuthPluginRegistry, BetterAuthPluginRegistryIdentifier, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, ClientAtomListener, ClientFetchOption, ClientStore, DynamicBaseURLConfig, GenerateIdFn, GenericEndpointContext, HookEndpointContext, InfoContext, InternalAdapter, LiteralString, LiteralUnion, PluginContext, Prettify, Primitive, SecretConfig, StandardSchemaV1, StoreIdentifierOption, UnionToIntersection, UserProvisioningSource, ValidateUserInfoAction, ValidateUserInfoMethod, ValidateUserInfoOAuthInfo, ValidateUserInfoResult, ValidateUserInfoSSOInfo, ValidateUserInfoSource };

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.3";
+const INSTRUMENTATION_VERSION = "1.7.0-beta.5";
 /**
 * 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 };