@igxjs/node-components 1.0.12 → 1.0.14

package/README.md

@@ -78,7 +78,7 @@ flexRouter.mount(app, '');
 import { JwtManager } from '@igxjs/node-components';
 
 // Constructor uses UPPERCASE naming with JWT_ prefix
-const jwt = new JwtManager({ SESSION_AGE: 64800000 });
+const jwt = new JwtManager({ JWT_EXPIRATION_TIME: 64800 });
 const SECRET = process.env.JWT_SECRET;
 
 // Create token (encrypt method uses camelCase for per-call options)
@@ -127,7 +127,7 @@ Uses traditional server-side session cookies. When a user authenticates via SSO,
 
 **Configuration:**
 - `SESSION_MODE`: `SessionMode.SESSION` (default) - Uses session-based authentication
-- `SESSION_AGE`: Session timeout in milliseconds (default: 64800000)
+- `SESSION_AGE`: Session timeout in seconds (default: 64800 = 18 hours)
 - `REDIS_URL`: Redis connection string for session storage
 
 **Auth Methods:**
@@ -182,7 +182,7 @@ fetch('/api/protected', {
 | `SSO_SUCCESS_URL` | string | - | Redirect URL after successful login (token mode) |
 | `SSO_FAILURE_URL` | string | - | Redirect URL after failed login (token mode) |
 | `SESSION_MODE` | string | `SessionMode.SESSION` | Authentication mode: `SessionMode.SESSION` or `SessionMode.TOKEN` |
-| `SESSION_AGE` | number | 64800000 | Session timeout in milliseconds |
+| `SESSION_AGE` | number | 64800 | Session timeout in seconds (default: 64800 = 18 hours) |
 | `SESSION_COOKIE_PATH` | string | `'/'` | Session cookie path |
 | `SESSION_SECRET` | string | - | Session/JWT secret key |
 | `SESSION_PREFIX` | string | `'ibmid:'` | Redis session/key prefix |

package/components/jwt.js

@@ -1,4 +1,4 @@
-import crypto from 'node:crypto';
+import { webcrypto as crypto } from 'node:crypto';
 
 import { jwtDecrypt, EncryptJWT } from 'jose';
 
@@ -37,7 +37,7 @@ export class JwtManager {
    * @typedef {Object} JwtManagerOptions JwtManager configuration options
    * @property {string} [JWT_ALGORITHM='dir'] JWE algorithm (default: 'dir')
    * @property {string} [JWT_ENCRYPTION='A256GCM'] Encryption method (default: 'A256GCM')
-   * @property {number} [SESSION_AGE=64800000] Token expiration time in milliseconds (default: 64800000 = 18 hours)
+   * @property {number|string} [JWT_EXPIRATION_TIME=64800] Token expiration time - number in seconds (e.g., 64800) or string with time suffix (e.g., '18h', '7d', '1080m') (default: 64800 = 18 hours)
    * @property {string} [JWT_SECRET_HASH_ALGORITHM='SHA-256'] Hash algorithm (default: 'SHA-256')
    * @property {string?} [JWT_ISSUER] Optional JWT issuer claim
    * @property {string?} [JWT_AUDIENCE] Optional JWT audience claim
@@ -48,8 +48,8 @@ export class JwtManager {
   constructor(options = {}) {
     this.algorithm = options.JWT_ALGORITHM || 'dir';
     this.encryption = options.JWT_ENCRYPTION || 'A256GCM';
-    // SESSION_AGE is in milliseconds, convert to seconds for expirationTime
-    this.expirationTime = Math.floor((options.SESSION_AGE || 64800000) / 1000);
+    // JWT_EXPIRATION_TIME is in seconds
+    this.expirationTime = options.JWT_EXPIRATION_TIME || 64800;
     this.secretHashAlgorithm = options.JWT_SECRET_HASH_ALGORITHM || 'SHA-256';
     this.issuer = options.JWT_ISSUER;
     this.audience = options.JWT_AUDIENCE;
@@ -63,7 +63,7 @@ export class JwtManager {
    * @typedef {Object} JwtEncryptOptions Encryption method options
    * @property {string} [algorithm='dir'] JWE algorithm (overrides instance JWT_ALGORITHM)
    * @property {string} [encryption='A256GCM'] Encryption method (overrides instance JWT_ENCRYPTION)
-   * @property {number} [expirationTime] Token expiration time in seconds (overrides instance expirationTime derived from SESSION_AGE)
+   * @property {number|string} [expirationTime] Token expiration time - number in seconds or string with time suffix like '1h', '30m', '7d' (overrides instance JWT_EXPIRATION_TIME)
    * @property {string} [secretHashAlgorithm='SHA-256'] Hash algorithm for secret derivation (overrides instance JWT_SECRET_HASH_ALGORITHM)
    * @property {string?} [issuer] Optional JWT issuer claim (overrides instance JWT_ISSUER)
    * @property {string?} [audience] Optional JWT audience claim (overrides instance JWT_AUDIENCE)
@@ -91,6 +91,9 @@ export class JwtManager {
       new TextEncoder().encode(secret)
     );
 
+    // Convert number to string with 's' suffix, pass strings directly
+    const expTime = typeof expirationTime === 'number' ? `${expirationTime}s` : expirationTime;
+
     const jwt = new EncryptJWT(data)
       .setProtectedHeader({
         alg: algorithm,
@@ -98,7 +101,7 @@ export class JwtManager {
         typ: 'JWT',
       })
       .setIssuedAt()
-      .setExpirationTime(`${expirationTime}s`); // Pass as string with 's' suffix for seconds
+      .setExpirationTime(expTime); // Accepts: number (as seconds) or string (e.g., '18h', '7d')
 
     // Add optional claims if provided
     if (issuer) jwt.setIssuer(issuer);
@@ -124,7 +127,7 @@ export class JwtManager {
    * @param {string} token JWT token to decrypt
    * @param {string} secret Secret key or password for decryption
    * @param {JwtDecryptOptions} [options] Per-call configuration overrides (camelCase naming convention)
-   * @returns {Promise<import('jose').JWTDecryptResult<import('jose').EncryptJWT>} Returns decrypted JWT token
+   * @returns {Promise<import('jose').JWTDecryptResult>} Returns decrypted JWT token
    */
   async decrypt(token, secret, options = {}) {
     const clockTolerance = options.clockTolerance ?? this.clockTolerance;
@@ -147,4 +150,4 @@ export class JwtManager {
 
     return await jwtDecrypt(token, new Uint8Array(secretHash), decryptOptions);
   }
-}
+}

package/components/redis.js

@@ -11,17 +11,36 @@ export class RedisManager {
   #client = null;
   /**
    * Connect with Redis
+   * @param {string} redisUrl Redis connection URL
+   * @param {string} certPath Path to TLS certificate (required when using rediss:// protocol)
    * @returns {Promise<boolean>} Returns `true` if Redis server is connected
+   * @throws {TypeError} If redisUrl is not a string
+   * @throws {Error} If TLS is enabled but certPath is invalid
    */
   async connect(redisUrl, certPath) {
     if (redisUrl?.length > 0) {
       try {
+        // Validate redisUrl is a string
+        if (typeof redisUrl !== 'string') {
+          throw new TypeError(`Invalid redisUrl: expected string but received ${typeof redisUrl}`);
+        }
+
         /** @type {import('@redis/client').RedisClientOptions} */
         const options = {
           url: redisUrl,
           socket: { tls: redisUrl.includes('rediss:'), ca: null },
         };
-        if(options.socket.tls) {
+
+        if (options.socket.tls) {
+          // Validate certPath when TLS is enabled
+          if (!certPath || typeof certPath !== 'string') {
+            throw new Error('TLS certificate path is required when using rediss:// protocol');
+          }
+
+          if (!fs.existsSync(certPath)) {
+            throw new Error(`TLS certificate file not found at path: ${certPath}`);
+          }
+
           const caCert = fs.readFileSync(certPath);
           options.socket.ca = caCert;
         }

package/components/router.js

@@ -43,11 +43,23 @@ export class FlexRouter {
   }
 
   /**
-   * Mount router
+   * Mount router to Express application
    * @param {import('@types/express').Express} app Express app
    * @param {string} basePath Base path
+   * @throws {TypeError} If app is not a valid Express instance
+   * @throws {TypeError} If basePath is not a string
    */
   mount(app, basePath) {
+    // Validate app is an Express instance (has 'use' method)
+    if (!app || typeof app.use !== 'function') {
+      throw new TypeError('Invalid Express app: app must be an Express application instance with a "use" method');
+    }
+
+    // Validate basePath is a string
+    if (typeof basePath !== 'string') {
+      throw new TypeError(`Invalid basePath: expected string but received ${typeof basePath}`);
+    }
+
     const path = basePath.concat(this.context);
     app.use(path, this.handlers, this.router);
   }

package/components/session.js

@@ -34,7 +34,20 @@ export class SessionConfig {
    * @default SessionMode.SESSION
    */
   SESSION_MODE;
-  /** @type {string} */
+  /** 
+   * @type {string} Identity Provider microservice endpoint URL
+   * 
+   * This is a fully customized, independent microservice that provides SSO authentication.
+   * The endpoint serves multiple applications and provides the following APIs:
+   * - GET /auth/providers - List supported identity providers
+   * - POST /auth/login/:idp - Generate login URL for specific identity provider
+   * - POST /auth/verify - Verify JWT token validity
+   * - GET /auth/callback/:idp - Validate authentication and return user data
+   * - POST /auth/refresh - Refresh access tokens
+   * 
+   * @example
+   * SSO_ENDPOINT_URL: 'https://idp.example.com/open/api/v1'
+   */
   SSO_ENDPOINT_URL;
   /** @type {string} */
   SSO_CLIENT_ID;
@@ -45,7 +58,7 @@ export class SessionConfig {
   /** @type {string} */
   SSO_FAILURE_URL;
 
-  /** @type {number} Session age in milliseconds */
+  /** @type {number} Session age in seconds (default: 64800 = 18 hours) */
   SESSION_AGE;
   /**
    * @type {string} Session cookie path
@@ -128,13 +141,48 @@ export class SessionManager {
   /**
    * Create a new session manager
    * @param {SessionConfig} config Session configuration
+   * @throws {TypeError} If config is not an object
+   * @throws {Error} If required configuration fields are missing
    */
   constructor(config) {
+    // Validate config is an object
+    if (!config || typeof config !== 'object') {
+      throw new TypeError('SessionManager configuration must be an object');
+    }
+
+    // Validate required fields based on SESSION_MODE
+    const mode = config.SESSION_MODE || SessionMode.SESSION;
+    
+    // SESSION_SECRET is always required for both modes
+    if (!config.SESSION_SECRET) {
+      throw new Error('SESSION_SECRET is required for SessionManager');
+    }
+
+    // Validate SSO configuration if SSO endpoints are used
+    if (config.SSO_ENDPOINT_URL) {
+      if (!config.SSO_CLIENT_ID) {
+        throw new Error('SSO_CLIENT_ID is required when SSO_ENDPOINT_URL is provided');
+      }
+      if (!config.SSO_CLIENT_SECRET) {
+        throw new Error('SSO_CLIENT_SECRET is required when SSO_ENDPOINT_URL is provided');
+      }
+    }
+
+    // Validate TOKEN mode specific requirements
+    if (mode === SessionMode.TOKEN) {
+      if (!config.SSO_SUCCESS_URL) {
+        throw new Error('SSO_SUCCESS_URL is required for TOKEN authentication mode');
+      }
+      if (!config.SSO_FAILURE_URL) {
+        throw new Error('SSO_FAILURE_URL is required for TOKEN authentication mode');
+      }
+    }
+
     this.#config = {
       // Session Mode
       SESSION_MODE: config.SESSION_MODE || SessionMode.SESSION,
-      // Session
-      SESSION_AGE: config.SESSION_AGE || 64800000,
+      // Session - SESSION_AGE is now in seconds (default: 64800 = 18 hours)
+      SESSION_AGE: config.SESSION_AGE || 64800,
       SESSION_COOKIE_PATH: config.SESSION_COOKIE_PATH || '/',
       SESSION_SECRET: config.SESSION_SECRET,
       SESSION_PREFIX: config.SESSION_PREFIX || 'ibmid:',
@@ -205,6 +253,15 @@ export class SessionManager {
     return this.#config.SESSION_KEY;
   }
 
+  /**
+   * Get session age in milliseconds (for express-session cookie maxAge)
+   * @returns {number} Returns the session age in milliseconds
+   * @private
+   */
+  #getSessionAgeInMilliseconds() {
+    return Math.round(this.#config.SESSION_AGE * 1000);
+  }
+
   /**
    * Get Redis key for token storage
    * @param {string} email User email
@@ -238,14 +295,22 @@ export class SessionManager {
    * Generate and store JWT token in Redis
    * - JWT payload contains only { email, tid } for minimal size
    * - Full user data is stored in Redis as single source of truth
-   * @param {object} user User object
+   * @param {object} user User object with email and attributes
    * @returns {Promise<string>} Returns the generated JWT token
+   * @throws {Error} If JWT encryption fails
+   * @throws {Error} If Redis storage fails
    * @private
+   * @example
+   * const token = await this.#generateAndStoreToken({
+   *   email: 'user@example.com',
+   *   attributes: { /* user data * / }
+   * });
    */
   async #generateAndStoreToken(user) {
     // Generate unique token ID for this device/session
     const tid = crypto.randomUUID();
-    const ttlSeconds = Math.floor(this.#config.SESSION_AGE / 1000);
+    // SESSION_AGE is already in seconds
+    const ttlSeconds = this.#config.SESSION_AGE;
     // Create JWT token with only email and tid (minimal payload)
     const token = await this.#jwtManager.encrypt(
       { email: user.email, tid },
@@ -266,13 +331,17 @@ export class SessionManager {
   }
 
   /**
-   * Verify token authentication
-   * @param {import('@types/express').Request} req Request
-   * @param {import('@types/express').Response} res Response
-   * @param {import('@types/express').NextFunction} next Next function
-   * @param {boolean} isDebugging Debugging flag
-   * @param {string} redirectUrl Redirect URL
+   * Verify token authentication - extracts and validates JWT from Authorization header
+   * @param {import('@types/express').Request} req Request with Authorization header
+   * @param {import('@types/express').Response} res Response object
+   * @param {import('@types/express').NextFunction} next Next middleware function
+   * @param {boolean} isDebugging If true, allows unauthenticated requests
+   * @param {string} redirectUrl URL to redirect to on authentication failure
+   * @throws {CustomError} If token is missing, invalid, or expired
    * @private
+   * @example
+   * // Authorization header format: "Bearer {jwt_token}"
+   * await this.#verifyToken(req, res, next, false, '/login');
    */
   async #verifyToken(req, res, next, isDebugging, redirectUrl) {
     try {
@@ -306,7 +375,6 @@ export class SessionManager {
 
       // Parse and attach user to request
       req.user = JSON.parse(userData);
-      res.locals.user = req.user;
 
       // Validate authorization
       const { authorized = isDebugging } = req.user ?? { authorized: isDebugging };
@@ -337,12 +405,13 @@ export class SessionManager {
   }
 
   /**
-   * Verify session authentication
-   * @param {import('@types/express').Request} req Request
-   * @param {import('@types/express').Response} res Response
-   * @param {import('@types/express').NextFunction} next Next function
-   * @param {boolean} isDebugging Debugging flag
-   * @param {string} redirectUrl Redirect URL
+   * Verify session authentication - checks if user is authorized in session
+   * @param {import('@types/express').Request} req Request with session data
+   * @param {import('@types/express').Response} res Response object
+   * @param {import('@types/express').NextFunction} next Next middleware function
+   * @param {boolean} isDebugging If true, allows unauthorized users
+   * @param {string} redirectUrl URL to redirect to if user is unauthorized
+   * @throws {CustomError} If user is not authorized
    * @private
    */
   async #verifySession(req, res, next, isDebugging, redirectUrl) {
@@ -357,13 +426,18 @@ export class SessionManager {
   }
 
   /**
-   * Refresh token authentication
-   * @param {import('@types/express').Request} req Request
-   * @param {import('@types/express').Response} res Response
-   * @param {import('@types/express').NextFunction} next Next function
-   * @param {(user: object) => object} initUser Initialize user function
-   * @param {string} idpUrl Identity provider URL
+   * Refresh token authentication - exchanges refresh token for new JWT
+   * Invalidates old token and generates a new one with updated user data
+   * @param {import('@types/express').Request} req Request with Authorization header
+   * @param {import('@types/express').Response} res Response object
+   * @param {import('@types/express').NextFunction} next Next middleware function
+   * @param {(user: object) => object} initUser Function to initialize/transform user object
+   * @param {string} idpUrl Identity provider refresh endpoint URL
+   * @throws {CustomError} If refresh lock is active or SSO refresh fails
    * @private
+   * @example
+   * // Response format:
+   * // { token: "new_jwt", user: {...}, expiresIn: 64800, tokenType: "Bearer" }
    */
   async #refreshToken(req, res, next, initUser, idpUrl) {
     try {
@@ -425,7 +499,7 @@ export class SessionManager {
       return res.json({
         token: newToken,
         user,
-        expiresIn: Math.floor(this.#config.SESSION_AGE / 1000),
+        expiresIn: this.#config.SESSION_AGE, // Already in seconds
         tokenType: 'Bearer'
       });
     } catch (error) {
@@ -603,7 +677,10 @@ export class SessionManager {
    */
   async setup(app, updateUser) {
     this.#redisManager = new RedisManager();
-    this.#jwtManager = new JwtManager(this.#config);
+    this.#jwtManager = new JwtManager({
+      ...this.#config,
+      JWT_EXPIRATION_TIME: this.#config.SESSION_AGE, // SESSION_AGE is already in seconds
+    });
     // Identity Provider Request
     this.#idpRequest = axios.create({
       baseURL: this.#config.SSO_ENDPOINT_URL,
@@ -622,7 +699,7 @@ export class SessionManager {
     // Redis Session
     this.#logger.log('### Using Redis as the Session Store ###');
     return session({
-      cookie: { maxAge: this.#config.SESSION_AGE, path: this.#config.SESSION_COOKIE_PATH, sameSite: false },
+      cookie: { maxAge: this.#getSessionAgeInMilliseconds(), path: this.#config.SESSION_COOKIE_PATH, sameSite: false },
       store: new RedisStore({ client: this.#redisManager.getClient(), prefix: this.#config.SESSION_PREFIX, disableTouch: true }),
       resave: false, saveUninitialized: false,
       secret: this.#config.SESSION_SECRET,
@@ -638,7 +715,7 @@ export class SessionManager {
     this.#logger.log('### Using Memory as the Session Store ###');
     const MemoryStore = memStore(session);
     return session({
-      cookie: { maxAge: this.#config.SESSION_AGE, path: this.#config.SESSION_COOKIE_PATH, sameSite: false },
+      cookie: { maxAge: this.#getSessionAgeInMilliseconds(), path: this.#config.SESSION_COOKIE_PATH, sameSite: false },
       store: new MemoryStore({}),
       resave: false, saveUninitialized: false,
       secret: this.#config.SESSION_SECRET,

package/index.d.ts

@@ -79,33 +79,160 @@ export const SessionMode: {
 
 // Session Configuration - uses strict UPPERCASE naming convention for all property names
 export interface SessionConfig {
-  /** Identity Provider */
+  /** 
+   * SSO Identity Provider endpoint URL
+   * @example 'https://idp.example.com/open/api/v1'
+   * @required Required when using SSO authentication
+   */
   SSO_ENDPOINT_URL?: string;
+
+  /** 
+   * OAuth2 Client ID registered with the Identity Provider
+   * @example 'my-app-client-id'
+   * @required Required when using SSO authentication
+   */
   SSO_CLIENT_ID?: string;
+
+  /** 
+   * OAuth2 Client Secret for authentication
+   * @example 'super-secret-client-key'
+   * @required Required when using SSO authentication
+   */
   SSO_CLIENT_SECRET?: string;
+
+  /** 
+   * Redirect URL after successful SSO login
+   * @example '/dashboard' or 'https://myapp.com/home'
+   * @default '/'
+   */
   SSO_SUCCESS_URL?: string;
+
+  /** 
+   * Redirect URL after failed SSO login
+   * @example '/login?error=auth_failed'
+   * @default '/login'
+   */
   SSO_FAILURE_URL?: string;
 
-  /** Authentication mode: 'session' or 'token' (default: 'session') */
+  /** 
+   * Authentication mode: 'session' for cookie-based sessions, 'token' for JWT token-based auth
+   * @example 'session' | 'token'
+   * @default 'session'
+   */
   SESSION_MODE?: string;
 
+  /** 
+   * Session expiration time in seconds
+   * @example 3600 (1 hour) or 86400 (24 hours) or 64800 (18 hours)
+   * @default 64800 (18 hours)
+   */
   SESSION_AGE?: number;
+
+  /** 
+   * Cookie path for session cookies
+   * @example '/' for entire site or '/app' for specific path
+   * @default '/'
+   */
   SESSION_COOKIE_PATH?: string;
+
+  /** 
+   * Secret key used for signing session cookies (should be a strong random string)
+   * @example 'your-super-secret-session-key-change-this-in-production'
+   * @required Required for session-based authentication
+   */
   SESSION_SECRET?: string;
+
+  /** 
+   * Redis key prefix for storing session data
+   * @example 'myapp:session:' (will result in keys like 'myapp:session:user@example.com')
+   * @default 'sess:'
+   */
   SESSION_PREFIX?: string;
+
+  /** 
+   * Redis key name for storing session data
+   * @example 'user' (results in session.user containing user data)
+   * @default 'user'
+   */
   SESSION_KEY?: string;
+
+  /** 
+   * Redis key name for storing session expiry timestamp
+   * @example 'expires' (results in session.expires containing expiry time)
+   * @default 'expires'
+   */
   SESSION_EXPIRY_KEY?: string;
+
+  /** 
+   * Path to custom HTML template for token storage page (TOKEN mode only)
+   * @example './templates/token-storage.html'
+   * @default Built-in template included in the library
+   */
   TOKEN_STORAGE_TEMPLATE_PATH?: string;
 
+  /** 
+   * Redis connection URL
+   * @example 'redis://localhost:6379' or 'rediss://user:pass@host:6380/0' (rediss for TLS)
+   * @required Required when using Redis for session storage
+   */
   REDIS_URL?: string;
+
+  /** 
+   * Path to TLS certificate file for secure Redis connections
+   * @example '/path/to/redis-ca-cert.pem'
+   * @optional Only needed for TLS-enabled Redis connections
+   */
   REDIS_CERT_PATH?: string;
 
+  /** 
+   * JWE algorithm for token encryption
+   * @example 'dir' (Direct Key Agreement) or 'RSA-OAEP' or 'A256KW'
+   * @default 'dir'
+   * @see https://tools.ietf.org/html/rfc7518#section-4.1
+   */
   JWT_ALGORITHM?: string;
+
+  /** 
+   * JWE encryption method
+   * @example 'A256GCM' (AES-256 GCM) or 'A128GCM' or 'A192GCM'
+   * @default 'A256GCM'
+   * @see https://tools.ietf.org/html/rfc7518#section-5.1
+   */
   JWT_ENCRYPTION?: string;
+
+  /** 
+   * Clock tolerance in seconds for JWT token validation (allows for time drift between servers)
+   * @example 30 (allows 30 seconds of clock skew)
+   * @default 30
+   */
   JWT_CLOCK_TOLERANCE?: number;
+
+  /** 
+   * Hash algorithm for deriving encryption key from secret
+   * @example 'SHA-256' or 'SHA-384' or 'SHA-512'
+   * @default 'SHA-256'
+   */
   JWT_SECRET_HASH_ALGORITHM?: string;
+
+  /** 
+   * JWT issuer claim (iss) - identifies the principal that issued the token
+   * @example 'https://myapp.com' or 'my-auth-service'
+   * @optional Adds additional security validation
+   */
   JWT_ISSUER?: string;
+
+  /** 
+   * JWT audience claim (aud) - identifies the recipients that the token is intended for
+   * @example 'https://api.myapp.com' or 'my-api-service'
+   * @optional Adds additional security validation
+   */
   JWT_AUDIENCE?: string;
+
+  /** 
+   * JWT subject claim (sub) - identifies the principal that is the subject of the token
+   * @example 'user-authentication' or 'api-access'
+   * @optional Adds additional context to tokens
+   */
   JWT_SUBJECT?: string;
 }
 
@@ -144,8 +271,19 @@ export interface SessionUser {
 // Session Manager
 export class SessionManager {
   /**
-   * Constructor
-   * @param config - Session configuration (uses strict UPPERCASE property names)
+   * Create a new SessionManager instance
+   * @param config Session configuration object with UPPERCASE property names
+   * @example
+   * ```javascript
+   * const sessionManager = new SessionManager({
+   *   SSO_ENDPOINT_URL: 'https://idp.example.com/open/api/v1',
+   *   SSO_CLIENT_ID: 'my-app-client-id',
+   *   SSO_CLIENT_SECRET: 'secret-key',
+   *   SESSION_MODE: 'session', // or 'token' for JWT-based auth
+   *   SESSION_SECRET: 'your-session-secret',
+   *   REDIS_URL: 'redis://localhost:6379'
+   * });
+   * ```
    */
   constructor(config: SessionConfig);
 
@@ -312,75 +450,191 @@ export class RedisManager {
 
 // JWT Manager Configuration - uses strict UPPERCASE naming convention with JWT_ prefix for all property names
 export interface JwtManagerOptions {
-  /** JWE algorithm (default: 'dir') */
+  /** 
+   * JWE algorithm for token encryption
+   * @example 'dir' (Direct Key Agreement - symmetric encryption, recommended for most cases)
+   * @example 'RSA-OAEP' (RSA with OAEP padding - for asymmetric encryption)
+   * @example 'A256KW' (AES Key Wrap with 256-bit key)
+   * @default 'dir'
+   * @see https://tools.ietf.org/html/rfc7518#section-4.1
+   */
   JWT_ALGORITHM?: string;
 
-  /** JWE encryption method (default: 'A256GCM') */
+  /** 
+   * JWE content encryption method
+   * @example 'A256GCM' (AES-256 GCM - recommended, highest security)
+   * @example 'A128GCM' (AES-128 GCM - faster, lower security)
+   * @example 'A192GCM' (AES-192 GCM - balanced)
+   * @default 'A256GCM'
+   * @see https://tools.ietf.org/html/rfc7518#section-5.1
+   */
   JWT_ENCRYPTION?: string;
 
-  /** Clock tolerance in seconds for token validation (default: 30) */
+  /** 
+   * Token expiration time - accepts number (seconds) or string with time suffix
+   * @example 64800 (18 hours as number)
+   * @example '18h' (18 hours)
+   * @example '7d' (7 days)
+   * @example '1080m' (1080 minutes = 18 hours)
+   * @example '30s' (30 seconds)
+   * @default 64800 (18 hours)
+   */
+  JWT_EXPIRATION_TIME?: number | string;
+
+  /** 
+   * Clock tolerance in seconds for token validation
+   * Allows for small time differences between client and server clocks
+   * @example 30 (allows 30 seconds of clock drift)
+   * @example 60 (more lenient, allows 1 minute of drift)
+   * @default 30
+   */
   JWT_CLOCK_TOLERANCE?: number;
 
-  /** Hash algorithm for secret derivation (default: 'SHA-256') */
+  /** 
+   * Hash algorithm used for deriving encryption key from secret string
+   * @example 'SHA-256' (recommended for most cases)
+   * @example 'SHA-384' (higher security)
+   * @example 'SHA-512' (highest security, slower)
+   * @default 'SHA-256'
+   */
   JWT_SECRET_HASH_ALGORITHM?: string;
 
-  /** Optional JWT issuer claim */
+  /** 
+   * JWT issuer claim (iss) - identifies who issued the token
+   * Used for token validation to ensure tokens are from expected source
+   * @example 'https://myapp.com'
+   * @example 'my-auth-service'
+   * @optional Recommended for production environments
+   */
   JWT_ISSUER?: string;
 
-  /** Optional JWT audience claim */
+  /** 
+   * JWT audience claim (aud) - identifies the intended recipients
+   * Used for token validation to ensure tokens are for the correct service
+   * @example 'https://api.myapp.com'
+   * @example ['api.myapp.com', 'admin.myapp.com'] (can be array)
+   * @optional Recommended for production environments
+   */
   JWT_AUDIENCE?: string;
 
-  /** Optional JWT subject claim */
+  /** 
+   * JWT subject claim (sub) - identifies the principal (subject) of the token
+   * Provides context about what the token represents
+   * @example 'user-authentication'
+   * @example 'api-access-token'
+   * @optional Adds semantic meaning to tokens
+   */
   JWT_SUBJECT?: string;
 }
 
 /**
  * Options for encrypt() method - uses camelCase naming convention
+ * These options allow you to override the defaults set in JwtManagerOptions for specific encryption operations
  */
 export interface JwtEncryptOptions {
-  /** Override default algorithm */
+  /** 
+   * Override default JWE algorithm for this specific token
+   * @example 'dir' or 'RSA-OAEP'
+   * @use-case Use when you need different encryption algorithms for different token types
+   */
   algorithm?: string;
 
-  /** Override default encryption method */
+  /** 
+   * Override default encryption method for this specific token
+   * @example 'A256GCM' or 'A128GCM'
+   * @use-case Use when you need different encryption strength for different token types
+   */
   encryption?: string;
 
-  /** Override default expiration time */
-  expirationTime?: number;
+  /** 
+   * Override default expiration time for this specific token
+   * @example '1h' (short-lived token for sensitive operations)
+   * @example '30m' (half hour)
+   * @example '7d' (long-lived token for remember-me functionality)
+   * @example 3600 (1 hour as number in seconds)
+   * @use-case Use when different tokens need different lifetimes (e.g., access token vs refresh token)
+   */
+  expirationTime?: number | string;
 
-  /** Override default hash algorithm */
+  /** 
+   * Override default hash algorithm for deriving encryption key
+   * @example 'SHA-256' or 'SHA-512'
+   * @use-case Use when you need stronger hashing for specific high-security tokens
+   */
   secretHashAlgorithm?: string;
 
-  /** Override default issuer claim */
+  /** 
+   * Override default issuer claim for this specific token
+   * @example 'https://admin.myapp.com' (for admin tokens)
+   * @use-case Use when tokens are issued by different services
+   */
   issuer?: string;
 
-  /** Override default audience claim */
+  /** 
+   * Override default audience claim for this specific token
+   * @example 'https://api.myapp.com' (for API access tokens)
+   * @example ['service1.myapp.com', 'service2.myapp.com'] (multiple audiences)
+   * @use-case Use when tokens are intended for different services
+   */
   audience?: string;
 
-  /** Override default subject claim */
+  /** 
+   * Override default subject claim for this specific token
+   * @example 'password-reset' (for password reset tokens)
+   * @example 'email-verification' (for verification tokens)
+   * @use-case Use when different token types serve different purposes
+   */
   subject?: string;
 }
 
 /**
  * Options for decrypt() method - uses camelCase naming convention
+ * These options allow you to override validation settings and verify specific claims during decryption
  */
 export interface JwtDecryptOptions {
-  /** Override default clock tolerance */
+  /** 
+   * Override default clock tolerance for this specific token validation
+   * @example 30 (seconds) - allows 30 seconds of clock drift
+   * @example 60 (seconds) - more lenient for distributed systems
+   * @use-case Use when validating tokens from systems with known clock drift issues
+   */
   clockTolerance?: number;
 
-  /** Override default hash algorithm */
+  /** 
+   * Override default hash algorithm for deriving decryption key
+   * Must match the algorithm used during encryption
+   * @example 'SHA-256' or 'SHA-512'
+   * @use-case Use when tokens were encrypted with different hash algorithms
+   */
   secretHashAlgorithm?: string;
 
-  /** Expected issuer claim for validation */
+  /** 
+   * Expected issuer claim (iss) for validation
+   * Token will be rejected if issuer doesn't match
+   * @example 'https://myapp.com'
+   * @use-case Use to ensure tokens come from a specific trusted source
+   */
   issuer?: string;
 
-  /** Expected audience claim for validation */
+  /** 
+   * Expected audience claim (aud) for validation
+   * Token will be rejected if audience doesn't match
+   * @example 'https://api.myapp.com'
+   * @example ['service1.myapp.com', 'service2.myapp.com'] (multiple valid audiences)
+   * @use-case Use to ensure tokens are intended for your service
+   */
   audience?: string;
 
-  /** Expected subject claim for validation */
+  /** 
+   * Expected subject claim (sub) for validation
+   * Token will be rejected if subject doesn't match
+   * @example 'user-authentication'
+   * @use-case Use to validate tokens are of the expected type/purpose
+   */
   subject?: string;
 }
 
-export type JwtDecryptResult = JWTDecryptResult<EncryptJWT>;
+export type JwtDecryptResult = JWTDecryptResult;
 
 // JwtManager class for JWT encryption and decryption
 export class JwtManager {
@@ -396,6 +650,16 @@ export class JwtManager {
   /**
    * Create a new JwtManager instance with configurable defaults
    * @param options Configuration options (uses strict UPPERCASE with JWT_ prefix property names)
+   * @example
+   * ```javascript
+   * const jwtManager = new JwtManager({
+   *   JWT_ALGORITHM: 'dir',
+   *   JWT_ENCRYPTION: 'A256GCM',
+   *   JWT_EXPIRATION_TIME: '18h', // or 64800 seconds
+   *   JWT_ISSUER: 'https://myapp.com',
+   *   JWT_AUDIENCE: 'https://api.myapp.com'
+   * });
+   * ```
    */
   constructor(options?: JwtManagerOptions);
 
@@ -403,17 +667,31 @@ export class JwtManager {
    * Generate JWT token for user session
    * @param data User data payload
    * @param input Secret key or password for encryption
-   * @param options Per-call configuration overrides (uses strict UPPERCASE with JWT_ prefix property names)
+   * @param options Per-call configuration overrides (uses camelCase property names)
    * @returns Returns encrypted JWT token
    */
   encrypt(data: JWTPayload, input: string, options?: JwtEncryptOptions): Promise<string>;
 
   /**
-   * Decrypt JWT token for user session
-   * @param token JWT token to decrypt
-   * @param input Secret key or password for decryption
-   * @param options Per-call configuration overrides (uses strict UPPERCASE with JWT_ prefix property names)
-   * @returns Returns decrypted JWT token
+   * Decrypt and validate JWT token for user session
+   * @param token JWT token string to decrypt and validate
+   * @param input Secret key or password for decryption (must match the key used for encryption)
+   * @param options Per-call validation overrides (uses camelCase property names)
+   * @returns Returns decrypted JWT token result containing payload and protected header
+   * @throws Will throw error if token is invalid, expired, or validation fails
+   * @example
+   * ```javascript
+   * try {
+   *   const result = await jwtManager.decrypt(
+   *     tokenString,
+   *     'my-secret-key',
+   *     { issuer: 'https://myapp.com' } // Optional: validate issuer claim
+   *   );
+   *   console.log(result.payload); // Access decrypted data
+   * } catch (error) {
+   *   console.error('Token validation failed:', error.message);
+   * }
+   * ```
    */
   decrypt(token: string, input: string, options?: JwtDecryptOptions): Promise<JwtDecryptResult>;
 }
@@ -533,4 +811,4 @@ declare module 'express-session' {
     [key: string]: any;
     user?: SessionUser;
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@igxjs/node-components",
-  "version": "1.0.12",
+  "version": "1.0.14",
   "description": "Node components for igxjs",
   "main": "index.js",
   "type": "module",
@@ -12,7 +12,21 @@
     "url": "git+https://github.com/igxjs/node-components.git"
   },
   "keywords": [
-    "igxjs"
+    "igxjs",
+    "express",
+    "session-management",
+    "jwt",
+    "jwe",
+    "redis",
+    "authentication",
+    "sso",
+    "oauth",
+    "middleware",
+    "node-components",
+    "session",
+    "token-auth",
+    "bearer-token",
+    "express-middleware"
   ],
   "author": "Michael",
   "license": "Apache-2.0",
@@ -20,6 +34,9 @@
     "url": "https://github.com/igxjs/node-components/issues"
   },
   "homepage": "https://github.com/igxjs/node-components#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "dependencies": {
     "@redis/client": "^5.11.0",
     "@types/express": "^5.0.6",
@@ -31,11 +48,18 @@
   },
   "devDependencies": {
     "chai": "^6.2.2",
-    "express": "^5.2.1",
     "mocha": "^12.0.0-beta-10",
     "sinon": "^21.0.3",
     "supertest": "^7.0.0"
   },
+  "peerDependencies": {
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": false
+    }
+  },
   "files": [
     "index.js",
     "index.d.ts",