my-pi/pi-ssh/README.md

# pi-ssh

`pi-ssh` keeps Pi and its local tools on the local machine while exposing explicit remote tools over a persistent Node `ssh2` connection:

- `ssh_read`
- `ssh_write`
- `ssh_edit`
- `ssh_find`
- `ssh_grep`
- `ssh_bash`

The extension does not override Pi's local `read`, `write`, `edit`, `find`, `grep`, or `bash` tools.

## Architecture

Runtime connections are pure `ssh2`; the extension does not spawn OpenSSH and does not require `sshpass`, `ControlMaster`, or passwordless login. Remote file operations use SFTP and remote shell commands use an SSH exec channel.

Hosts must be explicitly imported before use. OpenSSH remains only an import source: the configuration helper runs `ssh -G <alias>` once to resolve the selected alias, then stores the resulting endpoint and authentication data in the pi-ssh vault. Later changes to `~/.ssh/config` require re-importing the host.

ProxyJump and ProxyCommand are intentionally rejected in the first ssh2 release.

## Configure hosts

From the installed bundle or this repository:

```sh
./ssh_config.sh import
./ssh_config.sh import packaging-server
```

The helper:

1. lets you select concrete aliases from `~/.ssh/config`;
2. uses `ssh -G` to resolve HostName, User, Port, and IdentityFile;
3. asks whether the selected host uses a private key or password;
4. asks for a private-key passphrase when needed;
5. obtains and displays the server's SHA256 host-key fingerprint;
6. connects with `ssh2` to verify authentication;
7. optionally assigns a display label and group;
8. writes the encrypted vault.

Other commands:

```sh
./ssh_config.sh list
./ssh_config.sh update packaging-server
./ssh_config.sh remove packaging-server
./ssh_config.sh rotate-key
```

Secret prompts require an interactive terminal. Passwords and passphrases are never passed as command-line arguments.

## Vault

The default paths are:

```text
${XDG_CONFIG_HOME:-$HOME/.config}/my-pi/pi-ssh/
├── hosts.enc
└── vault.key
```

On POSIX systems the directory is mode `700` and both files are mode `600`. `hosts.enc` is encrypted and authenticated with AES-256-GCM; `vault.key` contains the adjacent random 256-bit key. Writes use a fresh IV and an atomic temporary-file rename. Plaintext configuration is never written to a temporary file.

This is deliberately a **casual-disclosure boundary**, not protection against compromise of the local account: anyone who can read both files can decrypt the vault. Encryption prevents the host configuration and passwords from being exposed by accidentally viewing or copying `hosts.enc` alone.

The encrypted payload contains host endpoints, pinned host-key fingerprints, groups, and either:

- a private-key path plus optional passphrase; or
- the server password.

Private-key contents are not copied into the vault.

## Usage

Connect interactively:

```text
/ssh
/ssh packaging-server
/ssh packaging-server:/absolute/remote/path
/ssh status
/ssh off
```

Or at startup:

```sh
pi --ssh packaging-server
pi --ssh packaging-server:/absolute/remote/path
```

Only imported host IDs are accepted. Arbitrary `user@host` targets are rejected.

The active host ID and remote cwd are stored in the Pi session for resume. Credentials are never stored in Pi session entries.

## Runtime behavior

- One persistent `ssh2` client is used for the active host.
- Each `ssh_bash` call opens an exec channel and runs under `bash -lc` in the selected remote cwd.
- SFTP provides remote reads and writes.
- Writes use a temporary remote file and prefer OpenSSH's atomic rename SFTP extension when the server supports it.
- A pinned SHA256 host-key mismatch fails closed.
- Connection loss fails closed; the extension does not silently replay a command.
- Remote `AGENTS.md` and `CLAUDE.md` files are never discovered or injected.
- `ssh_find` and `ssh_grep` perform capability detection inside each approved call and return at most 200 bounded result lines.
- RTK treats only `ssh_bash` as a Bash output-compaction alias; it does not rewrite remote commands or process remote search/read results.

### Adaptive remote search

`ssh_find` performs fixed-substring path matching with this backend order:

```text
fd → fdfind → git ls-files → find
```

`ssh_grep` defaults to literal, case-insensitive content matching with this backend order:

```text
ripgrep → git grep → find + grep
```

No backend is installed or uploaded. The tools use what the server already provides, report the chosen backend and truncation state, and cap `limit` at 200. A genuine no-match result succeeds with zero rows; invalid regexes, missing roots, and backend failures remain errors even though output passes through bounded `head`/`cut` stages. Narrow `path` and `pattern` when truncated rather than increasing the limit. Direct `find`, `fd`, `grep`, and `rg` commands remain forbidden through `ssh_bash`; use the structured search tools instead. Regex mode (`literal: false`) follows the selected backend's regex dialect.

The remote host must provide `bash`. SFTP support is required for file tools.

## Permission-system integration

All remote operations enter the bundle's existing permission chain:

- `ssh_read`, `ssh_write`, `ssh_edit`, `ssh_find`, and `ssh_grep` start as `ask`;
- `ssh_bash` uses the full deterministic Bash policy and `decisionFloor: "ask"`;
- deterministic hard denies remain denies;
- asks enter the configured `auto-review` authorizer;
- reviewer failures defer to the normal terminal prompt.

Permission evidence includes the configured host ID, resolved endpoint, port, remote cwd, and a bounded operation summary. It never includes passwords, passphrases, private-key contents, or the vault key. Remote paths are not normalized as local filesystem paths.

## Security notes

- Import only servers you control or trust.
- Verify host-key fingerprints through an independent channel before accepting them.
- Treat both vault files as secrets even though `hosts.enc` is encrypted.
- The extension's threat model does not protect credentials from malicious code already running as the same local user.
- Password keyboard-interactive mode reuses the configured password for the server's prompts; use it only with a trusted pinned host.
- Remote content reaches the model only through an explicit `ssh_*` call or explicit user `!` command.

## Development

```sh
npm test
```

Important files:

- `index.ts` — Pi extension and tool registration
- `src/ssh2-transport.ts` — persistent ssh2, exec, and SFTP transport
- `src/config.ts` — validated configuration types
- `src/vault.ts` — AES-GCM vault
- `src/import.ts` — `ssh -G` import helpers
- `scripts/ssh-config.mjs` — interactive configuration CLI
- `permission-integration.ts` — permission-system bridge

## Upstream and license

This maintained fork originates from `pansapiens/pi-ssh`; see [UPSTREAM.md](UPSTREAM.md). The pure ssh2 design also references the transport architecture in `@99percentpeople/pi-ssh-remote` without adopting its local-tool override model. Licensed under MIT; see [LICENSE](LICENSE).