jerkjs 2.0.1 → 2.0.2

package/examples/v2_cors/README.md

@@ -0,0 +1,82 @@
+# Ejemplo API con Funcionalidad CORS
+
+Este ejemplo demuestra cómo usar la funcionalidad CORS (Cross-Origin Resource Sharing) del Framework JERK.
+
+## Características
+
+- Configuración de CORS con múltiples orígenes permitidos
+- Configuración de métodos HTTP permitidos
+- Configuración de encabezados permitidos y expuestos
+- Soporte para credenciales
+- Manejo de solicitudes preflight (OPTIONS)
+- Ejemplos de endpoints para probar diferentes aspectos de CORS
+
+## Configuración de CORS
+
+El ejemplo configura CORS con las siguientes opciones:
+
+- **Orígenes permitidos**: `['http://localhost:3000', 'http://localhost:8080', 'https://miapp.com']`
+- **Métodos permitidos**: `['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS']`
+- **Encabezados permitidos**: `['Content-Type', 'Authorization', 'X-Requested-With', 'Accept', 'X-Api-Key']`
+- **Encabezados expuestos**: `['X-Total-Count', 'X-Request-ID']`
+- **Credenciales**: `true` (permite el uso de cookies y encabezados de autenticación)
+- **Max Age**: `86400` (24 horas para caché de preflight)
+
+## Uso
+
+1. Inicia el servidor:
+   ```bash
+   node app.js
+   ```
+
+2. El servidor escuchará en `http://localhost:8094`
+
+## Endpoints
+
+- `GET /` - Página de inicio
+- `GET /public` - Endpoint público con CORS habilitado
+- `POST /data` - Endpoint para recibir datos con CORS
+- `GET /test-cors` - Endpoint para probar diferentes encabezados CORS
+
+## Pruebas de CORS
+
+Puedes probar la funcionalidad CORS desde una aplicación web alojada en uno de los orígenes permitidos:
+
+### Ejemplo de solicitud GET:
+```javascript
+fetch('http://localhost:8094/public')
+  .then(response => response.json())
+  .then(data => console.log(data));
+```
+
+### Ejemplo de solicitud POST con encabezados personalizados:
+```javascript
+fetch('http://localhost:8094/data', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    'X-Api-Key': 'tu-api-key'
+  },
+  body: JSON.stringify({ dato: 'ejemplo' })
+})
+.then(response => response.json())
+.then(data => console.log(data));
+```
+
+### Solicitudes complejas que disparan preflight:
+Las solicitudes con encabezados personalizados o ciertos tipos de contenido dispararán una solicitud OPTIONS preflight, que será manejada automáticamente por el middleware CORS.
+
+## Estructura del proyecto
+
+```
+examples/v2_cors/
+├── app.js              # Punto de entrada de la aplicación
+└── README.md
+```
+
+## Notas
+
+- El middleware CORS maneja automáticamente las solicitudes preflight (OPTIONS)
+- Los encabezados expuestos son accesibles desde el código JavaScript del cliente
+- Las credenciales permiten el uso de cookies y encabezados de autenticación
+- El encabezado `Access-Control-Max-Age` permite cachear la respuesta preflight

package/examples/v2_cors/app.js

@@ -0,0 +1,108 @@
+const {
+  APIServer,
+  Cors,
+  Logger
+} = require('../../index.js');
+
+async function startServer() {
+  // Crear instancia del servidor
+  const server = new APIServer({
+    port: 8094,
+    host: 'localhost'
+  });
+
+  // Crear instancia del logger
+  const logger = new Logger({ level: 'info' });
+
+  try {
+    // Crear instancia del middleware CORS
+    const cors = new Cors({
+      origin: ['http://localhost:3000', 'http://localhost:8080', 'https://miapp.com'],
+      methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+      allowedHeaders: [
+        'Content-Type', 
+        'Authorization', 
+        'X-Requested-With',
+        'Accept', 
+        'X-Api-Key'
+      ],
+      exposedHeaders: [
+        'X-Total-Count',
+        'X-Request-ID'
+      ],
+      credentials: true,
+      maxAge: 86400 // 24 horas
+    });
+
+    // Aplicar el middleware CORS al servidor
+    server.use(cors.middleware());
+
+    // Agregar algunas rutas de ejemplo
+    server.addRoute('GET', '/', (req, res) => {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ 
+        message: 'API con CORS configurado',
+        endpoints: {
+          'GET /public': 'Endpoint público con CORS',
+          'POST /data': 'Endpoint para recibir datos con CORS',
+          'GET /test-cors': 'Endpoint para probar diferentes encabezados CORS'
+        }
+      }));
+    });
+
+    server.addRoute('GET', '/public', (req, res) => {
+      // Establecer encabezados personalizados que serán expuestos al cliente
+      res.setHeader('X-Request-ID', 'req-' + Date.now());
+      res.setHeader('X-Total-Count', '100');
+      
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ 
+        message: 'Este es un endpoint público con CORS habilitado',
+        timestamp: new Date().toISOString(),
+        origin: req.headers.origin || 'no origin'
+      }));
+    });
+
+    server.addRoute('POST', '/data', (req, res) => {
+      // Establecer encabezados personalizados
+      res.setHeader('X-Request-ID', 'req-' + Date.now());
+      
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ 
+        message: 'Datos recibidos exitosamente',
+        receivedData: req.body,
+        timestamp: new Date().toISOString()
+      }));
+    });
+
+    server.addRoute('GET', '/test-cors', (req, res) => {
+      // Endpoint para probar diferentes aspectos de CORS
+      res.setHeader('X-Request-ID', 'req-' + Date.now());
+      res.setHeader('X-Custom-Header', 'custom-value'); // Este encabezado no está en exposedHeaders
+      
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ 
+        message: 'Prueba de CORS completada',
+        headers: req.headers,
+        timestamp: new Date().toISOString()
+      }));
+    });
+
+    // Manejar solicitudes OPTIONS para todos los endpoints (preflight)
+    // No es necesario agregar una ruta específica para '*' ya que el middleware CORS lo maneja
+
+    // Iniciar el servidor
+    server.start();
+
+    logger.info('Servidor iniciado en http://localhost:8094');
+    logger.info('CORS configurado para orígenes: http://localhost:3000, http://localhost:8080, https://miapp.com');
+  } catch (error) {
+    logger.error('Error iniciando el servidor:', error.message);
+    process.exit(1);
+  }
+}
+
+// Iniciar el servidor
+startServer();
+
+module.exports = { startServer };

package/examples/v2_cors/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "jerk-cors-example",
+  "version": "1.0.0",
+  "description": "Ejemplo de API con funcionalidad CORS usando el Framework JERK",
+  "main": "app.js",
+  "scripts": {
+    "start": "node app.js",
+    "dev": "nodemon app.js"
+  },
+  "keywords": [
+    "api",
+    "sdk",
+    "cors",
+    "cross-origin",
+    "security",
+    "framework"
+  ],
+  "author": "JERK Framework",
+  "license": "MIT",
+  "devDependencies": {
+    "nodemon": "^3.0.0"
+  }
+}

package/examples/v2_json_auth/README.md

@@ -0,0 +1,83 @@
+# Ejemplo API con Autenticación JSON
+
+Este ejemplo demuestra cómo crear una API con autenticación basada en tokens estáticos almacenados en un archivo JSON utilizando el Framework JERK.
+
+## Características
+
+- Autenticación JWT con tokens gestionados a través de almacenamiento JSON
+- Rutas protegidas y públicas
+- Sistema de login para obtener tokens
+- Controladores organizados por funcionalidad
+- Tokens almacenados en un archivo JSON local
+
+## Configuración
+
+1. Asegúrate de tener instaladas las dependencias del framework JERK
+2. El archivo de tokens `tokens.json` se creará automáticamente al iniciar la aplicación
+
+## Uso
+
+1. Inicia el servidor:
+   ```bash
+   node app.js
+   ```
+
+2. El servidor escuchará en `http://localhost:8091`
+
+## Endpoints
+
+- `GET /` - Página de inicio (público)
+- `POST /login` - Iniciar sesión y obtener token (público)
+- `GET /protected` - Contenido protegido (requiere token)
+- `GET /profile` - Perfil de usuario (requiere token)
+- `GET /tokens` - Ver tokens almacenados (requiere token)
+
+## Ejemplo de uso
+
+1. Iniciar sesión:
+   ```bash
+   curl -X POST http://localhost:8091/login \
+     -H "Content-Type: application/json" \
+     -d '{"username": "admin", "password": "password"}'
+   ```
+
+2. Acceder a contenido protegido:
+   ```bash
+   curl -X GET http://localhost:8091/protected \
+     -H "Authorization: Bearer TU_TOKEN_AQUI"
+   ```
+
+3. Ver perfil de usuario:
+   ```bash
+   curl -X GET http://localhost:8091/profile \
+     -H "Authorization: Bearer TU_TOKEN_AQUI"
+   ```
+
+4. Ver tokens almacenados:
+   ```bash
+   curl -X GET http://localhost:8091/tokens \
+     -H "Authorization: Bearer TU_TOKEN_AQUI"
+   ```
+
+## Estructura del proyecto
+
+```
+examples/v2_json_auth/
+├── app.js              # Punto de entrada de la aplicación
+├── routes.json         # Definición de rutas
+├── controllers/        # Controladores de las rutas
+│   ├── mainController.js
+│   ├── authController.js
+│   ├── protectedController.js
+│   ├── userController.js
+│   └── tokenController.js
+├── tokens.json         # Archivo de almacenamiento de tokens (generado automáticamente)
+└── README.md
+```
+
+## Seguridad
+
+- Los tokens se gestionan a través del sistema de TokenManager del framework
+- Los tokens expiran después de 1 hora
+- Las rutas protegidas requieren un token válido en el header Authorization
+- El archivo de tokens se almacena localmente en formato JSON

package/examples/v2_json_auth/app.js

@@ -0,0 +1,72 @@
+const {
+  APIServer,
+  Authenticator,
+  RouteLoader,
+  Logger,
+  TokenManager
+} = require('../../index.js');
+
+async function startServer() {
+  // Crear instancia del servidor
+  const server = new APIServer({
+    port: 8091,
+    host: 'localhost'
+  });
+
+  // Crear instancia del logger
+  const logger = new Logger({ level: 'info' });
+
+  try {
+    // Crear instancia del TokenManager con almacenamiento en JSON
+    const tokenManager = new TokenManager({
+      storage: 'json',
+      tokenFile: './tokens.json'
+    });
+
+    // Crear instancia del autenticador
+    const authenticator = new Authenticator({ logger });
+
+    // Registrar estrategia de autenticación JWT que utiliza el TokenManager con almacenamiento JSON
+    authenticator.use('jwt-json', async (req, options = {}) => {
+      const authHeader = req.headers.authorization;
+      const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN
+
+      if (!token) {
+        return false;
+      }
+
+      // Validar el token usando el TokenManager
+      const secret = 'super-secret-key-for-json-example';
+      const decoded = tokenManager.validateToken(token, secret);
+      
+      if (decoded) {
+        // Verificar si el token está almacenado en el archivo JSON (opcional, dependiendo del enfoque)
+        // En este caso, simplemente verificamos que el token sea válido
+        req.user = decoded;
+        return true;
+      }
+
+      return false;
+    });
+
+    // Agregar el autenticador al servidor para que pueda ser usado por el RouteLoader
+    server.authenticator = authenticator;
+
+    // Cargar rutas desde archivo JSON
+    const routeLoader = new RouteLoader();
+    await routeLoader.loadRoutes(server, './routes.json');
+
+    // Iniciar el servidor
+    server.start();
+
+    logger.info('Servidor iniciado en http://localhost:8091');
+  } catch (error) {
+    logger.error('Error iniciando el servidor:', error.message);
+    process.exit(1);
+  }
+}
+
+// Iniciar el servidor
+startServer();
+
+module.exports = { startServer };

package/examples/v2_json_auth/controllers/authController.js

@@ -0,0 +1,67 @@
+const jwt = require('jsonwebtoken');
+const { TokenManager } = require('../../../index.js');
+
+// TokenManager para este controlador
+const tokenManager = new TokenManager({
+  storage: 'json',
+  tokenFile: './tokens.json'
+});
+
+const authController = {
+  login: async (req, res) => {
+    try {
+      const { username, password } = req.body;
+
+      // Validación simple de credenciales (esto debería ser más robusto en producción)
+      if (!username || !password) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Nombre de usuario y contraseña requeridos' }));
+        return;
+      }
+
+      // Simulación de autenticación (en una aplicación real, esto verificaría contra una base de datos)
+      if (username === 'admin' && password === 'password') {
+        // Generar un token JWT
+        const payload = { 
+          userId: 1, 
+          username: username,
+          role: 'admin'
+        };
+        
+        // Secret para firmar el token (en producción, debería estar en variables de entorno)
+        const secret = 'super-secret-key-for-json-example';
+        const token = jwt.sign(payload, secret, { expiresIn: '1h' });
+
+        // En este ejemplo con almacenamiento JSON, no almacenamos el token en sí
+        // pero podríamos registrar información sobre él si es necesario
+        // Alternativamente, podríamos usar el TokenManager para generar un par de tokens
+        const tokenPair = tokenManager.generateTokenPair(
+          { userId: 1, username: username, role: 'admin' },
+          {
+            jwtSecret: secret,
+            refreshSecret: 'refresh-' + secret,
+            accessExpiresIn: '15m',
+            refreshExpiresIn: '7d'
+          }
+        );
+        
+        // Usamos el token de acceso
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ 
+          message: 'Inicio de sesión exitoso',
+          token: tokenPair.accessToken,
+          user: payload
+        }));
+      } else {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Credenciales inválidas' }));
+      }
+    } catch (error) {
+      console.error('Error en login:', error);
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Error interno del servidor' }));
+    }
+  }
+};
+
+module.exports = authController;

package/examples/v2_json_auth/controllers/mainController.js

@@ -0,0 +1,16 @@
+const mainController = {
+  home: (req, res) => {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ 
+      message: 'Bienvenido a la API de ejemplo con autenticación JSON',
+      endpoints: {
+        'POST /login': 'Iniciar sesión y obtener token',
+        'GET /protected': 'Contenido protegido (requiere token)',
+        'GET /profile': 'Perfil de usuario (requiere token)',
+        'GET /tokens': 'Ver tokens almacenados (requiere token)'
+      }
+    }));
+  }
+};
+
+module.exports = mainController;

package/examples/v2_json_auth/controllers/protectedController.js

@@ -0,0 +1,12 @@
+const protectedController = {
+  getProtectedData: (req, res) => {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ 
+      message: 'Datos protegidos accesados exitosamente',
+      user: req.user,
+      timestamp: new Date().toISOString()
+    }));
+  }
+};
+
+module.exports = protectedController;

package/examples/v2_json_auth/controllers/tokenController.js

@@ -0,0 +1,28 @@
+const { TokenManager } = require('../../../index.js');
+
+// TokenManager para este controlador
+const tokenManager = new TokenManager({
+  storage: 'json',
+  tokenFile: './tokens.json'
+});
+
+const tokenController = {
+  getTokens: (req, res) => {
+    try {
+      // Obtener todos los tokens almacenados
+      const tokens = tokenManager.getAllTokens ? tokenManager.getAllTokens() : 'Método no disponible en esta implementación';
+      
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ 
+        message: 'Tokens almacenados',
+        tokens: tokens || 'No se pudo obtener la lista de tokens'
+      }));
+    } catch (error) {
+      console.error('Error obteniendo tokens:', error);
+      res.writeHead(500, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Error obteniendo tokens' }));
+    }
+  }
+};
+
+module.exports = tokenController;

package/examples/v2_json_auth/controllers/userController.js

@@ -0,0 +1,15 @@
+const userController = {
+  getProfile: (req, res) => {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ 
+      profile: {
+        id: req.user.userId,
+        username: req.user.username || 'Usuario',
+        role: req.user.role || 'guest'
+      },
+      message: 'Perfil de usuario obtenido exitosamente'
+    }));
+  }
+};
+
+module.exports = userController;

package/examples/v2_json_auth/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "jerk-json-auth-example",
+  "version": "1.0.0",
+  "description": "Ejemplo de API con autenticación JSON usando el Framework JERK",
+  "main": "app.js",
+  "scripts": {
+    "start": "node app.js",
+    "dev": "nodemon app.js"
+  },
+  "keywords": [
+    "api",
+    "sdk",
+    "authentication",
+    "json",
+    "jwt",
+    "framework"
+  ],
+  "author": "JERK Framework",
+  "license": "MIT",
+  "dependencies": {
+    "jsonwebtoken": "^9.0.0"
+  },
+  "devDependencies": {
+    "nodemon": "^3.0.0"
+  }
+}

package/examples/v2_json_auth/routes.json

@@ -0,0 +1,37 @@
+[
+  {
+    "path": "/",
+    "method": "GET",
+    "controller": "./controllers/mainController.js",
+    "handler": "home",
+    "auth": "none"
+  },
+  {
+    "path": "/login",
+    "method": "POST",
+    "controller": "./controllers/authController.js",
+    "handler": "login",
+    "auth": "none"
+  },
+  {
+    "path": "/protected",
+    "method": "GET",
+    "controller": "./controllers/protectedController.js",
+    "handler": "getProtectedData",
+    "auth": "jwt-json"
+  },
+  {
+    "path": "/profile",
+    "method": "GET",
+    "controller": "./controllers/userController.js",
+    "handler": "getProfile",
+    "auth": "jwt-json"
+  },
+  {
+    "path": "/tokens",
+    "method": "GET",
+    "controller": "./controllers/tokenController.js",
+    "handler": "getTokens",
+    "auth": "jwt-json"
+  }
+]

package/examples/v2_json_auth/tokens.json

@@ -0,0 +1,20 @@
+{
+  "example_token": {
+    "userId": 0,
+    "createdAt": "2026-01-14T00:00:00.000Z",
+    "expiresAt": "2026-01-15T00:00:00.000Z",
+    "revoked": false
+  },
+  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInVzZXJuYW1lIjoiYWRtaW4iLCJyb2xlIjoiYWRtaW4iLCJ0b2tlblR5cGUiOiJyZWZyZXNoIiwiaWF0IjoxNzY4NDMzODc2LCJleHAiOjE3NjkwMzg2NzZ9.50INL6kmOd9A2mQiBRBlHaXHk31Tw7SgQMH_uRh6NVo": {
+    "userId": 1,
+    "createdAt": "2026-01-14T23:37:56.407Z",
+    "expiresAt": "2026-01-21T23:37:56.407Z",
+    "revoked": false
+  },
+  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOjEsInVzZXJuYW1lIjoiYWRtaW4iLCJyb2xlIjoiYWRtaW4iLCJ0b2tlblR5cGUiOiJyZWZyZXNoIiwiaWF0IjoxNzY4NDM4NzU4LCJleHAiOjE3NjkwNDM1NTh9.WoMURKAizVPkMM0-lqtl1-mP0L8OMM6INeG5Bv79ixU": {
+    "userId": 1,
+    "createdAt": "2026-01-15T00:59:18.846Z",
+    "expiresAt": "2026-01-22T00:59:18.846Z",
+    "revoked": false
+  }
+}