tiny-essentials 1.1.1 → 1.2.1

package/dist/v1/libs/TinyCrypto.mjs

@@ -1,7 +1,16 @@
-import crypto from 'crypto';
-import fs from 'fs';
+import { randomBytes, createDecipheriv, createCipheriv } from 'crypto';
+import * as fs from 'fs';
+import { Buffer } from 'buffer';
 import { objType } from '../../v1/basics/objFilter.mjs';
-// Detecta se estamos no browser
+/**
+ * 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';
 /**
  * TinyCrypto is a utility class that provides methods for secure key generation,
@@ -17,8 +26,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.
      *
@@ -28,15 +37,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';
     }
     /**
      * Generates a secure random cryptographic key.
@@ -49,7 +60,7 @@ class TinyCrypto {
      * const customKey = cryptoManager.generateKey(16); // Generates a 16-byte key (e.g. for AES-128)
      */
     generateKey(value = 32) {
-        return crypto.randomBytes(value); // 256-bit
+        return randomBytes(value); // 256-bit
     }
     /**
      * Generates a secure random Initialization Vector (IV).
@@ -62,7 +73,7 @@ class TinyCrypto {
      * const customIV = cryptoManager.generateIV(16); // Generates a 16-byte IV if needed for other algorithms
      */
     generateIV(value = 12) {
-        return crypto.randomBytes(value); // 96-bit padrão para GCM
+        return randomBytes(value); // 96-bit padrão para GCM
     }
     /**
      * Encrypts a given value (string, number, object, etc.)
@@ -71,10 +82,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!');
@@ -86,28 +94,37 @@ class TinyCrypto {
      */
     encrypt(data, iv = this.generateIV()) {
         const plainText = this.#serialize(data);
-        const cipher = crypto.createCipheriv(this.algorithm, this.key, iv, {
+        const cipher = createCipheriv(this.algorithm, this.key, iv, {
+            // @ts-ignore
             authTagLength: this.authTagLength,
         });
+        // @ts-ignore
         let encrypted = cipher.update(plainText, this.inputEncoding);
+        // @ts-ignore
         encrypted = 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.
@@ -126,11 +143,15 @@ class TinyCrypto {
         const ivBuffer = Buffer.from(iv, this.outputEncoding);
         const encryptedBuffer = Buffer.from(encrypted, this.outputEncoding);
         const authTagBuffer = Buffer.from(authTag, this.outputEncoding);
-        const decipher = crypto.createDecipheriv(this.algorithm, this.key, ivBuffer, {
+        const decipher = 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);
         if (expectedType)
@@ -143,10 +164,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
@@ -162,11 +180,14 @@ class TinyCrypto {
         const ivBuffer = Buffer.from(iv, this.outputEncoding);
         const encryptedBuffer = Buffer.from(encrypted, this.outputEncoding);
         const authTagBuffer = Buffer.from(authTag, this.outputEncoding);
-        const decipher = crypto.createDecipheriv(this.algorithm, this.key, ivBuffer, {
+        const decipher = 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);
         return typeof type === 'string' ? type : 'unknown';
@@ -256,10 +277,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) {
@@ -271,7 +294,7 @@ class TinyCrypto {
             });
         }
         else {
-            const raw = fs.readFileSync(file, 'utf8');
+            const raw = fs.readFileSync(/** @type {string} */ (file), 'utf8');
             const config = JSON.parse(raw);
             return this.importConfig(config);
         }
@@ -302,9 +325,11 @@ 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 hexKey = typeof reader.result === 'string' ? reader.result.trim() : '';
                     const keyBuffer = Buffer.from(hexKey, 'hex');
                     this.key = keyBuffer;
                     resolve(keyBuffer);
@@ -314,7 +339,7 @@ class TinyCrypto {
             });
         }
         else {
-            const hexKey = fs.readFileSync(file, 'utf8');
+            const hexKey = fs.readFileSync(/** @type {string} */ (file), 'utf8');
             const keyBuffer = Buffer.from(hexKey, 'hex');
             this.key = keyBuffer;
             return keyBuffer;
@@ -358,8 +383,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.
      *
@@ -406,7 +431,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.
@@ -447,8 +472,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',
             value: Array.from(data.entries()),
@@ -470,7 +495,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.
@@ -497,14 +522,14 @@ 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),
@@ -524,7 +549,7 @@ class TinyCrypto {
      */
     #serialize(data) {
         const type = objType(data) || 'undefined';
-        if (this.#valueConvertTypes[type])
+        if (typeof type === 'string' && this.#valueConvertTypes[type])
             return this.#valueConvertTypes[type](data);
         throw new Error(`Unsupported data type for encryption: ${type}`);
     }

package/docs/README.md

@@ -14,6 +14,8 @@ This folder contains external libraries and utility modules that are designed to
 
 - 🔐 **[TinyCrypto.md](./libs/TinyCrypto.md)** — A flexible and browser-compatible AES-256-GCM encryption utility with support for complex JavaScript types like `Date`, `RegExp`, `Buffer`, and even DOM elements (in the browser).
 
+- 📄 **[TinyCertCrypto.md](./libs/TinyCertCrypto.md)** — A lightweight tool for managing RSA key pairs and X.509 certificates with support for generation, PEM parsing, encryption/decryption of JSON, and certificate metadata extraction. Works in both Node.js and browser environments (with limitations in browser).
+
 ---
 
 ### 2. **`basics/`** 

package/docs/libs/TinyCertCrypto.md

@@ -0,0 +1,202 @@
+# ✨ Tiny Cert Crypto
+
+A lightweight 🔐 utility for managing, generating, and handling **X.509 certificates** and **RSA key pairs**.  
+Built with flexibility in mind — runs seamlessly in both **Node.js** and **browser** environments! 🌍
+
+---
+
+## 📦 Features
+
+- 🛠️ RSA key pair generation (**Node.js only**)
+- 🧾 Self-signed X.509 certificate creation
+- 🧬 Support for PEM-based 🔑 public/private keys and certificates
+- 🧊 JSON encryption & decryption using Base64 encoding
+- 🕵️ Metadata extraction from certificates (issuer, subject, validity, etc.)
+- 📁 Flexible key loading: from memory, local files (Node.js), or URLs (browser)
+
+---
+
+## 🚀 Getting Started
+
+### 📚 Constructor
+
+```js
+const instance = new TinyCertCrypto({
+  publicCertPath: 'cert.pem',          // Path to public cert (Node.js)
+  privateKeyPath: 'key.pem',           // Path to private key (Node.js)
+  publicCertBuffer: null,              // String or Buffer in memory (Node.js/browser)
+  privateKeyBuffer: null,              // String or Buffer in memory (Node.js/browser)
+  cryptoType: 'RSA-OAEP',              // Encryption algorithm (default: 'RSA-OAEP')
+});
+```
+
+> 🔍 In **browser environments**, at least `publicCertPath` or `publicCertBuffer` must be provided.
+
+---
+
+## 🧪 Core Methods
+
+### 🔧 `async init()`
+Initializes the certificate and key system from files, memory buffers, or URLs.
+
+- Loads the public certificate/key.
+- Optionally loads the private key.
+- Detects whether you’re running in Node.js or the browser and adjusts behavior accordingly.
+
+---
+
+### 📑 `extractCertMetadata()`
+Returns parsed metadata from the loaded certificate.
+
+```js
+{
+  subject: { names: {}, shortNames: {}, raw: "CN=example.com,O=MyOrg" },
+  issuer: { names: {}, shortNames: {}, raw: "CN=example.com,O=MyOrg" },
+  serialNumber: '...',
+  validFrom: Date,
+  validTo: Date
+}
+```
+
+---
+
+### 🛡️ `encryptJson(jsonObject)`
+Encrypts a JavaScript object using the loaded **public key**, returning a **Base64-encoded string**.
+
+```js
+const encrypted = instance.encryptJson({ hello: "world" });
+```
+
+---
+
+### 🔓 `decryptToJson(base64String)`
+Decrypts a Base64 string using the **private key**, returning the original JSON object.
+
+```js
+const json = instance.decryptToJson(encrypted);
+```
+
+---
+
+### 🔍 `hasKeys()`
+Returns `true` if both `publicKey` and `privateKey` are loaded.
+
+---
+
+### 📜 `hasCert()`
+Returns `true` if a certificate (`publicCert`) is loaded.
+
+---
+
+### ♻️ `reset()`
+Resets the internal state, clearing:
+- `publicKey`
+- `privateKey`
+- `publicCert`
+- `metadata`
+- `source`
+
+---
+
+### 📦 `fetchNodeForge()` & `getNodeForge()`
+Handles lazy-loading and reuse of the `node-forge` module.
+
+Use if you want to access Forge directly without importing it yourself:
+
+```js
+const forge = await instance.fetchNodeForge();
+```
+
+---
+
+## 🧠 Internals & Design
+
+- 🔍 Uses regular expressions to detect PEM types (`CERTIFICATE`, `PUBLIC KEY`, `PRIVATE KEY`)
+- 🧪 Automatically parses PEM buffers and files depending on the runtime
+- 🔐 Encrypts data with the selected algorithm (`RSA-OAEP`, etc.)
+- 🧬 X.509 certificate metadata extraction is done via `node-forge`
+
+---
+
+## 🧰 Requirements
+
+| Environment | Requirement        |
+|-------------|--------------------|
+| Node.js     | `node-forge` |
+| Browser     | Works with native `fetch()` and `TextDecoder` |
+
+---
+
+## 😺 Example Use Case
+
+```js
+const crypto = new TinyCertCrypto({ publicCertPath: 'cert.pem', privateKeyPath: 'key.pem' });
+await crypto.init();
+
+const data = { secret: 'I love ponies' };
+const encrypted = crypto.encryptJson(data);
+const decrypted = crypto.decryptToJson(encrypted);
+
+console.log(decrypted); // { secret: 'I love ponies' }
+```
+
+---
+
+### 🧾 `async generateX509Cert(subjectFields, options = {})`
+Generates a new **RSA key pair** and a **self-signed X.509 certificate** using the provided subject information.
+
+🔐 This is ideal for internal services, development environments, or cryptographic testing tools where a trusted CA is not required.
+
+---
+
+**🧬 Parameters:**
+
+- `subjectFields` (`Object`) – Describes the identity fields that will be embedded into the certificate's subject and issuer:
+  - Common fields include:
+    - `CN`: Common Name (e.g. domain or hostname)
+    - `O`: Organization Name
+    - `OU`: Organizational Unit
+    - `L`: Locality (City)
+    - `ST`: State or Province
+    - `C`: Country (2-letter code)
+    - `emailAddress`: Optional email field
+
+- `options` (`Object`) – Optional configuration:
+  - `keySize` (`number`) – RSA key size in bits (default: `2048`)
+  - `validityInYears` (`number`) – Certificate validity period (default: `1`)
+  - `randomBytesLength` (`number`) – Length of the serial number (default: `16`)
+  - `digestAlgorithm` (`string`) – Digest algorithm used to sign the certificate (default: `'sha256'`)
+  - `forgeInstance` (`object`) – Optionally inject a specific instance of `node-forge`
+  - `cryptoType` (`string`) – Encryption scheme used for later operations (e.g., `'RSA-OAEP'`, `'RSAES-PKCS1-V1_5'`)
+
+---
+
+**✅ Returns:**
+
+An object containing all the generated artifacts:
+
+```js
+{
+  publicKey: '-----BEGIN PUBLIC KEY-----...',
+  privateKey: '-----BEGIN PRIVATE KEY-----...',
+  cert: '-----BEGIN CERTIFICATE-----...'
+}
+```
+
+- `publicKey`: The newly generated **PEM-encoded RSA public key**
+- `privateKey`: The corresponding **PEM-encoded RSA private key**
+- `cert`: A **PEM-encoded X.509 certificate** that is **self-signed** with the private key and matches the provided subject
+
+---
+
+**📌 Notes:**
+
+- 🔄 The `subject` and `issuer` of the certificate are the same (self-signed).
+- ⏳ The certificate `validFrom` is set to the current date, and `validTo` is based on the `validityInYears` option.
+- 🔢 A secure random `serialNumber` is generated using `crypto.randomBytes`.
+
+---
+
+**⚠️ Availability:**
+
+> This method is only available in **Node.js environments** due to its dependency on the native `crypto` module and synchronous file access via `fs`.

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "tiny-essentials",
-  "version": "1.1.1",
+  "version": "1.2.1",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",
     "test:js": "npx babel-node test/index.js",
     "test:mjs": "node test/index.mjs",
     "test:cjs": "node test/index.cjs",
-    "fix:prettier": "prettier --write ./src/* && prettier --write ./test/*",
+    "fix:prettier": "npm run fix:prettier:src && npm run fix:prettier:test && npm run fix:prettier:rollup.config && npm run fix:prettier:webpack.config",
+    "fix:prettier:src": "prettier --write ./src/*",
+    "fix:prettier:test": "prettier --write ./test/*",
+    "fix:prettier:rollup.config": "prettier --write ./rollup.config.mjs",
+    "fix:prettier:webpack.config": "prettier --write ./webpack.config.mjs",
     "auto-build": "npm run build",
-    "build": "tsc -p tsconfig.json && rollup -c",
+    "build": "tsc -p tsconfig.json && rollup -c && webpack --mode production",
     "build-clean": "npm run clean && npm run build",
     "build-dist": "npm run build",
     "build-browserify": "npx browserify build/browserify.js -p esmify > dist/TinyAiApi.web.js",
@@ -58,7 +62,6 @@
     "@rollup/plugin-commonjs": "^28.0.3",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^16.0.1",
-    "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.1.2",
     "babel-preset-es2015": "^6.24.1",
     "byte-length": "^1.0.2",
@@ -72,15 +75,17 @@
     "moment-timezone": "^0.5.48",
     "mysql": "^2.18.1",
     "node-fetch": "2.7.0",
+    "node-forge": "^1.3.1",
+    "node-polyfill-webpack-plugin": "^4.1.0",
     "object-hash": "^3.0.0",
     "prettier": "3.5.3",
     "rollup": "^4.40.0",
-    "rollup-plugin-polyfill-node": "^0.13.0",
     "rollup-preserve-directives": "^1.1.3",
     "tinycolor2": "^1.6.0",
     "tslib": "^2.8.1",
     "type-fest": "^4.40.0",
     "typescript": "^5.8.3",
-    "util": "^0.12.5"
+    "webpack": "^5.99.6",
+    "webpack-cli": "^6.0.1"
   }
 }