auth-vir 2.3.8 → 2.4.0

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

@@ -119,14 +119,16 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
     protected cachedParsedJwtKeys: Record<string, Readonly<JwtKeys>>;
     constructor(config: BackendAuthClientConfig<DatabaseUser, UserId, AssumedUserParams, CsrfHeaderName>);
     /** Get all the parameters used for cookie generation. */
-    protected getCookieParams({ isSignUpCookie, }: {
+    protected getCookieParams({ isSignUpCookie, serviceOrigin, }: {
         /**
          * Set this to `true` when we are setting the initial cookie right after a user signs up.
          * This allows them to auto-authorize when they verify their email address.
          *
          * This should only be set to `true` when a new user is signing up.
          */
-        isSignUpCookie?: boolean | undefined;
+        isSignUpCookie: boolean;
+        /** Overrides the client's already established `serviceOrigin`. */
+        serviceOrigin: string | undefined;
     }): Promise<Readonly<CookieParams>>;
     /** Calls the provided `getUserFromDatabase` config. */
     protected getDatabaseUser({ isSignUpCookie, userId, assumingUser, }: {
@@ -144,9 +146,15 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
         headers: IncomingHttpHeaders;
     }): Promise<DatabaseUser | undefined>;
     /** Securely extract a user from their request headers. */
-    getSecureUser({ requestHeaders, isSignUpCookie, }: {
+    getSecureUser({ requestHeaders, isSignUpCookie, allowUserAuthRefresh, }: {
         requestHeaders: IncomingHttpHeaders;
-        isSignUpCookie?: boolean | undefined;
+        isSignUpCookie: boolean;
+        /**
+         * If true, this method will generate headers to refresh the user's auth session. This
+         * should likely only be done with a specific endpoint, like whatever endpoint you trigger
+         * with the frontend auth client's `checkUser.performCheck` callback.
+         */
+        allowUserAuthRefresh: boolean;
     }): Promise<GetUserResult<DatabaseUser> | undefined>;
     /**
      * Get all the JWT params used when creating the auth cookie, in case you need them for
@@ -157,19 +165,29 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
     createLogoutHeaders(params: RequireExactlyOne<{
         allCookies: true;
         isSignUpCookie: boolean;
+        /** Overrides the client's already established `serviceOrigin`. */
+        serviceOrigin?: string | undefined;
     }>): Promise<Partial<Record<CsrfHeaderName, string>> & {
         'set-cookie': string[];
     }>;
     /** Use these headers to log a user in. */
-    createLoginHeaders({ userId, requestHeaders, isSignUpCookie, }: {
+    createLoginHeaders({ userId, requestHeaders, isSignUpCookie, serviceOrigin, }: {
         userId: UserId;
         requestHeaders: IncomingHttpHeaders;
         isSignUpCookie: boolean;
+        /** Overrides the client's already established `serviceOrigin`. */
+        serviceOrigin?: string | undefined;
     }): Promise<OutgoingHttpHeaders>;
     /** Combines `.getInsecureUser()` and `.getSecureUser()` into one method. */
     getInsecureOrSecureUser(params: {
         requestHeaders: IncomingHttpHeaders;
-        isSignUpCookie?: boolean | undefined;
+        isSignUpCookie: boolean;
+        /**
+         * If true, this method will generate headers to refresh the user's auth session. This
+         * should likely only be done with a specific endpoint, like whatever endpoint you trigger
+         * with the frontend auth client's `checkUser.performCheck` callback.
+         */
+        allowUserAuthRefresh: boolean;
     }): Promise<RequireOneOrNone<{
         secureUser: GetUserResult<DatabaseUser>;
         /**
@@ -185,7 +203,13 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
      *   where JavaScript cannot be used to attach the CSRF token header to the request (like when
      *   opening a PDF file). Use `.getSecureUser()` instead, whenever possible.
      */
-    getInsecureUser({ requestHeaders, }: {
+    getInsecureUser({ requestHeaders, allowUserAuthRefresh, }: {
         requestHeaders: IncomingHttpHeaders;
+        /**
+         * If true, this method will generate headers to refresh the user's auth session. This
+         * should likely only be done with a specific endpoint, like whatever endpoint you trigger
+         * with the frontend auth client's `checkUser.performCheck` callback.
+         */
+        allowUserAuthRefresh: boolean;
     }): Promise<GetUserResult<DatabaseUser> | undefined>;
 }

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

@@ -24,10 +24,10 @@ export class BackendAuthClient {
         this.config = config;
     }
     /** Get all the parameters used for cookie generation. */
-    async getCookieParams({ isSignUpCookie, }) {
+    async getCookieParams({ isSignUpCookie, serviceOrigin, }) {
         return {
             cookieDuration: this.config.userSessionIdleTimeout || defaultSessionIdleTimeout,
-            hostOrigin: this.config.serviceOrigin,
+            hostOrigin: serviceOrigin || this.config.serviceOrigin,
             jwtParams: await this.getJwtParams(),
             isDev: this.config.isDev,
             cookieName: isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth,
@@ -110,7 +110,7 @@ export class BackendAuthClient {
         return assumedUser;
     }
     /** Securely extract a user from their request headers. */
-    async getSecureUser({ requestHeaders, isSignUpCookie, }) {
+    async getSecureUser({ requestHeaders, isSignUpCookie, allowUserAuthRefresh, }) {
         const userIdResult = await extractUserIdFromRequestHeaders(requestHeaders, await this.getJwtParams(), isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth, this.config.overrides);
         if (!userIdResult) {
             return undefined;
@@ -118,7 +118,7 @@ export class BackendAuthClient {
         const user = await this.getDatabaseUser({
             userId: userIdResult.userId,
             assumingUser: undefined,
-            isSignUpCookie: !!isSignUpCookie,
+            isSignUpCookie,
         });
         if (!user) {
             return undefined;
@@ -133,7 +133,7 @@ export class BackendAuthClient {
         return {
             user: assumedUser || user,
             isAssumed: !!assumedUser,
-            responseHeaders: cookieRefreshHeaders,
+            responseHeaders: allowUserAuthRefresh ? cookieRefreshHeaders : {},
         };
     }
     /**
@@ -160,11 +160,13 @@ export class BackendAuthClient {
         const signUpCookieHeaders = params.allCookies || params.isSignUpCookie
             ? generateLogoutHeaders(await this.getCookieParams({
                 isSignUpCookie: true,
+                serviceOrigin: params.serviceOrigin,
             }), this.config.overrides)
             : undefined;
         const authCookieHeaders = params.allCookies || !params.isSignUpCookie
             ? generateLogoutHeaders(await this.getCookieParams({
                 isSignUpCookie: false,
+                serviceOrigin: params.serviceOrigin,
             }), this.config.overrides)
             : undefined;
         const setCookieHeader = {
@@ -180,16 +182,18 @@ export class BackendAuthClient {
         };
     }
     /** Use these headers to log a user in. */
-    async createLoginHeaders({ userId, requestHeaders, isSignUpCookie, }) {
+    async createLoginHeaders({ userId, requestHeaders, isSignUpCookie, serviceOrigin, }) {
         const oppositeCookieName = isSignUpCookie ? AuthCookieName.Auth : AuthCookieName.SignUp;
         const hasExistingOppositeCookie = requestHeaders.cookie?.includes(`${oppositeCookieName}=`);
         const discardOppositeCookieHeaders = hasExistingOppositeCookie
             ? generateLogoutHeaders(await this.getCookieParams({
                 isSignUpCookie: !isSignUpCookie,
+                serviceOrigin,
             }), this.config.overrides)
             : undefined;
         const newCookieHeaders = await generateSuccessfulLoginHeaders(userId, await this.getCookieParams({
             isSignUpCookie,
+            serviceOrigin,
         }), this.config.overrides);
         return {
             ...newCookieHeaders,
@@ -216,7 +220,7 @@ export class BackendAuthClient {
      *   where JavaScript cannot be used to attach the CSRF token header to the request (like when
      *   opening a PDF file). Use `.getSecureUser()` instead, whenever possible.
      */
-    async getInsecureUser({ requestHeaders, }) {
+    async getInsecureUser({ requestHeaders, allowUserAuthRefresh, }) {
         // eslint-disable-next-line @typescript-eslint/no-deprecated
         const userIdResult = await insecureExtractUserIdFromCookieAlone(requestHeaders, await this.getJwtParams(), AuthCookieName.Auth);
         if (!userIdResult) {
@@ -230,12 +234,14 @@ export class BackendAuthClient {
         if (!user) {
             return undefined;
         }
+        const refreshHeaders = allowUserAuthRefresh &&
+            (await this.createCookieRefreshHeaders({
+                userIdResult,
+            }));
         return {
             user,
             isAssumed: false,
-            responseHeaders: (await this.createCookieRefreshHeaders({
-                userIdResult,
-            })) || {},
+            responseHeaders: refreshHeaders || {},
         };
     }
 }

package/package.json

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

@@ -168,6 +168,7 @@ export class BackendAuthClient<
     /** Get all the parameters used for cookie generation. */
     protected async getCookieParams({
         isSignUpCookie,
+        serviceOrigin,
     }: {
         /**
          * Set this to `true` when we are setting the initial cookie right after a user signs up.
@@ -175,11 +176,13 @@ export class BackendAuthClient<
          *
          * This should only be set to `true` when a new user is signing up.
          */
-        isSignUpCookie?: boolean | undefined;
+        isSignUpCookie: boolean;
+        /** Overrides the client's already established `serviceOrigin`. */
+        serviceOrigin: string | undefined;
     }): Promise<Readonly<CookieParams>> {
         return {
             cookieDuration: this.config.userSessionIdleTimeout || defaultSessionIdleTimeout,
-            hostOrigin: this.config.serviceOrigin,
+            hostOrigin: serviceOrigin || this.config.serviceOrigin,
             jwtParams: await this.getJwtParams(),
             isDev: this.config.isDev,
             cookieName: isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth,
@@ -305,9 +308,16 @@ export class BackendAuthClient<
     public async getSecureUser({
         requestHeaders,
         isSignUpCookie,
+        allowUserAuthRefresh,
     }: {
         requestHeaders: IncomingHttpHeaders;
-        isSignUpCookie?: boolean | undefined;
+        isSignUpCookie: boolean;
+        /**
+         * If true, this method will generate headers to refresh the user's auth session. This
+         * should likely only be done with a specific endpoint, like whatever endpoint you trigger
+         * with the frontend auth client's `checkUser.performCheck` callback.
+         */
+        allowUserAuthRefresh: boolean;
     }): Promise<GetUserResult<DatabaseUser> | undefined> {
         const userIdResult = await extractUserIdFromRequestHeaders<UserId>(
             requestHeaders,
@@ -322,7 +332,7 @@ export class BackendAuthClient<
         const user = await this.getDatabaseUser({
             userId: userIdResult.userId,
             assumingUser: undefined,
-            isSignUpCookie: !!isSignUpCookie,
+            isSignUpCookie,
         });
 
         if (!user) {
@@ -342,7 +352,7 @@ export class BackendAuthClient<
         return {
             user: assumedUser || user,
             isAssumed: !!assumedUser,
-            responseHeaders: cookieRefreshHeaders,
+            responseHeaders: allowUserAuthRefresh ? cookieRefreshHeaders : {},
         };
     }
 
@@ -374,6 +384,8 @@ export class BackendAuthClient<
         params: RequireExactlyOne<{
             allCookies: true;
             isSignUpCookie: boolean;
+            /** Overrides the client's already established `serviceOrigin`. */
+            serviceOrigin?: string | undefined;
         }>,
     ): Promise<
         Partial<Record<CsrfHeaderName, string>> & {
@@ -385,6 +397,7 @@ export class BackendAuthClient<
                 ? (generateLogoutHeaders(
                       await this.getCookieParams({
                           isSignUpCookie: true,
+                          serviceOrigin: params.serviceOrigin,
                       }),
                       this.config.overrides,
                   ) satisfies Record<CsrfHeaderName, string>)
@@ -394,6 +407,7 @@ export class BackendAuthClient<
                 ? (generateLogoutHeaders(
                       await this.getCookieParams({
                           isSignUpCookie: false,
+                          serviceOrigin: params.serviceOrigin,
                       }),
                       this.config.overrides,
                   ) satisfies Record<CsrfHeaderName, string>)
@@ -423,10 +437,13 @@ export class BackendAuthClient<
         userId,
         requestHeaders,
         isSignUpCookie,
+        serviceOrigin,
     }: {
         userId: UserId;
         requestHeaders: IncomingHttpHeaders;
         isSignUpCookie: boolean;
+        /** Overrides the client's already established `serviceOrigin`. */
+        serviceOrigin?: string | undefined;
     }): Promise<OutgoingHttpHeaders> {
         const oppositeCookieName = isSignUpCookie ? AuthCookieName.Auth : AuthCookieName.SignUp;
         const hasExistingOppositeCookie = requestHeaders.cookie?.includes(`${oppositeCookieName}=`);
@@ -435,6 +452,7 @@ export class BackendAuthClient<
             ? generateLogoutHeaders(
                   await this.getCookieParams({
                       isSignUpCookie: !isSignUpCookie,
+                      serviceOrigin,
                   }),
                   this.config.overrides,
               )
@@ -444,6 +462,7 @@ export class BackendAuthClient<
             userId,
             await this.getCookieParams({
                 isSignUpCookie,
+                serviceOrigin,
             }),
             this.config.overrides,
         );
@@ -465,7 +484,13 @@ export class BackendAuthClient<
     /** Combines `.getInsecureUser()` and `.getSecureUser()` into one method. */
     public async getInsecureOrSecureUser(params: {
         requestHeaders: IncomingHttpHeaders;
-        isSignUpCookie?: boolean | undefined;
+        isSignUpCookie: boolean;
+        /**
+         * If true, this method will generate headers to refresh the user's auth session. This
+         * should likely only be done with a specific endpoint, like whatever endpoint you trigger
+         * with the frontend auth client's `checkUser.performCheck` callback.
+         */
+        allowUserAuthRefresh: boolean;
     }): Promise<
         RequireOneOrNone<{
             secureUser: GetUserResult<DatabaseUser>;
@@ -497,8 +522,15 @@ export class BackendAuthClient<
      */
     public async getInsecureUser({
         requestHeaders,
+        allowUserAuthRefresh,
     }: {
         requestHeaders: IncomingHttpHeaders;
+        /**
+         * If true, this method will generate headers to refresh the user's auth session. This
+         * should likely only be done with a specific endpoint, like whatever endpoint you trigger
+         * with the frontend auth client's `checkUser.performCheck` callback.
+         */
+        allowUserAuthRefresh: boolean;
     }): Promise<GetUserResult<DatabaseUser> | undefined> {
         // eslint-disable-next-line @typescript-eslint/no-deprecated
         const userIdResult = await insecureExtractUserIdFromCookieAlone<UserId>(
@@ -521,13 +553,16 @@ export class BackendAuthClient<
             return undefined;
         }
 
+        const refreshHeaders =
+            allowUserAuthRefresh &&
+            (await this.createCookieRefreshHeaders({
+                userIdResult,
+            }));
+
         return {
             user,
             isAssumed: false,
-            responseHeaders:
-                (await this.createCookieRefreshHeaders({
-                    userIdResult,
-                })) || {},
+            responseHeaders: refreshHeaders || {},
         };
     }
 }