@futdevpro/fsm-dynamo 1.16.39 → 1.20.2

package/build/_modules/crypto/_collections/crypto.util.js

@@ -1,657 +1,657 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.DyFM_Crypto = void 0;
-const tslib_1 = require("tslib");
-const CryptoJS = tslib_1.__importStar(require("crypto-js"));
-const error_control_model_1 = require("../../../_models/control-models/error.control-model");
-const object_util_1 = require("../../../_collections/utils/object.util");
-const global_settings_const_1 = require("../../../_collections/constants/global-settings.const");
-const log_util_1 = require("../../../_collections/utils/log.util");
-// 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.
- */
-class DyFM_Crypto {
-    static CRYPTO_VERSION = '1.0';
-    static DEFAULT_CONFIG = {
-        ivLength: 16, // 128 bits
-        saltLength: 16, // 128 bits
-        keyIterations: 1000, // Reduced for better performance and stability
-        keySize: 8 // 256 bits (8 * 32)
-    };
-    static defaultErrorUserMsg = `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
-     */
-    static validateInput(data, key, operation) {
-        // Validate key
-        if (!key) {
-            throw new error_control_model_1.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 error_control_model_1.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 error_control_model_1.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
-     */
-    static validateEncryptData(data) {
-        if (data === undefined) {
-            throw new error_control_model_1.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 error_control_model_1.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 error_control_model_1.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
-     */
-    static validateDecryptData(data) {
-        if (data === undefined) {
-            throw new error_control_model_1.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 error_control_model_1.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 error_control_model_1.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 error_control_model_1.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 error_control_model_1.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 error_control_model_1.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
-     */
-    static generateIV(data, key, config) {
-        // 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
-     */
-    static generateSalt(data, key, config) {
-        // 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
-     */
-    static createDeterministicSeed(data, key, purpose) {
-        // Create a consistent seed that includes all relevant factors
-        // Order matters: data + key + purpose for consistency
-        const seed = `${data}|${key}|${purpose}`;
-        return seed;
-    }
-    /**
-     * Derives a key using PBKDF2 with reduced iterations for stability
-     */
-    static deriveKey(key, salt, config) {
-        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
-     */
-    static safeSerialize(data) {
-        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 error_control_model_1.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
-     */
-    static deterministicStringify(obj) {
-        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
-     */
-    static safeDeserialize(data) {
-        try {
-            if (!data || data.trim().length === 0) {
-                throw new error_control_model_1.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 = object_util_1.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 = object_util_1.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;
-        }
-        catch (error) {
-            if (error instanceof error_control_model_1.DyFM_Error) {
-                throw error;
-            }
-            throw new error_control_model_1.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(data, key, config) {
-        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 error_control_model_1.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(encryptedData, key, config) {
-        try {
-            this.validateInput(encryptedData, key, 'decrypt');
-            const finalConfig = { ...this.DEFAULT_CONFIG, ...config };
-            // Convert from URL-safe base64
-            const base64 = 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 = (4 - (base64.length % 4)) % 4;
-            const paddedBase64 = 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 = Math.ceil((finalConfig.ivLength + finalConfig.saltLength + 16) * 4 / 3);
-            if (paddedBase64.length < minExpectedBase64Length) {
-                if (global_settings_const_1.DyFM_global_settings.log_settings.server_debug || true) {
-                    log_util_1.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 error_control_model_1.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.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 = (finalConfig.ivLength + finalConfig.saltLength + 16) / 4; // 16 bytes minimum for ciphertext
-            if (combined.words.length < minLength) {
-                throw new error_control_model_1.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 = 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 error_control_model_1.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(decryptedStr);
-        }
-        catch (error) {
-            // Check if it's already a DyFM_Error
-            if (error instanceof error_control_model_1.DyFM_Error) {
-                throw error;
-            }
-            // Handle specific decryption errors
-            if (error instanceof Error) {
-                if (error.message.includes('Malformed UTF-8')) {
-                    throw new error_control_model_1.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 error_control_model_1.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 error_control_model_1.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 = 32, customChars) {
-        // 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) {
-        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 DB_ENC_PREFIX = '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(data, key, keyVersion = 1, config) {
-        const ciphertext = 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) {
-        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) {
-        if (!this.isEncryptedDbValue(value)) {
-            return null;
-        }
-        const rest = value.slice(this.DB_ENC_PREFIX.length);
-        const sep = rest.indexOf(':');
-        if (sep < 0) {
-            return null;
-        }
-        const parsed = 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(value, key, config) {
-        if (!this.isEncryptedDbValue(value)) {
-            throw new error_control_model_1.DyFM_Error({
-                ...this.getDefaultErrorSettings('decrypt'),
-                errorCode: 'DyFM-CRY-ENV-MISSING',
-                message: 'Value is not a DB-encryption envelope (missing DYENC1: prefix).',
-            });
-        }
-        const rest = value.slice(this.DB_ENC_PREFIX.length);
-        const sep = rest.indexOf(':');
-        const ciphertext = rest.slice(sep + 1);
-        return this.decrypt(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) {
-        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}`
-            };
-        }
-    }
-    /**
-     * Gets default error settings with enhanced debugging information
-     */
-    static getDefaultErrorSettings(operation, error) {
-        const baseSettings = {
-            status: error?.___status ?? error?.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;
-    }
-}
-exports.DyFM_Crypto = DyFM_Crypto;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyFM_Crypto = void 0;
+const tslib_1 = require("tslib");
+const CryptoJS = tslib_1.__importStar(require("crypto-js"));
+const error_control_model_1 = require("../../../_models/control-models/error.control-model");
+const object_util_1 = require("../../../_collections/utils/object.util");
+const global_settings_const_1 = require("../../../_collections/constants/global-settings.const");
+const log_util_1 = require("../../../_collections/utils/log.util");
+// 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.
+ */
+class DyFM_Crypto {
+    static CRYPTO_VERSION = '1.0';
+    static DEFAULT_CONFIG = {
+        ivLength: 16, // 128 bits
+        saltLength: 16, // 128 bits
+        keyIterations: 1000, // Reduced for better performance and stability
+        keySize: 8 // 256 bits (8 * 32)
+    };
+    static defaultErrorUserMsg = `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
+     */
+    static validateInput(data, key, operation) {
+        // Validate key
+        if (!key) {
+            throw new error_control_model_1.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 error_control_model_1.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 error_control_model_1.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
+     */
+    static validateEncryptData(data) {
+        if (data === undefined) {
+            throw new error_control_model_1.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 error_control_model_1.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 error_control_model_1.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
+     */
+    static validateDecryptData(data) {
+        if (data === undefined) {
+            throw new error_control_model_1.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 error_control_model_1.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 error_control_model_1.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 error_control_model_1.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 error_control_model_1.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 error_control_model_1.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
+     */
+    static generateIV(data, key, config) {
+        // 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
+     */
+    static generateSalt(data, key, config) {
+        // 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
+     */
+    static createDeterministicSeed(data, key, purpose) {
+        // Create a consistent seed that includes all relevant factors
+        // Order matters: data + key + purpose for consistency
+        const seed = `${data}|${key}|${purpose}`;
+        return seed;
+    }
+    /**
+     * Derives a key using PBKDF2 with reduced iterations for stability
+     */
+    static deriveKey(key, salt, config) {
+        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
+     */
+    static safeSerialize(data) {
+        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 error_control_model_1.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
+     */
+    static deterministicStringify(obj) {
+        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
+     */
+    static safeDeserialize(data) {
+        try {
+            if (!data || data.trim().length === 0) {
+                throw new error_control_model_1.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 = object_util_1.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 = object_util_1.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;
+        }
+        catch (error) {
+            if (error instanceof error_control_model_1.DyFM_Error) {
+                throw error;
+            }
+            throw new error_control_model_1.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(data, key, config) {
+        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 error_control_model_1.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(encryptedData, key, config) {
+        try {
+            this.validateInput(encryptedData, key, 'decrypt');
+            const finalConfig = { ...this.DEFAULT_CONFIG, ...config };
+            // Convert from URL-safe base64
+            const base64 = 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 = (4 - (base64.length % 4)) % 4;
+            const paddedBase64 = 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 = Math.ceil((finalConfig.ivLength + finalConfig.saltLength + 16) * 4 / 3);
+            if (paddedBase64.length < minExpectedBase64Length) {
+                if (global_settings_const_1.DyFM_global_settings.log_settings.server_debug || true) {
+                    log_util_1.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 error_control_model_1.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.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 = (finalConfig.ivLength + finalConfig.saltLength + 16) / 4; // 16 bytes minimum for ciphertext
+            if (combined.words.length < minLength) {
+                throw new error_control_model_1.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 = 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 error_control_model_1.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(decryptedStr);
+        }
+        catch (error) {
+            // Check if it's already a DyFM_Error
+            if (error instanceof error_control_model_1.DyFM_Error) {
+                throw error;
+            }
+            // Handle specific decryption errors
+            if (error instanceof Error) {
+                if (error.message.includes('Malformed UTF-8')) {
+                    throw new error_control_model_1.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 error_control_model_1.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 error_control_model_1.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 = 32, customChars) {
+        // 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) {
+        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 DB_ENC_PREFIX = '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(data, key, keyVersion = 1, config) {
+        const ciphertext = 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) {
+        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) {
+        if (!this.isEncryptedDbValue(value)) {
+            return null;
+        }
+        const rest = value.slice(this.DB_ENC_PREFIX.length);
+        const sep = rest.indexOf(':');
+        if (sep < 0) {
+            return null;
+        }
+        const parsed = 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(value, key, config) {
+        if (!this.isEncryptedDbValue(value)) {
+            throw new error_control_model_1.DyFM_Error({
+                ...this.getDefaultErrorSettings('decrypt'),
+                errorCode: 'DyFM-CRY-ENV-MISSING',
+                message: 'Value is not a DB-encryption envelope (missing DYENC1: prefix).',
+            });
+        }
+        const rest = value.slice(this.DB_ENC_PREFIX.length);
+        const sep = rest.indexOf(':');
+        const ciphertext = rest.slice(sep + 1);
+        return this.decrypt(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) {
+        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}`
+            };
+        }
+    }
+    /**
+     * Gets default error settings with enhanced debugging information
+     */
+    static getDefaultErrorSettings(operation, error) {
+        const baseSettings = {
+            status: error?.___status ?? error?.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;
+    }
+}
+exports.DyFM_Crypto = DyFM_Crypto;
 //# sourceMappingURL=crypto.util.js.map