role_system/
lib.rs

1//! # Role System
2//!
3//! A flexible and powerful role-based access control (RBAC) library for Rust applications.
4//! 
5//! This crate provides a complete framework for defining roles, permissions, and access policies 
6//! with support for dynamic role management, hierarchical roles, and fine-grained permission checking.
7//!
8//! ## Features
9//!
10//! - Hierarchical role definitions and inheritance
11//! - Fine-grained permission control
12//! - Dynamic role management at runtime
13//! - Role assignment to users, groups, or resources
14//! - Conditional permissions based on context
15//! - Permission caching for performance
16//! - Custom permission validators
17//! - Serializable role definitions
18//! - Audit logging of permission checks
19//! - Integration with authentication systems
20//! - Thread-safe implementation
21//! - Support for temporary role elevation
22//! - Role constraints (time-based, location-based, etc.)
23//!
24//! ## Quick Start
25//!
26//! ```rust
27//! use role_system::{RoleSystem, Role, Permission, Subject, Resource};
28//! 
29//! // Initialize the role system
30//! let mut role_system = RoleSystem::new();
31//! 
32//! // Define permissions
33//! let read_docs = Permission::new("read", "documents");
34//! let write_docs = Permission::new("write", "documents");
35//! 
36//! // Define roles with permissions
37//! let reader = Role::new("reader").add_permission(read_docs.clone());
38//! let writer = Role::new("writer")
39//!     .add_permission(read_docs.clone())
40//!     .add_permission(write_docs.clone());
41//! 
42//! // Register roles
43//! role_system.register_role(reader)?;
44//! role_system.register_role(writer)?;
45//! 
46//! // Assign roles to subjects
47//! let user = Subject::new("user1");
48//! role_system.assign_role(&user, "reader")?;
49//! 
50//! // Check permissions
51//! let document = Resource::new("doc1", "documents");
52//! let can_read = role_system.check_permission(&user, "read", &document)?;
53//! 
54//! assert!(can_read);
55//! # Ok::<(), role_system::Error>(())
56//! ```
57//!
58//! ## Audit Logging
59//!
60//! When the `audit` feature is enabled, Role System logs important security events 
61//! using the standard Rust logging framework. To enable logging:
62//!
63//! ```rust
64//! use role_system::init_audit_logger;
65//!
66//! // Initialize logging (must be called early in program execution)
67//! init_audit_logger();
68//!
69//! // Configure log level through RUST_LOG environment variable:
70//! // RUST_LOG=info,role_system=debug
71//! ```
72//!
73//! The following events are logged:
74//! - Role registration and updates
75//! - Role hierarchy changes
76//! - Role assignments and removals
77//! - Permission checks (at debug level)
78//! - Security-relevant errors
79//!
80
81#[cfg(feature = "audit")]
82pub fn init_audit_logger() {
83    env_logger::init();
84}
85
86pub mod core;
87pub mod error;
88pub mod permission;
89pub mod resource;
90pub mod role;
91pub mod storage;
92pub mod subject;
93
94#[cfg(feature = "async")]
95pub mod async_support;
96
97// Re-export main types for convenience
98pub use crate::{
99    core::{RoleSystem, AccessResult},
100    error::Error,
101    permission::Permission,
102    resource::Resource,
103    role::Role,
104    subject::Subject,
105};
106
107pub type Result<T> = std::result::Result<T, Error>;
role_system/lib.rs

role_system/
lib.rs
