auth-vir 2.6.0 → 2.7.1

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

@@ -4,6 +4,7 @@ import { extractUserIdFromRequestHeaders, generateLogoutHeaders, generateSuccess
 import { AuthCookieName } from '../cookie.js';
 import { AuthHeaderName, mergeHeaderValues } from '../headers.js';
 import { parseJwtKeys } from '../jwt/jwt-keys.js';
+import { authLog } from '../log.js';
 const defaultSessionIdleTimeout = {
     minutes: 20,
 };
@@ -63,6 +64,10 @@ export class BackendAuthClient {
             relativeTo: userIdResult.jwtExpiration,
         });
         if (isExpiredAlready) {
+            authLog('auth-vir: SESSION EXPIRED - JWT already expired, user will be logged out', {
+                userId: userIdResult.userId,
+                jwtExpiration: userIdResult.jwtExpiration,
+            });
             return undefined;
         }
         /**
@@ -78,6 +83,11 @@ 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;
             }
         }
@@ -136,6 +146,7 @@ export class BackendAuthClient {
     async getSecureUser({ requestHeaders, isSignUpCookie, allowUserAuthRefresh, }) {
         const userIdResult = await extractUserIdFromRequestHeaders(requestHeaders, await this.getJwtParams(), isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth, this.config.overrides);
         if (!userIdResult) {
+            authLog('auth-vir: getSecureUser failed - could not extract user from request');
             return undefined;
         }
         const user = await this.getDatabaseUser({
@@ -144,6 +155,9 @@ export class BackendAuthClient {
             isSignUpCookie,
         });
         if (!user) {
+            authLog('auth-vir: getSecureUser failed - user not found in database', {
+                userId: userIdResult.userId,
+            });
             return undefined;
         }
         const assumedUser = await this.getAssumedUser({
@@ -181,6 +195,10 @@ export class BackendAuthClient {
     }
     /** 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,
@@ -250,6 +268,7 @@ 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({
@@ -258,6 +277,9 @@ export class BackendAuthClient {
             assumingUser: undefined,
         });
         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.js

@@ -2,6 +2,7 @@ import { HttpStatus, } from '@augment-vir/common';
 import { listenToActivity } from 'detect-activity';
 import { CsrfTokenFailureReason, extractCsrfTokenHeader, getCurrentCsrfToken, 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.
@@ -44,6 +45,9 @@ export class FrontendAuthClient {
         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();
             return undefined;
         }
@@ -110,6 +114,7 @@ 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);
     }
@@ -121,11 +126,13 @@ 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);
         if (!csrfToken) {
+            authLog('auth-vir: LOGOUT - handleLoginResponse: no CSRF token in response');
             await this.logout();
             throw new Error('Did not receive any CSRF token.');
         }
@@ -140,6 +147,9 @@ 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;
         }

package/dist/auth.js

@@ -1,6 +1,7 @@
 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';
 function readHeader(headers, headerName) {
     if (headers instanceof Headers) {
         return headers.get(headerName) || undefined;
@@ -38,10 +39,20 @@ export async function extractUserIdFromRequestHeaders(headers, jwtParams, cookie
         const csrfToken = readCsrfTokenHeader(headers, overrides);
         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) {
+            authLog('auth-vir: extractUserIdFromRequestHeaders failed - JWT invalid or CSRF mismatch', {
+                hasJwt: !!jwt,
+                csrfMatch: jwt ? jwt.data.csrfToken === csrfToken : false,
+                cookieName,
+            });
             return undefined;
         }
         return {
@@ -51,7 +62,8 @@ export async function extractUserIdFromRequestHeaders(headers, jwtParams, cookie
             sessionStartedAt: jwt.data.sessionStartedAt,
         };
     }
-    catch {
+    catch (error) {
+        authLog('auth-vir: extractUserIdFromRequestHeaders error', { error, cookieName });
         return undefined;
     }
 }
@@ -67,10 +79,12 @@ 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 {
@@ -80,7 +94,8 @@ export async function insecureExtractUserIdFromCookieAlone(headers, jwtParams, c
             sessionStartedAt: jwt.data.sessionStartedAt,
         };
     }
-    catch {
+    catch (error) {
+        authLog('auth-vir: insecureExtractUserIdFromCookieAlone error', { error });
         return undefined;
     }
 }
@@ -115,6 +130,9 @@ 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);
     return {
         'set-cookie': clearAuthCookie(cookieConfig),
@@ -132,13 +150,16 @@ export function generateLogoutHeaders(cookieConfig, overrides = {}) {
  */
 export function handleAuthResponse(response, overrides = {}) {
     if (!response.ok) {
+        authLog('auth-vir: LOGOUT - handleAuthResponse: response not ok, wiping CSRF token');
         wipeCurrentCsrfToken(overrides);
         return;
     }
     const { csrfToken } = extractCsrfTokenHeader(response, overrides);
     if (!csrfToken) {
+        authLog('auth-vir: LOGOUT - handleAuthResponse: no CSRF token in response, wiping');
         wipeCurrentCsrfToken(overrides);
         throw new Error('Did not receive any CSRF token.');
     }
+    authLog('auth-vir: handleAuthResponse - successfully stored CSRF token');
     storeCsrfToken(csrfToken, overrides);
 }

package/dist/csrf-token.js

@@ -2,6 +2,7 @@ import { randomString, wrapInTry, } from '@augment-vir/common';
 import { calculateRelativeDate, fullDateShape, getNowInUtcTimezone, isDateAfter, } from 'date-vir';
 import { defineShape, parseJsonWithShape } from 'object-shape-tester';
 import { AuthHeaderName } from './headers.js';
+import { authLog } from './log.js';
 /**
  * Shape definition for {@link CsrfToken}.
  *
@@ -74,6 +75,7 @@ export function parseCsrfToken(value) {
         fallbackValue: undefined,
     });
     if (!csrfToken) {
+        authLog('auth-vir: CSRF token parse failed - will cause logout if used');
         return {
             failure: CsrfTokenFailureReason.ParseFailed,
         };
@@ -82,6 +84,9 @@ export function parseCsrfToken(value) {
         fullDate: getNowInUtcTimezone(),
         relativeTo: csrfToken.expiration,
     })) {
+        authLog('auth-vir: CSRF token expired - will cause logout', {
+            expiration: csrfToken.expiration,
+        });
         return {
             failure: CsrfTokenFailureReason.Expired,
         };
@@ -107,5 +112,6 @@ export function getCurrentCsrfToken(overrides = {}) {
  * @category Auth : Client
  */
 export function wipeCurrentCsrfToken(overrides = {}) {
+    authLog('auth-vir: wipeCurrentCsrfToken called', new Error().stack);
     return (overrides.localStorage || globalThis.localStorage).removeItem(overrides.csrfHeaderName || AuthHeaderName.CsrfToken);
 }

package/dist/index.d.ts

@@ -8,4 +8,5 @@ export * from './headers.js';
 export * from './jwt/jwt-keys.js';
 export * from './jwt/jwt.js';
 export * from './jwt/user-jwt.js';
+export * from './log.js';
 export * from './mock-local-storage.js';

package/dist/index.js

@@ -8,4 +8,5 @@ export * from './headers.js';
 export * from './jwt/jwt-keys.js';
 export * from './jwt/jwt.js';
 export * from './jwt/user-jwt.js';
+export * from './log.js';
 export * from './mock-local-storage.js';

package/dist/log.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Send logs to the console for debugging.
+ *
+ * @category Internal
+ */
+export declare function authLog(...params: any[]): void;
+/**
+ * Set to `false` to disable logging.
+ *
+ * @category Internal
+ */
+export declare function setShouldLogAuth(value: boolean): void;

package/dist/log.js

@@ -0,0 +1,20 @@
+/**
+ * Send logs to the console for debugging.
+ *
+ * @category Internal
+ */
+export function authLog(...params) {
+    if (!shouldLogAuth) {
+        return;
+    }
+    console.info(...params);
+}
+let shouldLogAuth = true;
+/**
+ * Set to `false` to disable logging.
+ *
+ * @category Internal
+ */
+export function setShouldLogAuth(value) {
+    shouldLogAuth = value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auth-vir",
-    "version": "2.6.0",
+    "version": "2.7.1",
     "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

@@ -26,6 +26,7 @@ import {AuthCookieName, type CookieParams} from '../cookie.js';
 import {AuthHeaderName, mergeHeaderValues} from '../headers.js';
 import {generateNewJwtKeys, parseJwtKeys, type JwtKeys, type RawJwtKeys} from '../jwt/jwt-keys.js';
 import {type CreateJwtParams} from '../jwt/jwt.js';
+import {authLog} from '../log.js';
 
 /**
  * Output from `BackendAuthClient.getSecureUser()`.
@@ -260,6 +261,10 @@ export class BackendAuthClient<
         });
 
         if (isExpiredAlready) {
+            authLog('auth-vir: SESSION EXPIRED - JWT already expired, user will be logged out', {
+                userId: userIdResult.userId,
+                jwtExpiration: userIdResult.jwtExpiration,
+            });
             return undefined;
         }
 
@@ -277,6 +282,14 @@ export class BackendAuthClient<
             });
 
             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;
             }
         }
@@ -375,6 +388,7 @@ export class BackendAuthClient<
             this.config.overrides,
         );
         if (!userIdResult) {
+            authLog('auth-vir: getSecureUser failed - could not extract user from request');
             return undefined;
         }
 
@@ -385,6 +399,9 @@ export class BackendAuthClient<
         });
 
         if (!user) {
+            authLog('auth-vir: getSecureUser failed - user not found in database', {
+                userId: userIdResult.userId,
+            });
             return undefined;
         }
 
@@ -445,6 +462,14 @@ export class BackendAuthClient<
             'set-cookie': string[];
         }
     > {
+        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(
@@ -601,6 +626,7 @@ export class BackendAuthClient<
         );
 
         if (!userIdResult) {
+            authLog('auth-vir: getInsecureUser failed - could not extract user from request');
             return undefined;
         }
 
@@ -611,6 +637,9 @@ export class BackendAuthClient<
         });
 
         if (!user) {
+            authLog('auth-vir: getInsecureUser failed - user not found in database', {
+                userId: userIdResult.userId,
+            });
             return undefined;
         }
 

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

@@ -17,6 +17,7 @@ import {
     wipeCurrentCsrfToken,
 } from '../csrf-token.js';
 import {AuthHeaderName} from '../headers.js';
+import {authLog} from '../log.js';
 
 /**
  * Config for {@link FrontendAuthClient}.
@@ -119,6 +120,9 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
             csrfTokenResult.failure &&
             csrfTokenResult.failure !== CsrfTokenFailureReason.DoesNotExist
         ) {
+            authLog('auth-vir: LOGOUT - getCurrentCsrfToken: invalid CSRF token', {
+                failure: csrfTokenResult.failure,
+            });
             await this.logout();
             return undefined;
         } else {
@@ -200,6 +204,7 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
 
     /** Wipes the current user auth. */
     public async logout() {
+        authLog('auth-vir: LOGOUT - FrontendAuthClient.logout called', new Error().stack);
         await this.config.authClearedCallback?.();
         wipeCurrentCsrfToken(this.config.overrides);
     }
@@ -222,6 +227,7 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
         >,
     ): Promise<void> {
         if (!response.ok) {
+            authLog('auth-vir: LOGOUT - handleLoginResponse: response not ok');
             await this.logout();
             throw new Error('Login response failed.');
         }
@@ -229,6 +235,7 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
         const {csrfToken} = extractCsrfTokenHeader(response, this.config.overrides);
 
         if (!csrfToken) {
+            authLog('auth-vir: LOGOUT - handleLoginResponse: no CSRF token in response');
             await this.logout();
             throw new Error('Did not receive any CSRF token.');
         }
@@ -259,6 +266,9 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
             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;
         }

package/src/auth.ts

@@ -17,6 +17,7 @@ import {
 import {AuthHeaderName} from './headers.js';
 import {type ParseJwtParams} from './jwt/jwt.js';
 import {type JwtUserData} from './jwt/user-jwt.js';
+import {authLog} from './log.js';
 
 /**
  * All possible headers container types supported by {@link extractUserIdFromRequestHeaders}.
@@ -93,12 +94,28 @@ export async function extractUserIdFromRequestHeaders<UserId extends string | nu
         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) {
+            authLog(
+                'auth-vir: extractUserIdFromRequestHeaders failed - JWT invalid or CSRF mismatch',
+                {
+                    hasJwt: !!jwt,
+                    csrfMatch: jwt ? jwt.data.csrfToken === csrfToken : false,
+                    cookieName,
+                },
+            );
             return undefined;
         }
 
@@ -108,7 +125,8 @@ export async function extractUserIdFromRequestHeaders<UserId extends string | nu
             cookieName,
             sessionStartedAt: jwt.data.sessionStartedAt,
         };
-    } catch {
+    } catch (error) {
+        authLog('auth-vir: extractUserIdFromRequestHeaders error', {error, cookieName});
         return undefined;
     }
 }
@@ -130,12 +148,16 @@ export async function insecureExtractUserIdFromCookieAlone<UserId extends string
         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;
         }
 
@@ -145,7 +167,8 @@ export async function insecureExtractUserIdFromCookieAlone<UserId extends string
             cookieName,
             sessionStartedAt: jwt.data.sessionStartedAt,
         };
-    } catch {
+    } catch (error) {
+        authLog('auth-vir: insecureExtractUserIdFromCookieAlone error', {error});
         return undefined;
     }
 }
@@ -206,6 +229,13 @@ export function generateLogoutHeaders<CsrfHeaderName extends string = AuthHeader
 ): {
     'set-cookie': string;
 } & Record<CsrfHeaderName, string> {
+    authLog(
+        'auth-vir: LOGOUT - generateLogoutHeaders called',
+        {
+            cookieName: cookieConfig.cookieName,
+        },
+        new Error().stack,
+    );
     const csrfHeaderName = (overrides.csrfHeaderName || AuthHeaderName.CsrfToken) as CsrfHeaderName;
 
     return {
@@ -239,6 +269,7 @@ export function handleAuthResponse(
     }> = {},
 ) {
     if (!response.ok) {
+        authLog('auth-vir: LOGOUT - handleAuthResponse: response not ok, wiping CSRF token');
         wipeCurrentCsrfToken(overrides);
         return;
     }
@@ -246,9 +277,11 @@ export function handleAuthResponse(
     const {csrfToken} = extractCsrfTokenHeader(response, overrides);
 
     if (!csrfToken) {
+        authLog('auth-vir: LOGOUT - handleAuthResponse: no CSRF token in response, wiping');
         wipeCurrentCsrfToken(overrides);
         throw new Error('Did not receive any CSRF token.');
     }
 
+    authLog('auth-vir: handleAuthResponse - successfully stored CSRF token');
     storeCsrfToken(csrfToken, overrides);
 }

package/src/csrf-token.ts

@@ -14,6 +14,7 @@ import {
 import {defineShape, parseJsonWithShape} from 'object-shape-tester';
 import {type RequireExactlyOne} from 'type-fest';
 import {AuthHeaderName} from './headers.js';
+import {authLog} from './log.js';
 
 /**
  * Shape definition for {@link CsrfToken}.
@@ -137,6 +138,7 @@ export function parseCsrfToken(value: string | undefined | null): Readonly<GetCs
     );
 
     if (!csrfToken) {
+        authLog('auth-vir: CSRF token parse failed - will cause logout if used');
         return {
             failure: CsrfTokenFailureReason.ParseFailed,
         };
@@ -148,6 +150,9 @@ export function parseCsrfToken(value: string | undefined | null): Readonly<GetCs
             relativeTo: csrfToken.expiration,
         })
     ) {
+        authLog('auth-vir: CSRF token expired - will cause logout', {
+            expiration: csrfToken.expiration,
+        });
         return {
             failure: CsrfTokenFailureReason.Expired,
         };
@@ -202,6 +207,7 @@ export function wipeCurrentCsrfToken(
         csrfHeaderName: string;
     }> = {},
 ) {
+    authLog('auth-vir: wipeCurrentCsrfToken called', new Error().stack);
     return (overrides.localStorage || globalThis.localStorage).removeItem(
         overrides.csrfHeaderName || AuthHeaderName.CsrfToken,
     );

package/src/index.ts

@@ -8,4 +8,5 @@ export * from './headers.js';
 export * from './jwt/jwt-keys.js';
 export * from './jwt/jwt.js';
 export * from './jwt/user-jwt.js';
+export * from './log.js';
 export * from './mock-local-storage.js';

package/src/log.ts

@@ -0,0 +1,22 @@
+/**
+ * Send logs to the console for debugging.
+ *
+ * @category Internal
+ */
+export function authLog(...params: any[]) {
+    if (!shouldLogAuth) {
+        return;
+    }
+    console.info(...params);
+}
+
+let shouldLogAuth = true;
+
+/**
+ * Set to `false` to disable logging.
+ *
+ * @category Internal
+ */
+export function setShouldLogAuth(value: boolean) {
+    shouldLogAuth = value;
+}