@m2-ai/lattice-cli 0.0.0-stage → 0.8.7

package/dist/security-runtime/src/checks/project-scripts/index.mjs

@@ -0,0 +1,187 @@
+// project-scripts (REQ-019): runs the project's own typecheck, lint, test and build scripts (and pytest) with CI=1 and records
+// result, duration and the output tail. This check EXECUTES PROJECT CODE, so it runs only in deep and release (never scan), only
+// when dependencies are already installed (it never installs anything), and with the runner's environment allowlist (no tokens or cloud keys).
+// Release mode: a failing typecheck, test or build blocks (severity high, category "release"); a failing lint is only a warning.
+// Deep mode: every failure is a warning (medium).
+import fs from 'node:fs';
+import path from 'node:path';
+import { scrubText } from '../../core/findings.mjs';
+
+export const id = 'project-scripts';
+export const title = 'Project typecheck, lint, test and build scripts';
+export const modes = ['deep', 'release'];
+export const requiredIn = ['release'];
+// Project scripts may create build output. Run this phase before the artifact scanners.
+export const phase = 1;
+export const SCRIPT_TIMEOUT_SEC = 20 * 60;
+export const timeoutSec = 5 * SCRIPT_TIMEOUT_SEC + 300; // four scripts plus pytest, each with its own 20 minute limit
+export const TAIL_LINES = 40;
+
+// Script names are fixed constants chosen here, never taken from package.json, so every token passed to the package manager is ours.
+const SCRIPTS = [
+  { name: 'typecheck', candidates: ['typecheck', 'type-check', 'tsc'], blocksInRelease: true },
+  { name: 'lint', candidates: ['lint'], blocksInRelease: false },
+  { name: 'test', candidates: ['test'], blocksInRelease: true },
+  { name: 'build', candidates: ['build'], blocksInRelease: true },
+];
+const MANAGER_ORDER = ['pnpm', 'yarn', 'bun', 'npm']; // lockfile-derived manager names from detect.mjs
+const NOTICE = 'vsg executed the project\'s own scripts (project code ran) with CI=1 and an allowlisted environment: no tokens or cloud keys were passed, and nothing was installed.';
+
+const exists = (p) => { try { return fs.statSync(p); } catch { return null; } };
+const readJson = (p) => { try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; } };
+const read = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch { return ''; } };
+
+function hasPytest(repo) {
+  if (exists(path.join(repo, 'pytest.ini')) || exists(path.join(repo, 'conftest.py'))) return true;
+  if (exists(path.join(repo, 'tests'))?.isDirectory()) return true;
+  return /\[pytest\]/.test(read(path.join(repo, 'tox.ini'))) || /\[tool:pytest\]/.test(read(path.join(repo, 'setup.cfg')))
+    || /\[tool\.pytest/.test(read(path.join(repo, 'pyproject.toml')));
+}
+
+export function applies(ctx) {
+  return exists(path.join(ctx.repo, 'package.json')) || hasPytest(ctx.repo)
+    ? true
+    : { applies: false, reason: 'no package.json and no pytest configuration or tests directory' };
+}
+
+/** Finds an executable on PATH (the current directory is never searched). Returns the full path or null. */
+export function findOnPath(name, env = process.env) {
+  const win = process.platform === 'win32';
+  const exts = win ? (env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean) : [''];
+  const dirs = (env.PATH || env.Path || '').split(path.delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    for (const ext of exts) {
+      const full = path.join(dir, `${name}${ext}`);
+      if (exists(full)?.isFile()) return full;
+    }
+  }
+  return null;
+}
+
+/**
+ * Builds the spawn arguments for "<manager> run <script>" without a shell string.
+ * Node 22 refuses to spawn .cmd files directly on Windows, and the package managers are .cmd shims there. The shim is started through
+ * cmd.exe with every argument passed separately (cmd.exe /d /s /c <manager> run <script>): all tokens are fixed constants made of
+ * letters and dashes, so nothing needs quoting and nothing from the repository reaches the command line. Elsewhere (and for bun.exe)
+ * the resolved executable is spawned directly.
+ */
+export function packageManagerCommand(manager, script, resolved) {
+  if (process.platform === 'win32' && /\.(cmd|bat)$/i.test(resolved)) {
+    return { command: process.env.ComSpec || 'cmd.exe', args: ['/d', '/s', '/c', manager, 'run', script] };
+  }
+  return { command: resolved, args: ['run', script] };
+}
+
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;?]*[A-Za-z]`, 'g');
+export function tailOf(stdout, stderr, lines = TAIL_LINES) {
+  const all = `${stdout}\n${stderr}`.replace(ANSI, '').split(/\r?\n/).map((l) => l.trimEnd());
+  while (all.length && !all[all.length - 1]) all.pop();
+  return scrubText(all.slice(-lines).join('\n'));
+}
+
+function chooseManager(ctx) {
+  const roots = (ctx.detection.lockfiles ?? []).filter((l) => !l.file.includes('/')).map((l) => l.manager);
+  const found = MANAGER_ORDER.find((m) => roots.includes(m));
+  return { manager: found ?? 'npm', fromLockfile: !!found };
+}
+
+async function execScript(ctx, { name, label, command, args, extraEnvNames = [] }) {
+  const r = await ctx.runProcess({
+    command, args, cwd: ctx.repo, timeoutMs: SCRIPT_TIMEOUT_SEC * 1000, maxOutputBytes: 8 * 1024 * 1024,
+    envNames: ['PNPM_HOME', ...extraEnvNames], extraEnv: { CI: '1' },
+  });
+  const base = { name, command: label, durationMs: r.durationMs };
+  if (r.status !== 'ran') return { ...base, status: /timed out/.test(r.reason ?? '') ? 'timed_out' : 'not_run', reason: r.reason, outputTail: tailOf(r.stdout ?? '', r.stderr ?? '') };
+  return { ...base, status: r.exitCode === 0 ? 'passed' : 'failed', exitCode: r.exitCode, outputTail: tailOf(r.stdout, r.stderr) };
+}
+
+export async function run(ctx) {
+  const results = {};
+  const evidenceNote = { notice: NOTICE };
+  const release = ctx.mode === 'release';
+  const notRunReasons = [];
+
+  // ---- package.json scripts ----
+  const pkgPath = path.join(ctx.repo, 'package.json');
+  if (exists(pkgPath)) {
+    const scripts = readJson(pkgPath)?.scripts ?? {};
+    const planned = SCRIPTS.map((s) => {
+      const script = s.candidates.find((c) => typeof scripts[c] === 'string');
+      if (!script) return { ...s, status: 'not_applicable', reason: `package.json has no ${s.candidates.join('/')} script` };
+      if (s.name === 'test' && /no test specified/i.test(scripts[script])) return { ...s, status: 'not_applicable', reason: 'the test script is the npm init placeholder' };
+      return { ...s, script };
+    });
+    const { manager, fromLockfile } = chooseManager(ctx);
+    evidenceNote.packageManager = `${manager}${fromLockfile ? ' (from the lockfile)' : ' (no lockfile found: default)'}`;
+    const toRun = planned.filter((p) => p.script);
+    for (const p of planned.filter((x) => !x.script)) results[p.name] = { name: p.name, status: 'not_applicable', reason: p.reason };
+    if (toRun.length) {
+      const modules = exists(path.join(ctx.repo, 'node_modules'));
+      const resolved = findOnPath(manager);
+      let why = '';
+      if (!modules?.isDirectory()) why = 'dependencies not installed';
+      else if (!resolved) why = `${manager} was not found on PATH`;
+      if (why) {
+        for (const p of toRun) results[p.name] = { name: p.name, script: p.script, status: 'not_run', reason: why };
+        notRunReasons.push(`${toRun.map((p) => p.name).join(', ')}: ${why}`);
+      } else {
+        for (const p of toRun) {
+          const { command, args } = packageManagerCommand(manager, p.script, resolved);
+          results[p.name] = { ...(await execScript(ctx, { name: p.name, label: `${manager} run ${p.script}`, command, args })), script: p.script, blocksInRelease: p.blocksInRelease };
+        }
+      }
+    }
+  }
+
+  // ---- pytest ----
+  if (hasPytest(ctx.repo)) {
+    const python = ['python', 'python3'].map((n) => findOnPath(n)).find(Boolean);
+    if (!python) {
+      results.pytest = { name: 'pytest', status: 'not_run', reason: 'python was not found on PATH' };
+      notRunReasons.push('pytest: python was not found on PATH');
+    } else {
+      const r = await execScript(ctx, { name: 'pytest', label: 'python -m pytest -q', command: python, args: ['-m', 'pytest', '-q'], extraEnvNames: ['VIRTUAL_ENV', 'PYTHONPATH'] });
+      if (r.status === 'failed' && /No module named '?pytest/.test(r.outputTail)) {
+        results.pytest = { name: 'pytest', status: 'not_run', reason: 'pytest is not installed in this Python environment' };
+        notRunReasons.push('pytest: pytest is not installed in this Python environment');
+      } else if (r.status === 'failed' && r.exitCode === 5) {
+        results.pytest = { ...r, status: 'not_applicable', reason: 'pytest collected no tests' };
+      } else results.pytest = { ...r, blocksInRelease: true };
+    }
+  }
+
+  // ---- findings ----
+  const findings = [];
+  for (const r of Object.values(results)) {
+    if (r.status !== 'failed' && r.status !== 'timed_out') continue;
+    const blocks = release && r.blocksInRelease;
+    const what = r.status === 'timed_out' ? `timed out after ${SCRIPT_TIMEOUT_SEC / 60} minutes` : `failed with exit code ${r.exitCode}`;
+    findings.push({
+      tool: 'project-scripts', ruleId: `script-${r.name}`, key: `script-${r.name}`, category: 'release',
+      severity: blocks ? 'high' : 'medium', confidence: 'confirmed',
+      title: `Project ${r.name} ${r.status === 'timed_out' ? 'timed out' : 'failed'}`,
+      description: `\`${r.command}\` ${what} (${Math.round(r.durationMs / 100) / 10} s).${blocks ? '' : release ? ' A failing lint only warns.' : ' Deep mode reports script failures as warnings; release mode blocks on a failing typecheck, test or build.'}`,
+      evidence: r.outputTail,
+      fix: `Fix the ${r.name} failure and rerun vsg. The last ${TAIL_LINES} lines of output are in raw/project-scripts/${r.name}.txt.`,
+      location: { file: r.name === 'pytest' ? 'pytest' : 'package.json' },
+    });
+  }
+
+  const evidence = { 'summary.json': { ...evidenceNote, scripts: Object.fromEntries(Object.entries(results).map(([k, v]) => [k, { ...v, outputTail: undefined }])) } };
+  for (const r of Object.values(results)) if (r.outputTail) evidence[`${r.name}.txt`] = `$ ${r.command} (exit ${r.exitCode ?? r.status}, ${r.durationMs} ms)\n${r.outputTail}\n`;
+
+  const ranAny = Object.values(results).some((r) => ['passed', 'failed', 'timed_out'].includes(r.status));
+  const executed = ranAny ? NOTICE : 'No project code was executed.';
+  // Nothing verified: fail closed. If a release-blocking failure exists the verdict is BLOCKED anyway, so the findings are kept.
+  if (notRunReasons.length && !findings.some((f) => f.severity === 'high')) {
+    return { status: 'not_run', reason: `${notRunReasons.join('; ')}. ${executed}`, evidence };
+  }
+  const summary = Object.values(results).map((r) => `${r.name}: ${r.status}`).join(', ');
+  return {
+    status: 'ran', reason: notRunReasons.length ? `some scripts did not run (${notRunReasons.join('; ')})` : '', findings,
+    dataVersions: { projectCode: executed, scripts: summary || 'none' },
+    evidence,
+  };
+}
+
+export default { id, title, modes, requiredIn, phase, timeoutSec, applies, run };

package/dist/security-runtime/src/checks/sbom/index.mjs

@@ -0,0 +1,98 @@
+// sbom (REQ-020): a CycloneDX 1.5 SBOM from OSV-Scanner, validated before it is kept. Written to raw/sbom/sbom.cdx.json by the report writer.
+// A SBOM that is malformed, or that is missing a package from a supported lockfile, makes the check not_run so release cannot pass on a partial SBOM.
+import fs from 'node:fs';
+import path from 'node:path';
+import { osvExcludeArgs } from '../_lib/osv.mjs';
+import { keyOf, lockfileKind, normPyName, parseLockfile } from '../_lib/lockfiles.mjs';
+
+export const id = 'sbom';
+export const title = 'CycloneDX 1.5 software bill of materials';
+export const modes = ['release'];
+export const requiredIn = ['release'];
+export const timeoutSec = 600;
+
+const base = (f) => f.slice(f.lastIndexOf('/') + 1);
+
+export function applies(ctx) {
+  const d = ctx.detection;
+  return d.lockfiles.length > 0 || (d.manifests ?? []).some((m) => /^requirements.*\.txt$/.test(base(m)))
+    ? true
+    : { applies: false, reason: 'no lockfile or requirements file was found' };
+}
+
+/** Component key in the same form as keyOf: ecosystem:name@version. */
+function componentKey(c) {
+  const purl = typeof c.purl === 'string' ? /^pkg:(npm|pypi)\/([^@?#]+)@([^?#]+)/i.exec(c.purl) : null;
+  if (purl) {
+    const eco = purl[1].toLowerCase() === 'pypi' ? 'PyPI' : 'npm';
+    const name = decodeURIComponent(purl[2]);
+    return `${eco}:${eco === 'PyPI' ? normPyName(name) : name}@${decodeURIComponent(purl[3])}`;
+  }
+  return null;
+}
+
+/** Returns a list of problems (empty when the document is a minimal valid CycloneDX 1.5 BOM). */
+export function validateCycloneDx(bom) {
+  const problems = [];
+  if (!bom || typeof bom !== 'object') return ['not a JSON object'];
+  if (bom.bomFormat !== 'CycloneDX') problems.push('bomFormat must be "CycloneDX"');
+  if (bom.specVersion !== '1.5') problems.push(`specVersion must be "1.5" (got ${JSON.stringify(bom.specVersion)})`);
+  if (!Array.isArray(bom.components)) problems.push('components must be an array');
+  else {
+    bom.components.forEach((c, i) => {
+      if (typeof c?.name !== 'string' || !c.name) problems.push(`components[${i}] has no name`);
+      if (!['library', 'application', 'framework', 'container', 'device', 'file', 'firmware', 'operating-system', 'platform', 'machine-learning-model', 'data', 'device-driver', 'cryptographic-asset'].includes(c?.type)) problems.push(`components[${i}] has an invalid type`);
+    });
+  }
+  return problems.slice(0, 10);
+}
+
+/** Every pinned package of every supported lockfile in the repository, as keyOf keys. */
+export function lockfilePackages(ctx) {
+  const files = [...ctx.detection.lockfiles.map((l) => l.file), ...(ctx.detection.manifests ?? [])].filter((f) => lockfileKind(f));
+  const keys = new Map();
+  const unreadable = [];
+  for (const file of files) {
+    try {
+      for (const p of parseLockfile(file, fs.readFileSync(path.join(ctx.repo, file), 'utf8')) ?? []) keys.set(keyOf(p), `${p.name}@${p.version} (${file})`);
+    } catch { unreadable.push(file); }
+  }
+  const unsupported = ctx.detection.lockfiles.map((l) => l.file).filter((f) => !lockfileKind(f));
+  return { keys, unreadable, unsupported };
+}
+
+export async function run(ctx) {
+  const res = await ctx.runTool('osv-scanner', [
+    'scan', 'source', '-r', '--format', 'cyclonedx-1-5', '--all-packages', '--no-resolve', '--allow-no-lockfiles', '--no-ignore',
+    ...osvExcludeArgs(ctx),
+    '.',
+  ]);
+  if (res.status !== 'ran') return { status: 'not_run', reason: res.reason };
+  if (res.truncated) return { status: 'not_run', reason: 'OSV-Scanner output was too large to read completely.' };
+  if (res.exitCode !== 0 && res.exitCode !== 1) {
+    const tail = res.stderr.trim().split(/\r?\n/).slice(-3).join(' | ');
+    return { status: 'not_run', reason: `OSV-Scanner failed with exit code ${res.exitCode}${tail ? `: ${tail}` : ''}.` };
+  }
+  let bom;
+  try { bom = JSON.parse(res.stdout.replace(/^/, '')); } catch { return { status: 'not_run', reason: 'OSV-Scanner did not return a JSON SBOM.' }; }
+  const problems = validateCycloneDx(bom);
+  if (problems.length) return { status: 'not_run', reason: `The SBOM is not valid CycloneDX 1.5: ${problems.join('; ')}.` };
+
+  const { keys, unreadable, unsupported } = lockfilePackages(ctx);
+  const have = new Set(bom.components.map(componentKey).filter(Boolean));
+  const missing = [...keys].filter(([k]) => !have.has(k)).map(([, label]) => label);
+  if (missing.length) {
+    return { status: 'not_run', reason: `The SBOM is missing ${missing.length} of ${keys.size} lockfile packages (for example ${missing.slice(0, 3).join(', ')}).` };
+  }
+  const notes = [
+    ...(unsupported.length ? [`${unsupported.join(', ')} is not a lockfile type vsg can compare against, so its completeness was not verified`] : []),
+    ...(unreadable.length ? [`could not read ${unreadable.join(', ')} for the completeness check`] : []),
+  ];
+  return {
+    status: 'ran', reason: notes.join('; '), findings: [], toolVersion: ctx.registry?.get('osv-scanner')?.version ?? null,
+    dataVersions: { sbom: `CycloneDX 1.5, ${bom.components.length} components, ${keys.size} lockfile packages verified` },
+    evidence: { 'sbom.cdx.json': `${JSON.stringify(bom, null, 2)}\n` },
+  };
+}
+
+export default { id, title, modes, requiredIn, timeoutSec, applies, run };

package/dist/security-runtime/src/checks/secrets-build/index.mjs

@@ -0,0 +1,63 @@
+// secrets-build (REQ-012): Betterleaks over build output (.next, dist, build, out) in deep and release runs.
+// Not a required check: a repository without build output has nothing to scan, and release mode builds first (REQ-019).
+import fs from 'node:fs';
+import path from 'node:path';
+import { demoJwtFinding, hitToFinding, ROTATE, runBetterleaks, supabasePublicKeyFinding } from '../_lib/secrets.mjs';
+
+export const id = 'secrets-build';
+export const title = 'Secrets in build output';
+export const modes = ['deep', 'release'];
+export const requiredIn = [];
+// The check is optional when no build output exists, but becomes required once output is present.
+export const requiredIfApplied = true;
+export const phase = 2;
+export const timeoutSec = 1800;
+
+const BUILD_DIRS = new Set(['.next', 'dist', 'build', 'out']);
+const SKIP_DIRS = new Set(['node_modules', '.git', '.vsg', '.venv', 'venv', '__pycache__', '.pnpm-store']);
+const MAX_DEPTH = 4;
+// framework caches duplicate the real output and are very large
+const SKIP = [String.raw`(?:^|/)node_modules/`, String.raw`(?:^|/)\.next/cache/`, String.raw`^\.vsg/`];
+
+/** Build output directories (relative posix paths), found without following symlinks. */
+export function findBuildDirs(repo, nested = []) {
+  const found = [];
+  const skipNested = new Set(nested.map((n) => n.path));
+  const walk = (dir, depth) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (!e.isDirectory() || e.isSymbolicLink() || SKIP_DIRS.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      if (skipNested.has(path.relative(repo, full).split(path.sep).join('/'))) continue;
+      if (BUILD_DIRS.has(e.name)) found.push(path.relative(repo, full).split(path.sep).join('/'));
+      else if (depth < MAX_DEPTH) walk(full, depth + 1);
+    }
+  };
+  walk(repo, 0);
+  return found.sort();
+}
+
+export function applies(ctx) {
+  return findBuildDirs(ctx.repo, ctx.nestedRepos).length > 0 ? true : { applies: false, reason: 'no build output (.next, dist, build or out) found' };
+}
+
+export async function run(ctx) {
+  const dirs = findBuildDirs(ctx.repo, ctx.nestedRepos);
+  if (!dirs.length) return { status: 'not_applicable', reason: 'no build output (.next, dist, build or out) found' };
+  const validate = !ctx.flags?.noValidate;
+  const scan = await runBetterleaks(ctx, { kind: 'dir', paths: dirs, validate, skip: SKIP });
+  if (scan.status !== 'ran') return { status: 'not_run', reason: scan.reason };
+  const demo = demoJwtFinding(scan.demoJwts, { where: 'in build output' });
+  const publicKey = supabasePublicKeyFinding(scan.publicKeys, { where: 'in build output' });
+  const findings = [...scan.hits.map((h) => hitToFinding(h, {
+    category: 'secret', severity: 'critical', where: 'in build output',
+    fix: `${ROTATE} Then find which source value or environment variable reached the bundle (public-prefixed variables are compiled into client code) and rebuild.`,
+  })), ...(demo ? [demo] : []), ...(publicKey ? [publicKey] : [])];
+  return {
+    status: 'ran', reason: '', findings, toolVersion: ctx.registry?.get('betterleaks')?.version ?? null,
+    evidence: { directories: dirs, hits: scan.hits.length, filteredLocalizationNoise: scan.filtered, suppressed: scan.suppressed, validated: validate },
+  };
+}
+
+export default { id, title, modes, requiredIn, requiredIfApplied, phase, timeoutSec, applies, run };

package/dist/security-runtime/src/checks/secrets-history/index.mjs

@@ -0,0 +1,112 @@
+// secrets-history (REQ-012): Betterleaks over the full git history (deep and release).
+// Blocking policy: a secret only in history blocks at High unless validated inactive, so inactive ones are emitted at Medium.
+// REQ-037: the same value in several files or commits is one finding; a low-precision generic-rule hit in a file that no longer exists
+// is "history only" and does not block.
+import fs from 'node:fs';
+import path from 'node:path';
+import { severityRank } from '../../core/findings.mjs';
+import { demoJwtFinding, effectiveSeverity, gitState, hitToFinding, ignoredPaths, isGenericRule, ROTATE, runBetterleaks, skipPatterns, supabasePublicKeyFinding } from '../_lib/secrets.mjs';
+
+export const id = 'secrets-history';
+export const title = 'Secrets in git history';
+export const modes = ['deep', 'release'];
+export const requiredIn = ['deep', 'release'];
+export const timeoutSec = 1800;
+
+const MAX_LOCATIONS = 25;
+const locationLines = (members) => {
+  const lines = members.slice(0, MAX_LOCATIONS).map((m) => {
+    const c = m.commits;
+    const commits = c.length ? `${c.length} commit${c.length === 1 ? '' : 's'}: ${c.slice(0, 3).map((x) => x.slice(0, 12)).join(', ')}${c.length > 3 ? ', ...' : ''}` : 'no commit';
+    return `${m.file}${m.line ? `:${m.line}` : ''} (${m.ruleId}; ${commits})`;
+  });
+  if (members.length > MAX_LOCATIONS) lines.push(`and ${members.length - MAX_LOCATIONS} more`);
+  return lines.join('\n');
+};
+
+/**
+ * One group per secret value (hash): the same value in several files or commits is one finding, and its severity is the worst member's.
+ * A generic-rule hit whose file no longer exists in the tree is "history only" and capped at Medium; a group is history only when every
+ * member is such a hit. Returns [{ rep, members, severity, historyOnly }].
+ */
+export function groupHistoryHits(hits, exists) {
+  const base = (h) => (h.validation.state === 'valid' ? 'critical' : h.validation.state === 'inactive' ? 'medium' : 'high');
+  const gone = (h) => isGenericRule(h.ruleId) && h.validation.state !== 'valid' && !exists(h.file);
+  const sevOf = (h) => effectiveSeverity(h, gone(h) ? 'medium' : base(h));
+  const byHash = new Map();
+  for (const h of hits) {
+    if (!byHash.has(h.hash)) byHash.set(h.hash, []);
+    byHash.get(h.hash).push(h);
+  }
+  return [...byHash.values()].map((members) => {
+    members.sort((a, b) => severityRank(sevOf(b)) - severityRank(sevOf(a))
+      || Number(isGenericRule(a.ruleId)) - Number(isGenericRule(b.ruleId))
+      || `${a.file}:${a.line ?? 0}`.localeCompare(`${b.file}:${b.line ?? 0}`));
+    const rep = members[0];
+    const historyOnly = members.every(gone);
+    return { rep, members, severity: sevOf(rep), historyOnly };
+  });
+}
+
+export async function applies(ctx) {
+  const s = await gitState(ctx);
+  if (!s.usable) return { applies: false, reason: 'not a git repository, so there is no history to scan' };
+  if (!s.hasCommits) return { applies: false, reason: 'the repository has no commits yet' };
+  return true;
+}
+
+export async function run(ctx) {
+  const s = await gitState(ctx);
+  // A truncated history cannot support a "no secrets in history" result, so the check does not claim it.
+  if (s.shallow) return { status: 'not_run', reason: 'This is a shallow clone, so older commits are missing. Fetch the full history (git fetch --unshallow) and run again.' };
+  const validate = !ctx.flags?.noValidate;
+  const scan = await runBetterleaks(ctx, { kind: 'git', validate });
+  if (scan.status !== 'ran') return { status: 'not_run', reason: scan.reason };
+  // A value that is still in the working tree is already reported by secrets-tree (same rule, file and value), so it is not repeated as a
+  // history finding. Rotation is required either way and the tree finding says so. The commits are kept in evidence.
+  const alsoInTree = [];
+  let hits = scan.hits;
+  if (hits.length) {
+    const tree = await runBetterleaks(ctx, { kind: 'dir', paths: ['.'], validate: false, skip: skipPatterns(await ignoredPaths(ctx)) });
+    if (tree.status === 'ran') {
+      const keyOf = (h) => JSON.stringify([h.ruleId, h.file, h.hash]);
+      const inTree = new Set(tree.hits.map(keyOf));
+      hits = hits.filter((h) => {
+        if (!inTree.has(keyOf(h))) return true;
+        alsoInTree.push({ ruleId: h.ruleId, file: h.file, commits: h.commits.slice(0, 5).map((c) => c.slice(0, 12)), commitCount: h.commits.length });
+        return false;
+      });
+    }
+  }
+  const exists = (file) => { try { return fs.existsSync(path.join(ctx.repo, file)); } catch { return false; } };
+  const groups = groupHistoryHits(hits, exists);
+  const findings = groups.map(({ rep, members, severity, historyOnly }) => {
+    const commits = [...new Set(members.flatMap((m) => m.commits))];
+    const f = hitToFinding(rep, {
+      category: 'secret-history',
+      severity,
+      where: historyOnly ? 'in git history (history only)' : 'in git history',
+      extra: `${commits.length ? ` First seen in commit ${commits[0].slice(0, 12)}${commits.length > 1 ? ` and ${commits.length - 1} more` : ''}.` : ''}${historyOnly ? ' History only: the file no longer exists in the current tree and the rule is a low-precision generic one, so this does not block.' : ''}${members.length > 1 ? ` The same value appears in ${members.length} places (listed in the evidence).` : ''}`,
+      fix: `${ROTATE} Removing the file now does not help: the value stays in every earlier commit and clone until the history is rewritten or the credential is revoked. Rotation is the fix; rewrite history only if the repository must stay private to the value.`,
+    });
+    if (members.length > 1) f.evidence += `\n${members.length} locations:\n${locationLines(members)}`;
+    if (rep.validation.state === 'inactive') f.confidence = 'high';
+    return f;
+  });
+  const demo = demoJwtFinding(scan.demoJwts, { where: 'in git history' });
+  if (demo) findings.push(demo);
+  const publicKey = supabasePublicKeyFinding(scan.publicKeys, { where: 'in git history' });
+  if (publicKey) findings.push(publicKey);
+  return {
+    status: 'ran',
+    reason: validate ? '' : 'credential validation was disabled by --no-validate',
+    findings, toolVersion: ctx.registry?.get('betterleaks')?.version ?? null,
+    evidence: {
+      hits: scan.hits.length, reported: findings.length, groupedByValue: hits.length - groups.length, historyOnly: groups.filter((g) => g.historyOnly).length,
+      filteredLocalizationNoise: scan.filtered, suppressed: scan.suppressed,
+      duplicatesOfWorkingTree: alsoInTree.length, duplicatesOfWorkingTreeSample: alsoInTree.slice(0, 20), validated: validate,
+    },
+  };
+}
+
+export default { id, title, modes, requiredIn, timeoutSec, applies, run };

package/dist/security-runtime/src/checks/secrets-tree/env.mjs

@@ -0,0 +1,120 @@
+// Environment exposure (REQ-012): secret-named variables with a public (browser-bundled) prefix, and committed .env files.
+// Reports names and locations only. Values are never read into a finding.
+import fs from 'node:fs';
+import path from 'node:path';
+import { jwtClaims, supabasePublicKeyKind } from '../_lib/secrets.mjs';
+
+const PUBLIC_NAME = /\b((?:NEXT_PUBLIC|EXPO_PUBLIC|VITE)_[A-Z0-9_]*[A-Z0-9])\b/g;
+const SECRETISH = /SECRET|SERVICE_ROLE|PRIVATE|PASSWORD|TOKEN/;
+const SAFE = /PUBLISHABLE|ANON|PUBLIC_KEY|SITE_KEY/;
+const TEXT_FILE = /(\.(?:[cm]?[jt]sx?|vue|svelte|astro|html|json|ya?ml|toml|sh)|\.env[^/]*)$/i;
+const SKIP_FILE = /(?:^|\/)(?:package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?|tsconfig[^/]*\.json)$|\.min\.js$/;
+const EXAMPLE = /\.(?:example|sample|template|dist)$/i;
+const MAX_BYTES = 1024 * 1024;
+
+const base = (f) => f.slice(f.lastIndexOf('/') + 1);
+export const isEnvFile = (f) => /^\.env(\..+)?$/.test(base(f));
+
+/** True when a public-prefixed variable name indicates a secret and is not a known-public key kind. */
+export function isSecretPublicName(name) {
+  return /SECRET|SERVICE_ROLE|PRIVATE|PASSWORD/.test(name) || (SECRETISH.test(name) && !SAFE.test(name));
+}
+
+const severityOf = (name) => (/SERVICE_ROLE|SECRET|PRIVATE/.test(name) ? 'critical' : 'high');
+
+/** files: relative posix paths; tracked: Set of committed paths or null when there is no git view. Returns raw findings. */
+export function envExposure(repo, files, tracked) {
+  const out = [];
+  const seen = new Map();
+  const byDesign = new Map();
+  for (const file of files) {
+    if (isEnvFile(file) && !EXAMPLE.test(file)) {
+      const committed = tracked ? tracked.has(file) : null;
+      out.push({
+        category: 'config', severity: committed === false ? 'medium' : 'high', confidence: committed === null ? 'medium' : 'high', key: `env-file:${file}`,
+        tool: 'vsg', ruleId: 'committed-env-file', location: { file },
+        title: committed === false ? `Environment file ${file} is not ignored by git` : `Environment file ${file} is committed`,
+        description: committed === null
+          ? 'Environment files hold real configuration and secrets and must not be shared with the code. This directory has no git history to confirm whether the file is committed.'
+          : committed ? 'Environment files hold real configuration and secrets, and a committed copy stays in history even after it is deleted.'
+            : 'The file is not committed yet but .gitignore does not exclude it, so the next "git add ." would commit it.',
+        evidence: file, refs: [],
+        fix: `Keep only a ${base(file).replace(/^(\.env)(\..+)?$/, '$1')}.example file with placeholder values in git. Add ${file} to .gitignore${committed ? ', run "git rm --cached ' + file + '", and rotate every secret it contained' : ''}.`,
+      });
+    }
+    if (!TEXT_FILE.test(file) || SKIP_FILE.test(file)) continue;
+    let text;
+    try {
+      const full = path.join(repo, file);
+      if (fs.statSync(full).size > MAX_BYTES) continue;
+      text = fs.readFileSync(full, 'utf8');
+    } catch { continue; }
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      for (const m of lines[i].matchAll(PUBLIC_NAME)) {
+        const name = m[1];
+        const value = valueAfter(lines[i], m.index + name.length);
+        if (!isSecretPublicName(name) && !looksPrivate(value)) continue;
+        const k = `${file}\0${name}`;
+        if (seen.has(k)) continue;
+        seen.set(k, true);
+        const kind = publicByDesign(name, value);
+        if (kind) {
+          if (!byDesign.has(name)) byDesign.set(name, { kind, hits: [] });
+          byDesign.get(name).hits.push(`${file}:${i + 1}`);
+          continue;
+        }
+        out.push({
+          category: 'secret', severity: severityOf(name), confidence: 'high', key: `public-env:${name}`, tool: 'vsg', ruleId: 'public-env-secret',
+          location: { file, line: i + 1 },
+          title: `Secret-named variable ${name} is exposed to the browser`,
+          description: `Variables starting with ${/^(?:NEXT_PUBLIC_|EXPO_PUBLIC_|VITE_)/.exec(name)[0]} are compiled into client-side JavaScript that anyone can read. The name ${name} indicates a secret.`,
+          evidence: `${name} at ${file} line ${i + 1}`, refs: [],
+          fix: `Rename it without the public prefix, read it only in server code, and rotate the credential because it may already be in a shipped bundle. Public keys such as publishable or anon keys are fine to expose.`,
+        });
+      }
+    }
+  }
+  // Public-by-design keys: one info finding per variable name, not a secret.
+  for (const [name, { kind, hits }] of byDesign) {
+    out.push({
+      category: 'secret', severity: 'info', confidence: 'high', key: `public-by-design:${name}`, tool: 'vsg', ruleId: 'public-env-public-by-design',
+      location: { file: hits[0].replace(/:\d+$/, ''), line: Number(/:(\d+)$/.exec(hits[0])[1]) },
+      title: `${name} is a ${kind}, public by design`,
+      description: `${name} has a secret-looking name but holds a ${kind}, which is meant to be shipped to the browser. It is not a secret. Reported once per variable.`,
+      evidence: `${name} at ${hits.slice(0, 10).join(', ')}${hits.length > 10 ? `, and ${hits.length - 10} more` : ''}`, refs: [],
+      fix: 'No action needed. Confirm the key is restricted to your domains or origins where the vendor supports it.',
+    });
+  }
+  return out;
+}
+
+// ---- public-by-design values and names (REQ-037) ----
+// A secret-looking name is accepted when the value (when one is on the line) has a known public shape, or when the name belongs to a
+// known public-key family and the value, if present, is not a recognizable secret. Values are inspected here and never stored.
+const RULES = [
+  { kind: 'PostHog project key', name: /POSTHOG/, value: /^phc_[A-Za-z0-9]{16,}$/ },
+  { kind: 'Sentry DSN', name: /SENTRY[A-Z0-9_]*DSN|DSN[A-Z0-9_]*SENTRY/, value: /^https:\/\/[0-9a-f]{16,64}(?::[^@/\s]*)?@[^/\s]+\/\d+$/i },
+  { kind: 'Stripe publishable key', name: /STRIPE[A-Z0-9_]*(?:PUBLISHABLE|_PK)/, value: /^pk_(?:live|test)_[A-Za-z0-9]{8,}$/ },
+  { kind: 'Supabase anon key', name: /SUPABASE[A-Z0-9_]*ANON/, value: (v) => supabasePublicKeyKind(v) === 'anon key' },
+  { kind: 'Supabase publishable key', name: /SUPABASE[A-Z0-9_]*PUBLISHABLE/, value: (v) => supabasePublicKeyKind(v) === 'publishable key' },
+  { kind: 'Google Maps browser key', name: /(?:GOOGLE|GMAPS|MAPS)[A-Z0-9_]*(?:KEY|TOKEN)/, value: /^AIza[0-9A-Za-z_-]{30,}$/ },
+  { kind: 'Mapbox public token', name: /MAPBOX/, value: /^pk\.[A-Za-z0-9._-]{20,}$/ },
+];
+const matchesValue = (rule, v) => (typeof rule.value === 'function' ? rule.value(v) : rule.value.test(v));
+/** A value that is clearly a private credential (so a public-looking name must not excuse it). */
+const looksPrivate = (v) => /^(?:sk[_.-]|rk_|ghp_|gho_|github_pat_|AKIA|xox[abprs]-|phx_|sb_secret_)/.test(v) || (!!jwtClaims(v) && !supabasePublicKeyKind(v));
+const usable = (v) => !!v && /^[A-Za-z0-9._~+/=:@%-]{8,}$/.test(v) && !/^(?:process|import|env|\$)/.test(v);
+
+/** The text after NAME on a line, as a value: `NAME=value`, `NAME: "value"`. Empty for a bare reference such as process.env.NAME. */
+const valueAfter = (line, from) => /^\s*[:=]\s*["'`]?([^\s"'`,;)}\]]+)/.exec(line.slice(from))?.[1] ?? '';
+
+/** The kind of public-by-design key a variable holds ('' when it is not one). */
+export function publicByDesign(name, value = '') {
+  if (usable(value)) {
+    const byValue = RULES.find((r) => matchesValue(r, value));
+    if (byValue) return byValue.kind;
+    return '';
+  }
+  return RULES.find((r) => r.name.test(name))?.kind ?? '';
+}