auth-vir/dist/auth.d.ts

Auth made easy and secure via JWT cookies, CSRF tokens, and password hashing helpers.

import { clearAuthCookie, type CookieParams } from './cookie.js';
import { type 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>, cookieName?: string | undefined): Promise<string | undefined>;
/**
 * Extract a user id from just the cookie, without CSRF token validation. This is _less secure_ than
 * {@link extractUserIdFromRequestHeaders} as a result. This should only be used in rare
 * circumstances where you cannot rely on client-side JavaScript to insert the CSRF token.
 *
 * @deprecated Prefer {@link extractUserIdFromRequestHeaders} instead: it is more secure.
 */
export declare function extractUserIdFromCookieAlone(headers: HeaderContainer, jwtParams: Readonly<ParseJwtParams>, cookieName?: string | undefined): Promise<string | undefined>;
/**
 * Used by host (backend) code to set headers on a response object.
 *
 * @category Auth : Host
 */
export declare function generateSuccessfulLoginHeaders(
/** The id from your database of the user you're authenticating. */
userId: string, cookieConfig: Readonly<CookieParams>): Promise<{
    'set-cookie': string;
    "csrf-token": string;
}>;
/**
 * Used by host (backend) code to set headers on a response object when the user has logged out or
 * failed to authorize.
 *
 * @category Auth : Host
 */
export declare function generateLogoutHeaders(...params: Parameters<typeof clearAuthCookie>): {
    '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;