tiny-essentials 1.2.1 → 1.3.0

package/docs/libs/TinyCertCrypto.md

@@ -1,202 +0,0 @@
-# ✨ 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/docs/libs/TinyCrypto.md

@@ -1,177 +0,0 @@
-# 🔐 Tiny Crypto
-
-**Tiny Crypto** is a flexible and browser-compatible encryption utility class built for AES-256-GCM encryption with full support for serialization and deserialization of complex JavaScript data types.
-
-Whether you're in Node.js or a browser, Tiny Crypto helps you easily encrypt/decrypt values, save/load configurations, and keep your secrets safe — all while supporting real-world usage like RegExp, Date, Buffer, and even DOM elements (in browsers only)!
-
----
-
-## ✨ Features
-
-- 🔒 AES-256-GCM symmetric encryption
-- 🧠 Automatic serialization of complex types (Date, RegExp, Set, Map, etc.)
-- 📤 Save and load keys/configs from files
-- 🌐 Works in both **Node.js** and **Browsers**
-- ⚠️ Type validation on decryption
-- 💾 Smart support for file APIs (e.g. `FileReader` in browser, `fs` in Node)
-
----
-
-## 🚀 Getting Started
-
-```js
-const crypto = new TinyCrypto();
-
-// Encrypt some data
-const { encrypted, iv, authTag } = crypto.encrypt({ hello: 'world' });
-
-// Decrypt it back
-const decrypted = crypto.decrypt({ encrypted, iv, authTag });
-
-console.log(decrypted); // { hello: 'world' }
-```
-
----
-
-## 🧠 Supported Data Types
-
-When you encrypt a value, its type is recorded and restored when decrypted.
-
-Supports:
-
-- `String`, `Number`, `Boolean`, `BigInt`, `Null`, `Undefined`
-- `Array`, `Object`, `Map`, `Set`, `Buffer`
-- `RegExp`, `Date`, `Symbol`
-- `HTMLElement` _(browser only)_
-
-Does NOT support:
-
-- `Function`, `Promise`, `WeakMap`, `WeakSet` → ❌ Will throw!
-
----
-
-## 🔧 API
-
-### `constructor(options)`
-
-| Option           | Type   | Default         | Description                       |
-| ---------------- | ------ | --------------- | --------------------------------- |
-| `algorithm`      | string | `'aes-256-gcm'` | AES algorithm used for encryption |
-| `key`            | Buffer | auto-generated  | The secret key to use (32 bytes)  |
-| `outputEncoding` | string | `'hex'`         | Encoding used for outputs         |
-| `inputEncoding`  | string | `'utf8'`        | Encoding used for plain data      |
-| `authTagLength`  | number | `16`            | GCM auth tag length               |
-
----
-
-### `encrypt(data, iv?)`
-
-Encrypts a value and returns an object with `{ iv, encrypted, authTag }`.
-
-```js
-const result = crypto.encrypt('Hello!');
-```
-
----
-
-### `decrypt({ iv, encrypted, authTag }, expectedType?)`
-
-Decrypts a previously encrypted value and returns the original data. You can optionally pass an `expectedType` to validate it.
-
-```js
-const plain = crypto.decrypt(result, 'string');
-```
-
----
-
-### `getTypeFromEncrypted({ iv, encrypted, authTag })`
-
-Returns the type name of the encrypted data without fully decrypting it.
-
----
-
-### `generateKey(length = 32)`
-
-Generates a secure random key. Default: 32 bytes (AES-256).
-
----
-
-### `generateIV(length = 12)`
-
-Generates a secure random IV. Default: 12 bytes (GCM standard).
-
----
-
-### `saveKeyToFile(filename = 'secret.key')`
-
-Saves the current key to a file (browser: prompts download).
-
----
-
-### `loadKeyFromFile(file)`
-
-Loads a key from a file (browser: File object, Node: file path).
-
----
-
-### `saveConfigToFile(filename = 'crypto-config.json')`
-
-Saves the current configuration as JSON.
-
----
-
-### `loadConfigFromFile(file)`
-
-Loads configuration from a JSON file.
-
----
-
-### `exportConfig()`
-
-Returns an object with the current settings:
-
-```json
-{
-  "algorithm": "aes-256-gcm",
-  "outputEncoding": "hex",
-  "inputEncoding": "utf8",
-  "authTagLength": 16,
-  "key": "..."
-}
-```
-
----
-
-### `importConfig(config)`
-
-Applies a configuration object. Throws if invalid types are provided.
-
----
-
-## 🧪 Type Validation
-
-You can ensure the decrypted value matches the original type:
-
-```js
-crypto.decrypt(result, 'map'); // ✅
-crypto.decrypt(result, 'set'); // ❌ throws if type mismatch
-```
-
----
-
-## ❗ Errors You Might See
-
-- `Unsupported data type for encryption: Function`
-- `Type mismatch: expected Map, but got Set`
-- `Invalid config JSON file`
-- `HTMLElement deserialization is only supported in browsers`
-
----
-
-## 🛡️ Security Notice
-
-This utility is for learning and light usage. For production, ensure:
-
-- Proper key management (use secure vaults)
-- Safe IV reuse (IVs must be unique per encryption)
-- Your platform's crypto standards are followed