dsh-config-manager 0.1.0

package/src/utils/json.ts

@@ -0,0 +1,77 @@
+/**
+ * JSON 深度保护：解析/序列化/克隆带嵌套深度上限（防 JSON 深度攻击，规范 §19.5）。
+ * 解析分两段：JSON.parse 可能因引擎栈限制抛 RangeError（捕获并归一），
+ * 再对结果做显式栈 walk 检查深度（避免 walk 自身递归爆栈）。
+ */
+
+export const DEFAULT_MAX_JSON_DEPTH = 64;
+export const DEFAULT_MAX_JSON_BYTES = 64 * 1024 * 1024;
+
+export class JsonDepthError extends Error {
+  constructor(message = `JSON 嵌套深度超过上限 ${DEFAULT_MAX_JSON_DEPTH}`) {
+    super(message);
+    this.name = 'JsonDepthError';
+  }
+}
+
+/** 测量对象/数组的嵌套深度（迭代式显式栈，不会递归爆栈；二进制视为叶子） */
+export function measureDepth(value: unknown): number {
+  let max = 0;
+  // 栈元素：[value, depth]
+  const stack: [unknown, number][] = [[value, 1]];
+  while (stack.length > 0) {
+    const [current, depth] = stack.pop()!;
+    if (depth > max) max = depth;
+    if (current !== null && typeof current === 'object' && !(current instanceof Uint8Array)) {
+      const next = depth + 1;
+      if (Array.isArray(current)) {
+        for (const item of current) stack.push([item, next]);
+      } else {
+        for (const key of Object.keys(current as Record<string, unknown>)) {
+          stack.push([(current as Record<string, unknown>)[key], next]);
+        }
+      }
+    }
+  }
+  return max;
+}
+
+/** 深度保护解析：超限抛 JsonDepthError，非法 JSON 抛 SyntaxError */
+export function parseJsonSafe(
+  text: string,
+  opts: { maxDepth?: number; maxBytes?: number } = {},
+): unknown {
+  const maxDepth = opts.maxDepth ?? DEFAULT_MAX_JSON_DEPTH;
+  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_JSON_BYTES;
+  if (text.length > maxBytes) {
+    throw new JsonDepthError(`JSON 体积超过上限 ${maxBytes} 字节`);
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    // 引擎栈限制导致的深层嵌套也会以 RangeError 出现 → 归一为 JsonDepthError
+    if (err instanceof RangeError) throw new JsonDepthError(`JSON 解析失败（可能是嵌套过深）: ${String(err.message)}`);
+    throw err;
+  }
+  const depth = measureDepth(parsed);
+  if (depth > maxDepth) {
+    throw new JsonDepthError(`JSON 嵌套深度 ${depth} 超过上限 ${maxDepth}`);
+  }
+  return parsed;
+}
+
+/** 深度保护序列化：先测深度再 stringify（默认不缩进） */
+export function stringifyJsonSafe(value: unknown, opts: { maxDepth?: number; space?: number } = {}): string {
+  const maxDepth = opts.maxDepth ?? DEFAULT_MAX_JSON_DEPTH;
+  const depth = measureDepth(value);
+  if (depth > maxDepth) throw new JsonDepthError(`JSON 嵌套深度 ${depth} 超过上限 ${maxDepth}`);
+  return JSON.stringify(value, null, opts.space);
+}
+
+/** 深度保护深拷贝（迭代式，安全） */
+export function deepClone<T>(value: T, maxDepth: number = DEFAULT_MAX_JSON_DEPTH): T {
+  const depth = measureDepth(value);
+  if (depth > maxDepth) throw new JsonDepthError();
+  return JSON.parse(JSON.stringify(value)) as T;
+}

package/src/utils/logger.ts

@@ -0,0 +1,114 @@
+/**
+ * 结构化日志（规范 §24）：LEVEL / 消息 / 可选元数据，带 redact 钩子。
+ * Secret 值永不入日志：sink 前对 msg 做文本级掩码、对 meta 做字段名级掩码。
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/** 敏感字段名黑名单（大小写不敏感；命中即掩码值，规范 §6 清单） */
+export const SENSITIVE_FIELD_BLACKLIST = [
+  'password', 'passwd', 'token', 'accesstoken', 'refreshtoken', 'apikey',
+  'secret', 'credential', 'authorization', 'cookie', 'privatekey', 'clientsecret',
+  'sessionkey', 'authtoken', 'bearer',
+];
+
+const REDACTED = '***REDACTED***';
+
+/** 字段名是否命中敏感黑名单（大小写不敏感，子串匹配） */
+export function isSensitiveField(field: string): boolean {
+  const lower = field.toLowerCase().replace(/[^a-z0-9]/g, '');
+  return SENSITIVE_FIELD_BLACKLIST.some((f) => lower.includes(f));
+}
+
+/** 对象级掩码：字段名命中黑名单 → 值替换（返回新对象，不改原对象） */
+export function redactValue(value: unknown, blacklist: string[] = SENSITIVE_FIELD_BLACKLIST): unknown {
+  if (value === null || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map((v) => redactValue(v, blacklist));
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    const lower = k.toLowerCase();
+    const hit = blacklist.some((f) => lower.includes(f));
+    out[k] = hit ? REDACTED : redactValue(v, blacklist);
+  }
+  return out;
+}
+
+/** 文本级掩码：JSON 片段 `"field": "value"`、`field=value`、`field: value` 形态 */
+export function redact(text: string, blacklist: string[] = SENSITIVE_FIELD_BLACKLIST): string {
+  let out = text;
+  for (const field of blacklist) {
+    // "field": "anything"
+    out = out.replace(new RegExp(`("${field}"\\s*:\\s*")[^"]*(")`, 'gi'), `$1${REDACTED}$2`);
+    // field=value / field: value（不含 JSON 引号形态）
+    out = out.replace(new RegExp(`(\\b${field}\\s*=\\s*)[^\\s,;]+`, 'gi'), `$1${REDACTED}`);
+    out = out.replace(new RegExp(`(\\b${field}\\s*:\\s*)[^\\s,;}]+`, 'gi'), `$1${REDACTED}`);
+  }
+  return out;
+}
+
+export interface LogMeta { [key: string]: unknown }
+
+export interface LogSink {
+  (level: LogLevel, message: string, meta?: LogMeta): void;
+}
+
+export interface Logger {
+  level: LogLevel;
+  debug(message: string, meta?: LogMeta): void;
+  info(message: string, meta?: LogMeta): void;
+  warn(message: string, meta?: LogMeta): void;
+  error(message: string, meta?: LogMeta): void;
+}
+
+export interface LoggerOptions {
+  level?: LogLevel;
+  /** 输出目标；缺省写 console（单行 JSON）。测试可注入内存 sink。 */
+  sink?: LogSink;
+  /** 额外敏感字段黑名单 */
+  extraBlacklist?: string[];
+  /** 是否带时间戳前缀 */
+  timestamp?: boolean;
+}
+
+const LEVEL_ORDER: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3 };
+
+/** 创建结构化日志器（默认 console JSON 行，全部输出过 redact） */
+export function createLogger(opts: LoggerOptions = {}): Logger {
+  const level = opts.level ?? 'info';
+  const blacklist = [...SENSITIVE_FIELD_BLACKLIST, ...(opts.extraBlacklist ?? [])];
+  const sink: LogSink = opts.sink ?? ((lvl, message, meta) => {
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      level: lvl,
+      msg: redact(message, blacklist),
+      ...(meta ? { meta: redactValue(meta, blacklist) } : {}),
+    });
+    // eslint-disable-next-line no-console
+    (lvl === 'error' ? console.error : lvl === 'warn' ? console.warn : console.log)(line);
+  });
+  const emit = (lvl: LogLevel, message: string, meta?: LogMeta): void => {
+    if (LEVEL_ORDER[lvl] < LEVEL_ORDER[level]) return;
+    try {
+      sink(lvl, message, meta);
+    } catch {
+      // 日志器自身永不抛错
+    }
+  };
+  return {
+    level,
+    debug: (m, meta) => emit('debug', m, meta),
+    info: (m, meta) => emit('info', m, meta),
+    warn: (m, meta) => emit('warn', m, meta),
+    error: (m, meta) => emit('error', m, meta),
+  };
+}
+
+/** 静默日志器（测试用） */
+export function nullLogger(): Logger {
+  return {
+    level: 'error',
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+  };
+}

package/src/utils/paths.ts

@@ -0,0 +1,122 @@
+/**
+ * 路径处理唯一出口（node:path 不直接散落业务代码）：
+ * 规范化、平台判定、绝对路径识别、前缀批量映射、ZIP 条目名安全校验。
+ */
+import path from 'node:path';
+import type { PathMapping } from '../core/types.ts';
+
+/** 归一化内部表示：统一 `/` 分隔、去尾部斜杠（空串保持） */
+export function normalizePath(p: string): string {
+  if (p === '') return '';
+  const norm = p.replaceAll('\\', '/');
+  return norm.length > 1 ? norm.replace(/\/+$/, '') : norm;
+}
+
+/** 转当前平台原生路径 */
+export function toNativePath(p: string): string {
+  const norm = normalizePath(p);
+  if (process.platform === 'win32') return norm.replaceAll('/', '\\');
+  return norm;
+}
+
+/** 跨平台绝对路径识别（POSIX `/x` 与 Windows `C:\x`、UNC `\\server\share`） */
+export function isAbsolutePath(p: string): boolean {
+  if (p === '') return false;
+  if (p.startsWith('/')) return true;
+  if (/^[a-zA-Z]:[\\/]/.test(p)) return true; // 盘符
+  if (p.startsWith('\\\\') || p.startsWith('//')) return true; // UNC
+  return false;
+}
+
+/** 路径是否为 home 目录（~ 或用户主目录开头） */
+export function isHomePath(p: string, homeDir: string): boolean {
+  const norm = normalizePath(p);
+  const home = normalizePath(homeDir);
+  return norm === '~' || norm === home || norm.startsWith(home + '/') || norm.startsWith('~/');
+}
+
+/** 目标平台与当前平台是否一致 */
+export function isSamePlatform(a: string, b: string): boolean {
+  return a === b;
+}
+
+/** ZIP 条目名安全检查（Zip Slip / 绝对路径 / 盘符 / NUL，规范 §19.1-2）。
+ * 规则与 node:path 解耦：纯分段校验，跨平台无歧义。 */
+export function isPathSafe(entryName: string): boolean {
+  if (entryName === '') return false;
+  if (entryName.includes('\0')) return false;
+  if (entryName.startsWith('/') || entryName.startsWith('\\')) return false; // 绝对路径
+  if (/^[a-zA-Z]:[\\/]/.test(entryName)) return false; // 盘符
+  if (/^\\\\/.test(entryName)) return false; // UNC
+  const segments = entryName.split(/[\\/]+/);
+  if (segments.some((s) => s === '..')) return false; // 目录穿越
+  return true;
+}
+
+/** 候选目录是否位于父目录之内（含等于父目录） */
+export function isSameOrChild(p: string, parent: string): boolean {
+  const rel = path.relative(parent, p);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/**
+ * 前缀批量映射（规范 §12）：把对象内所有字符串值中匹配 oldPrefix 的路径
+ * 替换为 newPrefix（路径感知：必须落在段边界）。返回新对象（不改原对象）。
+ */
+export function applyPrefixMappings(value: unknown, mappings: PathMapping[]): unknown {
+  if (mappings.length === 0) return value;
+  return mapStrings(value, (s) => {
+    let out = s;
+    for (const m of mappings) {
+      const oldNorm = normalizePath(m.oldPrefix);
+      if (oldNorm === '') continue;
+      const candidate = normalizePath(out);
+      if (candidate === oldNorm) {
+        out = normalizePath(m.newPrefix);
+        continue;
+      }
+      if (candidate.startsWith(oldNorm + '/')) {
+        const rest = candidate.slice(oldNorm.length); // 含前导 /
+        out = normalizePath(normalizePath(m.newPrefix) + rest);
+      }
+    }
+    return out;
+  });
+}
+
+/** 对对象内所有字符串叶节点做变换（迭代式，保留非字符串原样；二进制 Uint8Array 视为叶子） */
+export function mapStrings(value: unknown, fn: (s: string) => string): unknown {
+  if (typeof value === 'string') return fn(value);
+  if (value === null || typeof value !== 'object') return value;
+  if (value instanceof Uint8Array) return value; // 二进制不按字段展开
+  if (Array.isArray(value)) return value.map((v) => mapStrings(v, fn));
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    out[k] = mapStrings(v, fn);
+  }
+  return out;
+}
+
+/**
+ * 收集对象中所有绝对路径叶值（供 analyzer 做跨设备路径检测）。
+ * 返回 (value, jsonPath) 对；jsonPath 形如 "workspaces[0].path"。
+ */
+export function collectAbsolutePaths(value: unknown, prefix = ''): { value: string; path: string }[] {
+  const hits: { value: string; path: string }[] = [];
+  const visit = (v: unknown, p: string): void => {
+    if (typeof v === 'string') {
+      if (isAbsolutePath(v)) hits.push({ value: v, path: p });
+      return;
+    }
+    if (v === null || typeof v !== 'object') return;
+    if (Array.isArray(v)) {
+      v.forEach((item, i) => visit(item, `${p}[${i}]`));
+      return;
+    }
+    for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+      visit(val, p === '' ? k : `${p}.${k}`);
+    }
+  };
+  visit(value, prefix);
+  return hits;
+}

package/src/utils/zip.ts

@@ -0,0 +1,332 @@
+/**
+ * ZIP 读写封装：node:zlib（deflate raw）+ 自实现 CRC32，零依赖。
+ * 同时是 ZIP 安全的第一道防线（规范 §19，m4 的 zip-security 可在此基础上强化）：
+ *   - 条目名 isPathSafe（拒绝 ../、绝对路径、盘符、UNC、NUL）
+ *   - 条目数 / 压缩体积 / 解压体积 / 单条 / 压缩比（zip bomb）上限
+ *   - 解压时逐条 CRC32 与尺寸校验，损坏即整体拒绝
+ * 解压只允许写入受控目标目录（safeExtract），绝不落任意路径。
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { parseJsonSafe } from './json.ts';
+import { isPathSafe, isSameOrChild } from './paths.ts';
+
+export interface ZipEntryMeta {
+  name: string;
+  method: number; // 0=store, 8=deflate
+  compressedSize: number;
+  uncompressedSize: number;
+  crc32: number;
+  isDirectory: boolean;
+  /** 本地文件头在 ZIP 字节流中的偏移 */
+  localOffset: number;
+}
+
+export interface ZipSafetyLimits {
+  maxEntries?: number;
+  maxTotalBytes?: number;      // 解压后累计字节上限
+  maxCompressedBytes?: number; // ZIP 内压缩数据累计上限
+  maxSingleBytes?: number;     // 单条目解压后上限
+  maxRatio?: number;           // 单条目解压/压缩比上限（zip bomb 检测）
+}
+
+export const DEFAULT_ZIP_SAFETY_LIMITS: Required<ZipSafetyLimits> = {
+  maxEntries: 10_000,
+  maxTotalBytes: 500 * 1024 * 1024,
+  maxCompressedBytes: 200 * 1024 * 1024,
+  maxSingleBytes: 100 * 1024 * 1024,
+  maxRatio: 200,
+};
+
+export class ZipSafetyError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ZipSafetyError';
+  }
+}
+
+/* ---------------- CRC32（表驱动） ---------------- */
+
+let crcTable: Uint32Array | null = null;
+function getCrcTable(): Uint32Array {
+  if (crcTable) return crcTable;
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) {
+      c = (c & 1) !== 0 ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
+    }
+    table[n] = c >>> 0;
+  }
+  crcTable = table;
+  return table;
+}
+
+export function crc32(data: Uint8Array): number {
+  const table = getCrcTable();
+  let crc = 0xffffffff;
+  for (let i = 0; i < data.length; i++) {
+    crc = table[(crc ^ data[i]!) & 0xff]! ^ (crc >>> 8);
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/* ---------------- 写入 ---------------- */
+
+function dosDateTime(): { time: number; date: number } {
+  const now = new Date();
+  const time = ((now.getHours() & 0x1f) << 11) | ((now.getMinutes() & 0x3f) << 5) | ((now.getSeconds() >> 1) & 0x1f);
+  const date = (((now.getFullYear() - 1980) & 0x7f) << 9) | (((now.getMonth() + 1) & 0x0f) << 5) | (now.getDate() & 0x1f);
+  return { time, date };
+}
+
+export interface ZipWriteEntry { name: string; data: Uint8Array; }
+
+/** 组装 ZIP 字节（全部条目 method=8 deflate，UTF-8 文件名，含中央目录与 EOCD） */
+export function zipToBuffer(entries: ZipWriteEntry[]): Uint8Array {
+  const chunks: Buffer[] = [];
+  const central: Buffer[] = [];
+  let offset = 0;
+  const { time, date } = dosDateTime();
+
+  for (const entry of entries) {
+    if (!isPathSafe(entry.name)) {
+      throw new ZipSafetyError(`拒绝写入不安全的条目名: ${entry.name}`);
+    }
+    const nameBuf = Buffer.from(entry.name, 'utf8');
+    const data = Buffer.isBuffer(entry.data) ? entry.data : Buffer.from(entry.data);
+    const compressed = zlib.deflateRawSync(data);
+    const crc = crc32(data);
+
+    const local = Buffer.alloc(30);
+    local.writeUInt32LE(0x04034b50, 0);
+    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(0x0800, 6); // UTF-8 文件名
+    local.writeUInt16LE(8, 8);     // deflate
+    local.writeUInt16LE(time, 10);
+    local.writeUInt16LE(date, 12);
+    local.writeUInt32LE(crc, 14);
+    local.writeUInt32LE(compressed.length, 18);
+    local.writeUInt32LE(data.length, 22);
+    local.writeUInt16LE(nameBuf.length, 26);
+    local.writeUInt16LE(0, 28);
+    chunks.push(local, nameBuf, compressed);
+
+    const cen = Buffer.alloc(46);
+    cen.writeUInt32LE(0x02014b50, 0);
+    cen.writeUInt16LE(20, 4);
+    cen.writeUInt16LE(20, 6);
+    cen.writeUInt16LE(0x0800, 8);
+    cen.writeUInt16LE(8, 10);
+    cen.writeUInt16LE(time, 12);
+    cen.writeUInt16LE(date, 14);
+    cen.writeUInt32LE(crc, 16);
+    cen.writeUInt32LE(compressed.length, 20);
+    cen.writeUInt32LE(data.length, 24);
+    cen.writeUInt16LE(nameBuf.length, 28);
+    cen.writeUInt16LE(0, 30);
+    cen.writeUInt16LE(0, 32);
+    cen.writeUInt16LE(0, 34);
+    cen.writeUInt16LE(0, 36);
+    cen.writeUInt32LE(0, 38);
+    cen.writeUInt32LE(offset, 42);
+    central.push(cen, nameBuf);
+
+    offset += local.length + nameBuf.length + compressed.length;
+  }
+
+  const cd = Buffer.concat(central);
+  const eocd = Buffer.alloc(22);
+  eocd.writeUInt32LE(0x06054b50, 0);
+  eocd.writeUInt16LE(0, 4);
+  eocd.writeUInt16LE(0, 6);
+  eocd.writeUInt16LE(entries.length, 8);
+  eocd.writeUInt16LE(entries.length, 10);
+  eocd.writeUInt32LE(cd.length, 12);
+  eocd.writeUInt32LE(offset, 16);
+  eocd.writeUInt16LE(0, 20);
+
+  return Buffer.concat([...chunks, cd, eocd]);
+}
+
+/** 写出 ZIP 文件 */
+export async function writeZip(zipPath: string, entries: ZipWriteEntry[]): Promise<void> {
+  const buf = zipToBuffer(entries);
+  await fs.mkdir(path.dirname(zipPath), { recursive: true });
+  await fs.writeFile(zipPath, buf);
+}
+
+/* ---------------- 读取 ---------------- */
+
+const EOCD_SIG = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
+const LOCAL_SIG = 0x04034b50;
+const CENTRAL_SIG = 0x02014b50;
+
+/** 内存 ZIP 归档：构造时校验全部条目名与上限；读取时逐条解压 + CRC/尺寸/比预算校验 */
+export class ZipArchive {
+  private readonly buf: Buffer;
+  private readonly metas: ZipEntryMeta[];
+  readonly limits: Required<ZipSafetyLimits>;
+  private totalUncompressed = 0;
+
+  constructor(buf: Uint8Array, metas: ZipEntryMeta[], limits: Required<ZipSafetyLimits>) {
+    this.buf = Buffer.isBuffer(buf) ? buf : Buffer.from(buf);
+    this.metas = metas;
+    this.limits = limits;
+  }
+
+  names(): string[] {
+    return this.metas.map((m) => m.name);
+  }
+
+  entries(): ZipEntryMeta[] {
+    return this.metas.map((m) => ({ ...m }));
+  }
+
+  has(name: string): boolean {
+    return this.metas.some((m) => m.name === name);
+  }
+
+  /** 读取并解压单条目（带 CRC32 / 尺寸 / 体积预算 / 压缩比校验） */
+  readEntry(name: string): Uint8Array {
+    const meta = this.metas.find((m) => m.name === name);
+    if (!meta) throw new ZipSafetyError(`ZIP 中不存在条目: ${name}`);
+    if (meta.isDirectory) return Buffer.alloc(0);
+
+    const lhOffset = meta.localOffset;
+    const lh = this.buf.subarray(lhOffset, lhOffset + 30);
+    if (lh.length < 30 || lh.readUInt32LE(0) !== LOCAL_SIG) {
+      throw new ZipSafetyError(`条目 "${name}" 的本地文件头损坏`);
+    }
+    const nameLen = lh.readUInt16LE(26);
+    const extraLen = lh.readUInt16LE(28);
+    const dataStart = lhOffset + 30 + nameLen + extraLen;
+    if (dataStart + meta.compressedSize > this.buf.length) {
+      throw new ZipSafetyError(`条目 "${name}" 数据越界`);
+    }
+    const raw = this.buf.subarray(dataStart, dataStart + meta.compressedSize);
+
+    let out: Buffer;
+    if (meta.method === 0) {
+      out = raw;
+    } else if (meta.method === 8) {
+      try {
+        out = zlib.inflateRawSync(raw, { maxOutputLength: this.limits.maxSingleBytes });
+      } catch (err) {
+        throw new ZipSafetyError(`条目 "${name}" 解压失败: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    } else {
+      throw new ZipSafetyError(`条目 "${name}" 使用未知压缩方法 ${meta.method}`);
+    }
+
+    if (out.length !== meta.uncompressedSize) {
+      throw new ZipSafetyError(`条目 "${name}" 解压尺寸不符（${out.length} ≠ ${meta.uncompressedSize}）`);
+    }
+    if (crc32(out) !== meta.crc32) {
+      throw new ZipSafetyError(`条目 "${name}" CRC32 校验失败（ZIP 已损坏）`);
+    }
+
+    this.totalUncompressed += out.length;
+    if (this.totalUncompressed > this.limits.maxTotalBytes) {
+      throw new ZipSafetyError('ZIP 解压总字节数超过上限');
+    }
+    if (meta.compressedSize > 0) {
+      const ratio = out.length / meta.compressedSize;
+      if (ratio > this.limits.maxRatio) {
+        throw new ZipSafetyError(`条目 "${name}" 压缩比 ${ratio.toFixed(1)} 超过上限（疑似 zip bomb）`);
+      }
+    }
+    return out;
+  }
+
+  readEntryText(name: string): string {
+    return Buffer.from(this.readEntry(name)).toString('utf8');
+  }
+
+  /** 读取并深度保护解析 JSON 条目 */
+  readEntryJson(name: string): unknown {
+    return parseJsonSafe(this.readEntryText(name));
+  }
+}
+
+/** 解析 ZIP（含安全校验：条目名 / 条目数 / 压缩体积） */
+export function parseZip(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[] = [];
+  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 localOffset = b.readUInt32LE(pos + 42);
+    const name = b.subarray(pos + 46, pos + 46 + nameLen).toString('utf8');
+
+    if (!isPathSafe(name)) throw new ZipSafetyError(`ZIP 条目名不安全: ${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);
+}
+
+/**
+ * 安全解压到受控目录（对齐设计 §13.4 safeExtract 签名）。
+ * 返回条目相对路径列表；任何越界/损坏即整体拒绝（不部分落盘）。
+ * m4 的 zip-security 可替换/强化本实现。
+ */
+export async function safeExtract(
+  zipPath: string,
+  destDir: string,
+  limits: ZipSafetyLimits = {},
+): Promise<string[]> {
+  const data = await fs.readFile(zipPath);
+  const archive = parseZip(data, limits);
+  const extracted: string[] = [];
+  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);
+  }
+  return extracted;
+}