auth-vir 2.1.0 → 2.3.0

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

@@ -1,7 +1,7 @@
 import { type AnyObject, type JsonCompatibleObject, type MaybePromise, type PartialWithUndefined, type RequiredAndNotNull } from '@augment-vir/common';
 import { type AnyDuration } from 'date-vir';
 import { type IncomingHttpHeaders, type OutgoingHttpHeaders } from 'node:http';
-import { type EmptyObject } from 'type-fest';
+import { type EmptyObject, type RequireExactlyOne, type RequireOneOrNone } from 'type-fest';
 import { type UserIdResult } from '../auth.js';
 import { type CookieParams } from '../cookie.js';
 import { AuthHeaderName } from '../headers.js';
@@ -154,21 +154,38 @@ export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId ex
      */
     getJwtParams(): Promise<Readonly<CreateJwtParams>>;
     /** Use these headers to log out the user. */
-    createLogoutHeaders(): Promise<{
-        'set-cookie': string;
-    } & Record<CsrfHeaderName, string>>;
+    createLogoutHeaders(params: RequireExactlyOne<{
+        allCookies: true;
+        isSignUpCookie: boolean;
+    }>): Promise<Partial<Record<CsrfHeaderName, string>> & {
+        'set-cookie': string[];
+    }>;
     /** Use these headers to log a user in. */
     createLoginHeaders({ userId, requestHeaders, isSignUpCookie, }: {
         userId: UserId;
         requestHeaders: IncomingHttpHeaders;
         isSignUpCookie: boolean;
     }): Promise<Pick<RequiredAndNotNull<OutgoingHttpHeaders>, 'set-cookie'> & Record<CsrfHeaderName, string>>;
+    /** Combines `.getInsecureUser()` and `.getSecureUser()` into one method. */
+    getInsecureOrSecureUser(params: {
+        requestHeaders: IncomingHttpHeaders;
+        isSignUpCookie?: boolean | undefined;
+    }): Promise<RequireOneOrNone<{
+        secureUser: GetUserResult<DatabaseUser>;
+        /**
+         * @deprecated This only half authenticates the user. It should only be used in
+         *   circumstances 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.
+         */
+        insecureUser: GetUserResult<DatabaseUser>;
+    }>>;
     /**
      * @deprecated This only half authenticates the user. It should only be used in circumstances
      *   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({ headers, }: {
-        headers: IncomingHttpHeaders;
+    getInsecureUser({ requestHeaders, }: {
+        requestHeaders: IncomingHttpHeaders;
     }): Promise<GetUserResult<DatabaseUser> | undefined>;
 }

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

@@ -155,16 +155,27 @@ export class BackendAuthClient {
         };
     }
     /** Use these headers to log out the user. */
-    async createLogoutHeaders() {
-        const signUpCookieHeaders = generateLogoutHeaders(await this.getCookieParams({
-            isSignUpCookie: true,
-        }), this.config.overrides);
-        const authCookieHeaders = generateLogoutHeaders(await this.getCookieParams({
-            isSignUpCookie: false,
-        }), this.config.overrides);
-        return {
+    async createLogoutHeaders(params) {
+        const signUpCookieHeaders = params.allCookies || params.isSignUpCookie
+            ? generateLogoutHeaders(await this.getCookieParams({
+                isSignUpCookie: true,
+            }), this.config.overrides)
+            : undefined;
+        const authCookieHeaders = params.allCookies || !params.isSignUpCookie
+            ? generateLogoutHeaders(await this.getCookieParams({
+                isSignUpCookie: false,
+            }), this.config.overrides)
+            : undefined;
+        const setCookieHeader = {
+            'set-cookie': mergeHeaderValues(signUpCookieHeaders?.['set-cookie'], authCookieHeaders?.['set-cookie']),
+        };
+        const csrfTokenHeader = {
             ...authCookieHeaders,
-            'set-cookie': mergeHeaderValues(signUpCookieHeaders['set-cookie'], authCookieHeaders['set-cookie']),
+            ...signUpCookieHeaders,
+        };
+        return {
+            ...csrfTokenHeader,
+            ...setCookieHeader,
         };
     }
     /** Use these headers to log a user in. */
@@ -189,14 +200,24 @@ export class BackendAuthClient {
                 : {}),
         };
     }
+    /** Combines `.getInsecureUser()` and `.getSecureUser()` into one method. */
+    async getInsecureOrSecureUser(params) {
+        const secureUser = await this.getSecureUser(params);
+        if (secureUser) {
+            return secureUser;
+        }
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        const insecureUser = await this.getInsecureUser(params);
+        return insecureUser ? { insecureUser } : {};
+    }
     /**
      * @deprecated This only half authenticates the user. It should only be used in circumstances
      *   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({ headers, }) {
+    async getInsecureUser({ requestHeaders, }) {
         // eslint-disable-next-line @typescript-eslint/no-deprecated
-        const userIdResult = await insecureExtractUserIdFromCookieAlone(headers, await this.getJwtParams(), AuthCookieName.Auth);
+        const userIdResult = await insecureExtractUserIdFromCookieAlone(requestHeaders, await this.getJwtParams(), AuthCookieName.Auth);
         if (!userIdResult) {
             return undefined;
         }

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

@@ -1,4 +1,4 @@
-import { type JsonCompatibleObject, type MaybePromise, type PartialWithUndefined, type SelectFrom, type SetOptionalWithUndefined } from '@augment-vir/common';
+import { createBlockingInterval, 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';
 /**
@@ -45,7 +45,7 @@ export type FrontendAuthClientConfig = PartialWithUndefined<{
  */
 export declare class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject = EmptyObject> {
     protected readonly config: FrontendAuthClientConfig;
-    protected userCheckInterval: undefined | ReturnType<typeof globalThis.setInterval>;
+    protected userCheckInterval: undefined | ReturnType<typeof createBlockingInterval>;
     constructor(config?: FrontendAuthClientConfig);
     /**
      * Destroys the client and performs all necessary cleanup (like clearing the user check

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

@@ -1,5 +1,4 @@
-import { HttpStatus, } from '@augment-vir/common';
-import { convertDuration } from 'date-vir';
+import { createBlockingInterval, HttpStatus, } from '@augment-vir/common';
 import { CsrfTokenFailureReason, extractCsrfTokenHeader, getCurrentCsrfToken, storeCsrfToken, wipeCurrentCsrfToken, } from '../csrf-token.js';
 import { AuthHeaderName } from '../headers.js';
 /**
@@ -15,17 +14,14 @@ export class FrontendAuthClient {
     constructor(config = {}) {
         this.config = config;
         if (config.checkUser) {
-            const intervalDuration = convertDuration(config.checkUser.interval || { minutes: 1 }, {
-                milliseconds: true,
-            }).milliseconds;
-            this.userCheckInterval = globalThis.setInterval(async () => {
+            this.userCheckInterval = createBlockingInterval(async () => {
                 const response = await config.checkUser?.performCheck();
                 if (response) {
                     await this.verifyResponseAuth({
                         status: response.status,
                     });
                 }
-            }, intervalDuration);
+            }, config.checkUser.interval || { minutes: 1 });
         }
     }
     /**
@@ -33,7 +29,7 @@ export class FrontendAuthClient {
      * interval).
      */
     destroy() {
-        globalThis.clearInterval(this.userCheckInterval);
+        this.userCheckInterval?.clearInterval();
     }
     /** Wraps {@link getCurrentCsrfToken} to automatically handle wiping an invalid CSRF token. */
     async getCurrentCsrfToken() {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "auth-vir",
-    "version": "2.1.0",
+    "version": "2.3.0",
     "description": "Auth made easy and secure via JWT cookies, CSRF tokens, and password hashing helpers.",
     "keywords": [
         "auth",
@@ -42,8 +42,8 @@
         "test:web": "virmator test web"
     },
     "dependencies": {
-        "@augment-vir/assert": "^31.41.0",
-        "@augment-vir/common": "^31.41.0",
+        "@augment-vir/assert": "^31.42.0",
+        "@augment-vir/common": "^31.42.0",
         "date-vir": "^8.0.0",
         "hash-wasm": "^4.12.0",
         "jose": "^6.1.0",
@@ -52,9 +52,9 @@
         "url-vir": "^2.1.6"
     },
     "devDependencies": {
-        "@augment-vir/test": "^31.41.0",
+        "@augment-vir/test": "^31.42.0",
         "@prisma/client": "^6.17.1",
-        "@types/node": "^24.8.1",
+        "@types/node": "^24.9.1",
         "@web/dev-server-esbuild": "^1.0.4",
         "@web/test-runner": "^0.20.2",
         "@web/test-runner-commands": "^0.9.0",

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

@@ -8,7 +8,7 @@ import {
 } from '@augment-vir/common';
 import {calculateRelativeDate, getNowInUtcTimezone, isDateAfter, type AnyDuration} from 'date-vir';
 import {type IncomingHttpHeaders, type OutgoingHttpHeaders} from 'node:http';
-import {type EmptyObject} from 'type-fest';
+import {type EmptyObject, type RequireExactlyOne, type RequireOneOrNone} from 'type-fest';
 import {
     extractUserIdFromRequestHeaders,
     generateLogoutHeaders,
@@ -369,31 +369,52 @@ export class BackendAuthClient<
     }
 
     /** Use these headers to log out the user. */
-    public async createLogoutHeaders(): Promise<
-        {
-            'set-cookie': string;
-        } & Record<CsrfHeaderName, string>
+    public async createLogoutHeaders(
+        params: RequireExactlyOne<{
+            allCookies: true;
+            isSignUpCookie: boolean;
+        }>,
+    ): Promise<
+        Partial<Record<CsrfHeaderName, string>> & {
+            'set-cookie': string[];
+        }
     > {
-        const signUpCookieHeaders = generateLogoutHeaders(
-            await this.getCookieParams({
-                isSignUpCookie: true,
-            }),
-            this.config.overrides,
-        );
-        const authCookieHeaders = generateLogoutHeaders(
-            await this.getCookieParams({
-                isSignUpCookie: false,
-            }),
-            this.config.overrides,
-        );
-
-        return {
-            ...authCookieHeaders,
+        const signUpCookieHeaders =
+            params.allCookies || params.isSignUpCookie
+                ? (generateLogoutHeaders(
+                      await this.getCookieParams({
+                          isSignUpCookie: true,
+                      }),
+                      this.config.overrides,
+                  ) satisfies Record<CsrfHeaderName, string>)
+                : undefined;
+        const authCookieHeaders =
+            params.allCookies || !params.isSignUpCookie
+                ? (generateLogoutHeaders(
+                      await this.getCookieParams({
+                          isSignUpCookie: false,
+                      }),
+                      this.config.overrides,
+                  ) satisfies Record<CsrfHeaderName, string>)
+                : undefined;
+
+        const setCookieHeader: {
+            'set-cookie': string[];
+        } = {
             'set-cookie': mergeHeaderValues(
-                signUpCookieHeaders['set-cookie'],
-                authCookieHeaders['set-cookie'],
+                signUpCookieHeaders?.['set-cookie'],
+                authCookieHeaders?.['set-cookie'],
             ),
         };
+        const csrfTokenHeader = {
+            ...authCookieHeaders,
+            ...signUpCookieHeaders,
+        } as Record<CsrfHeaderName, string>;
+
+        return {
+            ...csrfTokenHeader,
+            ...setCookieHeader,
+        };
     }
 
     /** Use these headers to log a user in. */
@@ -442,19 +463,47 @@ export class BackendAuthClient<
         };
     }
 
+    /** Combines `.getInsecureUser()` and `.getSecureUser()` into one method. */
+    public async getInsecureOrSecureUser(params: {
+        requestHeaders: IncomingHttpHeaders;
+        isSignUpCookie?: boolean | undefined;
+    }): Promise<
+        RequireOneOrNone<{
+            secureUser: GetUserResult<DatabaseUser>;
+            /**
+             * @deprecated This only half authenticates the user. It should only be used in
+             *   circumstances 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.
+             */
+            insecureUser: GetUserResult<DatabaseUser>;
+        }>
+    > {
+        const secureUser = await this.getSecureUser(params);
+
+        if (secureUser) {
+            return secureUser;
+        }
+
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        const insecureUser = await this.getInsecureUser(params);
+
+        return insecureUser ? {insecureUser} : {};
+    }
+
     /**
      * @deprecated This only half authenticates the user. It should only be used in circumstances
      *   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.
      */
     public async getInsecureUser({
-        headers,
+        requestHeaders,
     }: {
-        headers: IncomingHttpHeaders;
+        requestHeaders: IncomingHttpHeaders;
     }): Promise<GetUserResult<DatabaseUser> | undefined> {
         // eslint-disable-next-line @typescript-eslint/no-deprecated
         const userIdResult = await insecureExtractUserIdFromCookieAlone<UserId>(
-            headers,
+            requestHeaders,
             await this.getJwtParams(),
             AuthCookieName.Auth,
         );

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

@@ -1,4 +1,5 @@
 import {
+    createBlockingInterval,
     HttpStatus,
     type JsonCompatibleObject,
     type MaybePromise,
@@ -6,7 +7,7 @@ import {
     type SelectFrom,
     type SetOptionalWithUndefined,
 } from '@augment-vir/common';
-import {convertDuration, type AnyDuration} from 'date-vir';
+import {type AnyDuration} from 'date-vir';
 import {type EmptyObject} from 'type-fest';
 import {
     CsrfTokenFailureReason,
@@ -68,22 +69,21 @@ export type FrontendAuthClientConfig = PartialWithUndefined<{
  * @category Client
  */
 export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject = EmptyObject> {
-    protected userCheckInterval: undefined | ReturnType<typeof globalThis.setInterval>;
+    protected userCheckInterval: undefined | ReturnType<typeof createBlockingInterval>;
 
     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);
+            this.userCheckInterval = createBlockingInterval(
+                async () => {
+                    const response = await config.checkUser?.performCheck();
+                    if (response) {
+                        await this.verifyResponseAuth({
+                            status: response.status,
+                        });
+                    }
+                },
+                config.checkUser.interval || {minutes: 1},
+            );
         }
     }
 
@@ -92,7 +92,7 @@ export class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject =
      * interval).
      */
     public destroy() {
-        globalThis.clearInterval(this.userCheckInterval);
+        this.userCheckInterval?.clearInterval();
     }
 
     /** Wraps {@link getCurrentCsrfToken} to automatically handle wiping an invalid CSRF token. */