@linxin666/dsh-remote-web-ui 0.2.3 → 0.2.5

package/src/pairing.ts

@@ -13,11 +13,14 @@
  *   unknown one (no oracle for validity).
  * - `stop()` revokes every device session and clears the token, so paired
  *   devices are cut off on their next gated request.
+ * - `revoke()` drops one device session; idle sessions older than
+ *   `idleExpireMs` are deleted on sweep, load, and the next gated request.
  */
 
 import { randomBytes } from 'node:crypto'
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
 import { dirname } from 'node:path'
+import type { PostureSnapshot } from './posture.ts'
 
 /** The observable pairing phases the panel renders. */
 export type PairingPhase =
@@ -48,12 +51,34 @@ 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
+
+/** Cap on the persisted/displayed User-Agent string. */
+const MAX_USER_AGENT_CHARS = 180
+
 /** One paired device session, keyed by the device id stored in its cookie. */
 export interface DeviceSession {
   /** Pairing time (ms epoch). */
   createdAt: number
   /** Last time the device passed a gated request or heartbeat. */
   lastSeenAt: number
+  /** Sanitized User-Agent captured at accept (optional; missing on old files). */
+  userAgent?: string
+}
+
+/** One device row in a loopback snapshot (ids are session credentials). */
+export interface DeviceSnapshot {
+  /** Cookie value / session credential of this device. */
+  id: string
+  /** Pairing time (ms epoch). */
+  createdAt: number
+  /** Last heartbeat or gated request (ms epoch). */
+  lastSeenAt: number
+  /** Whether lastSeenAt is within the offline window. */
+  online: boolean
+  /** Sanitized User-Agent captured at accept, when known. */
+  userAgent?: string
 }
 
 /** One tunnel status frame (auto-tunnel only; undefined when disabled). */
@@ -77,6 +102,8 @@ export interface PairingSnapshot {
   publicUrl?: string
   /** Auto-tunnel status, while the auto-tunnel feature is active. */
   tunnel?: TunnelStatus
+  /** Latest /api posture probe (undefined until the first round completes). */
+  posture?: PostureSnapshot
   /** Opaque (non-secret) id of the active token (undefined when stopped/lan-required). */
   tokenId?: string
   /** Absolute expiry of the active token. */
@@ -85,6 +112,8 @@ export interface PairingSnapshot {
   deviceCount: number
   /** Count of devices active within the offline window. */
   onlineCount: number
+  /** Per-device roster for the loopback panel (never sent on /api/pair/status). */
+  devices: DeviceSnapshot[]
 }
 
 /** Service tunables (config-validated upstream; plain numbers here). */
@@ -97,11 +126,16 @@ export interface PairingConfig {
   maxDevices: number
   /** Cookie name carrying the device id. */
   cookieName: string
+  /**
+   * Idle sessions older than this are deleted (memory and disk). Defaults
+   * to {@link DEFAULT_IDLE_EXPIRE_MS} when omitted.
+   */
+  idleExpireMs?: number
   /**
    * Path to a JSON file where paired device sessions are persisted. When
    * set, sessions survive process restarts (the phone keeps its 365-day
    * cookie), so re-pairing after a dsh web restart is not required. When
-   * unset (default), sessions stay memory-only — the previous behavior.
+   * unset, sessions stay memory-only.
    */
   devicesFile?: string
 }
@@ -153,6 +187,9 @@ export class PairingService {
   private publicBase: string | undefined
   /** Auto-tunnel status, while the auto-tunnel feature is active. */
   private tunnelStatus: TunnelStatus | undefined
+  private posture: PostureSnapshot | undefined
+  /** True when lastSeenAt changed since the last persist (flushed on sweep). */
+  private dirty = false
 
   /**
    * @param config - tunables. The settings surface replaces the object (a
@@ -181,11 +218,21 @@ export class PairingService {
       for (const [deviceId, session] of Object.entries(saved)) {
         if (typeof deviceId !== 'string') continue
         if (typeof session !== 'object' || session === null) continue
-        const { createdAt, lastSeenAt } = session as { createdAt?: unknown; lastSeenAt?: unknown }
+        const { createdAt, lastSeenAt, userAgent } = session as {
+          createdAt?: unknown
+          lastSeenAt?: unknown
+          userAgent?: unknown
+        }
         if (typeof createdAt !== 'number' || typeof lastSeenAt !== 'number') continue
-        this.devices.set(deviceId, { createdAt, lastSeenAt })
+        const label = typeof userAgent === 'string' ? sanitizeUserAgent(userAgent) : undefined
+        this.devices.set(deviceId, {
+          createdAt,
+          lastSeenAt,
+          ...(label !== undefined ? { userAgent: label } : {}),
+        })
       }
       this.clampToMaxDevices()
+      if (this.evictIdle()) this.persist()
     } catch {
       // Unreadable/corrupt: start empty rather than refusing to boot.
     }
@@ -199,12 +246,25 @@ export class PairingService {
     for (const [id] of ordered.slice(0, overflow)) this.devices.delete(id)
   }
 
+  /** Drop sessions whose lastSeenAt is older than idleExpireMs. */
+  private evictIdle(): boolean {
+    const now = this.clock.now()
+    const limit = this.config.idleExpireMs ?? DEFAULT_IDLE_EXPIRE_MS
+    let removed = false
+    for (const [id, session] of [...this.devices]) {
+      if (now - session.lastSeenAt > limit) {
+        this.devices.delete(id)
+        removed = true
+      }
+    }
+    return removed
+  }
+
   /**
    * Write the current device table to the configured file. Called on the
-   * mutation boundaries that change the set of live sessions (accept and
-   * stop); `lastSeenAt` refreshes are deliberately not persisted here so a
-   * per-request write storm is avoided — after a restart the phone's first
-   * heartbeat re-warms its own session.
+   * mutation boundaries that change the set of live sessions (accept, stop,
+   * revoke, idle eviction) and, throttled, from sweep() so lastSeenAt
+   * survives a restart without a write per request.
    *
    * Device ids are session credentials (the gate authorizes requests by the
    * cookie's device id), so the file is written 0600 via a temp file and
@@ -216,8 +276,11 @@ export class PairingService {
     try {
       mkdirSync(dirname(file), { recursive: true })
       const temp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`
-      writeFileSync(temp, JSON.stringify(Object.fromEntries(this.devices)), { mode: 0o600 })
+      const payload: Record<string, DeviceSession> = {}
+      for (const [id, session] of this.devices) payload[id] = session
+      writeFileSync(temp, JSON.stringify(payload), { mode: 0o600 })
       renameSync(temp, file)
+      this.dirty = false
     } catch (error) {
       console.error('remote-web-ui: failed to persist paired devices', error)
     }
@@ -261,6 +324,12 @@ export class PairingService {
     this.notify()
   }
 
+  /** Set the latest /api posture probe result (see posture.ts). */
+  setPosture(snapshot: PostureSnapshot | undefined): void {
+    this.posture = snapshot
+    this.notify()
+  }
+
   /**
    * Issue a fresh token, replacing (invalidating) any previous one. A
    * stopped service re-arms through this call (the panel's refresh button).
@@ -302,9 +371,10 @@ export class PairingService {
    * successful call for the same token is impossible because the first
    * consumes it.
    * @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): AcceptResult {
+  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' }
@@ -320,7 +390,12 @@ export class PairingService {
       }
       if (oldest !== undefined) this.devices.delete(oldest.id)
     }
-    this.devices.set(deviceId, { createdAt: now, lastSeenAt: now })
+    const label = sanitizeUserAgent(userAgent)
+    this.devices.set(deviceId, {
+      createdAt: now,
+      lastSeenAt: now,
+      ...(label !== undefined ? { userAgent: label } : {}),
+    })
     this.persist()
     this.notify()
     return { ok: true, deviceId }
@@ -339,17 +414,32 @@ export class PairingService {
     this.notify()
   }
 
+  /**
+   * Revoke one paired device. The next gated request from that cookie is
+   * refused; other sessions stay live. Unknown ids are a no-op.
+   * @param deviceId - the cookie value of the device to drop.
+   * @returns true when a live session was removed.
+   */
+  revoke(deviceId: string): boolean {
+    if (this.stopped) return false
+    if (!this.devices.delete(deviceId)) return false
+    this.persist()
+    this.notify()
+    return true
+  }
+
   /**
    * The api/gate path: record activity for a device id and report whether
    * the request may proceed. Unknown or revoked ids (including any device
-   * after stop()) are refused.
+   * after stop() or idle expiry) are refused.
    * @param deviceId - the cookie value of the requesting device.
    * @returns true when the device session is live and was refreshed.
    */
   touchDevice(deviceId: string): boolean {
-    const session = this.devices.get(deviceId)
-    if (session === undefined || this.stopped) return false
+    const session = this.liveSession(deviceId)
+    if (session === undefined) return false
     session.lastSeenAt = this.clock.now()
+    this.dirty = true
     this.notify()
     return true
   }
@@ -360,18 +450,24 @@ export class PairingService {
   }
 
   /**
-   * Periodic sweep: re-evaluate the derived snapshot (a device aging past
-   * the offline window flips the phase to disconnected). Emits only when
-   * the snapshot actually changed.
+   * Periodic sweep: drop idle sessions, flush a dirty lastSeenAt, and
+   * re-evaluate the derived snapshot (a device aging past the offline
+   * window flips the phase to disconnected). Emits only when the snapshot
+   * actually changed.
    */
   sweep(): void {
+    const evicted = this.evictIdle()
+    if (evicted || this.dirty) this.persist()
     this.notify()
   }
 
   /** The current snapshot (fresh object per call — stable between emits). */
   snapshot(): PairingSnapshot {
     const now = this.clock.now()
-    const onlineCount = [...this.devices.values()].filter(session => this.isOnlineAt(session, now)).length
+    const devices = [...this.devices.entries()]
+      .sort((a, b) => a[1].createdAt - b[1].createdAt)
+      .map(([id, session]) => this.toDeviceSnapshot(id, session, now))
+    const onlineCount = devices.filter(device => device.online).length
     const token = this.activeToken()
     return {
       phase: this.derivePhase(onlineCount, token !== undefined),
@@ -379,16 +475,17 @@ export class PairingService {
       lanAddresses: [...this.lanBases.keys()],
       ...(this.publicBase !== undefined ? { publicUrl: this.publicBase } : {}),
       ...(this.tunnelStatus !== undefined ? { tunnel: this.tunnelStatus } : {}),
+      ...(this.posture !== undefined ? { posture: this.posture } : {}),
       ...(token !== undefined ? { tokenId: token.record.id, tokenExpiresAt: token.record.expiresAt } : {}),
       deviceCount: this.devices.size,
       onlineCount,
+      devices,
     }
   }
 
-  /** Whether a cookie value names a currently live device session. */
+  /** Whether a cookie value names a currently live (non-idle) device session. */
   hasDevice(deviceId: string): boolean {
-    const session = this.devices.get(deviceId)
-    return session !== undefined && !this.stopped
+    return this.liveSession(deviceId) !== undefined
   }
 
   /** Subscribe to snapshot changes (each emit passes a fresh snapshot). */
@@ -406,6 +503,34 @@ export class PairingService {
     return undefined
   }
 
+  /**
+   * Return a live session, deleting it first when idle-expired. Side-effecting
+   * so a stale cookie cannot pass the gate between sweeps.
+   */
+  private liveSession(deviceId: string): DeviceSession | undefined {
+    if (this.stopped) return undefined
+    const session = this.devices.get(deviceId)
+    if (session === undefined) return undefined
+    const limit = this.config.idleExpireMs ?? DEFAULT_IDLE_EXPIRE_MS
+    if (this.clock.now() - session.lastSeenAt > limit) {
+      this.devices.delete(deviceId)
+      this.persist()
+      this.notify()
+      return undefined
+    }
+    return session
+  }
+
+  private toDeviceSnapshot(id: string, session: DeviceSession, now: number): DeviceSnapshot {
+    return {
+      id,
+      createdAt: session.createdAt,
+      lastSeenAt: session.lastSeenAt,
+      online: this.isOnlineAt(session, now),
+      ...(session.userAgent !== undefined ? { userAgent: session.userAgent } : {}),
+    }
+  }
+
   private derivePhase(onlineCount: number, hasToken: boolean): PairingPhase {
     if (this.lanBases.size === 0 && this.publicBase === undefined) return 'lan-required'
     if (this.stopped) return 'stopped'
@@ -445,6 +570,20 @@ function snapshotsEqual(a: PairingSnapshot, b: PairingSnapshot): boolean {
     && a.tokenExpiresAt === b.tokenExpiresAt
     && a.deviceCount === b.deviceCount
     && a.onlineCount === b.onlineCount
+    && devicesEqual(a.devices, b.devices)
+}
+
+/** Per-device roster equality (order is pairing time). */
+function devicesEqual(a: readonly DeviceSnapshot[], b: readonly DeviceSnapshot[]): boolean {
+  return a.length === b.length && a.every((device, index) => {
+    const other = b[index]
+    return other !== undefined
+      && device.id === other.id
+      && device.createdAt === other.createdAt
+      && device.lastSeenAt === other.lastSeenAt
+      && device.online === other.online
+      && device.userAgent === other.userAgent
+  })
 }
 
 /** Tunnel frame equality (undefined equals undefined; fields compared shallowly). */
@@ -457,3 +596,11 @@ function tunnelEqual(a: TunnelStatus | undefined, b: TunnelStatus | undefined):
 function sameStrings(a: readonly string[], b: readonly string[]): boolean {
   return a.length === b.length && a.every((value, index) => value === b[index])
 }
+
+/** 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
+  const cleaned = raw.replace(/[\u0000-\u001F\u007F]/g, ' ').replace(/\s+/g, ' ').trim()
+  if (cleaned === '') return undefined
+  return cleaned.length <= MAX_USER_AGENT_CHARS ? cleaned : cleaned.slice(0, MAX_USER_AGENT_CHARS)
+}

package/src/posture.ts

@@ -0,0 +1,154 @@
+/**
+ * Deployment posture probe: verify that the connection plugin's `/api` fence
+ * actually refuses non-loopback requests for every origin this deployment
+ * advertises (the public tunnel host, the LAN bases). The fence is the SDK's
+ * own Host check — the one seam a plugin cannot mount a gate into — so this
+ * probe is the guardrail that makes a re-opened `/api` (for example a
+ * re-added `--trusted-host`, or the SDK's LAN-literal auto-trust under
+ * `--host 0.0.0.0`) visible instead of silent.
+ *
+ * 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.
+ */
+
+import type { ClientRequest, ClientRequestArgs } from 'node:http'
+import http from 'node:http'
+
+/** One probed origin. */
+export interface PostureHost {
+  /** The forged Host header value that was probed. */
+  host: string
+  /** True when the probe reached past the fence (anything but 403). */
+  exposed: boolean
+}
+
+/** One probe round. */
+export interface PostureSnapshot {
+  /** When the round completed (epoch ms). */
+  checkedAt: number
+  /** Every probed origin and its verdict. */
+  hosts: PostureHost[]
+}
+
+/** Whether any probed origin is currently exposed. */
+export function anyExposed(snapshot: PostureSnapshot): boolean {
+  return snapshot.hosts.some(host => host.exposed)
+}
+
+/**
+ * Build the forged Host values to probe: the public base authority (host or
+ * host:port as written in the URL) plus every LAN base literal.
+ * @param publicBaseUrl - the configured public base URL (or undefined).
+ * @param lanAddresses - the LAN interface addresses the QR advertises.
+ * @param port - the local webServer port (LAN hosts are probed as host:port).
+ * @returns Host header values, de-duplicated.
+ */
+export function postureTargets(publicBaseUrl: string | undefined, lanAddresses: string[], port: number): string[] {
+  const targets: string[] = []
+  if (publicBaseUrl !== undefined) {
+    try {
+      const url = new URL(publicBaseUrl)
+      const authority = url.port === '' ? url.hostname : `${url.hostname}:${url.port}`
+      if (authority !== '') targets.push(authority)
+    } catch {
+      // A malformed base is ignored elsewhere with a warning; nothing to probe.
+    }
+  }
+  for (const address of lanAddresses) {
+    targets.push(`${address}:${String(port)}`)
+  }
+  return [...new Set(targets)]
+}
+
+/** Injectable transport seam (defaults to node:http). */
+export type ProbeRequest = (options: ClientRequestArgs, onStatus: (status: number) => void) => ClientRequest
+
+const defaultRequest: ProbeRequest = (options, onStatus) => {
+  const request = http.request(options, response => { onStatus(response.statusCode ?? 0) })
+  request.on('error', () => { onStatus(0) })
+  return request
+}
+
+/**
+ * Probe one forged Host against the local `/api` fence.
+ * @param port - the local webServer port.
+ * @param hostHeader - the Host header to forge.
+ * @param request - transport seam.
+ * @param timeoutMs - give up after this long (counts as not exposed; the
+ * fence being unreachable is not evidence it is open).
+ * @returns true when the probe got past the fence.
+ */
+async function probeHost(port: number, hostHeader: string, request: ProbeRequest, timeoutMs: number): Promise<boolean> {
+  return await new Promise<boolean>(resolve => {
+    let settled = false
+    const finish = (exposed: boolean): void => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      handle.destroy()
+      resolve(exposed)
+    }
+    const handle = request({
+      host: '127.0.0.1',
+      port,
+      method: 'POST',
+      path: '/api/session.list',
+      headers: { host: hostHeader, 'content-type': 'application/json' },
+      timeout: timeoutMs,
+    }, status => { finish(status !== 403) })
+    const timer = setTimeout(() => { finish(false) }, timeoutMs + 1_000)
+    handle.on('error', () => { finish(false) })
+    handle.end('{}')
+  })
+}
+
+/** Probe options. */
+export interface ProbePostureOptions {
+  /** The local webServer port. */
+  port: number
+  /** Forged Host header values (see {@link postureTargets}). */
+  targets: string[]
+  /** Transport seam (defaults to node:http). */
+  request?: ProbeRequest
+  /** Per-host timeout (default 3000 ms). */
+  timeoutMs?: number
+  /** Clock seam (default Date.now). */
+  now?: () => number
+}
+
+/**
+ * Run one posture probe round.
+ * @returns the snapshot for this round.
+ */
+export async function probePosture(options: ProbePostureOptions): Promise<PostureSnapshot> {
+  const { port, targets } = options
+  const request = options.request ?? defaultRequest
+  const timeoutMs = options.timeoutMs ?? 3_000
+  const now = options.now ?? ((): number => Date.now())
+  const hosts: PostureHost[] = []
+  for (const target of targets) {
+    // Sequential on purpose: one slow host must not multiply the round's latency.
+    hosts.push({ host: target, exposed: await probeHost(port, target, request, timeoutMs) })
+  }
+  return { checkedAt: now(), hosts }
+}
+
+/**
+ * Reserve an advertised-target key so a second trigger with the same set
+ * does not overlap an in-flight round. Pair with {@link releasePostureKey}
+ * on failure — otherwise that key never retries.
+ */
+export function claimPostureKey(current: string | undefined, key: string): { run: boolean; next: string } {
+  if (current === key) return { run: false, next: current }
+  return { run: true, next: key }
+}
+
+/**
+ * Drop a failed in-flight key so the next trigger re-probes the same targets.
+ * A newer key that started meanwhile is left alone.
+ */
+export function releasePostureKey(current: string | undefined, attempted: string): string | undefined {
+  return current === attempted ? undefined : current
+}