auth-vir 2.0.3 → 2.1.0

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

@@ -1,4 +1,5 @@
-import { type JsonCompatibleObject, type MaybePromise, type PartialWithUndefined, type SelectFrom } from '@augment-vir/common';
+import { type JsonCompatibleObject, type MaybePromise, type PartialWithUndefined, type SelectFrom, type SetOptionalWithUndefined } from '@augment-vir/common';
+import { type AnyDuration } from 'date-vir';
 import { type EmptyObject } from 'type-fest';
 /**
  * Config for {@link FrontendAuthClient}.
@@ -13,6 +14,22 @@ export type FrontendAuthClientConfig = PartialWithUndefined<{
     canAssumeUser: () => MaybePromise<boolean>;
     /** Called whenever the current user becomes unauthorized and their CSRF token is wiped. */
     authClearedCallback: () => MaybePromise<void>;
+    /**
+     * Performs automatic checks on an interval to see if the user is still authenticated. Omit this
+     * to turn off automatic checks.
+     */
+    checkUser: {
+        /**
+         * Get a response from the backend to see if the user is still authenticated. If the
+         * response returns a non-authorized status, the user is wiped. Any other status is
+         * ignored.
+         */
+        performCheck: () => MaybePromise<SelectFrom<Response, {
+            status: true;
+        }>>;
+        /** @default {minutes: 1} */
+        interval?: AnyDuration | undefined;
+    };
     overrides: PartialWithUndefined<{
         localStorage: Pick<Storage, 'setItem' | 'removeItem' | 'getItem'>;
         csrfHeaderName: string;
@@ -28,11 +45,21 @@ export type FrontendAuthClientConfig = PartialWithUndefined<{
  */
 export declare class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject = EmptyObject> {
     protected readonly config: FrontendAuthClientConfig;
+    protected userCheckInterval: undefined | ReturnType<typeof globalThis.setInterval>;
     constructor(config?: FrontendAuthClientConfig);
+    /**
+     * Destroys the client and performs all necessary cleanup (like clearing the user check
+     * interval).
+     */
+    destroy(): void;
     /** Wraps {@link getCurrentCsrfToken} to automatically handle wiping an invalid CSRF token. */
     getCurrentCsrfToken(): Promise<string | undefined>;
-    /** @returns Whether the user assuming succeeded or not. */
-    assumeUser(assumedUserParams: Readonly<AssumedUserParams>): Promise<boolean>;
+    /**
+     * Assume the given user. Pass `undefined` to wipe the currently assumed user.
+     *
+     * @returns Whether the assumed user setting or clearing succeeded or not.
+     */
+    assumeUser(assumedUserParams: Readonly<AssumedUserParams> | undefined): Promise<boolean>;
     /** Gets the assumed user params stored in local storage, if any. */
     getAssumedUser(): AssumedUserParams | undefined;
     /**
@@ -58,8 +85,8 @@ export declare class FrontendAuthClient<AssumedUserParams extends JsonCompatible
      * Use to verify _all_ responses received from the backend. Immediately logs the user out once
      * an unauthorized response is detected.
      */
-    verifyResponseAuth(response: Readonly<SelectFrom<Response, {
+    verifyResponseAuth(response: Readonly<SetOptionalWithUndefined<SelectFrom<Response, {
         status: true;
         headers: true;
-    }>>): Promise<void>;
+    }>, 'headers'>>): Promise<void>;
 }

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

@@ -1,4 +1,5 @@
 import { HttpStatus, } from '@augment-vir/common';
+import { convertDuration } from 'date-vir';
 import { CsrfTokenFailureReason, extractCsrfTokenHeader, getCurrentCsrfToken, storeCsrfToken, wipeCurrentCsrfToken, } from '../csrf-token.js';
 import { AuthHeaderName } from '../headers.js';
 /**
@@ -10,8 +11,29 @@ import { AuthHeaderName } from '../headers.js';
  */
 export class FrontendAuthClient {
     config;
+    userCheckInterval;
     constructor(config = {}) {
         this.config = config;
+        if (config.checkUser) {
+            const intervalDuration = convertDuration(config.checkUser.interval || { minutes: 1 }, {
+                milliseconds: true,
+            }).milliseconds;
+            this.userCheckInterval = globalThis.setInterval(async () => {
+                const response = await config.checkUser?.performCheck();
+                if (response) {
+                    await this.verifyResponseAuth({
+                        status: response.status,
+                    });
+                }
+            }, intervalDuration);
+        }
+    }
+    /**
+     * Destroys the client and performs all necessary cleanup (like clearing the user check
+     * interval).
+     */
+    destroy() {
+        globalThis.clearInterval(this.userCheckInterval);
     }
     /** Wraps {@link getCurrentCsrfToken} to automatically handle wiping an invalid CSRF token. */
     async getCurrentCsrfToken() {
@@ -25,12 +47,22 @@ export class FrontendAuthClient {
             return csrfTokenResult.csrfToken?.token;
         }
     }
-    /** @returns Whether the user assuming succeeded or not. */
+    /**
+     * Assume the given user. Pass `undefined` to wipe the currently assumed user.
+     *
+     * @returns Whether the assumed user setting or clearing succeeded or not.
+     */
     async assumeUser(assumedUserParams) {
+        const localStorage = this.config.overrides?.localStorage || globalThis.localStorage;
+        const storageKey = this.config.overrides?.assumedUserHeaderName || AuthHeaderName.AssumedUser;
+        if (!assumedUserParams) {
+            localStorage.removeItem(storageKey);
+            return true;
+        }
         if (!(await this.config.canAssumeUser?.())) {
             return false;
         }
-        (this.config.overrides?.localStorage || globalThis.localStorage).setItem(this.config.overrides?.assumedUserHeaderName || AuthHeaderName.AssumedUser, JSON.stringify(assumedUserParams));
+        localStorage.setItem(storageKey, JSON.stringify(assumedUserParams));
         return true;
     }
     /** Gets the assumed user params stored in local storage, if any. */
@@ -101,7 +133,7 @@ export class FrontendAuthClient {
      */
     async verifyResponseAuth(response) {
         if (response.status === HttpStatus.Unauthorized &&
-            !response.headers.get(AuthHeaderName.IsSignUpAuth)) {
+            !response.headers?.get(AuthHeaderName.IsSignUpAuth)) {
             await this.logout();
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auth-vir",
-    "version": "2.0.3",
+    "version": "2.1.0",
     "description": "Auth made easy and secure via JWT cookies, CSRF tokens, and password hashing helpers.",
     "keywords": [
         "auth",

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

@@ -4,7 +4,9 @@ import {
     type MaybePromise,
     type PartialWithUndefined,
     type SelectFrom,
+    type SetOptionalWithUndefined,
 } from '@augment-vir/common';
+import {convertDuration, type AnyDuration} from 'date-vir';
 import {type EmptyObject} from 'type-fest';
 import {
     CsrfTokenFailureReason,
@@ -28,6 +30,29 @@ export type FrontendAuthClientConfig = PartialWithUndefined<{
     canAssumeUser: () => MaybePromise<boolean>;
     /** Called whenever the current user becomes unauthorized and their CSRF token is wiped. */
     authClearedCallback: () => MaybePromise<void>;
+
+    /**
+     * Performs automatic checks on an interval to see if the user is still authenticated. Omit this
+     * to turn off automatic checks.
+     */
+    checkUser: {
+        /**
+         * Get a response from the backend to see if the user is still authenticated. If the
+         * response returns a non-authorized status, the user is wiped. Any other status is
+         * ignored.
+         */
+        performCheck: () => MaybePromise<
+            SelectFrom<
+                Response,
+                {
+                    status: true;
+                }
+            >
+        >;
+        /** @default {minutes: 1} */
+        interval?: AnyDuration | undefined;
+    };
+
     overrides: PartialWithUndefined<{
         localStorage: Pick<Storage, 'setItem' | 'removeItem' | 'getItem'>;
         csrfHeaderName: string;
@@ -43,7 +68,32 @@ export type FrontendAuthClientConfig = PartialWithUndefined<{
  * @category Client
  */
 export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject = EmptyObject> {
-    constructor(protected readonly config: FrontendAuthClientConfig = {}) {}
+    protected userCheckInterval: undefined | ReturnType<typeof globalThis.setInterval>;
+
+    constructor(protected readonly config: FrontendAuthClientConfig = {}) {
+        if (config.checkUser) {
+            const intervalDuration = convertDuration(config.checkUser.interval || {minutes: 1}, {
+                milliseconds: true,
+            }).milliseconds;
+
+            this.userCheckInterval = globalThis.setInterval(async () => {
+                const response = await config.checkUser?.performCheck();
+                if (response) {
+                    await this.verifyResponseAuth({
+                        status: response.status,
+                    });
+                }
+            }, intervalDuration);
+        }
+    }
+
+    /**
+     * Destroys the client and performs all necessary cleanup (like clearing the user check
+     * interval).
+     */
+    public destroy() {
+        globalThis.clearInterval(this.userCheckInterval);
+    }
 
     /** Wraps {@link getCurrentCsrfToken} to automatically handle wiping an invalid CSRF token. */
     public async getCurrentCsrfToken(): Promise<string | undefined> {
@@ -60,16 +110,28 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
         }
     }
 
-    /** @returns Whether the user assuming succeeded or not. */
-    public async assumeUser(assumedUserParams: Readonly<AssumedUserParams>): Promise<boolean> {
+    /**
+     * Assume the given user. Pass `undefined` to wipe the currently assumed user.
+     *
+     * @returns Whether the assumed user setting or clearing succeeded or not.
+     */
+    public async assumeUser(
+        assumedUserParams: Readonly<AssumedUserParams> | undefined,
+    ): Promise<boolean> {
+        const localStorage = this.config.overrides?.localStorage || globalThis.localStorage;
+        const storageKey =
+            this.config.overrides?.assumedUserHeaderName || AuthHeaderName.AssumedUser;
+
+        if (!assumedUserParams) {
+            localStorage.removeItem(storageKey);
+            return true;
+        }
+
         if (!(await this.config.canAssumeUser?.())) {
             return false;
         }
 
-        (this.config.overrides?.localStorage || globalThis.localStorage).setItem(
-            this.config.overrides?.assumedUserHeaderName || AuthHeaderName.AssumedUser,
-            JSON.stringify(assumedUserParams),
-        );
+        localStorage.setItem(storageKey, JSON.stringify(assumedUserParams));
 
         return true;
     }
@@ -164,18 +226,21 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
      */
     public async verifyResponseAuth(
         response: Readonly<
-            SelectFrom<
-                Response,
-                {
-                    status: true;
-                    headers: true;
-                }
+            SetOptionalWithUndefined<
+                SelectFrom<
+                    Response,
+                    {
+                        status: true;
+                        headers: true;
+                    }
+                >,
+                'headers'
             >
         >,
     ): Promise<void> {
         if (
             response.status === HttpStatus.Unauthorized &&
-            !response.headers.get(AuthHeaderName.IsSignUpAuth)
+            !response.headers?.get(AuthHeaderName.IsSignUpAuth)
         ) {
             await this.logout();
         }