Roles & Permissions

Version: 1.0.1

CMS uses a role-based access control system. Each user has a role and optional per-page permissions that determine what they can view, edit, and delete.

User Roles

Permission Types

Each page supports three permission levels:

Permissions are stored per user, per page in the user_permissions database table.

Page Keys

These internal keys map to application pages:

Access Matrix by Role

Admin

Admins also have exclusive access to:

• Users and Access page (sidebar only shows for admin role)
• Business Profile section on Profile page (logo and business name)

Editor (Example — Custom Permissions)

Editors get whatever permissions the admin assigns. Example configurations:

Customer Service Editor

Senior Agent

Viewer (Example)

Viewers can:

• See dashboard stats
• Browse complaints and workflows
• Copy customer messages
• Open complaint detail and print views

Viewers cannot:

• Add, edit, or delete any records
• Access Users and Access
• Change business profile

How Permissions Are Enforced

Permissions are checked at multiple layers:

1. Middleware

• Requires a valid login session cookie for all routes except /login and auth API routes
• Does not check roles — only authentication

2. Route Guard (LayoutContent)

• Maps current URL to a page key
• Redirects to the first page the user can view if they lack access
• Logs out if the user has no viewable pages at all

3. Sidebar Menu

• Menu items are filtered by canView(pageKey)
• Users and Access only appears for role === 'admin'
• Complaint Type only appears if user has view permission

4. Page Components

• Each page checks permissions before showing content
• Action buttons (Add, Edit, Delete) are hidden when permission is missing
• Unauthorized users see "You do not have access" message

5. API Routes

• User CRUD (/api/users/*) — Admin only
• Business profile update and logo upload — Admin only
• Password change — Authenticated user (own account)
• Complaint image upload — Any authenticated user

Note: Complaints, workflows, and complaint types are read/written directly via Supabase client from the browser. API-level permission enforcement for these is handled by the UI, not separate API middleware.

Default Permissions (New Database)

When cms-schema.sql is run:

Admin user (admin@admin.com):

• All pages, all permissions set to true

Non-admin users (if created without explicit permissions):

• Default view-only on: Dashboard, Complaints, Resolution Workflow, Settings
• No access to Users and Access or Complaint Type unless explicitly granted

Managing Permissions (Admin Guide)

Create a New User

1. Go to Settings → Users and Access
2. Click Add User
3. Fill in name, email, password, and role
4. Set permissions in the grid (View / Edit / Delete per page)
5. Save

Change Existing User Permissions

1. Find the user in the table
2. Click Edit
3. Update role and/or permission checkboxes
4. Save — changes apply on the user's next page load

Best Practices

Security Notes

• Change the default admin password immediately after setup
• Use strong passwords (minimum 6 characters enforced; recommend 12+)
• Set a strong JWT_SECRET in production (32+ random characters)
• Review user permissions periodically
• Remove users who no longer need access

Permission Helper Functions (Developer Reference)

The AuthContext exposes these helpers used throughout the UI:

canView(pageKey: string): boolean   // Can open the page
canEdit(pageKey: string): boolean   // Can add/modify records
canDelete(pageKey: string): boolean  // Can delete records

For admin users, all three always return true. For viewer role, canEdit and canDelete always return false.