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

package/src/lan-bind.ts

@@ -0,0 +1,145 @@
+/**
+ * LAN bind toggle: the managed cordis patch block that pins the web
+ * server's bind. On = a block binding 0.0.0.0; off = the same block binding
+ * 127.0.0.1. The block takes effect on the next `dsh web` start (the live
+ * patch watcher cannot rebind a running listener, and on this harness line
+ * the user patch layer cannot evaluate webStartup-dependent expressions
+ * reliably - static values are the only dependable form), so the plugin
+ * re-asserts the block at every boot and the settings card reports the
+ * running bind honestly.
+ *
+ * Same-id patch rows REPLACE the row config wholesale, so the block carries
+ * the official web-app webserver row's full config (bind + compression)
+ * with the bind values materialized. The CLI's --host 0.0.0.0 guard stays
+ * intact: deliberate LAN exposure happens through this configuration layer
+ * only. Until the user flips the toggle once, the plugin never touches the
+ * patch file.
+ *
+ * The block discipline (markers, atomic write, strip-and-rewrite) follows
+ * the dsh-LAN reference implementation (MIT).
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve, sep } from 'node:path'
+import { dshHome } from './dsh-home.ts'
+
+/** Profile names safe to interpolate into the patch path: one path segment, no traversal. */
+const PROFILE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+
+export const LAN_BIND_BLOCK_BEGIN = '# --- remote-web-ui lan-bind block (managed - do not edit) ---'
+export const LAN_BIND_BLOCK_END = '# --- end remote-web-ui lan-bind block ---'
+
+/** The two bind hosts the managed block pins. */
+export type LanBindHost = '0.0.0.0' | '127.0.0.1'
+
+/**
+ * The absolute path of the profile patch file this toggle manages. The value
+ * is config-controlled (and the DSH_PROFILE env fallback bypasses schema
+ * validation entirely), so the path is guarded twice: the profile must be a
+ * single safe path segment, and the resolved file must stay under the
+ * profiles directory.
+ */
+export function profilePatchFile(profile: string, home: string = dshHome()): string {
+  if (!PROFILE_PATTERN.test(profile)) {
+    throw new Error(`remote-web-ui: unsafe lan-bind profile ${JSON.stringify(profile)}`)
+  }
+  const file = resolve(join(home, 'profiles', profile, 'cordis.patch.yml'))
+  const root = resolve(join(home, 'profiles')) + sep
+  if (!file.startsWith(root)) {
+    throw new Error(`remote-web-ui: lan-bind profile ${JSON.stringify(profile)} escapes the profiles directory`)
+  }
+  return file
+}
+
+function readPatchContent(file: string): string {
+  if (!existsSync(file)) return ''
+  return readFileSync(file, 'utf8')
+}
+
+/** Escape one literal string for embedding into a RegExp pattern. */
+function escapeRegex(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** Remove the managed block (and its markers) from patch content. */
+export function stripManagedBlock(content: string): string {
+  const begin = escapeRegex(LAN_BIND_BLOCK_BEGIN)
+  const end = escapeRegex(LAN_BIND_BLOCK_END)
+  const pattern = new RegExp(`\\r?\\n?${begin}[\\s\\S]*?${end}\\r?\\n?`, 'g')
+  return content.replace(pattern, '\n')
+}
+
+/**
+ * Render the managed block for one bind state. The values are static: the
+ * user patch layer has no reliable lazy service evaluation, and the plugin
+ * re-asserts the block at every boot so CLI flags (--port, --host) win by
+ * rewriting it before the next start.
+ */
+export function managedBlock(host: LanBindHost, port: number): string {
+  return [
+    LAN_BIND_BLOCK_BEGIN,
+    '- id: webserver',
+    "  name: '@deepseek-ai/dsh-host-webserver'",
+    '  config:',
+    `    host: '${host}'`,
+    `    port: ${String(port)}`,
+    '    compression: gzip',
+    '    compressionLevel: 1',
+    '    compressionThresholdBytes: 1024',
+    LAN_BIND_BLOCK_END,
+    '',
+  ].join('\n')
+}
+
+/** The bind state a managed block pins (undefined when there is no block). */
+export interface ManagedBindState {
+  host: LanBindHost | (string & {})
+  port: number | undefined
+}
+
+/**
+ * Parse the block's pinned bind out of patch content. A block whose values
+ * were hand-edited reports the literals as-is so the card can surface them
+ * instead of silently claiming one of the two known states.
+ */
+export function managedBindOf(content: string): ManagedBindState | undefined {
+  const begin = content.indexOf(LAN_BIND_BLOCK_BEGIN)
+  if (begin === -1) return undefined
+  const end = content.indexOf(LAN_BIND_BLOCK_END, begin)
+  const block = end === -1 ? content.slice(begin) : content.slice(begin, end)
+  const hostMatch = /host:\s*'([^']+)'/.exec(block)
+  const portMatch = /port:\s*(\d+)/.exec(block)
+  return {
+    host: hostMatch?.[1] ?? '',
+    port: portMatch !== null ? Number(portMatch[1]) : undefined,
+  }
+}
+
+/** Full file-level state for the settings card and the boot re-assert. */
+export function lanBindState(profile: string, home: string = dshHome()): { blockPresent: boolean; host?: string; port?: number } {
+  const state = managedBindOf(readPatchContent(profilePatchFile(profile, home)))
+  if (state === undefined) return { blockPresent: false }
+  return { blockPresent: true, host: state.host, port: state.port }
+}
+
+/**
+ * Write (or rewrite) the managed block with the given bind. The rest of the
+ * patch file is preserved; the block is rewritten atomically (unique temp
+ * file + rename, so concurrent writers can never rename a half-written
+ * file) with the original file's permissions preserved. A hand-truncated
+ * unterminated block (BEGIN marker without END, which stripManagedBlock
+ * cannot match) is truncated at its BEGIN marker first so the rewrite can
+ * never stack a second webserver row onto the orphan.
+ */
+export function writeLanBind(host: LanBindHost, port: number, profile: string, home: string = dshHome()): void {
+  const file = profilePatchFile(profile, home)
+  const stripped = stripManagedBlock(readPatchContent(file))
+  const orphanBegin = stripped.indexOf(LAN_BIND_BLOCK_BEGIN)
+  const base = (orphanBegin === -1 ? stripped : stripped.slice(0, orphanBegin)).trimEnd()
+  const content = `${base}\n\n${managedBlock(host, port)}`
+  const mode = existsSync(file) ? statSync(file).mode & 0o777 : 0o600
+  mkdirSync(dirname(file), { recursive: true })
+  const temp = `${file}.remote-web-ui-tmp-${process.pid.toString(36)}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
+  writeFileSync(temp, content, { mode })
+  renameSync(temp, file)
+}

package/src/loopback-proxy.ts

@@ -12,6 +12,7 @@ import { request as httpRequest } from 'node:http'
 import { connect } from 'node:net'
 import type { Duplex } from 'node:stream'
 import { writeJson } from './http.ts'
+import type { InnerAuth } from './inner-auth.ts'
 
 /** WebSocket handshake headers forwarded to the loopback upstream. */
 const WS_FORWARD_HEADERS = [
@@ -37,12 +38,30 @@ const HTTP_FORWARD_RESPONSE_HEADERS = [
  * @param res - the outer response.
  * @param port - local webServer port.
  * @param upstreamPath - path + query on 127.0.0.1 (must start with `/`).
+ * @param auth - when given, the process's inner browser-auth credential is
+ *   attached so the connection plugin's /api route (fence + browser auth,
+ *   authority-bound cookie, no loopback exemption on this cohort) accepts
+ *   the re-issued request; a 401 answer invalidates the cached credential.
  */
 export function proxyLoopbackHttp(
   req: IncomingMessage,
   res: ServerResponse,
   port: number,
   upstreamPath: string,
+  auth?: InnerAuth,
+): void {
+  void Promise.resolve(auth?.ready())
+    .catch(() => undefined)
+    .then((cookie) => { pipeLoopbackHttp(req, res, port, upstreamPath, auth, typeof cookie === 'string' ? cookie : undefined) })
+}
+
+function pipeLoopbackHttp(
+  req: IncomingMessage,
+  res: ServerResponse,
+  port: number,
+  upstreamPath: string,
+  auth: InnerAuth | undefined,
+  cookie: string | undefined,
 ): void {
   const headers: Record<string, string> = {
     host: `127.0.0.1:${String(port)}`,
@@ -54,6 +73,7 @@ export function proxyLoopbackHttp(
   if (typeof contentLength === 'string') headers['content-length'] = contentLength
   const accept = req.headers.accept
   if (typeof accept === 'string') headers.accept = accept
+  if (cookie !== undefined) headers.cookie = cookie
 
   const upstream = httpRequest({
     host: '127.0.0.1',
@@ -62,6 +82,10 @@ export function proxyLoopbackHttp(
     method: req.method,
     headers,
   }, (upstreamRes) => {
+    // The cached credential went stale (secret rotation, credential store
+    // reset): drop it so the next request re-redeems. The in-flight response
+    // still pipes through untouched.
+    if (upstreamRes.statusCode === 401 && cookie !== undefined) auth?.invalidate()
     const out: OutgoingHttpHeaders = {}
     for (const name of HTTP_FORWARD_RESPONSE_HEADERS) {
       const value = upstreamRes.headers[name]
@@ -87,6 +111,8 @@ export function proxyLoopbackHttp(
  * @param head - bytes already read past the handshake.
  * @param port - local webServer port.
  * @param upstreamPath - path + query on 127.0.0.1.
+ * @param cookie - the inner browser-auth credential for the handshake, when
+ *   the upstream route enforces it (the gateway event-stream mux does).
  */
 export function proxyLoopbackUpgrade(
   req: IncomingMessage,
@@ -94,6 +120,7 @@ export function proxyLoopbackUpgrade(
   head: Buffer,
   port: number,
   upstreamPath: string,
+  cookie?: string,
 ): void {
   const lines = [
     `GET ${upstreamPath} HTTP/1.1`,
@@ -101,6 +128,7 @@ export function proxyLoopbackUpgrade(
     'Upgrade: websocket',
     'Connection: Upgrade',
   ]
+  if (cookie !== undefined) lines.push(`Cookie: ${cookie}`)
   for (const name of WS_FORWARD_HEADERS) {
     const value = req.headers[name]
     if (value === undefined) continue
@@ -109,6 +137,12 @@ export function proxyLoopbackUpgrade(
   const handshake = `${lines.join('\r\n')}\r\n\r\n`
 
   const upstream = connect(port, '127.0.0.1')
+  // A half-open tunnel path (dead-but-alive edge connection) would otherwise
+  // let the phone's mux socket sit stale for minutes: keepalive probes the
+  // pipe periodically and destroys both legs on the first real gap, so the
+  // client's reconnect + stream re-baseline re-syncs the feed in seconds.
+  ;(socket as unknown as import('node:net').Socket).setKeepAlive(true, 20_000)
+  upstream.setKeepAlive(true, 20_000)
   const tearDown = (): void => {
     upstream.destroy()
     socket.destroy()

package/src/pairing.persist.test.ts

@@ -201,4 +201,4 @@ describe('PairingService device persistence', () => {
     const deviceId = result.ok ? result.deviceId : ''
     expect(saved[deviceId]?.userAgent).toBe('Mozilla/5.0 TestPhone')
   })
-})
+})

package/src/pairing.ts

@@ -7,8 +7,12 @@
  * Security invariants:
  * - One active token at a time; `issue()` replaces it, so a refreshed QR
  *   immediately invalidates the previous link.
- * - A token is consumed by the first successful `accept()` — reuse is
- *   refused with `'used'`.
+ * - A token stays re-usable until it expires or is replaced: the first
+ *   successful `accept()` marks it consumed, but the same link may pair
+ *   again within the window (each re-accept mints a fresh device session).
+ *   Mobile flows routinely split across cookie contexts (camera preview to
+ *   in-app browser to the system browser), and the later context must be
+ *   able to complete its own pairing from the same link.
  * - Tokens expire; `accept()` on an expired token is refused like an
  *   unknown one (no oracle for validity).
  * - `stop()` revokes every device session and clears the token, so paired
@@ -51,8 +55,16 @@ export interface TokenRecord {
   address?: string
 }
 
-/** Default idle-expiry window: 7 days without heartbeat or a gated request. */
-export const DEFAULT_IDLE_EXPIRE_MS = 7 * 24 * 60 * 60 * 1000
+/**
+ * Default idle-expiry window: 30 days without a heartbeat or a gated
+ * request. The reopen service worker refreshes lastSeenAt on every
+ * navigation it serves, so the window only runs out through genuine
+ * disuse; 30 days matches the browser-credential lifetimes the surrounding
+ * flow was built around, while the effective device lifetime stays shorter
+ * than the 365-day cookie because of this sweep. Override per deployment
+ * through the idleExpireMs config.
+ */
+export const DEFAULT_IDLE_EXPIRE_MS = 30 * 24 * 60 * 60 * 1000
 
 /** Cap on the persisted/displayed User-Agent string. */
 const MAX_USER_AGENT_CHARS = 180
@@ -379,8 +391,10 @@ export class PairingService {
    */
   accept(token: string, userAgent?: string): AcceptResult {
     const record = this.tokens.get(token)
-    if (record === undefined || record.consumed || this.stopped || this.clock.now() > record.expiresAt) {
-      return { ok: false, code: record?.consumed === true ? 'used' : 'invalid' }
+    // A consumed token stays a valid bearer credential until expiry or
+    // replacement (see the module doc): re-accept mints a fresh device.
+    if (record === undefined || this.stopped || this.clock.now() > record.expiresAt) {
+      return { ok: false, code: 'invalid' }
     }
     record.consumed = true
     const deviceId = this.clock.randomToken()

package/src/remote-api.ts

@@ -1,21 +1,21 @@
 /**
  * The remote desktop data channel: `/remote` is this plugin's own prefix, so
- * the paired-device cookie is the access control (exactly like `/m/api`).
- * After that gate, every fenced same-origin path the browser rewrote here is
- * re-issued to 127.0.0.1 as a loopback-shaped request so sibling plugin
- * fences (and the connection plugin's `/api`) accept it — no `--trusted-host`
- * and no per-plugin pairing consult.
+ * the paired-device cookie is the access control. After that gate, every
+ * fenced same-origin path the browser rewrote here is re-issued to 127.0.0.1
+ * as a loopback-shaped request so sibling plugin fences (and the connection
+ * plugin's `/api`) accept it — no `--trusted-host` and no per-plugin pairing
+ * consult.
  *
  * Security model:
  * - While `requirePairingForLan` is on (default), every request must carry a
  *   live paired-device cookie, enforced before any bytes are forwarded and
  *   before any host call. With the policy off, the cookie gate is skipped
- *   (the loopback-only denials below still apply).
- * - The SDK's loopback-only privileged methods (native dialogs, the settings
- *   plane, credentials — the `PRIVILEGED_METHODS` set of client-connection)
- *   are denied here. The set is pinned by tests/remote-contract.spec.ts.
- * - `/api/pair/*`, `/api/update/*`, `/api/plugin-manager/*`,
- *   `/api/dsh-desktop-launcher/*` and `/api/dsh-web-ui-settings/*` stay physically local.
+ *   (the local-only denials below still apply).
+ * - A paired remote desktop is a full-control credential: the browser half
+ *   flips the official UI into host mode (the transport ownsHost hook), so
+ *   the configuration plane (settings, credentials, presets, deliverables)
+ *   rides this channel like every other call. The four control planes in
+ *   LOCAL_ONLY_PREFIXES stay physically local.
  * - Everything else is HTTP- or WebSocket-proxied to the local port with
  *   Host rewritten, Origin and cookies dropped, and a synthetic same-origin
  *   browser marker added after authentication. Plugin loopback fences then
@@ -28,24 +28,27 @@ import type { WebRoute, WebUpgradeRoute } from '@deepseek-ai/dsh-host-webserver'
 import type { PairingService } from './pairing.ts'
 import { readCookie } from './gate.ts'
 import { writeJson } from './http.ts'
+import type { InnerAuth } from './inner-auth.ts'
 import { proxyLoopbackHttp, proxyLoopbackUpgrade } from './loopback-proxy.ts'
 import {
-  DESKTOP_LAUNCHER_PATH,
-  LOOPBACK_ONLY_METHODS,
-  PLUGIN_MANAGER_PATH,
+  REMOTE_DEVICE_HEADER,
+  REMOTE_DEVICE_QUERY,
   REMOTE_PREFIX,
   REMOTE_UPGRADE_PATHS,
-  WEB_UI_SETTINGS_BRIDGE_PATH,
+  localOnlyDenial,
 } from './remote-methods.ts'
 
 export {
   DESKTOP_LAUNCHER_PATH,
-  LOOPBACK_ONLY_METHODS,
+  LOCAL_ONLY_PREFIXES,
   PLUGIN_MANAGER_PATH,
   REMOTE_API_PATHS,
+  REMOTE_DEVICE_HEADER,
+  REMOTE_DEVICE_QUERY,
   REMOTE_PREFIX,
   REMOTE_UPGRADE_PATHS,
   WEB_UI_SETTINGS_BRIDGE_PATH,
+  localOnlyDenial,
 } from './remote-methods.ts'
 export { REMOTE_API_PREFIX } from './remote-methods.ts'
 
@@ -76,6 +79,13 @@ export interface RemoteApiDeps {
    * edit takes effect without a restart. Defaults to true.
    */
   requirePairingForLan?: boolean | (() => boolean)
+  /**
+   * The process's inner browser-auth credential attached to re-issued
+   * requests (the connection plugin's /api route enforces that cookie and
+   * the pairing gate above already ran). Undefined keeps the previous
+   * cookie-less behavior — the inner route then answers 401 on this cohort.
+   */
+  auth?: InnerAuth
 }
 
 /** One SDK-shaped error envelope (keeps the desktop client's parse path intact). */
@@ -104,31 +114,28 @@ export function innerPathOf(pathname: string): string | undefined {
 }
 
 /**
- * Whether a paired inner path must stay physically local.
+ * Whether a paired inner path must stay physically local (delegates to the
+ * shared LOCAL_ONLY_PREFIXES table).
  * @returns a denial message, or undefined when the path may be proxied.
  */
 export function loopbackOnlyDenial(innerPath: string): string | undefined {
-  if (innerPath === '/api/pair' || innerPath.startsWith('/api/pair/')) {
-    return 'pairing endpoints stay loopback-only and stay unreachable from a paired remote desktop'
-  }
-  if (innerPath === '/api/update' || innerPath.startsWith('/api/update/')) {
-    return 'update endpoints stay loopback-only and stay unreachable from a paired remote desktop'
-  }
-  if (innerPath === PLUGIN_MANAGER_PATH || innerPath.startsWith(`${PLUGIN_MANAGER_PATH}/`)) {
-    return 'plugin-manager stays loopback-only and stays unreachable from a paired remote desktop'
-  }
-  if (innerPath === DESKTOP_LAUNCHER_PATH || innerPath.startsWith(`${DESKTOP_LAUNCHER_PATH}/`)) {
-    return 'desktop-launcher endpoints stay loopback-only and stay unreachable from a paired remote desktop'
-  }
-  if (innerPath === WEB_UI_SETTINGS_BRIDGE_PATH || innerPath.startsWith(`${WEB_UI_SETTINGS_BRIDGE_PATH}/`)) {
-    return 'settings-bridge endpoints stay loopback-only and stay unreachable from a paired remote desktop'
-  }
-  if (!innerPath.startsWith('/api/')) return undefined
-  const method = innerPath.slice('/api/'.length)
-  if (method !== '' && !method.includes('/') && LOOPBACK_ONLY_METHODS.has(method)) {
-    return `${method} is loopback-only and stays unreachable from a paired remote desktop`
-  }
-  return undefined
+  return localOnlyDenial(innerPath)
+}
+
+/**
+ * Resolve a live device credential for a gated HTTP request: the pairing
+ * cookie first, then the cookieless header the boot patch attaches. Unknown
+ * or revoked ids are a no-op - a stale id never re-arms a device.
+ * @returns the touched device id, or undefined when neither credential is live.
+ */
+export function pairedDeviceIdOf(req: IncomingMessage, service: PairingService): string | undefined {
+  const cookieDevice = readCookie(req.headers.cookie, service.config.cookieName)
+  const headerDevice = typeof req.headers[REMOTE_DEVICE_HEADER] === 'string'
+    ? (req.headers[REMOTE_DEVICE_HEADER] as string)
+    : undefined
+  const id = cookieDevice ?? headerDevice
+  if (id === undefined) return undefined
+  return service.touchDevice(id) ? id : undefined
 }
 
 /**
@@ -145,9 +152,8 @@ export function makeRemoteApiRoutes(deps: RemoteApiDeps): WebRoute[] {
     // (a stale client rewrite must not 403); loopback-only denials stay below.
     const require = typeof requirePairingForLan === 'function' ? requirePairingForLan() : requirePairingForLan
     if (require) {
-      const deviceId = readCookie(req.headers.cookie, service.config.cookieName)
-      const paired = deviceId !== undefined && service.touchDevice(deviceId)
-      if (!paired) {
+      const paired = pairedDeviceIdOf(req, service)
+      if (paired === undefined) {
         req.resume()
         envelopeError(res, 403, 'invalid-request', 'unpaired', 'this device is not paired with the desktop')
         return
@@ -175,7 +181,7 @@ export function makeRemoteApiRoutes(deps: RemoteApiDeps): WebRoute[] {
       return
     }
 
-    proxyLoopbackHttp(req, res, port, `${inner}${url.search}`)
+    proxyLoopbackHttp(req, res, port, `${inner}${url.search}`, deps.auth)
   }
 
   return [{ kind: 'prefix', path: REMOTE_PREFIX, handler }]
@@ -209,8 +215,15 @@ export function makeRemoteApiUpgradeRoutes(deps: RemoteApiDeps): WebUpgradeRoute
   const handlerFor = (fallbackPath: string) => (req: IncomingMessage, socket: Duplex, head: Buffer): void => {
     const require = typeof requirePairingForLan === 'function' ? requirePairingForLan() : requirePairingForLan
     if (require) {
-      const deviceId = readCookie(req.headers.cookie, service.config.cookieName)
-      if (deviceId === undefined || !service.touchDevice(deviceId)) {
+      // WebSocket handshakes cannot carry headers from the Web API, so the
+      // cookieless credential rides the query; the cookie stays the primary.
+      let queryDevice: string | undefined
+      try {
+        queryDevice = new URL(req.url ?? '/', 'http://127.0.0.1').searchParams.get(REMOTE_DEVICE_QUERY) ?? undefined
+      } catch { /* fall through to the cookie */ }
+      const deviceId = pairedDeviceIdOf(req, service)
+      const paired = deviceId ?? (queryDevice !== undefined && service.touchDevice(queryDevice) ? queryDevice : undefined)
+      if (paired === undefined) {
         socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n')
         socket.destroy()
         return
@@ -223,7 +236,16 @@ export function makeRemoteApiUpgradeRoutes(deps: RemoteApiDeps): WebUpgradeRoute
       socket.destroy()
       return
     }
-    proxyLoopbackUpgrade(req, socket, head, port, inner)
+    // The inner handshake needs the browser-auth credential (the gateway
+    // event-stream route enforces it); resolving it is async, so the
+    // handshake bytes are written once it settles. A missing credential
+    // proceeds as before — the gateway route then refuses.
+    void Promise.resolve(deps.auth?.ready())
+      .catch(() => undefined)
+      .then((cookie) => {
+        if (socket.destroyed) return
+        proxyLoopbackUpgrade(req, socket, head, port, inner, typeof cookie === 'string' ? cookie : undefined)
+      })
   }
 
   return REMOTE_UPGRADE_PATHS.map((path) => ({

package/src/remote-channel-boot.ts

@@ -10,8 +10,15 @@
  * (hooks + pending unpaired signal) instead of patching twice.
  *
  * The rewrite decisions are generated from REMOTE_CHANNEL_RULES, the same
- * data the browser patch consumes — the two cannot drift apart. The script
- * self-skips on loopback origins and never throws.
+ * data the browser patch consumes — the two cannot drift apart. On this
+ * 0.1.2-alpha.2 line the "configuration plane is local" behavior lives in
+ * the browser (client plugins branch on connection.isLoopback), so the
+ * script also flips the official UI into host mode by installing the
+ * transport hook `__DSH_TRANSPORT__ = { ownsHost: true }` before the
+ * connection plugin reads it: the paired remote desktop gets the full
+ * settings/credentials/presets surface, and every call still rides the
+ * gated /remote channel. The script self-skips on loopback origins and
+ * never throws.
  * @module @linxin666/dsh-remote-web-ui/remote-channel-boot
  */
 
@@ -32,7 +39,23 @@ export function buildRemoteChannelBootScript(rules: RemoteChannelRules = REMOTE_
     'var w=window,loc=w.location,h=loc.hostname;' +
     // Loopback origins keep the original paths (mirrors isLoopbackHostname).
     "if(h==='localhost'||h==='::1'||/^127(\\.\\d{1,3}){3}$/.test(h))return;" +
+    // Host mode: the paired remote desktop presents itself as the machine
+    // owner, so the official UI keeps its full configuration surface (the
+    // settings mirror, document controller, and deliverables open actions
+    // all branch on connection.isLoopback). Must run before any boot entry.
+    'try{if(w.__DSH_TRANSPORT__===undefined)w.__DSH_TRANSPORT__={};w.__DSH_TRANSPORT__.ownsHost=true}catch(e){}' +
     'var R=' + json + ';' +
+    // The cookieless device credential: read lazily per call - the
+    // /pair-app capture script sets it in head AFTER this boot script ran,
+    // so a parse-time read would always see null.
+    'function rdv(){try{return w.sessionStorage.getItem(R.deviceKey)}catch(e){return null}}' +
+    'function att(init){' +
+    'var dv=rdv();' +
+    'if(dv===null)return init;' +
+    'var h=init&&init.headers;' +
+    'if(typeof Headers!=="undefined"&&h instanceof Headers){try{h.set(R.deviceHeader,dv)}catch(e){}return init}' +
+    'if(typeof h==="object"&&h!==null){var o={};for(var k in h)o[k]=h[k];o[R.deviceHeader]=dv;return Object.assign({},init,{headers:o})}' +
+    'return init}' +
     'function sf(p){' +
     'if(p.indexOf(R.pairPrefix)===0)return false;' +
     'if(p.indexOf(R.updatePrefix)===0)return false;' +
@@ -80,7 +103,7 @@ export function buildRemoteChannelBootScript(rules: RemoteChannelRules = REMOTE_
     'var next=new URL(url);' +
     'next.pathname=rp(url.pathname);' +
     'var target=typeof input==="string"||input instanceof URL?next.toString():new Request(next,input);' +
-    'return Promise.resolve(of.call(w,target,init)).then(function(res){' +
+    'return Promise.resolve(of.call(w,target,att(init))).then(function(res){' +
     // denied() is sync-false for non-403 and a promise otherwise.
     'void Promise.resolve(denied(res)).then(signal);' +
     'return res})}' +
@@ -92,6 +115,8 @@ export function buildRemoteChannelBootScript(rules: RemoteChannelRules = REMOTE_
     'if(o!==""&&o===loc.origin&&sw(p.pathname)){' +
     'var nx=new URL(p);' +
     'nx.pathname=rp(p.pathname);' +
+    'var dvv=rdv();' +
+    'if(dvv!==null)nx.searchParams.set(R.deviceQuery,dvv);' +
     'return protocols!==undefined?new OW(nx,protocols):new OW(nx)}' +
     'return protocols!==undefined?new OW(url,protocols):new OW(url)};' +
     'w.WebSocket.prototype=OW.prototype;' +
@@ -103,6 +128,8 @@ export function buildRemoteChannelBootScript(rules: RemoteChannelRules = REMOTE_
     'if(so(p)&&sf(p.pathname)){' +
     'var nx=new URL(p);' +
     'nx.pathname=rp(p.pathname);' +
+    'var dvv=rdv();' +
+    'if(dvv!==null)nx.searchParams.set(R.deviceQuery,dvv);' +
     'return new OE(nx,cfg)}' +
     'return new OE(url,cfg)};' +
     'w.EventSource.prototype=OE.prototype}' +
@@ -123,9 +150,49 @@ export function buildRemoteChannelBootScript(rules: RemoteChannelRules = REMOTE_
     'for(var i=0;i<restores.length;i++)restores[i]();' +
     'try{delete w[' + seat + ']}catch(e){w[' + seat + ']=undefined}};' +
     'w[' + seat + ']=seat' +
+    // The boot watchdog rides the same IIFE and skip conditions: it needs
+    // the non-loopback gate above (the desktop boots over loopback without
+    // a tunnel in the path) and the try/catch fail-closed envelope.
+    buildBootWatchdogScript() +
     '}catch(e){}' +
     '})();'
 }
 
+/** Boot-watchdog latch: one self-reload per session while the boot is broken. */
+export const BOOT_WATCHDOG_KEY = 'dsh-remote-boot-reload'
+
+/** Total wait for the app's first conversation surface before the reload. */
+const BOOT_WATCHDOG_WAIT_MS = 15_000
+
+/** Watchdog poll cadence. */
+const BOOT_WATCHDOG_POLL_MS = 1_000
+
+/**
+ * Build the boot-watchdog script fragment. A remote boot has no recovery
+ * path of its own: the SPA mounts nothing when a boot-critical request dies
+ * (a tunnel-edge 429 under burst, a dropped stream, a boot-order race), and
+ * the phone then shows a permanently blank shell. The watchdog polls for the
+ * app's conversation surface and reloads once when it never appears; the
+ * sessionStorage latch keeps a genuinely broken deployment from looping,
+ * and a successful boot clears the latch so a later failure can recover.
+ */
+export function buildBootWatchdogScript(waitMs = BOOT_WATCHDOG_WAIT_MS, pollMs = BOOT_WATCHDOG_POLL_MS): string {
+  const key = JSON.stringify(BOOT_WATCHDOG_KEY)
+  return (
+    // Leading semicolon: the preceding seat assignment ends without one,
+    // and the fragment must parse when spliced into the IIFE.
+    ';function wBoot(){try{return !!(w.document&&w.document.querySelector&&(w.document.querySelector("[data-conversation-scroll]")||w.document.querySelector("[data-slot=\\"conversation\\"]")))}catch(e){return false}}' +
+    'function wTick(n){try{' +
+    'if(wBoot()){try{w.sessionStorage.removeItem(' + key + ')}catch(e){}return}' +
+    'if(n<' + waitMs + '){w.setTimeout(function(){wTick(n+' + pollMs + ')},' + pollMs + ');return}' +
+    'var done=false;try{done=w.sessionStorage.getItem(' + key + ')==="1"}catch(e){}' +
+    'if(done)return;' +
+    'try{w.sessionStorage.setItem(' + key + ',"1")}catch(e){}' +
+    'w.location.reload()' +
+    '}catch(e){}}' +
+    'if(typeof w.setTimeout==="function")w.setTimeout(function(){wTick(0)},' + pollMs + ');'
+  )
+}
+
 /** The script this plugin contributes; built once from the live rules. */
 export const REMOTE_CHANNEL_BOOT_SCRIPT: string = buildRemoteChannelBootScript()

package/src/remote-channel-rules.ts

@@ -9,6 +9,10 @@
 /** The gated mirror prefix (must match src/remote-methods.ts). */
 export const REMOTE_PREFIX = '/remote'
 
+import { REMOTE_DEVICE_HEADER, REMOTE_DEVICE_QUERY } from './remote-methods.ts'
+
+export { REMOTE_DEVICE_HEADER, REMOTE_DEVICE_QUERY }
+
 /** Connection-plugin method prefix under the gated channel. */
 export const REMOTE_API_PREFIX = `${REMOTE_PREFIX}/api`
 
@@ -24,6 +28,12 @@ export interface RemoteChannelRules {
   readonly gitPrefix: string
   readonly petPrefix: string
   readonly wsPaths: readonly string[]
+  /** Header carrying the cookieless device credential on gated fetches. */
+  readonly deviceHeader: string
+  /** sessionStorage key holding the device credential (set by /pair-app). */
+  readonly deviceKey: string
+  /** Query parameter carrying it on WebSocket upgrades. */
+  readonly deviceQuery: string
 }
 
 /** The live rule set. */
@@ -37,13 +47,18 @@ export const REMOTE_CHANNEL_RULES: RemoteChannelRules = {
   sidebarPrefix: '/sidebar/',
   gitPrefix: '/git/',
   petPrefix: '/pet/',
+  // The official 0.1.2-alpha.2 line opens exactly one stream socket (the
+  // Typert gateway mux, /api/remote.mux); the legacy /api/events.* paths
+  // were removed by the SDK and stay absent here.
   wsPaths: [
-    '/api/events.mux',
-    '/api/events.host',
+    '/api/remote.mux',
     '/sidebar/ws/terminal',
     '/sidebar/ws/agent-terminals',
     '/api/dsh-ssh/terminal',
   ],
+  deviceHeader: REMOTE_DEVICE_HEADER,
+  deviceKey: 'dsh-remote-device',
+  deviceQuery: REMOTE_DEVICE_QUERY,
 }
 
 /** The window global the boot patch publishes its seat under. */