mosaicstack/stack
25
0
Fork 1
Code Issues 416 Pull Requests 13 Actions Packages Projects Releases 15 Wiki Activity

row 210 (#1707): DESIGN.md r1, agent host access with sudo through the credential store (Gizmoduck)

Browse Source
This commit is contained in:
jason.woltje
2026-10-20 15:30:28 -05:00
parent 9ba31b5b3f
commit 7b10bc0fff
1 changed files with 420 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
agents/gizmoduck/work/queue-210/DESIGN.md
+420
View File
@@ -0,0 +1,420 @@
# Row 210 (#424, Gitea #1707): agent host access with sudo through the credential store
Gizmoduck, 2026-10-20, r1. Design only, no code. Reviewer Duckworth, gate owner Sage. Due 2026-10-27 (Q184).
- Brief: `docs/plans/2026-10-20_host-credentials.md` at 9db578ff5.
- Base read: `origin/refactor` 9ba31b5b3. Row 199 read as DESIGN.md r6, 4d3007ec9 on `megavolt/row199`.
Row 199 has no code on origin yet, so every "199 gives" below cites its design, not code.
- PRD: REQ-CRED-3 in Honker's 1.7 draft (`agents/honker/work/queue-194/PRD-1.7-DRAFT.md:111-115`, 11cb0423b).
- Branch `gizmoduck/row210`. The row can't be claimed yet: `queue move 210 in-progress` refuses "waits on 199".
## 1. What the code does today
| # | Fact | Cite |
|---|---|---|
| E1 | The bus reads credentials for two kinds only, `gitea` and `vikunja` | `bus/src/credentials.mjs:22`, `business/src/vocabulary.mjs:103` |
| E2 | A credential value must match `^[-A-Za-z0-9._~]+\n?$`, at least 16 and at most 16384 bytes. An OpenSSH private key fails it at the first `-----BEGIN` space | `bus/src/credentials.mjs:84-87` |
| E3 | `assertClean` searches `JSON.stringify(result)` for each token. JSON escapes a newline, so a multi-line secret is never found: `JSON.stringify("a\nb").includes("a\nb")` is `false` (run on node here) | `bus/src/credentials.mjs:95-103` |
| E4 | `use()` turns any exception in the operation into `service-failed`, then runs `assertClean` | `bus/src/credentials.mjs:104-117` |
| E5 | Host to bus-child IPC is serial, one request at a time, with a 10 s timeout. A slow reply breaks the channel | `cli/src/host.mjs:31`, `:270` |
| E6 | The web verbs run in the bus child over `broker.sock`. `requestWeb` checks keys, runs `#secretCheck`, checks the grant `roles[s.role].web`, records `action.allowed` (requested), calls `onAdmit()` so the server raises the socket timeout, runs the service and records completion | `bus/src/broker.mjs:1492-1530`, `bus/src/server.mjs:87-95` |
| E7 | `roles[role].web` comes from the resolved tool limit. A role entry in the bus holds `authority`, `web` and `credentials` | `bus/src/business.mjs:17-20` |
| E8 | A business-file role entry takes `definition`, `holder`, `vars`, `tracker`, `credentials`. Anything else refuses at load | `business/src/business.mjs:89` |
| E9 | The chief's `organization.set` takes only `ORGANIZATION_KEYS`. The human-only `instances.set` takes `INSTANCE_KEYS` and refuses any definition that declares a credential (`organization-credentials-out-of-scope`). Holder, credentials and tracker stay hand edits | `bus/src/broker.mjs:145-147`, `:1248-1298`, `business/src/instance-settings.mjs:1-5`, `:22-31` |
| E10 | An action outside ROUTED is a hard wait and classifies `gated` for every role. No role file may grant one | `bus/src/broker.mjs:44-70`, `business/src/vocabulary.mjs:58-88`, PRD REQ-WAIT-2 and 3 |
| E11 | The seat sandbox does not confine the network, abstract Unix sockets or the host UID | `seat/src/sandbox.mjs:29-31` |
| E12 | The bus child spawns no process today. `child_process` appears only in the human and tester CLIs | `grep child_process packages/bus/src/*.mjs` |
| E13 | Role networks are `none`, `api-only`, `open`. The bundle carries the value, and the sandbox's own comment says the network is not confined (E11) | `business/src/vocabulary.mjs:101`, `harness/src/bundle.mjs:252` |
Row 199 (r6) gives: the store at `<configDir>/secrets/agents/<business>/<agent>/<kind>` (D1), the `{store: true}`
reference (D2), the read path (D3, D3a), `useFor(session, kind, op)` with the call-site allowlist test (D5),
the `publish` grant shape, a list on the role entry plus a hard-wait action whose decision binds the commit
(D9), and the human-only lifecycle verbs with `changes.jsonl` receipts (section 6).
## 2. Probe (throwaway keys, scratch sshd on 127.0.0.1:22410, OpenSSH 10.5p1)
Run in `/mnt/storage/scratch/gizmo-210-probe` with keys made for the probe and deleted after. No real key or
host was touched.
| Probe | Result |
|---|---|
| `ssh-add -` with the private key on stdin, to an agent on a private socket | works, "Identity added: (stdin)" |
| `IdentityAgent=<sock>` with `IdentitiesOnly=yes` and `IdentityFile=none` | refused, `Permission denied (publickey)`. With `IdentitiesOnly`, ssh offers only agent keys that match a configured identity |
| same with `IdentityFile=<the public key file>` | works, rc 0 |
| `-i /dev/fd/3` with the key on fd 3 | fails, "Identity file /dev/fd/3 not accessible". ssh closes inherited fds, so the fd route is out |
| a known_hosts file pinning the wrong key under `HostKeyAlias` with `StrictHostKeyChecking=yes` | refused, "Host key verification failed", rc 255 |
| `printf '%s|'` with `'a b'` and `'it'\''s'` single-quoted, plus an unquoted `$((1+1))` as a control | prints `a b|it's|2|`. The quoted elements arrive whole, and only the unquoted control expanded |
| remote `exit 7` | ssh exits 7 |
| killing the agent | its socket file is gone |
## 3. Decisions
### D1. The kind and its naming
One key per (agent, host). The kind name is `host.<hostId>`, so the store file is
`<configDir>/secrets/agents/<business>/<agent>/host.<hostId>` (199 D1, unchanged). `hostId` matches
`^[a-z0-9][a-z0-9-]{0,31}$`.
The closed kind set becomes `gitea`, `vikunja` and the family `host.<hostId>`. One exported helper,
`credentialKind(name)` in `vocabulary.mjs`, answers whether a name is a kind, and each place that checks
kinds calls it: `SERVICES` users (`role.mjs:105-118`), `bus/src/credentials.mjs:22`, the broker's service
check, the CLI `issue` date flag and 199's remove regex. A build test greps for literal `'gitea', 'vikunja'`
lists outside `vocabulary.mjs` and fails on a new one.
Why per host and not per agent. A key that leaks, or a host that is retired, is revoked for that host alone.
ops-01 installs one public key per host, and an `authorized_keys` line names one agent. The cost is more keys
for Jason to issue, one per grant.
A role definition declares the kind once as `{"service": "host"}` with no scopes. The business file binds the
concrete hosts (D3). A definition can't name a host, because hosts belong to one stack instance.
The date is `--rotate-by DATE`, as for gitea. An ssh key doesn't expire on its own, so `status()` reports
`rotation-due` or `valid`, the gitea branch.
### D2. The value check
`checkValue(kind, text)` replaces the one regex at `credentials.mjs:84`. For `gitea` and `vikunja` it is
today's check, unchanged. For `host.*` the value must be:
- PEM framed by `-----BEGIN OPENSSH PRIVATE KEY-----` and `-----END OPENSSH PRIVATE KEY-----`, LF line ends,
at most 16384 bytes (the existing cap).
- An `openssh-key-v1` blob with cipher `none`, kdf `none`, exactly one key, type `ssh-ed25519`. Parsed in
node with `Buffer`, no ssh-keygen call, so the check runs at bus start without a process.
- The two check integers equal, and the public key in the private section equals the one in the header.
Anything else refuses `credential-format`. An encrypted key refuses, because the bus has no way to ask for a
passphrase and `BatchMode=yes` would fail at use time instead of at load. The parsed public key is kept with
the entry so `status` and D7 can print its fingerprint without touching the private part.
### D3. The grant
Four layers. Each must hold, and the code checks all four on every call.
1. **Role definition, reviewed commit.** `roles/<def>.json` lists `{"service": "host"}` in `credentials`. That
is the "reviewed role change" in the brief. Once a PRD version routes `host.sudo` (section 5), the same
reviewed commit puts `host.sudo` in that definition's `authority.withinRole`.
2. **Host registry, business file, hand edit.** A new top-level key:
```
"hosts": { "<hostId>": { "address": "10.1.1.53", "port": 22, "user": "localadmin",
"hostKeys": ["ssh-ed25519 AAAA..."] } }
```
`address` is an IPv4 or IPv6 literal or a DNS name matching `^[a-z0-9]([a-z0-9.-]{0,251}[a-z0-9])?$`.
`port` is 1 to 65535. `user` matches `^[a-z_][a-z0-9_-]{0,31}$`. `hostKeys` is a non-empty list of
`ssh-ed25519`, `ecdsa-sha2-nistp256` or `ssh-rsa` public key lines, type and base64 only, no comment.
3. **Agent grant, business file, hand edit.** A new role-entry key beside 199's `publish`:
```
"hosts": { "<hostId>": { "commands": "any" | [["systemctl", "status"], ["journalctl", "-u"]] } }
```
Each `hostId` must be in the registry, and the role's definition must declare `host`. A role entry with
`hosts` whose definition lacks `host` refuses at load and names `roles.<agent>.hosts`. `commands` is the
command boundary (D6).
4. **The key.** `credentials["host.<hostId>"] = {"store": true, "rotateBy": DATE}` with the file present
(199 D2, D3a). A grant without an issued key refuses `credential-unavailable` at call time, as 199 does.
Who writes each layer is in section 4. Neither the chief nor any agent can reach layers 2 to 4: `hosts` is
outside `ORGANIZATION_KEYS` and `INSTANCE_KEYS` (E9), `instances.set` already refuses a definition that
declares credentials (E9), and 199's `issue` is human-only.
### D4. The action and the decision binding
`host.sudo` is a new action in ACTIONS and in neither ROUTED list. Until a PRD version routes it, it is a hard
wait and classifies `gated` for every role (E10). Each call then needs a decision the human resolved.
The decision binds one call, the way 199 D9 binds `pushCommit`. When the action is `host.sudo`, the
`decision.raise` event body gets `hostRun = {host, argvSha256, stdinSha256}`, from the raise's own args. The
question shown to the human ends with the host id and the argv, each element JSON-quoted, so Jason sees what
runs. `#authorityFor` refuses `decision-mismatch` when the call's host, argv hash or stdin hash differs, as
`holderRun` does at `broker.mjs:796`. A decision is spent once (`decision-consumed`).
After routing, a definition that lists `host.sudo` within-role runs without a decision, and `decision` is
optional for that class only. The grant layers in D3 still apply.
### D5. The executor: a `broker.sock` verb in the bus child
```
host.run {"host", "argv": [..], "stdin"?, "timeout"?, "decision"?}
-> {"exit", "signal", "stdout", "stderr", "truncated": {"stdout", "stderr"}, "ms"} or a refusal
```
It runs in the bus child, shaped like `requestWeb` (E6), not as a host IPC op. A sudo command can take
minutes and the host channel times out at 10 s and serves one request at a time (E5). The key is in the bus
child's memory already (199 D3), so no ticket has to cross to the CLI host. Row 199's publish needs a ticket
because git and the working repo live in the CLI host. ssh needs neither. If Megavolt's 199 BUILD.md
deviation moved the executor somewhere this conflicts with, I follow it and record the change. I haven't seen
it, since it isn't on origin.
Order of checks. Each refusal goes through `broker.refuse()` and logs `action.refused`.
1. `keys(args)`, then `#secretCheck(args)`, then identity from the cap.
2. `host` is in the registry (`host-unknown`).
3. `host` is in `roles[s.role].hosts` (`host-not-granted`). This is the REQ-CRED-3 check "a grant exists for
that agent and that host".
4. `argv` shape (D6) and `commands` match (`command-not-granted`).
5. `#checkAuthority(s, "host.sudo", {decision, target: host, context})` (D4).
6. Record `action.allowed` phase `requested` with host, argv hash, stdin size and hash. Then `onAdmit()`, which
sets the socket timeout to the call's timeout plus 10 s, as the web branch does (`server.mjs:95`).
7. `credentials.useFor(s, "host." + host, run)`, where `run` is D7.
8. D8's leak check on the output, then `#secretCheck` on the result.
9. Record phase `completed` with exit, signal, ms, and size and sha256 of stdout and stderr. The output itself
never goes into an event. A failure records `host-failed` with the same fields.
Only one `host.run` per (agent, host) runs at a time. A second refuses `host-busy`. That keeps a stuck call
from piling up ssh processes and makes revoke (D9) simple.
This is the first process the bus child spawns (E12). The spawn uses `spawn` with an argv array, never a
shell, `detached: true` for its own process group, and `env` set to `{PATH: "/usr/bin:/bin"}` only.
### D6. The command boundary
`argv` is an array of 1 to 256 strings. Each is 1 to 4096 bytes of UTF-8 with no NUL, and the total is at most
32768 bytes. `argv[0]` must not contain `/` unless it starts with `/`. `stdin` is optional, a string of at most
65536 bytes, and goes through `#secretCheck` with the args.
The remote command is built by the bus, never taken as a string:
```
sudo -n -- 'argv0' 'argv1' ...
```
Each element is POSIX single-quoted: wrap in `'`, and replace each `'` with `'\''`. The probe shows the
remote shell gets each element back exactly (section 2). `sudo -n` fails instead of prompting, so a host
without NOPASSWD returns sudo's error, not a hang. The host's login shell for `user` must be POSIX. That is a
host precondition for ops-01, listed in section 7.
`commands` in the grant:
- `"any"`: every argv passes. This is root on the host.
- a list of argv prefixes: an argv passes when its first N elements equal some prefix of length N, element
by element, no globbing. `[["systemctl", "status"]]` admits `systemctl status nginx` and refuses
`systemctl restart nginx`.
I recommend Jason uses prefix lists where the job is known and `"any"` only for an agent he'd trust with root
on that host. A prefix list limits mistakes, not a determined agent. Many commands can start a shell or an editor as
root, `systemctl edit` for one. Section 6 says
plainly what `"any"` gives away.
Output: stdout and stderr each capped at 1 MiB. Past the cap the bus keeps reading and drops the rest so the
remote side doesn't block, and sets `truncated`. `timeout` defaults to 60 s, maximum 900 s. At the timeout
the bus sends SIGTERM to the ssh process group, then SIGKILL after 5 s, and answers `signal`. ssh's own exit
code 255 and a remote command exiting 255 can't be told apart. The result returns stderr so the agent can see
which, and the doc says so.
### D7. Handing the key to ssh
Per call, inside `useFor`'s operation:
1. `mkdtemp` a dir under `<configDir>/secrets/run/` with mode 0700. `<configDir>` is never bound into a sandbox
(199 D3). The socket path is checked against the 107-byte Unix socket limit before use, refusing
`host-failed` if over.
2. Write two files in it, mode 0600: `known_hosts` with one line per pinned key, `mosaic-host-<hostId> <type>
<base64>`, and `id.pub` with the entry's public key (D2).
3. Start `ssh-agent -D -a <dir>/a.sock` as a child in the same process group, wait for the socket, then run
`ssh-add -` with `SSH_AUTH_SOCK` set and the private key written to its stdin. The key never touches disk,
argv or env.
4. Run ssh with exactly these options and nothing from any config file:
```
ssh -F /dev/null -T -p <port>
-o BatchMode=yes -o IdentitiesOnly=yes -o IdentityFile=<dir>/id.pub -o IdentityAgent=<dir>/a.sock
-o StrictHostKeyChecking=yes -o UserKnownHostsFile=<dir>/known_hosts -o GlobalKnownHostsFile=/dev/null
-o HostKeyAlias=mosaic-host-<hostId> -o UpdateHostKeys=no -o CheckHostIP=no -o VerifyHostKeyDNS=no
-o ForwardAgent=no -o ForwardX11=no -o ClearAllForwardings=yes -o PermitLocalCommand=no
-o ProxyCommand=none -o ProxyJump=none -o ControlMaster=no -o ControlPath=none
-o ConnectTimeout=10 -o ServerAliveInterval=15 -o ServerAliveCountMax=3
<user>@<address> -- <remote command from D6>
```
`-F /dev/null` stops `~/.ssh/config` from adding a ProxyCommand, a different key or forwarding. The pin is
`StrictHostKeyChecking=yes` against a file the bus wrote from the registry, so there is no trust on first
use: an unknown or changed host key refuses with rc 255 (probe, section 2) and the bus answers
`host-key-mismatch` when stderr has "Host key verification failed".
5. In a `finally`: kill the agent, kill any ssh still running, remove the dir. A test asserts the dir is gone
after success, refusal, timeout and an exception thrown inside the operation.
The 0600 temp key file route the brief allows is not used. The agent route keeps the private key off disk,
and the fd route doesn't work (probe).
### D8. The leak check
`assertClean` misses a multi-line key (E3). For a `host.*` entry, `useFor` checks the result with
`assertCleanKey(result, entry)`, which searches the JSON text for:
- each base64 body line of the PEM of 24 characters or more,
- the whole body with line breaks removed,
- the 32-byte ed25519 private seed as lowercase hex and as base64 at each of the three byte offsets.
A match refuses `credential-leak`. The output is dropped, and the event records only sizes and hashes. The
existing `assertClean` still runs for the token kinds. The same function runs on `stdin` before the call, so
an agent can't round-trip a key it somehow has back through the host.
### D9. Lifecycle
199's verbs carry over with `KIND = host.<hostId>`. Two additions:
- `issue AGENT host.<id>` checks D2, then prints the public key line and a suggested `authorized_keys` line
for ops-01: `from="<stack host address>",restrict <type> <base64> mosaic-<business>-<agent>-<id>`. It
prints only public material.
- `revoke` also kills a `host.run` in flight for that agent and host (process group SIGKILL) before it drops
the key. The call answers `credential-unavailable`. Remote processes that the killed ssh started may keep
running (section 6).
`status` shows each host entry with its fingerprint (SHA256 of the public key), the rotate date and state.
The tester gets `status` and `revoke` only, as in 199.
### D10. Where the files change
| File | Change |
|---|---|
| `business/src/vocabulary.mjs` | `host.sudo` in ACTIONS, `credentialKind`, host id pattern |
| `business/src/business.mjs` | top-level `hosts` registry, role-entry `hosts`, load checks from D3 |
| `business/src/role.mjs` | `{"service": "host"}` in `checkCredentials` with no scopes |
| `business/src/credentials.mjs` | `host.*` refs take `rotateBy` |
| `bus/src/credentials.mjs` | kind check via `credentialKind`, `checkValue` (D2), `assertCleanKey` (D8), busy and kill map |
| `bus/src/host-run.mjs` (new) | D6 argv and quoting, D7 ssh-agent and ssh spawn, cleanup |
| `bus/src/broker.mjs` | `host.run` verb (D5), `host.sudo` in `#authorityFor` with `hostRun` (D4) |
| `bus/src/server.mjs` | `host.run` branch beside the web branch with `onAdmit` |
| `bus/src/business.mjs` | carry `hosts` onto the bus role entry |
| `harness` tool list | a `host_run` tool for roles whose bus entry has hosts, wired the way the web tools are (`harness/src/bundle.mjs:20-32`) |
| `cli` | 199's `credentials issue` accepts `host.<id>`, prints D9's lines |
Row 199's own kind and regex are not changed inside row 199. This row rebases onto 199's landing and changes
them here.
## 4. Who grants (brief item, "yours to propose with reasons")
Proposal: **Jason, at every layer that widens access. No agent, chief included, and not the tester.**
| Layer | Who | How | Why |
|---|---|---|---|
| Definition declares `host` (and later lists `host.sudo`) | Jason | reviewed commit to `roles/*.json`, as for any role authority (AGENTS.md invariant 7) | It decides which kinds of agent may ever hold a host key. Review puts a second seat on it |
| Host registry and pins | Jason, with ops-01's key fingerprints | hand edit of the business file | The pin is the host identity. A wrong pin is a man-in-the-middle on root. It must come from the host side, not from a first connection |
| Agent grant `roles.<agent>.hosts` | Jason | hand edit of the business file | Q183: "not all agents will need to have that access". The per-agent, per-host choice is his |
| Key `issue` | Jason | 199's human-only `issue` | The key passes through the caller. The tester is an agent (199 section 6, duckworth N1) |
| `authorized_keys` on the host | ops-01 | host side, from the line `issue` prints | ops-01 owns the hosts (brief) |
| Revoke | Jason, Mos, or the tester | `revoke` | Taking access away should be quick and needs no new trust |
Why not a reviewed commit for the agent grant too. The business file lives in `<configDir>`, outside the
repository (AGENTS.md invariant 2), and per-instance grants already stay hand edits there (E9, 199 D9 step 2).
Moving grants into the repo would put host addresses and the per-instance roster under review, which is a
bigger change than this row. The definition layer is the reviewed one.
Why not the chief. A chief with this power could hire an agent and grant it root. 199 already keeps hires
uncredentialed (199 D13). `instances.set` refuses credentialed definitions today (E9), and this row keeps it
that way.
REQ-CRED-3 says the who-grants answer is set by this design and approved by Jason. The table above is that
answer.
## 5. The routing gap
PRD 1.7 (draft r2) routes `role.hire`, `role.fire` and `git.push.remote`. It does not route `host.sudo`. Under
REQ-WAIT-3 the action lands as a hard wait, so each `host.run` needs a decision Jason resolves, bound to that
host and argv (D4). That is safe but probably not what Q183 asks for ("allow agents to perform their jobs").
Q-S1 for Sage: can `host.sudo` routing go into 1.7 beside REQ-CRED-3, or does it wait for 1.8? The code is the
same either way. Routing is one reviewed commit adding it to both ROUTED lists and to the chosen definitions'
`withinRole`, as 199 plans for `git.push.remote`.
The brief also says this row lands only after the PRD version holding REQ-CRED-3 is approved.
## 6. Limits, said plainly
- **`"any"` is root, and root can outlive the grant.** The seat sandbox doesn't confine the network (E11).
An agent with `"any"` on a host can add its own key to `authorized_keys` there, then ssh straight from its
sandbox, around the bus, the events and revoke. Prefix lists make that harder, not impossible. Only a
sandbox that confines the network closes it, and that is not this row. So a grant of `"any"` should go only
to an agent Jason would trust with root on that host, and ops-01's host-side audit (sudo log,
`authorized_keys` changes) is the check after the fact.
- **Revoke stops the stack's path, not remote processes.** Killing ssh may leave a remote process running.
`-T` gives no tty, so there is no SIGHUP from a closing terminal.
- **Same OS user.** Anything running as the stack's OS user outside a sandbox can read the key file, as 199 D6
says for every kind.
- **Exit 255** is ssh's failure code and also a remote exit code (D6).
- **The pin trusts the registry.** Whoever writes the business file controls which host key is trusted. That
is Jason (section 4).
## 7. Host preconditions (ops-01, not this row)
- `user` has NOPASSWD sudo and a POSIX login shell. `sudo` has no `requiretty` for that user.
- The agent's key is in `authorized_keys` with `from="<stack host>",restrict`.
- The host's public keys are handed to Jason for the registry.
## 8. Tests
All tests use a scratch sshd on 127.0.0.1 started by the test, with keys made by the test, and a fake `sudo`
on the test user's PATH that prints its argv as JSON and runs nothing as root. The sshd config sets
`AuthorizedKeysFile` and `HostKey` in the test's `mkdtemp` dir. A helper skips the ssh tests with a visible
reason only when `/usr/bin/sshd` is missing, and the gate fails if any of them skipped. No test reaches
another host.
| # | Test | Refusal or result |
|---|---|---|
| T1 | business load: `hosts` registry field checks, bad address, port, user, empty `hostKeys`, a key line with a comment | load refuses, names the key path |
| T2 | role entry `hosts` naming an unknown host, or on a definition without `host` | load refuses `roles.<agent>.hosts` |
| T3 | `organization.set` and `instances.set` with `hosts` in args | `invalid-request`, and the file is unchanged |
| T4 | value check: a valid unencrypted ed25519 key loads. An encrypted key, an RSA key, two keys, CRLF, a gitea token in a `host.*` slot, and a PEM in a `gitea` slot each refuse | `credential-format` |
| T5 | `host.run` with an unknown host | `host-unknown` |
| T6 | `host.run` on a host not in the caller's grant, including a host granted to another agent | `host-not-granted` |
| T7 | argv shape: empty, a NUL, too long, too many, a relative path with `/`, non-string | `invalid-request` |
| T8 | prefix list: a matching argv runs, a longer argv runs, a shorter one and a differing element refuse | `command-not-granted` |
| T9 | before routing: no decision refuses, a decision for another argv, another host or another stdin refuses, a spent one refuses | `gated`, `decision-mismatch`, `decision-consumed` |
| T10 | quoting: argv with spaces, quotes, `$()`, backticks, `;`, newline and glob characters reaches fake sudo unchanged | fake sudo's JSON equals argv |
| T11 | the remote command starts `sudo -n --` | fake sudo sees `-n` and `--` first |
| T12 | exit code and signal pass through, timeout kills the process group and answers `signal` | result fields |
| T13 | output cap: 2 MiB of stdout returns 1 MiB and `truncated.stdout: true`, and the call doesn't hang | result fields |
| T14 | host key pin: the sshd presents a key not in `hostKeys` | `host-key-mismatch`, and no command ran (fake sudo's marker file absent) |
| T15 | a registry with the right key passes on a fresh dir with no `~/.ssh/known_hosts` in HOME. A HOME with a `~/.ssh/config` setting a ProxyCommand doesn't change the call | runs, and the proxy marker is absent |
| T16 | leak: the fake sudo prints the private key file (multi-line), and in a second case prints only one body line, and in a third the seed in hex | `credential-leak`, the event has no output |
| T17 | `stdin` containing a body line of the key | `credential-leak` before any spawn |
| T18 | cleanup: after success, refusal, timeout and a thrown error, the run dir is gone and no `ssh-agent` or `ssh` with that dir in argv survives | dir absent, pgrep empty |
| T19 | the private key never appears in the argv or env of any spawned process (read from `/proc/<pid>/cmdline` and `environ` while the fake sudo sleeps) | absent |
| T20 | second concurrent call for the same agent and host | `host-busy` |
| T21 | revoke during a sleeping call kills it, and the next call refuses | `credential-unavailable` |
| T22 | events: `action.allowed` requested and completed carry sizes and hashes, never stdout, stderr, stdin or the key | event bodies |
| T23 | `issue` of a `host.*` kind prints the public line and the `authorized_keys` suggestion and never the private key | stdout and stderr checked |
| T24 | build grep: no literal `'gitea', 'vikunja'` kind list outside `vocabulary.mjs`, and 199's `credentials.use(` allowlist unchanged | grep |
| T25 | no role file in `roles/` lists `host.sudo` while it is a hard wait (REQ-WAIT-2) | grep |
## 9. Mutants
One per refusal, plus the two the brief names. Each must be killed.
| # | Mutant | Killed by |
|---|---|---|
| M1 | registry check skipped | T5 |
| M2 | agent grant check skipped | T6 |
| M3 | grant check reads any agent's `hosts` | T6 |
| M4 | each argv shape check removed, one mutant each (5) | T7 |
| M5 | prefix match compares only `argv[0]` | T8 |
| M6 | `"any"` assumed for a list grant | T8 |
| M7 | `#checkAuthority` call removed | T9 |
| M8 | `hostRun` argv hash not compared | T9 |
| M9 | `hostRun` stdin hash not compared | T9 |
| M10 | quoting drops the `'\''` replacement | T10 |
| M11 | `sudo -n` loses `-n` | T11 |
| M12 | **host key pin skipped**: `StrictHostKeyChecking=accept-new` | T14 |
| M13 | **pin skipped another way**: `UserKnownHostsFile` set to the user's default | T14, T15 |
| M14 | `-F /dev/null` removed | T15 |
| M15 | **key leaks into output**: `assertCleanKey` not called | T16 |
| M16 | leak check uses only the joined body | T16 (one-line case) |
| M17 | stdin leak check removed | T17 |
| M18 | `finally` cleanup removed | T18 |
| M19 | key passed with `-i` from a temp file left on disk | T18, T19 |
| M20 | output cap removed | T13 |
| M21 | timeout kill removed | T12 |
| M22 | busy check removed | T20 |
| M23 | revoke doesn't kill the in-flight call | T21 |
| M24 | event records stdout | T22 |
| M25 | each value check removed, one mutant each (encrypted, type, count, CRLF) | T4 |
| M26 | `organization.set` accepts `hosts` | T3 |
| M27 | load check for a definition without `host` removed | T2 |
The mutant script follows row 201's shape: copy the packages to scratch, anchor each mutant once, run each
test file in its own process group with a timeout, control first, exit 1 on any survivor. It runs on Sage's
slot.
## 10. Questions
- **Q-S1 (Sage):** routing for `host.sudo` in 1.7 or 1.8 (section 5).
- **Q-S2 (Sage, for Megavolt):** does 199's BUILD.md deviation move credential use out of the bus child? D5
assumes the key stays there.
- **Q-J1 (Jason, through Mos, at the live window):** the first grants, per agent and host, `"any"` or a prefix
list. Not needed for the build.