@igxjs/node-components 1.0.14 → 1.0.15

package/README.md

@@ -46,12 +46,18 @@ export const tokenSession = new SessionManager({
 });
 
 // Setup in your app
-await session.setup(app, (user) => ({ ...user, displayName: user.email }));
+await session.setup(app);
 
-// Protect routes
-app.get('/protected', session.authenticate(), (req, res) => {
+// Protect routes - user data automatically loaded into req.user
+app.get('/protected', session.authenticate(), session.requireUser(), (req, res) => {
   res.json({ user: req.user });
 });
+
+// SSO callback with user transformation
+app.get('/auth/callback', session.callback((user) => ({
+  ...user,
+  displayName: user.email
+})));
 ```
 
 [📖 Full SessionManager Documentation](./docs/session-manager.md)
@@ -131,8 +137,9 @@ Uses traditional server-side session cookies. When a user authenticates via SSO,
 - `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.authenticate(errorRedirectUrl)` - Protect routes with SSO session verification
+- `session.verifySession(errorRedirectUrl)` - Explicit session verification method
+- `session.requireUser()` - Middleware to load user data into `req.user` from session store
 - `session.logout(redirect?, all?)` - Logout current session (or logout all for token mode)
 
 ### TOKEN Mode
@@ -148,10 +155,11 @@ Uses JWT bearer tokens instead of session cookies. When a user authenticates via
 - `JWT_CLOCK_TOLERANCE`: Clock skew tolerance in seconds (default: 30)
 
 **Auth Methods:**
-- `session.verifyToken(isDebugging, redirectUrl)` - Protect routes with token verification
+- `session.verifyToken(errorRedirectUrl)` - Protect routes with token verification
+- `session.requireUser()` - Middleware to load user data into `req.user` from Redis using JWT token
 - `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
+- `session.logout(redirect?, all?)` - Logout current token or all tokens for user
 
 **Token Storage (Client-Side):**
 
@@ -186,6 +194,9 @@ fetch('/api/protected', {
 | `SESSION_COOKIE_PATH` | string | `'/'` | Session cookie path |
 | `SESSION_SECRET` | string | - | Session/JWT secret key |
 | `SESSION_PREFIX` | string | `'ibmid:'` | Redis session/key prefix |
+| `SESSION_KEY` | string | `'session_token'` | Redis key for session data (SESSION mode) or localStorage key for token (TOKEN mode) |
+| `SESSION_EXPIRY_KEY` | string | `'session_expires_at'` | localStorage key for session expiry timestamp (TOKEN mode) |
+| `TOKEN_STORAGE_TEMPLATE_PATH` | string | - | Path to custom HTML template for TOKEN mode callback |
 | `REDIS_URL` | string | - | Redis connection URL (optional) |
 | `REDIS_CERT_PATH` | string | - | Path to Redis TLS certificate |
 | `JWT_ALGORITHM` | string | `'dir'` | JWT signing algorithm |

package/components/session.js

@@ -137,6 +137,8 @@ export class SessionManager {
   #jwtManager = null;
   /** @type {import('./logger.js').Logger} */
   #logger = Logger.getInstance('SessionManager');
+  /** @type {string?} Cached HTML template for token storage */
+  #htmlTemplate = null;
 
   /**
    * Create a new session manager
@@ -291,6 +293,37 @@ export class SessionManager {
     return this.#redisManager;
   }
 
+  /**
+   * Setup the session/user handlers with configurations
+   * @param {import('@types/express').Application} app Express application
+   */
+  async setup(app) {
+    this.#redisManager = new RedisManager();
+    this.#jwtManager = new JwtManager({
+      ...this.#config,
+      JWT_EXPIRATION_TIME: this.#config.SESSION_AGE, // SESSION_AGE is already in seconds
+    });
+
+    // Identity Provider Request
+    this.#idpRequest = axios.create({
+      baseURL: this.#config.SSO_ENDPOINT_URL,
+      timeout: 30000,
+    });
+    app.set('trust proxy', 1);
+    const isOK = await this.#redisManager.connect(this.#config.REDIS_URL, this.#config.REDIS_CERT_PATH);
+    if (this.#config.SESSION_MODE === SessionMode.SESSION) {
+      app.use(this.#sessionHandler(isOK));
+    }
+
+    // Cache HTML template for TOKEN mode
+    if (this.#config.SESSION_MODE === SessionMode.TOKEN) {
+      const templatePath = this.#config.TOKEN_STORAGE_TEMPLATE_PATH ||
+        path.resolve(__dirname, 'assets', 'template.html');
+      this.#htmlTemplate = fs.readFileSync(templatePath, 'utf8');
+      this.#logger.debug('### HTML TEMPLATE CACHED ###');
+    }
+  }
+
   /**
    * Generate and store JWT token in Redis
    * - JWT payload contains only { email, tid } for minimal size
@@ -309,57 +342,44 @@ export class SessionManager {
   async #generateAndStoreToken(user) {
     // Generate unique token ID for this device/session
     const tid = crypto.randomUUID();
-    // SESSION_AGE is already in seconds
-    const ttlSeconds = this.#config.SESSION_AGE;
     // Create JWT token with only email and tid (minimal payload)
-    const token = await this.#jwtManager.encrypt(
-      { email: user.email, tid },
-      this.#config.SESSION_SECRET,
-      { expirationTime: ttlSeconds }
-    );
+    const payload = { email: user.email, tid };
+    const token = await this.#jwtManager.encrypt(payload, this.#config.SESSION_SECRET, { expirationTime: this.#config.SESSION_AGE });
 
     // Store user data in Redis with TTL
     const redisKey = this.#getTokenRedisKey(user.email, tid);
 
-    await this.#redisManager.getClient().setEx(
-      redisKey,
-      ttlSeconds,
-      JSON.stringify(user)
-    );
+    await this.#redisManager.getClient().setEx(redisKey, this.#config.SESSION_AGE, JSON.stringify(user));
     this.#logger.debug(`### TOKEN GENERATED: ${user.email} ###`);
     return token;
   }
 
   /**
-   * Verify token authentication - extracts and validates JWT from Authorization header
-   * @param {import('@types/express').Request} req Request with Authorization header
-   * @param {import('@types/express').Response} res Response object
-   * @param {import('@types/express').NextFunction} next Next middleware function
-   * @param {boolean} isDebugging If true, allows unauthenticated requests
-   * @param {string} redirectUrl URL to redirect to on authentication failure
-   * @throws {CustomError} If token is missing, invalid, or expired
+   * Extract and validate user data from Authorization header (TOKEN mode only)
+   * @param {string} authHeader Authorization header in format "Bearer {token}"
+   * @param {boolean} [fetchFromRedis=true] Whether to fetch full user data from Redis
+   *   - true: Returns { tid, user } with full user data from Redis (default)
+   *   - false: Returns JWT payload only (lightweight validation)
+   * @returns {Promise<{ tid: string?, email: string?, user: object? } | object>}
+   *   - When fetchFromRedis=true: { tid: string, user: object }
+   *   - When fetchFromRedis=false: JWT payload object
+   * @throws {CustomError} UNAUTHORIZED (401) if:
+   *   - Authorization header is missing or invalid format
+   *   - Token decryption fails
+   *   - Token payload is invalid (missing email/tid)
+   *   - Token not found in Redis (when fetchFromRedis=true)
    * @private
-   * @example
-   * // Authorization header format: "Bearer {jwt_token}"
-   * await this.#verifyToken(req, res, next, false, '/login');
    */
-  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
-      );
+  async #getUserFromToken(authHeader, fetchFromRedis = true) {
+    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 token ID
+    if (fetchFromRedis) {
+      /** @type {{ email: string, tid: string }} Extract email and token ID */
       const { email, tid } = payload;
       if (!email || !tid) {
         throw new CustomError(httpCodes.UNAUTHORIZED, 'Invalid token payload');
@@ -372,26 +392,58 @@ export class SessionManager {
       if (!userData) {
         throw new CustomError(httpCodes.UNAUTHORIZED, 'Token not found or expired');
       }
+      return { tid, user: JSON.parse(userData) };
+    }
+    return payload;
+  }
 
-      // Parse and attach user to request
-      req.user = JSON.parse(userData);
-
-      // Validate authorization
-      const { authorized = isDebugging } = req.user ?? { authorized: isDebugging };
-      if (!authorized && !isDebugging) {
-        throw new CustomError(httpCodes.FORBIDDEN, 'User is not authorized');
-      }
+  /**
+   * Get authenticated user data (works for both SESSION and TOKEN modes)
+   * @param {import('@types/express').Request} req Express request object
+   * @returns {Promise<object>} Full user data object
+   * @throws {CustomError} If user is not authenticated
+   * @public
+   * @example
+   * // Use in custom middleware
+   * app.use(async (req, res, next) => {
+   *   try {
+   *     const user = await sessionManager.getUser(req);
+   *     req.customUser = user;
+   *     next();
+   *   } catch (error) {
+   *     next(error);
+   *   }
+   * });
+   */
+  async getUser(req) {
+    if (this.#config.SESSION_MODE === SessionMode.TOKEN) {
+      const { user } = await this.#getUserFromToken(req.headers.authorization, true);
+      return user;
+    }
+    // Session mode
+    return req.session[this.#getSessionKey()];
+  }
 
+  /**
+   * Verify token authentication - extracts and validates JWT from Authorization header
+   * @param {import('@types/express').Request} req Request with Authorization header
+   * @param {import('@types/express').Response} res Response object
+   * @param {import('@types/express').NextFunction} next Next middleware function
+   * @param {string} errorRedirectUrl URL to redirect to on authentication failure
+   * @throws {CustomError} If token is missing, invalid, or expired
+   * @private
+   * @example
+   * // Authorization header format: "Bearer {jwt_token}"
+   * await this.#verifyToken(req, res, next, '/login');
+   */
+  async #verifyToken(req, res, next, errorRedirectUrl) {
+    try {
+      // Lightweight token validation (no Redis lookup)
+      await this.#getUserFromToken(req.headers.authorization, false);
       return next();
-
     } catch (error) {
-      if (isDebugging) {
-        this.#logger.warn('### TOKEN VERIFICATION FAILED (debugging mode) ###', error.message);
-        return next();
-      }
-
-      if (redirectUrl) {
-        return res.redirect(redirectUrl);
+      if (errorRedirectUrl) {
+        return res.redirect(errorRedirectUrl);
       }
 
       // Handle specific JWT errors
@@ -409,18 +461,19 @@ export class SessionManager {
    * @param {import('@types/express').Request} req Request with session data
    * @param {import('@types/express').Response} res Response object
    * @param {import('@types/express').NextFunction} next Next middleware function
-   * @param {boolean} isDebugging If true, allows unauthorized users
-   * @param {string} redirectUrl URL to redirect to if user is unauthorized
+   * @param {string} errorRedirectUrl URL to redirect to if user is unauthorized
    * @throws {CustomError} If user is not authorized
    * @private
    */
-  async #verifySession(req, res, next, isDebugging, redirectUrl) {
-    const { authorized = isDebugging } = req.user ?? { authorized: isDebugging };
+  async #verifySession(req, res, next, errorRedirectUrl) {
+    // Fix: Check session data directly, not req.user (which is only populated by requireUser())
+    const user = req.session[this.#getSessionKey()];
+    const { authorized = false } = user ?? { authorized: false };
     if (authorized) {
       return next();
     }
-    if (redirectUrl) {
-      return res.redirect(redirectUrl);
+    if (errorRedirectUrl) {
+      return res.redirect(errorRedirectUrl);
     }
     return next(new CustomError(httpCodes.UNAUTHORIZED, httpMessages.UNAUTHORIZED));
   }
@@ -432,41 +485,31 @@ export class SessionManager {
    * @param {import('@types/express').Response} res Response object
    * @param {import('@types/express').NextFunction} next Next middleware function
    * @param {(user: object) => object} initUser Function to initialize/transform user object
-   * @param {string} idpUrl Identity provider refresh endpoint URL
+   * @param {string} idpRefreshUrl Identity provider refresh endpoint URL
    * @throws {CustomError} If refresh lock is active or SSO refresh fails
    * @private
    * @example
    * // Response format:
-   * // { token: "new_jwt", user: {...}, expiresIn: 64800, tokenType: "Bearer" }
+   * // { jwt: "new_jwt", user: {...}, expires_at: 64800, token_type: "Bearer" }
    */
-  async #refreshToken(req, res, next, initUser, idpUrl) {
+  async #refreshToken(req, res, next, initUser, idpRefreshUrl) {
     try {
-      // Get current user from verifyToken middleware
-      const { email, attributes } = req.user || {};
-
-      if (!email) {
-        throw new CustomError(httpCodes.UNAUTHORIZED, 'User not authenticated');
-      }
-
-      // Extract Token ID 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 { tid: oldTokenId } = payload;
+      /** @type {{ tid: string, user: { email: string, attributes: { idp: string, refresh_token: string }? } }} */
+      const { tid, user } = await this.#getUserFromToken(req.headers.authorization, true);
 
       // Check refresh lock
-      if (this.hasLock(email)) {
+      if (this.hasLock(user?.email)) {
         throw new CustomError(httpCodes.CONFLICT, 'Token refresh is locked');
       }
-      this.lock(email);
+      this.lock(user?.email);
 
       // Call SSO refresh endpoint
-      const response = await this.#idpRequest.post(idpUrl, {
+      const response = await this.#idpRequest.post(idpRefreshUrl, {
         user: {
-          email,
+          email: user?.email,
           attributes: {
-            idp: attributes?.idp,
-            refresh_token: attributes?.refresh_token
+            idp: user?.attributes?.idp,
+            refresh_token: user?.attributes?.refresh_token
           }
         }
       });
@@ -484,24 +527,19 @@ export class SessionManager {
       }
 
       // Initialize user with new data
-      const user = initUser(newPayload.user);
+      const newUser = initUser(newPayload.user);
 
       // Generate new token
-      const newToken = await this.#generateAndStoreToken(user);
+      const newToken = await this.#generateAndStoreToken(newUser);
 
       // Remove old token from Redis
-      const oldRedisKey = this.#getTokenRedisKey(email, oldTokenId);
+      const oldRedisKey = this.#getTokenRedisKey(user.email, tid);
       await this.#redisManager.getClient().del(oldRedisKey);
 
       this.#logger.debug('### TOKEN REFRESHED SUCCESSFULLY ###');
 
       // Return new token
-      return res.json({
-        token: newToken,
-        user,
-        expiresIn: this.#config.SESSION_AGE, // Already in seconds
-        tokenType: 'Bearer'
-      });
+      return res.json({ jwt: newToken, user: newUser, expires_at: this.#config.SESSION_AGE, token_type: 'Bearer' });
     } catch (error) {
       return next(httpHelper.handleAxiosError(error));
     }
@@ -513,17 +551,17 @@ export class SessionManager {
    * @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
+   * @param {string} idpRefreshUrl Token Refresh URL
    * @private
    */
-  async #refreshSession(req, res, next, initUser, idpUrl) {
+  async #refreshSession(req, res, next, initUser, idpRefreshUrl) {
     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, {
+      const response = await this.#idpRequest.post(idpRefreshUrl, {
         user: {
           email,
           attributes: {
@@ -604,15 +642,8 @@ export class SessionManager {
     }
 
     try {
-      // Extract Token ID 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);
+      // Extract Token ID and email from current token
+      const payload = await this.#getUserFromToken(req.headers.authorization, false);
       const { email, tid } = payload;
 
       if (!email || !tid) {
@@ -670,27 +701,6 @@ export class SessionManager {
     });
   }
 
-  /**
-   * Setup the session/user handlers with configurations
-   * @param {import('@types/express').Application} app Express application
-   * @param {(user: object) => object} updateUser Update user object if user should have proper attributes, e.g. permissions, avatar URL
-   */
-  async setup(app, updateUser) {
-    this.#redisManager = new RedisManager();
-    this.#jwtManager = new JwtManager({
-      ...this.#config,
-      JWT_EXPIRATION_TIME: this.#config.SESSION_AGE, // SESSION_AGE is already in seconds
-    });
-    // Identity Provider Request
-    this.#idpRequest = axios.create({
-      baseURL: this.#config.SSO_ENDPOINT_URL,
-      timeout: 30000,
-    });
-    app.set('trust proxy', 1);
-    app.use(await this.#sessionHandler());
-    app.use(this.#userHandler(updateUser));
-  }
-
   /**
    * Get Redis session RequestHandler
    * @returns {import('@types/express').RequestHandler} Returns RequestHandler instance of Express
@@ -724,67 +734,85 @@ export class SessionManager {
 
   /**
    * Get session RequestHandler
-   * @returns {Promise<import('@types/express').RequestHandler>} Returns RequestHandler instance of Express
+   * @param {boolean} isRedisReady Is Redis Ready
+   * @returns {import('@types/express').RequestHandler} Returns RequestHandler instance of Express
    */
-  async #sessionHandler() {
-    if(this.#config.REDIS_URL?.length > 0) {
-      await this.#redisManager.connect(this.#config.REDIS_URL, this.#config.REDIS_CERT_PATH);
+  #sessionHandler(isRedisReady) {
+    if(isRedisReady) {
       return this.#redisSession();
     }
     return this.#memorySession();
   }
 
   /**
-   * User HTTP Handler
-   * @param {(user: object) => object} updateUser User wrapper
+   * Middleware to load full user data (works for both SESSION and TOKEN modes)
    * @returns {import('@types/express').RequestHandler} Returns express Request Handler
    */
-  #userHandler (updateUser) {
-    return (req, res, next) => {
-      req.user = req.session[this.#getSessionKey()];
-      /** @type {import('@types/express').Request & { user: object }} Session user */
-      res.locals.user = updateUser(req.user);
-      return next();
+  requireUser = () => {
+    return async (req, res, next) => {
+      try {
+        req.user = await this.getUser(req);
+        return next();
+      }
+      catch (error) {
+        return next(error);
+      }
     };
-  }
+  };
 
   /**
    * Resource protection based on configured SESSION_MODE
-   * @param {boolean} [isDebugging=false] Debugging flag
-   * @param {string} [redirectUrl=''] Redirect URL
+   * - SESSION mode: Verifies user exists in session store and is authorized (checks req.session data)
+   * - TOKEN mode: Validates JWT token from Authorization header (lightweight validation)
+   * 
+   * Note: This method verifies authentication only. Use requireUser() after this to populate req.user.
+   * 
+   * @param {string} [errorRedirectUrl=''] Redirect URL on authentication failure
    * @returns {import('@types/express').RequestHandler} Returns express Request Handler
-   */
-  authenticate(isDebugging = false, redirectUrl = '') {
+   * @example
+   * // Option 1: Just verify authentication (user data remains in req.session or token)
+   * app.get('/api/check', session.authenticate(), (req, res) => {
+   *   res.json({ authenticated: true });
+   * });
+   * 
+   * // Option 2: Verify authentication AND load user data into req.user
+   * app.get('/api/profile', 
+   *   session.authenticate(),   // Verifies session/token
+   *   session.requireUser(),     // Loads user data into req.user
+   *   (req, res) => {
+   *     res.json({ user: req.user }); // User data available here
+   *   }
+   * );
+   */
+  authenticate(errorRedirectUrl = '') {
     return async (req, res, next) => {
       const mode = this.#config.SESSION_MODE || SessionMode.SESSION;
       if (mode === SessionMode.TOKEN) {
-        return this.#verifyToken(req, res, next, isDebugging, redirectUrl);
+        return this.#verifyToken(req, res, next, errorRedirectUrl);
       }
-      return this.#verifySession(req, res, next, isDebugging, redirectUrl);
+      return this.#verifySession(req, res, next, errorRedirectUrl);
     };
   }
 
   /**
    * Resource protection by token (explicit token verification)
-   * @param {boolean} [isDebugging=false] Debugging flag
-   * @param {string} [redirectUrl=''] Redirect URL
+   * @param {string} [errorRedirectUrl=''] Redirect URL
    * @returns {import('@types/express').RequestHandler} Returns express Request Handler
    */
-  verifyToken(isDebugging = false, redirectUrl = '') {
+  verifyToken(errorRedirectUrl = '') {
     return async (req, res, next) => {
-      return this.#verifyToken(req, res, next, isDebugging, redirectUrl);
+      return this.#verifyToken(req, res, next, errorRedirectUrl);
     };
   }
 
   /**
    * Resource protection by session (explicit session verification)
-   * @param {boolean} [isDebugging=false] Debugging flag
-   * @param {string} [redirectUrl=''] Redirect URL
+   * @param {string} [errorRedirectUrl=''] Redirect URL
    * @returns {import('@types/express').RequestHandler} Returns express Request Handler
    */
-  verifySession(isDebugging = false, redirectUrl = '') {
+  verifySession(errorRedirectUrl = '') {
     return async (req, res, next) => {
-      return this.#verifySession(req, res, next, isDebugging, redirectUrl);
+      return this.#verifySession(req, res, next, errorRedirectUrl);
     };
   }
 
@@ -813,62 +841,75 @@ export class SessionManager {
       });
     }
     throw new CustomError(httpCodes.BAD_REQUEST, 'Invalid JWT payload');
-  };
-
-  /**
-   * SSO callback for successful login
-   * @param {(user: object) => object} initUser Initialize user object function
-   * @returns {import('@types/express').RequestHandler} Returns express Request Handler
-   */
-  callback(initUser) {
-    return async (req, res, next) => {
-      const { jwt = '' } = req.query;
-      if (!jwt) {
-        return next(new CustomError(httpCodes.BAD_REQUEST, 'Missing `jwt` in query parameters'));
-      }
-
-      try {
-        // 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');
+    };
+  
+    /**
+     * Render HTML template for token storage
+     * @param {string} token JWT token
+     * @param {string} expiresAt Expiry timestamp
+     * @param {string} sucessRedirectUrl Success redirect URL
+     * @returns {string} Rendered HTML
+     * @private
+     */
+    #renderTokenStorageHtml(token, expiresAt, sucessRedirectUrl) {
+      return this.#htmlTemplate
+        .replaceAll('{{SESSION_DATA_KEY}}', this.#config.SESSION_KEY)
+        .replaceAll('{{SESSION_DATA_VALUE}}', token)
+        .replaceAll('{{SESSION_EXPIRY_KEY}}', this.#config.SESSION_EXPIRY_KEY)
+        .replaceAll('{{SESSION_EXPIRY_VALUE}}', expiresAt)
+        .replaceAll('{{SSO_SUCCESS_URL}}', sucessRedirectUrl)
+        .replaceAll('{{SSO_FAILURE_URL}}', this.#config.SSO_FAILURE_URL);
+    }
+  
+    /**
+     * SSO callback for successful login
+     * @param {(user: object) => object} initUser Initialize user object function
+     * @returns {import('@types/express').RequestHandler} Returns express Request Handler
+     */
+    callback(initUser) {
+      return async (req, res, next) => {
+        const { jwt = '' } = req.query;
+        if (!jwt) {
+          return next(new CustomError(httpCodes.BAD_REQUEST, 'Missing `jwt` in query parameters'));
         }
+  
+        try {
+          // 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');
+          }
+  
+          /** @type {import('../index.js').SessionUser} */
+          const user = initUser(payload.user);
+          /** @type {string} */
+          const callbackRedirectUrl = payload.redirect_url || this.#config.SSO_SUCCESS_URL;
+  
+          // Token mode: Generate token and return HTML page
+          if (this.#config.SESSION_MODE === SessionMode.TOKEN) {
+            const token = await this.#generateAndStoreToken(user);
+            this.#logger.debug('### CALLBACK TOKEN GENERATED ###');
+            const html = this.#renderTokenStorageHtml(token, user.attributes.expires_at, callbackRedirectUrl);
+            return res.send(html);
+          }
 
-        /** @type {import('../index.js').SessionUser} */
-        const user = initUser(payload.user);
-        /** @type {string} */
-        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);
-
-          this.#logger.debug('### CALLBACK TOKEN GENERATED ###');
-
-          const templatePath = this.#config.TOKEN_STORAGE_TEMPLATE_PATH || path.resolve(__dirname, 'assets', 'template.html');
-          // Return HTML page that stores token in localStorage and redirects
-          const template = fs.readFileSync(templatePath, 'utf8');
-          const html = template
-            .replaceAll('{{SESSION_DATA_KEY}}', this.#config.SESSION_KEY)
-            .replaceAll('{{SESSION_DATA_VALUE}}', token)
-            .replaceAll('{{SESSION_EXPIRY_KEY}}', this.#config.SESSION_EXPIRY_KEY)
-            .replaceAll('{{SESSION_EXPIRY_VALUE}}', user.attributes.expires_at)
-            .replaceAll('{{SSO_SUCCESS_URL}}', redirectUrl)
-            .replaceAll('{{SSO_FAILURE_URL}}', this.#config.SSO_FAILURE_URL);
-          return res.send(html);
+          // Session mode: Save to session and redirect
+          await this.#saveSession(req, jwt, initUser);
+          return res.redirect(callbackRedirectUrl);
         }
-        // Session-based: Save to session and redirect
-        await this.#saveSession(req, jwt, initUser);
-        return res.redirect(redirectUrl);
-      }
-      catch (error) {
-        this.#logger.error('### CALLBACK ERROR ###', error);
-        return res.redirect(this.#config.SSO_FAILURE_URL.concat('?message=').concat(encodeURIComponent(error.message)));
-      }
-    };
-  }
+        catch (error) {
+          this.#logger.error('### CALLBACK ERROR ###', error);
+          let errorMessage = error.message;
+          if (error.code === 'ERR_JWT_EXPIRED') {
+            errorMessage = 'Authentication token expired';
+          } else if (error.code === 'ERR_JWT_INVALID') {
+            errorMessage = 'Invalid authentication token';
+          }
+          return res.redirect(this.#config.SSO_FAILURE_URL.concat('?message=').concat(encodeURIComponent(errorMessage)));
+        }
+      };
+    }
 
   /**
    * Get Identity Providers
@@ -896,14 +937,14 @@ export class SessionManager {
    * @returns {import('@types/express').RequestHandler} Returns express Request Handler
    */
   refresh(initUser) {
-    const idpUrl = '/auth/refresh'.concat('?client_id=').concat(this.#config.SSO_CLIENT_ID);
+    const idpRefreshUrl = '/auth/refresh'.concat('?client_id=').concat(this.#config.SSO_CLIENT_ID);
     return async (req, res, next) => {
       const mode = this.#config.SESSION_MODE || SessionMode.SESSION;
-      
+
       if (mode === SessionMode.TOKEN) {
-        return this.#refreshToken(req, res, next, initUser, idpUrl);
+        return this.#refreshToken(req, res, next, initUser, idpRefreshUrl);
       } else {
-        return this.#refreshSession(req, res, next, initUser, idpUrl);
+        return this.#refreshSession(req, res, next, initUser, idpRefreshUrl);
       }
     };
   }

package/index.d.ts

@@ -142,24 +142,27 @@ export interface SessionConfig {
    */
   SESSION_SECRET?: string;
 
-  /** 
+  /**
    * Redis key prefix for storing session data
    * @example 'myapp:session:' (will result in keys like 'myapp:session:user@example.com')
-   * @default 'sess:'
+   * @default 'ibmid:' (legacy default, consider changing for your use case)
    */
   SESSION_PREFIX?: string;
 
-  /** 
+  /**
    * Redis key name for storing session data
+   * - In SESSION mode: key used to store the user in the session
+   * - In TOKEN mode: key of localStorage where the token is stored
    * @example 'user' (results in session.user containing user data)
-   * @default 'user'
+   * @default 'session_token'
    */
   SESSION_KEY?: string;
 
-  /** 
+  /**
    * Redis key name for storing session expiry timestamp
+   * - In TOKEN mode: key of localStorage where the session expiry timestamp is stored
    * @example 'expires' (results in session.expires containing expiry time)
-   * @default 'expires'
+   * @default 'session_expires_at'
    */
   SESSION_EXPIRY_KEY?: string;
 
@@ -311,41 +314,98 @@ export class SessionManager {
   redisManager(): RedisManager;
 
   /**
-   * Initialize the session configurations
+   * Get authenticated user data (works for both SESSION and TOKEN modes)
+   * @param req Express request object
+   * @returns Promise resolving to full user data object
+   * @throws CustomError If user is not authenticated
+   * @example
+   * ```javascript
+   * // Use in custom middleware
+   * app.use(async (req, res, next) => {
+   *   try {
+   *     const user = await sessionManager.getUser(req);
+   *     req.customUser = user;
+   *     next();
+   *   } catch (error) {
+   *     next(error);
+   *   }
+   * });
+   * ```
+   */
+  getUser(req: Request): Promise<SessionUser>;
+
+  /**
+   * Initialize the session configurations and middleware
    * @param app Express application
-   * @param config Session configurations
-   * @param updateUser Process user object to compute attributes like permissions, avatar URL, etc.
    */
-  setup(
-    app: Application,
-    updateUser: (user: SessionUser | undefined) => any
-  ): Promise<void>;
+  setup(app: Application): Promise<void>;
+
+  /**
+   * Middleware to load full user data into req.user
+   * - SESSION mode: Loads user from session store (req.session[SESSION_KEY])
+   * - TOKEN mode: Loads user from Redis using JWT token
+   * - Provides request-level caching to avoid redundant lookups
+   * - Should be used after authenticate() middleware
+   * @returns Returns express Request Handler
+   * @example
+   * ```javascript
+   * app.get('/api/profile',
+   *   session.authenticate(),    // Verifies authentication
+   *   session.requireUser(),      // Loads user data into req.user
+   *   (req, res) => {
+   *     res.json({ user: req.user }); // User data available here
+   *   }
+   * );
+   * ```
+   */
+  requireUser(): RequestHandler;
 
   /**
    * 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: '')
+   * - SESSION mode: Verifies user exists in session store and is authorized (checks req.session data)
+   * - TOKEN mode: Validates JWT token from Authorization header (lightweight validation)
+   * 
+   * Note: This method verifies authentication only and does NOT populate req.user.
+   * Use requireUser() after this middleware to load user data into req.user.
+   * 
+   * @param errorRedirectUrl Redirect URL on authentication failure (default: '')
    * @returns Returns express Request Handler
+   * @example
+   * ```javascript
+   * // Option 1: Just verify authentication (user data remains in req.session or token)
+   * app.get('/api/check', 
+   *   session.authenticate(), 
+   *   (req, res) => {
+   *     res.json({ authenticated: true });
+   *   }
+   * );
+   * 
+   * // Option 2: Verify authentication AND populate req.user (recommended for most use cases)
+   * app.get('/api/profile',
+   *   session.authenticate(),    // Verifies session/token validity
+   *   session.requireUser(),      // Loads user data into req.user
+   *   (req, res) => {
+   *     res.json({ user: req.user }); // User data now available
+   *   }
+   * );
+   * ```
    */
-  authenticate(isDebugging?: boolean, redirectUrl?: string): RequestHandler;
+  authenticate(errorRedirectUrl?: 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: '')
+   * @param errorRedirectUrl Redirect URL (default: '')
    * @returns Returns express Request Handler
    */
-  verifyToken(isDebugging?: boolean, redirectUrl?: string): RequestHandler;
+  verifyToken(errorRedirectUrl?: string): RequestHandler;
 
   /**
    * Resource protection by session (explicit session verification)
-   * @param isDebugging Debugging flag (default: false)
-   * @param redirectUrl Redirect URL (default: '')
+   * @param errorRedirectUrl Redirect URL (default: '')
    * @returns Returns express Request Handler
    */
-  verifySession(isDebugging?: boolean, redirectUrl?: string): RequestHandler;
+  verifySession(errorRedirectUrl?: string): RequestHandler;
 
   /**
    * SSO callback for successful login

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@igxjs/node-components",
-  "version": "1.0.14",
+  "version": "1.0.15",
   "description": "Node components for igxjs",
   "main": "index.js",
   "type": "module",