Skip to main content

codync_network/
rules.rs

1//! Who on the other computers may write to this computer's agents. The receiving computer checks
2//! its own rules before it takes a letter, so none depends on the sender's goodwill: the first rule
3//! that matches decides, and with no rules every member may write (the default). A rule allows,
4//! denies, or lets the letter in under a ceiling (`auto`, `ask`): the app that takes it lets the
5//! agent act for it no more freely than that.
6
7use anyhow::{Result, bail};
8use serde::{Deserialize, Serialize};
9use std::fmt;
10use std::str::FromStr;
11
12/// Matches any computer or agent.
13pub const ANY: &str = "*";
14/// Enough for any one person's computers, and few enough to check on every letter.
15pub const MAX_RULES: usize = 100;
16
17/// What a sender may have an agent here do, the most trusted first (so the greater is the stricter).
18/// `Auto` and `Ask` are ceilings on how the agent works on the letter, never a way to work more
19/// freely than it is set to. Only an agent the app runs can be held to one, so a letter under a
20/// ceiling to any other agent is refused.
21#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
22#[serde(rename_all = "lowercase")]
23pub enum Access {
24    /// Taken as the agent is set to work.
25    Allow,
26    /// Taken; the agent does by itself only what it judges safe and asks its user about the rest.
27    Auto,
28    /// Taken; the agent asks its user before every change and command.
29    Ask,
30    Deny,
31}
32
33impl Access {
34    /// The level as a rule spells it.
35    pub fn word(self) -> &'static str {
36        match self {
37            Self::Allow => "allow",
38            Self::Auto => "auto",
39            Self::Ask => "ask",
40            Self::Deny => "deny",
41        }
42    }
43
44    /// Whether the agent has to be held to a ceiling for a letter at this level.
45    pub fn is_ceiling(self) -> bool {
46        matches!(self, Self::Auto | Self::Ask)
47    }
48}
49
50/// `deny *@server → *`: letters from `from_agent` on `from_computer` to `to_agent` here.
51#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
52#[serde(rename_all = "camelCase")]
53pub struct Rule {
54    /// A computer in the network, or `*`.
55    pub from_computer: String,
56    /// An agent on that computer, or `*`.
57    pub from_agent: String,
58    /// One of this computer's agents, or `*`.
59    pub to_agent: String,
60    pub access: Access,
61}
62
63impl Rule {
64    /// `from` is `agent@computer`, either side `*`, or `*` alone for anyone.
65    pub fn new(access: Access, from: &str, to: &str) -> Result<Self> {
66        let (from_agent, from_computer) = match from.trim() {
67            ANY => (ANY, ANY),
68            from => from.rsplit_once('@').ok_or_else(|| anyhow::anyhow!("from is agent@computer, or *"))?,
69        };
70        let rule = Self {
71            from_computer: from_computer.trim().into(),
72            from_agent: from_agent.trim().into(),
73            to_agent: to.trim().into(),
74            access,
75        };
76        rule.check()?;
77        Ok(rule)
78    }
79
80    fn check(&self) -> Result<()> {
81        // An agent's address name is up to 40 characters of any script, as long as a letter carries.
82        let parts = [
83            (&self.from_computer, 64),
84            (&self.from_agent, crate::wire::MAX_ADDRESS),
85            (&self.to_agent, crate::wire::MAX_ADDRESS),
86        ];
87        for (part, max) in parts {
88            if part.is_empty() || part.len() > max || part.contains(char::is_whitespace) {
89                bail!("each part of a rule is a name or *, without spaces");
90            }
91        }
92        Ok(())
93    }
94
95    fn matches(&self, computer: &str, agent: &str, to: &str) -> bool {
96        let fits = |pattern: &str, name: &str| pattern == ANY || pattern.eq_ignore_ascii_case(name);
97        fits(&self.from_computer, computer) && fits(&self.from_agent, agent) && fits(&self.to_agent, to)
98    }
99}
100
101impl fmt::Display for Rule {
102    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
103        write!(f, "{} {}@{} → {}", self.access.word(), self.from_agent, self.from_computer, self.to_agent)
104    }
105}
106
107impl FromStr for Access {
108    type Err = anyhow::Error;
109
110    fn from_str(s: &str) -> Result<Self> {
111        match s {
112            "allow" => Ok(Self::Allow),
113            "auto" => Ok(Self::Auto),
114            "ask" => Ok(Self::Ask),
115            "deny" => Ok(Self::Deny),
116            _ => bail!("a rule is allow, auto, ask or deny"),
117        }
118    }
119}
120
121/// Checks a whole list before it replaces the old one.
122pub fn check_all(rules: &[Rule]) -> Result<()> {
123    if rules.len() > MAX_RULES {
124        bail!("at most {MAX_RULES} rules");
125    }
126    rules.iter().try_for_each(Rule::check)
127}
128
129/// How `agent` on `computer` may write to `to` here: the first rule that matches decides, and
130/// without one `default` does.
131pub fn access(rules: &[Rule], default: Access, computer: &str, agent: &str, to: &str) -> Access {
132    rules.iter().find(|r| r.matches(computer, agent, to)).map_or(default, |r| r.access)
133}
134
135#[cfg(test)]
136mod tests {
137    use super::*;
138
139    fn rule(access: Access, from: &str, to: &str) -> Rule {
140        Rule::new(access, from, to).expect("a valid rule")
141    }
142
143    #[test]
144    fn the_first_match_decides_and_no_rules_allow_everyone() {
145        assert_eq!(access(&[], Access::Allow, "server", "lead", "reviewer"), Access::Allow);
146        assert_eq!(access(&[], Access::Auto, "server", "lead", "reviewer"), Access::Auto, "the app's default");
147        let rules = [rule(Access::Allow, "lead@server", "reviewer"), rule(Access::Deny, "*@server", "*")];
148        assert_eq!(access(&rules, Access::Allow, "server", "lead", "reviewer"), Access::Allow);
149        assert_eq!(
150            access(&rules, Access::Allow, "server", "lead", "coder"),
151            Access::Deny,
152            "only the reviewer was allowed"
153        );
154        assert_eq!(
155            access(&rules, Access::Allow, "Server", "other", "reviewer"),
156            Access::Deny,
157            "computer names ignore case"
158        );
159        assert_eq!(access(&rules, Access::Allow, "laptop", "lead", "coder"), Access::Allow, "no rule for the laptop");
160        assert_eq!(access(&[rule(Access::Deny, "*", "*")], Access::Allow, "laptop", "a", "b"), Access::Deny);
161    }
162
163    #[test]
164    fn a_rule_can_set_a_ceiling() {
165        let rules =
166            [rule(Access::Ask, "*@cloud", "*"), rule(Access::Auto, "*@mini", "*"), rule(Access::Allow, "*", "*")];
167        assert_eq!(access(&rules, Access::Allow, "cloud", "lead", "reviewer"), Access::Ask);
168        assert_eq!(access(&rules, Access::Allow, "mini", "lead", "reviewer"), Access::Auto);
169        assert_eq!(access(&rules, Access::Allow, "desk", "lead", "reviewer"), Access::Allow);
170        assert!(Access::Allow < Access::Auto && Access::Auto < Access::Ask && Access::Ask < Access::Deny);
171        assert!(Access::Auto.is_ceiling() && Access::Ask.is_ceiling() && !Access::Allow.is_ceiling());
172        assert_eq!("auto".parse::<Access>().expect("a level"), Access::Auto);
173        assert_eq!("ask".parse::<Access>().expect("a level"), Access::Ask);
174        assert_eq!(rules[0].to_string(), "ask *@cloud → *");
175        assert_eq!(serde_json::to_value(&rules[0]).expect("serializes")["access"], "ask");
176    }
177
178    #[test]
179    fn rules_read_and_show_like_addresses() {
180        let r = rule(Access::Deny, "*@server", "*");
181        assert_eq!((r.from_agent.as_str(), r.from_computer.as_str()), ("*", "server"));
182        assert_eq!(r.to_string(), "deny *@server → *");
183        assert!(Rule::new(Access::Allow, "lead", "x").is_err(), "a bare agent needs its computer");
184        assert!(Rule::new(Access::Allow, "a b@c", "x").is_err());
185        let long = "審".repeat(40);
186        assert!(Rule::new(Access::Allow, &format!("{long}@desk"), &long).is_ok(), "any script's address names");
187        assert!(check_all(&vec![r; MAX_RULES + 1]).is_err());
188        let json = serde_json::to_value(rule(Access::Allow, "lead@desk", "reviewer")).expect("serializes");
189        assert_eq!(json["access"], "allow");
190        assert_eq!(json["fromComputer"], "desk");
191    }
192}