dsh-mesh-node 0.0.0-stage → 0.0.1

package/src/core/acl.js

@@ -0,0 +1,81 @@
+// ACL editing helpers. Pure functions so the CLI and the self-test share one truth:
+// an upgraded config keeps its (possibly customised) allow list — new default allows
+// are NOT merged in automatically, which is why `acl reset|allow|deny` exists.
+import { DEFAULT_ALLOW } from './config.js'
+
+function unique(list) {
+  return [...new Set(list.filter(name => typeof name === 'string' && name.trim()).map(name => name.trim()))]
+}
+
+function validate(names, known) {
+  if (!known) return names
+  const catalog = new Set(known)
+  const unknown = names.filter(name => !catalog.has(name))
+  if (unknown.length > 0) {
+    throw Object.assign(new Error(`unknown tool(s): ${unknown.join(', ')}`), { code: 'E_INVALID_ARG' })
+  }
+  return names
+}
+
+/**
+ * Compute the next ACL from the current one.
+ * @param {{allow?: string[], deny?: string[]}} current
+ * @param {{allow?: string[], deny?: string[], reset?: boolean, known?: string[]}} change
+ * @returns {{allow: string[], deny: string[], changed: boolean, notes: string[]}}
+ */
+export function resolveAclUpdate(current, change = {}) {
+  const notes = []
+  let allow = [...(current?.allow || [])]
+  let deny = [...(current?.deny || [])]
+
+  if (change.reset) {
+    allow = [...DEFAULT_ALLOW]
+    deny = []
+    notes.push('reset to DEFAULT_ALLOW')
+  }
+
+  const toAllow = validate(unique(change.allow || []), change.known)
+  const toDeny = validate(unique(change.deny || []), change.known)
+
+  for (const name of toAllow) {
+    if (!allow.includes(name)) {
+      allow.push(name)
+      notes.push(`allow ${name}`)
+    }
+    if (deny.includes(name)) {
+      deny = deny.filter(n => n !== name)
+      notes.push(`un-deny ${name}`)
+    }
+  }
+  for (const name of toDeny) {
+    if (!deny.includes(name)) {
+      deny.push(name)
+      notes.push(`deny ${name}`)
+    }
+    if (allow.includes(name)) {
+      allow = allow.filter(n => n !== name)
+      notes.push(`un-allow ${name}`)
+    }
+  }
+
+  const changed =
+    allow.length !== (current?.allow || []).length ||
+    deny.length !== (current?.deny || []).length ||
+    allow.some(n => !(current?.allow || []).includes(n))
+
+  return { allow, deny, changed, notes }
+}
+
+/** Effective view: every tool with the flag that `mesh_self` reports. */
+export function describeAcl(config, names = []) {
+  const allow = config?.acl?.allow || []
+  const deny = config?.acl?.deny || []
+  return {
+    allow,
+    deny,
+    tools: names.map(name => {
+      const denied = deny.includes(name)
+      return { name, allowed: denied ? false : allow.includes(name) }
+    })
+  }
+}

package/src/core/audit.js

@@ -0,0 +1,75 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { nowIso, short, stripBom } from './util.js'
+
+const MAX_AUDIT_BYTES = 5 * 1024 * 1024
+const KEEP_TAIL_LINES = 400
+
+export function auditPath(home) {
+  mkdirSync(home, { recursive: true, mode: 0o700 })
+  return join(home, 'audit.jsonl')
+}
+
+function rotateIfNeeded(file) {
+  try {
+    if (!existsSync(file)) return
+    if (statSync(file).size < MAX_AUDIT_BYTES) return
+    renameSync(file, `${file}.1`)
+  } catch {
+    /* rotation is best-effort: never break a tool call because of it */
+  }
+}
+
+/**
+ * Audit writer. One JSON line per tool call: who (token id), what, result, duration.
+ * Never contains argument values (they may hold secrets); only argument key names.
+ */
+export function makeAudit({ home, log = console }) {
+  const file = auditPath(home)
+  return async function audit(event) {
+    const line = {
+      ts: nowIso(),
+      ...event,
+      args: Array.isArray(event?.args) ? event.args : undefined
+    }
+    try {
+      rotateIfNeeded(file)
+      appendFileSync(file, JSON.stringify(line) + '\n', { encoding: 'utf8' })
+    } catch (error) {
+      log?.error?.(`[dsh-mesh] audit write failed: ${error?.message || error}`)
+    }
+  }
+}
+
+/** Read the last `limit` audit lines (newest last). */
+export function tailAudit(home, { limit = 50, tool, ok } = {}) {
+  const file = auditPath(home)
+  if (!existsSync(file)) return { path: file, entries: [], total: 0 }
+  const text = stripBom(readFileSync(file, 'utf8'))
+  const lines = text.split(/\r?\n/).filter(Boolean)
+  let entries = []
+  for (const line of lines) {
+    try {
+      entries.push(JSON.parse(stripBom(line)))
+    } catch {
+      /* skip corrupt line */
+    }
+  }
+  const total = entries.length
+  if (tool) entries = entries.filter((e) => e.tool === tool)
+  if (typeof ok === 'boolean') entries = entries.filter((e) => e.ok === ok)
+  const slice = entries.slice(-Math.min(Math.max(1, limit), KEEP_TAIL_LINES))
+  return { path: file, total, matched: entries.length, entries: slice }
+}
+
+export function auditSummary(home) {
+  const file = auditPath(home)
+  if (!existsSync(file)) return { path: file, exists: false, sizeBytes: 0 }
+  let sizeBytes = 0
+  try {
+    sizeBytes = statSync(file).size
+  } catch {
+    /* ignore */
+  }
+  return { path: file, exists: true, sizeBytes, preview: short('', 0) }
+}

package/src/core/autostart.js

@@ -0,0 +1,119 @@
+// Autostart helper: keep the mesh endpoint alive across user logins (Windows Task Scheduler).
+// Read-only by default: `status` only queries schtasks; `install`/`remove` need an explicit
+// confirmation flag because creating a per-user scheduled task is a user-level config change.
+import { execFile } from 'node:child_process'
+import { fileURLToPath } from 'node:url'
+import { dirname as dirnameOf, join as joinPath } from 'node:path'
+
+export const TASK_NAME = 'dsh-mesh-endpoint'
+
+const CLI_PATH = joinPath(dirnameOf(fileURLToPath(import.meta.url)), '..', 'cli.js')
+
+function exec(args) {
+  return new Promise((resolvePromise) => {
+    // schtasks writes the console code page (GBK on zh-CN Windows), so decode bytes ourselves.
+    execFile(
+      'schtasks',
+      args,
+      { windowsHide: true, timeout: 15000, encoding: 'buffer' },
+      (error, stdout, stderr) => {
+        const code = error ? (typeof error.code === 'number' ? error.code : 1) : 0
+        resolvePromise({
+          code,
+          stdout: decodeText(stdout),
+          stderr: decodeText(stderr),
+          message: error ? String(error.message) : ''
+        })
+      }
+    )
+  })
+}
+
+function decodeText(buf) {
+  if (!Buffer.isBuffer(buf)) return buf || ''
+  try {
+    return new TextDecoder('gbk').decode(buf)
+  } catch {
+    return buf.toString('utf8')
+  }
+}
+
+function assertWindows() {
+  if (process.platform !== 'win32') throw new Error('autostart is Windows-only (schtasks)')
+}
+
+/** Parse `schtasks /Query /V /FO LIST` into a flat object (localized labels are matched by suffix). */
+function parseVerboseList(text) {
+  const out = {}
+  for (const line of text.split(/\r?\n/)) {
+    const i = line.indexOf(':')
+    if (i === -1) continue
+    const key = line.slice(0, i).trim()
+    const value = line.slice(i + 1).trim()
+    if (key && value) out[key] = value
+  }
+  return out
+}
+
+/** Inspect the task. Never throws for "not installed" — that is the normal state. */
+export async function autostartStatus(name = TASK_NAME) {
+  assertWindows()
+  const res = await exec(['/Query', '/TN', name, '/V', '/FO', 'LIST'])
+  if (res.code !== 0) {
+    return { installed: false, name, detail: (res.stderr || res.message || '').trim() }
+  }
+  const fields = parseVerboseList(res.stdout)
+  // zh-CN Windows localizes these labels ("状态", "要运行的任务", …), so a suffix match on the
+  // English name alone silently returns undefined — match localized aliases too (2026-10-19).
+  const ALIASES = {
+    status: ['Status', '状态'],
+    state: ['ScheduledTaskState', '计划任务状态', '已计划的任务状态'],
+    taskToRun: ['TaskToRun', '要运行的任务'],
+    lastRun: ['LastRunTime', '上次运行时间'],
+    lastResult: ['LastResult', '上次结果'],
+    runAsUser: ['RunAsUser', '运行身份', '运行方式', '作为用户运行']
+  }
+  const pick = (aliases) => {
+    const squash = (value) => value.replace(/[\s.]/g, '')
+    const key = Object.keys(fields).find((candidate) => aliases.some((alias) => squash(candidate).endsWith(squash(alias)) && squash(candidate).length <= squash(alias).length + 2))
+      || Object.keys(fields).find((candidate) => aliases.includes(candidate.trim()))
+    return key ? fields[key] : undefined
+  }
+  return {
+    installed: true,
+    name,
+    status: pick(ALIASES.status),
+    state: pick(ALIASES.state),
+    taskToRun: pick(ALIASES.taskToRun),
+    lastRun: pick(ALIASES.lastRun),
+    lastResult: pick(ALIASES.lastResult),
+    runAsUser: pick(ALIASES.runAsUser)
+  }
+}
+
+/** The exact command a login-time task would run. */
+export function autostartCommand(name = TASK_NAME, port) {
+  const portArg = port ? ` --port ${port}` : ''
+  return `"${process.execPath}" "${CLI_PATH}" serve${portArg}`
+}
+
+/**
+ * Create/replace a logon-triggered task that runs `serve`.
+ * Callers must pass `yes: true`; the CLI only forwards it after an explicit `--yes`.
+ */
+export async function autostartInstall({ name = TASK_NAME, command = autostartCommand(name), yes = false } = {}) {
+  assertWindows()
+  if (!yes) throw new Error('refusing to install without --yes (creates a per-user scheduled task)')
+  // /RL LIMITED: run at the user's normal integrity level, never elevated.
+  const res = await exec(['/Create', '/TN', name, '/SC', 'ONLOGON', '/RL', 'LIMITED', '/TR', command, '/F'])
+  if (res.code !== 0) throw new Error(`schtasks /Create failed (${res.code}): ${(res.stderr || res.message || '').trim()}`)
+  return { ok: true, name, command, stdout: res.stdout.trim() }
+}
+
+export async function autostartRemove({ name = TASK_NAME, yes = false } = {}) {
+  assertWindows()
+  if (!yes) throw new Error('refusing to remove without --yes')
+  const res = await exec(['/Delete', '/TN', name, '/F'])
+  if (res.code !== 0) throw new Error(`schtasks /Delete failed (${res.code}): ${(res.stderr || res.message || '').trim()}`)
+  return { ok: true, name }
+}

package/src/core/cluster.js

@@ -0,0 +1,340 @@
+/**
+ * Cluster view (M7 step 4).
+ *
+ * A single read-only snapshot of everything this node can currently reach:
+ * - local: every DSH instance behind a host bridge (id / pid / tool count / live agents)
+ * - remote: every paired peer's `/health` (version / tools / uptime / TLS pin)
+ *
+ * The point is to answer "is the cluster healthy, and if not, which hop is broken"
+ * from one call, instead of hand-running `host status` plus curl on each peer.
+ * Nothing here mutates state; all probes are bounded by `timeoutMs`.
+ */
+import { request as httpRequest } from 'node:http'
+import { request as httpsRequest } from 'node:https'
+import { createHostClient, hostInstances } from './host-agent.js'
+import { MESH_VERSION } from './config.js'
+import { callPeerTool } from './peer-client.js'
+import { fingerprintOfSocket, normalizeFingerprint } from './tls.js'
+
+const DEFAULT_TIMEOUT_MS = 4000
+
+function normalizeUrl(url) {
+  return String(url || '').replace(/\/+$/, '')
+}
+
+function normalizePeerHealth(body) {
+  if (!body || body.service !== 'dsh-mesh') {
+    return { error: { code: 'E_PEER_BAD_RESPONSE', message: 'peer /health did not identify as dsh-mesh' } }
+  }
+  return {
+    version: body.version,
+    node: body.node,
+    tools: body.tools,
+    pid: body.pid ?? null,
+    uptimeSec: body.uptimeSec,
+    tls: body.tls === true,
+    pairing: body.pairing ? { enabled: body.pairing.enabled === true, codeActive: body.pairing.codeActive === true } : null
+  }
+}
+
+/**
+ * Probe one paired peer over HTTPS. Uses TOFU pinning (peers store the cert
+ * fingerprint captured at pairing time): the trust chain is not judged, the
+ * certificate is read off the socket and compared against the stored pin.
+ */
+export function probePeer(peer, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const base = normalizeUrl(peer?.url)
+  const expected = peer?.certFingerprint ? normalizeFingerprint(peer.certFingerprint) : null
+  return new Promise((resolve) => {
+    let settled = false
+    const startedAt = Date.now()
+    const finish = (value) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      resolve({ id: peer?.id || null, name: peer?.name || null, url: base, ...value })
+    }
+    if (!base) {
+      return finish({ up: false, latencyMs: 0, error: { code: 'E_PEER_BAD_RESPONSE', message: 'peer has no url' } })
+    }
+
+    const isHttps = base.startsWith('https:')
+    const request = isHttps ? httpsRequest : httpRequest
+    const options = { method: 'GET', agent: false, headers: { accept: 'application/json' } }
+    if (isHttps) options.rejectUnauthorized = false
+
+    const req = request(`${base}/health`, options, (res) => {
+      // Grab the certificate *inside* the response callback: by the time `end`
+      // fires the socket may already be gone (same trap as company-check.mjs).
+      let got = null
+      if (isHttps) {
+        try {
+          got = fingerprintOfSocket(res.socket)
+        } catch {
+          got = null
+        }
+      }
+      const chunks = []
+      res.on('data', (chunk) => chunks.push(chunk))
+      res.on('end', () => {
+        const latencyMs = Date.now() - startedAt
+        const text = Buffer.concat(chunks).toString('utf8')
+        let body
+        try {
+          body = JSON.parse(text)
+        } catch {
+          return finish({
+            up: false,
+            latencyMs,
+            fingerprint: got,
+            fingerprintMatch: got && expected ? normalizeFingerprint(got) === expected : null,
+            error: { code: 'E_PEER_BAD_RESPONSE', message: `peer /health returned non-JSON (${res.statusCode})` }
+          })
+        }
+        const match = got && expected ? normalizeFingerprint(got) === expected : null
+        if (res.statusCode !== 200) {
+          return finish({
+            up: false,
+            latencyMs,
+            status: res.statusCode,
+            fingerprint: got,
+            fingerprintMatch: match,
+            error: { code: 'E_PEER_BAD_RESPONSE', message: `peer /health returned ${res.statusCode}` }
+          })
+        }
+        if (match === false) {
+          const health = normalizePeerHealth(body)
+          return finish({
+            up: true,
+            latencyMs,
+            fingerprint: got,
+            fingerprintMatch: false,
+            ...health,
+            error: {
+              code: 'E_PEER_PIN_MISMATCH',
+              message: 'peer certificate does not match the fingerprint stored at pairing time — refuse to trust it'
+            }
+          })
+        }
+        const health = normalizePeerHealth(body)
+        return finish({ up: !health.error, latencyMs, fingerprint: got, fingerprintMatch: match, ...health })
+      })
+    })
+    const timer = setTimeout(() => {
+      try {
+        req.destroy(new Error('timeout'))
+      } catch {
+        /* ignore */
+      }
+      finish({
+        up: false,
+        latencyMs: Date.now() - startedAt,
+        error: { code: 'E_PEER_TIMEOUT', message: `peer did not answer within ${timeoutMs} ms` }
+      })
+    }, timeoutMs)
+    req.on('error', (error) => {
+      finish({
+        up: false,
+        latencyMs: Date.now() - startedAt,
+        error: {
+          code: error?.code === 'ECONNRESET' || error?.code === 'ECONNREFUSED' ? 'E_PEER_OFFLINE' : 'E_PEER_TLS',
+          message: `${base} unreachable (${error?.code || error?.message || error})`,
+          detail: error?.code || null
+        }
+      })
+    })
+    req.setTimeout(timeoutMs, () => req.destroy(new Error('timeout')))
+    req.end()
+  })
+}
+
+/** Probe one local DSH instance through its host bridge. */
+export async function probeInstance({ config, home, log, entry, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  const startedAt = Date.now()
+  const base = { id: entry.id, label: entry.label || entry.id, url: entry.url, profileDir: entry.profileDir || '' }
+  try {
+    const client = createHostClient({ config, home, log, instance: entry.id })
+    await client.ping()
+    const [self, tools, agents] = await Promise.all([client.self(), client.tools(), client.agents()])
+    const toolList = tools?.tools || []
+    const agentList = agents?.agents || []
+    return {
+      ...base,
+      up: true,
+      latencyMs: Date.now() - startedAt,
+      plugin: self?.plugin || null,
+      hostname: self?.node?.hostname || null,
+      platform: self?.node?.platform || null,
+      pid: self?.node?.pid || null,
+      toolCount: toolList.length,
+      agents: agentList.map((agent) => ({ id: agent.id, status: agent.status, title: agent.title || '' })),
+      runningAgents: agentList.filter((agent) => agent.status === 'running').length
+    }
+  } catch (error) {
+    return {
+      ...base,
+      up: false,
+      latencyMs: Date.now() - startedAt,
+      error: { code: error?.code || 'E_HOST_OFFLINE', message: error?.message || String(error) }
+    }
+  }
+}
+
+/**
+ * Probe this node's OWN serve endpoint (`/health`) — the hop every peer needs.
+ * The host-bridge probes below only prove the DSH instances are up; when the
+ * local mesh server dies they all still look fine and only the peers look
+ * offline. Reported 2026-10-23: the company endpoint had been down ~3 days
+ * while `self-update status --deep` read clean.
+ */
+export async function probeSelfEndpoint(config, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const node = config?.node || {}
+  const scheme = node.tls?.enabled ? 'https' : 'http'
+  const url = `${scheme}://${node.bind || '127.0.0.1'}:${node.port || 8124}`
+  const probe = await probePeer({ id: 'self', name: 'self', url }, { timeoutMs })
+  return {
+    url,
+    up: probe.up === true,
+    version: probe.version || null,
+    pid: probe.pid ?? null,
+    tools: probe.tools ?? null,
+    uptimeSec: probe.uptimeSec ?? null,
+    error: probe.error || null
+  }
+}
+
+/** Parse the JSON payload of an MCP tool result (remote tools return text content). */
+function parsePeerToolPayload(result) {
+  const block = result?.content?.[0]
+  if (!block || block.type !== 'text') return null
+  try {
+    return JSON.parse(block.text)
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Ask a paired peer for its OWN host instances through the MCP `host_instances`
+ * tool, so the cluster view can show all machines' DSH instances in one place.
+ * This is best-effort: a peer that denies the tool (or has no token) still gets
+ * its /health row — we just record `instancesError` instead of failing the view.
+ */
+async function probePeerInstances(peer, timeoutMs) {
+  if (!peer?.token) {
+    return { error: { code: 'E_PEER_NO_TOKEN', message: 'peer has no outbound token in peers.json — cannot list its host instances' } }
+  }
+  try {
+    const result = await callPeerTool(peer, { tool: 'host_instances', args: {}, timeoutMs })
+    const body = parsePeerToolPayload(result.result)
+    const rows = Array.isArray(body?.instances) ? body.instances : []
+    return {
+      instances: rows.map((row) => ({
+        id: row.id,
+        label: row.label || row.id,
+        url: row.url,
+        alive: row.alive === true
+      }))
+    }
+  } catch (error) {
+    return { error: { code: error?.code || 'E_PEER_CALL_FAILED', message: error?.message || String(error) } }
+  }
+}
+
+/**
+ * @param {{ probeSelf?: boolean }} options `probeSelf: true` additionally probes
+ * this node's own serve endpoint, so a CLI running *outside* the server can tell
+ * "my host bridges are fine" apart from "my node is actually serving peers".
+ * Off by default: callers inside the server would only measure themselves, and
+ * tests use `node.port = 0`.
+ */
+export async function clusterReport({ config, home, log, peers = [], timeoutMs = DEFAULT_TIMEOUT_MS, probeSelf = false } = {}) {
+  const endpoint = probeSelf ? await probeSelfEndpoint(config, { timeoutMs }) : null
+  const instances = []
+  for (const entry of hostInstances(config)) {
+    if (entry.enabled === false) continue
+    instances.push(await probeInstance({ config, home, log, entry, timeoutMs }))
+  }
+  const peerReports = await Promise.all(
+    peers.map(async (peer) => {
+      const report = await probePeer(peer, { timeoutMs })
+      if (report.up === true && !report.error) {
+        const remote = await probePeerInstances(peer, timeoutMs)
+        report.instances = remote.instances || []
+        if (remote.error) report.instancesError = remote.error
+      }
+      return report
+    })
+  )
+
+  const issues = []
+  if (endpoint && !endpoint.up) {
+    issues.push(`local endpoint ${endpoint.url} down: ${endpoint.error?.code || 'E_ENDPOINT_OFFLINE'}`)
+  }
+  for (const instance of instances) {
+    if (!instance.up) issues.push(`instance ${instance.id} down: ${instance.error?.code || 'E_HOST_OFFLINE'}`)
+    else if (instance.runningAgents > 0) issues.push(`instance ${instance.id} has ${instance.runningAgents} running agent(s)`)
+  }
+  for (const peer of peerReports) {
+    if (!peer.up) issues.push(`peer ${peer.name || peer.id || peer.url} down: ${peer.error?.code || 'E_PEER_OFFLINE'}`)
+    else if (peer.fingerprintMatch === false) issues.push(`peer ${peer.name || peer.id} fingerprint mismatch`)
+    else if (peer.instancesError) {
+      issues.push(`peer ${peer.name || peer.id} host instances unavailable: ${peer.instancesError.code}`)
+    }
+  }
+
+  // Flatten remote instances next to local ones so one call shows the whole
+  // cluster (four DSH instances on two machines). `scope` says where a row lives.
+  const localRows = instances.map((instance) => ({
+    scope: 'local',
+    id: instance.id,
+    label: instance.label,
+    up: instance.up === true,
+    toolCount: instance.toolCount ?? null,
+    pid: instance.pid ?? null
+  }))
+  const remoteRows = []
+  for (const peer of peerReports) {
+    for (const row of peer.instances || []) {
+      remoteRows.push({
+        scope: peer.name || peer.id,
+        id: row.id,
+        label: row.label,
+        url: row.url,
+        up: row.alive === true,
+        remote: true
+      })
+      if (row.alive !== true) issues.push(`peer ${peer.name || peer.id} instance ${row.id} down`)
+    }
+  }
+
+  const anyInstanceUp = instances.some((instance) => instance.up)
+  const remoteAllAlive = remoteRows.every((row) => row.up === true)
+  const allUp =
+    (!endpoint || endpoint.up) &&
+    instances.every((instance) => instance.up) &&
+    peerReports.every((peer) => peer.up && peer.fingerprintMatch !== false) &&
+    remoteAllAlive
+
+  return {
+    node: { version: MESH_VERSION, home, instances: instances.length, peers: peerReports.length },
+    summary: { local: localRows.length, remote: remoteRows.length, total: localRows.length + remoteRows.length },
+    endpoint,
+    instances,
+    remoteInstances: remoteRows,
+    cluster: [...localRows, ...remoteRows],
+    peers: peerReports,
+    verdict:
+      endpoint && !endpoint.up
+        ? 'down'
+        : instances.length === 0
+          ? 'unknown'
+          : allUp
+            ? 'ok'
+            : anyInstanceUp
+              ? 'degraded'
+              : 'down',
+    issues
+  }
+}
+