auth-vir/dist/cookie.d.ts

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

import { type PartialWithUndefined, type SelectFrom } from '@augment-vir/common';
import { type AnyDuration } from 'date-vir';
import { type Primitive } from 'type-fest';
import { type CreateJwtParams, type ParseJwtParams, type ParsedJwt } from './jwt/jwt.js';
import { type JwtUserData } from './jwt/user-jwt.js';
/**
 * Cookie header names supported by default.
 *
 * @category Internal
 */
export declare enum AuthCookie {
    /** Used for a full user login auth. */
    Auth = "auth",
    /** Use for a temporary "just signed up" auth. */
    SignUp = "sign-up",
    /** Used for storing the CSRF token. Not `HttpOnly` so that frontend JS can read it. */
    Csrf = "auth-vir-csrf"
}
/**
 * Resolves a cookie name by appending a suffix when provided. When `cookieNameSuffix` is
 * `undefined`, the base name is returned unchanged.
 *
 * @category Internal
 */
export declare function resolveCookieName(baseCookieName: AuthCookie, cookieNameSuffix?: string | undefined): string;
/**
 * Parameters for {@link generateAuthCookie}.
 *
 * @category Internal
 */
export type CookieParams = {
    /**
     * The origin of the host (backend) service that cookies will be included in all requests to.
     * This should be restricted to just your host (backend) origin for security purposes.
     *
     * @example 'https://www.example.com'
     */
    hostOrigin: string;
    /**
     * The max duration of this cookie. Or, in other words, the max user session duration before
     * they're logged out.
     */
    cookieDuration: AnyDuration;
    /**
     * All JWT parameters required for generating the encrypted JWT that will be embedded in the
     * Cookie. Note that all JWT keys contained herein should never shared with any frontend,
     * client, etc.
     */
    jwtParams: Readonly<CreateJwtParams>;
} & PartialWithUndefined<{
    /**
     * Which auth cookie name to use.
     *
     * @default AuthCookie.Auth
     */
    authCookie: AuthCookie;
    /**
     * Is set to `true` (which should only be done in development environments), the cookie will be
     * allowed in insecure requests (non HTTPS requests).
     *
     * @default false
     */
    isDev: boolean;
    /**
     * Optional suffix appended to cookie names (e.g., `'staging'` produces `auth-staging`). When
     * `undefined`, cookie names are unchanged. Useful for running multiple environments on the same
     * domain without cookie collisions.
     */
    cookieNameSuffix: string;
}>;
/**
 * Generate a secure cookie that stores the user JWT data. Used in host (backend) code.
 *
 * @category Internal
 */
export declare function generateAuthCookie(userJwtData: Readonly<JwtUserData>, cookieConfig: Readonly<CookieParams>): Promise<string>;
/**
 * Generate a CSRF token cookie. This cookie is intentionally not `HttpOnly` so that frontend
 * JavaScript can read it and inject the value as a request header for double-submit verification.
 *
 * The CSRF cookie uses a fixed 400-day MAX-AGE rather than matching the auth cookie duration. 400
 * days is the cross-browser safe maximum (Chrome caps cookie lifetimes at 400 days; other browsers
 * accept it as-is). The CSRF token is only meaningful when paired with a valid JWT, so it doesn't
 * need its own expiration management. It gets regenerated on every fresh login.
 *
 * @category Internal
 */
export declare function generateCsrfCookie(csrfToken: string, cookieConfig: Readonly<SelectFrom<CookieParams, {
    hostOrigin: true;
    isDev: true;
}>> & PartialWithUndefined<{
    cookieNameSuffix: string;
}>): string;
/**
 * Generate a cookie value that will clear the previous auth cookie. Use this when signing out.
 *
 * @category Internal
 */
export declare function clearAuthCookie(cookieConfig: Readonly<SelectFrom<CookieParams, {
    hostOrigin: true;
    isDev: true;
}>> & PartialWithUndefined<{
    authCookie: AuthCookie;
    cookieNameSuffix: string;
}>): string;
/**
 * Generate a cookie value that will clear the CSRF token cookie. Use this when signing out.
 *
 * @category Internal
 */
export declare function clearCsrfCookie(cookieConfig: Readonly<SelectFrom<CookieParams, {
    hostOrigin: true;
    isDev: true;
}>> & PartialWithUndefined<{
    cookieNameSuffix: string;
}>): string;
/**
 * Generate a cookie string from a raw set of parameters.
 *
 * @category Internal
 */
export declare function generateCookie(params: Readonly<Record<string, Exclude<Primitive, symbol>>>): string;
/**
 * Extract an auth cookie from a cookie string. Used in host (backend) code.
 *
 * @category Internal
 * @returns The extracted auth Cookie JWT data or `undefined` if no valid auth JWT data was found.
 */
export declare function extractCookieJwt({ rawCookie, jwtParams, cookieName, cookieNameSuffix, }: {
    rawCookie: string;
    jwtParams: Readonly<ParseJwtParams>;
    cookieName: AuthCookie;
} & PartialWithUndefined<{
    cookieNameSuffix: string;
}>): Promise<undefined | ParsedJwt<JwtUserData>>;