auth-vir 5.0.4 → 5.2.0

package/README.md

@@ -156,12 +156,12 @@ export async function createUser(
  */
 export async function getAuthenticatedUser(request: ClientRequest) {
     const userId = (
-        await extractUserIdFromRequestHeaders<MyUserId>(
-            request.getHeaders(),
+        await extractUserIdFromRequestHeaders<MyUserId>({
+            headers: request.getHeaders(),
             jwtParams,
-            csrfOption,
-            AuthCookie.Auth,
-        )
+            csrfHeaderNameOption: csrfOption,
+            cookieName: AuthCookie.Auth,
+        })
     )?.userId;
     const user = userId ? findUserInDatabaseById(userId) : undefined;
 

package/dist/auth-client/backend-auth.client.d.ts

@@ -137,6 +137,25 @@ export type BackendAuthClientConfig<DatabaseUser extends AnyObject, UserId exten
      * @default {minutes: 5}
      */
     allowedClockSkew: Readonly<AnyDuration>;
+    /**
+     * Optional separate origin for the CSRF cookie's `Domain` attribute. When set, the
+     * non-`HttpOnly` CSRF cookie will use this origin's hostname instead of `serviceOrigin`.
+     *
+     * This is useful when the backend and frontend live on different subdomains that don't
+     * share a common parent narrower than the top-level domain. The `HttpOnly` auth cookie
+     * stays scoped to `serviceOrigin` (protecting it from unrelated subdomains), while the CSRF
+     * cookie uses the broader domain so frontend JavaScript can read it via `document.cookie`.
+     *
+     * The CSRF token alone is not a security risk — it is only meaningful when paired with the
+     * JWT embedded in the `HttpOnly` auth cookie.
+     */
+    csrfCookieOrigin: string;
+    /**
+     * Optional suffix appended to cookie names (e.g., `'staging'` produces `auth-staging`,
+     * `auth-vir-csrf-staging`). When `undefined`, cookie names are unchanged. Useful for
+     * running multiple environments on the same domain without cookie collisions.
+     */
+    cookieNameSuffix: string;
 }>>;
 /**
  * An auth client for creating and validating JWTs embedded in cookies. This should only be used in
@@ -149,6 +168,11 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
     protected readonly config: BackendAuthClientConfig<DatabaseUser, UserId, AssumedUserParams>;
     protected cachedParsedJwtKeys: Record<string, Readonly<JwtKeys>>;
     constructor(config: BackendAuthClientConfig<DatabaseUser, UserId, AssumedUserParams>);
+    /**
+     * Resolves the origin to use for CSRF cookie generation. Returns `csrfCookieOrigin` if
+     * configured, otherwise falls back to the auth cookie origin.
+     */
+    protected resolveCsrfCookieOrigin(authCookieOrigin: string): string;
     /** Conditionally logs a message if logging is enabled for the given user context. */
     protected logForUser(params: {
         user: DatabaseUser | undefined;
@@ -218,6 +242,8 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
         cookieParams: Readonly<CookieParams>;
         existingUserIdResult: Readonly<UserIdResult<UserId>>;
     }): Promise<Record<string, string | string[]>>;
+    /** Generates login headers for a brand-new session (no existing JWT to reuse). */
+    protected generateFreshLoginHeaders(userId: UserId, cookieParams: Readonly<CookieParams>): Promise<Record<string, string[]>>;
     /** Use these headers to log a user in. */
     createLoginHeaders({ userId, requestHeaders, isSignUpCookie, }: {
         userId: UserId;

package/dist/auth-client/backend-auth.client.js

@@ -1,7 +1,8 @@
 import { ensureArray, } from '@augment-vir/common';
 import { calculateRelativeDate, createUtcFullDate, getNowInUtcTimezone, isDateAfter, } from 'date-vir';
-import { extractUserIdFromRequestHeaders, generateLogoutHeaders, generateSuccessfulLoginHeaders, insecureExtractUserIdFromCookieAlone, } from '../auth.js';
-import { AuthCookie, generateAuthCookie, generateCsrfCookie } from '../cookie.js';
+import { extractUserIdFromRequestHeaders, generateLogoutHeaders, insecureExtractUserIdFromCookieAlone, } from '../auth.js';
+import { AuthCookie, clearCsrfCookie, generateAuthCookie, generateCsrfCookie, resolveCookieName, } from '../cookie.js';
+import { generateCsrfToken } from '../csrf-token.js';
 import { AuthHeaderName, mergeHeaderValues } from '../headers.js';
 import { parseJwtKeys } from '../jwt/jwt-keys.js';
 import { defaultAllowedClockSkew } from '../jwt/jwt.js';
@@ -28,6 +29,13 @@ export class BackendAuthClient {
     constructor(config) {
         this.config = config;
     }
+    /**
+     * Resolves the origin to use for CSRF cookie generation. Returns `csrfCookieOrigin` if
+     * configured, otherwise falls back to the auth cookie origin.
+     */
+    resolveCsrfCookieOrigin(authCookieOrigin) {
+        return this.config.csrfCookieOrigin || authCookieOrigin;
+    }
     /** Conditionally logs a message if logging is enabled for the given user context. */
     logForUser(params, message, extra) {
         if (this.config.enableLogging?.(params)) {
@@ -56,6 +64,7 @@ export class BackendAuthClient {
             jwtParams: await this.getJwtParams(),
             isDev: this.config.isDev,
             authCookie: isSignUpCookie ? AuthCookie.SignUp : AuthCookie.Auth,
+            cookieNameSuffix: this.config.cookieNameSuffix,
         };
     }
     /** Calls the provided `getUserFromDatabase` config. */
@@ -143,7 +152,11 @@ export class BackendAuthClient {
                 userId: userIdResult.userId,
                 sessionStartedAt: userIdResult.sessionStartedAt || Date.now(),
             }, cookieParams);
-            const csrfCookie = generateCsrfCookie(userIdResult.csrfToken, cookieParams);
+            const csrfCookie = generateCsrfCookie(userIdResult.csrfToken, {
+                ...cookieParams,
+                hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+                cookieNameSuffix: this.config.cookieNameSuffix,
+            });
             return {
                 'set-cookie': [
                     authCookie,
@@ -186,7 +199,13 @@ export class BackendAuthClient {
     }
     /** Securely extract a user from their request headers. */
     async getSecureUser({ requestHeaders, isSignUpCookie, allowUserAuthRefresh, }) {
-        const userIdResult = await extractUserIdFromRequestHeaders(requestHeaders, await this.getJwtParams(), this.config.csrf, isSignUpCookie ? AuthCookie.SignUp : AuthCookie.Auth);
+        const userIdResult = await extractUserIdFromRequestHeaders({
+            headers: requestHeaders,
+            jwtParams: await this.getJwtParams(),
+            csrfHeaderNameOption: this.config.csrf,
+            cookieName: isSignUpCookie ? AuthCookie.SignUp : AuthCookie.Auth,
+            cookieNameSuffix: this.config.cookieNameSuffix,
+        });
         if (!userIdResult) {
             this.logForUser({
                 user: undefined,
@@ -227,11 +246,13 @@ export class BackendAuthClient {
          * Always include the CSRF cookie so it gets re-established if the browser clears it. When
          * session refresh fires, its headers already include a CSRF cookie.
          */
+        const authCookieOrigin = (await this.config.generateServiceOrigin?.({
+            requestHeaders,
+        })) || this.config.serviceOrigin;
         const csrfCookie = generateCsrfCookie(userIdResult.csrfToken, {
-            hostOrigin: (await this.config.generateServiceOrigin?.({
-                requestHeaders,
-            })) || this.config.serviceOrigin,
+            hostOrigin: this.resolveCsrfCookieOrigin(authCookieOrigin),
             isDev: this.config.isDev,
+            cookieNameSuffix: this.config.cookieNameSuffix,
         });
         return {
             user: assumedUser || user,
@@ -282,8 +303,19 @@ export class BackendAuthClient {
                 preserveCsrf: !clearingAllCookies,
             })
             : undefined;
+        /**
+         * When `csrfCookieOrigin` is configured, the CSRF cookie lives on a broader domain than the
+         * auth cookie. Clear it on that broader domain too so stale tokens don't linger.
+         */
+        const broadCsrfClearCookie = clearingAllCookies && this.config.csrfCookieOrigin
+            ? clearCsrfCookie({
+                hostOrigin: this.config.csrfCookieOrigin,
+                isDev: this.config.isDev,
+                cookieNameSuffix: this.config.cookieNameSuffix,
+            })
+            : undefined;
         return {
-            'set-cookie': mergeHeaderValues(signUpCookieHeaders?.['set-cookie'], authCookieHeaders?.['set-cookie']),
+            'set-cookie': mergeHeaderValues(signUpCookieHeaders?.['set-cookie'], authCookieHeaders?.['set-cookie'], broadCsrfClearCookie),
         };
     }
     /**
@@ -296,7 +328,31 @@ export class BackendAuthClient {
             userId,
             sessionStartedAt: existingUserIdResult.sessionStartedAt,
         }, cookieParams);
-        const csrfCookie = generateCsrfCookie(existingUserIdResult.csrfToken, cookieParams);
+        const csrfCookie = generateCsrfCookie(existingUserIdResult.csrfToken, {
+            ...cookieParams,
+            hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+            cookieNameSuffix: this.config.cookieNameSuffix,
+        });
+        return {
+            'set-cookie': [
+                authCookie,
+                csrfCookie,
+            ],
+        };
+    }
+    /** Generates login headers for a brand-new session (no existing JWT to reuse). */
+    async generateFreshLoginHeaders(userId, cookieParams) {
+        const csrfToken = generateCsrfToken();
+        const authCookie = await generateAuthCookie({
+            csrfToken,
+            userId,
+            sessionStartedAt: Date.now(),
+        }, cookieParams);
+        const csrfCookie = generateCsrfCookie(csrfToken, {
+            ...cookieParams,
+            hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+            cookieNameSuffix: this.config.cookieNameSuffix,
+        });
         return {
             'set-cookie': [
                 authCookie,
@@ -307,7 +363,8 @@ export class BackendAuthClient {
     /** Use these headers to log a user in. */
     async createLoginHeaders({ userId, requestHeaders, isSignUpCookie, }) {
         const oppositeCookieName = isSignUpCookie ? AuthCookie.Auth : AuthCookie.SignUp;
-        const hasExistingOppositeCookie = requestHeaders.cookie?.includes(`${oppositeCookieName}=`);
+        const resolvedOppositeCookieName = resolveCookieName(oppositeCookieName, this.config.cookieNameSuffix);
+        const hasExistingOppositeCookie = requestHeaders.cookie?.includes(`${resolvedOppositeCookieName}=`);
         const discardOppositeCookieHeaders = hasExistingOppositeCookie
             ? generateLogoutHeaders(await this.getCookieParams({
                 isSignUpCookie: !isSignUpCookie,
@@ -316,7 +373,13 @@ export class BackendAuthClient {
                 preserveCsrf: true,
             })
             : undefined;
-        const existingUserIdResult = await extractUserIdFromRequestHeaders(requestHeaders, await this.getJwtParams(), this.config.csrf, isSignUpCookie ? AuthCookie.SignUp : AuthCookie.Auth);
+        const existingUserIdResult = await extractUserIdFromRequestHeaders({
+            headers: requestHeaders,
+            jwtParams: await this.getJwtParams(),
+            csrfHeaderNameOption: this.config.csrf,
+            cookieName: isSignUpCookie ? AuthCookie.SignUp : AuthCookie.Auth,
+            cookieNameSuffix: this.config.cookieNameSuffix,
+        });
         const cookieParams = await this.getCookieParams({
             isSignUpCookie,
             requestHeaders,
@@ -327,7 +390,7 @@ export class BackendAuthClient {
                 cookieParams,
                 existingUserIdResult,
             })
-            : await generateSuccessfulLoginHeaders(userId, cookieParams);
+            : await this.generateFreshLoginHeaders(userId, cookieParams);
         return {
             ...newCookieHeaders,
             'set-cookie': mergeHeaderValues(newCookieHeaders['set-cookie'], discardOppositeCookieHeaders?.['set-cookie']),
@@ -361,7 +424,12 @@ export class BackendAuthClient {
      */
     async getInsecureUser({ requestHeaders, allowUserAuthRefresh, }) {
         // eslint-disable-next-line @typescript-eslint/no-deprecated
-        const userIdResult = await insecureExtractUserIdFromCookieAlone(requestHeaders, await this.getJwtParams(), AuthCookie.Auth);
+        const userIdResult = await insecureExtractUserIdFromCookieAlone({
+            headers: requestHeaders,
+            jwtParams: await this.getJwtParams(),
+            cookieName: AuthCookie.Auth,
+            cookieNameSuffix: this.config.cookieNameSuffix,
+        });
         if (!userIdResult) {
             this.logForUser({
                 user: undefined,

package/dist/auth-client/frontend-auth.client.d.ts

@@ -10,6 +10,11 @@ import { type CsrfHeaderNameOption } from '../csrf-token.js';
 export type FrontendAuthClientConfig = Readonly<{
     csrf: Readonly<CsrfHeaderNameOption>;
 }> & PartialWithUndefined<{
+    /**
+     * Optional suffix appended to cookie names (e.g., `'staging'` produces
+     * `auth-vir-csrf-staging`). When `undefined`, cookie names are unchanged.
+     */
+    cookieNameSuffix: string;
     /**
      * Determine if the current user can assume the identity of another user. If this is not
      * defined, all users will be blocked from assuming other user identities.

package/dist/auth-client/frontend-auth.client.js

@@ -79,7 +79,7 @@ export class FrontendAuthClient {
      * combine them with these.
      */
     createAuthenticatedRequestInit() {
-        const csrfToken = getCurrentCsrfToken();
+        const csrfToken = getCurrentCsrfToken(this.config.cookieNameSuffix);
         const assumedUser = this.getAssumedUser();
         const headers = {
             ...(csrfToken

package/dist/auth.d.ts

@@ -1,6 +1,6 @@
-import { type SelectFrom } from '@augment-vir/common';
+import { type PartialWithUndefined, type SelectFrom } from '@augment-vir/common';
 import { type FullDate, type UtcTimezone } from 'date-vir';
-import { AuthCookie, type CookieParams } from './cookie.js';
+import { type AuthCookie, type CookieParams } from './cookie.js';
 import { type CsrfHeaderNameOption } from './csrf-token.js';
 import { type ParseJwtParams } from './jwt/jwt.js';
 import { type JwtUserData } from './jwt/user-jwt.js';
@@ -37,7 +37,13 @@ export type UserIdResult<UserId extends string | number> = {
  * @category Auth : Host
  * @returns The extracted user id or `undefined` if no valid auth headers exist.
  */
-export declare function extractUserIdFromRequestHeaders<UserId extends string | number>(headers: HeaderContainer, jwtParams: Readonly<ParseJwtParams>, csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>, cookieName?: AuthCookie): Promise<Readonly<UserIdResult<UserId>> | undefined>;
+export declare function extractUserIdFromRequestHeaders<UserId extends string | number>({ headers, jwtParams, csrfHeaderNameOption, cookieName, cookieNameSuffix, }: Readonly<{
+    headers: HeaderContainer;
+    jwtParams: Readonly<ParseJwtParams>;
+    csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>;
+    cookieName: AuthCookie;
+    cookieNameSuffix?: string | undefined;
+}>): Promise<Readonly<UserIdResult<UserId>> | undefined>;
 /**
  * Extract a user id from just the cookie, without CSRF token validation. This is _less secure_ than
  * {@link extractUserIdFromRequestHeaders} as a result. This should only be used in rare
@@ -46,7 +52,12 @@ export declare function extractUserIdFromRequestHeaders<UserId extends string |
  * @deprecated Prefer {@link extractUserIdFromRequestHeaders} instead: it is more secure.
  * @category Auth : Host
  */
-export declare function insecureExtractUserIdFromCookieAlone<UserId extends string | number>(headers: HeaderContainer, jwtParams: Readonly<ParseJwtParams>, cookieName: AuthCookie): Promise<Readonly<UserIdResult<UserId>> | undefined>;
+export declare function insecureExtractUserIdFromCookieAlone<UserId extends string | number>({ headers, jwtParams, cookieName, cookieNameSuffix, }: Readonly<{
+    headers: HeaderContainer;
+    jwtParams: Readonly<ParseJwtParams>;
+    cookieName: AuthCookie;
+    cookieNameSuffix?: string | undefined;
+}>): Promise<Readonly<UserIdResult<UserId>> | undefined>;
 /**
  * Used by host (backend) code to set headers on a response object. Sets both the auth JWT cookie
  * and the CSRF token cookie. The CSRF cookie is not `HttpOnly` so that frontend JavaScript can read
@@ -71,11 +82,13 @@ sessionStartedAt?: number | undefined): Promise<Record<string, string[]>>;
 export declare function generateLogoutHeaders(cookieConfig: Readonly<SelectFrom<CookieParams, {
     hostOrigin: true;
     isDev: true;
-}>>, options?: Readonly<{
+}>> & PartialWithUndefined<{
+    cookieNameSuffix: string;
+}>, options?: Readonly<PartialWithUndefined<{
     /**
-     * When `true`, the CSRF cookie is preserved (not cleared). Use this when clearing only one
-     * cookie type (e.g., the auth cookie) while keeping the other active session (e.g.,
+     * When `true`, the CSRF cookie is preserved (not cleared). Use this when clearing only
+     * one cookie type (e.g., the auth cookie) while keeping the other active session (e.g.,
      * sign-up) that still needs its CSRF token.
      */
-    preserveCsrf?: boolean | undefined;
-}>): Record<string, string[]>;
+    preserveCsrf: boolean;
+}>>): Record<string, string[]>;

package/dist/auth.js

@@ -1,4 +1,4 @@
-import { AuthCookie, clearAuthCookie, clearCsrfCookie, extractCookieJwt, generateAuthCookie, generateCsrfCookie, } from './cookie.js';
+import { clearAuthCookie, clearCsrfCookie, extractCookieJwt, generateAuthCookie, generateCsrfCookie, } from './cookie.js';
 import { generateCsrfToken, resolveCsrfHeaderName } from './csrf-token.js';
 function readHeader(headers, headerName) {
     if (headers instanceof Headers) {
@@ -28,14 +28,19 @@ function readCsrfTokenHeader(headers, csrfHeaderNameOption) {
  * @category Auth : Host
  * @returns The extracted user id or `undefined` if no valid auth headers exist.
  */
-export async function extractUserIdFromRequestHeaders(headers, jwtParams, csrfHeaderNameOption, cookieName = AuthCookie.Auth) {
+export async function extractUserIdFromRequestHeaders({ headers, jwtParams, csrfHeaderNameOption, cookieName, cookieNameSuffix, }) {
     try {
         const csrfToken = readCsrfTokenHeader(headers, csrfHeaderNameOption);
         const cookie = readHeader(headers, 'cookie');
         if (!cookie || !csrfToken) {
             return undefined;
         }
-        const jwt = await extractCookieJwt(cookie, jwtParams, cookieName);
+        const jwt = await extractCookieJwt({
+            rawCookie: cookie,
+            jwtParams,
+            cookieName,
+            cookieNameSuffix,
+        });
         if (!jwt || jwt.data.csrfToken !== csrfToken) {
             return undefined;
         }
@@ -60,13 +65,18 @@ export async function extractUserIdFromRequestHeaders(headers, jwtParams, csrfHe
  * @deprecated Prefer {@link extractUserIdFromRequestHeaders} instead: it is more secure.
  * @category Auth : Host
  */
-export async function insecureExtractUserIdFromCookieAlone(headers, jwtParams, cookieName) {
+export async function insecureExtractUserIdFromCookieAlone({ headers, jwtParams, cookieName, cookieNameSuffix, }) {
     try {
         const cookie = readHeader(headers, 'cookie');
         if (!cookie) {
             return undefined;
         }
-        const jwt = await extractCookieJwt(cookie, jwtParams, cookieName);
+        const jwt = await extractCookieJwt({
+            rawCookie: cookie,
+            jwtParams,
+            cookieName,
+            cookieNameSuffix,
+        });
         if (!jwt) {
             return undefined;
         }

package/dist/cookie.d.ts

@@ -16,6 +16,13 @@ export declare enum AuthCookie {
     /** Used for storing the CSRF token. Not `HttpOnly` so that frontend JS can read it. */
     Csrf = "auth-vir-csrf"
 }
+/**
+ * Resolves a cookie name by appending a suffix when provided. When `cookieNameSuffix` is
+ * `undefined`, the base name is returned unchanged.
+ *
+ * @category Internal
+ */
+export declare function resolveCookieName(baseCookieName: AuthCookie, cookieNameSuffix?: string | undefined): string;
 /**
  * Parameters for {@link generateAuthCookie}.
  *
@@ -54,6 +61,12 @@ export type CookieParams = {
      * @default false
      */
     isDev: boolean;
+    /**
+     * Optional suffix appended to cookie names (e.g., `'staging'` produces `auth-staging`). When
+     * `undefined`, cookie names are unchanged. Useful for running multiple environments on the same
+     * domain without cookie collisions.
+     */
+    cookieNameSuffix: string;
 }>;
 /**
  * Generate a secure cookie that stores the user JWT data. Used in host (backend) code.
@@ -75,7 +88,9 @@ export declare function generateAuthCookie(userJwtData: Readonly<JwtUserData>, c
 export declare function generateCsrfCookie(csrfToken: string, cookieConfig: Readonly<SelectFrom<CookieParams, {
     hostOrigin: true;
     isDev: true;
-}>>): string;
+}>> & PartialWithUndefined<{
+    cookieNameSuffix: string;
+}>): string;
 /**
  * Generate a cookie value that will clear the previous auth cookie. Use this when signing out.
  *
@@ -86,6 +101,7 @@ export declare function clearAuthCookie(cookieConfig: Readonly<SelectFrom<Cookie
     isDev: true;
 }>> & PartialWithUndefined<{
     authCookie: AuthCookie;
+    cookieNameSuffix: string;
 }>): string;
 /**
  * Generate a cookie value that will clear the CSRF token cookie. Use this when signing out.
@@ -95,7 +111,9 @@ export declare function clearAuthCookie(cookieConfig: Readonly<SelectFrom<Cookie
 export declare function clearCsrfCookie(cookieConfig: Readonly<SelectFrom<CookieParams, {
     hostOrigin: true;
     isDev: true;
-}>>): string;
+}>> & PartialWithUndefined<{
+    cookieNameSuffix: string;
+}>): string;
 /**
  * Generate a cookie string from a raw set of parameters.
  *
@@ -108,4 +126,10 @@ export declare function generateCookie(params: Readonly<Record<string, Exclude<P
  * @category Internal
  * @returns The extracted auth Cookie JWT data or `undefined` if no valid auth JWT data was found.
  */
-export declare function extractCookieJwt(rawCookie: string, jwtParams: Readonly<ParseJwtParams>, cookieName: AuthCookie): Promise<undefined | ParsedJwt<JwtUserData>>;
+export declare function extractCookieJwt({ rawCookie, jwtParams, cookieName, cookieNameSuffix, }: {
+    rawCookie: string;
+    jwtParams: Readonly<ParseJwtParams>;
+    cookieName: AuthCookie;
+} & PartialWithUndefined<{
+    cookieNameSuffix: string;
+}>): Promise<undefined | ParsedJwt<JwtUserData>>;

package/dist/cookie.js

@@ -17,6 +17,20 @@ export var AuthCookie;
     /** Used for storing the CSRF token. Not `HttpOnly` so that frontend JS can read it. */
     AuthCookie["Csrf"] = "auth-vir-csrf";
 })(AuthCookie || (AuthCookie = {}));
+/**
+ * Resolves a cookie name by appending a suffix when provided. When `cookieNameSuffix` is
+ * `undefined`, the base name is returned unchanged.
+ *
+ * @category Internal
+ */
+export function resolveCookieName(baseCookieName, cookieNameSuffix) {
+    return [
+        baseCookieName,
+        cookieNameSuffix,
+    ]
+        .filter(check.isTruthy)
+        .join('-');
+}
 function generateSetCookie({ name, value, httpOnly, cookieConfig, }) {
     return generateCookie({
         [name]: value,
@@ -39,7 +53,7 @@ function generateSetCookie({ name, value, httpOnly, cookieConfig, }) {
  */
 export async function generateAuthCookie(userJwtData, cookieConfig) {
     return generateSetCookie({
-        name: cookieConfig.authCookie || AuthCookie.Auth,
+        name: resolveCookieName(cookieConfig.authCookie || AuthCookie.Auth, cookieConfig.cookieNameSuffix),
         value: await createUserJwt(userJwtData, cookieConfig.jwtParams),
         httpOnly: true,
         cookieConfig,
@@ -58,7 +72,7 @@ export async function generateAuthCookie(userJwtData, cookieConfig) {
  */
 export function generateCsrfCookie(csrfToken, cookieConfig) {
     return generateSetCookie({
-        name: AuthCookie.Csrf,
+        name: resolveCookieName(AuthCookie.Csrf, cookieConfig.cookieNameSuffix),
         value: csrfToken,
         httpOnly: false,
         cookieConfig: {
@@ -76,7 +90,7 @@ export function generateCsrfCookie(csrfToken, cookieConfig) {
  */
 export function clearAuthCookie(cookieConfig) {
     return generateSetCookie({
-        name: cookieConfig.authCookie || AuthCookie.Auth,
+        name: resolveCookieName(cookieConfig.authCookie || AuthCookie.Auth, cookieConfig.cookieNameSuffix),
         value: 'redacted',
         httpOnly: true,
         cookieConfig,
@@ -89,7 +103,7 @@ export function clearAuthCookie(cookieConfig) {
  */
 export function clearCsrfCookie(cookieConfig) {
     return generateSetCookie({
-        name: AuthCookie.Csrf,
+        name: resolveCookieName(AuthCookie.Csrf, cookieConfig.cookieNameSuffix),
         value: 'redacted',
         httpOnly: false,
         cookieConfig,
@@ -125,13 +139,14 @@ export function generateCookie(params) {
  * @category Internal
  * @returns The extracted auth Cookie JWT data or `undefined` if no valid auth JWT data was found.
  */
-export async function extractCookieJwt(rawCookie, jwtParams, cookieName) {
-    const cookieRegExp = new RegExp(`${escapeStringForRegExp(cookieName)}=[^;]+(?:;|$)`);
+export async function extractCookieJwt({ rawCookie, jwtParams, cookieName, cookieNameSuffix, }) {
+    const resolvedName = resolveCookieName(cookieName, cookieNameSuffix);
+    const cookieRegExp = new RegExp(`${escapeStringForRegExp(resolvedName)}=[^;]+(?:;|$)`);
     const [cookieValue] = safeMatch(rawCookie, cookieRegExp);
     if (!cookieValue) {
         return undefined;
     }
-    const rawJwt = cookieValue.replace(`${cookieName}=`, '').replace(';', '');
+    const rawJwt = cookieValue.replace(`${resolvedName}=`, '').replace(';', '');
     const jwt = await parseUserJwt(rawJwt, jwtParams);
     return jwt;
 }

package/dist/csrf-token.d.ts

@@ -30,4 +30,4 @@ export declare function resolveCsrfHeaderName(options: Readonly<CsrfHeaderNameOp
  *
  * @category Auth : Client
  */
-export declare function getCurrentCsrfToken(): string | undefined;
+export declare function getCurrentCsrfToken(cookieNameSuffix?: string | undefined): string | undefined;

package/dist/csrf-token.js

@@ -1,6 +1,6 @@
 import { check } from '@augment-vir/assert';
 import { escapeStringForRegExp, randomString, safeMatch } from '@augment-vir/common';
-import { AuthCookie } from './cookie.js';
+import { AuthCookie, resolveCookieName } from './cookie.js';
 /**
  * Generates a random, cryptographically secure CSRF token string.
  *
@@ -35,8 +35,9 @@ export function resolveCsrfHeaderName(options) {
  *
  * @category Auth : Client
  */
-export function getCurrentCsrfToken() {
-    const cookieRegExp = new RegExp(`${escapeStringForRegExp(AuthCookie.Csrf)}=([^;]+)`);
+export function getCurrentCsrfToken(cookieNameSuffix) {
+    const resolvedName = resolveCookieName(AuthCookie.Csrf, cookieNameSuffix);
+    const cookieRegExp = new RegExp(`${escapeStringForRegExp(resolvedName)}=([^;]+)`);
     const [, value,] = safeMatch(globalThis.document.cookie, cookieRegExp);
     return value || undefined;
 }

package/dist/generated/internal/class.js

@@ -22,8 +22,8 @@ const config = {
             "fromEnvVar": null
         },
         "config": {
-            "moduleFormat": "esm",
-            "engineType": "client"
+            "engineType": "client",
+            "moduleFormat": "esm"
         },
         "binaryTargets": [
             {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auth-vir",
-    "version": "5.0.4",
+    "version": "5.2.0",
     "description": "Auth made easy and secure via JWT cookies, CSRF tokens, and password hashing helpers.",
     "keywords": [
         "auth",

package/src/auth-client/backend-auth.client.ts

@@ -17,12 +17,18 @@ import {type EmptyObject, type RequireExactlyOne, type RequireOneOrNone} from 't
 import {
     extractUserIdFromRequestHeaders,
     generateLogoutHeaders,
-    generateSuccessfulLoginHeaders,
     insecureExtractUserIdFromCookieAlone,
     type UserIdResult,
 } from '../auth.js';
-import {AuthCookie, generateAuthCookie, generateCsrfCookie, type CookieParams} from '../cookie.js';
-import {type CsrfHeaderNameOption} from '../csrf-token.js';
+import {
+    AuthCookie,
+    clearCsrfCookie,
+    generateAuthCookie,
+    generateCsrfCookie,
+    resolveCookieName,
+    type CookieParams,
+} from '../cookie.js';
+import {generateCsrfToken, type CsrfHeaderNameOption} from '../csrf-token.js';
 import {AuthHeaderName, mergeHeaderValues} from '../headers.js';
 import {generateNewJwtKeys, parseJwtKeys, type JwtKeys, type RawJwtKeys} from '../jwt/jwt-keys.js';
 import {defaultAllowedClockSkew, type CreateJwtParams, type ParseJwtParams} from '../jwt/jwt.js';
@@ -168,6 +174,25 @@ export type BackendAuthClientConfig<
          * @default {minutes: 5}
          */
         allowedClockSkew: Readonly<AnyDuration>;
+        /**
+         * Optional separate origin for the CSRF cookie's `Domain` attribute. When set, the
+         * non-`HttpOnly` CSRF cookie will use this origin's hostname instead of `serviceOrigin`.
+         *
+         * This is useful when the backend and frontend live on different subdomains that don't
+         * share a common parent narrower than the top-level domain. The `HttpOnly` auth cookie
+         * stays scoped to `serviceOrigin` (protecting it from unrelated subdomains), while the CSRF
+         * cookie uses the broader domain so frontend JavaScript can read it via `document.cookie`.
+         *
+         * The CSRF token alone is not a security risk — it is only meaningful when paired with the
+         * JWT embedded in the `HttpOnly` auth cookie.
+         */
+        csrfCookieOrigin: string;
+        /**
+         * Optional suffix appended to cookie names (e.g., `'staging'` produces `auth-staging`,
+         * `auth-vir-csrf-staging`). When `undefined`, cookie names are unchanged. Useful for
+         * running multiple environments on the same domain without cookie collisions.
+         */
+        cookieNameSuffix: string;
     }>
 >;
 
@@ -201,6 +226,14 @@ export class BackendAuthClient<
         protected readonly config: BackendAuthClientConfig<DatabaseUser, UserId, AssumedUserParams>,
     ) {}
 
+    /**
+     * Resolves the origin to use for CSRF cookie generation. Returns `csrfCookieOrigin` if
+     * configured, otherwise falls back to the auth cookie origin.
+     */
+    protected resolveCsrfCookieOrigin(authCookieOrigin: string): string {
+        return this.config.csrfCookieOrigin || authCookieOrigin;
+    }
+
     /** Conditionally logs a message if logging is enabled for the given user context. */
     protected logForUser(
         params: {
@@ -251,6 +284,7 @@ export class BackendAuthClient<
             jwtParams: await this.getJwtParams(),
             isDev: this.config.isDev,
             authCookie: isSignUpCookie ? AuthCookie.SignUp : AuthCookie.Auth,
+            cookieNameSuffix: this.config.cookieNameSuffix,
         };
     }
 
@@ -383,7 +417,11 @@ export class BackendAuthClient<
                 },
                 cookieParams,
             );
-            const csrfCookie = generateCsrfCookie(userIdResult.csrfToken, cookieParams);
+            const csrfCookie = generateCsrfCookie(userIdResult.csrfToken, {
+                ...cookieParams,
+                hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+                cookieNameSuffix: this.config.cookieNameSuffix,
+            });
 
             return {
                 'set-cookie': [
@@ -460,12 +498,13 @@ export class BackendAuthClient<
          */
         allowUserAuthRefresh: boolean;
     }): Promise<GetUserResult<DatabaseUser> | undefined> {
-        const userIdResult = await extractUserIdFromRequestHeaders<UserId>(
-            requestHeaders,
-            await this.getJwtParams(),
-            this.config.csrf,
-            isSignUpCookie ? AuthCookie.SignUp : AuthCookie.Auth,
-        );
+        const userIdResult = await extractUserIdFromRequestHeaders<UserId>({
+            headers: requestHeaders,
+            jwtParams: await this.getJwtParams(),
+            csrfHeaderNameOption: this.config.csrf,
+            cookieName: isSignUpCookie ? AuthCookie.SignUp : AuthCookie.Auth,
+            cookieNameSuffix: this.config.cookieNameSuffix,
+        });
         if (!userIdResult) {
             this.logForUser(
                 {
@@ -519,12 +558,15 @@ export class BackendAuthClient<
          * Always include the CSRF cookie so it gets re-established if the browser clears it. When
          * session refresh fires, its headers already include a CSRF cookie.
          */
+        const authCookieOrigin =
+            (await this.config.generateServiceOrigin?.({
+                requestHeaders,
+            })) || this.config.serviceOrigin;
+
         const csrfCookie = generateCsrfCookie(userIdResult.csrfToken, {
-            hostOrigin:
-                (await this.config.generateServiceOrigin?.({
-                    requestHeaders,
-                })) || this.config.serviceOrigin,
+            hostOrigin: this.resolveCsrfCookieOrigin(authCookieOrigin),
             isDev: this.config.isDev,
+            cookieNameSuffix: this.config.cookieNameSuffix,
         });
 
         return {
@@ -605,10 +647,24 @@ export class BackendAuthClient<
                   )
                 : undefined;
 
+        /**
+         * When `csrfCookieOrigin` is configured, the CSRF cookie lives on a broader domain than the
+         * auth cookie. Clear it on that broader domain too so stale tokens don't linger.
+         */
+        const broadCsrfClearCookie =
+            clearingAllCookies && this.config.csrfCookieOrigin
+                ? clearCsrfCookie({
+                      hostOrigin: this.config.csrfCookieOrigin,
+                      isDev: this.config.isDev,
+                      cookieNameSuffix: this.config.cookieNameSuffix,
+                  })
+                : undefined;
+
         return {
             'set-cookie': mergeHeaderValues(
                 signUpCookieHeaders?.['set-cookie'],
                 authCookieHeaders?.['set-cookie'],
+                broadCsrfClearCookie,
             ),
         };
     }
@@ -635,7 +691,41 @@ export class BackendAuthClient<
             cookieParams,
         );
 
-        const csrfCookie = generateCsrfCookie(existingUserIdResult.csrfToken, cookieParams);
+        const csrfCookie = generateCsrfCookie(existingUserIdResult.csrfToken, {
+            ...cookieParams,
+            hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+            cookieNameSuffix: this.config.cookieNameSuffix,
+        });
+
+        return {
+            'set-cookie': [
+                authCookie,
+                csrfCookie,
+            ],
+        };
+    }
+
+    /** Generates login headers for a brand-new session (no existing JWT to reuse). */
+    protected async generateFreshLoginHeaders(
+        userId: UserId,
+        cookieParams: Readonly<CookieParams>,
+    ): Promise<Record<string, string[]>> {
+        const csrfToken = generateCsrfToken();
+
+        const authCookie = await generateAuthCookie(
+            {
+                csrfToken,
+                userId,
+                sessionStartedAt: Date.now(),
+            },
+            cookieParams,
+        );
+
+        const csrfCookie = generateCsrfCookie(csrfToken, {
+            ...cookieParams,
+            hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+            cookieNameSuffix: this.config.cookieNameSuffix,
+        });
 
         return {
             'set-cookie': [
@@ -656,7 +746,13 @@ export class BackendAuthClient<
         isSignUpCookie: boolean;
     }): Promise<OutgoingHttpHeaders> {
         const oppositeCookieName = isSignUpCookie ? AuthCookie.Auth : AuthCookie.SignUp;
-        const hasExistingOppositeCookie = requestHeaders.cookie?.includes(`${oppositeCookieName}=`);
+        const resolvedOppositeCookieName = resolveCookieName(
+            oppositeCookieName,
+            this.config.cookieNameSuffix,
+        );
+        const hasExistingOppositeCookie = requestHeaders.cookie?.includes(
+            `${resolvedOppositeCookieName}=`,
+        );
 
         const discardOppositeCookieHeaders = hasExistingOppositeCookie
             ? generateLogoutHeaders(
@@ -670,12 +766,13 @@ export class BackendAuthClient<
               )
             : undefined;
 
-        const existingUserIdResult = await extractUserIdFromRequestHeaders<UserId>(
-            requestHeaders,
-            await this.getJwtParams(),
-            this.config.csrf,
-            isSignUpCookie ? AuthCookie.SignUp : AuthCookie.Auth,
-        );
+        const existingUserIdResult = await extractUserIdFromRequestHeaders<UserId>({
+            headers: requestHeaders,
+            jwtParams: await this.getJwtParams(),
+            csrfHeaderNameOption: this.config.csrf,
+            cookieName: isSignUpCookie ? AuthCookie.SignUp : AuthCookie.Auth,
+            cookieNameSuffix: this.config.cookieNameSuffix,
+        });
 
         const cookieParams = await this.getCookieParams({
             isSignUpCookie,
@@ -688,7 +785,7 @@ export class BackendAuthClient<
                   cookieParams,
                   existingUserIdResult,
               })
-            : await generateSuccessfulLoginHeaders(userId, cookieParams);
+            : await this.generateFreshLoginHeaders(userId, cookieParams);
 
         return {
             ...newCookieHeaders,
@@ -764,11 +861,12 @@ export class BackendAuthClient<
         allowUserAuthRefresh: boolean;
     }): Promise<GetUserResult<DatabaseUser> | undefined> {
         // eslint-disable-next-line @typescript-eslint/no-deprecated
-        const userIdResult = await insecureExtractUserIdFromCookieAlone<UserId>(
-            requestHeaders,
-            await this.getJwtParams(),
-            AuthCookie.Auth,
-        );
+        const userIdResult = await insecureExtractUserIdFromCookieAlone<UserId>({
+            headers: requestHeaders,
+            jwtParams: await this.getJwtParams(),
+            cookieName: AuthCookie.Auth,
+            cookieNameSuffix: this.config.cookieNameSuffix,
+        });
 
         if (!userIdResult) {
             this.logForUser(

package/src/auth-client/frontend-auth.client.ts

@@ -25,6 +25,11 @@ export type FrontendAuthClientConfig = Readonly<{
     csrf: Readonly<CsrfHeaderNameOption>;
 }> &
     PartialWithUndefined<{
+        /**
+         * Optional suffix appended to cookie names (e.g., `'staging'` produces
+         * `auth-vir-csrf-staging`). When `undefined`, cookie names are unchanged.
+         */
+        cookieNameSuffix: string;
         /**
          * Determine if the current user can assume the identity of another user. If this is not
          * defined, all users will be blocked from assuming other user identities.
@@ -163,7 +168,7 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
      * combine them with these.
      */
     public createAuthenticatedRequestInit(): RequestInit {
-        const csrfToken = getCurrentCsrfToken();
+        const csrfToken = getCurrentCsrfToken(this.config.cookieNameSuffix);
 
         const assumedUser = this.getAssumedUser();
         const headers: HeadersInit = {

package/src/auth.ts

@@ -1,7 +1,7 @@
-import {type SelectFrom} from '@augment-vir/common';
+import {type PartialWithUndefined, type SelectFrom} from '@augment-vir/common';
 import {type FullDate, type UtcTimezone} from 'date-vir';
 import {
-    AuthCookie,
+    type AuthCookie,
     clearAuthCookie,
     clearCsrfCookie,
     type CookieParams,
@@ -71,12 +71,19 @@ function readCsrfTokenHeader(
  * @category Auth : Host
  * @returns The extracted user id or `undefined` if no valid auth headers exist.
  */
-export async function extractUserIdFromRequestHeaders<UserId extends string | number>(
-    headers: HeaderContainer,
-    jwtParams: Readonly<ParseJwtParams>,
-    csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>,
-    cookieName: AuthCookie = AuthCookie.Auth,
-): Promise<Readonly<UserIdResult<UserId>> | undefined> {
+export async function extractUserIdFromRequestHeaders<UserId extends string | number>({
+    headers,
+    jwtParams,
+    csrfHeaderNameOption,
+    cookieName,
+    cookieNameSuffix,
+}: Readonly<{
+    headers: HeaderContainer;
+    jwtParams: Readonly<ParseJwtParams>;
+    csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>;
+    cookieName: AuthCookie;
+    cookieNameSuffix?: string | undefined;
+}>): Promise<Readonly<UserIdResult<UserId>> | undefined> {
     try {
         const csrfToken = readCsrfTokenHeader(headers, csrfHeaderNameOption);
         const cookie = readHeader(headers, 'cookie');
@@ -85,7 +92,12 @@ export async function extractUserIdFromRequestHeaders<UserId extends string | nu
             return undefined;
         }
 
-        const jwt = await extractCookieJwt(cookie, jwtParams, cookieName);
+        const jwt = await extractCookieJwt({
+            rawCookie: cookie,
+            jwtParams,
+            cookieName,
+            cookieNameSuffix,
+        });
 
         if (!jwt || jwt.data.csrfToken !== csrfToken) {
             return undefined;
@@ -112,11 +124,17 @@ export async function extractUserIdFromRequestHeaders<UserId extends string | nu
  * @deprecated Prefer {@link extractUserIdFromRequestHeaders} instead: it is more secure.
  * @category Auth : Host
  */
-export async function insecureExtractUserIdFromCookieAlone<UserId extends string | number>(
-    headers: HeaderContainer,
-    jwtParams: Readonly<ParseJwtParams>,
-    cookieName: AuthCookie,
-): Promise<Readonly<UserIdResult<UserId>> | undefined> {
+export async function insecureExtractUserIdFromCookieAlone<UserId extends string | number>({
+    headers,
+    jwtParams,
+    cookieName,
+    cookieNameSuffix,
+}: Readonly<{
+    headers: HeaderContainer;
+    jwtParams: Readonly<ParseJwtParams>;
+    cookieName: AuthCookie;
+    cookieNameSuffix?: string | undefined;
+}>): Promise<Readonly<UserIdResult<UserId>> | undefined> {
     try {
         const cookie = readHeader(headers, 'cookie');
 
@@ -124,7 +142,12 @@ export async function insecureExtractUserIdFromCookieAlone<UserId extends string
             return undefined;
         }
 
-        const jwt = await extractCookieJwt(cookie, jwtParams, cookieName);
+        const jwt = await extractCookieJwt({
+            rawCookie: cookie,
+            jwtParams,
+            cookieName,
+            cookieNameSuffix,
+        });
 
         if (!jwt) {
             return undefined;
@@ -188,15 +211,18 @@ export async function generateSuccessfulLoginHeaders(
  * @category Auth : Host
  */
 export function generateLogoutHeaders(
-    cookieConfig: Readonly<SelectFrom<CookieParams, {hostOrigin: true; isDev: true}>>,
-    options?: Readonly<{
-        /**
-         * When `true`, the CSRF cookie is preserved (not cleared). Use this when clearing only one
-         * cookie type (e.g., the auth cookie) while keeping the other active session (e.g.,
-         * sign-up) that still needs its CSRF token.
-         */
-        preserveCsrf?: boolean | undefined;
-    }>,
+    cookieConfig: Readonly<SelectFrom<CookieParams, {hostOrigin: true; isDev: true}>> &
+        PartialWithUndefined<{cookieNameSuffix: string}>,
+    options?: Readonly<
+        PartialWithUndefined<{
+            /**
+             * When `true`, the CSRF cookie is preserved (not cleared). Use this when clearing only
+             * one cookie type (e.g., the auth cookie) while keeping the other active session (e.g.,
+             * sign-up) that still needs its CSRF token.
+             */
+            preserveCsrf: boolean;
+        }>
+    >,
 ): Record<string, string[]> {
     return {
         'set-cookie': [

package/src/cookie.ts

@@ -25,6 +25,24 @@ export enum AuthCookie {
     Csrf = 'auth-vir-csrf',
 }
 
+/**
+ * Resolves a cookie name by appending a suffix when provided. When `cookieNameSuffix` is
+ * `undefined`, the base name is returned unchanged.
+ *
+ * @category Internal
+ */
+export function resolveCookieName(
+    baseCookieName: AuthCookie,
+    cookieNameSuffix?: string | undefined,
+): string {
+    return [
+        baseCookieName,
+        cookieNameSuffix,
+    ]
+        .filter(check.isTruthy)
+        .join('-');
+}
+
 /**
  * Parameters for {@link generateAuthCookie}.
  *
@@ -63,6 +81,12 @@ export type CookieParams = {
      * @default false
      */
     isDev: boolean;
+    /**
+     * Optional suffix appended to cookie names (e.g., `'staging'` produces `auth-staging`). When
+     * `undefined`, cookie names are unchanged. Useful for running multiple environments on the same
+     * domain without cookie collisions.
+     */
+    cookieNameSuffix: string;
 }>;
 
 function generateSetCookie({
@@ -102,7 +126,10 @@ export async function generateAuthCookie(
     cookieConfig: Readonly<CookieParams>,
 ): Promise<string> {
     return generateSetCookie({
-        name: cookieConfig.authCookie || AuthCookie.Auth,
+        name: resolveCookieName(
+            cookieConfig.authCookie || AuthCookie.Auth,
+            cookieConfig.cookieNameSuffix,
+        ),
         value: await createUserJwt(userJwtData, cookieConfig.jwtParams),
         httpOnly: true,
         cookieConfig,
@@ -122,10 +149,11 @@ export async function generateAuthCookie(
  */
 export function generateCsrfCookie(
     csrfToken: string,
-    cookieConfig: Readonly<SelectFrom<CookieParams, {hostOrigin: true; isDev: true}>>,
+    cookieConfig: Readonly<SelectFrom<CookieParams, {hostOrigin: true; isDev: true}>> &
+        PartialWithUndefined<{cookieNameSuffix: string}>,
 ): string {
     return generateSetCookie({
-        name: AuthCookie.Csrf,
+        name: resolveCookieName(AuthCookie.Csrf, cookieConfig.cookieNameSuffix),
         value: csrfToken,
         httpOnly: false,
         cookieConfig: {
@@ -144,10 +172,13 @@ export function generateCsrfCookie(
  */
 export function clearAuthCookie(
     cookieConfig: Readonly<SelectFrom<CookieParams, {hostOrigin: true; isDev: true}>> &
-        PartialWithUndefined<{authCookie: AuthCookie}>,
+        PartialWithUndefined<{authCookie: AuthCookie; cookieNameSuffix: string}>,
 ) {
     return generateSetCookie({
-        name: cookieConfig.authCookie || AuthCookie.Auth,
+        name: resolveCookieName(
+            cookieConfig.authCookie || AuthCookie.Auth,
+            cookieConfig.cookieNameSuffix,
+        ),
         value: 'redacted',
         httpOnly: true,
         cookieConfig,
@@ -160,10 +191,11 @@ export function clearAuthCookie(
  * @category Internal
  */
 export function clearCsrfCookie(
-    cookieConfig: Readonly<SelectFrom<CookieParams, {hostOrigin: true; isDev: true}>>,
+    cookieConfig: Readonly<SelectFrom<CookieParams, {hostOrigin: true; isDev: true}>> &
+        PartialWithUndefined<{cookieNameSuffix: string}>,
 ) {
     return generateSetCookie({
-        name: AuthCookie.Csrf,
+        name: resolveCookieName(AuthCookie.Csrf, cookieConfig.cookieNameSuffix),
         value: 'redacted',
         httpOnly: false,
         cookieConfig,
@@ -206,12 +238,20 @@ export function generateCookie(
  * @category Internal
  * @returns The extracted auth Cookie JWT data or `undefined` if no valid auth JWT data was found.
  */
-export async function extractCookieJwt(
-    rawCookie: string,
-    jwtParams: Readonly<ParseJwtParams>,
-    cookieName: AuthCookie,
-): Promise<undefined | ParsedJwt<JwtUserData>> {
-    const cookieRegExp = new RegExp(`${escapeStringForRegExp(cookieName)}=[^;]+(?:;|$)`);
+export async function extractCookieJwt({
+    rawCookie,
+    jwtParams,
+    cookieName,
+    cookieNameSuffix,
+}: {
+    rawCookie: string;
+    jwtParams: Readonly<ParseJwtParams>;
+    cookieName: AuthCookie;
+} & PartialWithUndefined<{
+    cookieNameSuffix: string;
+}>): Promise<undefined | ParsedJwt<JwtUserData>> {
+    const resolvedName = resolveCookieName(cookieName, cookieNameSuffix);
+    const cookieRegExp = new RegExp(`${escapeStringForRegExp(resolvedName)}=[^;]+(?:;|$)`);
 
     const [cookieValue] = safeMatch(rawCookie, cookieRegExp);
 
@@ -219,7 +259,7 @@ export async function extractCookieJwt(
         return undefined;
     }
 
-    const rawJwt = cookieValue.replace(`${cookieName}=`, '').replace(';', '');
+    const rawJwt = cookieValue.replace(`${resolvedName}=`, '').replace(';', '');
 
     const jwt = await parseUserJwt(rawJwt, jwtParams);
 

package/src/csrf-token.ts

@@ -1,7 +1,7 @@
 import {check} from '@augment-vir/assert';
 import {escapeStringForRegExp, randomString, safeMatch} from '@augment-vir/common';
 import {type RequireExactlyOne} from 'type-fest';
-import {AuthCookie} from './cookie.js';
+import {AuthCookie, resolveCookieName} from './cookie.js';
 
 /**
  * Generates a random, cryptographically secure CSRF token string.
@@ -51,8 +51,9 @@ export function resolveCsrfHeaderName(options: Readonly<CsrfHeaderNameOption>):
  *
  * @category Auth : Client
  */
-export function getCurrentCsrfToken(): string | undefined {
-    const cookieRegExp = new RegExp(`${escapeStringForRegExp(AuthCookie.Csrf)}=([^;]+)`);
+export function getCurrentCsrfToken(cookieNameSuffix?: string | undefined): string | undefined {
+    const resolvedName = resolveCookieName(AuthCookie.Csrf, cookieNameSuffix);
+    const cookieRegExp = new RegExp(`${escapeStringForRegExp(resolvedName)}=([^;]+)`);
     const [
         ,
         value,

package/src/generated/internal/class.ts

@@ -27,8 +27,8 @@ const config: runtime.GetPrismaClientConfig = {
       "fromEnvVar": null
     },
     "config": {
-      "moduleFormat": "esm",
-      "engineType": "client"
+      "engineType": "client",
+      "moduleFormat": "esm"
     },
     "binaryTargets": [
       {