auth-vir/dist/jwt.d.ts

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

import { type AnyObject, type PartialWithUndefined } from '@augment-vir/common';
import { type AnyDuration, type DateLike } from 'date-vir';
import { type JwtKeys } from './jwt-keys.js';
/**
 * Params for {@link createJwt}.
 *
 * @category Internal
 */
export type CreateJwtParams = Readonly<{
    /**
     * The keys required to sign and encrypt the JWT.
     *
     * These keys should be kept secret and never shared with any frontend, client, etc.
     */
    jwtKeys: Readonly<JwtKeys>;
    /**
     * The name of the company, the name of the service, or the URL to the service that originally
     * issued the JWT. The same value must be used when creating and parsing a JWT or the parse will
     * fail.
     *
     * This name can be anything you want.
     *
     * @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.1
     */
    issuer: string;
    /**
     * The arbitrary name or URL of the client intended to consume the JWT. The host and client must
     * both know this name in order for the token to be signed and read correctly.
     *
     * This name can be anything you want.
     *
     * @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.3
     */
    audience: string;
    /**
     * The duration until the JWT expires.
     *
     * @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.4
     */
    jwtDuration: Readonly<AnyDuration>;
}> & Readonly<PartialWithUndefined<{
    /**
     * Set a custom issued at date.
     *
     * This should usually not be overridden.
     *
     * @default Date.now()
     * @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.6
     */
    issuedAt: DateLike;
    /**
     * Set a custom date for when the JWT will become valid. The JWT will be considered
     * invalid and not be processed until this date.
     *
     * This should usually not be overridden.
     *
     * @default
     * none, the JWT will be immediately valid
     * @see https://datatracker.ietf.org/doc/html/rfc7519#section-4.1.5
     */
    notValidUntil: DateLike;
}>>;
/**
 * Creates a signed and encrypted JWT that contains the given data.
 *
 * @category Internal
 */
export declare function createJwt<JwtData extends AnyObject = AnyObject>(
/** The data to be included in the JWT. */
data: JwtData, params: Readonly<CreateJwtParams>): Promise<string>;
/**
 * Params for {@link parseJwt}.
 *
 * @category Internal
 */
export type ParseJwtParams = Readonly<Pick<CreateJwtParams, 'issuer' | 'audience' | 'jwtKeys'>>;
/**
 * Parse and extract all data from an encrypted and signed JWT.
 *
 * @category Internal
 * @throws Errors if the decryption, signature verification, or other JWT requirements fail
 */
export declare function parseJwt<JwtData extends AnyObject = AnyObject>(encryptedJwt: string, params: Readonly<ParseJwtParams>): Promise<JwtData>;