@saulwade/swl-ses 1.3.8 → 1.4.0

package/gateway/lib/event-channel.js

@@ -0,0 +1,191 @@
+'use strict';
+
+/**
+ * event-channel.js
+ *
+ * Pub/sub event channel para CommandRelay y otros componentes del gateway.
+ *
+ * Patrón adaptado de `temp/obsidian-agent-client-master/src/acp/acp-handler.ts`
+ * (Set<listeners> con callback unsubscribe). Diferencias:
+ *   - Zero-deps Node.js (sin RxJS, sin EventEmitter de node — Set nativo).
+ *   - Backward compat: si no hay listeners, comportamiento idéntico al actual.
+ *   - Tipos de evento explícitos para evitar typos.
+ *
+ * Casos de uso en SWL:
+ *   - CommandRelay emite eventos al recibir/aceptar/rechazar/procesar comandos.
+ *   - Múltiples adaptadores (Telegram, Discord) pueden suscribirse simultáneamente.
+ *   - El consumidor /swl:inbox puede mostrar progreso sin polling.
+ *
+ * Uso:
+ *   const channel = new EventChannel();
+ *   const off = channel.on('cmd:queued', (event) => console.log(event));
+ *   channel.emit({ type: 'cmd:queued', commandId: 'cmd-abc', userId: '123' });
+ *   off();  // unsubscribe
+ *
+ * @module gateway/lib/event-channel
+ */
+
+// ── tipos de evento ──────────────────────────────────────────────────────────
+
+/**
+ * Tipos válidos de evento. Se usan strings para serializar fácilmente
+ * a JSONL si se requiere persistencia (no obligatorio).
+ */
+const EVENTS = Object.freeze({
+  // Lifecycle de comandos en CommandRelay
+  CMD_RECEIVED:  'cmd:received',   // mensaje llegó al relay
+  CMD_REJECTED:  'cmd:rejected',   // rechazado por validación (auth/rate/dedup)
+  CMD_QUEUED:    'cmd:queued',     // encolado en .planning/inbox/
+  CMD_PROCESSED: 'cmd:processed',  // marcado como procesado por consumidor
+
+  // Lifecycle de notificaciones
+  NOTIFICATION_SENT:   'notification:sent',
+  NOTIFICATION_FAILED: 'notification:failed',
+});
+
+// ── implementación ────────────────────────────────────────────────────────────
+
+/**
+ * Canal de eventos pub/sub con escucha por tipo o wildcard.
+ *
+ * Mantiene dos estructuras:
+ *   - listenersByType: Map<eventType, Set<callback>>
+ *   - wildcardListeners: Set<callback>  (escuchan TODOS los eventos)
+ *
+ * Una excepción en un listener NO interrumpe la propagación a los demás —
+ * patrón de aislamiento del mismo origen (acp-handler.ts:47-50).
+ */
+class EventChannel {
+  constructor() {
+    this.listenersByType = new Map();
+    this.wildcardListeners = new Set();
+    this.errorHandler = null;  // opcional: callback para errores en listeners
+  }
+
+  /**
+   * Suscribe un listener a un tipo de evento (o '*' para todos).
+   *
+   * @param {string} eventType - tipo de evento o '*'
+   * @param {function} callback - recibe el objeto event
+   * @returns {function} función de unsubscribe (idempotente)
+   */
+  on(eventType, callback) {
+    if (typeof callback !== 'function') {
+      throw new TypeError('callback debe ser función');
+    }
+    if (typeof eventType !== 'string' || !eventType) {
+      throw new TypeError('eventType debe ser string no vacío');
+    }
+
+    if (eventType === '*') {
+      this.wildcardListeners.add(callback);
+      return () => this.wildcardListeners.delete(callback);
+    }
+
+    if (!this.listenersByType.has(eventType)) {
+      this.listenersByType.set(eventType, new Set());
+    }
+    const set = this.listenersByType.get(eventType);
+    set.add(callback);
+    return () => set.delete(callback);
+  }
+
+  /**
+   * Suscribe un listener que se invoca UNA sola vez y luego se desuscribe.
+   */
+  once(eventType, callback) {
+    const off = this.on(eventType, (event) => {
+      off();
+      callback(event);
+    });
+    return off;
+  }
+
+  /**
+   * Emite un evento a todos los listeners suscriptos al tipo + wildcards.
+   * El evento debe tener al menos `type`. Se enriquece con `ts` (ISO).
+   *
+   * @param {object} event - objeto con `type` y datos arbitrarios
+   * @returns {number} cantidad de listeners notificados
+   */
+  emit(event) {
+    if (!event || typeof event !== 'object') {
+      throw new TypeError('event debe ser objeto');
+    }
+    if (typeof event.type !== 'string' || !event.type) {
+      throw new TypeError('event.type es obligatorio');
+    }
+
+    const enriched = { ts: new Date().toISOString(), ...event };
+    let notified = 0;
+
+    // Listeners específicos del tipo
+    const typedSet = this.listenersByType.get(enriched.type);
+    if (typedSet) {
+      for (const cb of typedSet) {
+        notified++;
+        this._safeInvoke(cb, enriched);
+      }
+    }
+
+    // Listeners wildcard
+    for (const cb of this.wildcardListeners) {
+      notified++;
+      this._safeInvoke(cb, enriched);
+    }
+
+    return notified;
+  }
+
+  /**
+   * Cuenta de listeners para un tipo (o total si no se pasa tipo).
+   */
+  listenerCount(eventType) {
+    if (eventType == null) {
+      let total = this.wildcardListeners.size;
+      for (const set of this.listenersByType.values()) total += set.size;
+      return total;
+    }
+    if (eventType === '*') return this.wildcardListeners.size;
+    const set = this.listenersByType.get(eventType);
+    return (set ? set.size : 0) + this.wildcardListeners.size;
+  }
+
+  /**
+   * Limpia todos los listeners. Útil para tests.
+   */
+  clear() {
+    this.listenersByType.clear();
+    this.wildcardListeners.clear();
+  }
+
+  /**
+   * Asigna un handler para errores en listeners.
+   * Si no se asigna, los errores se silencian (no rompen la propagación).
+   */
+  onError(handler) {
+    if (typeof handler !== 'function') {
+      throw new TypeError('handler debe ser función');
+    }
+    this.errorHandler = handler;
+  }
+
+  // ── internos ────────────────────────────────────────────────────────────────
+
+  _safeInvoke(cb, event) {
+    try {
+      cb(event);
+    } catch (err) {
+      if (this.errorHandler) {
+        try { this.errorHandler(err, event); } catch (_) { /* silencioso */ }
+      }
+    }
+  }
+}
+
+// ── exports ───────────────────────────────────────────────────────────────────
+
+module.exports = {
+  EventChannel,
+  EVENTS,
+};

package/gateway/session.js

@@ -0,0 +1,131 @@
+'use strict';
+
+/**
+ * Gateway Session — Gestión de sesiones por plataforma.
+ *
+ * Mantiene un mapeo entre usuarios de plataformas externas y sesiones SWL.
+ * Permite que un usuario de Telegram tenga una "sesión" persistente con el gateway.
+ *
+ * Persistencia en .planning/gateway-sessions.json.
+ *
+ * @module gateway/session
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { atomicWriteJSON } = require('../hooks/lib/atomic-write');
+
+// ---------------------------------------------------------------------------
+// Constantes
+// ---------------------------------------------------------------------------
+
+const SESSIONS_FILE    = '.planning/gateway-sessions.json';
+const INACTIVITY_MS    = 30 * 60 * 1000; // 30 minutos
+const MAX_SESSIONS     = 100;
+
+// ---------------------------------------------------------------------------
+// API
+// ---------------------------------------------------------------------------
+
+/**
+ * Obtiene o crea una sesión para un usuario de plataforma.
+ *
+ * @param {string} baseDir
+ * @param {string} platformUserId - Identificador único: "telegram:12345"
+ * @returns {object} Sesión con lastActivity actualizada.
+ */
+function getOrCreateSession(baseDir, platformUserId) {
+  const sessions = _loadSessions(baseDir);
+  const now = Date.now();
+
+  let session = sessions[platformUserId];
+
+  if (session) {
+    // Verificar timeout de inactividad
+    if (now - session.lastActivity > INACTIVITY_MS) {
+      // Sesión expirada — crear nueva
+      session = _newSession(platformUserId);
+    } else {
+      session.lastActivity = now;
+    }
+  } else {
+    session = _newSession(platformUserId);
+  }
+
+  sessions[platformUserId] = session;
+
+  // Limitar número total de sesiones (FIFO)
+  const keys = Object.keys(sessions);
+  if (keys.length > MAX_SESSIONS) {
+    // Eliminar las más antiguas
+    const sorted = keys.sort((a, b) => sessions[a].lastActivity - sessions[b].lastActivity);
+    for (let i = 0; i < keys.length - MAX_SESSIONS; i++) {
+      delete sessions[sorted[i]];
+    }
+  }
+
+  _saveSessions(baseDir, sessions);
+  return session;
+}
+
+/**
+ * Lista todas las sesiones activas (no expiradas).
+ *
+ * @param {string} baseDir
+ * @returns {object[]}
+ */
+function listActiveSessions(baseDir) {
+  const sessions = _loadSessions(baseDir);
+  const now = Date.now();
+
+  return Object.entries(sessions)
+    .filter(([, s]) => now - s.lastActivity <= INACTIVITY_MS)
+    .map(([userId, s]) => ({ userId, ...s }));
+}
+
+/**
+ * Invalida una sesión específica.
+ *
+ * @param {string} baseDir
+ * @param {string} platformUserId
+ */
+function invalidateSession(baseDir, platformUserId) {
+  const sessions = _loadSessions(baseDir);
+  delete sessions[platformUserId];
+  _saveSessions(baseDir, sessions);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers internos
+// ---------------------------------------------------------------------------
+
+function _newSession(platformUserId) {
+  const [platform, userId] = platformUserId.split(':');
+  return {
+    id: `gw-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`,
+    platform,
+    userId,
+    createdAt: Date.now(),
+    lastActivity: Date.now(),
+    context: {},
+  };
+}
+
+function _loadSessions(baseDir) {
+  const p = path.join(baseDir, SESSIONS_FILE);
+  try {
+    if (!fs.existsSync(p)) return {};
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (_) {
+    return {};
+  }
+}
+
+function _saveSessions(baseDir, sessions) {
+  const dir = path.dirname(path.join(baseDir, SESSIONS_FILE));
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  atomicWriteJSON(path.join(baseDir, SESSIONS_FILE), sessions);
+}
+
+module.exports = { getOrCreateSession, listActiveSessions, invalidateSession };

package/gateway/webhook-server.js

@@ -0,0 +1,324 @@
+'use strict';
+
+/**
+ * webhook-server.js — Servidor HTTP local para webhooks entrantes firmados.
+ *
+ * Orquesta las tres librerías de las fases anteriores:
+ *
+ *   webhook-verify   → valida HMAC SHA-256 (GitHub) o Bearer (generic)
+ *   rate-limit-ip    → token bucket per-IP
+ *   webhook-dedup    → idempotencia por event-id en ledger JSONL
+ *
+ * Endpoints:
+ *
+ *   POST /webhooks/github   — requiere X-Hub-Signature-256 + secret
+ *   POST /webhooks/generic  — requiere Authorization: Bearer + secret
+ *   GET  /healthz           — liveness (sin auth)
+ *   *                       — 404
+ *
+ * Pipeline por request:
+ *
+ *   1. IP allowlist (si está configurada)
+ *   2. Rate limit per-IP (barato; aborta antes de HMAC costoso)
+ *   3. Lectura de body con cap de tamaño
+ *   4. HMAC verify (GitHub) o Bearer verify (generic)
+ *   5. Extracción de event-id (X-GitHub-Delivery o X-Request-ID o hash del body)
+ *   6. Dedup (rechazo idempotente: 200 OK pero no escribe)
+ *   7. Escritura a .planning/inbox/cmd-*.json (schema compatible con /swl:inbox)
+ *
+ * Diseño:
+ *
+ *   - `http` nativo de Node, sin Express ni Fastify (zero-deps).
+ *   - Función factory `crearServidor(deps)` que retorna http.Server sin
+ *     arrancar. El bootstrap CLI (Fase 4) llama `.listen()`. Esto permite
+ *     tests con puerto efímero `0` y dependencias mock.
+ *   - Configuración 100 % vía objeto `deps` inyectado — sin lectura directa
+ *     de process.env (eso lo hace el bootstrap CLI).
+ *   - Bind por defecto `127.0.0.1` (ADR-0017 decisión #1). Cambiar requiere
+ *     intencionalidad explícita en el bootstrap.
+ *
+ * @module gateway/webhook-server
+ */
+
+const http = require('http');
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const { verifyGithubSignature, verifyBearer } = require('../hooks/lib/webhook-verify');
+
+const HEADER_GITHUB_SIG = 'x-hub-signature-256';
+const HEADER_GITHUB_DELIVERY = 'x-hub-delivery';
+const HEADER_GITHUB_DELIVERY_ALT = 'x-github-delivery';
+const HEADER_GITHUB_EVENT = 'x-github-event';
+const HEADER_AUTHORIZATION = 'authorization';
+const HEADER_REQUEST_ID = 'x-request-id';
+
+/**
+ * Crea un servidor HTTP listo para arrancar con `.listen()`.
+ *
+ * @param {object} deps Dependencias inyectadas.
+ * @param {string} deps.inboxDir Ruta absoluta al directorio inbox.
+ * @param {object} deps.dedup Instancia de WebhookDedup.
+ * @param {object} deps.rateLimiter Instancia de RateLimiterIP.
+ * @param {string|null} deps.githubSecret Secreto HMAC (null = endpoint deshabilitado).
+ * @param {string|null} deps.bearerSecret Token Bearer (null = endpoint deshabilitado).
+ * @param {number} deps.maxPayloadBytes Tope de tamaño del body.
+ * @param {Array<string>|null} deps.allowIps Lista de IPs permitidas (null = todas).
+ * @param {function} [deps.logger] Función de logging (default: console.error).
+ * @returns {http.Server}
+ */
+function crearServidor(deps) {
+  validarDeps(deps);
+  const logger = deps.logger || ((nivel, msg, extra) => {
+    const linea = JSON.stringify({ nivel, msg, ...(extra || {}), ts: new Date().toISOString() });
+    if (nivel === 'error' || nivel === 'warn') console.error(linea);
+    else console.log(linea);
+  });
+
+  const server = http.createServer((req, res) => {
+    manejarRequest(req, res, deps, logger).catch(err => {
+      logger('error', 'manejarRequest threw', { err: err.message });
+      enviarRespuesta(res, 500, { error: 'internal-error' });
+    });
+  });
+
+  return server;
+}
+
+async function manejarRequest(req, res, deps, logger) {
+  const url = req.url || '';
+  const metodo = req.method || 'GET';
+  const ip = obtenerIp(req);
+
+  // 1. Healthz (sin auth, sin rate limit)
+  if (metodo === 'GET' && url === '/healthz') {
+    return enviarRespuesta(res, 200, { status: 'ok' });
+  }
+
+  // 2. Solo POST para endpoints de webhook
+  if (metodo !== 'POST') {
+    return enviarRespuesta(res, 404, { error: 'not-found' });
+  }
+
+  // 3. Path conocido
+  const proveedor = identificarProveedor(url);
+  if (!proveedor) {
+    return enviarRespuesta(res, 404, { error: 'not-found' });
+  }
+
+  // 4. IP allowlist
+  if (deps.allowIps && deps.allowIps.length > 0 && !ipPermitida(ip, deps.allowIps)) {
+    logger('warn', 'ip-blocked', { ip, url });
+    return enviarRespuesta(res, 403, { error: 'forbidden' });
+  }
+
+  // 5. Rate limit
+  if (!deps.rateLimiter.permite(ip)) {
+    logger('warn', 'rate-limit', { ip, url });
+    return enviarRespuesta(res, 429, { error: 'rate-limit-exceeded' });
+  }
+
+  // 6. Endpoint habilitado (secreto configurado)
+  const secretoRequerido = proveedor === 'github' ? deps.githubSecret : deps.bearerSecret;
+  if (!secretoRequerido) {
+    logger('warn', 'endpoint-disabled', { proveedor });
+    return enviarRespuesta(res, 404, { error: 'not-found' });
+  }
+
+  // 7. Leer body con cap
+  let body;
+  try {
+    body = await leerBody(req, deps.maxPayloadBytes);
+  } catch (err) {
+    if (err.code === 'PAYLOAD_TOO_LARGE') {
+      return enviarRespuesta(res, 413, { error: 'payload-too-large' });
+    }
+    logger('error', 'read-body-error', { err: err.message });
+    return enviarRespuesta(res, 400, { error: 'bad-request' });
+  }
+
+  // 8. Verify firma
+  const autorizado = proveedor === 'github'
+    ? verifyGithubSignature(body, req.headers[HEADER_GITHUB_SIG], deps.githubSecret)
+    : verifyBearer(req.headers[HEADER_AUTHORIZATION], deps.bearerSecret);
+
+  if (!autorizado) {
+    logger('warn', 'unauthorized', { ip, proveedor });
+    return enviarRespuesta(res, 401, { error: 'unauthorized' });
+  }
+
+  // 9. Extraer event-id
+  const eventId = extraerEventId(req, body, proveedor);
+
+  // 10. Dedup
+  if (deps.dedup.yaVisto(eventId)) {
+    logger('info', 'duplicate', { proveedor, eventId });
+    return enviarRespuesta(res, 200, { status: 'duplicate', event_id: eventId });
+  }
+
+  // 11. Escribir al inbox
+  let bodyParseado;
+  try {
+    bodyParseado = JSON.parse(body.toString('utf8'));
+  } catch (_) {
+    // Body no es JSON — guardarlo como string
+    bodyParseado = body.toString('utf8');
+  }
+
+  const eventoGithub = req.headers[HEADER_GITHUB_EVENT];
+  const cmdId = `cmd-${Date.now().toString(36)}-${crypto.randomBytes(3).toString('hex')}`;
+  const cmd = {
+    id: cmdId,
+    platform: 'webhook',
+    userId: proveedor,
+    userName: `webhook-${proveedor}`,
+    texto: resumirEvento(proveedor, eventoGithub, bodyParseado),
+    recibidoEn: new Date().toISOString(),
+    estado: 'pending',
+    chatId: null,
+    comando: null,
+    webhookProvider: proveedor,
+    webhookEventId: eventId,
+    webhookEventType: eventoGithub || null,
+    webhookBody: bodyParseado,
+  };
+
+  try {
+    fs.mkdirSync(deps.inboxDir, { recursive: true });
+    fs.writeFileSync(path.join(deps.inboxDir, `${cmdId}.json`), JSON.stringify(cmd, null, 2), 'utf8');
+    deps.dedup.registrar(eventId, proveedor);
+  } catch (err) {
+    logger('error', 'inbox-write-error', { err: err.message });
+    return enviarRespuesta(res, 500, { error: 'write-error' });
+  }
+
+  logger('info', 'accepted', { proveedor, eventId, cmdId });
+  return enviarRespuesta(res, 200, { status: 'accepted', event_id: eventId, cmd_id: cmdId });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function validarDeps(deps) {
+  if (!deps || typeof deps !== 'object') throw new Error('webhook-server: deps requerido');
+  if (!deps.inboxDir || typeof deps.inboxDir !== 'string') {
+    throw new Error('webhook-server: deps.inboxDir requerido');
+  }
+  if (!deps.dedup || typeof deps.dedup.yaVisto !== 'function') {
+    throw new Error('webhook-server: deps.dedup inválido');
+  }
+  if (!deps.rateLimiter || typeof deps.rateLimiter.permite !== 'function') {
+    throw new Error('webhook-server: deps.rateLimiter inválido');
+  }
+  if (!Number.isFinite(deps.maxPayloadBytes) || deps.maxPayloadBytes <= 0) {
+    throw new Error('webhook-server: deps.maxPayloadBytes requerido y positivo');
+  }
+}
+
+function identificarProveedor(url) {
+  // url puede traer query string; comparar solo el path
+  const pathOnly = url.split('?')[0];
+  if (pathOnly === '/webhooks/github') return 'github';
+  if (pathOnly === '/webhooks/generic') return 'generic';
+  return null;
+}
+
+function obtenerIp(req) {
+  // En este servidor sin proxy, socket.remoteAddress es la IP real.
+  // Si se pone detrás de reverse proxy, hay que leer X-Forwarded-For — pero
+  // eso es responsabilidad del proxy y requiere config explícita (no implementado).
+  const ip = req.socket && req.socket.remoteAddress;
+  if (!ip) return '0.0.0.0';
+  // Normalizar IPv4-mapped IPv6 (::ffff:127.0.0.1 → 127.0.0.1)
+  return ip.startsWith('::ffff:') ? ip.slice(7) : ip;
+}
+
+function ipPermitida(ip, allowIps) {
+  // Comparación exacta. CIDR queda fuera de scope de Fase 3 — si se necesita,
+  // el bootstrap usa una librería de CIDR matching. Aquí: equality match.
+  return allowIps.includes(ip);
+}
+
+function leerBody(req, maxBytes) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let total = 0;
+    let abortado = false;
+
+    req.on('data', chunk => {
+      if (abortado) return;
+      total += chunk.length;
+      if (total > maxBytes) {
+        abortado = true;
+        // Pausar la lectura — NO destruir el socket. Destruir cerraría la
+        // conexión antes de que el handler pueda enviar la respuesta 413,
+        // causando ECONNRESET en el cliente. Con pause, el socket queda
+        // vivo, res.end() envía la respuesta y luego Node cierra el socket.
+        req.pause();
+        const err = new Error('payload too large');
+        err.code = 'PAYLOAD_TOO_LARGE';
+        return reject(err);
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => {
+      if (!abortado) resolve(Buffer.concat(chunks));
+    });
+    req.on('error', err => {
+      if (!abortado) reject(err);
+    });
+  });
+}
+
+function extraerEventId(req, body, proveedor) {
+  if (proveedor === 'github') {
+    const id = req.headers[HEADER_GITHUB_DELIVERY] || req.headers[HEADER_GITHUB_DELIVERY_ALT];
+    if (id) return String(id);
+  }
+  const reqId = req.headers[HEADER_REQUEST_ID];
+  if (reqId) return String(reqId);
+  // Fallback: hash del body. Mismo body = mismo id = idempotente.
+  return 'sha256-' + crypto.createHash('sha256').update(body).digest('hex');
+}
+
+function resumirEvento(proveedor, eventoGithub, body) {
+  if (proveedor === 'github' && eventoGithub) {
+    // Resumen útil para que /swl:inbox decida qué hacer
+    const ref = body && typeof body === 'object' ? body.ref : null;
+    const action = body && typeof body === 'object' ? body.action : null;
+    if (ref) return `github:${eventoGithub} ${ref}`;
+    if (action) return `github:${eventoGithub} ${action}`;
+    return `github:${eventoGithub}`;
+  }
+  if (proveedor === 'generic') {
+    if (body && typeof body === 'object' && body.command) {
+      return `generic:${String(body.command)}`;
+    }
+    const raw = typeof body === 'string' ? body : JSON.stringify(body);
+    return `generic:${raw.slice(0, 200)}`;
+  }
+  return `${proveedor}:event`;
+}
+
+function enviarRespuesta(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'Content-Length': Buffer.byteLength(payload),
+  });
+  res.end(payload);
+}
+
+module.exports = {
+  crearServidor,
+  // exportar helpers para tests de unidad si crece la necesidad
+  _internals: {
+    identificarProveedor,
+    obtenerIp,
+    ipPermitida,
+    extraerEventId,
+    resumirEvento,
+  },
+};