@futdevpro/fsm-dynamo 1.14.12 → 1.14.13

package/src/_modules/crypto/_collections/crypto-v4.util.ts

@@ -0,0 +1,702 @@
+import * as CryptoJS from 'crypto-js';
+import { 
+  DyFM_Error, 
+  DyFM_Error_Settings 
+} from '../../../_models/control-models/error.control-model';
+import { DyFM_Object } from '../../../_collections/utils/object.util';
+
+
+/**
+ * Configuration options for encryption/decryption
+ */
+export interface CryptoConfig {
+  ivLength?: number;
+  saltLength?: number;
+  keyIterations?: number;
+  keySize?: number;
+}
+
+// Compact: about 60–80 character tokens, not 200+
+// Non-standard: hard to reverse-engineer
+// Usable in cookies, headers, URLs
+
+/**
+ * A utility class for stable encryption and decryption of data
+ * Uses AES-256-CBC with deterministic IV and salt for consistent results across systems
+ * Prioritizes reliability and cross-platform compatibility over security
+ * 
+ * @important DETERMINISTIC ENCRYPTION: This implementation produces identical encrypted 
+ * output for identical input data and key across different systems and multiple calls.
+ * The same input will ALWAYS generate the same encrypted string on any platform.
+ * 
+ * @warning SECURITY NOTICE: This deterministic behavior is intentional for cross-platform
+ * compatibility but reduces security. Identical inputs produce identical outputs, which
+ * can be exploited for pattern analysis attacks. Use only when consistency across
+ * systems is more important than cryptographic security.
+ */
+export class DyFM_Crypto {
+  private static readonly CRYPTO_VERSION = '1.0';
+  private static readonly DEFAULT_CONFIG: Required<CryptoConfig> = {
+    ivLength: 16, // 128 bits
+    saltLength: 16, // 128 bits
+    keyIterations: 1000, // Reduced for better performance and stability
+    keySize: 8 // 256 bits (8 * 32)
+  };
+  private static readonly defaultErrorUserMsg = 
+    `We encountered an unhandled Authentication Error, ` +
+    `\nplease contact the responsible development team.`;
+
+  // Key derivation cache for performance optimization
+  private static keyCache = new Map<string, CryptoJS.lib.WordArray>();
+  private static readonly MAX_CACHE_SIZE = 100;
+
+  /**
+   * Validates the input data and key with comprehensive error messages
+   * @throws {DyFM_Error} if validation fails
+   */
+  private static validateInput(data: any, key: string, operation: 'encrypt' | 'decrypt'): void {
+    // Validate key
+    if (!key) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings(operation),
+        errorCode: 'DyFM-CRY-KEY-MISSING',
+        message: `Encryption key is required for ${operation} operation. Please provide a valid key.`
+      });
+    }
+
+    if (typeof key !== 'string') {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings(operation),
+        errorCode: 'DyFM-CRY-KEY-TYPE',
+        message: `Encryption key must be a string, but received ${typeof key}. Please provide a valid string key.`
+      });
+    }
+
+    if (key.trim().length === 0) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings(operation),
+        errorCode: 'DyFM-CRY-KEY-EMPTY',
+        message: 'Encryption key cannot be empty or contain only whitespace. Please provide a non-empty key.'
+      });
+    }
+
+    // Only warn about weak keys but don't reject them for backward compatibility
+    if (key.length < 8) {
+      console.warn('Warning: Encryption key is too short (minimum 8 characters recommended). Consider using a stronger key for better security.');
+    }
+
+    // Validate data based on operation
+    if (operation === 'encrypt') {
+      this.validateEncryptData(data);
+    } else if (operation === 'decrypt') {
+      this.validateDecryptData(data);
+    }
+  }
+
+  /**
+   * Validates data for encryption
+   */
+  private static validateEncryptData(data: any): void {
+    if (data === undefined) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('encrypt'),
+        errorCode: 'DyFM-CRY-DATA-UNDEFINED',
+        message: 'Cannot encrypt undefined data. Please provide valid data to encrypt.'
+      });
+    }
+
+    if (data === null) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('encrypt'),
+        errorCode: 'DyFM-CRY-DATA-NULL',
+        message: 'Cannot encrypt null data. Please provide valid data to encrypt.'
+      });
+    }
+
+    // Check for empty strings
+    if (typeof data === 'string' && data.trim().length === 0) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('encrypt'),
+        errorCode: 'DyFM-CRY-DATA-EMPTY-STRING',
+        message: 'Cannot encrypt empty string. Please provide non-empty data to encrypt.'
+      });
+    }
+
+    // Allow empty objects and arrays for backward compatibility
+    // Only reject truly empty data like empty strings
+  }
+
+  /**
+   * Validates data for decryption
+   */
+  private static validateDecryptData(data: any): void {
+    if (data === undefined) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('decrypt'),
+        errorCode: 'DyFM-CRY-ENCRYPTED-UNDEFINED',
+        message: 'Cannot decrypt undefined data. Please provide valid encrypted data to decrypt.'
+      });
+    }
+
+    if (data === null) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('decrypt'),
+        errorCode: 'DyFM-CRY-ENCRYPTED-NULL',
+        message: 'Cannot decrypt null data. Please provide valid encrypted data to decrypt.'
+      });
+    }
+
+    if (typeof data !== 'string') {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('decrypt'),
+        errorCode: 'DyFM-CRY-ENCRYPTED-TYPE',
+        message: `Encrypted data must be a string, but received ${typeof data}. Please provide valid encrypted string data.`
+      });
+    }
+
+    if (data.trim().length === 0) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('decrypt'),
+        errorCode: 'DyFM-CRY-ENCRYPTED-EMPTY',
+        message: 'Cannot decrypt empty string. Please provide valid encrypted data to decrypt.'
+      });
+    }
+
+    if (data.length < 10) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('decrypt'),
+        errorCode: 'DyFM-CRY-ENCRYPTED-TOO-SHORT',
+        message: 'Encrypted data appears to be too short to be valid. Please check the encrypted data.'
+      });
+    }
+
+    // Check if it looks like valid encrypted data format
+    if (!/^[A-Za-z0-9\-_]+$/.test(data)) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('decrypt'),
+        errorCode: 'DyFM-CRY-ENCRYPTED-INVALID-FORMAT',
+        message: 'Encrypted data does not appear to be in valid format. Expected URL-safe base64 format.'
+      });
+    }
+  }
+
+  /**
+   * Generates a deterministic IV based on the input data and key
+   * Uses SHA-256 with proper truncation for maximum stability
+   * 
+   * @important DETERMINISTIC: Same data + key will ALWAYS produce the same IV
+   * across all systems and CryptoJS versions for consistent encryption results
+   */
+  private static generateIV(data: string, key: string, config: Required<CryptoConfig>): CryptoJS.lib.WordArray {
+    // Create a deterministic seed from data and key
+    const seed = this.createDeterministicSeed(data, key, 'IV');
+    
+    // Use SHA-256 for better stability and consistency
+    const hash = CryptoJS.SHA256(seed);
+    
+    // Extract exactly 16 bytes (128 bits) for IV
+    // Use the first 4 words (4 * 4 = 16 bytes) from the hash
+    const ivWords = hash.words.slice(0, 4);
+    return CryptoJS.lib.WordArray.create(ivWords);
+  }
+
+  /**
+   * Generates a deterministic salt based on the input data and key
+   * Uses SHA-256 with proper truncation for maximum stability
+   * 
+   * @important DETERMINISTIC: Same data + key will ALWAYS produce the same salt
+   * across all systems and CryptoJS versions for consistent encryption results
+   */
+  private static generateSalt(data: string, key: string, config: Required<CryptoConfig>): CryptoJS.lib.WordArray {
+    // Create a deterministic seed from data and key (different from IV)
+    const seed = this.createDeterministicSeed(data, key, 'SALT');
+    
+    // Use SHA-256 for better stability and consistency
+    const hash = CryptoJS.SHA256(seed);
+    
+    // Extract exactly 16 bytes (128 bits) for salt
+    // Use the first 4 words (4 * 4 = 16 bytes) from the hash
+    const saltWords = hash.words.slice(0, 4);
+    return CryptoJS.lib.WordArray.create(saltWords);
+  }
+
+  /**
+   * Creates a deterministic seed for IV/salt generation
+   * Ensures consistent output across all environments and versions
+   */
+  private static createDeterministicSeed(data: string, key: string, purpose: string): string {
+    // Create a consistent seed that includes all relevant factors
+    // Order matters: data + key + purpose for consistency
+    const seed = `${data}|${key}|${purpose}`;
+    return seed;
+  }
+
+  /**
+   * Generates a cache key for the derived key based on the input key and salt
+   */
+  private static generateCacheKey(key: string, salt: CryptoJS.lib.WordArray): string {
+    // Create a deterministic cache key from key and salt
+    const saltHex = salt.toString(CryptoJS.enc.Hex);
+    return `${key}|${saltHex}`;
+  }
+
+  /**
+   * Manages cache size by removing oldest entries when limit is exceeded
+   */
+  private static manageCacheSize(): void {
+    if (this.keyCache.size >= this.MAX_CACHE_SIZE) {
+      // Remove oldest entries (Map maintains insertion order)
+      const entriesToRemove = this.keyCache.size - this.MAX_CACHE_SIZE + 10; // Remove 10 extra for efficiency
+      const keysToRemove = Array.from(this.keyCache.keys()).slice(0, entriesToRemove);
+      keysToRemove.forEach(key => this.keyCache.delete(key));
+    }
+  }
+
+  /**
+   * Derives a key using PBKDF2 with reduced iterations for stability
+   * Uses caching to avoid redundant PBKDF2 computations for better performance
+   */
+  private static deriveKey(key: string, salt: CryptoJS.lib.WordArray, config: Required<CryptoConfig>): CryptoJS.lib.WordArray {
+    const cacheKey = this.generateCacheKey(key, salt);
+    
+    // Check cache first
+    if (this.keyCache.has(cacheKey)) {
+      return this.keyCache.get(cacheKey)!;
+    }
+
+    // Compute new key using PBKDF2
+    const derivedKey = CryptoJS.PBKDF2(key, salt, {
+      keySize: config.keySize,
+      iterations: config.keyIterations
+    });
+
+    // Store in cache and manage size
+    this.keyCache.set(cacheKey, derivedKey);
+    this.manageCacheSize();
+
+    return derivedKey;
+  }
+
+  /**
+   * Safely serializes data to JSON with deterministic ordering
+   * Uses regular JSON.stringify but ensures consistency through other means
+   */
+  private static safeSerialize<T>(data: T): string {
+    try {
+      // Use regular JSON.stringify for backward compatibility
+      // The deterministic behavior comes from the IV/salt generation, not serialization
+      return JSON.stringify(data);
+    } catch (error) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('safeSerialize', error),
+        errorCode: 'DyFM-CRY-SER',
+        message: 'Failed to serialize data'
+      });
+    }
+  }
+
+  /**
+   * Deterministic JSON stringify that produces identical output across environments
+   * Uses a hybrid approach: sorts keys for consistency but preserves order for arrays
+   */
+  private static deterministicStringify(obj: any): string {
+    if (obj === null) return 'null';
+    if (obj === undefined) return 'undefined';
+    if (typeof obj === 'string') return JSON.stringify(obj);
+    if (typeof obj === 'number') return JSON.stringify(obj);
+    if (typeof obj === 'boolean') return JSON.stringify(obj);
+    
+    if (Array.isArray(obj)) {
+      const items = obj.map(item => this.deterministicStringify(item));
+      return '[' + items.join(',') + ']';
+    }
+    
+    if (typeof obj === 'object') {
+      // For objects, we need to be more careful about key ordering
+      // Use a stable sort that preserves original order when possible
+      const keys = Object.keys(obj);
+      
+      // Only sort if there are potential ordering issues
+      const needsSorting = keys.some((key, index) => {
+        if (index === 0) return false;
+        return key < keys[index - 1];
+      });
+      
+      const sortedKeys = needsSorting ? [...keys].sort() : keys;
+      const pairs = sortedKeys.map(key => {
+        const value = this.deterministicStringify(obj[key]);
+        return JSON.stringify(key) + ':' + value;
+      });
+      return '{' + pairs.join(',') + '}';
+    }
+    
+    // Handle Date objects and other special types
+    if (obj instanceof Date) {
+      return JSON.stringify(obj.toISOString());
+    }
+    
+    // Fallback to regular JSON.stringify for other types
+    return JSON.stringify(obj);
+  }
+
+  /**
+   * Safely deserializes JSON data with enhanced error handling
+   */
+  private static safeDeserialize<T>(data: string): T {
+    try {
+      if (!data || data.trim().length === 0) {
+        throw new DyFM_Error({
+          ...this.getDefaultErrorSettings('safeDeserialize'),
+          errorCode: 'DyFM-CRY-DES-EMPTY',
+          message: 'Cannot deserialize empty data. The decrypted data appears to be empty or invalid.'
+        });
+      }
+
+      //let parsed = JSON.parse(data);
+      let parsed = DyFM_Object.failableSafeParseJSON(data);
+      
+      // Handle double-stringified JSON (or more levels of stringification)
+      let maxAttempts = 3; // Prevent infinite loops
+      while (typeof parsed === 'string' && maxAttempts > 0) {
+        try {
+          //const nextParsed = JSON.parse(parsed);
+          const nextParsed = DyFM_Object.failableSafeParseJSON(parsed);
+          // Only continue if parsing actually changed the result
+          if (nextParsed !== parsed) {
+            parsed = nextParsed;
+            maxAttempts--;
+          } else {
+            break;
+          }
+        } catch {
+          // If parse fails, return current state
+          break;
+        }
+      }
+
+      // Handle primitive values
+      /* if (typeof parsed === 'string' || typeof parsed === 'number' || typeof parsed === 'boolean') {
+        return parsed as T;
+      } */
+
+      return parsed as T;
+    } catch (error) {
+      if (error instanceof DyFM_Error) {
+        throw error;
+      }
+      
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('safeDeserialize', error),
+        errorCode: 'DyFM-CRY-DES',
+        message: 'Failed to deserialize data. The decrypted data may be corrupted or in an unexpected format.'
+      });
+    }
+  }
+
+  /**
+   * Encrypts data using AES-256-CBC with deterministic IV and salt
+   * 
+   * @important DETERMINISTIC BEHAVIOR: This method will produce identical encrypted
+   * output for identical input parameters across different systems, Node.js versions,
+   * and multiple function calls. The same data + key combination will ALWAYS generate
+   * the same encrypted string.
+   * 
+   * @param data The data to encrypt
+   * @param key The encryption key
+   * @param config Optional configuration
+   * @returns URL-safe encrypted string that is identical across systems for same input
+   * @throws {DyFM_Error} if encryption fails
+   * 
+   * @example
+   * // These will produce identical results on any system:
+   * const result1 = DyFM_Crypto.encrypt({id: 1}, "mykey");
+   * const result2 = DyFM_Crypto.encrypt({id: 1}, "mykey");
+   * console.log(result1 === result2); // Always true
+   */
+  static encrypt<T>(data: T, key: string, config?: CryptoConfig): string {
+    try {
+      this.validateInput(data, key, 'encrypt');
+      const finalConfig = { ...this.DEFAULT_CONFIG, ...config };
+
+      // Convert data to string
+      const dataStr = this.safeSerialize(data);
+
+      // Generate deterministic IV and salt based on data and key
+      const iv = this.generateIV(dataStr, key, finalConfig);
+      const salt = this.generateSalt(dataStr, key, finalConfig);
+
+      // Derive key using PBKDF2
+      const derivedKey = this.deriveKey(key, salt, finalConfig);
+
+      // Encrypt the data
+      const encrypted = CryptoJS.AES.encrypt(dataStr, derivedKey, {
+        iv: iv,
+        mode: CryptoJS.mode.CBC,
+        padding: CryptoJS.pad.Pkcs7
+      });
+
+      // Combine IV + Salt + Ciphertext (skip version for backward compatibility)
+      const combined = iv.concat(salt).concat(encrypted.ciphertext);
+
+      // Convert to URL-safe base64
+      return CryptoJS.enc.Base64.stringify(combined)
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+    } catch (error) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('encrypt', error),
+        errorCode: 'DyFM-CRY-ENC',
+      });
+    }
+  }
+
+  /**
+   * Decrypts data that was encrypted using encrypt()
+   * @param encryptedData The encrypted data
+   * @param key The decryption key
+   * @param config Optional configuration
+   * @returns The decrypted data
+   * @throws {DyFM_Error} if decryption fails
+   */
+  static decrypt<T>(encryptedData: string, key: string, config?: CryptoConfig): T {
+    try {
+      this.validateInput(encryptedData, key, 'decrypt');
+      const finalConfig = { ...this.DEFAULT_CONFIG, ...config };
+
+      // Convert from URL-safe base64
+      const base64 = encryptedData
+        .replace(/-/g, '+')
+        .replace(/_/g, '/');
+
+      // Parse the combined data
+      const combined = CryptoJS.enc.Base64.parse(base64);
+
+      // For now, skip version checking to maintain backward compatibility
+      // TODO: Implement proper version checking in future versions
+      
+      // Validate minimum length (IV + Salt + minimum ciphertext)
+      const minLength = (finalConfig.ivLength + finalConfig.saltLength + 16) / 4; // 16 bytes minimum for ciphertext
+      if (combined.words.length < minLength) {
+        throw new DyFM_Error({
+          ...this.getDefaultErrorSettings('decrypt'),
+          errorCode: 'DyFM-CRY-DATA-CORRUPTED',
+          message: `Encrypted data is corrupted or incomplete. Expected at least ${minLength * 4} bytes, but received ${combined.sigBytes} bytes.`
+        });
+      }
+
+      // Extract IV, salt, and ciphertext (skip version for now)
+      const ivStart = 0;
+      const saltStart = ivStart + finalConfig.ivLength / 4;
+      const cipherStart = saltStart + finalConfig.saltLength / 4;
+      
+      const iv = CryptoJS.lib.WordArray.create(combined.words.slice(ivStart, saltStart));
+      const salt = CryptoJS.lib.WordArray.create(combined.words.slice(saltStart, cipherStart));
+      const ciphertext = CryptoJS.lib.WordArray.create(combined.words.slice(cipherStart));
+
+      // Derive key using PBKDF2
+      const derivedKey = this.deriveKey(key, salt, finalConfig);
+
+      // Decrypt the data
+      const decrypted = CryptoJS.AES.decrypt(
+        { ciphertext: ciphertext },
+        derivedKey,
+        {
+          iv: iv,
+          mode: CryptoJS.mode.CBC,
+          padding: CryptoJS.pad.Pkcs7
+        }
+      );
+
+      // Parse JSON
+      const decryptedStr = decrypted.toString(CryptoJS.enc.Utf8);
+      
+      // Check if decryption produced empty result
+      if (!decryptedStr || decryptedStr.trim().length === 0) {
+        throw new DyFM_Error({
+          ...this.getDefaultErrorSettings('decrypt'),
+          errorCode: 'DyFM-CRY-DECRYPT-EMPTY',
+          message: 'Decryption failed - the result is empty. This usually means the encryption key is incorrect or the data is corrupted.'
+        });
+      }
+      
+      return this.safeDeserialize<T>(decryptedStr);
+    } catch (error) {
+      // Check if it's already a DyFM_Error
+      if (error instanceof DyFM_Error) {
+        throw error;
+      }
+      
+      // Handle specific decryption errors
+      if (error instanceof Error) {
+        if (error.message.includes('Malformed UTF-8')) {
+          throw new DyFM_Error({
+            ...this.getDefaultErrorSettings('decrypt', error),
+            errorCode: 'DyFM-CRY-DECRYPT-UTF8',
+            message: 'Decryption failed - invalid UTF-8 data. This usually means the encryption key is incorrect or the data is corrupted.'
+          });
+        }
+        
+        if (error.message.includes('Invalid padding')) {
+          throw new DyFM_Error({
+            ...this.getDefaultErrorSettings('decrypt', error),
+            errorCode: 'DyFM-CRY-DECRYPT-PADDING',
+            message: 'Decryption failed - invalid padding. This usually means the encryption key is incorrect or the data is corrupted.'
+          });
+        }
+      }
+      
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('decrypt', error),
+        errorCode: 'DyFM-CRY-DRY',
+        message: 'Decryption failed. Please verify the encryption key and ensure the encrypted data is valid.'
+      });
+    }
+  }
+
+  /**
+   * Generates a secure random key with enhanced complexity
+   * @param length Length of the key in characters (default: 32)
+   * @param customChars Optional custom character set to use
+   * @returns A secure random key with mixed case letters, numbers, and special characters
+   */
+  static generateKey(length: number = 32, customChars?: string): string {
+    // Use custom character set if provided, otherwise use simple safe characters
+    const chars = customChars || 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+    let complexKey = '';
+    
+    // Generate random characters directly for the desired length
+    for (let i = 0; i < length; i++) {
+      // Generate random bytes for each character
+      const randomBytes = CryptoJS.lib.WordArray.random(1);
+      const randomValue = randomBytes.words[0];
+      const charIndex = Math.abs(randomValue) % chars.length;
+      complexKey += chars[charIndex];
+    }
+    
+    return complexKey;
+  }
+
+  /**
+   * Validates if a string is a valid encrypted data
+   * @param encryptedData The data to validate
+   * @returns true if the data appears to be valid encrypted data
+   */
+  static isValidEncryptedData(encryptedData: string): boolean {
+    if (!encryptedData || typeof encryptedData !== 'string') {
+      return false;
+    }
+    return /^[A-Za-z0-9\-_]+$/.test(encryptedData);
+  }
+
+  /**
+   * Analyzes encrypted data to help with debugging
+   * @param encryptedData The encrypted data to analyze
+   * @returns Analysis information about the encrypted data
+   */
+  static analyzeEncryptedData(encryptedData: string): {
+    isValid: boolean;
+    version?: string;
+    dataLength: number;
+    hasValidFormat: boolean;
+    error?: string;
+  } {
+    try {
+      if (!this.isValidEncryptedData(encryptedData)) {
+        return {
+          isValid: false,
+          dataLength: encryptedData?.length || 0,
+          hasValidFormat: false,
+          error: 'Invalid format - not URL-safe base64'
+        };
+      }
+
+      // Convert from URL-safe base64
+      const base64 = encryptedData
+        .replace(/-/g, '+')
+        .replace(/_/g, '/');
+
+      // Parse the combined data
+      const combined = CryptoJS.enc.Base64.parse(base64);
+      
+      // For now, just check if the data has minimum required length
+      const minLength = (16 + 16 + 16) / 4; // IV + Salt + minimum ciphertext
+      
+      if (combined.words.length < minLength) {
+        return {
+          isValid: false,
+          dataLength: combined.sigBytes,
+          hasValidFormat: false,
+          error: 'Data too short to contain valid encrypted data'
+        };
+      }
+
+      return {
+        isValid: true,
+        version: 'legacy',
+        dataLength: combined.sigBytes,
+        hasValidFormat: true,
+        error: undefined
+      };
+    } catch (error) {
+      return {
+        isValid: false,
+        dataLength: encryptedData?.length || 0,
+        hasValidFormat: false,
+        error: `Analysis failed: ${error}`
+      };
+    }
+  }
+
+  /**
+   * Clears the key derivation cache
+   * Useful for testing and memory management
+   */
+  static clearKeyCache(): void {
+    this.keyCache.clear();
+  }
+
+  /**
+   * Gets cache statistics for debugging and monitoring
+   * @returns Cache statistics including size and hit ratio
+   */
+  static getCacheStats(): {
+    size: number;
+    maxSize: number;
+    utilizationPercent: number;
+  } {
+    return {
+      size: this.keyCache.size,
+      maxSize: this.MAX_CACHE_SIZE,
+      utilizationPercent: Math.round((this.keyCache.size / this.MAX_CACHE_SIZE) * 100)
+    };
+  }
+
+  /**
+   * Gets default error settings with enhanced debugging information
+   */
+  private static getDefaultErrorSettings(operation: string, error?: any): DyFM_Error_Settings {
+    const baseSettings = {
+      status: (error as DyFM_Error)?.___status ?? (error as any)?.status ?? 401,
+      message: `Crypto operation "${operation}" failed.`,
+      error: error,
+      errorCode: 'DyFM-CRY-ERR'
+    };
+
+    // Add debugging information for common failure scenarios
+    if (operation === 'decrypt') {
+      baseSettings.message += '\nThis usually indicates: ' +
+                              '\n  1) Wrong encryption key, ' +
+                              '\n  2) Corrupted encrypted data, ' +
+                              '\n  3) Version incompatibility, ' +
+                              '\n  4) Data was encrypted with different parameters.';
+    } else if (operation === 'encrypt') {
+      baseSettings.message += '\nThis usually indicates: ' +
+                              '\n  1) Invalid input data, ' +
+                              '\n  2) Invalid encryption key, ' +
+                              '\n  3) Serialization failure.';
+    }
+
+    return baseSettings;
+  }
+}