jerkjs 2.0.1 → 2.0.2

package/docs/OAUTH2_GOOGLE_MANUAL.md

@@ -0,0 +1,405 @@
+# Manual para Implementar OAuth 2.0 con Google usando el Framework API SDK
+
+## Índice
+1. [Introducción](#introducción)
+2. [Requisitos Previos](#requisitos-previos)
+3. [Configuración en Google Cloud Console](#configuración-en-google-cloud-console)
+4. [Configuración del Framework API SDK](#configuración-del-framework-api-sdk)
+5. [Implementación del Flujo OAuth 2.0](#implementación-del-flujo-oauth-20)
+6. [Manejo de Tokens](#manejo-de-tokens)
+7. [Protección de Endpoints](#protección-de-endpoints)
+8. [Consideraciones de Seguridad](#consideraciones-de-seguridad)
+9. [Depuración y Troubleshooting](#depuración-y-troubleshooting)
+
+## Introducción
+
+OAuth 2.0 es un protocolo de autorización que permite a aplicaciones de terceros obtener acceso limitado a cuentas de usuario de un servicio web. En este manual, aprenderás cómo implementar OAuth 2.0 con Google usando el Framework API SDK.
+
+## Requisitos Previos
+
+- Cuenta de Google
+- Acceso a Google Cloud Console
+- Node.js instalado
+- Framework API SDK instalado
+- Conocimientos básicos de JavaScript y APIs REST
+
+## Configuración en Google Cloud Console
+
+### Paso 1: Crear un proyecto en Google Cloud Console
+
+1. Accede a [Google Cloud Console](https://console.cloud.google.com/)
+2. Haz clic en "Seleccionar un proyecto" o "Nuevo proyecto"
+3. Ingresa un nombre para tu proyecto
+4. Haz clic en "Crear"
+
+### Paso 2: Habilitar Google+ API (o las APIs que necesites)
+
+1. En el panel lateral izquierdo, haz clic en "APIs y servicios" > "Biblioteca"
+2. Busca "Google+ API" o las APIs que planeas usar (como People API)
+3. Haz clic en "Habilitar"
+
+### Paso 3: Crear credenciales OAuth 2.0
+
+1. En el panel lateral izquierdo, haz clic en "APIs y servicios" > "Credenciales"
+2. Haz clic en "Crear credenciales" > "ID de cliente OAuth 2.0"
+3. Si aún no has configurado el consentimiento OAuth, haz clic en "Configurar pantalla de consentimiento OAuth"
+4. Completa la información de la pantalla de consentimiento:
+   - Tipo de usuario: Público o Interno (según tu necesidad)
+   - Ingresa un nombre de aplicación
+   - Agrega direcciones de correo electrónico de desarrolladores
+   - Ingresa un dominio de aplicación (si aplica)
+5. Guarda la configuración de consentimiento
+
+### Paso 4: Configurar las credenciales
+
+1. De vuelta en la página de credenciales, haz clic en "Crear credenciales" > "ID de cliente OAuth 2.0"
+2. Selecciona "Aplicación web" como tipo de aplicación
+3. Ingresa un nombre para las credenciales
+4. En "URI de redirección autorizados", agrega las siguientes URLs:
+   - `http://localhost:8093/auth/callback` (ajusta el puerto según tu configuración)
+   - `http://localhost:3000/auth/callback` (si usas otro puerto)
+   - Cualquier otra URL de callback que vayas a usar
+5. Haz clic en "Crear"
+6. Guarda el "ID de cliente" y el "Secreto de cliente" que se mostrarán
+
+## Configuración del Framework API SDK
+
+### Paso 1: Instalar el Framework API SDK
+
+```bash
+npm install apisdk
+```
+
+### Paso 2: Configurar variables de entorno
+
+Crea un archivo `.env` en la raíz de tu proyecto:
+
+```env
+OAUTH_CLIENT_ID=tu_client_id_aqui
+OAUTH_CLIENT_SECRET=tu_client_secret_aqui
+OAUTH_CALLBACK_URL=http://localhost:8093/auth/callback
+```
+
+### Paso 3: Importar los componentes necesarios
+
+```javascript
+const {
+  APIServer,
+  Authenticator,
+  RouteLoader,
+  Logger,
+  TokenManager
+} = require('apisdk');
+```
+
+## Implementación del Flujo OAuth 2.0
+
+### Paso 1: Configurar el servidor y autenticador
+
+```javascript
+const server = new APIServer({
+  port: 8093,
+  host: 'localhost'
+});
+
+const authenticator = new Authenticator({ logger });
+
+// Registrar la estrategia OAuth2
+authenticator.use('google-oauth', authenticator.oauth2Strategy({
+  clientId: process.env.OAUTH_CLIENT_ID,
+  clientSecret: process.env.OAUTH_CLIENT_SECRET,
+  callbackURL: process.env.OAUTH_CALLBACK_URL,
+  authorizationURL: 'https://accounts.google.com/o/oauth2/v2/auth',
+  tokenURL: 'https://oauth2.googleapis.com/token'
+}));
+
+// Agregar autenticador al servidor
+server.authenticator = authenticator;
+```
+
+### Paso 2: Crear el endpoint para iniciar OAuth
+
+```javascript
+// Ruta para iniciar el flujo OAuth
+router.get('/auth/google', (req, res) => {
+  // El framework maneja la redirección a Google
+  const authMiddleware = authenticator.authenticate('google-oauth');
+  authMiddleware(req, res, () => {});
+});
+```
+
+### Paso 3: Crear el endpoint de callback
+
+```javascript
+// Ruta para manejar el callback de OAuth
+router.get('/auth/callback', async (req, res) => {
+  try {
+    // El framework maneja la autenticación y el intercambio de código por token
+    const authMiddleware = authenticator.authenticate('google-oauth', {
+      failureRedirect: '/login'
+    });
+    
+    // Ejecutar middleware de autenticación
+    authMiddleware(req, res, async () => {
+      // Si llegamos aquí, la autenticación fue exitosa
+      if (req.user) {
+        // Generar token JWT para el usuario autenticado
+        const token = jwt.sign({
+          userId: req.user.id,
+          email: req.user.email,
+          name: req.user.name
+        }, process.env.JWT_SECRET);
+        
+        // Redirigir con token o mostrar página de éxito
+        res.writeHead(302, { 'Location': `/dashboard?token=${token}` });
+        res.end();
+      } else {
+        res.writeHead(401, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Autenticación fallida' }));
+      }
+    });
+  } catch (error) {
+    console.error('Error en callback OAuth:', error);
+    res.writeHead(500, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Error interno del servidor' }));
+  }
+});
+```
+
+## Manejo de Tokens
+
+### Paso 1: Configurar TokenManager
+
+```javascript
+const tokenManager = new TokenManager({
+  storage: 'memory' // Opciones: 'memory', 'json', 'database'
+});
+```
+
+### Paso 2: Generar tokens JWT
+
+```javascript
+// Generar token JWT después de autenticación exitosa
+const generateToken = (userData) => {
+  return jwt.sign(
+    { 
+      userId: userData.id,
+      email: userData.email,
+      name: userData.name,
+      provider: 'google'
+    },
+    process.env.JWT_SECRET,
+    { expiresIn: '1h' }
+  );
+};
+```
+
+### Paso 3: Validar tokens
+
+```javascript
+// Middleware para validar tokens JWT
+const validateToken = (req, res, next) => {
+  const authHeader = req.headers.authorization;
+  const token = authHeader && authHeader.split(' ')[1]; // Bearer TOKEN
+
+  if (!token) {
+    res.writeHead(401, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Token no proporcionado' }));
+    return;
+  }
+
+  jwt.verify(token, process.env.JWT_SECRET, (err, decoded) => {
+    if (err) {
+      res.writeHead(403, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Token inválido' }));
+      return;
+    }
+    
+    req.user = decoded;
+    next();
+  });
+};
+```
+
+## Protección de Endpoints
+
+### Paso 1: Proteger rutas individuales
+
+```javascript
+// Proteger una ruta específica
+router.get('/profile', validateToken, (req, res) => {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({
+    user: req.user,
+    message: 'Perfil de usuario protegido'
+  }));
+});
+```
+
+### Paso 2: Proteger rutas usando el framework
+
+```javascript
+// Usar la estrategia JWT del framework
+authenticator.use('jwt-auth', (req, options = {}) => {
+  const authHeader = req.headers.authorization;
+  const token = authHeader && authHeader.split(' ')[1];
+
+  if (!token) return false;
+
+  try {
+    const decoded = jwt.verify(token, process.env.JWT_SECRET);
+    req.user = decoded;
+    return true;
+  } catch (error) {
+    return false;
+  }
+});
+
+// Proteger ruta con autenticación JWT
+router.get('/protected', authenticator.authenticate('jwt-auth'), (req, res) => {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ message: 'Contenido protegido', user: req.user }));
+});
+```
+
+## Consideraciones de Seguridad
+
+### 1. Almacenamiento de credenciales
+
+- Nunca almacenes credenciales en el código fuente
+- Usa variables de entorno o servicios de gestión de secretos
+- Rotar periódicamente los secrets
+
+### 2. Validación de tokens
+
+- Siempre valida tokens antes de conceder acceso
+- Implementa expiración de tokens
+- Considera usar refresh tokens para largas sesiones
+
+### 3. Configuración de Google
+
+- Limita las URLs de redirección a solo las que necesitas
+- Usa HTTPS en producción
+- Monitorea el uso de tus credenciales
+
+### 4. Manejo de errores
+
+- No reveles información sensible en mensajes de error
+- Implementa logging adecuado para auditoría
+- Maneja correctamente los casos de fallo de autenticación
+
+## Depuración y Troubleshooting
+
+### Problemas comunes y soluciones
+
+#### 1. Error: "redirect_uri_mismatch"
+- **Causa**: La URL de redirección no coincide con las registradas en Google Cloud Console
+- **Solución**: Verifica que la URL en tu código coincida exactamente con las registradas
+
+#### 2. Error: "invalid_client"
+- **Causa**: Client ID o Client Secret incorrectos
+- **Solución**: Verifica que las credenciales sean correctas y no estén truncadas
+
+#### 3. Token expirado
+- **Causa**: El access token ha expirado
+- **Solución**: Implementa refresh tokens o solicita nuevo acceso
+
+### Herramientas de depuración
+
+```javascript
+// Habilitar logging detallado
+const logger = new Logger({ level: 'debug' });
+
+// Verificar estado de autenticación
+console.log('Usuario autenticado:', req.user);
+console.log('Headers:', req.headers);
+console.log('Query params:', req.query);
+```
+
+### Pruebas
+
+```javascript
+// Prueba de endpoint protegido
+const testProtectedEndpoint = async (token) => {
+  const response = await fetch('http://localhost:8093/protected', {
+    headers: {
+      'Authorization': `Bearer ${token}`
+    }
+  });
+  
+  const data = await response.json();
+  console.log('Respuesta del endpoint protegido:', data);
+};
+```
+
+## Ejemplo Completo
+
+Aquí tienes un ejemplo completo de implementación:
+
+```javascript
+const {
+  APIServer,
+  Authenticator,
+  Router,
+  Logger
+} = require('apisdk');
+
+const jwt = require('jsonwebtoken');
+
+async function startServer() {
+  const server = new APIServer({
+    port: 8093,
+    host: 'localhost'
+  });
+
+  const logger = new Logger({ level: 'info' });
+  const router = new Router();
+  const authenticator = new Authenticator({ logger });
+
+  // Configurar estrategia OAuth2
+  authenticator.use('google-oauth', authenticator.oauth2Strategy({
+    clientId: process.env.OAUTH_CLIENT_ID,
+    clientSecret: process.env.OAUTH_CLIENT_SECRET,
+    callbackURL: process.env.OAUTH_CALLBACK_URL,
+  }));
+
+  // Agregar autenticador al servidor
+  server.authenticator = authenticator;
+
+  // Ruta para iniciar OAuth
+  router.get('/auth/google', (req, res) => {
+    authenticator.authenticate('google-oauth')(req, res, () => {});
+  });
+
+  // Ruta de callback
+  router.get('/auth/callback', (req, res) => {
+    authenticator.authenticate('google-oauth', {
+      successRedirect: '/dashboard',
+      failureRedirect: '/login'
+    })(req, res, () => {});
+  });
+
+  // Ruta protegida
+  router.get('/dashboard', (req, res) => {
+    if (req.user) {
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ message: 'Bienvenido al dashboard', user: req.user }));
+    } else {
+      res.writeHead(401, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'No autorizado' }));
+    }
+  });
+
+  // Agregar rutas al servidor
+  for (const route of router.getRoutes()) {
+    server.addRoute(route.method, route.path, route.handler);
+  }
+
+  server.start();
+  logger.info('Servidor iniciado en http://localhost:8093');
+}
+
+startServer();
+```
+
+Este manual proporciona una guía completa para implementar OAuth 2.0 con Google usando el Framework API SDK, desde la configuración inicial hasta la implementación completa y consideraciones de seguridad.

package/docs/frontend-and-sessions.md

@@ -47,7 +47,7 @@ El framework ahora puede servir diferentes tipos de contenido:
 Para usar el sistema de sesiones, primero debes configurar el middleware en tu aplicación:
 
 ```javascript
-const { APIServer, SessionManager, Cors } = require('jerkjs');
+const { APIServer, SessionManager, Cors } = require('@apisdkjs/apisdkjs');
 
 async function startServer() {
   const server = new APIServer({
@@ -187,7 +187,7 @@ El sistema de sesiones está completamente integrado con el sistema de hooks, fi
 #### Registrar actividad de sesión
 
 ```javascript
-const { hooks } = require('jerkjs');
+const { hooks } = require('@apisdkjs/apisdkjs');
 
 // Registrar cuando se crea una sesión
 hooks.addAction('session_created', (sessionId, sessionData) => {
@@ -203,7 +203,7 @@ hooks.addAction('session_destroyed', (sessionId, sessionData) => {
 #### Modificar datos de sesión antes de crearla
 
 ```javascript
-const { hooks } = require('jerkjs');
+const { hooks } = require('@apisdkjs/apisdkjs');
 
 // Añadir información de IP y fecha a los datos de sesión
 hooks.addFilter('session_create_data', (userData, req) => {
@@ -218,7 +218,7 @@ hooks.addFilter('session_create_data', (userData, req) => {
 #### Personalizar el manejo de autenticación fallida
 
 ```javascript
-const { hooks } = require('jerkjs');
+const { hooks } = require('@apisdkjs/apisdkjs');
 
 // Registrar intentos de acceso no autorizado
 hooks.addAction('session_auth_failed', (req, res, redirectTo) => {
@@ -235,7 +235,7 @@ hooks.addAction('session_auth_failed', (req, res, redirectTo) => {
 #### Extender datos de sesión durante la actualización
 
 ```javascript
-const { hooks } = require('jerkjs');
+const { hooks } = require('@apisdkjs/apisdkjs');
 
 // Añadir marca de tiempo a cada actualización de sesión
 hooks.addFilter('session_update_data', (newData, req, sessionId) => {
@@ -259,7 +259,7 @@ const {
   Logger,
   Cors,
   SessionManager
-} = require('jerkjs');
+} = require('@apisdkjs/apisdkjs');
 
 async function startServer() {
   const server = new APIServer({

package/examples/advanced/controllers/productController.js

@@ -0,0 +1,64 @@
+/**
+ * Controlador de ejemplo para productos
+ * Archivo: examples/advanced/controllers/productController.js
+ */
+
+// Simulación de base de datos de productos
+let products = [
+  { id: 1, name: 'Laptop', price: 1000, category: 'Electronics' },
+  { id: 2, name: 'Mouse', price: 25, category: 'Accessories' }
+];
+
+// Obtener todos los productos
+function getProducts(req, res) {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({ 
+    success: true,
+    data: products
+  }));
+}
+
+// Actualizar un producto por ID
+function updateProduct(req, res) {
+  try {
+    const productId = parseInt(req.params.id);
+    const { name, price, category } = req.body;
+
+    const productIndex = products.findIndex(p => p.id === productId);
+
+    if (productIndex === -1) {
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ 
+        success: false,
+        message: 'Producto no encontrado'
+      }));
+      return;
+    }
+
+    // Actualizar producto
+    products[productIndex] = {
+      ...products[productIndex],
+      ...(name && { name }),
+      ...(price && { price }),
+      ...(category && { category })
+    };
+
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ 
+      success: true,
+      data: products[productIndex]
+    }));
+  } catch (error) {
+    res.writeHead(500, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ 
+      success: false,
+      message: 'Error al actualizar producto'
+    }));
+  }
+}
+
+// Exportar handlers
+module.exports = {
+  getProducts,
+  updateProduct
+};

package/examples/advanced/controllers/userController.js

@@ -0,0 +1,85 @@
+/**
+ * Controlador de ejemplo para usuarios
+ * Archivo: examples/basic/controllers/userController.js
+ */
+
+// Simulación de base de datos
+let users = [
+  { id: 1, name: 'John Doe', email: 'john@example.com' },
+  { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
+];
+
+// Obtener todos los usuarios
+function getUsers(req, res) {
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({
+    success: true,
+    data: users
+  }));
+}
+
+// Obtener un usuario por ID
+function getUserById(req, res) {
+  const userId = parseInt(req.params.id);
+  const user = users.find(u => u.id === userId);
+
+  if (!user) {
+    res.writeHead(404, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      success: false,
+      message: 'Usuario no encontrado'
+    }));
+    return;
+  }
+
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify({
+    success: true,
+    data: user
+  }));
+}
+
+// Crear un nuevo usuario
+function createUser(req, res) {
+  try {
+    const { name, email } = req.body;
+
+    // Validar datos
+    if (!name || !email) {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({
+        success: false,
+        message: 'Nombre y correo electrónico son requeridos'
+      }));
+      return;
+    }
+
+    // Crear nuevo usuario
+    const newUser = {
+      id: users.length + 1,
+      name,
+      email
+    };
+
+    users.push(newUser);
+
+    res.writeHead(201, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      success: true,
+      data: newUser
+    }));
+  } catch (error) {
+    res.writeHead(500, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({
+      success: false,
+      message: 'Error al crear usuario'
+    }));
+  }
+}
+
+// Exportar handlers
+module.exports = {
+  getUsers,
+  getUserById,
+  createUser
+};

package/examples/advanced/routes.json

@@ -0,0 +1,51 @@
+[
+  {
+    "path": "/api/users",
+    "method": "GET",
+    "auth": "jwt",
+    "authOptions": {
+      "jwtSecret": "secret-jwt-key"
+    },
+    "controller": "./basic/controllers/userController.js",
+    "handler": "getUsers"
+  },
+  {
+    "path": "/api/users/:id",
+    "method": "GET",
+    "auth": "jwt",
+    "authOptions": {
+      "jwtSecret": "secret-jwt-key"
+    },
+    "controller": "./basic/controllers/userController.js",
+    "handler": "getUserById"
+  },
+  {
+    "path": "/api/users",
+    "method": "POST",
+    "auth": "apiKey",
+    "authOptions": {
+      "apiKeyHeader": "X-API-Key",
+      "apiKeyValues": ["secret-key-123"]
+    },
+    "controller": "./basic/controllers/userController.js",
+    "handler": "createUser"
+  },
+  {
+    "path": "/api/products",
+    "method": "GET",
+    "auth": "none",
+    "controller": "./advanced/controllers/productController.js",
+    "handler": "getProducts"
+  },
+  {
+    "path": "/api/products/:id",
+    "method": "PUT",
+    "auth": "apiKey",
+    "authOptions": {
+      "apiKeyHeader": "X-API-Key",
+      "apiKeyValues": ["secret-key-123"]
+    },
+    "controller": "./advanced/controllers/productController.js",
+    "handler": "updateProduct"
+  }
+]