systemprompt_security/policy/
types.rs

1//! Shared types for the unified governance plane.
2//!
3//! These types support the governance chain ([`super::GovernancePolicy`]) and
4//! feed into the typed deny variants in [`crate::authz::types::DenyReason`].
5//! They live here (and not in `authz/types.rs`) because they describe the
6//! *governed-call* enforcement plane — secret scans, scope checks, blocklists,
7//! rate limits — which is orthogonal to the user→entity allow/deny resolver.
8//! What a governed call targets and carries lives in [`super::governed`].
9//!
10//! Copyright (c) systemprompt.io — Business Source License 1.1.
11//! See <https://systemprompt.io> for licensing details.
12
13use std::fmt;
14use std::str::FromStr;
15
16use serde::{Deserialize, Serialize};
17use systemprompt_identifiers::{CallId, PolicyId, SessionId, UserId};
18
19use super::governed::{GovernedInput, GovernedTarget};
20use crate::authz::error::AuthzError;
21use crate::authz::types::Decision;
22
23/// Where in a governed payload a secret-scanner finding was located.
24///
25/// [`GovernedInput::location_kind`] supplies `kind` for the governance chain,
26/// and `redacted` must already have the credential removed — it is rendered
27/// into [`crate::authz::types::DenyReason`] and reaches the audit log.
28#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
29pub struct SecretLocation {
30    pub kind: String,
31    pub path: String,
32    pub redacted: String,
33}
34
35impl SecretLocation {
36    pub fn new(
37        kind: impl Into<String>,
38        path: impl Into<String>,
39        redacted: impl Into<String>,
40    ) -> Self {
41        Self {
42            kind: kind.into(),
43            path: path.into(),
44            redacted: redacted.into(),
45        }
46    }
47}
48
49impl fmt::Display for SecretLocation {
50    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
51        if self.path.is_empty() {
52            write!(f, "{} ({})", self.kind, self.redacted)
53        } else {
54            write!(f, "{}.{} ({})", self.kind, self.path, self.redacted)
55        }
56    }
57}
58
59#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
60pub struct RateLimitWindow {
61    pub name: String,
62    pub seconds: u64,
63    pub limit: u64,
64}
65
66/// Scope of an agent invocation for governance evaluation. Agents may run
67/// either inside an authenticated user session or under a system/service
68/// identity (cron, replay, internal scheduler).
69#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
70#[serde(tag = "kind", rename_all = "snake_case")]
71pub enum AgentScope {
72    User { user_id: UserId },
73    System,
74}
75
76impl AgentScope {
77    #[must_use]
78    pub const fn user_id(&self) -> Option<&UserId> {
79        match self {
80            Self::User { user_id } => Some(user_id),
81            Self::System => None,
82        }
83    }
84}
85
86/// Permission tier carried alongside [`AgentScope`] in [`PolicyContext`].
87///
88/// `AgentScope` answers "who is acting" (user vs system process identity);
89/// `AccessScope` answers "what permission tier is granted to this invocation"
90/// (admin, plain user, unknown). The two are orthogonal — a system actor may
91/// have any tier, a user actor may be admin or plain — so they live as
92/// separate fields rather than a cartesian enum. `Unknown` is the fallback when
93/// an agent card declares no `oauth.scopes` entry.
94#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize, sqlx::Type)]
95#[sqlx(type_name = "TEXT", rename_all = "lowercase")]
96#[serde(rename_all = "lowercase")]
97pub enum AccessScope {
98    Admin,
99    User,
100    Unknown,
101}
102
103impl AccessScope {
104    #[must_use]
105    pub const fn as_str(self) -> &'static str {
106        match self {
107            Self::Admin => "admin",
108            Self::User => "user",
109            Self::Unknown => "unknown",
110        }
111    }
112}
113
114impl fmt::Display for AccessScope {
115    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
116        f.write_str(self.as_str())
117    }
118}
119
120impl FromStr for AccessScope {
121    type Err = AuthzError;
122
123    fn from_str(s: &str) -> Result<Self, Self::Err> {
124        match s {
125            "admin" => Ok(Self::Admin),
126            "user" => Ok(Self::User),
127            "unknown" | "" => Ok(Self::Unknown),
128            other => Err(AuthzError::Validation(format!(
129                "unknown access scope: {other}"
130            ))),
131        }
132    }
133}
134
135#[derive(Debug)]
136pub struct PolicyContext<'a> {
137    pub target: GovernedTarget,
138    pub agent_scope: AgentScope,
139    pub access_scope: AccessScope,
140    pub session_id: &'a SessionId,
141    pub user_id: &'a UserId,
142    pub input: &'a GovernedInput,
143    /// Identity of the logical call, stable across every evaluation of it.
144    ///
145    /// One call is legitimately evaluated more than once — an enforcement point
146    /// behind another still has to run the chain, because it is reachable by
147    /// callers that never passed the first. A policy that accumulates state
148    /// uses this to tell "the same call again" from "another call".
149    pub call_id: &'a CallId,
150}
151
152/// A unit of governance evaluation for one governed call — an MCP tool call or
153/// a submitted prompt, per [`PolicyContext::target`].
154///
155/// Implementations are pure-sync; auditing happens outside the chain.
156/// Traced first-deny-wins composition is provided by
157/// [`super::GovernanceEngine`].
158///
159/// `evaluate` must be **idempotent per [`PolicyContext::call_id`]**: evaluating
160/// one call twice yields the same [`Decision`] and leaves the same state behind
161/// as evaluating it once. A policy that counts calls therefore counts calls,
162/// not evaluations — the two diverge wherever enforcement points nest.
163pub trait GovernancePolicy: Send + Sync + fmt::Debug {
164    fn id(&self) -> PolicyId;
165    fn name(&self) -> &'static str;
166    fn description(&self) -> &'static str;
167    fn evaluate(&self, ctx: &PolicyContext<'_>) -> Decision;
168}
systemprompt_security/policy/types.rs

systemprompt_security/policy/
types.rs
