@logictan/dsh-config-manager 0.1.60

package/src/security/encryption.ts

@@ -0,0 +1,335 @@
+/**
+ * 凭据加密（规范 §7 / 设计 §7.3 / core `EncryptionProvider` 契约实现，零依赖 node:crypto）。
+ *
+ * 方案：scrypt（KDF）+ AES-256-GCM（AEAD），每次导出 salt/iv 全随机，密码绝不落盘。
+ * secrets.enc 二进制布局（设计 §7.3 细化）：
+ *
+ *   magic "DSC1"(4B) + version(1B) + salt(16B) + iv(12B) + authTag(16B) + ciphertext
+ *
+ * - magic/version 不符 → `UNSUPPORTED_FORMAT`（不是本插件产物 / 版本过新）
+ * - blob 内嵌参数与 manifest 的 EncryptionInfo 不一致 → `TAMPERED`（元数据被篡改）
+ * - GCM 认证失败（密码错误或密文被改） → `BAD_PASSWORD`（提示重输密码或核对备份来源）
+ *
+ * 与 core 契约的关系：
+ * - `createEncryptionProvider(password)` 返回 core `EncryptionProvider`（encrypt 无密码参数，
+ *   闭包持有导出密码；decrypt 用调用方传入的密码 → 支持「换密码解密」）。
+ * - 底层纯函数 encryptCredentials/decryptCredentials 对齐设计 §13.4，供直接调用与测试。
+ * - plaintext 语义：`.credentials.yaml` 文件原文（m5 经 HostContext.fs 文件级读取提供；
+ *   ctx.credentials 永不回读值——研究报告 §3.2 硬约束），本模块只做字节级加解密。
+ */
+import crypto from 'node:crypto';
+import { promisify } from 'node:util';
+import type { EncryptionInfo } from '../schema/types.ts';
+import type { EncryptionProvider } from '../core/types.ts';
+
+const scryptAsync = promisify(crypto.scrypt) as (
+  password: crypto.BinaryLike,
+  salt: crypto.BinaryLike,
+  keylen: number,
+  options: crypto.ScryptOptions,
+) => Promise<Buffer>;
+
+export const SCHEMA_MAGIC = 'DSC1';
+export const SCHEMA_VERSION = 1;
+
+/** 整体加密备份容器的 magic（D C A rchive）：头部布局同 secrets.enc，kdf 参数用默认常量 */
+export const ARCHIVE_MAGIC = 'DCA1';
+export const ARCHIVE_VERSION = 1;
+
+/** 探测字节是否为整体加密备份容器（上传/下载时判定 containerType） */
+export function isArchiveBlob(buf: Uint8Array): boolean {
+  return Buffer.from(buf.subarray(0, 4)).toString('ascii') === ARCHIVE_MAGIC;
+}
+export const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1, keyLength: 32 } as const;
+export const SALT_LENGTH = 16;
+export const IV_LENGTH = 12;
+export const TAG_LENGTH = 16;
+/** magic(4) + version(1) + salt(16) + iv(12) + authTag(16) */
+export const HEADER_LENGTH = 4 + 1 + SALT_LENGTH + IV_LENGTH + TAG_LENGTH;
+
+export type SecurityErrorCode = 'BAD_PASSWORD' | 'TAMPERED' | 'UNSUPPORTED_FORMAT';
+
+export class SecurityError extends Error {
+  readonly code: SecurityErrorCode;
+  constructor(code: SecurityErrorCode, message: string) {
+    super(message);
+    this.name = 'SecurityError';
+    this.code = code;
+  }
+}
+
+/** KDF 参数值域校验（防 manifest 被篡改成超大 N 导致 DoS；非法即拒绝） */
+export function validateKdfParams(params: unknown): params is EncryptionInfo['kdfParams'] {
+  if (params === null || typeof params !== 'object') return false;
+  const p = params as Record<string, unknown>;
+  if (typeof p['N'] !== 'number' || p['N'] < 2 ** 14 || p['N'] > 2 ** 20) return false;
+  if (typeof p['r'] !== 'number' || p['r'] < 1 || p['r'] > 32) return false;
+  if (typeof p['p'] !== 'number' || p['p'] < 1 || p['p'] > 32) return false;
+  return typeof p['keyLength'] === 'number' && p['keyLength'] === 32;
+}
+
+/** 派生密钥（scrypt，参数可来自 manifest；默认常量） */
+export async function deriveKey(
+  password: string,
+  salt: Uint8Array,
+  params: EncryptionInfo['kdfParams'] = SCRYPT_PARAMS,
+): Promise<Buffer> {
+  return scryptAsync(password, salt, params.keyLength, { N: params.N, r: params.r, p: params.p });
+}
+
+/** 加密 .credentials.yaml 原文 → { blob, info }（info 直接进 manifest.security.encryption） */
+export async function encryptCredentials(
+  plaintext: string,
+  password: string,
+): Promise<{ blob: Uint8Array; info: EncryptionInfo }> {
+  if (password === '') throw new SecurityError('BAD_PASSWORD', '加密密码不能为空');
+  // 产品决策（2026-09-13）：加密**不做任何密码强度校验**——用户提供的任何密码都必须可用。
+  // 请勿在此重新加入强度闸门；用户自定的密码策略不由本插件约束。
+  const salt = crypto.randomBytes(SALT_LENGTH);
+  const iv = crypto.randomBytes(IV_LENGTH);
+  const key = await deriveKey(password, salt);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+
+  const header = Buffer.alloc(HEADER_LENGTH);
+  header.write(SCHEMA_MAGIC, 0, 'ascii');
+  header[4] = SCHEMA_VERSION;
+  salt.copy(header, 5);
+  iv.copy(header, 5 + SALT_LENGTH);
+  authTag.copy(header, 5 + SALT_LENGTH + IV_LENGTH);
+
+  const info: EncryptionInfo = {
+    algorithm: 'aes-256-gcm',
+    kdf: 'scrypt',
+    kdfParams: { ...SCRYPT_PARAMS },
+    salt: salt.toString('base64'),
+    iv: iv.toString('base64'),
+    authTag: authTag.toString('base64'),
+    version: SCHEMA_VERSION,
+  };
+  return { blob: Buffer.concat([header, encrypted]), info };
+}
+
+/** 解密 secrets.enc（authTag 校验失败抛 BAD_PASSWORD；元数据不一致抛 TAMPERED） */
+export async function decryptCredentials(
+  blob: Uint8Array,
+  info: EncryptionInfo,
+  password: string,
+): Promise<string> {
+  if (blob.length < HEADER_LENGTH) {
+    throw new SecurityError('TAMPERED', 'secrets.enc 体积过小（截断或损坏）');
+  }
+  const magic = Buffer.from(blob.subarray(0, 4)).toString('ascii');
+  if (magic !== SCHEMA_MAGIC) {
+    throw new SecurityError('UNSUPPORTED_FORMAT', `未知文件格式 magic "${magic}"，不是本插件产物`);
+  }
+  const version = blob[4]!;
+  if (version !== SCHEMA_VERSION) {
+    throw new SecurityError('UNSUPPORTED_FORMAT', `不支持的 secrets.enc 版本 ${version}`);
+  }
+  if (info.algorithm !== 'aes-256-gcm' || info.kdf !== 'scrypt' || !validateKdfParams(info.kdfParams)) {
+    throw new SecurityError('UNSUPPORTED_FORMAT', 'manifest 加密参数非法或不受支持');
+  }
+
+  const blobSalt = blob.subarray(5, 5 + SALT_LENGTH);
+  const blobIv = blob.subarray(5 + SALT_LENGTH, 5 + SALT_LENGTH + IV_LENGTH);
+  const blobTag = blob.subarray(5 + SALT_LENGTH + IV_LENGTH, HEADER_LENGTH);
+  if (
+    info.salt !== Buffer.from(blobSalt).toString('base64') ||
+    info.iv !== Buffer.from(blobIv).toString('base64') ||
+    info.authTag !== Buffer.from(blobTag).toString('base64')
+  ) {
+    throw new SecurityError('TAMPERED', 'secrets.enc 与 manifest 加密参数不一致（可能被篡改）');
+  }
+
+  let key: Buffer;
+  try {
+    key = await deriveKey(password, blobSalt, info.kdfParams);
+  } catch (err) {
+    throw new SecurityError('BAD_PASSWORD', `密钥派生失败: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, blobIv);
+  decipher.setAuthTag(blobTag);
+  try {
+    const decrypted = Buffer.concat([
+      decipher.update(blob.subarray(HEADER_LENGTH)),
+      decipher.final(),
+    ]);
+    return decrypted.toString('utf8');
+  } catch {
+    throw new SecurityError('BAD_PASSWORD', '解密认证失败：密码错误或密文被篡改');
+  }
+}
+
+/**
+ * 创建 core `EncryptionProvider`（对齐 core/types.ts 契约）。
+ * encrypt 使用闭包持有密码；decrypt 使用调用方传入的密码（支持换密码解密）。
+ */
+export function createEncryptionProvider(password: string): EncryptionProvider {
+  return {
+    async encrypt(plaintext: string): Promise<{ blob: Uint8Array; info: EncryptionInfo }> {
+      return encryptCredentials(plaintext, password);
+    },
+    async decrypt(blob: Uint8Array, info: EncryptionInfo, pw: string): Promise<string> {
+      return decryptCredentials(blob, info, pw);
+    },
+  };
+}
+
+/* ---------------- 整体备份容器加密（§7.4：加密整个 ZIP，而非仅 secrets） ---------------- */
+
+/**
+ * 加密完整 ZIP 字节 → 加密容器 blob。
+ *
+ * 布局（DCA1，与 secrets.enc 同构，kdf 参数用默认常量）：
+ *   magic "DCA1"(4B) + version(1B) + salt(16B) + iv(12B) + authTag(16B) + ciphertext(plainZIP)
+ *
+ * 语义：整个备份（manifest / 各分区 JSON / sessions / 插件文件 / secrets.enc……）
+ * 全部进入 ciphertext，磁盘上无法看到任何明文内容。verifyEncryptedBlob 用于
+ * 校验密码正确（GCM authTag 通过）且返回真实解密用的随机参数。
+ */
+export async function encryptArchive(
+  plainZip: Uint8Array,
+  password: string,
+): Promise<{ blob: Uint8Array; info: EncryptionInfo; kdf: { salt: Buffer; iv: Buffer } }> {
+  if (password === '') throw new SecurityError('BAD_PASSWORD', '加密密码不能为空');
+  // 产品决策（2026-09-13）：加密**不做任何密码强度校验**——用户提供的任何密码都必须可用。
+  // 请勿在此重新加入强度闸门；用户自定的密码策略不由本插件约束。
+  const salt = crypto.randomBytes(SALT_LENGTH);
+  const iv = crypto.randomBytes(IV_LENGTH);
+  const key = await deriveKey(password, salt);
+  const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);
+  const encrypted = Buffer.concat([cipher.update(plainZip), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+
+  const header = Buffer.alloc(HEADER_LENGTH);
+  header.write(ARCHIVE_MAGIC, 0, 'ascii');
+  header[4] = ARCHIVE_VERSION;
+  salt.copy(header, 5);
+  iv.copy(header, 5 + SALT_LENGTH);
+  authTag.copy(header, 5 + SALT_LENGTH + IV_LENGTH);
+
+  const info: EncryptionInfo = {
+    algorithm: 'aes-256-gcm',
+    kdf: 'scrypt',
+    kdfParams: { ...SCRYPT_PARAMS },
+    salt: salt.toString('base64'),
+    iv: iv.toString('base64'),
+    authTag: authTag.toString('base64'),
+    version: ARCHIVE_VERSION,
+  };
+  return { blob: Buffer.concat([header, encrypted]), info, kdf: { salt, iv } };
+}
+
+/** 容器版解密：用「先验真实参数」校验密码并解密（—— 调用方必须先用 verifyEncryptedBlob 拿到 info/kdf） */
+export async function decryptArchive(
+  blob: Uint8Array,
+  info: EncryptionInfo,
+  kdfParam: { salt: Buffer; iv: Buffer },
+  password: string,
+): Promise<Uint8Array> {
+  if (blob.length < HEADER_LENGTH) {
+    throw new SecurityError('TAMPERED', '加密备份容器体积过小（截断或损坏）');
+  }
+  const magic = Buffer.from(blob.subarray(0, 4)).toString('ascii');
+  if (magic !== ARCHIVE_MAGIC) {
+    throw new SecurityError('UNSUPPORTED_FORMAT', `未知文件格式 magic "${magic}"，不是本插件产物`);
+  }
+  const version = blob[4]!;
+  if (version !== ARCHIVE_VERSION) {
+    throw new SecurityError('UNSUPPORTED_FORMAT', `不支持的加密备份版本 ${version}`);
+  }
+  const blobSalt = Buffer.from(blob.subarray(5, 5 + SALT_LENGTH));
+  const blobIv = Buffer.from(blob.subarray(5 + SALT_LENGTH, 5 + SALT_LENGTH + IV_LENGTH));
+  const blobTag = Buffer.from(blob.subarray(5 + SALT_LENGTH + IV_LENGTH, HEADER_LENGTH));
+  const paramSalt = Buffer.isBuffer(kdfParam.salt) ? kdfParam.salt : Buffer.from(kdfParam.salt);
+  const paramIv = Buffer.isBuffer(kdfParam.iv) ? kdfParam.iv : Buffer.from(kdfParam.iv);
+  // 与此时真实的随机参数对齐（参数来自 verify 阶段读取，防调用方换参数）
+  if (
+    !blobSalt.equals(paramSalt) ||
+    !blobIv.equals(paramIv)
+  ) {
+    throw new SecurityError('TAMPERED', '加密备份参数不一致（可能被篡改）');
+  }
+
+  let key: Buffer;
+  try {
+    key = await deriveKey(password, blobSalt, info.kdfParams);
+  } catch (err) {
+    throw new SecurityError('BAD_PASSWORD', `密钥派生失败: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, blobIv);
+  decipher.setAuthTag(blobTag);
+  try {
+    return Buffer.concat([
+      decipher.update(blob.subarray(HEADER_LENGTH)),
+      decipher.final(),
+    ]);
+  } catch {
+    throw new SecurityError('BAD_PASSWORD', '解密认证失败：密码错误或密文被篡改');
+  }
+}
+
+export interface EncryptedBlobInfo {
+  /** 容器是否合法（magic/version/header 校验通过） */
+  valid: boolean;
+  /** 密码是否正确（GCM authTag 认证通过）；valid=false 时恒 false */
+  ok: boolean;
+  /** 解密所需参数（valid && ok 时有效；用默认常量派生 key） */
+  info: EncryptionInfo | null;
+  kdf: { salt: Buffer; iv: Buffer } | null;
+  /** 错误码（供上层转用户可读错误）：BAD_PASSWORD / TAMPERED / UNSUPPORTED_FORMAT */
+  code: SecurityErrorCode | null;
+}
+
+/**
+ * 校验加密备份容器并验证密码（只读，零解密返回内容）。
+ * - 容器不合法（非 DCA1 / 截断 / 参数异常）→ valid=false + code
+ * - 密码正确 → ok=true + 返回随机参数（后续 decryptArchive 用之）
+ * - 密码错误 → ok=false + code=BAD_PASSWORD
+ */
+export async function verifyEncryptedBlob(
+  blob: Uint8Array,
+  password: string,
+): Promise<EncryptedBlobInfo> {
+  if (blob.length < HEADER_LENGTH) {
+    return { valid: false, ok: false, info: null, kdf: null, code: 'TAMPERED' };
+  }
+  const magic = Buffer.from(blob.subarray(0, 4)).toString('ascii');
+  if (magic !== ARCHIVE_MAGIC) {
+    return { valid: false, ok: false, info: null, kdf: null, code: 'UNSUPPORTED_FORMAT' };
+  }
+  const version = blob[4]!;
+  if (version !== ARCHIVE_VERSION) {
+    return { valid: false, ok: false, info: null, kdf: null, code: 'UNSUPPORTED_FORMAT' };
+  }
+  const salt = Buffer.from(blob.subarray(5, 5 + SALT_LENGTH));
+  const iv = Buffer.from(blob.subarray(5 + SALT_LENGTH, 5 + SALT_LENGTH + IV_LENGTH));
+  const tag = Buffer.from(blob.subarray(5 + SALT_LENGTH + IV_LENGTH, HEADER_LENGTH));
+  const info: EncryptionInfo = {
+    algorithm: 'aes-256-gcm',
+    kdf: 'scrypt',
+    kdfParams: { ...SCRYPT_PARAMS },
+    salt: salt.toString('base64'),
+    iv: iv.toString('base64'),
+    authTag: tag.toString('base64'),
+    version: ARCHIVE_VERSION,
+  };
+  let key: Buffer;
+  try {
+    key = await deriveKey(password, salt, info.kdfParams);
+  } catch (err) {
+    return { valid: true, ok: false, info, kdf: { salt, iv }, code: 'BAD_PASSWORD' };
+  }
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);
+  decipher.setAuthTag(tag);
+  try {
+    decipher.update(blob.subarray(HEADER_LENGTH));
+    decipher.final();
+  } catch {
+    return { valid: true, ok: false, info, kdf: { salt, iv }, code: 'BAD_PASSWORD' };
+  }
+  return { valid: true, ok: true, info, kdf: { salt, iv }, code: null };
+}

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 };