derive per-agent egress entries from operator-linked accounts

swarm-wire/src/egress_allow.rs

@@ -45,11 +45,48 @@ pub struct Entry {
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub agent: Option<String>,
     /// The controller derived this entry from the agent's backend environment
-    /// and replaces it whenever that changes; an operator can neither add nor
-    /// remove one. A hive renders it like any other entry, and a reader that
-    /// predates the field ignores it.
+    /// or a linked account and replaces it whenever that changes; an operator
+    /// can neither add nor remove one. A hive renders it like any other entry,
+    /// and a reader that predates the field ignores it.
     #[serde(default, skip_serializing_if = "std::ops::Not::not")]
     pub derived: bool,
+    /// What a derived entry follows: [`BACKEND_ENV_SOURCE`], or a name starting
+    /// with [`LINK_SOURCE_PREFIX`] for an account the operator linked. Absent
+    /// on an entry written before the field existed, which counts as
+    /// [`BACKEND_ENV_SOURCE`]. A reader that predates the field ignores it.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub source: Option<String>,
+}
+
+/// The [`Entry::source`] of an entry derived from the agent's backend
+/// environment.
+pub const BACKEND_ENV_SOURCE: &str = "backend-env";
+
+/// What the [`Entry::source`] of an entry derived from a linked account starts
+/// with: `link:github`, `link:matrix:<account>` or `link:forge:<label>`.
+pub const LINK_SOURCE_PREFIX: &str = "link:";
+
+impl Entry {
+    /// Whether the controller derived this entry from the agent's backend
+    /// environment, which an entry without a source counts as.
+    #[must_use]
+    pub fn from_backend_env(&self) -> bool {
+        self.derived
+            && self
+                .source
+                .as_deref()
+                .is_none_or(|s| s == BACKEND_ENV_SOURCE)
+    }
+
+    /// Whether the controller derived this entry from a linked account.
+    #[must_use]
+    pub fn from_link(&self) -> bool {
+        self.derived
+            && self
+                .source
+                .as_deref()
+                .is_some_and(|s| s.starts_with(LINK_SOURCE_PREFIX))
+    }
 }
 
 /// The value under [`BUCKET`]/[`KEY`]. No `deny_unknown_fields`: a field a
@@ -229,11 +266,13 @@ mod tests {
                     domain: "github.com".to_owned(),
                     agent: None,
                     derived: false,
+                    source: None,
                 },
                 Entry {
                     domain: "crates.io".to_owned(),
                     agent: Some("atlas".to_owned()),
                     derived: false,
+                    source: None,
                 },
             ],
         };
@@ -255,6 +294,7 @@ mod tests {
             domain: "llm.example.com".to_owned(),
             agent: Some("atlas".to_owned()),
             derived: true,
+            source: None,
         };
         let wire = r#"{"domain":"llm.example.com","agent":"atlas","derived":true}"#;
         assert_eq!(serde_json::to_string(&derived).unwrap(), wire);
@@ -265,4 +305,32 @@ mod tests {
         assert!(!manual.derived);
         assert_eq!(manual.domain, "a.io");
     }
+
+    #[test]
+    fn a_source_round_trips_and_an_entry_without_one_is_from_the_backend_env() {
+        let entry = |source: Option<&str>| Entry {
+            domain: "github.com".to_owned(),
+            agent: Some("atlas".to_owned()),
+            derived: true,
+            source: source.map(str::to_owned),
+        };
+        let linked = entry(Some("link:github"));
+        let wire =
+            r#"{"domain":"github.com","agent":"atlas","derived":true,"source":"link:github"}"#;
+        assert_eq!(serde_json::to_string(&linked).unwrap(), wire);
+        assert_eq!(serde_json::from_str::<Entry>(wire).unwrap(), linked);
+        assert!(linked.from_link() && !linked.from_backend_env());
+
+        assert!(entry(None).from_backend_env() && !entry(None).from_link());
+        assert!(entry(Some(BACKEND_ENV_SOURCE)).from_backend_env());
+        // A source this build does not know belongs to neither.
+        let other = entry(Some("later:x"));
+        assert!(!other.from_backend_env() && !other.from_link());
+        // Only a derived entry has a source.
+        let manual = Entry {
+            derived: false,
+            ..entry(Some("link:github"))
+        };
+        assert!(!manual.from_backend_env() && !manual.from_link());
+    }
 }