@catbee/utils/build/src/utils/crypto.utils.d.ts

A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.

import { BinaryToTextEncoding, CipherGCMTypes } from "crypto";
export type BufferEncoding = "ascii" | "utf8" | "utf-8" | "utf16le" | "utf-16le" | "ucs2" | "ucs-2" | "base64" | "base64url" | "latin1" | "binary" | "hex";
/**
 * Generates an HMAC digest using the specified algorithm and secret key.
 *
 * @param {string} algorithm - The hashing algorithm (e.g., 'sha256', 'sha1').
 * @param {string} input - The string to hash.
 * @param {string} secret - The secret key for HMAC.
 * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding ('hex', 'base64', etc).
 * @returns {string} HMAC digest as a string.
 */
export declare function hmac(algorithm: string, input: string, secret: string, encoding?: BinaryToTextEncoding): string;
/**
 * Generates a hash digest using the specified algorithm.
 *
 * @param {string} algorithm - The hashing algorithm (e.g., 'sha256', 'md5').
 * @param {string} input - The string to hash.
 * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding ('hex', 'base64', etc).
 * @returns {string} Hash digest as a string.
 */
export declare function hash(algorithm: string, input: string, encoding?: BinaryToTextEncoding): string;
/**
 * Generates an HMAC-SHA256 digest.
 *
 * @param {string} input - The string to hash.
 * @param {string} secret - The secret key.
 * @returns {string} SHA-256 HMAC digest as a string.
 */
export declare function sha256Hmac(input: string, secret: string): string;
/**
 * Generates a SHA1 hash digest.
 *
 * @param {string} input - The string to hash.
 * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
 * @returns {string} SHA-1 hash as a string.
 */
export declare function sha1(input: string, encoding?: BinaryToTextEncoding): string;
/**
 * Generates a SHA256 hash digest.
 *
 * @param {string} input - The string to hash.
 * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
 * @returns {string} SHA-256 hash as a string.
 */
export declare function sha256(input: string, encoding?: BinaryToTextEncoding): string;
/**
 * Generates an MD5 hash digest.
 *
 * @param {string} input - The string to hash.
 * @returns {string} MD5 hash as a string.
 */
export declare function md5(input: string): string;
/**
 * Generates a cryptographically strong random string by hashing a random UUID with SHA-256.
 *
 * @returns {string} Random string hashed with SHA-256 (hex encoding).
 */
export declare function randomString(): string;
/**
 * Generates a secure random buffer of specified byte length.
 *
 * @param {number} [byteLength=32] - Number of random bytes to generate.
 * @returns {Buffer} Buffer containing random bytes.
 */
export declare function generateRandomBytes(byteLength?: number): Buffer;
/**
 * Generates a secure random string of specified byte length with specified encoding.
 *
 * @param {number} [byteLength=32] - Number of random bytes to generate.
 * @param {BinaryToTextEncoding} [encoding='hex'] - Output encoding.
 * @returns {string} Random string in specified encoding.
 */
export declare function generateRandomBytesAsString(byteLength?: number, encoding?: BinaryToTextEncoding): string;
/**
 * Generates a secure API key with a specified format.
 *
 * @param {string} [prefix=''] - Optional prefix for the key.
 * @param {number} [byteLength=24] - Number of random bytes to generate.
 * @returns {string} Formatted API key.
 */
export declare function generateApiKey(prefix?: string, byteLength?: number): string;
/**
 * Compares two strings, arrays, or buffers in constant time to prevent timing attacks.
 *
 * @param {string | Buffer | Uint8Array} a - First value to compare
 * @param {string | Buffer | Uint8Array} b - Second value to compare
 * @returns {boolean} True if values are equal
 */
export declare function safeCompare(a: string | Buffer | Uint8Array, b: string | Buffer | Uint8Array): boolean;
/**
 * Interface for encryption options
 */
export interface EncryptionOptions {
    /** Algorithm to use (default: aes-256-gcm) */
    algorithm?: CipherGCMTypes;
    /** Input encoding for plaintext if string (default: utf8) */
    inputEncoding?: BufferEncoding;
    /** Output encoding for ciphertext (default: hex) */
    outputEncoding?: BinaryToTextEncoding;
}
/**
 * Interface for decryption options
 */
export interface DecryptionOptions {
    /** Algorithm to use (default: aes-256-gcm) */
    algorithm?: CipherGCMTypes;
    /** Input encoding for ciphertext if string (default: hex) */
    inputEncoding?: BinaryToTextEncoding;
    /** Output encoding for plaintext (default: utf8) */
    outputEncoding?: BufferEncoding;
}
/**
 * Result of encryption operation including all data needed for decryption
 */
export interface EncryptionResult {
    /** Encrypted data (string or Buffer based on options) */
    ciphertext: string | Buffer;
    /** Initialization vector */
    iv: Buffer;
    /** Authentication tag (for GCM mode) */
    authTag?: Buffer;
    /** Algorithm used */
    algorithm: string;
}
/**
 * Encrypts data using a symmetric key with secure defaults (AES-256-GCM).
 *
 * @param {string | Buffer} data - Data to encrypt
 * @param {string | Buffer} key - Encryption key or passphrase
 * @param {EncryptionOptions} [options] - Encryption options
 * @returns {Promise<EncryptionResult>} Encrypted data with metadata
 */
export declare function encrypt(data: string | Buffer, key: string | Buffer, options?: EncryptionOptions): Promise<EncryptionResult>;
/**
 * Decrypts data that was encrypted with the encrypt function.
 *
 * @param {EncryptionResult} encryptedData - The encrypted data and metadata
 * @param {string | Buffer} key - Decryption key or passphrase
 * @param {DecryptionOptions} [options] - Decryption options
 * @returns {Promise<string | Buffer>} Decrypted data
 */
export declare function decrypt(encryptedData: EncryptionResult, key: string | Buffer, options?: DecryptionOptions): Promise<string | Buffer>;
/**
 * Creates a signed token with an expiration time and payload.
 *
 * @param {object} payload - Data to include in the token
 * @param {string} secret - Secret key for signing
 * @param {number} [expiresInSeconds=3600] - Token expiration in seconds
 * @returns {string} Signed token string
 */
export declare function createSignedToken(payload: Record<string, any>, secret: string, expiresInSeconds?: number): string;
/**
 * Verifies and decodes a signed token.
 *
 * @param {string} token - The token to verify
 * @param {string} secret - Secret key for verification
 * @returns {object | null} Decoded payload if valid, null if invalid
 */
export declare function verifySignedToken(token: string, secret: string): Record<string, any> | null;
//# sourceMappingURL=crypto.utils.d.ts.map