dsh-cherry-bridge 0.1.11 → 0.2.1

package/README.en.md

@@ -28,23 +28,25 @@ flowchart TB
 ```
 
 - Package: `dsh-cherry-bridge`, plugin id: `cherry-remote`
-- Transport: `ws://` + Noise XX (encryption lives in the Noise record layer; no TLS termination required)
+- Transport: `ws://` + Noise XX by default (encryption lives in the Noise record layer); a desktop behind a TLS front is reached over `wss://`, with `wsTls` supplying the private-CA trust
 - Tool face: 14 `cherry_*` tools, enabled **per workspace**, and by default **nobody has them** (see “Scope”)
 - Settings page and HTTP face: the same-origin prefix `/cherry-remote/api` on the host web server
 
 ## Install
 
 > **DSH version requirement**: `>=0.2.0-rc.2 <0.3.0-0` (declared via `engines.dsh` in `package.json`; when unmet the bundle is skipped and its settings-page row disabled — `dsh plugin allow-version` grants an explicit exemption; 0.3.0 needs a fresh compatibility pass before the range widens).
+>
+> **Cherry Studio compatibility**: desktop **2.1.4 – 2.1.10 is verified** — the `v3` custom-address QR needs **2.1.8+**, and the `v2` QR of 2.1.4 – 2.1.7 works too. 2.1.9/2.1.10 differ from 2.1.8 on the remote-access face by exactly one robustness fix in the desktop's write chain (PR #22593, no client impact), and were smoke-tested on a real 2.1.10 (create a session → send → wait → read). Outside that range is unverified: the handshake negotiates protocol version `[1]` only, so an incompatible peer fails loudly as `unreachable` instead of misbehaving. The protocol packages are pinned to `0.7.0` / `0.2.5` — 2.1.10 still ships that same pair.
 
 ```bash
 # From npm (recommended, pinned)
-npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.11
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.2.1
 
 # Install the latest npm release
 npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge
 
 # From GitHub source (same commit as the npm release)
-npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.11
+npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.2.1
 ```
 
 The package ships `cordis.patch.yml` (`package.json`'s `dsh.bundle.patch` points
@@ -93,6 +95,9 @@ cherry_interactions → see pending question/approval cards; cherry_respond answ
 | `dataDir` | string | `$DSH_HOME/cherry-remote` (fallback `~/.dsh/cherry-remote`) | Plugin data directory holding `identity.key` and `devices.json` (both `0600`). |
 | `perSessionCacheBytes` | number | `2097152` (2 MiB) | Per-session cap on the **local** subscription event cache; beyond it the oldest events are dropped LRU-style with a `warn`. |
 | `rateBudgetPerSecond` | number | `32` | Per-device smoothed request budget (req/s). The desktop's shared allowance is 64 req/s through 2.1.6 and 256 req/s from 2.1.7, and only the newer generation downgrades an overrun to a single `RATE_LIMITED` refusal (the older one terminates the session with close `1011`) — hence a value sized for the harsher generation. Content reads (`agent.content.read`) derive their own tier at 8:1, **capped at 512/s** (that allowance is the same in both generations). |
+| `wsTls` | object | — | **Flat** `tls.connect` options for every `wss` dial (`rejectUnauthorized` / `ca` only): operator-supplied trust for a desktop behind a private CA or a self-signed TLS front. Applied to BOTH dial sites — pairing and reconnect. **Never written to the device archive, never logged, never in diagnostics.** The whole object applies as written or is ignored entirely: an unknown key or unusable value warns by name and falls back to Node's default trust store (no partial application). |
+
+> `wsTls.ca` is **PEM CONTENT** (the certificate text itself), not a file path.
 
 > ⚠️ `cordis.patch.yml`'s `config` is **whole-replace**, not merged with the
 > defaults. Removing a key gets you the plugin default; a key that exists but is
@@ -102,7 +107,7 @@ cherry_interactions → see pending question/approval cards; cherry_respond answ
 
 | Tool | What it does |
 | --- | --- |
-| `cherry_devices` | List every paired device and its connection state (`connected`/`connecting`/`offline`/`disabled`/`identity-mismatch`). |
+| `cherry_devices` | List every paired device and its connection state (`connected`/`connecting`/`offline`/`disabled`/`identity-mismatch`). `action: "forget"` makes named addresses go away (removed from the dial list, and not re-learned when the desktop advertises them again, until `remember` or a re-pair); `action: "remember"` lifts that mark so the next handshake may learn them again. Both write actions require `device` and `hosts`. |
 | `cherry_agents` | List the agents available on a device (paginated). A truncated answer always carries `truncated` + `truncationReason` (`limit` or `safety-bound`, the latter the 1000-item internal ceiling); when the stop point can be named it also carries a `resumeCursor`: replay it as `cursor` with the same device and filters to continue from that stop point (`limit` then bounds the next answer). A token from another tool, device or filter set is refused **locally**, never forwarded. |
 | `cherry_workspaces` | List an agent's **registered** workspaces, and whether a system workspace exists. A truncated answer always carries `truncated` + `truncationReason`; when the stop point can be named it also carries a `resumeCursor` — replay it as `cursor` with the same filters to continue. |
 | `cherry_sessions` | List an agent's sessions, optionally filtered by workspace. A truncated answer always carries `truncated` + `truncationReason` (`limit` or `safety-bound`); when the stop point can be named it also carries a `resumeCursor`: replay it as `cursor` with the same device and **identical filters** to continue (`limit` then bounds the next answer); a token from another tool, device or filter set is refused **locally**. |
@@ -200,7 +205,9 @@ subscription was lost and could not be rebuilt, so the outcome is
 - **Known limitations**: `cherry_respond` lets a DSH agent approve Cherry-side
   approval cards on the user's behalf (the MVP adds no interception layer and
   trusts DSH's own tool-call approvals); only the `agent` capability is
-  requested per device; `ws://` only (Noise encryption), no direct TLS.
+  requested per device; transport is `ws://` by default, and `wss://` requires a
+  TLS front in front of the desktop (this plugin never terminates TLS; `wsTls`
+  carries the private-CA trust).
 
 > Engineering detail — replay rules, the 32 MiB/≈3× memory contract, empty-page
 > and cursor tolerance, integrity semantics — lives in [`AGENTS.md`](AGENTS.md).
@@ -210,9 +217,9 @@ subscription was lost and could not be rebuilt, so the outcome is
 The plugin is also a **web client bundle** (`package.json`'s `dsh.client`,
 exporting `./client`). Through the `settings.section` slot it registers a
 **`cherry-remote`** page (nav label “Cherry Bridge”): device cards
-(enable/disable/remove), a pairing wizard (paste → 6-digit code → verdict), a
-scope panel, and live state pushed over the same-origin SSE feed
-(`/cherry-remote/api/events`).
+(enable/disable/remove, plus forget/restore for an address), a pairing wizard
+(paste → 6-digit code → verdict), a scope panel, and live state pushed over the
+same-origin SSE feed (`/cherry-remote/api/events`).
 
 The 14 tools appear **per workspace**, by **hiding, not refusing** (in an
 out-of-scope session they never enter the tool table, saving context):

package/README.md

@@ -26,23 +26,25 @@ flowchart TB
 ```
 
 - 包名：`dsh-cherry-bridge`，插件 id：`cherry-remote`
-- 传输：`ws://` + Noise XX（加密由 Noise 记录层提供，不依赖 TLS 终止）
+- 传输：默认 `ws://` + Noise XX（加密由 Noise 记录层提供）；桌面端位于 TLS 前置之后时拨 `wss://`，私有 CA 的信任由 `wsTls` 提供
 - 工具面：14 个 `cherry_*` 工具，**按工作区**启用，默认**谁都没有**（见「启用范围」）
 - 设置页与 HTTP 面：宿主 Web 服务器上的同源前缀 `/cherry-remote/api`
 
 ## 安装
 
 > **DSH 版本需求**：`>=0.2.0-rc.2 <0.3.0-0`（由 `package.json` 的 `engines.dsh` 声明；不满足时 bundle 被跳过、设置页里该插件的行被禁用，确需在区间外使用可用 `dsh plugin allow-version` 精确豁免。0.3.0 需重新评估兼容性后再放开）。
+>
+> **Cherry Studio 兼容范围**：桌面端 **2.1.4 – 2.1.10 已核对**——`v3` 自定义地址二维码需 **2.1.8+**，2.1.4–2.1.7 的 `v2` 二维码同样可用。2.1.9/2.1.10 与 2.1.8 在 remote-access 面上只差桌面端发送链的一处健壮性修复（PR #22593，不影响客户端），并在 2.1.10 真机上跑过「建会话 → 发送 → 等待 → 读取」冒烟。区间外未经验证：握手只协商协议版本 `[1]`，不兼容时会以 `unreachable` 明确失败，不会静默出错。协议包钉在 `0.7.0` / `0.2.5`，2.1.10 携带的还是同一对版本。
 
 ```bash
 # 从 npm 安装（推荐，钉住版本）
-npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.1.11
+npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge@0.2.1
 
 # 安装 npm 最新发布版
 npx @deepseek-ai/dsh plugin --profile web add dsh-cherry-bridge
 
 # 从 GitHub 源码安装（与 npm 发布同一提交）
-npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.1.11
+npx @deepseek-ai/dsh plugin --profile web add github:SAXEM1997/dsh-cherry-bridge#v0.2.1
 ```
 
 本包自带 `cordis.patch.yml`（`package.json` 的 `dsh.bundle.patch` 指向它），
@@ -85,6 +87,9 @@ cherry_interactions → 看待答的提问/审批卡；cherry_respond 作答
 | `dataDir` | string | `$DSH_HOME/cherry-remote`（回退 `~/.dsh/cherry-remote`） | 插件数据目录，存放 `identity.key` 与 `devices.json`（均 `0600`）。 |
 | `perSessionCacheBytes` | number | `2097152`（2 MiB） | 每个会话的**本地**订阅事件缓存上限，超出按 LRU 丢弃最旧事件并 `warn`。 |
 | `rateBudgetPerSecond` | number | `32` | 每设备平滑请求预算（请求/秒）。桌面端共享额度在 ≤2.1.6 是 64 req/s、≥2.1.7 是 256 req/s，且只有新版本才把超限降级为单请求 `RATE_LIMITED`（旧版本直接 close `1011` 终止会话），故按更严格的一代取保守值。内容读取（`agent.content.read`）按 8:1 派生独立一档，且**封顶 512/s**（该额度两代一致）。 |
+| `wsTls` | object | — | 每次 `wss` 拨号的**扁平** `tls.connect` 选项（只接受 `rejectUnauthorized` / `ca`），供桌面端位于私有 CA 或自签 TLS 前置之后时由运维提供信任；配对与重连**两个拨号点**共用。**不写入设备档案、不写日志、不进诊断报告。** 整个对象要么按原样生效、要么整体忽略：未知键或不可用值按名 `warn` 后回退 Node 默认信任库（不部分应用）。 |
+
+> `wsTls.ca` 是 **PEM 内容**（证书文本本身），不是文件路径。
 
 > ⚠️ `cordis.patch.yml` 的 `config` 是**整体替换**，不与默认值合并。删掉一个键得到的是
 > 插件默认值；键存在但值非法（`0`、负数、字符串）会按名 `warn` 后回落默认值。
@@ -93,7 +98,7 @@ cherry_interactions → 看待答的提问/审批卡；cherry_respond 作答
 
 | 工具 | 作用 |
 | --- | --- |
-| `cherry_devices` | 列出已配对设备及连接状态（`connected`/`connecting`/`offline`/`disabled`/`identity-mismatch`）。 |
+| `cherry_devices` | 列出已配对设备及连接状态（`connected`/`connecting`/`offline`/`disabled`/`identity-mismatch`）。`action: "forget"` 可遗忘指定地址（从拨号列表移除，且桌面再广播也不会被重新学习，直到 `remember` 或重新配对）；`action: "remember"` 撤销该标记（下次握手可重新学习）；两者都需要 `device` 与 `hosts`。 |
 | `cherry_agents` | 列出某设备上可用的 agent（分页）。被截断时必带 `truncated`+`truncationReason`（`limit` 或 `safety-bound`，后者是 1000 条内部上限）；停点可命名时还给出 `resumeCursor`——用同一 device 与过滤条件把它回传为 `cursor` 即可从停点继续（此时 `limit` 约束的是下一次回答）；跨工具/设备/过滤条件的令牌会被**本地拒绝**，不会转发给对端。 |
 | `cherry_workspaces` | 列出某 agent 的**已注册**工作区，以及是否存在系统工作区。被截断时必带 `truncated`+`truncationReason`；停点可命名时还给出 `resumeCursor`——用相同过滤条件回传为 `cursor` 即可续读。 |
 | `cherry_sessions` | 列出某 agent 的会话，可按工作区过滤。被截断时必带 `truncated`+`truncationReason`（`limit` 或 `safety-bound`），停点可命名时还给出 `resumeCursor`——用同一 device 与**相同过滤条件**把它回传为 `cursor` 即可从停点继续（此时 `limit` 约束的是下一次回答）；跨工具/设备/过滤条件的令牌会被**本地拒绝**。 |
@@ -155,7 +160,8 @@ cherry_interactions → 看待答的提问/审批卡；cherry_respond 作答
   idle 回答的历史走查仍从那一刻起算自己的预算（慢但成功的快照不会把走查挤成零）；
   代价是两段预算**分开计**，病态调用可能把两段都花掉。
 - **已知限制**：`cherry_respond` 让 DSH agent 可代替用户批准 Cherry 端审批卡（MVP 不加拦截层，
-  信任 DSH 自身的工具审批）；每设备仅申请 `agent` capability；仅 `ws://`（Noise 加密），不做 TLS 直连。
+  信任 DSH 自身的工具审批）；每设备仅申请 `agent` capability；传输默认 `ws://`，
+  `wss://` 要求桌面端位于 TLS 前置之后（本插件不做 TLS 终止；私有 CA 的信任由 `wsTls` 提供）。
 
 > 传输重放、32 MiB/≈3× 内存、空页与游标容忍、完整性语义等工程细节见 [`AGENTS.md`](AGENTS.md)。
 
@@ -163,7 +169,8 @@ cherry_interactions → 看待答的提问/审批卡；cherry_respond 作答
 
 插件同时是 **web client bundle**（`package.json` 的 `dsh.client`，导出 `./client`），通过
 `settings.section` 槽位注册 **`cherry-remote`**（导航标签「Cherry 互联」）页面：
-设备卡片（启用/停用/删除）、配对向导（粘贴 → 6 位验证码 → 终态）、启用范围面板，以及经
+设备卡片（启用/停用/删除，地址的「忘记 / 恢复」）、配对向导（粘贴 → 6 位验证码 → 终态）、
+启用范围面板，以及经
 `/cherry-remote/api/events` SSE 推送的实时状态。
 
 14 个工具**按工作区**决定是否出现，机制是**隐藏而非拒绝**（不在范围的会话里不进工具表，省上下文）：

package/dist/index.d.mts

@@ -1,5 +1,19 @@
 import { connectSecureChannel } from "@cherrystudio/remote-transport";
+import "@cherrystudio/remote-protocol";
 import "@cherrystudio/remote-protocol/agent";
+//#region src/connection.d.ts
+/**
+ * Options handed to every `WebSocket` dial (issue #126).
+ *
+ * FLAT `tls.connect` options — `ws` forwards its own option bag straight to
+ * `tls.connect`, so `{ rejectUnauthorized: false }` or `{ ca: <pem> }` belong
+ * at the top level rather than under a `tls:` key.
+ */
+type WsDialOptions = {
+  rejectUnauthorized?: boolean;
+  ca?: string | Buffer | Array<string | Buffer>;
+};
+//#endregion
 //#region src/tools.d.ts
 /**
  * The plugin's tool face: the complete fourteen-tool `cherry_*` family — six
@@ -264,10 +278,24 @@ export interface CherryBridgeConfig {
    * (not a protocol value). Omitted uses {@link DEFAULT_PER_SESSION_CACHE_BYTES}.
    */
   perSessionCacheBytes?: number;
+  /**
+   * FLAT `tls.connect` options for every `wss` dial (issue #133): the operator's
+   * TLS trust for a desktop behind a private CA or a self-signed TLS front.
+   * `ws` forwards this bag straight to Node's TLS layer, so `{ ca: <pem> }` and
+   * `{ rejectUnauthorized: false }` belong at the TOP level — the `{ tls: {…} }`
+   * shape (`https`' wrapper) is not recognised by `ws` and is refused here.
+   * Applied to BOTH dial sites: the steady-state pool and pairing.
+   *
+   * NEVER persisted in the record, never logged, never reported: a `ca` is PEM
+   * CONTENT, and trust is a grant the operator makes, not a fact the desktop
+   * asserts about itself.
+   */
+  wsTls?: WsDialOptions;
 }
 /**
- * The two config values that reach constructor arguments, with their defaults
- * applied.
+ * The plugin-config values that reach constructor arguments, resolved once: the
+ * two numeric budgets with their defaults applied, and the validated TLS trust
+ * bag (see {@link dialOptions}).
  *
  * Resolved ONCE per `apply` and threaded explicitly, rather than re-read at each
  * construction site: a config surface that can change between two constructions
@@ -276,8 +304,9 @@ export interface CherryBridgeConfig {
 export interface ResolvedBridgeConfig {
   rateBudgetPerSecond: number;
   perSessionCacheBytes: number;
+  wsTls: WsDialOptions | undefined;
 }
-/** Applies the documented fallbacks to the plugin config's numeric keys. */
+/** Applies the documented fallbacks and validates the plugin config's keys. */
 export declare function resolveBridgeConfig(config?: CherryBridgeConfig): ResolvedBridgeConfig;
 /** The context slice `apply` touches beyond the HTTP face's own services. */
 export interface CherryBridgeContext extends CherryHttpContext, CherryToolsContext {