cipher-kit 2.0.0-beta.4 → 2.0.0

package/README.md

@@ -4,158 +4,417 @@
 <h1 align="center" style="font-weight:900;">cipher-kit</h1>
 
 <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>
 
-## About 📖
+## Why `cipher-kit`? 🤔
 
-`cipher-kit` is a modern encryption toolkit designed to work seamlessly across **Web**, **Node.js**, **Deno**, and **Bun** environments.  
-It provides a simple, secure, and dependency-free API for encrypting and decrypting data with **AES-GCM**, ensuring strong security, predictable behavior, and type safety.
-
-## Features 🌟
-
-- 🛡️ **AES-GCM Encryption** – Secure and authenticated encryption with built-in integrity checks.
-- 🌐 **Cross-Platform** – Works in Web, Node.js, Deno, and Bun without code changes.
+- 🛡️ **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 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.
-- 🔒 **SHA-256 Key Derivation** – Derives strong encryption keys from passwords.
-- 🧪 **Strict Validation & `Result<T>` Typing** – Unified return type with robust input validation.
+- 🍼 **Explain Like I'm Five** - Newbie-friendly explanations and documentation.
 
 ## Installation 🔥
 
 ```bash
 npm install cipher-kit@latest
+# or
+yarn add cipher-kit@latest
+# or
+pnpm install cipher-kit@latest
+# or
+bun add cipher-kit@latest
 ```
 
-> 💡 Works with `npm`, `pnpm`, `yarn`, `bun`, and `deno`. You can use it in dev dependencies since it's typically used only for local HTTPS.
+## Quick Start 🚀
+
+```typescript
+// Node.js Quick Start
+import { createSecretKey, encrypt, decrypt } from "cipher-kit/node";
+
+const nodeSecretKey = createSecretKey("my-passphrase");
+const encrypted = encrypt("Hello World!", nodeSecretKey);
+const decrypted = decrypt(encrypted, nodeSecretKey);
+console.log(decrypted); // "Hello World!"
+
+// Web Quick Start
+import { createSecretKey, encrypt, decrypt } from "cipher-kit/web-api";
+
+const webSecretKey = await createSecretKey("my-passphrase");
+const encrypted = await encrypt("Hello World!", webSecretKey);
+const decrypted = await decrypt(encrypted, webSecretKey);
+console.log(decrypted); // "Hello World!"
+```
 
 ## Usage 🪛
 
-Pick the runtime you’re targeting, or import from the root:
+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
-// For Node.js
-import { encrypt, decrypt } from 'cipher-kit/node';
+// Option A: import helpers directly
+import { isNodeSecretKey } from "cipher-kit/node";
+import { isWebSecretKey } from "cipher-kit/web-api";
+
+function isSecretKey(key: unknown): boolean {
+  return isNodeSecretKey(key) || isWebSecretKey(key);
+}
 
-// For Web API, Deno, Bun, Cloudflare Workers
-import { encrypt, decrypt } from 'cipher-kit/web-api';
+// Option B: via kits from the root export
+import { webKit, nodeKit } from "cipher-kit";
 
-// Or import everything from the root
-// Functions that, for example encrypt and decrypt will use Node.js implementation.
-// You can also access web and node object kits directly.
-import { encrypt, decrypt, nodeKit, webKit } from 'cipher-kit';
+function isSecretKey(key: unknown): boolean {
+  return nodeKit.isNodeSecretKey(key) || webKit.isWebSecretKey(key);
+}
 ```
 
-Functions that throw error will show that in their JSDoc comments.
+### The `try` Prefix (Non-Throwing `Result` API) 🤔
 
-If you would like to avoid using `try/catch`, you can use the functions that prefixed with `try`, e.g., `tryEncrypt`, `tryDecrypt`, `tryEncryptObj`, `tryDecryptObj`. You need to check if the `error` is `undefined` or the `success` is `true` to ensure the operation was successful.
+The `try` prefix functions return a `Result<T>` object that indicates success or failure without throwing exceptions.
 
-### Node.js Example:
+This is useful in scenarios where you want to handle errors gracefully without using `try/catch` blocks.
 
 ```typescript
-import {
-  generateUuid,
-  hash,
-  createSecretKey,
-  encrypt,
-  decrypt,
-  encryptObj,
-  decryptObj,
-  tryEncrypt,
-  tryDecrypt,
-} from 'cipher-kit/node';
+// Throwing version - simpler but requires try/catch
+const msg = encrypt("Secret message", secretKey);
+console.log(`Encrypted message: ${msg}`);
 
-const str = 'The brown fox 🦊 jumps over the lazy dog 🐶.';
+// Non-throwing version - returns a Result<T> object
+const msg = tryEncrypt("Secret message", secretKey);
 
-function nodeExample() {
-  console.log(`New UUID: ${generateUuid()}`);
+// 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}`);
+```
 
-  console.log(`SHA-256 Hash (ABCDEFG): ${hash('ABCDEFG')}`);
+### Encryption & Decryption 🤫
 
-  const secretKey = createSecretKey('my secure passphrase');
+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.
 
-  const encrypted = encrypt(str, secretKey);
-  console.log(`Encrypted Data: ${encrypted}`);
-  console.log(`Decrypted Data: ${decrypt(encrypted, secretKey)}`);
+#### _Secret Key Creation_ 🔑
 
-  const encryptedObj = encryptObj({ message: 'Hello, World! 🌍', count: 42 }, secretKey);
-  console.log(`Encrypted Object: ${encryptedObj}`);
-  console.log(`Decrypted Object: ${JSON.stringify(decryptObj(encryptedObj, secretKey))}`);
+Before encrypting or decrypting data, you need to create a secret key.
 
-  const { result: tryEncrypted, error: tryEncryptError } = tryEncrypt(str, secretKey);
-  if (tryEncryptError) {
-    console.error(`Encryption Try failed: ${tryEncryptError.message} - ${tryEncryptError.description}`);
-    return;
-  }
-  console.log(`Encrypted Try Data: ${tryEncrypted}`);
+Each key is tied to a specific platform (Web or Node.js) and cannot be used interchangeably.
 
-  const decryptedTry = tryDecrypt(tryEncrypted, secretKey);
-  if (decryptedTry.success === false) {
-    console.error(`Decryption Try failed: ${decryptedTry.error.message} - ${decryptedTry.error.description}`);
-    return;
-  }
-  console.log(`Try Decrypted Data: ${decryptedTry.result}`);
+```typescript
+// Node.js example
+import { createSecretKey } from "cipher-kit/node";
+
+const nodeSecretKey = 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.
+
+```typescript
+interface CreateSecretKeyOptions {
+  // Which encryption algorithm to use (default: "aes256gcm")
+  algorithm?: "aes256gcm" | "aes192gcm" | "aes128gcm";
+
+  // Digest algorithm for HKDF (key derivation) (default: "sha256")
+  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;
+
+  // Optional context info for HKDF (default: "cipher-kit").
+  info?: string;
 }
+```
+
+#### _Encrypting Data_ 🔐
+
+Ciphertext formats differ between Web and Node.js platforms.
+
+- Node.js - `iv.cipher.tag.` (3 parts)
+- Web - `iv.cipherWithTag.` (2 parts)
+
+```typescript
+// 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";
 
-nodeExample();
+const encrypted = await encrypt("Hello, World!", webSecretKey);
+console.log(`Encrypted: ${encrypted}`);
 ```
 
-### Web API Example:
+The function accepts an optional `options` parameter to customize the output encoding.
 
 ```typescript
-import {
-  generateUuid,
-  hash,
-  createSecretKey,
-  encrypt,
-  decrypt,
-  encryptObj,
-  decryptObj,
-  tryEncrypt,
-  tryDecrypt,
-} from 'cipher-kit/web-api';
+interface EncryptOptions {
+  // Output ciphertext encoding(default: "base64url")
+  encoding?: "base64url" | "base64" | "hex";
+}
+```
 
-const str = 'The brown fox 🦊 jumps over the lazy dog 🐶.';
+#### _Decrypting Data_ 🔓
 
-async function webApiExample() {
-  console.log(`New UUID: ${generateUuid()}`);
+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.
 
-  console.log(`SHA-256 Hash (ABCDEFG): ${await hash('ABCDEFG')}`);
+```typescript
+// Node.js example
+import { decrypt } from "cipher-kit/node";
+
+const decrypted = decrypt(encrypted, nodeSecretKey);
+console.log(`Decrypted: ${decrypted}`);
 
-  const secretKey = await createSecretKey('my secure passphrase');
+// Web example
+import { decrypt } from "cipher-kit/web-api";
 
-  const encrypted = await encrypt(str, secretKey);
-  console.log(`Encrypted Data: ${encrypted}`);
-  console.log(`Decrypted Data: ${await decrypt(encrypted, secretKey)}`);
+const decrypted = await decrypt(encrypted, webSecretKey);
+console.log(`Decrypted: ${decrypted}`);
+```
 
-  const encryptedObj = await encryptObj({ message: 'Hello, World! 🌍', count: 42 }, secretKey);
-  console.log(`Encrypted Object: ${encryptedObj}`);
-  console.log(`Decrypted Object: ${JSON.stringify(await decryptObj(encryptedObj, secretKey))}`);
+The function accepts an optional `options` parameter to specify the input encoding.
 
-  const { result: tryEncrypted, error: tryEncryptError } = await tryEncrypt(str, secretKey);
-  if (tryEncryptError) {
-    console.error(`Encryption Try failed: ${tryEncryptError.message} - ${tryEncryptError.description}`);
-    return;
-  }
-  console.log(`Encrypted Try Data: ${tryEncrypted}`);
+Make sure to use the same encoding that was used during encryption.
 
-  const decryptedTry = await tryDecrypt(tryEncrypted, secretKey);
-  if (decryptedTry.success === false) {
-    console.error(`Decryption Try failed: ${decryptedTry.error.message} - ${decryptedTry.error.description}`);
-    return;
-  }
-  console.log(`Try Decrypted Data: ${decryptedTry.result}`);
+```typescript
+interface DecryptOptions {
+  // Input ciphertext encoding (default: "base64url")
+  encoding?: "base64url" | "base64" | "hex";
 }
+```
+
+#### _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";
 
-webApiExample();
+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
+// Node.js example
+import { hash } from "cipher-kit/node";
+
+const hashed = hash("Hello, World!");
+console.log(`Hashed: ${hashed}`);
+
+// Web example
+import { hash } from "cipher-kit/web-api";
+
+const hashed = await hash("Hello, World!");
+console.log(`Hashed: ${hashed}`);
+```
+
+The function accepts an optional `options` parameter to customize the hashing process.
+
+```typescript
+interface HashOptions {
+  // Digest algorithm to use (default: "sha256").
+  digest?: "sha256" | "sha384" | "sha512";
+
+  // Output encoding (default: "base64url").
+  encoding?: "base64url" | "base64" | "hex";
+}
+```
+
+### 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
+// Node.js example
+import { generateUuid } from "cipher-kit/node";
+
+const uuid = generateUuid();
+console.log(`Generated UUID: ${uuid}`);
+
+// Web example
+import { generateUuid } from "cipher-kit/web-api";
+
+const uuid = generateUuid();
+console.log(`Generated UUID: ${uuid}`);
+```
+
+### 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 constant-time comparison to prevent timing attacks.
+
+```typescript
+// Node.js example
+import { hashPassword, verifyPassword } from "cipher-kit/node";
+
+const { hash, salt } = hashPassword("some-secure-password");
+console.log(`Hashed Password: ${hash}`);
+
+const isMatch = verifyPassword("some-secure-password", hash, salt);
+console.log(`Password match: ${isMatch}`);
+
+// Web example
+import { hashPassword, verifyPassword } from "cipher-kit/web-api";
+
+const { hash, salt } = await hashPassword("some-secure-password");
+console.log(`Hashed Password: ${hash}`);
+
+const isMatch = await verifyPassword("some-secure-password", hash, salt);
+console.log(`Password match: ${isMatch}`);
+```
+
+The `hashPassword` and `verifyPassword` functions accept an optional `options` parameter to customize the hashing process.
+
+```typescript
+interface HashPasswordOptions {
+  // Digest algorithm to use (default: "sha512").
+  digest?: "sha256" | "sha384" | "sha512";
+
+  // Encoding format for the output hash (default: "base64url").
+  encoding?: "base64url" | "base64" | "hex";
+
+  // Length of the salt in bytes (default: 16 bytes, min: 8 bytes).
+  saltLength?: number;
+
+  // Number of iterations for key derivation (default: 320000, min: 1000).
+  iterations?: number;
+
+  // Length of the derived key in bytes (default: 64 bytes, min: 16 bytes).
+  keyLength?: number;
+}
+
+interface VerifyPasswordOptions {
+  // Digest algorithm used during the original hashing (default: `'sha512'`).
+  digest?: "sha256" | "sha384" | "sha512";
+
+  // Encoding format used during the original hashing (default: `'base64url'`).
+  encoding?: "base64url" | "base64" | "hex";
+
+  // Number of iterations used during the original hashing (default: `320000`).
+  iterations?: number;
+
+  // Length of the key used during the original hashing (default: `64`).
+  keyLength?: number;
+}
+```
+
+### 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, matchPattern } from "cipher-kit"; // works in both "cipher-kit/web-api" and "cipher-kit/node"
+
+function isEncryptedFormat(message: string): boolean {
+  return matchPattern(message, "general"); // or "node" or "web"
+}
+
+// or
+
+function isEncryptedFormat(message: string): boolean {
+  return ENCRYPTED_REGEX.general.test(message); // or "node" or "web"
+}
 ```
 
 ## Contributions 🤝
@@ -170,4 +429,8 @@ Want to contribute or suggest a feature?
 
 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>
+<div style="font-size: 12px; font-style: italic;">Thank you!</div>
+</div>

package/dist/{chunk-UIV6DG54.cjs → chunk-3UX5MZ2P.cjs}

@@ -154,5 +154,5 @@ exports.stringifyObj = stringifyObj;
 exports.title = title;
 exports.tryParseToObj = tryParseToObj;
 exports.tryStringifyObj = tryStringifyObj;
-//# sourceMappingURL=chunk-UIV6DG54.cjs.map
-//# sourceMappingURL=chunk-UIV6DG54.cjs.map
+//# sourceMappingURL=chunk-3UX5MZ2P.cjs.map
+//# sourceMappingURL=chunk-3UX5MZ2P.cjs.map

package/dist/chunk-3UX5MZ2P.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-3UX5MZ2P.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 $isObj(x: unknown): x is Record<string, unknown> {\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 $isLooseObj(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 (!$isLooseObj(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    !$isLooseObj(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    !$isLooseObj(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 * matchPattern(\"abc.def.ghi.\", \"node\");    // true\r\n * matchPattern(\"abc.def.\", \"web\");         // true\r\n * matchPattern(\"abc.def.\", \"node\");        // false\r\n * matchPattern(\"abc.def.ghi.\", \"general\"); // true\r\n * ```\r\n */\r\nexport function matchPattern(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 { $isObj } 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 ($isObj(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 { $isObj, $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 (!$isObj(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\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 res = tryStringifyObj({ a: 1 });\r\n * if (res.success) {\r\n *   console.log(res.result); // {\"a\":1}\r\n * } else {\r\n *   console.error(res.error.message, res.error.description);\r\n * }\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 * try {\r\n * const json = stringifyObj({ a: 1 }); // {\"a\":1}\r\n * } catch (error: unknown) {\r\n *   console.error(error);\r\n * }\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\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 (!$isObj(obj)) 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 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 res = tryParseToObj<{ a: number }>('{\"a\":1}');\r\n * if (res.success) {\r\n *   console.log(res.result.a); // 1\r\n * } else {\r\n *   console.error(res.error.message, res.error.description);\r\n * }\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 * try {\r\n *   const obj = parseToObj<{ a: number }>('{\"a\":1}'); // obj.a === 1\r\n * } catch (error: unknown) {\r\n *   console.error(error);\r\n * }\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"]}

package/dist/{chunk-LHB5NXYW.js → chunk-4MFF6V3R.js}

@@ -1,4 +1,4 @@
-import { __export, $isSecretKey, $fmtResultErr, $ok, $err, $fmtError, title, $isStr, ENCRYPTION_ALGORITHMS, DIGEST_ALGORITHMS, CIPHER_ENCODING, matchPattern, $stringifyObj, $parseToObj, ENCODING } from './chunk-YMNOTRET.js';
+import { __export, $isSecretKey, $fmtResultErr, $ok, $err, $fmtError, title, $isStr, ENCRYPTION_ALGORITHMS, DIGEST_ALGORITHMS, CIPHER_ENCODING, matchPattern, $stringifyObj, $parseToObj, ENCODING } from './chunk-FKSYSPJR.js';
 
 // src/web/kit.ts
 var kit_exports = {};
@@ -563,5 +563,5 @@ function convertEncoding(data, from, to) {
 }
 
 export { convertBytesToStr, convertEncoding, convertStrToBytes, createSecretKey, decrypt, decryptObj, encrypt, encryptObj, generateUuid, hash, hashPassword, isWebSecretKey, kit_exports, tryConvertBytesToStr, tryConvertEncoding, tryConvertStrToBytes, tryCreateSecretKey, tryDecrypt, tryDecryptObj, tryEncrypt, tryEncryptObj, tryGenerateUuid, tryHash, tryHashPassword, verifyPassword };
-//# sourceMappingURL=chunk-LHB5NXYW.js.map
-//# sourceMappingURL=chunk-LHB5NXYW.js.map
+//# sourceMappingURL=chunk-4MFF6V3R.js.map
+//# sourceMappingURL=chunk-4MFF6V3R.js.map