# swarm-matrix-minter

A boot-time oneshot that runs **inside `containers.hive-matrix`**, beside the
homeserver, and puts the `@hive:` account's access token into the swarm's secret
store under an identity of its own.

## Why it lives in the matrix container

The credential it mints is authorised by the appservice `as_token`, and the
container already holds that: `nix/host-modules/hive-matrix.nix` bind-mounts the
rendered appservice registration into it read-only, because that is how tuwunel
itself is handed the registration. Minting anywhere else would mean copying the
`as_token` to a second holder — and the point of this component is that the hive
stops being one.

It is not the swarm controller for the same reason, plus a structural one: a
homeserver has exactly **one** `@hive:` account and a swarm runs one
homeserver, so "mint it once" needs no lock, no lease and no trigger surface — it
is a property of the thing being minted.

## Idempotency

The **store** is the key, not the homeserver. A run reads
`swarm/services/matrix/hive-access-token` first and returns without touching the
homeserver when something is already there. Only an empty path reaches the mint
ladder:

1. `POST /_matrix/client/v3/register` with `"type": "m.login.application_service"`
   — one round trip, no UIAA.
2. `M_USER_IN_USE` (the expected arm on a homeserver that has already loaded the
   registration, since the account is the appservice's own `sender_localpart`) →
   `POST /_matrix/client/v3/login` as the appservice, same pinned `device_id`, so
   the old device is replaced rather than duplicated.
3. Write the result to the store.

A crash between the homeserver call and the store write is recoverable: the next
run takes arm 2.

## 🩸 A secret is a path, never a value

Nothing here logs, prints or interpolates a token. The mint ladder's errors are
built from the homeserver's _status_ and its `errcode`, never its body, because a
`/login` response body is an access token. The one identifier this binary logs is
the store path it wrote.