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
5 changed files with 737 additions and 107 deletions

View file

@ -7,11 +7,15 @@
//! 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
//! `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::extract::State;
use axum::http::StatusCode;
use serde::Deserialize;
use serde::{Deserialize, Serialize};
use swarm_secret_client::backend_env::{self, BackendEnv};
use utoipa::ToSchema;
@ -33,6 +37,55 @@ pub struct PutBackendEnvRequest {
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.
#[utoipa::path(
put,
@ -84,10 +137,12 @@ pub async fn put_backend_env(
/// 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
/// 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.
fn validated(text: &str) -> Result<String, String> {
pub(crate) fn validated(text: &str) -> Result<String, String> {
let text = text.trim();
if text.is_empty() {
return Err("env is required".to_owned());
@ -132,7 +187,7 @@ fn valid_line(line: &str) -> bool {
}
#[cfg(test)]
mod tests {
pub(crate) mod tests {
use std::sync::Arc;
use axum::http::StatusCode;
@ -145,7 +200,7 @@ mod tests {
const SECRET: &str = "sk-live-0123";
/// 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 {
hives: std::sync::Arc::new(vec![crate::routes::hives::HiveEntry {
name: "pr1ma".to_owned(),
@ -295,4 +350,23 @@ mod tests {
assert_eq!(problem.status, Some(StatusCode::INTERNAL_SERVER_ERROR));
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 serde::de::{DeserializeOwned, IgnoredAny};
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 crate::routes::agents::swarm_hive;
@ -755,6 +757,48 @@ pub async fn delete_backend_env(
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)]
pub(crate) mod tests {
use std::collections::BTreeMap;
@ -1285,6 +1329,33 @@ pub(crate) mod tests {
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_PASSPHRASE: &str = "swarm/agents/atlas/matrix-recovery/catgirl";

View file

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

View file

@ -28,12 +28,12 @@ use crate::routes::{self, AppState, agents, config_prs, forge_admin, hives, jobq
use crate::{
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_todos, agents_md, alerts, archetypes, auth, backend_env, bash_task, builder,
claude_login, config_drift, config_pr, egress_allow, egress_deny, forge, forge_account,
github_account, gitlab_account, inference, issue_report, linked_accounts, matrix_account,
message_stream, notify_flows, notify_router_api, pause_hold, pr_report, pulls, queue_identity,
review_classifier, schedules, ssh_connections, status, subagent_term, term_stream, wanted,
webhook,
agent_todos, agents_md, alerts, archetypes, auth, backend_env, backend_secrets, bash_task,
builder, claude_login, config_drift, config_pr, egress_allow, egress_deny, forge,
forge_account, github_account, gitlab_account, inference, issue_report, linked_accounts,
matrix_account, message_stream, notify_flows, notify_router_api, pause_hold, pr_report, pulls,
queue_identity, review_classifier, schedules, ssh_connections, status, subagent_term,
term_stream, wanted, webhook,
};
/// 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
))
.routes(routes!(
backend_env::get_backend_env,
backend_env::put_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!(
claude_login::get_claude_login,