dsh-remote-bridge 2.5.2 → 2.6.1

package/README.en.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-v2.5.2-087f8c">
+  <img alt="Version" src="https://img.shields.io/badge/version-v2.6.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">
@@ -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.2/dsh-remote-bridge-v2.5.2.tgz
+dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.6.1/dsh-remote-bridge-v2.6.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.5.2/dsh-remote-bridge-v2.5.2.tgz
+dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.6.1/dsh-remote-bridge-v2.6.1.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.2.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.6.1.tgz
 ```
 
 ## First connection
@@ -219,10 +219,28 @@ The following controls remain active over both HTTP and HTTPS:
 - revocable scopes and per-root grants;
 - separate rate limits for pairing, authentication failures, and normal requests;
 - audit records that omit tokens, file bodies, and chat bodies;
-- no automatic access to roots added after a device was paired.
+- no automatic access to roots added after a device was paired;
+- provider `baseURL` changes are limited to public http(s) destinations, and moving a
+  provider that already stores a credential to a new host also requires a fresh API key
+  (the kernel sends that key to the address, so this is a credential boundary, not just SSRF).
 
 Only a loopback client may add roots, change device grants, create pairing codes, configure the listener, or permanently purge trash.
 
+### Local LLM endpoints (ollama / LM Studio)
+
+Private, loopback, link-local and CGNAT provider addresses are **rejected by default**.
+To use a local model server, list it explicitly in the plugin config:
+
+```yaml
+allowPrivateProviderHosts:
+  - 127.0.0.1:11434     # recommended: pin the port
+  - 192.168.1.5         # bare host: allows every port on that host
+```
+
+Exact `host` or `host:port` only — CIDR is not supported. Prefer the `host:port` form:
+allowing `192.168.1.5` allows every service on it, while ollama only listens on 11434.
+See `docs/project/SECURITY.md` for the reasoning and the audit trail fields.
+
 ## Path boundary
 
 External requests use `rootId + relativePath`, never an absolute server path.
@@ -297,6 +315,16 @@ A device also needs an explicit grant for every `rootId`. Local administrators m
 
 **New scopes are picked before pairing, in Remote access**: whatever you tick is what the generated pairing code carries, and those scopes take effect once the app enters the code. For a device that is already paired, open **Devices** and use its **Permissions** button.
 
+The default selection is five scopes — `chat.read`, `chat.write`, `files.read`, `files.write`, `settings.read` — and **deliberately excludes** `files.delete` and `settings.write`. You can still tick them; the default just no longer hands out destructive permissions on its own.
+
+### Device names and models
+
+At pairing time the bridge has no idea who will use the token, so a new device starts with a **platform-neutral** placeholder name (`Mobile device`). The first time the device connects, the bridge works out its platform and model from the request and replaces the name with `platform · model` (for example `HarmonyOS · ICL-AL10`).
+
+Platform detection prefers the client-declared `X-Dsh-Device: <platform>/<model>` header and falls back to the `User-Agent`. **The model is only taken from what the client reports**: neither okhttp nor ArkWeb puts a model in its default UA, and the bridge will not guess — a wrong model is worse than no model.
+
+Open **Devices** and use **Permissions** to rename a device. **A name you set yourself is never overwritten**; an automatically generated name still updates when the device reports a new identity. Device names are for display and troubleshooting only and take no part in authorization.
+
 **Revoking a device deletes it from the database** rather than leaving a marker row behind. Its grants go with it, while the audit trail (who revoked which device, and when) is kept.
 
 ## Upgrade and uninstall
@@ -354,19 +382,33 @@ pnpm pack
 
 `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.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.
+`npm pack` produces roughly a **0.64 MB** archive (v2.6.1 measured 669,434 bytes, SHA-256 `9bf0189b…2cd35`): 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
+**v2.6.1 verification status**: 74 test files / 682 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.
+The SEC-H11 attack chain was confirmed **by measurement** (a fake LLM endpoint was stood up and the
+kernel was observed sending the real `Authorization: Bearer` to it); each of the four gates now has a
+regression assertion. The three device-identity specs (27 + 13 + 12 cases) cover the UA detection
+order, "a `declared` name is never overwritten", and idempotent migration of the old table shape.
 
 ## Project
 
-- Version: `v2.5.2`
+- Version: `v2.6.1`
+- **v2.6.1 is the security-fix + device-identity release**: it closes a **high-severity** hole —
+  the three provider `baseURL` entry points (create / update / model discovery) performed no
+  validation at all, so a device holding `settings.write` could point the baseURL at its own server
+  and the kernel would request `/models` there with **that provider's real API key**, leaking the
+  credential outright; the persistent variant was worse, since after changing the baseURL every
+  subsequent chat would send the key there. There are now three gates (protocol allow-list,
+  private networks denied by default with an explicit `allowPrivateProviderHosts` opt-in, and a
+  new key required when repointing a provider that already holds a credential), and the pairing
+  default was narrowed from seven scopes to five (no more `settings.write` / `files.delete` by default).
+  It also fixes "the device name is always 'Android device'": the bridge now derives the platform and
+  model from the `X-Dsh-Device` header (User-Agent as fallback), renames the placeholder to
+  "platform · model", and offers a rename channel (a manually set name is never overwritten).
+- **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,

package/README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <img alt="Version" src="https://img.shields.io/badge/version-v2.5.2-087f8c">
+  <img alt="Version" src="https://img.shields.io/badge/version-v2.6.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">
@@ -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.2/dsh-remote-bridge-v2.5.2.tgz
+dsh plugin --profile web add https://github.com/westanke/dsh-remote-bridge/releases/download/v2.6.1/dsh-remote-bridge-v2.6.1.tgz
 
 # ③ Gitee Release 的 tarball（国内访问更快）
-dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.5.2/dsh-remote-bridge-v2.5.2.tgz
+dsh plugin --profile web add https://gitee.com/westanke/dsh-remote-bridge/releases/download/v2.6.1/dsh-remote-bridge-v2.6.1.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.2.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.6.1.tgz
 ```
 
 ## 第一次使用
@@ -182,14 +182,59 @@ dsh plugin --profile web add ./dsh-remote-bridge-v2.5.2.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 或域名连接。
@@ -206,9 +251,27 @@ dsh plugin --profile web add ./dsh-remote-bridge-v2.5.2.tgz
 - 配对、认证和普通请求分别限流。
 - 审计记录操作类型和对象，但不记录令牌、文件正文或聊天正文。
 - 新增根目录不会自动授权给已经配对的设备。
+- 供应商 `baseURL` 只能指向公网 http(s) 地址；把「已经存有凭据」的供应商换到新 host
+  还必须同时提供新的 API key —— 因为内核会带着那把 key 去请求这个地址，这是凭据边界，
+  不只是 SSRF。
 
 只有来自回环地址的管理界面可以添加根目录、调整设备权限、生成配对码、修改监听设置和永久清理回收站。
 
+### 自建 LLM（ollama / LM Studio）
+
+私网、回环、链路本地与 CGNAT 的供应商地址**默认拒绝**。要用本机模型服务，在插件配置里
+显式放行：
+
+```yaml
+allowPrivateProviderHosts:
+  - 127.0.0.1:11434     # 推荐：钉住端口
+  - 192.168.1.5         # 裸 host：放行该主机的全部端口
+```
+
+只接受精确 `host` 或 `host:port`，**不支持 CIDR**。推荐带端口写法：放行 `192.168.1.5`
+等于放行它上面所有服务，而 ollama 只在 11434。理由与审计字段见
+[docs/project/SECURITY.md](docs/project/SECURITY.md#供应商-baseurl-的地址策略261-起sec-h11)。
+
 ## 文件边界
 
 外部接口只接受 `rootId + relativePath`，不会接收服务器绝对路径。路径还会经过以下检查：
@@ -283,6 +346,16 @@ Authorization: Bearer DEVICE_TOKEN
 
 **新增的权限是配对前在「远程访问」里勾选的**：勾什么，生成的配对码就带什么；APP 输入配对码后这些权限随设备一起生效。已在用的设备则到「设备」里点它的「权限」修改。
 
+默认勾选是五档 —— `chat.read`、`chat.write`、`files.read`、`files.write`、`settings.read`，**刻意不含** `files.delete` 与 `settings.write`。你仍然可以自己勾上；默认值只是不再替你做这个决定。
+
+### 设备名与型号
+
+配对那一刻桥并不知道将来是谁来用这个令牌，所以新设备先得到一个**平台无关**的占位名（`Mobile device`）。设备第一次连上来时，桥会从请求里识别平台与型号，把名字自动换成「平台 · 型号」（比如 `HarmonyOS · ICL-AL10`）。
+
+平台判定优先看客户端上报的 `X-Dsh-Device: <platform>/<model>` 头，没有就从 `User-Agent` 兜底。**型号只认客户端上报**：OkHttp 与 ArkWeb 的默认 UA 里都没有机型，桥不会去猜 —— 猜错的型号比没有型号更糟。
+
+在「设备」页点「权限」可以直接改名。**你手动改过的名字不会再被自动覆盖**；自动生成的名字在设备上报了新身份时仍会更新。设备名只用于显示与排查，不参与任何授权判断。
+
 **撤销一台设备会直接把它从数据库里删除**，不是打个标记留着；它的授权随之清除，但审计记录（谁在什么时候撤了谁）会保留。
 
 ## 升级与卸载
@@ -340,20 +413,30 @@ pnpm pack
 
 `pnpm check` 覆盖类型检查、文档一致性与测试；当前 **67 个测试文件 / 557 个用例**，外加 **8 个浏览器层用例**（Playwright 实测量出的计算样式，含 375px 窄屏契约），全部通过。
 
-`npm pack` 的产物约 **0.61 MB**（v2.5.2 实测 635,316 字节，SHA-256 `1779c02e…bdd3bd`）：2.2.0 删除独立页及其编辑器依赖、并关闭 source map 之后从 1.72 MB 降下来，之后随投影透传、权限 BFF 与五维加固小幅增长。
+`npm pack` 的产物约 **0.64 MB**（v2.6.1 实测 669,434 字节，SHA-256 `9bf0189b…2cd35`）：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.6.1 的验证状态**：74 个测试文件 / 682 个用例全绿、8 个 Playwright 浏览器用例
+（含 375px 窄屏契约）、`typecheck`/`docs:check`/构建通过。SEC-H11 的攻击链是**用实测**
+确认的（起一个假 LLM 端点，抓到内核把真实 `Authorization: Bearer` 打过去），修复后的
+四道闸门各有回归断言；设备身份的三个 spec（27 + 13 + 12 例）覆盖 UA 判定顺序、
+「`declared` 永不覆盖」与老表结构迁移幂等。
 
 ## 项目信息
 
-- 当前版本：`v2.5.2`
+- 当前版本：`v2.6.1`
+- **v2.6.1 是安全修复 + 设备身份版**：修掉一个**高危**问题 —— 供应商 `baseURL` 的三个入口
+  （新建 / 修改 / 探测模型）此前不做任何校验，持有 `settings.write` 的设备可以把 baseURL
+  指向自己的服务器，内核会带着**该供应商的真实 API key** 去请求 `/models`，等于凭据直接外泄；
+  持久化变体更糟：改完 baseURL 之后正常聊天都会把 key 发过去。现在三道闸门（协议白名单、
+  私网默认拒绝 + `allowPrivateProviderHosts` 显式放行、换 host 且已有凭据时必须同时给新 key），
+  配对默认权限也从七档收到五档（不再默认给 `settings.write` 与 `files.delete`）。
+  另修「设备名永远是『Android 设备』」：桥现在从 `X-Dsh-Device` 头（UA 兜底）识别平台与型号，
+  自动把占位名换成「平台 · 型号」，并新增改名通道（手动改过的名字永不被自动覆盖）。
+- **v2.6.0 是通用设置面 + IM 入口版**：新增「按插件划分的设置命名空间」两个端点（手机端照 schema 自建表单，新装插件无需改 App），以及「人已出门、电脑还锁着」时用 IM 一句话开隧道并收回配对配置的双入口（宿主命令 `/tunnel` + 工具 `open_tunnel_config`）；另加一键清理 N 天未使用设备、移除审计页，并把「激活期降级保护」补上（apply 尾部抛错不再拆掉整条插件上下文）。
 - **v2.5.2 是全量完善版**：落地五维审计（安全/功能/性能/界面/按钮反馈）——含高危的
   `debug/host-services` 免鉴权信息泄露修复、限流双桶、广播背压、弱 ETag、审计保留策略等，
   并把「一键开隧道并生成令牌」做成同一次请求内搭车完成；隧道运行时管理面安全锁定，

package/docs/api/asyncapi.yaml

@@ -1,7 +1,7 @@
 asyncapi: 3.0.0
 info:
   title: DeepSeek Harness Mobile Events
-  version: 2.5.2
+  version: 2.6.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.5.2
+  version: 2.6.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.5.2 }
+                  pluginVersion: { type: string, const: 2.6.1 }
   /debug/host-services:
     get:
       operationId: hostServices
@@ -506,7 +506,16 @@ paths:
         '403': { $ref: '#/components/responses/Error' }
     post:
       operationId: createCustomProvider
-      description: Creates a fully custom llm-pi-ai provider using the protocols reported by ProviderSettings.customProvider.
+      description: |
+        Creates a fully custom llm-pi-ai provider using the protocols reported by
+        ProviderSettings.customProvider.
+
+        `baseURL` must be an absolute http(s) URL. Private, loopback, link-local and
+        CGNAT destinations are rejected with `403 PROVIDER_BASE_URL_FORBIDDEN` unless the
+        deployment lists the host in `allowPrivateProviderHosts` (exact `host` or
+        `host:port`, no CIDR). The kernel sends the provider's stored API key to this
+        address, so the check is what keeps a paired device from redirecting credentials.
+        See SECURITY.md ("供应商 baseURL 的地址策略").
       requestBody:
         required: true
         content:
@@ -519,6 +528,7 @@ paths:
             application/json:
               schema: { $ref: '#/components/schemas/ProviderSettings' }
         '400': { $ref: '#/components/responses/Error' }
+        '403': { $ref: '#/components/responses/Error' }
         '409': { $ref: '#/components/responses/Error' }
   /settings/plugins:
     get:
@@ -579,6 +589,68 @@ paths:
           content:
             application/json:
               schema: { $ref: '#/components/schemas/ModelCatalog' }
+  /settings/namespaces:
+    get:
+      operationId: listSettingsNamespaces
+      summary: Read every DSH plugin settings namespace
+      description: |
+        Returns the host's per-plugin settings document as one entry per namespace, so a
+        mobile client can build a form from `schema` without a dedicated endpoint per
+        plugin. Requires `settings.read`.
+
+        The top-level `writable` mirrors the host settings document. Each entry's
+        `writable` is that value AND the bridge's write policy: namespaces starting with
+        `ui-` or ending in `locale` are writable by default; high-risk ones (`llm-*`,
+        `permission`, `agent-default-model`, `subagent-*`, …) are read-only unless the
+        deployment explicitly allows them through `settingsWriteNamespaces`. When an
+        entry is not writable, `reason` says why: `HOST_READONLY` (the whole settings
+        document is read-only) or `HIGH_RISK_NAMESPACE` (write policy).
+
+        Secret values never leave the host: the kernel already redacts fields declared as
+        secrets, and the bridge additionally masks string values whose key matches
+        `apiKey|secret|token|password|credential|apiKeyEnv` with `***`.
+      responses:
+        '200':
+          description: All namespaces, with secret values redacted and per-namespace writability.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SettingsNamespaces' }
+        '403': { $ref: '#/components/responses/Error' }
+  /settings/namespaces/{ns}:
+    parameters:
+      - name: ns
+        in: path
+        required: true
+        schema: { type: string }
+        description: Namespace id (a plugin name such as `ui-chat`).
+    patch:
+      operationId: mutateSettingsNamespace
+      description: |
+        Applies path-addressed `set` / `unset` operations to one namespace, mirroring the
+        kernel's `settings.mutate`. Requires `settings.write`; at most 32 operations per
+        request. A successful mutation is audited as `settings.namespace.mutate` with the
+        touched field paths only — never the values.
+
+        Only namespaces allowed by the write policy can be changed; others answer
+        403 `SETTINGS_NAMESPACE_READONLY`. `expectedRevision` is optimistic concurrency:
+        a mismatch answers 409 `SETTINGS_CONFLICT`; an invalid ops body answers
+        400 `SETTINGS_OPS_INVALID`; a missing host settings service answers
+        503 `SETTINGS_UNAVAILABLE`.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/SettingsNamespaceOps' }
+      responses:
+        '200':
+          description: The mutated namespace, in the same shape as one entry of `SettingsNamespaces.namespaces`.
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SettingsNamespaceSummary' }
+        '400': { $ref: '#/components/responses/Error' }
+        '403': { $ref: '#/components/responses/Error' }
+        '409': { $ref: '#/components/responses/Error' }
+        '503': { $ref: '#/components/responses/Error' }
   /settings/providers/{providerId}:
     parameters:
       - name: providerId
@@ -587,7 +659,15 @@ paths:
         schema: { type: string }
     patch:
       operationId: updateProvider
-      description: Updates provider settings and optionally writes an API key to the DSH credential store.
+      description: |
+        Updates provider settings and optionally writes an API key to the DSH credential store.
+
+        `baseURL` goes through the same address policy as creation. In addition, moving a
+        provider that already holds a credential to a different host requires supplying a
+        new `apiKey` in the same patch (`403 PROVIDER_BASE_URL_REPOINT_FORBIDDEN`) —
+        otherwise a paired device could point a live key at its own public domain, which
+        the private-address rule cannot catch. Changing models, the display name, or the
+        path within the same host is unaffected.
       requestBody:
         required: true
         content:
@@ -613,6 +693,11 @@ paths:
   /settings/providers/{providerId}/discover:
     post:
       operationId: discoverProviderModels
+      description: |
+        Fetches `GET {baseURL}/models` through the kernel, carrying the provider's stored
+        credential. `baseURL` here is a temporary override that is NOT persisted, so a
+        rejected address never reaches the config — but it does reach the network unless
+        the address policy allows it. Same rules as creation.
       parameters:
         - name: providerId
           in: path
@@ -640,6 +725,8 @@ paths:
                   models:
                     type: array
                     items: { $ref: '#/components/schemas/ProviderModel' }
+        '400': { $ref: '#/components/responses/Error' }
+        '403': { $ref: '#/components/responses/Error' }
   /chat/sessions:
     get:
       operationId: listChatSessions
@@ -1350,6 +1437,28 @@ components:
         rootIds:
           type: array
           items: { type: string }
+        platform:
+          type: string
+          description: >-
+            Platform the device reported, or the one inferred from its
+            User-Agent when it reported nothing. Absent for devices that never
+            connected since the bridge started collecting it. Informational
+            only — it is client-declared and never takes part in authorization.
+          enum: [android, harmonyos, ios, ipados, web, windows, macos, linux]
+        model:
+          type: string
+          description: >-
+            Model the device reported. Often absent: neither okhttp nor ArkWeb
+            puts a model in its default User-Agent, and the bridge deliberately
+            does not guess — a wrong model is worse than no model.
+        nameSource:
+          type: string
+          description: >-
+            Where `name` came from. `default` (pairing placeholder) and
+            `detected` (auto-generated from the reported identity) may still be
+            replaced when the device reports a different identity; `declared`
+            means a human set it and it is never overwritten automatically.
+          enum: [default, detected, declared]
     FileEntry:
       type: object
       required: [name, path, kind, size, modifiedAt, writable]
@@ -1624,6 +1733,83 @@ components:
         providers:
           type: array
           items: { $ref: '#/components/schemas/Provider' }
+    SettingsNamespaceSecret:
+      type: object
+      description: One secret slot reported by the host. Only its path and whether it is set are exposed, never the value.
+      required: [path, set]
+      properties:
+        path:
+          type: array
+          items: { type: string }
+        set: { type: boolean }
+    SettingsNamespaceSummary:
+      type: object
+      description: One DSH settings namespace as seen by a remote client, with secret values redacted.
+      required: [ns, revision, value, writable]
+      properties:
+        ns: { type: string, examples: [ui-chat, ui-theme] }
+        revision: { type: integer, minimum: 0 }
+        schema:
+          type: object
+          additionalProperties: true
+          description: Kernel schema tree for form generation; its shape is kernel-defined.
+        value:
+          description: Effective value (base merged with user overrides), recursively redacted.
+        base:
+          description: Built-in default value, recursively redacted.
+        user:
+          description: User overrides only, recursively redacted.
+        autoGenerate:
+          type: object
+          additionalProperties: true
+          description: Kernel-reported fields that are generated automatically.
+        applies:
+          type: object
+          additionalProperties: true
+          description: Kernel-reported applicability conditions for this namespace.
+        secrets:
+          type: array
+          items: { $ref: '#/components/schemas/SettingsNamespaceSecret' }
+        writable:
+          type: boolean
+          description: The host document is writable AND this namespace passes the bridge's write policy.
+        reason:
+          type: string
+          enum: [HOST_READONLY, HIGH_RISK_NAMESPACE]
+          description: Present only when `writable` is false.
+    SettingsNamespaces:
+      type: object
+      required: [writable, namespaces]
+      properties:
+        writable:
+          type: boolean
+          description: Whether the host settings document itself is writable.
+        namespaces:
+          type: array
+          items: { $ref: '#/components/schemas/SettingsNamespaceSummary' }
+    SettingsNamespaceOps:
+      type: object
+      description: Path-addressed operations and optional optimistic-concurrency revision.
+      required: [ops]
+      properties:
+        ops:
+          type: array
+          minItems: 1
+          maxItems: 32
+          items:
+            oneOf:
+              - type: object
+                required: [op, path, value]
+                properties:
+                  op: { type: string, const: set }
+                  path: { type: array, items: { type: string } }
+                  value: {}
+              - type: object
+                required: [op, path]
+                properties:
+                  op: { type: string, const: unset }
+                  path: { type: array, items: { type: string } }
+        expectedRevision: { type: integer, minimum: 0 }
     ProviderPatch:
       type: object
       properties:

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

@@ -46,6 +46,12 @@ data class DeviceView(
     val name: String,
     val scopes: List<String>,
     val rootIds: List<String>,
+    /** 平台：`android` / `harmonyos` / `ios` / …。老桥与从未连过的设备没有这个字段。 */
+    val platform: String? = null,
+    /** 型号。桥刻意不猜（okhttp/ArkWeb 默认 UA 里没有机型），所以多数时候是 null。 */
+    val model: String? = null,
+    /** `name` 的来源：`default` / `detected` / `declared`。null 等价于 `declared`。 */
+    val nameSource: String? = null,
 )
 
 @Serializable