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

package/dist/security-runtime/src/core/archive.mjs

@@ -0,0 +1,114 @@
+// Archive extraction with Node built-ins only (zip and tar.gz). Every entry path is validated before anything is written.
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { InstallError } from './errors.mjs';
+
+const MAX_TOTAL = 4 * 1024 ** 3;
+
+/** Resolves an archive entry name inside root, or throws if it would escape (absolute, drive letter, "..", NUL). */
+export function safeJoin(root, name) {
+  const n = String(name).replace(/\\/g, '/');
+  if (!n || n.includes('\0') || n.startsWith('/') || /^[A-Za-z]:/.test(n) || n.split('/').includes('..')) {
+    throw new InstallError(`Archive entry "${name}" would escape the install directory. Nothing was extracted.`);
+  }
+  const resolved = path.resolve(root, n);
+  if (resolved !== path.resolve(root) && !resolved.startsWith(path.resolve(root) + path.sep)) {
+    throw new InstallError(`Archive entry "${name}" would escape the install directory. Nothing was extracted.`);
+  }
+  return resolved;
+}
+
+/** Returns [{ name, dir, mode, data() }]. */
+export function listZip(buf) {
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= Math.max(0, buf.length - 65557); i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) { eocd = i; break; }
+  }
+  if (eocd < 0) throw new InstallError('Not a valid zip archive.');
+  const count = buf.readUInt16LE(eocd + 10);
+  let p = buf.readUInt32LE(eocd + 16);
+  if (count === 0xffff || p === 0xffffffff) throw new InstallError('Zip64 archives are not supported.');
+  const entries = [];
+  for (let i = 0; i < count; i++) {
+    if (buf.readUInt32LE(p) !== 0x02014b50) throw new InstallError('Corrupt zip directory.');
+    const madeBy = buf.readUInt16LE(p + 4);
+    const flags = buf.readUInt16LE(p + 8);
+    const method = buf.readUInt16LE(p + 10);
+    const compSize = buf.readUInt32LE(p + 20);
+    const size = buf.readUInt32LE(p + 24);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const commentLen = buf.readUInt16LE(p + 32);
+    const ext = buf.readUInt32LE(p + 38);
+    const local = buf.readUInt32LE(p + 42);
+    const name = buf.toString('utf8', p + 46, p + 46 + nameLen);
+    p += 46 + nameLen + extraLen + commentLen;
+    if (flags & 1) throw new InstallError('Encrypted zip entries are not supported.');
+    const unixType = madeBy >> 8 === 3 ? (ext >>> 16) & 0xf000 : 0;
+    if (unixType === 0xa000) throw new InstallError(`Archive entry "${name}" is a symbolic link, which is not allowed.`);
+    entries.push({
+      name,
+      dir: name.endsWith('/') || name.endsWith('\\'),
+      mode: unixType ? (ext >>> 16) & 0o777 : 0,
+      data() {
+        if (buf.readUInt32LE(local) !== 0x04034b50) throw new InstallError('Corrupt zip entry.');
+        const start = local + 30 + buf.readUInt16LE(local + 26) + buf.readUInt16LE(local + 28);
+        const raw = buf.subarray(start, start + compSize);
+        const out = method === 0 ? raw : method === 8 ? zlib.inflateRawSync(raw, { maxOutputLength: Math.max(size, 1) }) : null;
+        if (!out) throw new InstallError(`Unsupported zip compression method ${method}.`);
+        if (out.length !== size) throw new InstallError(`Zip entry "${name}" has the wrong size.`);
+        return out;
+      },
+      size,
+    });
+  }
+  return entries;
+}
+
+const octal = (b) => parseInt(b.toString('latin1').replace(/\0.*$/s, '').trim() || '0', 8);
+const cstr = (b) => b.toString('utf8').replace(/\0.*$/s, '');
+
+export function listTarGz(gz) {
+  const buf = zlib.gunzipSync(gz, { maxOutputLength: MAX_TOTAL });
+  const entries = [];
+  let pendingName = null;
+  for (let i = 0; i + 512 <= buf.length;) {
+    const h = buf.subarray(i, i + 512);
+    if (h.every((b) => b === 0)) break;
+    let name = cstr(h.subarray(0, 100));
+    if (cstr(h.subarray(257, 262)) === 'ustar' && cstr(h.subarray(345, 500))) name = `${cstr(h.subarray(345, 500))}/${name}`;
+    const size = octal(h.subarray(124, 136));
+    const type = String.fromCharCode(h[156] || 48);
+    const body = buf.subarray(i + 512, i + 512 + size);
+    i += 512 + Math.ceil(size / 512) * 512;
+    if (type === 'x') {
+      for (const m of body.toString('utf8').matchAll(/\d+ path=([^\n]*)\n/g)) pendingName = m[1];
+    } else if (type === 'g') {
+      continue;
+    } else if (type === 'L') {
+      pendingName = cstr(body);
+    } else if (type === '0' || type === '5') {
+      entries.push({ name: pendingName ?? name, dir: type === '5', mode: octal(h.subarray(100, 108)) & 0o777, data: () => body, size });
+      pendingName = null;
+    } else {
+      throw new InstallError(`Archive entry "${name}" has unsupported type "${type}" (links and devices are not allowed).`);
+    }
+  }
+  return entries;
+}
+
+/** Extracts into targetDir (created). All entry names are validated before the first write. */
+export function extractArchive(buf, kind, targetDir) {
+  const entries = kind === 'zip' ? listZip(buf) : kind === 'tar.gz' ? listTarGz(buf) : null;
+  if (!entries) throw new InstallError(`Unknown archive type "${kind}".`);
+  const total = entries.reduce((n, e) => n + (e.size ?? 0), 0);
+  if (total > MAX_TOTAL) throw new InstallError('Archive expands to more than 4 GB.');
+  const planned = entries.map((e) => ({ e, dest: safeJoin(targetDir, e.name) }));
+  fs.mkdirSync(targetDir, { recursive: true });
+  for (const { e, dest } of planned) {
+    if (e.dir) { fs.mkdirSync(dest, { recursive: true }); continue; }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, e.data(), { mode: e.mode & 0o111 ? 0o755 : 0o644 });
+  }
+}

package/dist/security-runtime/src/core/base-ref.mjs

@@ -0,0 +1,43 @@
+// The comparison base for acceptance review (accept.mjs) and dependency changes (checks/dep-change): one resolver, so a report never says
+// "no base ref" while another check found the baseline. Reads git only; the repository's own git config cannot run code (core.fsmonitor off).
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Remote branches tried, in order, when no base is given. actions/checkout never creates origin/HEAD, so a CI run only has origin/<branch>
+ * (the pull request's base branch, or the default branch).
+ */
+export const DEFAULT_BASES = ['origin/HEAD', 'origin/main', 'origin/master'];
+
+const git = (repo, args) => {
+  try {
+    return execFileSync('git', ['-c', 'core.fsmonitor=false', '--no-optional-locks', '-C', repo, ...args], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 20_000 }).trim();
+  } catch {
+    return null;
+  }
+};
+
+const norm = (p) => path.resolve(p).replace(/\\/g, '/').toLowerCase();
+
+/**
+ * { sha, ref, how } of the comparison base, or { sha: null, why }. The base is, in order: the --base flag, vsg.config.json baseRef,
+ * then the merge-base of HEAD with origin/HEAD, origin/main or origin/master. Needs a git repository rooted at the scanned directory.
+ */
+export function resolveBase(repo, { flag, config } = {}) {
+  const top = git(repo, ['rev-parse', '--show-toplevel']);
+  if (top === null || !top) return { sha: null, why: 'the directory is not a git repository' };
+  let same = false;
+  try { same = norm(fs.realpathSync(top)) === norm(fs.realpathSync(repo)); } catch { /* compared below */ }
+  if (!same) return { sha: null, why: 'the scanned directory is not the root of its git repository' };
+  const explicit = flag ?? config?.baseRef;
+  if (explicit) {
+    const sha = git(repo, ['rev-parse', '--verify', '--quiet', `${explicit}^{commit}`]);
+    return sha ? { sha, ref: explicit, how: flag ? '--base' : 'vsg.config.json baseRef' } : { sha: null, why: `base ref "${explicit}" does not exist` };
+  }
+  for (const remote of DEFAULT_BASES) {
+    const sha = git(repo, ['merge-base', 'HEAD', remote]);
+    if (sha) return { sha, ref: remote, how: `merge-base with ${remote}` };
+  }
+  return { sha: null, why: 'no remote default branch (origin/HEAD, origin/main or origin/master) was found' };
+}

package/dist/security-runtime/src/core/checks.mjs

@@ -0,0 +1,39 @@
+// Check discovery: every src/checks/<id>/index.mjs exports { id, title, modes, requiredIn, applies(ctx), run(ctx) }.
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { UsageError } from './errors.mjs';
+import { defaultChecksDir } from './paths.mjs';
+
+const MODES = ['scan', 'deep', 'url', 'release'];
+
+export function validateCheck(c, where) {
+  const bad = (m) => { throw new UsageError(`Check ${where} is invalid: ${m}.`); };
+  if (!c || typeof c.id !== 'string' || !c.id) bad('id is required');
+  if (typeof c.title !== 'string') bad('title is required');
+  if (!Array.isArray(c.modes) || c.modes.some((m) => !MODES.includes(m))) bad('modes must list scan, deep, url or release');
+  if (!Array.isArray(c.requiredIn) || c.requiredIn.some((m) => !MODES.includes(m))) bad('requiredIn must list modes');
+  if (typeof c.applies !== 'function' || typeof c.run !== 'function') bad('applies and run must be functions');
+  return c;
+}
+
+/** Scans each directory for <id>/index.mjs. A later directory overrides an earlier check with the same id (used by tests). */
+export async function discoverChecks(dirs = [defaultChecksDir]) {
+  const byId = new Map();
+  for (const dir of dirs) {
+    let names = [];
+    try { names = fs.readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name).sort(); } catch { continue; }
+    for (const name of names) {
+      const file = path.join(dir, name, 'index.mjs');
+      if (!fs.existsSync(file)) continue;
+      let mod;
+      try { mod = await import(pathToFileURL(file).href); } catch (e) { throw new UsageError(`Check ${name} failed to load: ${e.message}`); }
+      const check = validateCheck(mod.default ?? mod, file);
+      byId.set(check.id, { id: check.id, title: check.title, modes: check.modes, requiredIn: check.requiredIn, applies: check.applies, run: check.run, timeoutSec: check.timeoutSec,
+        // A small phase number is an ordering barrier, not a dependency graph. Checks in one phase still run concurrently.
+        phase: Number.isInteger(check.phase) && check.phase >= 0 ? check.phase : 0,
+        last: check.last === true, requiredIfApplied: check.requiredIfApplied === true });
+    }
+  }
+  return [...byId.values()].sort((a, b) => a.id.localeCompare(b.id));
+}

package/dist/security-runtime/src/core/detect.mjs

@@ -0,0 +1,90 @@
+// Stack detection (REQ-007). Walks the repository once (no symlink following), then applies rule tables.
+import fs from 'node:fs';
+import path from 'node:path';
+import { findNestedRepos, primeNested, primedNested } from './nested.mjs';
+
+const SKIP_DIRS = new Set(['node_modules', '.git', '.vsg', '.next', '.expo', '.venv', 'venv', '__pycache__', '.turbo', '.cache', 'coverage', 'dist', 'build', '.pnpm-store']);
+const MAX_FILES = 100_000;
+const MAX_DEPTH = 10;
+
+const LOCKFILES = {
+  'package-lock.json': 'npm', 'npm-shrinkwrap.json': 'npm', 'pnpm-lock.yaml': 'pnpm', 'yarn.lock': 'yarn', 'bun.lock': 'bun', 'bun.lockb': 'bun',
+  'poetry.lock': 'poetry', 'Pipfile.lock': 'pipenv', 'uv.lock': 'uv', 'Cargo.lock': 'cargo', 'go.sum': 'go', 'composer.lock': 'composer', 'Gemfile.lock': 'bundler',
+};
+const AI_NODE = [/^openai$/, /^@anthropic-ai\//, /^ai$/, /^@ai-sdk\//, /^@google\/generative-ai$/, /^@google\/genai$/, /^langchain$/, /^@langchain\//, /^@mistralai\//, /^groq-sdk$/];
+const AI_PY = ['openai', 'anthropic', 'langchain', 'google-generativeai', 'mistralai', 'groq'];
+
+/** Every file below root (posix relative paths), leaving out nested repositories and worktrees (see nested.mjs). */
+export function listFiles(root, nested = primedNested(root) ?? findNestedRepos(root)) {
+  const skip = new Set(nested.map((n) => n.path));
+  const files = [];
+  const walk = (dir, depth) => {
+    if (depth > MAX_DEPTH || files.length >= MAX_FILES) return;
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (e.isSymbolicLink()) continue;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name) && !skip.has(path.relative(root, full).split(path.sep).join('/'))) walk(full, depth + 1); }
+      else if (e.isFile()) files.push(path.relative(root, full).split(path.sep).join('/'));
+    }
+  };
+  walk(root, 0);
+  return files.sort();
+}
+
+const readText = (root, rel) => { try { return fs.readFileSync(path.join(root, rel), 'utf8'); } catch { return ''; } };
+const base = (f) => f.slice(f.lastIndexOf('/') + 1);
+
+export function detect(root) {
+  const nestedRepos = findNestedRepos(root);
+  primeNested(root, nestedRepos);
+  const files = listFiles(root, nestedRepos);
+  const lockfiles = files.filter((f) => LOCKFILES[base(f)]).map((file) => ({ file, manager: LOCKFILES[base(file)] }));
+  const packageJsons = files.filter((f) => base(f) === 'package.json');
+  const manifests = files.filter((f) => /^requirements.*\.txt$/.test(base(f)) || ['pyproject.toml', 'Pipfile', 'setup.py', 'go.mod', 'Cargo.toml', 'composer.json', 'Gemfile'].includes(base(f)));
+
+  const nodeDeps = new Set();
+  for (const pj of packageJsons.slice(0, 300)) {
+    try {
+      const j = JSON.parse(readText(root, pj));
+      for (const k of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) for (const n of Object.keys(j[k] ?? {})) nodeDeps.add(n);
+    } catch { /* unreadable package.json: no dependency signal */ }
+  }
+  const pyText = files.filter((f) => /^requirements.*\.txt$/.test(base(f)) || ['pyproject.toml', 'Pipfile', 'setup.py'].includes(base(f)))
+    .map((f) => readText(root, f).toLowerCase()).join('\n');
+  const pyHas = (name) => new RegExp(`(^|[^a-z0-9_.-])${name.replace(/[-.]/g, '[-_.]')}($|[^a-z0-9_.-])`, 'm').test(pyText);
+  const anyNode = (re) => [...nodeDeps].some((d) => re.test(d));
+
+  const agentConfigs = files.filter((f) => {
+    const b = base(f);
+    return ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md', 'SKILL.md', '.cursorrules', '.windsurfrules', '.mcp.json', 'copilot-instructions.md'].includes(b)
+      || /^\.(cursor|claude|codex|gemini|windsurf|continue|aider)\//.test(f) || /(^|\/)\.cursor\/rules\//.test(f)
+      || /(^|\/)\.vscode\/(tasks|mcp)\.json$/.test(f) || /(^|\/)\.devcontainer(\/|\.json$)/.test(f)
+      || /(^|\/)\.(husky|githooks)\//.test(f);
+  });
+  const workflows = files.filter((f) => /(^|\/)\.github\/(workflows\/[^/]+\.ya?ml|actions\/.+\/action\.ya?ml)$/.test(f));
+  const docker = files.filter((f) => /^(Dockerfile(\..+)?|.+\.dockerfile|(docker-)?compose([.-].+)?\.ya?ml)$/i.test(base(f)));
+  const iac = files.filter((f) => f.endsWith('.tf') || base(f) === 'Chart.yaml' || /(^|\/)(k8s|kubernetes)\/.+\.ya?ml$/.test(f));
+
+  const detection = {
+    nestedRepos,
+    lockfiles,
+    packageManagers: [...new Set(lockfiles.map((l) => l.manager))].sort(),
+    manifests,
+    packageJsons,
+    nextjs: nodeDeps.has('next') || files.some((f) => /^next\.config\.(js|mjs|ts|cjs)$/.test(base(f))),
+    expo: nodeDeps.has('expo') || files.some((f) => /^app\.config\.(js|ts)$/.test(base(f))),
+    supabase: anyNode(/^@supabase\//) || nodeDeps.has('supabase') || files.some((f) => /(^|\/)supabase\/(config\.toml|migrations\/)/.test(f)),
+    stripe: nodeDeps.has('stripe') || anyNode(/^@stripe\//) || pyHas('stripe'),
+    aiSdk: anyNode({ test: (d) => AI_NODE.some((re) => re.test(d)) }) || AI_PY.some(pyHas),
+    python: files.some((f) => f.endsWith('.py')) || manifests.some((m) => /requirements|pyproject|Pipfile|setup\.py/.test(m)),
+    workflows,
+    docker,
+    iac,
+    agentConfigs,
+  };
+  detection.stacks = ['nextjs', 'expo', 'supabase', 'stripe', 'aiSdk', 'python'].filter((k) => detection[k])
+    .concat(workflows.length ? ['workflows'] : [], docker.length || iac.length ? ['containers-iac'] : [], agentConfigs.length ? ['agent-configs'] : []);
+  return detection;
+}

package/dist/security-runtime/src/core/errors.mjs

@@ -0,0 +1,5 @@
+// Error types. UsageError maps to exit code 3 (usage, configuration, authorization or lock error).
+export class UsageError extends Error {}
+export class LockError extends UsageError {}
+export class FetchError extends Error {}
+export class InstallError extends Error {}

package/dist/security-runtime/src/core/fetch.mjs

@@ -0,0 +1,139 @@
+// Fetch wrapper: host allowlist, timeout, retries for GET, redirect checks, and an on-disk cache with age reporting.
+import fs from 'node:fs';
+import path from 'node:path';
+import { FetchError } from './errors.mjs';
+import { sha256 } from './findings.mjs';
+import { vsgHome } from './paths.mjs';
+
+/** Documented endpoints (build spec, Interface table). Product origins and other hosts are passed in explicitly. */
+export const DOCUMENTED_HOSTS = [
+  'api.osv.dev', 'osv-vulnerabilities.storage.googleapis.com',
+  'www.cisa.gov', 'api.first.org',
+  'registry.npmjs.org', 'api.npmjs.org', 'pypi.org', 'files.pythonhosted.org',
+  'api.github.com', 'github.com', 'objects.githubusercontent.com', 'release-assets.githubusercontent.com',
+  'github-releases.githubusercontent.com', 'raw.githubusercontent.com',
+  'api.supabase.com', 'ghcr.io', 'registry-1.docker.io',
+];
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+const isLocalHost = (h) => LOCAL_HOSTS.has(h) || h.endsWith('.localhost');
+const DAY = 24 * 60 * 60 * 1000;
+
+function checkAllowed(url, allowHosts, strictHosts = false) {
+  let u;
+  try { u = new URL(url); } catch { throw new FetchError(`Invalid URL "${url}".`); }
+  const host = u.hostname.toLowerCase();
+  // strictHosts: only the caller's hosts (a live session's one registered origin), never the documented endpoints
+  const allowed = new Set([...(strictHosts ? [] : DOCUMENTED_HOSTS), ...allowHosts.map((h) => h.toLowerCase())]);
+  // an allowHosts entry may be a bare host or host:port; a registered origin passes host:port so other ports stay refused
+  if (!allowed.has(host) && !allowed.has(u.host.toLowerCase())) throw new FetchError(`Host "${host}" is not an allowed endpoint. Register it as a target or use a documented endpoint.`);
+  if (u.protocol !== 'https:' && !(u.protocol === 'http:' && isLocalHost(host))) {
+    throw new FetchError(`Refusing non-HTTPS request to "${host}". Only local targets may use HTTP.`);
+  }
+  return u;
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Reads at most `cap` bytes of a response body, then cancels the stream. Returns { buf, truncated }. */
+export async function readCapped(res, cap) {
+  if (!res.body) return { buf: Buffer.alloc(0), truncated: false };
+  const reader = res.body.getReader();
+  const chunks = [];
+  let n = 0;
+  let truncated = false;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    chunks.push(value);
+    n += value.length;
+    if (n > cap) { truncated = true; await reader.cancel().catch(() => {}); break; }
+  }
+  const all = Buffer.concat(chunks);
+  return { buf: truncated ? all.subarray(0, cap) : all, truncated };
+}
+
+// Credentials belong to the host they were meant for. Like fetch's own redirect handling, drop them when a redirect changes origin.
+const CREDENTIAL_HEADERS = new Set(['authorization', 'cookie', 'proxy-authorization', 'apikey', 'x-api-key']);
+const withoutCredentials = (headers) => Object.fromEntries(Object.entries(headers ?? {}).filter(([k]) => !CREDENTIAL_HEADERS.has(k.toLowerCase())));
+
+/**
+ * Returns { ok, status, headers, body: Buffer }. Never throws for HTTP error statuses; throws FetchError for
+ * disallowed hosts and for network failure after retries. Only GET is retried (write probes are never retried).
+ * strictHosts: only allowHosts are allowed (no documented endpoints), for the first request and every redirect.
+ * A redirect off them is not followed: the 3xx response is returned as it is.
+ */
+export async function vfetch(url, {
+  method = 'GET', headers = {}, body, timeoutMs = 30_000, retries = 2, retryDelayMs = 500, allowHosts = [], strictHosts = false, maxBytes = 1_000_000_000,
+  fetchImpl = globalThis.fetch,
+} = {}) {
+  checkAllowed(url, allowHosts, strictHosts);
+  const attempts = method === 'GET' ? retries + 1 : 1;
+  let lastError;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    if (attempt > 0) await sleep(retryDelayMs * 2 ** (attempt - 1));
+    let failure = null; // per attempt: an earlier attempt's failure must not mask this one
+    try {
+      let current = url;
+      let sent = headers;
+      let done = false;
+      for (let hop = 0; hop <= 5 && !done; hop++) {
+        checkAllowed(current, allowHosts, strictHosts); // every redirect target is checked too
+        const res = await fetchImpl(current, { method, headers: sent, body, redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) });
+        const location = res.status >= 300 && res.status < 400 ? res.headers.get('location') : null;
+        if (location) {
+          const next = new URL(location, current);
+          let follow = true;
+          if (strictHosts) { try { checkAllowed(next.href, allowHosts, true); } catch { follow = false; } }
+          if (follow) {
+            if (next.origin !== new URL(current).origin) sent = withoutCredentials(sent);
+            current = next.href;
+            continue;
+          }
+        }
+        const { buf, truncated } = await readCapped(res, maxBytes);
+        if (truncated) throw new FetchError(`Response from ${new URL(current).hostname} exceeds ${maxBytes} bytes.`);
+        if ((res.status >= 500 || res.status === 429) && attempt < attempts - 1) { failure = new FetchError(`HTTP ${res.status}`); done = true; continue; }
+        return { ok: res.ok, status: res.status, headers: res.headers, body: buf };
+      }
+      if (!failure) throw new FetchError('Too many redirects.');
+    } catch (e) {
+      if (e instanceof FetchError && /not an allowed|non-HTTPS|exceeds|Invalid URL|Too many/.test(e.message)) throw e;
+      failure = e;
+    }
+    lastError = failure;
+  }
+  throw new FetchError(`Request to ${new URL(url).hostname} failed: ${lastError?.message ?? 'unknown error'}.`);
+}
+
+const cacheFile = (url) => path.join(vsgHome(), 'cache', `${sha256(url).slice(0, 32)}.json`);
+
+/**
+ * GET with a disk cache. Fresh cache (age <= ttlMs) is used without a request. If the network fails, a cache no older
+ * than maxStaleMs is returned with degraded: true; otherwise this throws (the calling check becomes not_run).
+ * Returns { body, source: 'cache'|'network'|'stale-cache', ageMs, degraded }.
+ */
+export async function cachedGet(url, { ttlMs = DAY, maxStaleMs = 7 * DAY, now = Date.now, ...opts } = {}) {
+  const file = cacheFile(url);
+  let entry = null;
+  try { entry = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { /* no usable cache */ }
+  const age = entry ? now() - entry.fetchedAt : Infinity;
+  if (entry && age <= ttlMs) return { body: Buffer.from(entry.body, 'base64'), source: 'cache', ageMs: age, degraded: false };
+  let failure;
+  try {
+    const res = await vfetch(url, opts);
+    if (res.ok) {
+      fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+      const tmp = `${file}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify({ url, fetchedAt: now(), body: res.body.toString('base64') }), { mode: 0o600 });
+      fs.renameSync(tmp, file);
+      return { body: res.body, source: 'network', ageMs: 0, degraded: false };
+    }
+    failure = `HTTP ${res.status}`;
+  } catch (e) {
+    if (/not an allowed|non-HTTPS/.test(e.message)) throw e;
+    failure = e.message;
+  }
+  if (entry && age <= maxStaleMs) return { body: Buffer.from(entry.body, 'base64'), source: 'stale-cache', ageMs: age, degraded: true };
+  const why = entry ? `cached copy is ${Math.floor(age / DAY)} days old (limit ${Math.floor(maxStaleMs / DAY)})` : 'no cached copy';
+  throw new FetchError(`Feed ${new URL(url).hostname} is unreachable (${failure}) and ${why}.`);
+}

package/dist/security-runtime/src/core/findings.mjs

@@ -0,0 +1,177 @@
+// Findings model: schema, fingerprint, dedupe and redaction (REQ-004).
+import crypto from 'node:crypto';
+import { owaspForCwes } from './sarif.mjs';
+
+export const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
+export const CONFIDENCES = ['confirmed', 'high', 'medium', 'low'];
+export const CATEGORIES = [
+  'secret', 'secret-history', 'malicious-package', 'dependency-vuln', 'dependency-change', 'code',
+  'supabase', 'workflow', 'agent-surface', 'malware', 'replay', 'live', 'release', 'agent-finding',
+  'iac', 'posture', 'license', 'config', 'other',
+];
+export const sha256 = (data) => crypto.createHash('sha256').update(data).digest('hex');
+/** Higher number is worse. */
+export const severityRank = (s) => SEVERITIES.length - SEVERITIES.indexOf(s);
+const confidenceRank = (c) => CONFIDENCES.length - CONFIDENCES.indexOf(c);
+
+/** Redaction (spec): first 4 characters, the length, and an 8-character SHA-256 prefix. Values of 8 or fewer characters show no prefix. */
+export function redact(value) {
+  const s = String(value);
+  const prefix = s.length > 8 ? s.slice(0, 4) : '';
+  return `${prefix}[redacted len=${s.length} sha256=${sha256(s).slice(0, 8)}]`;
+}
+
+const SECRET_PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{30,}\b/g,
+  /\bgithub_pat_[A-Za-z0-9_]{30,}\b/g,
+  /\b(?:sk|rk|pk)_(?:live|test)_[A-Za-z0-9]{16,}\b/g,
+  /\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{20,}\b/g,
+  /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g,
+  /\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/g,
+];
+// header and assignment forms: the value is the secret, the name stays readable
+const VALUE_PATTERNS = [
+  /\b(Bearer|Basic)\s+([A-Za-z0-9._~+\/=-]{12,})/gi,
+  /\b(Set-Cookie|Cookie|Authorization|X-Api-Key)(\s*[:=]\s*)([^\r\n]{8,})/gi,
+  /\b([A-Za-z0-9_.-]*(?:password|passwd|secret|token|api[_-]?key|private[_-]?key)[A-Za-z0-9_.-]*)(\s*[:=]\s*["']?)([^\s"',;}]{8,})/gi,
+];
+
+/** Removes secrets from free text: known values first, then well-known token shapes and secret-named assignments. */
+export function scrubText(text, secrets = []) {
+  let out = String(text ?? '');
+  for (const s of secrets) if (s && String(s).length >= 8) out = out.split(String(s)).join(redact(s));
+  for (const re of SECRET_PATTERNS) out = out.replace(re, (m) => redact(m));
+  out = out.replace(VALUE_PATTERNS[0], (_m, scheme, v) => `${scheme} ${redact(v)}`);
+  out = out.replace(VALUE_PATTERNS[1], (_m, name, sep, v) => (v.includes('[redacted') ? _m : `${name}${sep}${redact(v)}`));
+  out = out.replace(VALUE_PATTERNS[2], (_m, name, sep, v) => (v.includes('[redacted') ? _m : `${name}${sep}${redact(v)}`));
+  return out.replace(URL_PATTERN, (u) => scrubUrl(u));
+}
+
+// Query and fragment values whose names look like credentials, and userinfo, never reach a finding or its fingerprint.
+const SECRET_PARAM = /token|key|secret|sig|auth|password|passwd|code|session|credential|jwt/i;
+const URL_PATTERN = /\b[a-z][a-z0-9+.-]*:\/\/[^\s"'<>]+/gi;
+const redactParams = (part) => part.split('&').map((kv) => {
+  const i = kv.indexOf('=');
+  if (i < 0) return kv;
+  let name = kv.slice(0, i);
+  try { name = decodeURIComponent(name); } catch { /* keep the raw name */ }
+  return SECRET_PARAM.test(name) ? `${kv.slice(0, i)}=REDACTED` : kv;
+}).join('&');
+
+/** Makes a URL safe to store: drops userinfo, redacts secret-looking query and fragment values, then scrubs token shapes. The rest is left byte for byte. */
+export function scrubUrl(url) {
+  let s = String(url).replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/?#]*@/i, '$1');
+  const hashAt = s.indexOf('#');
+  let hash = hashAt < 0 ? '' : s.slice(hashAt + 1);
+  if (hashAt >= 0) s = s.slice(0, hashAt);
+  const queryAt = s.indexOf('?');
+  const query = queryAt < 0 ? null : s.slice(queryAt + 1);
+  if (queryAt >= 0) s = s.slice(0, queryAt);
+  if (query !== null) s += `?${redactParams(query)}`;
+  if (hashAt >= 0) hash = hash.includes('=') ? redactParams(hash) : hash;
+  // token shapes only: scrubText's assignment patterns would swallow the rest of a query string
+  let out = hashAt >= 0 ? `${s}#${hash}` : s;
+  for (const re of SECRET_PATTERNS) out = out.replace(re, (m) => redact(m));
+  return out;
+}
+
+const posix = (p) => String(p).replace(/\\/g, '/').replace(/^\.\//, '');
+
+/** Builds a schema-shaped finding from an adapter's raw finding. Throws on an invalid one. */
+export function makeFinding(raw, checkId) {
+  const loc = raw.location ?? {};
+  const location = {};
+  if (loc.file !== undefined) location.file = posix(loc.file);
+  for (const k of ['line', 'package', 'version', 'ecosystem']) if (loc[k] !== undefined) location[k] = loc[k];
+  if (loc.url !== undefined) location.url = scrubUrl(loc.url);
+  const title = typeof raw.title === 'string' ? scrubText(raw.title) : raw.title;
+  const key = raw.key ?? raw.ruleId ?? title; // fingerprints come from the scrubbed values, so a rotated secret does not change them
+  const fingerprint = sha256([raw.category, key, location.file ?? '', location.package ?? '', location.version ?? '',
+    location.ecosystem ?? '', location.url ?? ''].join('\u0000'));
+  const cwes = [].concat(raw.cwe ?? []);
+  const owasp = [...new Set([...(raw.owasp ?? []), ...owaspForCwes(cwes)])];
+  const finding = {
+    id: `VSG-${fingerprint.slice(0, 8)}`,
+    fingerprint,
+    check: checkId,
+    sources: raw.sources ?? [{ tool: raw.tool ?? checkId, ruleId: raw.ruleId ?? null }],
+    category: raw.category,
+    severity: raw.severity,
+    confidence: raw.confidence ?? 'medium',
+    title,
+    description: scrubText(raw.description ?? ''),
+    location,
+    evidence: scrubText(raw.evidence ?? ''),
+    refs: raw.refs ?? [],
+    fix: scrubText(raw.fix ?? ''),
+    exploited: { kev: raw.exploited?.kev ?? false, epss: raw.exploited?.epss ?? null },
+    owasp,
+    blocking: false,
+    blockReason: '',
+    status: 'open',
+    isNew: null,
+  };
+  const errors = validateFinding(finding);
+  if (errors.length) throw new Error(`invalid finding "${raw.title ?? '?'}": ${errors.join('; ')}`);
+  return finding;
+}
+
+export function validateFinding(f) {
+  const errors = [];
+  const need = (c, m) => { if (!c) errors.push(m); };
+  need(/^VSG-[0-9a-f]{8}$/.test(f?.id ?? ''), 'id');
+  need(/^[0-9a-f]{64}$/.test(f?.fingerprint ?? ''), 'fingerprint');
+  need(typeof f?.check === 'string' && f.check, 'check');
+  need(Array.isArray(f?.sources) && f.sources.length > 0, 'sources');
+  need(CATEGORIES.includes(f?.category), `category "${f?.category}"`);
+  need(SEVERITIES.includes(f?.severity), `severity "${f?.severity}"`);
+  need(CONFIDENCES.includes(f?.confidence), `confidence "${f?.confidence}"`);
+  need(typeof f?.title === 'string' && f.title, 'title');
+  need(typeof f?.description === 'string', 'description');
+  need(f?.location && typeof f.location === 'object', 'location');
+  need(typeof f?.evidence === 'string', 'evidence');
+  need(Array.isArray(f?.refs), 'refs');
+  need(typeof f?.fix === 'string', 'fix');
+  need(typeof f?.exploited?.kev === 'boolean', 'exploited.kev');
+  need(Array.isArray(f?.owasp), 'owasp');
+  need(typeof f?.blocking === 'boolean', 'blocking');
+  need(['open', 'accepted', 'expired-acceptance'].includes(f?.status), 'status');
+  return errors;
+}
+
+/** One issue reported by several tools becomes one finding with every source. Deterministic regardless of input order. */
+export function dedupe(findings) {
+  const groups = new Map();
+  for (const f of findings) {
+    if (!groups.has(f.fingerprint)) groups.set(f.fingerprint, []);
+    groups.get(f.fingerprint).push(f);
+  }
+  const out = [];
+  for (const group of groups.values()) {
+    group.sort((a, b) => severityRank(b.severity) - severityRank(a.severity) || a.check.localeCompare(b.check));
+    const merged = structuredClone(group[0]);
+    const seen = new Set();
+    merged.sources = [];
+    for (const g of group) {
+      for (const s of g.sources) {
+        const k = `${s.tool}\u0000${s.ruleId}`;
+        if (!seen.has(k)) { seen.add(k); merged.sources.push(s); }
+      }
+      if (confidenceRank(g.confidence) > confidenceRank(merged.confidence)) merged.confidence = g.confidence;
+      merged.refs = [...new Set([...merged.refs, ...g.refs])];
+      merged.owasp = [...new Set([...merged.owasp, ...g.owasp])];
+      merged.exploited.kev ||= g.exploited.kev;
+      if (g.exploited.epss != null && (merged.exploited.epss == null || g.exploited.epss > merged.exploited.epss)) merged.exploited.epss = g.exploited.epss;
+      if (!merged.fix && g.fix) merged.fix = g.fix;
+    }
+    merged.sources.sort((a, b) => `${a.tool}${a.ruleId}`.localeCompare(`${b.tool}${b.ruleId}`));
+    out.push(merged);
+  }
+  return sortFindings(out);
+}
+
+export function sortFindings(findings) {
+  return [...findings].sort((a, b) => severityRank(b.severity) - severityRank(a.severity) || a.fingerprint.localeCompare(b.fingerprint));
+}