auth-vir 2.7.2 → 3.0.1

package/README.md

@@ -81,10 +81,19 @@ import {
     parseJwtKeys,
     type CookieParams,
     type CreateJwtParams,
+    type CsrfHeaderNameOption,
 } from 'auth-vir';
 
 type MyUserId = string;
 
+/**
+ * The CSRF header prefix for this app. Either `csrfHeaderPrefix` or `csrfHeaderName` must be
+ * provided to all CSRF-related functions.
+ */
+const csrfOption: CsrfHeaderNameOption = {
+    csrfHeaderPrefix: 'my-app',
+};
+
 /**
  * Use this for a /login endpoint.
  *
@@ -105,7 +114,7 @@ export async function handleLogin(
         throw new Error('Credentials mismatch.');
     }
 
-    const authHeaders = await generateSuccessfulLoginHeaders(user.id, cookieParams);
+    const authHeaders = await generateSuccessfulLoginHeaders(user.id, cookieParams, csrfOption);
     response.setHeaders(new Headers(authHeaders));
 }
 
@@ -121,7 +130,7 @@ export async function createUser(
 ) {
     const newUser = await createUserInDatabase(userRequestData);
 
-    const authHeaders = await generateSuccessfulLoginHeaders(newUser.id, cookieParams);
+    const authHeaders = await generateSuccessfulLoginHeaders(newUser.id, cookieParams, csrfOption);
     response.setHeaders(new Headers(authHeaders));
 }
 
@@ -132,7 +141,7 @@ export async function createUser(
  */
 export async function getAuthenticatedUser(request: ClientRequest) {
     const userId = (
-        await extractUserIdFromRequestHeaders<MyUserId>(request.getHeaders(), jwtParams)
+        await extractUserIdFromRequestHeaders<MyUserId>(request.getHeaders(), jwtParams, csrfOption)
     )?.userId;
     const user = userId ? findUserInDatabaseById(userId) : undefined;
 
@@ -252,15 +261,28 @@ Here's a full example of how to use all the client / frontend side auth function
 
 ```TypeScript
 import {HttpStatus} from '@augment-vir/common';
-import {AuthHeaderName} from '../headers.js';
-import {getCurrentCsrfToken, handleAuthResponse, wipeCurrentCsrfToken} from 'auth-vir';
+import {
+    type CsrfHeaderNameOption,
+    getCurrentCsrfToken,
+    handleAuthResponse,
+    resolveCsrfHeaderName,
+    wipeCurrentCsrfToken,
+} from 'auth-vir';
+
+/**
+ * The CSRF header prefix for this app. Either `csrfHeaderPrefix` or `csrfHeaderName` must be
+ * provided to all CSRF-related functions.
+ */
+const csrfOption: CsrfHeaderNameOption = {
+    csrfHeaderPrefix: 'my-app',
+};
 
 /** Call this when the user logs in for the first time this session. */
 export async function sendLoginRequest(
     userLoginData: {username: string; password: string},
     loginUrl: string,
 ) {
-    if (getCurrentCsrfToken().csrfToken) {
+    if (getCurrentCsrfToken(csrfOption).csrfToken) {
         throw new Error('Already logged in.');
     }
 
@@ -270,7 +292,7 @@ export async function sendLoginRequest(
         credentials: 'include',
     });
 
-    handleAuthResponse(response);
+    handleAuthResponse(response, csrfOption);
 
     return response;
 }
@@ -281,7 +303,7 @@ export async function sendAuthenticatedRequest(
     requestInit: Omit<RequestInit, 'headers'> = {},
     headers: Record<string, string> = {},
 ) {
-    const {csrfToken} = getCurrentCsrfToken();
+    const {csrfToken} = getCurrentCsrfToken(csrfOption);
 
     if (!csrfToken) {
         throw new Error('Not authenticated.');
@@ -292,7 +314,7 @@ export async function sendAuthenticatedRequest(
         credentials: 'include',
         headers: {
             ...headers,
-            [AuthHeaderName.CsrfToken]: csrfToken.token,
+            [resolveCsrfHeaderName(csrfOption)]: csrfToken.token,
         },
     });
 
@@ -302,7 +324,7 @@ export async function sendAuthenticatedRequest(
      * another tab.)
      */
     if (response.status === HttpStatus.Unauthorized) {
-        wipeCurrentCsrfToken();
+        wipeCurrentCsrfToken(csrfOption);
         throw new Error(`User no longer logged in.`);
     } else {
         return response;
@@ -311,7 +333,7 @@ export async function sendAuthenticatedRequest(
 
 /** Call this when the user explicitly clicks a "log out" button. */
 export function logout() {
-    wipeCurrentCsrfToken();
+    wipeCurrentCsrfToken(csrfOption);
 }
 ```
 

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

@@ -4,9 +4,9 @@ import { type IncomingHttpHeaders, type OutgoingHttpHeaders } from 'node:http';
 import { type EmptyObject, type RequireExactlyOne, type RequireOneOrNone } from 'type-fest';
 import { type UserIdResult } from '../auth.js';
 import { type CookieParams } from '../cookie.js';
-import { AuthHeaderName } from '../headers.js';
+import { type CsrfHeaderNameOption } from '../csrf-token.js';
 import { type JwtKeys, type RawJwtKeys } from '../jwt/jwt-keys.js';
-import { type CreateJwtParams } from '../jwt/jwt.js';
+import { type CreateJwtParams, type ParseJwtParams } from '../jwt/jwt.js';
 /**
  * Output from `BackendAuthClient.getSecureUser()`.
  *
@@ -31,7 +31,8 @@ export type GetUserResult<DatabaseUser extends AnyObject> = {
  *
  * @category Internal
  */
-export type BackendAuthClientConfig<DatabaseUser extends AnyObject, UserId extends string | number, AssumedUserParams extends JsonCompatibleObject = EmptyObject, CsrfHeaderName extends string = AuthHeaderName.CsrfToken> = Readonly<{
+export type BackendAuthClientConfig<DatabaseUser extends AnyObject, UserId extends string | number, AssumedUserParams extends JsonCompatibleObject = EmptyObject> = Readonly<{
+    csrf: Readonly<CsrfHeaderNameOption>;
     /** The origin of your backend that is offering auth cookies. */
     serviceOrigin: string;
     /** Finds the relevant user from your own database. */
@@ -45,6 +46,7 @@ export type BackendAuthClientConfig<DatabaseUser extends AnyObject, UserId exten
          * their user identity. Otherwise, this is `undefined`.
          */
         assumingUser: AssumedUserParams | undefined;
+        requestHeaders: Readonly<IncomingHttpHeaders>;
     }) => MaybePromise<DatabaseUser | undefined | null>;
     /**
      * Get JWT keys produced by {@link generateNewJwtKeys}. Make sure that each time this is
@@ -58,6 +60,11 @@ export type BackendAuthClientConfig<DatabaseUser extends AnyObject, UserId exten
      */
     isDev: boolean;
 } & PartialWithUndefined<{
+    /**
+     * Overwrite the header name used for tracking is an admin is assuming the identity of
+     * another user.
+     */
+    assumedUserHeaderName: string;
     /**
      * Optionally generate a service origin from request headers. The generated origin is used
      * for set-cookie headers.
@@ -107,30 +114,33 @@ export type BackendAuthClientConfig<DatabaseUser extends AnyObject, UserId exten
      *
      * @default {minutes: 2}
      */
-    sessionRefreshTimeout: Readonly<AnyDuration>;
+    sessionRefreshStartTime: Readonly<AnyDuration>;
     /**
      * The maximum duration a session can last, regardless of activity. After this time, the
      * user will be logged out even if they are actively using the application.
      *
-     * @default {weeks: 2}
+     * @default {days: 1.5}
      */
     maxSessionDuration: Readonly<AnyDuration>;
-    overrides: PartialWithUndefined<{
-        csrfHeaderName: CsrfHeaderName;
-        assumedUserHeaderName: string;
-    }>;
+    /**
+     * Allowed clock skew tolerance for JWT and CSRF token expiration checks. Accounts for
+     * differences between server and client clocks.
+     *
+     * @default {minutes: 5}
+     */
+    allowedClockSkew: Readonly<AnyDuration>;
 }>>;
 /**
  * An auth client for creating and validating JWTs embedded in cookies. This should only be used in
  * a backend environment as it accesses native Node packages.
  *
  * @category Auth : Host
- * @category Client
+ * @category Clients
  */
-export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId extends string | number, AssumedUserParams extends AnyObject = EmptyObject, CsrfHeaderName extends string = AuthHeaderName.CsrfToken> {
-    protected readonly config: BackendAuthClientConfig<DatabaseUser, UserId, AssumedUserParams, CsrfHeaderName>;
+export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId extends string | number, AssumedUserParams extends AnyObject = EmptyObject> {
+    protected readonly config: BackendAuthClientConfig<DatabaseUser, UserId, AssumedUserParams>;
     protected cachedParsedJwtKeys: Record<string, Readonly<JwtKeys>>;
-    constructor(config: BackendAuthClientConfig<DatabaseUser, UserId, AssumedUserParams, CsrfHeaderName>);
+    constructor(config: BackendAuthClientConfig<DatabaseUser, UserId, AssumedUserParams>);
     /** Get all the parameters used for cookie generation. */
     protected getCookieParams({ isSignUpCookie, requestHeaders, }: {
         /**
@@ -143,10 +153,11 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
         requestHeaders: Readonly<IncomingHttpHeaders> | undefined;
     }): Promise<Readonly<CookieParams>>;
     /** Calls the provided `getUserFromDatabase` config. */
-    protected getDatabaseUser({ isSignUpCookie, userId, assumingUser, }: {
+    protected getDatabaseUser({ isSignUpCookie, userId, assumingUser, requestHeaders, }: {
         userId: UserId | undefined;
         assumingUser: AssumedUserParams | undefined;
         isSignUpCookie: boolean;
+        requestHeaders: IncomingHttpHeaders;
     }): Promise<undefined | DatabaseUser>;
     /** Creates a `'cookie-set'` header to refresh the user's session cookie. */
     protected createCookieRefreshHeaders({ userIdResult, requestHeaders, }: {
@@ -154,9 +165,9 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
         requestHeaders: IncomingHttpHeaders;
     }): Promise<OutgoingHttpHeaders | undefined>;
     /** Reads the user's assumed user headers and, if configured, gets the assumed user. */
-    protected getAssumedUser({ headers, user, }: {
+    protected getAssumedUser({ requestHeaders, user, }: {
         user: DatabaseUser;
-        headers: IncomingHttpHeaders;
+        requestHeaders: IncomingHttpHeaders;
     }): Promise<DatabaseUser | undefined>;
     /** Securely extract a user from their request headers. */
     getSecureUser({ requestHeaders, isSignUpCookie, allowUserAuthRefresh, }: {
@@ -173,7 +184,7 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
      * Get all the JWT params used when creating the auth cookie, in case you need them for
      * something else too.
      */
-    getJwtParams(): Promise<Readonly<CreateJwtParams>>;
+    getJwtParams(): Promise<Readonly<CreateJwtParams> & ParseJwtParams>;
     /** Use these headers to log out the user. */
     createLogoutHeaders(params: Readonly<RequireExactlyOne<{
         allCookies: true;
@@ -181,7 +192,7 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
     }> & {
         /** Overrides the client's already established `serviceOrigin`. */
         serviceOrigin?: string | undefined;
-    }>): Promise<Partial<Record<CsrfHeaderName, string>> & {
+    }>): Promise<Record<string, string | string[]> & {
         'set-cookie': string[];
     }>;
     /** Use these headers to log a user in. */

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

@@ -1,25 +1,26 @@
 import { ensureArray, } from '@augment-vir/common';
-import { calculateRelativeDate, createUtcFullDate, getNowInUtcTimezone, isDateAfter, negateDuration, } from 'date-vir';
+import { calculateRelativeDate, createUtcFullDate, getNowInUtcTimezone, isDateAfter, } from 'date-vir';
 import { extractUserIdFromRequestHeaders, generateLogoutHeaders, generateSuccessfulLoginHeaders, insecureExtractUserIdFromCookieAlone, } from '../auth.js';
-import { AuthCookieName } from '../cookie.js';
+import { AuthCookieName, generateAuthCookie } from '../cookie.js';
+import { defaultAllowedClockSkew, resolveCsrfHeaderName, } from '../csrf-token.js';
 import { AuthHeaderName, mergeHeaderValues } from '../headers.js';
 import { parseJwtKeys } from '../jwt/jwt-keys.js';
-import { authLog } from '../log.js';
+import { isSessionRefreshReady } from './is-session-refresh-ready.js';
 const defaultSessionIdleTimeout = {
     minutes: 20,
 };
-const defaultSessionRefreshTimeout = {
+const defaultSessionRefreshStartTime = {
     minutes: 2,
 };
 const defaultMaxSessionDuration = {
-    weeks: 2,
+    days: 1.5,
 };
 /**
  * An auth client for creating and validating JWTs embedded in cookies. This should only be used in
  * a backend environment as it accesses native Node packages.
  *
  * @category Auth : Host
- * @category Client
+ * @category Clients
  */
 export class BackendAuthClient {
     config;
@@ -41,7 +42,7 @@ export class BackendAuthClient {
         };
     }
     /** Calls the provided `getUserFromDatabase` config. */
-    async getDatabaseUser({ isSignUpCookie, userId, assumingUser, }) {
+    async getDatabaseUser({ isSignUpCookie, userId, assumingUser, requestHeaders, }) {
         if (!userId) {
             return undefined;
         }
@@ -49,6 +50,7 @@ export class BackendAuthClient {
             assumingUser,
             userId,
             isSignUpCookie,
+            requestHeaders,
         });
         if (!authenticatedUser) {
             return undefined;
@@ -58,16 +60,13 @@ export class BackendAuthClient {
     /** Creates a `'cookie-set'` header to refresh the user's session cookie. */
     async createCookieRefreshHeaders({ userIdResult, requestHeaders, }) {
         const now = getNowInUtcTimezone();
-        /** Double check that the JWT hasn't already expired. */
+        const clockSkew = this.config.allowedClockSkew || defaultAllowedClockSkew;
+        /** Double check that the JWT hasn't already expired (with clock skew tolerance). */
         const isExpiredAlready = isDateAfter({
             fullDate: now,
-            relativeTo: userIdResult.jwtExpiration,
+            relativeTo: calculateRelativeDate(userIdResult.jwtExpiration, clockSkew),
         });
         if (isExpiredAlready) {
-            authLog('auth-vir: SESSION EXPIRED - JWT already expired, user will be logged out', {
-                userId: userIdResult.userId,
-                jwtExpiration: userIdResult.jwtExpiration,
-            });
             return undefined;
         }
         /**
@@ -83,51 +82,45 @@ export class BackendAuthClient {
                 relativeTo: maxSessionEndDate,
             });
             if (isSessionExpired) {
-                authLog('auth-vir: SESSION EXPIRED - max session duration exceeded, user will be logged out', {
-                    userId: userIdResult.userId,
-                    sessionStartedAt: userIdResult.sessionStartedAt,
-                    maxSessionDuration,
-                });
                 return undefined;
             }
         }
-        /**
-         * This check performs the following: the current time + the refresh threshold > JWT
-         * expiration.
-         *
-         * Visually, this check looks like this:
-         *
-         *      X   C=======Y=======R   Z
-         *
-         * - C = current time
-         * - R = C + refresh threshold
-         * - `=` = the time frame in which {@link isRefreshReady} = true.
-         * - X = JWT expiration that has already expired (rejected by {@link isExpiredAlready}.
-         * - Y = JWT expiration within the refresh threshold: {@link isRefreshReady} = true.
-         * - Z = JWT expiration outside the refresh threshold: {@link isRefreshReady} = false.
-         */
-        const sessionRefreshTimeout = this.config.sessionRefreshTimeout || defaultSessionRefreshTimeout;
-        const isRefreshReady = isDateAfter({
-            fullDate: now,
-            relativeTo: calculateRelativeDate(userIdResult.jwtExpiration, negateDuration(sessionRefreshTimeout)),
+        const sessionRefreshStartTime = this.config.sessionRefreshStartTime || defaultSessionRefreshStartTime;
+        const isRefreshReady = isSessionRefreshReady({
+            now,
+            jwtIssuedAt: userIdResult.jwtIssuedAt,
+            sessionRefreshStartTime,
         });
         if (isRefreshReady) {
-            return this.createLoginHeaders({
+            const isSignUpCookie = userIdResult.cookieName === AuthCookieName.SignUp;
+            const cookieParams = await this.getCookieParams({
+                isSignUpCookie,
                 requestHeaders,
-                userId: userIdResult.userId,
-                isSignUpCookie: userIdResult.cookieName === AuthCookieName.SignUp,
             });
+            const csrfHeaderName = resolveCsrfHeaderName(this.config.csrf);
+            const { cookie, expiration } = await generateAuthCookie({
+                csrfToken: userIdResult.csrfToken,
+                userId: userIdResult.userId,
+                sessionStartedAt: userIdResult.sessionStartedAt || Date.now(),
+            }, cookieParams);
+            return {
+                'set-cookie': cookie,
+                [csrfHeaderName]: JSON.stringify({
+                    token: userIdResult.csrfToken,
+                    expiration,
+                }),
+            };
         }
         else {
             return undefined;
         }
     }
     /** Reads the user's assumed user headers and, if configured, gets the assumed user. */
-    async getAssumedUser({ headers, user, }) {
+    async getAssumedUser({ requestHeaders, user, }) {
         if (!this.config.assumeUser || !(await this.config.assumeUser.canAssumeUser(user))) {
             return undefined;
         }
-        const assumedUserHeader = ensureArray(headers[this.config.overrides?.assumedUserHeaderName || AuthHeaderName.AssumedUser])[0];
+        const assumedUserHeader = ensureArray(requestHeaders[this.config.assumedUserHeaderName || AuthHeaderName.AssumedUser])[0];
         if (!assumedUserHeader) {
             return undefined;
         }
@@ -139,31 +132,27 @@ export class BackendAuthClient {
             isSignUpCookie: false,
             userId: parsedAssumedUserData.userId,
             assumingUser: parsedAssumedUserData.assumedUserParams,
+            requestHeaders,
         });
         return assumedUser;
     }
     /** Securely extract a user from their request headers. */
     async getSecureUser({ requestHeaders, isSignUpCookie, allowUserAuthRefresh, }) {
-        const userIdResult = await extractUserIdFromRequestHeaders(requestHeaders, await this.getJwtParams(), isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth, this.config.overrides);
+        const userIdResult = await extractUserIdFromRequestHeaders(requestHeaders, await this.getJwtParams(), this.config.csrf, isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth);
         if (!userIdResult) {
-            if (!isSignUpCookie) {
-                authLog('auth-vir: getSecureUser failed - could not extract user from request');
-            }
             return undefined;
         }
         const user = await this.getDatabaseUser({
             userId: userIdResult.userId,
             assumingUser: undefined,
             isSignUpCookie,
+            requestHeaders,
         });
         if (!user) {
-            authLog('auth-vir: getSecureUser failed - user not found in database', {
-                userId: userIdResult.userId,
-            });
             return undefined;
         }
         const assumedUser = await this.getAssumedUser({
-            headers: requestHeaders,
+            requestHeaders,
             user,
         });
         const cookieRefreshHeaders = (await this.createCookieRefreshHeaders({
@@ -184,7 +173,7 @@ export class BackendAuthClient {
         const rawJwtKeys = await this.config.getJwtKeys();
         const cacheKey = JSON.stringify(rawJwtKeys);
         const cachedParsedKeys = this.cachedParsedJwtKeys[cacheKey];
-        const parsedKeys = cachedParsedKeys ?? (await parseJwtKeys(rawJwtKeys));
+        const parsedKeys = cachedParsedKeys || (await parseJwtKeys(rawJwtKeys));
         if (!cachedParsedKeys) {
             this.cachedParsedJwtKeys = { [cacheKey]: parsedKeys };
         }
@@ -193,25 +182,22 @@ export class BackendAuthClient {
             audience: 'server-context',
             issuer: 'server-auth',
             jwtDuration: this.config.userSessionIdleTimeout || defaultSessionIdleTimeout,
+            allowedClockSkew: this.config.allowedClockSkew || defaultAllowedClockSkew,
         };
     }
     /** Use these headers to log out the user. */
     async createLogoutHeaders(params) {
-        authLog('auth-vir: LOGOUT - BackendAuthClient.createLogoutHeaders called', {
-            allCookies: 'allCookies' in params ? params.allCookies : undefined,
-            isSignUpCookie: 'isSignUpCookie' in params ? params.isSignUpCookie : undefined,
-        }, new Error().stack);
         const signUpCookieHeaders = params.allCookies || params.isSignUpCookie
             ? generateLogoutHeaders(await this.getCookieParams({
                 isSignUpCookie: true,
                 requestHeaders: undefined,
-            }), this.config.overrides)
+            }), this.config.csrf)
             : undefined;
         const authCookieHeaders = params.allCookies || !params.isSignUpCookie
             ? generateLogoutHeaders(await this.getCookieParams({
                 isSignUpCookie: false,
                 requestHeaders: undefined,
-            }), this.config.overrides)
+            }), this.config.csrf)
             : undefined;
         const setCookieHeader = {
             'set-cookie': mergeHeaderValues(signUpCookieHeaders?.['set-cookie'], authCookieHeaders?.['set-cookie']),
@@ -233,14 +219,14 @@ export class BackendAuthClient {
             ? generateLogoutHeaders(await this.getCookieParams({
                 isSignUpCookie: !isSignUpCookie,
                 requestHeaders,
-            }), this.config.overrides)
+            }), this.config.csrf)
             : undefined;
-        const existingUserIdResult = await extractUserIdFromRequestHeaders(requestHeaders, await this.getJwtParams(), isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth, this.config.overrides);
+        const existingUserIdResult = await extractUserIdFromRequestHeaders(requestHeaders, await this.getJwtParams(), this.config.csrf, isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth);
         const sessionStartedAt = existingUserIdResult?.sessionStartedAt;
         const newCookieHeaders = await generateSuccessfulLoginHeaders(userId, await this.getCookieParams({
             isSignUpCookie,
             requestHeaders,
-        }), this.config.overrides, sessionStartedAt);
+        }), this.config.csrf, sessionStartedAt);
         return {
             ...newCookieHeaders,
             'set-cookie': mergeHeaderValues(newCookieHeaders['set-cookie'], discardOppositeCookieHeaders?.['set-cookie']),
@@ -270,18 +256,15 @@ export class BackendAuthClient {
         // eslint-disable-next-line @typescript-eslint/no-deprecated
         const userIdResult = await insecureExtractUserIdFromCookieAlone(requestHeaders, await this.getJwtParams(), AuthCookieName.Auth);
         if (!userIdResult) {
-            authLog('auth-vir: getInsecureUser failed - could not extract user from request');
             return undefined;
         }
         const user = await this.getDatabaseUser({
             isSignUpCookie: false,
             userId: userIdResult.userId,
             assumingUser: undefined,
+            requestHeaders,
         });
         if (!user) {
-            authLog('auth-vir: getInsecureUser failed - user not found in database', {
-                userId: userIdResult.userId,
-            });
             return undefined;
         }
         const refreshHeaders = allowUserAuthRefresh &&

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

@@ -1,12 +1,15 @@
 import { type createBlockingInterval, type JsonCompatibleObject, type MaybePromise, type PartialWithUndefined, type SelectFrom } from '@augment-vir/common';
 import { type AnyDuration } from 'date-vir';
 import { type EmptyObject } from 'type-fest';
+import { type CsrfHeaderNameOption } from '../csrf-token.js';
 /**
  * Config for {@link FrontendAuthClient}.
  *
  * @category Internal
  */
-export type FrontendAuthClientConfig = PartialWithUndefined<{
+export type FrontendAuthClientConfig = Readonly<{
+    csrf: Readonly<CsrfHeaderNameOption>;
+}> & PartialWithUndefined<{
     /**
      * 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.
@@ -15,8 +18,8 @@ export type FrontendAuthClientConfig = PartialWithUndefined<{
     /** Called whenever the current user becomes unauthorized and their CSRF token is wiped. */
     authClearedCallback: () => MaybePromise<void>;
     /**
-     * Performs automatic checks on an interval to see if the user is still authenticated. Omit this
-     * to turn off automatic checks.
+     * Performs automatic checks on an interval to see if the user is still authenticated. Omit
+     * this to turn off automatic checks.
      */
     checkUser: {
         /**
@@ -27,8 +30,8 @@ export type FrontendAuthClientConfig = PartialWithUndefined<{
          * If the user is not currently authorized, this should return `undefined` to prevent
          * unnecessary network traffic.
          *
-         * This will be called any time the user interacts with the page, debounced by the adjacent
-         * `debounce` property.
+         * This will be called any time the user interacts with the page, debounced by the
+         * adjacent `debounce` property.
          */
         performCheck: () => MaybePromise<SelectFrom<Response, {
             status: true;
@@ -40,10 +43,20 @@ export type FrontendAuthClientConfig = PartialWithUndefined<{
          */
         debounce?: AnyDuration | undefined;
     };
+    /**
+     * Overwrite the header name used for tracking is an admin is assuming the identity of
+     * another user.
+     */
+    assumedUserHeaderName: string;
+    /**
+     * Allowed clock skew tolerance for CSRF token expiration checks. Accounts for differences
+     * between server and client clocks.
+     *
+     * @default {minutes: 5}
+     */
+    allowedClockSkew: Readonly<AnyDuration>;
     overrides: PartialWithUndefined<{
         localStorage: Pick<Storage, 'setItem' | 'removeItem' | 'getItem'>;
-        csrfHeaderName: string;
-        assumedUserHeaderName: string;
     }>;
 }>;
 /**
@@ -51,21 +64,21 @@ export type FrontendAuthClientConfig = PartialWithUndefined<{
  * in a frontend environment as it accesses native browser APIs.
  *
  * @category Auth : Client
- * @category Client
+ * @category Clients
  */
 export declare class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject = EmptyObject> {
     protected readonly config: FrontendAuthClientConfig;
     protected userCheckInterval: undefined | ReturnType<typeof createBlockingInterval>;
     /** Used to clean up the activity listener on `.destroy()`. */
     protected removeActivityListener: VoidFunction | undefined;
-    constructor(config?: FrontendAuthClientConfig);
+    constructor(config: FrontendAuthClientConfig);
     /**
      * Destroys the client and performs all necessary cleanup (like clearing the user check
      * interval).
      */
     destroy(): void;
     /** Wraps {@link getCurrentCsrfToken} to automatically handle wiping an invalid CSRF token. */
-    getCurrentCsrfToken(): Promise<string | undefined>;
+    getCurrentCsrfToken(): string | undefined;
     /**
      * Assume the given user. Pass `undefined` to wipe the currently assumed user.
      *
@@ -80,7 +93,7 @@ export declare class FrontendAuthClient<AssumedUserParams extends JsonCompatible
      * `@augment-vir/common`](https://electrovir.github.io/augment-vir/functions/mergeDeep.html) to
      * combine them with these.
      */
-    createAuthenticatedRequestInit(): Promise<RequestInit>;
+    createAuthenticatedRequestInit(): RequestInit;
     /** Wipes the current user auth. */
     logout(): Promise<void>;
     /**