auth-vir 2.7.2 → 3.0.0

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

@@ -1,21 +1,20 @@
 import { HttpStatus, } from '@augment-vir/common';
 import { listenToActivity } from 'detect-activity';
-import { CsrfTokenFailureReason, extractCsrfTokenHeader, getCurrentCsrfToken, storeCsrfToken, wipeCurrentCsrfToken, } from '../csrf-token.js';
+import { CsrfTokenFailureReason, defaultAllowedClockSkew, extractCsrfTokenHeader, getCurrentCsrfToken, resolveCsrfHeaderName, storeCsrfToken, wipeCurrentCsrfToken, } from '../csrf-token.js';
 import { AuthHeaderName } from '../headers.js';
-import { authLog } from '../log.js';
 /**
  * An auth client for sending and validating client requests to a backend. This should only be used
  * in a frontend environment as it accesses native browser APIs.
  *
  * @category Auth : Client
- * @category Client
+ * @category Clients
  */
 export class FrontendAuthClient {
     config;
     userCheckInterval;
     /** Used to clean up the activity listener on `.destroy()`. */
     removeActivityListener;
-    constructor(config = {}) {
+    constructor(config) {
         this.config = config;
         if (config.checkUser) {
             this.removeActivityListener = listenToActivity({
@@ -41,19 +40,22 @@ export class FrontendAuthClient {
         this.removeActivityListener?.();
     }
     /** Wraps {@link getCurrentCsrfToken} to automatically handle wiping an invalid CSRF token. */
-    async getCurrentCsrfToken() {
-        const csrfTokenResult = getCurrentCsrfToken(this.config.overrides);
-        if (csrfTokenResult.failure &&
-            csrfTokenResult.failure !== CsrfTokenFailureReason.DoesNotExist) {
-            authLog('auth-vir: LOGOUT - getCurrentCsrfToken: invalid CSRF token', {
-                failure: csrfTokenResult.failure,
-            });
-            await this.logout();
+    getCurrentCsrfToken() {
+        const csrfTokenResult = getCurrentCsrfToken({
+            ...this.config.csrf,
+            localStorage: this.config.overrides?.localStorage,
+            allowedClockSkew: this.config.allowedClockSkew || defaultAllowedClockSkew,
+        });
+        if (csrfTokenResult.failure) {
+            if (csrfTokenResult.failure !== CsrfTokenFailureReason.DoesNotExist) {
+                wipeCurrentCsrfToken({
+                    ...this.config.csrf,
+                    localStorage: this.config.overrides?.localStorage,
+                });
+            }
             return undefined;
         }
-        else {
-            return csrfTokenResult.csrfToken?.token;
-        }
+        return csrfTokenResult.csrfToken.token;
     }
     /**
      * Assume the given user. Pass `undefined` to wipe the currently assumed user.
@@ -62,7 +64,7 @@ export class FrontendAuthClient {
      */
     async assumeUser(assumedUserParams) {
         const localStorage = this.config.overrides?.localStorage || globalThis.localStorage;
-        const storageKey = this.config.overrides?.assumedUserHeaderName || AuthHeaderName.AssumedUser;
+        const storageKey = this.config.assumedUserHeaderName || AuthHeaderName.AssumedUser;
         if (!assumedUserParams) {
             localStorage.removeItem(storageKey);
             return true;
@@ -75,7 +77,7 @@ export class FrontendAuthClient {
     }
     /** Gets the assumed user params stored in local storage, if any. */
     getAssumedUser() {
-        const rawValue = (this.config.overrides?.localStorage || globalThis.localStorage).getItem(this.config.overrides?.assumedUserHeaderName || AuthHeaderName.AssumedUser);
+        const rawValue = (this.config.overrides?.localStorage || globalThis.localStorage).getItem(this.config.assumedUserHeaderName || AuthHeaderName.AssumedUser);
         if (!rawValue) {
             return undefined;
         }
@@ -92,18 +94,18 @@ export class FrontendAuthClient {
      * `@augment-vir/common`](https://electrovir.github.io/augment-vir/functions/mergeDeep.html) to
      * combine them with these.
      */
-    async createAuthenticatedRequestInit() {
-        const csrfToken = await this.getCurrentCsrfToken();
+    createAuthenticatedRequestInit() {
+        const csrfToken = this.getCurrentCsrfToken();
         const assumedUser = this.getAssumedUser();
         const headers = {
             ...(csrfToken
                 ? {
-                    [AuthHeaderName.CsrfToken]: csrfToken,
+                    [resolveCsrfHeaderName(this.config.csrf)]: csrfToken,
                 }
                 : {}),
             ...(assumedUser
                 ? {
-                    [this.config.overrides?.assumedUserHeaderName || AuthHeaderName.AssumedUser]: JSON.stringify(assumedUser),
+                    [this.config.assumedUserHeaderName || AuthHeaderName.AssumedUser]: JSON.stringify(assumedUser),
                 }
                 : {}),
         };
@@ -114,9 +116,11 @@ export class FrontendAuthClient {
     }
     /** Wipes the current user auth. */
     async logout() {
-        authLog('auth-vir: LOGOUT - FrontendAuthClient.logout called', new Error().stack);
         await this.config.authClearedCallback?.();
-        wipeCurrentCsrfToken(this.config.overrides);
+        wipeCurrentCsrfToken({
+            ...this.config.csrf,
+            localStorage: this.config.overrides?.localStorage,
+        });
     }
     /**
      * Use to handle a login response. Automatically stores the CSRF token.
@@ -126,17 +130,20 @@ export class FrontendAuthClient {
      */
     async handleLoginResponse(response) {
         if (!response.ok) {
-            authLog('auth-vir: LOGOUT - handleLoginResponse: response not ok');
             await this.logout();
             throw new Error('Login response failed.');
         }
-        const { csrfToken } = extractCsrfTokenHeader(response, this.config.overrides);
+        const { csrfToken } = extractCsrfTokenHeader(response, this.config.csrf, {
+            allowedClockSkew: this.config.allowedClockSkew || defaultAllowedClockSkew,
+        });
         if (!csrfToken) {
-            authLog('auth-vir: LOGOUT - handleLoginResponse: no CSRF token in response');
             await this.logout();
             throw new Error('Did not receive any CSRF token.');
         }
-        storeCsrfToken(csrfToken, this.config.overrides);
+        storeCsrfToken(csrfToken, {
+            ...this.config.csrf,
+            localStorage: this.config.overrides?.localStorage,
+        });
     }
     /**
      * Use to verify _all_ responses received from the backend. Immediately logs the user out once
@@ -147,16 +154,18 @@ export class FrontendAuthClient {
     async verifyResponseAuth(response) {
         if (response.status === HttpStatus.Unauthorized &&
             !response.headers?.get(AuthHeaderName.IsSignUpAuth)) {
-            authLog('auth-vir: LOGOUT - verifyResponseAuth: unauthorized response (401)', {
-                status: response.status,
-            });
             await this.logout();
             return false;
         }
         /** If the response has a new CSRF token, store it. */
-        const { csrfToken } = extractCsrfTokenHeader(response, this.config.overrides);
+        const { csrfToken } = extractCsrfTokenHeader(response, this.config.csrf, {
+            allowedClockSkew: this.config.allowedClockSkew || defaultAllowedClockSkew,
+        });
         if (csrfToken) {
-            storeCsrfToken(csrfToken, this.config.overrides);
+            storeCsrfToken(csrfToken, {
+                ...this.config.csrf,
+                localStorage: this.config.overrides?.localStorage,
+            });
         }
         return true;
     }

package/dist/auth-client/is-session-refresh-ready.d.ts

@@ -0,0 +1,23 @@
+import { type AnyDuration, type FullDate, type UtcTimezone } from 'date-vir';
+/**
+ * Determines if enough time has passed since the JWT was issued to start refreshing the session.
+ *
+ * Visually, this check looks like this:
+ *
+ *      I====R===========E
+ *
+ * - I = JWT issued time (from the JWT's `iat` claim)
+ * - R = session refreshing is available now (I + sessionRefreshStartTime)
+ * - E = JWT expiration
+ * - `=` between R and E = the time frame in which the return value is `true`.
+ *
+ * @category Auth : Host
+ */
+export declare function isSessionRefreshReady({ now, jwtIssuedAt, sessionRefreshStartTime, }: {
+    /** The current time. */
+    now?: Readonly<FullDate<UtcTimezone>> | undefined;
+    /** When the JWT was issued (`iat` claim). */
+    jwtIssuedAt: Readonly<FullDate<UtcTimezone>>;
+    /** How long after JWT issuance before refreshing is available. */
+    sessionRefreshStartTime: Readonly<AnyDuration>;
+}): boolean;

package/dist/auth-client/is-session-refresh-ready.js

@@ -0,0 +1,21 @@
+import { calculateRelativeDate, getNowInUtcTimezone, isDateAfter, } from 'date-vir';
+/**
+ * Determines if enough time has passed since the JWT was issued to start refreshing the session.
+ *
+ * Visually, this check looks like this:
+ *
+ *      I====R===========E
+ *
+ * - I = JWT issued time (from the JWT's `iat` claim)
+ * - R = session refreshing is available now (I + sessionRefreshStartTime)
+ * - E = JWT expiration
+ * - `=` between R and E = the time frame in which the return value is `true`.
+ *
+ * @category Auth : Host
+ */
+export function isSessionRefreshReady({ now = getNowInUtcTimezone(), jwtIssuedAt, sessionRefreshStartTime, }) {
+    return isDateAfter({
+        fullDate: now,
+        relativeTo: calculateRelativeDate(jwtIssuedAt, sessionRefreshStartTime),
+    });
+}

package/dist/auth.d.ts

@@ -1,7 +1,7 @@
 import { type PartialWithUndefined } from '@augment-vir/common';
 import { type FullDate, type UtcTimezone } from 'date-vir';
 import { type CookieParams } from './cookie.js';
-import { AuthHeaderName } from './headers.js';
+import { type CsrfHeaderNameOption } from './csrf-token.js';
 import { type ParseJwtParams } from './jwt/jwt.js';
 import { type JwtUserData } from './jwt/user-jwt.js';
 /**
@@ -18,7 +18,11 @@ export type HeaderContainer = Record<string, string[] | undefined | string | num
 export type UserIdResult<UserId extends string | number> = {
     userId: UserId;
     jwtExpiration: FullDate<UtcTimezone>;
+    /** When the JWT was issued (`iat` claim). */
+    jwtIssuedAt: FullDate<UtcTimezone>;
     cookieName: string;
+    /** The CSRF token embedded in the JWT. */
+    csrfToken: string;
     /**
      * Unix timestamp (in milliseconds) when the session was originally started. Used to enforce max
      * session duration.
@@ -33,9 +37,7 @@ 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>, cookieName?: string, overrides?: PartialWithUndefined<{
-    csrfHeaderName: string;
-}>): Promise<Readonly<UserIdResult<UserId>> | undefined>;
+export declare function extractUserIdFromRequestHeaders<UserId extends string | number>(headers: HeaderContainer, jwtParams: Readonly<ParseJwtParams>, csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>, cookieName?: string): 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
@@ -50,29 +52,21 @@ export declare function insecureExtractUserIdFromCookieAlone<UserId extends stri
  *
  * @category Auth : Host
  */
-export declare function generateSuccessfulLoginHeaders<CsrfHeaderName extends string = AuthHeaderName.CsrfToken>(
+export declare function generateSuccessfulLoginHeaders(
 /** The id from your database of the user you're authenticating. */
-userId: string | number, cookieConfig: Readonly<CookieParams>, overrides?: PartialWithUndefined<{
-    csrfHeaderName: CsrfHeaderName;
-}>, 
+userId: string | number, cookieConfig: Readonly<CookieParams>, csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>, 
 /**
  * The timestamp (in seconds) when the session originally started. If not provided, the current
  * time will be used (for new sessions).
  */
-sessionStartedAt?: number | undefined): Promise<{
-    'set-cookie': string;
-} & Record<CsrfHeaderName, string>>;
+sessionStartedAt?: number | undefined): Promise<Record<string, string>>;
 /**
  * Used by host (backend) code to set headers on a response object when the user has logged out or
  * failed to authorize.
  *
  * @category Auth : Host
  */
-export declare function generateLogoutHeaders<CsrfHeaderName extends string = AuthHeaderName.CsrfToken>(cookieConfig: Readonly<Pick<CookieParams, 'cookieName' | 'hostOrigin' | 'isDev'>>, overrides?: PartialWithUndefined<{
-    csrfHeaderName: CsrfHeaderName;
-}>): {
-    'set-cookie': string;
-} & Record<CsrfHeaderName, string>;
+export declare function generateLogoutHeaders(cookieConfig: Readonly<Pick<CookieParams, 'cookieName' | 'hostOrigin' | 'isDev'>>, csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>): Record<string, string>;
 /**
  * Store auth data on a client (frontend) after receiving an auth response from the host (backend).
  * Specifically, this stores the CSRF token into local storage (which doesn't need to be a secret).
@@ -82,13 +76,11 @@ export declare function generateLogoutHeaders<CsrfHeaderName extends string = Au
  * @category Auth : Client
  * @throws Error if no CSRF token header is found.
  */
-export declare function handleAuthResponse(response: Readonly<Pick<Response, 'ok' | 'headers'>>, overrides?: PartialWithUndefined<{
+export declare function handleAuthResponse(response: Readonly<Pick<Response, 'ok' | 'headers'>>, options: Readonly<CsrfHeaderNameOption> & PartialWithUndefined<{
     /**
      * Allows mocking or overriding the global `localStorage`.
      *
      * @default globalThis.localStorage
      */
     localStorage: Pick<Storage, 'setItem' | 'removeItem'>;
-    /** Override the default CSRF token header name. */
-    csrfHeaderName: string;
 }>): void;

package/dist/auth.js

@@ -1,7 +1,5 @@
 import { AuthCookieName, clearAuthCookie, extractCookieJwt, generateAuthCookie, } from './cookie.js';
-import { extractCsrfTokenHeader, generateCsrfToken, parseCsrfToken, storeCsrfToken, wipeCurrentCsrfToken, } from './csrf-token.js';
-import { AuthHeaderName } from './headers.js';
-import { authLog } from './log.js';
+import { extractCsrfTokenHeader, generateCsrfToken, parseCsrfToken, resolveCsrfHeaderName, storeCsrfToken, wipeCurrentCsrfToken, } from './csrf-token.js';
 function readHeader(headers, headerName) {
     if (headers instanceof Headers) {
         return headers.get(headerName) || undefined;
@@ -19,15 +17,12 @@ function readHeader(headers, headerName) {
         }
     }
 }
-function readCsrfTokenHeader(headers, overrides) {
-    const rawCsrfToken = readHeader(headers, overrides.csrfHeaderName || AuthHeaderName.CsrfToken);
+function readCsrfTokenHeader(headers, csrfHeaderNameOption) {
+    const rawCsrfToken = readHeader(headers, resolveCsrfHeaderName(csrfHeaderNameOption));
     if (!rawCsrfToken) {
         return undefined;
     }
     const token = parseCsrfToken(rawCsrfToken).csrfToken?.token || rawCsrfToken;
-    if (!token) {
-        authLog('auth-vir: CSRF token not found.');
-    }
     return token;
 }
 /**
@@ -38,38 +33,27 @@ function readCsrfTokenHeader(headers, overrides) {
  * @category Auth : Host
  * @returns The extracted user id or `undefined` if no valid auth headers exist.
  */
-export async function extractUserIdFromRequestHeaders(headers, jwtParams, cookieName = AuthCookieName.Auth, overrides = {}) {
+export async function extractUserIdFromRequestHeaders(headers, jwtParams, csrfHeaderNameOption, cookieName = AuthCookieName.Auth) {
     try {
-        const csrfToken = readCsrfTokenHeader(headers, overrides);
+        const csrfToken = readCsrfTokenHeader(headers, csrfHeaderNameOption);
         const cookie = readHeader(headers, 'cookie');
         if (!cookie || !csrfToken) {
-            authLog('auth-vir: extractUserIdFromRequestHeaders failed - missing cookie or CSRF token', {
-                hasCookie: !!cookie,
-                hasCsrfToken: !!csrfToken,
-                cookieName,
-            });
             return undefined;
         }
         const jwt = await extractCookieJwt(cookie, jwtParams, cookieName);
         if (!jwt || jwt.data.csrfToken !== csrfToken) {
-            if (cookieName === AuthCookieName.Auth) {
-                authLog('auth-vir: extractUserIdFromRequestHeaders failed - JWT invalid or CSRF mismatch', {
-                    hasJwt: !!jwt,
-                    csrfMatch: jwt ? jwt.data.csrfToken === csrfToken : false,
-                    cookieName,
-                });
-            }
             return undefined;
         }
         return {
             userId: jwt.data.userId,
             jwtExpiration: jwt.jwtExpiration,
+            jwtIssuedAt: jwt.jwtIssuedAt,
             cookieName,
+            csrfToken: jwt.data.csrfToken,
             sessionStartedAt: jwt.data.sessionStartedAt,
         };
     }
-    catch (error) {
-        authLog('auth-vir: extractUserIdFromRequestHeaders error', { error, cookieName });
+    catch {
         return undefined;
     }
 }
@@ -85,23 +69,22 @@ export async function insecureExtractUserIdFromCookieAlone(headers, jwtParams, c
     try {
         const cookie = readHeader(headers, 'cookie');
         if (!cookie) {
-            authLog('auth-vir: insecureExtractUserIdFromCookieAlone failed - no cookie');
             return undefined;
         }
         const jwt = await extractCookieJwt(cookie, jwtParams, cookieName);
         if (!jwt) {
-            authLog('auth-vir: insecureExtractUserIdFromCookieAlone failed - JWT extraction failed');
             return undefined;
         }
         return {
             userId: jwt.data.userId,
             jwtExpiration: jwt.jwtExpiration,
+            jwtIssuedAt: jwt.jwtIssuedAt,
             cookieName,
+            csrfToken: jwt.data.csrfToken,
             sessionStartedAt: jwt.data.sessionStartedAt,
         };
     }
-    catch (error) {
-        authLog('auth-vir: insecureExtractUserIdFromCookieAlone error', { error });
+    catch {
         return undefined;
     }
 }
@@ -112,21 +95,25 @@ export async function insecureExtractUserIdFromCookieAlone(headers, jwtParams, c
  */
 export async function generateSuccessfulLoginHeaders(
 /** The id from your database of the user you're authenticating. */
-userId, cookieConfig, overrides = {}, 
+userId, cookieConfig, csrfHeaderNameOption, 
 /**
  * The timestamp (in seconds) when the session originally started. If not provided, the current
  * time will be used (for new sessions).
  */
 sessionStartedAt) {
     const csrfToken = generateCsrfToken(cookieConfig.cookieDuration);
-    const csrfHeaderName = (overrides.csrfHeaderName || AuthHeaderName.CsrfToken);
+    const csrfHeaderName = resolveCsrfHeaderName(csrfHeaderNameOption);
+    const { cookie, expiration } = await generateAuthCookie({
+        csrfToken: csrfToken.token,
+        userId,
+        sessionStartedAt: sessionStartedAt ?? Date.now(),
+    }, cookieConfig);
     return {
-        'set-cookie': await generateAuthCookie({
-            csrfToken: csrfToken.token,
-            userId,
-            sessionStartedAt: sessionStartedAt ?? Date.now(),
-        }, cookieConfig),
-        [csrfHeaderName]: JSON.stringify(csrfToken),
+        'set-cookie': cookie,
+        [csrfHeaderName]: JSON.stringify({
+            token: csrfToken.token,
+            expiration,
+        }),
     };
 }
 /**
@@ -135,11 +122,8 @@ sessionStartedAt) {
  *
  * @category Auth : Host
  */
-export function generateLogoutHeaders(cookieConfig, overrides = {}) {
-    authLog('auth-vir: LOGOUT - generateLogoutHeaders called', {
-        cookieName: cookieConfig.cookieName,
-    }, new Error().stack);
-    const csrfHeaderName = (overrides.csrfHeaderName || AuthHeaderName.CsrfToken);
+export function generateLogoutHeaders(cookieConfig, csrfHeaderNameOption) {
+    const csrfHeaderName = resolveCsrfHeaderName(csrfHeaderNameOption);
     return {
         'set-cookie': clearAuthCookie(cookieConfig),
         [csrfHeaderName]: 'redacted',
@@ -154,18 +138,15 @@ export function generateLogoutHeaders(cookieConfig, overrides = {}) {
  * @category Auth : Client
  * @throws Error if no CSRF token header is found.
  */
-export function handleAuthResponse(response, overrides = {}) {
+export function handleAuthResponse(response, options) {
     if (!response.ok) {
-        authLog('auth-vir: LOGOUT - handleAuthResponse: response not ok, wiping CSRF token');
-        wipeCurrentCsrfToken(overrides);
+        wipeCurrentCsrfToken(options);
         return;
     }
-    const { csrfToken } = extractCsrfTokenHeader(response, overrides);
+    const { csrfToken } = extractCsrfTokenHeader(response, options);
     if (!csrfToken) {
-        authLog('auth-vir: LOGOUT - handleAuthResponse: no CSRF token in response, wiping');
-        wipeCurrentCsrfToken(overrides);
+        wipeCurrentCsrfToken(options);
         throw new Error('Did not receive any CSRF token.');
     }
-    authLog('auth-vir: handleAuthResponse - successfully stored CSRF token');
-    storeCsrfToken(csrfToken, overrides);
+    storeCsrfToken(csrfToken, options);
 }

package/dist/cookie.d.ts

@@ -1,5 +1,5 @@
 import { type PartialWithUndefined } from '@augment-vir/common';
-import { type AnyDuration } from 'date-vir';
+import { type AnyDuration, type FullDate, type UtcTimezone } from 'date-vir';
 import { type Primitive } from 'type-fest';
 import { type CreateJwtParams, type ParseJwtParams, type ParsedJwt } from './jwt/jwt.js';
 import { type JwtUserData } from './jwt/user-jwt.js';
@@ -48,12 +48,21 @@ export type CookieParams = {
      */
     isDev: boolean;
 }>;
+/**
+ * Output from {@link generateAuthCookie}.
+ *
+ * @category Internal
+ */
+export type GenerateAuthCookieResult = {
+    cookie: string;
+    expiration: FullDate<UtcTimezone>;
+};
 /**
  * Generate a secure cookie that stores the user JWT data. Used in host (backend) code.
  *
  * @category Internal
  */
-export declare function generateAuthCookie(userJwtData: Readonly<JwtUserData>, cookieConfig: Readonly<CookieParams>): Promise<string>;
+export declare function generateAuthCookie(userJwtData: Readonly<JwtUserData>, cookieConfig: Readonly<CookieParams>): Promise<GenerateAuthCookieResult>;
 /**
  * Generate a cookie value that will clear the previous auth cookie. Use this when signing out.
  *

package/dist/cookie.js

@@ -1,6 +1,6 @@
 import { check } from '@augment-vir/assert';
-import { safeMatch } from '@augment-vir/common';
-import { convertDuration } from 'date-vir';
+import { escapeStringForRegExp, safeMatch } from '@augment-vir/common';
+import { calculateRelativeDate, convertDuration, getNowInUtcTimezone, } from 'date-vir';
 import { parseUrl } from 'url-vir';
 import { createUserJwt, parseUserJwt } from './jwt/user-jwt.js';
 /**
@@ -21,15 +21,19 @@ export var AuthCookieName;
  * @category Internal
  */
 export async function generateAuthCookie(userJwtData, cookieConfig) {
-    return generateCookie({
-        [cookieConfig.cookieName || 'auth']: await createUserJwt(userJwtData, cookieConfig.jwtParams),
-        Domain: parseUrl(cookieConfig.hostOrigin).hostname,
-        HttpOnly: true,
-        Path: '/',
-        SameSite: 'Strict',
-        'MAX-AGE': convertDuration(cookieConfig.cookieDuration, { seconds: true }).seconds,
-        Secure: !cookieConfig.isDev,
-    });
+    const expiration = calculateRelativeDate(getNowInUtcTimezone(), cookieConfig.cookieDuration);
+    return {
+        cookie: generateCookie({
+            [cookieConfig.cookieName || 'auth']: await createUserJwt(userJwtData, cookieConfig.jwtParams),
+            Domain: parseUrl(cookieConfig.hostOrigin).hostname,
+            HttpOnly: true,
+            Path: '/',
+            SameSite: 'Strict',
+            'MAX-AGE': convertDuration(cookieConfig.cookieDuration, { seconds: true }).seconds,
+            Secure: !cookieConfig.isDev,
+        }),
+        expiration,
+    };
 }
 /**
  * Generate a cookie value that will clear the previous auth cookie. Use this when signing out.
@@ -78,7 +82,7 @@ export function generateCookie(params) {
  * @returns The extracted auth Cookie JWT data or `undefined` if no valid auth JWT data was found.
  */
 export async function extractCookieJwt(rawCookie, jwtParams, cookieName = AuthCookieName.Auth) {
-    const cookieRegExp = new RegExp(`${cookieName}=[^;]+(?:;|$)`);
+    const cookieRegExp = new RegExp(`${escapeStringForRegExp(cookieName)}=[^;]+(?:;|$)`);
     const [cookieValue] = safeMatch(rawCookie, cookieRegExp);
     if (!cookieValue) {
         return undefined;

package/dist/csrf-token.d.ts

@@ -27,6 +27,14 @@ export declare const csrfTokenShape: import("object-shape-tester").Shape<{
  * @category Internal
  */
 export type CsrfToken = typeof csrfTokenShape.runtimeType;
+/**
+ * Default allowed clock skew for CSRF token expiration checks. Accounts for differences between
+ * server and client clocks when checking token expiration.
+ *
+ * @category Internal
+ * @default {minutes: 5}
+ */
+export declare const defaultAllowedClockSkew: Readonly<AnyDuration>;
 /**
  * Generates a random, cryptographically secure CSRF token.
  *
@@ -48,6 +56,25 @@ export declare enum CsrfTokenFailureReason {
     /** A CSRF token was found and parsed but is expired. */
     Expired = "expired"
 }
+/**
+ * Options for specifying the CSRF token header name.
+ *
+ * @category Auth : Client
+ * @category Auth : Host
+ */
+export type CsrfHeaderNameOption = RequireExactlyOne<{
+    /** Prefix used to generate the header name: `${prefix}-auth-vir-csrf-token`. */
+    csrfHeaderPrefix: string;
+    /** Overrides the entire CSRF header name. */
+    csrfHeaderName: string;
+}>;
+/**
+ * Resolves a {@link CsrfHeaderNameOption} to the actual header name string.
+ *
+ * @category Auth : Client
+ * @category Auth : Host
+ */
+export declare function resolveCsrfHeaderName(option: Readonly<CsrfHeaderNameOption>): string;
 /**
  * Output from {@link getCurrentCsrfToken}.
  *
@@ -64,45 +91,60 @@ export type GetCsrfTokenResult = RequireExactlyOne<{
  */
 export declare function extractCsrfTokenHeader(response: Readonly<PartialWithUndefined<SelectFrom<Response, {
     headers: true;
-}>>>, overrides?: PartialWithUndefined<{
-    csrfHeaderName: string;
+}>>>, csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>, options?: PartialWithUndefined<{
+    /**
+     * Allowed clock skew tolerance for CSRF token expiration checks.
+     *
+     * @default {minutes: 5}
+     */
+    allowedClockSkew: Readonly<AnyDuration>;
 }>): Readonly<GetCsrfTokenResult>;
 /**
  * Stores the given CSRF token into local storage.
  *
  * @category Auth : Client
  */
-export declare function storeCsrfToken(csrfToken: Readonly<CsrfToken>, overrides?: PartialWithUndefined<{
+export declare function storeCsrfToken(csrfToken: Readonly<CsrfToken>, options: Readonly<CsrfHeaderNameOption> & PartialWithUndefined<{
     /**
      * Allows mocking or overriding the global `localStorage`.
      *
      * @default globalThis.localStorage
      */
     localStorage: Pick<Storage, 'setItem' | 'removeItem'>;
-    /** Override the default CSRF token header name. */
-    csrfHeaderName: string;
 }>): void;
 /**
  * Parse a raw CSRF token JSON string.
  *
  * @category Internal
  */
-export declare function parseCsrfToken(value: string | undefined | null): Readonly<GetCsrfTokenResult>;
+export declare function parseCsrfToken(value: string | undefined | null, options?: PartialWithUndefined<{
+    /**
+     * Allowed clock skew tolerance for CSRF token expiration checks. Accounts for differences
+     * between server and client clocks.
+     *
+     * @default {minutes: 5}
+     */
+    allowedClockSkew: Readonly<AnyDuration>;
+}>): Readonly<GetCsrfTokenResult>;
 /**
  * Used in client (frontend) code to retrieve the current CSRF token in order to send it with
  * requests to the host (backend).
  *
  * @category Auth : Client
  */
-export declare function getCurrentCsrfToken(overrides?: PartialWithUndefined<{
+export declare function getCurrentCsrfToken(options: Readonly<CsrfHeaderNameOption> & PartialWithUndefined<{
     /**
      * Allows mocking or overriding the global `localStorage`.
      *
      * @default globalThis.localStorage
      */
     localStorage: Pick<Storage, 'getItem'>;
-    /** Override the default CSRF token header name. */
-    csrfHeaderName: string;
+    /**
+     * Allowed clock skew tolerance for CSRF token expiration checks.
+     *
+     * @default {minutes: 5}
+     */
+    allowedClockSkew: Readonly<AnyDuration>;
 }>): Readonly<GetCsrfTokenResult>;
 /**
  * Wipes the current stored CSRF token. This should be used by client (frontend) code to logout a
@@ -110,13 +152,11 @@ export declare function getCurrentCsrfToken(overrides?: PartialWithUndefined<{
  *
  * @category Auth : Client
  */
-export declare function wipeCurrentCsrfToken(overrides?: PartialWithUndefined<{
+export declare function wipeCurrentCsrfToken(options: Readonly<CsrfHeaderNameOption> & PartialWithUndefined<{
     /**
      * Allows mocking or overriding the global `localStorage`.
      *
      * @default globalThis.localStorage
      */
     localStorage: Pick<Storage, 'removeItem'>;
-    /** Override the default CSRF token header name. */
-    csrfHeaderName: string;
 }>): void;