captcha-canvas/dist/security/SecurityPresets.d.ts

A captcha generator by using skia-canvas module.

/**
 * Security configuration presets for CAPTCHA generation.
 *
 * This module provides predefined security levels that configure character set complexity,
 * text length requirements, entropy levels, and validation strictness to balance
 * security against usability for different use cases.
 */
import { CharacterSetConfig, getCryptographicStrength } from './CryptoUtils';
/**
 * Security level enumeration.
 */
export declare enum SecurityLevel {
    LOW = "LOW",
    MEDIUM = "MEDIUM",
    HIGH = "HIGH",
    MAXIMUM = "MAXIMUM"
}
/**
 * Interface for comprehensive security configuration.
 */
export interface SecurityConfig {
    /** Security level preset */
    level: SecurityLevel;
    /** Character set configuration for text generation */
    characterSet: CharacterSetConfig;
    /** Text length requirements */
    textLength: {
        min: number;
        max: number;
        default: number;
    };
    /** Entropy requirements in bits */
    entropy: {
        minimum: number;
        recommended: number;
    };
    /** Validation strictness settings */
    validation: {
        /** Require cryptographic random number generation (no Math.random fallbacks) */
        requireCrypto: boolean;
        /** Enable input sanitization */
        enableSanitization: boolean;
        /** Enable Unicode normalization */
        enableNormalization: boolean;
        /** Maximum allowed generation attempts before failure */
        maxAttempts: number;
    };
    /** Visual security settings */
    visual: {
        /** Minimum rotation angle range */
        minRotation: number;
        /** Maximum rotation angle range */
        maxRotation: number;
        /** Enable skewing by default */
        enableSkew: boolean;
        /** Minimum opacity for text */
        minOpacity: number;
        /** Recommended decoy character count multiplier */
        decoyMultiplier: number;
    };
    /** Rate limiting guidance */
    rateLimiting: {
        /** Recommended requests per minute per IP */
        requestsPerMinute: number;
        /** Recommended session timeout in minutes */
        sessionTimeoutMinutes: number;
    };
}
/**
 * LOW security preset - Basic protection suitable for low-risk applications.
 *
 * Provides minimal security with high usability. Suitable for comment forms,
 * newsletter signups, or other low-risk scenarios where user experience
 * is prioritized over security.
 *
 * @example
 * ```typescript
 * const captcha = new CaptchaGenerator()
 *   .setSecurityLevel(SecurityLevel.LOW);
 * ```
 */
export declare const LOW_SECURITY: SecurityConfig;
/**
 * MEDIUM security preset - Balanced security and usability.
 *
 * Provides good security with reasonable usability. Suitable for most
 * web applications, user registration forms, and general-purpose CAPTCHAs.
 * This is the recommended default for most applications.
 *
 * @example
 * ```typescript
 * const captcha = new CaptchaGenerator()
 *   .setSecurityLevel(SecurityLevel.MEDIUM);
 * ```
 */
export declare const MEDIUM_SECURITY: SecurityConfig;
/**
 * HIGH security preset - Strong security for sensitive applications.
 *
 * Provides high security with moderate usability impact. Suitable for
 * financial applications, admin panels, password reset forms, and other
 * security-sensitive scenarios.
 *
 * @example
 * ```typescript
 * const captcha = new CaptchaGenerator()
 *   .setSecurityLevel(SecurityLevel.HIGH);
 * ```
 */
export declare const HIGH_SECURITY: SecurityConfig;
/**
 * MAXIMUM security preset - Maximum security for critical applications.
 *
 * Provides maximum security with significant usability impact. Suitable for
 * highly sensitive applications, security research, or scenarios where
 * security is paramount over user experience.
 *
 * @example
 * ```typescript
 * const captcha = new CaptchaGenerator()
 *   .setSecurityLevel(SecurityLevel.MAXIMUM);
 * ```
 */
export declare const MAXIMUM_SECURITY: SecurityConfig;
/**
 * Security preset lookup table.
 */
export declare const SECURITY_PRESETS: Record<SecurityLevel, SecurityConfig>;
/**
 * Gets the security configuration for the specified level.
 *
 * @param level - Security level to retrieve
 * @returns Security configuration object
 * @throws {Error} When security level is invalid
 *
 * @example
 * ```typescript
 * const config = getSecurityConfig(SecurityLevel.HIGH);
 * console.log(`Using ${config.characterSet.name} with ${config.textLength.default} characters`);
 * ```
 */
export declare function getSecurityConfig(level: SecurityLevel): SecurityConfig;
/**
 * Validates that a security configuration meets minimum requirements.
 *
 * @param config - Security configuration to validate
 * @throws {Error} When configuration is invalid
 *
 * @example
 * ```typescript
 * const customConfig = { ...MEDIUM_SECURITY, textLength: { min: 2, max: 4, default: 3 } };
 * validateSecurityConfig(customConfig); // May throw if entropy is too low
 * ```
 */
export declare function validateSecurityConfig(config: SecurityConfig): void;
/**
 * Gets security information and recommendations for a given configuration.
 *
 * @param config - Security configuration to analyze
 * @returns Security analysis object
 *
 * @example
 * ```typescript
 * const analysis = getSecurityInfo(MEDIUM_SECURITY);
 * console.log(`Security Level: ${analysis.level}`);
 * console.log(`Estimated Strength: ${analysis.strength.level}`);
 * console.log(`Recommendations: ${analysis.recommendations.join(', ')}`);
 * ```
 */
export declare function getSecurityInfo(config: SecurityConfig): {
    level: SecurityLevel;
    strength: ReturnType<typeof getCryptographicStrength>;
    recommendations: string[];
    warnings: string[];
};
/**
 * Creates a custom security configuration based on a preset with overrides.
 *
 * @param baseLevel - Base security level to start from
 * @param overrides - Partial configuration to override base settings
 * @returns Custom security configuration
 *
 * @example
 * ```typescript
 * const customConfig = createCustomSecurityConfig(SecurityLevel.MEDIUM, {
 *   textLength: { min: 8, max: 10, default: 9 },
 *   characterSet: CHARACTER_SETS.ALPHANUMERIC_SYMBOLS
 * });
 * ```
 */
export declare function createCustomSecurityConfig(baseLevel: SecurityLevel, overrides: Partial<SecurityConfig>): SecurityConfig;
/**
 * Recommends an appropriate security level based on application requirements.
 *
 * @param requirements - Application security requirements
 * @returns Recommended security level and reasoning
 *
 * @example
 * ```typescript
 * const recommendation = recommendSecurityLevel({
 *   isFinancial: true,
 *   hasPersonalData: true,
 *   expectedVolume: 'medium',
 *   userExperiencePriority: 'balanced'
 * });
 * console.log(`Recommended: ${recommendation.level} - ${recommendation.reasoning}`);
 * ```
 */
export declare function recommendSecurityLevel(requirements: {
    isFinancial?: boolean;
    hasPersonalData?: boolean;
    isAdminPanel?: boolean;
    expectedVolume?: 'low' | 'medium' | 'high';
    userExperiencePriority?: 'security' | 'balanced' | 'usability';
    threatLevel?: 'low' | 'medium' | 'high' | 'critical';
}): {
    level: SecurityLevel;
    reasoning: string;
    alternatives?: SecurityLevel[];
};