@naman_deep_singh/security 1.3.3 → 1.4.0

package/dist/esm/core/jwt/validateToken.js

@@ -1,31 +1,34 @@
-export function validateTokenPayload(payload, rules = {
-    requiredFields: ['exp', 'iat'],
-}) {
-    const { requiredFields = [], forbiddenFields = [], validateTypes = {}, } = rules;
+import { ValidationError } from '@naman_deep_singh/errors-utils';
+/**
+ * Validates a JWT payload according to the provided rules.
+ * Throws ValidationError if validation fails.
+ */
+export function validateTokenPayload(payload, rules = { requiredFields: ['exp', 'iat'] }) {
+    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}` };
+            throw new ValidationError(`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}` };
+            throw new ValidationError(`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}.`,
-            };
+            throw new ValidationError(`Invalid type for ${key}. Expected ${expectedType}, got ${typeof payload[key]}`);
         }
     }
-    return { valid: true };
 }
+/**
+ * Checks if a JWT payload is expired.
+ * Returns true if expired or missing 'exp'.
+ */
 export function isTokenExpired(payload) {
     if (!payload.exp)
         return true;

package/dist/esm/core/jwt/verify.d.ts

@@ -1,19 +1,18 @@
-import type jwt from 'jsonwebtoken';
-import { type JwtPayload, type Secret } from 'jsonwebtoken';
-import type { VerificationResult } from './types';
+import { type JwtPayload, type Secret, VerifyOptions } from 'jsonwebtoken';
+import { VerificationResult } from './types';
 /**
- * Verify token (throws if invalid or expired)
+ * Verify token (throws UnauthorizedError if invalid or expired)
  */
 export declare const verifyToken: (token: string, secret: Secret) => string | JwtPayload;
 /**
- * Safe verify — never throws, returns structured result
+ * Verify token with options
  */
-export declare const safeVerifyToken: (token: string, secret: Secret) => VerificationResult;
+export declare const verifyTokenWithOptions: (token: string, secret: Secret, options?: VerifyOptions) => string | JwtPayload;
 /**
- * Verify token with validation options
+ * Safe verify — never throws, returns structured result with UnauthorizedError on failure
  */
-export declare const verifyTokenWithOptions: (token: string, secret: Secret, options?: jwt.VerifyOptions) => string | JwtPayload;
+export declare const safeVerifyToken: (token: string, secret: Secret) => VerificationResult;
 /**
- * Safe verify with validation options
+ * Safe verify with options — never throws, returns structured result with UnauthorizedError on failure
  */
-export declare const safeVerifyTokenWithOptions: (token: string, secret: Secret, options?: jwt.VerifyOptions) => VerificationResult;
+export declare const safeVerifyTokenWithOptions: (token: string, secret: Secret, options?: VerifyOptions) => VerificationResult;

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

@@ -1,30 +1,63 @@
 import { verify } from 'jsonwebtoken';
+import { UnauthorizedError } from '@naman_deep_singh/errors-utils';
 /**
- * Verify token (throws if invalid or expired)
+ * Verify token (throws UnauthorizedError if invalid or expired)
  */
 export const verifyToken = (token, secret) => {
-    return verify(token, secret);
+    try {
+        return verify(token, secret);
+    }
+    catch (error) {
+        if (error.name === 'TokenExpiredError') {
+            throw new UnauthorizedError({ message: 'Token has expired' }, error);
+        }
+        if (error.name === 'JsonWebTokenError') {
+            throw new UnauthorizedError({ message: 'Invalid token' }, error);
+        }
+        throw new UnauthorizedError({ message: 'Failed to verify token' }, error);
+    }
 };
 /**
- * Safe verify — never throws, returns structured result
+ * Verify token with options
  */
-export const safeVerifyToken = (token, secret) => {
+export const verifyTokenWithOptions = (token, secret, options = {}) => {
     try {
-        const decoded = verify(token, secret);
-        return { valid: true, payload: decoded };
+        return verify(token, secret, options);
     }
     catch (error) {
-        return { valid: false, error: error };
+        if (error.name === 'TokenExpiredError') {
+            throw new UnauthorizedError({ message: 'Token has expired' }, error);
+        }
+        if (error.name === 'JsonWebTokenError') {
+            throw new UnauthorizedError({ message: 'Invalid token' }, error);
+        }
+        throw new UnauthorizedError({ message: 'Failed to verify token' }, error);
     }
 };
 /**
- * Verify token with validation options
+ * Safe verify — never throws, returns structured result with UnauthorizedError on failure
  */
-export const verifyTokenWithOptions = (token, secret, options = {}) => {
-    return verify(token, secret, options);
+export const safeVerifyToken = (token, secret) => {
+    try {
+        const decoded = verify(token, secret);
+        return { valid: true, payload: decoded };
+    }
+    catch (error) {
+        let wrappedError;
+        if (error.name === 'TokenExpiredError') {
+            wrappedError = new UnauthorizedError({ message: 'Token has expired' }, error);
+        }
+        else if (error.name === 'JsonWebTokenError') {
+            wrappedError = new UnauthorizedError({ message: 'Invalid token' }, error);
+        }
+        else {
+            wrappedError = new UnauthorizedError({ message: '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, secret, options = {}) => {
     try {
@@ -32,6 +65,16 @@ export const safeVerifyTokenWithOptions = (token, secret, options = {}) => {
         return { valid: true, payload: decoded };
     }
     catch (error) {
-        return { valid: false, error: error };
+        let wrappedError;
+        if (error.name === 'TokenExpiredError') {
+            wrappedError = new UnauthorizedError({ message: 'Token has expired' }, error);
+        }
+        else if (error.name === 'JsonWebTokenError') {
+            wrappedError = new UnauthorizedError({ message: 'Invalid token' }, error);
+        }
+        else {
+            wrappedError = new UnauthorizedError({ message: 'Failed to verify token' }, error);
+        }
+        return { valid: false, error: wrappedError };
     }
 };

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

@@ -11,7 +11,7 @@ export const hashPassword = async (password, saltRounds = 10) => {
         return bcrypt.hash(password, salt);
     }
     catch (_err) {
-        throw new InternalServerError('Password hashing failed');
+        throw new InternalServerError({ message: 'Password hashing failed' });
     }
 };
 export function hashPasswordWithPepper(password, pepper) {
@@ -27,7 +27,7 @@ export const hashPasswordSync = (password, saltRounds = 10) => {
         return bcrypt.hashSync(password, salt);
     }
     catch (_error) {
-        throw new InternalServerError('Password hashing failed');
+        throw new InternalServerError({ message: 'Password hashing failed' });
     }
 };
 export function hashPasswordWithPepperSync(password, pepper) {

package/dist/esm/core/password/passwordManager.d.ts

@@ -23,7 +23,7 @@ export declare class PasswordManager implements IPasswordManager {
      */
     checkStrength(password: string): PasswordStrength;
     /**
-     * Check if password hash needs upgrade (different salt rounds)
+     * Check if password hash needs upgrade (saltRounds change)
      */
     needsUpgrade(_hash: string, _currentConfig: PasswordConfig): boolean;
 }

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

@@ -21,25 +21,20 @@ export class PasswordManager {
     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);
+            let finalSalt = salt;
+            if (!finalSalt) {
+                finalSalt = await bcrypt.genSalt(saltRounds);
             }
-            const hash = await bcrypt.hash(password, passwordSalt);
-            return {
-                hash,
-                salt: passwordSalt,
-            };
+            const hash = await bcrypt.hash(password, finalSalt);
+            return { hash, salt: finalSalt };
         }
         catch (error) {
-            if (error instanceof BadRequestError ||
-                error instanceof ValidationError) {
+            if (error instanceof BadRequestError || error instanceof ValidationError) {
                 throw error;
             }
-            throw new BadRequestError('Failed to hash password');
+            throw new BadRequestError({ message: 'Failed to hash password' }, error instanceof Error ? error : undefined);
         }
     }
     /**
@@ -47,19 +42,12 @@ export class PasswordManager {
      */
     async verify(password, hash, salt) {
         try {
-            if (!password || !hash || !salt) {
+            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;
+            // bcrypt compare works directly with hash
+            return await bcrypt.compare(password, hash);
         }
-        catch (_error) {
+        catch {
             return false;
         }
     }
@@ -69,7 +57,7 @@ export class PasswordManager {
     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}`);
+            throw new ValidationError({ message: `Password length must be between ${config.minLength} and ${config.maxLength}` });
         }
         let charset = 'abcdefghijklmnopqrstuvwxyz';
         if (config.requireUppercase)
@@ -78,24 +66,20 @@ export class PasswordManager {
             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;
     }
     /**
@@ -104,45 +88,27 @@ export class PasswordManager {
     validate(password, config = {}) {
         const finalConfig = { ...this.defaultConfig, ...config };
         const errors = [];
-        // 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) {
-            errors.push(`Password must be at least ${finalConfig.minLength} characters long`);
-        }
-        if (password.length > finalConfig.maxLength) {
+        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`);
-        }
-        // 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)) {
+                if (!rule.test(password))
                     errors.push(rule.message);
-                }
             });
         }
-        const strength = this.checkStrength(password);
-        const isValid = errors.length === 0;
-        return {
-            isValid,
-            errors,
-            strength,
-        };
+        return { isValid: errors.length === 0, errors, strength: this.checkStrength(password) };
     }
     /**
      * Check password strength
@@ -152,26 +118,20 @@ export class PasswordManager {
         let score = 0;
         const feedback = [];
         const suggestions = [];
-        /* ---------------- 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) {
+        else if (entropy < 36)
+            score++;
+        else if (entropy < 60)
             score += 2;
-        }
-        else {
+        else
             score += 3;
-        }
-        /* ---------------- Length scoring ---------------- */
         if (password.length >= 12)
             score++;
         if (password.length >= 16)
             score++;
-        /* ---------------- Character variety ---------------- */
         if (/[a-z]/.test(password))
             score++;
         if (/[A-Z]/.test(password))
@@ -180,7 +140,6 @@ export class PasswordManager {
             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');
@@ -197,15 +156,12 @@ export class PasswordManager {
             score--;
             feedback.push('Avoid sequential patterns');
         }
-        /* ---------------- Common passwords ---------------- */
         const commonPasswords = ['password', '123456', 'qwerty', 'admin', 'letmein'];
         if (commonPasswords.some((common) => password.toLowerCase().includes(common))) {
             score = 0;
             feedback.push('Avoid common passwords');
         }
-        /* ---------------- Clamp score ---------------- */
         score = Math.max(0, Math.min(4, score));
-        /* ---------------- Strength label ---------------- */
         let label;
         switch (score) {
             case 0:
@@ -228,22 +184,14 @@ export class PasswordManager {
                 label = 'strong';
                 suggestions.push('Your password is very secure');
                 break;
-            default:
-                label = 'very-weak';
+            default: 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, _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.js

@@ -1,17 +1,17 @@
 import { BadRequestError, ValidationError, } from '@naman_deep_singh/errors-utils';
 export const isPasswordStrong = (password, options = {}) => {
     if (!password)
-        throw new BadRequestError('Invalid password provided');
+        throw new BadRequestError({ message: 'Invalid password provided' });
     const { minLength = 8, requireUppercase = true, requireLowercase = true, requireNumbers = true, requireSymbols = false, } = 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({ message: 'Password must include uppercase letters' });
     if (requireLowercase && !/[a-z]/.test(password))
-        throw new ValidationError('Password must include lowercase letters');
+        throw new ValidationError({ message: 'Password must include lowercase letters' });
     if (requireNumbers && !/[0-9]/.test(password))
-        throw new ValidationError('Password must include numbers');
+        throw new ValidationError({ message: 'Password must include numbers' });
     if (requireSymbols && !/[^A-Za-z0-9]/.test(password))
-        throw new ValidationError('Password must include symbols');
+        throw new ValidationError({ message: 'Password must include symbols' });
     return true;
 };

package/dist/esm/core/password/utils.d.ts

@@ -1,4 +1,16 @@
+/**
+ * Ensure password is a valid non-empty string
+ */
 export declare function ensureValidPassword(password: string): void;
+/**
+ * Timing-safe comparison between two strings
+ */
 export declare function safeCompare(a: string, b: string): boolean;
+/**
+ * Estimate password entropy based on character pool
+ */
 export declare function estimatePasswordEntropy(password: string): number;
+/**
+ * Normalize password string to a consistent form
+ */
 export declare function normalizePassword(password: string): string;

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

@@ -1,10 +1,16 @@
 import crypto from 'crypto';
 import { BadRequestError } from '@naman_deep_singh/errors-utils';
+/**
+ * Ensure password is a valid non-empty string
+ */
 export function ensureValidPassword(password) {
     if (!password || typeof password !== 'string') {
-        throw new BadRequestError('Invalid password provided');
+        throw new BadRequestError({ message: 'Invalid password provided' });
     }
 }
+/**
+ * Timing-safe comparison between two strings
+ */
 export function safeCompare(a, b) {
     const bufA = Buffer.from(a);
     const bufB = Buffer.from(b);
@@ -12,6 +18,9 @@ export function safeCompare(a, b) {
         return false;
     return crypto.timingSafeEqual(bufA, bufB);
 }
+/**
+ * Estimate password entropy based on character pool
+ */
 export function estimatePasswordEntropy(password) {
     let pool = 0;
     if (/[a-z]/.test(password))
@@ -22,8 +31,14 @@ export function estimatePasswordEntropy(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) {
     return password.normalize('NFKC');
 }

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

@@ -7,11 +7,11 @@ export const verifyPassword = async (password, hash) => {
     try {
         const result = await bcrypt.compare(password, hash);
         if (!result)
-            throw new UnauthorizedError('Password verification failed');
+            throw new UnauthorizedError({ message: 'Password verification failed' });
         return result;
     }
     catch {
-        throw new UnauthorizedError('Password verification failed');
+        throw new UnauthorizedError({ message: 'Password verification failed' });
     }
 };
 export async function verifyPasswordWithPepper(password, pepper, hash) {
@@ -24,11 +24,11 @@ export const verifyPasswordSync = (password, hash) => {
     try {
         const result = bcrypt.compareSync(password, hash);
         if (!result)
-            throw new UnauthorizedError('Password verification failed');
+            throw new UnauthorizedError({ message: 'Password verification failed' });
         return result;
     }
     catch (_error) {
-        throw new UnauthorizedError('Password verification failed');
+        throw new UnauthorizedError({ message: 'Password verification failed' });
     }
 };
 export async function verifyPasswordWithPepperSync(password, pepper, hash) {

package/dist/esm/index.d.ts

@@ -21,16 +21,11 @@ declare const _default: {
     generateTokens: (payload: Record<string, unknown>, accessSecret: import("node_modules/@types/jsonwebtoken").Secret, refreshSecret: import("node_modules/@types/jsonwebtoken").Secret, accessExpiry?: string | number, refreshExpiry?: string | number) => JWTUtils.TokenPair;
     parseDuration(input: string | number): number;
     signToken: (payload: Record<string, unknown>, secret: import("node_modules/@types/jsonwebtoken").Secret, expiresIn?: string | number, options?: import("node_modules/@types/jsonwebtoken").SignOptions) => string;
-    validateTokenPayload(payload: Record<string, unknown>, rules?: JWTUtils.TokenRequirements): {
-        valid: true;
-    } | {
-        valid: false;
-        error: string;
-    };
+    validateTokenPayload(payload: Record<string, unknown>, rules?: JWTUtils.TokenRequirements): void;
     isTokenExpired(payload: import("node_modules/@types/jsonwebtoken").JwtPayload): boolean;
     verifyToken: (token: string, secret: import("node_modules/@types/jsonwebtoken").Secret) => string | import("node_modules/@types/jsonwebtoken").JwtPayload;
-    safeVerifyToken: (token: string, secret: import("node_modules/@types/jsonwebtoken").Secret) => JWTUtils.VerificationResult;
     verifyTokenWithOptions: (token: string, secret: import("node_modules/@types/jsonwebtoken").Secret, options?: import("node_modules/@types/jsonwebtoken").VerifyOptions) => string | import("node_modules/@types/jsonwebtoken").JwtPayload;
+    safeVerifyToken: (token: string, secret: import("node_modules/@types/jsonwebtoken").Secret) => JWTUtils.VerificationResult;
     safeVerifyTokenWithOptions: (token: string, secret: import("node_modules/@types/jsonwebtoken").Secret, options?: import("node_modules/@types/jsonwebtoken").VerifyOptions) => JWTUtils.VerificationResult;
     hashPasswordWithPepper(password: string, pepper: string): Promise<string>;
     hashPasswordWithPepperSync(password: string, pepper: string): string;

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

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