Role System

A flexible and powerful role-based access control (RBAC) library for Rust applications.

🚀 Production-ready RBAC system with hierarchical roles, conditional permissions, and async support.

Features

✨ Core Features

Hierarchical Roles with inheritance
Fine-grained Permissions with wildcards
Dynamic Role Management and elevation
Context-based Conditional Permissions
Thread-safe Concurrent Access

🔒 Security

Fail-safe Default Deny
Comprehensive Audit Logging
Input Validation and Sanitization
Security-first Design

⚡ Performance

Built-in Permission Caching
Efficient Lock-free Data Structures
Optimized Pattern Matching
Detailed Performance Analysis

🔧 Integration

Comprehensive Middleware Examples - NEW!
Web Framework Examples
Multiple Storage Backends
Async/Await Support
Custom Storage Adapters

📚 Documentation

Comprehensive API Docs
Versioning Policy
Security Policy
Contributing Guide
Hierarchical Roles: Support for role inheritance and hierarchy
Fine-grained Permissions: Detailed permission control with action and resource type specifications
Dynamic Role Management: Runtime role assignment, removal, and temporary elevation
Conditional Permissions: Context-based permission validation
Multiple Subject Types: Support for users, groups, services, and devices
Thread-safe: Built with concurrent access in mind using DashMap
Async Support: Optional async/await support with Tokio
Persistence: Optional serialization support with Serde
Audit Logging: Optional audit trail with tracing
Caching: Built-in permission caching for performance
Flexible Storage: Pluggable storage backends (memory, file, custom)

Quick Start

Add this to your Cargo.toml:

[dependencies]

role-system = "0.1"

⚡ 5-Minute Integration

For web applications, check out our comprehensive middleware examples that show how to integrate with popular frameworks in just 5-10 lines of code:

Actix Web - Custom middleware with Transform trait
Axum - Type-safe extractors and layers
Rocket - Request guards and fairings
Warp - Filter-based authorization

Each example includes JWT authentication, role-based authorization, and production-ready error handling.

Basic Example

use role_system::{RoleSystem, Role, Permission, Subject, Resource};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the role system
    let mut role_system = RoleSystem::new();
    
    // Define permissions
    let read_docs = Permission::new("read", "documents");
    let write_docs = Permission::new("write", "documents");
    
    // Define roles with permissions
    let reader = Role::new("reader").add_permission(read_docs.clone());
    let writer = Role::new("writer")
        .add_permission(read_docs.clone())
        .add_permission(write_docs.clone());
    
    // Register roles
    role_system.register_role(reader)?;
    role_system.register_role(writer)?;
    
    // Create hierarchical roles (writer inherits from reader)
    role_system.add_role_inheritance("writer", "reader")?;
    
    // Assign roles to subjects
    let user = Subject::new("user1");
    role_system.assign_role(&user, "reader")?;
    
    // Check permissions
    let document = Resource::new("doc1", "documents");
    let can_read = role_system.check_permission(&user, "read", &document)?;
    let can_write = role_system.check_permission(&user, "write", &document)?;
    
    println!("User can read: {}", can_read);   // true
    println!("User can write: {}", can_write); // false
    
    Ok(())
}

Advanced Example with Conditional Permissions

use role_system::{RoleSystem, Role, Permission, Subject, Resource};
use std::collections::HashMap;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut role_system = RoleSystem::new();
    
    // Create a conditional permission that only works during business hours
    let conditional_print = Permission::with_condition("print", "documents", |context| {
        context.get("time") == Some(&"business_hours".to_string()) && 
        context.get("location") == Some(&"office".to_string())
    });
    
    let office_worker = Role::new("office_worker")
        .add_permission(Permission::new("read", "documents"))
        .add_permission(conditional_print);
    
    role_system.register_role(office_worker)?;
    
    let user = Subject::new("employee1");
    role_system.assign_role(&user, "office_worker")?;
    
    let document = Resource::new("report.pdf", "documents");
    
    // Create context
    let mut context = HashMap::new();
    context.insert("time".to_string(), "business_hours".to_string());
    context.insert("location".to_string(), "office".to_string());
    
    // Check permission with context
    let can_print = role_system.check_permission_with_context(
        &user, "print", &document, &context
    )?;
    
    println!("Can print during business hours at office: {}", can_print); // true
    
    // Change context - now at home
    context.insert("location".to_string(), "home".to_string());
    let can_print_home = role_system.check_permission_with_context(
        &user, "print", &document, &context
    )?;
    
    println!("Can print from home: {}", can_print_home); // false
    
    Ok(())
}

Async Example

use role_system::{
    async_support::{AsyncRoleSystem, AsyncRoleSystemBuilder},
    Role, Permission, Subject, Resource,
    storage::MemoryStorage,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create async role system
    let async_system = AsyncRoleSystemBuilder::<MemoryStorage>::new()
        .enable_caching(true)
        .build();
    
    // Define role and permissions
    let admin_role = Role::new("admin")
        .add_permission(Permission::super_admin()); // Grants access to everything
    
    async_system.register_role(admin_role).await?;
    
    // Assign role to user
    let admin_user = Subject::user("admin1");
    async_system.assign_role(&admin_user, "admin").await?;
    
    // Check permission
    let sensitive_data = Resource::new("secrets.txt", "files");
    let can_access = async_system
        .check_permission(&admin_user, "read", &sensitive_data)
        .await?;
    
    println!("Admin can access sensitive data: {}", can_access); // true
    
    Ok(())
}

Features and Configuration

Feature Flags

async (default): Enables async/await support with Tokio
persistence: Enables serialization support with Serde
audit: Enables audit logging with tracing

[dependencies]

role-system = { version = "0.1", features = ["persistence", "audit"] }

Storage Backends

The role system supports multiple storage backends:

Memory Storage (Default)

use role_system::{RoleSystem, storage::MemoryStorage};

let role_system = RoleSystem::<MemoryStorage>::new();

File Storage (with `persistence` feature)

use role_system::{RoleSystem, storage::FileStorage, core::RoleSystemConfig};

let storage = FileStorage::new("./roles.json")?;
let config = RoleSystemConfig::default();
let role_system = RoleSystem::with_storage(storage, config);

Custom Storage

Implement the Storage trait to create your own storage backend:

use role_system::storage::Storage;

struct DatabaseStorage {
    // Your database connection
}

impl Storage for DatabaseStorage {
    fn store_role(&mut self, role: Role) -> Result<()> {
        // Store role in database
    }
    
    fn get_role(&self, name: &str) -> Result<Option<Role>> {
        // Retrieve role from database
    }
    
    // ... implement other methods
}

Architecture

Core Components

RoleSystem: Main entry point for role-based access control
Role: Represents a collection of permissions that can be assigned to subjects
Permission: Represents an action that can be performed on a resource type
Subject: Represents an entity that can have roles (user, group, service, device)
Resource: Represents something that can be accessed or acted upon
Storage: Pluggable storage backend for persisting role data

Permission Model

Permissions follow the format action:resource_type:

read:documents - Read access to documents
write:users - Write access to user records
admin:* - Admin access to all resource types
*:documents - All actions on documents

Role Hierarchy

Roles can inherit from other roles, creating a hierarchy:

// admin inherits all permissions from writer
role_system.add_role_inheritance("admin", "writer")?;

// writer inherits all permissions from reader
role_system.add_role_inheritance("writer", "reader")?;

Subject Types

The system supports different types of subjects:

User: Human users
Group: Collections of users
Service: Applications or services
Device: IoT devices or systems
Custom: User-defined subject types

Temporary Role Elevation

Users can be temporarily granted additional roles:

// Elevate user to admin role for 1 hour
role_system.elevate_role(&user, "admin", Some(Duration::from_secs(3600)))?;

Performance

Caching: Built-in permission caching to avoid repeated calculations
Thread-safe: Uses DashMap for concurrent access without locks
Efficient hierarchy: Smart hierarchy traversal with cycle detection
Lazy evaluation: Permissions are only calculated when needed

Security Considerations

Fail-safe defaults: Permissions are denied by default
Explicit grants: All permissions must be explicitly granted
Hierarchy validation: Prevents circular dependencies in role hierarchy
Audit logging: Optional comprehensive audit trail
Context validation: Conditional permissions based on runtime context

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Acknowledgments

This library was extracted and evolved from the role management system originally developed for the COAD (Code Organization and Analysis Dashboard) project, providing a standalone, reusable RBAC solution for the Rust ecosystem.

role-system 0.1.0