dsh-config-manager 0.1.0

package/lib/utils/json.js

@@ -0,0 +1,76 @@
+/**
+ * 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) {
+    let max = 0;
+    // 栈元素：[value, depth]
+    const stack = [[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)) {
+                    stack.push([current[key], next]);
+                }
+            }
+        }
+    }
+    return max;
+}
+/** 深度保护解析：超限抛 JsonDepthError，非法 JSON 抛 SyntaxError */
+export function parseJsonSafe(text, opts = {}) {
+    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;
+    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, opts = {}) {
+    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(value, maxDepth = DEFAULT_MAX_JSON_DEPTH) {
+    const depth = measureDepth(value);
+    if (depth > maxDepth)
+        throw new JsonDepthError();
+    return JSON.parse(JSON.stringify(value));
+}
+//# sourceMappingURL=json.js.map

package/lib/utils/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/utils/json.ts"],"names":[],"mappings":"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"}

package/lib/utils/logger.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 结构化日志（规范 §24）：LEVEL / 消息 / 可选元数据，带 redact 钩子。
+ * Secret 值永不入日志：sink 前对 msg 做文本级掩码、对 meta 做字段名级掩码。
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/** 敏感字段名黑名单（大小写不敏感；命中即掩码值，规范 §6 清单） */
+export declare const SENSITIVE_FIELD_BLACKLIST: string[];
+/** 字段名是否命中敏感黑名单（大小写不敏感，子串匹配） */
+export declare function isSensitiveField(field: string): boolean;
+/** 对象级掩码：字段名命中黑名单 → 值替换（返回新对象，不改原对象） */
+export declare function redactValue(value: unknown, blacklist?: string[]): unknown;
+/** 文本级掩码：JSON 片段 `"field": "value"`、`field=value`、`field: value` 形态 */
+export declare function redact(text: string, blacklist?: string[]): string;
+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;
+}
+/** 创建结构化日志器（默认 console JSON 行，全部输出过 redact） */
+export declare function createLogger(opts?: LoggerOptions): Logger;
+/** 静默日志器（测试用） */
+export declare function nullLogger(): Logger;

package/lib/utils/logger.js

@@ -0,0 +1,82 @@
+/** 敏感字段名黑名单（大小写不敏感；命中即掩码值，规范 §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) {
+    const lower = field.toLowerCase().replace(/[^a-z0-9]/g, '');
+    return SENSITIVE_FIELD_BLACKLIST.some((f) => lower.includes(f));
+}
+/** 对象级掩码：字段名命中黑名单 → 值替换（返回新对象，不改原对象） */
+export function redactValue(value, blacklist = SENSITIVE_FIELD_BLACKLIST) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map((v) => redactValue(v, blacklist));
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        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, blacklist = SENSITIVE_FIELD_BLACKLIST) {
+    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;
+}
+const LEVEL_ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
+/** 创建结构化日志器（默认 console JSON 行，全部输出过 redact） */
+export function createLogger(opts = {}) {
+    const level = opts.level ?? 'info';
+    const blacklist = [...SENSITIVE_FIELD_BLACKLIST, ...(opts.extraBlacklist ?? [])];
+    const sink = 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, message, meta) => {
+        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() {
+    return {
+        level: 'error',
+        debug: () => { },
+        info: () => { },
+        warn: () => { },
+        error: () => { },
+    };
+}
+//# sourceMappingURL=logger.js.map

package/lib/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"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"}

package/lib/utils/paths.d.ts

@@ -0,0 +1,31 @@
+import type { PathMapping } from '../core/types.ts';
+/** 归一化内部表示：统一 `/` 分隔、去尾部斜杠（空串保持） */
+export declare function normalizePath(p: string): string;
+/** 转当前平台原生路径 */
+export declare function toNativePath(p: string): string;
+/** 跨平台绝对路径识别（POSIX `/x` 与 Windows `C:\x`、UNC `\\server\share`） */
+export declare function isAbsolutePath(p: string): boolean;
+/** 路径是否为 home 目录（~ 或用户主目录开头） */
+export declare function isHomePath(p: string, homeDir: string): boolean;
+/** 目标平台与当前平台是否一致 */
+export declare function isSamePlatform(a: string, b: string): boolean;
+/** ZIP 条目名安全检查（Zip Slip / 绝对路径 / 盘符 / NUL，规范 §19.1-2）。
+ * 规则与 node:path 解耦：纯分段校验，跨平台无歧义。 */
+export declare function isPathSafe(entryName: string): boolean;
+/** 候选目录是否位于父目录之内（含等于父目录） */
+export declare function isSameOrChild(p: string, parent: string): boolean;
+/**
+ * 前缀批量映射（规范 §12）：把对象内所有字符串值中匹配 oldPrefix 的路径
+ * 替换为 newPrefix（路径感知：必须落在段边界）。返回新对象（不改原对象）。
+ */
+export declare function applyPrefixMappings(value: unknown, mappings: PathMapping[]): unknown;
+/** 对对象内所有字符串叶节点做变换（迭代式，保留非字符串原样；二进制 Uint8Array 视为叶子） */
+export declare function mapStrings(value: unknown, fn: (s: string) => string): unknown;
+/**
+ * 收集对象中所有绝对路径叶值（供 analyzer 做跨设备路径检测）。
+ * 返回 (value, jsonPath) 对；jsonPath 形如 "workspaces[0].path"。
+ */
+export declare function collectAbsolutePaths(value: unknown, prefix?: string): {
+    value: string;
+    path: string;
+}[];

package/lib/utils/paths.js

@@ -0,0 +1,132 @@
+/**
+ * 路径处理唯一出口（node:path 不直接散落业务代码）：
+ * 规范化、平台判定、绝对路径识别、前缀批量映射、ZIP 条目名安全校验。
+ */
+import path from 'node:path';
+/** 归一化内部表示：统一 `/` 分隔、去尾部斜杠（空串保持） */
+export function normalizePath(p) {
+    if (p === '')
+        return '';
+    const norm = p.replaceAll('\\', '/');
+    return norm.length > 1 ? norm.replace(/\/+$/, '') : norm;
+}
+/** 转当前平台原生路径 */
+export function toNativePath(p) {
+    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) {
+    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, homeDir) {
+    const norm = normalizePath(p);
+    const home = normalizePath(homeDir);
+    return norm === '~' || norm === home || norm.startsWith(home + '/') || norm.startsWith('~/');
+}
+/** 目标平台与当前平台是否一致 */
+export function isSamePlatform(a, b) {
+    return a === b;
+}
+/** ZIP 条目名安全检查（Zip Slip / 绝对路径 / 盘符 / NUL，规范 §19.1-2）。
+ * 规则与 node:path 解耦：纯分段校验，跨平台无歧义。 */
+export function isPathSafe(entryName) {
+    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, parent) {
+    const rel = path.relative(parent, p);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+/**
+ * 前缀批量映射（规范 §12）：把对象内所有字符串值中匹配 oldPrefix 的路径
+ * 替换为 newPrefix（路径感知：必须落在段边界）。返回新对象（不改原对象）。
+ */
+export function applyPrefixMappings(value, mappings) {
+    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, fn) {
+    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 = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = mapStrings(v, fn);
+    }
+    return out;
+}
+/**
+ * 收集对象中所有绝对路径叶值（供 analyzer 做跨设备路径检测）。
+ * 返回 (value, jsonPath) 对；jsonPath 形如 "workspaces[0].path"。
+ */
+export function collectAbsolutePaths(value, prefix = '') {
+    const hits = [];
+    const visit = (v, p) => {
+        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)) {
+            visit(val, p === '' ? k : `${p}.${k}`);
+        }
+    };
+    visit(value, prefix);
+    return hits;
+}
+//# sourceMappingURL=paths.js.map

package/lib/utils/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/utils/paths.ts"],"names":[],"mappings":"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"}

package/lib/utils/zip.d.ts

@@ -0,0 +1,54 @@
+export interface ZipEntryMeta {
+    name: string;
+    method: number;
+    compressedSize: number;
+    uncompressedSize: number;
+    crc32: number;
+    isDirectory: boolean;
+    /** 本地文件头在 ZIP 字节流中的偏移 */
+    localOffset: number;
+}
+export interface ZipSafetyLimits {
+    maxEntries?: number;
+    maxTotalBytes?: number;
+    maxCompressedBytes?: number;
+    maxSingleBytes?: number;
+    maxRatio?: number;
+}
+export declare const DEFAULT_ZIP_SAFETY_LIMITS: Required<ZipSafetyLimits>;
+export declare class ZipSafetyError extends Error {
+    constructor(message: string);
+}
+export declare function crc32(data: Uint8Array): number;
+export interface ZipWriteEntry {
+    name: string;
+    data: Uint8Array;
+}
+/** 组装 ZIP 字节（全部条目 method=8 deflate，UTF-8 文件名，含中央目录与 EOCD） */
+export declare function zipToBuffer(entries: ZipWriteEntry[]): Uint8Array;
+/** 写出 ZIP 文件 */
+export declare function writeZip(zipPath: string, entries: ZipWriteEntry[]): Promise<void>;
+/** 内存 ZIP 归档：构造时校验全部条目名与上限；读取时逐条解压 + CRC/尺寸/比预算校验 */
+export declare class ZipArchive {
+    private readonly buf;
+    private readonly metas;
+    readonly limits: Required<ZipSafetyLimits>;
+    private totalUncompressed;
+    constructor(buf: Uint8Array, metas: ZipEntryMeta[], limits: Required<ZipSafetyLimits>);
+    names(): string[];
+    entries(): ZipEntryMeta[];
+    has(name: string): boolean;
+    /** 读取并解压单条目（带 CRC32 / 尺寸 / 体积预算 / 压缩比校验） */
+    readEntry(name: string): Uint8Array;
+    readEntryText(name: string): string;
+    /** 读取并深度保护解析 JSON 条目 */
+    readEntryJson(name: string): unknown;
+}
+/** 解析 ZIP（含安全校验：条目名 / 条目数 / 压缩体积） */
+export declare function parseZip(buf: Uint8Array, limits?: ZipSafetyLimits): ZipArchive;
+/**
+ * 安全解压到受控目录（对齐设计 §13.4 safeExtract 签名）。
+ * 返回条目相对路径列表；任何越界/损坏即整体拒绝（不部分落盘）。
+ * m4 的 zip-security 可替换/强化本实现。
+ */
+export declare function safeExtract(zipPath: string, destDir: string, limits?: ZipSafetyLimits): Promise<string[]>;