@goodandready/dsh-lanmode 0.5.0 → 0.6.0

package/README.md

@@ -132,6 +132,64 @@ A self-signed certificate is a compromise, not a solution: the browser will
 still ask. But it turns "impossible" into "confirm once", and that is the whole
 difference between voice input working over the network and not.
 
+## Replacing a reverse proxy
+
+Direct mode is meant to be the whole answer: install the plugin, set two fields,
+switch the proxy off. What a reverse proxy in front of the harness has to do,
+the bridge does — rewrite `Host` and `Origin` so the same-origin fence passes,
+carry WebSockets, keep long-lived streams alive, terminate TLS.
+
+**Moving over without anyone noticing.** Keep the address, the port and the
+certificate the browsers have already accepted:
+
+```yaml
+- id: dsh-lanmode
+  config:
+    mode: direct
+    directPort: 3080          # the port the proxy served on
+    tls: files
+    tlsCert: /path/to/your/existing/fullchain.pem
+    tlsKey: /path/to/your/existing/key.pem
+    unlockPrivileged: true
+    allow:
+      - 192.168.0.0/16
+```
+
+Then stop the proxy. Nothing changes for anyone: same URL, same certificate, no
+second confirmation.
+
+The harness already holds that port on the loopback, so `directHost` is left
+alone: the plugin notices the clash and binds this machine's network addresses
+by name instead of binding everything. It says so in the log.
+
+**Starting from nothing.** No proxy, no certificate:
+
+```yaml
+- id: dsh-lanmode
+  config:
+    mode: direct
+    directPort: 3088
+    tls: self-signed
+    unlockPrivileged: true
+    allow:
+      - 192.168.0.0/16
+```
+
+The browser asks once about the certificate; compare the fingerprint printed in
+the log and accept it.
+
+**What you lose compared with a real proxy.** Not much, and it is worth naming:
+no HTTP/2, no gzip, no request logging beyond refusals, no rate limiting, no
+virtual hosts. If you need any of those, keep the proxy — the plugin does not
+mind sitting behind one, and that is exactly what `proxy` mode is.
+
+**What you do not lose.** Settings and credentials over the network, WebSockets,
+streamed replies of any length, TLS, the microphone.
+
+**Check after switching**, in this order: the conversation opens and a reply
+streams to the end; settings open and save; a long reply is not cut; the
+microphone works on `/dsh-lanmode/health`.
+
 ## Who may connect
 
 The direct listener has no password and will not get one: the plugin does not
@@ -156,6 +214,33 @@ Two honest limits. This is not authentication: whoever is on the list gets in
 unchecked. And behind a reverse proxy it means nothing — every request arrives
 from the proxy, so filter there instead.
 
+## The price of it working
+
+The harness pins its privileged calls — settings, credentials, agent presets,
+opening paths on the machine, model discovery — to the loopback on purpose, and
+no trusted-host list opens them. The bridge presents itself as a loopback
+client, so those calls go through. That is not a side effect: without it a page
+on the network shows the settings and can neither read nor write them, which is
+the whole reason this plugin exists.
+
+The price, stated plainly: **any device that reaches this port can read and
+change your API keys, with no authentication at all.** Nothing here asks who you
+are.
+
+It is a setting, not a secret:
+
+```yaml
+    unlockPrivileged: false   # settings over the network stop working
+```
+
+Off, the privileged calls are refused by the bridge with a message saying why,
+and everything else keeps working. On — which is the default, because otherwise
+the plugin does not do its job — the log says at startup exactly what is open,
+and the diagnostics page shows it as a separate line.
+
+Fill in `allow` either way. It is not authentication, but it narrows the circle
+from «the whole network» to «these addresses».
+
 ## Diagnostics
 
 `GET /dsh-lanmode/health` — one page answering the questions that otherwise take
@@ -197,6 +282,9 @@ All of it can be edited as the `dsh-lanmode` namespace — in `$DSH_HOME/setting
 | `tlsCert` | — | `files`: path to the certificate in PEM |
 | `tlsKey` | — | `files`: path to the private key in PEM |
 | `allow` | `[]` | `direct`: addresses and CIDR ranges allowed in. Empty means everyone |
+| `unlockPrivileged` | `true` | `direct`: let the settings and credentials calls through. What makes the plugin work, and what opens your keys to the network |
+| `privilegedExtra` | `[]` | `direct`: extra path patterns to treat as privileged |
+| `streamTimeoutMs` | `0` | `direct`: limit on one request. Zero means none, and that is what long replies need |
 | `diagnostics` | `true` | serve `GET /dsh-lanmode/health` |
 | `settings` | `true` | return the settings service |
 | `randomUuid` | `true` | provide `crypto.randomUUID` on plain HTTP |

package/lib/bind.js

@@ -0,0 +1,25 @@
+// Выбор адреса для слушателя прямого режима.
+//
+// Отдельным модулем, потому что проверки не должны тянуть за собой харнесс:
+// точка входа импортирует схему настроек, а её в рабочей копии нет.
+
+import { localAddresses } from './tls.js'
+
+/**
+ * На каких адресах слушать.
+ *
+ * Харнесс уже занимает свой порт на петле, поэтому «все адреса» на том же порту
+ * не поднимутся вовсе: получится EADDRINUSE, и плагин молча не заработает. В
+ * этом случае привязываемся к сетевым адресам машины поимённо — привычный порт
+ * сохраняется, столкновения нет.
+ */
+export function bindAddresses(config, harnessPort) {
+  const wanted = String(config.directHost || '0.0.0.0')
+  const port = config.directPort || 3088
+  const everywhere = wanted === '0.0.0.0' || wanted === '::' || wanted === ''
+  if (!everywhere || port !== harnessPort) return { hosts: [wanted], shared: false }
+
+  const own = localAddresses().filter((address) => /^[0-9.]+$/.test(address) && !/^127\./.test(address))
+  if (own.length === 0) return { hosts: [wanted], shared: false }
+  return { hosts: own, shared: true }
+}

package/lib/bridge.js

@@ -19,6 +19,7 @@ import http from 'node:http'
 import https from 'node:https'
 
 import { allowed } from './access.js'
+import { REFUSED, isPrivileged } from './privileged.js'
 
 function rewritten(headers, authority) {
   const out = { ...headers, host: authority }
@@ -48,10 +49,27 @@ function throttle(log, everyMs) {
   }
 }
 
+/**
+ * Снять ограничения на время.
+ *
+ * Ответ агента печатается минутами, а событийный поток живёт часами. Умолчания
+ * Node рассчитаны на обычные запросы и такое рвут — молча, посреди ответа, что
+ * снаружи выглядит как поломка харнесса. Обратный прокси перед харнессом
+ * настраивают ровно так же, иначе он не годится.
+ */
+function relaxTimeouts(server, streamTimeoutMs) {
+  server.timeout = streamTimeoutMs
+  server.requestTimeout = streamTimeoutMs
+  server.headersTimeout = streamTimeoutMs || 0
+  server.keepAliveTimeout = streamTimeoutMs || 72000
+}
+
 /**
  * @param ctx контекст плагина (нужен ctx.webServer.port)
- * @param options {{host: string, port: number, log: (message: string) => void,
- *                  allow?: object[], tls?: {cert: string, key: string}}}
+ * @param options {{hosts: string[], port: number, log: (message: string) => void,
+ *                  allow?: object[], tls?: {cert: string, key: string},
+ *                  unlockPrivileged?: boolean, privilegedExtra?: string[],
+ *                  streamTimeoutMs?: number}}
  * @returns функция остановки
  */
 export function startDirectBridge(ctx, options) {
@@ -63,6 +81,9 @@ export function startDirectBridge(ctx, options) {
   const authority = '127.0.0.1:' + upstreamPort
   const rules = options.allow ?? []
   const refuse = throttle(options.log, 10000)
+  const streamTimeoutMs = options.streamTimeoutMs ?? 0
+  const unlocked = options.unlockPrivileged !== false
+  const hosts = options.hosts && options.hosts.length ? options.hosts : ['0.0.0.0']
 
   /** Пускать ли этого гостя; отказ пишется в журнал не чаще раза в десять секунд. */
   const welcome = (address) => {
@@ -77,13 +98,26 @@ export function startDirectBridge(ctx, options) {
       res.end('forbidden')
       return
     }
+    if (!unlocked && isPrivileged(req.url, options.privilegedExtra)) {
+      res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' })
+      res.end(REFUSED)
+      return
+    }
+
+    // Ответ идёт кусками столько, сколько нужно: ни своих ограничений, ни
+    // накопления в памяти.
+    req.setTimeout(streamTimeoutMs)
+    res.setTimeout(streamTimeoutMs)
+
     const upstream = http.request({
       host: '127.0.0.1',
       port: upstreamPort,
       method: req.method,
       path: req.url,
       headers: rewritten(req.headers, authority),
+      timeout: streamTimeoutMs || undefined,
     }, (answer) => {
+      answer.setTimeout(streamTimeoutMs)
       res.writeHead(answer.statusCode || 502, answer.headers)
       answer.pipe(res)
     })
@@ -94,14 +128,7 @@ export function startDirectBridge(ctx, options) {
     req.pipe(upstream)
   }
 
-  const bridge = options.tls
-    ? https.createServer({ cert: options.tls.cert, key: options.tls.key }, handle)
-    : http.createServer(handle)
-
-  // Веб-сокеты интерфейса идут через Upgrade: их надо передать сырыми. Проверка
-  // адреса здесь такая же: пропустить веб-сокеты — значит не сделать ничего,
-  // весь разговор с агентом идёт именно по ним.
-  bridge.on('upgrade', (req, socket, head) => {
+  const upgrade = (req, socket, head) => {
     if (!welcome(socket.remoteAddress)) {
       try {
         socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n')
@@ -109,6 +136,11 @@ export function startDirectBridge(ctx, options) {
       } catch (already) { /* уже мертво */ }
       return
     }
+    // Событийный поток живёт часами и молчит между событиями: любой таймаут на
+    // этом сокете рано или поздно оборвёт разговор с агентом.
+    socket.setTimeout(0)
+    socket.setNoDelay(true)
+
     const upstream = http.request({
       host: '127.0.0.1',
       port: upstreamPort,
@@ -117,6 +149,8 @@ export function startDirectBridge(ctx, options) {
       headers: rewritten(req.headers, authority),
     })
     upstream.on('upgrade', (answer, upstreamSocket, upstreamHead) => {
+      upstreamSocket.setTimeout(0)
+      upstreamSocket.setNoDelay(true)
       const lines = ['HTTP/1.1 101 Switching Protocols']
       for (const [key, value] of Object.entries(answer.headers)) lines.push(key + ': ' + value)
       socket.write(lines.join('\r\n') + '\r\n\r\n')
@@ -130,17 +164,42 @@ export function startDirectBridge(ctx, options) {
     upstream.on('error', () => { try { socket.destroy() } catch (already) { /* уже мертво */ } })
     if (head && head.length) upstream.write(head)
     upstream.end()
-  })
+  }
 
-  bridge.on('error', (failure) => {
-    options.log('прямой режим не поднялся: ' + String(failure && failure.message || failure))
-  })
+  const servers = []
+  for (const host of hosts) {
+    const server = options.tls
+      ? https.createServer({ cert: options.tls.cert, key: options.tls.key }, handle)
+      : http.createServer(handle)
+    server.on('upgrade', upgrade)
+    relaxTimeouts(server, streamTimeoutMs)
 
-  bridge.listen(options.port, options.host, () => {
-    options.log('прямой режим: слушаю ' + (options.tls ? 'https://' : 'http://')
-      + options.host + ':' + options.port + ', передаю на ' + authority
-      + (rules.length ? ', пускаю ' + rules.length + ' правил(о) из списка' : ''))
-  })
+    server.on('error', (failure) => {
+      const code = failure && failure.code
+      if (code === 'EADDRINUSE') {
+        options.log('порт ' + options.port + ' на адресе ' + host + ' уже занят. '
+          + 'Либо там уже кто-то обслуживает сеть, либо порт держит посторонний: '
+          + 'смените directPort или освободите его')
+      } else if (code === 'EADDRNOTAVAIL') {
+        options.log('адрес ' + host + ' на этой машине не поднят — пропускаю его')
+      } else {
+        options.log('прямой режим не поднялся на ' + host + ': '
+          + String(failure && failure.message || failure))
+      }
+    })
 
-  return () => { bridge.close() }
+    server.listen(options.port, host, () => {
+      options.log('слушаю ' + (options.tls ? 'https://' : 'http://') + host + ':' + options.port
+        + ', передаю на ' + authority
+        + (rules.length ? ', пускаю ' + rules.length + ' правил(о) из списка' : ', пускаю всех')
+        + (unlocked ? '' : ', привилегированные вызовы закрыты'))
+    })
+    servers.push(server)
+  }
+
+  return () => {
+    for (const server of servers) {
+      try { server.close() } catch (already) { /* уже закрыт */ }
+    }
+  }
 }

package/lib/health.js

@@ -20,6 +20,7 @@ export function hostReport(state) {
     modeReason: state.modeReason ?? '',
     listener: state.listener ?? null,
     tls: state.tls ?? { enabled: false },
+    unlockPrivileged: state.unlockPrivileged ?? null,
     pieces: state.pieces,
     allow: state.allow ?? [],
     assumptions: state.assumptions ?? [],
@@ -39,19 +40,34 @@ const BROWSER_SCRIPT = `
      'интерфейс зовёт его при загрузке; на голом HTTP его подставляет заплатка'],
     ['буфер обмена', !!(navigator.clipboard && navigator.clipboard.writeText),
      'кнопки «копировать»; на голом HTTP его подставляет заплатка'],
-    ['заплатка отработала', !!shim,
+    // Проверять наличие заплатки на ЭТОЙ странице бессмысленно: она вставляется
+    // в страницу интерфейса, а не в нашу, и ответ был бы всегда «нет» — ложная
+    // тревога того сорта, из-за которой потом ищут несуществующую поломку.
+    // Поэтому спрашиваем ту страницу, куда она и вставляется.
+    ['заплатка на странице интерфейса', 'проверяется',
      'если нет — скрипт не попал на страницу или его выключили через ?lanmode=off'],
     ['страница считается своей', /^(localhost|\\[::1\\]|::1|127\\.)/.test(location.hostname),
      'на чужом имени харнесс уводит настройки в режим памяти; это и чинит заплатка']
   ]
-  var rows = checks.map(function (item) {
-    return '<tr><td>' + (item[1] ? '✔' : '✘') + '</td><td>' + item[0] + '</td><td>'
-      + (item[1] ? '' : item[2]) + '</td></tr>'
-  }).join('')
-  out.innerHTML = '<table>' + rows + '</table>'
-  window.__DSH_LANMODE_BROWSER__ = checks.map(function (item) {
-    return { name: item[0], ok: item[1] }
-  })
+  function draw() {
+    out.innerHTML = '<table>' + checks.map(function (item) {
+      var mark = item[1] === 'проверяется' ? '…' : (item[1] ? '✔' : '✘')
+      return '<tr><td>' + mark + '</td><td>' + item[0] + '</td><td>'
+        + (item[1] === true || item[1] === 'проверяется' ? '' : item[2]) + '</td></tr>'
+    }).join('') + '</table>'
+    window.__DSH_LANMODE_BROWSER__ = checks.map(function (item) {
+      return { name: item[0], ok: item[1] }
+    })
+  }
+  draw()
+
+  // Страницу интерфейса спрашиваем отдельно и дорисовываем ответ: она приходит
+  // не мгновенно, а держать из-за неё всю таблицу незачем.
+  var at = checks.findIndex(function (item) { return item[0].indexOf('заплатка') === 0 })
+  fetch('/', { cache: 'no-store' })
+    .then(function (answer) { return answer.text() })
+    .then(function (html) { checks[at][1] = html.indexOf('data-dsh-lanmode') !== -1; draw() })
+    .catch(function () { checks[at][1] = false; draw() })
 })()
 `
 
@@ -71,8 +87,14 @@ function escapeHtml(text) {
 export function healthPage(state) {
   const report = hostReport(state)
   const listener = report.listener
-    ? escapeHtml(report.listener.scheme + '://' + report.listener.host + ':' + report.listener.port)
+    ? escapeHtml(report.listener.hosts.map((host) => report.listener.scheme + '://' + host
+      + ':' + report.listener.port).join(', '))
     : 'нет — сеть обслуживает кто-то другой'
+  const privileged = report.unlockPrivileged === null
+    ? 'не применимо в этом режиме'
+    : (report.unlockPrivileged
+      ? 'ОТКРЫТЫ: настройки и учётные данные доступны любому, кто дотянулся до порта'
+      : 'закрыты: настройки по сети не читаются и не пишутся')
 
   return '<!doctype html><html lang="ru"><head><meta charset="utf-8">'
     + '<meta name="viewport" content="width=device-width, initial-scale=1">'
@@ -94,6 +116,7 @@ export function healthPage(state) {
       : 'нет') + '</dd>'
     + '<dt>подменено</dt><dd>' + escapeHtml(Object.entries(report.pieces)
       .filter(([, on]) => on).map(([name]) => name).join(', ') || 'ничего') + '</dd>'
+    + '<dt>привилегированные вызовы</dt><dd>' + escapeHtml(privileged) + '</dd>'
     + '<dt>пускаю</dt><dd>' + escapeHtml(report.allow.length ? report.allow.join(', ') : 'всех') + '</dd>'
     + '</dl>'
     + '<h2>Точки крепления</h2><table>' + report.assumptions.map(row).join('') + '</table>'

package/lib/index.js

@@ -35,7 +35,9 @@ import { fileURLToPath } from 'node:url'
 
 import { parseAllow } from './access.js'
 import { checkAssumptions, summarize } from './assumptions.js'
+import { bindAddresses } from './bind.js'
 import { startDirectBridge } from './bridge.js'
+import { isPrivileged } from './privileged.js'
 import { healthPage, hostReport } from './health.js'
 import { detectMode } from './mode.js'
 import { ensureCertificate, localAddresses, readCertificate } from './tls.js'
@@ -106,6 +108,27 @@ export const Config = z.object({
       + 'circle, nothing more. Behind a reverse proxy it is meaningless — every request arrives from '
       + 'the proxy.')
     .default([]),
+  unlockPrivileged: z
+    .boolean()
+    .description('mode=direct: let the settings, credentials, agent-preset, path-opening and '
+      + 'model-discovery calls through. The harness pins those to the loopback on purpose, and the '
+      + 'bridge lifts that pin because without it a page on the network can show settings but '
+      + 'neither read nor write them — which is the whole point of this plugin. '
+      + 'The price, stated plainly: any device that reaches this port can read and change your API '
+      + 'keys with no authentication whatsoever. Turn it off for a network you do not trust, and '
+      + 'fill in "allow" either way.')
+    .default(true),
+  privilegedExtra: z
+    .array(z.string())
+    .description('mode=direct: extra path patterns to treat as privileged, for plugins that add '
+      + 'their own loopback-pinned calls. Regular expressions over the request path.')
+    .default([]),
+  streamTimeoutMs: z
+    .number()
+    .description('mode=direct: how long a single request may take. Zero means no limit, and that is '
+      + 'the default: an agent reply is printed over minutes and the event stream lives for hours, '
+      + 'while Node cuts both by default.')
+    .default(0),
   diagnostics: z
     .boolean()
     .description('Serve GET /dsh-lanmode/health: what is patched, which mode is on, and what the '
@@ -190,8 +213,11 @@ function certificateDir(config) {
 
 /** Поднять слушатель прямого режима: сначала сертификат, потом мост. */
 async function raiseListener(ctx, config, state) {
-  const host = config.directHost || '0.0.0.0'
   const port = config.directPort || 3088
+  const { hosts, shared } = bindAddresses(config, ctx.webServer && ctx.webServer.port)
+  if (shared) {
+    say('порт ' + port + ' занят харнессом на петле, поэтому слушаю поимённо: ' + hosts.join(', '))
+  }
   const { rules, dropped } = parseAllow(config.allow)
   if (dropped.length) say('в списке разрешённых не разобраны записи: ' + dropped.join(', '))
 
@@ -226,8 +252,28 @@ async function raiseListener(ctx, config, state) {
     }
   }
 
-  state.listener = { scheme: tls ? 'https' : 'http', host, port }
-  return startDirectBridge(ctx, { host, port, log: say, allow: rules, tls })
+  const unlocked = config.unlockPrivileged !== false
+  if (unlocked) {
+    say('ВНИМАНИЕ: привилегированные вызовы открыты для сети. Настройки, учётные данные '
+      + 'и открытие путей на этой машине доступны ЛЮБОМУ, кто дотянется до порта ' + port
+      + ', без всякой проверки. Так плагин и делает свою работу, но знать об этом надо.')
+    if (rules.length === 0) {
+      say('список разрешённых адресов пуст. Заполните allow — это не пароль, но круг сузит.')
+    }
+  }
+
+  state.listener = { scheme: tls ? 'https' : 'http', hosts, port }
+  state.unlockPrivileged = unlocked
+  return startDirectBridge(ctx, {
+    hosts,
+    port,
+    log: say,
+    allow: rules,
+    tls,
+    unlockPrivileged: unlocked,
+    privilegedExtra: config.privilegedExtra,
+    streamTimeoutMs: config.streamTimeoutMs || 0,
+  })
 }
 
 function start(ctx, config) {
@@ -242,6 +288,7 @@ function start(ctx, config) {
     mode: config.mode,
     modeReason: '',
     listener: null,
+    unlockPrivileged: null,
     tls: { enabled: false },
     pieces,
     allow: Array.isArray(config.allow) ? config.allow : [],

package/lib/privileged.js

@@ -0,0 +1,49 @@
+// Привилегированные вызовы харнесса.
+//
+// Часть методов ядро намеренно держит на петле: настройки, учётные данные,
+// наборы агента, открытие путей на машине, опрос моделей. Забор у них строже
+// обычного — он пропускает только клиента, пришедшего с петли, и никакой
+// список доверенных адресов его не открывает.
+//
+// Мост переписывает Host и Origin на петлю, поэтому для харнесса он и есть
+// клиент с петли. Побочное следствие: привилегированные вызовы открываются
+// тоже. Это и делает прямой режим полноценным — без этого страница по сети
+// показывает настройки, но не может ни прочитать их, ни записать.
+//
+// Плата названа прямо: любое устройство, дотянувшееся до порта, читает и меняет
+// учётные данные без всякой проверки. Поэтому обход управляется отдельной
+// настройкой, о нём говорится при запуске и он виден на странице диагностики.
+
+/**
+ * Пути, которые ядро держит на петле.
+ *
+ * Список ведётся по именам методов, а не по догадкам: каждый из них меняет либо
+ * настройки, либо ключи, либо трогает файловую систему машины.
+ */
+export const PRIVILEGED = [
+  /^\/api\/settings\.(describe|openDocument|update|replace|mutate)$/,
+  /^\/api\/credentials\.(describe|set|unset)$/,
+  /^\/api\/agentPreset\.(read|copy|openDocument|remove)$/,
+  /^\/api\/host\.(pickDirectory|openPath)$/,
+  /^\/api\/llm\.discoverModels$/,
+]
+
+/** Привилегированный ли это путь. */
+export function isPrivileged(url, extra) {
+  const path = String(url ?? '').split('?')[0]
+  if (!path) return false
+  for (const rule of PRIVILEGED) if (rule.test(path)) return true
+  for (const rule of extra ?? []) {
+    try {
+      if (new RegExp(rule).test(path)) return true
+    } catch (badPattern) {
+      // Кривое выражение в настройках не должно ронять мост: считаем, что
+      // такого правила нет, а о разборе жалуется тот, кто их читает.
+    }
+  }
+  return false
+}
+
+/** Что сказать человеку, когда обход выключен, а вызов пришёл. */
+export const REFUSED = 'dsh-lanmode: этот вызов ядро держит на петле. '
+  + 'Включите unlockPrivileged, если сознательно открываете настройки и ключи сети.'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-lanmode",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "LAN and reverse-proxy access for the DeepSeek Harness Web UI: returns the settings service on pages that are not localhost, fills in the Web APIs the browser withholds on plain HTTP, and can open a listener of its own so nothing else is needed.",
   "license": "MIT",
   "type": "module",