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

package/dist/security-runtime/src/checks/dep-change/index.mjs

@@ -0,0 +1,316 @@
+// dep-change (REQ-010): signals on packages added or changed against the base ref, from registry metadata, plus GuardDog on the changed set.
+// Reads lockfiles and registry metadata only. Never installs anything and never runs repository code.
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveBase as resolveBaseOf } from '../../core/base-ref.mjs';
+import { git } from '../_lib/secrets.mjs';
+import { keyOf, lockfileKind, NPM_NAME, normPyName, parseLockfile, PYPI_NAME, VERSION_SAFE } from '../_lib/lockfiles.mjs';
+import { runGuardDog } from './guarddog.mjs';
+import { analyzeNpm, analyzePyPI, RegistryClient } from './registries.mjs';
+
+export const id = 'dep-change';
+export const title = 'Dependency-change signals (age, provenance, publisher, install scripts, removals, GuardDog)';
+export const modes = ['scan', 'deep', 'release'];
+export const requiredIn = ['scan', 'deep', 'release'];
+export const timeoutSec = 1800;
+
+const CONCURRENCY = 8;
+/**
+ * Wall-clock budgets. Registry lookups get REGISTRY_BUDGET_MS (packages not looked up in time count as unchecked; over 10% of them makes
+ * the check not_run). GuardDog gets what is left of TOTAL_BUDGET_MS, but at least MIN_GUARDDOG_BUDGET_MS. Without caps, one working copy
+ * with 31 changed packages ran for 256 s.
+ */
+export const REGISTRY_BUDGET_MS = 30_000;
+export const TOTAL_BUDGET_MS = 60_000;
+const MIN_GUARDDOG_BUDGET_MS = 15_000;
+const MAX_PACKAGES = 300;
+const MAX_UNCHECKED = 0.1;
+const base = (f) => f.slice(f.lastIndexOf('/') + 1);
+const dirOf = (f) => (f.includes('/') ? f.slice(0, f.lastIndexOf('/')) : '');
+const supportedFiles = (d) => [...d.lockfiles.map((l) => l.file), ...(d.manifests ?? [])].filter((f) => lockfileKind(f));
+
+export function applies(ctx) {
+  const d = ctx.detection;
+  return supportedFiles(d).length > 0 || d.lockfiles.length > 0
+    ? true
+    : { applies: false, reason: 'no lockfile or pinned requirements file was found' };
+}
+
+/** Runs fn over items with `limit` workers and stops starting new items once stop() is true. Returns the items that were never started. */
+async function pool(items, limit, fn, stop = () => false) {
+  const queue = [...items];
+  await Promise.all(Array.from({ length: Math.min(limit, queue.length) }, async () => {
+    while (queue.length && !stop()) await fn(queue.shift());
+  }));
+  return queue;
+}
+
+
+/** { sha, ref, how } of the comparison base, or { sha: null, why }: the resolver shared with the acceptance review (core/base-ref.mjs). */
+export async function resolveBase(ctx) {
+  return resolveBaseOf(ctx.repo, { flag: ctx.flags?.base, config: ctx.config });
+}
+
+const readText = (repo, rel) => { try { return fs.readFileSync(path.join(repo, rel), 'utf8'); } catch { return null; } };
+
+function directNames(repo, file) {
+  const pj = readText(repo, path.posix.join(dirOf(file), 'package.json'));
+  if (pj === null) return null;
+  try {
+    const j = JSON.parse(pj);
+    return new Set(['dependencies', 'devDependencies', 'optionalDependencies'].flatMap((k) => Object.keys(j[k] ?? {})));
+  } catch { return null; }
+}
+
+/** Packages in one lockfile that are new or changed. Returns { added: [...], changed: [...], mode, note }. */
+function changesFor(ctx, file, current, baseParsed) {
+  const kind = lockfileKind(file);
+  const usable = current.filter((p) => !p.skip);
+  const skipped = current.filter((p) => p.skip);
+  if (baseParsed) {
+    const baseKeys = new Set(baseParsed.map(keyOf));
+    const baseVersions = new Map();
+    for (const b of baseParsed) {
+      const k = `${b.ecosystem}:${b.ecosystem === 'PyPI' ? normPyName(b.name) : b.name}`;
+      if (!baseVersions.has(k)) baseVersions.set(k, []);
+      baseVersions.get(k).push(b.version);
+    }
+    const out = [];
+    for (const p of usable) {
+      if (baseKeys.has(keyOf(p))) continue;
+      const prev = baseVersions.get(`${p.ecosystem}:${p.ecosystem === 'PyPI' ? normPyName(p.name) : p.name}`);
+      out.push({ ...p, file, prevVersion: prev ? prev[prev.length - 1] : null, added: !prev });
+    }
+    return { packages: out, skipped, mode: 'diff against base' };
+  }
+  // No base: direct dependencies only.
+  let direct;
+  let note = '';
+  if (kind === 'requirements') direct = usable;
+  else if (kind === 'npm-lock' || kind === 'pnpm-lock') {
+    const names = directNames(ctx.repo, file);
+    if (names) direct = usable.filter((p) => names.has(p.name) && (kind === 'pnpm-lock' || p.top));
+    else { direct = []; note = `no readable package.json beside ${file}, so its direct dependencies could not be identified`; }
+  } else { direct = usable; note = `${file}: direct dependencies are not derived for ${kind}; every locked package is considered (capped at ${MAX_PACKAGES})`; }
+  return { packages: direct.map((p) => ({ ...p, file, prevVersion: null, added: true })), skipped, mode: 'direct dependencies only (no base)', note };
+}
+
+const label = (p) => `${p.name}${p.ecosystem === 'PyPI' ? '==' : '@'}${p.version}`;
+const rawFinding = (p, o) => ({
+  category: 'dependency-change', tool: 'vsg', ruleId: `dep-change/${o.key}`, confidence: 'medium',
+  location: { file: p.file, package: p.name, version: p.version, ecosystem: p.ecosystem }, refs: [], ...o,
+});
+
+/** Turns one package's signals into findings. Blocking rows follow the policy table; single other signals are medium warnings. */
+export function findingsFor(p, res) {
+  const out = [];
+  const byId = Object.fromEntries(res.signals.map((s) => [s.id, s]));
+  const where = `${label(p)} in ${p.file}`;
+  const cmp = res.comparison ? ` Compared with ${res.comparison.version} (${res.comparison.source}).` : '';
+  const consumed = new Set();
+  const detail = (ids) => ids.filter((i) => byId[i]).map((i) => byId[i].detail).join(' ');
+
+  if (byId.removed) {
+    out.push(rawFinding(p, {
+      key: 'version-removed', severity: 'high', confidence: 'high',
+      title: `Version removed from the registry: ${label(p)}`,
+      description: `${byId.removed.detail} ${where} still depends on it.`,
+      evidence: byId.removed.detail,
+      fix: `Treat ${label(p)} as untrusted. Check the package's security advisories, pin a version that still exists, and rotate secrets on any machine or CI run that installed it.`,
+    }));
+    return out;
+  }
+  if (byId['provenance-dropped']) {
+    consumed.add('provenance-dropped');
+    out.push(rawFinding(p, {
+      key: 'provenance-dropped', severity: 'high', confidence: 'high',
+      title: `Provenance dropped: ${label(p)}`,
+      description: `${byId['provenance-dropped'].detail} A release that stops carrying build provenance may have been published from a stolen token rather than the project's CI.${cmp}`,
+      evidence: [detail(['provenance-dropped', 'publisher-changed', 'new-install-script', 'new-dependencies', 'fresh'])].join('\n'),
+      fix: `Do not ship ${where}. Pin the version that had provenance (${res.comparison?.version ?? 'the previous release'}) until the maintainers explain the change.`,
+    }));
+  }
+  const risky = byId['new-install-script'] || res.signals.some((s) => s.id === 'new-dependencies' && s.recent?.length);
+  if (byId.fresh && risky) {
+    for (const i of ['fresh', 'new-install-script']) consumed.add(i);
+    if (byId['new-dependencies']?.recent?.length) consumed.add('new-dependencies');
+    out.push(rawFinding(p, {
+      key: 'fresh-risky-change', severity: 'high', confidence: 'high',
+      title: `Brand-new release with an install script or very new dependency: ${label(p)}`,
+      description: `${detail(['fresh', 'new-install-script', 'new-dependencies'])}${cmp} A version under 72 hours old that also adds an install-time script or a dependency created within 30 days matches the pattern of recent npm supply-chain attacks.`,
+      evidence: detail(['fresh', 'publisher-changed', 'new-install-script', 'new-dependencies']),
+      fix: `Wait for the release to age and be reviewed, or pin the previous version (${res.comparison?.version ?? 'the last one you reviewed'}). Install scripts should run only for packages you trust.`,
+    }));
+  }
+  const warnings = {
+    fresh: ['published-recently', 'Published less than 72 hours ago', 'Let new releases age a few days before adopting them, or review the diff against the previous version first.'],
+    'publisher-changed': ['publisher-changed', 'Publisher changed', 'Confirm the new publisher is a legitimate maintainer. A publisher change is a common sign of an account takeover.'],
+    'new-install-script': ['new-install-script', 'New install script', 'Review the script before installing, and consider ignore-scripts for this package.'],
+    'new-dependencies': ['new-dependencies', 'New dependencies', 'Review each new dependency, especially recently created or unknown ones.'],
+    'low-reputation': ['low-reputation', 'Low-reputation new package', 'Confirm you need this package and that it is the one you meant to install (typosquats are often new and rarely downloaded).'],
+    yanked: ['yanked-release', 'Yanked release', 'Upgrade to a release that has not been yanked.'],
+  };
+  for (const s of res.signals) {
+    if (consumed.has(s.id) || !warnings[s.id]) continue;
+    const [key, head, fix] = warnings[s.id];
+    out.push(rawFinding(p, { key, severity: 'medium', title: `${head}: ${label(p)}`, description: `${s.detail}${cmp}`, evidence: s.detail, fix }));
+  }
+  return out;
+}
+
+// Registry signals that corroborate a GuardDog high_risk verdict. GuardDog's heuristics also fire on large legitimate packages
+// (for example bundled webpack code in next), so a GuardDog-only verdict is a review item, not a Critical block.
+const CORROBORATING = new Set(['provenance-dropped', 'publisher-changed', 'new-install-script', 'fresh', 'removed', 'low-reputation']);
+
+function guardDogFindings(p, gd, signals = []) {
+  const r = gd.result;
+  if (!r || (!r.malicious && !r.rules.length)) return [];
+  const rules = r.rules.map((x) => `${x.rule}${x.where ? ` at ${x.where}` : ''}${x.message ? `: ${x.message}` : ''}`);
+  const evidence = `GuardDog risk rating: ${r.label}. ${rules.slice(0, 8).join('\n')}`;
+  if (r.malicious && !signals.some((s) => CORROBORATING.has(s.id))) {
+    return [{
+      category: 'dependency-change', severity: 'medium', confidence: 'medium', key: 'guarddog-high-risk-uncorroborated', tool: 'guarddog', ruleId: 'guarddog/high_risk',
+      location: { file: p.file, package: p.name, version: p.version, ecosystem: p.ecosystem }, refs: [],
+      title: `GuardDog rates ${label(p)} as high risk, with no registry warning sign`,
+      description: `GuardDog's heuristics matched (${r.rules.map((x) => x.rule).join(', ')}), but the registry shows no sign of compromise: provenance, publisher, install scripts, release age and reputation are all normal. These rules also fire on large legitimate packages, so review the flagged code before shipping.`,
+      evidence,
+      fix: `Review the flagged code in ${label(p)}. It blocks automatically only when a registry warning sign agrees.`,
+    }];
+  }
+  if (r.malicious) {
+    return [{
+      category: 'malicious-package', severity: 'critical', confidence: 'high', key: 'guarddog-malicious', tool: 'guarddog', ruleId: 'guarddog/high_risk',
+      location: { file: p.file, package: p.name, version: p.version, ecosystem: p.ecosystem }, refs: [],
+      title: `GuardDog rates ${label(p)} as high risk (likely malicious)`,
+      description: `GuardDog's malicious-behavior rules matched this package version: ${r.rules.map((x) => x.rule).join(', ')}. Treat any machine or CI run that installed it as compromised.`,
+      evidence,
+      fix: `Remove ${label(p)} from ${p.file}, reinstall from a clean state, and rotate secrets available to machines that installed it.`,
+    }];
+  }
+  return [{
+    category: 'dependency-change', severity: 'medium', confidence: 'medium', key: 'guarddog-issues', tool: 'guarddog', ruleId: 'guarddog/issues',
+    location: { file: p.file, package: p.name, version: p.version, ecosystem: p.ecosystem }, refs: [],
+    title: `GuardDog flagged ${r.rules.length} issue${r.rules.length === 1 ? '' : 's'} in ${label(p)}`,
+    description: `GuardDog rated this version "${r.label}": ${r.rules.map((x) => x.rule).join(', ')}. These rules also fire on legitimate packages, so review the code.`,
+    evidence, fix: `Review the flagged code in ${label(p)} before shipping this change.`,
+  }];
+}
+
+export async function run(ctx) {
+  const d = ctx.detection;
+  const files = supportedFiles(d);
+  const unsupported = d.lockfiles.map((l) => l.file).filter((f) => !lockfileKind(f));
+  if (!files.length) {
+    return { status: 'not_run', reason: `dependency-change analysis does not support ${unsupported.join(', ')} yet (supported: package-lock.json, pnpm-lock.yaml, requirements.txt, uv.lock, poetry.lock)` };
+  }
+  const nowMs = ctx.nowMs ?? Date.now();
+  const startedAt = Date.now();
+  const notes = [];
+  const baseInfo = await resolveBase(ctx);
+  notes.push(baseInfo.sha ? `base: ${baseInfo.ref} (${baseInfo.sha.slice(0, 12)}, ${baseInfo.how})` : `no base available: ${baseInfo.why}; only direct dependencies were considered`);
+  if (unsupported.length) notes.push(`not analyzed (unsupported lockfile type): ${unsupported.join(', ')}`);
+
+  const changes = new Map();
+  const baseKeysAll = new Set(); // name@version of every package in the base version of any lockfile
+  const skipped = [];
+  const unreadable = [];
+  let considered = 0;
+  for (const file of files) {
+    const text = readText(ctx.repo, file);
+    let current;
+    try { current = text === null ? null : parseLockfile(file, text); } catch { current = null; }
+    if (!current) { unreadable.push(file); continue; }
+    let baseParsed = null;
+    if (baseInfo.sha) {
+      const r = await git(ctx, ['show', `${baseInfo.sha}:./${file}`]);
+      if (r.status === 'ran' && r.exitCode === 0) { try { baseParsed = parseLockfile(file, r.stdout); } catch { baseParsed = null; } }
+      if (!baseParsed) notes.push(`${file} does not exist (or is unreadable) at the base, so only its direct dependencies were considered`);
+    }
+    const c = changesFor(ctx, file, current, baseParsed);
+    if (c.note) notes.push(c.note);
+    skipped.push(...c.skipped.map((p) => ({ file, name: p.name, version: p.version, why: p.skip })));
+    if (baseParsed) for (const b of baseParsed) baseKeysAll.add(keyOf(b));
+    for (const p of c.packages) {
+      const k = keyOf(p);
+      const entry = baseParsed ? p : { ...p, noBase: true };
+      if (!changes.has(k) || (changes.get(k).noBase && !entry.noBase)) changes.set(k, entry);
+    }
+    considered += current.length;
+  }
+  // A lockfile with no counterpart at the base (an untracked or new project folder) lists direct dependencies as "changed", but a
+  // name@version that the base lockfiles already hold is not new to the repository: it was released before and is not looked up again.
+  let alreadyInBase = 0;
+  for (const [k, p] of changes) if (p.noBase && baseKeysAll.has(k)) { changes.delete(k); alreadyInBase++; }
+  if (alreadyInBase) notes.push(`${alreadyInBase} direct dependenc${alreadyInBase === 1 ? 'y' : 'ies'} of a lockfile that is new since the base are already in the base lockfiles at the same version and were not looked up again`);
+  if (unreadable.length) notes.push(`could not read or parse: ${unreadable.join(', ')}`);
+  if (unreadable.length === files.length) return { status: 'not_run', reason: `no lockfile could be read: ${unreadable.join(', ')}` };
+
+  let todo = [...changes.values()].filter((p) => (p.ecosystem === 'npm' ? NPM_NAME.test(p.name) : PYPI_NAME.test(p.name)) && VERSION_SAFE.test(p.version));
+  const invalid = changes.size - todo.length;
+  if (invalid) notes.push(`${invalid} package name(s) or version(s) were not valid registry identifiers and were not looked up`);
+  todo.sort((a, b) => Number(b.added) - Number(a.added) || a.name.localeCompare(b.name) || a.version.localeCompare(b.version));
+  if (todo.length > MAX_PACKAGES) {
+    notes.push(`${todo.length} packages changed; only the first ${MAX_PACKAGES} (new packages first) were analyzed and ${todo.length - MAX_PACKAGES} were not`);
+    todo = todo.slice(0, MAX_PACKAGES);
+  }
+
+  const reg = new RegistryClient(ctx.fetch, nowMs);
+  const results = [];
+  const registryBudgetMs = ctx.registryBudgetMs ?? REGISTRY_BUDGET_MS;
+  const registryDeadline = Date.now() + registryBudgetMs;
+  const notStarted = await pool(todo, CONCURRENCY, async (p) => {
+    const res = await (p.ecosystem === 'PyPI' ? analyzePyPI : analyzeNpm)(reg, p);
+    results.push({ p, res });
+  }, () => Date.now() >= registryDeadline);
+  for (const p of notStarted) results.push({ p, res: { checked: false, reason: `not looked up: the ${Math.round(registryBudgetMs / 1000)}-second registry time budget ran out` } });
+  results.sort((a, b) => keyOf(a.p).localeCompare(keyOf(b.p)));
+  const unchecked = results.filter((r) => !r.res.checked);
+  const total = todo.length + invalid;
+  if (total > 0 && (unchecked.length + invalid) / total > MAX_UNCHECKED) {
+    return {
+      status: 'not_run',
+      reason: `${unchecked.length + invalid} of ${total} changed packages could not be checked (limit 10%): ${unchecked.slice(0, 3).map((r) => `${label(r.p)} (${r.res.reason})`).join('; ')}`,
+    };
+  }
+  if (unchecked.length) notes.push(`${unchecked.length} of ${total} packages could not be checked: ${unchecked.map((r) => `${label(r.p)} (${r.res.reason})`).join('; ')}`);
+  for (const r of results) for (const n of r.res.notes ?? []) if (!notes.includes(`${r.p.name}: ${n}`) && !/^PyPI provenance/.test(n)) notes.push(`${label(r.p)}: ${n}`);
+  if (results.some((r) => r.p.ecosystem === 'PyPI')) notes.push('PyPI provenance and publisher are not exposed in the PyPI JSON API, so provenance-drop and publisher-change were not evaluated for PyPI packages');
+
+  const findings = [];
+  for (const { p, res } of results) if (res.checked) findings.push(...findingsFor(p, res));
+
+  // GuardDog on the changed packages, most suspicious first.
+  const suspicion = new Map(results.map((r) => [keyOf(r.p), r.res.signals?.length ?? 0]));
+  const gdCandidates = results.filter((r) => r.res.checked && !r.res.signals.some((s) => s.id === 'removed')).map((r) => r.p)
+    .sort((a, b) => suspicion.get(keyOf(b)) - suspicion.get(keyOf(a)));
+  const gd = gdCandidates.length ? await runGuardDog({ ...ctx, guarddogBudgetMs: ctx.guarddogBudgetMs ?? Math.max(MIN_GUARDDOG_BUDGET_MS, TOTAL_BUDGET_MS - (Date.now() - startedAt)) }, gdCandidates) : { ran: false, reason: 'GuardDog skipped: no changed package to scan', results: [] };
+  if (!gd.ran) notes.push(gd.reason);
+  else {
+    if (gd.skipped) notes.push(`GuardDog scanned the first 25 of ${gdCandidates.length} changed packages; ${gd.skipped} were not scanned`);
+    if (gd.budgetSkipped) notes.push(`GuardDog's ${Math.round(gd.budgetMs / 1000)}-second time budget ran out: ${gd.budgetSkipped} of ${gdCandidates.length} changed packages were not scanned (the most suspicious were scanned first)`);
+    if (gd.cached) notes.push(`${gd.cached} GuardDog result(s) came from the local cache (same image digest, package version scanned within 14 days)`);
+    for (const r of gd.results) {
+      const p = gdCandidates.find((x) => `${x.name}@${x.version}` === r.package);
+      if (!r.ok) notes.push(`GuardDog could not scan ${r.package}: ${r.reason}`);
+      else findings.push(...guardDogFindings(p, r, results.find((x) => keyOf(x.p) === keyOf(p))?.res.signals ?? []));
+    }
+  }
+
+  const summary = results.map(({ p, res }) => ({
+    package: label(p), file: p.file, ecosystem: p.ecosystem, added: p.added, comparison: res.comparison ?? null,
+    checked: res.checked, reason: res.reason, signals: (res.signals ?? []).map((s) => ({ id: s.id, detail: s.detail })), notes: res.notes ?? [], facts: res.facts ?? null,
+  }));
+  return {
+    status: 'ran',
+    reason: [unchecked.length ? `${unchecked.length} package(s) could not be checked` : '', !gd.ran ? gd.reason : '', gd.ran && gd.budgetSkipped ? `GuardDog did not scan ${gd.budgetSkipped} package(s): time budget` : ''].filter(Boolean).join('; '),
+    findings,
+    toolVersion: gd.ran ? `guarddog ${gd.version}` : null,
+    dataVersions: { registries: 'registry.npmjs.org and pypi.org (live)', ...(baseInfo.sha ? { base: baseInfo.sha.slice(0, 12) } : {}), ...(gd.ran ? { guarddogImage: gd.image } : {}) },
+    evidence: {
+      'summary.json': JSON.stringify({ base: baseInfo.sha ? { ref: baseInfo.ref, sha: baseInfo.sha } : null, packagesInLockfiles: considered, analyzed: results.length, notes, skippedNonRegistry: skipped, guarddog: gd.ran ? { image: gd.image, scanned: gd.results.length, cached: gd.cached, notScannedOverCap: gd.skipped, notScannedTimeBudget: gd.budgetSkipped, budgetMs: gd.budgetMs, durationMs: gd.durationMs } : { skipped: gd.reason }, packages: summary }, null, 2),
+      ...(gd.ran ? { 'guarddog.json': JSON.stringify(gd.results, null, 2) } : {}),
+    },
+  };
+}
+
+export default { id, title, modes, requiredIn, timeoutSec, applies, run };

package/dist/security-runtime/src/checks/dep-change/registries.mjs

@@ -0,0 +1,199 @@
+// Registry metadata and the per-package signals for dep-change (REQ-010). All requests go through ctx.fetch (the core fetch wrapper).
+// Each analyze function returns { checked: true, signals, notes, comparison } or { checked: false, reason }.
+const HOUR = 3_600_000;
+const DAY = 24 * HOUR;
+export const FRESH_MS = 72 * HOUR;
+export const NEW_PACKAGE_MS = 30 * DAY;
+export const LOW_WEEKLY_DOWNLOADS = 100;
+const INSTALL_SCRIPTS = ['preinstall', 'install', 'postinstall'];
+const MAX_NEW_DEPS_LOOKED_UP = 10;
+const isPrerelease = (v) => /[-+a-z]/i.test(v.replace(/^v/, '')) && !/^\d+(\.\d+)*$/.test(v);
+const pyReleaseLike = (v) => /^\d+(\.\d+)*$/.test(v);
+const ms = (s) => { const t = Date.parse(s); return Number.isFinite(t) ? t : null; };
+const days = (n) => `${Math.round((n / DAY) * 10) / 10} days`;
+const hours = (n) => `${Math.round((n / HOUR) * 10) / 10} hours`;
+
+export class RegistryClient {
+  constructor(fetchFn, nowMs) {
+    this.fetchFn = fetchFn;
+    this.nowMs = nowMs;
+    this.cache = new Map();
+  }
+
+  /** null when the registry answers 404; throws on any other failure. */
+  getJson(url) {
+    if (!this.cache.has(url)) {
+      this.cache.set(url, (async () => {
+        const res = await this.fetchFn(url, { timeoutMs: 20_000, retries: 2, headers: { accept: 'application/json' }, maxBytes: 128 * 1024 * 1024 });
+        if (res.status === 404) return null;
+        if (!res.ok) throw new Error(`HTTP ${res.status} from ${new URL(url).hostname}`);
+        try { return JSON.parse(res.body.toString('utf8')); } catch { throw new Error(`invalid JSON from ${new URL(url).hostname}`); }
+      })());
+    }
+    return this.cache.get(url);
+  }
+
+  npmPackument(name) { return this.getJson(`https://registry.npmjs.org/${name.startsWith('@') ? `@${encodeURIComponent(name.slice(1))}` : name}`); }
+  npmDownloads(name) { return this.getJson(`https://api.npmjs.org/downloads/point/last-week/${name}`); }
+  pypiProject(name) { return this.getJson(`https://pypi.org/pypi/${name}/json`); }
+  pypiVersion(name, version) { return this.getJson(`https://pypi.org/pypi/${name}/${version}/json`); }
+
+  /** Creation time (ms) of an npm package, or null when it cannot be determined. */
+  async npmCreated(name) { try { const p = await this.npmPackument(name); return ms(p?.time?.created); } catch { return null; } }
+  async pypiCreated(name) {
+    try { const p = await this.pypiProject(name); return earliestUpload(Object.values(p?.releases ?? {}).flat()); } catch { return null; }
+  }
+}
+
+function earliestUpload(files) {
+  const times = (files ?? []).map((f) => ms(f.upload_time_iso_8601 ?? f.upload_time)).filter((t) => t !== null);
+  return times.length ? Math.min(...times) : null;
+}
+
+/** The latest release published before `version`, by publish time (prereleases only when `version` is one). */
+function previousByTime(versions, timeOf, version, isPre) {
+  const mine = timeOf(version);
+  if (mine === null) return null;
+  const want = isPre(version);
+  let best = null;
+  for (const v of versions) {
+    if (v === version) continue;
+    const t = timeOf(v);
+    if (t === null || t >= mine || (!want && isPre(v))) continue;
+    if (!best || t > best.t) best = { v, t };
+  }
+  return best?.v ?? null;
+}
+
+const SIGNAL_FIX_PIN = 'Do not release this change. Pin the comparison version (or the last version you reviewed) and have the dependency change reviewed by a person before it ships.';
+
+async function newDependencySignal(reg, names, now, notes, lookup) {
+  const looked = names.slice(0, MAX_NEW_DEPS_LOOKED_UP);
+  const recent = [];
+  for (const d of looked) {
+    const created = await lookup(d);
+    if (created === null) { notes.push(`could not determine when new dependency ${d} was created`); continue; }
+    if (now - created < NEW_PACKAGE_MS) recent.push({ name: d, ageDays: Math.round(((now - created) / DAY) * 10) / 10 });
+  }
+  if (names.length > looked.length) notes.push(`only the first ${looked.length} of ${names.length} new dependencies were looked up for age`);
+  return recent;
+}
+
+export async function analyzeNpm(reg, { name, version, prevVersion, added }) {
+  const now = reg.nowMs;
+  let pack;
+  try { pack = await reg.npmPackument(name); } catch (e) { return { checked: false, reason: `npm registry lookup failed: ${e.message}` }; }
+  const signals = [];
+  const notes = [];
+  if (pack === null) {
+    return { checked: true, signals: [{ id: 'removed', detail: `${name} is no longer on the npm registry (HTTP 404). The whole package was unpublished or taken down.` }], notes, comparison: null };
+  }
+  const times = pack.time ?? {};
+  const v = pack.versions?.[version];
+  if (!v) {
+    const when = times[version] ? ` It was published ${times[version]} and has since been removed.` : '';
+    return { checked: true, signals: [{ id: 'removed', detail: `${name}@${version} is not on the npm registry.${when} Registries remove versions mainly after malware or a security takedown.` }], notes, comparison: null };
+  }
+
+  const published = ms(times[version]);
+  const age = published === null ? null : now - published;
+  const prevLock = prevVersion && pack.versions[prevVersion] ? prevVersion : null;
+  const prev = prevLock ?? previousByTime(Object.keys(pack.versions), (x) => ms(times[x]), version, isPrerelease);
+  const comparison = prev ? { version: prev, source: prevLock ? 'base lockfile' : 'previous registry release' } : null;
+  const pv = prev ? pack.versions[prev] : null;
+
+  const fresh = age !== null && age >= 0 && age < FRESH_MS;
+  if (fresh) signals.push({ id: 'fresh', detail: `${name}@${version} was published ${hours(age)} ago (under 72 hours).` });
+
+  let newScripts = [];
+  let recentNewDeps = [];
+  if (pv) {
+    if (pv.dist?.attestations && !v.dist?.attestations) {
+      signals.push({ id: 'provenance-dropped', detail: `${name}@${prev} (${comparison.source}) has npm provenance attestations, but ${name}@${version} does not.` });
+    }
+    const was = pv._npmUser?.name;
+    const now_ = v._npmUser?.name;
+    if (was && now_ && was !== now_) signals.push({ id: 'publisher-changed', detail: `Published by "${now_}" instead of "${was}" (the publisher of ${name}@${prev}).` });
+    newScripts = INSTALL_SCRIPTS.filter((s) => v.scripts?.[s] && !pv.scripts?.[s]);
+    if (newScripts.length) signals.push({ id: 'new-install-script', detail: `New install-time script(s): ${newScripts.map((s) => `${s}: ${String(v.scripts[s]).slice(0, 120)}`).join('; ')}.`, scripts: newScripts });
+    const newDeps = Object.keys(v.dependencies ?? {}).filter((d) => !(d in (pv.dependencies ?? {})));
+    if (newDeps.length) {
+      recentNewDeps = await newDependencySignal(reg, newDeps, now, notes, (d) => reg.npmCreated(d));
+      signals.push({ id: 'new-dependencies', detail: `New dependencies compared with ${name}@${prev}: ${newDeps.join(', ')}.${recentNewDeps.length ? ` Created under 30 days ago: ${recentNewDeps.map((d) => `${d.name} (${d.ageDays} days old)`).join(', ')}.` : ''}`, names: newDeps, recent: recentNewDeps });
+    }
+  } else {
+    // A first release has nothing to compare with, but an install-time script in it is still new to everyone who installs it.
+    newScripts = INSTALL_SCRIPTS.filter((s) => v.scripts?.[s]);
+    if (newScripts.length) signals.push({ id: 'new-install-script', detail: `First release of ${name}, and it has install-time script(s): ${newScripts.map((s) => `${s}: ${String(v.scripts[s]).slice(0, 120)}`).join('; ')}.`, scripts: newScripts });
+    notes.push('no earlier release to compare with, so provenance, publisher and dependency changes were not evaluated');
+  }
+
+  if (added) {
+    const created = ms(times.created);
+    const reasons = [];
+    if (created !== null && now - created < NEW_PACKAGE_MS) reasons.push(`the package was created ${days(now - created)} ago`);
+    try {
+      const dl = await reg.npmDownloads(name);
+      if (dl && Number.isFinite(dl.downloads) && dl.downloads < LOW_WEEKLY_DOWNLOADS) reasons.push(`it had ${dl.downloads} downloads in the last week`);
+      if (dl === null) notes.push('npm download counts are not available for this package');
+    } catch (e) { notes.push(`weekly downloads could not be read: ${e.message}`); }
+    if (reasons.length) signals.push({ id: 'low-reputation', detail: `New to this project, and ${reasons.join(' and ')}.` });
+  }
+  return { checked: true, signals, notes, comparison, facts: { published: times[version] ?? null, newScripts, recentNewDeps: recentNewDeps.map((d) => d.name) } };
+}
+
+const requiresNames = (info) => [...new Set((info?.requires_dist ?? [])
+  .filter((r) => !/;\s*.*\bextra\s*==/.test(r))
+  .map((r) => /^([A-Za-z0-9][A-Za-z0-9._-]*)/.exec(r)?.[1])
+  .filter(Boolean)
+  .map((n) => n.toLowerCase().replace(/[-_.]+/g, '-')))];
+
+export async function analyzePyPI(reg, { name, version, prevVersion, added }) {
+  const now = reg.nowMs;
+  let vj; let project;
+  try {
+    vj = await reg.pypiVersion(name, version);
+    project = await reg.pypiProject(name);
+  } catch (e) { return { checked: false, reason: `PyPI lookup failed: ${e.message}` }; }
+  const notes = ['PyPI provenance and publisher are not exposed in the PyPI JSON API, so provenance-drop and publisher-change were not evaluated'];
+  if (vj === null || project === null) {
+    return { checked: true, signals: [{ id: 'removed', detail: `${name}==${version} is not on PyPI (HTTP 404). Removed releases are often malware takedowns.` }], notes, comparison: null };
+  }
+  const signals = [];
+  const files = vj.urls ?? [];
+  if (files.length && files.every((f) => f.yanked)) {
+    signals.push({ id: 'yanked', detail: `${name}==${version} was yanked by its maintainers${files[0].yanked_reason ? `: ${files[0].yanked_reason}` : ''}.` });
+  }
+  const published = earliestUpload(files);
+  const age = published === null ? null : now - published;
+  const fresh = age !== null && age >= 0 && age < FRESH_MS;
+  if (fresh) signals.push({ id: 'fresh', detail: `${name}==${version} was uploaded ${hours(age)} ago (under 72 hours).` });
+
+  const releases = project.releases ?? {};
+  const timeOf = (x) => earliestUpload(releases[x]);
+  const prevLock = prevVersion && releases[prevVersion] ? prevVersion : null;
+  const prev = prevLock ?? previousByTime(Object.keys(releases), timeOf, version, (x) => !pyReleaseLike(x));
+  const comparison = prev ? { version: prev, source: prevLock ? 'base lockfile' : 'previous registry release' } : null;
+  let recentNewDeps = [];
+  if (prev) {
+    let pj = null;
+    try { pj = await reg.pypiVersion(name, prev); } catch (e) { notes.push(`comparison release metadata could not be read: ${e.message}`); }
+    if (pj) {
+      const had = new Set(requiresNames(pj.info));
+      const newDeps = requiresNames(vj.info).filter((d) => !had.has(d));
+      if (newDeps.length) {
+        recentNewDeps = await newDependencySignal(reg, newDeps, now, notes, (d) => reg.pypiCreated(d));
+        signals.push({ id: 'new-dependencies', detail: `New dependencies compared with ${name}==${prev}: ${newDeps.join(', ')}.${recentNewDeps.length ? ` Created under 30 days ago: ${recentNewDeps.map((d) => `${d.name} (${d.ageDays} days old)`).join(', ')}.` : ''}`, names: newDeps, recent: recentNewDeps });
+      }
+    }
+  } else {
+    notes.push('no earlier release to compare with, so dependency changes were not evaluated');
+  }
+  if (added) {
+    const created = earliestUpload(Object.values(releases).flat());
+    if (created !== null && now - created < NEW_PACKAGE_MS) signals.push({ id: 'low-reputation', detail: `New to this project, and the package was created ${days(now - created)} ago. PyPI offers no download counts, so popularity was not checked.` });
+  }
+  return { checked: true, signals, notes, comparison, facts: { published: published === null ? null : new Date(published).toISOString(), newScripts: [], recentNewDeps: recentNewDeps.map((d) => d.name) } };
+}
+
+export { SIGNAL_FIX_PIN };