@vvlad1973/crypto 2.1.3 → 2.3.0

package/dist/__tests__/crypto.test.js

@@ -35,7 +35,6 @@ describe('Crypto', () => {
         expect(crypto).toBeDefined();
     });
     it('should return UUIDv4', () => {
-        const crypto = new Crypto(options);
         const uuid = Crypto.getUUID();
         const uuidv4Regex = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
         expect(uuid).toMatch(uuidv4Regex);
@@ -153,6 +152,50 @@ describe('isCrypto', () => {
         expect(isCrypto(plainObject)).toBe(false);
     });
 });
+describe('encryptStorable / decryptStorable', () => {
+    const password = 'testPassword';
+    const salt = 'testSalt';
+    const plainText = 'Hello, World!';
+    it('round-trips correctly', () => {
+        const crypto = new Crypto(password, salt);
+        expect(crypto.decryptStorable(crypto.encryptStorable(plainText))).toBe(plainText);
+    });
+    it('produces different ciphertext on each call (fresh IV)', () => {
+        const crypto = new Crypto(password, salt);
+        expect(crypto.encryptStorable(plainText)).not.toBe(crypto.encryptStorable(plainText));
+    });
+    it('output is longer than encrypt() by exactly 16 bytes (32 hex chars)', () => {
+        const crypto = new Crypto(password, salt, 'sha512', 1000, 32, 0);
+        const storable = crypto.encryptStorable(plainText);
+        const legacy = crypto.encrypt(plainText);
+        expect(storable.length).toBe(legacy.length + 32);
+    });
+    it('two different instances with same key can cross-decrypt', () => {
+        const a = new Crypto(password, salt);
+        const b = new Crypto(password, salt);
+        expect(b.decryptStorable(a.encryptStorable(plainText))).toBe(plainText);
+    });
+    it('throws RangeError when input is too short', () => {
+        const crypto = new Crypto(password, salt);
+        expect(() => crypto.decryptStorable('aabbcc')).toThrow(RangeError);
+    });
+    it('handles empty string', () => {
+        const crypto = new Crypto(password, salt);
+        expect(crypto.decryptStorable(crypto.encryptStorable(''))).toBe('');
+    });
+    it('handles Unicode text', () => {
+        const crypto = new Crypto(password, salt);
+        const unicode = '🔐 Шифрование 中文';
+        expect(crypto.decryptStorable(crypto.encryptStorable(unicode))).toBe(unicode);
+    });
+    it('construction-time IV does not affect result', () => {
+        const c0 = new Crypto(password, salt, 'sha512', 1000, 32, 0);
+        const c5 = new Crypto(password, salt, 'sha512', 1000, 32, 5);
+        // Both should decrypt successfully regardless of instance IV
+        expect(c5.decryptStorable(c0.encryptStorable(plainText))).toBe(plainText);
+        expect(c0.decryptStorable(c5.encryptStorable(plainText))).toBe(plainText);
+    });
+});
 describe('Compatibility with previous version', () => {
     const plainText = 'Проверка связи';
     let options;

package/dist/crypto.d.ts

@@ -40,16 +40,51 @@ export declare class Crypto {
     private convertNumberToIV;
     /**
      * Encrypt a text string.
+     * Uses the IV supplied at construction time (fixed or random-at-construct).
+     * The IV is **not** embedded in the output — both sides must use the same IV.
+     * For persistent storage use {@link encryptStorable} instead.
+     *
      * @param {string} text - The plain text to encrypt.
      * @returns {string} The encrypted text as a hex string.
      */
     encrypt(text: string): string;
     /**
-     * Decrypt an encrypted text string.
+     * Decrypt an encrypted text string produced by {@link encrypt}.
+     * Uses the IV supplied at construction time.
+     *
      * @param {string} text - The encrypted text as a hex string.
      * @returns {string} The decrypted plain text.
      */
     decrypt(text: string): string;
+    /**
+     * Encrypts text and prepends a fresh random IV to the output.
+     *
+     * Use this method when the ciphertext will be stored (database, file, etc.)
+     * and retrieved later in a different process instance.  A new random IV is
+     * generated for every call, so repeated encryptions of the same plaintext
+     * produce different ciphertexts — no IV reuse across records.
+     *
+     * Output format: `hex( IV[16 bytes] || ciphertext[N bytes] )`
+     *
+     * The construction-time IV is **not** used by this method.
+     *
+     * @param {string} text - The plain text to encrypt.
+     * @returns {string} Hex string containing the prepended IV and ciphertext.
+     * @see {@link decryptStorable}
+     */
+    encryptStorable(text: string): string;
+    /**
+     * Decrypts a value produced by {@link encryptStorable}.
+     *
+     * Extracts the first 16 bytes as the IV, then decrypts the remainder.
+     * The construction-time IV is **not** used by this method.
+     *
+     * @param {string} text - Hex string `IV[16 bytes] || ciphertext` from {@link encryptStorable}.
+     * @returns {string} The decrypted plain text.
+     * @throws {RangeError} When the input is shorter than 16 bytes (32 hex chars).
+     * @see {@link encryptStorable}
+     */
+    decryptStorable(text: string): string;
     /**
      * Returns a UUID ver.4 string.
      * @returns {string} UUID ver.4 string.

package/dist/crypto.js

@@ -53,6 +53,10 @@ export class Crypto {
     }
     /**
      * Encrypt a text string.
+     * Uses the IV supplied at construction time (fixed or random-at-construct).
+     * The IV is **not** embedded in the output — both sides must use the same IV.
+     * For persistent storage use {@link encryptStorable} instead.
+     *
      * @param {string} text - The plain text to encrypt.
      * @returns {string} The encrypted text as a hex string.
      */
@@ -65,7 +69,9 @@ export class Crypto {
         return encrypted.toString('hex');
     }
     /**
-     * Decrypt an encrypted text string.
+     * Decrypt an encrypted text string produced by {@link encrypt}.
+     * Uses the IV supplied at construction time.
+     *
      * @param {string} text - The encrypted text as a hex string.
      * @returns {string} The decrypted plain text.
      */
@@ -78,6 +84,50 @@ export class Crypto {
         ]);
         return decrypted.toString('utf8');
     }
+    /**
+     * Encrypts text and prepends a fresh random IV to the output.
+     *
+     * Use this method when the ciphertext will be stored (database, file, etc.)
+     * and retrieved later in a different process instance.  A new random IV is
+     * generated for every call, so repeated encryptions of the same plaintext
+     * produce different ciphertexts — no IV reuse across records.
+     *
+     * Output format: `hex( IV[16 bytes] || ciphertext[N bytes] )`
+     *
+     * The construction-time IV is **not** used by this method.
+     *
+     * @param {string} text - The plain text to encrypt.
+     * @returns {string} Hex string containing the prepended IV and ciphertext.
+     * @see {@link decryptStorable}
+     */
+    encryptStorable(text) {
+        const iv = randomBytes(16);
+        const cipher = createCipheriv('aes-256-ctr', this.key, iv);
+        const encrypted = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]);
+        return Buffer.concat([iv, encrypted]).toString('hex');
+    }
+    /**
+     * Decrypts a value produced by {@link encryptStorable}.
+     *
+     * Extracts the first 16 bytes as the IV, then decrypts the remainder.
+     * The construction-time IV is **not** used by this method.
+     *
+     * @param {string} text - Hex string `IV[16 bytes] || ciphertext` from {@link encryptStorable}.
+     * @returns {string} The decrypted plain text.
+     * @throws {RangeError} When the input is shorter than 16 bytes (32 hex chars).
+     * @see {@link encryptStorable}
+     */
+    decryptStorable(text) {
+        const buf = Buffer.from(text, 'hex');
+        if (buf.length < 16) {
+            throw new RangeError(`decryptStorable: input too short (${buf.length} bytes); ` +
+                'expected at least 16 bytes for the IV prefix.');
+        }
+        const iv = buf.subarray(0, 16);
+        const ciphertext = buf.subarray(16);
+        const decipher = createDecipheriv('aes-256-ctr', this.key, iv);
+        return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+    }
     /**
      * Returns a UUID ver.4 string.
      * @returns {string} UUID ver.4 string.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvlad1973/crypto",
-  "version": "2.1.3",
+  "version": "2.3.0",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -17,7 +17,7 @@
   "license": "MIT with Commercial Use",
   "description": "A JavaScript class for encrypting and decrypting text using specified cryptographic parameters (algorithm, password, etc.)",
   "devDependencies": {
-    "@types/node": "^25.0.3",
+    "@types/node": "^25.3.3",
     "@typescript-eslint/parser": "^7.18.0",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",

package/src/crypto.ts

@@ -102,6 +102,10 @@ export class Crypto {
 
   /**
    * Encrypt a text string.
+   * Uses the IV supplied at construction time (fixed or random-at-construct).
+   * The IV is **not** embedded in the output — both sides must use the same IV.
+   * For persistent storage use {@link encryptStorable} instead.
+   *
    * @param {string} text - The plain text to encrypt.
    * @returns {string} The encrypted text as a hex string.
    */
@@ -115,7 +119,9 @@ export class Crypto {
   }
 
   /**
-   * Decrypt an encrypted text string.
+   * Decrypt an encrypted text string produced by {@link encrypt}.
+   * Uses the IV supplied at construction time.
+   *
    * @param {string} text - The encrypted text as a hex string.
    * @returns {string} The decrypted plain text.
    */
@@ -129,6 +135,54 @@ export class Crypto {
     return decrypted.toString('utf8');
   }
 
+  /**
+   * Encrypts text and prepends a fresh random IV to the output.
+   *
+   * Use this method when the ciphertext will be stored (database, file, etc.)
+   * and retrieved later in a different process instance.  A new random IV is
+   * generated for every call, so repeated encryptions of the same plaintext
+   * produce different ciphertexts — no IV reuse across records.
+   *
+   * Output format: `hex( IV[16 bytes] || ciphertext[N bytes] )`
+   *
+   * The construction-time IV is **not** used by this method.
+   *
+   * @param {string} text - The plain text to encrypt.
+   * @returns {string} Hex string containing the prepended IV and ciphertext.
+   * @see {@link decryptStorable}
+   */
+  public encryptStorable(text: string): string {
+    const iv = randomBytes(16);
+    const cipher = createCipheriv('aes-256-ctr', this.key, iv);
+    const encrypted = Buffer.concat([cipher.update(text, 'utf8'), cipher.final()]);
+    return Buffer.concat([iv, encrypted]).toString('hex');
+  }
+
+  /**
+   * Decrypts a value produced by {@link encryptStorable}.
+   *
+   * Extracts the first 16 bytes as the IV, then decrypts the remainder.
+   * The construction-time IV is **not** used by this method.
+   *
+   * @param {string} text - Hex string `IV[16 bytes] || ciphertext` from {@link encryptStorable}.
+   * @returns {string} The decrypted plain text.
+   * @throws {RangeError} When the input is shorter than 16 bytes (32 hex chars).
+   * @see {@link encryptStorable}
+   */
+  public decryptStorable(text: string): string {
+    const buf = Buffer.from(text, 'hex');
+    if (buf.length < 16) {
+      throw new RangeError(
+        `decryptStorable: input too short (${buf.length} bytes); ` +
+        'expected at least 16 bytes for the IV prefix.',
+      );
+    }
+    const iv = buf.subarray(0, 16);
+    const ciphertext = buf.subarray(16);
+    const decipher = createDecipheriv('aes-256-ctr', this.key, iv);
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+  }
+
   /**
    * Returns a UUID ver.4 string.
    * @returns {string} UUID ver.4 string.