Permissions & Access Control

Overview

Corcava implements a comprehensive role-based access control system that ensures team members have appropriate access to projects, boards, and tasks while maintaining security and data isolation. Based on code analysis, the system uses a combination of user roles, permission checking, and team-based isolation to control access to project management features.

Understanding the permission system will help you properly configure team access and maintain appropriate security for your projects and client data.

Role-Based Access - Different User Roles and Capabilities

User Role System

Available Roles: Based on code analysis, the system implements 7 distinct user roles:

1. SUPERADMIN

Full System Access - Complete control over all organizational data and settings
isShowAllAndOwnProjectCRUD() - Can view and manage all projects
isShowAllAndOwnTaskCRUD() - Can view and manage all tasks
Team Management - Can manage all team members and roles
Financial Control - Access to all invoicing and financial features

2. ORGANIZATION_MANAGER

Team Leadership - Manage teams, projects, and organizational settings
isShowAllAndOwnProjectCRUD() - Can view and manage all team projects
isShowAllAndOwnTaskCRUD() - Can view and manage all team tasks
Client Management - Full access to client relationships and data
Financial Access - Can manage invoicing and expenses

3. SALES_MANAGER

Sales Operations - Oversee sales activities and manage sales team
isShowAllAndOwnTaskCRUD() - Can view and manage all tasks
isShowAllAndOwnContactCRUD() - Can manage all contacts and leads
isShowAllAndOwnDealCRUD() - Can manage all deals and opportunities
Project Creation - Can create projects for clients
Limited Financial - Can create invoices but limited financial access

4. SALES_REPRESENTATIVE

Focused Sales Access - Access only to assigned leads and deals
isShowAllAndOwnDealCRUD() - Can manage deals and opportunities
Project Creation - Can create projects for their clients
Limited Scope - Cannot access other team members' data
Client Interaction - Can manage assigned client relationships

5. PROJECT_MANAGER

Role Defined - Enum exists but implementation not found in analyzed code
Limited Usage - Role may not be actively implemented in current system

6. USER

Task Execution - Can work on assigned tasks and projects
Project Assignment Required - Must be assigned to projects to access
Collaboration Access - Can comment, assign users, and track time
Limited Administration - Cannot create projects or manage team settings

7. PROJECT_VIEWER

Client Access Role - Designed for client portal access
Two Sub-Types - 'viewer' and 'manager' variants
Project Assignment Required - Must be assigned to specific projects
Read/Write Access - Can view and interact with assigned projects
Free Role - Adding users in this role is free

Role Implementation Details

Role Checking Methods: Based on User model analysis:

hasRole(RoleName $role) - Check if user has specific role
Role-specific methods - isSuperAdmin(), isOrganizationManager(), etc.
Permission checking - hasPermission(string $permission)
CRUD permission groups - isShowAllAndOwnProjectCRUD(), etc.

Project Viewer Sub-Types:

isViewer() - PROJECT_VIEWER role with 'viewer' project_viewer value
isViewerManager() - PROJECT_VIEWER role with 'manager' project_viewer value
isProjectViewer() - Any PROJECT_VIEWER role regardless of sub-type

Project-Level Permissions - Who Can Access Which Projects

Project Access Control

Project Permission Implementation: Based on ProjectPolicy analysis:

Project Viewing (viewAny):

Permission Check - Users with 'project.viewAny' permission
Viewer Access - Project viewers can see assigned projects
Team Isolation - Users only see projects from their team

Project Creation (create):

Admin Roles - isShowAllAndOwnProjectCRUD() (Superadmin, OrgManager)
Sales Roles - Sales Managers and Sales Representatives can create projects
User Restriction - Regular users cannot create projects

Project Editing (edit/update):

Permission-Based - Users with 'project.update' permission
Viewer Exception - Project viewers can edit if assigned to project
Ownership-Based - Sales users can edit their own projects
Team Validation - All edits require same team membership

Project Deletion/Archiving:

Admin Control - Primarily admin and manager roles
Ownership Rights - Sales users can delete their own projects
Team Isolation - Can only delete projects within same team

Project Assignment System

Project User Relationships:

User Assignment System - Explicit assignment of users to projects
belongsToProject() - Method to check if user belongs to project
Team Validation - Project assignment requires same team membership
Permission Cascade - Project assignment affects board and task access

Assignment Benefits: ✅ Granular Control - Assign specific users to specific projects
✅ Security Isolation - Users only access assigned projects
✅ Flexible Management - Easy to add/remove users from projects
✅ Permission Inheritance - Project assignment enables board and task access

Board-Level Security - Board-Specific Access Controls

Board Permission System

Board Access Control: Based on ProjectBoardPolicy analysis:

Board Viewing:

Task Permission Dependency - Requires 'task.viewAny' permission
Project Assignment - Must be assigned to project containing board
Team Membership - Must be member of same team as board
Role-Based Access - Different access levels based on user role

Board Creation:

Admin Roles - isShowAllAndOwnTaskCRUD() users can create boards
Regular Users - Users can create boards on assigned projects
Viewer Managers - Can create boards on assigned projects
Viewer Restriction - Regular viewers cannot create boards

Board Management:

Update Permission - Requires 'task.update' permission
Ownership-Based - Users can manage boards they own
Admin Override - Admins can manage all team boards
Team Validation - All operations require same team membership

Board Security Features

Access Validation:

Multi-Layer Checking - Permission, role, team, and project assignment checks
Project User Join - Complex query joining projects and project_users tables
Team Isolation - Board access strictly limited to team members
Permission Cascade - Board access enables column and task access

Security Benefits: ✅ Project-Based Security - Board access tied to project assignment
✅ Team Isolation - Complete separation between different teams
✅ Role Respect - Different capabilities based on user roles
✅ Ownership Recognition - Board owners have enhanced permissions

Task-Level Permissions - Fine-Grained Task Access

Task Permission System

Task Access Control: Based on TaskPolicy analysis:

Task Viewing:

Team Validation - Must be member of same team as task
Column Team Check - Validates user team matches task column team
All Roles Allowed - All role types can view tasks (with team validation)
Universal Access - viewAny() returns true (with other validations)

Task Creation:

Broad Access - Most roles can create tasks (admin, user, viewer, viewer manager)
Project Assignment - Must have access to target project
Permission Check - Some roles require 'task.update' permission
Team Validation - Task creation limited to team members

Task Management:

Update Tasks - Similar permissions to task creation
Delete Tasks - Requires appropriate role and team membership
Assign Users - Can assign users to tasks with proper permissions
Add Comments - Broad access for team collaboration

Special Task Permissions:

moveToBoard - Can move tasks between boards within same team
Time Tracking - Project viewers with 'viewer' type cannot track time
File Access - Task attachment access follows task permissions

Task Security Implementation

Permission Validation Pattern: All task operations follow similar validation pattern:

Team Validation - Check user team matches task column team
Role Check - Verify user role has appropriate permissions
Project Assignment - Ensure user assigned to project (for viewers)
Permission String - Check specific permission strings where required

Task Security Benefits: ✅ Team Isolation - Tasks completely isolated between teams
✅ Project-Based Access - Task access tied to project assignment
✅ Role-Appropriate Permissions - Different capabilities based on user role
✅ Fine-Grained Control - Specific permissions for different task operations

Client Portal Access - What Clients Can See and Do

Client Portal Implementation

Client User System: Based on code analysis, client portal access uses PROJECT_VIEWER role:

Client Portal Features:

DashboardClient View - Special dashboard for client users
isViewer() Detection - System detects client users and routes to client interface
Chat Integration - Automatic chat creation for client communication
Widget Integration - Client portal widget for communication

Client Access Permissions:

Project Assignment Required - Clients must be assigned to specific projects
Team Validation - Client access limited to their team context
Limited Scope - Clients see only assigned projects and related data
Professional Interface - Separate client-facing interface

Client Portal Security

Access Control for Clients:

Role-Based Routing - isViewer() users automatically routed to client portal
Project Isolation - Clients only see projects they're assigned to
Data Filtering - All queries filtered by client assignment and permissions
Team Boundary - Client access strictly limited to their team

Client Portal Benefits: ✅ Secure Access - Clients only see relevant project information
✅ Professional Interface - Clean, client-appropriate interface
✅ Project Transparency - Clients can see project progress and status
✅ Controlled Communication - Managed communication channels with team

Permission System Architecture

Technical Implementation

Permission Storage:

Role System - Stores available user roles and capabilities
User Role Assignment - Links users to roles with team context
Individual Permissions - Specific permissions within each role
Team Isolation - All permissions scoped to team level

Permission Checking:

hasPermission() - String-based permission checking
Role Methods - Specific role checking methods
Policy Classes - Dedicated policy classes for each model
Gate Registration - Automatic gate registration for all permissions

Security Layers:

Authentication - User must be logged in
Team Membership - User must be member of relevant team
Role Validation - User must have appropriate role
Permission Check - User must have specific permission
Project Assignment - User must be assigned to project (where applicable)

Permission Benefits

✅ Multi-Layer Security - Multiple validation layers prevent unauthorized access
✅ Team Isolation - Complete separation between different teams
✅ Role-Appropriate Access - Permissions match user responsibilities
✅ Project-Specific Control - Granular control over project access
✅ Client Security - Secure, controlled access for client users

Getting Started with Permission Management

Quick Start Guide

Step 1: Understand Your Role

Check your user role and permissions
Understand what actions you can perform
Know which projects and data you can access
Identify any limitations in your access

Step 2: Manage Team Permissions

Review team member roles and access levels
Assign users to appropriate projects
Verify team members have necessary permissions
Adjust roles as needed for project requirements

Step 3: Configure Client Access

Set up client users with PROJECT_VIEWER role
Assign clients to specific projects
Configure client portal access appropriately
Test client access to ensure proper isolation

Permission Best Practices

✅ Principle of Least Privilege - Give users only the access they need
✅ Regular Review - Periodically audit user roles and permissions
✅ Clear Role Definition - Ensure team understands their access levels
✅ Project Assignment - Properly assign users to relevant projects
✅ Client Separation - Keep client access secure and appropriate
✅ Team Isolation - Maintain clear boundaries between teams

Troubleshooting Permission Issues

Common Problems

Cannot Access Projects:

Role Check - Verify you have appropriate role for project access
Project Assignment - Ensure you're assigned to the specific project
Team Membership - Confirm you're member of the correct team
Permission String - Check if you have required permission strings

Cannot Create/Edit Tasks:

Task Permission - Verify you have 'task.update' permission
Project Assignment - Ensure you're assigned to the project
Team Validation - Confirm your team matches the task's team
Role Limitations - Some roles have restricted task access

Client Portal Issues:

Role Configuration - Verify client has PROJECT_VIEWER role
Project Assignment - Ensure client is assigned to specific projects
Portal Setup - Check client portal widget configuration
Team Context - Verify client is in correct team context

Permission Debugging

Checking Your Permissions:

Role Verification - Confirm your assigned role
Permission List - Review your specific permissions
Project Assignment - Check which projects you're assigned to
Team Context - Verify you're in correct team
Policy Validation - Understand which policy rules apply to your actions

Next Steps

Now that you understand permissions and access control, you're ready to explore:

Mobile & Responsive Features - Mobile interface and touch interactions
Reporting & Analytics - Project performance and team productivity metrics
Best Practices & Workflows - Recommended project management approaches
Troubleshooting & FAQs - Common issues and solutions

Remember: The permission system in Corcava is designed to provide security while enabling collaboration. Understanding your role and permissions will help you work effectively within the system while maintaining appropriate access controls for your team and clients.