ts-packages 1.0.0 → 2.0.0

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

@@ -0,0 +1,385 @@
+import jwt, { type JwtPayload, type Secret } from 'jsonwebtoken'
+
+import type {
+	AccessToken,
+	ITokenManager,
+	JWTConfig,
+	RefreshToken,
+	TokenPair,
+	TokenValidationOptions,
+} from '../../interfaces/jwt.interface'
+import { signToken } from './signToken'
+import { safeVerifyToken, verifyToken } from './verify'
+
+import {
+	BadRequestError,
+	UnauthorizedError,
+	ValidationError,
+} from '@naman_deep_singh/errors-utils'
+import { LRUCache } from '@naman_deep_singh/js-extensions'
+
+export class JWTManager implements ITokenManager {
+	private accessSecret: Secret
+	private refreshSecret: Secret
+	private accessExpiry: string | number
+	private refreshExpiry: string | number
+	private cache?: LRUCache<
+		string,
+		{ valid: boolean; payload: JwtPayload | string; timestamp: number }
+	>
+	private cacheTTL: number
+
+	constructor(config: JWTConfig) {
+		this.accessSecret = config.accessSecret
+		this.refreshSecret = config.refreshSecret
+		this.accessExpiry = config.accessExpiry || '15m'
+		this.refreshExpiry = config.refreshExpiry || '7d'
+		this.cacheTTL = 5 * 60 * 1000 // 5 minutes default TTL
+
+		if (config.enableCaching) {
+			this.cache = new LRUCache(config.maxCacheSize || 100)
+		}
+	}
+
+	/**
+	 * Generate both access and refresh tokens
+	 */
+	async generateTokens(payload: Record<string, unknown>): Promise<TokenPair> {
+		try {
+			this.validatePayload(payload)
+
+			const accessToken = await this.generateAccessToken(payload)
+			const refreshToken = await this.generateRefreshToken(payload)
+
+			return {
+				accessToken,
+				refreshToken,
+			}
+		} catch (error) {
+			if (
+				error instanceof BadRequestError ||
+				error instanceof ValidationError
+			) {
+				throw error
+			}
+			throw new BadRequestError('Failed to generate tokens')
+		}
+	}
+
+	/**
+	 * Generate access token
+	 */
+	async generateAccessToken(
+		payload: Record<string, unknown>,
+	): Promise<AccessToken> {
+		try {
+			this.validatePayload(payload)
+
+			const token = signToken(payload, this.accessSecret, this.accessExpiry, {
+				algorithm: 'HS256',
+			})
+
+			return token as unknown as AccessToken
+		} catch (error) {
+			if (
+				error instanceof BadRequestError ||
+				error instanceof ValidationError
+			) {
+				throw error
+			}
+			throw new BadRequestError('Failed to generate access token')
+		}
+	}
+
+	/**
+	 * Generate refresh token
+	 */
+	async generateRefreshToken(
+		payload: Record<string, unknown>,
+	): Promise<RefreshToken> {
+		try {
+			this.validatePayload(payload)
+
+			const token = signToken(payload, this.refreshSecret, this.refreshExpiry, {
+				algorithm: 'HS256',
+			})
+
+			return token as unknown as RefreshToken
+		} catch (error) {
+			if (
+				error instanceof BadRequestError ||
+				error instanceof ValidationError
+			) {
+				throw error
+			}
+			throw new BadRequestError('Failed to generate refresh token')
+		}
+	}
+
+	/**
+	 * Verify access token
+	 */
+	async verifyAccessToken(token: string): Promise<JwtPayload | string> {
+		try {
+			if (!token || typeof token !== 'string') {
+				throw new ValidationError('Access token must be a non-empty string')
+			}
+
+			const cacheKey = `access_${token}`
+			if (this.cache) {
+				const cached = this.cache.get(cacheKey)
+				if (cached && Date.now() - cached.timestamp <= this.cacheTTL) {
+					if (!cached.valid) {
+						throw new UnauthorizedError('Access token is invalid or expired')
+					}
+					return cached.payload
+				}
+			}
+
+			const decoded = verifyToken(token, this.accessSecret)
+
+			if (this.cache) {
+				this.cache.set(cacheKey, {
+					valid: true,
+					payload: decoded,
+					timestamp: Date.now(),
+				})
+			}
+
+			return decoded
+		} catch (error) {
+			if (
+				error instanceof ValidationError ||
+				error instanceof UnauthorizedError
+			) {
+				throw error
+			}
+
+			if (error instanceof Error && error.name === 'TokenExpiredError') {
+				throw new UnauthorizedError('Access token has expired')
+			}
+
+			if (error instanceof Error && error.name === 'JsonWebTokenError') {
+				throw new UnauthorizedError('Access token is invalid')
+			}
+
+			throw new UnauthorizedError('Failed to verify access token')
+		}
+	}
+
+	/**
+	 * Verify refresh token
+	 */
+	async verifyRefreshToken(token: string): Promise<JwtPayload | string> {
+		try {
+			if (!token || typeof token !== 'string') {
+				throw new ValidationError('Refresh token must be a non-empty string')
+			}
+
+			const cacheKey = `refresh_${token}`
+			if (this.cache) {
+				const cached = this.cache.get(cacheKey)
+				if (cached) {
+					if (!cached.valid) {
+						throw new UnauthorizedError('Refresh token is invalid or expired')
+					}
+					return cached.payload
+				}
+			}
+
+			const decoded = verifyToken(token, this.refreshSecret)
+
+			if (this.cache) {
+				this.cache.set(cacheKey, {
+					valid: true,
+					payload: decoded,
+					timestamp: Date.now(),
+				})
+			}
+
+			return decoded
+		} catch (error) {
+			if (
+				error instanceof ValidationError ||
+				error instanceof UnauthorizedError
+			) {
+				throw error
+			}
+
+			if (error instanceof Error && error.name === 'TokenExpiredError') {
+				throw new UnauthorizedError('Refresh token has expired')
+			}
+
+			if (error instanceof Error && error.name === 'JsonWebTokenError') {
+				throw new UnauthorizedError('Refresh token is invalid')
+			}
+
+			throw new UnauthorizedError('Failed to verify refresh token')
+		}
+	}
+
+	/**
+	 * Decode token without verification
+	 */
+	decodeToken(token: string, complete = false): JwtPayload | string | null {
+		try {
+			if (!token || typeof token !== 'string') {
+				throw new ValidationError('Token must be a non-empty string')
+			}
+
+			return jwt.decode(token, { complete }) as JwtPayload | string | null
+		} catch (error) {
+			if (error instanceof ValidationError) {
+				throw error
+			}
+			return null
+		}
+	}
+
+	/**
+	 * Extract token from Authorization header
+	 */
+	extractTokenFromHeader(authHeader: string): string | null {
+		try {
+			if (!authHeader || typeof authHeader !== 'string') {
+				return null
+			}
+
+			const parts = authHeader.split(' ')
+			if (parts.length !== 2 || parts[0] !== 'Bearer') {
+				return null
+			}
+
+			return parts[1]
+		} catch {
+			return null
+		}
+	}
+
+	/**
+	 * Validate token without throwing exceptions
+	 */
+	validateToken(
+		token: string,
+		secret: Secret,
+		_options: TokenValidationOptions = {},
+	): boolean {
+		try {
+			if (!token || typeof token !== 'string') {
+				return false
+			}
+
+			const result = safeVerifyToken(token, secret)
+			return result.valid
+		} catch {
+			return false
+		}
+	}
+
+	/**
+	 * Rotate refresh token
+	 */
+	async rotateRefreshToken(oldToken: string): Promise<RefreshToken> {
+		try {
+			if (!oldToken || typeof oldToken !== 'string') {
+				throw new ValidationError(
+					'Old refresh token must be a non-empty string',
+				)
+			}
+
+			const decoded = await this.verifyRefreshToken(oldToken)
+
+			if (typeof decoded === 'string') {
+				throw new ValidationError(
+					'Invalid token payload — expected JWT payload object',
+				)
+			}
+
+			// Create new payload without issued/expired timestamps
+			const payload: JwtPayload = { ...decoded }
+			delete payload.iat
+			delete payload.exp
+
+			// Generate new refresh token
+			const newToken = signToken(
+				payload,
+				this.refreshSecret,
+				this.refreshExpiry,
+			)
+
+			return newToken as unknown as RefreshToken
+		} catch (error) {
+			if (
+				error instanceof ValidationError ||
+				error instanceof UnauthorizedError
+			) {
+				throw error
+			}
+			throw new BadRequestError('Failed to rotate refresh token')
+		}
+	}
+
+	/**
+	 * Check if token is expired
+	 */
+	isTokenExpired(token: string): boolean {
+		try {
+			const decoded = this.decodeToken(token) as JwtPayload | null
+			if (!decoded || !decoded.exp) {
+				return true
+			}
+
+			const currentTime = Math.floor(Date.now() / 1000)
+			return decoded.exp < currentTime
+		} catch {
+			return true
+		}
+	}
+
+	/**
+	 * Get token expiration date
+	 */
+	getTokenExpiration(token: string): Date | null {
+		try {
+			const decoded = this.decodeToken(token) as JwtPayload | null
+			if (!decoded || !decoded.exp) {
+				return null
+			}
+
+			return new Date(decoded.exp * 1000)
+		} catch {
+			return null
+		}
+	}
+
+	/**
+	 * Clear token cache
+	 */
+	clearCache(): void {
+		this.cache?.clear()
+	}
+
+	/**
+	 * Get cache statistics
+	 */
+	getCacheStats(): { size: number; maxSize: number } | null {
+		if (!this.cache) return null
+
+		// Note: LRUCache doesn't expose internal size, so we return maxSize only
+		return {
+			size: -1, // Size not available from LRUCache
+			maxSize: (this.cache as any).maxSize,
+		}
+	}
+
+	// Private helper methods
+	private validatePayload(payload: Record<string, unknown>): void {
+		if (!payload || typeof payload !== 'object') {
+			throw new ValidationError('Payload must be a non-null object')
+		}
+
+		if (Object.keys(payload).length === 0) {
+			throw new ValidationError('Payload cannot be empty')
+		}
+	}
+}

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

@@ -0,0 +1,32 @@
+const TIME_UNITS: Record<string, number> = {
+	s: 1,
+	m: 60,
+	h: 3600,
+	d: 86400,
+	w: 604800,
+}
+
+export function parseDuration(input: string | number): number {
+	if (typeof input === 'number') return input
+
+	const regex = /(\d+)\s*(s|m|h|d|w)/gi
+	let totalSeconds = 0
+	let match
+
+	while ((match = regex.exec(input)) !== null) {
+		const value = Number.parseInt(match[1], 10)
+		const unit = match[2].toLowerCase()
+
+		if (!TIME_UNITS[unit]) {
+			throw new Error(`Invalid time unit: ${unit}`)
+		}
+
+		totalSeconds += value * TIME_UNITS[unit]
+	}
+
+	if (totalSeconds === 0) {
+		throw new Error(`Invalid expiry format: "${input}"`)
+	}
+
+	return totalSeconds
+}

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

@@ -0,0 +1,31 @@
+import { type Secret, type SignOptions, sign } from 'jsonwebtoken'
+import { parseDuration } from './parseDuration'
+
+function getExpiryTimestamp(seconds: number) {
+	return Math.floor(Date.now() / 1000) + seconds
+}
+
+export const signToken = (
+	payload: Record<string, unknown>,
+	secret: Secret,
+	expiresIn: string | number = '1h',
+	options: SignOptions = {},
+): string => {
+	const seconds = parseDuration(expiresIn)
+
+	if (!seconds || seconds < 10) {
+		throw new Error('Token expiry too small')
+	}
+
+	const tokenPayload = {
+		...payload,
+	}
+
+	if (!('exp' in payload)) tokenPayload.exp = getExpiryTimestamp(seconds)
+	if (!('iat' in payload)) tokenPayload.iat = Math.floor(Date.now() / 1000)
+
+	return sign(tokenPayload, secret, {
+		algorithm: 'HS256',
+		...options,
+	})
+}

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

@@ -0,0 +1,29 @@
+import type { JwtPayload } from 'jsonwebtoken'
+
+// Branded types to prevent token mixing
+export interface AccessTokenBrand {
+	readonly access: unique symbol
+}
+export interface RefreshTokenBrand {
+	readonly refresh: unique symbol
+}
+
+export type AccessToken = string & AccessTokenBrand
+export type RefreshToken = string & RefreshTokenBrand
+
+export interface TokenPair {
+	accessToken: AccessToken
+	refreshToken: RefreshToken
+}
+
+// Enhanced verification result types
+export interface VerificationResult<T = JwtPayload> {
+	valid: boolean
+	payload?: T | string
+	error?: Error
+}
+
+export interface TokenValidationOptions {
+	ignoreExpiration?: boolean
+	ignoreIssuedAt?: boolean
+}

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

@@ -0,0 +1,52 @@
+import type { JwtPayload } from 'node_modules/@types/jsonwebtoken'
+
+export interface TokenRequirements {
+	requiredFields?: string[]
+	forbiddenFields?: string[]
+	validateTypes?: Record<string, 'string' | 'number' | 'boolean'>
+}
+
+export function validateTokenPayload(
+	payload: Record<string, unknown>,
+	rules: TokenRequirements = {
+		requiredFields: ['exp', 'iat'],
+	},
+): { valid: true } | { valid: false; error: string } {
+	const {
+		requiredFields = [],
+		forbiddenFields = [],
+		validateTypes = {},
+	} = rules
+
+	// 1. Required fields
+	for (const field of requiredFields) {
+		if (!(field in payload)) {
+			return { valid: false, error: `Missing required field: ${field}` }
+		}
+	}
+
+	// 2. Forbidden fields
+	for (const field of forbiddenFields) {
+		if (field in payload) {
+			return { valid: false, error: `Forbidden field in token: ${field}` }
+		}
+	}
+
+	// 3. Type validation
+	for (const key in validateTypes) {
+		const expectedType = validateTypes[key]
+		if (key in payload && typeof payload[key] !== expectedType) {
+			return {
+				valid: false,
+				error: `Invalid type for ${key}. Expected ${expectedType}.`,
+			}
+		}
+	}
+
+	return { valid: true }
+}
+
+export function isTokenExpired(payload: JwtPayload): boolean {
+	if (!payload.exp) return true
+	return Date.now() >= payload.exp * 1000
+}

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

@@ -0,0 +1,55 @@
+import type jwt from 'jsonwebtoken'
+import { type JwtPayload, type Secret, verify } from 'jsonwebtoken'
+import type { VerificationResult } from './types'
+
+/**
+ * Verify token (throws if invalid or expired)
+ */
+export const verifyToken = (
+	token: string,
+	secret: Secret,
+): string | JwtPayload => {
+	return verify(token, secret)
+}
+
+/**
+ * Safe verify — never throws, returns structured result
+ */
+export const safeVerifyToken = (
+	token: string,
+	secret: Secret,
+): VerificationResult => {
+	try {
+		const decoded = verify(token, secret)
+		return { valid: true, payload: decoded }
+	} catch (error) {
+		return { valid: false, error: error as Error }
+	}
+}
+
+/**
+ * Verify token with validation options
+ */
+export const verifyTokenWithOptions = (
+	token: string,
+	secret: Secret,
+	options: jwt.VerifyOptions = {},
+): string | JwtPayload => {
+	return verify(token, secret, options)
+}
+
+/**
+ * Safe verify with validation options
+ */
+export const safeVerifyTokenWithOptions = (
+	token: string,
+	secret: Secret,
+	options: jwt.VerifyOptions = {},
+): VerificationResult => {
+	try {
+		const decoded = verify(token, secret, options)
+		return { valid: true, payload: decoded }
+	} catch (error) {
+		return { valid: false, error: error as Error }
+	}
+}

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

@@ -0,0 +1,40 @@
+import { InternalServerError } from '@naman_deep_singh/errors-utils'
+import bcrypt from 'bcryptjs'
+import { ensureValidPassword } from './utils'
+
+/**
+ * Hash a password asynchronously using bcrypt.
+ */
+export const hashPassword = async (
+	password: string,
+	saltRounds = 10,
+): Promise<string> => {
+	try {
+		ensureValidPassword(password)
+		const salt = await bcrypt.genSalt(saltRounds)
+		return bcrypt.hash(password, salt)
+	} catch (_err) {
+		throw new InternalServerError('Password hashing failed')
+	}
+}
+
+export function hashPasswordWithPepper(password: string, pepper: string) {
+	return hashPassword(password + pepper)
+}
+
+/**
+ * Hash a password synchronously using bcrypt.
+ */
+export const hashPasswordSync = (password: string, saltRounds = 10): string => {
+	try {
+		ensureValidPassword(password)
+		const salt = bcrypt.genSaltSync(saltRounds)
+		return bcrypt.hashSync(password, salt)
+	} catch (_error) {
+		throw new InternalServerError('Password hashing failed')
+	}
+}
+
+export function hashPasswordWithPepperSync(password: string, pepper: string) {
+	return hashPasswordSync(password + pepper)
+}

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

@@ -0,0 +1,3 @@
+export * from './hash'
+export * from './strength'
+export * from './verify'