dsh-remote-bridge 2.5.0 → 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.5.0-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">
@@ -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.0/dsh-remote-bridge-v2.5.0.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.5.0/dsh-remote-bridge-v2.5.0.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
 ```
@@ -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.0.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.5.1.tgz
 ```
 
 ## First connection
@@ -358,9 +358,22 @@ pnpm pack
 
 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.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.5.0`
+- 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.5.0-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">
@@ -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.0/dsh-remote-bridge-v2.5.0.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.5.0/dsh-remote-bridge-v2.5.0.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
 ```
@@ -112,7 +112,7 @@ npx @deepseek-ai/dsh web
 从 GitHub Release 下载离线安装包时，可直接安装 tarball：
 
 ```sh
-dsh plugin --profile web add ./dsh-remote-bridge-v2.5.0.tgz
+dsh plugin --profile web add ./dsh-remote-bridge-v2.5.1.tgz
 ```
 
 ## 第一次使用
@@ -346,9 +346,19 @@ v2.5.0 在 DSH **0.2.1-rc.2** 上完成真机验证：14/14 宿主服务全部
 权限档位目录返回内核真实三档。开发基线为上游 `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.5.0`
+- 当前版本：`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/docs/api/asyncapi.yaml

@@ -1,7 +1,7 @@
 asyncapi: 3.0.0
 info:
   title: DeepSeek Harness Mobile Events
-  version: 2.5.0
+  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.5.0
+  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

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

@@ -1621,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;
 }
@@ -1850,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;
@@ -1985,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;

package/lib/index.js

@@ -44,6 +44,261 @@ function asApiError(error) {
 	return new ApiError(500, "INTERNAL_ERROR", "An internal server error occurred.");
 }
 //#endregion
+//#region src/host/image-handoff.ts
+/**
+* 交接目录的**出厂默认**。
+*
+* 设置面板里「当前默认」那一栏展示的就是这个字面量，且是只读的 —— 它是这份代码的
+* 契约（历史交接消息、识图工具、手机端都按它写过），不是一个可以随风改的偏好项。
+* 用户可以改的是设置的**当前值**（存在数据库里），默认值本身不跟着走。
+*/
+const DEFAULT_HANDOFF_SUBDIR = ".dsh-images";
+/** settings 表里的键名。 */
+const IMAGE_SUBDIR_SETTING = "image_handoff_subdir";
+/**
+* 只读图片路由。刻意放在 `/plugin/` 下而不是版本化 REST 前缀里：
+* 它不参与 REST 契约、不需要设备 token，将来 REST 升版时这条也不该跟着动。
+*/
+const IMAGE_ROUTE = "/plugin/dsh-remote-bridge/raw";
+/** 目录名上限：它要拼进路径，太长的名字只是拿来坑自己的。 */
+const MAX_SUBDIR_CHARS = 64;
+/**
+* 把用户填的目录名收成一个安全值。
+*
+* 只收**单段**目录名：`/`、`\`、NUL 一律拒绝（否则它就不是「目录名」而是「路径」，
+* 会把落盘位置带出工作目录）；`.` 与 `..` 拒绝（前者是当前目录、后者是往上爬）；
+* 允许点开头 —— 默认值 `.dsh-images` 自己就是点目录。
+*/
+function normalizeHandoffSubdir(value) {
+	if (typeof value !== "string") throw new ApiError(400, "IMAGE_SUBDIR_INVALID", "The image directory name must be a string.");
+	const trimmed = value.trim();
+	if (trimmed === "" || trimmed.length > MAX_SUBDIR_CHARS) throw new ApiError(400, "IMAGE_SUBDIR_INVALID", `The image directory name must be 1-${MAX_SUBDIR_CHARS} characters.`);
+	if (trimmed === "." || trimmed === "..") throw new ApiError(400, "IMAGE_SUBDIR_INVALID", "The image directory name cannot be \".\" or \"..\".");
+	if (!/^[A-Za-z0-9._-]+$/.test(trimmed)) throw new ApiError(400, "IMAGE_SUBDIR_INVALID", "The image directory name may only contain letters, digits, dots, underscores, and hyphens.");
+	return trimmed;
+}
+/**
+* 读出当前生效的目录名。
+*
+* 数据库里那条坏掉（手改过 / 旧版本写过）就退回默认并**顺手修掉**：一个坏值不该让
+* 「发图」这个动作从此失败，而每次读都只回退不修正会把坏值永远留着。
+*/
+function readHandoffSubdir(database) {
+	const stored = database.getSetting(IMAGE_SUBDIR_SETTING);
+	if (stored === void 0) return DEFAULT_HANDOFF_SUBDIR;
+	try {
+		return normalizeHandoffSubdir(stored);
+	} catch {
+		database.setSetting(IMAGE_SUBDIR_SETTING, DEFAULT_HANDOFF_SUBDIR);
+		return DEFAULT_HANDOFF_SUBDIR;
+	}
+}
+/** 校验并保存，返回落库后的值。 */
+function saveHandoffSubdir(database, value) {
+	const normalized = normalizeHandoffSubdir(value);
+	database.setSetting(IMAGE_SUBDIR_SETTING, normalized);
+	return normalized;
+}
+/** 设置面板要的那三个值。 */
+function imageHandoffView(database, fallbackDir) {
+	return {
+		subdir: readHandoffSubdir(database),
+		defaultSubdir: DEFAULT_HANDOFF_SUBDIR,
+		fallbackDir
+	};
+}
+/** 交接文件名的白名单：`<sha256>.<图片扩展名>`，路径穿越在名字这一层就死掉。 */
+const HANDOFF_FILE_NAME = /^[0-9a-f]{64}\.(png|jpe?g|webp|gif|heic|heif|bmp|avif)$/i;
+/** 扩展名 → 该扩展名必须用内容自证的身份。 */
+const HANDOFF_MEDIA_TYPES = {
+	png: "image/png",
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	webp: "image/webp",
+	gif: "image/gif",
+	heic: "image/heic",
+	heif: "image/heif",
+	bmp: "image/bmp",
+	avif: "image/avif"
+};
+/** 浏览器只会显示预览，超过这个就别端过去了。 */
+const MAX_BYTES = 33554432;
+/** 病态长的入参在碰文件系统之前就退掉。 */
+const MAX_NAME_CHARS = 4096;
+/** 按扩展名取声明的媒体类型；不支持的扩展名返回 undefined。 */
+function declaredMediaType(name) {
+	const cut = name.lastIndexOf(".");
+	if (cut === -1) return void 0;
+	return HANDOFF_MEDIA_TYPES[name.slice(cut + 1).toLowerCase()];
+}
+/**
+* 「扩展名声明」与「字节自证」是否属于同一图片家族。
+*
+* 为什么需要这一层而不是直接 `declared === sniffed`：**HEIC 与 HEIF 在字节层面无法区分**。
+* 两者都是 ISO-BMFF，靠 `ftyp` 后面的 brand 认家族，而 `heic`/`heif`/`mif1`/`hevc`
+* 都在同一套 `hei*` / `hev*` / `mif*` 前缀里 —— 嗅探器只能诚实地报出「这是 HEI 家族」，
+* 也就是 `image/heic`；它**不该**为了迁就某条扩展名而返回一个自己无法自证的值。
+*
+* 于是把「等价」这件事放在一致性校验这一侧：
+* - 写盘表（`dsh-0.2-bridge.ts`）按内核给的 mediaType 原样产 `<hash>.heif`；
+* - 读取表把 `heif` 声明成 `image/heif`；
+* - 嗅探器对同一份字节返回 `image/heic`；
+* - 两者同族 → 放行。
+*
+* 这不是把闸门拆了：**跨家族的错配仍然全部 415**（png 字节配 `.jpg` 名、
+* `image/png` 配 `.avif` 名、heic 字节配 `.avif` 名）。只放开这一对无法在字节层
+* 区分的「同一家族两个名字」。
+*/
+function sameImageFamily(declared, sniffed) {
+	if (declared === sniffed) return true;
+	const heifFamily = /* @__PURE__ */ new Set(["image/heic", "image/heif"]);
+	return heifFamily.has(declared) && heifFamily.has(sniffed);
+}
+/**
+* 从文件头认出真实格式。扩展名只是**声明**，这里才是内容自证。
+* @param head - 文件前至少 12 个字节。
+*/
+function sniffMediaType(head) {
+	const ascii = (offset, text) => {
+		if (head.length < offset + text.length) return false;
+		for (let index = 0; index < text.length; index += 1) if (head[offset + index] !== text.charCodeAt(index)) return false;
+		return true;
+	};
+	const bytes = (...expected) => {
+		if (head.length < expected.length) return false;
+		return expected.every((byte, index) => head[index] === byte);
+	};
+	if (bytes(137, 80, 78, 71, 13, 10, 26, 10)) return "image/png";
+	if (bytes(255, 216, 255)) return "image/jpeg";
+	if (ascii(0, "GIF87a") || ascii(0, "GIF89a")) return "image/gif";
+	if (ascii(0, "RIFF") && ascii(8, "WEBP")) return "image/webp";
+	if (bytes(66, 77)) return "image/bmp";
+	if (ascii(4, "ftyp")) {
+		const brand = head.length >= 12 ? String.fromCharCode(...head.subarray(8, 12)) : "";
+		if (brand.startsWith("avi")) return "image/avif";
+		if (brand.startsWith("hei") || brand.startsWith("hev") || brand.startsWith("mif")) return "image/heic";
+	}
+}
+/** 请求的 `Host` 是否指向回环（DNS 重绑定防护）。 */ function loopbackHost(req) {
+	const host = req.headers.host;
+	if (typeof host !== "string" || host === "") return false;
+	if (host.startsWith("[")) return host.startsWith("[::1]");
+	const name = host.split(":")[0];
+	return name === "127.0.0.1" || name === "localhost";
+}
+/**
+* 请求是否来自某个插件自己服务的页面。
+*
+* 沙箱化的画布跑在不透明 origin 里，它自己的请求不带可用的 origin，但会带来源页 URL
+* —— 这是 HTML 产物也能显示工作区图片的原因。
+*/
+function pluginPageReferer(req) {
+	const referer = req.headers.referer;
+	if (typeof referer !== "string" || referer === "") return false;
+	try {
+		const url = new URL(referer);
+		if (url.host !== req.headers.host) return false;
+		return url.pathname.startsWith("/plugin/");
+	} catch {
+		return false;
+	}
+}
+/**
+* 请求是否可以被回答。
+*
+* 浏览器一定发 `Sec-Fetch-Site`，跨站一律拒绝；没有这个头的调用方不是浏览器页面
+* （curl、测试），此时回环可达性本身就是访问模型 —— 与本地 GUI 其余部分假定的信任一致。
+*/
+function sameOrigin(req) {
+	if (!loopbackHost(req)) return false;
+	if (pluginPageReferer(req)) return true;
+	const site = req.headers["sec-fetch-site"];
+	if (typeof site === "string") return site === "same-origin" || site === "none";
+	const origin = req.headers.origin;
+	if (typeof origin !== "string" || origin === "") return true;
+	try {
+		return new URL(origin).host === req.headers.host;
+	} catch {
+		return false;
+	}
+}
+/** 用一段纯文本说出拒绝理由：不回显调用方给的路径，也不做任何目录列举。 */
+function refuse(res, status, reason) {
+	const body = `${reason}\n`;
+	res.writeHead(status, {
+		"content-type": "text/plain; charset=utf-8",
+		"content-length": String(Buffer.byteLength(body)),
+		"cache-control": "no-store",
+		"x-content-type-options": "nosniff"
+	});
+	res.end(body);
+}
+/**
+* 这条路由的处理器工厂。
+* @param options - 取图实现。
+* @returns 一个 `(req, res) => Promise<void>`，可直接交给 `webServer.register`。
+*/
+function createImageRouteHandler(options) {
+	return async function serveImage(req, res) {
+		if (req.method !== "GET" && req.method !== "HEAD") {
+			refuse(res, 405, "method not allowed");
+			return;
+		}
+		if (!sameOrigin(req)) {
+			refuse(res, 403, "cross-site request refused");
+			return;
+		}
+		const url = new URL(req.url ?? "/", "http://127.0.0.1");
+		const sessionId = (url.searchParams.get("sessionId") ?? "").trim();
+		const rawName = url.searchParams.get("name") ?? "";
+		if (sessionId === "" || rawName === "" || rawName.length > MAX_NAME_CHARS) {
+			refuse(res, 400, "sessionId and name are required");
+			return;
+		}
+		const name = rawName.split(/[/\\]/).pop() ?? rawName;
+		if (HANDOFF_FILE_NAME.exec(name) === null) {
+			refuse(res, 404, "no such handoff image");
+			return;
+		}
+		const declared = declaredMediaType(name);
+		let image;
+		try {
+			image = await options.read(sessionId, name);
+		} catch {
+			refuse(res, 404, "no such handoff image");
+			return;
+		}
+		if (image.bytes.byteLength === 0) {
+			refuse(res, 404, "empty file");
+			return;
+		}
+		if (image.bytes.byteLength > MAX_BYTES) {
+			refuse(res, 413, "image is too large to display");
+			return;
+		}
+		const sniffed = sniffMediaType(image.bytes.subarray(0, 12));
+		if (sniffed === void 0) {
+			refuse(res, 415, "content is not a supported image");
+			return;
+		}
+		if (declared !== void 0 && !sameImageFamily(declared, sniffed)) {
+			refuse(res, 415, "content does not match the file extension");
+			return;
+		}
+		res.writeHead(200, {
+			"content-type": sniffed,
+			"content-length": String(image.bytes.byteLength),
+			"cache-control": "private, max-age=300",
+			"x-content-type-options": "nosniff"
+		});
+		if (req.method === "HEAD") {
+			res.end();
+			return;
+		}
+		res.end(Buffer.from(image.bytes.buffer, image.bytes.byteOffset, image.bytes.byteLength));
+	};
+}
+//#endregion
 //#region src/host/rate-limit.ts
 var FixedWindowLimiter = class {
 	limit;
@@ -74,18 +329,141 @@ var FixedWindowLimiter = class {
 };
 //#endregion
 //#region src/host/auth.ts
+/**
+* 判定「这是不是一次真正的本机管理请求」。
+*
+* ## 为什么不能只看 `remoteAddress`
+*
+* 修复前 `requireAdmin` 的全部判据是「TCP 来源是回环 + Origin 是回环」。这条判据在
+* **任何把外部请求转到本机回环的拓扑下都恒真**：插件自带的 cloudflared Quick Tunnel
+* 用 `--url http://127.0.0.1:PORT` 转发（`cloudflared.ts`），公网请求进到 bridge 时
+* `req.socket.remoteAddress` 就是 `127.0.0.1`。于是 `https://xxx.trycloudflare.com/manage/roots`
+* 一个凭据都不带也能读到全部授权根的绝对路径（v2.5.0 实测 200/201）。
+* 同一类拓扑还包括 ngrok、frp、Caddy/Nginx `proxy_pass 127.0.0.1`、SSH 端口转发、
+* Tailscale Serve。见 `docs/project/PITFALLS.md` §隧道让回环判据失效。
+*
+* ## 四层判据（层层收紧，`undefined` = 放行）
+*
+* 0. **隧道运行中一律拒绝**（`tunnelActive === true`）—— 100% 可靠的一条：隧道是我们
+*    自己拉的进程，状态握在自己手里，不依赖任何可伪造的请求头。返回
+*    `TUNNEL_MODE_ADMIN_DISABLED`。
+* 1. **出现任何转发头即视为经代理** —— `Forwarded` / `X-Forwarded-For` /
+*    `X-Forwarded-Host` / `X-Forwarded-Proto` / `X-Real-IP`。真正的本机浏览器与
+*    `curl 127.0.0.1` 都不会发这些头；发了就说明前面有一层我们不认识的代理。
+*    返回 `ADMIN_PROXY_FORWARDED`。
+* 2. **`Host` 必须是回环**（复用 `image-handoff.ts` 的 `loopbackHost`，它接受
+*    `127.0.0.1` / `localhost` / `[::1]`）。缺失 `Host` 也拒。这一条挡两类攻击：
+*    隧道/反代转发进来的公网域名（`Host: xxx.trycloudflare.com`），以及 **DNS 重绑定**
+*    （攻击者域名解析到 127.0.0.1，浏览器照样发回环 `Origin`，只有 `Host` 露馅）。
+*    返回 `ADMIN_HOST_NOT_LOOPBACK`。
+* 3. **socket 来源必须是回环，`Origin` 若存在必须是回环**。`Origin` 缺失**仍然放行** ——
+*    这是刻意的取舍，理由见下。
+*
+* ## 为什么 `Origin` 缺失还放行（刻意的取舍，别「顺手修掉」）
+*
+* 翻成「必须带回环 Origin」能多挡一点，但会**同时打死 `curl` 与脚本调试**：它们在
+* 本机跑、天然不带 `Origin`，而本机进程本来就有权读这些文件（它们能直接 `cat`）。
+* 真正的防线不是「请求必须像浏览器」，而是**拓扑与头**：判据 0 管住了我们自己拉的隧道，
+* 判据 1 管住了任何代理，判据 2 管住了公网域名与 DNS 重绑定。隧道场景里公网请求即使
+* 不带 `Origin` 也会先撞上判据 0/1/2 —— 这正是 §3.1 那条攻击链的断点。
+*
+* 换句话说：**允许缺 `Origin` 不再是「可信」，而是「不再有决定权」**。修复前它是有
+* 决定权的（`isLoopbackOrigin(undefined) === true` 直接就给了管理员身份）。
+*
+* @param req - 待判定的请求。
+* @param options.tunnelActive - 是否有我们自管的隧道在运行；缺省视为没有。
+* @param options.allowTunnelMode - 仅用于「隧道状态」这类**只读、无副作用**的端点：
+*   让它们豁免判据 0（否则隧道一开，面板连「隧道开着」这件事都读不到），
+*   判据 1/2/3 仍然全部生效。**其他任何 `/manage` 端点都不许传这个选项。**
+*/
+function adminRefusal(req, options = {}) {
+	if (options.tunnelActive === true && options.allowTunnelMode !== true) return {
+		code: "TUNNEL_MODE_ADMIN_DISABLED",
+		message: "Management endpoints are disabled while the Cloudflare tunnel is running. Use the local WebUI, or stop the tunnel first."
+	};
+	for (const name of FORWARDING_HEADERS) if (headerPresent(req, name)) return {
+		code: "ADMIN_PROXY_FORWARDED",
+		message: "Management endpoints are available only from the local machine, not through a proxy or tunnel."
+	};
+	if (!loopbackHost(req)) return {
+		code: "ADMIN_HOST_NOT_LOOPBACK",
+		message: "Management endpoints are available only under a loopback host name (127.0.0.1, localhost or [::1])."
+	};
+	if (!isLoopbackAddress(requestAddress(req)) || !isLoopbackOrigin(req.headers.origin)) return {
+		code: "ADMIN_LOOPBACK_REQUIRED",
+		message: "This operation is available only from the local machine."
+	};
+}
+/**
+* 「这个请求不是本机直连」的**全部**证据头。
+*
+* 分两组，理由不同：
+*
+* 1. **转发头**（`Forwarded` / `X-Forwarded-*` / `X-Real-IP`）：本机浏览器与
+*    `curl 127.0.0.1` 都不会发。**存在即拒**，不看值 —— `X-Forwarded-For: 127.0.0.1`
+*    正是最典型的洗白写法（攻击者从隧道进来，塞一个声称自己是本机的头）。
+* 2. **Cloudflare 边缘头**（`Cf-Connecting-IP` / `Cf-Ray` / `Cf-IpCountry` / `Cf-Visitor`）：
+*    这一组是**真实隧道场景的兜底**。cloudflared 的 `httpHostHeader` 默认为空，会把
+*    `Host` 改写成源站地址（`127.0.0.1:PORT`），于是判据 2 在真实隧道下挡不住；
+*    而 Cloudflare 边缘一定会注入这组头（且请求方无法伪造成「我没有经过边缘」）。
+*    实测（`.local-backup/security-audit/verify-fix-tunnel-admin.mjs`）：
+*    只把 Host 改成回环地址就能拿到 200，加上这组头才被挡住。
+*
+* 这两组都不参与「判据 0 的豁免」—— 隧道状态端点仍要求它们为空。
+*/
+const FORWARDING_HEADERS = [
+	"forwarded",
+	"x-forwarded-for",
+	"x-forwarded-host",
+	"x-forwarded-proto",
+	"x-real-ip",
+	"cf-connecting-ip",
+	"cf-ray",
+	"cf-ipcountry",
+	"cf-visitor"
+];
+/** 头存在且非空才算「出现」：空串是某些代理库的产物，不构成声明。 */
+function headerPresent(req, name) {
+	const raw = req.headers[name];
+	if (raw === void 0) return false;
+	if (Array.isArray(raw)) return raw.some((value) => value.trim() !== "");
+	return raw.trim() !== "";
+}
 var AuthService = class {
 	database;
+	options;
 	authFailures = new FixedWindowLimiter(20, 3e5);
 	pairingAttempts = new FixedWindowLimiter(10, 6e5);
 	requests = new FixedWindowLimiter(120, 6e4);
-	constructor(database) {
+	constructor(database, options = {}) {
 		this.database = database;
+		this.options = options;
+	}
+	/**
+	* 隧道是否在跑。探针抛错时**按「在跑」处理**（fail closed）：探针读的是我们自己
+	* 对象上的 getter，它抛错意味着状态不可知；状态不可知时放行管理面正是这次修复要
+	* 消灭的那类决定。
+	*/
+	tunnelRunning() {
+		const probe = this.options.tunnelActive;
+		if (probe === void 0) return false;
+		try {
+			return probe() === true;
+		} catch {
+			return true;
+		}
 	}
 	principal(req, options = {}) {
 		const remote = requestAddress(req);
 		this.requests.consume(remote);
-		if (options.allowAdmin === true && req.headers["x-dsh-workspace-admin"] === "1" && isLoopbackAddress(remote) && isLoopbackOrigin(req.headers.origin)) return ADMIN_PRINCIPAL;
+		if (options.allowAdmin === true && req.headers["x-dsh-workspace-admin"] === "1") {
+			const refusal = adminRefusal(req, { tunnelActive: this.tunnelRunning() });
+			if (refusal !== void 0) {
+				this.authFailures.consume(remote);
+				throw new ApiError(403, refusal.code, refusal.message);
+			}
+			return ADMIN_PRINCIPAL;
+		}
 		const authorization = req.headers.authorization;
 		if (authorization === void 0 || !authorization.startsWith("Bearer ")) {
 			this.authFailures.consume(remote);
@@ -105,8 +483,18 @@ var AuthService = class {
 			rootIds: new Set(device.rootIds)
 		};
 	}
-	requireAdmin(req) {
-		if (!isLoopbackAddress(requestAddress(req)) || !isLoopbackOrigin(req.headers.origin)) throw new ApiError(403, "ADMIN_LOOPBACK_REQUIRED", "This operation is available only from the local machine.");
+	/**
+	* `/manage/**` 的守门人。
+	*
+	* @param options.allowTunnelMode - 只有「隧道状态下读/停隧道」这几个端点会传 true。
+	*   见 `adminRefusal` 的同名说明与 `router.ts` 的 `TUNNEL_MODE_EXEMPT_PATHS`。
+	*/
+	requireAdmin(req, options = {}) {
+		const refusal = adminRefusal(req, {
+			tunnelActive: this.tunnelRunning(),
+			...options.allowTunnelMode === true ? { allowTunnelMode: true } : {}
+		});
+		if (refusal !== void 0) throw new ApiError(403, refusal.code, refusal.message);
 		return ADMIN_PRINCIPAL;
 	}
 	requireScope(principal, scope) {
@@ -123,6 +511,13 @@ function isLoopbackAddress(address) {
 	const normalized = address.toLowerCase().split("%")[0];
 	return normalized === "127.0.0.1" || normalized === "::1" || normalized === "::ffff:127.0.0.1";
 }
+/**
+* `Origin` 是否是回环。
+*
+* `undefined` 返回 `true` 是**刻意保留**的（理由见 `adminRefusal` 的注释）：它不再
+* 单独构成「可信」，判据 0/1/2 已经承担了决定性判断。改这一行会让 `curl` 调试
+* 无处可去，而本机进程本来就能直接读这些文件。
+*/
 function isLoopbackOrigin(origin) {
 	if (origin === void 0) return true;
 	try {
@@ -381,11 +776,24 @@ var CloudflaredTunnelManager = class {
 		};
 		this.emit();
 	}
+	/**
+	* 是否有隧道在运行 —— 管理面鉴权的**判据 0**。
+	*
+	* 判据取自**进程持有状态**，不是请求头，所以它对「隧道把外部流量转进 127.0.0.1」
+	* 这条绕过路径 100% 可靠：不管转发进来的请求长什么样，只要隧道开着，管理面就关门。
+	* 见 `auth.ts` 的 `adminRefusal` 与 `PITFALLS.md` §隧道让回环判据失效。
+	*
+	* `running` 与 `publicState.running` 是同一个表达式（同一份真相），这里单独暴露是为了
+	* 让鉴权层不必构造一个含 url 的视图对象 —— 少一处把地址带进意外地方的机会。
+	*/
+	get tunnelActive() {
+		return this.process !== null && !this.process.killed;
+	}
 	get publicState() {
 		return {
 			channel: this.channel,
 			url: this.url,
-			running: this.process !== null && !this.process.killed,
+			running: this.tunnelActive,
 			...this.errorText === void 0 ? {} : { error: this.errorText }
 		};
 	}
@@ -471,239 +879,6 @@ var CloudflaredTunnelManager = class {
 	}
 };
 //#endregion
-//#region src/host/image-handoff.ts
-/**
-* 交接目录的**出厂默认**。
-*
-* 设置面板里「当前默认」那一栏展示的就是这个字面量，且是只读的 —— 它是这份代码的
-* 契约（历史交接消息、识图工具、手机端都按它写过），不是一个可以随风改的偏好项。
-* 用户可以改的是设置的**当前值**（存在数据库里），默认值本身不跟着走。
-*/
-const DEFAULT_HANDOFF_SUBDIR = ".dsh-images";
-/** settings 表里的键名。 */
-const IMAGE_SUBDIR_SETTING = "image_handoff_subdir";
-/**
-* 只读图片路由。刻意放在 `/plugin/` 下而不是版本化 REST 前缀里：
-* 它不参与 REST 契约、不需要设备 token，将来 REST 升版时这条也不该跟着动。
-*/
-const IMAGE_ROUTE = "/plugin/dsh-remote-bridge/raw";
-/** 目录名上限：它要拼进路径，太长的名字只是拿来坑自己的。 */
-const MAX_SUBDIR_CHARS = 64;
-/**
-* 把用户填的目录名收成一个安全值。
-*
-* 只收**单段**目录名：`/`、`\`、NUL 一律拒绝（否则它就不是「目录名」而是「路径」，
-* 会把落盘位置带出工作目录）；`.` 与 `..` 拒绝（前者是当前目录、后者是往上爬）；
-* 允许点开头 —— 默认值 `.dsh-images` 自己就是点目录。
-*/
-function normalizeHandoffSubdir(value) {
-	if (typeof value !== "string") throw new ApiError(400, "IMAGE_SUBDIR_INVALID", "The image directory name must be a string.");
-	const trimmed = value.trim();
-	if (trimmed === "" || trimmed.length > MAX_SUBDIR_CHARS) throw new ApiError(400, "IMAGE_SUBDIR_INVALID", `The image directory name must be 1-${MAX_SUBDIR_CHARS} characters.`);
-	if (trimmed === "." || trimmed === "..") throw new ApiError(400, "IMAGE_SUBDIR_INVALID", "The image directory name cannot be \".\" or \"..\".");
-	if (!/^[A-Za-z0-9._-]+$/.test(trimmed)) throw new ApiError(400, "IMAGE_SUBDIR_INVALID", "The image directory name may only contain letters, digits, dots, underscores, and hyphens.");
-	return trimmed;
-}
-/**
-* 读出当前生效的目录名。
-*
-* 数据库里那条坏掉（手改过 / 旧版本写过）就退回默认并**顺手修掉**：一个坏值不该让
-* 「发图」这个动作从此失败，而每次读都只回退不修正会把坏值永远留着。
-*/
-function readHandoffSubdir(database) {
-	const stored = database.getSetting(IMAGE_SUBDIR_SETTING);
-	if (stored === void 0) return DEFAULT_HANDOFF_SUBDIR;
-	try {
-		return normalizeHandoffSubdir(stored);
-	} catch {
-		database.setSetting(IMAGE_SUBDIR_SETTING, DEFAULT_HANDOFF_SUBDIR);
-		return DEFAULT_HANDOFF_SUBDIR;
-	}
-}
-/** 校验并保存，返回落库后的值。 */
-function saveHandoffSubdir(database, value) {
-	const normalized = normalizeHandoffSubdir(value);
-	database.setSetting(IMAGE_SUBDIR_SETTING, normalized);
-	return normalized;
-}
-/** 设置面板要的那三个值。 */
-function imageHandoffView(database, fallbackDir) {
-	return {
-		subdir: readHandoffSubdir(database),
-		defaultSubdir: DEFAULT_HANDOFF_SUBDIR,
-		fallbackDir
-	};
-}
-/** 交接文件名的白名单：`<sha256>.<图片扩展名>`，路径穿越在名字这一层就死掉。 */
-const HANDOFF_FILE_NAME = /^[0-9a-f]{64}\.(png|jpe?g|webp|gif|heic|heif|bmp|avif)$/i;
-/** 扩展名 → 该扩展名必须用内容自证的身份。 */
-const HANDOFF_MEDIA_TYPES = {
-	png: "image/png",
-	jpg: "image/jpeg",
-	jpeg: "image/jpeg",
-	webp: "image/webp",
-	gif: "image/gif",
-	heic: "image/heic",
-	heif: "image/heif",
-	bmp: "image/bmp",
-	avif: "image/avif"
-};
-/** 浏览器只会显示预览，超过这个就别端过去了。 */
-const MAX_BYTES = 33554432;
-/** 病态长的入参在碰文件系统之前就退掉。 */
-const MAX_NAME_CHARS = 4096;
-/** 按扩展名取声明的媒体类型；不支持的扩展名返回 undefined。 */
-function declaredMediaType(name) {
-	const cut = name.lastIndexOf(".");
-	if (cut === -1) return void 0;
-	return HANDOFF_MEDIA_TYPES[name.slice(cut + 1).toLowerCase()];
-}
-/**
-* 从文件头认出真实格式。扩展名只是**声明**，这里才是内容自证。
-* @param head - 文件前至少 12 个字节。
-*/
-function sniffMediaType(head) {
-	const ascii = (offset, text) => {
-		if (head.length < offset + text.length) return false;
-		for (let index = 0; index < text.length; index += 1) if (head[offset + index] !== text.charCodeAt(index)) return false;
-		return true;
-	};
-	const bytes = (...expected) => {
-		if (head.length < expected.length) return false;
-		return expected.every((byte, index) => head[index] === byte);
-	};
-	if (bytes(137, 80, 78, 71, 13, 10, 26, 10)) return "image/png";
-	if (bytes(255, 216, 255)) return "image/jpeg";
-	if (ascii(0, "GIF87a") || ascii(0, "GIF89a")) return "image/gif";
-	if (ascii(0, "RIFF") && ascii(8, "WEBP")) return "image/webp";
-	if (bytes(66, 77)) return "image/bmp";
-	if (ascii(4, "ftyp")) {
-		const brand = head.length >= 12 ? String.fromCharCode(...head.subarray(8, 12)) : "";
-		if (brand.startsWith("avi")) return "image/avif";
-		if (brand.startsWith("hei") || brand.startsWith("hev") || brand.startsWith("mif")) return "image/heic";
-	}
-}
-/** 请求的 `Host` 是否指向回环（DNS 重绑定防护）。 */
-function loopbackHost(req) {
-	const host = req.headers.host;
-	if (typeof host !== "string" || host === "") return false;
-	if (host.startsWith("[")) return host.startsWith("[::1]");
-	const name = host.split(":")[0];
-	return name === "127.0.0.1" || name === "localhost";
-}
-/**
-* 请求是否来自某个插件自己服务的页面。
-*
-* 沙箱化的画布跑在不透明 origin 里，它自己的请求不带可用的 origin，但会带来源页 URL
-* —— 这是 HTML 产物也能显示工作区图片的原因。
-*/
-function pluginPageReferer(req) {
-	const referer = req.headers.referer;
-	if (typeof referer !== "string" || referer === "") return false;
-	try {
-		const url = new URL(referer);
-		if (url.host !== req.headers.host) return false;
-		return url.pathname.startsWith("/plugin/");
-	} catch {
-		return false;
-	}
-}
-/**
-* 请求是否可以被回答。
-*
-* 浏览器一定发 `Sec-Fetch-Site`，跨站一律拒绝；没有这个头的调用方不是浏览器页面
-* （curl、测试），此时回环可达性本身就是访问模型 —— 与本地 GUI 其余部分假定的信任一致。
-*/
-function sameOrigin(req) {
-	if (!loopbackHost(req)) return false;
-	if (pluginPageReferer(req)) return true;
-	const site = req.headers["sec-fetch-site"];
-	if (typeof site === "string") return site === "same-origin" || site === "none";
-	const origin = req.headers.origin;
-	if (typeof origin !== "string" || origin === "") return true;
-	try {
-		return new URL(origin).host === req.headers.host;
-	} catch {
-		return false;
-	}
-}
-/** 用一段纯文本说出拒绝理由：不回显调用方给的路径，也不做任何目录列举。 */
-function refuse(res, status, reason) {
-	const body = `${reason}\n`;
-	res.writeHead(status, {
-		"content-type": "text/plain; charset=utf-8",
-		"content-length": String(Buffer.byteLength(body)),
-		"cache-control": "no-store",
-		"x-content-type-options": "nosniff"
-	});
-	res.end(body);
-}
-/**
-* 这条路由的处理器工厂。
-* @param options - 取图实现。
-* @returns 一个 `(req, res) => Promise<void>`，可直接交给 `webServer.register`。
-*/
-function createImageRouteHandler(options) {
-	return async function serveImage(req, res) {
-		if (req.method !== "GET" && req.method !== "HEAD") {
-			refuse(res, 405, "method not allowed");
-			return;
-		}
-		if (!sameOrigin(req)) {
-			refuse(res, 403, "cross-site request refused");
-			return;
-		}
-		const url = new URL(req.url ?? "/", "http://127.0.0.1");
-		const sessionId = (url.searchParams.get("sessionId") ?? "").trim();
-		const rawName = url.searchParams.get("name") ?? "";
-		if (sessionId === "" || rawName === "" || rawName.length > MAX_NAME_CHARS) {
-			refuse(res, 400, "sessionId and name are required");
-			return;
-		}
-		const name = rawName.split(/[/\\]/).pop() ?? rawName;
-		if (HANDOFF_FILE_NAME.exec(name) === null) {
-			refuse(res, 404, "no such handoff image");
-			return;
-		}
-		const declared = declaredMediaType(name);
-		let image;
-		try {
-			image = await options.read(sessionId, name);
-		} catch {
-			refuse(res, 404, "no such handoff image");
-			return;
-		}
-		if (image.bytes.byteLength === 0) {
-			refuse(res, 404, "empty file");
-			return;
-		}
-		if (image.bytes.byteLength > MAX_BYTES) {
-			refuse(res, 413, "image is too large to display");
-			return;
-		}
-		const sniffed = sniffMediaType(image.bytes.subarray(0, 12));
-		if (sniffed === void 0) {
-			refuse(res, 415, "content is not a supported image");
-			return;
-		}
-		if (declared !== void 0 && sniffed !== declared) {
-			refuse(res, 415, "content does not match the file extension");
-			return;
-		}
-		res.writeHead(200, {
-			"content-type": sniffed,
-			"content-length": String(image.bytes.byteLength),
-			"cache-control": "private, max-age=300",
-			"x-content-type-options": "nosniff"
-		});
-		if (req.method === "HEAD") {
-			res.end();
-			return;
-		}
-		res.end(Buffer.from(image.bytes.buffer, image.bytes.byteOffset, image.bytes.byteLength));
-	};
-}
-//#endregion
 //#region src/host/path-policy.ts
 const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
 function validateRelativePath(value) {
@@ -2092,7 +2267,7 @@ function createDsh02ApiProxy(host, options = {}) {
 }
 //#endregion
 //#region src/shared/version.ts
-const PLUGIN_VERSION = "2.5.0";
+const PLUGIN_VERSION = "2.5.1";
 //#endregion
 //#region src/host/capabilities.ts
 /**
@@ -5147,6 +5322,23 @@ function matchJobRoute(pathname) {
 	};
 	return null;
 }
+/**
+* 隧道运行期间**仍然可达**的管理端点（豁免判据 0）。
+*
+* 为什么存在这个集合：判据 0（隧道开着 → 管理面整体关门）会让「隧道状态」这个信号
+* 本体也 403，于是面板没法告诉用户「隧道开着所以管理面停用」—— 只剩一个没法解读的
+* 失败。这两个端点进来的目的就是解掉这个矛盾。
+*
+* 为什么是安全的：它们**只读、无副作用**（不写库、不发令牌、不改监听），返回的
+* `running`/`channel`/`error`/阶段进度都不构成攻击面。**唯一敏感的是 `url`** ——
+* Quick Tunnel 地址本身是一次对外入口。
+*
+* 豁免**只针对判据 0**。判据 1/2/3（转发头+Cloudflare 边缘头 / Host / Origin）对它们
+* 照旧全部生效，所以真实隧道来源的请求连这两个端点也是 403、拿不到隧道地址。
+* 「远程能读到 running 但读不到 url」这个方案被**否决**了：那需要在判据 1 上再开一个口子，
+* 而那正是本次修复要消灭的东西。`tunnelStateFor` 里还留了一层不变量检查作双保险。
+*/
+const TUNNEL_MODE_EXEMPT_PATHS = /* @__PURE__ */ new Set(["/manage/cloudflare/status", "/manage/cloudflare/activity"]);
 var ApiRouter = class {
 	options;
 	constructor(options) {
@@ -5205,7 +5397,7 @@ var ApiRouter = class {
 			return;
 		}
 		if (pathname.startsWith("/manage")) {
-			this.options.auth.requireAdmin(req);
+			this.options.auth.requireAdmin(req, { ...TUNNEL_MODE_EXEMPT_PATHS.has(pathname) ? { allowTunnelMode: true } : {} });
 			await this.dispatchManagement(req, res, url, requestId);
 			return;
 		}
@@ -5824,7 +6016,7 @@ var ApiRouter = class {
 		}
 		if (this.options.tunnels !== void 0 && pathname === "/manage/cloudflare/status") {
 			if (method === "GET" || method === "HEAD") {
-				sendJson(res, 200, this.options.tunnels.publicState);
+				sendJson(res, 200, this.tunnelStateFor(req));
 				return;
 			}
 		}
@@ -5860,6 +6052,30 @@ var ApiRouter = class {
 		}
 		throw new ApiError(404, "ROUTE_NOT_FOUND", "The requested management route does not exist.");
 	}
+	/**
+	* 隧道状态视图。
+	*
+	* **这里不做脱敏，因为用不上**：判据 1 已经把 Cloudflare 边缘头（`Cf-Connecting-IP` /
+	* `Cf-Ray` / …）算作「前面有代理」的证据，于是任何真实隧道来源的请求在
+	* `requireAdmin` 就被 403 挡住了，根本到不了这个方法。能走到这里的只有真·本机请求
+	* （判据 1/2/3 全过），所以 `url` 可以照常给它 —— 那是桌面端「用隧道地址生成配置文本」
+	* 的依据。
+	*
+	* 为什么仍然保留这个方法而不是直接 `publicState`：脱敏的位置要留在一个**语义明确**的
+	* 出口上。将来若有人为了「让远程客户端也能读到隧道是否开着」而放宽判据 1，
+	* 必须在这里重新定义脱敏，而不是顺手把 `url` 一起放出去。
+	* 评估结论见报告：本轮选择「远程一律 403」而不是「远程读得到但 `url` 为 null」，
+	* 因为后者需要为状态端点在判据 1 上再开一个口子，而那正是这次修复要消灭的东西。
+	*/
+	tunnelStateFor(req) {
+		const tunnels = this.options.tunnels;
+		if (tunnels === void 0) throw new ApiError(404, "ROUTE_NOT_FOUND", "The requested management route does not exist.");
+		const state = tunnels.publicState;
+		return adminRefusal(req, { tunnelActive: false }) === void 0 ? state : {
+			...state,
+			url: null
+		};
+	}
 	async dispatchEntries(req, res, url, principal, root, requestId) {
 		const method = req.method ?? "GET";
 		if (method === "GET") {
@@ -6916,7 +7132,8 @@ async function apply(ctx, config = {}) {
 	}
 	await registerBuiltinWorkspaceRoot(ctx, database);
 	const events = new WorkspaceEventBus();
-	const auth = new AuthService(database);
+	const tunnels = new CloudflaredTunnelManager();
+	const auth = new AuthService(database, { tunnelActive: () => tunnels.tunnelActive });
 	const files = new FileService(database, (event) => events.emit(event));
 	const imageHandoffDir = path.join(dataDir, "image-handoff");
 	const handoffRootsOf = () => database.listRoots().map((root) => ({
@@ -6963,7 +7180,7 @@ async function apply(ctx, config = {}) {
 		chat,
 		settings,
 		remote,
-		tunnels: new CloudflaredTunnelManager(),
+		tunnels,
 		cloudflaredBinDir: path.join(dataDir, "cloudflared-bin"),
 		maxUploadBytes,
 		imageFallbackDir: imageHandoffDir,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-remote-bridge",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "Versioned REST bridge for DeepSeek Harness: remote access for trusted clients (chat, files, devices) plus a Phone-settings panel inside the DSH WebUI.",
   "type": "module",
   "packageManager": "pnpm@11.19.0",