@futdevpro/fsm-dynamo 1.16.38 → 1.16.40

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

@@ -1,331 +1,331 @@
-import * as CryptoJS from 'crypto-js';
-
-import { 
-  DyFM_Error, 
-  DyFM_Error_Settings 
-} from '../../../_models/control-models/error.control-model';
-import { DyFM_Object } from '../../../_collections/utils/object.util';
-
-
-/**
- * Configuration options for encryption/decryption
- */
-export interface CryptoConfig {
-  ivLength?: number;
-  saltLength?: number;
-  keyIterations?: number;
-  keySize?: number;
-}
-
-// Compact: about 60–80 character tokens, not 200+
-// Non-standard: hard to reverse-engineer
-// Usable in cookies, headers, URLs
-
-/**
- * A utility class for stable encryption and decryption of data
- * Uses AES-256-CBC with deterministic IV and salt for consistent results across systems
- * Prioritizes reliability and cross-platform compatibility over security
- * 
- * @important DETERMINISTIC ENCRYPTION: This implementation produces identical encrypted 
- * output for identical input data and key across different systems and multiple calls.
- * The same input will ALWAYS generate the same encrypted string on any platform.
- * 
- * @warning SECURITY NOTICE: This deterministic behavior is intentional for cross-platform
- * compatibility but reduces security. Identical inputs produce identical outputs, which
- * can be exploited for pattern analysis attacks. Use only when consistency across
- * systems is more important than cryptographic security.
- */
-export class DyFM_Crypto {
-  private static readonly DEFAULT_CONFIG: Required<CryptoConfig> = {
-    ivLength: 16, // 128 bits
-    saltLength: 16, // 128 bits
-    keyIterations: 1000, // Reduced for better performance and stability
-    keySize: 8, // 256 bits (8 * 32)
-  };
-  private static readonly defaultErrorUserMsg = 
-    `We encountered an unhandled Authentication Error, ` +
-    `\nplease contact the responsible development team.`;
-
-  /**
-   * Validates the input data and key
-   * @throws {DyFM_Error} if validation fails
-   */
-  private static validateInput(data: any, key: string): void {
-    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
-   */
-  private static generateIV(data: string, key: string, config: Required<CryptoConfig>): CryptoJS.lib.WordArray {
-    // 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
-   */
-  private static generateSalt(data: string, key: string, config: Required<CryptoConfig>): CryptoJS.lib.WordArray {
-    // 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
-   */
-  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
-   */
-  private static safeSerialize<T>(data: T): string {
-    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
-   */
-  private static safeDeserialize<T>(data: string): T {
-    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 as T;
-    } 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<T>(data: T, key: string, config?: CryptoConfig): string {
-    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<T>(encryptedData: string, key: string, config?: CryptoConfig): T {
-    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<T>(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: number = 32): string {
-    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: string): boolean {
-    if (!encryptedData || typeof encryptedData !== 'string') {
-      return false;
-    }
-
-    return /^[A-Za-z0-9\-_]+$/.test(encryptedData);
-  }
-
-  /**
-   * Gets default error settings
-   */
-  private static getDefaultErrorSettings(operation: string, error?: any): DyFM_Error_Settings {
-    return {
-      status: (error as DyFM_Error)?.___status ?? (error as any)?.status ?? 401,
-      message: `Crypto operation "${operation}" failed`,
-      error: error,
-      errorCode: 'DyFM-CRY-ERR',
-    };
-  }
-}
+import * as CryptoJS from 'crypto-js';
+
+import { 
+  DyFM_Error, 
+  DyFM_Error_Settings 
+} from '../../../_models/control-models/error.control-model';
+import { DyFM_Object } from '../../../_collections/utils/object.util';
+
+
+/**
+ * Configuration options for encryption/decryption
+ */
+export interface CryptoConfig {
+  ivLength?: number;
+  saltLength?: number;
+  keyIterations?: number;
+  keySize?: number;
+}
+
+// Compact: about 60–80 character tokens, not 200+
+// Non-standard: hard to reverse-engineer
+// Usable in cookies, headers, URLs
+
+/**
+ * A utility class for stable encryption and decryption of data
+ * Uses AES-256-CBC with deterministic IV and salt for consistent results across systems
+ * Prioritizes reliability and cross-platform compatibility over security
+ * 
+ * @important DETERMINISTIC ENCRYPTION: This implementation produces identical encrypted 
+ * output for identical input data and key across different systems and multiple calls.
+ * The same input will ALWAYS generate the same encrypted string on any platform.
+ * 
+ * @warning SECURITY NOTICE: This deterministic behavior is intentional for cross-platform
+ * compatibility but reduces security. Identical inputs produce identical outputs, which
+ * can be exploited for pattern analysis attacks. Use only when consistency across
+ * systems is more important than cryptographic security.
+ */
+export class DyFM_Crypto {
+  private static readonly DEFAULT_CONFIG: Required<CryptoConfig> = {
+    ivLength: 16, // 128 bits
+    saltLength: 16, // 128 bits
+    keyIterations: 1000, // Reduced for better performance and stability
+    keySize: 8, // 256 bits (8 * 32)
+  };
+  private static readonly defaultErrorUserMsg = 
+    `We encountered an unhandled Authentication Error, ` +
+    `\nplease contact the responsible development team.`;
+
+  /**
+   * Validates the input data and key
+   * @throws {DyFM_Error} if validation fails
+   */
+  private static validateInput(data: any, key: string): void {
+    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
+   */
+  private static generateIV(data: string, key: string, config: Required<CryptoConfig>): CryptoJS.lib.WordArray {
+    // 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
+   */
+  private static generateSalt(data: string, key: string, config: Required<CryptoConfig>): CryptoJS.lib.WordArray {
+    // 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
+   */
+  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
+   */
+  private static safeSerialize<T>(data: T): string {
+    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
+   */
+  private static safeDeserialize<T>(data: string): T {
+    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 as T;
+    } 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<T>(data: T, key: string, config?: CryptoConfig): string {
+    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<T>(encryptedData: string, key: string, config?: CryptoConfig): T {
+    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<T>(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: number = 32): string {
+    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: string): boolean {
+    if (!encryptedData || typeof encryptedData !== 'string') {
+      return false;
+    }
+
+    return /^[A-Za-z0-9\-_]+$/.test(encryptedData);
+  }
+
+  /**
+   * Gets default error settings
+   */
+  private static getDefaultErrorSettings(operation: string, error?: any): DyFM_Error_Settings {
+    return {
+      status: (error as DyFM_Error)?.___status ?? (error as any)?.status ?? 401,
+      message: `Crypto operation "${operation}" failed`,
+      error: error,
+      errorCode: 'DyFM-CRY-ERR',
+    };
+  }
+}