npm - @igxjs/node-components - Versions diffs - 1.0.14 → 1.0.16 - Mend

@igxjs/node-components 1.0.14 → 1.0.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md +18 -7
package/components/assets/template.html +7 -2
package/components/session.js +301 -240
package/index.d.ts +90 -23
package/package.json +3 -17

package/README.md CHANGED Viewed

@@ -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/assets/template.html CHANGED Viewed

@@ -2,7 +2,7 @@
 <html lang="en">
   <head>
     <title>Sign in IBM Garage</title>
-    <meta name="viewport" content="width=device-width,initial-scale=1,shrink-to-fit=no,viewport-fit=cover,minimum-scale=1,maximum-scale=1,user-scalable=no">
+    <meta name="viewport" content="width=device-width,initial-scale=1,shrink-to-fit=no,viewport-fit=cover,minimum-scale=1,maximum-scale=2">
     <meta name="robots" content="noindex, nofollow" />
     <style>
       :root {
@@ -94,9 +94,14 @@
         localStorage.setItem('{{SESSION_EXPIRY_KEY}}', '{{SESSION_EXPIRY_VALUE}}');
       }
+      /**
+       * Note: You can also request full user informlation by using ajax request or loading server side page.
+       */
       // Fall back to simple navigation
       location.href = '{{SSO_SUCCESS_URL}}';
-    } catch (e) {
+    }
+    catch (e) {
       console.error('Redirect failed:', e);
       success = false;
     }

package/components/session.js CHANGED Viewed

@@ -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
@@ -270,7 +272,7 @@ export class SessionManager {
    * @private
    */
   #getTokenRedisKey(email, tid) {
-    return `${this.#config.SESSION_KEY}:t:${email}:${tid}`;
+    return `${this.#config.SESSION_KEY}:${email}:${tid}`;
   }
   /**
@@ -280,7 +282,7 @@ export class SessionManager {
    * @private
    */
   #getTokenRedisPattern(email) {
-    return `${this.#config.SESSION_KEY}:t:${email}:*`;
+    return `${this.#config.SESSION_KEY}:${email}:*`;
   }
   /**
@@ -291,75 +293,103 @@ 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.getSessionMode() === SessionMode.SESSION) {
+      app.use(this.#sessionHandler(isOK));
+    }
+    // Cache HTML template for TOKEN mode
+    if (this.getSessionMode() === 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 lightweight JWT token
+   * @param {string} email User email
+   * @param {string} tokenId Token ID
+   * @param {number} expirationTime Expiration time in seconds
+   * @returns {Promise<string>} Returns the generated JWT token
+   * @private
+   */
+  async #getLightweightToken(email, tokenId, expirationTime) {
+    return await this.#jwtManager.encrypt({ email, tid: tokenId }, this.#config.SSO_CLIENT_SECRET, { expirationTime });
+  }
   /**
    * Generate and store JWT token in Redis
    * - JWT payload contains only { email, tid } for minimal size
    * - Full user data is stored in Redis as single source of truth
-   * @param {object} user User object with email and attributes
+   * @param {string} tid Token ID
+   * @param {Record<string, any> & { email: string, tid: string }} user User object with email and attributes
    * @returns {Promise<string>} Returns the generated JWT token
    * @throws {Error} If JWT encryption fails
    * @throws {Error} If Redis storage fails
    * @private
    * @example
-   * const token = await this.#generateAndStoreToken({
+   * const token = await this.#generateAndStoreToken('tid', {
    *   email: 'user@example.com',
    *   attributes: { /* user data * / }
    * });
    */
-  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 }
-    );
+  async #generateAndStoreToken(tid, user) {
+    // Create JWT token with only email, tid and idp (minimal payload)
+    const token = await this.#getLightweightToken(user.email, tid, 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} [includeUserData=true] Whether to include full user data in response
+   *   - true: Returns { tid, user } with full user data (default)
+   *   - false: Returns JWT payload only (lightweight validation)
+   * @returns {Promise<{ tid: string, user: { email: string, attributes: { expires_at: number, sub: string } } } & object>}
+   *   - When includeUserData=true: { tid: string, user: object }
+   *   - When includeUserData=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 includeUserData=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, includeUserData = true) {
+    if (!authHeader?.startsWith('Bearer ')) {
+      throw new CustomError(httpCodes.UNAUTHORIZED, 'Missing or invalid authorization header');
+    }
+    const token = authHeader.substring(7); // Remove 'Bearer ' prefix
+    /** @type {{ payload: { email: string, tid: string } & import('jose').JWTPayload }} */
+    const { payload } = await this.#jwtManager.decrypt(token, this.#config.SSO_CLIENT_SECRET);
-      // Extract email and token ID
+    if (includeUserData) {
+      /** @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 +402,59 @@ export class SessionManager {
       if (!userData) {
         throw new CustomError(httpCodes.UNAUTHORIZED, 'Token not found or expired');
       }
+      return { tid, user: { ...JSON.parse(userData) } };
+    }
+    return { tid: payload.tid, user: { email: payload.email, attributes: { sub: payload.sub, expires_at: payload.exp ? payload.exp * 1000 : 0 } } };
+  }
-      // 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
+   * @param {boolean} [includeUserData=false] Whether to include full user data in response
+   * @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, includeUserData = false) {
+    if (this.getSessionMode() === SessionMode.TOKEN) {
+      const { user } = await this.#getUserFromToken(req.headers.authorization, includeUserData);
+      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 +472,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));
   }
@@ -431,43 +495,31 @@ export class SessionManager {
    * @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 {(user: object) => object} initUser Function to initialize/transform user object
-   * @param {string} idpUrl Identity provider refresh endpoint URL
+   * @param {(user: object) => object & { email: string }} initUser Function to initialize/transform user object
+   * @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: {...} }
    */
-  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;
+      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, {
-        user: {
-          email,
-          attributes: {
-            idp: attributes?.idp,
-            refresh_token: attributes?.refresh_token
-          }
+      const response = await this.#idpRequest.post(idpRefreshUrl, {
+        idp: user?.attributes?.idp,
+        refresh_token: user?.attributes?.refresh_token
+      }, {
+        headers: {
+          Authorization: req.headers.authorization
         }
       });
@@ -484,24 +536,15 @@ 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);
-      // Remove old token from Redis
-      const oldRedisKey = this.#getTokenRedisKey(email, oldTokenId);
-      await this.#redisManager.getClient().del(oldRedisKey);
+      const newToken = await this.#generateAndStoreToken(tid, newUser);
       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 });
     } catch (error) {
       return next(httpHelper.handleAxiosError(error));
     }
@@ -513,29 +556,36 @@ 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: {} };
+      // Check refresh lock
       if (this.hasLock(email)) {
-        throw new CustomError(httpCodes.CONFLICT, 'User refresh is locked');
+        throw new CustomError(httpCodes.CONFLICT, 'Session refresh is locked');
       }
       this.lock(email);
-      const response = await this.#idpRequest.post(idpUrl, {
-        user: {
-          email,
-          attributes: {
-            idp: attributes?.idp,
-            refresh_token: attributes?.refresh_token
-          }
+      /** @type {string} */
+      const token = await this.#getLightweightToken(email, req.sessionID, req.user.attributes.expires_at);
+      // Call SSO refresh endpoint
+      const response = await this.#idpRequest.post(idpRefreshUrl, {
+        idp: attributes?.idp,
+        refresh_token: attributes?.refresh_token,
+      }, {
+        headers: {
+          Authorization: `Bearer ${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);
+        const { payload } = await this.#jwtManager.decrypt(jwt, this.#config.SSO_CLIENT_SECRET);
+        const result = await this.#saveSession(req, payload, initUser);
+        return res.json(result);
       }
       throw new CustomError(response.status, response.statusText);
     } catch (error) {
@@ -604,16 +654,9 @@ 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);
-      const { email, tid } = payload;
+      // Extract Token ID and email from current token
+      const { tid, user } = await this.#getUserFromToken(req.headers.authorization, false);
+      const { email } = user;
       if (!email || !tid) {
         throw new CustomError(httpCodes.BAD_REQUEST, 'Invalid token payload');
@@ -670,27 +713,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,80 +746,96 @@ 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, true);
+        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;
+      const mode = this.getSessionMode() || 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);
     };
   }
   /**
    * Save session
    * @param {import('@types/express').Request} request Request object
-   * @param {string} jwt JWT
+   * @param {import('jose').JWTPayload} payload JWT
    * @param {(user: object) => object} initUser Redirect URL
    * @returns {Promise<{ user: import('../models/types/user').UserModel, redirect_url: string }>} Promise
    */
-  #saveSession = async (request, jwt, initUser) => {
-    /** @type {{ payload: { user: import('../models/types/user').UserModel, redirect_url: string } }} */
-    const { payload } = await this.#jwtManager.decrypt(jwt, this.#config.SSO_CLIENT_SECRET);
+  #saveSession = async (request, payload, initUser) => {
     if (payload?.user) {
       this.#logger.debug('### CALLBACK USER ###');
       request.session[this.#getSessionKey()] = initUser(payload.user);
@@ -813,62 +851,77 @@ export class SessionManager {
       });
     }
     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);
-  /**
-   * 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'));
-      }
+          if (!payload?.user) {
+            throw new CustomError(httpCodes.BAD_REQUEST, 'Invalid JWT payload');
+          }
+          /** @type {string} */
+          const callbackRedirectUrl = payload.redirect_url || this.#config.SSO_SUCCESS_URL;
+          // Token mode: Generate token and return HTML page
+          if (this.getSessionMode() === SessionMode.TOKEN) {
+            /** @type {import('../index.js').SessionUser} */
+            const user = initUser(payload.user);
+            // Generate unique token ID for this device/session
+            const tid = crypto.randomUUID();
+            const token = await this.#generateAndStoreToken(tid, user);
+            this.#logger.debug('### CALLBACK TOKEN GENERATED ###');
+            const html = this.#renderTokenStorageHtml(token, user.attributes.expires_at, callbackRedirectUrl);
+            return res.send(html);
+          }
-      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');
+          // Session mode: Save to session and redirect
+          await this.#saveSession(req, payload, initUser);
+          return res.redirect(callbackRedirectUrl);
         }
-        /** @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);
+        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)));
         }
-        // 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)));
-      }
-    };
-  }
+      };
+    }
   /**
    * Get Identity Providers
@@ -896,14 +949,15 @@ 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;
+      const mode = this.getSessionMode() || SessionMode.SESSION;
       if (mode === SessionMode.TOKEN) {
-        return this.#refreshToken(req, res, next, initUser, idpUrl);
-      } else {
-        return this.#refreshSession(req, res, next, initUser, idpUrl);
+        return this.#refreshToken(req, res, next, initUser, idpRefreshUrl);
+      }
+      else {
+        return this.#refreshSession(req, res, next, initUser, idpRefreshUrl);
       }
     };
   }
@@ -917,8 +971,8 @@ export class SessionManager {
       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;
+      const mode = this.getSessionMode() || SessionMode.SESSION;
       if (mode === SessionMode.TOKEN) {
         return this.#logoutToken(req, res, isRedirect, logoutAll);
       }
@@ -944,4 +998,11 @@ export class SessionManager {
     };
   }
+  /**
+   * Get session mode
+   * @returns {string} Session mode
+   */
+  getSessionMode() {
+    return this.#config.SESSION_MODE;
+  }
 }

package/index.d.ts CHANGED Viewed

@@ -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,99 @@ 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
+   * @param includeUserData Include user data in the response (default: false)
+   * @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, true);
+   *     req.customUser = user;
+   *     next();
+   *   } catch (error) {
+   *     next(error);
+   *   }
+   * });
+   * ```
+   */
+  getUser(req: Request, includeUserData: boolean?): 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
@@ -379,6 +440,12 @@ export class SessionManager {
    * @returns Returns express Request Handler
    */
   logout(): RequestHandler;
+  /**
+   * Get the current session mode
+   * @returns Returns 'session' or 'token' based on configuration
+   */
+  getSessionMode(): string;
 }
 // Custom Error class

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@igxjs/node-components",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "Node components for igxjs",
   "main": "index.js",
   "type": "module",
@@ -12,21 +12,7 @@
     "url": "git+https://github.com/igxjs/node-components.git"
   },
   "keywords": [
-    "igxjs",
-    "express",
-    "session-management",
-    "jwt",
-    "jwe",
-    "redis",
-    "authentication",
-    "sso",
-    "oauth",
-    "middleware",
-    "node-components",
-    "session",
-    "token-auth",
-    "bearer-token",
-    "express-middleware"
+    "igxjs"
   ],
   "author": "Michael",
   "license": "Apache-2.0",
@@ -43,7 +29,7 @@
     "axios": "^1.13.6",
     "connect-redis": "^9.0.0",
     "express-session": "^1.19.0",
-    "jose": "^6.2.1",
+    "jose": "^6.2.2",
     "memorystore": "^1.6.7"
   },
   "devDependencies": {