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

keep the matrix appservice registration in bao, with the host file as the last copy

Browse source
This commit is contained in:
atlas 2026-10-27 13:52:17 +01:00
commit d5c5862654
12 changed files with 1014 additions and 273 deletions
Download patch file Download diff file Expand all files Collapse all files

41
docs/integrations/matrix.md
View file

@ -129,10 +129,11 @@ creation doesn't depend on registration being open to anyone who learns
a token.
1. **`swarm-matrix-ctl appservice render`**, inside the `hive-matrix`
container and before tuwunel starts, mints the registration's
`as_token` and its spec-required `hs_token` when they're missing, and
renders the registration to
`/var/lib/swarm-matrix-appservice/swarm.yaml` (mode `0600 root:root`).
container and before tuwunel starts, renders the registration to
`/var/lib/swarm-matrix-appservice/swarm.yaml` (mode `0600 root:root`)
from the `as_token` and spec-required `hs_token` beside it. It mints
them only on a container that has none, and never reaches the store, so
a store outage can't keep the homeserver down.
2. **systemd `LoadCredential=`** copies the registration into
`/run/credentials/tuwunel.service/swarm-appservice.yaml`, owned by
tuwunel's dynamic user with mode `0400`, at service start. The source
@ -168,13 +169,21 @@ namespace non-exclusive. It's the swarm's identity on the homeserver:
`swarm-controller` creates every agent's account and every hive's sender
account with it.
`swarm-matrix-ctl appservice render` mints its tokens inside the
`hive-matrix` container, before tuwunel starts, and renders the
registration tuwunel loads as a credential. `appservice publish`
then writes its `as_token` to
`swarm/controller/swarm-controller/matrix/appservice-token`. No hive's
policy reaches that path: only matrix-ctl (which writes it) and
`swarm-controller` (which reads it) hold a grant to it.
The swarm secret store holds the registration's tokens, at
`swarm/controller/swarm-controller/matrix/appservice-registration`.
`swarm-matrix-ctl appservice render` renders the registration tuwunel
loads as a credential from the copy of them in the `hive-matrix`
container, before tuwunel starts and without the store.
`appservice sync` runs beside tuwunel on a timer. The store's tokens win:
when they differ from the container's, it writes them there. It
restarts tuwunel whenever the registration is newer than tuwunel's last
start, so the next run retries one that failed after writing. A store that holds none takes the container's
tokens with a create-only write, so a running swarm keeps its value, and
a container that has none mints a pair. `sync` then writes the `as_token`
to `swarm/controller/swarm-controller/matrix/appservice-token`. No hive's
policy reaches either path: only matrix-ctl (which holds `create` and
`read` on the registration, and writes the token) and `swarm-controller`
(which reads only the token) hold a grant.
`@swarm` is the **one** account the homeserver promotes to admin at boot
(`admin_execute`). Only those two principals read its token, which is
@ -277,9 +286,9 @@ required.
<details><summary>Appservice identity</summary>
`swarm-matrix-ctl appservice render` mints the appservice tokens and
renders the registration before tuwunel starts, so every boot has both
halves.
`swarm-matrix-ctl appservice render` renders the registration from the
container's copy of the appservice tokens before tuwunel starts, so every
boot has both halves, with the store up or down.
<!-- vale write-good.Passive = NO -->
- **Access tokens live on the device that minted them.**
@ -289,8 +298,8 @@ halves.
(above); a hive's sender account is never promoted.
- **The value that matters lives at
`swarm/controller/swarm-controller/matrix/appservice-token`.**
`appservice publish` writes the container's copy there whenever the
store's differs, and `swarm-controller` reads it from there.
`appservice sync` writes it there whenever the store's differs from the
registration's `as_token`, and `swarm-controller` reads it from there.
<!-- vale write-good.Passive = YES -->
</details>

68
docs/swarm/credentials-reference.md
View file

@ -14,39 +14,40 @@ the rest of the cell says how.
<!-- vale write-good.Passive = NO -->
| store path | minter | reader | automatic re-mint | automatic re-pull |
| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `swarm/agents/<agent>/matrix/main` | `swarm-controller`, at agent creation and every 5 minutes | the agent | ✅ when missing or rejected by the homeserver | ✅ the daemon restarts within 5 minutes of a rejection |
| `swarm/agents/<agent>/matrix/<account>` | `swarm-controller`, from a credential you hand it | the agent | must be stated | ✅ retried within 2 to 16 minutes after a rejection |
| `swarm/agents/<agent>/matrix-recovery/<account>` | `swarm-controller`, a random passphrase per account | the agent | ❌ never replaced: the account's key backup opens only with this passphrase | ❌ read when the account comes up |
| `swarm/controller/swarm-controller/matrix/appservice-token` | `swarm-matrix-ctl` in `hive-matrix`, once | `swarm-controller` | ❌ minted once | ✅ read every 5 minutes |
| `swarm/controller/swarm-controller/oidc/client` | authelia, first boot | `swarm-controller` | ❌ minted once; `swarm-secret-publish` republishes a re-mint | ✅ re-read when authelia refuses it |
| `swarm/controller/swarm-controller/forge/token` | the forge, once | `swarm-controller` | ❌ minted once; delete `/var/lib/forgejo/swarm-controller-token-name` in the forge container to mint a new one | ✅ re-read on a 401 |
| `swarm/controller/swarm-controller/grafana/token` | `swarm-bao-grafana-controller-token` on Grafana's host | `swarm-controller` | ✅ every 10 minutes, when Grafana refuses it or none is stored | ✅ re-read on a 401 |
| `swarm/controller/swarm-controller/forge/webhook-secret` | `swarm-controller`, at start, from its old `webhook-secret` file; a new one only when there is no file | `swarm-controller` | ❌ minted once; a rotated secret fails every delivery until the forge hooks are re-registered | ❌ read at start |
| `swarm/agents/<agent>/bao-mtls` | the store's agent PKI mount (`deploy.bao.agentPkiMountPath`), at agent creation | `hive-c0re`, then the agent | ✅ re-issued every 5 minutes once past half its 7-day validity | ✅ the agent re-reads every 10 minutes; it renews only while its current leaf is valid |
| `swarm/agents/<agent>/queue` | `swarm-controller`, at agent creation | the agent; the queue, log and metrics auth services | ✅ re-minted at 45 days; skipped for `Destroyed` agents, whose path is deleted | ✅ read on every reconnect; an open connection keeps the old secret for up to an hour; the log and metrics stores honour a replaced secret for up to `deploy.victorialogs.authVerdictTtl` and `deploy.victoriametrics.agentAuthVerdictTtl` (60 s by default) |
| `swarm/agents/<agent>/forge-token` | `swarm-controller`, at agent creation and every 5 minutes | the agent | ✅ when missing or no longer matching the forge | ✅ every 10 minutes |
| `swarm/agents/<agent>/forge/<label>` | `swarm-controller`, when you link an external forge account in the swarm UI | the agent | ❌ your token; delete it and link the label again | ✅ every 2 minutes |
| `swarm/agents/<agent>/github-token` | `swarm-controller`, when you link a GitHub account in the swarm UI | the agent | ❌ your token; delete it and link again | ✅ every 2 minutes |
| `swarm/agents/<agent>/claude-credentials` | `swarm-claude-login`, when you log the agent in from its card; one version per login | the agent, while it waits for a login | ❌ log in again | ✅ every 30 seconds while waiting |
| `swarm/hives/<hive>/matrix/sender-token` | `swarm-controller`, every 5 minutes | `swarm-controller` and the hive | ✅ when missing or rejected by the homeserver | ✅ the hive re-reads on every sweep |
| `swarm/hives/<hive>/forge/token` | `swarm-controller`, every 5 minutes | `swarm-controller` and the hive | ✅ when missing or no longer matching the forge | ✅ read on every forge call |
| `swarm/hives/<hive>/oidc/client` | authelia, first boot; `swarm-secret-publish` copies it in | the hive | ❌ minted once; `swarm-secret-publish` republishes a re-mint | ✅ re-read when authelia refuses it |
| `swarm/services/<clientId>/oidc/client` | authelia | that service | must be stated | must be stated |
| `swarm/services/ci-runner/registration-token` | `swarm-controller`, from the forge, at start and every 5 minutes | `swarm-bao-ci-runner` on the runner's host | ❌ the forge keeps one token until an admin resets it; the controller then writes the new one within 5 minutes | ✅ every 10 minutes; restarts the runner on a change |
| `swarm/services/<grafana client id>/metrics/bearer` | `swarm-bao-grafana-metrics-bearer` on Grafana's host, when none is stored | `swarm-metrics-auth` and `swarm-logs-grafana-auth` | ❌ delete it and restart `swarm-bao-grafana-metrics-bearer` | ✅ the auth services re-read within a minute; ❌ Grafana restarts when its copy changes |
| `swarm/services/<grafana client id>/secret-key` | `swarm-bao-grafana-secret-key` on Grafana's host, from the key an earlier release generated; a new one only when there is none | Grafana | ❌ minted once; a different key leaves Grafana unable to read its stored datasource secrets | ❌ Grafana reads it at start; the unit restarts Grafana when the file changes |
| `swarm/services/swarm-authelia/keys/<name>`, for `jwt`, `session`, `storage-encryption`, `oidc-hmac` and `oidc-issuer` | authelia's `authelia-swarm-secrets` unit in its container, under the secret publisher's identity, from the key file an earlier release generated; a new one only when there is none | authelia | ❌ minted once; a different storage-encryption key leaves authelia's database unreadable and a different issuer key invalidates every issued token | ❌ read when the unit runs; the unit restarts authelia when the file changes |
| `swarm/services/review-classifier/anthropic-api-key` | you, in the store's UI, field `api_key` | `swarm-review-classifier` | ❌ write a new key | ✅ read on every run |
| `swarm/services/review-classifier/acp-provider` | you, in the store's UI, field `api_key` | `swarm-review-classifier` | ❌ write a new key | ✅ read on every run |
| `swarm/services/review-classifier/forge/token` | `swarm-controller`, at start and every 5 minutes | `swarm-controller` | ✅ when missing or no longer matching the forge | ✅ read on every review |
| `swarm/services/builder/forge/token` | `swarm-controller`, at start and every 5 minutes | `swarm-builder`, `swarm-controller` | ✅ when missing or no longer matching the forge | ✅ read on every build |
| `swarm/services/attic/push-token` | `swarm-bao-attic-tokens` on the cache's host, when none is stored; with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the token on stdin | `swarm-builder` | ❌ write a new token; a token the cache refuses fails the push, and the build stays green with `cached` false | ✅ read on every push; with no `swarm.attic` cache set, nothing reads it |
| `swarm/services/attic/pull-token` | `swarm-bao-attic-tokens` on the cache's host, when none is stored; read-only, ten years | nothing yet | ❌ write a new token | must be stated |
| `swarm/services/attic/jwt-secret` | `swarm-bao-attic-secret` on the cache's host, when none is stored | `swarm-bao-attic-secret`, `swarm-bao-attic-tokens` | ❌ a new key invalidates both tokens | ❌ atticd restarts when the file changes |
| `swarm/services/ci-metrics/forge/token` | `swarm-controller`, at start and every 5 minutes | `swarm-ci-metrics`, `swarm-controller` | ✅ when missing or no longer matching the forge | ✅ read on every pass |
| _(not in the store)_ a hive's mTLS leaf | the store's PKI, or you by hand | the hive itself, from disk | must be stated | must be stated |
| store path | minter | reader | automatic re-mint | automatic re-pull |
| ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `swarm/agents/<agent>/matrix/main` | `swarm-controller`, at agent creation and every 5 minutes | the agent | ✅ when missing or rejected by the homeserver | ✅ the daemon restarts within 5 minutes of a rejection |
| `swarm/agents/<agent>/matrix/<account>` | `swarm-controller`, from a credential you hand it | the agent | must be stated | ✅ retried within 2 to 16 minutes after a rejection |
| `swarm/agents/<agent>/matrix-recovery/<account>` | `swarm-controller`, a random passphrase per account | the agent | ❌ never replaced: the account's key backup opens only with this passphrase | ❌ read when the account comes up |
| `swarm/controller/swarm-controller/matrix/appservice-token` | `swarm-matrix-ctl appservice sync` in `hive-matrix`, from the registration's `as_token` | `swarm-controller` | ❌ follows the registration below | ✅ read every 5 minutes |
| `swarm/controller/swarm-controller/matrix/appservice-registration` | `swarm-matrix-ctl appservice sync` in `hive-matrix`: seeded from the container's own tokens when the store holds none, a new pair only when the container has none either | `swarm-matrix-ctl` in `hive-matrix`; the controller has no grant to it | ❌ minted once; an operator who replaces it makes `sync` write the new pair into the container and restart the homeserver | ✅ `sync` re-reads it every 10 minutes |
| `swarm/controller/swarm-controller/oidc/client` | authelia, first boot | `swarm-controller` | ❌ minted once; `swarm-secret-publish` republishes a re-mint | ✅ re-read when authelia refuses it |
| `swarm/controller/swarm-controller/forge/token` | the forge, once | `swarm-controller` | ❌ minted once; delete `/var/lib/forgejo/swarm-controller-token-name` in the forge container to mint a new one | ✅ re-read on a 401 |
| `swarm/controller/swarm-controller/grafana/token` | `swarm-bao-grafana-controller-token` on Grafana's host | `swarm-controller` | ✅ every 10 minutes, when Grafana refuses it or none is stored | ✅ re-read on a 401 |
| `swarm/controller/swarm-controller/forge/webhook-secret` | `swarm-controller`, at start, from its old `webhook-secret` file; a new one only when there is no file | `swarm-controller` | ❌ minted once; a rotated secret fails every delivery until the forge hooks are re-registered | ❌ read at start |
| `swarm/agents/<agent>/bao-mtls` | the store's agent PKI mount (`deploy.bao.agentPkiMountPath`), at agent creation | `hive-c0re`, then the agent | ✅ re-issued every 5 minutes once past half its 7-day validity | ✅ the agent re-reads every 10 minutes; it renews only while its current leaf is valid |
| `swarm/agents/<agent>/queue` | `swarm-controller`, at agent creation | the agent; the queue, log and metrics auth services | ✅ re-minted at 45 days; skipped for `Destroyed` agents, whose path is deleted | ✅ read on every reconnect; an open connection keeps the old secret for up to an hour; the log and metrics stores honour a replaced secret for up to `deploy.victorialogs.authVerdictTtl` and `deploy.victoriametrics.agentAuthVerdictTtl` (60 s by default) |
| `swarm/agents/<agent>/forge-token` | `swarm-controller`, at agent creation and every 5 minutes | the agent | ✅ when missing or no longer matching the forge | ✅ every 10 minutes |
| `swarm/agents/<agent>/forge/<label>` | `swarm-controller`, when you link an external forge account in the swarm UI | the agent | ❌ your token; delete it and link the label again | ✅ every 2 minutes |
| `swarm/agents/<agent>/github-token` | `swarm-controller`, when you link a GitHub account in the swarm UI | the agent | ❌ your token; delete it and link again | ✅ every 2 minutes |
| `swarm/agents/<agent>/claude-credentials` | `swarm-claude-login`, when you log the agent in from its card; one version per login | the agent, while it waits for a login | ❌ log in again | ✅ every 30 seconds while waiting |
| `swarm/hives/<hive>/matrix/sender-token` | `swarm-controller`, every 5 minutes | `swarm-controller` and the hive | ✅ when missing or rejected by the homeserver | ✅ the hive re-reads on every sweep |
| `swarm/hives/<hive>/forge/token` | `swarm-controller`, every 5 minutes | `swarm-controller` and the hive | ✅ when missing or no longer matching the forge | ✅ read on every forge call |
| `swarm/hives/<hive>/oidc/client` | authelia, first boot; `swarm-secret-publish` copies it in | the hive | ❌ minted once; `swarm-secret-publish` republishes a re-mint | ✅ re-read when authelia refuses it |
| `swarm/services/<clientId>/oidc/client` | authelia | that service | must be stated | must be stated |
| `swarm/services/ci-runner/registration-token` | `swarm-controller`, from the forge, at start and every 5 minutes | `swarm-bao-ci-runner` on the runner's host | ❌ the forge keeps one token until an admin resets it; the controller then writes the new one within 5 minutes | ✅ every 10 minutes; restarts the runner on a change |
| `swarm/services/<grafana client id>/metrics/bearer` | `swarm-bao-grafana-metrics-bearer` on Grafana's host, when none is stored | `swarm-metrics-auth` and `swarm-logs-grafana-auth` | ❌ delete it and restart `swarm-bao-grafana-metrics-bearer` | ✅ the auth services re-read within a minute; ❌ Grafana restarts when its copy changes |
| `swarm/services/<grafana client id>/secret-key` | `swarm-bao-grafana-secret-key` on Grafana's host, from the key an earlier release generated; a new one only when there is none | Grafana | ❌ minted once; a different key leaves Grafana unable to read its stored datasource secrets | ❌ Grafana reads it at start; the unit restarts Grafana when the file changes |
| `swarm/services/swarm-authelia/keys/<name>`, for `jwt`, `session`, `storage-encryption`, `oidc-hmac` and `oidc-issuer` | authelia's `authelia-swarm-secrets` unit in its container, under the secret publisher's identity, from the key file an earlier release generated; a new one only when there is none | authelia | ❌ minted once; a different storage-encryption key leaves authelia's database unreadable and a different issuer key invalidates every issued token | ❌ read when the unit runs; the unit restarts authelia when the file changes |
| `swarm/services/review-classifier/anthropic-api-key` | you, in the store's UI, field `api_key` | `swarm-review-classifier` | ❌ write a new key | ✅ read on every run |
| `swarm/services/review-classifier/acp-provider` | you, in the store's UI, field `api_key` | `swarm-review-classifier` | ❌ write a new key | ✅ read on every run |
| `swarm/services/review-classifier/forge/token` | `swarm-controller`, at start and every 5 minutes | `swarm-controller` | ✅ when missing or no longer matching the forge | ✅ read on every review |
| `swarm/services/builder/forge/token` | `swarm-controller`, at start and every 5 minutes | `swarm-builder`, `swarm-controller` | ✅ when missing or no longer matching the forge | ✅ read on every build |
| `swarm/services/attic/push-token` | `swarm-bao-attic-tokens` on the cache's host, when none is stored; with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the token on stdin | `swarm-builder` | ❌ write a new token; a token the cache refuses fails the push, and the build stays green with `cached` false | ✅ read on every push; with no `swarm.attic` cache set, nothing reads it |
| `swarm/services/attic/pull-token` | `swarm-bao-attic-tokens` on the cache's host, when none is stored; read-only, ten years | nothing yet | ❌ write a new token | must be stated |
| `swarm/services/attic/jwt-secret` | `swarm-bao-attic-secret` on the cache's host, when none is stored | `swarm-bao-attic-secret`, `swarm-bao-attic-tokens` | ❌ a new key invalidates both tokens | ❌ atticd restarts when the file changes |
| `swarm/services/ci-metrics/forge/token` | `swarm-controller`, at start and every 5 minutes | `swarm-ci-metrics`, `swarm-controller` | ✅ when missing or no longer matching the forge | ✅ read on every pass |
| _(not in the store)_ a hive's mTLS leaf | the store's PKI, or you by hand | the hive itself, from disk | must be stated | must be stated |
<!-- vale write-good.Passive = YES -->
@ -103,6 +104,7 @@ pieces fit, and the reasoning behind them, is in [`credentials.md`](credentials.
| swarm-services root CA (cert + key) | `swarm-bao.nix`'s granting unit, inside the store's `pki` mount | the **key** never leaves the mount; the **cert** lands at `/var/lib/swarm-bao-services-pki/services-root.pem` (0644) and at `/var/lib/hive-tls/swarm-services-root.pem` on every hive | nothing to copy — every hive receives the cert with the leaf it asks the store for, or from `pki/ca/pem` where it fronts no swarm name and needs a store identity |
| authelia session, JWT, storage-encryption and OIDC HMAC keys | `authelia-swarm-secrets` in authelia's container. It stores each in the swarm secret store at `swarm/services/swarm-authelia/keys/<name>` when the store holds none: the value of the key an earlier release generated, or a new one when there is no such file. The files stay on disk. While the store's policy doesn't grant the leaf yet, or the store is down, the unit runs on the files. A container with no secret publisher identity generates the files, as before | `/var/lib/authelia-swarm/{session,jwt,storage-encryption,oidc-hmac}.key` | nothing to place: the publisher's store leaf is the one in the row below. A store that stays unreachable on a start with no key file keeps authelia from starting |
| authelia OIDC issuer key (RSA) | same unit, same store path (`oidc-issuer`) | `/var/lib/authelia-swarm/oidc-issuer.key` | same — relying parties verify against the **public** half at `/jwks.json` |
| swarm appservice registration (`as_token`, `hs_token`) | `swarm-matrix-ctl appservice sync` in `hive-matrix`. The store's pair wins; a store holding none takes the container's own tokens, so the value doesn't change by moving. Only `appservice render` on a container with neither mints a new pair | `/var/lib/swarm-matrix-appservice/{as-token,hs-token,swarm.yaml}` in `hive-matrix`, the last copy `sync` took, which tuwunel starts from; the store path is `swarm/controller/swarm-controller/matrix/appservice-registration` | nothing to place: matrix-ctl's store leaf is the one the container binds. A store that's down leaves the homeserver running on the files |
| OIDC client secret, plaintext half | `authelia crypto hash generate --random` | `/var/lib/authelia-swarm/oidc-clients/<id>.secret` | operator provides the file and names it in whichever option reads it — `sso.clientSecretFile` for a service; the forge and, by default, the hive collector need none — `swarm-bao-forge-oidc` and `swarm-bao-hive-otel-oidc` fetch it from the store ([how](credentials.md#hive-level-secrets)) |
| OIDC client secret, digest half | the same mint | `oidc-clients/<id>.digest` | authelia's own half; merged at runtime via `settingsFiles` |
| the swarm collector's copy of its OIDC secret | `swarm-bao-otel-oidc.service` reads it out of the swarm secret store, **on every host that runs the collector and holds a store identity** | `/run/swarm-otel-oidc/<id>.secret` on the host's tmpfs, bind-mounted read-only into the `swarm-otel` container — never on persistent disk, so a reboot fetches it again | same unit, same path — one route, co-located or not. A collector with no store identity has `clientSecretFile == null`, its already-supported unauthenticated-push degrade — see [swarm-level secrets](credentials.md#swarm-level-secrets) |

50
nix/host-modules/hive-matrix.nix
View file

@ -137,11 +137,12 @@ let
#
# The homeserver's one appservice registration, and the swarm's identity on
# it: `swarm-controller` creates every agent's account and every hive's
# `@hive-<hive>` sender with its token. Minted INSIDE this container by
# `swarm-matrix-ctl appservice render` and published to the store by
# `appservice publish`, which is why it is gated on matrix-ctl's store
# identity: with nobody to publish it, a registration here would be an
# admin credential nobody reads.
# `@hive-<hive>` sender with its token. The store holds its tokens;
# `swarm-matrix-ctl appservice sync` keeps this container's copy in step with
# them, which is why it is gated on matrix-ctl's store identity: with nobody
# to sync it, a registration here would be an admin credential nobody reads.
# `appservice render` minted a copy here only for a host that has none, and
# renders the one the homeserver starts from.
#
# Its sender is promoted to homeserver admin at boot (`admin_execute`
# below), so its token goes only to a store path no hive's policy reaches.
@ -1002,9 +1003,11 @@ in
# below is `requiredBy` it and local only.
++ lib.optional ctlActive "${swarmAppserviceCredentialId}:${swarmAppserviceDir}/swarm.yaml";
# The swarm registration, minted and rendered before the homeserver
# loads it. No network and no store: this is on tuwunel's start
# path, and a store outage must not keep the homeserver down.
# The swarm registration, rendered before the homeserver loads it from
# the tokens in the state dir: the last copy of the store's that
# `swarm-matrix-appservice-sync` took, or a minted pair on a host with
# none. No network and no store: this is on tuwunel's start path, and
# a store outage must not keep the homeserver down.
systemd.services.swarm-matrix-appservice-render = lib.mkIf ctlActive {
description = "render the swarm's appservice registration";
before = [ "tuwunel.service" ];
@ -1027,21 +1030,31 @@ in
};
};
# Hand the swarm registration's token to swarm-controller, through
# the store, under matrix-ctl's identity; the write lands at a path
# only matrix-ctl and the controller are granted (./swarm-bao.nix).
# The store holds the swarm registration; this keeps the state dir
# the render above reads in step with it, and publishes the
# `as_token` to the path `swarm-controller` reads, under matrix-ctl's
# identity (the grants are in ./swarm-bao.nix). A store without the
# registration is seeded from the state dir, so nothing rotates.
#
# ⚠️ Not `before`/`requiredBy` tuwunel, and nothing orders tuwunel
# after it: the homeserver starts from the state dir's last copy
# whether or not the store answers. When the registration is newer than
# tuwunel's last start, this restarts tuwunel onto it.
#
# `Restart=on-failure` covers a sealed store or one still starting;
# the start timeout is bounded for the reason
# the timer below repeats the run, which a unit without `RemainAfterExit` allows.
# The start timeout is bounded for the reason
# ./swarm-secret-publisher.nix states: a sealed store answers on the
# port and never answers the read.
systemd.services.swarm-matrix-appservice-publish = lib.mkIf ctlActive {
description = "publish the swarm's appservice token to the swarm secret store";
systemd.services.swarm-matrix-appservice-sync = lib.mkIf ctlActive {
description = "keep the swarm's appservice registration in step with the swarm secret store";
after = [ "swarm-matrix-appservice-render.service" ];
requires = [ "swarm-matrix-appservice-render.service" ];
wantedBy = [ "multi-user.target" ];
path = [ pkgs.systemd ];
serviceConfig = {
Type = "oneshot";
ExecStart = "${deployCfg.matrix.ctlPackage}/bin/swarm-matrix-ctl appservice publish";
ExecStart = "${deployCfg.matrix.ctlPackage}/bin/swarm-matrix-ctl appservice sync";
Restart = "on-failure";
RestartSec = 30;
TimeoutStartSec = 60;
@ -1053,12 +1066,19 @@ in
BAO_CLIENT_KEY = deployCfg.matrix.ctlBaoClientKeyFile;
MATRIX_APPSERVICE_CERT_ROLE = ctlCertRole;
MATRIX_APPSERVICE_DIR = swarmAppserviceDir;
MATRIX_APPSERVICE_SENDER = swarmSenderLocalpart;
MATRIX_APPSERVICE_USER_REGEX = appserviceUserRegex;
MATRIX_APPSERVICE_RESTART_UNIT = "tuwunel.service";
}
// lib.optionalAttrs (deployCfg.bao.serverCaFile != null) {
BAO_CACERT = deployCfg.bao.serverCaFile;
};
};
systemd.timers.swarm-matrix-appservice-sync = lib.mkIf ctlActive (
storeRefreshTimer "re-read the swarm's appservice registration from the swarm secret store"
);
environment.systemPackages = [ deployCfg.matrix.package ];
};
};

35
nix/host-modules/swarm-bao.nix
View file

@ -618,7 +618,7 @@ let
matrixCtlPolicyName = "swarm-matrix-ctl";
matrixCtlCn = baoDeploy.matrixCtlCommonName;
# Three paths, each spelled to the leaf, and every narrowing in them is
# Four paths, each spelled to the leaf, and every narrowing in them is
# load-bearing.
#
# `secret/data/` is KV v2's ACL prefix, inserted by the engine rather than
@ -628,18 +628,27 @@ let
# to overwrite Grafana's OIDC client. The paths are spelled to the leaf for
# that reason, not for tidiness.
#
# The first is the swarm appservice's token, which matrix-ctl mints inside
# the container and publishes here for the controller. `read` as well as
# write, unlike either sibling, because publish compares before it writes.
# The first is the swarm appservice's token, which matrix-ctl derives from
# the registration and publishes here for the controller. `read` as well as
# write, unlike either sibling, because sync compares before it writes.
#
# The second is the homeserver's own OIDC client secret, read-only:
# The second is the registration's tokens: the store's copy, which matrix-ctl
# seeds from the container's state dir and then follows. `create` and `read`
# only, never `update`: a registration that exists is replaced by an
# operator, not by a unit.
#
# The third is the homeserver's own OIDC client secret, read-only:
# `swarm-bao-matrix-oidc` on the homeserver's host reads it under this leaf.
# The third, also read-only, is the client secret of the journal forwarder in
# The fourth, also read-only, is the client secret of the journal forwarder in
# the homeserver's container.
matrixCtlPolicyText = ''
path "${credentialMountPath}/data/${swarmAppserviceTokenLeaf}" {
capabilities = ["create", "update", "read"]
}
path "${credentialMountPath}/data/${swarmAppserviceRegistrationLeaf}" {
capabilities = ["create", "read"]
}
''
+ readStanza "${credentialMountPath}/data/swarm/services/${hyperhiveCfg.swarm.matrix.sso.clientId}/oidc/client"
+ readStanza "${credentialMountPath}/data/swarm/services/${hyperhiveCfg.swarm.matrix.otel.clientId}/oidc/client";
@ -650,6 +659,11 @@ let
# homeserver's admin.
swarmAppserviceTokenLeaf = "swarm/controller/swarm-controller/matrix/appservice-token";
# The swarm appservice registration's leaf, the nix half of
# `swarm_secret_client::matrix::swarm_appservice_registration_path`. Only
# matrix-ctl reaches it; the controller reads the token above, not this.
swarmAppserviceRegistrationLeaf = "swarm/controller/swarm-controller/matrix/appservice-registration";
# The controller's own OIDC client secret, the nix half of
# `swarm_secret_client::queue::controller_client_path`. The publisher writes
# it; the controller reads it and holds no other copy.
@ -1902,12 +1916,13 @@ in
example = "swarm-matrix-ctl.svc";
description = ''
Subject the store's matrix-ctl cert-auth role accepts — the
identity the matrix container's `swarm-matrix-appservice-publish`
unit presents when it publishes the swarm appservice's token.
identity the matrix container's `swarm-matrix-appservice-sync`
unit presents when it syncs the swarm appservice's registration and
publishes its token.
A **third** identity rather than reuse of either sibling above. Its
grant is that credential itself, plus read on two OIDC client
secrets: the homeserver's, fetched by `swarm-bao-matrix-oidc`, and
grant is that credential and the registration it derives from, plus
read on two OIDC client secrets: the homeserver's, fetched by `swarm-bao-matrix-oidc`, and
that of the journal forwarder in the homeserver's container. The
point of the whole arrangement is that the
process holding the appservice token is not the hive, so handing it

27
nix/module-eval/bao-grants.nix
View file

@ -575,12 +575,13 @@ let
# prefix the publisher holds would be a real loss even though it would
# read as tidier.
#
# The first leaf is the swarm appservice token, which matrix-ctl mints
# and publishes for the controller; the second and third are the
# homeserver's own OIDC client secret and its container forwarder's,
# read-only. The whole list, so a fourth stanza fails rather than riding
# The first leaf is the swarm appservice token, which matrix-ctl derives
# and publishes for the controller; the second is the registration it
# derives that from, `create` and `read` only; the third and fourth are
# the homeserver's own OIDC client secret and its container forwarder's,
# read-only. The whole list, so a fifth stanza fails rather than riding
# along beside correct ones.
name = "matrix-ctl's grant is the swarm appservice token and the homeserver's and its forwarder's OIDC secrets, nothing else";
name = "matrix-ctl's grant is the swarm appservice token and registration and the homeserver's and its forwarder's OIDC secrets, nothing else";
ok =
let
s = baoGrantHere.systemd.services.swarm-bao-matrix-ctl-policy.script;
@ -594,6 +595,13 @@ let
"read"
];
}
{
path = "secret/data/swarm/controller/swarm-controller/matrix/appservice-registration";
caps = [
"create"
"read"
];
}
{
path = "secret/data/swarm/services/tuwunel/oidc/client";
caps = [ "read" ];
@ -611,8 +619,9 @@ let
}
{
# 🩸 `read` is load-bearing here, unlike on the publisher: matrix-ctl's
# `appservice publish` reads the swarm appservice token back and writes
# only when the store's copy differs.
# `appservice sync` reads the swarm appservice token back and writes
# only when the store's copy differs, and reads the registration before
# it creates it.
name = "matrix-ctl may read back what it writes";
ok =
let
@ -2238,7 +2247,9 @@ let
# it: matrix-ctl is its one writer. Pinned as the whole stanza, so an
# added capability fails.
name = "the controller reads the swarm appservice token and cannot write it";
ok = lib.hasInfix "path \"secret/data/swarm/controller/swarm-controller/matrix/appservice-token\" {\n capabilities = [\"read\"]\n}" baoGrantHere.systemd.services.swarm-bao-controller-policy.script;
ok =
lib.hasInfix "path \"secret/data/swarm/controller/swarm-controller/matrix/appservice-token\" {\n capabilities = [\"read\"]\n}" baoGrantHere.systemd.services.swarm-bao-controller-policy.script
&& !(lib.hasInfix "appservice-registration" baoGrantHere.systemd.services.swarm-bao-controller-policy.script);
}
{
# The controller's own OIDC client secret, which the publisher writes and

63
nix/module-eval/bao-matrix-reader.nix
View file

@ -171,7 +171,7 @@ let
ok =
let
env =
baoWithMatrix.containers.hive-matrix.config.systemd.services.swarm-matrix-appservice-publish.environment;
baoWithMatrix.containers.hive-matrix.config.systemd.services.swarm-matrix-appservice-sync.environment;
hiveLeaf = baoWithMatrix.services.hyperhive.deploy.bao.clientCertFile;
in
env.BAO_CLIENT_CERT == "/var/lib/swarm-bao-pki/matrix-ctl.pem" && env.BAO_CLIENT_CERT != hiveLeaf;
@ -193,24 +193,26 @@ let
# agreement the unit cannot get wrong, and the verb: a bare invocation
# exits non-zero with clap's usage, a deploy-time failure with no local
# signal.
name = "the publish unit is handed the store role and invokes its verb";
name = "the sync unit is handed the store role, the sender and the homeserver unit, and invokes its verb";
ok =
let
u = baoWithMatrix.containers.hive-matrix.config.systemd.services.swarm-matrix-appservice-publish;
u = baoWithMatrix.containers.hive-matrix.config.systemd.services.swarm-matrix-appservice-sync;
in
u.environment.MATRIX_APPSERVICE_CERT_ROLE == "swarm-matrix-ctl"
&& lib.hasSuffix "/bin/swarm-matrix-ctl appservice publish" u.serviceConfig.ExecStart;
&& u.environment.MATRIX_APPSERVICE_RESTART_UNIT == "tuwunel.service"
&& u.environment.MATRIX_APPSERVICE_SENDER == "swarm"
&& lib.hasSuffix "/bin/swarm-matrix-ctl appservice sync" u.serviceConfig.ExecStart;
}
{
# 🩸 A secret is a path, never a value. Every variable the unit is given
# names a file or an address; the token itself is read out of the state
# dir at runtime, so nothing here can be a token and an environment block
# is world-readable through `systemctl show`.
name = "the publish unit's environment carries paths and addresses, never a token";
name = "the sync unit's environment carries paths and addresses, never a token";
ok =
let
env =
baoWithMatrix.containers.hive-matrix.config.systemd.services.swarm-matrix-appservice-publish.environment;
baoWithMatrix.containers.hive-matrix.config.systemd.services.swarm-matrix-appservice-sync.environment;
in
!(lib.any (v: lib.hasInfix "as_token" v || lib.hasInfix "syt_" v) (lib.attrValues env));
}
@ -272,6 +274,52 @@ let
&& lib.hasSuffix "swarm-matrix-ctl appservice render" r.serviceConfig.ExecStart
&& !(r.environment ? BAO_ADDR);
}
{
# The start path stays free of the store. The render is what tuwunel
# waits for and it carries no store address or identity; the sync unit
# that does is neither before tuwunel nor required by it, and tuwunel
# names it nowhere, so a store outage leaves the homeserver starting on
# the state dir's last copy. The presence arms are the render's own
# ordering (the same lookup finds `before`/`requiredBy` where they are)
# and the sync's order after the render.
name = "the sync unit is off tuwunel's start path and the render holds no store identity";
ok =
let
c = baoWithMatrix.containers.hive-matrix.config.systemd;
r = c.services.swarm-matrix-appservice-render;
s = c.services.swarm-matrix-appservice-sync;
t = c.services.tuwunel;
names =
u:
lib.concatLists [
(u.after or [ ])
(u.requires or [ ])
(u.wants or [ ])
(u.bindsTo or [ ])
];
sync = "swarm-matrix-appservice-sync.service";
in
lib.elem "tuwunel.service" r.before
&& lib.elem "swarm-matrix-appservice-render.service" s.after
&& !(lib.elem "tuwunel.service" (s.before or [ ]))
&& !(lib.elem "tuwunel.service" (s.requiredBy or [ ]))
&& !(lib.elem "tuwunel.service" (s.wantedBy or [ ]))
&& !(lib.elem sync (names t))
&& !(lib.elem sync (r.before or [ ]))
&& !(lib.any (lib.hasPrefix "BAO_") (lib.attrNames r.environment));
}
{
# A timer repeats the sync, which needs a unit that does not stay
# `active` after a run.
name = "the sync unit is repeated by a timer and does not stay active";
ok =
let
c = baoWithMatrix.containers.hive-matrix.config.systemd;
in
c.timers.swarm-matrix-appservice-sync.timerConfig.OnUnitInactiveSec == "10min"
&& !(c.services.swarm-matrix-appservice-sync.serviceConfig.RemainAfterExit or false)
&& (c.services.swarm-matrix-appservice-render.serviceConfig.RemainAfterExit or false);
}
{
# The absence arm for the four above: with no matrix-ctl identity there
# is nobody to publish the swarm token, so no admin, no registration and
@ -284,7 +332,8 @@ let
in
!(g ? admin_execute)
&& !(c.systemd.services ? swarm-matrix-appservice-render)
&& !(c.systemd.services ? swarm-matrix-appservice-publish)
&& !(c.systemd.services ? swarm-matrix-appservice-sync)
&& !(c.systemd.timers ? swarm-matrix-appservice-sync)
&& !(lib.any (lib.hasPrefix "swarm-appservice.yaml") c.systemd.services.tuwunel.serviceConfig.LoadCredential);
}
];

2
swarm-controller/src/matrix_account/agent_token.rs
View file

@ -117,7 +117,7 @@ pub(super) async fn appservice_token(store: &SecretStore) -> Result<String> {
Some(c) if !c.value.trim().is_empty() => Ok(c.value.trim().to_owned()),
_ => bail!(
"nothing at {path}: the matrix container has not published the swarm \
appservice token (swarm-matrix-appservice-publish)"
appservice token (swarm-matrix-appservice-sync)"
),
}
}

15
swarm-matrix-ctl/README.md
View file

@ -13,13 +13,18 @@ crate.
### `appservice render`
Mints the swarm appservice registration's tokens when absent and renders the
registration tuwunel loads. Runs before the homeserver and needs no network.
Renders the swarm appservice registration tuwunel loads from the tokens in the
state dir, minting them only on a host that has none. Runs before the
homeserver and needs no network: the tokens on disk are the last copy `sync`
took from the store.
### `appservice publish`
### `appservice sync`
Writes the rendered `as_token` to the swarm secret store for `swarm-controller`,
when the store's copy differs.
The store holds the registration's tokens. This writes them into the state dir
when they differ, restarts the homeserver whenever the registration is
newer than its last start, and publishes the `as_token` for `swarm-controller`. A store holding none is seeded from the
state dir, create-only, so nothing rotates. It runs beside the homeserver, so a
store outage leaves the homeserver running on the last copy.
Both are configured entirely by the `MATRIX_APPSERVICE_*` environment the units
set — no flags. A systemd `Environment=` block is what a nix module can render; a

790
swarm-matrix-ctl/src/appservice.rs
View file

@ -1,38 +1,38 @@
//! `swarm-matrix-ctl appservice` — the **swarm's** own appservice
//! registration: minted here, loaded by the homeserver beside us, and published
//! to the one store path `swarm-controller` reads it from.
//! registration. The store holds it; this container keeps a copy the
//! homeserver starts from.
//!
//! Two verbs, because they have opposite failure rules:
//!
//! - [`render`] runs before tuwunel and touches nothing but this container's
//! state dir. tuwunel loads the file it writes through `LoadCredential`, and
//! a missing credential source fails the homeserver's start, so this half
//! must not be able to fail on a network.
//! - [`publish`] runs after it and needs the store. A sealed store delays it
//! must not be able to fail on a network. It renders from the tokens on
//! disk, which are the last copy [`sync`] took from the store, and mints
//! them only on a host that has none.
//! - [`sync`] runs beside the homeserver, never before it, and needs the store.
//! The store's tokens win: it writes the state dir only when they differ, and
//! restarts the homeserver whenever the registration is newer than the
//! homeserver's last start. A store holding none is seeded from
//! the state dir, create-only, so nothing rotates. A sealed store delays it
//! and nothing else.
//!
//! "Only once": the token file in the state dir is the record. [`render`]
//! mints only when it is absent and re-renders from it every time; [`publish`]
//! writes the store only when the store's copy differs.
//!
//! This registration's sender is promoted to homeserver admin at boot
//! (`nix/host-modules/hive-matrix.nix`), which is why its token goes to
//! `swarm_secret_client::matrix::swarm_appservice_token_path` — a path no
//! hive's policy reaches — and to nowhere else.
//! (`nix/host-modules/hive-matrix.nix`), which is why its `as_token` goes to
//! `swarm_secret_client::matrix::swarm_appservice_token_path` for
//! `swarm-controller` — a path no hive's policy reaches — and to nowhere else.
use std::io::Write as _;
use std::os::unix::fs::OpenOptionsExt as _;
use std::path::{Path, PathBuf};
use anyhow::{Context, Result};
use anyhow::{Context, Result, bail};
use swarm_secret_client::{
SecretStore,
client::{DEFAULT_CERT_MOUNT, Settings},
matrix,
matrix::{self, Registration},
};
use crate::registration;
/// This container's state dir for the registration and its two tokens.
const ENV_DIR: &str = "MATRIX_APPSERVICE_DIR";
/// The registration's `sender_localpart`: the account the homeserver creates
@ -40,8 +40,11 @@ const ENV_DIR: &str = "MATRIX_APPSERVICE_DIR";
const ENV_SENDER: &str = "MATRIX_APPSERVICE_SENDER";
/// The user namespace regex, rendered by nix.
const ENV_USER_REGEX: &str = "MATRIX_APPSERVICE_USER_REGEX";
/// Role on the store's `cert` auth mount that [`publish`] logs in with.
/// Role on the store's `cert` auth mount that [`sync`] logs in with.
const ENV_CERT_ROLE: &str = "MATRIX_APPSERVICE_CERT_ROLE";
/// The unit that loads the registration, which [`sync`] restarts when the
/// registration is newer than its last start.
const ENV_RESTART_UNIT: &str = "MATRIX_APPSERVICE_RESTART_UNIT";
/// The registration's `id`.
const ID: &str = "swarm";
@ -85,11 +88,8 @@ fn render_into(dir: &Path, sender: &str, regex: &str) -> Result<()> {
/// The token at `path`, minting and writing one first when there is none.
fn existing_or_minted(path: &Path) -> Result<String> {
match std::fs::read_to_string(path) {
Ok(t) if !t.trim().is_empty() => return Ok(t.trim().to_owned()),
Ok(_) => {}
Err(e) if e.kind() == std::io::ErrorKind::NotFound => {}
Err(e) => return Err(e).with_context(|| format!("reading {}", path.display())),
if let Some(t) = read_token(path)? {
return Ok(t);
}
let token = swarm_matrix_client::random_hex(TOKEN_BYTES)?;
write_secret(path, &token)?;
@ -97,6 +97,16 @@ fn existing_or_minted(path: &Path) -> Result<String> {
Ok(token)
}
/// The trimmed token at `path`; `None` when the file is missing or blank.
fn read_token(path: &Path) -> Result<Option<String>> {
match std::fs::read_to_string(path) {
Ok(t) if !t.trim().is_empty() => Ok(Some(t.trim().to_owned())),
Ok(_) => Ok(None),
Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(None),
Err(e) => Err(e).with_context(|| format!("reading {}", path.display())),
}
}
/// Write `contents` to `path` as a `0600` file, through a rename so a reader
/// never sees half of it.
fn write_secret(path: &Path, contents: &str) -> Result<()> {
@ -136,23 +146,74 @@ fn registration_yaml(sender: &str, regex: &str, as_token: &str, hs_token: &str)
)
}
/// Whether the store needs the local token written to it.
fn needs_publish(stored: Option<&matrix::Credential>, local: &str) -> bool {
stored.is_none_or(|c| c.value.trim() != local)
/// What [`sync`] needs of the store, so the decisions can be tested without
/// one.
trait Store {
/// The registration's tokens, or `None` when nothing is stored.
async fn registration(&self) -> Result<Option<Registration>>;
/// Store `r` only if nothing is stored yet.
async fn create_registration(&self, r: &Registration) -> Result<()>;
/// What `swarm-controller` reads.
async fn controller_token(&self) -> Result<Option<matrix::Credential>>;
async fn write_controller_token(&self, as_token: &str) -> Result<()>;
}
/// Write the rendered registration's `as_token` to the store, unless the store
/// already holds it.
/// The real store, logged in as matrix-ctl.
struct Bao(SecretStore);
impl Store for Bao {
async fn registration(&self) -> Result<Option<Registration>> {
let path = matrix::swarm_appservice_registration_path()?;
self.0
.read_optional(&path)
.await
.with_context(|| format!("reading {path}"))
}
async fn create_registration(&self, r: &Registration) -> Result<()> {
let path = matrix::swarm_appservice_registration_path()?;
self.0
.create(&path, r)
.await
.with_context(|| format!("creating {path}"))
}
async fn controller_token(&self) -> Result<Option<matrix::Credential>> {
let path = matrix::swarm_appservice_token_path()?;
self.0
.read_optional(&path)
.await
.with_context(|| format!("reading {path}"))
}
async fn write_controller_token(&self, as_token: &str) -> Result<()> {
let path = matrix::swarm_appservice_token_path()?;
self.0
.write(
&path,
&matrix::Credential {
value: as_token.to_owned(),
homeserver: None,
},
)
.await
.with_context(|| format!("writing {path}"))
}
}
/// Make the state dir hold the store's registration, and the controller's token
/// match it.
///
/// # Errors
/// If a variable is missing, the registration has not been rendered, or the
/// store refuses the login, the read or the write.
pub async fn publish() -> Result<()> {
/// If a variable is missing, the store refuses the login, a read or a write,
/// the state dir cannot be written, or the homeserver cannot be restarted.
pub async fn sync() -> Result<()> {
let get = |k: &str| std::env::var(k).ok();
let dir = PathBuf::from(required(&get, ENV_DIR)?);
let sender = required(&get, ENV_SENDER)?;
let regex = required(&get, ENV_USER_REGEX)?;
let cert_role = required(&get, ENV_CERT_ROLE)?;
let registration = dir.join(REGISTRATION);
let local = registration::as_token(&registration.to_string_lossy())?;
let unit = required(&get, ENV_RESTART_UNIT)?;
let settings = Settings::from_env().context("reading the store's BAO_* environment")?;
let store = SecretStore::connect(&settings, &cert_role, DEFAULT_CERT_MOUNT)
@ -160,31 +221,228 @@ pub async fn publish() -> Result<()> {
.with_context(|| {
format!("logging in to the swarm secret store as cert role {cert_role}")
})?;
let path = matrix::swarm_appservice_token_path()?;
let stored: Option<matrix::Credential> = store
.read_optional(&path)
.await
.with_context(|| format!("reading {path}"))?;
if !needs_publish(stored.as_ref(), &local) {
tracing::info!(%path, "the swarm appservice token is already published");
return Ok(());
sync_with(&Bao(store), &dir, &sender, &regex, mint, &Systemd(unit)).await
}
/// [`sync`] against an explicit store, directory and homeserver unit.
///
/// The store's registration wins. Where it holds none, the state dir's tokens
/// seed it, and only a host with neither mints a pair. The homeserver is
/// restarted whenever the registration was written after it last started, so
/// a run that failed between the write and the restart is finished by the next.
async fn sync_with(
store: &impl Store,
dir: &Path,
sender: &str,
regex: &str,
mint: impl FnOnce() -> Result<Registration>,
unit: &impl Homeserver,
) -> Result<()> {
let local = read_local(dir)?;
let current = stored_or_seeded(store, local.as_ref(), mint).await?;
let want = registration_yaml(sender, regex, &current.as_token, &current.hs_token);
let have = std::fs::read_to_string(dir.join(REGISTRATION)).ok();
if local.as_ref() != Some(&current) || have.as_deref() != Some(&want) {
write_secret(&dir.join(AS_TOKEN), &current.as_token)?;
write_secret(&dir.join(HS_TOKEN), &current.hs_token)?;
write_secret(&dir.join(REGISTRATION), &want)?;
tracing::info!("took the swarm appservice registration from the store");
}
restart_if_stale(unit, &dir.join(REGISTRATION))?;
if needs_publish(store.controller_token().await?.as_ref(), &current.as_token) {
store.write_controller_token(&current.as_token).await?;
tracing::info!("published the swarm appservice token for the controller");
}
Ok(())
}
/// The store's registration; where it holds none, `local` or a minted pair is
/// created there first. A refused create is a lost race or a denial, and the
/// read-back tells which: it finds the winner's value, or nothing.
async fn stored_or_seeded(
store: &impl Store,
local: Option<&Registration>,
mint: impl FnOnce() -> Result<Registration>,
) -> Result<Registration> {
if let Some(stored) = store.registration().await? {
return Ok(stored);
}
let seed = match local {
Some(l) => l.clone(),
None => mint()?,
};
if let Err(e) = store.create_registration(&seed).await {
tracing::warn!(error = %e, "could not create the swarm appservice registration; reading it back");
}
store
.write(
&path,
&matrix::Credential {
value: local,
homeserver: None,
},
)
.await
.with_context(|| format!("writing the swarm appservice token to {path}"))?;
tracing::info!(%path, "published the swarm appservice token");
Ok(())
.registration()
.await?
.context("the store holds no swarm appservice registration after creating one")
}
/// The tokens on disk, when both are there.
fn read_local(dir: &Path) -> Result<Option<Registration>> {
let as_token = read_token(&dir.join(AS_TOKEN))?;
let hs_token = read_token(&dir.join(HS_TOKEN))?;
Ok(as_token
.zip(hs_token)
.map(|(as_token, hs_token)| Registration { as_token, hs_token }))
}
fn mint() -> Result<Registration> {
Ok(Registration {
as_token: swarm_matrix_client::random_hex(TOKEN_BYTES)?,
hs_token: swarm_matrix_client::random_hex(TOKEN_BYTES)?,
})
}
/// Whether the store needs the local token written to it.
fn needs_publish(stored: Option<&matrix::Credential>, local: &str) -> bool {
stored.is_none_or(|c| c.value.trim() != local)
}
/// What [`sync`] needs of the unit that loads the registration.
trait Homeserver {
/// When the unit last became active, in microseconds since the epoch;
/// `None` when it never has.
fn started_us(&self) -> Result<Option<u64>>;
/// Restart it onto the registration on disk.
fn restart(&self) -> Result<()>;
}
/// The real unit, through `systemctl`.
struct Systemd(String);
impl Homeserver for Systemd {
fn started_us(&self) -> Result<Option<u64>> {
let out = std::process::Command::new("systemctl")
.args([
"show",
"--timestamp=us+utc",
"-p",
"ActiveEnterTimestamp",
"--value",
])
.arg(&self.0)
.output()
.context("running systemctl show")?;
if !out.status.success() {
bail!("systemctl show {} exited with {}", self.0, out.status);
}
parse_timestamp_us(String::from_utf8_lossy(&out.stdout).trim())
}
fn restart(&self) -> Result<()> {
restart_via(&self.0, systemctl)
}
}
/// Restart the homeserver when the registration on disk is newer than its last
/// start. Derived from the files and the unit on every run rather than from
/// what this run wrote, so a run that failed after writing is retried by the
/// next. A start time that cannot be read leaves the unit as it is: the next
/// run decides again.
fn restart_if_stale(unit: &impl Homeserver, registration: &Path) -> Result<()> {
let started = match unit.started_us() {
Ok(started) => started.unwrap_or(0),
Err(e) => {
tracing::warn!(error = %e, "cannot tell when the homeserver last started; leaving it as it is");
return Ok(());
}
};
let written = std::fs::metadata(registration)
.and_then(|m| m.modified())
.with_context(|| format!("reading the time of {}", registration.display()))?
.duration_since(std::time::UNIX_EPOCH)
.context("the registration is dated before the epoch")?
.as_micros();
if written <= u128::from(started) {
return Ok(());
}
tracing::info!("the registration is newer than the homeserver's start; restarting it");
unit.restart()
.context("restarting the homeserver onto the new registration")
}
/// `systemctl systemd-timestamp` output (`--timestamp=us+utc`, for example
/// `Tue 2026-10-27 12:00:00.123456 UTC`) as microseconds since the epoch. Empty
/// is `None`: a unit that never became active has no timestamp.
fn parse_timestamp_us(s: &str) -> Result<Option<u64>> {
if s.is_empty() {
return Ok(None);
}
let bad = || anyhow::anyhow!("unreadable systemd timestamp {s:?}");
let token = |sep: char| {
s.split_whitespace()
.find(|t| t.contains(sep))
.ok_or_else(bad)
};
let numbers = |text: &str, sep: char| -> Result<Vec<i64>> {
text.split(sep)
.map(|n| n.parse().map_err(|_| bad()))
.collect()
};
let time = token(':')?;
let (clock, fraction) = time.split_once('.').unwrap_or((time, ""));
let [year, month, day] = numbers(token('-')?, '-')?[..] else {
return Err(bad());
};
let [hour, minute, second] = numbers(clock, ':')?[..] else {
return Err(bad());
};
let micros: i64 = format!("{fraction:0<6}")[..6].parse().map_err(|_| bad())?;
// Days since 1970-01-01 of a proleptic Gregorian date.
let year = if month <= 2 { year - 1 } else { year };
let era = year.div_euclid(400);
let year_of_era = year - era * 400;
let day_of_year = (153 * ((month + 9) % 12) + 2) / 5 + day - 1;
let day_of_era = year_of_era * 365 + year_of_era / 4 - year_of_era / 100 + day_of_year;
let days = era * 146_097 + day_of_era - 719_468;
let seconds = days * 86_400 + hour * 3600 + minute * 60 + second;
u64::try_from(seconds * 1_000_000 + micros)
.map(Some)
.map_err(|_| bad())
}
/// Run `systemctl` with `args`, returning its exit status.
fn systemctl(args: &[&str]) -> Result<std::process::ExitStatus> {
std::process::Command::new("systemctl")
.args(args)
.status()
.with_context(|| format!("running systemctl {}", args.join(" ")))
}
/// Restart `unit` onto the new registration: a running one is restarted, and a
/// failed one — it may have failed for want of the file — is reset and started.
/// One stopped on purpose stays stopped. `--no-block`, so this run does not
/// wait on the homeserver's start. Every call but the `is-failed` probe must
/// exit zero.
fn restart_via(
unit: &str,
run: impl Fn(&[&str]) -> Result<std::process::ExitStatus>,
) -> Result<()> {
let must = |args: &[&str]| {
let status = run(args)?;
if status.success() {
Ok(())
} else {
bail!("systemctl {} exited with {status}", args.join(" "))
}
};
if run(&["is-failed", "--quiet", unit])?.success() {
must(&["reset-failed", unit])?;
must(&["start", "--no-block", unit])
} else {
must(&["try-restart", "--no-block", unit])
}
}
#[cfg(test)]
mod tests {
use std::cell::{Cell, RefCell};
use super::*;
const REGEX: &str = "^@[a-z0-9._=/-]+:t\\.local$";
@ -202,24 +460,152 @@ mod tests {
dir
}
fn reg(tag: &str) -> Registration {
Registration {
as_token: format!("as-{tag}"),
hs_token: format!("hs-{tag}"),
}
}
/// A store in memory. `down` fails every call, as a sealed or unreachable
/// store does; `racer` is what another writer stores between this run's
/// read and its create.
#[derive(Default)]
struct Fake {
registration: RefCell<Option<Registration>>,
token: RefCell<Option<String>>,
down: bool,
racer: RefCell<Option<Registration>>,
creates: Cell<u32>,
token_writes: Cell<u32>,
}
impl Store for Fake {
async fn registration(&self) -> Result<Option<Registration>> {
if self.down {
bail!("the store is down");
}
Ok(self.registration.borrow().clone())
}
async fn create_registration(&self, r: &Registration) -> Result<()> {
self.creates.set(self.creates.get() + 1);
if let Some(winner) = self.racer.borrow_mut().take() {
*self.registration.borrow_mut() = Some(winner);
bail!("already created");
}
*self.registration.borrow_mut() = Some(r.clone());
Ok(())
}
async fn controller_token(&self) -> Result<Option<matrix::Credential>> {
Ok(self.token.borrow().clone().map(|value| matrix::Credential {
value,
homeserver: None,
}))
}
async fn write_controller_token(&self, as_token: &str) -> Result<()> {
self.token_writes.set(self.token_writes.get() + 1);
*self.token.borrow_mut() = Some(as_token.to_owned());
Ok(())
}
}
/// Write the state dir as `render` leaves it for `r`.
fn host_with(dir: &Path, r: &Registration) {
write_secret(&dir.join(AS_TOKEN), &r.as_token).expect("as");
write_secret(&dir.join(HS_TOKEN), &r.hs_token).expect("hs");
write_secret(
&dir.join(REGISTRATION),
&registration_yaml("swarm", REGEX, &r.as_token, &r.hs_token),
)
.expect("yaml");
}
fn files(dir: &Path) -> Vec<String> {
[AS_TOKEN, HS_TOKEN, REGISTRATION]
.iter()
.map(|f| std::fs::read_to_string(dir.join(f)).unwrap_or_default())
.collect()
}
/// The homeserver unit. `started` is when it last became active; a restart
/// that succeeds makes it later than every file.
struct Unit {
started: Cell<Option<u64>>,
fail_restart: Cell<bool>,
restarts: Cell<u32>,
}
impl Unit {
/// Last started at the epoch, before any file in a test.
fn long_running() -> Self {
Self::started(Some(1))
}
/// Last started after every file in a test.
fn just_started() -> Self {
Self::started(Some(u64::MAX))
}
fn started(at: Option<u64>) -> Self {
Self {
started: Cell::new(at),
fail_restart: Cell::new(false),
restarts: Cell::new(0),
}
}
}
impl Homeserver for Unit {
fn started_us(&self) -> Result<Option<u64>> {
Ok(self.started.get())
}
fn restart(&self) -> Result<()> {
self.restarts.set(self.restarts.get() + 1);
if self.fail_restart.get() {
bail!("systemctl refused");
}
self.started.set(Some(u64::MAX));
Ok(())
}
}
/// Run one sync against `unit`, returning how often it minted.
async fn run(store: &Fake, dir: &Path, unit: &Unit) -> (Result<()>, u32) {
let mints = Cell::new(0);
let out = sync_with(
store,
dir,
"swarm",
REGEX,
|| {
mints.set(mints.get() + 1);
Ok(reg("minted"))
},
unit,
)
.await;
(out, mints.get())
}
#[test]
fn the_rendered_registration_carries_the_token_it_minted() {
let dir = scratch();
render_into(&dir, "swarm", REGEX).expect("renders");
let token = registration::as_token(&dir.join(REGISTRATION).to_string_lossy())
.expect("the as_token line parses");
let yaml = std::fs::read_to_string(dir.join(REGISTRATION)).expect("rendered");
let token = std::fs::read_to_string(dir.join(AS_TOKEN)).expect("minted");
assert_eq!(token.len(), TOKEN_BYTES * 2);
assert_eq!(
std::fs::read_to_string(dir.join(AS_TOKEN)).expect("minted"),
token
);
assert!(yaml.contains(&format!("\nas_token: {token}\n")), "{yaml}");
std::fs::remove_dir_all(&dir).ok();
}
#[test]
fn a_second_render_keeps_the_token() {
// "Only once": a re-mint on every boot would hand the controller a
// token the homeserver no longer loads until publish catches up.
// token the homeserver no longer loads until sync catches up.
let dir = scratch();
render_into(&dir, "swarm", REGEX).expect("first");
let first = std::fs::read_to_string(dir.join(REGISTRATION)).expect("rendered");
@ -254,8 +640,288 @@ mod tests {
std::fs::remove_dir_all(&dir).ok();
}
#[tokio::test]
async fn seeding_from_the_host_leaves_every_file_unchanged() {
// A host that has run for months with the store empty: the store takes
// its value, and nothing on the host moves, so nothing rotates.
let dir = scratch();
let on_disk = reg("old");
host_with(&dir, &on_disk);
let before = files(&dir);
let store = Fake::default();
let unit = Unit::just_started();
let (out, mints) = run(&store, &dir, &unit).await;
let restarts = unit.restarts.get();
out.expect("syncs");
assert_eq!(*store.registration.borrow(), Some(on_disk));
assert_eq!(files(&dir), before);
assert_eq!(mints, 0, "a host that has the value mints nothing");
assert_eq!(restarts, 0, "an unchanged host does not restart");
assert_eq!(store.token.borrow().as_deref(), Some("as-old"));
std::fs::remove_dir_all(&dir).ok();
}
#[tokio::test]
async fn the_store_wins_when_both_hold_a_value() {
let dir = scratch();
host_with(&dir, &reg("disk"));
let store = Fake::default();
*store.registration.borrow_mut() = Some(reg("store"));
*store.token.borrow_mut() = Some("as-disk".to_owned());
let unit = Unit::long_running();
let (out, _) = run(&store, &dir, &unit).await;
let restarts = unit.restarts.get();
out.expect("syncs");
let want = registration_yaml("swarm", REGEX, "as-store", "hs-store");
assert_eq!(
files(&dir),
vec!["as-store".to_owned(), "hs-store".to_owned(), want]
);
assert_eq!(*store.registration.borrow(), Some(reg("store")));
assert_eq!(store.creates.get(), 0, "a held value is never rewritten");
assert_eq!(restarts, 1);
assert_eq!(store.token.borrow().as_deref(), Some("as-store"));
std::fs::remove_dir_all(&dir).ok();
}
#[tokio::test]
async fn a_host_without_the_files_takes_them_from_the_store() {
let dir = scratch();
let store = Fake::default();
*store.registration.borrow_mut() = Some(reg("store"));
let unit = Unit::long_running();
let (out, mints) = run(&store, &dir, &unit).await;
let restarts = unit.restarts.get();
out.expect("syncs");
assert_eq!(read_local(&dir).expect("reads"), Some(reg("store")));
assert!(dir.join(REGISTRATION).exists());
assert_eq!((restarts, mints), (1, 0));
std::fs::remove_dir_all(&dir).ok();
}
#[tokio::test]
async fn a_fresh_host_mints_into_the_store() {
let dir = scratch();
let store = Fake::default();
let unit = Unit::long_running();
let (out, mints) = run(&store, &dir, &unit).await;
let restarts = unit.restarts.get();
out.expect("syncs");
assert_eq!(mints, 1);
assert_eq!(*store.registration.borrow(), Some(reg("minted")));
assert_eq!(read_local(&dir).expect("reads"), Some(reg("minted")));
assert_eq!(restarts, 1);
std::fs::remove_dir_all(&dir).ok();
}
#[tokio::test]
async fn a_lost_race_adopts_the_winners_registration() {
let dir = scratch();
host_with(&dir, &reg("disk"));
let store = Fake::default();
*store.racer.borrow_mut() = Some(reg("winner"));
let unit = Unit::long_running();
let (out, _) = run(&store, &dir, &unit).await;
let restarts = unit.restarts.get();
out.expect("syncs");
assert_eq!(read_local(&dir).expect("reads"), Some(reg("winner")));
assert_eq!(restarts, 1);
std::fs::remove_dir_all(&dir).ok();
}
#[tokio::test]
async fn a_store_that_is_down_leaves_the_host_as_it_is() {
let dir = scratch();
host_with(&dir, &reg("disk"));
let before = files(&dir);
let store = Fake {
down: true,
..Fake::default()
};
let unit = Unit::just_started();
let (out, mints) = run(&store, &dir, &unit).await;
let restarts = unit.restarts.get();
assert!(out.is_err(), "the unit reports the outage");
assert_eq!(files(&dir), before, "the homeserver keeps the last copy");
assert_eq!((restarts, mints), (0, 0));
std::fs::remove_dir_all(&dir).ok();
}
#[tokio::test]
async fn the_start_path_renders_the_copy_sync_took_from_the_store() {
// `render` has no store: after an outage it renders what the last sync
// wrote, without minting over it.
let dir = scratch();
let store = Fake::default();
*store.registration.borrow_mut() = Some(reg("store"));
run(&store, &dir, &Unit::long_running())
.await
.0
.expect("syncs");
let synced = files(&dir);
render_into(&dir, "swarm", REGEX).expect("renders");
assert_eq!(files(&dir), synced);
std::fs::remove_dir_all(&dir).ok();
}
#[tokio::test]
async fn a_second_sync_restarts_nothing() {
let dir = scratch();
let store = Fake::default();
*store.registration.borrow_mut() = Some(reg("store"));
let unit = Unit::long_running();
run(&store, &dir, &unit).await.0.expect("first");
let first = unit.restarts.get();
let (out, _) = run(&store, &dir, &unit).await;
let second = unit.restarts.get() - first;
out.expect("syncs");
assert_eq!((first, second), (1, 0));
assert_eq!(
store.token_writes.get(),
1,
"the controller's copy is written once"
);
std::fs::remove_dir_all(&dir).ok();
}
#[tokio::test]
async fn a_restart_that_failed_is_retried_by_the_next_run() {
// The files are written and the restart is refused. The next run finds
// nothing to write, and still restarts: the decision comes from the
// files' age against the unit's start, not from this run's writes.
let dir = scratch();
let store = Fake::default();
*store.registration.borrow_mut() = Some(reg("store"));
let unit = Unit::long_running();
unit.fail_restart.set(true);
let (first, _) = run(&store, &dir, &unit).await;
assert!(first.is_err(), "the refused restart fails the run");
let written = files(&dir);
unit.fail_restart.set(false);
let (second, _) = run(&store, &dir, &unit).await;
second.expect("the retry succeeds");
assert_eq!(files(&dir), written, "nothing was left to write");
assert_eq!(unit.restarts.get(), 2);
assert_eq!(read_local(&dir).expect("reads"), Some(reg("store")));
std::fs::remove_dir_all(&dir).ok();
}
#[tokio::test]
async fn a_unit_that_started_after_the_files_is_left_alone() {
// The control for the retry above: the same files, a unit that started
// after them, and no restart.
let dir = scratch();
host_with(&dir, &reg("store"));
let store = Fake::default();
*store.registration.borrow_mut() = Some(reg("store"));
let unit = Unit::just_started();
run(&store, &dir, &unit).await.0.expect("syncs");
assert_eq!(unit.restarts.get(), 0);
std::fs::remove_dir_all(&dir).ok();
}
#[tokio::test]
async fn a_start_time_that_cannot_be_read_restarts_nothing() {
struct Unreadable(Cell<u32>);
impl Homeserver for Unreadable {
fn started_us(&self) -> Result<Option<u64>> {
bail!("no such unit")
}
fn restart(&self) -> Result<()> {
self.0.set(self.0.get() + 1);
Ok(())
}
}
let dir = scratch();
let store = Fake::default();
*store.registration.borrow_mut() = Some(reg("store"));
let unit = Unreadable(Cell::new(0));
let out = sync_with(&store, &dir, "swarm", REGEX, || Ok(reg("minted")), &unit).await;
out.expect("the run goes on");
assert_eq!(unit.0.get(), 0);
assert_eq!(store.token.borrow().as_deref(), Some("as-store"));
std::fs::remove_dir_all(&dir).ok();
}
/// `restart_via` against a `systemctl` that exits with the given codes for the
/// verbs named (zero for the rest), returning the verbs it was called with.
fn restart_script(exits: &[(&'static str, i32)]) -> (Result<()>, Vec<String>) {
use std::os::unix::process::ExitStatusExt as _;
let calls = RefCell::new(Vec::new());
let out = restart_via("tuwunel.service", |args| {
calls.borrow_mut().push(args[0].to_owned());
let code = exits.iter().find(|(v, _)| *v == args[0]).map_or(0, |e| e.1);
Ok(std::process::ExitStatus::from_raw(code << 8))
});
(out, calls.into_inner())
}
#[test]
fn publish_writes_only_what_the_store_lacks() {
fn a_running_unit_is_restarted_and_a_refusal_fails_the_run() {
let (out, calls) = restart_script(&[("is-failed", 1)]);
out.expect("restarts");
assert_eq!(calls, ["is-failed", "try-restart"]);
let (out, _) = restart_script(&[("is-failed", 1), ("try-restart", 1)]);
assert!(out.is_err());
}
#[test]
fn a_failed_unit_is_reset_and_started_and_a_refusal_of_either_fails_the_run() {
let (out, calls) = restart_script(&[]);
out.expect("resets and starts");
assert_eq!(calls, ["is-failed", "reset-failed", "start"]);
let (out, calls) = restart_script(&[("reset-failed", 1)]);
assert!(out.is_err(), "a refused reset fails the run");
assert_eq!(calls, ["is-failed", "reset-failed"], "and nothing starts");
let (out, _) = restart_script(&[("start", 1)]);
assert!(out.is_err(), "a refused start fails the run");
}
#[test]
fn systemd_timestamps_read_as_microseconds_since_the_epoch() {
let at = |s| parse_timestamp_us(s).expect("parses");
assert_eq!(at("Thu 1970-01-01 00:00:01.000002 UTC"), Some(1_000_002));
assert_eq!(
at("Wed 2000-03-01 00:00:00.5 UTC"),
Some(951_868_800_500_000)
);
assert_eq!(
at("Tue 2026-10-27 12:00:00 UTC"),
Some(1_793_102_400_000_000)
);
assert_eq!(at(""), None, "a unit that never started has none");
parse_timestamp_us("n/a garbage").expect_err("not a timestamp");
}
#[test]
fn the_controllers_copy_is_written_only_when_it_differs() {
let same = matrix::Credential {
value: "aa".to_owned(),
homeserver: None,
@ -271,7 +937,13 @@ mod tests {
#[test]
fn every_variable_is_scoped_to_the_verb() {
for var in [ENV_DIR, ENV_SENDER, ENV_USER_REGEX, ENV_CERT_ROLE] {
for var in [
ENV_DIR,
ENV_SENDER,
ENV_USER_REGEX,
ENV_CERT_ROLE,
ENV_RESTART_UNIT,
] {
assert!(var.starts_with("MATRIX_APPSERVICE_"), "{var}");
}
}

22
swarm-matrix-ctl/src/main.rs
View file

@ -8,14 +8,13 @@
//! here is a verb below, not a new crate.
//!
//! [`appservice`] mints the **swarm's** own appservice registration and
//! publishes its token for `swarm-controller`.
//! keeps it in step with the store and publishes its token for `swarm-controller`.
//!
//! 🩸 **A secret is a path, never a value.** The only identifier any verb here
//! logs is the store path; see `swarm_matrix_client`'s module doc for the same rule
//! applied to error messages.
mod appservice;
mod registration;
use anyhow::Result;
use clap::{Parser, Subcommand};
@ -43,9 +42,10 @@ enum Appservice {
/// Mint the tokens when absent and render the registration tuwunel loads.
/// Local only: it runs before the homeserver and must not need a network.
Render,
/// Write the rendered `as_token` to the swarm secret store when the
/// store's copy differs.
Publish,
/// Make the state dir hold the store's registration, seeding the store
/// from it when the store holds none, and restart the homeserver when the
/// registration is newer than its last start. Runs beside the homeserver, never before it.
Sync,
}
#[tokio::main]
@ -59,7 +59,7 @@ async fn main() -> Result<()> {
match Cli::parse().command {
Command::Appservice(Appservice::Render) => appservice::render(),
Command::Appservice(Appservice::Publish) => appservice::publish().await,
Command::Appservice(Appservice::Sync) => appservice::sync().await,
}
}
@ -83,12 +83,8 @@ mod tests {
cli.command,
Command::Appservice(Appservice::Render)
));
let cli =
Cli::try_parse_from(["swarm-matrix-ctl", "appservice", "publish"]).expect("a verb");
assert!(matches!(
cli.command,
Command::Appservice(Appservice::Publish)
));
let cli = Cli::try_parse_from(["swarm-matrix-ctl", "appservice", "sync"]).expect("a verb");
assert!(matches!(cli.command, Command::Appservice(Appservice::Sync)));
Cli::try_parse_from(["swarm-matrix-ctl", "appservice"])
.expect_err("a sub-verb is required");
}
@ -99,7 +95,7 @@ mod tests {
.expect_err("only declared verbs are accepted");
}
/// A bare invocation must not silently do something. `appservice publish`
/// A bare invocation must not silently do something. `appservice sync`
/// writes a credential, so "no verb" defaulting to it would make a typo in
/// the unit write rather than fail.
#[test]

102
swarm-matrix-ctl/src/registration.rs
View file

@ -1,102 +0,0 @@
//! Reading the `as_token` out of the appservice registration the matrix
//! container already has.
//!
//! No new credential is delivered for this. The registration **is** the
//! `as_token`, and `appservice render` writes it into this container's own
//! state dir — 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 (`registration_yaml` in `appservice.rs`, a `format!` 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 in the shape `registration_yaml` renders it, tokens
/// last. Reproduced rather than rendered so this module's tests do not
/// depend on the renderer's.
const RENDERED: &str = "id: swarm\n\
url: null\n\
sender_localpart: swarm\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: swarm\n", "as_token:\n", "as_token: \n"] {
assert!(extract(bad).is_err(), "{bad:?} must not yield a token");
}
}
}

68
swarm-secret-client/src/matrix.rs
View file

@ -129,6 +129,44 @@ pub fn swarm_appservice_token_path() -> Result<String, Error> {
Ok(format!("{prefix}/matrix/appservice-token"))
}
/// The path holding the swarm appservice's registration: the `as_token` and
/// `hs_token` the homeserver loads.
///
/// The store is the source of truth for both tokens. The matrix container keeps a
/// copy on disk that the homeserver starts from, and derives
/// [`swarm_appservice_token_path`] from the `as_token` here for
/// `swarm-controller`. It sits beside that path, under the one kind no hive's
/// policy reads, for the same reason.
///
/// # Errors
/// Never in practice: the name segment is a constant. The `Result` is
/// [`principal_prefix`]'s.
pub fn swarm_appservice_registration_path() -> Result<String, Error> {
let prefix = principal_prefix(Kind::Controller, CONTROLLER)?;
Ok(format!("{prefix}/matrix/appservice-registration"))
}
/// What [`swarm_appservice_registration_path`] holds. The registration's
/// namespaces are configuration rendered by nix, not part of it.
///
/// No `Debug` derive: both fields authenticate to the homeserver.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Registration {
/// The token the appservice presents to the homeserver.
pub as_token: String,
/// The token the homeserver presents to the appservice.
pub hs_token: String,
}
impl std::fmt::Debug for Registration {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Registration")
.field("as_token", &"<redacted>")
.field("hs_token", &"<redacted>")
.finish()
}
}
/// What an account's path holds: the token, plus the homeserver it belongs to.
///
/// The homeserver rides with the token because the agent's daemon learns both
@ -266,6 +304,28 @@ mod tests {
);
}
#[test]
fn the_swarm_appservice_registration_lands_beside_its_token() {
assert_eq!(
swarm_appservice_registration_path().expect("a constant segment"),
"swarm/controller/swarm-controller/matrix/appservice-registration"
);
}
#[test]
fn a_registration_debug_prints_no_token() {
let r = Registration {
as_token: "as-secret".to_owned(),
hs_token: "hs-secret".to_owned(),
};
let shown = format!("{r:?}");
assert!(
!shown.contains("as-secret") && !shown.contains("hs-secret"),
"{shown}"
);
assert!(shown.contains("Registration"), "{shown}");
}
#[test]
fn no_hive_policy_reaches_the_swarm_appservice_token() {
// 🩸 The swarm's sender is a homeserver admin, so its token must not
@ -280,8 +340,12 @@ mod tests {
.filter_map(|p| p.strip_suffix("*\" {"))
.collect();
let reads = |path: &str| granted.iter().any(|g| path.starts_with(g));
let path = swarm_appservice_token_path().expect("a constant segment");
assert!(!reads(&path), "{path} is readable under {granted:?}");
for path in [
swarm_appservice_token_path().expect("a constant segment"),
swarm_appservice_registration_path().expect("a constant segment"),
] {
assert!(!reads(&path), "{path} is readable under {granted:?}");
}
// The control: an agent's account path IS under a hive stanza, so the
// assertion above can fail at all.
let agent = account_path("atlas", "main").expect("legal");