dsh-remote-agent 0.0.0-stage → 0.4.0

package/lib/hub/views.js

@@ -0,0 +1,351 @@
+/**
+ * 视图投影层：把**副机上报的数据**投影成"可以安全交给宿主"的形状。
+ *
+ * ── 为什么需要这一层 ──────────────────────────────────────────────
+ * 副机是一个独立的、可被攻陷的远端。它上报的 handoff / changed / exit / error /
+ * manifest 全部是**不可信输入**：字段集由它决定，它可以往里面塞绝对路径
+ * （回显主机目录结构）、环境变量、诊断信息、甚至凭证片段。
+ *
+ * 宿主有两种消费方，两边的要求一致：**只拿它真正需要的字段**。
+ *   1. 工具返回值 → 进入会话日志 → 后续每个请求都带上（泄漏会被持久化）
+ *   2. Web 面板   → 进入浏览器 → 可能被扩展/调试工具/截图带走
+ *
+ * ── 为什么集中在这一个文件 ────────────────────────────────────────
+ * 曾经散在三处：`node-registry.taskView`、`tools.buildManifestView`、
+ * `ui-routes.*View`。结果 `remote_handoff` 因为"没有对应的 View 函数"就
+ * 裸直出了 `t.handoff` —— 加固做了一半，且是最该加固的那一半（工具路径
+ * 会被写进会话日志）。集中后新增消费方无处可"绕开"投影。
+ *
+ * ── 一条硬规则 ───────────────────────────────────────────────────
+ * 本文件的函数**只做逐字段构造**，永不 spread 输入对象。所有字符串截断，
+ * 所有数字做类型检查，缺失一律给安全默认值。这样副机怎么改它的上报形状，
+ * 都不可能让宿主这边出现"没预料到的字段"。
+ */
+
+/**
+ * 取数组的**最后** n 条，`n <= 0` 回空数组。
+ *
+ * 为什么不用裸 `list.slice(-n)`：`slice(-0)` 等于 `slice(0)`，会把**整条数组**
+ * 都留下 —— 与"不要尾巴"的直觉相反，是个静默的语义反转。`tail` 是公开选项，
+ * 消费方传 0 时应当拿到空尾巴而不是全部（本层原先两处都踩了这个坑）。
+ */
+function tailSlice(list, n) {
+  const want = Number.isFinite(n) ? Math.trunc(n) : 0
+  if (want <= 0) return []
+  return list.slice(-want)
+}
+
+/** 单个 changed 条目：只保留客户端/模型真正会读的四个字段。 */
+export function changedItemView(c) {
+  if (!c || typeof c !== 'object') return null
+  return {
+    op: typeof c.op === 'string' ? c.op : 'unknown',
+    path: typeof c.path === 'string' ? c.path.slice(0, 500) : '',
+    bytes: Number.isFinite(c.bytes) ? c.bytes : 0,
+    deltaBytes: Number.isFinite(c.deltaBytes) ? c.deltaBytes : 0,
+  }
+}
+
+/** changed 数组：投影 + 丢弃非对象元素（否则消费方解引用 c.op 会抛）。 */
+export function changedView(list, { max = 50 } = {}) {
+  if (!Array.isArray(list)) return []
+  return list.slice(0, max).map(changedItemView).filter(Boolean)
+}
+
+/**
+ * 单个 diff 条目：path + unified diff 文本 + truncated 标志。
+ *
+ * diff 文本是副机生成的机器可读输出，但仍按不可信输入对待：
+ * 逐条挑字段 + 长度封顶（单条 16KB，与副机 diff.js 的截断口径一致，
+ * 双保险 —— 副机版本更旧没有截断时，hub 侧兜底）。
+ */
+export function diffItemView(d) {
+  if (!d || typeof d !== 'object') return null
+  if (typeof d.path !== 'string' || d.path === '') return null
+  if (typeof d.diff !== 'string' || d.diff === '') return null
+  return {
+    path: d.path.slice(0, 500),
+    diff: d.diff.slice(0, 16 * 1024),
+    truncated: d.truncated === true,
+  }
+}
+
+/** diffs 数组：投影 + 封顶条数（与副机 buildDiffs 的 12 文件上限同口径）。 */
+export function diffsView(list, { max = 12 } = {}) {
+  if (!Array.isArray(list)) return []
+  return list.slice(0, max).map(diffItemView).filter(Boolean)
+}
+
+/**
+ * 单个进度条目：只留 `phase` / `detail` / `at`。
+ *
+ * 与 changedItemView 同理，progressTail 也是副机上报的数组（见下方
+ * progressTailView 的说明），元素必须逐字段投影后才能给消费方解引用。
+ */
+export function progressItemView(p) {
+  if (!p || typeof p !== 'object') return null
+  return {
+    phase: typeof p.phase === 'string' ? p.phase : 'progress',
+    detail: typeof p.detail === 'string' ? p.detail.slice(0, 500) : '',
+    at: Number.isFinite(p.at) ? p.at : null,
+  }
+}
+
+/**
+ * 进度尾巴：投影 + 丢弃非对象元素，保留**最后** tail 条。
+ *
+ * 为什么不能只 `slice(-tail)`（原实现，本层唯一的裸透传）：
+ * progressTail 同样来自副机 —— `node-registry.applyView()` 把 task/sync 里的
+ * `view.progressTail` 原样存下，只有 task/progress 帧那条路是自己构造 entry。
+ * 而两个消费方都直接解引用元素：
+ *   - `lib/hub/tools.js` 的 remote_status 渲染：`p.phase` / `p.detail`
+ *   - `lib/hub/subagent-provider.js` 的兜底文本：`p.phase` / `p.detail`
+ * 副机上报一个 `null` 元素就能让它们抛 TypeError。tools 那条会让渲染失败；
+ * subagent 那条更隐蔽 —— 异常被 provider 的兜底 catch 吞掉，于是一个**已完成**
+ * 的任务被上报成"未完成：Cannot read properties of null"。这既是崩溃源，
+ * 也违反 remote_status 自己声明的输出 schema（`items: { type: 'object' }`）。
+ *
+ * `tail <= 0` 回空数组（注意 `slice(-0)` 会把整条数组都留下，不是"不要尾巴"）。
+ */
+export function progressTailView(list, { tail = 6, max = 20 } = {}) {
+  if (!Array.isArray(list)) return []
+  const cap = Number.isFinite(max) ? Math.trunc(max) : Infinity
+  const want = Number.isFinite(tail) ? Math.trunc(tail) : 0
+  const n = Math.min(want, cap)
+  if (n <= 0) return []
+  return tailSlice(list, n).map(progressItemView).filter(Boolean)
+}
+
+/** exit 摘要：副机可能往里塞诊断字段，只留可执行的语义。 */
+export function exitView(e) {
+  if (!e || typeof e !== 'object') return null
+  return {
+    code: Number.isFinite(e.code) ? e.code : null,
+    timedOut: e.timedOut === true,
+    aborted: e.aborted === true,
+    runner: typeof e.runner === 'string' ? e.runner : '',
+    toolCalls: Number.isFinite(e.toolCalls) ? e.toolCalls : 0,
+  }
+}
+
+/** error：只留稳定 code 与截断后的消息。 */
+export function errorView(e) {
+  if (!e || typeof e !== 'object') return null
+  return {
+    code: typeof e.code === 'string' ? e.code : '',
+    message: typeof e.message === 'string' ? e.message.slice(0, 500) : '',
+  }
+}
+
+/** 节点：不含 hello / conn 等内部对象。 */
+export function nodeView(n) {
+  if (!n || typeof n !== 'object') return null
+  return {
+    nodeId: typeof n.nodeId === 'string' ? n.nodeId : '',
+    online: n.online === true,
+    os: typeof n.os === 'string' ? n.os : 'unknown',
+    arch: typeof n.arch === 'string' ? n.arch : 'unknown',
+    agentMode: n.agentMode === true,
+    roots: Array.isArray(n.roots) ? n.roots.filter((r) => typeof r === 'string') : [],
+    caps: Array.isArray(n.caps) ? n.caps.filter((c) => typeof c === 'string') : [],
+    since: Number.isFinite(n.since) ? n.since : null,
+    lastSeen: Number.isFinite(n.lastSeen) ? n.lastSeen : null,
+    taskCount: Number.isFinite(n.taskCount) ? n.taskCount : 0,
+    // 仓库清单（提案 #13）：只给名字列表（url/path 仅供路由，不进 UI）
+    repos: Array.isArray(n.repos) ? n.repos.filter((x) => typeof x === 'string') : [],
+    reposAt: Number.isFinite(n.reposAt) ? n.reposAt : null,
+    // 资源遥测（最近一次 node/resource）：字段级投影，缺/null 都如实透传
+    resource: (n.resource && typeof n.resource === 'object')
+      ? {
+        cpuPct: Number.isFinite(n.resource.cpuPct) ? n.resource.cpuPct : null,
+        load1: Number.isFinite(n.resource.load1) ? n.resource.load1 : null,
+        memUsedMb: Number.isFinite(n.resource.memUsedMb) ? n.resource.memUsedMb : null,
+        memTotalMb: Number.isFinite(n.resource.memTotalMb) ? n.resource.memTotalMb : null,
+        at: Number.isFinite(n.resource.at) ? n.resource.at : null,
+      }
+      : null,
+  }
+}
+
+/** manifest 的 final 条目。 */
+export function finalItemView(f) {
+  if (!f || typeof f !== 'object') return null
+  return {
+    path: typeof f.path === 'string' ? f.path.slice(0, 500) : '',
+    kind: typeof f.kind === 'string' ? f.kind : 'file',
+    bytes: Number.isFinite(f.bytes) ? f.bytes : 0,
+    sha256: typeof f.sha256 === 'string' ? f.sha256 : null,
+  }
+}
+
+/** manifest：计数 + final 清单（不传字节）。 */
+export function manifestView(m, { max = 200 } = {}) {
+  if (!m || typeof m !== 'object') return null
+  const counts = m.counts && typeof m.counts === 'object' ? m.counts : null
+  return {
+    counts: counts
+      ? {
+        total: Number.isFinite(counts.total) ? counts.total : 0,
+        final: Number.isFinite(counts.final) ? counts.final : 0,
+        intermediate: Number.isFinite(counts.intermediate) ? counts.intermediate : 0,
+        other: Number.isFinite(counts.other) ? counts.other : 0,
+      }
+      : null,
+    bytesFinal: Number.isFinite(m.bytesFinal) ? m.bytesFinal : 0,
+    final: Array.isArray(m.items)
+      ? m.items
+        .filter((i) => i && i.role === 'final')
+        .slice(0, max)
+        .map(finalItemView)
+        .filter(Boolean)
+      : [],
+  }
+}
+
+/**
+ * handoff 里的 `artifacts` 段。
+ *
+ * ⚠ 形状与 `manifestView` **不同**，不要混用：
+ *   - `manifestView` 吃的是**副机的清单对象**（`items: [{role, path, ...}]`），
+ *     需要按 `role === 'final'` 筛。
+ *   - handoff 里的 `artifacts.final` 是**副机已经筛好的数组**（见
+ *     lib/node/task-engine.js 的 buildHandoff），只有 `{path, kind, bytes, sha256}`。
+ * 我第一版把两者当成一个形状，导致 final 恒为空数组（e2e 断言 `final 应含 产物.txt` 失败）。
+ */
+export function artifactsView(a, { max = 200 } = {}) {
+  if (!a || typeof a !== 'object') return null
+  const counts = a.counts && typeof a.counts === 'object' ? a.counts : null
+  return {
+    counts: counts
+      ? {
+        total: Number.isFinite(counts.total) ? counts.total : 0,
+        final: Number.isFinite(counts.final) ? counts.final : 0,
+        intermediate: Number.isFinite(counts.intermediate) ? counts.intermediate : 0,
+        other: Number.isFinite(counts.other) ? counts.other : 0,
+      }
+      : null,
+    bytesFinal: Number.isFinite(a.bytesFinal) ? a.bytesFinal : 0,
+    final: Array.isArray(a.final)
+      ? a.final.slice(0, max).map(finalItemView).filter(Boolean)
+      : [],
+    intermediateCount: Number.isFinite(a.intermediateCount) ? a.intermediateCount : 0,
+    note: typeof a.note === 'string' ? a.note.slice(0, 500) : '',
+  }
+}
+
+/**
+ * handoff 卡片：**投影最严的一处**。
+ *
+ * 副机的 buildHandoff() 会带上 workspace（绝对路径）、logs（可能含环境变量）、
+ * 以及它版本的任何新字段。这里逐字段挑出消费方要用的部分，其余一律丢弃。
+ */
+export function handoffView(h) {
+  if (!h || typeof h !== 'object') return null
+  const summary = h.summary && typeof h.summary === 'object' ? h.summary : null
+  return {
+    taskId: typeof h.taskId === 'string' ? h.taskId : null,
+    nodeId: typeof h.nodeId === 'string' ? h.nodeId : null,
+    status: typeof h.status === 'string' ? h.status : null,
+    mode: typeof h.mode === 'string' ? h.mode : null,
+    runner: typeof h.runner === 'string' ? h.runner : null,
+    durationMs: Number.isFinite(h.durationMs) ? h.durationMs : null,
+    startedAt: Number.isFinite(h.startedAt) ? h.startedAt : null,
+    endedAt: Number.isFinite(h.endedAt) ? h.endedAt : null,
+    exit: exitView(h.exit),
+    // **两个形状都提供**，因为两条消费路径的历史契约不同：
+    //   - 工具路径（remote_handoff）的既有契约是嵌套 `summary.text`，
+    //     已被测试与下游依赖（e2e 断言 `card.summary.text` 是字符串）。
+    //   - UI 路径读的是扁平 `summaryText`。
+    // 统一投影时若只留一个形状，就会静默破坏另一条路径 —— 这正是我第一版
+    // 改动造成的回归（9 个测试失败）。两个都给，各有明确来源。
+    summary: summary
+      ? { text: typeof summary.text === 'string' ? summary.text.slice(0, 4000) : '' }
+      : null,
+    summaryText: summary && typeof summary.text === 'string' ? summary.text.slice(0, 4000) : '',
+    changed: changedView(h.changed, { max: 50 }),
+    // 任务变更 diff 视图（提案 #21）：副机对文本文件改动生成的 unified diff。
+    diffs: diffsView(h.diffs),
+    // handoff 里的 artifacts 走**专用**投影（它的 final 已是筛好的数组）
+    artifacts: artifactsView(h.artifacts, { max: 200 }),
+    pullHint: typeof h.pullHint === 'string' ? h.pullHint.slice(0, 1000) : '',
+    // 刻意**不含**：workspace（绝对路径，回显主机目录）、logs（可能带环境变量）、
+    // goal（原文已在任务投影里）、sessionId（副机内部标识）
+  }
+}
+
+/**
+ * 任务投影：工具与 UI 共用的"一条任务长什么样"。
+ *
+ * ── 必须**幂等**（对已投影过的对象再投影一次，结果不变） ──────────────
+ * 共享层会被两条路径**叠加**调用：`registry.taskView(t)` 内部先做一次共享投影
+ * （见 node-registry.js），而 UI 路由 `/tasks` 拿到它之后再调一次
+ * `taskView(t)`（ui-routes.js）。若本函数假设输入一定是"原始注册表对象"，
+ * 第二次投影就会把第一次的成果丢掉：
+ *   - `summary.text` 在投影结果里变成了 `summaryText`，再读 `t.summary.text`
+ *     就得到空串 → 面板展开任务时"结果摘要"整块消失
+ *   - `changedCount` 从原始长度（例如 120）被降级成**已截断**的 `changed.length`（50）
+ *   - `manifestCounts` 同理丢失（原始对象里是 `manifest`，投影后是 `manifestCounts`）
+ * 所以三个字段都做"原始形状优先，已投影形状兜底"，让重复投影成为恒等操作。
+ *
+ * @param {object} t 节点注册表里的任务对象（含 nodeId/status/changed/manifest/…），
+ *   或本函数先前的输出（幂等）
+ * @param {object} [o]
+ * @param {number} [o.tail] 日志/进度尾部保留几条
+ * @param {boolean} [o.includeLogs] 是否带日志尾部（UI 要，工具的轻量视图可省）
+ */
+export function taskView(t, { tail = 6, includeLogs = true } = {}) {
+  if (!t || typeof t !== 'object') return null
+  const summaryText = t.summary && typeof t.summary.text === 'string'
+    ? t.summary.text.slice(0, 2000)
+    : typeof t.summaryText === 'string'
+      ? t.summaryText.slice(0, 2000)
+      : ''
+  const out = {
+    taskId: typeof t.taskId === 'string' ? t.taskId : '',
+    nodeId: typeof t.nodeId === 'string' ? t.nodeId : '',
+    nodeOnline: t.nodeOnline === true,
+    status: typeof t.status === 'string' ? t.status : 'unknown',
+    mode: typeof t.mode === 'string' ? t.mode : '',
+    // 两阶段审批（提案 #2）：'manual'（挂起待批）| 'auto'
+    approval: t.approval === 'manual' ? 'manual' : 'auto',
+    goal: typeof t.goal === 'string' ? t.goal.slice(0, 500) : '',
+    createdAt: Number.isFinite(t.createdAt) ? t.createdAt : 0,
+    updatedAt: Number.isFinite(t.updatedAt) ? t.updatedAt : 0,
+    // ⚠ 时间字段的 schema 声明是 number，**不能返回 null**。
+    //
+    // DSH 在工具返回值出边界时跑 schema 校验（`validateJsonSchemaValue`），
+    // null 会被判为 "must be a number" → 整个工具调用报
+    // `returned invalid output: "value.startedAt" must be a number`。
+    // 实测：remote_status 查一个刚创建、还没开始执行的任务就踩到
+    // （createdAt 有值，但 startedAt/endedAt/durationMs 都还没有）。
+    // 用 0 表达"还没有这个时间点" —— 消费方判 `> 0` 即可。
+    startedAt: Number.isFinite(t.startedAt) ? t.startedAt : 0,
+    endedAt: Number.isFinite(t.endedAt) ? t.endedAt : 0,
+    durationMs: Number.isFinite(t.durationMs) ? t.durationMs : 0,
+    exit: exitView(t.exit),
+    error: errorView(t.error),
+    summaryText,
+    // changedCount 是"原始条数"（面板标题用它），不能被投影后的截断值覆盖。
+    // 已投影对象里没有原始数组长度，只能信它带来的 changedCount。
+    changedCount: Array.isArray(t.changed)
+      ? (Number.isFinite(t.changedCount) ? t.changedCount : t.changed.length)
+      : (Number.isFinite(t.changedCount) ? t.changedCount : 0),
+    changed: changedView(t.changed, { max: 50 }),
+    // manifestCounts 的 schema 是 object，同样不能用 null → 空对象兜底。
+    manifestCounts: manifestView(t.manifest)?.counts
+      ?? (t.manifestCounts && typeof t.manifestCounts === 'object' ? t.manifestCounts : {}),
+    // workspace 刻意不回传：绝对路径会回显主机目录结构，而两个消费方都不读它。
+  }
+  if (includeLogs) {
+    // progressTail 必须做**元素级**投影，不能只 slice：它同样源自副机上报
+    // （node-registry 的 applyView 把 task/sync 里的数组原样存下），而消费方
+    // 会解引用 `p.phase` / `p.detail`。详见 progressTailView 的说明。
+    out.progressTail = progressTailView(t.progressTail, { tail })
+    // logTail 用同一个 tailSlice：原先的裸 slice(-tail) 在 tail=0 时会把**整条**
+    // 日志留下（slice(-0) === slice(0)），与"不要尾巴"相反。
+    out.logTail = Array.isArray(t.logTail)
+      ? tailSlice(t.logTail, tail).map((l) => (typeof l === 'string' ? l.slice(0, 2000) : String(l).slice(0, 2000)))
+      : []
+  }
+  return out
+}

package/lib/identity.js

@@ -0,0 +1,271 @@
+/**
+ * hub 身份：持久 ed25519 密钥对 + 指纹 + 身份帧签名（零外部依赖，node:crypto）。
+ *
+ * ═══════════════════════════════════════════════════════════════════════════
+ * 这个模块解决什么问题（评审报告 P2-11）
+ * ═══════════════════════════════════════════════════════════════════════════
+ *
+ * 协议此前只有**单向认证**：副机拿 token 向 hub 证明"我是被允许接入的节点"，
+ * 但 hub 从不需要向副机证明"我就是你知道的那个 hub"。于是：
+ *
+ *   - direct 模式：任何能 accept upgrade 的端点（假 hub / 中间人）回一帧
+ *     welcome，副机就上线 —— 之后的 task/start（mode:"exec" = 副机任意代码
+ *     执行）照单全收。token 是副机交出去的东西，假 hub 根本不验。
+ *   - relay 模式更糟：副机的"在线"信号来自中继的 hello/node accepted，
+ *     hub 在握手期对副机完全静默 —— 假中继接受 hello 后可以直接冒充 hub
+ *     下发任务。SECURITY.md 里"中继可见明文帧"只是机密性问题，这一条是
+ *     **身份 + 完整性**问题，且直接通向副机任意代码执行。
+ *
+ * 修法（本模块 + 协议扩展 + 副机验证，三处一起才闭环）：
+ *   1. hub 生成持久 ed25519 身份密钥对，首次启动落盘（0600）；
+ *   2. 握手时 hub 用私钥签一帧身份证明：指纹 + 公钥 + 签名 + 时间戳 +
+ *      本次连接 nonce。direct 模式放进 welcome，relay 模式用
+ *      hub/identity 帧主动补（上线信号不归 hub 发，只能追发）；
+ *   3. 副机侧验签 + 指纹比对。指纹经配对码零终端分发，首连自动钉住
+ *      （TOFU），之后不匹配即拒绝上线并大声报错。
+ *
+ * 为什么是 ed25519 而不是 HMAC / 预共享密钥：
+ *   - 指纹必须能公开分发（配对码里人眼可见），公钥验证不需要副机持有
+ *     任何秘密 —— 泄一个配对码不等于泄一把能冒充 hub 的钥匙；
+ *   - hub 侧一把私钥对所有副机通用，不需要 per-node 预共享表；
+ *   - node:crypto 原生支持，保持零外部依赖；
+ *   - 签名确定性（RFC 8032）让黄金向量可以跨 Node 版本锁定字节。
+ *
+ * 指纹格式：`hubfp1-` + base64url(sha256(SPKI DER)[0:16])，共 22 字符。
+ * 16 字节（128 bit）抗碰撞余量对"人眼核对 + 机器比对"双重场景足够，
+ * 又短到能塞进配对码和终端里显示。
+ */
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes, sign as edSign, verify as edVerify } from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import fs from 'node:fs'
+import path from 'node:path'
+
+/** 签名载荷的上下文前缀。改它 = 协议变更，旧签名全部作废（有意为之）。 */
+export const IDENTITY_CONTEXT = 'dsh-remote-agent/hub-identity/v1'
+export const FINGERPRINT_PREFIX = 'hubfp1-'
+/** 指纹取 sha256 的前 16 字节 → base64url 恰好 22 字符（无填充）。 */
+const FP_BYTES = 16
+/** hello/welcome 里 nonce 的字节数（hex 后 32 字符）。 */
+export const NONCE_BYTES = 16
+/** 身份文件格式版本。 */
+export const IDENTITY_FILE_VERSION = 1
+/** 身份文件名（落在 hub stateDir 下）。 */
+export const IDENTITY_FILE_NAME = 'hub-identity.json'
+/** 副机 TOFU 钉住文件名（落在副机 stateDir 下）。 */
+export const HUB_PIN_FILE_NAME = 'hub-pin.json'
+
+/* ───────────────────────────── 指纹 ───────────────────────────── */
+
+/** 由 SPKI DER 公钥字节算指纹。 */
+export function fingerprintOf(publicKeyDer) {
+  const buf = Buffer.isBuffer(publicKeyDer) ? publicKeyDer : Buffer.from(publicKeyDer ?? '')
+  if (buf.length === 0) return ''
+  const digest = createHash('sha256').update(buf).digest()
+  return FINGERPRINT_PREFIX + digest.subarray(0, FP_BYTES).toString('base64url')
+}
+
+/**
+ * 归一化指纹：形态不对一律返回 ''（调用方按"没有指纹"处理）。
+ * base64url 大小写敏感，不做大小写折叠 —— 折叠会让两个不同指纹相等。
+ */
+export function normalizeFingerprint(raw) {
+  if (typeof raw !== 'string') return ''
+  const s = raw.trim()
+  if (!s.startsWith(FINGERPRINT_PREFIX)) return ''
+  const body = s.slice(FINGERPRINT_PREFIX.length)
+  if (!/^[A-Za-z0-9_-]{22}$/.test(body)) return ''
+  return FINGERPRINT_PREFIX + body
+}
+
+/* ───────────────────────────── 密钥对 ───────────────────────────── */
+
+/**
+ * 生成一把新身份。返回 Base64url（DER）形态的持久化表示 + KeyObject。
+ * KeyObject 只在内存里用；落盘的永远是可以 JSON 序列化的字符串。
+ */
+export function generateIdentity() {
+  const { privateKey, publicKey } = generateKeyPairSync('ed25519')
+  const publicDer = publicKey.export({ format: 'der', type: 'spki' })
+  return {
+    privateKeyB64: privateKey.export({ format: 'der', type: 'pkcs8' }).toString('base64url'),
+    publicKeyB64: publicDer.toString('base64url'),
+    fingerprint: fingerprintOf(publicDer),
+  }
+}
+
+/**
+ * 把持久化表示还原成可签/可验的身份。
+ * 任何字段缺失/损坏/指纹与公钥不符 → 返回 null（调用方决定重建还是报错）。
+ */
+export function importIdentity(stored) {
+  if (!stored || typeof stored !== 'object') return null
+  const priv = typeof stored.privateKeyB64 === 'string' ? stored.privateKeyB64 : ''
+  const pub = typeof stored.publicKeyB64 === 'string' ? stored.publicKeyB64 : ''
+  if (priv === '' || pub === '') return null
+  try {
+    const privateKey = createPrivateKey({ key: Buffer.from(priv, 'base64url'), format: 'der', type: 'pkcs8' })
+    const publicKey = createPublicKey({ key: Buffer.from(pub, 'base64url'), format: 'der', type: 'spki' })
+    const fp = fingerprintOf(publicKey.export({ format: 'der', type: 'spki' }))
+    if (normalizeFingerprint(stored.fingerprint) !== fp) return null
+    return { privateKey, publicKey, privateKeyB64: priv, publicKeyB64: pub, fingerprint: fp }
+  } catch {
+    return null
+  }
+}
+
+/* ───────────────────────────── 签名 / 验签 ───────────────────────────── */
+
+/** 每次连接一个新 nonce（hex）。副机放 hello 里，hub 签进身份帧。 */
+export function newNonce() {
+  return randomBytes(NONCE_BYTES).toString('hex')
+}
+
+/**
+ * 签名载荷的规范化序列化。字段序固定 —— 换行分隔、无转义，
+ * 任何一字段漂移都会让验签失败（fail-closed 方向，安全）。
+ */
+export function identitySignPayload({ fingerprint, nodeId, nonce, at }) {
+  return [IDENTITY_CONTEXT, String(fingerprint ?? ''), String(nodeId ?? ''), String(nonce ?? ''), String(at ?? '')].join('\n')
+}
+
+/**
+ * hub 侧：签一帧身份证明。返回 base64url 签名（ed25519 = 64 字节 → 86 字符）。
+ * 抛错只可能是私钥形态坏了 —— 调用方（hub）按"身份不可用"降级。
+ */
+export function signIdentity(privateKeyB64, { fingerprint, nodeId, nonce, at }) {
+  const key = createPrivateKey({ key: Buffer.from(privateKeyB64, 'base64url'), format: 'der', type: 'pkcs8' })
+  const sig = edSign(undefined, Buffer.from(identitySignPayload({ fingerprint, nodeId, nonce, at }), 'utf8'), key)
+  return sig.toString('base64url')
+}
+
+/**
+ * 副机侧：验签。任何异常（公钥坏/签名坏/字段缺）一律 false，绝不抛。
+ */
+export function verifyIdentity(publicKeyB64, fields, sigB64) {
+  if (typeof publicKeyB64 !== 'string' || publicKeyB64 === '') return false
+  if (typeof sigB64 !== 'string' || sigB64 === '') return false
+  try {
+    const key = createPublicKey({ key: Buffer.from(publicKeyB64, 'base64url'), format: 'der', type: 'spki' })
+    return edVerify(
+      undefined,
+      Buffer.from(identitySignPayload(fields), 'utf8'),
+      key,
+      Buffer.from(sigB64, 'base64url'),
+    )
+  } catch {
+    return false
+  }
+}
+
+/* ───────────────────────────── 落盘 ───────────────────────────── */
+
+/**
+ * 收窄文件权限到「只有本人可读写」。
+ *
+ * 与 lib/relay-config.js 的同名函数同构（chmod 0600 + Windows icacls），
+ * 这里不放公共模块是因为 relay-config.js 会拖进整条 relay 依赖链，
+ * 而 hub/副机两侧只需要这 15 行。改动务必两边同步。
+ */
+export function restrictPermissions(target, { isDir = false } = {}) {
+  try {
+    fs.chmodSync(target, isDir ? 0o700 : 0o600)
+  } catch {
+    /* FAT/网络盘不支持 mode，忽略 */
+  }
+  if (process.platform !== 'win32') return
+  const user = process.env.USERDOMAIN && process.env.USERNAME
+    ? `${process.env.USERDOMAIN}\\${process.env.USERNAME}`
+    : process.env.USERNAME
+  if (!user) return
+  try {
+    spawnSync(
+      'icacls',
+      [target, '/inheritance:r', '/grant:r', isDir ? `${user}:(OI)(CI)F` : `${user}:F`],
+      { stdio: 'ignore', timeout: 5000, windowsHide: true },
+    )
+  } catch {
+    /* icacls 不存在或被策略拦住：保持默认 ACL */
+  }
+}
+
+/**
+ * 原子写一个 JSON（tmp + rename，0600）。失败抛可读错误。
+ * 导出给 lib/node/hub-pin.js 复用（副机 TOFU 钉住文件同一手法、同一口径）。
+ */
+export function writeJsonAtomic(file, obj) {
+  const dir = path.dirname(file)
+  fs.mkdirSync(dir, { recursive: true })
+  restrictPermissions(dir, { isDir: true })
+  const tmp = `${file}.${process.pid}.tmp`
+  try {
+    fs.writeFileSync(tmp, `${JSON.stringify(obj, null, 2)}\n`, { mode: 0o600 })
+    restrictPermissions(tmp)
+    fs.renameSync(tmp, file)
+  } catch (err) {
+    try {
+      fs.rmSync(tmp, { force: true })
+    } catch {
+      /* 清理失败不影响报错 */
+    }
+    throw new Error(`写入身份文件失败：${file}（${err.message}）`, { cause: err })
+  }
+  restrictPermissions(file)
+}
+
+/**
+ * hub 侧：读身份文件，没有/损坏就地重建。
+ *
+ * 三条语义：
+ *   1. 合法 → 原样返回（含 KeyObject），`created:false`；
+ *   2. 不存在 → 生成新的并落盘，`created:true`；
+ *   3. 存在但损坏 → **重建并覆盖**。这与 relay 的 tokens.json（损坏就抛错
+ *      等人修）不同，是刻意的：hub 身份重建后，所有已钉住指纹的副机会在
+ *      下次握手时**大声失败**——安全方向是 fail-closed，不会静默接受一个
+ *      新身份。而"hub 因为一个磁盘坏字节起不来"的可用性代价不可接受。
+ *
+ * 磁盘完全不可写时不抛：返回纯内存身份（hub 本次运行仍可认证，重启后
+ * 换身份 —— 副机会再次大声失败，可感知）。
+ */
+export function loadOrCreateHubIdentity(file) {
+  if (typeof file !== 'string' || file.trim() === '') {
+    throw new Error('loadOrCreateHubIdentity: file 必须是非空路径')
+  }
+  const target = path.resolve(file)
+  if (fs.existsSync(target)) {
+    let parsed
+    try {
+      parsed = JSON.parse(fs.readFileSync(target, 'utf8'))
+    } catch {
+      parsed = null
+    }
+    const imported = importIdentity(parsed)
+    if (imported) {
+      restrictPermissions(target)
+      return { ...imported, file: target, created: false }
+    }
+  }
+  const fresh = generateIdentity()
+  try {
+    writeJsonAtomic(target, {
+      version: IDENTITY_FILE_VERSION,
+      ...fresh,
+      createdAt: new Date().toISOString(),
+    })
+  } catch {
+    /* 落盘失败见上：内存身份照用 */
+  }
+  const imported = importIdentity(fresh)
+  return { ...imported, file: target, created: true }
+}
+
+/** 只读身份（setup 向导/探活用）：不创建、不写盘。损坏或缺失 → null。 */
+export function readHubIdentity(file) {
+  if (typeof file !== 'string' || file.trim() === '') return null
+  try {
+    if (!fs.existsSync(file)) return null
+    const imported = importIdentity(JSON.parse(fs.readFileSync(file, 'utf8')))
+    return imported ? { ...imported, file: path.resolve(file) } : null
+  } catch {
+    return null
+  }
+}