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

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 */