dsh-secure-remote

Readme

# dsh-secure-remote

[![CI](https://github.com/startGalway/dsh-secure-remote/actions/workflows/ci.yml/badge.svg)](https://github.com/startGalway/dsh-secure-remote/actions/workflows/ci.yml)
[![Latest release](https://img.shields.io/github/v/release/startGalway/dsh-secure-remote?display_name=tag&sort=semver&color=2ea44f)](https://github.com/startGalway/dsh-secure-remote/releases)
[![License](https://img.shields.io/github/license/startGalway/dsh-secure-remote?color=blue)](LICENSE)
[![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-8a63d2)](#支持矩阵)
[![SSH](https://img.shields.io/badge/remote-POSIX%20over%20SSH-f39c12)](#安全边界)

独立的 DeepSeek Harness SSH 安全与稳定性插件。它通过 bundle patch 替换内置 `ssh` provider，不修改 DeepSeek Harness 上游源码，也不迁移现有 `ssh_workspace` v1 数据。

[English README](README.en.md)

## 1.1.2 能力

- macOS / Linux 使用短路径私有目录运行 OpenSSH `ControlMaster`，修复 macOS `ControlPath too long` 导致的 PTY 启动失败。
- Windows 本地端使用系统 `ssh.exe`，明确关闭 ControlMaster；状态探测和应用层重连仍可用。
- Key 模式自动发现 SSH Config 主机和默认密钥；支持选择单个密钥文件或文件夹。
- Password 模式只显示 Host / Port / User / Password；密码通过 DSH credentials 服务保存，不进入 SSH 参数、日志或状态接口。
- Workspace 行显示 `connected`、`connecting`、`degraded`、`disconnected` 状态点、延迟和脱敏原因。
- 保留官方 `openRawChannel` 原始 SSH 通道，兼容 Remote Agent 安装和长连接。
- 官方 `@deepseek-ai/dsh-ssh` 未发布或不可解析时，自动使用随插件发布的兼容 runtime；该 peer 依赖为可选项。
- 远程文件工具严格限制在 Workspace 根目录，拒绝 `..`、前缀碰撞和符号链接逃逸。
- 远端必须是 POSIX 系统；检测到 Windows 等非 POSIX 目标时返回 `REMOTE_OS_UNSUPPORTED`。
- 保留已有 `SshProfile`、`RemoteWorkspaceView`、Workspace RPC、Session、Bash 和 Terminal 兼容性。

## 安全边界

文件工具受到 Workspace 根目录保护；远程 Bash 保持原有行为，拥有远程 SSH 账号本身的完整权限，不宣称受到文件边界隔离。默认保持 `StrictHostKeyChecking=yes`，不会自动降级到 `no/off`。

## 支持矩阵

| 本地端 | SSH 客户端 | ControlMaster | 状态/重连 | 远端目标 |
| --- | --- | --- | --- | --- |
| macOS | 系统 OpenSSH | 启用 | 支持 | POSIX |
| Linux | 系统 OpenSSH | 启用 | 支持 | POSIX |
| Windows | `ssh.exe` | 禁用 | 支持 | POSIX |

要求 Node.js 22+，以及兼容的 DeepSeek Harness Web profile。Windows 本地端已实现代码分支，但真实 Windows SSH fixture 需要在 Windows CI 或 Windows 机器上执行。

## 安装

发布到 GitHub 后，安装指定版本：

```sh
dsh plugin --profile web add github:startGalway/dsh-secure-remote#v1.1.2
```

本地开发安装：

```sh
dsh plugin --profile web add file:/absolute/path/to/dsh-secure-remote
```

安装后重启 Web profile。卸载插件不会迁移或删除已有远程 Workspace：

```sh
dsh plugin --profile web remove dsh-secure-remote
```

## 配置默认值

```yaml
workspaceBoundary: deny
connectionReuse: true
controlPersistMs: 300000
serverAliveIntervalSec: 15
serverAliveCountMax: 3
statusProbeIntervalMs: 30000
maxTransferBytes: 8388608
```

## 本地开发

```sh
npm run check
npm test
npm run pack:check
```

目录结构：

```text
dsh-secure-remote/
├── index.js                 # Host provider、状态、重连和 bundle patch 接入
├── ssh-launcher.js          # ControlPath、平台能力、密钥和 SSH Config 发现
├── secure-rpc.js            # 同源受信 RPC：discovery / resolve / pick / status / probe
├── path-guard.js            # 远程 Workspace 边界校验
├── client.js                # Web UI 源文件
├── ui/                      # 独立 Web companion package
├── test/                    # 路径、SSH launcher 和发现逻辑测试
└── cordis.patch.yml         # 禁用内置 ssh，挂载 secure provider 与 UI
```

## 已知限制

- Bash 不受 Workspace 文件边界限制。
- 远程 Windows 本轮不支持。
- 当前版本不包含双向目录镜像、原子文件传输、后台任务和远程 Git 工作流。
- Unix 侧保留一个 `0700`、短路径的兼容启动器，因为当前 DSH SSH runtime 只暴露单一 `sshPath` 接口；Windows 直接调用系统 `ssh.exe`。

## 许可证

MIT，见 [LICENSE](LICENSE)。安全问题请阅读 [SECURITY.md](SECURITY.md)，贡献规范见 [CONTRIBUTING.md](CONTRIBUTING.md)。