shell_tunnel/security/

capability.rs

//! Capability set — the frozen access-control *mechanism* (Phase A wire contract v1).
//!
//! A token carries a **set** of capability strings. A route declares a
//! **required-capability**; an access decision is a **set-membership** check.
//! The literal `"*"` is a **wildcard** that satisfies every capability check.
//!
//! Only this *mechanism* is contractual (frozen). The capability *vocabulary*
//! (which strings exist, e.g. `exec`, `session.read`) and role *presets* are
//! **non-contract** and grow additively — new strings may be added, but renaming,
//! removing, or tightening an existing string is breaking. See the Phase A spec.

use std::collections::HashSet;

/// The wildcard capability: a token holding it passes every capability check.
pub const WILDCARD: &str = "*";

/// An unordered set of capability strings held by a token.
///
/// Access control is pure set membership with a single special case: the
/// [`WILDCARD`] string satisfies any required capability.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct CapabilitySet(HashSet<String>);

impl CapabilitySet {
    /// Create an empty capability set (holds no capabilities).
    pub fn new() -> Self {
        Self(HashSet::new())
    }

    /// Create a wildcard set — satisfies **every** capability check.
    ///
    /// This is the set held by the `full-control` preset and the legacy-key
    /// mapping target (spec §4).
    pub fn wildcard() -> Self {
        let mut set = HashSet::new();
        set.insert(WILDCARD.to_string());
        Self(set)
    }

    /// Whether this set **satisfies** `required` — either it holds the wildcard,
    /// or it directly contains the required capability string.
    ///
    /// This is the frozen access-decision primitive (spec §2.1).
    pub fn satisfies(&self, required: &str) -> bool {
        self.0.contains(WILDCARD) || self.0.contains(required)
    }

    /// Whether this set holds the wildcard capability.
    pub fn is_wildcard(&self) -> bool {
        self.0.contains(WILDCARD)
    }

    /// Insert a capability string into the set.
    pub fn insert(&mut self, capability: impl Into<String>) {
        self.0.insert(capability.into());
    }

    /// Number of capability strings in the set.
    pub fn len(&self) -> usize {
        self.0.len()
    }

    /// Whether the set holds no capabilities.
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }

    /// Iterate over the capability strings.
    pub fn iter(&self) -> impl Iterator<Item = &String> {
        self.0.iter()
    }
}

impl<S: Into<String>> FromIterator<S> for CapabilitySet {
    fn from_iter<I: IntoIterator<Item = S>>(iter: I) -> Self {
        Self(iter.into_iter().map(Into::into).collect())
    }
}

/// Capability strings the router currently maps routes onto.
///
/// Vocabulary, not mechanism — additive by design (see the module header).
/// `fs.read` and `fs.write` are deliberately absent from the `operator` and
/// `read-only` presets, but what that buys differs sharply between the two,
/// and it is worth being exact rather than claiming a boundary twice:
///
/// - `read-only` holds `session.read` and **no `exec`**, so withholding
///   `fs.read` is a real containment boundary: such a token genuinely cannot
///   read a file on this machine, and adding `fs.read` to the preset would
///   have granted an access it did not have.
/// - `operator` holds `exec`. A token that can run commands can already read
///   and write anything the process can reach — `Get-Content`, `cp`, a
///   redirect. Withholding `fs.*` there contains **nothing**; it keeps an
///   issued token's capability surface from changing under it, which is a
///   least-surprise property, not a security one. Do not describe it as
///   confinement.
///
/// `full-control`'s [`CapabilitySet::wildcard`] covers both, as it does every
/// capability — there is no way to keep such a token from the file API once
/// `--fs-root` is set, and no reason to try, since `exec` already dominates it.
///
/// The practical consequence: `--fs-root` is a meaningful jail only for a
/// token that has `fs.*` **without** `exec` (`--capabilities fs.write` for a
/// deploy push, say). Against `operator` or `full-control` it is a convenience
/// boundary — chunked, resumable, checksummed transfer instead of piping bytes
/// through a command — not a containment one.
pub const KNOWN_CAPABILITIES: &[&str] = &[
    "exec",
    "session.read",
    "session.manage",
    "fs.read",
    "fs.write",
];

/// Resolve a role **preset** name to its capability set (spec §6).
///
/// Presets are a **non-contract** convenience mapping — they may change freely
/// and are not part of the frozen wire contract. Returns `None` for an unknown
/// name so the caller can surface a clear error.
pub fn preset(name: &str) -> Option<CapabilitySet> {
    match name {
        // `fs.read`/`fs.write` sit alongside `exec` here rather than being
        // withheld from it: this preset already grants command execution, which
        // reaches every file this process can. Withholding the file API from it
        // confined nothing and only pushed callers onto the slow path — see
        // `KNOWN_CAPABILITIES` above.
        "operator" => Some(
            [
                "exec",
                "session.read",
                "session.manage",
                "fs.read",
                "fs.write",
            ]
            .into_iter()
            .collect(),
        ),
        // Not given `fs.read`, and this one is a real boundary: `read-only`
        // has no `exec`, so a token holding it genuinely cannot read a file on
        // this machine. Adding it here would be a grant, not a convenience.
        "read-only" => Some(["session.read"].into_iter().collect()),
        "full-control" => Some(CapabilitySet::wildcard()),
        _ => None,
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_empty_set_satisfies_nothing() {
        let set = CapabilitySet::new();
        assert!(set.is_empty());
        assert!(!set.satisfies("exec"));
        assert!(!set.is_wildcard());
    }

    #[test]
    fn test_wildcard_satisfies_everything() {
        let set = CapabilitySet::wildcard();
        assert!(set.is_wildcard());
        assert!(set.satisfies("exec"));
        assert!(set.satisfies("session.read"));
        assert!(set.satisfies("anything.at.all"));
    }

    #[test]
    fn test_membership_is_exact() {
        let set: CapabilitySet = ["session.read"].into_iter().collect();
        assert!(set.satisfies("session.read"));
        // Not a prefix/hierarchy match — membership is exact.
        assert!(!set.satisfies("session.manage"));
        assert!(!set.satisfies("session"));
        assert!(!set.is_wildcard());
    }

    #[test]
    fn test_multiple_capabilities() {
        let set: CapabilitySet = ["exec", "session.read", "session.manage"]
            .into_iter()
            .collect();
        assert_eq!(set.len(), 3);
        assert!(set.satisfies("exec"));
        assert!(set.satisfies("session.read"));
        assert!(set.satisfies("session.manage"));
        assert!(!set.satisfies("fs.read"));
    }

    #[test]
    fn test_insert() {
        let mut set = CapabilitySet::new();
        set.insert("exec");
        assert!(set.satisfies("exec"));
        assert_eq!(set.len(), 1);
    }

    #[test]
    fn test_presets() {
        let operator = preset("operator").unwrap();
        assert!(operator.satisfies("exec"));
        assert!(operator.satisfies("session.read"));
        assert!(operator.satisfies("session.manage"));
        // Carried because `exec` above already reaches every file this process
        // can: withholding them confined nothing. Asserted rather than left
        // implicit so removing them again has to be a deliberate act.
        assert!(operator.satisfies("fs.read"));
        assert!(operator.satisfies("fs.write"));
        assert!(!operator.is_wildcard());

        let read_only = preset("read-only").unwrap();
        assert!(read_only.satisfies("session.read"));
        assert!(!read_only.satisfies("session.manage"));
        assert!(!read_only.satisfies("exec"));
        // The one preset where withholding the file API is a real boundary:
        // with no `exec`, this token has no other route to a file's contents.
        assert!(!read_only.satisfies("fs.read"));
        assert!(!read_only.satisfies("fs.write"));

        let full = preset("full-control").unwrap();
        assert!(full.is_wildcard());
        assert!(full.satisfies("anything"));

        assert!(preset("nonexistent").is_none());
    }
}