refactor: rename cookie 'options' to 'attributes' for consistency

github-actions[bot] · himself65 · github-actions[bot] · commit 4b87be55d9b3 · 2026-01-14T20:46:27.000Z
- Update BetterAuthCookie type to use 'attributes' instead of union type
- Rename all cookie.options references to cookie.attributes across codebase
- Update core cookie implementation (cookies/index.ts, session-store.ts)
- Update plugin files (multi-session, two-factor, admin, oidc-provider, mcp)
- Update state management (state.ts)
- Update external packages (expo, passkey)
- Update tests to reflect the change

This standardizes the API and avoids breaking changes by using the same
property name that createAuthCookie() returns.

Co-authored-by: Alex Yang &lt;himself65@users.noreply.github.com&gt;
diff --git a/packages/better-auth/src/cookies/cookies.test.ts b/packages/better-auth/src/cookies/cookies.test.ts
@@ -168,10 +168,10 @@ describe("cookie configuration", () => {
 
 		const cookies = getCookies(options);
 
-		expect(cookies.sessionToken.options.secure).toBe(true);
+		expect(cookies.sessionToken.attributes.secure).toBe(true);
 		expect(cookies.sessionToken.name).toContain("test-prefix.session_token");
-		expect(cookies.sessionData.options.sameSite).toBe("lax");
-		expect(cookies.sessionData.options.domain).toBe("example.com");
+		expect(cookies.sessionData.attributes.sameSite).toBe("lax");
+		expect(cookies.sessionData.attributes.domain).toBe("example.com");
 	});
 });
 
@@ -1207,11 +1207,11 @@ describe("parse cookies", () => {
 });
 
 describe("expireCookie", () => {
-	it("preserves options", () => {
+	it("preserves attributes", () => {
 		const setCookie = vi.fn();
 		expireCookie({ setCookie } as any, {
 			name: "test",
-			options: {
+			attributes: {
 				path: "/custom",
 				httpOnly: true,
 			},
diff --git a/packages/better-auth/src/cookies/index.ts b/packages/better-auth/src/cookies/index.ts
@@ -59,7 +59,7 @@ export function createCookieGetter(options: BetterAuthOptions) {
 
 		return {
 			name: `${secureCookiePrefix}${name}`,
-			options: {
+			attributes: {
 				secure: !!secureCookiePrefix,
 				sameSite: "lax",
 				path: "/",
@@ -90,23 +90,23 @@ export function getCookies(options: BetterAuthOptions) {
 	return {
 		sessionToken: {
 			name: sessionToken.name,
-			options: sessionToken.options,
+			attributes: sessionToken.attributes,
 		},
 		/**
 		 * This cookie is used to store the session data in the cookie
 		 * This is useful for when you want to cache the session in the cookie
 		 */
 		sessionData: {
 			name: sessionData.name,
-			options: sessionData.options,
+			attributes: sessionData.attributes,
 		},
 		dontRememberToken: {
 			name: dontRememberToken.name,
-			options: dontRememberToken.options,
+			attributes: dontRememberToken.attributes,
 		},
 		accountData: {
 			name: accountData.name,
-			options: accountData.options,
+			attributes: accountData.attributes,
 		},
 	};
 }
@@ -158,10 +158,10 @@ export async function setCookieCache(
 		};
 
 		const options = {
-			...ctx.context.authCookies.sessionData.options,
+			...ctx.context.authCookies.sessionData.attributes,
 			maxAge: dontRememberMe
 				? undefined
-				: ctx.context.authCookies.sessionData.options.maxAge,
+				: ctx.context.authCookies.sessionData.attributes.maxAge,
 		};
 
 		const expiresAtDate = getDate(options.maxAge || 60, "sec").getTime();
@@ -250,7 +250,7 @@ export async function setSessionCookie(
 	dontRememberMe =
 		dontRememberMe !== undefined ? dontRememberMe : !!dontRememberMeCookie;
 
-	const options = ctx.context.authCookies.sessionToken.options;
+	const options = ctx.context.authCookies.sessionToken.attributes;
 	const maxAge = dontRememberMe
 		? undefined
 		: ctx.context.sessionConfig.expiresIn;
@@ -270,7 +270,7 @@ export async function setSessionCookie(
 			ctx.context.authCookies.dontRememberToken.name,
 			"true",
 			ctx.context.secret,
-			ctx.context.authCookies.dontRememberToken.options,
+			ctx.context.authCookies.dontRememberToken.attributes,
 		);
 	}
 	await setCookieCache(ctx, session, dontRememberMe);
@@ -302,7 +302,7 @@ export function expireCookie(
 	cookie: BetterAuthCookie,
 ) {
 	ctx.setCookie(cookie.name, "", {
-		...cookie.options,
+		...cookie.attributes,
 		maxAge: 0,
 	});
 }
@@ -320,7 +320,7 @@ export function deleteSessionCookie(
 		//clean up the account data chunks
 		const accountStore = createAccountStore(
 			ctx.context.authCookies.accountData.name,
-			ctx.context.authCookies.accountData.options,
+			ctx.context.authCookies.accountData.attributes,
 			ctx,
 		);
 		const cleanCookies = accountStore.clean();
@@ -334,7 +334,7 @@ export function deleteSessionCookie(
 	// Use createSessionStore to clean up all session data chunks
 	const sessionStore = createSessionStore(
 		ctx.context.authCookies.sessionData.name,
-		ctx.context.authCookies.sessionData.options,
+		ctx.context.authCookies.sessionData.attributes,
 		ctx,
 	);
 	const cleanCookies = sessionStore.clean();
diff --git a/packages/better-auth/src/cookies/session-store.ts b/packages/better-auth/src/cookies/session-store.ts
@@ -16,7 +16,7 @@ const CHUNK_SIZE = ALLOWED_COOKIE_SIZE - ESTIMATED_EMPTY_COOKIE_SIZE;
 interface Cookie {
 	name: string;
 	value: string;
-	options: CookieOptions;
+	attributes: CookieOptions;
 }
 
 type Chunks = Record<string, string>;
@@ -135,7 +135,7 @@ function getCleanCookies(
 		cleanedChunks[name] = {
 			name,
 			value: "",
-			options: { ...cookieOptions, maxAge: 0 },
+			attributes: { ...cookieOptions, maxAge: 0 },
 		};
 	}
 	return cleanedChunks;
@@ -191,7 +191,7 @@ const storeFactory =
 					{
 						name: cookieName,
 						value,
-						options: { ...cookieOptions, ...options },
+						attributes: { ...cookieOptions, ...options },
 					},
 					chunks,
 					logger,
@@ -222,7 +222,7 @@ const storeFactory =
 			 */
 			setCookies(cookies: Cookie[]): void {
 				for (const cookie of cookies) {
-					ctx.setCookie(cookie.name, cookie.value, cookie.options);
+					ctx.setCookie(cookie.name, cookie.value, cookie.attributes);
 				}
 			},
 		};
@@ -282,7 +282,7 @@ export async function setAccountCookie(
 	const accountDataCookie = c.context.authCookies.accountData;
 	const options = {
 		maxAge: 60 * 5,
-		...accountDataCookie.options,
+		...accountDataCookie.attributes,
 	};
 	const data = await symmetricEncodeJWT(
 		accountData,
diff --git a/packages/better-auth/src/plugins/admin/routes.ts b/packages/better-auth/src/plugins/admin/routes.ts
@@ -1103,7 +1103,7 @@ export const impersonateUser = (opts: AdminOptions) =>
 				adminCookieProp.name,
 				`${ctx.context.session.session.token}:${dontRememberMeCookie || ""}`,
 				ctx.context.secret,
-				authCookies.sessionToken.options,
+				authCookies.sessionToken.attributes,
 			);
 			await setSessionCookie(
 				ctx,
diff --git a/packages/better-auth/src/plugins/multi-session/index.ts b/packages/better-auth/src/plugins/multi-session/index.ts
@@ -179,7 +179,7 @@ export const multiSession = (options?: MultiSessionConfig | undefined) => {
 					if (!session || session.session.expiresAt < new Date()) {
 						expireCookie(ctx, {
 							name: multiSessionCookieName,
-							options: ctx.context.authCookies.sessionToken.options,
+							attributes: ctx.context.authCookies.sessionToken.attributes,
 						});
 						throw APIError.from(
 							"UNAUTHORIZED",
@@ -254,7 +254,7 @@ export const multiSession = (options?: MultiSessionConfig | undefined) => {
 					await ctx.context.internalAdapter.deleteSession(sessionToken);
 					expireCookie(ctx, {
 						name: multiSessionCookieName,
-						options: ctx.context.authCookies.sessionToken.options,
+						attributes: ctx.context.authCookies.sessionToken.attributes,
 					});
 					const isActive = ctx.context.session?.session.token === sessionToken;
 					if (!isActive) return ctx.json({ status: true });
@@ -332,7 +332,7 @@ export const multiSession = (options?: MultiSessionConfig | undefined) => {
 							cookieName,
 							sessionToken,
 							ctx.context.secret,
-							sessionCookieConfig.options,
+							sessionCookieConfig.attributes,
 						);
 					}),
 				},
@@ -360,7 +360,7 @@ export const multiSession = (options?: MultiSessionConfig | undefined) => {
 													SECURE_COOKIE_PREFIX.toLowerCase(),
 													SECURE_COOKIE_PREFIX,
 												),
-											options: ctx.context.authCookies.sessionToken.options,
+											attributes: ctx.context.authCookies.sessionToken.attributes,
 										});
 										return verifiedToken;
 									}
diff --git a/packages/better-auth/src/plugins/two-factor/index.ts b/packages/better-auth/src/plugins/two-factor/index.ts
@@ -354,7 +354,7 @@ export const twoFactor = <O extends TwoFactorOptions>(options?: O) => {
 									newTrustDeviceCookie.name,
 									`${newToken}!${data.session.token}`,
 									ctx.context.secret,
-									trustDeviceCookieAttrs.options,
+									trustDeviceCookieAttrs.attributes,
 								);
 								return;
 							}
@@ -382,7 +382,7 @@ export const twoFactor = <O extends TwoFactorOptions>(options?: O) => {
 							twoFactorCookie.name,
 							identifier,
 							ctx.context.secret,
-							twoFactorCookie.options,
+							twoFactorCookie.attributes,
 						);
 						return ctx.json({
 							twoFactorRedirect: true,
diff --git a/packages/better-auth/src/plugins/two-factor/verify-two-factor.ts b/packages/better-auth/src/plugins/two-factor/verify-two-factor.ts
@@ -95,7 +95,7 @@ export async function verifyTwoFactor(ctx: GenericEndpointContext) {
 						trustDeviceCookie.name,
 						`${token}!${session.token}`,
 						ctx.context.secret,
-						trustDeviceCookie.options,
+						trustDeviceCookie.attributes,
 					);
 					// delete the dont remember me cookie
 					expireCookie(ctx, ctx.context.authCookies.dontRememberToken);
diff --git a/packages/better-auth/src/state.ts b/packages/better-auth/src/state.ts
@@ -71,7 +71,7 @@ export async function generateGenericState(
 			},
 		);
 
-		c.setCookie(stateCookie.name, encryptedData, stateCookie.options);
+		c.setCookie(stateCookie.name, encryptedData, stateCookie.attributes);
 
 		return {
 			state,
@@ -92,7 +92,7 @@ export async function generateGenericState(
 		stateCookie.name,
 		state,
 		c.context.secret,
-		stateCookie.options,
+		stateCookie.attributes,
 	);
 
 	const expiresAt = new Date();
diff --git a/packages/core/src/types/cookie.ts b/packages/core/src/types/cookie.ts
@@ -1,6 +1,6 @@
 import type { CookieOptions } from "better-call";
 
-export type BetterAuthCookie = { name: string; options: CookieOptions };
+export type BetterAuthCookie = { name: string; attributes: CookieOptions };
 
 export type BetterAuthCookies = {
 	sessionToken: BetterAuthCookie;
diff --git a/packages/expo/src/routes.ts b/packages/expo/src/routes.ts
@@ -21,7 +21,7 @@ export const expoAuthorizationProxy = createAuthEndpoint(
 			ctx.setCookie(
 				oauthStateCookie.name,
 				oauthState,
-				oauthStateCookie.options,
+				oauthStateCookie.attributes,
 			);
 			return ctx.redirect(ctx.query.authorizationURL);
 		}
@@ -41,7 +41,7 @@ export const expoAuthorizationProxy = createAuthEndpoint(
 			stateCookie.name,
 			state,
 			ctx.context.secret,
-			stateCookie.options,
+			stateCookie.attributes,
 		);
 		return ctx.redirect(ctx.query.authorizationURL);
 	},
diff --git a/packages/passkey/src/routes.ts b/packages/passkey/src/routes.ts
@@ -220,7 +220,7 @@ export const generatePasskeyRegistrationOptions = (
 				verificationToken,
 				ctx.context.secret,
 				{
-					...webAuthnCookie.options,
+					...webAuthnCookie.attributes,
 					maxAge: maxAgeInSeconds,
 				},
 			);
@@ -386,7 +386,7 @@ export const generatePasskeyAuthenticationOptions = (
 				verificationToken,
 				ctx.context.secret,
 				{
-					...webAuthnCookie.options,
+					...webAuthnCookie.attributes,
 					maxAge: maxAgeInSeconds,
 				},
 			);
