dsh-remote-agent 0.0.0-stage → 0.4.1

package/deploy/relay-vps/README.md

@@ -0,0 +1,132 @@
+# dsh-remote-relay VPS 部署模板
+
+一台公网小 VPS，把「双方都在 NAT 后」的 hub 与 node 会合到一起。
+本目录是**可直接抄的部署模板**；想一条命令装完请用仓库里的
+`scripts/relay-init.sh`（幂等，自动生成 unit 与凭证）—— 两者等价，
+本目录的存在是为了让人**在装之前就能看到将要发生的一切**。
+
+> 中继只做寻址与转发：不存任务、不碰产物字节、不解析业务帧。
+> 它挂了任务照跑（副机本地持久执行，重连后 task/sync 对账）——
+> 这是设计使然，见 profiles/README.md 的降级链一节。
+
+---
+
+## 0. 装之前想清楚的三件事
+
+1. **端口**：默认 `8890/tcp`。只给这两台机器用就把来源限到它们的出口 IP，
+   别对 `0.0.0.0/0` 开。
+2. **TLS**：只要中继暴露在公网，就必须前置 TLS 用 `wss://`
+   （明文 `ws://` 下 token 与业务帧都在裸奔）。模板见
+   [`Caddyfile`](./Caddyfile)（自动证书，最省事）或
+   [`nginx.conf`](./nginx.conf)（已有证书/自有 nginx 时用）。
+3. **凭证**：`hubToken` / `enrollToken` 一对，中继机器上生成，
+   **只走加密信道交给两端**。日志里只出现 12 位指纹，别把明文贴进工单。
+
+## 1. 五分钟上手（推荐：一键脚本）
+
+```bash
+# 在 VPS 上，进入包根（把仓库 scp/rsync 过去，或 git clone）
+sudo ./scripts/relay-init.sh                  # 默认 8890 / 0.0.0.0；幂等
+#   RELAY_PORT=9000 sudo ./scripts/relay-init.sh   # 换端口
+#   DRY_RUN=1 ./scripts/relay-init.sh              # 只看动作不落盘
+#   sudo FORCE_ROTATE=1 ./scripts/relay-init.sh    # 轮换凭证（已入网副机要重配）
+
+# 拿明文 token（只打一次；别重定向进文件、别贴聊天记录）
+node bin/dsh-remote-relay.js --print-tokens --data-dir /var/lib/dsh-remote-relay
+# → RELAY_TOKENS hub=rt_... enroll=en_... source=file
+
+# 自检
+curl -fsS http://127.0.0.1:8890/healthz
+# → {"ok":true,"protocol":1,"nodes":0,"hubs":0,"stats":{...}}
+journalctl -u dsh-remote-relay -f     # 看 RELAY_READY 与事件 JSON 行
+```
+
+脚本做三件事：建系统用户与数据目录（0700）→ 生成/复用凭证写
+`/etc/dsh-remote-relay/env`（0600）→ 装 systemd unit 并 `enable --now`。
+没有 systemd 的机器会打印可复制的 nohup 命令。重复执行不会轮换 token。
+
+## 2. 手动安装（不用脚本时）
+
+```bash
+# ① 用户与目录
+sudo useradd --system --home-dir /var/lib/dsh-remote-relay \
+  --create-home --shell /usr/sbin/nologin dsh-relay
+sudo install -d -m 0700 -o root -g root /etc/dsh-remote-relay
+sudo install -d -m 0700 -o dsh-relay -g dsh-relay /var/lib/dsh-remote-relay
+
+# ② 凭证（env 模板抄自本目录 relay.env.example，改占位符）
+sudo install -m 0600 -o root -g root relay.env.example /etc/dsh-remote-relay/env
+sudo -u dsh-relay node bin/dsh-remote-relay.js \
+  --data-dir /var/lib/dsh-remote-relay    # 首次自动生成 tokens.json
+
+# ③ unit（模板抄自本目录 dsh-remote-relay.service，改 <占位符>）
+sudo install -m 0644 dsh-remote-relay.service /etc/systemd/system/
+sudo systemctl daemon-reload && sudo systemctl enable --now dsh-remote-relay
+```
+
+## 3. 防火墙 / 云安全组
+
+| 云 | 做法 |
+|---|---|
+| 阿里云 / 腾讯云 等安全组 | 放行 `tcp/8890`，来源填两台机器的出口 IP |
+| `ufw` | `ufw allow from <副机IP> to any port 8890 proto tcp` |
+| `firewalld` | 加 rich rule，source 限两台机器 |
+| 裸机 iptables | `-p tcp --dport 8890 -s <IP> -j ACCEPT`，默认 DROP |
+
+套了 TLS 前置时，反向代理监听 443，中继本体只听 `127.0.0.1`——
+公网根本看不到 8890（`Caddyfile` / `nginx.conf` 模板即此形态）。
+
+## 4. TLS 前置（公网必做）
+
+```bash
+# Caddy（自动申请/续期证书；把 <域名> 换成你的）
+sudo cp Caddyfile /etc/caddy/Caddyfile && sudo systemctl reload caddy
+```
+
+```bash
+# nginx（证书用自己的；两个模板都要抄：sites-available + include 段）
+sudo cp nginx.conf /etc/nginx/sites-available/dsh-relay
+sudo ln -s /etc/nginx/sites-available/dsh-relay /etc/nginx/sites-enabled/
+sudo nginx -t && sudo systemctl reload nginx
+```
+
+套上之后两端地址全部换成 `wss://<域名>/relay`（端口 443 省略）：
+hub 的 `relay.url`、node 的 `relayUrl` 一起换，token 不变。
+healthz 与 `/api/relay/*` 也走 443（模板已含 HTTP 透传）。
+
+## 5. 验证连通
+
+```bash
+# ① 中继活着（有 TLS 时走 https）
+curl -fsS https://<域名>/healthz
+
+# ② 副机入网后，节点目录（只读；token 用 hub 那一半）
+curl -fsS "https://<域名>/api/relay/nodes?token=rt_xxx"
+# → {"nodes":[{"nodeId":"slave-pc","os":"windows","since":...,"lastSeen":...}]}
+
+# ③ hub 侧：DSH 里 remote_nodes → online:true
+```
+
+**对指纹，不对明文**：中继日志的 `RELAY_READY ... hub=<12位> enroll=<12位>`
+与两端配置的来源必须是同一套。`nodes:0` 但副机说 online → 两端 token 不是
+一套；`hubs:0` → hub 的 `relay.url`/`relay.token` 不对。
+
+## 6. 轮换、备份、卸载
+
+```bash
+# 轮换（会让已入网副机全部掉线，提前打招呼）
+sudo FORCE_ROTATE=1 ./scripts/relay-init.sh
+node bin/dsh-remote-relay.js --print-tokens --data-dir /var/lib/dsh-remote-relay
+
+# 备份只需一个文件（凭证真身）
+sudo tar czf relay-tokens.tgz /etc/dsh-remote-relay/env
+
+# 卸载（数据目录里没有任务状态，删不心疼）
+sudo systemctl disable --now dsh-remote-relay
+sudo rm -f /etc/systemd/system/dsh-remote-relay.service
+sudo rm -rf /etc/dsh-remote-relay /var/lib/dsh-remote-relay
+```
+
+---
+
+*端到端配置片段与排障表见 [profiles/README.md](../../profiles/README.md)。*

package/deploy/relay-vps/dsh-remote-relay.service

@@ -0,0 +1,47 @@
+# dsh-remote-relay systemd unit 模板
+#
+# 用法：把 <尖括号> 占位符换成实际值，安装到
+#   /etc/systemd/system/dsh-remote-relay.service
+# 或者直接用 scripts/relay-init.sh 一键生成等价比的一份（推荐）。
+#
+# 与一键脚本的差异只有一点：本文件把路径写成占位符，方便先审后装；
+# relay-init.sh 生成的是填好值的同一份。
+
+[Unit]
+Description=dsh-remote-agent relay (addressing + forwarding only)
+Documentation=https://github.com/zbzbhs/dsh-remote-agent
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+# 运行身份：专用系统用户，nologin
+User=dsh-relay
+Group=dsh-relay
+# 包根（bin/dsh-remote-relay.js 的上级目录）
+WorkingDirectory=<PKG_DIR>
+# 凭证与监听参数都来自 env 文件（0600，root:root）；文件不存在会启动失败，
+# 这是故意的——没有凭证的中继没有意义。
+EnvironmentFile=/etc/dsh-remote-relay/env
+ExecStart=<NODE_BIN> <PKG_DIR>/bin/dsh-remote-relay.js \
+  --port ${DSH_RELAY_PORT} --host ${DSH_RELAY_HOST} --data-dir ${DSH_RELAY_DATA_DIR}
+
+Restart=always
+RestartSec=3
+KillSignal=SIGTERM
+TimeoutStopSec=20
+
+# ── 加固（与 relay-init.sh 生成的一致，勿随意删） ──
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectSystem=strict
+ProtectHome=true
+# 唯一可写路径：数据目录（tokens.json 在这里）
+ReadWritePaths=/var/lib/dsh-remote-relay
+
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=dsh-remote-relay
+
+[Install]
+WantedBy=multi-user.target

package/deploy/relay-vps/nginx.conf

@@ -0,0 +1,49 @@
+# dsh-remote-relay 的 TLS 前置模板（nginx）
+#
+# 安装：sudo cp nginx.conf /etc/nginx/sites-available/dsh-relay
+#       sudo ln -s /etc/nginx/sites-available/dsh-relay /etc/nginx/sites-enabled/
+#       sudo nginx -t && sudo systemctl reload nginx
+#
+# 与 Caddyfile 模板二选一。nginx 不会自动签证书，<证书路径> 用你自己的
+# （certbot / 云厂商证书均可）。
+
+upstream dsh_relay {
+	server 127.0.0.1:8890;
+	keepalive 4;
+}
+
+server {
+	listen 443 ssl;
+	http2 on;
+	server_name relay.example.com;
+
+	ssl_certificate     /etc/ssl/certs/relay.example.com.fullchain.pem;
+	ssl_certificate_key /etc/ssl/private/relay.example.com.key;
+	ssl_protocols TLSv1.2 TLSv1.3;
+
+	# 中继是长连接 WS 转发，读超时必须放宽：副机空闲时也可能几分钟
+	# 没有业务帧（中继自己的 ping/pong 保活，见 lib/relay.js）。
+	proxy_read_timeout  1h;
+	proxy_send_timeout  1h;
+
+	location / {
+		proxy_pass http://dsh_relay;
+
+		# ── WebSocket 三件套（缺一不可） ──
+		proxy_http_version 1.1;
+		proxy_set_header Upgrade $http_upgrade;
+		proxy_set_header Connection "upgrade";
+
+		proxy_set_header Host $host;
+		proxy_set_header X-Real-IP $remote_addr;
+		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+		proxy_set_header X-Forwarded-Proto $scheme;
+	}
+}
+
+# HTTP 一律跳 HTTPS（ACME challenge 若要走 80 需另行放行）
+server {
+	listen 80;
+	server_name relay.example.com;
+	return 301 https://$host$request_uri;
+}

package/deploy/relay-vps/relay.env.example

@@ -0,0 +1,20 @@
+# dsh-remote-relay 环境文件模板
+#
+# 安装：sudo install -m 0600 -o root -g root relay.env.example /etc/dsh-remote-relay/env
+# 然后编辑占位符。systemd unit 通过 EnvironmentFile= 读它。
+#
+# 权限必须是 0600 root:root —— 这里面是两个凭证的明文。
+
+# 监听地址。套了 TLS 前置（Caddyfile / nginx.conf 模板）时填 127.0.0.1，
+# 公网只看到反向代理的 443；不套 TLS 才填 0.0.0.0（并务必把来源限到两端 IP）。
+DSH_RELAY_HOST=127.0.0.1
+DSH_RELAY_PORT=8890
+
+# 数据目录：tokens.json 落点（0700 dsh-relay:dsh-relay）
+DSH_RELAY_DATA_DIR=/var/lib/dsh-remote-relay
+
+# ── 凭证 ──────────────────────────────────────────────────────────────
+# hub 端凭证：只有主电脑（hub）用，拨入时以 x-relay-token header 携带
+DSH_RELAY_HUB_TOKEN=rt_REPLACE_WITH_GENERATED
+# 入网凭证：副机（node）用；也支持一次性 token（管理接口铸造，15 分钟有效）
+DSH_RELAY_ENROLL_TOKEN=en_REPLACE_WITH_GENERATED

package/docs/dispatch-automation-eval.md

@@ -0,0 +1,140 @@
+# 派发自动化评估：预授权令牌 vs 文档明示边界
+
+**状态**：评估结论（2026-10-15），未实施任何代码改动。
+**触发**：生态评估报告 P1-7 —— "当前派发受 DSH 会话围栏限制需人肉，
+评估提供预授权令牌机制或文档明示该边界为设计使然"。
+
+---
+
+## 0. 结论（先行）
+
+| 方案 | 决定 | 一句话理由 |
+|---|---|---|
+| **B. 文档明示边界** | **现在做** | 围栏是 pinned 的安全属性（doc-drift 11/12/13），当前无实证的自动化需求；先把边界写清楚，让用户知道脚本该走哪条路 |
+| **A2. 短时令牌（桌面端铸造、脚本兑换）** | **预设计，不实施** | 设计正确、与仓内一次性 enroll token 同构；等出现真实需求再作为 minor 落地，本文第 4 节给出完整设计草图 |
+| **A1. 静态 automationToken** | **明确拒绝** | 在公网可暴露的 hub 上放一个无过期、可移植的 bearer secret，泄露面与 `sshpass -p` 同级；没有场景需要"永久有效" |
+
+**给用户的答案（一句话）**：派发任务的脚本化入口今天**故意不存在**——
+hub 的 webserver 整台被 DSH 会话围栏保护（实测除 `/healthz` 外一律 401），
+这是安全设计生效的证据。需要自动化时，驱动 DSH 自身的会话
+（`remote_task` 工具）是唯一受支持的路径；纯 HTTP 脚本无路可走是**设计使然，
+不是缺陷**（KNOWN-ISSUES §8 第 3 条同结论）。
+
+---
+
+## 1. 问题定义
+
+**派发自动化** = 不经人手、不看桌面面板，由脚本/CI/定时器向副机下达任务。
+典型场景： nightly 构建后自动派测试任务、看板系统联动、批量数据整理。
+
+**要评估的能力**：`POST /api/remote-agent/ui/dispatch` 对**非桌面会话**
+调用方开放。注意这不是"读数据"——dispatch 是**下命令**：`mode: exec`
+直接在副机跑 shell（SECURITY.md 明示"不限制副机能执行的命令"），
+所以这道的后面是副机上的任意代码执行。
+
+## 2. 现状事实链（全部可复现）
+
+| # | 事实 | 证据 |
+|---|---|---|
+| 1 | UI 路由**刻意复用** DSH 框架围栏，不另造鉴权 | `lib/hub/ui-routes.js` makeGuard 注释：`requestRejection` 的官方用途就是 "apply ... to **another** Web route" |
+| 2 | 围栏**失败关闭**：抛错 → 403，绝不放行 | 同文件 catch 分支；doc-drift 断言 12 锚定 |
+| 3 | 无 connection 服务时退回 sameOriginOk：无 Origin 放行 / 跨站 403 | `lib/hub/ui-routes.js` sameOriginOk |
+| 4 | **真实 DSH 运行时**：除 `/healthz` 外整台 401（桌面渲染器外） | KNOWN-ISSUES §8 第 3 条，DSH 0.2.0-rc.2 实测；`scripts/e2e-live-check.mjs` 文件头同记录 |
+| 5 | 因此 e2e-live-check 的派发步骤只能人肉 | 同上线索 + KNOWN-ISSUES §8「这一步需要人的原因」 |
+| 6 | 副机入网口（`/api/remote-agent/node`）对外开放，但 nodeToken 只让你**成为节点**（接收任务），不能派发 | `lib/hub/node-registry.js` attachDirect；profiles/README.md 路径二 |
+| 7 | 今天唯一的脚本化派发路径 = 驱动 DSH 自身会话（remote_task 工具） | README 用法节；工具经 DSH agent loop，围栏内 |
+
+**推论**：围栏挡住的不是"坏人"（那有 nodeToken/roots 管），而是
+"非桌面会话的调用方"——包括脚本。而 hub 属主本来就能从桌面派任何任务，
+所以围栏的真实语义是**「下令权绑定在桌面会话上」**，不是"下令权需要密码"。
+
+## 3. 已存在的替代缓解（为什么现在不做也不堵）
+
+1. **驱动 DSH 会话**：`remote_task` 是受支持的派发 API，自动化脚本可以
+   操作 DSH 的会话/工具层（DSH 自身能力，不归本插件管）。
+2. **relay 的一次性 enroll token 已是同构先例**：短 TTL、用过即焚、
+   只存中继内存（`lib/relay.js` mintToken）——证明本仓有能力做好
+   "预授权"这回事，缺的不是技术，是需求信号。
+3. **面板 pair-info 的 loopback 披露边界**：连"生成配对码"都只敢在
+   回环给全码（doc-drift 45）——插件对凭证披露的整体口径是收紧的，
+   单独给派发开一个Bearer大门与这个口径相冲。
+
+## 4. A2 设计草图（预设计，供未来 minor 直接施工）
+
+> 原则：**铸造必须经过桌面会话，兑换只给派发族路由，窗口短，可审计。**
+
+### 4.1 形态
+
+```
+桌面面板/会话 ──POST /ui/automation-token（会话围栏内）──► hub 内存
+   返回 { token: 'dt_...', expiresInMs: 900000, maxUses: 1 }   （默认 15 分钟 / 单次）
+脚本 ──POST /ui/dispatch  Header: x-dsh-remote-automation: dt_...──► 派发成功
+```
+
+### 4.2 约束（缺一不可，全部进 doc-drift）
+
+| 约束 | 原因 |
+|---|---|
+| 铸造路由在会话围栏内（不豁免） | 铸造权 = 桌面在座；豁免它就等于 A1 |
+| 兑换只放行 `dispatch` / `cancel` 两条 | **绝不放行** `pair-info`（披露凭证）、`pull`（写盘）、`config`（配置视图）、四个只读路由 |
+| token 只存内存，不落盘；TTL 默认 15min；默认单次 | 与 relay oneTime token 同策略（`lib/relay.js:118`），进程重启即失效 |
+| 比较用 timingSafeEqual，失败关闭 | 复用 relay.js safeEqual 模式；围栏抛错 → 403 |
+| 每次兑换写审计日志（nodeId + goal 长度 + token 指纹） | 可观测；不记 goal 正文（可能含秘密） |
+| `hub` 公网暴露时 SECURITY.md 明示：等同把下令权交出去 | 与 direct 模式 TLS 要求同一口径 |
+
+### 4.3 施工清单（≈1–1.5 人日，含测试与文档）
+
+1. `lib/hub/ui-routes.js`：automation-token 铸造路由 + guard 的 token 分支
+   （scope 白名单硬编码，不读配置——**不给自己留"以后放宽"的开关**）；
+2. `lib/client.js`：面板加「生成自动化令牌」按钮（与副机接入卡片同风格）；
+3. 测试：铸造→兑换 happy path、过期拒、超用拒、错 token 401、
+   pair-info 持 token 仍 401、guard 抛错失败关闭；
+4. doc-drift：scope 白名单断言（pair-info 永不在内）+ 铸造路由在围栏内；
+5. SECURITY.md 新增「自动化令牌」节；KNOWN-ISSUES §8 第 3 条补链接。
+
+### 4.4 工作量评估
+
+| 部分 | 量 |
+|---|---|
+| 路由 + guard + 内存 TTL 表 | ~120 行 |
+| 面板按钮 | ~40 行（复用 pair-info 模式） |
+| 测试 + doc-drift | ~150 行 |
+| 文档（SECURITY/profiles/CHANGELOG） | ~80 行 |
+
+真正的成本不是代码是**评审负担**：这是本插件第一次在会话围栏上开洞，
+每一行都要按"开洞"标准审。
+
+## 5. A1 为什么明确拒绝
+
+`automationToken` 静态配置看起来只多一行 config，但它是：
+
+1. **公网面上的便携静态 secret** —— direct 模式的 hub 本就在公网，
+   bearer token 进 shell history / CI log / 代理访问日志的成本远比
+   桌面会话 cookie 低（cookie 不落地、随会话消亡）；
+2. **无过期、可无限次用** —— 泄露即永久交出下令权，而 dispatch 的
+   后面是副机 shell；
+3. **与仓内口径相冲** —— relay 的一次性 token、pair-info 的 loopback
+   披露、icacls 0600，每个凭证决策都是"缩短暴露窗口"方向，A1 是唯一
+   反方向的；
+4. **没有场景需要永久有效** —— 定时任务用 A2 每次铸造即可（或接受
+   "定时任务先调 DSH 会话"）。
+
+## 6. 文档明示边界（B）的落点
+
+已写入 / 待写入：
+
+- 本文档（决策记录 + A2 预设计）；
+- KNOWN-ISSUES §8 第 3 条：补链接到本文；
+- README 安全节 / profiles/README 排障表：各加一行"脚本派发？
+  设计使然，见 docs/dispatch-automation-eval.md"；
+- 若未来实施 A2：CHANGELOG 记 minor，SECURITY.md 开节，本文档状态
+  改为"已实施"并指向实现。
+
+## 7. 风险与复审触发条件
+
+出现以下任一信号时复审本结论（直接按 §4 施工 A2）：
+
+- 有用户/Issues 明确要求脚本化派发（≥2 次独立请求）；
+- 出现"定时任务 + 副机"的真实场景描述（而非设想）；
+- DSH 自身提供了 headless 会话能力，使"驱动 DSH 会话"路径变轻
+  （此时 B 的缓解 #1 更强，可能继续不做）。