dsh-plugin-mobile-gateway 0.4.1 → 0.5.0

package/lib/index.mjs

@@ -48,6 +48,8 @@
 //                     { "type": "agent-presets" }                     -> preset roster (+ isDefault)
 //                     { "type": "defaults" }                          -> default agent preset + default permission
 //                     { "type": "set-default", "target": "agent-preset"|"permission", "value" }
+//                     { "type": "question-answer", "rpcId", "sessionId", "answers": [...] }
+//                     { "type": "question-cancel", "rpcId", "sessionId" }
 //   server -> client: { "kind": "hello", "protocol": 2, "authenticated", "device"?, "port", "clients" }
 //                     { "kind": "pong", "at" }
 //                     { "kind": "subscribed", "sessionId" }
@@ -55,8 +57,12 @@
 //                     { "kind": "workspaces" | "sessions" | "history" | "search", ...data }
 //                     { "kind": "error", "code", "message", "requestType"?, "sessionId"? }
 //                     { "kind": "event", "sessionId", "seq", "time", "event": { ... } }
+//                     { "kind": "question-requested", "rpcId", "sessionId", "questions", "replay"? }
+//                     { "kind": "question-response", "rpcId", "sessionId", "action", "accepted", "reason"? }
+//                     { "kind": "question-resolved", "rpcId", "sessionId", "outcome" }
 import fs from 'node:fs'
 import fsp from 'node:fs/promises'
+import http from 'node:http'
 import os from 'node:os'
 import path from 'node:path'
 import crypto from 'node:crypto'
@@ -67,6 +73,13 @@ import QRCode from 'qrcode'
 
 const { createRegistry } = devicesModule
 
+const PLUGIN_VERSION = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
+  } catch {
+    return 'unknown'
+  }
+})()
 const MAX_PREVIEW = 400
 const LOG_FILE = '/tmp/mobile-gateway.log'
 const DEFAULT_WS_PATH = '/ws/mobile'
@@ -88,6 +101,10 @@ const Config = Schema.object({
   pairingTtlMs: Schema.natural().min(30_000).max(15 * 60 * 1000).default(DEFAULT_PAIRING_TTL_MS),
   allowQueryToken: Schema.boolean().default(false),
   publicUrlFile: Schema.string().default('/etc/dsh-mobile-gateway/public-url'),
+  lanEnabled: Schema.boolean().default(false),
+  lanHost: Schema.string().default('0.0.0.0'),
+  lanPort: Schema.natural().min(1).max(65535).default(3081),
+  lanAdvertiseHost: Schema.string().default(''),
 })
 
 function log(line) {
@@ -665,7 +682,7 @@ function extractClientDeviceId(req) {
 }
 
 function rejectUpgrade(socket, status, message) {
-  const reason = status === 401 ? 'Unauthorized' : status === 503 ? 'Service Unavailable' : 'Bad Request'
+  const reason = status === 401 ? 'Unauthorized' : status === 403 ? 'Forbidden' : status === 404 ? 'Not Found' : status === 503 ? 'Service Unavailable' : 'Bad Request'
   socket.write(`HTTP/1.1 ${status} ${reason}\r\nConnection: close\r\nContent-Type: text/plain; charset=utf-8\r\nContent-Length: ${Buffer.byteLength(message)}\r\n\r\n${message}`)
   socket.destroy()
 }
@@ -675,6 +692,47 @@ function isLocalHostname(hostname) {
   return normalized === 'localhost' || normalized === '::1' || /^127(?:\.\d{1,3}){3}$/.test(normalized)
 }
 
+function isPrivateNetworkHostname(hostname) {
+  let normalized = hostname.replace(/^\[|\]$/g, '').split('%')[0].toLowerCase()
+  if (normalized.startsWith('::ffff:')) normalized = normalized.slice('::ffff:'.length)
+  if (isLocalHostname(normalized) || normalized.endsWith('.local')) return true
+  const octets = normalized.split('.').map((part) => Number(part))
+  if (octets.length === 4 && octets.every((part) => Number.isInteger(part) && part >= 0 && part <= 255)) {
+    return octets[0] === 10 ||
+      (octets[0] === 172 && octets[1] >= 16 && octets[1] <= 31) ||
+      (octets[0] === 192 && octets[1] === 168) ||
+      (octets[0] === 169 && octets[1] === 254)
+  }
+  return /^(?:f[cd][0-9a-f]{2}:|fe[89ab][0-9a-f]:)/i.test(normalized)
+}
+
+function privateLanAddresses() {
+  const physical = []
+  const fallback = []
+  const virtualInterface = /^(?:docker|br-|veth|utun|awdl|llw|vmnet|vbox|virbr|tailscale|wg)/i
+  for (const [name, records] of Object.entries(os.networkInterfaces())) {
+    for (const record of records || []) {
+      if (!record || record.internal || record.family !== 'IPv4' || !isPrivateNetworkHostname(record.address)) continue
+      const target = virtualInterface.test(name) ? fallback : physical
+      if (!target.includes(record.address)) target.push(record.address)
+    }
+  }
+  return physical.length ? physical : fallback
+}
+
+function lanWebSocketUrls(options, wsPath, boundPort) {
+  if (!options.lanEnabled) return []
+  const advertised = typeof options.lanAdvertiseHost === 'string' ? options.lanAdvertiseHost.trim() : ''
+  const hosts = advertised
+    ? [advertised]
+    : options.lanHost && options.lanHost !== '0.0.0.0' && options.lanHost !== '::'
+      ? [options.lanHost]
+      : privateLanAddresses()
+  return hosts
+    .filter((host) => isPrivateNetworkHostname(host))
+    .map((host) => `ws://${host.includes(':') ? `[${host}]` : host}:${boundPort}${wsPath}`)
+}
+
 function badRequest(message) {
   const error = new Error(message)
   error.status = 400
@@ -690,9 +748,9 @@ function normalizePublicUrl(value, req, wsPath) {
   const url = new URL(raw)
   if (url.protocol === 'https:') url.protocol = 'wss:'
   if (url.protocol === 'http:') url.protocol = 'ws:'
-  if (url.protocol !== 'ws:' && url.protocol !== 'wss:') throw badRequest('publicUrl must use wss:// (ws:// is allowed only for localhost)')
+  if (url.protocol !== 'ws:' && url.protocol !== 'wss:') throw badRequest('publicUrl must use wss:// (ws:// is allowed only for localhost and private LAN addresses)')
   if (url.username || url.password || url.search || url.hash) throw badRequest('publicUrl must not contain credentials, query parameters, or a fragment')
-  if (url.protocol === 'ws:' && !isLocalHostname(url.hostname)) throw badRequest('publicUrl must use wss:// for non-localhost endpoints')
+  if (url.protocol === 'ws:' && !isPrivateNetworkHostname(url.hostname)) throw badRequest('publicUrl must use wss:// outside localhost or a private LAN')
   return url.toString()
 }
 
@@ -775,12 +833,22 @@ const plugin = {
       pairingTtlMs: DEFAULT_PAIRING_TTL_MS,
       allowQueryToken: false,
       publicUrlFile: '/etc/dsh-mobile-gateway/public-url',
+      lanEnabled: false,
+      lanHost: '0.0.0.0',
+      lanPort: 3081,
+      lanAdvertiseHost: '',
       ...(config || {}),
     }
     const wsPath = options.path
     if (typeof wsPath !== 'string' || !wsPath.startsWith('/') || wsPath.endsWith('/') || wsPath.includes('?') || wsPath.includes('#')) {
       throw new Error('mobile-gateway: path must be an absolute pathname without a trailing slash, query, or fragment')
     }
+    if (options.lanEnabled === true && (typeof options.lanHost !== 'string' || !options.lanHost.trim())) {
+      throw new Error('mobile-gateway: lanHost must be a non-empty listen address')
+    }
+    if (options.lanEnabled === true && options.lanAdvertiseHost && !isPrivateNetworkHostname(options.lanAdvertiseHost)) {
+      throw new Error('mobile-gateway: lanAdvertiseHost must be localhost or a private LAN address')
+    }
     let requireAuth = options.requireAuth !== false
     const adminLoopbackOnly = options.adminLoopbackOnly !== false
     const deviceFile = options.deviceFile || path.join(os.homedir(), '.dsh', 'mobile-gateway-devices.json')
@@ -795,6 +863,8 @@ const plugin = {
       },
     })
     const clients = new Set()
+    const pendingQuestions = new Map()
+    const questionMuxAbort = new AbortController()
     let counter = 0
     let gatewayEnabled = options.gatewayEnabled === true
     let waitExpiresAt = null
@@ -802,6 +872,10 @@ const plugin = {
     let connectedSinceEnabled = false
     let lastAuthRejectLogAt = 0
     let suppressedAuthRejects = 0
+    let lanServer = null
+    let lanListening = false
+    let lanListenError = null
+    let lanBoundPort = options.lanPort
     const configuredPublicUrl = () => {
       if (typeof options.publicUrl === 'string' && options.publicUrl.trim()) return options.publicUrl.trim()
       if (typeof options.publicUrlFile !== 'string' || !options.publicUrlFile.trim()) return ''
@@ -852,6 +926,72 @@ const plugin = {
       }
     }
 
+    const questionFrameFor = (rpcId, payload, replay = false) => ({
+      kind: 'question-requested',
+      rpcId: String(rpcId),
+      sessionId: String(payload.sessionId),
+      questions: payload.questions,
+      ...(replay ? { replay: true } : {}),
+    })
+
+    const broadcastQuestionFrame = (frame) => {
+      const wire = JSON.stringify(frame)
+      for (const client of clients) {
+        if (client.filterSessionId && client.filterSessionId !== frame.sessionId) continue
+        if (client.readyState === 1) client.send(wire)
+      }
+    }
+
+    const respondToQuestion = async (msg, cancel = false) => {
+      const rpcId = typeof msg.rpcId === 'string' && msg.rpcId.trim() ? msg.rpcId.trim() : null
+      const sessionId = typeof msg.sessionId === 'string' && msg.sessionId.trim() ? msg.sessionId.trim() : null
+      if (!rpcId || !sessionId) {
+        return { kind: 'error', code: 'bad-request', message: `${msg.type} requires rpcId and sessionId`, requestType: msg.type }
+      }
+
+      if (cancel) {
+        const pending = pendingQuestions.get(rpcId)
+        if (pending && pending.sessionId !== sessionId) {
+          return { kind: 'error', code: 'bad-request', message: 'sessionId does not match the pending question', requestType: msg.type, sessionId }
+        }
+      } else if (!Array.isArray(msg.answers)) {
+        return { kind: 'error', code: 'bad-request', message: 'question-answer requires an answers array', requestType: msg.type, sessionId }
+      }
+
+      const result = cancel
+        ? { ok: false, error: { code: 'cancelled', message: 'question cancelled by mobile user', details: {} } }
+        : {
+            ok: true,
+            value: {
+              sessionId,
+              answer: {
+                answers: msg.answers.map((answer) => ({
+                  id: answer && answer.id,
+                  selected: answer && answer.selected,
+                  ...(answer && answer.custom !== undefined ? { custom: answer.custom } : {}),
+                })),
+              },
+            },
+          }
+
+      try {
+        const receipt = await api.respond({ type: 'client-response', rpcId, result })
+        log(`question response: rpcId=${rpcId} session=${sessionId} action=${cancel ? 'cancel' : 'answer'} accepted=${receipt.accepted}${receipt.accepted ? '' : ` reason=${receipt.reason}`}`)
+        return {
+          kind: 'question-response',
+          rpcId,
+          sessionId,
+          action: cancel ? 'cancel' : 'answer',
+          accepted: receipt.accepted,
+          ...(!receipt.accepted ? { reason: receipt.reason } : {}),
+        }
+      } catch (error) {
+        const message = error && error.message ? error.message : String(error)
+        log(`question response failed: rpcId=${rpcId} ${message}`)
+        return { kind: 'error', code: 'internal', message, requestType: msg.type, sessionId }
+      }
+    }
+
     if (gatewayEnabled) setGatewayEnabled(true, 'enabled by startup config')
 
     log(`applying: path=${wsPath}, webServer.port=${webServer.port}, gatewayEnabled=${gatewayEnabled}, requireAuth=${requireAuth}, devices=${registry.count()}`)
@@ -874,12 +1014,22 @@ const plugin = {
           const p = url.pathname
           if (req.method === 'GET' && p === '/mgw/status') {
             sendJson(res, 200, {
+              version: PLUGIN_VERSION,
               requireAuth,
               gatewayEnabled,
               waitExpiresAt,
               connectedClients: clients.size,
               wsPath,
               publicUrl: configuredPublicUrl() || null,
+              lan: {
+                enabled: options.lanEnabled === true,
+                listening: lanListening,
+                host: options.lanHost,
+                port: lanBoundPort,
+                urls: lanWebSocketUrls(options, wsPath, lanBoundPort),
+                requireAuth: true,
+                error: lanListenError,
+              },
               pairingTtlMs: options.pairingTtlMs,
               queryTokenAllowed: !!options.allowQueryToken,
             })
@@ -960,9 +1110,7 @@ const plugin = {
     })
     log(`management routes registered: /mgw (loopbackOnly=${adminLoopbackOnly})`)
 
-    const disposeUpgrade = webServer.registerUpgrade({
-      path: wsPath,
-      handler(req, socket, head) {
+    const handleMobileUpgrade = (req, socket, head, transport = {}) => {
         if (!gatewayEnabled) {
           rejectUpgrade(socket, 503, 'mobile gateway is disabled')
           return
@@ -988,7 +1136,11 @@ const plugin = {
           device = registry.authenticate(credential.value, extractClientDeviceId(req))
         }
 
-        if (requireAuth && !device) {
+        // The separately exposed LAN listener is always authenticated. The
+        // management UI's debug auth switch only affects the loopback DSH
+        // listener and can never turn a LAN endpoint into an open control
+        // plane.
+        if ((requireAuth || transport.lan === true) && !device) {
           logAuthRejected(req)
           rejectUpgrade(socket, 401, 'missing or invalid device credential')
           return
@@ -1026,6 +1178,10 @@ const plugin = {
             } else if (msg.type === 'unsubscribe') {
               ws.filterSessionId = undefined
               ws.send(JSON.stringify({ kind: 'subscribed', sessionId: null }))
+            } else if (msg.type === 'question-answer' || msg.type === 'question-cancel') {
+              respondToQuestion(msg, msg.type === 'question-cancel').then((frame) => {
+                if (frame && ws.readyState === 1) ws.send(JSON.stringify(frame))
+              })
             } else if (msg.type === 'message') {
               admitMessage(api, msg).then((frame) => {
                 if (frame && ws.readyState === 1) ws.send(JSON.stringify(frame))
@@ -1062,16 +1218,67 @@ const plugin = {
           ws.send(JSON.stringify({
             kind: 'hello',
             protocol: 2,
-            port: webServer.port,
+            port: transport.port || webServer.port,
             clients: clients.size,
             authenticated: !!device,
             ...(device ? { device: { id: device.id, name: device.name } } : {}),
           }))
+          for (const pending of pendingQuestions.values()) {
+            if (ws.filterSessionId && ws.filterSessionId !== pending.sessionId) continue
+            ws.send(JSON.stringify(questionFrameFor(pending.rpcId, pending, true)))
+          }
         })
+    }
+
+    const disposeUpgrade = webServer.registerUpgrade({
+      path: wsPath,
+      handler(req, socket, head) {
+        handleMobileUpgrade(req, socket, head, { port: webServer.port })
       },
     })
     log(`upgrade route registered: ${wsPath}`)
 
+    // DSH intentionally keeps its own WebUI listener on loopback. When LAN
+    // mode is enabled, expose a second, narrowly scoped listener that accepts
+    // only the authenticated mobile WebSocket path. It does not serve the
+    // WebUI or any /mgw management route.
+    if (options.lanEnabled === true) {
+      lanServer = http.createServer((req, res) => {
+        sendJson(res, 404, { error: 'not-found' })
+      })
+      lanServer.on('upgrade', (req, socket, head) => {
+        let pathname
+        try {
+          pathname = new URL(req.url || '/', 'http://lan.invalid').pathname
+        } catch (error) {
+          rejectUpgrade(socket, 400, 'invalid WebSocket path')
+          return
+        }
+        if (pathname !== wsPath) {
+          rejectUpgrade(socket, 404, 'not found')
+          return
+        }
+        if (!req.socket || !req.socket.remoteAddress || !isPrivateNetworkHostname(req.socket.remoteAddress)) {
+          rejectUpgrade(socket, 403, 'LAN listener accepts private-network clients only')
+          return
+        }
+        handleMobileUpgrade(req, socket, head, { lan: true, port: lanBoundPort })
+      })
+      lanServer.on('error', (error) => {
+        lanListening = false
+        lanListenError = error && error.message ? error.message : String(error)
+        log(`LAN listener failed: ${lanListenError}`)
+      })
+      lanServer.listen(options.lanPort, options.lanHost, () => {
+        lanListening = true
+        lanListenError = null
+        const address = lanServer.address()
+        if (address && typeof address === 'object') lanBoundPort = address.port
+        const urls = lanWebSocketUrls(options, wsPath, lanBoundPort)
+        log(`LAN listener ready: ${options.lanHost}:${lanBoundPort}${wsPath}${urls.length ? ` (${urls.join(', ')})` : ''}; authentication forced`)
+      })
+    }
+
     const disposeEvents = ctx.on('session/event', (session, event) => {
       if (clients.size === 0) return
       const wire = buildWireEvent(session, event)
@@ -1084,11 +1291,55 @@ const plugin = {
     })
     log('session/event listener attached')
 
+    const questionMuxTask = api.events && typeof api.events.mux === 'function' && typeof api.respond === 'function'
+      ? (async () => {
+          try {
+            for await (const envelope of api.events.mux(
+              { rpcId: crypto.randomUUID(), payload: {} },
+              questionMuxAbort.signal,
+            )) {
+              const payload = envelope && envelope.payload
+              if (!payload || typeof payload.type !== 'string') continue
+              if (payload.type === 'question/requested') {
+                const rpcId = String(envelope.rpcId)
+                const pending = {
+                  rpcId,
+                  sessionId: String(payload.sessionId),
+                  questions: payload.questions,
+                }
+                pendingQuestions.set(rpcId, pending)
+                broadcastQuestionFrame(questionFrameFor(rpcId, pending))
+                log(`question requested: rpcId=${rpcId} session=${pending.sessionId} questions=${Array.isArray(pending.questions) ? pending.questions.length : 0}`)
+              } else if (payload.type === 'question/resolved') {
+                const questionRpcId = String(payload.questionRpcId)
+                pendingQuestions.delete(questionRpcId)
+                broadcastQuestionFrame({
+                  kind: 'question-resolved',
+                  rpcId: questionRpcId,
+                  sessionId: String(payload.sessionId),
+                  outcome: payload.outcome,
+                })
+                log(`question resolved: rpcId=${questionRpcId} session=${payload.sessionId} outcome=${payload.outcome}`)
+              }
+            }
+          } catch (error) {
+            if (!questionMuxAbort.signal.aborted) {
+              log(`question mux failed: ${error && error.message ? error.message : String(error)}`)
+            }
+          }
+        })()
+      : null
+    if (questionMuxTask) log('api gateway question mux attached')
+    else log('api gateway question mux unavailable; human-in-the-loop disabled')
+
     ctx.effect(() => () => {
       if (waitTimer) clearTimeout(waitTimer)
+      questionMuxAbort.abort()
+      pendingQuestions.clear()
       disposeUpgrade()
       disposeMgmt()
       disposeEvents()
+      if (lanServer) lanServer.close()
       for (const client of clients) client.terminate()
       clients.clear()
       wss.close()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-mobile-gateway",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Persistent WebSocket gateway for dsh: exposes /ws/mobile on the web server and forwards agent session output to connected mobile clients",
   "main": "lib/index.mjs",
   "files": [
@@ -25,7 +25,7 @@
   },
   "bin": "bin/setup-ip.mjs",
   "scripts": {
-    "test": "node test/setup-ip.test.mjs && node test/gateway.test.mjs && node test/auth.test.mjs"
+    "test": "node test/setup-ip.test.mjs && node test/gateway.test.mjs && node test/auth.test.mjs && node test/lan.test.mjs"
   },
   "exports": {
     ".": "./lib/index.mjs",