fde2e-bu 1.2.0 → 1.3.1

package/src/nm/update.mjs

@@ -0,0 +1,727 @@
+// 扩展在线自更新（change bu-online-selfupdate A1/A3）——安装目录发现＋下载应用
+// ＋`fde2e-bu update` 子命令。host 侧接线见 nm/host.mjs 的 bu:update。
+//
+// 设计要点（design C1~C5）：
+//   - locateInstalls：扫 Chrome 系浏览器根（多平台、platform 可注入）各 profile 的
+//     Preferences/Secure Preferences → extensions.settings[<extId>].path（unpacked），
+//     复核 manifest version（与 SW 上报 runningVersion 相符——防误伤旧拷贝）；
+//     受管目录（~/fde2e/bu/ 内或目录旁 .browser-extension-state.json）让路 omni App。
+//   - applyUpdate：https + 域名硬白名单（NM 路径；CLI 路径 httpsOnly 仅强制 https——
+//     C5 运维明知故为）；流式落盘＋字节数/sha256 双校验（不符不动旧目录）；
+//     staging 解压（zip-slip/条目数/根 manifest/总量四重防护——对齐 omni pack.ts
+//     extractZipSafely 语义，参数按本包收敛为 256 条/64MB）；rm+rename 原子替换
+//     （Windows 瞬态占用指数退避 6 次 250ms 起截断 8s——对齐 omni buPlugin.ts）；
+//     finally 清 temp/staging；绝不写 sidecar（受管语义归 App 写入者）。
+//   - 零运行时依赖：zip 解析手写（store + deflate via zlib，zip64 拒绝）。
+import { createHash } from 'node:crypto';
+import {
+  createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync,
+  renameSync, rmSync, writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { dirname, join, resolve, sep } from 'node:path';
+import { inflateRawSync } from 'node:zlib';
+
+/** 扩展稳定 ID（manifest 固定 key 派生）——与 nm/bind.mjs 的 EXTENSION_ID 同值；
+ * 不跨模块引用是刻意的：bind→host→update→bind 会成环（bind 顶层常量在环上 TDZ 炸），
+ * 测试以「两处常量相等」断言防漂移。 */
+export const EXTENSION_ID = 'meojillndgamkbfjijfehjaefolnfopn';
+
+/** 官方 feed（C5 缺省；--feed 可覆写——测试/私有部署）。 */
+export const DEFAULT_FEED_URL = 'https://www.fde2e.com/downloads/fde2e-bu-feed.json';
+/** feed 内相对 url 的解析基址（design B）。 */
+export const DOWNLOADS_BASE = 'https://www.fde2e.com/downloads/';
+/** NM 路径下载域名硬白名单（C3：防 feed 被用作任意下载器）。 */
+export const UPDATE_HOST_ALLOWLIST_HOST = 'www.fde2e.com';
+/** omni App 受管标记：目录旁 sidecar 文件名（proposal 硬约束 1）。 */
+export const SIDECAR_NAME = '.browser-extension-state.json';
+/** 解压防护上限（对齐 omni extractZipSafely 语义、按本包收敛的参数）。 */
+export const EXTRACT_MAX_ENTRIES = 256;
+export const EXTRACT_MAX_BYTES = 64 * 1024 * 1024;
+/** Windows 瞬态占用退避（对齐 omni buPlugin.ts 实证参数）。 */
+export const RETRY_MAX = 6;
+export const RETRY_BASE_MS = 250;
+export const RETRY_CAP_MS = 8_000;
+/** 目录替换可重试的瞬态错误码（Windows 文件占用家族；EEXIST 同族兜底）。 */
+export const TRANSIENT_FS_CODES = new Set(['EPERM', 'EBUSY', 'EACCES', 'ENOTEMPTY', 'EEXIST']);
+
+/** 更新流程错误：code ∈ bad-url|verify|io（host 侧再映射 managed/not-found/bad-msg）。 */
+export function updateError(code, message) {
+  const err = new Error(message ?? code);
+  err.name = 'UpdateError';
+  err.code = code;
+  return err;
+}
+
+// ---------- semver（C5：feed 比较只认 >；等/低 no-op） ----------
+
+/**
+ * 解析版本串（Chrome manifest 口径：1~4 段数字，可带 -prerelease/+build）。
+ * @returns {number[]|null} 数值段数组（短缺补 0 到 3 段）；不可解析 → null
+ */
+export function parseSemver(v) {
+  if (typeof v !== 'string') return null;
+  const core = v.trim().replace(/^v=/, '').replace(/^v/, '').split('+')[0];
+  const [numsRaw, pre] = core.split('-');
+  const parts = numsRaw.split('.').map((s) => (/^\d+$/.test(s) ? Number(s) : NaN));
+  if (parts.length < 1 || parts.length > 4 || parts.some((n) => !Number.isSafeInteger(n) || n < 0)) return null;
+  while (parts.length < 3) parts.push(0);
+  return { nums: parts, pre: pre === undefined ? null : pre };
+}
+
+/** semver 比较：a>b → 1、相等 → 0、a<b → -1（prerelease 按 semver 点 11：无 > 有）。 */
+export function compareSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return NaN; // 调用方保证可解析（feed/manifest 均先校验）
+  for (let i = 0; i < 3; i++) {
+    if (pa.nums[i] !== pb.nums[i]) return pa.nums[i] > pb.nums[i] ? 1 : -1;
+  }
+  if (pa.pre === pb.pre) return 0;
+  if (pa.pre === null) return 1; // 无 prerelease > 有
+  if (pb.pre === null) return -1;
+  const sa = pa.pre.split('.');
+  const sb = pb.pre.split('.');
+  for (let i = 0; i < Math.max(sa.length, sb.length); i++) {
+    const x = sa[i];
+    const y = sb[i];
+    if (x === undefined) return -1; // 短前缀 < 长
+    if (y === undefined) return 1;
+    const xn = /^\d+$/.test(x);
+    const yn = /^\d+$/.test(y);
+    if (xn && yn) {
+      if (Number(x) !== Number(y)) return Number(x) > Number(y) ? 1 : -1;
+    } else if (xn !== yn) {
+      return xn ? -1 : 1; // 数值标识 < 字母数字标识
+    } else if (x !== y) {
+      return x > y ? 1 : -1;
+    }
+  }
+  return 0;
+}
+
+// ---------- C1 目录发现 ----------
+
+/**
+ * Chrome 系浏览器用户数据根（存在才扫；platform 可注入供测试）。
+ * @returns {{ label:string, root:string }[]} label ∈ chrome|chrome-beta|chrome-dev|
+ *   chrome-canary|chromium（macOS 的 Chromium 双路径同 label、按路径去重）
+ */
+export function browserScanRoots(home = homedir(), platform = process.platform) {
+  let roots;
+  if (platform === 'win32') {
+    const lad = join(home, 'AppData', 'Local'); // %LOCALAPPDATA% 缺省位置
+    roots = [
+      ['chrome', join(lad, 'Google', 'Chrome', 'User Data')],
+      ['chrome-beta', join(lad, 'Google', 'Chrome Beta', 'User Data')],
+      ['chrome-dev', join(lad, 'Google', 'Chrome Dev', 'User Data')],
+      ['chrome-canary', join(lad, 'Google', 'Chrome Canary', 'User Data')],
+      ['chromium', join(lad, 'Chromium', 'User Data')],
+    ];
+  } else if (platform === 'linux') {
+    const cfg = join(home, '.config');
+    roots = [
+      ['chrome', join(cfg, 'google-chrome')],
+      ['chromium', join(cfg, 'chromium')],
+      ['chromium', join(cfg, 'chromium-browser')],
+    ];
+  } else {
+    // macOS（及其它平台按 macOS 路径兜底——与 bind.browserManifestDirs 同策略）
+    const as = join(home, 'Library', 'Application Support');
+    roots = [
+      ['chrome', join(as, 'Google', 'Chrome')],
+      ['chrome-beta', join(as, 'Google', 'Chrome Beta')],
+      ['chrome-dev', join(as, 'Google', 'Chrome Dev')],
+      ['chrome-canary', join(as, 'Google', 'Chrome Canary')],
+      ['chromium', join(as, 'Google', 'Chromium')], // 任务规格字面路径
+      ['chromium', join(as, 'Chromium')], // macOS Chromium 平台规范路径
+    ];
+  }
+  const seen = new Set();
+  return roots.filter(([label, root]) => (seen.has(root) ? false : (seen.add(root), true)))
+    .map(([label, root]) => ({ label, root }));
+}
+
+/** profile 目录名（Chrome 约定：Default / Profile N）。 */
+export function isProfileDir(name) {
+  return name === 'Default' || /^Profile \d+$/.test(name);
+}
+
+/** 读 profile 的 Preferences/Secure Preferences → extensions.settings[extId].path。
+ * 存在 path 字段即视为 unpacked（design C1.2）；坏 JSON/无条目 → null。 */
+export function readUnpackedPath(profileDir, extId = EXTENSION_ID) {
+  for (const file of ['Preferences', 'Secure Preferences']) {
+    let data;
+    try {
+      data = JSON.parse(readFileSync(join(profileDir, file), 'utf8'));
+    } catch {
+      continue; // 不存在/坏 JSON → 换下一个来源
+    }
+    const entry = data?.extensions?.settings?.[extId];
+    if (entry && typeof entry === 'object' && typeof entry.path === 'string' && entry.path !== '') {
+      return { path: entry.path, source: file };
+    }
+  }
+  return null;
+}
+
+/** 目录内 manifest.json 的 version（缺失/坏 JSON/无 version → null）。 */
+export function readDirVersion(dir) {
+  try {
+    const m = JSON.parse(readFileSync(join(dir, 'manifest.json'), 'utf8'));
+    return typeof m?.version === 'string' && m.version !== '' ? m.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 受管判定（C2）：规范化路径位于 <home>/fde2e/bu/ 内，或目录旁存在 sidecar。 */
+export function isManagedPath(absDir, home = homedir()) {
+  const managedRoot = resolve(home, 'fde2e', 'bu');
+  if (absDir === managedRoot || absDir.startsWith(managedRoot + sep)) return true;
+  return existsSync(join(dirname(absDir), SIDECAR_NAME));
+}
+
+/**
+ * 扫描本机 unpacked 安装（C1）。
+ * @param {{ home?: string, extId?: string, runningVersion?: string,
+ *           platform?: string }} opts
+ *   runningVersion 给定（NM 路径）→ manifest version 必须相等，否则进 rejected
+ *   （旧拷贝，如实列出）；undefined（CLI 路径）→ 不做版本过滤（各安装自带版本
+ *   参与后续 semver 比较）。
+ * @returns {{ matches: Array<{path, browser, profile, version}>,
+ *             rejected: Array<{path, browser, profile, reason, found?, expected?}>,
+ *             managed: Array<{path, browser, profile}> }}
+ *   跨浏览器/多 profile 引用同一目录时按规范化路径去重（首见归属）。
+ */
+export function locateInstalls({ home = homedir(), extId = EXTENSION_ID, runningVersion, platform = process.platform } = {}) {
+  const matches = [];
+  const rejected = [];
+  const managed = [];
+  const seen = new Set();
+  for (const { label, root } of browserScanRoots(home, platform)) {
+    let profiles;
+    try {
+      profiles = readdirSync(root).filter(isProfileDir);
+    } catch {
+      continue; // 根不存在/不可读 → 该浏览器无安装
+    }
+    for (const profile of profiles) {
+      const found = readUnpackedPath(join(root, profile), extId);
+      if (!found) continue;
+      const path = resolve(found.path);
+      if (seen.has(path)) continue;
+      seen.add(path);
+      const at = { path, browser: label, profile };
+      if (isManagedPath(path, home)) {
+        managed.push(at);
+        continue;
+      }
+      const version = readDirVersion(path);
+      if (version === null) {
+        rejected.push({ ...at, reason: 'no-manifest' });
+        continue;
+      }
+      if (runningVersion !== undefined && version !== runningVersion) {
+        rejected.push({ ...at, reason: 'version-mismatch', found: version, expected: runningVersion });
+        continue;
+      }
+      matches.push({ ...at, version });
+    }
+  }
+  return { matches, rejected, managed };
+}
+
+// ---------- zip 解析（零依赖：store + deflate；zip64 拒绝） ----------
+
+const EOCD_SIG = 0x06054b50;
+const CDE_SIG = 0x02014b50;
+const LFH_SIG = 0x04034b50;
+
+/** 解析 zip 中央目录（纯函数）。@returns {{ entries, base }}——base＝前缀偏移修正。 */
+export function listZipEntries(buf) {
+  const minEocd = 22;
+  const maxScan = Math.min(buf.length, minEocd + 0xffff); // EOCD + 最大注释区
+  let eocd = -1;
+  for (let i = buf.length - minEocd; i >= buf.length - maxScan && i >= 0; i--) {
+    if (buf.readUInt32LE(i) === EOCD_SIG) { eocd = i; break; }
+  }
+  if (eocd < 0) throw updateError('verify', '更新包不是合法 zip（缺少 EOCD 结尾记录）');
+  const count = buf.readUInt16LE(eocd + 10);
+  const cdSize = buf.readUInt32LE(eocd + 12);
+  const cdOff = buf.readUInt32LE(eocd + 16);
+  if (count === 0xffff || cdOff === 0xffffffff) {
+    throw updateError('verify', '更新包为 zip64 形态（不支持——本包体积上限 64MB 无需 zip64）');
+  }
+  // 前缀偏移修正（自解压头等场景：EOCD 声明的偏移与实际位置差值即前缀长度）
+  let base = 0;
+  if (cdOff + cdSize !== eocd) {
+    base = eocd - cdSize - cdOff;
+    if (base < 0) throw updateError('verify', '更新包中央目录定位失败');
+  }
+  const entries = [];
+  let p = cdOff + base;
+  for (let i = 0; i < count; i++) {
+    if (p + 46 > buf.length || buf.readUInt32LE(p) !== CDE_SIG) {
+      throw updateError('verify', '更新包中央目录损坏');
+    }
+    const method = buf.readUInt16LE(p + 10);
+    const csize = buf.readUInt32LE(p + 20);
+    const usize = buf.readUInt32LE(p + 24);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const cmtLen = buf.readUInt16LE(p + 32);
+    const lho = buf.readUInt32LE(p + 42);
+    if (csize === 0xffffffff || usize === 0xffffffff || lho === 0xffffffff) {
+      throw updateError('verify', '更新包为 zip64 形态（不支持）');
+    }
+    entries.push({
+      name: buf.subarray(p + 46, p + 46 + nameLen).toString('utf8'),
+      method,
+      csize,
+      usize,
+      lho,
+    });
+    p += 46 + nameLen + extraLen + cmtLen;
+  }
+  return { entries, base };
+}
+
+/** 解出单条目数据（store 直取；deflate 走 zlib，maxOutputLength 防单条炸弹）。 */
+function readZipEntryData(buf, entry, base) {
+  const lho = entry.lho + base;
+  if (lho + 30 > buf.length || buf.readUInt32LE(lho) !== LFH_SIG) {
+    throw updateError('verify', `更新包条目头损坏：${entry.name}`);
+  }
+  const nameLen = buf.readUInt16LE(lho + 26);
+  const extraLen = buf.readUInt16LE(lho + 28);
+  const start = lho + 30 + nameLen + extraLen;
+  const end = start + entry.csize;
+  if (end > buf.length) throw updateError('verify', `更新包条目数据截断：${entry.name}`);
+  const raw = buf.subarray(start, end);
+  if (entry.method === 0) return Buffer.from(raw);
+  if (entry.method === 8) {
+    let out;
+    try {
+      out = inflateRawSync(raw, { maxOutputLength: EXTRACT_MAX_BYTES + 1 });
+    } catch (err) {
+      if (err?.code === 'ERR_BUFFER_TOO_LARGE') throw updateError('verify', `更新包条目解压超限：${entry.name}`);
+      throw updateError('verify', `更新包条目解压失败（${err?.message ?? err}）：${entry.name}`);
+    }
+    return out;
+  }
+  throw updateError('verify', `更新包条目压缩方式不支持（method=${entry.method}）：${entry.name}`);
+}
+
+/**
+ * 安全解压（对齐 omni pack.ts extractZipSafely 语义，参数按本包收敛）：
+ * zip-slip 拒绝（规范化后必须落在 destDir 内；绝对路径/../盘符/UNC 一律拒）＋
+ * 条目数 ≤256 ＋ 根必须有 manifest.json ＋ 总解压体积 ≤64MB。
+ * @returns {object} 根 manifest.json 解析结果（含 version 等）
+ */
+export function extractZipSafely(zipPath, destDir, { rootFile = 'manifest.json', what = '更新包' } = {}) {
+  let buf;
+  try {
+    buf = readFileSync(zipPath);
+  } catch (err) {
+    throw updateError('io', `读取更新包失败：${err?.message ?? err}`);
+  }
+  const { entries, base } = listZipEntries(buf);
+  if (entries.length > EXTRACT_MAX_ENTRIES) {
+    throw updateError('verify', `${what}条目数超限（${entries.length} > ${EXTRACT_MAX_ENTRIES}）`);
+  }
+  const destAbs = resolve(destDir);
+  mkdirSync(destAbs, { recursive: true });
+  let total = 0;
+  for (const entry of entries) {
+    const name = entry.name.replace(/\\/g, '/');
+    if (name.startsWith('/') || /^[A-Za-z]:/.test(name) || name.startsWith('//')) {
+      throw updateError('verify', `${what}含非法路径条目（绝对路径）：${entry.name}`);
+    }
+    const segs = name.split('/').filter((s) => s !== '' && s !== '.');
+    if (segs.length === 0 || segs.includes('..')) {
+      throw updateError('verify', `${what}含非法路径条目（越界）：${entry.name}`);
+    }
+    const target = join(destAbs, ...segs);
+    if (target !== destAbs && !target.startsWith(destAbs + sep)) {
+      throw updateError('verify', `${what}含非法路径条目（逃逸 staging）：${entry.name}`);
+    }
+    if (name.endsWith('/')) {
+      mkdirSync(target, { recursive: true }); // 目录条目
+      continue;
+    }
+    total += entry.usize;
+    if (total > EXTRACT_MAX_BYTES) {
+      throw updateError('verify', `${what}解压总量超限（> ${EXTRACT_MAX_BYTES} 字节）`);
+    }
+    const data = readZipEntryData(buf, entry, base);
+    if (data.length !== entry.usize) {
+      throw updateError('verify', `${what}条目尺寸与目录声明不符：${entry.name}`);
+    }
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, data);
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(join(destAbs, rootFile), 'utf8'));
+  } catch {
+    throw updateError('verify', `${what}缺 ${rootFile} 或不可解析（包结构不符）`);
+  }
+  return manifest;
+}
+
+// ---------- 下载策略（BU_UPDATE_BASE：测试/私有部署覆写） ----------
+
+/**
+ * 下载基址与白名单（NM 路径用）。BU_UPDATE_BASE 覆写＝信任重定向到指定基址
+ * （E2E 假 feed server / 私有部署用），**不是**放宽为任意域：允许域＝基址 host，
+ * http 仅当基址显式为 http（本机回环假服务器）。缺省＝www.fde2e.com 硬白名单。
+ */
+export function downloadPolicy(env = process.env) {
+  const override = env.BU_UPDATE_BASE;
+  if (override !== undefined && override !== '') {
+    let u;
+    try {
+      u = new URL(override);
+    } catch {
+      throw updateError('bad-url', `BU_UPDATE_BASE 无法解析：${override}`);
+    }
+    return {
+      base: override.endsWith('/') ? override : `${override}/`,
+      allowHost: u.hostname,
+      allowHttp: u.protocol === 'http:',
+    };
+  }
+  return { base: DOWNLOADS_BASE, allowHost: UPDATE_HOST_ALLOWLIST_HOST, allowHttp: false };
+}
+
+/** NM 路径 url 校验：相对形态按基址解析；协议/域名过白名单（C3 硬白名单）。 */
+export function resolveNmUrl(raw, env = process.env) {
+  const policy = downloadPolicy(env);
+  let u;
+  try {
+    u = new URL(String(raw), policy.base);
+  } catch {
+    throw updateError('bad-url', `下载 url 无法解析：${raw}`);
+  }
+  const wantProto = policy.allowHttp ? /^https?:$/ : /^https:$/;
+  if (!wantProto.test(u.protocol)) {
+    throw updateError('bad-url', `下载 url 协议必须 ${policy.allowHttp ? 'http(s)' : 'https'}（收到 ${u.protocol}//${u.hostname}）`);
+  }
+  if (u.hostname !== policy.allowHost) {
+    throw updateError('bad-url', `下载 url 域名不在白名单（只允许 ${policy.allowHost}，收到 ${u.hostname}）`);
+  }
+  return u;
+}
+
+// ---------- C3 下载与应用 ----------
+
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** 陈旧 temp/staging 清扫：属主 pid 已死才清（活进程的产物不动）。 */
+export function sweepStaleArtifacts(parentDir) {
+  let names;
+  try {
+    names = readdirSync(parentDir);
+  } catch {
+    return;
+  }
+  for (const n of names) {
+    const m = /^\.bu-update-(\d+)\.zip$/.exec(n) ?? /^\.browser-extension\.update-(\d+)$/.exec(n)
+      ?? /\.old-(\d+)$/.exec(n);
+    if (!m) continue;
+    const pid = Number(m[1]);
+    if (pid === process.pid) continue;
+    try {
+      process.kill(pid, 0); // ESRCH＝属主已死才可清；EPERM＝活着但无权探测 → 不清
+      continue;
+    } catch (err) {
+      if (err?.code === 'EPERM') continue;
+    }
+    try {
+      rmSync(join(parentDir, n), { recursive: true, force: true });
+    } catch { /* 清扫失败不阻断更新 */ }
+  }
+}
+
+/**
+ * 目录原子替换：三步交换（rename 旧→.old → rename staging→dest → 清 .old），任一步
+ * 瞬态占用（EPERM/EBUSY/EACCES/ENOTEMPTY，Windows 杀软/索引器/浏览器正读）指数退避
+ * 重试（6 次 250ms 起截断 8s）。第二步失败时回滚（.old → dest），旧目录始终在场——
+ * 杜绝「rm 成功 + rename 耗尽」把安装目录清空的毁灭尾迹（对抗审查 P1-1）；进程在
+ * 步骤间被杀留下的 .old-<pid>/staging 残留由 sweepStaleArtifacts 按属主探活清理。
+ * rm/rename/sleep 可注入（单测占用重试矩阵用 fast-sleep 不实等 7.9s）。
+ */
+export async function replaceDirAtomic(staging, dest, {
+  sleepImpl = defaultSleep, rmImpl = rmSync, renameImpl = renameSync,
+} = {}) {
+  const old = `${dest}.old-${process.pid}`;
+  rmImpl(old, { recursive: true, force: true });
+  const run = async (label, fn) => {
+    let lastErr;
+    for (let attempt = 0; attempt < RETRY_MAX; attempt++) {
+      try {
+        return fn();
+      } catch (err) {
+        if (!TRANSIENT_FS_CODES.has(err?.code)) {
+          const wrapped = updateError('io', `目录替换失败（${label}）：${err?.message ?? err}`);
+          wrapped.causeCode = err?.code; // 调用方按原始错误码分流（如 ENOENT＝dest 不在场）
+          throw wrapped;
+        }
+        lastErr = err;
+        if (attempt < RETRY_MAX - 1) {
+          await sleepImpl(Math.min(RETRY_BASE_MS * 2 ** attempt, RETRY_CAP_MS));
+        }
+      }
+    }
+    throw updateError('io', `目录替换失败（${label}，瞬态占用重试 ${RETRY_MAX} 次后放弃）：${lastErr?.message ?? lastErr}`);
+  };
+  // 让位：dest 存在 → rename 到 .old（瞬态退避）；dest 不存在（ENOENT＝全新安装）→ 跳过
+  let hasOld = false;
+  try {
+    await run('旧目录让位', () => renameImpl(dest, old));
+    hasOld = true;
+  } catch (err) {
+    rmImpl(old, { recursive: true, force: true });
+    if (err?.causeCode !== 'ENOENT') throw err;
+    // ENOENT：dest 不在场＝全新安装，无旧可让/可回滚
+  }
+  try {
+    await run('新目录就位', () => renameImpl(staging, dest));
+  } catch (err) {
+    if (hasOld) {
+      try { await run('回滚', () => renameImpl(old, dest)); } catch { /* 回滚也败：.old 在场，下次 sweep/重试自愈 */ }
+    }
+    throw err;
+  }
+  if (hasOld) rmImpl(old, { recursive: true, force: true });
+}
+
+/**
+ * 下载并应用更新到 destDir（C3 全流程）。
+ * @param {{ url: string, sha256: string, size: number, destDir: string,
+ *           fetchImpl?: Function, sleepImpl?: Function, httpsOnly?: boolean,
+ *           env?: object }} opts
+ *   httpsOnly（CLI 路径，C5）：只强制 https、不限域名（运维明知故为）；
+ *   缺省（NM 路径）：https + www.fde2e.com 硬白名单（BU_UPDATE_BASE 可重定向）。
+ * @returns {Promise<{from: string|null, to: string, path: string}>}
+ *   from＝旧目录 manifest version（目录缺失 → null）、to＝新包 manifest version。
+ * @throws {Error&{code:'bad-url'|'verify'|'io'}} 失败时旧目录保持原样（verify/bad-url
+ *   绝不触碰；io 仅替换阶段可能已 rm——rename 失败重试耗尽属不可恢复 IO 错）。
+ */
+export async function applyUpdate({ url, sha256, size, destDir, fetchImpl, sleepImpl, httpsOnly = false, env = process.env }) {
+  // 1. url 校验（CLI：绝对 https 任意域；NM：基址解析 + 硬白名单）
+  let u;
+  if (httpsOnly) {
+    try {
+      u = new URL(String(url));
+    } catch {
+      throw updateError('bad-url', `下载 url 无法解析：${url}`);
+    }
+    if (u.protocol !== 'https:') {
+      throw updateError('bad-url', `下载 url 协议必须 https（收到 ${u.protocol}//${u.hostname}）`);
+    }
+  } else {
+    u = resolveNmUrl(url, env);
+  }
+  if (typeof sha256 !== 'string' || !/^[0-9a-fA-F]{64}$/.test(sha256)) {
+    throw updateError('verify', 'sha256 须为 64 位 hex');
+  }
+  if (!Number.isSafeInteger(size) || size <= 0) {
+    throw updateError('verify', 'size 须为正整数');
+  }
+  const dest = resolve(String(destDir));
+  const parent = dirname(dest);
+  mkdirSync(parent, { recursive: true });
+  sweepStaleArtifacts(parent); // 前次中断残留（属主已死）顺手清
+  const tempZip = join(parent, `.bu-update-${process.pid}.zip`);
+  const staging = join(parent, `.browser-extension.update-${process.pid}`);
+  rmSync(tempZip, { force: true });
+  rmSync(staging, { recursive: true, force: true });
+  const fetchFn = fetchImpl ?? globalThis.fetch;
+  if (typeof fetchFn !== 'function') throw updateError('io', '无可用 fetch（Node >= 18）');
+
+  try {
+    // 2. 流式下载（超出 size 即断——feed 声明即预算，不做无界落盘）；
+    //    redirect:'error' 拒绝跟随 30x——白名单只校验首跳 URL（对抗审查 P2.1 收紧）
+    let res;
+    try {
+      res = await fetchFn(u.href, { redirect: 'error' });
+    } catch (err) {
+      throw updateError('io', `下载失败（${u.host}）：${err?.message ?? err}`);
+    }
+    if (!res || typeof res.ok !== 'boolean' || !res.ok) {
+      throw updateError('io', `下载失败（${u.host}）：HTTP ${res?.status ?? '???'}`);
+    }
+    if (!res.body) throw updateError('io', '下载响应无 body');
+    const source = res.body.getReader ? Readable.fromWeb(res.body) : Readable.from(res.body);
+    const hash = createHash('sha256');
+    const sink = createWriteStream(tempZip);
+    let bytes = 0;
+    try {
+      await pipeline(source, async function* verifyAndPass(chunks) {
+        for await (const chunk of chunks) {
+          bytes += chunk.length;
+          if (bytes > size) {
+            throw updateError('verify', `下载数超预期（>${size}B——feed 声明与实际不符）`);
+          }
+          hash.update(chunk);
+          yield chunk;
+        }
+      }, sink);
+    } catch (err) {
+      if (err?.code === 'verify') throw err;
+      throw updateError('io', `下载中断：${err?.message ?? err}`);
+    } finally {
+      sink.destroy();
+    }
+
+    // 3. 字节数 + sha256 双校验（不符删 temp 报 verify——绝不碰旧目录）
+    if (bytes !== size) {
+      throw updateError('verify', `字节数不符（feed=${size}，实收=${bytes}）`);
+    }
+    const hex = hash.digest('hex');
+    if (hex !== sha256.toLowerCase()) {
+      throw updateError('verify', `sha256 不符（feed=${sha256.toLowerCase()}，实算=${hex}）`);
+    }
+
+    // 4. staging 解压（zip-slip/条目/形状/总量四重防护）＋读新版本
+    const manifest = extractZipSafely(tempZip, staging);
+    if (typeof manifest?.version !== 'string' || manifest.version === '') {
+      throw updateError('verify', '更新包 manifest.json 缺 version（包结构不符）');
+    }
+    const from = readDirVersion(dest);
+
+    // 5. 原子替换（瞬态占用退避）；finally 清 temp/staging；不写任何 sidecar
+    await replaceDirAtomic(staging, dest, sleepImpl ? { sleepImpl } : {});
+    return { from, to: manifest.version, path: dest };
+  } finally {
+    rmSync(tempZip, { force: true });
+    rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+// ---------- feed 契约（B）＋ CLI 直跑（C5） ----------
+
+/** feed 形状校验：{version, url, sha256, size} 必填（date/notes 可选）。 */
+export function validateFeed(feed) {
+  if (!feed || typeof feed !== 'object' || Array.isArray(feed)) return 'feed 须为 JSON 对象';
+  if (typeof feed.version !== 'string' || feed.version === '') return 'feed.version 须为非空字符串';
+  if (parseSemver(feed.version) === null) return `feed.version 不是合法版本串：${feed.version}`;
+  if (typeof feed.url !== 'string' || feed.url === '') return 'feed.url 须为非空字符串';
+  if (typeof feed.sha256 !== 'string' || !/^[0-9a-fA-F]{64}$/.test(feed.sha256)) return 'feed.sha256 须为 64 位 hex';
+  if (!Number.isSafeInteger(feed.size) || feed.size <= 0) return 'feed.size 须为正整数';
+  return null;
+}
+
+/**
+ * `fde2e-bu update` 子命令（C5）：发现（--ext-dir 免扫描 / 缺省 C1 扫描）→
+ * feed 检查（semver 只认 >）→ 逐目录 applyUpdate（httpsOnly）。
+ * 0 命中 exit 1＋指引；受管安装让路（含 --ext-dir 指向受管目录）；--dry-run 只报不写。
+ * @returns {Promise<number>} exit code
+ */
+export async function cmdSelfUpdate({
+  extDir, feed = DEFAULT_FEED_URL, dryRun = false,
+  home = homedir(), platform = process.platform,
+  fetchImpl, sleepImpl, env = process.env,
+} = {}) {
+  // 1. 发现（先于任何网络访问——0 命中不需要 feed）
+  let targets = [];
+  if (extDir !== undefined) {
+    const abs = resolve(String(extDir));
+    if (isManagedPath(abs, home)) {
+      console.error(`跳过：${abs} 由 FDE2E Omni 桌面版管理，插件随 App 更新。`);
+      return 1;
+    }
+    const version = readDirVersion(abs);
+    if (version === null) {
+      console.error(`--ext-dir 目录缺 manifest.json（或无 version 字段）：${abs}`);
+      return 1;
+    }
+    targets = [{ path: abs, browser: 'ext-dir', profile: '-', version }];
+  } else {
+    const found = locateInstalls({ home, platform }); // CLI 无 runningVersion：不过滤版本
+    for (const m of found.managed) console.log(`跳过（受 FDE2E Omni 桌面版管理，插件随 App 更新）：${m.path}`);
+    for (const r of found.rejected) console.log(`跳过（manifest 缺失或不可解析）：${r.path}`);
+    targets = found.matches;
+    if (targets.length === 0) {
+      console.error('未找到 unpacked 安装（0 命中）。');
+      console.error('  1. 确认浏览器已装 FDE2E 扩展（unpacked 加载）后重试；');
+      console.error('  2. 安装在非常规位置时用 --ext-dir <目录> 显式指定；');
+      console.error('  3. 受 FDE2E Omni 桌面版管理的安装随 App 更新，不走本命令。');
+      return 1;
+    }
+  }
+  console.log(`发现 ${targets.length} 处安装：`);
+  for (const t of targets) console.log(`  - ${t.path}（${t.browser}/${t.profile}，v${t.version}）`);
+
+  // 2. feed（--feed 仅强制 https——C5 运维明知故为）
+  let feedUrl;
+  try {
+    feedUrl = new URL(String(feed));
+  } catch {
+    console.error(`--feed url 无法解析：${feed}`);
+    return 1;
+  }
+  if (feedUrl.protocol !== 'https:') {
+    console.error(`--feed 必须 https（收到 ${feedUrl.protocol}//${feedUrl.host}）`);
+    return 1;
+  }
+  const fetchFn = fetchImpl ?? globalThis.fetch;
+  let feedJson;
+  try {
+    const res = await fetchFn(feedUrl.href);
+    if (!res || !res.ok) throw new Error(`HTTP ${res?.status ?? '???'}`);
+    feedJson = JSON.parse(await res.text());
+  } catch (err) {
+    console.error(`feed 获取失败（${feedUrl.href}）：${err?.message ?? err}`);
+    return 1;
+  }
+  const shapeErr = validateFeed(feedJson);
+  if (shapeErr !== null) {
+    console.error(`feed 形状不符：${shapeErr}`);
+    return 1;
+  }
+  const base = new URL('./', feedUrl).href;
+  let dl;
+  try {
+    dl = new URL(feedJson.url, base);
+  } catch {
+    console.error(`feed.url 无法按基址解析：${feedJson.url}（基址 ${base}）`);
+    return 1;
+  }
+  console.log(`feed：v${feedJson.version}（${dl.href}，${feedJson.size}B）`);
+
+  // 3. semver 比较（只认 >；等/低 no-op）
+  const due = targets.filter((t) => compareSemver(feedJson.version, t.version) > 0);
+  const fresh = targets.filter((t) => compareSemver(feedJson.version, t.version) <= 0);
+  for (const t of fresh) console.log(`已是最新（v${t.version}）：${t.path}`);
+  if (due.length === 0) {
+    console.log('没有需要更新的安装。');
+    return 0;
+  }
+  if (dryRun) {
+    for (const t of due) console.log(`[dry-run] 将更新：${t.path}（v${t.version} → v${feedJson.version}）`);
+    console.log('dry-run：未写盘。');
+    return 0;
+  }
+
+  // 4. 逐目录应用（多命中全部应用；任一失败不回滚其它——如实逐条报告）
+  let failed = 0;
+  for (const t of due) {
+    try {
+      const r = await applyUpdate({
+        url: dl.href, sha256: feedJson.sha256, size: feedJson.size, destDir: t.path,
+        ...(fetchImpl ? { fetchImpl } : {}), ...(sleepImpl ? { sleepImpl } : {}),
+        httpsOnly: true,
+      });
+      console.log(`已更新：${t.path}（v${r.from ?? '(无旧版本)'} → v${r.to}）`);
+    } catch (err) {
+      failed++;
+      console.error(`更新失败（${err?.code ?? 'io'}）：${t.path}——${err?.message ?? err}`);
+    }
+  }
+  return failed > 0 ? 1 : 0;
+}