role_system/
lib.rs

1//! # Role System
2//!
3//! This crate provides a complete framework for defining roles, permissions, and access policies
4//! with support for dynamic role management, hierarchical roles, and fine-grained permission checking.
5//!
6//! ## Features
7//!
8//! - Hierarchical role definitions and inheritance
9//! - Fine-grained permission control
10//! - Dynamic role management at runtime
11//! - Role assignment to users, groups, or resources
12//! - Conditional permissions based on context
13//! - Permission caching for performance
14//! - Custom permission validators
15//! - Serializable role definitions
16//! - Audit logging of permission checks
17//! - Integration with authentication systems
18//! - Thread-safe implementation
19//! - Support for temporary role elevation
20//! - Role constraints (time-based, location-based, etc.)
21//!
22//! ## Quick Start
23//!
24//! ```rust
25//! use role_system::{RoleSystem, Role, Permission, Subject, Resource};
26//!
27//! // Initialize the role system
28//! let mut role_system = RoleSystem::new();
29//!
30//! // Define permissions
31//! let read_docs = Permission::new("read", "documents");
32//! let write_docs = Permission::new("write", "documents");
33//!
34//! // Define roles with permissions
35//! let reader = Role::new("reader").add_permission(read_docs.clone());
36//! let writer = Role::new("writer")
37//!     .add_permission(read_docs.clone())
38//!     .add_permission(write_docs.clone());
39//!
40//! // Register roles
41//! role_system.register_role(reader)?;
42//! role_system.register_role(writer)?;
43//!
44//! // Assign roles to subjects
45//! let user = Subject::new("user1");
46//! role_system.assign_role(&user, "reader")?;
47//!
48//! // Check permissions
49//! let document = Resource::new("doc1", "documents");
50//! let can_read = role_system.check_permission(&user, "read", &document)?;
51//!
52//! assert!(can_read);
53//! # Ok::<(), role_system::Error>(())
54//! ```
55//!
56//! ## Audit Logging
57//!
58//! When the `audit` feature is enabled, Role System logs important security events
59//! using the standard Rust logging framework. To enable logging:
60//!
61//! ```rust
62//! use role_system::init_audit_logger;
63//!
64//! // Initialize logging (must be called early in program execution)
65//! init_audit_logger();
66//!
67//! // Configure log level through RUST_LOG environment variable:
68//! // RUST_LOG=info,role_system=debug
69//! ```
70//!
71//! The following events are logged:
72//! - Role registration and updates
73//! - Role hierarchy changes
74//! - Role assignments and removals
75//! - Permission checks (at debug level)
76//! - Security-relevant errors
77//!
78
79#[cfg(feature = "audit")]
80pub fn init_audit_logger() {
81    env_logger::init();
82}
83
84pub mod app_type;
85pub mod auth_context;
86pub mod batch;
87pub mod cache;
88pub mod context_integration;
89pub mod core;
90pub mod database;
91pub mod error;
92
93// Testing and fuzzing
94#[cfg(test)]
95pub mod fuzz;
96
97pub mod health;
98pub mod hierarchy;
99pub mod macros;
100pub mod metrics;
101pub mod performance;
102pub mod permission;
103pub mod property_tests;
104pub mod query;
105pub mod rate_limit;
106pub mod resource;
107pub mod role;
108pub mod storage;
109pub mod subject;
110pub mod telemetry;
111pub mod temporal;
112
113#[cfg(feature = "async")]
114pub mod async_support;
115
116// Re-export main types for convenience
117pub use crate::{
118    app_type::ApplicationType,
119    auth_context::{AuthenticationContext, JwtContext, SessionContext},
120    batch::{BatchConfig, BatchOperations, BatchPermissionCheck, BatchResult, BatchRoleAssignment},
121    context_integration::ContextualPermissions,
122    core::{AccessResult, RoleSystem, RoleSystemConfig},
123    error::Error,
124    hierarchy::{
125        HierarchyConfig, HierarchyConfigBuilder, RelationshipType, RoleHierarchyTree, RoleNode,
126        RoleRelationship,
127    },
128    permission::Permission,
129    resource::Resource,
130    role::Role,
131    storage::MemoryStorage,
132    subject::Subject,
133};
134
135#[cfg(feature = "async")]
136pub use crate::async_support::AsyncRoleSystem;
role_system/lib.rs

role_system/
lib.rs
