@futdevpro/fsm-dynamo 1.20.92 → 1.20.94

package/build-esm/_modules/ci-tools/index.js

@@ -0,0 +1,6 @@
+// ENUMS
+export * from './_enums/cit-ci-result-code.enum';
+export * from './_enums/cit-ci-step-result-code.enum';
+// MODELS
+export * from './_models/cit-ci-result-info.data-models';
+export * from './_models/cit-ci-step-result.interface';

package/build-esm/_modules/crypto/_collections/crypto-v1.util.js

@@ -0,0 +1,199 @@
+import * as CryptoJS from 'crypto-js';
+import { DyFM_Object } from '../../../_collections/utils/object.util';
+import { DyFM_Error } from '../../../_models/control-models/error.control-model';
+/**
+ * A utility class for secure encryption and decryption of data
+ * Uses AES-256-CBC with deterministic IV and salt for consistent results
+ */
+export class DyFM_Crypto {
+    static defaultErrorUserMsg = `We encountered an unhandled Authentication Error, ` +
+        `\nplease contact the responsible development team.`;
+    /**
+     * Validates the encryption key
+     */
+    static validateKey(key) {
+        if (!key || typeof key !== 'string') {
+            throw new DyFM_Error({
+                status: 401,
+                message: 'Encryption key is required and must be a string',
+                errorCode: 'DyFM-CRY-KEY-REQ'
+            });
+        }
+        if (key.trim().length === 0) {
+            throw new DyFM_Error({
+                status: 401,
+                message: 'Encryption key cannot be empty or whitespace-only',
+                errorCode: 'DyFM-CRY-KEY-EMPTY'
+            });
+        }
+    }
+    /**
+     * Safely serializes data to JSON
+     */
+    static safeSerialize(data) {
+        try {
+            return JSON.stringify(data);
+        }
+        catch (error) {
+            throw new DyFM_Error({
+                ...this.getDefaultErrorSettings('safeSerialize', error),
+                errorCode: 'DyFM-CRY-SER',
+                message: 'Failed to serialize data'
+            });
+        }
+    }
+    /**
+     * Safely deserializes JSON data
+     */
+    static safeDeserialize(data) {
+        try {
+            let parsed = DyFM_Object.failableSafeParseJSON(data);
+            // Handle double-stringified JSON
+            if (typeof parsed === 'string') {
+                try {
+                    parsed = DyFM_Object.failableSafeParseJSON(parsed);
+                }
+                catch {
+                    // If second parse fails, return the string as is
+                    return parsed;
+                }
+            }
+            // Handle primitive values
+            if (typeof parsed === 'string' || typeof parsed === 'number' || typeof parsed === 'boolean') {
+                return parsed;
+            }
+            return parsed;
+        }
+        catch (error) {
+            throw new DyFM_Error({
+                ...this.getDefaultErrorSettings('safeDeserialize', error),
+                errorCode: 'DyFM-CRY-DES',
+                message: 'Failed to deserialize data'
+            });
+        }
+    }
+    /**
+     * Derives a 256-bit key from the passphrase using SHA256
+     */
+    static deriveKey(key) {
+        return CryptoJS.SHA256(key);
+    }
+    /**
+     * Creates a deterministic IV from the key only
+     */
+    static createDeterministicIV(key) {
+        const hash = CryptoJS.SHA256(key + ':iv');
+        return CryptoJS.lib.WordArray.create(hash.words.slice(0, 4)); // Use first 16 bytes (128 bits)
+    }
+    /**
+     * Encrypts data using AES-256-CBC with deterministic key and IV
+     * @param data The data to encrypt
+     * @param key The encryption key
+     * @returns URL-safe encrypted string
+     * @throws {DyFM_Error} if encryption fails
+     */
+    static encrypt(data, key) {
+        try {
+            // Validate key
+            this.validateKey(key);
+            // Validate data
+            if (data === undefined || data === null) {
+                throw new DyFM_Error({
+                    status: 401,
+                    message: 'Data cannot be undefined or null',
+                    errorCode: 'DyFM-CRY-DATA-NULL'
+                });
+            }
+            // Convert data to string
+            const dataStr = this.safeSerialize(data);
+            // Derive key and IV
+            const aesKey = this.deriveKey(key);
+            const iv = this.createDeterministicIV(key);
+            // Encrypt the data with deterministic key and IV
+            const encrypted = CryptoJS.AES.encrypt(dataStr, aesKey, {
+                iv: iv,
+                mode: CryptoJS.mode.CBC,
+                padding: CryptoJS.pad.Pkcs7
+            });
+            // Convert to URL-safe base64
+            const base64 = encrypted.ciphertext.toString(CryptoJS.enc.Base64);
+            return base64
+                .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
+     * @returns The decrypted data
+     * @throws {DyFM_Error} if decryption fails
+     */
+    static decrypt(encryptedData, key) {
+        try {
+            // Validate key
+            this.validateKey(key);
+            // Validate encrypted data
+            if (!encryptedData || typeof encryptedData !== 'string') {
+                throw new DyFM_Error({
+                    status: 401,
+                    message: 'Encrypted data is required and must be a string',
+                    errorCode: 'DyFM-CRY-DATA-REQ'
+                });
+            }
+            // Convert from URL-safe base64
+            let base64 = encryptedData
+                .replace(/-/g, '+')
+                .replace(/_/g, '/');
+            // Add padding if needed
+            const padLength = 4 - (base64.length % 4);
+            if (padLength < 4) {
+                base64 += '='.repeat(padLength);
+            }
+            // Derive key and IV
+            const aesKey = this.deriveKey(key);
+            const iv = this.createDeterministicIV(key);
+            // Decrypt the data
+            const encryptedWA = CryptoJS.enc.Base64.parse(base64);
+            const decrypted = CryptoJS.AES.decrypt({ ciphertext: encryptedWA }, aesKey, {
+                iv: iv,
+                mode: CryptoJS.mode.CBC,
+                padding: CryptoJS.pad.Pkcs7
+            });
+            // Parse JSON
+            const decryptedStr = decrypted.toString(CryptoJS.enc.Utf8);
+            if (!decryptedStr) {
+                throw new DyFM_Error({
+                    status: 401,
+                    message: 'Failed to decrypt data - invalid key or corrupted data',
+                    errorCode: 'DyFM-CRY-DEC-FAIL'
+                });
+            }
+            return this.safeDeserialize(decryptedStr);
+        }
+        catch (error) {
+            throw new DyFM_Error({
+                ...this.getDefaultErrorSettings('decrypt', error),
+                errorCode: 'DyFM-CRY-DRY',
+            });
+        }
+    }
+    /**
+     * Gets default error settings
+     */
+    static getDefaultErrorSettings(operation, error) {
+        return {
+            status: error?.___status ?? error?.status ?? 401,
+            message: `Crypto operation "${operation}" failed; ` + DyFM_Error.getAnyMessage(error),
+            error: error,
+            errorCode: 'DyFM-CRY-ERR'
+        };
+    }
+}

package/build-esm/_modules/crypto/_collections/crypto-v2.util.js

@@ -0,0 +1,273 @@
+import * as CryptoJS from 'crypto-js';
+import { DyFM_Error } from '../../../_models/control-models/error.control-model';
+import { DyFM_Object } from '../../../_collections/utils/object.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.
+ */
+export class DyFM_Crypto {
+    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
+     * @throws {DyFM_Error} if validation fails
+     */
+    static validateInput(data, key) {
+        if (!key || typeof key !== 'string' || key.trim().length === 0) {
+            throw new DyFM_Error({
+                ...this.getDefaultErrorSettings('validateInput'),
+                errorCode: 'DyFM-CRY-IKY',
+                message: 'Invalid encryption key',
+            });
+        }
+        // Allow null values but not undefined
+        if (data === undefined) {
+            throw new DyFM_Error({
+                ...this.getDefaultErrorSettings('validateInput'),
+                errorCode: 'DyFM-CRY-IDT',
+                message: `Invalid data to encrypt/decrypt (is "${data}")`,
+            });
+        }
+    }
+    /**
+     * Generates a deterministic IV based on the input data and key
+     * Uses MD5 for better stability across different CryptoJS versions
+     *
+     * @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) {
+        // Use MD5 for better stability - simpler hash algorithm, more consistent across versions
+        const combined = data + key;
+        const hash = CryptoJS.MD5(combined);
+        // Use slice(0, 4) for 16 bytes - more stable than division operations
+        return CryptoJS.lib.WordArray.create(hash.words.slice(0, 4));
+    }
+    /**
+     * Generates a deterministic salt based on the input data and key
+     * Uses MD5 for better stability across different CryptoJS versions
+     *
+     * @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) {
+        // Use MD5 for better stability - simpler hash algorithm, more consistent across versions
+        const combined = key + data;
+        const hash = CryptoJS.MD5(combined);
+        // Use slice(0, 4) for 16 bytes - more stable than division operations
+        return CryptoJS.lib.WordArray.create(hash.words.slice(0, 4));
+    }
+    /**
+     * 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
+     */
+    static safeSerialize(data) {
+        try {
+            // Always use JSON.stringify to ensure proper serialization/deserialization
+            return JSON.stringify(data);
+        }
+        catch (error) {
+            throw new DyFM_Error({
+                ...this.getDefaultErrorSettings('safeSerialize', error),
+                errorCode: 'DyFM-CRY-SER',
+                message: 'Failed to serialize data',
+            });
+        }
+    }
+    /**
+     * Safely deserializes JSON data
+     */
+    static safeDeserialize(data) {
+        try {
+            //let parsed = JSON.parse(data);
+            let parsed = DyFM_Object.failableSafeParseJSON(data);
+            // Handle double-stringified JSON (or more levels of stringification)
+            let maxAttempts = 3; // Prevent infinite loops
+            while (typeof parsed === 'string' && maxAttempts > 0) {
+                try {
+                    //const nextParsed = JSON.parse(parsed);
+                    const nextParsed = DyFM_Object.failableSafeParseJSON(parsed);
+                    // Only continue if parsing actually changed the result
+                    if (nextParsed !== parsed) {
+                        parsed = nextParsed;
+                        maxAttempts--;
+                    }
+                    else {
+                        break;
+                    }
+                }
+                catch {
+                    // If parse fails, return current state
+                    break;
+                }
+            }
+            // Handle primitive values
+            /* if (typeof parsed === 'string' || typeof parsed === 'number' || typeof parsed === 'boolean') {
+              return parsed as T;
+            } */
+            return parsed;
+        }
+        catch (error) {
+            throw new DyFM_Error({
+                ...this.getDefaultErrorSettings('safeDeserialize', error),
+                errorCode: 'DyFM-CRY-DES',
+                message: 'Failed to deserialize data',
+            });
+        }
+    }
+    /**
+     * 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);
+            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
+            const combined = iv.concat(salt).concat(encrypted.ciphertext);
+            // Convert to URL-safe base64
+            return CryptoJS.enc.Base64.stringify(combined)
+                .replace(/\+/g, '-')
+                .replace(/\//g, '_')
+                .replace(/=+$/, '');
+        }
+        catch (error) {
+            throw new DyFM_Error({
+                ...this.getDefaultErrorSettings('encrypt', error),
+                errorCode: 'DyFM-CRY-ENC',
+            });
+        }
+    }
+    /**
+     * Decrypts data that was encrypted using encrypt()
+     * @param encryptedData The encrypted data
+     * @param key The decryption key
+     * @param config Optional configuration
+     * @returns The decrypted data
+     * @throws {DyFM_Error} if decryption fails
+     */
+    static decrypt(encryptedData, key, config) {
+        try {
+            this.validateInput(encryptedData, key);
+            const finalConfig = { ...this.DEFAULT_CONFIG, ...config };
+            // Convert from URL-safe base64
+            const base64 = encryptedData
+                .replace(/-/g, '+')
+                .replace(/_/g, '/');
+            // Parse the combined data
+            const combined = CryptoJS.enc.Base64.parse(base64);
+            // 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('Invalid encrypted data length');
+            }
+            // Extract IV, salt, and ciphertext
+            const iv = CryptoJS.lib.WordArray.create(combined.words.slice(0, finalConfig.ivLength / 4));
+            const salt = CryptoJS.lib.WordArray.create(combined.words.slice(finalConfig.ivLength / 4, (finalConfig.ivLength + finalConfig.saltLength) / 4));
+            const ciphertext = CryptoJS.lib.WordArray.create(combined.words.slice((finalConfig.ivLength + finalConfig.saltLength) / 4));
+            // 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);
+            return this.safeDeserialize(decryptedStr);
+        }
+        catch (error) {
+            throw new DyFM_Error({
+                ...this.getDefaultErrorSettings('decrypt', error),
+                errorCode: 'DyFM-CRY-DRY',
+            });
+        }
+    }
+    /**
+     * Generates a secure random key
+     * @param length Length of the key in bytes (default: 32)
+     * @returns A secure random key
+     */
+    static generateKey(length = 32) {
+        return CryptoJS.lib.WordArray.random(length).toString();
+    }
+    /**
+     * 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);
+    }
+    /**
+     * Gets default error settings
+     */
+    static getDefaultErrorSettings(operation, error) {
+        return {
+            status: error?.___status ?? error?.status ?? 401,
+            message: `Crypto operation "${operation}" failed`,
+            error: error,
+            errorCode: 'DyFM-CRY-ERR',
+        };
+    }
+}