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
//! # webgates-core
//!
//! User-focused Rust building blocks for authentication and authorization.
//!
//! `webgates-core` is the domain layer of the `webgates` ecosystem. It gives you
//! the types and services you need to represent users, declare access rules, and
//! evaluate authorization decisions without depending on any web framework,
//! transport, cookie layer, JWT implementation, or persistence backend.
//!
//! If you are onboarding to the project, the easiest mental model is:
//!
//! 1. represent the current user as an [`accounts::Account`]
//! 2. declare access requirements with an [`authz::access_policy::AccessPolicy`]
//! 3. evaluate that policy with an [`authz::authorization_service::AuthorizationService`]
//! 4. optionally connect your own login flow with [`credentials::Credentials`] and
//! [`credentials::credentials_verifier::CredentialsVerifier`]
//!
//! ## What this crate is good for
//!
//! Use `webgates-core` when you want to:
//!
//! - keep authentication and authorization logic in pure Rust domain code
//! - model users with roles, groups, and direct permissions
//! - build your own integration for a framework not covered by sibling crates
//! - share authorization logic across HTTP services, workers, CLIs, or WASM
//! - keep dependencies small and transport-agnostic
//!
//! If you want a more batteries-included experience, start with the higher-level
//! `webgates` crate instead.
//!
//! ## Core types to learn first
//!
//! Most developers can learn the crate through this sequence:
//!
//! - [`accounts::Account`] for authenticated user state
//! - [`roles::Role`] and [`groups::Group`] for access modeling
//! - [`permissions::Permissions`] and [`permissions::permission_id::PermissionId`] for fine-grained capability checks
//! - [`authz::access_policy::AccessPolicy`] for declaring access rules
//! - [`authz::authorization_service::AuthorizationService`] for evaluating those rules
//! - [`credentials::Credentials`] and [`credentials::credentials_verifier::CredentialsVerifier`] for authentication boundaries
//! - [`verification_result::VerificationResult`] for verification outcomes
//!
//! ## A minimal end-to-end example
//!
//! ```rust
//! use webgates_core::accounts::Account;
//! use webgates_core::authz::access_policy::AccessPolicy;
//! use webgates_core::authz::authorization_service::AuthorizationService;
//! use webgates_core::groups::Group;
//! use webgates_core::roles::Role;
//!
//! let account = Account::<Role, Group>::new("alice@example.com")
//! .with_roles(vec![Role::Moderator])
//! .with_groups(vec![Group::new("support")]);
//!
//! let policy = AccessPolicy::<Role, Group>::require_role(Role::Admin)
//! .or_require_group(Group::new("support"));
//!
//! let service = AuthorizationService::new(policy);
//! assert!(service.is_authorized(&account));
//! ```
//!
//! ## Important authorization behavior
//!
//! [`authz::access_policy::AccessPolicy`] uses **OR semantics** across configured
//! requirements. If any configured role, group, or permission requirement
//! matches, authorization succeeds.
//!
//! ## Getting started on docs.rs
//!
//! If you are reading this on docs.rs and want the fastest path into the crate,
//! follow this order:
//!
//! 1. Start with [`accounts::Account`] to understand what authenticated user
//! state looks like.
//! 2. Read [`roles::Role`] and [`groups::Group`] to understand broad access
//! modeling.
//! 3. Read [`permissions::Permissions`] if you need fine-grained capabilities.
//! 4. Read [`authz::access_policy::AccessPolicy`] to learn how access
//! requirements are declared.
//! 5. Read [`authz::authorization_service::AuthorizationService`] to see how a
//! policy is evaluated against an account.
//! 6. Read [`credentials::Credentials`] and
//! [`credentials::credentials_verifier::CredentialsVerifier`] if you are
//! implementing authentication flows.
//!
//! A good first interactive example is to create an `Account`, define an
//! `AccessPolicy`, and verify the result with `AuthorizationService`, as shown in
//! the minimal example above.