secure-hash-vault 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pradeep Kumar Sheoran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,270 @@
+# CipherForge
+
+**CipherForge** is a simple, fast, and safe TypeScript crypto toolkit for password hashing, password verification, and authenticated data encryption using Node.js `node:crypto`.
+
+Created by **Pradeep Kumar Sheoran (Developer)** at **BSG Technologies**. Contact: **+91-8595147850** (also WhatsApp).
+
+Donation support: UPI on mobile number **+91-8595147850**.
+
+Hashtags: `#CipherForge` `#NodeCrypto` `#TypeScript` `#PasswordHashing` `#AES256GCM` `#Scrypt` `#BSGTechnologies`
+
+## Installation
+
+```bash
+npm install secure-hash-vault
+```
+
+## Features
+
+- One-way password hashing with async Node.js `crypto.scrypt`.
+- Password verification with timing-safe comparison.
+- Random salt generation and optional secret pepper support.
+- Metadata-safe password hash format.
+- Hash upgrade detection with `needsRehash()`.
+- AES-256-GCM authenticated encryption for text, JSON, buffers, and files.
+- JSON-safe encrypted payload object and compact string format.
+- Base64URL and hex helpers.
+- Developer-friendly custom errors.
+- TypeScript-first API with ESM and CJS builds.
+- No third-party crypto dependency and no custom cryptographic algorithm.
+
+## Important Security Rule
+
+Passwords are **not decrypted**. A password should be stored as a one-way hash, then checked during login with `verifyPassword()`. Reversible encryption/decryption is only for general data such as tokens, secrets, files, JSON payloads, and private text.
+
+## Password Hashing
+
+```ts
+import { hashPassword, verifyPassword } from "secure-hash-vault";
+
+const result = await hashPassword("MyStrongPassword@123", {
+  pepper: process.env.CIPHER_FORGE_PEPPER
+});
+
+// Store only result.hash in your database.
+console.log(result.hash);
+
+const verified = await verifyPassword("MyStrongPassword@123", result.hash, {
+  pepper: process.env.CIPHER_FORGE_PEPPER
+});
+
+if (verified.valid) {
+  console.log("Login success");
+}
+```
+
+Password hash format:
+
+```text
+$cv$v1$scrypt$N=16384,r=8,p=1,keyLen=64$saltBase64Url$hashBase64Url
+```
+
+Example response:
+
+```json
+{
+  "algorithm": "scrypt",
+  "version": "v1",
+  "hash": "$cv$v1$scrypt$N=16384,r=8,p=1,keyLen=64$abcSalt$xyzHash",
+  "salt": "abcSalt",
+  "params": {
+    "N": 16384,
+    "r": 8,
+    "p": 1,
+    "keyLen": 64
+  },
+  "createdAt": "2026-07-02T10:00:00.000Z"
+}
+```
+
+## Salt And Pepper
+
+A salt is random public data generated per password hash. It prevents two equal passwords from producing the same stored hash.
+
+A pepper is a secret value added during hashing and verification. Keep it in an environment variable or a secret manager. Never store the pepper in the database.
+
+```ts
+import { generatePepper, generateSalt } from "secure-hash-vault";
+
+console.log(generateSalt());
+console.log(generatePepper());
+```
+
+## Hash Upgrade Detection
+
+```ts
+import { needsRehash } from "secure-hash-vault";
+
+const shouldUpgrade = needsRehash(storedHash, {
+  params: { N: 32768, r: 8, p: 1, keyLen: 64 }
+});
+```
+
+## Data Encryption
+
+CipherForge uses AES-256-GCM for reversible encryption. AES-GCM provides confidentiality and integrity verification.
+
+```ts
+import { decryptText, encryptText } from "secure-hash-vault";
+
+const encrypted = await encryptText("secret data", "master-secret");
+const decrypted = await decryptText(encrypted, "master-secret");
+```
+
+Encrypted payload format:
+
+```json
+{
+  "format": "cv.enc.v1",
+  "algorithm": "aes-256-gcm",
+  "kdf": "scrypt",
+  "params": {
+    "N": 16384,
+    "r": 8,
+    "p": 1,
+    "keyLen": 32
+  },
+  "iv": "base64url-iv",
+  "salt": "base64url-salt",
+  "tag": "base64url-auth-tag",
+  "cipherText": "base64url-ciphertext",
+  "metadata": {
+    "createdAt": "2026-07-02T10:00:00.000Z"
+  }
+}
+```
+
+Compact format:
+
+```text
+$cvenc$v1$aes-256-gcm$scrypt$params$salt$iv$tag$cipherText
+```
+
+## JSON Encryption
+
+```ts
+import { decryptJson, encryptJson } from "secure-hash-vault";
+
+const encrypted = await encryptJson({ userId: 1, role: "admin" }, "master-secret");
+const decrypted = await decryptJson<{ userId: number; role: string }>(encrypted, "master-secret");
+```
+
+## Buffer Encryption
+
+```ts
+import { decryptBuffer, encryptBuffer } from "secure-hash-vault";
+
+const encrypted = await encryptBuffer(Buffer.from("binary secret"), "master-secret");
+const decrypted = await decryptBuffer(encrypted, "master-secret");
+```
+
+## File Encryption
+
+```ts
+import { decryptFile, encryptFile } from "secure-hash-vault";
+
+await encryptFile("private.txt", "private.txt.cv", "master-secret");
+await decryptFile("private.txt.cv", "private.decrypted.txt", "master-secret");
+```
+
+## Client API
+
+```ts
+import { createCipherForge } from "secure-hash-vault";
+
+const vault = createCipherForge({
+  password: {
+    algorithm: "scrypt",
+    params: {
+      N: 16384,
+      r: 8,
+      p: 1,
+      keyLen: 64
+    }
+  },
+  encryption: {
+    algorithm: "aes-256-gcm"
+  }
+});
+
+const passwordHash = await vault.password.hash("MyPassword@123");
+const isValid = await vault.password.verify("MyPassword@123", passwordHash.hash);
+
+const encrypted = await vault.crypto.encryptText("secret data", "master-key");
+const decrypted = await vault.crypto.decryptText(encrypted, "master-key");
+```
+
+## Universal Converter
+
+```ts
+import { CipherForge } from "secure-hash-vault";
+
+const encryptedText = await CipherForge.encrypt("hello", "master-secret");
+const decryptedText = await CipherForge.decrypt(encryptedText, "master-secret");
+
+const encryptedJson = await CipherForge.encrypt({ userId: 1, role: "admin" }, "master-secret");
+const decryptedJson = await CipherForge.decrypt(encryptedJson, "master-secret", { as: "json" });
+```
+
+## Error Classes
+
+```ts
+import {
+  DecryptionError,
+  EncryptionError,
+  InvalidConfigError,
+  InvalidPasswordHashError,
+  InvalidPayloadError,
+  PasswordVerificationError,
+  SecureHashVaultError
+} from "secure-hash-vault";
+```
+
+## Common Mistakes
+
+- Do not decrypt passwords. Use `verifyPassword()`.
+- Do not store plain passwords.
+- Do not use SHA-256 alone for password storage.
+- Do not reuse IVs for encryption. CipherForge generates a random IV every time.
+- Do not store pepper beside password hashes.
+- Do not invent a custom cryptographic algorithm.
+- Do not ignore AES-GCM authentication failures.
+
+## Production Checklist
+
+- Store only password hashes in the database.
+- Use HTTPS.
+- Keep pepper in environment variables or a secret manager.
+- Never store pepper in the database.
+- Rotate encryption secrets carefully.
+- Back up encryption keys safely.
+- Use timing-safe comparison.
+- Use random salt and IV.
+- Audit code before production use.
+- Keep Node.js updated.
+
+## Implementation Guide
+
+CipherForge is a wrapper around trusted Node.js primitives:
+
+- Password hashing: `crypto.scrypt`.
+- Random bytes: `crypto.randomBytes`.
+- Authenticated encryption: `crypto.createCipheriv("aes-256-gcm")`.
+- Authenticated decryption: `crypto.createDecipheriv("aes-256-gcm")`.
+- Constant-time checks: `crypto.timingSafeEqual`.
+
+Build commands:
+
+```bash
+npm run typecheck
+npm run test
+npm run build
+npm run pack:dry
+```
+
+## Package Author
+
+- Developer: **Pradeep Kumar Sheoran**
+- Company: **BSG Technologies**
+- Contact: **+91-8595147850** (also WhatsApp)
+- Donation: UPI on mobile number **+91-8595147850**