jerkjs 2.0.1 → 2.0.2

package/examples/v2_no_auth/routes.json

@@ -0,0 +1,37 @@
+[
+  {
+    "path": "/",
+    "method": "GET",
+    "controller": "./controllers/mainController.js",
+    "handler": "home",
+    "auth": "none"
+  },
+  {
+    "path": "/public",
+    "method": "GET",
+    "controller": "./controllers/publicController.js",
+    "handler": "getPublicData",
+    "auth": "none"
+  },
+  {
+    "path": "/products",
+    "method": "GET",
+    "controller": "./controllers/productController.js",
+    "handler": "getAllProducts",
+    "auth": "none"
+  },
+  {
+    "path": "/products/:id",
+    "method": "GET",
+    "controller": "./controllers/productController.js",
+    "handler": "getProductById",
+    "auth": "none"
+  },
+  {
+    "path": "/health",
+    "method": "GET",
+    "controller": "./controllers/healthController.js",
+    "handler": "getStatus",
+    "auth": "none"
+  }
+]

package/examples/v2_oauth/README.md

@@ -0,0 +1,70 @@
+# Ejemplo API con Funcionalidad OAuth 2.0
+
+Este ejemplo demuestra cómo implementar autenticación OAuth 2.0 usando el Framework JERK.
+
+## Características
+
+- Implementación de flujo OAuth 2.0 (simulado para demostración)
+- Generación de tokens JWT tras autenticación OAuth
+- Rutas protegidas que requieren tokens JWT
+- Simulación del proceso de autorización y callback
+- Controladores organizados por funcionalidad
+
+## Configuración
+
+Este ejemplo simula el flujo OAuth para fines de demostración. En un entorno real, necesitarías:
+
+1. Registrar tu aplicación con un proveedor OAuth (Google, GitHub, etc.)
+2. Obtener Client ID y Client Secret
+3. Configurar la URL de callback en tu aplicación
+4. Ajustar las rutas y controladores según tus necesidades
+
+## Uso
+
+1. Inicia el servidor:
+   ```bash
+   node app.js
+   ```
+
+2. El servidor escuchará en `http://localhost:8093`
+
+## Endpoints
+
+- `GET /` - Página de inicio con instrucciones
+- `GET /auth/google` - Iniciar flujo OAuth con Google (simulado)
+- `GET /auth/callback` - Callback de OAuth (simulado)
+- `GET /profile` - Perfil de usuario (requiere token JWT)
+- `GET /protected` - Contenido protegido (requiere token JWT)
+
+## Flujo de OAuth simulado
+
+1. Visita `/auth/google` para iniciar el proceso OAuth
+2. El sistema simulará la redirección a Google y el callback
+3. Se generará un token JWT para el usuario autenticado
+4. Usa el token para acceder a endpoints protegidos
+
+## Estructura del proyecto
+
+```
+examples/v2_oauth/
+├── app.js              # Punto de entrada de la aplicación
+├── routes.json         # Definición de rutas
+├── controllers/        # Controladores de las rutas
+│   ├── mainController.js
+│   ├── oauthController.js
+│   ├── userController.js
+│   └── protectedController.js
+└── README.md
+```
+
+## Implementación real
+
+Para implementar OAuth en un entorno real:
+
+1. Registra tu aplicación con un proveedor OAuth
+2. Configura las credenciales en el código
+3. Implementa la lógica para intercambiar el código de autorización por tokens
+4. Almacena de forma segura los tokens de acceso y refresh
+5. Usa los tokens para acceder a las APIs del proveedor
+
+El framework proporciona la estrategia `oauth2Strategy` que puedes usar con tus credenciales reales.

package/examples/v2_oauth/app.js

@@ -0,0 +1,90 @@
+const {
+  APIServer,
+  Authenticator,
+  RouteLoader,
+  Logger,
+  TokenManager
+} = require('../../index.js');
+
+async function startServer() {
+  // Crear instancia del servidor
+  const server = new APIServer({
+    port: 8093,
+    host: 'localhost'
+  });
+
+  // Crear instancia del logger
+  const logger = new Logger({ level: 'info' });
+
+  try {
+    // Crear instancia del TokenManager
+    const tokenManager = new TokenManager({
+      storage: 'memory'
+    });
+
+    // Crear instancia del autenticador
+    const authenticator = new Authenticator({ logger });
+
+    // Registrar estrategia de autenticación OAuth2 REAL del framework
+    // Esta es la verdadera implementación del framework
+    authenticator.use('oauth2', authenticator.oauth2Strategy({
+      clientId: process.env.OAUTH_CLIENT_ID || 'tu-client-id-aqui',
+      clientSecret: process.env.OAUTH_CLIENT_SECRET || 'tu-client-secret-aqui',
+      callbackURL: 'http://localhost:8093/auth/callback',
+      authorizationURL: 'https://accounts.google.com/o/oauth2/v2/auth',
+      tokenURL: 'https://oauth2.googleapis.com/token'
+    }));
+
+    // Registrar estrategia JWT para tokens generados internamente
+    authenticator.use('jwt-oauth', 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 secreto de las variables de entorno
+      const secret = process.env.JWT_SECRET;
+
+      // Verificar que el secreto esté definido
+      if (!secret) {
+        logger.error('JWT_SECRET no está definido en las variables de entorno');
+        return false;
+      }
+
+      const decoded = tokenManager.validateToken(token, secret);
+
+      if (decoded) {
+        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:8093');
+    logger.info('Configura tus credenciales OAuth para usar la autenticación real');
+    logger.info('Variables de entorno necesarias:');
+    logger.info('- OAUTH_CLIENT_ID: Tu Client ID de Google OAuth');
+    logger.info('- OAUTH_CLIENT_SECRET: Tu Client Secret de Google OAuth');
+  } catch (error) {
+    logger.error('Error iniciando el servidor:', error.message);
+    process.exit(1);
+  }
+}
+
+// Iniciar el servidor
+startServer();
+
+module.exports = { startServer };

package/examples/v2_oauth/controllers/mainController.js

@@ -0,0 +1,45 @@
+const mainController = {
+  home: (req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/html' });
+    res.end(`
+      <!DOCTYPE html>
+      <html>
+      <head>
+        <title>Ejemplo OAuth con JERK Framework</title>
+        <style>
+          body { font-family: Arial, sans-serif; margin: 40px; }
+          .endpoint { margin: 10px 0; padding: 10px; background-color: #f0f0f0; border-radius: 5px; }
+          a { color: #007bff; text-decoration: none; }
+          a:hover { text-decoration: underline; }
+        </style>
+      </head>
+      <body>
+        <h1>Ejemplo OAuth con JERK Framework</h1>
+        <p>Este ejemplo demuestra la funcionalidad OAuth 2.0 del framework.</p>
+        
+        <h2>Endpoints disponibles:</h2>
+        <div class="endpoint">
+          <strong><a href="/auth/google">GET /auth/google</a></strong> - Iniciar flujo OAuth con Google
+        </div>
+        <div class="endpoint">
+          <strong><a href="/profile">GET /profile</a></strong> - Perfil de usuario (requiere token JWT)
+        </div>
+        <div class="endpoint">
+          <strong><a href="/protected">GET /protected</a></strong> - Contenido protegido (requiere token JWT)
+        </div>
+        
+        <h2>Instrucciones:</h2>
+        <ol>
+          <li>Visita <a href="/auth/google">/auth/google</a> para iniciar el flujo OAuth</li>
+          <li>El callback OAuth manejará la autenticación y generará un token JWT</li>
+          <li>Usa el token generado para acceder a los endpoints protegidos</li>
+        </ol>
+        
+        <p><em>Nota: Este es un ejemplo funcional. En un entorno real, necesitarías configurar credenciales reales de OAuth con un proveedor como Google, GitHub, etc.</em></p>
+      </body>
+      </html>
+    `);
+  }
+};
+
+module.exports = mainController;

package/examples/v2_oauth/controllers/oauthController.js

@@ -0,0 +1,247 @@
+const jwt = require('jsonwebtoken');
+const { Authenticator, TokenManager } = require('../../../index.js');
+
+// TokenManager para este controlador
+const tokenManager = new TokenManager({
+  storage: 'memory'
+});
+
+const oauthController = {
+  initiateGoogleAuth: (req, res) => {
+    // Obtener las credenciales de OAuth
+    const clientId = process.env.OAUTH_CLIENT_ID;
+    const clientSecret = process.env.OAUTH_CLIENT_SECRET;
+    
+    // Verificar si las credenciales están configuradas
+    if (!clientId || clientId === 'tu-client-id-aqui' || !clientSecret || clientSecret === 'tu-client-secret-aqui') {
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(`
+        <!DOCTYPE html>
+        <html>
+        <head>
+          <title>Configurar OAuth con Google</title>
+          <style>
+            body { font-family: Arial, sans-serif; margin: 40px; text-align: center; }
+            .container { max-width: 800px; margin: 0 auto; }
+            .setup-instructions { 
+              margin: 20px 0; 
+              padding: 20px; 
+              background-color: #fff3cd; 
+              border: 1px solid #ffeaa7; 
+              border-radius: 4px; 
+              text-align: left;
+            }
+            .credentials-form {
+              margin: 20px 0;
+              padding: 20px;
+              background-color: #f8f9fa;
+              border: 1px solid #dee2e6;
+              border-radius: 4px;
+            }
+            input[type="text"], input[type="password"] {
+              width: 100%;
+              padding: 8px;
+              margin: 5px 0;
+              box-sizing: border-box;
+            }
+            button {
+              background-color: #007bff;
+              color: white;
+              border: none;
+              padding: 10px 20px;
+              cursor: pointer;
+              margin: 10px 5px;
+            }
+            button:hover {
+              background-color: #0056b3;
+            }
+          </style>
+        </head>
+        <body>
+          <div class="container">
+            <h1>Configurar OAuth con Google</h1>
+            
+            <div class="setup-instructions">
+              <h3>Para usar la autenticación OAuth real:</h3>
+              <ol>
+                <li>Registra tu aplicación en <a href="https://console.cloud.google.com/" target="_blank">Google Cloud Console</a></li>
+                <li>Ve a "APIs & Services" > "Credentials"</li>
+                <li>Crea un "OAuth 2.0 Client IDs"</li>
+                <li>Configura "Authorized redirect URIs" con: <code>http://localhost:8093/auth/callback</code></li>
+                <li>Copia tu Client ID y Client Secret</li>
+              </ol>
+            </div>
+            
+            <div class="credentials-form">
+              <h3>Ingresa tus credenciales OAuth</h3>
+              <form id="credentialsForm">
+                <label for="clientId">Client ID:</label>
+                <input type="text" id="clientId" name="clientId" placeholder="Ingresa tu Client ID">
+                
+                <label for="clientSecret">Client Secret:</label>
+                <input type="password" id="clientSecret" name="clientSecret" placeholder="Ingresa tu Client Secret">
+                
+                <div style="margin-top: 15px;">
+                  <button type="submit">Guardar Credenciales</button>
+                  <button type="button" onclick="location.href='/'">Volver al inicio</button>
+                </div>
+              </form>
+              
+              <div id="statusMessage" style="margin-top: 15px; display: none;"></div>
+            </div>
+            
+            <script>
+              document.getElementById('credentialsForm').addEventListener('submit', function(e) {
+                e.preventDefault();
+                
+                const clientId = document.getElementById('clientId').value;
+                const clientSecret = document.getElementById('clientSecret').value;
+                
+                // Enviar credenciales al servidor
+                fetch('/auth/setup', {
+                  method: 'POST',
+                  headers: {
+                    'Content-Type': 'application/json'
+                  },
+                  body: JSON.stringify({ clientId, clientSecret })
+                })
+                .then(response => response.json())
+                .then(data => {
+                  const statusDiv = document.getElementById('statusMessage');
+                  statusDiv.style.display = 'block';
+                  
+                  if (data.success) {
+                    statusDiv.innerHTML = '<p style="color: green;">Credenciales guardadas exitosamente. <a href="/auth/google">Haz clic aquí para iniciar OAuth</a></p>';
+                    document.getElementById('credentialsForm').reset();
+                  } else {
+                    statusDiv.innerHTML = '<p style="color: red;">Error: ' + data.message + '</p>';
+                  }
+                })
+                .catch(error => {
+                  console.error('Error:', error);
+                  document.getElementById('statusMessage').innerHTML = '<p style="color: red;">Error al guardar credenciales</p>';
+                  document.getElementById('statusMessage').style.display = 'block';
+                });
+              });
+            </script>
+          </div>
+        </body>
+        </html>
+      `);
+      return;
+    }
+    
+    // Si las credenciales están configuradas, crear la URL de autorización OAuth
+    const redirectUri = encodeURIComponent('http://localhost:8093/auth/callback');
+    const scope = encodeURIComponent('email profile');
+    const authUrl = `https://accounts.google.com/o/oauth2/v2/auth?` +
+      `client_id=${clientId}&` +
+      `redirect_uri=${redirectUri}&` +
+      `response_type=code&` +
+      `scope=${scope}&` +
+      `access_type=offline&` +
+      `prompt=consent`;
+    
+    // Redirigir al usuario a la URL de autorización de Google
+    res.writeHead(302, { 'Location': authUrl });
+    res.end();
+  },
+
+  handleCallback: async (req, res) => {
+    const { code } = req.query;
+    
+    if (!code) {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'No authorization code received' }));
+      return;
+    }
+    
+    try {
+      // En una implementación real, intercambiaríamos el código por tokens de acceso
+      const clientId = process.env.OAUTH_CLIENT_ID;
+      const clientSecret = process.env.OAUTH_CLIENT_SECRET;
+      const redirectUri = 'http://localhost:8093/auth/callback';
+      
+      // Simular la obtención de tokens (en una implementación real, haríamos una solicitud HTTP real)
+      // Aquí es donde el framework realmente haría el trabajo pesado
+      
+      // Simular la obtención de información del usuario desde Google
+      // En una implementación real, usaríamos el access token para llamar a la API de Google
+      const userInfo = {
+        id: 'demo_user_id',
+        email: 'demo@example.com',
+        name: 'Demo User',
+        picture: 'https://via.placeholder.com/150'
+      };
+      
+      // Generar un token JWT para el usuario autenticado
+      const secret = 'super-secret-key-for-oauth-example';
+      const tokenPayload = {
+        userId: userInfo.id,
+        email: userInfo.email,
+        name: userInfo.name,
+        provider: 'google',
+        iat: Math.floor(Date.now() / 1000),
+        exp: Math.floor(Date.now() / 1000) + (60 * 60) // Expira en 1 hora
+      };
+      
+      const token = jwt.sign(tokenPayload, secret);
+      
+      // Enviar respuesta con el token
+      res.writeHead(200, { 'Content-Type': 'text/html' });
+      res.end(`
+        <h2>¡Autenticación OAuth exitosa!</h2>
+        <p>Usuario autenticado: <strong>${userInfo.name}</strong></p>
+        <p>Email: <strong>${userInfo.email}</strong></p>
+        <p>Proveedor: <strong>Google</strong></p>
+        
+        <div style="margin: 20px 0; padding: 15px; background-color: #d4edda; border: 1px solid #c3e6cb; border-radius: 4px;">
+          <p><strong>Token JWT generado:</strong></p>
+          <textarea readonly style="width: 100%; height: 80px; font-family: monospace;">${token}</textarea>
+          <p>Este token puede usarse en el header <code>Authorization: Bearer &lt;token&gt;</code> para acceder a endpoints protegidos</p>
+        </div>
+        
+        <p><a href="/profile">Ir al perfil del usuario</a> | <a href="/">Volver a la página principal</a></p>
+      `);
+    } catch (error) {
+      console.error('Error en el callback OAuth:', error);
+      res.writeHead(500, { 'Content-Type': 'text/html' });
+      res.end(`
+        <h2>Error en el proceso de autenticación</h2>
+        <p>${error.message}</p>
+        <p><a href="/auth/google">Intentar de nuevo</a></p>
+      `);
+    }
+  },
+  
+  setupCredentials: (req, res) => {
+    // Este endpoint es para fines de demostración
+    // En una implementación real, las credenciales se configurarían en variables de entorno
+    let body = '';
+    req.on('data', chunk => {
+      body += chunk.toString();
+    });
+    req.on('end', () => {
+      try {
+        const data = JSON.parse(body);
+        
+        // En una implementación real, esto se haría de forma segura
+        // Aquí solo simulamos el proceso para fines de demostración
+        
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ 
+          success: true, 
+          message: 'Credenciales recibidas. En una implementación real, estas se configurarían como variables de entorno.' 
+        }));
+      } catch (error) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ 
+          success: false, 
+          message: 'Error al procesar las credenciales' 
+        }));
+      }
+    });
+  }
+};
+
+module.exports = oauthController;

package/examples/v2_oauth/controllers/protectedController.js

@@ -0,0 +1,13 @@
+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(),
+      provider: 'Este contenido fue protegido usando autenticación JWT generada tras OAuth'
+    }));
+  }
+};
+
+module.exports = protectedController;

package/examples/v2_oauth/controllers/userController.js

@@ -0,0 +1,17 @@
+const userController = {
+  getProfile: (req, res) => {
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ 
+      profile: {
+        id: req.user.userId,
+        email: req.user.email,
+        name: req.user.name,
+        provider: req.user.provider,
+        authenticatedAt: new Date().toISOString()
+      },
+      message: 'Perfil de usuario obtenido exitosamente'
+    }));
+  }
+};
+
+module.exports = userController;

package/examples/v2_oauth/package.json

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

package/examples/v2_oauth/routes.json

@@ -0,0 +1,44 @@
+[
+  {
+    "path": "/",
+    "method": "GET",
+    "controller": "./controllers/mainController.js",
+    "handler": "home",
+    "auth": "none"
+  },
+  {
+    "path": "/auth/google",
+    "method": "GET",
+    "controller": "./controllers/oauthController.js",
+    "handler": "initiateGoogleAuth",
+    "auth": "none"
+  },
+  {
+    "path": "/auth/callback",
+    "method": "GET",
+    "controller": "./controllers/oauthController.js",
+    "handler": "handleCallback",
+    "auth": "none"
+  },
+  {
+    "path": "/auth/setup",
+    "method": "POST",
+    "controller": "./controllers/oauthController.js",
+    "handler": "setupCredentials",
+    "auth": "none"
+  },
+  {
+    "path": "/profile",
+    "method": "GET",
+    "controller": "./controllers/userController.js",
+    "handler": "getProfile",
+    "auth": "jwt-oauth"
+  },
+  {
+    "path": "/protected",
+    "method": "GET",
+    "controller": "./controllers/protectedController.js",
+    "handler": "getProtectedData",
+    "auth": "jwt-oauth"
+  }
+]

package/examples/v2_openapi/README.md

@@ -0,0 +1,77 @@
+# Ejemplo API con Funcionalidad OpenAPI
+
+Este ejemplo demuestra cómo crear una API con funcionalidad OpenAPI integrada utilizando el Framework JERK.
+
+## Características
+
+- API con autenticación JWT
+- Documentación OpenAPI 3.0 generada automáticamente
+- Interfaz Swagger UI para explorar y probar la API
+- Rutas protegidas y públicas
+- Controladores organizados por funcionalidad
+- Esquemas OpenAPI definidos para modelos de datos
+
+## Configuración
+
+No se requieren dependencias adicionales más allá del Framework JERK.
+
+## Uso
+
+1. Inicia el servidor:
+   ```bash
+   node app.js
+   ```
+
+2. El servidor escuchará en `http://localhost:8092`
+
+## Endpoints
+
+- `GET /` - Página de inicio
+- `POST /login` - Iniciar sesión y obtener token
+- `GET /users` - Lista de usuarios (requiere token)
+- `GET /products` - Lista de productos (requiere token)
+- `GET /profile` - Perfil de usuario (requiere token)
+- `GET /docs` - Documentación interactiva OpenAPI/Swagger
+- `GET /openapi.json` - Especificación OpenAPI
+
+## Ejemplo de uso
+
+1. Iniciar sesión:
+   ```bash
+   curl -X POST http://localhost:8092/login \
+     -H "Content-Type: application/json" \
+     -d '{"username": "admin", "password": "password"}'
+   ```
+
+2. Acceder a usuarios con el token:
+   ```bash
+   curl -X GET http://localhost:8092/users \
+     -H "Authorization: Bearer TU_TOKEN_AQUI"
+   ```
+
+3. Ver documentación interactiva:
+   Visita `http://localhost:8092/docs` en tu navegador
+
+## Estructura del proyecto
+
+```
+examples/v2_openapi/
+├── app.js              # Punto de entrada de la aplicación
+├── routes.json         # Definición de rutas
+├── controllers/        # Controladores de las rutas
+│   ├── mainController.js
+│   ├── authController.js
+│   ├── userController.js
+│   └── productController.js
+└── README.md
+```
+
+## Documentación OpenAPI
+
+El framework genera automáticamente:
+- Una especificación OpenAPI 3.0 en `/openapi.json`
+- Una interfaz Swagger UI interactiva en `/docs`
+- Esquemas de datos definidos para reutilización
+- Documentación detallada de endpoints, parámetros y respuestas
+- Soporte para diferentes códigos de respuesta HTTP
+- Definición de esquemas de seguridad