dsh-remote-bridge 2.2.4 → 2.3.0

package/lib/index.js

@@ -1,6 +1,6 @@
 import path, { join } from "node:path";
-import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { chmod, copyFile, lstat, mkdir, open, readFile, readdir, readlink, realpath, rename, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import { createReadStream, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import os, { homedir, hostname, networkInterfaces } from "node:os";
@@ -1013,20 +1013,32 @@ var WorkspaceDatabase = class {
 	close() {
 		this.db.close();
 	}
+	/**
+	* 导出 `roots` 的建表语句（只读，诊断与迁移测试用）。
+	*
+	* 存在的理由：迁移要判断「UNIQUE 还在不在」，单看 `PRAGMA table_info` 看不出来 ——
+	* 表结构读出来一模一样，区别在约束上。这个方法让「重建真的发生了」可以被断言，
+	* 而不是靠迁移没报错来推测。
+	*/
+	dumpSchema() {
+		return this.db.prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'roots'").get()?.sql ?? "";
+	}
 	getSetting(key) {
 		return this.db.prepare("SELECT value FROM settings WHERE key = ?").get(key)?.value;
 	}
 	setSetting(key, value) {
 		this.db.prepare("INSERT INTO settings(key,value) VALUES(?,?) ON CONFLICT(key) DO UPDATE SET value=excluded.value").run(key, value);
 	}
-	async addRoot(inputPath, label) {
+	async addRoot(inputPath, label, options) {
 		const realPath = await canonicalRoot(inputPath);
-		const duplicate = this.db.prepare("SELECT * FROM roots WHERE real_path = ?").get(realPath);
-		if (duplicate !== void 0) return rootFromRow(duplicate);
+		if (options?.allowDuplicate !== true) {
+			const duplicate = this.db.prepare("SELECT * FROM roots WHERE real_path = ?").get(realPath);
+			if (duplicate !== void 0) return rootFromRow(duplicate);
+		}
 		const id = randomUUID();
 		const createdAt = Date.now();
 		const resolvedLabel = label?.trim() || path.basename(realPath) || realPath;
-		this.db.prepare("INSERT INTO roots(id,label,real_path,created_at) VALUES(?,?,?,?)").run(id, resolvedLabel, realPath, createdAt);
+		this.db.prepare("INSERT INTO roots(id,label,real_path,created_at,builtin) VALUES(?,?,?,?,0)").run(id, resolvedLabel, realPath, createdAt);
 		this.audit("admin", "loopback-admin", "root.add", id, void 0, { label: resolvedLabel });
 		return {
 			id,
@@ -1036,13 +1048,52 @@ var WorkspaceDatabase = class {
 		};
 	}
 	listRoots() {
-		return this.db.prepare("SELECT * FROM roots ORDER BY created_at, id").all().map(rootFromRow);
+		return this.db.prepare("SELECT * FROM roots ORDER BY builtin DESC, created_at, id").all().map(rootFromRow);
 	}
 	getRoot(id) {
 		const row = this.db.prepare("SELECT * FROM roots WHERE id = ?").get(id);
 		return row === void 0 ? void 0 : rootFromRow(row);
 	}
+	/**
+	* 登记「DSH 工作区」根 —— **幂等**。
+	*
+	* 用户要求：当前 DSH 的工作目录要显示成一个授权根，**不可删除、但可以正常访问**。
+	* 它不是另起一张表，而是**一条普通的根**加一个 `builtin` 标记：配对、`files.*`
+	* 授权、回收站、写盘全走现成逻辑，少一套需要同步维护的规则。
+	*
+	* ## 同目录已有一条普通根时，另起一条而不是复用它
+	*
+	* 这是实测踩到的现实情况：用户早于这个功能**自己**加过同一条目录（本机那条是
+	* 10-08 手工加的），路径和 DSH 工作区一模一样。
+	*
+	* 初版在这里「尊重用户选择」直接返回，结果就是**内置项永远登记不上** —— 因为它
+	* 每次都撞上那条已有的普通根然后什么都不做。界面上那个「不可删除」也就永远出不来。
+	* 用户的选择和功能的正确性在这里是冲突的：用户要的是「这条要不可删」，不是
+	* 「这条不能变」。
+	*
+	* 所以改成**另起一条**：用户原来那条保持可删（那是他的目录，他有权删），内置那条
+	* 独立存在。代价是列表里同一个路径出现两行 —— 这是「两条记录、两种权限」的必然
+	* 结果，比让功能失效或擅自改他的配置都更可接受。
+	*
+	* 幂等不再靠 UNIQUE（它已经被去掉了），而是靠「已存在 `builtin = 1` 的同路径就
+	* 直接返回」。插件**每次启动都可以无脑调一次**。
+	*
+	* 只有传入路径确实存在才登记：工作区可能被用户删掉，这时留一条指向虚空的授权根，
+	* 手机浏览时会一路报错，比不显示更糟。
+	*/
+	async ensureBuiltinRoot(realPath, label) {
+		const builtin = this.db.prepare("SELECT * FROM roots WHERE real_path = ? AND builtin = 1").get(realPath);
+		if (builtin !== void 0) return rootFromRow(builtin);
+		const created = await this.addRoot(realPath, label, { allowDuplicate: true });
+		this.db.prepare("UPDATE roots SET builtin = 1 WHERE id = ?").run(created.id);
+		this.audit("admin", "loopback-admin", "root.builtin", created.id, void 0, { label });
+		return {
+			...created,
+			builtin: true
+		};
+	}
 	removeRoot(id) {
+		if (this.getRoot(id)?.builtin === true) throw new ApiError(403, "ROOT_BUILTIN", "The DSH workspace root cannot be removed.");
 		if (this.db.prepare("DELETE FROM roots WHERE id = ?").run(id).changes === 0) throw new ApiError(404, "ROOT_NOT_FOUND", "The authorized root does not exist.");
 		this.audit("admin", "loopback-admin", "root.remove", id);
 	}
@@ -1121,7 +1172,7 @@ var WorkspaceDatabase = class {
 		};
 	}
 	listDevices() {
-		const rows = this.db.prepare("SELECT * FROM devices ORDER BY created_at DESC").all();
+		const rows = this.db.prepare("SELECT * FROM devices WHERE revoked_at IS NULL ORDER BY created_at DESC").all();
 		const rootQuery = this.db.prepare("SELECT root_id FROM device_roots WHERE device_id = ? ORDER BY root_id");
 		return rows.map((row) => ({
 			id: row.id,
@@ -1159,9 +1210,60 @@ var WorkspaceDatabase = class {
 		if (device === void 0) throw new ApiError(404, "DEVICE_NOT_FOUND", "The device does not exist.");
 		return device;
 	}
+	/**
+	* 撤销设备 = **直接删除这一行**（用户要求：已撤销的不显示，并自动从数据库中删除）。
+	*
+	* 原先是打 `revoked_at` 标记保留行，两处都不好：
+	* - 界面上会出现一长串灰掉的「已撤销」，本机实测堆到了 32 条，全是历史测试与旧设备；
+	* - 行留着就等于凭据的哈希还在库里，是个长期负担 —— 令牌已经没用了，留着没有意义。
+	*
+	* 删除是安全的，因为：
+	* - `device_roots` 是 `ON DELETE CASCADE`，授权行自动清掉；
+	* - `audit.actor_id` 是**普通字符串不是外键**，审计留痕（谁在什么时候撤了谁）一条不少；
+	* - `authenticate` 仍保留 `revoked_at IS NULL` 作为兜底，万一有别处留下的标记行，
+	*   它们依然登不进来 —— 两层保险不冲突。
+	*/
 	revokeDevice(id) {
-		if (this.db.prepare("UPDATE devices SET revoked_at = ? WHERE id = ? AND revoked_at IS NULL").run(Date.now(), id).changes === 0) throw new ApiError(404, "DEVICE_NOT_FOUND", "The active device does not exist.");
-		this.audit("admin", "loopback-admin", "device.revoke", void 0, void 0, { deviceId: id });
+		const active = this.getActiveDevice(id);
+		if (active === void 0) throw new ApiError(404, "DEVICE_NOT_FOUND", "The active device does not exist.");
+		this.audit("admin", "loopback-admin", "device.revoke", void 0, void 0, {
+			deviceId: id,
+			name: active.name
+		});
+		if (this.db.prepare("DELETE FROM devices WHERE id = ?").run(id).changes === 0) throw new ApiError(404, "DEVICE_NOT_FOUND", "The active device does not exist.");
+	}
+	/**
+	* 一次性清理历史遗留的「标记式」撤销设备（`revoked_at IS NOT NULL` 的行）。
+	*
+	* 撤销改成直接删除之前，每次撤销都只是打个标记，于是库越用越臃肿 —— 本机实测堆到
+	* **32 条**，全是历史测试探针和早已弃用的旧手机，界面上就是一长串灰字。
+	*
+	* 幂等：没有这种行时返回 0，不报错。插件每次启动调一次即可。
+	* 走 `revokeDevice` 的删除语义，但**不能**借它写 `device.revoke` 审计 ——
+	* 那会把「系统清理」记成管理员逐个撤销，审计会失真。清理本身只写一条汇总。
+	*/
+	/**
+	* 仅供测试：造一行「撤销改成删除之前」的标记式撤销数据。
+	*
+	* 真实场景来自历史库（每次撤销只打 `revoked_at` 标记，于是越积越多）。测试需要个
+	* 干净的办法制造这种行，而它不该走生产代码路径 —— 所以显式开一个测试专用入口，
+	* 并起一个自见其明的名字，免得有人把它当成正常 API。
+	*/
+	markRevokedForTest(id) {
+		this.db.prepare("UPDATE devices SET revoked_at = ? WHERE id = ?").run(Date.now(), id);
+	}
+	purgeRevokedDevices() {
+		if (this.db.prepare("SELECT id FROM devices WHERE revoked_at IS NOT NULL").all().length === 0) return 0;
+		this.db.exec("BEGIN IMMEDIATE");
+		try {
+			const result = this.db.prepare("DELETE FROM devices WHERE revoked_at IS NOT NULL").run();
+			this.db.exec("COMMIT");
+			this.audit("admin", "loopback-admin", "device.purge", void 0, void 0, { purged: result.changes });
+			return Number(result.changes);
+		} catch (error) {
+			this.db.exec("ROLLBACK");
+			throw error;
+		}
 	}
 	insertTrash(record) {
 		this.db.prepare("INSERT INTO trash(id,root_id,relative_path,payload_path,kind,size,digest,created_at,status) VALUES(?,?,?,?,?,?,?,?,?)").run(record.id, record.rootId, record.relativePath, record.payloadPath, record.kind, record.size, record.digest, record.createdAt, record.status);
@@ -1199,7 +1301,7 @@ var WorkspaceDatabase = class {
 		this.db.exec(`
       CREATE TABLE IF NOT EXISTS settings(key TEXT PRIMARY KEY, value TEXT NOT NULL);
       CREATE TABLE IF NOT EXISTS roots(
-        id TEXT PRIMARY KEY, label TEXT NOT NULL, real_path TEXT NOT NULL UNIQUE, created_at INTEGER NOT NULL
+        id TEXT PRIMARY KEY, label TEXT NOT NULL, real_path TEXT NOT NULL, created_at INTEGER NOT NULL
       );
       CREATE TABLE IF NOT EXISTS devices(
         id TEXT PRIMARY KEY, name TEXT NOT NULL, token_hash TEXT NOT NULL UNIQUE,
@@ -1230,6 +1332,50 @@ var WorkspaceDatabase = class {
       CREATE INDEX IF NOT EXISTS audit_time_idx ON audit(time DESC);
       CREATE INDEX IF NOT EXISTS trash_root_idx ON trash(root_id, created_at DESC);
     `);
+		if (!this.hasRootColumn("builtin")) this.db.exec("ALTER TABLE roots ADD COLUMN builtin INTEGER NOT NULL DEFAULT 0");
+		if (this.rootsPathIsUnique()) this.dropRootsUniqueConstraint();
+	}
+	/** `roots.real_path` 上是否还带 UNIQUE 约束。 */
+	rootsPathIsUnique() {
+		const row = this.db.prepare("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'roots'").get();
+		return /real_path\s+TEXT\s+NOT\s+NULL\s+UNIQUE/i.test(row?.sql ?? "");
+	}
+	/**
+	* 重建 `roots` 去掉 UNIQUE。
+	*
+	* 这是一次**有真实数据风险**的操作，所以每一步都写清楚理由：
+	* - `PRAGMA foreign_keys=OFF`：`device_roots.root_id` 引用 `roots(id)`，而重建要
+	*   DROP 掉被引用的那张表。开着外键会直接失败。
+	* - 事务：`new_roots` 建好、数据搬完、**最后**才 DROP 老表并改名。中途失败会整体
+	*   回滚，原表原封不动。
+	* - 搬数据用显式列名而不是 `SELECT *`：老表可能还没有 `builtin` 列（两种迁移顺序
+	*   都可能出现），按列名搬才不会在某一台机器上错位。
+	*/
+	dropRootsUniqueConstraint() {
+		const columns = this.hasRootColumn("builtin") ? "id, label, real_path, created_at, builtin" : "id, label, real_path, created_at, 0 AS builtin";
+		this.db.exec("PRAGMA foreign_keys=OFF");
+		try {
+			this.db.exec("BEGIN IMMEDIATE");
+			this.db.exec(`
+        CREATE TABLE roots_migrated(
+          id TEXT PRIMARY KEY, label TEXT NOT NULL, real_path TEXT NOT NULL,
+          created_at INTEGER NOT NULL, builtin INTEGER NOT NULL DEFAULT 0
+        );
+        INSERT INTO roots_migrated(${columns}) SELECT ${columns} FROM roots;
+        DROP TABLE roots;
+        ALTER TABLE roots_migrated RENAME TO roots;
+      `);
+			this.db.exec("COMMIT");
+		} catch (error) {
+			this.db.exec("ROLLBACK");
+			throw error;
+		} finally {
+			this.db.exec("PRAGMA foreign_keys=ON");
+		}
+	}
+	/** `roots` 表是否已有指定列。 */
+	hasRootColumn(column) {
+		return this.db.prepare("PRAGMA table_info(roots)").all().some((entry) => entry.name === column);
 	}
 };
 function hashSecret(secret) {
@@ -1251,7 +1397,8 @@ function rootFromRow(row) {
 		id: row.id,
 		label: row.label,
 		realPath: row.real_path,
-		createdAt: row.created_at
+		createdAt: row.created_at,
+		...row.builtin === 1 ? { builtin: true } : {}
 	};
 }
 function trashFromRow(row) {
@@ -1268,6 +1415,239 @@ function trashFromRow(row) {
 	};
 }
 //#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/dsh-0.2-bridge.ts
 /**
 * DSH 0.2.x host-service bridge.
@@ -1834,7 +2214,6 @@ function sessionIdOf(summary) {
 * - 解析不出工作目录时退回 DSH 目录（[DEFAULT_IMAGE_HANDOFF_DIR]）——
 *   宁可落到私有目录也不能让「发消息」本身失败。
 */
-const HANDOFF_SUBDIR = ".dsh-images";
 const DEFAULT_IMAGE_HANDOFF_DIR = join(homedir(), ".dsh", "image-handoff");
 const IMAGE_EXTENSIONS = {
 	"image/png": "png",
@@ -1880,33 +2259,30 @@ function writeHandoffFile(dir, workspace, mediaType, data) {
 	};
 }
 /** 交接文件名只允许「内容哈希 + 图片扩展名」：挡住一切路径穿越。 */
-const HANDOFF_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"
-};
+/**
+* 交接文件名的白名单与媒体类型表现在住在 `image-handoff.ts` —— 设置面板、只读图片路由
+* 和这里读的是**同一份**判据，分开写两份迟早漂移。这里只是就近取个别名。
+*/
+const HANDOFF_NAME = HANDOFF_FILE_NAME;
 /**
 * 读出一张交接图片的字节（供手机端把它**显示**出来）。
 *
-* 只接受裸文件名，目录永远由「会话工作目录 + `.dsh-images`」（或兜底目录）推出，
+* 只接受裸文件名，目录永远由「会话工作目录 + <识图路径>」（或兜底目录）推出，
 * 客户端给绝对路径也不认 —— 否则这条读文件的口子会变成任意文件读取。
-* 工作目录与 [writeHandoffFile] 用的是同一套解析，保证「写在哪、从哪读」。
+* 工作目录与 [writeHandoffFile] 用的是同一套解析，保证「写在哪、从哪读」；
+* `<识图路径>` 也来自同一个地方（设置里的当前值），改设置后写读同步跟着走。
+*
+* **导出**是给同源只读图片路由（`image-handoff.ts`）用的：那条路由不校验设备 token，
+* 所以它更需要「目录不由客户端给」这条约束 —— 直接复用这里，而不是另写一套解析。
 */
-async function readHandoffImageFile(host, roots, fallbackDir, sessionId, name) {
+async function readHandoffImageFile(host, roots, fallbackDir, subdir, sessionId, name) {
 	const fileName = name.split(/[/\\]/).pop() ?? name;
 	const match = HANDOFF_NAME.exec(fileName);
 	if (match === null) throw new Error("BAD_HANDOFF_NAME");
 	const ext = (match[1] ?? "").toLowerCase();
 	const mediaType = HANDOFF_MEDIA_TYPES[ext] ?? "application/octet-stream";
 	const workspace = await sessionWorkspaceDir(host, roots, sessionId);
-	const target = [...workspace !== void 0 ? [join(workspace, HANDOFF_SUBDIR, fileName)] : [], join(fallbackDir, fileName)].find((candidate) => existsSync(candidate));
+	const target = [...workspace !== void 0 ? [join(workspace, subdir, fileName)] : [], join(fallbackDir, fileName)].find((candidate) => existsSync(candidate));
 	if (target === void 0) throw new Error("HANDOFF_IMAGE_NOT_FOUND");
 	return {
 		bytes: new Uint8Array(readFileSync(target)),
@@ -1979,12 +2355,12 @@ function handoffLine(index, name, relative, locale) {
 	if (locale === "en") return `🖼️ Image ${index} "${name}" (this model can't see images, saved to ${relative}; to view it, open the path below with an image-reading tool)`;
 	return `🖼️ 图片 ${index}「${name}」（当前模型看不到图，已存到 ${relative}；要看图，请用识图工具打开下面那行的路径）`;
 }
-async function handoffImagesForTextOnlyModel(host, roots, fallbackDir, locale, sessionId, content) {
+async function handoffImagesForTextOnlyModel(host, roots, fallbackDir, subdir, locale, sessionId, content) {
 	if (!content.some((part) => part.type === "image")) return content;
 	try {
 		if (!await modelIsConfirmedTextOnly(host, sessionId)) return content;
 		const workspace = await sessionWorkspaceDir(host, roots, sessionId);
-		const dir = workspace !== void 0 ? join(workspace, HANDOFF_SUBDIR) : fallbackDir;
+		const dir = workspace !== void 0 ? join(workspace, subdir) : fallbackDir;
 		let index = 0;
 		return content.map((part) => {
 			if (part.type !== "image") return part;
@@ -2015,8 +2391,13 @@ function createDsh02ApiProxy(host, options = {}) {
 	const mux = new FrameHub();
 	const hostFrames = new FrameHub();
 	const imageHandoff = options.imageHandoff !== false;
-	const handoffRoots = options.handoffRoots ?? [];
+	const handoffRootsOf = () => {
+		const value = options.handoffRoots;
+		if (value === void 0) return [];
+		return typeof value === "function" ? value() : value;
+	};
 	const imageHandoffDir = options.imageHandoffDir ?? DEFAULT_IMAGE_HANDOFF_DIR;
+	const handoffSubdirOf = options.handoffSubdir ?? (() => ".dsh-images");
 	const fileUploadService = optionalService(host, "fileUploads");
 	const approvals = new ApprovalBridge(host, mux);
 	approvals.attach();
@@ -2120,7 +2501,7 @@ function createDsh02ApiProxy(host, options = {}) {
 				const requestId = randomUUID();
 				const { locale, ...kernelPayload } = request.payload;
 				const receiptIds = request.payload.content.filter((part) => part.type === "file").map((part) => part.receiptId);
-				const content = imageHandoff ? await handoffImagesForTextOnlyModel(host, handoffRoots, imageHandoffDir, locale ?? "zh", request.payload.sessionId, request.payload.content) : request.payload.content;
+				const content = imageHandoff ? await handoffImagesForTextOnlyModel(host, handoffRootsOf(), imageHandoffDir, handoffSubdirOf(), locale ?? "zh", request.payload.sessionId, request.payload.content) : request.payload.content;
 				const binding = receiptIds.length === 0 ? void 0 : await (async () => {
 					if (fileUploadService == null) throw new Error("FILE_UPLOADS_UNAVAILABLE: this DSH build provides no ctx.fileUploads service, so file attachments cannot be sent");
 					return fileUploadService.bindPrompt(await agentFor(request.payload.sessionId), receiptIds, requestId);
@@ -2157,7 +2538,7 @@ function createDsh02ApiProxy(host, options = {}) {
 			}),
 			readHandoffImage: (request) => call(async () => {
 				const { sessionId, name } = request.payload;
-				return readHandoffImageFile(host, handoffRoots, imageHandoffDir, sessionId, name);
+				return readHandoffImageFile(host, handoffRootsOf(), imageHandoffDir, handoffSubdirOf(), sessionId, name);
 			}),
 			cancel: (request) => call(() => host.sessionController.cancel(request.payload)),
 			rename: (request) => call(() => host.sessionController.rename(request.payload)),
@@ -3041,7 +3422,7 @@ async function inspectResolvedPath(root, wirePath) {
 }
 //#endregion
 //#region src/shared/version.ts
-const PLUGIN_VERSION = "2.2.1";
+const PLUGIN_VERSION = "2.3.0";
 //#endregion
 //#region src/host/router.ts
 var ApiRouter = class {
@@ -3639,6 +4020,17 @@ var ApiRouter = class {
 			sendJson(res, 200, { items: this.options.database.listAudit(optionalInteger(url.searchParams.get("limit")) ?? 200) });
 			return;
 		}
+		if (method === "GET" && pathname === "/manage/image") {
+			sendJson(res, 200, imageHandoffView(this.options.database, this.imageFallbackDir()));
+			return;
+		}
+		if (method === "PUT" && pathname === "/manage/image") {
+			const body = await readJson(req, 16384);
+			const subdir = saveHandoffSubdir(this.options.database, body.subdir);
+			this.options.database.audit("admin", "loopback-admin", "image.subdir", void 0, void 0, { subdir }, requestId);
+			sendJson(res, 200, imageHandoffView(this.options.database, this.imageFallbackDir()));
+			return;
+		}
 		const purgeRoute = pathname.match(/^\/manage\/trash\/([^/]+)$/);
 		if (method === "DELETE" && purgeRoute !== null) {
 			await this.options.files.purgeTrash(decodeURIComponent(purgeRoute[1]));
@@ -3736,6 +4128,10 @@ var ApiRouter = class {
 		const roots = this.options.database.listRoots();
 		return principal.rootIds === "all" ? roots : roots.filter((root) => principal.rootIds.has(root.id));
 	}
+	/** 兜底交接目录：没配就用状态目录下的 `image-handoff`（与 `index.ts` 的默认一致）。 */
+	imageFallbackDir() {
+		return this.options.imageFallbackDir ?? path.join(this.options.database.dataDir, "image-handoff");
+	}
 	audit(principal, action, rootId, relativePath, requestId, details = {}) {
 		this.options.database.audit(principal.kind, principal.id, action, rootId, relativePath, details, requestId);
 	}
@@ -4213,12 +4609,12 @@ var RemoteApiServer = class {
 		}
 	}
 };
-function attachEmbeddedRoutes(webServer, router, remote) {
+function attachEmbeddedRoutes(webServer, router, remote, extraRoutes = []) {
 	const disposers = [webServer.register({
 		kind: "prefix",
 		path: "/dsh-workspace-api",
 		handler: (req, res) => router.handle(req, res, "/dsh-workspace-api")
-	})];
+	}), ...extraRoutes.map((route) => webServer.register(route))];
 	return () => {
 		for (const dispose of disposers.reverse()) dispose();
 	};
@@ -4660,15 +5056,25 @@ async function apply(ctx, config = {}) {
 	const maxUploadBytes = config.maxUploadBytes ?? 20971520;
 	if (!Number.isSafeInteger(maxUploadBytes) || maxUploadBytes < 1) throw new Error("dsh-remote-bridge: maxUploadBytes must be positive");
 	const database = new WorkspaceDatabase(dataDir);
+	try {
+		const purged = database.purgeRevokedDevices();
+		if (purged > 0) ctx.logger.info(`dsh-remote-bridge: purged ${purged} revoked device(s)`);
+	} catch (error) {
+		ctx.logger.warn(/* @__PURE__ */ new Error(`dsh-remote-bridge: could not purge revoked devices: ${String(error)}`));
+	}
+	await registerBuiltinWorkspaceRoot(ctx, database);
 	const events = new WorkspaceEventBus();
 	const auth = new AuthService(database);
 	const files = new FileService(database, (event) => events.emit(event));
+	const imageHandoffDir = path.join(dataDir, "image-handoff");
+	const handoffRootsOf = () => database.listRoots().map((root) => ({
+		id: root.id,
+		realPath: root.realPath
+	}));
 	const apiProxy = createDsh02ApiProxy(ctx, {
-		handoffRoots: database.listRoots().map((root) => ({
-			id: root.id,
-			realPath: root.realPath
-		})),
-		imageHandoffDir: path.join(dataDir, "image-handoff")
+		handoffRoots: handoffRootsOf,
+		imageHandoffDir,
+		handoffSubdir: () => readHandoffSubdir(database)
 	});
 	const chat = new DshChatAdapter(apiProxy, database, {
 		agents: ctx.agents,
@@ -4692,7 +5098,8 @@ async function apply(ctx, config = {}) {
 		chat,
 		settings,
 		remote,
-		maxUploadBytes
+		maxUploadBytes,
+		imageFallbackDir: imageHandoffDir
 	});
 	try {
 		await remote.start();
@@ -4700,7 +5107,12 @@ async function apply(ctx, config = {}) {
 		database.close();
 		throw error;
 	}
-	const disposeEmbedded = attachEmbeddedRoutes(ctx.webServer, router, remote);
+	const imageRoute = createImageRouteHandler({ read: (sessionId, name) => readHandoffImageFile(ctx, handoffRootsOf(), imageHandoffDir, readHandoffSubdir(database), sessionId, name) });
+	const disposeEmbedded = attachEmbeddedRoutes(ctx.webServer, router, remote, [{
+		kind: "prefix",
+		path: IMAGE_ROUTE,
+		handler: imageRoute
+	}]);
 	ctx.effect(() => async () => {
 		disposeEmbedded();
 		await remote.stop();
@@ -4709,5 +5121,33 @@ async function apply(ctx, config = {}) {
 	const status = remote.status();
 	ctx.logger.info(`dsh-remote-bridge v${PLUGIN_VERSION}: ${status.host}:${status.port} (${status.remoteEnabled ? "remote enabled" : "loopback only"})`);
 }
+/**
+* 登记「DSH 工作区」为内置授权根。
+*
+* 取 `ctx.workspaceRegistry.list()` 的**第一个**工作区（用户明确要「只显示第一个」），
+* 登记成一条 `builtin` 根。四个必须静默失败的情形 —— 插件启动不该因为一个「锦上添花的
+* 默认根」而整个起不来：
+*
+* - 没有工作区（用户从没建过）：什么都不做；
+* - 第一个工作区的路径已经不存在（用户把它删了）：什么都不做，否则留下一条指向虚空的
+*   授权根，手机浏览时一路报错，比不显示更糟；
+* - 注册表自己抛了：同上，记一条 warn 就走。
+*
+* 目录存在性用 `stat` 判，且必须是**目录**而不是文件 —— `canonicalRoot` 之后如果指向一个
+* 普通文件，后续列目录会一路报错。
+*/
+async function registerBuiltinWorkspaceRoot(ctx, database) {
+	try {
+		const workspace = ctx.workspaceRegistry.list()[0];
+		if (workspace === void 0) return;
+		const target = workspace.path?.trim();
+		if (target === void 0 || target === "") return;
+		if (!(await stat(target)).isDirectory()) return;
+		const root = await database.ensureBuiltinRoot(target, workspace.title?.trim() || "DSH 工作区");
+		if (root !== void 0) ctx.logger.info(`dsh-remote-bridge: registered the DSH workspace as a built-in root: ${root.realPath}`);
+	} catch (error) {
+		ctx.logger.warn(/* @__PURE__ */ new Error(`dsh-remote-bridge: could not register the DSH workspace root: ${String(error)}`));
+	}
+}
 //#endregion
 export { apply, apply as default, inject, name };