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

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/routes.d.ts

@@ -24,6 +24,7 @@ import type { WebRoute } from '@deepseek-ai/dsh-host-webserver';
 import { z } from 'zod';
 import { type PairingService, type PairingSnapshot } from './pairing.ts';
 import { type PairGrantStore } from './pair-grant.ts';
+import { type LanSourceHop } from './lan-source.ts';
 /**
  * Browser-trust fence for the /api/pair routes, mirroring the connection
  * package's internal fence semantics (Host/Origin based, DNS-rebinding and
@@ -119,11 +120,18 @@ export declare function publicHostOf(url: string | undefined): string | undefine
  * 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 declare const APP_DEVICE_STORAGE_KEY = "dsh-remote-device";
 export declare function appShellCaptureScript(deviceId: string): string;
@@ -134,8 +142,18 @@ export declare 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 declare function patchAppShell(html: string, deviceId: string): string;
+export declare function patchAppShell(html: string, deviceId: string, hop?: LanSourceHop): string;
 /**
  * The reopen service worker served at PAIR_PATHS.appServiceWorker. A paired
  * phone comes back to `/` from history, bookmarks, or tab restore; the
@@ -144,9 +162,10 @@ export declare 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,
@@ -168,6 +187,12 @@ export declare const PAIR_PATHS: {
     readonly acceptPage: "/pair-accept";
     /** The cookieless app landing: serves the official shell for a paired device. */
     readonly 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.
+     */
+    readonly ping: "/pair-ping";
     /**
      * The reopen service worker (registered by the capture script). Root-level
      * path so its default script-directory scope already covers `/`.
@@ -206,12 +231,49 @@ export declare class PairingEventsStream {
     /** Stream count (tests/diagnostics). */
     get size(): number;
 }
+/**
+ * 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 declare const PAIRING_SOURCE_OPTIONS: readonly PairingSourcePreference[];
+/**
+ * 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 declare function lanSourceCandidates(lanBases: readonly string[], currentOrigin: string): string[];
 /** 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

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

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/routes.ts"],"names":[],"mappings":"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"}