better-auth 1.6.3 → 1.7.0-beta.1

package/dist/plugins/generic-oauth/index.mjs

@@ -1,6 +1,5 @@
 import { PACKAGE_VERSION } from "../../version.mjs";
 import { GENERIC_OAUTH_ERROR_CODES } from "./error-codes.mjs";
-import { getUserInfo, oAuth2Callback, oAuth2LinkAccount, signInWithOAuth2 } from "./routes.mjs";
 import { auth0 } from "./providers/auth0.mjs";
 import { gumroad } from "./providers/gumroad.mjs";
 import { hubspot } from "./providers/hubspot.mjs";
@@ -12,10 +11,61 @@ import { patreon } from "./providers/patreon.mjs";
 import { slack } from "./providers/slack.mjs";
 import { APIError } from "@better-auth/core/error";
 import { createAuthorizationURL, refreshAccessToken, validateAuthorizationCode } from "@better-auth/core/oauth2";
+import { decodeJwt } from "jose";
 import { betterFetch } from "@better-fetch/fetch";
 //#region src/plugins/generic-oauth/index.ts
+function buildClientAssertion(config, tokenEndpoint) {
+	if (config.authentication !== "private_key_jwt" || !config.clientAssertion) return;
+	return {
+		...config.clientAssertion,
+		tokenEndpoint
+	};
+}
+async function fetchDiscovery(url, headers) {
+	const result = await betterFetch(url, {
+		method: "GET",
+		headers
+	});
+	if (result.error || !result.data) return null;
+	if (result.data.issuer) try {
+		new URL(result.data.issuer);
+	} catch {
+		return null;
+	}
+	return result.data;
+}
+async function fetchUserInfo(tokens, userInfoUrl) {
+	if (tokens.idToken) try {
+		const decoded = decodeJwt(tokens.idToken);
+		if (decoded?.sub && decoded?.email) return {
+			id: decoded.sub,
+			emailVerified: decoded.email_verified,
+			image: decoded.picture,
+			...decoded
+		};
+	} catch {}
+	if (!userInfoUrl) return null;
+	const userInfo = await betterFetch(userInfoUrl, {
+		method: "GET",
+		headers: { Authorization: `Bearer ${tokens.accessToken}` }
+	});
+	if (userInfo.error || !userInfo.data) return null;
+	const data = userInfo.data;
+	return {
+		...data,
+		id: data.sub ?? data.id ?? "",
+		emailVerified: data.email_verified ?? false,
+		email: data.email,
+		image: data.picture,
+		name: data.name
+	};
+}
 /**
-* A generic OAuth plugin that can be used to add OAuth support to any provider
+* A generic OAuth plugin that registers any OAuth/OIDC provider
+* as a first-class social provider.
+*
+* Providers are used through the standard `signIn.social` and
+* `callback/:id` core endpoints — no plugin-specific endpoints needed.
 */
 const genericOAuth = (options) => {
 	const seenIds = /* @__PURE__ */ new Set();
@@ -29,25 +79,34 @@ const genericOAuth = (options) => {
 	return {
 		id: "generic-oauth",
 		version: PACKAGE_VERSION,
-		init: (ctx) => {
-			return { context: { socialProviders: options.config.map((c) => {
-				let finalUserInfoUrl = c.userInfoUrl;
-				return {
+		init: async (ctx) => {
+			const genericProviders = [];
+			for (const c of options.config) {
+				let authorizationUrl = c.authorizationUrl;
+				let tokenUrl = c.tokenUrl;
+				let userInfoUrl = c.userInfoUrl;
+				let issuer;
+				let isOidc = false;
+				if (c.discoveryUrl) {
+					const discovered = await fetchDiscovery(c.discoveryUrl, c.discoveryHeaders).catch((err) => {
+						ctx.logger.error(`Discovery fetch failed for "${c.providerId}": ${err}`);
+						return null;
+					});
+					if (discovered) {
+						authorizationUrl ??= discovered.authorization_endpoint;
+						tokenUrl ??= discovered.token_endpoint;
+						userInfoUrl ??= discovered.userinfo_endpoint;
+						issuer = discovered.issuer;
+						isOidc = Array.isArray(discovered.id_token_signing_alg_values_supported) && discovered.id_token_signing_alg_values_supported.length > 0;
+					} else if (!authorizationUrl || !tokenUrl) ctx.logger.error(`Provider "${c.providerId}": discovery returned no data and no explicit endpoints configured. OAuth sign-in will fail for this provider.`);
+				}
+				if (!c.clientSecret && !c.clientAssertion && c.authentication !== "private_key_jwt") ctx.logger.warn(`Provider "${c.providerId}": no clientSecret or clientAssertion configured. Token exchange will fail unless this is a public client.`);
+				genericProviders.push({
 					id: c.providerId,
-					name: c.providerId,
-					async createAuthorizationURL(data) {
-						let finalAuthUrl = c.authorizationUrl;
-						if (!finalAuthUrl && c.discoveryUrl) {
-							const discovery = await betterFetch(c.discoveryUrl, {
-								method: "GET",
-								headers: c.discoveryHeaders
-							});
-							if (discovery.data) {
-								finalAuthUrl = discovery.data.authorization_endpoint;
-								finalUserInfoUrl = finalUserInfoUrl ?? discovery.data.userinfo_endpoint;
-							}
-						}
-						if (!finalAuthUrl) throw APIError.from("BAD_REQUEST", GENERIC_OAUTH_ERROR_CODES.INVALID_OAUTH_CONFIGURATION);
+					name: c.name ?? c.providerId,
+					issuer,
+					createAuthorizationURL(data) {
+						if (!authorizationUrl) throw APIError.from("BAD_REQUEST", GENERIC_OAUTH_ERROR_CODES.INVALID_OAUTH_CONFIGURATION);
 						return createAuthorizationURL({
 							id: c.providerId,
 							options: {
@@ -55,51 +114,64 @@ const genericOAuth = (options) => {
 								clientSecret: c.clientSecret,
 								redirectURI: c.redirectURI
 							},
-							authorizationEndpoint: finalAuthUrl,
+							authorizationEndpoint: authorizationUrl,
 							state: data.state,
-							codeVerifier: c.pkce ? data.codeVerifier : void 0,
-							scopes: c.scopes || [],
-							redirectURI: `${ctx.baseURL}/oauth2/callback/${c.providerId}`
+							codeVerifier: c.pkce ?? true ? data.codeVerifier : void 0,
+							scopes: (() => {
+								const merged = [...data.scopes ?? [], ...c.scopes ?? []];
+								if (isOidc && !merged.includes("openid")) merged.unshift("openid");
+								return merged;
+							})(),
+							redirectURI: data.redirectURI,
+							prompt: c.prompt,
+							accessType: c.accessType,
+							responseType: c.responseType,
+							responseMode: c.responseMode,
+							additionalParams: c.authorizationUrlParams,
+							loginHint: data.loginHint
 						});
 					},
 					async validateAuthorizationCode(data) {
 						if (c.getToken) return c.getToken(data);
-						let finalTokenUrl = c.tokenUrl;
-						if (c.discoveryUrl) {
-							const discovery = await betterFetch(c.discoveryUrl, {
-								method: "GET",
-								headers: c.discoveryHeaders
-							});
-							if (discovery.data) {
-								finalTokenUrl = discovery.data.token_endpoint;
-								finalUserInfoUrl = discovery.data.userinfo_endpoint;
-							}
-						}
-						if (!finalTokenUrl) throw APIError.from("BAD_REQUEST", GENERIC_OAUTH_ERROR_CODES.TOKEN_URL_NOT_FOUND);
+						if (!tokenUrl) throw APIError.from("BAD_REQUEST", GENERIC_OAUTH_ERROR_CODES.TOKEN_URL_NOT_FOUND);
 						return validateAuthorizationCode({
 							headers: c.authorizationHeaders,
 							code: data.code,
-							codeVerifier: data.codeVerifier,
+							codeVerifier: c.pkce ?? true ? data.codeVerifier : void 0,
 							redirectURI: data.redirectURI,
 							options: {
 								clientId: c.clientId,
 								clientSecret: c.clientSecret,
 								redirectURI: c.redirectURI
 							},
-							tokenEndpoint: finalTokenUrl,
-							authentication: c.authentication
+							tokenEndpoint: tokenUrl,
+							authentication: c.authentication,
+							additionalParams: c.tokenUrlParams,
+							clientAssertion: buildClientAssertion(c, tokenUrl)
 						});
 					},
+					async getUserInfo(tokens) {
+						const raw = c.getUserInfo ? await c.getUserInfo(tokens) : await fetchUserInfo(tokens, userInfoUrl);
+						if (!raw) return null;
+						const mapped = c.mapProfileToUser ? await c.mapProfileToUser(raw) : {};
+						const user = {
+							id: raw.id,
+							email: raw.email,
+							emailVerified: raw.emailVerified,
+							image: raw.image,
+							name: raw.name,
+							...mapped
+						};
+						return {
+							user: {
+								...user,
+								image: user.image ?? void 0
+							},
+							data: raw
+						};
+					},
 					async refreshAccessToken(refreshToken) {
-						let finalTokenUrl = c.tokenUrl;
-						if (c.discoveryUrl) {
-							const discovery = await betterFetch(c.discoveryUrl, {
-								method: "GET",
-								headers: c.discoveryHeaders
-							});
-							if (discovery.data) finalTokenUrl = discovery.data.token_endpoint;
-						}
-						if (!finalTokenUrl) throw APIError.from("BAD_REQUEST", GENERIC_OAUTH_ERROR_CODES.TOKEN_URL_NOT_FOUND);
+						if (!tokenUrl) throw APIError.from("BAD_REQUEST", GENERIC_OAUTH_ERROR_CODES.TOKEN_URL_NOT_FOUND);
 						return refreshAccessToken({
 							refreshToken,
 							options: {
@@ -107,33 +179,21 @@ const genericOAuth = (options) => {
 								clientSecret: c.clientSecret
 							},
 							authentication: c.authentication,
-							tokenEndpoint: finalTokenUrl
+							clientAssertion: buildClientAssertion(c, tokenUrl),
+							tokenEndpoint: tokenUrl
 						});
 					},
-					async getUserInfo(tokens) {
-						const userInfo = c.getUserInfo ? await c.getUserInfo(tokens) : await getUserInfo(tokens, finalUserInfoUrl);
-						if (!userInfo) return null;
-						const userMap = await c.mapProfileToUser?.(userInfo);
-						return {
-							user: {
-								id: userInfo?.id,
-								email: userInfo?.email,
-								emailVerified: userInfo?.emailVerified,
-								image: userInfo?.image,
-								name: userInfo?.name,
-								...userMap
-							},
-							data: userInfo
-						};
-					},
-					options: { overrideUserInfoOnSignIn: c.overrideUserInfo }
-				};
-			}).concat(ctx.socialProviders) } };
-		},
-		endpoints: {
-			signInWithOAuth2: signInWithOAuth2(options),
-			oAuth2Callback: oAuth2Callback(options),
-			oAuth2LinkAccount: oAuth2LinkAccount(options)
+					disableImplicitSignUp: c.disableImplicitSignUp,
+					disableSignUp: c.disableSignUp,
+					options: {
+						disableSignUp: c.disableSignUp,
+						overrideUserInfoOnSignIn: c.overrideUserInfo
+					}
+				});
+			}
+			const existingIds = new Set(ctx.socialProviders.map((p) => p.id));
+			for (const gp of genericProviders) if (existingIds.has(gp.id)) ctx.logger.warn(`Generic OAuth provider "${gp.id}" shadows a built-in social provider with the same ID`);
+			return { context: { socialProviders: genericProviders.concat(ctx.socialProviders) } };
 		},
 		options,
 		$ERROR_CODES: GENERIC_OAUTH_ERROR_CODES

package/dist/plugins/generic-oauth/providers/auth0.d.mts

@@ -31,6 +31,6 @@ interface Auth0Options extends BaseOAuthProviderOptions {
  * });
  * ```
  */
-declare function auth0(options: Auth0Options): GenericOAuthConfig;
+declare function auth0(options: Auth0Options): GenericOAuthConfig<"auth0">;
 //#endregion
 export { Auth0Options, auth0 };

package/dist/plugins/generic-oauth/providers/gumroad.d.mts

@@ -26,6 +26,6 @@ interface GumroadOptions extends BaseOAuthProviderOptions {}
  *
  * @see https://app.gumroad.com/oauth
  */
-declare function gumroad(options: GumroadOptions): GenericOAuthConfig;
+declare function gumroad(options: GumroadOptions): GenericOAuthConfig<"gumroad">;
 //#endregion
 export { GumroadOptions, gumroad };

package/dist/plugins/generic-oauth/providers/hubspot.d.mts

@@ -31,6 +31,6 @@ interface HubSpotOptions extends BaseOAuthProviderOptions {
  * });
  * ```
  */
-declare function hubspot(options: HubSpotOptions): GenericOAuthConfig;
+declare function hubspot(options: HubSpotOptions): GenericOAuthConfig<"hubspot">;
 //#endregion
 export { HubSpotOptions, hubspot };

package/dist/plugins/generic-oauth/providers/keycloak.d.mts

@@ -31,6 +31,6 @@ interface KeycloakOptions extends BaseOAuthProviderOptions {
  * });
  * ```
  */
-declare function keycloak(options: KeycloakOptions): GenericOAuthConfig;
+declare function keycloak(options: KeycloakOptions): GenericOAuthConfig<"keycloak">;
 //#endregion
 export { KeycloakOptions, keycloak };

package/dist/plugins/generic-oauth/providers/microsoft-entra-id.d.mts

@@ -31,6 +31,6 @@ interface MicrosoftEntraIdOptions extends BaseOAuthProviderOptions {
  * });
  * ```
  */
-declare function microsoftEntraId(options: MicrosoftEntraIdOptions): GenericOAuthConfig;
+declare function microsoftEntraId(options: MicrosoftEntraIdOptions): GenericOAuthConfig<"microsoft-entra-id">;
 //#endregion
 export { MicrosoftEntraIdOptions, microsoftEntraId };

package/dist/plugins/generic-oauth/providers/okta.d.mts

@@ -31,6 +31,6 @@ interface OktaOptions extends BaseOAuthProviderOptions {
  * });
  * ```
  */
-declare function okta(options: OktaOptions): GenericOAuthConfig;
+declare function okta(options: OktaOptions): GenericOAuthConfig<"okta">;
 //#endregion
 export { OktaOptions, okta };

package/dist/plugins/generic-oauth/providers/patreon.d.mts

@@ -24,6 +24,6 @@ interface PatreonOptions extends BaseOAuthProviderOptions {}
  * });
  * ```
  */
-declare function patreon(options: PatreonOptions): GenericOAuthConfig;
+declare function patreon(options: PatreonOptions): GenericOAuthConfig<"patreon">;
 //#endregion
 export { PatreonOptions, patreon };

package/dist/plugins/generic-oauth/providers/slack.d.mts

@@ -24,6 +24,6 @@ interface SlackOptions extends BaseOAuthProviderOptions {}
  * });
  * ```
  */
-declare function slack(options: SlackOptions): GenericOAuthConfig;
+declare function slack(options: SlackOptions): GenericOAuthConfig<"slack">;
 //#endregion
 export { SlackOptions, slack };

package/dist/plugins/generic-oauth/types.d.mts

@@ -1,39 +1,29 @@
-import { GenericEndpointContext } from "@better-auth/core";
 import { User } from "@better-auth/core/db";
-import { OAuth2Tokens, OAuth2UserInfo } from "@better-auth/core/oauth2";
+import { ClientAssertionConfig, OAuth2Tokens, OAuth2UserInfo } from "@better-auth/core/oauth2";
 
 //#region src/plugins/generic-oauth/types.d.ts
-interface GenericOAuthOptions {
+interface GenericOAuthOptions<ID extends string = string> {
   /**
    * Array of OAuth provider configurations.
    */
-  config: GenericOAuthConfig[];
+  config: GenericOAuthConfig<ID>[];
 }
 /**
  * Configuration interface for generic OAuth providers.
  */
-interface GenericOAuthConfig {
+interface GenericOAuthConfig<ID extends string = string> {
   /** Unique identifier for the OAuth provider */
-  providerId: string;
+  providerId: ID;
+  /**
+   * Human-readable display name for this provider.
+   * Defaults to `providerId` if not set.
+   */
+  name?: string | undefined;
   /**
    * URL to fetch OAuth 2.0 configuration.
    * If provided, the authorization and token endpoints will be fetched from this URL.
    */
   discoveryUrl?: string | undefined;
-  /**
-   * The expected issuer identifier for validation.
-   * If not provided but discoveryUrl is set, it will be fetched from the discovery document.
-   * When set, the callback validates that the `iss` parameter matches this value.
-   * @see https://datatracker.ietf.org/doc/html/rfc9207
-   */
-  issuer?: string | undefined;
-  /**
-   * When true, requires the `iss` parameter in callbacks if an issuer is configured.
-   * This provides stricter security but may break with older OAuth servers
-   * that don't support issuer identification.
-   * @default false
-   */
-  requireIssuerValidation?: boolean | undefined;
   /**
    * URL for the authorization endpoint.
    * Optional if using discoveryUrl.
@@ -78,8 +68,10 @@ interface GenericOAuthConfig {
    */
   prompt?: ("none" | "login" | "create" | "consent" | "select_account" | "select_account consent" | "login consent") | undefined;
   /**
-   * Whether to use PKCE (Proof Key for Code Exchange)
-   * @default false
+   * Whether to use PKCE (Proof Key for Code Exchange).
+   * Required by OAuth 2.1 for all authorization code flows.
+   * Disable only for providers that explicitly reject PKCE.
+   * @default true
    */
   pkce?: boolean | undefined;
   /**
@@ -108,19 +100,20 @@ interface GenericOAuthConfig {
    */
   getUserInfo?: ((tokens: OAuth2Tokens) => Promise<OAuth2UserInfo | null>) | undefined;
   /**
-   * Custom function to map the user profile to a User object.
+   * Custom function to map the provider's user profile to your app's user fields.
+   * The profile contains standard OAuth2 fields plus any provider-specific extras.
    */
-  mapProfileToUser?: ((profile: Record<string, any>) => Partial<Partial<User>> | Promise<Partial<User>>) | undefined;
+  mapProfileToUser?: ((profile: OAuth2UserInfo & Record<string, unknown>) => Partial<User> | Promise<Partial<User>>) | undefined;
   /**
    * Additional search-params to add to the authorizationUrl.
    * Warning: Search-params added here overwrite any default params.
    */
-  authorizationUrlParams?: (Record<string, string> | ((ctx: GenericEndpointContext) => Record<string, string>)) | undefined;
+  authorizationUrlParams?: Record<string, string> | undefined;
   /**
    * Additional search-params to add to the tokenUrl.
    * Warning: Search-params added here overwrite any default params.
    */
-  tokenUrlParams?: (Record<string, string> | ((ctx: GenericEndpointContext) => Record<string, string>)) | undefined;
+  tokenUrlParams?: Record<string, string> | undefined;
   /**
    * Disable implicit sign up for new users. When set to true for the provider,
    * sign-in need to be called with with requestSignUp as true to create new users.
@@ -134,7 +127,12 @@ interface GenericOAuthConfig {
    * Authentication method for token requests.
    * @default "post"
    */
-  authentication?: ("basic" | "post") | undefined;
+  authentication?: ("basic" | "post" | "private_key_jwt") | undefined;
+  /**
+   * Client assertion config for `private_key_jwt` authentication.
+   * Required when `authentication` is `"private_key_jwt"`.
+   */
+  clientAssertion?: ClientAssertionConfig | undefined;
   /**
    * Custom headers to include in the discovery request.
    * Useful for providers like Epic that require specific headers (e.g., Epic-Client-ID).

package/dist/plugins/index.d.mts

@@ -29,8 +29,8 @@ import { PatreonOptions, patreon } from "./generic-oauth/providers/patreon.mjs";
 import { SlackOptions, slack } from "./generic-oauth/providers/slack.mjs";
 import { BaseOAuthProviderOptions, genericOAuth } from "./generic-oauth/index.mjs";
 import { HaveIBeenPwnedOptions, haveIBeenPwned } from "./haveibeenpwned/index.mjs";
-import { JWKOptions, JWSAlgorithms, Jwk, JwtOptions } from "./jwt/types.mjs";
-import { getJwtToken, signJWT } from "./jwt/sign.mjs";
+import { JWKOptions, JWSAlgorithms, Jwk, JwtOptions, ResolvedSigningKey } from "./jwt/types.mjs";
+import { getJwtToken, resolveSigningKey, signJWT } from "./jwt/sign.mjs";
 import { createJwk, generateExportedKeyPair, toExpJWT } from "./jwt/utils.mjs";
 import { verifyJWT } from "./jwt/verify.mjs";
 import { jwt } from "./jwt/index.mjs";
@@ -62,4 +62,4 @@ import { USERNAME_ERROR_CODES } from "./username/error-codes.mjs";
 import { UsernameOptions, username } from "./username/index.mjs";
 import { hasPermission } from "./organization/has-permission.mjs";
 import { DefaultOrganizationPlugin, DynamicAccessControlEndpoints, OrganizationCreator, OrganizationEndpoints, OrganizationPlugin, TeamEndpoints, organization, parseRoles } from "./organization/organization.mjs";
-export { AccessControl, AdminOptions, AnonymousOptions, AnonymousSession, ArrayElement, Auth0Options, AuthorizationQuery, AuthorizeResponse, BackupCodeOptions, BaseCaptchaOptions, BaseOAuthProviderOptions, BearerOptions, CaptchaFoxOptions, CaptchaOptions, Client, CloudflareTurnstileOptions, CodeVerificationValue, CustomSessionPluginOptions, DefaultOrganizationPlugin, DeviceAuthorizationOptions, DynamicAccessControlEndpoints, MULTI_SESSION_ERROR_CODES as ERROR_CODES, EmailOTPOptions, FieldSchema, GenericOAuthConfig, GenericOAuthOptions, GoogleRecaptchaOptions, GumroadOptions, HCaptchaOptions, HIDE_METADATA, HaveIBeenPwnedOptions, HubSpotOptions, InferAdminRolesFromOption, InferInvitation, InferMember, InferOptionSchema, InferOrganization, InferOrganizationRolesFromOption, InferOrganizationZodRolesFromOption, InferPluginContext, InferPluginErrorCodes, InferPluginIDs, InferTeam, Invitation, InvitationInput, InvitationStatus, JWKOptions, JWSAlgorithms, Jwk, JwtOptions, KeycloakOptions, LastLoginMethodOptions, LineOptions, LoginResult, MagicLinkOptions, Member, MemberInput, MicrosoftEntraIdOptions, MultiSessionConfig, OAuthAccessToken, OAuthProxyOptions, OIDCMetadata, OIDCOptions, OTPOptions, OktaOptions, OneTapOptions, OneTimeTokenOptions, OpenAPIModelSchema, OpenAPIOptions, Organization, OrganizationCreator, OrganizationEndpoints, OrganizationInput, OrganizationOptions, OrganizationPlugin, OrganizationRole, OrganizationSchema, Path, PatreonOptions, PhoneNumberOptions, Provider, Role, SIWEPluginOptions, SessionWithImpersonatedBy, SlackOptions, Statements, SubArray, Subset, TOTPOptions, TWO_FACTOR_ERROR_CODES, Team, TeamEndpoints, TeamInput, TeamMember, TeamMemberInput, TestCookie, TestHelpers, TestUtilsOptions, TimeString, TokenBody, TwoFactorOptions, TwoFactorProvider, TwoFactorTable, USERNAME_ERROR_CODES, UserWithAnonymous, UserWithPhoneNumber, UserWithRole, UserWithTwoFactor, UsernameOptions, admin, anonymous, auth0, backupCode2fa, bearer, captcha, createAccessControl, createJwk, customSession, defaultRolesSchema, deviceAuthorization, deviceAuthorizationOptionsSchema, emailOTP, encodeBackupCodes, generateBackupCodes, generateExportedKeyPair, generator, genericOAuth, getBackupCodes, getClient, getJwtToken, getMCPProtectedResourceMetadata, getMCPProviderMetadata, getMetadata, getOrgAdapter, gumroad, hasPermission, haveIBeenPwned, hubspot, invitationSchema, invitationStatus, jwt, keycloak, lastLoginMethod, line, magicLink, mcp, memberSchema, microsoftEntraId, ms, multiSession, oAuthDiscoveryMetadata, oAuthProtectedResourceMetadata, oAuthProxy, oidcProvider, okta, oneTap, oneTimeToken, openAPI, organization, organizationRoleSchema, organizationSchema, otp2fa, parseRoles, patreon, phoneNumber, role, roleSchema, sec, signJWT, siwe, slack, teamMemberSchema, teamSchema, testUtils, toExpJWT, totp2fa, twoFactor, twoFactorClient, username, verifyBackupCode, verifyJWT, withMcpAuth };
+export { AccessControl, AdminOptions, AnonymousOptions, AnonymousSession, ArrayElement, Auth0Options, AuthorizationQuery, AuthorizeResponse, BackupCodeOptions, BaseCaptchaOptions, BaseOAuthProviderOptions, BearerOptions, CaptchaFoxOptions, CaptchaOptions, Client, CloudflareTurnstileOptions, CodeVerificationValue, CustomSessionPluginOptions, DefaultOrganizationPlugin, DeviceAuthorizationOptions, DynamicAccessControlEndpoints, MULTI_SESSION_ERROR_CODES as ERROR_CODES, EmailOTPOptions, FieldSchema, GenericOAuthConfig, GenericOAuthOptions, GoogleRecaptchaOptions, GumroadOptions, HCaptchaOptions, HIDE_METADATA, HaveIBeenPwnedOptions, HubSpotOptions, InferAdminRolesFromOption, InferInvitation, InferMember, InferOptionSchema, InferOrganization, InferOrganizationRolesFromOption, InferOrganizationZodRolesFromOption, InferPluginContext, InferPluginErrorCodes, InferPluginIDs, InferTeam, Invitation, InvitationInput, InvitationStatus, JWKOptions, JWSAlgorithms, Jwk, JwtOptions, KeycloakOptions, LastLoginMethodOptions, LineOptions, LoginResult, MagicLinkOptions, Member, MemberInput, MicrosoftEntraIdOptions, MultiSessionConfig, OAuthAccessToken, OAuthProxyOptions, OIDCMetadata, OIDCOptions, OTPOptions, OktaOptions, OneTapOptions, OneTimeTokenOptions, OpenAPIModelSchema, OpenAPIOptions, Organization, OrganizationCreator, OrganizationEndpoints, OrganizationInput, OrganizationOptions, OrganizationPlugin, OrganizationRole, OrganizationSchema, Path, PatreonOptions, PhoneNumberOptions, Provider, ResolvedSigningKey, Role, SIWEPluginOptions, SessionWithImpersonatedBy, SlackOptions, Statements, SubArray, Subset, TOTPOptions, TWO_FACTOR_ERROR_CODES, Team, TeamEndpoints, TeamInput, TeamMember, TeamMemberInput, TestCookie, TestHelpers, TestUtilsOptions, TimeString, TokenBody, TwoFactorOptions, TwoFactorProvider, TwoFactorTable, USERNAME_ERROR_CODES, UserWithAnonymous, UserWithPhoneNumber, UserWithRole, UserWithTwoFactor, UsernameOptions, admin, anonymous, auth0, backupCode2fa, bearer, captcha, createAccessControl, createJwk, customSession, defaultRolesSchema, deviceAuthorization, deviceAuthorizationOptionsSchema, emailOTP, encodeBackupCodes, generateBackupCodes, generateExportedKeyPair, generator, genericOAuth, getBackupCodes, getClient, getJwtToken, getMCPProtectedResourceMetadata, getMCPProviderMetadata, getMetadata, getOrgAdapter, gumroad, hasPermission, haveIBeenPwned, hubspot, invitationSchema, invitationStatus, jwt, keycloak, lastLoginMethod, line, magicLink, mcp, memberSchema, microsoftEntraId, ms, multiSession, oAuthDiscoveryMetadata, oAuthProtectedResourceMetadata, oAuthProxy, oidcProvider, okta, oneTap, oneTimeToken, openAPI, organization, organizationRoleSchema, organizationSchema, otp2fa, parseRoles, patreon, phoneNumber, resolveSigningKey, role, roleSchema, sec, signJWT, siwe, slack, teamMemberSchema, teamSchema, testUtils, toExpJWT, totp2fa, twoFactor, twoFactorClient, username, verifyBackupCode, verifyJWT, withMcpAuth };

package/dist/plugins/index.mjs

@@ -23,7 +23,7 @@ import { slack } from "./generic-oauth/providers/slack.mjs";
 import { genericOAuth } from "./generic-oauth/index.mjs";
 import { haveIBeenPwned } from "./haveibeenpwned/index.mjs";
 import { createJwk, generateExportedKeyPair, toExpJWT } from "./jwt/utils.mjs";
-import { getJwtToken, signJWT } from "./jwt/sign.mjs";
+import { getJwtToken, resolveSigningKey, signJWT } from "./jwt/sign.mjs";
 import { verifyJWT } from "./jwt/verify.mjs";
 import { jwt } from "./jwt/index.mjs";
 import { lastLoginMethod } from "./last-login-method/index.mjs";
@@ -43,4 +43,4 @@ import { siwe } from "./siwe/index.mjs";
 import { testUtils } from "./test-utils/index.mjs";
 import { twoFactor } from "./two-factor/index.mjs";
 import { username } from "./username/index.mjs";
-export { MULTI_SESSION_ERROR_CODES as ERROR_CODES, HIDE_METADATA, TWO_FACTOR_ERROR_CODES, USERNAME_ERROR_CODES, admin, anonymous, auth0, bearer, captcha, createAccessControl, createJwk, customSession, deviceAuthorization, deviceAuthorizationOptionsSchema, emailOTP, generateExportedKeyPair, genericOAuth, getClient, getJwtToken, getMCPProtectedResourceMetadata, getMCPProviderMetadata, getMetadata, getOrgAdapter, gumroad, hasPermission, haveIBeenPwned, hubspot, jwt, keycloak, lastLoginMethod, line, magicLink, mcp, microsoftEntraId, multiSession, oAuthDiscoveryMetadata, oAuthProtectedResourceMetadata, oAuthProxy, oidcProvider, okta, oneTap, oneTimeToken, openAPI, organization, parseRoles, patreon, phoneNumber, role, signJWT, siwe, slack, testUtils, toExpJWT, twoFactor, twoFactorClient, username, verifyJWT, withMcpAuth };
+export { MULTI_SESSION_ERROR_CODES as ERROR_CODES, HIDE_METADATA, TWO_FACTOR_ERROR_CODES, USERNAME_ERROR_CODES, admin, anonymous, auth0, bearer, captcha, createAccessControl, createJwk, customSession, deviceAuthorization, deviceAuthorizationOptionsSchema, emailOTP, generateExportedKeyPair, genericOAuth, getClient, getJwtToken, getMCPProtectedResourceMetadata, getMCPProviderMetadata, getMetadata, getOrgAdapter, gumroad, hasPermission, haveIBeenPwned, hubspot, jwt, keycloak, lastLoginMethod, line, magicLink, mcp, microsoftEntraId, multiSession, oAuthDiscoveryMetadata, oAuthProtectedResourceMetadata, oAuthProxy, oidcProvider, okta, oneTap, oneTimeToken, openAPI, organization, parseRoles, patreon, phoneNumber, resolveSigningKey, role, signJWT, siwe, slack, testUtils, toExpJWT, twoFactor, twoFactorClient, username, verifyJWT, withMcpAuth };

package/dist/plugins/jwt/client.d.mts

@@ -1,4 +1,4 @@
-import { JWKOptions, JWSAlgorithms, Jwk, JwtOptions } from "./types.mjs";
+import { JWKOptions, JWSAlgorithms, Jwk, JwtOptions, ResolvedSigningKey } from "./types.mjs";
 import { jwt } from "./index.mjs";
 import { JSONWebKeySet } from "jose";
 import * as _better_fetch_fetch0 from "@better-fetch/fetch";

package/dist/plugins/jwt/index.d.mts

@@ -1,5 +1,5 @@
-import { JWKOptions, JWSAlgorithms, Jwk, JwtOptions } from "./types.mjs";
-import { getJwtToken, signJWT } from "./sign.mjs";
+import { JWKOptions, JWSAlgorithms, Jwk, JwtOptions, ResolvedSigningKey } from "./types.mjs";
+import { getJwtToken, resolveSigningKey, signJWT } from "./sign.mjs";
 import { createJwk, generateExportedKeyPair, toExpJWT } from "./utils.mjs";
 import { verifyJWT } from "./verify.mjs";
 import * as _better_auth_core0 from "@better-auth/core";
@@ -221,4 +221,4 @@ declare const jwt: <O extends JwtOptions>(options?: O) => {
   };
 };
 //#endregion
-export { JWKOptions, JWSAlgorithms, Jwk, JwtOptions, createJwk, generateExportedKeyPair, getJwtToken, jwt, signJWT, toExpJWT, verifyJWT };
+export { JWKOptions, JWSAlgorithms, Jwk, JwtOptions, ResolvedSigningKey, createJwk, generateExportedKeyPair, getJwtToken, jwt, resolveSigningKey, signJWT, toExpJWT, verifyJWT };

package/dist/plugins/jwt/index.mjs

@@ -5,7 +5,7 @@ import { PACKAGE_VERSION } from "../../version.mjs";
 import { getJwksAdapter } from "./adapter.mjs";
 import { schema } from "./schema.mjs";
 import { createJwk, generateExportedKeyPair, toExpJWT } from "./utils.mjs";
-import { getJwtToken, signJWT } from "./sign.mjs";
+import { getJwtToken, resolveSigningKey, signJWT } from "./sign.mjs";
 import { verifyJWT } from "./verify.mjs";
 import { BetterAuthError } from "@better-auth/core/error";
 import { createAuthEndpoint, createAuthMiddleware } from "@better-auth/core/api";
@@ -198,4 +198,4 @@ const jwt = (options) => {
 	};
 };
 //#endregion
-export { createJwk, generateExportedKeyPair, getJwtToken, jwt, signJWT, toExpJWT, verifyJWT };
+export { createJwk, generateExportedKeyPair, getJwtToken, jwt, resolveSigningKey, signJWT, toExpJWT, verifyJWT };

package/dist/plugins/jwt/sign.d.mts

@@ -1,4 +1,4 @@
-import { JwtOptions } from "./types.mjs";
+import { JwtOptions, ResolvedSigningKey } from "./types.mjs";
 import { GenericEndpointContext } from "@better-auth/core";
 
 //#region src/plugins/jwt/sign.d.ts
@@ -47,10 +47,22 @@ type JWTPayloadWithOptional = {
   iat?: number | undefined; /** Any other JWT Claim Set member. */
   [propName: string]: unknown | undefined;
 };
+/**
+ * Resolves the JWKS signing key, decrypts it, and imports it
+ * for use with jose's SignJWT. Returns null when signing is
+ * delegated to a custom jwt.sign callback.
+ *
+ * Callers that need the signing algorithm before constructing
+ * the JWT payload (e.g. for OIDC at_hash) should call this
+ * first, read `.alg`, then pass the result to `signJWT` via
+ * the `resolvedKey` option to avoid a redundant DB lookup.
+ */
+declare function resolveSigningKey(ctx: GenericEndpointContext, options?: JwtOptions): Promise<ResolvedSigningKey | null>;
 declare function signJWT(ctx: GenericEndpointContext, config: {
   options?: JwtOptions | undefined;
-  payload: JWTPayloadWithOptional;
+  payload: JWTPayloadWithOptional; /** Pre-resolved key from resolveSigningKey. Skips redundant DB lookup. */
+  resolvedKey?: ResolvedSigningKey;
 }): Promise<string>;
 declare function getJwtToken(ctx: GenericEndpointContext, options?: JwtOptions | undefined): Promise<string>;
 //#endregion
-export { getJwtToken, signJWT };
+export { getJwtToken, resolveSigningKey, signJWT };

package/dist/plugins/jwt/sign.mjs

@@ -4,6 +4,34 @@ import { createJwk, toExpJWT } from "./utils.mjs";
 import { BetterAuthError } from "@better-auth/core/error";
 import { SignJWT, importJWK } from "jose";
 //#region src/plugins/jwt/sign.ts
+/**
+* Resolves the JWKS signing key, decrypts it, and imports it
+* for use with jose's SignJWT. Returns null when signing is
+* delegated to a custom jwt.sign callback.
+*
+* Callers that need the signing algorithm before constructing
+* the JWT payload (e.g. for OIDC at_hash) should call this
+* first, read `.alg`, then pass the result to `signJWT` via
+* the `resolvedKey` option to avoid a redundant DB lookup.
+*/
+async function resolveSigningKey(ctx, options) {
+	if (options?.jwt?.sign) return null;
+	let key = await getJwksAdapter(ctx.context.adapter, options).getLatestKey(ctx);
+	if (!key || key.expiresAt && key.expiresAt < /* @__PURE__ */ new Date()) key = await createJwk(ctx, options);
+	const privateWebKey = !options?.jwks?.disablePrivateKeyEncryption ? await symmetricDecrypt({
+		key: ctx.context.secretConfig,
+		data: JSON.parse(key.privateKey)
+	}).catch(() => {
+		throw new BetterAuthError("Failed to decrypt private key. Make sure the secret currently in use is the same as the one used to encrypt the private key. If you are using a different secret, either clean up your JWKS or disable private key encryption.");
+	}) : key.privateKey;
+	const alg = key.alg ?? options?.jwks?.keyPairConfig?.alg ?? "EdDSA";
+	const privateKey = await importJWK(JSON.parse(privateWebKey), alg);
+	return {
+		alg,
+		kid: key.id,
+		privateKey
+	};
+}
 async function signJWT(ctx, config) {
 	const { options } = config;
 	const payload = config.payload;
@@ -29,19 +57,10 @@ async function signJWT(ctx, config) {
 		};
 		return options.jwt.sign(jwtPayload);
 	}
-	let key = await getJwksAdapter(ctx.context.adapter, options).getLatestKey(ctx);
-	if (!key || key.expiresAt && key.expiresAt < /* @__PURE__ */ new Date()) key = await createJwk(ctx, options);
-	const privateWebKey = !options?.jwks?.disablePrivateKeyEncryption ? await symmetricDecrypt({
-		key: ctx.context.secretConfig,
-		data: JSON.parse(key.privateKey)
-	}).catch(() => {
-		throw new BetterAuthError("Failed to decrypt private key. Make sure the secret currently in use is the same as the one used to encrypt the private key. If you are using a different secret, either clean up your JWKS or disable private key encryption.");
-	}) : key.privateKey;
-	const alg = key.alg ?? options?.jwks?.keyPairConfig?.alg ?? "EdDSA";
-	const privateKey = await importJWK(JSON.parse(privateWebKey), alg);
+	const { alg, kid, privateKey } = config.resolvedKey ?? await resolveSigningKey(ctx, options);
 	const jwt = new SignJWT(payload).setProtectedHeader({
 		alg,
-		kid: key.id
+		kid
 	}).setExpirationTime(exp).setIssuer(iss ?? defaultIss).setAudience(aud ?? defaultAud);
 	if (iat) jwt.setIssuedAt(iat);
 	if (payload.sub) jwt.setSubject(payload.sub);
@@ -61,4 +80,4 @@ async function getJwtToken(ctx, options) {
 	});
 }
 //#endregion
-export { getJwtToken, signJWT };
+export { getJwtToken, resolveSigningKey, signJWT };

package/dist/plugins/jwt/types.d.mts

@@ -187,5 +187,17 @@ interface Jwk {
   alg?: JWSAlgorithms | undefined;
   crv?: ("Ed25519" | "P-256" | "P-521") | undefined;
 }
+/**
+ * A fully resolved signing key ready for JWT signing.
+ * Produced by `resolveSigningKey`, consumed by `signJWT`.
+ * Separates key resolution from signing so callers can
+ * read the `alg` before constructing the JWT payload
+ * (required for OIDC hash claims like at_hash).
+ */
+interface ResolvedSigningKey {
+  alg: string;
+  kid: string;
+  privateKey: CryptoKey | Uint8Array;
+}
 //#endregion
-export { JWKOptions, JWSAlgorithms, Jwk, JwtOptions };
+export { JWKOptions, JWSAlgorithms, Jwk, JwtOptions, ResolvedSigningKey };

package/dist/plugins/jwt/utils.d.mts

@@ -16,7 +16,7 @@ declare function toExpJWT(expirationTime: number | Date | string, iat: number):
 declare function generateExportedKeyPair(options?: JwtOptions | undefined): Promise<{
   publicWebKey: jose.JWK;
   privateWebKey: jose.JWK;
-  alg: "EdDSA" | "ES256" | "ES512" | "PS256" | "RS256";
+  alg: "RS256" | "PS256" | "ES256" | "ES512" | "EdDSA";
   cfg: {
     crv?: "Ed25519" | undefined;
   } | {