@saulwade/swl-ses 1.0.0

package/hooks/auto-restaurar-settings.js

@@ -0,0 +1,360 @@
+'use strict';
+
+/**
+ * Hook auto-restaurar-settings — SessionStart, zero-deps.
+ *
+ * Al inicio de cada sesión verifica que ~/.claude/settings.json contiene
+ * los hooks SWL registrados en ~/.claude/notifications/baseline-hooks.json.
+ * Si falta alguno, los restaura preservando todos los hooks ajenos al baseline.
+ *
+ * Flujo:
+ *   1. Leer baseline. Si no existe → exit 0, log "baseline ausente".
+ *   2. Leer settings.json. Si no parsea → exit 0, log error (no sobreescribir).
+ *   3. Comparar hooks del baseline contra settings.json.
+ *   4. Si todos presentes → exit 0 (idempotente, no toca el archivo).
+ *   5. Si falta alguno → backup → merge → atomicWriteJSON → validar → rollback si falla.
+ *
+ * Mitigación al incidente del 2026-04-20: el bloque hooks del settings global
+ * del usuario desapareció silenciosamente y se quedó 4 días sin notificaciones.
+ *
+ * Restricciones:
+ *   - Best-effort: cualquier error no capturado → exit 0.
+ *   - NUNCA escribe fuera de ~/.claude/ (validación de path obligatoria).
+ *   - No loggea el contenido del settings.json, solo metadata.
+ *   - Opt-out: SWL_NOTIFICACIONES_TELEGRAM=0 desactiva el hook.
+ *
+ * @module hooks/auto-restaurar-settings
+ */
+
+const fs   = require('node:fs');
+const path = require('node:path');
+const os   = require('node:os');
+
+const { atomicWriteJSON } = require('./lib/atomic-write');
+
+// ----------------------------------------------------------------
+// Constantes de rutas
+// ----------------------------------------------------------------
+
+const HOME                = os.homedir();
+const DIR_CLAUDE          = path.join(HOME, '.claude');
+const RUTA_SETTINGS       = path.join(DIR_CLAUDE, 'settings.json');
+const DIR_NOTIFICACIONES  = path.join(DIR_CLAUDE, 'notifications');
+const RUTA_BASELINE       = path.join(DIR_NOTIFICACIONES, 'baseline-hooks.json');
+const LOG_FILE            = path.join(DIR_NOTIFICACIONES, 'hook.log');
+
+// Prefijo que debe tener cualquier ruta que escribamos
+const PREFIJO_PERMITIDO   = DIR_CLAUDE + path.sep;
+
+// ----------------------------------------------------------------
+// Logging — append-only a hook.log, silencioso si falla
+// ----------------------------------------------------------------
+
+/**
+ * Escribe una línea en el archivo de log del hook.
+ * No loggea contenido sensible del settings.json.
+ *
+ * @param {...*} args - Fragmentos del mensaje.
+ */
+function log(...args) {
+  try {
+    // Asegurar que el directorio existe antes de loggear
+    if (!fs.existsSync(DIR_NOTIFICACIONES)) {
+      fs.mkdirSync(DIR_NOTIFICACIONES, { recursive: true });
+    }
+    const partes = args.map(a => (typeof a === 'string' ? a : JSON.stringify(a)));
+    const linea  = `[${new Date().toISOString()}] [auto-restaurar-settings] ${partes.join(' ')}\n`;
+    fs.appendFileSync(LOG_FILE, linea, 'utf8');
+  } catch (_) {}
+}
+
+// ----------------------------------------------------------------
+// Validación de path traversal
+// ----------------------------------------------------------------
+
+/**
+ * Verifica que una ruta resuelta esté dentro de ~/.claude/.
+ * Aborta con log si la ruta escapa al directorio permitido.
+ *
+ * @param {string} rutaResuelta - Ruta ya resuelta con path.resolve().
+ * @returns {boolean} true si es segura, false si escapa.
+ */
+function esRutaPermitida(rutaResuelta) {
+  return rutaResuelta.startsWith(PREFIJO_PERMITIDO)
+    || rutaResuelta === RUTA_SETTINGS;
+}
+
+// ----------------------------------------------------------------
+// Lectura del baseline de hooks
+// ----------------------------------------------------------------
+
+/**
+ * Lee y parsea ~/.claude/notifications/baseline-hooks.json.
+ *
+ * @returns {{ ok: true, baseline: object } | { ok: false, motivo: string }}
+ */
+function leerBaseline() {
+  if (!fs.existsSync(RUTA_BASELINE)) {
+    return { ok: false, motivo: 'baseline ausente' };
+  }
+  try {
+    const contenido = fs.readFileSync(RUTA_BASELINE, 'utf8');
+    const baseline  = JSON.parse(contenido);
+    return { ok: true, baseline };
+  } catch (e) {
+    return { ok: false, motivo: `baseline inválido: ${e.message}` };
+  }
+}
+
+// ----------------------------------------------------------------
+// Lectura del settings.json global
+// ----------------------------------------------------------------
+
+/**
+ * Lee y parsea ~/.claude/settings.json.
+ *
+ * @returns {{ ok: true, settings: object } | { ok: false, motivo: string }}
+ */
+function leerSettings() {
+  if (!fs.existsSync(RUTA_SETTINGS)) {
+    // Si no existe es un settings vacío válido — lo tratamos como {}
+    return { ok: true, settings: {} };
+  }
+  try {
+    const contenido = fs.readFileSync(RUTA_SETTINGS, 'utf8');
+    const settings  = JSON.parse(contenido);
+    return { ok: true, settings };
+  } catch (e) {
+    return { ok: false, motivo: `settings JSON inválido — no se sobreescribe: ${e.message}` };
+  }
+}
+
+// ----------------------------------------------------------------
+// Expansión de placeholders en comandos del baseline
+// ----------------------------------------------------------------
+
+/**
+ * Expande el placeholder <HOME> en un comando del baseline.
+ *
+ * @param {string} comando - Comando con posible placeholder "<HOME>".
+ * @returns {string} Comando con <HOME> reemplazado por os.homedir().
+ */
+function expandirPlaceholders(comando) {
+  return comando.replace(/<HOME>/g, HOME);
+}
+
+// ----------------------------------------------------------------
+// Detección de hooks faltantes
+// ----------------------------------------------------------------
+
+/**
+ * Verifica qué hooks del baseline faltan en el settings actual.
+ *
+ * Un hook del baseline se considera "presente" si existe al menos un entry
+ * cuyo `command` (con <HOME> expandido) coincide exactamente con el del baseline.
+ *
+ * @param {object} settings   - Objeto del settings.json actual.
+ * @param {object} baselineHooks - Mapa event → array de grupos del baseline.
+ * @returns {Array<{ evento: string, grupo: object }>} Lista de grupos faltantes.
+ */
+function detectarFaltantes(settings, baselineHooks) {
+  const faltantes = [];
+  const hooksSettings = settings.hooks || {};
+
+  for (const [evento, grupos] of Object.entries(baselineHooks)) {
+    const gruposActuales = hooksSettings[evento] || [];
+
+    for (const grupo of grupos) {
+      // Extraer los comandos que este grupo del baseline define
+      const comandosBaseline = (grupo.hooks || [])
+        .filter(h => h.type === 'command' && h.command)
+        .map(h => expandirPlaceholders(h.command));
+
+      // Para cada comando del baseline, verificar si existe en algún entry del settings
+      for (const cmdBaseline of comandosBaseline) {
+        const yaPresente = gruposActuales.some(g =>
+          Array.isArray(g.hooks) &&
+          g.hooks.some(h => h.type === 'command' && h.command === cmdBaseline)
+        );
+        if (!yaPresente) {
+          // Construir el grupo a agregar con placeholder expandido
+          const grupoExpandido = {
+            matcher: grupo.matcher || '',
+            hooks: (grupo.hooks || []).map(h => ({
+              ...h,
+              command: h.command ? expandirPlaceholders(h.command) : h.command,
+            })),
+          };
+          faltantes.push({ evento, grupo: grupoExpandido, cmdBaseline });
+        }
+      }
+    }
+  }
+
+  return faltantes;
+}
+
+// ----------------------------------------------------------------
+// Creación del backup
+// ----------------------------------------------------------------
+
+/**
+ * Crea una copia de seguridad de settings.json antes de modificarlo.
+ * Nombre del backup: settings.json.swl-backup-<unix-timestamp>
+ *
+ * @returns {{ ok: true, rutaBackup: string } | { ok: false, motivo: string }}
+ */
+function crearBackup() {
+  const ts         = Date.now();
+  const rutaBackup = `${RUTA_SETTINGS}.swl-backup-${ts}`;
+
+  // Validar path traversal (el backup debe estar en ~/.claude/)
+  const resuelta = path.resolve(rutaBackup);
+  if (!esRutaPermitida(resuelta)) {
+    return { ok: false, motivo: `path traversal detectado en backup: ${resuelta}` };
+  }
+
+  try {
+    fs.copyFileSync(RUTA_SETTINGS, rutaBackup);
+    return { ok: true, rutaBackup };
+  } catch (e) {
+    return { ok: false, motivo: `error al crear backup: ${e.message}` };
+  }
+}
+
+// ----------------------------------------------------------------
+// Merge de hooks faltantes en settings
+// ----------------------------------------------------------------
+
+/**
+ * Agrega los hooks faltantes al settings, preservando todos los hooks existentes.
+ * Los hooks SWL se agregan al FINAL del array de cada evento.
+ *
+ * @param {object} settings  - Settings actual (se muta una copia profunda).
+ * @param {Array}  faltantes - Lista de { evento, grupo } a agregar.
+ * @returns {object} Nuevo settings con los hooks agregados.
+ */
+function mergeFaltantes(settings, faltantes) {
+  // Copia profunda para no mutar el original
+  const nuevo = JSON.parse(JSON.stringify(settings));
+
+  if (!nuevo.hooks) nuevo.hooks = {};
+
+  for (const { evento, grupo } of faltantes) {
+    if (!Array.isArray(nuevo.hooks[evento])) {
+      nuevo.hooks[evento] = [];
+    }
+    nuevo.hooks[evento].push(grupo);
+  }
+
+  return nuevo;
+}
+
+// ----------------------------------------------------------------
+// Flujo principal
+// ----------------------------------------------------------------
+
+function run() {
+  // Opt-out global
+  if (process.env.SWL_NOTIFICACIONES_TELEGRAM === '0') {
+    log('opt-out SWL_NOTIFICACIONES_TELEGRAM=0');
+    return;
+  }
+
+  log('inicio SessionStart');
+
+  // 1. Leer baseline
+  const resultBaseline = leerBaseline();
+  if (!resultBaseline.ok) {
+    log(resultBaseline.motivo);
+    return;
+  }
+  const { baseline } = resultBaseline;
+
+  // Validar estructura mínima del baseline
+  if (!baseline.hooks || typeof baseline.hooks !== 'object') {
+    log('baseline sin campo hooks — estructura inválida');
+    return;
+  }
+
+  // 2. Leer settings.json
+  const resultSettings = leerSettings();
+  if (!resultSettings.ok) {
+    log(resultSettings.motivo);
+    return;
+  }
+  const { settings } = resultSettings;
+
+  // 3. Detectar hooks faltantes
+  const faltantes = detectarFaltantes(settings, baseline.hooks);
+
+  if (faltantes.length === 0) {
+    log('todos los hooks del baseline presentes — noop');
+    return;
+  }
+
+  log(`hooks faltantes detectados: ${faltantes.length}`, faltantes.map(f => f.cmdBaseline).join(', '));
+
+  // 4. Validar path traversal para settings.json
+  const rutaSettingsResuelta = path.resolve(RUTA_SETTINGS);
+  if (!esRutaPermitida(rutaSettingsResuelta) && rutaSettingsResuelta !== path.resolve(RUTA_SETTINGS)) {
+    log('path traversal detectado para settings.json — abortando');
+    return;
+  }
+
+  // 5. Crear backup ANTES de modificar
+  // Si settings no existe aún, no hay nada que respaldar
+  let rutaBackup = null;
+  if (fs.existsSync(RUTA_SETTINGS)) {
+    const resultBackup = crearBackup();
+    if (!resultBackup.ok) {
+      log(resultBackup.motivo, '— abortando para preservar seguridad');
+      return;
+    }
+    rutaBackup = resultBackup.rutaBackup;
+    log('backup creado', path.basename(rutaBackup));
+  }
+
+  // 6. Merge: agregar hooks faltantes preservando todos los existentes
+  const settingsNuevo = mergeFaltantes(settings, faltantes);
+
+  // 7. Escribir con atomicWriteJSON
+  try {
+    atomicWriteJSON(RUTA_SETTINGS, settingsNuevo);
+  } catch (e) {
+    log('error al escribir settings.json:', e.message);
+    // No intentamos rollback aquí porque atomicWriteJSON es atómico:
+    // si falla, el archivo original queda intacto.
+    return;
+  }
+
+  // 8. Validación post-escritura: re-leer y parsear
+  try {
+    const contenidoVerificacion = fs.readFileSync(RUTA_SETTINGS, 'utf8');
+    JSON.parse(contenidoVerificacion);
+  } catch (e) {
+    log('VALIDACIÓN POST-ESCRITURA FALLÓ:', e.message);
+    // Restaurar desde backup si existe
+    if (rutaBackup && fs.existsSync(rutaBackup)) {
+      try {
+        fs.copyFileSync(rutaBackup, RUTA_SETTINGS);
+        log('rollback completado desde backup', path.basename(rutaBackup));
+      } catch (eRollback) {
+        log('ERROR CRÍTICO: rollback falló:', eRollback.message, '— intervención manual requerida en', RUTA_SETTINGS);
+      }
+    }
+    return;
+  }
+
+  log(`restauración completada: ${faltantes.length} hook(s) agregados`);
+}
+
+// ----------------------------------------------------------------
+// Ejecución con best-effort: cualquier excepción no capturada → exit 0
+// ----------------------------------------------------------------
+
+try {
+  run();
+} catch (e) {
+  log('excepción no capturada en run():', e && e.message);
+}