swarm UI: show the accounts linked to each agent

GET /api/hives/{hive}/agents/{agent}/linked-accounts returns one row per
account linked to the agent, as kind, name and host: each matrix account
under swarm/agents/<agent>/matrix (with its homeserver, and the agent's own
`main` marked reserved), each forge label under swarm/agents/<agent>/forge
(with its url), and github when swarm/agents/<agent>/github-token exists
(host github.com, which is not stored). No credential field is in the
response type.

Listing those two directories needs a new controller grant: `list` on
secret/metadata/swarm/agents/+/matrix and .../+/forge only, pinned in
bao-grants.nix as the only metadata stanzas under agents/ beside the queue
revocation. Checked against a dev OpenBao 2.6.3: the grant lists those two
directories and is refused on agents/, agents/<agent>/, and a leaf.

The swarm UI agent detail panel shows all rows under "accounts"; the table
view's matrix column shows the matrix rows. The link badges stay.

Refs #4855

swarm-controller/src/linked_accounts.rs

@@ -0,0 +1,353 @@
+//! The accounts linked to one agent, as kind, name and host: what the swarm
+//! UI's agent panel lists.
+//!
+//! Read from the paths [`crate::matrix_account`], [`crate::forge_account`] and
+//! [`crate::github_account`] write, plus the agent's own `main` matrix account,
+//! which `matrix_account::agent_token` mints into the same directory. Each
+//! entry is read for its host and nothing else leaves this module:
+//! [`LinkedAccount`] has no field a credential could land in.
+//!
+//! Naming the matrix accounts and forge labels takes `list` on each agent's
+//! `matrix` and `forge` metadata directories, which `controllerPolicyText` in
+//! `nix/host-modules/swarm-bao.nix` grants on those two directories alone.
+
+use std::future::Future;
+
+use axum::Json;
+use axum::extract::State;
+use axum::http::StatusCode;
+use serde::Serialize;
+use serde::de::DeserializeOwned;
+use swarm_secret_client::{Error, SecretStore, forge, github, matrix};
+use utoipa::ToSchema;
+
+use super::{AppState, error_problem, swarm_hive};
+
+/// The host shown for a GitHub token. The store keeps none: a token is only
+/// ever used against github.com.
+const GITHUB_HOST: &str = "github.com";
+
+/// Which kind of account a [`LinkedAccount`] is.
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, ToSchema)]
+#[serde(rename_all = "snake_case")]
+pub enum AccountKind {
+    Matrix,
+    Forgejo,
+    Github,
+}
+
+/// One account linked to an agent. Never carries the credential.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, ToSchema)]
+pub struct LinkedAccount {
+    kind: AccountKind,
+    /// The matrix account name, the forge label, or `github`.
+    #[schema(example = "main")]
+    name: String,
+    /// The matrix homeserver, the forge base URL, or `github.com`. `None` for a
+    /// matrix account stored without a homeserver.
+    #[schema(example = "https://matrix.example.org")]
+    host: Option<String>,
+    /// The agent's own matrix account, which the swarm mints and an operator
+    /// does not link.
+    reserved: bool,
+}
+
+/// The store reads a listing makes, so a test can stand in for the store.
+pub(crate) trait AccountStore {
+    /// As [`SecretStore::list`].
+    fn list(&self, dir: &str) -> impl Future<Output = Result<Vec<String>, Error>> + Send;
+
+    /// As [`SecretStore::read_optional`].
+    fn read_optional<T: DeserializeOwned + Send>(
+        &self,
+        path: &str,
+    ) -> impl Future<Output = Result<Option<T>, Error>> + Send;
+}
+
+impl AccountStore for SecretStore {
+    async fn list(&self, dir: &str) -> Result<Vec<String>, Error> {
+        SecretStore::list(self, dir).await
+    }
+
+    async fn read_optional<T: DeserializeOwned + Send>(
+        &self,
+        path: &str,
+    ) -> Result<Option<T>, Error> {
+        SecretStore::read_optional(self, path).await
+    }
+}
+
+/// The object names directly under `dir`. A key ending in `/` is a directory
+/// below it, not an account.
+async fn objects(store: &impl AccountStore, dir: &str) -> Result<Vec<String>, Error> {
+    let keys = store.list(dir).await?;
+    Ok(keys.into_iter().filter(|k| !k.ends_with('/')).collect())
+}
+
+/// Every account the store holds for `agent`: matrix, then forgejo, then
+/// github.
+///
+/// A missing directory lists nothing, and a listed name whose object is gone
+/// gets no entry.
+///
+/// # Errors
+/// Anything [`SecretStore::list`] or [`SecretStore::read_optional`] does not
+/// treat as absence, such as a denial or an unreachable store, and an `agent`
+/// or listed name that is not a single path segment.
+pub(crate) async fn linked_accounts(
+    store: &impl AccountStore,
+    agent: &str,
+) -> Result<Vec<LinkedAccount>, Error> {
+    let mut out = Vec::new();
+
+    for name in objects(store, &matrix::accounts_dir(agent)?).await? {
+        let path = matrix::account_path(agent, &name)?;
+        if let Some(c) = store.read_optional::<matrix::Credential>(&path).await? {
+            out.push(LinkedAccount {
+                kind: AccountKind::Matrix,
+                reserved: crate::matrix_account::is_reserved_account(&name),
+                host: c.homeserver,
+                name,
+            });
+        }
+    }
+
+    for label in objects(store, &forge::accounts_dir(agent)?).await? {
+        let path = forge::account_path(agent, &label)?;
+        if let Some(a) = store.read_optional::<forge::Account>(&path).await? {
+            out.push(LinkedAccount {
+                kind: AccountKind::Forgejo,
+                name: label,
+                host: Some(a.url),
+                reserved: false,
+            });
+        }
+    }
+
+    let path = github::account_path(agent)?;
+    if store
+        .read_optional::<github::Credential>(&path)
+        .await?
+        .is_some()
+    {
+        out.push(LinkedAccount {
+            kind: AccountKind::Github,
+            name: "github".to_owned(),
+            host: Some(GITHUB_HOST.to_owned()),
+            reserved: false,
+        });
+    }
+
+    Ok(out)
+}
+
+/// List the accounts linked to an agent: names and hosts, never a credential.
+#[utoipa::path(
+    get,
+    path = "/api/hives/{hive}/agents/{agent}/linked-accounts",
+    params(
+        ("hive" = String, Path, description = "hive the agent runs on"),
+        ("agent" = String, Path, description = "agent whose accounts to list"),
+    ),
+    responses(
+        (status = 200, description = "the agent's linked accounts, empty when it has none", body = Vec<LinkedAccount>),
+        (status = 400, description = "the agent is not an identifier, or the hive is not in this swarm (problem+json)", body = String),
+        (status = 500, description = "the store could not be read (problem+json)", body = String),
+    ),
+    tag = "agents"
+)]
+pub async fn get_linked_accounts(
+    State(state): State<AppState>,
+    axum::extract::Path((hive, agent)): axum::extract::Path<(String, String)>,
+) -> Result<Json<Vec<LinkedAccount>>, problem_details::ProblemDetails> {
+    let hive = swarm_hive(&state, &hive).map_err(|(s, d)| error_problem(s, &d))?;
+    let agent = hive_types::Ident::parse(&agent)
+        .map_err(|reason| error_problem(StatusCode::BAD_REQUEST, reason))?
+        .into_string();
+
+    let store = crate::store::connect().await.map_err(|e| {
+        tracing::warn!(error = %e, "connecting to the swarm secret store failed");
+        error_problem(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string())
+    })?;
+    let accounts = linked_accounts(&store, &agent).await.map_err(|e| {
+        tracing::warn!(%hive, %agent, error = %e, "listing linked accounts failed");
+        error_problem(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string())
+    })?;
+    Ok(Json(accounts))
+}
+
+#[cfg(test)]
+mod tests {
+    use std::collections::BTreeMap;
+
+    use serde::de::DeserializeOwned;
+    use serde_json::{Value, json};
+    use swarm_secret_client::Error;
+
+    use super::{AccountKind, AccountStore, LinkedAccount, linked_accounts};
+
+    /// Objects by path. A list answers the next segment of every path under
+    /// the directory, with a trailing `/` when it goes deeper, as the store
+    /// does.
+    #[derive(Default)]
+    struct FakeStore {
+        objects: BTreeMap<String, Value>,
+        denied: bool,
+    }
+
+    impl FakeStore {
+        fn with(mut self, path: &str, object: Value) -> Self {
+            self.objects.insert(path.to_owned(), object);
+            self
+        }
+    }
+
+    impl AccountStore for FakeStore {
+        async fn list(&self, dir: &str) -> Result<Vec<String>, Error> {
+            if self.denied {
+                return Err(Error::MissingEnv("BAO_ADDR"));
+            }
+            let prefix = format!("{dir}/");
+            let mut keys: Vec<String> = self
+                .objects
+                .keys()
+                .filter_map(|p| p.strip_prefix(&prefix))
+                .map(|rest| match rest.split_once('/') {
+                    Some((head, _)) => format!("{head}/"),
+                    None => rest.to_owned(),
+                })
+                .collect();
+            keys.dedup();
+            Ok(keys)
+        }
+
+        async fn read_optional<T: DeserializeOwned + Send>(
+            &self,
+            path: &str,
+        ) -> Result<Option<T>, Error> {
+            if self.denied {
+                return Err(Error::MissingEnv("BAO_ADDR"));
+            }
+            Ok(self
+                .objects
+                .get(path)
+                .map(|v| serde_json::from_value(v.clone()).expect("fixture decodes")))
+        }
+    }
+
+    fn row(kind: AccountKind, name: &str, host: Option<&str>, reserved: bool) -> LinkedAccount {
+        LinkedAccount {
+            kind,
+            name: name.to_owned(),
+            host: host.map(str::to_owned),
+            reserved,
+        }
+    }
+
+    fn every_kind() -> FakeStore {
+        FakeStore::default()
+            .with(
+                "swarm/agents/atlas/matrix/main",
+                json!({"value": "t0k3n-main", "homeserver": "https://matrix.swarm"}),
+            )
+            .with(
+                "swarm/agents/atlas/matrix/catgirl",
+                json!({"value": "t0k3n-cat", "homeserver": "https://matrix.example.org"}),
+            )
+            .with(
+                "swarm/agents/atlas/matrix/old",
+                json!({"value": "t0k3n-old"}),
+            )
+            .with(
+                "swarm/agents/atlas/forge/codeberg",
+                json!({"value": "t0k3n-forge", "url": "https://codeberg.org"}),
+            )
+            .with(
+                "swarm/agents/atlas/github-token",
+                json!({"value": "t0k3n-gh"}),
+            )
+            // Another agent's accounts, and the agent's own forge token beside
+            // its `forge/` directory: neither is a linked account of atlas.
+            .with(
+                "swarm/agents/red/matrix/catgirl",
+                json!({"value": "t0k3n-red", "homeserver": "https://matrix.example.org"}),
+            )
+            .with(
+                "swarm/agents/atlas/forge-token",
+                json!({"value": "t0k3n-own", "name": "atlas"}),
+            )
+    }
+
+    #[tokio::test]
+    async fn every_kind_is_listed_with_its_name_and_host() {
+        let got = linked_accounts(&every_kind(), "atlas")
+            .await
+            .expect("store answers");
+        assert_eq!(
+            got,
+            vec![
+                row(
+                    AccountKind::Matrix,
+                    "catgirl",
+                    Some("https://matrix.example.org"),
+                    false
+                ),
+                row(
+                    AccountKind::Matrix,
+                    "main",
+                    Some("https://matrix.swarm"),
+                    true
+                ),
+                row(AccountKind::Matrix, "old", None, false),
+                row(
+                    AccountKind::Forgejo,
+                    "codeberg",
+                    Some("https://codeberg.org"),
+                    false
+                ),
+                row(AccountKind::Github, "github", Some("github.com"), false),
+            ]
+        );
+    }
+
+    #[tokio::test]
+    async fn the_response_carries_no_credential() {
+        let got = linked_accounts(&every_kind(), "atlas")
+            .await
+            .expect("store answers");
+        let body = serde_json::to_value(&got).expect("serialises");
+        for entry in body.as_array().expect("an array") {
+            let mut keys: Vec<&str> = entry
+                .as_object()
+                .expect("an object")
+                .keys()
+                .map(String::as_str)
+                .collect();
+            keys.sort_unstable();
+            assert_eq!(keys, ["host", "kind", "name", "reserved"], "{entry}");
+        }
+        let text = body.to_string();
+        assert!(!text.contains("value"), "{text}");
+        assert!(!text.contains("t0k3n"), "{text}");
+        // The control: the same serialisation does carry the names, so the
+        // absence above is not an empty body.
+        assert!(text.contains("catgirl"), "{text}");
+    }
+
+    #[tokio::test]
+    async fn an_agent_with_nothing_stored_lists_nothing() {
+        let got = linked_accounts(&FakeStore::default(), "atlas")
+            .await
+            .expect("absence is not an error");
+        assert!(got.is_empty(), "{got:?}");
+    }
+
+    #[tokio::test]
+    async fn a_store_that_refuses_is_an_error_not_an_empty_list() {
+        let store = FakeStore {
+            denied: true,
+            ..every_kind()
+        };
+        assert!(linked_accounts(&store, "atlas").await.is_err());
+    }
+}

swarm-controller/src/main.rs

@@ -51,6 +51,7 @@ mod forge;
 mod forge_account;
 mod github_account;
 mod issue_report;
+mod linked_accounts;
 mod matrix_account;
 mod otel_http_client;
 mod queue_identity;
@@ -2892,6 +2893,7 @@ fn build_app(state: AppState) -> axum::Router {
         .routes(routes!(matrix_account::put_matrix_account))
         .routes(routes!(forge_account::put_forge_account))
         .routes(routes!(github_account::put_github_account))
+        .routes(routes!(linked_accounts::get_linked_accounts))
         .routes(routes!(get_hive_wanted))
         .routes(routes!(term_stream::stream_agent_term))
         .routes(routes!(agent_state_stream::stream_agent_state))

swarm-controller/src/matrix_account.rs

@@ -194,9 +194,10 @@ pub async fn put_matrix_account(
 }
 
 /// Whether `account` is the agent's own account, which [`agent_token`] mints
-/// and `nix/agent-modules/matrix.nix` declares per agent — see the call site's
-/// own comment for why this route must never write one.
-fn is_reserved_account(account: &str) -> bool {
+/// and `nix/agent-modules/matrix.nix` declares per agent — see
+/// [`put_matrix_account`]'s comment on it for why that route must never write
+/// one.
+pub(crate) fn is_reserved_account(account: &str) -> bool {
     account == agent_token::ACCOUNT
 }