# Role-Based Access Control (RBAC) - Current Implementation

## Overview

AtlasOS implements a three-tier role-based access control system with the following roles:

1. **Administrator** (`administrator`) - Full system control
2. **Operator** (`operator`) - Storage and service operations
3. **Viewer** (`viewer`) - Read-only access

## Current Implementation Status

### ✅ Fully Implemented (Administrator-Only)

These operations **require Administrator role**:

- **User Management**: Create, update, delete users, list users
- **Service Management**: Start, stop, restart, reload services, view service logs
- **Maintenance Mode**: Enable/disable maintenance mode

### ⚠️ Partially Implemented (Authentication Required, No Role Check)

These operations **require authentication** but **don't check specific roles** (any authenticated user can perform them):

- **ZFS Operations**: Create/delete pools, datasets, ZVOLs, import/export pools, scrub operations
- **Snapshot Management**: Create/delete snapshots, create/delete snapshot policies
- **Storage Services**: Create/update/delete SMB shares, NFS exports, iSCSI targets
- **Backup & Restore**: Create backups, restore backups

### ✅ Public (No Authentication Required)

These endpoints are **publicly accessible**:

- **Read-Only Operations**: List pools, datasets, ZVOLs, shares, exports, targets, snapshots
- **Dashboard Data**: System statistics and health information
- **Web UI Pages**: All HTML pages (authentication required for mutations via API)

## Role Definitions

### Administrator (`administrator`)
- **Full system access**
- Can manage users (create, update, delete)
- Can manage services (start, stop, restart, reload)
- Can enable/disable maintenance mode
- Can perform all storage operations
- Can view audit logs

### Operator (`operator`)
- **Storage and service operations** (intended)
- Currently: Same as authenticated user (can perform storage operations)
- Should be able to: Create/manage pools, datasets, shares, snapshots
- Should NOT be able to: Manage users, manage services, maintenance mode

### Viewer (`viewer`)
- **Read-only access** (intended)
- Currently: Can view all public data
- Should be able to: View all system information
- Should NOT be able to: Perform any mutations (create, update, delete)

## Current Permission Matrix

| Operation | Administrator | Operator | Viewer | Unauthenticated |
|-----------|--------------|----------|--------|-----------------|
| **User Management** |
| List users | ✅ | ❌ | ❌ | ❌ |
| Create user | ✅ | ❌ | ❌ | ❌ |
| Update user | ✅ | ❌ | ❌ | ❌ |
| Delete user | ✅ | ❌ | ❌ | ❌ |
| **Service Management** |
| View service status | ✅ | ❌ | ❌ | ❌ |
| Start/stop/restart service | ✅ | ❌ | ❌ | ❌ |
| View service logs | ✅ | ❌ | ❌ | ❌ |
| **Storage Operations** |
| List pools/datasets/ZVOLs | ✅ | ✅ | ✅ | ✅ (public) |
| Create pool/dataset/ZVOL | ✅ | ✅* | ❌ | ❌ |
| Delete pool/dataset/ZVOL | ✅ | ✅* | ❌ | ❌ |
| Import/export pool | ✅ | ✅* | ❌ | ❌ |
| **Share Management** |
| List shares/exports/targets | ✅ | ✅ | ✅ | ✅ (public) |
| Create share/export/target | ✅ | ✅* | ❌ | ❌ |
| Update share/export/target | ✅ | ✅* | ❌ | ❌ |
| Delete share/export/target | ✅ | ✅* | ❌ | ❌ |
| **Snapshot Management** |
| List snapshots/policies | ✅ | ✅ | ✅ | ✅ (public) |
| Create snapshot/policy | ✅ | ✅* | ❌ | ❌ |
| Delete snapshot/policy | ✅ | ✅* | ❌ | ❌ |
| **Maintenance Mode** |
| View status | ✅ | ✅ | ✅ | ✅ (public) |
| Enable/disable | ✅ | ❌ | ❌ | ❌ |

*Currently works but not explicitly restricted - any authenticated user can perform these operations

## Implementation Details

### Role Checking

Roles are checked using the `requireRole()` middleware:

```go
// Example: Administrator-only endpoint
a.mux.HandleFunc("/api/v1/users", methodHandler(
    func(w http.ResponseWriter, r *http.Request) { a.handleListUsers(w, r) },
    func(w http.ResponseWriter, r *http.Request) {
        adminRole := models.RoleAdministrator
        a.requireRole(adminRole)(http.HandlerFunc(a.handleCreateUser)).ServeHTTP(w, r)
    },
    nil, nil, nil,
))
```

### Multiple Roles Support

The `requireRole()` function accepts multiple roles:

```go
// Allow both Administrator and Operator
a.requireRole(models.RoleAdministrator, models.RoleOperator)(handler)
```

### Current Limitations

1. **No Operator/Viewer Differentiation**: Most storage operations don't check roles - they only require authentication
2. **Hardcoded Role Checks**: Role permissions are defined in route handlers, not in a centralized permission matrix
3. **No Granular Permissions**: Can't assign specific permissions (e.g., "can create pools but not delete them")

## Future Improvements

To properly implement Operator and Viewer roles:

1. **Add Role Checks to Storage Operations**:
   - Allow Operator and Administrator for create/update/delete operations
   - Restrict Viewer to read-only (GET requests only)

2. **Centralize Permission Matrix**:
   - Create a permission configuration file or database table
   - Map operations to required roles

3. **Granular Permissions** (Future):
   - Allow custom permission sets
   - Support resource-level permissions (e.g., "can manage pool X but not pool Y")

## Testing Roles

To test different roles:

1. Create users with different roles via the Management page
2. Login as each user
3. Attempt operations and verify permissions

**Note**: Currently, most operations work for any authenticated user. Only user management, service management, and maintenance mode are properly restricted to Administrators.