Watch
0
0
Fork
You've already forked hyperhive
0

Compare commits

...
35 changed files with 1883 additions and 159 deletions

2
Cargo.lock generated
View file

@ -2092,6 +2092,7 @@ version = "0.1.0"
dependencies = [ dependencies = [
"serde", "serde",
"serde_json", "serde_json",
"tracing",
] ]
[[package]] [[package]]
@ -4818,6 +4819,7 @@ name = "swarm-agent-verify"
version = "0.1.0" version = "0.1.0"
dependencies = [ dependencies = [
"anyhow", "anyhow",
"serde",
"subtle", "subtle",
"swarm-secret-client", "swarm-secret-client",
"thiserror 2.0.18", "thiserror 2.0.18",

View file

@ -289,6 +289,8 @@ host access it has.
| `execution` | the `bash` MCP server (`mcp__bash__run`/`status`/`kill`), rendered into the agent's MCP config only with it; a subagent gets Claude's own `Bash` instead. See `docs/tools/bash.md`. | | `execution` | the `bash` MCP server (`mcp__bash__run`/`status`/`kill`), rendered into the agent's MCP config only with it; a subagent gets Claude's own `Bash` instead. See `docs/tools/bash.md`. |
| `web_tools` | the Claude built-ins `WebFetch`/`WebSearch` | | `web_tools` | the Claude built-ins `WebFetch`/`WebSearch` |
| `manage_root_agent` | every agent's state (rw) bind-mounted into the holder's container, plus `/meta` (ro) | | `manage_root_agent` | every agent's state (rw) bind-mounted into the holder's container, plus `/meta` (ro) |
| `logs` | the log store: `swarm-logs` queries. Checked by `swarm-logs-auth` at the gateway, not by a tool list. Off by default. |
| `metrics` | the metrics store: `swarm-metrics` queries. Checked by `swarm-metrics-agent-auth`, the same binary, for the metrics gateway. Off by default. |
**Always-on tools** — `Permission::ALWAYS_ON_TOOLS` exposes `set_status`, **Always-on tools** — `Permission::ALWAYS_ON_TOOLS` exposes `set_status`,
`compact`, and `mark_todos_done` to every agent regardless of its `compact`, and `mark_todos_done` to every agent regardless of its
@ -311,6 +313,34 @@ the default (`Permission::DEFAULT`): `messaging`, `meta`, `inbox`,
none. swarm-controller logs every refused `PUT` or `DELETE` on that route at `warn` as none. swarm-controller logs every refused `PUT` or `DELETE` on that route at `warn` as
`agent permissions: request refused`, with the fields `op`, `agent`, `status` and `detail`. `agent permissions: request refused`, with the fields `op`, `agent`, `status` and `detail`.
**`logs` and `metrics`** — off for every agent until granted, and separate
because logs are the more sensitive. Grant one with
`swarmctl agent permissions set <agent>` (listing it with the others) or the
create-agent screen; the setup assistant creates ruth with both. An agent
without it gets a 403 from the store's gateway when `swarm-logs` or
`swarm-metrics` queries; a bad secret is still a 401.
An agent decodes its own record, in its harness
(`hive-agent/src/swarm_permissions.rs`, through `swarm_queue_client::agent_permissions::read`),
and a build that doesn't know a name would drop to no permissions. The controller
therefore refuses a change that adds `logs` or `metrics` to an existing
agent, with a 409, unless both the agent's hive (`tolerant-permissions` in its
status snapshot) and its running harness (the same entry in its turn-state
header, `swarm_wire::hive_status`) advertise it. A harness not yet updated, a
stopped agent and one that hasn't sent its first header (up to a minute after
a restart) all refuse; keeping a grant it already holds needs no report. A
create has no harness yet and checks the hive only.
The controller mirrors the two grants to the store leaf
`swarm/agents/<agent>/observability` (`swarm_secret_client::observability`),
which the gateways read, and the gateway denies when it can't read that leaf.
A change that drops a grant writes the leaf first and the record second, so a
failed write changes nothing; a change that adds one writes the record first,
so a failed write leaves the gateway denying. Every five minutes the controller
also makes each agent's leaf equal its record and logs a warning for each leaf
it corrects. A revoked grant stops working within `authVerdictTtl` (60
seconds by default) of the agent's last allowed query.
**Internet flag** — the record also carries `unrestricted_internet`, a **Internet flag** — the record also carries `unrestricted_internet`, a
boolean that isn't a `Permission`. An absent value means on, so every agent boolean that isn't a `Permission`. An absent value means on, so every agent
that existed before the field keeps the open access it had. `POST /api/agents` that existed before the field keeps the open access it had. `POST /api/agents`

View file

@ -16,47 +16,48 @@ the rest of the cell says how.
<!-- vale write-good.Passive = NO --> <!-- vale write-good.Passive = NO -->
| store path | minter | reader | automatic re-mint | automatic re-pull | | store path | minter | reader | automatic re-mint | automatic re-pull |
| ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ---------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `swarm/agents/<agent>/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/<agent>/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/<agent>/matrix/<account>` | `swarm-controller`, from a credential you hand it | the agent | must be stated | ✅ retried within 2 to 16 minutes after a rejection | | `swarm/agents/<agent>/matrix/<account>` | `swarm-controller`, from a credential you hand it | the agent | must be stated | ✅ retried within 2 to 16 minutes after a rejection |
| `swarm/agents/<agent>/matrix-recovery/<account>` | `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/agents/<agent>/matrix-recovery/<account>` | `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 appservice sync` in `hive-matrix`, from the registration's `as_token` | `swarm-controller` | ❌ follows the registration below | ✅ read every 5 minutes | | `swarm/controller/swarm-controller/matrix/appservice-token` | `swarm-matrix-ctl appservice sync` in `hive-matrix`, from the registration's `as_token` | `swarm-controller` | ❌ follows the registration below | ✅ read every 5 minutes |
| `swarm/controller/swarm-controller/matrix/appservice-registration` | `swarm-matrix-ctl appservice render` in `hive-matrix`, when the store answers and holds none; before that, the tokens an earlier version kept in the container, stored unchanged | `swarm-matrix-ctl` in `hive-matrix`; the controller has no grant to it | ❌ minted once; an operator who replaces it makes `sync` render the new pair and restart the homeserver | ✅ `sync` re-reads it every 10 minutes | | `swarm/controller/swarm-controller/matrix/appservice-registration` | `swarm-matrix-ctl appservice render` in `hive-matrix`, when the store answers and holds none; before that, the tokens an earlier version kept in the container, stored unchanged | `swarm-matrix-ctl` in `hive-matrix`; the controller has no grant to it | ❌ minted once; an operator who replaces it makes `sync` render the new pair and restart the homeserver | ✅ `sync` re-reads it every 10 minutes |
| `swarm/controller/swarm-controller/oidc/client` | authelia, first boot | `swarm-controller` | ❌ minted once, straight into the store; minted again only when the store holds none | ✅ re-read when authelia refuses it | | `swarm/controller/swarm-controller/oidc/client` | authelia, first boot | `swarm-controller` | ❌ minted once, straight into the store; minted again only when the store holds none | ✅ 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/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/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/controller/swarm-controller/forge/webhook-secret` | `swarm-controller`, at start, from its old `webhook-secret` file; a new one only when there is no file | `swarm-controller` | ❌ minted once; a rotated secret fails every delivery until the forge hooks are re-registered | ❌ read at start | | `swarm/controller/swarm-controller/forge/webhook-secret` | `swarm-controller`, at start, from its old `webhook-secret` file; a new one only when there is no file | `swarm-controller` | ❌ minted once; a rotated secret fails every delivery until the forge hooks are re-registered | ❌ read at start |
| `swarm/agents/<agent>/bao-mtls` | the store's agent PKI mount (`deploy.bao.agentPkiMountPath`), at agent creation, and by the renewal pass when none is stored or its cert-auth role is missing | `hive-c0re`, then the agent | ✅ re-issued every 5 minutes once past half its 7-day validity; minted when none is stored or its cert-auth role is missing, for agents not `Destroyed` | ✅ the agent re-reads every 10 minutes; it renews only while its current leaf is valid | | `swarm/agents/<agent>/bao-mtls` | the store's agent PKI mount (`deploy.bao.agentPkiMountPath`), at agent creation, and by the renewal pass when none is stored or its cert-auth role is missing | `hive-c0re`, then the agent | ✅ re-issued every 5 minutes once past half its 7-day validity; minted when none is stored or its cert-auth role is missing, for agents not `Destroyed` | ✅ the agent re-reads every 10 minutes; it renews only while its current leaf is valid |
| `swarm/agents/<agent>/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/<agent>/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/<agent>/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/<agent>/observability` | `swarm-controller`, when an operator sets, clears or creates an agent's permissions with `logs` or `metrics` in the old or new list, and when it destroys the agent; the leaf stays absent for an agent that never held either | the agent (read-only, its own prefix); `swarm-logs-auth` and `swarm-metrics-agent-auth`, which deny when it's absent or unreadable | ✅ the controller rewrites it with the permission, and every five minutes makes it equal the record's | ✅ the stores honour a changed grant for up to `deploy.victorialogs.authVerdictTtl` and `deploy.victoriametrics.agentAuthVerdictTtl` (60 s by default) |
| `swarm/agents/<agent>/forge/<label>` | `swarm-controller`, when you link an external forge account in the swarm UI | the agent | ❌ your token; delete it and link the label again | ✅ every 2 minutes | | `swarm/agents/<agent>/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/<agent>/github-token` | `swarm-controller`, when you link a GitHub account in the swarm UI | the agent | ❌ your token; delete it and link again | ✅ every 2 minutes | | `swarm/agents/<agent>/forge/<label>` | `swarm-controller`, when you link an external forge account in the swarm UI | the agent | ❌ your token; delete it and link the label again | ✅ every 2 minutes |
| `swarm/agents/<agent>/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/<agent>/github-token` | `swarm-controller`, when you link a GitHub account in the swarm UI | the agent | ❌ your token; delete it and link again | ✅ every 2 minutes |
| `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/agents/<agent>/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/hives/<hive>/matrix/sender-token` | `swarm-controller`, every 5 minutes | `swarm-controller` and the hive | ✅ when missing or rejected by the homeserver | ✅ the hive re-reads on every sweep | | `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/hives/<hive>/matrix/sender-token` | `swarm-controller`, every 5 minutes | `swarm-controller` and the hive | ✅ when missing or rejected by the homeserver | ✅ the hive re-reads on every sweep |
| `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 | | `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/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/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 |
| `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/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/services/<clientId>/oidc/client` | authelia | that service | must be stated | must be stated | | `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/ci-runner/registration-token` | `swarm-controller`, from the forge, at start and every 5 minutes | `swarm-bao-ci-runner` on the runner's host | ❌ the forge keeps one token until an admin resets it; the controller then writes the new one within 5 minutes | ✅ every 10 minutes; restarts the runner on a change | | `swarm/services/<clientId>/oidc/client` | authelia | that service | must be stated | must be stated |
| `swarm/services/<grafana client id>/metrics/bearer` | `swarm-bao-grafana-metrics-bearer` on Grafana's host, when none is stored | `swarm-metrics-auth` and `swarm-logs-grafana-auth` | ❌ delete it and restart `swarm-bao-grafana-metrics-bearer` | ✅ the auth services re-read within a minute; ❌ Grafana restarts when its copy changes | | `swarm/services/ci-runner/registration-token` | `swarm-controller`, from the forge, at start and every 5 minutes | `swarm-bao-ci-runner` on the runner's host | ❌ the forge keeps one token until an admin resets it; the controller then writes the new one within 5 minutes | ✅ every 10 minutes; restarts the runner on a change |
| `swarm/services/<grafana client id>/secret-key` | `swarm-bao-grafana-secret-key` on Grafana's host, from the key an earlier release generated; a new one only when there is none | Grafana | ❌ minted once; a different key leaves Grafana unable to read its stored datasource secrets | ❌ Grafana reads it at start; the unit restarts Grafana when the file changes | | `swarm/services/<grafana client id>/metrics/bearer` | `swarm-bao-grafana-metrics-bearer` on Grafana's host, when none is stored | `swarm-metrics-auth` and `swarm-logs-grafana-auth` | ❌ delete it and restart `swarm-bao-grafana-metrics-bearer` | ✅ the auth services re-read within a minute; ❌ Grafana restarts when its copy changes |
| `swarm/services/swarm-authelia/keys/<name>`, for `jwt`, `session`, `storage-encryption`, `oidc-hmac` and `oidc-issuer` | authelia's `authelia-swarm-secrets` unit in its container, under the secret publisher's identity, from the key file an earlier release generated; a new one only when there is none | authelia | ❌ minted once; a different storage-encryption key leaves authelia's database unreadable and a different issuer key invalidates every issued token | ❌ read when the unit runs; the unit restarts authelia when the file changes | | `swarm/services/<grafana client id>/secret-key` | `swarm-bao-grafana-secret-key` on Grafana's host, from the key an earlier release generated; a new one only when there is none | Grafana | ❌ minted once; a different key leaves Grafana unable to read its stored datasource secrets | ❌ Grafana reads it at start; the unit restarts Grafana when the file changes |
| `swarm/services/review-classifier/anthropic-api-key` | you, in the store's UI, field `api_key` | `swarm-review-classifier` | ❌ write a new key | ✅ read on every run | | `swarm/services/swarm-authelia/keys/<name>`, for `jwt`, `session`, `storage-encryption`, `oidc-hmac` and `oidc-issuer` | authelia's `authelia-swarm-secrets` unit in its container, under the secret publisher's identity, from the key file an earlier release generated; a new one only when there is none | authelia | ❌ minted once; a different storage-encryption key leaves authelia's database unreadable and a different issuer key invalidates every issued token | ❌ read when the unit runs; the unit restarts authelia when the file changes |
| `swarm/services/review-classifier/acp-provider` | you, in the store's UI, field `api_key` | `swarm-review-classifier` | ❌ write a new key | ✅ read on every run | | `swarm/services/review-classifier/anthropic-api-key` | you, in the store's UI, field `api_key` | `swarm-review-classifier` | ❌ write a new key | ✅ read on every run |
| `swarm/services/review-classifier/forge/token` | `swarm-controller`, at start and every 5 minutes | `swarm-controller` | ✅ when missing or no longer matching the forge | ✅ read on every review | | `swarm/services/review-classifier/acp-provider` | you, in the store's UI, field `api_key` | `swarm-review-classifier` | ❌ write a new key | ✅ read on every run |
| `swarm/services/builder/forge/token` | `swarm-controller`, at start and every 5 minutes | `swarm-builder`, `swarm-controller` | ✅ when missing or no longer matching the forge | ✅ read on every build | | `swarm/services/review-classifier/forge/token` | `swarm-controller`, at start and every 5 minutes | `swarm-controller` | ✅ when missing or no longer matching the forge | ✅ read on every review |
| `swarm/services/attic/push-token` | `swarm-bao-attic-tokens` on the cache's host, when none is stored; with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the token on stdin | `swarm-builder` | ❌ write a new token; a token the cache refuses fails the push, and the build stays green with `cached` false | ✅ read on every push; with both `swarm.attic` options null, nothing reads it | | `swarm/services/builder/forge/token` | `swarm-controller`, at start and every 5 minutes | `swarm-builder`, `swarm-controller` | ✅ when missing or no longer matching the forge | ✅ read on every build |
| `swarm/services/attic/pull-token` | `swarm-bao-attic-tokens` on the cache's host, when none is stored; read-only, ten years; with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin | `swarm-controller`, to copy it and to check narinfos | ❌ write a new token | ✅ copied to the hives every 5 minutes | | `swarm/services/attic/push-token` | `swarm-bao-attic-tokens` on the cache's host, when none is stored; with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the token on stdin | `swarm-builder` | ❌ write a new token; a token the cache refuses fails the push, and the build stays green with `cached` false | ✅ read on every push; with both `swarm.attic` options null, nothing reads it |
| `swarm/services/attic/url` | `swarm-bao-attic-tokens` on the cache's host, when none is stored (`https://<swarm.attic.domain>`); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin (scheme included, no trailing slash) | `swarm-controller`, which copies it to each hive | ❌ delete it and restart `swarm-bao-attic-tokens`, or write the new value | ✅ copied to the hives every 5 minutes | | `swarm/services/attic/pull-token` | `swarm-bao-attic-tokens` on the cache's host, when none is stored; read-only, ten years; with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin | `swarm-controller`, to copy it and to check narinfos | ❌ write a new token | ✅ copied to the hives every 5 minutes |
| `swarm/services/attic/cache` | `swarm-bao-attic-tokens` on the cache's host, when none is stored (`swarm.attic.cache`); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin | `swarm-controller`, which copies it to each hive | ❌ as the URL | ✅ copied to the hives every 5 minutes | | `swarm/services/attic/url` | `swarm-bao-attic-tokens` on the cache's host, when none is stored (`https://<swarm.attic.domain>`); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin (scheme included, no trailing slash) | `swarm-controller`, which copies it to each hive | ❌ delete it and restart `swarm-bao-attic-tokens`, or write the new value | ✅ copied to the hives every 5 minutes |
| `swarm/services/attic/public-key` | `swarm-bao-attic-tokens` on the cache's host, when none is stored (the key `attic cache info` prints); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin (`<name>:<base64>`) | `swarm-controller`, which copies it to each hive | ❌ as the URL. A cache recreated with a new key leaves the stored one stale: every hive then reports `bad-signature` | ✅ copied to the hives every 5 minutes | | `swarm/services/attic/cache` | `swarm-bao-attic-tokens` on the cache's host, when none is stored (`swarm.attic.cache`); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin | `swarm-controller`, which copies it to each hive | ❌ as the URL | ✅ copied to the hives every 5 minutes |
| `swarm/hives/<hive>/attic/{pull-token,url,cache,public-key}` | `swarm-controller`, from the four `swarm/services/attic/` leaves, every 5 minutes; it skips a leaf whose source holds nothing, and a copy whose source is gone stays | the hive (`hive-c0re`) | ✅ a changed source is written over the copy in the next pass | ✅ read every 5 minutes | | `swarm/services/attic/public-key` | `swarm-bao-attic-tokens` on the cache's host, when none is stored (the key `attic cache info` prints); with an external cache, you, in the store's UI (field `value`), or `bao kv put` with `value=-` and the value on stdin (`<name>:<base64>`) | `swarm-controller`, which copies it to each hive | ❌ as the URL. A cache recreated with a new key leaves the stored one stale: every hive then reports `bad-signature` | ✅ copied to the hives every 5 minutes |
| `swarm/services/attic/jwt-secret` | `swarm-bao-attic-secret` on the cache's host, when none is stored | `swarm-bao-attic-secret`, `swarm-bao-attic-tokens` | ❌ a new key invalidates both tokens | ❌ atticd restarts when the file changes | | `swarm/hives/<hive>/attic/{pull-token,url,cache,public-key}` | `swarm-controller`, from the four `swarm/services/attic/` leaves, every 5 minutes; it skips a leaf whose source holds nothing, and a copy whose source is gone stays | the hive (`hive-c0re`) | ✅ a changed source is written over the copy in the next pass | ✅ read every 5 minutes |
| `swarm/services/ci-metrics/forge/token` | `swarm-controller`, at start and every 5 minutes | `swarm-ci-metrics`, `swarm-controller` | ✅ when missing or no longer matching the forge | ✅ read on every pass | | `swarm/services/attic/jwt-secret` | `swarm-bao-attic-secret` on the cache's host, when none is stored | `swarm-bao-attic-secret`, `swarm-bao-attic-tokens` | ❌ a new key invalidates both tokens | ❌ atticd restarts when the file changes |
| _(not in the store)_ a hive's mTLS leaf | the store's PKI, or you by hand | the hive itself, from disk | must be stated | must be stated | | `swarm/services/ci-metrics/forge/token` | `swarm-controller`, at start and every 5 minutes | `swarm-ci-metrics`, `swarm-controller` | ✅ when missing or no longer matching the forge | ✅ read on every pass |
| _(not in the store)_ a hive's mTLS leaf | the store's PKI, or you by hand | the hive itself, from disk | must be stated | must be stated |
<!-- vale write-good.Passive = YES --> <!-- vale write-good.Passive = YES -->

View file

@ -1,6 +1,6 @@
| `deploy.victoriametrics.agentAuthRate` | Default `50r/s` per client address, for agent reads checked by `swarm-metrics-agent-auth`; over it and `agentAuthBurst`, the gateway answers 403. | | `deploy.victoriametrics.agentAuthRate` | Default `50r/s` per client address, for agent reads checked by `swarm-metrics-agent-auth`; over it and `agentAuthBurst`, the gateway answers 403. |
| `deploy.victoriametrics.agentAuthBurst` | Default `500` requests above `agentAuthRate` before the 403s start. | | `deploy.victoriametrics.agentAuthBurst` | Default `500` requests above `agentAuthRate` before the 403s start. |
| `deploy.victoriametrics.agentAuthVerdictTtl` | Default `60` seconds that `swarm-metrics-agent-auth` keeps granting an agent secret it verified. A replaced or deleted secret keeps working at the metrics store for up to that long. | | `deploy.victoriametrics.agentAuthVerdictTtl` | Default `60` seconds that `swarm-metrics-agent-auth` keeps granting an agent secret it verified. A replaced or deleted secret keeps working at the metrics store for up to that long. A revoked `metrics` permission does too. |
| `deploy.victoriametrics.agentAuthPackage` | The `swarm-logs-auth` build that runs as `swarm-metrics-agent-auth`. Set on its own: `deploy.victorialogs.authPackage` doesn't reach it. | | `deploy.victoriametrics.agentAuthPackage` | The `swarm-logs-auth` build that runs as `swarm-metrics-agent-auth`. Set on its own: `deploy.victorialogs.authPackage` doesn't reach it. |
# Swarm-wide services # Swarm-wide services
@ -249,7 +249,8 @@ vhost does it:
store, and `swarm-metrics-auth` on the store's host checks it against the store, and `swarm-metrics-auth` on the store's host checks it against the
same store path. An agent's `swarm-metrics` sends its same store path. An agent's `swarm-metrics` sends its
`swarm-agent.<agent>.<secret>` bearer, which `swarm-metrics-agent-auth` on `swarm-agent.<agent>.<secret>` bearer, which `swarm-metrics-agent-auth` on
the store's host checks against `swarm/agents/<agent>/queue`. A request the store's host checks against `swarm/agents/<agent>/queue`. It also needs the `metrics`
permission, or the answer is a 403. A request
without a bearer needs an operator's authelia session (group `admins`); without a bearer needs an operator's authelia session (group `admins`);
without one it gets a 401, not a login redirect. without one it gets a 401, not a login redirect.
- **vmui**: an operator's authelia session, with a redirect to the login. - **vmui**: an operator's authelia session, with a redirect to the login.
@ -305,22 +306,23 @@ Drilldown_ app is deliberately not installed: it only supports Loki, and
no setting here changes that, so Explore is the log browser for this no setting here changes that, so Explore is the log browser for this
swarm. swarm.
| Option | When you'd touch it | | Option | When you'd touch it |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deploy.victorialogs.retentionPeriod` | Default `30d`, far shorter than the metrics store's — logs are bulkier per unit of value and are typically read within days of ingestion. Raise it if you need to answer questions about last quarter. | | `deploy.victorialogs.retentionPeriod` | Default `30d`, far shorter than the metrics store's — logs are bulkier per unit of value and are typically read within days of ingestion. Raise it if you need to answer questions about last quarter. |
| `deploy.victorialogs.authRate` | Default `50r/s` per client address, for agent queries checked by `swarm-logs-auth`; over it and `authBurst`, the gateway answers 403. Agents on one host share the address; the default covers about a hundred cold-starting together. | | `deploy.victorialogs.authRate` | Default `50r/s` per client address, for agent queries checked by `swarm-logs-auth`; over it and `authBurst`, the gateway answers 403. Agents on one host share the address; the default covers about a hundred cold-starting together. |
| `deploy.victorialogs.authBurst` | Default `500` requests above `authRate` before the 403s start. | | `deploy.victorialogs.authBurst` | Default `500` requests above `authRate` before the 403s start. |
| `deploy.victorialogs.authVerdictTtl` | Default `60` seconds that `swarm-logs-auth` keeps granting an agent secret it verified, without asking the secret store. A replaced or deleted secret keeps working at the log store for up to that long. | | `deploy.victorialogs.authVerdictTtl` | Default `60` seconds that `swarm-logs-auth` keeps granting an agent secret it verified, without asking the secret store. A replaced or deleted secret keeps working at the log store for up to that long. A revoked `logs` permission does too. |
| `deploy.victorialogs.grafanaAuthPackage` | The `swarm-metrics-auth` build that runs as `swarm-logs-grafana-auth`. Set on its own: `deploy.victoriametrics.authPackage` doesn't reach it. | | `deploy.victorialogs.grafanaAuthPackage` | The `swarm-metrics-auth` build that runs as `swarm-logs-grafana-auth`. Set on its own: `deploy.victoriametrics.authPackage` doesn't reach it. |
| `swarm.victorialogs.domain` | Only to rename it. | | `swarm.victorialogs.domain` | Only to rename it. |
| `deploy.victorialogs.port` | Only if something else on the services host already claims `9428`. | | `deploy.victorialogs.port` | Only if something else on the services host already claims `9428`. |
It binds loopback and takes no credential of its own: the gateway vhost is It binds loopback and takes no credential of its own: the gateway vhost is
the only way in, and the collector is the only intended writer. the only way in, and the collector is the only intended writer.
**Who may query.** `/select/logsql/` takes one of three credentials. An **Who may query.** `/select/logsql/` takes one of three credentials. An
agent presents its `swarm-agent.<agent>.<secret>` bearer, checked by agent presents its `swarm-agent.<agent>.<secret>` bearer, checked by
`swarm-logs-auth`. Grafana's datasource presents the same bearer as its `swarm-logs-auth`. The agent must also hold the `logs` permission,
which is off by default; without it the answer is a 403 (`docs/process/conventions.md`, Permissions). Grafana's datasource presents the same bearer as its
metrics datasource, which `swarm-bao-grafana-metrics-bearer` creates, and a metrics datasource, which `swarm-bao-grafana-metrics-bearer` creates, and a
second `swarm-metrics-auth` instance (`swarm-logs-grafana-auth`) on the log second `swarm-metrics-auth` instance (`swarm-logs-grafana-auth`) on the log
store's host checks it against the same store path; the gateway tells it from store's host checks it against the same store path; the gateway tells it from

View file

@ -256,7 +256,7 @@ Replace the permissions the swarm grants an agent; the internet flag stays unles
###### **Options:** ###### **Options:**
* `--permissions <PERMISSIONS>` — The permissions to grant, comma-separated: any of `messaging`, `meta`, `inbox`, `execution`, `web_tools`, `manage_root_agent`. `--permissions ''` grants none * `--permissions <PERMISSIONS>` — The permissions to grant, comma-separated: any of `messaging`, `meta`, `inbox`, `execution`, `web_tools`, `manage_root_agent`, `logs`, `metrics`. `--permissions ''` grants none
* `--unrestricted-internet <BOOL>` — Whether the agent's traffic may leave the host unfiltered. Left out, the stored value stays * `--unrestricted-internet <BOOL>` — Whether the agent's traffic may leave the host unfiltered. Left out, the stored value stays
Possible values: `true`, `false` Possible values: `true`, `false`

View file

@ -89,7 +89,9 @@ reaches that one leaf per agent: the queue's auth callout (`swarm-nats-auth`),
the log store's agent check (`swarm-logs-auth`, on the log store's host), and the log store's agent check (`swarm-logs-auth`, on the log store's host), and
the metrics store's (`swarm-metrics-agent-auth`, under the `swarm-metrics-auth` the metrics store's (`swarm-metrics-agent-auth`, under the `swarm-metrics-auth`
leaf on the metrics store's host). Any one compromised can present any agent's leaf on the metrics store's host). Any one compromised can present any agent's
queue secret, at the queue and at both stores' read routes alike. queue secret, at the queue and at both stores' read routes alike. The two store checks also read the
agent's `swarm/agents/<agent>/observability` leaf, which only the controller writes, and let
the agent through only with the `logs` or `metrics` permission it names.
### Per-hive credentials live under the hive kind ### Per-hive credentials live under the hive kind

View file

@ -1,8 +1,8 @@
// <SetupAssistant> - the start page's first-time helper: a paperclip with a // <SetupAssistant> - the start page's first-time helper: a paperclip with a
// speech bubble offering to set up an agent. It renders only while the swarm // speech bubble offering to set up an agent. It renders only while the swarm
// has no `ruth` (see `ruthIsMissing`), and a click opens the create-agent // has no `ruth` (see `ruthIsMissing`), and a click opens the create-agent
// form with her name filled in and `manage_root_agent` checked on top of the // form with her name filled in and `manage_root_agent`, `logs` and
// default permissions (`RUTH_EXTRA_PERMISSIONS`); the form already selects // `metrics` checked on top of the default permissions (`RUTH_EXTRA_PERMISSIONS`); the form already selects
// the only hive. No dismiss: once ruth exists it goes away. // the only hive. No dismiss: once ruth exists it goes away.
import { useEffect, useState } from "preact/hooks"; import { useEffect, useState } from "preact/hooks";
import { Dialog } from "../ui/dialog/Dialog.js"; import { Dialog } from "../ui/dialog/Dialog.js";

View file

@ -27,5 +27,9 @@ export async function ruthIsMissing(fetchImpl: Fetch): Promise<boolean> {
} }
/** What the setup assistant's create form checks on top of the default set: /** What the setup assistant's create form checks on top of the default set:
* ruth recovers the other agents, which takes `manage_root_agent`. */ * ruth recovers the other agents, which takes `manage_root_agent`, and reads
export const RUTH_EXTRA_PERMISSIONS = ["manage_root_agent"]; * the swarm's logs and metrics, which are off by default. swarm-controller
* refuses `logs` and `metrics` (409, naming the hive) for a hive that does
* not advertise `tolerant-permissions`; the form shows that error, and
* unticking them creates ruth without. */
export const RUTH_EXTRA_PERMISSIONS = ["manage_root_agent", "logs", "metrics"];

View file

@ -58,17 +58,24 @@ test("anything but a clear answer is not missing", async () => {
); );
}); });
// The assistant's create form sends `manage_root_agent` with the default // The assistant's create form sends `manage_root_agent`, `logs` and `metrics` with
// set, so a new ruth holds it from her first start; the default alone does not. // the default set, so a new ruth holds them from her first start; the default
test("the assistant creates ruth with manage_root_agent", () => { // alone does not.
test("the assistant creates ruth with manage_root_agent, logs and metrics", () => {
const defaults = ["messaging", "meta", "inbox", "execution"]; const defaults = ["messaging", "meta", "inbox", "execution"];
const all = [...defaults, "web_tools", "manage_root_agent"]; const all = [
...defaults,
"web_tools",
"manage_root_agent",
"logs",
"metrics",
];
assert.deepEqual( assert.deepEqual(
requestPermissions( requestPermissions(
initialSelection(all, defaults, RUTH_EXTRA_PERMISSIONS), initialSelection(all, defaults, RUTH_EXTRA_PERMISSIONS),
defaults, defaults,
), ),
[...defaults, "manage_root_agent"], [...defaults, "manage_root_agent", "logs", "metrics"],
); );
assert.equal( assert.equal(
requestPermissions(initialSelection(all, defaults, []), defaults), requestPermissions(initialSelection(all, defaults, []), defaults),

View file

@ -35,6 +35,7 @@ use tokio::time::{Interval, MissedTickBehavior};
use swarm_wire::agent_inference::Effective; use swarm_wire::agent_inference::Effective;
use swarm_wire::agent_login::Login; use swarm_wire::agent_login::Login;
use swarm_wire::hive_status::{Capabilities, TOLERANT_PERMISSIONS};
use swarm_wire::wanted::AgentState; use swarm_wire::wanted::AgentState;
use crate::events::{Bus, BusEvent, LiveEvent, TurnState}; use crate::events::{Bus, BusEvent, LiveEvent, TurnState};
@ -100,6 +101,10 @@ struct AgentStateMsg {
/// `needs_login`, from this process's own [`LoginState`], so always set. /// `needs_login`, from this process's own [`LoginState`], so always set.
#[serde(flatten)] #[serde(flatten)]
login: Login, login: Login,
/// What this harness can do, so swarm-controller grants an agent a
/// permission only when the harness running it can decode it.
#[serde(flatten)]
capabilities: Capabilities,
} }
/// What this process can honestly report about the agent-state axis. /// What this process can honestly report about the agent-state axis.
@ -140,6 +145,13 @@ fn login(state: LoginState) -> Login {
/// Build the current header from the bus, the login state and the pause /// Build the current header from the bus, the login state and the pause
/// marker. /// marker.
/// The capabilities this build reports.
fn capabilities() -> Capabilities {
Capabilities {
capabilities: vec![TOLERANT_PERMISSIONS.to_owned()],
}
}
fn snapshot(bus: &Bus, login_state: &Mutex<LoginState>) -> AgentStateMsg { fn snapshot(bus: &Bus, login_state: &Mutex<LoginState>) -> AgentStateMsg {
let (turn_state, since_unix) = bus.state_snapshot(); let (turn_state, since_unix) = bus.state_snapshot();
let model = bus.model(); let model = bus.model();
@ -158,6 +170,7 @@ fn snapshot(bus: &Bus, login_state: &Mutex<LoginState>) -> AgentStateMsg {
ctx_usage: bus.last_ctx_usage(), ctx_usage: bus.last_ctx_usage(),
cost_usage: bus.last_cost_usage(), cost_usage: bus.last_cost_usage(),
login: login(*login_state.lock().unwrap_or_else(PoisonError::into_inner)), login: login(*login_state.lock().unwrap_or_else(PoisonError::into_inner)),
capabilities: capabilities(),
} }
} }
@ -332,12 +345,14 @@ async fn publish(
#[cfg(test)] #[cfg(test)]
mod tests { mod tests {
use super::{ use super::{
AgentStateMsg, REFRESH_INTERVAL, Trigger, due, login, next_trigger, refresh_timer, snapshot, AgentStateMsg, REFRESH_INTERVAL, Trigger, capabilities, due, login, next_trigger,
refresh_timer, snapshot,
}; };
use crate::events::{BusEvent, LiveEvent, TurnState}; use crate::events::{BusEvent, LiveEvent, TurnState};
use crate::login::LoginState; use crate::login::LoginState;
use std::sync::Mutex; use std::sync::Mutex;
use swarm_wire::agent_inference::{Effective, Source}; use swarm_wire::agent_inference::{Effective, Source};
use swarm_wire::hive_status::{Capabilities, TOLERANT_PERMISSIONS};
use swarm_wire::wanted::AgentState; use swarm_wire::wanted::AgentState;
use tokio::sync::broadcast; use tokio::sync::broadcast;
use tokio::time::{Duration, Instant}; use tokio::time::{Duration, Instant};
@ -387,6 +402,7 @@ mod tests {
"cache_creation_input_tokens": 88, "cache_creation_input_tokens": 88,
}))), }))),
login: login(LoginState::NeedsLogin), login: login(LoginState::NeedsLogin),
capabilities: capabilities(),
} }
} }
@ -406,6 +422,7 @@ mod tests {
keys, keys,
[ [
"agent_state", "agent_state",
"capabilities",
"context_window_tokens", "context_window_tokens",
"cost_usage", "cost_usage",
"ctx_usage", "ctx_usage",
@ -505,6 +522,14 @@ mod tests {
} }
} }
/// swarm-controller reads the harness's capabilities back out of a header.
#[test]
fn the_header_advertises_tolerant_permissions() {
let bytes = serde_json::to_vec(&msg()).expect("serialises");
let decoded: Capabilities = serde_json::from_slice(&bytes).expect("decodes");
assert!(decoded.has(TOLERANT_PERMISSIONS));
}
/// A login landing, or a logout, changes the header the next bus event /// A login landing, or a logout, changes the header the next bus event
/// rebuilds, so it goes out without waiting for a refresh. /// rebuilds, so it goes out without waiting for a refresh.
#[test] #[test]

View file

@ -396,15 +396,29 @@ pub(crate) fn queue_first_deploy(
coord.job_queue.insert_first_deploy_once(agent) coord.job_queue.insert_first_deploy_once(agent)
} }
/// Offer one snapshot: this hive's current readiness, under its own key. /// The snapshot a hive offers: its readiness, and what it can do (`swarm_wire::hive_status`).
#[derive(serde::Serialize)]
struct Snapshot {
#[serde(flatten)]
readiness: crate::warnings::Readiness,
capabilities: &'static [&'static str],
}
fn snapshot() -> Snapshot {
Snapshot {
readiness: crate::warnings::readiness(),
capabilities: &[swarm_wire::hive_status::TOLERANT_PERMISSIONS],
}
}
/// Offer one snapshot under this hive's own key.
async fn publish(client: &async_nats::Client, hive: &str) -> Result<()> { async fn publish(client: &async_nats::Client, hive: &str) -> Result<()> {
// An unconnected client does not fail a JetStream request, it hangs // An unconnected client does not fail a JetStream request, it hangs
// on it — which here would hang the loop, shutdown arm included. // on it — which here would hang the loop, shutdown arm included.
swarm_queue_client::ensure_connected(client)?; swarm_queue_client::ensure_connected(client)?;
let store = swarm_queue_client::status::open_or_create(client).await?; let store = swarm_queue_client::status::open_or_create(client).await?;
let payload = let payload = serde_json::to_vec(&snapshot()).context("serialising the snapshot")?;
serde_json::to_vec(&crate::warnings::readiness()).context("serialising the readiness")?;
store store
.put(hive, payload.into()) .put(hive, payload.into())
.await .await
@ -427,3 +441,20 @@ mod rev_marker_tests {
assert!(!marker_holds(&marker, "bbb"), "another rev still deploys"); assert!(!marker_holds(&marker, "bbb"), "another rev still deploys");
} }
} }
#[cfg(test)]
mod snapshot_tests {
use super::snapshot;
/// The controller reads the capability out of the published bytes with
/// the wire type, and the readiness keeps its own top-level fields.
#[test]
fn the_snapshot_advertises_tolerant_permissions_beside_the_readiness() {
let value = serde_json::to_value(snapshot()).unwrap();
assert!(
swarm_wire::hive_status::Capabilities::of_snapshot(&value)
.has(swarm_wire::hive_status::TOLERANT_PERMISSIONS)
);
assert!(value.get("status").is_some() && value.get("warnings").is_some());
}
}

View file

@ -9,6 +9,7 @@ workspace = true
[dependencies] [dependencies]
serde.workspace = true serde.workspace = true
tracing.workspace = true
[dev-dependencies] [dev-dependencies]
serde_json.workspace = true serde_json.workspace = true

View file

@ -9,7 +9,7 @@
mod permission; mod permission;
pub use permission::Permission; pub use permission::{Permission, deserialize_known};
pub mod review; pub mod review;
pub mod term_msg; pub mod term_msg;

View file

@ -38,6 +38,15 @@ pub enum Permission {
/// thing to manage. Kept under that spelling because every stored grant /// thing to manage. Kept under that spelling because every stored grant
/// carries it. /// carries it.
ManageRootAgent, ManageRootAgent,
/// Read access to the log store: what `swarm-logs` queries. Checked by
/// the log gateway's `swarm-logs-auth` against the grant swarm-controller
/// mirrors into the secret store, so `tools()` is empty. Not in
/// [`Permission::DEFAULT`].
Logs,
/// Read access to the metrics store: what `swarm-metrics` queries.
/// Checked like [`Permission::Logs`], for the metrics gateway. Not in
/// [`Permission::DEFAULT`].
Metrics,
} }
impl Permission { impl Permission {
@ -49,6 +58,8 @@ impl Permission {
Self::Execution, Self::Execution,
Self::WebTools, Self::WebTools,
Self::ManageRootAgent, Self::ManageRootAgent,
Self::Logs,
Self::Metrics,
]; ];
/// What an agent the swarm sets nothing for holds, whatever its name. /// What an agent the swarm sets nothing for holds, whatever its name.
@ -69,8 +80,13 @@ impl Permission {
// — an out-of-process server has no later enforcement point, so // — an out-of-process server has no later enforcement point, so
// that gate is the actual security boundary. `WebTools` grants // that gate is the actual security boundary. `WebTools` grants
// Claude built-ins (`builtin_tools()`); `ManageRootAgent` grants // Claude built-ins (`builtin_tools()`); `ManageRootAgent` grants
// bind mounts. // bind mounts; `Logs` and `Metrics` are checked by the store
Self::Execution | Self::WebTools | Self::ManageRootAgent => &[], // gateways, not by a tool allowlist.
Self::Execution
| Self::WebTools
| Self::ManageRootAgent
| Self::Logs
| Self::Metrics => &[],
} }
} }
@ -115,8 +131,43 @@ impl Permission {
Self::Execution => "execution", Self::Execution => "execution",
Self::WebTools => "web_tools", Self::WebTools => "web_tools",
Self::ManageRootAgent => "manage_root_agent", Self::ManageRootAgent => "manage_root_agent",
Self::Logs => "logs",
Self::Metrics => "metrics",
} }
} }
/// The permission stored under `name`; `None` for a name this build does
/// not know.
#[must_use]
pub fn from_name(name: &str) -> Option<Self> {
Self::ALL.iter().copied().find(|p| p.as_str() == name)
}
}
/// Decodes a stored permission list, skipping names this build does not know.
/// For `#[serde(deserialize_with)]` on a stored record: a permission a newer
/// swarm adds must not cost an older reader the rest of the record.
///
/// # Errors
///
/// When the value is not a list of strings.
pub fn deserialize_known<'de, D>(d: D) -> Result<Option<Vec<Permission>>, D::Error>
where
D: serde::Deserializer<'de>,
{
let names: Option<Vec<String>> = Option::deserialize(d)?;
Ok(names.map(|names| {
names
.iter()
.filter_map(|name| {
let known = Permission::from_name(name);
if known.is_none() {
tracing::debug!(name, "skipping a permission this build does not know");
}
known
})
.collect()
}))
} }
impl From<Permission> for &'static str { impl From<Permission> for &'static str {
@ -142,11 +193,46 @@ mod tests {
"inbox", "inbox",
"execution", "execution",
"web_tools", "web_tools",
"manage_root_agent" "manage_root_agent",
"logs",
"metrics"
] ]
); );
} }
/// Reading stores a log or metric grant is never a default: an agent the
/// swarm sets nothing for does not hold them.
#[test]
fn logs_and_metrics_are_off_by_default() {
assert!(!Permission::DEFAULT.contains(&Permission::Logs));
assert!(!Permission::DEFAULT.contains(&Permission::Metrics));
assert!(Permission::ALL.contains(&Permission::Logs));
assert!(Permission::ALL.contains(&Permission::Metrics));
}
#[derive(serde::Deserialize)]
struct Record {
#[serde(default, deserialize_with = "deserialize_known")]
permissions: Option<Vec<Permission>>,
}
#[test]
fn an_unknown_name_is_skipped_not_a_decode_failure() {
let r: Record =
serde_json::from_str(r#"{"permissions":["messaging","telepathy","logs"]}"#).unwrap();
assert_eq!(
r.permissions,
Some(vec![Permission::Messaging, Permission::Logs])
);
// Presence control: an unset field stays unset, `[]` stays empty.
let r: Record = serde_json::from_str("{}").unwrap();
assert_eq!(r.permissions, None);
let r: Record = serde_json::from_str(r#"{"permissions":[]}"#).unwrap();
assert_eq!(r.permissions, Some(vec![]));
// A list of non-strings is still a decode failure.
assert!(serde_json::from_str::<Record>(r#"{"permissions":[1]}"#).is_err());
}
/// The serde form of every variant, pinned independently of `as_str`: /// The serde form of every variant, pinned independently of `as_str`:
/// stored grants decode by it, so it must stay byte-identical. /// stored grants decode by it, so it must stay byte-identical.
#[test] #[test]
@ -158,6 +244,8 @@ mod tests {
(Permission::Execution, "\"execution\""), (Permission::Execution, "\"execution\""),
(Permission::WebTools, "\"web_tools\""), (Permission::WebTools, "\"web_tools\""),
(Permission::ManageRootAgent, "\"manage_root_agent\""), (Permission::ManageRootAgent, "\"manage_root_agent\""),
(Permission::Logs, "\"logs\""),
(Permission::Metrics, "\"metrics\""),
]; ];
assert_eq!(want.len(), Permission::ALL.len()); assert_eq!(want.len(), Permission::ALL.len());
for (perm, json) in want { for (perm, json) in want {

View file

@ -1219,7 +1219,7 @@ let
# The log store's auth responders: the agent one checks the secret an agent # The log store's auth responders: the agent one checks the secret an agent
# presents against the one stored for it (the same `+` leaf as the queue # presents against the one stored for it (the same `+` leaf as the queue
# responder's), the other checks the bearer Grafana presents against # responder's) and reads the agent's mirrored `logs`/`metrics` grant, the other checks the bearer Grafana presents against
# Grafana's metrics bearer; and the store container's journal forwarder # Grafana's metrics bearer; and the store container's journal forwarder
# reads its own client secret under the same leaf. Nothing else. # reads its own client secret under the same leaf. Nothing else.
logsAuthReaders = [ logsAuthReaders = [
@ -1229,6 +1229,7 @@ let
batchToken = true; batchToken = true;
policyText = policyText =
readStanza "${credentialMountPath}/data/swarm/agents/+/queue" readStanza "${credentialMountPath}/data/swarm/agents/+/queue"
+ readStanza "${credentialMountPath}/data/swarm/agents/+/observability"
+ readStanza "${credentialMountPath}/data/${grafanaMetricsBearerLeaf}" + readStanza "${credentialMountPath}/data/${grafanaMetricsBearerLeaf}"
# The journal forwarder in the store's container, under this same leaf. # The journal forwarder in the store's container, under this same leaf.
+ readStanza "${credentialMountPath}/data/swarm/services/${hyperhiveCfg.swarm.victorialogs.otel.clientId}/oidc/client"; + readStanza "${credentialMountPath}/data/swarm/services/${hyperhiveCfg.swarm.victorialogs.otel.clientId}/oidc/client";
@ -1237,7 +1238,7 @@ let
# The metrics store's responders under one leaf: the agent one checks the # The metrics store's responders under one leaf: the agent one checks the
# secret an agent presents against the one stored for it (the same `+` leaf # secret an agent presents against the one stored for it (the same `+` leaf
# as the log store's), the other checks the bearer Grafana presents; and the # as the log store's) and reads the agent's mirrored grant, the other checks the bearer Grafana presents; and the
# host unit that fetches the store container's journal forwarder secret. # host unit that fetches the store container's journal forwarder secret.
# Nothing else. # Nothing else.
metricsAuthReaders = [ metricsAuthReaders = [
@ -1247,6 +1248,7 @@ let
batchToken = true; batchToken = true;
policyText = policyText =
readStanza "${credentialMountPath}/data/swarm/agents/+/queue" readStanza "${credentialMountPath}/data/swarm/agents/+/queue"
+ readStanza "${credentialMountPath}/data/swarm/agents/+/observability"
+ readStanza "${credentialMountPath}/data/${grafanaMetricsBearerLeaf}" + readStanza "${credentialMountPath}/data/${grafanaMetricsBearerLeaf}"
# The metrics store container's journal forwarder, fetched on its host. # The metrics store container's journal forwarder, fetched on its host.
+ readStanza "${credentialMountPath}/data/swarm/services/${hyperhiveCfg.swarm.victoriametrics.otel.clientId}/oidc/client"; + readStanza "${credentialMountPath}/data/swarm/services/${hyperhiveCfg.swarm.victoriametrics.otel.clientId}/oidc/client";

View file

@ -216,8 +216,9 @@ in
without reading the secret store. A denial is never remembered. without reading the secret store. A denial is never remembered.
This is also how long a re-minted or deleted queue secret keeps working This is also how long a re-minted or deleted queue secret keeps working
at the log store's query route after its last successful check. `0` at the log store's query route after its last successful check. It is
checks the store on every query. equally how long a revoked `logs` permission keeps working. `0` checks
the store on every query.
''; '';
}; };
@ -514,6 +515,7 @@ in
"--socket ${logsAuthSocket}" "--socket ${logsAuthSocket}"
# The role ./swarm-bao.nix writes on the store's `cert` mount. # The role ./swarm-bao.nix writes on the store's `cert` mount.
"--store-cert-role swarm-logs-auth" "--store-cert-role swarm-logs-auth"
"--surface logs"
"--verdict-ttl ${toString deployCfg.victorialogs.authVerdictTtl}" "--verdict-ttl ${toString deployCfg.victorialogs.authVerdictTtl}"
]; ];
# Paths only: `argv` is world-readable via /proc/<pid>/cmdline. # Paths only: `argv` is world-readable via /proc/<pid>/cmdline.

View file

@ -295,8 +295,9 @@ in
remembered. remembered.
This is also how long a re-minted or deleted queue secret keeps working This is also how long a re-minted or deleted queue secret keeps working
at the metrics store's read API after its last successful check. `0` at the metrics store's read API after its last successful check. It is
checks the store on every query. equally how long a revoked `metrics` permission keeps working. `0` checks
the store on every query.
''; '';
}; };
@ -610,6 +611,7 @@ in
"${deployCfg.victoriametrics.agentAuthPackage}/bin/swarm-logs-auth" "${deployCfg.victoriametrics.agentAuthPackage}/bin/swarm-logs-auth"
"--socket ${agentAuthSocket}" "--socket ${agentAuthSocket}"
"--store-cert-role swarm-metrics-auth" "--store-cert-role swarm-metrics-auth"
"--surface metrics"
"--verdict-ttl ${toString deployCfg.victoriametrics.agentAuthVerdictTtl}" "--verdict-ttl ${toString deployCfg.victoriametrics.agentAuthVerdictTtl}"
]; ];
LoadCredential = lib.mapAttrsToList (id: path: "${id}:${path}") metricsAuthStoreFiles; LoadCredential = lib.mapAttrsToList (id: path: "${id}:${path}") metricsAuthStoreFiles;

View file

@ -835,7 +835,7 @@ let
# Every agent's queue secret, Grafana's metrics bearer and the store # Every agent's queue secret, Grafana's metrics bearer and the store
# container forwarder's client secret, all read-only, and nothing else: # container forwarder's client secret, all read-only, and nothing else:
# this principal checks a presented secret and does nothing with it. # this principal checks a presented secret and does nothing with it.
name = "the log store responder's grant is every agent's queue secret, Grafana's bearer and its container forwarder's client secret, read-only, and nothing else"; name = "the log store responder's grant is every agent's queue secret and log/metric grant, Grafana's bearer and its container forwarder's client secret, read-only, and nothing else";
ok = ok =
let let
s = baoGrantHere.systemd.services.swarm-bao-logs-auth-policy.script; s = baoGrantHere.systemd.services.swarm-bao-logs-auth-policy.script;
@ -845,6 +845,10 @@ let
path = "secret/data/swarm/agents/+/queue"; path = "secret/data/swarm/agents/+/queue";
caps = [ "read" ]; caps = [ "read" ];
} }
{
path = "secret/data/swarm/agents/+/observability";
caps = [ "read" ];
}
{ {
path = "secret/data/swarm/services/swarm-grafana/metrics/bearer"; path = "secret/data/swarm/services/swarm-grafana/metrics/bearer";
caps = [ "read" ]; caps = [ "read" ];
@ -871,7 +875,7 @@ let
# creates and the store container forwarder's client secret, and nothing # creates and the store container forwarder's client secret, and nothing
# else: this principal checks presented bearers, and its host fetches # else: this principal checks presented bearers, and its host fetches
# one secret for the container. # one secret for the container.
name = "the metrics store responder's grant is agents' queue secrets, Grafana's metrics bearer and its container forwarder's client secret, read-only, and nothing else"; name = "the metrics store responder's grant is agents' queue secrets and log/metric grants, Grafana's metrics bearer and its container forwarder's client secret, read-only, and nothing else";
ok = ok =
let let
s = baoGrantHere.systemd.services.swarm-bao-metrics-auth-policy.script; s = baoGrantHere.systemd.services.swarm-bao-metrics-auth-policy.script;
@ -881,6 +885,10 @@ let
path = "secret/data/swarm/agents/+/queue"; path = "secret/data/swarm/agents/+/queue";
caps = [ "read" ]; caps = [ "read" ];
} }
{
path = "secret/data/swarm/agents/+/observability";
caps = [ "read" ];
}
{ {
path = "secret/data/swarm/services/swarm-grafana/metrics/bearer"; path = "secret/data/swarm/services/swarm-grafana/metrics/bearer";
caps = [ "read" ]; caps = [ "read" ];

View file

@ -998,6 +998,7 @@ let
&& !(hasStorePath "${logs.authPackage}" agentUnit.serviceConfig.ExecStart) && !(hasStorePath "${logs.authPackage}" agentUnit.serviceConfig.ExecStart)
&& hasStorePath "${v.authPackage}/bin/swarm-metrics-auth " unit.serviceConfig.ExecStart && hasStorePath "${v.authPackage}/bin/swarm-metrics-auth " unit.serviceConfig.ExecStart
&& lib.hasInfix "--store-cert-role swarm-metrics-auth" agentUnit.serviceConfig.ExecStart && lib.hasInfix "--store-cert-role swarm-metrics-auth" agentUnit.serviceConfig.ExecStart
&& lib.hasInfix "--surface metrics" agentUnit.serviceConfig.ExecStart
&& lib.hasInfix "--verdict-ttl ${toString v.agentAuthVerdictTtl}" agentUnit.serviceConfig.ExecStart && lib.hasInfix "--verdict-ttl ${toString v.agentAuthVerdictTtl}" agentUnit.serviceConfig.ExecStart
&& agentUnit.serviceConfig.LoadCredential == unit.serviceConfig.LoadCredential && agentUnit.serviceConfig.LoadCredential == unit.serviceConfig.LoadCredential
&& lib.hasInfix "limit_req_zone $binary_remote_addr zone=swarm_metrics_agent_auth:1m rate=${v.agentAuthRate};" http && lib.hasInfix "limit_req_zone $binary_remote_addr zone=swarm_metrics_agent_auth:1m rate=${v.agentAuthRate};" http
@ -1143,6 +1144,7 @@ let
&& lib.hasInfix "internal;" l."= /__swarm_logs_agent_auth".extraConfig && lib.hasInfix "internal;" l."= /__swarm_logs_agent_auth".extraConfig
&& l."= /__swarm_logs_agent_auth".proxyPass == "http://unix:/run/swarm-logs-auth/auth.sock:/" && l."= /__swarm_logs_agent_auth".proxyPass == "http://unix:/run/swarm-logs-auth/auth.sock:/"
&& lib.hasInfix "--socket /run/swarm-logs-auth/auth.sock" unit.serviceConfig.ExecStart && lib.hasInfix "--socket /run/swarm-logs-auth/auth.sock" unit.serviceConfig.ExecStart
&& lib.hasInfix "--surface logs" unit.serviceConfig.ExecStart
&& lib.hasInfix "internal;" l."= /__swarm_logs_grafana_auth".extraConfig && lib.hasInfix "internal;" l."= /__swarm_logs_grafana_auth".extraConfig
&& &&
l."= /__swarm_logs_grafana_auth".proxyPass == "http://unix:/run/swarm-logs-grafana-auth/auth.sock:/" l."= /__swarm_logs_grafana_auth".proxyPass == "http://unix:/run/swarm-logs-grafana-auth/auth.sock:/"

View file

@ -5,6 +5,7 @@ edition.workspace = true
[dependencies] [dependencies]
anyhow.workspace = true anyhow.workspace = true
serde.workspace = true
# Comparing an agent's presented secret with the stored one. # Comparing an agent's presented secret with the stored one.
subtle.workspace = true subtle.workspace = true
# The read of the stored credential the token is checked against. # The read of the stored credential the token is checked against.

Some files were not shown because too many files have changed in this diff Show more