ts-packages 1.0.0 → 3.0.0

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

@@ -0,0 +1,233 @@
+import jwt, { type JwtPayload, type Secret } from 'jsonwebtoken'
+
+import type {
+	AccessToken,
+	ITokenManager,
+	JWTConfig,
+	RefreshToken,
+	TokenPair,
+} from '../../interfaces/jwt.interface'
+import { signToken } from './signToken'
+import { safeVerifyToken } 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; 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
+
+		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(
+				{ reason: 'Failed to generate tokens' },
+				error instanceof Error ? error : undefined,
+			)
+		}
+	}
+
+	/** 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(
+				{ reason: 'Failed to generate access token' },
+				error instanceof Error ? error : undefined,
+			)
+		}
+	}
+
+	/** 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(
+				{ reason: 'Failed to generate refresh token' },
+				error instanceof Error ? error : undefined,
+			)
+		}
+	}
+
+	/** Verify access token */
+	async verifyAccessToken(token: string): Promise<JwtPayload> {
+		return this.verifyTokenWithCache(token, this.accessSecret, 'access')
+	}
+
+	/** Verify refresh token */
+	async verifyRefreshToken(token: string): Promise<JwtPayload> {
+		return this.verifyTokenWithCache(token, this.refreshSecret, 'refresh')
+	}
+
+	/** Decode token without verification */
+	decodeToken(token: string, complete = false): JwtPayload | string | null {
+		if (!token || typeof token !== 'string') return null
+		return jwt.decode(token, { complete }) as JwtPayload | string | null
+	}
+
+	/** Extract token from Authorization header */
+	extractTokenFromHeader(authHeader: string): string | null {
+		if (!authHeader || typeof authHeader !== 'string') return null
+		const parts = authHeader.split(' ')
+		if (parts.length !== 2 || parts[0] !== 'Bearer') return null
+		return parts[1]
+	}
+
+	/** Validate token without throwing exceptions */
+	validateToken(token: string, secret: Secret): boolean {
+		if (!token || typeof token !== 'string') return false
+		return safeVerifyToken(token, secret).valid
+	}
+
+	/** Rotate refresh token */
+	async rotateRefreshToken(oldToken: string): Promise<RefreshToken> {
+		if (!oldToken || typeof oldToken !== 'string') {
+			throw new ValidationError({
+				reason: 'Old refresh token must be a non-empty string',
+			})
+		}
+
+		const decoded = await this.verifyRefreshToken(oldToken)
+		const payload: JwtPayload = { ...decoded }
+		delete payload.iat
+		delete payload.exp
+
+		const newToken = signToken(payload, this.refreshSecret, this.refreshExpiry)
+		return newToken as unknown as RefreshToken
+	}
+
+	/** Check if token is expired */
+	isTokenExpired(token: string): boolean {
+		try {
+			const decoded = this.decodeToken(token) as JwtPayload | null
+			if (!decoded || !decoded.exp) return true
+			return decoded.exp < Math.floor(Date.now() / 1000)
+		} 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
+		return { size: -1, maxSize: (this.cache as any).maxSize }
+	}
+
+	/** Private helper methods */
+	private validatePayload(payload: Record<string, unknown>): void {
+		if (!payload || typeof payload !== 'object') {
+			throw new ValidationError({
+				reason: 'Payload must be a non-null object',
+			})
+		}
+		if (Object.keys(payload).length === 0) {
+			throw new ValidationError({ reason: 'Payload cannot be empty' })
+		}
+	}
+
+	private async verifyTokenWithCache(
+		token: string,
+		secret: Secret,
+		type: 'access' | 'refresh',
+	): Promise<JwtPayload> {
+		if (!token || typeof token !== 'string') {
+			throw new ValidationError({
+				reason: `${type} token must be a non-empty string`,
+			})
+		}
+
+		const cacheKey = `${type}_${token}`
+		if (this.cache) {
+			const cached = this.cache.get(cacheKey)
+			if (cached && Date.now() - cached.timestamp <= this.cacheTTL) {
+				if (!cached.valid)
+					throw new UnauthorizedError({
+						reason: `${type} token is invalid or expired`,
+					})
+				return cached.payload
+			}
+		}
+
+		const { valid, payload, error } = safeVerifyToken(token, secret)
+		if (!valid || !payload || typeof payload === 'string') {
+			this.cache?.set(cacheKey, {
+				valid: false,
+				payload: {} as JwtPayload,
+				timestamp: Date.now(),
+			})
+			throw new UnauthorizedError({
+				reason: `${type} token is invalid or expired`,
+				cause: error,
+			})
+		}
+
+		this.cache?.set(cacheKey, { valid: true, payload, timestamp: Date.now() })
+		return payload
+	}
+}

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

@@ -0,0 +1,34 @@
+import { ValidationError } from '@naman_deep_singh/errors-utils'
+
+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 ValidationError({ reason: `Invalid time unit: ${unit}` })
+		}
+
+		totalSeconds += value * TIME_UNITS[unit]
+	}
+
+	if (totalSeconds === 0) {
+		throw new ValidationError({ reason: `Invalid expiry format: "${input}"` })
+	}
+
+	return totalSeconds
+}

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

@@ -0,0 +1,32 @@
+import { ValidationError } from '@naman_deep_singh/errors-utils'
+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 ValidationError({ reason: '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,60 @@
+import { ValidationError } from '@naman_deep_singh/errors-utils'
+import type { JwtPayload } from 'jsonwebtoken'
+
+export interface TokenRequirements {
+	requiredFields?: string[]
+	forbiddenFields?: string[]
+	validateTypes?: Record<string, 'string' | 'number' | 'boolean'>
+}
+
+/**
+ * Validates a JWT payload according to the provided rules.
+ * Throws ValidationError if validation fails.
+ */
+export function validateTokenPayload(
+	payload: Record<string, unknown>,
+	rules: TokenRequirements = { requiredFields: ['exp', 'iat'] },
+): void {
+	const {
+		requiredFields = [],
+		forbiddenFields = [],
+		validateTypes = {},
+	} = rules
+
+	// 1. Required fields
+	for (const field of requiredFields) {
+		if (!(field in payload)) {
+			throw new ValidationError({
+				reason: `Missing required field: ${field}`,
+			})
+		}
+	}
+
+	// 2. Forbidden fields
+	for (const field of forbiddenFields) {
+		if (field in payload) {
+			throw new ValidationError({
+				reason: `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) {
+			throw new ValidationError({
+				reason: `Invalid type for ${key}. Expected ${expectedType}, got ${typeof payload[key]}`,
+			})
+		}
+	}
+}
+
+/**
+ * Checks if a JWT payload is expired.
+ * Returns true if expired or missing 'exp'.
+ */
+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,117 @@
+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 UnauthorizedError if invalid or expired)
+ */
+export const verifyToken = (
+	token: string,
+	secret: Secret,
+): string | JwtPayload => {
+	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)
+	}
+}
+
+/**
+ * Verify token with options
+ */
+export const verifyTokenWithOptions = (
+	token: string,
+	secret: Secret,
+	options: VerifyOptions = {},
+): string | JwtPayload => {
+	try {
+		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)
+	}
+}
+
+/**
+ * Safe verify — never throws, returns structured result with UnauthorizedError on failure
+ */
+export const safeVerifyToken = (
+	token: string,
+	secret: Secret,
+): 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 options — never throws, returns structured result with UnauthorizedError on failure
+ */
+export const safeVerifyTokenWithOptions = (
+	token: string,
+	secret: Secret,
+	options: VerifyOptions = {},
+): VerificationResult => {
+	try {
+		const decoded = verify(token, secret, options)
+		return { valid: true, payload: decoded }
+	} 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

@@ -0,0 +1,46 @@
+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 (error) {
+		throw new InternalServerError(
+			{ reason: 'Password hashing failed' },
+			error instanceof Error ? error : undefined,
+		)
+	}
+}
+
+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(
+			{ reason: 'Password hashing failed' },
+			error instanceof Error ? error : undefined,
+		)
+	}
+}
+
+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'