@igxjs/node-components 1.0.9 → 1.0.11

package/index.d.ts

@@ -5,14 +5,26 @@ import { EncryptJWT, JWTDecryptResult, JWTPayload } from 'jose';
 import { RedisClientType } from '@redis/client';
 import { Application, RequestHandler, Request, Response, NextFunction, Router } from 'express';
 
-// Session Configuration
+export { JWTPayload } from 'jose';
+
+// Session Mode constants
+export const SessionMode: {
+  SESSION: string;
+  TOKEN: string;
+};
+
+// Session Configuration - uses strict UPPERCASE naming convention for all property names
 export interface SessionConfig {
+  /** Identity Provider */
   SSO_ENDPOINT_URL?: string;
   SSO_CLIENT_ID?: string;
   SSO_CLIENT_SECRET?: string;
   SSO_SUCCESS_URL?: string;
   SSO_FAILURE_URL?: string;
 
+  /** Authentication mode: 'session' or 'token' (default: 'session') */
+  SESSION_MODE?: string;
+
   SESSION_AGE?: number;
   SESSION_COOKIE_PATH?: string;
   SESSION_SECRET?: string;
@@ -20,6 +32,15 @@ export interface SessionConfig {
 
   REDIS_URL?: string;
   REDIS_CERT_PATH?: string;
+
+  JWT_ALGORITHM?: string;
+  JWT_ENCRYPTION?: string;
+  JWT_EXPIRATION_TIME?: string;
+  JWT_CLOCK_TOLERANCE?: number;
+  JWT_SECRET_HASH_ALGORITHM?: string;
+  JWT_ISSUER?: string;
+  JWT_AUDIENCE?: string;
+  JWT_SUBJECT?: string;
 }
 
 export interface SessionUserAttributes {
@@ -58,7 +79,7 @@ export interface SessionUser {
 export class SessionManager {
   /**
    * Constructor
-   * @param config - Session configuration
+   * @param config - Session configuration (uses strict UPPERCASE property names)
    */
   constructor(config: SessionConfig);
 
@@ -97,15 +118,35 @@ export class SessionManager {
   ): Promise<void>;
 
   /**
-   * Resource protection middleware
+   * Resource protection middleware based on configured SESSION_MODE
+   * Uses verifySession() for SESSION mode and verifyToken() for TOKEN mode
    * @param isDebugging Debugging flag (default: false)
    * @param redirectUrl Redirect URL (default: '')
    * @returns Returns express Request Handler
    */
   authenticate(isDebugging?: boolean, redirectUrl?: string): RequestHandler;
 
+  /**
+   * Resource protection by token (explicit token verification)
+   * Requires Authorization: Bearer {token} header
+   * @param isDebugging Debugging flag (default: false)
+   * @param redirectUrl Redirect URL (default: '')
+   * @returns Returns express Request Handler
+   */
+  verifyToken(isDebugging?: boolean, redirectUrl?: string): RequestHandler;
+
+  /**
+   * Resource protection by session (explicit session verification)
+   * @param isDebugging Debugging flag (default: false)
+   * @param redirectUrl Redirect URL (default: '')
+   * @returns Returns express Request Handler
+   */
+  verifySession(isDebugging?: boolean, redirectUrl?: string): RequestHandler;
+
   /**
    * SSO callback for successful login
+   * SESSION mode: Saves session and redirects
+   * TOKEN mode: Generates JWT token, returns HTML page with localStorage script
    * @param initUser Initialize user object function
    * @returns Returns express Request Handler
    */
@@ -118,17 +159,22 @@ export class SessionManager {
   identityProviders(): RequestHandler;
 
   /**
-   * Application logout (NOT SSO)
+   * Refresh user authentication based on configured SESSION_MODE
+   * SESSION mode: Refreshes session data
+   * TOKEN mode: Generates new token, invalidates old token
+   * @param initUser Initialize user object function
    * @returns Returns express Request Handler
    */
-  logout(): RequestHandler;
+  refresh(initUser: (user: SessionUser) => SessionUser): RequestHandler;
 
   /**
-   * Refresh user session
-   * @param initUser Initialize user object function
+   * Application logout based on configured SESSION_MODE (NOT SSO)
+   * SESSION mode: Destroys session and clears cookie
+   * TOKEN mode: Invalidates current token or all tokens (with ?all=true query param)
+   * Query params: redirect=true (redirect to success/failure URL), all=true (logout all tokens - TOKEN mode only)
    * @returns Returns express Request Handler
    */
-  refresh(initUser: (user: SessionUser) => SessionUser): RequestHandler;
+  logout(): RequestHandler;
 }
 
 // Custom Error class
@@ -187,7 +233,7 @@ export class RedisManager {
 
   /**
    * Determine if the Redis server is connected
-   * @returns Returns true if Redis server is connected
+   * @returns Returns true if the Redis server is connected
    */
   isConnected(): Promise<boolean>;
 
@@ -198,57 +244,81 @@ export class RedisManager {
   disConnect(): Promise<void>;
 }
 
-// JWT Manager Configuration
+// JWT Manager Configuration - uses strict UPPERCASE naming convention with JWT_ prefix for all property names
 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;
+  /** JWE algorithm (default: 'dir') */
+  JWT_ALGORITHM?: string;
+  
+  /** JWE encryption method (default: 'A256GCM') */
+  JWT_ENCRYPTION?: string;
+  
+  /** Token expiration time (default: '10m') */
+  JWT_EXPIRATION_TIME?: string;
+  
+  /** Clock tolerance in seconds for token validation (default: 30) */
+  JWT_CLOCK_TOLERANCE?: number;
+  
+  /** Hash algorithm for secret derivation (default: 'SHA-256') */
+  JWT_SECRET_HASH_ALGORITHM?: string;
+  
+  /** Optional JWT issuer claim */
+  JWT_ISSUER?: string;
+  
+  /** Optional JWT audience claim */
+  JWT_AUDIENCE?: string;
+  
+  /** Optional JWT subject claim */
+  JWT_SUBJECT?: string;
 }
 
+/**
+ * Options for encrypt() method - uses camelCase naming convention
+ */
 export interface JwtEncryptOptions {
-  /** @type {string} Override default algorithm */
+  /** Override default algorithm */
   algorithm?: string;
-  /** @type {string} Override default encryption method */
+
+  /** Override default encryption method */
   encryption?: string;
-  /** @type {string} Override default expiration time */
+
+  /** Override default expiration time */
   expirationTime?: string;
-  /** @type {string} Override default hash algorithm */
+
+  /** Override default hash algorithm */
   secretHashAlgorithm?: string;
-  /** @type {string} Override default issuer claim */
+
+  /** Override default issuer claim */
   issuer?: string;
-  /** @type {string} Override default audience claim */
+
+  /** Override default audience claim */
   audience?: string;
-  /** @type {string} Override default subject claim */
+
+  /** Override default subject claim */
   subject?: string;
 }
 
+/**
+ * Options for decrypt() method - uses camelCase naming convention
+ */
 export interface JwtDecryptOptions {
-  /** @type {number} Override default clock tolerance */
+  /** Override default clock tolerance */
   clockTolerance?: number;
-  /** @type {string} Override default hash algorithm */
+
+  /** Override default hash algorithm */
   secretHashAlgorithm?: string;
-  /** @type {string} Expected issuer claim for validation */
+
+  /** Expected issuer claim for validation */
   issuer?: string;
-  /** @type {string} Expected audience claim for validation */
+
+  /** Expected audience claim for validation */
   audience?: string;
-  /** @type {string} Expected subject claim for validation */
+
+  /** Expected subject claim for validation */
   subject?: string;
 }
 
-export type DecryptedJWT = JWTDecryptResult<EncryptJWT>;
+export type JwtDecryptResult = JWTDecryptResult<EncryptJWT>;
+
 // JwtManager class for JWT encryption and decryption
 export class JwtManager {
   algorithm: string;
@@ -262,7 +332,7 @@ export class JwtManager {
 
   /**
    * Create a new JwtManager instance with configurable defaults
-   * @param options Configuration options
+   * @param options Configuration options (uses strict UPPERCASE with JWT_ prefix property names)
    */
   constructor(options?: JwtManagerOptions);
 
@@ -270,7 +340,7 @@ export class JwtManager {
    * 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
+   * @param options Per-call configuration overrides (uses strict UPPERCASE with JWT_ prefix property names)
    * @returns Returns encrypted JWT token
    */
   encrypt(data: JWTPayload, input: string, options?: JwtEncryptOptions): Promise<string>;
@@ -279,10 +349,10 @@ export class JwtManager {
    * 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
+   * @param options Per-call configuration overrides (uses strict UPPERCASE with JWT_ prefix property names)
    * @returns Returns decrypted JWT token
    */
-  decrypt(token: string, input: string, options?: JwtDecryptOptions): Promise<DecryptedJWT>;
+  decrypt(token: string, input: string, options?: JwtDecryptOptions): Promise<JwtDecryptResult>;
 }
 
 // HTTP status code keys (exposed for type safety)
@@ -400,4 +470,4 @@ declare module 'express-session' {
     [key: string]: any;
     user?: SessionUser;
   }
-}
+}

package/index.js

@@ -1,4 +1,4 @@
-export { SessionConfig, SessionManager } from './components/session.js';
+export { SessionConfig, SessionManager, SessionMode } from './components/session.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';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@igxjs/node-components",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "Node components for igxjs",
   "main": "index.js",
   "type": "module",
@@ -26,16 +26,23 @@
     "axios": "^1.13.6",
     "connect-redis": "^9.0.0",
     "express-session": "^1.19.0",
-    "jose": "^6.1.3",
+    "jose": "^6.2.0",
     "memorystore": "^1.6.7"
   },
   "devDependencies": {
     "chai": "^6.2.2",
     "express": "^5.2.1",
-    "mocha": "^11.0.1",
+    "mocha": "^12.0.0-beta-10",
     "sinon": "^21.0.2",
     "supertest": "^7.0.0"
   },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "components/",
+    "LICENSE",
+    "README.md"
+  ],
   "publishConfig": {
     "access": "public"
   },

package/.github/workflows/node.js.yml

@@ -1,31 +0,0 @@
-# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs
-
-name: Node.js CI
-
-on:
-  push:
-    branches: [ "main" ]
-  pull_request:
-    branches: [ "main" ]
-
-jobs:
-  build:
-
-    runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: [18.x, 20.x, 22.x]
-        # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
-
-    steps:
-    - uses: actions/checkout@v4
-    - name: Use Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v4
-      with:
-        node-version: ${{ matrix.node-version }}
-        cache: 'npm'
-    - run: npm ci
-    - run: npm run build --if-present
-    - run: npm test

package/.github/workflows/npm-publish.yml

@@ -1,33 +0,0 @@
-# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
-# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
-
-name: Node.js Package
-
-on:
-  release:
-    types: [created]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-      - run: npm ci
-      - run: npm test
-
-  publish-npm:
-    needs: build
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org/
-      - run: npm ci
-      - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/docs/README.md

@@ -1,54 +0,0 @@
-# Node Components Documentation
-
-Detailed documentation for `@igxjs/node-components` - shared components for Express.js applications.
-
-## 📚 Component Documentation
-
-### Core Modules
-
-- **[SessionManager](./session-manager.md)** - SSO session management with Redis and memory storage
-  - Configuration options and singleton pattern
-  - Complete setup and usage examples
-  - API reference for all methods
-
-- **[FlexRouter](./flex-router.md)** - Flexible routing utility for Express.js
-  - Context path and middleware management
-  - API versioning and route organization
-  - Advanced usage patterns
-
-- **[RedisManager](./redis-manager.md)** - Redis connection management
-  - TLS/SSL support
-  - Connection monitoring and error handling
-  - Direct Redis operations
-
-- **[JWT Manager](./jwt-manager.md)** - JWT encryption and decryption
-  - Secure token-based authentication
-  - Express.js integration patterns
-  - Refresh token implementation
-
-- **[HTTP Handlers](./http-handlers.md)** - Standardized error handling
-  - Custom error classes and middleware
-  - HTTP status codes and messages
-  - Axios error handling and validation helpers
-
-## 🚀 Quick Links
-
-- [Main README](../README.md) - Package overview and installation
-- [GitHub Repository](https://github.com/igxjs/node-components)
-
-## 💡 Getting Help
-
-If you need help:
-1. Check the relevant component documentation above
-2. Review the examples in each guide
-3. Look at the type definitions in `index.d.ts`
-4. Open an issue on GitHub
-
-## 📖 Documentation Structure
-
-Each component documentation includes:
-- Overview of features
-- Configuration options
-- Basic and advanced usage examples
-- Complete API reference
-- Related documentation links

package/docs/flex-router.md

@@ -1,167 +0,0 @@
-# FlexRouter
-
-A flexible routing utility for Express.js that allows mounting routers with custom context paths and middleware handlers.
-
-## Overview
-
-FlexRouter provides a convenient way to organize and mount Express routers with predefined context paths and optional middleware. This is particularly useful for:
-- API versioning (e.g., `/api/v1`, `/api/v2`)
-- Separating public and protected routes
-- Applying middleware to specific route groups
-- Managing complex routing hierarchies
-
-## Usage Example
-
-```javascript
-import { Router } from 'express';
-import { FlexRouter } from '@igxjs/node-components';
-// Assuming you have an authenticate middleware
-// import { authenticate } from './middlewares/auth.js';
-
-// Create routers
-const publicRouter = Router();
-const privateRouter = Router();
-
-publicRouter.get('/health', (req, res) => {
-  res.send('OK');
-});
-
-privateRouter.get('/users', (req, res) => {
-  res.json({ users: [] });
-});
-
-// Define flex routers with context paths and optional middleware
-export const routers = [
-  new FlexRouter('/api/v1/public', publicRouter),
-  new FlexRouter('/api/v1/protected', privateRouter, [authenticate]), // with middleware
-];
-
-// Mount all routers to your Express app
-const app = express();
-const basePath = '';
-
-routers.forEach(router => {
-  router.mount(app, basePath);
-});
-
-// Routes will be available at:
-// - /api/v1/public/health
-// - /api/v1/protected/users (with authenticate middleware)
-```
-
-## Advanced Usage
-
-### Multiple Middleware
-
-You can apply multiple middleware functions to a FlexRouter:
-
-```javascript
-import { rateLimiter } from './middlewares/rate-limiter.js';
-import { logger } from './middlewares/logger.js';
-import { authenticate } from './middlewares/auth.js';
-
-const apiRouter = Router();
-
-apiRouter.get('/data', (req, res) => {
-  res.json({  [] });
-});
-
-// Apply multiple middleware in order
-const protectedApi = new FlexRouter(
-  '/api/v1',
-  apiRouter,
-  [logger, rateLimiter, authenticate] // Applied in this order
-);
-
-protectedApi.mount(app, '');
-```
-
-### Using Base Paths
-
-You can add a base path when mounting routers, useful for multi-tenant applications:
-
-```javascript
-const tenantRouter = Router();
-
-tenantRouter.get('/dashboard', (req, res) => {
-  res.json({ tenant: req.params.tenantId });
-});
-
-const flexRouter = new FlexRouter('/api', tenantRouter);
-
-// Mount with tenant-specific base path
-flexRouter.mount(app, '/tenant/:tenantId');
-
-// Route will be available at: /tenant/:tenantId/api/dashboard
-```
-
-### Organizing Routes by Feature
-
-```javascript
-// features/users/routes.js
-const usersRouter = Router();
-usersRouter.get('/', getAllUsers);
-usersRouter.post('/', createUser);
-export const usersFlexRouter = new FlexRouter('/users', usersRouter);
-
-// features/products/routes.js
-const productsRouter = Router();
-productsRouter.get('/', getAllProducts);
-export const productsFlexRouter = new FlexRouter('/products', productsRouter);
-
-// app.js
-import { usersFlexRouter } from './features/users/routes.js';
-import { productsFlexRouter } from './features/products/routes.js';
-
-const apiRouters = [usersFlexRouter, productsFlexRouter];
-
-apiRouters.forEach(router => router.mount(app, '/api/v1'));
-
-// Routes available:
-// - /api/v1/users
-// - /api/v1/products
-```
-
-## API
-
-### Constructor
-
-**`new FlexRouter(context, router, handlers?)`**
-
-Creates a new FlexRouter instance.
-
-**Parameters:**
-- `context` (string) - The context path for the router (e.g., `/api/v1`)
-- `router` (Router) - Express Router instance containing your route definitions
-- `handlers` (Array, optional) - Array of middleware handler functions to apply to all routes in this router
-
-**Returns:** FlexRouter instance
-
-### Methods
-
-**`mount(app, basePath)`**
-
-Mounts the router to an Express application with the specified base path.
-
-**Parameters:**
-- `app` (Express) - Express application instance
-- `basePath` (string) - Base path to prepend to the context path
-
-**Example:**
-```javascript
-const flexRouter = new FlexRouter('/api', router);
-flexRouter.mount(app, '/v1'); // Mounts at /v1/api
-```
-
-## Best Practices
-
-1. **Group Related Routes**: Use FlexRouter to group related routes together
-2. **Apply Middleware Strategically**: Apply middleware at the FlexRouter level for route groups that share the same requirements
-3. **Consistent Naming**: Use consistent naming conventions for context paths (e.g., all lowercase, kebab-case)
-4. **Version Your APIs**: Use FlexRouter to manage different API versions easily
-5. **Keep Routers Focused**: Each router should handle a specific feature or resource type
-
-## Related Documentation
-
-- [SessionManager](./session-manager.md) - For authentication middleware usage
-- [Back to main documentation](../README.md)