diff --git a/docs/2-handbook/swarm/forge.md b/docs/2-handbook/swarm/forge.md index e3ff66e51..fe3464f60 100644 --- a/docs/2-handbook/swarm/forge.md +++ b/docs/2-handbook/swarm/forge.md @@ -46,6 +46,13 @@ swarm controller creates both and keeps the tokens in the swarm secret store, so you set up nothing by hand. A token that goes missing or stops matching the forge is re-minted within five minutes. +Removing a hive from `swarm.hives` revokes its credentials on the next +controller start: its forge token, its seat in the `hives` team, its token +secret in the store and the store login it uses. The forge account stays, so +putting the hive back in `swarm.hives` gives it new credentials within five +minutes of that start. The controller logs one `hive is not in the roster` line +per hive it cut off. + Two things live in the `agent-configs` Forgejo organization: - A config repo per agent, `agent-configs/`. The agent is a read diff --git a/docs/4-implementation/swarm/credentials-reference.md b/docs/4-implementation/swarm/credentials-reference.md index 5006da565..0fb35409f 100644 --- a/docs/4-implementation/swarm/credentials-reference.md +++ b/docs/4-implementation/swarm/credentials-reference.md @@ -36,7 +36,7 @@ the rest of the cell says how. | `swarm/agents//github-token` | `swarm-controller`, when you link a GitHub account in the swarm UI | the agent, which keeps it in `/run` only; the `/github-token` copy of an earlier version is no longer read | ❌ your token; delete it and link again | ✅ every 2 minutes | | `swarm/agents//backend-env` | `hive-agent-backend-env`, in the agent's container, from the agent's `backendEnvironmentFile` when the leaf holds nothing (field `env`, the file's exact text); or `swarm-controller`, when you set the API-key environment in the swarm UI | the agent | ❌ nothing replaces it without you; a save in the swarm UI overwrites it, including text an agent wrote into an empty leaf; the agent's file stays as it was | ❌ the file in `/run` refreshes every 2 minutes, and the harness and the subagent daemon load it at their next start | | `swarm/agents//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//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//forge/token` | `swarm-controller`, every 5 minutes; deleted when the hive leaves the roster | `swarm-controller` and the hive | ✅ when missing or no longer matching the forge | ✅ read on every forge call | | `swarm/agents//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, 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//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 | diff --git a/docs/4-implementation/swarm/forge-accounts.md b/docs/4-implementation/swarm/forge-accounts.md index d36889b99..bbc756017 100644 --- a/docs/4-implementation/swarm/forge-accounts.md +++ b/docs/4-implementation/swarm/forge-accounts.md @@ -42,6 +42,39 @@ controller's grant on `swarm/hives/+/forge/token`), then the controller host, then the hives. A hive that starts before its token exists reads nothing, and builds nothing, until the controller's next pass. +## A hive that leaves the roster + +A hive dropped from `swarm.hives` keeps the credentials above until +swarm-controller cuts it off (`forge::hive_cutoff`). The roster is the +`SWARM_CONTROLLER_HIVES` env var, read at start, so a removal takes effect at +the next controller start. On every pass, swarm-controller cuts off each hive +that has a forge account with the hive email, or a cert-auth role +`hive-`, and isn't in the roster. A role named `hive-agent-` +belongs to an agent and never matches. + +For each such hive, in this order: + +1. delete its `swarm-hive` forge token, +2. remove its account from the `agent-configs/hives` team, +3. delete the store secret `swarm/hives//forge/token`, +4. delete the cert-auth role `hive-`. + +The role goes last because it marks that work remains: a step that fails +leaves the role, and the next pass runs every step again. A step that finds +nothing to remove does nothing, so a finished hive costs a few reads per pass. +The pass logs one `hive is not in the roster: its credentials are revoked` line +per hive with what it removed, and a warning for a hive whose cut-off failed. + +The forge account stays, so a hive put back in the roster gets its token and +team seat from the pass above and its role from the store access +swarm-controller writes at start. + +Nothing happens when the roster didn't load. An unset or unparseable +`SWARM_CONTROLLER_HIVES`, and a roster with no hive, read the same as a removal of every +hive, so the controller logs an error at start and skips the +cut-off. The attic pull token and the OIDC client secret under +`swarm/hives//` stay, as does the forge account itself. + ## Per-agent forge accounts Each agent gets its own Forgejo user and access token. swarm-controller