tiny-essentials 1.1.1 → 1.2.1

package/dist/v1/libs/TinyCrypto.cjs

@@ -2,9 +2,37 @@
 
 var crypto = require('crypto');
 var fs = require('fs');
+var buffer = require('buffer');
 var objFilter = require('../basics/objFilter.cjs');
 
-// Detecta se estamos no browser
+function _interopNamespaceDefault(e) {
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var fs__namespace = /*#__PURE__*/_interopNamespaceDefault(fs);
+
+/**
+ * Determines if the environment is a browser.
+ *
+ * This constant checks if the code is running in a browser environment by verifying if
+ * the `window` object and the `window.document` object are available. It will return `true`
+ * if the environment is a browser, and `false` otherwise (e.g., in a Node.js environment).
+ *
+ * @constant {boolean}
+ */
 const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
 
 /**
@@ -21,8 +49,8 @@ class TinyCrypto {
    *
    * @param {Object} [options={}] - Configuration options for encryption and decryption.
    * @param {string} [options.algorithm='aes-256-gcm'] - The encryption algorithm to use. Recommended: 'aes-256-gcm' for authenticated encryption.
-   * @param {string} [options.outputEncoding='hex'] - The encoding used when returning encrypted data (e.g., 'hex', 'base64').
-   * @param {string} [options.inputEncoding='utf8'] - The encoding used for plaintext inputs (e.g., 'utf8').
+   * @param {BufferEncoding} [options.outputEncoding='hex'] - The encoding used when returning encrypted data (e.g., 'hex', 'base64').
+   * @param {BufferEncoding} [options.inputEncoding='utf8'] - The encoding used for plaintext inputs (e.g., 'utf8').
    * @param {number} [options.authTagLength=16] - The length of the authentication tag used in GCM mode. Usually 16 for AES-256-GCM.
    * @param {Buffer} [options.key] - Optional 32-byte cryptographic key. If not provided, a random key is generated.
    *
@@ -32,15 +60,17 @@ class TinyCrypto {
    * const crypto = new CryptoManager({
    *   algorithm: 'aes-256-gcm',
    *   outputEncoding: 'base64',
-   *   key: crypto.randomBytes(32),
+   *   key: randomBytes(32),
    * });
    */
   constructor(options = {}) {
     this.algorithm = options.algorithm || 'aes-256-gcm';
-    this.outputEncoding = options.outputEncoding || 'hex';
-    this.inputEncoding = options.inputEncoding || 'utf8';
     this.authTagLength = options.authTagLength || 16;
     this.key = options.key || this.generateKey();
+    /** @type {BufferEncoding} */
+    this.outputEncoding = options.outputEncoding || 'hex';
+    /** @type {BufferEncoding} */
+    this.inputEncoding = options.inputEncoding || 'utf8';
   }
 
   /**
@@ -78,10 +108,7 @@ class TinyCrypto {
    *
    * @param {*} data - The data to encrypt. Can be of any supported type (string, number, boolean, Date, JSON, etc.).
    * @param {Buffer} [iv=this.generateIV()] - Optional Initialization Vector (IV). If not provided, a secure random IV is generated.
-   * @returns {Object} An object containing:
-   * - `iv` {string} - The IV used, encoded with the output encoding.
-   * - `encrypted` {string} - The encrypted payload.
-   * - `authTag` {string} - The authentication tag used to verify the integrity of the ciphertext.
+   * @returns {EncryptedDataParams} An object containing the encrypted data.
    *
    * @example
    * const result = cryptoManager.encrypt('Hello, world!');
@@ -95,30 +122,40 @@ class TinyCrypto {
     const plainText = this.#serialize(data);
 
     const cipher = crypto.createCipheriv(this.algorithm, this.key, iv, {
+      // @ts-ignore
       authTagLength: this.authTagLength,
     });
 
+    // @ts-ignore
     let encrypted = cipher.update(plainText, this.inputEncoding);
-    encrypted = Buffer.concat([encrypted, cipher.final()]);
+    // @ts-ignore
+    encrypted = buffer.Buffer.concat([encrypted, cipher.final()]);
     const authTag = cipher.getAuthTag();
 
     return {
+      // @ts-ignore
       iv: iv.toString(this.outputEncoding),
+      // @ts-ignore
       encrypted: encrypted.toString(this.outputEncoding),
+      // @ts-ignore
       authTag: authTag.toString(this.outputEncoding),
     };
   }
 
+  /**
+   * @typedef {Object} EncryptedDataParams
+   * @property {string} iv - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
+   * @property {string} encrypted - The encrypted data to decrypt, encoded with the output encoding.
+   * @property {string} authTag - The authentication tag used to verify the integrity of the encrypted data.
+   */
+
   /**
    * Decrypts a previously encrypted value.
    *
    * The method checks the integrity of the data using the authentication tag (`authTag`) and ensures the data is properly decrypted.
    * After decryption, it automatically deserializes the data back to its original type.
    *
-   * @param {Object} params - An object containing the encrypted data:
-   *   - `iv` {string} - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
-   *   - `encrypted` {string} - The encrypted data to decrypt, encoded with the output encoding.
-   *   - `authTag` {string} - The authentication tag used to verify the integrity of the encrypted data.
+   * @param {EncryptedDataParams} params - An object containing the encrypted data.
    * @param {string|null} [expectedType=null] - Optionally specify the expected type of the decrypted data. If provided, the method will validate the type of the deserialized value.
    * @returns {*} The decrypted value, which will be the original type of the data before encryption.
    * @throws {Error} Throws if the authentication tag doesn't match or the data has been tampered with.
@@ -134,17 +171,21 @@ class TinyCrypto {
    * console.log(decrypted); // Outputs: 'Hello, world!'
    */
   decrypt({ iv, encrypted, authTag }, expectedType = null) {
-    const ivBuffer = Buffer.from(iv, this.outputEncoding);
-    const encryptedBuffer = Buffer.from(encrypted, this.outputEncoding);
-    const authTagBuffer = Buffer.from(authTag, this.outputEncoding);
+    const ivBuffer = buffer.Buffer.from(iv, this.outputEncoding);
+    const encryptedBuffer = buffer.Buffer.from(encrypted, this.outputEncoding);
+    const authTagBuffer = buffer.Buffer.from(authTag, this.outputEncoding);
 
     const decipher = crypto.createDecipheriv(this.algorithm, this.key, ivBuffer, {
+      // @ts-ignore
       authTagLength: this.authTagLength,
     });
 
     decipher.setAuthTag(authTagBuffer);
 
+    /** @type {string} */
+    // @ts-ignore
     let decrypted = decipher.update(encryptedBuffer, null, this.inputEncoding);
+    // @ts-ignore
     decrypted += decipher.final(this.inputEncoding);
     const { value, type } = this.#deserialize(decrypted);
 
@@ -158,10 +199,7 @@ class TinyCrypto {
    * This method decrypts the encrypted data and extracts its type information without fully deserializing the value.
    * It is useful when you need to verify the type of the encrypted data before fully decrypting it.
    *
-   * @param {Object} params - An object containing the encrypted data:
-   *   - `iv` {string} - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
-   *   - `encrypted` {string} - The encrypted data to decrypt, encoded with the output encoding.
-   *   - `authTag` {string} - The authentication tag used to verify the integrity of the encrypted data.
+   * @param {EncryptedDataParams} params - An object containing the encrypted data.
    * @returns {string} The type of the original data (e.g., 'string', 'number', 'date', etc.).
    *
    * @example
@@ -174,17 +212,20 @@ class TinyCrypto {
    * console.log(dataType); // Outputs: 'string'
    */
   getTypeFromEncrypted({ iv, encrypted, authTag }) {
-    const ivBuffer = Buffer.from(iv, this.outputEncoding);
-    const encryptedBuffer = Buffer.from(encrypted, this.outputEncoding);
-    const authTagBuffer = Buffer.from(authTag, this.outputEncoding);
+    const ivBuffer = buffer.Buffer.from(iv, this.outputEncoding);
+    const encryptedBuffer = buffer.Buffer.from(encrypted, this.outputEncoding);
+    const authTagBuffer = buffer.Buffer.from(authTag, this.outputEncoding);
 
     const decipher = crypto.createDecipheriv(this.algorithm, this.key, ivBuffer, {
+      // @ts-ignore
       authTagLength: this.authTagLength,
     });
 
     decipher.setAuthTag(authTagBuffer);
 
+    // @ts-ignore
     let decrypted = decipher.update(encryptedBuffer, null, this.inputEncoding);
+    // @ts-ignore
     decrypted += decipher.final(this.inputEncoding);
 
     const { type } = this.#deserialize(decrypted);
@@ -217,7 +258,7 @@ class TinyCrypto {
       a.download = filename;
       a.click();
       URL.revokeObjectURL(url);
-    } else fs.writeFileSync(filename, data);
+    } else fs__namespace.writeFileSync(filename, data);
   }
 
   /**
@@ -246,7 +287,7 @@ class TinyCrypto {
       a.download = filename;
       a.click();
       URL.revokeObjectURL(url);
-    } else fs.writeFileSync(filename, configData);
+    } else fs__namespace.writeFileSync(filename, configData);
   }
 
   /**
@@ -274,10 +315,12 @@ class TinyCrypto {
   async loadConfigFromFile(file) {
     if (isBrowser) {
       return new Promise((resolve, reject) => {
+        if (!(file instanceof File))
+          return reject(new Error('In browser, the file must be a File object'));
         const reader = new FileReader();
         reader.onload = () => {
           try {
-            const config = JSON.parse(reader.result);
+            const config = typeof reader.result === 'string' ? JSON.parse(reader.result) : {};
             resolve(this.importConfig(config));
           } catch (err) {
             reject(new Error('Invalid config JSON file'));
@@ -287,7 +330,7 @@ class TinyCrypto {
         reader.readAsText(file);
       });
     } else {
-      const raw = fs.readFileSync(file, 'utf8');
+      const raw = fs__namespace.readFileSync(/** @type {string} */ (file), 'utf8');
       const config = JSON.parse(raw);
       return this.importConfig(config);
     }
@@ -319,10 +362,12 @@ class TinyCrypto {
   async loadKeyFromFile(file) {
     if (isBrowser) {
       return new Promise((resolve, reject) => {
+        if (!(file instanceof File))
+          return reject(new Error('In browser, the file must be a File object'));
         const reader = new FileReader();
         reader.onload = () => {
-          const hexKey = reader.result.trim();
-          const keyBuffer = Buffer.from(hexKey, 'hex');
+          const hexKey = typeof reader.result === 'string' ? reader.result.trim() : '';
+          const keyBuffer = buffer.Buffer.from(hexKey, 'hex');
           this.key = keyBuffer;
           resolve(keyBuffer);
         };
@@ -330,8 +375,8 @@ class TinyCrypto {
         reader.readAsText(file);
       });
     } else {
-      const hexKey = fs.readFileSync(file, 'utf8');
-      const keyBuffer = Buffer.from(hexKey, 'hex');
+      const hexKey = fs__namespace.readFileSync(/** @type {string} */ (file), 'utf8');
+      const keyBuffer = buffer.Buffer.from(hexKey, 'hex');
       this.key = keyBuffer;
       return keyBuffer;
     }
@@ -376,8 +421,8 @@ class TinyCrypto {
    *
    * @param {Object} config - The configuration object to import.
    * @param {string} config.algorithm - The encryption algorithm (e.g., 'aes-256-gcm').
-   * @param {string} config.outputEncoding - The output encoding format (e.g., 'hex').
-   * @param {string} config.inputEncoding - The input encoding format (e.g., 'utf8').
+   * @param {BufferEncoding} config.outputEncoding - The output encoding format (e.g., 'hex').
+   * @param {BufferEncoding} config.inputEncoding - The input encoding format (e.g., 'utf8').
    * @param {number} config.authTagLength - The authentication tag length (e.g., 16).
    * @param {string} config.key - The cryptographic key in hexadecimal string format.
    *
@@ -409,7 +454,7 @@ class TinyCrypto {
     else if (typeof config.authTagLength !== 'undefined')
       throw new Error('Invalid or missing "authTagLength" property. Expected a number.');
 
-    if (typeof config.key === 'string') this.key = Buffer.from(config.key, 'hex');
+    if (typeof config.key === 'string') this.key = buffer.Buffer.from(config.key, 'hex');
     else if (typeof config.key !== 'undefined')
       throw new Error('Invalid or missing "key" property. Expected a hexadecimal string.');
   }
@@ -424,7 +469,7 @@ class TinyCrypto {
    * Each key corresponds to a specific data type (e.g., 'number', 'date', 'buffer', etc.),
    * and the value is a function that serializes the data to a specific format.
    *
-   * @type {Object}
+   * @type {Record<string, (data: any) => string>}
    * @property {Function} weakmap - Throws an error as WeakMap cannot be serialized.
    * @property {Function} weakset - Throws an error as WeakSet cannot be serialized.
    * @property {Function} promise - Throws an error as Promise cannot be serialized.
@@ -465,8 +510,8 @@ class TinyCrypto {
     number: (data) => JSON.stringify({ __type: 'number', value: data }),
     boolean: (data) => JSON.stringify({ __type: 'boolean', value: data }),
     string: (data) => JSON.stringify({ __type: 'string', value: data }),
-    null: (data) => JSON.stringify({ __type: 'null' }),
-    undefined: (data) => JSON.stringify({ __type: 'undefined' }),
+    null: () => JSON.stringify({ __type: 'null' }),
+    undefined: () => JSON.stringify({ __type: 'undefined' }),
     map: (data) =>
       JSON.stringify({
         __type: 'map',
@@ -491,7 +536,7 @@ class TinyCrypto {
    * Each key corresponds to a specific data type (e.g., 'Date', 'BigInt', 'Buffer', etc.),
    * and the value is a function that deserializes the value to its original format.
    *
-   * @type {Object}
+   * @type {Record<string, (data: any) => any>}
    * @property {Function} regexp - Deserializes a regular expression from its string representation (e.g., `/pattern/flags`).
    * @property {Function} htmlelement - Deserializes an HTML element from its serialized outerHTML string (only works in browser environments).
    * @property {Function} date - Deserializes a date from its ISO string representation.
@@ -518,21 +563,21 @@ class TinyCrypto {
         throw new Error('HTMLElement deserialization is only supported in browsers');
       const div = document.createElement('div');
       div.innerHTML = value;
-      return div.firstElementChild;
+      return div;
     },
     date: (value) => new Date(value),
     bigint: (value) => BigInt(value),
     number: (value) => Number(value),
     boolean: (value) => Boolean(value),
-    null: (value) => null,
-    undefined: (value) => undefined,
+    null: () => null,
+    undefined: () => undefined,
     map: (value) => new Map(value),
     set: (value) => new Set(value),
     symbol: (value) => Symbol(value),
     array: (value) => value,
     object: (value) => value,
     string: (value) => String(value),
-    buffer: (value) => Buffer.from(value, 'base64'),
+    buffer: (value) => buffer.Buffer.from(value, 'base64'),
   };
 
   /**
@@ -546,7 +591,8 @@ class TinyCrypto {
    */
   #serialize(data) {
     const type = objFilter.objType(data) || 'undefined';
-    if (this.#valueConvertTypes[type]) return this.#valueConvertTypes[type](data);
+    if (typeof type === 'string' && this.#valueConvertTypes[type])
+      return this.#valueConvertTypes[type](data);
     throw new Error(`Unsupported data type for encryption: ${type}`);
   }
 

package/dist/v1/libs/TinyCrypto.d.mts

@@ -13,8 +13,8 @@ declare class TinyCrypto {
      *
      * @param {Object} [options={}] - Configuration options for encryption and decryption.
      * @param {string} [options.algorithm='aes-256-gcm'] - The encryption algorithm to use. Recommended: 'aes-256-gcm' for authenticated encryption.
-     * @param {string} [options.outputEncoding='hex'] - The encoding used when returning encrypted data (e.g., 'hex', 'base64').
-     * @param {string} [options.inputEncoding='utf8'] - The encoding used for plaintext inputs (e.g., 'utf8').
+     * @param {BufferEncoding} [options.outputEncoding='hex'] - The encoding used when returning encrypted data (e.g., 'hex', 'base64').
+     * @param {BufferEncoding} [options.inputEncoding='utf8'] - The encoding used for plaintext inputs (e.g., 'utf8').
      * @param {number} [options.authTagLength=16] - The length of the authentication tag used in GCM mode. Usually 16 for AES-256-GCM.
      * @param {Buffer} [options.key] - Optional 32-byte cryptographic key. If not provided, a random key is generated.
      *
@@ -24,21 +24,23 @@ declare class TinyCrypto {
      * const crypto = new CryptoManager({
      *   algorithm: 'aes-256-gcm',
      *   outputEncoding: 'base64',
-     *   key: crypto.randomBytes(32),
+     *   key: randomBytes(32),
      * });
      */
     constructor(options?: {
         algorithm?: string | undefined;
-        outputEncoding?: string | undefined;
-        inputEncoding?: string | undefined;
+        outputEncoding?: BufferEncoding | undefined;
+        inputEncoding?: BufferEncoding | undefined;
         authTagLength?: number | undefined;
         key?: Buffer<ArrayBufferLike> | undefined;
     });
     algorithm: string;
-    outputEncoding: string;
-    inputEncoding: string;
     authTagLength: number;
     key: Buffer<ArrayBufferLike>;
+    /** @type {BufferEncoding} */
+    outputEncoding: BufferEncoding;
+    /** @type {BufferEncoding} */
+    inputEncoding: BufferEncoding;
     /**
      * Generates a secure random cryptographic key.
      *
@@ -68,10 +70,7 @@ declare class TinyCrypto {
      *
      * @param {*} data - The data to encrypt. Can be of any supported type (string, number, boolean, Date, JSON, etc.).
      * @param {Buffer} [iv=this.generateIV()] - Optional Initialization Vector (IV). If not provided, a secure random IV is generated.
-     * @returns {Object} An object containing:
-     * - `iv` {string} - The IV used, encoded with the output encoding.
-     * - `encrypted` {string} - The encrypted payload.
-     * - `authTag` {string} - The authentication tag used to verify the integrity of the ciphertext.
+     * @returns {EncryptedDataParams} An object containing the encrypted data.
      *
      * @example
      * const result = cryptoManager.encrypt('Hello, world!');
@@ -81,17 +80,33 @@ declare class TinyCrypto {
      * //   authTag: 'aa93...'
      * // }
      */
-    encrypt(data: any, iv?: Buffer): Object;
+    encrypt(data: any, iv?: Buffer): {
+        /**
+         * - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
+         */
+        iv: string;
+        /**
+         * - The encrypted data to decrypt, encoded with the output encoding.
+         */
+        encrypted: string;
+        /**
+         * - The authentication tag used to verify the integrity of the encrypted data.
+         */
+        authTag: string;
+    };
+    /**
+     * @typedef {Object} EncryptedDataParams
+     * @property {string} iv - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
+     * @property {string} encrypted - The encrypted data to decrypt, encoded with the output encoding.
+     * @property {string} authTag - The authentication tag used to verify the integrity of the encrypted data.
+     */
     /**
      * Decrypts a previously encrypted value.
      *
      * The method checks the integrity of the data using the authentication tag (`authTag`) and ensures the data is properly decrypted.
      * After decryption, it automatically deserializes the data back to its original type.
      *
-     * @param {Object} params - An object containing the encrypted data:
-     *   - `iv` {string} - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
-     *   - `encrypted` {string} - The encrypted data to decrypt, encoded with the output encoding.
-     *   - `authTag` {string} - The authentication tag used to verify the integrity of the encrypted data.
+     * @param {EncryptedDataParams} params - An object containing the encrypted data.
      * @param {string|null} [expectedType=null] - Optionally specify the expected type of the decrypted data. If provided, the method will validate the type of the deserialized value.
      * @returns {*} The decrypted value, which will be the original type of the data before encryption.
      * @throws {Error} Throws if the authentication tag doesn't match or the data has been tampered with.
@@ -106,17 +121,27 @@ declare class TinyCrypto {
      * const decrypted = cryptoManager.decrypt(encryptedData, 'string');
      * console.log(decrypted); // Outputs: 'Hello, world!'
      */
-    decrypt({ iv, encrypted, authTag }: Object, expectedType?: string | null): any;
+    decrypt({ iv, encrypted, authTag }: {
+        /**
+         * - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
+         */
+        iv: string;
+        /**
+         * - The encrypted data to decrypt, encoded with the output encoding.
+         */
+        encrypted: string;
+        /**
+         * - The authentication tag used to verify the integrity of the encrypted data.
+         */
+        authTag: string;
+    }, expectedType?: string | null): any;
     /**
      * Retrieves the type of the original data from an encrypted object.
      *
      * This method decrypts the encrypted data and extracts its type information without fully deserializing the value.
      * It is useful when you need to verify the type of the encrypted data before fully decrypting it.
      *
-     * @param {Object} params - An object containing the encrypted data:
-     *   - `iv` {string} - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
-     *   - `encrypted` {string} - The encrypted data to decrypt, encoded with the output encoding.
-     *   - `authTag` {string} - The authentication tag used to verify the integrity of the encrypted data.
+     * @param {EncryptedDataParams} params - An object containing the encrypted data.
      * @returns {string} The type of the original data (e.g., 'string', 'number', 'date', etc.).
      *
      * @example
@@ -128,7 +153,20 @@ declare class TinyCrypto {
      * const dataType = cryptoManager.getTypeFromEncrypted(encryptedData);
      * console.log(dataType); // Outputs: 'string'
      */
-    getTypeFromEncrypted({ iv, encrypted, authTag }: Object): string;
+    getTypeFromEncrypted({ iv, encrypted, authTag }: {
+        /**
+         * - The Initialization Vector (IV) used in encryption, encoded with the output encoding.
+         */
+        iv: string;
+        /**
+         * - The encrypted data to decrypt, encoded with the output encoding.
+         */
+        encrypted: string;
+        /**
+         * - The authentication tag used to verify the integrity of the encrypted data.
+         */
+        authTag: string;
+    }): string;
     /**
      * Saves the cryptographic key to a file.
      *
@@ -240,8 +278,8 @@ declare class TinyCrypto {
      *
      * @param {Object} config - The configuration object to import.
      * @param {string} config.algorithm - The encryption algorithm (e.g., 'aes-256-gcm').
-     * @param {string} config.outputEncoding - The output encoding format (e.g., 'hex').
-     * @param {string} config.inputEncoding - The input encoding format (e.g., 'utf8').
+     * @param {BufferEncoding} config.outputEncoding - The output encoding format (e.g., 'hex').
+     * @param {BufferEncoding} config.inputEncoding - The input encoding format (e.g., 'utf8').
      * @param {number} config.authTagLength - The authentication tag length (e.g., 16).
      * @param {string} config.key - The cryptographic key in hexadecimal string format.
      *
@@ -258,10 +296,11 @@ declare class TinyCrypto {
      */
     importConfig(config: {
         algorithm: string;
-        outputEncoding: string;
-        inputEncoding: string;
+        outputEncoding: BufferEncoding;
+        inputEncoding: BufferEncoding;
         authTagLength: number;
         key: string;
     }): void;
     #private;
 }
+import { Buffer } from 'buffer';