adminOnly.js

Go to the documentation of this file.

/**
 * @file Admin Role Authorization Middleware
 * @module middleware/adminOnly
 * @description
 * Express middleware for restricting routes to admin-level users. Validates user role
 * from req.user (set by auth middleware). Allows admin, msp, and root roles, denies
 * regular staff users.
 *
 * Role hierarchy:
 * - root: Super admin (Root MSP)
 * - msp: MSP admin
 * - admin: Tenant admin
 * - staff: Regular user (DENIED)
 * @requires middleware/auth - Must run AFTER authenticateToken middleware
 * @see {@link module:middleware/auth} for authentication middleware
 * @see {@link module:middleware/tenant~requireRoot} for root-only access
 */
 
/**
 * Restricts route access to admin-level users (admin/msp/root roles).
 *
 * Checks req.user.role set by authenticateToken middleware. Allows admins, MSPs, and
 * root users, denies staff. Returns 403 for staff users, 401 for unauthenticated.
 * @function requireAdmin
 * @param {object} req - Express request object
 * @param {object} req.user - User object from authenticateToken middleware
 * @param {string} req.user.role - User role (admin/msp/root/staff)
 * @param {object} res - Express response object
 * @param {Function} next - Express next middleware function
 * @returns {void} Calls next() for admin users, sends 401/403 otherwise
 * @throws {401} Authentication required - Missing req.user
 * @throws {403} Admin access required - User role is staff
 * @example
 * // Apply to admin-only routes
 * const authenticateToken = require('./middleware/auth');
 * const requireAdmin = require('./middleware/adminOnly');
 * 
 * router.delete('/customers/:id', authenticateToken, requireAdmin, (req, res) => {
 *   // Only admins can delete customers
 * });
 * @example
 * // Error response for staff user
 * {
 *   "error": "Admin access required. Staff users cannot perform this action."
 * }
 */
function requireAdmin(req, res, next) {
  if (!req.user) {
    return res.status(401).json({ error: 'Authentication required' });
  }
 
  const userRole = req.user.role;
  
  // Allow admin, msp, and root roles
  if (userRole === 'admin' || userRole === 'msp' || userRole === 'root') {
    return next();
  }
 
  return res.status(403).json({ error: 'Admin access required. Staff users cannot perform this action.' });
}
 
module.exports = requireAdmin;