Watch
0
0
Fork
You've already forked hyperhive
0

swarm: an agent's backend secrets get a store leaf of their own, and its backend environment reads back

The credentials of an agent's backend (ANTHROPIC_API_KEY and the like) move to their own leaf, swarm/agents/<agent>/backend-secrets, written through new PUT, GET and DELETE routes on /api/hives/{hive}/agents/{agent}/backend-secrets. GET says only whether any are stored. The backend environment at backend-env now reads back as stored through GET on its route, so it holds configuration only.

The agent's hive-agent-backend-env unit now runs on every agent with a store, reads both leaves and writes the configuration and then the secrets into the one file the harness and the subagent daemon load, so a secret wins over a variable of the same name. It removes the file when the store holds neither. The harness counts an agent whose environment holds ANTHROPIC_API_KEY or ANTHROPIC_AUTH_TOKEN as API-billed, so it tries the key instead of waiting for a Claude login; a real 401 still sets needs-login. The controller's policy may delete the new leaf.

Tests: the secret-client path, the controller routes, the script test of the unit with a stub bao, the module-eval cases and the harness's mode check. Docs: the swarm UI routes, the credentials reference and the API-key provider page.
This commit is contained in:
iris 2026-11-20 20:18:43 +01:00
commit 33fdd5205e
19 changed files with 737 additions and 107 deletions

View file

@ -34,6 +34,7 @@ the rest of the cell says how.
| `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/<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>/gitlab/<label>` | `swarm-controller`, when you link a GitLab account through the API | the agent | ❌ your token; delete it and link the label again | ✅ every 2 minutes; a deleted account leaves the agent's `glab` configuration on the next run | | `swarm/agents/<agent>/gitlab/<label>` | `swarm-controller`, when you link a GitLab account through the API | the agent | ❌ your token; delete it and link the label again | ✅ every 2 minutes; a deleted account leaves the agent's `glab` configuration on the next run |
| `swarm/agents/<agent>/github-token` | `swarm-controller`, when you link a GitHub account in the swarm UI | the agent, which keeps it in `/run` only; the `<state>/github-token` copy of an earlier version is no longer read | ❌ your token; delete it and link again | ✅ every 2 minutes | | `swarm/agents/<agent>/github-token` | `swarm-controller`, when you link a GitHub account in the swarm UI | the agent, which keeps it in `/run` only; the `<state>/github-token` copy of an earlier version is no longer read | ❌ your token; delete it and link again | ✅ every 2 minutes |
| `swarm/agents/<agent>/backend-secrets` | `swarm-controller`, when you set the API key or the secrets in the swarm UI; no unit writes it | the agent, read-only, through `hive-agent-backend-env` | ❌ nothing replaces it without you | ❌ the file in `/run` refreshes every 2 minutes, and the harness loads it at its next start |
| `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>/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>/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>/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; 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/hives/<hive>/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 |
@ -138,7 +139,7 @@ pieces fit, and the reasoning behind them, is in [`credentials.md`](../../2-hand
| the hive collector's copy of its hive's OIDC secret | `swarm-bao-hive-otel-oidc.service` reads it out of the swarm secret store under the hive's own leaf, **on every hive that runs the collector and holds that leaf**; the leaf is the source | `/run/hive-otel-oidc/hive-<name>.secret` on the hive's host tmpfs, 0400 root, loaded by `LoadCredential` — never on persistent disk, so a reboot fetches it again | same unit, same path, co-located or not. Nothing for an operator to place beyond the hive's store leaf (`deploy.bao.clientCertFile`). Naming a secret file with `otel.clientSecretFile` instead is legacy for a host without a leaf: the build warns, and the fix is to place the leaf from `/var/lib/swarm-bao-pki/hives/<hive>/` and drop the setting | | the hive collector's copy of its hive's OIDC secret | `swarm-bao-hive-otel-oidc.service` reads it out of the swarm secret store under the hive's own leaf, **on every hive that runs the collector and holds that leaf**; the leaf is the source | `/run/hive-otel-oidc/hive-<name>.secret` on the hive's host tmpfs, 0400 root, loaded by `LoadCredential` — never on persistent disk, so a reboot fetches it again | same unit, same path, co-located or not. Nothing for an operator to place beyond the hive's store leaf (`deploy.bao.clientCertFile`). Naming a secret file with `otel.clientSecretFile` instead is legacy for a host without a leaf: the build warns, and the fix is to place the leaf from `/var/lib/swarm-bao-pki/hives/<hive>/` and drop the setting |
| the swarm controller's forge token | the forge's `forgejo-swarm-controller-account`, in-container, once. An attempt that fails or runs past 30 seconds retries after 5 seconds, then at growing intervals up to 5 minutes | the swarm secret store at `swarm/controller/swarm-controller/forge/token`, written by the mint under the forge publisher's leaf, which the forge container loads as a credential; the controller holds it in memory only. `/var/lib/forgejo/swarm-controller-token-name` in the forge container holds its name, the minter's record that it has minted | nothing to place beyond the controller's store leaf. A forge host without the store needs the publisher's leaf placed (`deploy.bao.forgePublisherClientCertFile`) | | the swarm controller's forge token | the forge's `forgejo-swarm-controller-account`, in-container, once. An attempt that fails or runs past 30 seconds retries after 5 seconds, then at growing intervals up to 5 minutes | the swarm secret store at `swarm/controller/swarm-controller/forge/token`, written by the mint under the forge publisher's leaf, which the forge container loads as a credential; the controller holds it in memory only. `/var/lib/forgejo/swarm-controller-token-name` in the forge container holds its name, the minter's record that it has minted | nothing to place beyond the controller's store leaf. A forge host without the store needs the publisher's leaf placed (`deploy.bao.forgePublisherClientCertFile`) |
| the swarm controller's Grafana token | `swarm-bao-grafana-controller-token.service`, **on the host that runs Grafana**, as Grafana's built-in admin over its socket: it creates the `swarm-controller` service account as a Viewer (and sets it back to Viewer on every run), mints a token for it and writes it to the swarm secret store at `swarm/controller/swarm-controller/grafana/token` under Grafana's leaf. It waits up to 60 seconds for Grafana's socket to answer before its first call. Re-run every ten minutes: it keeps a stored token Grafana accepts, and replaces one Grafana refuses with 401 (or a missing one), deleting every other token of that account first | the swarm secret store only; the controller reads it for `GET /api/alerts` and holds it in memory, re-reading the store once when Grafana answers 401 | nothing to place: Grafana's leaf is already required to run Grafana. Until the unit has run, `/api/alerts` answers 503 naming the empty path | | the swarm controller's Grafana token | `swarm-bao-grafana-controller-token.service`, **on the host that runs Grafana**, as Grafana's built-in admin over its socket: it creates the `swarm-controller` service account as a Viewer (and sets it back to Viewer on every run), mints a token for it and writes it to the swarm secret store at `swarm/controller/swarm-controller/grafana/token` under Grafana's leaf. It waits up to 60 seconds for Grafana's socket to answer before its first call. Re-run every ten minutes: it keeps a stored token Grafana accepts, and replaces one Grafana refuses with 401 (or a missing one), deleting every other token of that account first | the swarm secret store only; the controller reads it for `GET /api/alerts` and holds it in memory, re-reading the store once when Grafana answers 401 | nothing to place: Grafana's leaf is already required to run Grafana. Until the unit has run, `/api/alerts` answers 503 naming the empty path |
| an agent's API-key environment (`ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, an ACP provider key) | `hive-agent-backend-env.service`, in the agent's container, on an agent with a store that uses `useApiKey` or the `acp` runtime. When the store holds nothing at `swarm/agents/<agent>/backend-env` and `backendEnvironmentFile` is a non-empty file, it creates the leaf with the file's exact bytes and `-cas=0`, under the agent's own leaf, which may create that path and not update it. It never rotates a value and never rewrites or deletes the file. To set or replace a key, use **set the API-key environment** in the swarm UI (`PUT /api/hives/{hive}/agents/{agent}/backend-env`): `swarm-controller` overwrites the leaf with its own grant, and the store's value then wins over the file. Its **remove** (`DELETE` on the same path) deletes the leaf, and an agent whose file has content then creates it from that file again | the swarm secret store at that path; the unit writes it to `/run/hive-agent-backend-env/env` (tmpfs, `0600`, root), and `hive-agent` and `hive-subagent-daemon` load that after `backendEnvironmentFile` as `EnvironmentFile=` | the same unit, same path. A variable in the store wins over the same one in the file. With the store down at a start, the file alone carries the agent, as it did before the store held a copy; with an older hive build the agent ignores the leaf and keeps reading the file | | an agent's API-key environment (`ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, an ACP provider key) | `hive-agent-backend-env.service`, in the agent's container, on every agent with a store, whatever its runtime or its login kind. When the store holds nothing at `swarm/agents/<agent>/backend-env` and `backendEnvironmentFile` is a non-empty file, it creates the leaf with the file's exact bytes and `-cas=0`, under the agent's own leaf, which may create that path and not update it. It never rotates a value and never rewrites or deletes the file. To set or replace a key, use **set the API-key environment** in the swarm UI (`PUT /api/hives/{hive}/agents/{agent}/backend-env`): `swarm-controller` overwrites the leaf with its own grant, and the store's value then wins over the file. Its **remove** (`DELETE` on the same path) deletes the leaf, and an agent whose file has content then creates it from that file again | the swarm secret store at that path; the unit writes it to `/run/hive-agent-backend-env/env` (tmpfs, `0600`, root), and `hive-agent` and `hive-subagent-daemon` load that after `backendEnvironmentFile` as `EnvironmentFile=` | the same unit, same path. A variable in the store wins over the same one in the file. With the store down at a start, the file alone carries the agent, as it did before the store held a copy; with an older hive build the agent ignores the leaf and keeps reading the file |
| an agent's proxy settings (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, the credential in the proxy URL) | `hive-agent-proxy-credential.service`, in the agent's container, as the agent user, at start and every 10 minutes: it reads `swarm/agents/<agent>/proxy-credential` under the agent's own leaf and builds the file from it. It writes nothing while the path holds nothing or the hive's facts name no squid | `/run/hive-agent-proxy-credential/proxy.env` (tmpfs, `0600`, the agent user); the harness, its bash tool, the subagents, the MCP servers and the pollers load it as `EnvironmentFile=-` and read it when they start | With no credential, or on a hive that writes no `HIVE_SQUID_PROXY` and `HIVE_EGRESS_NO_PROXY` fact, nothing writes the file and a unit has no proxy variable and reaches the internet without the proxy; the host still redirects the web traffic of a `restricted` or `log` agent into squid (see [the network reference](../networking/network.md#intercepted-web-traffic)). A failed read keeps the file already in place. A unit started before the file appeared goes direct until its next start. The credential is also in the environment of every process those units start, so `env` in the agent's shell prints it | | an agent's proxy settings (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY`, the credential in the proxy URL) | `hive-agent-proxy-credential.service`, in the agent's container, as the agent user, at start and every 10 minutes: it reads `swarm/agents/<agent>/proxy-credential` under the agent's own leaf and builds the file from it. It writes nothing while the path holds nothing or the hive's facts name no squid | `/run/hive-agent-proxy-credential/proxy.env` (tmpfs, `0600`, the agent user); the harness, its bash tool, the subagents, the MCP servers and the pollers load it as `EnvironmentFile=-` and read it when they start | With no credential, or on a hive that writes no `HIVE_SQUID_PROXY` and `HIVE_EGRESS_NO_PROXY` fact, nothing writes the file and a unit has no proxy variable and reaches the internet without the proxy; the host still redirects the web traffic of a `restricted` or `log` agent into squid (see [the network reference](../networking/network.md#intercepted-web-traffic)). A failed read keeps the file already in place. A unit started before the file appeared goes direct until its next start. The credential is also in the environment of every process those units start, so `env` in the agent's shell prints it |
| an agent's claude login (`.credentials.json`) | `swarm-claude-login.service`, in its container, when an operator completes `claude auth login` from the agent's card in the swarm UI; it stores the file as a new version at `swarm/agents/<agent>/claude-credentials` under its own leaf, which may create and update that path and read nothing under an agent | the swarm secret store at that path; the agent's `hive-agent` reads it under the agent's own leaf every 30 seconds while it waits for a login and writes it to `~/.claude/.credentials.json` | the same read, co-located or not; nothing for an operator to place beyond the agent's store leaf. When the store's copy and the agent's differ the KV version decides: the agent installs only a version newer than the last it installed (`claude-credentials-version` under the harness dir), because claude rotates the refresh token in its own copy and the stored one goes stale. The agent ignores a stale or equal version, and a relogin writes a newer one — [claude-login.md](../../2-handbook/swarm/claude-login.md) | | an agent's claude login (`.credentials.json`) | `swarm-claude-login.service`, in its container, when an operator completes `claude auth login` from the agent's card in the swarm UI; it stores the file as a new version at `swarm/agents/<agent>/claude-credentials` under its own leaf, which may create and update that path and read nothing under an agent | the swarm secret store at that path; the agent's `hive-agent` reads it under the agent's own leaf every 30 seconds while it waits for a login and writes it to `~/.claude/.credentials.json` | the same read, co-located or not; nothing for an operator to place beyond the agent's store leaf. When the store's copy and the agent's differ the KV version decides: the agent installs only a version newer than the last it installed (`claude-credentials-version` under the harness dir), because claude rotates the refresh token in its own copy and the stored one goes stale. The agent ignores a stale or equal version, and a relogin writes a newer one — [claude-login.md](../../2-handbook/swarm/claude-login.md) |
| the queue responder's copy of its OIDC secret | the responder reads it out of the swarm secret store itself as it starts, under its own leaf, and again when authelia refuses it | the daemon's memory only; never on disk | same read, wherever authelia runs. Nothing for an operator to place beyond the responder's store leaf (`deploy.nats.authBaoClientCertFile`) | | the queue responder's copy of its OIDC secret | the responder reads it out of the swarm secret store itself as it starts, under its own leaf, and again when authelia refuses it | the daemon's memory only; never on disk | same read, wherever authelia runs. Nothing for an operator to place beyond the responder's store leaf (`deploy.nats.authBaoClientCertFile`) |

View file

@ -267,7 +267,8 @@ is a no-op without the other:
- **`useApiKey`** tells the harness itself not to wait for a Claude OAuth - **`useApiKey`** tells the harness itself not to wait for a Claude OAuth
session: at boot, `LoginState::from_dir` reports `Online` without session: at boot, `LoginState::from_dir` reports `Online` without
checking `~/.claude/` (`hive_agent::login::using_api_key`, reads checking `~/.claude/` (`hive_agent::login::using_api_key`, reads
`HIVE_USE_API_KEY`), and the harness stamps the fact into the `HIVE_USE_API_KEY`, and counts an environment that holds `ANTHROPIC_API_KEY`
or `ANTHROPIC_AUTH_TOKEN` too, see below), and the harness stamps the fact into the
consolidated harness state file so the operator dashboard also stops reading this consolidated harness state file so the operator dashboard also stops reading this
agent's empty `~/.claude/` as "needs login." An api-key agent that hits agent's empty `~/.claude/` as "needs login." An api-key agent that hits
a real 401 (the key itself is bad) still surfaces `needs_login` — the a real 401 (the key itself is bad) still surfaces `needs_login` — the
@ -283,8 +284,8 @@ is a no-op without the other:
(`hive-subagent-daemon`) loads the same file, so the agent's claude (`hive-subagent-daemon`) loads the same file, so the agent's claude
subagents run on the same key. subagents run on the same key.
On an agent with a secret store (`services.hyperhive.agent.bao.addr`) that uses On an agent with a secret store (`services.hyperhive.agent.bao.addr`),
`useApiKey` or the `acp` runtime, `hive-agent-backend-env.service` also keeps the `hive-agent-backend-env.service` also keeps the
file's text in the store at `swarm/agents/<agent>/backend-env`, field `env`, and file's text in the store at `swarm/agents/<agent>/backend-env`, field `env`, and
writes it to `/run/hive-agent-backend-env/env` every 2 minutes. When the store writes it to `/run/hive-agent-backend-env/env` every 2 minutes. When the store
holds nothing there, the unit creates the leaf from `backendEnvironmentFile`, holds nothing there, the unit creates the leaf from `backendEnvironmentFile`,
@ -295,7 +296,18 @@ the store down at a start the file alone carries the agent. Both read it at
their own start, so a changed value reaches a running agent at its next their own start, so a changed value reaches a running agent at its next
restart. restart.
To set or replace a key, use **set the API-key environment** on the agent in the swarm UI: An operator can also store the credentials apart from that text, at
`swarm/agents/<agent>/backend-secrets`, field `env`, with
`PUT /api/hives/{hive}/agents/{agent}/backend-secrets` (`GET` says whether the
store holds any and never returns them; `DELETE` removes them). The unit writes them into the
`/run` file after the text, so a secret wins over a variable of the same name, and
removes the file when the store holds neither. An agent whose environment holds
`ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` counts as an api-key agent even with
`useApiKey` off, so it tries the key instead of waiting for a Claude login, and a
real 401 still surfaces `needs_login`. `GET …/backend-env` reads the
text back, so it holds configuration only.
To set or replace the whole environment text, use **set the API-key environment** on the agent in the swarm UI:
it sends `PUT /api/hives/{hive}/agents/{agent}/backend-env` with the file text, it sends `PUT /api/hives/{hive}/agents/{agent}/backend-env` with the file text,
which must be blank lines, `#` or `;` comments, and `NAME=VALUE` lines of at which must be blank lines, `#` or `;` comments, and `NAME=VALUE` lines of at
most 16 KiB. A save overwrites the stored text, including text the agent wrote most 16 KiB. A save overwrites the stored text, including text the agent wrote

View file

@ -1122,8 +1122,19 @@ a link dialog closes.
stored text, including text the agent wrote into an empty leaf. The box is stored text, including text the agent wrote into an empty leaf. The box is
write-only and starts empty; **remove** sends the `DELETE` below. A write-only and starts empty; **remove** sends the `DELETE` below. A
swarm-controller without the route answers 404, and the dialog says so. swarm-controller without the route answers 404, and the dialog says so.
`GET` on the same path reads the text back as stored, so keep credentials out
of it and in the secrets below.
What the agent does with it: What the agent does with it:
[API-key provider](../turn-loop/config.md#api-key-provider-useapikey--backendenvironmentfile). [API-key provider](../turn-loop/config.md#api-key-provider-useapikey--backendenvironmentfile).
- **set the secrets** — `PUT /api/hives/{hive}/agents/{agent}/backend-secrets`
with the text of an `EnvironmentFile` (same shape and limit as the environment
above), stored apart from it at `swarm/agents/<agent>/backend-secrets`. No route
returns it: `GET` answers `{"stored": true|false}`, and `DELETE` removes it.
The agent's `hive-agent-backend-env` unit writes the environment and then these
secrets into the file the harness loads, so a secret wins over a variable of the
same name, and an agent whose environment then holds `ANTHROPIC_API_KEY` tries
the key instead of waiting for a Claude login. The harness reads the file at its
start, so a change needs an agent restart.
#### Deleting a linked account #### Deleting a linked account

View file

@ -118,14 +118,25 @@ impl LoginState {
} }
} }
/// Whether this agent is configured to authenticate to its backend with an /// Whether this agent authenticates to its backend with an API key rather than
/// API key rather than a Claude OAuth session — set by /// a Claude OAuth session: `services.hyperhive.agent.useApiKey` sets
/// `services.hyperhive.agent.useApiKey` via the `HIVE_USE_API_KEY` env var /// `HIVE_USE_API_KEY=1` (`nix/agent-modules/agent-service.nix`), and an agent
/// (`nix/agent-modules/agent-service.nix`). Read fresh on every call rather /// whose environment holds a key — one an operator stored through the swarm UI
/// than cached: it's an env var, not a value worth a `OnceLock` for. /// reaches it as `ANTHROPIC_API_KEY` (`nix/agent-modules/backend-env.nix`) —
/// counts too, so it tries the key instead of waiting for a login. Read fresh
/// on every call rather than cached: it's an env var, not a value worth a
/// `OnceLock` for.
#[must_use] #[must_use]
pub fn using_api_key() -> bool { pub fn using_api_key() -> bool {
std::env::var("HIVE_USE_API_KEY").is_ok_and(|v| v == "1") api_key_mode(|name| std::env::var(name).ok())
}
/// [`using_api_key`] over `env`, so a test needs no process environment.
fn api_key_mode(env: impl Fn(&str) -> Option<String>) -> bool {
env("HIVE_USE_API_KEY").is_some_and(|v| v == "1")
|| ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"]
.into_iter()
.any(|name| env(name).is_some_and(|v| !v.trim().is_empty()))
} }
/// Baseline for [`has_fresh_credentials`] when the caller has no specific /// Baseline for [`has_fresh_credentials`] when the caller has no specific
@ -306,7 +317,29 @@ mod tests {
use std::fs; use std::fs;
use std::time::{Duration, SystemTime}; use std::time::{Duration, SystemTime};
use super::{NO_PRIOR_FAILURE, has_fresh_credentials, has_session}; use super::{NO_PRIOR_FAILURE, api_key_mode, has_fresh_credentials, has_session};
fn mode(vars: &[(&str, &str)]) -> bool {
api_key_mode(|name| {
vars.iter()
.find(|(n, _)| *n == name)
.map(|(_, v)| (*v).to_owned())
})
}
#[test]
fn a_key_in_the_environment_or_the_flag_makes_an_api_key_agent() {
assert!(!mode(&[]));
assert!(mode(&[("HIVE_USE_API_KEY", "1")]));
assert!(mode(&[("ANTHROPIC_API_KEY", "sk-ant-x")]));
assert!(mode(&[("ANTHROPIC_AUTH_TOKEN", "t")]));
// The control: neither an off flag nor an empty key counts.
assert!(!mode(&[("HIVE_USE_API_KEY", "0")]));
assert!(!mode(&[
("ANTHROPIC_API_KEY", " "),
("ANTHROPIC_AUTH_TOKEN", "")
]));
}
/// Test-only shorthand: most cases don't exercise the unreadable-mtime /// Test-only shorthand: most cases don't exercise the unreadable-mtime
/// fallback, so they don't care about its baseline. /// fallback, so they don't care about its baseline.

View file

@ -161,6 +161,12 @@ in
option changes what the harness believes about its own login state, option changes what the harness believes about its own login state,
the other actually supplies the credentials `claude` reads. Neither the other actually supplies the credentials `claude` reads. Neither
is useful alone. is useful alone.
An agent that stores an API key in the swarm secret store (the swarm UI's
claude login section) needs neither: the harness also counts it as
API-billed when its environment holds `ANTHROPIC_API_KEY` or
`ANTHROPIC_AUTH_TOKEN`, so it tries instead of waiting for a login. This
option stays the override for an agent whose key comes another way.
''; '';
}; };
@ -200,13 +206,13 @@ in
before creating the file, or a fresh host rebuild before state is before creating the file, or a fresh host rebuild before state is
restored — makes systemd skip it rather than refuse to start the restored — makes systemd skip it rather than refuse to start the
harness. See `services.hyperhive.agent.useApiKey`'s doc for the option this one is harness. See `services.hyperhive.agent.useApiKey`'s doc for the option this one is
paired with. The subagent daemon loads the same file on an ACP agent paired with. The subagent daemon loads the same file, so its subagents
and on an agent with `useApiKey` set, so its subagents authenticate authenticate the same way the harness does.
the same way the harness does.
On an agent with a store (`services.hyperhive.agent.bao.addr`) that uses On an agent with a store (`services.hyperhive.agent.bao.addr`),
`useApiKey` or the `acp` runtime, `hive-agent-backend-env.service` also `hive-agent-backend-env.service` also keeps this file's text at
keeps this file's text at `swarm/agents/<agent>/backend-env`, field `env`. `swarm/agents/<agent>/backend-env`, field `env`, and appends the credentials
an operator stores at `swarm/agents/<agent>/backend-secrets`, field `env`.
A leaf nobody has written is created from this file once, with the same A leaf nobody has written is created from this file once, with the same
bytes, and this file is never rewritten or deleted. The harness and the bytes, and this file is never rewritten or deleted. The harness and the
subagent daemon load this file first and the store's copy after it, so subagent daemon load this file first and the store's copy after it, so

View file

@ -3,30 +3,31 @@
# itself into the file the harness and the subagent daemon load as # itself into the file the harness and the subagent daemon load as
# `EnvironmentFile=`. # `EnvironmentFile=`.
# #
# The store holds the file's text at `swarm/agents/<agent>/backend-env`, field # The store holds the configuration at `swarm/agents/<agent>/backend-env` and the
# `env` (`swarm_secret_client::backend_env`). Each run does one of three things: # credentials apart from it at `swarm/agents/<agent>/backend-secrets`, both as
# the text of an env file in field `env` (`swarm_secret_client::backend_env`,
# `::backend_secrets`). An operator can read the first back, never the second.
# Each run does one of these things:
# #
# - the store has a value: it is written to `/run/hive-agent-backend-env/env`; # - the store has a configuration, secrets or both: they are written to
# - the store has none and `backendEnvironmentFile` is a non-empty file: the # `/run/hive-agent-backend-env/env`, the configuration first, so a secret wins
# file's exact bytes are created at the leaf with `-cas=0`, then read back # over a variable of the same name. A harness whose environment then holds
# `ANTHROPIC_API_KEY` bills the API and tries it instead of waiting for a
# Claude login (`hive_agent::login::using_api_key`);
# - the store has no configuration and `backendEnvironmentFile` is a non-empty
# file: its exact bytes are created at the leaf with `-cas=0`, then read back
# and written the same way. A run that loses the race to another writer, or # and written the same way. A run that loses the race to another writer, or
# whose create the store's policy refuses, uses whatever the read-back finds; # whose create the store's policy refuses, uses whatever the read-back finds;
# - neither: nothing is written, which is an agent with no backend file. # - the store has neither: the file is removed, so a credential an operator took
# away stops being loaded at the next start.
# #
# It never rotates a value and never touches `backendEnvironmentFile`. That # It never rotates a value and never touches `backendEnvironmentFile`, which stays
# file stays an `EnvironmentFile=` of its own, listed before the fetched one: # an `EnvironmentFile=` of its own, listed before the fetched one: a later file
# systemd lets a later file override an earlier one, so the store's value wins # overrides an earlier one, so the store wins and the file carries the agent when
# when there is one, and the file carries the agent when the store is down. # the store is down. The create grant cannot constrain content, so the agent's own
# # process can create an empty leaf with any text; that is no wider than the file
# The leaf's create grant cannot constrain content, so while the leaf is empty # it already owns (`heal_own_dir` in `./user.nix` re-owns the harness dir at boot).
# the agent's own process can also create it with any text, and the store's # The unit runs as root because an operator's file is root-owned `0600`.
# value then wins over the file. That is no wider than the file the agent
# already owns: the container activation's `heal_own_dir` (`./user.nix`)
# re-owns the harness dir to the agent recursively at every boot, so the agent
# already controls the legacy file.
#
# The unit runs as root because the file is root-owned `0600` where an operator
# placed it. Root can still read the agent's `0400` store identity.
{ {
pkgs, pkgs,
lib, lib,
@ -48,13 +49,19 @@ let
# `path::MOUNT`. # `path::MOUNT`.
leaf = "secret/swarm/agents/${agentName}/backend-env"; leaf = "secret/swarm/agents/${agentName}/backend-env";
# The nix half of `swarm_secret_client::backend_secrets::secrets_path` plus `path::MOUNT`.
secretsLeaf = "secret/swarm/agents/${agentName}/backend-secrets";
runtimeDir = unitName; runtimeDir = unitName;
envFile = "/run/${runtimeDir}/env"; envFile = "/run/${runtimeDir}/env";
stagedFile = "/run/${runtimeDir}/env.new"; stagedFile = "/run/${runtimeDir}/env.new";
stagedTextFile = "/run/${runtimeDir}/text.new";
stagedSecretsFile = "/run/${runtimeDir}/secrets.new";
errFile = "/run/${runtimeDir}/bao.err"; errFile = "/run/${runtimeDir}/bao.err";
# An OAuth claude agent has no backend credentials to fetch. # Every agent with a store: an operator may store credentials for any of them,
fetches = cfg.addr != null && (agentCfg.useApiKey || agentCfg.runtime == "acp"); # and an agent with neither configuration nor secrets gets no file.
fetches = cfg.addr != null;
earlier = agentCfg.backendEnvironmentFile; earlier = agentCfg.backendEnvironmentFile;
@ -68,8 +75,8 @@ in
description = '' description = ''
The `EnvironmentFile=` entries that carry this agent's backend The `EnvironmentFile=` entries that carry this agent's backend
environment, in load order: `backendEnvironmentFile` when set, then the environment, in load order: `backendEnvironmentFile` when set, then the
file `${unitName}.service` keeps when the agent has a store and uses an file `${unitName}.service` keeps when the agent has a store. Read-only:
API key. Read-only: the harness and the subagent daemon take it as it is. the harness and the subagent daemon take it as it is.
''; '';
}; };
@ -125,9 +132,11 @@ in
err=${lib.escapeShellArg errFile} err=${lib.escapeShellArg errFile}
staged=${lib.escapeShellArg stagedFile} staged=${lib.escapeShellArg stagedFile}
staged_text=${lib.escapeShellArg stagedTextFile}
staged_secrets=${lib.escapeShellArg stagedSecretsFile}
live=${lib.escapeShellArg envFile} live=${lib.escapeShellArg envFile}
earlier=${lib.escapeShellArg (if earlier == null then "" else earlier)} earlier=${lib.escapeShellArg (if earlier == null then "" else earlier)}
trap 'rm -f "$err" "$staged"' EXIT trap 'rm -f "$err" "$staged" "$staged_text" "$staged_secrets"' EXIT
# Bounded, so a store that drops packets cannot hold the unit past its # Bounded, so a store that drops packets cannot hold the unit past its
# start timeout. # start timeout.
@ -140,51 +149,70 @@ in
fi fi
export BAO_TOKEN export BAO_TOKEN
# Sets READ to have, missing or unusable, and leaves the value in # Sets READ to have, missing or unusable for the leaf at $1, and leaves
# $staged. `kv get` exits 2 with "No value found at <path>" for a leaf # its field $2 in the file $3. `kv get` exits 2 with "No value found at
# nobody wrote, and 2 again for a refused read, so the message tells # <path>" for a leaf nobody wrote, and 2 again for a refused read, so
# them apart. The value goes from the store's answer into a file and # the message tells them apart. The value goes from the store's answer
# is never in a variable or an argument. # into a file and is never in a variable or an argument.
read_leaf() { read_leaf() {
rm -f "$staged" rm -f "$3"
if store kv get -field=env ${lib.escapeShellArg leaf} >"$staged" 2>"$err"; then if store kv get -field="$2" "$1" >"$3" 2>"$err"; then
if [ -s "$staged" ]; then READ=have; else READ=unusable; fi if [ -s "$3" ]; then READ=have; else READ=unusable; fi
elif grep -q '^No value found at ' "$err"; then elif grep -q '^No value found at ' "$err"; then
READ=missing READ=missing
elif grep -q '^Field "env" not present' "$err"; then elif grep -q "^Field \"$2\" not present" "$err"; then
READ=unusable READ=unusable
else else
echo "could not read ${leaf}:" >&2 echo "could not read $1:" >&2
cat "$err" >&2 cat "$err" >&2
exit 1 exit 1
fi fi
} }
read_leaf read_leaf ${lib.escapeShellArg leaf} env "$staged_text"
if [ "$READ" = missing ]; then if [ "$READ" = missing ] && [ -n "$earlier" ] && [ -s "$earlier" ]; then
if [ -n "$earlier" ] && [ -s "$earlier" ]; then echo "${leaf} holds nothing; creating it from $earlier."
echo "${leaf} holds nothing; creating it from $earlier." if ! store kv put -cas=0 ${lib.escapeShellArg leaf} env=@"$earlier" >/dev/null 2>"$err"; then
if ! store kv put -cas=0 ${lib.escapeShellArg leaf} env=@"$earlier" >/dev/null 2>"$err"; then echo "could not create ${leaf}; reading it back in case another run did:" >&2
echo "could not create ${leaf}; reading it back in case another run did:" >&2 cat "$err" >&2
cat "$err" >&2
fi
read_leaf
else
echo "${leaf} holds nothing and there is no file to create it from."
exit 0
fi fi
read_leaf ${lib.escapeShellArg leaf} env "$staged_text"
fi fi
if [ "$READ" != have ]; then TEXT=$READ
echo "${leaf} holds no usable env; the file in place, if any, is used." >&2 read_leaf ${lib.escapeShellArg secretsLeaf} env "$staged_secrets"
SECRETS=$READ
if [ "$TEXT" = unusable ] || [ "$SECRETS" = unusable ]; then
echo "${leaf} or ${secretsLeaf} holds no usable value; the file in place, if any, is used." >&2
exit 0
fi
if [ "$TEXT" != have ] && [ "$SECRETS" != have ]; then
# Both were deleted, or never written: nothing the store holds may
# outlive its removal, or an operator who takes the key away would
# still see the agent bill the API.
rm -f "$live"
echo "${leaf} and ${secretsLeaf} hold nothing and there is no file to create them from."
exit 0 exit 0
fi fi
# The configuration first and the secrets after it, so a secret wins when
# both name a variable, as a later file does over an earlier one.
{
if [ "$TEXT" = have ]; then cat "$staged_text"; fi
if [ "$SECRETS" = have ]; then
if [ "$TEXT" = have ] && [ "$(tail -c1 "$staged_text" | od -An -tx1 | tr -d ' \n')" != 0a ]; then
echo
fi
cat "$staged_secrets"
fi
} >"$staged"
if cmp -s "$staged" "$live"; then if cmp -s "$staged" "$live"; then
echo "this agent's backend environment at ${leaf} is unchanged." echo "this agent's backend environment at ${leaf} and ${secretsLeaf} is unchanged."
exit 0 exit 0
fi fi
mv -f "$staged" "$live" mv -f "$staged" "$live"
echo "fetched this agent's backend environment from ${leaf}." echo "fetched this agent's backend environment from ${leaf} and ${secretsLeaf}."
''; '';
}; };

View file

@ -454,14 +454,19 @@ in
// //
lib.optionalAttrs lib.optionalAttrs
( (
(config.services.hyperhive.agent.runtime == "acp" || config.services.hyperhive.agent.useApiKey) (
config.services.hyperhive.agent.runtime == "acp"
|| config.services.hyperhive.agent.useApiKey
|| config.services.hyperhive.agent.bao.addr != null
)
&& config.services.hyperhive.agent.backendEnvironment.environmentFiles != [ ] && config.services.hyperhive.agent.backendEnvironment.environmentFiles != [ ]
) )
{ {
# A subagent authenticates with the same credentials as the # A subagent authenticates with the same credentials as the
# harness: an ACP subagent to its provider, a claude subagent of # harness: an ACP subagent to its provider, a claude subagent of
# an api-key agent with `ANTHROPIC_API_KEY`, as it has no OAuth # an api-key agent with `ANTHROPIC_API_KEY`, as it has no OAuth
# session to fall back on. # session to fall back on. An agent with a store may have a key
# an operator stored there, which the fetched file carries.
EnvironmentFile = config.services.hyperhive.agent.backendEnvironment.environmentFiles; EnvironmentFile = config.services.hyperhive.agent.backendEnvironment.environmentFiles;
}; };
}; };

View file

@ -531,6 +531,10 @@ let
capabilities = ["delete"] capabilities = ["delete"]
} }
path "${credentialMountPath}/metadata/swarm/agents/+/backend-secrets" {
capabilities = ["delete"]
}
path "${credentialMountPath}/data/swarm/hives/+/forge/token" { path "${credentialMountPath}/data/swarm/hives/+/forge/token" {
capabilities = ["create", "read", "update"] capabilities = ["create", "read", "update"]
} }

View file

@ -183,7 +183,7 @@ let
{ {
# The case above is the presence control: the same lookup finds the # The case above is the presence control: the same lookup finds the
# fetched file where it is loaded. # fetched file where it is loaded.
name = "an agent with no store, or a claude agent on OAuth, loads no fetched backend file"; name = "an agent with no store loads no fetched backend file, and every agent with one does";
ok = ok =
let let
fetched = fetched =
@ -195,8 +195,8 @@ let
!(fetched claudeApiKey) !(fetched claudeApiKey)
&& !(fetched acp) && !(fetched acp)
&& !(fetched opencode) && !(fetched opencode)
&& !(fetched claudeBao) && fetched claudeBao
&& !(claudeBao.systemd.services ? hive-agent-backend-env) && claudeBao.systemd.services ? hive-agent-backend-env
&& !(claudeApiKey.systemd.services ? hive-agent-backend-env) && !(claudeApiKey.systemd.services ? hive-agent-backend-env)
&& claudeApiKeyBao.systemd.services ? hive-agent-backend-env && claudeApiKeyBao.systemd.services ? hive-agent-backend-env
&& claudeApiKeyBao.systemd.timers ? hive-agent-backend-env; && claudeApiKeyBao.systemd.timers ? hive-agent-backend-env;
@ -228,7 +228,8 @@ let
let let
s = claudeApiKeyBao.systemd.services.hive-agent-backend-env.script; s = claudeApiKeyBao.systemd.services.hive-agent-backend-env.script;
in in
lib.hasInfix "kv get -field=env secret/swarm/agents/a1/backend-env" s lib.hasInfix "read_leaf secret/swarm/agents/a1/backend-env env" s
&& lib.hasInfix "read_leaf secret/swarm/agents/a1/backend-secrets env" s
&& lib.hasInfix "kv put -cas=0 secret/swarm/agents/a1/backend-env env=@\"$earlier\"" s && lib.hasInfix "kv put -cas=0 secret/swarm/agents/a1/backend-env env=@\"$earlier\"" s
&& lib.hasInfix "earlier=${backendEnv}" s && lib.hasInfix "earlier=${backendEnv}" s
&& !(lib.hasInfix "kv put secret" s) && !(lib.hasInfix "kv put secret" s)

View file

@ -2553,7 +2553,7 @@ let
lib.hasInfix "path \"secret/metadata/swarm/agents/+/matrix/\" {\n capabilities = [\"list\"]\n}" s lib.hasInfix "path \"secret/metadata/swarm/agents/+/matrix/\" {\n capabilities = [\"list\"]\n}" s
&& lib.hasInfix "path \"secret/metadata/swarm/agents/+/forge/\" {\n capabilities = [\"list\"]\n}" s && lib.hasInfix "path \"secret/metadata/swarm/agents/+/forge/\" {\n capabilities = [\"list\"]\n}" s
&& lib.hasInfix "path \"secret/metadata/swarm/agents/+/gitlab/\" {\n capabilities = [\"list\"]\n}" s && lib.hasInfix "path \"secret/metadata/swarm/agents/+/gitlab/\" {\n capabilities = [\"list\"]\n}" s
&& stanzas == 10; && stanzas == 11;
} }
{ {
# `linked_accounts` deletes one matrix account, forge account, GitLab # `linked_accounts` deletes one matrix account, forge account, GitLab
@ -2574,7 +2574,8 @@ let
&& lib.hasInfix "path \"secret/metadata/swarm/agents/+/forge/+\" {\n capabilities = [\"delete\"]\n}" s && lib.hasInfix "path \"secret/metadata/swarm/agents/+/forge/+\" {\n capabilities = [\"delete\"]\n}" s
&& lib.hasInfix "path \"secret/metadata/swarm/agents/+/gitlab/+\" {\n capabilities = [\"delete\"]\n}" s && lib.hasInfix "path \"secret/metadata/swarm/agents/+/gitlab/+\" {\n capabilities = [\"delete\"]\n}" s
&& lib.hasInfix "path \"secret/metadata/swarm/agents/+/github-token\" {\n capabilities = [\"delete\"]\n}" s && lib.hasInfix "path \"secret/metadata/swarm/agents/+/github-token\" {\n capabilities = [\"delete\"]\n}" s
&& lib.hasInfix "path \"secret/metadata/swarm/agents/+/backend-env\" {\n capabilities = [\"delete\"]\n}" s; && lib.hasInfix "path \"secret/metadata/swarm/agents/+/backend-env\" {\n capabilities = [\"delete\"]\n}" s
&& lib.hasInfix "path \"secret/metadata/swarm/agents/+/backend-secrets\" {\n capabilities = [\"delete\"]\n}" s;
} }
{ {
# `forge::hive_cutoff` deletes the token secret of a hive that left the # `forge::hive_cutoff` deletes the token secret of a hive that left the

View file

@ -26,10 +26,13 @@ case "$1 $2" in
} }
;;& ;;&
"kv get") "kv get")
[ "$3" = -field=env ] || { case "$3" in
echo "fake bao: get without -field=env: $*" >&2 -field=env | -field=key) ;;
exit 95 *)
} echo "fake bao: get without -field=env or -field=key: $*" >&2
exit 95
;;
esac
leaf=$FAKE_BAO_KV/$(printf '%s' "$4" | tr / _) leaf=$FAKE_BAO_KV/$(printf '%s' "$4" | tr / _)
[ -z "${FAKE_BAO_DENY_READ-}" ] || { [ -z "${FAKE_BAO_DENY_READ-}" ] || {
printf 'Error reading %s: Error making API request.\n\nURL: GET https://bao.t.local:8200/v1/%s\nCode: 403. Errors:\n\n* 1 error occurred:\n\t* permission denied\n' "$4" "$4" >&2 printf 'Error reading %s: Error making API request.\n\nURL: GET https://bao.t.local:8200/v1/%s\nCode: 403. Errors:\n\n* 1 error occurred:\n\t* permission denied\n' "$4" "$4" >&2
@ -46,7 +49,7 @@ case "$1 $2" in
exit 2 exit 2
fi fi
if [ "$(cat "$leaf.field" 2>/dev/null)" = other ]; then if [ "$(cat "$leaf.field" 2>/dev/null)" = other ]; then
echo 'Field "env" not present in secret' >&2 echo "Field \"${3#-field=}\" not present in secret" >&2
exit 1 exit 1
fi fi
cat "$leaf" cat "$leaf"

View file

@ -13,8 +13,10 @@ fail() {
} }
leaf=secret/swarm/agents/a1/backend-env leaf=secret/swarm/agents/a1/backend-env
secrets_leaf=secret/swarm/agents/a1/backend-secrets
login_call="login -method=cert -token-only" login_call="login -method=cert -token-only"
get_call="kv get -field=env $leaf" get_call="kv get -field=env $leaf"
secrets_call="kv get -field=env $secrets_leaf"
# setup <description> # setup <description>
setup() { setup() {
@ -43,6 +45,7 @@ setup() {
deny_write= deny_write=
race= race=
stored=$kv/$(printf '%s' "$leaf" | tr / _) stored=$kv/$(printf '%s' "$leaf" | tr / _)
stored_secrets=$kv/$(printf '%s' "$secrets_leaf" | tr / _)
} }
go() { go() {
@ -124,6 +127,11 @@ expect_leaf() {
expect_same "$stored" "$1" expect_same "$stored" "$1"
} }
# A secrets leaf holding <text> before the run.
put_secrets() {
printf '%s' "$1" >"$stored_secrets"
}
file_text=$'ANTHROPIC_API_KEY=k-file\nANTHROPIC_BASE_URL=http://x\n' file_text=$'ANTHROPIC_API_KEY=k-file\nANTHROPIC_BASE_URL=http://x\n'
setup "no store identity delivered" setup "no store identity delivered"
@ -139,7 +147,7 @@ setup "a store holding nothing is seeded from the file, bytes unchanged, and the
put_earlier "$file_text" put_earlier "$file_text"
go go
expect_rc 0 expect_rc 0
expect_calls "$login_call" "$get_call" "kv put -cas=0 $leaf env=@$earlier" "$get_call" expect_calls "$login_call" "$get_call" "kv put -cas=0 $leaf env=@$earlier" "$get_call" "$secrets_call"
expect_leaf "$file_text" expect_leaf "$file_text"
expect_same "$rt/env" "$file_text" expect_same "$rt/env" "$file_text"
expect_earlier_untouched "$file_text" expect_earlier_untouched "$file_text"
@ -160,7 +168,7 @@ put_earlier "$file_text"
put_leaf $'ANTHROPIC_API_KEY=k-bao\n' put_leaf $'ANTHROPIC_API_KEY=k-bao\n'
go go
expect_rc 0 expect_rc 0
expect_calls "$login_call" "$get_call" expect_calls "$login_call" "$get_call" "$secrets_call"
expect_leaf $'ANTHROPIC_API_KEY=k-bao\n' expect_leaf $'ANTHROPIC_API_KEY=k-bao\n'
expect_same "$rt/env" $'ANTHROPIC_API_KEY=k-bao\n' expect_same "$rt/env" $'ANTHROPIC_API_KEY=k-bao\n'
expect_earlier_untouched "$file_text" expect_earlier_untouched "$file_text"
@ -189,8 +197,8 @@ expect_no_file "$rt/env.new"
setup "no file and nothing in the store writes nothing" setup "no file and nothing in the store writes nothing"
go go
expect_rc 0 expect_rc 0
expect_out "no file to create it from" expect_out "no file to create them from"
expect_calls "$login_call" "$get_call" expect_calls "$login_call" "$get_call" "$secrets_call"
expect_no_file "$rt/env" expect_no_file "$rt/env"
expect_no_file "$stored" expect_no_file "$stored"
@ -198,16 +206,17 @@ setup "an empty file is never stored"
put_earlier "" put_earlier ""
go go
expect_rc 0 expect_rc 0
expect_calls "$login_call" "$get_call" expect_calls "$login_call" "$get_call" "$secrets_call"
expect_no_file "$rt/env" expect_no_file "$rt/env"
expect_no_file "$stored" expect_no_file "$stored"
setup "nothing in the store leaves an env fetched earlier alone" # An operator who takes the key away must not see the agent keep loading it.
setup "nothing in the store removes an env fetched earlier"
printf kept >"$rt/env" printf kept >"$rt/env"
chmod 0600 "$rt/env" chmod 0600 "$rt/env"
go go
expect_rc 0 expect_rc 0
expect_same "$rt/env" kept expect_no_file "$rt/env"
setup "a store that refuses the login with a file in place changes nothing and fails the unit" setup "a store that refuses the login with a file in place changes nothing and fails the unit"
put_earlier "$file_text" put_earlier "$file_text"
@ -226,7 +235,7 @@ put_earlier "$file_text"
race=$'ANTHROPIC_API_KEY=k-winner\n' race=$'ANTHROPIC_API_KEY=k-winner\n'
go go
expect_rc 0 expect_rc 0
expect_calls "$login_call" "$get_call" "kv put -cas=0 $leaf env=@$earlier" "$get_call" expect_calls "$login_call" "$get_call" "kv put -cas=0 $leaf env=@$earlier" "$get_call" "$secrets_call"
expect_err "could not create $leaf" expect_err "could not create $leaf"
expect_leaf $'ANTHROPIC_API_KEY=k-winner\n' expect_leaf $'ANTHROPIC_API_KEY=k-winner\n'
expect_same "$rt/env" $'ANTHROPIC_API_KEY=k-winner\n' expect_same "$rt/env" $'ANTHROPIC_API_KEY=k-winner\n'
@ -237,9 +246,9 @@ put_earlier "$file_text"
deny_write=1 deny_write=1
go go
expect_rc 0 expect_rc 0
expect_calls "$login_call" "$get_call" "kv put -cas=0 $leaf env=@$earlier" "$get_call" expect_calls "$login_call" "$get_call" "kv put -cas=0 $leaf env=@$earlier" "$get_call" "$secrets_call"
expect_err "permission denied" expect_err "permission denied"
expect_err "holds no usable env" expect_out "hold nothing"
expect_no_file "$rt/env" expect_no_file "$rt/env"
expect_no_file "$stored" expect_no_file "$stored"
expect_earlier_untouched "$file_text" expect_earlier_untouched "$file_text"
@ -249,8 +258,8 @@ put_earlier "$file_text"
put_leaf "" put_leaf ""
go go
expect_rc 0 expect_rc 0
expect_calls "$login_call" "$get_call" expect_calls "$login_call" "$get_call" "$secrets_call"
expect_err "holds no usable env" expect_err "holds no usable value"
expect_leaf "" expect_leaf ""
expect_no_file "$rt/env" expect_no_file "$rt/env"
@ -260,7 +269,7 @@ put_leaf "x"
printf other >"$stored.field" printf other >"$stored.field"
go go
expect_rc 0 expect_rc 0
expect_calls "$login_call" "$get_call" expect_calls "$login_call" "$get_call" "$secrets_call"
expect_leaf "x" expect_leaf "x"
expect_no_file "$rt/env" expect_no_file "$rt/env"
@ -275,6 +284,49 @@ expect_calls "$login_call" "$get_call"
expect_no_file "$rt/env" expect_no_file "$rt/env"
expect_earlier_untouched "$file_text" expect_earlier_untouched "$file_text"
setup "secrets alone are written as they are"
put_secrets $'ANTHROPIC_API_KEY=sk-ant-key\n'
go
expect_rc 0
expect_calls "$login_call" "$get_call" "$secrets_call"
expect_same "$rt/env" $'ANTHROPIC_API_KEY=sk-ant-key\n'
if [ "$(stat -c %a "$rt/env")" != 600 ]; then fail "env is mode $(stat -c %a "$rt/env"), expected 600"; fi
expect_no_file "$rt/env.new"
expect_no_file "$rt/secrets.new"
expect_no_file "$rt/text.new"
setup "the secrets follow the configuration, so they win over a variable it names"
put_leaf $'ANTHROPIC_BASE_URL=http://x\nANTHROPIC_API_KEY=from-text\n'
put_secrets $'ANTHROPIC_API_KEY=sk-ant-key\n'
go
expect_rc 0
expect_same "$rt/env" $'ANTHROPIC_BASE_URL=http://x\nANTHROPIC_API_KEY=from-text\nANTHROPIC_API_KEY=sk-ant-key\n'
setup "a configuration with no final newline still gets the secrets on a line of their own"
put_leaf "ANTHROPIC_BASE_URL=http://x"
put_secrets $'ANTHROPIC_API_KEY=sk-ant-key\n'
go
expect_rc 0
expect_same "$rt/env" $'ANTHROPIC_BASE_URL=http://x\nANTHROPIC_API_KEY=sk-ant-key\n'
setup "secrets an operator removed leave the configuration alone in the file"
put_leaf $'ANTHROPIC_BASE_URL=http://x\n'
printf 'ANTHROPIC_BASE_URL=http://x\nANTHROPIC_API_KEY=old\n' >"$rt/env"
chmod 0600 "$rt/env"
go
expect_rc 0
expect_same "$rt/env" $'ANTHROPIC_BASE_URL=http://x\n'
setup "a secrets leaf without the env field changes nothing"
put_secrets "x"
printf other >"$stored_secrets.field"
printf kept >"$rt/env"
chmod 0600 "$rt/env"
go
expect_rc 0
expect_err "holds no usable value"
expect_same "$rt/env" kept
# `UMask=0077` makes every file the script creates 0600; a stale leftover of a # `UMask=0077` makes every file the script creates 0600; a stale leftover of a
# stopped run must not block the next. # stopped run must not block the next.
setup "leftovers of a stopped run do not block the fetch" setup "leftovers of a stopped run do not block the fetch"

View file

@ -7,11 +7,15 @@
//! whatever the leaf holds, including a value the agent wrote itself while the //! whatever the leaf holds, including a value the agent wrote itself while the
//! leaf was empty, and the store's value wins over the agent's //! leaf was empty, and the store's value wins over the agent's
//! `backendEnvironmentFile`. //! `backendEnvironmentFile`.
//!
//! This is the agent's *configuration* (the provider's base URL, a model name),
//! and it reads back as stored. Credentials belong in the write-only
//! [`crate::backend_secrets`] leaf, which the agent's unit loads after this one.
use axum::Json; use axum::Json;
use axum::extract::State; use axum::extract::State;
use axum::http::StatusCode; use axum::http::StatusCode;
use serde::Deserialize; use serde::{Deserialize, Serialize};
use swarm_secret_client::backend_env::{self, BackendEnv}; use swarm_secret_client::backend_env::{self, BackendEnv};
use utoipa::ToSchema; use utoipa::ToSchema;
@ -33,6 +37,55 @@ pub struct PutBackendEnvRequest {
env: String, env: String,
} }
/// An agent's stored backend environment.
#[derive(Serialize, ToSchema)]
pub struct BackendEnvText {
/// The file text, as stored.
env: String,
}
/// Read an agent's backend environment as stored.
#[utoipa::path(
get,
path = "/api/hives/{hive}/agents/{agent}/backend-env",
params(
("hive" = String, Path, description = "hive the agent runs on"),
("agent" = String, Path, description = "agent the environment belongs to"),
),
responses(
(status = 200, description = "the stored text", body = BackendEnvText),
(status = 400, description = "the agent is not an identifier, or the hive is not in this swarm (problem+json)", body = String),
(status = 404, description = "no backend environment is stored (problem+json)", body = String),
(status = 500, description = "the store could not be read (problem+json)", body = String),
),
tag = "agents"
)]
pub async fn get_backend_env(
State(state): State<AppState>,
axum::extract::Path((hive, agent)): axum::extract::Path<(String, String)>,
) -> Result<Json<BackendEnvText>, problem_details::ProblemDetails> {
let hive = swarm_hive(&state, &hive).map_err(|(s, d)| error_problem(s, &d))?;
let agent = hive_types::Ident::parse(&agent)
.map_err(|reason| error_problem(StatusCode::BAD_REQUEST, reason))?
.into_string();
let path = backend_env::env_path(&agent)
.map_err(|e| error_problem(StatusCode::BAD_REQUEST, &e.to_string()))?;
let store = state.accounts.open().await.map_err(|e| {
tracing::warn!(error = %e, "connecting to the swarm secret store failed");
error_problem(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string())
})?;
let stored = store
.read_optional::<BackendEnv>(&path)
.await
.map_err(|e| {
tracing::warn!(%hive, %agent, error = %e, "reading the backend env failed");
error_problem(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string())
})?;
stored
.map(|b| Json(BackendEnvText { env: b.env }))
.ok_or_else(|| error_problem(StatusCode::NOT_FOUND, "no backend environment is stored"))
}
/// Store an agent's backend environment, replacing any stored one. /// Store an agent's backend environment, replacing any stored one.
#[utoipa::path( #[utoipa::path(
put, put,
@ -84,10 +137,12 @@ pub async fn put_backend_env(
/// The text as it is stored, or why it cannot be. /// The text as it is stored, or why it cannot be.
/// ///
/// Shared with [`crate::backend_secrets`], whose text has the same shape.
///
/// systemd skips a line it cannot parse and goes on, so a typo would load as /// systemd skips a line it cannot parse and goes on, so a typo would load as
/// a missing key. A quote that is not closed would swallow the lines after it /// a missing key. A quote that is not closed would swallow the lines after it
/// into one value. The reasons name a line number and never its text. /// into one value. The reasons name a line number and never its text.
fn validated(text: &str) -> Result<String, String> { pub(crate) fn validated(text: &str) -> Result<String, String> {
let text = text.trim(); let text = text.trim();
if text.is_empty() { if text.is_empty() {
return Err("env is required".to_owned()); return Err("env is required".to_owned());
@ -132,7 +187,7 @@ fn valid_line(line: &str) -> bool {
} }
#[cfg(test)] #[cfg(test)]
mod tests { pub(crate) mod tests {
use std::sync::Arc; use std::sync::Arc;
use axum::http::StatusCode; use axum::http::StatusCode;
@ -145,7 +200,7 @@ mod tests {
const SECRET: &str = "sk-live-0123"; const SECRET: &str = "sk-live-0123";
/// Bare-minimum `AppState`, as `github_account`'s tests build it. /// Bare-minimum `AppState`, as `github_account`'s tests build it.
fn state(store: &Arc<FakeStore>) -> crate::routes::AppState { pub(crate) fn state(store: &Arc<FakeStore>) -> crate::routes::AppState {
crate::routes::AppState { crate::routes::AppState {
hives: std::sync::Arc::new(vec![crate::routes::hives::HiveEntry { hives: std::sync::Arc::new(vec![crate::routes::hives::HiveEntry {
name: "pr1ma".to_owned(), name: "pr1ma".to_owned(),
@ -295,4 +350,23 @@ mod tests {
assert_eq!(problem.status, Some(StatusCode::INTERNAL_SERVER_ERROR)); assert_eq!(problem.status, Some(StatusCode::INTERNAL_SERVER_ERROR));
assert!(!format!("{problem:?}").contains(SECRET), "{problem:?}"); assert!(!format!("{problem:?}").contains(SECRET), "{problem:?}");
} }
#[tokio::test]
async fn the_stored_text_reads_back_as_stored_and_nothing_stored_is_a_404() {
let store = Arc::default();
let get = |store: &Arc<FakeStore>| {
super::get_backend_env(
axum::extract::State(state(store)),
axum::extract::Path(("pr1ma".to_owned(), "atlas".to_owned())),
)
};
let problem = get(&store).await.err().expect("nothing stored");
assert_eq!(problem.status, Some(StatusCode::NOT_FOUND));
put(&store, "atlas", "ANTHROPIC_BASE_URL=https://x.example")
.await
.expect("saved");
let read = get(&store).await.expect("read");
assert_eq!(read.0.env, "ANTHROPIC_BASE_URL=https://x.example\n");
}
} }

View file

@ -0,0 +1,224 @@
//! An agent's backend secrets: an operator hands us the text of a systemd
//! `EnvironmentFile` that holds credentials (`ANTHROPIC_API_KEY=…`), and we put
//! it in a leaf of its own in the swarm's secret store, apart from the
//! configuration in [`crate::backend_env`].
//!
//! The agent end is `nix/agent-modules/backend-env.nix`, which reads both under
//! the agent's own certificate into the file its harness loads as
//! `EnvironmentFile=`, the configuration first and these secrets after it. An
//! agent whose environment then holds `ANTHROPIC_API_KEY` bills the API and
//! tries it instead of waiting for a Claude login. No route hands the text
//! back; [`get_backend_secrets`] says only whether the leaf holds any.
use axum::Json;
use axum::extract::State;
use axum::http::StatusCode;
use serde::{Deserialize, Serialize};
use swarm_secret_client::backend_secrets::{self, BackendSecrets};
use utoipa::ToSchema;
use super::linked_accounts::AccountStore;
use crate::backend_env::validated;
use crate::routes::agents::swarm_hive;
use crate::routes::{AppState, error_problem};
/// The secrets to store for one agent.
///
/// No `Debug` derive: this carries live credentials.
#[derive(Deserialize, ToSchema)]
pub struct PutBackendSecretsRequest {
/// The file text, `NAME=VALUE` per line, as for the backend environment.
/// Never logged, and never returned by any route.
env: String,
}
/// Whether an agent has backend secrets stored.
#[derive(Debug, Serialize, ToSchema)]
pub struct BackendSecretsStatus {
/// `true` when the leaf holds text; the text is never returned.
stored: bool,
}
/// Whether an agent has backend secrets stored.
#[utoipa::path(
get,
path = "/api/hives/{hive}/agents/{agent}/backend-secrets",
params(
("hive" = String, Path, description = "hive the agent runs on"),
("agent" = String, Path, description = "agent the secrets belong to"),
),
responses(
(status = 200, description = "whether secrets are stored; never the secrets", body = BackendSecretsStatus),
(status = 400, description = "the agent is not an identifier, or the hive is not in this swarm (problem+json)", body = String),
(status = 500, description = "the store could not be read (problem+json)", body = String),
),
tag = "agents"
)]
pub async fn get_backend_secrets(
State(state): State<AppState>,
axum::extract::Path((hive, agent)): axum::extract::Path<(String, String)>,
) -> Result<Json<BackendSecretsStatus>, problem_details::ProblemDetails> {
let hive = swarm_hive(&state, &hive).map_err(|(s, d)| error_problem(s, &d))?;
let agent = hive_types::Ident::parse(&agent)
.map_err(|reason| error_problem(StatusCode::BAD_REQUEST, reason))?
.into_string();
let path = backend_secrets::secrets_path(&agent)
.map_err(|e| error_problem(StatusCode::BAD_REQUEST, &e.to_string()))?;
let store = state.accounts.open().await.map_err(|e| {
tracing::warn!(error = %e, "connecting to the swarm secret store failed");
error_problem(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string())
})?;
let stored = store
.read_optional::<BackendSecrets>(&path)
.await
.map_err(|e| {
tracing::warn!(%hive, %agent, error = %e, "reading the backend secrets failed");
error_problem(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string())
})?;
Ok(Json(BackendSecretsStatus {
stored: stored.is_some_and(|s| !s.env.trim().is_empty()),
}))
}
/// Store an agent's backend secrets, replacing any stored ones.
#[utoipa::path(
put,
path = "/api/hives/{hive}/agents/{agent}/backend-secrets",
params(
("hive" = String, Path, description = "hive the agent runs on"),
("agent" = String, Path, description = "agent the secrets belong to"),
),
request_body = PutBackendSecretsRequest,
responses(
(status = 204, description = "stored"),
(status = 400, description = "the agent is not an identifier, the text is empty, too large or not `NAME=VALUE` lines, or the hive is not in this swarm (problem+json)", body = String),
(status = 500, description = "the store could not be written (problem+json)", body = String),
),
tag = "agents"
)]
pub async fn put_backend_secrets(
State(state): State<AppState>,
axum::extract::Path((hive, agent)): axum::extract::Path<(String, String)>,
Json(req): Json<PutBackendSecretsRequest>,
) -> Result<StatusCode, problem_details::ProblemDetails> {
let hive = swarm_hive(&state, &hive).map_err(|(s, d)| error_problem(s, &d))?;
let agent = hive_types::Ident::parse(&agent)
.map_err(|reason| error_problem(StatusCode::BAD_REQUEST, reason))?
.into_string();
let path = backend_secrets::secrets_path(&agent)
.map_err(|e| error_problem(StatusCode::BAD_REQUEST, &e.to_string()))?;
let stored = BackendSecrets {
env: validated(&req.env).map_err(|e| error_problem(StatusCode::BAD_REQUEST, &e))?,
};
let store = state.accounts.open().await.map_err(|e| {
tracing::warn!(error = %e, "connecting to the swarm secret store failed");
error_problem(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string())
})?;
store.write(&path, &stored).await.map_err(|e| {
// The path names the agent; the value is not in it.
tracing::warn!(%path, error = %e, "storing the backend secrets failed");
error_problem(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string())
})?;
tracing::info!(%hive, %agent, "backend secrets stored");
Ok(StatusCode::NO_CONTENT)
}
#[cfg(test)]
mod tests {
use std::sync::Arc;
use axum::http::StatusCode;
use serde_json::json;
use swarm_secret_client::backend_secrets::BackendSecrets;
use super::super::backend_env::tests::state;
use super::super::linked_accounts::{AccountStore, tests::FakeStore};
use super::PutBackendSecretsRequest;
const SECRET: &str = "sk-ant-live-0123";
async fn put(
store: &Arc<FakeStore>,
agent: &str,
env: &str,
) -> Result<StatusCode, problem_details::ProblemDetails> {
super::put_backend_secrets(
axum::extract::State(state(store)),
axum::extract::Path(("pr1ma".to_owned(), agent.to_owned())),
axum::Json(PutBackendSecretsRequest {
env: env.to_owned(),
}),
)
.await
}
async fn stored(store: &FakeStore, agent: &str) -> Option<String> {
store
.read_optional::<BackendSecrets>(&format!("swarm/agents/{agent}/backend-secrets"))
.await
.expect("store answers")
.map(|s| s.env)
}
#[tokio::test]
async fn secrets_are_stored_under_the_agent_and_replace_earlier_ones() {
let store = Arc::new(FakeStore::default().with(
"swarm/agents/atlas/backend-secrets",
json!({"env": "OLD=1\n"}),
));
let status = put(&store, "atlas", &format!("ANTHROPIC_API_KEY={SECRET}"))
.await
.expect("stored");
assert_eq!(status, StatusCode::NO_CONTENT);
assert_eq!(store.written(), ["swarm/agents/atlas/backend-secrets"]);
assert_eq!(
stored(&store, "atlas").await.as_deref(),
Some("ANTHROPIC_API_KEY=sk-ant-live-0123\n")
);
}
#[tokio::test]
async fn a_bad_agent_or_text_is_refused_before_the_store_and_never_echoed() {
let store = Arc::default();
let leaky = format!("{SECRET}-no-equals");
for (agent, env) in [
("Atlas", "A=1"),
("../x", "A=1"),
("atlas", " "),
("atlas", leaky.as_str()),
] {
let problem = put(&store, agent, env).await.expect_err("refused");
assert_eq!(problem.status, Some(StatusCode::BAD_REQUEST), "{problem:?}");
assert!(!format!("{problem:?}").contains(SECRET), "{problem:?}");
}
assert!(store.written().is_empty());
}
#[tokio::test]
async fn a_store_failure_does_not_echo_the_secrets() {
let store = Arc::new(FakeStore::denying());
let problem = put(&store, "atlas", &format!("ANTHROPIC_API_KEY={SECRET}"))
.await
.expect_err("refused");
assert_eq!(problem.status, Some(StatusCode::INTERNAL_SERVER_ERROR));
assert!(!format!("{problem:?}").contains(SECRET), "{problem:?}");
}
#[tokio::test]
async fn the_status_says_whether_secrets_are_stored_and_never_what_they_are() {
let store = Arc::new(FakeStore::default().with(
"swarm/agents/atlas/backend-secrets",
json!({"env": format!("ANTHROPIC_API_KEY={SECRET}\n")}),
));
for (agent, want) in [("atlas", true), ("red", false)] {
let got = super::get_backend_secrets(
axum::extract::State(state(&store)),
axum::extract::Path(("pr1ma".to_owned(), agent.to_owned())),
)
.await
.expect("answers");
assert_eq!(got.0.stored, want, "{agent}");
assert!(!format!("{got:?}").contains(SECRET));
}
}
}

View file

@ -34,7 +34,9 @@ use axum::extract::State;
use axum::http::StatusCode; use axum::http::StatusCode;
use serde::de::{DeserializeOwned, IgnoredAny}; use serde::de::{DeserializeOwned, IgnoredAny};
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
use swarm_secret_client::{Error, SecretStore, backend_env, forge, github, gitlab, matrix}; use swarm_secret_client::{
Error, SecretStore, backend_env, backend_secrets, forge, github, gitlab, matrix,
};
use utoipa::{IntoParams, ToSchema}; use utoipa::{IntoParams, ToSchema};
use crate::routes::agents::swarm_hive; use crate::routes::agents::swarm_hive;
@ -755,6 +757,48 @@ pub async fn delete_backend_env(
Ok(StatusCode::NO_CONTENT) Ok(StatusCode::NO_CONTENT)
} }
/// Delete an agent's backend secrets from the store, every version of them.
#[utoipa::path(
delete,
path = "/api/hives/{hive}/agents/{agent}/backend-secrets",
params(
("hive" = String, Path, description = "hive the agent runs on"),
("agent" = String, Path, description = "agent the secrets belong to"),
),
responses(
(status = 204, description = "deleted"),
(status = 400, description = "the agent is not an identifier, or the hive is not in this swarm (problem+json)", body = String),
(status = 404, description = "no backend secrets are stored (problem+json)", body = String),
(status = 500, description = "the store could not be read or written (problem+json)", body = String),
),
tag = "agents"
)]
pub async fn delete_backend_secrets(
State(state): State<AppState>,
axum::extract::Path((hive, agent)): axum::extract::Path<(String, String)>,
) -> Result<StatusCode, problem_details::ProblemDetails> {
let hive = swarm_hive(&state, &hive).map_err(|(s, d)| error_problem(s, &d))?;
let agent = hive_types::Ident::parse(&agent)
.map_err(|reason| error_problem(StatusCode::BAD_REQUEST, reason))?
.into_string();
let path = backend_secrets::secrets_path(&agent)
.map_err(|e| error_problem(StatusCode::BAD_REQUEST, &e.to_string()))?;
let store = state.accounts.open().await.map_err(|e| {
tracing::warn!(error = %e, "connecting to the swarm secret store failed");
error_problem(StatusCode::INTERNAL_SERVER_ERROR, &e.to_string())
})?;
remove_plain::<IgnoredAny>(&store, &path)
.await
.map_err(|e| {
tracing::warn!(%hive, %agent, error = ?e, "deleting the backend secrets failed");
e.problem()
})?;
tracing::info!(%hive, %agent, "backend secrets deleted");
Ok(StatusCode::NO_CONTENT)
}
#[cfg(test)] #[cfg(test)]
pub(crate) mod tests { pub(crate) mod tests {
use std::collections::BTreeMap; use std::collections::BTreeMap;
@ -1285,6 +1329,33 @@ pub(crate) mod tests {
assert_eq!(deleted(&store).len(), 1); assert_eq!(deleted(&store).len(), 1);
} }
#[tokio::test]
async fn deleting_backend_secrets_removes_that_agents_leaf_only() {
let store = Arc::new(
FakeStore::default()
.with(
"swarm/agents/atlas/backend-secrets",
json!({"env": "K=1\n"}),
)
.with("swarm/agents/atlas/backend-env", json!({"env": "A=1\n"})),
);
let del = |agent: &'static str| {
super::delete_backend_secrets(
axum::extract::State(state(&store)),
axum::extract::Path(("pr1ma".to_owned(), agent.to_owned())),
)
};
assert_eq!(
del("atlas").await.expect("stored"),
axum::http::StatusCode::NO_CONTENT
);
assert_eq!(deleted(&store), ["swarm/agents/atlas/backend-secrets"]);
let problem = del("red").await.expect_err("none");
assert_eq!(problem.status, Some(axum::http::StatusCode::NOT_FOUND));
let problem = del("../x").await.expect_err("refused");
assert_eq!(problem.status, Some(axum::http::StatusCode::BAD_REQUEST));
}
const CATGIRL: &str = "swarm/agents/atlas/matrix/catgirl"; const CATGIRL: &str = "swarm/agents/atlas/matrix/catgirl";
const CATGIRL_PASSPHRASE: &str = "swarm/agents/atlas/matrix-recovery/catgirl"; const CATGIRL_PASSPHRASE: &str = "swarm/agents/atlas/matrix-recovery/catgirl";

View file

@ -50,6 +50,7 @@ mod attic_copy;
mod auth; mod auth;
mod backend_egress; mod backend_egress;
mod backend_env; mod backend_env;
mod backend_secrets;
mod bash_task; mod bash_task;
mod builder; mod builder;
mod cache_miss; mod cache_miss;

View file

@ -28,12 +28,12 @@ use crate::routes::{self, AppState, agents, config_prs, forge_admin, hives, jobq
use crate::{ use crate::{
agent_commands, agent_control, agent_custom, agent_icon, agent_input, agent_limits, agent_commands, agent_control, agent_custom, agent_icon, agent_input, agent_limits,
agent_login, agent_permissions, agent_renewal, agent_ssh, agent_state_stream, agent_status, agent_login, agent_permissions, agent_renewal, agent_ssh, agent_state_stream, agent_status,
agent_todos, agents_md, alerts, archetypes, auth, backend_env, bash_task, builder, agent_todos, agents_md, alerts, archetypes, auth, backend_env, backend_secrets, bash_task,
claude_login, config_drift, config_pr, egress_allow, egress_deny, forge, forge_account, builder, claude_login, config_drift, config_pr, egress_allow, egress_deny, forge,
github_account, gitlab_account, inference, issue_report, linked_accounts, matrix_account, forge_account, github_account, gitlab_account, inference, issue_report, linked_accounts,
message_stream, notify_flows, notify_router_api, pause_hold, pr_report, pulls, queue_identity, matrix_account, message_stream, notify_flows, notify_router_api, pause_hold, pr_report, pulls,
review_classifier, schedules, ssh_connections, status, subagent_term, term_stream, wanted, queue_identity, review_classifier, schedules, ssh_connections, status, subagent_term,
webhook, term_stream, wanted, webhook,
}; };
/// Where the daemon binds, overridable via `SWARM_CONTROLLER_SOCKET`. /// Where the daemon binds, overridable via `SWARM_CONTROLLER_SOCKET`.
@ -663,9 +663,15 @@ fn linked_account_routes(router: OpenApiRouter<AppState>) -> OpenApiRouter<AppSt
linked_accounts::delete_github_account linked_accounts::delete_github_account
)) ))
.routes(routes!( .routes(routes!(
backend_env::get_backend_env,
backend_env::put_backend_env, backend_env::put_backend_env,
linked_accounts::delete_backend_env linked_accounts::delete_backend_env
)) ))
.routes(routes!(
backend_secrets::get_backend_secrets,
backend_secrets::put_backend_secrets,
linked_accounts::delete_backend_secrets
))
.routes(routes!(linked_accounts::get_linked_accounts)) .routes(routes!(linked_accounts::get_linked_accounts))
.routes(routes!( .routes(routes!(
claude_login::get_claude_login, claude_login::get_claude_login,

View file

@ -0,0 +1,96 @@
//! Where an agent's backend secrets live in the store, apart from the rest of
//! its backend environment.
//!
//! [`crate::backend_env`] holds the configuration an operator may read back
//! (the base URL, a model name). The credentials sit in this leaf, so the
//! controller never has to hand one back: it writes the leaf and says only
//! whether it holds anything. Both objects hold the text of a systemd
//! `EnvironmentFile`. The agent's own `hive-agent-backend-env` unit
//! (`nix/agent-modules/backend-env.nix`) reads both under the agent's
//! certificate and writes one file, the configuration first and the secrets
//! after it, so a variable named in both takes the secret's value.
//!
//! The agent's read stanza ([`crate::policy::render_shared_agent`]) covers the
//! leaf like any other under its prefix. Only the controller writes it.
use serde::{Deserialize, Serialize};
use crate::{
Error,
path::{Kind, principal_prefix},
};
/// The last segment of the path.
pub(crate) const LEAF: &str = "backend-secrets";
/// The path holding `agent`'s backend secrets.
///
/// # Errors
/// [`Error::PathSegment`] when `agent` contains anything but `[A-Za-z0-9_-]`,
/// which is what keeps one agent's name from addressing another agent's secret.
pub fn secrets_path(agent: &str) -> Result<String, Error> {
let prefix = principal_prefix(Kind::Agent, agent)?;
Ok(format!("{prefix}/{LEAF}"))
}
/// What a [`secrets_path`] holds.
///
/// No `Debug` derive: `env` carries live credentials, and a derived `Debug` is
/// one `{:?}` away from a log line.
#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct BackendSecrets {
/// The file text, `NAME=value` per line. `backend-env.nix` reads it with
/// `bao kv get -field=env`, so this name is load-bearing for a reader this
/// crate does not control.
pub env: String,
}
impl std::fmt::Debug for BackendSecrets {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("BackendSecrets")
.field("env", &"<redacted>")
.finish()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_secrets_land_under_the_agent_prefix() {
// Spelled out: `backend-env.nix` spells the same string.
assert_eq!(
secrets_path("atlas").expect("a plain name is legal"),
"swarm/agents/atlas/backend-secrets"
);
}
#[test]
fn a_traversal_in_the_agent_name_is_refused() {
for bad in ["../argus", "a/b", "atlas/../argus", "a.b", ""] {
let e = secrets_path(bad).expect_err("a traversal is not legal");
assert!(matches!(e, Error::PathSegment { kind: "agent", .. }), "{e}");
}
assert!(secrets_path("a-b_C9").is_ok());
}
#[test]
fn the_stored_field_is_env() {
let stored: BackendSecrets =
serde_json::from_str(r#"{"env":"A=b\n"}"#).expect("the documented shape decodes");
assert_eq!(stored.env, "A=b\n");
}
#[test]
fn debug_hides_the_credentials() {
let shown = format!(
"{:?}",
BackendSecrets {
env: "ANTHROPIC_API_KEY=sk-live".to_owned()
}
);
assert!(!shown.contains("sk-live"), "{shown}");
assert!(shown.contains("<redacted>"), "{shown}");
}
}

View file

@ -6,7 +6,7 @@
//! deployment's environment into a logged-in client ([`client`]), and, per kind //! deployment's environment into a logged-in client ([`client`]), and, per kind
//! of secret, the path it lives at together with the fields it holds //! of secret, the path it lives at together with the fields it holds
//! ([`matrix`], [`queue`], [`mtls`], [`forge`], [`github`], [`grafana`], //! ([`matrix`], [`queue`], [`mtls`], [`forge`], [`github`], [`grafana`],
//! [`acp`], [`attic`], [`backend_env`], [`ci`], [`review_classifier`], [`builder`], [`ci_metrics`], //! [`acp`], [`attic`], [`backend_env`], [`backend_secrets`], [`ci`], [`review_classifier`], [`builder`], [`ci_metrics`],
//! [`claude_login`], [`proxy`]). //! [`claude_login`], [`proxy`]).
//! Each of those is a thing the controller and a hive must say identically, so //! Each of those is a thing the controller and a hive must say identically, so
//! it is said once here. //! it is said once here.
@ -33,6 +33,7 @@ pub mod acp;
pub mod archive; pub mod archive;
pub mod attic; pub mod attic;
pub mod backend_env; pub mod backend_env;
pub mod backend_secrets;
pub mod builder; pub mod builder;
pub mod cert; pub mod cert;
#[cfg(feature = "otel")] #[cfg(feature = "otel")]