matrix: mint the appservice sender token in the matrix container

A swarm runs one homeserver and a homeserver has one appservice sender
account, so "mint it once" is a property of the thing being minted
rather than something a lock has to enforce. That is what makes this
account the one to move first: no trigger route, no controller change
and no agent list — a boot-time oneshot beside tuwunel is the whole
mechanism.

`swarm-matrix-minter` runs inside `containers.hive-matrix`, which
already holds the appservice token: the rendered registration is bound
in read-only because that is how tuwunel is handed it. What the
container lacked was an identity of its own, so this adds one — a leaf
from the store's CA with a grant of exactly one path, not the hive's
leaf, which reads every secret in the store.

Both ends of the credential ship here. The minter reads the path it
publishes to before it touches the homeserver, and returning on a
non-empty read IS the "only once"; `hive-c0re`'s `ensure_hive_user`
reads the same path, authenticating with the hive name already in
`HYPERHIVE_HIVE_NAME`. The existing mint-then-`M_USER_IN_USE`-login
ladder stays as the fallback for a store that is empty, unconfigured or
unreachable, which is every swarm deployed before this — so nothing
needs backfilling and nothing breaks if the rest of the sequence never
lands.

The credential is not an admin credential, and is not named like one.
It is the access token of the appservice registration's own
`sender_localpart` — `@hive:<server_name>`, an account the homeserver
creates for itself when it loads the registration. The store path is
`swarm/services/matrix/sender-token`, the host path is
`matrix/access-token`, and the homeserver no longer runs an
`admin_execute` promotion for that account at boot. Everything the hive
provisions with it — the Space, the chat room, their hierarchy and join
rules, the invites — rides on being the creator of those rooms at power
level 100, not on homeserver admin; there is no Synapse admin API here
to need, tuwunel has none.

Two operations do need an admin *sender* and therefore stop working:
`hivectl matrix promote-user` and `hivectl matrix reset-password`, both
`!admin …` messages into `#admins:<server>`, plus the password-reset
recovery path that an agent with a lost password file falls back to.
They are swarm-level operations and are left failing loudly rather than
served by an over-privileged token every other call site would also
carry. The sweep's own admin-rights check and self-repair go with them:
an account that is deliberately not an admin has nothing to check.

`ephemeral = false` stays, and hive root can still read the container's
filesystem. Accepted: what this buys is identity separation — no hive
*process* holds or reads the appservice token — not physical isolation.

Refs #4345

swarm-matrix-minter/src/registration.rs

@@ -0,0 +1,104 @@
+//! Reading the `as_token` out of the appservice registration the matrix
+//! container already has.
+//!
+//! No new credential is delivered for this. `nix/host-modules/hive-matrix.nix`
+//! binds the registration directory into the container read-only so tuwunel can
+//! load it, and the registration **is** the `as_token` — so the file this
+//! module opens is one this process could already read, and one the homeserver
+//! beside it reads too.
+//!
+//! Scanned line-by-line rather than parsed as YAML. The file has exactly one
+//! renderer (`appserviceRegistrationScript` in that same module, a `printf` of
+//! `as_token: <hex>`), so a parser would be a second, looser reading of a shape
+//! this repo writes itself — and it would pull a YAML crate into a binary whose
+//! only other input is JSON.
+
+use anyhow::{Context, Result, bail};
+
+/// The key the token is stored under, and the whole of the agreement with the
+/// renderer.
+const KEY: &str = "as_token:";
+
+/// Read the registration at `path` and return its `as_token`.
+///
+/// # Errors
+/// When the file cannot be read, or holds no `as_token` with a value — which is
+/// what a registration rendered by something other than this repo looks like
+/// from here.
+pub fn as_token(path: &str) -> Result<String> {
+    let text = std::fs::read_to_string(path)
+        .with_context(|| format!("reading the appservice registration at {path}"))?;
+    // The path, not the file's contents: every line of it is either a secret or
+    // a shape this module already knows.
+    extract(&text).with_context(|| format!("no `as_token` in the registration at {path}"))
+}
+
+/// [`as_token`] over text already in hand, so the agreement with the renderer
+/// can be tested without a file.
+fn extract(text: &str) -> Result<String> {
+    for line in text.lines() {
+        if let Some(rest) = line.strip_prefix(KEY) {
+            let token = rest.trim();
+            if token.is_empty() {
+                bail!("the registration's `as_token` is empty");
+            }
+            return Ok(token.to_owned());
+        }
+    }
+    bail!("the registration carries no `as_token` line")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// The registration exactly as `appserviceRegistrationScript` renders it —
+    /// the quoted heredoc, then the `printf` of the two tokens. Reproduced
+    /// verbatim because that script is the other end of this agreement and
+    /// lives in a file no Rust test can reach.
+    const RENDERED: &str = "id: hyperhive\n\
+         url: null\n\
+         sender_localpart: hive\n\
+         rate_limited: false\n\
+         namespaces:\n  \
+           users:\n    \
+             - exclusive: false\n      \
+               regex: '@[a-z0-9._=/+-]+:example\\.test$'\n  \
+           aliases: []\n  \
+           rooms: []\n\
+         as_token: deadbeef\n\
+         hs_token: cafebabe\n";
+
+    #[test]
+    fn the_token_is_taken_from_the_registration_this_repo_renders() {
+        assert_eq!(
+            extract(RENDERED).expect("the rendered shape parses"),
+            "deadbeef"
+        );
+    }
+
+    #[test]
+    fn the_homeservers_own_token_is_not_mistaken_for_the_appservices() {
+        // `hs_token` authenticates the homeserver TO the appservice and is a
+        // different secret with a confusingly similar name; a substring search
+        // would find it inside neither, but a `contains("s_token")`-shaped one
+        // would. The control is that the line order in `RENDERED` puts
+        // `as_token` first, so this arm needs the reverse to mean anything.
+        let reversed = "hs_token: cafebabe\nas_token: deadbeef\n";
+        assert_eq!(
+            extract(reversed).expect("order does not matter"),
+            "deadbeef"
+        );
+    }
+
+    #[test]
+    fn a_registration_with_no_token_is_an_error_rather_than_an_empty_string() {
+        // An empty token authenticates nothing, and a homeserver answers a
+        // request carrying one with a 403 that names the account rather than
+        // the credential — so failing here is the only report an operator can
+        // act on.
+        for bad in ["id: hyperhive\n", "as_token:\n", "as_token:   \n"] {
+            assert!(extract(bad).is_err(), "{bad:?} must not yield a token");
+        }
+    }
+}