# 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//backend-env` and the # credentials apart from it at `swarm/agents//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 # " 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" ]; }; }; }