tiny-essentials 1.0.0 → 1.1.1

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

@@ -0,0 +1,267 @@
+export default TinyCrypto;
+/**
+ * TinyCrypto is a utility class that provides methods for secure key generation,
+ * encryption, and decryption of data. It also allows for serialization
+ * and deserialization of complex data types, and offers methods to save and load encryption
+ * configurations and keys from files.
+ *
+ * @class
+ */
+declare class TinyCrypto {
+    /**
+     * Creates a new instance of the CryptoManager class with configurable options.
+     *
+     * @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 {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.
+     *
+     * @throws {Error} Throws if the provided key is not 32 bytes long.
+     *
+     * @example
+     * const crypto = new CryptoManager({
+     *   algorithm: 'aes-256-gcm',
+     *   outputEncoding: 'base64',
+     *   key: crypto.randomBytes(32),
+     * });
+     */
+    constructor(options?: {
+        algorithm?: string | undefined;
+        outputEncoding?: string | undefined;
+        inputEncoding?: string | undefined;
+        authTagLength?: number | undefined;
+        key?: Buffer<ArrayBufferLike> | undefined;
+    });
+    algorithm: string;
+    outputEncoding: string;
+    inputEncoding: string;
+    authTagLength: number;
+    key: Buffer<ArrayBufferLike>;
+    /**
+     * Generates a secure random cryptographic key.
+     *
+     * @param {number} [value=32] - The number of bytes to generate. Default is 32 bytes (256 bits), suitable for AES-256.
+     * @returns {Buffer} A securely generated random key as a Buffer.
+     *
+     * @example
+     * const key = cryptoManager.generateKey(); // Generates a 32-byte key
+     * const customKey = cryptoManager.generateKey(16); // Generates a 16-byte key (e.g. for AES-128)
+     */
+    generateKey(value?: number): Buffer;
+    /**
+     * Generates a secure random Initialization Vector (IV).
+     *
+     * @param {number} [value=12] - The number of bytes to generate. Default is 12 bytes (96 bits), the recommended size for AES-GCM.
+     * @returns {Buffer} A securely generated IV as a Buffer.
+     *
+     * @example
+     * const iv = cryptoManager.generateIV(); // Generates a 12-byte IV
+     * const customIV = cryptoManager.generateIV(16); // Generates a 16-byte IV if needed for other algorithms
+     */
+    generateIV(value?: number): Buffer;
+    /**
+     * Encrypts a given value (string, number, object, etc.)
+     *
+     * The value is first serialized de forma segura (preservando o tipo) antes da criptografia.
+     *
+     * @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.
+     *
+     * @example
+     * const result = cryptoManager.encrypt('Hello, world!');
+     * // {
+     * //   iv: 'b32a...',
+     * //   encrypted: 'c1d5...',
+     * //   authTag: 'aa93...'
+     * // }
+     */
+    encrypt(data: any, iv?: Buffer): Object;
+    /**
+     * 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 {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.
+     * @throws {Error} Throws if the deserialized value doesn't match the `expectedType`.
+     *
+     * @example
+     * const encryptedData = {
+     *   iv: 'b32a...',
+     *   encrypted: 'c1d5...',
+     *   authTag: 'aa93...'
+     * };
+     * const decrypted = cryptoManager.decrypt(encryptedData, 'string');
+     * console.log(decrypted); // Outputs: 'Hello, world!'
+     */
+    decrypt({ iv, encrypted, authTag }: Object, 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.
+     * @returns {string} The type of the original data (e.g., 'string', 'number', 'date', etc.).
+     *
+     * @example
+     * const encryptedData = {
+     *   iv: 'b32a...',
+     *   encrypted: 'c1d5...',
+     *   authTag: 'aa93...'
+     * };
+     * const dataType = cryptoManager.getTypeFromEncrypted(encryptedData);
+     * console.log(dataType); // Outputs: 'string'
+     */
+    getTypeFromEncrypted({ iv, encrypted, authTag }: Object): string;
+    /**
+     * Saves the cryptographic key to a file.
+     *
+     * If running in a browser, the method generates a download link for the key as a text file.
+     * If running in Node.js, the method saves the key to the specified file path.
+     *
+     * @param {string} [filename='secret.key'] - The name of the file to save the key. Defaults to 'secret.key'.
+     * @throws {Error} Throws an error if the file cannot be written in Node.js.
+     *
+     * @example
+     * // In a browser, triggers a download of the key
+     * cryptoManager.saveKeyToFile('myKey.key');
+     *
+     * // In Node.js, saves the key to 'myKey.key'
+     * cryptoManager.saveKeyToFile('myKey.key');
+     */
+    saveKeyToFile(filename?: string): void;
+    /**
+     * Saves the current cryptographic configuration to a JSON file.
+     *
+     * If running in a browser, the method generates a download link for the configuration as a JSON file.
+     * If running in Node.js, the method saves the configuration to the specified file path.
+     *
+     * @param {string} [filename='crypto-config.json'] - The name of the file to save the configuration. Defaults to 'crypto-config.json'.
+     * @throws {Error} Throws an error if the file cannot be written in Node.js.
+     *
+     * @example
+     * // In a browser, triggers a download of the configuration
+     * cryptoManager.saveConfigToFile('myConfig.json');
+     *
+     * // In Node.js, saves the configuration to 'myConfig.json'
+     * cryptoManager.saveConfigToFile('myConfig.json');
+     */
+    saveConfigToFile(filename?: string): void;
+    /**
+     * Loads and imports cryptographic configuration from a JSON file.
+     *
+     * If running in a browser, the method allows the user to select a file, reads the file as text,
+     * parses the JSON, and imports the configuration.
+     * If running in Node.js, the method reads the file synchronously and imports the configuration.
+     *
+     * @param {File|string} file - The file to load the configuration from. In the browser, this is a `File` object, and in Node.js, it's a file path.
+     * @returns {Promise<void>} A promise that resolves when the configuration is successfully loaded and imported.
+     * @throws {Error} Throws an error if the JSON file is invalid or the file cannot be read.
+     *
+     * @example
+     * // In a browser, prompt user to select a file and load the configuration
+     * cryptoManager.loadConfigFromFile(file)
+     *   .then(() => console.log('Config loaded successfully'))
+     *   .catch(err => console.error('Error loading config:', err));
+     *
+     * // In Node.js, load the configuration from a file path
+     * cryptoManager.loadConfigFromFile('myConfig.json')
+     *   .then(() => console.log('Config loaded successfully'))
+     *   .catch(err => console.error('Error loading config:', err));
+     */
+    loadConfigFromFile(file: File | string): Promise<void>;
+    /**
+     * Loads a cryptographic key from a file and sets it for encryption/decryption.
+     *
+     * If running in a browser, the method allows the user to select a file, reads the file as text,
+     * and loads the key (in hexadecimal format) into the current instance.
+     * If running in Node.js, the method reads the file synchronously, parses the hexadecimal key,
+     * and loads it into the current instance.
+     *
+     * @param {File|string} file - The file to load the key from. In the browser, this is a `File` object, and in Node.js, it's a file path.
+     * @returns {Promise<Buffer>} A promise that resolves with the key as a `Buffer` when the file is successfully loaded.
+     * @throws {Error} Throws an error if the file cannot be read or if the key is invalid.
+     *
+     * @example
+     * // In a browser, prompt user to select a file and load the key
+     * cryptoManager.loadKeyFromFile(file)
+     *   .then(key => console.log('Key loaded successfully:', key))
+     *   .catch(err => console.error('Error loading key:', err));
+     *
+     * // In Node.js, load the key from a file path
+     * cryptoManager.loadKeyFromFile('myKey.key')
+     *   .then(key => console.log('Key loaded successfully:', key))
+     *   .catch(err => console.error('Error loading key:', err));
+     */
+    loadKeyFromFile(file: File | string): Promise<Buffer>;
+    /**
+     * Exports the current cryptographic configuration as a JSON object.
+     *
+     * The exported configuration includes the encryption algorithm, output encoding format,
+     * input encoding format, the cryptographic key (in hexadecimal format), and the authentication tag length.
+     * This method does not include any sensitive data like the raw key, only its hexadecimal representation.
+     *
+     * @returns {Object} The exported configuration as a plain JavaScript object.
+     * @example
+     * const config = cryptoManager.exportConfig();
+     * console.log(config);
+     * // Example output:
+     * // {
+     * //   algorithm: 'aes-256-gcm',
+     * //   outputEncoding: 'hex',
+     * //   inputEncoding: 'utf8',
+     * //   key: 'abcdef1234567890...',
+     * //   authTagLength: 16
+     * // }
+     */
+    exportConfig(): Object;
+    /**
+     * Imports a cryptographic configuration from a JSON object.
+     *
+     * This method sets the configuration for the encryption process, including the algorithm, encoding formats,
+     * authentication tag length, and the cryptographic key (in hexadecimal string format).
+     * If any of the expected properties are missing or invalid, an error will be thrown.
+     *
+     * @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 {number} config.authTagLength - The authentication tag length (e.g., 16).
+     * @param {string} config.key - The cryptographic key in hexadecimal string format.
+     *
+     * @throws {Error} If any required property is missing or has an invalid type.
+     * @example
+     * const config = {
+     *   algorithm: 'aes-256-gcm',
+     *   outputEncoding: 'hex',
+     *   inputEncoding: 'utf8',
+     *   authTagLength: 16,
+     *   key: 'abcdef1234567890abcdef1234567890',
+     * };
+     * cryptoManager.importConfig(config);
+     */
+    importConfig(config: {
+        algorithm: string;
+        outputEncoding: string;
+        inputEncoding: string;
+        authTagLength: number;
+        key: string;
+    }): void;
+    #private;
+}