@saulwade/swl-ses 2.3.1 → 2.4.1

package/scripts/mcp-server/auth.js

@@ -1,105 +1,105 @@
-'use strict';
-
-/**
- * Auth opt-in para swl-mcp-server v1.0.0 (ADR-0019 Sub-fase 3).
- *
- * El stub experimental v0.1.x corría sin auth. Cualquier proceso con acceso al
- * stdio podía leer toda la memoria SWL. Esa decisión era aceptable solo en
- * single-user local — no en multi-usuario, no expuesto a red, no compartido.
- *
- * v1.0.0 introduce auth **opt-in**:
- *   - Si `SWL_MCP_API_KEY` NO está definida en el entorno del server, el comportamiento
- *     es idéntico al stub (sin auth). Compatibilidad total con clientes existentes.
- *   - Si `SWL_MCP_API_KEY` ESTÁ definida, cada `tools/call` debe incluir
- *     `params._auth = "<api-key>"`. Sin el token o con token incorrecto, se devuelve
- *     `-32001 Unauthorized`.
- *
- * Decisión deliberada de NO usar header `Authorization: Bearer ...`:
- *   - El protocolo MCP sobre stdio NO transporta headers HTTP.
- *   - Inventar un campo en `initialize.capabilities` específico para swl-ses
- *     rompería la spec del protocolo.
- *   - `_auth` como campo en `params` es el patrón de menor fricción.
- *
- * Limitaciones aceptadas:
- *   - Token estático sin rotación automática — el operador rota manualmente
- *     cambiando la env var del proceso.
- *   - Sin scopes (read/write) porque v1 sigue siendo read-only.
- *
- * @module scripts/mcp-server/auth
- */
-
-const ENV_VAR_NAME = 'SWL_MCP_API_KEY';
-const ERROR_CODE_UNAUTHORIZED = -32001;
-const ERROR_CODE_FORBIDDEN = -32002;
-
-/**
- * Construye un validador de auth desde el entorno actual.
- *
- * Pattern de "construct once, use many": leer la env var una sola vez al arranque
- * y devolver una función pura que valida cada request. Evita race conditions con
- * tests que mutan process.env.
- *
- * @param {object} [opciones] - { env: NodeJS.ProcessEnv } sustituible para tests.
- * @returns {{ requerida: boolean, validar: (request: object) => { ok: boolean, code?: number, message?: string } }}
- */
-function construirValidador(opciones = {}) {
-  const env = opciones.env || process.env;
-  const apiKey = env[ENV_VAR_NAME];
-  const requerida = typeof apiKey === 'string' && apiKey.length > 0;
-
-  return {
-    requerida,
-    validar: (request) => {
-      if (!requerida) return { ok: true };
-      // Solo validar tools/call — initialize, ping, tools/list son metadata pública.
-      const metodo = request && request.method;
-      if (metodo !== 'tools/call') return { ok: true };
-
-      const params = request.params || {};
-      const tokenCliente = params._auth;
-
-      if (typeof tokenCliente !== 'string' || tokenCliente.length === 0) {
-        return {
-          ok: false,
-          code: ERROR_CODE_UNAUTHORIZED,
-          message: 'swl-mcp-server requiere autenticación: SWL_MCP_API_KEY está configurada en el server. El cliente debe enviar params._auth con el API key.',
-        };
-      }
-      if (!comparacionConstante(tokenCliente, apiKey)) {
-        return {
-          ok: false,
-          code: ERROR_CODE_FORBIDDEN,
-          message: 'Token inválido.',
-        };
-      }
-      return { ok: true };
-    },
-  };
-}
-
-/**
- * Comparación de strings en tiempo constante para evitar timing attacks
- * sobre el API key. Implementación zero-deps simple.
- *
- * Si las longitudes difieren, igual se itera la longitud máxima para no filtrar
- * información sobre el largo del secreto vía duración de la comparación.
- */
-function comparacionConstante(a, b) {
-  if (typeof a !== 'string' || typeof b !== 'string') return false;
-  const len = Math.max(a.length, b.length);
-  let diff = a.length ^ b.length;
-  for (let i = 0; i < len; i++) {
-    const ca = i < a.length ? a.charCodeAt(i) : 0;
-    const cb = i < b.length ? b.charCodeAt(i) : 0;
-    diff |= ca ^ cb;
-  }
-  return diff === 0;
-}
-
-module.exports = {
-  construirValidador,
-  comparacionConstante,
-  ENV_VAR_NAME,
-  ERROR_CODE_UNAUTHORIZED,
-  ERROR_CODE_FORBIDDEN,
-};
+'use strict';
+
+/**
+ * Auth opt-in para swl-mcp-server v1.0.0 (ADR-0019 Sub-fase 3).
+ *
+ * El stub experimental v0.1.x corría sin auth. Cualquier proceso con acceso al
+ * stdio podía leer toda la memoria SWL. Esa decisión era aceptable solo en
+ * single-user local — no en multi-usuario, no expuesto a red, no compartido.
+ *
+ * v1.0.0 introduce auth **opt-in**:
+ *   - Si `SWL_MCP_API_KEY` NO está definida en el entorno del server, el comportamiento
+ *     es idéntico al stub (sin auth). Compatibilidad total con clientes existentes.
+ *   - Si `SWL_MCP_API_KEY` ESTÁ definida, cada `tools/call` debe incluir
+ *     `params._auth = "<api-key>"`. Sin el token o con token incorrecto, se devuelve
+ *     `-32001 Unauthorized`.
+ *
+ * Decisión deliberada de NO usar header `Authorization: Bearer ...`:
+ *   - El protocolo MCP sobre stdio NO transporta headers HTTP.
+ *   - Inventar un campo en `initialize.capabilities` específico para swl-ses
+ *     rompería la spec del protocolo.
+ *   - `_auth` como campo en `params` es el patrón de menor fricción.
+ *
+ * Limitaciones aceptadas:
+ *   - Token estático sin rotación automática — el operador rota manualmente
+ *     cambiando la env var del proceso.
+ *   - Sin scopes (read/write) porque v1 sigue siendo read-only.
+ *
+ * @module scripts/mcp-server/auth
+ */
+
+const ENV_VAR_NAME = 'SWL_MCP_API_KEY';
+const ERROR_CODE_UNAUTHORIZED = -32001;
+const ERROR_CODE_FORBIDDEN = -32002;
+
+/**
+ * Construye un validador de auth desde el entorno actual.
+ *
+ * Pattern de "construct once, use many": leer la env var una sola vez al arranque
+ * y devolver una función pura que valida cada request. Evita race conditions con
+ * tests que mutan process.env.
+ *
+ * @param {object} [opciones] - { env: NodeJS.ProcessEnv } sustituible para tests.
+ * @returns {{ requerida: boolean, validar: (request: object) => { ok: boolean, code?: number, message?: string } }}
+ */
+function construirValidador(opciones = {}) {
+  const env = opciones.env || process.env;
+  const apiKey = env[ENV_VAR_NAME];
+  const requerida = typeof apiKey === 'string' && apiKey.length > 0;
+
+  return {
+    requerida,
+    validar: (request) => {
+      if (!requerida) return { ok: true };
+      // Solo validar tools/call — initialize, ping, tools/list son metadata pública.
+      const metodo = request && request.method;
+      if (metodo !== 'tools/call') return { ok: true };
+
+      const params = request.params || {};
+      const tokenCliente = params._auth;
+
+      if (typeof tokenCliente !== 'string' || tokenCliente.length === 0) {
+        return {
+          ok: false,
+          code: ERROR_CODE_UNAUTHORIZED,
+          message: 'swl-mcp-server requiere autenticación: SWL_MCP_API_KEY está configurada en el server. El cliente debe enviar params._auth con el API key.',
+        };
+      }
+      if (!comparacionConstante(tokenCliente, apiKey)) {
+        return {
+          ok: false,
+          code: ERROR_CODE_FORBIDDEN,
+          message: 'Token inválido.',
+        };
+      }
+      return { ok: true };
+    },
+  };
+}
+
+/**
+ * Comparación de strings en tiempo constante para evitar timing attacks
+ * sobre el API key. Implementación zero-deps simple.
+ *
+ * Si las longitudes difieren, igual se itera la longitud máxima para no filtrar
+ * información sobre el largo del secreto vía duración de la comparación.
+ */
+function comparacionConstante(a, b) {
+  if (typeof a !== 'string' || typeof b !== 'string') return false;
+  const len = Math.max(a.length, b.length);
+  let diff = a.length ^ b.length;
+  for (let i = 0; i < len; i++) {
+    const ca = i < a.length ? a.charCodeAt(i) : 0;
+    const cb = i < b.length ? b.charCodeAt(i) : 0;
+    diff |= ca ^ cb;
+  }
+  return diff === 0;
+}
+
+module.exports = {
+  construirValidador,
+  comparacionConstante,
+  ENV_VAR_NAME,
+  ERROR_CODE_UNAUTHORIZED,
+  ERROR_CODE_FORBIDDEN,
+};

package/scripts/mcp-server/cache.js

@@ -1,106 +1,106 @@
-'use strict';
-
-/**
- * Cache mtime-based para handlers del swl-mcp-server v1.0.0 (ADR-0019 Sub-fase 3).
- *
- * El stub experimental leía disco en cada call (latencia medida ~10ms con
- * APRENDIZAJES.md de 1172 líneas). Para datasets más grandes (>10k líneas) o
- * múltiples clientes concurrentes, el caching reduce sustancialmente la carga.
- *
- * Patrón:
- *   - Key = path absoluto del archivo.
- *   - Value = { mtime, contenido, parsed }.
- *   - Invalidación: si fs.stat().mtime > value.mtime → recargar y reparsear.
- *   - TTL opcional vía `SWL_MCP_CACHE_TTL_MS` (default 60000 ms): aunque mtime no
- *     haya cambiado, recargar tras TTL para defensa contra clock skew o ediciones
- *     que no actualizan mtime (raras pero posibles en filesystems exóticos).
- *
- * Zero-deps. NO usar para escritura — sigue read-only.
- *
- * @module scripts/mcp-server/cache
- */
-
-const fs = require('fs');
-
-const DEFAULT_TTL_MS = 60 * 1000;
-
-/**
- * Crea una instancia de cache mtime-based.
- *
- * @param {object} [opciones]
- * @param {number} [opciones.ttlMs] - TTL en milisegundos. Default 60000.
- * @param {object} [opciones.env] - Para leer SWL_MCP_CACHE_TTL_MS en tests.
- * @returns {{ get: Function, invalidate: Function, stats: Function, _store: Map }}
- */
-function crearCache(opciones = {}) {
-  const env = opciones.env || process.env;
-  const ttlMs = opciones.ttlMs !== undefined
-    ? opciones.ttlMs
-    : (parseInt(env.SWL_MCP_CACHE_TTL_MS, 10) || DEFAULT_TTL_MS);
-
-  const store = new Map();
-  const stats = { hits: 0, misses: 0, invalidations: 0 };
-
-  /**
-   * Obtiene el valor cacheado para `path`. Si el archivo cambió (mtime) o el TTL
-   * expiró, vuelve a leer y parsear con `parser(contenido, path)`.
-   *
-   * @param {string} ruta - Path absoluto del archivo a cachear.
-   * @param {(contenido: string, ruta: string) => any} parser - Función que transforma
-   *   el contenido del archivo en el objeto a cachear. DEBE ser pura.
-   * @returns {{ data: any, hit: boolean } | null} null si el archivo no existe.
-   */
-  function get(ruta, parser) {
-    let stat;
-    try {
-      stat = fs.statSync(ruta);
-    } catch (err) {
-      if (err.code === 'ENOENT') return null;
-      throw err;
-    }
-
-    const mtimeMs = stat.mtimeMs;
-    const ahora = Date.now();
-    const cached = store.get(ruta);
-
-    if (cached && cached.mtimeMs === mtimeMs && (ahora - cached.cargadoEn) < ttlMs) {
-      stats.hits++;
-      return { data: cached.data, hit: true };
-    }
-
-    if (cached) stats.invalidations++;
-    else stats.misses++;
-
-    const contenido = fs.readFileSync(ruta, 'utf-8');
-    const data = parser(contenido, ruta);
-    store.set(ruta, { mtimeMs, cargadoEn: ahora, data });
-    return { data, hit: false };
-  }
-
-  /**
-   * Invalida una entrada o todo el cache.
-   * @param {string} [ruta] - Si se omite, vacía todo.
-   */
-  function invalidate(ruta) {
-    if (ruta === undefined) {
-      const n = store.size;
-      store.clear();
-      stats.invalidations += n;
-      return n;
-    }
-    if (store.delete(ruta)) stats.invalidations++;
-    return 0;
-  }
-
-  return {
-    get,
-    invalidate,
-    stats: () => ({ ...stats, size: store.size, ttlMs }),
-    _store: store, // exposed para tests
-  };
-}
-
-module.exports = {
-  crearCache,
-  DEFAULT_TTL_MS,
-};
+'use strict';
+
+/**
+ * Cache mtime-based para handlers del swl-mcp-server v1.0.0 (ADR-0019 Sub-fase 3).
+ *
+ * El stub experimental leía disco en cada call (latencia medida ~10ms con
+ * APRENDIZAJES.md de 1172 líneas). Para datasets más grandes (>10k líneas) o
+ * múltiples clientes concurrentes, el caching reduce sustancialmente la carga.
+ *
+ * Patrón:
+ *   - Key = path absoluto del archivo.
+ *   - Value = { mtime, contenido, parsed }.
+ *   - Invalidación: si fs.stat().mtime > value.mtime → recargar y reparsear.
+ *   - TTL opcional vía `SWL_MCP_CACHE_TTL_MS` (default 60000 ms): aunque mtime no
+ *     haya cambiado, recargar tras TTL para defensa contra clock skew o ediciones
+ *     que no actualizan mtime (raras pero posibles en filesystems exóticos).
+ *
+ * Zero-deps. NO usar para escritura — sigue read-only.
+ *
+ * @module scripts/mcp-server/cache
+ */
+
+const fs = require('fs');
+
+const DEFAULT_TTL_MS = 60 * 1000;
+
+/**
+ * Crea una instancia de cache mtime-based.
+ *
+ * @param {object} [opciones]
+ * @param {number} [opciones.ttlMs] - TTL en milisegundos. Default 60000.
+ * @param {object} [opciones.env] - Para leer SWL_MCP_CACHE_TTL_MS en tests.
+ * @returns {{ get: Function, invalidate: Function, stats: Function, _store: Map }}
+ */
+function crearCache(opciones = {}) {
+  const env = opciones.env || process.env;
+  const ttlMs = opciones.ttlMs !== undefined
+    ? opciones.ttlMs
+    : (parseInt(env.SWL_MCP_CACHE_TTL_MS, 10) || DEFAULT_TTL_MS);
+
+  const store = new Map();
+  const stats = { hits: 0, misses: 0, invalidations: 0 };
+
+  /**
+   * Obtiene el valor cacheado para `path`. Si el archivo cambió (mtime) o el TTL
+   * expiró, vuelve a leer y parsear con `parser(contenido, path)`.
+   *
+   * @param {string} ruta - Path absoluto del archivo a cachear.
+   * @param {(contenido: string, ruta: string) => any} parser - Función que transforma
+   *   el contenido del archivo en el objeto a cachear. DEBE ser pura.
+   * @returns {{ data: any, hit: boolean } | null} null si el archivo no existe.
+   */
+  function get(ruta, parser) {
+    let stat;
+    try {
+      stat = fs.statSync(ruta);
+    } catch (err) {
+      if (err.code === 'ENOENT') return null;
+      throw err;
+    }
+
+    const mtimeMs = stat.mtimeMs;
+    const ahora = Date.now();
+    const cached = store.get(ruta);
+
+    if (cached && cached.mtimeMs === mtimeMs && (ahora - cached.cargadoEn) < ttlMs) {
+      stats.hits++;
+      return { data: cached.data, hit: true };
+    }
+
+    if (cached) stats.invalidations++;
+    else stats.misses++;
+
+    const contenido = fs.readFileSync(ruta, 'utf-8');
+    const data = parser(contenido, ruta);
+    store.set(ruta, { mtimeMs, cargadoEn: ahora, data });
+    return { data, hit: false };
+  }
+
+  /**
+   * Invalida una entrada o todo el cache.
+   * @param {string} [ruta] - Si se omite, vacía todo.
+   */
+  function invalidate(ruta) {
+    if (ruta === undefined) {
+      const n = store.size;
+      store.clear();
+      stats.invalidations += n;
+      return n;
+    }
+    if (store.delete(ruta)) stats.invalidations++;
+    return 0;
+  }
+
+  return {
+    get,
+    invalidate,
+    stats: () => ({ ...stats, size: store.size, ttlMs }),
+    _store: store, // exposed para tests
+  };
+}
+
+module.exports = {
+  crearCache,
+  DEFAULT_TTL_MS,
+};

package/scripts/validar.js

@@ -55,7 +55,7 @@ if (fs.existsSync(hooksConfigPath)) {
   verificar(hooksEnConfig.length >= 4, `hooks-config.json: ${hooksEnConfig.length} hooks definidos (mínimo 4)`);
   for (const hookName of hooksEnConfig) {
     const hc = hooksConfig.hooks[hookName];
-    const eventosValidos = ['PreToolUse', 'PostToolUse', 'Stop', 'Notification', 'SubagentStop', 'UserPromptSubmit', 'PreCompact', 'SessionStart'];
+    const eventosValidos = ['PreToolUse', 'PostToolUse', 'Stop', 'Notification', 'SubagentStart', 'SubagentStop', 'UserPromptSubmit', 'PreCompact', 'SessionStart'];
     verificar(
       eventosValidos.includes(hc.event),
       `hooks-config.json: ${hookName} tiene event válido (${hc.event})`

package/scripts/verificar-release.js

@@ -329,6 +329,17 @@ function main() {
     ? '  [OK] Gate evolución: manifiesto al día + fuente sin evolved espurio'
     : `  [FALLA] Gate evolución: ${gateEvolved.problemas.join('; ')}`);
 
+  // Gate de invariantes: frases load-bearing de manifiestos/invariantes-criticos.json
+  // presentes verbatim en sus componentes. Blocking — perder una frase en un
+  // reword rompe el contrato cross-componente en silencio.
+  const gateInvariantes = ejecutarGateInvariantes();
+  if (!gateInvariantes.ok) {
+    fallasObligatorias++;
+  }
+  console.log(gateInvariantes.ok
+    ? `  [OK] Gate invariantes: ${gateInvariantes.frasesVerificadas} frase(s) load-bearing presentes`
+    : `  [FALLA] Gate invariantes: ${gateInvariantes.problemas.join('; ')}`);
+
   if (jsonOut) {
     process.stdout.write(JSON.stringify({
       version,
@@ -343,6 +354,7 @@ function main() {
       aiisms_gate: aiismsGate,
       gate_licencias: gateLicencias,
       gate_evolved: gateEvolved,
+      gate_invariantes: gateInvariantes,
       resultados: resultados.map(({ entrada, resultado }) => ({
         archivo: entrada.archivo,
         obligatorio: entrada.obligatorio,
@@ -928,6 +940,44 @@ function ejecutarGateLicencias(baseDir = CWD) {
   }
 }
 
+/**
+ * Gate de invariantes: frases load-bearing declaradas en
+ * manifiestos/invariantes-criticos.json deben existir verbatim en sus
+ * archivos. Complementa a canonical-hashes (que detecta QUE un archivo
+ * cambió) detectando si un reword perdió UNA regla puntual del contrato
+ * cross-componente. Blocking: la fricción de actualizar el manifiesto en
+ * un reword intencional es el recordatorio de propagar el cambio.
+ *
+ * @param {string} [baseDir=CWD] - Raíz del repo (inyectable para tests).
+ * @returns {{ ok: boolean, disponible: boolean, problemas: string[], frasesVerificadas: number }}
+ */
+function ejecutarGateInvariantes(baseDir = CWD) {
+  const manifiestoPath = path.join(baseDir, 'manifiestos', 'invariantes-criticos.json');
+  let manifiesto;
+  try {
+    manifiesto = JSON.parse(fs.readFileSync(manifiestoPath, 'utf8'));
+  } catch (err) {
+    return { ok: false, disponible: false, problemas: [`manifiesto ilegible: ${err.message}`], frasesVerificadas: 0 };
+  }
+
+  const problemas = [];
+  let frasesVerificadas = 0;
+  for (const [archivo, frases] of Object.entries(manifiesto.invariantes || {})) {
+    const contenido = leerArchivoSeguro(path.join(baseDir, archivo));
+    if (contenido === null) {
+      problemas.push(`${archivo}: archivo no existe`);
+      continue;
+    }
+    for (const frase of frases) {
+      frasesVerificadas++;
+      if (!contenido.includes(frase)) {
+        problemas.push(`${archivo}: perdió la frase invariante "${frase}"`);
+      }
+    }
+  }
+  return { ok: problemas.length === 0, disponible: true, problemas, frasesVerificadas };
+}
+
 if (require.main === module) main();
 
 module.exports = {
@@ -938,4 +988,5 @@ module.exports = {
   ejecutarGateDescription,
   ejecutarGateLicencias,
   ejecutarGateEvolved,
+  ejecutarGateInvariantes,
 };