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

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

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:

$cv$v1$scrypt$N=16384,r=8,p=1,keyLen=64$saltBase64Url$hashBase64Url

Example response:

{
  "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.

import { generatePepper, generateSalt } from "secure-hash-vault";

console.log(generateSalt());
console.log(generatePepper());

Hash Upgrade Detection

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.

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:

{
  "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:

$cvenc$v1$aes-256-gcm$scrypt$params$salt$iv$tag$cipherText

JSON Encryption

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

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

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

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

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

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:

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