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}