@better-auth/core 1.7.0-rc.3 → 1.7.0-rc.4

package/dist/api/index.d.mts

@@ -123,6 +123,7 @@ declare const createAuthMiddleware: {
       updateAge: number;
       expiresIn: number;
       freshAge: number;
+      cookieCacheSigner?: import("@better-auth/core").CookieCacheSigner | undefined;
       cookieRefreshCache: false | {
         enabled: true;
         updateAge: number;
@@ -252,6 +253,7 @@ declare const createAuthMiddleware: {
       updateAge: number;
       expiresIn: number;
       freshAge: number;
+      cookieCacheSigner?: import("@better-auth/core").CookieCacheSigner | undefined;
       cookieRefreshCache: false | {
         enabled: true;
         updateAge: number;

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

package/dist/db/get-tables.mjs

@@ -198,7 +198,7 @@ const buildAuthTables = (options) => {
 		account: {
 			modelName: options.account?.modelName || "account",
 			indexes: mergeTableIndexes([{
-				fields: ["issuer", "providerAccountId"],
+				fields: ["issuer", "accountId"],
 				unique: true
 			}], account?.indexes),
 			fields: {
@@ -207,10 +207,10 @@ const buildAuthTables = (options) => {
 					required: true,
 					fieldName: options.account?.fields?.issuer || "issuer"
 				},
-				providerAccountId: {
+				accountId: {
 					type: "string",
 					required: true,
-					fieldName: options.account?.fields?.providerAccountId || "providerAccountId"
+					fieldName: options.account?.fields?.accountId || "accountId"
 				},
 				providerId: {
 					type: "string",

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

@@ -10,7 +10,7 @@ declare const accountSchema: z.ZodObject<{
   updatedAt: z.ZodDefault<z.ZodDate>;
   providerId: z.ZodString;
   issuer: z.ZodString;
-  providerAccountId: z.ZodString;
+  accountId: z.ZodString;
   userId: z.ZodCoercedString<unknown>;
   accessToken: z.ZodOptional<z.ZodNullable<z.ZodString>>;
   refreshToken: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -22,7 +22,7 @@ declare const accountSchema: z.ZodObject<{
 }, z.core.$strip>;
 type BaseAccount = z.infer<typeof accountSchema>;
 /** The stable provider-side key used to recognize an account. */
-type AccountKey = Readonly<Pick<BaseAccount, "issuer" | "providerAccountId">>;
+type AccountKey = Readonly<Pick<BaseAccount, "issuer" | "accountId">>;
 /**
  * Creates the synthetic issuer used by providers without an issuer of their own.
  */

package/dist/db/schema/account.mjs

@@ -4,7 +4,7 @@ import * as z from "zod";
 const accountSchema = coreSchema.extend({
 	providerId: z.string(),
 	issuer: z.string(),
-	providerAccountId: z.string(),
+	accountId: z.string(),
 	userId: z.coerce.string(),
 	accessToken: z.string().nullish(),
 	refreshToken: z.string().nullish(),

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, UserProvisioningSource, ValidateUserInfoAction, ValidateUserInfoMethod, ValidateUserInfoOAuthInfo, ValidateUserInfoResult, ValidateUserInfoSSOInfo, ValidateUserInfoSource } from "./types/init-options.mjs";
-import { BetterAuthCookie, BetterAuthCookies } from "./types/cookie.mjs";
+import { BetterAuthCookie, BetterAuthCookies, CookieCachePayload } from "./types/cookie.mjs";
 import { SecretConfig } from "./types/secret.mjs";
-import { AuthContext, BetterAuthPluginRegistry, BetterAuthPluginRegistryIdentifier, GenericEndpointContext, InfoContext, InternalAdapter, PluginContext } from "./types/context.mjs";
+import { AuthContext, BetterAuthPluginRegistry, BetterAuthPluginRegistryIdentifier, CookieCacheSigner, 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 type { 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 };
+export type { AuthContext, Awaitable, AwaitableFunction, BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthClientOptions, BetterAuthClientPlugin, BetterAuthCookie, BetterAuthCookies, BetterAuthDBOptions, BetterAuthOptions, BetterAuthPlugin, BetterAuthPluginErrorCodePart, BetterAuthPluginRegistry, BetterAuthPluginRegistryIdentifier, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, ClientAtomListener, ClientFetchOption, ClientStore, CookieCachePayload, CookieCacheSigner, 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-rc.3";
+const INSTRUMENTATION_VERSION = "1.7.0-rc.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/social-providers/apple.d.mts

@@ -70,7 +70,7 @@ declare const apple: (options: AppleOptions) => {
   name: string;
   accountSubject: ({ profile }: OAuthAccountKeyContext<AppleProfile>) => string;
   accountIssuer: string;
-  createAuthorizationURL({ state, scopes, redirectURI, additionalParams }: {
+  createAuthorizationURL({ state, scopes, redirectURI, additionalParams, codeVerifier }: {
     state: string;
     codeVerifier: string;
     scopes?: string[] | undefined;

package/dist/social-providers/apple.mjs

@@ -14,7 +14,7 @@ const apple = (options) => {
 		name: "Apple",
 		accountSubject: ({ profile }) => profile.sub,
 		accountIssuer: "https://appleid.apple.com",
-		async createAuthorizationURL({ state, scopes, redirectURI, additionalParams }) {
+		async createAuthorizationURL({ state, scopes, redirectURI, additionalParams, codeVerifier }) {
 			if (!getPrimaryClientId(options.clientId) || !options.clientSecret) {
 				logger.error("Client ID and client secret are required for Apple. Make sure to provide them in the options.");
 				throw new BetterAuthError("CLIENT_ID_AND_SECRET_REQUIRED");
@@ -29,6 +29,7 @@ const apple = (options) => {
 				scopes: _scope,
 				state,
 				redirectURI,
+				codeVerifier,
 				responseMode: "form_post",
 				responseType: "code id_token",
 				additionalParams

package/dist/social-providers/index.d.mts

@@ -45,7 +45,7 @@ declare const socialProviders: {
     name: string;
     accountSubject: ({ profile }: OAuthAccountKeyContext<AppleProfile>) => string;
     accountIssuer: string;
-    createAuthorizationURL({ state, scopes, redirectURI, additionalParams }: {
+    createAuthorizationURL({ state, scopes, redirectURI, additionalParams, codeVerifier }: {
       state: string;
       codeVerifier: string;
       scopes?: string[] | undefined;

package/dist/types/context.d.mts

@@ -9,7 +9,7 @@ import { BetterAuthPlugin } from "./plugin.mjs";
 import { BetterAuthOptions, BetterAuthRateLimitOptions, UserProvisioningSource } from "./init-options.mjs";
 import { Account, AccountKey } from "../db/schema/account.mjs";
 import "../db/index.mjs";
-import { BetterAuthCookie, BetterAuthCookies } from "./cookie.mjs";
+import { BetterAuthCookie, BetterAuthCookies, CookieCachePayload } from "./cookie.mjs";
 import { SecretConfig } from "./secret.mjs";
 import { OAuthProvider } from "../oauth2/oauth-provider.mjs";
 import "../oauth2/index.mjs";
@@ -54,6 +54,16 @@ type BetterAuthPluginRegistryIdentifier = keyof BetterAuthPluginRegistry<unknown
 type GenericEndpointContext<Options extends BetterAuthOptions = BetterAuthOptions> = EndpointContext<string, any> & {
   context: AuthContext<Options>;
 };
+/**
+ * Signs and verifies session cookie-cache values.
+ */
+type CookieCacheSigner = {
+  sign: (ctx: GenericEndpointContext, payload: CookieCachePayload, expiresIn: number) => Promise<string>;
+  verify: (ctx: GenericEndpointContext, token: string) => Promise<{
+    payload: CookieCachePayload;
+    expiresAt: number;
+  } | null>;
+};
 interface InternalAdapter<_Options extends BetterAuthOptions = BetterAuthOptions> {
   createOAuthUser(user: Omit<User, "id" | "createdAt" | "updatedAt">, account: Omit<Account, "userId" | "id" | "createdAt" | "updatedAt"> & Partial<Account>): Promise<{
     user: User;
@@ -261,6 +271,7 @@ type AuthContext<Options extends BetterAuthOptions = BetterAuthOptions> = Plugin
     updateAge: number;
     expiresIn: number;
     freshAge: number;
+    cookieCacheSigner?: CookieCacheSigner | undefined;
     cookieRefreshCache: false | {
       enabled: true;
       updateAge: number;
@@ -330,4 +341,4 @@ type AuthContext<Options extends BetterAuthOptions = BetterAuthOptions> = Plugin
   runInBackgroundOrAwait: (promise: Promise<unknown> | void) => Awaitable<unknown>;
 };
 //#endregion
-export { AuthContext, BetterAuthPluginRegistry, BetterAuthPluginRegistryIdentifier, GenericEndpointContext, InfoContext, InternalAdapter, PluginContext };
+export { AuthContext, BetterAuthPluginRegistry, BetterAuthPluginRegistryIdentifier, CookieCacheSigner, GenericEndpointContext, InfoContext, InternalAdapter, PluginContext };

package/dist/types/cookie.d.mts

@@ -1,3 +1,6 @@
+import { Session } from "../db/schema/session.mjs";
+import { User } from "../db/schema/user.mjs";
+import "../db/index.mjs";
 import { CookieOptions } from "better-call";
 //#region src/types/cookie.d.ts
 type BetterAuthCookie = {
@@ -10,5 +13,14 @@ type BetterAuthCookies = {
   accountData: BetterAuthCookie;
   dontRememberToken: BetterAuthCookie;
 };
+/**
+ * A validated cookie-cache payload, including legacy payloads without a version.
+ */
+type CookieCachePayload = {
+  session: Session & Record<string, unknown>;
+  user: User & Record<string, unknown>;
+  updatedAt: number;
+  version?: string | undefined;
+};
 //#endregion
-export { BetterAuthCookie, BetterAuthCookies };
+export { BetterAuthCookie, BetterAuthCookies, CookieCachePayload };

package/dist/types/index.d.mts

@@ -1,9 +1,9 @@
 import { Awaitable, AwaitableFunction, LiteralString, LiteralUnion, Prettify, Primitive, UnionToIntersection } from "./helper.mjs";
 import { BetterAuthPlugin, BetterAuthPluginErrorCodePart, HookEndpointContext } from "./plugin.mjs";
 import { BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthDBOptions, BetterAuthOptions, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, DynamicBaseURLConfig, GenerateIdFn, StoreIdentifierOption, UserProvisioningSource, ValidateUserInfoAction, ValidateUserInfoMethod, ValidateUserInfoOAuthInfo, ValidateUserInfoResult, ValidateUserInfoSSOInfo, ValidateUserInfoSource } from "./init-options.mjs";
-import { BetterAuthCookie, BetterAuthCookies } from "./cookie.mjs";
+import { BetterAuthCookie, BetterAuthCookies, CookieCachePayload } from "./cookie.mjs";
 import { SecretConfig } from "./secret.mjs";
-import { AuthContext, BetterAuthPluginRegistry, BetterAuthPluginRegistryIdentifier, GenericEndpointContext, InfoContext, InternalAdapter, PluginContext } from "./context.mjs";
+import { AuthContext, BetterAuthPluginRegistry, BetterAuthPluginRegistryIdentifier, CookieCacheSigner, GenericEndpointContext, InfoContext, InternalAdapter, PluginContext } from "./context.mjs";
 import { BetterAuthClientOptions, BetterAuthClientPlugin, ClientAtomListener, ClientFetchOption, ClientStore } from "./plugin-client.mjs";
 import { StandardSchemaV1 as StandardSchemaV1$1 } from "@standard-schema/spec";
-export type { 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$1 as StandardSchemaV1, StoreIdentifierOption, UnionToIntersection, UserProvisioningSource, ValidateUserInfoAction, ValidateUserInfoMethod, ValidateUserInfoOAuthInfo, ValidateUserInfoResult, ValidateUserInfoSSOInfo, ValidateUserInfoSource };
+export type { AuthContext, Awaitable, AwaitableFunction, BaseURLConfig, BetterAuthAdvancedOptions, BetterAuthClientOptions, BetterAuthClientPlugin, BetterAuthCookie, BetterAuthCookies, BetterAuthDBOptions, BetterAuthOptions, BetterAuthPlugin, BetterAuthPluginErrorCodePart, BetterAuthPluginRegistry, BetterAuthPluginRegistryIdentifier, BetterAuthRateLimitOptions, BetterAuthRateLimitRule, BetterAuthRateLimitStorage, ClientAtomListener, ClientFetchOption, ClientStore, CookieCachePayload, CookieCacheSigner, DynamicBaseURLConfig, GenerateIdFn, GenericEndpointContext, HookEndpointContext, InfoContext, InternalAdapter, LiteralString, LiteralUnion, PluginContext, Prettify, Primitive, SecretConfig, StandardSchemaV1$1 as StandardSchemaV1, StoreIdentifierOption, UnionToIntersection, UserProvisioningSource, ValidateUserInfoAction, ValidateUserInfoMethod, ValidateUserInfoOAuthInfo, ValidateUserInfoResult, ValidateUserInfoSSOInfo, ValidateUserInfoSource };

package/dist/types/init-options.d.mts

@@ -978,20 +978,6 @@ type BetterAuthOptions = {
        * @default "compact"
        */
       strategy?: "compact" | "jwt" | "jwe";
-      /**
-       * JWT-specific configuration for `strategy: "jwt"`.
-       */
-      jwt?: {
-        /**
-         * Which signing key is used for cookie-cache JWTs.
-         *
-         * - `"secret"`: uses the Better Auth secret with HS256.
-         * - `"jwt-plugin"`: uses the installed `jwt()` plugin's asymmetric signing keys.
-         *
-         * @default "secret"
-         */
-        signingKey?: "secret" | "jwt-plugin";
-      };
       /**
        * Controls stateless cookie cache refresh behavior.
        *

package/dist/utils/email.d.mts

@@ -0,0 +1,19 @@
+//#region src/utils/email.d.ts
+interface PlaceholderEmailOptions {
+  /**
+   * A stable identifier that distinguishes the account within the namespace.
+   */
+  identifier: string;
+  /**
+   * A namespace that distinguishes identical identifiers from different sources.
+   */
+  namespace: string;
+}
+/**
+ * Creates a stable, non-routable email address for an account without an email.
+ *
+ * @throws TypeError if the generated email is invalid.
+ */
+declare function createPlaceholderEmail({ identifier, namespace }: PlaceholderEmailOptions): string;
+//#endregion
+export { PlaceholderEmailOptions, createPlaceholderEmail };

package/dist/utils/email.mjs

@@ -0,0 +1,18 @@
+import * as z from "zod";
+//#region src/utils/email.ts
+/**
+* @see https://www.rfc-editor.org/rfc/rfc6761.html#section-6.4
+*/
+const PLACEHOLDER_EMAIL_DOMAIN = "placeholder.invalid";
+/**
+* Creates a stable, non-routable email address for an account without an email.
+*
+* @throws TypeError if the generated email is invalid.
+*/
+function createPlaceholderEmail({ identifier, namespace }) {
+	const result = z.email().safeParse(`${identifier}@${namespace}.${PLACEHOLDER_EMAIL_DOMAIN}`);
+	if (!result.success) throw new TypeError("Invalid placeholder email");
+	return result.data;
+}
+//#endregion
+export { createPlaceholderEmail };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@better-auth/core",
-  "version": "1.7.0-rc.3",
+  "version": "1.7.0-rc.4",
   "description": "The most comprehensive authentication framework for TypeScript.",
   "type": "module",
   "license": "MIT",
@@ -164,8 +164,8 @@
     "@better-fetch/fetch": "1.3.1",
     "@cloudflare/workers-types": "^4.20250121.0",
     "@opentelemetry/api": "^1.9.1",
-    "@opentelemetry/sdk-trace-base": "^2.8.0",
-    "@opentelemetry/sdk-trace-node": "^2.8.0",
+    "@opentelemetry/sdk-trace-base": "^2.10.0",
+    "@opentelemetry/sdk-trace-node": "^2.10.0",
     "better-call": "1.3.7",
     "jose": "^6.2.3",
     "kysely": "^0.28.17 || ^0.29.0",

package/src/db/get-tables.ts

@@ -253,7 +253,7 @@ const buildAuthTables = (options: BetterAuthOptions): BetterAuthDBSchema => {
 			indexes: mergeTableIndexes(
 				[
 					{
-						fields: ["issuer", "providerAccountId"],
+						fields: ["issuer", "accountId"],
 						unique: true,
 					},
 				],
@@ -265,11 +265,10 @@ const buildAuthTables = (options: BetterAuthOptions): BetterAuthDBSchema => {
 					required: true,
 					fieldName: options.account?.fields?.issuer || "issuer",
 				},
-				providerAccountId: {
+				accountId: {
 					type: "string",
 					required: true,
-					fieldName:
-						options.account?.fields?.providerAccountId || "providerAccountId",
+					fieldName: options.account?.fields?.accountId || "accountId",
 				},
 				providerId: {
 					type: "string",

package/src/db/schema/account.ts

@@ -10,7 +10,7 @@ import { coreSchema } from "./shared";
 export const accountSchema = coreSchema.extend({
 	providerId: z.string(),
 	issuer: z.string(),
-	providerAccountId: z.string(),
+	accountId: z.string(),
 	userId: z.coerce.string(),
 	accessToken: z.string().nullish(),
 	refreshToken: z.string().nullish(),
@@ -39,9 +39,7 @@ export const accountSchema = coreSchema.extend({
 export type BaseAccount = z.infer<typeof accountSchema>;
 
 /** The stable provider-side key used to recognize an account. */
-export type AccountKey = Readonly<
-	Pick<BaseAccount, "issuer" | "providerAccountId">
->;
+export type AccountKey = Readonly<Pick<BaseAccount, "issuer" | "accountId">>;
 
 function encodeAccountIssuerProviderId(providerId: string): string {
 	return encodeURIComponent(providerId);

package/src/db/schema/user.ts

@@ -9,7 +9,7 @@ import { coreSchema } from "./shared";
 export const userSchema = coreSchema.extend({
 	// TODO(#9124): widen to nullish in v2. OAuth providers (Discord phone-only,
 	// Apple subsequent sign-ins, etc.) can legitimately omit email; identity
-	// must key on (issuer, providerAccountId) per OpenID Connect Core §5.7.
+	// must key on (issuer, accountId) per OpenID Connect Core §5.7.
 	email: z.string().transform((val) => val.toLowerCase()),
 	emailVerified: z.boolean().default(false),
 	name: z.string(),

package/src/social-providers/apple.ts

@@ -89,6 +89,7 @@ export const apple = (options: AppleOptions) => {
 			scopes,
 			redirectURI,
 			additionalParams,
+			codeVerifier,
 		}) {
 			if (!getPrimaryClientId(options.clientId) || !options.clientSecret) {
 				logger.error(
@@ -106,6 +107,7 @@ export const apple = (options: AppleOptions) => {
 				scopes: _scope,
 				state,
 				redirectURI,
+				codeVerifier,
 				responseMode: "form_post",
 				responseType: "code id_token",
 				additionalParams,

package/src/types/context.ts

@@ -12,7 +12,11 @@ import type { DBAdapter, Where } from "../db/adapter";
 import type { AccountKey } from "../db/schema/account";
 import type { createLogger } from "../env";
 import type { OAuthProvider } from "../oauth2";
-import type { BetterAuthCookie, BetterAuthCookies } from "./cookie";
+import type {
+	BetterAuthCookie,
+	BetterAuthCookies,
+	CookieCachePayload,
+} from "./cookie";
 import type { Awaitable, LiteralString } from "./helper";
 import type {
 	BetterAuthOptions,
@@ -86,6 +90,24 @@ export type GenericEndpointContext<
 	context: AuthContext<Options>;
 };
 
+/**
+ * Signs and verifies session cookie-cache values.
+ */
+export type CookieCacheSigner = {
+	sign: (
+		ctx: GenericEndpointContext,
+		payload: CookieCachePayload,
+		expiresIn: number,
+	) => Promise<string>;
+	verify: (
+		ctx: GenericEndpointContext,
+		token: string,
+	) => Promise<{
+		payload: CookieCachePayload;
+		expiresAt: number;
+	} | null>;
+};
+
 export interface InternalAdapter<
 	_Options extends BetterAuthOptions = BetterAuthOptions,
 > {
@@ -403,6 +425,7 @@ export type AuthContext<Options extends BetterAuthOptions = BetterAuthOptions> =
 				updateAge: number;
 				expiresIn: number;
 				freshAge: number;
+				cookieCacheSigner?: CookieCacheSigner | undefined;
 				cookieRefreshCache:
 					| false
 					| {

package/src/types/cookie.ts

@@ -1,4 +1,5 @@
 import type { CookieOptions } from "better-call";
+import type { Session, User } from "../db";
 
 export type BetterAuthCookie = { name: string; attributes: CookieOptions };
 
@@ -8,3 +9,13 @@ export type BetterAuthCookies = {
 	accountData: BetterAuthCookie;
 	dontRememberToken: BetterAuthCookie;
 };
+
+/**
+ * A validated cookie-cache payload, including legacy payloads without a version.
+ */
+export type CookieCachePayload = {
+	session: Session & Record<string, unknown>;
+	user: User & Record<string, unknown>;
+	updatedAt: number;
+	version?: string | undefined;
+};

package/src/types/index.ts

@@ -3,6 +3,7 @@ export type {
 	AuthContext,
 	BetterAuthPluginRegistry,
 	BetterAuthPluginRegistryIdentifier,
+	CookieCacheSigner,
 	GenericEndpointContext,
 	InfoContext,
 	InternalAdapter,
@@ -11,6 +12,7 @@ export type {
 export type {
 	BetterAuthCookie,
 	BetterAuthCookies,
+	CookieCachePayload,
 } from "./cookie";
 export type * from "./helper";
 export type {

package/src/types/init-options.ts

@@ -1089,20 +1089,6 @@ export type BetterAuthOptions = {
 					 * @default "compact"
 					 */
 					strategy?: "compact" | "jwt" | "jwe";
-					/**
-					 * JWT-specific configuration for `strategy: "jwt"`.
-					 */
-					jwt?: {
-						/**
-						 * Which signing key is used for cookie-cache JWTs.
-						 *
-						 * - `"secret"`: uses the Better Auth secret with HS256.
-						 * - `"jwt-plugin"`: uses the installed `jwt()` plugin's asymmetric signing keys.
-						 *
-						 * @default "secret"
-						 */
-						signingKey?: "secret" | "jwt-plugin";
-					};
 					/**
 					 * Controls stateless cookie cache refresh behavior.
 					 *

package/src/utils/email.ts

@@ -0,0 +1,36 @@
+import * as z from "zod";
+
+/**
+ * @see https://www.rfc-editor.org/rfc/rfc6761.html#section-6.4
+ */
+const PLACEHOLDER_EMAIL_DOMAIN = "placeholder.invalid";
+
+export interface PlaceholderEmailOptions {
+	/**
+	 * A stable identifier that distinguishes the account within the namespace.
+	 */
+	identifier: string;
+	/**
+	 * A namespace that distinguishes identical identifiers from different sources.
+	 */
+	namespace: string;
+}
+
+/**
+ * Creates a stable, non-routable email address for an account without an email.
+ *
+ * @throws TypeError if the generated email is invalid.
+ */
+export function createPlaceholderEmail({
+	identifier,
+	namespace,
+}: PlaceholderEmailOptions): string {
+	const result = z
+		.email()
+		.safeParse(`${identifier}@${namespace}.${PLACEHOLDER_EMAIL_DOMAIN}`);
+	if (!result.success) {
+		throw new TypeError("Invalid placeholder email");
+	}
+
+	return result.data;
+}