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

package/src/lib/npmrc.js

@@ -0,0 +1,93 @@
+// Lectura del .npmrc del proyecto (formato ini de npm): `clave=valor`, `clave[]=valor` repetible
+// y comentarios con `#` o `;`.
+
+// Como `unsafe()` del paquete `ini` que usa npm: un valor sin comillas se corta en el primer `;` o
+// `#` sin escapar (comentario al final de la línea); uno entre comillas se toma entero.
+function unsafe(raw) {
+  const val = raw.trim();
+  if (/^(["']).*\1$/.test(val)) {
+    let value = val.charAt(0) === "'" ? val.slice(1, -1) : val;
+    try {
+      value = JSON.parse(value);
+    } catch {
+      // como ini: si no es JSON, queda como está
+    }
+    return { value: String(value), comment: '' };
+  }
+  let out = '';
+  for (let i = 0; i < val.length; i++) {
+    const c = val[i];
+    if (c === '\\' && i + 1 < val.length && '\\;#'.includes(val[i + 1])) {
+      out += val[++i];
+    } else if (c === ';' || c === '#') {
+      return { value: out.trim(), comment: val.slice(i).trim() };
+    } else {
+      out += c;
+    }
+  }
+  return { value: out.trim(), comment: '' };
+}
+
+export function parseNpmrc(text) {
+  const entries = [];
+  (text ?? '').split(/\r?\n/).forEach((raw, i) => {
+    const line = raw.trim();
+    if (!line || line.startsWith('#') || line.startsWith(';') || line.startsWith('[')) return;
+    const eq = line.indexOf('=');
+    if (eq < 0) return;
+    const rawKey = line.slice(0, eq).trim();
+    let key = unsafe(rawKey).value;
+    const array = key.endsWith('[]');
+    if (array) key = key.slice(0, -2).trim();
+    const { value, comment } = unsafe(line.slice(eq + 1));
+    entries.push({ key, rawKey, value, comment, line: i + 1, array });
+  });
+  const find = (key) => entries.filter((e) => e.key === key || e.key === key.replace(/-/g, '_'));
+  return {
+    entries,
+    // La última asignación de la clave, como npm.
+    get: (key) => find(key).at(-1),
+    getAll: (key) => find(key),
+  };
+}
+
+// Las claves y valores que pide la política, en el orden en que init las escribe, con el
+// comentario que las acompaña.
+export function requiredSettings(policy) {
+  return [
+    { key: 'min-release-age', value: String(policy.minReleaseAgeDays), comment: `Dependencias externas: mínimo ${policy.minReleaseAgeDays} días desde su publicación` },
+    ...policy.releaseAgeExclude.map((pattern) => ({
+      key: 'min-release-age-exclude',
+      array: true,
+      value: pattern,
+      comment: 'Paquetes internos: se pueden instalar inmediatamente',
+    })),
+    { key: 'save-exact', value: 'true', comment: 'Guardar versiones exactas' },
+    { key: 'engine-strict', value: 'true', comment: 'Validar engines (npm >= la versión mínima de la política)' },
+    { key: 'strict-allow-scripts', value: 'true', comment: 'Install scripts: solo corren los aprobados en allowScripts (package.json)' },
+    { key: 'audit-level', value: policy.vulnerabilityLevel, comment: `npm audit falla solo por vulnerabilidades ${policy.vulnerabilityLevel === 'critical' ? 'críticas' : policy.vulnerabilityLevel}` },
+  ];
+}
+
+const AUDIT_LEVELS = ['info', 'low', 'moderate', 'high', 'critical'];
+
+// ¿El valor del .npmrc cumple la política? Devuelve el problema o null.
+export function settingProblem(setting, npmrc, policy) {
+  if (setting.array) {
+    const values = npmrc.getAll(setting.key).map((e) => e.value);
+    return values.includes(setting.value) ? null : 'missing';
+  }
+  const entry = npmrc.get(setting.key);
+  if (!entry) return 'missing';
+  switch (setting.key) {
+    case 'min-release-age': {
+      const days = Number(entry.value);
+      return Number.isFinite(days) && days >= policy.minReleaseAgeDays ? null : 'value';
+    }
+    case 'audit-level':
+      // Un nivel más estricto que el de la política también sirve.
+      return AUDIT_LEVELS.includes(entry.value) ? null : 'value';
+    default:
+      return entry.value === setting.value ? null : 'value';
+  }
+}

package/src/lib/semver.js

@@ -0,0 +1,74 @@
+// Lo mínimo de semver que necesita el kit, sin dependencias: comparar versiones y obtener la
+// versión más baja que admite un rango (`engines`).
+
+const PART = /^(\d+|x|X|\*)$/;
+
+// `v9.8.7` → [9, 8, 7]. Las partes que faltan o son comodín valen 0. Devuelve null si no es
+// una versión.
+export function parseVersion(text) {
+  const clean = String(text).trim().replace(/^[=v]+/, '').split(/[-+]/)[0];
+  const parts = clean.split('.');
+  if (!parts[0] || parts.length > 3 || !parts.every((p) => PART.test(p))) return null;
+  const nums = parts.map((p) => (/^\d+$/.test(p) ? Number(p) : 0));
+  while (nums.length < 3) nums.push(0);
+  return nums;
+}
+
+export function compareVersions(a, b) {
+  const x = Array.isArray(a) ? a : parseVersion(a);
+  const y = Array.isArray(b) ? b : parseVersion(b);
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] - y[i];
+  return 0;
+}
+
+export const formatVersion = (v) => v.join('.');
+
+// Cuántas partes numéricas trae la versión escrita (`9` → 1, `9.8` → 2, `9.x` → 1).
+const precision = (text) => String(text).replace(/^[=v]+/, '').split(/[-+]/)[0].split('.').filter((p) => /^\d+$/.test(p)).length;
+
+function lowerBound(comparator) {
+  const m = comparator.match(/^(>=|<=|>|<|=|\^|~)?\s*(.*)$/);
+  const [, op = '', rest] = m;
+  if (rest === '' || /^[*xX]$/.test(rest)) return op === '<' ? null : [0, 0, 0];
+  const v = parseVersion(rest);
+  if (!v) return undefined; // no se entiende
+  if (op === '<' || op === '<=') return [0, 0, 0];
+  if (op === '>') {
+    const p = precision(rest);
+    if (p >= 3) return [v[0], v[1], v[2] + 1];
+    if (p === 2) return [v[0], v[1] + 1, 0];
+    return [v[0] + 1, 0, 0];
+  }
+  return v;
+}
+
+// Versión más baja que admite un rango semver (`>=9.1.0` → 9.1.0, `^7 || ^9` → 7.0.0,
+// `11.x` → 11.0.0). Devuelve null si el rango no se entiende o no admite ninguna versión.
+export function minVersion(range) {
+  let best = null;
+  for (const alternative of String(range).split('||')) {
+    const text = alternative.trim();
+    let bound;
+    const hyphen = text.match(/^(\S+)\s+-\s+\S+$/);
+    if (hyphen) {
+      bound = parseVersion(hyphen[1]);
+    } else {
+      // `>= 18` → `>=18`, para separar los comparadores por espacios.
+      const comparators = text.replace(/(>=|<=|>|<|=|\^|~)\s+/g, '$1').split(/\s+/).filter(Boolean);
+      if (!comparators.length) comparators.push('*');
+      bound = [0, 0, 0];
+      for (const c of comparators) {
+        const lb = lowerBound(c);
+        if (lb === undefined) return null;
+        if (lb === null) continue;
+        if (compareVersions(lb, bound) > 0) bound = lb;
+      }
+    }
+    if (!bound) return null;
+    if (!best || compareVersions(bound, best) < 0) best = bound;
+  }
+  return best && formatVersion(best);
+}
+
+// ¿El texto es un rango (y no una versión puntual)?
+export const isRange = (text) => /[<>^~|*xX]|\s-\s/.test(String(text).replace(/^v/, '')) || /\s/.test(String(text).trim());

package/src/policy.js

@@ -0,0 +1,36 @@
+// La política de seguridad de dependencias npm. Es el único lugar con umbrales, días y scopes:
+// los chequeos leen de acá y nunca fijan valores propios. Las versiones y fechas de Node no van
+// acá: se leen de nodejs.org en cada corrida.
+//
+// Cambiar un valor es cambiar la política: va con su decisión fechada y con una versión nueva
+// del kit.
+
+const freeze = (obj) => {
+  for (const value of Object.values(obj)) {
+    if (value && typeof value === 'object') freeze(value);
+  }
+  return Object.freeze(obj);
+};
+
+export const policy = freeze({
+  // Días mínimos desde la publicación de una versión antes de instalarla.
+  minReleaseAgeDays: 7,
+  // Scopes propios que se instalan sin esperar (glob simple `@scope/*`).
+  releaseAgeExclude: ['@theoptimalpartner/*'],
+  // `min-release-age-exclude` existe desde npm 11.17; npm 10 ignora `min-release-age` sin avisar.
+  minNpmVersion: '11.17.0',
+  // Vulnerabilidades (que no son malware) que bloquean, solo en dependencias de producción.
+  vulnerabilityLevel: 'critical',
+  // CWE que identifica un advisory de malware. Bloquea con cualquier severidad y en todo el árbol.
+  malwareCwe: ['CWE-506'],
+  // Únicos orígenes aceptados para el `resolved` de las entradas del lockfile.
+  allowedRegistries: ['https://registry.npmjs.org/'],
+  // Días de soporte restantes de una línea de Node por debajo de los cuales se avisa.
+  nodeEolWarnDays: 180,
+  // Claves del .npmrc del proyecto. `error`: sin ellas la política no se cumple.
+  // `warn`: recomendadas.
+  requiredNpmrc: {
+    error: ['min-release-age', 'engine-strict', 'strict-allow-scripts'],
+    warn: ['min-release-age-exclude[]', 'save-exact', 'audit-level'],
+  },
+});

package/src/report.js

@@ -0,0 +1,68 @@
+// Salida en texto y en JSON del comando `check`.
+
+const ICON = { error: '✗', warn: '⚠', info: 'ℹ', ok: '✓' };
+const COLOR = { error: 31, warn: 33, info: 36, ok: 32, dim: 2, bold: 1 };
+
+export function useColor(stream = process.stdout, env = process.env) {
+  return Boolean(stream.isTTY) && !('NO_COLOR' in env);
+}
+
+const painter = (color) => (code, text) => (color ? `\u001b[${code}m${text}\u001b[0m` : text);
+const location = (r) => (r.file ? `${r.file}${r.line ? `:${r.line}` : ''}` : '');
+const withPin = (r) => [location(r), r.data?.pin].filter(Boolean).join('  ');
+
+// Junta los hallazgos de un chequeo que dicen lo mismo en distintos archivos, o que comparten
+// `data.group` (un encabezado común; cada uno se lista con su `data.pin`).
+function group(findings) {
+  const groups = new Map();
+  for (const f of findings) {
+    const headline = f.data?.group ?? f.message;
+    const key = `${f.level}\u0000${headline}`;
+    if (!groups.has(key)) groups.set(key, { level: f.level, message: headline, items: [] });
+    groups.get(key).items.push(f);
+  }
+  return [...groups.values()];
+}
+
+// Un bloque por chequeo, con el título y una línea por hallazgo.
+export function formatBlocks(checks, results, { color = false, indent = '' } = {}) {
+  const paint = painter(color);
+  const lines = [];
+  for (const check of checks) {
+    const own = results.filter((r) => r.check === check.id);
+    lines.push(`${indent}${paint(COLOR.bold, check.title)}`);
+    // Los `info` con `data.ok` solo van en --json: en texto, el chequeo sin observaciones.
+    const visible = own.filter((r) => !(r.level === 'info' && r.data?.ok));
+    if (!visible.length) {
+      lines.push(`${indent}  ${paint(COLOR.ok, ICON.ok)} sin observaciones`);
+      continue;
+    }
+    for (const g of group(visible)) {
+      const icon = paint(COLOR[g.level], ICON[g.level]);
+      if (g.items.length === 1) {
+        const [item] = g.items;
+        // Con `data.group`, el mensaje propio ya nombra lo que dice el pin.
+        const where = item.data?.group ? location(item) : withPin(item);
+        lines.push(`${indent}  ${icon} ${where ? `${paint(COLOR.dim, where)}  ` : ''}${item.message}`);
+      } else {
+        lines.push(`${indent}  ${icon} ${g.message}`);
+        for (const item of g.items) {
+          const where = withPin(item);
+          if (where) lines.push(`${indent}      ${paint(COLOR.dim, where)}`);
+        }
+      }
+    }
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+export function formatText({ kitVersion, dir, checks, results, summary }, { color = false } = {}) {
+  const paint = painter(color);
+  const total = `${summary.errors} error(es), ${summary.warnings} aviso(s)`;
+  const colored = summary.errors ? paint(COLOR.error, total) : summary.warnings ? paint(COLOR.warn, total) : paint(COLOR.ok, total);
+  return `${paint(COLOR.dim, `npm-security-kit ${kitVersion} · ${dir}`)}\n\n${formatBlocks(checks, results, { color })}\n${colored}\n`;
+}
+
+export function formatJson({ kitVersion, policy, results, summary }) {
+  return `${JSON.stringify({ kitVersion, policy, results, summary }, null, 2)}\n`;
+}

package/src/run.js

@@ -0,0 +1,35 @@
+// Corre los chequeos en paralelo y junta los hallazgos en el orden de la lista. Si un chequeo
+// lanza una excepción, queda como un error de ese chequeo y los demás siguen.
+
+const LEVELS = new Set(['error', 'warn', 'info']);
+
+function normalize(check, finding) {
+  const level = LEVELS.has(finding.level) ? finding.level : 'error';
+  const out = { check: check.id, level, message: String(finding.message) };
+  if (finding.file) out.file = finding.file;
+  if (finding.line) out.line = finding.line;
+  if (finding.data !== undefined) out.data = finding.data;
+  return out;
+}
+
+export function summarize(results) {
+  return {
+    errors: results.filter((r) => r.level === 'error').length,
+    warnings: results.filter((r) => r.level === 'warn').length,
+  };
+}
+
+export async function runChecks(checks, ctx) {
+  const perCheck = await Promise.all(
+    checks.map(async (check) => {
+      try {
+        const findings = (await check.run(ctx)) ?? [];
+        return findings.map((f) => normalize(check, f));
+      } catch (error) {
+        return [normalize(check, { level: 'error', message: `falló el chequeo ${check.id}: ${error.message}` })];
+      }
+    }),
+  );
+  const results = perCheck.flat();
+  return { results, summary: summarize(results) };
+}

package/src/version.js

@@ -0,0 +1,3 @@
+import { readFileSync } from 'node:fs';
+
+export const kitVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;