@naman_deep_singh/security 1.0.4 → 1.2.0

package/README.md

@@ -1,116 +1,351 @@
 # @naman_deep_singh/security
 
-Security utilities for password hashing and JWT token management with TypeScript support.
+**Version:** 1.2.0
 
-## Installation
+A complete, lightweight security toolkit for Node.js & TypeScript providing:
+
+🔐 **Password hashing & validation** with bcrypt
+🔑 **JWT signing & verification** (no deprecated expiresIn)
+🧮 **Duration parser** ("15m", "7d", etc.)
+🪪 **Token generator** (access + refresh pair)
+♻️ **Refresh token rotation** helper
+🧰 **Robust token extraction** (Headers, Cookies, Query, Body, WebSocket)
+🧩 **Safe & strict JWT decode** 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
+✔ **Consistent errors** across your application ecosystem
+✔ **Works in both ESM and CommonJS**
 
 ```bash
+
+📦 Installation
 npm install @naman_deep_singh/security
-```
 
-## Features
+🔧 Features
 
-- ✅ **Password hashing** with bcrypt (salt rounds: 10)
-- ✅ **JWT token management** with configurable expiration
-- ✅ **TypeScript support** with full type safety
-- ✅ **Hybrid exports** - use named imports or namespace imports
-- ✅ **Backward compatibility** with legacy function names
-- ✅ **Async/await support** for all operations
+🔥 Password Hashing — secure & async (bcrypt with 10 salt rounds)
 
-## Usage
+🔥 Custom Expiry JWT — manual exp support using duration strings
 
-### Named Imports (Tree-shakable)
-```typescript
-import { hashPassword, verifyPassword, generateToken, verifyToken } from '@naman_deep_singh/security';
+🔥 Token Pair Generation (accessToken + refreshToken)
 
-// Password hashing
-const hashedPassword = await hashPassword('mypassword');
-const isValid = await verifyPassword('mypassword', hashedPassword);
+🔥 Refresh Token Rotation
 
-// JWT tokens
-const token = generateToken({ userId: 1, role: 'admin' }, 'your-secret-key', '24h');
-const decoded = verifyToken(token, 'your-secret-key');
-```
+🔥 Safe & Unsafe JWT Verification
 
-### Namespace Import
-```typescript
-import SecurityUtils from '@naman_deep_singh/security';
+🔥 Strict vs Flexible Decoding
 
-const hashedPassword = await SecurityUtils.hashPassword('mypassword');
-const token = SecurityUtils.generateToken({ userId: 1 }, 'secret');
-```
+🔥 Universal Token Extraction (Headers, Cookies, Query, Body, WebSocket)
 
-### Backward Compatibility
-```typescript
-import { comparePassword, signToken } from '@naman_deep_singh/security';
+🔥 Duration Parser ("15m", "1h", "7d")
 
-// Legacy function names still work
-const isValid = await comparePassword('password', 'hash');
-const token = signToken({ userId: 1 }, 'secret');
-```
+🔥 Production-grade types
 
-## API Reference
+📘 Quick Start
+import {
+  hashPassword,
+  verifyPassword,
+  generateTokens,
+  verifyToken,
+  safeVerifyToken,
+  extractToken
+} from "@naman_deep_singh/security";
 
-### Password Functions
-- `hashPassword(password: string): Promise<string>` - Hash a password using bcrypt with salt rounds 10
-- `verifyPassword(password: string, hash: string): Promise<boolean>` - Verify password against hash
-- `comparePassword(password: string, hash: string): Promise<boolean>` - Alias for verifyPassword (backward compatibility)
+📚 API Documentation
 
-### JWT Functions
-- `generateToken(payload: Record<string, unknown>, secret: Secret, expiresIn?: string): string` - Generate JWT token
-- `verifyToken(token: string, secret: Secret): string | JwtPayload` - Verify and decode JWT token
-- `signToken(payload: Record<string, unknown>, secret: Secret, expiresIn?: string): string` - Alias for generateToken (backward compatibility)
+Below is a complete reference with full usage examples.
 
-## Examples
+🧂 1. Password Utilities
+hashPassword(password: string): Promise<string>
+const hashed = await hashPassword("mypassword");
+console.log(hashed); // $2a$10$...
 
-### Complete Authentication Flow
-```typescript
-import { hashPassword, verifyPassword, generateToken, verifyToken } from '@naman_deep_singh/security';
 
-// Registration
-async function registerUser(email: string, password: string) {
-  const hashedPassword = await hashPassword(password);
-  // Save user with hashedPassword to database
-  return { email, password: hashedPassword };
+verifyPassword(password: string, hash: string): Promise<boolean>
+const isValid = await verifyPassword("mypassword", hashed);
+if (isValid) console.log("Correct password");
+
+// Synchronous version also available
+const isValidSync = verifyPasswordSync("mypassword", hashed);
+
+🔑 2. JWT Signing
+signToken(payload, secret, expiresIn, options)
+
+Creates a JWT with custom exp logic ("15m", "1h", "7d")
+
+const token = signToken(
+  { userId: 1 },
+  process.env.JWT_SECRET!,
+  "1h"
+);
+
+console.log(token);
+
+
+✔ No deprecated expiresIn from jsonwebtoken
+✔ Expiration is injected manually via exp
+
+🧮 3. parseDuration()
+
+Parses duration strings into 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.
+
+const tokens = generateTokens(
+  { userId: 42 },
+  process.env.ACCESS_SECRET!,
+  process.env.REFRESH_SECRET!,
+  "15m",
+  "7d"
+);
+
+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";
+
+const newRefreshToken = rotateRefreshToken(
+  oldRefreshToken,
+  process.env.REFRESH_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? }
+
+const result = safeVerifyToken(token, process.env.ACCESS_SECRET!);
+
+if (!result.valid) {
+  console.log("Token invalid:", result.error);
+} else {
+  console.log("Token OK:", result.payload);
+}
+
+🧬 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: "" })
+
+WebSocket messages (string or object)
+
+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
+  });
+
+  if (!token) return res.status(401).json({ error: "Token missing" });
+
+  try {
+    req.user = verifyToken(token, process.env.ACCESS_SECRET!);
+    next();
+  } catch (err) {
+    return res.status(401).json({ error: "Invalid token" });
+  }
 }
 
-// Login
-async function loginUser(email: string, password: string, storedHash: string) {
-  const isValid = await verifyPassword(password, storedHash);
-  
-  if (!isValid) {
-    throw new Error('Invalid credentials');
+Example: WebSocket (ws library)
+ws.on("message", (msg) => {
+  const token = extractToken({ wsMessage: msg });
+
+  if (!token) return;
+
+  const result = safeVerifyToken(token, process.env.ACCESS_SECRET!);
+
+  if (result.valid) {
+    console.log("WS authenticated user:", result.payload);
   }
-  
-  const token = generateToken(
-    { email, loginTime: Date.now() },
-    process.env.JWT_SECRET!,
-    '7d'
+});
+
+🧩 10. Full Authentication Example
+Registration
+async function registerUser(email: string, password: string) {
+  const hash = await hashPassword(password);
+
+  return {
+    email,
+    passwordHash: hash
+  };
+}
+
+Login
+async function loginUser(email, password, storedHash) {
+  const valid = await verifyPassword(password, storedHash);
+
+  if (!valid) throw new Error("Invalid credentials");
+
+  return generateTokens(
+    { email },
+    process.env.ACCESS_SECRET!,
+    process.env.REFRESH_SECRET!,
+    "15m",
+    "7d"
   );
-  
-  return { token };
 }
 
-// Verify JWT
-function authenticateRequest(token: string) {
+Token Refresh
+function refresh(oldRefreshToken) {
+  const newRefreshToken = rotateRefreshToken(
+    oldRefreshToken,
+    process.env.REFRESH_SECRET!
+  );
+
+  const decoded = decodeTokenStrict(oldRefreshToken);
+
+  const newAccessToken = signToken(
+    { userId: decoded.userId },
+    process.env.ACCESS_SECRET!,
+    "15m"
+  );
+
+  return { accessToken: newAccessToken, refreshToken: newRefreshToken };
+}
+
+🚨 Error Handling
+
+This package uses standardized errors from `@naman_deep_singh/errors-utils`:
+
+```typescript
+import { 
+  hashPassword, 
+  verifyPassword,
+  BadRequestError, 
+  UnauthorizedError,
+  ValidationError,
+  InternalServerError 
+} from '@naman_deep_singh/security';
+
+try {
+  const hash = await hashPassword('mypassword');
+} catch (error) {
+  if (error instanceof BadRequestError) {
+    // Invalid password input (400)
+    console.log('Invalid password provided');
+  } else if (error instanceof InternalServerError) {
+    // Hashing failed (500)
+    console.log('Server error during hashing');
+  }
+}
+
+try {
+  const isValid = await verifyPassword('password', hash);
+} catch (error) {
+  if (error instanceof UnauthorizedError) {
+    // Password verification failed (401)
+    console.log('Invalid credentials');
+  }
+}
+```
+
+**Error Types:**
+- `BadRequestError` (400) - Invalid input data
+- `UnauthorizedError` (401) - Authentication failures
+- `ValidationError` (422) - Password strength validation
+- `InternalServerError` (500) - Server-side processing errors
+
+🔐 Security Best Practices
+
+✔ Use 32+ character secrets
+✔ 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
+✔ Handle errors appropriately with proper HTTP status codes
+
+🔗 Integration with Other Packages
+
+### With @naman_deep_singh/server-utils
+
+```typescript
+import { createServer } from '@naman_deep_singh/server-utils';
+import { hashPassword, verifyPassword } from '@naman_deep_singh/security';
+
+const server = createServer('Auth API', '1.0.0');
+
+server.app.post('/register', async (req, res) => {
   try {
-    const decoded = verifyToken(token, process.env.JWT_SECRET!);
-    return decoded;
+    const { password } = req.body;
+    const hash = await hashPassword(password);
+    // Save user with hash...
+    res.json({ success: true });
   } catch (error) {
-    throw new Error('Invalid token');
+    // Errors automatically handled by server-utils middleware
+    throw error; // Will be caught and formatted consistently
   }
-}
+});
 ```
 
-## Dependencies
+### With @naman_deep_singh/errors-utils + @naman_deep_singh/response-utils
 
-- **bcryptjs** - For secure password hashing
-- **jsonwebtoken** - For JWT token management
+```typescript
+import { expressErrorHandler } from '@naman_deep_singh/errors-utils';
+import { responderMiddleware } from '@naman_deep_singh/response-utils';
+
+server.app.use(responderMiddleware());
+server.app.use(expressErrorHandler); // Handles security errors consistently
+```
 
-## Security Best Practices
+📜 License
 
-1. **Use strong secrets** for JWT signing (minimum 32 characters)
-2. **Set appropriate expiration times** for tokens
-3. **Store JWT secrets in environment variables**
-4. **Never log or expose hashed passwords**
-5. **Use HTTPS** in production for token transmission
+MIT — free to use & modify.

package/dist/cjs/core/crypto/decrypt.d.ts

@@ -0,0 +1 @@
+export declare const decrypt: (data: string, secret: string) => string;

package/dist/cjs/core/crypto/decrypt.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decrypt = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const ALGO = "AES-256-GCM";
+const decrypt = (data, secret) => {
+    const [ivHex, encryptedHex] = data.split(":");
+    const iv = Buffer.from(ivHex, "hex");
+    const encrypted = Buffer.from(encryptedHex, "hex");
+    const key = crypto_1.default.createHash("sha256").update(secret).digest();
+    const decipher = crypto_1.default.createDecipheriv(ALGO, key, iv);
+    const decrypted = Buffer.concat([
+        decipher.update(encrypted),
+        decipher.final(),
+    ]);
+    return decrypted.toString("utf8");
+};
+exports.decrypt = decrypt;

package/dist/cjs/core/crypto/encrypt.d.ts

@@ -0,0 +1 @@
+export declare const encrypt: (text: string, secret: string) => string;

package/dist/cjs/core/crypto/encrypt.js

@@ -0,0 +1,16 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encrypt = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const ALGO = "AES-256-GCM";
+const encrypt = (text, secret) => {
+    const key = crypto_1.default.createHash("sha256").update(secret).digest();
+    const iv = crypto_1.default.randomBytes(16);
+    const cipher = crypto_1.default.createCipheriv(ALGO, key, iv);
+    const encrypted = Buffer.concat([cipher.update(text, "utf8"), cipher.final()]);
+    return `${iv.toString("hex")}:${encrypted.toString("hex")}`;
+};
+exports.encrypt = encrypt;

package/dist/cjs/core/crypto/hmac.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Sign message using HMAC SHA-256
+ */
+export declare const hmacSign: (message: string, secret: string) => string;
+/**
+ * Verify HMAC signature
+ */
+export declare const hmacVerify: (message: string, secret: string, signature: string) => boolean;

package/dist/cjs/core/crypto/hmac.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hmacVerify = exports.hmacSign = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+/**
+ * Sign message using HMAC SHA-256
+ */
+const hmacSign = (message, secret) => {
+    return crypto_1.default.createHmac("sha256", secret).update(message).digest("hex");
+};
+exports.hmacSign = hmacSign;
+/**
+ * Verify HMAC signature
+ */
+const hmacVerify = (message, secret, signature) => {
+    const expected = (0, exports.hmacSign)(message, secret);
+    if (signature.length !== expected.length)
+        return false;
+    return crypto_1.default.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+};
+exports.hmacVerify = hmacVerify;

package/dist/cjs/core/crypto/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./decrypt";
+export * from "./encrypt";
+export * from "./hmac";
+export * from "./random";

package/dist/cjs/core/crypto/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./decrypt"), exports);
+__exportStar(require("./encrypt"), exports);
+__exportStar(require("./hmac"), exports);
+__exportStar(require("./random"), exports);

package/dist/cjs/core/crypto/random.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Generate cryptographically secure random string
+ */
+export declare const randomToken: (length?: number) => string;
+/**
+ * Generate a strong random password
+ */
+export declare const generateStrongPassword: (length?: number) => string;

package/dist/cjs/core/crypto/random.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateStrongPassword = exports.randomToken = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+/**
+ * Generate cryptographically secure random string
+ */
+const randomToken = (length = 32) => {
+    return crypto_1.default.randomBytes(length).toString("hex");
+};
+exports.randomToken = randomToken;
+/**
+ * Generate a strong random password
+ */
+const generateStrongPassword = (length = 16) => {
+    return crypto_1.default.randomBytes(length).toString("hex").slice(0, length);
+};
+exports.generateStrongPassword = generateStrongPassword;

package/dist/cjs/core/jwt/decode.d.ts

@@ -0,0 +1,12 @@
+import { JwtPayload } from "jsonwebtoken";
+/**
+ * Flexible decode
+ * Returns: null | string | JwtPayload
+ * Mirrors jsonwebtoken.decode()
+ */
+export declare function decodeToken(token: string): null | string | JwtPayload;
+/**
+ * Strict decode
+ * Always returns JwtPayload or throws error
+ */
+export declare function decodeTokenStrict(token: string): JwtPayload;

package/dist/cjs/core/jwt/decode.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeToken = decodeToken;
+exports.decodeTokenStrict = decodeTokenStrict;
+// src/jwt/decodeToken.ts
+const jsonwebtoken_1 = require("jsonwebtoken");
+/**
+ * Flexible decode
+ * Returns: null | string | JwtPayload
+ * Mirrors jsonwebtoken.decode()
+ */
+function decodeToken(token) {
+    return (0, jsonwebtoken_1.decode)(token);
+}
+/**
+ * Strict decode
+ * Always returns JwtPayload or throws error
+ */
+function decodeTokenStrict(token) {
+    const decoded = (0, jsonwebtoken_1.decode)(token);
+    if (!decoded || typeof decoded === "string") {
+        throw new Error("Invalid JWT payload structure");
+    }
+    return decoded;
+}

package/dist/cjs/core/jwt/extractToken.d.ts

@@ -0,0 +1,11 @@
+export interface TokenSources {
+    header?: string | undefined | null;
+    cookies?: Record<string, string> | undefined;
+    query?: Record<string, string | undefined> | undefined;
+    body?: Record<string, unknown> | undefined;
+    wsMessage?: string | Record<string, unknown> | undefined;
+}
+/**
+ * Universal token extractor
+ */
+export declare function extractToken(sources: TokenSources): string | null;

package/dist/cjs/core/jwt/extractToken.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractToken = extractToken;
+/**
+ * Universal token extractor
+ */
+function extractToken(sources) {
+    const { header, cookies, query, body, wsMessage } = sources;
+    // 1. Authorization: Bearer <token>
+    if (header) {
+        const parts = header.split(" ");
+        if (parts.length === 2 && parts[0] === "Bearer")
+            return parts[1];
+    }
+    // 2. Cookies: token / accessToken
+    if (cookies) {
+        if (cookies["token"])
+            return cookies["token"];
+        if (cookies["accessToken"])
+            return cookies["accessToken"];
+    }
+    // 3. Query params: ?token=xxx
+    if (query?.token)
+        return query.token;
+    // 4. Body: { token: "" }
+    if (body?.token && typeof body.token === 'string')
+        return body.token;
+    // 5. WebSocket message extraction (NEW)
+    if (wsMessage) {
+        try {
+            let msg = wsMessage;
+            // If it's a JSON string → parse safely
+            if (typeof wsMessage === "string") {
+                msg = JSON.parse(wsMessage);
+            }
+            // Ensure msg is an object before property access
+            if (typeof msg === 'object' && msg !== null) {
+                const m = msg;
+                if (typeof m['token'] === 'string')
+                    return m['token'];
+                const auth = m['auth'];
+                if (typeof auth === 'object' && auth !== null) {
+                    const a = auth;
+                    if (typeof a['token'] === 'string')
+                        return a['token'];
+                }
+            }
+        }
+        catch {
+            // Ignore parse errors gracefully
+        }
+    }
+    return null;
+}

package/dist/cjs/core/jwt/generateTokens.d.ts

@@ -0,0 +1,4 @@
+import { Secret } from "jsonwebtoken";
+import { RefreshToken, TokenPair } from "./types";
+export declare const generateTokens: (payload: Record<string, unknown>, accessSecret: Secret, refreshSecret: Secret, accessExpiry?: string | number, refreshExpiry?: string | number) => TokenPair;
+export declare function rotateRefreshToken(oldToken: string, secret: Secret): RefreshToken;