diff --git a/docs/README.md b/docs/README.md index cede24f90..c88c4e491 100644 --- a/docs/README.md +++ b/docs/README.md @@ -78,8 +78,10 @@ declarations. [`networking/snapshot-store.md`](networking/snapshot-store.md). - **Who mints each credential, who reads it, and how does it rotate — and where's that shape headed?** → [`swarm/credentials.md`](swarm/credentials.md) - (current state and target state); - [`swarm/secrets.md`](swarm/secrets.md) for where each file lives today. + (the rules, where each secret goes and why) and + [`swarm/credentials-reference.md`](swarm/credentials-reference.md) (the + tables: each credential, current state and target state, and where each + file lives today). - **How does the secret store come up, who writes its grants, how's it sealed?** → [`swarm/bao.md`](swarm/bao.md). - **How does an agent get a prompt at set times, and why doesn't it fire diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index 1258cc688..8d79838d0 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -9,7 +9,7 @@ Every command runs as **root on the host**. > **Not all-local?** Each step says which host it runs on. A split swarm > also has credentials you can't generate where they're read — each -> host's mTLS identity at the secret store. Read [`swarm/secrets.md`](../swarm/secrets.md) first; it +> host's mTLS identity at the secret store. Read [`swarm/credentials.md`](../swarm/credentials.md) first; it > says which files you place, and where. ## 1 · Secret store diff --git a/docs/integrations/github.md b/docs/integrations/github.md index f973afb1f..7495cb72c 100644 --- a/docs/integrations/github.md +++ b/docs/integrations/github.md @@ -50,7 +50,7 @@ when the token changed. It needs a store identity (`services.hyperhive.agent.bao.addr`); an agent without one gets no token. The unit never deletes the file: a `github-token` already in place stays when the store holds none or doesn't answer. Where the token lives and who -reads it: [credentials.md](../swarm/credentials.md). +reads it: [credentials-reference.md](../swarm/credentials-reference.md). ## Security diff --git a/docs/scheduler/observability.md b/docs/scheduler/observability.md index 0585e9c0f..e2b0aec03 100644 --- a/docs/scheduler/observability.md +++ b/docs/scheduler/observability.md @@ -148,7 +148,7 @@ run lands a changed value it restarts the collector. A timer runs it again every ten minutes, so a secret rotated later reaches the collector within about ten minutes. On a hive that runs the store the leaf is already there; elsewhere it's the credential you -place — see [secret placement](../swarm/secrets.md). +place — see [secret placement](../swarm/credentials.md). To deliver the secret some other way, name the file. The fetch unit isn't rendered, and the collector waits up to 120s for the file to appear: diff --git a/docs/swarm/README.md b/docs/swarm/README.md index b97142628..7521c8ce6 100644 --- a/docs/swarm/README.md +++ b/docs/swarm/README.md @@ -41,10 +41,11 @@ grafana, the controller, authelia, …) → stack, each on whichever host you put it. → [`services.md`](services.md) - **SSO** — the secrets authelia generates and how each reaches its reader. → [`sso.md`](sso.md) -- **secrets** — every credential the swarm holds, who mints it and where it - lives → [`secrets.md`](secrets.md) · the per-secret minter/reader/renewal - contract → [`credentials.md`](credentials.md) · how the store comes up, - who writes its grants and how it unseals → [`bao.md`](bao.md) +- **secrets** — the rules a credential follows → [`credentials.md`](credentials.md); + every credential the swarm holds, who mints it, who reads it, how it renews + and where it lives → [`credentials-reference.md`](credentials-reference.md) · + how the store comes up, who writes its grants and how it unseals → + [`bao.md`](bao.md) - **swarm CA** — the store root every hive's gateway leaf chains to, and what to hand a peer. → [`ca.md`](ca.md) - **snapshot store** — the swarm's one `btrfs receive` endpoint, diff --git a/docs/swarm/bao.md b/docs/swarm/bao.md index 00c8125e2..d85f1af8e 100644 --- a/docs/swarm/bao.md +++ b/docs/swarm/bao.md @@ -3,7 +3,7 @@ The swarm runs one OpenBao store, `swarm-bao`. Every swarm-level credential an agent or service needs comes from it under that principal's own certificate identity. What lives in it and who reads what: -[`secrets.md`](secrets.md). This page covers the store itself — how it +[`credentials-reference.md`](credentials-reference.md). This page covers the store itself — how it comes up, who may write its grants, and how it's sealed and reached. The operator steps (init, the one-time granter bootstrap) are in @@ -114,7 +114,7 @@ Those are `mkDefault`s, so naming your own paths wins. Do that when your certificates come from a real internal CA; the store has no opinion about which. A host that does **not** deploy the store names the reader's three itself, plus a pair for every principal it runs — see -[per-principal identities](secrets.md#per-principal-identities) for the list. +[per-principal identities](credentials-reference.md#store-identities-one-per-principal) for the list. They're the credentials the store can't hand you, being what opens it, so the store's host signs them and the operator copies them to the host that needs them and names them in config. The service principals' leaves are at the top of diff --git a/docs/swarm/builder.md b/docs/swarm/builder.md index fddc36c2a..c014a68f0 100644 --- a/docs/swarm/builder.md +++ b/docs/swarm/builder.md @@ -190,7 +190,7 @@ status. The same `git` fetches a config's own inputs, so the builder registers the helper for the forge's URL only, and the helper answers only an `https` request for the forge's host: any other host gets nothing. The builder holds no write credential; swarm-controller writes the status with its own forge token. Details per path: -[`credentials.md`](credentials.md). +[`credentials-reference.md`](credentials-reference.md). ## Isolation diff --git a/docs/swarm/secrets.md b/docs/swarm/credentials-reference.md similarity index 52% rename from docs/swarm/secrets.md rename to docs/swarm/credentials-reference.md index 04fe931c2..dadc9075d 100644 --- a/docs/swarm/secrets.md +++ b/docs/swarm/credentials-reference.md @@ -1,259 +1,133 @@ -# Swarm secrets: what exists, and where each one lives +# Credentials: the per-secret reference -A swarm generates its credentials in three different places and reads them -in a fourth, so "where does this file go" has a different answer per deployment. -This page is that answer, one row per secret. +Every credential in the swarm's secret store, in one table: who mints it, who +reads it, and whether it renews on its own. The overview and the rules a +credential follows are in [`credentials.md`](credentials.md); this page is +the detail, so it changes whenever someone adds a credential or moves its minting. +The second half, [where each secret lives on disk](#where-each-secret-lives-on-disk), maps the +files that exist today. -Two rules run through all of it. +In the table, **automatic re-mint** is something replacing the stored value +without an operator. **Automatic re-pull** is the reader picking up a replaced +value without a restart. ✅ means it happens today, ❌ means it doesn't, and +the rest of the cell says how. -**Private key material and access tokens are paths, never values.** Every option -carrying one takes a file path (`*File`), because a literal written into a nix -expression ends up in the nix store — world-readable and permanent. No -option in this tree accepts one inline, and adding one would be a leak rather -than a convenience. + -The rule is about what must stay secret, not about credentials generally. -**Public material is a value**: a certificate, or a public nkey like -the queue callout's user key, reaches every client that connects, -so the store is a perfectly good place for it. +| store path | minter | reader | automatic re-mint | automatic re-pull | +| ----------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `swarm/agents//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//matrix/` | `swarm-controller`, from a credential you hand it | the agent | must be stated | ✅ retried within 2 to 16 minutes after a rejection | +| `swarm/agents//matrix-recovery/` | `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/agents//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//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//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//forge/