feat: add pure ssh2 remote operations

pi-ssh/extension-spec.md

@@ -0,0 +1,118 @@
+# pi-ssh extension specification
+
+## Goal
+
+Pi and its default tools remain local. Explicit collision-free tools perform selected operations on one configured remote server:
+
+- `ssh_read`
+- `ssh_write`
+- `ssh_edit`
+- `ssh_find`
+- `ssh_grep`
+- `ssh_bash`
+
+The extension is for operating servers from local projects, not for replacing Pi's local workspace. It never auto-loads remote project instructions.
+
+## Connection model
+
+Runtime communication uses Node `ssh2` only. OpenSSH is not spawned during Pi sessions. A user must explicitly import a concrete OpenSSH alias before connecting:
+
+```text
+ssh_config.sh import <alias>
+  → ssh -G <alias>
+  → user chooses private-key or password auth
+  → ssh2 obtains host key, user confirms fingerprint
+  → ssh2 verifies authentication
+  → encrypted vault is updated
+```
+
+The resulting host ID is the only runtime selector:
+
+```text
+/ssh <host-id>[:/absolute/path]
+pi --ssh <host-id>[:/absolute/path]
+```
+
+Arbitrary `user@host`, port overrides, ProxyJump, and ProxyCommand are not supported in the first pure-ssh2 version. Unsupported imported configuration is rejected rather than ignored.
+
+## Vault
+
+Default paths:
+
+```text
+${XDG_CONFIG_HOME:-$HOME/.config}/my-pi/pi-ssh/hosts.enc
+${XDG_CONFIG_HOME:-$HOME/.config}/my-pi/pi-ssh/vault.key
+```
+
+The directory is mode `700` and files are mode `600` on POSIX. A random adjacent 256-bit key encrypts and authenticates the complete validated configuration with AES-256-GCM. Each write uses a fresh IV and atomic replacement; plaintext is never written to a temporary file.
+
+The adjacent-key design prevents casual disclosure of `hosts.enc` alone but does not protect against code able to read both files as the same local user.
+
+The encrypted payload includes endpoint, authentication data, host groups, default cwd, and a pinned SHA256 host-key fingerprint. Private keys remain in their original paths; only their path and optional passphrase are stored.
+
+## Authentication
+
+Supported methods:
+
+- password;
+- single-password keyboard-interactive;
+- OpenSSH private key;
+- encrypted private key with passphrase.
+
+Passwords, passphrases, private-key contents, vault key, and decrypted configuration must never enter command arguments, logs, permission evidence, system prompts, or Pi session entries.
+
+## Host-key verification
+
+Import displays the observed host-key algorithm and SHA256 fingerprint for explicit confirmation. Runtime `hostVerifier` must compare the server key with the pinned fingerprint and fail closed on any mismatch. Key changes require explicit host update.
+
+## Transport
+
+One persistent `ssh2.Client` belongs to the active host. Connection loss fails closed and no operation is automatically replayed.
+
+### Shell
+
+`ssh_bash` and explicit user `!` commands open exec channels. Commands run through `bash -lc` after changing to the selected remote cwd. Output streams through the normal Pi Bash operations callback. Abort or timeout closes the channel without reconnecting or replaying.
+
+### Files
+
+SFTP implements file operations:
+
+- read and access checks;
+- recursive directory creation;
+- remote write through a temporary file;
+- atomic OpenSSH rename extension when available;
+- safe direct-write fallback when SFTP v3 cannot replace an existing target.
+
+Remote paths map from Pi's local factory cwd into the selected remote cwd, but permission-system access extractors prevent those paths from entering local path normalization.
+
+### Search
+
+Search tools execute one capability-adaptive, bounded shell pipeline inside the already approved tool call. They never install or upload binaries.
+
+- `ssh_find`: `fd` → `fdfind` → `git ls-files` → `find`; fixed filename/path substring semantics.
+- `ssh_grep`: `rg` → `git grep` → `find -exec grep`; literal case-insensitive semantics by default.
+- each backend emits at most `limit + 1` lines so truncation is explicit; public `limit` is 1–200; each returned line is capped.
+- relative paths resolve against remote cwd and `~/` against remote home.
+- user strings are single-quoted as shell arguments and NUL/newline input is rejected.
+- capability detection occurs only within the reviewed search call.
+- search output is normalized by `pi-ssh` and excluded from RTK compaction.
+
+Direct search commands remain denied through `ssh_bash`; structured search tools are the authoritative remote search surface.
+
+## Permission boundary
+
+There is one permission gate: `pi-permission-system`.
+
+- `ssh_read`, `ssh_write`, `ssh_edit`, `ssh_find`, and `ssh_grep` default to `ask`.
+- `ssh_bash` is a Bash-semantic `shellTools` alias with `decisionFloor: "ask"`.
+- Bash hard denies remain denies.
+- All asks enter the configured authorizer chain.
+- Permission service absence or bridge registration failure must not install a permissive fallback.
+
+Evidence includes configured host ID, endpoint, port, remote cwd, and a bounded operation summary, never credentials.
+
+## Session and UI
+
+The session stores only host ID, remote cwd, and remote home. Resume reloads current vault data and establishes a new ssh2 connection; failures fall back to local mode. `/ssh off` disposes the client and clears the status line.
+
+The system prompt states that default tools are local and `ssh_*` tools are remote. It does not include remote file content.