feat: add API to start and stop impersonation session (#2450)

* added functionality for start and stop of impersonation

* added middleware and fixed code quality

* fixed bot comments

* removed unused types and fixed authentication middleware jsdoc

* fixed bot comments

* fixed controller import

* fixed build errors

* fixed failing test

* used constants for 403 error

* fixed jsdoc for middleware

Author: Suvidh-kaushik

constants/requests.ts

@@ -71,6 +71,11 @@ export const UNAUTHORIZED_TO_UPDATE_REQUEST = "Unauthorized to update request";
 
 export const FEATURE_NOT_IMPLEMENTED = "Feature not implemented";
 
-export const IMPERSONATION_NOT_COMPLETED = "Please complete impersonation before creating a new request";
-export const IMPERSONATION_ALREADY_ATTEMPTED = "No active request is available for impersonation";
-export const IMPERSONATION_REQUEST_NOT_APPROVED = "Awaiting approval for impersonation request";
+export const INVALID_ACTION_PARAM = "Invalid 'action' parameter: must be either 'START' or 'STOP'";
+
+export const OPERATION_NOT_ALLOWED = "You are not allowed for this operation at the moment";
+
+export const IMPERSONATION_LOG_TYPE = {
+  SESSION_STARTED:"SESSION_STARTED",
+  SESSION_STOPPED:"SESSION_STOPPED"
+}

controllers/impersonationRequests.ts

@@ -4,9 +4,10 @@ import {
   REQUEST_FETCHED_SUCCESSFULLY,
   REQUEST_DOES_NOT_EXIST,
   ERROR_WHILE_UPDATING_REQUEST,
-  REQUEST_CREATED_SUCCESSFULLY
+  REQUEST_CREATED_SUCCESSFULLY,
+  OPERATION_NOT_ALLOWED
 } from "../constants/requests";
-import { createImpersonationRequestService, updateImpersonationRequestService } from "../services/impersonationRequests";
+import { createImpersonationRequestService, updateImpersonationRequestService, generateImpersonationTokenService, startImpersonationService, stopImpersonationService } from "../services/impersonationRequests";
 import { getImpersonationRequestById, getImpersonationRequests } from "../models/impersonationRequests";
 import {
   CreateImpersonationRequest,
@@ -16,6 +17,7 @@ import {
   ImpersonationRequestResponse,
   GetImpersonationControllerRequest,
   GetImpersonationRequestByIdRequest,
+  ImpersonationSessionRequest
 } from "../types/impersonationRequest";
 import { getPaginatedLink } from "../utils/helper";
 import { NextFunction } from "express";
@@ -180,3 +182,50 @@ export const updateImpersonationRequestStatusController = async (
     next(error);
   }
 };
+
+
+
+/**
+ * Controller to handle impersonation session actions (START or STOP).
+ *
+ * @param {ImpersonationSessionRequest} req - Express request object containing user data, query params, and impersonation flag.
+ * @param {ImpersonationRequestResponse} res - Express response object used to send the response.
+ * @param {NextFunction} next - Express next middleware function for error handling.
+ * @returns {Promise<ImpersonationRequestResponse>} Sends a JSON response with updated request data and sets authentication cookies based on action.
+ *
+ * @throws {Forbidden} If the action is invalid or STOP is requested without an active impersonation session.
+ */
+export const impersonationController = async (
+  req: ImpersonationSessionRequest,
+  res: ImpersonationRequestResponse,
+  next: NextFunction
+): Promise<ImpersonationRequestResponse | void> => {
+  const { action } = req.query;
+  const requestId = req.params.id;
+  const userId = req.userData?.id;
+  let authCookie;
+  let response;
+  try {
+
+    if (action === "START") {
+      authCookie = await generateImpersonationTokenService(requestId, action);
+      response = await startImpersonationService({ requestId, userId });
+    }
+
+    if (action === "STOP") {
+      authCookie = await generateImpersonationTokenService(requestId, action);
+      response = await stopImpersonationService({ requestId, userId });
+    }
+
+    res.clearCookie(authCookie.name);
+    res.cookie(authCookie.name, authCookie.value, authCookie.options);
+
+    return res.status(200).json({
+      message: response.returnMessage,
+      data: response.updatedRequest
+    });
+  } catch (error) {
+    logger.error(`Failed to process impersonation ${action} for requestId=${requestId}, userId=${userId}`, error);
+    return next(error);
+  }
+};

middlewares/addAuthorizationForImpersonation.ts

@@ -0,0 +1,39 @@
+import { NextFunction } from "express";
+import authorizeRoles from "./authorizeRoles";
+const { SUPERUSER } = require("../constants/roles");
+import { ImpersonationRequestResponse, ImpersonationSessionRequest } from "../types/impersonationRequest";
+import { INVALID_ACTION_PARAM, OPERATION_NOT_ALLOWED } from "../constants/requests";
+
+/**
+ * Middleware to authorize impersonation actions based on the `action` query parameter.
+ *
+ * - If `action=START`: Only users with the SUPERUSER role are authorized.
+ * - If `action=STOP`: Only allowed if the user is currently impersonating someone (`req.isImpersonating === true`).
+ * - If `action` is missing or has an invalid value: Responds with 400 Bad Request.
+ *
+ * @param {ImpersonationSessionRequest} req - Express request object, extended to include impersonation context.
+ * @param {ImpersonationRequestResponse} res - Express response object with Boom error handling.
+ * @param {NextFunction} next - Express callback to pass control to the next middleware.
+ *
+ * @returns {void}
+ */
+export const addAuthorizationForImpersonation = async (
+  req: ImpersonationSessionRequest,
+  res: ImpersonationRequestResponse,
+  next: NextFunction
+) => {
+  const { action } = req.query;
+
+  if (action === "START") {
+    return authorizeRoles([SUPERUSER])(req, res, next);
+  }
+
+  if (action === "STOP") {
+    if (!req.isImpersonating) {
+      return res.boom.forbidden(OPERATION_NOT_ALLOWED);
+    }
+    return next();
+  }
+
+  return res.boom.badRequest(INVALID_ACTION_PARAM);
+};

middlewares/authenticate.js

@@ -1,62 +1,82 @@
 const authService = require("../services/authService");
 const dataAccess = require("../services/dataAccessLayer");
+const logger = require("../utils/logger");
 
 /**
- * Middleware to check if the user has been restricted. If user is restricted,
- * then only allow read requests and do not allow to any edit/create requests.
+ * Middleware to check if the user is restricted or in an impersonation session.
+ *
+ * - If the user is impersonating, only GET requests and the STOP impersonation route are allowed.
+ * - If the user is restricted (based on roles), only GET requests are permitted.
  *
  * Note: This requires that user is authenticated hence must be called after
  * the user authentication middleware. We are calling it from within the
  * `authenticate` middleware itself to avoid explicitly adding this middleware
  * while defining routes.
  *
- * @param {Object} req - Express request object
- * @param {Object} res - Express response object
- * @param {Function} next - Express middleware function
- * @returns {Object} - Returns unauthorized object if user has been restricted.
+ * @async
+ * @function checkRestricted
+ * @param {import('express').Request} req - Express request object
+ * @param {import('express').Response} res - Express response object
+ * @param {Function} next - Express next middleware function
+ * @returns {void}
  */
 const checkRestricted = async (req, res, next) => {
   const { roles } = req.userData;
+
+  if (req.isImpersonating) {
+    const isStopImpersonationRoute =
+      req.method === "PATCH" &&
+      req.baseUrl === "/impersonation" &&
+      /^\/[a-zA-Z0-9_-]+$/.test(req.path) &&
+      req.query.action === "STOP";
+
+    if (req.method !== "GET" && !isStopImpersonationRoute) {
+      return res.boom.forbidden("Only viewing is permitted during impersonation");
+    }
+  }
+
   if (roles && roles.restricted && req.method !== "GET") {
     return res.boom.forbidden("You are restricted from performing this action");
   }
+
   return next();
 };
 
 /**
- * Middleware to validate the authenticated routes
- * 1] Verifies the token and adds user info to `req.userData` for further use
- * 2] In case of JWT expiry, adds a new JWT to the response if `currTime - tokenInitialisationTime <= refreshTtl`
+ * Authentication middleware that:
+ * 1. Verifies JWT token from cookies (or headers in non-production).
+ * 2. Handles impersonation if applicable.
+ * 3. Refreshes token if it's expired but still within the refresh TTL window.
+ * 4. Attaches user data to `req.userData` for downstream use.
  *
- * The currently implemented mechanism satisfies the current use case.
- * Authentication with JWT and a refreshToken to be added once we have user permissions and authorizations to be handled
- *
- * @todo: Add tests to assert on refreshed JWT generation by modifying the TTL values for the specific test. Currently not possible in the absence of a test-suite.
- *
- *
- * @param req {Object} - Express request object
- * @param res {Object} - Express response object
- * @param next {Function} - Express middleware function
- * @return {Object} - Returns unauthenticated object if token is invalid
+ * @async
+ * @function
+ * @param {import('express').Request} req - Express request object
+ * @param {import('express').Response} res - Express response object
+ * @param {Function} next - Express next middleware function
+ * @returns {Promise<void>} - Calls `next()` on successful authentication or returns an error response.
  */
 module.exports = async (req, res, next) => {
   try {
     let token = req.cookies[config.get("userToken.cookieName")];
 
     /**
-     * Enable Bearer Token authentication for NON-PRODUCTION environments
-     * This is enabled as Swagger UI does not support cookie authe
+     * Enable Bearer Token authentication for NON-PRODUCTION environments.
+     * Useful for Swagger or manual testing where cookies are not easily managed.
      */
     if (process.env.NODE_ENV !== "production" && !token) {
-      token = req.headers.authorization.split(" ")[1];
+      token = req.headers.authorization?.split(" ")[1];
     }
 
-    const { userId } = authService.verifyAuthToken(token);
+    const { userId, impersonatedUserId } = authService.verifyAuthToken(token);
+    // `req.isImpersonating` keeps track of the impersonation session
+    req.isImpersonating = Boolean(impersonatedUserId);
 
-    // add user data to `req.userData` for further use
-    const userData = await dataAccess.retrieveUsers({ id: userId });
-    req.userData = userData.user;
+    const userData = impersonatedUserId
+      ? await dataAccess.retrieveUsers({ id: impersonatedUserId })
+      : await dataAccess.retrieveUsers({ id: userId });
 
+    req.userData = userData.user;
     return checkRestricted(req, res, next);
   } catch (err) {
     logger.error(err);
@@ -78,14 +98,13 @@ module.exports = async (req, res, next) => {
           sameSite: "lax",
         });
 
-        // add user data to `req.userData` for further use
-        req.userData = await dataAccess.retrieveUsers({ id: userId });
+        const userData = await dataAccess.retrieveUsers({ id: userId });
+        req.userData = userData.user;
+
         return checkRestricted(req, res, next);
-      } else {
-        return res.boom.unauthorized("Unauthenticated User");
       }
-    } else {
       return res.boom.unauthorized("Unauthenticated User");
     }
+    return res.boom.unauthorized("Unauthenticated User");
   }
 };

middlewares/validators/impersonationRequests.ts

@@ -1,6 +1,6 @@
 import joi from "joi";
 import { NextFunction } from "express";
-import { CreateImpersonationRequest,GetImpersonationControllerRequest,GetImpersonationRequestByIdRequest,ImpersonationRequestResponse, UpdateImpersonationRequest } from "../../types/impersonationRequest";
+import { CreateImpersonationRequest,GetImpersonationControllerRequest,GetImpersonationRequestByIdRequest,ImpersonationRequestResponse, UpdateImpersonationRequest, ImpersonationSessionRequest } from "../../types/impersonationRequest";
 import { REQUEST_STATE } from "../../constants/requests";
 const logger = require("../../utils/logger");
 
@@ -130,3 +130,42 @@ export const updateImpersonationRequestValidator=async (
      return res.boom.badRequest(errorMessages);
     }
 }
+
+
+
+/**
+ * Middleware to validate query parameters for impersonation session actions.
+ *
+ * @param {ImpersonationSessionRequest} req - Express request object containing query params
+ * @param {ImpersonationRequestResponse} res - Express response object used to send validation errors
+ * @param {NextFunction} next - Express next middleware function
+ * @returns {Promise<void>} - Resolves if validation succeeds, otherwise sends an error response
+ */
+export const impersonationSessionValidator = async (
+  req: ImpersonationSessionRequest,
+  res: ImpersonationRequestResponse,
+  next: NextFunction
+): Promise<void> => {
+  const querySchema = joi
+    .object()
+    .strict()
+    .keys({
+      action: joi
+        .string()
+        .valid("START", "STOP")
+        .required()
+        .messages({
+          "any.only": "action must be START or STOP",
+        }),
+      dev: joi.string().optional(),
+    });
+
+  try {
+    await querySchema.validateAsync(req.query, { abortEarly: false });
+    next();
+  } catch (error) {
+    const errorMessages = error.details.map((detail: { message: string }) => detail.message);
+    logger.error(`Error while validating request payload: ${errorMessages}`);
+    return res.boom.badRequest(errorMessages);
+  }
+};

models/impersonationRequests.ts

@@ -1,12 +1,15 @@
 import firestore from "../utils/firestore";
 import {
   ERROR_WHILE_CREATING_REQUEST,
+  REQUEST_ALREADY_PENDING,
+  REQUEST_STATE,
+  ERROR_WHILE_FETCHING_REQUEST,
   ERROR_WHILE_UPDATING_REQUEST,
-  ERROR_WHILE_FETCHING_REQUEST
+  OPERATION_NOT_ALLOWED
 } from "../constants/requests";
 import { Timestamp } from "firebase-admin/firestore";
 import { Query, CollectionReference } from '@google-cloud/firestore';
-import { CreateImpersonationRequestModelDto, ImpersonationRequest, UpdateImpersonationRequestModelDto, PaginatedImpersonationRequests,ImpersonationRequestQuery} from "../types/impersonationRequest";
+import { CreateImpersonationRequestModelDto, ImpersonationRequest, UpdateImpersonationRequestModelDto, PaginatedImpersonationRequests,ImpersonationRequestQuery } from "../types/impersonationRequest";
 import { Forbidden } from "http-errors";
 const logger = require("../utils/logger");
 const impersonationRequestModel = firestore.collection("impersonationRequests");
@@ -36,7 +39,7 @@ export const createImpersonationRequest = async (
     const snapshot = await reqQuery.get();
 
     if (!snapshot.empty) {
-      throw new Forbidden("You are not allowed for this Operation at the moment");
+      throw new Forbidden(OPERATION_NOT_ALLOWED);
     }
 
     const requestBody = {

routes/impersonation.ts

@@ -1,7 +1,8 @@
 import express from "express";
-import { createImpersonationRequestValidator, getImpersonationRequestByIdValidator, getImpersonationRequestsValidator, updateImpersonationRequestValidator } from "../middlewares/validators/impersonationRequests";
+import { createImpersonationRequestValidator, getImpersonationRequestByIdValidator, getImpersonationRequestsValidator, updateImpersonationRequestValidator, impersonationSessionValidator } from "../middlewares/validators/impersonationRequests";
 import authenticate from "../middlewares/authenticate";
-import { createImpersonationRequestController, getImpersonationRequestByIdController, getImpersonationRequestsController, updateImpersonationRequestStatusController } from "../controllers/impersonationRequests";
+import { createImpersonationRequestController, getImpersonationRequestByIdController, getImpersonationRequestsController, impersonationController, updateImpersonationRequestStatusController } from "../controllers/impersonationRequests";
+import { addAuthorizationForImpersonation } from "../middlewares/addAuthorizationForImpersonation";
 const router = express.Router();
 const authorizeRoles = require("../middlewares/authorizeRoles");
 const { SUPERUSER } = require("../constants/roles");
@@ -35,4 +36,12 @@ router.patch(
   updateImpersonationRequestStatusController
 );
 
+router.patch(
+    "/:id",
+    authenticate,
+    impersonationSessionValidator,
+    addAuthorizationForImpersonation,
+    impersonationController
+);
+
 module.exports = router;

services/authService.js

@@ -12,6 +12,21 @@ const generateAuthToken = (payload) => {
   });
 };
 
+/**
+ * Generates a short-lived JWT token for impersonation sessions.
+ *
+ * @param {Object} payload - The payload to include in the JWT (e.g., userId, impersonatedUserId).
+ * @param {string} payload.userId - The ID of the super-user initiating the impersonation.
+ * @param {string} payload.impersonatedUserId - The ID of the user being impersonated.
+ * @returns {string} - The generated JWT for impersonation, signed using RS256 algorithm.
+ */
+const generateImpersonationAuthToken = (payload) => {
+  return jwt.sign(payload, config.get("userToken.privateKey"), {
+    algorithm: "RS256",
+    expiresIn: config.get("userToken.impersonationTtl"),
+  });
+};
+
 /**
  * Verifies if the JWT is valid. Throws error in case of signature error or expiry
  *
@@ -36,4 +51,5 @@ module.exports = {
   generateAuthToken,
   verifyAuthToken,
   decodeAuthToken,
+  generateImpersonationAuthToken,
 };