dsh-vpn 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AIcivilization
+
+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

@@ -0,0 +1,114 @@
+# dsh-vpn
+
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件：在 dsh 里填好 VPS 的 IP、端口、用户名和密码，一键部署 sing-box，然后扫二维码导入代理客户端。
+
+- **不依赖本机的 ssh 命令**：内置纯 JS 的 SSH 客户端（[ssh2](https://github.com/mscdex/ssh2)），用密码登录。
+- **两种用法**：在设置页点按钮，或者直接对 agent 说“帮我装个节点”。
+- **五种协议可选**：VLESS Reality、Hysteria2（默认）、TUIC v5、AnyTLS、Shadowsocks 2022。
+- **免域名的正规证书**：可选 Let's Encrypt 为服务器 IP 签发的证书，所有客户端都能正常校验证书。
+
+## 使用
+
+```bash
+dsh plugin --profile web add dsh-vpn
+```
+
+打开 dsh →「插件」→ dsh-vpn：
+
+1. 填写服务器 IP、SSH 端口、用户名、密码，点「保存」和「测试连接」。
+2. 勾选要安装的协议，选择证书类型（推荐「IP 证书」），保存后点「安装 / 更新」。
+3. 在「节点二维码」里点「刷新」，用手机或电脑上的客户端扫码导入。
+4. 在云服务商控制台的安全组里放行页面提示的端口。用 IP 证书时，TCP 80 端口要一直开放，用于续期。
+
+## 证书
+
+| 类型 | 适合 | 客户端校验 |
+|---|---|---|
+| 自签证书（默认） | 不想开放 80 端口 | Hysteria2 锁定证书指纹；TUIC 和 AnyTLS 的链接无法锁定，客户端会跳过校验 |
+| IP 证书（推荐） | 大多数情况 | 所有协议都正常校验证书，不需要域名 |
+
+IP 证书由 sing-box 1.14 内置的 ACME 向 Let's Encrypt 申请（[2026 年起正式提供](https://letsencrypt.org/2026/01/15/6day-and-ip-general-availability)），通过 80 端口完成 HTTP 验证。证书有效期 6 天，由 sing-box 自动续期。
+
+- 签发失败（常见原因是 80 端口没开）：自动退回自签证书，节点仍可使用，页面会提示原因。
+- 80 端口被其他程序占用：直接拒绝，不改动正在运行的节点。
+- 「查看状态」会显示证书剩余时间；剩余不到 24 小时仍未续期时会发出警告，因为证书过期后客户端将无法连接。
+
+## 安全设计
+
+| 方面 | 做法 |
+|---|---|
+| 密码存储 | 存在 dsh 凭据库（`$DSH_HOME/.credentials.yaml`，权限 0600），不写进配置文件；浏览器只能写入，读不回来 |
+| 接口鉴权 | 设置页的接口挂在 dsh 自己的 `/api` 下，复用 dsh 的登录 cookie 和防跨站、防 DNS rebinding 检查 |
+| 主机指纹 | 首次连接时记录 SSH 主机指纹，之后指纹变化就拒绝连接，防止中间人截获密码 |
+| sudo | 非 root 用户用 `sudo -S`：密码只经 stdin 传入，不会出现在命令行，也不会传给脚本 |
+| agent 操作 | agent 安装或卸载前会弹出审批，提示语言跟随电脑系统语言，并写明目标服务器、协议，以及是否重新生成密钥 |
+| 证书 | 推荐用 IP 证书，所有协议都正常校验；自签模式下 Hysteria2 锁定指纹，TUIC 和 AnyTLS 会标注“需跳过证书校验” |
+
+## 组成
+
+| 路径 | 作用 |
+|---|---|
+| `scripts/vpn.sh` | 在服务器上运行的安装脚本，也可以单独使用：`ssh vps 'sudo bash -s -- install --protocols reality,hy2' < scripts/vpn.sh` |
+| `src/ssh.ts` / `src/remote.ts` | SSH 连接、主机指纹锁定、上传并执行脚本 |
+| `src/core.ts` | 统一的操作入口（设置页和 agent 共用），同一时间只执行一个操作 |
+| `src/settings.ts` / `src/credential-store.ts` | 服务器设置的校验和存储 |
+| `src/api.ts` | 设置页调用的 `/api/dsh-vpn/*` 接口 |
+| `src/index.ts` | agent 工具 `vpn_install` / `vpn_status` / `vpn_links` / `vpn_uninstall`，以及执行前的审批 |
+| `src/client/` | 浏览器端：设置页、二维码 |
+| `src/skill.ts` + `assets/vpn-ops.md` | `vpn-ops` 技能：操作流程和排障 |
+
+## 远端落盘位置
+
+- `/usr/local/bin/sing-box`
+- `/etc/dsh-vpn/`：`state.env`（密钥、端口、已选协议、证书类型）、`config.json`、`cert/`（自签证书）、`acme/`（IP 证书，由 sing-box 维护）
+- `/etc/systemd/system/dsh-vpn.service`
+- `/etc/sysctl.d/99-dsh-vpn.conf`：开启 BBR
+
+## 开发与测试
+
+```bash
+pnpm install
+pnpm test            # 单元测试（进程内的假 SSH 服务器，不联网）
+pnpm build           # lib/：宿主端 tsc 转译 + 浏览器端 esbuild 打包
+DSH_SRC=/path/to/deepseek-harness pnpm typecheck   # 对照 dsh 源码做宿主端和浏览器端的类型检查
+```
+
+`build` 用 esbuild 把 `ssh2` 打包进 `lib/`，所以发布到 npm 的包没有任何运行时依赖，也就没有安装脚本。这是必须的：dsh 自带的 pnpm 11 在依赖的安装脚本被跳过时会让 `dsh plugin add` 直接失败。被打包的第三方库的许可证见 `THIRD_PARTY_NOTICES.md`。
+
+npm 上的 `@deepseek-ai/*` 包版本过旧，所以 `build` 不做类型检查，类型检查对照 dsh 源码单独进行。
+
+## 发布
+
+推送与 `package.json` 版本号一致的标签，GitHub Actions 会先跑测试，再发布到 npm，并附带来源证明（provenance）。需要在仓库 Secrets 里配置 `NPM_TOKEN`：
+
+```bash
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+端到端测试会在目标机器上**安装再卸载**，并用 sing-box 客户端实测每种协议的连通性。本地可以用 [Lima](https://lima-vm.io) 虚拟机：
+
+```bash
+limactl start --name=vps --vm-type=vz --network=vzNAT --set '.mounts=[]' template:ubuntu-24.04
+# 在虚拟机里开启 sshd 的密码登录并设置密码，然后：
+DSH_VPN_E2E_HOST=192.168.64.2 DSH_VPN_E2E_USER=root DSH_VPN_E2E_PASSWORD=… pnpm test:e2e
+```
+
+IP 证书的测试需要一个本地 ACME 服务器，用 Let's Encrypt 官方的 [Pebble](https://github.com/letsencrypt/pebble) 模拟。**只能在测试虚拟机上运行**，因为它会把 Pebble 的根证书加入系统信任：
+
+```bash
+ssh 测试机 'sudo bash -s' < tests/e2e/pebble-setup.sh
+DSH_VPN_E2E_ACME=https://localhost:14000/dir DSH_VPN_E2E_HOST=… pnpm test:e2e
+```
+
+在插件配置里设置 `acmeProvider`，就可以让插件改用 Pebble 或其他 ACME 服务器。
+
+## TODO
+
+- [ ] SSH 私钥登录
+- [ ] 导出客户端配置文件（sing-box / mihomo）和订阅链接
+- [ ] 可自定义 Reality 的 SNI、协议端口
+- [ ] 证书使用自己的域名（DNS 验证：Cloudflare / 阿里云）
+- [ ] IPv6 的 IP 证书（目前只在 IPv4 上验证过）
+- [ ] 支持 OpenRC（Alpine）和 iptables/nftables
+- [ ] 支持 GitHub 下载镜像
+- [ ] 在真实 VPS 上跑端到端测试（Debian 12 / Ubuntu 24.04 / Rocky 9）

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,177 @@
+# Third-party notices
+
+lib/ bundles the following packages.
+
+## asn1@0.2.6 (MIT)
+
+```
+Copyright (c) 2011 Mark Cavage, All rights reserved.
+
+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
+```
+
+## bcrypt-pbkdf@1.0.2 (BSD-3-Clause)
+
+```
+The Blowfish portions are under the following license:
+
+Blowfish block cipher for OpenBSD
+Copyright 1997 Niels Provos <provos@physnet.uni-hamburg.de>
+All rights reserved.
+
+Implementation advice by David Mazieres <dm@lcs.mit.edu>.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. The name of the author may not be used to endorse or promote products
+   derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+
+The bcrypt_pbkdf portions are under the following license:
+
+Copyright (c) 2013 Ted Unangst <tedu@openbsd.org>
+
+Permission to use, copy, modify, and distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+
+
+Performance improvements (Javascript-specific):
+
+Copyright 2016, Joyent Inc
+Author: Alex Wilson <alex.wilson@joyent.com>
+
+Permission to use, copy, modify, and distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+```
+
+## safer-buffer@2.1.2 (MIT)
+
+```
+MIT License
+
+Copyright (c) 2018 Nikita Skovoroda <chalkerx@gmail.com>
+
+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.
+```
+
+## ssh2@1.17.0 (MIT)
+
+```
+Copyright Brian White. All rights reserved.
+
+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.
+```
+
+## tweetnacl@0.14.5 (Unlicense)
+
+```
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <http://unlicense.org>
+```

package/assets/vpn-ops.md

@@ -0,0 +1,46 @@
+# vpn-ops
+
+Deploy and operate a personal sing-box server on the user's VPS. The plugin logs in over SSH with the password saved on its settings page (dsh → Plugins → dsh-vpn). No local ssh client is needed.
+
+## Workflow
+
+1. **Check first.** Call `vpn_status`.
+   - `error: not_configured` → tell the user to open dsh → 插件 (Plugins) → dsh-vpn, fill in server IP, SSH port, username and password, then click 保存 and 测试连接. Never ask for the password in chat.
+   - Installed and active → offer `vpn_links` instead of reinstalling.
+2. **Install.** Call `vpn_install`. Omit `protocols` to use the selection saved in settings. Only pass `regenerate: true` when the user explicitly wants new keys, because every old link stops working.
+3. **Deliver.** Say the links are ready and that the settings page shows scannable QR codes (刷新 button). Client apps: v2rayN, NekoBox, Shadowrocket, sing-box, Clash Meta / mihomo.
+4. **Remind** the user to open the reported ports in the cloud provider's security group, using the right transport for each protocol.
+
+## Certificates
+
+The settings page offers **self-signed** (default) or **IP certificate** (recommended): a Let's Encrypt certificate for the server IP, issued and renewed automatically by sing-box. With it, every client verifies normally and no link needs "skip certificate verification". It needs TCP port 80 open at all times for renewal; the certificate lasts 6 days.
+
+## Protocols
+
+| id | Name | Transport | Notes |
+|---|---|---|---|
+| `reality` | VLESS Reality | TCP | Default. Hardest to detect. |
+| `hy2` | Hysteria2 | UDP | Default. Fast on lossy links; the link pins the certificate. |
+| `tuic` | TUIC v5 | UDP | With a self-signed cert, clients skip verification; with an IP certificate, they verify normally. |
+| `anytls` | AnyTLS | TCP | Same as TUIC. |
+| `ss` | Shadowsocks 2022 | TCP+UDP | Widely supported; no TLS disguise. |
+
+## Troubleshooting
+
+| Error / symptom | Likely cause | What to do |
+|---|---|---|
+| `auth_failed` | Wrong username or password | User fixes it on the settings page |
+| `host_key_mismatch` | Server reinstalled or replaced, or a man-in-the-middle | Ask whether the server was reinstalled. Only then may the user click 重置指纹 (Reset fingerprint) |
+| `connect_failed` / `timeout` | Wrong IP or port, SSH blocked, server down | Check the IP and SSH port on the settings page |
+| `sudo_failed` | User is not root and lacks sudo, or the sudo password differs | Use root, or grant sudo |
+| `no_systemd` | Container or OpenRC VPS | Not supported yet |
+| `download_failed` | VPS cannot reach GitHub | Retry later |
+| `cert_failed` | IP certificate not issued (usually port 80 closed). The node fell back to self-signed and still works | Open TCP 80 in the security group, then install again |
+| `port80_in_use` | Another program (nginx, …) holds port 80 | Stop it, or use self-signed |
+| Status says the certificate expires within 24 h or has expired | Renewal failing | Open TCP 80; an expired certificate breaks every TLS protocol |
+| Installed and active, but the client times out | Cloud security group or upstream firewall | Open the TCP/UDP ports in the cloud console |
+| Reality fails, others work | SNI site blocked | Reinstall with another SNI (future option) |
+| UDP protocols fail, TCP works | ISP blocks or throttles UDP | Use Reality or AnyTLS |
+| Everything stopped after working | IP blocked | `vpn_install` with `regenerate: true` for new ports; if it is still blocked, the IP must change |
+
+Never paste passwords, private keys or the state file into chat. Share links are secrets too: show them only to the user.

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+- insert:
+    - id: vpn
+      name: dsh-vpn
+      # Server, password and protocols are set on the plugin's settings page
+      # (stored in dsh's credential store, not here).
+      config: {}
+      # config:
+      #   timeoutMs: 600000   # per-operation deadline
+      #   confirm: true       # ask before the agent installs/uninstalls
+    - id: vpn-skill
+      name: dsh-vpn/skill