feat(encryption): add multi-algorithm support with factory pattern 🔑

- Add AES-256-GCM and ChaCha20-Poly1305 encryption algorithms
- Add unit tests for both algorithm implementations
- Add error handling for invalid algorithm selection
- Configure TypeScript and Jest for new algorithm modules
- Implement factory pattern for scalable algorithm management
- Refactor SecureJWT class to use algorithm abstraction layer
- Update coverage badge to 98.28% and add algorithm comparison
- Update README with algorithm selection and performance documentation

Author: NeaByteLab

CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.3.0] - 2025-09-06
+
+### Added
+- **Dual encryption algorithms**: AES-256-GCM and ChaCha20-Poly1305 support
+- **Algorithm selection**: Choose between AES-256-GCM (default) or ChaCha20-Poly1305
+- **Factory pattern**: Scalable algorithm management system
+- **Algorithm unit tests**: Unit test coverage for both algorithms
+- **Performance comparison**: ChaCha20-Poly1305 is 2-3x faster for verification
+- **Algorithm documentation**: Updated README with algorithm selection guide
+
+### Changed
+- **SecureJWT constructor**: Added optional `algorithm` parameter
+- **Encryption abstraction**: Refactored to use algorithm factory pattern
+- **README updates**: Enhanced with dual algorithm documentation and performance metrics
+- **Coverage badge**: Updated to 98.28%
+
+### Technical
+- **Algorithm interface**: Created `IEncryptionAlgo` interface for algorithm abstraction
+- **Factory implementation**: `Algorithms` class for algorithm instance management
+- **TypeScript support**: Added path aliases for algorithm modules
+- **Jest configuration**: Updated to support new algorithm test files
+
+---
+
 ## [1.2.0] - 2025-09-06
 
 ### Breaking Changes

README.md

@@ -3,14 +3,15 @@
 ![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%25-brightgreen)
+![coverage](https://img.shields.io/badge/coverage-98.28%25-brightgreen)
 ![license](https://img.shields.io/npm/l/@neabyte/secure-jwt.svg)
 
-A secure JWT implementation with AES-256-GCM encryption for Node.js applications.
+A secure JWT implementation with **AES-256-GCM** & **ChaCha20-Poly1305** algorithms for Node.js applications.
 
 ## ✨ Features
 
-- 🔒 **AES-256-GCM encryption** - Industry-standard security
+- 🔒 **Multi algorithms** - AES-256-GCM & ChaCha20-Poly1305
+- ⚙️ **Algorithm selection** - Choose the best encryption for your use case
 - 🛡️ **Tamper detection** - Authentication tags prevent modification
 - ⏰ **Automatic expiration** - Built-in token lifecycle management
 - 🔄 **Version compatibility** - Prevents downgrade attacks
@@ -111,11 +112,36 @@ const arrayToken: string = jwt.sign([1, 2, 3])
 const jwt = new SecureJWT({
   secret: 'your-secret-key',     // Required: 8-255 characters
   expireIn: '1h',                // Required: Time string
+  algorithm: 'aes-256-gcm',      // Optional: default: 'aes-256-gcm'
   version: '1.0.0',              // Optional: Default '1.0.0'
   cached: 1000                   // Optional: Cache size (default: 1000)
 })
 ```
 
+### 🔧 Algorithm Options
+
+Choose the encryption algorithm that best fits your needs:
+
+```javascript
+// AES-256-GCM (default) - Hardware accelerated, industry standard
+const jwtAES = new SecureJWT({
+  algorithm: 'aes-256-gcm',
+  secret: 'key',
+  expireIn: '1h'
+})
+
+// ChaCha20-Poly1305 - Maximum performance, 2-3x faster
+const jwtChaCha = new SecureJWT({
+  algorithm: 'chacha20-poly1305',
+  secret: 'key',
+  expireIn: '1h'
+})
+```
+
+**Algorithm Comparison:**
+- **AES-256-GCM**: Hardware accelerated, widely supported, industry standard
+- **ChaCha20-Poly1305**: Software optimized, 2-3x faster, perfect for high-throughput applications
+
 ### Time Format
 
 ```javascript
@@ -138,8 +164,12 @@ const jwt = new SecureJWT({
 ```javascript
 new SecureJWT(options: JWTOptions)
 ```
+**Available Algorithm:**
+- `aes-256-gcm`
+- `chacha20-poly1305`
 
 **Options:**
+- `algorithm?:` - Encryption algorithm (default: 'aes-256-gcm')
 - `secret: string` - Secret key (8-255 chars, required for security)
 - `expireIn: string` - Token expiration time (required for security)
 - `version?: string` - Token version (default: '1.0.0')

jest.config.js

@@ -24,6 +24,8 @@ export default {
   coverageReporters: ['text', 'lcov', 'html'],
   moduleNameMapper: {
     '^@/(.*)$': '<rootDir>/src/$1',
+    '^@algorithms/(.*)$': '<rootDir>/src/algorithms/$1',
+    '^@interfaces/(.*)$': '<rootDir>/src/interfaces/$1',
     '^@types/(.*)$': '<rootDir>/src/types/$1',
     '^@utils/(.*)$': '<rootDir>/src/utils/$1'
   },

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@neabyte/secure-jwt",
-  "description": "Secure JWT with AES-256-GCM encryption, built-in caching, tamper detection, and TypeScript support",
-  "version": "1.2.0",
+  "description": "Secure JWT with AES-256-GCM & ChaCha20-Poly1305 encryption, built-in caching, tamper detection, and TypeScript support",
+  "version": "1.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

src/algorithms/AES256.ts

@@ -0,0 +1,66 @@
+import { createCipheriv, createDecipheriv } from 'node:crypto'
+import { ErrorHandler } from '@utils/index'
+import type { TokenEncrypted, EncryptionAlgo, IEncryptionAlgo } from '@interfaces/index'
+
+/**
+ * AES-256-GCM encryption class
+ * Provides encryption and decryption using AES-256-GCM algorithm
+ */
+export default class AES256 implements IEncryptionAlgo {
+  /** Algorithm name constant */
+  private readonly algorithm = 'aes-256-gcm'
+
+  /**
+   * Encrypts data using AES-256-GCM
+   * @param data - String data to encrypt
+   * @param key - 32-byte encryption key
+   * @param iv - 16-byte initialization vector
+   * @param version - Token version for additional authentication data
+   * @returns Object containing encrypted data, IV, and authentication tag
+   */
+  encrypt(data: string, key: Buffer, iv: Buffer, version: string): TokenEncrypted {
+    const cipher = createCipheriv(this.algorithm, key, iv)
+    cipher.setAAD(Buffer.from(`secure-jwt-${version}`, 'utf8'))
+    let encrypted = cipher.update(data, 'utf8', 'hex')
+    encrypted += cipher.final('hex')
+    const tag = cipher.getAuthTag()
+    ErrorHandler.validateAuthTag(tag)
+    return {
+      encrypted,
+      iv: iv.toString('hex'),
+      tag: tag.toString('hex')
+    }
+  }
+
+  /**
+   * Decrypts data using AES-256-GCM
+   * @param tokenEncrypted - Object containing encrypted data, IV, and authentication tag
+   * @param key - 32-byte decryption key
+   * @param version - Token version for additional authentication data
+   * @returns Decrypted string data
+   */
+  decrypt(tokenEncrypted: TokenEncrypted, key: Buffer, version: string): string {
+    const decipher = createDecipheriv(this.algorithm, key, Buffer.from(tokenEncrypted.iv, 'hex'))
+    decipher.setAAD(Buffer.from(`secure-jwt-${version}`, 'utf8'))
+    decipher.setAuthTag(Buffer.from(tokenEncrypted.tag, 'hex'))
+    let decrypted = decipher.update(tokenEncrypted.encrypted, 'hex', 'utf8')
+    decrypted += decipher.final('utf8')
+    return decrypted
+  }
+
+  /**
+   * Gets the required IV length for AES-256-GCM
+   * @returns IV length in bytes (16)
+   */
+  getIVLength(): number {
+    return 16
+  }
+
+  /**
+   * Gets the algorithm name
+   * @returns Algorithm name string
+   */
+  getAlgoName(): EncryptionAlgo {
+    return this.algorithm
+  }
+}

src/algorithms/ChaCha20.ts

@@ -0,0 +1,68 @@
+import { createCipheriv, createDecipheriv } from 'node:crypto'
+import { ErrorHandler } from '@utils/index'
+import type { TokenEncrypted, EncryptionAlgo, IEncryptionAlgo } from '@interfaces/index'
+
+/**
+ * ChaCha20-Poly1305 encryption class
+ * Provides encryption and decryption using ChaCha20-Poly1305 algorithm
+ */
+export default class ChaCha20 implements IEncryptionAlgo {
+  /** Algorithm name constant */
+  private readonly algorithm = 'chacha20-poly1305'
+
+  /**
+   * Encrypts data using ChaCha20-Poly1305
+   * @param data - String data to encrypt
+   * @param key - 32-byte encryption key
+   * @param iv - 12-byte initialization vector
+   * @param version - Token version for additional authentication data
+   * @returns Object containing encrypted data, IV, and authentication tag
+   */
+  encrypt(data: string, key: Buffer, iv: Buffer, version: string): TokenEncrypted {
+    const cipher = createCipheriv(this.algorithm, key, iv)
+    cipher.setAAD(Buffer.from(`secure-jwt-${version}`, 'utf8'), { plaintextLength: data.length })
+    let encrypted = cipher.update(data, 'utf8', 'hex')
+    encrypted += cipher.final('hex')
+    const tag = cipher.getAuthTag()
+    ErrorHandler.validateAuthTag(tag)
+    return {
+      encrypted,
+      iv: iv.toString('hex'),
+      tag: tag.toString('hex')
+    }
+  }
+
+  /**
+   * Decrypts data using ChaCha20-Poly1305
+   * @param tokenEncrypted - Object containing encrypted data, IV, and authentication tag
+   * @param key - 32-byte decryption key
+   * @param version - Token version for additional authentication data
+   * @returns Decrypted string data
+   */
+  decrypt(tokenEncrypted: TokenEncrypted, key: Buffer, version: string): string {
+    const decipher = createDecipheriv(this.algorithm, key, Buffer.from(tokenEncrypted.iv, 'hex'))
+    decipher.setAAD(Buffer.from(`secure-jwt-${version}`, 'utf8'), {
+      plaintextLength: tokenEncrypted.encrypted.length / 2
+    })
+    decipher.setAuthTag(Buffer.from(tokenEncrypted.tag, 'hex'))
+    let decrypted = decipher.update(tokenEncrypted.encrypted, 'hex', 'utf8')
+    decrypted += decipher.final('utf8')
+    return decrypted
+  }
+
+  /**
+   * Gets the required IV length for ChaCha20-Poly1305
+   * @returns IV length in bytes (12)
+   */
+  getIVLength(): number {
+    return 12
+  }
+
+  /**
+   * Gets the algorithm name
+   * @returns Algorithm name string
+   */
+  getAlgoName(): EncryptionAlgo {
+    return this.algorithm
+  }
+}

src/algorithms/index.ts

@@ -0,0 +1,36 @@
+import { randomBytes } from 'node:crypto'
+import AES256 from '@algorithms/AES256'
+import ChaCha20 from '@algorithms/ChaCha20'
+import { EncryptionError, getErrorMessage } from '@utils/index'
+import type { EncryptionAlgo, IEncryptionAlgo } from '@interfaces/index'
+
+/**
+ * Algorithms factory class
+ * Creates encryption algorithm instances and generates random bytes
+ */
+export default class Algorithms {
+  /**
+   * Generates cryptographically secure random bytes
+   * @param length - Number of bytes to generate
+   * @returns Buffer containing random bytes
+   */
+  static getRandomBytes(length: number): Buffer {
+    return randomBytes(length)
+  }
+
+  /**
+   * Creates an encryption algorithm instance
+   * @param algorithm - Algorithm type to create
+   * @returns Encryption algorithm instance
+   * @throws EncryptionError when algorithm is not supported
+   */
+  static getInstance(algorithm: EncryptionAlgo): IEncryptionAlgo {
+    if (algorithm === 'aes-256-gcm') {
+      return new AES256()
+    } else if (algorithm === 'chacha20-poly1305') {
+      return new ChaCha20()
+    } else {
+      throw new EncryptionError(getErrorMessage('INVALID_ALGORITHM'))
+    }
+  }
+}