auth-vir 3.0.1 → 3.1.1

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

@@ -91,6 +91,12 @@ export type BackendAuthClientConfig<
          */
         isDev: boolean;
     } & PartialWithUndefined<{
+        /** If this returns true, logging will be enabled while handling the relevant session. */
+        enableLogging(params: {
+            user: DatabaseUser | undefined;
+            userId: UserId | undefined;
+            assumedUserParams: AssumedUserParams | undefined;
+        }): boolean;
         /**
          * Overwrite the header name used for tracking is an admin is assuming the identity of
          * another user.
@@ -103,6 +109,8 @@ export type BackendAuthClientConfig<
         generateServiceOrigin(params: {
             requestHeaders: Readonly<IncomingHttpHeaders>;
         }): MaybePromise<undefined | string>;
+        /** If provided, logs will be sent to this method. */
+        log?: (message: string, extraData: AnyObject) => void;
         /**
          * Set this to allow specific users (determined by `canAssumeUser`) to assume the identity
          * of other users. This should only be used for admins so that they can troubleshoot user
@@ -197,6 +205,30 @@ export class BackendAuthClient<
         protected readonly config: BackendAuthClientConfig<DatabaseUser, UserId, AssumedUserParams>,
     ) {}
 
+    /** Conditionally logs a message if logging is enabled for the given user context. */
+    protected logForUser(
+        params: {
+            user: DatabaseUser | undefined;
+            userId: UserId | undefined;
+            assumedUserParams: AssumedUserParams | undefined;
+        },
+        message: string,
+        extra?: Record<string, unknown>,
+    ): void {
+        if (this.config.enableLogging?.(params)) {
+            const extraData = {
+                userId: params.userId,
+                ...extra,
+            };
+
+            if (this.config.log) {
+                this.config.log(message, extraData);
+            } else {
+                console.info(`[auth-vir] ${message}`, extraData);
+            }
+        }
+    }
+
     /** Get all the parameters used for cookie generation. */
     protected async getCookieParams({
         isSignUpCookie,
@@ -212,7 +244,9 @@ export class BackendAuthClient<
         requestHeaders: Readonly<IncomingHttpHeaders> | undefined;
     }): Promise<Readonly<CookieParams>> {
         const serviceOrigin = requestHeaders
-            ? await this.config.generateServiceOrigin?.({requestHeaders})
+            ? await this.config.generateServiceOrigin?.({
+                  requestHeaders,
+              })
             : undefined;
 
         return {
@@ -248,6 +282,17 @@ export class BackendAuthClient<
         });
 
         if (!authenticatedUser) {
+            this.logForUser(
+                {
+                    user: undefined,
+                    userId,
+                    assumedUserParams: assumingUser,
+                },
+                'getUserFromDatabase returned no user',
+                {
+                    isSignUpCookie,
+                },
+            );
             return undefined;
         }
 
@@ -273,6 +318,18 @@ export class BackendAuthClient<
         });
 
         if (isExpiredAlready) {
+            this.logForUser(
+                {
+                    user: undefined,
+                    userId: userIdResult.userId,
+                    assumedUserParams: undefined,
+                },
+                'Session refresh denied: JWT already expired (even with clock skew tolerance)',
+                {
+                    jwtExpiration: userIdResult.jwtExpiration,
+                    now: JSON.stringify(now),
+                },
+            );
             return undefined;
         }
 
@@ -290,6 +347,19 @@ export class BackendAuthClient<
             });
 
             if (isSessionExpired) {
+                this.logForUser(
+                    {
+                        user: undefined,
+                        userId: userIdResult.userId,
+                        assumedUserParams: undefined,
+                    },
+                    'Session refresh denied: max session duration exceeded',
+                    {
+                        sessionStartedAt: userIdResult.sessionStartedAt,
+                        maxSessionEndDate: JSON.stringify(maxSessionEndDate),
+                        now: JSON.stringify(now),
+                    },
+                );
                 return undefined;
             }
         }
@@ -327,6 +397,18 @@ export class BackendAuthClient<
                 }),
             };
         } else {
+            this.logForUser(
+                {
+                    user: undefined,
+                    userId: userIdResult.userId,
+                    assumedUserParams: undefined,
+                },
+                'Session refresh skipped: not yet ready for refresh',
+                {
+                    jwtIssuedAt: userIdResult.jwtIssuedAt,
+                    sessionRefreshStartTime,
+                },
+            );
             return undefined;
         }
     }
@@ -390,6 +472,17 @@ export class BackendAuthClient<
             isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth,
         );
         if (!userIdResult) {
+            this.logForUser(
+                {
+                    user: undefined,
+                    userId: undefined,
+                    assumedUserParams: undefined,
+                },
+                'getSecureUser: failed to extract user ID from request headers (invalid JWT, missing cookie, or CSRF mismatch)',
+                {
+                    isSignUpCookie,
+                },
+            );
             return undefined;
         }
 
@@ -401,6 +494,17 @@ export class BackendAuthClient<
         });
 
         if (!user) {
+            this.logForUser(
+                {
+                    user: undefined,
+                    userId: userIdResult.userId,
+                    assumedUserParams: undefined,
+                },
+                'getSecureUser: user not found in database',
+                {
+                    isSignUpCookie,
+                },
+            );
             return undefined;
         }
 
@@ -435,7 +539,9 @@ export class BackendAuthClient<
         const parsedKeys = cachedParsedKeys || (await parseJwtKeys(rawJwtKeys));
 
         if (!cachedParsedKeys) {
-            this.cachedParsedJwtKeys = {[cacheKey]: parsedKeys};
+            this.cachedParsedJwtKeys = {
+                [cacheKey]: parsedKeys,
+            };
         }
         return {
             jwtKeys: parsedKeys,
@@ -469,7 +575,6 @@ export class BackendAuthClient<
                           isSignUpCookie: true,
                           requestHeaders: undefined,
                       }),
-                      this.config.csrf,
                   )
                 : undefined;
         const authCookieHeaders =
@@ -479,26 +584,41 @@ export class BackendAuthClient<
                           isSignUpCookie: false,
                           requestHeaders: undefined,
                       }),
-                      this.config.csrf,
                   )
                 : undefined;
 
-        const setCookieHeader: {
-            'set-cookie': string[];
-        } = {
+        return {
             'set-cookie': mergeHeaderValues(
                 signUpCookieHeaders?.['set-cookie'],
                 authCookieHeaders?.['set-cookie'],
             ),
         };
-        const csrfTokenHeader = {
-            ...authCookieHeaders,
-            ...signUpCookieHeaders,
-        };
+    }
+
+    /**
+     * Refreshes a login session by reissuing the auth cookie with the same CSRF token instead of
+     * generating a new one.
+     */
+    protected async refreshLoginHeaders({
+        userId,
+        cookieParams,
+        existingUserIdResult,
+    }: {
+        userId: UserId;
+        cookieParams: Readonly<CookieParams>;
+        existingUserIdResult: Readonly<UserIdResult<UserId>>;
+    }): Promise<Record<string, string>> {
+        const {cookie} = await generateAuthCookie(
+            {
+                csrfToken: existingUserIdResult.csrfToken,
+                userId,
+                sessionStartedAt: existingUserIdResult.sessionStartedAt,
+            },
+            cookieParams,
+        );
 
         return {
-            ...csrfTokenHeader,
-            ...setCookieHeader,
+            'set-cookie': cookie,
         };
     }
 
@@ -521,7 +641,6 @@ export class BackendAuthClient<
                       isSignUpCookie: !isSignUpCookie,
                       requestHeaders,
                   }),
-                  this.config.csrf,
               )
             : undefined;
 
@@ -531,17 +650,19 @@ export class BackendAuthClient<
             this.config.csrf,
             isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth,
         );
-        const sessionStartedAt = existingUserIdResult?.sessionStartedAt;
 
-        const newCookieHeaders = await generateSuccessfulLoginHeaders(
-            userId,
-            await this.getCookieParams({
-                isSignUpCookie,
-                requestHeaders,
-            }),
-            this.config.csrf,
-            sessionStartedAt,
-        );
+        const cookieParams = await this.getCookieParams({
+            isSignUpCookie,
+            requestHeaders,
+        });
+
+        const newCookieHeaders = existingUserIdResult
+            ? await this.refreshLoginHeaders({
+                  userId,
+                  cookieParams,
+                  existingUserIdResult,
+              })
+            : await generateSuccessfulLoginHeaders(userId, cookieParams, this.config.csrf);
 
         return {
             ...newCookieHeaders,
@@ -584,13 +705,19 @@ export class BackendAuthClient<
         const secureUser = await this.getSecureUser(params);
 
         if (secureUser) {
-            return {secureUser};
+            return {
+                secureUser,
+            };
         }
 
         // eslint-disable-next-line @typescript-eslint/no-deprecated
         const insecureUser = await this.getInsecureUser(params);
 
-        return insecureUser ? {insecureUser} : {};
+        return insecureUser
+            ? {
+                  insecureUser,
+              }
+            : {};
     }
 
     /**
@@ -618,6 +745,14 @@ export class BackendAuthClient<
         );
 
         if (!userIdResult) {
+            this.logForUser(
+                {
+                    user: undefined,
+                    userId: undefined,
+                    assumedUserParams: undefined,
+                },
+                'getInsecureUser: failed to extract user ID from cookie (invalid JWT or missing cookie)',
+            );
             return undefined;
         }
 
@@ -629,6 +764,14 @@ export class BackendAuthClient<
         });
 
         if (!user) {
+            this.logForUser(
+                {
+                    user: undefined,
+                    userId: userIdResult.userId,
+                    assumedUserParams: undefined,
+                },
+                'getInsecureUser: user not found in database',
+            );
             return undefined;
         }
 

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

@@ -9,15 +9,14 @@ import {
 import {type AnyDuration} from 'date-vir';
 import {listenToActivity} from 'detect-activity';
 import {type EmptyObject} from 'type-fest';
+import {type CsrfTokenStore} from '../csrf-token-store.js';
 import {
     type CsrfHeaderNameOption,
-    CsrfTokenFailureReason,
     defaultAllowedClockSkew,
     extractCsrfTokenHeader,
     getCurrentCsrfToken,
     resolveCsrfHeaderName,
     storeCsrfToken,
-    wipeCurrentCsrfToken,
 } from '../csrf-token.js';
 import {AuthHeaderName} from '../headers.js';
 
@@ -85,6 +84,7 @@ export type FrontendAuthClientConfig = Readonly<{
 
         overrides: PartialWithUndefined<{
             localStorage: Pick<Storage, 'setItem' | 'removeItem' | 'getItem'>;
+            csrfTokenStore: CsrfTokenStore;
         }>;
     }>;
 
@@ -112,7 +112,9 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
                         });
                     }
                 },
-                debounce: config.checkUser.debounce || {minutes: 1},
+                debounce: config.checkUser.debounce || {
+                    minutes: 1,
+                },
                 fireImmediately: false,
             });
         }
@@ -128,20 +130,14 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
     }
 
     /** Wraps {@link getCurrentCsrfToken} to automatically handle wiping an invalid CSRF token. */
-    public getCurrentCsrfToken(): string | undefined {
-        const csrfTokenResult = getCurrentCsrfToken({
+    public async getCurrentCsrfToken(): Promise<string | undefined> {
+        const csrfTokenResult = await getCurrentCsrfToken({
             ...this.config.csrf,
-            localStorage: this.config.overrides?.localStorage,
+            csrfTokenStore: this.config.overrides?.csrfTokenStore,
             allowedClockSkew: this.config.allowedClockSkew || defaultAllowedClockSkew,
         });
 
         if (csrfTokenResult.failure) {
-            if (csrfTokenResult.failure !== CsrfTokenFailureReason.DoesNotExist) {
-                wipeCurrentCsrfToken({
-                    ...this.config.csrf,
-                    localStorage: this.config.overrides?.localStorage,
-                });
-            }
             return undefined;
         }
 
@@ -162,9 +158,7 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
         if (!assumedUserParams) {
             localStorage.removeItem(storageKey);
             return true;
-        }
-
-        if (!(await this.config.canAssumeUser?.())) {
+        } else if (!(await this.config.canAssumeUser?.())) {
             return false;
         }
 
@@ -195,8 +189,8 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
      * `@augment-vir/common`](https://electrovir.github.io/augment-vir/functions/mergeDeep.html) to
      * combine them with these.
      */
-    public createAuthenticatedRequestInit(): RequestInit {
-        const csrfToken = this.getCurrentCsrfToken();
+    public async createAuthenticatedRequestInit(): Promise<RequestInit> {
+        const csrfToken = await this.getCurrentCsrfToken();
 
         const assumedUser = this.getAssumedUser();
         const headers: HeadersInit = {
@@ -222,10 +216,6 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
     /** Wipes the current user auth. */
     public async logout() {
         await this.config.authClearedCallback?.();
-        wipeCurrentCsrfToken({
-            ...this.config.csrf,
-            localStorage: this.config.overrides?.localStorage,
-        });
     }
 
     /**
@@ -259,9 +249,9 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
             throw new Error('Did not receive any CSRF token.');
         }
 
-        storeCsrfToken(csrfToken, {
+        await storeCsrfToken(csrfToken, {
             ...this.config.csrf,
-            localStorage: this.config.overrides?.localStorage,
+            csrfTokenStore: this.config.overrides?.csrfTokenStore,
         });
     }
 
@@ -297,9 +287,9 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
             allowedClockSkew: this.config.allowedClockSkew || defaultAllowedClockSkew,
         });
         if (csrfToken) {
-            storeCsrfToken(csrfToken, {
+            await storeCsrfToken(csrfToken, {
                 ...this.config.csrf,
-                localStorage: this.config.overrides?.localStorage,
+                csrfTokenStore: this.config.overrides?.csrfTokenStore,
             });
         }
 

package/src/auth.ts

@@ -7,6 +7,7 @@ import {
     extractCookieJwt,
     generateAuthCookie,
 } from './cookie.js';
+import {type CsrfTokenStore} from './csrf-token-store.js';
 import {
     type CsrfHeaderNameOption,
     extractCsrfTokenHeader,
@@ -14,7 +15,6 @@ import {
     parseCsrfToken,
     resolveCsrfHeaderName,
     storeCsrfToken,
-    wipeCurrentCsrfToken,
 } from './csrf-token.js';
 import {type ParseJwtParams} from './jwt/jwt.js';
 import {type JwtUserData} from './jwt/user-jwt.js';
@@ -202,48 +202,42 @@ export async function generateSuccessfulLoginHeaders(
  */
 export function generateLogoutHeaders(
     cookieConfig: Readonly<Pick<CookieParams, 'cookieName' | 'hostOrigin' | 'isDev'>>,
-    csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>,
 ): Record<string, string> {
-    const csrfHeaderName = resolveCsrfHeaderName(csrfHeaderNameOption);
-
     return {
         'set-cookie': clearAuthCookie(cookieConfig),
-        [csrfHeaderName]: 'redacted',
     };
 }
 
 /**
  * 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).
- * Alternatively, if the given response failed, this will wipe the existing (if anyone) stored CSRF
+ * Specifically, this stores the CSRF token into IndexedDB (which doesn't need to be a secret).
+ * Alternatively, if the given response failed, this will wipe the existing (if any) stored CSRF
  * token.
  *
  * @category Auth : Client
  * @throws Error if no CSRF token header is found.
  */
-export function handleAuthResponse(
+export async function handleAuthResponse(
     response: Readonly<Pick<Response, 'ok' | 'headers'>>,
     options: Readonly<CsrfHeaderNameOption> &
         PartialWithUndefined<{
             /**
-             * Allows mocking or overriding the global `localStorage`.
+             * Allows mocking or overriding the default CSRF token store.
              *
-             * @default globalThis.localStorage
+             * @default getDefaultCsrfTokenStore()
              */
-            localStorage: Pick<Storage, 'setItem' | 'removeItem'>;
+            csrfTokenStore: CsrfTokenStore;
         }>,
-) {
+): Promise<void> {
     if (!response.ok) {
-        wipeCurrentCsrfToken(options);
         return;
     }
 
     const {csrfToken} = extractCsrfTokenHeader(response, options);
 
     if (!csrfToken) {
-        wipeCurrentCsrfToken(options);
         throw new Error('Did not receive any CSRF token.');
     }
 
-    storeCsrfToken(csrfToken, options);
+    await storeCsrfToken(csrfToken, options);
 }

package/src/cookie.ts

@@ -91,7 +91,9 @@ export async function generateAuthCookie(
             HttpOnly: true,
             Path: '/',
             SameSite: 'Strict',
-            'MAX-AGE': convertDuration(cookieConfig.cookieDuration, {seconds: true}).seconds,
+            'MAX-AGE': convertDuration(cookieConfig.cookieDuration, {
+                seconds: true,
+            }).seconds,
             Secure: !cookieConfig.isDev,
         }),
         expiration,

package/src/csrf-token-store.ts

@@ -0,0 +1,54 @@
+import {LocalDbClient} from 'local-db-client';
+import {defineShape} from 'object-shape-tester';
+
+const csrfTokenDbShapes = {
+    csrfToken: defineShape(''),
+} as const;
+
+/**
+ * The interface used for overriding the default CSRF token store in storage functions.
+ *
+ * @category Internal
+ */
+export type CsrfTokenStore = {
+    /** Retrieves the stored CSRF token, if any. */
+    getCsrfToken(): Promise<string | undefined>;
+    /** Stores a CSRF token. */
+    setCsrfToken(value: string): Promise<void>;
+    /** Deletes the stored CSRF token. */
+    deleteCsrfToken(): Promise<void>;
+};
+
+async function createDefaultCsrfTokenStore(): Promise<CsrfTokenStore> {
+    const client = await LocalDbClient.createClient(csrfTokenDbShapes, {
+        storeName: 'auth-vir-csrf',
+    });
+
+    return {
+        async getCsrfToken() {
+            return (await client.load.csrfToken()) || undefined;
+        },
+        async setCsrfToken(value) {
+            await client.set.csrfToken(value);
+        },
+        async deleteCsrfToken() {
+            await client.delete.csrfToken();
+        },
+    };
+}
+
+/**
+ * The default {@link LocalDbClient} instance used for storing CSRF tokens. This uses a dedicated
+ * store name to avoid collisions with other storage. Lazily initialized to avoid crashes in Node.js
+ * environments where IndexedDB is not available.
+ *
+ * @category Internal
+ */
+export async function getDefaultCsrfTokenStore(): Promise<CsrfTokenStore> {
+    if (!cachedStorePromise) {
+        cachedStorePromise = createDefaultCsrfTokenStore();
+    }
+    return cachedStorePromise;
+}
+
+let cachedStorePromise: Promise<CsrfTokenStore> | undefined;