@linxin666/dsh-remote-web-ui 0.2.6 → 0.2.8

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   node scripts/verify-docs.mjs --write <dir>
-README.md: 290224ef41cca3f8d8820fc37b985edbfe2d6549
-README.zh.md: 10b01e05a61885c53b48b2e9542a269119674f8a
+README.md: dc31fab1b49b32fe325ead616d52846435fa1180
+README.zh.md: e5ccaf0f52d01e9b8f92e265947c22dff68e2a97

package/README.md

@@ -65,7 +65,10 @@ that probes and runs the update.
   `/api/dsh-desktop-launcher/*` and `/api/dsh-web-ui-settings/*` control
   endpoints stay loopback-only. Unpaired desktop browsers get a persistent
   full-page block instead of data (the page keys off the `unpaired` error
-  code, not every 403).
+  code, not every 403). The block retires once a gated call succeeds or the
+  channel itself is torn down — turning `requirePairingForLan` off (or the
+  plugin off) also clears a notice raised while the channel was briefly
+  active.
 - **Posture probe**: the plugin probes the SDK `/api` fence with forged
   Host headers (the public base and every LAN base). A 403 is the default
   stance (fence closed; remote access goes through pairing). Anything other
@@ -473,6 +476,10 @@ opens at `http://127.0.0.1`.
   unpair one at a time. Credential-bearing device ids and raw User-Agent
   values are not rendered. `/api/pair/status` never returns the device id
   list, even to a paired phone.
+- **The desktop gate policy is public**: `/api/pair/status` exposes only the
+  boolean `requirePairingForLan` policy so a remote desktop can choose the
+  correct transport before its settings scope is available. This field is
+  not a credential and does not expose tokens, devices, counts, or tunnel URLs.
 - **Quick-tunnel hostnames change per run**: a `trycloudflare.com` URL is
   random on every `cloudflared` start, so `publicBaseUrl` must be updated
   whenever the tunnel restarts. A named tunnel (fixed hostname) avoids the

package/README.zh.md

@@ -13,7 +13,7 @@
 - **手机侧**：扫码将手机与一次性、限时令牌绑定，并落地到 **`/m/` 独立移动端界面**——一款专为小屏设计的轻客户端（见[截图](#截图)），而不是把桌面 UI 塞进手机。该页面可安装为 PWA；每个已安装应用使用自己的已配对设备 cookie，存储隔离的移动端 Web App 需要在该上下文打开新的二维码链接，或粘贴桌面端新复制的链接完成配对。链接携带 `workspace` 参数，手机落地到桌面正在查看的同一工作区。
 - **PC 侧（远程桌面配对）**：同一份二维码链接和配对令牌也能配对 PC 浏览器——把手机侧配对流扩展到桌面 Web GUI。从面板复制链接，在另一台电脑的浏览器打开（局域网 URL 或隧道 URL 均可）；接受往返后，完整 Web GUI 在那台设备上运行——工作区、会话、聊天、切模型——受围栏保护的同源流量走门控的 `/remote` 通道，而不是直接调用仅 loopback 的 host 路由。手机进 `/m/`，PC 进桌面 UI：一枚令牌、一套配对流、两种界面。未配对的 PC 只看到不渲染底层数据的完整阻断页，其中提供电脑配对步骤与「重新检测」操作。
 - **安全**：一个有效的一次性令牌（刷新会使旧链接失效；已接受的令牌不可复用；令牌会过期）。停止会撤销每一台已配对设备与当前令牌——已配对设备在下一次请求时被切断。配对是本插件对自己远程通道的访问控制：手机走 `/m/api`，非 loopback origin 打开的桌面浏览器走 `/remote`。未配对调用方在读取请求体之前就被 `/remote` 拒绝。loopback（127.0.0.1）继续直接使用 `/api`。默认的远程桌面路径不使用 `--trusted-host`：连接插件的 `/api` 围栏对公网和局域网主机保持关闭，已配对 PC 改走 `/remote`。`--trusted-host` 是 SDK 的另一种用法，会让该主机被信任访问 `/api` 本身——配对不门控 `/api`（任何插件都无法做到；围栏是 SDK 自己的接缝）。当 `/api` 无需配对即可到达时，下方姿态探测会报告该姿态。
-- **远程桌面通道**：`requirePairingForLan` 开启（默认）时，经局域网 URL 或隧道打开的桌面 Web GUI 透明地改走 `/remote`——同一套 UI，同一枚配对 cookie 门控。浏览器中 `/api`、`/sidebar`、`/git`、`/pet` 下的请求，以及已知的事件、终端与 SSH WebSocket，会在不转发远程 Origin 或配对 cookie 的前提下重新发给本机 Web Server；认证反代会为兄弟路由围栏提供自己生成的同源浏览器标记。SDK 的 loopback 专属特权方法（原生对话框、settings 与 credentials 面）对已配对远程桌面保持不可达，`/api/pair/*`、`/api/update/*`、`/api/plugin-manager/*`、`/api/dsh-desktop-launcher/*` 与 `/api/dsh-web-ui-settings/*` 控制端点保持仅 loopback。未配对的桌面浏览器看到持久的全页阻断界面而不是数据（阻断页按错误码 `unpaired` 触发，不是任意 403）。
+- **远程桌面通道**：`requirePairingForLan` 开启（默认）时，经局域网 URL 或隧道打开的桌面 Web GUI 透明地改走 `/remote`——同一套 UI，同一枚配对 cookie 门控。浏览器中 `/api`、`/sidebar`、`/git`、`/pet` 下的请求，以及已知的事件、终端与 SSH WebSocket，会在不转发远程 Origin 或配对 cookie 的前提下重新发给本机 Web Server；认证反代会为兄弟路由围栏提供自己生成的同源浏览器标记。SDK 的 loopback 专属特权方法（原生对话框、settings 与 credentials 面）对已配对远程桌面保持不可达，`/api/pair/*`、`/api/update/*`、`/api/plugin-manager/*`、`/api/dsh-desktop-launcher/*` 与 `/api/dsh-web-ui-settings/*` 控制端点保持仅 loopback。未配对的桌面浏览器看到持久的全页阻断界面而不是数据（阻断页按错误码 `unpaired` 触发，不是任意 403）。阻断页在任一门控调用成功后，或通道本身被拆除时退出——把 `requirePairingForLan` 关掉（或关闭插件）也会清掉通道短暂激活期间弹出的提示。
 - **姿态探测**：插件用伪造 Host 头（公网 base 与每个 LAN base）探测 SDK 的 `/api` 围栏。403 是默认姿态（围栏关闭，远程访问走配对）。任何非 403 结果——`--trusted-host`，或 `--host 0.0.0.0` 下 SDK 的局域网自动信任——都会以 CRITICAL 日志与配对面板红色横幅呈现，因此 SDK 的 `/api` 信任姿态是被看见的，而不是被假设的。探测失败会丢掉进行中的目标缓存，相同 origin 会在下次触发时重试。
 - **实时状态**：桌面面板经 SSE 流实时镜像配对状态（等待 → 已连接 → 已断开），并展示已授权设备名单。
 - **远程更新**：侧边栏加载后，底部的下载触发按钮（手机图标左侧）会静默探测 npm registry 上已安装的 `@linxin666/dsh-*` 全家桶版本；发现可自动更新的新版本时，按钮显示圆点并提供“发现新版本，检查更新”提示。点击按钮打开更新面板；未安装聚合包时，检查和更新覆盖 profile 中 registry 管理的全部 `@linxin666/*` 直接依赖，本地 link / file 开发依赖会被跳过。当存在较新版本时，面板展示版本对比并等待确认——点击「开始更新」后执行更新（在所属 dsh profile 内 `pnpm update --latest`；pnpm 缺失时依次回退 `corepack pnpm`、`npx --yes pnpm`，Windows 上经 `cmd.exe` 执行以解析 npm 安装的 `.cmd` shim；由仅 loopback 的 `/api/update/status` + `/api/update/run` 端点驱动）并请求重启 dsh web 以生效。pnpm 绿色退出后还会对照 registry 复核已装版本：绿色退出但版本纹丝不动（例如 pnpm 的 `minimumReleaseAge` 门禁静默跳过同日发布的新版本）会报告为「未更新成功」并附配置指引，而不是误报成功。锚点自身是本地 link 安装（开发模式）时，只报告 npm 状态而不更新。
@@ -173,6 +173,7 @@ pnpm run build
 - **撤销是逐请求的**：已配对手机请求已在 停止 落地时在途，完成该请求；下一个 403。
 - **已配对设备会话默认落盘**：设备会话（不含一次性二维码 token）写入 `$DSH_HOME/remote-web-ui-devices.json`（0600，临时文件加原子 rename）。已配对 cookie 在重启 `dsh web` 后仍然有效。刷新二维码仍会签发新 token；重启不会恢复当前二维码。点「停止」或单台「取消配对」会立即撤销并同步落盘。超过 `idleExpireMs`（默认 7 天，无心跳或门控请求）的会话会被删除，必须重新扫码。设备 id 即会话凭证（网关凭 cookie 中的设备 id 放行请求）。需要时可用 `devicesFile` 覆盖为其他绝对路径。变更 `cookieName` 会使旧设备失效（预期行为）。
 - **设备名单仅本机可见**：配对面板根据 User-Agent 显示精简设备名称（例如 `Windows · Chrome`）、在线/离线状态与最近活动时间，并可单台取消配对。界面不渲染作为会话凭据的设备 id 或原始 User-Agent。`/api/pair/status` 即使对已配对手机也不返回设备 id 名单。
+- **桌面门控策略是公开字段**：`/api/pair/status` 只公开布尔值 `requirePairingForLan`，让远程桌面在设置作用域不可用前选择正确传输通道。该字段不是凭据，也不暴露令牌、设备、计数或隧道 URL。
 - **Quick-tunnel hostname 每次运行变化**：`trycloudflare.com` URL 每次 `cloudflared` 启动随机，所以隧道重启时 `publicBaseUrl` 必须随之更新。named tunnel（固定 hostname）避免这种抖动，也是持久安装 PWA 地址所必需的。
 - **PWA 为在线优先**：只缓存静态壳和离线页。全部移动端远程控制能力仍要求运行中的 DSH host；离线时不提供会话、API 响应或命令。
 - **开发 HMR**：`dsh web --dev` 按路径轮询每个 roster bundle，因此重建本包（其自己的 `tsdown --watch`）会热重载 client bundle；无 harness 侧 watcher。

package/lib/client.js

@@ -1230,6 +1230,14 @@ window.__ModuleLoader__.load({
 		QRCodeSVG.displayName = "QRCodeSVG";
 		//#endregion
 		//#region src/client/pair-api.ts
+		/** Read the host-authoritative desktop pairing policy. */
+		async function readPairGatePolicy() {
+			const response = await fetch("/api/pair/status");
+			if (!response.ok) throw new Error(`remote-web-ui: status failed with ${String(response.status)}`);
+			const value = await response.json();
+			if (typeof value.requirePairingForLan !== "boolean") throw new Error("remote-web-ui: status omitted requirePairingForLan");
+			return { requirePairingForLan: value.requirePairingForLan };
+		}
 		/**
 		* Mint a fresh pairing token (one active token at a time — this invalidates
 		* any previous link).
@@ -2162,6 +2170,7 @@ window.__ModuleLoader__.load({
 				"data-wide": wide ? void 0 : "rail",
 				"data-update-available": updateAvailable ? "true" : void 0,
 				"aria-label": updateLabel,
+				"aria-expanded": open,
 				title: updateLabel,
 				onClick: openPanel,
 				children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconDownloadOutline16, { size: wide ? 16 : 18 })
@@ -2358,7 +2367,8 @@ window.__ModuleLoader__.load({
 				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(TooltipAnchor, {
 					wide,
 					label: t("entry.label"),
-					onClick: openPanel
+					onClick: openPanel,
+					expanded: open
 				})]
 			}), open && (0, react_dom.createPortal)(/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				className: remote_module_css_default.overlay,
@@ -2382,12 +2392,13 @@ window.__ModuleLoader__.load({
 			}), document.body)] });
 		}
 		/** The trigger: an icon-only control with a persistent accessible label. */
-		function TooltipAnchor({ wide, label, onClick }) {
+		function TooltipAnchor({ wide, label, onClick, expanded }) {
 			return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 				type: "button",
 				className: remote_module_css_default.trigger,
 				"data-wide": wide ? "wide" : "rail",
 				"aria-label": label,
+				"aria-expanded": expanded,
 				title: label,
 				onClick,
 				children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(PhoneIcon, { size: wide ? 16 : 18 })
@@ -3813,6 +3824,12 @@ window.__ModuleLoader__.load({
 			"/sidebar/ws/agent-terminals",
 			"/api/dsh-ssh/terminal"
 		]);
+		/** Decide whether a remote desktop channel is required from local or host policy. */
+		function remoteChannelRequired(hostname, snapshot, hostPairingPolicy) {
+			if (isLoopbackHostname(hostname)) return false;
+			if (snapshot.status === "ready") return (snapshot.value?.enabled ?? true) && (snapshot.value?.requirePairingForLan ?? true);
+			return hostPairingPolicy !== false;
+		}
 		/**
 		* Browser-safe loopback classification for the page origin (the SDK client
 		* exports its own; this copy keeps the module dependency-free).
@@ -3984,6 +4001,17 @@ window.__ModuleLoader__.load({
 				for (const restore of restoreSrc) restore();
 			};
 		}
+		/**
+		* Decide what the channel lifecycle must do next.
+		* @param active - whether the gated remote channel should be running now.
+		* @param installed - whether it currently is (disposer !== undefined).
+		* @returns the transition to apply.
+		*/
+		function channelTransition(active, installed) {
+			if (active && !installed) return "install";
+			if (!active && installed) return "retire";
+			return "none";
+		}
 		//#endregion
 		//#region src/client/FenceNotice.tsx
 		/**
@@ -4154,6 +4182,8 @@ window.__ModuleLoader__.load({
 			settingsScope.subscribe(syncRuntime);
 			syncRuntime();
 			let disposeChannel;
+			let hostPairingPolicy;
+			let unpairedWhilePolicyPending = false;
 			let fenceNotice;
 			const showFenceNotice = () => {
 				if (fenceNotice !== void 0) return;
@@ -4178,26 +4208,41 @@ window.__ModuleLoader__.load({
 				fenceNotice?.unmount();
 				fenceNotice = void 0;
 			};
-			const channelActive = () => {
-				if (isLoopbackHostname(window.location.hostname)) return false;
-				const snapshot = settingsScope.getSnapshot();
-				const value = snapshot.status === "ready" ? snapshot.value : void 0;
-				return (value?.enabled ?? true) && (value?.requirePairingForLan ?? true);
+			const handleUnpaired = () => {
+				if (settingsScope.getSnapshot().status !== "ready" && hostPairingPolicy === void 0) {
+					unpairedWhilePolicyPending = true;
+					return;
+				}
+				showFenceNotice();
 			};
+			const channelActive = () => remoteChannelRequired(window.location.hostname, settingsScope.getSnapshot(), hostPairingPolicy);
 			const syncChannel = () => {
-				if (channelActive() && disposeChannel === void 0) disposeChannel = ctx.effect(() => {
+				const transition = channelTransition(channelActive(), disposeChannel !== void 0);
+				if (transition === "install") disposeChannel = ctx.effect(() => {
 					return installRemoteChannel(window, {
-						onUnpaired: showFenceNotice,
+						onUnpaired: handleUnpaired,
 						onPaired: hideFenceNotice
 					});
 				}, "remote-web-ui: remote desktop channel");
-				else if (!channelActive() && disposeChannel !== void 0) {
+				else if (transition === "retire" && disposeChannel !== void 0) {
 					disposeChannel();
 					disposeChannel = void 0;
+					hideFenceNotice();
 				}
 			};
 			settingsScope.subscribe(syncChannel);
 			syncChannel();
+			if (!isLoopbackHostname(window.location.hostname) && settingsScope.getSnapshot().status !== "ready") readPairGatePolicy().then((policy) => {
+				hostPairingPolicy = policy.requirePairingForLan;
+				syncChannel();
+				if (hostPairingPolicy && unpairedWhilePolicyPending) showFenceNotice();
+				unpairedWhilePolicyPending = false;
+			}).catch(() => {
+				hostPairingPolicy = true;
+				syncChannel();
+				if (unpairedWhilePolicyPending) showFenceNotice();
+				unpairedWhilePolicyPending = false;
+			});
 			ctx.effect(() => {
 				const timer = window.setTimeout(() => {
 					if (sessionStorage.getItem("dsh-remote-pair-failed") === null) return;