ts-packages 1.0.0 → 3.0.0

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

@@ -0,0 +1,244 @@
+import crypto from 'crypto'
+import bcrypt from 'bcryptjs'
+
+import type {
+	HashedPassword,
+	IPasswordManager,
+	PasswordConfig,
+	PasswordStrength,
+	PasswordValidationResult,
+} from '../../interfaces/password.interface'
+
+import {
+	BadRequestError,
+	ValidationError,
+} from '@naman_deep_singh/errors-utils'
+import { ensureValidPassword, estimatePasswordEntropy } from './utils'
+
+export class PasswordManager implements IPasswordManager {
+	private defaultConfig: PasswordConfig
+
+	constructor(config: PasswordConfig = {}) {
+		this.defaultConfig = {
+			saltRounds: 10,
+			minLength: 8,
+			maxLength: 128,
+			requireUppercase: true,
+			requireLowercase: true,
+			requireNumbers: true,
+			requireSpecialChars: false,
+			...config,
+		}
+	}
+
+	/**
+	 * Hash a password asynchronously using bcrypt
+	 */
+	async hash(password: string, salt?: string): Promise<HashedPassword> {
+		try {
+			ensureValidPassword(password)
+			this.validate(password)
+
+			const saltRounds = this.defaultConfig.saltRounds!
+
+			let finalSalt = salt
+			if (!finalSalt) {
+				finalSalt = await bcrypt.genSalt(saltRounds)
+			}
+
+			const hash = await bcrypt.hash(password, finalSalt)
+
+			return { hash, salt: finalSalt }
+		} catch (error) {
+			if (
+				error instanceof BadRequestError ||
+				error instanceof ValidationError
+			) {
+				throw error
+			}
+			throw new BadRequestError(
+				{ reason: 'Failed to hash password' },
+				error instanceof Error ? error : undefined,
+			)
+		}
+	}
+
+	/**
+	 * Verify password against hash and salt
+	 */
+	async verify(password: string, hash: string, salt: string): Promise<boolean> {
+		try {
+			if (!password || !hash || !salt) return false
+
+			// bcrypt compare works directly with hash
+			return await bcrypt.compare(password, hash)
+		} catch {
+			return false
+		}
+	}
+
+	/**
+	 * Generate a random password
+	 */
+	generate(length = 16, options: PasswordConfig = {}): string {
+		const config = { ...this.defaultConfig, ...options }
+
+		if (length < config.minLength! || length > 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 += '!@#$%^&*()_+-=[]{}|;:,.<>?'
+
+		const randomBytes = crypto.randomBytes(length)
+		let password = ''
+		for (let i = 0; i < length; i++) {
+			password += charset[randomBytes[i] % charset.length]
+		}
+
+		// Ensure requirements
+		if (config.requireUppercase && !/[A-Z]/.test(password))
+			password = password.replace(/[a-z]/, 'A')
+		if (config.requireLowercase && !/[a-z]/.test(password))
+			password = password.replace(/[A-Z]/, 'a')
+		if (config.requireNumbers && !/[0-9]/.test(password))
+			password = password.replace(/[A-Za-z]/, '0')
+		if (config.requireSpecialChars && !/[^A-Za-z0-9]/.test(password))
+			password = password.replace(/[A-Za-z0-9]/, '!')
+
+		return password
+	}
+
+	/**
+	 * Validate password against configuration
+	 */
+	validate(
+		password: string,
+		config: PasswordConfig = {},
+	): PasswordValidationResult {
+		const finalConfig = { ...this.defaultConfig, ...config }
+		const errors: string[] = []
+
+		if (!password || typeof password !== 'string')
+			errors.push('Password must be a non-empty string')
+		if (password.length < finalConfig.minLength!)
+			errors.push(
+				`Password must be at least ${finalConfig.minLength} characters`,
+			)
+		if (password.length > finalConfig.maxLength!)
+			errors.push(
+				`Password must not exceed ${finalConfig.maxLength} characters`,
+			)
+		if (finalConfig.requireUppercase && !/[A-Z]/.test(password))
+			errors.push('Password must contain at least one uppercase letter')
+		if (finalConfig.requireLowercase && !/[a-z]/.test(password))
+			errors.push('Password must contain at least one lowercase letter')
+		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))
+			errors.push('Password must contain at least one special character')
+
+		if (finalConfig.customRules) {
+			finalConfig.customRules.forEach((rule) => {
+				if (!rule.test(password)) errors.push(rule.message)
+			})
+		}
+
+		return {
+			isValid: errors.length === 0,
+			errors,
+			strength: this.checkStrength(password),
+		}
+	}
+
+	/**
+	 * Check password strength
+	 */
+	checkStrength(password: string): PasswordStrength {
+		const entropy = estimatePasswordEntropy(password)
+		let score = 0
+		const feedback: string[] = []
+		const suggestions: string[] = []
+
+		if (entropy < 28) {
+			feedback.push('Password is easy to guess')
+			suggestions.push('Use more unique characters and length')
+		} else if (entropy < 36) score++
+		else if (entropy < 60) score += 2
+		else score += 3
+
+		if (password.length >= 12) score++
+		if (password.length >= 16) score++
+
+		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++
+
+		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')
+		}
+
+		const commonPasswords = ['password', '123456', 'qwerty', 'admin', 'letmein']
+		if (
+			commonPasswords.some((common) => password.toLowerCase().includes(common))
+		) {
+			score = 0
+			feedback.push('Avoid common passwords')
+		}
+
+		score = Math.max(0, Math.min(4, score))
+
+		let label: PasswordStrength['label']
+		switch (score) {
+			case 0:
+				label = 'very-weak'
+				suggestions.push('Use a longer password with mixed characters')
+				break
+			case 1:
+				label = 'weak'
+				suggestions.push('Add more character variety')
+				break
+			case 2:
+				label = 'fair'
+				suggestions.push('Consider increasing length or randomness')
+				break
+			case 3:
+				label = 'good'
+				suggestions.push('Your password is reasonably secure')
+				break
+			case 4:
+				label = 'strong'
+				suggestions.push('Your password is very secure')
+				break
+			default:
+				label = 'very-weak'
+		}
+
+		return { score, label, feedback, suggestions }
+	}
+
+	/**
+	 * Check if password hash needs upgrade (saltRounds change)
+	 */
+	needsUpgrade(_hash: string, _currentConfig: PasswordConfig): boolean {
+		return false
+	}
+}

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

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

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

@@ -0,0 +1,7 @@
+export interface PasswordStrengthOptions {
+	minLength?: number
+	requireUppercase?: boolean
+	requireLowercase?: boolean
+	requireNumbers?: boolean
+	requireSymbols?: boolean
+}

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

@@ -0,0 +1,47 @@
+import crypto from 'crypto'
+import { BadRequestError } from '@naman_deep_singh/errors-utils'
+
+/**
+ * Ensure password is a valid non-empty string
+ */
+export function ensureValidPassword(password: string): void {
+	if (!password || typeof password !== 'string') {
+		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)
+
+	if (bufA.length !== bufB.length) return false
+
+	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)
+}
+
+/**
+ * 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

@@ -0,0 +1,49 @@
+import { UnauthorizedError } from '@naman_deep_singh/errors-utils'
+import bcrypt from 'bcryptjs'
+
+/**
+ * Compare a password with a stored hash asynchronously.
+ */
+export const verifyPassword = async (
+	password: string,
+	hash: string,
+): Promise<boolean> => {
+	try {
+		const result = await bcrypt.compare(password, hash)
+		if (!result)
+			throw new UnauthorizedError({ reason: 'Password verification failed' })
+		return result
+	} catch {
+		throw new UnauthorizedError({ reason: 'Password verification failed' })
+	}
+}
+
+export async function verifyPasswordWithPepper(
+	password: string,
+	pepper: string,
+	hash: string,
+) {
+	return verifyPassword(password + pepper, hash)
+}
+
+/**
+ * Compare a password with a stored hash synchronously.
+ */
+export const verifyPasswordSync = (password: string, hash: string): boolean => {
+	try {
+		const result = bcrypt.compareSync(password, hash)
+		if (!result)
+			throw new UnauthorizedError({ reason: 'Password verification failed' })
+		return result
+	} catch (_error) {
+		throw new UnauthorizedError({ reason: 'Password verification failed' })
+	}
+}
+
+export async function verifyPasswordWithPepperSync(
+	password: string,
+	pepper: string,
+	hash: string,
+) {
+	return verifyPasswordSync(password + pepper, hash)
+}

package/packages/security/src/index.ts

@@ -1,39 +1,21 @@
-import jwt, { Secret, JwtPayload } from "jsonwebtoken";
-import bcrypt from "bcryptjs";
-
-// 🧱 Password helpers
-export const hashPassword = async (password: string): Promise<string> => {
-  const salt = await bcrypt.genSalt(10);
-  return bcrypt.hash(password, salt);
-};
-
-export const verifyPassword = async (password: string, hash: string): Promise<boolean> => {
-  return bcrypt.compare(password, hash);
-};
-
-// For backward compatibility
-export const comparePassword = verifyPassword;
-
-// 🧩 JWT helpers
-export const generateToken = (payload: Record<string, unknown>, secret: Secret, expiresIn = "1h"): string => {
-  return jwt.sign(payload, secret, { expiresIn, algorithm: "HS256" } as jwt.SignOptions);
-};
-
-export const verifyToken = (token: string, secret: Secret): string | JwtPayload => {
-  return jwt.verify(token, secret);
-};
-
-// For backward compatibility
-export const signToken = generateToken;
-
-// Default export for namespace usage
-const SecurityUtils = {
-  hashPassword,
-  verifyPassword,
-  comparePassword,
-  generateToken,
-  verifyToken,
-  signToken
-};
-
-export default SecurityUtils;
+export * from './core/password'
+export * from './core/jwt'
+export * from './core/crypto'
+
+// Re-export common errors for convenience
+export {
+	BadRequestError,
+	UnauthorizedError,
+	ValidationError,
+	InternalServerError,
+} from '@naman_deep_singh/errors-utils'
+
+import * as CryptoUtils from './core/crypto'
+import * as JWTUtils from './core/jwt'
+import * as PasswordUtils from './core/password'
+
+export default {
+	...PasswordUtils,
+	...JWTUtils,
+	...CryptoUtils,
+}

package/packages/security/src/interfaces/jwt.interface.ts

@@ -0,0 +1,58 @@
+import type { JwtPayload, Secret } from 'jsonwebtoken'
+
+export interface AccessToken extends String {
+	readonly __type: 'AccessToken'
+}
+
+export interface RefreshToken extends String {
+	readonly __type: 'RefreshToken'
+}
+
+export interface TokenPair {
+	accessToken: AccessToken
+	refreshToken: RefreshToken
+}
+
+export interface JWTConfig {
+	accessSecret: Secret
+	refreshSecret: Secret
+	accessExpiry?: string | number
+	refreshExpiry?: string | number
+	enableCaching?: boolean
+	maxCacheSize?: number
+}
+
+export interface TokenValidationOptions {
+	ignoreExpiration?: boolean
+	ignoreNotBefore?: boolean
+	audience?: string | string[]
+	issuer?: string
+	algorithms?: string[]
+}
+
+export interface TokenGenerationOptions {
+	algorithm?: string
+	expiresIn?: string | number
+	audience?: string | string[]
+	issuer?: string
+	subject?: string
+	kid?: string
+}
+
+export interface ITokenManager {
+	generateTokens(payload: Record<string, unknown>): Promise<TokenPair>
+	generateAccessToken(payload: Record<string, unknown>): Promise<AccessToken>
+	generateRefreshToken(payload: Record<string, unknown>): Promise<RefreshToken>
+	verifyAccessToken(token: string): Promise<JwtPayload | string>
+	verifyRefreshToken(token: string): Promise<JwtPayload | string>
+	decodeToken(token: string, complete?: boolean): JwtPayload | string | null
+	extractTokenFromHeader(authHeader: string): string | null
+	validateToken(
+		token: string,
+		secret: Secret,
+		options?: TokenValidationOptions,
+	): boolean
+	rotateRefreshToken(oldToken: string): Promise<RefreshToken>
+	isTokenExpired(token: string): boolean
+	getTokenExpiration(token: string): Date | null
+}

package/packages/security/src/interfaces/password.interface.ts

@@ -0,0 +1,54 @@
+export interface PasswordConfig {
+	saltRounds?: number
+	minLength?: number
+	maxLength?: number
+	requireUppercase?: boolean
+	requireLowercase?: boolean
+	requireNumbers?: boolean
+	requireSpecialChars?: boolean
+	customRules?: PasswordRule[]
+}
+
+export interface PasswordRule {
+	test: (password: string) => boolean
+	message: string
+}
+
+export interface PasswordStrength {
+	score: number // 0-4 (very weak to very strong)
+	label: 'very-weak' | 'weak' | 'fair' | 'good' | 'strong'
+	feedback: string[]
+	suggestions: string[]
+}
+
+export interface PasswordValidationResult {
+	isValid: boolean
+	errors: string[]
+	strength: PasswordStrength
+}
+
+export interface HashedPassword {
+	hash: string
+	salt: string
+}
+
+export interface IPasswordManager {
+	hash(password: string, salt?: string): Promise<HashedPassword>
+	verify(password: string, hash: string, salt: string): Promise<boolean>
+	generate(length?: number, options?: PasswordConfig): string
+	validate(password: string, config?: PasswordConfig): PasswordValidationResult
+	checkStrength(password: string): PasswordStrength
+	needsUpgrade(hash: string, currentConfig: PasswordConfig): boolean
+}
+
+export interface IPasswordStrengthChecker {
+	analyze(password: string): PasswordStrength
+	checkLength(password: string): { valid: boolean; message: string }
+	checkComplexity(
+		password: string,
+		config: PasswordConfig,
+	): { valid: boolean; message: string }[]
+	checkCommonPasswords(password: string): { valid: boolean; message: string }
+	checkSequential(password: string): { valid: boolean; message: string }
+	checkRepetition(password: string): { valid: boolean; message: string }
+}

package/packages/security/tsconfig.base.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "moduleResolution": "node",
+    "strict": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "declaration": true,
+    "baseUrl": ".",
+    "paths": {
+      "*": ["*", "*.ts", "*.js"]
+    }
+  },
+  "include": ["src/**/*"]
+}

package/packages/security/tsconfig.cjs.json

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

package/packages/security/tsconfig.esm.json

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