@igxjs/node-components 1.0.6 → 1.0.8

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,6 +1,7 @@
 import 'express-session';
 
 import { AxiosError } from 'axios';
+import { EncryptJWT, JWTDecryptResult } from 'jose';
 import { RedisClientType } from '@redis/client';
 import { Application, RequestHandler, Request, Response, NextFunction, Router } from 'express';
 
@@ -197,6 +198,93 @@ export class RedisManager {
   disConnect(): Promise<void>;
 }
 
+// JWT Manager Configuration
+export interface JwtManagerOptions {
+  /** @type {string} JWE algorithm (default: 'dir') */
+  algorithm?: string;
+  /** @type {string} JWE encryption method (default: 'A256GCM') */
+  encryption?: string;
+  /** @type {string} Token expiration time (default: '10m') */
+  expirationTime?: string;
+  /** @type {number} Clock tolerance in seconds for token validation (default: 30) */
+  clockTolerance?: number;
+  /** @type {string} Hash algorithm for secret derivation (default: 'SHA-256') */
+  secretHashAlgorithm?: string;
+  /** @type {string} Optional JWT issuer claim */
+  issuer?: string;
+  /** @type {string} Optional JWT audience claim */
+  audience?: string;
+  /** @type {string} Optional JWT subject claim */
+  subject?: string;
+}
+
+export interface JwtEncryptOptions {
+  /** @type {string} Override default algorithm */
+  algorithm?: string;
+  /** @type {string} Override default encryption method */
+  encryption?: string;
+  /** @type {string} Override default expiration time */
+  expirationTime?: string;
+  /** @type {string} Override default hash algorithm */
+  secretHashAlgorithm?: string;
+  /** @type {string} Override default issuer claim */
+  issuer?: string;
+  /** @type {string} Override default audience claim */
+  audience?: string;
+  /** @type {string} Override default subject claim */
+  subject?: string;
+}
+
+export interface JwtDecryptOptions {
+  /** @type {number} Override default clock tolerance */
+  clockTolerance?: number;
+  /** @type {string} Override default hash algorithm */
+  secretHashAlgorithm?: string;
+  /** @type {string} Expected issuer claim for validation */
+  issuer?: string;
+  /** @type {string} Expected audience claim for validation */
+  audience?: string;
+  /** @type {string} Expected subject claim for validation */
+  subject?: string;
+}
+
+export type DecryptedJWT = JWTDecryptResult<EncryptJWT>;
+// JwtManager class for JWT encryption and decryption
+export class JwtManager {
+  algorithm: string;
+  encryption: string;
+  expirationTime: string;
+  clockTolerance: number;
+  secretHashAlgorithm: string;
+  issuer?: string;
+  audience?: string;
+  subject?: string;
+
+  /**
+   * Create a new JwtManager instance with configurable defaults
+   * @param options Configuration options
+   */
+  constructor(options?: JwtManagerOptions);
+
+  /**
+   * 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
+   * @returns Returns encrypted JWT token
+   */
+  encrypt( 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
+   * @returns Returns decrypted JWT token
+   */
+  decrypt(token: string, input: string, options?: JwtDecryptOptions): Promise<DecryptedJWT>;
+}
+
 // HTTP status code keys (exposed for type safety)
 export const httpCodes: {
   OK: number;
@@ -208,6 +296,7 @@ export const httpCodes: {
   NOT_FOUND: number;
   NOT_ACCEPTABLE: number;
   CONFLICT: number;
+  LOCKED: number;
   SYSTEM_FAILURE: number;
   NOT_IMPLEMENTED: number;
 };
@@ -223,6 +312,7 @@ export const httpMessages: {
   NOT_FOUND: string;
   NOT_ACCEPTABLE: string;
   CONFLICT: string;
+  LOCKED: string;
   SYSTEM_FAILURE: string;
   NOT_IMPLEMENTED: string;
 };
@@ -255,6 +345,21 @@ export const httpHelper: {
   handleAxiosError(error: Error | AxiosError, defaultMessage?: string): CustomError;
 };
 
+/**
+ * HTTP Error - alias of `new CustomError()`
+ * @param code Error code
+ * @param message Error message
+ * @param error Original Error instance
+ * @param data Error data
+ * @returns Returns a new instance of CustomError
+ */
+export function httpError(
+  code: number,
+  message: string,
+  error?: object,
+  data?: object
+): CustomError;
+
 /**
  * Custom error handler middleware
  * @param err Error object

package/index.js

@@ -1,4 +1,5 @@
 export { SessionConfig, SessionManager } from './components/session.js';
-export { httpCodes, httpMessages, httpErrorHandler, CustomError, httpHelper } from './components/http-handlers.js';
+export { httpCodes, httpMessages, httpErrorHandler, httpNotFoundHandler, CustomError, httpHelper, httpError } from './components/http-handlers.js';
 export { RedisManager } from './components/redis.js';
 export { FlexRouter } from './components/router.js';
+export { JwtManager } from './components/jwt.js';

package/package.json

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