systemprompt_security/authz/
resolver.rs

1//! Pure deny-overrides resolver with `user > … > role` specificity.
2//!
3//! Core ships two subject dimensions, `user` and `role`. Extensions declare
4//! their own — department, cost centre, clearance — as
5//! [`SubjectDimension`]s and pass them in via [`ResolveInput::dimensions`],
6//! with the user's values for them in [`ResolveInput::attributes`]. The
7//! precedence ladder is built per call from those two fields, so `resolve`
8//! learns no tenant vocabulary and stays pure. With no dimensions passed the
9//! ladder is exactly `user > role`, which is the pre-existing behaviour.
10//!
11//! The function is intentionally synchronous and free of I/O so it can be
12//! reused by the in-process [`super::rule_based::RuleBasedHook`], the
13//! template's webhook handler, and unit tests without setup. Callers fetch
14//! [`AccessRule`]s plus the `default_included` sentinel from
15//! [`super::repository::AccessControlRepository`] and pass them in.
16//!
17//! A declared ruleset is **authoritative and closed**: an entity that names its
18//! own roles is closed to every role it does not name, and only an entity with
19//! no rules of its own defers to its parents. This is what makes a narrow
20//! `roles: [admin]` grant restrictive even when the entity belongs to a group
21//! that is granted to everyone.
22//!
23//! `default_included` is `Option<bool>` — `None` signals the entity is
24//! unknown to access control (no row in `access_control_entities`), which
25//! the resolver turns into [`DenyReason::UnknownEntity`] rather than the
26//! generic `NotAssigned` deny. This distinction matters operationally: an
27//! unknown entity is a publish-pipeline gap, not a missing role grant.
28//!
29//! Copyright (c) systemprompt.io — Business Source License 1.1.
30//! See <https://systemprompt.io> for licensing details.
31
32use systemprompt_identifiers::UserId;
33
34use super::subject::{ROLE_PRECEDENCE, SubjectAttributes, SubjectDimension, USER_PRECEDENCE};
35use super::types::{Access, AccessRule, Decision, DenyReason, EntityRef, MatchedBy, RuleType};
36
37/// A parent entity whose rules cascade onto the child being resolved.
38///
39/// Parents are ordered nearest-first: the entity directly above the child
40/// comes before its grandparent, so a closer grant wins over a more distant
41/// one within the same precedence band.
42#[derive(Debug, Clone, Copy)]
43pub struct ResolveParent<'a> {
44    pub entity: &'a EntityRef,
45    pub rules: &'a [AccessRule],
46    pub default_included: Option<bool>,
47}
48
49/// Inputs to [`resolve`]. Bundled so the function stays under the clippy
50/// argument-count limit and so call sites can read top-to-bottom.
51#[derive(Debug, Clone, Copy)]
52pub struct ResolveInput<'a> {
53    pub entity: &'a EntityRef,
54    pub rules: &'a [AccessRule],
55    pub user_id: &'a UserId,
56    pub user_roles: &'a [String],
57    pub default_included: Option<bool>,
58    pub parents: &'a [ResolveParent<'a>],
59    /// The user's values for each extension-declared dimension, gathered by
60    /// [`gather_subject_attributes`][super::subject::gather_subject_attributes].
61    pub attributes: &'a SubjectAttributes,
62    /// Extension dimensions to interleave into the precedence ladder. Passed
63    /// in rather than read from the inventory so `resolve` stays pure and
64    /// unit-testable; pass `&[]` for core-only `user > role` behaviour.
65    pub dimensions: &'a [SubjectDimension],
66}
67
68/// Resolves a decision with parent inheritance on the crate-head deny-overrides
69/// model.
70///
71/// A child deny overrides a parent allow, a nearer rule overrides a farther one
72/// within the same precedence band, and a parent grant cascades to the child
73/// only when the child declares no rules at all — a child that declares any
74/// rule owns its decision and is closed to roles it does not name. An unknown
75/// child entity (`default_included == None`) yields
76/// [`DenyReason::UnknownEntity`] unless a rule or a parent's `default_included`
77/// grants access.
78#[must_use]
79pub fn resolve(input: ResolveInput<'_>) -> Decision {
80    let ResolveInput {
81        entity,
82        rules,
83        user_id,
84        user_roles,
85        default_included,
86        parents,
87        attributes,
88        dimensions,
89    } = input;
90
91    let ladder = ladder(dimensions);
92    let subject = Subject {
93        user_id,
94        user_roles,
95        attributes,
96        ladder: &ladder,
97    };
98
99    if let Some(decision) = match_ruleset(entity, rules, &subject) {
100        return decision;
101    }
102    let parents = if rules.is_empty() { parents } else { &[] };
103
104    for parent in parents {
105        if let Some(decision) = match_ruleset(parent.entity, parent.rules, &subject) {
106            return decision;
107        }
108    }
109
110    if default_included == Some(true) {
111        return Decision::Allow {
112            matched_by: MatchedBy::DefaultIncluded,
113        };
114    }
115    if parents
116        .iter()
117        .any(|parent| parent.default_included == Some(true))
118    {
119        return Decision::Allow {
120            matched_by: MatchedBy::DefaultIncluded,
121        };
122    }
123
124    if default_included.is_none() {
125        return Decision::Deny {
126            reason: DenyReason::UnknownEntity {
127                entity: entity.clone(),
128            },
129        };
130    }
131    Decision::Deny {
132        reason: DenyReason::NotAssigned {
133            entity: entity.clone(),
134            user_id: user_id.clone(),
135            roles: user_roles.to_vec(),
136        },
137    }
138}
139
140fn ladder(dimensions: &[SubjectDimension]) -> Vec<(RuleType, u16)> {
141    let mut bands = vec![
142        (RuleType::USER, USER_PRECEDENCE),
143        (RuleType::ROLE, ROLE_PRECEDENCE),
144    ];
145    bands.extend(
146        dimensions
147            .iter()
148            .filter(|d| d.rule_type != RuleType::USER && d.rule_type != RuleType::ROLE)
149            .map(|d| (d.rule_type.clone(), d.precedence)),
150    );
151    bands.sort_by_key(|&(_, precedence)| precedence);
152    bands
153}
154
155struct Subject<'a> {
156    user_id: &'a UserId,
157    user_roles: &'a [String],
158    attributes: &'a SubjectAttributes,
159    ladder: &'a [(RuleType, u16)],
160}
161
162impl Subject<'_> {
163    fn matches(&self, rule: &AccessRule) -> bool {
164        if rule.rule_type == RuleType::USER {
165            return rule.rule_value == self.user_id.as_str();
166        }
167        let held = if rule.rule_type == RuleType::ROLE {
168            self.user_roles
169        } else {
170            self.attributes.values(&rule.rule_type)
171        };
172        held.iter().any(|value| value == &rule.rule_value)
173    }
174}
175
176fn match_ruleset(
177    target: &EntityRef,
178    ruleset: &[AccessRule],
179    subject: &Subject<'_>,
180) -> Option<Decision> {
181    for (rule_type, _) in subject.ladder {
182        let in_band = |r: &&AccessRule| r.rule_type == *rule_type && subject.matches(r);
183
184        if let Some(rule) = ruleset
185            .iter()
186            .find(|r| in_band(r) && r.access == Access::Deny)
187        {
188            return Some(deny_for(target, subject, rule));
189        }
190        if let Some(rule) = ruleset
191            .iter()
192            .find(|r| in_band(r) && r.access == Access::Allow)
193        {
194            return Some(allow_for(rule));
195        }
196    }
197    None
198}
199
200fn deny_for(target: &EntityRef, subject: &Subject<'_>, rule: &AccessRule) -> Decision {
201    let reason = if rule.rule_type == RuleType::USER {
202        DenyReason::UserDeny {
203            entity: target.clone(),
204            user_id: subject.user_id.clone(),
205            justification: rule.justification.clone(),
206        }
207    } else if rule.rule_type == RuleType::ROLE {
208        DenyReason::RoleDeny {
209            entity: target.clone(),
210            role: rule.rule_value.clone(),
211            justification: rule.justification.clone(),
212        }
213    } else {
214        DenyReason::AttributeDeny {
215            entity: target.clone(),
216            rule_type: rule.rule_type.clone(),
217            value: rule.rule_value.clone(),
218            justification: rule.justification.clone(),
219        }
220    };
221    Decision::Deny { reason }
222}
223
224fn allow_for(rule: &AccessRule) -> Decision {
225    let matched_by = if rule.rule_type == RuleType::USER {
226        MatchedBy::UserAllow
227    } else if rule.rule_type == RuleType::ROLE {
228        MatchedBy::RoleAllow {
229            role: rule.rule_value.clone(),
230        }
231    } else {
232        MatchedBy::AttributeAllow {
233            rule_type: rule.rule_type.clone(),
234            value: rule.rule_value.clone(),
235        }
236    };
237    Decision::Allow { matched_by }
238}
systemprompt_security/authz/resolver.rs

systemprompt_security/authz/
resolver.rs
