@igxjs/node-components 1.0.9 → 1.0.11

package/README.md

@@ -12,7 +12,7 @@ npm install @igxjs/node-components
 
 | Component | Description | Documentation |
 |-----------|-------------|---------------|
-| **SessionManager** | SSO session management with Redis/memory storage | [View docs](./docs/session-manager.md) |
+| **SessionManager** | SSO session management with Redis/memory storage, supporting both session and token-based authentication | [View docs](./docs/session-manager.md) |
 | **FlexRouter** | Flexible routing with context paths and middleware | [View docs](./docs/flex-router.md) |
 | **RedisManager** | Redis connection management with TLS support | [View docs](./docs/redis-manager.md) |
 | **JWT Manager** | Secure JWT encryption/decryption with JWE | [View docs](./docs/jwt-manager.md) |
@@ -23,9 +23,9 @@ npm install @igxjs/node-components
 ### SessionManager
 
 ```javascript
-import { SessionManager } from '@igxjs/node-components';
+import { SessionManager, SessionMode } from '@igxjs/node-components';
 
-// Create singleton instance
+// Create singleton instance with SESSION authentication (default)
 export const session = new SessionManager({
   SSO_ENDPOINT_URL: process.env.SSO_ENDPOINT_URL,
   SSO_CLIENT_ID: process.env.SSO_CLIENT_ID,
@@ -34,6 +34,16 @@ export const session = new SessionManager({
   REDIS_URL: process.env.REDIS_URL
 });
 
+// Create singleton instance with TOKEN authentication
+export const tokenSession = new SessionManager({
+  SESSION_MODE: SessionMode.TOKEN,  // Use token-based authentication
+  SSO_ENDPOINT_URL: process.env.SSO_ENDPOINT_URL,
+  SSO_CLIENT_ID: process.env.SSO_CLIENT_ID,
+  SSO_CLIENT_SECRET: process.env.SSO_CLIENT_SECRET,
+  SESSION_SECRET: process.env.SESSION_SECRET,
+  REDIS_URL: process.env.REDIS_URL,
+});
+
 // Setup in your app
 await session.setup(app, (user) => ({ ...user, displayName: user.email }));
 
@@ -105,9 +115,93 @@ app.use(httpErrorHandler);
 
 [📖 Full HTTP Handlers Documentation](./docs/http-handlers.md)
 
+## SessionManager Authentication Modes
+
+The `SessionManager` supports two authentication modes:
+
+### SESSION Mode (Default)
+
+Uses traditional server-side session cookies. When a user authenticates via SSO, their session is stored in Redis or memory storage. The client sends the session cookie with each request to prove authentication.
+
+**Configuration:**
+- `SESSION_MODE`: `SessionMode.SESSION` (default) - Uses session-based authentication
+- `SESSION_AGE`: Session timeout in milliseconds (default: 64800000)
+- `REDIS_URL`: Redis connection string for session storage
+
+**Auth Methods:**
+- `session.authenticate()` - Protect routes with SSO session verification
+- `session.verifySession(isDebugging, redirectUrl)` - Explicit session verification method
+- `session.logout(redirect?, all?)` - Logout current session (or logout all for token mode)
+
+### TOKEN Mode
+
+Uses JWT bearer tokens instead of session cookies. When a user authenticates via SSO, a JWT token is generated and stored in Redis. The client includes the token in the Authorization header (`Bearer {token}`) with each request.
+
+**Configuration:**
+- `SESSION_MODE`: `SessionMode.TOKEN` - Uses token-based authentication
+- `SSO_SUCCESS_URL`: Redirect URL after successful SSO login
+- `SSO_FAILURE_URL`: Redirect URL after failed SSO login  
+- `JWT_ALGORITHM`: JWT algorithm (default: `'dir'`)
+- `JWT_ENCRYPTION`: Encryption algorithm (default: `'A256GCM'`)
+- `JWT_EXPIRATION_TIME`: Token expiration time (default: `'10m'`)
+- `JWT_CLOCK_TOLERANCE`: Clock skew tolerance in seconds (default: 30)
+
+**Auth Methods:**
+- `session.verifyToken(isDebugging, redirectUrl)` - Protect routes with token verification
+- `session.callback(initUser)` - SSO callback handler for token generation
+- `session.refresh(initUser)` - Refresh user authentication based on auth mode
+- `session.logout(redirect?, all?)` - Logout current or all tokens
+
+**Token Storage (Client-Side):**
+
+When using token-based authentication, the client-side HTML page stores the token in `localStorage`:
+
+```html
+<script>
+  // Store auth data in localStorage
+  localStorage.setItem('authToken', ${JSON.stringify(token)});
+  localStorage.setItem('tokenExpiry', ${Date.now() + sessionAge});
+  localStorage.setItem('user', ${JSON.stringify({
+    email: user.email,
+    name: user.name,
+  })});
+  
+  // Redirect to original destination
+  window.location.replace(redirectUrl);
+</script>
+```
+
+## SessionManager Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `SSO_ENDPOINT_URL` | string | - | Identity provider endpoint URL |
+| `SSO_CLIENT_ID` | string | - | SSO client ID |
+| `SSO_CLIENT_SECRET` | string | - | SSO client secret |
+| `SSO_SUCCESS_URL` | string | - | Redirect URL after successful login (token mode) |
+| `SSO_FAILURE_URL` | string | - | Redirect URL after failed login (token mode) |
+| `SESSION_MODE` | string | `SessionMode.SESSION` | Authentication mode: `SessionMode.SESSION` or `SessionMode.TOKEN` |
+| `SESSION_AGE` | number | 64800000 | Session timeout in milliseconds |
+| `SESSION_COOKIE_PATH` | string | `'/'` | Session cookie path |
+| `SESSION_SECRET` | string | - | Session/JWT secret key |
+| `SESSION_PREFIX` | string | `'ibmid:'` | Redis session/key prefix |
+| `REDIS_URL` | string | - | Redis connection URL (optional) |
+| `REDIS_CERT_PATH` | string | - | Path to Redis TLS certificate |
+| `JWT_ALGORITHM` | string | `'dir'` | JWT signing algorithm |
+| `JWT_ENCRYPTION` | string | `'A256GCM'` | JWE encryption algorithm |
+| `JWT_EXPIRATION_TIME` | string | `'10m'` | Token expiration duration |
+| `JWT_CLOCK_TOLERANCE` | number | 30 | Clock skew tolerance in seconds |
+| `JWT_SECRET_HASH_ALGORITHM` | string | `'SHA-256'` | Algorithm for hashing secrets |
+| `JWT_ISSUER` | string | - | JWT issuer identifier |
+| `JWT_AUDIENCE` | string | - | JWT audience identifier |
+| `JWT_SUBJECT` | string | - | JWT subject identifier |
+
 ## Features
 
 - ✅ **SSO Integration** - Full SSO support with Redis or memory storage
+- ✅ **Dual Authentication Modes** - SESSION (cookies) or TOKEN (Bearer tokens)
+- ✅ **Token Refresh** - Automatic token refresh via SSO endpoints
+- ✅ **Session Refresh Locks** - Prevent concurrent token/session refresh attacks
 - ✅ **JWT Security** - Encrypted JWT tokens using JWE (jose library)
 - ✅ **Flexible Routing** - Easy mounting with context paths and middleware
 - ✅ **Redis Support** - TLS/SSL and automatic reconnection
@@ -148,4 +242,4 @@ import type {
 
 ## License
 
-[Apache 2.0](LICENSE)
+[Apache 2.0](LICENSE)

package/components/http-handlers.js

@@ -141,6 +141,12 @@ const _getErrorMessage = (error, defaultMessage) => {
 };
 
 export const httpHelper = {
+  /**
+   * Format a string with placeholders
+   * @param {string} str String with {0}, {1}, etc. placeholders
+   * @param {...string} args Values to replace placeholders
+   * @returns {string} Formatted string
+   */
   format (str, ...args) {
     const matched = str.match(/{\d}/ig);
     matched.forEach((element, index) => {

package/components/jwt.js

@@ -1,51 +1,89 @@
+import crypto from 'node:crypto';
+
 import { jwtDecrypt, EncryptJWT } from 'jose';
 
+/**
+ * JwtManager configuration options
+ * Uses strict UPPERCASE naming convention with JWT_ prefix for all property names.
+ */
 export class JwtManager {
+  /** @type {string} JWE algorithm */
+  algorithm;
+  
+  /** @type {string} Encryption method */
+  encryption;
+  
+  /** @type {string} Token expiration time */
+  expirationTime;
+  
+  /** @type {number} Clock tolerance in seconds */
+  clockTolerance;
+  
+  /** @type {string} Hash algorithm for secret derivation */
+  secretHashAlgorithm;
+  
+  /** @type {string|null} Optional JWT issuer claim */
+  issuer;
+  
+  /** @type {string|null} Optional JWT audience claim */
+  audience;
+  
+  /** @type {string|null} Optional JWT subject claim */
+  subject;
   /**
    * 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 use UPPERCASE naming convention with JWT_ prefix (e.g., JWT_ALGORITHM).
+   * 
+   * @typedef {Object} JwtManagerOptions JwtManager configuration options
+   * @property {string} [JWT_ALGORITHM='dir'] JWE algorithm (default: 'dir')
+   * @property {string} [JWT_ENCRYPTION='A256GCM'] Encryption method (default: 'A256GCM')
+   * @property {string} [JWT_EXPIRATION_TIME='10m'] Token expiration time (default: '10m')
+   * @property {string} [JWT_SECRET_HASH_ALGORITHM='SHA-256'] Hash algorithm (default: 'SHA-256')
+   * @property {string?} [JWT_ISSUER] Optional JWT issuer claim
+   * @property {string?} [JWT_AUDIENCE] Optional JWT audience claim
+   * @property {string?} [JWT_SUBJECT] Optional JWT subject claim
+   * @property {number} [JWT_CLOCK_TOLERANCE=30] Clock tolerance in seconds (default: 30)
+   * @param {JwtManagerOptions} options Configuration options
    */
   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;
+    this.algorithm = options.JWT_ALGORITHM || 'dir';
+    this.encryption = options.JWT_ENCRYPTION || 'A256GCM';
+    this.expirationTime = options.JWT_EXPIRATION_TIME || '10m';
+    this.secretHashAlgorithm = options.JWT_SECRET_HASH_ALGORITHM || 'SHA-256';
+    this.issuer = options.JWT_ISSUER;
+    this.audience = options.JWT_AUDIENCE;
+    this.subject = options.JWT_SUBJECT;
+    this.clockTolerance = options.JWT_CLOCK_TOLERANCE ?? 30;
   }
 
+  /**
+   * Encrypt method options (camelCase naming convention, uses instance defaults when not provided)
+   * 
+   * @typedef {Object} JwtEncryptOptions Encryption method options
+   * @property {string} [algorithm='dir'] JWE algorithm (overrides instance JWT_ALGORITHM)
+   * @property {string} [encryption='A256GCM'] Encryption method (overrides instance JWT_ENCRYPTION)
+   * @property {string} [expirationTime='10m'] Token expiration time (overrides instance JWT_EXPIRATION_TIME)
+   * @property {string} [secretHashAlgorithm='SHA-256'] Hash algorithm for secret derivation (overrides instance JWT_SECRET_HASH_ALGORITHM)
+   * @property {string?} [issuer] Optional JWT issuer claim (overrides instance JWT_ISSUER)
+   * @property {string?} [audience] Optional JWT audience claim (overrides instance JWT_AUDIENCE)
+   * @property {string?} [subject] Optional JWT subject claim (overrides instance JWT_SUBJECT)
+   */
   /**
    * Generate JWT token for user session
+   * 
    * @param {import('jose').JWTPayload} data User data payload
    * @param {string} secret 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
+   * @param {JwtEncryptOptions} [options] Per-call configuration overrides (camelCase naming convention)
    * @returns {Promise<string>} Returns encrypted JWT token
    */
   async encrypt(data, secret, 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 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 secretHash = await crypto.subtle.digest(
       secretHashAlgorithm,
@@ -69,23 +107,29 @@ export class JwtManager {
   }
 
   /**
-   * Decrypt JWT token for user session
+   * Decrypt method options (camelCase naming convention, uses instance defaults when not provided)
+   * 
+   * @typedef {Object} JwtDecryptOptions Decryption method options
+   * @property {number} [clockTolerance=30] Clock tolerance in seconds (overrides instance JWT_CLOCK_TOLERANCE)
+   * @property {string} [secretHashAlgorithm='SHA-256'] Hash algorithm for secret derivation (overrides instance JWT_SECRET_HASH_ALGORITHM)
+   * @property {string?} [issuer] Optional JWT issuer claim for validation (overrides instance JWT_ISSUER)
+   * @property {string?} [audience] Optional JWT audience claim for validation (overrides instance JWT_AUDIENCE)
+   * @property {string?} [subject] Optional JWT subject claim for validation (overrides instance JWT_SUBJECT)
+   **/
+  /**
+   * Decrypt JWT
+   * 
    * @param {string} token JWT token to decrypt
    * @param {string} secret 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
+   * @param {JwtDecryptOptions} [options] Per-call configuration overrides (camelCase naming convention)
+   * @returns {Promise<import('jose').JWTDecryptResult<import('jose').EncryptJWT>} Returns decrypted JWT token
    */
   async decrypt(token, secret, 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 secretHashAlgorithm = options.secretHashAlgorithm ?? this.secretHashAlgorithm;
+    const issuer = options.issuer ?? this.issuer;
+    const audience = options.audience ?? this.audience;
+    const subject = options.subject ?? this.subject;
 
     const secretHash = await crypto.subtle.digest(
       secretHashAlgorithm,
@@ -101,4 +145,4 @@ export class JwtManager {
 
     return await jwtDecrypt(token, new Uint8Array(secretHash), decryptOptions);
   }
-}
+}