@igxjs/node-components 1.0.6 → 1.0.8

package/README.md

@@ -1,6 +1,6 @@
 # Node Components
 
-Shared components for Express.js applications providing session management, routing utilities, error handling, and Redis integration.
+Shared components for Express.js applications providing session management, routing utilities, error handling, JWT authentication, and Redis integration.
 
 ## Installation
 
@@ -8,349 +8,112 @@ Shared components for Express.js applications providing session management, rout
 npm install @igxjs/node-components
 ```
 
-## Modules
+## Components
 
-### 1. Session Manager
+| Component | Description | Documentation |
+|-----------|-------------|---------------|
+| **SessionManager** | SSO session management with Redis/memory storage | [View docs](./docs/session-manager.md) |
+| **FlexRouter** | Flexible routing with context paths and middleware | [View docs](./docs/flex-router.md) |
+| **RedisManager** | Redis connection management with TLS support | [View docs](./docs/redis-manager.md) |
+| **JWT Manager** | Secure JWT encryption/decryption with JWE | [View docs](./docs/jwt-manager.md) |
+| **HTTP Handlers** | Standardized error handling and status codes | [View docs](./docs/http-handlers.md) |
 
-Provides SSO (Single Sign-On) session management with support for Redis and memory-based session stores.
+## Quick Start Examples
 
-#### Configuration Options
+### SessionManager
 
 ```javascript
-// Example configuration object
-// All fields are strings except SESSION_AGE which is a number
-
-const config = {
-  // SSO Configuration
-  SSO_ENDPOINT_URL: 'https://sso.example.com',
-  SSO_CLIENT_ID: 'your-client-id',
-  SSO_CLIENT_SECRET: 'your-client-secret',
-  SSO_SUCCESS_URL: '/dashboard',
-  SSO_FAILURE_URL: '/login',
-  
-  // Session Configuration
-  SESSION_AGE: 64800000, // 18 hours in milliseconds
-  SESSION_COOKIE_PATH: '/',
-  SESSION_SECRET: 'your-session-secret',
-  SESSION_PREFIX: 'ibmid:',  // Default value when not provided
-  
-  // Redis Configuration (optional - uses memory store if not provided)
-  REDIS_URL: 'redis://localhost:6379',
-  REDIS_CERT_PATH: '/path/to/cert.pem' // For TLS connections
-};
-```
-
-#### Usage Example
-
-```javascript
-import express from 'express';
 import { SessionManager } from '@igxjs/node-components';
 
-const app = express();
-const session = new SessionManager(config);
-
-// Initialize session
-await session.setup(app, (user) => {
-  // Process user object - compute permissions, avatar URL, etc.
-  return {
-    ...user,
-    displayName: user.email?.split('@')[0],
-    hasAdminAccess: user.authorized && user.email?.endsWith('@admin.com')
-  };
+// Create singleton instance
+export const session = new SessionManager({
+  SSO_ENDPOINT_URL: process.env.SSO_ENDPOINT_URL,
+  SSO_CLIENT_ID: process.env.SSO_CLIENT_ID,
+  SSO_CLIENT_SECRET: process.env.SSO_CLIENT_SECRET,
+  SESSION_SECRET: process.env.SESSION_SECRET,
+  REDIS_URL: process.env.REDIS_URL
 });
 
-// Protect routes with authentication
+// Setup in your app
+await session.setup(app, (user) => ({ ...user, displayName: user.email }));
+
+// Protect routes
 app.get('/protected', session.authenticate(), (req, res) => {
   res.json({ user: req.user });
 });
-
-// SSO callback endpoint
-app.get('/auth/callback', session.callback((user) => {
-  // Initialize user object after successful login
-  return {
-    ...user,
-    loginTime: new Date()
-  };
-}));
-
-// Get available identity providers
-app.get('/auth/providers', session.identityProviders());
-
-// Refresh user session
-app.post('/auth/refresh', session.refresh((user) => {
-  return { ...user, refreshedAt: new Date() };
-}));
-
-// Logout endpoint
-app.get('/auth/logout', session.logout());
 ```
 
-#### API Methods
-
-- **`setup(app, updateUser)`** - Initialize session configurations
-- **`authenticate(isDebugging?, redirectUrl?)`** - Resource protection middleware
-- **`callback(initUser)`** - SSO callback handler for successful login
-- **`identityProviders()`** - Get available identity providers
-- **`logout()`** - Application logout handler (not SSO logout)
-- **`refresh(initUser)`** - Refresh user session with new token
-- **`redisManager()`** - Get the RedisManager instance (returns RedisManager or null)
-- **`hasLock(email)`** - Check if email has a session refresh lock
-- **`lock(email)`** - Lock email for session refresh (prevents concurrent refreshes)
-- **`clearLocks()`** - Clear expired session refresh locks
-
----
-
-### 2. FlexRouter
+[📖 Full SessionManager Documentation](./docs/session-manager.md)
 
-A flexible routing utility for Express.js that allows mounting routers with custom context paths and middleware handlers.
-
-#### Usage Example
+### FlexRouter
 
 ```javascript
 import { Router } from 'express';
 import { FlexRouter } from '@igxjs/node-components';
-// Assuming you have an authenticate middleware
-// import { authenticate } from './middlewares/auth.js';
-
-// Create routers
-const publicRouter = Router();
-const privateRouter = Router();
-
-publicRouter.get('/health', (req, res) => {
-  res.send('OK');
-});
 
-privateRouter.get('/users', (req, res) => {
-  res.json({ users: [] });
-});
-
-// Define flex routers with context paths and optional middleware
-export const routers = [
-  new FlexRouter('/api/v1/public', publicRouter),
-  new FlexRouter('/api/v1/protected', privateRouter, [authenticate]), // with middleware
-];
+const apiRouter = Router();
+apiRouter.get('/users', (req, res) => res.json({ users: [] }));
 
-// Mount all routers to your Express app
-const app = express();
-const basePath = '';
-
-routers.forEach(router => {
-  router.mount(app, basePath);
-});
-
-// Routes will be available at:
-// - /api/v1/public/health
-// - /api/v1/protected/users (with authenticate middleware)
-```
-
-#### API
-
-- **`constructor(context, router, handlers?)`** - Create a new FlexRouter
-  - `context` (string) - The context path for the router
-  - `router` - Express Router instance
-  - `handlers` - Optional array of middleware handlers
-  
-- **`mount(app, basePath)`** - Mount the router to an Express application
-  - `app` - Express application instance
-  - `basePath` (string) - Base path to prepend to the context
-
----
-
-### 3. RedisManager
-
-Redis connection management with TLS support and automatic reconnection handling.
-
-* Note: the RedisManager is used internally by the `SessionManager`, so you don't need to use it directly.
-
-#### Usage Example
-
-```javascript
-import { RedisManager } from '@igxjs/node-components';
-
-const redisManager = new RedisManager();
-
-// Connect to Redis (with optional TLS certificate)
-const connected = await redisManager.connect(
-  'rediss://localhost:6379',
-  '/path/to/cert.pem'
-);
-
-if (connected) {
-  // Get Redis client for direct operations
-  const client = redisManager.getClient();
-  await client.set('key', 'value');
-  
-  // Check connection status
-  const isConnected = await redisManager.isConnected();
-  
-  // Disconnect when done
-  await redisManager.disConnect();
-}
+// Mount with context path and middleware
+const flexRouter = new FlexRouter('/api/v1', apiRouter, [authenticate]);
+flexRouter.mount(app, '');
 ```
 
-#### API Methods
-
-- **`connect(redisUrl, certPath)`** - Connect to Redis server
-  - Returns: `Promise<boolean>` - Returns true if connected successfully
-  - Supports both `redis://` and `rediss://` (TLS) URLs
-  - Automatically handles TLS certificate loading when using `rediss://`
-
-- **`getClient()`** - Get the Redis client instance
-  - Returns: Redis client for direct operations
-
-- **`isConnected()`** - Check if Redis connection is active
-  - Returns: `Promise<boolean>` - Returns true if connected and responsive
-
-- **`disConnect()`** - Disconnect from Redis server
-  - Returns: `Promise<void>`
-
----
+[📖 Full FlexRouter Documentation](./docs/flex-router.md)
 
-### 4. HTTP Handlers
-
-Custom error handling utilities with standardized HTTP status codes and error responses.
-
-#### Available Exports
+### JWT Manager
 
 ```javascript
-import { 
-  CustomError, 
-  httpErrorHandler, 
-  httpCodes, 
-  httpMessages,
-  httpHelper 
-} from '@igxjs/node-components';
-```
+import { JwtManager } from '@igxjs/node-components';
 
-#### Usage Examples
+const jwt = new JwtManager({ expirationTime: '1h' });
+const SECRET = process.env.JWT_SECRET;
 
-**Creating Custom Errors:**
+// Create token
+const token = await jwt.encrypt({ userId: '123', email: 'user@example.com' }, SECRET);
 
-```javascript
-// Basic custom error
-throw new CustomError(httpCodes.BAD_REQUEST, 'Invalid input data');
-
-// With error details and additional data
-throw new CustomError(
-  httpCodes.UNAUTHORIZED,
-  'Authentication failed',
-  { originalError: err },
-  { attemptedEmail: email }
-);
+// Verify token
+const { payload } = await jwt.decrypt(token, SECRET);
 ```
 
-**Handling Axios/HTTP Errors:**
+[📖 Full JWT Manager Documentation](./docs/jwt-manager.md)
 
-```javascript
-// Use httpHelper to handle Axios errors
-try {
-  await axios.get('https://api.example.com/data');
-} catch (error) {
-  // Convert Axios error to CustomError
-  throw httpHelper.handleAxiosError(error, 'Failed to fetch data');
-}
-
-// Or use it in error handling
-app.get('/api/data', async (req, res, next) => {
-  try {
-    const response = await axios.get('https://external-api.com/data');
-    res.json(response.data);
-  } catch (error) {
-    return next(httpHelper.handleAxiosError(error, 'Failed to fetch external data'));
-  }
-});
-```
-
-**Error Handler Middleware:**
+### HTTP Handlers
 
 ```javascript
-import express from 'express';
-import { httpErrorHandler } from '@igxjs/node-components';
-
-const app = express();
+import {
+  httpCodes,
+  httpError,
+  httpErrorHandler,
+  httpNotFoundHandler
+} from '@igxjs/node-components';
 
-// Your routes here
+// Use in routes
 app.get('/api/data', async (req, res, next) => {
   try {
-    // Your logic
+    const data = await fetchData();
+    res.json(data);
   } catch (error) {
-    next(error);
+    next(httpError(httpCodes.SYSTEM_FAILURE, 'Failed to fetch data', error));
   }
 });
 
-// Add error handler as the last middleware
+// Add middleware
+app.use(httpNotFoundHandler);
 app.use(httpErrorHandler);
 ```
 
-#### HTTP Codes & Messages
-
-```javascript
-httpCodes.OK               // 200
-httpCodes.CREATED          // 201
-httpCodes.NO_CONTENT       // 204
-httpCodes.BAD_REQUEST      // 400
-httpCodes.UNAUTHORIZED     // 401
-httpCodes.FORBIDDEN        // 403
-httpCodes.NOT_FOUND        // 404
-httpCodes.NOT_ACCEPTABLE   // 406
-httpCodes.CONFLICT         // 409
-httpCodes.SYSTEM_FAILURE   // 500
-httpCodes.NOT_IMPLEMENTED  // 501
-
-// Corresponding messages
-httpMessages.OK            // 'OK'
-httpMessages.BAD_REQUEST   // 'Bad Request'
-// ... etc
-```
-
-#### CustomError API
-
-**Constructor:**
-```javascript
-// new CustomError(code, message, error, data)
-// - code: number - HTTP status code
-// - message: string - Error message
-// - error: object (optional) - Original error object
-// -  object (optional) - Additional error data
-```
-
-**Properties:**
-- **`code`** - HTTP status code (number)
-- **`message`** - Error message (string)
-- **`error`** - Original error object (if provided)
-- **`data`** - Additional error data (if provided)
-
-#### httpHelper API
-
-The `httpHelper` object provides utility methods for error handling:
-
-**Methods:**
-
-- **`httpHelper.handleAxiosError(error, defaultMessage)`** - Analyze and convert Axios/HTTP errors to CustomError
-  - `error` (Error | AxiosError) - The error object to analyze
-  - `defaultMessage` (string, optional) - Default message if error message cannot be extracted (default: 'An error occurred')
-  - Returns: `CustomError` instance with extracted status code, message, and data
-
-- **`httpHelper.format(str, ...args)`** - Format a string with placeholders
-  - `str` (string) - String with `{0}`, `{1}`, etc. placeholders
-  - `...args` - Values to replace placeholders
-  - Returns: Formatted string
-
-- **`httpHelper.toZodMessage(error)`** - Generate friendly Zod validation error message
-  - `error` (ZodError) - Zod validation error
-  - Returns: Formatted error message string
-
----
+[📖 Full HTTP Handlers Documentation](./docs/http-handlers.md)
 
 ## Features
 
-- ✅ **Session Management** - Full SSO integration with Redis or memory storage
-- ✅ **Flexible Routing** - Easy mounting of routers with context paths and middleware
-- ✅ **Redis Integration** - Robust Redis connection management with TLS support
-- ✅ **Error Handling** - Standardized error responses and HTTP status codes
-- ✅ **TypeScript Support** - Complete type definitions included
-- ✅ **Session Locking** - Prevents concurrent session refresh operations
-- ✅ **Automatic Reconnection** - Redis auto-reconnect with event handling
+- ✅ **SSO Integration** - Full SSO support with Redis or memory storage
+- ✅ **JWT Security** - Encrypted JWT tokens using JWE (jose library)
+- ✅ **Flexible Routing** - Easy mounting with context paths and middleware
+- ✅ **Redis Support** - TLS/SSL and automatic reconnection
+- ✅ **Error Handling** - Standardized HTTP responses
+- ✅ **TypeScript** - Complete type definitions included
+- ✅ **Production Ready** - Session locking, auto-reconnection, error handling
 
 ## Requirements
 
@@ -358,22 +121,31 @@ The `httpHelper` object provides utility methods for error handling:
 - Express.js >= 4.x
 - Redis (optional, for session storage)
 
-## TypeScript
+## TypeScript Support
 
-This package includes TypeScript definitions. You can import types in TypeScript projects:
+This package includes TypeScript definitions:
 
 ```typescript
 import type { 
-  SessionConfig, 
   SessionManager,
-  SessionUser,
-  SessionUserAttributes,
+  SessionConfig,
+  JwtManager,
   FlexRouter,
   RedisManager,
   CustomError 
 } from '@igxjs/node-components';
 ```
 
+## Documentation
+
+📚 **[Complete Documentation](./docs/README.md)** - Detailed guides for all components
+
+- [SessionManager Documentation](./docs/session-manager.md) - Comprehensive SSO session management guide
+- [FlexRouter Documentation](./docs/flex-router.md) - Advanced routing patterns
+- [RedisManager Documentation](./docs/redis-manager.md) - Redis connection management
+- [JWT Manager Documentation](./docs/jwt-manager.md) - Token authentication guide
+- [HTTP Handlers Documentation](./docs/http-handlers.md) - Error handling utilities
+
 ## License
 
-[Apache 2.0](LICENSE.md)
+[Apache 2.0](LICENSE)

package/components/http-handlers.js

@@ -10,6 +10,7 @@ export const httpMessages = {
   NOT_FOUND: 'Not Found',
   NOT_ACCEPTABLE: 'Not Acceptable',
   CONFLICT: 'Conflict',
+  LOCKED: 'Locked',
   SYSTEM_FAILURE: 'System Error',
   NOT_IMPLEMENTED: 'Not Implemented',
 };
@@ -17,13 +18,14 @@ export const httpMessages = {
 export const httpCodes = {
   OK: 200,
   CREATED: 201,
-  NO_CONTENT: 201,
+  NO_CONTENT: 204,
   BAD_REQUEST: 400,
   UNAUTHORIZED: 401,
   FORBIDDEN: 403,
   NOT_FOUND: 404,
   NOT_ACCEPTABLE: 406,
   CONFLICT: 409,
+  LOCKED: 423,
   SYSTEM_FAILURE: 500,
   NOT_IMPLEMENTED: 501,
 };

package/components/jwt.js

@@ -0,0 +1,104 @@
+import { jwtDecrypt, EncryptJWT } from 'jose';
+
+export class JwtManager {
+  /**
+   * Create a new JwtManager instance with configurable defaults
+   * @param {Object} options Configuration options
+   * @param {string} [options.algorithm='dir'] JWE algorithm (e.g., 'dir', 'A128KW', 'A192KW', 'A256KW')
+   * @param {string} [options.encryption='A256GCM'] JWE encryption method (e.g., 'A256GCM', 'A128GCM', 'A192GCM')
+   * @param {string} [options.expirationTime='10m'] Token expiration time (e.g., '10m', '1h', '7d')
+   * @param {number} [options.clockTolerance=30] Clock tolerance in seconds for token validation
+   * @param {string} [options.secretHashAlgorithm='SHA-256'] Hash algorithm for secret derivation
+   * @param {string} [options.issuer] Optional JWT issuer claim
+   * @param {string} [options.audience] Optional JWT audience claim
+   * @param {string} [options.subject] Optional JWT subject claim
+   */
+  constructor(options = {}) {
+    this.algorithm = options.algorithm || 'dir';
+    this.encryption = options.encryption || 'A256GCM';
+    this.expirationTime = options.expirationTime || '10m';
+    this.clockTolerance = options.clockTolerance ?? 30;
+    this.secretHashAlgorithm = options.secretHashAlgorithm || 'SHA-256';
+    this.issuer = options.issuer;
+    this.audience = options.audience;
+    this.subject = options.subject;
+  }
+
+  /**
+   * Generate JWT token for user session
+   * @param {import('jose').JWTPayload} data User data payload
+   * @param {string} secret Secret key or password for encryption
+   * @param {Object} [options] Per-call configuration overrides
+   * @param {string} [options.algorithm] Override default algorithm
+   * @param {string} [options.encryption] Override default encryption method
+   * @param {string} [options.expirationTime] Override default expiration time
+   * @param {string} [options.secretHashAlgorithm] Override default hash algorithm
+   * @param {string} [options.issuer] Override default issuer claim
+   * @param {string} [options.audience] Override default audience claim
+   * @param {string} [options.subject] Override default subject claim
+   * @returns {Promise<string>} Returns encrypted JWT token
+   */
+  async encrypt(data, secret, options = {}) {
+    const algorithm = options.algorithm || this.algorithm;
+    const encryption = options.encryption || this.encryption;
+    const expirationTime = options.expirationTime || this.expirationTime;
+    const secretHashAlgorithm = options.secretHashAlgorithm || this.secretHashAlgorithm;
+    const issuer = options.issuer || this.issuer;
+    const audience = options.audience || this.audience;
+    const subject = options.subject || this.subject;
+
+    const secretHash = await crypto.subtle.digest(
+      secretHashAlgorithm,
+      new TextEncoder().encode(secret)
+    );
+
+    const jwt = new EncryptJWT(data)
+      .setProtectedHeader({
+        alg: algorithm,
+        enc: encryption
+      })
+      .setIssuedAt()
+      .setExpirationTime(expirationTime);
+
+    // Add optional claims if provided
+    if (issuer) jwt.setIssuer(issuer);
+    if (audience) jwt.setAudience(audience);
+    if (subject) jwt.setSubject(subject);
+
+    return await jwt.encrypt(new Uint8Array(secretHash));
+  }
+
+  /**
+   * Decrypt JWT token for user session
+   * @param {string} token JWT token to decrypt
+   * @param {string} secret Secret key or password for decryption
+   * @param {Object} [options] Per-call configuration overrides
+   * @param {number} [options.clockTolerance] Override default clock tolerance
+   * @param {string} [options.secretHashAlgorithm] Override default hash algorithm
+   * @param {string} [options.issuer] Expected issuer claim for validation
+   * @param {string} [options.audience] Expected audience claim for validation
+   * @param {string} [options.subject] Expected subject claim for validation
+   * @returns {Promise<import('jose').JWTDecryptResult<import('jose').EncryptJWT>>} Returns decrypted JWT token
+   */
+  async decrypt(token, secret, options = {}) {
+    const clockTolerance = options.clockTolerance ?? this.clockTolerance;
+    const secretHashAlgorithm = options.secretHashAlgorithm || this.secretHashAlgorithm;
+    const issuer = options.issuer || this.issuer;
+    const audience = options.audience || this.audience;
+    const subject = options.subject || this.subject;
+
+    const secretHash = await crypto.subtle.digest(
+      secretHashAlgorithm,
+      new TextEncoder().encode(secret)
+    );
+
+    const decryptOptions = { clockTolerance };
+
+    // Add optional claim validations if provided
+    if (issuer) decryptOptions.issuer = issuer;
+    if (audience) decryptOptions.audience = audience;
+    if (subject) decryptOptions.subject = subject;
+
+    return await jwtDecrypt(token, new Uint8Array(secretHash), decryptOptions);
+  }
+}

package/docs/README.md

@@ -0,0 +1,54 @@
+# Node Components Documentation
+
+Detailed documentation for `@igxjs/node-components` - shared components for Express.js applications.
+
+## 📚 Component Documentation
+
+### Core Modules
+
+- **[SessionManager](./session-manager.md)** - SSO session management with Redis and memory storage
+  - Configuration options and singleton pattern
+  - Complete setup and usage examples
+  - API reference for all methods
+
+- **[FlexRouter](./flex-router.md)** - Flexible routing utility for Express.js
+  - Context path and middleware management
+  - API versioning and route organization
+  - Advanced usage patterns
+
+- **[RedisManager](./redis-manager.md)** - Redis connection management
+  - TLS/SSL support
+  - Connection monitoring and error handling
+  - Direct Redis operations
+
+- **[JWT Manager](./jwt-manager.md)** - JWT encryption and decryption
+  - Secure token-based authentication
+  - Express.js integration patterns
+  - Refresh token implementation
+
+- **[HTTP Handlers](./http-handlers.md)** - Standardized error handling
+  - Custom error classes and middleware
+  - HTTP status codes and messages
+  - Axios error handling and validation helpers
+
+## 🚀 Quick Links
+
+- [Main README](../README.md) - Package overview and installation
+- [GitHub Repository](https://github.com/igxjs/node-components)
+
+## 💡 Getting Help
+
+If you need help:
+1. Check the relevant component documentation above
+2. Review the examples in each guide
+3. Look at the type definitions in `index.d.ts`
+4. Open an issue on GitHub
+
+## 📖 Documentation Structure
+
+Each component documentation includes:
+- Overview of features
+- Configuration options
+- Basic and advanced usage examples
+- Complete API reference
+- Related documentation links