Crate role_system

Role System

This crate provides a complete framework for defining roles, permissions, and access policies with support for dynamic role management, hierarchical roles, and fine-grained permission checking.

Features

• Hierarchical role definitions and inheritance
• Fine-grained permission control
• Dynamic role management at runtime
• Role assignment to users, groups, or resources
• Conditional permissions based on context
• Permission caching for performance
• Custom permission validators
• Serializable role definitions
• Audit logging of permission checks
• Integration with authentication systems
• Thread-safe implementation
• Support for temporary role elevation
• Role constraints (time-based, location-based, etc.)

Quick Start

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

// 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)?;

// 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)?;

assert!(can_read);

Audit Logging

When the audit feature is enabled, Role System logs important security events using the standard Rust logging framework. To enable logging:

use role_system::init_audit_logger;

// Initialize logging (must be called early in program execution)
init_audit_logger();

// Configure log level through RUST_LOG environment variable:
// RUST_LOG=info,role_system=debug

The following events are logged:

• Role registration and updates
• Role hierarchy changes
• Role assignments and removals
• Permission checks (at debug level)
• Security-relevant errors

Re-exports

pub use crate::app_type::ApplicationType;

pub use crate::auth_context::AuthenticationContext;

pub use crate::auth_context::JwtContext;

pub use crate::auth_context::SessionContext;

pub use crate::batch::BatchConfig;

pub use crate::batch::BatchOperations;

pub use crate::batch::BatchPermissionCheck;

pub use crate::batch::BatchResult;

pub use crate::batch::BatchRoleAssignment;

pub use crate::context_integration::ContextualPermissions;

pub use crate::core::AccessResult;

pub use crate::core::RoleSystem;

pub use crate::error::Error;

pub use crate::permission::Permission;

pub use crate::resource::Resource;

pub use crate::role::Role;

pub use crate::subject::Subject;

Modules

app_type

Application types for role templates.

async_support

Async support for the role system (requires ‘async’ feature).

auth_context

Generic authentication context integration.

batch

Batch operations API for high-performance bulk operations

cache

Fine-grained cache management for the role system.

context_integration

Contextual permission checking with external authentication contexts.

core

Core role system implementation.

database

Database storage backend for the role system.

error

Error types for the role system.

health

Health check and monitoring utilities for the role system.

macros

Convenience macros for the role system.

metrics

Metrics collection for the role system.

performance

Performance optimization utilities for the role system.

permission

Permission definitions and validation with enhanced three-part format support.

property_tests

Property-based testing for the role system.

query

Query interface for the role system.

rate_limit

Rate limiting for role system operations.

resource

Resource definitions for access control.

role

Role definitions and management.

storage

Storage abstractions for persisting role system data.

subject

Subject definitions (users, groups, or entities that can have roles).

telemetry

Telemetry and observability integration for comprehensive monitoring.

temporal

Temporal and time-based permission management.

Macros

conditional_permission

Macro for defining conditional permissions with context requirements.

instrument

Macro for creating instrumented operations.

permissions

Macro for creating multiple permissions with a clean syntax.

role_with_permissions

Macro for creating a role with permissions in a single expression.

subjects

Macro for creating subjects with different types.

Functions

init_audit_logger