vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

feat(nix): issue each hive's CA under a swarm root CA

Browse source 
Cross-hive trust was O(n²) hand-pinning: every hive had to name every
peer's CA. A swarm root makes it O(1) — trust the root once and every
present and future peer validates.

The root is generated by a new `swarm-ca` unit on a single-host swarm
and operator-provided otherwise; `swarm.ca.autoConfigure` picks between
them and derives its default from `swarm.peers` being empty, so "all on
one host" is read off the deployment rather than remembered. Both modes
produce the same artifacts in the same places, so splitting hosts later
is moving the service dirs, not switching code paths. The root key never
enters the nix store, and the root is never regenerated automatically —
replacing it invalidates every peer at once.

Each hive CA carries `nameConstraints` pinned to that hive's domain, so
a leaked hive CA can only mint names inside its own subdomain, enforced
by verifiers rather than by convention.

`ca.pem` was serving as both the issuer and the anchor consumers trust;
those are the same file only while it is self-signed. openssl will not
terminate a chain at a trusted cert that isn't self-signed (rustls and
Go will), so the promotion would have broken some consumers and not
others. `hive-tls-ca` now also writes `trust-bundle.pem` — the hive CA
plus whatever it is rooted at — and every anchor consumer reads that:
agents, the CI and forge containers, and the peer-config recipe. On a
hive with no swarm root the bundle is just that CA, so nothing consuming
it needs a mode to branch on.
This commit is contained in:
atlas 2026-08-05 14:33:49 +02:00 • committed by mara
commit 06710e83b4
8 changed files with 366 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

53
docs/swarm.md
View file

@ -54,6 +54,56 @@ to.
See `docs/conventions.md` § Hive identity for the env-var chain
and `qualify()` / `qualified_label()` semantics.
## Swarm CA
A hive's internal TLS chains to a **swarm root CA**: the root signs each
hive's own CA, and that hive CA signs the gateway leaf. A peer that
trusts the root once validates every hive in the swarm, present and
future, instead of being pinned to each one by hand.
Two provisioning modes, one structure — what differs is who puts the
artifacts on disk:
| | swarm root | this hive's CA |
| --- | --- | --- |
| all on one host (default) | generated by `swarm-ca.service` on first boot | issued by `hive-tls-ca.service` under the root |
| split across hosts | operator-provided | operator-provided |
`services.hyperhive.swarm.ca.autoConfigure` selects between them. It
defaults to true exactly while this hive declares no `swarm.peers`, so a
single-host swarm costs no configuration and declaring a peer stops the
host from minting a root that could not be the swarm's. Moving the swarm
CA onto its own host is then a matter of moving
`services.hyperhive.swarm.ca.stateDir` and setting `autoConfigure =
false` — there is no second code path to switch to.
The root's private key never reaches the nix store: the store is
world-readable, so a key committed to a flake is a key published to
everyone who builds it. Only certificates are distributed.
Each hive CA is **name-constrained** (X.509 `nameConstraints`) to that
hive's own domain, so a hive CA that leaks can only mint names inside
its own subdomain — enforced by every verifier rather than by
convention.
### What to hand a peer
`hivectl peer-config` prints the `cp` line. The file is
`<tls.stateDir>/trust-bundle.pem` — the hive CA plus the swarm root —
not `ca.pem`: an intermediate on its own is not something a verifier can
build a chain to. On a hive that predates the swarm root the bundle is
just that hive's self-signed CA, so the recipe does not change.
### Adopting the hierarchy on an existing hive
An existing `ca.pem` is never re-rooted automatically — swapping it
would break every consumer that already trusts it, and agents only pick
up new trust when their container restarts. To adopt, delete `ca.pem` +
`ca-key.pem` under `tls.stateDir` and restart `hive-tls-ca.service`;
the CA is re-issued under the root and the leaf re-signed. Until then
the hive serves TLS exactly as before and is simply not part of the
swarm's trust hierarchy.
## Declaring peer hives
```nix
@ -74,7 +124,8 @@ trust knobs — pick by what you need to trust:
federation certificate against the system CA bundle independently
(see _Matrix federation_ below), so a fingerprint pin does nothing
for a self-signed matrix cert.
- **`caCert`** (path to the peer's root CA PEM) — embeds that CA (at
- **`caCert`** (path to the peer's trust bundle / root CA PEM, i.e. what
its `hivectl peer-config` told you to copy) — embeds that CA (at
build time, into the nix store — no runtime file on the host) and
trusts it **everywhere the hive's own internal CA is**: it rides
alongside `hive-ca.pem` in every agent's