✨ (auth): Añade el catálogo de permisos y acceso

DeclarePermissions y PermissionRegistry reúnen al arrancar los
permisos que declaran las extensiones. Access define quién puede
acceder a una ruta y `deny_access()` responde a quien no lo cumple.
Las acciones de permisos (CheckPermission, DeclarePermissions y
AnonymousDenied) pasan a `base::action::auth`, con el mismo patrón
que las de páginas y componentes.
This commit is contained in:
Manuel Cillero 2026-11-07 06:19:48 +01:00
parent b2dfb52d93
commit 379450ec40
7 changed files with 567 additions and 87 deletions

View file

@ -3,3 +3,5 @@
pub mod component;
pub mod page;
pub mod auth;

39
src/base/action/auth.rs Normal file
View file

@ -0,0 +1,39 @@
//! Acciones para conectar las extensiones de autenticación y declarar permisos.
//!
//! Con ellas una extensión concede los permisos al usuario actual ([`CheckPermission`]), da a
//! conocer los suyos en el catálogo ([`DeclarePermissions`]) o decide qué responder a un usuario
//! anónimo sin acceso a una ruta ([`AnonymousDenied`]). El resto del sistema de autorización está
//! en el módulo [`auth`](crate::auth).
use crate::auth::{PermissionRef, PermissionRegistry};
use crate::web::{HttpRequest, Response};
/// Tipo de función para comprobar si el usuario actual tiene un permiso concreto.
///
/// Se invoca con:
///
/// - `request`: petición HTTP desde la que se accede a los datos inyectados por el middleware de
/// autenticación.
/// - `perm`: permiso a comprobar; el handler usará
/// [`Permission::key()`](crate::auth::Permission::key) para identificarlo contra su propio
/// modelo de permisos.
/// - `granted`: referencia mutable; el handler debe asignarla a `true` si concede el permiso.
pub type FnActionCheckPerm = fn(request: &HttpRequest, perm: PermissionRef, granted: &mut bool);
/// Tipo de función para declarar permisos en el catálogo.
pub type FnActionDeclarePermissions = fn(registry: &mut PermissionRegistry);
/// Tipo de función para responder a un usuario anónimo sin acceso a una ruta.
///
/// Devuelve la respuesta (p. ej. una redirección al formulario de inicio de sesión), o `None` para
/// dejar que responda otra acción o, si ninguna lo hace, la página de acceso denegado.
pub type FnActionAnonymousDenied = fn(request: &HttpRequest) -> Option<Response>;
mod check_permission;
pub use check_permission::*;
mod declare_permissions;
pub use declare_permissions::*;
mod anonymous_denied;
pub use anonymous_denied::*;

View file

@ -0,0 +1,69 @@
use crate::prelude::*;
use super::FnActionAnonymousDenied;
use std::ops::ControlFlow;
/// Acción para responder a un usuario anónimo sin acceso a una ruta.
///
/// La registra una extensión de autenticación para ofrecer el inicio de sesión en lugar de la
/// página de acceso denegado, y volver después a la ruta pedida. Responde la primera acción, por
/// orden de peso, que devuelva una respuesta. Ver [`deny_access()`].
///
/// # Ejemplo
///
/// ```rust,no_run
/// # use pagetop::prelude::*;
/// fn offer_login(request: &HttpRequest) -> Option<Response> {
/// // Vuelve a la ruta pedida tras iniciar sesión.
/// let waypoint = Waypoint::new(request.uri().to_owned());
/// Some(Redirect::see_other(waypoint.append_to("/login")))
/// }
///
/// pub struct MyAuth;
///
/// #[async_trait]
/// impl Extension for MyAuth {
/// fn actions(&self) -> Vec<ActionBox> {
/// actions![action::auth::AnonymousDenied::new(offer_login)]
/// }
/// }
/// ```
pub struct AnonymousDenied {
f: FnActionAnonymousDenied,
weight: Weight,
}
impl ActionDispatcher for AnonymousDenied {
fn weight(&self) -> Weight {
self.weight
}
}
impl AnonymousDenied {
/// Permite [registrar](Extension::actions) una nueva acción [`FnActionAnonymousDenied`].
pub fn new(f: FnActionAnonymousDenied) -> Self {
AnonymousDenied { f, weight: 0 }
}
/// Opcional. Acciones con pesos más bajos se aplican antes. Se pueden usar valores negativos.
pub fn with_weight(mut self, value: Weight) -> Self {
self.weight = value;
self
}
/// Despacha las acciones hasta que una responde, y devuelve su respuesta.
#[inline]
pub(crate) fn dispatch(request: &HttpRequest) -> Option<Response> {
let mut response = None;
try_dispatch_actions(|action: &Self| {
response = (action.f)(request);
if response.is_some() {
ControlFlow::Break(())
} else {
ControlFlow::Continue(())
}
});
response
}
}

View file

@ -0,0 +1,70 @@
use crate::prelude::*;
use super::FnActionCheckPerm;
use std::ops::ControlFlow;
/// Acción para comprobar si el usuario actual tiene un permiso concreto.
///
/// Las extensiones de autenticación pueden registrar su handler sobre esta acción para implementar
/// su modelo de permisos. Los handlers son aditivos de tal forma que si cualquiera de ellos asigna
/// `granted = true`, el permiso se concede. La consultan [`has_permission()`] y el acceso de las
/// rutas ([`Access::Permission`]).
///
/// # Ejemplo
///
/// ```rust,no_run
/// # use pagetop::prelude::*;
/// fn check_my_permissions(request: &HttpRequest, perm: PermissionRef, granted: &mut bool) {
/// // Leer los datos extendidos de autenticación inyectados en la petición.
/// // Comparar `perm.key()` contra el modelo propio.
/// // Si concede el permiso, asignar `*granted = true`.
/// }
///
/// pub struct MyAuth;
///
/// #[async_trait]
/// impl Extension for MyAuth {
/// fn actions(&self) -> Vec<ActionBox> {
/// actions![action::auth::CheckPermission::new(check_my_permissions)]
/// }
/// }
/// ```
pub struct CheckPermission {
f: FnActionCheckPerm,
weight: Weight,
}
impl ActionDispatcher for CheckPermission {
fn weight(&self) -> Weight {
self.weight
}
}
impl CheckPermission {
/// Permite [registrar](Extension::actions) una nueva acción [`FnActionCheckPerm`].
pub fn new(f: FnActionCheckPerm) -> Self {
CheckPermission { f, weight: 0 }
}
/// Opcional. Acciones con pesos más bajos se aplican antes. Se pueden usar valores negativos.
pub fn with_weight(mut self, value: Weight) -> Self {
self.weight = value;
self
}
/// Despacha las acciones hasta que una concede el permiso, y devuelve si alguna lo ha hecho.
#[inline]
pub(crate) fn dispatch(request: &HttpRequest, perm: PermissionRef) -> bool {
let mut granted = false;
try_dispatch_actions(|action: &Self| {
(action.f)(request, perm, &mut granted);
if granted {
ControlFlow::Break(())
} else {
ControlFlow::Continue(())
}
});
granted
}
}

View file

@ -0,0 +1,85 @@
use crate::prelude::*;
use super::FnActionDeclarePermissions;
/// Acción para declarar los permisos de una extensión en el catálogo de permisos.
///
/// Cada extensión añade una instancia en [`Extension::actions()`]. PageTop despacha todas al
/// arrancar, después de registrar las acciones y antes de inicializar las extensiones, y construye
/// el catálogo global ([`PermissionRegistry::global()`]). El texto y el grupo de cada permiso los
/// aporta el propio [`Permission`] ([`label()`], [`group()`] y [`group_label()`]).
///
/// Declarar un permiso no lo concede a nadie: sólo lo da a conocer, para que una extensión de
/// autenticación pueda ofrecerlo (p. ej. en una pantalla de asignación de permisos a roles). Sin
/// ninguna, el permiso existe en el catálogo pero [`has_permission()`] lo deniega siempre.
///
/// Un permiso que exige una ruta ([`Access::Permission`]) o una pieza del panel de administración
/// sin estar declarado se avisa en las trazas al arrancar: nadie podría concederlo desde una
/// pantalla así.
///
/// # Ejemplo
///
/// ```rust,no_run
/// # use pagetop::prelude::*;
/// #[derive(Clone, Copy, Debug)]
/// enum MyPermission {
/// DoSomething,
/// }
///
/// impl Permission for MyPermission {
/// fn key(&self) -> CowStr {
/// match self {
/// Self::DoSomething => "myext:do_something".into(),
/// }
/// }
/// }
///
/// fn declare_permissions(registry: &mut PermissionRegistry) {
/// registry.register(&MyPermission::DoSomething);
/// }
///
/// pub struct MyExtension;
///
/// #[async_trait]
/// impl Extension for MyExtension {
/// fn actions(&self) -> Vec<ActionBox> {
/// actions![action::auth::DeclarePermissions::new(declare_permissions)]
/// }
/// }
/// ```
///
/// [`label()`]: Permission::label
/// [`group()`]: Permission::group
/// [`group_label()`]: Permission::group_label
pub struct DeclarePermissions {
f: FnActionDeclarePermissions,
weight: Weight,
}
impl ActionDispatcher for DeclarePermissions {
fn weight(&self) -> Weight {
self.weight
}
}
impl DeclarePermissions {
/// Permite [registrar](Extension::actions) una nueva acción [`FnActionDeclarePermissions`].
pub fn new(f: FnActionDeclarePermissions) -> Self {
DeclarePermissions { f, weight: 0 }
}
/// Opcional. Acciones con pesos más bajos se aplican antes. Se pueden usar valores negativos.
///
/// Determina el orden de registro en el catálogo y, con él, el de los permisos de un mismo
/// grupo en [`PermissionRegistry::by_group()`].
pub fn with_weight(mut self, value: Weight) -> Self {
self.weight = value;
self
}
/// Despacha las acciones sobre el catálogo que se está construyendo.
#[inline]
pub(crate) fn dispatch(registry: &mut PermissionRegistry) {
dispatch_actions(|action: &Self| (action.f)(registry));
}
}