Third-party plugins cannot expose settings namespaces to the web settings page (WEB_SETTINGS_NAMESPACES whitelist is upgrade-fragile)

[Ye-Yu-Mo]

Summary

A plugin installed from outside this repo cannot make its settings namespace editable in the web settings page. Even after the plugin registers its namespace (via installSettingsSection / settings.register) and contributes a settings.section cell on the client, web reads/writes are refused with settings-not-exposed unless the namespace is manually appended to WEB_SETTINGS_NAMESPACES in packages/host/apiproxy. That list is a hardcoded const in the shipped package, so the patch is overwritten on every dsh upgrade (npx reinstall / @deepseek-ai/dsh update) — a silent regression for the plugin's users.

Reproduction

1. Install a third-party plugin, e.g. dsh plugin --profile web add link:/path/to/my-plugin, whose host half calls installSettingsSection(ctx, 'my-ns', schema, entry, hooks) and whose client half registers a settings.section cell (id: 'my-ns').

2. Open Settings → the plugin's page, change a field, hit Save.

3. Expected: the write persists (schema validation + revision fencing apply).

4. Actual: the write is refused before the settings seam is touched:

   settings-not-exposed: settings namespace "my-ns" is not exposed to configuration clients

   Editing ~/.dsh/settings.yaml directly works fine.

Workaround: append 'my-ns' to WEB_SETTINGS_NAMESPACES in both lib/index.js and lib/types/api-proxy.js of the installed @deepseek-ai/dsh-host-apiproxy, then restart. Fragile: any dsh update wipes it, and the source src/ tree ships without the entry, so the divergence is easy to miss.

Background

The design note .agents/notes/implemented/feature/2026-08-10-web-plugin-configuration.zh.md already records this as a deliberate cost:

「暴露仍是 Host 的白名单。仅有注册依然不会跨越传输边界……加入第四个插件仍需要在 apiproxy 白名单里添一条，因此本页的覆盖面是 Host 的决定而非插件的决定。」

and documents the preferred alternative — a registration-time exposure declaration:

「用注册期的暴露声明取代白名单。这才是诚实的形状——命名空间的拥有方声明自己的暴露，在本仓库之外分发的插件也无需改动 packages/host/apiproxy 就能呈现自己的配置。」

deferred because it would change the seam contract, every existing registration point, anti-enumeration semantics, and needs a fail-closed redaction path before plugins may expose arbitrary schemas.

Proposal

Implement the registration-time exposure declaration, e.g. an expose option on settings.register(ns, schema, { expose }) (or a dedicated registration call), addressing the deferred concerns:

• Anti-enumeration: only namespaces the owning plugin explicitly marks exposed are served to configuration clients; describe/get for others keep answering settings-not-exposed exactly as today.
• Redaction: reuse the existing settings.describe({ redactSecrets: true }) path so an exposed arbitrary schema still never leaks secrets over the wire (the current seam already redacts before views are built).
• Migration: default expose: false keeps today's semantics for existing callers; in-repo namespaces flip to expose: true as they're migrated off WEB_SETTINGS_NAMESPACES, which can then be removed.

Until then, at minimum it would help to document the whitelist requirement for third-party plugin authors — the runtime error message already points to the workaround, but the docs don't, and the upgrade-overwrite failure mode is hard to diagnose.

(Encountered with a local third-party plugin dsh-llm-proxy; happy to provide more detail or a minimal repro repo.)

---