jerkjs 2.5.8 → 2.6.1

package/doc-2.5/WAF_MODULE_MANUAL.md

@@ -0,0 +1,229 @@
+# Manual del Módulo WAF (Web Application Firewall) para JERK Framework
+
+## Tabla de Contenidos
+1. [Introducción](#introducción)
+2. [Características del WAF](#características-del-waf)
+3. [Comandos Disponibles](#comandos-disponibles)
+4. [Estadísticas del Servidor](#estadísticas-del-servidor)
+5. [Gestión de Reglas X-Headers](#gestión-de-reglas-x-headers)
+6. [Listas de IPs](#listas-de-ips)
+7. [Persistencia de Reglas](#persistencia-de-reglas)
+8. [Ejemplos de Uso](#ejemplos-de-uso)
+
+## Introducción
+
+El módulo WAF (Web Application Firewall) es una extensión de la extensión de administración de JERK Framework que permite monitorear, gestionar y proteger tu aplicación web. Proporciona estadísticas en tiempo real, gestión de reglas de seguridad y control de acceso basado en headers X-.
+
+## Características del WAF
+
+- **Estadísticas en tiempo real**: Conteo de solicitudes procesadas y respuestas enviadas con medición en kilobytes
+- **Monitoreo de tráfico**: Registro de accesos a rutas y endpoints
+- **Sistema de reglas X-Headers**: Bloqueo basado en headers como X-Forwarded-For, X-Real-IP, etc.
+- **Listas de IPs**: Sistema de whitelist (nunca bloqueadas) y blacklist (siempre bloqueadas)
+- **Persistencia**: Guardado y carga de reglas de seguridad
+- **Interfaz interactiva**: Sistema de comandos para gestión en tiempo real
+
+## Comandos Disponibles
+
+### Comandos Generales de Estadísticas
+- `waf-status` o `waf-stats`: Muestra estadísticas generales del servidor
+- `waf-blocked` o `waf-security`: Muestra estadísticas de seguridad
+- `waf-x-headers`: Muestra reglas de headers X- configuradas
+
+### Comandos de Gestión de Reglas
+- `create-x-rule`: Crea una nueva regla de seguridad basada en headers X-
+- `remove-x-rule`: Remueve una regla de seguridad existente
+- `save-rules`: Guarda todas las reglas a un archivo
+- `load-rules`: Carga reglas desde un archivo
+
+### Comandos de Gestión de IPs
+- `waf-block-ip`: Bloquea temporalmente una IP
+- `waf-unblock-ip`: Desbloquea una IP temporalmente bloqueada
+- `waf-whitelist`: Agrega una IP a la lista blanca
+- `waf-blacklist`: Agrega una IP a la lista negra
+
+## Estadísticas del Servidor
+
+### waf-status / waf-stats
+Muestra las estadísticas generales del servidor:
+
+```
+=== Estadísticas del WAF ===
+Solicitudes procesadas: 15
+Solicitudes procesadas (KB): 2.45 KB
+Respuestas enviadas: 15
+Respuestas enviadas (KB): 15.67 KB
+IPs en lista blanca: 2
+IPs en lista negra: 1
+Reglas de seguridad activas: 3
+```
+
+### Campos de Estadísticas
+- **Solicitudes procesadas**: Número total de solicitudes HTTP procesadas
+- **Solicitudes procesadas (KB)**: Cantidad total de datos recibidos en kilobytes
+- **Respuestas enviadas**: Número total de respuestas HTTP enviadas
+- **Respuestas enviadas (KB)**: Cantidad total de datos enviados en kilobytes
+- **IPs en lista blanca**: Número de IPs que nunca serán bloqueadas
+- **IPs en lista negra**: Número de IPs que siempre serán bloqueadas
+- **Reglas de seguridad activas**: Número de reglas de seguridad activas
+
+## Gestión de Reglas X-Headers
+
+### Crear Regla (`create-x-rule`)
+Proceso interactivo para crear reglas de seguridad basadas en headers X-:
+
+1. **Nombre del header**: Introduce el nombre del header X- (ej: X-Forwarded-For, X-Real-IP)
+2. **Patrón**: Introduce el patrón para coincidir (cadena o expresión regular)
+3. **Acción**: Selecciona la acción a tomar:
+   - `1` o `block`: Bloquear solicitudes que coincidan
+   - `2` o `log`: Registrar solicitudes que coincidan
+   - `3` o `monitor`: Monitorear solicitudes que coincidan
+4. **Razón**: Introduce la razón para la regla (opcional)
+
+### Remover Regla (`remove-x-rule`)
+Proceso interactivo para remover reglas existentes:
+1. Se muestra una lista numerada de reglas disponibles
+2. Introduce el número de la regla que deseas remover
+3. La regla se elimina inmediatamente del sistema
+
+## Listas de IPs
+
+### Whitelist (`waf-whitelist`)
+Agrega una IP a la lista blanca (nunca será bloqueada):
+
+```
+> waf-whitelist
+Introduce la IP a agregar a la lista blanca (ej: 192.168.1.100):
+> 192.168.1.100
+IP 192.168.1.100 agregada a la lista blanca.
+```
+
+### Blacklist (`waf-blacklist`)
+Agrega una IP a la lista negra (siempre será bloqueada):
+
+```
+> waf-blacklist
+Introduce la IP a agregar a la lista negra (ej: 10.0.0.100):
+> 10.0.0.100
+IP 10.0.0.100 agregada a la lista negra.
+```
+
+### Bloqueo Temporal (`waf-block-ip`)
+Bloquea temporalmente una IP:
+
+```
+> waf-block-ip
+Introduce la IP a bloquear temporalmente (ej: 192.168.1.100):
+> 192.168.1.200
+IP 192.168.1.200 bloqueada temporalmente.
+```
+
+## Persistencia de Reglas
+
+### Guardar Reglas (`save-rules`)
+Guarda todas las reglas de seguridad actuales a un archivo JSON:
+
+```
+> save-rules
+✅ Reglas guardadas exitosamente en: /path/to/waf-rules/waf-rules-timestamp.json
+Total de reglas guardadas: 3
+```
+
+### Cargar Reglas (`load-rules`)
+Carga reglas de seguridad desde un archivo JSON:
+
+```
+> load-rules
+=== Archivos de Reglas Disponibles ===
+1. waf-rules-1770795262452.json
+
+Introduce el número del archivo a cargar (o "cancel" para cancelar):
+> 1
+
+¿Deseas reemplazar las reglas actuales? (sí/no):
+> sí
+
+✅ Reglas cargadas exitosamente desde: /path/to/waf-rules/waf-rules-1770795262452.json
+Total de reglas cargadas: 3
+```
+
+## Ejemplos de Uso
+
+### Ejemplo 1: Crear Regla para Bloquear IPs Internas
+```
+> create-x-rule
+=== Crear Regla de Header X- ===
+Introduce el nombre del header X- (ej: X-Forwarded-For, X-Real-IP):
+> X-Forwarded-For
+Header seleccionado: X-Forwarded-For
+Introduce el patrón para coincidir (cadena o expresión regular):
+> 192.168.
+Selecciona la acción a tomar:
+1. block - Bloquear solicitudes que coincidan
+2. log - Registrar solicitudes que coincidan
+3. monitor - Monitorear solicitudes que coincidan
+Escribe el número o el nombre de la acción:
+> 1
+Acción seleccionada: block
+Introduce la razón para la regla (opcional):
+> Bloquear IPs internas
+✅ Regla de header X- creada exitosamente:
+  ID: xheader_x_forwarded_for_1770792842636
+  Header: x-forwarded-for
+  Patrón: 192.168.
+  Acción: block
+  Razón: Bloquear IPs internas
+```
+
+### Ejemplo 2: Ver Estadísticas de Seguridad
+```
+> waf-security
+=== Estadísticas de Seguridad del WAF ===
+IPs bloqueadas temporalmente: 2
+Intentos de ataque detectados: 5
+Tipos de ataques detectados: 3
+Registros de seguridad: 10
+
+Accesos a rutas (Input/Output):
+  GET /: 8 accesos
+  POST /api/users: 3 accesos
+  GET /api/users: 4 accesos
+
+Endpoints más accedidos:
+  GET /: 8 hits
+  GET /api/users: 4 hits
+  POST /api/users: 3 hits
+```
+
+### Ejemplo 3: Agregar IP a Lista Negra
+```
+> waf-blacklist
+Introduce la IP a agregar a la lista negra (ej: 10.0.0.100):
+> 10.0.0.100
+IP 10.0.0.100 agregada a la lista negra.
+```
+
+## Consideraciones de Seguridad
+
+- El servidor de administración solo escucha en localhost (127.0.0.1) por defecto
+- Todas las operaciones de bloqueo son inmediatas y afectan al sistema en tiempo real
+- Las reglas de seguridad se aplican antes de que la solicitud llegue a los controladores
+- El sistema de persistencia permite mantener reglas entre reinicios del servidor
+
+## Solución de Problemas
+
+### Las estadísticas no se actualizan
+- Verifica que el middleware de firewall esté activo en tu servidor
+- Asegúrate de que las solicitudes estén pasando por el sistema de firewall
+
+### Las reglas no se aplican
+- Verifica que el firewall esté correctamente integrado en tu pipeline de middlewares
+- Confirma que las reglas se hayan creado correctamente usando `waf-x-headers`
+
+## Autor
+
+JERK Framework Team
+
+## Versión
+
+v2.5.8

package/index.js

@@ -1,6 +1,6 @@
 /**
  * Punto de entrada del framework JERK
- * JERK Framework 2.5.1
+ * JERK Framework 2.5.8
  */
 
 // Mostrar mensaje de versión al iniciar
@@ -51,10 +51,15 @@ const { ErrorHandler, ValidationError, AuthenticationError, DatabaseError } = re
 
 // Componentes de caché
 const CacheHooks = require('./lib/cache/CacheHooks');
+
 // Componentes del QueryBuilder (v2.3.0) - MODIFICADO PARA USAR QBUILDERJS
 const QueryBuilder = require('qbuilderjs');
 // No hay middleware ni hooks ya que se eliminó la implementación interna
 
+// Componentes de sistema de colas (v2.6.0)
+const QueueSystem = require('./lib/queue/QueueSystem');
+const QueueIntegration = require('./lib/queue/integration');
+
 
 // Exportar todos los componentes del framework
 module.exports = {
@@ -100,7 +105,7 @@ module.exports = {
   // Componentes de modelo (v2.4.0)
   ModelBase,
   ModelManager,
-  // Componentes del QueryBuilder (v2.3.0) 
+  // Componentes del QueryBuilder (v2.3.0)
   QueryBuilder,
   UserModel,
 
@@ -118,6 +123,10 @@ module.exports = {
   AuthenticationError,
   DatabaseError,
 
+  // Componentes de sistema de colas (v2.6.0)
+  QueueSystem,
+  QueueIntegration,
+
   // Componentes de administración (v2.5.7)
   AdminExtension: require('./lib/admin/AdminExtension')
 };
@@ -130,4 +139,4 @@ const hooksInstance = new HookSystem();
 module.exports.hooks = hooksInstance;
 
 // Disparar hooks de inicio del framework
-hooksInstance.doAction('framework_init');
+hooksInstance.doAction('framework_init');

package/jerk-admin-client/README.md

@@ -0,0 +1,69 @@
+# Cliente CLI para JERK Framework Administration Server
+
+Cliente de línea de comandos para interactuar con el servidor de administración de JERK Framework. Permite reutilizar comandos y cuenta con autocompletado.
+
+## Características
+
+- **Autocompletado**: Presiona TAB para autocompletar comandos conocidos
+- **Historial de comandos**: Accede a comandos previamente utilizados
+- **Reutilización de comandos**: Reutiliza comandos por número o por texto
+- **Conservación de contexto**: Mantiene el historial entre sesiones
+
+## Instalación
+
+El cliente CLI está incluido en el framework JERK y se puede ejecutar directamente:
+
+```bash
+node jerk-admin-client.js
+```
+
+O con parámetros específicos:
+
+```bash
+node jerk-admin-client.js --host 127.0.0.1 --port 9999
+```
+
+## Comandos del Cliente
+
+Además de los comandos del servidor de administración, el cliente CLI incluye comandos especiales:
+
+- `history` - Muestra el historial de comandos
+- `clear` - Limpia la pantalla
+- `re <número>` - Reutiliza el comando número n del historial
+- `re <texto>` - Reutiliza el último comando que contiene el texto
+- `help-cli` - Muestra la ayuda del cliente
+
+## Uso
+
+1. Inicia el cliente:
+```bash
+node jerk-admin-client.js
+```
+
+2. El cliente se conectará automáticamente al servidor de administración en `localhost:9999`
+
+3. Usa los comandos estándar del servidor de administración:
+   - `stats` - Ver estadísticas generales
+   - `requests` - Ver estadísticas de solicitudes
+   - `endpoints` - Ver endpoints más accedidos
+   - `routes` - Ver rutas registradas
+   - `help` - Ver todos los comandos disponibles
+
+4. Usa los comandos especiales del cliente para mejorar la experiencia:
+   - `history` para ver comandos anteriores
+   - `re 3` para reutilizar el tercer comando del historial
+   - `re stats` para reutilizar el último comando que contenía "stats"
+
+## Atajos
+
+- Presiona `↑` y `↓` para navegar por el historial de comandos
+- Presiona `TAB` para autocompletar comandos
+- Presiona `Ctrl+C` para salir del cliente
+
+## Configuración
+
+Por defecto, el cliente intenta conectarse a `localhost:9999`. Puedes especificar un host y puerto diferente usando los argumentos `--host` y `--port`.
+
+## Archivo de Historial
+
+El cliente guarda el historial de comandos en `~/.jerk_admin_history` para conservarlo entre sesiones.

package/jerk-admin-client/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@jerkjs/admin-client",
+  "version": "1.0.0",
+  "description": "Cliente CLI para interactuar con el servidor de administración de JERK Framework",
+  "main": "jerk-admin-client.js",
+  "bin": {
+    "jerk-admin": "./jerk-admin-client.js"
+  },
+  "scripts": {
+    "start": "node jerk-admin-client.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "jerkjs",
+    "admin",
+    "cli",
+    "client",
+    "framework"
+  ],
+  "author": "JERK Framework Team",
+  "license": "Apache-2.0",
+  "dependencies": {}
+}

package/jerk-admin-client.js

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+
+/**
+ * Cliente CLI para interactuar con el servidor de administración de JERK Framework
+ * Permite reutilizar comandos y tiene autocompletado
+ */
+
+const net = require('net');
+const readline = require('readline');
+const fs = require('fs');
+const path = require('path');
+
+// Configuración por defecto
+const DEFAULT_HOST = 'localhost';
+const DEFAULT_PORT = 9999;
+
+// Historial de comandos
+let commandHistory = [];
+const HISTORY_FILE = path.join(require('os').homedir(), '.jerk_admin_history');
+
+// Cargar historial de comandos si existe
+if (fs.existsSync(HISTORY_FILE)) {
+  try {
+    const historyData = fs.readFileSync(HISTORY_FILE, 'utf8');
+    commandHistory = JSON.parse(historyData);
+  } catch (error) {
+    console.error('Error al cargar el historial:', error.message);
+  }
+}
+
+// Comandos conocidos para autocompletado
+const knownCommands = [
+  'help',
+  'stats',
+  'statistics', 
+  'requests',
+  'endpoints',
+  'routes',
+  'active',
+  'version',
+  'status',
+  'cache',
+  'cache-stats',
+  'cache-clear',
+  'cache-info',
+  'sysinfo',
+  'system',
+  'resources',
+  'time',
+  'date',
+  'quit',
+  'exit'
+];
+
+// Función para guardar el historial
+function saveHistory() {
+  try {
+    fs.writeFileSync(HISTORY_FILE, JSON.stringify(commandHistory, null, 2));
+  } catch (error) {
+    console.error('Error al guardar el historial:', error.message);
+  }
+}
+
+// Función para autocompletar comandos
+function completer(line) {
+  const hits = knownCommands.filter(cmd => cmd.startsWith(line));
+  return [hits.length ? hits : knownCommands, line];
+}
+
+// Función para crear el cliente
+function createClient(host = DEFAULT_HOST, port = DEFAULT_PORT) {
+  const client = new net.Socket();
+  
+  // Conectar al servidor de administración
+  client.connect(port, host, () => {
+    console.log(`Conectado al servidor de administración en ${host}:${port}`);
+    console.log('Escribe "help" para ver los comandos disponibles o "quit" para salir\n');
+    
+    // Configurar readline con autocompletado
+    const rl = readline.createInterface({
+      input: process.stdin,
+      output: process.stdout,
+      completer: completer,
+      history: commandHistory
+    });
+    
+    // Mostrar historial de comandos recientes
+    if (commandHistory.length > 0) {
+      console.log(`Comandos recientes: ${commandHistory.slice(-5).join(', ')}\n`);
+    }
+    
+    // Función para manejar la entrada del usuario
+    function handleInput() {
+      rl.question('> ', (input) => {
+        const command = input.trim();
+        
+        if (command.toLowerCase() === 'quit' || command.toLowerCase() === 'exit') {
+          console.log('Desconectando del servidor...');
+          client.end();
+          rl.close();
+          saveHistory();
+          return;
+        }
+        
+        if (command.toLowerCase() === 'history') {
+          console.log('Historial de comandos:');
+          commandHistory.forEach((cmd, index) => {
+            console.log(`${index + 1}. ${cmd}`);
+          });
+          handleInput();
+          return;
+        }
+        
+        if (command.toLowerCase() === 'clear') {
+          console.clear();
+          handleInput();
+          return;
+        }
+        
+        if (command.toLowerCase() === 'help-cli') {
+          console.log('\n--- Comandos del Cliente CLI ---');
+          console.log('help-cli - Muestra esta ayuda');
+          console.log('history - Muestra el historial de comandos');
+          console.log('clear - Limpia la pantalla');
+          console.log('re <número> - Reutiliza el comando número n del historial');
+          console.log('re <texto> - Reutiliza el último comando que contiene el texto');
+          console.log('-----------------------------\n');
+          handleInput();
+          return;
+        }
+        
+        // Comando para reutilizar comandos del historial
+        if (command.toLowerCase().startsWith('re ')) {
+          const arg = command.substring(3).trim();
+          
+          if (/^\d+$/.test(arg)) {
+            // Reutilizar por número
+            const index = parseInt(arg) - 1;
+            if (index >= 0 && index < commandHistory.length) {
+              const reusedCmd = commandHistory[index];
+              console.log(`Reutilizando comando: ${reusedCmd}`);
+              client.write(reusedCmd + '\n');
+              if (!commandHistory.includes(reusedCmd)) {
+                commandHistory.push(reusedCmd);
+              }
+            } else {
+              console.log(`Número de comando inválido: ${arg}`);
+              handleInput();
+            }
+          } else {
+            // Reutilizar por texto
+            const matchingCmd = commandHistory.reverse().find(cmd => cmd.includes(arg));
+            commandHistory.reverse(); // Restaurar orden original
+            
+            if (matchingCmd) {
+              console.log(`Reutilizando comando: ${matchingCmd}`);
+              client.write(matchingCmd + '\n');
+            } else {
+              console.log(`No se encontró comando que contenga: ${arg}`);
+              handleInput();
+            }
+          }
+        } else if (command) {
+          // Enviar comando al servidor
+          client.write(command + '\n');
+          
+          // Agregar al historial si no está repetido
+          if (!commandHistory.includes(command)) {
+            commandHistory.push(command);
+            // Mantener solo los últimos 100 comandos
+            if (commandHistory.length > 100) {
+              commandHistory = commandHistory.slice(-100);
+            }
+          }
+        }
+        
+        handleInput();
+      });
+    }
+    
+    // Iniciar la interacción
+    handleInput();
+  });
+  
+  // Manejar datos recibidos del servidor
+  client.on('data', (data) => {
+    const output = data.toString();
+    process.stdout.write(output);
+    
+    // Si la salida termina con el prompt, significa que el comando terminó
+    if (output.endsWith('> ')) {
+      // No hacer nada, dejar que readline continúe
+    }
+  });
+  
+  // Manejar errores
+  client.on('error', (error) => {
+    console.error(`Error de conexión: ${error.message}`);
+    process.exit(1);
+  });
+  
+  // Manejar cierre de conexión
+  client.on('close', () => {
+    console.log('\nConexión cerrada');
+    process.exit(0);
+  });
+}
+
+// Mostrar ayuda
+function showHelp() {
+  console.log(`
+Cliente CLI para JERK Framework Administration Server
+
+Uso: node jerk-admin-client.js [opciones]
+
+Opciones:
+  -h, --host HOST     Host del servidor (por defecto: ${DEFAULT_HOST})
+  -p, --port PORT     Puerto del servidor (por defecto: ${DEFAULT_PORT})
+  --help              Mostrar esta ayuda
+
+Comandos especiales del cliente:
+  history             Mostrar historial de comandos
+  clear               Limpiar la pantalla
+  re <número>         Reutilizar comando por número
+  re <texto>          Reutilizar último comando que contiene texto
+  help-cli            Mostrar ayuda del cliente
+
+Ejemplos:
+  node jerk-admin-client.js
+  node jerk-admin-client.js --host 127.0.0.1 --port 9999
+  `);
+}
+
+// Parsear argumentos
+const args = process.argv.slice(2);
+let host = DEFAULT_HOST;
+let port = DEFAULT_PORT;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--help' || args[i] === '-h') {
+    showHelp();
+    process.exit(0);
+  } else if (args[i] === '--host' || args[i] === '-h') {
+    host = args[++i];
+  } else if (args[i] === '--port' || args[i] === '-p') {
+    port = parseInt(args[++i]);
+  }
+}
+
+// Validar puerto
+if (isNaN(port) || port <= 0 || port > 65535) {
+  console.error(`Puerto inválido: ${port}`);
+  process.exit(1);
+}
+
+// Iniciar el cliente
+createClient(host, port);