@logictan/dsh-config-manager 0.1.60

package/src/security/vault.test.ts

@@ -0,0 +1,164 @@
+/**
+ * 文件级 vault 单元测试（src/security/vault.ts）。
+ *
+ * 覆盖：镜像 → 删除源 → 恢复 → 缺失提示；幂等；清理旧镜像；不覆盖已存在目标；
+ * 路径穿越防御。全部基于内存 FileSystemFacade mock（对齐 core 层解耦，node 可测）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import path from 'node:path';
+
+import { refreshVault, restoreVaultFiles, listVault, vaultRootOf, DEFAULT_SENSITIVE_RELS } from './vault.ts';
+import type { FileSystemFacade } from '../core/types.ts';
+import { normalizePath } from '../utils/paths.ts';
+
+/* ================= 内存 fs mock（key 与宿主一致：home 内绝对路径归一化） ================= */
+
+class MemFs implements FileSystemFacade {
+  files = new Map<string, Uint8Array>();
+  private readonly homeDir: string;
+  constructor(homeDir: string) {
+    this.homeDir = homeDir;
+  }
+  private key(p: string): string {
+    return normalizePath(path.resolve(this.homeDir, p));
+  }
+  async readFile(relPath: string): Promise<Uint8Array> {
+    const v = this.files.get(this.key(relPath));
+    if (v === undefined) throw new Error(`ENOENT: ${relPath}`);
+    return v;
+  }
+  async writeFile(relPath: string, data: Uint8Array): Promise<void> {
+    this.files.set(this.key(relPath), data);
+  }
+  async exists(relPath: string): Promise<boolean> {
+    return this.files.has(this.key(relPath));
+  }
+  async copy(from: string, to: string): Promise<void> {
+    const v = this.files.get(this.key(from));
+    if (v === undefined) throw new Error(`ENOENT: ${from}`);
+    this.files.set(this.key(to), v);
+  }
+  async remove(relPath: string): Promise<void> {
+    this.files.delete(this.key(relPath));
+  }
+  async listRecursive(dir: string): Promise<string[]> {
+    const base = normalizePath(path.resolve(this.homeDir));
+    const prefix = normalizePath(path.resolve(this.homeDir, dir));
+    const out: string[] = [];
+    for (const k of this.files.keys()) {
+      if (k === prefix || k.startsWith(prefix + '/')) {
+        out.push(k.slice(base.length).replace(/^[\\/]+/, ''));
+      }
+    }
+    return out.sort();
+  }
+  async mkdir(): Promise<void> { /* 内存实现无需建目录 */ }
+}
+
+const HOME = path.resolve('/home/alice'); // POSIX 风格绝对路径，跨平台 key 一致
+const DATA_DIR = path.join(HOME, 'dsh-config-manager');
+const CRED = '.credentials.yaml';
+const CRED_SRC = path.join(HOME, CRED);
+const CRED_VAULT = path.join(DATA_DIR, 'vault', CRED);
+const CRED_BYTES = Buffer.from('apiKey: sk-super-secret-123\n', 'utf8');
+
+test('refreshVault：现存敏感文件镜像入库，重复调用幂等', async () => {
+  const fs = new MemFs(HOME);
+  await fs.writeFile(CRED_SRC, CRED_BYTES);
+
+  const r1 = await refreshVault(fs, DATA_DIR, HOME, DEFAULT_SENSITIVE_RELS);
+  assert.deepEqual(r1.mirrored, [CRED], '应镜像 .credentials.yaml');
+  assert.deepEqual(r1.cleaned, [], '首次刷新无清理');
+  assert.deepEqual(r1.skipped, [], '无跳过项');
+  // vault 内容与源字节一致
+  const mirrored = await fs.readFile(CRED_VAULT);
+  assert.deepEqual(Buffer.from(mirrored), CRED_BYTES, 'vault 镜像字节应与源一致');
+
+  // 幂等：再次刷新结果一致，无重复条目
+  const r2 = await refreshVault(fs, DATA_DIR, HOME, DEFAULT_SENSITIVE_RELS);
+  assert.deepEqual(r2.mirrored, [CRED]);
+  const entries = await listVault(fs, DATA_DIR, HOME);
+  assert.equal(entries.length, 1, '重复刷新不应产生重复条目');
+  assert.equal(entries[0]!.rel, CRED);
+  assert.equal(entries[0]!.vaultPath, CRED_VAULT);
+});
+
+test('refreshVault：源缺失跳过；源删除与清单移除触发旧镜像清理', async () => {
+  const fs = new MemFs(HOME);
+
+  // 源缺失：不报错、不入库
+  const r0 = await refreshVault(fs, DATA_DIR, HOME, DEFAULT_SENSITIVE_RELS);
+  assert.deepEqual(r0.mirrored, []);
+  assert.deepEqual(r0.cleaned, []);
+
+  // 先镜像 → 删除源 → 再刷新：清理旧镜像
+  await fs.writeFile(CRED_SRC, CRED_BYTES);
+  await refreshVault(fs, DATA_DIR, HOME, DEFAULT_SENSITIVE_RELS);
+  assert.equal(await fs.exists(CRED_VAULT), true, '镜像应先入库');
+  await fs.remove(CRED_SRC); // 模拟凭据文件被删除
+  const r1 = await refreshVault(fs, DATA_DIR, HOME, DEFAULT_SENSITIVE_RELS);
+  assert.deepEqual(r1.mirrored, [], '源不存在不再镜像');
+  assert.deepEqual(r1.cleaned, [CRED], '源已删除 → 旧镜像被清理');
+  assert.equal(await fs.exists(CRED_VAULT), false, 'vault 旧镜像应已删除');
+
+  // 清单移除（rels 不再包含）：旧镜像同样被清理
+  await fs.writeFile(CRED_SRC, CRED_BYTES);
+  await refreshVault(fs, DATA_DIR, HOME, DEFAULT_SENSITIVE_RELS);
+  const r2 = await refreshVault(fs, DATA_DIR, HOME, []);
+  assert.deepEqual(r2.cleaned, [CRED], 'rel 不在清单 → 旧镜像被清理');
+});
+
+test('restoreVaultFiles：回填缺失目标、不覆盖已存在目标、缺失项提示重填', async () => {
+  const fs = new MemFs(HOME);
+  await fs.writeFile(CRED_VAULT, CRED_BYTES); // 只有 vault 有镜像
+
+  // 目标缺失 → 回填
+  const r1 = await restoreVaultFiles(fs, DATA_DIR, HOME, DEFAULT_SENSITIVE_RELS);
+  assert.deepEqual(r1.restored, [CRED]);
+  assert.deepEqual(r1.missing, []);
+  assert.deepEqual(Buffer.from(await fs.readFile(CRED_SRC)), CRED_BYTES, '目标应回填 vault 内容');
+
+  // 目标已存在 → 不覆盖（安全）
+  const newer = Buffer.from('apiKey: sk-newer-on-target\n', 'utf8');
+  await fs.writeFile(CRED_SRC, newer);
+  const r2 = await restoreVaultFiles(fs, DATA_DIR, HOME, DEFAULT_SENSITIVE_RELS);
+  assert.deepEqual(r2.restored, []);
+  assert.deepEqual(r2.skipped, [{ rel: CRED, reason: 'targetExists' }]);
+  assert.deepEqual(Buffer.from(await fs.readFile(CRED_SRC)), newer, '已存在目标不得被覆盖');
+
+  // vault 缺对应文件（跨机恢复/从未镜像）→ missing 提示重填
+  const OTHER = 'profiles/web/secrets.yaml';
+  const r3 = await restoreVaultFiles(fs, DATA_DIR, HOME, [CRED, OTHER]);
+  assert.deepEqual(r3.missing, [OTHER]);
+  assert.deepEqual(r3.restored, []);
+
+  // 跨机场景：vault 为空 → 全部 missing
+  const fs2 = new MemFs(HOME);
+  const r4 = await restoreVaultFiles(fs2, DATA_DIR, HOME, DEFAULT_SENSITIVE_RELS);
+  assert.deepEqual(r4.restored, []);
+  assert.deepEqual(r4.missing, [CRED], 'vault 空 = 跨机恢复，提示重填');
+});
+
+test('listVault：按 rel 排序列出镜像内容', async () => {
+  const fs = new MemFs(HOME);
+  await fs.writeFile(CRED_VAULT, CRED_BYTES);
+  await fs.writeFile(path.join(DATA_DIR, 'vault', 'profiles', 'web', 'secrets.yaml'), Buffer.from('token: t\n', 'utf8'));
+
+  const entries = await listVault(fs, DATA_DIR, HOME);
+  assert.deepEqual(entries.map((e) => e.rel), ['.credentials.yaml', 'profiles/web/secrets.yaml']);
+  assert.ok(entries.every((e) => e.vaultPath.startsWith(vaultRootOf(DATA_DIR))), 'vaultPath 应在 vault 根下');
+
+  // 空 vault → 空数组
+  const fs2 = new MemFs(HOME);
+  assert.deepEqual(await listVault(fs2, DATA_DIR, HOME), []);
+});
+
+test('非法 rel（路径穿越 / 绝对路径 / 盘符）被拒绝', async () => {
+  const fs = new MemFs(HOME);
+  const badRels = ['../escape.yaml', '/etc/passwd', 'C:\\evil.yaml', 'a/../../b.yaml'];
+  for (const rel of badRels) {
+    await assert.rejects(refreshVault(fs, DATA_DIR, HOME, [rel]), /非法敏感文件路径/, `refresh 应拒绝 ${rel}`);
+    await assert.rejects(restoreVaultFiles(fs, DATA_DIR, HOME, [rel]), /非法敏感文件路径/, `restore 应拒绝 ${rel}`);
+  }
+});

package/src/security/vault.ts

@@ -0,0 +1,198 @@
+/**
+ * 文件级 vault（敏感文件本机镜像，设计参考 dsh-backup 的「文件级 vault」思路）。
+ *
+ * 动机：字段级 Secret 扫描只能剥离结构化数据里的敏感值；像 .credentials.yaml 这类
+ * 「整文件即秘密」的文件，字节明文不进归档、不进同步，而是只镜像到本机
+ * <dataDir>/vault/ 目录（vault 目录本身绝不进入导出/同步，与 self 分区白名单互斥），
+ * 恢复（如跨机导入）时从 vault 回填 $DSH_HOME；vault 无对应文件（跨机恢复、
+ * 从未镜像过）则提示用户重填。比字段级扫描更彻底（整文件隔离）。
+ *
+ * 纯函数式设计：fs 一律经 FileSystemFacade 参数注入（对齐 core 层解耦原则），
+ * 不直接 import node:fs；node 环境可用内存 mock 全量测试。
+ * 路径约定：dshHome / dataDir 为绝对路径；敏感文件清单 rel 一律为相对 $DSH_HOME
+ * 的斜杠分隔相对路径（与 FileSystemFacade.listRecursive 的 home-relative 产出一致）。
+ *
+ * 安全不变量：
+ *  - vault 内容 = 敏感文件明文，仅存在于本机 dataDir，永不进入 ZIP / 同步 / 日志；
+ *  - rel 入参必须通过 isPathSafe（拒绝绝对路径 / .. / 盘符 / NUL），防路径穿越；
+ *  - 恢复不覆盖已存在的目标文件（避免覆盖目标机更新后的凭据），缺失项记入 missing。
+ *
+ * 权限说明：FileSystemFacade 无 chmod 能力（宿主 mkdir 已递归），vault 目录权限
+ * 跟随宿主 dataDir 既有策略；Windows 不强制 POSIX 权限位。
+ */
+import path from 'node:path';
+import type { FileSystemFacade } from '../core/types.ts';
+import { isPathSafe, normalizePath } from '../utils/paths.ts';
+
+/**
+ * 默认敏感文件清单（相对 $DSH_HOME）：当前 DSH 唯一「整文件即秘密」的文件
+ * （.credentials.yaml = 凭据明文 token/password/密钥）。
+ * 宿主可传入扩展清单（如 profiles/<p>/secrets.yaml、.env 等），默认清单保持最小。
+ */
+export const DEFAULT_SENSITIVE_RELS: readonly string[] = [
+  '.credentials.yaml',
+];
+
+/** vault 根目录 = <dataDir>/vault */
+export function vaultRootOf(dataDir: string): string {
+  return path.join(dataDir, 'vault');
+}
+
+/** refreshVault 结果 */
+export interface VaultRefreshResult {
+  /** 本次实际镜像入库的敏感文件（相对 $DSH_HOME） */
+  mirrored: string[];
+  /** 因源文件已不存在 / rel 不再属于清单而被清理的旧镜像（相对 $DSH_HOME） */
+  cleaned: string[];
+  /** 单个文件镜像失败（非致命：读源 / 写镜像异常），reason 为错误消息 */
+  skipped: { rel: string; reason: string }[];
+}
+
+/** restoreVaultFiles 结果 */
+export interface VaultRestoreResult {
+  /** 已从 vault 回填到 $DSH_HOME 的文件（相对 $DSH_HOME） */
+  restored: string[];
+  /** vault 中缺失、需要用户重填的文件（跨机恢复 vault 为空 → 全部缺失） */
+  missing: string[];
+  /** 跳过项：reason 为 'targetExists'（目标已存在不覆盖）或错误消息（拷贝失败） */
+  skipped: { rel: string; reason: string }[];
+}
+
+/** listVault 条目 */
+export interface VaultEntry {
+  /** 原始敏感文件路径（相对 $DSH_HOME） */
+  rel: string;
+  /** vault 内镜像的绝对路径 */
+  vaultPath: string;
+}
+
+/** rel 必须为安全相对路径（拒绝绝对路径 / .. / 盘符 / NUL），防路径穿越 */
+function assertSafeRel(rel: string): void {
+  if (!isPathSafe(rel)) throw new Error(`vault: 非法敏感文件路径 "${rel}"`);
+}
+
+/** 校验 + 归一化 rel 清单（统一 / 分隔，与 FileSystemFacade.listRecursive 产出对齐） */
+function normalizeRels(rels: readonly string[]): string[] {
+  const out: string[] = [];
+  for (const rel of rels) {
+    assertSafeRel(rel);
+    out.push(normalizePath(rel));
+  }
+  return out;
+}
+
+/**
+ * 刷新 vault：把 $DSH_HOME 下现存敏感文件镜像到 <dataDir>/vault/<rel>。
+ * 幂等：重复调用结果一致（同字节覆盖写，不产生重复条目）。
+ * 清理：源文件已不存在、或 rel 不再属于传入清单的旧镜像会被删除。
+ * 返回实际入库清单（供报告 / 提示「已镜像到本机 vault」）。
+ */
+export async function refreshVault(
+  fs: FileSystemFacade,
+  dataDir: string,
+  dshHome: string,
+  rels: readonly string[],
+): Promise<VaultRefreshResult> {
+  const normRels = normalizeRels(rels);
+  const vaultRoot = vaultRootOf(dataDir);
+  await fs.mkdir(vaultRoot); // 宿主 mkdir 递归；失败向上抛（调用方按尽力而为处理）
+  const mirrored: string[] = [];
+  const skipped: { rel: string; reason: string }[] = [];
+
+  // 1. 镜像现存敏感文件（源不存在则跳过；读/写失败按文件记录，不中断整体）
+  for (const rel of normRels) {
+    const src = path.join(dshHome, rel);
+    const dst = path.join(vaultRoot, rel);
+    try {
+      if (!(await fs.exists(src))) continue;
+      const data = await fs.readFile(src);
+      await fs.writeFile(dst, data);
+      mirrored.push(rel);
+    } catch (err) {
+      skipped.push({ rel, reason: err instanceof Error ? err.message : String(err) });
+    }
+  }
+
+  // 2. 清理旧镜像：源已不存在 或 rel 不再属于清单（listRecursive 产出为 home-relative）
+  const cleaned: string[] = [];
+  try {
+    const vaultFiles = await fs.listRecursive(vaultRoot);
+    for (const homeRel of vaultFiles) {
+      const vaultRel = normalizePath(path.relative(vaultRoot, path.join(dshHome, homeRel)));
+      if (vaultRel === '' || vaultRel.startsWith('..') || path.isAbsolute(vaultRel)) continue; // 防御：理论上不会发生
+      if (!normRels.includes(vaultRel)) {
+        await fs.remove(path.join(vaultRoot, vaultRel));
+        cleaned.push(vaultRel);
+        continue;
+      }
+      if (!(await fs.exists(path.join(dshHome, vaultRel)))) {
+        await fs.remove(path.join(vaultRoot, vaultRel));
+        cleaned.push(vaultRel);
+      }
+    }
+  } catch {
+    // 清理是尽力而为：listRecursive / remove 失败不影响镜像结果
+  }
+
+  return { mirrored, cleaned, skipped };
+}
+
+/**
+ * 从 vault 回填敏感文件到 $DSH_HOME（跨机恢复 / 本机误删后的恢复）。
+ * 不覆盖已存在的目标文件（安全：避免覆盖目标机更新后的凭据）；
+ * vault 无对应文件（跨机恢复、从未镜像过）记入 missing，由调用方提示用户重填。
+ */
+export async function restoreVaultFiles(
+  fs: FileSystemFacade,
+  dataDir: string,
+  dshHome: string,
+  rels: readonly string[],
+): Promise<VaultRestoreResult> {
+  const normRels = normalizeRels(rels);
+  const vaultRoot = vaultRootOf(dataDir);
+  const restored: string[] = [];
+  const missing: string[] = [];
+  const skipped: { rel: string; reason: string }[] = [];
+
+  for (const rel of normRels) {
+    const vaultPath = path.join(vaultRoot, rel);
+    const target = path.join(dshHome, rel);
+    try {
+      if (!(await fs.exists(vaultPath))) {
+        missing.push(rel);
+        continue;
+      }
+      if (await fs.exists(target)) {
+        skipped.push({ rel, reason: 'targetExists' });
+        continue;
+      }
+      await fs.copy(vaultPath, target);
+      restored.push(rel);
+    } catch (err) {
+      skipped.push({ rel, reason: err instanceof Error ? err.message : String(err) });
+    }
+  }
+
+  return { restored, missing, skipped };
+}
+
+/**
+ * 列出 vault 内容（镜像结构 = 相对 $DSH_HOME 的 rel 平铺在 vault 根下，
+ * 例如 vault/.credentials.yaml 即 $DSH_HOME/.credentials.yaml 的镜像）。
+ * vault 不存在 / 为空时返回空数组。
+ */
+export async function listVault(
+  fs: FileSystemFacade,
+  dataDir: string,
+  dshHome: string,
+): Promise<VaultEntry[]> {
+  const vaultRoot = vaultRootOf(dataDir);
+  const homeRels = await fs.listRecursive(vaultRoot); // home-relative；vault 不存在时宿主返回 []
+  const entries: VaultEntry[] = [];
+  for (const homeRel of homeRels) {
+    const rel = normalizePath(path.relative(vaultRoot, path.join(dshHome, homeRel)));
+    if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) continue; // 防御
+    entries.push({ rel, vaultPath: path.join(vaultRoot, rel) });
+  }
+  return entries.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0));
+}

package/src/security/zip-security.ts

@@ -0,0 +1,180 @@
+/**
+ * ZIP 解压安全（规范 §19 / 设计 §9 / core utils/zip.ts 的强化层）。
+ *
+ * 分工（避免与 core 重复）：
+ * - core `utils/zip.ts` 已实现：条目名 isPathSafe、条目数/压缩体积/解压体积/单条/压缩比限额、
+ *   CRC32 与尺寸校验、ZipArchive.readEntry 预算、safeExtract 基础解压。
+ * - 本模块在其上强化 core 未覆盖的攻击面：
+ *   1. **symlink 条目拒绝**：解析中央目录 external attrs 的 Unix mode（S_IFLNK 0xA000）→ 拒绝；
+ *   2. **重复条目名拒绝**：同名条目（含目录/文件互撞）→ 拒绝（防读取歧义攻击）；
+ *   3. **安全解压强化**：解压后逐条 lstat 复查「必须是普通文件」，任何异常 → 中止并**完整清理**目标目录；
+ *   4. **可执行文件告警**：扩展名黑名单 → warnings（本插件从不执行 ZIP 内文件）。
+ *
+ * 与 core 注入点对齐：`parseZipHardened` / `createHardenedZipParser` 满足
+ * `ImporterOptions.parseZipOverride` 签名 `(buf, limits?) => ZipArchive`。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isPathSafe, isSameOrChild } from '../utils/paths.ts';
+import {
+  DEFAULT_ZIP_SAFETY_LIMITS,
+  ZipArchive,
+  ZipSafetyError,
+  type ZipEntryMeta,
+  type ZipSafetyLimits,
+} from '../utils/zip.ts';
+
+export { isPathSafe } from '../utils/paths.ts';
+
+/* ---------------- 常量 ---------------- */
+
+const EOCD_SIG = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
+const CENTRAL_SIG = 0x02014b50;
+/** Unix 文件类型掩码（external attrs 高 16 位） */
+const S_IFMT = 0xf000;
+/** 符号链接 */
+const S_IFLNK = 0xa000;
+
+/** 可执行文件扩展名黑名单（§19.6：只警告，本插件不执行任何脚本） */
+export const EXECUTABLE_EXTENSIONS = new Set([
+  '.exe', '.bat', '.cmd', '.sh', '.ps1', '.dll', '.so', '.dylib', '.bin', '.jar',
+]);
+
+/** 条目名是否疑似可执行文件（按扩展名） */
+export function isExecutableName(name: string): boolean {
+  const ext = name.slice(name.lastIndexOf('.')).toLowerCase();
+  return EXECUTABLE_EXTENSIONS.has(ext);
+}
+
+/* ---------------- 强化解析（parseZipOverride 注入点） ---------------- */
+
+/**
+ * 强化版 ZIP 解析：在 core 全部安全校验（条目名/条目数/压缩体积）之上，
+ * 增加 symlink 拒绝与重复条目名拒绝。返回 core `ZipArchive`（解压校验完全复用）。
+ */
+export function parseZipHardened(buf: Uint8Array, limits: ZipSafetyLimits = {}): ZipArchive {
+  const merged: Required<ZipSafetyLimits> = { ...DEFAULT_ZIP_SAFETY_LIMITS, ...limits };
+  const b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
+  if (b.length < 22) throw new ZipSafetyError('不是合法的 ZIP 文件（体积过小）');
+
+  const eocdIdx = b.lastIndexOf(EOCD_SIG);
+  if (eocdIdx < 0 || eocdIdx + 22 > b.length) {
+    throw new ZipSafetyError('不是合法的 ZIP 文件（缺少中央目录结束记录）');
+  }
+  const totalEntries = b.readUInt16LE(eocdIdx + 10);
+  const cdSize = b.readUInt32LE(eocdIdx + 12);
+  const cdOffset = b.readUInt32LE(eocdIdx + 16);
+  if (cdOffset + cdSize > b.length) throw new ZipSafetyError('中央目录越界（ZIP 损坏）');
+  if (totalEntries > merged.maxEntries) {
+    throw new ZipSafetyError(`ZIP 条目数 ${totalEntries} 超过上限 ${merged.maxEntries}`);
+  }
+
+  const metas: ZipEntryMeta[] = [];
+  const seenNames = new Set<string>();
+  let pos = cdOffset;
+  let compressedTotal = 0;
+  for (let i = 0; i < totalEntries; i++) {
+    if (pos + 46 > cdOffset + cdSize) throw new ZipSafetyError('中央目录条目越界（ZIP 损坏）');
+    if (b.readUInt32LE(pos) !== CENTRAL_SIG) throw new ZipSafetyError('中央目录签名损坏');
+
+    const method = b.readUInt16LE(pos + 10);
+    const crc = b.readUInt32LE(pos + 16);
+    const compSize = b.readUInt32LE(pos + 20);
+    const uncompSize = b.readUInt32LE(pos + 24);
+    const nameLen = b.readUInt16LE(pos + 28);
+    const extraLen = b.readUInt16LE(pos + 30);
+    const commentLen = b.readUInt16LE(pos + 32);
+    const externalAttrs = b.readUInt32LE(pos + 38);
+    const localOffset = b.readUInt32LE(pos + 42);
+    const name = b.subarray(pos + 46, pos + 46 + nameLen).toString('utf8');
+
+    // —— 强化检查 ——
+    if (!isPathSafe(name)) throw new ZipSafetyError(`ZIP 条目名不安全: ${name}`);
+    if (seenNames.has(name)) throw new ZipSafetyError(`ZIP 条目名重复: ${name}`);
+    seenNames.add(name);
+    const mode = (externalAttrs >>> 16) & S_IFMT;
+    if (mode === S_IFLNK) {
+      throw new ZipSafetyError(`ZIP 含符号链接条目，已拒绝: ${name}`);
+    }
+    if (localOffset + 30 > b.length) {
+      throw new ZipSafetyError(`条目 "${name}" 本地文件头越界`);
+    }
+
+    compressedTotal += compSize;
+    if (compressedTotal > merged.maxCompressedBytes) {
+      throw new ZipSafetyError('ZIP 压缩数据总量超过上限');
+    }
+    metas.push({
+      name,
+      method,
+      compressedSize: compSize,
+      uncompressedSize: uncompSize,
+      crc32: crc,
+      isDirectory: name.endsWith('/'),
+      localOffset,
+    });
+    pos += 46 + nameLen + extraLen + commentLen;
+  }
+  return new ZipArchive(b, metas, merged);
+}
+
+/** 工厂：带默认限额的强化解析器（对齐 ImporterOptions.parseZipOverride 签名） */
+export function createHardenedZipParser(defaultLimits?: ZipSafetyLimits) {
+  return (buf: Uint8Array, limits?: ZipSafetyLimits): ZipArchive =>
+    parseZipHardened(buf, { ...defaultLimits, ...limits });
+}
+
+/* ---------------- 强化安全解压（m5 导入文件类分区用） ---------------- */
+
+export interface SafeExtractResult {
+  /** 已解压条目的 ZIP 相对路径（正斜杠） */
+  files: string[];
+  /** 非阻塞告警（可执行文件条目等） */
+  warnings: string[];
+}
+
+/**
+ * 安全解压到受控目录（对齐 core safeExtract 语义 + 强化）：
+ *  - 条目名/限额/symlink/重复名检查（parseZipHardened）；
+ *  - 逐条 CRC32/尺寸/预算校验（ZipArchive.readEntry）；
+ *  - 解压后 lstat 复查「全部产物必须是普通文件」（防符号链接/非常规写入）；
+ *  - 任何异常 → 中止并**完整清理** destDir 后抛出（不残留部分落盘）。
+ */
+export async function safeExtractHardened(
+  zipPath: string,
+  destDir: string,
+  limits: ZipSafetyLimits = {},
+): Promise<SafeExtractResult> {
+  const data = await fs.readFile(zipPath);
+  const archive = parseZipHardened(data, limits);
+  const extracted: string[] = [];
+  const warnings: string[] = [];
+
+  try {
+    for (const meta of archive.entries()) {
+      if (meta.isDirectory) continue;
+      const target = path.join(destDir, ...meta.name.split('/'));
+      if (!isSameOrChild(target, destDir)) {
+        throw new ZipSafetyError(`解压目标越界: ${meta.name}`);
+      }
+      await fs.mkdir(path.dirname(target), { recursive: true });
+      await fs.writeFile(target, archive.readEntry(meta.name));
+      extracted.push(meta.name);
+      if (isExecutableName(meta.name)) {
+        warnings.push(`条目 "${meta.name}" 是潜在可执行文件，本插件不会执行它`);
+      }
+    }
+    // 解压后复查：全部产物必须是普通文件（防 symlink 逃逸 / 非常规写入）
+    for (const rel of extracted) {
+      const p = path.join(destDir, ...rel.split('/'));
+      const st = await fs.lstat(p);
+      if (!st.isFile()) {
+        throw new ZipSafetyError(`解压产物不是普通文件: ${rel}`);
+      }
+    }
+    return { files: extracted, warnings };
+  } catch (err) {
+    await fs.rm(destDir, { recursive: true, force: true });
+    throw err;
+  }
+}