dsh-ssh-vault 0.0.0-stage → 2.0.0

package/CONTRIBUTING.zh-CN.md

@@ -0,0 +1,167 @@
+# 贡献指南
+
+[English](CONTRIBUTING.md) | **简体中文**
+
+这个插件会**保管别人的口令**，还要在**别人的机器上执行命令**。所以它的门槛比一般小工具高：
+下面第一节的红线不是风格偏好，破了就是真实泄露或真实事故。
+
+## 一、红线（违反即拒绝）
+
+### 1. 绝不提交凭据、私钥与真实环境信息
+
+不要提交：私钥、口令、API key、`%DSH_HOME%` 下的任何文件、真实内网地址、真实主机名、
+真实账号名、会话日志。
+
+需要真实主机的测试**一律走环境变量**，源码里不得出现字面值：
+
+```js
+// 正确
+const KALI = { host: env.LIVE_KALI_HOST, user: env.LIVE_KALI_USER, pass: env.LIVE_KALI_PASS }
+
+// 错误
+const KALI = { host: '198.51.100.7', user: 'root', pass: '123456' }
+```
+
+示例、测试数据、文档一律使用**文档专用地址**：`192.0.2.0/24`、`198.51.100.0/24`、`203.0.113.0/24`。
+
+按下提交键之前自查：
+
+```powershell
+git status --short                 # 确认没有 id_rsa / id_rsa.pub / dist / .env
+git diff --cached                  # 逐眼过一遍，尤其看有没有 IP、账号、口令
+```
+
+`.gitignore` 已排除常见项，**但那不是保证**——它挡不住一个叫 `config.local.js` 的新文件。
+
+### 2. 口令不得进入命令行、日志或对话
+
+这是本项目的核心设计约束。任何改动都必须维持：
+
+| 位置 | 要求 |
+| --- | --- |
+| 本地 `ssh` 命令行 | 口令只能经 `SSH_ASKPASS` 环境变量传递 |
+| 远端命令行与 `ps` | 口令只能走标准输入 |
+| 会话日志 | 工具参数里不得出现口令，只能出现 `sudo: true` 这类开关 |
+| 磁盘 | 只有 AES-256-GCM 密文；明文只允许存在于内存 |
+
+改完执行路径后，必须能通过 `test/live.mjs` 中的「口令不出现在远端进程列表」一项。
+
+### 3. 保持零运行时依赖
+
+不要引入 npm 依赖。插件只调用系统 OpenSSH 客户端（`ssh` / `scp`）与 Node 内置模块。
+`package.json` 里不应出现 `dependencies`。
+
+### 4. 不擅自改动用户的 profile 或保险库
+
+运行时只读写自己的保险库目录（`%DSH_HOME%\ssh-vault`）。
+不要写 `%DSH_HOME%\.credentials.yaml`、profile 的 `package.json` 或 `cordis.patch.yml`，
+也不要碰用户的 `~/.ssh`。
+
+## 二、开发环境
+
+- Node.js >= 20（见 `package.json` 的 `engines`）
+- Windows 10 / 11 且启用 OpenSSH 客户端（`ssh -V` 能输出版本）。**本插件按设计仅支持 Windows**——数据密钥由
+  DPAPI 保护、askpass 辅助程序是 Windows `.cmd`；`package.json` 声明了 `os: ["win32"]`，运行期也会在其它平台
+  拒绝加载。不要重新引入「非 Windows 上把密钥明文落盘」的代码路径。
+- **不需要 `npm install`**——项目零依赖
+
+## 三、测试
+
+### 提交前必须跑
+
+```powershell
+npm test
+```
+
+它依次执行三个**免主机**回归，CI 跑的是同一组：
+
+```powershell
+node test/diagnose.mjs     # shell 翻译、八进制解码、失败归因
+node test/unit.mjs         # 参数构造、超时/取消保留输出、wait_for / detach 脚本
+node test/background.mjs   # 后台任务注册契约
+```
+
+### 需要真实主机时
+
+```powershell
+$env:LIVE_KALI_HOST = '<host>'
+$env:LIVE_KALI_USER = '<user>'
+$env:LIVE_KALI_PASS = '<password>'
+$env:LIVE_WIN_HOST  = '<host>'
+$env:LIVE_WIN_USER  = '<user>'
+$env:LIVE_WIN_KEY   = '<private key path>'
+node test/live.mjs
+node test/selftest.mjs
+```
+
+### 硬性要求
+
+- 改动 `lib/ssh.js` 的参数构造或诊断 → **必须**补 `test/unit.mjs` / `test/diagnose.mjs` 用例
+- 改动后台任务 → **必须**补 `test/background.mjs`
+- 新增面向模型的行为 → 至少一条单元用例把它钉住
+- **不许为了让测试通过而放宽断言**。如果新用例要求改旧断言，先在 PR 里说明旧断言为什么是错的
+
+## 四、代码风格
+
+格式由 [`.editorconfig`](.editorconfig) 约束，另有以下约定：
+
+- ESM（`import` / `export`），`"type": "module"`
+- 2 空格缩进、单引号、**行尾不加分号**、行宽约 120
+- 导出的函数写 JSDoc（`@param` / `@returns`）；**注释用中文，标识符用英文**
+- 纯函数优先：参数构造（`buildSshArgs`）、脚本生成（`buildWaitScript`、`buildDetachScript`）、
+  归因（`diagnose`）都保持无副作用，这样才测得动
+- 错误信息面向使用者：说清**发生了什么**与**怎么恢复**，不要只把底层错误抛出去
+
+## 五、提交信息
+
+采用 [Conventional Commits](https://www.conventionalcommits.org/zh-hans/)：
+
+```
+<type>: <简短描述>
+
+<可选正文：为什么这么改>
+```
+
+`type` 取 `feat` / `fix` / `docs` / `refactor` / `test` / `chore`。
+标题用英文祈使句，正文中英文皆可。**一次提交只做一件事。**
+
+## 六、Pull Request
+
+1. 行为变更先开 issue 讨论，尤其是涉及权限、执行路径、存储格式的
+2. 分支名 `feat/...`、`fix/...`、`docs/...`
+3. PR 描述写清三件事：**改了什么、为什么、怎么验证的**
+4. 命中以下任一项时，必须在描述里单独说明：
+   - 新增了执行路径（口令会经过哪里）
+   - 保险库格式变化（是否需要迁移，旧数据怎么办）
+   - 新增工具参数（它会不会进入会话日志）
+5. `npm test` 通过，且 `git diff` 里没有凭据
+
+## 七、设计约束（架构层面）
+
+动代码前先确认没有破坏这些：
+
+- **别名寻址**：模型只见别名，地址与凭据由保险库提供。
+  不要新增需要模型传主机名、账号或口令的参数。
+- **中断不等于失明**：任何执行路径在超时或被取消时，都必须回传已经收到的输出。
+- **失败要说清归因**：本地密钥问题、公钥未装机、口令错误、防火墙丢包必须能区分；
+  「账号或口令不正确」只能在前几项都排除之后出现。
+- **长任务不占用工具调用**：优先用 `detach`（远端脱离）与 `wait_for`（条件等待），
+  不要把 `sleep` 轮询写进工具实现。
+- **会话日志是唯一真相**：不新增自定义会话事件；插件状态要么能从日志重建，
+  要么放进保险库或存储服务。
+- **存储格式带版本号**：改动 `vault.json` / `key.json` 结构时必须升版本并能读旧数据。
+
+## 八、项目结构
+
+| 路径 | 职责 |
+| --- | --- |
+| `index.js` | 插件入口、四个模型面向工具、配置解析、凭据解析 |
+| `lib/vault.js` | 加密保险库（AES-256-GCM + DPAPI / scrypt） |
+| `lib/ssh.js` | OpenSSH 驱动：参数构造、askpass 注入、失败归因、等待与脱离脚本 |
+| `lib/background.js` | `ctx.jobs` 后台任务适配 |
+| `scripts/set-secret.mjs` | 离线口令录入（不经过 DSH，也不经过模型） |
+| `test/` | 回归；前三个免主机，后三个需要真实目标 |
+
+## 九、许可
+
+提交贡献即表示同意以 [MIT](LICENSE) 授权。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-ssh-vault contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,453 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# dsh-ssh-vault
+
+![DSH-SSH-Vault banner](assets/banner.png)
+
+**English** | [简体中文](README.zh-CN.md)
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](package.json)
+[![DSH plugin](https://img.shields.io/badge/DeepSeek%20Harness-plugin-4f7cff.svg)](https://github.com/deepseek-ai)
+[![Version](https://img.shields.io/badge/version-2.0.0-informational.svg)](package.json)
+[![Tests](https://img.shields.io/badge/test-321%20cases-brightgreen.svg)](test)
+
+</div>
+
+SSH for DeepSeek Harness agents: host address, port, account, password and private key live in an encrypted vault, and the conversation only ever uses an alias. The model never sees a password, and a password never reaches a command line or a remote process list.
+
+## Overview
+
+**Windows only.** The vault data key is protected by Windows DPAPI and the `SSH_ASKPASS` helper is a Windows `.cmd` wrapper; the plugin declares `os: ["win32"]` and refuses to start anywhere else rather than storing the key as plaintext.
+
+Three capabilities in one plugin:
+
+- **Model-facing tools** — `ssh_hosts`, `ssh_run`, `ssh_transfer`, `ssh_probe`, so the agent operates remote hosts by alias.
+- **Settings UI** — add, edit and delete hosts in Settings → SSH Connections, and test reachability. A password entered there travels in an HTTP body, never through the session log.
+- **`/hosts` command** — probe hosts and run commands from the conversation without going through the model.
+
+Under the hood it drives the local OpenSSH client (`ssh` / `scp`). It does not implement the SSH protocol itself.
+
+## Install
+
+```bash
+dsh plugin --profile desktop install dsh-ssh-vault
+```
+
+From a local checkout. The argument is a path, so `.` works when you are already inside the plugin directory:
+
+```bash
+# inside the checkout
+dsh plugin --profile desktop install .
+
+# or point at it from elsewhere
+dsh plugin --profile desktop install ../dsh-ssh-vault
+
+# or install from a packed tarball
+dsh plugin --profile desktop install ./dsh-ssh-vault-<version>.tgz
+```
+
+**`--profile` is required.** DSH isolates plugins per profile, and one machine can carry several (`desktop`, `cli`, …). Omitting it falls back to whichever profile is currently default, which is an easy way to install into the wrong place. Confirm the landing spot with:
+
+```bash
+dsh plugin --profile desktop list
+```
+
+**Restart DSH after installing.** Host-side tools and routes are loaded at startup.
+
+**This package is Windows only.** `package.json` declares `os: ["win32"]`, so `dsh plugin ... install` refuses to install it on Linux or macOS; a checkout loaded on another platform refuses to start for the same reason (see [Known limitations](#platform-and-authentication)).
+
+### Requirements
+
+| Item | Requirement |
+| --- | --- |
+| Node | ≥ 20 |
+| Machine | Windows 10 / 11 with the OpenSSH Client enabled (`ssh -V` prints a version) |
+| Platform | **Windows only** (`win32`) — installation and loading are refused on Linux / macOS |
+
+## Quick start
+
+1. **Install, then restart DSH.**
+2. Open **Settings → SSH Connections**, click "Add connection", fill in alias, address, port, account, and choose password or private-key authentication.
+   Each card carries a health dot that is checked automatically: grey = not checked, yellow = checking, green = reachable, red = unreachable.
+3. Say something in the conversation, for example:
+
+   ```
+   run uptime on kali
+   ```
+
+   The model calls `ssh_run` and the result appears as a terminal card.
+
+Do not paste passwords into the conversation. A password entered in Settings goes straight into the encrypted vault and never enters the model context.
+
+## Usage
+
+### Model-facing tools
+
+| Tool | Purpose | Typical phrasing |
+| --- | --- | --- |
+| `ssh_hosts` | Manage the vault (list / show / add / update / remove) | "which hosts do I have", "change kali's note" |
+| `ssh_run` | Run a command on a host, return stdout and stderr | "check disk usage on kali" |
+| `ssh_transfer` | Upload or download a file (scp) | "copy this file to /tmp on kali" |
+| `ssh_probe` | Reachability self-check returning system facts | "is kali still reachable" |
+
+**Where to see the result:** calls to `ssh_run`, `ssh_probe` and `ssh_transfer` render as a **terminal card** — a header with "host · command" and a state dot, above a scrollable monospace output area. The dot is blue while running, grey on success, red on failure (including a non-zero exit code).
+
+### Settings UI
+
+Settings → SSH Connections provides:
+
+- A host list with a health dot per card; hover for detail
+- Add / edit / delete connections (the alias is editable, credentials move with it)
+- A "Test connection" button per card, whose result also drives the dot
+- "Open in file manager" for the vault directory
+- Password and private-key authentication; a key can be uploaded whole and is written into the vault with its permissions tightened
+
+### Language
+
+Everything the plugin shows follows the language chosen in **Settings → General → Language**; there is no separate switch here.
+
+- The settings page and the in-conversation SSH cards get their copy from the host's locale service, so they change the moment the language does.
+- `/hosts` output, transport diagnostics, Settings-API errors, vault errors and background-job status are generated on the Host; they read the same persisted preference (`locale.preference`) and follow later changes, falling back to the request's `Accept-Language` only when nothing was ever chosen.
+- **Model-facing definitions stay English**: tool names, descriptions and parameter schemas belong to the model interface, not to the UI.
+
+### The `/hosts` command
+
+Start a line with `/` in the composer and the command runs **without going through the model**.
+
+```
+/hosts                    list every host, grouped into online / offline
+/hosts kali               probe one
+/hosts kali,win10         probe several (either comma form works)
+/hosts kali; apt update   run a command on kali
+/hosts kali,win10; uptime run on every reachable host
+```
+
+- Separators accept both ASCII and full-width forms: `,` and `，`, `;` and `；`
+- If the text after the semicolon reads as natural language (e.g. "check the disk"), the command **does not run it** and tells you to send that sentence to the conversation instead — command output never reaches the model, so such requests cannot go through the command
+- Output renders as **two cards**: reachability and command execution, each with its own state dot
+- **Picking `/hosts` from the `/` menu only claims it**: the composer shows the command token with its hint. Press Enter again to run it bare (list hosts), or type `alias; shell command` as its arguments. To go back to a normal prompt instead, delete the command token — until then, whatever you type is the command's argument
+- **Before the first message the result appears above the composer.** DSH treats a transcript containing only command rows as an inactive view, so a bare `/hosts` in a brand-new conversation used to look like "nothing happened" until you sent a message. The plugin now mirrors the `/hosts` cards (running state included) in the composer dock while the session is still blank; once the first message exists the transcript takes over, so nothing is duplicated
+- A bare call probes only when the health cache is cold, in parallel and with a 4s budget, so it answers within seconds even when several hosts are unreachable
+
+## Architecture
+
+### Two halves
+
+This is a **Host + Client** plugin; the two halves load through different mechanisms:
+
+| Half | Entry | Loading |
+| --- | --- | --- |
+| **Host** | `index.js` | Cordis plugin, inserted into the Loader through `cordis.patch.yml` |
+| **Client** | `client.js` | Browser module, declared via `dsh.client` in `package.json` and injected into the page by the host |
+
+The Host half carries every sensitive operation: vault encryption, driving the local `ssh` client, web routes, and the registration of commands and tools.
+The Client half only renders and collects form input; it never executes a command.
+
+### Data flow
+
+```mermaid
+flowchart TB
+    subgraph entry [Entry points]
+        chat[Conversation / model tool call]
+        settings[Settings form]
+        cmd["/hosts command"]
+    end
+
+    subgraph host [Host half — index.js]
+        resolve[Resolve alias → read credentials → build ssh args]
+        vault[(Vault<br/>AES-256-GCM ciphertext)]
+        api["Web routes /ssh-vault/*"]
+        exec[Spawn local ssh / scp]
+    end
+
+    subgraph client [Client half — client.js]
+        toolcard[Tool terminal card]
+        cmdcard["/hosts double card"]
+        form[Connection form]
+    end
+
+    proxy[Remote host]
+
+    chat --> resolve
+    cmd --> resolve
+    settings -->|POST JSON| api
+    form -->|same-origin, document-relative| api
+    api --> vault
+    resolve --> vault
+    resolve --> exec
+    exec -->|stdout / stderr| toolcard
+    exec -->|stdout / stderr| cmdcard
+    exec <--> proxy
+```
+
+Three invariants hold across that chain:
+
+1. **A password never reaches a command line** — local ssh receives it through `SSH_ASKPASS`; remote sudo is primed over stdin
+2. **Only ciphertext touches disk** — AES-256-GCM, with the data key protected by Windows DPAPI (or, optionally, derived from a master passphrase via scrypt)
+3. **`~/.ssh` is never touched** — `known_hosts` points into the vault directory and `HashKnownHosts` is enabled
+
+## Configuration
+
+The plugin has **no user-configurable options**. `config: {}` in `cordis.patch.yml` is an empty object, and the Loader entry `id` is fixed as `ssh-vault`.
+
+Behaviour is shaped by the following:
+
+| Item | Notes |
+| --- | --- |
+| Vault directory | Defaults to `$DSH_HOME/ssh-vault`; `DSH_HOME` is decided by DSH |
+| Key protection | `dpapi` (Windows DPAPI, the default) or `passphrase` (scrypt-derived key, no key material on disk). `file` stores the key as plaintext and is an explicit opt-in only |
+| Timeouts | `ssh_run` defaults to 120s, adjustable, capped at 30 minutes; commands inside `/hosts` are fixed at 120s |
+| Health checks | Settings page and `/hosts` probe with a 15s timeout; the background sweep refreshes every 5 minutes |
+
+## API and extension points
+
+Host-side services are reached through `ctx.inject` as optional dependencies; a missing service does not fail the plugin, it just disables that capability.
+
+### Model tools (`ctx.tools.register`)
+
+| Tool | Key parameters |
+| --- | --- |
+| `ssh_hosts` | `action` required (list / show / add / update / remove); `reveal` controls whether address and account are masked |
+| `ssh_run` | `host`, `command` required; optional `sudo`, `timeoutMs`, `workdir`, `run_in_background`, `wait_for`, `bindAddress` |
+| `ssh_transfer` | `host`, `direction`, `local`, `remote` required; optional `recursive` |
+| `ssh_probe` | `host` required; optional `timeoutMs`, `bindAddress` |
+
+The three terminal-style tools also register `presentCall` / `presentResult` hooks, but **the current DSH version has no consumer for them**; presentation is handled by the slots below.
+
+### Client slots (`ctx.slots.register`)
+
+| Slot | Key | Effect |
+| --- | --- | --- |
+| `settings.section` | `id: ssh-vault`, `order: 20`, `label` | The "SSH Connections" page in the settings panel |
+| `tool.call.toolview` | `ssh_run`, `ssh_probe`, `ssh_transfer` | Renders those tool calls as terminal cards |
+| `conversation.chat.commandview` | `hosts` | Renders `/hosts` output as two terminal cards |
+
+The `tool.call.toolview` key space is open; none of these three names were taken, so no built-in UI is shadowed.
+
+All three registrations also carry `locale: 'ssh-vault'` — the namespace registered with the host's locale service — which is what makes the rendered cards re-render and re-read their copy when the language changes.
+
+### Human command (`ctx.commands.register`)
+
+| Command | Notes |
+| --- | --- |
+| `/hosts` | Probe hosts / run a command on them. Form: `alias[,alias][; shell command]` |
+
+The command's `description` and `input.hint` are **re-registered only when the interface language changes**. The disposer returned by `commands.register` destroys the current definition, so replacing it while the user is typing arguments strips the composer of its command context (backspace stops working, and the UI needs a restart). That is why registration is never driven by timers or health results; a locale switch is a deliberate Settings action with nothing being typed, making it the one safe moment to swap the definition.
+
+### HTTP routes (`ctx.webServer.register`)
+
+Mounted at `/ssh-vault` (`kind: 'prefix'`, **no trailing slash**). `POST` only, JSON in and out, with an envelope of `{ ok: true, value }` or `{ ok: false, error }`.
+
+| Path | Effect |
+| --- | --- |
+| `/ssh-vault/list` | Host list (address and account masked, no passwords) |
+| `/ssh-vault/save` | Create / update / rename |
+| `/ssh-vault/remove` | Delete |
+| `/ssh-vault/test` | Reachability probe |
+| `/ssh-vault/reveal` | Return unmasked address and account |
+| `/ssh-vault/openVault` | Open the vault directory in the system file manager |
+
+`openVault` **accepts no path argument at all** — it can only open the plugin's own vault directory.
+
+Every request crosses the Host Connection trust fence **before** the handler looks at the method, the body or the vault: it calls `ctx.connection.requestRejection(req)`, the same Host/Origin check and browser-session authentication used by `/api`. A rejected request gets `401` / `403` and never reaches the vault, so a DNS-rebinding or cross-site call cannot read host data or trigger a probe.
+
+### About `ctx.systemPrompt.section`
+
+**This plugin does not use that extension point.** Every tool carries its own `description`, and no section is injected into the system prompt, so prompt length and ordering are unaffected.
+
+## Lifecycle
+
+### Startup
+
+1. The Loader reads `cordis.patch.yml` and inserts the entry with `id: ssh-vault`
+2. The host `import`s `index.js` and calls `apply(ctx, config)`
+3. `apply` opens the vault, registers the four tools, and — where the services exist — the web routes, the `/hosts` command and the background health timer. It also subscribes to the host settings document so it can read the interface language and follow later switches
+4. The Client half is injected into the page per the `dsh.client` declaration, and its `apply` registers the three slots and its `ssh-vault` dictionary with the locale service
+
+### Unload and resource reclamation
+
+Async resources are wrapped in `ctx.effect`, and Cordis runs the returned cleanups in reverse order on teardown:
+
+- Tool and command disposers (including the locale-switched command definition)
+- Web route disposers
+- The settings-document subscription and its startup retry timers
+- The health sweep's `setTimeout` / `setInterval`
+- The vault handle
+- The client's locale dictionary and slot registrations
+
+Vault data **survives uninstall** and is available again after reinstall.
+
+### Hot update
+
+The two halves behave differently, and this is easy to get wrong:
+
+| Change | Takes effect by |
+| --- | --- |
+| `client.js` and slot rendering | Reinstall the bundle, then **reload the page** |
+| `index.js` / `lib/**` | **Restart DSH**; reinstalling does not replace an already-loaded module generation |
+| `package.json` `version` | The version shown in Settings is read from this file by the Host |
+
+**Do not infer that the browser has new code from an unchanged slot id** — slot registration reflects the host side, not the module actually running in the page.
+
+## Known limitations
+
+### Platform and authentication
+
+- **Windows only.** The data key is protected by Windows DPAPI and the `SSH_ASKPASS` helper is a Windows `.cmd`; the repository therefore declares `os: ["win32"]`. There is no Linux/macOS mode: running the code there would have to fall back to a plaintext `key.json`, so the plugin refuses to load instead. SSH still targets Linux/Unix hosts *remotely* — the restriction is on the machine running DSH.
+- **`dpapi` is the default key protection; `passphrase` is available** (a master passphrase, with the key derived through scrypt). `file` stores the key as plaintext and must be chosen explicitly; it is not a fallback.
+- **The Settings UI supports only password and private-key authentication.** The `agent` auth type can be set through `ssh_hosts add`, but the form cannot enter or edit it
+- **Remote shells supported: bash / sh / cmd / powershell.** Sudo priming applies to POSIX shells only
+
+### Concurrency
+
+- **Connections to one host are serialised in-process.** Every call opens a fresh SSH
+  connection, and a burst of them — especially concurrent `scp` — trips sshd's connection
+  limits and accumulates failed-auth counters toward an account lock. Background jobs are
+  exempt from the queue so a long task does not block that host for everything else.
+- **The vault has no cross-process lock.** Two DSH instances (different profiles pointing at the same vault directory) writing at the same time means the later write wins
+- Within one profile, writes from several sessions serialize on the event loop, but frequent concurrent edits of the same host are still not advisable
+
+### Account lockout
+
+Windows OpenSSH disconnects a **locked** account outright instead of returning
+`Permission denied`, so a locked account looks like a network problem: the port answers, the
+banner arrives, then the connection is reset. If "port open, banner fine, still cannot
+connect" shows up, check the account before chasing the firewall — `net user <account>` on
+Windows, `faillock --user <account>` on Linux. Locking the management account also kills
+key-based login, so keep a second administrative path available when experimenting with
+lockout policy. `ssh_run` warns before commands that change account state.
+
+### Host keys
+
+`StrictHostKeyChecking=accept-new` is used: **the first connection is trusted automatically**, and any later fingerprint change is refused. There is no separate fingerprint-verification flow, so judging whether a first-time target is trustworthy is up to the operator.
+
+### Output and timeouts
+
+- `ssh_run` caps a single result at 200000 characters and truncates beyond that
+- Each command inside `/hosts` echoes at most 40 lines
+- Commands inside `/hosts` have a fixed 120s timeout that is not configurable
+- Foreground tool calls have **no streaming output**: the result appears in one piece when the command ends. To watch a long job, use `run_in_background`, whose output lands in a job card
+
+### Interface
+
+- The **navigation icon next to "SSH Connections" is drawn by the host from the section id**. The `settings.section` registration accepts only `id` / `order` / `label`, so a plugin cannot supply its own icon
+- Command arguments have **no candidate-list mechanism** (`CommandInputDescriptor` carries only `hint` and `attachments`), so `/hosts` cannot offer alias completion
+- A command with an `input` hint is **claimed, not executed**, when picked from the `/` menu: this is DSH behaviour and the plugin cannot bypass it. The hint (localized) explains that a second Enter runs the command bare
+- **DSH does not treat a transcript made only of command rows as an active view.** `/hosts` compensates with the composer-dock mirror described above; the built-in rule still applies to other plugins' commands
+- The **interface language is read from the shared host settings**, so with several browsers attached to one host the most recently written preference wins; DSH Desktop is a single-user surface, where this is the intended behaviour
+
+### Open questions
+
+Not verified in detail; check the source or upstream docs before relying on them:
+
+- Whether DSH exposes a structured field for command results, which would replace the textual section markers (`─── 连接状态:ok ───`) used today
+- Whether the host will connect a consumer to `presentCall` / `presentResult` in a future version
+
+## Security boundary
+
+### What it touches
+
+| Category | Accessed | Detail |
+| --- | --- | --- |
+| Filesystem | **Yes** | The vault directory (`vault.json`, `key.json`, `known_hosts`, uploaded key copies) and any private-key path you supply; **never** `~/.ssh` |
+| Network | **Yes** | Outbound SSH through the local `ssh` / `scp` processes; loopback HTTP routes (same origin, behind the Host Connection trust fence) |
+| Terminal | **Yes** | Spawns the local OpenSSH client; `openVault` launches the system file manager |
+| External APIs | **No** | No third-party service is contacted |
+| User data | **Yes** | Host address, port, account, password, private key, note, tags |
+
+### Password handling
+
+- **Local SSH**: passed through `SSH_ASKPASS`, never on the command line or in a process list
+- **Remote sudo**: primed over stdin, never on the remote command line or in `ps`
+- **On disk**: only AES-256-GCM ciphertext; the data key is protected by DPAPI or a scrypt-derived key
+- **Model context**: a password never appears in tool arguments or results; one entered in Settings travels in an HTTP body and stays out of the session log
+- **`credentialRef`**: when a host points at an entry in the Harness credential store, the password is read at connect time and never passes through this plugin
+
+### Trust boundary
+
+The web routes ride on the DSH web server and ask the Host Connection service for a rejection first (the same Host/Origin fence and browser-session authentication as `/api`). The plugin adds no authentication of its own beyond that, so **do not expose the DSH web port to an untrusted network**.
+
+### Reporting a vulnerability
+
+See [SECURITY.md](SECURITY.md).
+
+## FAQ
+
+**"SSH Connections" is missing from Settings after installing.**
+Check you installed into the right profile: `dsh plugin --profile <name> list`. Then restart DSH — the client bundle is injected at page bootstrap, so a page reload alone is not enough.
+
+**A tool call reports a missing route, or Settings says the host is still running old code.**
+The host code was updated but the process was not restarted. Restart DSH.
+
+**The health dot stays red although the host answers ping.**
+The dot tests the **SSH port 22**, not ICMP. Check that `sshd` is running, that a firewall allows the port, and that the address stored in the vault is still current.
+
+**A connection test reports "connection not established within 15000ms".**
+Again a network-layer signal: the address changed, a firewall is blocking, or the machine is up without `sshd`. It is unrelated to login credentials.
+
+**A word gets a red squiggle while typing `/hosts`.**
+That is why the command is named `hosts`: the composer is a Lexical editor whose plain text nodes are subject to browser spellcheck, and `hosts` is a dictionary word while `ssh` is not.
+
+**`/hosts kali,win10` says "not found".**
+Check the alias spelling against the vault; it is case-sensitive. Run `/hosts` with no arguments to list the valid aliases.
+
+**A private key upload is rejected.**
+Three common causes: a `.pub` public key was chosen, a PuTTY `.ppk` was chosen (convert it with `puttygen` first), or the file has no `BEGIN … PRIVATE KEY` header.
+
+**Output from several hosts runs together.**
+Use the `/hosts host; command` form; the output splits into a reachability card and a command card.
+
+**I switched DSH to English but some plugin text is still Chinese.**
+From 1.15.0 the whole surface follows the DSH language. After upgrading, reload the page once (client half) and restart DSH once (host half) to load the new code; after that, switching the language in Settings applies immediately, no reload needed. Model-facing tool definitions stay English by design.
+
+**Does it work on Linux or macOS?**
+No. The data key is protected by Windows DPAPI and the `SSH_ASKPASS` helper is a Windows `.cmd`; any non-Windows path would have to store the key as plaintext, so the plugin refuses to load there. `package.json` declares `os: ["win32"]` and installation is rejected elsewhere. The *remote* hosts can of course be Linux/Unix — only the machine running DSH must be Windows.
+
+**Client code changed but the interface did not.**
+Reload the page. Host-side changes need a DSH restart.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The hard rules: **zero runtime dependencies** (Node built-ins only on the Host side; only the host-provided `react` on the Client side), no real credentials or addresses in the repo, and a password must never reach a command line or the session log.
+
+```bash
+npm test            # host-free regression suite
+npm run test:live   # end-to-end cases against real hosts
+```
+
+## License
+
+[MIT](LICENSE)
+
+## Cheat sheet: start · use · stop · uninstall
+
+```bash
+# Install (profile required)
+dsh plugin --profile desktop install dsh-ssh-vault
+dsh plugin --profile desktop install .        # from inside a local checkout
+
+# Confirm where it landed
+dsh plugin --profile desktop list
+
+# Reinstall to refresh the installed copy
+dsh plugin --profile desktop remove dsh-ssh-vault
+dsh plugin --profile desktop install dsh-ssh-vault
+
+# Uninstall
+dsh plugin --profile desktop remove dsh-ssh-vault
+```
+
+**Starting and stopping** are handled by the DSH process itself: the plugin loads when DSH starts and unloads when DSH exits. It has no separate process and no resident background service.
+
+Uninstalling **does not delete the vault**. Data stays in `$DSH_HOME/ssh-vault` and is usable again after reinstall; delete that directory by hand to remove it entirely.
+
+Everyday reference:
+
+```
+Settings → SSH Connections        manage hosts, test reachability, open the vault directory
+/hosts                            list hosts and their online state
+/hosts kali                       probe one host
+/hosts kali,win10; uptime         run a command on several
+(just talk)                       let the model pick hosts and call the tools
+```