rocket_grants/
lib.rs

1#![doc(
2    html_logo_url = "https://raw.githubusercontent.com/DDtKey/protect-endpoints/main/rocket-grants/logo.png"
3)]
4//! A crate to protect your endpoints in `rocket`.
5//!
6//! For built-in configure see: [`GrantsFairing`].
7//!
8//! To check user access to specific services, you can use [`proc-macro`] or manual.
9//!
10//! The library can also be integrated with third-party solutions or your custom fairings, see [`permissions`] module.
11//!
12//! You can find more [`examples`] in the git repository.
13//!
14//! [`GrantsFairing`]: GrantsFairing
15//! [`examples`]: https://github.com/DDtKey/protect-endpoints/tree/main/rocket-grants/examples
16//! [`permissions`]: authorities
17//! [`proc-macro`]: proc_macro
18#![doc = include_str!("../README.md")]
19
20pub mod authorities;
21mod fairing;
22
23pub use fairing::GrantsFairing;
24
25/// Procedural macros for checking user authorities (permissions or roles).
26///
27/// # Examples
28/// ```rust
29/// use rocket::{Response, http::Status};
30/// use rocket::serde::json::Json;
31///
32/// // User should be ADMIN with OP_GET_SECRET permission
33/// #[rocket_grants::protect("ROLE_ADMIN", "OP_GET_SECRET")]
34/// #[rocket::get("/")]
35/// async fn macro_secured() -> &'static str {
36///    "some secured info"
37/// }
38///
39/// // User should be ADMIN and MANAGER
40/// #[rocket_grants::protect("ROLE_ADMIN", "ROLE_MANAGER")]
41/// #[rocket::get("/role")]
42/// async fn role_macro_secured() -> &'static str {
43///    "some secured info"
44/// }
45///
46/// // Additional security condition to ensure the protection of the endpoint
47/// #[rocket_grants::protect("USER", expr = "user_id == user.id")]
48/// #[rocket::post("/secure/<user_id>", data = "<user>")]
49/// async fn role_macro_secured_with_params(user_id: i32, user: Json<User>) -> &'static str {
50///    "some secured info with parameters"
51/// }
52///
53/// #[derive(serde::Deserialize)]
54/// struct User { id: i32 }
55///
56/// // You own type is also supported (need to configure fairing for this type as well):
57/// #[rocket_grants::protect(any("Role::Admin", "Role::Manager"), ty = Role)]
58/// #[rocket::get("/enum")]
59/// async fn role_enum_macro_secured() -> &'static str {
60///    "some secured info"
61/// }
62/// #[derive(Eq, PartialEq, Hash)] // required bounds
63/// enum Role { Admin, Manager }
64///
65/// ```
66#[cfg(feature = "macro-check")]
67pub mod proc_macro {
68    pub use protect_endpoints_proc_macro::protect_rocket as protect;
69}
70
71/// Just a shortcut for proc-macros
72#[cfg(feature = "macro-check")]
73pub use proc_macro::*;
rocket_grants/lib.rs

rocket_grants/
lib.rs
