@igxjs/node-components 1.0.5 → 1.0.7

package/README.md

@@ -206,7 +206,173 @@ if (connected) {
 
 ---
 
-### 4. HTTP Handlers
+### 4. JWT Manager
+
+Provides JWT (JSON Web Token) encryption and decryption utilities using the `jose` library with JWE (JSON Web Encryption) for secure token management.
+
+#### Configuration Options
+
+```javascript
+// Example configuration object
+const jwtOptions = {
+  algorithm: 'dir',              // JWE algorithm (default: 'dir')
+  encryption: 'A256GCM',         // JWE encryption method (default: 'A256GCM')
+  expirationTime: '10m',         // Token expiration (default: '10m')
+  clockTolerance: 30,            // Clock tolerance in seconds (default: 30)
+  secretHashAlgorithm: 'SHA-256', // Hash algorithm for secret derivation (default: 'SHA-256')
+  issuer: 'your-app',            // Optional JWT issuer claim
+  audience: 'your-users',        // Optional JWT audience claim
+  subject: 'user-session'        // Optional JWT subject claim
+};
+```
+
+#### Usage Example
+
+```javascript
+import { JwtManager } from '@igxjs/node-components';
+
+// Create instance with default configuration
+const jwtManager = new JwtManager({
+  expirationTime: '1h',
+  issuer: 'my-app',
+  audience: 'my-users'
+});
+
+// Encrypt user data
+const userData = {
+  userId: '12345',
+  email: 'user@example.com',
+  roles: ['admin', 'user']
+};
+
+const secret = 'your-secret-key';
+const token = await jwtManager.encrypt(userData, secret);
+
+console.log('Encrypted Token:', token);
+
+// Decrypt token
+try {
+  const result = await jwtManager.decrypt(token, secret);
+  console.log('Decrypted Payload:', result.payload);
+  console.log('Protected Header:', result.protectedHeader);
+} catch (error) {
+  console.error('Token validation failed:', error);
+}
+
+// Override options per-call
+const shortLivedToken = await jwtManager.encrypt(
+  userData,
+  secret,
+  { expirationTime: '5m' }  // Override default expiration
+);
+
+// Decrypt with custom validation
+const validatedResult = await jwtManager.decrypt(
+  token,
+  secret,
+  {
+    clockTolerance: 60,  // Allow more clock skew
+    issuer: 'my-app',    // Validate issuer
+    audience: 'my-users' // Validate audience
+  }
+);
+```
+
+#### Advanced Usage with Express
+
+```javascript
+import express from 'express';
+import { JwtManager } from '@igxjs/node-components';
+
+const app = express();
+const jwt = new JwtManager({ expirationTime: '24h' });
+const SECRET = process.env.JWT_SECRET;
+
+// Login endpoint - create token
+app.post('/api/login', async (req, res, next) => {
+  try {
+    const { username, password } = req.body;
+    
+    // Verify credentials (your logic here)
+    const user = await verifyCredentials(username, password);
+    
+    // Create JWT token
+    const token = await jwt.encrypt({
+      sub: user.id,
+      email: user.email,
+      roles: user.roles
+    }, SECRET);
+    
+    res.json({ token });
+  } catch (error) {
+    next(error);
+  }
+});
+
+// Protected endpoint - verify token
+app.get('/api/profile', async (req, res, next) => {
+  try {
+    const token = req.headers.authorization?.replace('Bearer ', '');
+    
+    if (!token) {
+      return res.status(401).json({ error: 'No token provided' });
+    }
+    
+    // Decrypt and validate token
+    const { payload } = await jwt.decrypt(token, SECRET);
+    
+    res.json({ user: payload });
+  } catch (error) {
+    // Token expired or invalid
+    res.status(401).json({ error: 'Invalid or expired token' });
+  }
+});
+```
+
+#### API Methods
+
+**Constructor:**
+- **`new JwtManager(options?)`** - Create a new JwtManager instance
+  - `options` (JwtManagerOptions, optional) - Configuration options
+  - All options are optional and have sensible defaults
+
+**Methods:**
+- **`encrypt(data, input, options?)`** - Generate encrypted JWT token
+  - `data` (JWTPayload) - User data payload to encrypt
+  - `input` (string) - Secret key or password for encryption
+  - `options` (JwtEncryptOptions, optional) - Per-call configuration overrides
+  - Returns: `Promise<string>` - Encrypted JWT token
+
+- **`decrypt(token, input, options?)`** - Decrypt and validate JWT token
+  - `token` (string) - JWT token to decrypt
+  - `input` (string) - Secret key or password for decryption
+  - `options` (JwtDecryptOptions, optional) - Per-call configuration overrides
+  - Returns: `Promise<JWTDecryptResult>` - Object containing `payload` and `protectedHeader`
+
+#### Configuration Details
+
+**Algorithms:**
+- `'dir'` (default) - Direct encryption with shared symmetric key
+- `'A128KW'`, `'A192KW'`, `'A256KW'` - AES Key Wrap algorithms
+
+**Encryption Methods:**
+- `'A256GCM'` (default) - AES-GCM with 256-bit key
+- `'A128GCM'`, `'A192GCM'` - AES-GCM with 128/192-bit keys
+
+**Expiration Time Format:**
+- `'10m'` - 10 minutes
+- `'1h'` - 1 hour
+- `'7d'` - 7 days
+- `'30s'` - 30 seconds
+
+**JWT Claims:**
+- `issuer` (iss) - Token issuer identification
+- `audience` (aud) - Intended token recipient
+- `subject` (sub) - Token subject (usually user ID)
+
+---
+
+### 5. HTTP Handlers
 
 Custom error handling utilities with standardized HTTP status codes and error responses.
 
@@ -215,7 +381,9 @@ Custom error handling utilities with standardized HTTP status codes and error re
 ```javascript
 import { 
   CustomError, 
-  httpErrorHandler, 
+  httpError,
+  httpErrorHandler,
+  httpNotFoundHandler,
   httpCodes, 
   httpMessages,
   httpHelper 
@@ -227,9 +395,12 @@ import {
 **Creating Custom Errors:**
 
 ```javascript
-// Basic custom error
+// Using CustomError class
 throw new CustomError(httpCodes.BAD_REQUEST, 'Invalid input data');
 
+// Using httpError helper function (alias for new CustomError)
+throw httpError(httpCodes.BAD_REQUEST, 'Invalid input data');
+
 // With error details and additional data
 throw new CustomError(
   httpCodes.UNAUTHORIZED,
@@ -237,6 +408,14 @@ throw new CustomError(
   { originalError: err },
   { attemptedEmail: email }
 );
+
+// Using httpError with additional data
+throw httpError(
+  httpCodes.UNAUTHORIZED,
+  'Authentication failed',
+  { originalError: err },
+  { attemptedEmail: email }
+);
 ```
 
 **Handling Axios/HTTP Errors:**
@@ -265,7 +444,7 @@ app.get('/api/data', async (req, res, next) => {
 
 ```javascript
 import express from 'express';
-import { httpErrorHandler } from '@igxjs/node-components';
+import { httpErrorHandler, httpNotFoundHandler } from '@igxjs/node-components';
 
 const app = express();
 
@@ -278,29 +457,31 @@ app.get('/api/data', async (req, res, next) => {
   }
 });
 
+// Add 404 handler before error handler
+app.use(httpNotFoundHandler);
+
 // Add error handler as the last middleware
 app.use(httpErrorHandler);
 ```
 
 #### HTTP Codes & Messages
 
-```javascript
-httpCodes.OK               // 200
-httpCodes.CREATED          // 201
-httpCodes.NO_CONTENT       // 204
-httpCodes.BAD_REQUEST      // 400
-httpCodes.UNAUTHORIZED     // 401
-httpCodes.FORBIDDEN        // 403
-httpCodes.NOT_FOUND        // 404
-httpCodes.NOT_ACCEPTABLE   // 406
-httpCodes.CONFLICT         // 409
-httpCodes.SYSTEM_FAILURE   // 500
-
-// Corresponding messages
-httpMessages.OK            // 'OK'
-httpMessages.BAD_REQUEST   // 'Bad Request'
-// ... etc
-```
+**Available Status Codes:**
+- `httpCodes.OK` (200)
+- `httpCodes.CREATED` (201)
+- `httpCodes.NO_CONTENT` (204)
+- `httpCodes.BAD_REQUEST` (400)
+- `httpCodes.UNAUTHORIZED` (401)
+- `httpCodes.FORBIDDEN` (403)
+- `httpCodes.NOT_FOUND` (404)
+- `httpCodes.NOT_ACCEPTABLE` (406)
+- `httpCodes.CONFLICT` (409)
+- `httpCodes.LOCKED` (423)
+- `httpCodes.SYSTEM_FAILURE` (500)
+- `httpCodes.NOT_IMPLEMENTED` (501)
+
+**Available Status Messages:**
+- Corresponding `httpMessages` constants are available for each status code (e.g., `httpMessages.OK`, `httpMessages.BAD_REQUEST`, etc.)
 
 #### CustomError API
 
@@ -319,6 +500,35 @@ httpMessages.BAD_REQUEST   // 'Bad Request'
 - **`error`** - Original error object (if provided)
 - **`data`** - Additional error data (if provided)
 
+#### httpError API
+
+**Function:**
+- **`httpError(code, message, error?, data?)`** - Convenience function to create CustomError instances
+  - `code` (number) - HTTP status code
+  - `message` (string) - Error message
+  - `error` (object, optional) - Original error object
+  - `data` (object, optional) - Additional error data
+  - Returns: `CustomError` instance
+  - **Note:** This is an alias for `new CustomError()` - use whichever syntax you prefer
+
+#### httpErrorHandler API
+
+**Middleware Function:**
+- **`httpErrorHandler(err, req, res, next)`** - Express error handling middleware
+  - Handles `CustomError` instances and other errors
+  - Sets appropriate HTTP status codes and response format
+  - Adds CORS headers automatically
+  - Logs error details to console
+  - **Usage:** Add as the last middleware in your Express app
+
+#### httpNotFoundHandler API
+
+**Middleware Function:**
+- **`httpNotFoundHandler(req, res, next)`** - Express 404 handler middleware
+  - Catches all unmatched routes and returns 404 error
+  - Creates a `CustomError` with NOT_FOUND status
+  - **Usage:** Add before the error handler middleware
+
 #### httpHelper API
 
 The `httpHelper` object provides utility methods for error handling:
@@ -344,6 +554,7 @@ The `httpHelper` object provides utility methods for error handling:
 ## Features
 
 - ✅ **Session Management** - Full SSO integration with Redis or memory storage
+- ✅ **JWT Manager** - Secure JWT encryption/decryption with JWE using the jose library
 - ✅ **Flexible Routing** - Easy mounting of routers with context paths and middleware
 - ✅ **Redis Integration** - Robust Redis connection management with TLS support
 - ✅ **Error Handling** - Standardized error responses and HTTP status codes
@@ -367,6 +578,10 @@ import type {
   SessionManager,
   SessionUser,
   SessionUserAttributes,
+  JwtManager,
+  JwtManagerOptions,
+  JwtEncryptOptions,
+  JwtDecryptOptions,
   FlexRouter,
   RedisManager,
   CustomError 

package/components/http-handlers.js

@@ -10,19 +10,22 @@ export const httpMessages = {
   NOT_FOUND: 'Not Found',
   NOT_ACCEPTABLE: 'Not Acceptable',
   CONFLICT: 'Conflict',
+  LOCKED: 'Locked',
   SYSTEM_FAILURE: 'System Error',
+  NOT_IMPLEMENTED: 'Not Implemented',
 };
 
 export const httpCodes = {
   OK: 200,
   CREATED: 201,
-  NO_CONTENT: 201,
+  NO_CONTENT: 204,
   BAD_REQUEST: 400,
   UNAUTHORIZED: 401,
   FORBIDDEN: 403,
   NOT_FOUND: 404,
   NOT_ACCEPTABLE: 406,
   CONFLICT: 409,
+  LOCKED: 423,
   SYSTEM_FAILURE: 500,
   NOT_IMPLEMENTED: 501,
 };

package/components/jwt.js

@@ -0,0 +1,104 @@
+import { jwtDecrypt, EncryptJWT } from 'jose';
+
+export class JwtManager {
+  /**
+   * Create a new JwtManager instance with configurable defaults
+   * @param {Object} options Configuration options
+   * @param {string} [options.algorithm='dir'] JWE algorithm (e.g., 'dir', 'A128KW', 'A192KW', 'A256KW')
+   * @param {string} [options.encryption='A256GCM'] JWE encryption method (e.g., 'A256GCM', 'A128GCM', 'A192GCM')
+   * @param {string} [options.expirationTime='10m'] Token expiration time (e.g., '10m', '1h', '7d')
+   * @param {number} [options.clockTolerance=30] Clock tolerance in seconds for token validation
+   * @param {string} [options.secretHashAlgorithm='SHA-256'] Hash algorithm for secret derivation
+   * @param {string} [options.issuer] Optional JWT issuer claim
+   * @param {string} [options.audience] Optional JWT audience claim
+   * @param {string} [options.subject] Optional JWT subject claim
+   */
+  constructor(options = {}) {
+    this.algorithm = options.algorithm || 'dir';
+    this.encryption = options.encryption || 'A256GCM';
+    this.expirationTime = options.expirationTime || '10m';
+    this.clockTolerance = options.clockTolerance ?? 30;
+    this.secretHashAlgorithm = options.secretHashAlgorithm || 'SHA-256';
+    this.issuer = options.issuer;
+    this.audience = options.audience;
+    this.subject = options.subject;
+  }
+
+  /**
+   * Generate JWT token for user session
+   * @param {import('jose').JWTPayload} data User data payload
+   * @param {string} input Secret key or password for encryption
+   * @param {Object} [options] Per-call configuration overrides
+   * @param {string} [options.algorithm] Override default algorithm
+   * @param {string} [options.encryption] Override default encryption method
+   * @param {string} [options.expirationTime] Override default expiration time
+   * @param {string} [options.secretHashAlgorithm] Override default hash algorithm
+   * @param {string} [options.issuer] Override default issuer claim
+   * @param {string} [options.audience] Override default audience claim
+   * @param {string} [options.subject] Override default subject claim
+   * @returns {Promise<string>} Returns encrypted JWT token
+   */
+  async encrypt(data, input, options = {}) {
+    const algorithm = options.algorithm || this.algorithm;
+    const encryption = options.encryption || this.encryption;
+    const expirationTime = options.expirationTime || this.expirationTime;
+    const secretHashAlgorithm = options.secretHashAlgorithm || this.secretHashAlgorithm;
+    const issuer = options.issuer || this.issuer;
+    const audience = options.audience || this.audience;
+    const subject = options.subject || this.subject;
+
+    const secret = await crypto.subtle.digest(
+      secretHashAlgorithm,
+      new TextEncoder().encode(input)
+    );
+
+    const jwt = new EncryptJWT(data)
+      .setProtectedHeader({
+        alg: algorithm,
+        enc: encryption
+      })
+      .setIssuedAt()
+      .setExpirationTime(expirationTime);
+
+    // Add optional claims if provided
+    if (issuer) jwt.setIssuer(issuer);
+    if (audience) jwt.setAudience(audience);
+    if (subject) jwt.setSubject(subject);
+
+    return await jwt.encrypt(new Uint8Array(secret));
+  }
+
+  /**
+   * Decrypt JWT token for user session
+   * @param {string} token JWT token to decrypt
+   * @param {string} input Secret key or password for decryption
+   * @param {Object} [options] Per-call configuration overrides
+   * @param {number} [options.clockTolerance] Override default clock tolerance
+   * @param {string} [options.secretHashAlgorithm] Override default hash algorithm
+   * @param {string} [options.issuer] Expected issuer claim for validation
+   * @param {string} [options.audience] Expected audience claim for validation
+   * @param {string} [options.subject] Expected subject claim for validation
+   * @returns {Promise<import('jose').JWTDecryptResult<import('jose').EncryptJWT>>} Returns decrypted JWT token
+   */
+  async decrypt(token, input, options = {}) {
+    const clockTolerance = options.clockTolerance ?? this.clockTolerance;
+    const secretHashAlgorithm = options.secretHashAlgorithm || this.secretHashAlgorithm;
+    const issuer = options.issuer || this.issuer;
+    const audience = options.audience || this.audience;
+    const subject = options.subject || this.subject;
+
+    const secret = await crypto.subtle.digest(
+      secretHashAlgorithm,
+      new TextEncoder().encode(input)
+    );
+
+    const decryptOptions = { clockTolerance };
+
+    // Add optional claim validations if provided
+    if (issuer) decryptOptions.issuer = issuer;
+    if (audience) decryptOptions.audience = audience;
+    if (subject) decryptOptions.subject = subject;
+
+    return await jwtDecrypt(token, new Uint8Array(secret), decryptOptions);
+  }
+}

package/index.d.ts

@@ -1,6 +1,7 @@
 import 'express-session';
 
 import { AxiosError } from 'axios';
+import { JWTPayload, JWTDecryptResult } from 'jose';
 import { RedisClientType } from '@redis/client';
 import { Application, RequestHandler, Request, Response, NextFunction, Router } from 'express';
 
@@ -197,6 +198,92 @@ 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;
+}
+
+// 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<JWTDecryptResult>;
+}
+
 // HTTP status code keys (exposed for type safety)
 export const httpCodes: {
   OK: number;
@@ -208,7 +295,9 @@ export const httpCodes: {
   NOT_FOUND: number;
   NOT_ACCEPTABLE: number;
   CONFLICT: number;
+  LOCKED: number;
   SYSTEM_FAILURE: number;
+  NOT_IMPLEMENTED: number;
 };
 
 // HTTP message keys (exposed for type safety)
@@ -222,7 +311,9 @@ export const httpMessages: {
   NOT_FOUND: string;
   NOT_ACCEPTABLE: string;
   CONFLICT: string;
+  LOCKED: string;
   SYSTEM_FAILURE: string;
+  NOT_IMPLEMENTED: string;
 };
 
 /**
@@ -253,6 +344,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.5",
+  "version": "1.0.7",
   "description": "Node components for igxjs",
   "main": "index.js",
   "type": "module",