From e621397252ef8e9bc0afbbfb270a6683b56527ee Mon Sep 17 00:00:00 2001 From: atlas Date: Mon, 16 Nov 2026 18:38:10 +0100 Subject: [PATCH] swarm ui ssh row with target snippets, docs for the per-agent switch --- docs/2-handbook/external-accounts/ssh.md | 115 ++++++------- .../swarm/credentials-reference.md | 2 +- docs/4-implementation/swarm/ssh-ca.md | 70 +++++--- docs/4-implementation/web-ui/swarm-ui.md | 11 ++ docs/5-project/process/conventions.md | 5 + .../swarm-ui/src/agent/detail/AgentDetail.tsx | 3 + .../src/agent/detail/AgentPermissions.tsx | 3 +- .../swarm-ui/src/agent/detail/AgentSsh.tsx | 156 ++++++++++++++++++ .../packages/swarm-ui/src/agent/detail/ssh.ts | 75 +++++++++ .../packages/swarm-ui/test/agent-ssh.test.mjs | 62 +++++++ nix/host-modules/lib/ssh-agent-ca.nix | 2 +- nix/target-modules/agent-ssh.nix | 5 +- 12 files changed, 416 insertions(+), 93 deletions(-) create mode 100644 frontend/packages/swarm-ui/src/agent/detail/AgentSsh.tsx create mode 100644 frontend/packages/swarm-ui/src/agent/detail/ssh.ts create mode 100644 frontend/packages/swarm-ui/test/agent-ssh.test.mjs diff --git a/docs/2-handbook/external-accounts/ssh.md b/docs/2-handbook/external-accounts/ssh.md index 4d200af8e..4c804e936 100644 --- a/docs/2-handbook/external-accounts/ssh.md +++ b/docs/2-handbook/external-accounts/ssh.md @@ -1,44 +1,33 @@ # SSH access to a machine Let an agent SSH into a machine you name, such as a test VM, without copying a -key onto it. The agent holds no standing SSH key. It asks the swarm's secret -store for a certificate that lasts an hour, and the machine trusts the swarm's -SSH certificate authority (CA) instead of a list of keys. +key onto it. The agent holds no standing SSH key. While you allow it, the agent +gets a certificate from the swarm's SSH certificate authority (CA) that lasts +an hour. The machine trusts the CA, so it needs no list of keys. -Agent-side, nothing changes until you do both of these: +Two things have to be true before an agent gets in: -1. Switch SSH on for the agent and name the machines it may reach. -2. Make each machine trust the CA and list the agents allowed in. +1. **You switch SSH on for that agent**, in the swarm UI. +2. **The machine trusts the CA** and lists the agent. -The permission to get a certificate is in the policy every agent shares, so -every agent with a store identity can already get a certificate for its own -name, whether or not you switch SSH on for it. That's harmless: no machine -trusts a name it doesn't list. Switching SSH on only sets up the key, the -renewal and the client config. +Every agent already has an SSH client, a key it makes in memory, and a +certificate unit. The switch alone decides whether the swarm signs. ## 1. Switch it on for an agent -In the agent's config: +Open the agent's card in the swarm UI and find the **ssh** row. Select it and +tick **allow the agent to get SSH certificates**. The default is off. The +agent has a certificate within about 25 minutes of the change. Untick the box +to stop new certificates. The row also shows the three forms of the target +setup below, already filled in with the swarm's CA key and the agent's name. -```nix -services.hyperhive.agent.ssh = { - enable = true; - hosts.testvm = { - hostName = "10.0.0.7"; - user = "test"; - port = 22; # the default - hostKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…"; - }; -}; -``` +The agent then runs `ssh user@host`, with no other setup. It offers its +certificate and nothing else. -`hostKey` is the machine's own host public key, the one line in -`/etc/ssh/ssh_host_ed25519_key.pub` on it. The agent pins it: it refuses a -machine that presents any other key, and never trusts a key on first sight. - -The agent then runs `ssh testvm` with no other flag. The agent's SSH client -offers its certificate and nothing else. The option needs the agent to have a -store identity, the same as for its other store credentials. +**Host keys use trust on first use.** The agent accepts the key a machine +shows on the first connection, keeps it in its state directory (so it survives +restarts), and refuses a changed key afterwards. A swapped machine on the first +contact would go unnoticed. The row's explainer says so. This doesn't open the network. If you set the hive's `egress.forward` to `reject`, the hive refuses the agent's direct connection to the machine's port @@ -47,33 +36,31 @@ until a separate allowance exists; the default `log` lets it through. See ## 2. Make a machine trust the CA -On the swarm's store host, read the CA's public key: +Open **on the target** in the same row. It shows the swarm's CA public key, a +public value, and the agent's name, in three forms. Replace `` with the +account the agent logs in as. The target never contacts the swarm. + +- **NixOS:** the CA key in `services.openssh.settings.TrustedUserCAKeys` and + `users.users..openssh.authorizedPrincipals = [ "" ];`. The same + as one module: import `hyperhive.nixosModules.agent-ssh-target` and set + `services.hyperhive.agentSshTarget` (`enable`, `caPublicKey`, + `principals.`). +- **home-manager:** `home.file.".ssh/authorized_keys".text` holding one + `cert-authority` line. +- **plain ssh:** one line in the account's `~/.ssh/authorized_keys`: + + ``` + cert-authority,principals="" ssh-ed25519 AAAA… + ``` + + This works on any machine without a change to its sshd config. + +To read the CA key outside the UI, run this on the swarm's store host: ```bash bao read -field=public_key ssh-agents/config/ca ``` -The store also serves the same key without a token at -`/v1/ssh-agents/public_key`. The key is public and you set it -once. Then import the module on the machine, which can be any NixOS machine, -and not only a hive host: - -```nix -{ - imports = [ hyperhive.nixosModules.agent-ssh-target ]; - - services.hyperhive.agentSshTarget = { - enable = true; - caPublicKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…"; - principals.test = [ "atlas" "maia" ]; - }; -} -``` - -`principals.` lists the agents that may log in as that local account. The -account has to exist. An account with no entry accepts no certificate. The -module writes no `authorized_keys`. - ## What an agent can and can't do - It can only get a certificate for **its own name**. The store signs for the @@ -86,19 +73,17 @@ module writes no `authorized_keys`. ## Revoking access -- **One agent from one machine:** remove its name from that user's - `principals` and deploy the machine. The next login attempt fails. -- **One agent from every machine:** remove its name from every machine's - `principals`. That's the revocation. No swarm-wide switch - stops signing for an agent that a hive still declares: if you delete - its cert-auth role `hive-agent-` in the store, `swarm-controller` - writes it back within five minutes. Signing stops only once no hive declares - the agent any more (you destroyed it); the controller then stops renewing - its store identity, and the identity lapses with its 7-day certificate. -- **A certificate already issued** stays valid until it expires, at most three - hours, whatever you remove. Removing a principal blocks new logins at once. -- **The CA itself:** if the CA key changes, every machine needs the - new public key. Nothing replaces the CA by itself. +- **One agent from one machine:** remove its principal (the `authorizedPrincipals` + entry, or the `cert-authority` line) and deploy the machine. The next login + attempt fails. +- **One agent from every machine:** untick the switch. The swarm stops signing + for it within five minutes; an agent already signed in can still sign + for up to an hour. Destroying the agent cuts its store identity off within + minutes. Either way a certificate already signed stays valid until it + expires, at most three hours, so removing the principal on a machine is what + cuts it off there at once. +- **The CA itself:** if the CA key changes, every machine needs the new public + key. Nothing replaces the CA by itself. For the bao paths, field names and units, see [the SSH CA implementation page](../../4-implementation/swarm/ssh-ca.md). diff --git a/docs/4-implementation/swarm/credentials-reference.md b/docs/4-implementation/swarm/credentials-reference.md index 5c5819f78..5006da565 100644 --- a/docs/4-implementation/swarm/credentials-reference.md +++ b/docs/4-implementation/swarm/credentials-reference.md @@ -38,7 +38,7 @@ the rest of the cell says how. | `swarm/agents//claude-credentials` | `swarm-claude-login`, when you log the agent in from its card; one version per login | the agent, while it waits for a login | ❌ log in again | ✅ every 30 seconds while waiting | | `swarm/hives//forge/token` | `swarm-controller`, every 5 minutes | `swarm-controller` and the hive | ✅ when missing or no longer matching the forge | ✅ read on every forge call | | `swarm/agents//proxy-credential` | `swarm-controller`: 32 random bytes, at start and every 5 minutes for every agent that holds a store identity | the hive (`hive-c0re`) and the agent, which fetches it | ❌ never replaced: written only while the path holds nothing | ✅ `hive-c0re` re-reads it every 30 seconds | -| `ssh-agents/sign/swarm-agent` (a signing call, nothing is stored) | the store's SSH CA mount (`ssh-agents`), when the agent's `hive-agent-ssh-cert` unit asks it to sign the public key the unit generated in its own `/run`; the CA key is generated inside the store by `swarm-bao-agent-ssh-policy` | the agent, which keeps the key and the signed certificate in `/run` only; a target machine trusts the CA's public key by value | ✅ the certificate lasts 60 minutes; the CA is never replaced, and a target that holds a different CA key refuses every certificate | ✅ the agent signs again every 20 minutes | +| `ssh-agents/sign/swarm-agent` (a signing call, nothing is stored) | the store's SSH CA mount (`ssh-agents`), when the agent's `hive-agent-ssh-cert` unit asks it to sign, which the operator's per-agent `ssh` switch allows the public key the unit generated in its own `/run`; the CA key is generated inside the store by `swarm-bao-agent-ssh-policy` | the agent, which keeps the key and the signed certificate in `/run` only; a target machine trusts the CA's public key by value | ✅ the certificate lasts 60 minutes; the CA is never replaced, and a target that holds a different CA key refuses every certificate | ✅ the agent signs again every 20 minutes | | `swarm/hives//squid-selfcheck` | `swarm-controller`, in the same pass as the agents' credentials | the hive: `hive-c0re` and `squid-selfcheck-credential` (root) | ❌ never replaced: written only while the path holds nothing | ✅ `hive-c0re` every 30 seconds, the root unit every 10 minutes | | `swarm/hives//oidc/client` | authelia, first boot, straight into the store | the hive | ❌ minted once, straight into the store; minted again only when the store holds none | ✅ re-read when authelia refuses it | | `swarm/services//oidc/client` | authelia | that service | must be stated | must be stated | diff --git a/docs/4-implementation/swarm/ssh-ca.md b/docs/4-implementation/swarm/ssh-ca.md index ab760bcca..b144daa6b 100644 --- a/docs/4-implementation/swarm/ssh-ca.md +++ b/docs/4-implementation/swarm/ssh-ca.md @@ -39,18 +39,43 @@ each agent's cert login after the agent a glob, host certificates, other key types or another extension is a refusal from the store. -## What an agent may call +## The switch and the signing policy -The shared agent policy `hive-agent` (`render_shared_agent`) holds one more -stanza: `update` on `ssh-agents/sign/swarm-agent`, and nothing on the rest of -the mount. `swarm-controller` writes the policy at every start and at every -agent mint, so a deploy that adds the stanza reaches existing agents when the -controller restarts. A token already issued picks the change up on its next -request, because bao reads policies per request. +The operator's switch is the `ssh` field of the agent's record in `agent-permissions` +(`swarm_wire::agent_permissions`), set with `PUT /api/agents/{name}/permissions` +from the swarm UI's **ssh** row. Absent is off. A `PUT` or `DELETE` that leaves +the field out keeps it. + +Signing is a separate policy, `hive-agent-ssh` (`policy::SSH_POLICY`, +`render_ssh_signer`): `update` on `ssh-agents/sign/swarm-agent` and nothing +else. The shared agent policy `hive-agent` holds no SSH stanza. `swarm-controller` +writes `hive-agent-ssh` at every identity mint and every pass of `agent_ssh.rs`, +and attaches it to the agent's cert-auth role `hive-agent-` as a second +`token_policies` entry only while the switch is on. + +- **Rewrite.** A change of the field wakes `agent_ssh`'s pass at once, and the pass + also runs every five minutes. It reads each role's policies and rewrites only + `token_policies` (a partial write: the role's certificate, names and lifetimes + stay) when they differ from the shared policy plus, if on, `hive-agent-ssh`. + The identity mint (`agent_identity.rs`) keeps whatever the role has, so a + certificate renewal doesn't switch it off. The pass doesn't create a missing role. +- **When it takes effect.** A token carries the policies of the role it logged in + under and keeps them until it expires, at most the role's `token_ttl` of one + hour. Switching **on** reaches the agent at its next login, which its + certificate unit makes on every run (every 20 minutes), so within about 25 + minutes of the pass. Switching **off** stops every new login at once; an agent + already holding a token that carries the policy can still sign until that token + expires, at most an hour. Neither touches a certificate already signed: it + stays valid until it expires, at most three hours. +- **The CA key.** `GET /api/ssh/ca` returns `{ "public_key": "ssh-ed25519 …" }`, read + from `ssh-agents/config/ca` with the controller's own identity. The controller + holds `read` on that path and nothing else on the mount: it can't sign. It + answers 404 while the store holds no CA. ## The agent's unit -With `services.hyperhive.agent.ssh.enable`, `nix/agent-modules/ssh.nix` adds +`nix/agent-modules/ssh.nix` is on in every agent that has a store address +(`services.hyperhive.agent.bao.addr`), with no option. It adds `hive-agent-ssh-cert.service` and its timer, as the agent user: - the key is `/run/hive-agent-ssh-cert/key` (directory `0700`, files `0400`, @@ -58,14 +83,18 @@ With `services.hyperhive.agent.ssh.enable`, `nix/agent-modules/ssh.nix` adds `key-cert.pub` beside it; - each run logs in to the store with the cert identity `hive-agent-bao-identity` keeps, signs `key.pub` through the role, checks the answer parses as a - certificate and renames it into place; + certificate and renames it into place. A `403` from the signing call is the + switch being off: the unit prints one line and exits 0, and the next tick asks + again. Any other failure fails the unit, which retries; - the timer fires 20 minutes after each run, a third of the 60-minute lifetime, from the same file as the role's TTL; -- the generated `/etc/ssh/ssh_config` has one `Host ` block per entry - (`HostName`, `User`, `Port`, `IdentityFile`, `CertificateFile`, - `IdentitiesOnly yes`, `StrictHostKeyChecking yes`), and - `/etc/ssh/ssh_known_hosts` one pinned line per `hostKey` (`[host]:port` for a - port other than 22). +- the system `/etc/ssh/ssh_config` has one `Host *` block: `IdentityFile` and + `CertificateFile` from `/run`, `IdentitiesOnly yes`, + `StrictHostKeyChecking accept-new`, and + `UserKnownHostsFile /agents//state/ssh_known_hosts`. The host binds the + state directory in, so the pins survive a restart; the container root + doesn't. The agent trusts the first key a host shows and refuses a changed + one. ## The target module @@ -84,11 +113,8 @@ per-agent allowance for it yet. ## Revocation -Every agent shares the role, which holds nothing per agent, so there is no -per-agent signing switch. `swarm-controller`'s renewal pass (`agent_renewal.rs`) re-mints -the store identity, and writes the cert-auth role `hive-agent-` back, for -every agent a hive still declares, so deleting the role doesn't stick. Nothing -in the controller deletes the role when you destroy an agent; the renewal pass -skips a destroyed agent and its identity lapses with its 7-day -certificate. A target's `principals` list is the immediate control. A -certificate already signed stays valid for at most `max_ttl` (180 minutes). +Unticking the switch stops signing as described above. Destroying an agent +disables its identity entity and deletes its cert-auth role +(`agent_cutoff.rs`), after which its tokens stop working at once. A target's +principals list is the immediate control per machine. A certificate already +signed stays valid for at most `max_ttl` (180 minutes). diff --git a/docs/4-implementation/web-ui/swarm-ui.md b/docs/4-implementation/web-ui/swarm-ui.md index 3d074f8fb..4c7ddeea6 100644 --- a/docs/4-implementation/web-ui/swarm-ui.md +++ b/docs/4-implementation/web-ui/swarm-ui.md @@ -851,6 +851,17 @@ back, so the controller's log (`agent max repos`) is the record of what it appli to each agent. The controller tries an agent whose account the forge refuses again every five minutes. +The **ssh** row is whether the agent may get SSH certificates from the swarm: a +badge reading on or off, off by default. Selecting it opens an explainer, a +checkbox that does a `PUT` of `ssh` with the stored permissions beside it, and +a folded **on the target** section. That section reads `GET /api/ssh/ca` and +shows the swarm's CA key and the agent's name as the lines for a NixOS machine, +a home-manager user and a plain `authorized_keys` file, with a copy button; the +card builds the text in `frontend/packages/swarm-ui/src/agent/detail/ssh.ts`. A `PUT` +that leaves `ssh` out, and the `DELETE` of **use the default**, keep it. The +controller attaches the signing policy to the agent's login role within five +minutes; see [the SSH CA](../swarm/ssh-ca.md#the-switch-and-the-signing-policy). + A saved change isn't instant. The hive reads the grant about every 30 seconds and the agent takes it at its next turn. A change to `manage_root_agent` restarts the agent after its current turn. The card reads diff --git a/docs/5-project/process/conventions.md b/docs/5-project/process/conventions.md index 6086ce515..0a460eda6 100644 --- a/docs/5-project/process/conventions.md +++ b/docs/5-project/process/conventions.md @@ -349,6 +349,11 @@ off creating organizations on every agent account. A `PUT` that leaves the field out, a `DELETE`, and a re-create keep the stored value; the route refuses more than 100. +**SSH switch** — the record also carries `ssh`, whether the agent's login role +attaches the SSH signing policy. An absent value is off. Only the controller reads +it (`agent_ssh`). A `PUT` that leaves the field out, a `DELETE` and a re-create +keep the stored value. + **How a change applies** — - The agent's harness reads its own key every 10 seconds and builds every turn's `--tools`, `--allowedTools` and MCP config from the last value, so a diff --git a/frontend/packages/swarm-ui/src/agent/detail/AgentDetail.tsx b/frontend/packages/swarm-ui/src/agent/detail/AgentDetail.tsx index 358aeeeb1..838804bd9 100644 --- a/frontend/packages/swarm-ui/src/agent/detail/AgentDetail.tsx +++ b/frontend/packages/swarm-ui/src/agent/detail/AgentDetail.tsx @@ -22,6 +22,7 @@ import { AgentInference } from "./AgentInference.js"; import { StatusMessage } from "./StatusMessage.js"; import { AgentInstructions } from "./AgentInstructions.js"; import { AgentLimits } from "./AgentLimits.js"; +import { AgentSsh } from "./AgentSsh.js"; import { AgentInternet, AgentPermissions, @@ -229,6 +230,8 @@ function GrantRows({ agent }: { agent: string }) {
{g.grant === null ? g.loading : }
+
ssh
+
{g.grant === null ? g.loading : }
permissions
{g.grant === null ? ( diff --git a/frontend/packages/swarm-ui/src/agent/detail/AgentPermissions.tsx b/frontend/packages/swarm-ui/src/agent/detail/AgentPermissions.tsx index 35049eeeb..195003028 100644 --- a/frontend/packages/swarm-ui/src/agent/detail/AgentPermissions.tsx +++ b/frontend/packages/swarm-ui/src/agent/detail/AgentPermissions.tsx @@ -4,7 +4,7 @@ // changes. // // Both read `GET /api/agents/{name}/permissions`, which answers the stored -// grant as `{ permissions?, unrestricted_internet?, internet_log?, max_repos? }` (`{}` when +// grant as `{ permissions?, unrestricted_internet?, internet_log?, max_repos?, ssh? }` (`{}` when // the swarm sets none, so the agent runs on the default set). The permissions // control offers the catalogue from `GET /api/permissions` as checkboxes and // PUTs the ticked ones, a PUT replacing the stored value whole. A selection @@ -50,6 +50,7 @@ interface Grant { unrestricted_internet?: boolean; internet_log?: boolean; max_repos?: number; + ssh?: boolean; } // Mirrors swarm-controller's `Catalogue` (`GET /api/permissions`). diff --git a/frontend/packages/swarm-ui/src/agent/detail/AgentSsh.tsx b/frontend/packages/swarm-ui/src/agent/detail/AgentSsh.tsx new file mode 100644 index 000000000..53f9f1033 --- /dev/null +++ b/frontend/packages/swarm-ui/src/agent/detail/AgentSsh.tsx @@ -0,0 +1,156 @@ +// — one agent's SSH access in an opened agent card: a badge that +// opens an explainer, the switch, and a folded "on the target" section with the +// text a machine needs to trust the agent's certificates. +// +// The switch is the `ssh` field of `GET/PUT /api/agents/{name}/permissions`, +// shared with the other grant controls through `useGrant`. The CA key comes +// from `GET /api/ssh/ca`, which carries a public value only. The snippets are +// built in `ssh.ts`, prefilled with the key and this agent's name. +// +// Its state belongs to one agent: callers key it by agent name. +import { useEffect, useState } from "preact/hooks"; +import { ApiErrorPanel } from "@hive/shared/api-error-panel.js"; +import { readApiError, type ProblemDetails } from "@hive/shared/api-error.js"; +import { Badge } from "@hive/shared/badge.js"; +import { BadgePopover } from "../../ui/badge-popover/BadgePopover.js"; +import { Button } from "../../ui/button/Button.js"; +import { CheckboxField } from "../../ui/checkbox-field/CheckboxField.js"; +import { Hint } from "../../ui/hint/Hint.js"; +import { Preformatted } from "../../ui/preformatted/Preformatted.js"; +import type { GrantState } from "./AgentPermissions.js"; +import { + sshBody, + sshSummary, + targetSnippet, + TARGET_FORMS, + type TargetForm, +} from "./ssh.js"; + +export function AgentSsh({ agent, g }: { agent: string; g: GrantState }) { + const { grant, busy, saveError, loading, send } = g; + const [form, setForm] = useState("nixos"); + const [copied, setCopied] = useState(false); + // The CA key, or why there is none: a store without a CA yet answers 404. + const [ca, setCa] = useState(null); + const [caError, setCaError] = useState(null); + + useEffect(() => { + let cancelled = false; + (async () => { + const r = await fetch("/api/ssh/ca"); + if (!r.ok) { + if (!cancelled) setCaError(await readApiError(r)); + return; + } + const body = (await r.json()) as { public_key: string }; + if (!cancelled) setCa(body.public_key); + })().catch((e: unknown) => { + if (!cancelled) setCaError({ detail: String(e) }); + }); + return () => { + cancelled = true; + }; + }, []); + + if (grant === null) return loading; + + const on = grant.ssh === true; + const snippet = ca === null ? null : targetSnippet(form, agent, ca); + + async function copy() { + if (snippet === null) return; + try { + await navigator.clipboard.writeText(snippet); + setCopied(true); + setTimeout(() => setCopied(false), 1500); + } catch { + // No clipboard (an insecure context): the text is on screen to select. + } + } + + return ( +
+ +

+ Lets {agent} log in over SSH to machines that trust the swarm's SSH + certificate authority. With this on, {agent} gets a certificate that + names it and lasts one hour, and renews it every 20 minutes; its key + lives in memory only. The change reaches {agent} within about 25 + minutes. A certificate already signed stays valid until it expires, at + most three hours. A machine has to trust the authority before anything + works: see "on the target" below. +

+

+ {agent} accepts the key a machine shows on the first connection and + refuses a changed one afterwards (trust on first use). It does not + check the key against anything you registered. +

+ + void send({ + method: "PUT", + headers: { "content-type": "application/json" }, + body: JSON.stringify(sshBody(grant.permissions, next)), + }) + } + /> + {saveError ? ( + + ) : null} +
+ on the target + {snippet === null ? ( + caError ? ( + + ) : ( + + loading… + + ) + ) : ( + <> +

+ Put this on a machine {agent} should reach, with{" "} + <user> replaced by the account it logs in as. + The key is the swarm's CA, a public value. +

+
+ {TARGET_FORMS.map(([f, label]) => ( + setForm(f)} + /> + ))}{" "} + +
+ + {snippet} + + + )} +
+
+
+ ); +} diff --git a/frontend/packages/swarm-ui/src/agent/detail/ssh.ts b/frontend/packages/swarm-ui/src/agent/detail/ssh.ts new file mode 100644 index 000000000..f43d584bc --- /dev/null +++ b/frontend/packages/swarm-ui/src/agent/detail/ssh.ts @@ -0,0 +1,75 @@ +// An opened agent card's SSH row: what the badge says, the body of the PUT that +// flips the switch, and the text an operator puts on a target machine. Kept out +// of the component so `npm test` can run it. + +/** The three ways a target can be set up to trust the swarm's SSH CA. */ +export type TargetForm = "nixos" | "home-manager" | "ssh"; + +/** The forms in the order the card offers them, with their tab labels. */ +export const TARGET_FORMS: [TargetForm, string][] = [ + ["nixos", "NixOS"], + ["home-manager", "home-manager"], + ["ssh", "ssh"], +]; + +/** What the badge shows for a stored `ssh` flag: absent is off. */ +export function sshSummary(stored: boolean | undefined): string { + return stored === true ? "on" : "off"; +} + +/** + * The `PUT` body that sets the switch. A `PUT` without `permissions` resets a + * stored list to the default, so the stored list goes along, as in + * `internetBody`; the other fields are left out, which keeps them. + */ +export function sshBody( + stored: string[] | undefined, + on: boolean, +): { permissions?: string[]; ssh: boolean } { + return { + ...(stored === undefined ? {} : { permissions: stored }), + ssh: on, + }; +} + +/** + * The single `authorized_keys` line that makes a machine accept `agent`'s + * certificates, whatever its sshd config: it trusts the CA for that one + * principal and no other. + */ +export function authorizedKeysLine(agent: string, caKey: string): string { + return `cert-authority,principals="${agent}" ${caKey.trim()}`; +} + +/** + * The text for one form of target. `` stays a placeholder the operator + * edits: it is the account on the target the agent logs in as. + */ +export function targetSnippet( + form: TargetForm, + agent: string, + caKey: string, +): string { + const ca = caKey.trim(); + switch (form) { + case "nixos": + return [ + "# The CA key is public. sshd trusts certificates it signed, and the", + `# principal ${agent} may log in as .`, + `environment.etc."ssh/hyperhive-agent-ssh-ca.pub".text = "${ca}\\n";`, + 'services.openssh.settings.TrustedUserCAKeys = "/etc/ssh/hyperhive-agent-ssh-ca.pub";', + `users.users..openssh.authorizedPrincipals = [ "${agent}" ];`, + "", + "# The same, as one module: imports = [ hyperhive.nixosModules.agent-ssh-target ];", + "# services.hyperhive.agentSshTarget.enable = true, with caPublicKey and principals.", + ].join("\n"); + case "home-manager": + return [ + "home.file.\".ssh/authorized_keys\".text = ''", + ` ${authorizedKeysLine(agent, ca)}`, + "'';", + ].join("\n"); + case "ssh": + return `# in ~/.ssh/authorized_keys on the target\n${authorizedKeysLine(agent, ca)}`; + } +} diff --git a/frontend/packages/swarm-ui/test/agent-ssh.test.mjs b/frontend/packages/swarm-ui/test/agent-ssh.test.mjs new file mode 100644 index 000000000..76f64e281 --- /dev/null +++ b/frontend/packages/swarm-ui/test/agent-ssh.test.mjs @@ -0,0 +1,62 @@ +// An opened agent card's SSH row: the badge, the PUT body and the target +// snippets. Run by `npm test` with Node's type stripping. +import assert from "node:assert/strict"; +import { test } from "node:test"; +import { + authorizedKeysLine, + sshBody, + sshSummary, + targetSnippet, +} from "../src/agent/detail/ssh.ts"; + +const ca = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOHf\n"; + +test("the badge reads absent as off", () => { + assert.equal(sshSummary(undefined), "off"); + assert.equal(sshSummary(false), "off"); + assert.equal(sshSummary(true), "on"); +}); + +test("the PUT carries the stored permission list so it is not reset", () => { + assert.deepEqual(sshBody(undefined, true), { ssh: true }); + assert.deepEqual(sshBody(["meta"], false), { + permissions: ["meta"], + ssh: false, + }); + // Nothing else is sent: the internet and repository fields stay as stored. + assert.deepEqual(Object.keys(sshBody(["meta"], true)).sort(), [ + "permissions", + "ssh", + ]); +}); + +test("the authorized_keys line trusts the CA for one principal only", () => { + assert.equal( + authorizedKeysLine("atlas", ca), + 'cert-authority,principals="atlas" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOHf', + ); +}); + +test("each target form names the agent and the CA key, and keeps for the operator", () => { + for (const form of ["nixos", "home-manager", "ssh"]) { + const text = targetSnippet(form, "atlas", ca); + assert.ok(text.includes("ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOHf"), form); + assert.ok(text.includes("atlas"), form); + } + assert.ok(targetSnippet("nixos", "atlas", ca).includes("")); + assert.ok( + targetSnippet("nixos", "atlas", ca).includes( + 'authorizedPrincipals = [ "atlas" ]', + ), + ); + assert.ok(targetSnippet("nixos", "atlas", ca).includes("TrustedUserCAKeys")); + assert.ok( + targetSnippet("home-manager", "atlas", ca).includes( + 'home.file.".ssh/authorized_keys"', + ), + ); + // No trailing newline of the CA key leaks into a line. + assert.ok(!targetSnippet("ssh", "atlas", ca).includes("\n\n")); + // The control: another agent gets its own principal. + assert.ok(targetSnippet("ssh", "maia", ca).includes('principals="maia"')); +}); diff --git a/nix/host-modules/lib/ssh-agent-ca.nix b/nix/host-modules/lib/ssh-agent-ca.nix index a17bc30a8..565d40845 100644 --- a/nix/host-modules/lib/ssh-agent-ca.nix +++ b/nix/host-modules/lib/ssh-agent-ca.nix @@ -4,7 +4,7 @@ # derived from the certificate's lifetime. # # `mountPath` and `roleName` are also `swarm_secret_client::policy::SSH_MOUNT` -# and `SSH_ROLE`, which the shared agent policy names; the bao-grants module-eval +# and `SSH_ROLE`, which the SSH signing policy names; the bao-grants module-eval # suite reads that file and fails when the two disagree. # # Pure attrset, not a NixOS module. diff --git a/nix/target-modules/agent-ssh.nix b/nix/target-modules/agent-ssh.nix index 53e534866..72c79537a 100644 --- a/nix/target-modules/agent-ssh.nix +++ b/nix/target-modules/agent-ssh.nix @@ -9,9 +9,8 @@ # a certificate, the agent's name, so listing an agent here is what lets it in. # No `authorized_keys` entry is written or needed. Removing a name from # `principals` ends that agent's logins at the next attempt, whatever -# certificate it holds. The swarm has no switch that stops signing for an -# agent that is still declared; a certificate already signed expires within -# three hours. +# certificate it holds; a certificate already signed expires within three +# hours. The swarm UI's per-agent switch decides whether the swarm signs. # # The agent's side is ../agent-modules/ssh.nix. {