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

View file

@ -161,6 +161,12 @@ in
option changes what the harness believes about its own login state,
the other actually supplies the credentials `claude` reads. Neither
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
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
paired with. The subagent daemon loads the same file on an ACP agent
and on an agent with `useApiKey` set, so its subagents authenticate
the same way the harness does.
paired with. The subagent daemon loads the same file, so its subagents
authenticate the same way the harness does.
On an agent with a store (`services.hyperhive.agent.bao.addr`) that uses
`useApiKey` or the `acp` runtime, `hive-agent-backend-env.service` also
keeps this file's text at `swarm/agents/<agent>/backend-env`, field `env`.
On an agent with a store (`services.hyperhive.agent.bao.addr`),
`hive-agent-backend-env.service` also keeps this file's text at
`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
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

View file

@ -3,30 +3,31 @@
# itself into the file the harness and the subagent daemon load as
# `EnvironmentFile=`.
#
# The store holds the file's text at `swarm/agents/<agent>/backend-env`, field
# `env` (`swarm_secret_client::backend_env`). Each run does one of three things:
# The store holds the configuration at `swarm/agents/<agent>/backend-env` and the
# 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 none and `backendEnvironmentFile` is a non-empty file: the
# file's exact bytes are created at the leaf with `-cas=0`, then read back
# - the store has a configuration, secrets or both: they are written to
# `/run/hive-agent-backend-env/env`, the configuration first, so a secret wins
# 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
# 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
# file stays an `EnvironmentFile=` of its own, listed before the fetched one:
# systemd lets a later file override an earlier one, so the store's value wins
# when there is one, and the file carries the agent when the store is down.
#
# The leaf's create grant cannot constrain content, so while the leaf is empty
# the agent's own process can also create it with any text, and the store's
# 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.
# It never rotates a value and never touches `backendEnvironmentFile`, which stays
# an `EnvironmentFile=` of its own, listed before the fetched one: a later file
# overrides an earlier one, so the store wins and the file carries the agent when
# 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
# it already owns (`heal_own_dir` in `./user.nix` re-owns the harness dir at boot).
# The unit runs as root because an operator's file is root-owned `0600`.
{
pkgs,
lib,
@ -48,13 +49,19 @@ let
# `path::MOUNT`.
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;
envFile = "/run/${runtimeDir}/env";
stagedFile = "/run/${runtimeDir}/env.new";
stagedTextFile = "/run/${runtimeDir}/text.new";
stagedSecretsFile = "/run/${runtimeDir}/secrets.new";
errFile = "/run/${runtimeDir}/bao.err";
# An OAuth claude agent has no backend credentials to fetch.
fetches = cfg.addr != null && (agentCfg.useApiKey || agentCfg.runtime == "acp");
# Every agent with a store: an operator may store credentials for any of them,
# and an agent with neither configuration nor secrets gets no file.
fetches = cfg.addr != null;
earlier = agentCfg.backendEnvironmentFile;
@ -68,8 +75,8 @@ in
description = ''
The `EnvironmentFile=` entries that carry this agent's backend
environment, in load order: `backendEnvironmentFile` when set, then the
file `${unitName}.service` keeps when the agent has a store and uses an
API key. Read-only: the harness and the subagent daemon take it as it is.
file `${unitName}.service` keeps when the agent has a store. Read-only:
the harness and the subagent daemon take it as it is.
'';
};
@ -125,9 +132,11 @@ in
err=${lib.escapeShellArg errFile}
staged=${lib.escapeShellArg stagedFile}
staged_text=${lib.escapeShellArg stagedTextFile}
staged_secrets=${lib.escapeShellArg stagedSecretsFile}
live=${lib.escapeShellArg envFile}
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
# start timeout.
@ -140,51 +149,70 @@ in
fi
export BAO_TOKEN
# Sets READ to have, missing or unusable, and leaves the value in
# $staged. `kv get` exits 2 with "No value found at <path>" for a leaf
# nobody wrote, and 2 again for a refused read, so the message tells
# them apart. The value goes from the store's answer into a file and
# is never in a variable or an argument.
# Sets READ to have, missing or unusable for the leaf at $1, and leaves
# its field $2 in the file $3. `kv get` exits 2 with "No value found at
# <path>" for a leaf nobody wrote, and 2 again for a refused read, so
# the message tells them apart. The value goes from the store's answer
# into a file and is never in a variable or an argument.
read_leaf() {
rm -f "$staged"
if store kv get -field=env ${lib.escapeShellArg leaf} >"$staged" 2>"$err"; then
if [ -s "$staged" ]; then READ=have; else READ=unusable; fi
rm -f "$3"
if store kv get -field="$2" "$1" >"$3" 2>"$err"; then
if [ -s "$3" ]; then READ=have; else READ=unusable; fi
elif grep -q '^No value found at ' "$err"; then
READ=missing
elif grep -q '^Field "env" not present' "$err"; then
elif grep -q "^Field \"$2\" not present" "$err"; then
READ=unusable
else
echo "could not read ${leaf}:" >&2
echo "could not read $1:" >&2
cat "$err" >&2
exit 1
fi
}
read_leaf
if [ "$READ" = missing ]; then
if [ -n "$earlier" ] && [ -s "$earlier" ]; then
echo "${leaf} holds nothing; creating it from $earlier."
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
cat "$err" >&2
fi
read_leaf
else
echo "${leaf} holds nothing and there is no file to create it from."
exit 0
read_leaf ${lib.escapeShellArg leaf} env "$staged_text"
if [ "$READ" = missing ] && [ -n "$earlier" ] && [ -s "$earlier" ]; then
echo "${leaf} holds nothing; creating it from $earlier."
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
cat "$err" >&2
fi
read_leaf ${lib.escapeShellArg leaf} env "$staged_text"
fi
if [ "$READ" != have ]; then
echo "${leaf} holds no usable env; the file in place, if any, is used." >&2
TEXT=$READ
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
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
echo "this agent's backend environment at ${leaf} is unchanged."
echo "this agent's backend environment at ${leaf} and ${secretsLeaf} is unchanged."
exit 0
fi
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
(
(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 != [ ]
)
{
# A subagent authenticates with the same credentials as the
# harness: an ACP subagent to its provider, a claude subagent of
# 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;
};
};

View file

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

View file

@ -183,7 +183,7 @@ let
{
# The case above is the presence control: the same lookup finds the
# 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 =
let
fetched =
@ -195,8 +195,8 @@ let
!(fetched claudeApiKey)
&& !(fetched acp)
&& !(fetched opencode)
&& !(fetched claudeBao)
&& !(claudeBao.systemd.services ? hive-agent-backend-env)
&& fetched claudeBao
&& claudeBao.systemd.services ? hive-agent-backend-env
&& !(claudeApiKey.systemd.services ? hive-agent-backend-env)
&& claudeApiKeyBao.systemd.services ? hive-agent-backend-env
&& claudeApiKeyBao.systemd.timers ? hive-agent-backend-env;
@ -228,7 +228,8 @@ let
let
s = claudeApiKeyBao.systemd.services.hive-agent-backend-env.script;
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 "earlier=${backendEnv}" 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/+/forge/\" {\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
@ -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/+/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/+/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

View file

@ -26,10 +26,13 @@ case "$1 $2" in
}
;;&
"kv get")
[ "$3" = -field=env ] || {
echo "fake bao: get without -field=env: $*" >&2
exit 95
}
case "$3" in
-field=env | -field=key) ;;
*)
echo "fake bao: get without -field=env or -field=key: $*" >&2
exit 95
;;
esac
leaf=$FAKE_BAO_KV/$(printf '%s' "$4" | tr / _)
[ -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
@ -46,7 +49,7 @@ case "$1 $2" in
exit 2
fi
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
fi
cat "$leaf"

View file

@ -13,8 +13,10 @@ fail() {
}
leaf=secret/swarm/agents/a1/backend-env
secrets_leaf=secret/swarm/agents/a1/backend-secrets
login_call="login -method=cert -token-only"
get_call="kv get -field=env $leaf"
secrets_call="kv get -field=env $secrets_leaf"
# setup <description>
setup() {
@ -43,6 +45,7 @@ setup() {
deny_write=
race=
stored=$kv/$(printf '%s' "$leaf" | tr / _)
stored_secrets=$kv/$(printf '%s' "$secrets_leaf" | tr / _)
}
go() {
@ -124,6 +127,11 @@ expect_leaf() {
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'
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"
go
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_same "$rt/env" "$file_text"
expect_earlier_untouched "$file_text"
@ -160,7 +168,7 @@ put_earlier "$file_text"
put_leaf $'ANTHROPIC_API_KEY=k-bao\n'
go
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_same "$rt/env" $'ANTHROPIC_API_KEY=k-bao\n'
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"
go
expect_rc 0
expect_out "no file to create it from"
expect_calls "$login_call" "$get_call"
expect_out "no file to create them from"
expect_calls "$login_call" "$get_call" "$secrets_call"
expect_no_file "$rt/env"
expect_no_file "$stored"
@ -198,16 +206,17 @@ setup "an empty file is never stored"
put_earlier ""
go
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 "$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"
chmod 0600 "$rt/env"
go
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"
put_earlier "$file_text"
@ -226,7 +235,7 @@ put_earlier "$file_text"
race=$'ANTHROPIC_API_KEY=k-winner\n'
go
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_leaf $'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
go
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 "holds no usable env"
expect_out "hold nothing"
expect_no_file "$rt/env"
expect_no_file "$stored"
expect_earlier_untouched "$file_text"
@ -249,8 +258,8 @@ put_earlier "$file_text"
put_leaf ""
go
expect_rc 0
expect_calls "$login_call" "$get_call"
expect_err "holds no usable env"
expect_calls "$login_call" "$get_call" "$secrets_call"
expect_err "holds no usable value"
expect_leaf ""
expect_no_file "$rt/env"
@ -260,7 +269,7 @@ put_leaf "x"
printf other >"$stored.field"
go
expect_rc 0
expect_calls "$login_call" "$get_call"
expect_calls "$login_call" "$get_call" "$secrets_call"
expect_leaf "x"
expect_no_file "$rt/env"
@ -275,6 +284,49 @@ expect_calls "$login_call" "$get_call"
expect_no_file "$rt/env"
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
# stopped run must not block the next.
setup "leftovers of a stopped run do not block the fetch"