vinzenz/hyperhive
vinzenz/hyperhive
Watch
0
0
Fork
You've already forked hyperhive
 0
Code Activity

github: PATs live in swarm bao; the agent fetches them itself

Browse source 
An operator links an agent's GitHub personal access token in the swarm UI
(LinkGithubAccountForm, "link github account" on /agents). swarm-controller's
PUT /api/hives/{hive}/agents/{agent}/github-account stores it at
swarm/agents/<agent>/github-token (swarm_secret_client::github), a flat leaf
under the agent's prefix that the agent's existing read grant already covers:
no policy change, and no list grant, since there is one token per agent.

In the agent, hive-agent-github-token (oneshot + 2-minute timer, as the agent
user, under its own store certificate, ordered before hive-github-notify)
reads that path and writes <state>/github-token, 0600 and agent-owned, the
file the gh wrapper, git credential helper and hive-github-notify already
read. It replaces the file by rename only when the bytes changed and never
deletes it: a hive-written github-token stays until a token is linked in the
swarm UI. It is installed only with a store address and
services.hyperhive.agent.github.enable.

Removed: the dashboard's CR3D3NTIALS page (credentials.html/js/css, its
build entries and H0M3 tile; GITHUB was its only tab), hive-c0re's
dashboard/matrix_accounts.rs with GET/POST /api/github-account,
priv_client::write_agent_github_token, the host socket's
SetAgentGithubToken and `hivectl github set-token`, and hive-priv's
WriteAgentGithubToken with write_agent_state_file, its only caller gone.

Docs: integrations/github.md and swarm/ui.md describe the swarm path,
swarm/credentials.md gains the store-path row, and the hive UI docs,
hivectl docs and security.md's hive-priv table drop the removed pieces.

Closes #4347
This commit is contained in:
atlas 2026-10-02 17:48:27 +02:00
commit 8e23feb01b
41 changed files with 804 additions and 846 deletions
Download patch file Download diff file Expand all files Collapse all files

1
nix/agent-modules/default.nix
View file

@ -50,6 +50,7 @@ in
./forge-token.nix
./frontend.nix
./github.nix
./github-token.nix
./logs.nix
./matrix.nix
./mcp.nix

154
nix/agent-modules/github-token.nix Normal file
View file

@ -0,0 +1,154 @@
# This agent's GitHub personal access token, fetched from the swarm secret
# store by the agent itself, into the file ./github.nix's readers use.
#
# An operator links the token in the swarm UI; `swarm-controller` stores it at
# `swarm/agents/<agent>/github-token` (`swarm_secret_client::github`). The
# agent's own read grant covers that path, so this unit reads it and writes
# `<state>/github-token`, which the `gh` wrapper, the git credential helper and
# `hive-github-notify` read.
#
# It never deletes. A `github-token` already in place stays when the store has
# none or cannot be read. The file is replaced by rename, and only when its
# bytes changed.
{
pkgs,
lib,
config,
...
}:
let
cfg = config.services.hyperhive.agent.bao;
agentName = config.services.hyperhive.agent.user.name;
stateDir = "/agents/${agentName}/state";
# The same three ids ./bao.nix and ./forge-accounts.nix load.
certCredential = "hive-agent-bao-cert";
keyCredential = "hive-agent-bao-key";
serverCaCredential = "hive-agent-bao-server-ca";
unitName = "hive-agent-github-token";
# The nix half of `swarm_secret_client::github::account_path` plus
# `path::MOUNT`.
tokenPath = "secret/swarm/agents/${agentName}/github-token";
runtimeDir = unitName;
# The store's whole answer, token included: kept in the unit's own `0700`
# directory, never in the state dir.
rawFile = "/run/${runtimeDir}/account.json";
errFile = "/run/${runtimeDir}/bao.err";
tokenFile = "${stateDir}/github-token";
stagedFile = "${stateDir}/.github-token.new";
configured = cfg.addr != null && config.services.hyperhive.agent.github.enable;
storeRetry = import ../host-modules/lib/store-retry.nix { };
in
{
config = lib.mkIf configured {
systemd.services.${unitName} = {
description = "fetch this agent's GitHub token from the secret store";
after = [
"network.target"
"hive-agent-bao-identity.service"
];
# The poller reads the token once at start.
before = [ "hive-github-notify.service" ];
wantedBy = [ "multi-user.target" ];
path = [
pkgs.openbao
pkgs.coreutils
pkgs.diffutils
pkgs.jq
];
# ../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.
RemainAfterExit = false;
TimeoutStartSec = 30;
User = agentName;
Group = agentName;
RuntimeDirectory = runtimeDir;
RuntimeDirectoryMode = "0700";
# `0600`, the mode `github-token` has always had.
UMask = "0077";
LoadCredential = [
certCredential
keyCredential
serverCaCredential
];
};
environment = {
BAO_ADDR = cfg.addr;
BAO_CLIENT_CERT = "%d/${certCredential}";
BAO_CLIENT_KEY = "%d/${keyCredential}";
};
script = ''
set -euo pipefail
# No identity delivered: ./bao.nix's check reports that.
for id in ${lib.escapeShellArg certCredential} ${lib.escapeShellArg keyCredential}; do
if [ ! -s "$CREDENTIALS_DIRECTORY/$id" ]; then
echo "this agent has no store identity, so it cannot fetch its GitHub token." >&2
exit 0
fi
done
if [ -s "$CREDENTIALS_DIRECTORY/${serverCaCredential}" ]; then
export BAO_CACERT="$CREDENTIALS_DIRECTORY/${serverCaCredential}"
fi
err=${lib.escapeShellArg errFile}
raw=${lib.escapeShellArg rawFile}
staged=${lib.escapeShellArg stagedFile}
token=${lib.escapeShellArg tokenFile}
trap 'rm -f "$err" "$raw" "$staged"' EXIT
if ! BAO_TOKEN="$(bao 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
# No token linked and a store that cannot answer look alike here, and
# either way the file in place, if any, is kept.
if ! bao kv get -format=json ${lib.escapeShellArg tokenPath} >"$raw" 2>"$err"; then
echo "no GitHub token read from ${tokenPath}; github-token left as it is:" >&2
if [ -s "$err" ]; then cat "$err" >&2; fi
exit 0
fi
# ⚠️ The token goes from the store's answer straight into a file; it is
# never in a variable or an argument. A malformed object exits 0:
# failing the unit would only restart it into the same answer.
rm -f "$staged"
if ! jq -er '.data.data.value | strings' "$raw" >"$staged"; then
echo "${tokenPath} holds no string value; github-token left as it is." >&2
exit 0
fi
if cmp -s "$staged" "$token"; then
echo "this agent's GitHub token at ${tokenPath} is unchanged."
exit 0
fi
mv -f "$staged" "$token"
echo "fetched this agent's GitHub token from ${tokenPath}."
'';
};
# The same cadence as ./forge-accounts.nix.
systemd.timers.${unitName} = {
description = "re-fetch this agent's GitHub token from the secret store";
wantedBy = [ "timers.target" ];
timerConfig = {
OnUnitInactiveSec = "2min";
RandomizedDelaySec = "20s";
};
};
};
}

17
nix/agent-modules/github.nix
View file

@ -1,7 +1,7 @@
# GitHub integration (services.hyperhive.agent.github.enable): a `gh` wrapper + a git
# credential helper, both reading the PAT from the agent's
# `github-token` state file at invocation, so a dashboard-pasted token
# takes effect with no rebuild. The token PATH is baked in at build
# `github-token` state file at invocation, so a token ./github-token.nix
# fetches takes effect with no rebuild. The token PATH is baked in at build
# time (nix knows `userName`) — NOT read from `$HIVE_GITHUB_TOKEN_FILE`,
# because claude's Bash tool runs `bash -c` in a minimal env that
# doesn't source `/etc/set-environment`, so the env var isn't present
@ -41,12 +41,13 @@ in
description = ''
Install the GitHub integration in this agent: a `gh` CLI wrapper and a
git credential helper for `https://github.com`, both authenticated from
an operator-supplied personal access token (PAT). The PAT is written to
`<state>/github-token` out of band --- the dashboard credentials tab or
`hivectl github set-token` --- so giving an agent GitHub is a runtime
paste, no per-agent config or rebuild. The wrappers read the token file
at invocation, so a freshly-pasted PAT takes effect immediately; until
one exists, `gh` / `git push` just fail unauthenticated.
an operator-supplied personal access token (PAT). The operator links the
PAT in the swarm UI, and the agent fetches it from the swarm secret store
into `<state>/github-token` (needs `services.hyperhive.agent.bao.addr`),
so giving an agent GitHub is a runtime action, no per-agent config or
rebuild. The wrappers read the token file at invocation, so a fetched
PAT takes effect immediately; until one exists, `gh` / `git push` just
fail unauthenticated.
github.com only. git authenticates as `x-access-token` + the PAT (GitHub
ignores the username for PAT auth); `gh` derives its identity from the

4
nix/checks.nix
View file

@ -126,6 +126,10 @@ in
inherit pkgs self nixosSystem;
inherit (pkgs) lib;
};
module-eval-agent-github-bao = import ./module-eval/agent-github-bao.nix {
inherit pkgs self nixosSystem;
inherit (pkgs) lib;
};
module-eval-agent-memory = import ./module-eval/agent-memory.nix {
inherit pkgs self nixosSystem;
inherit (pkgs) lib;

5
nix/host-modules/hyperhive.nix
View file

@ -219,9 +219,8 @@ in
description = ''
Hive-wide switch for the per-agent GitHub integration (the `gh` CLI
wrapper + git credential helper, per `hyperhive.github.enable`). On by
default: every agent gets the integration, inert until a PAT is
provisioned via the dashboard credentials tab or `hivectl github
set-token`. Set `false` to turn it off for the whole hive --- the
default: every agent gets the integration, inert until an operator links
a PAT for it in the swarm UI. Set `false` to turn it off for the whole hive --- the
meta-flake renderer (`hive-c0re/src/meta.rs`) then injects
`hyperhive.github.enable = false` into every agent. Exposed to hive-c0re
as `HYPERHIVE_GITHUB_DISABLED` (set only when the integration is off).

114
nix/module-eval/agent-github-bao.nix Normal file
View file

@ -0,0 +1,114 @@
# `checks.module-eval-agent-github-bao` — see ./lib.nix for the shared
# rationale (why this suite exists, naming convention, "evaluates
# not executes").
#
# The agent side of the swarm-stored GitHub token: ../agent-modules/github-token.nix
# fetches it into the file ../agent-modules/github.nix's readers use.
{
pkgs,
lib,
self,
nixosSystem,
}:
let
inherit
(import ./lib.nix {
inherit
pkgs
lib
self
nixosSystem
;
})
agentWith
runGroup
;
baoAddr = "https://bao.t.local:8200";
# A store, and the integration on by default.
agentGithubBao = agentWith {
services.hyperhive.agent.bao.addr = baoAddr;
};
# No store: the absence arm, and what makes the cases above able to fail.
agentGithubNoBao = agentWith { };
# A store, and the integration switched off.
agentGithubOff = agentWith {
services.hyperhive.agent.bao.addr = baoAddr;
services.hyperhive.agent.github.enable = false;
};
fetchUnit = machine: machine.systemd.services.hive-agent-github-token;
has = machine: machine.systemd.services ? hive-agent-github-token;
hasTimer = machine: machine.systemd.timers ? hive-agent-github-token;
in
let
cases = [
{
name = "an agent with a store address and the integration on fetches its github token";
ok = has agentGithubBao && hasTimer agentGithubBao;
}
{
name = "an agent with no store address, or with the integration off, fetches none";
ok =
!(has agentGithubNoBao)
&& !(hasTimer agentGithubNoBao)
&& !(has agentGithubOff)
&& !(hasTimer agentGithubOff);
}
{
# The nix half of `swarm_secret_client::github::account_path`, and the
# file ./github.nix's `gh` wrapper, credential helper and poller read.
name = "the fetch reads the agent's own github-token path into its state-dir file";
ok =
let
name = agentGithubBao.services.hyperhive.agent.user.name;
s = (fetchUnit agentGithubBao).script;
in
lib.hasInfix "bao kv get -format=json secret/swarm/agents/${name}/github-token >" s
&& lib.hasInfix "token=/agents/${name}/state/github-token" s
&& lib.hasInfix ".data.data.value | strings" s;
}
{
# The agent user owns its state dir (./user.nix), and the file keeps the
# `0600` it has always had.
name = "the fetch runs as the agent, with its own store identity";
ok =
let
u = fetchUnit agentGithubBao;
name = agentGithubBao.services.hyperhive.agent.user.name;
in
u.serviceConfig.User == name
&& u.serviceConfig.UMask == "0077"
&& builtins.elem "hive-agent-bao-cert" u.serviceConfig.LoadCredential
&& builtins.elem "hive-agent-bao-key" u.serviceConfig.LoadCredential
&& u.environment.BAO_ADDR == baoAddr
&& u.environment.BAO_CLIENT_CERT == "%d/hive-agent-bao-cert"
&& u.environment.BAO_CLIENT_KEY == "%d/hive-agent-bao-key";
}
{
# A file a hive wrote keeps working until the operator links a token in
# the swarm UI.
name = "the fetch never deletes the state-dir token, and swaps it in only on a change";
ok =
let
s = (fetchUnit agentGithubBao).script;
in
!(lib.hasInfix "rm -f \"$token\"" s)
&& lib.hasInfix "cmp -s \"$staged\" \"$token\"" s
&& lib.hasInfix "mv -f \"$staged\" \"$token\"" s;
}
{
# The poller reads the token once at start.
name = "the fetch runs before the github poller starts";
ok = builtins.elem "hive-github-notify.service" (fetchUnit agentGithubBao).before;
}
{
name = "the fetch re-runs every two minutes";
ok = agentGithubBao.systemd.timers.hive-agent-github-token.timerConfig.OnUnitInactiveSec == "2min";
}
];
in
runGroup "agent-github-bao" cases