@mstar-harness/engine 3.3.0 → 3.4.1

package/dist/audit.d.ts

@@ -8,6 +8,11 @@ export type AuditEffort = (typeof AUDIT_EFFORTS)[number];
 /** Risk values. */
 export declare const AUDIT_RISKS: readonly ["LOW", "MED", "HIGH"];
 export type AuditRisk = (typeof AUDIT_RISKS)[number];
+/** Confidence values (finding-format.md § Template — Confidence: HIGH
+ * (certain, read the code) / MED (strong signal, verify) / LOW (smell,
+ * investigate)). Enum SSOT for finding-doc lint + AuditFinding. */
+export declare const AUDIT_CONFIDENCES: readonly ["HIGH", "MED", "LOW"];
+export type AuditConfidence = (typeof AUDIT_CONFIDENCES)[number];
 /** Category codes (finding-format.md § Category codes + mstar-audit SKILL.md § Plan output (all variants) Status block). */
 export declare const AUDIT_CATEGORIES: readonly ["bug", "security", "perf", "tests", "tech-debt", "migration", "dx", "docs", "direction"];
 export type AuditCategory = (typeof AUDIT_CATEGORIES)[number];
@@ -42,6 +47,55 @@ export type RedactResult = {
     text: string;
     findings: SecretFinding[];
 };
+/**
+ * Whole-match credential patterns — the match is fully replaced. Patterns
+ * are deliberately conservative (prefixed signatures + minimum lengths) to
+ * avoid false positives (mstar-audit Hard Rule 4: reference file:line and
+ * credential type only, never the value). Exported as the D-2 SSOT: both
+ * `redactSecrets` and `scanSecrets` share this one table, so reviewers can
+ * reconcile against exactly what the engine scans. Extending it only ever
+ * ADDS detections for consumers of either reader — existing-pattern
+ * behavior of the dsh audit seam (`validateAuditDoc`) stays byte-identical.
+ */
+export declare const WHOLE_MATCH_PATTERNS: readonly {
+    type: string;
+    re: RegExp;
+}[];
+/**
+ * Key-value assignment patterns — for redaction the key name is preserved
+ * and only the value is replaced. Value minimum lengths (8 quoted / 16
+ * unquoted) keep the scan conservative (`token: x` and `password: 1234`
+ * are not flagged). Keys may carry optional quotes (JSON/YAML
+ * `"password": "..."`), which are preserved in the replacement: group 1 =
+ * optional open quote, group 3 = optional close quote, group 4 = separator,
+ * group 5 = value (dropped). Exported as part of the D-2 SSOT — shared by
+ * `redactSecrets` and `scanSecrets`.
+ */
+export declare const VALUE_PATTERNS: readonly {
+    typeOf: (key: string) => string;
+    re: RegExp;
+}[];
+/**
+ * Never-commit filename patterns (security-review.md §6): a file whose name
+ * matches should not be committed regardless of content — `.env*`, `*.pem`,
+ * `*.key`, `id_rsa`-family, plus named credential stores. All patterns are
+ * matched against the path BASENAME, never the full path.
+ */
+export declare const NEVER_COMMIT_FILENAMES: readonly {
+    type: string;
+    re: RegExp;
+}[];
+/**
+ * CI/IaC credential-leak shapes (security-review.md §6). Each entry is one
+ * deterministic line shape; match groups feed the finding message. All
+ * shapes are additive on top of the pattern tables above and never capture
+ * secret VALUES into findings (Hard Rule 4) — only file:line + type.
+ */
+export declare const CI_IAC_LEAK_SHAPES: readonly {
+    kind: string;
+    description: string;
+    re: RegExp;
+}[];
 /**
  * Scan text for credential patterns and replace every occurrence with a
  * `[REDACTED <type>@<line> in <file>]` marker (file omitted when `filePath`
@@ -50,6 +104,61 @@ export type RedactResult = {
  * line-sorted findings summary (`{ line, type }`).
  */
 export declare function redactSecrets(text: string, filePath?: string): RedactResult;
+/** One `scanSecrets` finding: file + 1-based line + credential type ONLY —
+ * never the secret value (mstar-audit Hard Rule 4). */
+export type ScannedSecret = {
+    file: string;
+    line: number;
+    type: string;
+};
+/**
+ * Read-only per-line secret scan over the given files. Report-only by
+ * design — it never redacts, never writes, and its findings carry
+ * `file:line` + credential type only (Hard Rule 4). Patterns come from the
+ * D-2 SSOT tables above (`WHOLE_MATCH_PATTERNS`, `VALUE_PATTERNS`) plus the
+ * never-commit filename list (`NEVER_COMMIT_FILENAMES`) and CI/IaC leak
+ * shapes (`CI_IAC_LEAK_SHAPES`). Safe-placeholder spans are masked before
+ * pattern evaluation (only the span — a key beside it still fires). Files
+ * that cannot be read are counted in `unreadableFiles` instead of being
+ * silently skipped: a security gate must never report clean over input it
+ * could not inspect (qc1 W-002).
+ */
+/** Result of {@link scanSecrets}: findings plus how many selected files
+ * could not be read (fail-closed signal for CLI gates). */
+export type ScanSecretsResult = {
+    findings: ScannedSecret[];
+    unreadableFiles: number;
+};
+export declare function scanSecrets(files: readonly string[]): ScanSecretsResult;
+/** Kinds of supply-chain findings (B-11): lockfile presence/duplication at
+ * install boundaries and GitHub Actions pin/exposure shapes. */
+export type SupplyChainFindingKind = "lockfile-missing" | "lockfile-duplicate" | "action-unpinned" | "pull_request_target-head";
+export type SupplyChainFinding = {
+    kind: SupplyChainFindingKind;
+    file: string;
+    line?: number;
+};
+/** Result of {@link supplyChainChecks}: gate verdict + machine findings. */
+export type SupplyChainResult = GateResult & {
+    findings: SupplyChainFinding[];
+};
+/**
+ * Deterministic supply-chain checks over `repoRoot` (read-only):
+ * - `lockfile-missing`: no recognized lockfile at the repo root
+ *   (package-lock.json / pnpm-lock.yaml / yarn.lock / bun.lock[b] /
+ *   Cargo.lock / poetry.lock / uv.lock / Gemfile.lock / composer.lock).
+ * - `lockfile-duplicate`: two or more distinct lockfiles at the root —
+ *   ambiguous install boundaries.
+ * - `action-unpinned`: `.github/workflows/*.yml` steps using mutable refs
+ *   (`@main`, `@master`, `@latest` or any non-SHA ref).
+ * - `pull_request_target-head`: a workflow triggers on `pull_request_target`
+ *   AND checks out the PR head — untrusted code with secrets access.
+ *
+ * Tri-age judgment (reachable / runtime-relevant) is deliberately left to
+ * the reviewer (C-class). Violation codes mirror finding kinds with the
+ * `audit.supply.` prefix; `ok` is false iff any finding exists.
+ */
+export declare function supplyChainChecks(repoRoot: string): SupplyChainResult;
 /** One audit finding, shaped after finding-format.md. */
 export type AuditFinding = {
     title: string;
@@ -57,7 +166,7 @@ export type AuditFinding = {
     impact: string;
     effort: AuditEffort;
     risk: AuditRisk;
-    confidence: "HIGH" | "MED" | "LOW";
+    confidence: AuditConfidence;
     evidence: readonly string[];
     priority: AuditPriority;
     fixSketch?: string;

package/dist/audit.js

@@ -1,4 +1,5 @@
 // src/audit.ts
+import { execFileSync } from "node:child_process";
 import { existsSync as existsSync3, mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync3, rmdirSync as rmdirSync2, rmSync, writeFileSync as writeFileSync3 } from "node:fs";
 import { basename as basename2, join as join4, resolve as resolve4, sep as sep2 } from "node:path";
 
@@ -343,6 +344,7 @@ function violation2(severity, code, message, fix) {
 var AUDIT_PRIORITIES = ["P1", "P2", "P3"];
 var AUDIT_EFFORTS = ["XS", "S", "M", "L", "XL"];
 var AUDIT_RISKS = ["LOW", "MED", "HIGH"];
+var AUDIT_CONFIDENCES = ["HIGH", "MED", "LOW"];
 var AUDIT_CATEGORIES = [
   "bug",
   "security",
@@ -409,9 +411,11 @@ function validateAuditStatusBlocks(planText) {
   return { ok: violations.length === 0, violations };
 }
 var WHOLE_MATCH_PATTERNS = [
-  { type: "private-key", re: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/g },
+  { type: "private-key", re: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g },
   { type: "aws-access-key", re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g },
   { type: "github-token", re: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g },
+  { type: "github-pat", re: /\bgithub_pat_[A-Za-z0-9_]{40,}\b/g },
+  { type: "stripe-live-key", re: /\bsk_live_[A-Za-z0-9]{16,}\b/g },
   { type: "slack-token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g },
   { type: "jwt", re: /\beyJ[A-Za-z0-9_-]{10,1024}\.[A-Za-z0-9_-]{10,1024}\.[A-Za-z0-9_-]{10,1024}\b/g },
   { type: "api-secret-key", re: /\bsk-[A-Za-z0-9-]{20,}\b/g }
@@ -422,6 +426,36 @@ var VALUE_PATTERNS = [
     re: /(["']?)\b(password|passwd|api[_-]?key|access[_-]?token|auth[_-]?token|secret|token)\b(["']?)(\s*[:=]\s*)("[^"\n]{8,}"|'[^'\n]{8,}'|[A-Za-z0-9_./+\-=]{16,})/gi
   }
 ];
+var NEVER_COMMIT_FILENAMES = [
+  { type: "env-file", re: /^\.env/i },
+  { type: "private-key-file", re: /\.(?:pem|key)$/i },
+  { type: "ssh-private-key-file", re: /^id_(?:rsa|ed25519|ecdsa|dsa)$/ },
+  { type: "credentials-json", re: /^credentials\.json$/i },
+  { type: "service-account-json", re: /^service-account\.json$/i },
+  { type: "git-credentials", re: /^\.?git-credentials$/i }
+];
+var CI_IAC_LEAK_SHAPES = [
+  {
+    kind: "actions-plaintext-env",
+    description: "GitHub Actions env assignment with plaintext literal",
+    re: /^\s*(?:-\s+)?env:\s*[A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|KEY)[A-Z0-9_]*\s*[:=]\s*["']?[A-Za-z0-9_/+=-]{8,}["']?\s*$/
+  },
+  {
+    kind: "actions-secret-echo",
+    description: "echo of a GitHub Actions secrets context value",
+    re: /\becho\b[^#\n]*\$\{\{\s*secrets\.[A-Za-z0-9_]+\s*\}\}/
+  },
+  {
+    kind: "dockerfile-credential-env",
+    description: "Dockerfile ENV/ARG with credential-looking name",
+    re: /^\s*(?:ENV|ARG)\s+[A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|APIKEY|API_KEY|ACCESS_KEY|PRIVATE_KEY)[A-Z0-9_]*\b/i
+  },
+  {
+    kind: "terraform-hardcoded-password",
+    description: "Terraform hardcoded password attribute",
+    re: /^\s*password\s*=\s*"[^$\{][^"]*"\s*$/
+  }
+];
 function buildLineStarts(text) {
   const starts = [0];
   for (let i = 0;i < text.length; i++) {
@@ -443,17 +477,25 @@ function lineAt(starts, index) {
   }
   return lo + 1;
 }
+function lineStartOf(text, index) {
+  return text.lastIndexOf(`
+`, index - 1) + 1;
+}
 function redactSecrets(text, filePath) {
   const starts = buildLineStarts(text);
   const marker = (type, index) => `[REDACTED ${type}@${lineAt(starts, index)}${filePath === undefined ? "" : ` in ${filePath}`}]`;
-  const replacements = [];
-  const findings = [];
+  const spans = [];
   for (const pattern of WHOLE_MATCH_PATTERNS) {
     for (const match of text.matchAll(pattern.re)) {
       if (match.index === undefined)
         continue;
-      replacements.push({ index: match.index, length: match[0].length, text: marker(pattern.type, match.index) });
-      findings.push({ line: lineAt(starts, match.index), type: pattern.type });
+      spans.push({
+        start: match.index,
+        end: match.index + match[0].length,
+        priority: 0,
+        text: marker(pattern.type, match.index),
+        type: pattern.type
+      });
     }
   }
   for (const pattern of VALUE_PATTERNS) {
@@ -462,20 +504,287 @@ function redactSecrets(text, filePath) {
         continue;
       const type = pattern.typeOf(match[2]);
       const replacement = `${match[1]}${match[2]}${match[3]}${match[4]}${marker(type, match.index)}`;
-      replacements.push({ index: match.index, length: match[0].length, text: replacement });
-      findings.push({ line: lineAt(starts, match.index), type });
+      spans.push({ start: match.index, end: match.index + match[0].length, priority: 1, text: replacement, type });
     }
   }
-  replacements.sort((a, b) => b.index - a.index);
+  for (const shape of CI_IAC_LEAK_SHAPES) {
+    const lineScoped = new RegExp(shape.re.source, shape.re.ignoreCase ? "gim" : "gm");
+    for (const match of text.matchAll(lineScoped)) {
+      if (match.index === undefined)
+        continue;
+      const lineEnd = text.indexOf(`
+`, match.index);
+      const end = lineEnd === -1 ? text.length : lineEnd;
+      spans.push({
+        start: match.index,
+        end,
+        priority: 2,
+        text: `${" ".repeat(match.index - lineStartOf(text, match.index))}${marker(shape.kind, match.index)}`,
+        type: shape.kind
+      });
+    }
+  }
+  spans.sort((a, b) => a.start - b.start || b.end - a.end || b.priority - a.priority);
+  const merged = [];
+  let groupMaxEnd = -1;
+  let best = null;
+  for (const span of spans) {
+    if (span.start < groupMaxEnd) {
+      if (groupMaxEnd < span.end)
+        groupMaxEnd = span.end;
+      if (span.end - span.start > best.end - best.start)
+        best = span;
+    } else {
+      if (best !== null)
+        merged.push(best);
+      groupMaxEnd = span.end;
+      best = span;
+    }
+  }
+  if (best !== null)
+    merged.push(best);
   let out = text;
-  for (const r of replacements)
-    out = out.slice(0, r.index) + r.text + out.slice(r.index + r.length);
+  for (let i = merged.length - 1;i >= 0; i--) {
+    const r = merged[i];
+    out = out.slice(0, r.start) + r.text + out.slice(r.end);
+  }
+  const findings = merged.map((r) => ({ line: lineAt(starts, r.start), type: r.type }));
   const deduped = new Map;
   for (const f of findings)
     deduped.set(`${f.line}:${f.type}`, f);
   const sorted = [...deduped.values()].sort((a, b) => a.line - b.line || a.type.localeCompare(b.type));
   return { text: out, findings: sorted };
 }
+var SAFE_PLACEHOLDER_SHAPES = [
+  /\$\{[A-Za-z_][A-Za-z0-9_]*\}/g,
+  /process\.env\.[A-Za-z_][A-Za-z0-9_]*/g,
+  /os\.environ(?:\.get)?\(?\s*["']/g
+];
+var SAFE_PLACEHOLDER_VALUES = ["your-api-key-here", "<your_api_key>", "<your-api-key>"];
+function maskSafePlaceholders(line) {
+  let masked = line;
+  for (const shape of [...SAFE_PLACEHOLDER_VALUES, ...SAFE_PLACEHOLDER_SHAPES]) {
+    if (typeof shape === "string") {
+      let at = masked.toLowerCase().indexOf(shape);
+      while (at !== -1) {
+        let from = at;
+        let to = at + shape.length;
+        if (masked[from - 1] === '"' || masked[from - 1] === "'")
+          from--;
+        if (masked[to] === '"' || masked[to] === "'")
+          to++;
+        masked = masked.slice(0, from) + " ".repeat(to - from) + masked.slice(to);
+        at = masked.toLowerCase().indexOf(shape);
+      }
+    } else {
+      for (const match of masked.matchAll(shape)) {
+        if (match.index === undefined)
+          continue;
+        let from = match.index;
+        let to = match.index + match[0].length;
+        if (masked[from - 1] === '"' || masked[from - 1] === "'")
+          from--;
+        if (masked[to] === '"' || masked[to] === "'")
+          to++;
+        masked = masked.slice(0, from) + " ".repeat(to - from) + masked.slice(to);
+      }
+    }
+  }
+  return masked;
+}
+var ACTIONS_ENV_KEY = /[A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|KEY)[A-Z0-9_]*/;
+function scanActionsEnvMap(lines) {
+  const out = [];
+  let inMap = false;
+  let mapIndent = 0;
+  for (let i = 0;i < lines.length; i++) {
+    const rawLine = lines[i] ?? "";
+    if (!rawLine.trim())
+      continue;
+    const indent = rawLine.length - rawLine.trimStart().length;
+    const line = maskSafePlaceholders(rawLine);
+    if (inMap) {
+      if (indent <= mapIndent) {
+        inMap = false;
+      } else if (line.trim() !== "") {
+        const child = /^\s*(?:["']?)([A-Za-z0-9_-]+)(?:["']?)\s*:\s*(.+?)\s*$/.exec(line);
+        const value = child?.[2] ?? "";
+        if (child !== null && ACTIONS_ENV_KEY.test(child[1]) && !/^\$\{\{[^}]*\}\}$/.test(value) && !/^\$\{[^}]*\}$/.test(value)) {
+          out.push(i + 1);
+        }
+      }
+      if (inMap)
+        continue;
+    }
+    if (/^\s*(?:-\s+)?env:\s*(?:#.*)?$/.test(line)) {
+      inMap = true;
+      mapIndent = indent;
+    }
+  }
+  return out;
+}
+function scanSecrets(files) {
+  const findings = [];
+  let unreadableFiles = 0;
+  const privateKeyRow = WHOLE_MATCH_PATTERNS.find((pattern) => pattern.type === "private-key");
+  if (privateKeyRow === undefined) {
+    throw new Error("scanSecrets: WHOLE_MATCH_PATTERNS is missing its private-key row (full-text PEM pass)");
+  }
+  for (const file of files) {
+    let text;
+    try {
+      text = readFileSync3(file, "utf8");
+    } catch {
+      unreadableFiles++;
+      continue;
+    }
+    const base = basename2(file);
+    for (const entry of NEVER_COMMIT_FILENAMES) {
+      if (entry.re.test(base))
+        findings.push({ file, line: 1, type: entry.type });
+    }
+    const starts = buildLineStarts(text);
+    for (const match of text.matchAll(privateKeyRow.re)) {
+      if (match.index === undefined)
+        continue;
+      findings.push({ file, line: lineAt(starts, match.index), type: privateKeyRow.type });
+    }
+    const lines = text.split(`
+`);
+    for (const lineNo of scanActionsEnvMap(lines)) {
+      findings.push({ file, line: lineNo, type: "actions-plaintext-env" });
+    }
+    for (let i = 0;i < lines.length; i++) {
+      const line = maskSafePlaceholders(lines[i] ?? "");
+      for (const pattern of WHOLE_MATCH_PATTERNS) {
+        if (line.match(pattern.re) !== null)
+          findings.push({ file, line: i + 1, type: pattern.type });
+      }
+      for (const pattern of VALUE_PATTERNS) {
+        const match = pattern.re.exec(line);
+        pattern.re.lastIndex = 0;
+        if (match !== null && !/^\$\{[^}]*\}$/.test(match[5])) {
+          findings.push({ file, line: i + 1, type: pattern.typeOf(match[2]) });
+        }
+      }
+      for (const shape of CI_IAC_LEAK_SHAPES) {
+        if (shape.re.test(line))
+          findings.push({ file, line: i + 1, type: shape.kind });
+      }
+    }
+  }
+  return { findings, unreadableFiles };
+}
+var LOCKFILE_NAMES = [
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock",
+  "bun.lock",
+  "bun.lockb",
+  "Cargo.lock",
+  "poetry.lock",
+  "uv.lock",
+  "Gemfile.lock",
+  "composer.lock"
+];
+function rootLockfiles(root) {
+  let entries;
+  try {
+    entries = readdirSync2(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const names = new Set(LOCKFILE_NAMES);
+  const present = entries.filter((entry) => entry.isFile() && names.has(entry.name)).map((entry) => join4(root, entry.name));
+  if (present.length === 0)
+    return [];
+  try {
+    const tracked = new Set(execFileSync("git", ["ls-files", "-z", "--", "."], {
+      cwd: root,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).split("\x00").filter((f) => f !== ""));
+    return present.filter((p) => tracked.has(basename2(p)));
+  } catch {
+    return present;
+  }
+}
+function supplyChainChecks(repoRoot) {
+  const findings = [];
+  const violations = [];
+  const lockfiles = rootLockfiles(repoRoot);
+  if (lockfiles.length === 0) {
+    findings.push({ kind: "lockfile-missing", file: repoRoot });
+    violations.push(violation2("medium", "audit.supply.lockfile-missing", `no recognized lockfile at ${repoRoot}`, "commit a lockfile (package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lock, …)"));
+  } else if (lockfiles.length > 1) {
+    findings.push({ kind: "lockfile-duplicate", file: lockfiles.map((f) => f.replace(`${repoRoot}/`, "")).join(", ") });
+    violations.push(violation2("medium", "audit.supply.lockfile-duplicate", `multiple lockfiles at ${repoRoot}: ${lockfiles.join(", ")}`, "keep exactly one lockfile per package manager"));
+  }
+  const workflowsDir = join4(repoRoot, ".github", "workflows");
+  let wfEntries = [];
+  try {
+    wfEntries = readdirSync2(workflowsDir, { withFileTypes: true });
+  } catch {
+    wfEntries = [];
+  }
+  for (const entry of wfEntries) {
+    if (!entry.isFile() || !/\.(?:ya?ml)$/.test(entry.name))
+      continue;
+    const wfPath = join4(workflowsDir, entry.name);
+    const relPath = `.github/workflows/${entry.name}`;
+    let text;
+    try {
+      text = readFileSync3(wfPath, "utf8");
+    } catch {
+      continue;
+    }
+    const lines = text.split(`
+`);
+    const hasPrt = /(?:^|\n)\s*(?:(?:-\s+)?pull_request_target\b|on:\s*(?:\[[^\]]*\s*)?pull_request_target\b)/.test(text);
+    const prtHeadSteps = new Set;
+    for (let i = 0;i < lines.length; i++) {
+      const line = lines[i] ?? "";
+      if (!/uses:\s*actions\/checkout\b/.test(line))
+        continue;
+      let stepIndent = line.length - line.trimStart().length;
+      for (let k = i - 1;k >= 0; k--) {
+        const up = lines[k] ?? "";
+        const ind = up.length - up.trimStart().length;
+        if (up.trimStart().startsWith("- ") && ind < stepIndent) {
+          stepIndent = ind;
+          break;
+        }
+      }
+      for (let j = i + 1;j < lines.length; j++) {
+        const l2 = lines[j] ?? "";
+        if (l2.trim() && l2.length - l2.trimStart().length <= stepIndent)
+          break;
+        if (/github\.event\.pull_request\.head\.(?:sha|ref)\b/.test(l2)) {
+          prtHeadSteps.add(i);
+          break;
+        }
+      }
+    }
+    for (let i = 0;i < lines.length; i++) {
+      const line = lines[i] ?? "";
+      const uses = /^\s*(?:-\s+)?uses:\s*(\S+)@(\S+)\s*(?:#.*)?$/.exec(line);
+      if (uses !== null) {
+        const ref = uses[2].replace(/^["']|["']$/g, "");
+        const shaLike = /^[0-9a-f]{40}$/.test(ref);
+        const versionLike = /^v\d+(?:\.\d+)*$/.test(ref);
+        if (!shaLike && !versionLike) {
+          findings.push({ kind: "action-unpinned", file: relPath, line: i + 1 });
+          violations.push(violation2("high", "audit.supply.action-unpinned", `${relPath}:${i + 1} uses \`${uses[1]}@${ref}\` — mutable ref`, "pin the action to a full commit SHA"));
+        }
+      }
+      if (hasPrt && prtHeadSteps.has(i)) {
+        findings.push({ kind: "pull_request_target-head", file: relPath, line: i + 1 });
+        violations.push(violation2("high", "audit.supply.pull_request_target-head", `${relPath}:${i + 1} checks out the PR head under pull_request_target`, "check out the base ref or use a pull_request trigger for untrusted code"));
+      }
+    }
+  }
+  return { ok: violations.length === 0, violations, findings };
+}
 function slugify(title) {
   return title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
@@ -509,6 +818,19 @@ function renderPlanFile(finding, plannedAt) {
 `)}
 `;
 }
+function redactText(text) {
+  return redactSecrets(text).text;
+}
+function redactFinding(finding) {
+  return {
+    ...finding,
+    title: redactText(finding.title),
+    impact: redactText(finding.impact),
+    evidence: finding.evidence.map(redactText),
+    ...finding.fixSketch !== undefined ? { fixSketch: redactText(finding.fixSketch) } : {},
+    ...finding.verification !== undefined ? { verification: redactText(finding.verification) } : {}
+  };
+}
 function readPlanFileSummary(filePath) {
   const text = readFileSync3(filePath, "utf8");
   const title = (text.match(/^# (.+)$/m) ?? [])[1] ?? filePath;
@@ -569,9 +891,10 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
   const carried = existsSync3(existingReadme) ? extractSecurityDispositionSections(readFileSync3(existingReadme, "utf8")) : { needsVerification: [], hardeningChecked: [] };
   const existing = readdirSync2(outDir).filter((f) => /^\d{3}-.*\.md$/.test(f));
   let next = existing.reduce((max, f) => Math.max(max, Number(f.slice(0, 3))), 0) + 1;
+  const redactedFindings = findings.map(redactFinding);
   const written = [];
   const usedSlugs = new Set;
-  for (const finding of findings) {
+  for (const finding of redactedFindings) {
     const num = String(next).padStart(3, "0");
     let slug = slugify(finding.title);
     if (usedSlugs.has(slug)) {
@@ -605,7 +928,7 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
   });
   const byNum = new Map(rows.map((r) => [r.num, r]));
   written.forEach((file, i) => {
-    const finding = findings[i];
+    const finding = redactedFindings[i];
     if (finding === undefined)
       return;
     const row = byNum.get(file.slice(0, 3));
@@ -620,14 +943,14 @@ function scaffoldAuditPlan(outDir, findings, options = {}) {
       row.dependsOn = finding.dependsOn ?? "none";
     }
   });
-  const needsVerificationLines = options.needsVerification !== undefined ? options.needsVerification.map((nv) => `- ${escapeCell(nv.lead)}: ${escapeCell(nv.how)}${nv.evidence ? ` (${escapeCell(nv.evidence)})` : ""}`) : carried.needsVerification;
-  const hardeningCheckedLines = options.hardeningChecked !== undefined ? options.hardeningChecked.map((hc) => `- ${hc.kind}: ${escapeCell(hc.text)}`) : carried.hardeningChecked;
+  const needsVerificationLines = options.needsVerification !== undefined ? options.needsVerification.map((nv) => `- ${escapeCell(redactText(nv.lead))}: ${escapeCell(redactText(nv.how))}${nv.evidence ? ` (${escapeCell(redactText(nv.evidence))})` : ""}`) : carried.needsVerification;
+  const hardeningCheckedLines = options.hardeningChecked !== undefined ? options.hardeningChecked.map((hc) => `- ${hc.kind}: ${escapeCell(redactText(hc.text))}`) : carried.hardeningChecked;
   writeFileSync3(join4(outDir, "README.md"), renderIndex({
     date,
     repoName: options.repoName ?? "repo",
     repoShortSha: options.repoShortSha ?? "unknown",
     rows,
-    rejected: options.rejected ?? [],
+    rejected: (options.rejected ?? []).map((r) => ({ title: redactText(r.title), reason: redactText(r.reason) })),
     needsVerification: needsVerificationLines,
     hardeningChecked: hardeningCheckedLines
   }));
@@ -766,11 +1089,18 @@ function planFileRel(outDir, planFile) {
 }
 export {
   validateAuditStatusBlocks,
+  supplyChainChecks,
+  scanSecrets,
   scaffoldAuditPlan,
   redactSecrets,
   promoteAuditPlans,
+  WHOLE_MATCH_PATTERNS,
+  VALUE_PATTERNS,
+  NEVER_COMMIT_FILENAMES,
+  CI_IAC_LEAK_SHAPES,
   AUDIT_RISKS,
   AUDIT_PRIORITIES,
   AUDIT_EFFORTS,
+  AUDIT_CONFIDENCES,
   AUDIT_CATEGORIES
 };

package/dist/dispatch.d.ts

@@ -172,13 +172,24 @@ export declare function assertTriIdentity(reviewerRoles: readonly string[]): Gat
  */
 export type ComposeDispatchGateOptions = {
     /**
-     * Host role-binding field (omp task entry `agent` / opencode `subagent` /
-     * cursor `subagent_type` / dsh `dispatchBinding`). The anti-recursion
-     * precheck runs for EVERY Assignment-shaped text: an empty or omitted
-     * binding fails closed (`dispatch.anti-recursion.empty-binding`) — the
-     * host cannot prove the dispatching agent is not recursing.
+     * Dispatching agent's OWN harness role (dsh `Config.dispatchBinding`).
+     * When non-empty, the anti-recursion precheck compares it against the
+     * Assignment's `Execute as` — equality is self-recursion
+     * (`dispatch.anti-recursion.self-type`, critical). Leave unset on hosts
+     * whose tool-call event cannot report the dispatching agent's identity
+     * (omp/opencode/cursor): the precheck is skipped there and the NEVER red
+     * line stays prompt-level (mstar-dispatch-gates).
      */
-    agent?: string;
+    caller?: string;
+    /**
+     * True on hosts whose contract declares the caller binding mandatory
+     * (dsh): an empty/missing `caller` then fails closed with
+     * `dispatch.anti-recursion.empty-binding` (critical) — the host could
+     * have declared the binding, so an absent one proves nothing and the
+     * dispatch must not proceed as if the NEVER red line held. Default
+     * `false`: the precheck is skipped entirely when `caller` is empty.
+     */
+    callerRequired?: boolean;
     /**
      * `false` for read-only roles (scout/explore) — skips the branch-form and
      * default-branch gates. Default: `true` (writable).
@@ -206,10 +217,14 @@ export type ComposeDispatchGateResult = GateResult & {
  *    Assignment-shaped passes silently (`shaped: false`).
  * 2. `validateAssignmentFields` with `writable: false` when `opts.writable
  *    === false` (read-only roles), else the writable default.
- * 3. Anti-recursion precheck — runs for every Assignment-shaped text; an
- *    empty/omitted host binding fails closed (`dispatch.anti-recursion.
- *    empty-binding`), a binding equal to `Execute as` is the existing
- *    `dispatch.anti-recursion.self-type` critical.
+ * 3. Anti-recursion precheck — CALLER semantics (issue #156): runs only
+ *    when the host supplies its own role binding (`caller`), or fails
+ *    closed on an empty one when the host contract requires it
+ *    (`callerRequired`, dsh). A caller equal to `Execute as` is the
+ *    `dispatch.anti-recursion.self-type` critical; a required-but-empty
+ *    caller is `dispatch.anti-recursion.empty-binding`. Target-only hosts
+ *    (omp/opencode/cursor) skip the leg — their binding field carries the
+ *    spawn TARGET, which equals `Execute as` on every compliant dispatch.
  * 4. Default-branch gate for writable text: the branch comes from the
  *    Assignment's own branch forms (create-form name / Working branch /
  *    Branch policy branch), else `$MSTAR_WORKING_BRANCH`; a well-formed
@@ -224,13 +239,17 @@ export type ComposeDispatchGateResult = GateResult & {
 export declare function composeDispatchGate(text: string, opts?: ComposeDispatchGateOptions): ComposeDispatchGateResult;
 /**
  * Anti-recursion precheck (NEVER red line, mstar-dispatch-gates § 承接方反递归
- * 红线): a leaf executor MUST NOT invoke a Task/subagent whose role-binding
- * field (`subagent_type` / `agent` / `subagent`) equals its own `Execute as`.
- * Comparison is case-insensitive after trim. An EMPTY binding fails closed
- * (`dispatch.anti-recursion.empty-binding`, critical): the host cannot
- * report which agent is calling, so anti-recursion cannot be proven — the
- * dispatch must not proceed as if the NEVER red line held. An empty
- * `executeAs` with a set binding stays ok (field presence is
- * `validateAssignmentFields`' job, not this precheck).
+ * 红线): a leaf executor MUST NOT dispatch a Task/subagent whose target role
+ * (the new Assignment's `Execute as`) equals its OWN role. `subagentType`
+ * is therefore the DISPATCHING agent's own role binding (dsh
+ * `Config.dispatchBinding`) — never the spawn-target field (omp `agent` /
+ * opencode `subagent`), which equals `Execute as` on every compliant
+ * dispatch (issue #156). Comparison is case-insensitive after trim. An
+ * EMPTY binding fails closed (`dispatch.anti-recursion.empty-binding`,
+ * critical): the host cannot report which agent is calling, so
+ * anti-recursion cannot be proven — the dispatch must not proceed as if
+ * the NEVER red line held. An empty `executeAs` with a set binding stays
+ * ok (field presence is `validateAssignmentFields`' job, not this
+ * precheck).
  */
 export declare function antiRecursionPrecheck(subagentType: string, executeAs: string): GateResult;