@logictan/dsh-config-manager 0.1.60

package/src/utils/hashing.ts

@@ -0,0 +1,53 @@
+/**
+ * SHA-256 完整性工具（integrity/checksums.json 的生成与校验）。
+ * m4 的 security/integrity.ts 可在此之上强化（本模块已实现规范 §18 全部语义）。
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+
+export function sha256Hex(data: Uint8Array | string): string {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+export async function hashFile(filePath: string): Promise<string> {
+  const data = await fs.readFile(filePath);
+  return sha256Hex(data);
+}
+
+/** 生成一组 ZIP 相对路径 → SHA-256 的校验表（路径必须为 ZIP 内正斜杠相对路径） */
+export function buildChecksums(entries: { name: string; data: Uint8Array }[]): Record<string, string> {
+  const checksums: Record<string, string> = {};
+  for (const e of entries) {
+    checksums[e.name] = sha256Hex(e.data);
+  }
+  return checksums;
+}
+
+export interface ChecksumVerifyResult {
+  ok: boolean;
+  mismatches: string[];
+  missing: string[];
+}
+
+/**
+ * 校验：checksums 表内每个相对路径必须在 entries 中存在且 SHA-256 一致。
+ * entries 中多余的文件（如 manifest.json / checksums.json 自身）不参与校验。
+ */
+export function verifyChecksums(
+  entries: ReadonlyMap<string, Uint8Array>,
+  checksums: Record<string, string>,
+): ChecksumVerifyResult {
+  const mismatches: string[] = [];
+  const missing: string[] = [];
+  for (const [relPath, expected] of Object.entries(checksums)) {
+    const data = entries.get(relPath);
+    if (data === undefined) {
+      missing.push(relPath);
+      continue;
+    }
+    if (sha256Hex(data) !== expected) {
+      mismatches.push(relPath);
+    }
+  }
+  return { ok: mismatches.length === 0 && missing.length === 0, mismatches, missing };
+}

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,176 @@
+/**
+ * 路径处理唯一出口（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));
+}
+
+/**
+ * 内部 control-plane namespace（F23 修复）：不可信 import（pluginFiles/self/file adapters）
+ * 不得把普通 config/file item 映射到这些 recovery storage 目录。
+ * 相对 homeDir 的路径（正斜杠归一）命中任一前缀 → 拒绝。
+ */
+const RESERVED_INTERNAL_PREFIXES: readonly string[] = [
+  'dsh-config-manager/snapshots/',
+  'dsh-config-manager/transactions/',
+  'dsh-config-manager/locks/',
+  'dsh-config-manager/safe-mode',
+  'dsh-config-manager/recovery-history/',
+  'dsh-config-manager/environment-fingerprint.token',
+  // Phase 6：迁移历史审计目录（统一历史引擎；防 F23 投毒链——不可信导入不得映射到该目录）。
+  'dsh-config-manager/migration-history/',
+  // 注意：不得整段保留 dsh-config-manager/sync/ —— self 分区合法持有 sync/*.json 白名单配置
+  //（sync-config / sync-selection / ui-prefs / backup-schedule），会误伤。
+  'dsh-config-manager/sync/snapshots/',
+  'dsh-config-manager/sync/work/',
+];
+
+/**
+ * 归一化并折叠 `.` / `..` 路径段（Reviewer B P0 修复）。
+ * 宿主 fs 经 `resolve(join(homeDir, rel))` 会折叠 `..`，因此「看似不在保留命名空间、实际经 `..` 落到保留区」
+ * 的路径（如 `dsh-config-manager/../dsh-config-manager/snapshots/...`）必须在此折叠后再判，否则 F23 被绕过。
+ * 纯字符串、跨平台（只用 `/`）语义与 node:path normalize 一致；`..` 超根时按根截断（不越到 home 外）。
+ */
+export function normalizePathCollapsed(p: string): string {
+  const norm = normalizePath(p);
+  if (norm === '') return '';
+  if (norm === '.') return '';
+  const out: string[] = [];
+  for (const seg of norm.split('/')) {
+    if (seg === '' || seg === '.') continue;
+    if (seg === '..') {
+      if (out.length > 0) out.pop();
+      continue; // 超根 `..` 直接丢弃（home 相对路径不可能越出 homeDir）
+    }
+    out.push(seg);
+  }
+  return out.join('/');
+}
+
+/** 判断相对 homeDir 的路径是否落在内部 control-plane namespace（F23 投毒防护）。
+ *  大小写不敏感（Windows 文件系统大小写不敏感，防 `DSh-Config-Manager/...` 绕过）；
+ *  先折叠 `..`/`.` 段（宿主 fs 会折叠，此处必须同样折叠以免被路径穿越绕过）。 */
+export function isReservedInternalRel(relPath: string): boolean {
+  const norm = normalizePathCollapsed(relPath).toLowerCase();
+  if (norm === '') return false;
+  for (const prefix of RESERVED_INTERNAL_PREFIXES) {
+    if (norm === prefix || norm.startsWith(prefix)) return true;
+  }
+  return false;
+}
+
+/**
+ * 前缀批量映射（规范 §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;
+}