jwt-smith/dist/index.d.mts

Enhanced JWT Authentication and Authorization Module

import { CookieOptions, Request, Response, NextFunction } from 'express';
import { KeyObject, PrivateKeyInput, JsonWebKeyInput, PublicKeyInput } from 'node:crypto';
import { Jwt, JwtPayload, JwtHeader } from 'jsonwebtoken';

interface Logger {
	info: (message: string, ...args: unknown[]) => void;
	warn: (message: string, ...args: unknown[]) => void;
	error: (message: string, ...args: unknown[]) => void;
	debug: (message: string, ...args: unknown[]) => void;
}

type Secret = string | Buffer | KeyObject | { key: string | Buffer; passphrase: string };

type Algorithm =
	| 'HS256'
	| 'RS256'
	| 'HS384'
	| 'HS512'
	| 'RS384'
	| 'RS512'
	| 'ES256'
	| 'ES384'
	| 'ES512'
	| 'PS256'
	| 'PS384'
	| 'PS512'
	| 'none';

type PrivateKey = PrivateKeyInput | string | Buffer | JsonWebKeyInput;

type PublicKey = PublicKeyInput | string | Buffer | KeyObject | JsonWebKeyInput;

type VerifyResponse = string | Jwt | JwtPayload | undefined;

type AppendToRequestProperties = 'user' | 'role' | 'language' | 'tokenPayload';

type AppendToRequest = AppendToRequestProperties[] | true;

interface AuthUser {
	id?: string | number;
	role?: string;
	[key: string]: unknown;
}

type TokenGenerationHandler = (
	refreshTokenPayload: VerifyResponse,
	tokenHolder: Record<string, unknown>,
) => Promise<{ token: string; refreshToken: string }>;

type RefreshTokenPayloadVerifier = (refreshTokenPayload: VerifyResponse) => Promise<void>;

type AuthTokenPayloadVerifier = (tokenPayload: VerifyResponse) => Promise<void>;

type RefreshTokenHolderVerifier = (
	tokenHolder: Record<string, unknown>,
	refreshTokenPayload: VerifyResponse,
) => Promise<boolean>;

type ExtractApiVersion = (request: AuthedRequest) => Promise<string | undefined>;

interface SignTokenOptions {
	algorithm?: Algorithm | undefined;
	keyid?: string | undefined;
	expiresIn?: string | number;
	notBefore?: string | number | undefined;
	audience?: string | string[] | undefined;
	subject?: string | undefined;
	issuer?: string | undefined;
	jwtid?: string | undefined;
	mutatePayload?: boolean | undefined;
	noTimestamp?: boolean | undefined;
	header?: JwtHeader | undefined;
	encoding?: string | undefined;
	allowInsecureKeySizes?: boolean | undefined;
	allowInvalidAsymmetricKeyTypes?: boolean | undefined;
}

interface VerifyTokenOptions {
	algorithms?: Algorithm[] | undefined;
	audience?: string | RegExp | (string | RegExp)[] | undefined;
	clockTimestamp?: number | undefined;
	clockTolerance?: number | undefined;
	complete?: boolean | undefined;
	issuer?: string | string[] | undefined;
	ignoreExpiration?: boolean | undefined;
	ignoreNotBefore?: boolean | undefined;
	jwtid?: string | undefined;
	nonce?: string | undefined;
	subject?: string | undefined;
	maxAge?: string | number | undefined;
	allowInvalidAsymmetricKeyTypes?: boolean | undefined;
}

interface TokenStorage {
	getToken?: (userId: string) => Promise<string | string[] | null>;
	getRefreshToken: (userId: string) => Promise<string | string[] | null>;
	getRefreshTokenHolder: (refreshToken: string) => Promise<Record<string, unknown> | null>;
	saveOrUpdateToken: (userId: string, refreshToken: string, token?: string) => Promise<void>;
	deleteToken: (userId: string, token?: string, refreshToken?: string) => Promise<void>;
	blackListRefreshToken: (token: string, relatedData?: Record<string, unknown>) => Promise<void>;
	checkBlackListedRefreshToken: (token: string) => Promise<Record<string, unknown> | undefined>;
}

interface CookieSettings {
	accessTokenCookieName?: string;
	accessCookieOptions?: CookieOptions;
	refreshTokenCookieName?: string;
	refreshCookieOptions?: CookieOptions;
}

interface RequestAppends {
	user?: AuthUser;
	role?: string;
	language?: string | string[];
	tokenPayload?: Record<string, unknown> | unknown | undefined;
}

type AuthedRequest = RequestAppends & Request;

interface MiddlewareConfigsOptions {
	/**
	 * Token storage instance.
	 * If not provided, the library will use the default token storage.
	 * The user can provide their own token storage instance.
	 * The library will use the provided token storage instance.
	 * The token storage instance should implement the TokenStorage interface.
	 * The token storage instance should have the following methods:
	 * - getToken
	 * - getRefreshToken
	 * - getRefreshTokenHolder
	 * - saveOrUpdateToken
	 * - deleteToken
	 * - blackListRefreshToken
	 * - checkBlackListedRefreshToken
	 *
	 * @type {TokenStorage}
	 * @memberof ConfigOptions
	 */
	tokenStorage?: TokenStorage;
	authHeaderName?: string;
	refreshTokenHeaderName?: string;
	appendToRequest?: AppendToRequest;
	cookieSettings?: CookieSettings;
	authTokenExtractor?: (header: string) => string | undefined;
	tokenGenerationHandler: TokenGenerationHandler;
	authTokenPayloadVerifier?: AuthTokenPayloadVerifier;
	refreshTokenPayloadVerifier?: RefreshTokenPayloadVerifier;
	refreshTokenHolderVerifier?: RefreshTokenHolderVerifier;
	extractApiVersion?: ExtractApiVersion;
}

interface ConfigOptions {
    logger?: Logger;
    publicKey?: Secret | PublicKey;
    refreshTokenKey?: Secret | PublicKey;
    signOptions?: SignTokenOptions;
    verifyOptions?: VerifyTokenOptions;
    middlewareConfigs?: MiddlewareConfigsOptions;
}
declare const JwtManager: (options: ConfigOptions) => void;

interface SignTokenParams {
    payload: string | Buffer | object;
    secret: Secret | PrivateKey;
    options?: SignTokenOptions;
}
declare const sign: (parameters: SignTokenParams) => Promise<string | undefined>;
declare const setDefaultSignOptions: (options: SignTokenOptions) => void;

interface VerifyTokenParams {
    token: string;
    secret: Secret | PublicKey;
    options?: VerifyTokenOptions;
}
declare const verify: (parameters: VerifyTokenParams) => Promise<VerifyResponse>;
declare const setDefaultVerifyOptions: (options: VerifyTokenOptions) => void;

declare const validateJwtHeaderMiddleware: (req: AuthedRequest, res: Response, next: NextFunction) => Promise<void>;

declare const roleBasedAuthenticationMiddleware: (requiredAction: string) => (req: AuthedRequest, res: Response, next: NextFunction) => Promise<void>;

declare const validateJwtCookieMiddleware: (req: Request, res: Response, next: NextFunction) => Promise<void>;

export { type Algorithm, type AppendToRequest, type AppendToRequestProperties, type AuthTokenPayloadVerifier, type AuthUser, type AuthedRequest, type CookieSettings, type ExtractApiVersion, JwtManager, type Logger, type MiddlewareConfigsOptions, type PrivateKey, type PublicKey, type RefreshTokenHolderVerifier, type RefreshTokenPayloadVerifier, type RequestAppends, type Secret, type SignTokenOptions, type TokenGenerationHandler, type TokenStorage, type VerifyResponse, type VerifyTokenOptions, roleBasedAuthenticationMiddleware, setDefaultSignOptions, setDefaultVerifyOptions, sign, validateJwtCookieMiddleware, validateJwtHeaderMiddleware, verify };