Watch
0
0
Fork
You've already forked hyperhive
0

swarm ui ssh row with target snippets, docs for the per-agent switch

This commit is contained in:
atlas 2026-11-16 18:38:10 +01:00 • committed by mara
commit e621397252
3 changed files with 417 additions and 94 deletions

View file

@ -38,7 +38,7 @@ the rest of the cell says how.
| `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>/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/agents/<agent>/proxy-credential` | `swarm-controller`: 32 random bytes, at start and every 5 minutes for every agent that holds a store identity | the hive (`hive-c0re`) and the agent, which fetches it | ❌ never replaced: written only while the path holds nothing | ✅ `hive-c0re` re-reads it every 30 seconds |
| `ssh-agents/sign/swarm-agent` (a signing call, nothing is stored) | the store's SSH CA mount (`ssh-agents`), when the agent's `hive-agent-ssh-cert` unit asks it to sign the public key the unit generated in its own `/run`; the CA key is generated inside the store by `swarm-bao-agent-ssh-policy` | the agent, which keeps the key and the signed certificate in `/run` only; a target machine trusts the CA's public key by value | ✅ the certificate lasts 60 minutes; the CA is never replaced, and a target that holds a different CA key refuses every certificate | ✅ the agent signs again every 20 minutes |
| `ssh-agents/sign/swarm-agent` (a signing call, nothing is stored) | the store's SSH CA mount (`ssh-agents`), when the agent's `hive-agent-ssh-cert` unit asks it to sign, which the operator's per-agent `ssh` switch allows the public key the unit generated in its own `/run`; the CA key is generated inside the store by `swarm-bao-agent-ssh-policy` | the agent, which keeps the key and the signed certificate in `/run` only; a target machine trusts the CA's public key by value | ✅ the certificate lasts 60 minutes; the CA is never replaced, and a target that holds a different CA key refuses every certificate | ✅ the agent signs again every 20 minutes |
| `swarm/hives/<hive>/squid-selfcheck` | `swarm-controller`, in the same pass as the agents' credentials | the hive: `hive-c0re` and `squid-selfcheck-credential` (root) | ❌ never replaced: written only while the path holds nothing | ✅ `hive-c0re` every 30 seconds, the root unit every 10 minutes |
| `swarm/hives/<hive>/oidc/client` | authelia, first boot, straight into the store | the hive | ❌ minted once, straight into the store; minted again only when the store holds none | ✅ re-read when authelia refuses it |
| `swarm/services/<clientId>/oidc/client` | authelia | that service | must be stated | must be stated |

View file

@ -39,18 +39,43 @@ each agent's cert login after the agent
a glob, host certificates, other key types or another extension is a refusal
from the store.
## What an agent may call
## The switch and the signing policy
The shared agent policy `hive-agent` (`render_shared_agent`) holds one more
stanza: `update` on `ssh-agents/sign/swarm-agent`, and nothing on the rest of
the mount. `swarm-controller` writes the policy at every start and at every
agent mint, so a deploy that adds the stanza reaches existing agents when the
controller restarts. A token already issued picks the change up on its next
request, because bao reads policies per request.
The operator's switch is the `ssh` field of the agent's record in `agent-permissions`
(`swarm_wire::agent_permissions`), set with `PUT /api/agents/{name}/permissions`
from the swarm UI's **ssh** row. Absent is off. A `PUT` or `DELETE` that leaves
the field out keeps it.
Signing is a separate policy, `hive-agent-ssh` (`policy::SSH_POLICY`,
`render_ssh_signer`): `update` on `ssh-agents/sign/swarm-agent` and nothing
else. The shared agent policy `hive-agent` holds no SSH stanza. `swarm-controller`
writes `hive-agent-ssh` at every identity mint and every pass of `agent_ssh.rs`,
and attaches it to the agent's cert-auth role `hive-agent-<name>` as a second
`token_policies` entry only while the switch is on.
- **Rewrite.** A change of the field wakes `agent_ssh`'s pass at once, and the pass
also runs every five minutes. It reads each role's policies and rewrites only
`token_policies` (a partial write: the role's certificate, names and lifetimes
stay) when they differ from the shared policy plus, if on, `hive-agent-ssh`.
The identity mint (`agent_identity.rs`) keeps whatever the role has, so a
certificate renewal doesn't switch it off. The pass doesn't create a missing role.
- **When it takes effect.** A token carries the policies of the role it logged in
under and keeps them until it expires, at most the role's `token_ttl` of one
hour. Switching **on** reaches the agent at its next login, which its
certificate unit makes on every run (every 20 minutes), so within about 25
minutes of the pass. Switching **off** stops every new login at once; an agent
already holding a token that carries the policy can still sign until that token
expires, at most an hour. Neither touches a certificate already signed: it
stays valid until it expires, at most three hours.
- **The CA key.** `GET /api/ssh/ca` returns `{ "public_key": "ssh-ed25519 …" }`, read
from `ssh-agents/config/ca` with the controller's own identity. The controller
holds `read` on that path and nothing else on the mount: it can't sign. It
answers 404 while the store holds no CA.
## The agent's unit
With `services.hyperhive.agent.ssh.enable`, `nix/agent-modules/ssh.nix` adds
`nix/agent-modules/ssh.nix` is on in every agent that has a store address
(`services.hyperhive.agent.bao.addr`), with no option. It adds
`hive-agent-ssh-cert.service` and its timer, as the agent user:
- the key is `/run/hive-agent-ssh-cert/key` (directory `0700`, files `0400`,
@ -58,14 +83,18 @@ With `services.hyperhive.agent.ssh.enable`, `nix/agent-modules/ssh.nix` adds
`key-cert.pub` beside it;
- each run logs in to the store with the cert identity `hive-agent-bao-identity`
keeps, signs `key.pub` through the role, checks the answer parses as a
certificate and renames it into place;
certificate and renames it into place. A `403` from the signing call is the
switch being off: the unit prints one line and exits 0, and the next tick asks
again. Any other failure fails the unit, which retries;
- the timer fires 20 minutes after each run, a third of the 60-minute lifetime,
from the same file as the role's TTL;
- the generated `/etc/ssh/ssh_config` has one `Host <name>` block per entry
(`HostName`, `User`, `Port`, `IdentityFile`, `CertificateFile`,
`IdentitiesOnly yes`, `StrictHostKeyChecking yes`), and
`/etc/ssh/ssh_known_hosts` one pinned line per `hostKey` (`[host]:port` for a
port other than 22).
- the system `/etc/ssh/ssh_config` has one `Host *` block: `IdentityFile` and
`CertificateFile` from `/run`, `IdentitiesOnly yes`,
`StrictHostKeyChecking accept-new`, and
`UserKnownHostsFile /agents/<name>/state/ssh_known_hosts`. The host binds the
state directory in, so the pins survive a restart; the container root
doesn't. The agent trusts the first key a host shows and refuses a changed
one.
## The target module
@ -84,11 +113,8 @@ per-agent allowance for it yet.
## Revocation
Every agent shares the role, which holds nothing per agent, so there is no
per-agent signing switch. `swarm-controller`'s renewal pass (`agent_renewal.rs`) re-mints
the store identity, and writes the cert-auth role `hive-agent-<name>` back, for
every agent a hive still declares, so deleting the role doesn't stick. Nothing
in the controller deletes the role when you destroy an agent; the renewal pass
skips a destroyed agent and its identity lapses with its 7-day
certificate. A target's `principals` list is the immediate control. A
certificate already signed stays valid for at most `max_ttl` (180 minutes).
Unticking the switch stops signing as described above. Destroying an agent
disables its identity entity and deletes its cert-auth role
(`agent_cutoff.rs`), after which its tokens stop working at once. A target's
principals list is the immediate control per machine. A certificate already
signed stays valid for at most `max_ttl` (180 minutes).

View file

@ -851,6 +851,17 @@ back, so the controller's log (`agent max repos`) is the record of what it appli
to each agent. The controller tries an agent whose account the forge refuses again
every five minutes.
The **ssh** row is whether the agent may get SSH certificates from the swarm: a
badge reading on or off, off by default. Selecting it opens an explainer, a
checkbox that does a `PUT` of `ssh` with the stored permissions beside it, and
a folded **on the target** section. That section reads `GET /api/ssh/ca` and
shows the swarm's CA key and the agent's name as the lines for a NixOS machine,
a home-manager user and a plain `authorized_keys` file, with a copy button; the
card builds the text in `frontend/packages/swarm-ui/src/agent/detail/ssh.ts`. A `PUT`
that leaves `ssh` out, and the `DELETE` of **use the default**, keep it. The
controller attaches the signing policy to the agent's login role within five
minutes; see [the SSH CA](../swarm/ssh-ca.md#the-switch-and-the-signing-policy).
A saved change isn't instant. The hive reads the grant about every 30 seconds
and the agent takes it at its next turn. A change to `manage_root_agent`
restarts the agent after its current turn. The card reads