@igxjs/node-components 1.0.0

package/index.d.ts

@@ -0,0 +1,289 @@
+import 'express-session';
+import '@types/express';
+
+import { AxiosError } from 'axios';
+import { RedisClientType } from '@redis/client';
+import { Application, RequestHandler, Request, Response, NextFunction, Router } from '@types/express';
+
+// Session Configuration
+export interface SessionConfig {
+  SSO_ENDPOINT_URL?: string;
+  SSO_CLIENT_ID?: string;
+  SSO_CLIENT_SECRET?: string;
+  SSO_SUCCESS_URL?: string;
+  SSO_FAILURE_URL?: string;
+
+  SESSION_AGE?: number;
+  SESSION_COOKIE_PATH?: string;
+  SESSION_SECRET?: string;
+  SESSION_PREFIX?: string;
+
+  REDIS_URL?: string;
+  REDIS_CERT_PATH?: string;
+}
+
+export interface SessionUserAttributes {
+  /** @type {string} Identity Provider ID */
+  idp: string;
+  /** @type {string} User ID */
+  sub: string;
+  /** @type {number} Local timeout timestamp */
+  expires_at: number;
+  /** @type {number} Remote timeout timestamp */
+  expires_rt: number;
+  /** @type {string} Access token */
+  access_token: string;
+  /** @type {string} Refresh token */
+  refresh_token: string;
+  /** @type {Array<string>} Groups of the user */
+  groups: string[];
+}
+
+export interface SessionUser {
+  /** @type {string} First name */
+  first_name: string;
+  /** @type {string} Last name */
+  last_name: string;
+  /** @type {string} Full name */
+  name: string;
+  /** @type {string} Email address */
+  email: string;
+  /** @type {SessionUserAttributes} User attributes */
+  attributes: SessionUserAttributes;
+  /** @type {boolean} User is authorized */
+  authorized: boolean;
+}
+
+// Session Manager
+export class SessionManager {
+  /**
+   * Check if the email has a session refresh lock
+   * @param email Email address
+   * @returns Returns true if the email has a session refresh lock
+   */
+  hasLock(email: string): boolean;
+
+  /**
+   * Lock the email for session refresh
+   * @param email Email address
+   */
+  lock(email: string): void;
+
+  /**
+   * Clear session refresh locks
+   */
+  clearLocks(): NodeJS.Timeout;
+
+  /**
+   * Get the Redis Manager
+   */
+  redisManager(): RedisManager;
+
+  /**
+   * Initialize the session configurations
+   * @param app Express application
+   * @param config Session configurations
+   * @param updateUser Process user object to compute attributes like permissions, avatar URL, etc.
+   */
+  setup(
+    app: Application,
+    config: SessionConfig,
+    updateUser: (user: SessionUser | undefined) => any
+  ): Promise<void>;
+  
+  /**
+   * Get session RequestHandler
+   * @returns Returns RequestHandler instance of Express
+   */
+  sessionHandler(): Promise<RequestHandler>;
+  
+  /**
+   * Resource protection middleware
+   * @param isDebugging Debugging flag (default: false)
+   * @param redirectUrl Redirect URL (default: '')
+   * @returns Returns express Request Handler
+   */
+  authenticate(isDebugging?: boolean, redirectUrl?: string): RequestHandler;
+  
+  /**
+   * SSO callback for successful login
+   * @param initUser Initialize user object function
+   * @returns Returns express Request Handler
+   */
+  callback(initUser: (user: SessionUser) => SessionUser): RequestHandler;
+  
+  /**
+   * Get Identity Providers
+   * @returns Returns express Request Handler
+   */
+  identityProviders(): RequestHandler;
+  
+  /**
+   * Application logout (NOT SSO)
+   * @returns Returns express Request Handler
+   */
+  logout(): RequestHandler;
+  
+  /**
+   * Refresh user session
+   * @param initUser Initialize user object function
+   * @returns Returns express Request Handler
+   */
+  refresh(initUser: (user: SessionUser) => SessionUser): RequestHandler;
+}
+
+// Custom Error class
+export class CustomError extends Error {
+  code: number;
+  object;
+  error: object;
+  
+  /**
+   * Construct a custom error
+   * @param code Error code
+   * @param message Message
+   * @param error Error object (optional)
+   * @param data Additional data (optional)
+   */
+  constructor(code: number, message: string, error?: object, data?: object);
+}
+
+// Singleton session instance
+export const session: SessionManager;
+
+// FlexRouter class for Express routing
+export class FlexRouter {
+  context: string;
+  router: Router;
+  handlers: RequestHandler[];
+  
+  /**
+   * Constructor
+   * @param context Context path
+   * @param router Router instance
+   * @param handlers Request handlers (optional)
+   */
+  constructor(context: string, router: Router, handlers?: RequestHandler[]);
+  
+  /**
+   * Mount router to Express app
+   * @param app Express application
+   * @param basePath Base path
+   */
+  mount(app: Application, basePath: string): void;
+}
+
+// RedisManager class for Redis connection management
+export class RedisManager {
+  /**
+   * Connect with Redis
+   * @param redisUrl Redis connection URL
+   * @param certPath Certificate path for TLS connections
+   * @returns Returns true if Redis server is connected
+   */
+  connect(redisUrl: string, certPath: string): Promise<boolean>;
+  
+  /**
+   * Get Redis client
+   * @returns Returns Redis client instance
+   */
+  getClient(): RedisClientType;
+  
+  /**
+   * Determine if the Redis server is connected
+   * @returns Returns true if Redis server is connected
+   */
+  isConnected(): Promise<boolean>;
+  
+  /**
+   * Disconnect from Redis
+   * @returns Returns nothing
+   */
+  disConnect(): Promise<void>;
+}
+
+// HTTP status code keys (exposed for type safety)
+export const httpCodes: {
+  OK: number;
+  CREATED: number;
+  NO_CONTENT: number;
+  BAD_REQUEST: number;
+  UNAUTHORIZED: number;
+  FORBIDDEN: number;
+  NOT_FOUND: number;
+  NOT_ACCEPTABLE: number;
+  CONFLICT: number;
+  SYSTEM_FAILURE: number;
+};
+
+// HTTP message keys (exposed for type safety)
+export const httpMessages: {
+  OK: string;
+  CREATED: string;
+  NO_CONTENT: string;
+  BAD_REQUEST: string;
+  UNAUTHORIZED: string;
+  FORBIDDEN: string;
+  NOT_FOUND: string;
+  NOT_ACCEPTABLE: string;
+  CONFLICT: string;
+  SYSTEM_FAILURE: string;
+};
+
+/**
+ * HTTP Helper utilities
+ */
+export const httpHelper: {
+  /**
+   * Format a string with placeholders
+   * @param str String with {0}, {1}, etc. placeholders
+   * @param args Values to replace placeholders
+   * @returns Formatted string
+   */
+  format(str: string, ...args: any[]): string;
+
+  /**
+   * Generate friendly Zod validation error message
+   * @param error Zod validation error
+   * @returns Formatted error message
+   */
+  toZodMessage(error: any): string;
+
+  /**
+   * Analyze and convert Axios/HTTP errors to CustomError
+   * @param error Error object
+   * @param defaultMessage Default error message
+   * @returns CustomError instance
+   */
+  handleAxiosError(error: Error | AxiosError, defaultMessage?: string): CustomError;
+};
+
+/**
+ * Custom error handler middleware
+ * @param err Error object
+ * @param req Express Request
+ * @param res Express Response
+ * @param next Next function
+ */
+export function httpErrorHandler(
+  err: CustomError | Error | any,
+  req: Request,
+  res: Response,
+  next: NextFunction
+): void;
+
+declare global {
+  namespace Express {
+    export interface Request {
+      user?: SessionUser;
+    }
+  }
+}
+
+// Augment Express Session with custom user property
+declare module 'express-session' {
+  interface SessionData {
+    [key: string]: any;
+    user?: SessionUser;
+  }
+}

package/index.js

@@ -0,0 +1,8 @@
+import { SessionManager } from './components/session.js';
+
+export { SessionConfig, SessionManager } from './components/session.js';
+export { httpCodes, httpMessages, httpErrorHandler, CustomError, httpHelper } from './components/http-handlers.js';
+export { RedisManager } from './components/redis.js';
+export { FlexRouter } from './components/router.js';
+
+export const session = new SessionManager();

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@igxjs/node-components",
+  "version": "1.0.0",
+  "description": "Node components for igxjs",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "test": "mocha tests/**/*.test.js --timeout 5000"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/igxjs/node-components.git"
+  },
+  "keywords": [
+    "igxjs"
+  ],
+  "author": "Michael",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/igxjs/node-components/issues"
+  },
+  "homepage": "https://github.com/igxjs/node-components#readme",
+  "dependencies": {
+    "@redis/client": "^5.11.0",
+    "@types/express": "^5.0.6",
+    "axios": "^1.13.6",
+    "connect-redis": "^9.0.0",
+    "express-session": "^1.19.0",
+    "jose": "^6.1.3",
+    "memorystore": "^1.6.7"
+  },
+  "devDependencies": {
+    "chai": "^6.2.2",
+    "express": "^5.2.1",
+    "mocha": "^11.0.1",
+    "sinon": "^21.0.2",
+    "supertest": "^7.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./index.d.ts"
+}

package/tests/http-handlers.test.js

@@ -0,0 +1,21 @@
+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/redis.test.js

@@ -0,0 +1,50 @@
+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

@@ -0,0 +1,50 @@
+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);
+    });
+  });
+});

package/tests/session.test.js

@@ -0,0 +1,116 @@
+import { describe, it, beforeEach, afterEach } from 'mocha';
+import { expect } from 'chai';
+import sinon from 'sinon';
+import { SessionManager, SessionConfig } from '../components/session.js';
+import { CustomError, httpCodes } from '../components/http-handlers.js';
+
+describe('SessionManager', () => {
+  let sessionManager;
+  let clock;
+
+  beforeEach(() => {
+    sessionManager = new SessionManager();
+    clock = sinon.useFakeTimers();
+  });
+
+  afterEach(() => {
+    clock.restore();
+  });
+
+  describe('SessionConfig', () => {
+    it('should create SessionConfig instance with properties', () => {
+      const config = new SessionConfig();
+      expect(config).to.be.instanceOf(SessionConfig);
+      expect(config).to.have.property('SSO_ENDPOINT_URL');
+      expect(config).to.have.property('SESSION_SECRET');
+      expect(config).to.have.property('REDIS_URL');
+    });
+  });
+
+  describe('Lock Management', () => {
+    describe('hasLock', () => {
+      it('should return false for email without lock', () => {
+        const result = sessionManager.hasLock('test@example.com');
+        expect(result).to.be.false;
+      });
+
+      it('should return true for email with active lock', () => {
+        sessionManager.lock('test@example.com');
+        const result = sessionManager.hasLock('test@example.com');
+        expect(result).to.be.true;
+      });
+
+      it('should return false for expired lock', () => {
+        sessionManager.lock('test@example.com');
+        clock.tick(61000);
+        const result = sessionManager.hasLock('test@example.com');
+        expect(result).to.be.false;
+      });
+    });
+
+    describe('lock', () => {
+      it('should create a lock for given email', () => {
+        sessionManager.lock('test@example.com');
+        expect(sessionManager.hasLock('test@example.com')).to.be.true;
+      });
+
+      it('should not create lock for empty email', () => {
+        sessionManager.lock('');
+        sessionManager.lock(null);
+        expect(sessionManager.hasLock('')).to.be.false;
+        expect(sessionManager.hasLock(null)).to.be.false;
+      });
+    });
+  });
+
+  describe('authenticate', () => {
+    let req, res, next;
+
+    beforeEach(() => {
+      req = { user: null };
+      res = { redirect: sinon.stub() };
+      next = sinon.stub();
+    });
+
+    it('should call next() if user is authorized', () => {
+      req.user = { authorized: true };
+      const middleware = sessionManager.authenticate();
+      middleware(req, res, next);
+      expect(next.calledOnce).to.be.true;
+      expect(next.firstCall.args).to.be.empty;
+    });
+
+    it('should call next with error if user is not authorized', () => {
+      req.user = { authorized: false };
+      const middleware = sessionManager.authenticate();
+      middleware(req, res, next);
+      expect(next.calledOnce).to.be.true;
+      const error = next.firstCall.args[0];
+      expect(error).to.be.instanceOf(CustomError);
+      expect(error.code).to.equal(httpCodes.UNAUTHORIZED);
+    });
+
+    it('should redirect if redirectUrl is provided', () => {
+      req.user = { authorized: false };
+      const middleware = sessionManager.authenticate(false, '/login');
+      middleware(req, res, next);
+      expect(res.redirect.calledWith('/login')).to.be.true;
+      expect(next.called).to.be.false;
+    });
+
+    it('should allow access in debug mode', () => {
+      req.user = null;
+      const middleware = sessionManager.authenticate(true);
+      middleware(req, res, next);
+      expect(next.calledOnce).to.be.true;
+      expect(next.firstCall.args).to.be.empty;
+    });
+  });
+
+  describe('redisManager', () => {
+    it('should return null before initialization', () => {
+      const manager = sessionManager.redisManager();
+      expect(manager).to.be.null;
+    });
+  });
+});