cipher-kit 2.0.0-beta.5 → 2.1.0

package/README.md

@@ -3,16 +3,15 @@
 
 <h1 align="center" style="font-weight:900;">cipher-kit</h1>
 
-<!-- TODO -->
 <p align="center">
-  Secure, Lightweight, and Cross-Platform <br/>
-  Encryption, Decryption, and Hashing <br/> 
-  for Web, Node.js, Deno, Bun, and Cloudflare Workers
+  Secure, Modern, and Cross-Platform <br/>
+  Cryptography Helpers for Web, Node.js, <br/> 
+  Deno, Bun, and Cloudflare Workers
 </p>
 
 <a href="https://opensource.org/licenses/MIT" rel="nofollow"><img src="https://img.shields.io/github/license/WolfieLeader/npm?color=DC343B" alt="License"></a>
 <a href="https://www.npmjs.com/package/cipher-kit" rel="nofollow"><img src="https://img.shields.io/npm/v/cipher-kit?color=0078D4" alt="npm version"></a>
-<a href="https://www.npmjs.com/package/cipher-kit" rel="nofollow"><img src="https://img.shields.io/npm/dy/cipher-kit.svg?color=03C03C" alt="npm downloads"></a>
+<a href="https://www.npmjs.com/package/cipher-kit" rel="nofollow"><img src="https://img.shields.io/npm/dt/cipher-kit.svg?color=03C03C" alt="npm downloads"></a>
 <a href="https://github.com/WolfieLeader/npm" rel="nofollow"><img src="https://img.shields.io/github/stars/WolfieLeader/npm" alt="stars"></a>
 
 </div>
@@ -22,10 +21,10 @@
 - 🛡️ **Secure and Flexible** - Uses best practices and modern cryptographic techniques, while providing a flexible and simple API.
 - 📦 **All-in-One Toolkit** – Combines encryption, hashing, encoding, serialization, and more into a single package.
 - 🌐 **Cross-Platform** – Works seamlessly across Web, Node.js, Deno, Bun, and Cloudflare Workers.
-- 💡 **Typed and Ergonomic** - Type safe and provides throwing and non-throwing (`Result`) APIs.
-- 🌳 **Tree-Shakable** - import root or platform-specific modules to reduce bundle size.
+- 💡 **Typed and Ergonomic** - Type-safe API with both throwing and non-throwing (`Result`) flavors.
+- 🌳 **Tree-Shakable** - Import from the root or from platform-specific entry points to keep bundles lean.
 - 🚫 **Zero Dependencies** – Fully self-contained, no external libraries required.
-- 🍼 **Explain like I'm five** - Newbie-friendly explanations and documentation.
+- 🍼 **Explain Like I'm Five** - Newbie-friendly explanations and documentation.
 
 ## Installation 🔥
 
@@ -39,65 +38,111 @@ pnpm install cipher-kit@latest
 bun add cipher-kit@latest
 ```
 
-## Usage 🪛
-
-### The `try` Prefix (Non-Throwing `Result` API)
+## Quick Start 🚀
 
-The `try` prefix functions return a `Result<T>` object that indicates success or failure without throwing exceptions.
+```typescript
+// Node.js
+import { createSecretKey, encrypt, decrypt } from "cipher-kit/node";
 
-This is useful in scenarios where you want to handle errors gracefully without using `try/catch` blocks.
+const secretKey = createSecretKey("my-passphrase");
+const encrypted = encrypt("Hello World!", secretKey);
+const decrypted = decrypt(encrypted, secretKey);
+console.log(decrypted); // "Hello World!"
 
-```typescript
-// Throwing version - simpler but requires try/catch
-const message = encrypt('Secret message', secretKey);
-console.log(`Encrypted message: ${message}`);
+// Web - including Deno, Bun, Cloudflare Workers
+import { createSecretKey, encrypt, decrypt } from "cipher-kit/web-api";
 
-// Non-throwing version - returns a Result<T> object
-const message = tryEncrypt('Secret message', secretKey);
-if (message.success) {
-  console.log(`Encrypted message: ${message.result}`);
-} else {
-  console.error(`Encryption failed: ${message.error.message} - ${message.error.description}`);
-}
+const secretKey = await createSecretKey("my-passphrase");
+const encrypted = await encrypt("Hello World!", secretKey);
+const decrypted = await decrypt(encrypted, secretKey);
+console.log(decrypted); // "Hello World!"
 ```
 
-### The `webKit` and `nodeKit` Objects
+## Usage 🪛
+
+Table of Contents:
+
+- [webKit and nodeKit](#webkit-and-nodekit-objects-)
+- [The try Prefix](#the-try-prefix-non-throwing-result-api-)
+- [Encryption & Decryption](#encryption--decryption-)
+  - [Secret Key Creation](#secret-key-creation-)
+  - [Encrypting Data](#encrypting-data-)
+  - [Decrypting Data](#decrypting-data-)
+  - [Encrypting & Decrypting Objects](#encrypting--decrypting-objects-)
+- [Hashing](#hashing-)
+- [UUID Generation](#uuid-generation-)
+- [Password Hashing & Verification](#password-hashing--verification-)
+- [Encoding & Decoding](#encoding--decoding-)
+- [Object Serialization & Deserialization](#object-serialization--deserialization-)
+- [Regex Utilities](#regex-utilities-)
+
+### `webKit` and `nodeKit` Objects 📦
 
 The `webKit` and `nodeKit` objects provide platform-specific implementations for Web (including Deno, Bun, and Cloudflare Workers) and Node.js environments, respectively.
 
 You can also import them directly from `cipher-kit/web-api` and `cipher-kit/node` for smaller bundle sizes.
 
 ```typescript
-import { webKit, nodeKit } from 'cipher-kit';
-import { isNodeSecretKey } from 'cipher-kit/node';
-import { isWebSecretKey } from 'cipher-kit/web-api';
+// Option A: import helpers directly
+import { isNodeSecretKey } from "cipher-kit/node";
+import { isWebSecretKey } from "cipher-kit/web-api";
 
-// These are the same:
 function isSecretKey(key: unknown): boolean {
   return isNodeSecretKey(key) || isWebSecretKey(key);
 }
 
+// Option B: via kits from the root export
+import { webKit, nodeKit } from "cipher-kit";
+
 function isSecretKey(key: unknown): boolean {
   return nodeKit.isNodeSecretKey(key) || webKit.isWebSecretKey(key);
 }
 ```
 
-### Encryption and Decryption
+### The `try` Prefix (Non-Throwing `Result` API) 🤔
 
-Encryption is the process of converting readable plaintext into unreadable ciphertext using an algorithm and a secret key to protect its confidentiality. Decryption is the reverse process, using the same algorithm and the correct key to convert the ciphertext back into its original, readable plaintext form.
+The `try` prefix functions return a `Result<T>` object that indicates success or failure without throwing exceptions.
+
+This is useful in scenarios where you want to handle errors gracefully without using `try/catch` blocks.
+
+```typescript
+// Throwing version - simpler but requires try/catch
+const msg = encrypt("Secret message", secretKey);
+console.log(`Encrypted message: ${msg}`);
 
-The package provides functions for both encryption and decryption. On top of that the function provides `encryptObj` and `decryptObj` functions that work the same way but for objects (using JSON serialization).
+// Non-throwing version - returns a Result<T> object
+const msg = tryEncrypt("Secret message", secretKey);
 
-#### Secret Key Creation
+// Either check for success status
+if (msg.success) console.log(`Encrypted message: ${msg.result}`);
+else console.error(`${msg.error.message} - ${msg.error.description}`);
+
+// Or Check that there is no error
+if (!msg.error) console.log(`Encrypted message: ${msg.result}`);
+else console.error(`${msg.error.message} - ${msg.error.description}`);
+```
+
+### Encryption & Decryption 🤫
+
+Encryption is the process of converting readable plaintext into unreadable ciphertext using an algorithm and a secret key to protect its confidentiality. Decryption is the reverse process, using the same algorithm and the correct key to convert the ciphertext back into its original, readable plaintext form.
+
+#### _Secret Key Creation_ 🔑
 
 Before encrypting or decrypting data, you need to create a secret key.
+The key must be at least 8 characters long.
 
 Each key is tied to a specific platform (Web or Node.js) and cannot be used interchangeably.
 
 ```typescript
-import { createSecretKey } from 'cipher-kit/node'; // or 'cipher-kit/web-api'
+// Node.js example
+import { createSecretKey } from "cipher-kit/node";
+
+const nodeSecretKey = createSecretKey("my-passphrase");
 
-const secretKey = createSecretKey('my-passphrase');
+// Web example
+import { createSecretKey } from "cipher-kit/web-api";
+
+const webSecretKey = await createSecretKey("my-passphrase");
 ```
 
 The function accepts an optional `options` as well, which allows you to customize the key derivation process.
@@ -105,10 +150,10 @@ The function accepts an optional `options` as well, which allows you to customiz
 ```typescript
 interface CreateSecretKeyOptions {
   // Which encryption algorithm to use (default: "aes256gcm")
-  algorithm?: 'aes256gcm' | 'aes192gcm' | 'aes128gcm';
+  algorithm?: "aes256gcm" | "aes192gcm" | "aes128gcm";
 
   // Digest algorithm for HKDF (key derivation) (default: "sha256")
-  digest?: 'sha256' | 'sha384' | 'sha512';
+  digest?: "sha256" | "sha384" | "sha512";
 
   // Optional salt for HKDF (key derivation), if you provide a random one it will return a different key each time (default: "cipher-kit-salt", must be >= 8 characters).
   salt?: string;
@@ -118,12 +163,24 @@ interface CreateSecretKeyOptions {
 }
 ```
 
-#### Encrypting Data
+#### _Encrypting Data_ 🔐
+
+Ciphertext formats differ between Web and Node.js platforms.
+
+- Node.js - `iv.cipher.tag.` (3 parts)
+- Web - `iv.cipherWithTag.` (2 parts)
 
 ```typescript
-import { encrypt } from 'cipher-kit/node'; // or 'cipher-kit/web-api'
+// Node.js example
+import { encrypt } from "cipher-kit/node";
+
+const encrypted = encrypt("Hello, World!", nodeSecretKey);
+console.log(`Encrypted: ${encrypted}`);
+
+// Web example
+import { encrypt } from "cipher-kit/web-api";
 
-const encrypted = encrypt('Hello, World!', secretKey);
+const encrypted = await encrypt("Hello, World!", webSecretKey);
 console.log(`Encrypted: ${encrypted}`);
 ```
 
@@ -132,16 +189,25 @@ The function accepts an optional `options` parameter to customize the output enc
 ```typescript
 interface EncryptOptions {
   // Output ciphertext encoding(default: "base64url")
-  encoding?: 'base64url' | 'base64' | 'hex';
+  outputEncoding?: "base64url" | "base64" | "hex";
 }
 ```
 
-#### Decrypting Data
+#### _Decrypting Data_ 🔓
+
+Since ciphertext formats differ between Web and Node.js platforms, make sure to use the correct `decrypt` function for the platform where the data was encrypted.
 
 ```typescript
-import { decrypt } from 'cipher-kit/node'; // or 'cipher-kit/web-api'
+// Node.js example
+import { decrypt } from "cipher-kit/node";
 
-const decrypted = decrypt(encrypted, secretKey);
+const decrypted = decrypt(encrypted, nodeSecretKey);
+console.log(`Decrypted: ${decrypted}`);
+
+// Web example
+import { decrypt } from "cipher-kit/web-api";
+
+const decrypted = await decrypt(encrypted, webSecretKey);
 console.log(`Decrypted: ${decrypted}`);
 ```
 
@@ -152,18 +218,53 @@ Make sure to use the same encoding that was used during encryption.
 ```typescript
 interface DecryptOptions {
   // Input ciphertext encoding (default: "base64url")
-  encoding?: 'base64url' | 'base64' | 'hex';
+  inputEncoding?: "base64url" | "base64" | "hex";
 }
 ```
 
-### Hashing
+#### _Encrypting & Decrypting Objects_ 🧬
+
+```typescript
+// Node.js example
+import { encryptObj, decryptObj } from "cipher-kit/node";
+
+const obj = { name: "Alice", age: 30, city: "Wonderland" };
+
+const encryptedObj = encryptObj(obj, nodeSecretKey);
+
+const decryptedObj = decryptObj<typeof obj>(encryptedObj, nodeSecretKey);
+console.log(`Decrypted Object:`, decryptedObj);
+
+// Web example
+import { encryptObj, decryptObj } from "cipher-kit/web-api";
+
+const obj = { name: "Alice", age: 30, city: "Wonderland" };
+
+const encryptedObj = await encryptObj(obj, webSecretKey);
+
+const decryptedObj = await decryptObj<typeof obj>(encryptedObj, webSecretKey);
+console.log(`Decrypted Object:`, decryptedObj);
+```
+
+The `encryptObj` and `decryptObj` functions accept the same `options` parameters as `encrypt` and `decrypt`, respectively.
+
+### Hashing 🪄
 
 Hashing is a one-way process that uses an algorithm to transform data of any size into a fixed-length string of characters, called a hash value or digest. It serves as a digital fingerprint for the data, enabling quick data retrieval in hash tables, password storage, and file integrity checks. Key features include its irreversibility (you can't get the original data back from the hash).
 
+Not suitable for storing passwords - use `hashPassword` instead.
+
 ```typescript
-import { hash } from 'cipher-kit/node'; // or 'cipher-kit/web-api'
+// Node.js example
+import { hash } from "cipher-kit/node";
+
+const hashed = hash("Hello, World!");
+console.log(`Hashed: ${hashed}`);
 
-const hashed = hash('Hello, World!');
+// Web example
+import { hash } from "cipher-kit/web-api";
+
+const hashed = await hash("Hello, World!");
 console.log(`Hashed: ${hashed}`);
 ```
 
@@ -172,40 +273,56 @@ The function accepts an optional `options` parameter to customize the hashing pr
 ```typescript
 interface HashOptions {
   // Digest algorithm to use (default: "sha256").
-  digest?: 'sha256' | 'sha384' | 'sha512';
+  digest?: "sha256" | "sha384" | "sha512";
 
   // Output encoding (default: "base64url").
-  encoding?: 'base64url' | 'base64' | 'hex';
+  outputEncoding?: "base64url" | "base64" | "hex";
 }
 ```
 
-### UUID Generation
+### UUID Generation 🪪
 
 UUID (Universally Unique Identifier) is a 128-bit identifier used to uniquely identify information in computer systems. It is designed to be globally unique, meaning that no two UUIDs should be the same, even if generated on different systems or at different times. UUIDs are commonly used in databases, distributed systems, and applications where unique identification is crucial.
 
 ```typescript
-import { generateUUID } from 'cipher-kit/node'; // or 'cipher-kit/web-api'
+// Node.js example
+import { generateUuid } from "cipher-kit/node";
+
+const uuid = generateUuid();
+console.log(`Generated UUID: ${uuid}`);
 
-const uuid = generateUUID();
+// Web example
+import { generateUuid } from "cipher-kit/web-api";
+
+const uuid = generateUuid();
 console.log(`Generated UUID: ${uuid}`);
 ```
 
-### Password Hashing and Verification
+### Password Hashing & Verification 💎
 
 Password hashing is a one-way process that transforms a plaintext password into a fixed-length hash. Password hashing is crucial for securely storing passwords in databases, as it protects user credentials from being exposed in case of a data breach.
 
 Password hashing is different from general-purpose hashing because it often involves additional techniques like salting and key stretching to enhance security against brute-force attacks, and it's usually slower to compute to make rainbow table attacks less feasible.
 
-To verify a password, the same hashing process is applied to the input password, and the resulting hash is compared to the stored hash, in a time-safe manner to prevent timing attacks.
+To verify a password, the same hashing process is applied to the input password, and the resulting hash is compared to the stored hash, in a constant-time comparison to prevent timing attacks.
 
 ```typescript
-import { hashPassword, verifyPassword } from 'cipher-kit/node'; // or 'cipher-kit/web-api'
+// Node.js example
+import { hashPassword, verifyPassword } from "cipher-kit/node";
+
+const { result, salt } = hashPassword("some-secure-password");
+console.log(`Hashed Password: ${result}`);
+
+const isMatch = verifyPassword("some-secure-password", result, salt);
+console.log(`Password match: ${isMatch}`);
+
+// Web example
+import { hashPassword, verifyPassword } from "cipher-kit/web-api";
 
-const password = 'my-secure-password';
-const hashedPassword = hashPassword(password);
-console.log(`Hashed Password: ${hashedPassword}`);
+const { result, salt } = await hashPassword("some-secure-password");
+console.log(`Hashed Password: ${result}`);
 
-const isMatch = verifyPassword(password, hashedPassword);
+const isMatch = await verifyPassword("some-secure-password", result, salt);
 console.log(`Password match: ${isMatch}`);
 ```
 
@@ -214,10 +331,10 @@ The `hashPassword` and `verifyPassword` functions accept an optional `options` p
 ```typescript
 interface HashPasswordOptions {
   // Digest algorithm to use (default: "sha512").
-  digest?: 'sha256' | 'sha384' | 'sha512';
+  digest?: "sha256" | "sha384" | "sha512";
 
   // Encoding format for the output hash (default: "base64url").
-  encoding?: 'base64url' | 'base64' | 'hex';
+  outputEncoding?: "base64url" | "base64" | "hex";
 
   // Length of the salt in bytes (default: 16 bytes, min: 8 bytes).
   saltLength?: number;
@@ -231,10 +348,10 @@ interface HashPasswordOptions {
 
 interface VerifyPasswordOptions {
   // Digest algorithm used during the original hashing (default: `'sha512'`).
-  digest?: 'sha256' | 'sha384' | 'sha512';
+  digest?: "sha256" | "sha384" | "sha512";
 
   // Encoding format used during the original hashing (default: `'base64url'`).
-  encoding?: 'base64url' | 'base64' | 'hex';
+  inputEncoding?: "base64url" | "base64" | "hex";
 
   // Number of iterations used during the original hashing (default: `320000`).
   iterations?: number;
@@ -244,18 +361,74 @@ interface VerifyPasswordOptions {
 }
 ```
 
-<!-- TODO obj <-> string, bytes <-> string, regex -->
+### Encoding & Decoding 🧩
+
+Encoding and decoding are processes used to convert data into a specific format for efficient transmission, storage, or representation. Encoding transforms data into a different format using a specific scheme, while decoding reverses this process to retrieve the original data. Common encoding schemes include Base64, Base64URL, and Hexadecimal (Hex).
+
+```typescript
+// Node.js and Web example - works the same in both
+import { convertStrToBytes, convertBytesToStr, convertEncoding } from "cipher-kit/node"; // or "cipher-kit/web-api"
+
+// Encoding
+const buffer = convertStrToBytes("Hello World!", "utf8"); // the input encoding
+console.log(`Encoded: ${buffer}`);
+
+// Decoding
+const str = convertBytesToStr(buffer, "utf8"); // the output encoding
+console.log(`Decoded: ${str}`);
+
+// Convert between encodings
+const base64 = convertEncoding("Hello World!", "utf8", "base64");
+console.log(`Base64: ${base64}`);
+```
+
+### Object Serialization & Deserialization 🧬
+
+Object serialization in JavaScript is the process of converting objects or arrays into a JSON string representation, that can be easily stored or transmitted. Deserialization is the reverse process, where the JSON string is parsed back into its original object or array structure.
+
+```typescript
+import { stringifyObj, parseToObj } from "cipher-kit"; // works in both "cipher-kit/web-api" and "cipher-kit/node"
+
+const obj = { name: "Alice", age: 30, city: "Wonderland" };
+
+const jsonString = stringifyObj(obj);
+console.log(`Serialized: ${jsonString}`);
+
+const parsedObj = parseToObj<typeof obj>(jsonString);
+console.log(`Deserialized:`, parsedObj);
+```
+
+### Regex Utilities 🔍
+
+Regular expressions (regex) are sequences of characters that form search patterns, used for pattern matching within strings.
+
+Before decrypting, you can validate the format (decryption functions already validate internally).
+
+```typescript
+import { ENCRYPTED_REGEX, matchEncryptedPattern } from "cipher-kit"; // works in both "cipher-kit/web-api" and "cipher-kit/node"
+
+function isEncryptedFormat(message: string): boolean {
+  return matchEncryptedPattern(message, "general"); // or "node" or "web"
+}
+
+// or
+
+function isEncryptedFormat(message: string): boolean {
+  return ENCRYPTED_REGEX.general.test(message); // or "node" or "web"
+}
+```
 
 ## Contributions 🤝
 
-Want to contribute or suggest a feature?
+Want to contribute or suggest a feature or improvement?
 
 - Open an issue or feature request
 - Submit a PR to improve the packages or add new ones
 - Star ⭐ the repo if you like what you see
 
-## License 📜
-
-This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).
-
-Thank you!
+<div align="center">
+<br/>
+<div style="font-size: 14px; font-weight:bold;"> ⚒️ Crafted carefully by <a href="https://github.com/WolfieLeader" target="_blank" rel="nofollow">WolfieLeader</a></div>
+<p style="font-size: 12px; font-style: italic;">This project is licensed under the <a href="https://opensource.org/licenses/MIT" target="_blank" rel="nofollow">MIT License</a>.</p>
+<div style="font-size: 12px; font-style: italic; font-weight: 600;">Thank you!</div>
+</div>

package/dist/{chunk-3FJZA77A.cjs → chunk-BHG5RSUV.cjs}

@@ -30,22 +30,22 @@ var ENCRYPTION_ALGORITHMS = Object.freeze({
 function $isStr(x, min = 1) {
   return x !== null && x !== void 0 && typeof x === "string" && x.trim().length >= min;
 }
-function $isObj(x) {
+function $isPlainObj(x) {
   if (typeof x !== "object" || x === null || x === void 0) return false;
   const proto = Object.getPrototypeOf(x);
   return proto === Object.prototype || proto === null;
 }
-function $isLooseObj(x) {
+function $isObj(x) {
   return typeof x === "object" && x !== null && x !== void 0;
 }
 var expectedKeys = /* @__PURE__ */ new Set(["platform", "digest", "algorithm", "key"]);
 function $isSecretKey(x, platform) {
-  if (!$isLooseObj(x) || platform !== "node" && platform !== "web" || x.platform !== platform) return null;
+  if (!$isObj(x) || platform !== "node" && platform !== "web" || x.platform !== platform) return null;
   const keys = Object.keys(x);
   if (keys.length !== expectedKeys.size) return null;
   for (const key of keys) if (!expectedKeys.has(key)) return null;
   for (const key of expectedKeys) if (!Object.hasOwn(x, key)) return null;
-  if (typeof x.digest !== "string" || !(x.digest in DIGEST_ALGORITHMS) || typeof x.algorithm !== "string" || !(x.algorithm in ENCRYPTION_ALGORITHMS) || !$isLooseObj(x.key) || x.key.type !== "secret") {
+  if (typeof x.digest !== "string" || !(x.digest in DIGEST_ALGORITHMS) || typeof x.algorithm !== "string" || !(x.algorithm in ENCRYPTION_ALGORITHMS) || !$isObj(x.key) || x.key.type !== "secret") {
     return null;
   }
   const algorithm = ENCRYPTION_ALGORITHMS[x.algorithm];
@@ -55,7 +55,7 @@ function $isSecretKey(x, platform) {
     }
     return Object.freeze({ ...x, injected: algorithm });
   }
-  if (!$isLooseObj(x.key.algorithm) || x.key.algorithm.name !== algorithm.web || typeof x.key.algorithm.length === "number" && x.key.algorithm.length !== algorithm.keyBytes * 8 || typeof x.key.extractable !== "boolean" || !Array.isArray(x.key.usages) || x.key.usages.length !== 2 || !(x.key.usages.includes("encrypt") && x.key.usages.includes("decrypt"))) {
+  if (!$isObj(x.key.algorithm) || x.key.algorithm.name !== algorithm.web || typeof x.key.algorithm.length === "number" && x.key.algorithm.length !== algorithm.keyBytes * 8 || typeof x.key.extractable !== "boolean" || !Array.isArray(x.key.usages) || x.key.usages.length !== 2 || !(x.key.usages.includes("encrypt") && x.key.usages.includes("decrypt"))) {
     return null;
   }
   return Object.freeze({ ...x, injected: algorithm });
@@ -65,7 +65,7 @@ var ENCRYPTED_REGEX = Object.freeze({
   web: /^([^.]+)\.([^.]+)\.$/,
   general: /^([^.]+)\.([^.]+)(?:\.([^.]+))?\.$/
 });
-function matchPattern(data, format) {
+function matchEncryptedPattern(data, format) {
   if (typeof data !== "string") return false;
   if (!(format in ENCRYPTED_REGEX)) throw new Error(`Unknown format: ${format}`);
   return ENCRYPTED_REGEX[format].test(data);
@@ -73,7 +73,7 @@ function matchPattern(data, format) {
 
 // src/helpers/error.ts
 function $ok(result) {
-  if ($isObj(result)) return { success: true, ...result };
+  if ($isPlainObj(result)) return { success: true, ...result };
   return { success: true, result };
 }
 function $err(err) {
@@ -101,30 +101,31 @@ function title(platform, title2) {
 // src/helpers/object.ts
 function $stringifyObj(obj) {
   try {
-    if (!$isObj(obj)) return $err({ msg: "Invalid object", desc: "Input is not a plain object" });
+    if (!$isPlainObj(obj)) return $err({ msg: "Invalid object", desc: "Input is not a plain object" });
     return $ok(JSON.stringify(obj));
   } catch (error) {
     return $err({ msg: "Utility: Stringify error", desc: $fmtError(error) });
   }
 }
-function tryStringifyObj(obj) {
-  return $stringifyObj(obj);
-}
-function stringifyObj(obj) {
-  const { result, error } = $stringifyObj(obj);
-  if (error) throw new Error($fmtResultErr(error));
-  return result;
-}
 function $parseToObj(str) {
   try {
     if (!$isStr(str)) return $err({ msg: "Utility: Invalid input", desc: "Input is not a valid string" });
     const obj = JSON.parse(str);
-    if (!$isObj(obj)) return $err({ msg: "Utility: Invalid object format", desc: "Parsed data is not a plain object" });
+    if (!$isPlainObj(obj))
+      return $err({ msg: "Utility: Invalid object format", desc: "Parsed data is not a plain object" });
     return $ok({ result: obj });
   } catch (error) {
     return $err({ msg: "Utility: Invalid format", desc: $fmtError(error) });
   }
 }
+function tryStringifyObj(obj) {
+  return $stringifyObj(obj);
+}
+function stringifyObj(obj) {
+  const { result, error } = $stringifyObj(obj);
+  if (error) throw new Error($fmtResultErr(error));
+  return result;
+}
 function tryParseToObj(str) {
   return $parseToObj(str);
 }
@@ -137,6 +138,7 @@ function parseToObj(str) {
 exports.$err = $err;
 exports.$fmtError = $fmtError;
 exports.$fmtResultErr = $fmtResultErr;
+exports.$isPlainObj = $isPlainObj;
 exports.$isSecretKey = $isSecretKey;
 exports.$isStr = $isStr;
 exports.$ok = $ok;
@@ -148,11 +150,11 @@ exports.ENCODING = ENCODING;
 exports.ENCRYPTED_REGEX = ENCRYPTED_REGEX;
 exports.ENCRYPTION_ALGORITHMS = ENCRYPTION_ALGORITHMS;
 exports.__export = __export;
-exports.matchPattern = matchPattern;
+exports.matchEncryptedPattern = matchEncryptedPattern;
 exports.parseToObj = parseToObj;
 exports.stringifyObj = stringifyObj;
 exports.title = title;
 exports.tryParseToObj = tryParseToObj;
 exports.tryStringifyObj = tryStringifyObj;
-//# sourceMappingURL=chunk-3FJZA77A.cjs.map
-//# sourceMappingURL=chunk-3FJZA77A.cjs.map
+//# sourceMappingURL=chunk-BHG5RSUV.cjs.map
+//# sourceMappingURL=chunk-BHG5RSUV.cjs.map

package/dist/chunk-BHG5RSUV.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/helpers/consts.ts","../src/helpers/validate.ts","../src/helpers/error.ts","../src/helpers/object.ts"],"names":["nodeCrypto","title"],"mappings":"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","file":"chunk-BHG5RSUV.cjs","sourcesContent":["export const ENCODING = Object.freeze([\"base64\", \"base64url\", \"hex\", \"utf8\", \"latin1\"] as const);\r\n\r\nexport const CIPHER_ENCODING = Object.freeze([\"base64\", \"base64url\", \"hex\"] as const);\r\n\r\nexport const DIGEST_ALGORITHMS = Object.freeze({\r\n  sha256: { node: \"sha256\", web: \"SHA-256\" },\r\n  sha384: { node: \"sha384\", web: \"SHA-384\" },\r\n  sha512: { node: \"sha512\", web: \"SHA-512\" },\r\n} as const);\r\n\r\nexport const ENCRYPTION_ALGORITHMS = Object.freeze({\r\n  aes256gcm: { keyBytes: 32, ivLength: 12, node: \"aes-256-gcm\", web: \"AES-GCM\" },\r\n  aes192gcm: { keyBytes: 24, ivLength: 12, node: \"aes-192-gcm\", web: \"AES-GCM\" },\r\n  aes128gcm: { keyBytes: 16, ivLength: 12, node: \"aes-128-gcm\", web: \"AES-GCM\" },\r\n} as const);\r\n","import nodeCrypto from \"node:crypto\";\r\nimport type { SecretKey } from \"~/helpers/types\";\r\nimport { DIGEST_ALGORITHMS, ENCRYPTION_ALGORITHMS } from \"./consts\";\r\n\r\nexport function $isStr(x: unknown, min = 1): x is string {\r\n  return x !== null && x !== undefined && typeof x === \"string\" && x.trim().length >= min;\r\n}\r\n\r\nexport function $isPlainObj<T extends object = Record<string, unknown>>(x: unknown): x is T {\r\n  if (typeof x !== \"object\" || x === null || x === undefined) return false;\r\n  const proto = Object.getPrototypeOf(x);\r\n  return proto === Object.prototype || proto === null;\r\n}\r\n\r\nexport function $isObj(x: unknown): x is Record<string, unknown> {\r\n  return typeof x === \"object\" && x !== null && x !== undefined;\r\n}\r\n\r\ntype InjectedSecretKey<Platform extends \"web\" | \"node\"> = SecretKey<Platform> & {\r\n  readonly injected: (typeof ENCRYPTION_ALGORITHMS)[keyof typeof ENCRYPTION_ALGORITHMS];\r\n};\r\n\r\nconst expectedKeys = new Set([\"platform\", \"digest\", \"algorithm\", \"key\"]);\r\n\r\nexport function $isSecretKey<Platform extends \"node\" | \"web\">(\r\n  x: unknown,\r\n  platform: Platform,\r\n): InjectedSecretKey<Platform> | null {\r\n  if (!$isObj(x) || (platform !== \"node\" && platform !== \"web\") || x.platform !== platform) return null;\r\n\r\n  const keys = Object.keys(x);\r\n  if (keys.length !== expectedKeys.size) return null;\r\n  for (const key of keys) if (!expectedKeys.has(key)) return null;\r\n  for (const key of expectedKeys) if (!Object.hasOwn(x, key)) return null;\r\n\r\n  if (\r\n    typeof x.digest !== \"string\" ||\r\n    !(x.digest in DIGEST_ALGORITHMS) ||\r\n    typeof x.algorithm !== \"string\" ||\r\n    !(x.algorithm in ENCRYPTION_ALGORITHMS) ||\r\n    !$isObj(x.key) ||\r\n    x.key.type !== \"secret\"\r\n  ) {\r\n    return null;\r\n  }\r\n\r\n  const algorithm = ENCRYPTION_ALGORITHMS[x.algorithm as keyof typeof ENCRYPTION_ALGORITHMS];\r\n\r\n  if (platform === \"node\") {\r\n    if (\r\n      !(x.key instanceof nodeCrypto.KeyObject) ||\r\n      (typeof x.key.symmetricKeySize === \"number\" && x.key.symmetricKeySize !== algorithm.keyBytes)\r\n    ) {\r\n      return null;\r\n    }\r\n    return Object.freeze({ ...x, injected: algorithm }) as InjectedSecretKey<Platform>;\r\n  }\r\n\r\n  if (\r\n    !$isObj(x.key.algorithm) ||\r\n    x.key.algorithm.name !== algorithm.web ||\r\n    (typeof x.key.algorithm.length === \"number\" && x.key.algorithm.length !== algorithm.keyBytes * 8) ||\r\n    typeof x.key.extractable !== \"boolean\" ||\r\n    !Array.isArray(x.key.usages) ||\r\n    x.key.usages.length !== 2 ||\r\n    !(x.key.usages.includes(\"encrypt\") && x.key.usages.includes(\"decrypt\"))\r\n  ) {\r\n    return null;\r\n  }\r\n  return Object.freeze({ ...x, injected: algorithm }) as InjectedSecretKey<Platform>;\r\n}\r\n\r\n/**\r\n * Regular expressions for encrypted data patterns.\r\n *\r\n * - **node**: `\"iv.cipher.tag.\"` (three dot-separated parts plus a trailing dot)\r\n * - **web**: `\"iv.cipherWithTag.\"` (two parts plus a trailing dot)\r\n * - **general**: accepts both shapes (2 or 3 parts) with a trailing dot\r\n *\r\n * Each part is any non-empty string without dots.\r\n *\r\n * ### 🍼 Explain Like I'm Five\r\n * You have a secret code you want to check. Before you check it,\r\n * you make sure it looks how a secret code should look.\r\n */\r\nexport const ENCRYPTED_REGEX = Object.freeze({\r\n  node: /^([^.]+)\\.([^.]+)\\.([^.]+)\\.$/,\r\n  web: /^([^.]+)\\.([^.]+)\\.$/,\r\n  general: /^([^.]+)\\.([^.]+)(?:\\.([^.]+))?\\.$/,\r\n});\r\n\r\n/**\r\n * Checks if a string matches an expected encrypted payload shape.\r\n *\r\n * - **node**: `\"iv.cipher.tag.\"` (three dot-separated parts plus a trailing dot)\r\n * - **web**: `\"iv.cipherWithTag.\"` (two parts plus a trailing dot)\r\n * - **general**: accepts both shapes (2 or 3 parts) with a trailing dot\r\n *\r\n * Each part is any non-empty string without dots.\r\n *\r\n * This validates only the **shape**, not whether content is valid base64/hex, etc.\r\n *\r\n * ### 🍼 Explain Like I'm Five\r\n * You have a secret code you want to check. Before you check it,\r\n * you make sure it looks how a secret code should look.\r\n *\r\n * @param data - The string to test.\r\n * @param format - Which layout to check: `'node'`, `'web'`, or `'general'`.\r\n * @returns `true` if the string matches the pattern; otherwise `false`.\r\n * @throws {Error} If an unknown `format` is provided.\r\n *\r\n * @example\r\n * ```ts\r\n * matchEncryptedPattern(\"abc.def.ghi.\", \"node\");    // true\r\n * matchEncryptedPattern(\"abc.def.\", \"web\");         // true\r\n * matchEncryptedPattern(\"abc.def.\", \"node\");        // false\r\n * matchEncryptedPattern(\"abc.def.ghi.\", \"general\"); // true\r\n * ```\r\n */\r\nexport function matchEncryptedPattern(data: string, format: \"general\" | \"node\" | \"web\"): boolean {\r\n  if (typeof data !== \"string\") return false;\r\n  if (!(format in ENCRYPTED_REGEX)) throw new Error(`Unknown format: ${format}`);\r\n  return ENCRYPTED_REGEX[format].test(data);\r\n}\r\n","import { $isPlainObj } from \"./validate\";\r\n\r\n/**\r\n * Standardized error object for the `Result` type.\r\n * Always has a brief `message` and a more detailed `description`.\r\n */\r\nexport interface ResultErr {\r\n  readonly message: string;\r\n  readonly description: string;\r\n}\r\n\r\n/**\r\n * Discriminated union for functions that can succeed or fail.\r\n *\r\n * - On **success**:\r\n *   - If `T` is an object - properties of `T` are **spread** into the result\r\n *     along with `success: true`.\r\n *   - Otherwise - `{ success: true, result: T }`.\r\n * - On **failure**: `{ success: false, error: E }`.\r\n *\r\n * @example\r\n * ```ts\r\n * // Primitive result\r\n * function getNum(): Result<number> {\r\n *   return $ok(42);\r\n * }\r\n * const r1 = getNum();\r\n * if (r1.success) console.log(r1.result); // 42\r\n *\r\n * // Object result (spread)\r\n * function getObject(): Result<{ name: string; age: number }> {\r\n *   return $ok({ name: 'Alice', age: 30 });\r\n * }\r\n * const r2 = getObject();\r\n * if (r2.success) console.log(r2.name, r2.age); // 'Alice' 30\r\n * ```\r\n */\r\nexport type Result<T, E = ResultErr> = T extends object\r\n  ?\r\n      | ({ readonly [K in keyof T]: T[K] } & { readonly success: true; readonly error?: undefined })\r\n      | ({ readonly [K in keyof T]?: undefined } & { readonly success: false; readonly error: E })\r\n  :\r\n      | { readonly success: true; readonly result: T; readonly error?: undefined }\r\n      | { readonly success: false; readonly error: E; readonly result?: undefined };\r\n\r\nexport function $ok<T>(result?: T): Result<T> {\r\n  if ($isPlainObj(result)) return { success: true, ...(result as T & object) } as Result<T>;\r\n  return { success: true, result } as Result<T>;\r\n}\r\n\r\nexport function $err(err: { msg: string; desc: string }): Result<never, ResultErr>;\r\nexport function $err(err: ResultErr): Result<never, ResultErr>;\r\nexport function $err(err: { msg: string; desc: string } | ResultErr): Result<never, ResultErr> {\r\n  return {\r\n    success: false,\r\n    error: {\r\n      message: \"msg\" in err ? err.msg : err.message,\r\n      description: \"desc\" in err ? err.desc : err.description,\r\n    },\r\n  } as Result<never, ResultErr>;\r\n}\r\n\r\nexport function $fmtError(error: unknown): string {\r\n  if (typeof error === \"string\") return error;\r\n  if (error instanceof Error) return error.message;\r\n  return String(error);\r\n}\r\n\r\nexport function $fmtResultErr(err: ResultErr | undefined): string {\r\n  if (!err) return \"Unknown error\";\r\n  return `${err.message} - ${err.description}`;\r\n}\r\n\r\nexport function title(platform: \"web\" | \"node\", title: string): string {\r\n  return `${platform === \"web\" ? \"Crypto Web API\" : \"Crypto NodeJS API\"} - ${title}`;\r\n}\r\n","import { $err, $fmtError, $fmtResultErr, $ok, type Result } from \"./error\";\r\nimport { $isPlainObj, $isStr } from \"./validate\";\r\n\r\nexport function $stringifyObj<T extends object = Record<string, unknown>>(obj: T): Result<string> {\r\n  try {\r\n    if (!$isPlainObj(obj)) return $err({ msg: \"Invalid object\", desc: \"Input is not a plain object\" });\r\n    return $ok(JSON.stringify(obj));\r\n  } catch (error) {\r\n    return $err({ msg: \"Utility: Stringify error\", desc: $fmtError(error) });\r\n  }\r\n}\r\n\r\nexport function $parseToObj<T extends object = Record<string, unknown>>(str: string): Result<{ result: T }> {\r\n  try {\r\n    if (!$isStr(str)) return $err({ msg: \"Utility: Invalid input\", desc: \"Input is not a valid string\" });\r\n    const obj = JSON.parse(str);\r\n\r\n    if (!$isPlainObj(obj))\r\n      return $err({ msg: \"Utility: Invalid object format\", desc: \"Parsed data is not a plain object\" });\r\n    return $ok({ result: obj as T });\r\n  } catch (error) {\r\n    return $err({ msg: \"Utility: Invalid format\", desc: $fmtError(error) });\r\n  }\r\n}\r\n\r\n/**\r\n * Safely serializes a plain object to JSON without throwing.\r\n *\r\n * Wraps `JSON.stringify` and returns a `Result` containing the JSON string or an error.\r\n * Only plain objects (POJOs) are accepted. Class instances, Maps, Sets, etc. are rejected.\r\n *\r\n * ### 🍼 Explain Like I'm Five\r\n * You have a box of toys (your object) and take a photo of it (a JSON string)\r\n * so you can send it to a friend.\r\n *\r\n * @template T - Plain object type to serialize.\r\n * @param obj - The object to stringify (must be a plain object).\r\n * @returns A `Result` with the JSON string on success, or an error.\r\n *\r\n * @example\r\n * ```ts\r\n * const { result, error, success } = tryStringifyObj({ a: 1 });\r\n *\r\n * if (success) console.log(result); // \"{\\\"a\\\":1}\"\r\n * else console.error(error); // { message: \"...\", description: \"...\" }\r\n * ```\r\n */\r\nexport function tryStringifyObj<T extends object = Record<string, unknown>>(obj: T): Result<string> {\r\n  return $stringifyObj(obj);\r\n}\r\n\r\n/**\r\n * Serializes a plain object to JSON (throwing).\r\n *\r\n * Wraps `JSON.stringify` and returns the result or throws an error.\r\n * Only plain objects (POJOs) are accepted. Class instances, Maps, Sets, etc. are rejected.\r\n *\r\n * ### 🍼 Explain Like I'm Five\r\n * You have a box of toys (your object) and take a photo of it (a JSON string)\r\n * so you can send it to a friend.\r\n *\r\n * @template T - Plain object type to serialize.\r\n * @param obj - The object to stringify (must be a plain object).\r\n * @returns JSON string representation of the object.\r\n * @throws {Error} If `obj` is not a plain object or serialization fails.\r\n *\r\n * @example\r\n * ```ts\r\n * const json = stringifyObj({ a: 1 }); // \"{\\\"a\\\":1}\"\r\n * ```\r\n */\r\nexport function stringifyObj<T extends object = Record<string, unknown>>(obj: T): string {\r\n  const { result, error } = $stringifyObj(obj);\r\n  if (error) throw new Error($fmtResultErr(error));\r\n  return result;\r\n}\r\n\r\n/**\r\n * Safely parses a JSON string to a plain object (non-throwing).\r\n *\r\n * Wraps `JSON.parse` and returns a `Result` containing the parsed object, or an error.\r\n *\r\n * ### 🍼 Explain Like I'm Five\r\n * You rebuild your toy box (an object) from a photo you took (a JSON string).\r\n *\r\n * @template T - The expected object type.\r\n * @param str - The JSON string to parse.\r\n * @returns A `Result` with the parsed object on success, or an error.\r\n *\r\n * @example\r\n * ```ts\r\n * const {result, error, success} = tryParseToObj<{ a: number }>('{\"a\":1}');\r\n *\r\n * if (success) console.log(result); // { a: 1 }\r\n * else console.error(error) // { message: \"...\", description: \"...\" }\r\n * ```\r\n */\r\nexport function tryParseToObj<T extends object = Record<string, unknown>>(str: string): Result<{ result: T }> {\r\n  return $parseToObj<T>(str);\r\n}\r\n\r\n/**\r\n * Parses a JSON string to a plain object (throwing).\r\n *\r\n * Wraps `JSON.parse` and returns the parsed object, or throws on failure.\r\n *\r\n * ### 🍼 Explain Like I'm Five\r\n * You rebuild your toy box (an object) from a photo you took (a JSON string).\r\n *\r\n * @template T - The expected object type.\r\n * @param str - The JSON string to parse.\r\n * @returns The parsed plain object.\r\n * @throws {Error} If the string can’t be parsed or doesn’t represent a plain object.\r\n *\r\n * @example\r\n * ```ts\r\n * const obj = parseToObj<{ a: number }>('{\"a\":1}'); // obj.a === 1\r\n * ```\r\n */\r\nexport function parseToObj<T extends object = Record<string, unknown>>(str: string): T {\r\n  const { result, error } = $parseToObj<T>(str);\r\n  if (error) throw new Error($fmtResultErr(error));\r\n  return result;\r\n}\r\n"]}