@igxjs/node-components 1.0.10 → 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/session.js

@@ -1,3 +1,4 @@
+import crypto from 'node:crypto';
 import axios from 'axios';
 import session from 'express-session';
 import memStore from 'memorystore';
@@ -7,11 +8,25 @@ import { CustomError, httpCodes, httpHelper, httpMessages } from './http-handler
 import { JwtManager } from './jwt.js';
 import { RedisManager } from './redis.js';
 
+/**
+ * Session authentication mode constants
+ */
+export const SessionMode = {
+  SESSION: 'session',
+  TOKEN: 'token'
+};
+
 /**
  * Session configuration options
- * Uses strict UPPERCASE naming convention for all property names
  */
 export class SessionConfig {
+  /** 
+   * @type {string} 
+   * Authentication mode for protected routes
+   * Supported values: SessionMode.SESSION | SessionMode.TOKEN
+   * @default SessionMode.SESSION
+   */
+  SESSION_MODE;
   /** @type {string} */
   SSO_ENDPOINT_URL;
   /** @type {string} */
@@ -73,6 +88,8 @@ export class SessionManager {
    */
   constructor(config) {
     this.#config = {
+      // Session Mode
+      SESSION_MODE: config.SESSION_MODE || SessionMode.SESSION,
       // Session
       SESSION_AGE: config.SESSION_AGE || 64800000,
       SESSION_COOKIE_PATH: config.SESSION_COOKIE_PATH || '/',
@@ -141,6 +158,27 @@ export class SessionManager {
     return 'user';
   }
 
+  /**
+   * Get Redis key for token storage
+   * @param {string} email User email
+   * @param {string} tokenId Token ID
+   * @returns {string} Returns the Redis key for token storage
+   * @private
+   */
+  #getTokenRedisKey(email, tokenId) {
+    return `${this.#config.SESSION_PREFIX}token:${email}:${tokenId}`;
+  }
+
+  /**
+   * Get Redis key pattern for all user tokens
+   * @param {string} email User email
+   * @returns {string} Returns the Redis key pattern for all user tokens
+   * @private
+   */
+  #getTokenRedisPattern(email) {
+    return `${this.#config.SESSION_PREFIX}token:${email}:*`;
+  }
+
   /**
    * Get RedisManager instance
    * @returns {import('./redis.js').RedisManager} Returns the RedisManager instance
@@ -149,6 +187,368 @@ export class SessionManager {
     return this.#redisManager;
   }
 
+  /**
+   * Generate and store JWT token in Redis
+   * @param {object} user User object
+   * @returns {Promise<string>} Returns the generated JWT token
+   * @private
+   */
+  async #generateAndStoreToken(user) {
+    // Generate unique token ID for this device/session
+    const tokenId = crypto.randomUUID();
+    
+    // Create JWT token with email and tokenId
+    const token = await this.#jwtManager.encrypt(
+      { 
+        email: user.email, 
+        tokenId 
+      },
+      this.#config.SESSION_SECRET,
+      { expirationTime: this.#config.JWT_EXPIRATION_TIME }
+    );
+    
+    // Store user data in Redis with TTL
+    const redisKey = this.#getTokenRedisKey(user.email, tokenId);
+    const ttlSeconds = Math.floor(this.#config.SESSION_AGE / 1000);
+    
+    await this.#redisManager.getClient().setEx(
+      redisKey,
+      ttlSeconds,
+      JSON.stringify(user)
+    );
+    
+    console.debug(`### TOKEN GENERATED: ${user.email} ###`);
+    
+    return token;
+  }
+
+  /**
+   * Verify token authentication
+   * @param {import('@types/express').Request} req Request
+   * @param {import('@types/express').Response} res Response
+   * @param {import('@types/express').NextFunction} next Next function
+   * @param {boolean} isDebugging Debugging flag
+   * @param {string} redirectUrl Redirect URL
+   * @private
+   */
+  async #verifyToken(req, res, next, isDebugging, redirectUrl) {
+    try {
+      // Extract token from Authorization header
+      const authHeader = req.headers.authorization;
+      if (!authHeader?.startsWith('Bearer ')) {
+        throw new CustomError(httpCodes.UNAUTHORIZED, 'Missing or invalid authorization header');
+      }
+
+      const token = authHeader.substring(7); // Remove 'Bearer ' prefix
+
+      // Decrypt JWT token
+      const { payload } = await this.#jwtManager.decrypt(
+        token,
+        this.#config.SESSION_SECRET
+      );
+
+      // Extract email and tokenId
+      const { email, tokenId } = payload;
+      if (!email || !tokenId) {
+        throw new CustomError(httpCodes.UNAUTHORIZED, 'Invalid token payload');
+      }
+
+      // Lookup user in Redis
+      const redisKey = this.#getTokenRedisKey(email, tokenId);
+      const userData = await this.#redisManager.getClient().get(redisKey);
+
+      if (!userData) {
+        throw new CustomError(httpCodes.UNAUTHORIZED, 'Token not found or expired');
+      }
+
+      // Parse and attach user to request
+      req.user = JSON.parse(userData);
+      res.locals.user = req.user;
+
+      // Validate authorization
+      const { authorized = isDebugging } = req.user ?? { authorized: isDebugging };
+      if (!authorized && !isDebugging) {
+        throw new CustomError(httpCodes.FORBIDDEN, 'User is not authorized');
+      }
+
+      return next();
+
+    } catch (error) {
+      if (isDebugging) {
+        console.warn('### TOKEN VERIFICATION FAILED (debugging mode) ###', error.message);
+        return next();
+      }
+
+      if (redirectUrl) {
+        return res.redirect(redirectUrl);
+      }
+
+      // Handle specific JWT errors
+      if (error.code === 'ERR_JWT_EXPIRED') {
+        return next(new CustomError(httpCodes.UNAUTHORIZED, 'Token expired'));
+      }
+
+      return next(error instanceof CustomError ? error : 
+        new CustomError(httpCodes.UNAUTHORIZED, 'Token verification failed'));
+    }
+  }
+
+  /**
+   * Verify session authentication
+   * @param {import('@types/express').Request} req Request
+   * @param {import('@types/express').Response} res Response
+   * @param {import('@types/express').NextFunction} next Next function
+   * @param {boolean} isDebugging Debugging flag
+   * @param {string} redirectUrl Redirect URL
+   * @private
+   */
+  async #verifySession(req, res, next, isDebugging, redirectUrl) {
+    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));
+  }
+
+  /**
+   * Refresh token authentication
+   * @param {import('@types/express').Request} req Request
+   * @param {import('@types/express').Response} res Response
+   * @param {import('@types/express').NextFunction} next Next function
+   * @param {(user: object) => object} initUser Initialize user function
+   * @param {string} idpUrl Identity provider URL
+   * @private
+   */
+  async #refreshToken(req, res, next, initUser, idpUrl) {
+    try {
+      // Get current user from verifyToken middleware
+      const { email, attributes } = req.user || {};
+
+      if (!email) {
+        throw new CustomError(httpCodes.UNAUTHORIZED, 'User not authenticated');
+      }
+
+      // Extract tokenId from current token
+      const authHeader = req.headers.authorization;
+      const token = authHeader?.substring(7);
+      const { payload } = await this.#jwtManager.decrypt(token, this.#config.SESSION_SECRET);
+      const oldTokenId = payload.tokenId;
+
+      // Check refresh lock
+      if (this.hasLock(email)) {
+        throw new CustomError(httpCodes.CONFLICT, 'Token refresh is locked');
+      }
+      this.lock(email);
+
+      // Call SSO refresh endpoint
+      const response = await this.#idpRequest.post(idpUrl, {
+        user: {
+          email,
+          attributes: {
+            idp: attributes?.idp,
+            refresh_token: attributes?.refresh_token
+          }
+        }
+      });
+
+      if (response.status !== httpCodes.OK) {
+        throw new CustomError(response.status, response.statusText);
+      }
+
+      // Decrypt new user data from SSO
+      const { jwt } = response.data;
+      const { payload: newPayload } = await this.#jwtManager.decrypt(jwt, this.#config.SSO_CLIENT_SECRET);
+
+      if (!newPayload?.user) {
+        throw new CustomError(httpCodes.BAD_REQUEST, 'Invalid JWT payload from SSO');
+      }
+
+      // Initialize user with new data
+      const user = initUser(newPayload.user);
+
+      // Generate new token
+      const newToken = await this.#generateAndStoreToken(user);
+
+      // Remove old token from Redis
+      const oldRedisKey = this.#getTokenRedisKey(email, oldTokenId);
+      await this.#redisManager.getClient().del(oldRedisKey);
+
+      console.debug('### TOKEN REFRESHED SUCCESSFULLY ###');
+
+      // Return new token
+      return res.json({
+        token: newToken,
+        user,
+        expiresIn: Math.floor(this.#config.SESSION_AGE / 1000),
+        tokenType: 'Bearer'
+      });
+    } catch (error) {
+      return next(httpHelper.handleAxiosError(error));
+    }
+  }
+
+  /**
+   * Refresh session authentication
+   * @param {import('@types/express').Request} req Request
+   * @param {import('@types/express').Response} res Response
+   * @param {import('@types/express').NextFunction} next Next function
+   * @param {(user: object) => object} initUser Initialize user function
+   * @param {string} idpUrl Identity provider URL
+   * @private
+   */
+  async #refreshSession(req, res, next, initUser, idpUrl) {
+    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) {
+        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 all tokens for a user
+   * @param {import('@types/express').Request} req Request
+   * @param {import('@types/express').Response} res Response
+   * @param {boolean} isRedirect Whether to redirect
+   * @private
+   */
+  async #logoutAllTokens(req, res, isRedirect) {
+    try {
+      const { email } = req.user || {};
+
+      if (!email) {
+        throw new CustomError(httpCodes.UNAUTHORIZED, 'User not authenticated');
+      }
+
+      // Find all tokens for this user
+      const pattern = this.#getTokenRedisPattern(email);
+      const keys = await this.#redisManager.getClient().keys(pattern);
+
+      // Delete all tokens
+      if (keys.length > 0) {
+        await this.#redisManager.getClient().del(keys);
+      }
+
+      console.info(`### ALL TOKENS LOGGED OUT: ${email} (${keys.length} tokens) ###`);
+
+      if (isRedirect) {
+        return res.redirect(this.#config.SSO_SUCCESS_URL);
+      }
+      return res.json({ 
+        message: 'All tokens logged out successfully',
+        tokensRemoved: keys.length,
+        redirect_url: this.#config.SSO_SUCCESS_URL
+      });
+    } catch (error) {
+      console.error('### LOGOUT ALL TOKENS ERROR ###', error);
+      if (isRedirect) {
+        return res.redirect(this.#config.SSO_FAILURE_URL);
+      }
+      return res.status(httpCodes.SYSTEM_FAILURE).json({ 
+        error: 'Logout all failed',
+        redirect_url: this.#config.SSO_FAILURE_URL
+      });
+    }
+  }
+
+  /**
+   * Logout token authentication
+   * @param {import('@types/express').Request} req Request
+   * @param {import('@types/express').Response} res Response
+   * @param {boolean} isRedirect Whether to redirect
+   * @param {boolean} logoutAll Whether to logout all tokens
+   * @private
+   */
+  async #logoutToken(req, res, isRedirect, logoutAll = false) {
+    // If logoutAll is true, delegate to the all tokens logout method
+    if (logoutAll) {
+      return this.#logoutAllTokens(req, res, isRedirect);
+    }
+
+    try {
+      // Extract tokenId from current token
+      const authHeader = req.headers.authorization;
+      const token = authHeader?.substring(7);
+
+      if (!token) {
+        throw new CustomError(httpCodes.BAD_REQUEST, 'No token provided');
+      }
+
+      const { payload } = await this.#jwtManager.decrypt(token, this.#config.SESSION_SECRET);
+      const { email, tokenId } = payload;
+
+      // Remove token from Redis
+      const redisKey = this.#getTokenRedisKey(email, tokenId);
+      await this.#redisManager.getClient().del(redisKey);
+
+      console.info('### TOKEN LOGOUT SUCCESSFULLY ###');
+
+      if (isRedirect) {
+        return res.redirect(this.#config.SSO_SUCCESS_URL);
+      }
+      return res.json({ 
+        message: 'Logout successful',
+        redirect_url: this.#config.SSO_SUCCESS_URL
+      });
+
+    } catch (error) {
+      console.error('### TOKEN LOGOUT ERROR ###', error);
+      if (isRedirect) {
+        return res.redirect(this.#config.SSO_FAILURE_URL);
+      }
+      return res.status(httpCodes.SYSTEM_FAILURE).json({ 
+        error: 'Logout failed',
+        redirect_url: this.#config.SSO_FAILURE_URL
+      });
+    }
+  }
+
+  /**
+   * Logout session authentication
+   * @param {import('@types/express').Request} req Request
+   * @param {import('@types/express').Response} res Response
+   * @param {Function} callback Callback function
+   * @private
+   */
+  #logoutSession(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('### SESSION LOGOUT SUCCESSFULLY ###');
+      return callback(null);
+    });
+  }
+
   /**
    * Setup the session/user handlers with configurations
    * @param {import('@types/express').Application} app Express application
@@ -225,24 +625,44 @@ export class SessionManager {
   }
 
   /**
-   * Resource protection
+   * Resource protection based on configured SESSION_MODE
    * @param {boolean} [isDebugging=false] Debugging flag
-   * @param {boolean} [redirectUrl=''] Redirect flag
+   * @param {string} [redirectUrl=''] Redirect URL
    * @returns {import('@types/express').RequestHandler} Returns express Request Handler
    */
-  authenticate (isDebugging = false, redirectUrl = '') {
+  authenticate(isDebugging = false, redirectUrl = '') {
     return async (req, res, next) => {
-      /** @type {{ authorized: boolean }} */
-      const { authorized = isDebugging } = req.user ?? { authorized: isDebugging };
-      if (authorized) {
-        return next();
+      const mode = this.#config.SESSION_MODE || SessionMode.SESSION;
+      if (mode === SessionMode.TOKEN) {
+        return this.#verifyToken(req, res, next, isDebugging, redirectUrl);
       }
-      if(redirectUrl) {
-        return res.redirect(redirectUrl);
-      }
-      return next(new CustomError(httpCodes.UNAUTHORIZED, httpMessages.UNAUTHORIZED));
+      return this.#verifySession(req, res, next, isDebugging, redirectUrl);
     };
-  };
+  }
+
+  /**
+   * Resource protection by token (explicit token verification)
+   * @param {boolean} [isDebugging=false] Debugging flag
+   * @param {string} [redirectUrl=''] Redirect URL
+   * @returns {import('@types/express').RequestHandler} Returns express Request Handler
+   */
+  verifyToken(isDebugging = false, redirectUrl = '') {
+    return async (req, res, next) => {
+      return this.#verifyToken(req, res, next, isDebugging, redirectUrl);
+    };
+  }
+
+  /**
+   * Resource protection by session (explicit session verification)
+   * @param {boolean} [isDebugging=false] Debugging flag
+   * @param {string} [redirectUrl=''] Redirect URL
+   * @returns {import('@types/express').RequestHandler} Returns express Request Handler
+   */
+  verifySession(isDebugging = false, redirectUrl = '') {
+    return async (req, res, next) => {
+      return this.#verifySession(req, res, next, isDebugging, redirectUrl);
+    };
+  }
 
   /**
    * Save session
@@ -279,16 +699,77 @@ export class SessionManager {
   callback(initUser) {
     return async (req, res, next) => {
       const { jwt = '' } = req.query;
-      if(!jwt) {
+      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);
+        // Decrypt JWT from Identity Adapter
+        const { payload } = await this.#jwtManager.decrypt(jwt, this.#config.SSO_CLIENT_SECRET);
+        
+        if (!payload?.user) {
+          throw new CustomError(httpCodes.BAD_REQUEST, 'Invalid JWT payload');
+        }
+
+        const user = initUser(payload.user);
+        const redirectUrl = payload.redirect_url || this.#config.SSO_SUCCESS_URL;
+
+        // Check SESSION_MODE to determine response type
+        if (this.#config.SESSION_MODE === SessionMode.TOKEN) {
+          // Token-based: Generate token and return HTML page that stores it
+          const token = await this.#generateAndStoreToken(user);
+
+          console.debug('### CALLBACK TOKEN GENERATED ###');
+
+          // Return HTML page that stores token in localStorage and redirects
+          return res.send(`
+            <!DOCTYPE html>
+            <html>
+            <head>
+              <meta charset="UTF-8">
+              <title>Authentication Complete</title>
+              <script>
+                (function() {
+                  try {
+                    // Store auth data in localStorage
+                    localStorage.setItem('authToken', ${JSON.stringify(token)});
+                    localStorage.setItem('tokenExpiry', ${Date.now() + this.#config.SESSION_AGE});
+                    localStorage.setItem('user', ${JSON.stringify({
+                      email: user.email,
+                      name: user.name,
+                    })});
+                    
+                    // Redirect to original destination
+                    window.location.replace(${JSON.stringify(redirectUrl)});
+                  } catch (error) {
+                    console.error('Failed to store authentication:', error);
+                    document.getElementById('error').style.display = 'block';
+                  }
+                })();
+              </script>
+              <style>
+                body { font-family: system-ui, sans-serif; text-align: center; padding: 50px; }
+                #error { display: none; color: #d32f2f; margin-top: 20px; }
+              </style>
+            </head>
+            <body>
+              <p>Completing authentication...</p>
+              <div id="error">
+                <p>Authentication failed. Please try again.</p>
+                <a href="${this.#config.SSO_FAILURE_URL}">Return to login</a>
+              </div>
+            </body>
+            </html>
+          `);
+        }
+        else {
+          // Session-based: Save to session and redirect
+          await this.#saveSession(req, jwt, initUser);
+          return res.redirect(redirectUrl);
+        }
       }
       catch (error) {
-        console.error('### LOGIN ERROR ###');
-        console.error(error);
+        console.error('### CALLBACK ERROR ###', error);
         return res.redirect(this.#config.SSO_FAILURE_URL.concat('?message=').concat(encodeURIComponent(error.message)));
       }
     };
@@ -315,86 +796,57 @@ export class SessionManager {
   }
 
   /**
-   * 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
+   * Refresh user authentication based on configured SESSION_MODE
    * @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));
+      const mode = this.#config.SESSION_MODE || SessionMode.SESSION;
+      
+      if (mode === SessionMode.TOKEN) {
+        return this.#refreshToken(req, res, next, initUser, idpUrl);
+      } else {
+        return this.#refreshSession(req, res, next, initUser, idpUrl);
       }
     };
   }
 
   /**
-   * Logout
-   * @param {import('@types/express').Request} req Request
-   * @param {import('@types/express').Response} res Response
-   * @param {(error: Error)} callback Callback
+   * Application logout based on configured SESSION_MODE (NOT SSO)
+   * @returns {import('@types/express').RequestHandler} Returns express Request Handler
    */
-  #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);
+  logout() {
+    return async (req, res) => {
+      const { redirect = false, all = false } = req.query;
+      const isRedirect = (redirect === 'true' || redirect === true);
+      const logoutAll = (all === 'true' || all === true);
+      const mode = this.#config.SESSION_MODE || SessionMode.SESSION;
+      
+      if (mode === SessionMode.TOKEN) {
+        return this.#logoutToken(req, res, isRedirect, logoutAll);
       }
-      console.info('### LOGOUT SUCCESSFULLY ###');
-      return callback(null);
-    });
+
+      // Note: 'all' parameter is only applicable for token-based authentication
+      // Session-based authentication is already single-instance per cookie
+      return this.#logoutSession(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 });
+      });
+    };
   }
+
 }

package/index.d.ts

@@ -5,6 +5,14 @@ import { EncryptJWT, JWTDecryptResult, JWTPayload } from 'jose';
 import { RedisClientType } from '@redis/client';
 import { Application, RequestHandler, Request, Response, NextFunction, Router } from 'express';
 
+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 */
@@ -14,6 +22,9 @@ export interface SessionConfig {
   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;
@@ -21,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 {
@@ -98,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
    */
@@ -119,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
@@ -273,6 +318,7 @@ export interface JwtDecryptOptions {
 }
 
 export type JwtDecryptResult = JWTDecryptResult<EncryptJWT>;
+
 // JwtManager class for JWT encryption and decryption
 export class JwtManager {
   algorithm: string;

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.10",
+  "version": "1.0.11",
   "description": "Node components for igxjs",
   "main": "index.js",
   "type": "module",