auth-vir 3.0.0 → 3.1.0

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

@@ -46,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
@@ -59,6 +60,12 @@ export type BackendAuthClientConfig<DatabaseUser extends AnyObject, UserId exten
      */
     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.
@@ -71,6 +78,8 @@ export type BackendAuthClientConfig<DatabaseUser extends AnyObject, UserId exten
     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
@@ -140,6 +149,12 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
     protected readonly config: BackendAuthClientConfig<DatabaseUser, UserId, AssumedUserParams>;
     protected cachedParsedJwtKeys: Record<string, Readonly<JwtKeys>>;
     constructor(config: BackendAuthClientConfig<DatabaseUser, UserId, AssumedUserParams>);
+    /** 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;
     /** Get all the parameters used for cookie generation. */
     protected getCookieParams({ isSignUpCookie, requestHeaders, }: {
         /**
@@ -152,10 +167,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, }: {
@@ -163,9 +179,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, }: {

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

@@ -28,10 +28,27 @@ export class BackendAuthClient {
     constructor(config) {
         this.config = config;
     }
+    /** Conditionally logs a message if logging is enabled for the given user context. */
+    logForUser(params, message, extra) {
+        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. */
     async getCookieParams({ isSignUpCookie, requestHeaders, }) {
         const serviceOrigin = requestHeaders
-            ? await this.config.generateServiceOrigin?.({ requestHeaders })
+            ? await this.config.generateServiceOrigin?.({
+                requestHeaders,
+            })
             : undefined;
         return {
             cookieDuration: this.config.userSessionIdleTimeout || defaultSessionIdleTimeout,
@@ -42,7 +59,7 @@ export class BackendAuthClient {
         };
     }
     /** Calls the provided `getUserFromDatabase` config. */
-    async getDatabaseUser({ isSignUpCookie, userId, assumingUser, }) {
+    async getDatabaseUser({ isSignUpCookie, userId, assumingUser, requestHeaders, }) {
         if (!userId) {
             return undefined;
         }
@@ -50,8 +67,16 @@ export class BackendAuthClient {
             assumingUser,
             userId,
             isSignUpCookie,
+            requestHeaders,
         });
         if (!authenticatedUser) {
+            this.logForUser({
+                user: undefined,
+                userId,
+                assumedUserParams: assumingUser,
+            }, 'getUserFromDatabase returned no user', {
+                isSignUpCookie,
+            });
             return undefined;
         }
         return authenticatedUser;
@@ -66,6 +91,14 @@ export class BackendAuthClient {
             relativeTo: calculateRelativeDate(userIdResult.jwtExpiration, clockSkew),
         });
         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;
         }
         /**
@@ -81,6 +114,15 @@ export class BackendAuthClient {
                 relativeTo: maxSessionEndDate,
             });
             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;
             }
         }
@@ -111,15 +153,23 @@ 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;
         }
     }
     /** 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.assumedUserHeaderName || AuthHeaderName.AssumedUser])[0];
+        const assumedUserHeader = ensureArray(requestHeaders[this.config.assumedUserHeaderName || AuthHeaderName.AssumedUser])[0];
         if (!assumedUserHeader) {
             return undefined;
         }
@@ -131,6 +181,7 @@ export class BackendAuthClient {
             isSignUpCookie: false,
             userId: parsedAssumedUserData.userId,
             assumingUser: parsedAssumedUserData.assumedUserParams,
+            requestHeaders,
         });
         return assumedUser;
     }
@@ -138,18 +189,33 @@ export class BackendAuthClient {
     async getSecureUser({ requestHeaders, isSignUpCookie, allowUserAuthRefresh, }) {
         const userIdResult = await extractUserIdFromRequestHeaders(requestHeaders, await this.getJwtParams(), this.config.csrf, 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;
         }
         const user = await this.getDatabaseUser({
             userId: userIdResult.userId,
             assumingUser: undefined,
             isSignUpCookie,
+            requestHeaders,
         });
         if (!user) {
+            this.logForUser({
+                user: undefined,
+                userId: userIdResult.userId,
+                assumedUserParams: undefined,
+            }, 'getSecureUser: user not found in database', {
+                isSignUpCookie,
+            });
             return undefined;
         }
         const assumedUser = await this.getAssumedUser({
-            headers: requestHeaders,
+            requestHeaders,
             user,
         });
         const cookieRefreshHeaders = (await this.createCookieRefreshHeaders({
@@ -172,7 +238,9 @@ export class BackendAuthClient {
         const cachedParsedKeys = this.cachedParsedJwtKeys[cacheKey];
         const parsedKeys = cachedParsedKeys || (await parseJwtKeys(rawJwtKeys));
         if (!cachedParsedKeys) {
-            this.cachedParsedJwtKeys = { [cacheKey]: parsedKeys };
+            this.cachedParsedJwtKeys = {
+                [cacheKey]: parsedKeys,
+            };
         }
         return {
             jwtKeys: parsedKeys,
@@ -238,11 +306,17 @@ export class BackendAuthClient {
     async getInsecureOrSecureUser(params) {
         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,
+            }
+            : {};
     }
     /**
      * @deprecated This only half authenticates the user. It should only be used in circumstances
@@ -253,14 +327,25 @@ export class BackendAuthClient {
         // eslint-disable-next-line @typescript-eslint/no-deprecated
         const userIdResult = await insecureExtractUserIdFromCookieAlone(requestHeaders, await this.getJwtParams(), AuthCookieName.Auth);
         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;
         }
         const user = await this.getDatabaseUser({
             isSignUpCookie: false,
             userId: userIdResult.userId,
             assumingUser: undefined,
+            requestHeaders,
         });
         if (!user) {
+            this.logForUser({
+                user: undefined,
+                userId: userIdResult.userId,
+                assumedUserParams: undefined,
+            }, 'getInsecureUser: user not found in database');
             return undefined;
         }
         const refreshHeaders = allowUserAuthRefresh &&

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

@@ -26,7 +26,9 @@ export class FrontendAuthClient {
                         });
                     }
                 },
-                debounce: config.checkUser.debounce || { minutes: 1 },
+                debounce: config.checkUser.debounce || {
+                    minutes: 1,
+                },
                 fireImmediately: false,
             });
         }

package/dist/cookie.js

@@ -29,7 +29,9 @@ export async function generateAuthCookie(userJwtData, cookieConfig) {
             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/dist/csrf-token.js

@@ -17,7 +17,9 @@ export const csrfTokenShape = defineShape({
  * @category Internal
  * @default {minutes: 5}
  */
-export const defaultAllowedClockSkew = { minutes: 5 };
+export const defaultAllowedClockSkew = {
+    minutes: 5,
+};
 /**
  * Generates a random, cryptographically secure CSRF token.
  *

package/dist/jwt/jwt.js

@@ -2,8 +2,13 @@ import { assertWrap, check } from '@augment-vir/assert';
 import { calculateRelativeDate, convertDuration, createFullDateInUserTimezone, createUtcFullDate, getNowInUtcTimezone, toTimestamp, } from 'date-vir';
 import { EncryptJWT, jwtDecrypt, jwtVerify, SignJWT } from 'jose';
 import { defaultAllowedClockSkew } from '../csrf-token.js';
-const encryptionProtectedHeader = { alg: 'dir', enc: 'A256GCM' };
-const signingProtectedHeader = { alg: 'HS512' };
+const encryptionProtectedHeader = {
+    alg: 'dir',
+    enc: 'A256GCM',
+};
+const signingProtectedHeader = {
+    alg: 'HS512',
+};
 /**
  * JWT uses seconds since the epoch per RFC 7519, whereas `toTimestamp` uses milliseconds.
  *
@@ -28,7 +33,9 @@ export function parseJwtTimestamp(seconds) {
 export async function createJwt(
 /** The data to be included in the JWT. */
 data, params) {
-    const rawJwt = new SignJWT({ data })
+    const rawJwt = new SignJWT({
+        data,
+    })
         .setProtectedHeader(signingProtectedHeader)
         .setIssuedAt(params.issuedAt
         ? toJwtTimestamp(createFullDateInUserTimezone(params.issuedAt))
@@ -40,7 +47,9 @@ data, params) {
         rawJwt.setNotBefore(toJwtTimestamp(createFullDateInUserTimezone(params.notValidUntil)));
     }
     const signedJwt = await rawJwt.sign(params.jwtKeys.signingKey);
-    return await new EncryptJWT({ jwt: signedJwt })
+    return await new EncryptJWT({
+        jwt: signedJwt,
+    })
         .setProtectedHeader(encryptionProtectedHeader)
         .encrypt(params.jwtKeys.encryptionKey);
 }
@@ -58,7 +67,9 @@ export async function parseJwt(encryptedJwt, params) {
     else if (!check.isString(decryptedJwt.payload.jwt)) {
         throw new TypeError('Decrypted jwt is not a string.');
     }
-    const clockToleranceSeconds = convertDuration(params.allowedClockSkew || defaultAllowedClockSkew, { seconds: true }).seconds;
+    const clockToleranceSeconds = convertDuration(params.allowedClockSkew || defaultAllowedClockSkew, {
+        seconds: true,
+    }).seconds;
     const verifiedJwt = await jwtVerify(decryptedJwt.payload.jwt, params.jwtKeys.signingKey, {
         issuer: params.issuer,
         audience: params.audience,

package/dist/jwt/user-jwt.js

@@ -19,7 +19,9 @@ export const userJwtDataShape = defineShape({
      * enforce the max session duration. If not present, the session is considered to have started
      * when the JWT was issued.
      */
-    sessionStartedAt: optionalShape(0, { alsoUndefined: true }),
+    sessionStartedAt: optionalShape(0, {
+        alsoUndefined: true,
+    }),
 });
 /**
  * Creates a new signed and encrypted {@link JwtUserData} when a client (frontend) successfully

package/dist/mock-local-storage.js

@@ -44,7 +44,10 @@ init = {}) {
             delete store[key];
         },
         setItem(key, value) {
-            accessRecord.setItem.push({ key, value });
+            accessRecord.setItem.push({
+                key,
+                value,
+            });
             store[key] = value;
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auth-vir",
-    "version": "3.0.0",
+    "version": "3.1.0",
     "description": "Auth made easy and secure via JWT cookies, CSRF tokens, and password hashing helpers.",
     "keywords": [
         "auth",
@@ -41,9 +41,9 @@
         "test:web": "virmator test web"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.65.0",
-        "@augment-vir/common": "^31.65.0",
-        "date-vir": "^8.1.1",
+        "@augment-vir/assert": "^31.67.1",
+        "@augment-vir/common": "^31.67.1",
+        "date-vir": "^8.2.0",
         "detect-activity": "^1.0.0",
         "hash-wasm": "^4.12.0",
         "jose": "^6.1.3",
@@ -52,9 +52,9 @@
         "url-vir": "^2.1.7"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.65.0",
+        "@augment-vir/test": "^31.67.1",
         "@prisma/client": "^6.19.2",
-        "@types/node": "^25.3.0",
+        "@types/node": "^25.3.3",
         "@web/dev-server-esbuild": "^1.0.5",
         "@web/test-runner": "^0.20.2",
         "@web/test-runner-commands": "^0.9.0",

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

@@ -77,6 +77,7 @@ export type BackendAuthClientConfig<
              * 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
@@ -90,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.
@@ -102,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
@@ -196,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,
@@ -211,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 {
@@ -228,10 +263,12 @@ export class BackendAuthClient<
         isSignUpCookie,
         userId,
         assumingUser,
+        requestHeaders,
     }: {
         userId: UserId | undefined;
         assumingUser: AssumedUserParams | undefined;
         isSignUpCookie: boolean;
+        requestHeaders: IncomingHttpHeaders;
     }): Promise<undefined | DatabaseUser> {
         if (!userId) {
             return undefined;
@@ -241,9 +278,21 @@ export class BackendAuthClient<
             assumingUser,
             userId,
             isSignUpCookie,
+            requestHeaders,
         });
 
         if (!authenticatedUser) {
+            this.logForUser(
+                {
+                    user: undefined,
+                    userId,
+                    assumedUserParams: assumingUser,
+                },
+                'getUserFromDatabase returned no user',
+                {
+                    isSignUpCookie,
+                },
+            );
             return undefined;
         }
 
@@ -269,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;
         }
 
@@ -286,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;
             }
         }
@@ -323,24 +397,36 @@ 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;
         }
     }
 
     /** Reads the user's assumed user headers and, if configured, gets the assumed user. */
     protected async getAssumedUser({
-        headers,
+        requestHeaders,
         user,
     }: {
         user: DatabaseUser;
-        headers: IncomingHttpHeaders;
+        requestHeaders: IncomingHttpHeaders;
     }): Promise<DatabaseUser | undefined> {
         if (!this.config.assumeUser || !(await this.config.assumeUser.canAssumeUser(user))) {
             return undefined;
         }
 
         const assumedUserHeader: string | undefined = ensureArray(
-            headers[this.config.assumedUserHeaderName || AuthHeaderName.AssumedUser],
+            requestHeaders[this.config.assumedUserHeaderName || AuthHeaderName.AssumedUser],
         )[0];
 
         if (!assumedUserHeader) {
@@ -358,6 +444,7 @@ export class BackendAuthClient<
             isSignUpCookie: false,
             userId: parsedAssumedUserData.userId,
             assumingUser: parsedAssumedUserData.assumedUserParams,
+            requestHeaders,
         });
 
         return assumedUser;
@@ -385,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;
         }
 
@@ -392,14 +490,26 @@ export class BackendAuthClient<
             userId: userIdResult.userId,
             assumingUser: undefined,
             isSignUpCookie,
+            requestHeaders,
         });
 
         if (!user) {
+            this.logForUser(
+                {
+                    user: undefined,
+                    userId: userIdResult.userId,
+                    assumedUserParams: undefined,
+                },
+                'getSecureUser: user not found in database',
+                {
+                    isSignUpCookie,
+                },
+            );
             return undefined;
         }
 
         const assumedUser = await this.getAssumedUser({
-            headers: requestHeaders,
+            requestHeaders,
             user,
         });
 
@@ -429,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,
@@ -578,13 +690,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,
+              }
+            : {};
     }
 
     /**
@@ -612,6 +730,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;
         }
 
@@ -619,9 +745,18 @@ export class BackendAuthClient<
             isSignUpCookie: false,
             userId: userIdResult.userId,
             assumingUser: undefined,
+            requestHeaders,
         });
 
         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

@@ -112,7 +112,9 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
                         });
                     }
                 },
-                debounce: config.checkUser.debounce || {minutes: 1},
+                debounce: config.checkUser.debounce || {
+                    minutes: 1,
+                },
                 fireImmediately: false,
             });
         }

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.ts

@@ -38,7 +38,9 @@ export type CsrfToken = typeof csrfTokenShape.runtimeType;
  * @category Internal
  * @default {minutes: 5}
  */
-export const defaultAllowedClockSkew: Readonly<AnyDuration> = {minutes: 5};
+export const defaultAllowedClockSkew: Readonly<AnyDuration> = {
+    minutes: 5,
+};
 
 /**
  * Generates a random, cryptographically secure CSRF token.

package/src/jwt/jwt.ts

@@ -16,8 +16,13 @@ import {EncryptJWT, jwtDecrypt, jwtVerify, SignJWT} from 'jose';
 import {defaultAllowedClockSkew} from '../csrf-token.js';
 import {type JwtKeys} from './jwt-keys.js';
 
-const encryptionProtectedHeader = {alg: 'dir', enc: 'A256GCM'};
-const signingProtectedHeader = {alg: 'HS512'};
+const encryptionProtectedHeader = {
+    alg: 'dir',
+    enc: 'A256GCM',
+};
+const signingProtectedHeader = {
+    alg: 'HS512',
+};
 
 /**
  * Params for {@link createJwt}.
@@ -110,7 +115,9 @@ export async function createJwt<JwtData extends AnyObject = AnyObject>(
     data: JwtData,
     params: Readonly<CreateJwtParams>,
 ): Promise<string> {
-    const rawJwt = new SignJWT({data})
+    const rawJwt = new SignJWT({
+        data,
+    })
         .setProtectedHeader(signingProtectedHeader)
         .setIssuedAt(
             params.issuedAt
@@ -129,7 +136,9 @@ export async function createJwt<JwtData extends AnyObject = AnyObject>(
 
     const signedJwt = await rawJwt.sign(params.jwtKeys.signingKey);
 
-    return await new EncryptJWT({jwt: signedJwt})
+    return await new EncryptJWT({
+        jwt: signedJwt,
+    })
         .setProtectedHeader(encryptionProtectedHeader)
         .encrypt(params.jwtKeys.encryptionKey);
 }
@@ -182,7 +191,9 @@ export async function parseJwt<JwtData extends AnyObject = AnyObject>(
 
     const clockToleranceSeconds = convertDuration(
         params.allowedClockSkew || defaultAllowedClockSkew,
-        {seconds: true},
+        {
+            seconds: true,
+        },
     ).seconds;
 
     const verifiedJwt = await jwtVerify(decryptedJwt.payload.jwt, params.jwtKeys.signingKey, {

package/src/jwt/user-jwt.ts

@@ -27,7 +27,9 @@ export const userJwtDataShape = defineShape({
      * enforce the max session duration. If not present, the session is considered to have started
      * when the JWT was issued.
      */
-    sessionStartedAt: optionalShape(0, {alsoUndefined: true}),
+    sessionStartedAt: optionalShape(0, {
+        alsoUndefined: true,
+    }),
 });
 
 /**

package/src/mock-local-storage.ts

@@ -59,7 +59,10 @@ export function createMockLocalStorage(
             delete store[key];
         },
         setItem(key, value) {
-            accessRecord.setItem.push({key, value});
+            accessRecord.setItem.push({
+                key,
+                value,
+            });
             store[key] = value;
         },
     };