dsh-mobile 0.4.6 → 0.5.0

package/lib/index.d.mts

@@ -1,6 +1,7 @@
 import { X509Certificate } from "node:crypto";
 import z from "@deepseek-ai/schemastery";
 import { ChildProcessWithoutNullStreams } from "node:child_process";
+import { IncomingMessage } from "node:http";
 import { Readable } from "node:stream";
 import { Context, Service } from "@deepseek-ai/cordis";
 import { WebRoute } from "@deepseek-ai/dsh-host-webserver";
@@ -262,6 +263,8 @@ interface PluginConfig {
   mobileLayoutFile?: string;
   /** Standalone browser compatibility bundle used before DSH boot. */
   mobileCompatibilityFile?: string;
+  /** Optional application-phase client package ids omitted only from the mobile boot graph. */
+  excludedClientModules?: string[];
   /** Stable public discovery identifier; it is not an authentication secret. */
   instanceId?: string;
   /** Managed CA certificate offered to the Android installer after fingerprint binding. */
@@ -302,6 +305,7 @@ interface ResolvedGatewayConfig {
   readonly customScriptFile: string;
   readonly mobileLayoutFile: string;
   readonly mobileCompatibilityFile: string;
+  readonly excludedClientModules: readonly string[];
   readonly instanceId: string;
   readonly pairingCaFile?: string;
   readonly tls: TlsConfig;
@@ -589,8 +593,8 @@ declare class MobileAccessService extends Service {
 declare function createMobileAccessService(ctx: Context): MobileAccessService;
 //#endregion
 //#region src/gateway.d.ts
-/** Replace only DSH's layout client module while retaining its complete plugin graph. */
-declare function rewriteMobileIndex(html: string): string;
+/** Rewrite the dedicated mobile graph; exclusions are opt-in and leave stock DSH unchanged. */
+declare function rewriteMobileIndex(html: string, excludedClientModules?: readonly string[]): string;
 /** Authenticated TLS edge in front of the ordinary loopback-only DSH Web server. */
 declare class MobileAccessGateway {
   readonly config: ResolvedGatewayConfig;
@@ -616,6 +620,7 @@ declare class MobileAccessGateway {
   private mdnsError;
   /** Names of the bundled mobile assets that could not be read, if any. */
   private mobileAssetError;
+  private lastModuleExclusionError;
   private bonjour;
   private pairingCaCertificate;
   private listenerPort;
@@ -752,7 +757,7 @@ declare class MobileAccessGateway {
   blockedUpgradePathReport(): BlockedUpgradePathEntry[];
   private handleUpgrade;
   /** Loopback-only DSH WebServer route for opening pairing and managing devices. */
-  localAdminRoute(prefix?: string): WebRoute;
+  localAdminRoute(prefix?: string, authenticateDesktop?: (request: IncomingMessage) => boolean): WebRoute;
   /** Close listeners and abort all accepted work before resolving teardown. */
   close(): Promise<void>;
   private performClose;

package/lib/index.mjs

@@ -761,6 +761,7 @@ const Config = z.object({
 	customScriptFile: z.string().hidden(),
 	mobileLayoutFile: z.string().hidden(),
 	mobileCompatibilityFile: z.string().hidden(),
+	excludedClientModules: z.array(String).default([]),
 	instanceId: z.string().hidden(),
 	pairingCaFile: z.string().hidden(),
 	initiallyEnabled: z.boolean().hidden().required(),
@@ -797,6 +798,13 @@ function absoluteFile(value, name) {
 	if (typeof value !== "string" || value.length === 0 || !isAbsolute(value)) throw new Error(`${name} must be an absolute file path`);
 	return resolve(value);
 }
+function excludedClientModules(value) {
+	if (value === void 0) return Object.freeze([]);
+	if (!Array.isArray(value) || value.some((id) => typeof id !== "string" || id.length === 0 || id.trim() !== id)) throw new Error("excludedClientModules must be an array of exact, non-empty client module ids");
+	const ids = value;
+	if (new Set(ids).size !== ids.length) throw new Error("excludedClientModules must not contain duplicate ids");
+	return Object.freeze([...ids]);
+}
 /** Resolve the hidden runtime-control file independently from gateway configuration. */
 function parseControlFile(value) {
 	return absoluteFile(value, "controlFile");
@@ -887,6 +895,7 @@ function parseGatewayConfig(raw) {
 		customScriptFile: value.customScriptFile === void 0 ? join(dirname(absoluteFile(value.stateFile, "stateFile")), "mobile.js") : absoluteFile(value.customScriptFile, "customScriptFile"),
 		mobileLayoutFile: value.mobileLayoutFile === void 0 ? fileURLToPath(new URL("./mobile-layout.js", import.meta.url)) : absoluteFile(value.mobileLayoutFile, "mobileLayoutFile"),
 		mobileCompatibilityFile: value.mobileCompatibilityFile === void 0 ? fileURLToPath(new URL("./mobile-compat.js", import.meta.url)) : absoluteFile(value.mobileCompatibilityFile, "mobileCompatibilityFile"),
+		excludedClientModules: excludedClientModules(value.excludedClientModules),
 		instanceId: value.instanceId === void 0 ? createHash("sha256").update(absoluteFile(value.stateFile, "stateFile")).digest("hex") : /^[a-f\d]{64}$/u.test(value.instanceId) ? value.instanceId : (() => {
 			throw new Error("instanceId must be a lowercase SHA-256 value");
 		})(),
@@ -1213,9 +1222,6 @@ var MobileAccessGatewayController = class {
 		return run;
 	}
 };
-//#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;
 }
@@ -1330,7 +1336,8 @@ function setSecurityHeaders(response, tls, framing = "gateway") {
 		"worker-src 'self' blob:",
 		...proxied ? [PROXIED_FRAME_SRC] : []
 	].join("; "));
-	response.setHeader("Permissions-Policy", "camera=(), microphone=(), geolocation=(), payment=(), usb=()");
+	const microphone = proxied ? "microphone=(self)" : "microphone=()";
+	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", proxied ? "SAMEORIGIN" : "DENY");
@@ -1427,7 +1434,7 @@ function localAuthority(header) {
 	}
 }
 /** Protect the inner management route from non-loopback and DNS-rebinding callers. */
-function assertLocalAdminTrust(request, requireBrowserOrigin) {
+function assertLocalAdminTrust(request, requireBrowserOrigin, authenticateDesktop = () => false) {
 	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 || !isLocalAdminHostname(host.hostname)) throw new HttpError(403, "forbidden");
@@ -1441,7 +1448,8 @@ function assertLocalAdminTrust(request, requireBrowserOrigin) {
 		if (error instanceof HttpError) throw error;
 		throw new HttpError(403, "forbidden");
 	}
-	if (requireBrowserOrigin && origin === void 0) throw new HttpError(403, "forbidden");
+	const desktopForward = site === void 0 && request.headers["x-dsh-mobile-desktop-admin"] === "dsh-app://app";
+	if (requireBrowserOrigin && origin === void 0 && !(desktopForward && authenticateDesktop())) throw new HttpError(403, "forbidden");
 	if (requireBrowserOrigin && site !== void 0 && site !== "same-origin") throw new HttpError(403, "forbidden");
 }
 //#endregion
@@ -2614,6 +2622,17 @@ const SIDEBAR_MODULE = "@deepseek-ai/dsh-client-ui-sidebar";
 const SETTINGS_MODULE = "@deepseek-ai/dsh-client-ui-settings";
 const API_GATEWAY_MODULE = "@deepseek-ai/dsh-api-gateway";
 const API_REMOTES_MODULE = "@deepseek-ai/dsh-api-remotes";
+const MOBILE_BOOT_CORE_MODULES = /* @__PURE__ */ new Set([
+	MOBILE_CLIENT_MODULE,
+	MOBILE_LAYOUT_MODULE,
+	CONNECTION_MODULE,
+	RUNTIME_MODULE,
+	RENDERER_MODULE,
+	SIDEBAR_MODULE,
+	SETTINGS_MODULE,
+	API_GATEWAY_MODULE,
+	API_REMOTES_MODULE
+]);
 const MOBILE_LAYOUT_DEPENDENCY_PROFILES = Object.freeze([Object.freeze({
 	slots: RUNTIME_MODULE,
 	dependencies: Object.freeze([RUNTIME_MODULE, "@deepseek-ai/dsh-client-ui-theme"])
@@ -2627,7 +2646,7 @@ 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 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},window.__DSH_FILE_UPLOAD__={fetch:(input,init)=>window.fetch(input,init)}})();`;
 /** Use this page's gateway health, rather than OS internet validation, for DSH reconnects. */
 const MOBILE_GATEWAY_REACHABILITY_BOOTSTRAP = `(()=>{
   const view=globalThis;
@@ -2719,13 +2738,49 @@ function revisionedMobileBatchPath(entries) {
 		path: `${MOBILE_BOOT_BATCH_PREFIX}${key}.js`
 	};
 }
+var ExcludedClientModulesError = class extends Error {
+	constructor(message) {
+		super(`excludedClientModules: ${message}`);
+	}
+};
+/** Validate graph edges before removing application rows from both manifest views. */
+function excludeMobileBootEntries(entries, batches, excludedIds) {
+	if (excludedIds.length === 0) return;
+	const excluded = new Set(excludedIds);
+	if (excluded.size !== excludedIds.length) throw new ExcludedClientModulesError("duplicate module ids");
+	const byId = new Map(entries.map((entry) => [entry.id, entry]));
+	const phases = /* @__PURE__ */ new Map();
+	for (const batch of batches) for (const id of batch.entries) {
+		if (phases.has(id)) throw new ExcludedClientModulesError(`upstream module ${id} belongs to multiple batches`);
+		phases.set(id, batch.phase);
+	}
+	for (const entry of entries) if (!phases.has(entry.id)) throw new ExcludedClientModulesError(`upstream module ${entry.id} belongs to no batch`);
+	for (const id of excluded) {
+		const entry = byId.get(id);
+		if (entry === void 0) throw new ExcludedClientModulesError(`module ${id} is not installed in this DSH client graph`);
+		if (MOBILE_BOOT_CORE_MODULES.has(id) || entry.immediately === true || phases.get(id) !== "application") throw new ExcludedClientModulesError(`module ${id} is required for mobile boot or belongs to a bootstrap batch`);
+	}
+	for (const entry of entries) {
+		if (excluded.has(entry.id)) continue;
+		for (const [field, edges] of [["inject", entry.inject], ["external", entry.external]]) {
+			if (edges !== void 0 && (!Array.isArray(edges) || edges.some((id) => typeof id !== "string"))) throw new ExcludedClientModulesError(`upstream module ${entry.id} has malformed ${field} dependencies`);
+			for (const dependency of edges ?? []) {
+				const packageId = dependency.endsWith("/client") ? dependency.slice(0, -7) : dependency;
+				if (excluded.has(packageId)) throw new ExcludedClientModulesError(`module ${entry.id} still depends on excluded module ${packageId}; exclude the dependent too or keep ${packageId}`);
+			}
+		}
+	}
+	entries.splice(0, entries.length, ...entries.filter((entry) => !excluded.has(entry.id)));
+	for (const batch of batches) batch.entries = batch.entries.filter((id) => !excluded.has(id));
+	batches.splice(0, batches.length, ...batches.filter((batch) => batch.entries.length > 0));
+}
 /**
 * Parse one upstream boot manifest and rewire the layout entry onto the
-* gateway-owned layout module. The layout entry's URL and revision become the
-* local `mobile-layout.js` path; the dedicated frontend is authenticated in the
-* gateway, so the requested layout needs no upstream address.
+* gateway-owned layout module. Optional exclusions remove application entries
+* and identify every affected batch for reassembly. The dedicated frontend is
+* authenticated in the gateway, so the layout needs no upstream address.
 */
-function parseMobileBootPlan(html) {
+function parseMobileBootPlan(html, excludedClientModules = []) {
 	const assignment = /(?:window\.__DSH_BOOT__|globalThis\["__DSH_BOOT__"\])\s*=\s*/u.exec(html);
 	if (assignment?.index === void 0) throw new Error("upstream DSH index has no boot manifest");
 	const replaceStart = assignment.index;
@@ -2744,14 +2799,17 @@ function parseMobileBootPlan(html) {
 	layout[0].url = MOBILE_LAYOUT_PATH;
 	layout[0].rev = `dsh-mobile-layout-${DSH_MOBILE_VERSION}`;
 	const parsedBatches = parsed.batches;
-	if (parsedBatches === void 0) return Object.freeze({
-		parsed,
-		entries,
-		slotProvider: dependencyProfile.slots,
-		assignment: assignment[0],
-		replaceStart,
-		replaceEnd: scriptEnd
-	});
+	if (parsedBatches === void 0) {
+		if (excludedClientModules.length > 0) throw new ExcludedClientModulesError("this DSH version has no batched boot manifest; disable exclusions or update DSH");
+		return Object.freeze({
+			parsed,
+			entries,
+			slotProvider: dependencyProfile.slots,
+			assignment: assignment[0],
+			replaceStart,
+			replaceEnd: scriptEnd
+		});
+	}
 	if (!Array.isArray(parsedBatches)) throw new Error("upstream DSH boot manifest batches are malformed");
 	const batches = parsedBatches;
 	const entryById = new Map(entries.map((entry) => [entry.id, entry]));
@@ -2763,15 +2821,26 @@ function parseMobileBootPlan(html) {
 	}
 	if (layoutBatches.length !== 1 || layoutBatches[0]?.phase !== "application") throw new Error("upstream DSH boot manifest has no unique application layout batch");
 	const layoutBatch = layoutBatches[0];
-	const planEntries = layoutBatch.entries.map((id) => {
-		const entry = entryById.get(id);
-		if (entry === void 0 || typeof entry.url !== "string" || typeof entry.rev !== "string") throw new Error("upstream DSH boot manifest batches are malformed");
-		return Object.freeze({
-			id,
-			url: entry.url,
-			rev: entry.rev
-		});
-	});
+	const originalApplicationBatches = batches.filter((batch) => batch.phase === "application").map((batch) => ({
+		...batch,
+		entries: [...batch.entries]
+	}));
+	excludeMobileBootEntries(entries, batches, excludedClientModules);
+	const affectedBatchUrls = new Set(originalApplicationBatches.filter((batch) => batch.entries.some((id) => excludedClientModules.includes(id))).map((batch) => batch.url));
+	const rewrittenBatchEntries = batches.filter((batch) => batch === layoutBatch || batch.phase === "application" && affectedBatchUrls.has(batch.url)).map((batch) => ({
+		batch,
+		entries: [...batch.entries].sort((left, right) => left < right ? -1 : left > right ? 1 : 0).map((id) => {
+			const entry = entryById.get(id);
+			if (entry === void 0 || typeof entry.url !== "string" || typeof entry.rev !== "string") throw new Error("upstream DSH boot manifest batches are malformed");
+			return Object.freeze({
+				id,
+				url: entry.url,
+				rev: entry.rev
+			});
+		})
+	}));
+	const planEntries = rewrittenBatchEntries.find((candidate) => candidate.batch === layoutBatch)?.entries;
+	if (planEntries === void 0) throw new Error("upstream DSH boot manifest lost the application layout batch");
 	return Object.freeze({
 		parsed,
 		entries,
@@ -2781,7 +2850,9 @@ function parseMobileBootPlan(html) {
 		replaceStart,
 		replaceEnd: scriptEnd,
 		layoutBatch,
-		planEntries
+		planEntries,
+		originalApplicationBatches,
+		rewrittenBatchEntries
 	});
 }
 /**
@@ -2840,30 +2911,62 @@ function splitMobileBootBatch(entries, sizes, passThrough) {
 		rows
 	};
 }
+function escapeMobilePreloadAttribute(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function mobileApplicationPreload(url) {
+	return `<link rel="preload" as="script" href="${escapeMobilePreloadAttribute(url)}">`;
+}
+function preloadAttribute(tag, name) {
+	const match = new RegExp(`(?:^|\\s)${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`, "iu").exec(tag);
+	return match?.[1] ?? match?.[2];
+}
+/** Replace only DSH's application-script preloads; bootstrap and unrelated links are untouched. */
+function rewriteMobileApplicationPreloads(html, replacements) {
+	if (replacements.size === 0) return html;
+	const escaped = new Map([...replacements].map(([url, markup]) => [escapeMobilePreloadAttribute(url), markup]));
+	return html.replace(/<link\b[^>]*>/giu, (tag) => {
+		if (!preloadAttribute(tag, "rel")?.split(/\s+/u).includes("preload") || preloadAttribute(tag, "as") !== "script") return tag;
+		return escaped.get(preloadAttribute(tag, "href") ?? "") ?? tag;
+	});
+}
 function rewriteMobileIndexWithBatch(html, options = {}) {
-	const plan = parseMobileBootPlan(html);
+	const plan = parseMobileBootPlan(html, options.excludedClientModules);
 	const remoteSettings = orderAuthenticatedSettings(plan.entries, plan.slotProvider);
 	let batches = [];
-	if (plan.batches !== void 0 && plan.layoutBatch !== void 0 && plan.planEntries !== void 0) {
-		const split = splitMobileBootBatch(plan.planEntries, options.sizes ?? /* @__PURE__ */ new Map(), options.passThrough ?? /* @__PURE__ */ new Set());
-		const at = plan.batches.indexOf(plan.layoutBatch);
-		if (at < 0) throw new Error("upstream DSH boot manifest has no unique application layout batch");
-		plan.batches.splice(at, 1, ...split.rows);
-		batches = Object.freeze(split.plans);
+	let preloadReplacements = /* @__PURE__ */ new Map();
+	if (plan.batches !== void 0 && plan.rewrittenBatchEntries !== void 0) {
+		const rewrites = plan.rewrittenBatchEntries.map(({ batch, entries }) => ({
+			batch,
+			split: splitMobileBootBatch(entries, options.sizes ?? /* @__PURE__ */ new Map(), options.passThrough ?? /* @__PURE__ */ new Set())
+		}));
+		if (rewrites.reduce((count, item) => count + item.split.plans.length, 0) > MAX_MOBILE_BOOT_BATCHES) throw new Error(`upstream DSH mobile boot requires more than ${String(MAX_MOBILE_BOOT_BATCHES)} merged batches`);
+		for (const { batch, split } of rewrites) {
+			const at = plan.batches.indexOf(batch);
+			if (at < 0) throw new Error("upstream DSH boot manifest lost an application batch");
+			plan.batches.splice(at, 1, ...split.rows);
+			batches = [...batches, ...split.plans];
+		}
+		for (const original of plan.originalApplicationBatches ?? []) {
+			const replacement = rewrites.find((item) => item.batch.url === original.url);
+			preloadReplacements.set(original.url, replacement === void 0 ? plan.batches.some((batch) => batch.url === original.url) ? mobileApplicationPreload(original.url) : "" : replacement.split.rows.map((row) => mobileApplicationPreload(row.url)).join(""));
+		}
+		batches = Object.freeze(batches);
 		plan.parsed.rev = createHash("sha256").update(JSON.stringify({
 			entries: plan.entries,
 			batches: plan.batches
 		})).digest("hex").slice(0, 16);
 	}
 	const replacement = `${MOBILE_GATEWAY_REACHABILITY_BOOTSTRAP}${remoteSettings ? MOBILE_AUTHENTICATED_TRANSPORT_BOOTSTRAP : ""}${MOBILE_CSRF_FETCH_BOOTSTRAP}window.__DSH_MOBILE_FRONTEND__="dedicated";${plan.assignment}${JSON.stringify(plan.parsed)};`;
+	const rewritten = `${html.slice(0, plan.replaceStart)}${replacement}${html.slice(plan.replaceEnd)}`;
 	return Object.freeze({
-		html: ensureMobileViewport(ensureMobileCompatibility(`${html.slice(0, plan.replaceStart)}${replacement}${html.slice(plan.replaceEnd)}`)),
+		html: ensureMobileViewport(ensureMobileCompatibility(rewriteMobileApplicationPreloads(rewritten, preloadReplacements))),
 		batches
 	});
 }
-/** Replace only DSH's layout client module while retaining its complete plugin graph. */
-function rewriteMobileIndex(html) {
-	return rewriteMobileIndexWithBatch(html).html;
+/** Rewrite the dedicated mobile graph; exclusions are opt-in and leave stock DSH unchanged. */
+function rewriteMobileIndex(html, excludedClientModules = []) {
+	return rewriteMobileIndexWithBatch(html, { excludedClientModules }).html;
 }
 var ByteLimitTransform = class extends Transform {
 	maximum;
@@ -3307,6 +3410,7 @@ var MobileAccessGateway = class {
 	mdnsError;
 	/** Names of the bundled mobile assets that could not be read, if any. */
 	mobileAssetError;
+	lastModuleExclusionError;
 	bonjour;
 	pairingCaCertificate;
 	listenerPort;
@@ -4276,11 +4380,26 @@ var MobileAccessGateway = class {
 			let body;
 			try {
 				const html = Buffer.concat(chunks).toString("utf8");
-				const plan = parseMobileBootPlan(html);
-				const rewritten = rewriteMobileIndexWithBatch(html, plan.planEntries === void 0 ? {} : await this.resolveMobileBootSizes(plan.planEntries));
+				const plan = parseMobileBootPlan(html, this.config.excludedClientModules);
+				const rewritten = rewriteMobileIndexWithBatch(html, plan.rewrittenBatchEntries === void 0 ? { excludedClientModules: this.config.excludedClientModules } : {
+					...await this.resolveMobileBootSizes(plan.rewrittenBatchEntries.flatMap((batch) => batch.entries)),
+					excludedClientModules: this.config.excludedClientModules
+				});
 				for (const batch of rewritten.batches) this.rememberMobileBootBatch(batch);
 				body = Buffer.from(rewritten.html);
-			} catch {
+			} catch (error) {
+				if (error instanceof ExcludedClientModulesError) {
+					const detail = error.message.replace(/[\r\n]/gu, " ").slice(0, 512);
+					if (detail !== this.lastModuleExclusionError) {
+						this.lastModuleExclusionError = detail;
+						process.emitWarning(detail, { code: "DSH_MOBILE_MODULE_EXCLUSION_INVALID" });
+					}
+					sendJson(response, 409, {
+						error: "excluded_client_modules_invalid",
+						detail
+					}, this.tlsEnabled);
+					return;
+				}
 				throw new HttpError(502, "upstream_unavailable");
 			}
 			const headers = sanitizeResponseHeaders(proxied.headers, this.config.upstreamOrigin);
@@ -4965,14 +5084,14 @@ var MobileAccessGateway = class {
 		}
 	}
 	/** Loopback-only DSH WebServer route for opening pairing and managing devices. */
-	localAdminRoute(prefix = LOCAL_ADMIN_PREFIX) {
+	localAdminRoute(prefix = LOCAL_ADMIN_PREFIX, authenticateDesktop) {
 		return {
 			kind: "prefix",
 			path: prefix,
 			handler: async (request, response) => {
 				try {
 					const target = parseRequestTarget(request.url);
-					assertLocalAdminTrust(request, request.method === "POST");
+					assertLocalAdminTrust(request, request.method === "POST", () => authenticateDesktop?.(request) === true);
 					if (target.search !== "") throw new HttpError(400, "bad_request");
 					if (request.method === "GET" && target.decodedPathname === `${prefix}/status`) {
 						sendJson(response, 200, {
@@ -9389,6 +9508,10 @@ var TaskEventHub = class {
 };
 //#endregion
 //#region src/diagnostics.ts
+/** Recognize the active remote-web-ui boot hook without evaluating or modifying it. */
+function hasCompetingRemoteChannelBoot(rows) {
+	return rows.some((row) => row.kind === "script" && row.text?.includes("__DSH_REMOTE_CHANNEL_BOOT__") === true);
+}
 const REMOTE_ERROR_GUIDANCE = Object.freeze({
 	component_missing: "重新安装完整插件包。",
 	funnel_permission_required: "继续完成 Tailscale Funnel 授权。",
@@ -9783,6 +9906,7 @@ async function collectConnectionDiagnostics(snapshot, probes = {}) {
 	const remoteProbe = snapshot.remote.provider !== "origin" && 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.competingRemoteChannelBoot === true) checks.push(check("remote-plugin-conflict", "warning", "competing-remote-channel", "第三方远程插件", "检测到另一套远程请求通道脚本；手机页面可能进入该插件自己的配对流程。", "在电脑端关闭 dsh-remote-web-ui 的远程访问后刷新，再使用 DSH Mobile 当前二维码配对；不要混用两种配对码。"));
 	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) {
@@ -11731,6 +11855,87 @@ async function regularFile(file, expectedBytes) {
 		throw error;
 	}
 }
+async function installStep(code, operation) {
+	try {
+		return await operation();
+	} catch (error) {
+		if (error instanceof Error && error.message.startsWith("cpolar_")) throw error;
+		throw new Error(code, { cause: error });
+	}
+}
+async function pathExists(path) {
+	try {
+		await lstat(path);
+		return true;
+	} catch (error) {
+		if (error.code === "ENOENT") return false;
+		throw error;
+	}
+}
+/** Replace only this version's verified binary, retaining the previous directory until promotion succeeds. */
+async function publishVerifiedCpolarExecutable(extracted, componentRoot, componentStorage, executableName, operations = {}) {
+	if (dirname(componentStorage) !== componentRoot || !inside(componentRoot, componentStorage) || basename(executableName) !== executableName || executableName === "." || executableName === "..") throw new Error("cpolar component storage escaped its private root");
+	const move = operations.move ?? rename;
+	const remove = operations.remove ?? ((path) => rm(path, {
+		recursive: true,
+		force: true
+	}));
+	const candidate = join(componentRoot, `.install-${randomBytes(12).toString("hex")}`);
+	const backup = join(componentRoot, `.previous-${randomBytes(12).toString("hex")}`);
+	let backupContainsPrevious = false;
+	let replacementInstalled = false;
+	try {
+		await mkdir(candidate, {
+			recursive: true,
+			mode: 448
+		});
+		await copyFile(extracted, join(candidate, executableName));
+		await chmod(join(candidate, executableName), 448);
+		if (await pathExists(componentStorage)) {
+			await move(componentStorage, backup);
+			backupContainsPrevious = true;
+		}
+		try {
+			await move(candidate, componentStorage);
+			replacementInstalled = true;
+		} catch (error) {
+			if (backupContainsPrevious) try {
+				await move(backup, componentStorage);
+				backupContainsPrevious = false;
+			} catch (rollbackError) {
+				process.emitWarning(`cpolar previous component remains at ${backup}; automatic rollback failed`, { code: "DSH_MOBILE_CPOLAR_ROLLBACK_FAILED" });
+				throw new Error("cpolar_storage_failed", { cause: new AggregateError([error, rollbackError]) });
+			}
+			throw error;
+		}
+	} finally {
+		try {
+			await remove(candidate);
+		} catch {
+			process.emitWarning(`cpolar temporary component remains at ${candidate}; cleanup failed`, { code: "DSH_MOBILE_CPOLAR_CLEANUP_FAILED" });
+		}
+		if (replacementInstalled && backupContainsPrevious) try {
+			await remove(backup);
+		} catch {
+			process.emitWarning(`cpolar previous component remains at ${backup}; cleanup failed`, { code: "DSH_MOBILE_CPOLAR_CLEANUP_FAILED" });
+		}
+	}
+}
+/** Remove only this install's staging directory without replacing a preceding failure. */
+async function cleanupCpolarInstallStaging(staging, installFailed, remove = (path) => rm(path, {
+	recursive: true,
+	force: true
+})) {
+	try {
+		await remove(staging);
+	} catch (error) {
+		if (installFailed) {
+			process.emitWarning(`cpolar staging directory remains at ${staging}; cleanup failed`, { code: "DSH_MOBILE_CPOLAR_CLEANUP_FAILED" });
+			return;
+		}
+		throw new Error("cpolar_storage_failed", { cause: error });
+	}
+}
 async function run(file, args) {
 	await new Promise((resolveRun, reject) => {
 		execFile(file, [...args], {
@@ -11885,11 +12090,14 @@ var CpolarComponentManager = class {
 		return this.enqueue(async () => {
 			const release = this.release;
 			if (release === void 0) throw new Error("cpolar_component_unsupported");
-			await mkdir(this.stagingRoot, {
-				recursive: true,
-				mode: 448
+			const staging = await installStep("cpolar_storage_failed", async () => {
+				await mkdir(this.stagingRoot, {
+					recursive: true,
+					mode: 448
+				});
+				return mkdtemp(join(this.stagingRoot, "install-"));
 			});
-			const staging = await mkdtemp(join(this.stagingRoot, "install-"));
+			let installFailed = false;
 			try {
 				const controller = new AbortController();
 				const timeout = setTimeout(() => {
@@ -11898,38 +12106,35 @@ var CpolarComponentManager = class {
 				timeout.unref();
 				let bytes;
 				try {
-					bytes = await this.fetchArtifact(release.downloadUrl, controller.signal);
+					bytes = await installStep("cpolar_download_failed", () => this.fetchArtifact(release.downloadUrl, controller.signal));
+				} catch (error) {
+					if (controller.signal.aborted) throw new Error("cpolar_download_timeout", { cause: error });
+					throw error;
 				} finally {
 					clearTimeout(timeout);
 				}
 				if (createHash("sha256").update(bytes).digest("hex") !== release.downloadSha256) throw new Error("cpolar_download_hash_mismatch");
 				const archive = join(staging, release.archiveKind === "tar.gz" ? "cpolar.tar.gz" : "cpolar.zip");
-				await writeFile(archive, bytes, {
+				await installStep("cpolar_storage_failed", () => writeFile(archive, bytes, {
 					flag: "wx",
 					mode: 384
-				});
-				await this.extractArtifact(archive, staging);
+				}));
+				await installStep("cpolar_extract_failed", () => this.extractArtifact(archive, staging));
 				const extracted = join(staging, release.executableName);
-				if (!await regularFile(extracted, release.executableBytes) || await sha256(extracted) !== release.executableSha256) throw new Error("cpolar_executable_hash_mismatch");
-				const candidate = join(this.componentRoot, `.install-${randomBytes(12).toString("hex")}`);
-				await mkdir(candidate, {
-					recursive: true,
-					mode: 448
-				});
-				await copyFile(extracted, join(candidate, release.executableName));
-				await chmod(join(candidate, release.executableName), 448);
-				await rm(this.componentStorage, {
-					recursive: true,
-					force: true
-				});
-				await rename(candidate, this.componentStorage);
+				if (!await installStep("cpolar_extract_failed", async () => await regularFile(extracted, release.executableBytes) && await sha256(extracted) === release.executableSha256)) throw new Error("cpolar_executable_hash_mismatch");
+				await installStep("cpolar_storage_failed", () => publishVerifiedCpolarExecutable(extracted, this.componentRoot, this.componentStorage, release.executableName));
 				this.installed = true;
 				this.errorCode = void 0;
+			} catch (error) {
+				installFailed = true;
+				try {
+					this.installed = await regularFile(this.executable, release.executableBytes) && await sha256(this.executable) === release.executableSha256;
+				} catch (_inspectionError) {
+					this.installed = false;
+				}
+				throw error;
 			} finally {
-				await rm(staging, {
-					recursive: true,
-					force: true
-				});
+				await cleanupCpolarInstallStaging(staging, installFailed);
 			}
 		});
 	}
@@ -13103,6 +13308,7 @@ async function apply(ctx, config) {
 		} : void 0;
 		return collectConnectionDiagnostics({
 			dshVersion,
+			competingRemoteChannelBoot: hasCompetingRemoteChannelBoot(ctx.webServer.collectIndexInjections?.() ?? []),
 			lan: {
 				configured: loaded.kind !== "unconfigured" || preparedLanSetup !== void 0,
 				running: lanController.isRunning(),
@@ -13126,13 +13332,17 @@ async function apply(ctx, config) {
 			}
 		}, pinnedFrpProbe === void 0 ? {} : { remote: pinnedFrpProbe });
 	};
+	const authenticateDesktopAdmin = (request) => {
+		const connection = ctx.connection;
+		return typeof connection?.requestRejection === "function" && connection.requestRejection(request) === void 0;
+	};
 	const adminRoute = {
 		kind: "prefix",
 		path: LOCAL_ADMIN_PREFIX,
 		handler: async (request, response) => {
 			try {
 				const target = parseRequestTarget(request.url);
-				assertLocalAdminTrust(request, request.method === "POST");
+				assertLocalAdminTrust(request, request.method === "POST", () => authenticateDesktopAdmin(request));
 				if (target.search !== "") throw new HttpError(400, "bad_request");
 				const lanControl = target.decodedPathname === `/api/mobile-access/control` || target.decodedPathname === `/api/mobile-access/lan/control`;
 				if (request.method === "GET" && lanControl) {
@@ -13221,7 +13431,15 @@ async function apply(ctx, config) {
 				}
 				if (request.method === "POST" && target.decodedPathname === `/api/mobile-access/remote/cpolar/component/install`) {
 					if ((await readJsonObject(request, 4096)).confirm !== true) throw new HttpError(400, "bad_request");
-					await remoteProviders.mutate(async () => cpolarComponent.install());
+					logger.info("cpolar component install started");
+					try {
+						await remoteProviders.mutate(async () => cpolarComponent.install());
+						logger.info("cpolar component install completed");
+					} catch (error) {
+						const cause = error instanceof Error && error.cause instanceof Error ? error.cause : void 0;
+						logger.error("cpolar component install failed: %s%s", error instanceof Error ? error.stack ?? error.message : String(error), cause === void 0 ? "" : `; cause: ${cause.message}`);
+						throw error;
+					}
 					sendJson(response, 200, remotePayload(), false);
 					return;
 				}
@@ -13464,18 +13682,18 @@ async function apply(ctx, config) {
 				if (target.decodedPathname.startsWith(`/api/mobile-access/remote/`)) {
 					const active = remoteController().gateway();
 					if (active === void 0) throw new HttpError(409, "gateway_stopped");
-					await active.localAdminRoute(`${LOCAL_ADMIN_PREFIX}/remote`).handler(request, response);
+					await active.localAdminRoute(`${LOCAL_ADMIN_PREFIX}/remote`, authenticateDesktopAdmin).handler(request, response);
 					return;
 				}
 				if (target.decodedPathname.startsWith(`/api/mobile-access/lan/`)) {
 					const active = lanGateway;
 					if (active === void 0) throw new HttpError(409, "gateway_stopped");
-					await active.localAdminRoute(`${LOCAL_ADMIN_PREFIX}/lan`).handler(request, response);
+					await active.localAdminRoute(`${LOCAL_ADMIN_PREFIX}/lan`, authenticateDesktopAdmin).handler(request, response);
 					return;
 				}
 				const active = lanGateway;
 				if (active === void 0) throw new HttpError(409, "gateway_stopped");
-				await active.localAdminRoute().handler(request, response);
+				await active.localAdminRoute(LOCAL_ADMIN_PREFIX, authenticateDesktopAdmin).handler(request, response);
 			} catch (error) {
 				const mapped = mapAdminError(error);
 				if (response.headersSent) response.destroy();