auth-vir/dist/auth.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 FullDate, type UtcTimezone } from 'date-vir';
import { type AuthCookie, type CookieParams } from './cookie.js';
import { type CsrfHeaderNameOption } from './csrf-token.js';
import { type ParseJwtParams } from './jwt/jwt.js';
import { type JwtUserData } from './jwt/user-jwt.js';
/**
 * All possible headers container types supported by {@link extractUserIdFromRequestHeaders}.
 *
 * @category Internal
 */
export type HeaderContainer = Record<string, string[] | undefined | string | number> | Headers;
/**
 * Output from {@link extractUserIdFromRequestHeaders}.
 *
 * @category Internal
 */
export type UserIdResult<UserId extends string | number> = {
    userId: UserId;
    jwtExpiration: FullDate<UtcTimezone>;
    /** When the JWT was issued (`iat` claim). */
    jwtIssuedAt: FullDate<UtcTimezone>;
    cookieName: AuthCookie;
    /** The CSRF token embedded in the JWT. */
    csrfToken: string;
    /**
     * Unix timestamp (in milliseconds) when the session was originally started. Used to enforce max
     * session duration.
     */
    sessionStartedAt: JwtUserData['sessionStartedAt'];
};
/**
 * 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<UserId extends string | number>({ headers, jwtParams, csrfHeaderNameOption, cookieName, cookieNameSuffix, }: Readonly<{
    headers: HeaderContainer;
    jwtParams: Readonly<ParseJwtParams>;
    csrfHeaderNameOption: Readonly<CsrfHeaderNameOption>;
    cookieName: AuthCookie;
    cookieNameSuffix?: string | undefined;
}>): Promise<Readonly<UserIdResult<UserId>> | 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.
 * @category Auth : Host
 */
export declare function insecureExtractUserIdFromCookieAlone<UserId extends string | number>({ headers, jwtParams, cookieName, cookieNameSuffix, }: Readonly<{
    headers: HeaderContainer;
    jwtParams: Readonly<ParseJwtParams>;
    cookieName: AuthCookie;
    cookieNameSuffix?: string | undefined;
}>): Promise<Readonly<UserIdResult<UserId>> | undefined>;
/**
 * Used by host (backend) code to set headers on a response object. Sets both the auth JWT cookie
 * and the CSRF token cookie. The CSRF cookie is not `HttpOnly` so that frontend JavaScript can read
 * it and inject the value as a request header.
 *
 * @category Auth : Host
 */
export declare function generateSuccessfulLoginHeaders(
/** The id from your database of the user you're authenticating. */
userId: string | number, cookieConfig: Readonly<CookieParams>, 
/**
 * The timestamp (in seconds) when the session originally started. If not provided, the current
 * time will be used (for new sessions).
 */
sessionStartedAt?: number | undefined): Promise<Record<string, 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(cookieConfig: Readonly<SelectFrom<CookieParams, {
    hostOrigin: true;
    isDev: true;
}>> & PartialWithUndefined<{
    cookieNameSuffix: string;
}>, options?: Readonly<PartialWithUndefined<{
    /**
     * When `true`, the CSRF cookie is preserved (not cleared). Use this when clearing only
     * one cookie type (e.g., the auth cookie) while keeping the other active session (e.g.,
     * sign-up) that still needs its CSRF token.
     */
    preserveCsrf: boolean;
}>>): Record<string, string[]>;