dsh-remote-bridge 2.5.0 → 2.5.2

package/README.en.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-v2.5.0-087f8c">
+  <img alt="Version" src="https://img.shields.io/badge/version-v2.5.2-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.0/dsh-remote-bridge-v2.5.0.tgz
+dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.5.2/dsh-remote-bridge-v2.5.2.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.0/dsh-remote-bridge-v2.5.0.tgz
+dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.5.2/dsh-remote-bridge-v2.5.2.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.0.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.5.2.tgz
 ```
 
 ## First connection
@@ -352,15 +352,30 @@ 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,316 bytes, SHA-256 `1779c02e…bdd3bd`): 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.2 verification status**: 67 test files / 557 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.0`
+- Version: `v2.5.2`
+- **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.0-087f8c">
+  <img alt="Version" src="https://img.shields.io/badge/version-v2.5.2-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.0/dsh-remote-bridge-v2.5.0.tgz
+dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.5.2/dsh-remote-bridge-v2.5.2.tgz
 
 # ③ Gitee Release 的 tarball（国内访问更快）
-dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.5.0/dsh-remote-bridge-v2.5.0.tgz
+dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.5.2/dsh-remote-bridge-v2.5.2.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.0.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.5.2.tgz
 ```
 
 ## 第一次使用
@@ -338,17 +338,30 @@ 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,316 字节，SHA-256 `1779c02e…bdd3bd`）：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.2 的验证状态**：67 个测试文件 / 557 个用例全绿、8 个 Playwright 浏览器用例
+（含 375px 窄屏契约）、`typecheck`/`docs:check`/构建通过；隧道管理面三轮真机回归均用
+React18 + Playwright 真点击台复现并验证（一键出令牌、停止出口、重进设置页锁定态），
+用户真机手工复测通过。
+
 ## 项目信息
 
-- 当前版本：`v2.5.0`
+- 当前版本：`v2.5.2`
+- **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 的问题。
 - 作者：上游 [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.0
+  version: 2.5.2
   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

package/docs/api/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: DeepSeek Harness Mobile API
-  version: 2.5.0
+  version: 2.5.2
   description: Versioned file and chat BFF for mobile and third-party DSH clients. HTTP and HTTPS are both supported.
 servers:
   - url: http://127.0.0.1:3090/api/v1
@@ -24,7 +24,7 @@ paths:
                 properties:
                   ok: { type: boolean, const: true }
                   version: { type: string, const: v1 }
-                  pluginVersion: { type: string, const: 2.4.2 }
+                  pluginVersion: { type: string, const: 2.5.2 }
   /debug/host-services:
     get:
       operationId: hostServices
@@ -39,8 +39,14 @@ paths:
         `observed` covers services confirmed present in the web profile but not yet
         consumed (currently only `workingDirectory`, added by DSH 0.2.1).
 
-        Requires a device token or loopback admin, like every other authenticated
-        endpoint: it exposes host internals.
+        Requires a device token or loopback admin **with the `settings.read`
+        scope** (a loopback admin inherits all scopes): it exposes host
+        internals. Since 2.5.2 the endpoint sits behind authentication like
+        every other `/api/v1` route (SEC-H1); it previously returned before the
+        principal was resolved. The response may additionally carry a
+        best-effort `metrics` object with runtime diagnostics; it is omitted in
+        builds without the metrics collector (and a missing probe still yields
+        `404`, not `500`).
       responses:
         '200':
           description: Injection probe snapshot taken while the plugin applied.
@@ -79,6 +85,14 @@ paths:
                       injectedAvailable: { type: integer }
                       injectedMissing: { type: array, items: { type: string } }
                       observedAvailable: { type: array, items: { type: string } }
+                  metrics:
+                    type: object
+                    description: |
+                      Optional runtime diagnostics attached to the same
+                      `settings.read`-gated report (no separate route). Omitted
+                      when the build has no metrics collector. Shape is
+                      diagnostic and additive.
+                    additionalProperties: true
         '404':
           description: The probe is not compiled into this build.
   /pairings/exchange:
@@ -134,6 +148,32 @@ paths:
                     type: array
                     items: { $ref: '#/components/schemas/Root' }
         '403': { $ref: '#/components/responses/Error' }
+  /roots/resolve:
+    get:
+      operationId: resolveAbsolutePath
+      summary: Map a host absolute path to its authorized root
+      description: |
+        Chat events carry server-absolute paths while `GET /roots` deliberately
+        omits root absolute paths, so clients cannot perform this mapping
+        themselves. Resolves `path` against the device's authorized roots using
+        realpath-normalized longest-prefix matching, then stat-checks the
+        target (rejecting symlinks inside the path) via the same machinery as
+        file content reads. The response never contains an absolute host path.
+        Requires `files.read`.
+      parameters:
+        - name: path
+          in: query
+          required: true
+          description: Absolute host path. Relative paths are rejected rather than guessed.
+          schema: { type: string, minLength: 1 }
+      responses:
+        '200':
+          description: Root match plus wire-relative metadata for the target.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/ResolvedPath' }
+        '400': { $ref: '#/components/responses/Error' }
+        '404': { $ref: '#/components/responses/Error' }
   /roots/{rootId}/entries:
     parameters:
       - $ref: '#/components/parameters/RootId'
@@ -271,6 +311,74 @@ paths:
         '200':
           description: Item restored without overwriting an existing path.
         '409': { $ref: '#/components/responses/Error' }
+  /image-handoff:
+    get:
+      operationId: readImageHandoff
+      summary: Fetch one handoff image for a chat session
+      description: |
+        Returns the raw bytes of an image the agent handed off (content-addressed
+        `sha256.<ext>` files written under the session working directory's
+        image-handoff subdirectory). `name` must be a bare file name only: the
+        directory is always derived by the host from the session working
+        directory, so no directory or absolute path can be supplied. Requires
+        `files.read` plus ownership of the session; "no such session" and "no
+        such file" are indistinguishable (both are 404). This authenticated REST
+        route is the device-side counterpart of the token-less browser route
+        `GET /plugin/dsh-remote-bridge/raw`.
+      parameters:
+        - name: sessionId
+          in: query
+          required: true
+          schema: { type: string }
+        - name: name
+          in: query
+          required: true
+          description: Bare handoff file name, e.g. `a1b2…e9.png`.
+          schema: { type: string, pattern: '^[0-9a-f]{64}\.[A-Za-z0-9]+$' }
+      responses:
+        '200':
+          description: Image bytes; handoff files are temporary artifacts, so the response is private and must be revalidated.
+          headers:
+            Cache-Control: { schema: { type: string }, description: private, max-age=0, must-revalidate }
+          content:
+            application/octet-stream:
+              schema: { type: string, contentEncoding: binary }
+        '400': { $ref: '#/components/responses/Error' }
+        '404': { $ref: '#/components/responses/Error' }
+  /attachments/{attachmentId}:
+    get:
+      operationId: readAttachment
+      summary: Fetch one session attachment's bytes
+      description: |
+        Returns the raw bytes of an image attachment referenced by a session
+        event. The attachment store is content-addressed, so `attachmentId`
+        contains a colon (typically `sha256:<hex>`) and **must be
+        percent-encoded in the URL** (`sha256%3A<hex>`). `sessionId` is a
+        required query parameter: the host verifies the session actually
+        references this attachment and validates bytes/media type against the
+        real reference stored in the session event. Requires `files.read` plus
+        ownership of the session. Bytes are immutable and may be cached
+        privately for a year.
+      parameters:
+        - name: attachmentId
+          in: path
+          required: true
+          description: Content-addressed attachment id, e.g. `sha256%3A<hex>` (the raw id is `sha256:<hex>` and must be percent-encoded).
+          schema: { type: string }
+        - name: sessionId
+          in: query
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: Attachment bytes; immutable and privately cacheable.
+          headers:
+            Cache-Control: { schema: { type: string }, description: private, max-age=31536000, immutable }
+          content:
+            application/octet-stream:
+              schema: { type: string, contentEncoding: binary }
+        '400': { $ref: '#/components/responses/Error' }
+        '404': { $ref: '#/components/responses/Error' }
   /chat/workspaces:
     get:
       operationId: listChatWorkspaces
@@ -784,6 +892,45 @@ paths:
       responses:
         '202': { description: Prompt accepted by DSH. }
         '409': { $ref: '#/components/responses/Error' }
+  /chat/sessions/{sessionId}/attachments:
+    parameters:
+      - name: sessionId
+        in: path
+        required: true
+        schema: { type: string }
+    post:
+      operationId: uploadSessionAttachment
+      summary: Upload one attachment and receive a receipt
+      description: |
+        Uploads one attachment as base64 text and returns the receipt a later
+        message can reference. Kernel file-type content parts require this
+        `receiptId` (obtained through an upload); only image content parts may
+        be inlined as base64 directly in a message. Requires `chat.write` plus
+        ownership of the session. The request body is limited to 24 MiB.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [data]
+              properties:
+                data:
+                  type: string
+                  contentEncoding: base64
+                  minLength: 1
+                  description: Base64-encoded attachment bytes.
+                name:
+                  type: string
+                  description: Optional original file name; trimmed by the server.
+      responses:
+        '201':
+          description: Stored; the receipt id is referenced by later message file parts.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/AttachmentReceipt' }
+        '400': { $ref: '#/components/responses/Error' }
+        '404': { $ref: '#/components/responses/Error' }
   /chat/sessions/{sessionId}/approvals:
     get:
       operationId: listPendingApprovals
@@ -994,6 +1141,24 @@ paths:
               schema: { $ref: '#/components/schemas/SessionModels' }
         '404': { $ref: '#/components/responses/Error' }
   /chat/sessions/{sessionId}/model:
+    get:
+      operationId: getSessionModelAlias
+      description: |
+        Alias of `GET /chat/sessions/{sessionId}/models`; the server route
+        `model(?:s)?$` answers GET on both spellings. New clients should call
+        `/models`.
+      parameters:
+        - name: sessionId
+          in: path
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: Current selection and models routable for this DSH session.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SessionModels' }
+        '404': { $ref: '#/components/responses/Error' }
     put:
       operationId: selectSessionModel
       parameters:
@@ -1155,6 +1320,24 @@ components:
         id: { type: string, format: uuid }
         label: { type: string }
         createdAt: { type: integer }
+    ResolvedPath:
+      type: object
+      description: Result of mapping an absolute host path into an authorized root; the root's absolute path itself is never included.
+      required: [rootId, path, kind, size, modifiedAt, contentType]
+      properties:
+        rootId: { type: string, format: uuid }
+        path: { $ref: '#/components/schemas/WirePath' }
+        kind: { type: string, enum: [file, directory] }
+        size: { type: integer, nullable: true }
+        modifiedAt: { type: integer, nullable: true }
+        contentType: { type: string, nullable: true }
+    AttachmentReceipt:
+      type: object
+      description: Upload receipt referenced later as a file-type content part in a message.
+      required: [receiptId, name]
+      properties:
+        receiptId: { type: string }
+        name: { type: string, nullable: true }
     Device:
       type: object
       required: [id, name, scopes, rootIds]