dsh-remote-bridge 2.4.3 → 2.5.1

package/lib/index.js

@@ -1,4 +1,4 @@
-import path, { join } from "node:path";
+import path, { join, sep } from "node:path";
 import { chmod, copyFile, lstat, mkdir, open, readFile, readdir, readlink, realpath, rename, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
 import { execFile, spawn } from "node:child_process";
 import { createHash, randomBytes, randomUUID } from "node:crypto";
@@ -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,19 +329,142 @@ 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;
-		const authorization = req.headers.authorization;
+		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);
 			throw new ApiError(401, "AUTH_REQUIRED", "A valid Bearer token is required.");
@@ -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 {
@@ -134,10 +529,22 @@ function isLoopbackOrigin(origin) {
 }
 //#endregion
 //#region src/host/cloudflared.ts
-/** 平台/架构 -> cloudflared 归档后缀。 */
-function archSuffix(platform = process.platform) {
+/**
+* 平台/架构 -> cloudflared 归档后缀。
+*
+* **架构必须能单独传**，不能读 `process.arch`：
+* 2026-10-20 CI 实锤 —— 旧实现里 platform 是参数、arch 却写死 `process.arch`，
+* 于是 `archSuffix('linux')` 在 macOS runner（arm64）上返回 `linux-arm64`，
+* 而调用方要的是「linux 平台该用哪个官方归档」。同一函数里 platform 可控、
+* arch 不可控，是**自相矛盾的设计**；测试在 macOS 上红、Linux 上绿，全平台矩阵
+* （ubuntu/windows/macos × 两个 Node 版本）里只有 Linux 那两格能过。
+*
+* 两个参数都带默认值时保持旧行为（本机平台 + 本机架构）；显式传入时，
+* 结果只由入参决定 —— 这才让「算一个别的平台的后缀」成为可能。
+*/
+function archSuffix(platform = process.platform, arch = process.arch) {
 	if (platform !== "linux") throw new Error(`cloudflared 尚不支持 ${platform} 平台。`);
-	switch (process.arch) {
+	switch (arch) {
 		case "x64": return "linux-amd64";
 		case "arm64": return "linux-arm64";
 		default: throw new Error(`cloudflared 尚不支持 ${process.arch} 架构。`);
@@ -197,8 +604,20 @@ function isDebSource() {
 	return mirrorBase().startsWith("deb+");
 }
 /** 返回要下载的源 URL：deb 源返回完整 .deb 地址；裸镜像基址拼架构后缀；否则官方 GitHub。 */
-function downloadUrlFor() {
-	const suffix = archSuffix();
+/**
+* cloudflared 官方归档的下载地址。
+*
+* **platform/arch 都能显式传入**（2026-10-20 CI 实锤后加）：旧实现里
+* `downloadUrlFor()` 走 `archSuffix()` 的默认参数 —— 也就是**本机** platform/arch。
+* 于是这个函数在 macOS runner 上直接抛「尚不支持 darwin 平台」，
+* 而它要回答的问题其实是「linux 的 cloudflared 该从哪下」。
+*
+* 默认值保持本机（生产调用点 `ensureCloudflared` 就在 linux 上跑，行为不变），
+* 但显式传入后结果只由入参决定 —— 这才让「算别的平台的 URL」成为可能，
+* 也让测试不依赖跑在什么机器上。
+*/
+function downloadUrlFor(platform = process.platform, arch = process.arch) {
+	const suffix = archSuffix(platform, arch);
 	const mirror = mirrorBase();
 	if (mirror === "") return `${OFFICIAL_BASE}${suffix}`;
 	if (mirror.startsWith("deb+")) return mirror.slice(4);
@@ -279,406 +698,186 @@ async function ensureCloudflared(dataDir, report) {
 				return writeFromDeb(dataDir, res.body, url);
 			}
 			report?.({
-				stage: "unpacking",
-				label: "写入二进制并赋予执行权限…",
-				percent: null
-			});
-			const tmp = path.join(dataDir, `.cloudflared.tmp-${process.pid}`);
-			await writeFile(tmp, res.body);
-			await chmod(tmp, 493);
-			await rename(tmp, existing);
-			return existing;
-		} catch (cause) {
-			errors.push(cause instanceof Error ? cause.message : String(cause));
-		}
-	}
-	const tried = candidates.map((c) => c.url).join("\n  ");
-	throw new Error(`下载 cloudflared 失败：\n  ${tried}\n原因：${errors.join("；")}`);
-}
-/**
-* 从 `.deb` 包字节中提取 `usr/bin/cloudflared`，原子落到 `dataDir/cloudflared`。
-* 不调用系统 `dpkg -i`（避免污染包数据库），只做解包 + 提取。
-*/
-async function writeFromDeb(dataDir, debBuffer, url) {
-	await mkdir(dataDir, { recursive: true });
-	const debPath = path.join(dataDir, `.cloudflared.deb-${process.pid}`);
-	const extractDir = path.join(dataDir, `.cloudflared-extract-${process.pid}`);
-	await writeFile(debPath, debBuffer);
-	await mkdir(extractDir, { recursive: true });
-	try {
-		await new Promise((resolve, reject) => {
-			execFile("dpkg-deb", [
-				"-x",
-				debPath,
-				extractDir
-			], (err) => err ? reject(err) : resolve());
-		});
-		const inner = path.join(extractDir, "usr", "bin", "cloudflared");
-		const out = path.join(dataDir, "cloudflared");
-		const bin = await readFile(inner);
-		await writeFile(out, bin);
-		await chmod(out, 493);
-		return out;
-	} finally {
-		await rm(debPath, { force: true }).catch(() => {});
-		await rm(extractDir, {
-			recursive: true,
-			force: true
-		}).catch(() => {});
-	}
-}
-/** 一次 cloudflared 子进程生命周期 + 对外状态机。 */
-var CloudflaredTunnelManager = class {
-	process = null;
-	url = null;
-	channel = null;
-	errorText = void 0;
-	listeners = [];
-	activity = {
-		stage: "idle",
-		label: "",
-		percent: null
-	};
-	/** 当前进行中任务的阶段进度（无任务时 stage 为 idle）。 */
-	get activityState() {
-		return this.activity;
-	}
-	/** 上报一条阶段进度（前端轮询 /cloudflare/activity 可见）。 */
-	reportActivity(a) {
-		this.activity = a;
-		this.emit();
-	}
-	/** 任务结束（成功或失败）时清空进行中进度。 */
-	clearActivity() {
-		this.activity = {
-			stage: "idle",
-			label: "",
-			percent: null
-		};
-		this.emit();
-	}
-	get publicState() {
-		return {
-			channel: this.channel,
-			url: this.url,
-			running: this.process !== null && !this.process.killed,
-			...this.errorText === void 0 ? {} : { error: this.errorText }
-		};
-	}
-	/** 订阅状态变化；返回取消函数。 */
-	onStatus(cb) {
-		this.listeners.push(cb);
-		return () => {
-			this.listeners = this.listeners.filter((fn) => fn !== cb);
-		};
-	}
-	emit() {
-		for (const fn of this.listeners) fn();
-	}
-	setError(message) {
-		this.errorText = message;
-		this.emit();
-	}
-	/**
-	* 启动一次 Quick Tunnel。
-	* @param exe cloudflared 可执行文件路径（来自 [ensureCloudflared]）
-	* @param port bridge 监听端口，cloudflared 把外网请求转发到 localhost:port
-	*/
-	async startQuick(exe, port) {
-		if (this.process !== null && !this.process.killed) throw new Error("隧道已经在运行中，请先停止。");
-		this.errorText = void 0;
-		this.reportActivity({
-			stage: "starting",
-			label: "正在启动 cloudflared 隧道…",
-			percent: null
-		});
-		const child = spawn(exe, [
-			"tunnel",
-			"--url",
-			`http://127.0.0.1:${port}`,
-			"--no-autoupdate"
-		], { stdio: [
-			"ignore",
-			"pipe",
-			"pipe"
-		] });
-		this.process = child;
-		this.channel = "quick";
-		this.emit();
-		const onData = (buf) => {
-			const found = extractQuickTunnelUrl(buf.toString("utf8"));
-			if (found !== null && this.url === null) {
-				this.url = found;
-				this.clearActivity();
-				this.emit();
-			}
-		};
-		child.stdout?.on("data", onData);
-		child.stderr?.on("data", onData);
-		child.on("exit", (code, signal) => {
-			const wasThis = this.process === child;
-			this.process = null;
-			this.channel = null;
-			this.emit();
-			if (wasThis) {
-				if (this.url === null) this.setError(`cloudflared 退出（code=${code ?? "?"}, signal=${signal ?? "?"}），未拿到隧道地址。`);
-				this.url = null;
-				if (this.channel === null) this.clearActivity();
-			}
-		});
-		return this.publicState;
-	}
-	/** 停止当前隧道。 */
-	stop() {
-		const child = this.process;
-		if (child !== null && !child.killed) child.kill("SIGTERM");
-		this.process = null;
-		this.channel = null;
-		this.url = null;
-		this.emit();
-		return this.publicState;
-	}
-	/** 注入已抓到的地址 + 通道（命名隧道用）。 */
-	setNamed(url) {
-		this.url = url;
-		this.channel = "named";
-		this.emit();
-		return this.publicState;
-	}
-};
-//#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;
+				stage: "unpacking",
+				label: "写入二进制并赋予执行权限…",
+				percent: null
+			});
+			const tmp = path.join(dataDir, `.cloudflared.tmp-${process.pid}`);
+			await writeFile(tmp, res.body);
+			await chmod(tmp, 493);
+			await rename(tmp, existing);
+			return existing;
+		} catch (cause) {
+			errors.push(cause instanceof Error ? cause.message : String(cause));
 		}
-		res.writeHead(200, {
-			"content-type": sniffed,
-			"content-length": String(image.bytes.byteLength),
-			"cache-control": "private, max-age=300",
-			"x-content-type-options": "nosniff"
+	}
+	const tried = candidates.map((c) => c.url).join("\n  ");
+	throw new Error(`下载 cloudflared 失败：\n  ${tried}\n原因：${errors.join("；")}`);
+}
+/**
+* 从 `.deb` 包字节中提取 `usr/bin/cloudflared`，原子落到 `dataDir/cloudflared`。
+* 不调用系统 `dpkg -i`（避免污染包数据库），只做解包 + 提取。
+*/
+async function writeFromDeb(dataDir, debBuffer, url) {
+	await mkdir(dataDir, { recursive: true });
+	const debPath = path.join(dataDir, `.cloudflared.deb-${process.pid}`);
+	const extractDir = path.join(dataDir, `.cloudflared-extract-${process.pid}`);
+	await writeFile(debPath, debBuffer);
+	await mkdir(extractDir, { recursive: true });
+	try {
+		await new Promise((resolve, reject) => {
+			execFile("dpkg-deb", [
+				"-x",
+				debPath,
+				extractDir
+			], (err) => err ? reject(err) : resolve());
 		});
-		if (req.method === "HEAD") {
-			res.end();
-			return;
-		}
-		res.end(Buffer.from(image.bytes.buffer, image.bytes.byteOffset, image.bytes.byteLength));
-	};
+		const inner = path.join(extractDir, "usr", "bin", "cloudflared");
+		const out = path.join(dataDir, "cloudflared");
+		const bin = await readFile(inner);
+		await writeFile(out, bin);
+		await chmod(out, 493);
+		return out;
+	} finally {
+		await rm(debPath, { force: true }).catch(() => {});
+		await rm(extractDir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
 }
+/** 一次 cloudflared 子进程生命周期 + 对外状态机。 */
+var CloudflaredTunnelManager = class {
+	process = null;
+	url = null;
+	channel = null;
+	errorText = void 0;
+	listeners = [];
+	activity = {
+		stage: "idle",
+		label: "",
+		percent: null
+	};
+	/** 当前进行中任务的阶段进度（无任务时 stage 为 idle）。 */
+	get activityState() {
+		return this.activity;
+	}
+	/** 上报一条阶段进度（前端轮询 /cloudflare/activity 可见）。 */
+	reportActivity(a) {
+		this.activity = a;
+		this.emit();
+	}
+	/** 任务结束（成功或失败）时清空进行中进度。 */
+	clearActivity() {
+		this.activity = {
+			stage: "idle",
+			label: "",
+			percent: null
+		};
+		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.tunnelActive,
+			...this.errorText === void 0 ? {} : { error: this.errorText }
+		};
+	}
+	/** 订阅状态变化；返回取消函数。 */
+	onStatus(cb) {
+		this.listeners.push(cb);
+		return () => {
+			this.listeners = this.listeners.filter((fn) => fn !== cb);
+		};
+	}
+	emit() {
+		for (const fn of this.listeners) fn();
+	}
+	setError(message) {
+		this.errorText = message;
+		this.emit();
+	}
+	/**
+	* 启动一次 Quick Tunnel。
+	* @param exe cloudflared 可执行文件路径（来自 [ensureCloudflared]）
+	* @param port bridge 监听端口，cloudflared 把外网请求转发到 localhost:port
+	*/
+	async startQuick(exe, port) {
+		if (this.process !== null && !this.process.killed) throw new Error("隧道已经在运行中，请先停止。");
+		this.errorText = void 0;
+		this.reportActivity({
+			stage: "starting",
+			label: "正在启动 cloudflared 隧道…",
+			percent: null
+		});
+		const child = spawn(exe, [
+			"tunnel",
+			"--url",
+			`http://127.0.0.1:${port}`,
+			"--no-autoupdate"
+		], { stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		] });
+		this.process = child;
+		this.channel = "quick";
+		this.emit();
+		const onData = (buf) => {
+			const found = extractQuickTunnelUrl(buf.toString("utf8"));
+			if (found !== null && this.url === null) {
+				this.url = found;
+				this.clearActivity();
+				this.emit();
+			}
+		};
+		child.stdout?.on("data", onData);
+		child.stderr?.on("data", onData);
+		child.on("exit", (code, signal) => {
+			const wasThis = this.process === child;
+			this.process = null;
+			this.channel = null;
+			this.emit();
+			if (wasThis) {
+				if (this.url === null) this.setError(`cloudflared 退出（code=${code ?? "?"}, signal=${signal ?? "?"}），未拿到隧道地址。`);
+				this.url = null;
+				if (this.channel === null) this.clearActivity();
+			}
+		});
+		return this.publicState;
+	}
+	/** 停止当前隧道。 */
+	stop() {
+		const child = this.process;
+		if (child !== null && !child.killed) child.kill("SIGTERM");
+		this.process = null;
+		this.channel = null;
+		this.url = null;
+		this.emit();
+		return this.publicState;
+	}
+	/** 注入已抓到的地址 + 通道（命名隧道用）。 */
+	setNamed(url) {
+		this.url = url;
+		this.channel = "named";
+		this.emit();
+		return this.publicState;
+	}
+};
 //#endregion
 //#region src/host/path-policy.ts
 const WINDOWS_RESERVED = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
@@ -796,7 +995,33 @@ function parentWirePath(relativePath) {
 * 调用方必须自己给出可读的错误（见 readAttachment），而不是让用户看到一个
 * 语焉不详的 500。
 */
+/**
+* 读一个**可选**宿主服务：存在就返回，不存在返回 null。
+*
+* ## 为什么必须走 `ctx.reflect.get(name, false)`，不能直接读属性
+*
+* cordis 的 `inject` 是**硬依赖**（`registry.d.ts` 的 `Inject` 类型只有数组与映射两种
+* 形式，注释原文是 "required services"）：inject 里任何一个服务缺失，`_refresh()`
+* 就把 epoch 置为 INACTIVE，**整个插件不激活**。
+*
+* 所以「可选服务」**不能**写进 inject —— 写了就变成「哪个内核版本缺它、插件在哪一版
+* 整个死掉」。而直接读属性（`host[name]`）也不行：不在 inject 里的属性会抛
+* `cannot get property "x" without inject`，与「服务不存在」**报同一个错**，
+* 于是这个函数会永远返回 null（这正是它此前的实际行为，
+* `attachments` / `fileUploads` 一直在走降级路径）。
+*
+* `ctx.reflect.get(name, false)` 是 cordis 给这件事准备的正路
+* （`cordis/lib/index.js` 的 ReflectService.get，注释原文：
+* "Read a service from the store **without the inject requirement**"）：
+* 不要求 inject 声明，服务不存在时返回 `undefined` 而不是抛错。
+*/
 function optionalService(host, name) {
+	const reflect = host.reflect;
+	if (reflect !== void 0 && typeof reflect.get === "function") try {
+		const value = reflect.get(name, false);
+		if (value === void 0 || value === null) return null;
+		return value;
+	} catch {}
 	try {
 		return host[name];
 	} catch {
@@ -1413,7 +1638,7 @@ function writeHandoffFile(dir, workspace, mediaType, data) {
 	if (!existsSync(absolute)) writeFileSync(absolute, bytes, { mode: 384 });
 	return {
 		absolute,
-		relative: workspace !== void 0 && absolute.startsWith(workspace + "/") ? absolute.slice(workspace.length + 1) : fileName
+		relative: workspace !== void 0 && absolute.startsWith(workspace + sep) ? absolute.slice(workspace.length + 1).split(sep).join("/") : fileName
 	};
 }
 /** 交接文件名只允许「内容哈希 + 图片扩展名」：挡住一切路径穿越。 */
@@ -2013,7 +2238,13 @@ function createDsh02ApiProxy(host, options = {}) {
 					settingsNs: entry.settingsNs,
 					settingsPath: [...entry.settingsPath],
 					active: live.has(entry.provider),
-					...entry.declared === void 0 ? {} : { declared: entry.declared }
+					...entry.declared === void 0 ? {} : { declared: entry.declared },
+					...entry.defaultBaseURL === void 0 ? {} : { defaultBaseURL: entry.defaultBaseURL },
+					...entry.baseURLEnv === void 0 ? {} : { baseURLEnv: [...entry.baseURLEnv] },
+					...entry.nativeAuth === void 0 ? {} : { nativeAuth: {
+						...entry.nativeAuth,
+						...entry.nativeAuth.env === void 0 ? {} : { env: [...entry.nativeAuth.env] }
+					} }
 				})) };
 			}),
 			models: () => call(async () => {
@@ -2036,7 +2267,7 @@ function createDsh02ApiProxy(host, options = {}) {
 }
 //#endregion
 //#region src/shared/version.ts
-const PLUGIN_VERSION = "2.4.3";
+const PLUGIN_VERSION = "2.5.1";
 //#endregion
 //#region src/host/capabilities.ts
 /**
@@ -3235,10 +3466,51 @@ function redactApprovalText(value, maxLength = 1200) {
 }
 //#endregion
 //#region src/host/database.ts
+/**
+* 本进程内打开的库（弱引用集合）。
+*
+* ## 为什么需要它
+*
+* `WorkspaceDatabase` 用 `PRAGMA journal_mode=WAL` 打开 sqlite，会留下
+* `workspace.sqlite` / `-wal` / `-shm` 三个文件，**且句柄不关就删不掉**。
+* Linux/macOS 上删一个仍被打开的文件是允许的（unlink 只是断链），所以问题
+* 在那里看不出来；**Windows 上直接 EBUSY**：
+*
+* ```
+* EBUSY: resource busy or locked, unlink 'C:\...\Temp\daw-xxx\state\workspace.sqlite'
+* ```
+*
+* 2026-10-20 CI 在 windows-latest 上实锤（macOS/Linux 全绿、Windows 全红）。
+*
+* ## 它的作用
+*
+* 进程退出时统一关闭所有还开着的库 —— 无论调用方记不记得 `close()`。
+* 这不是「代替 close」，而是**兜底**：正常路径仍应显式 close（早关早释放），
+* 但漏掉的那一个不会在 Windows 上变成 EBUSY 式的删除失败。
+*
+* 弱引用：不阻止 GC，也不阻止正常 close 后的移除（close 时会从集合里摘掉）。
+*/
+const openDatabases = /* @__PURE__ */ new Set();
+/** 进程退出时尽力关闭所有还开着的库。 */
+function closeAllOpenDatabases() {
+	for (const ref of [...openDatabases]) {
+		const db = ref.deref();
+		if (db === void 0) {
+			openDatabases.delete(ref);
+			continue;
+		}
+		try {
+			db.close();
+		} catch {}
+	}
+	openDatabases.clear();
+}
+process.once("exit", closeAllOpenDatabases);
 var WorkspaceDatabase = class {
 	dataDir;
 	trashDir;
 	db;
+	closed = false;
 	constructor(dataDir) {
 		this.dataDir = path.resolve(dataDir);
 		this.trashDir = path.join(this.dataDir, "trash");
@@ -3246,8 +3518,13 @@ var WorkspaceDatabase = class {
 		this.db = new DatabaseSync(path.join(this.dataDir, "workspace.sqlite"));
 		this.db.exec("PRAGMA journal_mode=WAL; PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000;");
 		this.migrate();
+		openDatabases.add(new WeakRef(this));
 	}
+	/** 关闭数据库。**幂等** —— 重复调用不抛错。 */
 	close() {
+		if (this.closed) return;
+		this.closed = true;
+		for (const ref of [...openDatabases]) if (ref.deref() === this) openDatabases.delete(ref);
 		this.db.close();
 	}
 	/**
@@ -4064,7 +4341,14 @@ function trashView(record) {
 * 使用方式：`GET /dsh-workspace-api/api/v1/debug/host-services`
 * （需要设备 token 或 loopback admin，与其它 REST 端点同一套鉴权）。
 */
-/** 插件 `src/index.ts` 里 inject 声明的全部服务名。 */
+/**
+* 插件 `cordis.patch.yml` 与 `src/index.ts` 里 inject 声明的全部服务名
+* （**两份清单必须一致**，docs:check 有对齐门禁）。
+*
+* ⚠️ 只能放「两个支持版本（0.2.0-rc.2 与 0.2.1-rc.2）上都存在的服务」——
+* cordis 的 inject 是硬依赖，缺一个整个插件不激活（2026-10-20 在 0.2.0-rc.2 的
+* smoke-profile-install 上实锤过）。可选服务一律走 OPTIONAL_SERVICE_NAMES。
+*/
 const INJECTED_SERVICE_NAMES = [
 	"sessionController",
 	"workspaceController",
@@ -4072,17 +4356,26 @@ const INJECTED_SERVICE_NAMES = [
 	"settingsController",
 	"credentialsController",
 	"agentPresets",
-	"permissionPresets",
 	"llm",
 	"webServer",
 	"agents",
-	"commands",
+	"commands"
+];
+/**
+* **可选服务**：不写进 inject（inject 是硬依赖），由插件经
+* `ctx.reflect.get(name, false)` 运行时读取 —— 读到就走该能力，读不到按能力位降级。
+*
+* 探针用同一条 `reflect.get` 读取它们：这样报告的是「内核**真的**提供了什么」，
+* 而不是「我们 inject 了什么」。两者的差就是「可选能力在这台内核上可用与否」。
+*/
+const OPTIONAL_SERVICE_NAMES = [
+	"permissionPresets",
 	"jobController",
 	"fileUploads",
-	"attachments"
+	"attachments",
+	"workingDirectory",
+	"workspaceFiles"
 ];
-/** 0.2.1 新增、插件尚未 inject 但已确认存在于 web profile 的服务。 */
-const OBSERVED_ONLY_SERVICE_NAMES = ["workingDirectory", "workspaceFiles"];
 /**
 * 在注入属性**仍可读**的时机（即 `apply` 执行期间）逐个试读服务。
 *
@@ -4096,6 +4389,32 @@ const OBSERVED_ONLY_SERVICE_NAMES = ["workingDirectory", "workspaceFiles"];
 * @returns 每个服务的可解析性报告。
 */
 function probeHostServices(host, pluginVersion) {
+	const reflect = host.reflect;
+	const probeOptional = (name) => {
+		if (reflect === void 0 || typeof reflect.get !== "function") return {
+			name,
+			available: false,
+			resolvable: false,
+			error: "ctx.reflect.get unavailable on this cordis"
+		};
+		try {
+			const value = reflect.get(name, false);
+			const resolvable = value !== null && value !== void 0;
+			return {
+				name,
+				available: true,
+				resolvable,
+				...resolvable ? {} : { error: "not provided by this kernel/profile" }
+			};
+		} catch (caught) {
+			return {
+				name,
+				available: false,
+				resolvable: false,
+				error: caught instanceof Error ? caught.message : String(caught)
+			};
+		}
+	};
 	const probeOne = (name) => {
 		let available = false;
 		let resolvable = false;
@@ -4116,7 +4435,7 @@ function probeHostServices(host, pluginVersion) {
 		};
 	};
 	const injected = INJECTED_SERVICE_NAMES.map(probeOne);
-	const observed = OBSERVED_ONLY_SERVICE_NAMES.map(probeOne);
+	const observed = OPTIONAL_SERVICE_NAMES.map(probeOptional);
 	return {
 		pluginVersion,
 		injected,
@@ -4125,7 +4444,7 @@ function probeHostServices(host, pluginVersion) {
 			injectedTotal: injected.length,
 			injectedAvailable: injected.filter((service) => service.available).length,
 			injectedMissing: injected.filter((service) => !service.available).map((service) => service.name),
-			observedAvailable: observed.filter((service) => service.available).map((service) => service.name)
+			observedAvailable: observed.filter((service) => service.resolvable).map((service) => service.name)
 		}
 	};
 }
@@ -4787,20 +5106,36 @@ function timestamp() {
 //#endregion
 //#region src/host/root-resolver.ts
 /**
-* 在授权根集合里找出包含该绝对路径的那一个（**纯字符串匹配，不触碰文件系统**）。
+* 与 [matchAuthorizedRoot] 相同，但**两侧都做 realpath 归一**再比较。
+*
+* ## 为什么需要它
+*
+* 授权根在入库时走了 `canonicalRoot()`（`database.ts` 的 addRoot），存的是**解析过
+* 符号链接**的路径；而客户端请求里的路径通常**没解析**。两者字面不同就匹配不上，
+* 结果是「明明在授权根内」却报 404 `PATH_OUTSIDE_ROOTS`。
 *
-* 多个根相互嵌套时取**最长**的那个 —— 否则外层根会把内层根下的文件解析成更长的相对路径，
-* 虽然仍能读到同一文件，但会绕过内层根更严格的授权语义。
+* 最常见的触发场景就是 **macOS 的临时目录**：`os.tmpdir()` 给的是
+* `/var/folders/...`，而它是指向 `/private/var/folders/...` 的**符号链接**。
+* 于是测试里 `mkdtemp(os.tmpdir())` 造出的根与请求路径字面不一致 → 404。
+* 2026-10-20 CI 在 macOS runner 上实锤（Linux 上 tmpdir 不带 symlink，所以只在 macOS 炸）。
 *
-* 注意这只是粗筛：字符串前缀相等不代表真实落在根内（根内可能存在指向外部的符号链接）。
-* 真正的安全校验由 [inspectResolvedPath] 经 `resolveAuthorizedPath` 完成。
+* 这不只是测试问题：用户给一个经 symlink 的路径加授权根、或客户端用 symlink 别名
+* 请求，都会踩到。**归一后两侧是同一条真实路径**，语义也就正确了。
+*
+* ## 安全边界不变
+*
+* 归一只解决「同一个目录的两种写法」，**不放宽**任何权限：
+* 真正的越权校验仍由 [inspectResolvedPath] → `resolveAuthorizedPath` 逐段做
+* （它会拒绝指向根外的符号链接）。这里只是把「找哪个根」这一步做准。
 */
-function matchAuthorizedRoot(absolutePath, roots) {
+async function matchAuthorizedRootResolved(absolutePath, roots) {
+	const candidate = await canonicalOrSelf(absolutePath);
 	let best;
 	for (const root of roots) {
-		const relative = wireRelative(root.realPath, absolutePath);
+		const canonicalRoot = await canonicalOrSelf(root.realPath);
+		const relative = wireRelative(canonicalRoot, candidate);
 		if (relative === void 0) continue;
-		if (best === void 0 || root.realPath.length > best.root.realPath.length) best = {
+		if (best === void 0 || canonicalRoot.length > best.root.realPath.length) best = {
 			root,
 			relative
 		};
@@ -4810,6 +5145,14 @@ function matchAuthorizedRoot(absolutePath, roots) {
 		path: best.relative
 	};
 }
+/** 取路径的真实形式；取不到（路径不存在、无权限等）就原样返回。 */
+async function canonicalOrSelf(target) {
+	try {
+		return await realpath(target);
+	} catch {
+		return target;
+	}
+}
 const CONTENT_TYPES = {
 	".md": "text/markdown",
 	".txt": "text/plain",
@@ -4979,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) {
@@ -5037,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;
 		}
@@ -5071,7 +5431,7 @@ var ApiRouter = class {
 			const requested = url.searchParams.get("path")?.trim() ?? "";
 			if (requested === "") throw new ApiError(400, "BODY_INVALID", "path is required.");
 			if (!path.isAbsolute(requested)) throw new ApiError(400, "PATH_NOT_ABSOLUTE", "path must be an absolute path.");
-			const match = matchAuthorizedRoot(path.resolve(requested), this.authorizedRoots(principal));
+			const match = await matchAuthorizedRootResolved(path.resolve(requested), this.authorizedRoots(principal));
 			if (match === void 0) throw new ApiError(404, "PATH_OUTSIDE_ROOTS", "The path is not inside any root this device may access.");
 			sendJson(res, 200, await inspectResolvedPath(this.requireRoot(principal, match.rootId), match.path));
 			return;
@@ -5656,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;
 			}
 		}
@@ -5692,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") {
@@ -6424,6 +6808,10 @@ var DshSettingsAdapter = class {
 					configurable: entry.settingsNs !== "",
 					configured,
 					removable,
+					...entry.defaultBaseURL === void 0 ? {} : { defaultBaseURL: entry.defaultBaseURL },
+					...entry.baseURLEnv === void 0 ? {} : { baseURLEnv: entry.baseURLEnv },
+					...entry.nativeAuth === void 0 ? {} : { nativeAuth: entry.nativeAuth },
+					...entry.settingsNs === "" ? {} : { settingsNs: entry.settingsNs },
 					credential: {
 						ref,
 						...credential
@@ -6463,12 +6851,18 @@ var DshSettingsAdapter = class {
 			});
 		}
 		if (patch.models !== void 0) {
-			validateModels(patch.models);
-			ops.push({
-				op: "set",
-				path: [...context.entry.settingsPath, "models"],
-				value: patch.models
+			if (patch.models === null) ops.push({
+				op: "unset",
+				path: [...context.entry.settingsPath, "models"]
 			});
+			else {
+				validateModels(patch.models);
+				ops.push({
+					op: "set",
+					path: [...context.entry.settingsPath, "models"],
+					value: patch.models
+				});
+			}
 		}
 		const ref = text(context.profile?.apiKeyEnv) ?? keyRef(providerId);
 		if (context.entry.settingsPath.length > 0 && context.profile === void 0) ops.unshift({
@@ -6718,14 +7112,10 @@ const inject = [
 	"settingsController",
 	"credentialsController",
 	"agentPresets",
-	"permissionPresets",
 	"llm",
 	"webServer",
 	"agents",
-	"commands",
-	"jobController",
-	"fileUploads",
-	"attachments"
+	"commands"
 ];
 async function apply(ctx, config = {}) {
 	const dataDir = path.resolve(config.dataDir ?? path.join(process.cwd(), ".dsh-workspace"));
@@ -6742,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) => ({
@@ -6770,13 +7161,9 @@ async function apply(ctx, config = {}) {
 		ctx.logger.warn(/* @__PURE__ */ new Error(`dsh-remote-bridge: host service probe failed: ${String(error)}`));
 	}
 	let router;
-	let jobControllerAvailable = false;
-	try {
-		ctx.jobController;
-		jobControllerAvailable = true;
-	} catch {
-		ctx.logger.warn(/* @__PURE__ */ new Error("dsh-remote-bridge: ctx.jobController unavailable, background-job endpoints disabled"));
-	}
+	const reflect = ctx.reflect;
+	const jobControllerAvailable = reflect?.get !== void 0 && reflect.get("jobController", false) !== void 0;
+	if (!jobControllerAvailable) ctx.logger.warn(/* @__PURE__ */ new Error("dsh-remote-bridge: jobController not provided by this kernel, background-job endpoints disabled"));
 	const remote = new RemoteApiServer({
 		port,
 		remoteHost,
@@ -6793,12 +7180,12 @@ async function apply(ctx, config = {}) {
 		chat,
 		settings,
 		remote,
-		tunnels: new CloudflaredTunnelManager(),
+		tunnels,
 		cloudflaredBinDir: path.join(dataDir, "cloudflared-bin"),
 		maxUploadBytes,
 		imageFallbackDir: imageHandoffDir,
 		...hostServiceReport === void 0 ? {} : { hostServiceReport },
-		...jobControllerAvailable ? { jobs: new JobAdapter({ jobController: ctx.jobController }) } : {}
+		...jobControllerAvailable && reflect?.get ? { jobs: new JobAdapter({ jobController: reflect.get("jobController", false) }) } : {}
 	});
 	try {
 		await remote.start();