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

package/lib/types/index.js

@@ -14,7 +14,7 @@ import { DEFAULT_IDLE_EXPIRE_MS, PairingService } from "./pairing.js";
 import { dshHome } from "./dsh-home.js";
 import { isPairedDeviceRequest, makeGateListener } from "./gate.js";
 import { RemoteWebUiPairing } from "./pairing-access.js";
-import { makeRoutes } from "./routes.js";
+import { makeRoutes, PAIRING_SOURCE_OPTIONS } from "./routes.js";
 import { makeRemoteApiRoutes, makeRemoteApiUpgradeRoutes } from "./remote-api.js";
 import { startRemotePresencePet } from "./remote-presence-pet.js";
 import { claimPostureKey, postureTargets, probePosture, releasePostureKey } from "./posture.js";
@@ -81,9 +81,15 @@ export const Config = z.object({
     lanBind: z.boolean().volatile(),
     profile: z.string().pattern(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
     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 = 10_000;
+/**
+ * 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 = 1_000;
 /** Read one resolved config field, following the live reference the schema produces. */
 function readConfigField(field, fallback) {
     if (field === undefined)
@@ -143,6 +149,7 @@ const DEFAULTS = {
     lanBind: undefined,
     profile: resolveManagedProfile(undefined, undefined, process.env.DSH_PROFILE),
     enabled: true,
+    pairingSource: 'auto',
 };
 /**
  * The launched profile the Host publishes on its `profileContext` service
@@ -186,6 +193,7 @@ function applyImpl(ctx, config) {
         lanBind: readOptionalConfigField(config?.lanBind),
         profile: resolveManagedProfile(readOptionalConfigField(config?.profile), launchedProfileName(ctx), process.env.DSH_PROFILE),
         enabled: readConfigField(config?.enabled, DEFAULTS.enabled),
+        pairingSource: readConfigField(config?.pairingSource, DEFAULTS.pairingSource),
     });
     const service = new PairingService(pairingConfigOf(resolve()));
     // ── auto tunnel ─────────────────────────────────────────────────────────
@@ -261,6 +269,14 @@ function applyImpl(ctx, config) {
     // 'off' until a sync pass turns a mode on; the phase listener only feeds
     // the public base while a plugin-managed tunnel (quick or named) runs.
     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;
@@ -291,6 +307,8 @@ function applyImpl(ctx, config) {
         disposeRelayRegistrar();
         publicBase.dispose();
         tunnel.dispose();
+        if (portSettleTimer !== undefined)
+            clearTimeout(portSettleTimer);
     }, 'remote-web-ui: auto tunnel');
     // The bind facts are known by now (webServer is an inject edge): the LAN
     // bases are frozen per process, matching the CLI's once-per-invocation
@@ -413,6 +431,7 @@ function applyImpl(ctx, config) {
         ...makeRoutes({
             service,
             requirePairingForLan: () => resolve().requirePairingForLan,
+            pairingSource: () => resolve().pairingSource,
             lanBindStatus,
             indexDocument: fetchAppShell,
             trustedHosts: () => {
@@ -446,13 +465,13 @@ function applyImpl(ctx, config) {
         // credential to everything it forwards (issue #1665).
         ...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);
@@ -468,7 +487,13 @@ function applyImpl(ctx, config) {
     const runPostureProbe = () => {
         if (!resolve().enabled)
             return;
-        const targets = postureTargets(service.publicBaseUrl, service.lanAddresses, ctx.webServer.port);
+        // The probe and the LAN targets need the bound port; before it settles
+        // (a recompose pass) there is nothing honest to probe — keep the previous
+        // snapshot and let the next trigger retry.
+        const port = ctx.webServer.port;
+        if (port === undefined)
+            return;
+        const targets = postureTargets(service.publicBaseUrl, service.lanAddresses, port);
         if (targets.length === 0) {
             postureKey = undefined;
             service.setPosture(undefined);
@@ -479,7 +504,7 @@ function applyImpl(ctx, config) {
         if (!claim.run)
             return;
         postureKey = claim.next;
-        void probePosture({ port: ctx.webServer.port, targets }).then((snapshot) => {
+        void probePosture({ port, targets }).then((snapshot) => {
             service.setPosture(snapshot);
             const exposedHosts = snapshot.hosts.filter(host => host.exposed).map(host => host.host);
             const exposed = exposedHosts.length > 0;
@@ -637,18 +662,13 @@ function applyImpl(ctx, config) {
         }));
     };
     ctx.effect(() => () => { lanBindWorkPending = false; }, 'remote-web-ui: lan-bind work');
-    // Apply the effective configuration to the running surfaces once per
-    // activation: the service tunables, the LAN-bind block/firewall, the tunnel
-    // plan, the pairing routes, the presence sweep, and the posture probe.
-    const sync = () => {
-        const value = resolve();
-        service.config = pairingConfigOf(value);
-        scheduleLanBindWork();
-        // The plugin-managed tunnels own the public base while one runs: the URL
-        // lands in the service through the tunnel's phase listener (the minted
-        // quick URL, or the named tunnel's fixed public hostname). The manual
-        // publicBaseUrl applies only when no tunnel runs.
-        const plan = tunnelPlanOf(value, ctx.webServer.port);
+    // Apply one tunnel plan to the running surfaces. The plugin-managed tunnels
+    // own the public base while one runs: the URL lands in the service through
+    // the tunnel's phase listener (the minted quick URL, or the named tunnel's
+    // fixed public hostname). The manual publicBaseUrl applies only when no
+    // tunnel runs.
+    const applyTunnelPlan = (value, port) => {
+        const plan = tunnelPlanOf(value, port);
         tunnelMode = plan.mode;
         publicBase.setMode(plan.mode);
         const liveTunnelUrl = publicBase.quickUrl();
@@ -714,6 +734,36 @@ function applyImpl(ctx, config) {
                 service.setPublicBaseUrl(value.publicBaseUrl);
             }
         }
+    };
+    // Apply the effective configuration to the running surfaces once per
+    // activation: the service tunables, the LAN-bind block/firewall, the tunnel
+    // plan, the pairing routes, the presence sweep, and the posture probe.
+    const sync = () => {
+        const value = resolve();
+        service.config = pairingConfigOf(value);
+        scheduleLanBindWork();
+        // The quick tunnel's loopback target URL needs the bound port. A recompose
+        // pass can run this apply before the listener binds: defer the tunnel
+        // branch (and re-plan on a short timer) instead of minting an
+        // http://127.0.0.1:undefined target; everything else in sync applies.
+        const livePort = ctx.webServer.port;
+        if (livePort === undefined && 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 === undefined) {
+                portSettleTimer = nodeSetTimeout(() => {
+                    portSettleTimer = undefined;
+                    sync();
+                }, PORT_SETTLE_RETRY_MS);
+                portSettleTimer.unref();
+            }
+        }
+        else {
+            portSettleWarned = false;
+            applyTunnelPlan(value, livePort);
+        }
         const enabled = value.enabled;
         if (!enabled) {
             service.stop();

package/lib/types/lan-source.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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. */
+export declare const LAN_SOURCE_STORAGE_KEY = "dsh-remote-lan-source";
+/**
+ * Probe budget for the whole candidate set. Long enough for a LAN round trip,
+ * short enough that a phone on another network never waits on it — the probe
+ * is fire-and-forget and the page it runs on is already usable.
+ */
+export declare const LAN_SOURCE_PROBE_TIMEOUT_MS = 800;
+/**
+ * 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.
+ */
+export declare const LAN_SOURCE_RETRY_WINDOW_MS = 120000;
+/** One probe payload: everything the injected script needs, JSON-serializable. */
+export interface LanSourceHop {
+    /**
+     * The LAN origins the probe may hop to, normalized (`https://host:port` with
+     * a default port dropped) so they compare equal to `location.origin`.
+     */
+    candidates: readonly string[];
+    /** The path the hop targets on the winning origin. */
+    path: string;
+    /** The path the probe itself requests, on each candidate. */
+    pingPath: string;
+    /** The one-time grant the hop consumes on the winning origin. */
+    grant: string;
+}
+/**
+ * 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.
+ */
+export declare function appShellLanSwitchScript(hop: LanSourceHop): string;
+//# sourceMappingURL=lan-source.d.ts.map

package/lib/types/lan-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lan-source.d.ts","sourceRoot":"","sources":["../../src/lan-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,0BAA0B,CAAA;AAE7D;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAA;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,SAAU,CAAA;AAEjD,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAA;IACZ,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAA;IAChB,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CA+DjE"}

package/lib/types/lan-source.js

@@ -0,0 +1,113 @@
+/**
+ * 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. */
+export const LAN_SOURCE_STORAGE_KEY = 'dsh-remote-lan-source';
+/**
+ * Probe budget for the whole candidate set. Long enough for a LAN round trip,
+ * short enough that a phone on another network never waits on it — the probe
+ * is fire-and-forget and the page it runs on is already usable.
+ */
+export const LAN_SOURCE_PROBE_TIMEOUT_MS = 800;
+/**
+ * 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.
+ */
+export const LAN_SOURCE_RETRY_WINDOW_MS = 120_000;
+/**
+ * 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.
+ */
+export function appShellLanSwitchScript(hop) {
+    const payload = JSON.stringify({
+        key: LAN_SOURCE_STORAGE_KEY,
+        candidates: hop.candidates,
+        path: hop.path,
+        ping: hop.pingPath,
+        grant: hop.grant,
+        timeout: LAN_SOURCE_PROBE_TIMEOUT_MS,
+        retry: LAN_SOURCE_RETRY_WINDOW_MS,
+    });
+    const body = '(function(){try{' +
+        'var w=window,loc=w.location;' +
+        'var P=' + payload + ';' +
+        'var S=w.sessionStorage;' +
+        // The candidate set is the decision's identity: a host whose interfaces
+        // changed hands the landing a different signature, which forces a re-probe.
+        'P.sig=P.candidates.join(",");' +
+        // The stored decision: which source this session settled on, the candidate
+        // set it was made against (so a host whose interfaces changed re-decides),
+        // and when. Anything unreadable is treated as "no decision".
+        '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){}}' +
+        // Already on a LAN candidate: nothing to decide, and a hop back to it
+        // would be the same origin. Recording the fact keeps a reload from probing.
+        '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){}' +
+        // The first answer wins: one reachable candidate is all the hop needs, and
+        // the losers keep running their own no-cors GETs harmlessly.
+        '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;' +
+        // A LAN decision taken moments ago, on a page that is not a LAN candidate,
+        // is a hop that did not stick. Fall back rather than hop again.
+        'if(Date.now()-d.at<P.retry){wr({src:"public",sig:P.sig,at:Date.now()});return}}' +
+        'probe()' +
+        '}catch(e){}})();';
+    return `<script>${body}</script>`;
+}

package/lib/types/lan.d.ts

@@ -5,11 +5,57 @@
  * 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.
+ * 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 declare function isUnadvertisableInterface(name: string): boolean;
+/**
+ * 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 declare function isAdvertisableIPv4(address: string): boolean;
+/** 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 declare function lanIPv4Candidates(interfaces?: NetworkInterfaceMap): LanCandidate[];
+/**
+ * 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 declare function lanIPv4Addresses(): string[];
+export declare function lanIPv4Addresses(interfaces?: NetworkInterfaceMap): string[];
 //# sourceMappingURL=lan.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"lan.d.ts","sourceRoot":"","sources":["../../src/lan.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;GAIG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAI3C"}
+{"version":3,"file":"lan.d.ts","sourceRoot":"","sources":["../../src/lan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAsD3C;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAG/D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAM3D;AAED,qCAAqC;AACrC,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAA;IACb,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,6EAA6E;AAC7E,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAA;AAEtE;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,GAAE,mBAAyC,GAAG,YAAY,EAAE,CAWvG;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,GAAE,mBAAyC,GAAG,MAAM,EAAE,CAEhG"}

package/lib/types/lan.js

@@ -5,15 +5,129 @@
  * 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 = [
+    '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;
+    // 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) {
+    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) {
+    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);
+}
+/**
+ * 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 = 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, 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() {
-    return Object.values(networkInterfaces()).flat()
-        .filter((iface) => { return iface !== undefined && iface.family === 'IPv4' && !iface.internal; })
-        .map(iface => iface.address);
+export function lanIPv4Addresses(interfaces = networkInterfaces()) {
+    return lanIPv4Candidates(interfaces).map(candidate => candidate.address);
 }

package/lib/types/remote-api.d.ts

@@ -35,8 +35,13 @@ export { REMOTE_API_PREFIX } from './remote-methods.ts';
 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

package/lib/types/remote-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-api.d.ts","sourceRoot":"","sources":["../../src/remote-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,WAAW,CAAA;AAEhE,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAGlD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAUhD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,2BAA2B,EAC3B,eAAe,GAChB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAgBvD,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,OAAO,EAAE,cAAc,CAAA;IACvB,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAA;IACZ;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;CACjB;AAWD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUhE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAQlG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,QAAQ,EAAE,CAwCnE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAYzF;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,EAAE,CAyCjF"}
+{"version":3,"file":"remote-api.d.ts","sourceRoot":"","sources":["../../src/remote-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAkB,MAAM,WAAW,CAAA;AAEhE,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAA;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAGlD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAUhD,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,EACb,oBAAoB,EACpB,2BAA2B,EAC3B,eAAe,GAChB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAgBvD,iCAAiC;AACjC,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,OAAO,EAAE,cAAc,CAAA;IACvB;;;;;OAKG;IACH,IAAI,EAAE,MAAM,MAAM,GAAG,SAAS,CAAA;IAC9B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;CACjB;AAWD;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUhE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAExE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAQlG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,aAAa,GAAG,QAAQ,EAAE,CAgDnE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAYzF;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,aAAa,GAAG,eAAe,EAAE,CAgDjF"}

package/lib/types/remote-api.js

@@ -101,7 +101,7 @@ export function pairedDeviceIdOf(req, service) {
  * @returns the routes to register on webServer.
  */
 export function makeRemoteApiRoutes(deps) {
-    const { service, port } = deps;
+    const { service } = deps;
     const handler = (req, res) => {
         // Paired credential first — before any bytes are buffered or forwarded.
         // Unconditional by design: this channel attaches the process's own
@@ -132,6 +132,14 @@ export function makeRemoteApiRoutes(deps) {
             envelopeError(res, 403, 'invalid-request', 'forbidden', denied);
             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);
     };
     return [{ kind: 'prefix', path: REMOTE_PREFIX, handler }];
@@ -174,7 +182,7 @@ export function upgradeInnerPath(reqUrl, fallbackPath) {
  * @returns the upgrade routes to register on webServer.
  */
 export function makeRemoteApiUpgradeRoutes(deps) {
-    const { service, port } = deps;
+    const { service } = deps;
     const handlerFor = (fallbackPath) => (req, socket, head) => {
         // WebSocket handshakes cannot carry headers from the Web API, so the
         // cookieless credential rides the query; the cookie stays the primary.
@@ -191,6 +199,13 @@ export function makeRemoteApiUpgradeRoutes(deps) {
             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/lib/types/remote-channel-boot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-channel-boot.d.ts","sourceRoot":"","sources":["../../src/remote-channel-boot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAoD,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAErH;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,GAAE,kBAAyC,GAAG,MAAM,CAkKrG;AAED,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,2BAA2B,CAAA;AAQzD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,SAAwB,EAAE,MAAM,SAAwB,GAAG,MAAM,CAgB9G;AAED,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,EAAE,MAAuC,CAAA"}
+{"version":3,"file":"remote-channel-boot.d.ts","sourceRoot":"","sources":["../../src/remote-channel-boot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAoD,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAErH;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,GAAE,kBAAyC,GAAG,MAAM,CAkKrG;AAED,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,2BAA2B,CAAA;AAQzD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,SAAwB,EAAE,MAAM,SAAwB,GAAG,MAAM,CAmB9G;AAED,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,EAAE,MAAuC,CAAA"}