fde2e-bu 1.3.0 → 1.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fde2e-bu",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "FDE2E Browser Use CLI —— skills 管理＋MCP server＋扩展配对（零运行时依赖）",
   "type": "module",
   "bin": {

package/src/nm/asset.mjs

@@ -0,0 +1,296 @@
+// NM 资产代取（change bu-chrome154-downloads B1，design §A）——SW 发起
+// `bu:asset-fetch`，host 按白名单校验后流式下载到生态资产目录
+// `~/fde2e/bu/assets/<safe-name>`，回绝对路径（CDP DOM.setFileInputFiles 消费）。
+// 背景：Chrome 154 上 chrome.downloads 对插件全量即断——配图上传链改走本通道，
+// 浏览器下载仅作保底回退（SW 侧 cdp.js downloadTo）。
+//
+// 契约（帧协议不变，host.mjs 写队列串行应答）：
+//   → {type:'bu:asset-fetch', url, name, maxBytes, allowHosts:[…]}
+//   ← {type:'bu:asset-fetch:ok', path, bytes, finalUrl, sha256}
+//   ← {type:'bu:asset-fetch:error', code, message}
+//     code ∈ bad-msg|bad-url|not-allowed|too-large|net|io
+//     （bad-msg/bad-url/not-allowed/too-large＝确定性拒绝——SW 侧不回退直接抛；
+//      net/io＝环境性失败——SW 无 CLI 时可回退 chrome.downloads）
+//
+// 安全边界（design §A「白名单双闸」的 host 侧）：
+//   - host **不自带**业务白名单（allowHosts 由 SW 从 constraints 传入），但强制
+//     协议与域校验——https-only（http 仅本机回环 dev）＋ allowHosts 成员匹配；
+//   - 重定向**逐跳**白名单（manual redirect 循环，任何一跳越权即断，最多 5 跳）；
+//   - maxBytes 双闸：content-length 预检 ＋ 流式累计（超限即断，不做无界落盘）；
+//   - 落盘 temp+rename 原子写；safe-name 同 cdp.js 规则（/ 与 \ 替换 _，另拒
+//     '.'/'..' 防目录逃逸）；写前清扫目录内 mtime>24h 文件（即取即用语义，防
+//     无界增长）。
+// 依赖全注入可测（home/fs/fetchImpl/now/sweepTtlMs）。
+import { createHash } from 'node:crypto';
+import * as realFs from 'node:fs';
+import { homedir } from 'node:os';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { join } from 'node:path';
+
+/** 消息类型（SW cdp.js assetFetch 客户端的入口消息）。 */
+export const ASSET_FETCH_MSG_TYPE = 'bu:asset-fetch';
+/** 重定向逐跳上限（design §A：redirect 逐跳白名单，5 跳预算）。 */
+export const MAX_REDIRECT_HOPS = 5;
+/** 资产目录内文件清扫 TTL（24h——上传即取即用，裕量覆盖重试）。 */
+export const ASSET_SWEEP_TTL_MS = 24 * 60 * 60 * 1000;
+/** http 放行的本机回环 host（URL.hostname 口径——IPv6 带方括号）。 */
+export const ASSET_LOOPBACK_HOSTS = ['127.0.0.1', 'localhost', '[::1]'];
+/** 单次 maxBytes 声明上限（防畸形巨值把资产目录当无界落盘面；业务上限在 SW 侧）。 */
+export const MAX_BYTES_CEILING = 1024 * 1024 * 1024;
+/** name 长度上限（文件名级；safe 化后仍适用）。 */
+export const NAME_MAX = 255;
+/** allowHosts 条数上限（防滥用；constraints 两侧白名单均 ≤4 条）。 */
+export const ALLOW_HOSTS_MAX = 64;
+
+/** 资产代取错误（code ∈ bad-msg|bad-url|not-allowed|too-large|net|io）。 */
+export function assetError(code, message) {
+  const err = new Error(message ?? code);
+  err.name = 'AssetFetchError';
+  err.code = code;
+  return err;
+}
+
+/** 本模块错误码封闭集（区分 Node 内建 err.code 如 ENOENT/EPIPE——那些按 io 兜底）。 */
+const ASSET_ERROR_CODES = new Set(['bad-msg', 'bad-url', 'not-allowed', 'too-large', 'net', 'io']);
+
+function errorReply(code, message) {
+  return { type: 'bu:asset-fetch:error', code, message };
+}
+
+/**
+ * 单跳校验（纯函数，供测试与逐跳循环共用）：
+ *   1. 协议必须 http(s)（其它协议 ⇒ bad-url）；
+ *   2. http 仅本机回环（⇒ not-allowed）；
+ *   3. hostname 必须是 allowHosts 成员（⇒ not-allowed）。
+ * @param {URL} u
+ * @param {string[]} allowHosts
+ * @returns {{code:string, message:string}|null}
+ */
+export function checkAssetHop(u, allowHosts) {
+  if (u.protocol !== 'https:' && u.protocol !== 'http:') {
+    return { code: 'bad-url', message: `资产 url 协议必须 http(s)（收到 ${u.protocol}//${u.hostname}）` };
+  }
+  if (u.protocol === 'http:' && !ASSET_LOOPBACK_HOSTS.includes(u.hostname)) {
+    return { code: 'not-allowed', message: `http 资产仅允许本机（${ASSET_LOOPBACK_HOSTS.join('/')}），收到 http://${u.hostname}` };
+  }
+  if (!allowHosts.includes(u.hostname)) {
+    return { code: 'not-allowed', message: `资产域名不在 allowHosts（只允许 ${allowHosts.join('/')}，收到 ${u.hostname}）` };
+  }
+  return null;
+}
+
+/** safe 化文件名（与 cdp.js downloadTo 同规则：/ 与 \ 替换 _；'.'/'..' 拒绝）。 */
+export function safeAssetName(name) {
+  // 路径分隔符 + Windows 保留字符一并替换（对抗审查 P3.3——跨平台优雅降级为可写名）
+  const safe = String(name).replace(/[/\\:*?"<>|\x00-\x1f]/g, '_');
+  if (safe === '.' || safe === '..') {
+    throw assetError('bad-msg', `资产 name 非法（${JSON.stringify(name)}——safe 化后仍是目录引用）`);
+  }
+  return safe;
+}
+
+/**
+ * 资产目录清扫（best-effort）：删除 mtime 早于 now−ttl 的**文件**（目录不动）；
+ * 单个 stat/unlink 失败忽略（清扫不阻断下载）。
+ */
+export function sweepAssetDir(dir, { ttlMs = ASSET_SWEEP_TTL_MS, now = Date.now(), fs = realFs } = {}) {
+  let names;
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return; // 目录不存在/不可读 → 无可清扫
+  }
+  for (const n of names) {
+    const p = join(dir, n);
+    try {
+      const st = fs.statSync(p);
+      if (!st.isFile()) continue;
+      if (now - st.mtimeMs > ttlMs) fs.rmSync(p, { force: true });
+    } catch { /* best-effort */ }
+  }
+}
+
+/** 丢弃响应体（redirect/manual 路径释放连接；无 body/不可取消则忽略）。 */
+async function discardBody(res) {
+  try {
+    if (res?.body?.cancel) await res.body.cancel();
+    else if (res?.body?.destroy) res.body.destroy();
+  } catch { /* 丢弃失败不阻断 */ }
+}
+
+/**
+ * 逐跳白名单下载循环（design §A：redirect:'manual'，任何一跳越权即断）。
+ * @returns {Promise<{res: object, finalUrl: string}>} 终跳 2xx 响应（body 未消费）
+ */
+async function fetchWithHopAllowlist(url, allowHosts, fetchImpl) {
+  let current = url;
+  for (let hop = 0; ; hop += 1) {
+    const deny = checkAssetHop(current, allowHosts);
+    if (deny) throw assetError(deny.code, deny.message);
+    let res;
+    try {
+      res = await fetchImpl(current.href, { redirect: 'manual' });
+    } catch (err) {
+      throw assetError('net', `资产下载失败（${current.host}）：${err?.message ?? err}`);
+    }
+    if (res && [301, 302, 303, 307, 308].includes(res.status)) {
+      const loc = res.headers?.get?.('location');
+      await discardBody(res);
+      if (typeof loc !== 'string' || loc === '') {
+        throw assetError('net', `重定向缺 Location（${current.host} → HTTP ${res.status}）`);
+      }
+      if (hop >= MAX_REDIRECT_HOPS) {
+        throw assetError('net', `重定向超过 ${MAX_REDIRECT_HOPS} 跳（终点 ${current.href}）`);
+      }
+      let next;
+      try {
+        next = new URL(loc, current.href); // 相对 Location 按当前跳解析
+      } catch {
+        throw assetError('net', `重定向 Location 无法解析：${loc}`);
+      }
+      current = next;
+      continue;
+    }
+    if (!res || typeof res.ok !== 'boolean' || !res.ok) {
+      await discardBody(res);
+      throw assetError('net', `资产下载失败（${current.host}）：HTTP ${res?.status ?? '???'}`);
+    }
+    // manual 模式下 res.url＝本跳请求 URL；缺省（桩环境）回退 current.href
+    const finalUrl = typeof res.url === 'string' && res.url !== '' ? res.url : current.href;
+    return { res, finalUrl };
+  }
+}
+
+/**
+ * 处理 bu:asset-fetch（async——下载/落盘是异步动作）。永不 reject：一切失败映射
+ * 错误帧（code 语义见文件头）。
+ * @param {unknown} msg
+ * @param {{ home?: string, fs?: object, fetchImpl?: Function, now?: () => number,
+ *           sweepTtlMs?: number }} [deps]
+ * @returns {Promise<{type:'bu:asset-fetch:ok', path:string, bytes:number, finalUrl:string, sha256:string}
+ *                 |{type:'bu:asset-fetch:error', code:string, message:string}>}
+ */
+export async function assetFetchHost(msg, deps = {}) {
+  // 1. 形状校验（结构性畸形 ⇒ bad-msg——确定性拒绝，SW 不回退）
+  if (msg === null || typeof msg !== 'object' || Array.isArray(msg)) {
+    return errorReply('bad-msg', '消息须为 JSON 对象');
+  }
+  if (msg.type !== ASSET_FETCH_MSG_TYPE) {
+    return errorReply('bad-msg', `未知消息类型：${JSON.stringify(msg.type ?? null)}`);
+  }
+  if (typeof msg.url !== 'string' || msg.url === '') {
+    return errorReply('bad-msg', `url 须为非空字符串（收到 ${JSON.stringify(msg.url ?? null)}）`);
+  }
+  if (typeof msg.name !== 'string' || msg.name === '' || msg.name.length > NAME_MAX) {
+    return errorReply('bad-msg', `name 须为 1~${NAME_MAX} 字符的字符串（收到 ${JSON.stringify(msg.name ?? null)}）`);
+  }
+  if (!Number.isSafeInteger(msg.maxBytes) || msg.maxBytes <= 0 || msg.maxBytes > MAX_BYTES_CEILING) {
+    return errorReply('bad-msg', `maxBytes 须为 (0, ${MAX_BYTES_CEILING}] 的整数（收到 ${JSON.stringify(msg.maxBytes ?? null)}）`);
+  }
+  if (!Array.isArray(msg.allowHosts) || msg.allowHosts.length === 0 || msg.allowHosts.length > ALLOW_HOSTS_MAX
+    || msg.allowHosts.some((h) => typeof h !== 'string' || h === '' || h.length > 253)) {
+    return errorReply('bad-msg', `allowHosts 须为 1~${ALLOW_HOSTS_MAX} 条非空字符串数组（收到 ${JSON.stringify(msg.allowHosts ?? null)}）`);
+  }
+  let safe;
+  try {
+    safe = safeAssetName(msg.name);
+  } catch (err) {
+    return errorReply(err.code, err.message);
+  }
+
+  const fsMod = deps.fs ?? realFs;
+  const fetchFn = deps.fetchImpl ?? globalThis.fetch;
+  if (typeof fetchFn !== 'function') {
+    return errorReply('net', '无可用 fetch（Node >= 18）');
+  }
+
+  /** 失败路径的 temp 残留清理（成功路径 rename 已把 temp 就位为终名）。 */
+  let tempPath = null;
+  try {
+    // 2. 首跳 URL 解析（字符串已到、不可解析 ⇒ bad-url）
+    let u;
+    try {
+      u = new URL(msg.url);
+    } catch {
+      throw assetError('bad-url', `资产 url 无法解析：${msg.url}`);
+    }
+
+    // 3. 逐跳白名单下载（含首跳协议/域校验）
+    const { res, finalUrl } = await fetchWithHopAllowlist(u, msg.allowHosts, fetchFn);
+    if (!res.body) throw assetError('net', '资产下载响应无 body');
+
+    // 4. content-length 预检（maxBytes 第一闸；无声明则只靠流式第二闸）
+    const clRaw = res.headers?.get?.('content-length');
+    if (typeof clRaw === 'string' && /^\d+$/.test(clRaw) && Number(clRaw) > msg.maxBytes) {
+      await discardBody(res);
+      throw assetError('too-large', `资产超限（content-length=${clRaw} > maxBytes=${msg.maxBytes}）`);
+    }
+
+    // 5. 落盘准备：目录 mkdir -p ＋ 写前清扫（mtime>ttl 的文件 best-effort 删）
+    const dir = join(deps.home ?? homedir(), 'fde2e', 'bu', 'assets');
+    fsMod.mkdirSync(dir, { recursive: true });
+    sweepAssetDir(dir, {
+      ...(deps.sweepTtlMs !== undefined ? { ttlMs: deps.sweepTtlMs } : {}),
+      // 专用 nowMs（epoch 毫秒）——不复用 host 共享 deps.now（那是 ISO 字符串，串线即
+      // 清扫静默失效的哑弹；对抗审查 P3.1）
+      ...(deps.nowMs !== undefined ? { now: deps.nowMs() } : {}),
+      fs: fsMod,
+    });
+    const finalPath = join(dir, safe);
+    tempPath = join(dir, `.bu-asset-${process.pid}-${safe}.tmp`);
+    fsMod.rmSync(tempPath, { force: true });
+
+    // 6. 流式累计（maxBytes 第二闸）＋ sha256 ＋ temp 写入 → rename 原子就位
+    const source = res.body.getReader ? Readable.fromWeb(res.body) : Readable.from(res.body);
+    const hash = createHash('sha256');
+    const sink = fsMod.createWriteStream(tempPath);
+    let bytes = 0;
+    try {
+      await pipeline(source, async function* countAndPass(chunks) {
+        for await (const chunk of chunks) {
+          bytes += chunk.length;
+          if (bytes > msg.maxBytes) {
+            throw assetError('too-large', `资产超限（流式累计 ${bytes} > maxBytes=${msg.maxBytes}）`);
+          }
+          hash.update(chunk);
+          yield chunk;
+        }
+      }, sink);
+    } catch (err) {
+      if (err?.name === 'AssetFetchError' && ASSET_ERROR_CODES.has(err.code)) throw err; // too-large 等本模块错误原样透传
+      throw assetError('io', `资产落盘中断：${err?.message ?? err}`);
+    } finally {
+      // 先等 sink 真正 close 再走外层清理——CI 实证（ubuntu/overlayfs）：destroy 是异步
+      // 语义，rmSync 抢跑会残留 .tmp（main run 39895242723 flake；mac 30 连跑不可复现）
+      await new Promise((resolve) => {
+        let settled = false;
+        const fin = () => { if (!settled) { settled = true; resolve(); } };
+        sink.once('close', fin);
+        try { sink.destroy(); } catch { fin(); /* 已关闭 */ }
+        setTimeout(fin, 1000); // close 事件缺席的兜底（不无限等）
+      });
+    }
+    try {
+      fsMod.renameSync(tempPath, finalPath);
+    } catch (err) {
+      fsMod.rmSync(tempPath, { force: true });
+      throw assetError('io', `资产原子就位失败（${safe}）：${err?.message ?? err}`);
+    }
+    return {
+      type: 'bu:asset-fetch:ok',
+      path: finalPath,
+      bytes,
+      finalUrl,
+      sha256: hash.digest('hex'),
+    };
+  } catch (err) {
+    if (tempPath !== null) {
+      try { fsMod.rmSync(tempPath, { force: true }); } catch { /* 清残留失败不遮蔽原错误 */ }
+    }
+    if (err?.name === 'AssetFetchError' && ASSET_ERROR_CODES.has(err.code)) {
+      return errorReply(err.code, err?.message ?? String(err));
+    }
+    return errorReply('io', err?.message ?? String(err)); // 兜底：未映射异常按 io
+  }
+}

package/src/nm/host.mjs

@@ -1,5 +1,6 @@
 // Native Messaging host（change bu-bind-http-publish A1/A2；bu-online-selfupdate A2
-// 增 bu:update）——Chrome NM 帧协议与 bu:pair/bu:update 消息处理。隐蔽子命令
+// 增 bu:update；bu-chrome154-downloads B1 增 bu:asset-fetch）——Chrome NM 帧协议与
+// bu:pair/bu:update/bu:asset-fetch 消息处理。隐蔽子命令
 // `fde2e-bu __nm-host` 直通本模块 runNmHost。
 //
 // 帧协议（Chrome Native Messaging 规范）：
@@ -12,15 +13,21 @@
 //   {type:'bu:update', feedVersion, url, sha256, size, runningVersion}
 //   （bu-online-selfupdate design C4：SW 判定有新版后请 host 定位 unpacked 安装并
 //   下载校验原子替换；url 相对形态按官方 downloads 基址解析，域名硬白名单。）
+//   {type:'bu:asset-fetch', url, name, maxBytes, allowHosts}
+//   （bu-chrome154-downloads design §A：Chrome 154 chrome.downloads 即断——SW 配图
+//   下载改 host 代取：逐跳白名单流式下载到 ~/fde2e/bu/assets/，回绝对路径＋sha256。）
 // 应答（CLI → 扩展）：
 //   成功 {type:'bu:pair:ok', cli:'fde2e-bu', version:<pkg>, saved:N}
 //        {type:'bu:update:ok', from, to, paths:[…]}（多命中全部应用）
+//        {type:'bu:asset-fetch:ok', path, bytes, finalUrl, sha256}
 //   失败 {type:'bu:pair:error', message:<原因>}（未知类型/校验不过/落盘失败）
 //        {type:'bu:update:error', code, message, paths?}
 //        （code ∈ managed|not-found|verify|bad-url|io|bad-msg——面板按码映射文案）
+//        {type:'bu:asset-fetch:error', code, message}
+//        （code ∈ bad-msg|bad-url|not-allowed|too-large|net|io——见 nm/asset.mjs）
 // 落盘：pairing.json（{version, savedAt, bindings}，atomicWrite 0600——复用
 //   src/mcp/config.mjs 的原子写底座）。pairing 只含 profileId/role/name/server 等
-//   非敏感标识，绝不含 token/credential。
+//   非敏感标识，绝不含 token/credential。资产代取落盘＝~/fde2e/bu/assets/（nm/asset.mjs）。
 // 生命周期：stdin EOF → 退出 0；一切日志只走 stderr（stdout 只有协议帧）。
 
 import { existsSync, readFileSync } from 'node:fs';
@@ -29,6 +36,7 @@ import { join } from 'node:path';
 import { atomicWrite } from '../mcp/config.mjs';
 import { resolveConfigDir } from '../configdir.mjs';
 import { locateInstalls, applyUpdate, EXTENSION_ID, resolveNmUrl } from './update.mjs';
+import { assetFetchHost } from './asset.mjs';
 import pkg from '../../package.json' with { type: 'json' };
 
 export const NM_HOST_NAME = 'com.fde2e.bu';
@@ -289,27 +297,36 @@ function errorReply(message) {
 
 /**
  * 单条 NM 消息 → 应答对象（不碰流；落盘经 deps 注入，纯逻辑可测）。
- * bu:update 走异步 handleUpdateMessage（返回 Promise——runNmHost 的写队列统一
- * 序列化应答帧）；其余（bu:pair/未知类型）同步应答，行为不变。
+ * bu:update 走异步 handleUpdateMessage、bu:asset-fetch 走异步 assetFetchHost
+ * （返回 Promise——runNmHost 的写队列统一序列化应答帧）；其余（bu:pair/未知类型）
+ * 同步应答，行为不变。
  * @param {unknown} msg 解析后的 JSON 值
  * @param {{ version?: string, now?: () => string, save?: (pairing:object) => void,
  *           home?: string, platform?: string, extId?: string,
- *           fetchImpl?: Function, sleepImpl?: Function, env?: object }} [deps]
+ *           fetchImpl?: Function, sleepImpl?: Function, env?: object,
+ *           fs?: object, sweepTtlMs?: number }} [deps]
  *   save 注入落盘动作；缺省＝写 resolveConfigDir() 下 pairing.json（调用时才解析
  *   env/家目录——测试可用 BU_CONFIG_DIR 重定向）。home/platform/fetchImpl/
- *   sleepImpl/env 属 bu:update 通道（定位与下载注入）。
+ *   sleepImpl/env 属 bu:update 通道（定位与下载注入）；home/fs/fetchImpl/now/
+ *   sweepTtlMs 属 bu:asset-fetch 通道（资产目录与下载注入）。
  * @returns {{type:'bu:pair:ok', cli:string, version:string, saved:number,
  *            received:number, truncated:boolean}
  *          |{type:'bu:pair:error', message:string}
- *          |Promise<{type:'bu:update:ok'|'bu:update:error', …}>}
+ *          |Promise<{type:'bu:update:ok'|'bu:update:error'|'bu:asset-fetch:ok'
+ *                   |'bu:asset-fetch:error', …}>}
  *   P1-2：received＝收到的原始条数、truncated＝扩展侧是否声明截断——截断要如实
  *   回执给 UI 显示「K 条未同步」，不再只报 saved 装作全量。
  */
 export function handleNmMessage(msg, deps = {}) {
-  // bu:update 分流（唯一异步通道）：形状校验/定位/下载全在 handleUpdateMessage 内
+  // bu:update 分流（异步通道）：形状校验/定位/下载全在 handleUpdateMessage 内
   if (msg !== null && typeof msg === 'object' && !Array.isArray(msg) && msg.type === 'bu:update') {
     return handleUpdateMessage(msg, deps);
   }
+  // bu:asset-fetch 分流（异步通道，bu-chrome154-downloads B1）：校验/逐跳白名单
+  // 下载/原子落盘全在 assetFetchHost 内；bu:pair/bu:update 行为零变更
+  if (msg !== null && typeof msg === 'object' && !Array.isArray(msg) && msg.type === 'bu:asset-fetch') {
+    return assetFetchHost(msg, deps);
+  }
   const version = deps.version ?? pkg.version;
   const check = validatePairMessage(msg);
   if (!check.ok) return errorReply(check.message);