matrix: one sender account and one sender token per hive

A swarm runs one homeserver and every hive on it logged in as the same
`@hive:` localpart, holding the same access token out of one swarm-wide
store path. That is one matrix identity for N hives: the homeserver
cannot attribute an action to the hive that took it, and revoking one
hive's standing revokes every hive's.

Three changes, and the third is the one that makes the other two real:

- **The localpart carries the hive's name** (`hive-<hive>`), derived in
  one place, `swarm_secret_client::matrix::hive_localpart`.
  `hive-matrix.nix` renders the same string as the appservice
  registration's `sender_localpart`, so the shared account stops being
  created rather than merely stops being used.
- **The store path is templated by hive**, not a constant. The
  "a swarm runs one homeserver, so this is a constant rather than a
  parameter" rationale went with it; it stopped holding the moment two
  hives shared the homeserver it describes.
- **The path moved out from under the grant every hive has.** It sat at
  `swarm/services/matrix/sender-token`, inside the
  `secret/data/swarm/services/*` read stanza `policy::render` gives every
  hive. It now sits under that hive's own stanza,
  `secret/data/swarm/hives/<hive>/*`, which interpolates the reader's
  name — so a hive reads its own token and is refused another's. The
  policy renderer itself is unchanged: narrowing the `services/*` grant
  would break the OIDC-secret read it exists for, and moving the
  credential is what this needed instead. A policy test walks the
  rendered stanzas and asserts none of hive alpha's covers hive beta's
  sender token, so a later stanza that widened it fails here.

`swarm-matrix-ctl` takes a new required `MATRIX_MINT_HIVE` and writes
that hive's path; its store grant in `swarm-bao.nix` follows, scoped to
one hive's leaf via the new `deploy.bao.matrixCtlHiveName` (defaulting to
this host's `hiveName`) rather than a `hives/*` wildcard, which would
hand the matrix container every hive's token back.

Migration: no outage at deploy. `ensure_hive_user` short-circuits on the
local token file, so a hive keeps running on what it has; with no such
file it reads the new per-hive path, finds nothing, and falls through to
the existing register-or-appservice-login ladder against its own
localpart — which needs only the per-hive `as_token` on local disk. The
old shared object is read by nothing afterwards. Rooms do not follow the
identity, and that is the one operator step; both ways out are written
into `docs/integrations/matrix.md`.

No admin standing is granted to the per-hive accounts: `admin_execute`
stays empty and the assertion pinning it is untouched.

swarm-matrix-ctl/src/mint.rs

@@ -2,10 +2,12 @@
 //! homeserver access token to the swarm's secret store, once.
 //!
 //! A oneshot inside `containers.hive-matrix`, not a daemon and not part of the
-//! swarm controller. It is this account rather than an agent's because a
-//! homeserver has **one** appservice registration and so one sender account,
-//! and a swarm runs one homeserver: "only once" is a property of what is being
-//! minted, so there is nothing to lock and no trigger to serve.
+//! swarm controller. It mints for **one hive** — the hive this container runs
+//! on, named by [`ENV_HIVE`] — and publishes to that hive's own path, so a
+//! swarm whose hives share a homeserver gets one account and one token per
+//! hive rather than one shared between all of them. "Only once" is therefore
+//! once per hive, and it is still a property of what is being minted rather
+//! than of a lock: nothing else writes that path.
 //!
 //! The store, not the homeserver, is the idempotency key — see
 //! [`already_published`]. On the hive side `hive-c0re`'s
@@ -31,9 +33,15 @@ const ENV_API_URL: &str = "MATRIX_MINT_API_URL";
 /// The bind-mounted appservice registration, which is where the `as_token`
 /// comes from. A path, never a value.
 const ENV_REGISTRATION: &str = "MATRIX_MINT_REGISTRATION";
-/// Localpart of the appservice's sender account. The registration's own
-/// `sender_localpart`, and `hive-c0re`'s `matrix::HIVE_LOCALPART`.
+/// Localpart of this hive's sender account. The registration's own
+/// `sender_localpart`, rendered by `hive-matrix.nix` from the hive name — the
+/// same string `swarm_secret_client::matrix::hive_localpart` builds, which is
+/// what `hive-c0re` derives its own copy with.
 const ENV_LOCALPART: &str = "MATRIX_MINT_LOCALPART";
+/// Name of the hive this container belongs to, and so the segment of the store
+/// path the token is published under. It is what keeps one hive's token out of
+/// another hive's reach — see `swarm_secret_client::matrix::sender_token_path`.
+const ENV_HIVE: &str = "MATRIX_MINT_HIVE";
 /// Public base URL of the homeserver, stored beside the token so a reader can
 /// reconstruct where it is good for. Optional: a swarm with no gateway vhost
 /// has no such URL, and `matrix::Credential` types the field to say so.
@@ -50,6 +58,7 @@ struct Config {
     api_url: String,
     registration: String,
     localpart: String,
+    hive: String,
     homeserver: Option<String>,
 }
 
@@ -77,6 +86,7 @@ impl Config {
             api_url: required(ENV_API_URL)?,
             registration: required(ENV_REGISTRATION)?,
             localpart: required(ENV_LOCALPART)?,
+            hive: required(ENV_HIVE)?,
             // Empty is absent: systemd renders an unset nix option as
             // `Environment=VAR=`, so that is the shape this arrives in.
             homeserver: get(ENV_HOMESERVER).filter(|v| !v.is_empty()),
@@ -128,7 +138,8 @@ pub async fn run() -> Result<()> {
             )
         })?;
 
-    let path = matrix::sender_token_path();
+    let path = matrix::sender_token_path(&config.hive)
+        .with_context(|| format!("building the store path for hive {}", config.hive))?;
     if already_published(&store, &path).await {
         tracing::info!(%path, "the sender token is already published; not minting");
         return Ok(());
@@ -175,7 +186,8 @@ mod tests {
             ENV_REGISTRATION => {
                 Some("/var/lib/hyperhive/matrix-appservice/hyperhive.yaml".to_owned())
             }
-            ENV_LOCALPART => Some("hive".to_owned()),
+            ENV_LOCALPART => Some("hive-pr1ma".to_owned()),
+            ENV_HIVE => Some("pr1ma".to_owned()),
             _ => None,
         }
     }
@@ -185,13 +197,20 @@ mod tests {
         // The control: without it every assertion below could be passing
         // because `from_lookup` rejects everything.
         let c = Config::from_lookup(full).expect("every required variable is set");
-        assert_eq!(c.localpart, "hive");
+        assert_eq!(c.localpart, "hive-pr1ma");
+        assert_eq!(c.hive, "pr1ma");
         assert_eq!(c.homeserver, None, "an absent public URL is not an error");
     }
 
     #[test]
     fn each_required_variable_is_named_when_it_is_the_missing_one() {
-        for var in [ENV_CERT_ROLE, ENV_API_URL, ENV_REGISTRATION, ENV_LOCALPART] {
+        for var in [
+            ENV_CERT_ROLE,
+            ENV_API_URL,
+            ENV_REGISTRATION,
+            ENV_LOCALPART,
+            ENV_HIVE,
+        ] {
             let e = Config::from_lookup(|k| if k == var { None } else { full(k) })
                 .expect_err("one required variable is absent");
             assert!(
@@ -237,6 +256,7 @@ mod tests {
             ENV_API_URL,
             ENV_REGISTRATION,
             ENV_LOCALPART,
+            ENV_HIVE,
             ENV_HOMESERVER,
         ] {
             assert!(
@@ -253,8 +273,29 @@ mod tests {
         // and names the literal so a move of the path is a deliberate edit on
         // both sides rather than a silent 404 on the reading one.
         assert_eq!(
-            matrix::sender_token_path(),
-            "swarm/services/matrix/sender-token"
+            matrix::sender_token_path("pr1ma").expect("a plain name is legal"),
+            "swarm/hives/pr1ma/matrix/sender-token"
         );
     }
+
+    #[test]
+    fn two_hives_are_published_to_two_paths() {
+        // What the hive segment is FOR: this binary runs beside a homeserver
+        // several hives share, so a path without the hive name in it would
+        // have each run overwrite the last and leave every hive holding one
+        // identity — which is the shape this change exists to end.
+        let a = matrix::sender_token_path("alpha").expect("legal");
+        let b = matrix::sender_token_path("beta").expect("legal");
+        assert_ne!(a, b);
+    }
+
+    #[test]
+    fn the_localpart_the_unit_hands_over_is_the_one_derived_from_the_hive() {
+        // The nix unit renders both variables independently; this pins that
+        // the pair it is expected to render agrees with the shared derivation,
+        // so a unit still passing the old bare `hive` fails here rather than
+        // silently logging in as another hive's account.
+        let c = Config::from_lookup(full).expect("every required variable is set");
+        assert_eq!(c.localpart, matrix::hive_localpart(&c.hive));
+    }
 }