dsh-remote-bridge 2.5.1 → 2.6.0

package/README.en.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-v2.5.1-087f8c">
+  <img alt="Version" src="https://img.shields.io/badge/version-v2.6.0-087f8c">
   <img alt="DSH plugin" src="https://img.shields.io/badge/DeepSeek_Harness-plugin-1f2328">
   <img alt="Platforms" src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-586069">
   <img alt="License" src="https://img.shields.io/badge/license-AGPL--3.0-2da44e">
@@ -102,10 +102,10 @@ dsh plugin --profile web add dsh-remote-bridge
 dsh plugin --profile web add dsh-remote-bridge --registry https://registry.npmmirror.com
 
 # 2. tarball from the GitHub release
-dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.5.1/dsh-remote-bridge-v2.5.1.tgz
+dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.6.0/dsh-remote-bridge-v2.6.0.tgz
 
 # 3. tarball from the Gitee release (faster from mainland China)
-dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.5.1/dsh-remote-bridge-v2.5.1.tgz
+dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.6.0/dsh-remote-bridge-v2.6.0.tgz
 
 npx @deepseek-ai/dsh web
 ```
@@ -122,7 +122,7 @@ Restart DSH after installation, then open settings — The section is titled **
 To install a downloaded release archive:
 
 ```sh
-dsh plugin --profile web add ./dsh-remote-bridge-v2.5.1.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.6.0.tgz
 ```
 
 ## First connection
@@ -352,28 +352,31 @@ pnpm check
 pnpm pack
 ```
 
-`pnpm check` covers type-checking, documentation consistency, and tests. It currently passes **30 test files / 226 cases**, plus **4 browser-layer cases** (Playwright measuring real computed styles).
+`pnpm check` covers type-checking, documentation consistency, and tests. It currently passes **67 test files / 557 cases**, plus **8 browser-layer cases** (Playwright measuring real computed styles, including the 375px narrow-viewport contract).
 
-`npm pack` produces roughly a **0.55 MB** archive (v2.5.0 measured 572,951 bytes, SHA-256 `38f25c10…299c93`): 2.2.0 dropped the standalone page and its editor dependencies and turned source maps off, down from 1.72 MB; it has since grown slightly with projection passthrough and the permission BFF.
+`npm pack` produces roughly a **0.61 MB** archive (v2.5.2 measured 635,325 bytes, SHA-256 `18d36904…c8095`): 2.2.0 dropped the standalone page and its editor dependencies and turned source maps off, down from 1.72 MB; it has since grown slightly with projection passthrough, the permission BFF, and the five-dimension hardening.
 
 v2.5.0 was verified on DSH **0.2.1-rc.2** on real hardware: all 14/14 host services injected, the three jobs endpoints exercised, and the permission catalog returned the kernel's real three presets. The development baseline is upstream `dsh-v0.2.1-rc.2` (commit `687f282e8625c6b8d11ff58211a90524be2e4317`); see `engines.dsh` above for the supported range. CI covers Windows, Ubuntu, and macOS.
 
-**v2.5.1 verification status**: 47 test files / 398 cases green (including the tunnel-topology
-management regression, the desktop-panel pass-through assertion, and the `it.fails` conversions),
-`typecheck` and `docs:check` pass, and the audit report's §3.1 attack chain was replayed against a real
-`RemoteApiServer` (now 403 for every step). **Not yet verified on real hardware**, and not published to
-npm or either release site — i.e. "not published ≠ not verified ≠ users have it".
+**v2.6.0 verification status**: 70 test files / 593 cases green, plus 8 Playwright browser cases
+(including the 375px narrow-viewport contract); `typecheck`, `docs:check`, and the build all pass.
+All three rounds of real-hardware tunnel regressions were reproduced and verified on a
+React18 + Playwright click harness (one-click token issuance, the stop-tunnel escape hatch, and the
+locked state when re-entering settings), then confirmed by manual testing on the user's machine.
 
 ## Project
 
-- Version: `v2.5.1`
-- **v2.5.1 is a security release**: it closes a remote privilege escalation where `/manage/**`
-  and the loopback admin header were granted to any request whose TCP source looked like loopback —
-  which is exactly what a Cloudflare tunnel (or any reverse proxy) makes every public request look like.
-  It also fixes `.heif` handoff images, which were always rejected with 415 by the read-only route.
-  After upgrading, **`/manage` returns 403 whenever the tunnel is running** (the only exceptions are the
-  read-only tunnel-status endpoints, which hide the tunnel URL from non-local callers); the desktop panel
-  is unaffected. See `docs/project/SECURITY.md` §「管理面的信任边界」.
+- Version: `v2.6.0`
+- **v2.6.0 is the plugin-settings + IM-entry release**: it adds the per-plugin settings namespaces (`GET /api/v1/settings/namespaces`, `PATCH .../{ns}`) so the app can build the form from the kernel schema, and two entry points for "I am out and the desktop is still locked" — the host command `/tunnel` and the tool `open_tunnel_config`; plus one-tap pruning of unused devices, the audit page removed, and a guard so a failing optional registration cannot tear down the whole plugin context.
+- **v2.5.2 is a comprehensive hardening release**: it lands the five-dimension audit
+  (security, features, performance, UI, button feedback) — including the unauthenticated
+  `debug/host-services` information disclosure fix, dual-bucket rate limiting, broadcast backpressure,
+  weak ETags, and audit retention — and makes "start tunnel & generate token" complete inside a single
+  request. While the tunnel runs, the management surface is safely locked with only "stop tunnel"
+  available, restoring automatically afterwards. v2.5.1's security model (403 on `/manage` while a tunnel
+  runs, the four-layer admin criteria) is unchanged; see `docs/project/SECURITY.md` §「管理面的信任边界」.
+- **v2.5.1 was the security release**: it closed the remote privilege escalation and the `.heif`
+  handoff-image 415 bug described in the changelog.
 - Author: upstream [Hakunm](https://github.com/Hakunm); this fork maintained by [westanke](https://github.com/westanke)
 - Repository: [GitHub](https://github.com/westanke/dsh-remote-bridge) · [Gitee](https://gitee.com/westanke/dsh-remote-bridge)
 - npm: [`dsh-remote-bridge`](https://www.npmjs.com/package/dsh-remote-bridge) ([mainland-China mirror](https://registry.npmmirror.com/dsh-remote-bridge))

package/README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-v2.5.1-087f8c">
+  <img alt="Version" src="https://img.shields.io/badge/version-v2.6.0-087f8c">
   <img alt="DSH plugin" src="https://img.shields.io/badge/DeepSeek_Harness-plugin-1f2328">
   <img alt="Platforms" src="https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-586069">
   <img alt="License" src="https://img.shields.io/badge/license-AGPL--3.0-2da44e">
@@ -93,10 +93,10 @@ dsh plugin --profile web add dsh-remote-bridge
 dsh plugin --profile web add dsh-remote-bridge --registry https://registry.npmmirror.com
 
 # ② GitHub Release 的 tarball
-dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.5.1/dsh-remote-bridge-v2.5.1.tgz
+dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.6.0/dsh-remote-bridge-v2.6.0.tgz
 
 # ③ Gitee Release 的 tarball（国内访问更快）
-dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.5.1/dsh-remote-bridge-v2.5.1.tgz
+dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.6.0/dsh-remote-bridge-v2.6.0.tgz
 
 npx @deepseek-ai/dsh web
 ```
@@ -112,7 +112,7 @@ npx @deepseek-ai/dsh web
 从 GitHub Release 下载离线安装包时，可直接安装 tarball：
 
 ```sh
-dsh plugin --profile web add ./dsh-remote-bridge-v2.5.1.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.6.0.tgz
 ```
 
 ## 第一次使用
@@ -182,14 +182,59 @@ dsh plugin --profile web add ./dsh-remote-bridge-v2.5.1.tgz
 装好 App 后，在「手机设置 → 远程访问」里生成配置文本或配对码即可连上本机。
 公开 API 不依赖 DSH 私有协议，也可用于其他客户端：
 
-- 查看、新建、重命名和移除 DSH 工作区登记。
-- 创建、重命名、分叉和归档会话。
+- 查看、新建、重命名和移除 DSH 工作区登记。- 创建、重命名、分叉和归档会话。
 - 读取消息、流式接收正文和思考、追加引导或取消运行。
 - 查看 TODO、斜杠命令、权限模式和待审批操作。
 - 选择 Agent、模型和思考强度。
 - 查看或修改模型供应商，支持完全自定义供应商。
 - 管理设备获准访问的文件和回收站项目。
 
+### 远程开隧道：人已经出门、电脑还锁着
+
+常见场景：**人已经出门，才发现电脑上的 Cloudflare 隧道没开，配置文本也没发给自己**。
+此时公网入口根本不存在，WebUI 和 App 都够不着这台机器。能用的只剩「本机主动连出去」的通道，
+装了 `@xmanrui/dsh-im`（微信 / 飞书 / 钉钉 / 企业微信 / Telegram …）或任何带命令栏的客户端时，
+有两条入口可以做这件事：
+
+**① 桌面 WebUI 的命令栏（立即可用）**
+
+```
+/tunnel
+```
+
+回的是这样一段：
+
+```
+云隧道已开启。
+地址：https://<random>.trycloudflare.com
+设备名：Android 设备
+配置文本（一行，复制后粘贴到 App 的「导入配置」）：
+DSH1:eyJ2IjoxLCJlbmRwb2ludHMiOlt7ImxhYmVsIjoi…
+```
+
+**② IM 聊天窗口里用一句话（配合智能体）**
+
+在微信/飞书里直接说「**帮我开隧道，把配置文本发我**」，智能体会调用本插件的
+`open_tunnel_config` 工具，把同样的地址与 `DSH1:` 文本回到聊天里。
+
+> 为什么 IM 里不是发 `/tunnel`？因为 `@xmanrui/dsh-im` 的斜杠命令表是**封闭的**：
+> 内置 31 条，另外只把 `/compact` `/clear` `/permission` 三条委派给宿主，没有
+> 「未知命令转交宿主命令表」的通用派发，也从不查询宿主的命令列表。所以 `/tunnel`
+> 在 IM 里会当成一句普通消息交给智能体 —— 这也正是上面第 ② 条走自然语言 + 工具的原因。
+> 如果 dsh-im 以后加上通用派发，`/tunnel` 会立刻可用，桥这边不用改。
+
+隧道**已经在跑**时再触发一次不会重复开，而是复用当前地址再给一份配置文本
+（每次调用都会新建一台设备，方便在面板里单独吊销）。
+
+能力边界刻意压得很小：**只能开，不能停、不能改配置、不读任何文件**。
+带参数一律拒绝，不提供 `/tunnel stop` 这类第二入口。就算口令泄露，损失上限也只是
+「隧道被人开了一下」—— 隧道本身不授予任何数据面权限（读文件、发消息仍要设备令牌）。
+
+> ⚠️ **必要前提：IM 机器人必须是白名单模式，且白名单里只有你自己。**
+> 这条通道的身份校验**不在本插件里**，而在 IM 插件自己的访问策略（`canExecuteCommands` +
+> allowlist）。如果机器人设成「允许所有用户私聊执行命令」，那等于把开机按钮放到公共群里 ——
+> 这是部署问题，代码替你兜不住。详见 [SECURITY.md](docs/project/SECURITY.md#im-命令tunnel的信任边界)。
+
 ## 远程访问与安全
 
 默认远程地址为 `0.0.0.0:3090`，IP 和端口都可修改。客户端可以使用能到达服务器的 IP 或域名连接。
@@ -338,27 +383,31 @@ pnpm check
 pnpm pack
 ```
 
-`pnpm check` 覆盖类型检查、文档一致性与测试；当前 **30 个测试文件 / 226 个用例**，外加 **4 个浏览器层用例**（Playwright 实测量出的计算样式），全部通过。
+`pnpm check` 覆盖类型检查、文档一致性与测试；当前 **67 个测试文件 / 557 个用例**，外加 **8 个浏览器层用例**（Playwright 实测量出的计算样式，含 375px 窄屏契约），全部通过。
 
-`npm pack` 的产物约 **0.55 MB**（v2.5.0 实测 572,951 字节，SHA-256 `38f25c10…299c93`）：2.2.0 删除独立页及其编辑器依赖、并关闭 source map 之后从 1.72 MB 降下来，之后随投影透传与权限 BFF 小幅增长。
+`npm pack` 的产物约 **0.61 MB**（v2.5.2 实测 635,325 字节，SHA-256 `18d36904…c8095`）：2.2.0 删除独立页及其编辑器依赖、并关闭 source map 之后从 1.72 MB 降下来，之后随投影透传、权限 BFF 与五维加固小幅增长。
 
 v2.5.0 在 DSH **0.2.1-rc.2** 上完成真机验证：14/14 宿主服务全部可注入、三个 jobs 端点实测通过、
 权限档位目录返回内核真实三档。开发基线为上游 `dsh-v0.2.1-rc.2`（commit `687f282e8625c6b8d11ff58211a90524be2e4317`），
 兼容范围见上文 `engines.dsh`。CI 覆盖 Windows、Ubuntu 和 macOS。
 
-**v2.5.1 的验证状态**：47 个测试文件 / 398 个用例全绿（含隧道拓扑下的管理面回归、
-桌面端放行断言、`it.fails` 转正）、`typecheck` 与 `docs:check` 通过，并用真实
-`RemoteApiServer` 重打了审计报告 §3.1 的攻击链（逐条 403）。**尚未做真机验收**，
-也未发布到 npm / 两站 Release —— 按「未发布 ≠ 已验证 ≠ 用户吃到了」记三态。
+**v2.6.0 的验证状态**：70 个测试文件 / 593 个用例全绿、8 个 Playwright 浏览器用例
+（含 375px 窄屏契约）、`typecheck`/`docs:check`/构建通过；隧道管理面三轮真机回归均用
+React18 + Playwright 真点击台复现并验证（一键出令牌、停止出口、重进设置页锁定态），
+用户真机手工复测通过。
 
 ## 项目信息
 
-- 当前版本：`v2.5.1`
+- 当前版本：`v2.6.0`
+- **v2.6.0 是通用设置面 + IM 入口版**：新增「按插件划分的设置命名空间」两个端点（手机端照 schema 自建表单，新装插件无需改 App），以及「人已出门、电脑还锁着」时用 IM 一句话开隧道并收回配对配置的双入口（宿主命令 `/tunnel` + 工具 `open_tunnel_config`）；另加一键清理 N 天未使用设备、移除审计页，并把「激活期降级保护」补上（apply 尾部抛错不再拆掉整条插件上下文）。
+- **v2.5.2 是全量完善版**：落地五维审计（安全/功能/性能/界面/按钮反馈）——含高危的
+  `debug/host-services` 免鉴权信息泄露修复、限流双桶、广播背压、弱 ETag、审计保留策略等，
+  并把「一键开隧道并生成令牌」做成同一次请求内搭车完成；隧道运行时管理面安全锁定，
+  仅保留「停止隧道」出口，停止后自动恢复。v2.5.1 的安全模型（开隧道时 `/manage` 403、
+  四层管理判据）保持不变，见 `docs/project/SECURITY.md` §管理面的信任边界。
 - **v2.5.1 是安全修复版**：堵住「开隧道/反代后管理面免凭据对公网开放」的远程提权（`/manage/**`
   与回环 admin 头此前只按「TCP 来源是否回环」判定，而隧道转发进来的请求来源恒为 `127.0.0.1`），
-  并修复 `.heif` 交接图必被只读路由 415 的问题。升级后**开隧道时 `/manage` 一律 403**
-  （唯一例外是只读的隧道状态端点，且对非本机调用方隐去隧道地址）；桌面端面板不受影响。
-  见 `docs/project/SECURITY.md` §管理面的信任边界。
+  并修复 `.heif` 交接图必被只读路由 415 的问题。
 - 作者：上游 [Hakunm](https://github.com/Hakunm)，本 fork 维护 [westanke](https://github.com/westanke)
 - 仓库：[GitHub](https://github.com/westanke/dsh-remote-bridge) · [Gitee](https://gitee.com/westanke/dsh-remote-bridge)
 - npm：[`dsh-remote-bridge`](https://www.npmjs.com/package/dsh-remote-bridge)（[国内镜像](https://registry.npmmirror.com/dsh-remote-bridge)）

package/docs/api/asyncapi.yaml

@@ -1,7 +1,7 @@
 asyncapi: 3.0.0
 info:
   title: DeepSeek Harness Mobile Events
-  version: 2.5.1
+  version: 2.6.0
   description: |
     Live file and authorized DSH chat events. Reconnect clients must refresh
     REST state; unbounded replay is not provided.
@@ -10,6 +10,25 @@ info:
     limit, quota exhausted, invalid API key, signed-out stop). Without it a
     remote client sees an ordinary `chat.turn.end` and keeps waiting on a run
     that already failed.
+
+    Connection-level behavior (source of truth: `src/host/server.ts`):
+
+    - Authentication happens **before** connection-limit counting. The
+      default cap is 32 accepted WebSocket connections (configurable); the
+      33rd authenticated upgrade is refused at the HTTP Upgrade stage with
+      `429 Too Many Requests` and `Retry-After: 5`.
+    - Frames larger than 1 MiB are refused with WebSocket close `1009`
+      (message too big).
+    - A server ping is sent every 30 seconds; a connection that misses the
+      pong for two consecutive intervals is terminated.
+    - Each connection has a 512-frame send queue. Under backpressure the
+      server first drops rebuildable `chat.message.delta` frames, then other
+      rebuildable frames queued ahead, and as a last resort the oldest state
+      frame. When any frame was dropped the server emits a best-effort
+      `connection.resyncRequired` frame (also immediately before a
+      `1013 Backpressure` close) telling the client to re-sync via REST;
+      clients must ignore the exact `dropped` value. Older clients that do
+      not know this event simply ignore it.
 servers:
   local:
     host: 127.0.0.1:3090
@@ -39,7 +58,7 @@ components:
           id: { type: string }
           type:
             type: string
-            examples: [file.changed, file.trashed, chat.message.delta, chat.message.committed, chat.session.status, chat.session.snapshot, chat.deliverables.presented, chat.approval.requested, chat.approval.resolved, chat.turn.failed, connection.ready]
+            examples: [file.changed, file.trashed, chat.message.delta, chat.message.committed, chat.session.status, chat.session.snapshot, chat.deliverables.presented, chat.approval.requested, chat.approval.resolved, chat.turn.failed, connection.ready, connection.resyncRequired]
           time: { type: integer }
           data:
             oneOf:
@@ -49,6 +68,7 @@ components:
               - $ref: '#/components/schemas/ChatApprovalResolved'
               - $ref: '#/components/schemas/ChatTurnFailed'
               - $ref: '#/components/schemas/ConnectionReadyData'
+              - $ref: '#/components/schemas/ConnectionResyncRequired'
               - $ref: '#/components/schemas/ChatSessionSnapshot'
               - $ref: '#/components/schemas/ChatDeliverablesPresented'
               - type: object
@@ -231,3 +251,32 @@ components:
         capabilities:
           type: array
           items: { type: string }
+
+    ConnectionResyncRequired:
+      type: object
+      description: |
+        Payload of a connection-scoped `connection.resyncRequired` frame. The
+        server emits it (best effort) after it had to drop queued frames for
+        this socket because the per-connection send queue (512 frames)
+        overflowed under backpressure; it is also emitted once immediately
+        before the server closes the socket with WebSocket code `1013`
+        (`Backpressure`), when even state frames no longer fit. State frames
+        (`chat.turn.*`, `chat.approval.*`, `chat.turn.failed`,
+        `connection.ready`) are preserved preferentially over
+        `chat.message.delta`.
+
+        On receipt, clients should re-fetch history and pending state via the
+        REST API (the dropped frames are never replayed). The `dropped` count
+        is diagnostic only and must not be acted on numerically; clients that
+        do not recognize this event type ignore it safely. Example:
+        `{"id":"<uuid>","type":"connection.resyncRequired","time":1761100000000,
+        "data":{"dropped":12,"reason":"backpressure"}}`.
+      required: [dropped, reason]
+      properties:
+        dropped:
+          type: integer
+          minimum: 0
+          description: Number of frames dropped for this connection since the previous resync notification.
+        reason:
+          type: string
+          const: backpressure