远程访问网关OneCat2015/Remote-My-DSH

Remote-My-DSH

CI

不，我不想让 DSH 只能运行在 localhost！
于是就有了这个…… 一个 DSH 的登录门禁：可以自己通过 HTTP 自加密传输 DSH 内容，或者被安全地包进 HTTPS 里。
（以及针对手机访问做了一点UI适配）

不——我不想让 DSH 只能活在 localhost 上。所以就有了这个：一个 DSH 的登录门禁，它通过 HTTP 自加密传输 DSH 的内容，或者安全地搭载在 HTTPS 之内。（同时也为手机访问做了一点 UI 适配。）

（但是：不包含 HTTPS 的远程访问只是“尽量安全一点”，主动中间人可以替换页面，算不上安全，只是一个安装即用的变通方法。）

（但是：没有 HTTPS 的远程访问只是“我们所能做到的最安全”——主动中间人可以替换页面，所以它并不真正算得上安全；它只是一个安装即用的变通方法。）

一、它是什么 / 它是什么

DeepSeek Harness（DSH）Web UI 的远程访问网关插件：将它安装到DSH，这个插件会跟随DSH一起启动或关闭。装上后，DSH 的 Web UI 不再只属于 localhost——数据面 AEAD 自加密、挑战-应答认证、会话与审计在登录门禁之后各司其职；但如果需要真正全链路安全，你需要使用HTTPS。

一个用于 DeepSeek Harness（DSH）Web UI 的远程访问网关插件：将它安装到 DSH 中，它就会随 DSH 一起启动和停止。安装后，Web UI 不再只属于 localhost——AEAD 自加密、挑战-应答认证、会话和审计各自在登录门禁之后履行自己的职责。但如果你需要真正的端到端安全，你需要 HTTPS。

二、给想用的人 / 给用户

主要功能 / 主要功能

- 零配置上手：默认监听 http://localhost:3443，打开即可登录。从手机或其他机器访问时，直接使用局域网 IP 打开，无需额外配置。
- 多场景可用：内网直连、公司大内网、家庭 IPv6 外出、公网中转等 4 种场景，均提供 examples/ 配置模板，复制修改即可使用。
- 会话续接：浏览器在线期间会话持续有效；断线 2 小时内重开可自动恢复，无需重新输入 token。勾选“记住此设备”后，下次访问免登录。
- UI 手机适配：登录页与设置面板已针对手机访问适配。

- 零配置启动：默认监听 http://localhost:3443——只需打开它并登录。从手机或其他机器访问时，通过局域网 IP 打开即可，无需额外配置。
- 多场景：局域网直连、公司内网、家庭 IPv6 外网、公网中转——四种场景都在 examples/ 中提供了模板；复制并调整即可。
- 会话恢复：浏览器在线期间，你的会话保持有效；断开后 2 小时内重新打开会自动恢复，无需重新输入 token。勾选“记住此设备”即可在下次访问时跳过登录。
- 移动端 UI 适配：登录页和设置面板已针对手机访问进行了适配。

快速开始 / 快速开始

方式一：从 npm 安装（推荐）/ 方式一：从 npm 安装（推荐）
dsh plugin --profile web add remote-my-dsh
remote-my-dsh enable                                       # 开启网关（或 DSH 设置里点启用）/ 启用网关（或在 DSH 设置中将其打开）

方式二：从 GitHub Release 下载安装 / 方式二：从 GitHub Release 下载安装
在 https://github.com/OneCat2015/Remote-My-DSH/releases 下载 remote-my-dsh-0.1.0.tgz
从 https://github.com/OneCat2015/Remote-My-DSH/releases 下载 remote-my-dsh-0.1.0.tgz
dsh plugin --profile web add remote-my-dsh-0.1.0.tgz
remote-my-dsh enable
首次启用会自动生成随机 token、验证器与 pepper，并打印访问地址。几点说明：同版本 tgz 重装时 pnpm 可能复用缓存，需先 remove 再 add；首次监听局域网口会触发 Windows 防火墙询问，放行一次即可；dsh plugin --profile web add remote-my-dsh 会从 npm registry 拉取最新版，升级时同样先 remove 再 add。

CLI

| 命令 | 说明 |
|---|---|
| remote-my-dsh enable | 一键启用：写 gateway.yml、生成验证器、打印访问地址 |
| remote-my-dsh token / token --rotate | 查看 / 轮换 token（已保持会话不杀，旧 token 登录与恢复凭据失效） |
| remote-my-dsh token --disable | 禁用 token，关闭入口 |
| remote-my-dsh status | 监听地址、加密模式、会话策略、最近审计 |
| remote-my-dsh ca | 导出自签根证书（tls: auto）与安装指引；设置 API 下载会先校验并修复当前 CA/叶证书/私钥三件套 |

配置也可在 DSH 的 Web UI（DSH 自身托管的 localhost 页面，非本插件托管的页面）中直接编辑。

常用配置

/gateway.yml（默认 ~/.dsh/profiles/web/gateway.yml）：

| 字段 | 默认 | 说明 |
|---|---|---|
| port | 3443 | 监听端口 |
| tls | off | auto = 自签， = 真证书 |
| crypto | auto | 数据面自加密 |
| session | browser+2h | 浏览器在线，断线保存 2 小时可续 |
| refresh | 12h | "记住此设备"恢复凭据有效期 |
| tokenLifetime | permanent | 访问令牌自动轮换周期：once = 登录成功后立即轮换一次；时长档到期自动轮换；permanent = 不自动轮换。轮换不杀已保持会话，但会使已记住设备的免登录恢复失效 |
重要提示：不配 TLS 的远程访问是明文 HTTP——数据内容是加密的，但页面本身无法防御主动中间人攻击。在不可信网络或传输敏感内容时，请先配置 tls: auto（自签证书）或真实证书。

Important：不配 TLS 的远程访问是明文 HTTP——数据内容是加密的，但页面本身无法防御主动中间人攻击。在不可信网络或传输敏感内容时，请先配置 tls: auto（自签证书）或真实证书。

三、给想了解的人 / For the Curious

工作原理 / How It Works

网关作为唯一外部入口，挂在 DSH 内层 webServer（必须绑定 127.0.0.1）之前。访问流程：未认证请求被 302 到登录页 → 挑战-应答握手（一次性 challenge + 短 TTL，proof 不携带 token）→ 密钥确认后建立会话密钥 Ks → 此后 /api 与 WebSocket 事件流全部经 /api/rpc 以 AEAD 帧反代到内层 DSH。真实的方法、路径、语义头只存在于密文内；静态资源经 cookie presence gate 明文放行。

网关作为唯一外部入口，挂在 DSH 内层 webServer（必须绑定 127.0.0.1）之前。访问流程：未认证请求被 302 到登录页 → 挑战-应答握手（一次性 challenge + 短 TTL，proof 不携带 token）→ 密钥确认后建立会话密钥 Ks → 此后 /api 与 WebSocket 事件流全部经 /api/rpc 以 AEAD 帧反代到内层 DSH。真实的方法、路径、语义头只存在于密文内；静态资源经 cookie presence gate 明文放行。

协议要点：PROTOCOL_VERSION = 2（ChaCha20-Poly1305 帧，21B 帧头仅含 sessionId + dir + seq）；Ks = HKDF(k ‖ ECDH, salt)，一次性 P-256，前向保密；方向子密钥 + 会话级 seq 窗口防重放；24 小时链式轮换。网关侧使用 node:crypto 原生引擎，浏览器侧使用 noble 纯 JS 引擎，两者逐字节一致（tests/engine.test.js 验证）。完整规格见 PLAN.md。

协议要点：PROTOCOL_VERSION = 2（ChaCha20-Poly1305 帧，21B 帧头仅含 sessionId + dir + seq）；Ks = HKDF(k ‖ ECDH, salt)，一次性 P-256，前向保密；方向子密钥 + 会话级 seq 窗口防重放；24 小时链式轮换。网关侧使用 node:crypto 原生引擎，浏览器侧使用 noble 纯 JS 引擎，两者逐字节一致（tests/engine.test.js 验证）。完整规格见 PLAN.md。

安全模型 / Security Model

可防护的：被动嗅探/DPI 无法读取内容；存储泄露（验证器 pepper 加密）；登录 proof 重放（一次性 challenge）；密文重放与篡改（AEAD + seq）；“录流量 + 日后窃取 token 回解历史会话”（前向保密）；登录参数在真实登录页未被替换时的在途篡改（Ed25519 签名）。另有代码层约束：非 loopback + crypto:off 直接拒绝启动，唯一放行口是显式 allowInsecureRemote: true（写入 warn 审计）——远程明文只允许在数据面加密的前提下存在。登录页还可展示当前 TLS 叶证书 SHA-256 指纹、SAN 和签名公钥 ID，tls:off 时仅作参考。
防护范围：被动嗅探/DPI 无法读取内容；存储被攻破（验证方 pepper 加密）；登录证明重放（一次性挑战）；密文重放与篡改（AEAD + seq）；"现在记录流量，日后窃取令牌，解密过往会话"（前向保密）；真实登录页未被替换时登录参数在传输中被篡改（Ed25519 签名）。此外还有代码层面的约束：非回环地址配合 crypto:off 会直接拒绝启动，唯一的放行条件是显式设置 allowInsecureRemote: true（会写入 warn 审计）——只有在数据面已加密时，才允许远程明文。登录页还可以显示当前 TLS 叶证书的 SHA-256 指纹、SAN 以及签名公钥 ID；在 tls:off 时这些仅供参考。

不防护的：明文 HTTP 下的页面级主动 MITM——验签代码可连同整页被替换，无法证明；应用 XSS——Ks 位于页面内存，DSH 渲染输出，无法根治。前两者的对应解法是 TLS，这也是本项目定位为"安装即用的变通方法"而非完全安全。

不防护的内容：明文 HTTP 下的页面级主动 MITM——验签代码可连同整页被替换，因此无法证明任何东西；应用 XSS——Ks 存在于页面内存中，且 DSH 会渲染输出，因此无法根除。这两者的解决方案都是 TLS，这也是本项目将自身定位为"安装即用的变通方法"而非完全安全的原因。

开发 / Development

npm run build          # tsc + 客户端/登录页/KDF worker bundle
npm test               # 全量测试（协议/引擎/登录/安全/端到端）
npm run test:protocol  # 仅协议用例

完整 18 字段配置表、升级与回归指南、性能基准（benchmarks/BENCHMARK.md）见 PROJECT.md 与 AGENTS.md。

完整的 18 字段配置表、升级与回归指南以及性能基准（benchmarks/BENCHMARK.md）位于 PROJECT.md 和 AGENTS.md 中。

关于本项目 / About This Project

本项目使用AI agent完成；不能保证没有bug/瑕疵。如有问题，请及时向我提出--谢谢！

本项目在 AI agent 的协助下构建；我们无法保证它没有 bug 或粗糙之处。如果你遇到任何问题，请告诉我——谢谢！

Created by Zcode/Idea from maomao

结语 / Conclusion

装上就可以直接用，但如果追求安全的话，还是再套层HTTPS吧。

装上就能直接用。但如果你追求安全性，不妨再套一层 HTTPS。