# 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 ```typescript // First user becomes admin const userCount = await databaseService.getUserCount(); const role = userCount === 0 ? 'administrator' : 'coordinator'; ``` ## Security Implementation ### Middleware Protection ```typescript // 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 ```typescript // User Management component if (currentUser?.role !== 'administrator') { return (

Access Denied

You need administrator privileges to access user management.

); } ``` ## Database Schema ### Users Table ```sql 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 ```typescript 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 ```typescript 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