@naman_deep_singh/security 1.2.0 → 1.3.0

package/README.md

@@ -1,109 +1,222 @@
 # @naman_deep_singh/security
 
-**Version:** 1.2.0
+**Version:** 1.3.0
 
 A complete, lightweight security toolkit for Node.js & TypeScript providing:
 
-🔐 **Password hashing & validation** with bcrypt
-🔑 **JWT signing & verification** (no deprecated expiresIn)
+🔐 **Password hashing & validation** with bcrypt (async/sync, peppered variants)
+🔑 **JWT signing & verification** (no deprecated expiresIn, with caching)
 🧮 **Duration parser** ("15m", "7d", etc.)
-🪪 **Token generator** (access + refresh pair)
+🪪 **Token generator** (access + refresh pair with branded types)
 ♻️ **Refresh token rotation** helper
 🧰 **Robust token extraction** (Headers, Cookies, Query, Body, WebSocket)
 🧩 **Safe & strict JWT decode** utilities
+🔒 **AES-256-GCM encryption/decryption** with HMAC and random utilities
 🚨 **Standardized error handling** with @naman_deep_singh/errors-utils
 
 ✔ **Fully typed** with TypeScript
 ✔ **Branded token types** for compile-time safety (AccessToken/RefreshToken)
-✔ **Structured verification results** for better error handling
-✔ **Enhanced verification options** with flexible configuration
+✔ **Class-based managers** for advanced features (PasswordManager, JWTManager, CryptoManager)
+✔ **Functional exports** for simple use cases
+✔ **Password strength checking** and validation
+✔ **Token caching** for performance
 ✔ **Consistent errors** across your application ecosystem
 ✔ **Works in both ESM and CommonJS**
 
 ```bash
-
 📦 Installation
 npm install @naman_deep_singh/security
+```
 
 🔧 Features
 
 🔥 Password Hashing — secure & async (bcrypt with 10 salt rounds)
+🔥 Password Validation & Strength Checking
+🔥 Password Generation with configurable requirements
+🔥 Peppered hashing variants
+🔥 Synchronous & asynchronous versions
 
 🔥 Custom Expiry JWT — manual exp support using duration strings
-
 🔥 Token Pair Generation (accessToken + refreshToken)
-
 🔥 Refresh Token Rotation
-
 🔥 Safe & Unsafe JWT Verification
-
 🔥 Strict vs Flexible Decoding
-
 🔥 Universal Token Extraction (Headers, Cookies, Query, Body, WebSocket)
+🔥 Token caching for performance
 
-🔥 Duration Parser ("15m", "1h", "7d")
+🔥 AES-256-GCM Encryption/Decryption
+🔥 HMAC signing and verification
+🔥 Cryptographically secure random generation
 
-🔥 Production-grade types
+🔥 Production-grade types and error handling
 
 📘 Quick Start
+
+### Functional Approach (Simple)
+```typescript
 import {
   hashPassword,
   verifyPassword,
   generateTokens,
   verifyToken,
   safeVerifyToken,
-  extractToken
+  extractToken,
+  encrypt,
+  decrypt
 } from "@naman_deep_singh/security";
 
+// Password operations
+const hashed = await hashPassword("mypassword");
+const isValid = await verifyPassword("mypassword", hashed);
+
+// JWT operations
+const tokens = generateTokens(
+  { userId: 42 },
+  process.env.ACCESS_SECRET!,
+  process.env.REFRESH_SECRET!,
+  "15m",
+  "7d"
+);
+
+const result = safeVerifyToken(tokens.accessToken, process.env.ACCESS_SECRET!);
+
+// Crypto operations
+const encrypted = encrypt("sensitive data", "secret-key");
+const decrypted = decrypt(encrypted, "secret-key");
+```
+
+### Class-Based Approach (Advanced)
+```typescript
+import { PasswordManager, JWTManager, CryptoManager } from "@naman_deep_singh/security";
+
+// Password Manager with validation
+const passwordManager = new PasswordManager({
+  minLength: 12,
+  requireUppercase: true,
+  requireNumbers: true,
+  requireSpecialChars: true
+});
+
+const validation = passwordManager.validate("MySecurePass123!");
+if (validation.isValid) {
+  const hashed = await passwordManager.hash("MySecurePass123!");
+}
+
+// JWT Manager with caching
+const jwtManager = new JWTManager({
+  accessSecret: process.env.ACCESS_SECRET!,
+  refreshSecret: process.env.REFRESH_SECRET!,
+  accessExpiry: "15m",
+  refreshExpiry: "7d",
+  enableCaching: true
+});
+
+const tokens = await jwtManager.generateTokens({ userId: 42 });
+const payload = await jwtManager.verifyAccessToken(tokens.accessToken);
+
+// Crypto Manager
+const cryptoManager = new CryptoManager("your-secret-key");
+const encrypted = cryptoManager.encrypt("data");
+const decrypted = cryptoManager.decrypt(encrypted);
+```
+
 📚 API Documentation
 
 Below is a complete reference with full usage examples.
 
-🧂 1. Password Utilities
-hashPassword(password: string): Promise<string>
-const hashed = await hashPassword("mypassword");
-console.log(hashed); // $2a$10$...
+## 🧂 1. Password Utilities
 
+### Functional Exports
+```typescript
+// Async hashing
+const hashed = await hashPassword("mypassword"); // Uses 10 salt rounds by default
+const hashed = await hashPassword("mypassword", 12); // Custom salt rounds
 
-verifyPassword(password: string, hash: string): Promise<boolean>
-const isValid = await verifyPassword("mypassword", hashed);
-if (isValid) console.log("Correct password");
+// Sync hashing
+const hashedSync = hashPasswordSync("mypassword");
+const hashedSync = hashPasswordSync("mypassword", 12);
+
+// Peppered variants
+const hashedPeppered = await hashPasswordWithPepper("mypassword", "pepper");
+const hashedPepperedSync = hashPasswordWithPepperSync("mypassword", "pepper");
 
-// Synchronous version also available
+// Verification
+const isValid = await verifyPassword("mypassword", hashed);
 const isValidSync = verifyPasswordSync("mypassword", hashed);
 
-🔑 2. JWT Signing
-signToken(payload, secret, expiresIn, options)
+// Peppered verification
+const isValidPeppered = await verifyPasswordWithPepper("mypassword", "pepper", hashed);
+const isValidPepperedSync = verifyPasswordWithPepperSync("mypassword", "pepper", hashed);
+```
 
-Creates a JWT with custom exp logic ("15m", "1h", "7d")
+### PasswordManager Class
+```typescript
+const passwordManager = new PasswordManager({
+  saltRounds: 12,
+  minLength: 8,
+  maxLength: 128,
+  requireUppercase: true,
+  requireLowercase: true,
+  requireNumbers: true,
+  requireSpecialChars: false,
+  customRules: [
+    { test: (pwd) => !pwd.includes('password'), message: 'Cannot contain "password"' }
+  ]
+});
 
-const token = signToken(
-  { userId: 1 },
-  process.env.JWT_SECRET!,
-  "1h"
-);
+// Hash with validation
+const result = await passwordManager.hash("MySecurePass123!");
+// Returns: { hash: "$2a$...", salt: "..." }
 
-console.log(token);
+// Verify
+const isValid = await passwordManager.verify("MySecurePass123!", result.hash, result.salt);
 
+// Validate password
+const validation = passwordManager.validate("MySecurePass123!");
+/*
+Returns: {
+  isValid: true,
+  errors: [],
+  strength: { score: 4, label: 'strong', feedback: [...], suggestions: [...] }
+}
+*/
 
-✔ No deprecated expiresIn from jsonwebtoken
-✔ Expiration is injected manually via exp
+// Generate secure password
+const generatedPassword = passwordManager.generate(16, {
+  requireUppercase: true,
+  requireNumbers: true,
+  requireSpecialChars: true
+});
 
-🧮 3. parseDuration()
+// Check strength
+const strength = passwordManager.checkStrength("MySecurePass123!");
+/*
+Returns: {
+  score: 4,
+  label: 'strong',
+  feedback: [],
+  suggestions: ["Your password is very secure"]
+}
+*/
+```
 
-Parses duration strings into seconds.
+## 🔑 2. JWT Utilities
+
+### Functional Exports
+```typescript
+// Sign token with duration string
+const token = signToken(
+  { userId: 1, role: "admin" },
+  process.env.JWT_SECRET!,
+  "1h" // Duration string: "15m", "2h", "7d", "30s"
+);
 
+// Parse duration to seconds
 parseDuration("15m"); // 900
 parseDuration("2h");  // 7200
 parseDuration("7d");  // 604800
 
-
-Useful for token expiry, cache expiry, rate limiting, etc.
-
-🪪 4. generateTokens()
-
-Generates access + refresh token pair.
-
+// Generate token pair
 const tokens = generateTokens(
   { userId: 42 },
   process.env.ACCESS_SECRET!,
@@ -111,169 +224,130 @@ const tokens = generateTokens(
   "15m",
   "7d"
 );
+// Returns: { accessToken: AccessToken, refreshToken: RefreshToken }
 
-console.log(tokens.accessToken);
-console.log(tokens.refreshToken);
-
-♻️ 5. rotateRefreshToken()
-
-Creates a new refresh token using the old one:
-
-import { rotateRefreshToken } from "@naman_deep_singh/security";
-
+// Rotate refresh token
 const newRefreshToken = rotateRefreshToken(
   oldRefreshToken,
   process.env.REFRESH_SECRET!
 );
 
+// Verify token (throws on error)
+const payload = verifyToken(token, process.env.ACCESS_SECRET!);
 
-✔ Automatically removes old exp and iat
-✔ Generates fresh expiration
-
-🔍 6. verifyToken()
-
-Throws if token is invalid or expired.
-
-try {
-  const payload = verifyToken(token, process.env.ACCESS_SECRET!);
-  console.log("User authenticated:", payload);
-} catch (err) {
-  console.error("Invalid or expired token");
-}
-
-🛡 7. safeVerifyToken()
-
-Never throws — returns { valid, payload?, error? }
-
+// Safe verify (never throws)
 const result = safeVerifyToken(token, process.env.ACCESS_SECRET!);
-
-if (!result.valid) {
-  console.log("Token invalid:", result.error);
-} else {
-  console.log("Token OK:", result.payload);
+/*
+Returns: {
+  valid: true,
+  payload: { userId: 1, ... },
+  error?: undefined
 }
+*/
+
+// Decode without verification
+const decoded = decodeToken(token); // Flexible: null | string | JwtPayload
+const payload = decodeTokenStrict(token); // Throws if not object
+
+// Extract token from various sources
+const token = extractToken({
+  header: req.headers.authorization, // "Bearer <token>"
+  cookies: req.cookies, // { token: "...", accessToken: "..." }
+  query: req.query, // { token: "..." }
+  body: req.body, // { token: "..." }
+  wsMessage: message // string or { token: "..." }
+});
+```
 
-🧬 8. Decoding Helpers
-decodeToken(token)
-
-Flexible — returns null | string | JwtPayload
-
-const decoded = decodeToken(token);
-console.log(decoded);
-
-decodeTokenStrict(token)
-
-Throws if payload is not an object.
-
-try {
-  const payload = decodeTokenStrict(token);
-  console.log(payload.userId);
-} catch (e) {
-  console.error("Invalid token payload");
-}
-
-🛰 9. extractToken()
-
-Extracts tokens from:
-
-Headers (Authorization: Bearer <token>)
-
-Cookies (token, accessToken)
-
-Query (?token=...)
-
-Body ({ token: "" })
+### JWTManager Class
+```typescript
+const jwtManager = new JWTManager({
+  accessSecret: process.env.ACCESS_SECRET!,
+  refreshSecret: process.env.REFRESH_SECRET!,
+  accessExpiry: "15m",
+  refreshExpiry: "7d",
+  enableCaching: true, // Optional caching
+  maxCacheSize: 100 // Default 100
+});
 
-WebSocket messages (string or object)
+// Generate tokens
+const tokens = await jwtManager.generateTokens({ userId: 42 });
 
-Example: Express middleware
-export function authMiddleware(req, res, next) {
-  const token = extractToken({
-    header: req.headers.authorization,
-    cookies: req.cookies,
-    query: req.query,
-    body: req.body
-  });
+// Verify tokens
+const accessPayload = await jwtManager.verifyAccessToken(tokens.accessToken);
+const refreshPayload = await jwtManager.verifyRefreshToken(tokens.refreshToken);
 
-  if (!token) return res.status(401).json({ error: "Token missing" });
+// Rotate refresh token
+const newRefreshToken = await jwtManager.rotateRefreshToken(oldRefreshToken);
 
-  try {
-    req.user = verifyToken(token, process.env.ACCESS_SECRET!);
-    next();
-  } catch (err) {
-    return res.status(401).json({ error: "Invalid token" });
-  }
-}
+// Decode token
+const decoded = jwtManager.decodeToken(token);
 
-Example: WebSocket (ws library)
-ws.on("message", (msg) => {
-  const token = extractToken({ wsMessage: msg });
+// Extract from header
+const token = jwtManager.extractTokenFromHeader("Bearer eyJ...");
 
-  if (!token) return;
+// Validate without throwing
+const isValid = jwtManager.validateToken(token, secret);
 
-  const result = safeVerifyToken(token, process.env.ACCESS_SECRET!);
+// Check expiration
+const isExpired = jwtManager.isTokenExpired(token);
+const expiresAt = jwtManager.getTokenExpiration(token);
 
-  if (result.valid) {
-    console.log("WS authenticated user:", result.payload);
-  }
-});
+// Cache management
+jwtManager.clearCache();
+const stats = jwtManager.getCacheStats(); // { size: 5, maxSize: 100 }
+```
 
-🧩 10. Full Authentication Example
-Registration
-async function registerUser(email: string, password: string) {
-  const hash = await hashPassword(password);
+## 🔒 3. Crypto Utilities
 
-  return {
-    email,
-    passwordHash: hash
-  };
-}
+### Functional Exports
+```typescript
+// AES-256-GCM Encryption
+const encrypted = encrypt("sensitive data", "your-secret-key");
+// Returns: "iv:encrypted_data"
 
-Login
-async function loginUser(email, password, storedHash) {
-  const valid = await verifyPassword(password, storedHash);
+const decrypted = decrypt(encrypted, "your-secret-key");
+// Returns: "sensitive data"
 
-  if (!valid) throw new Error("Invalid credentials");
+// HMAC
+const hmac = createHMAC("data", "secret-key");
+const isValidHMAC = verifyHMAC("data", hmac, "secret-key");
 
-  return generateTokens(
-    { email },
-    process.env.ACCESS_SECRET!,
-    process.env.REFRESH_SECRET!,
-    "15m",
-    "7d"
-  );
-}
+// Random generation
+const randomBytes = generateRandomBytes(32); // Buffer
+const randomString = generateRandomString(16); // Base64 string
+const randomHex = generateRandomHex(32); // Hex string
+```
 
-Token Refresh
-function refresh(oldRefreshToken) {
-  const newRefreshToken = rotateRefreshToken(
-    oldRefreshToken,
-    process.env.REFRESH_SECRET!
-  );
+### CryptoManager Class
+```typescript
+const cryptoManager = new CryptoManager("your-secret-key");
 
-  const decoded = decodeTokenStrict(oldRefreshToken);
+// Encryption
+const encrypted = cryptoManager.encrypt("data");
+const decrypted = cryptoManager.decrypt(encrypted);
 
-  const newAccessToken = signToken(
-    { userId: decoded.userId },
-    process.env.ACCESS_SECRET!,
-    "15m"
-  );
+// HMAC
+const hmac = cryptoManager.createHMAC("data");
+const isValid = cryptoManager.verifyHMAC("data", hmac);
 
-  return { accessToken: newAccessToken, refreshToken: newRefreshToken };
-}
+// Random
+const randomBytes = cryptoManager.generateRandomBytes(32);
+const randomString = cryptoManager.generateRandomString(16);
+```
 
-🚨 Error Handling
+## 🚨 Error Handling
 
 This package uses standardized errors from `@naman_deep_singh/errors-utils`:
 
 ```typescript
-import { 
-  hashPassword, 
+import {
+  hashPassword,
   verifyPassword,
-  BadRequestError, 
+  BadRequestError,
   UnauthorizedError,
   ValidationError,
-  InternalServerError 
+  InternalServerError
 } from '@naman_deep_singh/security';
 
 try {
@@ -304,14 +378,118 @@ try {
 - `ValidationError` (422) - Password strength validation
 - `InternalServerError` (500) - Server-side processing errors
 
+## 🧩 Complete Authentication Example
+
+### Registration with Validation
+```typescript
+import { PasswordManager, JWTManager } from '@naman_deep_singh/security';
+
+const passwordManager = new PasswordManager({
+  minLength: 12,
+  requireUppercase: true,
+  requireNumbers: true,
+  requireSpecialChars: true
+});
+
+const jwtManager = new JWTManager({
+  accessSecret: process.env.ACCESS_SECRET!,
+  refreshSecret: process.env.REFRESH_SECRET!,
+  accessExpiry: "15m",
+  refreshExpiry: "7d"
+});
+
+async function registerUser(email: string, password: string) {
+  // Validate password strength
+  const validation = passwordManager.validate(password);
+  if (!validation.isValid) {
+    throw new ValidationError(`Password validation failed: ${validation.errors.join(', ')}`);
+  }
+
+  // Hash password
+  const { hash, salt } = await passwordManager.hash(password);
+
+  // Store user with hash and salt
+  return {
+    email,
+    passwordHash: hash,
+    passwordSalt: salt
+  };
+}
+```
+
+### Login with Token Generation
+```typescript
+async function loginUser(email: string, password: string, storedHash: string, storedSalt: string) {
+  // Verify password
+  const isValid = await passwordManager.verify(password, storedHash, storedSalt);
+  if (!isValid) {
+    throw new UnauthorizedError("Invalid credentials");
+  }
+
+  // Generate tokens
+  return jwtManager.generateTokens({ email });
+}
+```
+
+### Token Refresh
+```typescript
+async function refreshTokens(oldRefreshToken: string) {
+  // Verify old refresh token
+  const decoded = await jwtManager.verifyRefreshToken(oldRefreshToken);
+
+  // Generate new token pair
+  const newTokens = await jwtManager.generateTokens(decoded);
+
+  // Rotate refresh token
+  const rotatedRefreshToken = await jwtManager.rotateRefreshToken(oldRefreshToken);
+
+  return {
+    accessToken: newTokens.accessToken,
+    refreshToken: rotatedRefreshToken
+  };
+}
+```
+
+### Express Middleware
+```typescript
+import { extractToken, safeVerifyToken } from '@naman_deep_singh/security';
+
+export function authMiddleware(req, res, next) {
+  const token = extractToken({
+    header: req.headers.authorization,
+    cookies: req.cookies,
+    query: req.query,
+    body: req.body
+  });
+
+  if (!token) {
+    return res.status(401).json({ error: "Token missing" });
+  }
+
+  const result = safeVerifyToken(token, process.env.ACCESS_SECRET!);
+
+  if (!result.valid) {
+    return res.status(401).json({ error: "Invalid token" });
+  }
+
+  req.user = result.payload;
+  next();
+}
+```
+
 🔐 Security Best Practices
 
-✔ Use 32+ character secrets
+✔ Use 32+ character secrets for JWT and encryption
 ✔ Store secrets in environment variables
 ✔ Always use HTTPS in production
 ✔ Keep refresh tokens secure (HttpOnly cookie recommended)
 ✔ Do not store passwords in plain text—ever
+✔ Use password peppering for additional security
+✔ Implement proper password strength requirements
+✔ Enable JWT caching for performance (but monitor memory usage)
 ✔ Handle errors appropriately with proper HTTP status codes
+✔ Regularly rotate secrets and tokens
+✔ Use secure random generation for all cryptographic operations
 
 🔗 Integration with Other Packages
 
@@ -319,19 +497,20 @@ try {
 
 ```typescript
 import { createServer } from '@naman_deep_singh/server-utils';
-import { hashPassword, verifyPassword } from '@naman_deep_singh/security';
+import { PasswordManager } from '@naman_deep_singh/security';
 
 const server = createServer('Auth API', '1.0.0');
+const passwordManager = new PasswordManager();
 
 server.app.post('/register', async (req, res) => {
   try {
     const { password } = req.body;
-    const hash = await hashPassword(password);
+    const hash = await passwordManager.hash(password);
     // Save user with hash...
     res.json({ success: true });
   } catch (error) {
     // Errors automatically handled by server-utils middleware
-    throw error; // Will be caught and formatted consistently
+    throw error;
   }
 });
 ```
@@ -348,4 +527,4 @@ server.app.use(expressErrorHandler); // Handles security errors consistently
 
 📜 License
 
-MIT — free to use & modify.
+MIT — free to use & modify.