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

package/src/lan.ts

@@ -5,17 +5,137 @@
  * 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
  */
 
 import { networkInterfaces } from 'node:os'
 
 /**
- * Non-internal IPv4 interface addresses of this machine — the IP-literal
- * authorities an all-interfaces bind is reachable by on the 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: readonly string[] = [
+  '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: readonly string[] = [
+  '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: readonly number[]): boolean {
+  const [a = 0, b = 0] = octets
+  // 0.0.0.0/8 "this network": never a usable address.
+  if (a === 0) return true
+  // 127.0.0.0/8 loopback (node already marks it internal; kept as the belt).
+  if (a === 127) return true
+  // 100.64.0.0/10 carrier-grade NAT: Tailscale and ISP-level NAT hand out
+  // addresses here, and a peer on the physical LAN cannot route to them.
+  if (a === 100 && b >= 64 && b <= 127) return true
+  // 169.254.0.0/16 link-local (APIPA / self-assigned).
+  if (a === 169 && b === 254) return true
+  // 198.18.0.0/15 benchmarking: the range a fake-IP TUN gateway takes.
+  if (a === 198 && (b === 18 || b === 19)) return true
+  // 224.0.0.0/4 multicast and 240.0.0.0/4 reserved (includes the broadcast).
+  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.
+ */
+export function isUnadvertisableInterface(name: string): boolean {
+  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.
+ */
+export function isAdvertisableIPv4(address: string): boolean {
+  const parts = address.split('.')
+  if (parts.length !== 4) return false
+  const octets = parts.map(part => (/^\d{1,3}$/.test(part) ? Number(part) : Number.NaN))
+  if (octets.some(octet => !Number.isInteger(octet) || octet > 255)) return false
+  return !isUnreachableIPv4(octets)
+}
+
+/** One sampled interface address. */
+export interface LanCandidate {
+  /** The interface name the address was sampled from. */
+  iface: string
+  /** The IPv4 literal. */
+  address: string
+}
+
+/** The `networkInterfaces()` shape, injectable so the filter is testable. */
+export type NetworkInterfaceMap = ReturnType<typeof networkInterfaces>
+
+/**
+ * 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).
+ */
+export function lanIPv4Candidates(interfaces: NetworkInterfaceMap = networkInterfaces()): LanCandidate[] {
+  const candidates: LanCandidate[] = []
+  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, 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).
  */
-export function lanIPv4Addresses(): string[] {
-  return Object.values(networkInterfaces()).flat()
-    .filter((iface): iface is NonNullable<typeof iface> => { return iface !== undefined && iface.family === 'IPv4' && !iface.internal })
-    .map(iface => iface.address)
+export function lanIPv4Addresses(interfaces: NetworkInterfaceMap = networkInterfaces()): string[] {
+  return lanIPv4Candidates(interfaces).map(candidate => candidate.address)
 }

package/src/remote-api.ts

@@ -73,8 +73,13 @@ function isSafeSegment(segment: string): boolean {
 export interface RemoteApiDeps {
   /** The pairing service (device gate + cookie name). */
   service: PairingService
-  /** Local webServer port the loopback proxy connects to. */
-  port: number
+  /**
+   * Local webServer port the loopback proxy connects to, read per request:
+   * `undefined` before the listener binds (a recompose pass can run this
+   * apply ahead of the bind), in which case the handlers refuse with 503
+   * instead of minting an `:undefined` URL.
+   */
+  port: () => number | undefined
   /**
    * The process's inner browser-auth credential attached to re-issued
    * requests (the connection plugin's /api route enforces that cookie and
@@ -140,7 +145,7 @@ export function pairedDeviceIdOf(req: IncomingMessage, service: PairingService):
  * @returns the routes to register on webServer.
  */
 export function makeRemoteApiRoutes(deps: RemoteApiDeps): WebRoute[] {
-  const { service, port } = deps
+  const { service } = deps
 
   const handler = (req: IncomingMessage, res: ServerResponse): void => {
     // Paired credential first — before any bytes are buffered or forwarded.
@@ -175,6 +180,14 @@ export function makeRemoteApiRoutes(deps: RemoteApiDeps): WebRoute[] {
       return
     }
 
+    const port = deps.port()
+    if (port === undefined) {
+      // The listener has not bound yet (a recompose pass): refuse instead of
+      // minting an http://127.0.0.1:undefined target; the desktop retries.
+      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)
   }
 
@@ -217,7 +230,7 @@ export function upgradeInnerPath(reqUrl: string | undefined, fallbackPath: strin
  * @returns the upgrade routes to register on webServer.
  */
 export function makeRemoteApiUpgradeRoutes(deps: RemoteApiDeps): WebUpgradeRoute[] {
-  const { service, port } = deps
+  const { service } = deps
 
   const handlerFor = (fallbackPath: string) => (req: IncomingMessage, socket: Duplex, head: Buffer): void => {
     // WebSocket handshakes cannot carry headers from the Web API, so the
@@ -234,6 +247,13 @@ export function makeRemoteApiUpgradeRoutes(deps: RemoteApiDeps): WebUpgradeRoute
       socket.destroy()
       return
     }
+    const port = deps.port()
+    if (port === undefined) {
+      // Same unbound-port refusal as the HTTP leg: no :undefined handshake.
+      socket.write('HTTP/1.1 503 Service Unavailable\r\nConnection: close\r\n\r\n')
+      socket.destroy()
+      return
+    }
     const inner = upgradeInnerPath(req.url, fallbackPath)
     const denied = loopbackOnlyDenial(inner.split('?')[0] ?? inner)
     if (denied !== undefined) {

package/src/remote-channel-boot.ts

@@ -204,7 +204,7 @@ export function buildRemoteChannelBootScript(rules: RemoteChannelRules = REMOTE_
 /** Boot-watchdog latch: one self-reload per session while the boot is broken. */
 export 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 = 15_000
 
 /** Watchdog poll cadence. */
@@ -227,6 +227,9 @@ export function buildBootWatchdogScript(waitMs = BOOT_WATCHDOG_WAIT_MS, pollMs =
     ';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}' +
+    // Parse-time installation must not spend the recovery budget downloading
+    // the initial scripts/styles over a slow remote link (issue #1845).
+    '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;' +

package/src/routes.ts

@@ -29,6 +29,7 @@ import { isLoopbackClient, readCookie } from './gate.ts'
 import { readJsonBody, writeJson } from './http.ts'
 import { createPairGrantStore, type PairGrantStore } from './pair-grant.ts'
 import { REMOTE_HOST_GRANT_GLOBAL } from './remote-channel-rules.ts'
+import { appShellLanSwitchScript, type LanSourceHop } from './lan-source.ts'
 
 /**
  * Browser-trust fence for the /api/pair routes, mirroring the connection
@@ -293,19 +294,27 @@ 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.
  */
 export const APP_DEVICE_STORAGE_KEY = 'dsh-remote-device'
 
 export function appShellCaptureScript(deviceId: string): string {
   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>`
 }
 
 /**
@@ -315,9 +324,19 @@ export function appShellCaptureScript(deviceId: string): string {
  * 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.
  */
-export function patchAppShell(html: string, deviceId: string): string {
-  const script = appShellCaptureScript(deviceId)
+export function patchAppShell(html: string, deviceId: string, hop?: LanSourceHop): string {
+  const script = appShellCaptureScript(deviceId) + (hop === undefined ? '' : appShellLanSwitchScript(hop))
   const head = /<head[^>]*>/i.exec(html)
   if (head === null) return script + html
   const end = head.index + head[0].length
@@ -332,9 +351,10 @@ export function patchAppShell(html: string, deviceId: string): string {
  * 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,
@@ -435,6 +455,12 @@ export const PAIR_PATHS = {
   acceptPage: '/pair-accept',
   /** 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 `/`.
@@ -527,12 +553,65 @@ export class PairingEventsStream {
   }
 }
 
+/**
+ * The manual override of the automatic network choice, for the case where the
+ * phone's own probe misjudges (a firewall that answers the reachability ping
+ * but not the page, or a LAN the probe cannot see).
+ *
+ * - `auto` (default): the QR link names the public base when one is configured
+ *   and the landing page probes the LAN candidates, switching to the first one
+ *   that answers.
+ * - `public`: the public base only, and the landing page never probes. For a
+ *   deployment where the LAN hop is undesirable.
+ * - `lan`: the first LAN literal directly, with no public hop. For a phone that
+ *   is known to sit on this machine's own network.
+ */
+export type PairingSourcePreference = 'auto' | 'public' | 'lan'
+
+/**
+ * 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.
+ */
+export const PAIRING_SOURCE_OPTIONS: readonly PairingSourcePreference[] = ['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.
+ */
+export function lanSourceCandidates(lanBases: readonly string[], currentOrigin: string): string[] {
+  const origins: string[] = []
+  for (const base of lanBases) {
+    let origin: string
+    try {
+      origin = new URL(base).origin
+    } catch {
+      continue
+    }
+    if (origin === currentOrigin || origins.includes(origin)) continue
+    origins.push(origin)
+  }
+  return origins
+}
+
 /** Route-family dependencies (test seam). */
 export interface PairRoutesDeps {
   /** The pairing service. */
   service: PairingService
   /** Current desktop gate policy, re-read for every status response. */
   requirePairingForLan?: boolean | (() => boolean)
+  /**
+   * The manual override of the automatic network choice
+   * ({@link PairingSourcePreference}), re-read per request. Defaults to
+   * `auto`: the QR link names the public base and the landing page decides
+   * whether to switch to a LAN origin.
+   */
+  pairingSource?: () => PairingSourcePreference
   /**
    * LAN-bind facts for the settings card (managed patch block state, live
    * bind host/port, firewall summary). Re-read per request so a hot-reloaded
@@ -568,6 +647,28 @@ export function makeRoutes(deps: PairRoutesDeps): WebRoute[] {
   const pairingRequired = (): boolean => typeof requirePairingForLan === 'function'
     ? requirePairingForLan()
     : requirePairingForLan
+  /** The manual network override, re-read per request (default: automatic). */
+  const sourcePreference = (): PairingSourcePreference => 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 = (): string[] => {
+    const publicHost = publicHostOf(service.publicBaseUrl)
+    const extraHosts = typeof deps.trustedHosts === 'function' ? deps.trustedHosts() : (deps.trustedHosts ?? [])
+    return [
+      ...service.lanAddresses,
+      ...(publicHost !== undefined ? [publicHost] : []),
+      ...extraHosts,
+      ...dynamicTrustedHosts,
+    ]
+  }
+  /** Every LAN base URL the service currently advertises, in interface order. */
+  const lanBaseUrls = (): string[] => service.lanAddresses
+    .map(address => service.lanBaseUrlFor(address))
+    .filter((base): base is string => base !== undefined)
   const grants = deps.grants ?? createPairGrantStore()
   const events = new PairingEventsStream(service)
   const dynamicTrustedHosts = new Set<string>()
@@ -581,17 +682,7 @@ export function makeRoutes(deps: PairRoutesDeps): WebRoute[] {
    * pairing entry pages), never for an API or subresource request.
    */
   const lanFence = (req: IncomingMessage, navigation = false): boolean => {
-    const publicHost = publicHostOf(service.publicBaseUrl)
-    // The service's LAN bases re-read per request: a hot rebind (the lan-bind
-    // toggle) updates them mid-process, and the fence must follow.
-    const bases = service.lanAddresses
-    const extraHosts = typeof deps.trustedHosts === 'function' ? deps.trustedHosts() : (deps.trustedHosts ?? [])
-    const combined = [
-      ...bases,
-      ...(publicHost !== undefined ? [publicHost] : []),
-      ...extraHosts,
-      ...dynamicTrustedHosts,
-    ]
+    const combined = servedAuthorities()
     if (navigation && isTopLevelDocumentNavigation(req) ? isTrustedHost(req, combined) : isTrustedApiRequest(req, combined)) return true
 
     // If request carries a valid paired device cookie from a private LAN host (e.g. after service restart), trust and remember it
@@ -702,10 +793,23 @@ export function makeRoutes(deps: PairRoutesDeps): WebRoute[] {
       // the injected portrait adaptation, PCs the full desktop UI), so the
       // remote surface can never drift from the official one.
       const { token, expiresAt } = service.issue(undefined, address)
-      // The default base is the public (tunneled) URL when configured — a
-      // phone anywhere can reach it — and the first LAN interface otherwise.
-      // An explicit address always names a LAN literal.
-      const base = address === undefined ? (service.publicBaseUrl ?? service.lanBaseUrl) : service.lanBaseUrlFor(address)
+      // The advertised base is the public (tunneled/relayed) one whenever it is
+      // configured: it is the only base a phone anywhere can reach, so the QR
+      // never depends on the scanning phone being on this machine's network.
+      // The landing page then decides at connect time whether to move to a LAN
+      // origin (lan-source.ts). `lan` is the manual override that pins the QR to
+      // a LAN literal; an explicit address always names one.
+      const preference = sourcePreference()
+      const base = address !== undefined
+        ? service.lanBaseUrlFor(address)
+        : preference === 'lan'
+          ? service.lanBaseUrl
+          : preference === 'public'
+            // Pinned to public: with none configured there is no satisfiable
+            // link, which the caller reports as lan-required rather than
+            // silently advertising a base the override excluded.
+            ? service.publicBaseUrl
+            : (service.publicBaseUrl ?? service.lanBaseUrl)
       if (base === undefined) throw new Error('remote-web-ui: base unavailable')
       writeJson(res, 200, {
         ok: true,
@@ -992,7 +1096,50 @@ export function makeRoutes(deps: PairRoutesDeps): WebRoute[] {
       '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: IncomingMessage, deviceId: string): LanSourceHop | undefined => {
+    if (sourcePreference() !== 'auto') return undefined
+    const candidates = lanSourceCandidates(lanBaseUrls(), appOrigin(req))
+    if (candidates.length === 0) return undefined
+    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: IncomingMessage, res: ServerResponse): void => {
+    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()
   }
 
   /**
@@ -1032,6 +1179,10 @@ export function makeRoutes(deps: PairRoutesDeps): WebRoute[] {
     routes.push({ kind: 'exact', path: PAIR_PATHS.lanBind, handler: handleLanBind })
   }
   routes.push({ kind: 'exact', path: PAIR_PATHS.acceptPage, handler: handleAcceptPage })
+  // The beacon is independent of the app landing: a deployment with no
+  // indexDocument still advertises LAN bases, and a landing served some other
+  // way may still probe them.
+  routes.push({ kind: 'exact', path: PAIR_PATHS.ping, handler: handlePing })
   if (deps.indexDocument !== undefined) {
     routes.push({ kind: 'exact', path: PAIR_PATHS.appPage, handler: handleAppPage })
     // The reopen worker is only meaningful when the app landing it

package/src/tunnel-plan.ts

@@ -28,14 +28,21 @@ export type TunnelPlan =
  * 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).
  */
 export function tunnelPlanOf(
   value: { autoTunnel?: boolean; tunnelToken?: string; publicBaseUrl?: string },
-  port: number,
+  port: number | undefined,
 ): TunnelPlan {
   if (value.autoTunnel === true) {
+    if (port === undefined) return { mode: 'off' }
     const ignored: Array<'tunnelToken' | 'publicBaseUrl'> = []
     if (value.tunnelToken !== undefined && value.tunnelToken !== '') ignored.push('tunnelToken')
     if (value.publicBaseUrl !== undefined && value.publicBaseUrl !== '') ignored.push('publicBaseUrl')

package/lib/invariant.js

@@ -1,21 +0,0 @@
-//#region src/invariant.ts
-const PACKAGE_NAME = "@linxin666/dsh-remote-web-ui";
-/** Cordis companion plugin name. */
-const name = "remote-web-ui-invariant";
-/** Service required before the companion can reserve package ownership. */
-const inject = ["invariants"];
-/**
-* No runtime invariant: this package owns no durable package-local event
-* stream; its route-table and device-session relationships are asserted by
-* the package's own specs (route register/dispose symmetry via the
-* webServer disposer contract, token/revocation semantics on the service).
-*/
-const install = () => {};
-/**
-* Register this package's invariant companion.
-* @param ctx - Cordis context carrying the invariant service.
-* @returns the installed registration's disposer after setup succeeds.
-*/
-const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
-//#endregion
-export { apply, inject, name };

package/lib/types/invariant.d.ts

@@ -1,16 +0,0 @@
-/**
- * Package-owned invariant companion for `@linxin666/dsh-remote-web-ui`.
- * @module @linxin666/dsh-remote-web-ui/invariant
- */
-import type { Context } from '@deepseek-ai/cordis';
-/** Cordis companion plugin name. */
-export declare const name = "remote-web-ui-invariant";
-/** Service required before the companion can reserve package ownership. */
-export declare const inject: string[];
-/**
- * Register this package's invariant companion.
- * @param ctx - Cordis context carrying the invariant service.
- * @returns the installed registration's disposer after setup succeeds.
- */
-export declare const apply: (ctx: Context) => Promise<() => void>;
-//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"invariant.d.ts","sourceRoot":"","sources":["../../src/invariant.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,oCAAoC;AACpC,eAAO,MAAM,IAAI,4BAA4B,CAAA;AAC7C,2EAA2E;AAC3E,eAAO,MAAM,MAAM,UAAiB,CAAA;AAUpC;;;;GAIG;AACH,eAAO,MAAM,KAAK,GAAI,KAAK,OAAO,KAAG,OAAO,CAAC,MAAM,IAAI,CACU,CAAA"}

package/lib/types/invariant.js

@@ -1,23 +0,0 @@
-/**
- * Package-owned invariant companion for `@linxin666/dsh-remote-web-ui`.
- * @module @linxin666/dsh-remote-web-ui/invariant
- */
-const PACKAGE_NAME = '@linxin666/dsh-remote-web-ui';
-/** Cordis companion plugin name. */
-export const name = 'remote-web-ui-invariant';
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants'];
-/**
- * No runtime invariant: this package owns no durable package-local event
- * stream; its route-table and device-session relationships are asserted by
- * the package's own specs (route register/dispose symmetry via the
- * webServer disposer contract, token/revocation semantics on the service).
- */
-const install = () => { };
-/**
- * Register this package's invariant companion.
- * @param ctx - Cordis context carrying the invariant service.
- * @returns the installed registration's disposer after setup succeeds.
- */
-export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
-/* jscpd:ignore-end */

package/src/invariant.ts

@@ -1,32 +0,0 @@
-/**
- * Package-owned invariant companion for `@linxin666/dsh-remote-web-ui`.
- * @module @linxin666/dsh-remote-web-ui/invariant
- */
-
-/* jscpd:ignore-start */
-import type { Context } from '@deepseek-ai/cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-
-const PACKAGE_NAME = '@linxin666/dsh-remote-web-ui'
-
-/** Cordis companion plugin name. */
-export const name = 'remote-web-ui-invariant'
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants']
-
-/**
- * No runtime invariant: this package owns no durable package-local event
- * stream; its route-table and device-session relationships are asserted by
- * the package's own specs (route register/dispose symmetry via the
- * webServer disposer contract, token/revocation semantics on the service).
- */
-const install: InvariantInstaller = () => {}
-
-/**
- * Register this package's invariant companion.
- * @param ctx - Cordis context carrying the invariant service.
- * @returns the installed registration's disposer after setup succeeds.
- */
-export const apply = (ctx: Context): Promise<() => void> =>
-  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
-/* jscpd:ignore-end */