auth-vir 2.7.2 → 3.0.1

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

@@ -10,7 +10,6 @@ import {
     createUtcFullDate,
     getNowInUtcTimezone,
     isDateAfter,
-    negateDuration,
     type AnyDuration,
 } from 'date-vir';
 import {type IncomingHttpHeaders, type OutgoingHttpHeaders} from 'node:http';
@@ -22,11 +21,16 @@ import {
     insecureExtractUserIdFromCookieAlone,
     type UserIdResult,
 } from '../auth.js';
-import {AuthCookieName, type CookieParams} from '../cookie.js';
+import {AuthCookieName, generateAuthCookie, type CookieParams} from '../cookie.js';
+import {
+    defaultAllowedClockSkew,
+    resolveCsrfHeaderName,
+    type CsrfHeaderNameOption,
+} from '../csrf-token.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';
+import {type CreateJwtParams, type ParseJwtParams} from '../jwt/jwt.js';
+import {isSessionRefreshReady} from './is-session-refresh-ready.js';
 
 /**
  * Output from `BackendAuthClient.getSecureUser()`.
@@ -57,9 +61,9 @@ export type BackendAuthClientConfig<
     DatabaseUser extends AnyObject,
     UserId extends string | number,
     AssumedUserParams extends JsonCompatibleObject = EmptyObject,
-    CsrfHeaderName extends string = AuthHeaderName.CsrfToken,
 > = Readonly<
     {
+        csrf: Readonly<CsrfHeaderNameOption>;
         /** The origin of your backend that is offering auth cookies. */
         serviceOrigin: string;
         /** Finds the relevant user from your own database. */
@@ -73,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
@@ -86,6 +91,11 @@ export type BackendAuthClientConfig<
          */
         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.
@@ -139,18 +149,21 @@ export type BackendAuthClientConfig<
          *
          * @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>;
     }>
 >;
 
@@ -158,12 +171,12 @@ const defaultSessionIdleTimeout: Readonly<AnyDuration> = {
     minutes: 20,
 };
 
-const defaultSessionRefreshTimeout: Readonly<AnyDuration> = {
+const defaultSessionRefreshStartTime: Readonly<AnyDuration> = {
     minutes: 2,
 };
 
 const defaultMaxSessionDuration: Readonly<AnyDuration> = {
-    weeks: 2,
+    days: 1.5,
 };
 
 /**
@@ -171,23 +184,17 @@ const defaultMaxSessionDuration: Readonly<AnyDuration> = {
  * a backend environment as it accesses native Node packages.
  *
  * @category Auth : Host
- * @category Client
+ * @category Clients
  */
 export class BackendAuthClient<
     DatabaseUser extends AnyObject,
     UserId extends string | number,
     AssumedUserParams extends AnyObject = EmptyObject,
-    CsrfHeaderName extends string = AuthHeaderName.CsrfToken,
 > {
     protected cachedParsedJwtKeys: Record<string, Readonly<JwtKeys>> = {};
 
     constructor(
-        protected readonly config: BackendAuthClientConfig<
-            DatabaseUser,
-            UserId,
-            AssumedUserParams,
-            CsrfHeaderName
-        >,
+        protected readonly config: BackendAuthClientConfig<DatabaseUser, UserId, AssumedUserParams>,
     ) {}
 
     /** Get all the parameters used for cookie generation. */
@@ -222,10 +229,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;
@@ -235,6 +244,7 @@ export class BackendAuthClient<
             assumingUser,
             userId,
             isSignUpCookie,
+            requestHeaders,
         });
 
         if (!authenticatedUser) {
@@ -254,17 +264,15 @@ export class BackendAuthClient<
     }): Promise<OutgoingHttpHeaders | undefined> {
         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;
         }
 
@@ -282,49 +290,42 @@ 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;
             }
         }
 
-        /**
-         * 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;
         }
@@ -332,18 +333,18 @@ export class BackendAuthClient<
 
     /** 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.overrides?.assumedUserHeaderName || AuthHeaderName.AssumedUser],
+            requestHeaders[this.config.assumedUserHeaderName || AuthHeaderName.AssumedUser],
         )[0];
 
         if (!assumedUserHeader) {
@@ -361,6 +362,7 @@ export class BackendAuthClient<
             isSignUpCookie: false,
             userId: parsedAssumedUserData.userId,
             assumingUser: parsedAssumedUserData.assumedUserParams,
+            requestHeaders,
         });
 
         return assumedUser;
@@ -384,13 +386,10 @@ export class BackendAuthClient<
         const userIdResult = await extractUserIdFromRequestHeaders<UserId>(
             requestHeaders,
             await this.getJwtParams(),
+            this.config.csrf,
             isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth,
-            this.config.overrides,
         );
         if (!userIdResult) {
-            if (!isSignUpCookie) {
-                authLog('auth-vir: getSecureUser failed - could not extract user from request');
-            }
             return undefined;
         }
 
@@ -398,17 +397,15 @@ export class BackendAuthClient<
             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,
         });
 
@@ -429,13 +426,13 @@ export class BackendAuthClient<
      * Get all the JWT params used when creating the auth cookie, in case you need them for
      * something else too.
      */
-    public async getJwtParams(): Promise<Readonly<CreateJwtParams>> {
+    public async getJwtParams(): Promise<Readonly<CreateJwtParams> & ParseJwtParams> {
         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};
@@ -445,6 +442,7 @@ export class BackendAuthClient<
             audience: 'server-context',
             issuer: 'server-auth',
             jwtDuration: this.config.userSessionIdleTimeout || defaultSessionIdleTimeout,
+            allowedClockSkew: this.config.allowedClockSkew || defaultAllowedClockSkew,
         };
     }
 
@@ -460,37 +458,29 @@ export class BackendAuthClient<
             }
         >,
     ): Promise<
-        Partial<Record<CsrfHeaderName, string>> & {
+        Record<string, string | string[]> & {
             '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(
+                ? generateLogoutHeaders(
                       await this.getCookieParams({
                           isSignUpCookie: true,
                           requestHeaders: undefined,
                       }),
-                      this.config.overrides,
-                  ) satisfies Record<CsrfHeaderName, string>)
+                      this.config.csrf,
+                  )
                 : undefined;
         const authCookieHeaders =
             params.allCookies || !params.isSignUpCookie
-                ? (generateLogoutHeaders(
+                ? generateLogoutHeaders(
                       await this.getCookieParams({
                           isSignUpCookie: false,
                           requestHeaders: undefined,
                       }),
-                      this.config.overrides,
-                  ) satisfies Record<CsrfHeaderName, string>)
+                      this.config.csrf,
+                  )
                 : undefined;
 
         const setCookieHeader: {
@@ -504,7 +494,7 @@ export class BackendAuthClient<
         const csrfTokenHeader = {
             ...authCookieHeaders,
             ...signUpCookieHeaders,
-        } as Record<CsrfHeaderName, string>;
+        };
 
         return {
             ...csrfTokenHeader,
@@ -531,15 +521,15 @@ export class BackendAuthClient<
                       isSignUpCookie: !isSignUpCookie,
                       requestHeaders,
                   }),
-                  this.config.overrides,
+                  this.config.csrf,
               )
             : undefined;
 
         const existingUserIdResult = await extractUserIdFromRequestHeaders<UserId>(
             requestHeaders,
             await this.getJwtParams(),
+            this.config.csrf,
             isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth,
-            this.config.overrides,
         );
         const sessionStartedAt = existingUserIdResult?.sessionStartedAt;
 
@@ -549,7 +539,7 @@ export class BackendAuthClient<
                 isSignUpCookie,
                 requestHeaders,
             }),
-            this.config.overrides,
+            this.config.csrf,
             sessionStartedAt,
         );
 
@@ -628,7 +618,6 @@ export class BackendAuthClient<
         );
 
         if (!userIdResult) {
-            authLog('auth-vir: getInsecureUser failed - could not extract user from request');
             return undefined;
         }
 
@@ -636,12 +625,10 @@ export class BackendAuthClient<
             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;
         }