khive_gate/
error.rs

1use thiserror::Error;
2
3/// Validation error for gate wire types.
4///
5/// Returned by `try_new` constructors and custom `Deserialize` impls when
6/// invariants are violated (empty fields, zero rate-limit values).
7#[derive(Error, Debug, Clone, PartialEq, Eq)]
8pub enum GateValidationError {
9    #[error("actor kind must not be empty")]
10    EmptyActorKind,
11    #[error("actor id must not be empty")]
12    EmptyActorId,
13    #[error("verb must not be empty")]
14    EmptyVerb,
15    #[error("deny reason must not be empty")]
16    EmptyDenyReason,
17    #[error("audit tag must not be empty")]
18    EmptyAuditTag,
19    #[error("rate limit window_secs must be > 0")]
20    ZeroRateLimitWindow,
21    #[error("rate limit max must be > 0")]
22    ZeroRateLimitMax,
23}
24
25/// Errors returned by [`crate::Gate::check`].
26#[derive(Error, Debug)]
27pub enum GateError {
28    #[error("policy error: {0}")]
29    Policy(String),
30    #[error("internal gate error: {0}")]
31    Internal(String),
32    #[error("validation error: {0}")]
33    Validation(#[from] GateValidationError),
34}
35
36impl GateError {
37    /// Stable, caller-safe classification of this error's failure category.
38    ///
39    /// This is what a `Gate::check` caller is permitted to forward to an
40    /// untrusted requester. It never includes this error's `Display` text:
41    /// a gate backend's error message can embed connection details,
42    /// addresses, or credentials, and that text must stay in server-side
43    /// logs only (log the full error separately with its `Display` impl).
44    ///
45    /// `Internal` is a transient backend-availability failure — safe to
46    /// retry. `Policy` and `Validation` are non-transient: the gate backend
47    /// is reachable but the request or its configured policy cannot be
48    /// evaluated, and retrying the identical request will not change the
49    /// outcome.
50    pub fn wire_reason(&self) -> &'static str {
51        match self {
52            Self::Internal(_) => "gate backend unavailable",
53            Self::Policy(_) => "gate policy evaluation failed",
54            Self::Validation(_) => "gate request validation failed",
55        }
56    }
57}
58
59#[cfg(test)]
60mod wire_reason_tests {
61    use super::{GateError, GateValidationError};
62
63    #[test]
64    fn wire_reason_never_echoes_backend_display_text() {
65        let canary = "postgres://svc:not-a-real-secret@internal-host";
66        let error = GateError::Internal(canary.to_string());
67
68        assert!(!error.wire_reason().contains(canary));
69        assert_eq!(error.wire_reason(), "gate backend unavailable");
70    }
71
72    #[test]
73    fn policy_and_internal_classify_into_distinguishable_stable_text() {
74        let internal = GateError::Internal("connection refused".to_string());
75        let policy = GateError::Policy("rule set has no allow clause".to_string());
76        let validation = GateError::Validation(GateValidationError::EmptyVerb);
77
78        assert_eq!(internal.wire_reason(), "gate backend unavailable");
79        assert_eq!(policy.wire_reason(), "gate policy evaluation failed");
80        assert_eq!(validation.wire_reason(), "gate request validation failed");
81        assert_ne!(internal.wire_reason(), policy.wire_reason());
82        assert_ne!(policy.wire_reason(), validation.wire_reason());
83    }
84}
khive_gate/error.rs

khive_gate/
error.rs
