systemprompt_security/authz/
subject.rs

1//! Extension-declared subject dimensions for the RBAC resolver.
2//!
3//! Core's resolver knows two subject dimensions, `user` and `role`. Anything
4//! else an operator wants to write rules against — department, cost centre,
5//! clearance, jurisdiction — is a tenant concept, and core deliberately does
6//! not learn it. What core provides instead is the mechanism:
7//!
8//! 1. An extension mints a [`RuleType`] with [`RuleType::extension`] and
9//!    describes it as a [`SubjectDimension`], choosing where it slots in the
10//!    precedence ladder.
11//! 2. It implements [`SubjectAttributeProvider`] to look up that dimension's
12//!    values for a user, and registers the provider with
13//!    [`register_subject_attribute_provider!
14//!    `][crate::register_subject_attribute_provider].
15//! 3. The enforcement path calls [`gather_subject_attributes`] once per request
16//!    and hands the resulting [`SubjectAttributes`] to
17//!    [`resolve`][super::resolver::resolve] alongside the dimension list.
18//!
19//! Values are resolved by lookup rather than read from JWT claims, so a
20//! department change or a revocation takes effect on the next request instead
21//! of lingering until the token refreshes.
22//!
23//! The split between metadata ([`SubjectDimension`], no behaviour) and
24//! behaviour ([`SubjectAttributeProvider`], async I/O) is what keeps
25//! [`resolve`][super::resolver::resolve] pure and synchronous: gathering is
26//! the only async step, and it happens before the resolver runs.
27//!
28//! Copyright (c) systemprompt.io — Business Source License 1.1.
29//! See <https://systemprompt.io> for licensing details.
30
31use std::collections::BTreeMap;
32use std::fmt::Debug;
33use std::sync::Arc;
34
35use async_trait::async_trait;
36use systemprompt_identifiers::UserId;
37
38use super::registry::AuthzHookContext;
39use super::types::RuleType;
40
41pub const USER_PRECEDENCE: u16 = 0;
42pub const ROLE_PRECEDENCE: u16 = 200;
43
44/// Describes one subject dimension to the resolver.
45///
46/// Metadata only: no behaviour and no I/O, so it is cheap to clone and safe to
47/// hold in a `const`.
48#[derive(Debug, Clone, PartialEq, Eq)]
49pub struct SubjectDimension {
50    pub rule_type: RuleType,
51    pub label: &'static str,
52    pub precedence: u16,
53}
54
55/// Subject values per dimension, gathered before the pure resolver runs.
56///
57/// A dimension with no values for the user is simply absent, which makes its
58/// rules unmatchable for that request.
59#[derive(Debug, Clone, Default, PartialEq, Eq)]
60pub struct SubjectAttributes(BTreeMap<RuleType, Vec<String>>);
61
62impl SubjectAttributes {
63    pub const EMPTY: Self = Self(BTreeMap::new());
64
65    #[must_use]
66    pub const fn new() -> Self {
67        Self::EMPTY
68    }
69
70    pub fn insert(&mut self, rule_type: RuleType, values: Vec<String>) {
71        self.0.insert(rule_type, values);
72    }
73
74    #[must_use]
75    pub fn values(&self, rule_type: &RuleType) -> &[String] {
76        self.0.get(rule_type).map_or(&[], Vec::as_slice)
77    }
78
79    #[must_use]
80    pub fn is_empty(&self) -> bool {
81        self.0.is_empty()
82    }
83}
84
85impl FromIterator<(RuleType, Vec<String>)> for SubjectAttributes {
86    fn from_iter<I: IntoIterator<Item = (RuleType, Vec<String>)>>(iter: I) -> Self {
87        Self(iter.into_iter().collect())
88    }
89}
90
91pub static NO_SUBJECT_ATTRIBUTES: SubjectAttributes = SubjectAttributes::EMPTY;
92
93/// Looks up the values a user holds for one extension-owned dimension.
94///
95/// `#[async_trait]` because providers are held as
96/// [`SharedSubjectAttributeProvider`], an `Arc<dyn …>`, so the trait must stay
97/// `dyn`-compatible.
98#[async_trait]
99pub trait SubjectAttributeProvider: Send + Sync + Debug {
100    fn dimension(&self) -> SubjectDimension;
101
102    async fn values_for(&self, user_id: &UserId) -> Result<Vec<String>, super::AuthzError>;
103}
104
105/// Shared handle to a registered provider.
106pub type SharedSubjectAttributeProvider = Arc<dyn SubjectAttributeProvider>;
107
108/// One inventory submission per
109/// [`register_subject_attribute_provider!
110/// `][crate::register_subject_attribute_provider] call. The factory runs once
111/// at `AppContext` build time and must not block.
112#[derive(Debug, Clone, Copy)]
113pub struct SubjectProviderRegistration {
114    pub factory: fn(&AuthzHookContext) -> SharedSubjectAttributeProvider,
115}
116
117inventory::collect!(SubjectProviderRegistration);
118
119#[must_use]
120pub fn discover_subject_providers(ctx: &AuthzHookContext) -> Vec<SharedSubjectAttributeProvider> {
121    inventory::iter::<SubjectProviderRegistration>()
122        .map(|reg| (reg.factory)(ctx))
123        .collect()
124}
125
126#[must_use]
127pub fn dimensions_of(providers: &[SharedSubjectAttributeProvider]) -> Vec<SubjectDimension> {
128    providers.iter().map(|p| p.dimension()).collect()
129}
130
131pub async fn gather_subject_attributes(
132    providers: &[SharedSubjectAttributeProvider],
133    user_id: &UserId,
134) -> Result<SubjectAttributes, super::AuthzError> {
135    let mut attributes = SubjectAttributes::new();
136    for provider in providers {
137        attributes.insert(
138            provider.dimension().rule_type,
139            provider.values_for(user_id).await?,
140        );
141    }
142    Ok(attributes)
143}
144
145#[macro_export]
146macro_rules! register_subject_attribute_provider {
147    ($factory:expr) => {
148        ::inventory::submit! {
149            $crate::authz::SubjectProviderRegistration {
150                factory: $factory,
151            }
152        }
153    };
154}
155
156/// The registered subject-attribute providers, discovered once at a
157/// composition root and shared by every consumer that needs to look a
158/// dimension up by name (gateway scope attribution, quota subjects).
159#[derive(Debug, Clone, Default)]
160pub struct SubjectProviderSet(Arc<[SharedSubjectAttributeProvider]>);
161
162impl SubjectProviderSet {
163    #[must_use]
164    pub fn discover(ctx: &AuthzHookContext) -> Self {
165        Self(discover_subject_providers(ctx).into())
166    }
167
168    #[must_use]
169    pub fn from_providers(providers: Vec<SharedSubjectAttributeProvider>) -> Self {
170        Self(providers.into())
171    }
172
173    #[must_use]
174    pub fn find(&self, dimension: &str) -> Option<&SharedSubjectAttributeProvider> {
175        self.0
176            .iter()
177            .find(|provider| provider.dimension().rule_type.as_str() == dimension)
178    }
179
180    #[must_use]
181    pub fn registered_dimensions(&self) -> Vec<RuleType> {
182        self.0.iter().map(|p| p.dimension().rule_type).collect()
183    }
184
185    pub fn iter(&self) -> impl Iterator<Item = &SharedSubjectAttributeProvider> {
186        self.0.iter()
187    }
188}
systemprompt_security/authz/subject.rs

systemprompt_security/authz/
subject.rs
