dsh-cherry-bridge 0.1.11 → 0.2.0

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.8 is tested** — the `v3` custom-address QR needs **2.1.8+**, and the `v2` QR of 2.1.4 – 2.1.7 works too. 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` — the versions desktop 2.1.8 ships.
 
 ```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.0
 
 # 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.0
 ```
 
 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
@@ -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).

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.8 已实测**——`v3` 自定义地址二维码需 **2.1.8+**，2.1.4–2.1.7 的 `v2` 二维码同样可用。区间外未经验证：握手只协商协议版本 `[1]`，不兼容时会以 `unreachable` 明确失败，不会静默出错。协议包钉在 `0.7.0` / `0.2.5`，即桌面端 2.1.8 所携带的版本。
 
 ```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.0
 
 # 安装 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.0
 ```
 
 本包自带 `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` 后回落默认值。
@@ -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)。
 

package/dist/index.d.mts

@@ -1,5 +1,18 @@
 import { connectSecureChannel } from "@cherrystudio/remote-transport";
 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 +277,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 +303,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 {