agent capabilities live in a swarm KV record, set from swarmctl

An agent's capabilities move from the hive's meta repo
(`meta/capabilities.json`, injected as `HIVE_CAPABILITIES`) into the
`capabilities` field of its key in a new `agent-permissions` KV bucket,
which swarm-controller alone writes.

- swarm-queue-client: `agent_permissions` (bucket, key, `AgentPermissions`,
  direct-get read, the import subject and its wire types).
- swarm-controller: creates the bucket at start; `GET|PUT|DELETE
  /api/agents/{name}/permissions` (deny_unknown_fields and unknown
  capability ⇒ 422, duplicate ⇒ 400, agent must be declared by a hive);
  answers each hive's one-shot import, writing a key only where there is
  none and only for agents that hive's wanted state declares.
- swarmctl: `agent permissions get|set|clear`.
- swarm-nats-auth: a hive reads every key of the bucket and sends its
  import on its own subject; the controller subscribes to the imports and
  may answer them (`responses`).
- hive-c0re: reads each of its agents' keys every 30s into
  /var/lib/hyperhive/swarm-agent-permissions.json and restarts an agent,
  gracefully, when its capabilities change. Unset is the compiled-in
  default (ruth: manage_root_agent; everyone else: none). A failed read
  keeps the stored value. On first boot it seeds that file from
  meta/capabilities.json, sends the grants to the controller, and deletes
  the file once the controller answers.

Deleted: the capabilities.json reader/writer, `HIVE_CAPABILITIES` in the
rendered meta flake, ruth's capability seed, the capabilities half of the
permissions rebuild job (`PermPayload::Capabilities`/`Combined`), the
dashboard's capabilities table and `capabilities_changed` event, and the
now-unused `Capability::description`.

Part of #5170.

swarmctl/src/permissions.rs

@@ -0,0 +1,126 @@
+//! `swarmctl agent permissions` — the capabilities the swarm grants one
+//! agent, through swarm-controller's `/api/agents/{name}/permissions` routes.
+//!
+//! The hive running the agent reads its key every 30 seconds and restarts the
+//! agent, after its current turn, when its capabilities change. Unset leaves
+//! the agent on its hive's default; an empty list grants nothing.
+//!
+//! The shape below mirrors the controller's `Permissions`, for the reason
+//! [`crate::agent`]'s module doc gives. Capability names are checked by the
+//! controller, which answers 422 for one it does not know.
+
+use anyhow::{Context as _, Result};
+use serde::{Deserialize, Serialize};
+
+use crate::agent::{parse_ident, send};
+use crate::remote::Target;
+
+/// One agent's permissions; an absent field is not set at swarm level.
+#[derive(Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
+struct Permissions {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    capabilities: Option<Vec<String>>,
+}
+
+fn runtime() -> Result<tokio::runtime::Runtime> {
+    tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .context("starting a tokio runtime for the controller request")
+}
+
+/// The agent's permissions path. The name is checked first, so it cannot
+/// reshape the URI.
+fn member(agent: &str) -> Result<String> {
+    let agent = parse_ident(agent, "agent name")?;
+    Ok(format!("/api/agents/{agent}/permissions"))
+}
+
+/// Run `swarmctl agent permissions get`.
+pub(crate) fn get(target: &Target, agent: &str) -> Result<()> {
+    let uri = member(agent)?;
+    let stored: Permissions = runtime()?.block_on(send(
+        target,
+        hyper::Method::GET,
+        &uri,
+        None::<&()>,
+        "permissions-get",
+    ))?;
+    print!("{}", render(&stored));
+    Ok(())
+}
+
+/// Run `swarmctl agent permissions set`: store the given capabilities, which
+/// replace the agent's record whole.
+pub(crate) fn set(target: &Target, agent: &str, capabilities: Vec<String>) -> Result<()> {
+    let uri = member(agent)?;
+    let stored: Permissions = runtime()?.block_on(send(
+        target,
+        hyper::Method::PUT,
+        &uri,
+        Some(&with_capabilities(capabilities)),
+        "permissions-set",
+    ))?;
+    print!("{}", render(&stored));
+    Ok(())
+}
+
+/// The record granting `capabilities`. An empty name, as `--capabilities ''`
+/// gives, is dropped, so that spelling grants nothing.
+fn with_capabilities(capabilities: Vec<String>) -> Permissions {
+    Permissions {
+        capabilities: Some(capabilities.into_iter().filter(|c| !c.is_empty()).collect()),
+    }
+}
+
+/// Run `swarmctl agent permissions clear`.
+pub(crate) fn clear(target: &Target, agent: &str) -> Result<()> {
+    let uri = member(agent)?;
+    runtime()?.block_on(send::<(), ()>(
+        target,
+        hyper::Method::DELETE,
+        &uri,
+        None,
+        "permissions-clear",
+    ))?;
+    println!("cleared; {agent} goes back to its hive's default");
+    Ok(())
+}
+
+fn render(p: &Permissions) -> String {
+    let caps = match p.capabilities.as_deref() {
+        None => "(not set; the hive's default)".to_owned(),
+        Some([]) => "(none)".to_owned(),
+        Some(caps) => caps.join(", "),
+    };
+    format!("capabilities: {caps}\n")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn get_tells_unset_from_none() {
+        let unset: Permissions = serde_json::from_str("{}").unwrap();
+        assert_eq!(
+            render(&unset),
+            "capabilities: (not set; the hive's default)\n"
+        );
+        let none: Permissions = serde_json::from_str(r#"{"capabilities":[]}"#).unwrap();
+        assert_eq!(render(&none), "capabilities: (none)\n");
+        let ruth: Permissions =
+            serde_json::from_str(r#"{"capabilities":["manage_root_agent"]}"#).unwrap();
+        assert_eq!(render(&ruth), "capabilities: manage_root_agent\n");
+    }
+
+    /// `--capabilities ''` stores an empty list, not one empty name.
+    #[test]
+    fn an_empty_list_flag_grants_nothing() {
+        let set = with_capabilities(vec![String::new()]);
+        assert_eq!(
+            serde_json::to_string(&set).unwrap(),
+            r#"{"capabilities":[]}"#
+        );
+    }
+}