@catbee/utils 0.0.8-rc.3 → 1.0.1

package/build/esm/utils/crypto.utils.js

@@ -1,278 +0,0 @@
-/*
- * The MIT License
- *
- * Copyright (c) 2025 Catbee Technologies. https://catbee-utils.npm.hprasath.com/license
- *
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- *
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- *
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- */
-import { createHmac, createHash, randomBytes, createCipheriv, createDecipheriv, scrypt, timingSafeEqual } from 'crypto';
-import { promisify } from 'util';
-import { uuid } from './id.utils';
-/**
- * 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 function hmac(algorithm, input, secret, encoding = 'hex') {
-    return createHmac(algorithm, secret).update(input).digest(encoding);
-}
-/**
- * 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 function hash(algorithm, input, encoding = 'hex') {
-    return createHash(algorithm).update(input).digest(encoding);
-}
-/**
- * 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 function sha256Hmac(input, secret) {
-    return hmac('sha256', input, secret);
-}
-/**
- * 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 function sha1(input, encoding = 'hex') {
-    return hash('sha1', input, encoding);
-}
-/**
- * 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 function sha256(input, encoding = 'hex') {
-    return hash('sha256', input, encoding);
-}
-/**
- * Generates an MD5 hash digest.
- *
- * @param {string} input - The string to hash.
- * @returns {string} MD5 hash as a string.
- */
-export function md5(input) {
-    return hash('md5', input);
-}
-/**
- * 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 function randomString() {
-    return sha256(uuid());
-}
-/**
- * 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 function generateRandomBytes(byteLength = 32) {
-    return randomBytes(byteLength);
-}
-/**
- * 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 function generateRandomBytesAsString(byteLength = 32, encoding = 'hex') {
-    return randomBytes(byteLength).toString(encoding);
-}
-/**
- * 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 function generateApiKey(prefix = '', byteLength = 24) {
-    const randomString = generateRandomBytesAsString(byteLength, 'base64');
-    const key = randomString
-        .replace(/[+/=]/g, '') // Remove non-URL-safe characters
-        .substring(0, 32); // Limit length
-    return prefix ? `${prefix}_${key}` : key;
-}
-/**
- * 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 function safeCompare(a, b) {
-    if (typeof a === 'string' && typeof b === 'string') {
-        // Convert strings to buffers
-        const bufA = Buffer.from(a);
-        const bufB = Buffer.from(b);
-        // Compare lengths first (not constant time, but prevents timing attack on contents)
-        if (bufA.length !== bufB.length)
-            return false;
-        return timingSafeEqual(bufA, bufB);
-    }
-    else if ((a instanceof Buffer || a instanceof Uint8Array) && (b instanceof Buffer || b instanceof Uint8Array)) {
-        // Compare lengths first
-        if (a.length !== b.length)
-            return false;
-        return timingSafeEqual(a instanceof Buffer ? a : Buffer.from(a), b instanceof Buffer ? b : Buffer.from(b));
-    }
-    throw new Error('Cannot compare: inputs must be strings, Buffers, or Uint8Arrays');
-}
-// Promisified version of scrypt for key derivation
-const scryptAsync = promisify(scrypt);
-/**
- * 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 async function encrypt(data, key, options = {}) {
-    const algorithm = options.algorithm || 'aes-256-gcm';
-    const inputEncoding = options.inputEncoding || 'utf8';
-    const outputEncoding = options.outputEncoding || 'hex';
-    // Generate a random IV
-    const iv = randomBytes(16);
-    // Derive key using scrypt if key is a string (passphrase)
-    const derivedKey = typeof key === 'string' ? await scryptAsync(key, iv.slice(0, 8), 32) : key;
-    // Create cipher
-    const cipher = createCipheriv(algorithm, derivedKey, iv);
-    // Encrypt the data
-    let ciphertext;
-    if (typeof data === 'string') {
-        ciphertext = cipher.update(data, inputEncoding, outputEncoding);
-        ciphertext += cipher.final(outputEncoding);
-    }
-    else {
-        const encrypted = Buffer.concat([cipher.update(data), cipher.final()]);
-        ciphertext = outputEncoding ? encrypted.toString(outputEncoding) : encrypted;
-    }
-    // Get authentication tag if using GCM mode
-    const authTag = algorithm.includes('gcm') ? cipher.getAuthTag() : undefined;
-    return {
-        ciphertext,
-        iv,
-        authTag,
-        algorithm
-    };
-}
-/**
- * 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 async function decrypt(encryptedData, key, options = {}) {
-    const algorithm = options.algorithm || encryptedData.algorithm || 'aes-256-gcm';
-    const inputEncoding = options.inputEncoding || 'hex';
-    const outputEncoding = options.outputEncoding || 'utf8';
-    // Derive key using scrypt if key is a string (passphrase)
-    const derivedKey = typeof key === 'string' ? await scryptAsync(key, encryptedData.iv.slice(0, 8), 32) : key;
-    // Create decipher
-    const decipher = createDecipheriv(algorithm, derivedKey, encryptedData.iv);
-    // Set auth tag if using GCM mode
-    if (encryptedData.authTag && algorithm.includes('gcm')) {
-        decipher.setAuthTag(encryptedData.authTag);
-    }
-    // Decrypt the data
-    let decrypted;
-    if (typeof encryptedData.ciphertext === 'string') {
-        decrypted = decipher.update(encryptedData.ciphertext, inputEncoding, outputEncoding);
-        decrypted += decipher.final(outputEncoding);
-    }
-    else {
-        const result = Buffer.concat([decipher.update(encryptedData.ciphertext), decipher.final()]);
-        decrypted = outputEncoding ? result.toString(outputEncoding) : result;
-    }
-    return decrypted;
-}
-/**
- * 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 function createSignedToken(payload, secret, expiresInSeconds = 3600) {
-    // Create payload with expiration
-    const tokenPayload = {
-        ...payload,
-        exp: Math.floor(Date.now() / 1000) + expiresInSeconds
-    };
-    // Convert to string
-    const payloadStr = JSON.stringify(tokenPayload);
-    // Base64 encode the payload
-    const base64Payload = Buffer.from(payloadStr).toString('base64url');
-    // Create signature
-    const signature = hmac('sha256', base64Payload, secret, 'base64url');
-    // Combine payload and signature
-    return `${base64Payload}.${signature}`;
-}
-/**
- * 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 function verifySignedToken(token, secret) {
-    try {
-        // Split token into parts
-        const [payloadB64, signature] = token.split('.');
-        if (!payloadB64 || !signature)
-            return null;
-        // Verify signature
-        const expectedSignature = hmac('sha256', payloadB64, secret, 'base64url');
-        if (!safeCompare(signature, expectedSignature))
-            return null;
-        // Decode payload
-        const payloadStr = Buffer.from(payloadB64, 'base64url').toString('utf8');
-        const payload = JSON.parse(payloadStr);
-        // Check expiration
-        if (payload.exp && payload.exp < Math.floor(Date.now() / 1000)) {
-            return null;
-        }
-        return payload;
-    }
-    catch {
-        return null;
-    }
-}

package/build/esm/utils/date.utils.d.ts

@@ -1,158 +0,0 @@
-/**
- * Format options for the formatDate function
- */
-export interface DateFormatOptions {
-    /** Date format pattern (default: 'yyyy-MM-dd') */
-    format?: string;
-    /** Locale to use for formatting (default: system locale) */
-    locale?: string | string[];
-    /** Time zone to use (default: system time zone) */
-    timeZone?: string;
-}
-/**
- * Format a date according to the specified format pattern.
- *
- * @param date - Date to format
- * @param options - Formatting options
- * @returns Formatted date string
- *
- * @example
- * ```typescript
- * // Format as ISO date
- * formatDate(new Date(), { format: 'yyyy-MM-dd' }); // '2023-05-15'
- *
- * // Format with time
- * formatDate(new Date(), { format: 'yyyy-MM-dd HH:mm:ss' }); // '2023-05-15 14:30:22'
- *
- * // Format with locale
- * formatDate(new Date(), { format: 'PPPP', locale: 'fr-FR' }); // 'lundi 15 mai 2023'
- * ```
- */
-export declare function formatDate(date: Date | number, options?: DateFormatOptions): string;
-/**
- * Format a date as relative time (e.g., "5 minutes ago", "in 3 days").
- *
- * @param date - Date to format
- * @param now - Reference date (default: current time)
- * @param locale - Locale to use for formatting
- * @returns Formatted relative time string
- */
-export declare function formatRelativeTime(date: Date | number, now?: Date | number, locale?: string | string[]): string;
-/**
- * Parse a date string or timestamp into a Date object.
- *
- * @param input - Date string or timestamp to parse
- * @param fallback - Fallback date if parsing fails
- * @returns Parsed Date object or fallback
- *
- * @example
- * ```typescript
- * parseDate('2023-05-15'); // Date object for May 15, 2023
- * parseDate('invalid', new Date()); // Returns current date as fallback
- * ```
- */
-export declare function parseDate(input: string | number, fallback?: Date): Date | null;
-/**
- * Calculate the difference between two dates in the specified unit.
- *
- * @param date1 - First date
- * @param date2 - Second date (default: current time)
- * @param unit - Unit of time for the difference
- * @returns Difference in the specified unit
- *
- * @example
- * ```typescript
- * // Get difference in days
- * dateDiff(new Date('2023-05-15'), new Date('2023-05-10'), 'days'); // 5
- *
- * // Get difference in hours
- * dateDiff(new Date('2023-05-15T10:00:00'), new Date('2023-05-15T06:00:00'), 'hours'); // 4
- * ```
- */
-export declare function dateDiff(date1: Date | number, date2?: Date | number, unit?: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years'): number;
-/**
- * Add a specified amount of time to a date.
- *
- * @param date - Base date
- * @param amount - Amount to add (can be negative)
- * @param unit - Unit of time to add
- * @returns New date with the addition
- *
- * @example
- * ```typescript
- * // Add 5 days
- * addToDate(new Date('2023-05-15'), 5, 'days'); // Date for May 20, 2023
- *
- * // Subtract 2 hours
- * addToDate(new Date('2023-05-15T10:00:00'), -2, 'hours'); // Date for May 15, 2023 08:00:00
- * ```
- */
-export declare function addToDate(date: Date | number, amount: number, unit: 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'months' | 'years'): Date;
-/**
- * Get the start of a time period containing the specified date.
- *
- * @param date - Date to get the start from
- * @param unit - Time unit
- * @returns Date object representing the start of the time unit
- *
- * @example
- * ```typescript
- * // Get start of day (midnight)
- * startOf(new Date('2023-05-15T14:30:00'), 'day'); // Date for May 15, 2023 00:00:00
- *
- * // Get start of month
- * startOf(new Date('2023-05-15'), 'month'); // Date for May 1, 2023
- * ```
- */
-export declare function startOf(date: Date | number, unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'): Date;
-/**
- * Get the end of a time period containing the specified date.
- *
- * @param date - Date to get the end from
- * @param unit - Time unit
- * @returns Date object representing the end of the time unit
- *
- * @example
- * ```typescript
- * // Get end of day (23:59:59.999)
- * endOf(new Date('2023-05-15T14:30:00'), 'day'); // Date for May 15, 2023 23:59:59.999
- *
- * // Get end of month
- * endOf(new Date('2023-05-15'), 'month'); // Date for May 31, 2023 23:59:59.999
- * ```
- */
-export declare function endOf(date: Date | number, unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'): Date;
-/**
- * Check if a date is between two other dates.
- *
- * @param date - Date to check
- * @param start - Start date of the range
- * @param end - End date of the range
- * @param inclusive - Whether the comparison should be inclusive of start/end
- * @returns True if the date is within the range
- *
- * @example
- * ```typescript
- * const date = new Date('2023-05-15');
- * const start = new Date('2023-05-10');
- * const end = new Date('2023-05-20');
- *
- * isBetween(date, start, end); // true
- * ```
- */
-export declare function isBetween(date: Date | number, start: Date | number, end: Date | number, inclusive?: boolean): boolean;
-/**
- * Check if a year is a leap year.
- *
- * @param year - Year to check (or date object)
- * @returns True if the year is a leap year
- */
-export declare function isLeapYear(year: number | Date): boolean;
-/**
- * Get the number of days in a month.
- *
- * @param year - Year
- * @param month - Month (0-11)
- * @returns Number of days in the month
- */
-export declare function daysInMonth(year: number | Date, month?: number): number;