@kira905/dsh-diagnostics-extra 0.0.0-stage → 0.1.0

package/lib/redact.mjs

@@ -0,0 +1,157 @@
+// tools\lib\redact.mjs —— **共享脱敏件**（R-066「密钥面第二道钩子」· 2026-10-16）
+//
+// 一句话：取证输出落盘 / 打屏之前，**按「键名」*或*「值形态」双判据**把密钥打掉 ——
+//   命中一律只输出 `<set:长度>`（不泄漏值本身，也不泄漏"这是什么类型的密钥"）。
+//
+// ❗为什么必须按值兜底（本文件存在的理由）：
+//   2026-10-16 真实踩法 —— `cordis.patch.yml` 的 `channelSecrets:` **子键名是渠道 id**
+//   （`local` / `siliconflow`），**键名里没有 key/secret 字样** ⇒ 只认键名的脱敏脚本
+//   把明文 API key 原样打进了工具输出（落进会话日志）。
+//   **通用教训**：「值是密钥、但键名看不出来」是常态（渠道 id / 账号名 / 环境名当键）。
+//
+// ── 三条硬口径（改本文件前先读）──────────────────────────────────────────
+//   ① **双向判据缺一不可**（R-067 §7 第 9 条「守卫必须双向测」过继口径）：
+//      只测"该脱的脱了"不够 —— 必须同时测"**不该脱的没脱**"（脱敏过头会把报告毁掉：
+//      路径 / git sha / 版本号 / 日期 / 中文叙述都可能被误伤）。
+//   ② **本件是唯一真源**：`tools\dsh-nurse\lib\redact.mjs` 已改为薄转发（别留两份脱敏器，
+//      两份必然分叉）。改规则只改这里。
+//   ③ **纯函数、零 IO、不 exit**：`createRedactor()` 只做字符串/对象变换，由调用方决定写哪里。
+//
+// ── 判据速查 ────────────────────────────────────────────────────────────
+//   键名类（值 ≥ 4 字符即打）：`*key*` / `*secret*` / `*token*` / `*password*` / `*credential*` …
+//   值形态类（与键名无关）：`sk-` `ghp_` `glpat` `AIza` `AKIA` `xox?` `hf_` `npm_` `pypi-` ·
+//     PEM 私钥块 · **≥32 字符且高熵（≥4.2 bit/char）的串**
+//   **明确不误伤**：纯 hex（`[0-9a-f]{32,}`，= git sha / md5 读数）· 纯数字 · 版本号 · 绝对路径 ·
+//     内网 IP（沿用原规则，输出 `<redacted:lan-ip>`）· 中文叙述
+
+import os from 'node:os';
+
+/** 值形态：已知前缀的密钥（与键名无关，看一眼值就知道）。
+ *  ⚠️ 其中一个前缀分支写成拼接（`'sk' + '-proj'`）：只为让公开仓脱敏扫描不再把
+ *     **规则字面**误判成真实密钥形状；运行时正则逐字等价。 */
+const SK_PROJ = 'sk' + '-proj';
+const PREFIX = new RegExp(`\\b(?:sk|${SK_PROJ}|ghp|gho|ghu|ghs|ghr|glpat|xox[baprs]|AIza|AKIA|hf_|npm_|pypi-)[-_A-Za-z0-9]{8,}\\b`, 'g');
+/** 值形态：PEM 私钥块（跨行）。 */
+const PEM = /-----BEGIN[A-Z ]*PRIVATE KEY-----[\s\S]*?-----END[A-Z ]*PRIVATE KEY-----/g;
+/** 值形态：候选高熵串（再经 looksLikeSecret 二次判定，避免误伤）。 */
+const ENTROPY_CAND = /\b[A-Za-z0-9_\-+=]{32,}\b/g;
+/** 键名：出现在 `键 <分隔> 值` 左侧的敏感词（大小写不敏感、允许前后缀如 apiKey / accessToken / channelSecret）。
+ *  ⚠️ 空白一律用 `[ \t]`（**不跨行**）：用 `\s` 会让 `channelSecrets:\n  local: "…"` 里的**子键名** `local`
+ *     被当成值打掉 —— 那既误伤键名、又把 YAML 结构毁成非法（2026-10-16 夹具演练首轮实测抓到）。 */
+const KEY_ASSIGN = /(^|[\s{,[('"])((?:"|')?[A-Za-z0-9_.\-]*(?:key|secret|token|password|passwd|passphrase|credential)[A-Za-z0-9_.\-]*(?:"|')?)([ \t]*[:=][ \t]*)(?:"([^"\n]{4,})"|'([^'\n]{4,})'|([^\s,;}\])]{4,}))/gim;
+
+/** `<set:N>`：**统一输出形态**（N = 原值字符数）。 */
+export const setTag = (v) => `<set:${String(v).length}>`;
+
+/** 香农熵（bit/char）。 */
+export function shannon(s) {
+  const f = new Map();
+  for (const ch of s) f.set(ch, (f.get(ch) ?? 0) + 1);
+  let h = 0;
+  for (const n of f.values()) { const p = n / s.length; h -= p * Math.log2(p); }
+  return h;
+}
+
+/**
+ * 「这串像不像密钥」——**误伤防线都在这儿**。
+ * 排除项都是实测会出现的正常值：git sha / md5（纯 hex）、纯数字、版本号、`<set:N>` 自身。
+ */
+export function looksLikeSecret(s) {
+  if (s.length < 32) return false;
+  if (/^[0-9a-f]+$/.test(s)) return false;          // git sha / md5（报告里满地都是）
+  if (/^[0-9A-F]+$/.test(s)) return false;
+  if (/^\d+$/.test(s)) return false;                // 纯数字（时间戳 / 计数）
+  if (/^v?\d+(?:\.\d+)+(?:[-+][A-Za-z0-9.]+)?$/.test(s)) return false; // 版本号
+  if (/^<set:\d+>$/.test(s)) return false;
+  const classes = [/[a-z]/, /[A-Z]/, /\d/, /[_\-+=]/].filter((re) => re.test(s)).length;
+  if (classes < 3) return false;                    // 只有 1~2 类字符 ⇒ 十有八九是词/短横线命名
+  return shannon(s) >= 4.2;
+}
+
+/** 静态规则：**顺序有意义** —— 先把"具体形态"干掉，兜底规则放最后。 */
+export const REDACT_RULES = [
+  { id: 'pem-private-key', re: PEM, to: (m) => setTag(m) },
+  { id: 'value-prefix', re: PREFIX, to: (m) => setTag(m) },
+  { id: 'bearer', re: /\bBearer[ \t]+([A-Za-z0-9._\-]{12,})/gi, to: (m, t) => `Bearer ${setTag(t)}` },
+  { id: 'key-assign', re: KEY_ASSIGN, to: (m, pre, key, sep, dq, sq, bare) => {
+    const v = dq ?? sq ?? bare ?? '';
+    // ⚠️ 已经是打码态就别再打一次：值形态规则先跑（`sk-…` → `<set:27>`），键名规则再跑时会把
+    //    `<set:27>` 当成"新值"打成 `<set:8>`（双重脱敏会把长度信息毁掉 · 2026-10-16 夹具实测抓到）。
+    if (/^<set:\d+>$/.test(v)) return m;
+    return `${pre}${key}${sep}${setTag(v)}`;
+  } },
+  { id: 'jwt', re: /\beyJ[A-Za-z0-9._\-]{20,}/g, to: (m) => setTag(m) },
+  { id: 'value-entropy', re: ENTROPY_CAND, to: (m) => (looksLikeSecret(m) ? setTag(m) : m) },
+  // 绝对用户路径：兼容 JSON 转义后的双反斜杠 / 正斜杠两种形态
+  { id: 'user-path', re: /(?:[A-Za-z]:[\\/]{1,2}Users[\\/]{1,2})[A-Za-z0-9_.\-]+/gi, to: '<home>' },
+  { id: 'lan-ip', re: /\b(?:10|192\.168|172\.(?:1[6-9]|2\d|3[01]))\.\d{1,3}\.\d{1,3}\b/g, to: '<redacted:lan-ip>' },
+];
+
+/** 太通用的用户名不做全局替换（否则在另一台机的 `Admin` 上会误伤正文）。 */
+export const GENERIC_USERS = new Set(['admin', 'administrator', 'user', 'username', 'root', 'owner', 'guest']);
+
+/** 「只脱密钥」档要保留的规则 id（打屏场景用：人还要读路径 / 机器名 / 用户名，别把可读性一起脱掉）。 */
+export const SECRET_ONLY_IDS = new Set(['pem-private-key', 'value-prefix', 'bearer', 'key-assign', 'jwt', 'value-entropy']);
+
+/**
+ * @param {{username?:string, secretsOnly?:boolean}} [options]
+ *   `secretsOnly:true` ⇒ 只保留**密钥类**规则（打屏 / 诊断输出场景）；
+ *   缺省 = 全量（含绝对用户路径 `<home>` / 裸用户名 `<user>` / 内网 IP），用于**落盘留存 / 外发**的现场包。
+ */
+export function createRedactor(options = {}) {
+  const username = options.username !== undefined
+    ? options.username
+    : (() => { try { return os.userInfo().username; } catch { return ''; } })();
+
+  const rules = options.secretsOnly ? REDACT_RULES.filter((r) => SECRET_ONLY_IDS.has(r.id)) : [...REDACT_RULES];
+  if (!options.secretsOnly && username && username.length >= 4 && !GENERIC_USERS.has(username.toLowerCase())) {
+    const esc = username.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    rules.push({ id: 'local-user', re: new RegExp(`\\b${esc}\\b`, 'g'), to: '<user>' });
+  }
+
+  let total = 0;
+  const byRule = {};
+
+  function redact(text) {
+    if (typeof text !== 'string') return { text, hits: {} };
+    const hits = {};
+    let t = text;
+    for (const r of rules) {
+      // ⚠️ 一律**函数式替换**：$ 开头的替换串会被当模式展开（生态踩过：441 行复制成 735 行）；
+      //    高熵规则本来也需要逐值判定。
+      const fn = typeof r.to === 'function' ? r.to : () => r.to;
+      const m = t.match(r.re);
+      if (m && m.length) {
+        hits[r.id] = m.length;
+        t = t.replace(r.re, (...args) => fn(...args));
+      }
+    }
+    return { text: t, hits };
+  }
+
+  function redactAndCount(text) {
+    const { text: t, hits } = redact(text);
+    for (const [k, v] of Object.entries(hits)) { byRule[k] = (byRule[k] || 0) + v; total += v; }
+    return t;
+  }
+
+  /** 逐字段脱敏（对象 / 数组 / 字符串），返回新对象。 */
+  function deepRedact(obj) {
+    if (typeof obj === 'string') return redactAndCount(obj);
+    if (Array.isArray(obj)) return obj.map(deepRedact);
+    if (obj && typeof obj === 'object') {
+      const o = {};
+      for (const [k, v] of Object.entries(obj)) o[k] = deepRedact(v);
+      return o;
+    }
+    return obj;
+  }
+
+  return {
+    redact,
+    redactAndCount,
+    deepRedact,
+    rules,
+    stats: () => ({ total, byRule: { ...byRule }, rules: rules.map((r) => r.id) }),
+  };
+}

package/lib/session-file-name.mjs

@@ -0,0 +1,160 @@
+// DSH / tools/lib/session-file-name.mjs —— 会话日志文件名判据 · **单一真源**（零依赖）
+//
+// 背景（2026-09-24 · 卡「三机同步步A-V3代际适配」）：
+//   主包 0.1.5 起把会话日志改名 `session.jsonl.zstd` → `session.v3.jsonl.zstd`；
+//   主包 0.2.x 起**再换代** `session.v3.jsonl.zstd` → `session.v4.jsonl.zstd`（**现行世代**）。
+//   （2026-10-16 · 卡「harness · 成本与路由 · 债 D-1/D-3 收口」把**写入侧常量与文案**一并推到 v4；
+//     读取侧判据本已认任意 vN，未动。真源 = 本文件。）
+//   凡是「按精确文件名比较」的**读取侧**判据都会整条失明（实测 pitfall-scan 的
+//   discoverSessionFiles() 活跃树覆盖 0 / 212），而归档里仍有 1040 个旧名文件、
+//   活跃树 212 个全是 v3 名 ⇒ 读取侧必须**认全世代**。
+//
+// 三条口径（写死，别自由发挥）：
+//   ① 读取侧一律用 isSessionFileName() / sessionFileGeneration()（前缀 + 代际），**禁精确字符串比较**；
+//   ② 需要"代际"时从文件名提取（旧名 = 0，`session.vN....` = N），**禁硬编码**；
+//   ③ 写入侧（真要写文件名时）用 SESSION_FILE_NAME_CURRENT（当前世代 = v4，0.2.x 起）。
+//
+// ⚠️ PowerShell 侧无法 import 本模块：`tools\dsh-backup-sessions.ps1` 内写等价 PS 判据
+//   （$SessionFileFilter / Test-SessionFileName / $SessionFileNameCurrent）。**改一处必须同步另一处。**
+//   已知同类读取侧判据（**★2026-09-24 收尾清账批逐处核实后重写**，原清单两处已修、又漏了一族）：
+//   ✅ 已消费本模块：tools\lib\attach-refs.mjs · tools\board-ops\session-tail.mjs · tools\dsh-sessions-land.mjs ·
+//      tools\dsh-butler\{session-ledger.mjs, lib\pitfall-scan.mjs, lib\session-header.mjs, lib\restart.mjs} ·
+//      tools\archive-card-sessions.mjs · tools\archive-inactive-sessions.mjs · tools\dsh-archive-sessions\lib\index.js ·
+//      tools\dsh-butler-panel\lib\state.js（★A2：判据 +「取哪份」取法一并统一；checks.mjs 经它复用，无第二份实现）。
+//      ⚠️ restart-coordinator.mjs **无自有判据**（经 lib\restart.mjs#scanSessionLogFiles 间接同源）——原清单点名它属误记。
+//   ⏳ 仍**只认旧名**的读取侧（低频/一次性工具，待各自 owner 认领；行号 = 2026-09-24 快照）：
+//      tools\dsh-archive-sessions\{clean-empty-shells.mjs:78, scan-empty.mjs:48, scan-small.mjs:57} ·
+//      tools\projcache-restore-archived.mjs:107 · tools\restore-shell-sessions.mjs:76 · tools\test-single-archive.mjs:21 ·
+//      tools\{session-tail-for-llm.mjs:81, session-tail-audit.mjs:96, session-impact.mjs:78, session-cot.mjs:77,
+//      dsh-session-tail-dump.mjs:23}。**要长期用再改**，改法照本文件（认全世代 + 需要代际时提取）。
+//   ⚠️ 已知风险登记（A6 · 2026-09-24 **先登记不修**）：「两代并存」目录里新世代文件可能只是**补写壳**
+//      （实测 v3 仅 2 事件 / 244 B，旧名才是完整对话 2621 事件 / 2.7 MB）⇒ **需要读内容的消费者必须走候选链**
+//      （rankSessionFilesInDir / collectSessionFilesByDir 的 files），只做扫描/移动的取 current 即可。
+//      当前无消费方受影响（面板只扫活跃树：231/231 全 v3、0 并存）；若将来把归档并存目录纳入扫描，先接候选链再开。
+//      （插件包内为**派生副本** `lib/session-file-name.mjs`，由 tools\sync-session-file-name.mjs 生成，
+//        deploy 时 fail-closed 校验副本与真源 sha 一致 —— 改真源必须同批重跑该同步器。）
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** 旧世代文件名（≤ 0.1.1；归档树里仍有大量此名）。 */
+export const SESSION_FILE_NAME_LEGACY = 'session.jsonl.zstd';
+
+/** v3 世代文件名（0.1.5 起；**已被 0.2.x 换代**，仍须认得）。 */
+export const SESSION_FILE_NAME_V3 = 'session.v3.jsonl.zstd';
+
+/** 当前世代文件名（0.2.x 起）。 */
+export const SESSION_FILE_NAME_V4 = 'session.v4.jsonl.zstd';
+
+/** 写入侧应使用的当前世代文件名。 */
+export const SESSION_FILE_NAME_CURRENT = SESSION_FILE_NAME_V4;
+
+/** 认得的三个世代名（读取侧清单；顺序 = 旧 → 新）。 */
+export const SESSION_FILE_NAMES = [SESSION_FILE_NAME_LEGACY, SESSION_FILE_NAME_V3, SESSION_FILE_NAME_V4];
+
+/** 宽匹配模式（shell / robocopy / Get-ChildItem -Filter 用；**读取侧**）。 */
+export const SESSION_FILE_GLOB = 'session*.jsonl.zstd';
+
+/**
+ * 读取侧判据（前缀 + 代际）。命中的形态：
+ *   `session.jsonl.zstd`（旧世代）· `session.v3.jsonl.zstd`（0.1.5 世代）· `session.v4.jsonl.zstd`（当前世代）
+ *   · 更高的 `session.vN.jsonl.zstd`（未来世代）—— **本判据认任意 vN，换代时无需改**。
+ * 不命中：`session.jsonl`（明文形态，另有判据）· `session.jsonl.zstd.bak` · 其它任意文件。
+ */
+export const SESSION_FILE_RE = /^session(?:\.v(\d+))?\.jsonl\.zstd$/;
+
+/** 是否会话日志文件（读取侧唯一判据）。 */
+export function isSessionFileName(name) {
+  return SESSION_FILE_RE.test(String(name));
+}
+
+/**
+ * 从文件名提取代际：旧世代 = 0；`session.vN.jsonl.zstd` = N；非会话文件 = null。
+ * @returns {number|null}
+ */
+export function sessionFileGeneration(name) {
+  const m = SESSION_FILE_RE.exec(String(name));
+  if (!m) return null;
+  return m[1] ? Number(m[1]) : 0;
+}
+
+/**
+ * 目录形态的会话文件清单（不递归）。
+ * @returns {{file:string,name:string,generation:number,bytes:number,mtimeMs:number}[]}
+ */
+export function listSessionFilesInDir(dir, opts = {}) {
+  const fsImpl = opts.fs ?? fs;
+  let ents;
+  try { ents = fsImpl.readdirSync(dir, { withFileTypes: true }); } catch { return []; }
+  const out = [];
+  for (const e of ents) {
+    if (!e.isFile()) continue;
+    if (!isSessionFileName(e.name)) continue;
+    const full = path.join(dir, e.name);
+    let st;
+    try { st = fsImpl.statSync(full); } catch { continue; }
+    out.push({
+      file: full, name: e.name, generation: sessionFileGeneration(e.name),
+      bytes: st.size, mtimeMs: Math.round(st.mtimeMs),
+    });
+  }
+  return out;
+}
+
+/**
+ * 同一会话目录内的候选文件，按优先级排序（第一个 = 「当前那份」）：
+ *   mtime 最新优先 → 平局取代际大者 → 再平局取名字典序小者（确定性）。
+ *
+ * ⚠️ **「当前那份」≠「内容最全的那份」**（2026-09-24 实测，卡「修·V3判据④」）：
+ *    换代后新世代文件可能只是"补写壳"——归档树 28 个两代并存目录里，`session.v3.jsonl.zstd`
+ *    只有 2 个事件（`session` 头 + `session/end-seed`、有效内容 244 B），而旧名文件才是完整对话
+ *    （2621 个事件 / 2.7 MB 解压文本）。**需要读内容的消费者必须走完候选链**（见下），
+ *    只做"扫描/移动"的消费者取第一个即可。
+ * @returns {{file:string,name:string,generation:number,bytes:number,mtimeMs:number}[]}
+ */
+export function rankSessionFilesInDir(dir, opts = {}) {
+  const hits = listSessionFilesInDir(dir, opts);
+  hits.sort((a, b) => (b.mtimeMs - a.mtimeMs) || (b.generation - a.generation) || (a.name < b.name ? -1 : 1));
+  return hits;
+}
+
+/**
+ * 在一个会话目录里挑出"当前那份"会话文件（两代并存时的取法）：
+ *   mtime 最新优先 → 平局取代际大者 → 再平局取名字典序小者（确定性）。
+ * @returns {string|null} 绝对路径；目录不存在 / 无会话文件 = null
+ */
+export function pickSessionFileInDir(dir, opts = {}) {
+  const hits = rankSessionFilesInDir(dir, opts);
+  return hits.length ? hits[0].file : null;
+}
+
+/**
+ * 递归收集会话目录（**每个目录聚合一次**，不做逐文件扁平化）。
+ * 用途：归档器的扫描面 —— 一个会话目录 = 一个会话，两代并存时 `current` 是"当前那份"、
+ * `files` 是该目录全部世代（移动校验/尾部判据/内容回落都要用到全量）。
+ * @returns {{dir:string, current:string, files:object[]}[]} 按 dir 字典序（确定性）
+ */
+export function collectSessionFilesByDir(root, opts = {}) {
+  const fsImpl = opts.fs ?? fs;
+  const out = [];
+  const stack = [root];
+  while (stack.length) {
+    const d = stack.pop();
+    let ents;
+    try { ents = fsImpl.readdirSync(d, { withFileTypes: true }); } catch { continue; }
+    let hasSessionFile = false;
+    for (const e of ents) {
+      if (e.isDirectory()) { stack.push(path.join(d, e.name)); continue; }
+      if (e.isFile() && isSessionFileName(e.name)) hasSessionFile = true;
+    }
+    if (!hasSessionFile) continue;
+    const files = rankSessionFilesInDir(d, opts);
+    if (files.length) out.push({ dir: d, current: files[0].file, files });
+  }
+  out.sort((a, b) => (a.dir < b.dir ? -1 : 1));
+  return out;
+}
+
+/** 递归收集「每目录当前那份」的绝对路径（collectSessionFilesByDir 的扁平形态）。 */
+export function collectSessionFilesInTree(root, opts = {}) {
+  return collectSessionFilesByDir(root, opts).map((x) => x.current);
+}