backend-mcp/docs/JWT_AUTHENTICATION.md

Generador automático de backends con Node.js, Express, Prisma y módulos configurables. Servidor MCP compatible con npx para agentes IA. Soporta PostgreSQL, MySQL, MongoDB y SQLite.

# Autenticación JWT para Backend MCP

## Descripción General

Backend MCP utiliza un sistema de autenticación basado en JWT (JSON Web Tokens) para proteger el acceso a sus herramientas mientras mantiene el código fuente completamente abierto en NPM. Esta estrategia permite:

- **Transparencia**: El código es visible y auditable
- **Monetización**: El acceso funcional requiere suscripción
- **Escalabilidad**: Diferentes planes con distintas capacidades
- **Seguridad**: Tokens con expiración y validación remota

## Planes y Precios

### Plan Básico - $5 USD/mes
- ✅ Todas las herramientas básicas de generación
- ✅ Configuración de bases de datos
- ✅ Creación de endpoints y modelos
- ✅ Soporte por email
- 📊 1,000 llamadas/mes
- 📊 10 proyectos activos
- 📊 3 conexiones de BD

### Plan Premium - $15 USD/mes
- ✅ Todo lo del plan Básico
- ✅ Herramientas de Docker y CI/CD
- ✅ Optimización de rendimiento
- ✅ Configuración de caché y monitoreo
- ✅ Soporte prioritario
- 📊 5,000 llamadas/mes
- 📊 50 proyectos activos
- 📊 10 conexiones de BD

### Plan Enterprise - $50 USD/mes
- ✅ Todo lo del plan Premium
- ✅ Herramientas de microservicios
- ✅ Configuración de load balancers
- ✅ Service mesh y observabilidad
- ✅ Soporte 24/7 + consultoría
- 📊 Llamadas ilimitadas
- 📊 Proyectos ilimitados
- 📊 Conexiones ilimitadas

## Configuración

### 1. Obtener Token JWT

1. Visita [https://backend-mcp.com/pricing](https://backend-mcp.com/pricing)
2. Selecciona tu plan preferido
3. Completa el pago con Stripe
4. Recibe tu token JWT por email
5. Gestiona tus tokens en [https://backend-mcp.com/dashboard](https://backend-mcp.com/dashboard)

### 2. Configurar el Token

#### Opción A: Línea de Comandos
```bash
npx backend-mcp postgresql://localhost:5432/db --jwt "tu_token_aqui"
```

#### Opción B: Variable de Entorno
```bash
export BACKEND_MCP_JWT="tu_token_aqui"
npx backend-mcp postgresql://localhost:5432/db
```

#### Opción C: Configuración MCP (Recomendado para Agentes de IA)

Para agentes de IA que usan MCP (Model Context Protocol), esta es la forma más eficiente de configurar el token JWT:

```json
{
  "mcpServers": {
    "BackendGenerator": {
      "command": "npx",
      "args": ["-y", "backend-mcp", "postgresql://user:pass@localhost:5432/db"],
      "env": {
        "BACKEND_MCP_JWT": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VySWQiOiJkZW1vLXVzZXIiLCJwbGFuIjoicHJlbWl1bSIsInBlcm1pc3Npb25zIjpbImJhc2ljIiwicHJlbWl1bSJdLCJpYXQiOjE3MzQ5NzQ0MDAsImV4cCI6MTczNzU2NjQwMCwiaXNzIjoiYmFja2VuZC1tY3AifQ.example_signature"
      }
    }
  }
}
```

**Ventajas de esta configuración:**
- ✅ **Acceso inmediato**: La IA tiene acceso completo desde el primer uso
- ✅ **Sin interrupciones**: No necesita solicitar tokens durante la conversación
- ✅ **Máxima eficiencia**: Todas las herramientas disponibles según el plan
- ✅ **Experiencia fluida**: El usuario no necesita gestionar tokens manualmente

**Configuración por Plan:**

```json
// Plan Básico ($5/mes)
{
  "mcpServers": {
    "BackendGenerator": {
      "command": "npx",
      "args": ["-y", "backend-mcp", "postgresql://user:pass@localhost:5432/db"],
      "env": {
        "BACKEND_MCP_JWT": "tu_token_basico_aqui"
      }
    }
  }
}

// Plan Premium ($15/mes) - Recomendado
{
  "mcpServers": {
    "BackendGenerator": {
      "command": "npx",
      "args": ["-y", "backend-mcp", "postgresql://user:pass@localhost:5432/db"],
      "env": {
        "BACKEND_MCP_JWT": "tu_token_premium_aqui"
      }
    }
  }
}

// Plan Enterprise ($50/mes)
{
  "mcpServers": {
    "BackendGenerator": {
      "command": "npx",
      "args": ["-y", "backend-mcp", "postgresql://user:pass@localhost:5432/db"],
      "env": {
        "BACKEND_MCP_JWT": "tu_token_enterprise_aqui"
      }
    }
  }
}
```

#### Opción D: Archivo .env
```env
BACKEND_MCP_JWT=tu_token_aqui
DATABASE_URL=postgresql://localhost:5432/db
```

## Herramientas por Plan

### Herramientas Básicas (Todos los planes)
- `configure_project` - Configuración inicial del proyecto
- `create_endpoint` - Creación de endpoints REST
- `configure_database` - Configuración de base de datos
- `setup_auth` - Configuración de autenticación
- `create_model` - Creación de modelos de datos
- `create_controller` - Creación de controladores
- `create_service` - Creación de servicios
- `create_middleware` - Creación de middleware
- `setup_validation` - Configuración de validaciones
- `create_migration` - Creación de migraciones

### Herramientas Premium (Premium y Enterprise)
- `setup_docker` - Configuración de Docker
- `setup_ci_cd` - Configuración de CI/CD
- `optimize_performance` - Optimización de rendimiento
- `setup_caching` - Configuración de caché
- `setup_monitoring` - Configuración de monitoreo
- `create_tests` - Generación de pruebas
- `setup_security` - Configuración de seguridad
- `analyze_code` - Análisis de código

### Herramientas Enterprise (Solo Enterprise)
- `setup_microservices` - Configuración de microservicios
- `setup_load_balancer` - Configuración de load balancer
- `setup_message_queue` - Configuración de colas de mensajes
- `setup_distributed_cache` - Configuración de caché distribuido
- `setup_api_gateway` - Configuración de API Gateway
- `setup_service_mesh` - Configuración de service mesh
- `setup_observability` - Configuración de observabilidad
- `setup_disaster_recovery` - Configuración de recuperación

## Desarrollo y Testing

### Tokens de Demostración

Para desarrollo y testing, puedes usar tokens de demostración:

```bash
# Generar tokens de demo
npm run auth:demo

# Usar token de demo
npx backend-mcp --jwt "demo_basic_token_2024" postgresql://localhost:5432/db
```

### Bypass de Autenticación (Solo Desarrollo)

```bash
# Activar bypass en desarrollo
export NODE_ENV=development
export BYPASS_AUTH=true

# Ahora funciona sin token
npx backend-mcp postgresql://localhost:5432/db
```

### Validar Token

```bash
# Validar un token específico
npm run auth:validate "tu_token_aqui"
```

## Arquitectura Técnica

### Flujo de Autenticación

1. **Extracción del Token**: El sistema busca el JWT en:
   - Argumentos de línea de comandos (`--jwt`)
   - Variables de entorno (`BACKEND_MCP_JWT`)
   - Parámetros de mensaje MCP
   - Headers HTTP (para APIs)

2. **Validación del Token**:
   - Verificación de firma HMAC-SHA256
   - Validación de expiración
   - Verificación del emisor
   - Consulta a API de validación remota

3. **Verificación de Permisos**:
   - Mapeo de herramienta a plan requerido
   - Verificación de permisos del usuario
   - Validación de límites de uso

4. **Caché de Tokens**:
   - Caché en memoria por 5 minutos
   - Reducción de llamadas a API
   - Invalidación automática

### Estructura del JWT

```json
{
  "header": {
    "alg": "HS256",
    "typ": "JWT"
  },
  "payload": {
    "iss": "backend-mcp-auth",
    "sub": "user_id_123",
    "email": "usuario@ejemplo.com",
    "plan": "premium",
    "permissions": ["basic", "premium"],
    "iat": 1703980800,
    "exp": 1706572800
  }
}
```

### API de Validación

La API de validación está desplegada en Vercel y proporciona:

- `POST /api/auth/validate` - Validar token
- `POST /api/auth/refresh` - Renovar token
- `POST /api/auth/revoke` - Revocar token
- `GET /api/plans` - Información de planes

## Manejo de Errores

### Códigos de Error

- `AUTH_REQUIRED` - Token no proporcionado
- `INVALID_TOKEN` - Token inválido o expirado
- `INSUFFICIENT_PERMISSIONS` - Plan insuficiente para la herramienta
- `NETWORK_ERROR` - Error de conexión con API
- `RATE_LIMIT_EXCEEDED` - Límite de uso excedido

### Mensajes de Error

```bash
# Sin token
🔐 Autenticación requerida. Obtén tu token JWT en https://backend-mcp.com/pricing por solo $5 USD/mes.

# Token inválido
❌ Token JWT inválido o expirado. Verifica tu token o renuévalo en https://backend-mcp.com/dashboard

# Permisos insuficientes
🚫 Permisos insuficientes. Esta herramienta requiere un plan superior. Actualiza en https://backend-mcp.com/upgrade

# Error de red
🌐 Error de conexión con el servidor de autenticación. Verifica tu conexión a internet.
```

## Seguridad

### Mejores Prácticas

1. **Nunca hardcodees tokens** en el código fuente
2. **Usa variables de entorno** para tokens en producción
3. **Rota tokens regularmente** (cada 30 días)
4. **Monitorea el uso** desde el dashboard
5. **Revoca tokens comprometidos** inmediatamente

### Protección de Tokens

- Los tokens tienen expiración automática
- Validación de firma criptográfica
- Revocación instantánea desde dashboard
- Monitoreo de uso anómalo
- Rate limiting por plan

## Migración y Actualización

### Desde Versión Gratuita

1. Instala la nueva versión: `npm install -g backend-mcp@latest`
2. Obtén tu token JWT en el sitio web
3. Configura el token según las opciones anteriores
4. ¡Listo! Todas tus configuraciones existentes funcionarán

### Actualización de Plan

1. Ve a [https://backend-mcp.com/dashboard](https://backend-mcp.com/dashboard)
2. Selecciona "Actualizar Plan"
3. Elige tu nuevo plan
4. El token existente se actualiza automáticamente
5. Las nuevas herramientas estarán disponibles inmediatamente

## Soporte

### Recursos de Ayuda

- 📖 [Documentación Completa](https://backend-mcp.com/docs)
- 💬 [Soporte por Email](mailto:support@backend-mcp.com)
- 🐛 [Reportar Bugs](https://github.com/backend-mcp/issues)
- 💡 [Solicitar Features](https://backend-mcp.com/feature-requests)

### FAQ

**P: ¿Puedo usar Backend MCP sin pagar?**
R: El código es open source y visible, pero las herramientas funcionales requieren suscripción. Ofrecemos tokens de demostración para testing.

**P: ¿Qué pasa si mi token expira?**
R: Recibirás notificaciones por email antes del vencimiento. Puedes renovar desde el dashboard o configurar renovación automática.

**P: ¿Puedo cambiar de plan en cualquier momento?**
R: Sí, puedes actualizar o degradar tu plan desde el dashboard. Los cambios son efectivos inmediatamente.

**P: ¿Los tokens funcionan offline?**
R: Los tokens se validan online, pero hay un caché local de 5 minutos. Para uso completamente offline, considera el plan Enterprise con validación local.

**P: ¿Hay descuentos por pago anual?**
R: Sí, ofrecemos 20% de descuento en planes anuales. Contacta a ventas para más detalles.

---

*Backend MCP - Generación de backends profesionales con autenticación JWT segura*