Remote-My-DSH

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

No — I don't want DSH to live on localhost alone. So this exists: a login gate for DSH that carries DSH's content self-encrypted over HTTP, or rides safely inside HTTPS. (With a bit of UI adaptation for phone access, too.)

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

(But: remote access without HTTPS is only "as safe as we could make it" — an active man-in-the-middle can replace the page, so it doesn't really count as secure; it's an install-and-use workaround.)

一、它是什么 / What It Is

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

A remote-access gateway plugin for the DeepSeek Harness (DSH) Web UI: install it into DSH, and it starts and stops together with DSH. Once installed, the Web UI no longer belongs to localhost alone — AEAD self-encryption, challenge-response auth, sessions, and audit each do their job behind the login gate. But if you need true end-to-end security, you need HTTPS.

二、给想用的人 / For Users

主要功能 / Key Features

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

• Zero-config startup: listens on http://localhost:3443 by default — just open it and sign in. From a phone or another machine, open it via the LAN IP, no extra configuration needed.
• Multiple scenarios: LAN direct, corporate intranet, home IPv6 out, public relay — all four come with templates in examples/; copy and tweak.
• Session resumption: your session stays valid while the browser is online; reopening within 2 hours of a disconnect resumes automatically without re-entering the token. Tick "Remember this device" to skip login on your next visit.
• Mobile UI adaptation: the login page and settings panel are adapted for phone access.

快速开始 / Quick Start

# 方式一：从 npm 安装（推荐）/ Option 1: install from npm (recommended)
dsh plugin --profile web add remote-my-dsh
remote-my-dsh enable                                       # 开启网关（或 DSH 设置里点启用）/ enable the gateway (or toggle it on in DSH settings)

# 方式二：从 GitHub Release 下载安装 / Option 2: install from a GitHub Release
# 在 https://github.com/OneCat2015/Remote-My-DSH/releases 下载 remote-my-dsh-0.1.0.tgz
# Download remote-my-dsh-0.1.0.tgz from https://github.com/OneCat2015/Remote-My-DSH/releases
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。

First enable generates a random token, verifier, and pepper, and prints the access URL. Notes: reinstalling a same-version tgz may reuse the pnpm cache — remove first, then add; listening on a LAN interface for the first time triggers a Windows Firewall prompt — allow it once; dsh plugin --profile web add remote-my-dsh pulls the latest version from the npm registry, and upgrades likewise need remove before 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/叶证书/私钥三件套

Command	Description
remote-my-dsh enable	One-click enable: write gateway.yml, generate a verifier, print the access URL
remote-my-dsh token / token --rotate	Show / rotate the token (keeps live sessions alive; old-token login and recovery credentials are invalidated)
remote-my-dsh token --disable	Disable the token, close the entry
remote-my-dsh status	Listen address, encryption mode, session policy, recent audit
remote-my-dsh ca	Export the self-signed root CA (tls: auto) with install guidance; the settings-API download validates and repairs the current CA/leaf cert/private-key trio first

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

Configuration can also be edited directly in DSH's Web UI — the localhost page hosted by DSH itself, not a page hosted by this plugin.

常用配置 / Common Configuration

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

字段	默认	说明
port	3443	监听端口
tls	off	auto = 自签，<路径> = 真证书
crypto	auto	数据面自加密
session	browser+2h	浏览器在线，断线保存 2 小时可续
refresh	12h	"记住此设备"恢复凭据有效期
tokenLifetime	permanent	访问令牌自动轮换周期：once = 登录成功后立即轮换一次；时长档到期自动轮换；permanent = 不自动轮换。轮换不杀已保持会话，但会使已记住设备的免登录恢复失效

Field	Default	Description
port	3443	Listening port
tls	off	auto = self-signed, <path> = a real certificate
crypto	auto	Self-encryption of the data plane
session	browser+2h	Browser-online sessions; resumable for 2 hours after disconnect
refresh	12h	Validity of the "Remember this device" recovery credential
tokenLifetime	permanent	Automatic access-token rotation period: once = rotate once right after a successful login; a duration rotates on expiry; permanent = never rotate. Rotation keeps live sessions alive but invalidates "remembered device" auto-login

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

Important: remote access without TLS is plaintext HTTP — the data content is encrypted, but the page itself cannot defend against an active man-in-the-middle. On untrusted networks or when transmitting sensitive content, configure tls: auto (self-signed) or a real certificate first.

三、给想了解的人 / 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 明文放行。

The gateway is the single external entry, standing in front of DSH's inner webServer (which must bind to 127.0.0.1). The flow: unauthenticated requests are 302'd to the login page → a challenge-response handshake (one-time challenge with a short TTL; the proof never carries the token) → once the key is confirmed, a session key Ks is established → from then on all /api and WebSocket event streams are reverse-proxied to inner DSH as AEAD frames via /api/rpc. The real method, path, and semantic headers exist only inside the ciphertext; static assets pass through in plaintext behind a 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 highlights: PROTOCOL_VERSION = 2 (ChaCha20-Poly1305 frames; the 21-byte frame header holds only sessionId + dir + seq); Ks = HKDF(k ‖ ECDH, salt) with one-time P-256 and forward secrecy; per-direction subkeys plus a session-level seq window prevent replay; 24-hour chained rotation. The gateway uses the native node:crypto engine while the browser uses the pure-JS noble engine — byte-for-byte identical (verified by tests/engine.test.js). Full spec in 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 时仅作参考。

What it protects against: passive sniffing/DPI cannot read the content; storage compromise (verifier pepper encryption); login-proof replay (one-time challenge); ciphertext replay and tampering (AEAD + seq); "record traffic now, steal the token later, decrypt past sessions" (forward secrecy); in-transit tampering of login parameters while the real login page hasn't been replaced (Ed25519 signature). There are also code-level constraints: non-loopback with crypto:off refuses to start outright, the only gate being an explicit allowInsecureRemote: true (written to the warn audit) — remote plaintext is allowed only when the data plane is encrypted. The login page can also display the current TLS leaf-certificate SHA-256 fingerprint, SAN, and signing-public-key ID; with tls:off this is informational only.

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

What it does NOT protect against: page-level active MITM under plaintext HTTP — the signature-verification code can be replaced along with the whole page, so nothing can be proven; application XSS — Ks lives in page memory and DSH renders the output, so it can't be rooted out. The answer to both is TLS, which is also why this project positions itself as an "install-and-use workaround" rather than fully secure.

开发 / Development

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

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

The complete 18-field configuration table, upgrade & regression guide, and performance benchmarks (benchmarks/BENCHMARK.md) live in PROJECT.md and AGENTS.md.

关于本项目 / About This Project

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

This project was built with the help of an AI agent; we can't guarantee it's free of bugs or rough edges. If you run into anything, please let me know — thanks!

Created by Zcode/Idea from maomao

结语 / Conclusion

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

Install it and it just works. But if you're after security, you might as well wrap it in HTTPS.