@igxjs/node-components 1.0.7 → 1.0.8

package/docs/jwt-manager.md

@@ -0,0 +1,124 @@
+# JWT Manager
+
+Provides JWT (JSON Web Token) encryption and decryption utilities using the `jose` library with JWE (JSON Web Encryption) for secure token management.
+
+## Overview
+
+JwtManager provides secure token-based authentication using:
+- JWE (JSON Web Encryption) for encrypted tokens
+- Configurable expiration times
+- Standard JWT claims (issuer, audience, subject)
+- Clock tolerance for time synchronization issues
+- Easy integration with Express.js applications
+
+## Configuration Options
+
+```javascript
+// Example configuration object
+const jwtOptions = {
+  algorithm: 'dir',              // JWE algorithm (default: 'dir')
+  encryption: 'A256GCM',         // JWE encryption method (default: 'A256GCM')
+  expirationTime: '10m',         // Token expiration (default: '10m')
+  clockTolerance: 30,            // Clock tolerance in seconds (default: 30)
+  secretHashAlgorithm: 'SHA-256', // Hash algorithm for secret derivation (default: 'SHA-256')
+  issuer: 'your-app',            // Optional JWT issuer claim
+  audience: 'your-users',        // Optional JWT audience claim
+  subject: 'user-session'        // Optional JWT subject claim
+};
+```
+
+## Basic Usage
+
+```javascript
+import { JwtManager } from '@igxjs/node-components';
+
+// Create instance with default configuration
+const jwtManager = new JwtManager({
+  expirationTime: '1h',
+  issuer: 'my-app',
+  audience: 'my-users'
+});
+
+// Encrypt user data
+const userData = {
+  userId: '12345',
+  email: 'user@example.com',
+  roles: ['admin', 'user']
+};
+
+const secret = 'your-secret-key';
+const token = await jwtManager.encrypt(userData, secret);
+
+console.log('Encrypted Token:', token);
+
+// Decrypt token
+try {
+  const result = await jwtManager.decrypt(token, secret);
+  console.log('Decrypted Payload:', result.payload);
+  console.log('Protected Header:', result.protectedHeader);
+} catch (error) {
+  console.error('Token validation failed:', error);
+}
+```
+
+## API Reference
+
+### Constructor
+
+**`new JwtManager(options?)`**
+
+Create a new JwtManager instance. All options are optional with sensible defaults.
+
+**Parameters:**
+- `options` (JwtManagerOptions, optional) - Configuration options
+
+### Methods
+
+#### `encrypt(data, input, options?)`
+
+Generate an encrypted JWT token.
+
+**Parameters:**
+- `data` (JWTPayload) - User data payload to encrypt
+- `input` (string) - Secret key or password for encryption
+- `options` (JwtEncryptOptions, optional) - Per-call configuration overrides
+
+**Returns:** `Promise<string>` - Encrypted JWT token
+
+#### `decrypt(token, input, options?)`
+
+Decrypt and validate a JWT token.
+
+**Parameters:**
+- `token` (string) - JWT token to decrypt
+- `input` (string) - Secret key or password for decryption
+- `options` (JwtDecryptOptions, optional) - Per-call configuration overrides
+
+**Returns:** `Promise<JWTDecryptResult>` - Object containing `payload` and `protectedHeader`
+
+## Configuration Details
+
+### Algorithms
+- `'dir'` (default) - Direct encryption with shared symmetric key
+- `'A128KW'`, `'A192KW'`, `'A256KW'` - AES Key Wrap algorithms
+
+### Encryption Methods
+- `'A256GCM'` (default) - AES-GCM with 256-bit key
+- `'A128GCM'`, `'A192GCM'` - AES-GCM with 128/192-bit keys
+
+### Expiration Time Format
+- `'10m'` - 10 minutes
+- `'1h'` - 1 hour
+- `'7d'` - 7 days
+- `'30s'` - 30 seconds
+
+### JWT Claims
+- `issuer` (iss) - Token issuer identification
+- `audience` (aud) - Intended token recipient
+- `subject` (sub) - Token subject (usually user ID)
+
+## Related Documentation
+
+- [SessionManager](./session-manager.md) - For SSO-based session management
+- [HTTP Handlers](./http-handlers.md) - For error handling in authentication flows
+- [Back to main documentation](../README.md)

package/docs/redis-manager.md

@@ -0,0 +1,210 @@
+# RedisManager
+
+Redis connection management with TLS support and automatic reconnection handling.
+
+## Overview
+
+RedisManager provides a robust Redis client with:
+- TLS/SSL support for secure connections
+- Automatic reconnection handling
+- Connection status monitoring
+- Clean disconnection management
+
+**Note:** RedisManager is used internally by the [SessionManager](./session-manager.md), so you typically don't need to use it directly unless you need custom Redis operations.
+
+## 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');
+  const value = await client.get('key');
+  console.log(value); // 'value'
+  
+  // Check connection status
+  const isConnected = await redisManager.isConnected();
+  console.log('Connected:', isConnected);
+  
+  // Disconnect when done
+  await redisManager.disConnect();
+}
+```
+
+## Connection URLs
+
+RedisManager supports two URL formats:
+
+### Standard Redis (non-TLS)
+```javascript
+await redisManager.connect('redis://localhost:6379');
+await redisManager.connect('redis://username:password@host:6379');
+```
+
+### Secure Redis (TLS)
+```javascript
+// Requires certificate path for TLS
+await redisManager.connect(
+  'rediss://localhost:6379',
+  '/path/to/certificate.pem'
+);
+```
+
+## Advanced Usage
+
+### Custom Operations
+
+```javascript
+import { RedisManager } from '@igxjs/node-components';
+
+const redisManager = new RedisManager();
+await redisManager.connect(process.env.REDIS_URL);
+
+const client = redisManager.getClient();
+
+// String operations
+await client.set('user:1', JSON.stringify({ name: 'John' }));
+const user = JSON.parse(await client.get('user:1'));
+
+// Hash operations
+await client.hSet('user:2', 'name', 'Jane');
+await client.hSet('user:2', 'email', 'jane@example.com');
+const userData = await client.hGetAll('user:2');
+
+// List operations
+await client.lPush('tasks', 'task1');
+await client.lPush('tasks', 'task2');
+const tasks = await client.lRange('tasks', 0, -1);
+
+// Set operations
+await client.sAdd('tags', 'javascript');
+await client.sAdd('tags', 'nodejs');
+const tags = await client.sMembers('tags');
+
+// Expiration
+await client.setEx('temporary', 3600, 'expires in 1 hour');
+await client.expire('user:1', 3600);
+
+// Clean up
+await redisManager.disConnect();
+```
+
+### Connection Monitoring
+
+```javascript
+const redisManager = new RedisManager();
+
+// Check if connected before operations
+if (await redisManager.isConnected()) {
+  const client = redisManager.getClient();
+  // Perform operations
+} else {
+  console.log('Redis not connected');
+}
+```
+
+### Error Handling
+
+```javascript
+const redisManager = new RedisManager();
+
+try {
+  const connected = await redisManager.connect(process.env.REDIS_URL);
+  
+  if (!connected) {
+    console.error('Failed to connect to Redis');
+    // Fall back to memory storage or handle appropriately
+    return;
+  }
+  
+  const client = redisManager.getClient();
+  await client.set('key', 'value');
+  
+} catch (error) {
+  console.error('Redis operation failed:', error);
+} finally {
+  await redisManager.disConnect();
+}
+```
+
+## API Methods
+
+### `connect(redisUrl, certPath?)`
+
+Connect to Redis server.
+
+**Parameters:**
+- `redisUrl` (string) - Redis connection URL (`redis://` or `rediss://`)
+- `certPath` (string, optional) - Path to TLS certificate file (required for `rediss://`)
+
+**Returns:** `Promise<boolean>` - Returns `true` if connected successfully
+
+**Example:**
+```javascript
+// Non-TLS connection
+await redisManager.connect('redis://localhost:6379');
+
+// TLS connection
+await redisManager.connect('rediss://localhost:6379', '/path/to/cert.pem');
+```
+
+### `getClient()`
+
+Get the Redis client instance for direct operations.
+
+**Returns:** Redis client object
+
+**Example:**
+```javascript
+const client = redisManager.getClient();
+await client.set('key', 'value');
+await client.get('key');
+```
+
+### `isConnected()`
+
+Check if Redis connection is active and responsive.
+
+**Returns:** `Promise<boolean>` - Returns `true` if connected and responsive
+
+**Example:**
+```javascript
+const connected = await redisManager.isConnected();
+if (connected) {
+  // Proceed with operations
+}
+```
+
+### `disConnect()`
+
+Disconnect from Redis server and clean up resources.
+
+**Returns:** `Promise<void>`
+
+**Example:**
+```javascript
+await redisManager.disConnect();
+```
+
+## Features
+
+- **Automatic Reconnection**: Handles connection drops and reconnects automatically
+- **TLS Support**: Secure connections with certificate-based authentication
+- **Connection Pooling**: Efficient connection management
+- **Error Handling**: Graceful error handling and logging
+- **Health Checks**: Built-in connection status monitoring
+
+## Related Documentation
+
+- [SessionManager](./session-manager.md) - Uses RedisManager for session storage
+- [Back to main documentation](../README.md)

package/docs/session-manager.md

@@ -0,0 +1,160 @@
+# SessionManager
+
+Provides SSO (Single Sign-On) session management with support for Redis and memory-based session stores.
+
+## Configuration Options
+
+```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
+};
+```
+
+## ⚠️ Important: Singleton Pattern
+
+**SessionManager should be instantiated once and exported as a singleton.** 
+
+**Why?**
+- SessionManager manages Redis connections (if configured)
+- Multiple instances can lead to connection pool exhaustion
+- Session state consistency requires a single source of truth
+- Middleware functions need to reference the same instance
+
+**✅ Recommended:** Create a separate module that exports a single SessionManager instance  
+**❌ Avoid:** Creating new SessionManager instances in multiple files
+
+## Recommended File Structure
+
+```
+your-project/
+├── src/
+│   ├── config/
+│   │   └── session-manager.js  ← Create SessionManager singleton here
+│   ├── routes/
+│   │   └── auth.js             ← Import session from config
+│   └── app.js                  ← Import and setup session
+└── package.json
+```
+
+## Usage Example
+
+### Step 1: Create SessionManager Singleton
+
+Create a dedicated file for your SessionManager instance:
+
+```javascript
+// config/session-manager.js
+import { SessionManager } from '@igxjs/node-components';
+
+// Create and export a single SessionManager 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,
+  SSO_SUCCESS_URL: '/dashboard',
+  SSO_FAILURE_URL: '/login',
+  SESSION_AGE: 64800000, // 18 hours in milliseconds
+  SESSION_COOKIE_PATH: '/',
+  SESSION_SECRET: process.env.SESSION_SECRET,
+  SESSION_PREFIX: 'ibmid:',
+  REDIS_URL: process.env.REDIS_URL,
+  REDIS_CERT_PATH: process.env.REDIS_CERT_PATH
+});
+```
+
+### Step 2: Setup and Use in Your Application
+
+Import and use the singleton instance throughout your application:
+
+```javascript
+// app.js or index.js
+import express from 'express';
+import { session } from './config/session-manager.js';
+
+const app = express();
+
+// Initialize session middleware (call once during app startup)
+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')
+  };
+});
+
+// Use session instance in your routes
+app.get('/protected', session.authenticate(), (req, res) => {
+  res.json({ user: req.user });
+});
+
+app.get('/auth/callback', session.callback((user) => {
+  return {
+    ...user,
+    loginTime: new Date()
+  };
+}));
+
+app.get('/auth/providers', session.identityProviders());
+app.post('/auth/refresh', session.refresh((user) => {
+  return { ...user, refreshedAt: new Date() };
+}));
+app.get('/auth/logout', session.logout());
+
+app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+```
+
+### Step 3: Import in Other Files
+
+```javascript
+// routes/auth.js
+import { Router } from 'express';
+import { session } from '../config/session-manager.js';
+
+const router = Router();
+
+// Reuse the same session instance
+router.get('/profile', session.authenticate(), (req, res) => {
+  res.json({ profile: req.user });
+});
+
+export default router;
+```
+
+## 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
+
+## Related Documentation
+
+- [RedisManager](./redis-manager.md) - Used internally by SessionManager for Redis storage
+- [Back to main documentation](../README.md)

package/index.d.ts

@@ -1,7 +1,7 @@
 import 'express-session';
 
 import { AxiosError } from 'axios';
-import { JWTPayload, JWTDecryptResult } from 'jose';
+import { EncryptJWT, JWTDecryptResult } from 'jose';
 import { RedisClientType } from '@redis/client';
 import { Application, RequestHandler, Request, Response, NextFunction, Router } from 'express';
 
@@ -248,6 +248,7 @@ export interface JwtDecryptOptions {
   subject?: string;
 }
 
+export type DecryptedJWT = JWTDecryptResult<EncryptJWT>;
 // JwtManager class for JWT encryption and decryption
 export class JwtManager {
   algorithm: string;
@@ -281,7 +282,7 @@ export class JwtManager {
    * @param options Per-call configuration overrides
    * @returns Returns decrypted JWT token
    */
-  decrypt(token: string, input: string, options?: JwtDecryptOptions): Promise<JWTDecryptResult>;
+  decrypt(token: string, input: string, options?: JwtDecryptOptions): Promise<DecryptedJWT>;
 }
 
 // HTTP status code keys (exposed for type safety)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@igxjs/node-components",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Node components for igxjs",
   "main": "index.js",
   "type": "module",