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

package/src/index.ts

@@ -24,7 +24,7 @@ import { DEFAULT_IDLE_EXPIRE_MS, PairingService, type PairingConfig } from './pa
 import { dshHome } from './dsh-home.ts'
 import { isPairedDeviceRequest, makeGateListener } from './gate.ts'
 import { RemoteWebUiPairing } from './pairing-access.ts'
-import { isTrustedApiRequest, makeRoutes } from './routes.ts'
+import { isTrustedApiRequest, makeRoutes, PAIRING_SOURCE_OPTIONS, type PairingSourcePreference } from './routes.ts'
 import { makeRemoteApiRoutes, makeRemoteApiUpgradeRoutes } from './remote-api.ts'
 import { startRemotePresencePet, type PresencePetSeam } from './remote-presence-pet.ts'
 import { claimPostureKey, postureTargets, probePosture, releasePostureKey } from './posture.ts'
@@ -207,6 +207,16 @@ export interface Config {
   profile?: string
   /** Master switch for the plugin (browser half + host pairing surfaces). */
   enabled?: boolean
+  /**
+   * The manual override of the automatic pairing-network choice, for the case
+   * where the phone's own probe misjudges (see `PairingSourcePreference` in
+   * routes.ts). `auto` (default) names the public base in the QR link and lets
+   * the landing page switch to a LAN origin when one answers; `public` pins the
+   * public base and disables the probe; `lan` pins the first LAN literal and
+   * skips the public hop entirely. Set through the profile patch — the settings
+   * card carries no control for it, so a save from that card leaves it alone.
+   */
+  pairingSource?: PairingSourcePreference
 }
 
 /**
@@ -245,11 +255,18 @@ 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
+
 /**
  * Fully resolved config: every field non-optional except `publicBaseUrl`,
  * which legitimately resolves to `undefined` when unset (the schema keeps it
@@ -294,6 +311,7 @@ export interface ResolvedConfigFields {
   lanBind?: ConfigField<boolean>
   profile?: ConfigField<string>
   enabled?: ConfigField<boolean>
+  pairingSource?: ConfigField<PairingSourcePreference>
 }
 
 /** Read one resolved config field, following the live reference the schema produces. */
@@ -360,6 +378,7 @@ const DEFAULTS: ResolvedConfig = {
   lanBind: undefined,
   profile: resolveManagedProfile(undefined, undefined, process.env.DSH_PROFILE),
   enabled: true,
+  pairingSource: 'auto',
 }
 
 /**
@@ -406,6 +425,7 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
     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()))
 
@@ -475,6 +495,14 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
   // '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: 'off' | 'quick' | 'named' = 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: ReturnType<typeof nodeSetTimeout> | undefined
+  /** Dedupes the unbound-port warning to one line per unsettled episode. */
+  let portSettleWarned = false
   tunnel.onPhase((info: TunnelInfo) => {
     if (tunnelMode === 'off') return
     if (info.phase === 'running' && info.url !== undefined) {
@@ -501,6 +529,7 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
     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
@@ -616,6 +645,7 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
     ...makeRoutes({
       service,
       requirePairingForLan: () => resolve().requirePairingForLan,
+      pairingSource: () => resolve().pairingSource,
       lanBindStatus,
       indexDocument: fetchAppShell,
       trustedHosts: () => {
@@ -647,13 +677,13 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
     // 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)
@@ -669,7 +699,12 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
   let postureWasExposed = false
   const runPostureProbe = (): void => {
     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)
@@ -679,7 +714,7 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
     const claim = claimPostureKey(postureKey, key)
     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
@@ -833,18 +868,13 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
   }
   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 = (): void => {
-    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: ResolvedConfig, port: number | undefined): void => {
+    const plan = tunnelPlanOf(value, port)
     tunnelMode = plan.mode
     publicBase.setMode(plan.mode)
     const liveTunnelUrl = publicBase.quickUrl()
@@ -903,6 +933,36 @@ function applyImpl(ctx: Context, config?: ResolvedConfigFields): void {
         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 = (): void => {
+    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/src/lan-source.ts

@@ -0,0 +1,132 @@
+/**
+ * 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
+
+/** 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 function appShellLanSwitchScript(hop: LanSourceHop): string {
+  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/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) {