# RBAC (Role-Based Access Control) System for Rustelo

**🔧 Optional Feature** - This document provides a comprehensive guide to the optional RBAC system for the Rustelo framework. RBAC is disabled by default and can be enabled via configuration flags to provide fine-grained access control for databases, files, and content based on user roles, categories, and tags.

## Table of Contents

1. [Overview](#overview)
2. [Quick Start](#quick-start)
3. [Feature Flags](#feature-flags)
4. [Core Concepts](#core-concepts)
5. [System Architecture](#system-architecture)
6. [Configuration](#configuration)
7. [Database Schema](#database-schema)
8. [API Usage](#api-usage)
9. [Middleware Integration](#middleware-integration)
10. [Examples](#examples)
11. [Best Practices](#best-practices)
12. [Troubleshooting](#troubleshooting)

## Overview

**⚡ RBAC is an optional feature** that can be enabled when you need advanced access control beyond basic role-based authentication. When disabled (default), Rustelo uses a simple but effective role-based system (Admin, Moderator, User, Guest).

When enabled, the RBAC system provides hierarchical access control that goes beyond simple role-based permissions:

- **🔒 Optional by Design**: Enable only what you need
- **📊 Multi-layered Access Control**: Users, roles, categories, and tags
- **🎯 Resource-Specific Permissions**: Database, file, directory, content, and API access
- **⚙️ Flexible Configuration**: TOML files and database storage
- **⚡ Performance Optimization**: Built-in caching and audit logging
- **🔧 Middleware Integration**: Seamless integration with Axum middleware
- **🔄 Graceful Fallback**: Falls back to basic auth when disabled

## Quick Start

### Option 1: Use Basic Authentication (Default)
```bash
# No configuration needed - works out of the box
ENABLE_RBAC=false  # This is the default
```

### Option 2: Enable Basic RBAC
```bash
# Enable RBAC with categories
ENABLE_RBAC=true
ENABLE_RBAC_CATEGORIES=true
ENABLE_RBAC_CACHING=true
```

### Option 3: Enable Full RBAC
```bash
# Enable all RBAC features
ENABLE_RBAC=true
ENABLE_RBAC_DATABASE=true
ENABLE_RBAC_FILES=true
ENABLE_RBAC_CONTENT=true
ENABLE_RBAC_CATEGORIES=true
ENABLE_RBAC_TAGS=true
ENABLE_RBAC_CACHING=true
ENABLE_RBAC_AUDIT=true
```

## Feature Flags

RBAC is controlled by environment variables. All features are **disabled by default**:

### Core RBAC
- `ENABLE_RBAC=false` - Master switch for RBAC system

### Access Control Features
- `ENABLE_RBAC_DATABASE=false` - Database access control
- `ENABLE_RBAC_FILES=false` - File system access control  
- `ENABLE_RBAC_CONTENT=false` - Content management access control
- `ENABLE_RBAC_API=false` - API endpoint access control

### User Organization Features
- `ENABLE_RBAC_CATEGORIES=false` - User categories (departments, teams)
- `ENABLE_RBAC_TAGS=false` - User tags (attributes, clearance levels)

### Advanced Features
- `ENABLE_RBAC_CACHING=false` - Permission result caching
- `ENABLE_RBAC_AUDIT=false` - Access attempt logging
- `ENABLE_RBAC_TOML_CONFIG=false` - TOML configuration file support
- `ENABLE_RBAC_HIERARCHICAL=false` - Hierarchical permissions
- `ENABLE_RBAC_DYNAMIC_RULES=false` - Dynamic rule evaluation

### Migration Path
1. **Start Simple**: Use default authentication (no RBAC)
2. **Add Categories**: Enable `ENABLE_RBAC=true` and `ENABLE_RBAC_CATEGORIES=true`
3. **Add Resources**: Enable specific resource types as needed
4. **Add Advanced**: Enable caching, audit logging, etc. for production

## Core Concepts

### Users
Users are the primary entities in the system. Each user has:
- Basic profile information
- Assigned roles
- Categories (organizational units)
- Tags (attributes/characteristics)

### Roles
Predefined permission sets:
- **Admin**: Full system access
- **Moderator**: Content management access
- **User**: Basic application access
- **Guest**: Limited read-only access
- **Custom**: User-defined roles

### Categories
Organizational units that group users by function:
- `admin` - Administrative access
- `editor` - Content editing access
- `viewer` - Read-only access
- `finance` - Financial data access
- `hr` - Human resources access
- `it` - Information technology access

### Tags
Attributes that define user characteristics:
- `sensitive` - Access to sensitive data
- `public` - Public data access
- `internal` - Internal data access
- `confidential` - Confidential data access
- `restricted` - Restricted access
- `temporary` - Temporary access

### Resource Types
- **Database**: Database access control
- **File**: File system access control
- **Directory**: Directory-level access control
- **Content**: CMS content access control
- **API**: API endpoint access control

## System Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        RBAC System Architecture                 │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │   TOML Config   │  │   Web Interface │  │   Database      │  │
│  │     Loader      │  │                 │  │   Configuration │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
│           │                       │                       │      │
│           └───────────────────────┼───────────────────────┘      │
│                                   │                              │
│  ┌─────────────────────────────────┼─────────────────────────────┐│
│  │              RBAC Service Layer │                             ││
│  │  ┌─────────────────┐  ┌─────────▼─────────┐  ┌─────────────┐ ││
│  │  │ Permission      │  │ Configuration     │  │ Access      │ ││
│  │  │ Cache           │  │ Manager           │  │ Evaluator   │ ││
│  │  └─────────────────┘  └───────────────────┘  └─────────────┘ ││
│  └─────────────────────────────────────────────────────────────┘│
│                                   │                              │
│  ┌─────────────────────────────────┼─────────────────────────────┐│
│  │              RBAC Repository    │                             ││
│  │  ┌─────────────────┐  ┌─────────▼─────────┐  ┌─────────────┐ ││
│  │  │ User Categories │  │ Access Rules      │  │ Audit Log   │ ││
│  │  │ & Tags          │  │ Management        │  │ Manager     │ ││
│  │  └─────────────────┘  └───────────────────┘  └─────────────┘ ││
│  └─────────────────────────────────────────────────────────────┘│
│                                   │                              │
│  ┌─────────────────────────────────┼─────────────────────────────┐│
│  │              Middleware Layer   │                             ││
│  │  ┌─────────────────┐  ┌─────────▼─────────┐  ┌─────────────┐ ││
│  │  │ Authentication  │  │ Authorization     │  │ Request     │ ││
│  │  │ Middleware      │  │ Middleware        │  │ Context     │ ││
│  │  └─────────────────┘  └───────────────────┘  └─────────────┘ ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘
```

## Configuration

### TOML Configuration

The RBAC system uses TOML files for configuration. Here's the structure:

```toml
[rbac]
cache_ttl_seconds = 300

[rbac.default_permissions]
Database = ["read_content"]
File = ["read_file:public/*"]
Content = ["read_content"]

[rbac.category_hierarchies]
admin = ["editor", "viewer"]
editor = ["viewer"]

[rbac.tag_hierarchies]
public = ["internal"]
internal = ["confidential"]

[[rbac.rules]]
id = "admin_full_access"
resource_type = "database"
resource_name = "*"
allowed_roles = ["admin"]
required_categories = ["admin"]
is_active = true
priority = 1000
```

### Environment Variables

```bash
# Database configuration
DATABASE_URL=postgres://user:password@localhost:5432/database

# RBAC configuration
RBAC_CONFIG_PATH=config/rbac.toml

# JWT configuration
JWT_SECRET=your-super-secret-jwt-key

# Server configuration
SERVER_HOST=127.0.0.1
SERVER_PORT=3030
```

## Database Schema

### Core Tables

#### Users Table
```sql
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    username VARCHAR(255) NOT NULL UNIQUE,
    email VARCHAR(255) NOT NULL UNIQUE,
    password_hash VARCHAR(255) NOT NULL,
    is_active BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
```

#### User Categories
```sql
CREATE TABLE user_categories (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    name VARCHAR(100) NOT NULL UNIQUE,
    description TEXT,
    parent_id UUID REFERENCES user_categories(id),
    is_active BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
```

#### User Tags
```sql
CREATE TABLE user_tags (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    name VARCHAR(100) NOT NULL UNIQUE,
    description TEXT,
    color VARCHAR(7),
    is_active BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
```

#### Access Rules
```sql
CREATE TABLE access_rules (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    name VARCHAR(255) NOT NULL,
    resource_type VARCHAR(50) NOT NULL,
    resource_name VARCHAR(500) NOT NULL,
    action VARCHAR(50) NOT NULL,
    priority INTEGER NOT NULL DEFAULT 0,
    is_active BOOLEAN NOT NULL DEFAULT true,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
```

### Assignment Tables

#### User Category Assignments
```sql
CREATE TABLE user_category_assignments (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    user_id UUID NOT NULL REFERENCES users(id),
    category_id UUID NOT NULL REFERENCES user_categories(id),
    assigned_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    expires_at TIMESTAMPTZ,
    UNIQUE(user_id, category_id)
);
```

#### User Tag Assignments
```sql
CREATE TABLE user_tag_assignments (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    user_id UUID NOT NULL REFERENCES users(id),
    tag_id UUID NOT NULL REFERENCES user_tags(id),
    assigned_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    expires_at TIMESTAMPTZ,
    UNIQUE(user_id, tag_id)
);
```

## API Usage

### Authentication Endpoints

#### Login
```bash
POST /api/auth/login
Content-Type: application/json

{
    "email": "user@example.com",
    "password": "password",
    "remember_me": true
}
```

#### Register
```bash
POST /api/auth/register
Content-Type: application/json

{
    "email": "user@example.com",
    "username": "username",
    "password": "password",
    "display_name": "User Name"
}
```

### RBAC Management Endpoints

#### Get RBAC Configuration
```bash
GET /api/rbac/config
Authorization: Bearer <token>
```

#### Update RBAC Configuration
```bash
POST /api/rbac/config
Authorization: Bearer <token>
Content-Type: application/json

{
    "rules": [...],
    "default_permissions": {...},
    "cache_ttl_seconds": 300
}
```

#### Assign Category to User
```bash
POST /api/rbac/users/{user_id}/categories
Authorization: Bearer <token>
Content-Type: application/json

{
    "category": "editor",
    "expires_at": "2024-12-31T23:59:59Z"
}
```

#### Assign Tag to User
```bash
POST /api/rbac/users/{user_id}/tags
Authorization: Bearer <token>
Content-Type: application/json

{
    "tag": "internal",
    "expires_at": "2024-12-31T23:59:59Z"
}
```

### Protected Resource Endpoints

#### Database Access
```bash
GET /api/database/analytics
Authorization: Bearer <token>

POST /api/database/analytics/query
Authorization: Bearer <token>
Content-Type: application/json

{
    "query": "SELECT * FROM users WHERE active = true",
    "parameters": []
}
```

#### File Access
```bash
GET /api/files/reports/financial/2024-q1.pdf
Authorization: Bearer <token>

POST /api/files/uploads/documents/report.pdf
Authorization: Bearer <token>
Content-Type: application/json

{
    "operation": "write",
    "content": "base64-encoded-content"
}
```

#### Content Access
```bash
GET /api/content/blog-posts/123
Authorization: Bearer <token>

POST /api/content/blog-posts/123
Authorization: Bearer <token>
Content-Type: application/json

{
    "title": "Updated Title",
    "content": "Updated content..."
}
```

## Middleware Integration

### Basic RBAC Middleware
```rust
use crate::auth::rbac_middleware::rbac_middleware;

let app = Router::new()
    .route("/api/protected", get(protected_handler))
    .layer(middleware::from_fn(rbac_middleware));
```

### Database-Specific Middleware
```rust
use crate::auth::rbac_middleware::require_database_access;

let app = Router::new()
    .route("/api/database/:db_name", get(database_handler))
    .layer(middleware::from_fn(require_database_access(
        "analytics".to_string(),
        "read".to_string()
    )));
```

### Category-Based Middleware
```rust
use crate::auth::rbac_middleware::require_category_access;

let app = Router::new()
    .route("/api/admin/users", get(admin_handler))
    .layer(middleware::from_fn(require_category_access(
        vec!["admin".to_string()]
    )));
```

### Tag-Based Middleware
```rust
use crate::auth::rbac_middleware::require_tag_access;

let app = Router::new()
    .route("/api/sensitive/data", get(sensitive_handler))
    .layer(middleware::from_fn(require_tag_access(
        vec!["sensitive".to_string()]
    )));
```

## Examples

### Example 1: Database Access Control

```rust
use crate::auth::{RBACService, rbac_middleware::*};

async fn database_handler(
    Path(db_name): Path<String>,
    State(rbac_service): State<Arc<RBACService>>,
) -> Result<Response, StatusCode> {
    // The middleware has already checked access
    // Your database logic here
    Ok(Json(json!({
        "database": db_name,
        "status": "accessible"
    })).into_response())
}

// Apply middleware
let app = Router::new()
    .route("/api/database/:db_name", get(database_handler))
    .layer(middleware::from_fn(rbac_middleware));
```

### Example 2: File Access Control

```rust
async fn file_handler(
    Path(file_path): Path<String>,
    State(rbac_service): State<Arc<RBACService>>,
) -> Result<Response, StatusCode> {
    // File access logic
    let content = std::fs::read_to_string(&file_path)?;
    Ok(Json(json!({
        "file": file_path,
        "content": content
    })).into_response())
}

// Apply file-specific middleware
let app = Router::new()
    .route("/api/files/*path", get(file_handler))
    .layer(middleware::from_fn(require_file_access(
        "reports/*".to_string(),
        "read".to_string()
    )));
```

### Example 3: User Category Management

```rust
async fn assign_category(
    Path(user_id): Path<Uuid>,
    State(rbac_service): State<Arc<RBACService>>,
    Json(request): Json<CategoryRequest>,
) -> Result<Response, StatusCode> {
    rbac_service.assign_category_to_user(
        user_id,
        &request.category,
        None,
        request.expires_at
    ).await?;
    
    Ok(Json(json!({
        "success": true,
        "message": "Category assigned successfully"
    })).into_response())
}
```

### Example 4: Custom Access Rules

```rust
async fn check_custom_access(
    user: &User,
    resource: &str,
    action: &str,
    rbac_service: &RBACService,
) -> Result<AccessResult> {
    let context = AccessContext {
        user: Some(user.clone()),
        resource_type: ResourceType::Custom("api".to_string()),
        resource_name: resource.to_string(),
        action: action.to_string(),
        additional_context: HashMap::new(),
    };
    
    rbac_service.check_access(&context).await
}
```

## Best Practices

### 1. Principle of Least Privilege
- Grant minimum necessary permissions
- Use specific resource names instead of wildcards when possible
- Regularly review and audit user permissions

### 2. Hierarchical Categories
```toml
[rbac.category_hierarchies]
admin = ["editor", "viewer", "finance", "hr"]
editor = ["viewer"]
finance = ["viewer"]
```

### 3. Tag-Based Attributes
```toml
[rbac.tag_hierarchies]
public = ["internal"]
internal = ["confidential"]
confidential = ["restricted"]
```

### 4. Caching Strategy
- Use appropriate cache TTL (default: 5 minutes)
- Implement cache invalidation on permission changes
- Monitor cache hit rates

### 5. Audit Logging
- Log all access attempts
- Include sufficient context for security analysis
- Regular audit log review

### 6. Configuration Management
- Use version control for RBAC configuration files
- Implement configuration validation
- Test permission changes in staging environment

### 7. Error Handling
```rust
match rbac_service.check_access(&context).await {
    Ok(AccessResult::Allow) => {
        // Process request
    }
    Ok(AccessResult::Deny) => {
        return Err(StatusCode::FORBIDDEN);
    }
    Ok(AccessResult::RequireAdditionalAuth) => {
        return Err(StatusCode::UNAUTHORIZED);
    }
    Err(_) => {
        return Err(StatusCode::INTERNAL_SERVER_ERROR);
    }
}
```

## Troubleshooting

### Common Issues

#### 1. Permission Denied Errors
**Symptoms**: Users getting 403 Forbidden errors
**Solutions**:
- Check user's assigned categories and tags
- Verify access rules are active
- Check rule priority order
- Review cache expiration

#### 2. Performance Issues
**Symptoms**: Slow response times
**Solutions**:
- Optimize database queries
- Adjust cache TTL settings
- Review access rule complexity
- Use database indexes

#### 3. Configuration Errors
**Symptoms**: RBAC rules not taking effect
**Solutions**:
- Validate TOML syntax
- Check database synchronization
- Verify rule priorities
- Review resource name patterns

#### 4. Cache Inconsistencies
**Symptoms**: Inconsistent access results
**Solutions**:
- Clear permission cache
- Check cache expiration settings
- Verify cache invalidation logic
- Review concurrent access patterns

### Debugging Commands

#### Check User Permissions
```bash
curl -X GET "http://localhost:3030/api/rbac/users/{user_id}/categories" \
  -H "Authorization: Bearer <token>"
```

#### View Access Audit Log
```bash
curl -X GET "http://localhost:3030/api/rbac/audit/{user_id}" \
  -H "Authorization: Bearer <token>"
```

#### Test Access Rules
```bash
curl -X POST "http://localhost:3030/api/users/{user_id}/access-check" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"database": "analytics", "action": "read"}'
```

### Database Queries for Debugging

#### Check User Categories
```sql
SELECT u.username, uc.name as category_name
FROM users u
JOIN user_category_assignments uca ON u.id = uca.user_id
JOIN user_categories uc ON uca.category_id = uc.id
WHERE u.id = $1;
```

#### Check User Tags
```sql
SELECT u.username, ut.name as tag_name
FROM users u
JOIN user_tag_assignments uta ON u.id = uta.user_id
JOIN user_tags ut ON uta.tag_id = ut.id
WHERE u.id = $1;
```

#### Check Access Rules
```sql
SELECT ar.name, ar.resource_type, ar.resource_name, ar.priority
FROM access_rules ar
WHERE ar.resource_type = $1 AND ar.is_active = true
ORDER BY ar.priority DESC;
```

## Migration Guide

### From Simple Role-Based System

1. **Backup existing data**
2. **Run RBAC migrations**
3. **Convert existing roles to categories**
4. **Create default access rules**
5. **Test permission assignments**

### Configuration Migration

```bash
# Backup current configuration
cp config/auth.toml config/auth.toml.backup

# Create RBAC configuration
cp config/rbac.toml.example config/rbac.toml

# Edit configuration
nano config/rbac.toml
```

## Performance Considerations

### Database Optimization

1. **Indexes**: Ensure proper indexing on frequently queried columns
2. **Connection Pooling**: Use appropriate connection pool sizes
3. **Query Optimization**: Optimize access rule queries

### Caching Strategy

1. **Cache TTL**: Balance between performance and consistency
2. **Cache Size**: Monitor memory usage
3. **Cache Invalidation**: Implement selective invalidation

### Monitoring

1. **Access Patterns**: Monitor frequent access patterns
2. **Performance Metrics**: Track response times
3. **Error Rates**: Monitor permission denial rates

## Security Considerations

### Data Protection

1. **Encryption**: Encrypt sensitive data at rest
2. **Transport Security**: Use HTTPS for all communications
3. **Token Management**: Implement secure token handling

### Access Control

1. **Regular Audits**: Conduct regular permission audits
2. **Privilege Escalation**: Monitor for privilege escalation attempts
3. **Anomaly Detection**: Implement anomaly detection for access patterns

### Compliance

1. **Audit Trails**: Maintain comprehensive audit logs
2. **Data Retention**: Implement appropriate data retention policies
3. **Privacy Controls**: Respect user privacy requirements

## Contributing

When contributing to the RBAC system:

1. **Follow Rust best practices**
2. **Add comprehensive tests**
3. **Update documentation**
4. **Consider security implications**
5. **Test with real-world scenarios**

## License

This RBAC system is part of the Rustelo framework and is licensed under the MIT License.