dsh-remote-bridge 2.4.3 → 2.5.1

package/README.en.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-v2.4.3-087f8c">
+  <img alt="Version" src="https://img.shields.io/badge/version-v2.5.1-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">
@@ -36,9 +36,17 @@ The interface is bilingual and defaults to Chinese. Prebuilt packages run on Win
 > `engines.dsh` is recognized by the 0.2.1 kernel (`prepareProfileEntries` in
 > `dsh-app-boot/lib/index.js`) — an unmet range only sets that entry to `disabled` and prints to
 > stderr; **the host process does not exit**. So no code change is needed to run on `0.2.1-rc.2`.
-> The only point still needing on-device confirmation is the injection surface of
-> `permissionPresets` (never injectable on 0.2.0 either, where the plugin already falls back to a
-> built-in catalog).
+>
+> **Functional differences between the two versions (important)**: the `inject` list holds **only
+> services that exist in both versions** — cordis treats `inject` as a **hard dependency**, and a
+> single missing service leaves the whole plugin inactive (proven by CI on the 0.2.0-rc.2 baseline:
+> writing a 0.2.1-only service into `inject` once made the plugin fail to activate on 0.2.0).
+> The services that only 0.2.1 provides (**background jobs** `jobController`, the **permission
+> catalog** `permissionPresets`, file upload `fileUploads`, attachment storage `attachments`) are
+> therefore read at runtime through `ctx.reflect.get(name, false)`: **all of them work on
+> 0.2.1-rc.2 and degrade automatically on 0.2.0-rc.2** (the jobs endpoints answer 404 there, the
+> permission catalog falls back to its built-in one) — the plugin itself runs on both kernels.
+> `GET /api/v1/debug/host-services` reports which optional capabilities the current machine has.
 
 ## What it looks like
 
@@ -94,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.4.3/dsh-remote-bridge-v2.4.3.tgz
+dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.5.1/dsh-remote-bridge-v2.5.1.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.4.3/dsh-remote-bridge-v2.4.3.tgz
+dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.5.1/dsh-remote-bridge-v2.5.1.tgz
 
 npx @deepseek-ai/dsh web
 ```
@@ -114,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.4.3.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.5.1.tgz
 ```
 
 ## First connection
@@ -346,13 +354,26 @@ 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).
 
-`npm pack` produces roughly a **0.55 MB** archive (v2.4.3 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.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.
+
+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.4.3 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 `master@47f943859bef60e4160492346772ded9b24f765a` (kernel 0.2.0-rc.2); 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".
 
 ## Project
 
-- Version: `v2.4.3`
+- 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` §「管理面的信任边界」.
 - 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.4.3-087f8c">
+  <img alt="Version" src="https://img.shields.io/badge/version-v2.5.1-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">
@@ -26,13 +26,21 @@
 > 0.2.x 上无法启动（表现为「添加根目录返回 405」）。兼容层的完整说明——基于什么、为什么、改了什么、
 > 测了什么——见 [DSH 0.2.x 兼容性适配说明](./docs/project/DSH-0.2-COMPAT.md)。
 >
-> **对 DSH 0.2.1-rc.2 的适配结论**（2026-10-20 复核，依据 `/media/wangke/OFFICE/workspace/dsh-remote-bridge/docs/project/DSH-0.2.1-ADAPTATION.md`）：
+> **对 DSH 0.2.1-rc.2 的适配结论**（2026-10-20 复核，依据 `docs/project/DSH-0.2.1-ADAPTATION.md`）：
 > 本插件**刻意不 import 任何 `@deepseek-ai/*` 包**，全部宿主服务经结构类型 + Host 注入消费
 > （见 `src/host/dsh-0.2-bridge.ts` 头注释）。逐一到 `0.2.1-rc.2` 实装包核对：`cordis.patch.yml`
 > 的 10 项 `inject` 服务名**全部仍存在且签名未变**，`engines.dsh` 在 0.2.1 被内核识别
 > （`dsh-app-boot/lib/index.js` 的 `prepareProfileEntries`），不满足时只把该 entry 置
 > `disabled` 并打 stderr，**宿主进程不退出**。故本插件无需改码即可运行于 `0.2.1-rc.2`。
-> 唯一需真机定论的是 `permissionPresets` 的注入面（0.2.0 上即注不进，已降级到内置目录）。
+>
+> **两版的功能差异（重要）**：`inject` 里只放**两个版本都存在**的服务 —— cordis 的 inject 是
+> **硬依赖**，任何一个服务缺失就整个插件不激活（CI 在 0.2.0-rc.2 基线上实锤过：
+> 一度因为把 0.2.1 才有的服务写进 inject 而让插件在 0.2.0 上整体不激活）。
+> 因此 0.2.1 才提供的服务（**后台任务** `jobController`、**权限档位目录**
+> `permissionPresets`、文件上传 `fileUploads`、附件存储 `attachments`）改为运行时经
+> `ctx.reflect.get(name, false)` 读取：**0.2.1-rc.2 上这些功能全部可用，0.2.0-rc.2 上
+> 自动降级**（如后台任务端点返回 404、权限档位走内置目录），插件本体两种内核都能跑。
+> 用 `GET /api/v1/debug/host-services` 可以查这台机器上哪些可选能力可用。
 
 ## 实际效果
 
@@ -85,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.4.3/dsh-remote-bridge-v2.4.3.tgz
+dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.5.1/dsh-remote-bridge-v2.5.1.tgz
 
 # ③ Gitee Release 的 tarball（国内访问更快）
-dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.4.3/dsh-remote-bridge-v2.4.3.tgz
+dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.5.1/dsh-remote-bridge-v2.5.1.tgz
 
 npx @deepseek-ai/dsh web
 ```
@@ -104,7 +112,7 @@ npx @deepseek-ai/dsh web
 从 GitHub Release 下载离线安装包时，可直接安装 tarball：
 
 ```sh
-dsh plugin --profile web add ./dsh-remote-bridge-v2.4.3.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.5.1.tgz
 ```
 
 ## 第一次使用
@@ -332,15 +340,25 @@ pnpm pack
 
 `pnpm check` 覆盖类型检查、文档一致性与测试；当前 **30 个测试文件 / 226 个用例**，外加 **4 个浏览器层用例**（Playwright 实测量出的计算样式），全部通过。
 
-`npm pack` 的产物约 **0.55 MB**（v2.4.3 实测 572,951 字节，SHA-256 `38f25c10…299c93`）：2.2.0 删除独立页及其编辑器依赖、并关闭 source map 之后从 1.72 MB 降下来，之后随投影透传与权限 BFF 小幅增长。
+`npm pack` 的产物约 **0.55 MB**（v2.5.0 实测 572,951 字节，SHA-256 `38f25c10…299c93`）：2.2.0 删除独立页及其编辑器依赖、并关闭 source map 之后从 1.72 MB 降下来，之后随投影透传与权限 BFF 小幅增长。
 
-v2.4.3 在 DSH **0.2.1-rc.2** 上完成真机验证：14/14 宿主服务全部可注入、三个 jobs 端点实测通过、
-权限档位目录返回内核真实三档。开发基线为 `master@47f943859bef60e4160492346772ded9b24f765a`（内核 0.2.0-rc.2），
+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.4.3`
+- 当前版本：`v2.5.1`
+- **v2.5.1 是安全修复版**：堵住「开隧道/反代后管理面免凭据对公网开放」的远程提权（`/manage/**`
+  与回环 admin 头此前只按「TCP 来源是否回环」判定，而隧道转发进来的请求来源恒为 `127.0.0.1`），
+  并修复 `.heif` 交接图必被只读路由 415 的问题。升级后**开隧道时 `/manage` 一律 403**
+  （唯一例外是只读的隧道状态端点，且对非本机调用方隐去隧道地址）；桌面端面板不受影响。
+  见 `docs/project/SECURITY.md` §管理面的信任边界。
 - 作者：上游 [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/cordis.patch.yml

@@ -16,6 +16,20 @@
       # 这一条曾长期掩盖真相：`permissionPresets` 一直以为「web profile 注不进、
       # 只能走内置兜底目录」，实际是这里没声明它。`jobController` 加进来之后
       # 同样注不进，才顺着 `_refresh()` 的 INACTIVE 逻辑反查到这条覆盖规则。
+      # ⚠️ 这份列表**只能放「两个支持版本上都存在的服务」**。
+      # cordis 的 inject 是**硬依赖**：任何一个服务缺失 → 整个 entry 永久 INACTIVE。
+      # 2026-10-20 CI 实锤：把 jobController / fileUploads / attachments /
+      # permissionPresets 加进来后，插件在 **0.2.0-rc.2**（smoke-profile-install
+      # 检出的上游基线）上整体不激活，报
+      # "waiting for services: ..., jobController, fileUploads" ——
+      # 那一版内核的 web profile 没挂这些服务。
+      #
+      # 可选服务（permissionPresets / jobController / fileUploads / attachments /
+      # workingDirectory）**不在这里声明**，由插件在运行时经
+      # `ctx.reflect.get(name, false)` 读取（cordis 给「不带 inject 要求」读服务
+      # 准备的正路，见 dsh-0.2-bridge.ts 的 optionalService 注释）：
+      # 0.2.1-rc.2 上读到就走全功能，0.2.0-rc.2 上读不到就按能力位降级。
+      # 探针（GET /debug/host-services）继续报告这 5 个名字的真实可用性。
       inject: [
         sessionController,
         workspaceController,
@@ -23,20 +37,10 @@
         settingsController,
         credentialsController,
         agentPresets,
-        # 权限档位目录（`ctx.permissionPresets`）：内核把它做成独立的 Typert
-        # 远程服务，会话投影那条 wire 视图只给 currentValue、不带候选项。
-        permissionPresets,
         llm,
         webServer,
         agents,
         commands,
-        # 后台任务（`ctx.jobController`）：远程场景下任务跑飞了要能停掉。
-        jobController,
-        # 文件上传服务（`ctx.fileUploads`）：用它而不是内核那条只绑 loopback 的
-        # /api/session/uploadFileBinary HTTP 路由。
-        fileUploads,
-        # 附件存储（`ctx.attachments`）：会话历史里的图片以 attachmentId 引用存在。
-        attachments,
       ]
       config:
         # 状态目录**不改名**：已装的机器上有既有数据库与回收站，换目录等于让用户

package/docs/api/asyncapi.yaml

@@ -1,7 +1,7 @@
 asyncapi: 3.0.0
 info:
   title: DeepSeek Harness Mobile Events
-  version: 2.4.3
+  version: 2.5.1
   description: |
     Live file and authorized DSH chat events. Reconnect clients must refresh
     REST state; unbounded replay is not provided.

package/docs/api/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: DeepSeek Harness Mobile API
-  version: 2.4.3
+  version: 2.5.1
   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.1 }
   /debug/host-services:
     get:
       operationId: hostServices
@@ -1408,8 +1408,26 @@ components:
         configurable: { type: boolean }
         configured: { type: boolean }
         removable: { type: boolean }
+        defaultBaseURL: { type: string, description: '目录供应商的适配器默认 API 地址（未配置时使用）。' }
+        baseURLEnv:
+          type: array
+          items: { type: string }
+          description: '可能覆盖默认地址的环境变量，按优先级排序。'
+        nativeAuth: { $ref: '#/components/schemas/NativeAuthHint' }
+        settingsNs:
+          type: string
+          description: 目录条目的设置命名空间；客户端用它捕获 expectedRevision（打开卡片那一刻的 revision）。
         credential: { $ref: '#/components/schemas/CredentialState' }
         config: { $ref: '#/components/schemas/ProviderConfig' }
+    NativeAuthHint:
+      type: object
+      required: [env, oauth]
+      properties:
+        env:
+          type: array
+          items: { type: string }
+          description: '适配器原生认证依赖的环境变量。'
+        oauth: { type: boolean, description: '是否支持 OAuth 登录。' }
     ProviderSettings:
       type: object
       required: [writable, revisionByNamespace, customProvider, providers]
@@ -1433,7 +1451,8 @@ components:
         thinking: { type: [string, 'null'] }
         reasoningEffort: { type: [string, 'null'] }
         models:
-          type: array
+          type: [array, 'null']
+          description: '数组=整体替换模型目录（空数组=自定义空目录）；`null`=恢复适配器默认目录（unset）。'
           items: { $ref: '#/components/schemas/ProviderModel' }
         expectedRevision: { type: integer, minimum: 0 }
     CustomProviderCapability:

package/kotlin-sdk/src/main/kotlin/ai/deepseek/dsh/workspace/DshWorkspaceClient.kt

@@ -206,6 +206,12 @@ data class CredentialState(
     val writable: Boolean,
 )
 
+@Serializable
+data class NativeAuthHint(
+    val env: List<String> = emptyList(),
+    val oauth: Boolean = false,
+)
+
 @Serializable
 data class ProviderView(
     val id: String,
@@ -215,6 +221,11 @@ data class ProviderView(
     val configurable: Boolean,
     val configured: Boolean,
     val removable: Boolean,
+    val defaultBaseURL: String? = null,
+    val baseURLEnv: List<String>? = null,
+    val nativeAuth: NativeAuthHint? = null,
+    /** 目录条目的设置命名空间；客户端用它捕获 expectedRevision（打开卡片那一刻的 revision）。 */
+    val settingsNs: String? = null,
     val credential: CredentialState,
     val config: ProviderConfig,
 )
@@ -242,6 +253,7 @@ data class ProviderPatch(
     val apiKey: String? = null,
     val thinking: String? = null,
     val reasoningEffort: String? = null,
+    /** 数组=整体替换（空数组=自定义空目录）；恢复默认目录用 [DshWorkspaceClient.resetProviderModels]（wire `models: null`）。 */
     val models: List<ProviderModel>? = null,
     val expectedRevision: Int? = null,
 )
@@ -426,6 +438,27 @@ class DshWorkspaceClient(
         return executeJson("settings/providers/$providerId", "PATCH", body, ProviderSettings.serializer())
     }
 
+    /**
+     * 恢复供应商的适配器默认模型目录（wire `models: null`）。data class 无法把
+     * null 默认值与「字段缺席」区分开，所以这里手工拼 body。
+     */
+    fun resetProviderModels(providerId: String, expectedRevision: Int? = null): ProviderSettings {
+        val body = buildString {
+            append("{\"models\":null")
+            if (expectedRevision != null) append(",\"expectedRevision\":").append(expectedRevision)
+            append('}')
+        }
+        return executeJson("settings/providers/$providerId", "PATCH", body, ProviderSettings.serializer())
+    }
+
+    fun deleteProvider(providerId: String, expectedRevision: Int? = null) {
+        val relative = buildString {
+            append("settings/providers/").append(providerId)
+            if (expectedRevision != null) append("?expectedRevision=").append(expectedRevision)
+        }
+        executeUnit(relative, "DELETE", null)
+    }
+
     fun createCustomProvider(provider: CustomProviderCreate): ProviderSettings {
         val body = json.encodeToString(CustomProviderCreate.serializer(), provider)
         return executeJson("settings/providers", "POST", body, ProviderSettings.serializer())

package/lib/client.cjs

@@ -30231,6 +30231,10 @@ window.__ModuleLoader__.load({
 				errorNotFound: "请求的文件或资源不存在。",
 				errorConflict: "目标已存在或当前状态发生冲突。",
 				errorRateLimited: "请求过于频繁，请稍后重试。",
+				errorTunnelModeAdminDisabled: "云隧道正在运行，管理面已停用。请先在本机面板里停止隧道，或直接在本机 WebUI 操作。",
+				errorAdminProxyForwarded: "管理面不接受经代理转发的请求。请在本机用 127.0.0.1 或 localhost 直接打开。",
+				errorAdminHostNotLoopback: "管理面只在本机回环地址下可用。请用 127.0.0.1 或 localhost 打开本页。",
+				errorAdminLoopbackRequired: "此操作只能在本机执行。",
 				author: "作者 Github@Hakunm",
 				version: "当前版本"
 			},
@@ -30403,6 +30407,10 @@ window.__ModuleLoader__.load({
 				errorNotFound: "The requested file or resource was not found.",
 				errorConflict: "The target already exists or its state has changed.",
 				errorRateLimited: "Too many requests. Try again shortly.",
+				errorTunnelModeAdminDisabled: "The Cloudflare tunnel is running, so management endpoints are disabled. Stop the tunnel in the local panel, or use the local WebUI.",
+				errorAdminProxyForwarded: "Management endpoints do not accept proxied requests. Open them locally via 127.0.0.1 or localhost.",
+				errorAdminHostNotLoopback: "Management endpoints are available only under a loopback address. Open this page via 127.0.0.1 or localhost.",
+				errorAdminLoopbackRequired: "This operation is available only from the local machine.",
 				author: "Author Github@Hakunm",
 				version: "Current version"
 			}
@@ -31614,6 +31622,10 @@ window.__ModuleLoader__.load({
 			if (error.code === "LISTENER_PORT_INVALID") return "listenerPortInvalid";
 			if (error.code === "REMOTE_ENABLED") return "disableToEditListener";
 			if (error.code === "NO_ENDPOINT") return "configTextNoEndpoints";
+			if (error.code === "TUNNEL_MODE_ADMIN_DISABLED") return "errorTunnelModeAdminDisabled";
+			if (error.code === "ADMIN_PROXY_FORWARDED") return "errorAdminProxyForwarded";
+			if (error.code === "ADMIN_HOST_NOT_LOOPBACK") return "errorAdminHostNotLoopback";
+			if (error.code === "ADMIN_LOOPBACK_REQUIRED") return "errorAdminLoopbackRequired";
 			if (error.code.includes("PATH") || error.code.includes("SYMLINK") || error.code.includes("REPARSE")) return "errorPathInvalid";
 			if (error.status === 403) return "errorForbidden";
 			if (error.status === 404) return "errorNotFound";

package/lib/index.d.ts

@@ -78,7 +78,9 @@ declare class WorkspaceDatabase {
   readonly dataDir: string;
   readonly trashDir: string;
   private readonly db;
+  private closed;
   constructor(dataDir: string);
+  /** 关闭数据库。**幂等** —— 重复调用不抛错。 */
   close(): void;
   /**
    * 导出 `roots` 的建表语句（只读，诊断与迁移测试用）。
@@ -218,6 +220,12 @@ interface ConfigurableProvider {
   settingsPath: string[];
   active: boolean;
   declared?: boolean;
+  defaultBaseURL?: string;
+  baseURLEnv?: string[];
+  nativeAuth?: {
+    env?: string[];
+    oauth?: boolean;
+  };
 }
 interface SettingsApiProxy extends DshApiProxy {
   settings: {
@@ -326,6 +334,14 @@ interface ProviderView {
   configurable: boolean;
   configured: boolean;
   removable: boolean;
+  defaultBaseURL?: string;
+  baseURLEnv?: string[];
+  nativeAuth?: {
+    env?: string[];
+    oauth?: boolean;
+  };
+  /** 目录条目的设置命名空间；客户端用它捕获 expectedRevision（打开卡片那一刻的 revision）。 */
+  settingsNs?: string;
   credential: {
     ref: string;
     configured: boolean;
@@ -341,7 +357,8 @@ interface ProviderPatch {
   apiKey?: string | null;
   thinking?: string | null;
   reasoningEffort?: string | null;
-  models?: ProviderModelView[];
+  /** `null` 恢复适配器默认模型目录（unset），`[]` 写入自定义空目录。 */
+  models?: ProviderModelView[] | null;
   expectedRevision?: number;
 }
 interface CustomProviderCreate {
@@ -738,6 +755,14 @@ interface LlmLike {
     settingsNs: string;
     settingsPath: readonly string[];
     declared?: boolean;
+    defaultBaseURL?: string;
+    /** Environment variables that may override the default base URL, in priority order. */
+    baseURLEnv?: readonly string[];
+    /** Native authentication the adapter can fall back to when no key is stored. */
+    nativeAuth?: {
+      env?: readonly string[];
+      oauth?: boolean;
+    };
     error?: string;
   }[];
   discoverModels(settingsNs: string, request: unknown, signal?: AbortSignal): Promise<readonly unknown[]>;
@@ -761,7 +786,14 @@ interface Dsh02HostServices {
   settingsController: SettingsControllerLike;
   credentialsController: CredentialsControllerLike;
   agentPresets: AgentPresetsLike;
-  permissionPresets: PermissionPresetsLike;
+  /**
+   * 权限档位目录（`ctx.permissionPresets`）——**可选**。
+   *
+   * 0.2.1 的 web profile 上有；0.2.0-rc.2 上没有。inject 是硬依赖，
+   * 所以它不能进 inject，只能声明成可选，由 `optionalService` 运行时读；
+   * 读不到时权限档位走 `FALLBACK_PERMISSION_CATALOG` + BFF。
+   */
+  permissionPresets?: PermissionPresetsLike;
   /**
    * 后台任务控制器（`ctx.jobController`，`@deepseek-ai/dsh-api-job-controller`）。
    *
@@ -771,7 +803,14 @@ interface Dsh02HostServices {
    * 与 `sessionController` 不同，这个是 `TypertRemoteService`（不是 `@Remote`
    * 控制器集合），但结构类型消费方式完全一样：只声明用到的成员，缺了就明确报错。
    */
-  jobController: JobControllerLike;
+  /**
+   * 后台任务控制器（`ctx.jobController`）——**可选**。
+   *
+   * 只有 DSH 0.2.1 的 web profile 挂了这个服务；0.2.0-rc.2 上没有，
+   * 而 inject 是硬依赖（缺一个整个插件不激活），所以它**不能**出现在 inject 里，
+   * 只能在这里声明成可选，由 `optionalService` 运行时读。
+   */
+  jobController?: JobControllerLike;
   llm: LlmLike;
   /**
    * 内核附件存储（`ctx.attachments`）；会话历史里的图片要经它取字节。
@@ -782,14 +821,23 @@ interface Dsh02HostServices {
    * `cannot get property "attachments" without inject` —— 请求链路本身没问题，
    * 挂在服务端、而且只在真的去取图时才炸，所以很难在本地测出来。
    */
-  attachments: AttachmentStoreLike;
   /**
-   * Kernel file-upload service (`ctx.fileUploads`).
+   * 内核附件存储（`ctx.attachments`）——**可选**。
+   *
+   * 0.2.0-rc.2 的 web profile 上没有这个服务（诊断日志实测 MISSING），
+   * 而 inject 是硬依赖，所以它只能声明成可选，由 `optionalService` 运行时读；
+   * 读不到时附件读取走内核 `sessionController.attachment()`。
+   */
+  attachments?: AttachmentStoreLike;
+  /**
+   * Kernel file-upload service (`ctx.fileUploads`)——**可选**。
    *
    * 为什么用它而不是内核那条 `/api/session/uploadFileBinary` HTTP 路由：那条路由
    * 只绑 loopback（手机根本到不了），而这个 cordis 服务就在同一个进程里，插件可直接调。
+   *
+   * 可选的原因同 [attachments]：0.2.0-rc.2 的 web profile 上没有它。
    */
-  fileUploads: FileUploadsLike;
+  fileUploads?: FileUploadsLike;
   /**
    * Cordis event bus of the host context. Used for the two facts the old
    * `apiProxy` event streams carried that no controller returns: session
@@ -1573,16 +1621,40 @@ declare class FixedWindowLimiter {
 }
 //#endregion
 //#region src/host/auth.d.ts
+interface AuthServiceOptions {
+  /**
+   * 隧道运行状态探针（`CloudflaredTunnelManager.tunnelActive`）。
+   *
+   * 用函数而不是快照：隧道随时启停，鉴权发生在请求那一刻，读的必须是当下状态。
+   * 不注入（测试、未接隧道的构建）即为「没有隧道」，判据 0 恒不触发。
+   */
+  tunnelActive?: () => boolean;
+}
 declare class AuthService {
   private readonly database;
+  private readonly options;
   private readonly authFailures;
   readonly pairingAttempts: FixedWindowLimiter;
   readonly requests: FixedWindowLimiter;
-  constructor(database: WorkspaceDatabase);
+  constructor(database: WorkspaceDatabase, options?: AuthServiceOptions);
+  /**
+   * 隧道是否在跑。探针抛错时**按「在跑」处理**（fail closed）：探针读的是我们自己
+   * 对象上的 getter，它抛错意味着状态不可知；状态不可知时放行管理面正是这次修复要
+   * 消灭的那类决定。
+   */
+  private tunnelRunning;
   principal(req: IncomingMessage, options?: {
     allowAdmin?: boolean;
   }): Principal;
-  requireAdmin(req: IncomingMessage): Principal;
+  /**
+   * `/manage/**` 的守门人。
+   *
+   * @param options.allowTunnelMode - 只有「隧道状态下读/停隧道」这几个端点会传 true。
+   *   见 `adminRefusal` 的同名说明与 `router.ts` 的 `TUNNEL_MODE_EXEMPT_PATHS`。
+   */
+  requireAdmin(req: IncomingMessage, options?: {
+    allowTunnelMode?: boolean;
+  }): Principal;
   requireScope(principal: Principal, scope: DeviceScope): void;
   requireRoot(principal: Principal, rootId: string): void;
 }
@@ -1802,6 +1874,17 @@ declare class CloudflaredTunnelManager {
   reportActivity(a: TunnelActivity): void;
   /** 任务结束（成功或失败）时清空进行中进度。 */
   clearActivity(): void;
+  /**
+   * 是否有隧道在运行 —— 管理面鉴权的**判据 0**。
+   *
+   * 判据取自**进程持有状态**，不是请求头，所以它对「隧道把外部流量转进 127.0.0.1」
+   * 这条绕过路径 100% 可靠：不管转发进来的请求长什么样，只要隧道开着，管理面就关门。
+   * 见 `auth.ts` 的 `adminRefusal` 与 `PITFALLS.md` §隧道让回环判据失效。
+   *
+   * `running` 与 `publicState.running` 是同一个表达式（同一份真相），这里单独暴露是为了
+   * 让鉴权层不必构造一个含 url 的视图对象 —— 少一处把地址带进意外地方的机会。
+   */
+  get tunnelActive(): boolean;
   get publicState(): TunnelPublicState;
   /** 订阅状态变化；返回取消函数。 */
   onStatus(cb: () => void): () => void;
@@ -1937,6 +2020,22 @@ declare class ApiRouter {
   handle(req: IncomingMessage, res: ServerResponse, stripPrefix?: string): Promise<void>;
   private dispatch;
   private dispatchManagement;
+  /**
+   * 隧道状态视图。
+   *
+   * **这里不做脱敏，因为用不上**：判据 1 已经把 Cloudflare 边缘头（`Cf-Connecting-IP` /
+   * `Cf-Ray` / …）算作「前面有代理」的证据，于是任何真实隧道来源的请求在
+   * `requireAdmin` 就被 403 挡住了，根本到不了这个方法。能走到这里的只有真·本机请求
+   * （判据 1/2/3 全过），所以 `url` 可以照常给它 —— 那是桌面端「用隧道地址生成配置文本」
+   * 的依据。
+   *
+   * 为什么仍然保留这个方法而不是直接 `publicState`：脱敏的位置要留在一个**语义明确**的
+   * 出口上。将来若有人为了「让远程客户端也能读到隧道是否开着」而放宽判据 1，
+   * 必须在这里重新定义脱敏，而不是顺手把 `url` 一起放出去。
+   * 评估结论见报告：本轮选择「远程一律 403」而不是「远程读得到但 `url` 为 null」，
+   * 因为后者需要为状态端点在判据 1 上再开一个口子，而那正是这次修复要消灭的东西。
+   */
+  private tunnelStateFor;
   private dispatchEntries;
   private dispatchContent;
   private requireRoot;