shell_tunnel/security/
capability.rs

1//! Capability set — the frozen access-control *mechanism* (Phase A wire contract v1).
2//!
3//! A token carries a **set** of capability strings. A route declares a
4//! **required-capability**; an access decision is a **set-membership** check.
5//! The literal `"*"` is a **wildcard** that satisfies every capability check.
6//!
7//! Only this *mechanism* is contractual (frozen). The capability *vocabulary*
8//! (which strings exist, e.g. `exec`, `session.read`) and role *presets* are
9//! **non-contract** and grow additively — new strings may be added, but renaming,
10//! removing, or tightening an existing string is breaking. See the Phase A spec.
11
12use std::collections::HashSet;
13
14/// The wildcard capability: a token holding it passes every capability check.
15pub const WILDCARD: &str = "*";
16
17/// An unordered set of capability strings held by a token.
18///
19/// Access control is pure set membership with a single special case: the
20/// [`WILDCARD`] string satisfies any required capability.
21#[derive(Debug, Clone, Default, PartialEq, Eq)]
22pub struct CapabilitySet(HashSet<String>);
23
24impl CapabilitySet {
25    /// Create an empty capability set (holds no capabilities).
26    pub fn new() -> Self {
27        Self(HashSet::new())
28    }
29
30    /// Create a wildcard set — satisfies **every** capability check.
31    ///
32    /// This is the set held by the `full-control` preset and the legacy-key
33    /// mapping target (spec §4).
34    pub fn wildcard() -> Self {
35        let mut set = HashSet::new();
36        set.insert(WILDCARD.to_string());
37        Self(set)
38    }
39
40    /// Whether this set **satisfies** `required` — either it holds the wildcard,
41    /// or it directly contains the required capability string.
42    ///
43    /// This is the frozen access-decision primitive (spec §2.1).
44    pub fn satisfies(&self, required: &str) -> bool {
45        self.0.contains(WILDCARD) || self.0.contains(required)
46    }
47
48    /// Whether this set holds the wildcard capability.
49    pub fn is_wildcard(&self) -> bool {
50        self.0.contains(WILDCARD)
51    }
52
53    /// Insert a capability string into the set.
54    pub fn insert(&mut self, capability: impl Into<String>) {
55        self.0.insert(capability.into());
56    }
57
58    /// Number of capability strings in the set.
59    pub fn len(&self) -> usize {
60        self.0.len()
61    }
62
63    /// Whether the set holds no capabilities.
64    pub fn is_empty(&self) -> bool {
65        self.0.is_empty()
66    }
67
68    /// Iterate over the capability strings.
69    pub fn iter(&self) -> impl Iterator<Item = &String> {
70        self.0.iter()
71    }
72}
73
74impl<S: Into<String>> FromIterator<S> for CapabilitySet {
75    fn from_iter<I: IntoIterator<Item = S>>(iter: I) -> Self {
76        Self(iter.into_iter().map(Into::into).collect())
77    }
78}
79
80/// Resolve a role **preset** name to its capability set (spec §6).
81///
82/// Presets are a **non-contract** convenience mapping — they may change freely
83/// and are not part of the frozen wire contract. Returns `None` for an unknown
84/// name so the caller can surface a clear error.
85pub fn preset(name: &str) -> Option<CapabilitySet> {
86    match name {
87        "operator" => Some(
88            ["exec", "session.read", "session.manage"]
89                .into_iter()
90                .collect(),
91        ),
92        "read-only" => Some(["session.read"].into_iter().collect()),
93        "full-control" => Some(CapabilitySet::wildcard()),
94        _ => None,
95    }
96}
97
98#[cfg(test)]
99mod tests {
100    use super::*;
101
102    #[test]
103    fn test_empty_set_satisfies_nothing() {
104        let set = CapabilitySet::new();
105        assert!(set.is_empty());
106        assert!(!set.satisfies("exec"));
107        assert!(!set.is_wildcard());
108    }
109
110    #[test]
111    fn test_wildcard_satisfies_everything() {
112        let set = CapabilitySet::wildcard();
113        assert!(set.is_wildcard());
114        assert!(set.satisfies("exec"));
115        assert!(set.satisfies("session.read"));
116        assert!(set.satisfies("anything.at.all"));
117    }
118
119    #[test]
120    fn test_membership_is_exact() {
121        let set: CapabilitySet = ["session.read"].into_iter().collect();
122        assert!(set.satisfies("session.read"));
123        // Not a prefix/hierarchy match — membership is exact.
124        assert!(!set.satisfies("session.manage"));
125        assert!(!set.satisfies("session"));
126        assert!(!set.is_wildcard());
127    }
128
129    #[test]
130    fn test_multiple_capabilities() {
131        let set: CapabilitySet = ["exec", "session.read", "session.manage"]
132            .into_iter()
133            .collect();
134        assert_eq!(set.len(), 3);
135        assert!(set.satisfies("exec"));
136        assert!(set.satisfies("session.read"));
137        assert!(set.satisfies("session.manage"));
138        assert!(!set.satisfies("fs.read"));
139    }
140
141    #[test]
142    fn test_insert() {
143        let mut set = CapabilitySet::new();
144        set.insert("exec");
145        assert!(set.satisfies("exec"));
146        assert_eq!(set.len(), 1);
147    }
148
149    #[test]
150    fn test_presets() {
151        let operator = preset("operator").unwrap();
152        assert!(operator.satisfies("exec"));
153        assert!(operator.satisfies("session.read"));
154        assert!(operator.satisfies("session.manage"));
155        assert!(!operator.is_wildcard());
156
157        let read_only = preset("read-only").unwrap();
158        assert!(read_only.satisfies("session.read"));
159        assert!(!read_only.satisfies("session.manage"));
160        assert!(!read_only.satisfies("exec"));
161
162        let full = preset("full-control").unwrap();
163        assert!(full.is_wildcard());
164        assert!(full.satisfies("anything"));
165
166        assert!(preset("nonexistent").is_none());
167    }
168}
shell_tunnel/security/capability.rs

shell_tunnel/security/
capability.rs
