ts-packages 1.0.0 → 3.0.0

package/packages/response-utils/src/index.ts

@@ -1,168 +1,13 @@
-export interface ApiResponse<T = any> {
-  success: boolean;
-  message: string;
-  data?: T;
-  error?: string;
-  statusCode: number;
-}
-
-export interface ResponseObject {
-  status: (code: number) => ResponseObject;
-  json: (data: unknown) => any;
-}
-
-export const success = <T>(data: T, message = 'Success', statusCode = 200, res?: ResponseObject): ApiResponse<T> => {
-  const response = {
-    success: true,
-    message,
-    data,
-    statusCode
-  };
-  
-  if (res) {
-    return res.status(statusCode).json(response);
-  }
-  
-  return response;
-};
-
-export const error = (message: string, statusCode = 500, error?: string, res?: ResponseObject): ApiResponse => {
-  const response = {
-    success: false,
-    message,
-    error,
-    statusCode
-  };
-  
-  if (res) {
-    return res.status(statusCode).json(response);
-  }
-  
-  return response;
-};
-
-export const created = <T>(data: T, message = 'Created successfully', res?: ResponseObject): ApiResponse<T> =>
-  success(data, message, 201, res);
-
-export const notFound = (message = 'Resource not found', res?: ResponseObject): ApiResponse =>
-  error(message, 404, undefined, res);
-
-export const badRequest = (message = 'Bad request', validationError?: string, res?: ResponseObject): ApiResponse =>
-  error(message, 400, validationError, res);
-
-export const unauthorized = (message = 'Unauthorized', res?: ResponseObject): ApiResponse =>
-  error(message, 401, undefined, res);
-
-export const forbidden = (message = 'Forbidden', res?: ResponseObject): ApiResponse =>
-  error(message, 403, undefined, res);
-
-export const serverError = (message = 'Internal server error', res?: ResponseObject): ApiResponse =>
-  error(message, 500, undefined, res);
-
-export const noContent = (message = 'No content', res?: ResponseObject): ApiResponse => {
-  const response = {
-    success: true,
-    message,
-    statusCode: 204
-  };
-  
-  if (res) {
-    return res.status(204).json(response);
-  }
-  
-  return response;
-};
-
-export const conflict = (message = 'Conflict', res?: ResponseObject): ApiResponse =>
-  error(message, 409, undefined, res);
-
-export const validationError = (message = 'Validation failed', errors: string[], res?: ResponseObject): ApiResponse => {
-  const response = {
-    success: false,
-    message,
-    error: errors.join(', '),
-    statusCode: 422
-  };
-  
-  if (res) {
-    return res.status(422).json(response);
-  }
-  
-  return response;
-};
-
-export interface PaginatedResponse<T> extends ApiResponse<T[]> {
-  pagination: {
-    page: number;
-    limit: number;
-    total: number;
-    totalPages: number;
-  };
-}
-
-export const paginated = <T>(
-  data: T[],
-  page: number,
-  limit: number,
-  total: number,
-  message = 'Data retrieved successfully',
-  res?: ResponseObject
-): PaginatedResponse<T> => {
-  const response = {
-    success: true,
-    message,
-    data,
-    statusCode: 200,
-    pagination: {
-      page,
-      limit,
-      total,
-      totalPages: Math.ceil(total / limit)
-    }
-  };
-  
-  if (res) {
-    return res.status(200).json(response);
-  }
-  
-  return response;
-};
-
-export const tooManyRequests = (message = 'Too many requests', res?: ResponseObject): ApiResponse => 
-  error(message, 429, undefined, res);
-
-export const timeout = (message = 'Request timeout', res?: ResponseObject): ApiResponse => 
-  error(message, 408, undefined, res);
-
-export const logError = (context: string, error: unknown): void => {
-  const message = error instanceof Error ? error.message : 'Unknown error';
-  console.error(`Error in ${context}:`, message);
-};
-
-export const getErrorMessage = (error: unknown): string => {
-  if (error instanceof Error) return error.message;
-  if (typeof error === 'string') return error;
-  return 'An unknown error occurred';
-};
-
-// Default export for namespace usage
-const ResponseUtils = {
-  success,
-  error,
-  created,
-  notFound,
-  badRequest,
-  unauthorized,
-  forbidden,
-  serverError,
-  noContent,
-  conflict,
-  validationError,
-  paginated,
-  tooManyRequests,
-  timeout,
-  logError,
-  getErrorMessage
-};
-
-export default ResponseUtils;
+// Core Responders
+export { BaseResponder } from './core/BaseResponder'
+export { createResponderFactory } from './core/factory'
+export * from './core/types'
+export * from './core/config'
+
+// Adapters (Express)
+export { ExpressResponder } from './adapters/express/ExpressResponder'
+export { responderMiddleware } from './middleware/express/expressMiddleware'
+
+// HTTP Status Constants
+export { HTTP_STATUS } from './constants/httpStatus'
+export type { HttpStatusCode } from './constants/httpStatus'

package/packages/response-utils/src/middleware/express/expressMiddleware.ts

@@ -0,0 +1,14 @@
+import type { RequestHandler } from 'express'
+import type { ResponderConfig } from '../../core/config'
+import { createResponderFactory } from '../../core/factory'
+
+export const responderMiddleware = (
+	cfg?: Partial<ResponderConfig>,
+): RequestHandler => {
+	const factory = createResponderFactory(cfg)
+
+	return (_req, res, next) => {
+		;(res as any).responder = <P = unknown>() => factory<P>(res)
+		next()
+	}
+}

package/packages/response-utils/tsconfig.base.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"]
+}

package/packages/response-utils/tsconfig.cjs.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "rootDir": "./src",
+    "outDir": "./dist/cjs"
+  }
+}

package/packages/response-utils/tsconfig.esm.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "rootDir": "./src",
+    "outDir": "./dist/esm"
+  }
+}

package/packages/security/README.md

@@ -1,116 +1,328 @@
-# @naman_deep_singh/security
+```bash
+@naman_deep_singh/security
 
-Security utilities for password hashing and JWT token management with TypeScript support.
+Version: 1.5.1
 
-## Installation
+A complete, lightweight security toolkit for Node.js & TypeScript providing:
 
-```bash
+🔐 Password hashing & validation with bcrypt (async/sync, peppered variants)
+🔑 JWT signing & verification (safe, strict, and cached)
+🧮 Duration parser ("15m", "7d", etc.)
+🪪 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)
+✔ 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
+
+📦 Installation
 npm install @naman_deep_singh/security
-```
 
-## Features
+🔧 Features
+Password Security
 
-- ✅ **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
+Async & sync bcrypt hashing
 
-## Usage
+Peppered hashing variants
 
-### Named Imports (Tree-shakable)
-```typescript
-import { hashPassword, verifyPassword, generateToken, verifyToken } from '@naman_deep_singh/security';
+Password validation & strength checking
 
-// Password hashing
-const hashedPassword = await hashPassword('mypassword');
-const isValid = await verifyPassword('mypassword', hashedPassword);
+Configurable complexity requirements
 
-// JWT tokens
-const token = generateToken({ userId: 1, role: 'admin' }, 'your-secret-key', '24h');
-const decoded = verifyToken(token, 'your-secret-key');
-```
+Secure password generation
 
-### Namespace Import
-```typescript
-import SecurityUtils from '@naman_deep_singh/security';
+JWT Security
 
-const hashedPassword = await SecurityUtils.hashPassword('mypassword');
-const token = SecurityUtils.generateToken({ userId: 1 }, 'secret');
-```
+Custom expiry using duration strings
 
-### Backward Compatibility
-```typescript
-import { comparePassword, signToken } from '@naman_deep_singh/security';
+Token pair generation (access + refresh)
 
-// Legacy function names still work
-const isValid = await comparePassword('password', 'hash');
-const token = signToken({ userId: 1 }, 'secret');
-```
+Refresh token rotation
 
-## API Reference
+Safe & unsafe JWT verification
 
-### 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)
+Strict vs flexible decoding
 
-### 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)
+Token caching for performance
 
-## Examples
+Cryptography
 
-### Complete Authentication Flow
-```typescript
-import { hashPassword, verifyPassword, generateToken, verifyToken } from '@naman_deep_singh/security';
+AES-256-GCM encryption/decryption
 
-// Registration
-async function registerUser(email: string, password: string) {
-  const hashedPassword = await hashPassword(password);
-  // Save user with hashedPassword to database
-  return { email, password: hashedPassword };
+HMAC signing and verification
+
+Cryptographically secure random generation
+
+Utilities
+
+Duration parsing (e.g., "15m" → 900 seconds)
+
+Token extraction from headers, cookies, query, body, and WebSocket messages
+
+Fully typed interfaces and branded token types
+
+📘 Quick Start
+Functional Approach (Simple)
+import {
+  hashPassword,
+  verifyPassword,
+  generateTokens,
+  verifyToken,
+  safeVerifyToken,
+  extractToken,
+  encrypt,
+  decrypt,
+  parseDuration,
+  decodeToken,
+  decodeTokenStrict,
+} 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"
+);
+
+// Safe verification
+const result = safeVerifyToken(tokens.accessToken, process.env.ACCESS_SECRET!);
+if (!result.valid) {
+  console.log(result.error.message); // UnauthorizedError instance
 }
 
-// Login
-async function loginUser(email: string, password: string, storedHash: string) {
-  const isValid = await verifyPassword(password, storedHash);
-  
-  if (!isValid) {
-    throw new Error('Invalid credentials');
-  }
-  
-  const token = generateToken(
-    { email, loginTime: Date.now() },
-    process.env.JWT_SECRET!,
-    '7d'
-  );
-  
-  return { token };
+// Decode without verification
+const decoded = decodeToken(tokens.accessToken); // null | string | JwtPayload
+const strictPayload = decodeTokenStrict(tokens.accessToken); // throws if invalid
+
+// Parse duration
+const seconds = parseDuration("15m"); // 900
+
+// Token extraction
+const token = extractToken({
+  header: req.headers.authorization,
+  cookies: req.cookies,
+  query: req.query,
+  body: req.body,
+  wsMessage: message, // string or { token: "..." }
+});
+
+// Crypto operations
+const encrypted = encrypt("sensitive data", "secret-key");
+const decrypted = decrypt(encrypted, "secret-key");
+
+Class-Based Approach (Advanced)
+PasswordManager
+import { PasswordManager } from "@naman_deep_singh/security";
+
+const passwordManager = new PasswordManager({
+  minLength: 12,
+  requireUppercase: true,
+  requireNumbers: true,
+  requireSpecialChars: true,
+  customRules: [
+    { test: (pwd) => !pwd.includes("password"), message: 'Cannot contain "password"' }
+  ]
+});
+
+// Validate password
+const validation = passwordManager.validate("MySecurePass123!");
+if (!validation.isValid) console.log(validation.errors);
+
+// Hash password
+const { hash, salt } = await passwordManager.hash("MySecurePass123!");
+
+// Verify password
+const isValid = await passwordManager.verify("MySecurePass123!", hash, salt);
+
+// Generate secure password
+const generated = passwordManager.generate(16, {
+  requireUppercase: true,
+  requireNumbers: true,
+  requireSpecialChars: true
+});
+
+// Check password strength
+const strength = passwordManager.checkStrength("MySecurePass123!");
+console.log(strength);
+
+JWTManager
+import { JWTManager } from "@naman_deep_singh/security";
+
+const jwtManager = new JWTManager({
+  accessSecret: process.env.ACCESS_SECRET!,
+  refreshSecret: process.env.REFRESH_SECRET!,
+  accessExpiry: "15m",
+  refreshExpiry: "7d",
+  enableCaching: true,
+  maxCacheSize: 100
+});
+
+// Generate tokens
+const tokens = await jwtManager.generateTokens({ userId: 42 });
+
+// Verify tokens
+const accessPayload = await jwtManager.verifyAccessToken(tokens.accessToken);
+const refreshPayload = await jwtManager.verifyRefreshToken(tokens.refreshToken);
+
+// Rotate refresh token
+const rotatedRefreshToken = await jwtManager.rotateRefreshToken(tokens.refreshToken);
+
+// Decode without verification
+const decoded = jwtManager.decodeToken(tokens.accessToken);
+const strictPayload = jwtManager.decodeTokenStrict(tokens.accessToken);
+
+// Extract token from header
+const token = jwtManager.extractTokenFromHeader("Bearer eyJ...");
+
+// Validate token without throwing
+const isValid = jwtManager.validateToken(tokens.accessToken, process.env.ACCESS_SECRET!);
+
+// Check token expiration
+const isExpired = jwtManager.isTokenExpired(tokens.accessToken);
+const expiresAt = jwtManager.getTokenExpiration(tokens.accessToken);
+
+// Cache management
+jwtManager.clearCache();
+const stats = jwtManager.getCacheStats(); // { size: -1, maxSize: 100 }
+
+CryptoManager
+import { CryptoManager } from "@naman_deep_singh/security";
+
+const cryptoManager = new CryptoManager("your-secret-key");
+
+// Encryption
+const encrypted = cryptoManager.encrypt("data");
+const decrypted = cryptoManager.decrypt(encrypted);
+
+// HMAC
+const hmac = cryptoManager.createHMAC("data");
+const isValid = cryptoManager.verifyHMAC("data", hmac);
+
+// Random generation
+const randomBytes = cryptoManager.generateRandomBytes(32);
+const randomString = cryptoManager.generateRandomString(16);
+const randomHex = cryptoManager.generateRandomHex(32);
+
+🚨 Error Handling
+
+This package uses standardized errors from @naman_deep_singh/errors-utils:
+
+import {
+  BadRequestError,
+  UnauthorizedError,
+  ValidationError,
+  InternalServerError
+} from '@naman_deep_singh/security';
+
+try {
+  const hash = await hashPassword('mypassword');
+} catch (error) {
+  if (error instanceof BadRequestError) console.log("Invalid password input");
+  if (error instanceof InternalServerError) console.log("Server error during hashing");
+}
+
+try {
+  const isValid = await verifyPassword('password', hash);
+} catch (error) {
+  if (error instanceof UnauthorizedError) console.log("Invalid credentials");
 }
 
-// Verify JWT
-function authenticateRequest(token: string) {
-  try {
-    const decoded = verifyToken(token, process.env.JWT_SECRET!);
-    return decoded;
-  } catch (error) {
-    throw new Error('Invalid token');
+
+Error Types:
+
+BadRequestError (400) — invalid input
+
+UnauthorizedError (401) — authentication failures
+
+ValidationError (422) — password strength validation
+
+InternalServerError (500) — server-side errors
+
+🧩 Authentication Example
+Registration
+async function registerUser(email: string, password: string) {
+  const validation = passwordManager.validate(password);
+  if (!validation.isValid) {
+    throw new ValidationError(`Password validation failed: ${validation.errors.join(', ')}`);
   }
+
+  const { hash, salt } = await passwordManager.hash(password);
+
+  return { email, passwordHash: hash, passwordSalt: salt };
 }
-```
 
-## Dependencies
+Login
+async function loginUser(email: string, password: string, storedHash: string, storedSalt: string) {
+  const isValid = await passwordManager.verify(password, storedHash, storedSalt);
+  if (!isValid) throw new UnauthorizedError("Invalid credentials");
+
+  return jwtManager.generateTokens({ email });
+}
+
+Token Refresh
+async function refreshTokens(oldRefreshToken: string) {
+  const decoded = await jwtManager.verifyRefreshToken(oldRefreshToken);
+
+  const newTokens = await jwtManager.generateTokens(decoded);
+  const rotatedRefreshToken = await jwtManager.rotateRefreshToken(oldRefreshToken);
+
+  return { accessToken: newTokens.accessToken, refreshToken: rotatedRefreshToken };
+}
+
+Express Middleware
+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: result.error.message });
+
+  req.user = result.payload;
+  next();
+}
+
+🔐 Security Best Practices
+
+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)
+
+Never store passwords in plain text
+
+Use password peppering for extra security
+
+Enable JWT caching carefully, monitor memory
 
-- **bcryptjs** - For secure password hashing
-- **jsonwebtoken** - For JWT token management
+Handle errors with proper HTTP status codes
 
-## Security Best Practices
+Rotate secrets and tokens regularly
 
-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
+Use secure random generation for cryptographic operations
+```