auth-vir 0.0.0 → 0.0.2

package/LICENSE-CC0

@@ -0,0 +1,121 @@
+CC0 1.0 Universal
+
+Creative Commons Legal Code
+
+    CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE
+    LEGAL SERVICES. DISTRIBUTION OF THIS DOCUMENT DOES NOT CREATE AN
+    ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS
+    INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES
+    REGARDING THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS
+    PROVIDED HEREUNDER, AND DISCLAIMS LIABILITY FOR DAMAGES RESULTING FROM
+    THE USE OF THIS DOCUMENT OR THE INFORMATION OR WORKS PROVIDED
+    HEREUNDER.
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator
+and subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for
+the purpose of contributing to a commons of creative, cultural and
+scientific works ("Commons") that the public can reliably and without fear
+of later claims of infringement build upon, modify, incorporate in other
+works, reuse and redistribute as freely as possible in any form whatsoever
+and for any purposes, including without limitation commercial purposes.
+These owners may contribute to the Commons to promote the ideal of a free
+culture and the further production of creative, cultural and scientific
+works, or to gain reputation or greater distribution for their Work in
+part through the use and efforts of others.
+
+For these and/or other purposes and motivations, and without any
+expectation of additional consideration or compensation, the person
+associating CC0 with a Work (the "Affirmer"), to the extent that he or she
+is an owner of Copyright and Related Rights in the Work, voluntarily
+elects to apply CC0 to the Work and publicly distribute the Work under its
+terms, with knowledge of his or her Copyright and Related Rights in the
+Work and the meaning and intended legal effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not
+limited to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display,
+     communicate, and translate a Work;
+ ii. moral rights retained by the original author(s) and/or performer(s);
+iii. publicity and privacy rights pertaining to a person's image or
+     likeness depicted in a Work;
+ iv. rights protecting against unfair competition in regards to a Work,
+     subject to the limitations in paragraph 4(a), below;
+  v. rights protecting the extraction, dissemination, use and reuse of data
+     in a Work;
+ vi. database rights (such as those arising under Directive 96/9/EC of the
+     European Parliament and of the Council of 11 March 1996 on the legal
+     protection of databases, and under any national implementation
+     thereof, including any amended or successor version of such
+     directive); and
+vii. other similar, equivalent or corresponding rights throughout the
+     world based on applicable law or treaty, and any national
+     implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention
+of, applicable law, Affirmer hereby overtly, fully, permanently,
+irrevocably and unconditionally waives, abandons, and surrenders all of
+Affirmer's Copyright and Related Rights and associated claims and causes
+of action, whether now known or unknown (including existing as well as
+future claims and causes of action), in the Work (i) in all territories
+worldwide, (ii) for the maximum duration provided by applicable law or
+treaty (including future time extensions), (iii) in any current or future
+medium and for any number of copies, and (iv) for any purpose whatsoever,
+including without limitation commercial, advertising or promotional
+purposes (the "Waiver"). Affirmer makes the Waiver for the benefit of each
+member of the public at large and to the detriment of Affirmer's heirs and
+successors, fully intending that such Waiver shall not be subject to
+revocation, rescission, cancellation, termination, or any other legal or
+equitable action to disrupt the quiet enjoyment of the Work by the public
+as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason
+be judged legally invalid or ineffective under applicable law, then the
+Waiver shall be preserved to the maximum extent permitted taking into
+account Affirmer's express Statement of Purpose. In addition, to the
+extent the Waiver is so judged Affirmer hereby grants to each affected
+person a royalty-free, non transferable, non sublicensable, non exclusive,
+irrevocable and unconditional license to exercise Affirmer's Copyright and
+Related Rights in the Work (i) in all territories worldwide, (ii) for the
+maximum duration provided by applicable law or treaty (including future
+time extensions), (iii) in any current or future medium and for any number
+of copies, and (iv) for any purpose whatsoever, including without
+limitation commercial, advertising or promotional purposes (the
+"License"). The License shall be deemed effective as of the date CC0 was
+applied by Affirmer to the Work. Should any part of the License for any
+reason be judged legally invalid or ineffective under applicable law, such
+partial invalidity or ineffectiveness shall not invalidate the remainder
+of the License, and in such case Affirmer hereby affirms that he or she
+will not (i) exercise any of his or her remaining Copyright and Related
+Rights in the Work or (ii) assert any associated claims and causes of
+action with respect to the Work, in either case contrary to Affirmer's
+express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+ a. No trademark or patent rights held by Affirmer are waived, abandoned,
+    surrendered, licensed or otherwise affected by this document.
+ b. Affirmer offers the Work as-is and makes no representations or
+    warranties of any kind concerning the Work, express, implied,
+    statutory or otherwise, including without limitation warranties of
+    title, merchantability, fitness for a particular purpose, non
+    infringement, or the absence of latent or other defects, accuracy, or
+    the present or absence of errors, whether or not discoverable, all to
+    the greatest extent permissible under applicable law.
+ c. Affirmer disclaims responsibility for clearing rights of other persons
+    that may apply to the Work or any use thereof, including without
+    limitation any person's Copyright and Related Rights in the Work.
+    Further, Affirmer disclaims responsibility for obtaining any necessary
+    consents, permissions or other rights required for any use of the
+    Work.
+ d. Affirmer understands and acknowledges that Creative Commons is not a
+    party to this document and has no duty or obligation with respect to
+    this CC0 or use of the Work.

package/LICENSE-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 electrovir
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,322 @@
+# auth-vir
+
+Auth made easy and secure via JWT cookies, CSRF tokens, and password hashing helpers. ESM and browser friendly.
+
+-   Reference docs: https://electrovir.github.io/auth-vir
+-   Clone and run the demo: https://github.com/electrovir/auth-vir/blob/dev/packages/demo
+
+# Install
+
+```sh
+npm i auth-vir
+```
+
+# Usage
+
+## Password hashing
+
+-   Hash a user created password:
+    <!-- example-link: ./src/examples/password-hash.example.ts -->
+
+    ```TypeScript
+    import {hashPassword} from 'auth-vir';
+
+    /** When a user creates or resets their password, hash it before storing it in your database. */
+
+    const hashedPassword = await hashPassword('user input password');
+
+    if (!hashedPassword) {
+        /** This happens if the user password is too long for the bcrypt algorithm. */
+        throw new Error('Password too long.');
+    }
+    /** Now store `hashedPassword` in your database. */
+    ```
+
+-   Compare a stored password hash for login checking:
+    <!-- example-link: ./src/examples/password-compare.example.ts -->
+
+    ```TypeScript
+    import {doesPasswordMatchHash} from 'auth-vir';
+
+    if (
+        !(await doesPasswordMatchHash({
+            hash: 'hash from database',
+            password: 'user input password for login',
+        }))
+    ) {
+        throw new Error('Login failure.');
+    }
+    ```
+
+## Session auth
+
+### Host / server / backend side
+
+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`.
+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.
+    - Run [`await generateNewJwtKeys()`](https://electrovir.github.io/auth-vir/functions/generateNewJwtKeys.html) (imported from this package) in your code.
+4. Securely store the generated keys in a secret place. Do not commit them. They should not be shared with anyone or any other host, client, or service.
+5. In your application code, load the string keys from step 1 into [`parseJwtKeys`](https://electrovir.github.io/auth-vir/functions/parseUserJwt.html): `await parseJwtKeys(stringKeys)`.
+6. Use the output of [`parseJwtKeys`](https://electrovir.github.io/auth-vir/functions/parseUserJwt.html) in all auth functionality:
+    - [`generateSuccessfulLoginHeaders`](https://electrovir.github.io/auth-vir/functions/generateSuccessfulLoginHeaders.html): after a user successfully logs in, run this function and attach the output headers to the `Response` object.
+    - [`extractUserIdFromRequestHeaders`](https://electrovir.github.io/auth-vir/functions/extractUserIdFromRequestHeaders.html): to verify an authenticated user `Request` object (make sure to properly attach all auth in the client by following the below [Client / frontend side](#client--frontend-side) guide).
+
+Here's a full example of how to use all host / server / backend side auth functionality:
+
+<!-- example-link: ./src/examples/full-backend.example.ts -->
+
+```TypeScript
+import {type ClientRequest, type ServerResponse} from 'node:http';
+import {
+    doesPasswordMatchHash,
+    extractUserIdFromRequestHeaders,
+    generateNewJwtKeys,
+    generateSuccessfulLoginHeaders,
+    hashPassword,
+    parseJwtKeys,
+    type CookieParams,
+    type CreateJwtParams,
+} from 'auth-vir';
+
+/**
+ * Use this for a /login endpoint.
+ *
+ * This verifies a user's login credentials and generate the auth cookie and CSRF token.
+ */
+export async function handleLogin(
+    userRequestData: Readonly<{username: string; password: string}>,
+    response: ServerResponse,
+) {
+    const user = findUserInDatabaseByUsername(userRequestData.username);
+
+    if (
+        !(await doesPasswordMatchHash({
+            hash: user.hashedPassword,
+            password: userRequestData.password,
+        }))
+    ) {
+        throw new Error('Credentials mismatch.');
+    }
+
+    const authHeaders = await generateSuccessfulLoginHeaders(user.id, cookieParams);
+    response.setHeaders(new Headers(authHeaders));
+}
+
+/**
+ * Use this for a /sign-up endpoint.
+ *
+ * This creates a new user, stores their securely hashed password in the database, and generates the
+ * auth cookie and CSRF token.
+ */
+export async function createUser(
+    userRequestData: Readonly<{username: string; password: string}>,
+    response: ServerResponse,
+) {
+    const newUser = await createUserInDatabase(userRequestData);
+
+    const authHeaders = await generateSuccessfulLoginHeaders(newUser.id, cookieParams);
+    response.setHeaders(new Headers(authHeaders));
+}
+
+/**
+ * Use this all endpoints that require an authenticated user.
+ *
+ * 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 user = userId ? findUserInDatabaseById(userId) : undefined;
+
+    if (!userId || !user) {
+        throw new Error('Unauthorized.');
+    }
+
+    return user;
+}
+
+/**
+ * # ===========
+ *
+ * Helpers
+ *
+ * # ===========
+ */
+
+async function loadSecretJwtKeys() {
+    /**
+     * This should load your saved JWT keys from a non-committed config file or a secrets manager
+     * (like AWS Secrets Manager).
+     */
+    return await generateNewJwtKeys();
+}
+
+const jwtParams: Readonly<CreateJwtParams> = {
+    audience: 'server context',
+    jwtDuration: {
+        hours: 2,
+    },
+    issuer: 'server login',
+    jwtKeys: await parseJwtKeys(await loadSecretJwtKeys()),
+};
+
+const cookieParams: CookieParams = {
+    cookieDuration: {
+        hours: 2,
+    },
+    hostOrigin: 'https://your-backend-origin.example.com',
+    jwtParams,
+};
+
+function findUserInDatabaseByUsername(username: string) {
+    /** This should connect to your database and find a user matching the given username. */
+
+    return {
+        /** This should be retrieved from your database. */
+        id: 'some id',
+        username,
+        /** This should be retrieved from your database. */
+        hashedPassword: 'hash retrieved from database',
+    };
+}
+
+function findUserInDatabaseById(userId: string): undefined | {id: string; username: string} {
+    /** This should connect to your database and find a user matching the given user id. */
+
+    return {
+        id: userId,
+        /** This should be retrieved from your database. */
+        username: 'some username',
+    };
+}
+
+async function createUserInDatabase(
+    userRequestData: Readonly<{username: string; password: string}>,
+) {
+    const hashedPassword = await hashPassword(userRequestData.password);
+
+    if (!hashedPassword) {
+        throw new Error('Password too long.');
+    }
+
+    /**
+     * Store the new username and hashedPassword in your database and return the new user id.
+     *
+     * @example
+     *
+     *     // using the Prisma ORM:
+     *     return (
+     *         await prismaClient.user.create({
+     *             data: {
+     *                 username: userRequestData.username,
+     *                 hashedPassword,
+     *             },
+     *             select: {
+     *                 id: true,
+     *             },
+     *         })
+     *     ).id;
+     */
+
+    return {
+        id: 'some new id',
+    };
+}
+```
+
+### Client / frontend side
+
+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()}}`.
+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:
+
+<!-- example-link: ./src/examples/full-frontend.example.ts -->
+
+```TypeScript
+import {HttpStatus} from '@augment-vir/common';
+import {
+    csrfTokenHeaderName,
+    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()) {
+        throw new Error('Already logged in.');
+    }
+
+    const response = await fetch(loginUrl, {
+        method: 'post',
+        body: JSON.stringify(userLoginData),
+        credentials: 'include',
+    });
+
+    handleAuthResponse(response);
+
+    return response;
+}
+
+/** Call this when the user needs to send any authenticated request after already having logged in. */
+export async function sendAuthenticatedRequest(
+    requestUrl: string,
+    requestInit: Omit<RequestInit, 'headers'> = {},
+    headers: Record<string, string> = {},
+) {
+    const csrfToken = getCurrentCsrfToken();
+
+    if (!csrfToken) {
+        throw new Error('Not authenticated.');
+    }
+
+    const response = await fetch(requestUrl, {
+        ...requestInit,
+        credentials: 'include',
+        headers: {
+            ...headers,
+            [csrfTokenHeaderName]: csrfToken,
+        },
+    });
+
+    /**
+     * This indicates the user is no longer authorized and thus needs to login again. (This likely
+     * means that their session timed out or they clicked a "log out" button onr your website in
+     * another tab.)
+     */
+    if (response.status === HttpStatus.Unauthorized) {
+        wipeCurrentCsrfToken();
+        throw new Error(`User no longer logged in.`);
+    } else {
+        return response;
+    }
+}
+
+/** Call this when the user explicitly clicks a "log out" button. */
+export function logout() {
+    wipeCurrentCsrfToken();
+}
+```
+
+# Requirements
+
+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`.
+-   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/bin.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import {runCliScript} from '@augment-vir/node/dist/index.js';
+import {join} from 'node:path';
+
+const cliPath = join(import.meta.dirname, 'src', 'jwt-keys.script.ts');
+
+await runCliScript(cliPath, import.meta.filename, 'auth-vir');

package/dist/auth.d.ts

@@ -0,0 +1,79 @@
+import { CookieParams } from './cookie.js';
+import { ParseJwtParams } from './jwt.js';
+/**
+ * All possible headers container types supported by {@link extractUserIdFromRequestHeaders}.
+ *
+ * @category Internal
+ */
+export type HeaderContainer = Record<string, string[] | undefined | string | number> | Headers;
+/**
+ * Extract the user id from a request by checking both the request cookie and CSRF token. This is
+ * used by host (backend) code to help verify a request. After extracting the user id using this,
+ * you should compare it to users stored in your database.
+ *
+ * @category Auth : Host
+ * @returns The extracted user id or `undefined` if no valid auth headers exist.
+ */
+export declare function extractUserIdFromRequestHeaders(headers: HeaderContainer, jwtParams: Readonly<ParseJwtParams>): Promise<string | undefined>;
+/**
+ * Used by host (backend) code to set headers on a response object.
+ *
+ * @category Auth : Host
+ */
+export declare function generateSuccessfulLoginHeaders(userId: string, 
+/** The id from your database of the user you're authenticating. */
+cookieConfig: Readonly<CookieParams>): Promise<{
+    'set-cookie': string;
+    "csrf-token": string;
+}>;
+/**
+ * Store auth data on a client (frontend) after receiving an auth response from the host (backend).
+ * Specifically, this stores the CSRF token into local storage (which doesn't need to be a secret).
+ * Alternatively, if the given response failed, this will wipe the existing (if anyone) stored CSRF
+ * token.
+ *
+ * @category Auth : Client
+ * @throws Error if no CSRF token header is found.
+ */
+export declare function handleAuthResponse(response: Readonly<Pick<Response, 'ok' | 'headers'>>, overrides?: {
+    /**
+     * Allows mocking or overriding the global `localStorage`.
+     *
+     * @default globalThis.localStorage
+     */
+    localStorage?: Pick<Storage, 'setItem' | 'removeItem'>;
+    /** Override the default CSRF token header name. */
+    csrfHeaderName?: string;
+}): void;
+/**
+ * Used in client (frontend) code to retrieve the current CSRF token in order to send it with
+ * requests to the host (backend).
+ *
+ * @category Auth : Client
+ */
+export declare function getCurrentCsrfToken(overrides?: {
+    /**
+     * Allows mocking or overriding the global `localStorage`.
+     *
+     * @default globalThis.localStorage
+     */
+    localStorage?: Pick<Storage, 'getItem'>;
+    /** Override the default CSRF token header name. */
+    csrfHeaderName?: string;
+}): string | undefined;
+/**
+ * Wipes the current stored CSRF token. This should be used by client (frontend) code to logout a
+ * user or react to a session timeout.
+ *
+ * @category Auth : Client
+ */
+export declare function wipeCurrentCsrfToken(overrides?: {
+    /**
+     * Allows mocking or overriding the global `localStorage`.
+     *
+     * @default globalThis.localStorage
+     */
+    localStorage?: Pick<Storage, 'removeItem'>;
+    /** Override the default CSRF token header name. */
+    csrfHeaderName?: string;
+}): void;

package/dist/auth.js

@@ -0,0 +1,101 @@
+import { extractCookieJwt, generateCookie } from './cookie.js';
+import { csrfTokenHeaderName, generateCsrfToken } from './csrf-token.js';
+function readHeader(headers, headerName) {
+    if (headers instanceof Headers) {
+        return headers.get(headerName) || undefined;
+    }
+    else {
+        const value = headers[headerName];
+        if (value == undefined) {
+            return undefined;
+        }
+        else if (Array.isArray(value)) {
+            return value[0];
+        }
+        else {
+            return String(value);
+        }
+    }
+}
+/**
+ * Extract the user id from a request by checking both the request cookie and CSRF token. This is
+ * used by host (backend) code to help verify a request. After extracting the user id using this,
+ * you should compare it to users stored in your database.
+ *
+ * @category Auth : Host
+ * @returns The extracted user id or `undefined` if no valid auth headers exist.
+ */
+export async function extractUserIdFromRequestHeaders(headers, jwtParams) {
+    try {
+        const csrfToken = readHeader(headers, csrfTokenHeaderName);
+        const cookie = readHeader(headers, 'cookie');
+        if (!cookie || !csrfToken) {
+            return undefined;
+        }
+        const jwt = await extractCookieJwt(cookie, jwtParams);
+        if (!jwt || jwt.csrfToken !== csrfToken) {
+            return undefined;
+        }
+        return jwt.userId;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Used by host (backend) code to set headers on a response object.
+ *
+ * @category Auth : Host
+ */
+export async function generateSuccessfulLoginHeaders(userId, 
+/** The id from your database of the user you're authenticating. */
+cookieConfig) {
+    const csrfToken = generateCsrfToken();
+    return {
+        'set-cookie': await generateCookie({
+            csrfToken,
+            userId,
+        }, cookieConfig),
+        [csrfTokenHeaderName]: csrfToken,
+    };
+}
+/**
+ * Store auth data on a client (frontend) after receiving an auth response from the host (backend).
+ * Specifically, this stores the CSRF token into local storage (which doesn't need to be a secret).
+ * Alternatively, if the given response failed, this will wipe the existing (if anyone) stored CSRF
+ * token.
+ *
+ * @category Auth : Client
+ * @throws Error if no CSRF token header is found.
+ */
+export function handleAuthResponse(response, overrides = {}) {
+    if (!response.ok) {
+        wipeCurrentCsrfToken(overrides);
+        return;
+    }
+    const headerName = overrides.csrfHeaderName || csrfTokenHeaderName;
+    const csrfToken = response.headers.get(headerName);
+    if (!csrfToken) {
+        wipeCurrentCsrfToken(overrides);
+        throw new Error('Did not receive any CSRF token.');
+    }
+    (overrides.localStorage || globalThis.localStorage).setItem(headerName, csrfToken);
+}
+/**
+ * Used in client (frontend) code to retrieve the current CSRF token in order to send it with
+ * requests to the host (backend).
+ *
+ * @category Auth : Client
+ */
+export function getCurrentCsrfToken(overrides = {}) {
+    return ((overrides.localStorage || globalThis.localStorage).getItem(overrides.csrfHeaderName || csrfTokenHeaderName) || undefined);
+}
+/**
+ * Wipes the current stored CSRF token. This should be used by client (frontend) code to logout a
+ * user or react to a session timeout.
+ *
+ * @category Auth : Client
+ */
+export function wipeCurrentCsrfToken(overrides = {}) {
+    return (overrides.localStorage || globalThis.localStorage).removeItem(overrides.csrfHeaderName || csrfTokenHeaderName);
+}