@theoptimalpartner/npm-security-kit 1.0.1 → 2.0.0-beta.0

package/src/init.js

@@ -0,0 +1,236 @@
+// `init`: deja un repo listo para el kit sin pisar nada. Completa .npmrc y engines, lista los
+// install scripts por aprobar y muestra (sin editarlos) los cambios del pipeline y de los
+// Dockerfiles. No pregunta nada: corre igual sin TTY.
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import * as dockerfileCheck from './checks/dockerfile.js';
+import { OVERRIDE_ENV, packagesWithScripts } from './checks/install-scripts.js';
+import * as nodeVersionCheck from './checks/node-version.js';
+import * as npmPolicyCheck from './checks/npm-policy.js';
+import { loadAllowPolicy, verdict } from './lib/allow-scripts.js';
+import { lockfileName } from './lib/audit.js';
+import { unifiedDiff } from './lib/diff.js';
+import { loadCalendar } from './lib/node-calendar.js';
+import { parseNpmrc, requiredSettings, settingProblem } from './lib/npmrc.js';
+import { compareVersions, minVersion, parseVersion } from './lib/semver.js';
+import { formatBlocks } from './report.js';
+import { runChecks } from './run.js';
+
+const PACKAGE = '@theoptimalpartner/npm-security-kit';
+
+// Agrega las claves de la política que faltan (con su comentario) y corrige las que tienen otro
+// valor. No borra ni reordena nada.
+export function mergeNpmrc(text, policy) {
+  const original = text ?? '';
+  const eol = original.includes('\r\n') ? '\r\n' : '\n';
+  const lines = original ? original.replace(/\r?\n$/, '').split(/\r?\n/) : [];
+  const npmrc = parseNpmrc(original);
+  const changes = [];
+  const additions = [];
+  for (const setting of requiredSettings(policy)) {
+    const problem = settingProblem(setting, npmrc, policy);
+    if (!problem) continue;
+    const line = `${setting.key}${setting.array ? '[]' : ''}=${setting.value}`;
+    if (problem === 'value') {
+      const entry = npmrc.get(setting.key);
+      // Conserva cómo estaba escrita la clave y el comentario al final de la línea.
+      lines[entry.line - 1] = `${entry.rawKey}=${setting.value}${entry.comment ? ` ${entry.comment}` : ''}`;
+      changes.push(`${line} (antes: ${setting.key}=${entry.value})`);
+    } else {
+      additions.push('', `# ${setting.comment}`, line);
+      changes.push(line);
+    }
+  }
+  if (!changes.length) return { text: original, changes };
+  if (!lines.length) additions.shift(); // archivo nuevo: sin línea en blanco al principio
+  return { text: `${[...lines, ...additions].join(eol)}${eol}`, changes };
+}
+
+function jsonFormat(text) {
+  return {
+    indent: text.match(/^[ \t]+(?=")/m)?.[0] ?? '  ',
+    eol: text.includes('\r\n') ? '\r\n' : '\n',
+    finalNewline: /\n$/.test(text),
+  };
+}
+
+// engines.npm (si falta o admite un npm viejo) y engines.node (solo si falta), conservando la
+// indentación y el salto de línea final del archivo.
+export function mergePackageJson(text, policy, nodeMajor) {
+  const pkg = JSON.parse(text);
+  const changes = [];
+  const minNpm = policy.minNpmVersion.replace(/\.0$/, '');
+  const engines = { ...(pkg.engines ?? {}) };
+  const currentNpm = typeof engines.npm === 'string' ? minVersion(engines.npm) : null;
+  if (!currentNpm || compareVersions(currentNpm, policy.minNpmVersion) < 0) {
+    changes.push(`engines.npm: ">=${minNpm}"${engines.npm ? ` (antes: "${engines.npm}")` : ''}`);
+    engines.npm = `>=${minNpm}`;
+  }
+  if (engines.node === undefined && nodeMajor) {
+    engines.node = `>=${nodeMajor}`;
+    changes.push(`engines.node: ">=${nodeMajor}"`);
+  }
+  if (!changes.length) return { text, changes };
+  pkg.engines = engines;
+  const { indent, eol, finalNewline } = jsonFormat(text);
+  const out = JSON.stringify(pkg, null, indent).replace(/\n/g, eol);
+  return { text: finalNewline ? `${out}${eol}` : out, changes };
+}
+
+export function pipelineStep(kitVersion, nodeVersion) {
+  return `- step: &test
+    name: Test (supply chain + build)
+    image: node:${nodeVersion}
+    caches:
+      - npm
+    script:
+      # Antes de instalar: malware, vulnerabilidades, Node, .npmrc, install scripts, Dockerfiles
+      - npx --yes ${PACKAGE}@${kitVersion} check
+      - npm ci
+      - npm audit signatures
+      - npm run build
+pipelines:
+  pull-requests:
+    '**':
+      - step:
+          <<: *test
+          condition:
+            state: BITBUCKET_PR_DESTINATION_BRANCH == "develop" || BITBUCKET_PR_DESTINATION_BRANCH == "main"`;
+}
+
+// ctx que ve los archivos como quedarían después de init (para el resumen de --dry-run) y
+// cachea el calendario de Node.
+function overlay(ctx, files) {
+  const cache = new Map();
+  const view = {
+    ...ctx,
+    readFile: (f) => (f in files ? files[f] : ctx.readFile(f)),
+    readJson: (f) => (f in files ? JSON.parse(files[f]) : ctx.readJson(f)),
+    exists: (f) => f in files || ctx.exists(f),
+    fetchJson: (url, opts) => {
+      if (!cache.has(url)) cache.set(url, ctx.fetchJson(url, opts));
+      return cache.get(url);
+    },
+    runNpm: async (args) => {
+      // El modo efectivo de strict-allow-scripts sale del .npmrc nuevo, salvo que lo pise el entorno.
+      if (args.join(' ') === 'config get strict-allow-scripts' && '.npmrc' in files) {
+        const env = ctx.env[OVERRIDE_ENV] ?? ctx.env[OVERRIDE_ENV.toUpperCase()];
+        const value = env ?? parseNpmrc(files['.npmrc']).get('strict-allow-scripts')?.value ?? 'false';
+        return { code: 0, stdout: `${value}\n`, stderr: '' };
+      }
+      return ctx.runNpm(args);
+    },
+  };
+  return view;
+}
+
+export async function runInit(ctx, { dryRun = false, stdout = process.stdout, color = false } = {}) {
+  const paint = (code, text) => (color ? `\u001b[${code}m${text}\u001b[0m` : text);
+  const out = [];
+  const say = (line = '') => out.push(line);
+  const section = (title) => {
+    say();
+    say(paint(1, title));
+  };
+
+  const pkgText = ctx.readFile('package.json');
+  if (pkgText === null) {
+    stdout.write(`npm-security-kit: no hay package.json en ${ctx.dir}. init se corre en la raíz de un proyecto npm.\n`);
+    return 2;
+  }
+
+  const files = {};
+  const view = overlay(ctx, files);
+  let cal = null;
+  try {
+    cal = await loadCalendar(view);
+  } catch (error) {
+    cal = { error };
+  }
+  const nodeVersion = cal.recommended;
+  const nodeMajor = nodeVersion ? parseVersion(nodeVersion)[0] : null;
+
+  say(paint(2, `npm-security-kit ${ctx.kitVersion} · init${dryRun ? ' --dry-run' : ''} · ${ctx.dir}`));
+
+  // 1. .npmrc y package.json
+  const npmrcBefore = ctx.readFile('.npmrc');
+  const npmrc = mergeNpmrc(npmrcBefore, ctx.policy);
+  const pkg = mergePackageJson(pkgText, ctx.policy, nodeMajor);
+  if (npmrc.changes.length) files['.npmrc'] = npmrc.text;
+  if (pkg.changes.length) files['package.json'] = pkg.text;
+
+  section(dryRun ? 'Cambios que haría (no se escribió nada)' : 'Cambios');
+  if (!npmrc.changes.length && !pkg.changes.length) {
+    say('  Sin cambios: .npmrc y package.json ya cumplen la política.');
+  } else if (dryRun) {
+    if (npmrc.changes.length) say(unifiedDiff('.npmrc', npmrcBefore, npmrc.text).trimEnd());
+    if (pkg.changes.length) say(unifiedDiff('package.json', pkgText, pkg.text).trimEnd());
+  } else {
+    for (const [file, text] of Object.entries(files)) writeFileSync(join(ctx.dir, file), text);
+    for (const c of npmrc.changes) say(`  .npmrc        ${npmrcBefore === null ? '(nuevo) ' : ''}+ ${c}`);
+    for (const c of pkg.changes) say(`  package.json  + ${c}`);
+  }
+  if (cal.error) say(`  No se pudo leer el calendario de Node (${cal.error.message}): engines.node no se completó.`);
+
+  // 2. Install scripts por aprobar
+  section('Install scripts por aprobar (allowScripts en package.json)');
+  const lockfile = lockfileName(ctx);
+  if (!lockfile) {
+    say('  No hay package-lock.json: generarlo con `npm install --package-lock-only` y volver a correr init.');
+  } else {
+    const policy = loadAllowPolicy(JSON.parse(view.readFile('package.json')), view.readFile('.npmrc'));
+    const pending = [
+      ...new Set(
+        packagesWithScripts(ctx.readJson(lockfile), ctx)
+          .filter((d) => verdict(policy.rules, d) === null)
+          .map((d) => `${d.name}@${d.version}${d.entry.optional && d.entry.os ? ` (opcional, solo ${d.entry.os.join('/')})` : ''}`),
+      ),
+    ];
+    if (!pending.length) {
+      say('  Ninguno: todos los paquetes con install scripts están aprobados o negados.');
+    } else {
+      for (const p of pending) say(`  - ${p}`);
+      say('  init no aprueba nada solo. Para revisarlos:');
+      say('    npm ci --ignore-scripts');
+      say('    npm install-scripts ls');
+      say('    npm install-scripts approve <paquete>   # lo que necesita compilar o descargar binarios');
+      say('    npm install-scripts deny <paquete>      # telemetría, publicidad o lo que no haga falta');
+    }
+  }
+
+  // 3. Pipeline (no se edita)
+  section('Pipeline: bitbucket-pipelines.yml (init no lo edita)');
+  const pipeline = ctx.readFile('bitbucket-pipelines.yml');
+  const used = pipeline?.match(/npm-security-kit@([\w.-]+)/);
+  if (used) {
+    say(`  Ya corre el kit (${used[0]}).${used[1] !== ctx.kitVersion ? ` Para esta versión: ${PACKAGE}@${ctx.kitVersion}.` : ''}`);
+  } else {
+    say(`  ${pipeline === null ? 'No hay bitbucket-pipelines.yml. ' : ''}Agregar el kit en el step de test, ANTES de npm ci, y correrlo solo en los PR a ramas que despliegan:`);
+    say();
+    for (const line of pipelineStep(ctx.kitVersion, nodeVersion ?? '<versión LTS>').split('\n')) say(`    ${line}`);
+  }
+
+  // 4. Dockerfiles (no se editan)
+  section('Dockerfiles (init no los edita)');
+  const docker = await dockerfileCheck.run(view);
+  if (!docker.length) say('  Sin cambios sugeridos.');
+  for (const f of docker) say(`  ${f.level === 'error' ? '✗' : '⚠'} ${f.file}:${f.line}  ${f.message}`);
+
+  // 5. Lo que queda: chequeos de configuración sobre el resultado
+  section(`Resumen${dryRun ? ' (como quedaría)' : ''}`);
+  const summaryChecks = [nodeVersionCheck, npmPolicyCheck];
+  const { results } = await runChecks(summaryChecks, view);
+  say(formatBlocks(summaryChecks, results, { color, indent: '  ' }).trimEnd());
+
+  section('Pasos siguientes');
+  const steps = [
+    dryRun ? 'Correr init sin --dry-run.' : 'Revisar el diff: git diff .npmrc package.json',
+    'Aprobar o negar los install scripts pendientes.',
+    'Agregar el step al pipeline y corregir los Dockerfiles.',
+    `Correr el chequeo completo: npx --yes ${PACKAGE}@${ctx.kitVersion} check`,
+  ];
+  steps.forEach((s, i) => say(`  ${i + 1}. ${s}`));
+
+  stdout.write(`${out.join('\n')}\n`);
+  return 0;
+}

package/src/lib/allow-scripts.js

@@ -0,0 +1,61 @@
+// La política allowScripts de npm 11, con las mismas reglas de coincidencia que npm
+// (@npmcli/arborist script-allowed.js) para los casos que revisa el kit.
+import { parseNpmrc } from './npmrc.js';
+
+const SOURCE_KEY = /^(git\+|git:|github:|gitlab:|bitbucket:|https?:|file:|\.{0,2}\/)/;
+const EXACT = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+// `pkg`, `pkg@*`, `pkg@1.2.3`, `pkg@1.2.3 || 1.2.4`, `@scope/pkg@1.2.3`, o un origen (git, file, url).
+export function parseAllowKey(key) {
+  if (SOURCE_KEY.test(key)) return { key, source: key };
+  const at = key.lastIndexOf('@');
+  const name = at > 0 ? key.slice(0, at) : key;
+  const spec = at > 0 ? key.slice(at + 1).trim() : '';
+  if (!spec || spec === '*') return { key, name, versions: null };
+  const parts = spec.split('||').map((p) => p.trim());
+  if (parts.every((p) => EXACT.test(p))) return { key, name, versions: new Set(parts) };
+  // Con `v` adelante npm la acepta pero nunca coincide (compara contra la versión de la URL).
+  if (parts.every((p) => EXACT.test(p.replace(/^v/, '')))) return { key, name, ignored: 'versión con "v": escribirla sin la "v"' };
+  // npm descarta los rangos (^, ~, >=, <) y los dist-tags: la entrada no aprueba ni niega nada.
+  return { key, name, ignored: /^[a-z]/i.test(spec) ? 'dist-tag' : 'rango semver' };
+}
+
+// La política efectiva: el campo allowScripts del package.json raíz o, si no está, la clave
+// `allow-scripts` del .npmrc (lista de nombres). Como npm, la primera que exista gana entera.
+export function loadAllowPolicy(pkg, npmrcText) {
+  let ignored = [];
+  if (pkg?.allowScripts && typeof pkg.allowScripts === 'object') {
+    const rules = Object.entries(pkg.allowScripts).map(([key, value]) => ({ ...parseAllowKey(key), allow: value }));
+    ignored = rules.filter((r) => r.ignored && !r.versions);
+    // Como npm: si todas las claves se descartan, el package.json no tiene política y vale el .npmrc.
+    if (rules.some((r) => !r.ignored)) return { source: 'package.json', rules, ignored };
+  }
+  const names = parseNpmrc(npmrcText)
+    .getAll('allow-scripts')
+    .flatMap((e) => e.value.split(','))
+    .map((n) => n.trim())
+    .filter(Boolean);
+  if (names.length) return { source: '.npmrc', rules: names.map((n) => ({ ...parseAllowKey(n), allow: true })), ignored };
+  return { source: null, rules: [], ignored };
+}
+
+// Como npm, una regla por nombre solo vale para paquetes del registro: no aprueba un tarball
+// local ni un repo git que se llamen igual.
+const fromRegistry = (entry) => !entry.resolved || /^https?:\/\/[^/]+\/.+\/-\/[^/]+-\d/.test(entry.resolved);
+
+const matches = (rule, dep) => {
+  if (rule.ignored) return false;
+  if (rule.source) return dep.entry.resolved === rule.source;
+  return fromRegistry(dep.entry) && rule.name === dep.name && (!rule.versions || rule.versions.has(dep.version));
+};
+
+// true (aprobado), false (negado: `false` le gana a `true`) o null (pendiente).
+export function verdict(rules, dep) {
+  let allow = false;
+  for (const rule of rules) {
+    if (!matches(rule, dep)) continue;
+    if (rule.allow === false) return false;
+    if (rule.allow === true) allow = true;
+  }
+  return allow ? true : null;
+}

package/src/lib/audit.js

@@ -0,0 +1,80 @@
+// `npm audit --json` sobre el lockfile, antes de `npm ci`. Distingue una falla del endpoint de
+// advisories (red, 5xx) de un reporte con vulnerabilidades: npm devuelve exit 1 en los dos casos.
+
+export class AuditUnavailableError extends Error {}
+
+const SEVERITY_RANK = { info: 0, low: 1, moderate: 2, high: 3, critical: 4 };
+export const severityAtLeast = (severity, level) => (SEVERITY_RANK[severity] ?? -1) >= (SEVERITY_RANK[level] ?? 99);
+
+export function lockfileName(ctx) {
+  if (ctx.exists('npm-shrinkwrap.json')) return 'npm-shrinkwrap.json';
+  if (ctx.exists('package-lock.json')) return 'package-lock.json';
+  return null;
+}
+
+function parseReport(stdout) {
+  let report;
+  try {
+    report = JSON.parse(stdout);
+  } catch {
+    return { problem: 'la respuesta de npm audit no es JSON' };
+  }
+  if (report && typeof report.vulnerabilities === 'object' && report.vulnerabilities !== null && !report.error) {
+    return { report };
+  }
+  const detail = report?.message || report?.error?.summary || report?.error?.code || 'respuesta sin "vulnerabilities"';
+  return { problem: String(detail).split('\n')[0] };
+}
+
+// `--package-lock-only` hace que npm audite el lockfile aunque haya node_modules. Los `--include`
+// le ganan a un `omit` del entorno (por ejemplo NODE_ENV=production, que esconde las devDependencies).
+export async function runAudit(ctx, extraArgs, { attempts = 3 } = {}) {
+  const args = ['audit', '--json', '--package-lock-only', ...extraArgs];
+  let problem;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    if (attempt > 1) await ctx.sleep(2000 * (attempt - 1));
+    const { stdout, stderr } = await ctx.runNpm(args);
+    const parsed = parseReport(stdout);
+    if (parsed.report) return parsed.report;
+    problem = parsed.problem === 'la respuesta de npm audit no es JSON' && stderr.trim() ? stderr.trim().split('\n')[0] : parsed.problem;
+  }
+  throw new AuditUnavailableError(problem);
+}
+
+export const unavailableFinding = (error) => ({
+  level: 'error',
+  message: `no se pudo consultar los advisories del registro (${error.message}); reintentar el step. No es un hallazgo de seguridad: el registro de npm no respondió.`,
+});
+
+// Cada advisory del reporte, atribuido al paquete vulnerable. Las entradas `via` que son texto
+// solo apuntan a otro paquete del reporte, y ese paquete trae el advisory completo.
+export function advisoriesOf(report) {
+  const out = [];
+  for (const [pkg, vuln] of Object.entries(report.vulnerabilities ?? {})) {
+    for (const via of vuln.via ?? []) {
+      if (!via || typeof via !== 'object') continue;
+      out.push({
+        name: via.name ?? pkg,
+        source: via.source,
+        title: via.title ?? '',
+        url: via.url,
+        severity: via.severity,
+        cwe: via.cwe ?? [],
+        range: via.range,
+        nodes: vuln.nodes ?? [],
+        fixAvailable: vuln.fixAvailable,
+      });
+    }
+  }
+  return out;
+}
+
+// El título es solo un respaldo para advisories sin CWE: hay vulnerabilidades comunes cuyo título
+// dice "malicious" ("bypass malicious or unwanted attributes", CWE-91), y no son malware.
+const MALWARE_TITLE = /\bmalware\b|\bmalicious (code|package|version)s?\b/i;
+
+export const isMalware = (advisory, policy) =>
+  advisory.cwe.some((cwe) => policy.malwareCwe.includes(cwe)) || (!advisory.cwe.length && MALWARE_TITLE.test(advisory.title));
+
+// Clave estable de un advisory sobre un paquete (un mismo GHSA puede aparecer en varios).
+export const advisoryKey = (a) => `${a.name}\u0000${a.source ?? a.url ?? a.title}`;

package/src/lib/diff.js

@@ -0,0 +1,54 @@
+// Diff unificado de dos textos (por líneas, con LCS), para `init --dry-run`. Los archivos que
+// toca init son chicos: no hace falta nada más eficiente.
+
+export function unifiedDiff(file, before, after, context = 3) {
+  if (before === after) return '';
+  const a = before === null ? [] : before.replace(/\n$/, '').split('\n');
+  const b = after.replace(/\n$/, '').split('\n');
+  const n = a.length;
+  const m = b.length;
+  const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    }
+  }
+  // Operaciones: [' ', línea] igual, ['-', línea] sale, ['+', línea] entra.
+  const ops = [];
+  let i = 0;
+  let j = 0;
+  while (i < n || j < m) {
+    if (i < n && j < m && a[i] === b[j]) {
+      ops.push([' ', a[i], i, j]);
+      i++;
+      j++;
+    } else if (j < m && (i >= n || lcs[i][j + 1] >= lcs[i + 1][j])) {
+      ops.push(['+', b[j], i, j]);
+      j++;
+    } else {
+      ops.push(['-', a[i], i, j]);
+      i++;
+    }
+  }
+  // Agrupa los cambios en hunks con `context` líneas alrededor.
+  const changed = ops.map((op, k) => (op[0] !== ' ' ? k : -1)).filter((k) => k >= 0);
+  const hunks = [];
+  for (const k of changed) {
+    const last = hunks.at(-1);
+    if (last && k - last.end <= context * 2) last.end = k;
+    else hunks.push({ start: k, end: k });
+  }
+  const out = [`--- a/${file}${before === null ? ' (no existe)' : ''}`, `+++ b/${file}`];
+  for (const h of hunks) {
+    const from = Math.max(0, h.start - context);
+    const to = Math.min(ops.length - 1, h.end + context);
+    const slice = ops.slice(from, to + 1);
+    const oldStart = slice[0][2] + 1;
+    const newStart = slice[0][3] + 1;
+    const oldLen = slice.filter((o) => o[0] !== '+').length;
+    const newLen = slice.filter((o) => o[0] !== '-').length;
+    out.push(`@@ -${oldLen ? oldStart : oldStart - 1},${oldLen} +${newLen ? newStart : newStart - 1},${newLen} @@`);
+    for (const [kind, line] of slice) out.push(`${kind}${line}`);
+  }
+  return `${out.join('\n')}\n`;
+}

package/src/lib/dockerfile.js

@@ -0,0 +1,74 @@
+// Lectura de Dockerfiles: dónde están, instrucciones lógicas (con las líneas continuadas con `\`)
+// y la imagen de cada `FROM`.
+
+// `Dockerfile`, `Dockerfile.dev`, `dev.Dockerfile`, `Containerfile` (y `dockerfile`). No cuenta código
+// ni documentos que se llaman parecido (`dockerfile.js`, `Dockerfile.md`) ni los `.dockerignore`.
+const NOT_DOCKERFILE = /\.(dockerignore|[cm]?[jt]sx?|json|ya?ml|md|txt|py|rb|go|java|kt|sh|ps1|toml|lock|tpl|j2|erb|ejs|hbs|template)$/i;
+export const isDockerfile = (name) =>
+  !NOT_DOCKERFILE.test(name) && (/^(Dockerfile|Containerfile|dockerfile)(\.[\w.-]+)?$/.test(name) || /\.(Dockerfile|Containerfile)$/.test(name));
+
+export const findDockerfiles = (ctx) => ctx.listFiles(isDockerfile, 3);
+
+// Instrucciones lógicas: `{ instruction, args, line }`, con `line` = la línea donde empieza.
+export function parseInstructions(text) {
+  const out = [];
+  const lines = text.split(/\r?\n/);
+  let current = null;
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (current) {
+      // Dentro de una instrucción continuada, los comentarios y las líneas vacías se saltan.
+      if (/^\s*#/.test(raw) || !raw.trim()) continue;
+      const cont = raw.replace(/\\\s*$/, '');
+      current.args += ` ${cont.trim()}`;
+      if (cont === raw) current = null;
+      continue;
+    }
+    if (/^\s*#/.test(raw) || !raw.trim()) continue;
+    const m = raw.match(/^\s*([A-Za-z]+)\s*(.*)$/);
+    if (!m) continue;
+    const body = m[2].replace(/\\\s*$/, '');
+    const entry = { instruction: m[1].toUpperCase(), args: body.trim(), line: i + 1 };
+    out.push(entry);
+    if (body !== m[2]) current = entry;
+  }
+  return out;
+}
+
+// Reemplaza `${VAR}`, `${VAR:-x}` y `$VAR` con los valores de `vars`.
+export function substitute(text, vars) {
+  return text
+    .replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::?-([^}]*))?\}/g, (all, name, def) => vars[name] ?? def ?? all)
+    .replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (all, name) => vars[name] ?? all);
+}
+
+// Etapas del Dockerfile: `{ from: { image, line, raw }, instructions: [...] }`. La imagen ya
+// tiene reemplazados los ARG declarados antes del primer FROM.
+export function parseStages(text) {
+  const globalArgs = {};
+  const stages = [];
+  for (const ins of parseInstructions(text)) {
+    if (ins.instruction === 'FROM') {
+      const tokens = substitute(ins.args, globalArgs).split(/\s+/).filter((t) => !t.startsWith('--'));
+      const as = tokens.findIndex((t) => /^as$/i.test(t));
+      const name = as > 0 ? tokens[as + 1]?.toLowerCase() : undefined;
+      stages.push({ name, from: { image: tokens[0] ?? '', line: ins.line, raw: `FROM ${ins.args}` }, instructions: [] });
+    } else if (!stages.length) {
+      if (ins.instruction === 'ARG') {
+        const m = ins.args.match(/^([A-Za-z_][A-Za-z0-9_]*)(?:=(.*))?$/);
+        if (m && m[2] !== undefined) globalArgs[m[1]] = m[2].replace(/^["']|["']$/g, '');
+      }
+    } else {
+      stages.at(-1).instructions.push(ins);
+    }
+  }
+  return stages;
+}
+
+// Tag de una imagen oficial de Node (`node:TAG`, `library/node:TAG`, `mirror/…/node:TAG`).
+// `node` sin tag es `latest`. Devuelve null si la imagen no es de Node.
+export function nodeImageTag(image) {
+  const m = image.match(/^(?:[^@\s]*\/)?node(?::([\w.-]+))?(@sha256:[a-f0-9]+)?$/i);
+  if (!m) return null;
+  return m[1] ?? (m[2] ? null : 'latest');
+}

package/src/lib/json-lines.js

@@ -0,0 +1,12 @@
+// Línea (1-based) de una clave anidada en un JSON formateado (`['engines', 'node']`), o undefined.
+export function jsonKeyLine(text, keys) {
+  const lines = text.split(/\r?\n/);
+  let from = 0;
+  for (const key of keys) {
+    const re = new RegExp(`^\\s*"${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}"\\s*:`);
+    const found = lines.findIndex((l, i) => i >= from && re.test(l));
+    if (found < 0) return undefined;
+    from = found;
+  }
+  return from + 1;
+}

package/src/lib/lockfile.js

@@ -0,0 +1,48 @@
+// Recorrido de las entradas de `packages` de un package-lock.json v2/v3.
+
+// `node_modules/a/node_modules/@s/b` → `@s/b`.
+export const nameFromKey = (key) => key.slice(key.lastIndexOf('node_modules/') + 'node_modules/'.length);
+
+// Nombre y versión según la URL del registro (`https://host/<nombre>/-/<archivo>-<versión>.tgz`).
+// npm usa esta identidad para allowScripts, porque el package.json del tarball se puede falsear.
+export function registryIdentity(resolved) {
+  const m = typeof resolved === 'string' && resolved.match(/^https?:\/\/[^/]+\/(.+)\/-\/([^/]+)\.tgz(?:[?#].*)?$/);
+  if (!m) return null;
+  const name = decodeURIComponent(m[1]).replace(/%2f/gi, '/');
+  const base = name.split('/').pop();
+  const version = m[2].startsWith(`${base}-`) ? m[2].slice(base.length + 1) : null;
+  return { name, version };
+}
+
+// lockfileVersion 1 (sin `packages`): las entradas salen del árbol `dependencies`.
+function v1Packages(dependencies, prefix = '', out = {}) {
+  for (const [name, dep] of Object.entries(dependencies ?? {})) {
+    const key = `${prefix}node_modules/${name}`;
+    out[key] = { ...dep, inBundle: dep.bundled, link: typeof dep.version === 'string' && dep.version.startsWith('file:') };
+    v1Packages(dep.dependencies, `${key}/`, out);
+  }
+  return out;
+}
+
+// Entradas de dependencias: `{ key, name, version, entry }`, sin la raíz, los links ni los
+// workspaces.
+export function* lockEntries(lock) {
+  const packages = lock?.packages ?? v1Packages(lock?.dependencies);
+  for (const [key, entry] of Object.entries(packages)) {
+    if (!key || entry.link || !key.includes('node_modules/')) continue;
+    const id = registryIdentity(entry.resolved);
+    yield { key, name: id?.name ?? entry.name ?? nameFromKey(key), version: id?.version ?? entry.version, entry };
+  }
+}
+
+// ¿La entrada se instala en esta plataforma? Las opcionales con `os`/`cpu` de otra plataforma
+// (fsevents en Linux) npm no las instala y sus scripts no corren.
+const allowedOn = (list, value) => {
+  if (!Array.isArray(list) || !list.length) return true;
+  if (list.includes(`!${value}`)) return false;
+  const positive = list.filter((v) => !v.startsWith('!'));
+  return !positive.length || positive.includes(value);
+};
+
+export const installsOn = (entry, { platform, arch }) =>
+  !(entry.optional || entry.devOptional) || (allowedOn(entry.os, platform) && allowedOn(entry.cpu, arch));

package/src/lib/node-calendar.js

@@ -0,0 +1,73 @@
+// Calendario de Node, leído de nodejs.org en cada corrida: acá no hay fechas ni versiones fijas.
+// La fase de cada línea sale de las fechas de schedule.json, no del campo `lts` de index.json,
+// que recién cambia cuando sale la primera release LTS de la línea.
+import { compareVersions, parseVersion } from './semver.js';
+
+export const INDEX_URL = 'https://nodejs.org/dist/index.json';
+export const SCHEDULE_URL = 'https://raw.githubusercontent.com/nodejs/Release/main/schedule.json';
+
+export async function loadCalendar(ctx) {
+  const [index, schedule] = await Promise.all([ctx.fetchJson(INDEX_URL), ctx.fetchJson(SCHEDULE_URL)]);
+  return analyzeCalendar(index, schedule, ctx.today);
+}
+
+const day = (text) => new Date(`${text}T00:00:00Z`);
+const majorOf = (version) => parseVersion(version)[0];
+
+export function analyzeCalendar(index, schedule, today) {
+  const releases = index
+    .filter((r) => parseVersion(r.version))
+    .sort((a, b) => compareVersions(b.version, a.version));
+  const lines = new Map();
+  for (const [key, sch] of Object.entries(schedule)) {
+    const m = key.match(/^v(\d+)$/);
+    if (m) lines.set(Number(m[1]), sch);
+  }
+
+  // eol | not-lts | maintenance | active | unknown
+  const phaseOf = (major) => {
+    const sch = lines.get(major);
+    if (!sch) return 'unknown';
+    if (sch.end && today >= day(sch.end)) return 'eol';
+    if (!sch.lts || today < day(sch.lts)) return 'not-lts';
+    if (sch.maintenance && today >= day(sch.maintenance)) return 'maintenance';
+    return 'active';
+  };
+
+  // La LTS más nueva: la línea de número más alto que ya es LTS y sigue con soporte.
+  const supported = [...lines.keys()].filter((m) => ['active', 'maintenance'].includes(phaseOf(m)));
+  const newestLts = supported.length ? Math.max(...supported) : null;
+
+  const ltsReleases = releases.filter((r) => r.lts);
+  const newestLtsRelease = newestLts !== null ? ltsReleases.find((r) => majorOf(r.version) === newestLts) : undefined;
+  const latestLtsRelease = ltsReleases[0];
+  const recommendedRelease = newestLtsRelease ?? latestLtsRelease;
+
+  return {
+    today,
+    releases,
+    lines,
+    phaseOf,
+    newestLts,
+    // La versión a instalar: la release LTS publicada de la LTS más nueva o, si todavía no salió,
+    // la última release LTS publicada.
+    recommended: recommendedRelease?.version.replace(/^v/, ''),
+    // true si la LTS más nueva todavía no tiene release LTS en index.json.
+    newestLtsWithoutRelease: newestLts !== null && !newestLtsRelease,
+    latestLtsMajor: latestLtsRelease ? majorOf(latestLtsRelease.version) : null,
+    latestMajor: releases.length ? majorOf(releases[0].version) : null,
+    majorOfCodename: (codename) => {
+      const r = ltsReleases.find((x) => String(x.lts).toLowerCase() === codename.toLowerCase());
+      if (r) return majorOf(r.version);
+      for (const [major, sch] of lines) if (sch.codename && sch.codename.toLowerCase() === codename.toLowerCase()) return major;
+      return null;
+    },
+    // Releases de seguridad de la línea posteriores a `version` (de la más nueva a la más vieja).
+    securityAfter: (major, version) =>
+      releases.filter((r) => majorOf(r.version) === major && r.security && compareVersions(r.version, version) > 0),
+    daysUntilEnd: (major) => Math.round((day(lines.get(major).end) - today) / 86400000),
+    // La próxima línea que va a ser LTS después de `major`.
+    nextLtsAfter: (major) =>
+      [...lines.entries()].filter(([m, s]) => m > major && s.lts).map(([m]) => m).sort((a, b) => a - b)[0] ?? null,
+  };
+}