@saulwade/swl-ses 1.0.0

package/hooks/lib/agent-comms.js

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * lib/agent-comms.js
+ * Agent Communications — Protocolo de comunicacion entre agentes SWL.
+ *
+ * Define tipos de mensaje estructurados para coordinacion de agentes:
+ * - TaskHandoff: delegar trabajo con contexto
+ * - Query/Response: intercambio de informacion
+ * - Completed: notificacion de completitud
+ * - Conflict: deteccion de ediciones concurrentes
+ *
+ * Los mensajes se persisten en .planning/comms/ como JSON.
+ *
+ * API publica:
+ *   MESSAGE_TYPES                                  → constantes de tipo
+ *   enviarMensaje(baseDir, mensaje)                → { id, type, from, to, ... }
+ *   leerMensajesPendientes(baseDir, agentName)     → object[]
+ *   marcarProcesado(baseDir, messageId)            → boolean
+ *   detectarConflicto(baseDir, agentName, file)    → object|null
+ *   limpiarMensajes(baseDir, horasMaximas?)        → number
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { atomicWriteJSON } = require('./atomic-write');
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+const COMMS_DIR = '.planning/comms';
+
+/** Ventana de tiempo para detectar conflictos de edicion concurrente (ms). */
+const VENTANA_CONFLICTO_MS = 5 * 60 * 1000;
+
+/** Tipos de mensaje validos del protocolo SWL inter-agent. */
+const MESSAGE_TYPES = {
+  TASK_HANDOFF: 'task_handoff',
+  QUERY:        'query',
+  RESPONSE:     'response',
+  COMPLETED:    'completed',
+  CONFLICT:     'conflict',
+};
+
+// ---------------------------------------------------------------------------
+// Utilidades internas
+// ---------------------------------------------------------------------------
+
+/**
+ * Asegura que el directorio de comunicaciones exista.
+ *
+ * @param {string} baseDir - Directorio raiz del proyecto.
+ * @returns {string} Ruta absoluta al directorio de comms.
+ */
+function ensureCommsDir(baseDir) {
+  const dir = path.join(baseDir, COMMS_DIR);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  return dir;
+}
+
+/**
+ * Genera un ID de mensaje unico basado en timestamp y aleatoriedad.
+ *
+ * Formato: msg-{timestamp_base36}-{random_4chars}
+ * Ejemplo: msg-lxyz1a-k9mq
+ *
+ * @returns {string}
+ */
+function generarMessageId() {
+  const ts   = Date.now().toString(36);
+  const rand = Math.random().toString(36).slice(2, 6);
+  return `msg-${ts}-${rand}`;
+}
+
+/**
+ * Lee y parsea un archivo JSON de mensaje de forma segura.
+ * Retorna null si el archivo no existe o tiene JSON invalido.
+ *
+ * @param {string} filePath - Ruta absoluta al archivo .json.
+ * @returns {object|null}
+ */
+function leerMensajeSeguro(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// API publica
+// ---------------------------------------------------------------------------
+
+/**
+ * Envia un mensaje entre agentes persistiendolo en .planning/comms/.
+ *
+ * @param {string} baseDir - Directorio raiz del proyecto.
+ * @param {object} opts
+ * @param {string} opts.type         - Uno de MESSAGE_TYPES (requerido).
+ * @param {string} [opts.from]       - Nombre del agente emisor.
+ * @param {string} [opts.to]         - Nombre del destinatario o 'broadcast'.
+ * @param {object} [opts.payload]    - Cuerpo del mensaje, estructura libre.
+ * @param {string[]} [opts.contextFiles] - Archivos relevantes al mensaje.
+ * @returns {object} Mensaje completo con id, timestamp y status 'pending'.
+ */
+function enviarMensaje(baseDir, { type, from, to, payload, contextFiles } = {}) {
+  const dir = ensureCommsDir(baseDir);
+  const id  = generarMessageId();
+
+  const msg = {
+    id,
+    type,
+    from:         from         || 'unknown',
+    to:           to           || 'broadcast',
+    payload:      payload      || {},
+    contextFiles: contextFiles || [],
+    timestamp:    new Date().toISOString(),
+    status:       'pending',
+  };
+
+  const filePath = path.join(dir, `${id}.json`);
+  atomicWriteJSON(filePath, msg);
+  return msg;
+}
+
+/**
+ * Lee todos los mensajes pendientes dirigidos a un agente especifico,
+ * incluyendo mensajes broadcast.
+ *
+ * @param {string} baseDir    - Directorio raiz del proyecto.
+ * @param {string} agentName  - Nombre del agente destinatario.
+ * @returns {object[]} Mensajes pendientes ordenados por timestamp ascendente.
+ */
+function leerMensajesPendientes(baseDir, agentName) {
+  const dir = path.join(baseDir, COMMS_DIR);
+  if (!fs.existsSync(dir)) return [];
+
+  return fs.readdirSync(dir)
+    .filter(f => f.startsWith('msg-') && f.endsWith('.json'))
+    .map(f => leerMensajeSeguro(path.join(dir, f)))
+    .filter(m =>
+      m !== null &&
+      m.status === 'pending' &&
+      (m.to === agentName || m.to === 'broadcast'),
+    )
+    .sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
+}
+
+/**
+ * Marca un mensaje como procesado, registrando la hora de procesamiento.
+ *
+ * @param {string} baseDir   - Directorio raiz del proyecto.
+ * @param {string} messageId - ID del mensaje a marcar.
+ * @returns {boolean} true si el mensaje existia y fue actualizado, false si no.
+ */
+function marcarProcesado(baseDir, messageId) {
+  const filePath = path.join(baseDir, COMMS_DIR, `${messageId}.json`);
+  if (!fs.existsSync(filePath)) return false;
+
+  const msg = leerMensajeSeguro(filePath);
+  if (!msg) return false;
+
+  msg.status      = 'processed';
+  msg.processedAt = new Date().toISOString();
+  atomicWriteJSON(filePath, msg);
+  return true;
+}
+
+/**
+ * Detecta conflictos de edicion concurrente: verifica si algun otro agente
+ * referencio el mismo archivo en un mensaje reciente (ventana de 5 minutos).
+ *
+ * @param {string} baseDir    - Directorio raiz del proyecto.
+ * @param {string} agentName  - Nombre del agente que quiere modificar el archivo.
+ * @param {string} filePath   - Ruta del archivo que se desea modificar.
+ * @returns {object|null}
+ *   Objeto de conflicto si se detecta:
+ *     { conflicto, agenteConflicto, archivo, mensajeOriginal, timestamp }
+ *   null si no hay conflicto.
+ */
+function detectarConflicto(baseDir, agentName, filePath) {
+  const dir = path.join(baseDir, COMMS_DIR);
+  if (!fs.existsSync(dir)) return null;
+
+  const ahora = Date.now();
+
+  const mensajes = fs.readdirSync(dir)
+    .filter(f => f.startsWith('msg-') && f.endsWith('.json'))
+    .map(f => leerMensajeSeguro(path.join(dir, f)))
+    .filter(Boolean);
+
+  for (const msg of mensajes) {
+    // Ignorar mensajes del propio agente
+    if (msg.from === agentName) continue;
+
+    // Ignorar mensajes fuera de la ventana de deteccion
+    if (ahora - new Date(msg.timestamp).getTime() > VENTANA_CONFLICTO_MS) continue;
+
+    const archivos = msg.contextFiles || [];
+    if (archivos.includes(filePath)) {
+      return {
+        conflicto:         true,
+        agenteConflicto:   msg.from,
+        archivo:           filePath,
+        mensajeOriginal:   msg.id,
+        timestamp:         msg.timestamp,
+      };
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Elimina mensajes ya procesados cuya antiguedad supera el limite indicado.
+ * Los mensajes pendientes nunca se eliminan con esta funcion.
+ *
+ * @param {string} baseDir          - Directorio raiz del proyecto.
+ * @param {number} [horasMaximas=24] - Edad maxima en horas para mensajes procesados.
+ * @returns {number} Cantidad de mensajes eliminados.
+ */
+function limpiarMensajes(baseDir, horasMaximas = 24) {
+  const dir = path.join(baseDir, COMMS_DIR);
+  if (!fs.existsSync(dir)) return 0;
+
+  const ahora  = Date.now();
+  const limite = horasMaximas * 60 * 60 * 1000;
+  let eliminados = 0;
+
+  for (const f of fs.readdirSync(dir)) {
+    if (!f.startsWith('msg-') || !f.endsWith('.json')) continue;
+
+    const msg = leerMensajeSeguro(path.join(dir, f));
+    if (!msg) continue;
+
+    const esViejo = ahora - new Date(msg.timestamp).getTime() > limite;
+    if (msg.status === 'processed' && esViejo) {
+      fs.unlinkSync(path.join(dir, f));
+      eliminados++;
+    }
+  }
+
+  return eliminados;
+}
+
+// ---------------------------------------------------------------------------
+// Exportaciones
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  MESSAGE_TYPES,
+  enviarMensaje,
+  leerMensajesPendientes,
+  marcarProcesado,
+  detectarConflicto,
+  limpiarMensajes,
+  COMMS_DIR,
+};

package/hooks/lib/agent-issue-codes.js

@@ -0,0 +1,284 @@
+'use strict';
+
+/**
+ * Taxonomía de códigos de issue para escaneo de agentes y skills.
+ *
+ * Portado desde agent-scan-main / docs/issue-codes.md (Apache 2.0).
+ * Cubre amenazas en servidores MCP, skills de agentes y flujos tóxicos.
+ *
+ * Uso en hooks de escaneo:
+ *   const { ISSUE_CODES, obtenerCodigo, formatearHallazgo } = require('./agent-issue-codes');
+ *   const info = obtenerCodigo('W008');
+ *   // → { codigo: 'W008', severidad: 'warning', titulo: 'Secretos hardcodeados en skill', ... }
+ *
+ * @module hooks/lib/agent-issue-codes
+ */
+
+// ---------------------------------------------------------------------------
+// Constante principal
+// ---------------------------------------------------------------------------
+
+/**
+ * Catálogo completo de códigos de issue estandarizados.
+ * Congelado para prevenir mutaciones en tiempo de ejecución.
+ *
+ * Severidades usadas:
+ *   - 'critical' → bloquear inmediatamente, riesgo de supply chain attack
+ *   - 'error'    → problema grave, acción requerida
+ *   - 'warning'  → patrón riesgoso, investigar antes de continuar
+ *   - 'info'     → observación, baja prioridad
+ *
+ * @type {Readonly<Array<{codigo: string, severidad: string, titulo: string, descripcion: string}>>}
+ */
+const ISSUE_CODES = Object.freeze([
+  // -------------------------------------------------------------------------
+  // Servidores MCP comprometidos (E001, E002, W001)
+  // -------------------------------------------------------------------------
+  {
+    codigo:      'E001',
+    severidad:   'critical',
+    titulo:      'Inyección de prompt en descripción de herramienta MCP',
+    descripcion: 'Se detectó una inyección de prompt en la descripción de una herramienta ' +
+                 'del servidor MCP. Ataque de envenenamiento de herramientas (tool poisoning): ' +
+                 'instrucciones adversariales ocultas que manipulan el comportamiento del agente. ' +
+                 'Desactivar la herramienta de inmediato.',
+  },
+  {
+    codigo:      'E002',
+    severidad:   'error',
+    titulo:      'Referencia entre servidores MCP (tool shadowing)',
+    descripcion: 'Una herramienta de un servidor MCP referencia una herramienta de otro servidor. ' +
+                 'Los servidores MCP deben ser autocontenidos. Cuando la descripción de una ' +
+                 'herramienta menciona herramientas de otro servidor, puede envenenar el ' +
+                 'comportamiento de esas herramientas de confianza (ataque de shadowing).',
+  },
+  {
+    codigo:      'W001',
+    severidad:   'warning',
+    titulo:      'Palabras sospechosas en descripción de herramienta MCP',
+    descripcion: 'La descripción de la herramienta contiene palabras frecuentes en ataques ' +
+                 'de inyección: "important", "crucial", "critical", "ignore", "override", ' +
+                 '"bypass". Su presencia aislada no confirma intención maliciosa, pero amerita ' +
+                 'investigación, especialmente combinada con descripciones inusuales.',
+  },
+
+  // -------------------------------------------------------------------------
+  // Flujos tóxicos (W015–W020)
+  // -------------------------------------------------------------------------
+  {
+    codigo:      'W015',
+    severidad:   'warning',
+    titulo:      'Contenido no confiable expuesto al agente (alta confianza)',
+    descripcion: 'El servidor MCP expone al agente contenido potencialmente no confiable ' +
+                 'de fuentes externas sin sanitización adecuada. Riesgo de inyección indirecta ' +
+                 'de prompt. Detección de alta confianza: herramientas que claramente obtienen ' +
+                 'datos de fuentes públicas o controladas por el usuario.',
+  },
+  {
+    codigo:      'W016',
+    severidad:   'warning',
+    titulo:      'Posible contenido no confiable expuesto al agente (baja confianza)',
+    descripcion: 'Detección de baja confianza de exposición potencial a contenido de terceros. ' +
+                 'El servidor MCP puede exponer datos externos, pero el riesgo es menos ' +
+                 'certero. Verificar si la herramienta valida y sanitiza datos externos.',
+  },
+  {
+    codigo:      'W017',
+    severidad:   'warning',
+    titulo:      'Exposición de datos sensibles (alta sensibilidad)',
+    descripcion: 'El servidor MCP integra y recupera información altamente sensible: ' +
+                 'comunicaciones personales, registros financieros o bóvedas de credenciales. ' +
+                 'Cargar datos privados en el contexto del agente amplifica el riesgo de ' +
+                 'exfiltración ante inyecciones de prompt o vulnerabilidades de logging.',
+  },
+  {
+    codigo:      'W018',
+    severidad:   'warning',
+    titulo:      'Exposición de datos del espacio de trabajo',
+    descripcion: 'El servidor MCP otorga acceso a archivos locales, código del proyecto ' +
+                 'o almacenes de datos del usuario. Menos sensible que W017, pero introduce ' +
+                 'riesgo de fuga de propiedad intelectual o detalles internos del proyecto.',
+  },
+  {
+    codigo:      'W019',
+    severidad:   'warning',
+    titulo:      'Capacidades destructivas (infraestructura compartida)',
+    descripcion: 'El servidor MCP permite modificar infraestructura compartida, ejecutar ' +
+                 'comandos de sistema arbitrarios o afectar a otros usuarios. Incluye: ' +
+                 'comandos shell, interacción con el navegador autenticado, modificación de ' +
+                 'SaaS compartido o transacciones financieras irreversibles.',
+  },
+  {
+    codigo:      'W020',
+    severidad:   'warning',
+    titulo:      'Capacidades destructivas locales',
+    descripcion: 'El servidor MCP permite modificar o eliminar archivos locales, alterar ' +
+                 'configuraciones personales o cambiar el estado del entorno de un solo usuario. ' +
+                 'Radio de explosión contenido, pero permite pérdida permanente de datos locales.',
+  },
+
+  // -------------------------------------------------------------------------
+  // Skills comprometidas (E004, E005, E006)
+  // -------------------------------------------------------------------------
+  {
+    codigo:      'E004',
+    severidad:   'critical',
+    titulo:      'Inyección de prompt en skill',
+    descripcion: 'Se detectó una inyección de prompt en las instrucciones del skill. ' +
+                 'El skill contiene instrucciones ocultas o engañosas fuera de su propósito ' +
+                 'declarado que intentan anular las directrices de seguridad del agente.',
+  },
+  {
+    codigo:      'E005',
+    severidad:   'critical',
+    titulo:      'URL de descarga sospechosa en skill',
+    descripcion: 'Se detectó una URL sospechosa en las instrucciones del skill que podría ' +
+                 'llevar al agente a descargar y ejecutar scripts o binarios maliciosos. ' +
+                 'Incluye: ejecutables de fuentes no confiables, typosquatting de paquetes ' +
+                 'oficiales, acortadores de URL o hosting personal de archivos.',
+  },
+  {
+    codigo:      'E006',
+    severidad:   'critical',
+    titulo:      'Patrones de código malicioso en skill',
+    descripcion: 'Se detectaron patrones de alto riesgo en el contenido del skill: ' +
+                 'exfiltración de datos, puertas traseras, ejecución remota de código, ' +
+                 'robo de credenciales, ataques a la cadena de suministro u ofuscación.',
+  },
+
+  // -------------------------------------------------------------------------
+  // Skills vulnerables (W007–W014)
+  // -------------------------------------------------------------------------
+  {
+    codigo:      'W007',
+    severidad:   'warning',
+    titulo:      'Manejo inseguro de credenciales en skill',
+    descripcion: 'El skill maneja credenciales de forma insegura al requerir que el agente ' +
+                 'incluya valores secretos literales en su output generado. Expone credenciales ' +
+                 'en el contexto y el historial de conversación del agente.',
+  },
+  {
+    codigo:      'W008',
+    severidad:   'warning',
+    titulo:      'Secretos hardcodeados en skill',
+    descripcion: 'Se detectaron credenciales sensibles embebidas directamente en el contenido ' +
+                 'del skill: claves de API, tokens de acceso, claves privadas o secretos de ' +
+                 'servicio. Los secretos nunca deben estar hardcodeados en texto plano.',
+  },
+  {
+    codigo:      'W009',
+    severidad:   'warning',
+    titulo:      'Capacidad de ejecución financiera directa',
+    descripcion: 'El skill está diseñado para operaciones financieras directas: otorga al ' +
+                 'agente capacidad de mover dinero o ejecutar transacciones financieras — ' +
+                 'procesamiento de pagos, operaciones con criptomonedas, integraciones ' +
+                 'bancarias o ejecución de órdenes de mercado.',
+  },
+  {
+    codigo:      'W011',
+    severidad:   'warning',
+    titulo:      'Exposición a contenido de terceros no confiable',
+    descripcion: 'El skill expone al agente a contenido generado por usuarios de fuentes ' +
+                 'públicas de terceros, creando riesgo de inyección indirecta de prompt. ' +
+                 'Incluye: navegación de URLs arbitrarias, lectura de redes sociales o ' +
+                 'análisis de contenido de sitios desconocidos.',
+  },
+  {
+    codigo:      'W012',
+    severidad:   'warning',
+    titulo:      'Dependencia externa no verificable',
+    descripcion: 'El skill obtiene instrucciones o código desde una URL externa en tiempo ' +
+                 'de ejecución, y el contenido obtenido controla directamente los prompts ' +
+                 'del agente o ejecuta código. Permite que la fuente externa modifique el ' +
+                 'comportamiento del agente sin cambios en el skill (riesgo RCE remoto).',
+  },
+  {
+    codigo:      'W013',
+    severidad:   'warning',
+    titulo:      'Modificación de servicios del sistema',
+    descripcion: 'El skill instruye al agente a comprometer la seguridad o integridad de ' +
+                 'la máquina del usuario modificando servicios o configuraciones a nivel de ' +
+                 'sistema: obtener privilegios elevados, alterar scripts de inicio o cambiar ' +
+                 'configuraciones globales. Puede ser legítimo en casos raros — investigar.',
+  },
+  {
+    codigo:      'W014',
+    severidad:   'info',
+    titulo:      'Archivo SKILL.md faltante',
+    descripcion: 'El skill no tiene el archivo SKILL.md requerido. Este archivo provee ' +
+                 'metadatos esenciales y documentación sobre el propósito, capacidades y ' +
+                 'consideraciones de seguridad del skill. Sin él, el análisis de seguridad ' +
+                 'es incompleto y los usuarios no pueden evaluar el skill antes de usarlo.',
+  },
+]);
+
+// ---------------------------------------------------------------------------
+// Funciones auxiliares
+// ---------------------------------------------------------------------------
+
+/**
+ * Mapa de acceso rápido por código (O(1)).
+ * Construido una sola vez al cargar el módulo.
+ *
+ * @type {Map<string, object>}
+ */
+const _MAPA_CODIGOS = new Map(ISSUE_CODES.map(issue => [issue.codigo, issue]));
+
+/**
+ * Busca y devuelve la entrada completa de un código de issue.
+ *
+ * @param {string} codigo - Código a buscar (ej. 'W008', 'E001').
+ * @returns {{ codigo: string, severidad: string, titulo: string, descripcion: string }|null}
+ *          El objeto de issue, o null si el código no existe.
+ *
+ * @example
+ * obtenerCodigo('W008')
+ * // → { codigo: 'W008', severidad: 'warning', titulo: 'Secretos hardcodeados en skill', ... }
+ *
+ * obtenerCodigo('X999') // → null
+ */
+function obtenerCodigo(codigo) {
+  return _MAPA_CODIGOS.get(String(codigo || '')) || null;
+}
+
+/**
+ * Genera una línea de hallazgo legible para reportes de escaneo.
+ * Incluye el código, la severidad, la ubicación y el detalle contextual.
+ *
+ * @param {object} params - Datos del hallazgo.
+ * @param {string} params.codigo    - Código de issue (ej. 'W008').
+ * @param {string} [params.archivo] - Ruta del archivo donde se detectó.
+ * @param {number} [params.linea]   - Número de línea del hallazgo.
+ * @param {string} [params.detalle] - Información adicional específica del hallazgo.
+ * @returns {string} Línea formateada para incluir en reportes.
+ *
+ * @example
+ * formatearHallazgo({ codigo: 'W008', archivo: 'habilidades/mi-skill.md', linea: 15, detalle: 'API key detectada' })
+ * // → '[W008] warning — Secretos hardcodeados en skill\n  Archivo: habilidades/mi-skill.md:15\n  Detalle: API key detectada'
+ */
+function formatearHallazgo({ codigo, archivo, linea, detalle } = {}) {
+  const issue = obtenerCodigo(codigo);
+
+  const encabezado = issue
+    ? `[${issue.codigo}] ${issue.severidad} — ${issue.titulo}`
+    : `[${String(codigo || 'DESCONOCIDO')}] — código no reconocido`;
+
+  const partes = [encabezado];
+
+  if (archivo) {
+    const ubicacion = linea ? `${archivo}:${linea}` : archivo;
+    partes.push(`  Archivo: ${ubicacion}`);
+  }
+
+  if (detalle) {
+    partes.push(`  Detalle: ${String(detalle)}`);
+  }
+
+  return partes.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = { ISSUE_CODES, obtenerCodigo, formatearHallazgo };