webgates_core/authz.rs
1//! Authorization primitives for role-, group-, and permission-based access control.
2//!
3//! This module is where you define **who should be allowed through** and how to
4//! evaluate that decision against an account.
5//!
6//! If you are new to `webgates-core`, the usual flow is:
7//!
8//! 1. create or load an [`crate::accounts::Account`]
9//! 2. build an [`access_policy::AccessPolicy`] that describes the requirement
10//! 3. evaluate it with [`authorization_service::AuthorizationService`]
11//!
12//! ## Main types
13//!
14//! - [`access_hierarchy::AccessHierarchy`] defines how custom role types support supervisor checks
15//! - [`access_policy::AccessPolicy`] declares role, group, and permission requirements
16//! - [`authorization_service::AuthorizationService`] evaluates a policy against an account
17//! - [`errors::AuthzError`] contains authorization-related error values
18//!
19//! Import items directly from their owning submodule for a single canonical path.
20//!
21//! # Quick start
22//!
23//! ```rust
24//! use webgates_core::accounts::Account;
25//! use webgates_core::authz::access_policy::AccessPolicy;
26//! use webgates_core::authz::authorization_service::AuthorizationService;
27//! use webgates_core::groups::Group;
28//! use webgates_core::roles::Role;
29//!
30//! let account = Account::<Role, Group>::new("user@example.com")
31//! .with_groups(vec![Group::new("engineering")]);
32//!
33//! let policy = AccessPolicy::<Role, Group>::require_group(Group::new("engineering"));
34//! let authz = AuthorizationService::new(policy);
35//!
36//! assert!(authz.is_authorized(&account));
37//! ```
38//!
39//! # Policy composition
40//!
41//! Policies use **OR semantics**. Authorization succeeds when any configured
42//! role, group, or permission requirement matches.
43//!
44//! ```rust
45//! use webgates_core::authz::access_policy::AccessPolicy;
46//! use webgates_core::groups::Group;
47//! use webgates_core::roles::Role;
48//!
49//! let policy = AccessPolicy::<Role, Group>::require_role(Role::Admin)
50//! .or_require_group(Group::new("security-team"))
51//! .or_require_permission("emergency:access");
52//!
53//! assert!(policy.has_requirements());
54//! ```
55//!
56//! # Hierarchical roles
57//!
58//! Use [`access_policy::AccessPolicy::<R, G>::require_role_or_supervisor`] when a
59//! higher-privileged role should satisfy a lower-privileged requirement.
60//!
61//! ```rust
62//! use webgates_core::authz::access_policy::AccessPolicy;
63//! use webgates_core::groups::Group;
64//! use webgates_core::roles::Role;
65//!
66//! let policy = AccessPolicy::<Role, Group>::require_role_or_supervisor(Role::Moderator);
67//!
68//! assert!(policy.has_requirements());
69//! ```
70
71/// Trait that marks a type as participating in role-hierarchy checks.
72pub mod access_hierarchy;
73/// Domain object describing who may access a protected resource.
74pub mod access_policy;
75mod access_scope;
76/// Domain service for evaluating access policies against accounts.
77pub mod authorization_service;
78/// Authorization-category error values.
79pub mod errors;