modkit_security/
access_scope.rs

1use std::fmt;
2use uuid::Uuid;
3
4/// A scalar value for scope filtering.
5///
6/// Used in [`ScopeFilter`] predicates to represent typed values.
7/// JSON conversion happens at the PDP/PEP boundary (see the PEP compiler),
8/// not inside the security model.
9#[derive(Clone, Debug, PartialEq, Eq, Hash)]
10pub enum ScopeValue {
11    /// UUID value (tenant IDs, resource IDs, etc.)
12    Uuid(Uuid),
13    /// String value (status, GTS type IDs, etc.)
14    String(String),
15    /// Integer value.
16    Int(i64),
17    /// Boolean value.
18    Bool(bool),
19}
20
21impl ScopeValue {
22    /// Try to extract a UUID from this value.
23    ///
24    /// Returns `Some` for `ScopeValue::Uuid` directly, and for
25    /// `ScopeValue::String` if the string is a valid UUID.
26    #[must_use]
27    pub fn as_uuid(&self) -> Option<Uuid> {
28        match self {
29            Self::Uuid(u) => Some(*u),
30            Self::String(s) => Uuid::parse_str(s).ok(),
31            Self::Int(_) | Self::Bool(_) => None,
32        }
33    }
34}
35
36impl fmt::Display for ScopeValue {
37    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
38        match self {
39            Self::Uuid(u) => write!(f, "{u}"),
40            Self::String(s) => write!(f, "{s}"),
41            Self::Int(n) => write!(f, "{n}"),
42            Self::Bool(b) => write!(f, "{b}"),
43        }
44    }
45}
46
47impl From<Uuid> for ScopeValue {
48    #[inline]
49    fn from(u: Uuid) -> Self {
50        Self::Uuid(u)
51    }
52}
53
54impl From<&Uuid> for ScopeValue {
55    #[inline]
56    fn from(u: &Uuid) -> Self {
57        Self::Uuid(*u)
58    }
59}
60
61impl From<String> for ScopeValue {
62    #[inline]
63    fn from(s: String) -> Self {
64        Self::String(s)
65    }
66}
67
68impl From<&str> for ScopeValue {
69    #[inline]
70    fn from(s: &str) -> Self {
71        Self::String(s.to_owned())
72    }
73}
74
75impl From<i64> for ScopeValue {
76    #[inline]
77    fn from(n: i64) -> Self {
78        Self::Int(n)
79    }
80}
81
82impl From<bool> for ScopeValue {
83    #[inline]
84    fn from(b: bool) -> Self {
85        Self::Bool(b)
86    }
87}
88
89/// Well-known authorization property names.
90///
91/// These constants are shared between the PEP compiler and the ORM condition
92/// builder (`ScopableEntity::resolve_property()`), ensuring a single source of
93/// truth for property names.
94pub mod pep_properties {
95    /// Tenant-ownership property. Typically maps to the `tenant_id` column.
96    pub const OWNER_TENANT_ID: &str = "owner_tenant_id";
97
98    /// Resource identity property. Typically maps to the primary key column.
99    pub const RESOURCE_ID: &str = "id";
100
101    /// Owner (user) identity property. Typically maps to an `owner_id` column.
102    pub const OWNER_ID: &str = "owner_id";
103}
104
105/// A single scope filter — a typed predicate on a named resource property.
106///
107/// The property name (e.g., `"owner_tenant_id"`, `"id"`) is an authorization
108/// concept. Mapping to DB columns is done by `ScopableEntity::resolve_property()`.
109///
110/// Variants mirror the predicate types from the PDP response:
111/// - [`ScopeFilter::Eq`] — equality (`property = value`)
112/// - [`ScopeFilter::In`] — set membership (`property IN (values)`)
113///
114/// ## Future extensions
115///
116/// Additional filter types (`in_tenant_subtree`, `in_group`,
117/// `in_group_subtree`) are planned. See the authorization design document
118/// (`docs/arch/authorization/DESIGN.md`) for the full predicate taxonomy.
119#[derive(Clone, Debug, PartialEq, Eq)]
120pub enum ScopeFilter {
121    /// Equality: `property = value`.
122    Eq(EqScopeFilter),
123    /// Set membership: `property IN (values)`.
124    In(InScopeFilter),
125}
126
127/// Equality scope filter: `property = value`.
128#[derive(Clone, Debug, PartialEq, Eq, Hash)]
129pub struct EqScopeFilter {
130    /// Authorization property name (e.g., `pep_properties::OWNER_TENANT_ID`).
131    property: String,
132    /// The value to match.
133    value: ScopeValue,
134}
135
136/// Set membership scope filter: `property IN (values)`.
137#[derive(Clone, Debug, PartialEq, Eq)]
138pub struct InScopeFilter {
139    /// Authorization property name (e.g., `pep_properties::OWNER_TENANT_ID`).
140    property: String,
141    /// The set of values to match against.
142    values: Vec<ScopeValue>,
143}
144
145impl EqScopeFilter {
146    /// Create an equality scope filter.
147    #[must_use]
148    pub fn new(property: impl Into<String>, value: impl Into<ScopeValue>) -> Self {
149        Self {
150            property: property.into(),
151            value: value.into(),
152        }
153    }
154
155    /// The authorization property name.
156    #[inline]
157    #[must_use]
158    pub fn property(&self) -> &str {
159        &self.property
160    }
161
162    /// The filter value.
163    #[inline]
164    #[must_use]
165    pub fn value(&self) -> &ScopeValue {
166        &self.value
167    }
168}
169
170impl InScopeFilter {
171    /// Create a set membership scope filter.
172    #[must_use]
173    pub fn new(property: impl Into<String>, values: Vec<ScopeValue>) -> Self {
174        Self {
175            property: property.into(),
176            values,
177        }
178    }
179
180    /// Create from an iterator of convertible values.
181    #[must_use]
182    pub fn from_values<V: Into<ScopeValue>>(
183        property: impl Into<String>,
184        values: impl IntoIterator<Item = V>,
185    ) -> Self {
186        Self {
187            property: property.into(),
188            values: values.into_iter().map(Into::into).collect(),
189        }
190    }
191
192    /// The authorization property name.
193    #[inline]
194    #[must_use]
195    pub fn property(&self) -> &str {
196        &self.property
197    }
198
199    /// The filter values.
200    #[inline]
201    #[must_use]
202    pub fn values(&self) -> &[ScopeValue] {
203        &self.values
204    }
205}
206
207impl ScopeFilter {
208    /// Create an equality filter (`property = value`).
209    #[must_use]
210    pub fn eq(property: impl Into<String>, value: impl Into<ScopeValue>) -> Self {
211        Self::Eq(EqScopeFilter::new(property, value))
212    }
213
214    /// Create a set membership filter (`property IN (values)`).
215    #[must_use]
216    pub fn r#in(property: impl Into<String>, values: Vec<ScopeValue>) -> Self {
217        Self::In(InScopeFilter::new(property, values))
218    }
219
220    /// Create a set membership filter from UUID values (convenience).
221    #[must_use]
222    pub fn in_uuids(property: impl Into<String>, uuids: Vec<Uuid>) -> Self {
223        Self::In(InScopeFilter::new(
224            property,
225            uuids.into_iter().map(ScopeValue::Uuid).collect(),
226        ))
227    }
228
229    /// The authorization property name.
230    #[must_use]
231    pub fn property(&self) -> &str {
232        match self {
233            Self::Eq(f) => f.property(),
234            Self::In(f) => f.property(),
235        }
236    }
237
238    /// Collect all values as a slice-like view for iteration.
239    ///
240    /// For `Eq`, returns a single-element slice; for `In`, returns the values slice.
241    #[must_use]
242    pub fn values(&self) -> ScopeFilterValues<'_> {
243        match self {
244            Self::Eq(f) => ScopeFilterValues::Single(&f.value),
245            Self::In(f) => ScopeFilterValues::Multiple(&f.values),
246        }
247    }
248
249    /// Extract filter values as UUIDs, skipping non-UUID entries.
250    ///
251    /// Useful when the caller knows the property holds UUID values
252    /// (e.g., `owner_tenant_id`, `id`).
253    #[must_use]
254    pub fn uuid_values(&self) -> Vec<Uuid> {
255        self.values()
256            .iter()
257            .filter_map(ScopeValue::as_uuid)
258            .collect()
259    }
260}
261
262/// Iterator adapter for [`ScopeFilter::values()`].
263///
264/// Provides a uniform way to iterate over filter values regardless of
265/// whether the filter is `Eq` (single value) or `In` (multiple values).
266#[derive(Clone, Debug)]
267pub enum ScopeFilterValues<'a> {
268    /// Single value from an `Eq` filter.
269    Single(&'a ScopeValue),
270    /// Multiple values from an `In` filter.
271    Multiple(&'a [ScopeValue]),
272}
273
274impl<'a> ScopeFilterValues<'a> {
275    /// Returns an iterator over the values.
276    #[must_use]
277    pub fn iter(&self) -> ScopeFilterValuesIter<'a> {
278        match self {
279            Self::Single(v) => ScopeFilterValuesIter::Single(Some(v)),
280            Self::Multiple(vs) => ScopeFilterValuesIter::Multiple(vs.iter()),
281        }
282    }
283
284    /// Returns `true` if any value matches the given predicate.
285    #[must_use]
286    pub fn contains(&self, value: &ScopeValue) -> bool {
287        self.iter().any(|v| v == value)
288    }
289}
290
291impl<'a> IntoIterator for ScopeFilterValues<'a> {
292    type Item = &'a ScopeValue;
293    type IntoIter = ScopeFilterValuesIter<'a>;
294
295    fn into_iter(self) -> Self::IntoIter {
296        self.iter()
297    }
298}
299
300impl<'a> IntoIterator for &ScopeFilterValues<'a> {
301    type Item = &'a ScopeValue;
302    type IntoIter = ScopeFilterValuesIter<'a>;
303
304    fn into_iter(self) -> Self::IntoIter {
305        self.iter()
306    }
307}
308
309/// Iterator over [`ScopeFilterValues`].
310pub enum ScopeFilterValuesIter<'a> {
311    /// Yields a single value.
312    Single(Option<&'a ScopeValue>),
313    /// Yields from a slice.
314    Multiple(std::slice::Iter<'a, ScopeValue>),
315}
316
317impl<'a> Iterator for ScopeFilterValuesIter<'a> {
318    type Item = &'a ScopeValue;
319
320    fn next(&mut self) -> Option<Self::Item> {
321        match self {
322            Self::Single(v) => v.take(),
323            Self::Multiple(iter) => iter.next(),
324        }
325    }
326}
327
328/// A conjunction (AND) of scope filters — one access path.
329///
330/// All filters within a constraint must match simultaneously for a row
331/// to be accessible via this path.
332#[derive(Clone, Debug, PartialEq)]
333pub struct ScopeConstraint {
334    filters: Vec<ScopeFilter>,
335}
336
337impl ScopeConstraint {
338    /// Create a new scope constraint from a list of filters.
339    #[must_use]
340    pub fn new(filters: Vec<ScopeFilter>) -> Self {
341        Self { filters }
342    }
343
344    /// The filters in this constraint (AND-ed together).
345    #[inline]
346    #[must_use]
347    pub fn filters(&self) -> &[ScopeFilter] {
348        &self.filters
349    }
350
351    /// Returns `true` if this constraint has no filters.
352    #[inline]
353    #[must_use]
354    pub fn is_empty(&self) -> bool {
355        self.filters.is_empty()
356    }
357}
358
359/// A disjunction (OR) of scope constraints defining what data is accessible.
360///
361/// Each constraint is an independent access path (OR-ed). Filters within a
362/// constraint are AND-ed. An unconstrained scope bypasses row-level filtering.
363///
364/// # Examples
365///
366/// ```
367/// use modkit_security::access_scope::{AccessScope, ScopeConstraint, ScopeFilter, pep_properties};
368/// use uuid::Uuid;
369///
370/// // deny-all (default)
371/// let scope = AccessScope::deny_all();
372/// assert!(scope.is_deny_all());
373///
374/// // single tenant
375/// let tid = Uuid::new_v4();
376/// let scope = AccessScope::for_tenant(tid);
377/// assert!(!scope.is_deny_all());
378/// assert!(scope.contains_uuid(pep_properties::OWNER_TENANT_ID, tid));
379/// ```
380#[derive(Clone, Debug, PartialEq)]
381pub struct AccessScope {
382    constraints: Vec<ScopeConstraint>,
383    unconstrained: bool,
384}
385
386impl Default for AccessScope {
387    /// Default is deny-all: no constraints and not unconstrained.
388    fn default() -> Self {
389        Self::deny_all()
390    }
391}
392
393impl AccessScope {
394    // ── Constructors ────────────────────────────────────────────────
395
396    /// Create an access scope from a list of constraints (OR-ed).
397    #[must_use]
398    pub fn from_constraints(constraints: Vec<ScopeConstraint>) -> Self {
399        Self {
400            constraints,
401            unconstrained: false,
402        }
403    }
404
405    /// Create an access scope with a single constraint.
406    #[must_use]
407    pub fn single(constraint: ScopeConstraint) -> Self {
408        Self::from_constraints(vec![constraint])
409    }
410
411    /// Create an "allow all" (unconstrained) scope.
412    ///
413    /// This represents a legitimate PDP decision with no row-level filtering.
414    /// Not a bypass — it's a valid authorization outcome.
415    #[must_use]
416    pub fn allow_all() -> Self {
417        Self {
418            constraints: Vec::new(),
419            unconstrained: true,
420        }
421    }
422
423    /// Create a "deny all" scope (no access).
424    #[must_use]
425    pub fn deny_all() -> Self {
426        Self {
427            constraints: Vec::new(),
428            unconstrained: false,
429        }
430    }
431
432    // ── Convenience constructors ────────────────────────────────────
433
434    /// Create a scope for a set of tenant IDs.
435    #[must_use]
436    pub fn for_tenants(ids: Vec<Uuid>) -> Self {
437        Self::single(ScopeConstraint::new(vec![ScopeFilter::in_uuids(
438            pep_properties::OWNER_TENANT_ID,
439            ids,
440        )]))
441    }
442
443    /// Create a scope for a single tenant ID.
444    #[must_use]
445    pub fn for_tenant(id: Uuid) -> Self {
446        Self::for_tenants(vec![id])
447    }
448
449    /// Create a scope for a set of resource IDs.
450    #[must_use]
451    pub fn for_resources(ids: Vec<Uuid>) -> Self {
452        Self::single(ScopeConstraint::new(vec![ScopeFilter::in_uuids(
453            pep_properties::RESOURCE_ID,
454            ids,
455        )]))
456    }
457
458    /// Create a scope for a single resource ID.
459    #[must_use]
460    pub fn for_resource(id: Uuid) -> Self {
461        Self::for_resources(vec![id])
462    }
463
464    // ── Accessors ───────────────────────────────────────────────────
465
466    /// The constraints in this scope (OR-ed).
467    #[inline]
468    #[must_use]
469    pub fn constraints(&self) -> &[ScopeConstraint] {
470        &self.constraints
471    }
472
473    /// Returns `true` if this scope is unconstrained (allow-all).
474    #[inline]
475    #[must_use]
476    pub fn is_unconstrained(&self) -> bool {
477        self.unconstrained
478    }
479
480    /// Returns `true` if this scope denies all access.
481    ///
482    /// A scope is deny-all when it is not unconstrained and has no constraints.
483    #[must_use]
484    pub fn is_deny_all(&self) -> bool {
485        !self.unconstrained && self.constraints.is_empty()
486    }
487
488    /// Collect all values for a given property across all constraints.
489    #[must_use]
490    pub fn all_values_for(&self, property: &str) -> Vec<&ScopeValue> {
491        let mut result = Vec::new();
492        for constraint in &self.constraints {
493            for filter in constraint.filters() {
494                if filter.property() == property {
495                    result.extend(filter.values());
496                }
497            }
498        }
499        result
500    }
501
502    /// Collect all UUID values for a given property across all constraints.
503    ///
504    /// Convenience wrapper — skips non-UUID values.
505    #[must_use]
506    pub fn all_uuid_values_for(&self, property: &str) -> Vec<Uuid> {
507        let mut result = Vec::new();
508        for constraint in &self.constraints {
509            for filter in constraint.filters() {
510                if filter.property() == property {
511                    result.extend(filter.uuid_values());
512                }
513            }
514        }
515        result
516    }
517
518    /// Check if any constraint has a filter matching the given property and value.
519    #[must_use]
520    pub fn contains_value(&self, property: &str, value: &ScopeValue) -> bool {
521        self.constraints.iter().any(|c| {
522            c.filters()
523                .iter()
524                .any(|f| f.property() == property && f.values().contains(value))
525        })
526    }
527
528    /// Check if any constraint has a filter matching the given property and UUID.
529    #[must_use]
530    pub fn contains_uuid(&self, property: &str, id: Uuid) -> bool {
531        self.contains_value(property, &ScopeValue::Uuid(id))
532    }
533
534    /// Check if any constraint references the given property.
535    #[must_use]
536    pub fn has_property(&self, property: &str) -> bool {
537        self.constraints
538            .iter()
539            .any(|c| c.filters().iter().any(|f| f.property() == property))
540    }
541}
542
543#[cfg(test)]
544#[cfg_attr(coverage_nightly, coverage(off))]
545mod tests {
546    use super::*;
547    use uuid::Uuid;
548
549    const T1: &str = "11111111-1111-1111-1111-111111111111";
550    const T2: &str = "22222222-2222-2222-2222-222222222222";
551
552    fn uid(s: &str) -> Uuid {
553        Uuid::parse_str(s).unwrap()
554    }
555
556    // --- ScopeFilter::Eq ---
557
558    #[test]
559    fn scope_filter_eq_constructor() {
560        let f = ScopeFilter::eq(pep_properties::OWNER_TENANT_ID, uid(T1));
561        assert_eq!(f.property(), pep_properties::OWNER_TENANT_ID);
562        assert!(matches!(f, ScopeFilter::Eq(_)));
563        assert!(f.values().contains(&ScopeValue::Uuid(uid(T1))));
564    }
565
566    #[test]
567    fn all_values_for_works_with_eq() {
568        let scope = AccessScope::single(ScopeConstraint::new(vec![ScopeFilter::eq(
569            pep_properties::OWNER_TENANT_ID,
570            uid(T1),
571        )]));
572        assert_eq!(
573            scope.all_uuid_values_for(pep_properties::OWNER_TENANT_ID),
574            &[uid(T1)]
575        );
576    }
577
578    #[test]
579    fn all_values_for_works_with_mixed_eq_and_in() {
580        let scope = AccessScope::from_constraints(vec![
581            ScopeConstraint::new(vec![ScopeFilter::eq(
582                pep_properties::OWNER_TENANT_ID,
583                uid(T1),
584            )]),
585            ScopeConstraint::new(vec![ScopeFilter::in_uuids(
586                pep_properties::OWNER_TENANT_ID,
587                vec![uid(T2)],
588            )]),
589        ]);
590        let values = scope.all_uuid_values_for(pep_properties::OWNER_TENANT_ID);
591        assert_eq!(values, &[uid(T1), uid(T2)]);
592    }
593
594    #[test]
595    fn contains_value_works_with_eq() {
596        let scope = AccessScope::single(ScopeConstraint::new(vec![ScopeFilter::eq(
597            pep_properties::OWNER_TENANT_ID,
598            uid(T1),
599        )]));
600        assert!(scope.contains_uuid(pep_properties::OWNER_TENANT_ID, uid(T1)));
601        assert!(!scope.contains_uuid(pep_properties::OWNER_TENANT_ID, uid(T2)));
602    }
603}
modkit_security/access_scope.rs

modkit_security/
access_scope.rs
