diff --git a/docs/integrations/matrix.md b/docs/integrations/matrix.md index 5658a245..32db5285 100644 --- a/docs/integrations/matrix.md +++ b/docs/integrations/matrix.md @@ -62,12 +62,12 @@ room id, so adopting a new one does **not** rename the existing users and rooms it strands them, because their ids still name a homeserver that no longer answers. -
Upgrading a homeserver that already has ids +
Pinning serverName on a homeserver with existing ids -A homeserver that minted ids under an older `serverName` default must -**pin the value it actually minted them under**, not adopt the current -default — see above for why adopting a new one strands existing users -and rooms: +`serverName` defaults to the bare `services.hyperhive.swarm.domain`. A +homeserver must set `serverName` to the value that minted its existing +ids — see above for why a different value strands existing users and +rooms: ```nix services.hyperhive.swarm.matrix = { @@ -79,8 +79,8 @@ services.hyperhive.swarm.matrix = { A rebuild on a host that already has a homeserver prints a `hive-matrix: WARNING — … serverName is unset` line when this is missing, -naming the value it's about to default to. It never fails the rebuild, so act on -it before the homeserver mints the ids. +naming the value it's about to default to. It never fails the rebuild, so +pin the value before the homeserver mints any ids under the default.
@@ -210,67 +210,55 @@ tuwunel only treats a message as a command when its sender is already an admin. `@hive-:` has no admin sender to make that call with. Both are swarm-level operations. -
Upgrading a hive that shared one sender account with every other hive +
Store precedence for a hive's sender account -Nothing to do, and no window where the hive is without an account. +`swarm/services/matrix/sender-token` is a shared path `hive-c0re` and +`swarm-controller` both build from the same function; nothing reads it. +`ensure_hive_user` reads the per-hive path +`swarm/hives//matrix/sender-token` **first, on every sweep**, not +just when that file is missing (`sender_source`'s decision), so a value +at the shared path never takes effect once the per-hive path has one. +`swarm-controller` mints a per-hive token within five minutes of a hive +appearing; the sweep then overwrites the per-hive file, no boot +required. -- **The old shared value at `swarm/services/matrix/sender-token` is read by - nothing.** `hive-c0re` and `swarm-controller` both build the path from the - same function, and it now carries the hive's name — so the old object - stays in the store, unread, until an operator deletes it. Delete it or - leave it; the accounts it authenticates as keep their own standing either - way, since an access token lives on the device that minted it. -- **The hive switches on the next sweep.** `ensure_hive_user` reads the - per-hive store path **first, on every sweep**, not just when the file is - missing (`sender_source`'s decision). `swarm-controller` mints a token - there for every hive within five minutes; the sweep takes it and - overwrites the file, so the shared token stops being served as soon as - one exists in the store, no boot required. While the store has nothing - yet, the file is left untouched (still the shared token, right after the - upgrade), so nothing breaks mid-sweep. -- **The rooms the shared account created don't follow the new account, and - this is the one step that needs a decision.** Membership is per account. - `ensure_hive_space` takes the stored room id first, so the sweep hands the - new account the old Space's id, the invite it then sends comes back - refused (a non-member can't invite), and the sweep logs it and carries - on — degraded, not crashed. Two ways out, both operator-chosen. Either invite - `@hive-:` into the existing Space and chat room from a client, which - keeps the history; or delete the hive's stored room-id files, after which - the next sweep creates a Space and chat room owned by the new account and - invites every agent into them. Do one of the two; leaving it gives a hive - that provisions no rooms. +- **Room membership follows the account the sweep currently uses.** + `ensure_hive_space` takes the stored room id first: if a different + account than the room's member created that id, the sweep's invite + comes back refused (a non-member can't invite), and the sweep logs it + and carries on — degraded, not crashed. Two ways out, both + operator-chosen: invite `@hive-:` into the existing Space and + chat room from a client, which keeps the history; or delete the + hive's stored room-id files, after which the next sweep creates a + Space and chat room owned by the current account and invites every + agent into them. Leaving it unresolved gives a hive that provisions + no rooms.
-
Upgrading a hive that used the registration token +
Appservice identity, not the registration token -Nothing to do, and nothing to time. The activation script mints the -appservice token and renders the registration before the homeserver -restarts, so the first boot after the switch already has both halves. +The activation script mints the appservice token and renders the +registration before the homeserver restarts, so every boot has both +halves. `registrationTokenFile` is a removed option: a config that +still sets it fails to evaluate with a message naming the appservice. -- **Existing accounts keep working.** An access token lives on the - device that minted it; removing the registration token touches no - device, no account and no session. `login_with_password` stays on, so - the password fallback is still there too. -- **The sender account may already be an admin** on such a hive (it won the - first-user grant when the hive was new). Nothing here demotes it; the - homeserver no longer promotes it, so a hive built fresh has an - ordinary account and an older one keeps whatever standing it acquired. -- **`/var/lib/hyperhive/matrix-register-token` stays on disk**, read by - nothing. Delete it or leave it; neither does any harm. -- **`registrationTokenFile` is a removed option.** A config that still - sets it fails to evaluate with a message naming the appservice — a hive - that never set it (the default) is unaffected. -- **A swarm store holding the old `matrix/registration-token` path** is - no longer read at all. The value that matters now lives at - `matrix/appservice-token`, and `swarm-secret-publish` on the authelia - host mints and `put`s it there — the hive uses its locally minted - token only until the first successful read. See - [`../swarm/secrets.md`](../swarm/secrets.md) for how that mint stays - idempotent across runs. +- **Access tokens are independent of the registration token.** An + access token lives on the device that minted it, so accounts and + sessions are unaffected by the registration token's presence. + `login_with_password` stays on, so the password fallback works + too. +- **The homeserver's `admin_execute` promotes only `@swarm` at boot** + (above); a hive's sender account is never promoted, regardless of + when it was created. +- **The value that matters lives at `matrix/appservice-token`.** + `swarm-secret-publish` on the authelia host mints and `put`s it + there; the hive uses its locally minted token only until the first + successful read. See [`../swarm/secrets.md`](../swarm/secrets.md) + for how that mint stays idempotent across runs.
diff --git a/docs/networking/network.md b/docs/networking/network.md index f10f4a3e..60c34647 100644 --- a/docs/networking/network.md +++ b/docs/networking/network.md @@ -8,15 +8,8 @@ the hive collector, and the gateway's resolver, which every swarm service turns on. Configured via `services.hyperhive.network.*`. Isolation is the only mode; agent containers never share the host netns. - -
Upgrading a config that sets isolateContainers or upstreamDns - -Neither option exists. A config that still sets -`services.hyperhive.network.isolateContainers` or -`services.hyperhive.network.upstreamDns` fails eval with a removal -message; drop the line. - -
+`services.hyperhive.network.isolateContainers` and +`services.hyperhive.network.upstreamDns` don't exist. ## Network map