jerkjs 2.5.2 → 2.5.6

package/doc-2.5/SESSION_SECURITY_FLAGS.md

@@ -0,0 +1,174 @@
+# Personalización de Flags de Seguridad para Cookies de Sesión
+
+## Introducción
+
+Desde la versión 2.5.5, el framework JERK permite la personalización de las flags de seguridad para las cookies de sesión a través del sistema de hooks y filtros. Esto permite a los desarrolladores implementar medidas de seguridad adicionales según sus necesidades específicas.
+
+## Filtros Disponibles
+
+El sistema de sesiones incluye dos filtros principales para la personalización de las flags de las cookies:
+
+### 1. `session_cookie_flags`
+
+Este filtro se aplica cuando se crea una nueva cookie de sesión. Permite modificar las flags que se aplican a la cookie cuando se establece por primera vez.
+
+**Parámetros:**
+- `defaultFlags` (string): Las flags predeterminadas de la cookie (`HttpOnly; Path=/`)
+- `req` (object): El objeto de solicitud HTTP
+- `res` (object): El objeto de respuesta HTTP
+- `sessionId` (string): El ID de la sesión que se está creando
+
+### 2. `session_cookie_destroy_flags`
+
+Este filtro se aplica cuando se destruye una cookie de sesión. Permite modificar las flags que se aplican a la cookie cuando se borra.
+
+**Parámetros:**
+- `defaultFlags` (string): Las flags predeterminadas de la cookie destruida (`HttpOnly; Path=/`)
+- `req` (object): El objeto de solicitud HTTP
+- `res` (object): El objeto de respuesta HTTP
+- `sessionId` (string): El ID de la sesión que se está destruyendo
+
+## Uso Básico
+
+### Ejemplo Simple
+
+```javascript
+const { hooks } = require('jerkjs');
+
+// Añadir SameSite=Lax a todas las cookies de sesión
+hooks.addFilter('session_cookie_flags', (defaultFlags, req, res, sessionId) => {
+    return defaultFlags + '; SameSite=Lax';
+});
+
+// Añadir SameSite=Lax a las cookies de sesión cuando se destruyen
+hooks.addFilter('session_cookie_destroy_flags', (defaultFlags, req, res, sessionId) => {
+    return defaultFlags + '; SameSite=Lax';
+});
+```
+
+### Ejemplo Avanzado con Detección de HTTPS
+
+```javascript
+const { hooks } = require('jerkjs');
+
+// Personalizar flags basadas en el protocolo de la solicitud
+hooks.addFilter('session_cookie_flags', (defaultFlags, req, res, sessionId) => {
+    // Detectar si la solicitud es HTTPS (para entornos reales o proxy)
+    const isHttps = (req && req.connection && req.connection.encrypted) || 
+                   (req && req.headers && req.headers['x-forwarded-proto'] === 'https');
+    
+    let flags = defaultFlags;
+    
+    // Agregar la flag Secure si es HTTPS
+    if (isHttps) {
+        flags += '; Secure';
+    }
+    
+    // Agregar SameSite según el contexto
+    flags += '; SameSite=Lax';
+    
+    return flags;
+});
+
+// Aplicar la misma lógica al destruir la sesión
+hooks.addFilter('session_cookie_destroy_flags', (defaultFlags, req, res, sessionId) => {
+    const isHttps = (req && req.connection && req.connection.encrypted) || 
+                   (req && req.headers && req.headers['x-forwarded-proto'] === 'https');
+    
+    let flags = defaultFlags;
+    
+    if (isHttps) {
+        flags += '; Secure';
+    }
+    
+    flags += '; SameSite=Lax';
+    
+    return flags;
+});
+```
+
+## Flags de Seguridad Comunes
+
+### Flags ya implementadas
+
+- **HttpOnly**: Previene ataques de secuestro de sesión mediante XSS
+- **Secure**: Asegura que la cookie solo se transmita a través de conexiones HTTPS
+- **SameSite**: Previene ataques de falsificación de solicitudes entre sitios (CSRF)
+
+### Flags adicionales disponibles
+
+- **Partitioned**: Proporciona una capa adicional de protección contra ataques de secuestro de sesión, especialmente en contextos de terceros. Compatible con `SameSite`.
+
+### Ejemplo con Partitioned
+
+```javascript
+hooks.addFilter('session_cookie_flags', (defaultFlags, req, res, sessionId) => {
+    const isHttps = (req && req.connection && req.connection.encrypted) || 
+                   (req && req.headers && req.headers['x-forwarded-proto'] === 'https');
+    
+    let flags = defaultFlags;
+    
+    if (isHttps) {
+        flags += '; Secure';
+    }
+    
+    // SameSite=Lax es generalmente recomendado para sesiones
+    flags += '; SameSite=Lax';
+    
+    // Partitioned es opcional y depende del contexto de uso
+    // Solo se recomienda en ciertos escenarios específicos
+    // flags += '; Partitioned';  // Descomentar si se requiere
+    
+    return flags;
+});
+```
+
+## Consideraciones de Seguridad
+
+### SameSite Options
+
+- `SameSite=Strict`: La cookie solo se envía en contextos de primer nivel (mismo sitio)
+- `SameSite=Lax`: La cookie se envía en solicitudes de navegación de alto nivel (links, etc.)
+- `SameSite=None`: La cookie se envía en todos los contextos (requiere Secure)
+
+### Recomendaciones
+
+- Siempre usar `Secure` en entornos HTTPS
+- Usar `SameSite=Lax` para la mayoría de los casos de sesión
+- Considerar `SameSite=Strict` para operaciones sensibles
+- `Partitioned` es experimental y debe usarse con precaución
+
+## Ejemplos de Configuraciones Comunes
+
+### Entorno de Producción (HTTPS)
+
+```javascript
+hooks.addFilter('session_cookie_flags', (defaultFlags, req, res, sessionId) => {
+    return defaultFlags + '; Secure; SameSite=Strict';
+});
+```
+
+### Aplicación con Subdominios
+
+```javascript
+hooks.addFilter('session_cookie_flags', (defaultFlags, req, res, sessionId) => {
+    const isHttps = (req && req.connection && req.connection.encrypted) || 
+                   (req && req.headers && req.headers['x-forwarded-proto'] === 'https');
+    
+    let flags = defaultFlags;
+    
+    if (isHttps) {
+        flags += '; Secure';
+    }
+    
+    // Para aplicaciones con subdominios, SameSite=None puede ser necesario
+    // Pero requiere la flag Secure
+    flags += '; SameSite=None';
+    
+    return flags;
+});
+```
+
+## Conclusión
+
+El sistema de filtros para las cookies de sesión proporciona una forma flexible y potente de personalizar las flags de seguridad según las necesidades específicas de cada aplicación. Esto mejora significativamente la seguridad del sistema de sesiones en comparación con la implementación predeterminada.

package/doc-2.5/an/303/241lisis-completo-jerk-framework.md

@@ -0,0 +1,213 @@
+# Análisis Completo del Framework JERK
+
+## Descripción General
+
+JERK es un framework de desarrollo web completo para Node.js que implementa una arquitectura MVC (Modelo-Vista-Controlador) con soporte para APIs REST, seguridad avanzada, y sistemas de plantillas. La versión actual es 2.5.4.
+
+## Arquitectura General
+
+El framework está estructurado en componentes modulares que se comunican entre sí a través de un sistema de hooks y filtros, permitiendo una alta extensibilidad y personalización.
+
+## Componentes Principales
+
+### 1. Servidor Principal (APIServer)
+
+- Implementa un servidor HTTP/HTTPS básico con soporte para rutas parametrizadas
+- Incluye manejo de archivos estáticos con soporte para índices y control de caché
+- Tiene integración con sistema de hooks para extensibilidad
+- Soporta middlewares y manejo de cuerpos de solicitud con límites de tamaño
+
+### 2. Sistema de Enrutamiento
+
+- **Router**: Sistema de enrutamiento avanzado con soporte para rutas anidadas
+- **RouteMatcher**: Componente especializado para coincidencia de rutas parametrizadas con cacheo de expresiones regulares
+- Soporta rutas estáticas y dinámicas con prioridad adecuada
+
+### 3. Middleware
+
+- **CORS**: Middleware para configuración de políticas de recursos cruzados
+- **Authenticator**: Sistema de autenticación con múltiples estrategias (JWT, API Keys, Basic Auth, OAuth2, OpenID Connect)
+- **Session**: Sistema de sesiones con almacenamiento en memoria y cookies seguras
+- **Validator**: Validador de esquemas para solicitudes HTTP
+- **RateLimiter**: Limitador de tasa con almacenamiento en memoria o Redis
+- **Compressor**: Middleware de compresión (gzip/deflate) con sistema de hooks
+- **Firewall**: Web Application Firewall (WAF) con detección de patrones de ataque
+- **AuditLogger**: Sistema de auditoría para eventos de seguridad
+
+### 4. Componentes MVC
+
+- **ControllerBase**: Controlador base con soporte para vistas, layouts y variables
+- **ModelBase**: Clase base para modelos con operaciones CRUD
+- **ViewEngine**: Motor de plantillas profesional con soporte para filtros, helpers, condiciones, bucles e inclusiones
+- **ModelManager**: Gestor de modelos con soporte para múltiples adaptadores
+- **Adaptadores**: Soporte para diferentes motores de base de datos (Memory, MariaDB/MySQL, SQLite)
+
+### 5. Sistema de Seguridad
+
+- **SecurityEnhancedServer**: Servidor con funcionalidades de seguridad avanzada (WAF)
+- **Firewall**: Sistema de firewall con listas blancas/negras y reglas personalizadas
+- **TokenManager**: Gestión de tokens JWT con diferentes tipos de almacenamiento
+- **AttackDetector**: Detector de patrones de ataque (SQL Injection, XSS, etc.)
+
+### 6. Sistema de Hooks
+
+- Implementación completa del sistema de hooks y filtros similar al de WordPress
+- Permite extensibilidad en todos los componentes del framework
+- Soporta namespaces y prioridades para los hooks
+
+### 7. Sistemas de Carga
+
+- **RouteLoader**: Carga de rutas desde archivos JSON
+- **RouteDirectoryLoader**: Carga de rutas desde múltiples archivos JSON en un directorio
+- **ControllerLoader**: Carga dinámica de controladores desde archivos
+
+### 8. Utilidades
+
+- **Logger**: Sistema de logging estructurado con diferentes niveles y formatos
+- **ErrorHandler**: Manejo centralizado de errores con soporte para diferentes tipos de excepciones
+- **ConfigParser**: Parser de configuración desde archivos JSON y variables de entorno
+- **MimeType**: Sistema de detección de tipos MIME
+
+## Características Destacadas
+
+1. **Arquitectura Modular**: Componentes independientes para mayor flexibilidad
+2. **Seguridad Avanzada**: Múltiples capas de seguridad incluyendo WAF
+3. **Sistema de Hooks**: Extensibilidad similar al sistema de WordPress
+4. **Autenticación Flexible**: Soporte para múltiples métodos de autenticación
+5. **Almacenamiento de Tokens**: Soporte para memoria, JSON, SQLite y MariaDB
+6. **Enrutamiento Avanzado**: Soporte para rutas parametrizadas, anidadas y estáticas
+7. **Soporte para Frontend**: Capacidad de servir contenido HTML y otros tipos de contenido
+8. **Sistema de Sesiones**: Gestión completa de sesiones con soporte para autenticación
+9. **Motor de Plantillas MVC**: Sistema profesional de vistas con soporte para filtros, helpers y hooks
+10. **Arquitectura de Modelos Completa (MVC)**: Capa de modelos para la lógica de negocio y acceso a datos
+11. **Sistema de Adaptadores de Base de Datos**: Soporte para múltiples motores de base de datos
+12. **Compatible con qbuilderjs**: Integración con QueryBuilder externo para construir consultas SQL
+
+## Estructura de Directorios
+
+- `lib/`: Código fuente principal del framework
+  - `core/`: Componentes fundamentales (servidor, router, hooks)
+  - `loader/`: Componentes de carga (rutas, controladores)
+  - `middleware/`: Middlewares de seguridad y funcionalidad
+  - `mvc/`: Componentes MVC (controladores, modelos, vistas)
+  - `router/`: Componentes de enrutamiento
+  - `utils/`: Utilidades (logging, manejo de errores, etc.)
+
+## Dependencias
+
+- `bcrypt`: Para hashing de contraseñas
+- `jsonwebtoken`: Para tokens JWT
+- `mariadb`: Para conexión con bases de datos MariaDB/MySQL
+- `sqlite3`: Para conexión con bases de datos SQLite
+- `qbuilderjs`: Para construcción de consultas SQL seguras
+
+## Patrones de Diseño
+
+- **Singleton**: Para componentes centrales como el sistema de hooks
+- **Factory**: Para creación de instancias de modelos y adaptadores
+- **Strategy**: Para diferentes estrategias de autenticación
+- **Observer**: A través del sistema de hooks para extensibilidad
+- **MVC**: Arquitectura modelo-vista-controlador para la separación de responsabilidades
+
+## Funcionalidades Avanzadas
+
+### Sistema de Hooks y Filtros
+
+El framework incluye un sistema completo de hooks y filtros similar al de WordPress, que permite extender la funcionalidad en diferentes puntos del ciclo de vida de la aplicación:
+
+```javascript
+const { hooks } = require('jerkjs');
+
+// Registrar una acción
+hooks.addAction('firewall_request_blocked', (rule, clientIP, req, res) => {
+  console.log(`Solicitud bloqueada: ${rule.name} para IP: ${clientIP}`);
+});
+
+// Registrar un filtro
+hooks.addFilter('session_create_data', (userData, req) => {
+  return {
+    ...userData,
+    ipAddress: req.headers['x-forwarded-for'] || req.connection.remoteAddress,
+    createdAt: new Date().toISOString()
+  };
+});
+```
+
+### Motor de Plantillas
+
+El motor de plantillas profesional incluye soporte para:
+
+- Variables: `{{variable}}`
+- Condiciones: `{{if variable}}contenido{{endif}}`
+- Bucles: `{{foreach:array}}contenido{{endforeach}}`
+- Inclusiones: `{{include:header}}`
+- Filtros: `{{variable|upper}}`
+- Helpers personalizados
+
+### Sistema de Modelos
+
+La arquitectura de modelos completa permite:
+
+- Encapsular la lógica de negocio y el acceso a datos
+- Utilizar diferentes adaptadores de base de datos
+- Implementar operaciones CRUD estándar
+- Extender con métodos personalizados
+
+## Conclusión
+
+Este framework está diseñado para proporcionar una solución completa para el desarrollo de aplicaciones web seguras y escalables, con una arquitectura modular que permite extender su funcionalidad a través del sistema de hooks y una sólida capa de seguridad que incluye WAF, autenticación multifactor y protección contra ataques comunes.
+
+La arquitectura modular y el sistema de hooks hacen que JERK sea altamente personalizable y adaptable a diferentes necesidades de desarrollo, mientras que su enfoque en la seguridad y el patrón MVC proporcionan una base sólida para construir aplicaciones robustas y mantenibles.
+
+## Consideraciones de Seguridad Adicionales
+
+### Seguridad de Cookies en el Sistema de Sesiones
+
+Tras un análisis detallado del código de JERK Framework, se ha identificado que el sistema de sesiones implementado en `lib/middleware/session.js` presenta algunas deficiencias en cuanto a la seguridad de las cookies:
+
+#### Flags de Seguridad Implementadas:
+
+1. **HttpOnly**: 
+   - Esta flag está presente en ambas configuraciones de cookie (creación y destrucción)
+   - **Propósito**: Previene ataques de secuestro de sesión mediante XSS (Cross-Site Scripting)
+   - **Funcionamiento**: Impide que el código JavaScript del lado del cliente acceda al valor de la cookie a través de document.cookie
+   - **Implementación en JERK**: Se aplica sistemáticamente en todas las operaciones de cookie de sesión
+
+#### Flags de Seguridad Ausentes:
+
+2. **Secure**:
+   - **NO ESTÁ IMPLEMENTADA** en la configuración actual de cookies en JERK
+   - **Propósito**: Asegura que la cookie solo se transmita a través de conexiones HTTPS cifradas
+   - **Importancia**: Crítica para prevenir el robo de cookies en redes inseguras
+   - **Falta en JERK**: El framework no incluye esta flag, lo que representa un riesgo de seguridad en entornos HTTPS
+
+3. **SameSite**:
+   - **NO ESTÁ IMPLEMENTADA** en la configuración actual de cookies en JERK
+   - **Propósito**: Previene ataques de falsificación de solicitudes entre sitios (CSRF)
+   - **Valores posibles**:
+     - `Strict`: La cookie solo se envía en contextos de primer nivel (mismo sitio)
+     - `Lax`: La cookie se envía en solicitudes de navegación de alto nivel (links, etc.)
+     - `None`: La cookie se envía en todos los contextos (requiere Secure)
+   - **Importancia**: Fundamental para la protección contra CSRF
+   - **Falta en JERK**: El framework no incluye esta protección
+
+#### Recomendaciones de Mejora:
+
+Para mejorar la seguridad del sistema de sesiones, se deberían considerar las siguientes modificaciones:
+
+1. **Agregar detección automática de HTTPS**:
+   ```javascript
+   let cookieFlags = 'HttpOnly; Path=/';
+   if (req.connection.encrypted || req.headers['x-forwarded-proto'] === 'https') {
+     cookieFlags += '; Secure';
+   }
+   cookieFlags += '; SameSite=Lax';
+   res.setHeader('Set-Cookie', `${this.cookieName}=${newSessionId}; ${cookieFlags}; Max-Age=${this.timeout / 1000}`);
+   ```
+
+2. **Permitir configuración personalizada**:
+   - Opciones para SameSite (Lax, Strict, None)
+   - Configuración de Path personalizable
+   - Soporte para dominios cruzados si es necesario
+
+La implementación actual en JERK Framework proporciona la protección básica con HttpOnly, pero carece de las flags Secure y SameSite que son esenciales para una seguridad completa en aplicaciones web modernas. Estas deficiencias deben abordarse para cumplir con los estándares de seguridad actuales.