@linxin666/dsh-remote-web-ui 0.3.6 → 0.3.10

package/src/gate.ts

@@ -6,9 +6,15 @@
  *
  * Policy: loopback requests (the desktop) pass without a device identity;
  * every non-loopback /api request must carry a live, non-revoked device
- * cookie. This makes the QR the only way into a LAN-exposed dsh web and
- * gives "停止" real teeth: revoked devices 403 on their next request,
- * including the mux/SSE stream (which then dies on reconnect).
+ * cookie — intended to make the QR the only way into a LAN-exposed dsh web
+ * and to give "停止" real teeth for direct /api callers.
+ *
+ * Cohort reality (0.1.2-alpha.2): NOTHING emits api/gate in the official
+ * runtime, so this listener never fires there and direct /api is governed
+ * solely by the harness fence + browser-auth cookie. The pairing gate with
+ * real teeth lives on the plugin's own /remote channel (remote-api.ts); the
+ * listener stays wired for cohort lines that do carry the seam, and the
+ * README security model states the gap plainly.
  */
 
 import type { IncomingMessage } from 'node:http'
@@ -100,8 +106,8 @@ export function makeGateListener(
 
 /**
  * Whether a request carries a live, non-revoked paired-device cookie for
- * this service. Sibling host routes outside /api (aionui-panel, etc.) use
- * the same check via the remoteWebUiPairing service.
+ * this service. Sibling host routes outside /api (the right-panel
+ * /sidebar/* routes, etc.) use the same check via the remoteWebUiPairing service.
  * @param service - the pairing service that owns the device table.
  * @param request - the incoming HTTP request.
  * @returns true when the cookie names a live session (and lastSeenAt was refreshed).

package/src/index.ts

@@ -13,23 +13,27 @@ import { join } from 'node:path'
 import { setInterval as nodeSetInterval, setTimeout as nodeSetTimeout } from 'node:timers'
 import type { IncomingMessage } from 'node:http'
 import type { Context } from '@deepseek-ai/cordis'
-import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings'
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
 import z from 'schemastery'
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import type {} from '@deepseek-ai/dsh-agent'
 import type {} from '@deepseek-ai/dsh-commands'
+// Type-only: pulls the host-side Context merge (ctx.connection, whose
+// authenticatedUrl the /pair-accept redirect consumes).
+import type {} from '@deepseek-ai/dsh-client-connection'
 import { DEFAULT_IDLE_EXPIRE_MS, PairingService, type PairingConfig } from './pairing.ts'
 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 { makeMobileRoutes } from './mobile-routes.ts'
-import { makeMobileApiRoutes } from './mobile-api.ts'
-import { PendingTracker } from './mobile-pending.ts'
-import { makePairedModelCatalogRoutes } from './paired-model-catalog.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'
 import { lanIPv4Addresses } from './lan.ts'
+import { ensureFirewallRule, firewallSummary, removeFirewallRule } from './firewall.ts'
+import { lanBindState, writeLanBind } from './lan-bind.ts'
+import { desiredBindHost, desiredBindPort, firewallActionNeeded, pendingRestartOf, type AppliedFirewallState, type StartupFacts } from './lan-bind-plan.ts'
+import { createInnerAuth } from './inner-auth.ts'
 import { TunnelManager, type TunnelInfo } from './tunnel.ts'
 import {
   checkUpdates,
@@ -54,6 +58,12 @@ declare module '@deepseek-ai/cordis' {
      * fires this per /api request before bridging to the API proxy on
      * deployments that carry the pairing/revocation seam; call `next()` to
      * delegate, return false (without calling it) to veto with 403.
+     *
+     * Cohort note (0.1.2-alpha.2): the official runtime ships NO emitter
+     * for this event, so the listener below never fires there and direct
+     * /api stays under the harness fence + browser auth. It is wired anyway
+     * so cohort lines that do carry the seam get pairing enforcement on
+     * direct /api without a plugin change.
      */
     'api/gate'(
       this: Context,
@@ -68,14 +78,14 @@ declare module '@deepseek-ai/cordis' {
 export const name = 'remote-web-ui'
 
 /** Services required before the pairing surfaces can mount. */
-export const inject = ['webServer', 'apiProxy', 'commands', 'agents']
+export const inject = ['webServer', 'typertGateway', 'connection']
 
 /**
  * Settings namespace of the remote-control capability — the section the web
  * settings surface edits. Spelled here rather than imported: the browser
  * half spells the same value and must not depend on a Host package.
  */
-export const REMOTE_WEB_UI_SETTINGS_NAMESPACE = settingsNamespace('remote-web-ui')
+export const REMOTE_WEB_UI_SETTINGS_NAMESPACE = 'remote-web-ui' as SettingsNamespace
 
 /** Plugin config, validated by the same-named schemastery schema. */
 export interface Config {
@@ -95,9 +105,14 @@ export interface Config {
   /**
    * When true (default), a desktop Web GUI opened at a non-loopback origin
    * rides the gated `/remote/api` channel and must carry a live paired-device
-   * cookie — the QR is the only way into remote desktop, and stop() cuts
-   * paired devices off. Set false to keep the desktop on plain `/api`
-   * (only useful when that origin is already trusted for `/api`).
+   * cookie — the QR is the only way into remote desktop, and stop()/revoke()
+   * cut the /remote channel and the pairing cookie off immediately. Scope
+   * note for this cohort: direct /api is governed by the harness fence +
+   * browser-auth cookie (the api/gate seam has no emitter on 0.1.2-alpha.2),
+   * so a harness browser credential a device has already redeemed is not
+   * invalidated by stop() — see the README security model. Set false to keep
+   * the desktop on plain `/api` (only useful when that origin is already
+   * trusted for `/api`).
    */
   requirePairingForLan?: boolean
   /**
@@ -125,12 +140,26 @@ export interface Config {
    */
   autoTunnel?: boolean
   /**
-   * Mobile composer behavior: when true (default), a plain Enter in the
-   * phone chat textarea sends the prompt and Shift+Enter inserts a newline.
-   * When false, plain Enter inserts a newline and only the send button
-   * sends (Shift+Enter keeps inserting a newline).
+   * LAN bind toggle. When the user flips it (true or false) the plugin
+   * writes the managed webserver block into the profile patch — true pins
+   * the bind default to 0.0.0.0 (an explicit --host flag still wins), false
+   * pins it back to 127.0.0.1 — and maintains the matching host firewall
+   * rule (Windows netsh; Linux firewalld/ufw/iptables; other platforms
+   * report the firewall as unmanaged). The block takes effect when the
+   * process next applies the profile — the live patch watcher recomposes on
+   * some profile shapes, otherwise on the next start — and the settings
+   * card reports the divergence (pendingRestart) instead of guessing.
+   * While the toggle has never been set (undefined), the plugin does not
+   * touch the patch file at all.
    */
-  mobileEnterToSend?: boolean
+  lanBind?: boolean
+  /**
+   * The profile whose cordis.patch.yml the LAN bind toggle manages.
+   * Defaults to the DSH_PROFILE environment variable, then "web". Must be
+   * a single safe path segment (the DSH_PROFILE env fallback bypasses this
+   * schema, so the path builder asserts containment independently).
+   */
+  profile?: string
   /** Master switch for the plugin (browser half + host pairing surfaces). */
   enabled?: boolean
 }
@@ -145,7 +174,8 @@ export const Config: z<Config> = z.object({
   publicBaseUrl: z.string(),
   devicesFile: z.string(),
   autoTunnel: z.boolean().default(false),
-  mobileEnterToSend: z.boolean().default(true),
+  lanBind: z.boolean(),
+  profile: z.string().pattern(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
   enabled: z.boolean().default(true),
 })
 
@@ -157,9 +187,12 @@ const SWEEP_INTERVAL_MS = 10_000
  * which legitimately resolves to `undefined` when unset (the schema keeps it
  * optional, so `Required` alone would over-narrow it to `string`).
  */
-type ResolvedConfig = Required<Omit<Config, 'publicBaseUrl' | 'devicesFile'>> & {
+type ResolvedConfig = Required<Omit<Config, 'publicBaseUrl' | 'devicesFile' | 'lanBind' | 'profile'>> & {
   publicBaseUrl: string | undefined
   devicesFile: string
+  /** undefined until the user flips the toggle once; undefined never writes the patch. */
+  lanBind: boolean | undefined
+  profile: string
 }
 
 /**
@@ -198,7 +231,8 @@ const DEFAULTS: ResolvedConfig = {
   publicBaseUrl: undefined,
   devicesFile: defaultDevicesFile(),
   autoTunnel: false,
-  mobileEnterToSend: true,
+  lanBind: undefined,
+  profile: process.env.DSH_PROFILE ?? 'web',
   enabled: true,
 }
 
@@ -220,12 +254,13 @@ function applyImpl(ctx: Context, config?: Config): void {
     publicBaseUrl: config?.publicBaseUrl,
     devicesFile: config?.devicesFile ?? DEFAULTS.devicesFile,
     autoTunnel: config?.autoTunnel ?? DEFAULTS.autoTunnel,
-    mobileEnterToSend: config?.mobileEnterToSend ?? DEFAULTS.mobileEnterToSend,
+    lanBind: config?.lanBind,
+    profile: config?.profile ?? process.env.DSH_PROFILE ?? DEFAULTS.profile,
     enabled: config?.enabled ?? DEFAULTS.enabled,
   }
   // The live source the pairing service and the gate read: the settings
   // section once the web settings surface is served, the composition entry
-  // otherwise (installSettingsSection swaps it when the namespace registers).
+  // otherwise (installSection swaps it when the namespace registers).
   let current: () => Config = () => config ?? {}
   const resolve = (): ResolvedConfig => {
     const value = current()
@@ -239,7 +274,8 @@ function applyImpl(ctx: Context, config?: Config): void {
       publicBaseUrl: value.publicBaseUrl,
       devicesFile: value.devicesFile ?? DEFAULTS.devicesFile,
       autoTunnel: value.autoTunnel ?? DEFAULTS.autoTunnel,
-      mobileEnterToSend: value.mobileEnterToSend ?? DEFAULTS.mobileEnterToSend,
+      lanBind: value.lanBind,
+      profile: value.profile ?? process.env.DSH_PROFILE ?? DEFAULTS.profile,
       enabled: value.enabled ?? DEFAULTS.enabled,
     }
   }
@@ -247,7 +283,7 @@ function applyImpl(ctx: Context, config?: Config): void {
 
   // ── auto tunnel ─────────────────────────────────────────────────────────
   // The minted public URL becomes the QR base (and the pairing fence's
-  // trusted host). Phone /api traffic rides the plugin's own /m/api channel,
+  // trusted host). Phone /api traffic rides the plugin's own /remote channel,
   // which is NOT subject to the connection trust fence — so no fence
   // mutation is needed here (a distributable plugin must not change the
   // harness's connection plugin).
@@ -277,11 +313,18 @@ function applyImpl(ctx: Context, config?: Config): void {
   // sampling stance. The QR can only advertise addresses the fence accepts;
   // every interface gets its own base URL so a multi-homed machine can pick
   // the network the phone can actually reach.
-  const lanBases = ctx.webServer.host === '0.0.0.0'
-    ? lanIPv4Addresses().map(address => ({ address, base: `http://${address}:${String(ctx.webServer.port)}` }))
-    : []
-  service.setLanBases(lanBases)
-  const lanAddresses = lanBases.map(entry => entry.address)
+  // A recompose pass can hand the plugin a webServer whose facts have not
+  // settled yet (host unset, port undefined); deriving LAN bases from that
+  // would advertise :undefined links or clear a working set, so the bases
+  // only update when both facts are readable.
+  const bindKnown = (ctx.webServer.host === '0.0.0.0' || ctx.webServer.host === '127.0.0.1')
+    && Number.isFinite(ctx.webServer.port)
+  if (bindKnown) {
+    const lanBases = ctx.webServer.host === '0.0.0.0'
+      ? lanIPv4Addresses().map(address => ({ address, base: `http://${address}:${String(ctx.webServer.port)}` }))
+      : []
+    service.setLanBases(lanBases)
+  }
 
   // Push a committed settings section into the service and gate. The service
   // config object is read per operation (token mint, touch, sweep), and the
@@ -292,12 +335,6 @@ function applyImpl(ctx: Context, config?: Config): void {
   // (now vetoing every non-loopback request) instead of opening the fence.
   let disposeRoutes: (() => void) | undefined
   let disposeSweep: (() => void) | undefined
-  // The phone's data channel: pairing routes + the /m page + the /m/api
-  // proxy (which needs the host ApiProxy service; the plugin injects it).
-  const apiProxy = ctx.get('apiProxy')
-  if (apiProxy === undefined) {
-    console.warn('remote-web-ui: apiProxy service unavailable — the mobile data channel is disabled')
-  }
   // ── remote update ────────────────────────────────────────────────────────
   // The dsh-web self-update surface: probe the npm registry for family
   // releases and run `pnpm update --latest` in the owning profile. Resolutions
@@ -372,29 +409,90 @@ function applyImpl(ctx: Context, config?: Config): void {
       })
     },
   })
+  // LAN-bind facts for the settings card, re-read per request so a hot
+  // rebind (the patch watcher recomposes the process) and a fresh toggle
+  // round are both reflected without a restart.
+  let lastKnownPort: number | undefined
+  let lastFirewallApplied: AppliedFirewallState | undefined
+  const lanBindStatus = (): Record<string, unknown> => {
+    const resolvedNow = resolve()
+    let state: { blockPresent: boolean; host?: string; port?: number }
+    try {
+      state = lanBindState(resolvedNow.profile)
+    } catch {
+      // An unsafe profile value must not take the whole status endpoint down.
+      state = { blockPresent: false }
+    }
+    const lanOn = state.host === '0.0.0.0'
+    const port = Number.isFinite(ctx.webServer.port) ? ctx.webServer.port : lastKnownPort
+    if (Number.isFinite(ctx.webServer.port)) lastKnownPort = ctx.webServer.port
+    const startup = ctx.get('webStartup') as StartupFacts | undefined
+    const desiredHost = resolvedNow.lanBind === undefined
+      ? undefined
+      : desiredBindHost(resolvedNow.lanBind === true, startup?.host)
+    return {
+      profile: resolvedNow.profile,
+      setting: resolvedNow.lanBind ?? null,
+      blockHost: state.host ?? null,
+      bindHost: ctx.webServer.host,
+      port,
+      lanUrls: ctx.webServer.host === '0.0.0.0' && port !== undefined
+        ? lanIPv4Addresses().map(address => `http://${address}:${String(port)}`)
+        : [],
+      firewall: port !== undefined ? firewallSummary(port, lanOn) : { ok: true, managed: false },
+      platform: process.platform,
+      // The running bind does not follow the block on every deployment (the
+      // live patch watcher is profile-shape dependent): flag the divergence
+      // so the card can ask for a restart instead of looking broken. The
+      // comparison uses the effective desired host (a CLI --host wins over
+      // the toggle), not the raw toggle.
+      pendingRestart: pendingRestartOf(resolvedNow.lanBind, desiredHost, ctx.webServer.host),
+    }
+  }
+  // The process's inner browser credential: the proxied /api re-issues to
+  // 127.0.0.1, where the connection route enforces the harness browser-auth
+  // cookie (authority-bound; no loopback exemption on this cohort), so a
+  // device's own cookie can never satisfy the inner check. The plugin
+  // redeems its own launch token once and attaches the cookie to inner
+  // requests; the credential is only ever exercised behind the pairing gate
+  // in remote-api.ts.
+  const innerAuth = createInnerAuth(() => {
+    if (!Number.isFinite(ctx.webServer.port)) return undefined
+    try {
+      return (ctx.connection as { authenticatedUrl?: (base: string) => string }).authenticatedUrl?.(`http://127.0.0.1:${String(ctx.webServer.port)}/`)
+    } catch {
+      return undefined
+    }
+  })
+  // The official index document for the /pair-app landing, fetched from the
+  // inner loopback with the process credential and cached briefly (the shell
+  // is static; skins/injections settle right after boot).
+  const APP_SHELL_TTL_MS = 30_000
+  let appShellCache: { at: number; html: string } | undefined
+  const fetchAppShell = async (): Promise<string | undefined> => {
+    if (!Number.isFinite(ctx.webServer.port)) return undefined
+    if (appShellCache !== undefined && Date.now() - appShellCache.at < APP_SHELL_TTL_MS) return appShellCache.html
+    const cookie = await innerAuth.ready()
+    try {
+      const response = await fetch(`http://127.0.0.1:${String(ctx.webServer.port)}/`, {
+        headers: cookie !== undefined ? { cookie } : undefined,
+      })
+      if (!response.ok) return undefined
+      const html = await response.text()
+      appShellCache = { at: Date.now(), html }
+      return html
+    } catch {
+      return undefined
+    }
+  }
   const routes = [
-    ...makeRoutes({ service, lanAddresses, requirePairingForLan: () => resolve().requirePairingForLan }),
-    ...makeMobileRoutes(),
-    ...(apiProxy !== undefined
-      ? makeMobileApiRoutes({
-          service,
-          apiProxy,
-          pendingTracker: new PendingTracker(),
-          mobileEnterToSend: () => resolve().mobileEnterToSend,
-          commandDispatcher: ctx.commands !== undefined && ctx.agents !== undefined
-            ? {
-                async execute(sessionId, line, signal) {
-                  const agent = ctx.agents.get(sessionId as never)
-                  if (agent === undefined) return { error: 'session-not-found' as const }
-                  const execution = await ctx.commands.execute(agent, line, [], signal)
-                  if (execution === undefined) return { error: 'unknown-command' as const }
-                  return { ok: true as const, result: execution.result }
-                },
-              }
-            : undefined,
-        })
-      : []),
-    ...(apiProxy !== undefined ? makePairedModelCatalogRoutes({ service, apiProxy, lanAddresses }) : []),
+    ...makeRoutes({
+      service,
+      lanAddresses: service.lanAddresses,
+      requirePairingForLan: () => resolve().requirePairingForLan,
+      lanBindStatus,
+      indexDocument: fetchAppShell,
+    }),
     // The remote desktop channel: policy-gated `/remote` prefix that
     // re-issues fenced paths to loopback (see remote-api.ts). The live
     // requirePairingForLan is re-read per request, same as the gate listener
@@ -404,6 +502,7 @@ function applyImpl(ctx: Context, config?: Config): void {
       service,
       port: ctx.webServer.port,
       requirePairingForLan: () => resolve().requirePairingForLan,
+      auth: innerAuth,
     }),
     ...updateRoutes,
   ]
@@ -411,6 +510,7 @@ function applyImpl(ctx: Context, config?: Config): void {
     service,
     port: ctx.webServer.port,
     requirePairingForLan: () => resolve().requirePairingForLan,
+    auth: innerAuth,
   })
   const gate = makeGateListener(service, () => resolve().requirePairingForLan, () => resolve().enabled)
   ctx.effect(() => ctx.on('api/gate', gate), 'remote-web-ui: api gate')
@@ -456,21 +556,89 @@ function applyImpl(ctx: Context, config?: Config): void {
   const initialPostureTimer = nodeSetTimeout(() => { runPostureProbe() }, 5_000)
   initialPostureTimer.unref()
   ctx.effect(() => () => { clearTimeout(initialPostureTimer) }, 'remote-web-ui: posture probe boot')
-  // Sibling plugins (aionui-panel, …) look this up by name. Absent when this
+  // Sibling plugins (dsh-better-sidebar, …) look this up by name. Absent when this
   // plugin is not installed; stop() / enabled=false still refuse cookies.
   new RemoteWebUiPairing(ctx, (request) => {
     if (!resolve().enabled) return false
     return isPairedDeviceRequest(service, request)
   })
 
-  if (lanAddresses.length > 0) {
-    const urls = lanAddresses.map(ip => `http://${ip}:${String(ctx.webServer.port)}/m/`).join(' , ')
-    console.log(`remote-web-ui: mobile UI reachable on LAN at ${urls}`)
+  // Remote-presence to pet-visibility link: while a paired device is online
+  // (an active phone mirror), hide the host-global pet through the pet's OWN
+  // hide switch; when the last device has been offline for a grace window,
+  // show it again (user design; the pet plugin is optional, so the seam is
+  // resolved per transition and every failure degrades to a no-op).
+  const presencePet = startRemotePresencePet({
+    onState: listener => service.onState(listener),
+    pet: (): PresencePetSeam | undefined => {
+      try {
+        return ctx.get('pet') as unknown as PresencePetSeam | undefined
+      } catch {
+        return undefined
+      }
+    },
+  })
+  ctx.effect(() => presencePet, 'remote-web-ui: remote-presence pet visibility')
+
+  if (service.lanAddresses.length > 0) {
+    const urls = service.lanAddresses.map(ip => `http://${ip}:${String(ctx.webServer.port)}`).join(' , ')
+    console.log(`remote-web-ui: the paired Web GUI is reachable on LAN at ${urls}`)
+  }
+  // Cohort honesty (see the README security model): the pairing gate covers
+  // the plugin's own /remote channel; direct /api from LAN origins is
+  // governed by the harness fence + browser-auth cookie, and this cohort's
+  // api/gate seam has no emitter — so stop()/revoke() cannot invalidate a
+  // browser credential a device has already redeemed.
+  if (ctx.webServer.host === '0.0.0.0') {
+    console.warn('remote-web-ui: LAN-exposed bind — pairing gates the /remote channel; direct /api stays under the harness fence + browser auth (stop() does not revoke an already-redeemed browser credential)')
   }
 
   const sync = (): void => {
     const value = resolve()
     service.config = pairingConfigOf(value)
+    // LAN bind toggle: only write the managed patch block once the user has
+    // flipped it (undefined = untouched, never write). Desired host/port come
+    // from the CLI flags when given (flags win), else from the toggle and
+    // the currently bound port. The block takes effect on the next start, so
+    // the re-assert at every boot keeps it in sync with both the toggle and
+    // the flags.
+    if (value.lanBind !== undefined) {
+      const startup = ctx.get('webStartup') as StartupFacts | undefined
+      const desiredHost = desiredBindHost(value.lanBind === true, startup?.host)
+      const desiredPort = desiredBindPort(startup?.port, Number.isFinite(ctx.webServer.port) ? ctx.webServer.port : undefined)
+      if (desiredPort === undefined) {
+        console.error('remote-web-ui: cannot assert the lan-bind block — the web server port is not known yet')
+      } else {
+        try {
+          const current = lanBindState(value.profile)
+          if (current.host !== desiredHost || current.port !== desiredPort) {
+            writeLanBind(desiredHost, desiredPort, value.profile)
+            console.log(`remote-web-ui: lan-bind block written for profile ${value.profile} (${desiredHost}:${String(desiredPort)}); it takes effect when the profile next applies (the card reports pendingRestart until the running bind follows)`)
+          }
+        } catch (error) {
+          console.error(`remote-web-ui: failed to write the lan-bind block: ${error instanceof Error ? error.message : String(error)}`)
+        }
+      }
+      // Keep the firewall rule aligned with the toggle (managed platforms
+      // only; see firewall.ts). The probes and rule rewrites are blocking
+      // subprocesses, so they run only when the desired state actually moved
+      // — not on every unrelated settings save. The port is the live bind
+      // port; without it there is nothing to align yet.
+      const livePort = Number.isFinite(ctx.webServer.port) ? ctx.webServer.port : undefined
+      if (livePort === undefined) {
+        console.error('remote-web-ui: cannot align the host firewall rule — the web server port is not known yet')
+      } else {
+        const nextFirewall: AppliedFirewallState = { enabled: value.lanBind === true, port: livePort }
+        if (firewallActionNeeded(lastFirewallApplied, nextFirewall)) {
+          const ruleOk = nextFirewall.enabled ? ensureFirewallRule(nextFirewall.port) : removeFirewallRule(nextFirewall.port)
+          if (ruleOk) {
+            lastFirewallApplied = nextFirewall
+          } else {
+            console.error('remote-web-ui: the host firewall rule could not be updated (admin rights required on managed platforms)')
+          }
+        }
+      }
+    }
     // The auto tunnel owns the public base while enabled: the minted URL
     // lands in the service through the tunnel's phase listener. The manual
     // publicBaseUrl applies only when the auto tunnel is off.
@@ -545,12 +713,14 @@ function applyImpl(ctx: Context, config?: Config): void {
     table.push({ kind: 'script', placement: 'head', text: REMOTE_CHANNEL_BOOT_SCRIPT })
   }), 'remote-web-ui: remote channel boot patch')
 
-  installSettingsSection(ctx, REMOTE_WEB_UI_SETTINGS_NAMESPACE, Config, config ?? {}, {
-    setSource: (source) => {
-      current = source
-      sync()
-    },
-    onChange: sync,
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.settings.installSection(ctx, REMOTE_WEB_UI_SETTINGS_NAMESPACE, Config, config ?? {}, {
+      setSource: (source) => {
+        current = source
+        sync()
+      },
+      onChange: sync,
+    })
   })
   sync()
 }

package/src/inner-auth.ts

@@ -0,0 +1,85 @@
+/**
+ * The inner browser credential for the remote desktop channel. The proxied
+ * /api re-issues requests to 127.0.0.1, where the connection plugin's route
+ * enforces the harness browser-auth cookie — an authority-bound signed cookie
+ * with no loopback exemption on this cohort line, so a cookie minted for the
+ * device's own authority can never satisfy the inner check. The process
+ * therefore redeems its own launch token (the same one-time exchange every
+ * paired device's first navigation performs) and attaches the resulting
+ * cookie to inner requests. The credential is only ever exercised behind the
+ * pairing gate: while requirePairingForLan is on, every proxied call already
+ * carried a live paired-device cookie before this module is consulted.
+ */
+
+/** Browser-auth credential the proxy attaches to loopback-bound requests. */
+export interface InnerAuth {
+  /**
+   * Resolve the `name=value` cookie pair for inner requests, or undefined
+   * when the launch token is unavailable (the proxy then sends without a
+   * credential and the inner route answers 401, exactly as before).
+   */
+  ready(): Promise<string | undefined>
+  /** Drop the cached credential; the next ready() re-redeems. */
+  invalidate(): void
+}
+
+/** The harness browser-auth cookie name prefix (see dsh-client-connection). */
+const BROWSER_AUTH_COOKIE_PREFIX = 'dsh-auth-'
+
+/**
+ * Build the inner-auth handle.
+ * @param launchUrl - the launch-token URL for the inner loopback authority
+ *   (the connection service's authenticatedUrl of `http://127.0.0.1:<port>/`),
+ *   or undefined when the connection service or port is unavailable.
+ * @param fetchImpl - injectable fetch (tests).
+ */
+export function createInnerAuth(
+  launchUrl: () => string | undefined,
+  fetchImpl: typeof fetch = fetch,
+): InnerAuth {
+  let cached: string | undefined
+  let inflight: Promise<string | undefined> | undefined
+
+  const redeem = async (): Promise<string | undefined> => {
+    const url = launchUrl()
+    if (url === undefined) return undefined
+    try {
+      // redirect: 'manual' keeps the 303's set-cookie readable instead of
+      // following it; the exchange itself is a plain GET with the token in
+      // the query, exactly what a first browser visit performs.
+      const response = await fetchImpl(url, { redirect: 'manual' })
+      const raw = response.headers.get('set-cookie')
+      if (raw === null) return undefined
+      // Generated cookie values are base64url and never contain commas, so a
+      // comma split followed by a prefix match finds the browser-auth entry
+      // even when the exchange sets several cookies.
+      const entry = raw
+        .split(',')
+        .map((part) => part.trim())
+        .find((part) => part.startsWith(BROWSER_AUTH_COOKIE_PREFIX))
+      if (entry === undefined) return undefined
+      const pair = entry.split(';')[0]?.trim()
+      return pair !== undefined && pair.includes('=') ? pair : undefined
+    } catch {
+      return undefined
+    }
+  }
+
+  return {
+    ready(): Promise<string | undefined> {
+      if (cached !== undefined) return Promise.resolve(cached)
+      inflight ??= redeem().then((value) => {
+        if (value !== undefined) cached = value
+        inflight = undefined
+        return value
+      }, () => {
+        inflight = undefined
+        return undefined
+      })
+      return inflight
+    },
+    invalidate(): void {
+      cached = undefined
+    },
+  }
+}

package/src/lan-bind-plan.ts

@@ -0,0 +1,81 @@
+/**
+ * Pure decision helpers shared by the lan-bind sync path (index.ts) and the
+ * status path (lanBindStatus). Extracted so the flags-win precedence, the
+ * pending-restart divergence check, and the firewall re-apply gate have one
+ * implementation and direct unit coverage.
+ */
+
+/** The two bind hosts the managed block pins. */
+export type LanBindPlanHost = '0.0.0.0' | '127.0.0.1'
+
+/** webStartup facts the CLI hands the process (absent unless a flag was passed). */
+export interface StartupFacts {
+  host?: string
+  port?: number
+}
+
+/**
+ * The bind host the managed block should pin: an explicit CLI --host wins,
+ * otherwise the toggle decides. CLI hosts outside the two managed literals
+ * (a pinned specific IP) are not a state the toggle manages — the toggle
+ * decides, and the card surfaces the divergence honestly.
+ * @param lanBind - the toggle value.
+ * @param startupHost - the CLI-provided bind host, when given.
+ * @returns the desired bind host literal.
+ */
+export function desiredBindHost(lanBind: boolean, startupHost: string | undefined): LanBindPlanHost {
+  if (startupHost === '0.0.0.0' || startupHost === '127.0.0.1') return startupHost
+  return lanBind ? '0.0.0.0' : '127.0.0.1'
+}
+
+/**
+ * The port the managed block should pin: the CLI port when given, else the
+ * currently bound port. Undefined when neither is readable yet (the caller
+ * skips the write and reports why).
+ * @param startupPort - the CLI-provided port, when given.
+ * @param livePort - the currently bound port, when finite.
+ */
+export function desiredBindPort(startupPort: number | undefined, livePort: number | undefined): number | undefined {
+  if (typeof startupPort === 'number' && Number.isFinite(startupPort)) return startupPort
+  return typeof livePort === 'number' && Number.isFinite(livePort) ? livePort : undefined
+}
+
+/**
+ * Whether the running bind has not caught up with what the toggle (plus a
+ * possibly overriding CLI host) will pin. Compared against the effective
+ * desired host — not the raw toggle — so a flag-managed bind is not reported
+ * as pending forever.
+ * @param lanBind - the toggle value (undefined = untouched, never pending).
+ * @param desiredHost - the effective desired host, or undefined when untouched.
+ * @param liveHost - the currently bound host.
+ */
+export function pendingRestartOf(
+  lanBind: boolean | undefined,
+  desiredHost: LanBindPlanHost | undefined,
+  liveHost: string | undefined,
+): boolean {
+  if (lanBind === undefined || desiredHost === undefined) return false
+  return liveHost !== desiredHost
+}
+
+/** The last firewall state this process applied. */
+export interface AppliedFirewallState {
+  enabled: boolean
+  port: number
+}
+
+/**
+ * Whether the firewall rule must be (re)applied: only when the toggle or the
+ * bound port moved since the last application. Keeps unrelated settings
+ * saves from spawning netsh/firewall-cmd delete+add churn.
+ * @param previous - the state applied earlier by this process, if any.
+ * @param next - the state the settings now ask for, if derivable.
+ */
+export function firewallActionNeeded(
+  previous: AppliedFirewallState | undefined,
+  next: AppliedFirewallState | undefined,
+): boolean {
+  if (next === undefined) return false
+  if (previous === undefined) return true
+  return previous.enabled !== next.enabled || previous.port !== next.port
+}