@igxjs/node-components 1.0.0

package/components/http-handlers.js

@@ -0,0 +1,167 @@
+import { STATUS_CODES } from 'node:http';
+
+export const httpMessages = {
+  OK: 'OK',
+  CREATED: 'Created',
+  NO_CONTENT: 'No Content',
+  BAD_REQUEST: 'Bad Request',
+  UNAUTHORIZED: 'Unauthorized',
+  FORBIDDEN: 'Forbidden',
+  NOT_FOUND: 'Not Found',
+  NOT_ACCEPTABLE: 'Not Acceptable',
+  CONFLICT: 'Conflict',
+  SYSTEM_FAILURE: 'System Error',
+};
+
+export const httpCodes = {
+  OK: 200,
+  CREATED: 201,
+  NO_CONTENT: 201,
+  BAD_REQUEST: 400,
+  UNAUTHORIZED: 401,
+  FORBIDDEN: 403,
+  NOT_FOUND: 404,
+  NOT_ACCEPTABLE: 406,
+  CONFLICT: 409,
+  SYSTEM_FAILURE: 500,
+};
+
+export class CustomError extends Error {
+  /** @type {number} */
+  code;
+  /** @type {object} */
+  data;
+  /** @type {object} */
+  error;
+  /**
+   * Construct a custom error
+   * @param {number} code Error code
+   * @param {string} message Message
+   */
+  constructor(code, message, error = {}, data = {}) {
+    super(message);
+    this.code = code;
+    this.error = error;
+    this.data = data;
+  }
+}
+
+/**
+ * Custom error handler
+ *
+ * @param {CustomError} err Error
+ * @param {import('@types/express').Request} req Request
+ * @param {import('@types/express').Response} res Response
+ * @param {import('@types/express').NextFunction} next Next
+ */
+export const httpErrorHandler = (err, req, res, next) => {
+  // If no error, pass to next middleware
+  if (!err) {
+    return next();
+  }
+
+  // Build response object with defaults
+  const responseBody = {
+    status: err.code || httpCodes.BAD_REQUEST,
+    message: err.message || httpMessages.BAD_REQUEST,
+  };
+
+  // Merge additional error data if present
+  if (err.data && typeof err.data === 'object') {
+    Object.entries(err.data).forEach(([key, value]) => {
+      responseBody[key] = value;
+    });
+  }
+
+  // Set CORS and custom headers
+  res.header('Access-Control-Expose-Headers', '*');
+  res.header('X-IBM-Override-Error-Pages', 'not-found, client-error, server-error');
+
+  // Send error response
+  res.status(responseBody.status).json(responseBody);
+
+  // Log error details
+  console.error('### ERROR ###');
+  console.error(`${req.method} ${req.path}`);
+
+  // Log based on error type
+  if ([httpCodes.UNAUTHORIZED, httpCodes.FORBIDDEN, httpCodes.NOT_FOUND].includes(err.code)) {
+    console.error('>>> Auth Error:', err.message);
+  } else {
+    console.error('>>> Name:', err.name);
+    console.error('>>> Message:', err.message);
+    if (err.stack) {
+      console.error('>>> Stack:', err.stack);
+    }
+  }
+
+  console.error('### /ERROR ###');
+};
+
+/**
+ * Extract HTTP status code from error
+ * @param {Error} error Error object
+ * @returns {number} HTTP status code
+ */
+const _getErrorCode = (error) => {
+  const statusCode = error.response?.status;
+  // Validate it's a valid HTTP status code
+  if (statusCode && typeof statusCode === 'number' && Object.hasOwn(STATUS_CODES, statusCode)) {
+    return statusCode;
+  }
+  return httpCodes.SYSTEM_FAILURE;
+};
+
+/**
+ * Extract error message from error
+ * @param {Error} error Error object
+ * @param {string} defaultMessage Default message
+ * @returns {string} Error message
+ */
+const _getErrorMessage = (error, defaultMessage) => {
+  // Priority: response.data.message > response.statusText > error.message > default
+  return error.response?.data?.message
+    || error.response?.statusText
+    || error.message
+    || defaultMessage;
+};
+
+export const httpHelper = {
+  format (str, ...args) {
+    const matched = str.match(/{\d}/ig);
+    matched.forEach((element, index) => {
+      if(args.length > index)
+        str = str.replace(element, args[index]);
+    });
+    return str;
+  },
+
+  /**
+   * Generate friendly Zod message
+   * @param {Error} error Zod error
+   * @returns {string} Returns friendly Zod message
+   */
+  toZodMessage(error) {
+    return error.issues
+    .map(issue => {
+      const path = issue.path.join('.');
+      return (path ? '['.concat(path).concat('] ').concat('') : '').concat(issue.message);
+    })
+    .join('; ');
+  },
+
+  /**
+   * Try to analyze axios Error
+   * @param {Error | import('axios').AxiosError} error Error object
+   * @param {string} defaultMessage Default error message
+   * @returns {CustomError} Returns CustomError instance
+   */
+  handleAxiosError(error, defaultMessage = 'An error occurred') {
+    console.warn(`### TRY ERROR: ${defaultMessage} ###`);
+    // Extract error details
+    const errorCode = _getErrorCode(error);
+    const errorMessage = _getErrorMessage(error, defaultMessage);
+    const errorData = error.response?.data || {};
+    return new CustomError(errorCode, errorMessage, error, errorData);
+  }
+};

package/components/redis.js

@@ -0,0 +1,76 @@
+import fs from 'node:fs';
+
+import { createClient } from '@redis/client';
+
+export class RedisManager {
+  /** @type {import('@redis/client').RedisClientType} */
+  #client = null;
+  /**
+   * Connect with Redis
+   * @returns {Promise<boolean>} Returns `true` if Redis server is connected
+   */
+  async connect(redisUrl, certPath) {
+    if (redisUrl?.length > 0) {
+      try {
+        /** @type {import('@redis/client').RedisClientOptions} */
+        const options = {
+          url: redisUrl,
+          socket: { tls: redisUrl.includes('rediss:'), ca: null },
+        };
+        if(options.socket.tls) {
+          const caCert = fs.readFileSync(certPath);
+          options.socket.ca = caCert;
+        }
+        this.#client = createClient(options);
+        this.#client.on('ready', () => {
+          console.info('### REDIS READY ###');
+        });
+        this.#client.on('reconnecting', (_res) => {
+          console.warn('### REDIS RECONNECTING ###');
+        });
+        this.#client.on('error', (error) => {
+          console.error(`### REDIS ERROR: ${error.message} ###`);
+        });
+        await this.#client.connect();
+        return true;
+      }
+      catch (error) {
+        console.error('### REDIS CONNECT ERROR ###');
+        console.error(error);
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Get Redis client
+   * @returns {import('@redis/client').RedisClientType} Returns Redis client
+   */
+  getClient() {
+    return this.#client;
+  }
+
+  /**
+   * Determine if the Redis server is connected
+   * @returns {boolean} Returns `true` if Redis server is connected
+   */
+  async isConnected() {
+    if (this.#client)
+      try {
+        const pongMessage = await this.#client.ping();
+        return 'PONG' === pongMessage;
+      } catch (error) {
+        console.error(`### REDIS PING ERROR ###`);
+        console.error(error);
+      }
+    return false;
+  }
+
+  /**
+   * Disconnect with Redis
+   * @returns {Promise<void>} Returns nothing
+   */
+  disConnect() {
+    return this.#client.quit();
+  }
+}

package/components/router.js

@@ -0,0 +1,54 @@
+/**
+ * FlexRouter for expressjs
+ * 
+ * @example
+ * import { Router } from 'express';
+ * import { FlexRouter } from '../models/router.js';
+ * import { authenticate } from '../middlewares/common.js';
+ * 
+ * export const publicRouter = Router();
+ * export const privateRouter = Router();
+ * 
+ * publicRouter.get('/health', (req, res) => {
+ *  res.send('OK');
+ * });
+ * 
+ * privateRouter.get('/', (req, res) => {
+ *  res.send('Hello World!');
+ * });
+ * 
+ * export const routers = [
+ *  new FlexRouter('/api/v1/protected', privateRouter, [authenticate]),
+ *  new FlexRouter('/api/v1/public', healthRouter),
+ * ];
+ */
+export class FlexRouter {
+  /** @type {string} */
+  context = '';
+  /** @type {import('@types/express').Router} */
+  router = null;
+  /** @type {import('@types/express').RequestHandler[]} */
+  handlers = [];
+
+  /**
+   * Constructor
+   * @param {string} context Context path
+   * @param {import('@types/express').Router} router Router instance
+   * @param {import('@types/express').RequestHandler[]} handlers Request handlers
+   */
+  constructor(context, router, handlers = []) {
+    this.context = context;
+    this.router = router;
+    this.handlers = handlers;
+  }
+
+  /**
+   * Mount router
+   * @param {import('@types/express').Express} app Express app
+   * @param {string} basePath Base path
+   */
+  mount(app, basePath) {
+    const path = basePath.concat(this.context);
+    app.use(path, this.handlers, this.router);
+  }
+}

package/components/session.js

@@ -0,0 +1,376 @@
+import axios from 'axios';
+import session from 'express-session';
+import { jwtDecrypt } from 'jose';
+import { RedisStore } from 'connect-redis';
+import memStore from 'memorystore';
+
+import { CustomError, httpCodes, httpHelper, httpMessages } from './http-handlers.js';
+import { RedisManager } from './redis.js';
+
+const MemoryStore = memStore(session);
+
+export class SessionConfig {
+  /** @type {string} */
+  SSO_ENDPOINT_URL;
+  /** @type {string} */
+  SSO_CLIENT_ID;
+  /** @type {string} */
+  SSO_CLIENT_SECRET;
+  /** @type {string} */
+  SSO_SUCCESS_URL;
+  /** @type {string} */
+  SSO_FAILURE_URL;
+
+  /** @type {number} */
+  SESSION_AGE;
+  /** @type {string} */
+  SESSION_COOKIE_PATH;
+  /** @type {string} */
+  SESSION_SECRET;
+  /** @type {string} */
+  SESSION_PREFIX;
+
+  /** @type {string} */
+  REDIS_URL;
+  /** @type {string} */
+  REDIS_CERT_PATH;
+}
+
+export class SessionManager {
+  /** @type {SessionConfig} */
+  #config = null;
+  /** @type {Map<string, number>} */
+  #sessionRefreshLocks = new Map();
+  /** @type {import('./redis.js').RedisManager} */
+  #redisManager = null;
+  /** @type {import('axios').AxiosInstance} */
+  #idpRequest = null;
+
+  /**
+   * Check if the email has a session refresh lock
+   * @param {string} email Email address
+   * @returns {boolean} Returns true if the email has a session refresh lock
+   */
+  hasLock(email) {
+    return this.#sessionRefreshLocks.has(email) && this.#sessionRefreshLocks.get(email) > Date.now();
+  }
+
+  /**
+   * Lock the email for session refresh
+   * @param {string} email Email address
+   */
+  lock(email) {
+    if (email) {
+      this.#sessionRefreshLocks.set(email, Date.now() + 60000);
+    }
+    this.clearLocks();
+  }
+
+  /**
+   * Clear session refresh locks
+   */
+  clearLocks() {
+    return setTimeout(() => {
+      for (const email of this.#sessionRefreshLocks.keys()) {
+        if (this.hasLock(email)) {
+          continue;
+        }
+        this.#sessionRefreshLocks.delete(email);
+      }
+    }, 1000);
+  }
+
+  /**
+   * Get session key
+   * @returns {string} Returns the session key
+   */
+  #getSessionKey() {
+    return 'user';
+  }
+
+  /**
+   * Get RedisManager instance
+   * @returns {import('./redis.js').RedisManager} Returns the RedisManager instance
+   */
+  redisManager() {
+    return this.#redisManager;
+  }
+
+  /**
+   * Setup the session/user handlers with configurations
+   * @param {import('@types/express').Application} app Express application
+   * @param {SessionConfig} config Redis configurations
+   * @param {(user: object) => object} updateUser Update user object if user should have proper attributes, e.g. permissions, avatar URL
+   */
+  async setup(app, config, updateUser) {
+    this.#redisManager = new RedisManager();
+    this.#config = {
+      // Session
+      SESSION_AGE: config.SESSION_AGE || 64800000,
+      SESSION_COOKIE_PATH: config.SESSION_COOKIE_PATH || '/',
+      SESSION_SECRET: config.SESSION_SECRET,
+      SESSION_PREFIX: config.SESSION_PREFIX || 'ibmid:',
+      // Identity Provider
+      SSO_ENDPOINT_URL: config.SSO_ENDPOINT_URL,
+      SSO_CLIENT_ID: config.SSO_CLIENT_ID,
+      SSO_CLIENT_SECRET: config.SSO_CLIENT_SECRET,
+      SSO_SUCCESS_URL: config.SSO_SUCCESS_URL,
+      SSO_FAILURE_URL: config.SSO_FAILURE_URL,
+      // Redis
+      REDIS_URL: config.REDIS_URL,
+      REDIS_CERT_PATH: config.REDIS_CERT_PATH,
+    };
+    // Identity Provider Request
+    this.#idpRequest = axios.create({
+      baseURL: this.#config.SSO_ENDPOINT_URL,
+      timeout: 30000,
+    });
+    app.set('trust proxy', 1);
+    app.use(await this.sessionHandler());
+    app.use(this.#userHandler(updateUser));
+  }
+
+  /**
+   * Get Redis session RequestHandler
+   * @returns {import('@types/express').RequestHandler} Returns RequestHandler instance of Express
+   */
+  #redisSession() {
+    // Redis Session
+    console.log('### Using Redis as the Session Store ###');
+    return session({
+      cookie: { maxAge: this.#config.SESSION_AGE, path: this.#config.SESSION_COOKIE_PATH, sameSite: false },
+      store: new RedisStore({ client: this.#redisManager.getClient(), prefix: this.#config.SESSION_PREFIX, disableTouch: true }),
+      resave: false, saveUninitialized: false,
+      secret: this.#config.SESSION_SECRET,
+    });
+  }
+
+  /**
+   * Get Memory session RequestHandler
+   * @returns {import('@types/express').RequestHandler} Returns RequestHandler instance of Express
+   */
+  #memorySession() {
+    // Memory Session
+    console.log('### Using Memory as the Session Store ###');
+    return session({
+      cookie: { maxAge: this.#config.SESSION_AGE, path: this.#config.SESSION_COOKIE_PATH, sameSite: false },
+      store: new MemoryStore({}),
+      resave: false, saveUninitialized: false,
+      secret: this.#config.SESSION_SECRET,
+    });
+  }
+
+  /**
+   * Get session RequestHandler
+   * @returns {Promise<import('@types/express').RequestHandler>} Returns RequestHandler instance of Express
+   */
+  async sessionHandler() {
+    if(this.#config.REDIS_URL?.length > 0) {
+      await this.#redisManager.connect(this.#config.REDIS_URL, this.#config.REDIS_CERT_PATH);
+      return this.#redisSession();
+    }
+    return this.#memorySession();
+  }
+
+  /**
+   * User HTTP Handler
+   * @param {(user: object) => object} updateUser User wrapper
+   * @returns {import('@types/express').RequestHandler} Returns express Request Handler
+   */
+  #userHandler (updateUser) {
+    return (req, res, next) => {
+      req.user = req.session[this.#getSessionKey()];
+      /** @type {import('@types/express').Request & { user: object }} Session user */
+      res.locals.user = updateUser(req.user);
+      return next();
+    };
+  }
+
+  /**
+   * Resource protection
+   * @param {boolean} [isDebugging=false] Debugging flag
+   * @param {boolean} [redirectUrl=''] Redirect flag
+   * @returns {import('@types/express').RequestHandler} Returns express Request Handler
+   */
+  authenticate (isDebugging = false, redirectUrl = '') {
+    return async (req, res, next) => {
+      /** @type {{ authorized: boolean }} */
+      const { authorized = isDebugging } = req.user ?? { authorized: isDebugging };
+      if (authorized) {
+        return next();
+      }
+      if(redirectUrl) {
+        return res.redirect(redirectUrl);
+      }
+      return next(new CustomError(httpCodes.UNAUTHORIZED, httpMessages.UNAUTHORIZED));
+    };
+  };
+
+  /**
+   * Save session
+   * @param {import('@types/express').Request} request Request object
+   * @param {string} jwt JWT
+   * @param {(user: object) => object} initUser Redirect URL
+   * @returns {Promise<{ user: import('../models/types/user').UserModel, redirect_url: string }>} Promise
+   */
+  #saveSession = async (request, jwt, initUser) => {
+    /** @type {{ payload: { user: import('../models/types/user').UserModel, redirect_url: string } }} */
+    const { payload } = await this.#decryptJWT(jwt, this.#config.SSO_CLIENT_SECRET);
+    if (payload?.user) {
+      console.debug('### CALLBACK USER ###');
+      request.session[this.#getSessionKey()] = initUser(payload.user);
+      return new Promise((resolve, reject) => {
+        request.session.touch().save((err) => {
+          if (err) {
+            console.error('### SESSION SAVE ERROR ###');
+            console.error(err);
+            return reject(new CustomError(httpCodes.SYSTEM_FAILURE,  'Session failed to save', err));
+          }
+          return resolve(payload);
+        });
+      });
+    }
+    throw new CustomError(httpCodes.BAD_REQUEST, 'Invalid JWT payload');
+  };
+
+  /**
+   * SSO callback for successful login
+   * @param {(user: object) => object} initUser Initialize user object function
+   * @returns {import('@types/express').RequestHandler} Returns express Request Handler
+   */
+  callback(initUser) {
+    return async (req, res, next) => {
+      const { jwt = '' } = req.query;
+      if(!jwt) {
+        return next(new CustomError(httpCodes.BAD_REQUEST, 'Missing `jwt` in query parameters'));
+      }
+      try {
+        const payload = await this.#saveSession(req, jwt, initUser);
+        return res.redirect(payload?.redirect_url ? payload.redirect_url : this.#config.SSO_SUCCESS_URL);
+      }
+      catch (error) {
+        console.error('### LOGIN ERROR ###');
+        console.error(error);
+        return res.redirect(this.#config.SSO_FAILURE_URL.concat('?message=').concat(encodeURIComponent(error.message)));
+      }
+    };
+  }
+
+  /**
+   * Get Identity Providers
+   * @returns {import('@types/express').RequestHandler} Returns express Request Handler
+   */
+  identityProviders() {
+    const idpUrl = '/auth/providers'.concat('?client_id=').concat(this.#config.SSO_CLIENT_ID);
+    return async (_req, res, next) => {
+      try {
+        const response = await this.#idpRequest.get(idpUrl);
+        if(response.status === httpCodes.OK) {
+          return res.json(response.data);
+        }
+        throw new CustomError(response.status, response.statusText);
+      }
+      catch(error) {
+        return next(httpHelper.handleAxiosError(error));
+      }
+    };
+  }
+
+  /**
+   * Application logout (NOT SSO)
+   * @returns {import('@types/express').RequestHandler} Returns express Request Handler
+   */
+  logout() {
+    return (req, res) => {
+      const { redirect = false } = req.query;
+      const isRedirect = (redirect === 'true' || redirect === true);
+      return this.#logout(req, res, (error => {
+        if (error) {
+          console.error('### LOGOUT CALLBACK ERROR ###');
+          console.error(error);
+          if (isRedirect)
+            return res.redirect(this.#config.SSO_FAILURE_URL);
+          return res.status(httpCodes.AUTHORIZATION_FAILED).send({ redirect_url: this.#config.SSO_FAILURE_URL });
+        }
+        if (isRedirect)
+          return res.redirect(this.#config.SSO_SUCCESS_URL);
+        return res.send({ redirect_url: this.#config.SSO_SUCCESS_URL });
+      }));
+    };
+  }
+
+  /**
+   * Refresh user session
+   * @param {(user: object) => object} initUser Initialize user object function
+   * @returns {import('@types/express').RequestHandler} Returns express Request Handler
+   */
+  refresh(initUser) {
+    const idpUrl = '/auth/refresh'.concat('?client_id=').concat(this.#config.SSO_CLIENT_ID);
+    return async (req, res, next) => {
+      try {
+        const { email, attributes } = req.user || { email: '', attributes: {} };
+        if (this.hasLock(email)) {
+          throw new CustomError(httpCodes.CONFLICT, 'User refresh is locked');
+        }
+        this.lock(email);
+        const response = await this.#idpRequest.post(idpUrl, {
+          user: {
+            email,
+            attributes: {
+              idp: attributes?.idp,
+              refresh_token: attributes?.refresh_token
+            },
+          }
+        });
+        if(response.status === httpCodes.OK) {
+          /** @type {{ jwt: string }} */
+          const { jwt } = response.data;
+          const payload = await this.#saveSession(req, jwt, initUser);
+          return res.json(payload);
+        }
+        throw new CustomError(response.status, response.statusText);
+      }
+      catch(error) {
+        return next(httpHelper.handleAxiosError(error));
+      }
+    };
+  }
+
+  /**
+   * Logout
+   * @param {import('@types/express').Request} req Request
+   * @param {import('@types/express').Response} res Response
+   * @param {(error: Error)} callback Callback
+   */
+  #logout(req, res, callback) {
+    try {
+      res.clearCookie('connect.sid');
+    } catch (error) {
+      console.error('### CLEAR COOKIE ERROR ###');
+      console.error(error);
+    }
+    return req.session.destroy((sessionError) => {
+      if (sessionError) {
+        console.error('### SESSION DESTROY CALLBACK ERROR ###');
+        console.error(sessionError);
+        return callback(sessionError);
+      }
+      console.info('### LOGOUT SUCCESSFULLY ###');
+      return callback(null);
+    });
+  }
+
+  /**
+   * Decrypt JWT data for user session
+   * @param {string} data JWT data
+   * @param {string} input Input string for encryption
+   * @returns {Promise<import('jose').JWTDecryptResult<import('jose').EncryptJWT>>} Returns decrypted JWT payload
+   */
+  async #decryptJWT(data, input) {
+    const secret = await crypto.subtle.digest(
+      'SHA-256',
+      new TextEncoder().encode(input)
+    );
+    return await jwtDecrypt(data, new Uint8Array(secret), { clockTolerance: 30 });
+  }
+}