dsh-mesh-node 0.0.3 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mesh-node",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Mesh server for dsh-mesh: expose a machine to peer DSH nodes over MCP/HTTPS, with delegation and optional desktop-control tools.",
   "type": "module",
   "private": false,

package/src/cli.js

@@ -521,23 +521,66 @@ async function main(argv) {
 
   if (cmd === 'token') {
     const sub = argv[1] || 'list'
-    const { addInboundToken, loadSecrets } = await import('./core/config.js')
+    const { addInboundToken, loadSecrets, setTokenRole, migrateTokensToRoles } = await import('./core/config.js')
+    const { ROLE_NAMES, isRole, describeRole } = await import('./core/roles.js')
     if (sub === 'list') {
       const secrets = loadSecrets(home)
-      const rows = (secrets.inbound || []).map((entry) => ({ id: entry.id, note: entry.note || '', acl: entry.acl || null }))
+      const rows = (secrets.inbound || []).map((entry) => ({
+        id: entry.id,
+        note: entry.note || '',
+        role: entry.role || null,
+        roleHint: entry.role ? describeRole(entry.role) : (entry.acl ? '显式 ACL（legacy）' : '继承节点 ACL'),
+        acl: entry.acl || null
+      }))
       console.log(JSON.stringify(rows, null, 2))
       return 0
     }
+    if (sub === 'set-role') {
+      const id = argv[2]
+      const role = argValue(argv, '--role', '')
+      const yes = argv.includes('--yes')
+      if (!id || !isRole(role)) {
+        console.error(`usage: node src/cli.js token set-role <id> --role <${ROLE_NAMES.join('|')}> [--yes]`)
+        return 1
+      }
+      if (!yes) {
+        console.log(JSON.stringify({ dryRun: true, id, role, description: describeRole(role) }, null, 2))
+        console.log('加 --yes 才写入 secrets.json（热重载，无需重启）')
+        return 0
+      }
+      const r = setTokenRole({ home, id, role })
+      console.log(JSON.stringify({ ...r, description: describeRole(role) }, null, 2))
+      return 0
+    }
+    if (sub === 'migrate-roles') {
+      const yes = argv.includes('--yes')
+      const r = migrateTokensToRoles({ home, dryRun: !yes })
+      console.log(JSON.stringify(r, null, 2))
+      if (!yes) console.log('加 --yes 才真正迁移（迁移前自动备份 secrets.json）')
+      return 0
+    }
     if (sub === 'add') {
       const id = argValue(argv, '--id', undefined)
       const note = argValue(argv, '--note', 'narrow token')
       const allowRaw = argValue(argv, '--allow', '')
       const fsRootsRaw = argValue(argv, '--fs-roots', '')
+      const roleRaw = argValue(argv, '--role', '')
       const yes = argv.includes('--yes')
+      if (roleRaw && !isRole(roleRaw)) {
+        console.error(`unknown role: ${roleRaw}（可选：${ROLE_NAMES.join(', ')}）`)
+        return 1
+      }
       const acl = {}
-      if (allowRaw) acl.allow = allowRaw.split(',').map((s) => s.trim()).filter(Boolean)
+      if (!roleRaw && allowRaw) acl.allow = allowRaw.split(',').map((s) => s.trim()).filter(Boolean)
+      if (roleRaw && allowRaw) console.error('⚠️ 同时给了 --role 和 --allow：以角色能力包为准，--allow 被忽略')
       if (fsRootsRaw) acl.fsRoots = fsRootsRaw.split(';').map((s) => s.trim()).filter(Boolean)
-      const plan = { id: id || '(auto: token-<random>)', note, acl: Object.keys(acl).length ? acl : '(inherit node ACL)' }
+      const plan = {
+        id: id || '(auto: token-<random>)',
+        note,
+        role: roleRaw || null,
+        roleDescription: roleRaw ? describeRole(roleRaw) : undefined,
+        acl: Object.keys(acl).length ? acl : '(inherit node ACL)'
+      }
       if (!yes) {
         console.log('（dry-run）将新增 inbound token：')
         console.log(JSON.stringify(plan, null, 2))
@@ -545,12 +588,12 @@ async function main(argv) {
         return 0
       }
       const finalId = id || `token-${Math.random().toString(16).slice(2, 10)}`
-      const created = addInboundToken({ home, id: finalId, note, acl: Object.keys(acl).length ? acl : undefined })
-      console.log(JSON.stringify({ id: created.id, token: created.token, acl: plan.acl, note }, null, 2))
+      const created = addInboundToken({ home, id: finalId, note, role: roleRaw || undefined, acl: Object.keys(acl).length ? acl : undefined })
+      console.log(JSON.stringify({ id: created.id, role: created.role, token: created.token, acl: plan.acl, note }, null, 2))
       console.log('⚠️ token 只显示这一次；只给对端配置用，禁止写进 git / 群聊 / 会分享的文档')
       return 0
     }
-    console.error('usage: node src/cli.js token list | token add [--id ID] [--allow tool1,tool2] [--fs-roots "C:\\a;C:\\b"] [--note TEXT] [--yes]')
+    console.error('usage: node src/cli.js token list | token add [--role observer|controller|node|admin] [--allow a,b] [--fs-roots "C:\\a;C:\\b"] [--note TEXT] [--yes] | token set-role <id> --role <role> [--yes] | token migrate-roles [--yes]')
     return 1
   }
 
@@ -627,15 +670,22 @@ async function main(argv) {
       : `${scheme}://${host}:${port}${config.node.path || '/mcp'}`
     if (argv.includes('--code')) {
       const { createPairingCode } = await import('./core/pairing.js')
+      const { isRole, ROLE_NAMES } = await import('./core/roles.js')
       const { describeCert } = await import('./core/tls.js')
       const rawTtl = Number(argValue(argv, '--ttl', String(config.pairing?.codeTtlSec || 1800)))
       const ttlSec = Number.isFinite(rawTtl) ? Math.min(86400, Math.max(60, Math.round(rawTtl))) : 1800
-      const created = createPairingCode({ home, ttlSec })
+      const role = argValue(argv, '--role', 'node')
+      if (!isRole(role)) {
+        console.error(`unknown role: ${role}（可选：${ROLE_NAMES.join(', ')}）`)
+        return 1
+      }
+      const created = createPairingCode({ home, ttlSec, role })
       const cert = scheme === 'https' ? describeCert(home) : null
       console.log(
         JSON.stringify(
           {
             pairingCode: created.code,
+            role: created.role,
             expiresAt: created.expiresAt,
             ttlSec,
             ttlHint: `码 ${Math.round(ttlSec / 60)} 分钟内有效、一次性；想留更久用 --ttl 86400（最长 24 h）`,
@@ -644,6 +694,7 @@ async function main(argv) {
             certFingerprint: cert?.fingerprint256 ?? null,
             nextSteps: [
               `on the peer machine: node src/cli.js peer add --url ${endpoint.replace(/\/mcp$/, '')} --code ${created.code} --name ${config.node.name}`,
+              `role: ${created.role}（对端兑换后获得这个角色；不用再逐工具授权）`,
               scheme === 'https'
                 ? `pass --fingerprint ${describeCert(home).fingerprint256} (or --ca <this node cert.pem>)`
                 : undefined

package/src/core/config.js

@@ -1,8 +1,9 @@
 import { homedir } from 'node:os'
 import { join, resolve, sep, isAbsolute } from 'node:path'
-import { mkdirSync, readFileSync, writeFileSync, existsSync, realpathSync, statSync, renameSync } from 'node:fs'
+import { mkdirSync, readFileSync, writeFileSync, existsSync, realpathSync, statSync, renameSync, copyFileSync } from 'node:fs'
 import { randomBytes, timingSafeEqual } from 'node:crypto'
 import { readJsonFile } from './util.js'
+import { roleAllow, isRole, inferRole } from './roles.js'
 
 export const MESH_VERSION = '0.17.0'
 export const CONFIG_VERSION = 7
@@ -514,10 +515,22 @@ export function rotateToken({ home = meshHome(), id = 'default', note } = {}) {
   return { id, token }
 }
 
-/** Per-token ACL; `null` means "inherit the node-wide acl". */
+/** Per-token ACL；`null` 表示“继承节点 ACL”。
+ *  - token 带 role：允许集合由角色能力包决定（node/admin 继承节点 ACL）
+ *  - token 不带 role：沿用旧的显式 acl.allow（向后兼容）
+ */
 export function peerAclForToken(secrets, tokenId) {
   const entry = (secrets?.inbound || []).find((item) => item?.id === tokenId)
   const acl = entry?.acl
+  if (entry?.role && isRole(entry.role)) {
+    const allowed = roleAllow(entry.role)
+    return {
+      role: entry.role,
+      allow: allowed || undefined,
+      deny: Array.isArray(acl?.deny) ? acl.deny : [],
+      fsRoots: Array.isArray(acl?.fsRoots) ? acl.fsRoots : undefined
+    }
+  }
   if (!acl || typeof acl !== 'object') return null
   return {
     allow: Array.isArray(acl.allow) ? acl.allow : undefined,
@@ -528,18 +541,87 @@ export function peerAclForToken(secrets, tokenId) {
 
 /**
  * Add an inbound token (used by pairing and by `peer` bookkeeping).
- * `acl` is optional: when given the token may only call that subset of tools.
+ * `role` 是推荐方式（observer/controller/node/admin）；`acl` 保留给旧的显式写法。
+ * 带 role 时 acl.allow 被忽略（角色决定允许集合），只保留 deny / fsRoots。
  */
-export function addInboundToken({ home = meshHome(), id, note, acl, token } = {}) {
+export function addInboundToken({ home = meshHome(), id, note, acl, role, token } = {}) {
   if (!id) throw new Error('addInboundToken requires an id')
+  if (role !== undefined && role !== null && !isRole(role)) throw new Error(`unknown role: ${role}`)
   const secrets = loadSecrets(home)
   const existing = (secrets.inbound || []).find((entry) => entry.id === id)
   if (existing) throw new Error(`token id already exists: ${id}`)
   const entry = { id, token: token || newToken(), note: note || 'paired' }
-  if (acl && typeof acl === 'object') entry.acl = acl
+  if (role) entry.role = role
+  if (acl && typeof acl === 'object') {
+    if (role) {
+      const narrowed = { ...acl }
+      delete narrowed.allow
+      if (Object.keys(narrowed).length > 0) entry.acl = narrowed
+    } else {
+      entry.acl = acl
+    }
+  }
   secrets.inbound = [...(secrets.inbound || []), entry]
   saveSecrets(secrets, home)
-  return { id: entry.id, token: entry.token }
+  return { id: entry.id, token: entry.token, role: entry.role || null }
+}
+
+/** 改一个入向 token 的角色（用户/管理员决策；会移除旧的显式 allow，保留 deny/fsRoots）。 */
+export function setTokenRole({ home = meshHome(), id, role } = {}) {
+  if (!id) throw new Error('setTokenRole requires an id')
+  if (!isRole(role)) throw new Error(`unknown role: ${role}`)
+  const secrets = loadSecrets(home)
+  const entry = (secrets.inbound || []).find((item) => item?.id === id)
+  if (!entry) throw new Error(`token id not found: ${id}`)
+  const before = entry.role || null
+  entry.role = role
+  if (entry.acl && typeof entry.acl === 'object') {
+    const narrowed = { ...entry.acl }
+    delete narrowed.allow
+    if (Object.keys(narrowed).length > 0) entry.acl = narrowed
+    else delete entry.acl
+  }
+  saveSecrets(secrets, home)
+  return { id, before, role }
+}
+
+/**
+ * 旧 token 自动迁移到角色（用户无需逐工具操作）。
+ * 规则：observer/controller 子集 → 对应角色；显式 ACL 恰好等于节点 ACL → node；
+ * 其余自定义/奇怪组合保留显式 ACL 并报告（不擅自扩权）。
+ */
+export function migrateTokensToRoles({ home = meshHome(), dryRun = false } = {}) {
+  const secrets = loadSecrets(home)
+  const nodeAllow = (loadConfig(home).acl?.allow || [])
+  const changes = []
+  let mutated = false
+  for (const entry of secrets.inbound || []) {
+    if (entry.role && isRole(entry.role)) continue
+    const allow = Array.isArray(entry.acl?.allow) ? entry.acl.allow : null
+    const role = inferRole(allow, nodeAllow)
+    if (!role) {
+      changes.push({ id: entry.id, role: null, skipped: true, fromTools: allow?.length ?? null })
+      continue
+    }
+    changes.push({ id: entry.id, role, fromTools: allow?.length ?? null })
+    if (!dryRun) {
+      entry.role = role
+      if (entry.acl && typeof entry.acl === 'object') {
+        const narrowed = { ...entry.acl }
+        delete narrowed.allow
+        if (Object.keys(narrowed).length > 0) entry.acl = narrowed
+        else delete entry.acl
+      }
+      mutated = true
+    }
+  }
+  let backup = null
+  if (!dryRun && mutated) {
+    backup = `${secretsPath(home)}.bak-roles-${new Date().toISOString().replace(/[:.]/g, '-')}`
+    copyFileSync(secretsPath(home), backup)
+    saveSecrets(secrets, home)
+  }
+  return { dryRun, backup, changes }
 }
 
 /** Delete an inbound token; the holder's next request fails with 401. */

package/src/core/pairing.js

@@ -1,6 +1,7 @@
 import { createHash, randomInt, timingSafeEqual } from 'node:crypto'
 import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
 import { meshHome, pairingPath, peersPath, ensureHome } from './config.js'
+import { isRole } from './roles.js'
 
 /**
  * One-time pairing codes.
@@ -60,8 +61,9 @@ function readJsonSafe(file) {
  * Create (and persist) a one-time code. Only one code is valid at a time:
  * creating a new one invalidates the previous one.
  */
-export function createPairingCode({ home = meshHome(), ttlSec = 300, note } = {}) {
+export function createPairingCode({ home = meshHome(), ttlSec = 300, note, role = 'node' } = {}) {
   ensureHome(home)
+  if (!isRole(role)) throw new Error(`unknown role: ${role}`)
   const compact = randomCode()
   const now = Date.now()
   const record = {
@@ -71,10 +73,11 @@ export function createPairingCode({ home = meshHome(), ttlSec = 300, note } = {}
     expiresAt: new Date(now + Math.max(30, ttlSec) * 1000).toISOString(),
     attempts: 0,
     used: false,
-    note: note || undefined
+    note: note || undefined,
+    role
   }
   writeJson0600(pairingPath(home), record)
-  return { code: formatCode(compact), expiresAt: record.expiresAt, ttlSec }
+  return { code: formatCode(compact), expiresAt: record.expiresAt, ttlSec, role }
 }
 
 export function readPairingState(home = meshHome()) {
@@ -86,7 +89,8 @@ export function readPairingState(home = meshHome()) {
     attempts: record.attempts || 0,
     used: record.used === true,
     expired: new Date(record.expiresAt).getTime() <= Date.now(),
-    note: record.note
+    note: record.note,
+    role: record.role || 'node'
   }
 }
 
@@ -124,7 +128,7 @@ export function claimPairingCode({ home = meshHome(), code, maxAttempts = 5 } =
   record.used = true
   record.usedAt = new Date().toISOString()
   writeJson0600(pairingPath(home), record)
-  return { ok: true }
+  return { ok: true, role: record.role || 'node' }
 }
 
 /** Peer bookkeeping on the *client* side: who we can talk to, and with which token. */

package/src/core/roles.js

@@ -0,0 +1,109 @@
+// @generated roles：mesh 入向 token 的角色 / 能力包（替代逐工具 ACL）
+// [why] 2026-11-09 事故：手机 controller token 被手工收窄成 5 个工具，导致 9181 次
+//       E_DENIED、委托链路瘫痪半天，最后要用户手工改 secrets.json 才恢复。
+//       角色制：入网时选一次设备角色（observer/controller/node/admin），能力包随代码升级；
+//       旧的逐工具 token 可自动推断迁移，用户不再需要逐工具授权。
+//
+// 原则：
+//   - 角色只做“收窄”，永远不会超过节点 ACL（applyPeerAcl 做交集）
+//   - controller = 协调者：能看状态 + 能委托 + 能操作桌面，但**不能**跨机写/重启/改配置
+//   - node = 继承节点 ACL（现有 PC 节点行为不变）
+//   - admin 预留：目前与 node 等价，真正提权仍需改节点 ACL（用户决策）
+// 注意：本文件不 import config.js（config.js 会 import 本文件，避免循环依赖）。
+
+export const ROLES_VERSION = 1
+
+const OBSERVER = [
+  'mesh_self',
+  'mesh_overview',
+  'mesh_alert',
+  'mesh_audit_tail',
+  'cluster_status',
+  'fs_read',
+  'fs_list',
+  'fs_stat',
+  'fs_stats',
+  'fs_grep',
+  'git_status',
+  'git_log',
+  'git_diff',
+  'repo_scan',
+  'task_status',
+  'task_list',
+  'session_history',
+  'host_instances',
+  'host_self',
+  'host_tools',
+  'host_sessions',
+  'host_logs',
+  'host_agents',
+  'channel_targets',
+  'channel_sessions',
+  'channel_page',
+  'delegate_list',
+  'delegate_status',
+  'delegate_candidates',
+  'repair_status'
+]
+
+const CONTROLLER = [
+  ...OBSERVER,
+  'delegate',
+  'delegate_reply',
+  'delegate_gc',
+  'host_session_create',
+  'host_session_prompt',
+  'pc_action',
+  'pc_app',
+  'pc_window',
+  'pc_browser'
+]
+
+/** @type {Record<string, { allow: string[] | null, description: string }>} */
+export const ROLE_PRESETS = {
+  observer: { allow: OBSERVER, description: '只读观察：状态 / 文件 / git / 日志 / 委托列表' },
+  controller: { allow: CONTROLLER, description: '协调者：观察 + 委托 + 桌面控制（不能跨机写/重启/改配置）' },
+  node: { allow: null, description: '节点：继承本机 ACL（与旧行为一致）' },
+  admin: { allow: null, description: '管理员：预留，当前等同 node（真正提权需改节点 ACL）' }
+}
+
+export const ROLE_NAMES = Object.keys(ROLE_PRESETS)
+
+export function isRole(name) {
+  return ROLE_NAMES.includes(String(name || ''))
+}
+
+/** 角色允许的工具；null 表示“继承节点 ACL”。 */
+export function roleAllow(role) {
+  const preset = ROLE_PRESETS[role]
+  return preset ? preset.allow : null
+}
+
+/** 最小覆盖给定工具集合的角色（用于旧 token 自动迁移）。
+ *  - observer / controller：显式 allow 是角色能力包子集 → 升级到该角色
+ *  - node：显式 allow 恰好等于节点 ACL → node（等价继承）
+ *  - 其他（自定义、或比角色包更宽/更窄的奇怪组合）→ null，保留显式 ACL，由用户决定
+ * @param {string[] | null | undefined} allowList
+ * @param {string[]} [nodeAllow]
+ */
+export function inferRole(allowList, nodeAllow = null) {
+  const allow = Array.isArray(allowList) ? allowList : null
+  if (!allow) return 'node'
+  const covers = (role) => {
+    const preset = ROLE_PRESETS[role]
+    if (!preset || !preset.allow) return false
+    return allow.every((name) => preset.allow.includes(name))
+  }
+  if (covers('observer')) return 'observer'
+  if (covers('controller')) return 'controller'
+  if (Array.isArray(nodeAllow) && nodeAllow.length > 0) {
+    const a = new Set(allow)
+    const b = new Set(nodeAllow)
+    if (a.size === b.size && [...a].every((name) => b.has(name))) return 'node'
+  }
+  return null // 自定义 / 无法安全推断 → 保留显式 ACL
+}
+
+export function describeRole(role) {
+  return ROLE_PRESETS[role]?.description || '自定义 ACL'
+}

package/src/selftest.js

@@ -4,8 +4,9 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { Client } from '@modelcontextprotocol/client'
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/client'
-import { loadSecrets, defaultConfig, configPath, loadConfig, DEFAULT_ALLOW, aclDrift } from './core/config.js'
+import { loadSecrets, defaultConfig, configPath, loadConfig, DEFAULT_ALLOW, aclDrift, peerAclForToken } from './core/config.js'
 import { describeAcl, resolveAclUpdate } from './core/acl.js'
+import { roleAllow, inferRole } from './core/roles.js'
 import { applyPatchInsert, assertInside, normalizePluginFiles, patchHasPlugin, pluginRoot } from './core/repair.js'
 import { hostTokenPath, resolveHostInstance } from './core/host-agent.js'
 import { buildAll, isAllowed } from './tools/index.js'
@@ -849,6 +850,41 @@ export async function runSelftest({ log = console } = {}) {
     assert(!isAllowed(config, 'host_session_archive'), 'host_session_archive must be denied by default')
   })
 
+  await check('roles: controller can delegate but not cross-machine writes/restarts', () => {
+    const allow = roleAllow('controller')
+    assert(allow.includes('delegate') && allow.includes('delegate_status'), 'controller must be able to delegate')
+    assert(allow.includes('pc_action') && allow.includes('fs_read'), 'controller must keep pc_* + read tools')
+    assert(allow.includes('host_session_create') && allow.includes('host_session_prompt'), 'controller must allow the CLI delegation path (session create/prompt)')
+    for (const dangerous of ['host_call', 'service_restart', 'mesh_config_patch', 'fs_write', 'shell_run']) {
+      assert(!allow.includes(dangerous), `controller must not include ${dangerous}`)
+    }
+  })
+
+  await check('roles: observer is read-only and cannot delegate or control', () => {
+    const allow = roleAllow('observer')
+    assert(allow.includes('fs_read') && allow.includes('cluster_status'), 'observer should read')
+    for (const notAllowed of ['delegate', 'pc_action', 'host_call', 'service_restart']) {
+      assert(!allow.includes(notAllowed), `observer must not include ${notAllowed}`)
+    }
+  })
+
+  await check('roles: inferRole maps legacy allow-lists safely', () => {
+    assert(inferRole(['mesh_self', 'fs_read']) === 'observer', 'read-only allow → observer')
+    assert(inferRole(['mesh_self', 'pc_action', 'delegate']) === 'controller', 'pc_*+delegate allow → controller')
+    assert(inferRole(DEFAULT_ALLOW, DEFAULT_ALLOW) === 'node', 'exact node ACL → node')
+    assert(inferRole(['mesh_self', 'shell_run'], DEFAULT_ALLOW) === null, 'unmappable custom ACL stays explicit')
+  })
+
+  await check('roles: peerAclForToken narrows by role and inherits for node', () => {
+    const controller = peerAclForToken({ inbound: [{ id: 'c', role: 'controller' }] }, 'c')
+    assert(controller && controller.role === 'controller', 'role should be reported')
+    assert(controller.allow.includes('delegate') && !controller.allow.includes('host_call'), 'controller allow-list applied')
+    const node = peerAclForToken({ inbound: [{ id: 'n', role: 'node' }] }, 'n')
+    assert(node && node.allow === undefined, 'node role inherits the node ACL')
+    const legacy = peerAclForToken({ inbound: [{ id: 'l', acl: { allow: ['mesh_self'] } }] }, 'l')
+    assert(legacy.allow.length === 1 && legacy.allow[0] === 'mesh_self', 'legacy explicit ACL untouched')
+  })
+
   const failed = results.filter((r) => !r.ok)
   console.log(`\nselftest: ${results.length - failed.length}/${results.length} passed`)
   if (failed.length > 0) {

package/src/server.js

@@ -224,6 +224,7 @@ export async function startMeshServer({ config, secrets, log = console, port, bi
           home: meshHomeDir,
           id: baseId,
           note: `paired ${new Date().toISOString()}`,
+          role: claim.role,
           acl: body?.acl
         })
       } catch {
@@ -231,6 +232,7 @@ export async function startMeshServer({ config, secrets, log = console, port, bi
           home: meshHomeDir,
           id: `${baseId}-${Math.random().toString(36).slice(2, 6)}`,
           note: `paired ${new Date().toISOString()}`,
+          role: claim.role,
           acl: body?.acl
         })
       }
@@ -242,6 +244,7 @@ export async function startMeshServer({ config, secrets, log = console, port, bi
         ok: true,
         token: created.token,
         tokenId: created.id,
+        role: created.role || null,
         node: liveConfig.node?.name || 'local',
         version: MESH_VERSION,
         url: `${scheme}://${listenBind}:${actualPort}${mcpPath}`,