fix(validation): improve constructor validation and error handling 🔧

- Add algorithm parameter validation
- Fix validation order to prevent masked error messages
- Fix whitespace handling in expireIn parameter
- Improve base64 string validation
- Increase test coverage to 98.37%

Author: NeaByteLab

CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.4.5] - 2025-09-06
+
+### Fixed
+- Added validation for encryption algorithm parameter
+- Base64 string validation in token processing
+- Constructor validation order to prevent masked error messages
+- Test coverage increased from 98.32% to 98.37%
+- Whitespace handling in `expireIn` parameter (e.g., " 1h " now works)
+
+### Changed
+- Error message specificity and validation order
+- Parameter validation across all constructor options
+- Added tests for previously uncovered validation paths
+
+### Technical
+- All options now validated before processing to surface specific errors
+- Added `.trim()` to handle whitespace in time strings
+- Added `validateAlgorithm` method with proper error messages
+
+---
+
 ## [1.4.4] - 2025-09-06
 
 ### Changed

README.md

@@ -3,7 +3,7 @@
 ![npm version](https://img.shields.io/npm/v/@neabyte/secure-jwt)
 ![node version](https://img.shields.io/node/v/@neabyte/secure-jwt)
 ![typescript version](https://img.shields.io/badge/typeScript-5.9.2-blue.svg)
-![coverage](https://img.shields.io/badge/coverage-98.32%25-brightgreen)
+![coverage](https://img.shields.io/badge/coverage-98.37%25-brightgreen)
 ![license](https://img.shields.io/npm/l/@neabyte/secure-jwt.svg)
 
 A secure JWT library implementation with multiple encryption algorithms, zero dependencies, and built-in security for Node.js applications. Designed for high performance and reliability with TypeScript support.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@neabyte/secure-jwt",
-  "description": "Secure JWT with AES-256-GCM & ChaCha20-Poly1305 encryption, built-in caching, tamper detection, and TypeScript support",
-  "version": "1.4.4",
+  "description": "A secure JWT library with multiple encryption algorithms, zero dependencies, and built-in security for Node.js applications.",
+  "version": "1.4.5",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

src/index.ts

@@ -49,6 +49,9 @@ export default class SecureJWT {
     ErrorHandler.validateOptions(options)
     ErrorHandler.validateExpireIn(options.expireIn)
     ErrorHandler.validateSecret(options.secret)
+    if (options.algorithm !== undefined) {
+      ErrorHandler.validateAlgorithm(options.algorithm)
+    }
     if (options.keyDerivation !== undefined) {
       ErrorHandler.validateKeyDerivation(options.keyDerivation)
     }

src/utils/ErrorHandler.ts

@@ -10,7 +10,7 @@ import {
   VersionMismatchError,
   getErrorMessage
 } from '@utils/index'
-import type { KeyDerivationAlgo } from '@interfaces/index'
+import type { EncryptionAlgo, KeyDerivationAlgo } from '@interfaces/index'
 
 /**
  * Handles errors and validates data for JWT operations
@@ -185,6 +185,24 @@ export class ErrorHandler {
     }
   }
 
+  /**
+   * Checks if encryption algorithm is valid
+   * @param algorithm - Encryption algorithm to check
+   * @throws {ValidationError} When algorithm is invalid
+   */
+  static validateAlgorithm(algorithm: string): void {
+    if (typeof algorithm !== 'string') {
+      throw new ValidationError(getErrorMessage('ALGORITHM_MUST_BE_STRING'))
+    }
+    if (algorithm.length === 0) {
+      throw new ValidationError(getErrorMessage('ALGORITHM_CANNOT_BE_EMPTY'))
+    }
+    const validAlgorithms = ['aes-256-gcm', 'chacha20-poly1305'] as const
+    if (!validAlgorithms.includes(algorithm as EncryptionAlgo)) {
+      throw new ValidationError(getErrorMessage('INVALID_ALGORITHM'))
+    }
+  }
+
   /**
    * Checks if payload size is within limits
    * @param payload - Payload string to check
@@ -377,6 +395,9 @@ export class ErrorHandler {
    * @throws {ValidationError} When base64 decoding fails
    */
   static validateBase64Decode(token: string, errorMessage: string): string {
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(token)) {
+      throw new ValidationError(errorMessage)
+    }
     try {
       return Buffer.from(token, 'base64').toString('utf8')
     } catch {

src/utils/ErrorMap.ts

@@ -87,6 +87,10 @@ export const errorMessages = {
   KEY_DERIVATION_INVALID_METHOD: 'Invalid key derivation method. Must be "basic" or "pbkdf2"',
   INVALID_KEY_DERIVATION_METHOD: 'Invalid key derivation method provided',
 
+  // Algorithm errors
+  ALGORITHM_MUST_BE_STRING: 'Algorithm must be a string',
+  ALGORITHM_CANNOT_BE_EMPTY: 'Algorithm cannot be empty',
+
   // Options errors
   OPTIONS_MUST_BE_OBJECT: 'Options must be an object',
   EXPIRE_IN_REQUIRED: 'expireIn is required and must be a string',

src/utils/TimeParser.ts

@@ -57,7 +57,7 @@ export function parseTimeString(timeString: string): TimeUnit {
  */
 export function parsetimeToMs(timeString: string): number {
   ErrorHandler.validateTimeString(timeString)
-  const timeUnit = parseTimeString(timeString)
+  const timeUnit = parseTimeString(timeString.trim())
   const milliseconds = timeToMs(timeUnit)
   const maxExpirationMs = 365 * 24 * 60 * 60 * 1000
   if (milliseconds > maxExpirationMs) {

tests/ErrorHandler.test.ts

@@ -48,6 +48,14 @@ describe('ErrorHandler', () => {
       const wrapped = ErrorHandler.wrap(fn)
       expect(() => wrapped('test')).toThrow('Unknown error occurred')
     })
+
+    it('should create SecureJWTError with error message for Error objects', () => {
+      const fn = jest.fn().mockImplementation(() => {
+        throw new Error('Custom error message')
+      })
+      const wrapped = ErrorHandler.wrap(fn)
+      expect(() => wrapped('test')).toThrow('Custom error message')
+    })
   })
 
   describe('validateData', () => {
@@ -454,10 +462,8 @@ describe('ErrorHandler', () => {
       expect(result).toBe('test')
     })
 
-    it('should not throw for invalid base64 (Buffer.from handles it)', () => {
-      // Buffer.from doesn't throw for invalid base64, it just produces garbage
-      const result = ErrorHandler.validateBase64Decode('invalid base64!', 'Invalid base64')
-      expect(typeof result).toBe('string')
+    it('should throw ValidationError for invalid base64', () => {
+      expect(() => ErrorHandler.validateBase64Decode('invalid base64!', 'Invalid base64')).toThrow(ValidationError)
     })
   })
 
@@ -619,10 +625,8 @@ describe('ErrorHandler', () => {
       expect(result).toBe(original)
     })
 
-    it('should not throw for invalid base64 (Buffer.from handles it)', () => {
-      // Buffer.from doesn't throw for invalid base64, it just produces garbage
-      const result = ErrorHandler.validateBase64Decode('invalid base64!', 'Invalid base64')
-      expect(typeof result).toBe('string')
+    it('should throw ValidationError for invalid base64', () => {
+      expect(() => ErrorHandler.validateBase64Decode('invalid base64!', 'Invalid base64')).toThrow(ValidationError)
     })
 
     it('should throw ValidationError when Buffer.from throws', () => {
@@ -1229,4 +1233,97 @@ describe('ErrorHandler', () => {
       }
     })
   })
+
+  describe('validateAlgorithm', () => {
+    it('should not throw for valid algorithms', () => {
+      expect(() => ErrorHandler.validateAlgorithm('aes-256-gcm')).not.toThrow()
+      expect(() => ErrorHandler.validateAlgorithm('chacha20-poly1305')).not.toThrow()
+    })
+
+    it('should throw ValidationError for non-string algorithm', () => {
+      expect(() => ErrorHandler.validateAlgorithm(123 as any)).toThrow(ValidationError)
+      expect(() => ErrorHandler.validateAlgorithm({} as any)).toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for empty string algorithm', () => {
+      expect(() => ErrorHandler.validateAlgorithm('')).toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for invalid algorithm', () => {
+      expect(() => ErrorHandler.validateAlgorithm('invalid-algo')).toThrow(ValidationError)
+      expect(() => ErrorHandler.validateAlgorithm('aes-128-gcm')).toThrow(ValidationError)
+    })
+  })
+
+  describe('validateExpiration', () => {
+    it('should not throw for valid expiration', () => {
+      const now = Math.floor(Date.now() / 1000)
+      const future = now + 3600
+      expect(() => ErrorHandler.validateExpiration(future, now + 7200)).not.toThrow()
+    })
+
+    it('should throw ValidationError for expiration too far in future', () => {
+      const now = Math.floor(Date.now() / 1000)
+      const future = now + 3600
+      expect(() => ErrorHandler.validateExpiration(future, now + 1800)).toThrow(ValidationError)
+    })
+  })
+
+  describe('validateVersionCompatibility', () => {
+    it('should not throw for matching versions', () => {
+      expect(() => ErrorHandler.validateVersionCompatibility('1.0.0', '1.0.0')).not.toThrow()
+    })
+
+    it('should throw VersionMismatchError for different versions', () => {
+      expect(() => ErrorHandler.validateVersionCompatibility('1.0.0', '2.0.0')).toThrow(VersionMismatchError)
+    })
+
+    it('should throw VersionMismatchError for downgrade attack', () => {
+      expect(() => ErrorHandler.validateVersionCompatibility('1.0.0', '2.0.0')).toThrow(VersionMismatchError)
+    })
+
+    it('should throw VersionMismatchError for upgrade not supported', () => {
+      expect(() => ErrorHandler.validateVersionCompatibility('2.0.0', '1.0.0')).toThrow(VersionMismatchError)
+    })
+  })
+
+  describe('validateTokenTimestamps', () => {
+    it('should not throw for matching timestamps', () => {
+      const now = Math.floor(Date.now() / 1000)
+      expect(() => ErrorHandler.validateTokenTimestamps(now + 3600, now + 3600, now, now)).not.toThrow()
+    })
+
+    it('should throw ValidationError for mismatched timestamps', () => {
+      const now = Math.floor(Date.now() / 1000)
+      expect(() => ErrorHandler.validateTokenTimestamps(now + 3600, now + 1800, now, now)).toThrow(ValidationError)
+      expect(() => ErrorHandler.validateTokenTimestamps(now + 3600, now + 3600, now, now + 1)).toThrow(ValidationError)
+    })
+  })
+
+  describe('validateJSONParse', () => {
+    it('should parse valid JSON', () => {
+      const result = ErrorHandler.validateJSONParse('{"test": "value"}', 'Error')
+      expect(result).toEqual({ test: 'value' })
+    })
+
+    it('should throw ValidationError for invalid JSON', () => {
+      expect(() => ErrorHandler.validateJSONParse('invalid json', 'Custom error')).toThrow(ValidationError)
+    })
+  })
+
+  describe('validateBase64Decode', () => {
+    it('should decode valid base64', () => {
+      const encoded = Buffer.from('test').toString('base64')
+      const result = ErrorHandler.validateBase64Decode(encoded, 'Error')
+      expect(result).toBe('test')
+    })
+
+    it('should throw ValidationError for invalid base64', () => {
+      expect(() => ErrorHandler.validateBase64Decode('invalid base64!', 'Custom error')).toThrow(ValidationError)
+    })
+
+    it('should throw ValidationError for malformed base64', () => {
+      expect(() => ErrorHandler.validateBase64Decode('invalid@#$%', 'Custom error')).toThrow(ValidationError)
+    })
+  })
 })

tests/ErrorMap.test.ts

@@ -76,7 +76,7 @@ describe('ErrorMap', () => {
     })
 
     it('should have consistent structure', () => {
-      expect(Object.keys(errorMessages)).toHaveLength(72)
+      expect(Object.keys(errorMessages)).toHaveLength(74)
     })
 
     it('should have all messages as strings', () => {