Crate role_system

Expand description

§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::core::RoleSystemConfig;
pub use crate::error::Error;
pub use crate::hierarchy::HierarchyConfig;
pub use crate::hierarchy::HierarchyConfigBuilder;
pub use crate::hierarchy::RelationshipType;
pub use crate::hierarchy::RoleHierarchyTree;
pub use crate::hierarchy::RoleNode;
pub use crate::hierarchy::RoleRelationship;
pub use crate::permission::Permission;
pub use crate::resource::Resource;
pub use crate::role::Role;
pub use crate::storage::MemoryStorage;
pub use crate::subject::Subject;
pub use crate::async_support::AsyncRoleSystem;

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.
hierarchy: Role hierarchy types and tree structures for optional hierarchy access.
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.
define_role: Define a single role with its permissions using a fluent builder syntax.
define_roles: Define multiple roles with their permissions declaratively.
instrument: Macro for creating instrumented operations.
permission: Quick macro for creating a permission with resource and actions.
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

Crate role_systemCopy item path