@logictan/dsh-config-manager 0.1.60

package/lib/security/secret-scanner.js

@@ -0,0 +1,404 @@
+/**
+ * 敏感字段扫描器（规范 §6 / 设计 §7.2 / core `SecretScanner` 契约的强化实现）。
+ *
+ * 定位：`ctx.settings.describe({redactSecrets:true})` 已剥离 DSH 已知秘密（设计 §7.2），
+ * 本扫描器是**第二道防线**，兜底插件自定义字段、MCP headers、patch config、文件类分区文本。
+ *
+ * 判定策略（两级，避免误伤/漏报）：
+ *  - 字段名：规范化（小写、去 `_-. ` 分隔符）后做「精确命中 / 敏感后缀 / 敏感前缀」三级匹配；
+ *    只剥离**字符串叶值**（对象/数组整体递归，不整块剥离——保证 `credentials: [...]` 状态数组存活）。
+ *  - 引用豁免：`apiKeyEnv` 等「只存引用名」字段、形如 `DEEPSEEK_API_KEY` 的全大写环境变量名
+ *    （`isEnvVarName`）以及 `${VAR}` / `{{VAR}}` / `%VAR%` / `$VAR` 模板引用（`isTemplateReference`）
+ *    一律保留——值是名字不是秘密。
+ *  - 值形状启发式（规范 §6「不能只根据固定字段判断」）：字段名未命中但值长得像 secret
+ *    （sk- / JWT / AKIA / GitHub PAT / PEM 私钥 / Bearer）也剥离；**示例/占位形态**（含
+ *    your/example/xxx/test/<...> 等占位词的 `sk-your-*`、`Bearer example-*`、JWT 教学串）放行。
+ *  - 两种判定档位（2026-08-21 优化）：
+ *    * 保守档（默认，导出/同步脱敏用）：字段名敏感**即**剥离（值形状优先、引用/env 名豁免）；
+ *    * 宽松档（`literalValueOnly`，市场发布扫描用）：字段名敏感**且**值像真实字面量凭据
+ *      （非占位符 / 非类型词 / 非代码表达式 / 非模板引用 / 非短标识符）才命中——消除
+ *      `"token": "your-token"`、`"token": "${OPENAI_API_KEY}"`、`"Authorization": "Bearer <token>"`
+ *      等「值不是秘密」的误报。
+ *  - 高熵 base64 默认关（误伤率高）。
+ *
+ * 实现不变量：返回 sanitized 为**全新对象**（不改原数据）；迭代式显式栈（防爆栈）+ 深度上限；
+ * 命中记录只含路径与字段名，**值永不外泄**。
+ */
+import { JsonDepthError } from '../utils/json.js';
+/** 剥离占位（与 core defaultSecretScanner 语义一致：空串 = 需补录提示） */
+export const REDACTED_PLACEHOLDER = '';
+/**
+ * 敏感字段名单（规范化名：小写、无分隔符）。
+ * 覆盖规范 §6 原始清单 + 设计 §7.2 + core logger 名单，并保持克制以防误伤
+ * （不收录 `key`/`session` 等过宽子串——`sessionIds`/`monkey` 不得中招）。
+ */
+export const DEFAULT_SECRET_FIELD_NAMES = [
+    // 规范 §6 原文
+    'password', 'passwd', 'token', 'accesstoken', 'refreshtoken',
+    'apikey', 'secret', 'credential', 'authorization', 'cookie',
+    'privatekey', 'clientsecret',
+    // 设计 §7.2 / core logger 扩充
+    'pwd', 'passphrase', 'authtoken', 'sessionkey', 'apisecret',
+    'authheader', 'bearer', 'webhooksecret',
+];
+/** 引用字段（值只是「名字」而非秘密）：规范化精确命中即豁免 */
+export const DEFAULT_REFERENCE_FIELDS = [
+    'apikeyenv', 'apikeyname', 'apikeyref',
+    'tokenenv', 'accesstokenenv', 'refreshtokenenv',
+    'clientsecretenv', 'passwordenv', 'secretref', 'credentialref',
+];
+/** 敏感后缀（规范化后以这些结尾 → 命中；`key` 故意不收，避免 monkey/whiskey 误伤） */
+const SENSITIVE_SUFFIXES = ['token', 'secret', 'password', 'passwd', 'credential'];
+/** 敏感前缀（规范化后以这些开头 → 命中；token/secret 等过宽词不收入） */
+const SENSITIVE_PREFIXES = [
+    'apikey', 'accesstoken', 'refreshtoken', 'authtoken',
+    'clientsecret', 'privatekey', 'authorization', 'authheader',
+    'webhooksecret', 'apisecret',
+];
+export const SECRET_VALUE_PATTERNS = [
+    { name: 'openai-style-key', re: /sk-[A-Za-z0-9_-]{8,}/ },
+    { name: 'jwt', re: /eyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/ },
+    { name: 'aws-access-key', re: /AKIA[0-9A-Z]{16}/ },
+    { name: 'github-token', re: /gh[pousr]_[A-Za-z0-9]{20,}/ },
+    { name: 'github-pat', re: /github_pat_[A-Za-z0-9_]{20,}/ },
+    { name: 'pem-private-key', re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA |ENCRYPTED )?PRIVATE KEY-----/ },
+    { name: 'bearer-token', re: /Bearer [A-Za-z0-9._~+/=-]{8,}/ },
+];
+/**
+ * 值形状命中片段中的「示例/占位」词：匹配到的片段含其中任一 → 视为示例形态放行。
+ * 覆盖 `sk-your-*`、`sk-example-*`、`sk-test-*`、`Bearer example-*`、`AKIA...EXAMPLE`（AWS 官方示例）、
+ * JWT 教学串（第三段 signature）等；真实随机密钥串几乎不可能包含这些完整单词，安全不回退。
+ */
+const SECRET_SHAPE_PLACEHOLDER_WORDS = [
+    'your', 'their', 'example', 'sample', 'dummy', 'placeholder',
+    'test', 'demo', 'signature', 'secret', 'value', 'xxxx',
+];
+/** 值形状命中是否「示例/占位」形态（含占位词或尖括号包裹）→ 放行 */
+function isExampleSecretShape(matched) {
+    if (/<[^>]+>/.test(matched))
+        return true;
+    const lower = matched.toLowerCase();
+    return SECRET_SHAPE_PLACEHOLDER_WORDS.some((w) => lower.includes(w));
+}
+function matchSecretValuePatternHit(value, extraPatterns = []) {
+    // 默认内置模式优先，个人化附加模式其次（返回的模式名语义以内置为准，附加模式不抢占）
+    for (const p of SECRET_VALUE_PATTERNS) {
+        const m = p.re.exec(value);
+        if (m !== null)
+            return { name: p.name, matched: m[0] };
+    }
+    for (const p of extraPatterns) {
+        const m = p.re.exec(value);
+        if (m !== null)
+            return { name: p.name, matched: m[0] };
+    }
+    return null;
+}
+/** 值是否命中强模式 secret 形状（示例/占位形态 → null；返回命中模式名；未命中返回 null）。
+ *  extraPatterns 为可选的个人化附加值形状模式（与 SECRET_VALUE_PATTERNS 合并判定，默认内置优先）；
+ *  单参调用行为与历史完全一致（向后兼容）。 */
+export function matchSecretValuePattern(value, extraPatterns = []) {
+    const hit = matchSecretValuePatternHit(value, extraPatterns);
+    if (hit === null)
+        return null;
+    if (isExampleSecretShape(hit.matched))
+        return null;
+    return hit.name;
+}
+/** 规范化字段名：小写 + 去 `_-. ` 分隔符（用于名单匹配） */
+export function normalizeFieldName(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+/** 是否为「环境变量名」形态（全大写下划线，如 DEEPSEEK_API_KEY）→ 视为引用名 */
+export function isEnvVarName(value) {
+    return /^[A-Z][A-Z0-9_]{2,}$/.test(value);
+}
+/** 是否为模板/环境变量引用形态（${VAR} / {{VAR}} / %VAR% / $VAR）→ 值是名字不是秘密。
+ *  注意：文本扫描的 `field: value` 正则用 `[^\s,;}]` 取值，`${...}` / `{{...}}` 的右花括号
+ *  会被截断，因此除完整闭合形态外，也接受「以 ${ / {{ / % 开头、内容全为变量名字符」的截断形态。 */
+export function isTemplateReference(value) {
+    const v = value.trim();
+    // 完整闭合形态
+    if (/^\$\{[A-Za-z0-9_.]+\}$/.test(v))
+        return true;
+    if (/^\{\{[A-Za-z0-9_.]+\}\}$/.test(v))
+        return true;
+    if (/^%[A-Za-z0-9_.]+%$/.test(v))
+        return true;
+    if (/^\$[A-Z][A-Z0-9_]{2,}$/.test(v))
+        return true;
+    // 截断形态（右花括号被取值正则排除）：真实凭据不会以 ${ / {{ / % 开头，放行安全
+    if (/^\$\{[A-Za-z0-9_.]*$/.test(v))
+        return true;
+    if (/^\{\{[A-Za-z0-9_.]*$/.test(v))
+        return true;
+    if (/^%[A-Za-z0-9_.]*$/.test(v))
+        return true;
+    return false;
+}
+/** 字段名是否命中敏感名单（规范化后精确 / 敏感后缀 / 敏感前缀） */
+export function isSensitiveFieldName(field, extra = []) {
+    const norm = normalizeFieldName(field);
+    if (norm === '')
+        return false;
+    if ([...DEFAULT_SECRET_FIELD_NAMES, ...extra].includes(norm))
+        return true;
+    if (SENSITIVE_SUFFIXES.some((s) => norm.endsWith(s) && norm.length > s.length))
+        return true;
+    return SENSITIVE_PREFIXES.some((p) => norm.startsWith(p));
+}
+/** 是否为引用字段（值只是名字，不剥离） */
+export function isReferenceField(field, extra = []) {
+    const norm = normalizeFieldName(field);
+    return [...DEFAULT_REFERENCE_FIELDS, ...extra].includes(norm);
+}
+/** 高熵启发式：长 base64/hex 串且 Shannon 熵高（默认关） */
+function isHighEntropySecret(value) {
+    if (!/^[A-Za-z0-9+/=_-]{32,}$/.test(value))
+        return false;
+    if (/^[A-Za-z0-9_-]+$/.test(value) && !/[0-9]/.test(value))
+        return false; // 纯单词串（如文件名）
+    const counts = new Map();
+    for (const ch of value)
+        counts.set(ch, (counts.get(ch) ?? 0) + 1);
+    let entropy = 0;
+    for (const n of counts.values()) {
+        const p = n / value.length;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy > 4.2;
+}
+/* ---------------- 值形态判定（结构化扫描与文本扫描共用） ---------------- */
+/** 占位符 / 示例形态：xxx、your-token、<...>、example、sample、dummy、placeholder、... */
+const PLACEHOLDER_RE = /^(x{3,}|your[-_ ]?[\w]+|their[-_ ]?[\w]+|<[^>]+>|example|examples?|sample|dummy|placeholder|som[e]thing|^\u2026)/i;
+/** 类型/关键字形态（代码声明，如 `authToken: string`、`token: null`） */
+const TYPE_KEYWORD_RE = /^(string|number|boolean|object|array|any|unknown|null|undefined|void|true|false|required|optional)$/i;
+/** 代码表达式/引用形态：值里出现调用/成员访问/引号/运算符/空白等 → 是代码而非字面量密钥 */
+function isCodeExpressionValue(value) {
+    // 方法调用 / 成员访问：data.token、process.env.X、wx.getStorageSync(...)、a.b(...)
+    if (/[.([\]'"`]/.test(value))
+        return true;
+    // 赋值/比较/模板：a=b、a&&b 等
+    if (/[=+*/%<>!&|?]+/.test(value))
+        return true;
+    // 含空白 → 短语/语句而非单个字面量
+    if (/\s/.test(value))
+        return true;
+    return false;
+}
+/** 混合字符长串是否「疑似真实凭据」：含数字、或含字母数字连字符下划线以外的符号、或大小写混合
+ *  （纯小写字母+连字符的示例值如 `abc-def-ghi-jkl` → 放行；`s3cretP@ssw0rd` / `abc123-def456` → 拦截） */
+function looksLikeCredential(value) {
+    if (value.length < 8)
+        return false;
+    if (/[0-9]/.test(value))
+        return true;
+    if (/[^A-Za-z0-9_-]/.test(value))
+        return true;
+    if (/[a-z]/.test(value) && /[A-Z]/.test(value))
+        return true;
+    return false;
+}
+/** 值是否为「字面量密钥」：既不是代码表达式，也不是占位符/类型词/短标识符/环境引用。
+ *  只有字段名敏感 **且** 值像真实字面量凭据时才报告 —— 消除技能文档中
+ *  `authToken: string`、`password: process.env.X`、`token: data.token` 等代码示例误报。
+ *  extraPatterns 为个人化附加值形状模式，与内置模式一同参与「值形状强信号」判定。 */
+function isLiteralSecretValue(value, extraPatterns = []) {
+    if (value === '')
+        return false;
+    // 值形状强信号（sk- / ghp_ / AKIA / JWT / PEM / Bearer / 个人化附加形状，示例/占位形态已降噪）—— 任何字段都视为真凭据
+    if (matchSecretValuePattern(value, extraPatterns) !== null)
+        return true;
+    if (PLACEHOLDER_RE.test(value))
+        return false;
+    if (TYPE_KEYWORD_RE.test(value))
+        return false;
+    if (isCodeExpressionValue(value))
+        return false;
+    if (isEnvVarName(value))
+        return false;
+    if (isTemplateReference(value))
+        return false;
+    // 纯字母数字短标识符（变量名/普通词，如 authToken、data、key）→ 非密钥
+    if (/^[A-Za-z0-9_]+$/.test(value) && value.length < 20)
+        return false;
+    // 其余：混合字符串，仅当像真实凭据（含数字/符号/大小写混合）才疑似
+    return looksLikeCredential(value);
+}
+/** 判定单个「字段名 + 字符串值」：strip | keep（含引用豁免与值形状）
+ * 顺序：值形状优先（AKIA 等全大写 secret 形状不能被 env 名豁免误放）→ 引用字段 → env 名 → 字段名。
+ * 宽松档（literalValueOnly，市场发布）：字段名命中还要求值像真实字面量凭据（非占位/引用/代码）。 */
+function judgeFieldValue(field, value, opts) {
+    if (value === '')
+        return false;
+    if (opts.literalValueOnly) {
+        // 宽松档（市场发布扫描）：值形状强信号字段无关必拦；字段名敏感 + 值像真实字面量凭据才拦
+        if (opts.valuePatterns && matchSecretValuePattern(value, opts.extraValuePatterns) !== null)
+            return true;
+        if (isSensitiveFieldName(field, opts.extraFieldNames) && isLiteralSecretValue(value, opts.extraValuePatterns))
+            return true;
+        return false;
+    }
+    // 保守档（导出/同步脱敏）：值形状优先 → 引用字段/env 名豁免 → 字段名敏感即剥
+    if (opts.valuePatterns && matchSecretValuePattern(value, opts.extraValuePatterns) !== null)
+        return true;
+    if (isReferenceField(field, opts.extraReferenceFields))
+        return false;
+    if (isEnvVarName(value))
+        return false; // 值是 env 变量名 → 引用
+    if (isSensitiveFieldName(field, opts.extraFieldNames))
+        return true;
+    if (opts.highEntropy && isHighEntropySecret(value))
+        return true;
+    return false;
+}
+/** 递归扫描 + 剥离（纯函数，不改原数据；深度保护；返回清洗后数据与命中清单） */
+export function scanAndRedact(data, opts = {}) {
+    const maxDepth = opts.maxDepth ?? 64;
+    const cfg = {
+        extraFieldNames: opts.extraFieldNames ?? [],
+        extraReferenceFields: opts.extraReferenceFields ?? [],
+        extraValuePatterns: opts.extraValuePatterns ?? [],
+        valuePatterns: opts.valuePatterns ?? true,
+        highEntropy: opts.highEntropy ?? false,
+        literalValueOnly: opts.literalValueOnly ?? false,
+    };
+    const hits = [];
+    if (data === null || typeof data !== 'object')
+        return { sanitized: data, hits };
+    if (data instanceof Uint8Array)
+        return { sanitized: data, hits };
+    const rootOut = Array.isArray(data) ? [] : {};
+    const stack = [{ src: data, dst: rootOut, path: '', depth: 1 }];
+    const visited = new WeakSet();
+    visited.add(data);
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        const { src, dst, path, depth } = frame;
+        if (depth > maxDepth)
+            throw new JsonDepthError(`扫描深度 ${depth} 超过上限 ${maxDepth}`);
+        if (src instanceof Uint8Array)
+            continue;
+        if (Array.isArray(src)) {
+            const outArr = dst;
+            for (let i = 0; i < src.length; i++) {
+                const v = src[i];
+                const childPath = `${path}[${i}]`;
+                if (v !== null && typeof v === 'object' && !(v instanceof Uint8Array)) {
+                    if (visited.has(v))
+                        throw new Error(`检测到循环引用，无法扫描（路径 ${childPath}）`);
+                    visited.add(v);
+                    const childOut = Array.isArray(v) ? [] : {};
+                    outArr.push(childOut);
+                    stack.push({ src: v, dst: childOut, path: childPath, depth: depth + 1 });
+                }
+                else {
+                    outArr.push(v);
+                }
+            }
+            continue;
+        }
+        const outObj = dst;
+        for (const [k, v] of Object.entries(src)) {
+            const childPath = path === '' ? k : `${path}.${k}`;
+            if (typeof v === 'string') {
+                if (judgeFieldValue(k, v, cfg)) {
+                    hits.push({ path: childPath, field: k });
+                    outObj[k] = REDACTED_PLACEHOLDER;
+                }
+                else {
+                    outObj[k] = v;
+                }
+                continue;
+            }
+            if (v !== null && typeof v === 'object' && !(v instanceof Uint8Array)) {
+                if (visited.has(v))
+                    throw new Error(`检测到循环引用，无法扫描（路径 ${childPath}）`);
+                visited.add(v);
+                const childOut = Array.isArray(v) ? [] : {};
+                outObj[k] = childOut;
+                stack.push({ src: v, dst: childOut, path: childPath, depth: depth + 1 });
+            }
+            else {
+                outObj[k] = v;
+            }
+        }
+    }
+    return { sanitized: rootOut, hits };
+}
+/* ---------------- 文本级扫描（scanText，文件类分区内容用） ---------------- */
+const FIELD_VALUE_RE = [
+    // "field": "value"（JSON 形态，保留引号）
+    { re: /"([A-Za-z0-9_.\-]+)"\s*:\s*"([^"]*)"/g, json: true },
+    // field=value
+    { re: /([A-Za-z0-9_.\-]+)\s*=\s*([^\s,;]+)/g, json: false },
+    // field: value
+    { re: /([A-Za-z0-9_.\-]+)\s*:\s*([^\s,;}]+)/g, json: false },
+];
+/** 文本级扫描：逐行找「敏感字段名 + 疑似真实字面量凭据」与「值形状」命中（只报告，不修改文本）。
+ *  2026-08-20 优化：字段名命中不再是充分条件 —— 值必须是「非代码引用 / 非占位符 / 非类型词 /
+ *  非短标识符」的字面量，消除技能/代码文档中 `token:`/`password:` 等示例命名的误报；
+ *  2026-08-21 优化：值形状（sk-/ghp_/AKIA/JWT/PEM/Bearer）对示例/占位形态（含 your/example/
+ *  xxx/test/<...> 等占位词）放行；混合字符串需像真实凭据（含数字/符号/大小写混合）才报告。 */
+export function scanText(text, opts = {}) {
+    const hits = [];
+    const extra = opts.extraFieldNames ?? [];
+    const extraPatterns = opts.extraValuePatterns ?? [];
+    const valuePatterns = opts.valuePatterns ?? true;
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const linePath = `line:${i + 1}`;
+        // 字段名形态
+        for (const { re, json } of FIELD_VALUE_RE) {
+            re.lastIndex = 0;
+            let m;
+            while ((m = re.exec(line)) !== null) {
+                const field = m[1];
+                const value = m[2];
+                if (!isSensitiveFieldName(field, extra))
+                    continue;
+                // 值必须是「疑似字面量凭据」才报告（消除代码示例/占位符误报）
+                if (!isLiteralSecretValue(value, extraPatterns))
+                    continue;
+                hits.push({ path: linePath, field });
+            }
+        }
+        // 值形状（字段名无关；整行 trim 后匹配 sk-/ghp_/JWT/PEM/Bearer 及个人化附加形状等强信号，示例形态已降噪）
+        if (valuePatterns) {
+            const trimmed = line.trim();
+            const name = matchSecretValuePattern(trimmed, extraPatterns);
+            if (name !== null)
+                hits.push({ path: linePath, field: `(${name})` });
+        }
+    }
+    return hits;
+}
+/** 强化版 SecretScanner（对齐 core SecretScanner 契约，可注入 Exporter.scanner） */
+export function createSecretScanner(opts = {}) {
+    return {
+        scanAndRedact(data) {
+            return scanAndRedact(data, opts);
+        },
+        scanText(text) {
+            return scanText(text, opts);
+        },
+    };
+}
+/** 从部署配置构造扫描器；未配置（undefined 或全部为空）时返回默认 createSecretScanner()，
+ *  行为与默认完全一致。配置了个人化规则时将其作为附加字段名 / 引用字段 / 值形状模式合并进扫描器。 */
+export function createConfiguredSecretScanner(patterns) {
+    if (patterns === undefined)
+        return createSecretScanner();
+    const isEmpty = (patterns.extraFieldNames?.length ?? 0) === 0 &&
+        (patterns.extraReferenceFields?.length ?? 0) === 0 &&
+        (patterns.extraValuePatterns?.length ?? 0) === 0;
+    if (isEmpty)
+        return createSecretScanner();
+    return createSecretScanner({
+        extraFieldNames: patterns.extraFieldNames,
+        extraReferenceFields: patterns.extraReferenceFields,
+        extraValuePatterns: patterns.extraValuePatterns,
+    });
+}
+//# sourceMappingURL=secret-scanner.js.map

package/lib/security/vault.d.ts

@@ -0,0 +1,59 @@
+import type { FileSystemFacade } from '../core/types.ts';
+/**
+ * 默认敏感文件清单（相对 $DSH_HOME）：当前 DSH 唯一「整文件即秘密」的文件
+ * （.credentials.yaml = 凭据明文 token/password/密钥）。
+ * 宿主可传入扩展清单（如 profiles/<p>/secrets.yaml、.env 等），默认清单保持最小。
+ */
+export declare const DEFAULT_SENSITIVE_RELS: readonly string[];
+/** vault 根目录 = <dataDir>/vault */
+export declare function vaultRootOf(dataDir: string): string;
+/** 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;
+}
+/**
+ * 刷新 vault：把 $DSH_HOME 下现存敏感文件镜像到 <dataDir>/vault/<rel>。
+ * 幂等：重复调用结果一致（同字节覆盖写，不产生重复条目）。
+ * 清理：源文件已不存在、或 rel 不再属于传入清单的旧镜像会被删除。
+ * 返回实际入库清单（供报告 / 提示「已镜像到本机 vault」）。
+ */
+export declare function refreshVault(fs: FileSystemFacade, dataDir: string, dshHome: string, rels: readonly string[]): Promise<VaultRefreshResult>;
+/**
+ * 从 vault 回填敏感文件到 $DSH_HOME（跨机恢复 / 本机误删后的恢复）。
+ * 不覆盖已存在的目标文件（安全：避免覆盖目标机更新后的凭据）；
+ * vault 无对应文件（跨机恢复、从未镜像过）记入 missing，由调用方提示用户重填。
+ */
+export declare function restoreVaultFiles(fs: FileSystemFacade, dataDir: string, dshHome: string, rels: readonly string[]): Promise<VaultRestoreResult>;
+/**
+ * 列出 vault 内容（镜像结构 = 相对 $DSH_HOME 的 rel 平铺在 vault 根下，
+ * 例如 vault/.credentials.yaml 即 $DSH_HOME/.credentials.yaml 的镜像）。
+ * vault 不存在 / 为空时返回空数组。
+ */
+export declare function listVault(fs: FileSystemFacade, dataDir: string, dshHome: string): Promise<VaultEntry[]>;

package/lib/security/vault.js

@@ -0,0 +1,151 @@
+/**
+ * 文件级 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 { isPathSafe, normalizePath } from '../utils/paths.js';
+/**
+ * 默认敏感文件清单（相对 $DSH_HOME）：当前 DSH 唯一「整文件即秘密」的文件
+ * （.credentials.yaml = 凭据明文 token/password/密钥）。
+ * 宿主可传入扩展清单（如 profiles/<p>/secrets.yaml、.env 等），默认清单保持最小。
+ */
+export const DEFAULT_SENSITIVE_RELS = [
+    '.credentials.yaml',
+];
+/** vault 根目录 = <dataDir>/vault */
+export function vaultRootOf(dataDir) {
+    return path.join(dataDir, 'vault');
+}
+/** rel 必须为安全相对路径（拒绝绝对路径 / .. / 盘符 / NUL），防路径穿越 */
+function assertSafeRel(rel) {
+    if (!isPathSafe(rel))
+        throw new Error(`vault: 非法敏感文件路径 "${rel}"`);
+}
+/** 校验 + 归一化 rel 清单（统一 / 分隔，与 FileSystemFacade.listRecursive 产出对齐） */
+function normalizeRels(rels) {
+    const out = [];
+    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, dataDir, dshHome, rels) {
+    const normRels = normalizeRels(rels);
+    const vaultRoot = vaultRootOf(dataDir);
+    await fs.mkdir(vaultRoot); // 宿主 mkdir 递归；失败向上抛（调用方按尽力而为处理）
+    const mirrored = [];
+    const skipped = [];
+    // 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 = [];
+    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, dataDir, dshHome, rels) {
+    const normRels = normalizeRels(rels);
+    const vaultRoot = vaultRootOf(dataDir);
+    const restored = [];
+    const missing = [];
+    const skipped = [];
+    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, dataDir, dshHome) {
+    const vaultRoot = vaultRootOf(dataDir);
+    const homeRels = await fs.listRecursive(vaultRoot); // home-relative；vault 不存在时宿主返回 []
+    const entries = [];
+    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));
+}
+//# sourceMappingURL=vault.js.map

package/lib/security/zip-security.d.ts

@@ -0,0 +1,27 @@
+import { ZipArchive, type ZipSafetyLimits } from '../utils/zip.ts';
+export { isPathSafe } from '../utils/paths.ts';
+/** 可执行文件扩展名黑名单（§19.6：只警告，本插件不执行任何脚本） */
+export declare const EXECUTABLE_EXTENSIONS: Set<string>;
+/** 条目名是否疑似可执行文件（按扩展名） */
+export declare function isExecutableName(name: string): boolean;
+/**
+ * 强化版 ZIP 解析：在 core 全部安全校验（条目名/条目数/压缩体积）之上，
+ * 增加 symlink 拒绝与重复条目名拒绝。返回 core `ZipArchive`（解压校验完全复用）。
+ */
+export declare function parseZipHardened(buf: Uint8Array, limits?: ZipSafetyLimits): ZipArchive;
+/** 工厂：带默认限额的强化解析器（对齐 ImporterOptions.parseZipOverride 签名） */
+export declare function createHardenedZipParser(defaultLimits?: ZipSafetyLimits): (buf: Uint8Array, limits?: ZipSafetyLimits) => ZipArchive;
+export interface SafeExtractResult {
+    /** 已解压条目的 ZIP 相对路径（正斜杠） */
+    files: string[];
+    /** 非阻塞告警（可执行文件条目等） */
+    warnings: string[];
+}
+/**
+ * 安全解压到受控目录（对齐 core safeExtract 语义 + 强化）：
+ *  - 条目名/限额/symlink/重复名检查（parseZipHardened）；
+ *  - 逐条 CRC32/尺寸/预算校验（ZipArchive.readEntry）；
+ *  - 解压后 lstat 复查「全部产物必须是普通文件」（防符号链接/非常规写入）；
+ *  - 任何异常 → 中止并**完整清理** destDir 后抛出（不残留部分落盘）。
+ */
+export declare function safeExtractHardened(zipPath: string, destDir: string, limits?: ZipSafetyLimits): Promise<SafeExtractResult>;