Sindbad~EG File Manager

# Access Control System Guide

## Overview
The application uses a hierarchical access control system with 4 levels of access. Each level can access modules at their level and below.

## Access Levels (Hierarchy)

### 1. **Assembly Level** (Lowest)
- **Access Value:** 1
- **Can Access:**
  - Basic membership management
  - Event attendance
  - Membership cards and codes
  - Assembly-specific data only

**Typical Modules:**
- Membership (assembly scope)
- Events (assembly scope)
- Event Attendance
- Event Registrations
- Membership Cards
- Member Codes
- Assemblies Management

---

### 2. **District Level**
- **Access Value:** 2
- **Can Access:**
  - All Assembly level modules
  - District-wide data
  - Reports and analytics

**Additional Modules:**
- Districts Management
- Reports
- Event Reports

---

### 3. **Area Level**
- **Access Value:** 3
- **Can Access:**
  - All District level modules
  - All Assembly level modules
  - Area-wide administration
  - User management
  - Communication tools

**Additional Modules:**
- Areas Management
- User Management
- Member Accounts
- Email Management
- Messaging
- Notifications

---

### 4. **Superuser Level** (Highest)
- **Access Value:** 4
- **Can Access:**
  - ALL modules in the system
  - System settings
  - Critical configurations

**Additional Modules:**
- Settings
- System Settings
- Page Content Editor
- General Settings
- Audit Logs (full access)

---

## Implementation

### Helper Functions (in `config/config.php`)

```php
// Check if user can access a specific level
canAccess($level)

// Check access and redirect if denied
checkAccess($requiredLevel, $redirectUrl = 'dashboard.php')

// Check if user can access a specific module
canAccessModule($moduleName)

// Get current user's access level
getAccessLevel()

// Check if current user is superuser
isSuperuser()
```

### Usage in Modules

**Method 1: Direct Access Check**
```php
<?php
require_once '../../config/config.php';
checkLogin();

// Require area level or higher
checkAccess('area');
```

**Method 2: Module Access Check (Auto-detect)**
```php
<?php
$requiredAccess = 'district'; // Set required level
require_once __DIR__ . '/../../includes/module_access_check.php';
```

---

## Module Access Levels Reference

| Module Name | Required Level | Scope |
|------------|----------------|-------|
| **Core Modules** |
| Membership | Assembly | Basic member management |
| Events | Assembly | Event creation and management |
| Event Attendance | Assembly | Check-in/check-out |
| Event Registrations | Assembly | Registration management |
| **Cards & Codes** |
| Membership Cards | Assembly | ID card generation |
| Member Codes | Assembly | QR code management |
| **Administration** |
| Assemblies | Assembly | Assembly management |
| Districts | District | District management |
| Areas | Area | Area management |
| **User Management** |
| Users | Area | User account management |
| Member Accounts | Area | Member login accounts |
| **Communication** |
| Email Management | Area | Email campaigns |
| Messaging | Area | Internal messaging |
| Notifications | Area | System notifications |
| **Reports** |
| Reports | District | General reports |
| Event Reports | District | Event analytics |
| Audit Logs | District | Activity logs |
| **System** |
| Settings | Superuser | System configuration |
| Page Content Editor | Superuser | Website content |

---

## Data Filtering by Access Level

Users can only see data within their scope:

### Assembly Level Users
```php
WHERE assembly_id = :user_assembly_id
```

### District Level Users
```php
WHERE district_id = :user_district_id
```

### Area Level Users
```php
WHERE area_id = :user_area_id
```

### Superusers
No filtering - see all data

---

## Access Control Flow

```
User logs in
    ↓
Session stores: access_level, area_id, district_id, assembly_id
    ↓
User visits module page
    ↓
checkAccess() verifies permission
    ↓
If denied → Redirect to dashboard with error
    ↓
If allowed → Load module with filtered data
```

---

## Security Features

1. **Session-based:** Access level stored in session
2. **Function-based:** Consistent access checks
3. **Database-driven:** Module permissions in `module_management` table
4. **Hierarchical:** Higher levels automatically get lower permissions
5. **Filtered queries:** Users only see data in their scope
6. **Error messages:** Clear feedback on access denial

---

## Database Structure

### module_management Table
```sql
- module_name (VARCHAR)
- module_url (VARCHAR)
- required_role (ENUM: 'assembly', 'district', 'area', 'superuser')
- is_active (BOOLEAN)
- display_order (INT)
```

### users Table
```sql
- access_level (ENUM: 'assembly', 'district', 'area', 'superuser')
- is_superuser (BOOLEAN)
- area_id (INT, nullable)
- district_id (INT, nullable)
- assembly_id (INT, nullable)
```

---

## Updating Access Levels

Run the SQL script to update module access levels:
```sql
-- Run this script
source sql/update_module_access_levels.sql;
```

---

## Testing Access Control

1. **Create test users** with different access levels
2. **Login as each user** and verify:
   - Correct modules appear in sidebar
   - Trying to access restricted URLs redirects
   - Data is properly filtered to user's scope
3. **Try direct URL access** to verify redirect works

---

## Common Issues

### Issue: User sees modules they shouldn't
**Solution:** Run `update_module_access_levels.sql` to fix module permissions

### Issue: Superuser can't access module
**Solution:** Check `isSuperuser()` returns true, verify session variables

### Issue: Access denied on valid module
**Solution:** Verify `required_role` in `module_management` table matches expectations

---

## Best Practices

1. ✅ Always use `checkAccess()` at the top of module files
2. ✅ Filter database queries by user's location IDs
3. ✅ Use helper functions instead of manual checks
4. ✅ Display clear error messages
5. ✅ Log access attempts for security
6. ✅ Test with all user levels before deployment

---

## Adding New Modules

When creating a new module:

1. **Add to database:**
```sql
INSERT INTO module_management (
    module_name, 
    module_url, 
    required_role, 
    module_icon, 
    display_order
) VALUES (
    'New Module', 
    'modules/new/index.php', 
    'assembly', -- Set appropriate level
    'icon-name', 
    100
);
```

2. **Add access check in module file:**
```php
checkAccess('assembly'); // Set appropriate level
```

3. **Filter queries if needed:**
```php
if (getAccessLevel() === 'assembly') {
    $query .= " AND assembly_id = :assembly_id";
}
```

---

## Support

For issues or questions about access control:
- Check this guide first
- Verify session variables are set correctly
- Review `config/config.php` helper functions
- Check database `required_role` values