vip-coordinator/ROLE_BASED_ACCESS_CONTROL.md

Role-Based Access Control (RBAC) System

Overview

The VIP Coordinator application implements a comprehensive role-based access control system with three distinct user roles, each with specific permissions and access levels.

User Roles

1. System Administrator (administrator)

Highest privilege level - Full system access

Permissions:

• ✅ User Management: Create, read, update, delete users
• ✅ Role Management: Assign and modify user roles
• ✅ VIP Management: Full CRUD operations on VIP records
• ✅ Driver Management: Full CRUD operations on driver records
• ✅ Schedule Management: Full CRUD operations on schedules
• ✅ System Settings: Access to admin panel and API configurations
• ✅ Flight Tracking: Access to all flight tracking features
• ✅ Reports & Analytics: Access to all system reports

API Endpoints Access:

POST   /auth/users                    ✅ Admin only
GET    /auth/users                    ✅ Admin only
PATCH  /auth/users/:email/role        ✅ Admin only
DELETE /auth/users/:email             ✅ Admin only

POST   /api/vips                      ✅ Admin + Coordinator
GET    /api/vips                      ✅ All authenticated users
PUT    /api/vips/:id                  ✅ Admin + Coordinator
DELETE /api/vips/:id                  ✅ Admin + Coordinator

POST   /api/drivers                   ✅ Admin + Coordinator
GET    /api/drivers                   ✅ All authenticated users
PUT    /api/drivers/:id               ✅ Admin + Coordinator
DELETE /api/drivers/:id               ✅ Admin + Coordinator

POST   /api/vips/:vipId/schedule      ✅ Admin + Coordinator
GET    /api/vips/:vipId/schedule      ✅ All authenticated users
PUT    /api/vips/:vipId/schedule/:id  ✅ Admin + Coordinator
PATCH  /api/vips/:vipId/schedule/:id/status ✅ All authenticated users
DELETE /api/vips/:vipId/schedule/:id  ✅ Admin + Coordinator

2. Coordinator (coordinator)

Standard operational access - Can manage VIPs, drivers, and schedules

Permissions:

• ❌ User Management: Cannot manage users or roles
• ✅ VIP Management: Full CRUD operations on VIP records
• ✅ Driver Management: Full CRUD operations on driver records
• ✅ Schedule Management: Full CRUD operations on schedules
• ❌ System Settings: No access to admin panel
• ✅ Flight Tracking: Access to flight tracking features
• ✅ Driver Availability: Can check driver conflicts and availability
• ✅ Status Updates: Can update event statuses

Typical Use Cases:

• Managing VIP arrivals and departures
• Assigning drivers to VIPs
• Creating and updating schedules
• Monitoring flight statuses
• Coordinating transportation logistics

3. Driver (driver)

Limited access - Can view assigned schedules and update status

Permissions:

• ❌ User Management: Cannot manage users
• ❌ VIP Management: Cannot create/edit/delete VIPs
• ❌ Driver Management: Cannot manage other drivers
• ❌ Schedule Creation: Cannot create or delete schedules
• ✅ View Schedules: Can view VIP schedules and assigned events
• ✅ Status Updates: Can update status of assigned events
• ✅ Personal Schedule: Can view their own complete schedule
• ❌ System Settings: No access to admin features

API Endpoints Access:

GET    /api/vips                      ✅ View only
GET    /api/drivers                   ✅ View only
GET    /api/vips/:vipId/schedule      ✅ View only
PATCH  /api/vips/:vipId/schedule/:id/status ✅ Can update status
GET    /api/drivers/:driverId/schedule ✅ Own schedule only

Typical Use Cases:

• Viewing assigned VIP transportation schedules
• Updating event status (en route, completed, delayed)
• Checking personal daily/weekly schedule
• Viewing VIP contact information and notes

Authentication Flow

1. Google OAuth Integration

• Users authenticate via Google OAuth 2.0
• First user automatically becomes administrator
• Subsequent users default to coordinator role
• Administrators can change user roles after authentication

2. JWT Token System

• Secure JWT tokens issued after successful authentication
• Tokens include user role information
• Middleware validates tokens and role permissions on each request

3. Role Assignment

// First user becomes admin
const userCount = await databaseService.getUserCount();
const role = userCount === 0 ? 'administrator' : 'coordinator';

Security Implementation

Middleware Protection

// Authentication required
app.get('/api/vips', requireAuth, async (req, res) => { ... });

// Role-based access
app.post('/api/vips', requireAuth, requireRole(['coordinator', 'administrator']), 
  async (req, res) => { ... });

// Admin only
app.get('/auth/users', requireAuth, requireRole(['administrator']), 
  async (req, res) => { ... });

Frontend Role Checking

// User Management component
if (currentUser?.role !== 'administrator') {
  return (
    <div className="p-6 bg-red-50 border border-red-200 rounded-lg">
      <h2 className="text-xl font-semibold text-red-800 mb-2">Access Denied</h2>
      <p className="text-red-600">You need administrator privileges to access user management.</p>
    </div>
  );
}

Database Schema

Users Table

CREATE TABLE users (
  id VARCHAR(255) PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  name VARCHAR(255) NOT NULL,
  picture TEXT,
  role VARCHAR(50) NOT NULL DEFAULT 'coordinator',
  provider VARCHAR(50) NOT NULL DEFAULT 'google',
  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
  last_sign_in_at TIMESTAMP WITH TIME ZONE
);

-- Indexes for performance
CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_role ON users(role);

Role Transition Guidelines

Promoting Users

1. Coordinator → Administrator

   • Grants full system access
   • Can manage other users
   • Access to system settings
   • Should be limited to trusted personnel

2. Driver → Coordinator

   • Grants VIP and schedule management
   • Can assign other drivers
   • Suitable for supervisory roles

Demoting Users

1. Administrator → Coordinator

   • Removes user management access
   • Retains operational capabilities
   • Cannot access system settings

2. Coordinator → Driver

   • Removes management capabilities
   • Retains view and status update access
   • Suitable for field personnel

Best Practices

1. Principle of Least Privilege

• Users should have minimum permissions necessary for their role
• Regular review of user roles and permissions
• Temporary elevation should be avoided

2. Role Assignment Strategy

• Administrators: IT staff, senior management (limit to 2-3 users)
• Coordinators: Operations staff, event coordinators (primary users)
• Drivers: Field personnel, transportation staff

3. Security Considerations

• Regular audit of user access logs
• Monitor for privilege escalation attempts
• Implement session timeouts for sensitive operations
• Use HTTPS for all authentication flows

4. Emergency Access

• Maintain at least one administrator account
• Document emergency access procedures
• Consider backup authentication methods

API Security Features

1. Token Validation

export function requireAuth(req: Request, res: Response, next: NextFunction) {
  const authHeader = req.headers.authorization;
  
  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'No token provided' });
  }

  const token = authHeader.substring(7);
  const user = verifyToken(token);

  if (!user) {
    return res.status(401).json({ error: 'Invalid token' });
  }

  (req as any).user = user;
  next();
}

2. Role Validation

export function requireRole(roles: string[]) {
  return (req: Request, res: Response, next: NextFunction) => {
    const user = (req as any).user;
    
    if (!user || !roles.includes(user.role)) {
      return res.status(403).json({ error: 'Insufficient permissions' });
    }
    
    next();
  };
}

Monitoring and Auditing

1. User Activity Logging

• Track user login/logout events
• Log role changes and who made them
• Monitor sensitive operations (user deletion, role changes)

2. Access Attempt Monitoring

• Failed authentication attempts
• Unauthorized access attempts
• Privilege escalation attempts

3. Regular Security Reviews

• Quarterly review of user roles
• Annual security audit
• Regular password/token rotation

Future Enhancements

1. Granular Permissions

• Department-based access control
• Resource-specific permissions
• Time-based access restrictions

2. Advanced Security Features

• Multi-factor authentication
• IP-based access restrictions
• Session management improvements

3. Audit Trail

• Comprehensive activity logging
• Change history tracking
• Compliance reporting

---

Quick Reference

Feature	Administrator	Coordinator	Driver
User Management	✅	❌	❌
VIP CRUD	✅	✅	❌
Driver CRUD	✅	✅	❌
Schedule CRUD	✅	✅	❌
Status Updates	✅	✅	✅
View Data	✅	✅	✅
System Settings	✅	❌	❌
Flight Tracking	✅	✅	❌

Last Updated: June 2, 2025 Version: 1.0