jwt-middleware-auth 1.1.0 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog - JWT Middleware Authentication
+
+### 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/README.md

@@ -0,0 +1,527 @@
+# JWT Middleware Auth
+
+A comprehensive middleware library for JWT authentication and role-based authorization in Express.js applications.
+
+## Installation
+
+```bash
+npm install jwt-middleware-auth
+```
+
+## Dependencies
+
+This package requires jsonwebtoken:
+
+```bash
+npm install jsonwebtoken@^9.0.3
+```
+
+## Usage
+
+### Basic Setup
+
+```javascript
+const express = require('express');
+const { verifyToken, authorizeRoles } = require('jwt-middleware-auth');
+
+const app = express();
+const JWT_SECRET = process.env.JWT_SECRET || 'your-secret-key';
+
+// Public route
+app.get('/api/public', (req, res) => {
+  res.json({ message: 'Public data' });
+});
+
+// Protected route - requires authentication
+app.get('/api/profile', verifyToken(JWT_SECRET), (req, res) => {
+  res.json({ user: req.user });
+});
+
+// Role-based route - requires specific role
+app.get('/api/admin', verifyToken(JWT_SECRET), authorizeRoles('admin'), (req, res) => {
+  res.json({ message: 'Admin data' });
+});
+```
+
+### Token Format
+
+Tokens should be sent in the request header:
+
+```
+token: Bearer <your-jwt-token>
+```
+
+Example:
+```
+token: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+## Available Middlewares
+
+### Authentication Middlewares
+
+#### `verifyToken(secret)`
+
+Verifies JWT token and populates `req.user` with decoded payload.
+
+```javascript
+app.get('/api/protected', verifyToken(JWT_SECRET), (req, res) => {
+  // req.user contains: { id, role, email, ... }
+  res.json({ userId: req.user.id });
+});
+```
+
+**Response on failure:**
+- `401` - Token not provided or invalid token
+
+---
+
+### Authorization Middlewares
+
+#### `authorizeRoles(...allowedRoles)`
+
+Checks if authenticated user has one of the allowed roles. Must be used after `verifyToken`.
+
+```javascript
+// Single role
+app.get('/api/admin-only', 
+  verifyToken(JWT_SECRET), 
+  authorizeRoles('admin'), 
+  controller
+);
+
+// Multiple roles
+app.get('/api/management', 
+  verifyToken(JWT_SECRET), 
+
+### Request Validation Middlewares
+
+#### `validateDashboardLogin`
+
+Validates the dashboard login request body.
+
+**Rules:**
+- `role` must NOT be provided
+- `email` is required
+- `password` is required unless `google` is truthy
+
+```javascript
+const express = require('express');
+const { validateDashboardLogin } = require('jwt-middleware-auth');
+
+const router = express.Router();
+
+router.post('/dashboard/login', validateDashboardLogin, loginController);
+```
+
+**Failure behavior:**
+- Returns `400` with a JSON `{ message }` describing the validation error.
+
+  authorizeRoles('admin', 'manager', 'SuperManager'), 
+  controller
+);
+```
+
+**Response on failure:**
+- `401` - User not authenticated
+- `403` - User doesn't have required role
+
+**Supported roles:**
+- `user` - Regular user
+- `admin` - Administrator
+- `seller` - Store seller/vendor
+- `paymentManager` - Payment processing manager
+- `manager` - General manager
+- `SuperManager` - Super administrator
+
+---
+
+#### `verifyTokenAndAuthorization(secret)`
+
+Allows access if user is updating their own account OR is an admin.
+
+```javascript
+// User can update their own profile, or admin can update any profile
+app.put('/api/users/:id', 
+  verifyTokenAndAuthorization(JWT_SECRET), 
+  updateUserController
+);
+```
+
+**Access granted when:**
+- `req.user.id === req.params.id` (own account)
+- `req.user.role === 'admin'` (admin override)
+
+---
+
+#### `verifyAdmin(secret)`
+
+Verifies user has admin privileges.
+
+```javascript
+app.delete('/api/users/:id', 
+  verifyAdmin(JWT_SECRET), 
+  deleteUserController
+);
+```
+
+**Access granted when:**
+- `req.user.isAdmin === true`
+
+---
+
+#### `verifyManager(secret)`
+
+Allows access if user is a manager or accessing their own resource.
+
+```javascript
+app.get('/api/reports/:id', 
+  verifyManager(JWT_SECRET), 
+  getReportController
+);
+```
+
+**Access granted when:**
+- `req.user.id == req.params.id` (own resource)
+- `req.user.role == 'manager'` (manager access)
+
+---
+
+#### `verifySeller(secret)`
+
+Allows access if user is a seller, payment manager, or accessing their own resource.
+
+```javascript
+app.get('/api/stores/:id', 
+  verifySeller(JWT_SECRET), 
+  getStoreController
+);
+```
+
+**Access granted when:**
+- `req.user.id == req.params.id` (own resource)
+- `req.user.role == 'seller'` (seller access)
+- `req.user.role == 'paymentManager'` (payment manager access)
+
+---
+
+#### `verifySellerRole(secret)`
+
+Focused role validation for sellers - ideal for resource creation.
+
+```javascript
+app.post('/api/offers', 
+  verifySellerRole(JWT_SECRET), 
+  createOfferController
+);
+```
+
+**Access granted when:**
+- `req.user.role === 'seller'`
+- `req.user.role === 'paymentManager'`
+
+---
+
+#### `verifySellerOrAdmin(secret)`
+
+Allows access for sellers, managers, admins, or super managers.
+
+```javascript
+app.get('/api/store/:id/orders', 
+  verifySellerOrAdmin(JWT_SECRET), 
+  getOrdersController
+);
+```
+
+**Access granted when:**
+- `req.user.role` is one of: `admin`, `seller`, `manager`, `SuperManager`
+
+---
+
+### Advanced Middlewares
+
+#### `verifyTokenAndOwnership(secret, getResourceOwnerId)`
+
+Higher-order middleware that verifies token and checks resource ownership.
+
+```javascript
+const { verifyTokenAndOwnership } = require('jwt-middleware-auth');
+const Offer = require('./models/Offer');
+
+// Define ownership check function
+const checkOfferOwnership = async (req) => {
+  const offer = await Offer.findById(req.params.id);
+  if (!offer) {
+    throw new Error('Offer not found');
+  }
+  return offer.sellerId; // Return the owner ID
+};
+
+// Apply to route
+app.put('/api/offers/:id', 
+  verifyTokenAndOwnership(JWT_SECRET, checkOfferOwnership), 
+  updateOfferController
+);
+```
+
+**Parameters:**
+- `secret` - JWT secret key
+- `getResourceOwnerId` - Async function that returns the resource owner's ID
+
+**Access granted when:**
+- `ownerId === req.user.id` (user owns the resource)
+
+**Responses:**
+- `404` - Resource not found
+- `403` - User doesn't own the resource
+- `500` - Error during ownership verification
+
+---
+
+## Complete Examples
+
+### User Management API
+
+```javascript
+const express = require('express');
+const { 
+  verifyToken, 
+  verifyTokenAndAuthorization,
+  verifyAdmin 
+} = require('jwt-middleware-auth');
+
+const app = express();
+const JWT_SECRET = process.env.JWT_SECRET;
+
+// Get own profile or any profile (admin)
+app.get('/api/users/:id', 
+  verifyTokenAndAuthorization(JWT_SECRET), 
+  (req, res) => {
+    // Fetch and return user
+  }
+);
+
+// Update own profile or any profile (admin)
+app.put('/api/users/:id', 
+  verifyTokenAndAuthorization(JWT_SECRET), 
+  (req, res) => {
+    // Update user
+  }
+);
+
+// Delete user (admin only)
+app.delete('/api/users/:id', 
+  verifyAdmin(JWT_SECRET), 
+  (req, res) => {
+    // Delete user
+  }
+);
+
+// List all users (admin only)
+app.get('/api/users', 
+  verifyAdmin(JWT_SECRET), 
+  (req, res) => {
+    // Return all users
+  }
+);
+```
+
+### E-commerce Store API
+
+```javascript
+const { 
+  verifyToken, 
+  authorizeRoles,
+  verifySellerRole,
+  verifyTokenAndOwnership 
+} = require('jwt-middleware-auth');
+
+const Store = require('./models/Store');
+
+// Get store ownership
+const checkStoreOwnership = async (req) => {
+  const store = await Store.findById(req.params.id);
+  if (!store) throw new Error('Store not found');
+  return store.ownerId;
+};
+
+// Create store (seller only)
+app.post('/api/stores', 
+  verifySellerRole(JWT_SECRET), 
+  createStoreController
+);
+
+// Update own store
+app.put('/api/stores/:id', 
+  verifyTokenAndOwnership(JWT_SECRET, checkStoreOwnership), 
+  updateStoreController
+);
+
+// View store analytics (seller, manager, admin)
+app.get('/api/stores/:id/analytics', 
+  verifyToken(JWT_SECRET),
+  authorizeRoles('seller', 'manager', 'admin'), 
+  getAnalyticsController
+);
+
+// Approve store (admin only)
+app.post('/api/stores/:id/approve', 
+  verifyToken(JWT_SECRET),
+  authorizeRoles('admin'), 
+  approveStoreController
+);
+```
+
+### Multi-Role Management System
+
+```javascript
+const { verifyToken, authorizeRoles } = require('jwt-middleware-auth');
+
+// Dashboard access - multiple roles
+app.get('/api/dashboard', 
+  verifyToken(JWT_SECRET),
+  authorizeRoles('admin', 'manager', 'SuperManager'),
+  (req, res) => {
+    res.json({ dashboard: 'data' });
+  }
+);
+
+// Financial reports - restricted roles
+app.get('/api/reports/financial', 
+  verifyToken(JWT_SECRET),
+  authorizeRoles('admin', 'paymentManager', 'SuperManager'),
+  (req, res) => {
+    res.json({ reports: 'financial data' });
+  }
+);
+
+// System settings - super admin only
+app.put('/api/settings', 
+  verifyToken(JWT_SECRET),
+  authorizeRoles('SuperManager'),
+  (req, res) => {
+    res.json({ message: 'Settings updated' });
+  }
+);
+```
+
+## Error Responses
+
+All middlewares return consistent error responses:
+
+### 401 Unauthorized
+
+```json
+{
+  "message": "Token is not provided"
+}
+```
+
+```json
+{
+  "message": "Invalid Token"
+}
+```
+
+```json
+{
+  "message": "Authentication required"
+}
+```
+
+### 403 Forbidden
+
+```json
+{
+  "message": "You are not authorized"
+}
+```
+
+```json
+{
+  "message": "Access denied. Insufficient permissions."
+}
+```
+
+```json
+{
+  "message": "Seller role required"
+}
+```
+
+```json
+{
+  "message": "You are not authorized to access this resource"
+}
+```
+
+### 404 Not Found
+
+```json
+{
+  "message": "Resource not found"
+}
+```
+
+### 500 Internal Server Error
+
+```json
+{
+  "message": "Error verifying resource ownership"
+}
+```
+
+## JWT Payload Structure
+
+Your JWT tokens should include:
+
+```javascript
+{
+  id: 'user-id',           // Required for ownership checks
+  role: 'user',            // Required for role-based access
+  isAdmin: false,          // Optional for admin checks
+  email: 'user@example.com', // Optional
+  // ... other claims
+}
+```
+
+## Best Practices
+
+1. **Use environment variables for secrets** - Never hardcode JWT secrets
+2. **Chain middlewares properly** - Always use `verifyToken` before authorization middlewares
+3. **Choose appropriate middleware** - Use specific middlewares (e.g., `authorizeRoles`) over general ones
+4. **Handle errors gracefully** - Use error middleware to catch and format authentication errors
+5. **Implement token refresh** - Consider implementing refresh token mechanism for better security
+6. **Short-lived tokens** - Use short expiration times for access tokens
+7. **Validate token payload** - Ensure JWT payload contains required fields (id, role)
+
+## Security Considerations
+
+- Store JWT secrets securely (environment variables, secret managers)
+- Use HTTPS in production to prevent token interception
+- Implement token expiration and refresh mechanisms
+- Consider token revocation strategy for logout
+- Validate and sanitize all user inputs
+- Use strong, random secret keys (minimum 32 characters)
+- Implement rate limiting on authentication endpoints
+- Log authentication failures for security monitoring
+
+## Middleware Comparison
+
+| Middleware | Authentication | Authorization | Use Case |
+|------------|----------------|---------------|----------|
+| `verifyToken` | ✅ | ❌ | Basic authentication |
+| `authorizeRoles` | ❌* | ✅ | Role-based access |
+| `verifyTokenAndAuthorization` | ✅ | ✅ | Self or admin access |
+| `verifyAdmin` | ✅ | ✅ | Admin-only access |
+| `verifyManager` | ✅ | ✅ | Manager or self access |
+| `verifySeller` | ✅ | ✅ | Seller/payment manager or self |
+| `verifySellerRole` | ✅ | ✅ | Seller role validation |
+| `verifySellerOrAdmin` | ✅ | ✅ | Elevated privileges |
+| `verifyTokenAndOwnership` | ✅ | ✅ | Resource ownership |
+
+*Requires `verifyToken` to be called first
+
+## License
+
+MIT

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,299 @@ 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);
+  }
+};
+
+/**
+ * Middleware to validate dashboard login request body.
+ *
+ * Rules:
+ * - `role` must NOT be provided (role is derived server-side).
+ * - `email` is required.
+ * - `password` is required unless `google` is truthy (Google login).
+ *
+ * @param {Object} req - Express request object
+ * @param {Object} res - Express response object
+ * @param {Function} next - Express next middleware function
+ * @returns {void}
+ *
+ * @example
+ * const express = require('express');
+ * const { validateDashboardLogin } = require('jwt-middleware-auth');
+ * const router = express.Router();
+ *
+ * router.post('/dashboard/login', validateDashboardLogin, loginController);
+ */
+const validateDashboardLogin = (req, res, next) => {
+  try {
+    const body = req.body || {};
+
+    // Role must not be provided for dashboard login
+    if (Object.prototype.hasOwnProperty.call(body, 'role')) {
+      return res.status(400).json({ message: 'Role must not be provided for dashboard login' });
+    }
+
+    if (!body.email) {
+      return res.status(400).json({ message: 'Email is required' });
+    }
+
+    // Password required for non-Google login
+    if (!body.google && !body.password) {
+      return res.status(400).json({ message: 'Password is required' });
+    }
+
+    next();
+  } catch (err) {
+    next(err);
+  }
+};
 
-module.exports = { verifyToken, verifySeller, verifyAdmin, verifyTokenAndAuthorization, verifyManager };
+module.exports = { 
+  verifyToken, 
+  authorizeRoles,
+  verifySeller,
+  verifySellerRole,
+  verifyTokenAndOwnership,
+  verifySellerOrAdmin,
+  verifyTokenAndMultiOwnership,
+  verifyUserOwnershipOrAdmin,
+  verifyAdminOrSuperManager,
+  validateDashboardLogin,
+  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.1.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": {