jwt-middleware-auth 1.1.0 → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,149 @@
+# Changelog - JWT Middleware Authentication
+
+## 2025-12-08
+
+### Added
+
+#### User & Admin Access Control
+- **`verifyUserOwnershipOrAdmin`** - Middleware for user-specific resource access control
+  - Validates that authenticated user can only access/modify their own data
+  - Grants automatic access to admin and SuperManager roles
+  - Extracts user ID from route params (`:id` or `:userId`)
+  - Returns 401 if user not authenticated
+  - Returns 403 if user attempts to access another user's data
+  - Example: `router.put('/user/:id', verifyToken(secret), verifyUserOwnershipOrAdmin, controller)`
+  - Use cases: User profile updates, user data retrieval, user deletion
+
+- **`verifyAdminOrSuperManager`** - Middleware for admin-only operations
+  - Restricts access to users with admin or SuperManager roles
+  - Returns 401 if user not authenticated
+  - Returns 403 if user lacks admin privileges
+  - Example: `router.get('/users', verifyToken(secret), verifyAdminOrSuperManager, controller)`
+  - Use cases: Admin dashboards, user management, sensitive data endpoints
+
+#### Seller & Multi-Role Verification
+- **`verifySellerOrAdmin(secret)`** - Middleware for seller/manager/admin/SuperManager role verification
+  - Validates that user has one of the elevated privilege roles
+  - Supports: admin, seller, manager, SuperManager
+  - Returns 403 if user lacks required privileges
+  - Example: `router.get('/store/:id/orders', verifySellerOrAdmin(secret), controller)`
+
+- **`verifySellerRole(secret)`** - Middleware for strict seller role verification
+  - Validates that the authenticated user has seller or paymentManager role
+  - Focused on role validation for creating resources (more specific than verifySeller)
+  - Returns 403 if user does not have required role
+  - Example: `router.post('/offers', verifySellerRole(secret), controller)`
+
+#### Advanced Ownership Verification
+- **`verifyTokenAndOwnership(secret, getResourceOwnerId)`** - Higher-order middleware factory for resource ownership verification
+  - Verifies JWT token AND checks that the authenticated user owns the resource
+  - Accepts async function to retrieve resource owner ID
+  - Handles resource not found errors with 404 status
+  - Compares owner ID with authenticated user ID (handles both ObjectId and string types)
+  - Returns 403 if user is not the resource owner
+  - Returns 404 if resource not found
+  - Returns 500 for ownership verification errors
+  - Example usage:
+    ```javascript
+    const checkOfferOwnership = async (req) => {
+      const offer = await Offer.findById(req.params.id);
+      if (!offer) throw new Error('Offer not found');
+      return offer.sellerId;
+    };
+    router.put('/offer/:id', verifyTokenAndOwnership(secret, checkOfferOwnership), controller)
+    ```
+
+- **`verifyTokenAndMultiOwnership(secret, getResourceOwnerIds)`** - Advanced multi-ownership verification
+  - Higher-order middleware factory for resources with multiple potential owners
+  - Automatically grants access to admin and SuperManager roles
+  - Accepts async function that returns array of owner IDs
+  - Checks if authenticated user matches any owner ID
+  - Useful for complex resources like orders (client OR seller can access)
+  - Returns 403 if user is not an owner or admin
+  - Returns 404 if resource not found
+  - Example usage:
+    ```javascript
+    const checkOrderOwnership = async (req) => {
+      const order = await Order.findById(req.params.id);
+      if (!order) throw new Error('Order not found');
+      const store = await Store.findById(order.storeId);
+      return [order.clientId, store.sellerId]; // Both can access
+    };
+    router.get('/order/:id', verifyTokenAndMultiOwnership(secret, checkOrderOwnership), controller)
+    ```
+
+#### Role-Based Access Control (RBAC)
+- **`authorizeRoles(...allowedRoles)`** - Middleware function for role-based access control
+  - Verifies authenticated users have one of the allowed roles
+  - Must be used after `verifyToken` middleware
+  - Supports multiple roles with flexible authorization logic
+  - Returns 401 if user is not authenticated
+  - Returns 403 if user lacks required permissions
+  - Example: `authorizeRoles('admin', 'manager')`
+
+#### Core Middleware (Previously Included)
+- **`verifyToken(secret)`** - Middleware to verify JWT tokens from request headers
+  - Expects token in 'token' header as 'Bearer <token>'
+  - Populates `req.user` with decoded token payload
+  
+- **`verifyTokenAndAuthorization(secret)`** - Middleware for user self-update authorization
+  - Allows access if user is updating their own account OR is an admin
+  
+- **`verifyAdmin(secret)`** - Middleware to verify admin privileges
+  - Checks `req.user.isAdmin` property
+  
+- **`verifyManager(secret)`** - Middleware to verify manager role or self-access
+  - Allows access if user is a manager OR accessing their own resource
+  
+- **`verifySeller(secret)`** - Middleware to verify seller/payment manager role
+  - Allows access if user is a seller, payment manager, OR accessing their own resource
+
+### Changed
+- Updated package description to reflect role-based authorization capabilities
+- Enhanced JSDoc documentation for all middleware functions with detailed examples
+- Added comprehensive inline comments explaining middleware behavior
+- Exported all new middleware functions in module exports
+- Package keywords updated to include: "authorization", "roles", "rbac"
+
+### Improved
+- Enhanced user data protection with ownership verification
+- Centralized admin role verification for consistent access control
+- Better separation of concerns between user-level and admin-level operations
+- Enhanced support for multi-tenant authorization patterns
+- Better handling of resources with multiple owners or access levels
+- Consistent admin/SuperManager privilege handling across all ownership middlewares
+- Enhanced flexibility for seller-related authorization with separate role-checking middleware
+- Better separation of concerns between role verification and ownership verification
+- Comprehensive error handling for resource ownership validation
+- Better error handling in `authorizeRoles` middleware
+- More descriptive error messages for authentication and authorization failures
+
+---
+
+## Summary
+
+**Total Middleware Functions:** 13
+
+**Categories:**
+- Core Authentication: 1 (verifyToken)
+- Admin & Role Verification: 4 (verifyAdmin, verifyAdminOrSuperManager, authorizeRoles, verifyManager)
+- Seller Verification: 3 (verifySeller, verifySellerRole, verifySellerOrAdmin)
+- Ownership & Authorization: 3 (verifyTokenAndAuthorization, verifyTokenAndOwnership, verifyTokenAndMultiOwnership)
+- User Access Control: 1 (verifyUserOwnershipOrAdmin)
+
+**Key Features:**
+- ✅ Complete JWT token verification
+- ✅ Flexible role-based access control (RBAC)
+- ✅ Resource ownership verification (single & multi-owner)
+- ✅ User self-access & admin privilege management
+- ✅ Seller/Manager role validation
+- ✅ Comprehensive error handling
+- ✅ TypeScript-ready with JSDoc documentation
+
+**Dependencies:**
+- jsonwebtoken: ^9.0.3
+
+**Migration Notes:**
+- All changes are additive - existing code continues to work
+- Custom authorization middleware can be replaced with centralized package functions
+- Simply import new middleware functions alongside existing ones for enhanced capabilities

package/index.js

@@ -1,24 +1,66 @@
 const jwt = require('jsonwebtoken');
 
+/**
+ * Middleware to verify JWT token from request headers
+ * Expects token in 'token' header as 'Bearer <token>'
+ * Populates req.user with decoded token payload
+ * @param {string} secret - JWT secret for token verification
+ * @returns {Function} Express middleware function
+ */
 const verifyToken = (secret) => {
-    return (req, res, next) => {
-      const authHeader = req.headers.token;
-  
-      if (authHeader) {
-        const token = authHeader.split(' ')[1];
-        jwt.verify(token, secret, (err, user) => {
-          if (err) {
-            return res.status(401).json({ message: 'Invalid Token' });
-          }
-          req.user = user;
-          next();
-        });
-      } else {
-        return res.status(401).json({ message: 'Token is not provided' });
+  return (req, res, next) => {
+    const authHeader = req.headers.token;
+
+    if (authHeader) {
+      const token = authHeader.split(' ')[1];
+      jwt.verify(token, secret, (err, user) => {
+        if (err) {
+          return res.status(401).json({ message: 'Invalid Token' });
+        }
+        req.user = user;
+        next();
+      });
+    } else {
+      return res.status(401).json({ message: 'Token is not provided' });
+    }
+  };
+};
+
+/**
+ * Middleware to check if the authenticated user has one of the allowed roles
+ * Must be used after verifyToken middleware as it expects req.user to be populated
+ * @param {...string} allowedRoles - Roles that are allowed to access the route
+ * @returns {Function} Express middleware function
+ * @example
+ * router.get('/admin-only', verifyToken(secret), authorizeRoles('admin'), controller)
+ * router.get('/multi-role', verifyToken(secret), authorizeRoles('admin', 'manager'), controller)
+ */
+const authorizeRoles = (...allowedRoles) => {
+  return (req, res, next) => {
+    try {
+      // Check if user is authenticated (should be set by verifyToken middleware)
+      if (!req.user) {
+        return res.status(401).json({ message: 'Authentication required' });
+      }
+
+      // Check if user has one of the allowed roles
+      if (!allowedRoles.includes(req.user.role)) {
+        return res.status(403).json({ message: 'Access denied. Insufficient permissions.' });
       }
-    };
+
+      next();
+    } catch (err) {
+      next(err);
+    }
   };
-//for updatin User information
+};
+
+/**
+ * Middleware for updating user information
+ * Allows access if user is updating their own account OR is an admin
+ * @param {string} secret - JWT secret for token verification
+ * @returns {Function} Express middleware function
+ */
 const verifyTokenAndAuthorization = (secret) => {
   return (req, res, next) => {
     verifyToken(secret)(req, res, () => {
@@ -30,39 +72,254 @@ const verifyTokenAndAuthorization = (secret) => {
   };
 };
 
-// for all access};
+/**
+ * Middleware to verify if user is an admin
+ * @param {string} secret - JWT secret for token verification
+ * @returns {Function} Express middleware function
+ */
 const verifyAdmin = (secret) => {
-	return (req, res, next) => {
-	  verifyToken(secret)(req, res, () => {
-		if (req.user.isAdmin || req.user.isAdmin == true) {
-		  return next();
-		}
-		return res.status(403).json({ message: 'You are not an admin' });
-	  });
-	};
+  return (req, res, next) => {
+    verifyToken(secret)(req, res, () => {
+      if (req.user.isAdmin || req.user.isAdmin == true) {
+        return next();
+      }
+      return res.status(403).json({ message: 'You are not an admin' });
+    });
   };
+};
 
-// for all access
+/**
+ * Middleware to verify if user is a manager or accessing their own resource
+ * @param {string} secret - JWT secret for token verification
+ * @returns {Function} Express middleware function
+ */
 const verifyManager = (secret) => {
-	return (req, res, next) => {
-	  verifyToken(secret)(req, res, () => {
-		if (req.user.id == req.params.id || req.user.role == 'manager') {
-		  return next();
-		}
-		return res.status(403).json({ message: 'You are not a manager' });
-	  });
-	};
+  return (req, res, next) => {
+    verifyToken(secret)(req, res, () => {
+      if (req.user.id == req.params.id || req.user.role == 'manager') {
+        return next();
+      }
+      return res.status(403).json({ message: 'You are not a manager' });
+    });
   };
-//for seller access
+};
+
+/**
+ * Middleware to verify if user is a seller, payment manager, or accessing their own resource
+ * @param {string} secret - JWT secret for token verification
+ * @returns {Function} Express middleware function
+ */
 const verifySeller = (secret) => {
-	return (req, res, next) => {
-	  verifyToken(secret)(req, res, () => {
-		if (req.user.id == req.params.id || req.user.role == 'seller' || req.user.role == 'paymentManager') {
-		  return next();
-		}
-		return res.status(403).json({ message: 'You are not authorized' });
-	  });
-	};
+  return (req, res, next) => {
+    verifyToken(secret)(req, res, () => {
+      if (req.user.id == req.params.id || req.user.role == 'seller' || req.user.role == 'paymentManager') {
+        return next();
+      }
+      return res.status(403).json({ message: 'You are not authorized' });
+    });
+  };
+};
+
+/**
+ * Middleware to verify seller role and optionally check resource ownership
+ * More flexible than verifySeller - focuses on role validation for creating resources
+ * @param {string} secret - JWT secret for token verification
+ * @returns {Function} Express middleware function
+ * @example
+ * router.post('/offers', verifySellerRole(secret), controller)
+ */
+const verifySellerRole = (secret) => {
+  return (req, res, next) => {
+    verifyToken(secret)(req, res, () => {
+      if (req.user.role === 'seller' || req.user.role === 'paymentManager') {
+        return next();
+      }
+      return res.status(403).json({ message: 'Seller role required' });
+    });
+  };
+};
+
+/**
+ * Higher-order middleware factory to verify token and check resource ownership
+ * Validates that the authenticated user owns the resource before allowing access
+ * @param {string} secret - JWT secret for token verification
+ * @param {Function} getResourceOwnerId - Async function that retrieves the owner ID of the resource
+ *   Function receives (req) and should return the owner ID or throw error if resource not found
+ * @returns {Function} Express middleware function
+ * @example
+ * // For offer ownership check
+ * const checkOfferOwnership = async (req) => {
+ *   const offer = await Offer.findById(req.params.id);
+ *   if (!offer) throw new Error('Offer not found');
+ *   return offer.sellerId;
+ * };
+ * router.put('/offer/:id', verifyTokenAndOwnership(secret, checkOfferOwnership), controller)
+ */
+const verifyTokenAndOwnership = (secret, getResourceOwnerId) => {
+  return (req, res, next) => {
+    verifyToken(secret)(req, res, async () => {
+      try {
+        const ownerId = await getResourceOwnerId(req);
+        
+        // Convert both to strings for comparison to handle ObjectId and string types
+        if (ownerId.toString() === req.user.id.toString()) {
+          return next();
+        }
+        
+        return res.status(403).json({ message: 'You are not authorized to access this resource' });
+      } catch (error) {
+        // If resource not found or other errors during ownership check
+        if (error.message.includes('not found')) {
+          return res.status(404).json({ message: error.message });
+        }
+        return res.status(500).json({ message: 'Error verifying resource ownership' });
+      }
+    });
   };
+};
+
+/**
+ * Middleware to verify seller, manager, admin, or SuperManager roles
+ * Used for operations that require elevated privileges
+ * @param {string} secret - JWT secret for token verification
+ * @returns {Function} Express middleware function
+ * @example
+ * router.get('/store/:id/orders', verifySellerOrAdmin(secret), controller)
+ */
+const verifySellerOrAdmin = (secret) => {
+  return (req, res, next) => {
+    verifyToken(secret)(req, res, () => {
+      const allowedRoles = ['admin', 'seller', 'manager', 'SuperManager'];
+      if (allowedRoles.includes(req.user.role)) {
+        return next();
+      }
+      return res.status(403).json({ message: 'Access denied. Seller or admin privileges required' });
+    });
+  };
+};
+
+/**
+ * Higher-order middleware factory for complex ownership verification
+ * Allows access if user is admin/SuperManager OR matches one of the owner IDs
+ * Useful for resources that can have multiple owners (e.g., orders - client or seller)
+ * @param {string} secret - JWT secret for token verification
+ * @param {Function} getResourceOwnerIds - Async function that retrieves owner IDs
+ *   Function receives (req) and should return an array of owner IDs or throw error
+ * @returns {Function} Express middleware function
+ * @example
+ * // For order ownership check (client or seller of the store)
+ * const checkOrderOwnership = async (req) => {
+ *   const order = await Order.findById(req.params.id);
+ *   if (!order) throw new Error('Order not found');
+ *   const store = await Store.findById(order.storeId);
+ *   return [order.clientId, store.sellerId]; // Both can access
+ * };
+ * router.get('/order/:id', verifyTokenAndMultiOwnership(secret, checkOrderOwnership), controller)
+ */
+const verifyTokenAndMultiOwnership = (secret, getResourceOwnerIds) => {
+  return (req, res, next) => {
+    verifyToken(secret)(req, res, async () => {
+      try {
+        // Admin and SuperManager can access all resources
+        if (req.user.role === 'admin' || req.user.role === 'SuperManager') {
+          return next();
+        }
+
+        const ownerIds = await getResourceOwnerIds(req);
+        const userId = req.user.id.toString();
+        
+        // Check if user ID matches any of the owner IDs
+        const hasAccess = ownerIds.some(ownerId => ownerId.toString() === userId);
+        
+        if (hasAccess) {
+          return next();
+        }
+        
+        return res.status(403).json({ message: 'Access denied to this resource' });
+      } catch (error) {
+        if (error.message.includes('not found')) {
+          return res.status(404).json({ message: error.message });
+        }
+        return res.status(500).json({ message: 'Error verifying resource ownership' });
+      }
+    });
+  };
+};
+
+/**
+ * Middleware to verify that the authenticated user can only access/modify their own data
+ * or is an admin who can access any data
+ * Designed for user-specific endpoints where ID is in route params
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ * @param {Function} next - Express next middleware function
+ * @returns {Function} Express middleware function
+ * @example
+ * router.put('/user/:id', verifyToken(secret), verifyUserOwnershipOrAdmin, controller)
+ * router.get('/user/find/:id', verifyToken(secret), verifyUserOwnershipOrAdmin, controller)
+ */
+const verifyUserOwnershipOrAdmin = (req, res, next) => {
+  try {
+    // req.user is set by verifyToken middleware
+    if (!req.user) {
+      return res.status(401).json({ message: 'Authentication required' });
+    }
+
+    const authenticatedUserId = req.user.id;
+    const requestedUserId = req.params.id || req.params.userId;
+    const userRole = req.user.role;
+
+    // Allow if user is accessing their own data or is an admin
+    if (authenticatedUserId === requestedUserId || userRole === 'admin' || userRole === 'SuperManager') {
+      return next();
+    }
+
+    return res.status(403).json({ message: 'Access denied. You can only access your own data' });
+  } catch (err) {
+    next(err);
+  }
+};
+
+/**
+ * Middleware to verify admin or SuperManager role
+ * Restricts access to admin-only operations
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ * @param {Function} next - Express next middleware function
+ * @returns {Function} Express middleware function
+ * @example
+ * router.get('/users', verifyToken(secret), verifyAdminOrSuperManager, controller)
+ * router.get('/sellers', verifyToken(secret), verifyAdminOrSuperManager, controller)
+ */
+const verifyAdminOrSuperManager = (req, res, next) => {
+  try {
+    if (!req.user) {
+      return res.status(401).json({ message: 'Authentication required' });
+    }
+
+    const userRole = req.user.role;
+
+    if (userRole === 'admin' || userRole === 'SuperManager') {
+      return next();
+    }
+
+    return res.status(403).json({ message: 'Access denied. Admin privileges required' });
+  } catch (err) {
+    next(err);
+  }
+};
 
-module.exports = { verifyToken, verifySeller, verifyAdmin, verifyTokenAndAuthorization, verifyManager };
+module.exports = { 
+  verifyToken, 
+  authorizeRoles,
+  verifySeller,
+  verifySellerRole,
+  verifyTokenAndOwnership,
+  verifySellerOrAdmin,
+  verifyTokenAndMultiOwnership,
+  verifyUserOwnershipOrAdmin,
+  verifyAdminOrSuperManager,
+  verifyAdmin, 
+  verifyTokenAndAuthorization, 
+  verifyManager 
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jwt-middleware-auth",
-  "version": "1.1.0",
-  "description": "A flexible middleware library for JWT authentication in Express.js",
+  "version": "2.0.0",
+  "description": "A comprehensive middleware library for JWT authentication and role-based authorization in Express.js",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -10,7 +10,10 @@
     "jwt",
     "express",
     "middleware",
-    "auth"
+    "auth",
+    "authorization",
+    "roles",
+    "rbac"
   ],
   "license": "MIT",
   "dependencies": {