@linxin666/dsh-remote-web-ui 0.2.3 → 0.2.5

package/lib/index.js

@@ -1,18 +1,20 @@
 import { createRequire } from "node:module";
-import { setInterval as setInterval$1 } from "node:timers";
+import { dirname, isAbsolute, join } from "node:path";
+import { setInterval as setInterval$1, setTimeout as setTimeout$1 } from "node:timers";
 import { Service } from "@deepseek-ai/cordis";
 import z from "schemastery";
 import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { homedir, networkInterfaces } from "node:os";
 import { z as z$1 } from "zod";
 import { readFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { RpcId } from "@deepseek-ai/dsh-host-apiproxy/api/rpc";
-import { networkInterfaces } from "node:os";
+import http, { request } from "node:http";
+import { connect } from "node:net";
 import { Tunnel, bin, install } from "cloudflared";
 import { spawn } from "node:child_process";
-//#region ../../node_modules/.pnpm/@deepseek-ai+dsh-settings@0.1.0-rc.7_@deepseek-ai+cordis@4.0.1_@deepseek-ai+dsh-brand@0_6b0eb868fb92d854799855c05c5fa43c/node_modules/@deepseek-ai/dsh-settings/lib/index.js
+//#region ../../node_modules/.pnpm/@deepseek-ai+dsh-settings@0.1.0-rc.8_@deepseek-ai+cordis@4.0.1_@deepseek-ai+dsh-brand@0_7616943ecf171cb97db9e2088de3356f/node_modules/@deepseek-ai/dsh-settings/lib/index.js
 /**
 * Structural secret redaction for settings values. `role('secret')` fields are
 * removed from a value before it crosses a wire boundary; a sidecar records
@@ -225,7 +227,13 @@ function installSettingsSection(ctx, ns, schema, entry, hooks) {
 *   unknown one (no oracle for validity).
 * - `stop()` revokes every device session and clears the token, so paired
 *   devices are cut off on their next gated request.
+* - `revoke()` drops one device session; idle sessions older than
+*   `idleExpireMs` are deleted on sweep, load, and the next gated request.
 */
+/** Default idle-expiry window: 7 days without heartbeat or a gated request. */
+const DEFAULT_IDLE_EXPIRE_MS = 10080 * 60 * 1e3;
+/** Cap on the persisted/displayed User-Agent string. */
+const MAX_USER_AGENT_CHARS = 180;
 /** Thrown by issue() for an address outside the sampled LAN literals. */
 var UnknownLanAddressError = class extends Error {
 	/**
@@ -262,6 +270,9 @@ var PairingService = class {
 	publicBase;
 	/** Auto-tunnel status, while the auto-tunnel feature is active. */
 	tunnelStatus;
+	posture;
+	/** True when lastSeenAt changed since the last persist (flushed on sweep). */
+	dirty = false;
 	/**
 	* @param config - tunables. The settings surface replaces the object (a
 	* fresh literal) when a committed section changes; every operation reads
@@ -287,14 +298,17 @@ var PairingService = class {
 			for (const [deviceId, session] of Object.entries(saved)) {
 				if (typeof deviceId !== "string") continue;
 				if (typeof session !== "object" || session === null) continue;
-				const { createdAt, lastSeenAt } = session;
+				const { createdAt, lastSeenAt, userAgent } = session;
 				if (typeof createdAt !== "number" || typeof lastSeenAt !== "number") continue;
+				const label = typeof userAgent === "string" ? sanitizeUserAgent(userAgent) : void 0;
 				this.devices.set(deviceId, {
 					createdAt,
-					lastSeenAt
+					lastSeenAt,
+					...label !== void 0 ? { userAgent: label } : {}
 				});
 			}
 			this.clampToMaxDevices();
+			if (this.evictIdle()) this.persist();
 		} catch {}
 	}
 	/** FIFO-cap the device table (a persisted file may outlive a lowered cap). */
@@ -304,12 +318,22 @@ var PairingService = class {
 		const ordered = [...this.devices.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt);
 		for (const [id] of ordered.slice(0, overflow)) this.devices.delete(id);
 	}
+	/** Drop sessions whose lastSeenAt is older than idleExpireMs. */
+	evictIdle() {
+		const now = this.clock.now();
+		const limit = this.config.idleExpireMs ?? 6048e5;
+		let removed = false;
+		for (const [id, session] of [...this.devices]) if (now - session.lastSeenAt > limit) {
+			this.devices.delete(id);
+			removed = true;
+		}
+		return removed;
+	}
 	/**
 	* Write the current device table to the configured file. Called on the
-	* mutation boundaries that change the set of live sessions (accept and
-	* stop); `lastSeenAt` refreshes are deliberately not persisted here so a
-	* per-request write storm is avoided — after a restart the phone's first
-	* heartbeat re-warms its own session.
+	* mutation boundaries that change the set of live sessions (accept, stop,
+	* revoke, idle eviction) and, throttled, from sweep() so lastSeenAt
+	* survives a restart without a write per request.
 	*
 	* Device ids are session credentials (the gate authorizes requests by the
 	* cookie's device id), so the file is written 0600 via a temp file and
@@ -321,8 +345,11 @@ var PairingService = class {
 		try {
 			mkdirSync(dirname(file), { recursive: true });
 			const temp = `${file}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
-			writeFileSync(temp, JSON.stringify(Object.fromEntries(this.devices)), { mode: 384 });
+			const payload = {};
+			for (const [id, session] of this.devices) payload[id] = session;
+			writeFileSync(temp, JSON.stringify(payload), { mode: 384 });
 			renameSync(temp, file);
+			this.dirty = false;
 		} catch (error) {
 			console.error("remote-web-ui: failed to persist paired devices", error);
 		}
@@ -358,6 +385,11 @@ var PairingService = class {
 		this.tunnelStatus = status;
 		this.notify();
 	}
+	/** Set the latest /api posture probe result (see posture.ts). */
+	setPosture(snapshot) {
+		this.posture = snapshot;
+		this.notify();
+	}
 	/**
 	* Issue a fresh token, replacing (invalidating) any previous one. A
 	* stopped service re-arms through this call (the panel's refresh button).
@@ -397,9 +429,10 @@ var PairingService = class {
 	* successful call for the same token is impossible because the first
 	* consumes it.
 	* @param token - the token secret from the QR link.
+	* @param userAgent - optional User-Agent header captured at accept.
 	* @returns the new device id, or a refusal code.
 	*/
-	accept(token) {
+	accept(token, userAgent) {
 		const record = this.tokens.get(token);
 		if (record === void 0 || record.consumed || this.stopped || this.clock.now() > record.expiresAt) return {
 			ok: false,
@@ -416,9 +449,11 @@ var PairingService = class {
 			};
 			if (oldest !== void 0) this.devices.delete(oldest.id);
 		}
+		const label = sanitizeUserAgent(userAgent);
 		this.devices.set(deviceId, {
 			createdAt: now,
-			lastSeenAt: now
+			lastSeenAt: now,
+			...label !== void 0 ? { userAgent: label } : {}
 		});
 		this.persist();
 		this.notify();
@@ -440,16 +475,30 @@ var PairingService = class {
 		this.notify();
 	}
 	/**
+	* Revoke one paired device. The next gated request from that cookie is
+	* refused; other sessions stay live. Unknown ids are a no-op.
+	* @param deviceId - the cookie value of the device to drop.
+	* @returns true when a live session was removed.
+	*/
+	revoke(deviceId) {
+		if (this.stopped) return false;
+		if (!this.devices.delete(deviceId)) return false;
+		this.persist();
+		this.notify();
+		return true;
+	}
+	/**
 	* The api/gate path: record activity for a device id and report whether
 	* the request may proceed. Unknown or revoked ids (including any device
-	* after stop()) are refused.
+	* after stop() or idle expiry) are refused.
 	* @param deviceId - the cookie value of the requesting device.
 	* @returns true when the device session is live and was refreshed.
 	*/
 	touchDevice(deviceId) {
-		const session = this.devices.get(deviceId);
-		if (session === void 0 || this.stopped) return false;
+		const session = this.liveSession(deviceId);
+		if (session === void 0) return false;
 		session.lastSeenAt = this.clock.now();
+		this.dirty = true;
 		this.notify();
 		return true;
 	}
@@ -458,17 +507,20 @@ var PairingService = class {
 		return this.touchDevice(deviceId);
 	}
 	/**
-	* Periodic sweep: re-evaluate the derived snapshot (a device aging past
-	* the offline window flips the phase to disconnected). Emits only when
-	* the snapshot actually changed.
+	* Periodic sweep: drop idle sessions, flush a dirty lastSeenAt, and
+	* re-evaluate the derived snapshot (a device aging past the offline
+	* window flips the phase to disconnected). Emits only when the snapshot
+	* actually changed.
 	*/
 	sweep() {
+		if (this.evictIdle() || this.dirty) this.persist();
 		this.notify();
 	}
 	/** The current snapshot (fresh object per call — stable between emits). */
 	snapshot() {
 		const now = this.clock.now();
-		const onlineCount = [...this.devices.values()].filter((session) => this.isOnlineAt(session, now)).length;
+		const devices = [...this.devices.entries()].sort((a, b) => a[1].createdAt - b[1].createdAt).map(([id, session]) => this.toDeviceSnapshot(id, session, now));
+		const onlineCount = devices.filter((device) => device.online).length;
 		const token = this.activeToken();
 		return {
 			phase: this.derivePhase(onlineCount, token !== void 0),
@@ -476,17 +528,19 @@ var PairingService = class {
 			lanAddresses: [...this.lanBases.keys()],
 			...this.publicBase !== void 0 ? { publicUrl: this.publicBase } : {},
 			...this.tunnelStatus !== void 0 ? { tunnel: this.tunnelStatus } : {},
+			...this.posture !== void 0 ? { posture: this.posture } : {},
 			...token !== void 0 ? {
 				tokenId: token.record.id,
 				tokenExpiresAt: token.record.expiresAt
 			} : {},
 			deviceCount: this.devices.size,
-			onlineCount
+			onlineCount,
+			devices
 		};
 	}
-	/** Whether a cookie value names a currently live device session. */
+	/** Whether a cookie value names a currently live (non-idle) device session. */
 	hasDevice(deviceId) {
-		return this.devices.get(deviceId) !== void 0 && !this.stopped;
+		return this.liveSession(deviceId) !== void 0;
 	}
 	/** Subscribe to snapshot changes (each emit passes a fresh snapshot). */
 	onState(listener) {
@@ -505,6 +559,32 @@ var PairingService = class {
 			};
 		}
 	}
+	/**
+	* Return a live session, deleting it first when idle-expired. Side-effecting
+	* so a stale cookie cannot pass the gate between sweeps.
+	*/
+	liveSession(deviceId) {
+		if (this.stopped) return void 0;
+		const session = this.devices.get(deviceId);
+		if (session === void 0) return void 0;
+		const limit = this.config.idleExpireMs ?? 6048e5;
+		if (this.clock.now() - session.lastSeenAt > limit) {
+			this.devices.delete(deviceId);
+			this.persist();
+			this.notify();
+			return;
+		}
+		return session;
+	}
+	toDeviceSnapshot(id, session, now) {
+		return {
+			id,
+			createdAt: session.createdAt,
+			lastSeenAt: session.lastSeenAt,
+			online: this.isOnlineAt(session, now),
+			...session.userAgent !== void 0 ? { userAgent: session.userAgent } : {}
+		};
+	}
 	derivePhase(onlineCount, hasToken) {
 		if (this.lanBases.size === 0 && this.publicBase === void 0) return "lan-required";
 		if (this.stopped) return "stopped";
@@ -529,7 +609,14 @@ var PairingService = class {
 };
 /** Structural equality over the snapshot's wire fields. */
 function snapshotsEqual(a, b) {
-	return a.phase === b.phase && a.lanAvailable === b.lanAvailable && sameStrings(a.lanAddresses, b.lanAddresses) && a.publicUrl === b.publicUrl && tunnelEqual(a.tunnel, b.tunnel) && a.tokenId === b.tokenId && a.tokenExpiresAt === b.tokenExpiresAt && a.deviceCount === b.deviceCount && a.onlineCount === b.onlineCount;
+	return a.phase === b.phase && a.lanAvailable === b.lanAvailable && sameStrings(a.lanAddresses, b.lanAddresses) && a.publicUrl === b.publicUrl && tunnelEqual(a.tunnel, b.tunnel) && a.tokenId === b.tokenId && a.tokenExpiresAt === b.tokenExpiresAt && a.deviceCount === b.deviceCount && a.onlineCount === b.onlineCount && devicesEqual(a.devices, b.devices);
+}
+/** Per-device roster equality (order is pairing time). */
+function devicesEqual(a, b) {
+	return a.length === b.length && a.every((device, index) => {
+		const other = b[index];
+		return other !== void 0 && device.id === other.id && device.createdAt === other.createdAt && device.lastSeenAt === other.lastSeenAt && device.online === other.online && device.userAgent === other.userAgent;
+	});
 }
 /** Tunnel frame equality (undefined equals undefined; fields compared shallowly). */
 function tunnelEqual(a, b) {
@@ -539,6 +626,44 @@ function tunnelEqual(a, b) {
 function sameStrings(a, b) {
 	return a.length === b.length && a.every((value, index) => value === b[index]);
 }
+/** Strip control characters and cap the User-Agent stored with a session. */
+function sanitizeUserAgent(raw) {
+	if (raw === void 0) return void 0;
+	const cleaned = raw.replace(/[\u0000-\u001F\u007F]/g, " ").replace(/\s+/g, " ").trim();
+	if (cleaned === "") return void 0;
+	return cleaned.length <= MAX_USER_AGENT_CHARS ? cleaned : cleaned.slice(0, MAX_USER_AGENT_CHARS);
+}
+//#endregion
+//#region src/dsh-home.ts
+/**
+* DSH_HOME resolution shared by the plugin family's Host halves: the
+* environment override wins, the platform home fallback follows. Mirrors
+* what dsh-pet and dsh-liangshen each used to implement locally.
+*/
+/** Expand a leading ~ (or ~user) in a path, platform-style. */
+function expandHome(path, home = homedir()) {
+	if (path === "~") return home;
+	if (path.startsWith("~/") || path.startsWith("~\\")) return join(home, path.slice(2));
+	return path;
+}
+/**
+* Resolve the DSH home directory.
+* @param env - process environment to read DSH_HOME from.
+* @param home - platform home directory fallback (test seam).
+* @returns the absolute DSH home path.
+*/
+function resolveDshHome(env = process.env, home = homedir()) {
+	const raw = env.DSH_HOME;
+	if (raw !== void 0 && raw.trim() !== "") {
+		const expanded = expandHome(raw.trim(), home);
+		return isAbsolute(expanded) ? expanded : join(process.cwd(), expanded);
+	}
+	return join(home, ".dsh");
+}
+/** Resolve the DSH home directory from the live environment. */
+function dshHome() {
+	return resolveDshHome();
+}
 //#endregion
 //#region src/loopback.ts
 /** IPv4 127/8 predicate (four decimal octets, first == 127). */
@@ -756,6 +881,7 @@ const PAIR_PATHS = {
 	issue: "/api/pair/issue",
 	accept: "/api/pair/accept",
 	stop: "/api/pair/stop",
+	revoke: "/api/pair/revoke",
 	heartbeat: "/api/pair/heartbeat",
 	status: "/api/pair/status",
 	events: "/api/pair/events"
@@ -773,6 +899,7 @@ const issuePayloadSchema = z$1.object({
 	address: z$1.string().min(1).optional()
 });
 const acceptPayloadSchema = z$1.object({ token: z$1.string().default("") });
+const revokePayloadSchema = z$1.object({ deviceId: z$1.string().min(1) });
 const pairActionPayloadSchema = z$1.object({}).passthrough();
 /**
 * Parse a pair request body through schema. A missing/empty or non-object
@@ -950,7 +1077,8 @@ function makeRoutes(deps) {
 			});
 			return;
 		}
-		const result = service.accept(payload.token);
+		const ua = req.headers["user-agent"];
+		const result = service.accept(payload.token, typeof ua === "string" ? ua : void 0);
 		if (!result.ok) {
 			writeJson(res, result.code === "used" ? 409 : 404, {
 				ok: false,
@@ -987,6 +1115,33 @@ function makeRoutes(deps) {
 		service.stop();
 		writeJson(res, 200, { ok: true });
 	};
+	const handleRevoke = async (req, res) => {
+		if (!requireMethod(req, res, "POST")) return;
+		if (!loopbackFence(req)) {
+			writeJson(res, 403, {
+				ok: false,
+				code: "forbidden"
+			});
+			return;
+		}
+		const body = await readJsonBody$1(req);
+		const payload = parsePairPayload(revokePayloadSchema, body);
+		if (payload === void 0) {
+			writeJson(res, 400, {
+				ok: false,
+				code: "bad-payload"
+			});
+			return;
+		}
+		if (!service.revoke(payload.deviceId)) {
+			writeJson(res, 404, {
+				ok: false,
+				code: "unknown-device"
+			});
+			return;
+		}
+		writeJson(res, 200, { ok: true });
+	};
 	const handleHeartbeat = async (req, res) => {
 		if (!requireMethod(req, res, "POST")) return;
 		if (!lanFence(req)) {
@@ -1026,10 +1181,11 @@ function makeRoutes(deps) {
 		const deviceId = readCookie(req.headers.cookie, service.config.cookieName);
 		const paired = deviceId !== void 0 && service.hasDevice(deviceId);
 		const snapshot = service.snapshot();
+		const { devices: _devices, ...rest } = snapshot;
 		writeJson(res, 200, {
 			ok: true,
 			paired,
-			...paired ? snapshot : {
+			...paired ? rest : {
 				phase: snapshot.phase,
 				lanAvailable: snapshot.lanAvailable,
 				lanAddresses: snapshot.lanAddresses
@@ -1064,6 +1220,11 @@ function makeRoutes(deps) {
 			path: PAIR_PATHS.stop,
 			handler: handleStop
 		},
+		{
+			kind: "exact",
+			path: PAIR_PATHS.revoke,
+			handler: handleRevoke
+		},
 		{
 			kind: "exact",
 			path: PAIR_PATHS.heartbeat,
@@ -1117,7 +1278,7 @@ function pageHtml(bundleUrl) {
 		"<meta name=\"apple-mobile-web-app-title\" content=\"DSH Remote\">",
 		"<link rel=\"manifest\" href=\"/m/manifest.webmanifest\">",
 		"<link rel=\"apple-touch-icon\" href=\"/m/apple-touch-icon.png\">",
-		"<title>移动端远程控制</title>",
+		"<title>远程访问</title>",
 		"</head>",
 		"<body>",
 		"<div id=\"root\"></div>",
@@ -1319,7 +1480,8 @@ function makeMobileRoutes() {
 * note the paired-device cookie also passes the global api/gate for the full
 * ApiProxy surface (gate.ts), so a paired phone is a full-control credential:
 * the allowlist only constrains this /m/api proxy, not the cookie's reach.
-* stop() revokes every device; there is no per-device revocation yet.
+* stop() revokes every device; the loopback panel can also revoke one
+* device at a time.
 */
 const MOBILE_ALLOWLIST = /* @__PURE__ */ new Set([
 	"workspace.list",
@@ -1559,7 +1721,11 @@ async function dispatch(apiProxy, method, payload, rpcId, signal) {
 	};
 	if (method === "session.list") {
 		const full = await apiProxy.sessions.list(request);
-		if (!full.result.ok) return full;
+		if (!full.result.ok) return {
+			type: "server-response",
+			rpcId,
+			result: full.result
+		};
 		const items = full.result.value.items;
 		const cursor = payload?.cursor;
 		items.sort((a, b) => b.updatedAt - a.updatedAt || (a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0));
@@ -1599,6 +1765,421 @@ async function dispatch(apiProxy, method, payload, rpcId, signal) {
 	throw new Error(`unhandled allowlisted method ${method}`);
 }
 //#endregion
+//#region src/loopback-proxy.ts
+/** WebSocket handshake headers forwarded to the loopback upstream. */
+const WS_FORWARD_HEADERS = [
+	"sec-websocket-key",
+	"sec-websocket-version",
+	"sec-websocket-extensions",
+	"sec-websocket-protocol"
+];
+/** Response headers copied from the loopback upstream (no hop-by-hop). */
+const HTTP_FORWARD_RESPONSE_HEADERS = [
+	"content-type",
+	"content-length",
+	"content-disposition",
+	"cache-control",
+	"etag",
+	"last-modified"
+];
+/**
+* Pipe one HTTP request to loopback and stream the response back.
+* @param req - the already-gated outer request.
+* @param res - the outer response.
+* @param port - local webServer port.
+* @param upstreamPath - path + query on 127.0.0.1 (must start with `/`).
+*/
+function proxyLoopbackHttp(req, res, port, upstreamPath) {
+	const headers = {
+		host: `127.0.0.1:${String(port)}`,
+		"sec-fetch-site": "same-origin"
+	};
+	const contentType = req.headers["content-type"];
+	if (typeof contentType === "string") headers["content-type"] = contentType;
+	const contentLength = req.headers["content-length"];
+	if (typeof contentLength === "string") headers["content-length"] = contentLength;
+	const accept = req.headers.accept;
+	if (typeof accept === "string") headers.accept = accept;
+	const upstream = request({
+		host: "127.0.0.1",
+		port,
+		path: upstreamPath,
+		method: req.method,
+		headers
+	}, (upstreamRes) => {
+		const out = {};
+		for (const name of HTTP_FORWARD_RESPONSE_HEADERS) {
+			const value = upstreamRes.headers[name];
+			if (value !== void 0) out[name] = value;
+		}
+		res.writeHead(upstreamRes.statusCode ?? 502, out);
+		upstreamRes.pipe(res);
+	});
+	upstream.on("error", () => {
+		if (!res.headersSent) {
+			writeJson(res, 502, {
+				ok: false,
+				error: {
+					code: "upstream-failure",
+					message: "upstream request failed"
+				}
+			});
+			return;
+		}
+		res.destroy();
+	});
+	req.pipe(upstream);
+}
+/**
+* Rebuild a WebSocket handshake as loopback-shaped and pipe both directions.
+* @param req - the already-gated upgrade request.
+* @param socket - the client duplex.
+* @param head - bytes already read past the handshake.
+* @param port - local webServer port.
+* @param upstreamPath - path + query on 127.0.0.1.
+*/
+function proxyLoopbackUpgrade(req, socket, head, port, upstreamPath) {
+	const lines = [
+		`GET ${upstreamPath} HTTP/1.1`,
+		`Host: 127.0.0.1:${String(port)}`,
+		"Upgrade: websocket",
+		"Connection: Upgrade"
+	];
+	for (const name of WS_FORWARD_HEADERS) {
+		const value = req.headers[name];
+		if (value === void 0) continue;
+		lines.push(`${name}: ${Array.isArray(value) ? value.join(", ") : value}`);
+	}
+	const handshake = `${lines.join("\r\n")}\r\n\r\n`;
+	const upstream = connect(port, "127.0.0.1");
+	const tearDown = () => {
+		upstream.destroy();
+		socket.destroy();
+	};
+	upstream.on("error", tearDown);
+	socket.on("error", tearDown);
+	upstream.on("close", () => {
+		socket.destroy();
+	});
+	socket.on("close", () => {
+		upstream.destroy();
+	});
+	upstream.on("connect", () => {
+		upstream.write(handshake);
+		if (head.length > 0) upstream.write(head);
+		socket.pipe(upstream);
+		upstream.pipe(socket);
+	});
+}
+//#endregion
+//#region src/remote-methods.ts
+/**
+* Remote desktop channel constants — SDK-independent so tests and the
+* client half can pin them without importing the host SDK graph.
+*/
+/** Gated mirror of same-origin fenced paths (`/remote` + original pathname). */
+const REMOTE_PREFIX = "/remote";
+/** Connection-plugin method prefix under the gated channel. */
+const REMOTE_API_PREFIX = `${REMOTE_PREFIX}/api`;
+/** WebSocket event-stream paths served by the channel (client rewrites to these). */
+const REMOTE_API_PATHS = {
+	mux: `${REMOTE_API_PREFIX}/events.mux`,
+	host: `${REMOTE_API_PREFIX}/events.host`
+};
+/**
+* Exact upgrade paths registered on webServer (the SDK matches upgrades by
+* exact path, not prefix). Query strings ride on the request URL.
+*/
+const REMOTE_UPGRADE_PATHS = [
+	REMOTE_API_PATHS.mux,
+	REMOTE_API_PATHS.host,
+	`${REMOTE_PREFIX}/sidebar/ws/terminal`,
+	`${REMOTE_PREFIX}/sidebar/ws/agent-terminals`,
+	`${REMOTE_API_PREFIX}/dsh-ssh/terminal`
+];
+/**
+* Loopback-only methods of the host API surface, mirrored from
+* client-connection's `PRIVILEGED_METHODS` (pinned by
+* tests/remote-contract.spec.ts against the installed SDK). They stay
+* unreachable from a paired remote desktop, matching the SDK's own stance
+* that the configuration plane is loopback-same-origin only.
+*/
+const LOOPBACK_ONLY_METHODS = /* @__PURE__ */ new Set([
+	"agentPreset.read",
+	"agentPreset.copy",
+	"agentPreset.openDocument",
+	"agentPreset.remove",
+	"host.pickDirectory",
+	"host.openPath",
+	"settings.describe",
+	"settings.openDocument",
+	"settings.update",
+	"settings.replace",
+	"settings.mutate",
+	"credentials.describe",
+	"credentials.set",
+	"credentials.unset",
+	"llm.discoverModels"
+]);
+//#endregion
+//#region src/remote-api.ts
+const ALLOWED_METHODS = /* @__PURE__ */ new Set([
+	"GET",
+	"HEAD",
+	"POST",
+	"PUT",
+	"PATCH",
+	"DELETE"
+]);
+/** Reject traversal and empty segments; allow plugin file-path characters. */
+function isSafeSegment(segment) {
+	if (segment === "") return false;
+	let decoded;
+	try {
+		decoded = decodeURIComponent(segment);
+	} catch {
+		return false;
+	}
+	return decoded !== "." && decoded !== ".." && !decoded.includes("/") && !decoded.includes("\\") && !decoded.includes("\0");
+}
+/** One SDK-shaped error envelope (keeps the desktop client's parse path intact). */
+function envelopeError(res, status, rpcId, code, message) {
+	writeJson(res, status, {
+		type: "server-response",
+		rpcId,
+		result: {
+			ok: false,
+			error: {
+				code,
+				message,
+				details: { issues: [] }
+			}
+		}
+	});
+}
+/**
+* Map `/remote/...` to the inner path, or undefined when the outer path is
+* not a safe rewrite target.
+*/
+function innerPathOf(pathname) {
+	if (pathname === "/remote" || pathname === `/remote/`) return void 0;
+	if (!pathname.startsWith(`/remote/`)) return void 0;
+	const rest = pathname.slice(7);
+	if (!rest.startsWith("/")) return void 0;
+	const segments = rest.slice(1).split("/");
+	if (segments.length === 0 || segments.some((segment) => !isSafeSegment(segment))) return;
+	return rest;
+}
+/**
+* Whether a paired inner path must stay physically local.
+* @returns a denial message, or undefined when the path may be proxied.
+*/
+function loopbackOnlyDenial(innerPath) {
+	if (innerPath === "/api/pair" || innerPath.startsWith("/api/pair/")) return "pairing endpoints stay loopback-only and stay unreachable from a paired remote desktop";
+	if (innerPath === "/api/update" || innerPath.startsWith("/api/update/")) return "update endpoints stay loopback-only and stay unreachable from a paired remote desktop";
+	if (innerPath === "/api/plugin-manager" || innerPath.startsWith(`/api/plugin-manager/`)) return "plugin-manager stays loopback-only and stays unreachable from a paired remote desktop";
+	if (innerPath === "/api/dsh-desktop-launcher" || innerPath.startsWith(`/api/dsh-desktop-launcher/`)) return "desktop-launcher endpoints stay loopback-only and stay unreachable from a paired remote desktop";
+	if (innerPath === "/api/dsh-web-ui-settings" || innerPath.startsWith(`/api/dsh-web-ui-settings/`)) return "settings-bridge endpoints stay loopback-only and stay unreachable from a paired remote desktop";
+	if (!innerPath.startsWith("/api/")) return void 0;
+	const method = innerPath.slice(5);
+	if (method !== "" && !method.includes("/") && LOOPBACK_ONLY_METHODS.has(method)) return `${method} is loopback-only and stays unreachable from a paired remote desktop`;
+}
+/**
+* Build the remote desktop channel HTTP routes.
+* @param deps - pairing service + local port.
+* @returns the routes to register on webServer.
+*/
+function makeRemoteApiRoutes(deps) {
+	const { service, port } = deps;
+	const handler = (req, res) => {
+		const deviceId = readCookie(req.headers.cookie, service.config.cookieName);
+		if (!(deviceId !== void 0 && service.touchDevice(deviceId))) {
+			req.resume();
+			envelopeError(res, 403, "invalid-request", "unpaired", "this device is not paired with the desktop");
+			return;
+		}
+		const method = req.method ?? "GET";
+		if (!ALLOWED_METHODS.has(method)) {
+			req.resume();
+			res.writeHead(405).end();
+			return;
+		}
+		const url = new URL(req.url ?? "/", "http://127.0.0.1");
+		const inner = innerPathOf(url.pathname);
+		if (inner === void 0) {
+			req.resume();
+			res.writeHead(404).end();
+			return;
+		}
+		const denied = loopbackOnlyDenial(inner);
+		if (denied !== void 0) {
+			req.resume();
+			envelopeError(res, 403, "invalid-request", "forbidden", denied);
+			return;
+		}
+		proxyLoopbackHttp(req, res, port, `${inner}${url.search}`);
+	};
+	return [{
+		kind: "prefix",
+		path: REMOTE_PREFIX,
+		handler
+	}];
+}
+/**
+* Map one outer upgrade URL onto the loopback path (query string included).
+*/
+function upgradeInnerPath(reqUrl, fallbackPath) {
+	if (reqUrl === void 0 || reqUrl === "") return fallbackPath;
+	let url;
+	try {
+		url = new URL(reqUrl, "http://127.0.0.1");
+	} catch {
+		return fallbackPath;
+	}
+	const inner = innerPathOf(url.pathname);
+	if (inner === void 0) return fallbackPath;
+	return `${inner}${url.search}`;
+}
+/**
+* Build the WebSocket upgrade routes for the event streams and known plugin
+* sockets. webServer matches upgrades by exact path.
+* @param deps - pairing service + local port.
+* @returns the upgrade routes to register on webServer.
+*/
+function makeRemoteApiUpgradeRoutes(deps) {
+	const { service, port } = deps;
+	const handlerFor = (fallbackPath) => (req, socket, head) => {
+		const deviceId = readCookie(req.headers.cookie, service.config.cookieName);
+		if (deviceId === void 0 || !service.touchDevice(deviceId)) {
+			socket.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+			socket.destroy();
+			return;
+		}
+		const inner = upgradeInnerPath(req.url, fallbackPath);
+		if (loopbackOnlyDenial(inner.split("?")[0] ?? inner) !== void 0) {
+			socket.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
+			socket.destroy();
+			return;
+		}
+		proxyLoopbackUpgrade(req, socket, head, port, inner);
+	};
+	return REMOTE_UPGRADE_PATHS.map((path) => ({
+		path,
+		handler: handlerFor(path.slice(7))
+	}));
+}
+//#endregion
+//#region src/posture.ts
+/**
+* Build the forged Host values to probe: the public base authority (host or
+* host:port as written in the URL) plus every LAN base literal.
+* @param publicBaseUrl - the configured public base URL (or undefined).
+* @param lanAddresses - the LAN interface addresses the QR advertises.
+* @param port - the local webServer port (LAN hosts are probed as host:port).
+* @returns Host header values, de-duplicated.
+*/
+function postureTargets(publicBaseUrl, lanAddresses, port) {
+	const targets = [];
+	if (publicBaseUrl !== void 0) try {
+		const url = new URL(publicBaseUrl);
+		const authority = url.port === "" ? url.hostname : `${url.hostname}:${url.port}`;
+		if (authority !== "") targets.push(authority);
+	} catch {}
+	for (const address of lanAddresses) targets.push(`${address}:${String(port)}`);
+	return [...new Set(targets)];
+}
+const defaultRequest = (options, onStatus) => {
+	const request = http.request(options, (response) => {
+		onStatus(response.statusCode ?? 0);
+	});
+	request.on("error", () => {
+		onStatus(0);
+	});
+	return request;
+};
+/**
+* Probe one forged Host against the local `/api` fence.
+* @param port - the local webServer port.
+* @param hostHeader - the Host header to forge.
+* @param request - transport seam.
+* @param timeoutMs - give up after this long (counts as not exposed; the
+* fence being unreachable is not evidence it is open).
+* @returns true when the probe got past the fence.
+*/
+async function probeHost(port, hostHeader, request, timeoutMs) {
+	return await new Promise((resolve) => {
+		let settled = false;
+		const finish = (exposed) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			handle.destroy();
+			resolve(exposed);
+		};
+		const handle = request({
+			host: "127.0.0.1",
+			port,
+			method: "POST",
+			path: "/api/session.list",
+			headers: {
+				host: hostHeader,
+				"content-type": "application/json"
+			},
+			timeout: timeoutMs
+		}, (status) => {
+			finish(status !== 403);
+		});
+		const timer = setTimeout(() => {
+			finish(false);
+		}, timeoutMs + 1e3);
+		handle.on("error", () => {
+			finish(false);
+		});
+		handle.end("{}");
+	});
+}
+/**
+* Run one posture probe round.
+* @returns the snapshot for this round.
+*/
+async function probePosture(options) {
+	const { port, targets } = options;
+	const request = options.request ?? defaultRequest;
+	const timeoutMs = options.timeoutMs ?? 3e3;
+	const now = options.now ?? (() => Date.now());
+	const hosts = [];
+	for (const target of targets) hosts.push({
+		host: target,
+		exposed: await probeHost(port, target, request, timeoutMs)
+	});
+	return {
+		checkedAt: now(),
+		hosts
+	};
+}
+/**
+* Reserve an advertised-target key so a second trigger with the same set
+* does not overlap an in-flight round. Pair with {@link releasePostureKey}
+* on failure — otherwise that key never retries.
+*/
+function claimPostureKey(current, key) {
+	if (current === key) return {
+		run: false,
+		next: current
+	};
+	return {
+		run: true,
+		next: key
+	};
+}
+/**
+* Drop a failed in-flight key so the next trigger re-probes the same targets.
+* A newer key that started meanwhile is left alone.
+*/
+function releasePostureKey(current, attempted) {
+	return current === attempted ? void 0 : current;
+}
+//#endregion
 //#region src/lan.ts
 /**
 * LAN address derivation for the pairing URLs. Mirrors the dsh CLI's
@@ -1918,6 +2499,12 @@ function isLinkedSpec(spec) {
 	if (typeof spec !== "string") return false;
 	return /^(?:link|file):|^\.{1,2}(?:[/\\]|$)/.test(spec);
 }
+/** Whether a direct local dependency overrides one of the aggregate's children. */
+function hasLinkedFamilyOverride(anchorManifest, profileManifest) {
+	const dependencies = profileManifest?.dependencies;
+	if (typeof dependencies !== "object" || dependencies === null) return false;
+	return familyChildren(anchorManifest).some((name) => isLinkedSpec(dependencies[name]));
+}
 /**
 * Resolve the anchor package's manifest path. The aggregate package is the
 * canonical entry point; this plugin's own package is the fallback. Both a
@@ -1950,7 +2537,7 @@ function resolveUpdateTarget(deps) {
 	if (profile === void 0) return { error: "link" };
 	const profileManifest = readManifest(join(profile.dir, "package.json"));
 	const spec = (profileManifest?.dependencies)?.[anchor];
-	if (isLinkedSpec(spec)) return { error: "link" };
+	if (isLinkedSpec(spec) || hasLinkedFamilyOverride(manifest, profileManifest)) return { error: "link" };
 	return {
 		profileName: profile.name,
 		profileDir: profile.dir,
@@ -2045,7 +2632,7 @@ async function checkUpdates(deps) {
 	};
 	const profile = findProfile(manifestPath);
 	const profileManifest = profile === void 0 ? void 0 : readManifest(join(profile.dir, "package.json"));
-	const linked = profile === void 0 || isLinkedSpec((profileManifest?.dependencies)?.[anchor]);
+	const linked = profile === void 0 || isLinkedSpec((profileManifest?.dependencies)?.[anchor]) || hasLinkedFamilyOverride(manifest, profileManifest);
 	if (profile === void 0) return {
 		mode: "link",
 		packages: [],
@@ -2424,6 +3011,7 @@ const Config = z.object({
 	tokenTtlMs: z.number().step(1).min(6e4).default(10 * 6e4),
 	offlineAfterMs: z.number().step(1).min(5e3).default(25e3),
 	maxDevices: z.number().step(1).min(1).max(64).default(4),
+	idleExpireMs: z.number().step(1).min(6e4).default(DEFAULT_IDLE_EXPIRE_MS),
 	cookieName: z.string().min(1).default("dsh_pair"),
 	requirePairingForLan: z.boolean().default(true),
 	publicBaseUrl: z.string(),
@@ -2445,19 +3033,25 @@ function pairingConfigOf(resolved) {
 		tokenTtlMs: resolved.tokenTtlMs,
 		offlineAfterMs: resolved.offlineAfterMs,
 		maxDevices: resolved.maxDevices,
+		idleExpireMs: resolved.idleExpireMs,
 		cookieName: resolved.cookieName,
 		devicesFile: resolved.devicesFile
 	};
 }
+/** Default paired-session store: `$DSH_HOME/remote-web-ui-devices.json`. */
+function defaultDevicesFile(home = dshHome()) {
+	return join(home, "remote-web-ui-devices.json");
+}
 /** Schema defaults, re-read for hand-built test contexts (the loader applies them normally). */
 const DEFAULTS = {
 	tokenTtlMs: 10 * 6e4,
 	offlineAfterMs: 25e3,
 	maxDevices: 4,
+	idleExpireMs: DEFAULT_IDLE_EXPIRE_MS,
 	cookieName: "dsh_pair",
 	requirePairingForLan: true,
 	publicBaseUrl: void 0,
-	devicesFile: void 0,
+	devicesFile: defaultDevicesFile(),
 	autoTunnel: false,
 	mobileEnterToSend: true,
 	enabled: true
@@ -2473,10 +3067,11 @@ function applyImpl(ctx, config) {
 		tokenTtlMs: config?.tokenTtlMs ?? DEFAULTS.tokenTtlMs,
 		offlineAfterMs: config?.offlineAfterMs ?? DEFAULTS.offlineAfterMs,
 		maxDevices: config?.maxDevices ?? DEFAULTS.maxDevices,
+		idleExpireMs: config?.idleExpireMs ?? DEFAULTS.idleExpireMs,
 		cookieName: config?.cookieName ?? DEFAULTS.cookieName,
 		requirePairingForLan: config?.requirePairingForLan ?? DEFAULTS.requirePairingForLan,
 		publicBaseUrl: config?.publicBaseUrl,
-		devicesFile: config?.devicesFile,
+		devicesFile: config?.devicesFile ?? DEFAULTS.devicesFile,
 		autoTunnel: config?.autoTunnel ?? DEFAULTS.autoTunnel,
 		mobileEnterToSend: config?.mobileEnterToSend ?? DEFAULTS.mobileEnterToSend,
 		enabled: config?.enabled ?? DEFAULTS.enabled
@@ -2488,6 +3083,7 @@ function applyImpl(ctx, config) {
 			tokenTtlMs: value.tokenTtlMs ?? DEFAULTS.tokenTtlMs,
 			offlineAfterMs: value.offlineAfterMs ?? DEFAULTS.offlineAfterMs,
 			maxDevices: value.maxDevices ?? DEFAULTS.maxDevices,
+			idleExpireMs: value.idleExpireMs ?? DEFAULTS.idleExpireMs,
 			cookieName: value.cookieName ?? DEFAULTS.cookieName,
 			requirePairingForLan: value.requirePairingForLan ?? DEFAULTS.requirePairingForLan,
 			publicBaseUrl: value.publicBaseUrl,
@@ -2508,6 +3104,7 @@ function applyImpl(ctx, config) {
 				state: "running",
 				url: info.url
 			});
+			runPostureProbe();
 		} else if (info.phase === "starting") {
 			service.setPublicBaseUrl(void 0);
 			service.setTunnelStatus({ state: "starting" });
@@ -2595,10 +3192,53 @@ function applyImpl(ctx, config) {
 			apiProxy,
 			mobileEnterToSend: () => resolve().mobileEnterToSend
 		}) : [],
+		...makeRemoteApiRoutes({
+			service,
+			port: ctx.webServer.port
+		}),
 		...updateRoutes
 	];
+	const upgrades = makeRemoteApiUpgradeRoutes({
+		service,
+		port: ctx.webServer.port
+	});
 	const gate = makeGateListener(service, () => resolve().requirePairingForLan, () => resolve().enabled);
 	ctx.effect(() => ctx.on("api/gate", gate), "remote-web-ui: api gate");
+	let postureKey;
+	let postureWasExposed = false;
+	const runPostureProbe = () => {
+		if (!resolve().enabled) return;
+		const targets = postureTargets(service.publicBaseUrl, service.lanAddresses, ctx.webServer.port);
+		if (targets.length === 0) {
+			postureKey = void 0;
+			service.setPosture(void 0);
+			return;
+		}
+		const key = targets.join("|");
+		const claim = claimPostureKey(postureKey, key);
+		if (!claim.run) return;
+		postureKey = claim.next;
+		probePosture({
+			port: ctx.webServer.port,
+			targets
+		}).then((snapshot) => {
+			service.setPosture(snapshot);
+			const exposedHosts = snapshot.hosts.filter((host) => host.exposed).map((host) => host.host);
+			const exposed = exposedHosts.length > 0;
+			if (exposed && !postureWasExposed) console.error(`remote-web-ui: CRITICAL — the /api fence is OPEN for [${exposedHosts.join(", ")}]: unpaired clients reach the full host API. Remove --trusted-host for these hosts (pairing covers them) or bind loopback.`);
+			else if (!exposed && postureWasExposed) console.log("remote-web-ui: the /api posture probe is clean again (every advertised origin refused with 403).");
+			postureWasExposed = exposed;
+		}).catch(() => {
+			postureKey = releasePostureKey(postureKey, key);
+		});
+	};
+	const initialPostureTimer = setTimeout$1(() => {
+		runPostureProbe();
+	}, 5e3);
+	initialPostureTimer.unref();
+	ctx.effect(() => () => {
+		clearTimeout(initialPostureTimer);
+	}, "remote-web-ui: posture probe boot");
 	new RemoteWebUiPairing(ctx, (request) => {
 		if (!resolve().enabled) return false;
 		return isPairedDeviceRequest(service, request);
@@ -2620,7 +3260,7 @@ function applyImpl(ctx, config) {
 		const enabled = value.enabled;
 		if (!enabled) service.stop();
 		if (disposeRoutes === void 0 && enabled) disposeRoutes = ctx.effect(() => {
-			const disposers = routes.map((route) => ctx.webServer.register(route));
+			const disposers = [...routes.map((route) => ctx.webServer.register(route)), ...upgrades.map((route) => ctx.webServer.registerUpgrade(route))];
 			return () => {
 				for (const dispose of disposers) dispose();
 			};
@@ -2642,6 +3282,7 @@ function applyImpl(ctx, config) {
 			disposeSweep();
 			disposeSweep = void 0;
 		}
+		runPostureProbe();
 	};
 	installSettingsSection(ctx, REMOTE_WEB_UI_SETTINGS_NAMESPACE, Config, config ?? {}, {
 		setSource: (source) => {
@@ -2662,4 +3303,4 @@ function isHttpUrl(value) {
 	}
 }
 //#endregion
-export { Config, REMOTE_WEB_UI_SETTINGS_NAMESPACE, apply, inject, name, pairingConfigOf };
+export { Config, REMOTE_WEB_UI_SETTINGS_NAMESPACE, apply, defaultDevicesFile, inject, name, pairingConfigOf };