feat(security): improve data validation & required secret key 🔒

- add cache size validation (max 10k tokens)
- add time expiration limit (max 1 year)
- enhance error handling and test coverage
- fix architecture diagram (key preparation vs derivation)
- make secret parameter required (8-255 chars)
- update JWTOptions interface and documentation

Author: NeaByteLab

CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [1.2.0] - 2025-09-06
+
+### Breaking Changes
+- `secret` parameter is now required in constructor
+- `JWTOptions.secret` changed from optional (`secret?: string`) to required (`secret: string`)
+
+### Security
+- Added cache size validation (max 10,000 tokens)
+- Added time expiration limit (max 1 year)
+- Made secret parameter required for enhanced security
+- Enhanced secret key validation (8-255 characters)
+
+### Added
+- Cache size validation with configurable limits
+- Time expiration validation with 1-year maximum
+- Enhanced error messages for better debugging
+- Comprehensive test coverage for new validations
+
+### Changed
+- Updated README documentation to reflect required secret parameter
+- Fixed architecture diagram (Key Preparation vs Key Derivation)
+- Simplified JSDoc comments across multiple files
+- Enhanced error handling and validation coverage
+
+### Fixed
+- Test suite updated to handle required secret parameter
+- Architecture diagram accuracy improved
+- Documentation consistency across all files
+
+---
+
 ## [1.1.1] - 2025-09-06
 
 ### Security

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-99.08%25-brightgreen)
+![coverage](https://img.shields.io/badge/coverage-98%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.
@@ -109,7 +109,7 @@ const arrayToken: string = jwt.sign([1, 2, 3])
 
 ```javascript
 const jwt = new SecureJWT({
-  secret: 'your-secret-key',     // Required: 8+ characters
+  secret: 'your-secret-key',     // Required: 8-255 characters
   expireIn: '1h',                // Required: Time string
   version: '1.0.0',              // Optional: Default '1.0.0'
   cached: 1000                   // Optional: Cache size (default: 1000)
@@ -140,8 +140,8 @@ new SecureJWT(options: JWTOptions)
 ```
 
 **Options:**
-- `secret?: string` - Secret key (8+ chars, optional)
-- `expireIn: string` - Token expiration time
+- `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')
 - `cached?: number` - Cache size for performance (default: 1000)
 
@@ -201,17 +201,18 @@ graph TD
     F --> G[Create Token Structure]
     G --> H[Base64 Encode]
     H --> I[Secure JWT Token]
-    
-    J[Secret Key] --> K[Key Derivation]
+
+    J[Secret Key] --> K[Key Preparation]
     K --> F
     L[Random Salt] --> K
-    
-    M[Version] --> N[Additional Authenticated Data]
+
+    M[Version] --> N[Additional
+    Authenticated Data]
     N --> F
-    
+
     F --> O[Authentication Tag]
     O --> G
-    
+
     style A fill:#e1f5fe,color:#000
     style I fill:#c8e6c9,color:#000
     style F fill:#fff3e0,color:#000
@@ -227,12 +228,12 @@ graph LR
     C --> D[Integrity Layer]
     D --> E[Encoding Layer]
     E --> F[Secure Token]
-    
+
     G[Secret Key] --> C
     H[Random IV] --> C
     I[Version AAD] --> C
     J[Auth Tag] --> D
-    
+
     style B fill:#ffebee,color:#000
     style C fill:#fff3e0,color:#000
     style D fill:#f3e5f5,color:#000

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.1.1",
+  "version": "1.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

src/index.ts

@@ -16,8 +16,8 @@ import {
 } from '@utils/index'
 
 /**
- * Secure JWT implementation with encryption support
- * Handles token creation, verification, and data extraction
+ * JWT implementation with encryption
+ * Creates, verifies, and extracts data from tokens
  */
 export default class SecureJWT {
   /** Secret key for encryption */
@@ -33,17 +33,18 @@ export default class SecureJWT {
 
   /**
    * Creates a new SecureJWT instance
-   * @param options - The configuration for token expiration, secret key, and version
+   * @param options - Configuration for token expiration, secret key, and version
    */
   constructor(options: JWTOptions) {
     ErrorHandler.validateOptions(options)
     ErrorHandler.validateExpireIn(options.expireIn)
-    if (options.secret !== undefined) {
-      ErrorHandler.validateSecret(options.secret)
-    }
+    ErrorHandler.validateSecret(options.secret)
     if (options.version !== undefined) {
       ErrorHandler.validateVersion(options.version)
     }
+    if (options.cached !== undefined) {
+      ErrorHandler.validateCacheSize(options.cached)
+    }
     this.#secret = this.generateSecret(options.secret)
     this.#expireInMs = parsetimeToMs(options.expireIn)
     this.#version = options.version ?? '1.0.0'
@@ -52,22 +53,19 @@ export default class SecureJWT {
   }
 
   /**
-   * Creates a secret key from the provided secret or generates a random one
-   * @param secret - The optional secret string for key creation
-   * @returns The Buffer containing the secret key
+   * Creates a secret key from the provided secret
+   * @param secret - Secret string for key creation
+   * @returns Buffer containing the secret key
    */
-  private generateSecret(secret?: string): Buffer {
-    if (secret != null && secret.length > 0) {
-      const salt = randomBytes(32)
-      return Buffer.concat([salt, Buffer.from(secret, 'utf8')])
-    }
-    return randomBytes(32)
+  private generateSecret(secret: string): Buffer {
+    const salt = randomBytes(32)
+    return Buffer.concat([salt, Buffer.from(secret, 'utf8')])
   }
 
   /**
    * Encrypts data using AES-256-GCM encryption
-   * @param data - The string data to encrypt
-   * @returns The object with encrypted data, initialization vector, and authentication tag
+   * @param data - String data to encrypt
+   * @returns Object with encrypted data, initialization vector, and authentication tag
    */
   private encrypt(data: string): TokenEncrypted {
     ErrorHandler.validateEncryptionData(data)
@@ -89,8 +87,8 @@ export default class SecureJWT {
 
   /**
    * Decrypts data using AES-256-GCM decryption
-   * @param tokenEncrypted - The object with encrypted data, initialization vector, and authentication tag
-   * @returns The decrypted data as string
+   * @param tokenEncrypted - Object with encrypted data, initialization vector, and authentication tag
+   * @returns Decrypted data as string
    */
   private decrypt(tokenEncrypted: TokenEncrypted): string {
     try {
@@ -116,9 +114,9 @@ export default class SecureJWT {
   }
 
   /**
-   * Creates a secure JWT token from data
-   * @param data - The data to sign (will be JSON stringified)
-   * @returns The JWT token string
+   * Creates a JWT token from data
+   * @param data - Data to sign (will be JSON stringified)
+   * @returns JWT token string
    */
   sign(data: unknown): string {
     try {
@@ -162,8 +160,8 @@ export default class SecureJWT {
 
   /**
    * Validates if a JWT token is valid
-   * @param token - The Base64 encoded token to check
-   * @returns The boolean indicating if token is valid and not expired
+   * @param token - Base64 encoded token to check
+   * @returns Boolean indicating if token is valid and not expired
    */
   verify(token: string): boolean {
     try {
@@ -217,7 +215,7 @@ export default class SecureJWT {
 
   /**
    * Validates a JWT token and throws specific errors
-   * @param token - The Base64 encoded token to validate
+   * @param token - Base64 encoded token to validate
    * @throws {ValidationError} When token format is invalid
    * @throws {TokenExpiredError} When token has expired
    * @throws {DecryptionError} When token decryption fails
@@ -260,8 +258,8 @@ export default class SecureJWT {
 
   /**
    * Extracts data from a JWT token
-   * @param token - The Base64 encoded token to decode
-   * @returns The decoded payload data
+   * @param token - Base64 encoded token to decode
+   * @returns Decoded payload data
    * @throws {ValidationError} When token format is invalid
    * @throws {TokenExpiredError} When token has expired
    * @throws {DecryptionError} When token decryption fails

src/interfaces/index.ts

@@ -2,7 +2,7 @@
  * JWT payload structure
  */
 export interface JWTPayload {
-  /** The actual data payload */
+  /** Actual data payload */
   payload: unknown
   /** Expiration timestamp in seconds */
   exp: number
@@ -14,10 +14,10 @@ export interface JWTPayload {
  * Configuration for JWT operations
  */
 export interface JWTOptions {
+  /** Secret key for signing tokens (required for security) */
+  secret: string
   /** Token expiration time as a string (e.g., '1h', '30m', '7d') */
   expireIn: string
-  /** Secret key for signing tokens (optional) */
-  secret?: string
   /** Version identifier for the token (optional) */
   version?: string
   /** Cache configuration (optional) */
@@ -28,7 +28,7 @@ export interface JWTOptions {
  * Time value with its unit
  */
 export interface TimeUnit {
-  /** Numeric value of the time */
+  /** Numeric value of time */
   value: number
   /** Time unit (milliseconds, seconds, minutes, hours, days, months, years) */
   unit: 'ms' | 's' | 'm' | 'h' | 'd' | 'M' | 'y'
@@ -68,7 +68,7 @@ export interface TokenEncrypted {
  * Payload data structure with timing and version information
  */
 export interface PayloadData {
-  /** The actual payload data */
+  /** Actual payload data */
   data: unknown
   /** Expiration timestamp in seconds */
   exp: number
@@ -82,7 +82,7 @@ export interface PayloadData {
  * Cache entry structure with expiration and usage tracking
  */
 export interface CacheEntry<T> {
-  /** The stored data */
+  /** Stored data */
   data: T
   /** When this entry expires (milliseconds since epoch) */
   expiresAt: number

src/utils/Cache.ts

@@ -1,7 +1,7 @@
 import type { CacheEntry } from '@interfaces/index'
 
 /**
- * In-memory cache that stores data with expiration times
+ * In-memory cache that stores data with expiration
  */
 export class Cache<T> {
   private readonly cache = new Map<string, CacheEntry<T>>()
@@ -20,8 +20,8 @@ export class Cache<T> {
 
   /**
    * Gets a value from the cache
-   * @param key - The key to look up
-   * @returns The cached value or undefined if not found or expired
+   * @param key - Key to look up
+   * @returns Cached value or undefined if not found or expired
    */
   get(key: string): T | undefined {
     const entry = this.cache.get(key)
@@ -38,8 +38,8 @@ export class Cache<T> {
 
   /**
    * Stores a value in the cache
-   * @param key - The key to store under
-   * @param value - The value to store
+   * @param key - Key to store under
+   * @param value - Value to store
    * @param ttl - Expiration time in milliseconds (optional, uses default if not provided, minimum: 1ms)
    */
   set(key: string, value: T, ttl?: number): void {
@@ -61,7 +61,7 @@ export class Cache<T> {
 
   /**
    * Checks if a key exists in the cache and is not expired
-   * @param key - The key to check
+   * @param key - Key to check
    * @returns True if the key exists and is valid
    */
   has(key: string): boolean {