dsh-mesh-node 0.0.0-stage → 0.0.2

package/src/core/peer-doctor.js

@@ -0,0 +1,294 @@
+/**
+ * Diagnose one paired peer end to end: can this machine reach it, does a DSH
+ * profile mount it, and do the running DSH instances actually expose its tools?
+ *
+ * Every check corresponds to a failure mode observed in the field:
+ * - missing certificate pin / token -> refused handshake or 401;
+ * - https peer without NODE_EXTRA_CA_CERTS in the DSH process -> silent
+ *   "mcp-client(home): server is disconnected" and zero tools;
+ * - overlay mounted but zero tools -> the in-DSH client failed to start
+ *   (DSH hot-reloads cordis.patch.yml, so a restart is the last resort, not
+ *   the first fix);
+ * - ACL/upgrade drift -> tools exist but calls return E_DENIED on the peer.
+ *
+ * The command is read-only: it never starts, stops, or reconfigures anything.
+ */
+import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+import { loadConfig, peersPath } from './config.js'
+import { loadPeers } from './pairing.js'
+import { createHostClient, hostInstances } from './host-agent.js'
+import { connectPeer } from './peer-client.js'
+
+const quiet = { debug() {}, info() {}, warn() {}, error() {} }
+
+/** DSH state directories worth scanning, most specific first. */
+export function dshHomeCandidates(env = process.env) {
+  const homes = []
+  const push = (value) => {
+    if (value && !homes.includes(value)) homes.push(value)
+  }
+  push(env.DSH_HOME)
+  for (const suffix of ['.dsh0', '.dsh1', '.dsh2', '.dsh3', '.dsh']) push(join(homedir(), suffix))
+  return homes
+}
+
+/** Which transport the entry around `lineIndex` declares (search a small window). */
+function transportFor(lines, lineIndex) {
+  for (let index = lineIndex; index >= 0 && index >= lineIndex - 25; index -= 1) {
+    const match = lines[index].match(/transport:\s*['"]?([A-Za-z-]+)/)
+    if (match) return match[1]
+    if (index < lineIndex && /^\s*-\s+insert:/.test(lines[index])) break
+  }
+  return 'unknown'
+}
+
+/** Resolve a path for comparison even when it does not exist yet (junction-aware). */
+function canonicalPath(value) {
+  try {
+    return realpathSync(value)
+  } catch {
+    return resolve(value)
+  }
+}
+
+/**
+ * True when an overlay's patch file lives in exactly this DSH profile directory.
+ * An overlay found through another instance's home (or through a `~/.dsh`
+ * junction pointing at `~/.dsh0`) must never be credited to another instance.
+ */
+export function overlayMatchesProfile(overlay, profileDir) {
+  if (!overlay?.patchPath || !profileDir) return false
+  const overlayDir = canonicalPath(dirname(overlay.patchPath))
+  const wanted = canonicalPath(profileDir)
+  return process.platform === 'win32' ? overlayDir.toLowerCase() === wanted.toLowerCase() : overlayDir === wanted
+}
+
+/**
+ * Find DSH profile overlays that mount this peer (matched by serverName).
+ * Pure filesystem read; returns one row per matching overlay.
+ */
+export function findPeerOverlays(peer, { env = process.env, dshHomes = null } = {}) {
+  const names = new Set([peer?.name, peer?.id, `${peer?.name}-mesh`, `${peer?.id}-mesh`].filter(Boolean))
+  const matches = []
+  const seen = new Set()
+  for (const dshHome of dshHomes ?? dshHomeCandidates(env)) {
+    const profilesDir = join(dshHome, 'profiles')
+    if (!existsSync(profilesDir)) continue
+    let profiles
+    try {
+      profiles = readdirSync(profilesDir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const profile of profiles) {
+      if (!profile.isDirectory()) continue
+      const patchPath = join(profilesDir, profile.name, 'cordis.patch.yml')
+      if (!existsSync(patchPath)) continue
+      let text
+      try {
+        text = readFileSync(patchPath, 'utf8')
+      } catch {
+        continue
+      }
+      if (!text.includes('dsh-mcp-client')) continue
+      const lines = text.split(/\r?\n/)
+      for (let index = 0; index < lines.length; index += 1) {
+        const match = lines[index].match(/^\s*serverName:\s*['"]?([^'"\s]+)['"]?\s*$/)
+        if (!match || !names.has(match[1])) continue
+        const key = `${canonicalPath(patchPath)}::${match[1]}`
+        if (seen.has(key)) continue
+        seen.add(key)
+        matches.push({
+          dshHome,
+          profile: profile.name,
+          patchPath,
+          serverName: match[1],
+          transport: transportFor(lines, index)
+        })
+      }
+    }
+  }
+  return matches
+}
+
+function hintForConnectFailure(code) {
+  if (code === 'E_PEER_PIN_MISMATCH') {
+    return 'the peer certificate changed or the stored pin is wrong: re-pair with `peer add` and the fingerprint printed by `pair --code`'
+  }
+  if (code === 'E_PEER_NO_PIN') {
+    return 'https peer without a fingerprint: `peer import --file <name>.yml --fingerprint <sha256>`'
+  }
+  if (code === 'E_PEER_AUTH') {
+    return 'token rejected: re-pair (`peer add`), or the peer revoked the token (`revoke` on that node)'
+  }
+  if (code === 'E_PEER_TIMEOUT') {
+    return 'no answer in time: check the peer is up (`node src/cli.js cluster status`), the frp tunnel, and that `serve` runs there'
+  }
+  return 'check the peer node: `node src/cli.js cluster status` and the peer’s own mesh serve log'
+}
+
+/**
+ * Run all checks and return {verdict, checks, nextSteps}. `verdict` is `fail`
+ * only when a hard requirement (peer record, pin, handshake) fails; mount and
+ * environment findings are `warn` unless they would make in-session tools
+ * silently absent without any explanation.
+ */
+export async function runPeerDoctor({ home, target = null, timeoutMs = 8000, env = process.env, dshHomes = null } = {}) {
+  const checks = []
+  const add = (id, status, detail, fix) => checks.push({ id, status, detail, ...(fix ? { fix } : {}) })
+  const peers = loadPeers(home)
+  const items = peers.items ?? []
+  add(
+    'peers-file',
+    items.length > 0 ? 'pass' : 'fail',
+    `${peersPath(home)}: ${items.length} peer record(s)`,
+    items.length > 0 ? undefined : 'node src/cli.js peer import --file <name>.yml'
+  )
+
+  const peer = target
+    ? items.find((item) => item.name === target || item.id === target)
+    : items.length === 1
+      ? items[0]
+      : null
+  if (!peer) {
+    add(
+      'peer-selection',
+      'fail',
+      target
+        ? `peer "${target}" is not in ${peersPath(home)}`
+        : `several peers are paired (${items.map((item) => item.name).join(', ')}); pass --to <name>`,
+      'node src/cli.js peer list'
+    )
+    return { verdict: 'fail', checks, nextSteps: ['pick a peer with --to <name>'] }
+  }
+  add('peer-selection', 'pass', `peer "${peer.name}" -> ${peer.url}`)
+
+  const secure = /^https:/i.test(peer.url)
+  if (secure) {
+    add(
+      'certificate-pin',
+      peer.certFingerprint ? 'pass' : 'fail',
+      peer.certFingerprint
+        ? `pinned ${String(peer.certFingerprint).slice(0, 23)}…`
+        : 'https peer has no stored fingerprint; the pinned fetch refuses to connect',
+      peer.certFingerprint
+        ? undefined
+        : 'node src/cli.js peer import --file <name>.yml --fingerprint <sha256 from `pair --code`>'
+    )
+  } else {
+    add('certificate-pin', 'pass', 'plain http peer — no TLS trust needed (not recommended across machines)')
+  }
+
+  const overlays = findPeerOverlays(peer, { env, dshHomes })
+  const httpOverlay = overlays.find((entry) => entry.transport !== 'stdio')
+  const overlayDetail = overlays.map((entry) => `${entry.dshHome}/profiles/${entry.profile} (${entry.transport})`).join('; ')
+  const caEnv = env.NODE_EXTRA_CA_CERTS || ''
+  if (secure && httpOverlay && !caEnv) {
+    add(
+      'dsh-ca-env',
+      'warn',
+      'NODE_EXTRA_CA_CERTS unset in this process and an overlay uses streamable-http: the in-DSH client cannot verify the self-signed peer and stays disconnected',
+      `switch it to the stdio bridge: node src/cli.js peer patch --transport stdio --to ${peer.name}`
+    )
+  } else if (secure) {
+    add(
+      'dsh-ca-env',
+      'pass',
+      caEnv ? `NODE_EXTRA_CA_CERTS=${caEnv}` : 'not needed: the stdio bridge pins the peer certificate itself'
+    )
+  }
+
+  if (overlays.length === 0) {
+    add(
+      'dsh-overlay',
+      'warn',
+      'no DSH profile overlay mounts this peer, so only CLI calls work',
+      `node src/cli.js peer patch --transport stdio --to ${peer.name}`
+    )
+  } else {
+    add('dsh-overlay', 'pass', overlayDetail)
+  }
+
+  // Did the RUNNING instances actually register the peer tools? This is the only
+  // check that distinguishes "overlay is valid" from "overlay is live".
+  try {
+    const config = loadConfig(home)
+    const instances = hostInstances(config)
+    if (instances.length === 0) {
+      add('dsh-live-tools', 'warn', 'no host bridge configured, so loaded tools cannot be verified', 'node src/cli.js host install --profile <DSH profile>')
+    }
+    for (const entry of instances) {
+      const client = createHostClient({ config, home, log: quiet, instance: entry.id })
+      const alive = await client.ping().catch(() => false)
+      if (!alive) {
+        add(`dsh-${entry.id}`, 'warn', 'host bridge not reachable — its loaded tools cannot be verified')
+        continue
+      }
+      const { tools } = await client.tools().catch(() => ({ tools: [] }))
+      const names = (tools ?? []).map((tool) => tool.name)
+      const mounted = names.filter((name) => name.startsWith(`mcp__${peer.name}__`) || name.startsWith(`mcp__${peer.name}-mesh__`))
+      const ownOverlays = entry.profileDir
+        ? overlays.filter((overlay) => overlayMatchesProfile(overlay, entry.profileDir))
+        : overlays
+      if (mounted.length > 0) {
+        add(`dsh-${entry.id}`, 'pass', `${mounted.length} peer tool(s) registered (e.g. ${mounted[0]})`)
+      } else if (ownOverlays.length > 0) {
+        add(
+          `dsh-${entry.id}`,
+          'warn',
+          `overlay is mounted in ${entry.profileDir} but this running instance exposes 0 "${peer.name}" tools (${names.length} total)`,
+          'DSH hot-reloads cordis.patch.yml (HMR) within seconds; if the tools stay missing, check the mcp-client startup error in the DSH log — restart only as a last resort'
+        )
+      } else {
+        add(
+          `dsh-${entry.id}`,
+          'warn',
+          `no overlay in this instance's profile (${entry.profileDir || 'unknown'}), so it can never expose peer tools (${names.length} tools total)`,
+          entry.profileDir
+            ? `add the peer insert block to ${join(entry.profileDir, 'cordis.patch.yml')} (HMR picks it up, no restart)`
+            : undefined
+        )
+      }
+    }
+  } catch (error) {
+    add('dsh-live-tools', 'warn', `could not inspect running instances: ${error?.message || error}`)
+  }
+
+  let connection
+  const started = Date.now()
+  try {
+    connection = await connectPeer(peer, { timeoutMs })
+    const listed = await connection.client.listTools()
+    add('mcp-handshake', 'pass', `initialized and listed ${(listed.tools ?? []).length} tools in ${Date.now() - started} ms`)
+  } catch (error) {
+    const code = typeof error?.code === 'string' ? error.code : null
+    add('mcp-handshake', 'fail', `${code ? `[${code}] ` : ''}${error?.message || error}`, hintForConnectFailure(code))
+  } finally {
+    if (connection) await connection.close()
+  }
+
+  const verdict = checks.some((check) => check.status === 'fail')
+    ? 'fail'
+    : checks.some((check) => check.status === 'warn')
+      ? 'warn'
+      : 'ok'
+  const nextSteps = []
+  const caMissing = secure && !caEnv
+  if (httpOverlay && caMissing) {
+    nextSteps.push(`switch the overlay to the stdio bridge: node src/cli.js peer patch --transport stdio --to ${peer.name}`)
+  }
+  if (overlays.length === 0) {
+    nextSteps.push(`mount the peer in DSH: node src/cli.js peer patch --transport stdio --to ${peer.name}`)
+  }
+  const staleLive = checks.filter(
+    (check) => check.id.startsWith('dsh-') && check.status === 'warn' && /overlay is mounted in/.test(check.detail)
+  )
+  if (staleLive.length > 0) {
+    nextSteps.push(
+      'DSH hot-reloads cordis.patch.yml (HMR): re-run this doctor after ~10 s; restart the instance only if the tools stay missing (read its mcp-client startup error first)'
+    )
+  }
+  return { verdict, peer: { name: peer.name, url: peer.url, secure }, checks, nextSteps }
+}

package/src/core/peer-http.js

@@ -0,0 +1,61 @@
+/**
+ * Minimal HTTP(S) JSON POST used for peer pairing.
+ *
+ * 两个安全选项：
+ * - `caPath`：信任一张自签证书（标准信任链校验）。
+ * - `fingerprint`：TOFU 固定指纹 —— 先不判信任链（自签必然不过），抓 socket 上的
+ *   对端证书算 SHA-256，再和人工核对过的指纹比对；不一致直接 `E_PIN_MISMATCH`。
+ *
+ * 抽成独立文件是为了让 e2e 能直接测（cli.js 有 main 副作用，不适合被 import）。
+ */
+import { fingerprintOfSocket, assertFingerprint } from './tls.js'
+
+export async function postJson(urlString, body, { caPath, fingerprint } = {}) {
+  const isHttps = String(urlString).startsWith('https:')
+  const { request } = await import(isHttps ? 'node:https' : 'node:http')
+  const { readFileSync } = await import('node:fs')
+  const options = { method: 'POST', headers: { 'content-type': 'application/json' } }
+  if (isHttps && caPath) options.ca = readFileSync(caPath)
+  // 固定指纹时先不判信任链（自签必然不过），拿到 socket 证书后自己比对指纹。
+  // 这是 TOFU 的标准做法：信任来自「配对码那条可信信道」里带出来的指纹，而不是 CA。
+  if (isHttps && fingerprint) {
+    options.rejectUnauthorized = false
+    // 关键：不能复用 keep-alive 连接 —— 复用时会话已建立，secureConnect 不会再触发，
+    // 指纹校验就会被跳过。每次固定指纹请求都开新连接。
+    options.agent = false
+  }
+  return await new Promise((resolvePromise, rejectPromise) => {
+    const req = request(urlString, options, (res) => {
+      let text = ''
+      res.setEncoding('utf8')
+      res.on('data', (chunk) => {
+        text += chunk
+      })
+      res.on('end', () => {
+        let parsed
+        try {
+          parsed = JSON.parse(text)
+        } catch {
+          parsed = { raw: text }
+        }
+        resolvePromise({ status: res.statusCode, body: parsed, fingerprint: req.__meshFingerprint })
+      })
+    })
+    if (isHttps && fingerprint) {
+      req.on('socket', (socket) => {
+        socket.once('secureConnect', () => {
+          try {
+            const got = fingerprintOfSocket(socket)
+            assertFingerprint(fingerprint, got)
+            req.__meshFingerprint = got
+          } catch (error) {
+            req.destroy(error)
+          }
+        })
+      })
+    }
+    req.setTimeout(20000, () => req.destroy(new Error('timeout')))
+    req.on('error', rejectPromise)
+    req.end(JSON.stringify(body ?? {}))
+  })
+}

package/src/core/repair.js

@@ -0,0 +1,93 @@
+import { isAbsolute, join, resolve, sep } from 'node:path'
+
+/**
+ * Pure helpers for the repair toolkit (M7 step 3). Keeping the path/validation
+ * logic here means the MCP tool, the CLI and the selftest all agree on what a
+ * legal plugin payload is — writing into a DSH profile is the one operation that
+ * can brick an instance, so it gets validated in exactly one place.
+ */
+
+export const PLUGIN_NAME_RE = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]{0,63}$/i
+
+export function repairError(code, message, extra = {}) {
+  const error = new Error(message)
+  error.code = code
+  Object.assign(error, extra)
+  return error
+}
+
+/** Directory a plugin package occupies inside a profile's node_modules. */
+export function pluginRoot(profileDir, name) {
+  return join(profileDir, 'node_modules', ...String(name).split('/'))
+}
+
+/**
+ * Validate and normalise a plugin file payload.
+ * `path` is always a forward-slash relative path inside the package directory.
+ */
+export function normalizePluginFiles(files, { maxFiles = 20, maxFileBytes = 262144 } = {}) {
+  if (!Array.isArray(files) || files.length === 0) {
+    throw repairError('E_INVALID_ARG', 'files must be a non-empty array of {path, content}')
+  }
+  if (files.length > maxFiles) {
+    throw repairError('E_INVALID_ARG', `too many files: ${files.length} > ${maxFiles}`)
+  }
+  const seen = new Set()
+  return files.map((file, index) => {
+    const raw = typeof file?.path === 'string' ? file.path : ''
+    const rel = raw.replace(/\\/g, '/').replace(/^\.\//, '')
+    if (!rel) throw repairError('E_INVALID_ARG', `files[${index}].path is required`)
+    if (isAbsolute(rel) || /^[a-z]:/i.test(rel)) {
+      throw repairError('E_INVALID_ARG', `files[${index}].path must be relative: ${raw}`)
+    }
+    const parts = rel.split('/').filter((part) => part.length > 0)
+    if (parts.length === 0 || parts.some((part) => part === '.' || part === '..')) {
+      throw repairError('E_INVALID_ARG', `files[${index}].path escapes the package root: ${raw}`)
+    }
+    const content = typeof file?.content === 'string' ? file.content : null
+    if (content === null) throw repairError('E_INVALID_ARG', `files[${index}].content must be a string`)
+    const bytes = Buffer.byteLength(content, 'utf8')
+    if (bytes > maxFileBytes) {
+      throw repairError('E_INVALID_ARG', `files[${index}] is ${bytes} bytes > limit ${maxFileBytes}`)
+    }
+    const key = parts.join('/').toLowerCase()
+    if (seen.has(key)) throw repairError('E_INVALID_ARG', `duplicate file path: ${rel}`)
+    seen.add(key)
+    return { rel: parts.join('/'), abs: parts.join(sep), content, bytes }
+  })
+}
+
+/** True when the profile patch already wires a plugin by name or id. */
+export function patchHasPlugin(patchText, name) {
+  const text = String(patchText || '')
+  if (!text) return false
+  const escaped = String(name).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  return new RegExp(`(^|[\\s-])(name|id):\\s*['"]?${escaped}['"]?\\s*$`, 'm').test(text)
+}
+
+export function buildPatchBlock(name) {
+  return `- insert:\n    - id: ${name}\n      name: ${name}\n`
+}
+
+/**
+ * Append a `- insert:` block unless the plugin is already wired.
+ * A non-empty, non-`[]` patch is preserved and flagged for backup by the caller.
+ */
+export function applyPatchInsert(patchText, name) {
+  const current = String(patchText ?? '')
+  if (patchHasPlugin(current, name)) return { text: current, changed: false, backup: false }
+  const trimmed = current.trim()
+  const needsBackup = Boolean(trimmed && trimmed !== '[]')
+  const header = needsBackup ? `${current.replace(/\s+$/, '')}\n` : ''
+  return { text: header + buildPatchBlock(name), changed: true, backup: needsBackup }
+}
+
+/** Resolve `candidate` and assert it stays inside `root` (profile confinement). */
+export function assertInside(root, candidate) {
+  const base = resolve(root)
+  const target = resolve(candidate)
+  if (target !== base && !target.startsWith(base + sep)) {
+    throw repairError('E_INVALID_ARG', `path escapes the allowed root: ${target}`)
+  }
+  return target
+}

package/src/core/restart-policy.js

@@ -0,0 +1,21 @@
+// @generated 2026-10-27 repair 重启命令的**运行期**白名单（不只是编辑期校验）
+// [why] 2026-10-27 P2 安全收紧：`repair.restartScripts` 是「配置即白名单」，但配置可以被手改/被别的工具写。
+//       如果只在写配置时校验，手改 config 仍能塞任意命令。所以 service_restart **执行前**也过同一套规则：
+//       只允许调用 mesh 自己的重启脚本 / 看护脚本 / autostart 的 start-dshN.vbs|cmd，且禁止 shell 元字符。
+// 归宿：reusable（dsh-mesh/src/core/）
+export const RESTART_TARGET_RE = /\b(restart-dsh-instance\.mjs|instance-watchdog\.mjs|start-dsh\d*\.(vbs|cmd))\b/
+export const MAX_RESTART_COMMAND_LEN = 600
+/** Shell metacharacters that would let a "restart" command become arbitrary code. */
+const FORBIDDEN_META_RE = /[|&;<>`$(){}]/
+
+export function validateRestartCommand(command) {
+  const text = String(command || '').trim()
+  if (!text) return { ok: false, reason: 'command is empty' }
+  if (text.length > MAX_RESTART_COMMAND_LEN) return { ok: false, reason: `command longer than ${MAX_RESTART_COMMAND_LEN} chars` }
+  const meta = FORBIDDEN_META_RE.exec(text)
+  if (meta) return { ok: false, reason: `command contains shell metacharacter "${meta[0]}" — only plain quoted paths/args are allowed` }
+  if (!RESTART_TARGET_RE.test(text)) {
+    return { ok: false, reason: 'command must reference restart-dsh-instance.mjs / instance-watchdog.mjs / start-dsh<N>.vbs|cmd' }
+  }
+  return { ok: true }
+}

package/src/core/result.js

@@ -0,0 +1,29 @@
+/** Uniform tool result helpers: text content only (M1 keeps no outputSchema, so no structuredContent). */
+export function ok(data) {
+  return { content: [{ type: 'text', text: typeof data === 'string' ? data : JSON.stringify(data, null, 2) }] }
+}
+
+export function fail(code, message, extra = {}) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify({ code, message, retryable: false, ...extra }, null, 2)
+      }
+    ]
+  }
+}
+
+export function denied(message, extra) {
+  return fail('E_DENIED', message, extra)
+}
+export function invalidArg(message, extra) {
+  return fail('E_INVALID_ARG', message, extra)
+}
+export function notFound(message, extra) {
+  return fail('E_NOT_FOUND', message, extra)
+}
+export function internal(message, extra) {
+  return fail('E_INTERNAL', message, { retryable: true, ...extra })
+}

package/src/core/sakura-api.js

@@ -0,0 +1,103 @@
+// SakuraFrp 账号级隧道状态（只读）：读本机 Launcher token + 调 api.natfrp.com/v4/tunnels（+ /v4/nodes 解析节点域名）
+// 用途：PC 端即可看到同账号下所有设备（含手机）的樱花隧道在线状态，不依赖对端上报。
+// 安全：token 只在内存中使用，绝不写日志/输出；结果缓存 60s。
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const API_BASE = 'https://api.natfrp.com'
+// 2026-11-09：动态检测——默认 5s 重新拉取账号隧道状态（SAKURA_POLL_MS 可覆盖；<=3s 会被抬到 3s）
+const CACHE_TTL_MS = Math.max(3000, Number(process.env.SAKURA_POLL_MS || 5000))
+
+let cache = { at: 0, data: null }
+
+/** 本机 Launcher 配置里的账号 token（Windows / Linux / macOS 常见路径，或 SAKURA_TOKEN 环境变量）。 */
+function findToken() {
+  const candidates = [
+    'C:/ProgramData/SakuraFrpService/config.json',
+    '/var/lib/sakurafrp/config.json',
+    '/ProgramData/SakuraFrpService/config.json',
+    join(homedir(), '.config', 'sakura-frp', 'config.json'),
+    join(homedir(), '.config', 'sakurafrp', 'config.json')
+  ]
+  for (const file of candidates) {
+    try {
+      const cfg = JSON.parse(readFileSync(file, 'utf8'))
+      if (cfg && cfg.token) return { token: String(cfg.token), source: file }
+    } catch {
+      /* try next */
+    }
+  }
+  if (process.env.SAKURA_TOKEN) return { token: process.env.SAKURA_TOKEN, source: 'env:SAKURA_TOKEN' }
+  return null
+}
+
+async function apiGet(path, token) {
+  const res = await fetch(API_BASE + path, {
+    headers: { Authorization: 'Bearer ' + token, accept: 'application/json', 'user-agent': 'dsh-mesh-sakura' },
+    signal: AbortSignal.timeout(12_000)
+  })
+  if (!res.ok) throw new Error('HTTP ' + res.status)
+  return res.json()
+}
+
+/** 隧道名 → 设备 key 的猜测映射（名字里含设备名时用）。 */
+function deviceKeyOf(name) {
+  const n = String(name || '')
+  if (!n) return null
+  let h = 0
+  for (const ch of n) h = (h * 31 + ch.codePointAt(0)) >>> 0
+  return 'dev' + (h % 1000)
+}
+
+/**
+ * 账号级樱花隧道列表 + 节点域名。失败返回 { available:false, error }，不抛异常。
+ * @param {{ttlMs?:number, token?:string}} [opts]
+ */
+export async function collectSakuraAccount({ ttlMs = CACHE_TTL_MS, token } = {}) {
+  if (!token && cache.data && Date.now() - cache.at < ttlMs) return cache.data
+  const found = token ? { token, source: 'arg' } : findToken()
+  if (!found) {
+    const data = { available: false, error: '本机未找到 Sakura Launcher token（config.json / SAKURA_TOKEN）', generatedAt: new Date().toISOString() }
+    cache = { at: Date.now(), data }
+    return data
+  }
+  try {
+    const [tunnels, nodes] = await Promise.all([apiGet('/v4/tunnels', found.token), apiGet('/v4/nodes', found.token)])
+    const list = (Array.isArray(tunnels) ? tunnels : []).map((t) => {
+      const node = nodes && nodes[String(t.node)] ? nodes[String(t.node)] : {}
+      const remote = t.remote == null ? '' : String(t.remote)
+      return {
+        id: t.id,
+        name: t.name,
+        type: t.type,
+        nodeId: t.node,
+        nodeName: node.name || '',
+        host: node.host || '',
+        remotePort: remote,
+        localIp: t.local_ip || '',
+        localPort: t.local_port == null ? null : Number(t.local_port),
+        online: t.online === true,
+        status: t.status == null ? null : Number(t.status),
+        statusReason: t.status_reason || '',
+        deviceKey: deviceKeyOf(t.name),
+        addr: (node.host || '') + (remote ? ':' + remote : '')
+      }
+    })
+    const data = {
+      available: true,
+      source: found.source,
+      generatedAt: new Date().toISOString(),
+      total: list.length,
+      online: list.filter((t) => t.online).length,
+      tunnels: list,
+      error: null
+    }
+    cache = { at: Date.now(), data }
+    return data
+  } catch (error) {
+    const data = { available: false, error: String(error?.message || error), generatedAt: new Date().toISOString(), source: found.source }
+    cache = { at: Date.now(), data }
+    return data
+  }
+}