@saulwade/swl-ses 1.3.8 → 1.4.0

package/hooks/lib/webhook-verify.js

@@ -0,0 +1,123 @@
+'use strict';
+
+/**
+ * webhook-verify.js — Verificación de firmas HMAC en webhooks entrantes.
+ *
+ * Provee dos funciones independientes:
+ *
+ *   - verifyGithubSignature(payloadBody, signatureHeader, secret)
+ *     GitHub envía la firma como header `X-Hub-Signature-256: sha256=<hex>`.
+ *     Calcula HMAC SHA-256 sobre el body crudo y compara timing-safe.
+ *
+ *   - verifyBearer(authorizationHeader, secret)
+ *     Genérico: header `Authorization: Bearer <token>` comparado timing-safe
+ *     contra el secreto compartido.
+ *
+ * Ambas funciones:
+ *   - Aceptan body como Buffer o string. Buffer es lo correcto para HMAC
+ *     porque GitHub firma los bytes literales del request, no la cadena
+ *     decodificada.
+ *   - Retornan boolean. Nunca lanzan excepciones — falla = false.
+ *   - Usan `crypto.timingSafeEqual` para evitar ataques de timing.
+ *   - Zero-deps (solo `crypto` nativo).
+ *
+ * Origen: port de `temp/claude-code-telegram-main/src/api/auth.py` (Python, 61 LOC).
+ *
+ * @module hooks/lib/webhook-verify
+ */
+
+const crypto = require('crypto');
+
+/**
+ * Verifica firma HMAC SHA-256 al estilo GitHub.
+ *
+ * @param {Buffer|string} payloadBody Body crudo del request.
+ * @param {string|undefined|null} signatureHeader Valor del header X-Hub-Signature-256.
+ * @param {string} secret Secreto compartido configurado en GitHub.
+ * @returns {boolean} true si la firma es válida; false en cualquier otro caso.
+ */
+function verifyGithubSignature(payloadBody, signatureHeader, secret) {
+  if (!signatureHeader || typeof signatureHeader !== 'string') {
+    return false;
+  }
+  if (!signatureHeader.startsWith('sha256=')) {
+    return false;
+  }
+  if (!secret || typeof secret !== 'string') {
+    return false;
+  }
+  if (payloadBody === undefined || payloadBody === null) {
+    return false;
+  }
+
+  const bodyBuffer = Buffer.isBuffer(payloadBody)
+    ? payloadBody
+    : Buffer.from(String(payloadBody), 'utf8');
+
+  const expectedDigest = crypto
+    .createHmac('sha256', secret)
+    .update(bodyBuffer)
+    .digest('hex');
+  const expectedHeader = 'sha256=' + expectedDigest;
+
+  return constantTimeEqual(expectedHeader, signatureHeader);
+}
+
+/**
+ * Verifica un Bearer token simple en el header Authorization.
+ *
+ * @param {string|undefined|null} authorizationHeader Valor del header Authorization.
+ * @param {string} secret Token esperado (sin el prefijo "Bearer ").
+ * @returns {boolean} true si el token coincide; false en cualquier otro caso.
+ */
+function verifyBearer(authorizationHeader, secret) {
+  if (!authorizationHeader || typeof authorizationHeader !== 'string') {
+    return false;
+  }
+  if (!authorizationHeader.startsWith('Bearer ')) {
+    return false;
+  }
+  if (!secret || typeof secret !== 'string') {
+    return false;
+  }
+
+  const token = authorizationHeader.slice('Bearer '.length);
+  return constantTimeEqual(token, secret);
+}
+
+/**
+ * Comparación timing-safe de dos strings.
+ *
+ * `crypto.timingSafeEqual` requiere buffers de la misma longitud. Si las
+ * longitudes difieren, el comparador termina temprano y eso filtra
+ * información de longitud por timing. Para evitarlo:
+ *
+ *   1. Si longitudes difieren, retornar false sin invocar timingSafeEqual.
+ *   2. Si coinciden, comparar.
+ *
+ * El filtrado de longitud es aceptable aquí porque la longitud de la firma
+ * HMAC SHA-256 hex es fija (71 caracteres con prefijo "sha256=") y la
+ * longitud del Bearer es controlada por el secreto del servidor — ninguna
+ * es información sensible derivable del input del atacante.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {boolean}
+ */
+function constantTimeEqual(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') {
+    return false;
+  }
+  if (a.length !== b.length) {
+    return false;
+  }
+  const bufA = Buffer.from(a, 'utf8');
+  const bufB = Buffer.from(b, 'utf8');
+  return crypto.timingSafeEqual(bufA, bufB);
+}
+
+module.exports = {
+  verifyGithubSignature,
+  verifyBearer,
+  constantTimeEqual,
+};

package/hooks/proteccion-rutas.js

@@ -208,8 +208,10 @@ function verificarDentroDeCwd(rutaRaw, cwdActual) {
 
 /**
  * Rutas permitidas fuera del CWD.
- * Estas rutas son legítimas para el funcionamiento de Claude Code
- * (memoria persistente, configuración de proyecto, etc.).
+ * Estas rutas son legítimas para el funcionamiento de Claude Code y SWL
+ * (memoria persistente, configuración global, skills/agentes/comandos/reglas
+ * del usuario que SWL instala globalmente y que se modifican durante backports
+ * entre proyectos).
  *
  * Se comparan con startsWith case-insensitive en Windows.
  */
@@ -218,21 +220,100 @@ const RUTAS_PERMITIDAS_EXTERNAS = [
   path.join(os.homedir(), '.claude', 'projects'),
   // Configuración global de Claude Code
   path.join(os.homedir(), '.claude', 'settings.json'),
+  // Skills globales del usuario (instaladas por SWL, modificables durante backport)
+  path.join(os.homedir(), '.claude', 'skills'),
+  // Agentes globales del usuario
+  path.join(os.homedir(), '.claude', 'agents'),
+  // Comandos globales del usuario
+  path.join(os.homedir(), '.claude', 'commands'),
+  // Reglas globales del usuario (modificables durante consolidación cross-proyecto)
+  path.join(os.homedir(), '.claude', 'rules'),
 ];
 
 /**
- * Verifica si una ruta resuelta está en la lista de rutas externas permitidas.
+ * Parsea la variable de entorno SWL_PROTECCION_RUTAS_PERMITIR (CSV de rutas
+ * absolutas) y devuelve un array de paths normalizados.
+ *
+ * Patrón de uso: el usuario define la variable ANTES de iniciar Claude Code
+ * cuando necesita permitir writes legítimos a destinos fuera del CWD que no
+ * están cubiertos por el whitelist por defecto. Ej:
+ *
+ *   SWL_PROTECCION_RUTAS_PERMITIR="D:\Python\sigaf,F:\vault\notas"
+ *
+ * Cada ruta se resuelve con path.resolve para normalizar separadores y
+ * eliminar referencias relativas. Rutas vacías o solo whitespace se descartan.
+ *
+ * @returns {string[]} array de paths absolutos resueltos (puede estar vacío)
+ */
+function parsearRutasPermitidasUsuario() {
+  const raw = process.env.SWL_PROTECCION_RUTAS_PERMITIR;
+  if (!raw || typeof raw !== 'string') return [];
+  return raw
+    .split(',')
+    .map(r => r.trim())
+    .filter(r => r.length > 0)
+    .map(r => path.resolve(r));
+}
+
+/**
+ * Cache módulo-level del parseo de SWL_PROTECCION_RUTAS_PERMITIR.
+ *
+ * `process.env` no cambia durante la vida del proceso (los hooks se ejecutan
+ * como subproceso de Claude Code, un proceso nuevo por cada Write/Edit), por
+ * lo que el parseo solo necesita hacerse una vez al cargar el módulo. Esto
+ * evita re-parsear el CSV y volver a llamar `path.resolve` en cada call a
+ * `esRutaExternaPermitida()`, que se ejecuta por cada operación de escritura.
+ *
+ * Para tests que necesitan re-parsear (cambian la variable después de cargar
+ * el módulo), exportar la función `_resetCacheRutasPermitidas()` permitiría
+ * forzar el refresh — los tests existentes usan spawnSync, por lo que cada
+ * subproceso carga el módulo fresco con su propio entorno.
+ */
+const RUTAS_PERMITIDAS_USUARIO = parsearRutasPermitidasUsuario();
+
+/**
+ * Normaliza separadores y elimina trailing slash para comparación de prefijo
+ * con boundary check. Garantiza que la comparación sea sobre componentes de
+ * path completos, no sobre substrings.
+ *
+ * Ejemplo: ambas variantes de `~/.claude/skills/` y `~/.claude/skills` se
+ * normalizan a `.../.claude/skills` (sin trailing).
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+function normalizarParaComparacion(p) {
+  return normalizarSeparadores(p).replace(/\/+$/, '');
+}
+
+/**
+ * Verifica si una ruta resuelta está en la lista de rutas externas permitidas
+ * (whitelist por defecto + rutas opt-in del usuario vía variable de entorno).
+ *
+ * **Boundary check obligatorio**: usa match exacto O prefijo seguido de '/'
+ * para evitar que paths siblings con el mismo prefijo textual pasen la
+ * verificación. Ejemplos de hostiles que DEBEN ser bloqueados:
+ *   - whitelist `~/.claude/skills` → `~/.claude/skills-evil/x.md` (no es subdir)
+ *   - whitelist `~/.claude/settings.json` → `~/.claude/settings.json.bak`
+ *   - whitelist `D:/Proyecto` → `D:/Proyecto-otro/file.md`
+ *
  * @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;
+  const rutaNorm = normalizarParaComparacion(rutaResuelta);
+  const rutaCmp = process.platform === 'win32' ? rutaNorm.toLowerCase() : rutaNorm;
+
+  const combinadas = RUTAS_PERMITIDAS_EXTERNAS.concat(RUTAS_PERMITIDAS_USUARIO);
+  for (const permitida of combinadas) {
+    const permitidaNorm = normalizarParaComparacion(permitida);
+    const permitidaCmp = process.platform === 'win32' ? permitidaNorm.toLowerCase() : permitidaNorm;
+
+    // Match exacto (cubre archivos como settings.json) O prefijo seguido de '/'
+    // (cubre subdirectorios como skills/foo dentro del directorio skills).
+    if (rutaCmp === permitidaCmp || rutaCmp.startsWith(permitidaCmp + '/')) {
+      return true;
+    }
   }
   return false;
 }
@@ -270,7 +351,8 @@ function extraerRuta(toolInput) {
  * @returns {string}
  */
 function construirMensajeBloqueo(tipoViolacion, rutaRaw, rutaResuelta, cwdActual) {
-  return [
+  const esTraversal = /traversal/i.test(tipoViolacion);
+  const lineas = [
     `Escritura bloqueada por política de seguridad de rutas.`,
     ``,
     `Violación: ${tipoViolacion}`,
@@ -282,10 +364,33 @@ function construirMensajeBloqueo(tipoViolacion, rutaRaw, rutaResuelta, cwdActual
     `  - 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');
+  ];
+
+  if (!esTraversal) {
+    lineas.push(
+      ``,
+      `Rutas externas permitidas por defecto:`,
+      `  - ~/.claude/projects, settings.json, skills, agents, commands, rules`,
+      ``,
+      `Para destinos legítimos no cubiertos (otros proyectos del usuario, vault,`,
+      `backports cross-proyecto), define la variable de entorno ANTES de iniciar`,
+      `Claude Code con un CSV de rutas absolutas:`,
+      ``,
+      `  PowerShell:  $env:SWL_PROTECCION_RUTAS_PERMITIR = "D:\\Python\\sigaf,F:\\vault"`,
+      `  Bash:        export SWL_PROTECCION_RUTAS_PERMITIR="/d/Python/sigaf,/f/vault"`,
+      ``,
+      `Alternativa: usar Bash con cp/heredoc (no pasa por este hook) cuando el`,
+      `destino es seguro y el cambio es puntual.`,
+    );
+  } else {
+    lineas.push(
+      ``,
+      `Path traversal NO se levanta con SWL_PROTECCION_RUTAS_PERMITIR — la variable`,
+      `solo afecta el check de "dentro del CWD", no las secuencias ../, ~/, %2e%2e.`,
+    );
+  }
+
+  return lineas.join('\n');
 }
 
 // ---------------------------------------------------------------------------