auth-vir 5.0.4 → 5.1.0

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

@@ -137,6 +137,19 @@ 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;
 }>>;
 /**
  * An auth client for creating and validating JWTs embedded in cookies. This should only be used in
@@ -149,6 +162,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 +236,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, } 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)) {
@@ -143,7 +151,10 @@ 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),
+            });
             return {
                 'set-cookie': [
                     authCookie,
@@ -227,10 +238,11 @@ 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,
         });
         return {
@@ -282,8 +294,18 @@ 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,
+            })
+            : undefined;
         return {
-            'set-cookie': mergeHeaderValues(signUpCookieHeaders?.['set-cookie'], authCookieHeaders?.['set-cookie']),
+            'set-cookie': mergeHeaderValues(signUpCookieHeaders?.['set-cookie'], authCookieHeaders?.['set-cookie'], broadCsrfClearCookie),
         };
     }
     /**
@@ -296,7 +318,29 @@ 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),
+        });
+        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),
+        });
         return {
             'set-cookie': [
                 authCookie,
@@ -327,7 +371,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']),

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.1.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,17 @@ 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,
+    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 +173,19 @@ 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;
     }>
 >;
 
@@ -201,6 +219,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: {
@@ -383,7 +409,10 @@ export class BackendAuthClient<
                 },
                 cookieParams,
             );
-            const csrfCookie = generateCsrfCookie(userIdResult.csrfToken, cookieParams);
+            const csrfCookie = generateCsrfCookie(userIdResult.csrfToken, {
+                ...cookieParams,
+                hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+            });
 
             return {
                 'set-cookie': [
@@ -519,11 +548,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,
         });
 
@@ -605,10 +636,23 @@ 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,
+                  })
+                : undefined;
+
         return {
             'set-cookie': mergeHeaderValues(
                 signUpCookieHeaders?.['set-cookie'],
                 authCookieHeaders?.['set-cookie'],
+                broadCsrfClearCookie,
             ),
         };
     }
@@ -635,7 +679,39 @@ export class BackendAuthClient<
             cookieParams,
         );
 
-        const csrfCookie = generateCsrfCookie(existingUserIdResult.csrfToken, cookieParams);
+        const csrfCookie = generateCsrfCookie(existingUserIdResult.csrfToken, {
+            ...cookieParams,
+            hostOrigin: this.resolveCsrfCookieOrigin(cookieParams.hostOrigin),
+        });
+
+        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),
+        });
 
         return {
             'set-cookie': [
@@ -688,7 +764,7 @@ export class BackendAuthClient<
                   cookieParams,
                   existingUserIdResult,
               })
-            : await generateSuccessfulLoginHeaders(userId, cookieParams);
+            : await this.generateFreshLoginHeaders(userId, cookieParams);
 
         return {
             ...newCookieHeaders,

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": [
       {