auth-vir 1.3.1 → 2.0.0

package/README.md

@@ -13,6 +13,10 @@ npm i auth-vir
 
 # Usage
 
+## Easy usage
+
+For the easiest usage, construct and use `BackendAuthClient` on your server and `FrontendAuthClient` in your frontend.
+
 ## Password hashing
 
 -   Hash a user created password:
@@ -49,9 +53,9 @@ npm i auth-vir
 
 Use this on your host / server / backend to authenticate client / frontend requests.
 
-1. Expose the [`csrfTokenHeaderName`](https://electrovir.github.io/auth-vir/variables/csrfTokenHeaderName.html) (or just `'csrf-token'`) header via CORS headers with either of the following options:
-    1. Set `customHeaders: [csrfTokenHeaderName]` in `implementService` from [`@rest-vir/implement-service`](https://www.npmjs.com/package/@rest-vir/implement-service).
-    2. Set the header `Access-Control-Allow-Headers` to (at least) `csrfTokenHeaderName`.
+1. Expose the [`AuthHeaderName.CsrfToken`](https://electrovir.github.io/auth-vir/variables/AuthHeaderName.html) (or just `'csrf-token'`) header via CORS headers with either of the following options:
+    1. Set `customHeaders: [AuthHeaderName.CsrfToken]` in `implementService` from [`@rest-vir/implement-service`](https://www.npmjs.com/package/@rest-vir/implement-service).
+    2. Set the header `Access-Control-Allow-Headers` to (at least) `AuthHeaderName.CsrfToken`.
 2. Set the `Access-Control-Allow-Origin` header (it cannot be `*`) and properly implement CORS headers and responses.
 3. Generate JWT signing and encryption keys with one of the following:
     - Run `npx auth-vir`: the generated keys will be printed to your console.
@@ -79,6 +83,8 @@ import {
     type CreateJwtParams,
 } from 'auth-vir';
 
+type MyUserId = string;
+
 /**
  * Use this for a /login endpoint.
  *
@@ -125,7 +131,9 @@ export async function createUser(
  * This loads the current user from their auth cookie and CSRF token.
  */
 export async function getAuthenticatedUser(request: ClientRequest) {
-    const userId = await extractUserIdFromRequestHeaders(request.getHeaders(), jwtParams);
+    const userId = (
+        await extractUserIdFromRequestHeaders<MyUserId>(request.getHeaders(), jwtParams)
+    )?.userId;
     const user = userId ? findUserInDatabaseById(userId) : undefined;
 
     if (!userId || !user) {
@@ -180,7 +188,12 @@ function findUserInDatabaseByUsername(username: string) {
     };
 }
 
-function findUserInDatabaseById(userId: string): undefined | {id: string; username: string} {
+function findUserInDatabaseById(userId: MyUserId):
+    | undefined
+    | {
+          id: MyUserId;
+          username: string;
+      } {
     /** This should connect to your database and find a user matching the given user id. */
 
     return {
@@ -230,7 +243,7 @@ Use this on your client / frontend for storing and sending session authorization
 
 1. Send a login fetch request to your host / server / backend with `{credentials: 'include'}` set on the request.
 2. Pass the `Response` from step 1 into [`handleAuthResponse`](https://electrovir.github.io/auth-vir/functions/handleAuthResponse.html).
-3. In all subsequent fetch requests to the host / server / backend, set `{credentials: 'include'}` and include `{headers: {[csrfTokenHeaderName]: getCurrentCsrfToken()}}`.
+3. In all subsequent fetch requests to the host / server / backend, set `{credentials: 'include'}` and include `{headers: {[AuthHeaderName.CsrfToken]: getCurrentCsrfToken()}}`.
 4. Upon user logout, call [`wipeCurrentCsrfToken()`](https://electrovir.github.io/auth-vir/functions/wipeCurrentCsrfToken.html)
 
 Here's a full example of how to use all the client / frontend side auth functionality:
@@ -239,19 +252,15 @@ Here's a full example of how to use all the client / frontend side auth function
 
 ```TypeScript
 import {HttpStatus} from '@augment-vir/common';
-import {
-    csrfTokenHeaderName,
-    getCurrentCsrfToken,
-    handleAuthResponse,
-    wipeCurrentCsrfToken,
-} from 'auth-vir';
+import {AuthHeaderName} from '../headers.js';
+import {getCurrentCsrfToken, handleAuthResponse, wipeCurrentCsrfToken} from 'auth-vir';
 
 /** Call this when the user logs in for the first time this session. */
 export async function sendLoginRequest(
     userLoginData: {username: string; password: string},
     loginUrl: string,
 ) {
-    if (getCurrentCsrfToken()) {
+    if (getCurrentCsrfToken().csrfToken) {
         throw new Error('Already logged in.');
     }
 
@@ -272,7 +281,7 @@ export async function sendAuthenticatedRequest(
     requestInit: Omit<RequestInit, 'headers'> = {},
     headers: Record<string, string> = {},
 ) {
-    const csrfToken = getCurrentCsrfToken();
+    const {csrfToken} = getCurrentCsrfToken();
 
     if (!csrfToken) {
         throw new Error('Not authenticated.');
@@ -283,7 +292,7 @@ export async function sendAuthenticatedRequest(
         credentials: 'include',
         headers: {
             ...headers,
-            [csrfTokenHeaderName]: csrfToken,
+            [AuthHeaderName.CsrfToken]: csrfToken.token,
         },
     });
 
@@ -310,8 +319,8 @@ export function logout() {
 
 All of these configurations must be set for the auth exports in this package to function properly:
 
--   Expose the [`csrfTokenHeaderName`](https://electrovir.github.io/auth-vir/variables/csrfTokenHeaderName.html) (or just `'csrf-token'`) header via CORS headers with either of the following options:
-    1.  Set `customHeaders: [csrfTokenHeaderName]` in `implementService` from [`@rest-vir/implement-service`](https://www.npmjs.com/package/@rest-vir/implement-service).
-    2.  Set the header `Access-Control-Allow-Headers` to (at least) `csrfTokenHeaderName`.
+-   Expose the [`AuthHeaderName.CsrfToken`](https://electrovir.github.io/auth-vir/variables/AuthHeaderName.html) (or just `'csrf-token'`) header via CORS headers with either of the following options:
+    1.  Set `customHeaders: [AuthHeaderName.CsrfToken]` in `implementService` from [`@rest-vir/implement-service`](https://www.npmjs.com/package/@rest-vir/implement-service).
+    2.  Set the header `Access-Control-Allow-Headers` to (at least) `AuthHeaderName.CsrfToken`.
 -   Set `credentials: include` in all fetch requests on the client that need to use or set the auth cookie.
 -   Server CORS should set `Access-Control-Allow-Origin` (it cannot be `*`).

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

@@ -0,0 +1,177 @@
+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 UserIdResult } from '../auth.js';
+import { type CookieParams } from '../cookie.js';
+import { AuthHeaderName } from '../headers.js';
+import { type JwtKeys, type RawJwtKeys } from '../jwt/jwt-keys.js';
+import { type CreateJwtParams } from '../jwt/jwt.js';
+/**
+ * Output from `BackendAuthClient.getSecureUser()`.
+ *
+ * @category Internal
+ */
+export type GetUserResult<DatabaseUser extends AnyObject> = {
+    /** The retrieved user. */
+    user: DatabaseUser;
+    /**
+     * When `true`, indicates that the current `user` result is as assumed user. This can only be
+     * `true` if you've configured user assuming in `BackendAuthClient`.
+     */
+    isAssumed: boolean;
+    /**
+     * This should be merged into your own response headers. It usually contains auth cookie
+     * duration refresh headers.
+     */
+    responseHeaders: OutgoingHttpHeaders;
+};
+/**
+ * Config for {@link BackendAuthClient}.
+ *
+ * @category Internal
+ */
+export type BackendAuthClientConfig<DatabaseUser extends AnyObject, UserId extends string | number, CsrfHeaderName extends string = AuthHeaderName.CsrfToken, AssumedUserParams extends JsonCompatibleObject = EmptyObject> = Readonly<{
+    /** The origin of your backend that is offering auth cookies. */
+    serviceOrigin: string;
+    /** Finds the relevant user from your own database. */
+    getUserFromDatabase: (userParams: {
+        /** The user id extracted from the request cookie. */
+        userId: UserId;
+        /** Indicates that we're loading the user from a sign up cookie. */
+        isSignUpCookie: boolean;
+        /**
+         * If this is set, we're attempting to load a database user for the purpose of assuming
+         * their user identity. Otherwise, this is `undefined`.
+         */
+        assumedUserParams: AssumedUserParams | undefined;
+    }) => MaybePromise<DatabaseUser | undefined | null>;
+    /**
+     * Get JWT keys produced by {@link generateNewJwtKeys}. Make sure that each time this is
+     * called, the same JWT keys are returned (do not call {@link generateNewJwtKeys} each time
+     * this is called). Any time the JWT keys change, all current sessions will terminate.
+     */
+    getJetKeys: () => MaybePromise<Readonly<RawJwtKeys>>;
+    /**
+     * When `isDev` is set, cookies do not require HTTPS (so they can be used with
+     * http://localhost).
+     */
+    isDev: boolean;
+} & PartialWithUndefined<{
+    /**
+     * 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
+     * issues.
+     *
+     * @see {@link AuthHeaderName}
+     */
+    assumeUser: {
+        /**
+         * Handles assumed user header value.
+         *
+         * @see {@link AuthHeaderName}
+         */
+        handleAssumedUserData: (
+        /**
+         * The assumed user header value.
+         *
+         * @see {@link AuthHeaderName}
+         */
+        data: string) => MaybePromise<{
+            assumedUserParams: AssumedUserParams;
+            userId: UserId;
+        } | undefined>;
+        /**
+         * Return `true` to allow the current user (by the given id) to assume identities of
+         * other users. Return `false` to block it. It is recommended to only return `true` for
+         * admin users.
+         *
+         * @see {@link AuthHeaderName}
+         */
+        canAssumeUser: (params: {
+            userId: UserId;
+        }) => MaybePromise<boolean>;
+    };
+    /**
+     * This determines how long a cookie will be valid until it needs to be refreshed.
+     *
+     * @default {minutes: 20}
+     */
+    userSessionIdleTimeout: Readonly<AnyDuration>;
+    /**
+     * How long before a user's session times out when we should start trying to refresh their
+     * session.
+     *
+     * @default {minutes: 5}
+     */
+    sessionRefreshThreshold: Readonly<AnyDuration>;
+    overrides: PartialWithUndefined<{
+        csrfHeaderName: CsrfHeaderName;
+        assumedUserHeaderName: string;
+    }>;
+}>>;
+/**
+ * An auth client for creating and validating JWTs embedded in cookies. This should only be used in
+ * a backend environment as it accesses native Node packages.
+ *
+ * @category Auth : Host
+ * @category Client
+ */
+export declare class BackendAuthClient<DatabaseUser extends AnyObject, UserId extends string | number, CsrfHeaderName extends string = AuthHeaderName.CsrfToken, AssumedUserParams extends AnyObject = EmptyObject> {
+    protected readonly config: BackendAuthClientConfig<DatabaseUser, UserId, CsrfHeaderName, AssumedUserParams>;
+    protected cachedParsedJwtKeys: Record<string, Readonly<JwtKeys>>;
+    constructor(config: BackendAuthClientConfig<DatabaseUser, UserId, CsrfHeaderName, AssumedUserParams>);
+    /** Get all the parameters used for cookie generation. */
+    protected getCookieParams({ isSignUpCookie, }: {
+        /**
+         * 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;
+    }): Promise<Readonly<CookieParams>>;
+    /** Calls the provided `getUserFromDatabase` config. */
+    protected getDatabaseUser({ isSignUpCookie, userId, assumedUserParams, }: {
+        userId: UserId | undefined;
+        assumedUserParams: AssumedUserParams | undefined;
+        isSignUpCookie: boolean;
+    }): Promise<undefined | DatabaseUser>;
+    /** Creates a `'cookie-set'` header to refresh the user's session cookie. */
+    protected createCookieRefreshHeaders({ userIdResult, }: {
+        userIdResult: Readonly<UserIdResult<UserId>>;
+    }): Promise<OutgoingHttpHeaders | undefined>;
+    /** Reads the user's assumed user headers and, if configured, gets the assumed user. */
+    protected getAssumedUser({ headers, originalUserId, }: {
+        originalUserId: UserId | undefined;
+        headers: IncomingHttpHeaders;
+    }): Promise<DatabaseUser | undefined>;
+    /** Securely extract a user from their request headers. */
+    getSecureUser({ requestHeaders, isSignUpCookie, }: {
+        requestHeaders: IncomingHttpHeaders;
+        isSignUpCookie?: boolean | undefined;
+    }): Promise<GetUserResult<DatabaseUser> | undefined>;
+    /**
+     * Get all the JWT params used when creating the auth cookie, in case you need them for
+     * something else too.
+     */
+    getJwtParams(): Promise<Readonly<CreateJwtParams>>;
+    /** Use these headers to log out the user. */
+    createLogoutHeaders(): Promise<{
+        'set-cookie': string;
+    } & Record<CsrfHeaderName, 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>>;
+    /**
+     * @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;
+    }): Promise<GetUserResult<DatabaseUser> | undefined>;
+}

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

@@ -0,0 +1,232 @@
+import { ensureArray, } from '@augment-vir/common';
+import { calculateRelativeDate, getNowInUtcTimezone, isDateAfter } from 'date-vir';
+import { extractUserIdFromRequestHeaders, generateLogoutHeaders, generateSuccessfulLoginHeaders, insecureExtractUserIdFromCookieAlone, } from '../auth.js';
+import { AuthCookieName } from '../cookie.js';
+import { AuthHeaderName, mergeHeaderValues } from '../headers.js';
+import { parseJwtKeys } from '../jwt/jwt-keys.js';
+const defaultSessionIdleTimeout = {
+    minutes: 20,
+};
+/**
+ * An auth client for creating and validating JWTs embedded in cookies. This should only be used in
+ * a backend environment as it accesses native Node packages.
+ *
+ * @category Auth : Host
+ * @category Client
+ */
+export class BackendAuthClient {
+    config;
+    cachedParsedJwtKeys = {};
+    constructor(config) {
+        this.config = config;
+    }
+    /** Get all the parameters used for cookie generation. */
+    async getCookieParams({ isSignUpCookie, }) {
+        return {
+            cookieDuration: this.config.userSessionIdleTimeout || defaultSessionIdleTimeout,
+            hostOrigin: this.config.serviceOrigin,
+            jwtParams: await this.getJwtParams(),
+            isDev: this.config.isDev,
+            cookieName: isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth,
+        };
+    }
+    /** Calls the provided `getUserFromDatabase` config. */
+    async getDatabaseUser({ isSignUpCookie, userId, assumedUserParams, }) {
+        if (!userId) {
+            return undefined;
+        }
+        const authenticatedUser = await this.config.getUserFromDatabase({
+            assumedUserParams,
+            userId,
+            isSignUpCookie,
+        });
+        if (!authenticatedUser) {
+            return undefined;
+        }
+        return authenticatedUser;
+    }
+    /** Creates a `'cookie-set'` header to refresh the user's session cookie. */
+    async createCookieRefreshHeaders({ userIdResult, }) {
+        const now = getNowInUtcTimezone();
+        /** Double check that the JWT hasn't already expired. */
+        const isExpiredAlready = isDateAfter({
+            fullDate: now,
+            relativeTo: userIdResult.jwtExpiration,
+        });
+        if (isExpiredAlready) {
+            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 isRefreshReady = isDateAfter({
+            fullDate: calculateRelativeDate(now, this.config.sessionRefreshThreshold || {
+                minutes: 5,
+            }),
+            relativeTo: userIdResult.jwtExpiration,
+        });
+        if (isRefreshReady) {
+            return this.createLoginHeaders({
+                requestHeaders: {},
+                userId: userIdResult.userId,
+                isSignUpCookie: userIdResult.cookieName === AuthCookieName.SignUp,
+            });
+        }
+        else {
+            return undefined;
+        }
+    }
+    /** Reads the user's assumed user headers and, if configured, gets the assumed user. */
+    async getAssumedUser({ headers, originalUserId, }) {
+        if (!originalUserId ||
+            !this.config.assumeUser ||
+            !(await this.config.assumeUser.canAssumeUser({
+                userId: originalUserId,
+            }))) {
+            return undefined;
+        }
+        const assumedUserHeader = ensureArray(headers[this.config.overrides?.assumedUserHeaderName || AuthHeaderName.AssumedUser])[0];
+        if (!assumedUserHeader) {
+            return undefined;
+        }
+        const parsedAssumedUserData = await this.config.assumeUser.handleAssumedUserData(assumedUserHeader);
+        if (!parsedAssumedUserData || !parsedAssumedUserData.userId) {
+            return undefined;
+        }
+        const assumedUser = await this.getDatabaseUser({
+            isSignUpCookie: false,
+            userId: parsedAssumedUserData.userId,
+            assumedUserParams: parsedAssumedUserData.assumedUserParams,
+        });
+        return assumedUser;
+    }
+    /** Securely extract a user from their request headers. */
+    async getSecureUser({ requestHeaders, isSignUpCookie, }) {
+        const userIdResult = await extractUserIdFromRequestHeaders(requestHeaders, await this.getJwtParams(), isSignUpCookie ? AuthCookieName.SignUp : AuthCookieName.Auth, this.config.overrides);
+        if (!userIdResult) {
+            return undefined;
+        }
+        const user = await this.getDatabaseUser({
+            userId: userIdResult.userId,
+            assumedUserParams: undefined,
+            isSignUpCookie: !!isSignUpCookie,
+        });
+        if (!user) {
+            return undefined;
+        }
+        const assumedUser = await this.getAssumedUser({
+            headers: requestHeaders,
+            originalUserId: userIdResult.userId,
+        });
+        const cookieRefreshHeaders = (await this.createCookieRefreshHeaders({
+            userIdResult,
+        })) || {};
+        if (assumedUser) {
+            return {
+                user: assumedUser,
+                isAssumed: true,
+                responseHeaders: cookieRefreshHeaders,
+            };
+        }
+        else {
+            return {
+                user,
+                isAssumed: false,
+                responseHeaders: cookieRefreshHeaders,
+            };
+        }
+    }
+    /**
+     * Get all the JWT params used when creating the auth cookie, in case you need them for
+     * something else too.
+     */
+    async getJwtParams() {
+        const rawJwtKeys = await this.config.getJetKeys();
+        const cacheKey = JSON.stringify(rawJwtKeys);
+        const cachedParsedKeys = this.cachedParsedJwtKeys[cacheKey];
+        const parsedKeys = cachedParsedKeys ?? (await parseJwtKeys(rawJwtKeys));
+        if (!cachedParsedKeys) {
+            this.cachedParsedJwtKeys = { [cacheKey]: parsedKeys };
+        }
+        return {
+            jwtKeys: parsedKeys,
+            audience: 'server-context',
+            issuer: 'server-auth',
+            jwtDuration: this.config.userSessionIdleTimeout || defaultSessionIdleTimeout,
+        };
+    }
+    /** 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 {
+            ...authCookieHeaders,
+            'set-cookie': mergeHeaderValues(signUpCookieHeaders['set-cookie'], authCookieHeaders['set-cookie']),
+        };
+    }
+    /** Use these headers to log a user in. */
+    async createLoginHeaders({ userId, requestHeaders, isSignUpCookie, }) {
+        const oppositeCookieName = isSignUpCookie ? AuthCookieName.Auth : AuthCookieName.SignUp;
+        const hasExistingOppositeCookie = requestHeaders.cookie?.includes(`${oppositeCookieName}=`);
+        const discardOppositeCookieHeaders = hasExistingOppositeCookie
+            ? generateLogoutHeaders(await this.getCookieParams({
+                isSignUpCookie: !isSignUpCookie,
+            }), this.config.overrides)
+            : undefined;
+        const newCookieHeaders = await generateSuccessfulLoginHeaders(userId, await this.getCookieParams({
+            isSignUpCookie,
+        }), this.config.overrides);
+        return {
+            ...newCookieHeaders,
+            'set-cookie': mergeHeaderValues(newCookieHeaders['set-cookie'], discardOppositeCookieHeaders?.['set-cookie']),
+            ...(isSignUpCookie
+                ? {
+                    [AuthHeaderName.IsSignUpAuth]: 'true',
+                }
+                : {}),
+        };
+    }
+    /**
+     * @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, }) {
+        // eslint-disable-next-line @typescript-eslint/no-deprecated
+        const userIdResult = await insecureExtractUserIdFromCookieAlone(headers, await this.getJwtParams(), AuthCookieName.Auth);
+        if (!userIdResult) {
+            return undefined;
+        }
+        const user = await this.getDatabaseUser({
+            isSignUpCookie: false,
+            userId: userIdResult.userId,
+            assumedUserParams: undefined,
+        });
+        if (!user) {
+            return undefined;
+        }
+        return {
+            user,
+            isAssumed: false,
+            responseHeaders: (await this.createCookieRefreshHeaders({
+                userIdResult,
+            })) || {},
+        };
+    }
+}

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

@@ -0,0 +1,64 @@
+import { type JsonCompatibleObject, type MaybePromise, type PartialWithUndefined, type SelectFrom } from '@augment-vir/common';
+import { type EmptyObject } from 'type-fest';
+/**
+ * Config for {@link FrontendAuthClient}.
+ *
+ * @category Internal
+ */
+export type FrontendAuthClientConfig = PartialWithUndefined<{
+    /**
+     * Determine if the current user can assume the identity of another user. If this is not
+     * defined, all users will be blocked from assuming other user identities.
+     */
+    canAssumeUser: () => MaybePromise<boolean>;
+    /** Called whenever the current user becomes unauthorized and their CSRF token is wiped. */
+    authClearedCallback: () => MaybePromise<void>;
+    overrides: PartialWithUndefined<{
+        localStorage: Pick<Storage, 'setItem' | 'removeItem' | 'getItem'>;
+        csrfHeaderName: string;
+        assumedUserHeaderName: string;
+    }>;
+}>;
+/**
+ * An auth client for sending and validating client requests to a backend. This should only be used
+ * in a frontend environment as it accesses native browser APIs.
+ *
+ * @category Auth : Client
+ * @category Client
+ */
+export declare class FrontendAuthClient<AssumedUserParams extends JsonCompatibleObject = EmptyObject> {
+    protected readonly config: FrontendAuthClientConfig;
+    constructor(config?: FrontendAuthClientConfig);
+    /** 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>;
+    getAssumedUser(): AssumedUserParams | undefined;
+    /**
+     * Creates a `RequestInit` object for the `fetch` API. If you have other request init options,
+     * use [`mergeDeep` from
+     * `@augment-vir/common`](https://electrovir.github.io/augment-vir/functions/mergeDeep.html) to
+     * combine them with these.
+     */
+    createAuthenticatedRequestInit(): Promise<RequestInit>;
+    /** Wipes the current user auth. */
+    logout(): Promise<void>;
+    /**
+     * Use to handle a login response. Automatically stores the CSRF token.
+     *
+     * @throws Error if the login response failed.
+     * @throws Error if the login response has an invalid CSRF token.
+     */
+    handleLoginResponse(response: Readonly<SelectFrom<Response, {
+        headers: true;
+        ok: true;
+    }>>): Promise<void>;
+    /**
+     * 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, {
+        status: true;
+        headers: true;
+    }>>): Promise<void>;
+}