@logictan/dsh-config-manager 0.1.60

package/lib/security/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 安全模块公共出口（m4-security）：
+ *  secret-scanner / encryption / integrity / zip-security / redaction。
+ *
+ * 与 core 的注入点对齐：
+ *  - `createSecretScanner()`        → ExporterOptions.scanner（SecretScanner 契约）
+ *  - `createEncryptionProvider(pw)` → ExporterOptions.encryption（EncryptionProvider 契约）
+ *  - `createHardenedZipParser()`    → ImporterOptions.parseZipOverride（(buf, limits?) => ZipArchive）
+ *  - `safeExtractHardened()`        → m5 导入文件类分区落盘通道
+ *  - `verifyChecksumsJson()`        → 完整性校验通道（core analyzer 已有内置校验，本模块供独立调用）
+ */
+export * from './secret-scanner.ts';
+export * from './encryption.ts';
+export * from './integrity.ts';
+export * from './zip-security.ts';
+export * from './redaction.ts';

package/lib/security/index.js

@@ -0,0 +1,17 @@
+/**
+ * 安全模块公共出口（m4-security）：
+ *  secret-scanner / encryption / integrity / zip-security / redaction。
+ *
+ * 与 core 的注入点对齐：
+ *  - `createSecretScanner()`        → ExporterOptions.scanner（SecretScanner 契约）
+ *  - `createEncryptionProvider(pw)` → ExporterOptions.encryption（EncryptionProvider 契约）
+ *  - `createHardenedZipParser()`    → ImporterOptions.parseZipOverride（(buf, limits?) => ZipArchive）
+ *  - `safeExtractHardened()`        → m5 导入文件类分区落盘通道
+ *  - `verifyChecksumsJson()`        → 完整性校验通道（core analyzer 已有内置校验，本模块供独立调用）
+ */
+export * from './secret-scanner.js';
+export * from './encryption.js';
+export * from './integrity.js';
+export * from './zip-security.js';
+export * from './redaction.js';
+//# sourceMappingURL=index.js.map

package/lib/security/integrity.d.ts

@@ -0,0 +1,30 @@
+import type { ChecksumVerifyResult } from '../utils/hashing.ts';
+export declare const CHECKSUMS_ALGORITHM: 'sha256';
+export declare const SHA256_HEX_RE: RegExp;
+/** 与 core ZIP 条目数上限一致的默认表大小上限 */
+export declare const DEFAULT_MAX_CHECKSUM_ENTRIES = 10000;
+export interface ChecksumsTableOptions {
+    maxEntries?: number;
+}
+/**
+ * 生成 checksums 表（对齐 core 扁平格式；内部复用 core buildChecksums）。
+ * entries.name 必须是 ZIP 内正斜杠相对路径。
+ */
+export declare function buildChecksums(entries: {
+    name: string;
+    data: Uint8Array;
+}[]): Record<string, string>;
+/**
+ * 解析并结构校验 checksums.json 原文。
+ * 非法结构 / 危险键 / 值非 SHA-256 hex / 条目数超限 → 抛错（不可信输入，宁可拒绝）。
+ */
+export declare function parseChecksumsTable(raw: string, opts?: ChecksumsTableOptions): Record<string, string>;
+/**
+ * 校验：表内每个路径必须在 entries 中存在且 SHA-256 一致；entries 多余文件（manifest/自身）不参与。
+ * 返回 { ok, mismatches, missing }（缺失与不符统一列入 mismatches 的展开视图，mismatches 只含不符）。
+ */
+export declare function verifyChecksums(entries: ReadonlyMap<string, Uint8Array>, table: Record<string, string>): ChecksumVerifyResult;
+/** 一步到位：解析 checksums.json 原文并校验（解析失败抛错；不符返回 {ok:false,...}） */
+export declare function verifyChecksumsJson(entries: ReadonlyMap<string, Uint8Array>, raw: string, opts?: ChecksumsTableOptions): ChecksumVerifyResult;
+/** 人类可读的不匹配摘要（给「Backup integrity check failed」错误消息用） */
+export declare function describeMismatches(result: ChecksumVerifyResult): string;

package/lib/security/integrity.js

@@ -0,0 +1,78 @@
+/**
+ * 配置完整性（规范 §18 / 设计 §9.7 / core utils/hashing.ts 的强化层）。
+ *
+ * checksums.json 实际格式由 core exporter 定死（`src/core/exporter.ts`）：
+ * 扁平对象 `{ "<ZIP 内相对路径>": "<sha256 hex>" }`，覆盖除 manifest.json 与自身外的全部条目；
+ * core analyzer 导入时按此解析（`as Record<string, string>`）。本模块**对齐该格式**，不擅自改结构。
+ *
+ * 强化点（在 core hashing 之上）：
+ *  - 解析防线：结构校验（对象、值必须 64 位 hex）、条目数上限、拒绝 `__proto__`/`constructor`/`prototype`
+ *    危险键（防 prototype pollution）；解析失败抛错 → 导入方归为「Backup integrity check failed」。
+ *  - 一步到位 `verifyChecksumsJson`：解析 + 校验合并，供 m5/导入管线直接调用。
+ *  - 校验语义：表内每个路径必须在条目集合中存在且 SHA-256 一致；缺失与不符均计入 mismatches。
+ */
+import { parseJsonSafe } from '../utils/json.js';
+import { buildChecksums as coreBuildChecksums, verifyChecksums as coreVerifyChecksums, } from '../utils/hashing.js';
+export const CHECKSUMS_ALGORITHM = 'sha256';
+export const SHA256_HEX_RE = /^[0-9a-f]{64}$/i;
+/** 与 core ZIP 条目数上限一致的默认表大小上限 */
+export const DEFAULT_MAX_CHECKSUM_ENTRIES = 10_000;
+/** 危险键（原型污染向量）：解析时拒绝 */
+const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+/**
+ * 生成 checksums 表（对齐 core 扁平格式；内部复用 core buildChecksums）。
+ * entries.name 必须是 ZIP 内正斜杠相对路径。
+ */
+export function buildChecksums(entries) {
+    return coreBuildChecksums(entries);
+}
+/**
+ * 解析并结构校验 checksums.json 原文。
+ * 非法结构 / 危险键 / 值非 SHA-256 hex / 条目数超限 → 抛错（不可信输入，宁可拒绝）。
+ */
+export function parseChecksumsTable(raw, opts = {}) {
+    const maxEntries = opts.maxEntries ?? DEFAULT_MAX_CHECKSUM_ENTRIES;
+    const parsed = parseJsonSafe(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('checksums.json 必须是 JSON 对象');
+    }
+    const entries = Object.entries(parsed);
+    if (entries.length > maxEntries) {
+        throw new Error(`checksums.json 条目数 ${entries.length} 超过上限 ${maxEntries}`);
+    }
+    const table = {};
+    for (const [relPath, hash] of entries) {
+        if (DANGEROUS_KEYS.has(relPath)) {
+            throw new Error(`checksums.json 含危险键 "${relPath}"，已拒绝`);
+        }
+        if (relPath === '' || relPath.includes('\\') || relPath.startsWith('/')) {
+            throw new Error(`checksums.json 含非法相对路径 "${relPath}"`);
+        }
+        if (typeof hash !== 'string' || !SHA256_HEX_RE.test(hash)) {
+            throw new Error(`checksums.json["${relPath}"] 不是合法的 SHA-256 hex`);
+        }
+        table[relPath] = hash;
+    }
+    return table;
+}
+/**
+ * 校验：表内每个路径必须在 entries 中存在且 SHA-256 一致；entries 多余文件（manifest/自身）不参与。
+ * 返回 { ok, mismatches, missing }（缺失与不符统一列入 mismatches 的展开视图，mismatches 只含不符）。
+ */
+export function verifyChecksums(entries, table) {
+    return coreVerifyChecksums(entries, table);
+}
+/** 一步到位：解析 checksums.json 原文并校验（解析失败抛错；不符返回 {ok:false,...}） */
+export function verifyChecksumsJson(entries, raw, opts = {}) {
+    const table = parseChecksumsTable(raw, opts);
+    return verifyChecksums(entries, table);
+}
+/** 人类可读的不匹配摘要（给「Backup integrity check failed」错误消息用） */
+export function describeMismatches(result) {
+    const parts = [
+        ...result.mismatches.map((m) => `"${m}" (hash 不符)`),
+        ...result.missing.map((m) => `"${m}" (缺失)`),
+    ];
+    return parts.join(', ');
+}
+//# sourceMappingURL=integrity.js.map

package/lib/security/redaction.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 日志/文本脱敏（规范 §24 / 设计 §9.8 / core utils/logger.ts 的强化层）。
+ *
+ * 与 core logger.redact 的分工：core 版按固定字段名单做子串替换（不感知字段边界）；
+ * 本模块为强化版，两模式：
+ *  1. **结构化字段形态**：JSON `"field": "value"` / `field=value` / `field: value`，
+ *     字段名命中敏感名单（复用 secret-scanner 的 `isSensitiveFieldName`，单一来源防漂移）→ 值替换。
+ *  2. **值形状模式**：与字段名无关，文本任意位置出现 sk- / JWT / AKIA / GitHub PAT /
+ *     PEM 私钥 / Bearer / URL query 的敏感参数值 → 替换。
+ *
+ * 幂等性：替换产物 `***REDACTED***` 不匹配任何模式，重复 redact 结果不变；
+ * JSON 行的引号结构保留（输出仍是合法 JSON）。
+ */
+import { DEFAULT_SECRET_FIELD_NAMES } from './secret-scanner.ts';
+export declare const REDACTED = "***REDACTED***";
+/**
+ * 文本脱敏（幂等）。blacklist 为**附加**规范化字段名（小写无分隔符，如 'clientsecret'）。
+ * 输出仍保留结构化形态（JSON 行合法）。
+ */
+export declare function redact(text: string, blacklist?: readonly string[]): string;
+/** 对象级掩码：字段名命中敏感名单 → 整值替换（返回新对象，不改原对象；结构与类型保留） */
+export declare function redactValue(value: unknown, blacklist?: readonly string[]): unknown;
+/** 预编译脱敏器（多次调用复用；blacklist 为附加规范化字段名） */
+export declare function createRedactor(blacklist?: readonly string[]): (text: string) => string;
+/** 默认名单（文档用；redact 的默认附加名单为空，内置判定已含 DEFAULT_SECRET_FIELD_NAMES） */
+export { DEFAULT_SECRET_FIELD_NAMES };

package/lib/security/redaction.js

@@ -0,0 +1,95 @@
+/**
+ * 日志/文本脱敏（规范 §24 / 设计 §9.8 / core utils/logger.ts 的强化层）。
+ *
+ * 与 core logger.redact 的分工：core 版按固定字段名单做子串替换（不感知字段边界）；
+ * 本模块为强化版，两模式：
+ *  1. **结构化字段形态**：JSON `"field": "value"` / `field=value` / `field: value`，
+ *     字段名命中敏感名单（复用 secret-scanner 的 `isSensitiveFieldName`，单一来源防漂移）→ 值替换。
+ *  2. **值形状模式**：与字段名无关，文本任意位置出现 sk- / JWT / AKIA / GitHub PAT /
+ *     PEM 私钥 / Bearer / URL query 的敏感参数值 → 替换。
+ *
+ * 幂等性：替换产物 `***REDACTED***` 不匹配任何模式，重复 redact 结果不变；
+ * JSON 行的引号结构保留（输出仍是合法 JSON）。
+ */
+import { DEFAULT_SECRET_FIELD_NAMES, isSensitiveFieldName } from './secret-scanner.js';
+export const REDACTED = '***REDACTED***';
+/* ---------------- 结构化字段形态 ---------------- */
+const JSON_FIELD_RE = /"([A-Za-z0-9_.\-]+)"\s*:\s*"([^"]*)"/g;
+/** kv 值到空白/逗号/分号/&（& 截断：避免吞掉 URL query 的后续参数） */
+const KV_FIELD_RE = /([A-Za-z0-9_.\-]+)\s*=\s*([^\s,;&]+)/g;
+/** colon 值允许空格（如 `Authorization: Bearer xyz`），到逗号/分号/右大括号截断 */
+const COLON_FIELD_RE = /([A-Za-z0-9_.\-]+)\s*:\s*([^,;}]+)/g;
+/* ---------------- 值形状模式（包含式，字段名无关） ---------------- */
+const VALUE_PATTERNS = [
+    { name: 'openai-key', re: /sk-[A-Za-z0-9_-]{8,}/g },
+    { name: 'jwt', re: /eyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g },
+    { name: 'aws-access-key', re: /AKIA[0-9A-Z]{16}/g },
+    { name: 'github-token', re: /gh[pousr]_[A-Za-z0-9]{20,}/g },
+    { name: 'github-pat', re: /github_pat_[A-Za-z0-9_]{20,}/g },
+    { name: 'pem-private-key', re: /-----BEGIN [A-Za-z0-9 ]*PRIVATE KEY-----/g },
+    { name: 'bearer-token', re: /Bearer [A-Za-z0-9._~+/=-]{8,}/g },
+];
+/** URL query 中的敏感参数值（保留参数名，只替换值） */
+const URL_QUERY_RE = /([?&](?:token|api[_-]?key|key|secret|access[_-]?token|password|auth)=)([^&\s"']+)/gi;
+/* ---------------- redact ---------------- */
+function replaceSensitiveField(text, re, blacklist) {
+    return text.replace(re, (match, field, value) => {
+        if (!isSensitiveFieldName(field, blacklist))
+            return match;
+        if (value === '')
+            return match;
+        // 只替换值部分，保留原分隔符与引号形态（JSON `"f": "v"` / kv `f=v` / colon `f: v`）
+        const idx = match.lastIndexOf(value);
+        return match.slice(0, idx) + REDACTED + match.slice(idx + value.length);
+    });
+}
+/**
+ * 文本脱敏（幂等）。blacklist 为**附加**规范化字段名（小写无分隔符，如 'clientsecret'）。
+ * 输出仍保留结构化形态（JSON 行合法）。
+ */
+export function redact(text, blacklist = []) {
+    let out = text;
+    // 1. 结构化字段形态（顺序：JSON → kv → colon；JSON 键不会被后续形态二次命中）
+    out = replaceSensitiveField(out, JSON_FIELD_RE, blacklist);
+    out = replaceSensitiveField(out, KV_FIELD_RE, blacklist);
+    out = replaceSensitiveField(out, COLON_FIELD_RE, blacklist);
+    // 2. 值形状模式（字段名无关，包含式）
+    for (const { re } of VALUE_PATTERNS) {
+        re.lastIndex = 0;
+        out = out.replace(re, REDACTED);
+    }
+    out = out.replace(URL_QUERY_RE, `$1${REDACTED}`);
+    return out;
+}
+/** 对象级掩码：字段名命中敏感名单 → 整值替换（返回新对象，不改原对象；结构与类型保留） */
+export function redactValue(value, blacklist = []) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (value instanceof Uint8Array)
+        return value;
+    if (Array.isArray(value))
+        return value.map((v) => redactValue(v, blacklist));
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = isSensitiveFieldName(k, blacklist) ? REDACTED : redactValue(v, blacklist);
+    }
+    return out;
+}
+/** 预编译脱敏器（多次调用复用；blacklist 为附加规范化字段名） */
+export function createRedactor(blacklist = []) {
+    const compiled = { json: JSON_FIELD_RE, kv: KV_FIELD_RE, colon: COLON_FIELD_RE };
+    return (text) => {
+        let out = replaceSensitiveField(text, new RegExp(compiled.json.source, 'g'), blacklist);
+        out = replaceSensitiveField(out, new RegExp(compiled.kv.source, 'g'), blacklist);
+        out = replaceSensitiveField(out, new RegExp(compiled.colon.source, 'g'), blacklist);
+        for (const { re } of VALUE_PATTERNS) {
+            re.lastIndex = 0;
+            out = out.replace(re, REDACTED);
+        }
+        out = out.replace(URL_QUERY_RE, `$1${REDACTED}`);
+        return out;
+    };
+}
+/** 默认名单（文档用；redact 的默认附加名单为空，内置判定已含 DEFAULT_SECRET_FIELD_NAMES） */
+export { DEFAULT_SECRET_FIELD_NAMES };
+//# sourceMappingURL=redaction.js.map

package/lib/security/secret-scanner.d.ts

@@ -0,0 +1,86 @@
+import type { SecretScanner, SensitiveHit } from '../core/types.ts';
+/** 剥离占位（与 core defaultSecretScanner 语义一致：空串 = 需补录提示） */
+export declare const REDACTED_PLACEHOLDER = "";
+/**
+ * 敏感字段名单（规范化名：小写、无分隔符）。
+ * 覆盖规范 §6 原始清单 + 设计 §7.2 + core logger 名单，并保持克制以防误伤
+ * （不收录 `key`/`session` 等过宽子串——`sessionIds`/`monkey` 不得中招）。
+ */
+export declare const DEFAULT_SECRET_FIELD_NAMES: readonly string[];
+/** 引用字段（值只是「名字」而非秘密）：规范化精确命中即豁免 */
+export declare const DEFAULT_REFERENCE_FIELDS: readonly string[];
+/** 值形状强模式（默认开）：一眼可辨的密钥/凭据形态（包含式：值内任意位置出现即命中） */
+export interface ValuePattern {
+    name: string;
+    re: RegExp;
+}
+export declare const SECRET_VALUE_PATTERNS: readonly ValuePattern[];
+/** 值是否命中强模式 secret 形状（示例/占位形态 → null；返回命中模式名；未命中返回 null）。
+ *  extraPatterns 为可选的个人化附加值形状模式（与 SECRET_VALUE_PATTERNS 合并判定，默认内置优先）；
+ *  单参调用行为与历史完全一致（向后兼容）。 */
+export declare function matchSecretValuePattern(value: string, extraPatterns?: readonly ValuePattern[]): string | null;
+export interface SecretScannerOptions {
+    /** 附加敏感字段名（任意原始形态，内部会规范化） */
+    extraFieldNames?: string[];
+    /** 附加引用字段名（规范化后精确命中即豁免） */
+    extraReferenceFields?: string[];
+    /**
+     * 附加值形状强模式（个人化规则，如昵称/用户名格式；与 SECRET_VALUE_PATTERNS 合并参与值形状判定，
+     * 默认内置模式优先；示例/占位形态同样降噪放行）。来自部署配置 personalPatterns，不进开源代码。
+     */
+    extraValuePatterns?: ValuePattern[];
+    /** 值形状启发式开关（默认 true） */
+    valuePatterns?: boolean;
+    /** 高熵长串启发式（默认 false：误伤风险高，需显式开启） */
+    highEntropy?: boolean;
+    /**
+     * 宽松档（默认 false = 保守档）。
+     * 保守档（导出/同步脱敏）：字段名敏感即命中，值形状优先、引用/env 名豁免；
+     * 宽松档（市场发布扫描）：字段名敏感**且**值像真实字面量凭据才命中——占位符 /
+     * 模板引用 / 代码表达式 / 类型词 / 短标识符放行，消除「值不是秘密」的误报。
+     */
+    literalValueOnly?: boolean;
+    /** 最大递归深度（默认 64，与 JSON 深度上限一致） */
+    maxDepth?: number;
+}
+/** 规范化字段名：小写 + 去 `_-. ` 分隔符（用于名单匹配） */
+export declare function normalizeFieldName(name: string): string;
+/** 是否为「环境变量名」形态（全大写下划线，如 DEEPSEEK_API_KEY）→ 视为引用名 */
+export declare function isEnvVarName(value: string): boolean;
+/** 是否为模板/环境变量引用形态（${VAR} / {{VAR}} / %VAR% / $VAR）→ 值是名字不是秘密。
+ *  注意：文本扫描的 `field: value` 正则用 `[^\s,;}]` 取值，`${...}` / `{{...}}` 的右花括号
+ *  会被截断，因此除完整闭合形态外，也接受「以 ${ / {{ / % 开头、内容全为变量名字符」的截断形态。 */
+export declare function isTemplateReference(value: string): boolean;
+/** 字段名是否命中敏感名单（规范化后精确 / 敏感后缀 / 敏感前缀） */
+export declare function isSensitiveFieldName(field: string, extra?: readonly string[]): boolean;
+/** 是否为引用字段（值只是名字，不剥离） */
+export declare function isReferenceField(field: string, extra?: readonly string[]): boolean;
+/** 递归扫描 + 剥离（纯函数，不改原数据；深度保护；返回清洗后数据与命中清单） */
+export declare function scanAndRedact(data: unknown, opts?: SecretScannerOptions): {
+    sanitized: unknown;
+    hits: SensitiveHit[];
+};
+/** 文本级扫描：逐行找「敏感字段名 + 疑似真实字面量凭据」与「值形状」命中（只报告，不修改文本）。
+ *  2026-08-20 优化：字段名命中不再是充分条件 —— 值必须是「非代码引用 / 非占位符 / 非类型词 /
+ *  非短标识符」的字面量，消除技能/代码文档中 `token:`/`password:` 等示例命名的误报；
+ *  2026-08-21 优化：值形状（sk-/ghp_/AKIA/JWT/PEM/Bearer）对示例/占位形态（含 your/example/
+ *  xxx/test/<...> 等占位词）放行；混合字符串需像真实凭据（含数字/符号/大小写混合）才报告。 */
+export declare function scanText(text: string, opts?: SecretScannerOptions): SensitiveHit[];
+/** 强化版 SecretScanner（对齐 core SecretScanner 契约，可注入 Exporter.scanner） */
+export declare function createSecretScanner(opts?: SecretScannerOptions): SecretScanner;
+/**
+ * 部署配置（F2 个人隐私规则注入，对齐 dsh-packer config.personalPatterns 设计）：
+ * 通用隐私规则开源内置（DEFAULT_SECRET_FIELD_NAMES / SECRET_VALUE_PATTERNS 等），
+ * 个人化规则（昵称/用户名等）由部署者注入，不进开源代码。
+ */
+export interface ConfiguredSecretPatterns {
+    /** 附加敏感字段名（个人账号/昵称等字段） */
+    extraFieldNames?: string[];
+    /** 附加引用字段名（值只是名字，如引用环境变量名的个人字段） */
+    extraReferenceFields?: string[];
+    /** 附加值形状强模式（个人昵称/用户名等一眼可辨格式） */
+    extraValuePatterns?: ValuePattern[];
+}
+/** 从部署配置构造扫描器；未配置（undefined 或全部为空）时返回默认 createSecretScanner()，
+ *  行为与默认完全一致。配置了个人化规则时将其作为附加字段名 / 引用字段 / 值形状模式合并进扫描器。 */
+export declare function createConfiguredSecretScanner(patterns: ConfiguredSecretPatterns | undefined): SecretScanner;