webgates-core 1.0.0

Core domain types, permission system, and authorization building blocks for webgates.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

//! Built-in hierarchical roles for authorization decisions.
//!
//! Use this module when the default `webgates-core` role hierarchy matches your
//! application. If not, define your own role enum and implement
//! [`crate::authz::access_hierarchy::AccessHierarchy`].
//!
//! The built-in hierarchy is ordered from least privileged to most privileged:
//!
//! - [`Role::User`]
//! - [`Role::Reporter`]
//! - [`Role::Moderator`]
//! - [`Role::Admin`]
//!
//! This ordering matters because [`crate::authz::access_hierarchy::AccessHierarchy`] uses the type's
//! total ordering to determine whether one role is the same as, or supervises,
//! another role.
//!
//! # Examples
//!
//! ```rust
//! use webgates_core::authz::access_policy::AccessPolicy;
//! use webgates_core::groups::Group;
//! use webgates_core::roles::Role;
//!
//! let exact_admin = AccessPolicy::<Role, Group>::require_role(Role::Admin);
//! let moderator_or_higher =
//!     AccessPolicy::<Role, Group>::require_role_or_supervisor(Role::Moderator);
//!
//! assert!(!exact_admin.denies_all());
//! assert!(!moderator_or_higher.denies_all());
//! ```
//!
//! # Custom role hierarchies
//!
//! If your application needs a different hierarchy, define your own enum in
//! least-privileged to most-privileged order and implement
//! [`crate::authz::access_hierarchy::AccessHierarchy`] for it.
//!
//! ```rust
//! use serde::{Deserialize, Serialize};
//! use webgates_core::authz::access_hierarchy::AccessHierarchy;
//!
//! #[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Serialize, Deserialize)]
//! enum CompanyRole {
//!     #[default]
//!     Employee,
//!     TeamLead,
//!     Manager,
//!     Director,
//! }
//!
//! impl std::fmt::Display for CompanyRole {
//!     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
//!         match self {
//!             CompanyRole::Employee => write!(f, "Employee"),
//!             CompanyRole::TeamLead => write!(f, "TeamLead"),
//!             CompanyRole::Manager => write!(f, "Manager"),
//!             CompanyRole::Director => write!(f, "Director"),
//!         }
//!     }
//! }
//!
//! impl AccessHierarchy for CompanyRole {}
//! ```

use crate::authz::access_hierarchy::AccessHierarchy;
use serde::{Deserialize, Serialize};

/// Built-in roles ordered from least privileged to most privileged.
///
/// These roles give you a ready-to-use hierarchy for common applications.
/// When used with [`crate::authz::access_policy::AccessPolicy::<Role, crate::groups::Group>::require_role_or_supervisor`],
/// a higher-privileged role can satisfy lower-role requirements.
///
/// # Example
///
/// ```rust
/// use webgates_core::authz::access_policy::AccessPolicy;
/// use webgates_core::groups::Group;
/// use webgates_core::roles::Role;
///
/// let moderator_or_higher =
///     AccessPolicy::<Role, Group>::require_role_or_supervisor(Role::Moderator);
/// let admin_or_moderator = AccessPolicy::<Role, Group>::require_role(Role::Admin)
///     .or_require_role(Role::Moderator);
///
/// assert!(!moderator_or_higher.denies_all());
/// assert!(!admin_or_moderator.denies_all());
/// ```
#[derive(
    Debug,
    Default,
    Clone,
    Copy,
    Eq,
    PartialEq,
    Ord,
    PartialOrd,
    Serialize,
    Deserialize,
    strum::Display,
    strum::EnumString,
    strum::EnumIter,
)]
pub enum Role {
    /// Baseline role for regular users.
    ///
    /// This is the default role assigned by `Account::new(...)` when you use the
    /// built-in [`Role`] type.
    #[default]
    User,
    /// Role for users who primarily need read-heavy or reporting access.
    Reporter,
    /// Elevated role for moderation or operational workflows.
    Moderator,
    /// Highest built-in role.
    ///
    /// Administrators typically have full access to protected operations.
    Admin,
}

impl AccessHierarchy for Role {}