Watch
0
0
Fork
You've already forked hyperhive
0
hyperhive/nix/agent-modules/backend-env.nix
iris 33fdd5205e 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.
2026-11-20 20:36:33 +01:00

240 lines
9.7 KiB
Nix

# This agent's backend environment (`ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`,
# an ACP provider key), fetched from the swarm secret store by the agent
# itself into the file the harness and the subagent daemon load as
# `EnvironmentFile=`.
#
# 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 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;
# - 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`, 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,
config,
...
}:
let
agentCfg = config.services.hyperhive.agent;
cfg = agentCfg.bao;
agentName = agentCfg.user.name;
# The server CA id ./bao.nix loads.
serverCaCredential = "hive-agent-bao-server-ca";
unitName = "hive-agent-backend-env";
# The nix half of `swarm_secret_client::backend_env::env_path` plus
# `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";
# 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;
storeRetry = import ../host-modules/lib/store-retry.nix { };
in
{
options.services.hyperhive.agent.backendEnvironment.environmentFiles = lib.mkOption {
type = lib.types.listOf lib.types.str;
readOnly = true;
default = lib.optional (earlier != null) "-${earlier}" ++ lib.optional fetches "-${envFile}";
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. Read-only:
the harness and the subagent daemon take it as it is.
'';
};
config = lib.mkIf fetches {
systemd.services.${unitName} = {
description = "fetch this agent's backend environment from the secret store";
after = [
"network.target"
"hive-agent-bao-identity.service"
];
wantedBy = [ "multi-user.target" ];
path = [
pkgs.openbao
pkgs.coreutils
pkgs.diffutils
pkgs.gnugrep
];
# ../host-modules/lib/store-retry.nix.
inherit (storeRetry) startLimitBurst startLimitIntervalSec;
serviceConfig = storeRetry.serviceConfig // {
Type = "oneshot";
# Not `RemainAfterExit`, so the timer below can start it again.
# `RuntimeDirectoryPreserve` keeps the file between runs and after the
# last one: the consumers read it at their own start.
RemainAfterExit = false;
TimeoutStartSec = 60;
RuntimeDirectory = runtimeDir;
RuntimeDirectoryMode = "0700";
RuntimeDirectoryPreserve = "yes";
# `0600`, the mode of the file an operator placed.
UMask = "0077";
LoadCredential = [ serverCaCredential ];
};
environment = {
BAO_ADDR = cfg.addr;
BAO_CLIENT_CERT = cfg.clientCertFile;
BAO_CLIENT_KEY = cfg.clientKeyFile;
};
script = ''
set -euo pipefail
# No identity delivered: ./bao.nix's check reports that.
for f in "$BAO_CLIENT_CERT" "$BAO_CLIENT_KEY"; do
if [ ! -s "$f" ]; then
echo "this agent has no store identity, so it cannot fetch its backend environment." >&2
exit 0
fi
done
if [ -s "$CREDENTIALS_DIRECTORY/${serverCaCredential}" ]; then
export BAO_CACERT="$CREDENTIALS_DIRECTORY/${serverCaCredential}"
fi
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" "$staged_text" "$staged_secrets"' EXIT
# Bounded, so a store that drops packets cannot hold the unit past its
# start timeout.
store() { timeout 15 bao "$@"; }
if ! BAO_TOKEN="$(store login -method=cert -token-only 2>"$err")"; then
echo "the swarm secret store at $BAO_ADDR did not accept this agent's certificate login:" >&2
if [ -s "$err" ]; then cat "$err" >&2; fi
exit 1
fi
export BAO_TOKEN
# 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 "$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 \"$2\" not present" "$err"; then
READ=unusable
else
echo "could not read $1:" >&2
cat "$err" >&2
exit 1
fi
}
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
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} and ${secretsLeaf} is unchanged."
exit 0
fi
mv -f "$staged" "$live"
echo "fetched this agent's backend environment from ${leaf} and ${secretsLeaf}."
'';
};
# The same cadence as ./github-token.nix.
systemd.timers.${unitName} = {
description = "re-fetch this agent's backend environment from the secret store";
wantedBy = [ "timers.target" ];
timerConfig = {
OnUnitInactiveSec = "2min";
RandomizedDelaySec = "20s";
};
};
# `wants`, not `requires`: a store outage must not stop the harness, whose
# `backendEnvironmentFile` still loads. `after` waits for one attempt.
systemd.services.hive-agent = {
wants = [ "${unitName}.service" ];
after = [ "${unitName}.service" ];
};
systemd.services.hive-subagent-daemon = {
wants = [ "${unitName}.service" ];
after = [ "${unitName}.service" ];
};
};
}