zipcalm 0.0.0-stage → 1.0.1

package/server/plugins/formats/_shared/entrySafety.js

@@ -0,0 +1,174 @@
+// 归档条目安全判定与写出（**所有格式包共用一套**，M4）
+//
+// 为什么必须共用：zip-slip 防护是 M2 验收过的关键安全代码（拒绝 `..` / 绝对路径 / 盘符 / NUL / symlink 逃逸）。
+// 每个格式各写一份 = 迟早漂移出漏洞；tar 与 zip 的差异只在"条目从哪来"，判定与写出完全一致。
+//
+// 判定复用 core/fs/safePath.js 的 normalizeUserPath（与 pathGuard 同一套语义），
+// 再叠加归档特有的盘符检查与"目标目录 + 分隔符"前缀校验。
+//
+// 写盘顺序铁律：**先把所有条目判定完，再开始写** —— 恶意归档不会产生"写到一半才发现"的副作用。
+
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { pipelineWith } from './streams.js';
+
+import { ERROR_CODES, apiError } from '../../../lib/errors.js';
+import { pathExists } from '../../../lib/fs-probe.js';
+import { createThrottledReporter } from '../../../lib/throttle.js';
+import { normalizeUserPath } from '../../../core/fs/safePath.js';
+import { repairEntries } from './nameRepair.js';
+
+const MAX_PATH_LENGTH = 4096;
+const MAX_SEGMENT_LENGTH = 255;
+
+/** 仅返回 basename：错误 details 里绝不出现本机绝对路径 */
+export function safeName(target) {
+  return typeof target === 'string' ? path.basename(target) : null;
+}
+
+/**
+ * 归档条目名 → 目标目录内的绝对路径；任何逃逸企图直接抛错（zip-slip 核心）。
+ * @returns {{targetPath: string, segments: string[], isRoot: boolean}}
+ */
+export function resolveEntryTarget(targetDir, entryName) {
+  if (typeof entryName !== 'string' || entryName.length === 0) {
+    throw apiError(ERROR_CODES.INVALID_PATH, '归档条目名为空', { entry: entryName });
+  }
+  const unified = entryName.replace(/\\/g, '/');
+  // 盘符（Windows 绝对路径形态，如 C:/evil）：API 语义里不可能合法
+  if (/^[A-Za-z]:/.test(unified)) {
+    throw apiError(ERROR_CODES.PATH_OUT_OF_ROOT, '归档条目含盘符（zip-slip）', { entry: entryName });
+  }
+  // 绝对路径：一律拒绝（总是相对目标目录展开）
+  if (unified.startsWith('/')) {
+    throw apiError(ERROR_CODES.PATH_OUT_OF_ROOT, '归档条目为绝对路径（zip-slip）', { entry: entryName });
+  }
+
+  let normalized;
+  try {
+    normalized = normalizeUserPath(unified, {
+      maxPathLength: MAX_PATH_LENGTH,
+      maxPathSegmentLength: MAX_SEGMENT_LENGTH,
+    });
+  } catch (error) {
+    // normalizeUserPath 抛的是契约错误（.. / 编码 .. / NUL / 超长）：原样抛，只补条目名便于定位
+    if (error && error.details) error.details.entry = entryName;
+    throw error;
+  }
+
+  const root = path.resolve(targetDir);
+  const target = path.resolve(root, ...normalized.segments);
+  if (target !== root && !target.startsWith(root + path.sep)) {
+    throw apiError(ERROR_CODES.PATH_OUT_OF_ROOT, '归档条目逃逸目标目录（zip-slip）', { entry: entryName });
+  }
+  return { targetPath: target, segments: normalized.segments, isRoot: target === root };
+}
+
+/** 符号链接条目：M4 策略同样是**一律拒绝**（比"仅拒绝指向目标外的链接"更保守） */
+export function rejectSymlink(entryName) {
+  throw apiError(ERROR_CODES.PATH_OUT_OF_ROOT, '归档包含符号链接条目，已拒绝解压', { entry: entryName });
+}
+
+/**
+ * 写盘前的条目预检：zip-slip 判定 + 覆盖判定（INV-08）。
+ * @param {Array<{name: string, isDir: boolean, size: number, link?: boolean, open?: Function}>} entries
+ * @param {string} targetDir 目标目录（绝对路径）
+ * @param {boolean} overwrite 是否允许覆盖已有同名文件
+ */
+export async function planTargets(entries, targetDir, overwrite) {
+  const plan = [];
+  let totalBytes = 0;
+  let totalFiles = 0;
+
+  // 共享阶段：先在**还原后的名字**上做路径判定（否则 `../` 可能藏在 PUA 转义里逃过检查）。
+  // 还原是增强不是必需路径：解不开/撞名就保留原名，绝不阻断解压。
+  const repaired = repairEntries(entries);
+
+  for (const entry of repaired.entries) {
+    if (entry.link) rejectSymlink(entry.name);
+    const unified = String(entry.name || '').replace(/\\/g, '/');
+    const nameForCheck = unified.replace(/\/+$/, '');
+    const resolved = resolveEntryTarget(targetDir, nameForCheck);
+    const isDir = Boolean(entry.isDir) || unified.endsWith('/');
+    const size = isDir ? 0 : Number(entry.size || 0);
+
+    plan.push({
+      entry,
+      isDir,
+      targetPath: resolved.targetPath,
+      displayName: entry.name,
+      size,
+      open: entry.open,
+    });
+    if (!isDir) {
+      totalBytes += size;
+      totalFiles += 1;
+    }
+  }
+
+  if (!overwrite) {
+    for (const plannedEntry of plan) {
+      if (plannedEntry.isDir) continue;
+      if (await pathExists(plannedEntry.targetPath)) {
+        throw apiError(ERROR_CODES.TARGET_EXISTS, '目标目录已存在同名文件（overwrite=false）', { entry: plannedEntry.displayName });
+      }
+    }
+  }
+
+  return { plan, totalBytes, totalFiles, repairedNames: repaired.repaired, repairConflicts: repaired.conflicts };
+}
+
+/**
+ * 按计划写盘：目录先建、文件走流式管道；失败/取消清理半成品（契约 §3.4.1 第 4 条）。
+ * @param {{plan: Array, totalBytes: number, totalFiles: number}} planned planTargets 的返回
+ */
+export async function writePlan(planned, targetDir, options = {}) {
+  const { signal } = options;
+  const report = createThrottledReporter(options.onProgress || (() => {}), { intervalMs: 100 });
+  let processedBytes = 0;
+  let processedFiles = 0;
+  let entries = 0;
+
+  await fsp.mkdir(targetDir, { recursive: true });
+
+  for (const plannedEntry of planned.plan) {
+    if (signal && signal.aborted) throw apiError(ERROR_CODES.ABORTED, '任务已取消');
+
+    if (plannedEntry.isDir) {
+      await fsp.mkdir(plannedEntry.targetPath, { recursive: true });
+      entries += 1;
+      continue;
+    }
+
+    await fsp.mkdir(path.dirname(plannedEntry.targetPath), { recursive: true });
+    try {
+      // 注意：signal 为空时绝不能传 undefined（pipeline 会把它当 stage 校验并抛错）
+      await pipelineWith([plannedEntry.open(), fs.createWriteStream(plannedEntry.targetPath)], signal);
+    } catch (error) {
+      try {
+        // force: true = 不存在也不算错（因此不需要先探一次是否存在）
+        await fsp.rm(plannedEntry.targetPath, { force: true });
+      } catch {
+        /* 清理失败不掩盖原始错误 */
+      }
+      if (error && (error.name === 'AbortError' || (signal && signal.aborted))) {
+        throw apiError(ERROR_CODES.ABORTED, '任务已取消');
+      }
+      throw error;
+    }
+
+    entries += 1;
+    processedFiles += 1;
+    processedBytes += plannedEntry.size;
+    report({
+      processedBytes,
+      totalBytes: planned.totalBytes,
+      processedFiles,
+      totalFiles: planned.totalFiles,
+      currentFile: plannedEntry.displayName,
+    });
+  }
+
+  return { entries, bytesOut: processedBytes };
+}

package/server/plugins/formats/_shared/nameRepair.js

@@ -0,0 +1,123 @@
+// 乱码文件名的识别与还原（**跨格式共享**：zip / tar / 7z / rar 都受益）
+//
+// 原理（实测，见 docs/17 D-13）：老版 unrar（5.70）与 node-unrar-js（内置 6.1.7）等引擎，
+// 在处理 RAR5 的 UTF-8 文件名时会把字节**逐个**转成 Unicode 私有区字符，并在开头插一个 U+FFFE 标记：
+//
+//   原始字节  e4 b8 ad e6 96 87 …（"中文…"）
+//   落盘名    73 37 2f efbfbe ee83a4 ee82b8 ee82ad …
+//             └s7/┘└U+FFFE┘└── U+E0XX（= 原字节 0xXX）──┘
+//
+// 这是**无损字节转义**：去掉 U+FFFE，把每个 U+E0xx 还原成字节 0xXX，拼回 UTF-8 即得原名。
+//
+// ⚠️ 前置条件：引擎必须在 `en_US.UTF-8`（或 zh_CN.UTF-8）下运行。默认 locale 与 **C.UTF-8** 都会
+// 输出有损的 `?`（字节已丢，不可还原）—— 这是实测踩到的陷阱。
+//
+// 判定**宁严勿松**：宁可漏还原（用户还能手动改），也不能误改正常文件名。
+// 三重校验全过才还原：① 含 U+FFFE 标记 ② 解码结果是合法 UTF-8 ③ 往返一致（重新编码 == 原始字节）。
+
+/** 私有区字节替身的码点范围：U+E000..U+E0FF 对应原始字节 0x00..0xFF */
+const PUA_BYTE_BASE = 0xe000;
+const PUA_BYTE_MAX = 0xe0ff;
+/** 转义标记：U+FFFE（非字符，正常文件名不可能包含） */
+const ESCAPE_MARKER = '\uFFFE';
+
+/** 名字里是否带转义标记（**硬门槛**：没有标记一律不动） */
+export function hasEscapeMarker(name) {
+  return String(name || '').includes(ESCAPE_MARKER);
+}
+
+/**
+ * 按 PUA 转义规则还原成字节，再解成 UTF-8 字符串。
+ * @param {string} name
+ * @returns {string} 还原结果（调用方必须自己再做校验，本函数不做判断）
+ */
+export function decodePuaEscaped(name) {
+  const cleaned = String(name || '').replaceAll(ESCAPE_MARKER, '');
+  const bytes = [];
+  for (const ch of cleaned) {
+    const cp = ch.codePointAt(0);
+    if (cp >= PUA_BYTE_BASE && cp <= PUA_BYTE_MAX) bytes.push(cp - PUA_BYTE_BASE);
+    else if (cp < 0x80) bytes.push(cp);
+    else bytes.push(...Buffer.from(ch, 'utf8'));
+  }
+  return Buffer.from(bytes).toString('utf8');
+}
+
+/** 把转义名还原出的原始字节序列（供报告里贴 hex） */
+export function escapedBytesHex(name) {
+  const cleaned = String(name || '').replaceAll(ESCAPE_MARKER, '');
+  const bytes = [];
+  for (const ch of cleaned) {
+    const cp = ch.codePointAt(0);
+    if (cp >= PUA_BYTE_BASE && cp <= PUA_BYTE_MAX) bytes.push(cp - PUA_BYTE_BASE);
+    else if (cp < 0x80) bytes.push(cp);
+    else bytes.push(...Buffer.from(ch, 'utf8'));
+  }
+  return Buffer.from(bytes).toString('hex');
+}
+
+/**
+ * 判定单条名字是否应还原（三重校验）。
+ * @param {string} name
+ * @returns {{name: string, repaired: boolean, reason: string|null, hex?: string}}
+ */
+export function repairName(name) {
+  const original = String(name || '');
+  // ① 硬门槛：必须含 U+FFFE 标记（正常名即使含合法私有区字符也不会被误改）
+  if (!hasEscapeMarker(original)) return { name: original, repaired: false, reason: null };
+  const hex = escapedBytesHex(original);
+  const candidate = decodePuaEscaped(original);
+  // ② 必须是合法 UTF-8（解出替换符说明字节非法）
+  if (!candidate || candidate.includes('\uFFFD')) {
+    return { name: original, repaired: false, reason: 'invalid-utf8', hex };
+  }
+  // ③ 往返一致：把结果按 UTF-8 重新编码，必须等于原始字节序列
+  if (Buffer.from(candidate, 'utf8').toString('hex') !== hex) {
+    return { name: original, repaired: false, reason: 'roundtrip-mismatch', hex };
+  }
+  // 路径结构必须仍然正常（不允许还原出空段 / . / ..，防止藏在转义里的越界）
+  //
+  // 注意：**目录条目名带尾部 '/'**（收集阶段就是用尾斜杠标记目录的），
+  // 不能把那个尾斜杠当成「空段」判成非法 —— 否则凡是被转义的目录名都永远还原不了，
+  // 而它的子文件却能还原，结果是目录与子项名字对不上、结构错位（实测踩到）。
+  const hadTrailingSlash = candidate.endsWith('/');
+  const body = hadTrailingSlash ? candidate.slice(0, -1) : candidate;
+  if (body.length === 0) return { name: original, repaired: false, reason: 'unsafe-path', hex };
+  const segments = body.split('/');
+  if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+    return { name: original, repaired: false, reason: 'unsafe-path', hex };
+  }
+  const decoded = hadTrailingSlash ? `${body}/` : body;
+  if (decoded === original) return { name: original, repaired: false, reason: null };
+  return { name: decoded, repaired: true, reason: null, hex };
+}
+
+/**
+ * 批量还原一组条目名，并处理"还原后撞名"。
+ *
+ * 撞名策略：**保留原名**（不静默覆盖、不静默改名），把冲突记进 conflicts 交给调用方记日志/报告。
+ *
+ * @param {Array<{name: string}>} entries
+ * @returns {{entries: Array, repaired: number, conflicts: Array<{from: string, to: string, reason: string}>}}
+ */
+export function repairEntries(entries) {
+  const conflicts = [];
+  const taken = new Set(entries.map((entry) => String(entry.name || '')));
+  let repaired = 0;
+
+  const next = entries.map((entry) => {
+    const verdict = repairName(entry.name);
+    if (!verdict.repaired) return entry;
+    // 同一批里还原后与他人（原始名或已还原名）撞名 → 放弃这次还原
+    if (taken.has(verdict.name) && verdict.name !== entry.name) {
+      conflicts.push({ from: entry.name, to: verdict.name, reason: 'target-exists' });
+      return entry;
+    }
+    taken.delete(String(entry.name || ''));
+    taken.add(verdict.name);
+    repaired += 1;
+    return { ...entry, name: verdict.name, nameRepairedFrom: entry.name };
+  });
+
+  return { entries: next, repaired, conflicts };
+}

package/server/plugins/formats/_shared/streams.js

@@ -0,0 +1,18 @@
+// 流工具（各格式包共用的小工具）
+//
+// 为什么要单独抽一个 `pipelineWith`：`stream.pipeline(a, b, undefined)` **不是"没有选项"**，
+// 而是把 `undefined` 当成一个 stage 去校验并抛
+// `The "body" argument must be of type function or ... Received undefined`。
+// 而"有取消信号时传 { signal }、没有时不传"是很自然的写法 —— 一不留神就写成了三元表达式带 undefined。
+// 实测踩过：M4 的 tar 系列在没有信号时崩在这里（zip 侧因为运行期总有信号，一直没暴露）。
+
+import { pipeline } from 'node:stream/promises';
+
+/**
+ * 按需附加 `{ signal }` 的 pipeline（signal 为空时不传第三个参数）。
+ * @param {Array} stages 至少两个流（最后一个是目标）
+ * @param {AbortSignal} [signal]
+ */
+export function pipelineWith(stages, signal) {
+  return signal ? pipeline(...stages, { signal }) : pipeline(...stages);
+}

package/server/plugins/formats/_shared/tar/compression.js

@@ -0,0 +1,114 @@
+// tar 系列的**压缩层策略**（tar / tar.gz / tar.zst 只差这一层）
+//
+// zstd 走「能力自探测 + 回退链」（docs/02 §二）：
+//   ① Node ≥ 22.15 内置 `node:zlib` 的 zstd（零依赖、流式）—— 首选；
+//   ② 系统 `zstd` 命令（`ZC_ZSTD_BIN` 可覆盖路径）；
+//   ③ 都不可用 → `available()=false` 并给出原因（由上层 tarFamily 组装）。
+//
+// 排障开关：`ZIPCALM_DISABLE_BUILTIN_ZSTD=1` 强制禁用内置实现，用于验证回退链是否真的生效。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { Duplex } from 'node:stream';
+import zlib from 'node:zlib';
+
+import { ERROR_CODES, apiError } from '../../../../lib/errors.js';
+
+/** Node 内置 zstd 是否可用（可用环境变量强制禁用，便于验证回退链） */
+export function builtinZstdUsable() {
+  if (process.env.ZIPCALM_DISABLE_BUILTIN_ZSTD === '1') return false;
+  return typeof zlib.createZstdCompress === 'function' && typeof zlib.createZstdDecompress === 'function';
+}
+
+/** 系统 zstd 命令探测：ZC_ZSTD_BIN 覆盖 → PATH 查找（找不到返回 null） */
+export function findZstdBinary() {
+  const override = process.env.ZC_ZSTD_BIN;
+  if (override) {
+    try {
+      fs.accessSync(override, fs.constants.X_OK);
+      return override;
+    } catch {
+      // 指定了但不可执行：视为不可用，不静默落到 PATH（避免"以为换了实现其实没换"）
+      return null;
+    }
+  }
+  for (const dir of String(process.env.PATH || '').split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, 'zstd');
+    try {
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return candidate;
+    } catch {
+      /* 继续找 */
+    }
+  }
+  return null;
+}
+
+/** 把一个外部命令包装成 Duplex（stdin 进 / stdout 出），失败即 destroy —— 回退链的流式实现 */
+export function spawnDuplex(command, args, label) {
+  const child = spawn(command, args, { stdio: ['pipe', 'pipe', 'inherit'] });
+  const duplex = new Duplex({
+    write(chunk, encoding, callback) {
+      if (child.stdin.write(chunk, encoding)) callback();
+      else child.stdin.once('drain', callback);
+    },
+    final(callback) {
+      child.stdin.end();
+      callback();
+    },
+    read() {
+      child.stdout.resume();
+    },
+  });
+  let exited = false;
+  child.stdout.on('data', (chunk) => {
+    if (!duplex.push(chunk)) child.stdout.pause();
+  });
+  child.stdout.on('end', () => {
+    if (!exited) duplex.push(null);
+  });
+  child.on('error', (error) => duplex.destroy(apiError(ERROR_CODES.INTERNAL_ERROR, `${label} 启动失败：${error.message}`)));
+  child.on('close', (code) => {
+    exited = true;
+    if (code !== 0) duplex.destroy(apiError(ERROR_CODES.INTERNAL_ERROR, `${label} 退出码 ${code}`));
+    else duplex.push(null);
+  });
+  return duplex;
+}
+
+/** 压缩流（写归档时用；compression='none' 返回 undefined 表示不套压缩层） */
+export function createCompressStream(compression, level) {
+  if (compression === 'gzip') return zlib.createGzip({ level });
+  if (compression === 'zstd') {
+    if (builtinZstdUsable()) {
+      return zlib.createZstdCompress({ params: { [zlib.constants.ZSTD_c_compressionLevel]: level } });
+    }
+    const binary = findZstdBinary();
+    if (!binary) throw apiError(ERROR_CODES.FORMAT_UNAVAILABLE, 'zstd 不可用：Node 内置不可用且未找到系统 zstd');
+    return spawnDuplex(binary, [`-${level}`, '-q', '-c'], 'zstd');
+  }
+  return undefined;
+}
+
+/** 解压流（读归档时用） */
+export function createDecompressStream(compression) {
+  if (compression === 'gzip') return zlib.createGunzip();
+  if (compression === 'zstd') {
+    if (builtinZstdUsable()) return zlib.createZstdDecompress();
+    const binary = findZstdBinary();
+    if (!binary) throw apiError(ERROR_CODES.FORMAT_UNAVAILABLE, 'zstd 不可用：Node 内置不可用且未找到系统 zstd');
+    return spawnDuplex(binary, ['-d', '-q', '-c'], 'zstd');
+  }
+  return undefined;
+}
+
+/** 打开归档并接上解压层（返回可读流；解析错误由调用方映射成 ARCHIVE_CORRUPTED） */
+export function openArchiveStream(archivePath, compression) {
+  const source = fs.createReadStream(archivePath);
+  const decompressor = createDecompressStream(compression);
+  if (!decompressor) return source;
+  source.on('error', (error) => decompressor.destroy(error));
+  return source.pipe(decompressor);
+}

package/server/plugins/formats/_shared/tar/reader.js

@@ -0,0 +1,74 @@
+// tar 系列的**读取侧**：流式解析 + 条目读取辅助 + 错误映射
+//
+// 三种 tar 格式共用同一套解析（压缩层由 compression.js 负责解掉）。
+
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+
+import * as tar from 'tar';
+
+import { ERROR_CODES, apiError } from '../../../../lib/errors.js';
+import { openArchiveStream } from './compression.js';
+
+/**
+ * 流式解析归档：逐条目回调。
+ *
+ * **关键约束（实测踩过）**：`onentry` 里必须**同步**接管条目流（attach 消费者 / resume），
+ * 只要延迟一个微任务，node-tar 就把该条目的数据丢掉（实测同一归档：同步读到 5/7 字节，延迟读到 0 字节）。
+ * 因此回调本身不做 await，而是"同步启动消费并返回 Promise"，由这里统一收集等待。
+ */
+export async function parseArchive(archivePath, compression, onEntry) {
+  const pending = [];
+  const errors = [];
+  const parser = tar.list({
+    onentry: (entry) => {
+      try {
+        const handlerResult = onEntry(entry);
+        if (handlerResult && typeof handlerResult.then === 'function') {
+          pending.push(handlerResult.catch((error) => errors.push(error)));
+        }
+      } catch (error) {
+        errors.push(error);
+        entry.resume();
+      }
+    },
+  });
+  await pipeline(openArchiveStream(archivePath, compression), parser);
+  await Promise.all(pending);
+  if (errors.length > 0) throw errors[0];
+}
+
+/** 读条目内容（用于 test 的 read-all 校验） */
+export function readEntryBuffer(entry) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    entry.on('data', (chunk) => chunks.push(chunk));
+    entry.on('end', () => resolve(Buffer.concat(chunks)));
+    entry.on('error', reject);
+  });
+}
+
+/** node-tar 条目 → 契约里的条目形态（name/type/size/compressedSize） */
+export function toApiEntry(entry) {
+  const name = entry.path || entry.name || '';
+  const isDir = entry.type === 'Directory';
+  return {
+    name,
+    type: isDir ? 'dir' : 'file',
+    size: Number(entry.size || 0),
+    compressedSize: 0,
+  };
+}
+
+/** 归档解析失败统一映射成契约错误码（不透传本机路径） */
+export function mapArchiveError(error, archivePath) {
+  if (error && error.code && String(error.code).startsWith('A')) return error; // 已是契约错误码
+  const reason = (error && (error.code || error.message)) || 'parse-failed';
+  if (reason === 'ENOENT') {
+    return apiError(ERROR_CODES.PATH_NOT_FOUND, '压缩包不存在', { archive: path.basename(archivePath) });
+  }
+  return apiError(ERROR_CODES.ARCHIVE_CORRUPTED, '压缩包无法解析（可能已损坏）', {
+    archive: path.basename(archivePath),
+    reason,
+  });
+}