@saulwade/swl-ses 1.3.7 → 1.4.0

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