dsh-mobile 0.3.16 → 0.4.1

package/lib/index.mjs

@@ -142,28 +142,28 @@ var AccessController = class {
 			devices: Object.freeze([...devices])
 		});
 	}
-	emitSessionEnded(session) {
+	emitSessionEnded(session, reason) {
 		const authorization = Object.freeze({
 			sessionKey: session.key,
 			deviceId: session.deviceId,
 			expiresAt: session.expiresAt
 		});
-		for (const listener of this.sessionEndedListeners) listener(authorization);
+		for (const listener of this.sessionEndedListeners) listener(authorization, reason);
 	}
-	removeSession(key) {
+	removeSession(key, reason) {
 		const session = this.sessions.get(key);
 		if (session === void 0) return;
 		this.sessions.delete(key);
-		this.emitSessionEnded(session);
+		this.emitSessionEnded(session, reason);
 	}
 	pruneSessions(now) {
-		for (const [key, session] of this.sessions) if (session.expiresAt <= now) this.removeSession(key);
+		for (const [key, session] of this.sessions) if (session.expiresAt <= now) this.removeSession(key, "expired");
 	}
 	createSession(deviceId, now, deviceExpiresAt) {
 		this.pruneSessions(now);
 		if (this.sessions.size >= this.options.maxSessions) {
 			const oldest = [...this.sessions.values()].sort((left, right) => left.createdAt - right.createdAt)[0];
-			if (oldest !== void 0) this.removeSession(oldest.key);
+			if (oldest !== void 0) this.removeSession(oldest.key, "evicted");
 		}
 		const sessionToken = opaqueToken();
 		const csrfToken = opaqueToken();
@@ -244,7 +244,9 @@ var AccessController = class {
 			const tokenDigest = digest(deviceToken);
 			const index = this.devices.findIndex((device) => timingSafeEqual(Buffer.from(device.tokenDigest, "hex"), tokenDigest));
 			const device = this.devices[index];
-			if (device === void 0 || device.revokedAt !== void 0 || device.expiresAt <= now) throw new AccessError(401, "authentication_failed");
+			if (device === void 0) throw new AccessError(401, "authentication_failed");
+			if (device.revokedAt !== void 0) throw new AccessError(401, "device_revoked");
+			if (device.expiresAt <= now) throw new AccessError(401, "device_expired");
 			const updated = Object.freeze({
 				...device,
 				lastSeenAt: now
@@ -256,6 +258,32 @@ var AccessController = class {
 			return this.createSession(device.id, now, device.expiresAt);
 		});
 	}
+	/** Validate a persistent device credential without consuming a Session slot. */
+	async probe(deviceToken) {
+		this.requireInitialized();
+		if (deviceToken.length > 512) throw new AccessError(401, "authentication_failed");
+		return this.exclusive(async () => {
+			const now = this.now();
+			const tokenDigest = digest(deviceToken);
+			const index = this.devices.findIndex((device) => timingSafeEqual(Buffer.from(device.tokenDigest, "hex"), tokenDigest));
+			const device = this.devices[index];
+			if (device === void 0) throw new AccessError(401, "authentication_failed");
+			if (device.revokedAt !== void 0) throw new AccessError(401, "device_revoked");
+			if (device.expiresAt <= now) throw new AccessError(401, "device_expired");
+			const updated = Object.freeze({
+				...device,
+				lastSeenAt: now
+			});
+			const next = [...this.devices];
+			next[index] = updated;
+			await this.store.save(this.snapshot(next));
+			this.devices = next;
+			return Object.freeze({
+				deviceId: device.id,
+				deviceExpiresAt: device.expiresAt
+			});
+		});
+	}
 	/** Resolve a short Session Cookie without revealing whether device or Session failed. */
 	authorizeSession(sessionToken) {
 		this.requireInitialized();
@@ -266,7 +294,7 @@ var AccessController = class {
 		const session = this.sessions.get(key);
 		const device = session === void 0 ? void 0 : this.devices.find((candidate) => candidate.id === session.deviceId);
 		if (session === void 0 || device === void 0 || device.revokedAt !== void 0 || device.expiresAt <= now) {
-			if (session !== void 0) this.removeSession(session.key);
+			if (session !== void 0) this.removeSession(session.key, "expired");
 			throw new AccessError(401, "authentication_failed");
 		}
 		return Object.freeze({
@@ -282,7 +310,7 @@ var AccessController = class {
 	}
 	/** End one short Session and notify the gateway to abort its attached work. */
 	logout(authorization) {
-		this.removeSession(authorization.sessionKey);
+		this.removeSession(authorization.sessionKey, "logout");
 	}
 	/** Persist revocation, then end every Session owned by that device. */
 	async revokeDevice(deviceId) {
@@ -298,7 +326,7 @@ var AccessController = class {
 			});
 			await this.store.save(this.snapshot(next));
 			this.devices = next;
-			for (const [key, session] of this.sessions) if (session.deviceId === deviceId) this.removeSession(key);
+			for (const [key, session] of this.sessions) if (session.deviceId === deviceId) this.removeSession(key, "revoked");
 			return true;
 		});
 	}
@@ -308,7 +336,7 @@ var AccessController = class {
 		await this.exclusive(async () => {
 			await this.store.save(this.snapshot([]));
 			this.devices = [];
-			for (const key of [...this.sessions.keys()]) this.removeSession(key);
+			for (const key of [...this.sessions.keys()]) this.removeSession(key, "revoked");
 			this.pairingWindow = void 0;
 		});
 	}
@@ -347,7 +375,7 @@ var AccessController = class {
 	async finishClose() {
 		await this.mutation;
 		this.pairingWindow = void 0;
-		for (const key of [...this.sessions.keys()]) this.removeSession(key);
+		for (const key of [...this.sessions.keys()]) this.removeSession(key, "expired");
 		this.sessionEndedListeners.clear();
 		this.initialized = false;
 	}
@@ -361,7 +389,7 @@ var AccessController = class {
 };
 //#endregion
 //#region src/network.ts
-function parseIpv4(address) {
+function parseIpv4$1(address) {
 	const parts = address.split(".");
 	if (parts.length !== 4) throw new Error(`invalid IPv4 address ${JSON.stringify(address)}`);
 	let value = 0n;
@@ -375,7 +403,7 @@ function parseIpv4(address) {
 }
 function parseIpv6Part(part, address) {
 	if (part.includes(".")) {
-		const ipv4 = parseIpv4(part);
+		const ipv4 = parseIpv4$1(part);
 		return [Number(ipv4 >> 16n & 65535n), Number(ipv4 & 65535n)];
 	}
 	if (!/^[\da-f]{1,4}$/iu.test(part)) throw new Error(`invalid IPv6 address ${JSON.stringify(address)}`);
@@ -405,12 +433,12 @@ function parseIp(address) {
 	const mapped = mappedIpv4(unwrapped);
 	if (mapped !== void 0) return {
 		bits: 32,
-		value: parseIpv4(mapped)
+		value: parseIpv4$1(mapped)
 	};
 	const version = isIP(unwrapped.split("%", 1)[0] ?? unwrapped);
 	if (version === 4) return {
 		bits: 32,
-		value: parseIpv4(unwrapped)
+		value: parseIpv4$1(unwrapped)
 	};
 	if (version === 6) return {
 		bits: 128,
@@ -1051,6 +1079,46 @@ var MobileAccessGatewayController = class {
 	}
 };
 //#endregion
+//#region src/local-admin-host.ts
+/** Browser-safe desktop-admin Host checks. Do not import Node APIs here. */
+function unwrapBrackets(hostname) {
+	return hostname.startsWith("[") && hostname.endsWith("]") ? hostname.slice(1, -1) : hostname;
+}
+function parseIpv4(hostname) {
+	const parts = hostname.split(".");
+	if (parts.length !== 4) return void 0;
+	const octets = [];
+	for (const part of parts) {
+		if (!/^(?:0|[1-9]\d{0,2})$/u.test(part)) return void 0;
+		const value = Number(part);
+		if (value > 255) return void 0;
+		octets.push(value);
+	}
+	return octets;
+}
+function isLoopbackIpv4(octets) {
+	return octets[0] === 127;
+}
+function isPrivateIpv4(octets) {
+	return octets[0] === 10 || octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31 || octets[0] === 192 && octets[1] === 168;
+}
+function isLinkLocalIpv4(octets) {
+	return octets[0] === 169 && octets[1] === 254;
+}
+/**
+* Hostnames that may appear on the DSH desktop admin surface.
+* Loopback, RFC1918, and IPv4 link-local are accepted. Public IPs,
+* CGNAT, and arbitrary DNS names stay rejected so DNS rebinding
+* cannot reach `/api/mobile-access`.
+*/
+function isLocalAdminHostname(hostname) {
+	const host = unwrapBrackets(hostname).trim().toLowerCase();
+	if (host === "localhost" || host === "::1") return true;
+	const octets = parseIpv4(host);
+	if (octets === void 0) return false;
+	return isLoopbackIpv4(octets) || isPrivateIpv4(octets) || isLinkLocalIpv4(octets);
+}
+//#endregion
 //#region src/http-security.ts
 const DEVICE_COOKIE = "dsh_ma_device";
 const SESSION_COOKIE = "dsh_ma_session";
@@ -1094,26 +1162,43 @@ function parseRequestTarget(raw) {
 		search: parsed.search
 	});
 }
-/** Set the gateway-owned browser protections and non-cacheability. */
-function setSecurityHeaders(response, tls) {
+/**
+* The frame sources a proxied GUI document may embed: its own routes, blob:
+* (the PDF viewer's object URL) and external http(s) pages (the sidebar
+* browser tab). The framed document runs in the tab's existing sandbox
+* (opaque origin, no same-origin privileges), so this does not hand the
+* embedded page anything it did not already have.
+*/
+const PROXIED_FRAME_SRC = "frame-src 'self' blob: https: http:";
+/**
+* Set the gateway browser protections and non-cacheability.
+* @param response - the response to decorate.
+* @param tls - whether the connection is TLS (adds HSTS).
+* @param framing - the framing policy; defaults to the strict gateway one, so
+*   every existing call site keeps refusing to be framed. Only the two PROXIED
+*   forwarders pass `'proxied'`.
+*/
+function setSecurityHeaders(response, tls, framing = "gateway") {
+	const proxied = framing === "proxied";
 	response.setHeader("Cache-Control", "no-store");
 	response.setHeader("Content-Security-Policy", [
 		"default-src 'self'",
 		"base-uri 'none'",
 		"object-src 'none'",
-		"frame-ancestors 'none'",
+		proxied ? "frame-ancestors 'self'" : "frame-ancestors 'none'",
 		"form-action 'self'",
 		"script-src 'self' 'unsafe-inline' 'unsafe-eval'",
 		"style-src 'self' 'unsafe-inline'",
 		"img-src 'self' data: blob:",
 		"font-src 'self' data:",
 		"connect-src 'self'",
-		"worker-src 'self' blob:"
+		"worker-src 'self' blob:",
+		...proxied ? [PROXIED_FRAME_SRC] : []
 	].join("; "));
 	response.setHeader("Permissions-Policy", "camera=(), microphone=(), geolocation=(), payment=(), usb=()");
 	response.setHeader("Referrer-Policy", "no-referrer");
 	response.setHeader("X-Content-Type-Options", "nosniff");
-	response.setHeader("X-Frame-Options", "DENY");
+	response.setHeader("X-Frame-Options", proxied ? "SAMEORIGIN" : "DENY");
 	response.setHeader("Cross-Origin-Resource-Policy", "same-origin");
 	if (tls) response.setHeader("Strict-Transport-Security", "max-age=31536000");
 }
@@ -1210,7 +1295,7 @@ function localAuthority(header) {
 function assertLocalAdminTrust(request, requireBrowserOrigin) {
 	if (request.socket.remoteAddress === void 0 || !isLoopbackAddress(request.socket.remoteAddress)) throw new HttpError(403, "forbidden");
 	const host = localAuthority(request.headers.host);
-	if (host === void 0 || host.hostname !== "localhost" && !isLoopbackAddress(host.hostname)) throw new HttpError(403, "forbidden");
+	if (host === void 0 || !isLocalAdminHostname(host.hostname)) throw new HttpError(403, "forbidden");
 	const site = request.headers["sec-fetch-site"];
 	if (site !== void 0 && site !== "same-origin" && site !== "none") throw new HttpError(403, "forbidden");
 	const origin = request.headers.origin;
@@ -1221,7 +1306,8 @@ function assertLocalAdminTrust(request, requireBrowserOrigin) {
 		if (error instanceof HttpError) throw error;
 		throw new HttpError(403, "forbidden");
 	}
-	if (requireBrowserOrigin && site !== void 0 && (origin === void 0 || site !== "same-origin")) throw new HttpError(403, "forbidden");
+	if (requireBrowserOrigin && origin === void 0) throw new HttpError(403, "forbidden");
+	if (requireBrowserOrigin && site !== void 0 && site !== "same-origin") throw new HttpError(403, "forbidden");
 }
 //#endregion
 //#region src/version.ts
@@ -1613,6 +1699,12 @@ function combineSignalLifetime(first, second) {
 		cleanup
 	};
 }
+/** Validate and normalize an action input through either supported schema form. */
+function parseActionInput(schema, input) {
+	if (schema === void 0) return input;
+	if (typeof schema === "function") return schema(input);
+	return schema.parse(input) ?? input;
+}
 /** Host registry and service consumed by both npm plugins and local extensions. */
 var MobileAccessService = class extends Service {
 	registered = /* @__PURE__ */ new Map();
@@ -1744,9 +1836,9 @@ var MobileAccessService = class extends Service {
 		if (extension === void 0) throw new MobileExtensionError("extension_not_found", "extension not found", 404);
 		const action = ("host" in extension ? extension.host : extension).actions?.[actionName];
 		if (action === void 0) throw new MobileExtensionError("action_not_found", "action not found", 404);
-		let parsed = input;
+		let parsed;
 		try {
-			parsed = action.input?.parse(input) ?? input;
+			parsed = parseActionInput(action.input, input);
 		} catch {
 			throw new MobileExtensionError("invalid_action_input", "action input is invalid", 400);
 		}
@@ -2094,6 +2186,188 @@ function createMobileAccessService(ctx) {
 	return new MobileAccessService(ctx);
 }
 //#endregion
+//#region src/auth-pages.ts
+const COPY = {
+	en: {
+		lang: "en",
+		pairTitle: "Pair DSH mobile access",
+		pairHeading: "Pair this device",
+		pairingCode: "Pairing code",
+		deviceName: "Device name",
+		pair: "Pair",
+		pairing: "Pairing…",
+		pairFailed: "Pairing failed",
+		unavailable: "The computer is unavailable.",
+		reconnectTitle: "Reconnect DSH mobile access",
+		reconnectHeading: "Reconnect this device",
+		restoring: "Restoring the secure Session…",
+		noLongerPaired: "This device is no longer paired. Open pairing on the computer, then pair it again.",
+		openPairing: "Open pairing"
+	},
+	zh: {
+		lang: "zh-CN",
+		pairTitle: "配对 DSH 移动访问",
+		pairHeading: "配对此设备",
+		pairingCode: "配对码",
+		deviceName: "设备名称",
+		pair: "配对",
+		pairing: "正在配对…",
+		pairFailed: "配对失败",
+		unavailable: "电脑当前不可用。",
+		reconnectTitle: "重新连接 DSH 移动访问",
+		reconnectHeading: "重新连接此设备",
+		restoring: "正在恢复安全会话…",
+		noLongerPaired: "此设备已不在配对列表中。请在电脑端打开配对，然后重新配对。",
+		openPairing: "打开配对页面"
+	},
+	it: {
+		lang: "it-IT",
+		pairTitle: "Abbina accesso mobile DSH",
+		pairHeading: "Abbina questo dispositivo",
+		pairingCode: "Codice di abbinamento",
+		deviceName: "Nome dispositivo",
+		pair: "Abbina",
+		pairing: "Abbinamento…",
+		pairFailed: "Abbinamento non riuscito",
+		unavailable: "Il computer non è disponibile.",
+		reconnectTitle: "Riconnetti accesso mobile DSH",
+		reconnectHeading: "Riconnetti questo dispositivo",
+		restoring: "Ripristino della sessione sicura…",
+		noLongerPaired: "Questo dispositivo non è più abbinato. Apri l’abbinamento sul computer e ripeti la procedura.",
+		openPairing: "Apri abbinamento"
+	}
+};
+/** Choose Chinese, Italian, or English from an HTTP Accept-Language header. */
+function resolveAuthPageLocale(header) {
+	const values = header?.split(",").map((value, index) => {
+		const [language, ...parameters] = value.split(";");
+		const quality = parameters.find((parameter) => parameter.trim().toLowerCase().startsWith("q="));
+		const parsedQuality = quality === void 0 ? 1 : Number(quality.trim().slice(2));
+		return {
+			language: language?.trim().toLowerCase() ?? "",
+			quality: Number.isFinite(parsedQuality) ? Math.max(0, Math.min(1, parsedQuality)) : 0,
+			index
+		};
+	}).filter((value) => value.quality > 0).sort((left, right) => right.quality - left.quality || left.index - right.index).map((value) => value.language) ?? [];
+	for (const value of values) {
+		if (value.startsWith("zh")) return "zh";
+		if (value.startsWith("it")) return "it";
+		if (value.startsWith("en")) return "en";
+	}
+	return "en";
+}
+/** Render the browser pairing form without reflecting request data into HTML. */
+function renderPairPage(locale) {
+	const copy = COPY[locale];
+	return `<!doctype html>
+<html lang="${copy.lang}">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+<title>${copy.pairTitle}</title>
+<main>
+  <h1>${copy.pairHeading}</h1>
+  <form id="pair-form">
+    <label>${copy.pairingCode} <input id="pair-token" autocomplete="one-time-code" required></label>
+    <label>${copy.deviceName} <input id="device-label" maxlength="64" autocomplete="off"></label>
+    <button type="submit">${copy.pair}</button>
+    <output id="pair-status" aria-live="polite"></output>
+  </form>
+</main>
+<script src="/mobile-access/pair.js" defer><\/script>
+</html>
+`;
+}
+/** Render the pairing form script with locale-owned status messages. */
+function renderPairScript(locale) {
+	const copy = COPY[locale];
+	return `(() => {
+  const form = document.getElementById('pair-form')
+  const token = document.getElementById('pair-token')
+  const label = document.getElementById('device-label')
+  const status = document.getElementById('pair-status')
+  const fragment = new URLSearchParams(location.hash.slice(1))
+  const supplied = fragment.get('token')
+  history.replaceState(null, '', location.pathname)
+  if (supplied) token.value = supplied
+  form.addEventListener('submit', async (event) => {
+    event.preventDefault()
+    status.value = ${JSON.stringify(copy.pairing)}
+    try {
+      const response = await fetch('/mobile-access/auth/pair', {
+        method: 'POST',
+        credentials: 'same-origin',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ token: token.value, label: label.value || undefined }),
+      })
+      if (!response.ok) {
+        status.value = ${JSON.stringify(copy.pairFailed)}
+        return
+      }
+      location.replace('/')
+    } catch {
+      status.value = ${JSON.stringify(copy.unavailable)}
+    }
+  })
+})()
+`;
+}
+/** Render the browser reauthentication page. */
+function renderLoginPage(locale) {
+	const copy = COPY[locale];
+	return `<!doctype html>
+<html lang="${copy.lang}">
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
+<title>${copy.reconnectTitle}</title>
+<main>
+  <h1>${copy.reconnectHeading}</h1>
+  <p id="login-progress" aria-live="polite">${copy.restoring}</p>
+  <section id="login-failed" hidden>
+    <p>${copy.noLongerPaired}</p>
+    <a href="/mobile-access/pair">${copy.openPairing}</a>
+  </section>
+</main>
+<script src="/mobile-access/login.js" defer><\/script>
+</html>
+`;
+}
+/** Render the reauthentication script with locale-owned failure text. */
+function renderLoginScript(locale) {
+	const copy = COPY[locale];
+	return `(() => {
+  const candidate = new URL(location.href).searchParams.get('return')
+  let returnPath = '/'
+  if (candidate && candidate.startsWith('/')) {
+    try {
+      const resolved = new URL(candidate, location.origin)
+      const pathname = decodeURIComponent(resolved.pathname)
+      if (resolved.origin === location.origin && pathname !== '/mobile-access'
+        && !pathname.startsWith('/mobile-access/') && !pathname.includes('\\\\')) {
+        returnPath = resolved.pathname + resolved.search + resolved.hash
+      }
+    } catch {
+      // Malformed untrusted return targets keep the safe root default.
+    }
+  }
+  fetch('/mobile-access/auth/renew', {
+    method: 'POST',
+    credentials: 'same-origin',
+    headers: { 'content-type': 'application/json' },
+    body: '{}',
+  }).then((response) => {
+    if (response.ok) {
+      location.replace(returnPath)
+      return
+    }
+    document.getElementById('login-progress').hidden = true
+    document.getElementById('login-failed').hidden = false
+  }).catch(() => {
+    document.getElementById('login-progress').textContent = ${JSON.stringify(copy.unavailable)}
+  })
+})()
+`;
+}
+//#endregion
 //#region src/gateway.ts
 const MAX_CONTROL_BODY_BYTES = 16384;
 const MAX_HEADER_BYTES = 16384;
@@ -2152,23 +2426,6 @@ const MOBILE_LAYOUT_DEPENDENCY_PROFILES = Object.freeze([Object.freeze({
 })]);
 const MOBILE_CSRF_FETCH_BOOTSTRAP = `(()=>{const nativeFetch=window.fetch.bind(window);window.fetch=(input,init)=>{const source=input instanceof Request?input:undefined;const method=String(init?.method??source?.method??'GET').toUpperCase();if(method==='GET'||method==='HEAD')return nativeFetch(input,init);const raw=typeof input==='string'?input:input instanceof URL?input.href:source?.url;if(raw===undefined||new URL(raw,location.href).origin!==location.origin)return nativeFetch(input,init);const headers=new Headers(init?.headers??source?.headers);if(!headers.has(${JSON.stringify(CSRF_HEADER)})){const prefix=${JSON.stringify(`${CSRF_COOKIE}=`)};const token=document.cookie.split(';').map(value=>value.trim()).find(value=>value.startsWith(prefix))?.slice(prefix.length);if(token!==undefined)headers.set(${JSON.stringify(CSRF_HEADER)},token)}return nativeFetch(input,{...init,headers})};})();`;
 const MOBILE_AUTHENTICATED_TRANSPORT_BOOTSTRAP = `(()=>{if(window.__DSH_TRANSPORT__!==undefined)throw new Error('DSH Mobile cannot replace an existing transport override');window.__DSH_TRANSPORT__={fetch:(input,init)=>window.fetch(input,init),ownsHost:true}})();`;
-const PAIR_PAGE = `<!doctype html>
-<html lang="en">
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
-<title>Pair DSH mobile access</title>
-<main>
-  <h1>Pair this device</h1>
-  <form id="pair-form">
-    <label>Pairing code <input id="pair-token" autocomplete="one-time-code" required></label>
-    <label>Device name <input id="device-label" maxlength="64" autocomplete="off"></label>
-    <button type="submit">Pair</button>
-    <output id="pair-status"></output>
-  </form>
-</main>
-<script src="/mobile-access/pair.js" defer><\/script>
-</html>
-`;
 const gzipBuffer = promisify(gzip);
 function ensureMobileViewport(html) {
 	const match = /<meta\b(?=[^>]*\bname\s*=\s*["']viewport["'])[^>]*>/iu.exec(html);
@@ -2272,80 +2529,6 @@ function rewriteMobileIndexWithBatch(html) {
 function rewriteMobileIndex(html) {
 	return rewriteMobileIndexWithBatch(html).html;
 }
-const PAIR_SCRIPT = `(() => {
-  const form = document.getElementById('pair-form')
-  const token = document.getElementById('pair-token')
-  const label = document.getElementById('device-label')
-  const status = document.getElementById('pair-status')
-  const fragment = new URLSearchParams(location.hash.slice(1))
-  const supplied = fragment.get('token')
-  history.replaceState(null, '', location.pathname)
-  if (supplied) token.value = supplied
-  form.addEventListener('submit', async (event) => {
-    event.preventDefault()
-    status.value = 'Pairing…'
-    const response = await fetch('/mobile-access/auth/pair', {
-      method: 'POST',
-      credentials: 'same-origin',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ token: token.value, label: label.value || undefined }),
-    })
-    if (!response.ok) {
-      status.value = 'Pairing failed'
-      return
-    }
-    location.replace('/')
-  })
-})()
-`;
-const LOGIN_PAGE = `<!doctype html>
-<html lang="en">
-<meta charset="utf-8">
-<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
-<title>Reconnect DSH mobile access</title>
-<main>
-  <h1>Reconnect this device</h1>
-  <p id="login-progress">Restoring the secure Session…</p>
-  <section id="login-failed" hidden>
-    <p>This device is no longer paired. Open pairing on the computer, then pair it again.</p>
-    <a href="/mobile-access/pair">Open pairing</a>
-  </section>
-</main>
-<script src="/mobile-access/login.js" defer><\/script>
-</html>
-`;
-const LOGIN_SCRIPT = `(() => {
-  const candidate = new URL(location.href).searchParams.get('return')
-  let returnPath = '/'
-  if (candidate && candidate.startsWith('/')) {
-    try {
-      const resolved = new URL(candidate, location.origin)
-      const pathname = decodeURIComponent(resolved.pathname)
-      if (resolved.origin === location.origin && pathname !== '/mobile-access'
-        && !pathname.startsWith('/mobile-access/') && !pathname.includes('\\\\')) {
-        returnPath = resolved.pathname + resolved.search + resolved.hash
-      }
-    } catch {
-      // Malformed untrusted return targets keep the safe root default.
-    }
-  }
-  fetch('/mobile-access/auth/renew', {
-    method: 'POST',
-    credentials: 'same-origin',
-    headers: { 'content-type': 'application/json' },
-    body: '{}',
-  }).then((response) => {
-    if (response.ok) {
-      location.replace(returnPath)
-      return
-    }
-    document.getElementById('login-progress').hidden = true
-    document.getElementById('login-failed').hidden = false
-  }).catch(() => {
-    document.getElementById('login-progress').textContent = 'The computer is unavailable.'
-  })
-})()
-`;
 var ByteLimitTransform = class extends Transform {
 	maximum;
 	total = 0;
@@ -2772,6 +2955,9 @@ var MobileAccessGateway = class {
 	mobileBootBatches = /* @__PURE__ */ new Map();
 	extensionEventListeners = /* @__PURE__ */ new Set();
 	extensionEventRevision = 0;
+	taskEventListeners = /* @__PURE__ */ new Set();
+	deviceEventListeners = /* @__PURE__ */ new Map();
+	pendingDeviceRevocations = /* @__PURE__ */ new Set();
 	extensionChangeTimer;
 	extensionChangeTask;
 	legacyCustomDigest = "";
@@ -2786,6 +2972,7 @@ var MobileAccessGateway = class {
 	removeSessionListener;
 	removeExtensionContentListener;
 	renewLimiter;
+	probeLimiter;
 	constructor(config, store, extensions, upstreamAuthenticatedUrl, extraWebSocketPaths, blockedUpgradeLog) {
 		this.config = config;
 		this.extensions = extensions;
@@ -2805,8 +2992,18 @@ var MobileAccessGateway = class {
 			maxRateLimitKeys: config.maxRateLimitKeys
 		});
 		this.renewLimiter = new BoundedRateLimiter(Math.min(100, config.maxPairingAttempts * 4), config.rateLimitWindowMs, config.maxRateLimitKeys);
-		this.removeSessionListener = this.access.onSessionEnded((authorization) => {
-			this.abortSessionResources(authorization.sessionKey);
+		this.probeLimiter = new BoundedRateLimiter(Math.min(1e3, config.maxDevices * 4), config.rateLimitWindowMs, config.maxRateLimitKeys);
+		this.removeSessionListener = this.access.onSessionEnded((authorization, reason) => {
+			if (reason === "revoked") {
+				if (!this.pendingDeviceRevocations.has(authorization.deviceId)) {
+					this.pendingDeviceRevocations.add(authorization.deviceId);
+					this.broadcastDeviceRevoked(authorization.deviceId);
+				}
+				setImmediate(() => {
+					this.abortSessionResources(authorization.sessionKey);
+					this.pendingDeviceRevocations.delete(authorization.deviceId);
+				});
+			} else this.abortSessionResources(authorization.sessionKey);
 		});
 		this.removeExtensionContentListener = this.extensions?.onContentChanged(() => {
 			this.broadcastExtensionChange();
@@ -3078,6 +3275,17 @@ var MobileAccessGateway = class {
 			sessionExpiresAt: result.sessionExpiresAt
 		}, this.tlsEnabled);
 	}
+	async handleNativeProbe(request, response) {
+		if (!this.probeLimiter.take(request.socket.remoteAddress ?? "unknown", Date.now())) throw new HttpError(429, "rate_limited");
+		const body = await readJsonObject(request, MAX_CONTROL_BODY_BYTES);
+		if (typeof body.deviceToken !== "string") throw new HttpError(400, "bad_request");
+		const result = await this.access.probe(body.deviceToken);
+		sendJson(response, 200, {
+			instanceId: this.config.instanceId,
+			deviceId: result.deviceId,
+			deviceExpiresAt: result.deviceExpiresAt
+		}, this.tlsEnabled);
+	}
 	async handleLogout(request, response) {
 		await readJsonObject(request, MAX_CONTROL_BODY_BYTES);
 		const authorization = this.authorize(request);
@@ -3140,8 +3348,11 @@ var MobileAccessGateway = class {
 		}
 		if (target.search === "" && request.method === "GET" && (target.decodedPathname === `/mobile-access/pair` || target.decodedPathname === `/mobile-access/pair.js`)) {
 			if (!this.access.pairingStatus().open) throw new HttpError(404, "not_found");
+			const languageHeader = request.headers["accept-language"];
+			const locale = resolveAuthPageLocale(typeof languageHeader === "string" ? languageHeader : void 0);
 			setSecurityHeaders(response, this.tlsEnabled);
-			const body = target.decodedPathname.endsWith(".js") ? PAIR_SCRIPT : PAIR_PAGE;
+			response.setHeader("Vary", "Accept-Language");
+			const body = target.decodedPathname.endsWith(".js") ? renderPairScript(locale) : renderPairPage(locale);
 			response.writeHead(200, {
 				"Content-Type": target.decodedPathname.endsWith(".js") ? "text/javascript; charset=utf-8" : "text/html; charset=utf-8",
 				"Content-Length": Buffer.byteLength(body)
@@ -3151,8 +3362,11 @@ var MobileAccessGateway = class {
 		}
 		if (request.method === "GET" && (target.decodedPathname === `/mobile-access/login` || target.decodedPathname === `/mobile-access/login.js`)) {
 			if (target.decodedPathname.endsWith(".js") && target.search !== "") throw new HttpError(400, "bad_request");
+			const languageHeader = request.headers["accept-language"];
+			const locale = resolveAuthPageLocale(typeof languageHeader === "string" ? languageHeader : void 0);
 			setSecurityHeaders(response, this.tlsEnabled);
-			const body = target.decodedPathname.endsWith(".js") ? LOGIN_SCRIPT : LOGIN_PAGE;
+			response.setHeader("Vary", "Accept-Language");
+			const body = target.decodedPathname.endsWith(".js") ? renderLoginScript(locale) : renderLoginPage(locale);
 			response.writeHead(200, {
 				"Content-Type": target.decodedPathname.endsWith(".js") ? "text/javascript; charset=utf-8" : "text/html; charset=utf-8",
 				"Content-Length": Buffer.byteLength(body)
@@ -3176,6 +3390,10 @@ var MobileAccessGateway = class {
 			await this.handleNativeRenew(request, response);
 			return;
 		}
+		if (target.search === "" && request.method === "POST" && target.decodedPathname === `/mobile-access/auth/native-probe`) {
+			await this.handleNativeProbe(request, response);
+			return;
+		}
 		if (target.search === "" && request.method === "POST" && target.decodedPathname === `/mobile-access/auth/logout`) {
 			await this.handleLogout(request, response);
 			return;
@@ -3612,7 +3830,7 @@ var MobileAccessGateway = class {
 			delete headers["content-length"];
 			delete headers["content-encoding"];
 			delete headers.etag;
-			setSecurityHeaders(response, this.tlsEnabled);
+			setSecurityHeaders(response, this.tlsEnabled, "proxied");
 			response.writeHead(200, {
 				...headers,
 				"Content-Type": "text/html; charset=utf-8",
@@ -3864,7 +4082,7 @@ var MobileAccessGateway = class {
 				}
 				bodyDone.catch(reject);
 			});
-			setSecurityHeaders(response, this.tlsEnabled);
+			setSecurityHeaders(response, this.tlsEnabled, "proxied");
 			const headers = sanitizeResponseHeaders(proxied.headers, this.config.upstreamOrigin);
 			const cacheControl = revisionedStaticCacheControl(request$2);
 			if (cacheControl !== void 0) headers["cache-control"] = cacheControl;
@@ -3900,6 +4118,22 @@ var MobileAccessGateway = class {
 		this.extensionEventRevision += 1;
 		for (const listener of this.extensionEventListeners) listener(this.extensionEventRevision);
 	}
+	/** Fan a completed task to every phone holding this gateway's event stream. */
+	broadcastTaskEvent(event) {
+		if (this.closing) return;
+		const payload = JSON.stringify({
+			sessionId: String(event.sessionId),
+			turn: Number(event.turn) || 0
+		});
+		for (const listener of this.taskEventListeners) listener(payload);
+	}
+	/** Notify only the device whose persistent credential was revoked by the Host. */
+	broadcastDeviceRevoked(deviceId) {
+		const listeners = this.deviceEventListeners.get(deviceId);
+		if (listeners === void 0) return;
+		const payload = JSON.stringify({ reason: "device_revoked" });
+		for (const listener of [...listeners]) listener(payload);
+	}
 	pollLegacyCustomChanges() {
 		if (this.extensionChangeTask !== void 0) return this.extensionChangeTask;
 		const digestFile = async (path, fallback) => {
@@ -3931,6 +4165,10 @@ var MobileAccessGateway = class {
 			closed = true;
 			if (heartbeat !== void 0) clearInterval(heartbeat);
 			this.extensionEventListeners.delete(send);
+			this.taskEventListeners.delete(sendTask);
+			const deviceListeners = this.deviceEventListeners.get(authorization.deviceId);
+			deviceListeners?.delete(sendDevice);
+			if (deviceListeners?.size === 0) this.deviceEventListeners.delete(authorization.deviceId);
 			request.removeListener("aborted", close);
 			response.removeListener("close", close);
 			operation.release();
@@ -3939,6 +4177,14 @@ var MobileAccessGateway = class {
 			if (closed || response.destroyed || response.writableEnded) return;
 			response.write(`id: ${String(revision)}\nevent: extensions-changed\ndata: {\"revision\":${String(revision)}}\n\n`);
 		};
+		const sendTask = (payload) => {
+			if (closed || response.destroyed || response.writableEnded) return;
+			response.write(`event: task-notify\ndata: ${payload}\n\n`);
+		};
+		const sendDevice = (payload) => {
+			if (closed || response.destroyed || response.writableEnded) return;
+			response.write(`event: device-revoked\ndata: ${payload}\n\n`);
+		};
 		setSecurityHeaders(response, this.tlsEnabled);
 		response.writeHead(200, {
 			"Content-Type": "text/event-stream; charset=utf-8",
@@ -3948,6 +4194,10 @@ var MobileAccessGateway = class {
 		});
 		response.write("retry: 2000\n: ready\n\n");
 		this.extensionEventListeners.add(send);
+		this.taskEventListeners.add(sendTask);
+		const deviceListeners = this.deviceEventListeners.get(authorization.deviceId) ?? /* @__PURE__ */ new Set();
+		deviceListeners.add(sendDevice);
+		this.deviceEventListeners.set(authorization.deviceId, deviceListeners);
 		heartbeat = setInterval(() => {
 			if (!closed && !response.destroyed && !response.writableEnded) response.write(": heartbeat\n\n");
 		}, EXTENSION_EVENT_HEARTBEAT_MS);
@@ -4218,6 +4468,7 @@ var MobileAccessGateway = class {
 		this.upstreamAuthRequest?.destroy();
 		this.upstreamAuthRequest = void 0;
 		this.removeSessionListener();
+		this.pendingDeviceRevocations.clear();
 		const accessClose = this.access.close();
 		for (const stored of this.mobileBootBatches.values()) stored.assembly?.controller.abort();
 		for (const request of this.activeRequests.values()) request.abort();
@@ -5766,6 +6017,84 @@ var FrpController = class {
 	}
 };
 //#endregion
+//#region src/task-events.ts
+const TASK_EVENT_DEBOUNCE_MS = 1e3;
+function turnNumber(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
+}
+function turnData(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return {
+		turn: 0,
+		completed: false
+	};
+	const record = value;
+	const reason = record.reason;
+	const completed = typeof reason === "string" ? reason === "completed" : reason !== null && typeof reason === "object" && reason.kind === "completed";
+	return {
+		turn: turnNumber(record.turn),
+		completed
+	};
+}
+/**
+* Subscribe to completed root turns. Subagent turns are skipped so one task
+* announces once, and rapid turn boundaries collapse into a single event.
+* Returns a disposer that also drops pending debounces.
+*/
+function watchTaskCompletions(ctx, options) {
+	const debounceMs = options.debounceMs ?? 1e3;
+	const pending = /* @__PURE__ */ new Map();
+	const disposeListener = ctx.on("session/event", (session, event) => {
+		if (event.type !== "turn/end") return;
+		const { turn, completed } = turnData(event.data);
+		if (!completed) return;
+		if (session.header?.parentSession !== void 0 && session.header?.parentSession !== null) return;
+		const sessionId = String(session.id);
+		options.log?.("task-completed-observed", {
+			sessionId,
+			turn
+		});
+		const previous = pending.get(sessionId);
+		if (previous !== void 0) clearTimeout(previous);
+		pending.set(sessionId, setTimeout(() => {
+			pending.delete(sessionId);
+			options.log?.("task-completed-announced", {
+				sessionId,
+				turn
+			});
+			options.onTaskCompleted(Object.freeze({
+				sessionId,
+				turn
+			}));
+		}, debounceMs));
+	});
+	return () => {
+		disposeListener();
+		for (const timer of pending.values()) clearTimeout(timer);
+		pending.clear();
+	};
+}
+/** One subscription feeding every live gateway; gateways register on start. */
+var TaskEventHub = class {
+	sinks = /* @__PURE__ */ new Set();
+	/** Register a sink; returns its disposer. */
+	add(sink) {
+		this.sinks.add(sink);
+		return () => {
+			this.sinks.delete(sink);
+		};
+	}
+	/** Fan out to a snapshot so a failing sink cannot break its siblings. */
+	broadcast(event) {
+		for (const sink of [...this.sinks]) try {
+			sink.broadcastTaskEvent(event);
+		} catch {}
+	}
+	/** Visible for tests. */
+	get size() {
+		return this.sinks.size;
+	}
+};
+//#endregion
 //#region src/diagnostics.ts
 const REMOTE_ERROR_GUIDANCE = Object.freeze({
 	component_missing: "重新安装完整插件包。",
@@ -5921,7 +6250,8 @@ async function collectConnectionDiagnostics(snapshot, probes = {}) {
 	const remoteProbe = snapshot.remote.running && snapshot.remote.state === "ready" && snapshot.remote.origin !== void 0 ? (probes.remote ?? defaultRemoteProbe)(snapshot.remote.origin) : Promise.resolve({ state: "not-applicable" });
 	const [firewall, remoteObservation] = await Promise.all([(probes.firewall ?? defaultFirewallProbe())(snapshot.lan.port), remoteProbe]);
 	checks.push(check("versions", "ok", "versions-current", "版本兼容", `插件 ${DSH_MOBILE_VERSION}，DSH ${snapshot.dshVersion}，Android App 最低 ${MINIMUM_ANDROID_APP_VERSION}。`));
-	if (snapshot.lan.networkError !== void 0) checks.push(check("network", "error", "network-unavailable", "局域网网卡", "已保存的网卡当前不可用。", "重新运行 dsh-mobile setup。"));
+	if (snapshot.lan.configured === false) checks.push(check("network", "error", "lan-setup-required", "局域网配置", "尚未完成局域网初始化。", "返回局域网页选择网卡并完成配置。"));
+	else if (snapshot.lan.networkError !== void 0) checks.push(check("network", "error", "network-unavailable", "局域网网卡", "已保存的网卡当前不可用。", "重新运行 dsh-mobile setup。"));
 	else if (snapshot.lan.configuredInterface !== void 0) {
 		const interfaceName = snapshot.lan.interfaceName ?? snapshot.lan.configuredInterface;
 		checks.push(check("network", "ok", "network-interface", "局域网网卡", `正在跟随 ${interfaceName}。`, void 0, { interfaceName }));
@@ -6017,11 +6347,11 @@ const MOBILE_CUSTOMIZATION_GUIDE_BODY = `你在为用户定制 DSH Mobile 的手
 2. 电脑端能力 —— 手机需要读电脑文件、执行命令或访问硬件时，创建扩展：
    - 目录：$DSH_HOME/mobile-access/extensions/<id>/，id 用小写字母数字和连字符（如 media-remote）
    - extension.json：{"schemaVersion":1,"id":"<id>","name":"显示名","version":"0.1.0","description":"说明"}
-   - host.mjs：电脑端 Node.js 代码（可信本地代码，可读写文件、执行命令）。导出默认函数 (api) => { ... }，用 api.action('名称', { input, run }) 注册动作、api.route({ method, path, handle }) 注册路由、api.effect(fn) 注册清理
+   - host.mjs：电脑端 Node.js 代码（可信本地代码，可读写文件、执行命令）。导出默认函数 (api) => { ... }，用 api.action('名称', { input, run }) 注册动作、api.route({ method, path, handle }) 注册路由、api.effect(fn) 注册清理。input 可以直接使用 api.schema.object(...) 等 Schemastery schema，也可以传入带 parse(value) 的适配器；两种形式都会在动作执行前校验并规范化输入。
    - mobile.js：手机端脚本，用 window.dshMobile.define({ apiVersion:1, id:'<id>', activate(api) { ... } })，activate 返回清理函数
    - mobile.css：手机端样式（可选）
    - assets/：手机端静态资源（可选）
-   - mobile.js 里用 api.host.invoke('动作名', 输入) 调 host.mjs 的 action，api.host.fetch('/路由路径') 调 route，api.host.assetUrl('相对路径') 生成与当前版本绑定的资源地址
+   - mobile.js 里用 api.host.invoke('动作名', 输入) 调 host.mjs 的 action（请求会按 application/json 发送），api.host.fetch('/路由路径') 调 route，api.host.assetUrl('相对路径') 生成与当前版本绑定的资源地址
    - 也可以先用命令生成模板：dsh plugin --profile web exec dsh-mobile extension create <id> --name "<名称>"，再在模板上改
 
 安全约束：
@@ -7646,7 +7976,7 @@ var CpolarController = class {
 		const args = [
 			"http",
 			`-config=${resolve(this.options.configFile)}`,
-			`-region=${this.options.region ?? "cn"}`,
+			...this.options.region === void 0 ? [] : [`-region=${this.options.region}`],
 			"-inspect-addr=false",
 			"-redirect-https=true",
 			"-log=stdout",
@@ -8537,6 +8867,8 @@ const VIRTUAL_INTERFACE_MARKERS = [
 	"wsl",
 	"zerotier"
 ];
+/** Route inspection is advisory; never let a system command hold setup open indefinitely. */
+const ROUTE_COMMAND_TIMEOUT_MS = 5e3;
 function requiredString(value, name) {
 	if (typeof value !== "string" || value.length === 0) throw new Error(`${name} must be a non-empty string`);
 	return value;
@@ -8603,6 +8935,59 @@ function likelyVirtualInterface(name) {
 	const normalized = name.toLowerCase().replaceAll(/[^a-z0-9]+/gu, " ");
 	return VIRTUAL_INTERFACE_MARKERS.some((marker) => normalized.includes(marker.replaceAll("-", " "))) || /^(?:br|wg)\d*\b/u.test(normalized);
 }
+async function runRouteCommand(file, args) {
+	return (await execFileText(file, [...args], {
+		encoding: "utf8",
+		timeout: ROUTE_COMMAND_TIMEOUT_MS
+	})).stdout;
+}
+function uniqueLines(output) {
+	return [...new Set(output.split(/\r?\n/gu).map((line) => line.trim()).filter(Boolean))];
+}
+/** Return operating-system default-route interfaces in routing preference order. */
+async function preferredLanInterfaceNames(platform = process.platform, run = runRouteCommand) {
+	try {
+		if (platform === "win32") return uniqueLines(await run("powershell.exe", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			[
+				"$routes = Get-NetRoute -AddressFamily IPv4 -DestinationPrefix '0.0.0.0/0' -ErrorAction Stop",
+				"$ranked = $routes | Where-Object { $_.State -eq 'Alive' -and $_.NextHop -ne '0.0.0.0' } | ForEach-Object {",
+				"  $route = $_",
+				"  $adapter = Get-NetAdapter -InterfaceIndex $route.InterfaceIndex -ErrorAction SilentlyContinue",
+				"  $ip = Get-NetIPInterface -AddressFamily IPv4 -InterfaceIndex $route.InterfaceIndex -ErrorAction SilentlyContinue",
+				"  if ($adapter -and $ip -and $adapter.Status -eq 'Up' -and $adapter.HardwareInterface -eq $true -and $adapter.Virtual -ne $true) {",
+				"    [pscustomobject]@{ Name = $route.InterfaceAlias; Metric = [int]$route.RouteMetric + [int]$ip.InterfaceMetric }",
+				"  }",
+				"}",
+				"$ranked | Sort-Object Metric | Select-Object -ExpandProperty Name -Unique"
+			].join("; ")
+		]));
+		if (platform === "linux") {
+			const routes = uniqueLines(await run("ip", [
+				"-o",
+				"-4",
+				"route",
+				"show",
+				"default"
+			])).map((line) => ({
+				name: /(?:^|\s)dev\s+(\S+)/u.exec(line)?.[1],
+				metric: Number(/(?:^|\s)metric\s+(\d+)/u.exec(line)?.[1] ?? 0)
+			})).filter((route) => route.name !== void 0 && !likelyVirtualInterface(route.name)).sort((left, right) => left.metric - right.metric);
+			return [...new Set(routes.map((route) => route.name))];
+		}
+		if (platform === "darwin") {
+			const name = /^\s*interface:\s*(\S+)\s*$/mu.exec(await run("route", [
+				"-n",
+				"get",
+				"default"
+			]))?.[1];
+			return name === void 0 || likelyVirtualInterface(name) ? [] : [name];
+		}
+	} catch {}
+	return [];
+}
 /** Select an active LAN, optionally by address or by a previously saved interface name. */
 function selectLanNetwork(requestedAddress, requestedInterface, table, preferredInterfaces = []) {
 	const candidates = availableLanNetworks(table);
@@ -8653,6 +9038,57 @@ async function atomicWrite(file, contents) {
 	await rename(temporary, file);
 	await restrictPrivateFile(file);
 }
+/** Create a long-lived CA or migrate the legacy self-signed server certificate as that CA. */
+async function ensureManagedCa(setup, legacy) {
+	let certPem;
+	let keyPem;
+	try {
+		[certPem, keyPem] = await Promise.all([readFile(setup.caCertFile, "utf8"), readFile(setup.caKeyFile, "utf8")]);
+	} catch (error) {
+		if (error.code !== "ENOENT") throw error;
+		let migrated = false;
+		if (legacy !== void 0) try {
+			[certPem, keyPem] = await Promise.all([readFile(legacy.certFile, "utf8"), readFile(legacy.keyFile, "utf8")]);
+			assertMatchingCa(certPem, keyPem);
+			migrated = true;
+		} catch (legacyError) {
+			if (legacyError.code !== "ENOENT") throw legacyError;
+		}
+		if (!migrated) {
+			const now = /* @__PURE__ */ new Date();
+			const notAfter = new Date(now);
+			notAfter.setFullYear(notAfter.getFullYear() + 5);
+			const generated = await generate([{
+				name: "commonName",
+				value: "DeepSeek Harness Mobile CA"
+			}], {
+				keyType: "ec",
+				curve: "P-256",
+				algorithm: "sha256",
+				notBeforeDate: /* @__PURE__ */ new Date(now.getTime() - 3e5),
+				notAfterDate: notAfter,
+				extensions: [{
+					name: "basicConstraints",
+					cA: true,
+					critical: true
+				}, {
+					name: "keyUsage",
+					digitalSignature: true,
+					keyCertSign: true,
+					cRLSign: true,
+					critical: true
+				}]
+			});
+			certPem = generated.cert;
+			keyPem = generated.private;
+		}
+		if (certPem === void 0 || keyPem === void 0) throw new Error("managed TLS CA creation did not produce key material");
+		await Promise.all([atomicWrite(setup.caCertFile, certPem), atomicWrite(setup.caKeyFile, keyPem)]);
+	}
+	if (certPem === void 0 || keyPem === void 0) throw new Error("managed TLS CA creation did not produce key material");
+	await Promise.all([restrictPrivateFile(setup.caCertFile), restrictPrivateFile(setup.caKeyFile)]);
+	return assertMatchingCa(certPem, keyPem);
+}
 /** Sign and atomically install a server leaf for the interface's current address. */
 async function refreshManagedServerCertificate(setup, address) {
 	await Promise.all([restrictPrivateFile(setup.tls.caCertFile), restrictPrivateFile(setup.tls.caKeyFile)]);
@@ -8719,6 +9155,79 @@ async function materializeManagedSetup(setup, table) {
 	};
 }
 //#endregion
+//#region src/lan-setup.ts
+const FIREWALL_TCP_RULE = "DSH Mobile HTTPS";
+const FIREWALL_UDP_RULE = "DSH Mobile Discovery";
+async function runElevatedPowerShell(script) {
+	await execFileText("powershell.exe", [
+		"-NoProfile",
+		"-NonInteractive",
+		"-Command",
+		[
+			"$ErrorActionPreference = 'Stop'; $process = Start-Process -FilePath 'powershell.exe' -Verb RunAs -WindowStyle Hidden -Wait -PassThru",
+			`  -ArgumentList @('-NoProfile','-NonInteractive','-EncodedCommand','${Buffer.from(script, "utf16le").toString("base64")}')`,
+			"; exit $process.ExitCode"
+		].join(" ")
+	], { windowsHide: true });
+}
+/** Install the two Windows inbound rules used by the managed LAN listener. */
+async function configureWindowsFirewall(port) {
+	if (process.platform !== "win32") return;
+	await runElevatedPowerShell([
+		"$ErrorActionPreference = 'Stop'",
+		`Get-NetFirewallRule -DisplayName '${FIREWALL_TCP_RULE}' -ErrorAction SilentlyContinue | Remove-NetFirewallRule`,
+		`Get-NetFirewallRule -DisplayName '${FIREWALL_UDP_RULE}' -ErrorAction SilentlyContinue | Remove-NetFirewallRule`,
+		`New-NetFirewallRule -DisplayName '${FIREWALL_TCP_RULE}' -Direction Inbound -Action Allow -Protocol TCP -LocalPort ${String(port)} -RemoteAddress LocalSubnet -Profile Any | Out-Null`,
+		`New-NetFirewallRule -DisplayName '${FIREWALL_UDP_RULE}' -Direction Inbound -Action Allow -Protocol UDP -LocalPort ${String(port)} -RemoteAddress LocalSubnet -Profile Any | Out-Null`
+	].join("; "));
+}
+/** Generate private TLS material and persist a managed setup selected by the user. */
+async function prepareManagedLanSetup(options) {
+	if (!isAbsolute(options.setupFile) || !isAbsolute(options.controlFile)) throw new Error("managed LAN setup paths must be absolute");
+	if (!Number.isSafeInteger(options.listenPort) || options.listenPort < 1024 || options.listenPort > 65535) throw new Error("managed LAN listenPort must be from 1024 through 65535");
+	if (!Number.isSafeInteger(options.dshPort) || options.dshPort < 1024 || options.dshPort > 65535) throw new Error("managed LAN dshPort must be from 1024 through 65535");
+	const directory = dirname(options.setupFile);
+	const tlsDirectory = join(directory, "tls");
+	await mkdir(tlsDirectory, {
+		recursive: true,
+		mode: 448
+	});
+	const managedTls = {
+		mode: "managed",
+		caCertFile: join(tlsDirectory, "ca.pem"),
+		caKeyFile: join(tlsDirectory, "ca-key.pem"),
+		certFile: join(tlsDirectory, "server-cert.pem"),
+		keyFile: join(tlsDirectory, "server-key.pem")
+	};
+	const ca = await ensureManagedCa(managedTls, {
+		certFile: join(tlsDirectory, "cert.pem"),
+		keyFile: join(tlsDirectory, "key.pem")
+	});
+	const setup = {
+		version: 2,
+		networkInterface: options.network.name,
+		listenPort: options.listenPort,
+		upstreamOrigin: `http://127.0.0.1:${String(options.dshPort)}`,
+		tls: managedTls
+	};
+	await refreshManagedServerCertificate(setup, options.network.address);
+	const androidCertificate = join(tlsDirectory, "dsh-mobile-ca.cer");
+	await writeFile(androidCertificate, ca.raw, { mode: 384 });
+	await Promise.all([...Object.values(managedTls).filter((value) => value !== "managed").map((file) => restrictPrivateFile(file)), restrictPrivateFile(androidCertificate)]);
+	if (options.configureFirewall) await configureWindowsFirewall(options.listenPort);
+	await Promise.all([writeFile(options.setupFile, `${JSON.stringify({
+		...setup,
+		tls: Object.fromEntries(Object.entries(setup.tls).map(([key, value]) => [key, typeof value === "string" ? value.replaceAll("\\", "/") : value]))
+	}, null, 2)}\n`, { mode: 384 }), writeFile(options.controlFile, "{\"version\":1,\"enabled\":true}\n", { mode: 384 })]);
+	await Promise.all([restrictPrivateFile(options.setupFile), restrictPrivateFile(options.controlFile)]);
+	return Object.freeze({
+		setup: Object.freeze(setup),
+		network: Object.freeze({ ...options.network }),
+		origin: `https://${options.network.address}:${String(options.listenPort)}`,
+		androidCertificate
+	});
+}
+//#endregion
 //#region src/plugin.ts
 /** Stable Cordis plugin name. */
 const name = "dsh-mobile";
@@ -8792,6 +9301,7 @@ function mapAdminError(error) {
 	if (error instanceof Error && error.message.startsWith("vps_")) return new HttpError(409, error.message);
 	if (error instanceof Error && error.message === "plugin_update_failed") return new HttpError(500, error.message);
 	if (error instanceof Error && error.message.startsWith("plugin_update_")) return new HttpError(409, error.message);
+	if (error instanceof Error && error.message.startsWith("lan_setup_")) return new HttpError(409, error.message);
 	return new HttpError(500, "internal_error");
 }
 const SETUP_KEYS = /* @__PURE__ */ new Set([
@@ -8831,8 +9341,9 @@ async function loadSetup(config) {
 		source = await readFile(resolve(config.setupFile), "utf8");
 	} catch (error) {
 		if (error.code === "ENOENT") return {
-			kind: "fixed",
-			config
+			kind: "unconfigured",
+			config,
+			setupFile: resolve(config.setupFile)
 		};
 		throw error;
 	}
@@ -8939,6 +9450,13 @@ async function apply(ctx, config) {
 	const logFile = await installMobileFileLogger(ctx, stateDirectory);
 	const logger = ctx.logger("dsh-mobile");
 	logger.info("logging initialized file=%s", logFile);
+	const taskEventHub = new TaskEventHub();
+	const disposeTaskEvents = watchTaskCompletions(ctx, {
+		onTaskCompleted: (event) => taskEventHub.broadcast(event),
+		log(event, fields) {
+			logger.info("task event=%s fields=%o", event, fields);
+		}
+	});
 	const remoteDirectory = join(stateDirectory, "remote");
 	const configuredDshHome = process.env.DSH_HOME?.trim();
 	const releaseManager = new PluginReleaseManager({ profileDirectory: releaseProfileDirectory(ctx, configuredDshHome === void 0 || configuredDshHome === "" ? dirname(stateDirectory) : resolve(configuredDshHome), process.argv.slice(2)) });
@@ -8984,6 +9502,7 @@ async function apply(ctx, config) {
 	await webSocketPaths.load();
 	const blockedUpgradePaths = new BlockedUpgradePathLog();
 	let lanGateway;
+	let preparedLanSetup;
 	const startGateway = async (candidateConfig) => {
 		const resolved = parseGatewayConfig({
 			...candidateConfig,
@@ -8992,12 +9511,15 @@ async function apply(ctx, config) {
 		const candidate = new MobileAccessGateway(resolved, new JsonDeviceStore(resolved.stateFile, resolved.maxDevices), mobileAccess, upstreamLoginUrl, webSocketPaths, blockedUpgradePaths);
 		await candidate.start();
 		lanGateway = candidate;
+		const removeTaskSink = taskEventHub.add(candidate);
 		return { close: async () => {
 			if (lanGateway === candidate) lanGateway = void 0;
+			removeTaskSink();
 			await candidate.close();
 		} };
 	};
 	const startRuntime = async () => {
+		if (loaded.kind === "unconfigured") throw new Error(preparedLanSetup === void 0 ? "lan_setup_required" : "lan_setup_restart_required");
 		if (loaded.kind === "fixed") return startGateway(loaded.config);
 		const following = new FollowingMobileAccessRuntime(async () => {
 			const network = selectLanNetwork(void 0, loaded.setup.networkInterface);
@@ -9014,7 +9536,13 @@ async function apply(ctx, config) {
 		await following.initialize(2e3);
 		return following;
 	};
-	const lanController = new MobileAccessGatewayController(new JsonMobileAccessControlStore(parseControlFile(config.controlFile), config.initiallyEnabled), startRuntime);
+	const lanControlFile = parseControlFile(config.controlFile);
+	const lanControlStore = new JsonMobileAccessControlStore(lanControlFile, config.initiallyEnabled);
+	if (loaded.kind === "unconfigured" && (await lanControlStore.load()).enabled) await lanControlStore.save({
+		version: 1,
+		enabled: false
+	});
+	const lanController = new MobileAccessGatewayController(lanControlStore, startRuntime);
 	const remoteDeviceFile = join(remoteDirectory, "devices.json");
 	const legacyCpolarDeviceFile = join(remoteDirectory, "cpolar", "devices.json");
 	if (initialRemoteProvider === "cpolar") try {
@@ -9048,7 +9576,6 @@ async function apply(ctx, config) {
 			store: cpolarStore,
 			executable: cpolarComponent.executable,
 			configFile: cpolarComponent.configFile,
-			region: "cn",
 			createGateway: createRemoteGateway
 		}),
 		frp: new FrpController({
@@ -9061,16 +9588,51 @@ async function apply(ctx, config) {
 	};
 	const remoteProviders = new RemoteProviderCoordinator(initialRemoteProvider, remoteControllers, remoteProviderStore);
 	const remoteController = () => remoteProviders.controller();
+	for (const provider of [
+		"tailscale",
+		"cpolar",
+		"frp"
+	]) {
+		const controller = remoteControllers[provider];
+		taskEventHub.add({ broadcastTaskEvent: (event) => {
+			controller.gateway()?.broadcastTaskEvent(event);
+		} });
+	}
 	const remotePayload = () => remoteControlPayload(remoteProviders.selected, remoteController().status(), remoteController().gateway(), {
 		tailscale: remoteControllers.tailscale.status(),
 		cpolar: remoteControllers.cpolar.status(),
 		frp: remoteControllers.frp.status()
 	}, cpolarComponent.status(), frpComponent.status(), frpConfig.status());
 	const lanPayload = () => ({
+		...loaded.kind === "unconfigured" ? {
+			configured: preparedLanSetup !== void 0,
+			restartRequired: preparedLanSetup !== void 0
+		} : {},
 		running: lanController.isRunning(),
 		origin: lanGateway?.address().origin,
+		...preparedLanSetup === void 0 ? {} : { pendingOrigin: preparedLanSetup.origin },
 		...lanGateway === void 0 ? {} : { extensions: lanGateway.extensionStatus() }
 	});
+	const lanSetupPayload = async () => {
+		if (loaded.kind !== "unconfigured" || preparedLanSetup !== void 0) return lanPayload();
+		const networks = availableLanNetworks();
+		const preferred = await preferredLanInterfaceNames();
+		let recommendedAddress;
+		try {
+			recommendedAddress = selectLanNetwork(void 0, void 0, void 0, preferred).address;
+		} catch {}
+		return {
+			...lanPayload(),
+			networks: networks.map((network) => ({
+				name: network.name,
+				address: network.address,
+				cidr: network.cidr,
+				recommended: network.address === recommendedAddress
+			})),
+			listenPort: 3443,
+			windowsFirewall: process.platform === "win32"
+		};
+	};
 	const diagnosticsPayload = async () => {
 		let interfaceName;
 		let networkError;
@@ -9083,6 +9645,7 @@ async function apply(ctx, config) {
 		return collectConnectionDiagnostics({
 			dshVersion,
 			lan: {
+				configured: loaded.kind !== "unconfigured" || preparedLanSetup !== void 0,
 				running: lanController.isRunning(),
 				...lanGateway === void 0 ? {} : {
 					origin: lanGateway.address().origin,
@@ -9117,6 +9680,10 @@ async function apply(ctx, config) {
 					sendJson(response, 200, lanPayload(), false);
 					return;
 				}
+				if (request.method === "GET" && target.decodedPathname === `/api/mobile-access/lan/setup`) {
+					sendJson(response, 200, await lanSetupPayload(), false);
+					return;
+				}
 				if (request.method === "GET" && target.decodedPathname === `/api/mobile-access/diagnostics`) {
 					sendJson(response, 200, await diagnosticsPayload(), false);
 					return;
@@ -9133,10 +9700,37 @@ async function apply(ctx, config) {
 				if (request.method === "POST" && lanControl) {
 					const body = await readJsonObject(request, 4096);
 					if (typeof body.running !== "boolean") throw new HttpError(400, "bad_request");
+					if (body.running && loaded.kind === "unconfigured") throw new HttpError(409, preparedLanSetup === void 0 ? "lan_setup_required" : "lan_setup_restart_required");
 					await lanController.setRunning(body.running);
 					sendJson(response, 200, lanPayload(), false);
 					return;
 				}
+				if (request.method === "POST" && target.decodedPathname === `/api/mobile-access/lan/setup`) {
+					const body = await readJsonObject(request, 4096);
+					if (loaded.kind !== "unconfigured") throw new HttpError(409, "lan_setup_already_configured");
+					if (preparedLanSetup !== void 0) {
+						sendJson(response, 200, await lanSetupPayload(), false);
+						return;
+					}
+					if (body.confirm !== true || typeof body.address !== "string") throw new HttpError(400, "bad_request");
+					const network = availableLanNetworks().find((candidate) => candidate.address === body.address);
+					if (network === void 0) throw new HttpError(409, "lan_setup_network_unavailable");
+					try {
+						preparedLanSetup = await prepareManagedLanSetup({
+							setupFile: loaded.setupFile,
+							controlFile: lanControlFile,
+							network,
+							listenPort: 3443,
+							dshPort: ctx.webServer.port,
+							configureFirewall: body.configureFirewall !== false
+						});
+					} catch (error) {
+						logger.error("managed LAN setup failed: %s", error instanceof Error ? error.stack ?? error.message : String(error));
+						throw new HttpError(409, "lan_setup_failed");
+					}
+					sendJson(response, 200, await lanSetupPayload(), false);
+					return;
+				}
 				if (request.method === "GET" && target.decodedPathname === `/api/mobile-access/remote/control`) {
 					sendJson(response, 200, remotePayload(), false);
 					return;
@@ -9403,6 +9997,7 @@ async function apply(ctx, config) {
 				await settleCleanupSteps([
 					unregister,
 					disposeMobileCommand,
+					disposeTaskEvents,
 					async () => {
 						const failures = (await Promise.allSettled(Object.values(remoteControllers).map((controller) => controller.close()))).filter((result) => result.status === "rejected").map((result) => result.reason);
 						if (failures.length > 0) throw new AggregateError(failures, "remote provider cleanup failed");
@@ -9420,6 +10015,7 @@ async function apply(ctx, config) {
 			await settleCleanupSteps([
 				unregister,
 				disposeMobileCommand,
+				disposeTaskEvents,
 				async () => {
 					const failures = (await Promise.allSettled(Object.values(remoteControllers).map((controller) => controller.close()))).filter((result) => result.status === "rejected").map((result) => result.reason);
 					if (failures.length > 0) throw new AggregateError(failures, "remote provider cleanup failed");
@@ -9432,6 +10028,6 @@ async function apply(ctx, config) {
 	}, "dsh-mobile: independent LAN and selectable remote providers with /mobile command");
 }
 //#endregion
-export { AUTH_PREFIX, AccessController, AccessError, BlockedUpgradePathLog, BoundedRateLimiter, CSRF_COOKIE, CSRF_HEADER, Config, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, FRP_VHOST_HTTP_PORT, DEVICE_COOKIE, EXTENSION_LIMITS, FRP_CADDY_IMPORT_LINE, FRP_CADDY_SNIPPET_MARKER, FRP_CADDY_SNIPPET_PATH, FRP_COMPONENT_RELEASES, FrpComponentManager, FrpConfigStore, FrpController, JsonDeviceStore, JsonMobileAccessControlStore, JsonRemoteProviderStore, LOCAL_ADMIN_PREFIX, MAX_BLOCKED_UPGRADE_PATHS, MAX_EXTRA_WEBSOCKET_PATHS, MAX_WEBSOCKET_PATH_LENGTH, MemoryDeviceStore, MobileAccessGateway, MobileAccessGatewayController, MobileAccessService, MobileExtensionError, RequestTrustPolicy, SESSION_COOKIE, WS_PATHS, WebSocketPathStore, addressAllowed, apply, assertExtensionId, configuredRemoteProvider, createCaddySite, createFrpServerTemplate, createFrpcToml, createMobileAccessService, createRestrictedFrpServerTemplate, inject, isGloballyRoutableIpv4, isLoopbackAddress, mergeSavedFrpSettings, mergeSavedFrpTarget, name, normalizeWebSocketPaths, parseAuthority, parseCidr, parseControlFile, parseDeviceSnapshot, parseExtensionManifest, parseFrpSettings, parseGatewayConfig, parseMobileAccessControlState, parseRemoteProviderState, resolveAuthority, rewriteMobileIndex, validateFrpPublicOrigin, validateFrpServerAddress, validateFrpServerPort, validateFrpToken, validateWebSocketPath };
+export { AUTH_PREFIX, AccessController, AccessError, BlockedUpgradePathLog, BoundedRateLimiter, CSRF_COOKIE, CSRF_HEADER, Config, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, FRP_VHOST_HTTP_PORT, DEVICE_COOKIE, EXTENSION_LIMITS, FRP_CADDY_IMPORT_LINE, FRP_CADDY_SNIPPET_MARKER, FRP_CADDY_SNIPPET_PATH, FRP_COMPONENT_RELEASES, FrpComponentManager, FrpConfigStore, FrpController, JsonDeviceStore, JsonMobileAccessControlStore, JsonRemoteProviderStore, LOCAL_ADMIN_PREFIX, MAX_BLOCKED_UPGRADE_PATHS, MAX_EXTRA_WEBSOCKET_PATHS, MAX_WEBSOCKET_PATH_LENGTH, MemoryDeviceStore, MobileAccessGateway, MobileAccessGatewayController, MobileAccessService, MobileExtensionError, RequestTrustPolicy, SESSION_COOKIE, TASK_EVENT_DEBOUNCE_MS, TaskEventHub, WS_PATHS, WebSocketPathStore, addressAllowed, apply, assertExtensionId, configuredRemoteProvider, createCaddySite, createFrpServerTemplate, createFrpcToml, createMobileAccessService, createRestrictedFrpServerTemplate, inject, isGloballyRoutableIpv4, isLoopbackAddress, mergeSavedFrpSettings, mergeSavedFrpTarget, name, normalizeWebSocketPaths, parseAuthority, parseCidr, parseControlFile, parseDeviceSnapshot, parseExtensionManifest, parseFrpSettings, parseGatewayConfig, parseMobileAccessControlState, parseRemoteProviderState, resolveAuthority, rewriteMobileIndex, validateFrpPublicOrigin, validateFrpServerAddress, validateFrpServerPort, validateFrpToken, validateWebSocketPath, watchTaskCompletions };
 
 //# sourceMappingURL=index.mjs.map