auth-vir 5.1.0 → 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

@@ -150,6 +150,12 @@ export type BackendAuthClientConfig<DatabaseUser extends AnyObject, UserId exten
      * 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

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

@@ -1,7 +1,7 @@
 import { ensureArray, } from '@augment-vir/common';
 import { calculateRelativeDate, createUtcFullDate, getNowInUtcTimezone, isDateAfter, } from 'date-vir';
 import { extractUserIdFromRequestHeaders, generateLogoutHeaders, insecureExtractUserIdFromCookieAlone, } from '../auth.js';
-import { AuthCookie, clearCsrfCookie, generateAuthCookie, generateCsrfCookie, } from '../cookie.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';
@@ -64,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. */
@@ -154,6 +155,7 @@ export class BackendAuthClient {
             const csrfCookie = generateCsrfCookie(userIdResult.csrfToken, {
                 ...cookieParams,
                 hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+                cookieNameSuffix: this.config.cookieNameSuffix,
             });
             return {
                 'set-cookie': [
@@ -197,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,
@@ -244,6 +252,7 @@ export class BackendAuthClient {
         const csrfCookie = generateCsrfCookie(userIdResult.csrfToken, {
             hostOrigin: this.resolveCsrfCookieOrigin(authCookieOrigin),
             isDev: this.config.isDev,
+            cookieNameSuffix: this.config.cookieNameSuffix,
         });
         return {
             user: assumedUser || user,
@@ -302,6 +311,7 @@ export class BackendAuthClient {
             ? clearCsrfCookie({
                 hostOrigin: this.config.csrfCookieOrigin,
                 isDev: this.config.isDev,
+                cookieNameSuffix: this.config.cookieNameSuffix,
             })
             : undefined;
         return {
@@ -321,6 +331,7 @@ export class BackendAuthClient {
         const csrfCookie = generateCsrfCookie(existingUserIdResult.csrfToken, {
             ...cookieParams,
             hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+            cookieNameSuffix: this.config.cookieNameSuffix,
         });
         return {
             'set-cookie': [
@@ -340,6 +351,7 @@ export class BackendAuthClient {
         const csrfCookie = generateCsrfCookie(csrfToken, {
             ...cookieParams,
             hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+            cookieNameSuffix: this.config.cookieNameSuffix,
         });
         return {
             'set-cookie': [
@@ -351,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,
@@ -360,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,
@@ -405,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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auth-vir",
-    "version": "5.1.0",
+    "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

@@ -25,6 +25,7 @@ import {
     clearCsrfCookie,
     generateAuthCookie,
     generateCsrfCookie,
+    resolveCookieName,
     type CookieParams,
 } from '../cookie.js';
 import {generateCsrfToken, type CsrfHeaderNameOption} from '../csrf-token.js';
@@ -186,6 +187,12 @@ export type BackendAuthClientConfig<
          * 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;
     }>
 >;
 
@@ -277,6 +284,7 @@ export class BackendAuthClient<
             jwtParams: await this.getJwtParams(),
             isDev: this.config.isDev,
             authCookie: isSignUpCookie ? AuthCookie.SignUp : AuthCookie.Auth,
+            cookieNameSuffix: this.config.cookieNameSuffix,
         };
     }
 
@@ -412,6 +420,7 @@ export class BackendAuthClient<
             const csrfCookie = generateCsrfCookie(userIdResult.csrfToken, {
                 ...cookieParams,
                 hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+                cookieNameSuffix: this.config.cookieNameSuffix,
             });
 
             return {
@@ -489,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(
                 {
@@ -556,6 +566,7 @@ export class BackendAuthClient<
         const csrfCookie = generateCsrfCookie(userIdResult.csrfToken, {
             hostOrigin: this.resolveCsrfCookieOrigin(authCookieOrigin),
             isDev: this.config.isDev,
+            cookieNameSuffix: this.config.cookieNameSuffix,
         });
 
         return {
@@ -645,6 +656,7 @@ export class BackendAuthClient<
                 ? clearCsrfCookie({
                       hostOrigin: this.config.csrfCookieOrigin,
                       isDev: this.config.isDev,
+                      cookieNameSuffix: this.config.cookieNameSuffix,
                   })
                 : undefined;
 
@@ -682,6 +694,7 @@ export class BackendAuthClient<
         const csrfCookie = generateCsrfCookie(existingUserIdResult.csrfToken, {
             ...cookieParams,
             hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+            cookieNameSuffix: this.config.cookieNameSuffix,
         });
 
         return {
@@ -711,6 +724,7 @@ export class BackendAuthClient<
         const csrfCookie = generateCsrfCookie(csrfToken, {
             ...cookieParams,
             hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+            cookieNameSuffix: this.config.cookieNameSuffix,
         });
 
         return {
@@ -732,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(
@@ -746,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,
@@ -840,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,