[Penify]: Documentation for commit - b5926d5

Author: penify-dev[bot]

backend/middleware/auth.js

@@ -16,7 +16,7 @@ const JWT_EXPIRY = process.env.JWT_EXPIRY || '15m';
 const JWT_REFRESH_EXPIRY = process.env.JWT_REFRESH_EXPIRY || '7d';
 
 /**
- * Generate JWT access token
+ * Generates a JWT access token with the given payload.
  */
 export function generateAccessToken(payload) {
   return jwt.sign(
@@ -37,7 +37,7 @@ export function generateAccessToken(payload) {
 }
 
 /**
- * Generate JWT refresh token
+ * Generates a JWT refresh token.
  */
 export function generateRefreshToken(payload) {
   return jwt.sign(
@@ -58,7 +58,14 @@ export function generateRefreshToken(payload) {
 }
 
 /**
- * Verify JWT token
+ * Verify JWT token.
+ *
+ * This function checks the validity of a JWT token using a specified secret based on whether it is a refresh token or not.
+ * It decodes the token and returns an object indicating its validity, the decoded payload, and whether it has expired.
+ * If an error occurs during verification, it handles different error types to provide specific feedback on the token's status.
+ *
+ * @param {string} token - The JWT token to verify.
+ * @param {boolean} [isRefresh=false] - Indicates if the token is a refresh token.
  */
 export function verifyToken(token, isRefresh = false) {
   try {
@@ -103,7 +110,17 @@ export function verifyToken(token, isRefresh = false) {
 }
 
 /**
- * Authentication middleware
+ * Authentication middleware for validating user tokens.
+ *
+ * This middleware checks for a valid Bearer token in the authorization header, verifies its validity and type,
+ * and retrieves user information. It handles various authentication errors, including blacklisted tokens,
+ * expired tokens, and inactive accounts, responding with appropriate status codes and messages.
+ * If successful, it attaches user and token information to the request object for further processing.
+ *
+ * @param req - The request object containing the HTTP request data.
+ * @param res - The response object used to send HTTP responses.
+ * @param next - The next middleware function in the stack.
+ * @throws Error If an internal error occurs during authentication.
  */
 export async function authMiddleware(req, res, next) {
   try {
@@ -212,7 +229,9 @@ export async function authMiddleware(req, res, next) {
 }
 
 /**
- * Optional authentication middleware (doesn't fail if no token)
+ * Optional authentication middleware that allows requests to proceed without a token.
+ *
+ * This middleware checks for the presence of an authorization header. If the header is missing or does not start with 'Bearer ', it sets req.user and req.token to null and calls next() to continue the request. If the header is present, it attempts to call the authMiddleware function. If authMiddleware throws an error, it catches the error, sets req.user and req.token to null, and continues the request.
  */
 export async function optionalAuthMiddleware(req, res, next) {
   const authHeader = req.headers.authorization;
@@ -234,7 +253,14 @@ export async function optionalAuthMiddleware(req, res, next) {
 }
 
 /**
- * Role-based authorization middleware
+ * Role-based authorization middleware.
+ *
+ * This middleware checks if the user is authenticated and has one of the required roles.
+ * If the user is not authenticated, a 401 status is returned with an appropriate message.
+ * If the user's role is not included in the specified roles, a 403 status is returned,
+ * indicating insufficient permissions. If both checks pass, the middleware calls the next function.
+ *
+ * @param {...string} roles - The roles that are required to access the resource.
  */
 export function requireRole(...roles) {
   return (req, res, next) => {
@@ -259,7 +285,16 @@ export function requireRole(...roles) {
 }
 
 /**
- * Refresh token middleware
+ * Middleware to refresh the token for authenticated users.
+ *
+ * This function checks for the presence of a refresh token in the request body, verifies its validity, and ensures it is not blacklisted.
+ * It also checks the token type and retrieves the associated user information, attaching it to the request object for further processing.
+ * If any validation fails, appropriate error responses are sent back to the client.
+ *
+ * @param req - The request object containing the refresh token in the body.
+ * @param res - The response object used to send responses back to the client.
+ * @param next - The next middleware function in the stack.
+ * @throws Error If an internal server error occurs during the token refresh process.
  */
 export async function refreshTokenMiddleware(req, res, next) {
   try {
@@ -334,7 +369,16 @@ export async function refreshTokenMiddleware(req, res, next) {
 }
 
 /**
- * Logout middleware - blacklist tokens
+ * Logout middleware - blacklist tokens.
+ *
+ * This middleware handles the logout process by blacklisting the access token and, if provided, the refresh token.
+ * It checks for the presence of the access token and blacklists it if available. If a refresh token is included in
+ * the request body, it verifies the token and blacklists it if valid. The function logs the logout action and
+ * proceeds to the next middleware, even if an error occurs during the blacklisting process.
+ *
+ * @param {Object} req - The request object containing user and token information.
+ * @param {Object} res - The response object.
+ * @param {Function} next - The next middleware function to call.
  */
 export async function logoutMiddleware(req, res, next) {
   try {
@@ -367,7 +411,7 @@ export async function logoutMiddleware(req, res, next) {
 }
 
 /**
- * Generate token pair (access + refresh)
+ * Generates a token pair (access + refresh) from the given payload.
  */
 export function generateTokenPair(payload) {
   const accessToken = generateAccessToken(payload);
@@ -383,7 +427,14 @@ export function generateTokenPair(payload) {
 }
 
 /**
- * Extract token from request
+ * Extract token from request.
+ *
+ * This function retrieves a token from the provided request object. It first checks the
+ * authorization header for a Bearer token and returns it if present. If the header is
+ * not available or does not contain a Bearer token, it falls back to checking the query
+ * parameters for a token, specifically for WebSocket scenarios.
+ *
+ * @param {Object} req - The request object containing headers and query parameters.
  */
 export function extractTokenFromRequest(req) {
   const authHeader = req.headers.authorization;