vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

drop the hive-side matrix code: sweep, hivectl matrix and the apiUrl option

Browse source
This commit is contained in:
damocles 2026-10-28 22:16:16 +01:00 • committed by mara
commit 6dbb18b6d4
1 changed files with 49 additions and 1007 deletions
Download patch file Download diff file Expand all files Collapse all files

62
docs/integrations/matrix.md
View file

@ -96,11 +96,8 @@ and federation peers all reach the homeserver at `chat.<swarm-domain>`
through the gateway; from outside the host that takes
`gateway.openFirewall`.
hive-c0re talks to matrix (its own sender login, invites) through `swarm.matrix.apiUrl`, which defaults to
`https://<swarm.matrix.gatewayHost>` on every hive. That login carries
the hive's matrix access token, and on a hive that doesn't run the
homeserver it crosses the network, so the default is TLS; hive-c0re
verifies the gateway's certificate against the hive trust bundle.
hive-c0re does not talk to the homeserver: matrix is swarm-level, and
the hive has no matrix API URL to set.
Federation peers find the homeserver through `.well-known/matrix/server`
at the server name, which names `<gatewayHost>:443`
@ -143,8 +140,8 @@ a token.
reads only `.yaml`/`.yml` entries from there, so the sibling
credentials are invisible to it. The `.yaml` suffix on the credential
id is what makes this work.
4. **hive-c0re** holds no appservice token and creates no account. Its
`@hive-<hive>:` token comes from the swarm store (below).
4. **hive-c0re** holds no appservice token, creates no account and does
not talk to matrix.
5. **`swarm-controller` creates every account**: each agent's, with its
token stored at `swarm/agents/<agent>/matrix/main` for the agent's
`hive-matrix-daemon` to read as the agent itself, and each hive's
@ -246,21 +243,14 @@ whose hives share a homeserver gives each of them its own identity: the
homeserver attributes an action to the hive that took it, and revoking one
hive's standing leaves the others alone.
Its access token is the **sender token**, and it's the credential
hive-c0re presents for every homeserver call it makes on the hive's
behalf. It's per hive for the same reason the account is:
`swarm-controller`, its only minter, mints it for every hive with the swarm's
appservice token and publishes it to `swarm/hives/<hive>/matrix/sender-token`, and the hive
reads it from there under its own certificate. That path sits inside the
hive's own read grant (`swarm/hives/<hive>/*`), so a hive fetches its own
token and gets a refusal on any other hive's. The name says what it
authenticates as — an account the swarm's appservice creates — rather
than any privilege level, because it carries none.
It needs no promotion for what the hive does with it. Inviting a user into a
room it has the power in is an ordinary client call — there is no homeserver
admin in any of it, and no Synapse admin API to reach for either, since
tuwunel has none.
Its access token is the **sender token**. `swarm-controller`, its only
minter, mints it for every hive with the swarm's appservice token and
publishes it to `swarm/hives/<hive>/matrix/sender-token`, inside the hive's own
read grant (`swarm/hives/<hive>/*`). Nothing on the hive uses it any more:
hive-c0re used to present it for its Space and invite calls and no longer
makes any. The name says what it authenticates as — an account the
swarm's appservice creates — rather than any privilege level, because it
carries none.
Promoting a user to homeserver admin and resetting a password both need an
admin **sender**: `!admin …` messages into `#admins:<server_name>`, and
@ -270,17 +260,6 @@ admin. Of the swarm's own accounts only `@swarm` is a homeserver admin
[Operators are homeserver admins](#operators-are-homeserver-admins)), so
both are swarm-level operations.
<details><summary>Store precedence for a hive's sender account</summary>
`ensure_hive_user` reads the per-hive path
`swarm/hives/<hive>/matrix/sender-token` **first, on every sweep**, not
just when that file is missing (`sender_source`'s decision).
`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.
</details>
<details><summary>Appservice identity</summary>
`swarm-matrix-ctl appservice render` renders the registration from the
@ -344,17 +323,14 @@ Initial rollout settings:
stored yet the account comes up without backup and picks it up on the
next daemon start. A failure is a `WARN` and never stops the daemon.
## Hive sender token
## Retired hive-side matrix code
hive-c0re keeps the hive's `@hive-<hive>:` sender token on disk for
`hivectl matrix invite`, refreshed from the swarm secret store by the
matrix sweep (at boot, then every 30 minutes).
Earlier versions also created a private "hive" Matrix Space and a
`hive-chat` room, invited every agent to both, and kept their ids in
`/var/lib/hyperhive/matrix/space-room-id` and `chat-room-id`. The sweep no
longer touches any of them. The rooms and files are harmless leftovers, so
delete them by hand if you like.
Earlier versions of hive-c0re created a private "hive" Matrix Space and a
`hive-chat` room, invited every agent to both, kept the hive's sender token
on disk and offered `hivectl matrix invite`. All of that is gone: matrix is
swarm-level, so the hive no longer talks to the homeserver. The Space, the
room and the files `/var/lib/hyperhive/matrix/{access-token,space-room-id,chat-room-id}`
are harmless leftovers, so delete them by hand if you like.
## Configuration tuning