dsh-remote-control-plugin 0.0.0-stage → 0.3.1

package/index.js

@@ -0,0 +1,1011 @@
+import { createHmac, randomBytes, randomInt, randomUUID, timingSafeEqual } from 'node:crypto'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { createServer as createHttpServer } from 'node:http'
+import { createServer as createHttpsServer } from 'node:https'
+import { isIP } from 'node:net'
+import os from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createFabric } from './host/fabric.js'
+import { createRelayLink } from './host/relay-link.js'
+import { createRelay } from './host/relay-core.js'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const WEB_DIR = path.join(HERE, 'web')
+const COOKIE_NAME = 'dsh_rc'
+const MAX_BODY_BYTES = 1024 * 1024
+
+const STATIC_FILES = {
+  '/': ['index.html', 'text/html; charset=utf-8'],
+  '/index.html': ['index.html', 'text/html; charset=utf-8'],
+  '/app.js': ['app.js', 'text/javascript; charset=utf-8'],
+  '/app.css': ['app.css', 'text/css; charset=utf-8'],
+  '/icon.svg': ['icon.svg', 'image/svg+xml'],
+}
+
+export const inject = ['sessionController']
+
+/**
+ * Phone-friendly remote control for this Host's Sessions.
+ *
+ * The plugin owns its own listener instead of reusing the loopback web
+ * carrier, so it never depends on the GUI's boot payload, cookies, or the
+ * `/api` bridge. Everything it renders is derived from
+ * `ctx.sessionController` (list / follow / prompt / cancel / create).
+ */
+export function apply(ctx, rawConfig) {
+  const log = pickLogger(ctx)
+  const config = normalizeConfig(rawConfig)
+  const stateFile = path.join(dshHome(), 'remote-control.json')
+  const peersFile = path.join(dshHome(), 'remote-control-peers.json')
+  const streams = new Set()
+  const published = { urls: [], code: '' }
+  const info = { port: config.port, proto: config.tls ? 'https' : 'http' }
+  const identity = { userId: null }
+
+  let server
+  let state
+  let fabric
+  let relayLink
+  let relayCore
+  let hostedKey = ''
+
+  const sessions = {
+    async list() {
+      const value = await ctx.sessionController.list({}, AbortSignal.timeout(15000))
+      return (value?.items ?? [])
+        .filter((item) => item.origin !== 'subagent')
+        .map((item) => {
+          const projections = item.projections?.values ?? {}
+          const title = firstString(projections.title, projections.sessionTitle, projections['session-title'])
+          return {
+            id: item.sessionId,
+            title: title || '',
+            running: Boolean(item.running),
+            blank: Boolean(item.blank),
+            updatedAt: item.updatedAt ?? 0,
+            cwd: item.cwd ?? '',
+          }
+        })
+        .sort((a, b) => b.updatedAt - a.updatedAt)
+    },
+    follow(sessionId, signal) {
+      return ctx.sessionController.follow(
+        { address: { kind: 'session', sessionId }, assistantStream: true },
+        signal,
+      )
+    },
+    prompt(sessionId, text) {
+      return ctx.sessionController.prompt({
+        requestId: randomUUID(),
+        sessionId,
+        mode: 'queue',
+        content: [{ type: 'text', text }],
+        clientTimeZone: timeZone(),
+      }, AbortSignal.timeout(30000))
+    },
+    cancel(sessionId) {
+      return ctx.sessionController.cancel({ sessionId })
+    },
+  }
+
+  fabric = createFabric({
+    log,
+    config,
+    stateFile: peersFile,
+    self: () => ({
+      deviceId: state?.deviceId ?? '',
+      deviceName: config.deviceName,
+      userId: identity.userId,
+      port: info.port,
+      proto: info.proto,
+    }),
+    sessions,
+  })
+
+  const ready = loadState(stateFile, config, log)
+    .then(async (loaded) => {
+      state = loaded
+      await refreshIdentity()
+      await start()
+      try {
+        await fabric.start()
+      } catch (error) {
+        log.warn(`[remote-control] peer discovery disabled: ${error?.message || error}`)
+      }
+      if (config.relayUrl && config.relayKey) {
+        try {
+          await startRelay(config.relayUrl, config.relayKey)
+        } catch (error) {
+          log.warn(`[remote-control] relay disabled: ${error?.message || error}`)
+        }
+      } else {
+        const persisted = await loadRelayConfig()
+        if (persisted?.hosted && persisted.key) {
+          try {
+            await startHostedRelay(persisted.key)
+          } catch (error) {
+            log.warn(`[remote-control] hosted relay disabled: ${error?.message || error}`)
+          }
+        } else if (persisted) {
+          try {
+            await startRelay(persisted.url, persisted.key)
+          } catch (error) {
+            log.warn(`[remote-control] relay disabled: ${error?.message || error}`)
+          }
+        }
+      }
+      const refresh = setInterval(() => { refreshIdentity().catch(() => {}) }, 60000)
+      refresh.unref?.()
+      ctx.effect(() => () => clearInterval(refresh))
+    })
+    .catch((error) => {
+      log.error(`[remote-control] disabled: ${error?.message || error}`)
+    })
+
+  async function refreshIdentity() {
+    const account = typeof ctx.get === 'function' ? safely(() => ctx.get('deepseekAccount')) : undefined
+    if (!account || typeof account.getDeviceIdentity !== 'function') return
+    try {
+      const value = await account.getDeviceIdentity()
+      identity.userId = value?.userId ?? null
+    } catch { /* signed out or unavailable */ }
+  }
+
+  const relayFile = path.join(dshHome(), 'remote-control-relay.json')
+
+  async function loadRelayConfig() {
+    try {
+      const raw = JSON.parse(await readFile(relayFile, 'utf8'))
+      if (raw && typeof raw.url === 'string' && typeof raw.key === 'string') return { url: raw.url, key: raw.key }
+    } catch (error) {
+      if (error?.code !== 'ENOENT') log.warn(`[remote-control] could not read ${relayFile}: ${error?.message || error}`)
+    }
+    return null
+  }
+
+  async function saveRelayConfig(value) {
+    try {
+      await writeFile(relayFile, JSON.stringify(value, null, 2), { mode: 0o600 })
+    } catch (error) {
+      log.warn(`[remote-control] could not persist ${relayFile}: ${error?.message || error}`)
+    }
+  }
+
+  async function clearRelayConfig() {
+    try { await rm(relayFile, { force: true }) } catch { /* ignore */ }
+  }
+
+  async function startRelay(url, key) {
+    const link = createRelayLink({
+      url,
+      key,
+      deviceId: state.deviceId,
+      deviceName: config.deviceName,
+      userId: identity.userId,
+      localPort: info.port,
+      log,
+    })
+    // Connect first: a failed join must not tear down a working relay link.
+    await link.start()
+    stopRelay()
+    relayLink = link
+    fabric.setRelay(link)
+    log.info(`[remote-control] relay connected: ${url}`)
+  }
+
+  function stopRelay() {
+    if (!relayLink) return
+    try { relayLink.stop() } catch { /* ignore */ }
+    relayLink = undefined
+    try { fabric?.setRelay(undefined) } catch { /* ignore */ }
+  }
+
+  /** Serve the relay from this Host and point our own link at it. */
+  async function startHostedRelay(key) {
+    stopHostedRelay()
+    relayCore = createRelay({ log })
+    hostedKey = key
+    try {
+      await startRelay(`http://127.0.0.1:${info.port}`, key)
+    } catch (error) {
+      stopHostedRelay()
+      throw error
+    }
+  }
+
+  function stopHostedRelay() {
+    if (relayCore) {
+      try { relayCore.close() } catch { /* ignore */ }
+      relayCore = undefined
+    }
+    hostedKey = ''
+  }
+
+  function shareUrls() {
+    if (config.publicUrl) return [config.publicUrl.replace(/\/+$/, '')]
+    return accessUrls(config, info.port, info.proto)
+  }
+
+  ctx.effect(() => () => {
+    for (const controller of streams) {
+      try { controller.abort() } catch { /* ignore */ }
+    }
+    streams.clear()
+    try { relayLink?.stop() } catch { /* ignore */ }
+    try { relayCore?.close() } catch { /* ignore */ }
+    try { fabric?.stop() } catch { /* ignore */ }
+    if (server) {
+      try { server.close() } catch { /* ignore */ }
+      server = undefined
+    }
+  })
+
+  // Discoverability: the local GUI can show the pairing code and reachable URLs.
+  // The handler refuses any non-loopback Host, so it never leaks over a LAN bind.
+  const webServer = typeof ctx.get === 'function' ? safely(() => ctx.get('webServer')) : undefined
+  if (webServer && typeof webServer.register === 'function') {
+    ctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: '/remote-control',
+      handler: (req, res) => serveInfo(req, res, published),
+    }))
+    ctx.effect(() => webServer.register({
+      kind: 'prefix',
+      path: '/remote-control/api',
+      handler: (req, res) => {
+        handleConsole(req, res).catch((error) => {
+          log.warn(`[remote-control] console call failed: ${error?.message || error}`)
+          try { json(res, 500, { error: 'internal', message: String(error?.message || error) }) } catch { /* ignore */ }
+        })
+      },
+    }))
+  }
+
+  async function handleConsole(req, res) {
+    if (!consoleAllowed(req)) return json(res, 403, { error: 'forbidden' })
+    if (!fabric) return json(res, 503, { error: 'starting' })
+    const url = new URL(req.url || '/', `http://${req.headers.host || 'localhost'}`)
+    const action = url.pathname.slice('/remote-control/api'.length)
+
+    if (action === '/state' && req.method === 'GET') {
+      const snapshot = fabric.snapshot()
+      const urls = relayCore ? shareUrls() : []
+      snapshot.relay = {
+        url: relayLink?.url() ?? '',
+        connected: relayLink?.connected() ?? false,
+        peers: relayLink?.peers().length ?? 0,
+        hosted: Boolean(relayCore),
+        urls,
+        invite: relayCore && hostedKey && urls[0] ? `${urls[0]} ${hostedKey}` : '',
+      }
+      return json(res, 200, snapshot)
+    }
+    if (action === '/relay/host' && req.method === 'POST') {
+      const body = await readJson(req)
+      if (body?.enabled === false) {
+        stopRelay()
+        stopHostedRelay()
+        await clearRelayConfig()
+        return json(res, 200, { ok: true })
+      }
+      let key = typeof body?.key === 'string' && body.key.length >= 16 ? body.key : ''
+      if (!key) {
+        const persisted = await loadRelayConfig()
+        key = persisted?.hosted && persisted.key ? persisted.key : randomBytes(16).toString('hex')
+      }
+      try {
+        await startHostedRelay(key)
+      } catch (error) {
+        return json(res, 502, { error: 'relay-failed', message: String(error?.message || error) })
+      }
+      const urls = shareUrls()
+      await saveRelayConfig({ hosted: true, url: urls[0] ?? '', key })
+      log.info(`[remote-control] hosting a relay at ${urls[0] ?? '(no address)'}`)
+      return json(res, 200, { ok: true, urls, invite: `${urls[0] ?? ''} ${key}` })
+    }
+    if (action === '/relay' && req.method === 'POST') {
+      const body = await readJson(req)
+      const url = String(body?.url || '').trim()
+      const key = String(body?.key || '')
+      let parsed
+      try { parsed = new URL(url) } catch { return json(res, 400, { error: 'bad-url', message: 'Relay URL must be absolute.' }) }
+      if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        return json(res, 400, { error: 'bad-url', message: 'Relay URL must use http or https.' })
+      }
+      if (key.length < 16) {
+        return json(res, 400, { error: 'bad-key', message: 'Workspace key must be at least 16 characters.' })
+      }
+      try {
+        await startRelay(url, key)
+      } catch (error) {
+        return json(res, 502, { error: 'relay-unreachable', message: String(error?.message || error) })
+      }
+      stopHostedRelay()
+      await saveRelayConfig({ hosted: false, url, key })
+      return json(res, 200, { ok: true })
+    }
+    if (action === '/relay/clear' && req.method === 'POST') {
+      stopRelay()
+      stopHostedRelay()
+      await clearRelayConfig()
+      return json(res, 200, { ok: true })
+    }
+    if (action === '/approve' && req.method === 'POST') {
+      const body = await readJson(req)
+      return json(res, 200, await fabric.approveRequest(String(body?.requestId || '')))
+    }
+    if (action === '/deny' && req.method === 'POST') {
+      const body = await readJson(req)
+      return json(res, 200, fabric.denyRequest(String(body?.requestId || '')))
+    }
+    if (action === '/connect' && req.method === 'POST') {
+      const body = await readJson(req)
+      return json(res, 200, await fabric.connect(String(body?.deviceId || '')))
+    }
+
+    const match = action.match(/^\/peer\/([^/]+)\/(sessions|stream|prompt|cancel)$/)
+    if (match) {
+      const deviceId = decodeURIComponent(match[1])
+      const operation = match[2]
+      if (operation === 'sessions' && req.method === 'GET') {
+        const reply = await fabric.callPeer(deviceId, 'GET', '/peer/sessions')
+        return json(res, reply.status ?? (reply.ok ? 200 : 502), reply.json ?? { error: reply.error })
+      }
+      if (operation === 'stream' && req.method === 'GET') {
+        return fabric.proxyStream(deviceId, String(url.searchParams.get('sessionId') || ''), res)
+      }
+      if (operation === 'prompt' && req.method === 'POST') {
+        const body = await readJson(req)
+        const reply = await fabric.callPeer(deviceId, 'POST', '/peer/prompt', {
+          sessionId: body?.sessionId,
+          text: body?.text,
+        })
+        return json(res, reply.status ?? (reply.ok ? 200 : 502), reply.json ?? { error: reply.error })
+      }
+      if (operation === 'cancel' && req.method === 'POST') {
+        const body = await readJson(req)
+        const reply = await fabric.callPeer(deviceId, 'POST', '/peer/cancel', { sessionId: body?.sessionId })
+        return json(res, reply.status ?? (reply.ok ? 200 : 502), reply.json ?? { error: reply.error })
+      }
+    }
+    return json(res, 404, { error: 'not-found' })
+  }
+
+  async function start() {
+    const options = {}
+    let factory = createHttpServer
+    let scheme = 'http'
+    if (config.tls) {
+      const [cert, key] = await Promise.all([
+        readFile(path.resolve(config.tls.certFile)),
+        readFile(path.resolve(config.tls.keyFile)),
+      ])
+      options.cert = cert
+      options.key = key
+      factory = createHttpsServer
+      scheme = 'https'
+    }
+
+    server = factory(options, (req, res) => {
+      handle(req, res).catch((error) => {
+        log.error(`[remote-control] request failed: ${error?.stack || error}`)
+        try { json(res, 500, { error: 'internal', message: String(error?.message || error) }) } catch { /* ignore */ }
+      })
+    })
+    server.on('clientError', (_error, socket) => {
+      try { socket.destroy() } catch { /* ignore */ }
+    })
+
+    await new Promise((resolve, reject) => {
+      const onError = (error) => reject(error)
+      server.once('error', onError)
+      server.listen(config.port, config.host, () => {
+        server.off('error', onError)
+        resolve()
+      })
+    })
+
+    server.on('error', (error) => log.error(`[remote-control] listener error: ${error?.message || error}`))
+
+    const port = server.address()?.port ?? config.port
+    info.port = port
+    info.proto = scheme
+    const urls = accessUrls(config, port, scheme)
+    published.urls = urls
+    published.code = state.code
+    log.info(`[remote-control] pairing code: ${state.code}`)
+    log.info(`[remote-control] open one of: ${urls.join('  ')}`)
+    log.info(`[remote-control] state file: ${stateFile} (delete it to rotate the code)`)
+  }
+
+  async function handle(req, res) {
+    const host = String(req.headers.host || '')
+    if (!hostAllowed(host, config)) {
+      return json(res, 403, { error: 'host-not-allowed', message: 'This Host header is not trusted by the remote-control listener.' })
+    }
+
+    const url = new URL(req.url || '/', `http://${host || 'localhost'}`)
+    const pathname = url.pathname
+
+    if (pathname === '/peer' || pathname.startsWith('/peer/')) {
+      return fabric.handlePeer(req, res, url)
+    }
+
+    if (relayCore && pathname.startsWith('/v1/')) {
+      return relayCore.handle(req, res)
+    }
+
+    if (req.method === 'GET' && STATIC_FILES[pathname]) {
+      const [file, type] = STATIC_FILES[pathname]
+      return serveStatic(res, file, type)
+    }
+
+    if (pathname === '/api/me') {
+      return json(res, 200, {
+        authenticated: isAuthenticated(req, state.secret),
+        name: 'DSH Remote Control',
+        version: '0.1.0',
+      })
+    }
+
+    if (pathname === '/api/pair' && req.method === 'POST') {
+      return pair(req, res)
+    }
+
+    if (pathname.startsWith('/api/')) {
+      if (!isAuthenticated(req, state.secret)) {
+        return json(res, 401, { error: 'unauthorized' })
+      }
+      if (req.method === 'POST' && !sameOrigin(req, config)) {
+        return json(res, 403, { error: 'origin-not-allowed' })
+      }
+    }
+
+    if (pathname === '/api/logout' && req.method === 'POST') {
+      res.setHeader('set-cookie', `${COOKIE_NAME}=; Path=/; HttpOnly; SameSite=Strict; Max-Age=0`)
+      return json(res, 200, { ok: true })
+    }
+
+    if (pathname === '/api/sessions' && req.method === 'GET') {
+      if (!ctx.sessionController) return json(res, 503, { error: 'session-controller-unavailable' })
+      return listSessions(res)
+    }
+
+    if (pathname === '/api/stream' && req.method === 'GET') {
+      if (!ctx.sessionController) return json(res, 503, { error: 'session-controller-unavailable' })
+      return streamSession(req, res, url)
+    }
+
+    if (pathname === '/api/prompt' && req.method === 'POST') {
+      if (!ctx.sessionController) return json(res, 503, { error: 'session-controller-unavailable' })
+      return promptSession(req, res)
+    }
+
+    if (pathname === '/api/cancel' && req.method === 'POST') {
+      if (!ctx.sessionController) return json(res, 503, { error: 'session-controller-unavailable' })
+      return cancelSession(req, res)
+    }
+
+    if (pathname === '/api/new-session' && req.method === 'POST') {
+      if (!ctx.sessionController) return json(res, 503, { error: 'session-controller-unavailable' })
+      return newSession(req, res)
+    }
+
+    return json(res, 404, { error: 'not-found' })
+  }
+
+  async function pair(req, res) {
+    if (!sameOrigin(req, config)) return json(res, 403, { error: 'origin-not-allowed' })
+    const body = await readJson(req)
+    const code = typeof body?.code === 'string' ? body.code.trim() : ''
+    const ip = clientIp(req)
+    if (tooManyAttempts(ip)) {
+      return json(res, 429, { error: 'rate-limited', message: 'Too many attempts. Wait a few minutes and try again.' })
+    }
+    if (!constantTimeEquals(code, state.code)) {
+      recordFailure(ip)
+      log.warn(`[remote-control] rejected pairing attempt from ${ip}`)
+      return json(res, 401, { error: 'bad-code', message: 'That pairing code is not correct.' })
+    }
+    recordSuccess(ip)
+    const token = issueToken(state.secret, config.cookieDays)
+    const attributes = [
+      `${COOKIE_NAME}=${token}`,
+      'Path=/',
+      'HttpOnly',
+      'SameSite=Strict',
+      `Max-Age=${Math.round(Math.max(1, config.cookieDays) * 86400)}`,
+    ]
+    if (config.tls) attributes.push('Secure')
+    res.setHeader('set-cookie', attributes.join('; '))
+    log.info(`[remote-control] paired a browser from ${ip}`)
+    return json(res, 200, { ok: true })
+  }
+
+  async function listSessions(res) {
+    const items = await sessions.list()
+    return json(res, 200, { items })
+  }
+
+  async function streamSession(req, res, url) {
+    const sessionId = String(url.searchParams.get('sessionId') || '')
+    if (!sessionId) return json(res, 400, { error: 'missing-session' })
+
+    const controller = new AbortController()
+    streams.add(controller)
+    res.writeHead(200, {
+      'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'no-store, no-transform',
+      connection: 'keep-alive',
+      'x-accel-buffering': 'no',
+    })
+    res.write(': connected\n\n')
+
+    const heartbeat = setInterval(() => {
+      try { res.write(': ping\n\n') } catch { /* ignore */ }
+    }, 15000)
+    heartbeat.unref?.()
+
+    let closed = false
+    const cleanup = () => {
+      if (closed) return
+      closed = true
+      clearInterval(heartbeat)
+      streams.delete(controller)
+      try { controller.abort() } catch { /* ignore */ }
+      try { res.end() } catch { /* ignore */ }
+    }
+    req.on('close', cleanup)
+    req.on('aborted', cleanup)
+
+    try {
+      const frames = ctx.sessionController.follow(
+        { address: { kind: 'session', sessionId }, assistantStream: true },
+        controller.signal,
+      )
+      for await (const frame of frames) {
+        if (res.writableEnded || res.destroyed) break
+        res.write(`data: ${JSON.stringify(frame)}\n\n`)
+      }
+    } catch (error) {
+      if (!controller.signal.aborted) {
+        const payload = { type: 'remote-error', code: error?.code ?? 'error', message: error?.message ?? String(error) }
+        try { res.write(`data: ${JSON.stringify(payload)}\n\n`) } catch { /* ignore */ }
+        log.warn(`[remote-control] follow failed for ${sessionId}: ${error?.message || error}`)
+      }
+    } finally {
+      cleanup()
+    }
+  }
+
+  async function promptSession(req, res) {
+    const body = await readJson(req)
+    const sessionId = typeof body?.sessionId === 'string' ? body.sessionId : ''
+    const text = typeof body?.text === 'string' ? body.text : ''
+    const mode = body?.mode === 'steer' ? 'steer' : 'queue'
+    if (!sessionId) return json(res, 400, { error: 'missing-session' })
+    if (!text.trim()) return json(res, 400, { error: 'empty-prompt', message: 'Write a message first.' })
+
+    const accepted = await ctx.sessionController.prompt({
+      requestId: randomUUID(),
+      sessionId,
+      mode,
+      content: [{ type: 'text', text }],
+      clientTimeZone: timeZone(),
+    }, AbortSignal.timeout(30000))
+    return json(res, 200, accepted ?? { accepted: true })
+  }
+
+  async function cancelSession(req, res) {
+    const body = await readJson(req)
+    const sessionId = typeof body?.sessionId === 'string' ? body.sessionId : ''
+    if (!sessionId) return json(res, 400, { error: 'missing-session' })
+    const value = ctx.sessionController.cancel({ sessionId })
+    return json(res, 200, value ?? { accepted: true })
+  }
+
+  async function newSession(req, res) {
+    const body = await readJson(req)
+    const request = {}
+    if (typeof body?.cwd === 'string' && body.cwd.trim()) request.cwd = body.cwd.trim()
+    else if (config.defaultCwd) request.cwd = config.defaultCwd
+    const value = await ctx.sessionController.create(request)
+    return json(res, 200, value)
+  }
+
+  async function serveStatic(res, file, type) {
+    try {
+      const data = await readFile(path.join(WEB_DIR, file))
+      res.writeHead(200, {
+        'content-type': type,
+        'cache-control': 'no-store',
+        'content-length': data.length,
+        'x-content-type-options': 'nosniff',
+      })
+      res.end(data)
+    } catch {
+      json(res, 404, { error: 'not-found' })
+    }
+  }
+
+  function json(res, status, value) {
+    const body = JSON.stringify(value)
+    res.writeHead(status, {
+      'content-type': 'application/json; charset=utf-8',
+      'content-length': Buffer.byteLength(body),
+      'cache-control': 'no-store',
+      'x-content-type-options': 'nosniff',
+    })
+    res.end(body)
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* loopback discovery page                                             */
+/* ------------------------------------------------------------------ */
+
+function serveInfo(req, res, published) {
+  const headers = {
+    'content-type': 'text/html; charset=utf-8',
+    'cache-control': 'no-store',
+    'x-content-type-options': 'nosniff',
+  }
+  const host = String(req.headers?.host || '')
+  const hostname = host.startsWith('[') ? host.slice(1, host.indexOf(']')) : host.split(':')[0]
+  const local = hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '::1'
+  if (!local) {
+    res.writeHead(403, headers)
+    res.end(renderInfoPage('Local only', '<p class="muted">Open this page from the harness computer itself.</p>'))
+    return
+  }
+
+  const code = published.code || 'starting…'
+  const urls = published.urls.length > 0 ? published.urls : []
+  const items = urls.length > 0
+    ? urls.map((url) => `<li><a href="${escapeHtml(url)}" target="_blank" rel="noreferrer">${escapeHtml(url)}</a></li>`).join('')
+    : '<li class="muted">starting…</li>'
+  const body = `
+    <p class="muted">Open one of these addresses on your phone or another computer, then enter the pairing code.</p>
+    <ul class="urls">${items}</ul>
+    <div class="code" aria-label="Pairing code">${escapeHtml(code)}</div>
+    <p class="muted small">The code is stored in <code>remote-control.json</code> inside your DSH home directory. Deleting that file rotates the code and forgets every paired device.</p>`
+  res.writeHead(200, headers)
+  res.end(renderInfoPage('Remote Control', body, code))
+}
+
+function renderInfoPage(title, body) {
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>
+  :root { color-scheme: dark light; --bg:#0b0d12; --fg:#e8ecf4; --muted:#93a0b5; --line:#232936; --accent:#5b8bff; }
+  @media (prefers-color-scheme: light) { :root { --bg:#f5f7fb; --fg:#14181f; --muted:#5d6779; --line:#dde2ec; --accent:#2f6bff; } }
+  body { margin:0; min-height:100vh; display:grid; place-items:center; background:var(--bg); color:var(--fg);
+         font:16px/1.5 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif; padding:24px; }
+  .card { width:100%; max-width:520px; border:1px solid var(--line); border-radius:18px; padding:24px; background:color-mix(in srgb, var(--fg) 3%, var(--bg)); }
+  h1 { font-size:18px; margin:0 0 12px; }
+  .muted { color:var(--muted); }
+  .small { font-size:13px; margin-top:18px; }
+  .urls { padding-left:18px; margin:12px 0 18px; }
+  .urls a { color:var(--accent); word-break:break-all; }
+  .code { font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; font-size:34px; letter-spacing:.28em;
+          text-align:center; padding:14px; border:1px dashed var(--line); border-radius:14px; }
+  code { font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace; }
+</style></head>
+<body><div class="card"><h1>${escapeHtml(title)}</h1>${body}</div></body></html>`
+}
+
+function escapeHtml(value) {
+  return String(value).replace(/[&<>"']/g, (character) => ({
+    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+  }[character]))
+}
+
+/* ------------------------------------------------------------------ */
+/* configuration                                                       */
+/* ------------------------------------------------------------------ */
+
+function normalizeConfig(raw = {}) {
+  const config = {
+    host: typeof raw?.host === 'string' && raw.host.trim() ? raw.host.trim() : '0.0.0.0',
+    port: Number.isInteger(raw?.port) ? raw.port : 57330,
+    publicUrl: typeof raw?.publicUrl === 'string' ? raw.publicUrl.trim() : '',
+    trustedHosts: Array.isArray(raw?.trustedHosts) ? raw.trustedHosts.filter((entry) => typeof entry === 'string') : [],
+    code: typeof raw?.code === 'string' ? raw.code.trim() : '',
+    cookieDays: Number.isFinite(raw?.cookieDays) ? raw.cookieDays : 30,
+    defaultCwd: typeof raw?.defaultCwd === 'string' ? raw.defaultCwd.trim() : '',
+    discovery: raw?.discovery !== false,
+    discoveryPort: Number.isInteger(raw?.discoveryPort) ? raw.discoveryPort : 57331,
+    relayUrl: typeof raw?.relayUrl === 'string' ? raw.relayUrl.trim() : '',
+    relayKey: typeof raw?.relayKey === 'string' ? raw.relayKey : '',
+    deviceName: typeof raw?.deviceName === 'string' && raw.deviceName.trim() ? raw.deviceName.trim() : os.hostname(),
+    tls: raw?.tls && typeof raw.tls === 'object' ? { certFile: raw.tls.certFile, keyFile: raw.tls.keyFile } : null,
+  }
+  if (!(config.port >= 0 && config.port <= 65535)) throw new Error('remote-control: `port` must be 0-65535')
+  if (!(config.discoveryPort >= 1 && config.discoveryPort <= 65535)) throw new Error('remote-control: `discoveryPort` must be 1-65535')
+  if (config.code && !/^\d{4,12}$/.test(config.code)) throw new Error('remote-control: `code` must be 4-12 digits')
+  if (config.cookieDays <= 0) throw new Error('remote-control: `cookieDays` must be positive')
+  if (config.tls && (!config.tls.certFile || !config.tls.keyFile)) throw new Error('remote-control: `tls` needs both certFile and keyFile')
+  if (config.publicUrl) {
+    try {
+      new URL(config.publicUrl)
+    } catch {
+      throw new Error('remote-control: `publicUrl` must be an absolute http(s) URL')
+    }
+  }
+  if (config.relayUrl) {
+    let parsed
+    try {
+      parsed = new URL(config.relayUrl)
+    } catch {
+      throw new Error('remote-control: `relayUrl` must be an absolute http(s) URL')
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+      throw new Error('remote-control: `relayUrl` must use http or https')
+    }
+    if (!config.relayKey || config.relayKey.length < 16) {
+      throw new Error('remote-control: `relayKey` must be at least 16 characters when `relayUrl` is set')
+    }
+  }
+  return config
+}
+
+function dshHome() {
+  return process.env.DSH_HOME || path.join(os.homedir(), '.dsh')
+}
+
+async function loadState(file, config, log) {
+  let persisted
+  try {
+    persisted = JSON.parse(await readFile(file, 'utf8'))
+  } catch (error) {
+    if (error?.code !== 'ENOENT') log.warn(`[remote-control] could not read ${file}: ${error?.message || error}`)
+  }
+  if (persisted && typeof persisted.secret === 'string' && persisted.secret.length >= 32) {
+    const state = {
+      secret: persisted.secret,
+      code: config.code || (typeof persisted.code === 'string' ? persisted.code : generateCode()),
+      createdAt: persisted.createdAt ?? Date.now(),
+      deviceId: typeof persisted.deviceId === 'string' && persisted.deviceId ? persisted.deviceId : newDeviceId(),
+    }
+    if (state.deviceId !== persisted.deviceId) await persistState(file, state, log)
+    return state
+  }
+  const state = {
+    secret: randomBytes(32).toString('hex'),
+    code: config.code || generateCode(),
+    createdAt: Date.now(),
+    deviceId: newDeviceId(),
+  }
+  await persistState(file, state, log)
+  return state
+}
+
+async function persistState(file, state, log) {
+  try {
+    await mkdir(path.dirname(file), { recursive: true })
+    await writeFile(file, JSON.stringify(state, null, 2), { mode: 0o600 })
+  } catch (error) {
+    log.warn(`[remote-control] could not persist ${file}: ${error?.message || error}`)
+  }
+}
+
+function newDeviceId() {
+  return `dsh-${randomBytes(8).toString('hex')}`
+}
+
+function generateCode() {
+  return String(randomInt(0, 1_000_000)).padStart(6, '0')
+}
+
+function timeZone() {
+  try { return Intl.DateTimeFormat().resolvedOptions().timeZone } catch { return undefined }
+}
+
+function firstString(...candidates) {
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim()) return candidate.trim()
+  }
+  return ''
+}
+
+function pickLogger(ctx) {
+  const candidate = typeof ctx?.logger === 'function' ? safely(() => ctx.logger('remote-control')) : ctx?.logger
+  if (candidate && typeof candidate.info === 'function') return candidate
+  return console
+}
+
+function safely(fn) {
+  try { return fn() } catch { return undefined }
+}
+
+/* ------------------------------------------------------------------ */
+/* authentication                                                      */
+/* ------------------------------------------------------------------ */
+
+function parseCookies(header) {
+  const jar = {}
+  if (typeof header !== 'string') return jar
+  for (const part of header.split(';')) {
+    const index = part.indexOf('=')
+    if (index <= 0) continue
+    jar[part.slice(0, index).trim()] = part.slice(index + 1).trim()
+  }
+  return jar
+}
+
+function hmac(secret, value) {
+  return createHmac('sha256', secret).update(value).digest('hex')
+}
+
+function issueToken(secret, days) {
+  const expires = Date.now() + Math.max(1, days) * 86_400_000
+  return `${expires}.${hmac(secret, String(expires))}`
+}
+
+function isAuthenticated(req, secret) {
+  const raw = parseCookies(req.headers?.cookie)[COOKIE_NAME]
+  if (!raw) return false
+  const dot = raw.lastIndexOf('.')
+  if (dot <= 0) return false
+  const expires = raw.slice(0, dot)
+  const signature = raw.slice(dot + 1)
+  if (!/^\d{1,16}$/.test(expires) || Number(expires) < Date.now()) return false
+  const expected = Buffer.from(hmac(secret, expires), 'hex')
+  const actual = Buffer.from(signature, 'hex')
+  return actual.length === expected.length && timingSafeEqual(actual, expected)
+}
+
+function constantTimeEquals(value, expected) {
+  const left = Buffer.from(String(value))
+  const right = Buffer.from(String(expected))
+  return left.length === right.length && timingSafeEqual(left, right)
+}
+
+const attempts = new Map()
+
+function clientIp(req) {
+  return String(req.socket?.remoteAddress || 'unknown')
+}
+
+function tooManyAttempts(ip) {
+  const entry = attempts.get(ip)
+  if (!entry) return false
+  if (entry.resetAt < Date.now()) { attempts.delete(ip); return false }
+  return entry.failures >= 10
+}
+
+function recordFailure(ip) {
+  const now = Date.now()
+  const entry = attempts.get(ip)
+  if (!entry || entry.resetAt < now) {
+    attempts.set(ip, { failures: 1, resetAt: now + 10 * 60_000 })
+    return
+  }
+  entry.failures += 1
+}
+
+function recordSuccess(ip) {
+  attempts.delete(ip)
+}
+
+/* ------------------------------------------------------------------ */
+/* request trust                                                       */
+/* ------------------------------------------------------------------ */
+
+function hostAllowed(header, config) {
+  const host = String(header || '').trim()
+  if (!host) return false
+  const hostname = host.startsWith('[') ? host.slice(1, host.indexOf(']')) : host.split(':')[0]
+  const name = hostname.toLowerCase()
+  if (!name) return false
+  if (name === 'localhost') return true
+  if (config.publicUrl) {
+    try {
+      if (new URL(config.publicUrl).hostname.toLowerCase() === name) return true
+    } catch { /* ignore */ }
+  }
+  if (config.trustedHosts.some((entry) => entry.toLowerCase() === name || entry.toLowerCase() === host.toLowerCase())) return true
+  if (isIP(name)) {
+    if (name === '127.0.0.1' || name === '::1') return true
+    return isWildcard(config.host) || normalizeAddress(name) === normalizeAddress(config.host)
+  }
+  return false
+}
+
+function sameOrigin(req, config) {
+  const origin = req.headers?.origin
+  if (!origin || origin === 'null') return true
+  try {
+    const parsed = new URL(origin)
+    const host = String(req.headers.host || '').toLowerCase()
+    if (parsed.host.toLowerCase() === host) return true
+    if (config.publicUrl && parsed.host.toLowerCase() === new URL(config.publicUrl).host.toLowerCase()) return true
+    return false
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The Devices panel talks to this Host half through the GUI's own origin.
+ * Same-origin browser fetches are allowed; a non-browser caller must be local.
+ */
+function consoleAllowed(req) {
+  const site = req.headers?.['sec-fetch-site']
+  if (typeof site === 'string' && site !== 'same-origin' && site !== 'none') return false
+  if (!site && !isLoopbackAddress(req.socket?.remoteAddress)) return false
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    const origin = req.headers?.origin
+    if (typeof origin === 'string' && origin && origin !== 'null') {
+      try {
+        if (new URL(origin).host !== String(req.headers.host || '')) return false
+      } catch {
+        return false
+      }
+    }
+  }
+  return true
+}
+
+function isLoopbackAddress(address) {
+  const value = String(address || '')
+  return value === '127.0.0.1' || value === '::1' || value === '::ffff:127.0.0.1'
+}
+
+function isWildcard(host) {
+  return host === '0.0.0.0' || host === '::' || host === '*'
+}
+
+function normalizeAddress(value) {
+  return String(value).toLowerCase().replace(/^\[|\]$/g, '')
+}
+
+function accessUrls(config, port, scheme) {
+  if (config.publicUrl) return [config.publicUrl.replace(/\/+$/, '') + '/']
+  if (!isWildcard(config.host)) return [`${scheme}://${formatHost(config.host)}:${port}/`]
+  const addresses = []
+  for (const entries of Object.values(os.networkInterfaces())) {
+    for (const entry of entries ?? []) {
+      if (entry.internal) continue
+      if (entry.family !== 'IPv4' && entry.family !== 4) continue
+      addresses.push(`${scheme}://${entry.address}:${port}/`)
+    }
+  }
+  if (addresses.length === 0) addresses.push(`${scheme}://127.0.0.1:${port}/`)
+  return addresses
+}
+
+function formatHost(host) {
+  return host.includes(':') ? `[${host}]` : host
+}
+
+/* ------------------------------------------------------------------ */
+/* request helpers                                                     */
+/* ------------------------------------------------------------------ */
+
+function readJson(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    let size = 0
+    req.on('data', (chunk) => {
+      size += chunk.length
+      if (size > MAX_BODY_BYTES) {
+        reject(new Error('request body too large'))
+        req.destroy()
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => {
+      if (chunks.length === 0) return resolve({})
+      try {
+        resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')))
+      } catch (error) {
+        reject(error)
+      }
+    })
+    req.on('error', reject)
+  })
+}