From 52fabe7096f2a020be5267069ae883cbc371b848 Mon Sep 17 00:00:00 2001 From: atlas Date: Wed, 16 Sep 2026 18:33:57 +0200 Subject: [PATCH] docs/swarm/credentials.md: fix 7 drifted/wrong file:line citations Audited all 22 file:line citations against source on this head, per argus's PR review. Fixed: - matrix_account.rs writer cell pointed at path-computation line 163; the actual store.write() call is at 189-197 (now anchored to the put_matrix_account function name too). - swarm-secret-publisher.nix appservice-token minter cited the "put on every run" comment (280-286) instead of the mint itself (271-278). - glue-matrix-bao-token.nix persisted-token cell cited the registration-restamp comment (186-188) instead of the printf+chmod (180-181). - glue-queue-agent-credential.nix persisted-files cell missed the secret's chmod 0600 at 219, citing 224-231; corrected to 218-224. - swarm-otel.nix persisted-file cell cited 763-767, one line short of the chmod 0400 at 768; corrected to 764-768. - hive-priv/src/main.rs:368,413 (forge/github token cell) landed in unrelated DestroyContainer/ListContainers/WriteAgentGithubToken match arms; replaced with the write_forge_token/write_github_token function names as a greppable, edit-resistant anchor. - swarm-bao.nix:527-528 (the "operator places by hand" quote) missed the quoted text, which starts at 529; corrected to 529-531. 15 of 22 already resolved exactly; no claim lacked supporting code, so nothing was removed. 22 of 22 citations checked. --- docs/swarm/credentials.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/swarm/credentials.md b/docs/swarm/credentials.md index fcae088d..692a7bba 100644 --- a/docs/swarm/credentials.md +++ b/docs/swarm/credentials.md @@ -28,13 +28,13 @@ Four credential families live in the swarm's secret store, plus the mTLS identity that opens it. That fifth row is not a stored secret — it is the credential that cannot be, being what authenticates the reader to the store. -| store path | what it is | minter | writer | reader | renewal | persisted outside the store | -| -------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `swarm/agents//matrix/` | one agent's matrix account credential | `swarm-controller`, via a caller-supplied bearer token or its own `m.login.password` (`swarm-controller/src/matrix_account.rs:14-21`) | same unit (`swarm-controller/src/matrix_account.rs:163`) | `hive-c0re`'s credential worker, under the **hive's** identity (`hive-c0re/src/workers/credential.rs:33-64`) | `NONE` | **yes** — `hive-priv` writes `/matrix-token`, `0600`, chowned to the agent (`hive-priv/src/main.rs:535-556`) | -| `swarm/hives//matrix/appservice-token` | the appservice token authenticating one hive's homeserver | `swarm-secret-publisher.nix` itself, `head -c 32 /dev/urandom` on the authelia host (`nix/host-modules/swarm-secret-publisher.nix:280-286`) | same unit (`nix/host-modules/swarm-secret-publisher.nix:288-289`) | `swarm-bao-matrix-token.service` on the hive (`nix/host-modules/glue-matrix-bao-token.nix:159-167`) | `NONE` | **yes, twice** — the publisher's own state copy (`nix/host-modules/swarm-secret-publisher.nix:185`) and the hive's token file, `0600` (`nix/host-modules/glue-matrix-bao-token.nix:186-188`) | -| `swarm/hives//queue/agent` | the OIDC client id + secret agent containers present to the swarm queue | authelia, on first boot, into its own client-secret dir | `swarm-secret-publish.service` (`nix/host-modules/swarm-secret-publisher.nix:222-225`) | `swarm-bao-queue-agent.service` on the hive (`nix/host-modules/glue-queue-agent-credential.nix:187-197`) | `NONE` | **yes** — `secret` `0600` and `client_id` `0644` under the hive's agent-credential dir (`nix/host-modules/glue-queue-agent-credential.nix:224-231`) | -| `swarm/services//oidc/client` | a swarm service's own OIDC client secret, one per service | authelia, on first boot | `swarm-secret-publish.service` (`nix/host-modules/swarm-secret-publisher.nix:245-248`) | whichever host runs that service — `swarm-bao-grafana-oidc.service` (`nix/host-modules/swarm-grafana.nix:565-684`), the collector's twin (`nix/host-modules/swarm-otel.nix:685-767`) | `NONE` | **yes** — Grafana's `0400` host file (`nix/host-modules/swarm-grafana.nix:678-682`), the collector's `0400` file handed in by `LoadCredential` (`nix/host-modules/swarm-otel.nix:763-767`) | -| _(not stored)_ the store's own mTLS leaves | the certificate a host presents to reach the store at all | `swarm-bao-pki.service`, self-signed, 10-year (`nix/host-modules/glue-bao-tls.nix:114-149`) | n/a | every client reads its own leaf off disk via `BAO_CLIENT_CERT` (`swarm-secret-client/src/client.rs:12-14`) | `NONE` — signed only when absent (`nix/host-modules/glue-bao-tls.nix:128-149`) | **always, by construction** — it has no other form | +| store path | what it is | minter | writer | reader | renewal | persisted outside the store | +| -------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `swarm/agents//matrix/` | one agent's matrix account credential | `swarm-controller`, via a caller-supplied bearer token or its own `m.login.password` (`swarm-controller/src/matrix_account.rs:14-21`) | same unit, `put_matrix_account`'s `store.write` call (`swarm-controller/src/matrix_account.rs:189-197`) | `hive-c0re`'s credential worker, under the **hive's** identity (`hive-c0re/src/workers/credential.rs:33-64`) | `NONE` | **yes** — `hive-priv` writes `/matrix-token`, `0600`, chowned to the agent (`hive-priv/src/main.rs:535-556`) | +| `swarm/hives//matrix/appservice-token` | the appservice token authenticating one hive's homeserver | `swarm-secret-publisher.nix` itself, `head -c 32 /dev/urandom` on the authelia host (`nix/host-modules/swarm-secret-publisher.nix:271-278`) | same unit (`nix/host-modules/swarm-secret-publisher.nix:288-289`) | `swarm-bao-matrix-token.service` on the hive (`nix/host-modules/glue-matrix-bao-token.nix:159-167`) | `NONE` | **yes, twice** — the publisher's own state copy (`nix/host-modules/swarm-secret-publisher.nix:185`) and the hive's token file, `0600` (`nix/host-modules/glue-matrix-bao-token.nix:180-181`) | +| `swarm/hives//queue/agent` | the OIDC client id + secret agent containers present to the swarm queue | authelia, on first boot, into its own client-secret dir | `swarm-secret-publish.service` (`nix/host-modules/swarm-secret-publisher.nix:222-225`) | `swarm-bao-queue-agent.service` on the hive (`nix/host-modules/glue-queue-agent-credential.nix:187-197`) | `NONE` | **yes** — `secret` `0600` and `client_id` `0644` under the hive's agent-credential dir (`nix/host-modules/glue-queue-agent-credential.nix:218-224`) | +| `swarm/services//oidc/client` | a swarm service's own OIDC client secret, one per service | authelia, on first boot | `swarm-secret-publish.service` (`nix/host-modules/swarm-secret-publisher.nix:245-248`) | whichever host runs that service — `swarm-bao-grafana-oidc.service` (`nix/host-modules/swarm-grafana.nix:565-684`), the collector's twin (`nix/host-modules/swarm-otel.nix:685-767`) | `NONE` | **yes** — Grafana's `0400` host file (`nix/host-modules/swarm-grafana.nix:678-682`), the collector's `0400` file handed in by `LoadCredential` (`nix/host-modules/swarm-otel.nix:764-768`) | +| _(not stored)_ the store's own mTLS leaves | the certificate a host presents to reach the store at all | `swarm-bao-pki.service`, self-signed, 10-year (`nix/host-modules/glue-bao-tls.nix:114-149`) | n/a | every client reads its own leaf off disk via `BAO_CLIENT_CERT` (`swarm-secret-client/src/client.rs:12-14`) | `NONE` — signed only when absent (`nix/host-modules/glue-bao-tls.nix:128-149`) | **always, by construction** — it has no other form | Four things in that table are uncomfortable, and they are the reason this page exists rather than a note in the margin of the old one. @@ -67,7 +67,7 @@ and `swarm-bao-grafana-oidc.service`. What each of them then does is write the fetched bytes to disk. Two per-agent credential files — the forge token and the github token -(`hive-priv/src/main.rs:368,413`) — are deliberately absent from the table. +(`hive-priv/src/main.rs`'s `write_forge_token`/`write_github_token`) — are deliberately absent from the table. They are operator-supplied and never pass through the store at all, so they are not credentials this page governs. Their absence is not an oversight. @@ -81,7 +81,7 @@ statement of fact, so it is stated as a target twice. **Every host needs a store mTLS certificate. Everything else is done through the store.** That is the target. Today only the host running the store itself auto-mints leaves — for itself, and pre-emptively for a controller and a -publisher that might be co-located. For every other host, `swarm-bao.nix:527-528` +publisher that might be co-located. For every other host, `swarm-bao.nix:529-531` says it outright: this is _"the credential an operator places by hand."_ There is no automated issuance path for an ordinary hive. The target is one out-of-band credential per host and zero out-of-band credentials anywhere else;