tenantAdmin.js

Go to the documentation of this file.

/**
 * @file Tenant Admin Role Authorization Middleware
 * @module middleware/tenantAdmin
 * @description
 * Express middleware for restricting routes to tenant administrator users. Validates user role
 * from req.user (set by auth middleware). Requires admin, msp, or root roles - denies staff.
 *
 * Use this for sensitive operations like refunds, financial adjustments, and account management
 * that should not be accessible to regular staff users.
 *
 * Role hierarchy:
 * - root: Super admin (Root MSP) ✅ Allowed
 * - msp: MSP admin ✅ Allowed
 * - admin: Tenant admin ✅ Allowed
 * - staff: Regular user ❌ DENIED
 * @requires middleware/auth - Must run AFTER authenticateToken middleware
 * @see {@link module:middleware/auth} for authentication middleware
 * @see {@link module:middleware/adminOnly} for similar admin-only middleware
 */
 
/**
 * Restricts route access to tenant administrator 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.
 *
 * **Use Cases:**
 * - Processing refunds
 * - Voiding invoices
 * - Financial adjustments
 * - Account configuration
 * - Sensitive data access
 * @function requireTenantAdmin
 * @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 {number} req.user.user_id - User ID for audit logging
 * @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} Tenant admin access required - User role is staff
 * @example
 * // Apply to tenant admin-only routes
 * const authenticateToken = require('./middleware/auth');
 * const requireTenantAdmin = require('./middleware/tenantAdmin');
 * 
 * router.post('/invoices/:id/refund', authenticateToken, requireTenantAdmin, (req, res) => {
 *   // Only tenant admins can process refunds
 * });
 * @example
 * // Error response for staff user attempting refund
 * {
 *   "error": "Tenant administrator access required. This action is restricted to admins only."
 * }
 */
function requireTenantAdmin(req, res, next) {
  if (!req.user) {
    return res.status(401).json({ 
      error: 'Authentication required',
      message: 'You must be logged in to perform this action'
    });
  }
 
  const userRole = req.user.role;
  
  // Allow admin, msp, and root roles (all administrator-level)
  if (userRole === 'admin' || userRole === 'msp' || userRole === 'root') {
    return next();
  }
 
  // Deny staff and any other roles
  return res.status(403).json({ 
    error: 'Tenant administrator access required',
    message: 'This action is restricted to tenant administrators. Staff users do not have permission.',
    requiredRole: 'admin',
    userRole: userRole
  });
}
 
module.exports = requireTenantAdmin;