# ssh-client

The operator account's `~/.ssh` as a module (novox/hq research 027/03, ADR 0182; to-be 42 phase 1,
item 9). `sshd` is the machine's side.

## What it declares, by ADR 0182's classes

| path | class | how |
|---|---|---|
| `~/.ssh/` | owned | directory, the account's, mode 0700 |
| `~/.ssh/config.d/` | owned | directory, the account's, mode 0700. This is ssh's own drop-in directory: another module that needs a host (a forge, a work bastion) places its own file here |
| `~/.ssh/config.d/00-mesh` | owned | a Host block per other machine of the mesh (a roster fact), regenerated whenever a machine joins, leaves or is renamed. It begins with the mesh's header |
| `~/.ssh/config` | written into, **at the start** | the mesh's region, `# BEGIN mesh ssh-client.config` … `# END …`. It holds one `Include ~/.ssh/config.d/*`. Every line below the region is the operator's, kept byte for byte |
| `~/.ssh/authorized_keys` | found | see *The gap* |
| `~/.ssh/known_hosts` | found | see *The gap* |
| private keys | found | never read, never written. `ssh_client_keys` and `ssh_client_check` read a file's first line to recognise a key, and ask `ssh-keygen` about it |

### Why an include, not Host blocks in the region

ssh takes the first value it finds for each option. Research 027/03 asks that the mesh's hosts come
before anything else in `~/.ssh/config`. Before this change, the region was written at the end: a
predecessor's hosts above it won, for the same machines.

A roster fact cannot be placed at the start. The controller gives facts no `at`, and the host leaves
an existing region where it is. So the region at the start holds only the include, and the hosts
are a whole file in `config.d` that the include reads first. `00-` sorts it before any other drop-in.

ssh restores the including file's section after an `Include` (OpenSSH `readconf.c`). So an operator
line just below the region is global again, as it was at the top of the file. This module's tests
parse the declared region and check it, and `ssh -G` was compared before and after on every machine.

The old region, `ssh-client.fact-ssh-config` at the end of `~/.ssh/config`, is no longer declared, so
the host removes it, and only it, at the first push.

## The gap: authorized keys and known hosts

Research 027/03 gives the mesh a region in `authorized_keys` (the operator's keys as the mesh records
them) and one in `known_hosts` (every machine's host key). **The controller holds neither fact.**

- A roster template sees each machine's name, mesh name, address and account, and nothing else
  (mesh-controller `roster.go`).
- No machine fact carries an ssh host key.
- The only key the controller knows for the operator is a sealing key for secrets, not an ssh key.

So both files stay *found*, and this module invents nothing.

**What would close it:**

1. The host reports its machine's public host keys in its profile, and the roster gains a field for
   them.
2. The operator's public keys become a mesh record: per account, with a comment saying whose and
   where.

Each region is then one more `into: block` resource here. Until then, `ssh_client_check` reads the
files as they are, and `ssh_client_revoke` / `ssh_client_known_host` act on them by hand.

## The one-off clean-up (ADR 0182: the operator removes a predecessor's output, once)

The mesh removes nothing it did not make. After the first push, a machine that had the predecessor's
layout still holds:

1. **The predecessor's `~/.ssh/config.d/mesh`.** Its hosts repeat the mesh's, with the same values,
   plus one forge host that no module carries yet. Move that host to your own part of
   `~/.ssh/config`, or to a work module's drop-in, then delete the file.
2. **The predecessor's header at the top of `~/.ssh/config`**, now just below the mesh's region: the
   comment beginning *"Mesh Host blocks are GENERATED"* and its `Include ~/.ssh/config.d/mesh` line.
3. **A predecessor's block of mesh hosts marked *managed by sshd***, on the machines that still have
   one.
4. **Backups beside the live files** (`config.bak-*`, `known_hosts.old`, `removed-*`). `ssh_client_check`
   lists them as debris.

Until you do, `ssh_client_hosts` and `ssh_client_check` list the repeated hosts as duplicates. The
mesh's still win, because they are read first.

## Tools

They run as the operator account and never escalate. No answer carries a key: fingerprints only.

| tool | | what |
|---|---|---|
| `ssh_client_hosts` | r | every Host and Match section in the order ssh reads it, each with file, line and source (`mesh`, `drop-in`, `operator`); duplicates; what is set outside any section |
| `ssh_client_resolve` | r | `ssh -G` for one host: what ssh would use, and which sections matched |
| `ssh_client_check` | r | modes of the directory and every file; keys with no passphrase (`ssh-keygen -y -P ""`, output used only to compare with the `.pub`), weak, old, unused, or whose `.pub` is another key's; one key under several names; the mesh's region first with its include; duplicate hosts; `known_hosts` for the mesh's machines, missing or stale (scanned live, 5 s each in parallel, unless `scan` is false); authorized keys without a comment; debris. It says what it did not check |
| `ssh_client_keys` | r | every private key, by its public half: type, size, fingerprint, comment, mode, age, passphrase, whether ssh offers it by itself |
| `ssh_client_authorized` | r | `authorized_keys` by fingerprint, type, size, comment and options |
| `ssh_client_revoke` | a | removes every line with one fingerprint, keeping the file first as `authorized_keys.revoked-<time>`. It refuses the last key (a lockout) and a key in a mesh region (a push would write it back) |
| `ssh_client_known_host` | r/a | known entries against what the host offers now: `matches`, `changed`, `not known` or `unreachable`. With `refresh`, it replaces the host's entries through `ssh-keygen -R` (which keeps `known_hosts.old`) with what was scanned. That trusts whatever answers |
| `ssh_client_test` | r | one batch-mode connection that runs only `true`: the address reached, the method and key that authenticated, or why not and which keys were offered. A key with a passphrase works only through an agent. The runtime has none in its environment, so the tool looks for the account's agent socket under `/run/user/<uid>` and names the one it used, or says there was none |

## Tests

```
go test ./...
```

The tests use a temporary home and a fake runner, with public keys made for the tests only. They cover:

- reading order and source across includes, with an operator line after the include being global
  again;
- the declared region parsed as ssh reads it;
- duplicates;
- keys: fingerprints computed as `ssh-keygen -l` does, RSA size, passphrase asked and never prompted,
  a mismatched `.pub`;
- `authorized` never printing a key;
- `revoke`: the backup, the mode kept, a lockout refused, a mesh region refused;
- `known_host` matching, changed and refreshed, and an unreachable host never refreshed;
- `test`: success, and failure with the agent named;
- `check`'s findings;
- that the tools served are the manifest's `tools`.