swarm ui ssh row with target snippets, docs for the per-agent switch
This commit is contained in:
parent
624d5f24f8
commit
e621397252
12 changed files with 417 additions and 94 deletions
|
|
@ -1,44 +1,33 @@
|
||||||
# SSH access to a machine
|
# SSH access to a machine
|
||||||
|
|
||||||
Let an agent SSH into a machine you name, such as a test VM, without copying a
|
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
|
key onto it. The agent holds no standing SSH key. While you allow it, the agent
|
||||||
store for a certificate that lasts an hour, and the machine trusts the swarm's
|
gets a certificate from the swarm's SSH certificate authority (CA) that lasts
|
||||||
SSH certificate authority (CA) instead of a list of keys.
|
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.
|
1. **You switch SSH on for that agent**, in the swarm UI.
|
||||||
2. Make each machine trust the CA and list the agents allowed in.
|
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 already has an SSH client, a key it makes in memory, and a
|
||||||
every agent with a store identity can already get a certificate for its own
|
certificate unit. The switch alone decides whether the swarm signs.
|
||||||
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.
|
|
||||||
|
|
||||||
## 1. Switch it on for an agent
|
## 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
|
The agent then runs `ssh user@host`, with no other setup. It offers its
|
||||||
services.hyperhive.agent.ssh = {
|
certificate and nothing else.
|
||||||
enable = true;
|
|
||||||
hosts.testvm = {
|
|
||||||
hostName = "10.0.0.7";
|
|
||||||
user = "test";
|
|
||||||
port = 22; # the default
|
|
||||||
hostKey = "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA…";
|
|
||||||
};
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
`hostKey` is the machine's own host public key, the one line in
|
**Host keys use trust on first use.** The agent accepts the key a machine
|
||||||
`/etc/ssh/ssh_host_ed25519_key.pub` on it. The agent pins it: it refuses a
|
shows on the first connection, keeps it in its state directory (so it survives
|
||||||
machine that presents any other key, and never trusts a key on first sight.
|
restarts), and refuses a changed key afterwards. A swapped machine on the first
|
||||||
|
contact would go unnoticed. The row's explainer says so.
|
||||||
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.
|
|
||||||
|
|
||||||
This doesn't open the network. If you set the hive's `egress.forward` to
|
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
|
`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
|
## 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 `<user>` 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.<user>.openssh.authorizedPrincipals = [ "<agent>" ];`. The same
|
||||||
|
as one module: import `hyperhive.nixosModules.agent-ssh-target` and set
|
||||||
|
`services.hyperhive.agentSshTarget` (`enable`, `caPublicKey`,
|
||||||
|
`principals.<user>`).
|
||||||
|
- **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="<agent>" 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
|
```bash
|
||||||
bao read -field=public_key ssh-agents/config/ca
|
bao read -field=public_key ssh-agents/config/ca
|
||||||
```
|
```
|
||||||
|
|
||||||
The store also serves the same key without a token at
|
|
||||||
`<store address>/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.<user>` 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
|
## What an agent can and can't do
|
||||||
|
|
||||||
- It can only get a certificate for **its own name**. The store signs for the
|
- 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
|
## Revoking access
|
||||||
|
|
||||||
- **One agent from one machine:** remove its name from that user's
|
- **One agent from one machine:** remove its principal (the `authorizedPrincipals`
|
||||||
`principals` and deploy the machine. The next login attempt fails.
|
entry, or the `cert-authority` line) and deploy the machine. The next login
|
||||||
- **One agent from every machine:** remove its name from every machine's
|
attempt fails.
|
||||||
`principals`. That's the revocation. No swarm-wide switch
|
- **One agent from every machine:** untick the switch. The swarm stops signing
|
||||||
stops signing for an agent that a hive still declares: if you delete
|
for it within five minutes; an agent already signed in can still sign
|
||||||
its cert-auth role `hive-agent-<name>` in the store, `swarm-controller`
|
for up to an hour. Destroying the agent cuts its store identity off within
|
||||||
writes it back within five minutes. Signing stops only once no hive declares
|
minutes. Either way a certificate already signed stays valid until it
|
||||||
the agent any more (you destroyed it); the controller then stops renewing
|
expires, at most three hours, so removing the principal on a machine is what
|
||||||
its store identity, and the identity lapses with its 7-day certificate.
|
cuts it off there at once.
|
||||||
- **A certificate already issued** stays valid until it expires, at most three
|
- **The CA itself:** if the CA key changes, every machine needs the new public
|
||||||
hours, whatever you remove. Removing a principal blocks new logins at once.
|
key. Nothing replaces the CA by itself.
|
||||||
- **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
|
For the bao paths, field names and units, see
|
||||||
[the SSH CA implementation page](../../4-implementation/swarm/ssh-ca.md).
|
[the SSH CA implementation page](../../4-implementation/swarm/ssh-ca.md).
|
||||||
|
|
|
||||||
|
|
@ -38,7 +38,7 @@ the rest of the cell says how.
|
||||||
| `swarm/agents/<agent>/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/agents/<agent>/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/<hive>/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/hives/<hive>/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/<agent>/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 |
|
| `swarm/agents/<agent>/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/<hive>/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/<hive>/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/<hive>/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/hives/<hive>/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/<clientId>/oidc/client` | authelia | that service | must be stated | must be stated |
|
| `swarm/services/<clientId>/oidc/client` | authelia | that service | must be stated | must be stated |
|
||||||
|
|
|
||||||
|
|
@ -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
|
a glob, host certificates, other key types or another extension is a refusal
|
||||||
from the store.
|
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
|
The operator's switch is the `ssh` field of the agent's record in `agent-permissions`
|
||||||
stanza: `update` on `ssh-agents/sign/swarm-agent`, and nothing on the rest of
|
(`swarm_wire::agent_permissions`), set with `PUT /api/agents/{name}/permissions`
|
||||||
the mount. `swarm-controller` writes the policy at every start and at every
|
from the swarm UI's **ssh** row. Absent is off. A `PUT` or `DELETE` that leaves
|
||||||
agent mint, so a deploy that adds the stanza reaches existing agents when the
|
the field out keeps it.
|
||||||
controller restarts. A token already issued picks the change up on its next
|
|
||||||
request, because bao reads policies per request.
|
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-<name>` 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
|
## 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:
|
`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`,
|
- 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;
|
`key-cert.pub` beside it;
|
||||||
- each run logs in to the store with the cert identity `hive-agent-bao-identity`
|
- 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
|
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,
|
- the timer fires 20 minutes after each run, a third of the 60-minute lifetime,
|
||||||
from the same file as the role's TTL;
|
from the same file as the role's TTL;
|
||||||
- the generated `/etc/ssh/ssh_config` has one `Host <name>` block per entry
|
- the system `/etc/ssh/ssh_config` has one `Host *` block: `IdentityFile` and
|
||||||
(`HostName`, `User`, `Port`, `IdentityFile`, `CertificateFile`,
|
`CertificateFile` from `/run`, `IdentitiesOnly yes`,
|
||||||
`IdentitiesOnly yes`, `StrictHostKeyChecking yes`), and
|
`StrictHostKeyChecking accept-new`, and
|
||||||
`/etc/ssh/ssh_known_hosts` one pinned line per `hostKey` (`[host]:port` for a
|
`UserKnownHostsFile /agents/<name>/state/ssh_known_hosts`. The host binds the
|
||||||
port other than 22).
|
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
|
## The target module
|
||||||
|
|
||||||
|
|
@ -84,11 +113,8 @@ per-agent allowance for it yet.
|
||||||
|
|
||||||
## Revocation
|
## Revocation
|
||||||
|
|
||||||
Every agent shares the role, which holds nothing per agent, so there is no
|
Unticking the switch stops signing as described above. Destroying an agent
|
||||||
per-agent signing switch. `swarm-controller`'s renewal pass (`agent_renewal.rs`) re-mints
|
disables its identity entity and deletes its cert-auth role
|
||||||
the store identity, and writes the cert-auth role `hive-agent-<name>` back, for
|
(`agent_cutoff.rs`), after which its tokens stop working at once. A target's
|
||||||
every agent a hive still declares, so deleting the role doesn't stick. Nothing
|
principals list is the immediate control per machine. A certificate already
|
||||||
in the controller deletes the role when you destroy an agent; the renewal pass
|
signed stays valid for at most `max_ttl` (180 minutes).
|
||||||
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).
|
|
||||||
|
|
|
||||||
|
|
@ -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
|
to each agent. The controller tries an agent whose account the forge refuses again
|
||||||
every five minutes.
|
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
|
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`
|
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
|
restarts the agent after its current turn. The card reads
|
||||||
|
|
|
||||||
|
|
@ -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
|
out, a `DELETE`, and a re-create keep the stored value; the route refuses more
|
||||||
than 100.
|
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** —
|
**How a change applies** —
|
||||||
- The agent's harness reads its own key every 10 seconds and builds every
|
- 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
|
turn's `--tools`, `--allowedTools` and MCP config from the last value, so a
|
||||||
|
|
|
||||||
|
|
@ -22,6 +22,7 @@ import { AgentInference } from "./AgentInference.js";
|
||||||
import { StatusMessage } from "./StatusMessage.js";
|
import { StatusMessage } from "./StatusMessage.js";
|
||||||
import { AgentInstructions } from "./AgentInstructions.js";
|
import { AgentInstructions } from "./AgentInstructions.js";
|
||||||
import { AgentLimits } from "./AgentLimits.js";
|
import { AgentLimits } from "./AgentLimits.js";
|
||||||
|
import { AgentSsh } from "./AgentSsh.js";
|
||||||
import {
|
import {
|
||||||
AgentInternet,
|
AgentInternet,
|
||||||
AgentPermissions,
|
AgentPermissions,
|
||||||
|
|
@ -229,6 +230,8 @@ function GrantRows({ agent }: { agent: string }) {
|
||||||
<dd>
|
<dd>
|
||||||
{g.grant === null ? g.loading : <AgentRepos agent={agent} g={g} />}
|
{g.grant === null ? g.loading : <AgentRepos agent={agent} g={g} />}
|
||||||
</dd>
|
</dd>
|
||||||
|
<dt>ssh</dt>
|
||||||
|
<dd>{g.grant === null ? g.loading : <AgentSsh agent={agent} g={g} />}</dd>
|
||||||
<dt>permissions</dt>
|
<dt>permissions</dt>
|
||||||
<dd>
|
<dd>
|
||||||
{g.grant === null ? (
|
{g.grant === null ? (
|
||||||
|
|
|
||||||
|
|
@ -4,7 +4,7 @@
|
||||||
// changes.
|
// changes.
|
||||||
//
|
//
|
||||||
// Both read `GET /api/agents/{name}/permissions`, which answers the stored
|
// 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
|
// 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
|
// control offers the catalogue from `GET /api/permissions` as checkboxes and
|
||||||
// PUTs the ticked ones, a PUT replacing the stored value whole. A selection
|
// PUTs the ticked ones, a PUT replacing the stored value whole. A selection
|
||||||
|
|
@ -50,6 +50,7 @@ interface Grant {
|
||||||
unrestricted_internet?: boolean;
|
unrestricted_internet?: boolean;
|
||||||
internet_log?: boolean;
|
internet_log?: boolean;
|
||||||
max_repos?: number;
|
max_repos?: number;
|
||||||
|
ssh?: boolean;
|
||||||
}
|
}
|
||||||
|
|
||||||
// Mirrors swarm-controller's `Catalogue` (`GET /api/permissions`).
|
// Mirrors swarm-controller's `Catalogue` (`GET /api/permissions`).
|
||||||
|
|
|
||||||
156
frontend/packages/swarm-ui/src/agent/detail/AgentSsh.tsx
Normal file
156
frontend/packages/swarm-ui/src/agent/detail/AgentSsh.tsx
Normal file
|
|
@ -0,0 +1,156 @@
|
||||||
|
// <AgentSsh> — 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<TargetForm>("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<string | null>(null);
|
||||||
|
const [caError, setCaError] = useState<ProblemDetails | null>(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 (
|
||||||
|
<div class="ui-agent-limits">
|
||||||
|
<BadgePopover
|
||||||
|
label="ssh"
|
||||||
|
value={sshSummary(grant.ssh)}
|
||||||
|
tone={on ? "warning" : "neutral"}
|
||||||
|
title={`whether ${agent} may get SSH certificates from the swarm`}
|
||||||
|
popoverLabel={`${agent} SSH access`}
|
||||||
|
>
|
||||||
|
<p class="ui-badge-popover-help">
|
||||||
|
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.
|
||||||
|
</p>
|
||||||
|
<p class="ui-badge-popover-help" role="note">
|
||||||
|
{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.
|
||||||
|
</p>
|
||||||
|
<CheckboxField
|
||||||
|
id={`ssh-${agent}`}
|
||||||
|
label={`allow ${agent} to get SSH certificates`}
|
||||||
|
checked={on}
|
||||||
|
disabled={busy}
|
||||||
|
onChange={(next) =>
|
||||||
|
void send({
|
||||||
|
method: "PUT",
|
||||||
|
headers: { "content-type": "application/json" },
|
||||||
|
body: JSON.stringify(sshBody(grant.permissions, next)),
|
||||||
|
})
|
||||||
|
}
|
||||||
|
/>
|
||||||
|
{saveError ? (
|
||||||
|
<ApiErrorPanel
|
||||||
|
context="the SSH switch was not saved"
|
||||||
|
problem={saveError}
|
||||||
|
/>
|
||||||
|
) : null}
|
||||||
|
<details class="ui-agent-ssh-target">
|
||||||
|
<summary>on the target</summary>
|
||||||
|
{snippet === null ? (
|
||||||
|
caError ? (
|
||||||
|
<ApiErrorPanel
|
||||||
|
context="the swarm's SSH CA key is not available"
|
||||||
|
problem={caError}
|
||||||
|
/>
|
||||||
|
) : (
|
||||||
|
<Hint as="span" role="status">
|
||||||
|
loading…
|
||||||
|
</Hint>
|
||||||
|
)
|
||||||
|
) : (
|
||||||
|
<>
|
||||||
|
<p class="ui-badge-popover-help">
|
||||||
|
Put this on a machine {agent} should reach, with{" "}
|
||||||
|
<code><user></code> replaced by the account it logs in as.
|
||||||
|
The key is the swarm's CA, a public value.
|
||||||
|
</p>
|
||||||
|
<div role="tablist" aria-label="target kind">
|
||||||
|
{TARGET_FORMS.map(([f, label]) => (
|
||||||
|
<Badge
|
||||||
|
key={f}
|
||||||
|
variant={f === form ? "default" : "quiet"}
|
||||||
|
tone={f === form ? "accent" : "neutral"}
|
||||||
|
value={label}
|
||||||
|
onClick={() => setForm(f)}
|
||||||
|
/>
|
||||||
|
))}{" "}
|
||||||
|
<Button onClick={() => void copy()}>
|
||||||
|
{copied ? "copied" : "copy"}
|
||||||
|
</Button>
|
||||||
|
</div>
|
||||||
|
<Preformatted wrap maxHeight="14em">
|
||||||
|
{snippet}
|
||||||
|
</Preformatted>
|
||||||
|
</>
|
||||||
|
)}
|
||||||
|
</details>
|
||||||
|
</BadgePopover>
|
||||||
|
</div>
|
||||||
|
);
|
||||||
|
}
|
||||||
75
frontend/packages/swarm-ui/src/agent/detail/ssh.ts
Normal file
75
frontend/packages/swarm-ui/src/agent/detail/ssh.ts
Normal file
|
|
@ -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. `<user>` 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 <user>.`,
|
||||||
|
`environment.etc."ssh/hyperhive-agent-ssh-ca.pub".text = "${ca}\\n";`,
|
||||||
|
'services.openssh.settings.TrustedUserCAKeys = "/etc/ssh/hyperhive-agent-ssh-ca.pub";',
|
||||||
|
`users.users.<user>.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 ~<user>/.ssh/authorized_keys on the target\n${authorizedKeysLine(agent, ca)}`;
|
||||||
|
}
|
||||||
|
}
|
||||||
62
frontend/packages/swarm-ui/test/agent-ssh.test.mjs
Normal file
62
frontend/packages/swarm-ui/test/agent-ssh.test.mjs
Normal file
|
|
@ -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 <user> 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("<user>"));
|
||||||
|
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"'));
|
||||||
|
});
|
||||||
|
|
@ -4,7 +4,7 @@
|
||||||
# derived from the certificate's lifetime.
|
# derived from the certificate's lifetime.
|
||||||
#
|
#
|
||||||
# `mountPath` and `roleName` are also `swarm_secret_client::policy::SSH_MOUNT`
|
# `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.
|
# suite reads that file and fails when the two disagree.
|
||||||
#
|
#
|
||||||
# Pure attrset, not a NixOS module.
|
# Pure attrset, not a NixOS module.
|
||||||
|
|
|
||||||
|
|
@ -9,9 +9,8 @@
|
||||||
# a certificate, the agent's name, so listing an agent here is what lets it in.
|
# 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
|
# No `authorized_keys` entry is written or needed. Removing a name from
|
||||||
# `principals` ends that agent's logins at the next attempt, whatever
|
# `principals` ends that agent's logins at the next attempt, whatever
|
||||||
# certificate it holds. The swarm has no switch that stops signing for an
|
# certificate it holds; a certificate already signed expires within three
|
||||||
# agent that is still declared; a certificate already signed expires within
|
# hours. The swarm UI's per-agent switch decides whether the swarm signs.
|
||||||
# three hours.
|
|
||||||
#
|
#
|
||||||
# The agent's side is ../agent-modules/ssh.nix.
|
# The agent's side is ../agent-modules/ssh.nix.
|
||||||
{
|
{
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue