@goodandready/dsh-lanmode 0.4.0 → 0.5.0

package/README.md

@@ -58,7 +58,7 @@ bind(spec) {
 ```yaml
 - id: dsh-lanmode
   config:
-    mode: proxy        # proxy | direct
+    mode: proxy        # proxy | direct | auto
 ```
 
 **`proxy`** (default) — something already listens on the network in front of the harness: nginx, Caddy, Tailscale serve, an SSH tunnel. The plugin only repairs the page and touches nothing else. This is the safe default: it cannot collide with whatever you already run.
@@ -77,17 +77,127 @@ Then open `http://<the machine's IP>:3088` from any device on the network.
 
 A listener rather than rebinding the harness itself, for two reasons: a bind host lives in the config tree and cannot be a switch inside the plugin, and rebinding to `0.0.0.0` collides with a reverse proxy already holding that port.
 
+**`auto`** — work it out. The plugin knocks on this machine's own network
+addresses at the harness port: the harness itself listens on loopback only, so
+anything answering there is a proxy, and the mode is `proxy`. When nothing
+answers and the direct port is free, it is `direct`. When it cannot tell — no
+addresses, no known port, a probe that errored — it picks `proxy` and opens
+nothing: an unnecessary listener on a network address is an open door, and one
+is not opened on a guess.
+
+What `auto` cannot see is a proxy sitting on a *different* port. From outside
+that is indistinguishable from nobody being there, and the plugin would open its
+own listener beside it. Set the mode by hand in that case.
+
+The decision is logged with its reason and shown on the diagnostics page.
+
 Changing the mode takes effect on restart.
 
+## HTTPS, and the microphone
+
+This is the one thing no substitution can repair. A browser hands out
+`navigator.mediaDevices` only over a secure connection, and behind it is a real
+device — there is nothing to fake. Over plain HTTP on a network address, voice
+input is impossible in principle.
+
+So the direct-mode listener can speak HTTPS:
+
+```yaml
+- id: dsh-lanmode
+  config:
+    mode: direct
+    tls: self-signed     # off | self-signed | files
+```
+
+**`self-signed`** — the plugin issues a certificate itself and keeps it in
+`tlsDir` (by default a folder next to the harness data). It goes into the
+certificate with every address this machine answers on, plus anything in
+`tlsHosts`: a certificate issued for one name is refused for every other, even
+after it has been accepted once. It is reissued when it is about to expire or
+when a new address appears. The fingerprint is printed to the log at startup —
+compare it in the browser instead of accepting blindly.
+
+Issuing needs `openssl` on the machine. Without it the plugin says so plainly
+and falls back to plain HTTP rather than pretending everything is fine.
+
+**`files`** — your own certificate:
+
+```yaml
+    tls: files
+    tlsCert: /path/to/cert.pem
+    tlsKey: /path/to/key.pem
+```
+
+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.
+
+## Who may connect
+
+The direct listener has no password and will not get one: the plugin does not
+intercept anyone else's routes, and inventing its own way into the harness is
+not its business. But between "no password" and "anyone on the network" there is
+room:
+
+```yaml
+- id: dsh-lanmode
+  config:
+    mode: direct
+    allow:
+      - 192.168.1.0/24
+      - 10.0.0.5
+```
+
+Addresses and CIDR ranges, IPv4 and IPv6. An empty list means everyone, which is
+how the plugin behaves until you fill it in. Refused connections are logged, at
+a limited rate so a scanner cannot drown the log.
+
+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.
+
+## Diagnostics
+
+`GET /dsh-lanmode/health` — one page answering the questions that otherwise take
+half an hour: which mode is on and why, what is patched, whether the browser
+considers the connection secure, and why the microphone is silent. Add
+`?format=json` for the same data in a form you can paste into a bug report.
+
+Half the answers can only come from the browser — a secure connection and a
+microphone exist nowhere else — so the page checks those in the browser that
+opened it.
+
+Nothing secret is on that page: it is open to anyone who reached the harness.
+Turn it off with `diagnostics: false`.
+
+## When the harness changes underneath
+
+The plugin holds on to the harness's internals: the index tap, the name of the
+package the substitution must leave alone, the shape of the connection object.
+An upgrade can move any of them, and a plugin that repairs someone else's
+behaviour must not fail quietly — that already happened once, and it took days
+of confusing symptoms to notice.
+
+So at startup it checks its own assumptions and says what it found: one line
+when everything is in place, a loud complaint naming what moved when it is not.
+The same list is on the diagnostics page.
+
 ## Settings
 
 All of it can be edited as the `dsh-lanmode` namespace — in `$DSH_HOME/settings.yaml`, or from the UI once the settings pages work.
 
 | Setting | Default | Meaning |
 |---|---|---|
-| `mode` | `proxy` | `proxy` or `direct` |
+| `mode` | `proxy` | `proxy`, `direct` or `auto` |
 | `directHost` | `0.0.0.0` | `direct`: which address to listen on |
 | `directPort` | `3088` | `direct`: which port to listen on |
+| `tls` | `off` | `direct`: `off`, `self-signed` or `files` — what the microphone hangs on |
+| `tlsDir` | — | `self-signed`: where the issued certificate is kept |
+| `tlsHosts` | `[]` | `self-signed`: extra names and addresses for the certificate |
+| `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 |
+| `diagnostics` | `true` | serve `GET /dsh-lanmode/health` |
 | `settings` | `true` | return the settings service |
 | `randomUuid` | `true` | provide `crypto.randomUUID` on plain HTTP |
 | `clipboard` | `true` | provide a clipboard fallback on plain HTTP |

package/lib/access.js

@@ -0,0 +1,156 @@
+// Кого пускать в прямом режиме.
+//
+// Пароля здесь нет и не будет: плагин чужие маршруты не перехватывает, а
+// придумывать свой вход в харнесс — не его дело. Но между «без пароля» и «кто
+// угодно из сети» есть промежуток, и список разрешённых адресов его занимает.
+//
+// Разбор записи CIDR свой, без зависимостей: адрес превращается в набор байтов,
+// и сравниваются первые N бит. Для IPv4 и IPv6 это одна и та же арифметика,
+// разной длины.
+
+/** Байты адреса IPv4, или `null`, если это не он. */
+function ipv4Bytes(text) {
+  const parts = text.split('.')
+  if (parts.length !== 4) return null
+  const bytes = []
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part)) return null
+    const value = Number(part)
+    if (value > 255) return null
+    bytes.push(value)
+  }
+  return bytes
+}
+
+/**
+ * Байты адреса IPv6, или `null`.
+ *
+ * Отдельно разбирается запись с хвостом IPv4 (`::ffff:192.168.1.5`): именно её
+ * отдаёт Node для обычных подключений на сокете двойного стека, и без неё
+ * список разрешённых адресов не сработал бы вовсе.
+ */
+function ipv6Bytes(text) {
+  let body = text
+  let tail = []
+  const dot = body.lastIndexOf(':')
+  if (body.includes('.')) {
+    const four = ipv4Bytes(body.slice(dot + 1))
+    if (!four) return null
+    tail = four
+    body = body.slice(0, dot + 1) + '0:0'
+  }
+
+  const halves = body.split('::')
+  if (halves.length > 2) return null
+  const head = halves[0] ? halves[0].split(':') : []
+  const rest = halves.length === 2 ? (halves[1] ? halves[1].split(':') : []) : []
+  if (halves.length === 1 && head.length !== 8) return null
+
+  const groups = []
+  for (const group of head) {
+    if (!/^[0-9a-fA-F]{1,4}$/.test(group)) return null
+    groups.push(Number.parseInt(group, 16))
+  }
+  const restGroups = []
+  for (const group of rest) {
+    if (!/^[0-9a-fA-F]{1,4}$/.test(group)) return null
+    restGroups.push(Number.parseInt(group, 16))
+  }
+  const missing = 8 - groups.length - restGroups.length
+  if (missing < 0) return null
+  const all = halves.length === 2
+    ? groups.concat(new Array(missing).fill(0), restGroups)
+    : groups
+
+  const bytes = []
+  for (const group of all) bytes.push(group >> 8, group & 255)
+  if (tail.length) {
+    bytes.splice(12, 4, ...tail)
+  }
+  return bytes.length === 16 ? bytes : null
+}
+
+/** Байты адреса — или `null`, если разобрать не вышло. */
+export function addressBytes(text) {
+  const clean = String(text ?? '').trim()
+  if (!clean) return null
+  if (clean.includes(':')) return ipv6Bytes(clean)
+  return ipv4Bytes(clean)
+}
+
+/**
+ * Адрес IPv4, спрятанный внутри записи IPv6.
+ *
+ * `::ffff:192.168.1.5` — это тот же 192.168.1.5, и правило, написанное для
+ * IPv4, обязано на него распространяться. Иначе список выглядит рабочим, а
+ * пускает мимо.
+ */
+function unwrapped(bytes) {
+  if (!bytes || bytes.length !== 16) return null
+  for (let i = 0; i < 10; i++) if (bytes[i] !== 0) return null
+  if (bytes[10] !== 255 || bytes[11] !== 255) return null
+  return bytes.slice(12)
+}
+
+/**
+ * Разобрать одну запись списка: адрес или подсеть в записи CIDR.
+ *
+ * @returns `{ bytes, bits }` или `null`, если запись непонятна.
+ */
+export function parseRule(text) {
+  const clean = String(text ?? '').trim()
+  if (!clean) return null
+  const slash = clean.lastIndexOf('/')
+  const address = slash === -1 ? clean : clean.slice(0, slash)
+  const bytes = addressBytes(address)
+  if (!bytes) return null
+
+  const full = bytes.length * 8
+  if (slash === -1) return { bytes, bits: full }
+  const bits = Number(clean.slice(slash + 1))
+  if (!Number.isInteger(bits) || bits < 0 || bits > full) return null
+  return { bytes, bits }
+}
+
+/** Разобрать весь список, молча отбрасывая непонятные записи. */
+export function parseAllow(list) {
+  const rules = []
+  const dropped = []
+  for (const item of Array.isArray(list) ? list : []) {
+    const rule = parseRule(item)
+    if (rule) rules.push(rule)
+    else if (String(item ?? '').trim()) dropped.push(String(item))
+  }
+  return { rules, dropped }
+}
+
+/** Совпадают ли первые `bits` бит. */
+function samePrefix(left, right, bits) {
+  if (left.length !== right.length) return false
+  const whole = bits >> 3
+  for (let i = 0; i < whole; i++) if (left[i] !== right[i]) return false
+  const spare = bits & 7
+  if (spare === 0) return true
+  const mask = (255 << (8 - spare)) & 255
+  return (left[whole] & mask) === (right[whole] & mask)
+}
+
+/**
+ * Пускать ли этот адрес.
+ *
+ * Пустой список означает «никого не ограничиваем» — так плагин ведёт себя до
+ * того, как список задали, и так же, если задали одну мусорную строку: тихо
+ * запереть дверь из-за опечатки хуже, чем не запирать вовсе.
+ */
+export function allowed(address, rules) {
+  if (!Array.isArray(rules) || rules.length === 0) return true
+  const bytes = addressBytes(address)
+  if (!bytes) return false
+  const inner = unwrapped(bytes)
+
+  for (const rule of rules) {
+    if (samePrefix(bytes, rule.bytes, rule.bits)) return true
+    if (inner && rule.bytes.length === 4 && samePrefix(inner, rule.bytes, rule.bits)) return true
+  }
+  return false
+}

package/lib/assumptions.js

@@ -0,0 +1,76 @@
+// Проверка точек крепления.
+//
+// Плагин чинит чужое поведение и держится за внутренности харнесса: за точку
+// вставки в index.html, за то, что вставка доезжает до отдаваемой страницы, и
+// за имя пакета, который заплатка обязана обходить стороной. Любая из точек
+// может уехать с обновлением ядра.
+//
+// Так уже было: подмена доходила до настроек ядра, но не до разделов плагинов,
+// и это выяснилось не сразу, а через несколько дней жалоб на пустые карточки.
+// Тихий отказ здесь хуже поломки — поэтому плагин проверяет свои допущения сам
+// и жалуется громко.
+
+/** Пакет, которому заплатка обязана оставлять настоящий ответ. */
+export const EXCLUDED_BUNDLE = '@deepseek-ai/dsh-client-ui-deliverables'
+
+/** Один вывод проверки. */
+function verdict(name, ok, detail) {
+  return { name, ok, detail }
+}
+
+/**
+ * Проверить всё, что можно проверить со стороны хоста.
+ *
+ * Со стороны браузера проверяет страница диагностики: то, что происходит в нём,
+ * отсюда не видно, а гадать — то же самое, что не проверять.
+ *
+ * @param options {{webServer: object, fetchIndex: () => Promise<string>}}
+ */
+export async function checkAssumptions(options) {
+  const results = []
+  const webServer = options.webServer
+
+  results.push(verdict(
+    'точка вставки в index.html',
+    Boolean(webServer && typeof webServer.tapIndex === 'function'),
+    'webServer.tapIndex — то, чем плагин вставляет заплатку на страницу',
+  ))
+
+  results.push(verdict(
+    'порт харнесса известен',
+    Boolean(webServer && webServer.port),
+    'webServer.port — без него не поднять прямой режим и не проверить, кто слушает сеть',
+  ))
+
+  let html = ''
+  try {
+    html = await options.fetchIndex()
+  } catch (unreachable) {
+    results.push(verdict('страница отдаётся', false, String(unreachable.message || unreachable)))
+    return results
+  }
+
+  results.push(verdict(
+    'заплатка попала на страницу',
+    html.includes('data-dsh-lanmode'),
+    'если её там нет, всё остальное не имеет значения',
+  ))
+
+  results.push(verdict(
+    'исключение на месте',
+    html.includes(EXCLUDED_BUNDLE),
+    'пакет ' + EXCLUDED_BUNDLE + ' обходится стороной, потому что решает, можно ли '
+      + 'открыть файл локально. Исчез или переименован — исключение больше ничего не исключает',
+  ))
+
+  return results
+}
+
+/** Свести проверки в одну строку для журнала. */
+export function summarize(results) {
+  const bad = results.filter((item) => !item.ok)
+  if (bad.length === 0) return 'точки крепления на месте: ' + results.length + ' из ' + results.length
+  return 'ТОЧКИ КРЕПЛЕНИЯ УЕХАЛИ (' + bad.length + ' из ' + results.length + '): '
+    + bad.map((item) => item.name).join('; ')
+    + '. Плагин может работать не так, как задумано, — вероятно, обновилось ядро'
+}

package/lib/bridge.js

@@ -1,92 +1,146 @@
-// Прямой режим: слушатель на сетевом адресе, который передаёт всё харнессу.
-//
-// Зачем не привязка харнесса к 0.0.0.0, как делают соседние плагины. Привязка
-// задаётся в дереве конфигурации и меняется только перезапуском, то есть
-// «переключателем в плагине» быть не может. Хуже того, если перед харнессом
-// уже стоит обратный прокси на том же порту, привязка столкнётся с ним лбами.
-// Отдельный слушатель включается и гасится вместе со строкой плагина и живёт
-// рядом с любым прокси.
-//
-// Заголовки Host и Origin переписываются на локальные: харнесс пропускает
-// запрос, только когда Origin совпадает с адресом, по которому он слушает.
-// Это ровно то, что делает любой обратный прокси, и это же означает, что
-// прямой режим открывает харнесс всем, кто дотянется до этого порта, — как и
-// nginx сегодня. Пароля здесь нет и быть не может: плагин чужие маршруты не
-// перехватывает.
-
-import http from 'node:http'
-
-function rewritten(headers, authority) {
-  const out = { ...headers, host: authority }
-  if (out.origin) out.origin = 'http://' + authority
-  if (out.referer) out.referer = String(out.referer).replace(/^https?:\/\/[^/]+/, 'http://' + authority)
-  return out
-}
-
-/**
- * @param ctx контекст плагина (нужен ctx.webServer.port)
- * @param options {{host: string, port: number, log: (message: string) => void}}
- * @returns функция остановки
- */
-export function startDirectBridge(ctx, options) {
-  const upstreamPort = ctx.webServer.port
-  if (!upstreamPort) {
-    options.log('прямой режим не поднят: веб-сервер ещё не сообщил порт')
-    return () => {}
-  }
-  const authority = '127.0.0.1:' + upstreamPort
-
-  const bridge = http.createServer((req, res) => {
-    const upstream = http.request({
-      host: '127.0.0.1',
-      port: upstreamPort,
-      method: req.method,
-      path: req.url,
-      headers: rewritten(req.headers, authority),
-    }, (answer) => {
-      res.writeHead(answer.statusCode || 502, answer.headers)
-      answer.pipe(res)
-    })
-    upstream.on('error', () => {
-      if (!res.headersSent) res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' })
-      res.end('dsh-lanmode: харнесс не отвечает')
-    })
-    req.pipe(upstream)
-  })
-
-  // Веб-сокеты интерфейса идут через Upgrade: их надо передать сырыми.
-  bridge.on('upgrade', (req, socket, head) => {
-    const upstream = http.request({
-      host: '127.0.0.1',
-      port: upstreamPort,
-      method: req.method,
-      path: req.url,
-      headers: rewritten(req.headers, authority),
-    })
-    upstream.on('upgrade', (answer, upstreamSocket, upstreamHead) => {
-      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')
-      if (upstreamHead && upstreamHead.length) socket.unshift(upstreamHead)
-      upstreamSocket.pipe(socket)
-      socket.pipe(upstreamSocket)
-      const drop = () => { try { upstreamSocket.destroy() } catch (already) { /* уже мертво */ } }
-      socket.on('error', drop)
-      socket.on('close', drop)
-    })
-    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))
-  })
-
-  bridge.listen(options.port, options.host, () => {
-    options.log('прямой режим: слушаю ' + options.host + ':' + options.port
-      + ', передаю на ' + authority)
-  })
-
-  return () => { bridge.close() }
-}
+// Прямой режим: слушатель на сетевом адресе, который передаёт всё харнессу.
+//
+// Зачем не привязка харнесса к 0.0.0.0, как делают соседние плагины. Привязка
+// задаётся в дереве конфигурации и меняется только перезапуском, то есть
+// «переключателем в плагине» быть не может. Хуже того, если перед харнессом
+// уже стоит обратный прокси на том же порту, привязка столкнётся с ним лбами.
+// Отдельный слушатель включается и гасится вместе со строкой плагина и живёт
+// рядом с любым прокси.
+//
+// Заголовки Host и Origin переписываются на локальные: харнесс пропускает
+// запрос, только когда Origin совпадает с адресом, по которому он слушает.
+// Это ровно то, что делает любой обратный прокси.
+//
+// Кого пускать — решает список разрешённых адресов, если он задан. Это не
+// замена паролю: тот, кто в списке, входит без всякой проверки. Это сужение
+// круга, и в описании плагина так и сказано.
+
+import http from 'node:http'
+import https from 'node:https'
+
+import { allowed } from './access.js'
+
+function rewritten(headers, authority) {
+  const out = { ...headers, host: authority }
+  if (out.origin) out.origin = 'http://' + authority
+  if (out.referer) out.referer = String(out.referer).replace(/^https?:\/\/[^/]+/, 'http://' + authority)
+  return out
+}
+
+/**
+ * Ограничитель частоты жалоб.
+ *
+ * Сканер из сети даёт сотни отказов в минуту, и без ограничения журнал
+ * превращается в поток одинаковых строк, в котором не видно ничего другого.
+ */
+function throttle(log, everyMs) {
+  let last = 0
+  let skipped = 0
+  return (message) => {
+    const now = Date.now()
+    if (now - last < everyMs) {
+      skipped += 1
+      return
+    }
+    log(skipped ? message + ' (и ещё ' + skipped + ' таких же)' : message)
+    last = now
+    skipped = 0
+  }
+}
+
+/**
+ * @param ctx контекст плагина (нужен ctx.webServer.port)
+ * @param options {{host: string, port: number, log: (message: string) => void,
+ *                  allow?: object[], tls?: {cert: string, key: string}}}
+ * @returns функция остановки
+ */
+export function startDirectBridge(ctx, options) {
+  const upstreamPort = ctx.webServer.port
+  if (!upstreamPort) {
+    options.log('прямой режим не поднят: веб-сервер ещё не сообщил порт')
+    return () => {}
+  }
+  const authority = '127.0.0.1:' + upstreamPort
+  const rules = options.allow ?? []
+  const refuse = throttle(options.log, 10000)
+
+  /** Пускать ли этого гостя; отказ пишется в журнал не чаще раза в десять секунд. */
+  const welcome = (address) => {
+    if (allowed(address, rules)) return true
+    refuse('отказано: адрес ' + String(address) + ' не в списке разрешённых')
+    return false
+  }
+
+  const handle = (req, res) => {
+    if (!welcome(req.socket.remoteAddress)) {
+      res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' })
+      res.end('forbidden')
+      return
+    }
+    const upstream = http.request({
+      host: '127.0.0.1',
+      port: upstreamPort,
+      method: req.method,
+      path: req.url,
+      headers: rewritten(req.headers, authority),
+    }, (answer) => {
+      res.writeHead(answer.statusCode || 502, answer.headers)
+      answer.pipe(res)
+    })
+    upstream.on('error', () => {
+      if (!res.headersSent) res.writeHead(502, { 'content-type': 'text/plain; charset=utf-8' })
+      res.end('dsh-lanmode: харнесс не отвечает')
+    })
+    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) => {
+    if (!welcome(socket.remoteAddress)) {
+      try {
+        socket.write('HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n')
+        socket.destroy()
+      } catch (already) { /* уже мертво */ }
+      return
+    }
+    const upstream = http.request({
+      host: '127.0.0.1',
+      port: upstreamPort,
+      method: req.method,
+      path: req.url,
+      headers: rewritten(req.headers, authority),
+    })
+    upstream.on('upgrade', (answer, upstreamSocket, upstreamHead) => {
+      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')
+      if (upstreamHead && upstreamHead.length) socket.unshift(upstreamHead)
+      upstreamSocket.pipe(socket)
+      socket.pipe(upstreamSocket)
+      const drop = () => { try { upstreamSocket.destroy() } catch (already) { /* уже мертво */ } }
+      socket.on('error', drop)
+      socket.on('close', drop)
+    })
+    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))
+  })
+
+  bridge.listen(options.port, options.host, () => {
+    options.log('прямой режим: слушаю ' + (options.tls ? 'https://' : 'http://')
+      + options.host + ':' + options.port + ', передаю на ' + authority
+      + (rules.length ? ', пускаю ' + rules.length + ' правил(о) из списка' : ''))
+  })
+
+  return () => { bridge.close() }
+}

package/lib/health.js

@@ -0,0 +1,104 @@
+// Страница диагностики.
+//
+// Каждый разбор поломки по сети начинался одинаково: непонятно, какой режим,
+// что подменено, видит ли браузер защищённое соединение и почему молчит
+// микрофон. Это выяснялось руками и подолгу.
+//
+// Половину ответов знает хост, половину — только браузер, потому что защищённое
+// соединение и наличие микрофона существуют исключительно на его стороне.
+// Поэтому страница отдаёт и то и другое: серверное как есть, браузерное —
+// скриптом, который выполняется у открывшего.
+//
+// Ничего секретного здесь быть не должно: страница открыта всем, кто дотянулся
+// до харнесса.
+
+/** Данные, которые знает хост. */
+export function hostReport(state) {
+  return {
+    version: state.version,
+    mode: state.mode,
+    modeReason: state.modeReason ?? '',
+    listener: state.listener ?? null,
+    tls: state.tls ?? { enabled: false },
+    pieces: state.pieces,
+    allow: state.allow ?? [],
+    assumptions: state.assumptions ?? [],
+  }
+}
+
+const BROWSER_SCRIPT = `
+(function () {
+  var out = document.getElementById('browser')
+  var shim = window.__DSH_LANMODE__ || null
+  var checks = [
+    ['защищённое соединение', window.isSecureContext === true,
+     'без него нет ни микрофона, ни crypto.randomUUID, ни буфера обмена. Лечится HTTPS: настройка tls в прямом режиме или прокси с сертификатом'],
+    ['микрофон доступен браузеру', !!(navigator.mediaDevices && navigator.mediaDevices.getUserMedia),
+     'единственное, чего не лечит подмена: за ним настоящее устройство. Нужен именно HTTPS'],
+    ['crypto.randomUUID', typeof (window.crypto && window.crypto.randomUUID) === 'function',
+     'интерфейс зовёт его при загрузке; на голом 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 row(item) {
+  return '<tr><td>' + (item.ok ? '✔' : '✘') + '</td><td>' + escapeHtml(item.name)
+    + '</td><td>' + (item.ok ? '' : escapeHtml(item.detail || '')) + '</td></tr>'
+}
+
+function escapeHtml(text) {
+  return String(text)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+/** Страница целиком. */
+export function healthPage(state) {
+  const report = hostReport(state)
+  const listener = report.listener
+    ? escapeHtml(report.listener.scheme + '://' + report.listener.host + ':' + report.listener.port)
+    : 'нет — сеть обслуживает кто-то другой'
+
+  return '<!doctype html><html lang="ru"><head><meta charset="utf-8">'
+    + '<meta name="viewport" content="width=device-width, initial-scale=1">'
+    + '<title>dsh-lanmode</title><style>'
+    + 'body{font:14px/1.5 system-ui,sans-serif;margin:0;padding:24px;max-width:900px}'
+    + 'h1{font-size:20px;margin:0 0 4px}h2{font-size:15px;margin:24px 0 8px}'
+    + 'table{border-collapse:collapse;width:100%}'
+    + 'td{padding:4px 8px;border-top:1px solid rgba(128,128,128,.3);vertical-align:top}'
+    + 'td:first-child{width:1.5em;text-align:center}td:nth-child(2){width:16em}'
+    + 'td:nth-child(3){color:#888}dl{margin:0}dt{color:#888;font-size:12px;margin-top:8px}'
+    + '@media(prefers-color-scheme:dark){body{background:#111;color:#ddd}}'
+    + '</style></head><body>'
+    + '<h1>dsh-lanmode ' + escapeHtml(report.version) + '</h1>'
+    + '<dl><dt>режим</dt><dd>' + escapeHtml(report.mode)
+    + (report.modeReason ? ' — ' + escapeHtml(report.modeReason) : '') + '</dd>'
+    + '<dt>слушатель</dt><dd>' + listener + '</dd>'
+    + '<dt>сертификат</dt><dd>' + (report.tls.enabled
+      ? escapeHtml(report.tls.source + ', отпечаток ' + report.tls.fingerprint)
+      : 'нет') + '</dd>'
+    + '<dt>подменено</dt><dd>' + escapeHtml(Object.entries(report.pieces)
+      .filter(([, on]) => on).map(([name]) => name).join(', ') || 'ничего') + '</dd>'
+    + '<dt>пускаю</dt><dd>' + escapeHtml(report.allow.length ? report.allow.join(', ') : 'всех') + '</dd>'
+    + '</dl>'
+    + '<h2>Точки крепления</h2><table>' + report.assumptions.map(row).join('') + '</table>'
+    + '<h2>Что видит браузер</h2><div id="browser"></div>'
+    + '<h2>Для отчёта об ошибке</h2><p>Те же данные в JSON: '
+    + '<a href="?format=json">?format=json</a></p>'
+    + '<script>' + BROWSER_SCRIPT + '</script></body></html>'
+}

package/lib/index.js

@@ -32,7 +32,13 @@ import z from '@deepseek-ai/schemastery'
 import { readFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+
+import { parseAllow } from './access.js'
+import { checkAssumptions, summarize } from './assumptions.js'
 import { startDirectBridge } from './bridge.js'
+import { healthPage, hostReport } from './health.js'
+import { detectMode } from './mode.js'
+import { ensureCertificate, localAddresses, readCertificate } from './tls.js'
 
 export const name = 'dsh-lanmode'
 export const inject = ['webServer']
@@ -44,7 +50,10 @@ export const Config = z.object({
       + '"proxy": something in front of it already listens on the network (nginx and friends) — '
       + 'the plugin only repairs the page. '
       + '"direct": the plugin also opens a listener of its own on the network and forwards to the '
-      + 'harness, so nothing else is needed.')
+      + 'harness, so nothing else is needed. '
+      + '"auto": look whether anything already answers on this machine\'s network address at the '
+      + 'harness port, and pick proxy if something does. When it cannot tell, it picks proxy: '
+      + 'an unnecessary listener on a network address is an open door, and one is not opened on a guess.')
     .default('proxy'),
   directHost: z
     .string()
@@ -69,6 +78,40 @@ export const Config = z.object({
     .description('Provide a fallback for navigator.clipboard.writeText on plain HTTP, '
       + 'so the copy buttons keep working. A no-op where the real one exists.')
     .default(true),
+  tls: z
+    .string()
+    .description('mode=direct: how the listener is secured. "off" — plain HTTP, as before. '
+      + '"self-signed" — the plugin issues a certificate itself (needs openssl) and renews it. '
+      + '"files" — use tlsCert and tlsKey. '
+      + 'This is what the microphone hangs on: a browser hands out navigator.mediaDevices only over '
+      + 'a secure connection, and no page-side substitution can help — there is a real device behind it.')
+    .default('off'),
+  tlsDir: z
+    .string()
+    .description('tls=self-signed: where the issued certificate is kept. '
+      + 'Empty uses a folder next to the harness data.')
+    .default(''),
+  tlsHosts: z
+    .array(z.string())
+    .description('tls=self-signed: extra names and addresses to put into the certificate, '
+      + 'on top of this machine\'s own. A certificate issued for one name is refused for every other, '
+      + 'even after it has been accepted once.')
+    .default([]),
+  tlsCert: z.string().description('tls=files: path to the certificate in PEM.').default(''),
+  tlsKey: z.string().description('tls=files: path to the private key in PEM.').default(''),
+  allow: z
+    .array(z.string())
+    .description('mode=direct: who may connect — addresses and CIDR ranges. Empty means everyone, '
+      + 'as before. This is not a password: whoever is on the list gets in unchecked. It narrows the '
+      + 'circle, nothing more. Behind a reverse proxy it is meaningless — every request arrives from '
+      + 'the proxy.')
+    .default([]),
+  diagnostics: z
+    .boolean()
+    .description('Serve GET /dsh-lanmode/health: what is patched, which mode is on, and what the '
+      + 'browser actually sees. Nothing secret is on that page — it is open to anyone who reached '
+      + 'the harness.')
+    .default(true),
 })
 
 const here = path.dirname(fileURLToPath(import.meta.url))
@@ -81,9 +124,36 @@ function shimSource() {
 /** Namespace, который плагин объявляет: через него режим правится настройками. */
 const NS = 'dsh-lanmode'
 
+/** Версия из манифеста: она нужна странице диагностики и отчётам об ошибках. */
+function version() {
+  try {
+    return JSON.parse(readFileSync(path.join(here, '..', 'package.json'), 'utf8')).version
+  } catch (unreadable) {
+    return 'неизвестна'
+  }
+}
+
+const say = (message) => {
+  // eslint-disable-next-line no-console
+  console.info('[dsh-lanmode] ' + message)
+}
+
 export function apply(ctx, config) {
-  // Значения берём из сервиса настроек, если он есть: тогда режим правится
-  // в настройках, а не только в дереве плагинов. Смена режима требует
+  // Запуск ровно один. Раньше их было два: путь со службой настроек и путь без
+  // неё срабатывали оба, потому что в момент проверки службы ещё не было. С
+  // одной только вставкой заплатки это сходило с рук — она защищена от повтора.
+  // С появлением слушателя, списка адресов и страницы диагностики перестало:
+  // страница показывала одно состояние, а мост работал по другому.
+  let started = false
+
+  const once = (usingCtx, effective) => {
+    if (started) return
+    started = true
+    start(usingCtx, effective)
+  }
+
+  // Значения берём из службы настроек, если она есть: тогда режим правится в
+  // настройках, а не только в дереве плагинов. Смена режима требует
   // перезапуска — слушатель поднимается один раз при старте.
   ctx.inject(['settings'], (sctx) => {
     let effective = config
@@ -93,34 +163,159 @@ export function apply(ctx, config) {
     } catch (alreadyRegistered) {
       effective = config
     }
-    start(sctx, effective)
+    once(sctx, effective)
   })
 
-  // Без сервиса настроек тоже должно работать — тогда только дерево плагинов.
+  // Без службы настроек тоже должно работать — тогда только дерево плагинов.
+  // Ждём: службы может не быть вовсе, а может не быть ещё. Различить это можно
+  // только временем, и лучше подождать, чем запуститься не тем набором.
   ctx.effect(() => {
-    if (ctx.get && ctx.get('settings')) return () => {}
-    start(ctx, config)
-    return () => {}
-  }, 'dsh-lanmode: запуск без сервиса настроек')
+    const timer = setTimeout(() => once(ctx, config), 2000)
+    return () => clearTimeout(timer)
+  }, 'dsh-lanmode: запуск без службы настроек')
 }
 
-function start(ctx, config) {
-  // Прямой режим: свой слушатель на сетевом адресе. В режиме прокси не
-  // поднимаем ничего — сеть уже обслуживает кто-то другой.
-  if (config.mode === 'direct') {
-    ctx.effect(() => startDirectBridge(ctx, {
-      host: config.directHost || '0.0.0.0',
-      port: config.directPort || 3088,
-      // eslint-disable-next-line no-console
-      log: (message) => console.info('[dsh-lanmode] ' + message),
-    }), 'dsh-lanmode: слушатель прямого режима')
+/**
+ * Куда складывать выпущенный сертификат.
+ *
+ * Рядом с прочими данными харнесса, если он сказал где; иначе — куда указал
+ * человек. Своего пути плагин не выдумывает: писать в неизвестное место чужой
+ * машины он не вправе.
+ */
+function certificateDir(config) {
+  if (config.tlsDir) return config.tlsDir
+  const home = process.env.DSH_HOME
+  return home ? path.join(home, 'dsh-lanmode') : ''
+}
+
+/** Поднять слушатель прямого режима: сначала сертификат, потом мост. */
+async function raiseListener(ctx, config, state) {
+  const host = config.directHost || '0.0.0.0'
+  const port = config.directPort || 3088
+  const { rules, dropped } = parseAllow(config.allow)
+  if (dropped.length) say('в списке разрешённых не разобраны записи: ' + dropped.join(', '))
+
+  let tls = null
+  if (config.tls === 'files') {
+    try {
+      tls = readCertificate(config.tlsCert, config.tlsKey)
+      state.tls = { enabled: true, source: 'свой сертификат', fingerprint: tls.fingerprint }
+    } catch (unreadable) {
+      say('сертификат не прочитан (' + String(unreadable.message || unreadable)
+        + ') — поднимаю без защищённого соединения, микрофон работать не будет')
+    }
+  } else if (config.tls === 'self-signed') {
+    const dir = certificateDir(config)
+    if (!dir) {
+      say('некуда положить сертификат: задайте tlsDir — поднимаю без защищённого соединения')
+    } else {
+      try {
+        const hosts = [...new Set([...(config.tlsHosts ?? []), ...localAddresses()])]
+        const made = await ensureCertificate({ dir, hosts, log: say })
+        tls = made
+        state.tls = { enabled: true, source: 'самоподписанный', fingerprint: made.fingerprint }
+        say((made.issued ? 'выпущен' : 'взят') + ' сертификат на ' + hosts.length
+          + ' имён, отпечаток ' + made.fingerprint)
+        say('браузер предупредит о нём один раз: сверьте отпечаток и подтвердите')
+      } catch (failed) {
+        say('сертификат не выпущен (' + String(failed.message || failed)
+          + '). Обычно это значит, что нет openssl: поставьте его или задайте свой '
+          + 'сертификат через tls=files. Поднимаю без защищённого соединения, '
+          + 'микрофон работать не будет')
+      }
+    }
   }
 
+  state.listener = { scheme: tls ? 'https' : 'http', host, port }
+  return startDirectBridge(ctx, { host, port, log: say, allow: rules, tls })
+}
+
+function start(ctx, config) {
   const pieces = {
     settings: config.settings !== false,
     randomUuid: config.randomUuid !== false,
     clipboard: config.clipboard !== false,
   }
+
+  const state = {
+    version: version(),
+    mode: config.mode,
+    modeReason: '',
+    listener: null,
+    tls: { enabled: false },
+    pieces,
+    allow: Array.isArray(config.allow) ? config.allow : [],
+    assumptions: [],
+  }
+
+  // Режим: заданный руками — как сказано, `auto` — по тому, обслуживает ли сеть
+  // кто-то другой. Слушатель поднимается один раз, поэтому и решение одно.
+  ctx.effect(() => {
+    let stop = () => {}
+    let alive = true
+
+    const decide = async () => {
+      let mode = config.mode
+      if (mode === 'auto') {
+        const verdict = await detectMode({
+          addresses: localAddresses(),
+          port: ctx.webServer && ctx.webServer.port,
+          directPort: config.directPort || 3088,
+        })
+        mode = verdict.mode
+        state.mode = mode
+        state.modeReason = verdict.reason
+        say('режим выбран сам: ' + mode + ' — ' + verdict.reason)
+      }
+      if (!alive || mode !== 'direct') return
+      stop = await raiseListener(ctx, config, state)
+    }
+
+    decide().catch((failed) => say('прямой режим не поднялся: ' + String(failed.message || failed)))
+    return () => { alive = false; stop() }
+  }, 'dsh-lanmode: слушатель прямого режима')
+
+  // Проверка точек крепления: плагин чинит чужое поведение, и его собственная
+  // поломка обязана быть заметной.
+  ctx.effect(() => {
+    let alive = true
+    const port = ctx.webServer && ctx.webServer.port
+    const fetchIndex = () => fetch('http://127.0.0.1:' + port + '/').then((answer) => answer.text())
+
+    // Даём харнессу договорить о себе: страница отдаётся не в первый миг.
+    const timer = setTimeout(() => {
+      checkAssumptions({ webServer: ctx.webServer, fetchIndex })
+        .then((results) => {
+          if (!alive) return
+          state.assumptions = results
+          const line = summarize(results)
+          if (results.every((item) => item.ok)) say(line)
+          // eslint-disable-next-line no-console
+          else console.warn('[dsh-lanmode] ' + line)
+        })
+        .catch((failed) => say('проверить точки крепления не вышло: ' + String(failed.message || failed)))
+    }, 3000)
+
+    return () => { alive = false; clearTimeout(timer) }
+  }, 'dsh-lanmode: проверка точек крепления')
+
+  if (config.diagnostics !== false) {
+    ctx.effect(() => ctx.webServer.register({
+      kind: 'exact',
+      path: '/dsh-lanmode/health',
+      handler: (req, res) => {
+        const json = String(req.url ?? '').includes('format=json')
+        if (json) {
+          res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' })
+          res.end(JSON.stringify(hostReport(state), null, 2))
+          return
+        }
+        res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' })
+        res.end(healthPage(state))
+      },
+    }), 'dsh-lanmode: страница диагностики')
+  }
+
   // Ничего не включено — и вставлять нечего.
   if (!pieces.settings && !pieces.randomUuid && !pieces.clipboard) return
 

package/lib/mode.js

@@ -0,0 +1,120 @@
+// Автовыбор режима.
+//
+// Режим сейчас выставляется руками, а при переезде о нём забывают. Ошибка в обе
+// стороны неприятна: лишний слушатель на занятом порту или его отсутствие там,
+// где он нужен.
+//
+// Определяем по одному признаку: отвечает ли что-нибудь на сетевом адресе этой
+// машины по порту харнесса. Харнесс слушает только петлю, поэтому ответ оттуда
+// означает, что сеть уже обслуживает кто-то другой, — то есть прокси.
+//
+// Правило простое и осознанно осторожное: не удалось выяснить — считаем, что
+// прокси есть, и ничего не поднимаем. Лишний слушатель на сетевом адресе — это
+// открытая дверь, и заводить её по догадке нельзя.
+//
+// Чего эта проверка не умеет: заметить прокси, который слушает ДРУГОЙ порт.
+// Такой случай неотличим снаружи от «никого нет», и для него режим задаётся
+// руками. Так и написано в описании плагина.
+
+import net from 'node:net'
+
+/** Отвечает ли кто-нибудь по этому адресу и порту. */
+function knock(host, port, timeoutMs) {
+  return new Promise((resolve) => {
+    const socket = net.connect({ host, port })
+    const done = (answer) => {
+      socket.removeAllListeners()
+      try { socket.destroy() } catch (already) { /* уже мертво */ }
+      resolve(answer)
+    }
+    socket.setTimeout(timeoutMs, () => done(false))
+    socket.on('connect', () => done(true))
+    socket.on('error', () => done(false))
+  })
+}
+
+/** Свой ли это адрес: петля отвечает всегда и для проверки не годится. */
+export function isLoopback(address) {
+  const clean = String(address).trim()
+  return clean === 'localhost' || clean === '::1' || clean === '[::1]' || /^127\./.test(clean)
+}
+
+/**
+ * Годится ли адрес для опроса.
+ *
+ * Связь-локальные адреса (fe80::) отбрасываются: без указания интерфейса к ним
+ * не подключиться, а с ним они всё равно ничего не говорят о том, обслуживает
+ * ли кто-то сеть.
+ */
+export function worthAsking(address) {
+  const clean = String(address ?? '').trim()
+  if (!clean || isLoopback(clean)) return false
+  if (/^fe80:/i.test(clean)) return false
+  if (/^169\.254\./.test(clean)) return false
+  // Имя машины опрашивать незачем: оно разрешается в один из тех же адресов.
+  return /^[0-9.]+$/.test(clean) || clean.includes(':')
+}
+
+/**
+ * Выбрать режим.
+ *
+ * Все адреса опрашиваются разом: их у машины бывает под сотню, и опрос по
+ * одному с ожиданием превращает выбор режима в минуты молчания при старте.
+ *
+ * @param options {{addresses: string[], port: number, directPort?: number,
+ *                  timeoutMs?: number, probe?: Function}}
+ * @returns `{ mode: 'proxy'|'direct', reason: string }`
+ */
+export async function detectMode(options) {
+  const probe = options.probe ?? knock
+  const timeoutMs = options.timeoutMs ?? 1000
+  const addresses = (options.addresses ?? []).filter(worthAsking)
+
+  if (!options.port) {
+    return { mode: 'proxy', reason: 'порт харнесса неизвестен — ничего не поднимаю' }
+  }
+  if (addresses.length === 0) {
+    return { mode: 'proxy', reason: 'сетевых адресов не нашлось — ничего не поднимаю' }
+  }
+
+  let answers
+  try {
+    answers = await Promise.all(addresses.map((address) => probe(address, options.port, timeoutMs)))
+  } catch (failed) {
+    return {
+      mode: 'proxy',
+      reason: 'проверить не удалось (' + String(failed.message || failed) + ') — ничего не поднимаю',
+    }
+  }
+
+  const busy = addresses.filter((address, index) => answers[index])
+  if (busy.length) {
+    return {
+      mode: 'proxy',
+      reason: 'по адресу ' + busy[0] + ':' + options.port + ' уже кто-то отвечает — сеть обслуживают без меня',
+    }
+  }
+
+  // Свой порт уже занят — поднимать нечего, и молчать об этом нельзя: иначе
+  // человек будет искать, почему по нему отвечает не то, что он ждёт.
+  if (options.directPort) {
+    let taken = false
+    try {
+      taken = await probe('127.0.0.1', options.directPort, timeoutMs)
+    } catch (unknown) {
+      taken = false
+    }
+    if (taken) {
+      return {
+        mode: 'proxy',
+        reason: 'порт ' + options.directPort + ' уже занят — свой слушатель не поднимаю',
+      }
+    }
+  }
+
+  return {
+    mode: 'direct',
+    reason: 'на ' + addresses.length + ' сетевых адресах по порту ' + options.port
+      + ' никто не отвечает — поднимаю свой слушатель',
+  }
+}

package/lib/tls.js

@@ -0,0 +1,173 @@
+// Сертификат для прямого режима.
+//
+// Зачем вообще. Микрофон браузер отдаёт только на защищённом соединении, и это
+// единственное, чего не лечит подмена на странице: `navigator.mediaDevices`
+// подделать нечем — за ним настоящее устройство. Пока прямой режим слушает
+// голый HTTP, голосовой ввод по сети невозможен в принципе.
+//
+// Самоподписанный сертификат — компромисс, а не решение: браузер всё равно
+// спросит. Но он превращает «невозможно» в «подтвердить один раз», а это
+// разница между «не работает» и «работает».
+//
+// Сертификат делается через openssl. Node умеет породить ключевую пару, но не
+// собрать из неё X.509: это ASN.1 вручную, сотни строк ради того, что уже
+// лежит в /usr/bin. Нет openssl — честно говорим об этом и предлагаем свой
+// сертификат, а не делаем вид, что всё в порядке.
+
+import { execFile } from 'node:child_process'
+import { X509Certificate } from 'node:crypto'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { addressBytes } from './access.js'
+
+/** За сколько до истечения перевыпускать. */
+const RENEW_BEFORE_MS = 30 * 24 * 60 * 60 * 1000
+
+/** Сколько живёт выпущенный нами сертификат. */
+const LIFETIME_DAYS = 397
+
+/**
+ * Адреса, по которым к этой машине могут обратиться.
+ *
+ * В сертификат идут все: браузер сверяет тот адрес, который набрали в строке,
+ * и сертификат, выписанный на одно имя, ругается на все остальные — даже после
+ * того, как его один раз приняли.
+ */
+export function localAddresses() {
+  const found = new Set(['localhost', '127.0.0.1', '::1'])
+  const interfaces = os.networkInterfaces()
+  for (const list of Object.values(interfaces)) {
+    for (const item of list ?? []) {
+      if (!item || item.internal) continue
+      if (item.address) found.add(item.address)
+    }
+  }
+  const hostname = os.hostname()
+  if (hostname) found.add(hostname)
+  return [...found]
+}
+
+/** Строка subjectAltName для openssl: имена — DNS, адреса — IP. */
+export function altNames(hosts) {
+  const parts = []
+  for (const host of hosts) {
+    const clean = String(host ?? '').trim()
+    if (!clean) continue
+    const isAddress = /^[0-9.]+$/.test(clean) || clean.includes(':')
+    parts.push((isAddress ? 'IP:' : 'DNS:') + clean)
+  }
+  return parts.join(',')
+}
+
+function run(command, args) {
+  return new Promise((resolve, reject) => {
+    execFile(command, args, { timeout: 30000 }, (error, stdout, stderr) => {
+      if (error) reject(new Error(String(stderr || error.message).trim()))
+      else resolve(String(stdout))
+    })
+  })
+}
+
+/** Что известно о лежащем сертификате: до какого числа и на какие имена. */
+export function inspect(certPem) {
+  const certificate = new X509Certificate(certPem)
+  const names = String(certificate.subjectAltName ?? '')
+    .split(',')
+    .map((part) => part.trim().replace(/^(DNS|IP Address|IP):/, ''))
+    .filter(Boolean)
+  return {
+    validTo: new Date(certificate.validTo),
+    fingerprint: certificate.fingerprint256,
+    names,
+  }
+}
+
+/**
+ * Годится ли лежащий сертификат: не истекает ли и покрывает ли нужные адреса.
+ *
+ * Второе важнее первого. Появился новый сетевой адрес — старый сертификат
+ * формально жив, но по новому адресу браузер его не примет, и человек будет
+ * гадать, почему «вчера работало».
+ */
+/**
+ * Одно и то же имя, записанное одинаково.
+ *
+ * Адрес можно записать по-разному: openssl превращает  в
+ * , и сравнение строк на этом рассыпается. Молча, с
+ * единственным следствием: сертификат перевыпускается при каждом запуске, а
+ * браузер каждый раз требует подтверждения заново — то есть смысл затеи
+ * пропадает.
+ */
+function canonical(name) {
+  const bytes = addressBytes(name)
+  if (bytes) return bytes.map((byte) => byte.toString(16).padStart(2, '0')).join('')
+  return String(name).trim().toLowerCase()
+}
+
+export function stillGood(info, hosts, now) {
+  if (!info) return false
+  if (info.validTo.getTime() - now < RENEW_BEFORE_MS) return false
+  const covered = new Set(info.names.map(canonical))
+  return hosts.every((host) => covered.has(canonical(host)))
+}
+
+/**
+ * Взять готовый сертификат или выпустить новый.
+ *
+ * @param options {{dir: string, hosts: string[], log: (message: string) => void, now?: number}}
+ * @returns `{ cert, key, fingerprint, issued }`
+ */
+export async function ensureCertificate(options) {
+  const dir = options.dir
+  const hosts = options.hosts
+  const now = options.now ?? Date.now()
+  const certPath = path.join(dir, 'lanmode-cert.pem')
+  const keyPath = path.join(dir, 'lanmode-key.pem')
+
+  if (fs.existsSync(certPath) && fs.existsSync(keyPath)) {
+    try {
+      const cert = fs.readFileSync(certPath, 'utf8')
+      const info = inspect(cert)
+      if (stillGood(info, hosts, now)) {
+        return {
+          cert,
+          key: fs.readFileSync(keyPath, 'utf8'),
+          fingerprint: info.fingerprint,
+          issued: false,
+        }
+      }
+      options.log('сертификат перевыпускается: истекает или не покрывает все адреса')
+    } catch (unreadable) {
+      options.log('сертификат нечитаем, выпускаю заново: ' + String(unreadable.message || unreadable))
+    }
+  }
+
+  fs.mkdirSync(dir, { recursive: true })
+  await run('openssl', [
+    'req', '-x509', '-newkey', 'rsa:2048', '-nodes', '-sha256',
+    '-days', String(LIFETIME_DAYS),
+    '-keyout', keyPath,
+    '-out', certPath,
+    '-subj', '/CN=' + (hosts[0] || 'localhost'),
+    '-addext', 'subjectAltName=' + altNames(hosts),
+  ])
+  // Ключ читаем не только мы: пусть его не читает никто, кроме владельца.
+  fs.chmodSync(keyPath, 0o600)
+
+  const cert = fs.readFileSync(certPath, 'utf8')
+  return {
+    cert,
+    key: fs.readFileSync(keyPath, 'utf8'),
+    fingerprint: inspect(cert).fingerprint,
+    issued: true,
+  }
+}
+
+/** Прочитать сертификат и ключ, указанные человеком. */
+export function readCertificate(certPath, keyPath) {
+  const cert = fs.readFileSync(certPath, 'utf8')
+  const key = fs.readFileSync(keyPath, 'utf8')
+  return { cert, key, fingerprint: inspect(cert).fingerprint, issued: false }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-lanmode",
-  "version": "0.4.0",
+  "version": "0.5.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",