release: v0.3.0 — add shimkit ssh; ship three host-tools as 0.3.0

Final of three new tools for v0.3.0 (ports → hosts → ssh per
docs/plans/v0.3.0-new-tools.md). All three together:

- `shimkit ports` (commit 6cf38f4 + b43450c)
- `shimkit hosts` (commit 2b4c7bf)
- `shimkit ssh`   (this commit)

Each follows the same five architecture rules and the same MODERATE
prompt + SEVERE token pattern from the v0.2.x tools. None ships an
optional dependency extra; everything uses CommandRunner + stdlib.

ssh-specific:

- Surface: keys list/generate/rotate, agent status/add, known-hosts
  audit/prune, perms audit/fix, config show [HOST]. 11 leaf
  subcommands under 5 sub-groups.
- Passphrase isolation: keys generate calls `ssh-keygen` with
  capture_output=False so the passphrase prompt lands on the user's
  TTY. shimkit never sees, captures, or logs the passphrase.
- Permission audit is asymmetric: a path with a STRICTER mode than
  expected (e.g. 0400 private key vs 0600 expected) is fine. Only
  laxer modes are flagged.
- known_hosts duplicate-prune preserves comments + blank lines
  verbatim; first occurrence wins.
- Pure scanner module (`scanner.py`) is unit-testable without
  shelling out.
- Config: SshConfig + SshPermsConfig added to typed schema.
- `--ssh-dir PATH` flag on every subcommand for tests + chroot use.

Test count 252 → 295 (23 new). Gates: ruff clean, mypy strict
clean, bandit medium=0.

Cut as v0.3.0 (not 0.2.4) because the surface change is large —
three new public top-level subcommands.

Author: imanimanyara

CHANGELOG.md

@@ -6,8 +6,27 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-05-15
+
+Three new host-machine dev-workflow tools, each shipped under the
+existing five architecture rules (CommandRunner chokepoint, UI
+chokepoint, config-driven values, builder pattern, fluent self).
+Test count 252 → 295. No new optional dependency extras — all
+three use only baseline binaries that ship with the OS.
+
 ### Added
 
+- `shimkit ssh` — SSH key + agent + known_hosts + perms hygiene.
+  `keys list/generate/rotate`, `agent status/add`,
+  `known-hosts audit/prune`, `perms audit/fix`, `config show
+  [HOST]`. No third-party deps; passphrases stay in `ssh-keygen`'s
+  TTY prompt (never logged or captured). Permission matrix is
+  config-driven (`tools.ssh.perms`); audit flags only laxer-than-
+  expected modes — stricter modes pass. 23 tests covering scanner
+  units (list_keys / parse_agent_keys /
+  find_known_host_duplicates / audit_perms), every CLI subcommand,
+  dry-run no-op assertions, and the moderate-prompt refusal under
+  `--no-input`. [`docs/tools/ssh.md`](docs/tools/ssh.md).
 - `shimkit ports` — cross-platform TCP/UDP port owner inspector +
   killer. `shimkit ports show [PORT]` lists every listening socket
   via `lsof` on macOS or `ss` on Linux; `shimkit ports kill PORT`

README.md

@@ -47,6 +47,10 @@ behaviour: [`docs/installation.md`](docs/installation.md).
 - **[`shimkit hosts`](docs/tools/hosts.md)** — `/etc/hosts` editor
   with atomic-write + timestamped backups. add / remove / block /
   unblock / apply-list (severe) / rollback. macOS + Linux.
+- **[`shimkit ssh`](docs/tools/ssh.md)** — SSH key + agent +
+  known_hosts + perms hygiene. keys list/generate/rotate, agent
+  status/add, known-hosts audit/prune, perms audit/fix, config
+  show. No third-party deps; passphrases handled by ssh-keygen.
 
 Plus three utilities:
 

docs/tools/ssh.md

@@ -0,0 +1,159 @@
+# shimkit ssh
+
+SSH key + agent + known_hosts + perms hygiene. No third-party deps —
+every operation shells out to baseline `ssh-keygen`, `ssh-add`,
+`ssh-agent`, or `ssh`. Passphrases are never handled by shimkit:
+`ssh-keygen` prompts the user directly.
+
+Pure scanner logic lives in `src/shimkit/tools/ssh/scanner.py`
+(filesystem read + known_hosts parser + perms audit). The manager
+owns CommandRunner shell-outs.
+
+## Commands
+
+| Command                                          | Purpose                                                |
+|--------------------------------------------------|--------------------------------------------------------|
+| `shimkit ssh`                                    | Interactive menu (read-only paths only).               |
+| `shimkit ssh keys list`                          | List every recognised private key.                     |
+| `shimkit ssh keys generate NAME`                 | Generate a new key (MODERATE).                         |
+| `shimkit ssh keys rotate NAME`                   | Back up the old key + regenerate (MODERATE).           |
+| `shimkit ssh agent status`                       | Show ssh-agent state + loaded keys.                    |
+| `shimkit ssh agent add KEY`                      | Pass-through to `ssh-add`.                             |
+| `shimkit ssh known-hosts audit`                  | Find duplicate entries.                                |
+| `shimkit ssh known-hosts prune`                  | Remove later duplicates (MODERATE).                    |
+| `shimkit ssh perms audit`                        | Check ~/.ssh modes against the config matrix.          |
+| `shimkit ssh perms fix`                          | chmod every offender (MODERATE).                       |
+| `shimkit ssh config show [HOST]`                 | Print ~/.ssh/config; with HOST, expand via `ssh -G`.   |
+
+Universal flags (`--quiet`, `--verbose`, `--log-file`, `--no-color`,
+`--color`, `--no-input`) go before any subcommand. Per-command flags
+(`--dry-run`, `--yes`, `--force`, `--json`, `--ssh-dir`,
+`--type`, `--comment`) go after.
+
+## Keys
+
+```bash
+shimkit ssh keys list                                # list every recognised key
+shimkit ssh keys list --json                         # machine-readable
+
+shimkit ssh keys generate id_work --type ed25519 --yes
+shimkit ssh keys generate id_work -C work@example   # custom comment
+shimkit ssh keys generate id_work --dry-run         # show command without running
+
+shimkit ssh keys rotate id_ed25519 --yes            # backup + regenerate
+```
+
+`rotate` moves the old key to `<name>.bak-YYYYMMDDHHMMSS` and the old
+`.pub` alongside, then runs `ssh-keygen` for a fresh pair. You're
+responsible for syncing the new public key to your authorized_keys
+on each server — shimkit prints the steps but pushes nowhere.
+
+## ssh-agent
+
+```bash
+shimkit ssh agent status            # what's loaded
+shimkit ssh agent status --json     # parses cleanly
+shimkit ssh agent add ~/.ssh/id_ed25519
+```
+
+`status` differentiates "agent not running" (exit 1, warning) from
+"agent running, no keys" (exit 0, info).
+
+## known_hosts hygiene
+
+```bash
+shimkit ssh known-hosts audit --json
+shimkit ssh known-hosts prune --yes
+```
+
+`audit` reports any `(host, key_blob)` pair seen more than once.
+`prune` keeps the first occurrence and drops the rest; comments and
+blank lines are preserved verbatim.
+
+## Permission matrix
+
+`audit` flags any path whose mode is **laxer** than the configured
+expected mode. Stricter modes pass — a `0400` key is fine even though
+expected is `600`.
+
+Default matrix (`tools.ssh.perms`):
+
+| Path                       | Expected |
+|----------------------------|----------|
+| `~/.ssh` (the dir)         | `700`    |
+| Private keys               | `600`    |
+| `.pub` files               | `644`    |
+| `~/.ssh/config`            | `644`    |
+| `~/.ssh/known_hosts`       | `644`    |
+| `~/.ssh/authorized_keys`   | `644`    |
+
+```bash
+shimkit ssh perms audit --json     # report only
+shimkit ssh perms fix --yes        # chmod each offender
+shimkit ssh perms fix --dry-run    # what would change
+```
+
+## ~/.ssh/config
+
+```bash
+shimkit ssh config show              # print ~/.ssh/config verbatim
+shimkit ssh config show gh           # `ssh -G gh` — effective expansion
+```
+
+The effective-expansion form is useful when `Include`s + multiple
+`Host` blocks make it non-obvious what options actually apply.
+
+## Configuration
+
+```json
+{
+  "tools": {
+    "ssh": {
+      "ssh_dir": "~/.ssh",
+      "default_key_type": "ed25519",
+      "perms": {
+        "dir": "700",
+        "private_key": "600",
+        "public_key": "644",
+        "config": "644",
+        "known_hosts": "644",
+        "authorized_keys": "644"
+      }
+    }
+  }
+}
+```
+
+`--ssh-dir PATH` overrides `ssh_dir` for one invocation — used by
+tests, also useful for editing a chroot's keys from outside.
+
+## Exit codes
+
+| Code | Meaning                                                     |
+|-----:|-------------------------------------------------------------|
+| 0    | success / no-op                                             |
+| 1    | generic failure (overwrite refused, ssh-keygen non-zero, prompt cancelled, agent unreachable) |
+| 2    | Typer usage error                                           |
+| 69   | EX_UNAVAILABLE — wrong platform                             |
+| 130  | SIGINT                                                      |
+
+## Platform support
+
+| Platform | Status |
+|----------|--------|
+| macOS    | ✓ — OpenSSH 9.x ships with macOS; `ssh-keygen` / `ssh-add` baseline. |
+| Linux    | ✓ — `openssh-client` package, also baseline.                          |
+| WSL      | ✓ (Linux path).                                                       |
+| Windows  | ✗ — out of charter.                                                   |
+
+## Security notes
+
+- **Passphrases never pass through shimkit.** `ssh-keygen` reads them
+  interactively from the TTY; our `CommandRunner.run` call uses
+  `capture_output=False` for that step. Nothing involving the
+  passphrase is logged, captured, or echoed.
+- **No automatic key push.** `keys rotate` does *not* upload the new
+  public key anywhere. You sync `authorized_keys` on each server
+  yourself.
+- **`config show` is read-only.** `~/.ssh/config` is your domain;
+  shimkit reads it but doesn't write to it.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "shimkit"
-version = "0.2.3"
+version = "0.3.0"
 description = "A toolkit of developer utilities — Java version manager, shell upgrader, and more. Python tools, shimmed by bash."
 readme = "README.md"
 license = { file = "LICENSE" }

src/shimkit/__init__.py

@@ -3,5 +3,5 @@
 Python tools, shimmed by bash.
 """
 
-__version__ = "0.2.3"
+__version__ = "0.3.0"
 __all__ = ["__version__"]

src/shimkit/cli.py

@@ -21,6 +21,7 @@
 from shimkit.tools.java.commands import java_app
 from shimkit.tools.ports.commands import ports_app
 from shimkit.tools.shell.commands import shell_app
+from shimkit.tools.ssh.commands import ssh_app
 
 app = typer.Typer(
     name="shimkit",
@@ -38,6 +39,7 @@
 app.add_typer(docker_clean_app)
 app.add_typer(ports_app)
 app.add_typer(hosts_app)
+app.add_typer(ssh_app)
 
 
 # --- config -----------------------------------------------------------------

src/shimkit/config/defaults.json

@@ -120,6 +120,18 @@
       "apply_list_severe_token": "APPLY-LIST",
       "max_entries_per_apply": 5000,
       "managed_block_marker": "# === shimkit-managed ==="
+    },
+    "ssh": {
+      "ssh_dir": "~/.ssh",
+      "default_key_type": "ed25519",
+      "perms": {
+        "dir": "700",
+        "private_key": "600",
+        "public_key": "644",
+        "config": "644",
+        "known_hosts": "644",
+        "authorized_keys": "644"
+      }
     }
   },
   "package_managers": {

src/shimkit/config/schema.py

@@ -163,6 +163,25 @@ class PortsConfig(_StrictModel):
     system_pid_threshold: int = Field(default=100, ge=1, le=65535)
 
 
+class SshPermsConfig(_StrictModel):
+    """File-mode matrix for `shimkit ssh perms`."""
+
+    dir: str = "700"
+    private_key: str = "600"
+    public_key: str = "644"
+    config: str = "644"
+    known_hosts: str = "644"
+    authorized_keys: str = "644"
+
+
+class SshConfig(_StrictModel):
+    """SSH key + agent + perms hygiene — `shimkit ssh`."""
+
+    ssh_dir: str = "~/.ssh"
+    default_key_type: str = "ed25519"
+    perms: SshPermsConfig = Field(default_factory=SshPermsConfig)
+
+
 class HostsConfig(_StrictModel):
     """/etc/hosts editor — `shimkit hosts`."""
 
@@ -185,6 +204,7 @@ class ToolsConfig(_StrictModel):
     docker_clean: DockerCleanConfig = Field(default_factory=DockerCleanConfig)
     ports: PortsConfig = Field(default_factory=PortsConfig)
     hosts: HostsConfig = Field(default_factory=HostsConfig)
+    ssh: SshConfig = Field(default_factory=SshConfig)
 
 
 class PackageManagerEntry(_StrictModel):

src/shimkit/tools/ssh/__init__.py

@@ -0,0 +1,15 @@
+"""SSH key + agent + perms hygiene — ``shimkit ssh``.
+
+Generate / rotate keys, manage ``ssh-agent``, audit + prune
+``known_hosts``, audit + fix ``~/.ssh`` permissions, and read your
+``~/.ssh/config``. No third-party deps — every operation shells out
+to baseline ``ssh-keygen`` / ``ssh-add`` / ``ssh-agent`` /
+``ssh-keyscan``.
+"""
+
+from __future__ import annotations
+
+from .manager import SshManager
+from .models import AgentKey, KeyEntry, PermIssue
+
+__all__ = ["AgentKey", "KeyEntry", "PermIssue", "SshManager"]