captcha-canvas
Version:
A captcha generator by using skia-canvas module.
172 lines (171 loc) • 6.43 kB
TypeScript
/**
* Enhanced cryptographic utilities for secure CAPTCHA generation.
*
* This module provides cryptographically secure random number generation
* and text generation functions that eliminate Math.random() fallbacks
* and provide robust error handling for crypto module availability.
*/
/**
* Character set definitions for secure text generation.
*/
export declare const CHARSET_HEXADECIMAL = "0123456789ABCDEF";
export declare const CHARSET_ALPHANUMERIC = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
export declare const CHARSET_ALPHANUMERIC_MIXED_CASE = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
export declare const CHARSET_ALPHANUMERIC_SYMBOLS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz!@#$%^&*";
export declare const CHARSET_UNICODE_BASIC = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz!@#$%^&*()_+-=[]{}|;:,.<>?";
/**
* Interface for character set configuration.
*/
export interface CharacterSetConfig {
/** The character set to use for text generation */
charset: string;
/** Custom name for the character set */
name?: string;
/** Minimum entropy bits per character */
minEntropyBits?: number;
}
/**
* Predefined character set configurations.
*/
export declare const CHARACTER_SETS: Record<string, CharacterSetConfig>;
/**
* Validates that the crypto module is available and functional.
*
* @throws {CaptchaGenerationError} When crypto module is unavailable or non-functional
*
* @example
* ```typescript
* try {
* validateCryptoAvailability();
* // Safe to use crypto functions
* } catch (error) {
* console.error('Crypto not available:', error.message);
* }
* ```
*/
export declare function validateCryptoAvailability(): void;
/**
* Generates a cryptographically secure random integer within the specified range (inclusive).
*
* This function provides guaranteed cryptographically secure random number generation
* without any Math.random() fallbacks. If crypto is unavailable, it throws an error
* rather than degrading security.
*
* @param min - Minimum value (inclusive)
* @param max - Maximum value (inclusive)
* @returns Cryptographically secure random integer between min and max
* @throws {CaptchaGenerationError} When crypto module is unavailable
*
* @example Basic range
* ```typescript
* const angle = secureRandomInt(-15, 15); // Random angle between -15 and 15 degrees
* ```
*
* @example Single parameter (0 to n)
* ```typescript
* const index = secureRandomInt(0, 5); // Random number from 0 to 5
* ```
*/
export declare function secureRandomInt(min?: number, max?: number): number;
/**
* Generates a cryptographically secure random float between 0 and 1.
*
* Used for skewing transformations and other visual randomization that requires
* cryptographic security. No Math.random() fallback is provided.
*
* @param min - Minimum value (default: 0)
* @param max - Maximum value (default: 1)
* @returns Cryptographically secure random float between min and max
* @throws {CaptchaGenerationError} When crypto module is unavailable
*
* @example Basic usage
* ```typescript
* const skewFactor = secureRandomFloat(); // 0.0 to 1.0
* ```
*
* @example Custom range
* ```typescript
* const opacity = secureRandomFloat(0.3, 0.8); // 0.3 to 0.8
* ```
*/
export declare function secureRandomFloat(min?: number, max?: number): number;
/**
* Generates cryptographically secure text using the specified character set.
*
* This function provides enhanced text generation with configurable character sets
* and guaranteed cryptographic security. It replaces the limited hexadecimal-only
* randomText function with flexible character set support.
*
* @param length - Number of characters to generate
* @param config - Character set configuration (defaults to hexadecimal for backward compatibility)
* @returns Cryptographically secure random text
* @throws {CaptchaGenerationError} When crypto module is unavailable or parameters are invalid
*
* @example Hexadecimal (backward compatible)
* ```typescript
* const hex = generateSecureText(6); // e.g., "A3F7B2"
* ```
*
* @example Alphanumeric
* ```typescript
* const text = generateSecureText(8, CHARACTER_SETS.ALPHANUMERIC); // e.g., "K7M9P2X4"
* ```
*
* @example Custom character set
* ```typescript
* const custom = generateSecureText(6, {
* charset: '0123456789',
* name: 'Numeric Only'
* }); // e.g., "847291"
* ```
*/
export declare function generateSecureText(length: number, config?: CharacterSetConfig): string;
/**
* Calculates the entropy (in bits) of text generated with the given character set and length.
*
* @param length - Length of the text
* @param charsetSize - Size of the character set used
* @returns Entropy in bits
*
* @example
* ```typescript
* const entropy = calculateEntropy(6, 16); // 24 bits for 6-char hex
* const entropy2 = calculateEntropy(8, 62); // ~47.6 bits for 8-char mixed case alphanumeric
* ```
*/
export declare function calculateEntropy(length: number, charsetSize: number): number;
/**
* Validates that the generated text meets minimum entropy requirements.
*
* @param text - The generated text to validate
* @param config - Character set configuration used to generate the text
* @param minEntropyBits - Minimum required entropy in bits (default: 32)
* @returns True if entropy is sufficient
* @throws {CaptchaGenerationError} When entropy is insufficient
*
* @example
* ```typescript
* const text = generateSecureText(6, CHARACTER_SETS.HEXADECIMAL);
* validateTextEntropy(text, CHARACTER_SETS.HEXADECIMAL, 20); // Requires at least 20 bits
* ```
*/
export declare function validateTextEntropy(text: string, config: CharacterSetConfig, minEntropyBits?: number): boolean;
/**
* Gets cryptographic strength assessment for the given configuration.
*
* @param length - Text length
* @param config - Character set configuration
* @returns Strength assessment object
*
* @example
* ```typescript
* const assessment = getCryptographicStrength(6, CHARACTER_SETS.HEXADECIMAL);
* console.log(`Strength: ${assessment.level}, Entropy: ${assessment.entropyBits} bits`);
* ```
*/
export declare function getCryptographicStrength(length: number, config: CharacterSetConfig): {
level: 'WEAK' | 'MODERATE' | 'STRONG' | 'VERY_STRONG';
entropyBits: number;
timeToBreak: string;
recommendation: string;
};