swarm-secret-client: name the hive queue credential, and grant a hive its own kind

The agreement half of delivering the agent queue principal's client secret
through the store. No producer yet, so nothing writes this path — the unit
that does lands in the same PR, with the write grant it needs.

queue.rs is the sibling matrix.rs prescribes for a second kind of secret
rather than another field on a shared struct. Keyed per HIVE, not per agent:
the queue identity is minted once per hive at deploy time and says which hive
an agent belongs to, never which agent.

The client id rides with the secret for matrix.rs's stated reason — a
credential has to be reconstructable from the store alone, and deriving
`hive-<name>-agent` on the reading side is the split spelling the authelia
module warns denies every agent as a timeout.

policy.rs's render() takes the hive name now and emits a second, narrow
stanza for that hive's own path. The agent stanza is untouched: an agent's
path does not name its hive, so narrowing it still needs the enumeration
docs/trust-boundary/security.md rejects. A hive path does name its principal,
so scoping it costs nothing and drifts nowhere.

every_hive_gets_a_byte_identical_document is replaced rather than deleted.
Its surviving half is that the text is a function of the deploy-time name
alone, so a re-emission cannot drift; the new arms are that one hive's
document cannot reach another's path, and that a name which could close the
stanza is refused — live again now that a name reaches the document text.

Refs #3853

swarm-secret-client/src/queue.rs

@@ -0,0 +1,94 @@
+//! The queue agreement: where a hive's agent-container credential lives in the
+//! store, and what the object at that path holds.
+//!
+//! The sibling of [`crate::matrix`], and it differs from it in one way worth
+//! reading before using either: a matrix credential is keyed per **agent**,
+//! this one per **hive**. Agents are created at runtime, so the queue
+//! identity they present is minted once per hive at deploy time and says which
+//! hive an agent belongs to, never which agent.
+
+use serde::{Deserialize, Serialize};
+
+use crate::{
+    Error,
+    path::{Kind, principal_prefix},
+};
+
+/// The path holding the client secret that agent containers on `hive` present
+/// to the swarm queue.
+///
+/// # Errors
+/// [`Error::PathSegment`] when `hive` contains anything but `[A-Za-z0-9_-]`,
+/// which is what keeps one hive's name from addressing another hive's secret.
+pub fn agent_client_path(hive: &str) -> Result<String, Error> {
+    let prefix = principal_prefix(Kind::Hive, hive)?;
+    Ok(format!("{prefix}/queue/agent"))
+}
+
+/// What the path holds: the client secret, plus the client id it belongs to.
+///
+/// The id rides with the secret for the same reason the homeserver rides with
+/// a matrix token — a credential has to be reconstructable from the store
+/// alone. Deriving it on the reading side instead would mean spelling
+/// `hive-<name>-agent` in a second place, and the authelia module's own option
+/// says what a split spelling costs: every agent is denied as a timeout.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Credential {
+    /// The secret itself. Named to match [`crate::matrix::Credential::value`]
+    /// so a nix-side reader spells `bao kv get -field=value` for either kind.
+    pub value: String,
+
+    /// The OIDC client id the secret authenticates.
+    pub client_id: String,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn a_hive_name_lands_under_its_own_principal_prefix() {
+        assert_eq!(
+            agent_client_path("alpha").expect("a plain name is legal"),
+            "swarm/hives/alpha/queue/agent"
+        );
+    }
+
+    #[test]
+    fn a_traversal_in_the_hive_name_is_refused() {
+        let e = agent_client_path("../beta").expect_err("a traversal is not");
+        assert!(matches!(e, Error::PathSegment { kind: "hive", .. }), "{e}");
+    }
+
+    #[test]
+    fn two_hives_never_share_a_path() {
+        assert_ne!(
+            agent_client_path("alpha").expect("legal"),
+            agent_client_path("beta").expect("legal")
+        );
+    }
+
+    #[test]
+    fn the_object_round_trips_through_the_store_representation() {
+        let c = Credential {
+            value: "s3cr3t".to_owned(),
+            client_id: "hive-alpha-agent".to_owned(),
+        };
+        let json = serde_json::to_string(&c).expect("serialises");
+        assert_eq!(
+            serde_json::from_str::<Credential>(&json).expect("deserialises"),
+            c
+        );
+    }
+
+    #[test]
+    fn the_field_names_the_nix_reader_asks_for_are_the_ones_written() {
+        let json = serde_json::to_value(Credential {
+            value: "s3cr3t".to_owned(),
+            client_id: "hive-alpha-agent".to_owned(),
+        })
+        .expect("serialises");
+        assert_eq!(json["value"], "s3cr3t");
+        assert_eq!(json["client_id"], "hive-alpha-agent");
+    }
+}