auth-vir 5.1.0 → 5.2.1

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

@@ -1,9 +1,12 @@
 import {
     ensureArray,
     type AnyObject,
+    type EmptyObject,
     type JsonCompatibleObject,
     type MaybePromise,
     type PartialWithUndefined,
+    type RequireExactlyOne,
+    type RequireOneOrNone,
 } from '@augment-vir/common';
 import {
     calculateRelativeDate,
@@ -13,7 +16,6 @@ import {
     type AnyDuration,
 } from 'date-vir';
 import {type IncomingHttpHeaders, type OutgoingHttpHeaders} from 'node:http';
-import {type EmptyObject, type RequireExactlyOne, type RequireOneOrNone} from 'type-fest';
 import {
     extractUserIdFromRequestHeaders,
     generateLogoutHeaders,
@@ -25,6 +27,7 @@ import {
     clearCsrfCookie,
     generateAuthCookie,
     generateCsrfCookie,
+    resolveCookieName,
     type CookieParams,
 } from '../cookie.js';
 import {generateCsrfToken, type CsrfHeaderNameOption} from '../csrf-token.js';
@@ -186,6 +189,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 +286,7 @@ export class BackendAuthClient<
             jwtParams: await this.getJwtParams(),
             isDev: this.config.isDev,
             authCookie: isSignUpCookie ? AuthCookie.SignUp : AuthCookie.Auth,
+            cookieNameSuffix: this.config.cookieNameSuffix,
         };
     }
 
@@ -412,6 +422,7 @@ export class BackendAuthClient<
             const csrfCookie = generateCsrfCookie(userIdResult.csrfToken, {
                 ...cookieParams,
                 hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+                cookieNameSuffix: this.config.cookieNameSuffix,
             });
 
             return {
@@ -489,12 +500,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 +568,7 @@ export class BackendAuthClient<
         const csrfCookie = generateCsrfCookie(userIdResult.csrfToken, {
             hostOrigin: this.resolveCsrfCookieOrigin(authCookieOrigin),
             isDev: this.config.isDev,
+            cookieNameSuffix: this.config.cookieNameSuffix,
         });
 
         return {
@@ -645,6 +658,7 @@ export class BackendAuthClient<
                 ? clearCsrfCookie({
                       hostOrigin: this.config.csrfCookieOrigin,
                       isDev: this.config.isDev,
+                      cookieNameSuffix: this.config.cookieNameSuffix,
                   })
                 : undefined;
 
@@ -682,6 +696,7 @@ export class BackendAuthClient<
         const csrfCookie = generateCsrfCookie(existingUserIdResult.csrfToken, {
             ...cookieParams,
             hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+            cookieNameSuffix: this.config.cookieNameSuffix,
         });
 
         return {
@@ -711,6 +726,7 @@ export class BackendAuthClient<
         const csrfCookie = generateCsrfCookie(csrfToken, {
             ...cookieParams,
             hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+            cookieNameSuffix: this.config.cookieNameSuffix,
         });
 
         return {
@@ -732,7 +748,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 +768,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 +863,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

@@ -1,5 +1,6 @@
 import {
     type createBlockingInterval,
+    type EmptyObject,
     HttpStatus,
     type JsonCompatibleObject,
     type MaybePromise,
@@ -8,7 +9,6 @@ import {
 } from '@augment-vir/common';
 import {type AnyDuration} from 'date-vir';
 import {listenToActivity} from 'detect-activity';
-import {type EmptyObject} from 'type-fest';
 import {
     type CsrfHeaderNameOption,
     getCurrentCsrfToken,
@@ -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.
@@ -131,13 +136,13 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
         if (!assumedUserParams) {
             localStorage.removeItem(storageKey);
             return true;
-        } else if (!(await this.config.canAssumeUser?.())) {
+        } else if (await this.config.canAssumeUser?.()) {
+            localStorage.setItem(storageKey, JSON.stringify(assumedUserParams));
+
+            return true;
+        } else {
             return false;
         }
-
-        localStorage.setItem(storageKey, JSON.stringify(assumedUserParams));
-
-        return true;
     }
 
     /** Gets the assumed user params stored in local storage, if any. */
@@ -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

@@ -3,10 +3,10 @@ import {
     escapeStringForRegExp,
     safeMatch,
     type PartialWithUndefined,
+    type Primitive,
     type SelectFrom,
 } from '@augment-vir/common';
 import {convertDuration, type AnyDuration} from 'date-vir';
-import {type Primitive} from 'type-fest';
 import {parseUrl} from 'url-vir';
 import {type CreateJwtParams, type ParseJwtParams, type ParsedJwt} from './jwt/jwt.js';
 import {createUserJwt, parseUserJwt, type JwtUserData} from './jwt/user-jwt.js';
@@ -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,11 @@
 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 {
+    escapeStringForRegExp,
+    randomString,
+    safeMatch,
+    type RequireExactlyOne,
+} from '@augment-vir/common';
+import {AuthCookie, resolveCookieName} from './cookie.js';
 
 /**
  * Generates a random, cryptographically secure CSRF token string.
@@ -51,8 +55,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/client.ts

@@ -6,7 +6,7 @@
 /*
  * This file should be your main import to use Prisma. Through it you get access to all the models, enums, and input types.
  * If you're looking for something you can import in the client-side of your application, please refer to the `browser.ts` file instead.
- * 
+ *
  * 🟢 You can import this file directly.
  */
 
@@ -28,19 +28,19 @@ export * from "./enums.js"
  * Type-safe database client for TypeScript
  * @example
  * ```
- * const prisma = new PrismaClient()
+ * const prisma = new PrismaClient({
+ *   adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL })
+ * })
  * // Fetch zero or more Users
  * const users = await prisma.user.findMany()
  * ```
  * 
- * Read more in our [docs](https://www.prisma.io/docs/reference/tools-and-interfaces/prisma-client).
+ * Read more in our [docs](https://pris.ly/d/client).
  */
-export const PrismaClient = $Class.getPrismaClientClass(__dirname)
+export const PrismaClient = $Class.getPrismaClientClass()
 export type PrismaClient<LogOpts extends Prisma.LogLevel = never, OmitOpts extends Prisma.PrismaClientOptions["omit"] = Prisma.PrismaClientOptions["omit"], ExtArgs extends runtime.Types.Extensions.InternalArgs = runtime.Types.Extensions.DefaultArgs> = $Class.PrismaClient<LogOpts, OmitOpts, ExtArgs>
 export { Prisma }
 
-
-
 /**
  * Model User
  *