@naman_deep_singh/security 1.2.0 → 1.3.1

package/dist/esm/core/password/passwordManager.js

@@ -0,0 +1,236 @@
+import crypto from 'crypto';
+import bcrypt from 'bcryptjs';
+import { BadRequestError, ValidationError, } from '@naman_deep_singh/errors-utils';
+import { ensureValidPassword, estimatePasswordEntropy } from './utils';
+export class PasswordManager {
+    constructor(config = {}) {
+        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, salt) {
+        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);
+            }
+            const hash = await bcrypt.hash(password, passwordSalt);
+            return {
+                hash,
+                salt: passwordSalt,
+            };
+        }
+        catch (error) {
+            if (error instanceof BadRequestError ||
+                error instanceof ValidationError) {
+                throw error;
+            }
+            throw new BadRequestError('Failed to hash password');
+        }
+    }
+    /**
+     * Verify password against hash and salt
+     */
+    async verify(password, hash, salt) {
+        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;
+            }
+            return isValid;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+    /**
+     * Generate a random password
+     */
+    generate(length = 16, options = {}) {
+        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}`);
+        }
+        let charset = 'abcdefghijklmnopqrstuvwxyz';
+        if (config.requireUppercase)
+            charset += 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+        if (config.requireNumbers)
+            charset += '0123456789';
+        if (config.requireSpecialChars)
+            charset += '!@#$%^&*()_+-=[]{}|;:,.<>?';
+        let password = '';
+        const randomBytes = crypto.randomBytes(length);
+        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)) {
+            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, config = {}) {
+        const finalConfig = { ...this.defaultConfig, ...config };
+        const errors = [];
+        // Basic validation
+        if (!password || typeof password !== 'string') {
+            errors.push('Password must be a non-empty string');
+        }
+        // Length validation
+        if (password.length < finalConfig.minLength) {
+            errors.push(`Password must be at least ${finalConfig.minLength} characters long`);
+        }
+        if (password.length > finalConfig.maxLength) {
+            errors.push(`Password must not exceed ${finalConfig.maxLength} characters`);
+        }
+        // Complexity requirements
+        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');
+        }
+        // Custom rules
+        if (finalConfig.customRules) {
+            finalConfig.customRules.forEach((rule) => {
+                if (!rule.test(password)) {
+                    errors.push(rule.message);
+                }
+            });
+        }
+        const strength = this.checkStrength(password);
+        const isValid = errors.length === 0;
+        return {
+            isValid,
+            errors,
+            strength,
+        };
+    }
+    /**
+     * Check password strength
+     */
+    checkStrength(password) {
+        const entropy = estimatePasswordEntropy(password);
+        let score = 0;
+        const feedback = [];
+        const suggestions = [];
+        // Length scoring
+        if (password.length >= 8)
+            score++;
+        if (password.length >= 12)
+            score++;
+        if (password.length >= 16)
+            score++;
+        // Character variety scoring
+        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++;
+        // Common patterns deduction
+        if (/^[A-Za-z]+$/.test(password)) {
+            score--;
+            feedback.push('Consider adding numbers and 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 check
+        const commonPasswords = ['password', '123456', 'qwerty', 'admin', 'letmein'];
+        if (commonPasswords.some((common) => password.toLowerCase().includes(common))) {
+            score = 0;
+            feedback.push('Avoid common passwords');
+        }
+        // Clamp score and determine label
+        score = Math.max(0, Math.min(4, score));
+        let 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 adding more length or character types');
+                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 (different salt rounds)
+     */
+    needsUpgrade(hash, currentConfig) {
+        // 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/dist/esm/core/password/strength.d.ts

@@ -1,2 +1,2 @@
-import { PasswordStrengthOptions } from "./types";
+import type { PasswordStrengthOptions } from './types';
 export declare const isPasswordStrong: (password: string, options?: PasswordStrengthOptions) => boolean;

package/dist/esm/core/password/strength.js

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

package/dist/esm/core/password/utils.js

@@ -1,7 +1,7 @@
-import crypto from "crypto";
-import { BadRequestError } from "@naman_deep_singh/errors-utils";
+import crypto from 'crypto';
+import { BadRequestError } from '@naman_deep_singh/errors-utils';
 export function ensureValidPassword(password) {
-    if (!password || typeof password !== "string") {
+    if (!password || typeof password !== 'string') {
         throw new BadRequestError('Invalid password provided');
     }
 }
@@ -25,5 +25,5 @@ export function estimatePasswordEntropy(password) {
     return password.length * Math.log2(pool);
 }
 export function normalizePassword(password) {
-    return password.normalize("NFKC");
+    return password.normalize('NFKC');
 }

package/dist/esm/core/password/verify.js

@@ -1,5 +1,5 @@
-import bcrypt from "bcryptjs";
-import { UnauthorizedError } from "@naman_deep_singh/errors-utils";
+import { UnauthorizedError } from '@naman_deep_singh/errors-utils';
+import bcrypt from 'bcryptjs';
 /**
  * Compare a password with a stored hash asynchronously.
  */

package/dist/esm/index.d.ts

@@ -1,8 +1,9 @@
-export * from "./core/password";
-export * from "./core/jwt";
-export * from "./core/crypto";
-export { BadRequestError, UnauthorizedError, ValidationError, InternalServerError } from "@naman_deep_singh/errors-utils";
-import * as JWTUtils from "./core/jwt";
+export * from './core/password';
+export * from './core/jwt';
+export * from './core/crypto';
+export { BadRequestError, UnauthorizedError, ValidationError, InternalServerError, } from '@naman_deep_singh/errors-utils';
+import * as CryptoUtils from './core/crypto';
+import * as JWTUtils from './core/jwt';
 declare const _default: {
     decrypt: (data: string, secret: string) => string;
     encrypt: (text: string, secret: string) => string;
@@ -10,6 +11,9 @@ declare const _default: {
     hmacVerify: (message: string, secret: string, signature: string) => boolean;
     randomToken: (length?: number) => string;
     generateStrongPassword: (length?: number) => string;
+    CryptoManager: typeof CryptoUtils.CryptoManager;
+    createCryptoManager: (config?: CryptoUtils.CryptoManagerConfig) => CryptoUtils.CryptoManager;
+    cryptoManager: CryptoUtils.CryptoManager;
     decodeToken(token: string): null | string | import("node_modules/@types/jsonwebtoken").JwtPayload;
     decodeTokenStrict(token: string): import("node_modules/@types/jsonwebtoken").JwtPayload;
     extractToken(sources: JWTUtils.TokenSources): string | null;

package/dist/esm/index.js

@@ -1,11 +1,11 @@
-export * from "./core/password";
-export * from "./core/jwt";
-export * from "./core/crypto";
+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 PasswordUtils from "./core/password";
-import * as JWTUtils from "./core/jwt";
-import * as CryptoUtils from "./core/crypto";
+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,

package/dist/esm/interfaces/jwt.interface.d.ts

@@ -0,0 +1,47 @@
+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/dist/esm/interfaces/jwt.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/interfaces/password.interface.d.ts

@@ -0,0 +1,60 @@
+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;
+    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/dist/esm/interfaces/password.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/types/core/crypto/cryptoManager.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Configuration options for CryptoManager
+ */
+export interface CryptoManagerConfig {
+    defaultAlgorithm?: string;
+    defaultEncoding?: BufferEncoding;
+    hmacAlgorithm?: string;
+}
+/**
+ * CryptoManager - Class-based wrapper for all cryptographic operations
+ * Provides a consistent interface for encryption, decryption, HMAC generation, and secure random generation
+ */
+export declare class CryptoManager {
+    private config;
+    constructor(config?: CryptoManagerConfig);
+    /**
+     * Update configuration
+     */
+    updateConfig(config: Partial<CryptoManagerConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Required<CryptoManagerConfig>;
+    /**
+     * Encrypt data using the default or specified algorithm
+     */
+    encrypt(plaintext: string, key: string, options?: {
+        algorithm?: string;
+        encoding?: BufferEncoding;
+        iv?: string;
+    }): string;
+    /**
+     * Decrypt data using the default or specified algorithm
+     */
+    decrypt(encryptedData: string, key: string, options?: {
+        algorithm?: string;
+        encoding?: BufferEncoding;
+        iv?: string;
+    }): string;
+    /**
+     * Generate HMAC signature
+     */
+    generateHmac(data: string, secret: string, options?: {
+        algorithm?: string;
+        encoding?: BufferEncoding;
+    }): string;
+    /**
+     * Generate cryptographically secure random bytes
+     */
+    generateSecureRandom(length: number, encoding?: BufferEncoding): string;
+    /**
+     * Verify HMAC signature
+     */
+    verifyHmac(data: string, secret: string, signature: string, options?: {
+        algorithm?: string;
+        encoding?: BufferEncoding;
+    }): boolean;
+    /**
+     * Create a key derivation function using PBKDF2
+     */
+    deriveKey(password: string, salt: string, iterations?: number, keyLength?: number): Promise<string>;
+    /**
+     * Hash data using SHA-256
+     */
+    sha256(data: string, encoding?: BufferEncoding): string;
+    /**
+     * Hash data using SHA-512
+     */
+    sha512(data: string, encoding?: BufferEncoding): string;
+    /**
+     * Generate a secure key pair for asymmetric encryption
+     */
+    generateKeyPair(options?: {
+        modulusLength?: number;
+        publicKeyEncoding?: {
+            type: string;
+            format: string;
+        };
+        privateKeyEncoding?: {
+            type: string;
+            format: string;
+        };
+    }): Promise<{
+        publicKey: string;
+        privateKey: string;
+    }>;
+    /**
+     * Encrypt data using RSA public key
+     */
+    rsaEncrypt(data: string, publicKey: string): Promise<string>;
+    /**
+     * Decrypt data using RSA private key
+     */
+    rsaDecrypt(encryptedData: string, privateKey: string): Promise<string>;
+    /**
+     * Create digital signature using RSA private key
+     */
+    rsaSign(data: string, privateKey: string, algorithm?: string): Promise<string>;
+    /**
+     * Verify digital signature using RSA public key
+     */
+    rsaVerify(data: string, signature: string, publicKey: string, algorithm?: string): Promise<boolean>;
+}
+/**
+ * Create a CryptoManager instance with default configuration
+ */
+export declare const createCryptoManager: (config?: CryptoManagerConfig) => CryptoManager;
+/**
+ * Default CryptoManager instance
+ */
+export declare const cryptoManager: CryptoManager;

package/dist/types/core/crypto/index.d.ts

@@ -1,4 +1,5 @@
-export * from "./decrypt";
-export * from "./encrypt";
-export * from "./hmac";
-export * from "./random";
+export { decrypt } from './decrypt';
+export { encrypt } from './encrypt';
+export { hmacSign, hmacVerify } from './hmac';
+export { randomToken, generateStrongPassword } from './random';
+export * from './cryptoManager';

package/dist/types/core/jwt/decode.d.ts

@@ -1,4 +1,4 @@
-import { JwtPayload } from "jsonwebtoken";
+import { type JwtPayload } from 'jsonwebtoken';
 /**
  * Flexible decode
  * Returns: null | string | JwtPayload

package/dist/types/core/jwt/generateTokens.d.ts

@@ -1,4 +1,4 @@
-import { Secret } from "jsonwebtoken";
-import { RefreshToken, TokenPair } from "./types";
+import { type Secret } from 'jsonwebtoken';
+import type { RefreshToken, TokenPair } from './types';
 export declare const generateTokens: (payload: Record<string, unknown>, accessSecret: Secret, refreshSecret: Secret, accessExpiry?: string | number, refreshExpiry?: string | number) => TokenPair;
 export declare function rotateRefreshToken(oldToken: string, secret: Secret): RefreshToken;

package/dist/types/core/jwt/index.d.ts

@@ -1,8 +1,8 @@
-export * from "./decode";
-export * from "./extractToken";
-export * from "./generateTokens";
-export * from "./parseDuration";
-export * from "./signToken";
-export * from "./types";
-export * from "./validateToken";
-export * from "./verify";
+export * from './decode';
+export * from './extractToken';
+export * from './generateTokens';
+export * from './parseDuration';
+export * from './signToken';
+export * from './types';
+export * from './validateToken';
+export * from './verify';

package/dist/types/core/jwt/jwtManager.d.ts

@@ -0,0 +1,67 @@
+import { type JwtPayload, type Secret } from 'jsonwebtoken';
+import type { AccessToken, ITokenManager, JWTConfig, RefreshToken, TokenPair, TokenValidationOptions } from '../../interfaces/jwt.interface';
+export declare class JWTManager implements ITokenManager {
+    private accessSecret;
+    private refreshSecret;
+    private accessExpiry;
+    private refreshExpiry;
+    private cache?;
+    private cacheTTL;
+    constructor(config: JWTConfig);
+    /**
+     * Generate both access and refresh tokens
+     */
+    generateTokens(payload: Record<string, unknown>): Promise<TokenPair>;
+    /**
+     * Generate access token
+     */
+    generateAccessToken(payload: Record<string, unknown>): Promise<AccessToken>;
+    /**
+     * Generate refresh token
+     */
+    generateRefreshToken(payload: Record<string, unknown>): Promise<RefreshToken>;
+    /**
+     * Verify access token
+     */
+    verifyAccessToken(token: string): Promise<JwtPayload | string>;
+    /**
+     * Verify refresh token
+     */
+    verifyRefreshToken(token: string): Promise<JwtPayload | string>;
+    /**
+     * Decode token without verification
+     */
+    decodeToken(token: string, complete?: boolean): JwtPayload | string | null;
+    /**
+     * Extract token from Authorization header
+     */
+    extractTokenFromHeader(authHeader: string): string | null;
+    /**
+     * Validate token without throwing exceptions
+     */
+    validateToken(token: string, secret: Secret, options?: TokenValidationOptions): boolean;
+    /**
+     * Rotate refresh token
+     */
+    rotateRefreshToken(oldToken: string): Promise<RefreshToken>;
+    /**
+     * Check if token is expired
+     */
+    isTokenExpired(token: string): boolean;
+    /**
+     * Get token expiration date
+     */
+    getTokenExpiration(token: string): Date | null;
+    /**
+     * Clear token cache
+     */
+    clearCache(): void;
+    /**
+     * Get cache statistics
+     */
+    getCacheStats(): {
+        size: number;
+        maxSize: number;
+    } | null;
+    private validatePayload;
+}