@theoptimalpartner/npm-security-kit 2.0.0-beta.4 → 2.0.0-beta.5

package/CHANGELOG.md

@@ -38,6 +38,17 @@ Sale primero como beta (`2.0.0-beta.N`), con el dist-tag `beta`.
     da EBADENGINE con el `engines.node` de `init`). Los pasos siguientes de `init` incluyen el cambio de línea, el
     lockfile y el `prepare` del proyecto; la sección del pipeline menciona `custom: ci`.
   - `check` sin `package.json` termina con exit 2 ("no es un proyecto npm"), como `init`.
+- **2.0.0-beta.5** (ajustes de una tercera prueba):
+  - `init` guía el cambio de línea también desde una línea sin soporte o no LTS (antes solo desde una sin npm 11), y
+    sube `engines.node` si admite una línea que hay que cambiar.
+  - `init` señala el `npm ci` del step que corre en los PR (inline o por su ancla) y aparte los de deploy y
+    publicación, que no necesitan el kit. No repite la imagen si el pipeline ya usa la que propone.
+  - `dockerfile`: en un monorepo, un Dockerfile cuyo contexto de build es una subcarpeta sin `.npmrc` instala sin la
+    política aunque la raíz lo tenga; ahora es error.
+  - Excepción con fecha para diferir el cambio de línea de Node cuando el salto es de más de 2 versiones mayores
+    (`npmSecurityKit.nodeUpgradeDeferredUntil` y `nodeUpgradeReason` en el `package.json`, hasta 183 días): mientras
+    está vigente, los errores de la línea de Node y de npm 10 son avisos e `init` no toca `engines`. El kit la sugiere
+    cuando el salto es grande.
 
 ### BREAKING
 

package/README.md

@@ -3,7 +3,7 @@
 Reglas de seguridad de dependencias npm en un solo comando que corre en el pipeline **antes de `npm ci`**. No tiene
 dependencias: `npx` descarga un solo tarball y revisa el lockfile antes de que se ejecute un solo install script.
 
-Los ejemplos usan la versión de este paquete (`2.0.0-beta.4`). Las publicadas, con sus dist-tags:
+Los ejemplos usan la versión de este paquete (`2.0.0-beta.5`). Las publicadas, con sus dist-tags:
 `npm view @theoptimalpartner/npm-security-kit dist-tags`.
 
 ## Qué revisa
@@ -12,7 +12,7 @@ Los ejemplos usan la versión de este paquete (`2.0.0-beta.4`). Las publicadas,
 |---|---|---|---|
 | `malware` | `npm audit` sobre **todo** el lockfile, incluidas las devDependencies | Cualquier advisory de malware (CWE-506), con cualquier severidad | — |
 | `vulnerabilities` | `npm audit --omit=dev` y, para las de desarrollo, el de todo el árbol | Vulnerabilidades `critical` en producción | Resumen de las `high` en producción; `critical` solo en devDependencies |
-| `node-version` | `.nvmrc`, `.node-version`, `.tool-versions`, `engines.node`, `volta.node`, `FROM node:` y `image:` del pipeline | Línea de Node sin soporte, que no es LTS o que no trae npm >= 11.17 en ninguna release (Node 22 trae npm 10) | Hay una LTS más nueva (mientras no tenga su primera release LTS, solo se informa), pocos días de soporte, parche de seguridad pendiente, versiones mayores distintas, nada fijado |
+| `node-version` | `.nvmrc`, `.node-version`, `.tool-versions`, `engines.node`, `volta.node`, `FROM node:` y `image:` del pipeline | Línea de Node sin soporte, que no es LTS o que no trae npm >= 11.17 en ninguna release (Node 22 trae npm 10); con un salto de más de 2 versiones, diferible con una excepción con fecha | Hay una LTS más nueva (mientras no tenga su primera release LTS, solo se informa), pocos días de soporte, parche de seguridad pendiente, versiones mayores distintas, nada fijado |
 | `npm-policy` | `.npmrc`, `engines.npm`, npm en uso, lockfile | Faltan `min-release-age`, `engine-strict` o `strict-allow-scripts`; npm < 11.17; no hay lockfile | Faltan `min-release-age-exclude[]`, `save-exact` o `audit-level`; lockfile < v3 |
 | `install-scripts` | Paquetes con install scripts del lockfile contra `allowScripts` | Alguno sin aprobar (con `strict-allow-scripts`) | Alguno sin aprobar con el override por variable de entorno |
 | `dockerfile` | `COPY` del `.npmrc` antes de `npm ci`, `.dockerignore` | Instala sin el `.npmrc` | Usa `npm install` en vez de `npm ci`; el `.dockerignore` deja fuera el lockfile |
@@ -48,7 +48,8 @@ subir a una LTS que traiga npm 11. `check` da error en cada lugar que fija la 22
 `image:`) e `init` propone la línea nueva. Cuando hay que cambiar de línea (sin soporte, no LTS o sin npm 11), el
 destino es uno solo: la LTS con soporte más baja que trae npm 11 (hoy la 24), en la release más nueva que **ya tiene
 imagen oficial en Docker Hub** (las imágenes salen días después que la release en nodejs.org). En local, cambiar de
-línea con `nvm install 24 && nvm use 24`: npm 11 sobre la 22 no alcanza, porque `engines.node` pide la 24.
+línea con `nvm install 24 && nvm use 24`: npm 11 sobre la 22 no alcanza, porque `engines.node` pide la 24. Si el salto
+es grande (18 o 20 → 24), ver **Diferir el cambio de Node** en las recetas.
 
 ## Uso
 
@@ -68,7 +69,7 @@ definitions:
           - npm
         script:
           # Antes de instalar: malware, vulnerabilidades, Node, .npmrc, install scripts, Dockerfiles
-          - npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0-beta.4 check
+          - npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0-beta.5 check
           - npm ci            # con strict-allow-scripts, los scripts no aprobados cortan acá
           - npm audit signatures
           # … y lo que ya corría el step: build, lint, tests
@@ -88,13 +89,13 @@ pipelines:
 
 - **Antes de `npm ci`:** `npm audit` funciona solo con el lockfile, así que el malware se detecta antes de que
   corra su `postinstall`.
-- **Versión fija** (`@2.0.0-beta.4`): subir la política en un repo es un cambio visible en su PR.
+- **Versión fija** (`@2.0.0-beta.5`): subir la política en un repo es un cambio visible en su PR.
 - **`--min-release-age=0` solo para `npx`:** `npx` no aplica `min-release-age-exclude` (npm 11.19.1 lo aplica al
   instalar, no al resolver el paquete de `npx`). Sin el flag, dentro de un repo con `min-release-age=7` una versión
   nueva del kit no se puede usar hasta cumplir 7 días (`ETARGET … with a date before`). Afecta solo al kit: la
   versión va fija y no tiene dependencias. El `npm ci` que sigue aplica los 7 días como siempre.
 - **`npm audit signatures`** va después de `npm ci` porque necesita `node_modules`.
-- Para guardar el resultado como artefacto: `npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0-beta.4 check --json > npm-security-kit.json`.
+- Para guardar el resultado como artefacto: `npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0-beta.5 check --json > npm-security-kit.json`.
 
 ### Dockerfile
 
@@ -109,24 +110,28 @@ RUN npm ci
 
 Si el `.dockerignore` excluye el `.npmrc` (por ejemplo con `.*`), agregar `!.npmrc` al final.
 
+En un monorepo, si el Dockerfile se construye con una subcarpeta como contexto (`cd backend && docker build .`), el
+`.npmrc` de la raíz no llega a la imagen: copiarlo a esa carpeta o construir con el contexto en la raíz. `check` lo
+marca como error.
+
 ### Adoptarlo en un repo: `init`
 
 Una vez por repo, en una rama:
 
 ```bash
-npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0-beta.4 init --dry-run
+npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0-beta.5 init --dry-run
 ```
 
 ```bash
-npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0-beta.4 init
+npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0-beta.5 init
 ```
 
 `init`:
 
 - agrega al `.npmrc` las claves de la política que faltan (con un comentario) y corrige las que tienen otro valor,
   sin borrar ni reordenar nada;
-- completa `engines.npm` (`>=11.17`) y, solo si falta, `engines.node` (con la línea de Node del repo, si trae npm 11;
-  si no, la siguiente que lo trae);
+- completa `engines.npm` (`>=11.17`) y `engines.node`: lo agrega si falta, con la línea de Node del repo si trae npm
+  11, y lo sube si admite una línea que hay que cambiar (sin soporte, no LTS o sin npm 11), a la línea propuesta;
 - **no aprueba install scripts**: lista los pendientes y los comandos para revisarlos;
 - **no edita** `bitbucket-pipelines.yml` ni los Dockerfiles: dice qué líneas agregar al step que corre `npm ci`, la
   condition con las ramas que despliegan y los `COPY` corregidos;
@@ -137,7 +142,7 @@ Después: revisar el diff, aprobar o negar los install scripts, aplicar el step
 ### En local
 
 ```bash
-npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0-beta.4 check
+npx --yes --min-release-age=0 @theoptimalpartner/npm-security-kit@2.0.0-beta.5 check
 ```
 
 No se instala como devDependency ni usa husky: el `.npmrc` protege el `npm install` local y el pipeline es el
@@ -221,6 +226,51 @@ Si un repo no puede adoptar todavía la aprobación de install scripts, se defin
 Con el override, npm ejecuta los scripts sin aprobar y el kit los informa como **aviso**, más un aviso de que el
 override está activo. Dentro del `docker build` la variable no llega sola: hay que pasarla como `ARG`.
 
+### Diferir el cambio de Node (salto grande)
+
+Pasar de Node 18 o 20 a la 24 suele arrastrar dependencias y refactors. Para no frenar el repo mientras se planifica,
+el cambio de línea se puede diferir con una excepción con fecha.
+
+**Cuándo se puede usar**
+
+- Solo si el salto de la línea del repo al destino (hoy la 24) es de **más de 2 versiones mayores**: 18 → 24 o
+  20 → 24 sí; 22 → 24 no (ese cambio es chico y no se difiere). `check` lo sugiere ("Salto grande (Node 18 → 24)…")
+  cuando aplica.
+- Cuando subir ahora no es viable (dependencias que no soportan la línea nueva, un refactor que hay que planificar), y
+  con el OK de quien aprueba los cambios de seguridad del repo. No es para "lo veo después".
+
+**Cómo**
+
+En la raíz del `package.json` (al lado de `dependencies`), en un PR:
+
+```json
+"npmSecurityKit": {
+  "nodeUpgradeDeferredUntil": "2027-03-31",
+  "nodeUpgradeReason": "Express 4 → 5 y los tipos de Node 24"
+}
+```
+
+- `nodeUpgradeDeferredUntil`: fecha `AAAA-MM-DD`, como mucho 183 días desde hoy.
+- `nodeUpgradeReason`: por qué no se puede subir ahora. Es obligatorio.
+- En la descripción del PR: el motivo, quién lo aprobó y el plan para subir antes de la fecha (tarjeta o PR).
+
+**Qué cambia mientras está vigente**
+
+- Los errores de la línea de Node y los de npm 10 (`npm` en uso, `engines.npm`) pasan a aviso, con la fecha y el motivo;
+  `check` dice cuántos días quedan. `init` no toca `engines`: los de la línea nueva, con `engine-strict`, romperían el
+  `npm ci` de la actual.
+- Lo demás sigue bloqueando: malware, vulnerabilidades críticas en producción, install scripts sin aprobar, `.npmrc`
+  y Dockerfiles.
+- **Ojo:** con npm 10 (la 18 no corre npm 11), `min-release-age` y `allowScripts` no hacen nada aunque estén en el
+  `.npmrc`. El repo queda sin la espera de 7 días ni el control de install scripts: el kit sigue revisando malware y
+  vulnerabilidades antes de `npm ci`, pero no reemplaza eso. Por eso la excepción vence.
+
+**Al vencer**
+
+- Los errores vuelven a bloquear el pipeline y `check` pide quitarla o renovarla.
+- Renovarla es otro PR con fecha nueva (como mucho 183 días desde ese día), motivo y OK. Si la fecha es inválida,
+  falta el motivo o pasa de 183 días, el kit la ignora y lo avisa.
+
 ### Vulnerabilidades `critical` en devDependencies
 
 No bloquean (no llegan a producción), pero corren en el pipeline y en las máquinas de los devs: `check` las informa

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoptimalpartner/npm-security-kit",
-  "version": "2.0.0-beta.4",
+  "version": "2.0.0-beta.5",
   "description": "Revisa el lockfile antes de npm ci: malware, vulnerabilidades, versión de Node, .npmrc, install scripts y Dockerfiles",
   "type": "module",
   "bin": {

package/src/checks/dockerfile.js

@@ -138,6 +138,10 @@ export async function run(ctx) {
     const own = dirOf(file);
     const context = own && (ctx.exists(join(own, '.dockerignore')) || ctx.exists(join(own, 'package.json'))) ? own : '';
     const hasNpmrc = ctx.exists(join(context, '.npmrc'));
+    // Monorepo: el contexto es una subcarpeta sin .npmrc y la política está en el de la raíz, que
+    // `docker build` no ve desde ahí.
+    const npmrcOutside = Boolean(context) && !hasNpmrc && ctx.exists('.npmrc');
+    let reportedOutside = false;
     const ignoreFile = ctx.exists(`${file}.dockerignore`) ? `${file}.dockerignore` : join(context, '.dockerignore');
     const ignoreText = ctx.readFile(ignoreFile);
     const npmrcIgnored = hasNpmrc ? dockerignoreExcludes(ignoreText, '.npmrc') : null;
@@ -171,6 +175,15 @@ export async function run(ctx) {
         const local = npmInstalls(ins.args).filter((n) => !n.global);
         if (!local.length) continue;
         installs = true;
+        if (npmrcOutside && !mountsNpmrc(ins.args) && !reportedOutside) {
+          reportedOutside = true;
+          findings.push({
+            level: 'error',
+            file,
+            line: ins.line,
+            message: `Instala sin el .npmrc: el contexto de build es ${context}/ (tiene su propio package.json o .dockerignore) y ahí no hay .npmrc; el de la raíz no llega a la imagen. Copiar el .npmrc a ${context}/ y agregarlo al COPY, o construir con el contexto en la raíz.`,
+          });
+        }
         if (hasNpmrc && !brought && !mountsNpmrc(ins.args) && !reported) {
           reported = true;
           findings.push({

package/src/checks/node-version.js

@@ -5,6 +5,7 @@
 import { findDockerfiles, nodeImageTag, parseStages } from '../lib/dockerfile.js';
 import { jsonKeyLine } from '../lib/json-lines.js';
 import { loadCalendar } from '../lib/node-calendar.js';
+import { readDeferral } from '../lib/node-deferral.js';
 import { imageExists, newestWithImage, upgradeTarget } from '../lib/node-target.js';
 import { compareVersions, isRange, minVersion, parseVersion } from '../lib/semver.js';
 
@@ -166,11 +167,11 @@ async function evaluate(ctx, pin, r, cal, { target, newestLtsWithoutImage }) {
 
   const phase = cal.phaseOf(r.major);
   if (phase === 'eol') {
-    return { ...base, level: 'error', message: `${prefix}: sin soporte desde ${sch.end}. Actualizar a ${rec}${engineHint}.`, data };
+    return { ...base, level: 'error', message: `${prefix}: sin soporte desde ${sch.end}. Actualizar a ${rec}${engineHint}.`, data: { ...data, lineChange: true } };
   }
   if (phase === 'not-lts') {
     const why = sch.lts ? `todavía no es LTS (lo será el ${sch.lts})` : 'línea impar, nunca va a ser LTS';
-    return { ...base, level: 'error', message: `${prefix}: no es LTS, ${why}. Usar ${rec}${engineHint}.`, data };
+    return { ...base, level: 'error', message: `${prefix}: no es LTS, ${why}. Usar ${rec}${engineHint}.`, data: { ...data, lineChange: true } };
   }
   // La política pide npm >= minNpmVersion y la imagen de Node trae el suyo: una línea que no lo trae en
   // ninguna release (la 22 trae npm 10) deja el pipeline y el docker build con npm 10.
@@ -181,7 +182,7 @@ async function evaluate(ctx, pin, r, cal, { target, newestLtsWithoutImage }) {
       ...base,
       level: 'error',
       message: `${prefix}: trae npm ${lineNpm}, y ninguna release de la ${r.major} trae npm >= ${policy.minNpmVersion}, que pide la política. Subir a una LTS con npm 11: ${to} o más nueva${engineHint}.`,
-      data: { ...data, npm: lineNpm },
+      data: { ...data, npm: lineNpm, lineChange: true },
     };
   }
 
@@ -223,6 +224,40 @@ async function evaluate(ctx, pin, r, cal, { target, newestLtsWithoutImage }) {
   return { ...base, level, message: `${prefix}: ${detail}`, data: { ...data, group: `v${r.major}: ${detail}` } };
 }
 
+// ¿Hay una excepción vigente que aplique a este repo? Aplica si alguna línea fijada que hay que cambiar
+// (sin soporte, no LTS o sin npm 11) está a más de policy.nodeDeferMinJump versiones mayores del destino.
+// La usan npm-policy (npm 10 y engines.npm) e init. Una vez por corrida.
+const deferrals = new WeakMap();
+export function activeDeferral(ctx) {
+  if (!deferrals.has(ctx)) deferrals.set(ctx, computeDeferral(ctx).catch(() => null));
+  return deferrals.get(ctx);
+}
+
+async function computeDeferral(ctx) {
+  const deferral = readDeferral(ctx);
+  if (deferral.status !== 'active') return null;
+  const cal = await loadCalendar(ctx);
+  const target = await upgradeTarget(ctx, cal);
+  if (!target) return null;
+  const majors = bigJumpLines(ctx, cal, target);
+  return majors.length ? { ...deferral, majors, target } : null;
+}
+
+// Las líneas fijadas que hay que cambiar y están a más de nodeDeferMinJump versiones del destino.
+function bigJumpLines(ctx, cal, target) {
+  const out = new Set();
+  for (const pin of findPins(ctx)) {
+    const r = resolvePin(pin, cal);
+    if (r.major === undefined || r.major === null || r.otherImage) continue;
+    if (target.major - r.major <= ctx.policy.nodeDeferMinJump) continue;
+    const phase = cal.phaseOf(r.major);
+    const npm = cal.npmOfLine(r.major);
+    const noNpm = npm && parseVersion(npm) && compareVersions(npm, ctx.policy.minNpmVersion) < 0;
+    if (phase === 'eol' || phase === 'not-lts' || noNpm) out.add(r.major);
+  }
+  return [...out].sort((a, b) => a - b);
+}
+
 export async function run(ctx) {
   let cal;
   try {
@@ -239,12 +274,59 @@ export async function run(ctx) {
   const pins = findPins(ctx);
   const findings = [];
   const majors = new Set();
+  const deferral = readDeferral(ctx);
+  const max = ctx.policy.nodeDeferMaxDays;
+  const big = target ? new Set(bigJumpLines(ctx, cal, target)) : new Set();
+  const deferring = deferral.status === 'active' && big.size > 0;
   let nodePins = 0;
   for (const pin of pins) {
     const r = resolvePin(pin, cal);
     if (!r.otherImage) nodePins++;
     if (r.major !== undefined && r.major !== null) majors.add(r.major);
-    findings.push(await evaluate(ctx, pin, r, cal, { target, newestLtsWithoutImage }));
+    const finding = await evaluate(ctx, pin, r, cal, { target, newestLtsWithoutImage });
+    // Con la excepción vigente, el cambio de una línea con salto grande pasa a aviso.
+    if (deferring && finding.level === 'error' && finding.data?.lineChange && big.has(r.major)) {
+      findings.push({
+        ...finding,
+        level: 'warn',
+        message: `${finding.message} Diferido hasta ${deferral.until} (${deferral.reason}).`,
+        data: { ...finding.data, deferredUntil: deferral.until },
+      });
+    } else {
+      findings.push(finding);
+    }
+  }
+  // El estado de la excepción, o la sugerencia de declararla cuando el salto es grande.
+  const deferralAt = { file: 'package.json', line: deferral.line };
+  const lines = [...big].map((m) => `Node ${m}`).join(' y ');
+  if (deferral.status === 'invalid') {
+    findings.push({ ...deferralAt, level: 'warn', message: `La excepción para diferir el cambio de Node no vale: ${deferral.problem}. Se ignora.` });
+  } else if (deferral.status === 'expired') {
+    findings.push({
+      ...deferralAt,
+      level: 'warn',
+      message: `La excepción para diferir el cambio de Node venció el ${deferral.until}: los errores vuelven a bloquear. Quitarla del package.json, o renovarla con otra fecha y motivo (máximo ${max} días).`,
+    });
+  } else if (deferral.status === 'active' && !deferring) {
+    findings.push({
+      ...deferralAt,
+      level: 'warn',
+      message: `La excepción para diferir el cambio de Node no hace falta: ninguna línea fijada está a más de ${ctx.policy.nodeDeferMinJump} versiones mayores del destino. Quitarla del package.json.`,
+    });
+  } else if (deferring) {
+    findings.push({
+      ...deferralAt,
+      level: 'warn',
+      message: `Cambio de línea de Node diferido hasta ${deferral.until} (${deferral.reason}): quedan ${deferral.daysLeft} días. Mientras tanto, los errores de ${lines} y de npm 10 son avisos; al vencer, vuelven a bloquear. Destino: ${target.version}.`,
+      data: { deferredUntil: deferral.until, majors: [...big] },
+    });
+  } else if (big.size && findings.some((f) => f.level === 'error' && f.data?.lineChange && big.has(f.data.major))) {
+    findings.push({
+      level: 'info',
+      message:
+        `Salto grande (${lines} → ${target.major}): si no se puede subir ahora, se puede diferir con una excepción con fecha en el package.json, ` +
+        `"npmSecurityKit": { "nodeUpgradeDeferredUntil": "AAAA-MM-DD", "nodeUpgradeReason": "…" } (máximo ${max} días). Mientras esté vigente, estos errores son avisos.`,
+    });
   }
   if (!nodePins) {
     const version = target?.version ?? cal.recommended;

package/src/checks/npm-policy.js

@@ -5,6 +5,7 @@ import { parseNpmrc, requiredSettings, settingProblem } from '../lib/npmrc.js';
 import { jsonKeyLine } from '../lib/json-lines.js';
 import { linesWithNpm, loadCalendar } from '../lib/node-calendar.js';
 import { upgradeTarget } from '../lib/node-target.js';
+import { activeDeferral } from './node-version.js';
 import { compareVersions, minVersion, parseVersion } from '../lib/semver.js';
 
 export const id = 'npm-policy';
@@ -85,6 +86,12 @@ export async function run(ctx) {
 
   // engines.npm
   const pkgText = ctx.readFile('package.json');
+  // Con el cambio de Node diferido (salto grande), la línea del repo puede no correr npm 11: engines.npm
+  // y el npm en uso son avisos hasta que venza la excepción. engines.npm >=11.17 con engine-strict
+  // rompería el npm ci de esa línea.
+  const deferral = await activeDeferral(ctx);
+  const deferredNote = deferral ? ` Diferido hasta ${deferral.until} junto con el cambio de Node (${deferral.reason}).` : '';
+  const npmLevel = deferral ? 'warn' : 'error';
   if (pkgText === null) {
     findings.push({ level: 'error', message: 'No hay package.json en el directorio revisado.' });
   } else {
@@ -93,16 +100,16 @@ export async function run(ctx) {
     const min = typeof range === 'string' ? minVersion(range) : null;
     if (typeof range !== 'string') {
       findings.push({
-        level: 'error',
+        level: npmLevel,
         file: 'package.json',
-        message: `Falta engines.npm: agregar "npm": ">=${minNpmShort}" en engines (${NPM10_WHY}).`,
+        message: `Falta engines.npm: agregar "npm": ">=${minNpmShort}" en engines (${NPM10_WHY}).${deferral ? ` Agregarlo al subir de Node: con engine-strict, en la línea actual rompe npm ci.${deferredNote}` : ''}`,
       });
     } else if (!min || compareVersions(min, minNpm) < 0) {
       findings.push({
-        level: 'error',
+        level: npmLevel,
         file: 'package.json',
         line: jsonKeyLine(pkgText, ['engines', 'npm']),
-        message: `engines.npm "${range}" admite npm anteriores a ${minNpm} (${NPM10_WHY}). Cambiar a ">=${minNpmShort}".`,
+        message: `engines.npm "${range}" admite npm anteriores a ${minNpm} (${NPM10_WHY}). Cambiar a ">=${minNpmShort}".${deferredNote}`,
         data: { range, min },
       });
     }
@@ -115,8 +122,8 @@ export async function run(ctx) {
     findings.push({ level: 'warn', message: `No se pudo saber la versión de npm en uso (${(npmVersion.stderr || npmVersion.stdout).trim() || 'sin salida'}).` });
   } else if (compareVersions(used, minNpm) < 0) {
     findings.push({
-      level: 'error',
-      message: (({ pipeline, local }) => `npm ${used} en uso: hace falta npm >= ${minNpm} (${NPM10_WHY}). En el pipeline y en el Dockerfile, ${pipeline}. En local, ${local}.`)(
+      level: npmLevel,
+      message: (({ pipeline, local }) => `npm ${used} en uso: hace falta npm >= ${minNpm} (${NPM10_WHY}). En el pipeline y en el Dockerfile, ${pipeline}. En local, ${local}.${deferredNote}`)(
         await npmHint(ctx, minNpm),
       ),
       data: { npm: used },

package/src/init.js

@@ -6,6 +6,7 @@ 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 { activeDeferral } 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';
@@ -55,9 +56,10 @@ function jsonFormat(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) {
+// engines.npm (si falta o admite un npm viejo) y engines.node (si falta, o con `raiseNode` si admite
+// una línea que hay que cambiar: sin soporte, no LTS o sin npm 11), conservando la indentación y el
+// salto de línea final del archivo.
+export function mergePackageJson(text, policy, nodeMajor, { raiseNode = false } = {}) {
   const pkg = JSON.parse(text);
   const changes = [];
   const minNpm = policy.minNpmVersion.replace(/\.0$/, '');
@@ -67,9 +69,10 @@ export function mergePackageJson(text, policy, nodeMajor) {
     changes.push(`engines.npm: ">=${minNpm}"${engines.npm ? ` (antes: "${engines.npm}")` : ''}`);
     engines.npm = `>=${minNpm}`;
   }
-  if (engines.node === undefined && nodeMajor) {
+  if (nodeMajor && (engines.node === undefined || raiseNode)) {
+    const before = engines.node;
     engines.node = `>=${nodeMajor}`;
-    changes.push(`engines.node: ">=${nodeMajor}"`);
+    changes.push(`engines.node: ">=${nodeMajor}"${before ? ` (antes: "${before}")` : ''}`);
   }
   if (!changes.length) return { text, changes };
   pkg.engines = engines;
@@ -88,18 +91,22 @@ export function mergePackageJson(text, policy, nodeMajor) {
 // soporte), el destino único de lib/node-target.js.
 export async function repoNode(ctx, cal) {
   const target = await upgradeTarget(ctx, cal);
-  let inUse = null;
+  const { ok } = linesWithNpm(cal, ctx.policy.minNpmVersion);
+  let inUse = null; // la línea más baja en uso que cumple (LTS con soporte y npm 11)
+  let from = null; // la línea más baja en uso que hay que cambiar, y por qué
   let pipelinePin = null;
   for (const pin of nodeVersionCheck.findPins(ctx)) {
     const r = nodeVersionCheck.resolvePin(pin, cal);
     if (r.major === undefined || r.major === null || r.latest) continue;
-    if (!['active', 'maintenance'].includes(cal.phaseOf(r.major))) continue;
-    if (inUse === null || r.major < inUse) inUse = r.major;
-    if (!pipelinePin && pin.file === 'bitbucket-pipelines.yml' && pin.kind === 'docker' && r.exact) pipelinePin = r;
+    if (ok.includes(r.major)) {
+      if (inUse === null || r.major < inUse) inUse = r.major;
+      if (!pipelinePin && pin.file === 'bitbucket-pipelines.yml' && pin.kind === 'docker' && r.exact) pipelinePin = r;
+    } else if (from === null || r.major < from.major) {
+      from = { major: r.major, why: lineProblem(cal, r.major, ctx.policy) };
+    }
   }
-  if (!target) return { major: null, image: null, npm: null, from: null };
-  const major = inUse === null ? target.major : (linesWithNpm(cal, ctx.policy.minNpmVersion).ok.find((m) => m >= inUse) ?? target.major);
-  const from = inUse !== null && major !== inUse ? inUse : null;
+  if (!target) return { major: null, image: null, npm: null, from };
+  const major = inUse ?? target.major;
   if (pipelinePin?.major === major) {
     let patched = false;
     for (const s of cal.securityAfter(major, pipelinePin.exact)) {
@@ -112,6 +119,43 @@ export async function repoNode(ctx, cal) {
   return { major, image: found?.image ?? String(major), npm: found?.npm ?? cal.npmOfLine(major), from };
 }
 
+// Por qué una línea de Node no sirve, para el mensaje de init.
+function lineProblem(cal, major, policy) {
+  const phase = cal.phaseOf(major);
+  if (phase === 'eol') return `sin soporte desde ${cal.lines.get(major).end}`;
+  if (phase === 'not-lts') return 'que no es LTS';
+  if (phase === 'unknown') return 'que no aparece en el calendario de Node';
+  return `pero ninguna release de la ${major} trae npm >= ${policy.minNpmVersion}, que pide la política`;
+}
+
+// Las líneas `- npm ci` del pipeline: las del step que corre en los PR (inline o por ancla) y el resto
+// (deploys, publicación). El kit va en el de los PR. Sin sección pull-requests, todas cuentan como PR.
+export function npmCiLines(text) {
+  const lines = (text ?? '').split(/\r?\n/);
+  const indent = (l) => l.match(/^ */)[0].length;
+  const isCi = (l) => /^\s*-\s*npm ci(\s|$)/.test(l);
+  const all = lines.flatMap((l, i) => (isCi(l) ? [i + 1] : []));
+  const blockAfter = (start) => {
+    const out = [];
+    for (let i = start + 1; i < lines.length; i++) {
+      if (!lines[i].trim() || lines[i].trim().startsWith('#')) continue;
+      if (indent(lines[i]) <= indent(lines[start])) break;
+      out.push(i);
+    }
+    return out;
+  };
+  const prStart = lines.findIndex((l) => /^\s+pull-requests:\s*(#.*)?$/.test(l));
+  if (prStart < 0) return { pr: all, others: [] };
+  const prBlock = blockAfter(prStart);
+  const pr = new Set(prBlock.filter((i) => isCi(lines[i])).map((i) => i + 1));
+  for (const anchor of new Set(prBlock.flatMap((i) => [...lines[i].matchAll(/\*([\w-]+)/g)].map((m) => m[1])))) {
+    const def = lines.findIndex((l) => new RegExp(`&${anchor}(\\s|$)`).test(l));
+    if (def >= 0) for (const i of blockAfter(def)) if (isCi(lines[i])) pr.add(i + 1);
+  }
+  if (!pr.size) return { pr: all, others: [] };
+  return { pr: [...pr].sort((a, b) => a - b), others: all.filter((n) => !pr.has(n)) };
+}
+
 // Las ramas que despliegan: las claves de `pipelines.branches` (sin globs), en orden.
 export function deployBranches(text) {
   const out = [];
@@ -227,7 +271,13 @@ export async function runInit(ctx, { dryRun = false, stdout = process.stdout, co
   // 1. .npmrc y package.json
   const npmrcBefore = ctx.readFile('.npmrc');
   const npmrc = mergeNpmrc(npmrcBefore, ctx.policy);
-  const pkg = mergePackageJson(pkgText, ctx.policy, node.major);
+  // Con el cambio de Node diferido (salto grande, excepción vigente), engines no se toca: los de la línea
+  // nueva, con engine-strict, romperían el npm ci de la actual.
+  const deferral = cal.error ? null : await activeDeferral(ctx);
+  const engNode = JSON.parse(pkgText).engines?.node;
+  const engMin = typeof engNode === 'string' ? minVersion(engNode) : null;
+  const raiseNode = Boolean(engMin && !cal.error && node.major && !linesWithNpm(cal, ctx.policy.minNpmVersion).ok.includes(parseVersion(engMin)[0]));
+  const pkg = deferral ? { text: pkgText, changes: [] } : mergePackageJson(pkgText, ctx.policy, node.major, { raiseNode });
   if (npmrc.changes.length) files['.npmrc'] = npmrc.text;
   if (pkg.changes.length) files['package.json'] = pkg.text;
 
@@ -277,23 +327,35 @@ export async function runInit(ctx, { dryRun = false, stdout = process.stdout, co
   const pipeline = ctx.readFile('bitbucket-pipelines.yml');
   const used = pipeline?.match(/npm-security-kit@([\w.-]+)/);
   const image = node.image ?? '<versión LTS>';
-  if (node.from !== null && node.from !== undefined) {
+  const bigJump = node.from && node.major - node.from.major > ctx.policy.nodeDeferMinJump;
+  if (deferral) {
+    say(
+      `  Cambio de Node diferido hasta ${deferral.until} (${deferral.reason}): el step sigue con la imagen actual y engines no se toca. ` +
+        `Al vencer, pasar a la ${node.major} (node:${image}).`,
+    );
+  } else if (node.from) {
     say(
-      `  El repo usa Node ${node.from}, pero ninguna release de la ${node.from} trae npm >= ${ctx.policy.minNpmVersion}, que pide la política: ` +
-        `se propone la ${node.major} (node:${image}${node.npm ? `, npm ${node.npm}` : ''}). Pasar a la ${node.major} el .nvmrc, las imágenes del pipeline y los FROM de los Dockerfiles.`,
+      `  El repo usa Node ${node.from.major}, ${node.from.why}: ` +
+        `se propone la ${node.major} (node:${image}${node.npm ? `, npm ${node.npm}` : ''}). Pasar a la ${node.major} el .nvmrc, las imágenes del pipeline, los FROM de los Dockerfiles y engines.node.` +
+        (bigJump ? ' Si el salto no se puede hacer ahora, se puede diferir con una excepción con fecha (README: "Diferir el cambio de Node").' : ''),
     );
   }
   const branches = deployBranches(pipeline);
-  const ciLines = (pipeline ?? '').split(/\r?\n/).flatMap((l, i) => (/^\s*-\s*npm ci(\s|$)/.test(l) ? [i + 1] : []));
+  const ci = npmCiLines(pipeline);
   if (used) {
     say(`  Ya corre el kit (${used[0]}).${used[1] !== ctx.kitVersion ? ` Para esta versión: ${PACKAGE}@${ctx.kitVersion}.` : ''}`);
-  } else if (ciLines.length) {
-    say(`  Agregar al step que ya corre npm ci (bitbucket-pipelines.yml:${ciLines.join(', ')}), sin reemplazar el resto del step:`);
+  } else if (ci.pr.length) {
+    say(`  Agregar al step que corre en los PR (bitbucket-pipelines.yml:${ci.pr.join(', ')}), antes de su npm ci, sin reemplazar el resto del step:`);
     say();
     say(`    - npx --yes --min-release-age=0 ${PACKAGE}@${ctx.kitVersion} check   # antes de npm ci`);
     say('    - npm audit signatures   # después de npm ci');
     say();
-    say(`  Con una imagen que traiga npm >= ${ctx.policy.minNpmVersion} (image: node:${image}).`);
+    if (ci.others.length) {
+      say(`  Los otros npm ci (líneas ${ci.others.join(', ')}: deploys, publicación) no necesitan el kit: ya pasó en el PR.`);
+    }
+    if (!deferral && !new RegExp(`node:${image.replace(/\./g, '\\.')}(\\s|$|-)`).test(pipeline)) {
+      say(`  Con una imagen que traiga npm >= ${ctx.policy.minNpmVersion} (image: node:${image}).`);
+    }
     if (!/^\s+ci:\s*(#.*)?$/m.test(pipeline)) {
       say('  Para correrlo a mano ("Run pipeline"), un `custom: ci` con el mismo step (ver el README).');
     }
@@ -324,9 +386,11 @@ export async function runInit(ctx, { dryRun = false, stdout = process.stdout, co
   section('Pasos siguientes');
   const steps = [
     dryRun ? 'Correr init sin --dry-run.' : 'Revisar el diff: git diff .npmrc package.json',
-    ...(node.from !== null && node.from !== undefined
+    ...(deferral
+      ? [`Antes del ${deferral.until}, cuando vence la excepción: pasar de la ${node.from?.major ?? deferral.majors[0]} a la ${node.major} (.nvmrc, imágenes, FROM, engines.node y engines.npm).`]
+      : node.from
       ? [
-          `Pasar el repo de la ${node.from} a la ${node.major}: .nvmrc, imágenes del pipeline y FROM de los Dockerfiles (node:${node.image}). ` +
+          `Pasar el repo de la ${node.from.major} a la ${node.major}: .nvmrc, imágenes del pipeline y FROM de los Dockerfiles (node:${node.image}). ` +
             `En local, \`nvm install ${node.major} && nvm use ${node.major}\`; si npm ci da EUSAGE, \`npm install --package-lock-only --ignore-scripts\`.`,
         ]
       : []),

package/src/lib/node-deferral.js

@@ -0,0 +1,39 @@
+// Excepción para diferir el cambio de línea de Node cuando el salto es grande (decisión del 28-10):
+// subir varias versiones mayores suele arrastrar dependencias y refactors. Se declara en el
+// package.json, así queda en el diff del PR, y vence:
+//
+//   "npmSecurityKit": { "nodeUpgradeDeferredUntil": "AAAA-MM-DD", "nodeUpgradeReason": "por qué" }
+//
+// Vale por hasta policy.nodeDeferMaxDays desde hoy y solo para las líneas cuyo salto al destino es de
+// más de policy.nodeDeferMinJump versiones mayores (eso lo decide quien la usa).
+import { parseDay } from '../context.js';
+import { jsonKeyLine } from './json-lines.js';
+
+const DAY = 86400000;
+const iso = (date) => date.toISOString().slice(0, 10);
+
+// `{ status: 'none' | 'invalid' | 'expired' | 'active', until?, reason?, line?, daysLeft?, problem? }`.
+export function readDeferral(ctx) {
+  const text = ctx.readFile('package.json');
+  let pkg;
+  try {
+    pkg = JSON.parse(text ?? 'null');
+  } catch {
+    return { status: 'none' };
+  }
+  const config = pkg?.npmSecurityKit;
+  if (!config || config.nodeUpgradeDeferredUntil === undefined) return { status: 'none' };
+  const until = config.nodeUpgradeDeferredUntil;
+  const line = jsonKeyLine(text, ['npmSecurityKit', 'nodeUpgradeDeferredUntil']);
+  const reason = typeof config.nodeUpgradeReason === 'string' ? config.nodeUpgradeReason.trim() : '';
+  const date = typeof until === 'string' ? parseDay(until) : null;
+  if (!date) return { status: 'invalid', until, line, problem: 'la fecha tiene que ser "AAAA-MM-DD"' };
+  if (!reason) return { status: 'invalid', until, line, problem: 'falta "nodeUpgradeReason" (por qué no se puede subir ahora)' };
+  const daysLeft = Math.round((date - ctx.today) / DAY);
+  const max = ctx.policy.nodeDeferMaxDays;
+  if (daysLeft > max) {
+    return { status: 'invalid', until, reason, line, problem: `pasa del máximo de ${max} días (como mucho hasta ${iso(new Date(ctx.today.getTime() + max * DAY))})` };
+  }
+  if (daysLeft < 0) return { status: 'expired', until, reason, line };
+  return { status: 'active', until, reason, line, daysLeft };
+}

package/src/policy.js

@@ -27,6 +27,10 @@ export const policy = freeze({
   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,
+  // El cambio de línea de Node se puede diferir con una excepción con fecha en el package.json solo si
+  // el salto al destino es de más de estas versiones mayores, y por hasta estos días.
+  nodeDeferMinJump: 2,
+  nodeDeferMaxDays: 183,
   // Claves del .npmrc del proyecto. `error`: sin ellas la política no se cumple.
   // `warn`: recomendadas.
   requiredNpmrc: {