cofluxd 0.11.0 → 0.12.0

package/README.md

@@ -22,6 +22,11 @@ cofluxd down            # 停止
 cofluxd uninstall [--purge]   # 卸载（--purge 连二进制/配置/凭证一并删）
 ```
 
+从 `cofluxd@0.12.0` 起，远端安装/更新会用 npm 包内置的 ed25519 公钥同时验证
+supervisor 与 worker 的 version/target/size/sha256/release statement；两个文件全部通过后才替换。
+CLI 还会取自身与 worker 的持久 release floor 较大值拒绝远端降级。`--bin-dir` 仍是本机管理员
+显式信任本地产物的开发/救援入口。
+
 默认连公共服务 `wss://api.coflux.dev/daemon`（自托管用 `--server` 改；已保存的地址继续生效，非默认时会有醒目提示）。
 
 ## 给 agent 用的命令

package/cofluxd.mjs

@@ -12,11 +12,25 @@ import dns from "node:dns/promises";
 import net from "node:net";
 import tls from "node:tls";
 import crypto from "node:crypto";
+import {
+  MAX_RELEASE_ARTIFACT_BYTES,
+  assertReleaseVersion,
+  compareReleaseVersions,
+  createReleasePublicKey,
+  installStagedPair,
+  parseReleaseManifestEntry,
+  verifyReleaseArtifact,
+} from "./release-trust.mjs";
 
 // 默认中心服务（公共 SaaS）；自托管用 --server 覆盖。
 const DEFAULT_SERVER = "wss://api.coflux.dev/daemon";
 
 const REPO = "myWsq/coflux";
+const RELEASE_API_BASE = (process.env.COFLUX_RELEASE_API_BASE || "https://api.github.com").replace(/\/+$/, "");
+const RELEASE_DOWNLOAD_BASE = (
+  process.env.COFLUX_RELEASE_DOWNLOAD_BASE || `https://github.com/${REPO}/releases/download`
+).replace(/\/+$/, "");
+const MAX_RELEASE_METADATA_BYTES = 1024 * 1024;
 const HOME = process.env.COFLUX_HOME || join(homedir(), ".coflux");
 const BIN_DIR = join(HOME, "bin");
 const SETTINGS = join(HOME, "settings.json"); // 用户配置（serverUrl/deviceName/shell）→ daemon 直接读；600 权限防同机其他用户窥探
@@ -28,6 +42,8 @@ const LOCAL_GATEWAY_STORE = join(HOME, "local-gateway.json"); // gateway key/ori
 const FDA_STATUS = join(HOME, "fda-status"); // supervisor 启动时探测落盘（仅 macOS，见 crates/supervisor/src/fda.rs）
 const SUP_BIN = join(BIN_DIR, "coflux-supervisor");
 const WRK_BIN = join(BIN_DIR, "coflux-worker");
+const CLI_RELEASE_FLOOR = join(HOME, "cofluxd.release-floor");
+const WORKER_RELEASE_FLOOR = join(HOME, "worker.release-floor");
 const IS_MAC = platform() === "darwin";
 const IS_LINUX = platform() === "linux";
 const PLIST = join(homedir(), "Library", "LaunchAgents", "com.coflux.daemon.plist");
@@ -121,30 +137,113 @@ function fileSha256(path) {
 
 // macOS：新落盘的二进制带 com.apple.provenance，launchd 顶层 spawn 会被 AMFI 以
 // OS_REASON_CODESIGNING 静默杀死——即使产物是 Developer ID 签名 + 已公证（2026-07-25
-// v0.13.0 实测仍被连杀）。本地 ad-hoc 重签使其成为"本机产物"绕开该检查；签名威胁模型
-// 不受影响（防的是中心被攻破推恶意产物，靠下载后的 sha256+ed25519 验签，与此无关）。
+// v0.13.0 实测仍被连杀）。本地 ad-hoc 重签使其成为"本机产物"绕开该检查。
+// 远端产物必须先完成 release statement 验签，再允许走到这里；绝不能替任意下载内容重签。
 function resignMacBinaries(paths) {
   if (!IS_MAC) return;
   for (const p of paths) {
     const r = run("codesign", ["--force", "-s", "-", p]);
-    if (r.status !== 0) console.warn(`⚠ 本地重签失败: ${p}（daemon 若被系统杀，手动 codesign --force -s - 该文件后 cofluxd restart）`);
+    if (r.status !== 0) {
+      throw new Error(`macOS 本地重签失败: ${p}；保留当前 daemon 二进制`);
+    }
+  }
+}
+
+async function fetchBounded(url, maxBytes, label) {
+  const res = await fetch(url, {
+    redirect: "follow",
+    signal: AbortSignal.timeout(30_000),
+  });
+  if (!res.ok) throw new Error(`${label} 下载失败（HTTP ${res.status}）`);
+  const declaredLength = Number(res.headers.get("content-length"));
+  if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+    throw new Error(`${label} 超过大小上限`);
+  }
+  if (!res.body) throw new Error(`${label} 响应没有 body`);
+  const chunks = [];
+  let total = 0;
+  for await (const chunk of res.body) {
+    const bytes = Buffer.from(chunk);
+    total += bytes.byteLength;
+    if (total > maxBytes) {
+      await res.body.cancel().catch(() => {});
+      throw new Error(`${label} 超过大小上限`);
+    }
+    chunks.push(bytes);
+  }
+  return Buffer.concat(chunks, total);
+}
+
+function loadReleasePublicKey() {
+  const publicKeyHex = process.env.COFLUX_WORKER_PUBKEY ||
+    fs.readFileSync(new URL("./release-pubkey.hex", import.meta.url), "utf8");
+  return createReleasePublicKey(publicKeyHex);
+}
+
+function readReleaseFloor(path, label) {
+  let metadata;
+  try { metadata = fs.lstatSync(path); }
+  catch (error) {
+    if (error?.code === "ENOENT") return undefined;
+    throw new Error(`${label} 元数据无法读取，拒绝远端升级`);
+  }
+  if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size <= 0 || metadata.size > 128) {
+    throw new Error(`${label} 不是安全且有界的普通文件，拒绝远端升级`);
   }
+  let value;
+  try { value = fs.readFileSync(path, "utf8").trim(); }
+  catch { throw new Error(`${label} 无法读取，拒绝远端升级`); }
+  try { assertReleaseVersion(value); }
+  catch { throw new Error(`${label} 已损坏，拒绝远端升级`); }
+  return value;
 }
 
-async function download(url, dest) {
-  const res = await fetch(url, { redirect: "follow" });
-  if (!res.ok) die(`下载失败 HTTP ${res.status}: ${url}\n（该版本/平台的 release 资产是否已发布？）`);
-  fs.writeFileSync(dest, Buffer.from(await res.arrayBuffer()), { mode: 0o755 });
+function currentReleaseFloor() {
+  const floors = [
+    readReleaseFloor(CLI_RELEASE_FLOOR, "cofluxd.release-floor"),
+    readReleaseFloor(WORKER_RELEASE_FLOOR, "worker.release-floor"),
+  ].filter(Boolean);
+  return floors.reduce((highest, candidate) => {
+    if (!highest) return candidate;
+    const order = compareReleaseVersions(candidate, highest);
+    if (order === 0 && candidate !== highest) {
+      throw new Error(`本机 release floor precedence 相同但身份冲突：${highest} / ${candidate}`);
+    }
+    return order > 0 ? candidate : highest;
+  }, undefined);
 }
+
+function persistCliReleaseFloor(version) {
+  const temp = join(HOME, `.cofluxd.release-floor.${process.pid}.${crypto.randomBytes(8).toString("hex")}`);
+  let file;
+  try {
+    file = fs.openSync(temp, "wx", 0o600);
+    fs.writeFileSync(file, `${version}\n`);
+    fs.fsyncSync(file);
+    fs.closeSync(file);
+    file = undefined;
+    fs.renameSync(temp, CLI_RELEASE_FLOOR);
+    const homeDir = fs.openSync(HOME, "r");
+    try { fs.fsyncSync(homeDir); }
+    finally { fs.closeSync(homeDir); }
+  } finally {
+    if (file !== undefined) {
+      try { fs.closeSync(file); } catch {}
+    }
+    try { fs.rmSync(temp, { force: true }); } catch {}
+  }
+}
+
 // 取最新 release tag（含 prerelease；GitHub 的 /releases/latest 跳转不含 prerelease，故走 API）。
 async function resolveLatestTag() {
   try {
-    const r = await fetch(`https://api.github.com/repos/${REPO}/releases?per_page=1`, {
-      headers: { "user-agent": "cofluxd", accept: "application/vnd.github+json" },
-    });
-    if (!r.ok) return null;
-    const arr = await r.json();
-    return Array.isArray(arr) && arr[0]?.tag_name ? arr[0].tag_name : null;
+    const body = await fetchBounded(
+      `${RELEASE_API_BASE}/repos/${REPO}/releases?per_page=1`,
+      MAX_RELEASE_METADATA_BYTES,
+      "GitHub release 元数据",
+    );
+    const arr = JSON.parse(body.toString("utf8"));
+    return Array.isArray(arr) && typeof arr[0]?.tag_name === "string" ? arr[0].tag_name : null;
   } catch {
     return null;
   }
@@ -155,13 +254,36 @@ async function resolveLatestTag() {
 async function ensureBinaries({ version, binDir, skipIfPresent }) {
   fs.mkdirSync(BIN_DIR, { recursive: true });
   if (binDir) {
-    for (const b of ["coflux-supervisor", "coflux-worker"]) {
-      const src = join(binDir, b);
-      if (!fs.existsSync(src)) die(`本地产物缺失: ${src}（先 cargo build --release？）`);
-      fs.copyFileSync(src, join(BIN_DIR, b));
-      fs.chmodSync(join(BIN_DIR, b), 0o755);
+    const localArtifacts = ["coflux-supervisor", "coflux-worker"].map((name) => ({
+      name,
+      path: join(binDir, name),
+    }));
+    for (const artifact of localArtifacts) {
+      if (!fs.existsSync(artifact.path)) {
+        die(`本地产物缺失: ${artifact.path}（先 cargo build --release？）`);
+      }
+    }
+    const stageDir = fs.mkdtempSync(join(BIN_DIR, ".coflux-local-install-"));
+    let localFailure;
+    try {
+      const staged = [];
+      for (const artifact of localArtifacts) {
+        const destination = join(BIN_DIR, artifact.name);
+        const source = join(stageDir, artifact.name);
+        fs.copyFileSync(artifact.path, source);
+        fs.chmodSync(source, 0o755);
+        staged.push({ source, destination });
+      }
+      resignMacBinaries(staged.map(({ source }) => source));
+      installStagedPair(staged);
+    } catch (error) {
+      localFailure = error;
+    } finally {
+      fs.rmSync(stageDir, { recursive: true, force: true });
+    }
+    if (localFailure) {
+      die(`本地 daemon 安装失败：${localFailure instanceof Error ? localFailure.message : String(localFailure)}`);
     }
-    resignMacBinaries([SUP_BIN, WRK_BIN]);
     console.log(`✓ 用本地二进制（${binDir}）`);
     return;
   }
@@ -169,21 +291,86 @@ async function ensureBinaries({ version, binDir, skipIfPresent }) {
     console.log(`✓ 二进制已存在（${BIN_DIR}），跳过下载（用 cofluxd update 升级）`);
     return;
   }
-  const t = rustTarget();
-  let base;
+  const target = rustTarget();
+  let releaseVersion;
   if (!version || version === "latest") {
     const tag = await resolveLatestTag();
-    if (tag) console.log(`最新版本: ${tag}`);
-    base = tag ? `https://github.com/${REPO}/releases/download/${tag}` : `https://github.com/${REPO}/releases/latest/download`;
+    if (!tag) die("无法取得最新 release 的精确版本，拒绝无版本身份的下载");
+    releaseVersion = tag;
+    console.log(`最新版本: ${releaseVersion}`);
   } else {
-    base = `https://github.com/${REPO}/releases/download/${version}`;
+    releaseVersion = version;
+  }
+  try {
+    assertReleaseVersion(releaseVersion);
+  } catch (error) {
+    die(error instanceof Error ? error.message : String(error));
+  }
+  let releaseFloor;
+  try {
+    releaseFloor = currentReleaseFloor();
+    const floorOrder = releaseFloor
+      ? compareReleaseVersions(releaseVersion, releaseFloor)
+      : 1;
+    if (floorOrder < 0 || (floorOrder === 0 && releaseVersion !== releaseFloor)) {
+      throw new Error(`远端 release ${releaseVersion} 不高于本机可信身份 ${releaseFloor}，拒绝降级/重放`);
+    }
+  } catch (error) {
+    die(error instanceof Error ? error.message : String(error));
+  }
+
+  const base = `${RELEASE_DOWNLOAD_BASE}/${releaseVersion}`;
+  const stageDir = fs.mkdtempSync(join(BIN_DIR, ".coflux-release-install-"));
+  let failure;
+  try {
+    const manifestBytes = await fetchBounded(
+      `${base}/manifest.json`,
+      MAX_RELEASE_METADATA_BYTES,
+      "release manifest",
+    );
+    let manifest;
+    try {
+      manifest = JSON.parse(manifestBytes.toString("utf8"));
+    } catch {
+      throw new Error("release manifest 不是有效 JSON");
+    }
+    const publicKey = loadReleasePublicKey();
+    const staged = [];
+    for (const component of ["supervisor", "worker"]) {
+      const entry = parseReleaseManifestEntry(manifest, component, releaseVersion, target);
+      const artifactName = `coflux-${component}-${target}`;
+      process.stdout.write(`下载并验签 ${artifactName} … `);
+      const data = await fetchBounded(
+        `${base}/${artifactName}`,
+        Math.min(entry.size, MAX_RELEASE_ARTIFACT_BYTES),
+        artifactName,
+      );
+      verifyReleaseArtifact({ component, version: releaseVersion, entry, data, publicKey });
+      const source = join(stageDir, `coflux-${component}`);
+      fs.writeFileSync(source, data, { mode: 0o755 });
+      fs.chmodSync(source, 0o755);
+      staged.push({
+        source,
+        destination: component === "supervisor" ? SUP_BIN : WRK_BIN,
+      });
+      console.log("✓");
+    }
+    // 两个远端产物均通过同一发布根的验签后，才允许做本地平台变换与替换。
+    resignMacBinaries(staged.map(({ source }) => source));
+    // floor 先于 pair 提交：若其后进程崩溃，最多是旧二进制配更高 floor；重跑同版仍允许，
+    // 但任何旧的合法 release 都不能趁窗口降级。
+    if (!releaseFloor || compareReleaseVersions(releaseVersion, releaseFloor) > 0) {
+      persistCliReleaseFloor(releaseVersion);
+    }
+    installStagedPair(staged);
+  } catch (error) {
+    failure = error;
+  } finally {
+    fs.rmSync(stageDir, { recursive: true, force: true });
   }
-  for (const b of ["coflux-supervisor", "coflux-worker"]) {
-    process.stdout.write(`下载 ${b}-${t} … `);
-    await download(`${base}/${b}-${t}`, join(BIN_DIR, b));
-    console.log("✓");
+  if (failure) {
+    die(`release 安装失败：${failure instanceof Error ? failure.message : String(failure)}`);
   }
-  resignMacBinaries([SUP_BIN, WRK_BIN]);
 }
 
 // 写 settings.json（daemon 直接读）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cofluxd",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "coflux daemon 管理 CLI：装/起/停/升级 Rust daemon（supervisor + worker）",
   "type": "module",
   "bin": {
@@ -8,6 +8,8 @@
   },
   "files": [
     "cofluxd.mjs",
+    "release-pubkey.hex",
+    "release-trust.mjs",
     "README.md",
     "skills"
   ],

package/release-pubkey.hex

@@ -0,0 +1 @@
+d5605555e704b65933a82f57cb648ac96884c237353b0e47f5445f09e745d7a1

package/release-trust.mjs

@@ -0,0 +1,240 @@
+import crypto from "node:crypto";
+import { Buffer } from "node:buffer";
+import fs from "node:fs";
+
+export const WORKER_RELEASE_STATEMENT_DOMAIN = Buffer.from(
+  "coflux-worker-release-v1\0",
+  "utf8",
+);
+export const SUPERVISOR_RELEASE_STATEMENT_DOMAIN = Buffer.from(
+  "coflux-supervisor-release-v1\0",
+  "utf8",
+);
+
+const STRICT_RELEASE_VERSION = /^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/;
+const SHA256_HEX = /^[0-9a-f]{64}$/i;
+const ED25519_SIGNATURE_HEX = /^[0-9a-f]{128}$/i;
+const ED25519_PUBLIC_KEY_HEX = /^[0-9a-f]{64}$/i;
+export const MAX_RELEASE_ARTIFACT_BYTES = 128 * 1024 * 1024;
+
+function parseReleaseVersion(version) {
+  const match = typeof version === "string" ? STRICT_RELEASE_VERSION.exec(version) : null;
+  if (!match) throw new Error(`release version 不是带 v 前缀的严格 SemVer: ${JSON.stringify(version)}`);
+  const prerelease = match[4]
+    ? match[4].split(".").map((identifier) => {
+      if (/^\d+$/.test(identifier) && identifier.length > 1 && identifier.startsWith("0")) {
+        throw new Error(`release version 的数字 prerelease 标识符含前导 0: ${JSON.stringify(version)}`);
+      }
+      return /^\d+$/.test(identifier)
+        ? { numeric: true, value: BigInt(identifier) }
+        : { numeric: false, value: identifier };
+    })
+    : [];
+  return {
+    raw: version,
+    core: [BigInt(match[1]), BigInt(match[2]), BigInt(match[3])],
+    prerelease,
+  };
+}
+
+/** 与 Rust semver crate 一致的 release tag 子集：必须带 v，数字标识符禁止前导 0。 */
+export function assertReleaseVersion(version) {
+  parseReleaseVersion(version);
+  return version;
+}
+
+/** SemVer precedence；build metadata 不参与比较。 */
+export function compareReleaseVersions(leftVersion, rightVersion) {
+  const left = parseReleaseVersion(leftVersion);
+  const right = parseReleaseVersion(rightVersion);
+  for (let index = 0; index < 3; index += 1) {
+    if (left.core[index] < right.core[index]) return -1;
+    if (left.core[index] > right.core[index]) return 1;
+  }
+  if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+    if (left.prerelease.length === right.prerelease.length) return 0;
+    return left.prerelease.length === 0 ? 1 : -1;
+  }
+  const common = Math.min(left.prerelease.length, right.prerelease.length);
+  for (let index = 0; index < common; index += 1) {
+    const a = left.prerelease[index];
+    const b = right.prerelease[index];
+    if (a.numeric && b.numeric) {
+      if (a.value < b.value) return -1;
+      if (a.value > b.value) return 1;
+    } else if (a.numeric !== b.numeric) {
+      return a.numeric ? -1 : 1;
+    } else {
+      if (a.value < b.value) return -1;
+      if (a.value > b.value) return 1;
+    }
+  }
+  return Math.sign(left.prerelease.length - right.prerelease.length);
+}
+
+function lenPrefixed(value) {
+  const bytes = Buffer.from(value, "utf8");
+  const length = Buffer.allocUnsafe(4);
+  length.writeUInt32BE(bytes.length);
+  return [length, bytes];
+}
+
+function artifactReleaseStatement(domain, { version, target, sha256, size }) {
+  assertReleaseVersion(version);
+  if (typeof target !== "string" || !target || Buffer.byteLength(target) > 128) {
+    throw new Error("release target 非法");
+  }
+  if (typeof sha256 !== "string" || !SHA256_HEX.test(sha256)) {
+    throw new Error("release sha256 必须是 32 字节 hex");
+  }
+  if (!Number.isSafeInteger(size) || size <= 0 || size > MAX_RELEASE_ARTIFACT_BYTES) {
+    throw new Error("release size 必须是有效且有界的正整数");
+  }
+  const sizeBytes = Buffer.allocUnsafe(8);
+  sizeBytes.writeBigUInt64BE(BigInt(size));
+  return Buffer.concat([
+    domain,
+    ...lenPrefixed(version),
+    ...lenPrefixed(target),
+    Buffer.from(sha256, "hex"),
+    sizeBytes,
+  ]);
+}
+
+/** worker 热升级沿用的 v1 transcript；不得改变 domain 或字段顺序。 */
+export function workerReleaseStatement(metadata) {
+  return artifactReleaseStatement(WORKER_RELEASE_STATEMENT_DOMAIN, metadata);
+}
+
+/** supervisor 安装专用 transcript；独立 domain 防止合法 worker 签名被横向移植。 */
+export function supervisorReleaseStatement(metadata) {
+  return artifactReleaseStatement(SUPERVISOR_RELEASE_STATEMENT_DOMAIN, metadata);
+}
+
+export function createReleasePublicKey(publicKeyHex) {
+  const normalized = typeof publicKeyHex === "string" ? publicKeyHex.trim() : "";
+  if (!ED25519_PUBLIC_KEY_HEX.test(normalized)) {
+    throw new Error("发布公钥必须是 32 字节 hex");
+  }
+  return crypto.createPublicKey({
+    format: "jwk",
+    key: {
+      kty: "OKP",
+      crv: "Ed25519",
+      x: Buffer.from(normalized, "hex").toString("base64url"),
+    },
+  });
+}
+
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * 从 schema 2 manifest 取指定 component/target。额外顶层字段允许滚动扩展；
+ * 但参与信任裁决的 version/target/size/hash/signature 全部严格校验。
+ */
+export function parseReleaseManifestEntry(manifest, component, version, target) {
+  assertReleaseVersion(version);
+  if (component !== "worker" && component !== "supervisor") {
+    throw new Error(`未知 release component: ${JSON.stringify(component)}`);
+  }
+  if (!isRecord(manifest) || manifest.schemaVersion !== 2 || manifest.version !== version) {
+    throw new Error("release manifest schema/version 与请求不一致");
+  }
+  const entries = manifest[component];
+  const entry = isRecord(entries) ? entries[target] : undefined;
+  if (!isRecord(entry) || entry.target !== target) {
+    throw new Error(`release manifest 缺少匹配的 ${component}/${target}`);
+  }
+  if (
+    typeof entry.sha256 !== "string" ||
+    !SHA256_HEX.test(entry.sha256) ||
+    !Number.isSafeInteger(entry.size) ||
+    entry.size <= 0 ||
+    entry.size > MAX_RELEASE_ARTIFACT_BYTES ||
+    typeof entry.releaseSignature !== "string" ||
+    !ED25519_SIGNATURE_HEX.test(entry.releaseSignature)
+  ) {
+    throw new Error(`release manifest 的 ${component}/${target} 元数据非法`);
+  }
+  if (
+    component === "worker" &&
+    (typeof entry.signature !== "string" || !ED25519_SIGNATURE_HEX.test(entry.signature))
+  ) {
+    throw new Error(`release manifest 的 worker/${target} 缺少 legacy 签名`);
+  }
+  return {
+    target,
+    sha256: entry.sha256.toLowerCase(),
+    size: entry.size,
+    signature: component === "worker" ? entry.signature.toLowerCase() : undefined,
+    releaseSignature: entry.releaseSignature.toLowerCase(),
+  };
+}
+
+/** 校验实际 bytes 与 manifest 元数据、raw worker 签名及 component-separated release 签名。 */
+export function verifyReleaseArtifact({ component, version, entry, data, publicKey }) {
+  if (!Buffer.isBuffer(data)) throw new Error("release 产物必须是 Buffer");
+  if (data.byteLength !== entry.size) {
+    throw new Error(`${component} 产物大小不匹配：期望 ${entry.size}，实际 ${data.byteLength}`);
+  }
+  const sha256 = crypto.createHash("sha256").update(data).digest("hex");
+  if (sha256 !== entry.sha256) {
+    throw new Error(`${component} 产物 sha256 不匹配`);
+  }
+  if (
+    component === "worker" &&
+    !crypto.verify(null, data, publicKey, Buffer.from(entry.signature, "hex"))
+  ) {
+    throw new Error("worker 产物 legacy Ed25519 签名无效");
+  }
+  const metadata = { version, target: entry.target, sha256, size: data.byteLength };
+  const statement = component === "worker"
+    ? workerReleaseStatement(metadata)
+    : supervisorReleaseStatement(metadata);
+  if (!crypto.verify(null, statement, publicKey, Buffer.from(entry.releaseSignature, "hex"))) {
+    throw new Error(`${component} 产物 release Ed25519 签名无效`);
+  }
+}
+
+/**
+ * 两个已验证/本地显式信任的暂存文件一起进入替换阶段；任一 rename 失败都会恢复旧 pair。
+ * 单文件 rename 是原子的，pair 级失败用同文件系统内备份回滚，绝不把“只更新一半”当成功。
+ */
+export function installStagedPair(staged) {
+  if (
+    !Array.isArray(staged) ||
+    staged.length !== 2 ||
+    staged.some(({ source, destination }) =>
+      typeof source !== "string" || !source || typeof destination !== "string" || !destination)
+  ) {
+    throw new Error("daemon 安装必须提供两个合法的暂存文件");
+  }
+  const installed = [];
+  const backups = [];
+  try {
+    for (const { source, destination } of staged) {
+      const backup = `${source}.previous`;
+      if (fs.existsSync(destination)) {
+        fs.renameSync(destination, backup);
+        backups.push({ backup, destination });
+      }
+      fs.renameSync(source, destination);
+      installed.push(destination);
+    }
+  } catch (error) {
+    for (const destination of installed.reverse()) {
+      try { fs.rmSync(destination, { force: true }); } catch {}
+    }
+    const restoreFailures = [];
+    for (const { backup, destination } of backups.reverse()) {
+      try { fs.renameSync(backup, destination); }
+      catch (restoreError) { restoreFailures.push(restoreError); }
+    }
+    if (restoreFailures.length > 0) {
+      throw new AggregateError([error, ...restoreFailures], "daemon 二进制替换失败且旧版本恢复不完整");
+    }
+    throw error;
+  }
+}