Skip to main content

scyph_abac/
error.rs

1//! ABAC error type definitions for `scyph-abac`.
2//!
3//! Defines [`AbacError`] — the unified error type for all attribute-based access control
4//! policy enforcement failures in `scyph-abac`.
5//!
6//! ## Error Hierarchy and HTTP Mapping
7//!
8//! | Variant | HTTP Status (via `AppError`) | Cause |
9//! |---------|------------------------------|-------|
10//! | `Forbidden` | 403 Forbidden | User attributes do not satisfy policy conditions |
11//! | `Unauthorized` | 401 Unauthorized | No authenticated principal provided |
12//! | `ValidationError` | 422 Unprocessable Entity | Policy attribute validation failed |
13//! | `Cedar` | 500 Internal Server Error | Cedar engine evaluation/parse error |
14//! | `Internal` | 500 Internal Server Error | Generic ABAC infrastructure failure |
15//!
16//! ## Conversion to `AppError`
17//!
18//! `AbacError` implements `From<AbacError> for AppError`, enabling seamless propagation
19//! with `?` in Axum handlers that return `Result<_, AppError>`:
20//!
21//! ```rust,ignore
22//! use scyph_abac::{AbacPolicy, AbacError, AuthUserEnforceExt};
23//! use scyph_core::{Action, AppError, ApiResponse};
24//!
25//! async fn get_document(user: AuthUser<AppClaims>, doc: Document) -> Result<ApiResponse<Document>, AppError> {
26//!     user.enforce::<DocumentPolicy>(&doc, Action::Read)?;  // AbacError -> AppError via ?
27//!     Ok(ApiResponse::ok(doc))
28//! }
29//! ```
30
31use scyph_core::{AppError, ErrorDetails};
32
33/// Error type for attribute-based access control policy evaluation in `scyph-abac`.
34#[derive(Debug, thiserror::Error)]
35pub enum AbacError {
36    /// Authenticated subject does not satisfy policy conditions for the requested resource/action.
37    #[error("Forbidden: {0}")]
38    Forbidden(String),
39
40    /// Missing or unauthenticated subject credentials.
41    #[error("Unauthorized: {0}")]
42    Unauthorized(String),
43
44    /// Structured validation failure for policy attributes or context inputs.
45    #[error("ABAC validation failed: {message}")]
46    ValidationError {
47        /// Summary validation failure message.
48        message: String,
49        /// Field-level policy attribute error details.
50        details: Vec<ErrorDetails>,
51    },
52
53    /// Cedar policy engine evaluation or schema error.
54    #[cfg(feature = "cedar")]
55    #[error("Cedar policy error: {0}")]
56    Cedar(#[from] crate::cedar::CedarError),
57
58    /// Internal or generic ABAC policy evaluation failure.
59    #[error("Internal ABAC error: {0}")]
60    Internal(String),
61}
62
63impl AbacError {
64    /// Constructs an [`AbacError::ValidationError`] with a summary message and field-level details.
65    pub fn validation(message: impl Into<String>, details: Vec<ErrorDetails>) -> Self {
66        Self::ValidationError {
67            message: message.into(),
68            details,
69        }
70    }
71}
72
73impl From<AbacError> for AppError {
74    /// Converts an [`AbacError`] into an RFC 7807 [`AppError`] response.
75    fn from(err: AbacError) -> Self {
76        match err {
77            AbacError::Forbidden(msg) => AppError::Forbidden(msg),
78            AbacError::Unauthorized(msg) => AppError::Unauthorized(msg),
79            AbacError::ValidationError { message, details } => {
80                AppError::ValidationError { message, details }
81            }
82            #[cfg(feature = "cedar")]
83            AbacError::Cedar(e) => AppError::internal(e.to_string()),
84            AbacError::Internal(msg) => AppError::internal(msg),
85        }
86    }
87}