@saulwade/swl-ses 1.0.0

package/hooks/proteccion-rutas.js

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: proteccion-rutas.js
+ * Tipo: PreToolUse  (aplica a: Write, Edit)
+ *
+ * Protege el sistema de archivos verificando que la ruta de destino sea segura:
+ *
+ *   1. Sin path traversal:
+ *      - Secuencias "../" o "..\\" (relativas que suben directorios)
+ *      - Rutas que comienzan con "~/" (directorio home del usuario)
+ *      - Secuencias percent-encoded: "%2e%2e", "%2E%2E", "%2e%2E" y combinaciones
+ *      - Rutas que comienzan con "/" o una letra de drive Windows seguida de ":\\"
+ *        apuntando fuera del CWD
+ *
+ *   2. Destino dentro del directorio de trabajo actual (CWD):
+ *      La ruta resuelta (path.resolve) debe comenzar con el CWD normalizado.
+ *      Si apunta fuera, se bloquea.
+ *
+ * Resultado:
+ *   - Violación detectada → razón en stdout + exit code 2 (block)
+ *   - Ruta segura         → sin output, proceso termina naturalmente
+ *   - Error interno       → sin output (nunca bloquear por fallo del hook)
+ *
+ * Limitaciones conocidas:
+ *   - No detecta symlinks que apuntan fuera del CWD (requeriría fs.realpathSync).
+ *   - En Windows las rutas UNC (\\server\share) no se analizan completamente.
+ */
+
+const path = require('path');
+const os   = require('os');
+
+// ---------------------------------------------------------------------------
+// Patrones de path traversal
+// ---------------------------------------------------------------------------
+
+/**
+ * Lista de patrones que indican intento de traversal.
+ * Se evalúan contra la ruta RAW recibida (antes de normalizar),
+ * para capturar intentos de evasión por encoding.
+ */
+const PATRONES_TRAVERSAL = [
+  {
+    descripcion: 'Secuencia "../" (subida de directorio POSIX)',
+    patron: /(?:^|\/)\.\.(?:\/|$)/,
+  },
+  {
+    descripcion: 'Secuencia "..\\" (subida de directorio Windows)',
+    patron: /(?:^|\\)\.\.(?:\\|$)/,
+  },
+  {
+    descripcion: 'Percent-encoding de ".." (%2e%2e, %2E%2E, etc.)',
+    patron: /%2[eE]%2[eE]/i,
+  },
+  {
+    descripcion: 'Percent-encoding de "/" (%2f, %2F)',
+    // Combinado con ".." es traversal: "..%2f"
+    patron: /\.\.%2[fF]/i,
+  },
+  {
+    descripcion: 'Percent-encoding de "\\" (%5c, %5C)',
+    patron: /\.\.%5[cC]/i,
+  },
+  {
+    descripcion: 'Ruta de directorio home (~/ o ~\\)',
+    patron: /^~[/\\]/,
+  },
+  {
+    descripcion: 'Doble barra que puede usarse para evasión (//)',
+    // Rutas como "//etc/passwd"
+    patron: /^\/\//,
+  },
+];
+
+// ---------------------------------------------------------------------------
+// Funciones auxiliares
+// ---------------------------------------------------------------------------
+
+/**
+ * Normaliza separadores de ruta a "/" para comparaciones consistentes
+ * entre POSIX y Windows.
+ * @param {string} p
+ * @returns {string}
+ */
+function normalizarSeparadores(p) {
+  return String(p).replace(/\\/g, '/');
+}
+
+// ---------------------------------------------------------------------------
+// Archivos de configuración protegidos (config protection)
+// ---------------------------------------------------------------------------
+
+/**
+ * Archivos de configuración de linters, formatters y compiladores que NO deben
+ * ser modificados por el agente. Cuando el agente intenta "resolver" errores
+ * de lint/formato debilitando la configuración, este check lo redirige a
+ * corregir el código en su lugar.
+ *
+ * Inspirado en ECC config-protection.js.
+ */
+const ARCHIVOS_CONFIG_PROTEGIDOS = [
+  // Linters
+  '.eslintrc', '.eslintrc.js', '.eslintrc.json', '.eslintrc.yml', '.eslintrc.cjs',
+  'eslint.config.js', 'eslint.config.mjs', 'eslint.config.ts',
+  'biome.json', 'biome.jsonc',
+  '.pylintrc', 'pylintrc', '.flake8', '.ruff.toml', 'ruff.toml',
+  '.rubocop.yml',
+  // Formatters
+  '.prettierrc', '.prettierrc.js', '.prettierrc.json', '.prettierrc.yml',
+  '.prettierrc.cjs', '.prettierrc.mjs', 'prettier.config.js', 'prettier.config.mjs',
+  '.editorconfig',
+  // TypeScript / compiladores
+  'tsconfig.json', 'tsconfig.build.json', 'tsconfig.app.json', 'tsconfig.spec.json',
+  // Testing
+  'jest.config.js', 'jest.config.ts', 'vitest.config.ts', 'vitest.config.js',
+  'pytest.ini', 'setup.cfg', 'pyproject.toml',
+  // CI/CD
+  '.github/workflows', '.gitlab-ci.yml',
+];
+
+/**
+ * Verifica si la ruta apunta a un archivo de configuración protegido.
+ * @param {string} rutaRaw
+ * @returns {{ protegido: boolean, archivo: string }}
+ */
+function verificarConfigProtegido(rutaRaw) {
+  const nombre = path.basename(rutaRaw);
+  const rutaNorm = normalizarSeparadores(rutaRaw);
+
+  for (const cfg of ARCHIVOS_CONFIG_PROTEGIDOS) {
+    if (nombre === cfg || rutaNorm.endsWith('/' + cfg) || rutaNorm === cfg) {
+      return { protegido: true, archivo: cfg };
+    }
+  }
+  return { protegido: false, archivo: '' };
+}
+
+/**
+ * Construye mensaje de advertencia para archivos de config protegidos.
+ * @param {string} archivo
+ * @param {string} rutaRaw
+ * @returns {string}
+ */
+function construirMensajeConfigProtegido(archivo, rutaRaw) {
+  return [
+    `Advertencia: modificacion de archivo de configuracion protegido.`,
+    ``,
+    `Archivo: ${archivo}`,
+    `Ruta: ${rutaRaw}`,
+    ``,
+    `Los archivos de linters, formatters y compiladores NO deben modificarse`,
+    `para resolver errores. En su lugar:`,
+    `  1. Corrige el codigo que causa el error de lint/formato`,
+    `  2. Si el error es un falso positivo, usa un comentario inline de supresion`,
+    `     (// eslint-disable-next-line, # noqa, #[allow(...)], etc.)`,
+    `  3. Solo modifica la config si es un requisito explicito del plan`,
+    ``,
+    `Si realmente necesitas modificar este archivo, documenta la razon en el commit.`,
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Funciones de verificación de traversal
+// ---------------------------------------------------------------------------
+
+/**
+ * Verifica que la ruta RAW no contenga patrones de traversal conocidos.
+ * @param {string} rutaRaw - Ruta tal como la entregó Claude Code.
+ * @returns {{ segura: boolean, descripcion: string }}
+ */
+function verificarPatronesTraversal(rutaRaw) {
+  for (const { patron, descripcion } of PATRONES_TRAVERSAL) {
+    if (patron.test(rutaRaw)) {
+      return { segura: false, descripcion };
+    }
+  }
+  return { segura: true, descripcion: '' };
+}
+
+/**
+ * Verifica que la ruta resuelta esté dentro del directorio de trabajo actual.
+ *
+ * Se usa path.resolve() para expandir rutas relativas y eliminar ".." que
+ * pudieran haber pasado los filtros anteriores. La comparación se hace con
+ * ambas rutas normalizadas a minúsculas en Windows (case-insensitive FS).
+ *
+ * @param {string} rutaRaw    - Ruta recibida del hook.
+ * @param {string} cwdActual  - Directorio de trabajo actual del proceso.
+ * @returns {{ dentro: boolean, rutaResuelta: string }}
+ */
+function verificarDentroDeCwd(rutaRaw, cwdActual) {
+  const rutaResuelta = path.resolve(cwdActual, rutaRaw);
+
+  // Normalizar separadores y agregar "/" al final del CWD para evitar
+  // falsos positivos con directorios que comparten prefijo.
+  // Ej: CWD=/proyecto y ruta=/proyecto-extra no debe pasar.
+  const cwdNorm  = normalizarSeparadores(cwdActual).replace(/\/?$/, '/');
+  const rutaNorm = normalizarSeparadores(rutaResuelta);
+
+  // En Windows el sistema de archivos es case-insensitive
+  const esDentroDeCwd = process.platform === 'win32'
+    ? rutaNorm.toLowerCase().startsWith(cwdNorm.toLowerCase())
+    : rutaNorm.startsWith(cwdNorm);
+
+  return { dentro: esDentroDeCwd, rutaResuelta };
+}
+
+/**
+ * Rutas permitidas fuera del CWD.
+ * Estas rutas son legítimas para el funcionamiento de Claude Code
+ * (memoria persistente, configuración de proyecto, etc.).
+ *
+ * Se comparan con startsWith case-insensitive en Windows.
+ */
+const RUTAS_PERMITIDAS_EXTERNAS = [
+  // Directorio de memoria persistente de Claude Code (auto memory)
+  path.join(os.homedir(), '.claude', 'projects'),
+  // Configuración global de Claude Code
+  path.join(os.homedir(), '.claude', 'settings.json'),
+];
+
+/**
+ * Verifica si una ruta resuelta está en la lista de rutas externas permitidas.
+ * @param {string} rutaResuelta
+ * @returns {boolean}
+ */
+function esRutaExternaPermitida(rutaResuelta) {
+  const rutaNorm = normalizarSeparadores(rutaResuelta);
+  for (const permitida of RUTAS_PERMITIDAS_EXTERNAS) {
+    const permitidaNorm = normalizarSeparadores(permitida);
+    const coincide = process.platform === 'win32'
+      ? rutaNorm.toLowerCase().startsWith(permitidaNorm.toLowerCase())
+      : rutaNorm.startsWith(permitidaNorm);
+    if (coincide) return true;
+  }
+  return false;
+}
+
+/**
+ * Extrae el file_path del payload del hook.
+ * Soporta las variantes que Claude Code puede enviar.
+ *
+ * @param {object} toolInput
+ * @returns {string|null}
+ */
+function extraerRuta(toolInput) {
+  const candidatos = [
+    toolInput.file_path,
+    toolInput.path,
+    toolInput.filename,
+    toolInput.dest,
+  ];
+  for (const c of candidatos) {
+    if (typeof c === 'string' && c.trim() !== '') return c.trim();
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Construcción de mensaje de bloqueo
+// ---------------------------------------------------------------------------
+
+/**
+ * Construye el mensaje de error para devolver a Claude Code.
+ * @param {string} tipoViolacion - Descripción corta del tipo de violación.
+ * @param {string} rutaRaw       - Ruta original recibida.
+ * @param {string} rutaResuelta  - Ruta resuelta por path.resolve.
+ * @param {string} cwdActual     - CWD del proceso.
+ * @returns {string}
+ */
+function construirMensajeBloqueo(tipoViolacion, rutaRaw, rutaResuelta, cwdActual) {
+  return [
+    `Escritura bloqueada por política de seguridad de rutas.`,
+    ``,
+    `Violación: ${tipoViolacion}`,
+    `Ruta recibida:  ${rutaRaw}`,
+    `Ruta resuelta:  ${rutaResuelta || '(no calculada)'}`,
+    `Directorio CWD: ${cwdActual}`,
+    ``,
+    `Reglas de seguridad:`,
+    `  - La ruta de destino debe estar dentro del directorio de trabajo actual.`,
+    `  - No se permiten secuencias de path traversal (../, ~/, %2e%2e, etc.).`,
+    `  - No se permiten rutas absolutas fuera del proyecto.`,
+    ``,
+    `Si necesitas escribir fuera del CWD, ajusta el directorio de trabajo`,
+    `o utiliza una ruta relativa dentro del proyecto.`,
+  ].join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Entrypoint principal
+// ---------------------------------------------------------------------------
+
+let inputRaw = '';
+
+process.stdin.on('data', chunk => {
+  inputRaw += chunk;
+});
+
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(inputRaw);
+
+    const toolName  = String(data.tool_name  || data.tool?.name || '');
+    const toolInput = data.tool_input || data.tool?.input || {};
+    const sessionId = String(data.session_id || 'default');
+
+    // Este hook solo aplica a Write y Edit
+    if (!['Write', 'Edit'].includes(toolName)) {
+      return;
+    }
+
+    // Extraer la ruta de destino
+    const rutaRaw = extraerRuta(toolInput);
+    if (!rutaRaw) {
+      // Sin ruta, nada que verificar — dejar que Claude Code maneje el error
+      return;
+    }
+
+    const cwdActual = process.cwd();
+
+    // --- Verificación 1: patrones de traversal en la ruta raw ---
+    const { segura, descripcion } = verificarPatronesTraversal(rutaRaw);
+    if (!segura) {
+      const { rutaResuelta } = verificarDentroDeCwd(rutaRaw, cwdActual);
+      const razon = construirMensajeBloqueo(
+        `Path traversal detectado — ${descripcion}`,
+        rutaRaw,
+        rutaResuelta,
+        cwdActual
+      );
+      process.stderr.write(razon);
+      try { require('./lib/guardrail-metrics').recordActivation('proteccion-rutas.js', sessionId, true); } catch (_) {}
+      process.exit(2);
+    }
+
+    // --- Verificación 2: destino dentro del CWD o en rutas externas permitidas ---
+    const { dentro, rutaResuelta } = verificarDentroDeCwd(rutaRaw, cwdActual);
+    if (!dentro && !esRutaExternaPermitida(rutaResuelta)) {
+      const razon = construirMensajeBloqueo(
+        `Destino fuera del directorio de trabajo actual`,
+        rutaRaw,
+        rutaResuelta,
+        cwdActual
+      );
+      process.stderr.write(razon);
+      try { require('./lib/guardrail-metrics').recordActivation('proteccion-rutas.js', sessionId, true); } catch (_) {}
+      process.exit(2);
+    }
+
+    // --- Verificación 3: archivos de configuración protegidos ---
+    const { protegido, archivo } = verificarConfigProtegido(rutaRaw);
+    if (protegido) {
+      const advertencia = construirMensajeConfigProtegido(archivo, rutaRaw);
+      process.stdout.write(advertencia);
+      // Exit 0 (advertencia, no bloqueo) — el agente ve el mensaje pero puede continuar
+      // si tiene justificacion explicita. Para bloquear, cambiar a process.exit(2).
+    }
+
+    // Ruta segura — permitir la operación
+
+  } catch (err) {
+    // El hook nunca bloquea por errores internos propios
+  }
+});

package/hooks/registro-turnos.js

@@ -0,0 +1,209 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Hook: registro-turnos.js
+ * Tipo: PostToolUse (todas las herramientas)
+ *
+ * Persiste cada tool call (turno) en .planning/sessions/{session_id}/turns.jsonl
+ * para auditoría granular y futuro replay/fork de sesiones.
+ *
+ * Patrón inspirado en `temp/claudian-main/src/core/bootstrap/SessionStorage.ts`
+ * (plugin Obsidian Claudian, Yishen Tu, MIT). Diferencias respecto al
+ * original:
+ *   - Claudian persiste SessionMetadata + transcripts en JSONL del provider.
+ *     SWL persiste turn-by-turn en formato propio compatible con
+ *     .planning/sessions/.
+ *   - Sanitización agresiva de entrada/salida antes de persistir
+ *     (riesgo PII/secretos en argumentos de tools).
+ *
+ * Estado: OPT-IN. Inactivo por defecto. Activar con SWL_REGISTRO_TURNOS=1.
+ *
+ * Razones del default OFF:
+ *   - Volumen alto: cada tool call genera entrada (decenas por sesión).
+ *   - Riesgo PII: tool_input de Bash/Write/Edit puede contener tokens,
+ *     contraseñas pegadas accidentalmente, paths privados.
+ *   - El usuario debe decidir explícitamente activarlo en su entorno.
+ *
+ * Schema de cada turno (JSONL append-only):
+ *   {
+ *     ts: ISO timestamp,
+ *     session_id: string,
+ *     tool: string,
+ *     input_resumen: string,         // preview ≤ 200 chars, secrets sanitizados
+ *     output_resumen: string,        // preview ≤ 500 chars, secrets sanitizados
+ *     duracion_ms?: number,
+ *     agente?: string,               // si tool=Agent, subagent_type
+ *     error?: boolean
+ *   }
+ *
+ * NUNCA persiste:
+ *   - tool_input completo (truncado a 200 chars)
+ *   - tool_response completo (truncado a 500 chars)
+ *   - Patrones que parezcan tokens/secretos (sanitizados a [REDACTED])
+ *
+ * Variables de entorno:
+ *   SWL_REGISTRO_TURNOS=1     - activa el hook (default: OFF)
+ *   SWL_REGISTRO_TURNOS_LIMITE - máximo turns por sesión (default: 1000)
+ *
+ * Helper de inspección:
+ *   /swl:sesiones --turnos=<session_id>
+ *
+ * @see hooks/lib/atomic-write.js
+ * @see hooks/lib/privacy-filter.js (si existe; fallback inline si no)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const LIMITE_TURNOS = parseInt(process.env.SWL_REGISTRO_TURNOS_LIMITE || '1000', 10);
+const MAX_INPUT_CHARS = 200;
+const MAX_OUTPUT_CHARS = 500;
+const DIR_BASE = path.join(process.cwd(), '.planning', 'sessions');
+
+// Patrones de sanitización conservadores: tokens largos, llaves API, JWT,
+// password en URLs, paths con .env. Si aparece un match, se reemplaza con
+// [REDACTED].
+const PATRONES_REDACT = [
+  /\b[A-Za-z0-9_-]{32,}\b/g,                    // tokens largos
+  /(?:sk|pk|key|token|secret|password|pwd|api[_-]?key)["':\s=]+[A-Za-z0-9_\-./]{8,}/gi,
+  /\bey[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{20,}\b/g, // JWT
+  /https?:\/\/[^:]+:[^@\s]+@/g,                 // basic auth en URL
+  /-----BEGIN [A-Z ]+-----[\s\S]*?-----END [A-Z ]+-----/g, // PEM blocks
+];
+
+function sanitizar(texto) {
+  if (!texto) return '';
+  let r = String(texto);
+  for (const re of PATRONES_REDACT) {
+    r = r.replace(re, '[REDACTED]');
+  }
+  return r;
+}
+
+function truncar(texto, max) {
+  const s = sanitizar(texto);
+  if (s.length <= max) return s;
+  return s.slice(0, max - 3) + '...';
+}
+
+function ensureDir(dir) {
+  try { fs.mkdirSync(dir, { recursive: true }); } catch { /* ignore */ }
+}
+
+function contarTurnos(rutaArchivo) {
+  try {
+    if (!fs.existsSync(rutaArchivo)) return 0;
+    const contenido = fs.readFileSync(rutaArchivo, 'utf8');
+    return contenido.split(/\r?\n/).filter(Boolean).length;
+  } catch {
+    return 0;
+  }
+}
+
+function extraerInfoTurno(data) {
+  const toolName = String(data.tool_name || data.tool?.name || '');
+  if (!toolName) return null;
+
+  const sessionId = String(data.session_id || 'default').slice(0, 64);
+
+  const toolInput = data.tool_input || data.tool?.input || {};
+  const toolResponse = data.tool_response || data.tool_result || {};
+
+  // Resumen de input: serializar y truncar
+  let inputStr = '';
+  try {
+    inputStr = typeof toolInput === 'string'
+      ? toolInput
+      : JSON.stringify(toolInput);
+  } catch { inputStr = '[unserializable]'; }
+
+  // Resumen de output: extraer campos comunes
+  let outputStr = '';
+  try {
+    if (typeof toolResponse === 'string') {
+      outputStr = toolResponse;
+    } else if (toolResponse && typeof toolResponse === 'object') {
+      const campos = ['output', 'content', 'stdout', 'text', 'result', 'message', 'error'];
+      for (const c of campos) {
+        if (typeof toolResponse[c] === 'string') {
+          outputStr = toolResponse[c];
+          break;
+        }
+      }
+      if (!outputStr) outputStr = JSON.stringify(toolResponse);
+    }
+  } catch { outputStr = '[unserializable]'; }
+
+  const esError = !!(toolResponse && (toolResponse.is_error || toolResponse.status === 'failed'));
+
+  const turno = {
+    ts: new Date().toISOString(),
+    session_id: sessionId,
+    tool: toolName,
+    input_resumen: truncar(inputStr, MAX_INPUT_CHARS),
+    output_resumen: truncar(outputStr, MAX_OUTPUT_CHARS),
+  };
+
+  if (data.duration_ms || toolResponse.duration_ms) {
+    turno.duracion_ms = data.duration_ms || toolResponse.duration_ms;
+  }
+
+  if (toolName === 'Agent') {
+    const subType = toolInput.subagent_type || toolInput.type;
+    if (subType) turno.agente = String(subType).slice(0, 60);
+  }
+
+  if (esError) turno.error = true;
+
+  return turno;
+}
+
+// Solo registrar listeners de stdin en modo CLI. Cuando se importa como
+// módulo (tests), registrar listeners mantiene el event loop vivo
+// indefinidamente porque stdin nunca emite 'end' en ese contexto, lo que
+// hace que la suite de tests cuelgue hasta el timeout. El hook real
+// invocado por Claude Code siempre se ejecuta como require.main.
+//
+// El opt-in via SWL_REGISTRO_TURNOS también se evalúa aquí adentro: si
+// estuviera en el top-level del archivo, importar el módulo desde un
+// test sin la env var mataría al test runner via process.exit(0).
+if (require.main === module) {
+  if (process.env.SWL_REGISTRO_TURNOS !== '1') {
+    // OPT-IN: hook inactivo por default. Salir silencioso sin leer stdin.
+    process.exit(0);
+  }
+  let inputRaw = '';
+  process.stdin.on('data', chunk => { inputRaw += chunk; });
+
+  process.stdin.on('end', () => {
+    try {
+      const data = JSON.parse(inputRaw);
+      const turno = extraerInfoTurno(data);
+      if (!turno) return;
+
+      const dirSesion = path.join(DIR_BASE, turno.session_id);
+      ensureDir(dirSesion);
+      const rutaArchivo = path.join(dirSesion, 'turns.jsonl');
+
+      if (contarTurnos(rutaArchivo) >= LIMITE_TURNOS) {
+        // Hard cap: no seguir creciendo. El usuario decide rotar/limpiar.
+        return;
+      }
+
+      fs.appendFileSync(rutaArchivo, JSON.stringify(turno) + '\n', 'utf8');
+    } catch (err) {
+      // Hook nunca bloquea Claude Code, pero deja una traza diagnóstica
+      // para no perder regresiones silenciosas (ver feedback memoria
+      // sobre errores silenciados).
+      process.stderr.write(`[registro-turnos] error interno: ${String(err.message || err).slice(0, 120)}\n`);
+    }
+  });
+} else {
+  module.exports = {
+    extraerInfoTurno,
+    sanitizar,
+    truncar,
+    _internals: { PATRONES_REDACT, MAX_INPUT_CHARS, MAX_OUTPUT_CHARS, LIMITE_TURNOS },
+  };
+}