webgates_core/lib.rs
1#![deny(missing_docs)]
2#![deny(unsafe_code)]
3#![deny(clippy::unwrap_used)]
4#![deny(clippy::expect_used)]
5//! # webgates-core
6//!
7//! User-focused Rust building blocks for authentication and authorization.
8//!
9//! `webgates-core` is the domain layer of the `webgates` ecosystem. It gives you
10//! the types and services you need to represent users, declare access rules, and
11//! evaluate authorization decisions without depending on any web framework,
12//! transport, cookie layer, JWT implementation, or persistence backend.
13//!
14//! If you are onboarding to the project, the easiest mental model is:
15//!
16//! 1. represent the current user as an [`accounts::Account`]
17//! 2. declare access requirements with an [`authz::access_policy::AccessPolicy`]
18//! 3. evaluate that policy with an [`authz::authorization_service::AuthorizationService`]
19//! 4. optionally connect your own login flow with [`credentials::Credentials`] and
20//! [`credentials::credentials_verifier::CredentialsVerifier`]
21//!
22//! ## What this crate is good for
23//!
24//! Use `webgates-core` when you want to:
25//!
26//! - keep authentication and authorization logic in pure Rust domain code
27//! - model users with roles, groups, and direct permissions
28//! - build your own integration for a framework not covered by sibling crates
29//! - share authorization logic across HTTP services, workers, CLIs, or WASM
30//! - keep dependencies small and transport-agnostic
31//!
32//! If you want a more batteries-included experience, start with the higher-level
33//! `webgates` crate instead.
34//!
35//! ## Core types to learn first
36//!
37//! Most developers can learn the crate through this sequence:
38//!
39//! - [`accounts::Account`] for authenticated user state
40//! - [`roles::Role`] and [`groups::Group`] for access modeling
41//! - [`permissions::Permissions`] and [`permissions::permission_id::PermissionId`] for fine-grained capability checks
42//! - [`authz::access_policy::AccessPolicy`] for declaring access rules
43//! - [`authz::authorization_service::AuthorizationService`] for evaluating those rules
44//! - [`credentials::Credentials`] and [`credentials::credentials_verifier::CredentialsVerifier`] for authentication boundaries
45//! - [`verification_result::VerificationResult`] for verification outcomes
46//!
47//! ## A minimal end-to-end example
48//!
49//! ```rust
50//! use webgates_core::accounts::Account;
51//! use webgates_core::authz::access_policy::AccessPolicy;
52//! use webgates_core::authz::authorization_service::AuthorizationService;
53//! use webgates_core::groups::Group;
54//! use webgates_core::roles::Role;
55//!
56//! let account = Account::<Role, Group>::new("alice@example.com")
57//! .with_roles(vec![Role::Moderator])
58//! .with_groups(vec![Group::new("support")]);
59//!
60//! let policy = AccessPolicy::<Role, Group>::require_role(Role::Admin)
61//! .or_require_group(Group::new("support"));
62//!
63//! let service = AuthorizationService::new(policy);
64//! assert!(service.is_authorized(&account));
65//! ```
66//!
67//! ## Important authorization behavior
68//!
69//! [`authz::access_policy::AccessPolicy`] uses **OR semantics** across configured
70//! requirements. If any configured role, group, or permission requirement
71//! matches, authorization succeeds.
72//!
73//! ## Getting started on docs.rs
74//!
75//! If you are reading this on docs.rs and want the fastest path into the crate,
76//! follow this order:
77//!
78//! 1. Start with [`accounts::Account`] to understand what authenticated user
79//! state looks like.
80//! 2. Read [`roles::Role`] and [`groups::Group`] to understand broad access
81//! modeling.
82//! 3. Read [`permissions::Permissions`] if you need fine-grained capabilities.
83//! 4. Read [`authz::access_policy::AccessPolicy`] to learn how access
84//! requirements are declared.
85//! 5. Read [`authz::authorization_service::AuthorizationService`] to see how a
86//! policy is evaluated against an account.
87//! 6. Read [`credentials::Credentials`] and
88//! [`credentials::credentials_verifier::CredentialsVerifier`] if you are
89//! implementing authentication flows.
90//!
91//! A good first interactive example is to create an `Account`, define an
92//! `AccessPolicy`, and verify the result with `AuthorizationService`, as shown in
93//! the minimal example above.
94
95pub mod accounts;
96pub mod authz;
97pub mod credentials;
98pub mod errors;
99pub mod errors_core;
100pub mod groups;
101pub mod permissions;
102pub mod prelude;
103pub mod roles;
104pub mod verification_result;