@mpoonuru/paseto/dist/index.d.ts

Modern PASETO (Platform-Agnostic Security Tokens) for Node.js with TypeScript support and V4 LOCAL encryption

import { KeyObject, PrivateKeyInput, JsonWebKeyInput, PublicKeyInput } from 'node:crypto';

/**
 * Options for producing PASETO tokens
 */
interface ProduceOptions {
    /** Implicit assertion for additional authenticated data */
    assertion?: string | Buffer;
    /** Intended audience for the token */
    audience?: string;
    /** Token expiration time (duration string like "1h", "30m", "7d") */
    expiresIn?: string;
    /** Optional footer data */
    footer?: Record<PropertyKey, unknown> | string | Buffer;
    /** Whether to include issued at (iat) claim */
    iat?: boolean;
    /** Token issuer */
    issuer?: string;
    /** Unique token identifier */
    jti?: string;
    /** Key identifier */
    kid?: string;
    /** Not before time (duration string) */
    notBefore?: string;
    /** Current time override for testing */
    now?: Date;
    /** Token subject */
    subject?: string;
}
/**
 * Options for consuming PASETO tokens
 */
interface ConsumeOptions<TComplete extends boolean = false> {
    /** Implicit assertion that must match */
    assertion?: string | Buffer;
    /** Expected audience */
    audience?: string;
    /** Clock tolerance for time-based claims */
    clockTolerance?: string;
    /** Whether to return complete result with metadata */
    complete?: TComplete;
    /** Whether payload should be returned as Buffer */
    buffer?: false;
    /** Ignore expiration claim */
    ignoreExp?: boolean;
    /** Ignore issued at claim */
    ignoreIat?: boolean;
    /** Ignore not before claim */
    ignoreNbf?: boolean;
    /** Expected issuer */
    issuer?: string;
    /** Maximum token age */
    maxTokenAge?: string;
    /** Current time override for testing */
    now?: Date;
    /** Expected subject */
    subject?: string;
}
/**
 * Options for consuming tokens with buffer payload
 */
interface ConsumeOptionsBuffer<TComplete extends boolean = false> {
    /** Implicit assertion that must match */
    assertion?: string | Buffer;
    /** Whether to return complete result with metadata */
    complete?: TComplete;
    /** Whether payload should be returned as Buffer */
    buffer: true;
}
/**
 * Complete result with token metadata
 */
interface CompleteResult<T = Record<string, unknown>> {
    /** Optional footer data */
    footer?: Buffer;
    /** Decoded payload */
    payload: T;
    /** Token purpose (local or public) */
    purpose: 'local' | 'public';
    /** PASETO version */
    version: string;
}
/**
 * Complete result with buffer payload
 */
interface CompleteResultBuffer {
    /** Optional footer data */
    footer?: Buffer;
    /** Raw payload buffer */
    payload: Buffer;
    /** Token purpose (local or public) */
    purpose: 'local' | 'public';
    /** PASETO version */
    version: string;
}
/**
 * Decode result without verification
 */
interface DecodeResult<T = Record<string, unknown>> {
    /** Optional footer data */
    footer?: Buffer;
    /** Decoded payload (if decodable) */
    payload?: T;
    /** Token purpose (local or public) */
    purpose: 'local' | 'public';
    /** PASETO version */
    version: string;
}
/**
 * Decode result with buffer payload
 */
interface DecodeResultBuffer {
    /** Optional footer data */
    footer?: Buffer;
    /** Raw payload buffer (if decodable) */
    payload?: Buffer;
    /** Token purpose (local or public) */
    purpose: 'local' | 'public';
    /** PASETO version */
    version: string;
}
/**
 * Supported key types for cryptographic operations
 */
type CryptoKey = KeyObject | Buffer | string;
type PrivateKey = KeyObject | Buffer | PrivateKeyInput | JsonWebKeyInput | string;
type PublicKey = KeyObject | Buffer | PublicKeyInput | JsonWebKeyInput | string;
type SymmetricKey = KeyObject | Buffer | string;
/**
 * PASETO token purposes
 */
type TokenPurpose = 'local' | 'public';
/**
 * PASETO versions
 */
type PasetoVersion = 'v1' | 'v2' | 'v3' | 'v4';
/**
 * Key generation options
 */
interface KeyGenerationOptions {
    /** Output format for the key */
    format?: 'keyobject' | 'paserk';
}
/**
 * PASERK (PASETO Key) result for asymmetric keys
 */
interface AsymmetricPaserkResult {
    /** Secret key in PASERK format */
    secretKey: string;
    /** Public key in PASERK format */
    publicKey: string;
}
/**
 * KeyObject result for asymmetric keys
 */
interface AsymmetricKeyResult {
    /** Private key as KeyObject for signing */
    privateKey: KeyObject;
    /** Public key as KeyObject for verification */
    publicKey: KeyObject;
}

/**
 * Base PASETO error class
 */
declare class PasetoError extends Error {
    constructor(message: string, options?: ErrorOptions);
}
/**
 * Error thrown when a claim validation fails
 */
declare class PasetoClaimInvalid extends PasetoError {
    constructor(message: string, options?: ErrorOptions);
}
/**
 * Error thrown when decryption fails
 */
declare class PasetoDecryptionFailed extends PasetoError {
    constructor(message?: string, options?: ErrorOptions);
}
/**
 * Error thrown when token format is invalid
 */
declare class PasetoInvalid extends PasetoError {
    constructor(message: string, options?: ErrorOptions);
}
/**
 * Error thrown when operation is not supported
 */
declare class PasetoNotSupported extends PasetoError {
    constructor(message: string, options?: ErrorOptions);
}
/**
 * Error thrown when signature verification fails
 */
declare class PasetoVerificationFailed extends PasetoError {
    constructor(message?: string, options?: ErrorOptions);
}
/**
 * All PASETO error classes
 */
declare const errors: {
    readonly PasetoError: typeof PasetoError;
    readonly PasetoClaimInvalid: typeof PasetoClaimInvalid;
    readonly PasetoDecryptionFailed: typeof PasetoDecryptionFailed;
    readonly PasetoInvalid: typeof PasetoInvalid;
    readonly PasetoNotSupported: typeof PasetoNotSupported;
    readonly PasetoVerificationFailed: typeof PasetoVerificationFailed;
};

/**
 * Options for V4 LOCAL token operations
 */
interface V4LocalOptions extends ProduceOptions {
}
/**
 * Options for V4 PUBLIC token operations
 */
interface V4PublicOptions extends ProduceOptions {
}

/**
 * Encrypt a payload using PASETO v4.local according to specification
 * @param payload - Data to encrypt (object or Buffer)
 * @param key - 256-bit symmetric key
 * @param options - Encryption options
 * @returns Encrypted PASETO token
 */
declare function encrypt(payload: Record<PropertyKey, unknown> | Buffer, key: SymmetricKey, options?: V4LocalOptions): Promise<string>;

/**
 * Decrypt a PASETO v4.local token
 */
declare function decrypt<T = Record<string, unknown>>(token: string, key: SymmetricKey, options?: ConsumeOptions<false>): Promise<T>;
declare function decrypt<T = Record<string, unknown>>(token: string, key: SymmetricKey, options?: ConsumeOptions<true>): Promise<CompleteResult<T>>;
declare function decrypt(token: string, key: SymmetricKey, options?: ConsumeOptionsBuffer<false>): Promise<Buffer>;
declare function decrypt(token: string, key: SymmetricKey, options?: ConsumeOptionsBuffer<true>): Promise<CompleteResultBuffer>;

/**
 * Sign a payload using PASETO v4.public
 * @param payload - Data to sign
 * @param key - Ed25519 private key
 * @param options - Signing options
 * @returns Signed PASETO token
 */
declare function sign(payload: Record<PropertyKey, unknown> | Buffer, key: PrivateKey, options?: V4PublicOptions): Promise<string>;

/**
 * Verify a PASETO v4.public token
 */
declare function verify<T = Record<string, unknown>>(token: string, key: PublicKey, options?: ConsumeOptions<false>): Promise<T>;
declare function verify<T = Record<string, unknown>>(token: string, key: PublicKey, options?: ConsumeOptions<true>): Promise<CompleteResult<T>>;
declare function verify(token: string, key: PublicKey, options?: ConsumeOptionsBuffer<false>): Promise<Buffer>;
declare function verify(token: string, key: PublicKey, options?: ConsumeOptionsBuffer<true>): Promise<CompleteResultBuffer>;

/**
 * Generate a key for PASETO v4 operations
 */
declare function generateKey(purpose: 'local'): Promise<KeyObject>;
declare function generateKey(purpose: 'local', options: {
    format: 'keyobject';
}): Promise<KeyObject>;
declare function generateKey(purpose: 'local', options: {
    format: 'paserk';
}): Promise<string>;
declare function generateKey(purpose: 'public'): Promise<AsymmetricKeyResult>;
declare function generateKey(purpose: 'public', options: {
    format: 'keyobject';
}): Promise<AsymmetricKeyResult>;
declare function generateKey(purpose: 'public', options: {
    format: 'paserk';
}): Promise<AsymmetricPaserkResult>;

/**
 * Pre-Authentication Encoding (PAE) as defined in PASETO specification
 * @param pieces - Array of data to encode (Uint8Array for security)
 * @returns Encoded Uint8Array
 */
declare function pae(...pieces: Uint8Array[]): Uint8Array;
/**
 * Pack PASETO token components securely
 * @param header - Token header string
 * @param footer - Optional footer (Buffer for backward compatibility)
 * @param pieces - Token components to pack (Uint8Array for security)
 * @returns Base64url encoded token
 */
declare function pack(header: string, footer: Buffer, ...pieces: Uint8Array[]): string;
/**
 * Consume/parse PASETO token
 * @param token - Token to parse
 * @param expectedHeader - Expected token header
 * @returns Parsed token components
 */
declare function consume(token: string, expectedHeader: string): {
    raw: Buffer;
    footer: Buffer;
};
/**
 * Timing-safe comparison of two Uint8Arrays (constant-time operation)
 */
declare function timingSafeEqual(a: Uint8Array, b: Uint8Array): boolean;

declare const V4: {
    readonly encrypt: typeof encrypt;
    readonly decrypt: typeof decrypt;
    readonly sign: typeof sign;
    readonly verify: typeof verify;
    readonly generateKey: typeof generateKey;
};
declare function decode(token: string): DecodeResult;

export { type AsymmetricPaserkResult, type CompleteResult, type CompleteResultBuffer, type ConsumeOptions, type ConsumeOptionsBuffer, type CryptoKey, type DecodeResult, type DecodeResultBuffer, type KeyGenerationOptions, PasetoClaimInvalid, PasetoDecryptionFailed, PasetoError, PasetoInvalid, PasetoNotSupported, PasetoVerificationFailed, type PasetoVersion, type PrivateKey, type ProduceOptions, type PublicKey, type SymmetricKey, type TokenPurpose, V4, consume, decode, errors, pack, pae, timingSafeEqual, decrypt as v4Decrypt, encrypt as v4Encrypt, generateKey as v4GenerateKey, sign as v4Sign, verify as v4Verify };