@futdevpro/fsm-dynamo 1.16.37 → 1.16.39

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

@@ -1,748 +1,748 @@
-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';
-import { DyFM_global_settings } from '../../../_collections/constants/global-settings.const';
-import { DyFM_Log } from '../../../_collections/utils/log.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: string = '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: string = 
-    `We encountered an unhandled Authentication Error, ` +
-    `\nplease contact the responsible development team.`;
-
-  /**
-   * 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: string = this.createDeterministicSeed(data, key, 'IV');
-    
-    // Use SHA-256 for better stability and consistency
-    const hash: CryptoJS.lib.WordArray = 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: number[] = 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: string = this.createDeterministicSeed(data, key, 'SALT');
-    
-    // Use SHA-256 for better stability and consistency
-    const hash: CryptoJS.lib.WordArray = 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: number[] = 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: string = `${data}|${key}|${purpose}`;
-    return seed;
-  }
-
-  /**
-   * Derives a key using PBKDF2 with reduced iterations for stability
-   */
-  private static deriveKey(key: string, salt: CryptoJS.lib.WordArray, config: Required<CryptoConfig>): CryptoJS.lib.WordArray {
-    return CryptoJS.PBKDF2(key, salt, {
-      keySize: config.keySize,
-      iterations: config.keyIterations
-    });
-  }
-
-  /**
-   * 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: string[] = Object.keys(obj);
-      
-      // Only sort if there are potential ordering issues
-      const needsSorting: boolean = keys.some((key, index) => {
-        if (index === 0) return false;
-        return key < keys[index - 1];
-      });
-      
-      const sortedKeys: string[] = needsSorting ? [...keys].sort() : keys;
-      const pairs: string[] = sortedKeys.map(key => {
-        const value: string = 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: T = DyFM_Object.failableSafeParseJSON(data);
-      
-      // Handle double-stringified JSON (or more levels of stringification)
-      let maxAttempts: number = 3; // Prevent infinite loops
-      while (typeof parsed === 'string' && maxAttempts > 0) {
-        try {
-          //const nextParsed = JSON.parse(parsed);
-          const nextParsed: T = 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: Required<CryptoConfig> = { ...this.DEFAULT_CONFIG, ...config };
-
-      // Convert data to string
-      const dataStr: string = this.safeSerialize(data);
-
-      // Generate deterministic IV and salt based on data and key
-      const iv: CryptoJS.lib.WordArray = this.generateIV(dataStr, key, finalConfig);
-      const salt: CryptoJS.lib.WordArray = this.generateSalt(dataStr, key, finalConfig);
-
-      // Derive key using PBKDF2
-      const derivedKey: CryptoJS.lib.WordArray = this.deriveKey(key, salt, finalConfig);
-
-      // Encrypt the data
-      const encrypted: CryptoJS.lib.WordArray = 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: CryptoJS.lib.WordArray = 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: Required<CryptoConfig> = { ...this.DEFAULT_CONFIG, ...config };
-
-      // Convert from URL-safe base64
-      const base64: string = encryptedData
-        .replace(/-/g, '+')
-        .replace(/_/g, '/');
-
-      // Add padding if needed (base64 must be multiple of 4 characters)
-      // This ensures CryptoJS.parse works correctly even when padding was stripped during URL transmission
-      const paddingNeeded: number = (4 - (base64.length % 4)) % 4;
-      const paddedBase64: string = base64 + '='.repeat(paddingNeeded);
-
-      // Validate base64 format before parsing
-      // Check if the string length makes sense for expected minimum byte count
-      // Minimum expected: 48 bytes = ~64 base64 characters (48 * 4/3 = 64)
-      const minExpectedBase64Length: number = Math.ceil((finalConfig.ivLength + finalConfig.saltLength + 16) * 4 / 3);
-      if (paddedBase64.length < minExpectedBase64Length) {
-        if (DyFM_global_settings.log_settings.server_debug || true) {
-          DyFM_Log.H_error(
-            `Encrypted data is too short. Expected at least ${minExpectedBase64Length} base64 characters ` +
-            `(for ${(finalConfig.ivLength + finalConfig.saltLength + 16)} bytes), ` +
-            `but received ${paddedBase64.length} characters (${encryptedData.length} original). ` +
-            `This may indicate the data was truncated during transmission or storage.` +
-            '\n\nEncrypted data: ' + encryptedData,
-            '\n\nkey: ' + key
-          );
-        }
-
-        throw new DyFM_Error({
-          ...this.getDefaultErrorSettings('decrypt'),
-          errorCode: 'DyFM-CRY-DATA-CORRUPTED',
-          message: `Encrypted data is too short. Expected at least ${minExpectedBase64Length} base64 characters ` +
-                   `(for ${(finalConfig.ivLength + finalConfig.saltLength + 16)} bytes), ` +
-                   `but received ${paddedBase64.length} characters (${encryptedData.length} original). ` +
-                   `This may indicate the data was truncated during transmission or storage.`
-        });
-      }
-
-      // Parse the combined data
-      const combined: CryptoJS.lib.WordArray = CryptoJS.enc.Base64.parse(paddedBase64);
-
-      // 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: number = (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. ` +
-                   `Original string length: ${encryptedData.length} characters. ` +
-                   `Base64 length: ${base64.length} characters (${paddedBase64.length} with padding). ` +
-                   `This may indicate the data was truncated during transmission or storage.`
-        });
-      }
-
-      // Extract IV, salt, and ciphertext (skip version for now)
-      const ivStart: number = 0;
-      const saltStart: number = ivStart + finalConfig.ivLength / 4;
-      const cipherStart: number = saltStart + finalConfig.saltLength / 4;
-      
-      const iv: CryptoJS.lib.WordArray = CryptoJS.lib.WordArray.create(combined.words.slice(ivStart, saltStart));
-      const salt: CryptoJS.lib.WordArray = CryptoJS.lib.WordArray.create(combined.words.slice(saltStart, cipherStart));
-      const ciphertext: CryptoJS.lib.WordArray = CryptoJS.lib.WordArray.create(combined.words.slice(cipherStart));
-
-      // Derive key using PBKDF2
-      const derivedKey: CryptoJS.lib.WordArray = this.deriveKey(key, salt, finalConfig);
-
-      // Decrypt the data
-      const decrypted: CryptoJS.lib.WordArray = CryptoJS.AES.decrypt(
-        { ciphertext: ciphertext },
-        derivedKey,
-        {
-          iv: iv,
-          mode: CryptoJS.mode.CBC,
-          padding: CryptoJS.pad.Pkcs7
-        }
-      );
-
-      // Parse JSON
-      const decryptedStr: string = 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: string = customChars || 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
-    let complexKey: string = '';
-    
-    // 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 = CryptoJS.lib.WordArray.random(1);
-      const randomValue: number = randomBytes.words[0];
-      const charIndex: number = 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);
-  }
-
-  // ────────────────────────────────────────────────────────────────────────────
-  // AT-REST DB field-encryption — verzió-envelope (opt-in `encrypt:true` mezőkhöz)
-  // ────────────────────────────────────────────────────────────────────────────
-  //
-  // Formátum: `DYENC1:<keyVersion>:<ciphertext>`. A `keyVersion` a jövőbeli kulcs-rotációhoz
-  // (a decrypt a verzióból tudja, melyik kulcs kell). Az envelope-prefix teszi MEGBÍZHATÓVÁ a
-  // "titkosított VAGY legacy plaintext" megkülönböztetést (az `isValidEncryptedData` regex
-  // önmagában plaintextre is illeszkedhet → nem elég a detektáláshoz).
-
-  /** Az AT-REST DB-field-encryption envelope-prefixe. */
-  static readonly DB_ENC_PREFIX: string = 'DYENC1:';
-
-  /**
-   * DB-mező titkosítása verzió-envelope-pel. Visszaad: `DYENC1:<keyVersion>:<ciphertext>`.
-   * A `DyFM_Crypto.encrypt` determinisztikus (Q3: elfogadott promptra) — üres/undefined/null-ra
-   * dob, ezért a HÍVÓ (nts-transzform) skip-eli az ilyen értékeket.
-   *
-   * @param data A titkosítandó érték
-   * @param key A titkosító kulcs (FDP_CORE_DBCONTENT_CRYPT_KEY)
-   * @param keyVersion A kulcs-verzió (rotációhoz; default 1)
-   */
-  static encryptDbValue<T>(data: T, key: string, keyVersion: number = 1, config?: CryptoConfig): string {
-    const ciphertext: string = this.encrypt(data, key, config);
-    return `${this.DB_ENC_PREFIX}${keyVersion}:${ciphertext}`;
-  }
-
-  /** True, ha az érték a DB-enc envelope-pel kezdődik (tehát titkosított, nem legacy plaintext). */
-  static isEncryptedDbValue(value: unknown): value is string {
-    return typeof value === 'string' && value.startsWith(this.DB_ENC_PREFIX);
-  }
-
-  /** A DB-enc envelope `keyVersion`-je, vagy `null` ha az érték nem envelope. */
-  static getDbValueKeyVersion(value: unknown): number | null {
-    if (!this.isEncryptedDbValue(value)) {
-      return null;
-    }
-    const rest: string = value.slice(this.DB_ENC_PREFIX.length);
-    const sep: number = rest.indexOf(':');
-    if (sep < 0) {
-      return null;
-    }
-    const parsed: number = Number(rest.slice(0, sep));
-    return Number.isFinite(parsed) ? parsed : null;
-  }
-
-  /**
-   * DB-enc envelope visszafejtése. A hívó a `getDbValueKeyVersion` alapján oldja fel a megfelelő
-   * kulcsot, és azt adja át. Ha az érték NEM envelope (legacy plaintext), a hívó NE ezt hívja
-   * (a read-transzform envelope-detektálással szűr → a plaintext változatlanul jön vissza).
-   */
-  static decryptDbValue<T>(value: string, key: string, config?: CryptoConfig): T {
-    if (!this.isEncryptedDbValue(value)) {
-      throw new DyFM_Error({
-        ...this.getDefaultErrorSettings('decrypt'),
-        errorCode: 'DyFM-CRY-ENV-MISSING',
-        message: 'Value is not a DB-encryption envelope (missing DYENC1: prefix).',
-      });
-    }
-    const rest: string = value.slice(this.DB_ENC_PREFIX.length);
-    const sep: number = rest.indexOf(':');
-    const ciphertext: string = rest.slice(sep + 1);
-    return this.decrypt<T>(ciphertext, key, config);
-  }
-
-  /**
-   * 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: string = encryptedData
-        .replace(/-/g, '+')
-        .replace(/_/g, '/');
-
-      // Parse the combined data
-      const combined: CryptoJS.lib.WordArray = CryptoJS.enc.Base64.parse(base64);
-      
-      // For now, just check if the data has minimum required length
-      const minLength: number = (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}`
-      };
-    }
-  }
-
-  /**
-   * Gets default error settings with enhanced debugging information
-   */
-  private static getDefaultErrorSettings(operation: string, error?: any): DyFM_Error_Settings {
-    const baseSettings: DyFM_Error_Settings = {
-      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, ' +
-                              '\n  5) Data truncation during transmission (check HTTP header size limits, URL length limits), ' +
-                              '\n  6) Missing base64 padding (should be automatically handled, but may indicate transmission issues).';
-      
-      // Add specific guidance for truncation issues (like the "18 bytes" error)
-      baseSettings.message += '\n\nFor truncation issues (e.g., "received 18 bytes"): ' +
-                              '\n  - Check if data is being truncated in HTTP headers (Nginx default: 4-8KB, configurable), ' +
-                              '\n  - Verify URL parameter length limits if passed via query string, ' +
-                              '\n  - Check database field size limits if stored, ' +
-                              '\n  - Ensure proxy/load balancer header size limits are sufficient, ' +
-                              '\n  - Verify the encrypted data string length matches expected size before decryption.';
-    } 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;
-  }
-}
+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';
+import { DyFM_global_settings } from '../../../_collections/constants/global-settings.const';
+import { DyFM_Log } from '../../../_collections/utils/log.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: string = '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: string = 
+    `We encountered an unhandled Authentication Error, ` +
+    `\nplease contact the responsible development team.`;
+
+  /**
+   * 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: string = this.createDeterministicSeed(data, key, 'IV');
+    
+    // Use SHA-256 for better stability and consistency
+    const hash: CryptoJS.lib.WordArray = 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: number[] = 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: string = this.createDeterministicSeed(data, key, 'SALT');
+    
+    // Use SHA-256 for better stability and consistency
+    const hash: CryptoJS.lib.WordArray = 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: number[] = 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: string = `${data}|${key}|${purpose}`;
+    return seed;
+  }
+
+  /**
+   * Derives a key using PBKDF2 with reduced iterations for stability
+   */
+  private static deriveKey(key: string, salt: CryptoJS.lib.WordArray, config: Required<CryptoConfig>): CryptoJS.lib.WordArray {
+    return CryptoJS.PBKDF2(key, salt, {
+      keySize: config.keySize,
+      iterations: config.keyIterations
+    });
+  }
+
+  /**
+   * 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: string[] = Object.keys(obj);
+      
+      // Only sort if there are potential ordering issues
+      const needsSorting: boolean = keys.some((key, index) => {
+        if (index === 0) return false;
+        return key < keys[index - 1];
+      });
+      
+      const sortedKeys: string[] = needsSorting ? [...keys].sort() : keys;
+      const pairs: string[] = sortedKeys.map(key => {
+        const value: string = 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: T = DyFM_Object.failableSafeParseJSON(data);
+      
+      // Handle double-stringified JSON (or more levels of stringification)
+      let maxAttempts: number = 3; // Prevent infinite loops
+      while (typeof parsed === 'string' && maxAttempts > 0) {
+        try {
+          //const nextParsed = JSON.parse(parsed);
+          const nextParsed: T = 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: Required<CryptoConfig> = { ...this.DEFAULT_CONFIG, ...config };
+
+      // Convert data to string
+      const dataStr: string = this.safeSerialize(data);
+
+      // Generate deterministic IV and salt based on data and key
+      const iv: CryptoJS.lib.WordArray = this.generateIV(dataStr, key, finalConfig);
+      const salt: CryptoJS.lib.WordArray = this.generateSalt(dataStr, key, finalConfig);
+
+      // Derive key using PBKDF2
+      const derivedKey: CryptoJS.lib.WordArray = this.deriveKey(key, salt, finalConfig);
+
+      // Encrypt the data
+      const encrypted: CryptoJS.lib.WordArray = 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: CryptoJS.lib.WordArray = 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: Required<CryptoConfig> = { ...this.DEFAULT_CONFIG, ...config };
+
+      // Convert from URL-safe base64
+      const base64: string = encryptedData
+        .replace(/-/g, '+')
+        .replace(/_/g, '/');
+
+      // Add padding if needed (base64 must be multiple of 4 characters)
+      // This ensures CryptoJS.parse works correctly even when padding was stripped during URL transmission
+      const paddingNeeded: number = (4 - (base64.length % 4)) % 4;
+      const paddedBase64: string = base64 + '='.repeat(paddingNeeded);
+
+      // Validate base64 format before parsing
+      // Check if the string length makes sense for expected minimum byte count
+      // Minimum expected: 48 bytes = ~64 base64 characters (48 * 4/3 = 64)
+      const minExpectedBase64Length: number = Math.ceil((finalConfig.ivLength + finalConfig.saltLength + 16) * 4 / 3);
+      if (paddedBase64.length < minExpectedBase64Length) {
+        if (DyFM_global_settings.log_settings.server_debug || true) {
+          DyFM_Log.H_error(
+            `Encrypted data is too short. Expected at least ${minExpectedBase64Length} base64 characters ` +
+            `(for ${(finalConfig.ivLength + finalConfig.saltLength + 16)} bytes), ` +
+            `but received ${paddedBase64.length} characters (${encryptedData.length} original). ` +
+            `This may indicate the data was truncated during transmission or storage.` +
+            '\n\nEncrypted data: ' + encryptedData,
+            '\n\nkey: ' + key
+          );
+        }
+
+        throw new DyFM_Error({
+          ...this.getDefaultErrorSettings('decrypt'),
+          errorCode: 'DyFM-CRY-DATA-CORRUPTED',
+          message: `Encrypted data is too short. Expected at least ${minExpectedBase64Length} base64 characters ` +
+                   `(for ${(finalConfig.ivLength + finalConfig.saltLength + 16)} bytes), ` +
+                   `but received ${paddedBase64.length} characters (${encryptedData.length} original). ` +
+                   `This may indicate the data was truncated during transmission or storage.`
+        });
+      }
+
+      // Parse the combined data
+      const combined: CryptoJS.lib.WordArray = CryptoJS.enc.Base64.parse(paddedBase64);
+
+      // 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: number = (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. ` +
+                   `Original string length: ${encryptedData.length} characters. ` +
+                   `Base64 length: ${base64.length} characters (${paddedBase64.length} with padding). ` +
+                   `This may indicate the data was truncated during transmission or storage.`
+        });
+      }
+
+      // Extract IV, salt, and ciphertext (skip version for now)
+      const ivStart: number = 0;
+      const saltStart: number = ivStart + finalConfig.ivLength / 4;
+      const cipherStart: number = saltStart + finalConfig.saltLength / 4;
+      
+      const iv: CryptoJS.lib.WordArray = CryptoJS.lib.WordArray.create(combined.words.slice(ivStart, saltStart));
+      const salt: CryptoJS.lib.WordArray = CryptoJS.lib.WordArray.create(combined.words.slice(saltStart, cipherStart));
+      const ciphertext: CryptoJS.lib.WordArray = CryptoJS.lib.WordArray.create(combined.words.slice(cipherStart));
+
+      // Derive key using PBKDF2
+      const derivedKey: CryptoJS.lib.WordArray = this.deriveKey(key, salt, finalConfig);
+
+      // Decrypt the data
+      const decrypted: CryptoJS.lib.WordArray = CryptoJS.AES.decrypt(
+        { ciphertext: ciphertext },
+        derivedKey,
+        {
+          iv: iv,
+          mode: CryptoJS.mode.CBC,
+          padding: CryptoJS.pad.Pkcs7
+        }
+      );
+
+      // Parse JSON
+      const decryptedStr: string = 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: string = customChars || 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+    let complexKey: string = '';
+    
+    // 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 = CryptoJS.lib.WordArray.random(1);
+      const randomValue: number = randomBytes.words[0];
+      const charIndex: number = 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);
+  }
+
+  // ────────────────────────────────────────────────────────────────────────────
+  // AT-REST DB field-encryption — verzió-envelope (opt-in `encrypt:true` mezőkhöz)
+  // ────────────────────────────────────────────────────────────────────────────
+  //
+  // Formátum: `DYENC1:<keyVersion>:<ciphertext>`. A `keyVersion` a jövőbeli kulcs-rotációhoz
+  // (a decrypt a verzióból tudja, melyik kulcs kell). Az envelope-prefix teszi MEGBÍZHATÓVÁ a
+  // "titkosított VAGY legacy plaintext" megkülönböztetést (az `isValidEncryptedData` regex
+  // önmagában plaintextre is illeszkedhet → nem elég a detektáláshoz).
+
+  /** Az AT-REST DB-field-encryption envelope-prefixe. */
+  static readonly DB_ENC_PREFIX: string = 'DYENC1:';
+
+  /**
+   * DB-mező titkosítása verzió-envelope-pel. Visszaad: `DYENC1:<keyVersion>:<ciphertext>`.
+   * A `DyFM_Crypto.encrypt` determinisztikus (Q3: elfogadott promptra) — üres/undefined/null-ra
+   * dob, ezért a HÍVÓ (nts-transzform) skip-eli az ilyen értékeket.
+   *
+   * @param data A titkosítandó érték
+   * @param key A titkosító kulcs (FDP_CORE_DBCONTENT_CRYPT_KEY)
+   * @param keyVersion A kulcs-verzió (rotációhoz; default 1)
+   */
+  static encryptDbValue<T>(data: T, key: string, keyVersion: number = 1, config?: CryptoConfig): string {
+    const ciphertext: string = this.encrypt(data, key, config);
+    return `${this.DB_ENC_PREFIX}${keyVersion}:${ciphertext}`;
+  }
+
+  /** True, ha az érték a DB-enc envelope-pel kezdődik (tehát titkosított, nem legacy plaintext). */
+  static isEncryptedDbValue(value: unknown): value is string {
+    return typeof value === 'string' && value.startsWith(this.DB_ENC_PREFIX);
+  }
+
+  /** A DB-enc envelope `keyVersion`-je, vagy `null` ha az érték nem envelope. */
+  static getDbValueKeyVersion(value: unknown): number | null {
+    if (!this.isEncryptedDbValue(value)) {
+      return null;
+    }
+    const rest: string = value.slice(this.DB_ENC_PREFIX.length);
+    const sep: number = rest.indexOf(':');
+    if (sep < 0) {
+      return null;
+    }
+    const parsed: number = Number(rest.slice(0, sep));
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+
+  /**
+   * DB-enc envelope visszafejtése. A hívó a `getDbValueKeyVersion` alapján oldja fel a megfelelő
+   * kulcsot, és azt adja át. Ha az érték NEM envelope (legacy plaintext), a hívó NE ezt hívja
+   * (a read-transzform envelope-detektálással szűr → a plaintext változatlanul jön vissza).
+   */
+  static decryptDbValue<T>(value: string, key: string, config?: CryptoConfig): T {
+    if (!this.isEncryptedDbValue(value)) {
+      throw new DyFM_Error({
+        ...this.getDefaultErrorSettings('decrypt'),
+        errorCode: 'DyFM-CRY-ENV-MISSING',
+        message: 'Value is not a DB-encryption envelope (missing DYENC1: prefix).',
+      });
+    }
+    const rest: string = value.slice(this.DB_ENC_PREFIX.length);
+    const sep: number = rest.indexOf(':');
+    const ciphertext: string = rest.slice(sep + 1);
+    return this.decrypt<T>(ciphertext, key, config);
+  }
+
+  /**
+   * 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: string = encryptedData
+        .replace(/-/g, '+')
+        .replace(/_/g, '/');
+
+      // Parse the combined data
+      const combined: CryptoJS.lib.WordArray = CryptoJS.enc.Base64.parse(base64);
+      
+      // For now, just check if the data has minimum required length
+      const minLength: number = (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}`
+      };
+    }
+  }
+
+  /**
+   * Gets default error settings with enhanced debugging information
+   */
+  private static getDefaultErrorSettings(operation: string, error?: any): DyFM_Error_Settings {
+    const baseSettings: DyFM_Error_Settings = {
+      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, ' +
+                              '\n  5) Data truncation during transmission (check HTTP header size limits, URL length limits), ' +
+                              '\n  6) Missing base64 padding (should be automatically handled, but may indicate transmission issues).';
+      
+      // Add specific guidance for truncation issues (like the "18 bytes" error)
+      baseSettings.message += '\n\nFor truncation issues (e.g., "received 18 bytes"): ' +
+                              '\n  - Check if data is being truncated in HTTP headers (Nginx default: 4-8KB, configurable), ' +
+                              '\n  - Verify URL parameter length limits if passed via query string, ' +
+                              '\n  - Check database field size limits if stored, ' +
+                              '\n  - Ensure proxy/load balancer header size limits are sufficient, ' +
+                              '\n  - Verify the encrypted data string length matches expected size before decryption.';
+    } 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;
+  }
+}