dsh-config-manager 0.1.0

package/src/security/index.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/src/security/integrity.ts

@@ -0,0 +1,102 @@
+/**
+ * 配置完整性（规范 §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.ts';
+import {
+  buildChecksums as coreBuildChecksums,
+  verifyChecksums as coreVerifyChecksums,
+} from '../utils/hashing.ts';
+import type { ChecksumVerifyResult } from '../utils/hashing.ts';
+
+export const CHECKSUMS_ALGORITHM = 'sha256' as const;
+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']);
+
+export interface ChecksumsTableOptions {
+  maxEntries?: number;
+}
+
+/**
+ * 生成 checksums 表（对齐 core 扁平格式；内部复用 core buildChecksums）。
+ * entries.name 必须是 ZIP 内正斜杠相对路径。
+ */
+export function buildChecksums(entries: { name: string; data: Uint8Array }[]): Record<string, string> {
+  return coreBuildChecksums(entries);
+}
+
+/**
+ * 解析并结构校验 checksums.json 原文。
+ * 非法结构 / 危险键 / 值非 SHA-256 hex / 条目数超限 → 抛错（不可信输入，宁可拒绝）。
+ */
+export function parseChecksumsTable(
+  raw: string,
+  opts: ChecksumsTableOptions = {},
+): Record<string, string> {
+  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 as Record<string, unknown>);
+  if (entries.length > maxEntries) {
+    throw new Error(`checksums.json 条目数 ${entries.length} 超过上限 ${maxEntries}`);
+  }
+  const table: Record<string, string> = {};
+  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: ReadonlyMap<string, Uint8Array>,
+  table: Record<string, string>,
+): ChecksumVerifyResult {
+  return coreVerifyChecksums(entries, table);
+}
+
+/** 一步到位：解析 checksums.json 原文并校验（解析失败抛错；不符返回 {ok:false,...}） */
+export function verifyChecksumsJson(
+  entries: ReadonlyMap<string, Uint8Array>,
+  raw: string,
+  opts: ChecksumsTableOptions = {},
+): ChecksumVerifyResult {
+  const table = parseChecksumsTable(raw, opts);
+  return verifyChecksums(entries, table);
+}
+
+/** 人类可读的不匹配摘要（给「Backup integrity check failed」错误消息用） */
+export function describeMismatches(result: ChecksumVerifyResult): string {
+  const parts = [
+    ...result.mismatches.map((m) => `"${m}" (hash 不符)`),
+    ...result.missing.map((m) => `"${m}" (缺失)`),
+  ];
+  return parts.join(', ');
+}

package/src/security/redaction.ts

@@ -0,0 +1,101 @@
+/**
+ * 日志/文本脱敏（规范 §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.ts';
+
+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: string; re: RegExp }[] = [
+  { 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: string, re: RegExp, blacklist: readonly string[]): string {
+  return text.replace(re, (match: string, field: string, value: string) => {
+    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: string, blacklist: readonly string[] = []): string {
+  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: unknown, blacklist: readonly string[] = []): unknown {
+  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: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    out[k] = isSensitiveFieldName(k, blacklist) ? REDACTED : redactValue(v, blacklist);
+  }
+  return out;
+}
+
+/** 预编译脱敏器（多次调用复用；blacklist 为附加规范化字段名） */
+export function createRedactor(blacklist: readonly string[] = []): (text: string) => string {
+  const compiled = { json: JSON_FIELD_RE, kv: KV_FIELD_RE, colon: COLON_FIELD_RE };
+  return (text: string): string => {
+    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 };

package/src/security/secret-scanner.ts

@@ -0,0 +1,275 @@
+/**
+ * 敏感字段扫描器（规范 §6 / 设计 §7.2 / core `SecretScanner` 契约的强化实现）。
+ *
+ * 定位：`ctx.settings.describe({redactSecrets:true})` 已剥离 DSH 已知秘密（设计 §7.2），
+ * 本扫描器是**第二道防线**，兜底插件自定义字段、MCP headers、patch config、文件类分区文本。
+ *
+ * 判定策略（两级，避免误伤/漏报）：
+ *  - 字段名：规范化（小写、去 `_-. ` 分隔符）后做「精确命中 / 敏感后缀 / 敏感前缀」三级匹配；
+ *    只剥离**字符串叶值**（对象/数组整体递归，不整块剥离——保证 `credentials: [...]` 状态数组存活）。
+ *  - 引用豁免：`apiKeyEnv` 等「只存引用名」字段、以及形如 `DEEPSEEK_API_KEY` 的全大写环境变量名
+ *    （`isEnvVarName`）一律保留——值是名字不是秘密。
+ *  - 值形状启发式（规范 §6「不能只根据固定字段判断」）：字段名未命中但值长得像 secret
+ *    （sk- / JWT / AKIA / GitHub PAT / PEM 私钥 / Bearer）也剥离；高熵 base64 默认关（误伤率高）。
+ *
+ * 实现不变量：返回 sanitized 为**全新对象**（不改原数据）；迭代式显式栈（防爆栈）+ 深度上限；
+ * 命中记录只含路径与字段名，**值永不外泄**。
+ */
+import { JsonDepthError } from '../utils/json.ts';
+import type { SecretScanner, SensitiveHit } from '../core/types.ts';
+
+/** 剥离占位（与 core defaultSecretScanner 语义一致：空串 = 需补录提示） */
+export const REDACTED_PLACEHOLDER = '';
+
+/**
+ * 敏感字段名单（规范化名：小写、无分隔符）。
+ * 覆盖规范 §6 原始清单 + 设计 §7.2 + core logger 名单，并保持克制以防误伤
+ * （不收录 `key`/`session` 等过宽子串——`sessionIds`/`monkey` 不得中招）。
+ */
+export const DEFAULT_SECRET_FIELD_NAMES: readonly string[] = [
+  // 规范 §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: readonly string[] = [
+  'apikeyenv', 'apikeyname', 'apikeyref',
+  'tokenenv', 'accesstokenenv', 'refreshtokenenv',
+  'clientsecretenv', 'passwordenv', 'secretref', 'credentialref',
+];
+
+/** 敏感后缀（规范化后以这些结尾 → 命中；`key` 故意不收，避免 monkey/whiskey 误伤） */
+const SENSITIVE_SUFFIXES = ['token', 'secret', 'password', 'passwd', 'credential'] as const;
+
+/** 敏感前缀（规范化后以这些开头 → 命中；token/secret 等过宽词不收入） */
+const SENSITIVE_PREFIXES = [
+  'apikey', 'accesstoken', 'refreshtoken', 'authtoken',
+  'clientsecret', 'privatekey', 'authorization', 'authheader',
+  'webhooksecret', 'apisecret',
+] as const;
+
+/** 值形状强模式（默认开）：一眼可辨的密钥/凭据形态（包含式：值内任意位置出现即命中） */
+export interface ValuePattern { name: string; re: RegExp }
+export const SECRET_VALUE_PATTERNS: readonly ValuePattern[] = [
+  { 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,}/ },
+];
+
+export interface SecretScannerOptions {
+  /** 附加敏感字段名（任意原始形态，内部会规范化） */
+  extraFieldNames?: string[];
+  /** 附加引用字段名（规范化后精确命中即豁免） */
+  extraReferenceFields?: string[];
+  /** 值形状启发式开关（默认 true） */
+  valuePatterns?: boolean;
+  /** 高熵长串启发式（默认 false：误伤风险高，需显式开启） */
+  highEntropy?: boolean;
+  /** 最大递归深度（默认 64，与 JSON 深度上限一致） */
+  maxDepth?: number;
+}
+
+/** 规范化字段名：小写 + 去 `_-. ` 分隔符（用于名单匹配） */
+export function normalizeFieldName(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+
+/** 是否为「环境变量名」形态（全大写下划线，如 DEEPSEEK_API_KEY）→ 视为引用名 */
+export function isEnvVarName(value: string): boolean {
+  return /^[A-Z][A-Z0-9_]{2,}$/.test(value);
+}
+
+/** 字段名是否命中敏感名单（规范化后精确 / 敏感后缀 / 敏感前缀） */
+export function isSensitiveFieldName(
+  field: string,
+  extra: readonly string[] = [],
+): boolean {
+  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: string,
+  extra: readonly string[] = [],
+): boolean {
+  const norm = normalizeFieldName(field);
+  return [...DEFAULT_REFERENCE_FIELDS, ...extra].includes(norm);
+}
+
+/** 值是否命中强模式 secret 形状（返回命中模式名；未命中返回 null） */
+export function matchSecretValuePattern(value: string): string | null {
+  for (const p of SECRET_VALUE_PATTERNS) {
+    if (p.re.test(value)) return p.name;
+  }
+  return null;
+}
+
+/** 高熵启发式：长 base64/hex 串且 Shannon 熵高（默认关） */
+function isHighEntropySecret(value: string): boolean {
+  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<string, number>();
+  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;
+}
+
+/** 判定单个「字段名 + 字符串值」：strip | keep（含引用豁免与值形状）
+ * 顺序：值形状优先（AKIA 等全大写 secret 形状不能被 env 名豁免误放）→ 引用字段 → env 名 → 字段名。 */
+function judgeFieldValue(field: string, value: string, opts: Required<Pick<SecretScannerOptions, 'extraFieldNames' | 'extraReferenceFields' | 'valuePatterns' | 'highEntropy'>>): boolean {
+  if (value === '') return false;
+  if (opts.valuePatterns && matchSecretValuePattern(value) !== 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: unknown, opts: SecretScannerOptions = {}): { sanitized: unknown; hits: SensitiveHit[] } {
+  const maxDepth = opts.maxDepth ?? 64;
+  const cfg: Required<Pick<SecretScannerOptions, 'extraFieldNames' | 'extraReferenceFields' | 'valuePatterns' | 'highEntropy'>> = {
+    extraFieldNames: opts.extraFieldNames ?? [],
+    extraReferenceFields: opts.extraReferenceFields ?? [],
+    valuePatterns: opts.valuePatterns ?? true,
+    highEntropy: opts.highEntropy ?? false,
+  };
+  const hits: SensitiveHit[] = [];
+
+  if (data === null || typeof data !== 'object') return { sanitized: data, hits };
+  if (data instanceof Uint8Array) return { sanitized: data, hits };
+
+  const rootOut: unknown = Array.isArray(data) ? [] : {};
+  interface Frame { src: unknown; dst: unknown; path: string; depth: number }
+  const stack: Frame[] = [{ src: data, dst: rootOut, path: '', depth: 1 }];
+  const visited = new WeakSet<object>();
+  visited.add(data as object);
+
+  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 as unknown[];
+      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: unknown = 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 as Record<string, unknown>;
+    for (const [k, v] of Object.entries(src as Record<string, unknown>)) {
+      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: unknown = 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 },
+] as const;
+
+/** 文本级扫描：逐行找「敏感字段名 = 值」与「值形状」命中（只报告，不修改文本） */
+export function scanText(text: string, opts: SecretScannerOptions = {}): SensitiveHit[] {
+  const hits: SensitiveHit[] = [];
+  const extra = opts.extraFieldNames ?? [];
+  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: RegExpExecArray | null;
+      while ((m = re.exec(line)) !== null) {
+        const field = m[1]!;
+        const value = m[2]!;
+        if (!isSensitiveFieldName(field, extra)) continue;
+        if (json) {
+          // JSON 形态下引号内值才报告（引用名豁免由调用方结合场景决定，这里保守报告）
+          hits.push({ path: linePath, field });
+          continue;
+        }
+        if (isEnvVarName(value)) continue; // 引用名不报告
+        hits.push({ path: linePath, field });
+      }
+    }
+    // 值形状（字段名无关）
+    if (valuePatterns) {
+      const trimmed = line.trim();
+      const name = matchSecretValuePattern(trimmed);
+      if (name !== null) hits.push({ path: linePath, field: `(${name})` });
+    }
+  }
+  return hits;
+}
+
+/** 强化版 SecretScanner（对齐 core SecretScanner 契约，可注入 Exporter.scanner） */
+export function createSecretScanner(opts: SecretScannerOptions = {}): SecretScanner {
+  return {
+    scanAndRedact(data: unknown): { sanitized: unknown; hits: SensitiveHit[] } {
+      return scanAndRedact(data, opts);
+    },
+    scanText(text: string): SensitiveHit[] {
+      return scanText(text, opts);
+    },
+  };
+}