@linxin666/dsh-remote-web-ui 0.4.5 → 0.4.7

package/lib/index.js

@@ -989,6 +989,62 @@ const REMOTE_CHANNEL_RULES = {
 /** The window global the boot patch publishes its seat under. */
 const REMOTE_CHANNEL_BOOT_GLOBAL = "__DSH_REMOTE_CHANNEL_BOOT__";
 //#endregion
+//#region src/lan-source.ts
+/**
+* The landing page's network-source decision: which origin a paired phone
+* should keep using.
+*
+* The QR link can only name one base, and the server cannot know whether the
+* scanning phone sits on this machine's own network: the public (relayed)
+* base is the only one that is always reachable, so the QR names it and the
+* phone decides at connect time. The device-gated landing (/pair-app) is the
+* plugin's own page already rendered ahead of the official shell's boot, so it
+* is the natural place to probe: after the page is served, a short
+* cross-origin `fetch` per LAN candidate (a no-cors GET at
+* {@link LAN_PING_PATH}) tells the browser whether that LAN origin answers,
+* and the first one that does becomes the new origin. A probe that finds
+* nothing, or that runs out of budget, changes nothing — the page the phone
+* already holds stays paired and usable, so the probe can never block pairing.
+*
+* Browsers do not block this probe. An https page may not normally fetch
+* `http://` subresources, but a host that is an IP literal is exempt from both
+* the block and the automatic upgrade (verified against Chrome: the console
+* reports "This request was not upgraded to HTTPS because its URL's host is an
+* IP address" and delivers the response), which is exactly the shape every LAN
+* candidate has.
+*
+* @module @linxin666/dsh-remote-web-ui/lan-source
+*/
+/** sessionStorage key holding this session's source decision. */
+const LAN_SOURCE_STORAGE_KEY = "dsh-remote-lan-source";
+/**
+* How recently a LAN hop must have been taken for a return to a non-LAN origin
+* to read as "the hop did not stick". A phone that fails to load the LAN page
+* re-scans the QR (which always names the public base) within seconds, and the
+* landing then has to choose the public source instead of hopping again into
+* the same black hole; a deliberate return much later is a fresh decision and
+* re-probes.
+*/
+const LAN_SOURCE_RETRY_WINDOW_MS = 12e4;
+/**
+* Build the inline script that runs the source decision on the landing page.
+* Reads every browser global through `window`, so a test can run it against
+* one fake object (the same seam the parse-time boot patch uses).
+* @param hop - the probe payload for this landing render.
+* @returns the `<script>` element to splice into the landing's head.
+*/
+function appShellLanSwitchScript(hop) {
+	return `<script>${"(function(){try{var w=window,loc=w.location;var P=" + JSON.stringify({
+		key: LAN_SOURCE_STORAGE_KEY,
+		candidates: hop.candidates,
+		path: hop.path,
+		ping: hop.pingPath,
+		grant: hop.grant,
+		timeout: 800,
+		retry: LAN_SOURCE_RETRY_WINDOW_MS
+	}) + ";var S=w.sessionStorage;P.sig=P.candidates.join(\",\");function rd(){try{var raw=S.getItem(P.key);if(typeof raw!==\"string\"||raw===\"\")return undefined;var d=JSON.parse(raw);if(typeof d!==\"object\"||d===null)return undefined;if(d.src!==\"lan\"&&d.src!==\"public\")return undefined;if(typeof d.sig!==\"string\"||typeof d.at!==\"number\")return undefined;return d}catch(e){return undefined}}function wr(d){try{S.setItem(P.key,JSON.stringify(d))}catch(e){}}function own(){for(var i=0;i<P.candidates.length;i++){if(P.candidates[i]===loc.origin)return true}return false}function go(base){try{loc.replace(base+P.path+\"?grant=\"+encodeURIComponent(P.grant))}catch(e){}}function probe(){if(typeof w.fetch!==\"function\")return;var settled=false;var timer=w.setTimeout(function(){finish(undefined)},P.timeout);function finish(base){if(settled)return;settled=true;try{w.clearTimeout(timer)}catch(e){}if(base===undefined){wr({src:\"public\",sig:P.sig,at:Date.now()});return}wr({src:\"lan\",sig:P.sig,base:base,at:Date.now()});go(base)}for(var i=0;i<P.candidates.length;i++){(function(base){var sent;try{sent=w.fetch(base+P.ping,{mode:\"no-cors\",cache:\"no-store\",credentials:\"omit\",referrerPolicy:\"no-referrer\"})}catch(e){sent=undefined}if(sent===undefined||typeof sent.then!==\"function\")return;sent.then(function(){finish(base)},function(){})})(P.candidates[i])}}var d=rd();if(own()){if(d===undefined||d.sig!==P.sig)wr({src:\"lan\",sig:P.sig,base:loc.origin,at:Date.now()});return}if(d!==undefined&&d.sig===P.sig){if(d.src===\"public\")return;if(Date.now()-d.at<P.retry){wr({src:\"public\",sig:P.sig,at:Date.now()});return}}probe()}catch(e){}})();"}<\/script>`;
+}
+//#endregion
 //#region src/routes.ts
 /**
 * Browser-trust fence for the /api/pair routes, mirroring the connection
@@ -1208,18 +1264,26 @@ const COOKIE_MAX_AGE_SEC = 365 * 24 * 60 * 60;
 * The cookieless device credential: pass the device id from the /pair-app
 * URL into sessionStorage (and localStorage for tab reloads) before any app
 * script runs - same key the boot patch and the channel gate read. The
-* replaceState to '/' hides the credential URL from the address bar and
-* leaves the SPA at its canonical root path. The reopen service worker is
-* registered in the same breath: later navigations to '/' (history,
-* bookmark, tab restore) must not fall through to the harness index gate,
-* which the cookieless flow can never satisfy.
+* replaceState drops the one-time grant from the address bar and leaves the
+* SPA on a path this plugin answers again; which path depends on the origin.
+*
+* A secure context registers the reopen service worker in the same breath,
+* and that worker owns navigations to '/', so the SPA keeps its canonical
+* root. A plain-HTTP LAN origin is never a secure context, so the worker
+* cannot exist there and '/' falls through to the harness index gate the
+* cookieless flow can never satisfy (issue #1867). The address bar therefore
+* keeps the plugin-owned landing path, which re-validates the device
+* credential on every reload and serves the bilingual re-pair page once the
+* pairing is gone. Both targets are bare paths: the one-time grant never
+* survives the rewrite, and no credential is ever left in the URL.
 */
 const APP_DEVICE_STORAGE_KEY = "dsh-remote-device";
 function appShellCaptureScript(deviceId) {
 	const safeId = JSON.stringify(deviceId);
 	const grantGlobal = JSON.stringify(REMOTE_HOST_GRANT_GLOBAL);
+	const reopenPath = JSON.stringify(PAIR_PATHS.appPage);
 	const register = `try{if('serviceWorker' in navigator){navigator.serviceWorker.register(${JSON.stringify(PAIR_PATHS.appServiceWorker)},{scope:'/'}).catch(function(e){})}}catch(e){}`;
-	return `<script>(function(){try{sessionStorage.setItem(${JSON.stringify(APP_DEVICE_STORAGE_KEY)},${safeId});}catch(e){}try{history.replaceState(null,'','/')}catch(e){}try{window[${grantGlobal}]=true}catch(e){}${register}})()<\/script>`;
+	return `<script>(function(){try{sessionStorage.setItem(${JSON.stringify(APP_DEVICE_STORAGE_KEY)},${safeId});}catch(e){}try{history.replaceState(null,'',window.isSecureContext?'/':${reopenPath})}catch(e){}try{window[${grantGlobal}]=true}catch(e){}${register}})()<\/script>`;
 }
 /**
 * Patch the official index document with the device-capture script. The script
@@ -1228,9 +1292,19 @@ function appShellCaptureScript(deviceId) {
 * hook only when this server-served marker is already set (see
 * remote-channel-boot.ts), so host mode is granted by the device-gated landing
 * instead of being asserted from the origin.
+*
+* A landing reached on a base other than the machine's own LAN origin also
+* carries the source-decision script (lan-source.ts): the phone decides at
+* connect time whether a LAN candidate answers, and switches its origin when
+* one does. It runs after the capture script so the granted page is fully
+* usable before the probe's outcome can move it.
+* @param html - the official index document.
+* @param deviceId - the device session this landing is being served for.
+* @param hop - the LAN candidates to probe, when a switch is possible.
+* @returns the patched document.
 */
-function patchAppShell(html, deviceId) {
-	const script = appShellCaptureScript(deviceId);
+function patchAppShell(html, deviceId, hop) {
+	const script = appShellCaptureScript(deviceId) + (hop === void 0 ? "" : appShellLanSwitchScript(hop));
 	const head = /<head[^>]*>/i.exec(html);
 	if (head === null) return script + html;
 	const end = head.index + head[0].length;
@@ -1244,9 +1318,10 @@ function patchAppShell(html, deviceId) {
 * worker owns navigations to `/` instead: network-first through /pair-app
 * (which validates the device cookie and refreshes its presence), the
 * cached shell for offline opens, and a pass-through of the original
-* request when the plugin no longer answers. Plain-HTTP LAN origins are not
-* secure contexts, so the worker never registers there — the LAN reopen
-* path stays "scan a fresh QR", which is cheap in-network.
+* request when the plugin no longer answers. A plain-HTTP LAN origin is
+* never a secure context, so the worker cannot exist there; the capture
+* script keeps the plugin-owned landing path in the address bar instead,
+* and that landing re-validates the device credential on every reload.
 *
 * Kept as a plain string (same pattern as the capture script): it must load
 * with no build step, run on every JS engine that ships service workers,
@@ -1346,6 +1421,12 @@ const PAIR_PATHS = {
 	/** The cookieless app landing: serves the official shell for a paired device. */
 	appPage: "/pair-app",
 	/**
+	* The landing page's LAN reachability beacon (lan-source.ts): an inert
+	* no-cors GET target, so a probe proves the origin answers without touching
+	* a credential or any state.
+	*/
+	ping: "/pair-ping",
+	/**
 	* The reopen service worker (registered by the capture script). Root-level
 	* path so its default script-directory scope already covers `/`.
 	*/
@@ -1424,6 +1505,39 @@ var PairingEventsStream = class {
 	}
 };
 /**
+* The accepted {@link PairingSourcePreference} values, shared with the config
+* schema so the patch that admits a value and the handler that reads it cannot
+* drift apart.
+*/
+const PAIRING_SOURCE_OPTIONS = [
+	"auto",
+	"public",
+	"lan"
+];
+/**
+* The LAN origins a landing page served from one authority may hop to: every
+* LAN base the service advertises except the authority serving the request
+* (hopping to the current origin would be a no-op), normalized through `URL`
+* so a default port compares equal to `location.origin`.
+* @param lanBases - the advertised LAN base URLs, in interface order.
+* @param currentOrigin - the origin serving the landing page.
+* @returns the distinct candidate origins, in interface order.
+*/
+function lanSourceCandidates(lanBases, currentOrigin) {
+	const origins = [];
+	for (const base of lanBases) {
+		let origin;
+		try {
+			origin = new URL(base).origin;
+		} catch {
+			continue;
+		}
+		if (origin === currentOrigin || origins.includes(origin)) continue;
+		origins.push(origin);
+	}
+	return origins;
+}
+/**
 * Build the /api/pair route family.
 * @param deps - service + fence inputs.
 * @returns the exact routes to register on webServer.
@@ -1431,6 +1545,26 @@ var PairingEventsStream = class {
 function makeRoutes(deps) {
 	const { service, requirePairingForLan = true } = deps;
 	const pairingRequired = () => typeof requirePairingForLan === "function" ? requirePairingForLan() : requirePairingForLan;
+	/** The manual network override, re-read per request (default: automatic). */
+	const sourcePreference = () => deps.pairingSource?.() ?? "auto";
+	/**
+	* Every authority this surface serves, as {@link isTrustedHost} wants them
+	* (bare `host` or `host:port` literals). The LAN literals are re-read per
+	* request: a hot rebind (the lan-bind toggle) updates them mid-process, and
+	* both the fence and the reachability beacon must follow.
+	*/
+	const servedAuthorities = () => {
+		const publicHost = publicHostOf(service.publicBaseUrl);
+		const extraHosts = typeof deps.trustedHosts === "function" ? deps.trustedHosts() : deps.trustedHosts ?? [];
+		return [
+			...service.lanAddresses,
+			...publicHost !== void 0 ? [publicHost] : [],
+			...extraHosts,
+			...dynamicTrustedHosts
+		];
+	};
+	/** Every LAN base URL the service currently advertises, in interface order. */
+	const lanBaseUrls = () => service.lanAddresses.map((address) => service.lanBaseUrlFor(address)).filter((base) => base !== void 0);
 	const grants = deps.grants ?? createPairGrantStore();
 	const events = new PairingEventsStream(service);
 	const dynamicTrustedHosts = /* @__PURE__ */ new Set();
@@ -1443,15 +1577,7 @@ function makeRoutes(deps) {
 	* pairing entry pages), never for an API or subresource request.
 	*/
 	const lanFence = (req, navigation = false) => {
-		const publicHost = publicHostOf(service.publicBaseUrl);
-		const bases = service.lanAddresses;
-		const extraHosts = typeof deps.trustedHosts === "function" ? deps.trustedHosts() : deps.trustedHosts ?? [];
-		const combined = [
-			...bases,
-			...publicHost !== void 0 ? [publicHost] : [],
-			...extraHosts,
-			...dynamicTrustedHosts
-		];
+		const combined = servedAuthorities();
 		if (navigation && isTopLevelDocumentNavigation(req) ? isTrustedHost(req, combined) : isTrustedApiRequest(req, combined)) return true;
 		const privateLanHost = privateLanHostOf(req, navigation);
 		if (privateLanHost !== void 0) {
@@ -1552,7 +1678,8 @@ function makeRoutes(deps) {
 		const { address } = payload;
 		try {
 			const { token, expiresAt } = service.issue(void 0, address);
-			const base = address === void 0 ? service.publicBaseUrl ?? service.lanBaseUrl : service.lanBaseUrlFor(address);
+			const preference = sourcePreference();
+			const base = address !== void 0 ? service.lanBaseUrlFor(address) : preference === "lan" ? service.lanBaseUrl : preference === "public" ? service.publicBaseUrl : service.publicBaseUrl ?? service.lanBaseUrl;
 			if (base === void 0) throw new Error("remote-web-ui: base unavailable");
 			writeJson(res, 200, {
 				ok: true,
@@ -1868,7 +1995,56 @@ function makeRoutes(deps) {
 			"referrer-policy": "no-referrer",
 			"set-cookie": [deviceCookie(req, service.config.cookieName, id)]
 		});
-		res.end(patchAppShell(html, id));
+		res.end(patchAppShell(html, id, lanHop(req, id)));
+	};
+	/**
+	* The LAN hop this landing may take, or undefined when there is nothing to
+	* decide. Three conditions have to hold together: the automatic preference
+	* (both overrides answer the question already — `lan` serves the QR from a
+	* LAN origin, `public` forbids the move), at least one LAN candidate other
+	* than this origin, and a fresh one-time grant for the target landing. The
+	* grant is what lets the target origin serve the shell: the device cookie is
+	* origin-scoped, so the LAN origin has no credential of its own, and the
+	* grant table lives in this process regardless of which interface answered.
+	* The candidate set is carried to the client as origins (lan-source.ts
+	* compares them against `location.origin`).
+	* @param req - the landing request (its authority is the current origin).
+	* @param deviceId - the device session the landing is served for.
+	* @returns the hop payload, or undefined when no switch is possible.
+	*/
+	const lanHop = (req, deviceId) => {
+		if (sourcePreference() !== "auto") return void 0;
+		const candidates = lanSourceCandidates(lanBaseUrls(), appOrigin(req));
+		if (candidates.length === 0) return void 0;
+		return {
+			candidates,
+			path: PAIR_PATHS.appPage,
+			pingPath: PAIR_PATHS.ping,
+			grant: grants.issue(deviceId).grant
+		};
+	};
+	/**
+	* The landing page's LAN reachability beacon: a 204 for a Host this plugin
+	* serves, a 403 otherwise. It carries no credential and no state — a phone
+	* that reaches it has proved the origin answers, which is all the source
+	* decision needs, and the fence's browser-marker half is deliberately not
+	* applied here: the probe is cross-site by construction (a page on the
+	* public origin fetching a LAN origin), so the marker check would turn every
+	* probe into the same 403 that means "not ours" and make the two
+	* indistinguishable.
+	*/
+	const handlePing = (req, res) => {
+		if (!requireMethod(req, res, "GET")) return;
+		if (!isTrustedHost(req, servedAuthorities())) {
+			res.writeHead(403, { "content-type": "text/plain; charset=utf-8" });
+			res.end();
+			return;
+		}
+		res.writeHead(204, {
+			"cache-control": "no-store",
+			"referrer-policy": "no-referrer"
+		});
+		res.end();
 	};
 	/**
 	* The reopen service worker script. Same phone-facing fence as the app
@@ -1938,6 +2114,11 @@ function makeRoutes(deps) {
 		path: PAIR_PATHS.acceptPage,
 		handler: handleAcceptPage
 	});
+	routes.push({
+		kind: "exact",
+		path: PAIR_PATHS.ping,
+		handler: handlePing
+	});
 	if (deps.indexDocument !== void 0) {
 		routes.push({
 			kind: "exact",
@@ -2186,7 +2367,7 @@ function pairedDeviceIdOf(req, service) {
 * @returns the routes to register on webServer.
 */
 function makeRemoteApiRoutes(deps) {
-	const { service, port } = deps;
+	const { service } = deps;
 	const handler = (req, res) => {
 		if (pairedDeviceIdOf(req, service) === void 0) {
 			req.resume();
@@ -2212,6 +2393,12 @@ function makeRemoteApiRoutes(deps) {
 			envelopeError(res, 403, "invalid-request", "forbidden", denied);
 			return;
 		}
+		const port = deps.port();
+		if (port === void 0) {
+			req.resume();
+			envelopeError(res, 503, "invalid-request", "port-unbound", "the local web server port is not bound yet; retry shortly");
+			return;
+		}
 		proxyLoopbackHttp(req, res, port, `${inner}${url.search}`, deps.auth);
 	};
 	return [{
@@ -2255,7 +2442,7 @@ function upgradeInnerPath(reqUrl, fallbackPath) {
 * @returns the upgrade routes to register on webServer.
 */
 function makeRemoteApiUpgradeRoutes(deps) {
-	const { service, port } = deps;
+	const { service } = deps;
 	const handlerFor = (fallbackPath) => (req, socket, head) => {
 		let queryDevice;
 		try {
@@ -2266,6 +2453,12 @@ function makeRemoteApiUpgradeRoutes(deps) {
 			socket.destroy();
 			return;
 		}
+		const port = deps.port();
+		if (port === void 0) {
+			socket.write("HTTP/1.1 503 Service Unavailable\r\nConnection: close\r\n\r\n");
+			socket.destroy();
+			return;
+		}
 		const inner = upgradeInnerPath(req.url, fallbackPath);
 		if (loopbackOnlyDenial(inner.split("?")[0] ?? inner) !== void 0) {
 			socket.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n");
@@ -2475,16 +2668,132 @@ function releasePostureKey(current, attempted) {
 * with, so the same non-internal IPv4 derivation applies here — an external
 * plugin cannot read the CLI's sampled snapshot, but the fence accepts
 * exactly these literals, which is the property that matters.
+*
+* One derivation is deliberately narrower than the CLI's: everything this
+* module returns is advertised to a phone (the QR base, the landing page's
+* LAN probe, and the fence's trusted-literal list), and an advertised literal
+* the peer can never reach costs a phone the whole pairing attempt. A macOS
+* host running a fake-IP proxy (Clash/Surge/Mihomo) samples its TUN gateway as
+* `198.18.0.1`, which is a benchmarking-range address no LAN peer can route
+* to; the old derivation advertised it like any other interface. The filter
+* below drops the interface kinds and address ranges a peer cannot reach, and
+* keeps everything else — RFC1918, ULA-side IPv4 and a routable public literal
+* (a VPS whose NIC is its only reachable base must stay advertisable).
+*
+* @module @linxin666/dsh-remote-web-ui/lan
+*/
+/**
+* Interface-name stems of tunnels and VPN adapters: interfaces whose address
+* is a private point-to-point endpoint on this machine, never an authority a
+* peer on the local network can dial. Matching is case-insensitive and
+* anchored at the start, so `utun0`/`utun4` both match while a hypothetical
+* `en0utun` does not. Windows reports adapter *descriptions* rather than POSIX
+* stems (`Tailscale`, `WireGuard Tunnel`, `OpenVPN Wintun`), which the same
+* list covers by prefix.
+*/
+const TUNNEL_INTERFACE_PREFIXES = [
+	"utun",
+	"tun",
+	"tap",
+	"ppp",
+	"ipsec",
+	"wg",
+	"wireguard",
+	"tailscale",
+	"nordlynx",
+	"proton",
+	"openvpn",
+	"zt"
+];
+/**
+* Interface-name stems of virtual machine and container bridges: `docker0`,
+* `vethXXXX`, `br-<id>`, `virbr0`, `vmnet8`, `vboxnet0` and the Hyper-V
+* `vEthernet` adapters. Their RFC1918 addresses belong to a NAT the host
+* shares with its own guests, so a phone on the physical LAN cannot reach
+* them; `bridge0`/`br0` are deliberately absent because a real bridged LAN
+* (macOS Internet Sharing) is exactly the address a phone does reach.
+*/
+const VIRTUAL_INTERFACE_PREFIXES = [
+	"docker",
+	"veth",
+	"virbr",
+	"vmnet",
+	"vboxnet",
+	"vethernet",
+	"br-"
+];
+/**
+* IPv4 ranges no peer on the local network can reach. The list is a denial
+* list rather than an RFC1918 allowlist on purpose: a host whose only
+* interface is a routable public literal (a VPS, a standalone server) would
+* otherwise lose its only constructible base and fall back to the
+* `lan-required` banner.
+* @param octets - the four address octets, in order.
+* @returns true when an address in this range must not be advertised.
+*/
+function isUnreachableIPv4(octets) {
+	const [a = 0, b = 0] = octets;
+	if (a === 0) return true;
+	if (a === 127) return true;
+	if (a === 100 && b >= 64 && b <= 127) return true;
+	if (a === 169 && b === 254) return true;
+	if (a === 198 && (b === 18 || b === 19)) return true;
+	if (a >= 224) return true;
+	return false;
+}
+/**
+* Whether an interface name belongs to a tunnel, VPN adapter, or virtual
+* machine/container bridge, so its address is not an authority a LAN peer
+* can dial.
+* @param name - the interface name from `os.networkInterfaces()`.
+* @returns true when the interface must not be advertised.
+*/
+function isUnadvertisableInterface(name) {
+	const lower = name.toLowerCase();
+	return [...TUNNEL_INTERFACE_PREFIXES, ...VIRTUAL_INTERFACE_PREFIXES].some((prefix) => lower.startsWith(prefix));
+}
+/**
+* Whether an IPv4 literal can be advertised to a pairing peer.
+* @param address - a dotted-quad IPv4 literal.
+* @returns true when a peer could plausibly reach it.
+*/
+function isAdvertisableIPv4(address) {
+	const parts = address.split(".");
+	if (parts.length !== 4) return false;
+	const octets = parts.map((part) => /^\d{1,3}$/.test(part) ? Number(part) : NaN);
+	if (octets.some((octet) => !Number.isInteger(octet) || octet > 255)) return false;
+	return !isUnreachableIPv4(octets);
+}
+/**
+* Every IPv4 interface address this machine can advertise to a pairing peer:
+* non-internal, on a non-tunnel and non-virtual interface, outside the ranges
+* no peer can route to.
+* @param interfaces - the sampled interface map (defaults to the live one).
+* @returns the candidates in interface order (possibly empty).
 */
+function lanIPv4Candidates(interfaces = networkInterfaces()) {
+	const candidates = [];
+	for (const [name, addresses] of Object.entries(interfaces)) {
+		if (isUnadvertisableInterface(name)) continue;
+		for (const iface of addresses ?? []) {
+			if (iface.family !== "IPv4" || iface.internal) continue;
+			if (!isAdvertisableIPv4(iface.address)) continue;
+			candidates.push({
+				iface: name,
+				address: iface.address
+			});
+		}
+	}
+	return candidates;
+}
 /**
-* Non-internal IPv4 interface addresses of this machine — the IP-literal
-* authorities an all-interfaces bind is reachable by on the LAN.
+* Non-internal, reachable IPv4 interface addresses of this machine — the
+* IP-literal authorities an all-interfaces bind is reachable by on the LAN.
+* @param interfaces - the sampled interface map (defaults to the live one).
 * @returns the addresses in interface order (possibly empty).
 */
-function lanIPv4Addresses() {
-	return Object.values(networkInterfaces()).flat().filter((iface) => {
-		return iface !== void 0 && iface.family === "IPv4" && !iface.internal;
-	}).map((iface) => iface.address);
+function lanIPv4Addresses(interfaces = networkInterfaces()) {
+	return lanIPv4Candidates(interfaces).map((candidate) => candidate.address);
 }
 //#endregion
 //#region src/firewall.ts
@@ -2979,11 +3288,18 @@ function isHttpUrl(value) {
 * token AND a valid public hostname (the token does not carry the hostname,
 * so the QR base and the fence trust would have no source without it);
 * otherwise no tunnel and the manual public base applies.
+*
+* The quick target URL names the local webServer port, so a plan made before
+* the listener binds cannot be quick: it comes back `off` and the caller —
+* which can observe the port settle — re-plans. The planner itself never
+* emits an `http://127.0.0.1:undefined` target.
 * @param value - the resolved settings slice that drives the tunnel.
-* @param port - the local webServer port the tunnel forwards to.
+* @param port - the local webServer port the tunnel forwards to (undefined
+*   before the listener binds).
 */
 function tunnelPlanOf(value, port) {
 	if (value.autoTunnel === true) {
+		if (port === void 0) return { mode: "off" };
 		const ignored = [];
 		if (value.tunnelToken !== void 0 && value.tunnelToken !== "") ignored.push("tunnelToken");
 		if (value.publicBaseUrl !== void 0 && value.publicBaseUrl !== "") ignored.push("publicBaseUrl");
@@ -4000,12 +4316,12 @@ function mountOnce(packageName, fn) {
 /**
 * Run one piece of work outside the caller's async context.
 *
-* The Host performs a settings mutation inside `hmr.runExclusive`, which marks
-* the running async context with an AsyncLocalStorage store. Side effects that
-* live on that path - writing `cordis.patch.yml`, the very file the HMR config
-* watcher refreshes from - must not run under that mark, or the watcher's
-* refresh can re-enter the exclusive transaction and be refused with "HMR
-* transactions cannot be nested" (#1751, #1754).
+* A Host mutation that runs inside `hmr.runExclusive` marks the running async
+* context with an AsyncLocalStorage store. Side effects on that path that write
+* a file the HMR config watcher refreshes from - `cordis.patch.yml` above all -
+* must not run under that mark, or the watcher's refresh re-enters the
+* exclusive transaction and is refused with "HMR transactions cannot be nested"
+* (#1751, #1754, #1816).
 *
 * Deferring is NOT enough, and the earlier belt that this one replaces was
 * built on a disproven premise: Node propagates an AsyncLocalStorage store into
@@ -4027,7 +4343,7 @@ function mountOnce(packageName, fn) {
 * // -> undefined
 * ```
 *
-* @module
+* @module dsh-web-shared/host/detached-work
 */
 /**
 * The escape hatch, created at module scope on purpose: a resource built while
@@ -4035,7 +4351,7 @@ function mountOnce(packageName, fn) {
 * instance is the only one the module ever needs. It carries no context of its
 * own, so every job run through it starts from the process's root context.
 */
-const DETACHED = new AsyncResource("dsh-remote-web-ui:detached-work", { triggerAsyncId: 0 });
+const DETACHED = new AsyncResource("dsh-web:detached-work", { triggerAsyncId: 0 });
 /**
 * Run `work` outside the caller's AsyncLocalStorage context.
 *
@@ -4095,7 +4411,7 @@ function buildRemoteChannelBootScript(rules = REMOTE_CHANNEL_RULES) {
 }
 /** Boot-watchdog latch: one self-reload per session while the boot is broken. */
 const BOOT_WATCHDOG_KEY = "dsh-remote-boot-reload";
-/** Total wait for the app's first conversation surface before the reload. */
+/** Post-load wait for the app's first conversation surface before the reload. */
 const BOOT_WATCHDOG_WAIT_MS = 15e3;
 /** Watchdog poll cadence. */
 const BOOT_WATCHDOG_POLL_MS = 1e3;
@@ -4110,7 +4426,7 @@ const BOOT_WATCHDOG_POLL_MS = 1e3;
 */
 function buildBootWatchdogScript(waitMs = BOOT_WATCHDOG_WAIT_MS, pollMs = BOOT_WATCHDOG_POLL_MS) {
 	const key = JSON.stringify(BOOT_WATCHDOG_KEY);
-	return ";function wBoot(){try{return !!(w.document&&w.document.querySelector&&(w.document.querySelector(\"[data-conversation-scroll]\")||w.document.querySelector(\"[data-slot=\\\"conversation\\\"]\")))}catch(e){return false}}function wTick(n){try{if(wBoot()){try{w.sessionStorage.removeItem(" + key + ")}catch(e){}return}if(n<" + waitMs + "){w.setTimeout(function(){wTick(n+" + pollMs + ")}," + pollMs + ");return}var done=false;try{done=w.sessionStorage.getItem(" + key + ")===\"1\"}catch(e){}if(done)return;try{w.sessionStorage.setItem(" + key + ",\"1\")}catch(e){}w.location.reload()}catch(e){}}if(typeof w.setTimeout===\"function\")w.setTimeout(function(){wTick(0)}," + pollMs + ");";
+	return ";function wBoot(){try{return !!(w.document&&w.document.querySelector&&(w.document.querySelector(\"[data-conversation-scroll]\")||w.document.querySelector(\"[data-slot=\\\"conversation\\\"]\")))}catch(e){return false}}function wTick(n){try{if(wBoot()){try{w.sessionStorage.removeItem(" + key + ")}catch(e){}return}if(!w.document||w.document.readyState!==\"complete\"){w.setTimeout(function(){wTick(0)}," + pollMs + ");return}if(n<" + waitMs + "){w.setTimeout(function(){wTick(n+" + pollMs + ")}," + pollMs + ");return}var done=false;try{done=w.sessionStorage.getItem(" + key + ")===\"1\"}catch(e){}if(done)return;try{w.sessionStorage.setItem(" + key + ",\"1\")}catch(e){}w.location.reload()}catch(e){}}if(typeof w.setTimeout===\"function\")w.setTimeout(function(){wTick(0)}," + pollMs + ");";
 }
 /** The script this plugin contributes; built once from the live rules. */
 const REMOTE_CHANNEL_BOOT_SCRIPT = buildRemoteChannelBootScript();
@@ -4206,10 +4522,16 @@ const Config = z.object({
 	relay: z.boolean().default(true).volatile(),
 	lanBind: z.boolean().volatile(),
 	profile: z.string().pattern(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
-	enabled: z.boolean().default(true).volatile()
+	enabled: z.boolean().default(true).volatile(),
+	pairingSource: z.union([...PAIRING_SOURCE_OPTIONS]).default("auto").volatile()
 });
 /** Presence sweep cadence (a stale device flips to disconnected within two sweeps). */
 const SWEEP_INTERVAL_MS = 1e4;
+/**
+* Re-plan retry while the quick tunnel waits for the webServer port to bind
+* (a recompose pass can run this apply ahead of the listener's bind).
+*/
+const PORT_SETTLE_RETRY_MS = 1e3;
 /** Read one resolved config field, following the live reference the schema produces. */
 function readConfigField(field, fallback) {
 	if (field === void 0) return fallback;
@@ -4264,7 +4586,8 @@ const DEFAULTS = {
 	relay: true,
 	lanBind: void 0,
 	profile: resolveManagedProfile(void 0, void 0, process.env.DSH_PROFILE),
-	enabled: true
+	enabled: true,
+	pairingSource: "auto"
 };
 /**
 * The launched profile the Host publishes on its `profileContext` service
@@ -4302,7 +4625,8 @@ function applyImpl(ctx, config) {
 		relay: readConfigField(config?.relay, DEFAULTS.relay),
 		lanBind: readOptionalConfigField(config?.lanBind),
 		profile: resolveManagedProfile(readOptionalConfigField(config?.profile), launchedProfileName(ctx), process.env.DSH_PROFILE),
-		enabled: readConfigField(config?.enabled, DEFAULTS.enabled)
+		enabled: readConfigField(config?.enabled, DEFAULTS.enabled),
+		pairingSource: readConfigField(config?.pairingSource, DEFAULTS.pairingSource)
 	});
 	const service = new PairingService(pairingConfigOf(resolve()));
 	const tunnel = new TunnelManager();
@@ -4346,6 +4670,14 @@ function applyImpl(ctx, config) {
 		registrar.announce(target);
 	};
 	let tunnelMode = resolve().autoTunnel ? "quick" : "off";
+	/**
+	* Retry timer while the quick tunnel waits for the webServer port to bind
+	* (undefined when no deferral is pending). Unref'd: never keeps the
+	* process alive on its own.
+	*/
+	let portSettleTimer;
+	/** Dedupes the unbound-port warning to one line per unsettled episode. */
+	let portSettleWarned = false;
 	tunnel.onPhase((info) => {
 		if (tunnelMode === "off") return;
 		if (info.phase === "running" && info.url !== void 0) {
@@ -4372,6 +4704,7 @@ function applyImpl(ctx, config) {
 		disposeRelayRegistrar();
 		publicBase.dispose();
 		tunnel.dispose();
+		if (portSettleTimer !== void 0) clearTimeout(portSettleTimer);
 	}, "remote-web-ui: auto tunnel");
 	if ((ctx.webServer.host === "0.0.0.0" || ctx.webServer.host === "127.0.0.1") && Number.isFinite(ctx.webServer.port)) {
 		const lanBases = ctx.webServer.host === "0.0.0.0" ? lanIPv4Addresses().map((address) => ({
@@ -4445,6 +4778,7 @@ function applyImpl(ctx, config) {
 	const routes = [...makeRoutes({
 		service,
 		requirePairingForLan: () => resolve().requirePairingForLan,
+		pairingSource: () => resolve().pairingSource,
 		lanBindStatus,
 		indexDocument: fetchAppShell,
 		trustedHosts: () => {
@@ -4465,12 +4799,12 @@ function applyImpl(ctx, config) {
 		}
 	}), ...makeRemoteApiRoutes({
 		service,
-		port: ctx.webServer.port,
+		port: () => ctx.webServer.port,
 		auth: innerAuth
 	})];
 	const upgrades = makeRemoteApiUpgradeRoutes({
 		service,
-		port: ctx.webServer.port,
+		port: () => ctx.webServer.port,
 		auth: innerAuth
 	});
 	const gate = makeGateListener(service, () => resolve().requirePairingForLan, () => resolve().enabled);
@@ -4479,7 +4813,9 @@ function applyImpl(ctx, config) {
 	let postureWasExposed = false;
 	const runPostureProbe = () => {
 		if (!resolve().enabled) return;
-		const targets = postureTargets(service.publicBaseUrl, service.lanAddresses, ctx.webServer.port);
+		const port = ctx.webServer.port;
+		if (port === void 0) return;
+		const targets = postureTargets(service.publicBaseUrl, service.lanAddresses, port);
 		if (targets.length === 0) {
 			postureKey = void 0;
 			service.setPosture(void 0);
@@ -4490,7 +4826,7 @@ function applyImpl(ctx, config) {
 		if (!claim.run) return;
 		postureKey = claim.next;
 		probePosture({
-			port: ctx.webServer.port,
+			port,
 			targets
 		}).then((snapshot) => {
 			service.setPosture(snapshot);
@@ -4573,11 +4909,8 @@ function applyImpl(ctx, config) {
 	ctx.effect(() => () => {
 		lanBindWorkPending = false;
 	}, "remote-web-ui: lan-bind work");
-	const sync = () => {
-		const value = resolve();
-		service.config = pairingConfigOf(value);
-		scheduleLanBindWork();
-		const plan = tunnelPlanOf(value, ctx.webServer.port);
+	const applyTunnelPlan = (value, port) => {
+		const plan = tunnelPlanOf(value, port);
 		tunnelMode = plan.mode;
 		publicBase.setMode(plan.mode);
 		const liveTunnelUrl = publicBase.quickUrl();
@@ -4615,6 +4948,28 @@ function applyImpl(ctx, config) {
 				service.setPublicBaseUrl(void 0);
 			} else service.setPublicBaseUrl(value.publicBaseUrl);
 		}
+	};
+	const sync = () => {
+		const value = resolve();
+		service.config = pairingConfigOf(value);
+		scheduleLanBindWork();
+		const livePort = ctx.webServer.port;
+		if (livePort === void 0 && value.autoTunnel === true) {
+			if (!portSettleWarned) {
+				portSettleWarned = true;
+				console.warn("remote-web-ui: autoTunnel is on but the web server port is not bound yet — the quick tunnel starts once the port settles");
+			}
+			if (portSettleTimer === void 0) {
+				portSettleTimer = setTimeout$1(() => {
+					portSettleTimer = void 0;
+					sync();
+				}, PORT_SETTLE_RETRY_MS);
+				portSettleTimer.unref();
+			}
+		} else {
+			portSettleWarned = false;
+			applyTunnelPlan(value, livePort);
+		}
 		const enabled = value.enabled;
 		if (!enabled) {
 			service.stop();