@linxin666/dsh-remote-web-ui 0.3.23 → 0.4.0

package/src/pairing.ts

@@ -7,9 +7,9 @@
  * Security invariants:
  * - One active token at a time; `issue()` replaces it, so a refreshed QR
  *   immediately invalidates the previous link.
- * - 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).
+ * - A token is a bearer credential for its whole window: it is refused only
+ *   when unknown, expired, or after `stop()`, and the same link may pair
+ *   repeatedly within that window (each 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.
@@ -22,7 +22,7 @@
  */
 
 import { randomBytes } from 'node:crypto'
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname } from 'node:path'
 import type { PostureSnapshot } from './posture.ts'
 
@@ -45,8 +45,6 @@ export interface TokenRecord {
   issuedAt: number
   /** Absolute expiry (ms epoch); accept() past this is refused. */
   expiresAt: number
-  /** Consumed by the first successful accept(). */
-  consumed: boolean
   /** Opaque, non-secret identifier surfaced in snapshots (never the pairing secret). */
   id: string
   /** Workspace the QR link should land the phone in (optional). */
@@ -167,10 +165,14 @@ export interface PairingConfig {
   devicesFile?: string
 }
 
-/** Result of one accept() attempt. */
+/**
+ * Result of one accept() attempt. A token is a bearer credential for its whole
+ * window (see the module doc), so the only refusal is `invalid`: unknown,
+ * expired, or after stop(). There is no "already used" outcome.
+ */
 export type AcceptResult =
   | { ok: true; deviceId: string }
-  | { ok: false; code: 'invalid' | 'used' }
+  | { ok: false; code: 'invalid' }
 
 /** Thrown by issue() for an address outside the sampled LAN literals. */
 export class UnknownLanAddressError extends Error {
@@ -189,6 +191,12 @@ export interface PairingClock {
   randomToken(): string
 }
 
+/** File-operation seam for the revocation-durability step (tests). */
+export interface PairingFsSeams {
+  /** Remove the stale device store (defaults to fs.rmSync with force). */
+  removeFile?(path: string): void
+}
+
 /** Real clock/entropy: 32 random hex chars per token. */
 export const defaultClock: PairingClock = {
   now: () => Date.now(),
@@ -231,6 +239,7 @@ export class PairingService {
   constructor(
     public config: PairingConfig,
     private readonly clock: PairingClock = defaultClock,
+    private readonly fs: PairingFsSeams = {},
   ) {
     this.loadPersisted()
   }
@@ -263,7 +272,7 @@ export class PairingService {
         })
       }
       this.clampToMaxDevices()
-      if (this.evictIdle()) this.persist()
+      if (this.evictIdle()) this.persistRevocation()
     } catch {
       // Unreadable/corrupt: start empty rather than refusing to boot.
     }
@@ -301,9 +310,9 @@ export class PairingService {
    * cookie's device id), so the file is written 0600 via a temp file and
    * atomic rename; a crash mid-write can never leave a half-written store.
    */
-  private persist(): void {
+  private persist(): boolean {
     const file = this.config.devicesFile
-    if (file === undefined) return
+    if (file === undefined) return true
     try {
       mkdirSync(dirname(file), { recursive: true })
       const temp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`
@@ -312,8 +321,32 @@ export class PairingService {
       writeFileSync(temp, JSON.stringify(payload), { mode: 0o600 })
       renameSync(temp, file)
       this.dirty = false
+      return true
     } catch (error) {
       console.error('remote-web-ui: failed to persist paired devices', error)
+      return false
+    }
+  }
+
+  /**
+   * Persist a table change that REVOKES access (stop, per-device revoke, idle
+   * eviction). A failed write would leave the revoked session on disk, and
+   * {@link loadPersisted} restores that file verbatim on the next start — the
+   * device's still-valid cookie would authorize again after an explicit
+   * revocation. When the write cannot be made durable, the stale store is
+   * removed instead (a missing file already loads as an empty table), so the
+   * failure costs a re-pair rather than silently undoing the revocation.
+   */
+  private persistRevocation(): void {
+    if (this.persist()) return
+    const file = this.config.devicesFile
+    if (file === undefined) return
+    try {
+      if (this.fs.removeFile !== undefined) this.fs.removeFile(file)
+      else rmSync(file, { force: true })
+      console.error('remote-web-ui: the device revocation could not be persisted; removed the stale device store so a restart cannot restore it')
+    } catch (error) {
+      console.error('remote-web-ui: the device revocation could not be persisted and the stale device store could not be removed', error)
     }
   }
 
@@ -343,9 +376,14 @@ export class PairingService {
     return this.publicBase
   }
 
-  /** Set or clear the public base URL (a tunnel in front of this server). */
+  /**
+   * Set or clear the public base URL (a tunnel in front of this server). The
+   * value is canonicalized to its origin: a trailing slash (what a browser
+   * address-bar copy produces) or a path would mint a dead `//pair-accept`
+   * link, which WHATWG resolves as an authority rather than a path.
+   */
   setPublicBaseUrl(url: string | undefined): void {
-    this.publicBase = url
+    this.publicBase = url === undefined ? undefined : canonicalBaseUrl(url)
     this.notify()
   }
 
@@ -395,7 +433,6 @@ export class PairingService {
       id: `t${this.tokenSerial}`,
       issuedAt: now,
       expiresAt: now + this.config.tokenTtlMs,
-      consumed: false,
       ...(workspaceId !== undefined ? { workspaceId } : {}),
       ...(address !== undefined ? { address } : {}),
     })
@@ -404,21 +441,20 @@ export class PairingService {
   }
 
   /**
-   * Consume a token and bind a device session. One-time: the second
-   * successful call for the same token is impossible because the first
-   * consumes it.
+   * Redeem a token and bind a device session. The token is a bearer
+   * credential for its whole window, not a single-use nonce: it is refused
+   * only when unknown, past its expiry, or after stop(), and every successful
+   * call — including a repeat within the same window — mints a fresh device
+   * session (see the module doc for the mobile cookie-context rationale).
    * @param token - the token secret from the QR link.
    * @param userAgent - optional User-Agent header captured at accept.
    * @returns the new device id, or a refusal code.
    */
   accept(token: string, userAgent?: string): AcceptResult {
     const record = this.tokens.get(token)
-    // 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()
     const now = this.clock.now()
     if (this.devices.size >= this.config.maxDevices) {
@@ -448,7 +484,7 @@ export class PairingService {
   stop(): void {
     this.tokens.clear()
     this.devices.clear()
-    this.persist()
+    this.persistRevocation()
     this.stopped = true
     this.notify()
   }
@@ -462,7 +498,7 @@ export class PairingService {
   revoke(deviceId: string): boolean {
     if (this.stopped) return false
     if (!this.devices.delete(deviceId)) return false
-    this.persist()
+    this.persistRevocation()
     this.notify()
     return true
   }
@@ -501,7 +537,8 @@ export class PairingService {
    */
   sweep(): void {
     const evicted = this.evictIdle()
-    if (evicted || this.dirty) this.persist()
+    if (evicted) this.persistRevocation()
+    else if (this.dirty) this.persist()
     this.notify()
   }
 
@@ -559,7 +596,7 @@ export class PairingService {
     const limit = this.config.idleExpireMs ?? DEFAULT_IDLE_EXPIRE_MS
     if (this.clock.now() - session.lastSeenAt > limit) {
       this.devices.delete(deviceId)
-      this.persist()
+      this.persistRevocation()
       this.notify()
       return undefined
     }
@@ -649,6 +686,20 @@ function sameStrings(a: readonly string[], b: readonly string[]): boolean {
   return a.length === b.length && a.every((value, index) => value === b[index])
 }
 
+/**
+ * Canonical origin of a public base URL. An unparsable value is returned
+ * verbatim so the caller's malformed-base warning stays the single owner of
+ * that case.
+ * @param url - the configured public base.
+ */
+export function canonicalBaseUrl(url: string): string {
+  try {
+    return new URL(url).origin
+  } catch {
+    return url
+  }
+}
+
 /** Strip control characters and cap the User-Agent stored with a session. */
 export function sanitizeUserAgent(raw: string | undefined): string | undefined {
   if (raw === undefined) return undefined

package/src/posture.ts

@@ -9,8 +9,13 @@
  *
  * The probe issues loopback requests with a forged Host header — the exact
  * shape a tunnel or LAN client produces — and treats anything other than a
- * 403 as exposed: the fence is documented to refuse with 403, so any other
- * status means the request reached the RPC bridge.
+ * 403 or a 401 as exposed. The fence is documented to refuse with 403; the
+ * harness answers 401 when the Host fence PASSED but the browser-auth cookie
+ * is missing (the connection plugin checks the fence first and the cookie
+ * second). A 401 therefore means the /api surface is still gated — reporting
+ * it as open produced a false CRITICAL on exactly the supported LAN
+ * deployment (0.0.0.0 bind auto-trusts the LAN literals) and desensitized the
+ * one alarm that should mean a real exposure.
  */
 
 import type { ClientRequest, ClientRequestArgs } from 'node:http'
@@ -20,7 +25,10 @@ import http from 'node:http'
 export interface PostureHost {
   /** The forged Host header value that was probed. */
   host: string
-  /** True when the probe reached past the fence (anything but 403). */
+  /**
+   * True when the probe reached the RPC bridge without any gate refusing it
+   * (a status that is neither the fence's 403 nor the browser-auth 401).
+   */
   exposed: boolean
 }
 
@@ -97,7 +105,7 @@ async function probeHost(port: number, hostHeader: string, request: ProbeRequest
       path: '/api/session.list',
       headers: { host: hostHeader, 'content-type': 'application/json' },
       timeout: timeoutMs,
-    }, status => { finish(status !== 403) })
+    }, status => { finish(status !== 403 && status !== 401) })
     const timer = setTimeout(() => { finish(false) }, timeoutMs + 1_000)
     handle.on('error', () => { finish(false) })
     handle.end('{}')

package/src/remote-api.ts

@@ -7,10 +7,14 @@
  * 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 local-only denials below still apply).
+ * - Every request must carry a live paired-device credential, enforced before
+ *   any bytes are forwarded and before any host call. This gate is
+ *   unconditional and does NOT follow `requirePairingForLan`: the channel
+ *   re-issues traffic with the process's own browser-auth credential, so it is
+ *   an authentication amplifier — an unpaired caller admitted here would reach
+ *   the full host API without ever holding that credential. The LAN policy
+ *   governs the plain `/api` surface only (whether the harness fence's LAN
+ *   auto-trust stands on its own); it can never widen this channel.
  * - 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)
@@ -69,15 +73,8 @@ function isSafeSegment(segment: string): boolean {
 export interface RemoteApiDeps {
   /** The pairing service (device gate + cookie name). */
   service: PairingService
-  /** The local webServer port the loopback proxy connects to. */
+  /** Local webServer port the loopback proxy connects to. */
   port: number
-  /**
-   * Live policy: whether the paired-device cookie gates the /remote channel.
-   * When false, requests are proxied without a cookie (the loopback-only
-   * denials still apply). A function is re-read per request, so a settings
-   * 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
@@ -139,24 +136,22 @@ export function pairedDeviceIdOf(req: IncomingMessage, service: PairingService):
 
 /**
  * Build the remote desktop channel HTTP routes.
- * @param deps - pairing service + local port + live pairing policy.
+ * @param deps - pairing service + local port + inner credential.
  * @returns the routes to register on webServer.
  */
 export function makeRemoteApiRoutes(deps: RemoteApiDeps): WebRoute[] {
-  const { service, port, requirePairingForLan = true } = deps
+  const { service, port } = deps
 
   const handler = (req: IncomingMessage, res: ServerResponse): void => {
-    // Cookie gate first — same order as /m/api. Do not buffer an unpaired body.
-    // With the live policy off, untrusted-but-policy-open callers are proxied
-    // (a stale client rewrite must not 403); loopback-only denials stay below.
-    const require = typeof requirePairingForLan === 'function' ? requirePairingForLan() : requirePairingForLan
-    if (require) {
-      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
-      }
+    // Paired credential first — before any bytes are buffered or forwarded.
+    // Unconditional by design: this channel attaches the process's own
+    // browser-auth cookie to every re-issued call, so admitting an unpaired
+    // caller would hand out that credential's authority (issue #1665).
+    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
     }
 
     const method = req.method ?? 'GET'
@@ -209,24 +204,22 @@ export function upgradeInnerPath(reqUrl: string | undefined, fallbackPath: strin
  * @returns the upgrade routes to register on webServer.
  */
 export function makeRemoteApiUpgradeRoutes(deps: RemoteApiDeps): WebUpgradeRoute[] {
-  const { service, port, requirePairingForLan = true } = deps
+  const { service, port } = deps
 
   const handlerFor = (fallbackPath: string) => (req: IncomingMessage, socket: Duplex, head: Buffer): void => {
-    const require = typeof requirePairingForLan === 'function' ? requirePairingForLan() : requirePairingForLan
-    if (require) {
-      // 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
-      }
+    // WebSocket handshakes cannot carry headers from the Web API, so the
+    // cookieless credential rides the query; the cookie stays the primary.
+    // The gate is unconditional here too (issue #1665).
+    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
     }
     const inner = upgradeInnerPath(req.url, fallbackPath)
     const denied = loopbackOnlyDenial(inner.split('?')[0] ?? inner)

package/src/remote-channel-boot.ts

@@ -17,7 +17,12 @@
  * 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. It finally publishes the official pre-Cordis
+ * gated /remote channel. Host mode is server-granted, not origin-asserted:
+ * the hook is installed only when the device-gated app landing (/pair-app)
+ * published the grant marker (REMOTE_HOST_GRANT_GLOBAL) ahead of this
+ * script, so a shell served to an unpaired browser - a fence-open
+ * deployment - never presents itself as the machine owner. It finally
+ * publishes the official pre-Cordis
  * upload hook (`__DSH_FILE_UPLOAD__`), because the background upload
  * transport otherwise runs inside a Web Worker whose own globals the
  * main-thread rewrite cannot reach (issue #1580). The script self-skips on
@@ -40,14 +45,17 @@ export function buildRemoteChannelBootScript(rules: RemoteChannelRules = REMOTE_
   return '(function(){' +
     'try{' +
     '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){}' +
+    // Loopback origins (including the bracketed IPv6 literal WHATWG returns)
+    // keep the original paths (mirrors isLoopbackHostname).
+    "if(h==='localhost'||h==='::1'||h==='[::1]'||/^127(\\.\\d{1,3}){3}$/.test(h))return;" +
     'var R=' + json + ';' +
+    // Host mode is server-granted: only the device-gated app landing
+    // publishes the grant marker (in a capture script that runs ahead of
+    // this one), so a shell that merely sits on a non-loopback origin - an
+    // unpaired browser reaching a fence-open deployment - keeps the official
+    // UI's memory-scope presentation instead of posing as the machine owner.
+    // Must run before any boot entry.
+    'try{if(w[R.hostGrantGlobal]===true){if(w.__DSH_TRANSPORT__===undefined)w.__DSH_TRANSPORT__={};w.__DSH_TRANSPORT__.ownsHost=true}}catch(e){}' +
     // 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.

package/src/remote-channel-rules.ts

@@ -16,6 +16,13 @@ export { REMOTE_DEVICE_HEADER, REMOTE_DEVICE_QUERY }
 /** Connection-plugin method prefix under the gated channel. */
 export const REMOTE_API_PREFIX = `${REMOTE_PREFIX}/api`
 
+/**
+ * The window global the device-gated app landing publishes to grant host mode.
+ * Set by the /pair-app capture script, read by the parse-time boot patch: the
+ * transport hook (ownsHost) is server-granted, not asserted from the origin.
+ */
+export const REMOTE_HOST_GRANT_GLOBAL = '__DSH_REMOTE_HOST_GRANT__'
+
 /** Every decision input of the remote-channel rewrite, JSON-serializable. */
 export interface RemoteChannelRules {
   readonly remotePrefix: string
@@ -37,6 +44,14 @@ export interface RemoteChannelRules {
   readonly uploadPath: string
   /** Page global the pre-Cordis upload hook is published under. */
   readonly uploadHookGlobal: string
+  /**
+   * Page global carrying the server-issued host-mode grant. Only the plugin's
+   * own device-gated app landing (/pair-app) publishes it; the boot patch
+   * therefore enables the official UI's host mode only for a shell the server
+   * actually granted, never for one that merely happens to sit on a
+   * non-loopback origin.
+   */
+  readonly hostGrantGlobal: string
 }
 
 /** The live rule set. */
@@ -56,6 +71,7 @@ export const REMOTE_CHANNEL_RULES: RemoteChannelRules = {
     '/api/remote.mux',
     '/sidebar/ws/terminal',
     '/sidebar/ws/agent-terminals',
+    '/sidebar/ws/agent-opens',
     '/api/dsh-ssh/terminal',
   ],
   deviceHeader: REMOTE_DEVICE_HEADER,
@@ -63,6 +79,7 @@ export const REMOTE_CHANNEL_RULES: RemoteChannelRules = {
   deviceQuery: REMOTE_DEVICE_QUERY,
   uploadPath: '/api/session/uploadFileBinary',
   uploadHookGlobal: '__DSH_FILE_UPLOAD__',
+  hostGrantGlobal: REMOTE_HOST_GRANT_GLOBAL,
 }
 
 /** The window global the boot patch publishes its seat under. */

package/src/remote-methods.ts

@@ -39,6 +39,7 @@ export const REMOTE_UPGRADE_PATHS = [
   REMOTE_API_PATHS.mux,
   `${REMOTE_PREFIX}/sidebar/ws/terminal`,
   `${REMOTE_PREFIX}/sidebar/ws/agent-terminals`,
+  `${REMOTE_PREFIX}/sidebar/ws/agent-opens`,
   `${REMOTE_API_PREFIX}/dsh-ssh/terminal`,
 ] as const