@igxjs/node-components 1.0.9 → 1.0.11

package/docs/session-manager.md

@@ -1,160 +0,0 @@
-# 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/tests/http-handlers.test.js

@@ -1,21 +0,0 @@
-import { describe, it } from 'mocha';
-import { expect } from 'chai';
-import { httpCodes, httpMessages, CustomError } from '../components/http-handlers.js';
-
-describe('HTTP Handlers', () => {
-  describe('httpCodes', () => {
-    it('should have correct HTTP status codes', () => {
-      expect(httpCodes.OK).to.equal(200);
-      expect(httpCodes.BAD_REQUEST).to.equal(400);
-      expect(httpCodes.NOT_FOUND).to.equal(404);
-    });
-  });
-
-  describe('CustomError', () => {
-    it('should create a CustomError', () => {
-      const error = new CustomError(404, 'Not found');
-      expect(error.code).to.equal(404);
-      expect(error.message).to.equal('Not found');
-    });
-  });
-});

package/tests/jwt.test.js

@@ -1,345 +0,0 @@
-import { describe, it, beforeEach } from 'mocha';
-import { expect } from 'chai';
-import { JwtManager } from '../components/jwt.js';
-
-describe('JwtManager', () => {
-  let jwtManager;
-  const testSecret = 'test-secret-key-12345';
-  const testData = {
-    userId: '123',
-    email: 'test@example.com',
-    role: 'user'
-  };
-
-  beforeEach(() => {
-    jwtManager = new JwtManager();
-  });
-
-  describe('Constructor', () => {
-    it('should create JwtManager instance with default options', () => {
-      const manager = new JwtManager();
-      expect(manager).to.be.instanceOf(JwtManager);
-      expect(manager.algorithm).to.equal('dir');
-      expect(manager.encryption).to.equal('A256GCM');
-      expect(manager.expirationTime).to.equal('10m');
-      expect(manager.clockTolerance).to.equal(30);
-      expect(manager.secretHashAlgorithm).to.equal('SHA-256');
-    });
-
-    it('should create JwtManager instance with custom options', () => {
-      const options = {
-        algorithm: 'A128KW',
-        encryption: 'A128GCM',
-        expirationTime: '1h',
-        clockTolerance: 60,
-        secretHashAlgorithm: 'SHA-512',
-        issuer: 'test-issuer',
-        audience: 'test-audience',
-        subject: 'test-subject'
-      };
-      const manager = new JwtManager(options);
-      expect(manager.algorithm).to.equal('A128KW');
-      expect(manager.encryption).to.equal('A128GCM');
-      expect(manager.expirationTime).to.equal('1h');
-      expect(manager.clockTolerance).to.equal(60);
-      expect(manager.secretHashAlgorithm).to.equal('SHA-512');
-      expect(manager.issuer).to.equal('test-issuer');
-      expect(manager.audience).to.equal('test-audience');
-      expect(manager.subject).to.equal('test-subject');
-    });
-
-    it('should handle clockTolerance of 0', () => {
-      const manager = new JwtManager({ clockTolerance: 0 });
-      expect(manager.clockTolerance).to.equal(0);
-    });
-  });
-
-  describe('encrypt', () => {
-    it('should encrypt data and return a JWT token', async () => {
-      const token = await jwtManager.encrypt(testData, testSecret);
-      expect(token).to.be.a('string');
-      expect(token.split('.').length).to.equal(5); // JWE has 5 parts
-    });
-
-    it('should encrypt with custom encryption method', async () => {
-      const token = await jwtManager.encrypt(testData, testSecret, {
-        algorithm: 'dir',
-        encryption: 'A256GCM'
-      });
-      expect(token).to.be.a('string');
-    });
-
-    it('should encrypt with custom expiration time', async () => {
-      const token = await jwtManager.encrypt(testData, testSecret, {
-        expirationTime: '1h'
-      });
-      expect(token).to.be.a('string');
-    });
-
-    it('should encrypt with issuer claim', async () => {
-      const token = await jwtManager.encrypt(testData, testSecret, {
-        issuer: 'test-issuer'
-      });
-      expect(token).to.be.a('string');
-    });
-
-    it('should encrypt with audience claim', async () => {
-      const token = await jwtManager.encrypt(testData, testSecret, {
-        audience: 'test-audience'
-      });
-      expect(token).to.be.a('string');
-    });
-
-    it('should encrypt with subject claim', async () => {
-      const token = await jwtManager.encrypt(testData, testSecret, {
-        subject: 'test-subject'
-      });
-      expect(token).to.be.a('string');
-    });
-
-    it('should encrypt with all optional claims', async () => {
-      const token = await jwtManager.encrypt(testData, testSecret, {
-        issuer: 'test-issuer',
-        audience: 'test-audience',
-        subject: 'test-subject'
-      });
-      expect(token).to.be.a('string');
-    });
-
-    it('should use default claims from constructor if not overridden', async () => {
-      const manager = new JwtManager({
-        issuer: 'default-issuer',
-        audience: 'default-audience'
-      });
-      const token = await manager.encrypt(testData, testSecret);
-      expect(token).to.be.a('string');
-    });
-  });
-
-  describe('decrypt', () => {
-    it('should decrypt a valid JWT token', async () => {
-      const token = await jwtManager.encrypt(testData, testSecret);
-      const result = await jwtManager.decrypt(token, testSecret);
-      
-      expect(result).to.have.property('payload');
-      expect(result).to.have.property('protectedHeader');
-      expect(result.payload).to.include(testData);
-    });
-
-    it('should decrypt token with correct payload data', async () => {
-      const token = await jwtManager.encrypt(testData, testSecret);
-      const result = await jwtManager.decrypt(token, testSecret);
-      
-      expect(result.payload.userId).to.equal(testData.userId);
-      expect(result.payload.email).to.equal(testData.email);
-      expect(result.payload.role).to.equal(testData.role);
-    });
-
-    it('should include standard JWT claims in decrypted payload', async () => {
-      const token = await jwtManager.encrypt(testData, testSecret);
-      const result = await jwtManager.decrypt(token, testSecret);
-      
-      expect(result.payload).to.have.property('iat');
-      expect(result.payload).to.have.property('exp');
-    });
-
-    it('should fail to decrypt with wrong secret', async () => {
-      const token = await jwtManager.encrypt(testData, testSecret);
-      
-      try {
-        await jwtManager.decrypt(token, 'wrong-secret');
-        expect.fail('Should have thrown an error');
-      } catch (error) {
-        expect(error).to.exist;
-      }
-    });
-
-    it('should decrypt token with custom clock tolerance', async () => {
-      const token = await jwtManager.encrypt(testData, testSecret, {
-        expirationTime: '1s'
-      });
-      
-      // Use higher clock tolerance to allow slightly expired tokens
-      const result = await jwtManager.decrypt(token, testSecret, {
-        clockTolerance: 120
-      });
-      
-      expect(result.payload).to.include(testData);
-    });
-
-    it('should validate issuer claim when provided', async () => {
-      const issuer = 'test-issuer';
-      const token = await jwtManager.encrypt(testData, testSecret, { issuer });
-      
-      const result = await jwtManager.decrypt(token, testSecret, { issuer });
-      expect(result.payload.iss).to.equal(issuer);
-    });
-
-    it('should fail when issuer claim does not match', async () => {
-      const token = await jwtManager.encrypt(testData, testSecret, {
-        issuer: 'correct-issuer'
-      });
-      
-      try {
-        await jwtManager.decrypt(token, testSecret, {
-          issuer: 'wrong-issuer'
-        });
-        expect.fail('Should have thrown an error');
-      } catch (error) {
-        expect(error).to.exist;
-      }
-    });
-
-    it('should validate audience claim when provided', async () => {
-      const audience = 'test-audience';
-      const token = await jwtManager.encrypt(testData, testSecret, { audience });
-      
-      const result = await jwtManager.decrypt(token, testSecret, { audience });
-      expect(result.payload.aud).to.equal(audience);
-    });
-
-    it('should fail when audience claim does not match', async () => {
-      const token = await jwtManager.encrypt(testData, testSecret, {
-        audience: 'correct-audience'
-      });
-      
-      try {
-        await jwtManager.decrypt(token, testSecret, {
-          audience: 'wrong-audience'
-        });
-        expect.fail('Should have thrown an error');
-      } catch (error) {
-        expect(error).to.exist;
-      }
-    });
-
-    it('should validate subject claim when provided', async () => {
-      const subject = 'test-subject';
-      const token = await jwtManager.encrypt(testData, testSecret, { subject });
-      
-      const result = await jwtManager.decrypt(token, testSecret, { subject });
-      expect(result.payload.sub).to.equal(subject);
-    });
-
-    it('should fail when subject claim does not match', async () => {
-      const token = await jwtManager.encrypt(testData, testSecret, {
-        subject: 'correct-subject'
-      });
-      
-      try {
-        await jwtManager.decrypt(token, testSecret, {
-          subject: 'wrong-subject'
-        });
-        expect.fail('Should have thrown an error');
-      } catch (error) {
-        expect(error).to.exist;
-      }
-    });
-
-    it('should use default claims from constructor for validation', async () => {
-      const manager = new JwtManager({
-        issuer: 'default-issuer',
-        audience: 'default-audience',
-        subject: 'default-subject'
-      });
-      
-      const token = await manager.encrypt(testData, testSecret);
-      const result = await manager.decrypt(token, testSecret);
-      
-      expect(result.payload.iss).to.equal('default-issuer');
-      expect(result.payload.aud).to.equal('default-audience');
-      expect(result.payload.sub).to.equal('default-subject');
-    });
-  });
-
-  describe('encrypt/decrypt round-trip', () => {
-    it('should successfully encrypt and decrypt data', async () => {
-      const originalData = {
-        id: 'user-123',
-        name: 'John Doe',
-        permissions: ['read', 'write']
-      };
-      
-      const token = await jwtManager.encrypt(originalData, testSecret);
-      const result = await jwtManager.decrypt(token, testSecret);
-      
-      expect(result.payload.id).to.equal(originalData.id);
-      expect(result.payload.name).to.equal(originalData.name);
-      expect(result.payload.permissions).to.deep.equal(originalData.permissions);
-    });
-
-    it('should handle SHA-256 hash algorithm', async () => {
-      const manager = new JwtManager({ 
-        secretHashAlgorithm: 'SHA-256',
-        encryption: 'A256GCM' // SHA-256 produces 256 bits, matches A256GCM
-      });
-      
-      const token = await manager.encrypt(testData, testSecret);
-      const result = await manager.decrypt(token, testSecret);
-      
-      expect(result.payload).to.include(testData);
-    });
-
-    it('should handle empty payload', async () => {
-      const emptyData = {};
-      const token = await jwtManager.encrypt(emptyData, testSecret);
-      const result = await jwtManager.decrypt(token, testSecret);
-      
-      expect(result.payload).to.have.property('iat');
-      expect(result.payload).to.have.property('exp');
-    });
-
-    it('should preserve different data types', async () => {
-      const complexData = {
-        string: 'test',
-        number: 42,
-        boolean: true,
-        array: [1, 2, 3],
-        object: { nested: 'value' },
-        null: null
-      };
-      
-      const token = await jwtManager.encrypt(complexData, testSecret);
-      const result = await jwtManager.decrypt(token, testSecret);
-      
-      expect(result.payload.string).to.equal(complexData.string);
-      expect(result.payload.number).to.equal(complexData.number);
-      expect(result.payload.boolean).to.equal(complexData.boolean);
-      expect(result.payload.array).to.deep.equal(complexData.array);
-      expect(result.payload.object).to.deep.equal(complexData.object);
-      expect(result.payload.null).to.equal(complexData.null);
-    });
-  });
-
-  describe('Error Handling', () => {
-    it('should fail with invalid token format', async () => {
-      try {
-        await jwtManager.decrypt('invalid.token.format', testSecret);
-        expect.fail('Should have thrown an error');
-      } catch (error) {
-        expect(error).to.exist;
-      }
-    });
-
-    it('should fail with empty token', async () => {
-      try {
-        await jwtManager.decrypt('', testSecret);
-        expect.fail('Should have thrown an error');
-      } catch (error) {
-        expect(error).to.exist;
-      }
-    });
-
-    it('should fail with corrupted token', async () => {
-      const token = await jwtManager.encrypt(testData, testSecret);
-      const corruptedToken = token.slice(0, -10) + 'corrupted';
-      
-      try {
-        await jwtManager.decrypt(corruptedToken, testSecret);
-        expect.fail('Should have thrown an error');
-      } catch (error) {
-        expect(error).to.exist;
-      }
-    });
-  });
-});

package/tests/redis.test.js

@@ -1,50 +0,0 @@
-import { describe, it, beforeEach, afterEach } from 'mocha';
-import { expect } from 'chai';
-import sinon from 'sinon';
-import { RedisManager } from '../components/redis.js';
-
-describe('RedisManager', () => {
-  let redisManager;
-  let consoleStubs;
-
-  beforeEach(() => {
-    redisManager = new RedisManager();
-    consoleStubs = {
-      info: sinon.stub(console, 'info'),
-      warn: sinon.stub(console, 'warn'),
-      error: sinon.stub(console, 'error')
-    };
-  });
-
-  afterEach(() => {
-    consoleStubs.info.restore();
-    consoleStubs.warn.restore();
-    consoleStubs.error.restore();
-  });
-
-  describe('connect', () => {
-    it('should return false if redisUrl is empty', async () => {
-      const result = await redisManager.connect('', null);
-      expect(result).to.be.false;
-    });
-
-    it('should return false if redisUrl is null', async () => {
-      const result = await redisManager.connect(null, null);
-      expect(result).to.be.false;
-    });
-  });
-
-  describe('getClient', () => {
-    it('should return null when not connected', () => {
-      const client = redisManager.getClient();
-      expect(client).to.be.null;
-    });
-  });
-
-  describe('isConnected', () => {
-    it('should return false when client is null', async () => {
-      const result = await redisManager.isConnected();
-      expect(result).to.be.false;
-    });
-  });
-});

package/tests/router.test.js

@@ -1,50 +0,0 @@
-import { describe, it, beforeEach } from 'mocha';
-import { expect } from 'chai';
-import sinon from 'sinon';
-import express from 'express';
-import { FlexRouter } from '../components/router.js';
-
-describe('FlexRouter', () => {
-  let app, router, middleware1, middleware2;
-
-  beforeEach(() => {
-    app = express();
-    router = express.Router();
-    middleware1 = sinon.stub().callsFake((req, res, next) => next());
-    middleware2 = sinon.stub().callsFake((req, res, next) => next());
-    sinon.spy(app, 'use');
-  });
-
-  describe('constructor', () => {
-    it('should create FlexRouter with context and router', () => {
-      const flexRouter = new FlexRouter('/api', router);
-      expect(flexRouter.context).to.equal('/api');
-      expect(flexRouter.router).to.equal(router);
-      expect(flexRouter.handlers).to.deep.equal([]);
-    });
-
-    it('should create FlexRouter with handlers', () => {
-      const handlers = [middleware1, middleware2];
-      const flexRouter = new FlexRouter('/api', router, handlers);
-      expect(flexRouter.handlers).to.deep.equal(handlers);
-    });
-  });
-
-  describe('mount', () => {
-    it('should mount router to app with correct path', () => {
-      const flexRouter = new FlexRouter('/users', router);
-      flexRouter.mount(app, '/api/v1');
-      expect(app.use.calledOnce).to.be.true;
-      expect(app.use.firstCall.args[0]).to.equal('/api/v1/users');
-    });
-
-    it('should mount router with handlers', () => {
-      const handlers = [middleware1, middleware2];
-      const flexRouter = new FlexRouter('/protected', router, handlers);
-      flexRouter.mount(app, '/api');
-      expect(app.use.calledOnce).to.be.true;
-      expect(app.use.firstCall.args[0]).to.equal('/api/protected');
-      expect(app.use.firstCall.args[1]).to.deep.equal(handlers);
-    });
-  });
-});