crypto-hallucination-detector 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# crypto-hallucination-detector
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+启发式静态检测器：标记「AI 易编造 / 易漏」的密码代码风险模式。
+
+## 定位
+
+**不是**漏洞扫描器，**不是** AST 解析器。它基于轻量结构扫描（字符串掩码 + 括号配平）识别需人工核验的**气味信号**：
+
+- **侧信道味道**：秘密相关分支 / 数组下标使用秘密 / switch-on-secret / 声明定常却非定常
+- **伪造 API**：AI 常编造的伪 noble / WebCrypto 命名（如 `noble.kem.mlkem`、`crypto.subtle.mlkem`）
+- **测试覆盖**：有实现但缺对应测试文件
+- **非定常比较**：对秘密值用 `!= / ===` 而非 ct-equal
+
+每条 finding 给出 file/line/severity/justification，**绝不宣判漏洞**——输出是 `needs-human-review`，由人定夺。
+
+## 运行
+
+```bash
+npm test                  # 自带样本验证（命中幻觉模式 + 不误报良好代码）
+node src/cli.js <dir>     # 扫描目录
+node src/cli.js <dir> --fail-on high   # CI 门禁：存在 >=high 的 finding 则退出码 1
+```
+
+`--fail-on <low|medium|high>` 让 CLI 在存在「该级别及以上」的 finding 时以退出码 1 失败（可作 CI 门禁）；缺参或非法值退出码 2。注意：`api-misuse` / `domain-params` / `test-coverage` 三类 finding 没有 `severity` 字段，统一按 `medium` 归并——所以 `--fail-on high` 会放过 `medium` 级 finding（含这三类）；若要连这三类一起拦截，用 `--fail-on low`。
+
+## 架构
+
+| 文件 | 职责 |
+|---|---|
+| `src/ast-scanner.js` | 零依赖结构扫描：注释 / 调用 / 分支 / 函数 / 秘密变量传播 |
+| `src/pattern-scanner.js` | 基于 ast 的启发式模式匹配（侧信道味道） |
+| `src/api-misuse.js` | 伪 API 白名单+可疑命名检测 |
+| `src/test-coverage.js` | 测试文件覆盖检查 |
+| `src/constant-time.js` | 聚合侧信道相关 finding |
+| `src/index.js` | 统一入口（聚合输出结构化报告） |
+| `src/cli.js` | 命令行入口 |
+
+## 关键纪律（对应 FIBEMATE 工程纪律）
+
+- **API 白名单不是真理**：`api-misuse.js` 的白名单针对 FIBEMATE 技术栈，**任何新项目使用前须按自家依赖核实**（"不拿推测当事实"的代码化）。
+- **零外部依赖**：不引入 acorn/esprima，避免把"完整 AST"当承诺；掩码扫描是启发式，定位透明。
+- **不误报优先**：良样本 `sample.good.js` 必须零 finding，测试守护此约束。
+
+## 已知局限
+
+- 启发式，可能漏报（混淆写法）或误报（字符串里恰好出现模式）；输出供人复核。
+- 不解析语言语义，仅结构特征。生产集成建议作为 PR 非阻塞检查。

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "crypto-hallucination-detector",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Heuristic static detector for AI-hallucinated or side-channel-unsafe crypto patterns",
+  "main": "src/index.js",
+  "bin": { "crypto-hallucination-detector": "src/cli.js" },
+  "scripts": {
+    "test": "node test/sample.test.js && node test/contract.test.js"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Lennonhaha/fibemate-tools.git",
+    "directory": "hallucination-detector"
+  },
+  "files": ["src"],
+  "engines": { "node": ">=16" }
+}

package/src/api-misuse.js

@@ -0,0 +1,70 @@
+'use strict';
+/*
+ * api-misuse.js — 检测「AI 易编造的伪 API / 错误调用」启发式
+ * 方法：基于白名单（真实存在、可复核的 API）核对代码中的调用点。
+ * 注意：白名单是针对「FIBEMATE 技术栈」的示例集合，非通用真理；
+ * 任何新项目使用前须按自家依赖核实（这正是「不拿推测当事实」纪律的代码化）。
+ * 报告模式：调用名不在白名单中、且形似「知名库 API 变体」时为 suspect。
+ */
+const { scanFile } = require('./ast-scanner');
+
+// @whitelist-version 2026-09-12
+// 白名单针对 FIBEMATE 技术栈（noble-ciphers/noble-hashes/@noble/curves + WebCrypto + 内部封装）。
+// 新项目使用前须按自家依赖核实（这正是「不拿推测当事实」纪律的代码化）。
+// 审计者可见：白名单是此日期的快照，库更新后需同步此标记。
+
+// 示例白名单（FIBEMATE 实际依赖的真实导出，逐条可核实）
+const KNOWN_OK = new Set([
+  // noble (noble-ciphers / noble-hashes / @noble/curves)
+  'ml_kem768', 'x25519', 'ed25519', 'sha256', 'sha3_256', 'shake256', 'hmac',
+  'randomBytes', 'crypto_subtle', 'getRandomValues', 'aeadEncrypt', 'aeadDecrypt',
+  'keccak_256', 'cshake256', 'mod', 'pow', 'inv', 'hashToField',
+  // WebCrypto
+  'crypto.subtle.encrypt', 'crypto.subtle.decrypt', 'crypto.subtle.importKey',
+  'crypto.subtle.deriveBits', 'crypto.subtle.sign', 'crypto.subtle.verify',
+  // Node
+  'createCipheriv', 'createDecipheriv', 'timingSafeEqual', 'scryptSync',
+  // FIBEMATE 内部
+  'doubleRatchetAdvance', 'ratchetStep', 'symmetricEncrypt', 'symmetricDecrypt',
+]);
+
+// 常见「AI 会编出来」的伪 noble/WebCrypto API（仅作可疑标记，不判违规）
+const SUSPECT_PATTERNS = [
+  { re: /noble\.(kem|pqc|mlkem)/i, note: 'noble 命名空间下常见编造：noble.kem/mlkem（真实为 @noble/ciphers 的 ml_kem768）' },
+  { re: /crypto\.subtle\.mlkem/i, note: 'WebCrypto 尚无 ML-KEM 标准 API，疑似编造' },
+  { re: /noble\.sha3/i, note: 'noble 下无 sha3 顶层导出，真实为 noble-hashes 的 sha3_256' },
+  { re: /x25519\.(derive|keyFrom)/i, note: 'x25519 在 @noble/curves 的真实方法名需注意大小写/挂载' },
+  // 仅当 .open( 前接密码学对象（cipher/box/ratchet/aead/seal 等）才可疑；排除 indexedDB.open 等通用 API
+  { re: /\b(cipher|box|aead|ratchet|secretbox|secretBox|symmetric)\.open\(/i, note: 'seal/open 常见于某些封装库，须确认是否真实存在' },
+  { re: /\.seal\(/i, note: 'seal/open 常见于某些封装库，须确认是否真实存在' },
+];
+
+function analyzeApiMisuse(source, filename) {
+  const scan = scanFile(source, filename);
+  const suspects = [];
+  for (const call of scan.calls) {
+    const full = call.name;
+    if (KNOWN_OK.has(full)) continue;
+    for (const sp of SUSPECT_PATTERNS) {
+      if (sp.re.test(full)) {
+        suspects.push({ file: filename, line: lineOf(scan, call.index), api: full, note: sp.note });
+        break;
+      }
+    }
+  }
+  // 同时扫描源码整体中的可疑 API 命名空间（成员访问链等，不限于调用名）
+  // 非全局正则用单次 test 即可（启发式：每文件每模式命中一次足够），避免 exec 死循环
+  for (const sp of SUSPECT_PATTERNS) {
+    if (sp.re.test(source)) {
+      const line = source.search(sp.re) >= 0
+        ? source.slice(0, source.search(sp.re)).split('\n').length
+        : 0;
+      suspects.push({ file: filename, line, api: source.match(sp.re)[0], note: sp.note });
+    }
+  }
+  return { file: filename, suspects, verdict: suspects.length ? 'needs-human-review' : 'ok' };
+}
+
+function lineOf(scan, index) { return scan.source.slice(0, index).split('\n').length; }
+
+module.exports = { analyzeApiMisuse };

package/src/ast-scanner.js

@@ -0,0 +1,204 @@
+'use strict';
+/*
+ * ast-scanner.js — 轻量结构扫描器（零依赖）
+ * 不调用完整 JS 解析器，基于「掩码源码 + 括号配平」提取：
+ *   - comments: 注释文本（含 @secret 标注、constant-time/secure/FIPS 声明）
+ *   - calls:    调用点（函数名 + 参数片段）
+ *   - branches: 分支条件（if/else if/while/for/三元）
+ *   - functions: 函数声明（name + 参数）
+ *   - secretVars: 秘密变量集合（显式 @secret + 命名启发 + 赋值传播）
+ * 启发式，非完整 AST。定位为「静态启发式检测器」，不宣称等效于 esprima/acorn。
+ */
+
+// 把字符串与注释替换成等宽空格，保留索引对齐，避免括号配平被串内 ( ) 干扰
+function maskSource(src) {
+  let out = '';
+  let i = 0;
+  const n = src.length;
+  while (i < n) {
+    const c = src[i];
+    const c2 = src[i + 1];
+    if (c === '/' && c2 === '/') {
+      let j = i; while (j < n && src[j] !== '\n') j++;
+      out += ' '.repeat(j - i); i = j; continue;
+    }
+    if (c === '/' && c2 === '*') {
+      let j = i + 2; while (j < n && !(src[j] === '*' && src[j + 1] === '/')) j++;
+      j = Math.min(n, j + 2); out += ' '.repeat(j - i); i = j; continue;
+    }
+    if (c === '"' || c === "'" || c === '`') {
+      const q = c; let j = i + 1;
+      while (j < n) {
+        if (src[j] === '\\') { j += 2; continue; }
+        if (src[j] === q) { j++; break; }
+        j++;
+      }
+      out += ' '.repeat(j - i); i = j; continue;
+    }
+    out += c; i++;
+  }
+  return out;
+}
+
+function extractComments(src) {
+  const comments = [];
+  const lineRe = /\/\/(.*)$/gm;
+  let m;
+  while ((m = lineRe.exec(src))) {
+    comments.push({ type: 'line', text: m[1].trim(), line: src.slice(0, m.index).split('\n').length });
+  }
+  const blockRe = /\/\*([\s\S]*?)\*\//g;
+  while ((m = blockRe.exec(src))) {
+    comments.push({ type: 'block', text: m[1].replace(/\s+/g, ' ').trim(),
+      line: src.slice(0, m.index).split('\n').length });
+  }
+  return comments;
+}
+
+function balancedSlice(src, openIdx) {
+  if (src[openIdx] !== '(') return null;
+  let depth = 0;
+  for (let i = openIdx; i < src.length; i++) {
+    const c = src[i];
+    if (c === '(') depth++;
+    else if (c === ')') { depth--; if (depth === 0) return src.slice(openIdx + 1, i); }
+  }
+  return src.slice(openIdx + 1);
+}
+
+const WORD = '[A-Za-z_$][\\w$]*';
+
+function scanFile(source, filename) {
+  const masked = maskSource(source);
+  const comments = extractComments(source);
+
+  const calls = [];
+  const callRe = new RegExp('(' + WORD + ')\\s*\\(', 'g');
+  let m;
+  while ((m = callRe.exec(masked))) {
+    const name = m[1];
+    const argsRaw = balancedSlice(masked, m.index + name.length);
+    calls.push({ name, args: argsRaw ? argsRaw.trim() : '', index: m.index });
+  }
+
+  const branches = [];
+  const branchRe = new RegExp('\\b(if|else\\s+if|while|for|switch)\\s*\\(', 'g');
+  while ((m = branchRe.exec(masked))) {
+    const kind = m[1].replace(/\s+/g, ' ');
+    const cond = balancedSlice(masked, m.index + m[0].length - 1);
+    branches.push({ kind, condition: cond ? cond.trim() : '', index: m.index });
+  }
+  // 三元表达式（?: 不在括号内）
+  let depth = 0;
+  for (let i = 0; i < masked.length; i++) {
+    const c = masked[i];
+    if (c === '(') depth++;
+    else if (c === ')') depth--;
+    else if (c === '?' && depth === 0) {
+      // 找匹配的 :
+      let d2 = depth, j = i + 1, startLine = source.slice(0, i).split('\n').length;
+      while (j < masked.length) {
+        if (masked[j] === '(') d2++;
+        else if (masked[j] === ')') d2--;
+        else if (masked[j] === ':' && d2 === 0) {
+          branches.push({ kind: 'ternary', condition: source.slice(i + 1, j).trim(), index: i, line: startLine });
+          break;
+        }
+        j++;
+      }
+    }
+  }
+
+  const functions = [];
+  const fnRe = new RegExp('function\\s+(' + WORD + ')\\s*\\(([^)]*)\\)', 'g');
+  while ((m = fnRe.exec(masked))) {
+    functions.push({ name: m[1], params: m[2].trim(), index: m.index });
+  }
+  const arrowRe = new RegExp('(' + WORD + ')\\s*=\\s*\\(([^)]*)\\)\\s*=>', 'g');
+  while ((m = arrowRe.exec(masked))) {
+    functions.push({ name: m[1], params: m[2].trim(), index: m.index });
+  }
+
+  // 赋值收集（用于秘密传播）：lhs = rhs
+  const assigns = [];
+  const assignRe = new RegExp('(' + WORD + ')\\s*=\\s*([^;=].*?);', 'g');
+  while ((m = assignRe.exec(masked))) {
+    assigns.push({ lhs: m[1], rhs: m[2].trim() });
+  }
+
+  // 秘密变量初集
+  const secretVars = new Set();
+  // 秘密变量命名判定：白名单 + 黑名单双向，黑名单优先（避免 rootKey/chainKey 等状态键被误判为秘密）
+  // 白名单：确为密码学秘密的常见命名（使用词边界，避免 section/second/privacy 等误中）
+  const SECRET_WHITE = [
+    /\bsecret\b/i,
+    /\bprivateKey\b/i, /\bprivKey\b/i,
+    /\bsharedSecret\b/i,
+    /\bsk\b/i,
+    /\bhmac\b/i,
+    /\bpassword\b/i, /\bpasswd\b/i,
+    /\btoken\b/i,
+    /\bsalt\b/i,
+    /\biv\b/i,
+    /\bnonce\b/i,
+  ];
+  // 黑名单：ratchet 等状态键，虽含 key 但不是侧信道敏感秘密（长度/存在性校验非时序敏感）
+  const SECRET_BLACK = [
+    /\brootKey\b/i,
+    /\bchainKey\b/i,
+    /\breceivingChainKey\b/i,
+    /\bsendingChainKey\b/i,
+    /\bmessageKey\b/i,
+    /\bheaderKey\b/i,
+  ];
+  function isSecretName(name) {
+    if (!name) return false;
+    if (SECRET_BLACK.some((r) => r.test(name))) return false;
+    return SECRET_WHITE.some((r) => r.test(name));
+  }
+  for (const c of comments) {
+    const mm = c.text.match(/@secret\s+([\w\s,]+)/i);
+    if (mm) {
+      mm[1].split(/[\s,]+/).filter(Boolean).forEach((nm) => secretVars.add(nm));
+    }
+  }
+  // 参数/变量名启发
+  for (const f of functions) {
+    f.params.split(',').map((s) => s.trim().split(/\s+/)[0]).filter(Boolean)
+      .forEach((p) => { if (isSecretName(p)) secretVars.add(p); });
+  }
+
+  // 赋值传播（定点迭代，小图足够）
+  let changed = true, guard = 0;
+  while (changed && guard++ < 20) {
+    changed = false;
+    for (const a of assigns) {
+      if ([...secretVars].some((s) => new RegExp('\\b' + s + '\\b').test(a.rhs))) {
+        if (!secretVars.has(a.lhs)) { secretVars.add(a.lhs); changed = true; }
+      }
+    }
+  }
+
+  // 声明中提及的声明式秘密（如 const secretKey = ...）
+  for (const a of assigns) {
+    if (isSecretName(a.lhs) && !secretVars.has(a.lhs)) secretVars.add(a.lhs);
+  }
+
+  return {
+    filename,
+    comments,
+    calls,
+    branches,
+    functions,
+    secretVars: [...secretVars],
+    masked,
+    source,
+  };
+}
+
+// 判断某段文本是否引用了秘密变量（词边界）
+function referencesSecret(text, secretVars) {
+  return secretVars.some((s) => new RegExp('\\b' + s + '\\b').test(text));
+}
+
+module.exports = { scanFile, referencesSecret, maskSource, extractComments };

package/src/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+'use strict';
+/*
+ * cli.js — 命令行入口
+ * 用法: node src/cli.js <file-or-dir> [rootDir] [--fail-on <low|medium|high>]
+ */
+const fs = require('fs');
+const path = require('path');
+const { analyzeProject } = require('./index');
+
+const EXCLUDE_DIRS = new Set(['node_modules', 'test', '.git', 'dist', 'build', 'coverage', 'out', '.next', 'vendor', '.cache', 'tmp']);
+const MAX_FILE_SIZE = 1024 * 1024; // 1 MB — skip files larger than this
+
+function collect(dirOrFile, acc) {
+  acc = acc || [];
+  const stat = fs.statSync(dirOrFile);
+  if (stat.isDirectory()) {
+    for (const e of fs.readdirSync(dirOrFile)) {
+      const full = path.join(dirOrFile, e);
+      const s = fs.statSync(full);
+      if (s.isDirectory()) {
+        if (EXCLUDE_DIRS.has(e)) continue;
+        collect(full, acc);
+      } else if (/\.(js|ts)$/.test(e)) {
+        if (s.size > MAX_FILE_SIZE) continue; // skip oversized files
+        acc.push({ filename: full, source: fs.readFileSync(full, 'utf-8') });
+      }
+    }
+  } else {
+    acc.push({ filename: dirOrFile, source: fs.readFileSync(dirOrFile, 'utf-8') });
+  }
+  return acc;
+}
+
+const SEVERITY_RANK = { low: 0, medium: 1, high: 2 };
+
+// 解析参数：--fail-on <level> 与位置参数分离；位置参数顺序保持不变
+function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--fail-on') {
+      flags.failOn = argv[++i];
+    } else if (a.startsWith('--')) {
+      flags[a.slice(2)] = true;
+    } else {
+      positional.push(a);
+    }
+  }
+  return { flags, positional };
+}
+
+// finding 的 severity 归一化：无 severity 字段（api-misuse / domain-params /
+// test-coverage）视为 medium——它们是「需人工核验」而非「确定违规」。
+function severityOf(f) {
+  return f.severity || 'medium';
+}
+
+function main() {
+  const { flags, positional } = parseArgs(process.argv.slice(2));
+  if (flags.failOn !== undefined && !Object.prototype.hasOwnProperty.call(SEVERITY_RANK, flags.failOn)) {
+    console.error('--fail-on requires one of: low | medium | high');
+    process.exit(2);
+  }
+  const target = positional[0];
+  if (!target) { console.error('usage: node src/cli.js <file-or-dir> [rootDir] [--fail-on <low|medium|high>]'); process.exit(2); }
+  const rootDir = positional[1] || (fs.statSync(target).isDirectory() ? target : '.');
+  const sources = collect(target);
+  const report = analyzeProject(sources, rootDir);
+  console.log(JSON.stringify(report, null, 2));
+  const n = report.findings.length;
+  console.log('\n[summary] files=' + sources.length + ' findings=' + n);
+  if (flags.failOn !== undefined && n > 0) {
+    const threshold = SEVERITY_RANK[flags.failOn];
+    const offending = report.findings.filter((f) => SEVERITY_RANK[severityOf(f)] >= threshold);
+    if (offending.length > 0) {
+      console.error('[fail-on] ' + offending.length + ' finding(s) at or above severity "' + flags.failOn + '"');
+      process.exit(1);
+    }
+  }
+}
+
+main();

package/src/constant-time.js

@@ -0,0 +1,29 @@
+'use strict';
+/*
+ * constant-time.js — 检测「非定常实现」启发式
+ * 真实来源：计时/功率侧信道通常源于：秘密相关分支、秘密做数组下标、
+ * 对秘密的非定常比较。这里聚合 ast-scanner + pattern-scanner 的产出，
+ * 给出「需人工核验」而非「确定违规」的标记。
+ */
+const { scanFile } = require('./ast-scanner');
+const { scanPatterns } = require('./pattern-scanner');
+
+function analyzeConstantTime(source, filename) {
+  const scan = scanFile(source, filename);
+  const suspicious = scanPatterns(scan).filter((f) =>
+    f.pattern === 'secret-dependent-branch' ||
+    f.pattern === 'array-index-by-secret' ||
+    f.pattern === 'switch-on-secret' ||
+    f.pattern === 'declared-secure-but-branches-secret');
+  const score = suspicious.filter((s) => s.severity === 'high').length * 2 +
+                suspicious.filter((s) => s.severity === 'medium').length;
+  return {
+    file: filename,
+    secretVars: scan.secretVars,
+    findings: suspicious,
+    score,
+    verdict: score === 0 ? 'no-side-channel-smell' : 'needs-human-review',
+  };
+}
+
+module.exports = { analyzeConstantTime };

package/src/domain-params.js

@@ -0,0 +1,105 @@
+'use strict';
+/*
+ * domain-params.js — 类 9：参数/域错误检测（启发式）
+ *
+ * 方法：从源码中按「文件名或源码内容识别算法」锚定，标记「疑似参数错误」。
+ *   - 文件名或文件内容含算法标识（如 ml-kem-768 / ml-dsa / slh-dsa）时才查表（减少误报）
+ *   - 该文件内扫描 PARAM_NAMES（q/n/k/h/d）的常量赋值，与 NIST 白名单精确比对
+ *   - 若常量值不在该算法的 NIST 标准白名单中，标记为 suspect（需人工核验，不判违规）
+ *   （注：文件名或内容任一命中算法标识即视为「该文件为对应算法实现」；
+ *    避免漏报；误报风险由文件名识别已挡掉大部分无关文件。）
+ *
+ * 设计约束（据本次起草评审）：
+ *   - 找参数：正则 + 关键字（不引入 AST 解析），先简单、能跑
+ *   - 查表：精确匹配，不搞 ±误差
+ *   - 疑似判定：标准算法（文件名或内容命中） + 常量不在白名单 = suspicious（双条件）
+ *   - 接口与 api-misuse 完全同形：{ file, suspects:[{file,line,param,value,note}], verdict }
+ *
+ * 白名单针对 FIBEMATE 技术栈中的 NIST 后量子算法；新项目使用前须按自家依赖核实。
+ * 审计者可见：白名单是此日期的快照，库/标准更新后需同步此标记。
+ */
+
+// @whitelist-version 2026-09-13
+// NIST 标准参数快照（FIBEMATE 实际依赖的真实参数，逐条可核实）。
+// 数据来源：FIPS 203 (ML-KEM) / FIPS 204 (ML-DSA) / FIPS 205 (SLH-DSA)。
+const NIST_PARAMS = {
+  'ml-kem-768':   { q: 3329,    n: 256, k: 3 },
+  'ml-kem-1024':  { q: 3329,    n: 256, k: 4 },
+  'ml-dsa-65':    { q: 8380417, n: 256, k: 6 },
+  'slh-dsa-sha2-128f': { n: 16, h: 66, d: 22 },
+  'slh-dsa-sha2-128s': { n: 16, h: 63, d: 7 },
+  // TODO: SM 系列（SM2/SM3/SM4）参数白名单待补——需先与国密标准核实
+};
+
+// 文件名 → 算法 key 的识别（保守小写匹配）
+const ALGO_HINTS = [
+  { key: 'ml-kem-768',        re: /ml[-_]?kem[-_]?768/i },
+  { key: 'ml-kem-1024',       re: /ml[-_]?kem[-_]?1024/i },
+  { key: 'ml-dsa-65',         re: /ml[-_]?dsa[-_]?65/i },
+  { key: 'slh-dsa-sha2-128f', re: /slh[-_]?dsa[-_]?sha2[-_]?128f/i },
+  { key: 'slh-dsa-sha2-128s', re: /slh[-_]?dsa[-_]?sha2[-_]?128s/i },
+];
+
+// 参数名白名单（只在出现这些赋值名时才纳入查表，避免把任意数字当参数）
+const PARAM_NAMES = ['q', 'n', 'k', 'h', 'd'];
+
+function inferAlgorithm(filename, source) {
+  const hay = filename + '\n' + (source || '');
+  for (const h of ALGO_HINTS) {
+    if (h.re.test(hay)) return h.key;
+  }
+  return null;
+}
+
+// 在密码学上下文里扫描形如 `name = <int>` / `name: <int>` 的常量赋值
+function extractParamConstants(source) {
+  const hits = [];
+  const lines = source.split('\n');
+  // 上下文判定：文件名或内容已识别为标准算法（见 analyzeDomainParams）的前提下，
+  // 全文件扫描 PARAM_NAMES 的赋值（不再要求行内密码学关键词，避免过度漏报；
+  // 误报风险已由「算法标识识别」这一条件挡掉大部分非密码学文件）。
+  const paramRe = new RegExp('\\b(' + PARAM_NAMES.join('|') + ')\\s*[:=]\\s*([0-9]+)', 'g');
+  for (let li = 0; li < lines.length; li++) {
+    const line = lines[li];
+    let m;
+    while ((m = paramRe.exec(line))) {
+      hits.push({ name: m[1], value: parseInt(m[2], 10), line: li + 1, snippet: line.trim() });
+    }
+  }
+  return hits;
+}
+
+function isKnownConstantFor(algo, name, value) {
+  const params = NIST_PARAMS[algo];
+  if (!params) return true; // 未知算法不报（保守）
+  if (!(name in params)) return true; // 该算法无此参数名不报（避免误伤无关常量）
+  return params[name] === value;
+}
+
+function analyzeDomainParams(source, filename) {
+  const algo = inferAlgorithm(filename, source);
+  const suspects = [];
+  if (!algo) {
+    // 文件名未识别为标准算法：不查表（双条件之一不满足）
+    return { file: filename, suspects, verdict: 'ok' };
+  }
+  const constants = extractParamConstants(source);
+  for (const c of constants) {
+    if (!isKnownConstantFor(algo, c.name, c.value)) {
+      suspects.push({
+        file: filename,
+        line: c.line,
+        param: c.name,
+        value: c.value,
+        note: `疑似参数错误: ${c.name}=${c.value} 不在 ${algo} 的 NIST 白名单中`,
+      });
+    }
+  }
+  return {
+    file: filename,
+    suspects,
+    verdict: suspects.length ? 'needs-human-review' : 'ok',
+  };
+}
+
+module.exports = { analyzeDomainParams, NIST_PARAMS, inferAlgorithm, extractParamConstants };

package/src/index.js

@@ -0,0 +1,38 @@
+'use strict';
+/*
+ * index.js — 聚合四个检测器的统一入口
+ * 输出结构化报告（供 CLI / 其他工具消费）。
+ * 定位：启发式静态检查，标记「需人工核验」，不宣判漏洞。
+ */
+const ct = require('./constant-time');
+const api = require('./api-misuse');
+const cov = require('./test-coverage');
+const dp = require('./domain-params');
+
+function analyzeFile(source, filename) {
+  const ctRes = ct.analyzeConstantTime(source, filename);
+  const apiRes = api.analyzeApiMisuse(source, filename);
+  const dpRes = dp.analyzeDomainParams(source, filename);
+  return {
+    file: filename,
+    constantTime: ctRes,
+    apiMisuse: apiRes,
+    domainParams: dpRes,
+  };
+}
+
+function analyzeProject(sources /* [{filename, source}] */, rootDir) {
+  const perFile = sources.map((s) => analyzeFile(s.source, s.filename));
+  const srcPaths = sources.map((s) => s.filename);
+  const covRes = cov.analyzeTestCoverage(srcPaths, rootDir);
+  const allFindings = [];
+  for (const f of perFile) {
+    for (const x of f.constantTime.findings) allFindings.push({ type: 'constant-time', ...x });
+    for (const s of f.apiMisuse.suspects) allFindings.push({ type: 'api-misuse', ...s });
+    for (const d of f.domainParams.suspects) allFindings.push({ type: 'domain-params', ...d });
+  }
+  for (const u of covRes.uncovered) allFindings.push({ type: 'test-coverage', file: u.file, note: 'no corresponding test file' });
+  return { perFile, coverage: covRes, findings: allFindings };
+}
+
+module.exports = { analyzeFile, analyzeProject };

package/src/pattern-scanner.js

@@ -0,0 +1,153 @@
+'use strict';
+/*
+ * pattern-scanner.js — 基于 ast-scanner 的启发式模式匹配
+ * 检测「AI 易编造 / 易漏」的危险代码模式（命名来源透明）：
+ *   - secret-dependent branch / loop  → 可能的时序侧信道（SPA/DPA 基础）
+ *   - array/string index by secret    → 缓存时序 / 越界推测
+ *   - early return on failure          → 可区分错误响应（时序/消息）
+ *   - switch on secret byte            → 经典非定常实现
+ *   - comparison via != / !== on secret→ 可能非定常比较
+ *   - comment declares secure but code branches on secret → 声明与实现矛盾
+ * 每个 pattern 给出 file/line/severity/justification，绝不臆断「一定是漏洞」。
+ */
+
+const { referencesSecret } = require('./ast-scanner');
+
+// 判断一个条件是否可能是「秘密相关」（保守）
+function conditionSecretRelated(cond, secretVars) {
+  if (!cond) return false;
+  return referencesSecret(cond, secretVars);
+}
+
+const PATTERNS = [
+  {
+    id: 'secret-dependent-branch',
+    severity: 'high',
+    desc: '分支条件引用了秘密变量（潜在时序/功率侧信道）',
+    test(ctx) {
+      const hits = [];
+      for (const b of ctx.branches) {
+        if (b.kind === 'if' || b.kind === 'else if' || b.kind === 'while' || b.kind === 'for' || b.kind === 'ternary') {
+          if (conditionSecretRelated(b.condition, ctx.secretVars)) {
+            hits.push({ line: lineOf(ctx, b.index), snippet: b.condition.slice(0, 80) });
+          }
+        }
+      }
+      return hits;
+    },
+  },
+  {
+    id: 'array-index-by-secret',
+    severity: 'high',
+    desc: '数组/对象下标或切片使用了秘密变量（潜在缓存时序）',
+    test(ctx) {
+      const hits = [];
+      // 形如 x[secretExpr] 或 x[ ... secret ... ]
+      const idxRe = /\[\s*([^\]]*?)\s*\]/g;
+      let m;
+      const code = ctx.masked;
+      while ((m = idxRe.exec(code))) {
+        if (m.index === idxRe.lastIndex) idxRe.lastIndex++; // 防零宽死循环
+        const inside = m[1];
+        if (referencesSecret(inside, ctx.secretVars)) {
+          hits.push({ line: lineOf(ctx, m.index), snippet: m[0].slice(0, 80) });
+        }
+      }
+      return hits;
+    },
+  },
+  {
+    id: 'switch-on-secret',
+    severity: 'medium',
+    desc: 'switch 条件引用了秘密变量',
+    test(ctx) {
+      const hits = [];
+      for (const b of ctx.branches) {
+        if (b.kind === 'switch' && conditionSecretRelated(b.condition, ctx.secretVars)) {
+          hits.push({ line: lineOf(ctx, b.index), snippet: b.condition.slice(0, 80) });
+        }
+      }
+      return hits;
+    },
+  },
+  {
+    id: 'declared-secure-but-branches-secret',
+    severity: 'medium',
+    desc: '注释声明安全/定常/constant-time，但代码存在秘密相关分支（声明与实现矛盾）',
+    test(ctx) {
+      const hits = [];
+      // 声明判定改为「就近」：仅当分支所在行前后 3 行内注释声明安全才判矛盾，
+      // 且排除反向说明（not / non- / TODO / FIXME / unsafe），避免 PKCS8 等被 secure 词边界误中
+      const lines = ctx.source.split('\n');
+      for (const b of ctx.branches) {
+        if (!(b.kind === 'if' || b.kind === 'else if' || b.kind === 'while' || b.kind === 'ternary')) continue;
+        if (!conditionSecretRelated(b.condition, ctx.secretVars)) continue;
+        const bLine = lineOf(ctx, b.index);
+        // bLine 是 1-based 行号；转 0-based 索引后向前 4 行 / 向后 1 行覆盖就近注释
+        const bIdx0 = bLine - 1;
+        const nearby = [];
+        for (let i = Math.max(0, bIdx0 - 4); i <= Math.min(lines.length - 1, bIdx0 + 1); i++) nearby.push(lines[i]);
+        const declaresSafe = nearby.some((ln) => {
+          const t = ln.trim();
+          if (/^\/\//.test(t)) {
+            const body = t.replace(/^\/\/\s*/, '');
+            // 反向说明优先排除
+            if (/\b(not|non[- ]?|TODO|FIXME|unsafe|insecure|downgrade)\b/i.test(body)) return false;
+            return /\b(constant[- ]?time|timing[- ]?safe|side[- ]?channel[- ]?free|secure|FIPS)\b/i.test(body);
+          }
+          return false;
+        });
+        if (declaresSafe) {
+          hits.push({ line: bLine, snippet: b.condition.slice(0, 80) });
+        }
+      }
+      return hits;
+    },
+  },
+  {
+    id: 'nonconstant-comparison',
+    severity: 'low',
+    desc: '疑似对秘密值使用非定常比较（!= / !== / == / ===），建议 ct-equal',
+    test(ctx) {
+      const hits = [];
+      // 按行扫描，避免长文本贪婪回溯
+      const lines = ctx.masked.split('\n');
+      for (let li = 0; li < lines.length; li++) {
+        const line = lines[li];
+        const re = /([!=]={1,2})\s*([^;\n]+)/g;
+        let mm;
+        while ((mm = re.exec(line))) {
+          if (referencesSecret(mm[2], ctx.secretVars)) {
+            hits.push({ line: li + 1, snippet: mm[0].slice(0, 80) });
+          }
+        }
+      }
+      return hits;
+    },
+  },
+];
+
+function lineOf(ctx, index) {
+  return ctx.source.slice(0, index).split('\n').length;
+}
+
+function scanPatterns(scan) {
+  const findings = [];
+  for (const p of PATTERNS) {
+    let hits = [];
+    try { hits = p.test(scan) || []; } catch (e) { hits = [{ line: 0, snippet: 'PATTERN ERROR: ' + e.message }]; }
+    for (const h of hits) {
+      findings.push({
+        file: scan.filename,
+        line: h.line,
+        pattern: p.id,
+        severity: p.severity,
+        desc: p.desc,
+        snippet: h.snippet,
+      });
+    }
+  }
+  return findings;
+}
+
+module.exports = { scanPatterns, PATTERNS };

package/src/test-coverage.js

@@ -0,0 +1,42 @@
+'use strict';
+/*
+ * test-coverage.js — 检测「有实现但缺测试 / 测试与实现声明不符」启发式
+ * 方法：扫描某文件是否有对应测试文件、以及测试中是否真正调用被测函数。
+ * 极简：给定一组源文件路径，检查同目录或 test/ 下是否存在覆盖它的测试。
+ */
+const fs = require('fs');
+const path = require('path');
+
+function findTestFor(srcPath, rootDir) {
+  const base = path.basename(srcPath, path.extname(srcPath));
+  const candidates = [
+    path.join(path.dirname(srcPath), base + '.test' + path.extname(srcPath)),
+    path.join(path.dirname(srcPath), '__tests__', base + '.test' + path.extname(srcPath)),
+    path.join(rootDir, 'test', base + '.test' + path.extname(srcPath)),
+    path.join(rootDir, 'test', base + path.extname(srcPath)),
+  ];
+  // Exclude self-match: when srcPath itself sits under a candidate path
+  // (e.g. source lives in test/), candidate 4 (`rootDir/test/base+ext`)
+  // resolves to srcPath itself, so fs.existsSync always returns true and
+  // `uncovered` is never populated. Drop that before the existence check.
+  // Compare *resolved* paths, not raw strings: a `./`-prefixed or otherwise
+  // unnormalized srcPath (e.g. `./test/foo.js` from `cli.js ./test`) used to
+  // slip past the string equality check and self-match.
+  // The bare `test/foo.js` candidate is intentionally kept: it matches
+  // Mocha-style default discovery (test/*.js); removing it would cause
+  // false negatives.
+  return candidates
+    .filter((c) => path.resolve(c) !== path.resolve(srcPath))
+    .find((c) => fs.existsSync(c)) || null;
+}
+
+function analyzeTestCoverage(srcPaths, rootDir) {
+  const uncovered = [];
+  for (const p of srcPaths) {
+    const t = findTestFor(p, rootDir);
+    if (!t) uncovered.push({ file: p, test: null });
+  }
+  return { uncovered, verdict: uncovered.length ? 'needs-human-review' : 'ok' };
+}
+
+module.exports = { analyzeTestCoverage, findTestFor };