shelving/util/jwt.d.ts

Toolkit for using data in JavaScript.

import { type Bytes, type PossibleBytes } from "./bytes.js";
import type { Data } from "./data.js";
import { type PossibleDate } from "./date.js";
import type { AnyCaller } from "./function.js";
export interface TokenClaims extends Data {
    /**
     * "Issued at" date (defaults to "now").
     * - Not used for validation, but always set in the token payload.
     * - Can be used to determine when the token was issued, and possibly revoke tokens issued before a certain date.
     */
    readonly iat?: PossibleDate;
    /**
     * "Not before" date.
     * - When validating the token, tokens before this date will be rejected
     */
    readonly nbf?: PossibleDate;
    /**
     * Expiry in milliseconds (defaults to "30 days").
     * - When validating the token, tokens after this date will be rejected
     */
    readonly exp?: number;
}
/**
 * Encode a JWT and return the string token.
 * - Currently only supports HMAC SHA-512 signing.
 *
 * @param claims The payload claims to include in the JWT.
 * @param secret The secret key to sign the JWT with.
 * @param expiry The expiry time in milliseconds (defaults to 30 days).
 *
 * @throws ValueError If the input parameters, e.g. `secret` or `issuer`, are invalid.
 */
export declare function encodeToken({ nbf, iat, exp, ...claims }: TokenClaims, secret: PossibleBytes): Promise<string>;
/** Parts that make up a JSON Web Token. */
export type TokenData = {
    header: string;
    payload: string;
    signature: string;
    headerData: Data;
    payloadData: Data;
    signatureBytes: Bytes;
};
/**
 * Split a JSON Web Token into its header, payload, and signature, and decode and parse the JSON.
 */
export declare function splitToken(token: string, caller?: AnyCaller): TokenData;
/**
 * Decode a JWT, verify it, and return the full payload data.
 * - Currently only supports HMAC SHA-512 signing.
 *
 * @throws ValueError If the input parameters, e.g. `secret` or `issuer`, are invalid.
 * @throws UnauthorizedError If the token is invalid or malformed.
 * @throws UnauthorizedError If the token signature is incorrect, token is expired or not issued yet.
 */
export declare function verifyToken(token: string, secret: PossibleBytes, caller?: AnyCaller): Promise<Data>;
/**
 * Set the `Authorization: Bearer {token}` on a `Request` object (by reference).
 *
 * @param request The `Request` object to set the token on.
 * @returns The same `Request` object that was passed in.
 */
export declare function setRequestToken(request: Request, token: string): Request;
/**
 * Extract the `Authorization: Bearer {token}` from a `Request` object, or return `undefined` if not set.
 *
 * @param request The `Request` object possibly containing an `Authorization: Bearer {token}` header to extract the token from.
 * @returns The string token extracted from the `Authorization` header, or `undefined` if not set.
 */
export declare function getRequestToken(request: Request): string | undefined;
/**
 * Extract the `Authorization: Bearer {token}` from a `Request` object, or throw `UnauthorizedError` if not set or malformed.
 *
 * @param request The `Request` object containing an `Authorization: Bearer {token}` header to extract the token from.
 * @returns The string token extracted from the `Authorization` header.
 * @throws UnauthorizedError If the `Authorization` header is not set, or the JWT it contains is not well-formed.
 */
export declare function requireRequestToken(request: Request, caller?: AnyCaller): string;
/**
 * Extract the `Authorization: Bearer {token}` from a `Request` object and verify it using a signature, or throw `UnauthorizedError` if not set, malformed, or invalid.
 * - Same as doing `requireRequestToken(request)` and then `verifyToken(token, secret)`.
 *
 * @param request The `Request` object containing an `Authorization: Bearer {token}` header to extract the token from.
 * @param secret The secret key to verify the JWT signature with.
 *
 * @returns The decoded payload data from the JWT.
 * @throws UnauthorizedError If the `Authorization` header is not set, the JWT it contains is not well-formed, or the JWT signature is invalid.
 *
 * @example `const { sub, iss, customClaim } = await verifyRequestToken(request, secret);`
 */
export declare function verifyRequestToken(request: Request, secret: PossibleBytes, caller?: AnyCaller): Promise<Data>;