systemprompt_security/authz/types/
decision.rs

1//! Authorization decision types and structured deny reasons.
2//!
3//! Copyright (c) systemprompt.io — Business Source License 1.1.
4//! See <https://systemprompt.io> for licensing details.
5
6use std::borrow::Cow;
7use std::fmt;
8
9use serde::{Deserialize, Serialize};
10use systemprompt_identifiers::{McpToolName, PolicyId, SecretPatternId, UserId};
11use thiserror::Error;
12
13use super::entity_ref::EntityRef;
14use super::kinds::RuleType;
15use crate::policy::types::{AccessScope, RateLimitWindow, SecretLocation};
16
17/// Why an [`super::request::AuthzRequest`] was allowed. Carries enough
18/// structure for the audit row to attribute the decision without re-deriving
19/// it.
20#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
21#[serde(tag = "kind", rename_all = "snake_case")]
22pub enum MatchedBy {
23    UserAllow,
24    RoleAllow {
25        role: String,
26    },
27    AttributeAllow {
28        rule_type: RuleType,
29        value: String,
30    },
31    DefaultIncluded,
32    PolicyAllow {
33        policy_id: PolicyId,
34        detail: Cow<'static, str>,
35    },
36}
37
38/// Structured deny rationale.
39///
40/// Variants cover both the user→entity resolver
41/// (`UserDeny`, `RoleDeny`, `NotAssigned`, `UnknownEntity`),
42/// the hook plane (`HookUnavailable`), and the tool-use governance chain
43/// (`SecretLeak`, `ScopeViolation`, `ToolBlocked`, `RateLimitExceeded`). The
44/// human-readable `#[error]` strings double as the `reason` column in the
45/// `governance_decisions` audit row.
46#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Error)]
47#[serde(tag = "kind", rename_all = "snake_case")]
48pub enum DenyReason {
49    #[error("user {user_id} explicitly denied for {entity}")]
50    UserDeny {
51        entity: EntityRef,
52        user_id: UserId,
53        #[serde(default, skip_serializing_if = "Option::is_none")]
54        justification: Option<String>,
55    },
56    #[error("role {role} denied for {entity}")]
57    RoleDeny {
58        entity: EntityRef,
59        role: String,
60        #[serde(default, skip_serializing_if = "Option::is_none")]
61        justification: Option<String>,
62    },
63    #[error("{rule_type} {value} denied for {entity}")]
64    AttributeDeny {
65        entity: EntityRef,
66        rule_type: RuleType,
67        value: String,
68        #[serde(default, skip_serializing_if = "Option::is_none")]
69        justification: Option<String>,
70    },
71    #[error(
72        "{entity}: not assigned to user {user_id} with roles {roles:?} (no allow rule; \
73         default_included = false). Add an allow rule in services/access-control/roles.yaml."
74    )]
75    NotAssigned {
76        entity: EntityRef,
77        user_id: UserId,
78        roles: Vec<String>,
79    },
80    #[error(
81        "{entity}: unknown to access control. Add an entity row via the publish pipeline or \
82         roles.yaml."
83    )]
84    UnknownEntity { entity: EntityRef },
85    #[error("authz hook unavailable for policy {policy}")]
86    HookUnavailable { policy: String },
87    #[error("{detail}")]
88    PolicyViolation {
89        policy: String,
90        detail: Cow<'static, str>,
91    },
92    #[error("secret detected: {pattern_name} at {location}")]
93    SecretLeak {
94        pattern_id: SecretPatternId,
95        pattern_name: Cow<'static, str>,
96        location: SecretLocation,
97    },
98    #[error("tool {tool} requires {required} scope")]
99    ScopeViolation {
100        tool: McpToolName,
101        required: AccessScope,
102    },
103    #[error("tool {tool} blocked by list {list_id}")]
104    ToolBlocked { tool: McpToolName, list_id: String },
105    #[error("rate limit {window:?} exceeded; retry after {retry_after_ms}ms")]
106    RateLimitExceeded {
107        window: RateLimitWindow,
108        retry_after_ms: u64,
109    },
110}
111
112#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
113#[serde(tag = "decision", rename_all = "lowercase")]
114pub enum Decision {
115    Allow { matched_by: MatchedBy },
116    Deny { reason: DenyReason },
117}
118
119impl Decision {
120    #[must_use]
121    pub const fn tag(&self) -> DecisionTag {
122        match self {
123            Self::Allow { .. } => DecisionTag::Allow,
124            Self::Deny { .. } => DecisionTag::Deny,
125        }
126    }
127}
128
129/// Discriminant-only view of [`Decision`] / [`super::request::AuthzDecision`],
130/// bound to the `governance_decisions.decision` column.
131///
132/// Typing the column at the Rust boundary couples it to the SQL CHECK
133/// allow-list; adding a `Decision` variant without extending the constraint
134/// fails the build.
135#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, sqlx::Type)]
136#[sqlx(type_name = "TEXT", rename_all = "lowercase")]
137#[serde(rename_all = "lowercase")]
138pub enum DecisionTag {
139    Allow,
140    Deny,
141}
142
143impl DecisionTag {
144    #[must_use]
145    pub const fn as_str(self) -> &'static str {
146        match self {
147            Self::Allow => "allow",
148            Self::Deny => "deny",
149        }
150    }
151}
152
153impl fmt::Display for DecisionTag {
154    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
155        f.write_str(self.as_str())
156    }
157}
158
159impl From<&super::request::AuthzDecision> for DecisionTag {
160    fn from(d: &super::request::AuthzDecision) -> Self {
161        match d {
162            super::request::AuthzDecision::Allow => Self::Allow,
163            super::request::AuthzDecision::Deny { .. } => Self::Deny,
164        }
165    }
166}
systemprompt_security/authz/types/decision.rs

systemprompt_security/authz/types/
decision.rs
