@dr-co/dsh-node-client 0.0.0-stage → 0.0.59

package/lib/sandbox.mjs

@@ -0,0 +1,152 @@
+/**
+ * Песочница клиента: три режима поверх `bwrap`.
+ *
+ * Идея не наша — она взята у DSH (`@deepseek-ai/dsh-sandbox-local`, MIT): там
+ * ровно тот же профиль `bwrap` и те же таблицы сигнатур отказа. Повторяем
+ * профиль сами, потому что их пакет тянет cordis, платформенные ветки и 6 МБ
+ * политик, а нам нужны 40 строк и предсказуемое поведение.
+ *
+ * Главное, что нужно понимать про детект отказа: **ничего не предсказывается**.
+ * Команда запускается под изоляцией, ядро само не пускает запись, а мы уже после
+ * факта смотрим код возврата и stderr и решаем, был ли это отказ песочницы.
+ *
+ * `LC_ALL=C` обязателен: сообщения ядра локализованы («Файловая система доступна
+ * только для чтения»), и английская сигнатура на русской локали не совпадёт.
+ * DSH делает то же самое в `dsh-subprocess-local`.
+ *
+ * @module dsh-node-client/sandbox
+ */
+import { spawnSync } from 'node:child_process'
+
+/** Режимы по возрастанию прав: слева уже, справа шире. */
+export const MODES = ['ro', 'rw', 'full']
+
+/** Сигнатуры отказа, которые печатает ядро под `bwrap` (как в DSH). */
+export const DENIAL_SIGNATURES = ['read-only file system']
+
+/** Признаки поломки самого раннера: это не отказ политики, а «не запустилось». */
+export const RUNNER_SIGNATURES = ['bwrap: ']
+
+/**
+ * Отображение наших режимов на режимы DSH — чтобы тексты и лестница эскалации
+ * совпадали с тем, что модель видит в основном DSH.
+ */
+export const DSH_MODES = { ro: 'read-only', rw: 'workspace-write', full: 'danger-full-access' }
+
+/** Лестница «строго шире»: во что можно повышать режим. */
+export const WIDER_MODES = {
+  ro: ['rw', 'full'],
+  rw: ['full'],
+  full: [],
+}
+
+/** Сравнить режимы: вернуть тот, что уже (ближе к ro). */
+export function narrower (a, b) {
+  return MODES.indexOf(a) <= MODES.indexOf(b) ? a : b
+}
+
+/**
+ * Профиль `bwrap` для режима.
+ *
+ * - `ro`   — весь хост только на чтение, сеть отрезана;
+ * - `rw`   — плюс запись в каталог workdir и в /tmp, сеть отрезана;
+ * - `full` — профиля нет, команда запускается как есть.
+ *
+ * @param {object} options
+ * @param {'ro'|'rw'|'full'} options.mode
+ * @param {string} [options.workdir] каталог, разрешённый на запись в режиме rw
+ * @param {string} [options.cwd] рабочий каталог команды
+ * @param {string[]} [options.mask] каталоги, которые надо спрятать (--tmpfs)
+ * @returns {string[]} аргументы bwrap до `--`
+ */
+export function profileArgs ({ mode, workdir, writable = [], cwd, mask = [] }) {
+  if (mode === 'full') return []
+  const args = [
+    '--ro-bind', '/', '/',
+    '--dev', '/dev',
+    '--unshare-pid',
+    '--unshare-net',
+    '--proc', '/proc',
+    '--die-with-parent',
+  ]
+  for (const path of mask) args.push('--tmpfs', path)
+  if (mode === 'rw') {
+    args.push('--tmpfs', '/tmp')
+    // запись разрешена в каждый разрешённый владельцем корень: сессия может
+    // переехать в соседний каталог (`session.chdir`), и он должен остаться
+    // доступным на запись, иначе rw превращается в ro после первого переезда
+    const targets = [...new Set([...(writable ?? []), workdir].filter(Boolean))]
+    for (const path of targets) args.push('--bind', path, path)
+  }
+  if (cwd) args.push('--chdir', cwd)
+  return args
+}
+
+let probeCache = null
+
+/**
+ * Работает ли `bwrap` на этой машине. Проверяется один раз за процесс: профиль
+ * `ro` против самого себя, команда `true`. Не работает — значит изоляции нет,
+ * и режимы `ro`/`rw` обязаны отказать, а не сделать вид, что всё хорошо.
+ *
+ * @returns {{available: boolean, version?: string, reason?: string}}
+ */
+export function probe (run = spawnSync) {
+  if (probeCache) return probeCache
+  const args = [...profileArgs({ mode: 'ro' }), '--', 'true']
+  try {
+    const result = run('bwrap', args, { timeout: 5000, stdio: 'ignore' })
+    if (result.status === 0) {
+      const version = run('bwrap', ['--version'], { timeout: 2000, encoding: 'utf8' })
+      probeCache = { available: true, version: String(version.stdout ?? '').trim() }
+    } else {
+      probeCache = { available: false, reason: `bwrap вернул ${result.status}` }
+    }
+  } catch (error) {
+    probeCache = { available: false, reason: error?.message ?? 'bwrap недоступен' }
+  }
+  return probeCache
+}
+
+/** Сбросить кэш пробы (тесты). */
+export function resetProbe () {
+  probeCache = null
+}
+
+/**
+ * Разобрать результат запуска: это отказ песочницы, поломка раннера или
+ * обычная ошибка команды.
+ *
+ * @param {object} options
+ * @param {number|null} options.code код возврата
+ * @param {string} [options.stderr] stderr процесса
+ * @param {'ro'|'rw'|'full'} options.mode
+ * @param {string} [options.enforcement]
+ * `denied` — ядро отказало в доступе (сигнатура в stderr), `failed` — команда
+ * вернула ненулевой код. Это разные факты: составная команда может вернуть 0,
+ * хотя одна из её частей уже отвергнута, и наоборот.
+ *
+ * @returns {{denied: boolean, failed: boolean, runnerFailure: boolean, signature: string|null}}
+ */
+export function classify ({ code, stderr = '', mode, enforcement = 'bwrap' }) {
+  const text = String(stderr ?? '').toLowerCase()
+  const signature = DENIAL_SIGNATURES.find((needle) => text.includes(needle)) ?? null
+  const runnerFailure = RUNNER_SIGNATURES.some((needle) => text.includes(needle))
+  // отказ — только при ненулевом коде возврата: команда, которая просто
+  // напечатала «read-only file system», отказом не считается
+  // Код возврата не обязателен: `echo … ; echo …` в одной строке возвращает 0,
+  // хотя запись уже была отвергнута. Сигнатура в stderr — единственный
+  // надёжный признак, а ложное срабатывание стоит одного лишнего вопроса.
+  const denied = mode !== 'full' && !runnerFailure && signature !== null
+  return { denied, failed: Number(code) !== 0, runnerFailure, signature: denied ? signature : null }
+}
+
+/** Ошибка «изоляции нет»: команда не должна запускаться вообще. */
+export class SandboxUnavailableError extends Error {
+  constructor (message, reason) {
+    super(message)
+    this.name = 'SandboxUnavailableError'
+    this.code = 'sandbox_unavailable'
+    this.reason = reason
+  }
+}

package/lib/sessions.mjs

@@ -0,0 +1,148 @@
+/**
+ * Каталоги сессий на клиенте.
+ *
+ * У каждой сессии свой каталог внутри workdir: `<workdir>/<session-id>`. Он же
+ * рабочий каталог команд этой сессии. Каталог можно переключить через встроенный
+ * плагин `session` (метод `chdir`), но только внутри `roots` из конфига — иначе
+ * песочница перестала бы что-либо значить.
+ *
+ * Выбор живёт в `state.sqlite`, поэтому переживает рестарт демона.
+ *
+ * @module dsh-node-client/sessions
+ */
+import { chmodSync, existsSync, mkdirSync, realpathSync, statSync } from 'node:fs'
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path'
+
+/** Недопустимый идентификатор сессии: `.` и `..` означают не имя, а переход. */
+export function safeSessionName (session) {
+  const safe = String(session ?? '').replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 120)
+  if (!safe || safe === '.' || safe === '..') {
+    throw Object.assign(new Error(`недопустимый идентификатор сессии: ${JSON.stringify(session)}`), { code: 'bad_session' })
+  }
+  return safe
+}
+
+/**
+ * Канонический путь: для существующего — `realpath`, для несуществующего хвоста —
+ * канонизация ближайшего существующего родителя плюс остаток.
+ */
+export function canonicalPath (input) {
+  const absolute = isAbsolute(input) ? input : resolve(input)
+  if (existsSync(absolute)) return realpathSync(absolute)
+  const parts = []
+  let current = absolute
+  while (!existsSync(current)) {
+    parts.unshift(current.slice(current.lastIndexOf(sep) + 1))
+    const parent = dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+  return join(existsSync(current) ? realpathSync(current) : current, ...parts)
+}
+
+/** Лежит ли путь внутри корня (по границе каталога, а не по префиксу строки). */
+export function inside (path, root) {
+  const canonicalRoot = canonicalPath(root)
+  if (path === canonicalRoot) return true
+  return path.startsWith(canonicalRoot.endsWith(sep) ? canonicalRoot : canonicalRoot + sep)
+}
+
+/** Какие каталоги разрешены к размещению сессий. `['/']` — весь хост. */
+export function normalizeRoots (roots) {
+  const list = Array.isArray(roots) && roots.length ? roots : ['/']
+  return list.map((root) => canonicalPath(String(root)))
+}
+
+/**
+ * Проверить и подготовить каталог сессии.
+ *
+ * @param {object} options
+ * @param {string} options.workdir базовый каталог (из настроек узла)
+ * @param {string} options.session идентификатор сессии
+ * @param {string[]} [options.roots] где разрешено создавать каталоги
+ * @returns {{dir: string, created: boolean}}
+ */
+export function prepareSessionDir ({ workdir, session, roots }) {
+  if (typeof workdir !== 'string' || !workdir.trim()) {
+    throw Object.assign(new Error('рабочая директория не задана'), { code: 'workdir_invalid' })
+  }
+  const allowed = normalizeRoots(roots)
+  const dir = join(canonicalPath(workdir), safeSessionName(session))
+  assertInside(dir, allowed)
+  const created = !existsSync(dir)
+  if (created) mkdirSync(dir, { recursive: true })
+  if (!statSync(dir).isDirectory()) {
+    throw Object.assign(new Error(`${dir} не каталог`), { code: 'workdir_invalid' })
+  }
+  return { dir, created }
+}
+
+/** Проверить, что путь внутри одного из разрешённых корней. */
+export function assertInside (path, roots) {
+  const allowed = normalizeRoots(roots)
+  const target = canonicalPath(path)
+  if (!allowed.some((root) => inside(target, root))) {
+    throw Object.assign(new Error(`каталог ${target} вне разрешённых: ${allowed.join(', ')}`), { code: 'workdir_denied' })
+  }
+  return target
+}
+
+/** Хранилище выбранных каталогов сессий. */
+export function createSessionStore (store) {
+  return {
+    /**
+     * Каталог сессии: выбранный ранее, иначе `<workdir>/<session>`.
+     * @returns {string}
+     */
+    dir (session, { workdir, roots } = {}) {
+      // выбранный ранее каталог уже проверен по `roots` в момент переключения
+      const saved = store.readSessionDir?.(session)
+      if (saved && existsSync(saved)) return saved
+      return prepareSessionDir({ workdir, session, roots }).dir
+    },
+
+    /**
+     * Переключить каталог сессии. Каталог должен существовать: создание — это
+     * отдельное действие (`mkdir`), чтобы `chdir` не делал неявных вещей.
+     */
+    chdir (session, path, { roots } = {}) {
+      const target = assertInside(path, roots)
+      if (!existsSync(target)) {
+        throw Object.assign(new Error(`каталога ${target} нет`), { code: 'workdir_not_found' })
+      }
+      if (!statSync(target).isDirectory()) {
+        throw Object.assign(new Error(`${target} не каталог`), { code: 'workdir_invalid' })
+      }
+      store.writeSessionDir?.(session, target)
+      return { dir: target }
+    },
+
+    /**
+     * Создать каталог внутри разрешённых корней.
+     * @param {string} session сессия
+     * @param {string} path путь
+     * @param {object} options
+     * @param {string[]} options.roots разрешённые корни
+     * @param {number} [options.mode] права (по умолчанию 0o755)
+     */
+    mkdir (session, path, { roots, mode = 0o755 } = {}) {
+      const target = assertInside(path, roots)
+      if (existsSync(target)) {
+        if (!statSync(target).isDirectory()) {
+          throw Object.assign(new Error(`${target} уже существует и это не каталог`), { code: 'workdir_invalid' })
+        }
+        return { dir: target, created: false }
+      }
+      mkdirSync(target, { recursive: true, mode })
+      try {
+        chmodSync(target, mode)
+      } catch {}
+      return { dir: target, created: true }
+    },
+
+    /** Текущий каталог сессии, без создания. */
+    cwd (session, { workdir, roots } = {}) {
+      return this.dir(session, { workdir, roots })
+    },
+  }
+}

package/lib/shell.mjs

@@ -0,0 +1,154 @@
+/**
+ * Чем исполнять команду на этой платформе.
+ *
+ * Модель зовёт API `shell`, а не «bash»: на Windows та же команда уходит в
+ * PowerShell, и называть это bash было бы враньём. Здесь собрано всё, что
+ * зависит от платформы: как собрать argv, как убить дерево процессов и есть ли
+ * вообще песочница.
+ *
+ * @module dsh-node-client/shell
+ */
+import { spawn } from 'node:child_process'
+
+/**
+ * Время с точностью лучше миллисекунды.
+ *
+ * `Date.now()` даёт миллисекунды, а на пинге в пределах одной сети этого мало:
+ * отклик бывает меньше миллисекунды, и разница часов утонула бы в округлении.
+ * `performance` даёт доли, но его начало отсчёта не сравнимо между машинами,
+ * поэтому складываем со `timeOrigin` — это уже обычное настенное время.
+ *
+ * @returns {number} миллисекунды с долями
+ */
+export function preciseNow () {
+  return Math.round((performance.timeOrigin + performance.now()) * 1000) / 1000
+}
+
+/** Платформа, для которой выбираем реализацию. */
+export const platform = process.platform
+
+/** Есть ли на платформе песочница, которой мы умеем пользоваться. */
+export const sandboxSupported = platform !== 'win32'
+
+/**
+ * Собрать argv для запуска командной строки.
+ *
+ * @param {string} command командная строка от модели
+ * @param {object} [options]
+ * @param {string} [options.shell] путь к оболочке (POSIX)
+ * @returns {{file: string, args: string[]}}
+ */
+export function shellArgv (command, { shell } = {}) {
+  if (platform === 'win32') {
+    // -NoProfile: чужой профиль меняет поведение и печатает баннеры в вывод;
+    // -NonInteractive: иначе команда может встать на приглашении
+    return {
+      file: process.env.DSHNC_POWERSHELL ?? 'powershell.exe',
+      args: ['-NoProfile', '-NonInteractive', '-Command', command],
+    }
+  }
+  return { file: shell ?? '/bin/sh', args: ['-c', command] }
+}
+
+/**
+ * Собрать argv с песочницей — так же, как для обычной команды.
+ *
+ * Задания (`job`) идут тем же путём, что и `exec`: в DSH фоновый процесс — это
+ * тот же процесс, и песочница применяется на спавне. Другая политика для
+ * фоновой работы означала бы, что политика узла обходится одной строкой.
+ *
+ * @param {object} options
+ * @param {string} options.command командная строка
+ * @param {string} [options.shell]
+ * @param {object|null} [options.sandbox] `{mode, args, probe}`
+ * @returns {{argv: string[], enforcement: string, error?: object}}
+ */
+export function commandArgv ({ command, shell, sandbox = null }) {
+  const base = shellArgv(command, { shell })
+  let argv = [base.file, ...base.args]
+  if (!sandbox || sandbox.mode === 'full') return { argv, enforcement: 'none' }
+  if (!sandboxSupported) {
+    return {
+      argv,
+      enforcement: 'none',
+      error: { ok: false, code: 'sandbox_unavailable', message: `на платформе ${process.platform} песочницы нет: разрешён только режим full` },
+    }
+  }
+  const probeResult = sandbox.probe?.() ?? { available: true }
+  if (!probeResult.available) {
+    return {
+      argv,
+      enforcement: 'none',
+      error: { ok: false, code: 'sandbox_unavailable', message: probeResult.reason ?? 'bwrap недоступен', results: null },
+    }
+  }
+  // каталог задаётся самим профилем песочницы (--chdir), поэтому `cwd` не нужен
+  argv = ['bwrap', ...(sandbox.args ?? []), '--', base.file, ...base.args]
+  return { argv, enforcement: 'bwrap' }
+}
+
+/**
+ * Запустить процесс так, чтобы его можно было убить вместе с потомками.
+ *
+ * POSIX: своя группа (`detached`), сигнал всей группе через `-pid`.
+ * Windows: отдельного механизма нет, поэтому убиваем дерево `taskkill /T /F`.
+ *
+ * @param {string} command
+ * @param {object} [options]
+ * @param {string} [options.cwd]
+ * @param {object} [options.env]
+ * @param {string} [options.shell]
+ * @returns {import('node:child_process').ChildProcess}
+ */
+export function spawnCommand (command, { cwd, env, shell } = {}) {
+  const { file, args } = shellArgv(command, { shell })
+  return spawn(file, args, {
+    cwd: cwd || undefined,
+    env: env ?? process.env,
+    // своя группа только на POSIX: на Windows флаг означает другое окно
+    detached: platform !== 'win32',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  })
+}
+
+/**
+ * Убить процесс вместе с потомками.
+ * @param {import('node:child_process').ChildProcess} child
+ * @param {NodeJS.Signals} [signal]
+ * @returns {boolean} удалось ли отправить сигнал
+ */
+export function killTree (child, signal = 'SIGTERM') {
+  if (!child?.pid) return false
+  if (platform === 'win32') {
+    try {
+      spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' }).unref()
+      return true
+    } catch {
+      return false
+    }
+  }
+  try {
+    // минус — это группа процессов: bwrap и всё, что он породил, умрёт вместе
+    process.kill(-child.pid, signal)
+    return true
+  } catch {
+    try {
+      child.kill(signal)
+      return true
+    } catch {
+      return false
+    }
+  }
+}
+
+/**
+ * Код возврата из результата PowerShell.
+ *
+ * `$LASTEXITCODE` есть только у внешних программ; если команда — чистый
+ * cmdlet, PowerShell вернёт 0, и это правильный ответ.
+ *
+ * @returns {string} хвост команды, который печатает код
+ */
+export function exitCodeTail () {
+  return platform === 'win32' ? '; exit $LASTEXITCODE' : ''
+}