@saulwade/swl-ses 2.6.0 → 2.8.0

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,
+};