ts-packages 2.0.0 → 3.0.0

package/packages/security/src/core/jwt/verify.ts

@@ -1,55 +1,117 @@
-import type jwt from 'jsonwebtoken'
-import { type JwtPayload, type Secret, verify } from 'jsonwebtoken'
+import { UnauthorizedError } from '@naman_deep_singh/errors-utils'
+import {
+	type JwtPayload,
+	type Secret,
+	type VerifyOptions,
+	verify,
+} from 'jsonwebtoken'
 import type { VerificationResult } from './types'
 
 /**
- * Verify token (throws if invalid or expired)
+ * Verify token (throws UnauthorizedError if invalid or expired)
  */
 export const verifyToken = (
 	token: string,
 	secret: Secret,
 ): string | JwtPayload => {
-	return verify(token, secret)
+	try {
+		return verify(token, secret)
+	} catch (error: any) {
+		if (error.name === 'TokenExpiredError') {
+			throw new UnauthorizedError({ reason: 'Token has expired' }, error)
+		}
+		if (error.name === 'JsonWebTokenError') {
+			throw new UnauthorizedError({ reason: 'Invalid token' }, error)
+		}
+		throw new UnauthorizedError({ reason: 'Failed to verify token' }, error)
+	}
 }
 
 /**
- * Safe verify — never throws, returns structured result
+ * Verify token with options
  */
-export const safeVerifyToken = (
+export const verifyTokenWithOptions = (
 	token: string,
 	secret: Secret,
-): VerificationResult => {
+	options: VerifyOptions = {},
+): string | JwtPayload => {
 	try {
-		const decoded = verify(token, secret)
-		return { valid: true, payload: decoded }
-	} catch (error) {
-		return { valid: false, error: error as Error }
+		return verify(token, secret, options)
+	} catch (error: any) {
+		if (error.name === 'TokenExpiredError') {
+			throw new UnauthorizedError({ reason: 'Token has expired' }, error)
+		}
+		if (error.name === 'JsonWebTokenError') {
+			throw new UnauthorizedError({ reason: 'Invalid token' }, error)
+		}
+		throw new UnauthorizedError({ reason: 'Failed to verify token' }, error)
 	}
 }
 
 /**
- * Verify token with validation options
+ * Safe verify — never throws, returns structured result with UnauthorizedError on failure
  */
-export const verifyTokenWithOptions = (
+export const safeVerifyToken = (
 	token: string,
 	secret: Secret,
-	options: jwt.VerifyOptions = {},
-): string | JwtPayload => {
-	return verify(token, secret, options)
+): VerificationResult => {
+	try {
+		const decoded = verify(token, secret)
+		return { valid: true, payload: decoded }
+	} catch (error: any) {
+		let wrappedError: UnauthorizedError
+
+		if (error.name === 'TokenExpiredError') {
+			wrappedError = new UnauthorizedError(
+				{ reason: 'Token has expired' },
+				error,
+			)
+		} else if (error.name === 'JsonWebTokenError') {
+			wrappedError = new UnauthorizedError({ reason: 'Invalid token' }, error)
+		} else {
+			wrappedError = new UnauthorizedError(
+				{ reason: 'Failed to verify token' },
+				error,
+			)
+		}
+
+		return { valid: false, error: wrappedError }
+	}
 }
 
 /**
- * Safe verify with validation options
+ * Safe verify with options — never throws, returns structured result with UnauthorizedError on failure
  */
 export const safeVerifyTokenWithOptions = (
 	token: string,
 	secret: Secret,
-	options: jwt.VerifyOptions = {},
+	options: VerifyOptions = {},
 ): VerificationResult => {
 	try {
 		const decoded = verify(token, secret, options)
 		return { valid: true, payload: decoded }
-	} catch (error) {
-		return { valid: false, error: error as Error }
+	} catch (error: any) {
+		let wrappedError: UnauthorizedError
+
+		if (error.name === 'TokenExpiredError') {
+			wrappedError = new UnauthorizedError(
+				{ reason: 'Token has expired' },
+				error instanceof Error ? error : undefined,
+			)
+		} else if (error.name === 'JsonWebTokenError') {
+			wrappedError = new UnauthorizedError(
+				{
+					reason: 'Invalid token',
+				},
+				error instanceof Error ? error : undefined,
+			)
+		} else {
+			wrappedError = new UnauthorizedError(
+				{ reason: 'Failed to verify token' },
+				error instanceof Error ? error : undefined,
+			)
+		}
+
+		return { valid: false, error: wrappedError }
 	}
 }

package/packages/security/src/core/password/hash.ts

@@ -13,8 +13,11 @@ export const hashPassword = async (
 		ensureValidPassword(password)
 		const salt = await bcrypt.genSalt(saltRounds)
 		return bcrypt.hash(password, salt)
-	} catch (_err) {
-		throw new InternalServerError('Password hashing failed')
+	} catch (error) {
+		throw new InternalServerError(
+			{ reason: 'Password hashing failed' },
+			error instanceof Error ? error : undefined,
+		)
 	}
 }
 
@@ -30,8 +33,11 @@ export const hashPasswordSync = (password: string, saltRounds = 10): string => {
 		ensureValidPassword(password)
 		const salt = bcrypt.genSaltSync(saltRounds)
 		return bcrypt.hashSync(password, salt)
-	} catch (_error) {
-		throw new InternalServerError('Password hashing failed')
+	} catch (error) {
+		throw new InternalServerError(
+			{ reason: 'Password hashing failed' },
+			error instanceof Error ? error : undefined,
+		)
 	}
 }
 

package/packages/security/src/core/password/passwordManager.ts

@@ -37,23 +37,18 @@ export class PasswordManager implements IPasswordManager {
 	async hash(password: string, salt?: string): Promise<HashedPassword> {
 		try {
 			ensureValidPassword(password)
-
-			// Validate password meets basic requirements
 			this.validate(password)
 
 			const saltRounds = this.defaultConfig.saltRounds!
-			let passwordSalt = salt
 
-			if (!passwordSalt) {
-				passwordSalt = await bcrypt.genSalt(saltRounds)
+			let finalSalt = salt
+			if (!finalSalt) {
+				finalSalt = await bcrypt.genSalt(saltRounds)
 			}
 
-			const hash = await bcrypt.hash(password, passwordSalt)
+			const hash = await bcrypt.hash(password, finalSalt)
 
-			return {
-				hash,
-				salt: passwordSalt,
-			}
+			return { hash, salt: finalSalt }
 		} catch (error) {
 			if (
 				error instanceof BadRequestError ||
@@ -61,7 +56,10 @@ export class PasswordManager implements IPasswordManager {
 			) {
 				throw error
 			}
-			throw new BadRequestError('Failed to hash password')
+			throw new BadRequestError(
+				{ reason: 'Failed to hash password' },
+				error instanceof Error ? error : undefined,
+			)
 		}
 	}
 
@@ -70,21 +68,11 @@ export class PasswordManager implements IPasswordManager {
 	 */
 	async verify(password: string, hash: string, salt: string): Promise<boolean> {
 		try {
-			if (!password || !hash || !salt) {
-				return false
-			}
-
-			// First verify with the provided salt
-			const isValid = await bcrypt.compare(password, hash)
-
-			// If invalid and different salt was used, try regenerating hash with new salt
-			if (!isValid && salt !== this.defaultConfig.saltRounds?.toString()) {
-				const newHash = await bcrypt.hash(password, salt)
-				return newHash === hash
-			}
+			if (!password || !hash || !salt) return false
 
-			return isValid
-		} catch (_error) {
+			// bcrypt compare works directly with hash
+			return await bcrypt.compare(password, hash)
+		} catch {
 			return false
 		}
 	}
@@ -96,37 +84,31 @@ export class PasswordManager implements IPasswordManager {
 		const config = { ...this.defaultConfig, ...options }
 
 		if (length < config.minLength! || length > config.maxLength!) {
-			throw new ValidationError(
-				`Password length must be between ${config.minLength} and ${config.maxLength}`,
-			)
+			throw new ValidationError({
+				reason: `Password length must be between ${config.minLength} and ${config.maxLength}`,
+			})
 		}
 
 		let charset = 'abcdefghijklmnopqrstuvwxyz'
-
 		if (config.requireUppercase) charset += 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
 		if (config.requireNumbers) charset += '0123456789'
 		if (config.requireSpecialChars) charset += '!@#$%^&*()_+-=[]{}|;:,.<>?'
 
-		let password = ''
 		const randomBytes = crypto.randomBytes(length)
-
+		let password = ''
 		for (let i = 0; i < length; i++) {
 			password += charset[randomBytes[i] % charset.length]
 		}
 
-		// Ensure all requirements are met
-		if (config.requireUppercase && !/[A-Z]/.test(password)) {
+		// Ensure requirements
+		if (config.requireUppercase && !/[A-Z]/.test(password))
 			password = password.replace(/[a-z]/, 'A')
-		}
-		if (config.requireLowercase && !/[a-z]/.test(password)) {
+		if (config.requireLowercase && !/[a-z]/.test(password))
 			password = password.replace(/[A-Z]/, 'a')
-		}
-		if (config.requireNumbers && !/[0-9]/.test(password)) {
+		if (config.requireNumbers && !/[0-9]/.test(password))
 			password = password.replace(/[A-Za-z]/, '0')
-		}
-		if (config.requireSpecialChars && !/[^A-Za-z0-9]/.test(password)) {
+		if (config.requireSpecialChars && !/[^A-Za-z0-9]/.test(password))
 			password = password.replace(/[A-Za-z0-9]/, '!')
-		}
 
 		return password
 	}
@@ -141,57 +123,35 @@ export class PasswordManager implements IPasswordManager {
 		const finalConfig = { ...this.defaultConfig, ...config }
 		const errors: string[] = []
 
-		// Basic validation
-		if (!password || typeof password !== 'string') {
+		if (!password || typeof password !== 'string')
 			errors.push('Password must be a non-empty string')
-		}
-
-		// Length validation
-		if (password.length < finalConfig.minLength!) {
+		if (password.length < finalConfig.minLength!)
 			errors.push(
-				`Password must be at least ${finalConfig.minLength} characters long`,
+				`Password must be at least ${finalConfig.minLength} characters`,
 			)
-		}
-
-		if (password.length > finalConfig.maxLength!) {
+		if (password.length > finalConfig.maxLength!)
 			errors.push(
 				`Password must not exceed ${finalConfig.maxLength} characters`,
 			)
-		}
-
-		// Complexity requirements
-		if (finalConfig.requireUppercase && !/[A-Z]/.test(password)) {
+		if (finalConfig.requireUppercase && !/[A-Z]/.test(password))
 			errors.push('Password must contain at least one uppercase letter')
-		}
-
-		if (finalConfig.requireLowercase && !/[a-z]/.test(password)) {
+		if (finalConfig.requireLowercase && !/[a-z]/.test(password))
 			errors.push('Password must contain at least one lowercase letter')
-		}
-
-		if (finalConfig.requireNumbers && !/[0-9]/.test(password)) {
+		if (finalConfig.requireNumbers && !/[0-9]/.test(password))
 			errors.push('Password must contain at least one number')
-		}
-
-		if (finalConfig.requireSpecialChars && !/[^A-Za-z0-9]/.test(password)) {
+		if (finalConfig.requireSpecialChars && !/[^A-Za-z0-9]/.test(password))
 			errors.push('Password must contain at least one special character')
-		}
 
-		// Custom rules
 		if (finalConfig.customRules) {
 			finalConfig.customRules.forEach((rule) => {
-				if (!rule.test(password)) {
-					errors.push(rule.message)
-				}
+				if (!rule.test(password)) errors.push(rule.message)
 			})
 		}
 
-		const strength = this.checkStrength(password)
-		const isValid = errors.length === 0
-
 		return {
-			isValid,
+			isValid: errors.length === 0,
 			errors,
-			strength,
+			strength: this.checkStrength(password),
 		}
 	}
 
@@ -200,60 +160,42 @@ export class PasswordManager implements IPasswordManager {
 	 */
 	checkStrength(password: string): PasswordStrength {
 		const entropy = estimatePasswordEntropy(password)
-
 		let score = 0
 		const feedback: string[] = []
 		const suggestions: string[] = []
 
-		/* ---------------- Entropy baseline ---------------- */
-
 		if (entropy < 28) {
 			feedback.push('Password is easy to guess')
 			suggestions.push('Use more unique characters and length')
-		} else if (entropy < 36) {
-			score += 1
-		} else if (entropy < 60) {
-			score += 2
-		} else {
-			score += 3
-		}
-
-		/* ---------------- Length scoring ---------------- */
+		} else if (entropy < 36) score++
+		else if (entropy < 60) score += 2
+		else score += 3
 
 		if (password.length >= 12) score++
 		if (password.length >= 16) score++
 
-		/* ---------------- Character variety ---------------- */
-
 		if (/[a-z]/.test(password)) score++
 		if (/[A-Z]/.test(password)) score++
 		if (/[0-9]/.test(password)) score++
 		if (/[^A-Za-z0-9]/.test(password)) score++
 
-		/* ---------------- Pattern deductions ---------------- */
-
 		if (/^[A-Za-z]+$/.test(password)) {
 			score--
 			feedback.push('Consider adding numbers or symbols')
 		}
-
 		if (/^[0-9]+$/.test(password)) {
 			score -= 2
 			feedback.push('Avoid using only numbers')
 		}
-
 		if (/([a-zA-Z0-9])\1{2,}/.test(password)) {
 			score--
 			feedback.push('Avoid repeated characters')
 		}
-
 		if (/(?:012|123|234|345|456|567|678|789)/.test(password)) {
 			score--
 			feedback.push('Avoid sequential patterns')
 		}
 
-		/* ---------------- Common passwords ---------------- */
-
 		const commonPasswords = ['password', '123456', 'qwerty', 'admin', 'letmein']
 		if (
 			commonPasswords.some((common) => password.toLowerCase().includes(common))
@@ -262,14 +204,9 @@ export class PasswordManager implements IPasswordManager {
 			feedback.push('Avoid common passwords')
 		}
 
-		/* ---------------- Clamp score ---------------- */
-
 		score = Math.max(0, Math.min(4, score))
 
-		/* ---------------- Strength label ---------------- */
-
 		let label: PasswordStrength['label']
-
 		switch (score) {
 			case 0:
 				label = 'very-weak'
@@ -295,20 +232,13 @@ export class PasswordManager implements IPasswordManager {
 				label = 'very-weak'
 		}
 
-		return {
-			score,
-			label,
-			feedback,
-			suggestions,
-		}
+		return { score, label, feedback, suggestions }
 	}
 
 	/**
-	 * Check if password hash needs upgrade (different salt rounds)
+	 * Check if password hash needs upgrade (saltRounds change)
 	 */
 	needsUpgrade(_hash: string, _currentConfig: PasswordConfig): boolean {
-		// Simple heuristic: if the hash doesn't match current salt rounds pattern
-		// In practice, you'd need to store the salt rounds with the hash
 		return false
 	}
 }

package/packages/security/src/core/password/strength.ts

@@ -8,7 +8,8 @@ export const isPasswordStrong = (
 	password: string,
 	options: PasswordStrengthOptions = {},
 ): boolean => {
-	if (!password) throw new BadRequestError('Invalid password provided')
+	if (!password)
+		throw new BadRequestError({ reason: 'Invalid password provided' })
 
 	const {
 		minLength = 8,
@@ -19,17 +20,21 @@ export const isPasswordStrong = (
 	} = options
 
 	if (password.length < minLength)
-		throw new ValidationError(
-			`Password must be at least ${minLength} characters`,
-		)
+		throw new ValidationError({
+			reason: `Password must be at least ${minLength} characters long`,
+		})
 	if (requireUppercase && !/[A-Z]/.test(password))
-		throw new ValidationError('Password must include uppercase letters')
+		throw new ValidationError({
+			reason: 'Password must include uppercase letters',
+		})
 	if (requireLowercase && !/[a-z]/.test(password))
-		throw new ValidationError('Password must include lowercase letters')
+		throw new ValidationError({
+			reason: 'Password must include lowercase letters',
+		})
 	if (requireNumbers && !/[0-9]/.test(password))
-		throw new ValidationError('Password must include numbers')
+		throw new ValidationError({ reason: 'Password must include numbers' })
 	if (requireSymbols && !/[^A-Za-z0-9]/.test(password))
-		throw new ValidationError('Password must include symbols')
+		throw new ValidationError({ reason: 'Password must include symbols' })
 
 	return true
 }

package/packages/security/src/core/password/utils.ts

@@ -1,12 +1,18 @@
 import crypto from 'crypto'
 import { BadRequestError } from '@naman_deep_singh/errors-utils'
 
-export function ensureValidPassword(password: string) {
+/**
+ * Ensure password is a valid non-empty string
+ */
+export function ensureValidPassword(password: string): void {
 	if (!password || typeof password !== 'string') {
-		throw new BadRequestError('Invalid password provided')
+		throw new BadRequestError({ reason: 'Invalid password provided' })
 	}
 }
 
+/**
+ * Timing-safe comparison between two strings
+ */
 export function safeCompare(a: string, b: string): boolean {
 	const bufA = Buffer.from(a)
 	const bufB = Buffer.from(b)
@@ -16,16 +22,26 @@ export function safeCompare(a: string, b: string): boolean {
 	return crypto.timingSafeEqual(bufA, bufB)
 }
 
+/**
+ * Estimate password entropy based on character pool
+ */
 export function estimatePasswordEntropy(password: string): number {
 	let pool = 0
+
 	if (/[a-z]/.test(password)) pool += 26
 	if (/[A-Z]/.test(password)) pool += 26
 	if (/[0-9]/.test(password)) pool += 10
 	if (/[^A-Za-z0-9]/.test(password)) pool += 32
 
+	// If no characters matched, fallback to 1 to avoid log2(0)
+	if (pool === 0) pool = 1
+
 	return password.length * Math.log2(pool)
 }
 
-export function normalizePassword(password: string) {
+/**
+ * Normalize password string to a consistent form
+ */
+export function normalizePassword(password: string): string {
 	return password.normalize('NFKC')
 }

package/packages/security/src/core/password/verify.ts

@@ -10,10 +10,11 @@ export const verifyPassword = async (
 ): Promise<boolean> => {
 	try {
 		const result = await bcrypt.compare(password, hash)
-		if (!result) throw new UnauthorizedError('Password verification failed')
+		if (!result)
+			throw new UnauthorizedError({ reason: 'Password verification failed' })
 		return result
 	} catch {
-		throw new UnauthorizedError('Password verification failed')
+		throw new UnauthorizedError({ reason: 'Password verification failed' })
 	}
 }
 
@@ -31,10 +32,11 @@ export async function verifyPasswordWithPepper(
 export const verifyPasswordSync = (password: string, hash: string): boolean => {
 	try {
 		const result = bcrypt.compareSync(password, hash)
-		if (!result) throw new UnauthorizedError('Password verification failed')
+		if (!result)
+			throw new UnauthorizedError({ reason: 'Password verification failed' })
 		return result
 	} catch (_error) {
-		throw new UnauthorizedError('Password verification failed')
+		throw new UnauthorizedError({ reason: 'Password verification failed' })
 	}
 }
 

package/packages/server-utils/README.md

@@ -1,6 +1,6 @@
 # @naman_deep_singh/server-utils
 
-**Version:** 1.4.3 (with integrated cache & session support)
+**Version:** 1.5.1 (with integrated cache & session support)
 
 Extensible server utilities for Express.js microservices with multi-protocol support, integrated caching, session management, and TypeScript.
 

package/packages/server-utils/dist/cjs/core/server.js

@@ -179,8 +179,8 @@ class ExpressServer {
                     });
                     console.log(`✅ [${serverName}] Cache initialized successfully (adapter: ${cacheConfig.adapter || 'memory'})`);
                 }
-                catch (err) {
-                    console.error(`❌ [${serverName}] Failed to initialize cache (fallback to memory if enabled):`, err instanceof Error ? err.message : err);
+                catch (error) {
+                    console.error(`❌ [${serverName}] Failed to initialize cache (fallback to memory if enabled):`, error instanceof Error ? error.message : error);
                     // Cache initialization error is critical but we continue to allow graceful fallback
                 }
             }
@@ -218,14 +218,14 @@ class ExpressServer {
                         this.app.use((0, middleware_1.useSession)(cookieName));
                         console.log(`✅ [${serverName}] Session middleware enabled (cookie: ${cookieName}, TTL: ${ttl}s)`);
                     }
-                    catch (err) {
-                        console.error(`❌ [${serverName}] Session middleware not available:`, err instanceof Error ? err.message : err);
+                    catch (error) {
+                        console.error(`❌ [${serverName}] Session middleware not available:`, error instanceof Error ? error.message : error);
                     }
                 }
             }
         }
-        catch (err) {
-            console.error(`❌ [${serverName}] Error during cache/session setup:`, err instanceof Error ? err.message : err);
+        catch (error) {
+            console.error(`❌ [${serverName}] Error during cache/session setup:`, error instanceof Error ? error.message : error);
         }
     }
     setupPeriodicHealthMonitoring() {

package/packages/server-utils/dist/cjs/middleware/auth.middleware.d.ts

@@ -1,7 +1,6 @@
-import type { Request, RequestHandler } from 'node_modules/@types/express';
+import type { Request, RequestHandler } from 'express';
 export interface AuthConfig {
     secret: string;
-    unauthorizedMessage?: string;
     tokenExtractor?: (req: Request) => string | null;
 }
 export declare function createAuthMiddleware(config: AuthConfig): RequestHandler;

package/packages/server-utils/dist/cjs/middleware/auth.middleware.js

@@ -4,7 +4,7 @@ exports.createAuthMiddleware = createAuthMiddleware;
 const errors_utils_1 = require("@naman_deep_singh/errors-utils");
 const security_1 = require("@naman_deep_singh/security");
 function createAuthMiddleware(config) {
-    const { secret, unauthorizedMessage = 'Unauthorized access', tokenExtractor = (req) => (0, security_1.extractToken)({
+    const { secret, tokenExtractor = (req) => (0, security_1.extractToken)({
         header: req.headers.authorization || undefined,
         cookies: req.cookies,
         query: req.query,
@@ -12,30 +12,33 @@ function createAuthMiddleware(config) {
     }), } = config;
     return async (req, _res, next) => {
         try {
-            // Extract token from request
+            // 1️⃣ Extract token
             const token = tokenExtractor(req);
             if (!token) {
-                const error = new errors_utils_1.UnauthorizedError(unauthorizedMessage, {
+                // No cause → client mistake
+                return next(new errors_utils_1.TokenMalformedError({
                     reason: 'No token provided',
-                });
-                return next(error);
+                }));
             }
-            // Use safe verify token from security package
+            // 2️⃣ Verify token
             const result = (0, security_1.safeVerifyToken)(token, secret);
             if (!result.valid) {
-                const error = new errors_utils_1.UnauthorizedError(unauthorizedMessage, {
-                    reason: 'Invalid or expired token',
-                    originalError: result.error?.message,
-                });
-                return next(error);
+                // Token expired
+                if (result.error?.name === 'TokenExpiredError') {
+                    return next(new errors_utils_1.TokenExpiredError({ reason: 'Token expired' }, result.error));
+                }
+                // Token invalid / malformed
+                return next(new errors_utils_1.TokenMalformedError({
+                    reason: 'Invalid token',
+                }, result.error));
             }
-            // Attach the verified payload as user
+            // 3️⃣ Attach payload
             req.user = result.payload;
             next();
         }
         catch (error) {
-            const unauthorizedError = new errors_utils_1.UnauthorizedError(unauthorizedMessage, error instanceof Error ? { originalError: error.message } : error);
-            return next(unauthorizedError);
+            // Unexpected error → always pass cause
+            return next(new errors_utils_1.UnauthorizedError({ reason: 'Authentication failed' }, error instanceof Error ? error : undefined));
         }
     };
 }