@qubiit/lmagent 2.5.0

package/rules/security.md

@@ -0,0 +1,316 @@
+# LMAgent Security Rules
+
+> **Tipo**: `rule` | **Versión**: 2.1 | **Actualización**: 2026-01
+
+## 📌 Quick Reference
+
+| Principio | Regla |
+|-----------|-------|
+| **Secrets** | NUNCA en código. Siempre `os.getenv()` o Vault. |
+| **Passwords** | bcrypt/argon2. NUNCA MD5/SHA1. |
+| **JWT** | RS256 preferido. Access token = 15 min máx. |
+| **SQL** | Queries parametrizadas SIEMPRE. Nunca f-strings. |
+| **Inputs** | Validar con Pydantic. Never trust user input. |
+| **Headers** | HTTPS + HSTS + CSP obligatorios en prod. |
+
+### 👥 Roles que usan esta regla
+`security-analyst`, `backend-engineer`, `devops-engineer`, `architect`
+
+---
+
+Este documento define las reglas y mejores prácticas de seguridad del framework.
+
+## 🔐 Principios Generales
+
+1. **Defense in Depth**: Múltiples capas de seguridad
+2. **Least Privilege**: Mínimos permisos necesarios
+3. **Secure by Default**: Configuración segura por defecto
+4. **Zero Trust**: No confiar en ningún input
+
+---
+
+## Autenticación
+
+### JWT Best Practices
+
+```python
+# ✅ BUENO
+JWT_SETTINGS = {
+    "algorithm": "RS256",  # Asimétrico
+    "access_token_expire": 15,  # minutos
+    "refresh_token_expire": 7 * 24 * 60,  # 7 días
+}
+
+# ❌ MALO
+JWT_SETTINGS = {
+    "algorithm": "HS256",  # Simétrico con secret débil
+    "access_token_expire": 60 * 24 * 365,  # 1 año
+}
+```
+
+### Password Storage
+
+```python
+# Usar bcrypt o argon2
+from passlib.context import CryptContext
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+def hash_password(password: str) -> str:
+    return pwd_context.hash(password)
+
+def verify_password(plain: str, hashed: str) -> bool:
+    return pwd_context.verify(plain, hashed)
+```
+
+### MFA
+
+- Implementar TOTP para cuentas sensibles
+- Usar librerías probadas (pyotp)
+- Backup codes obligatorios
+
+---
+
+## Autorización
+
+### RBAC Pattern
+
+```python
+class Permission(Enum):
+    READ_USERS = "users:read"
+    WRITE_USERS = "users:write"
+    DELETE_USERS = "users:delete"
+    ADMIN = "*"
+
+class Role:
+    ADMIN = [Permission.ADMIN]
+    EDITOR = [Permission.READ_USERS, Permission.WRITE_USERS]
+    VIEWER = [Permission.READ_USERS]
+```
+
+### Middleware de Autorización
+
+```python
+def require_permission(permission: Permission):
+    async def dependency(user: User = Depends(get_current_user)):
+        if not user.has_permission(permission):
+            raise HTTPException(status_code=403, detail="Forbidden")
+        return user
+    return Depends(dependency)
+
+@router.delete("/users/{id}")
+async def delete_user(
+    id: str,
+    user: User = require_permission(Permission.DELETE_USERS)
+):
+    ...
+```
+
+---
+
+## Input Validation
+
+### Pydantic Validators
+
+```python
+from pydantic import BaseModel, EmailStr, Field, validator
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: str = Field(min_length=8, max_length=128)
+    name: str = Field(min_length=1, max_length=100)
+    
+    @validator("password")
+    def password_strength(cls, v):
+        if not any(c.isupper() for c in v):
+            raise ValueError("Password must contain uppercase")
+        if not any(c.isdigit() for c in v):
+            raise ValueError("Password must contain digit")
+        return v
+```
+
+### SQL Injection Prevention
+
+```python
+# ✅ BUENO: Parameterized queries
+await conn.execute(
+    "SELECT * FROM users WHERE email = $1",
+    email
+)
+
+# ❌ MALO: String interpolation
+await conn.execute(
+    f"SELECT * FROM users WHERE email = '{email}'"
+)
+```
+
+### XSS Prevention
+
+```typescript
+// ✅ BUENO: React escapa automáticamente
+<div>{userInput}</div>
+
+// ❌ MALO: dangerouslySetInnerHTML
+<div dangerouslySetInnerHTML={{ __html: userInput }} />
+
+// Si necesitas HTML, sanitizar primero
+import DOMPurify from 'dompurify';
+<div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(html) }} />
+```
+
+---
+
+## Secrets Management
+
+### Variables de Entorno
+
+```bash
+# .env (NUNCA en git)
+DATABASE_URL=postgresql://user:pass@localhost/db
+JWT_SECRET_KEY=super-secret-key
+API_KEY=sk_live_xxxx
+```
+
+### Nunca en Código
+
+```python
+# ❌ MALO
+API_KEY = "sk_live_1234567890"
+
+# ✅ BUENO
+API_KEY = os.getenv("API_KEY")
+```
+
+### Rotación de Secrets
+
+- Rotar cada 90 días (mínimo)
+- Tener proceso de rotación automatizado
+- Invalidar secrets comprometidos inmediatamente
+
+---
+
+## Headers de Seguridad
+
+### FastAPI/Starlette
+
+```python
+from starlette.middleware.cors import CORSMiddleware
+from secure import Secure
+
+secure_headers = Secure()
+
+@app.middleware("http")
+async def add_security_headers(request: Request, call_next):
+    response = await call_next(request)
+    secure_headers.framework.headers(response.headers)
+    return response
+```
+
+### Headers Recomendados
+
+```http
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+X-XSS-Protection: 1; mode=block
+Strict-Transport-Security: max-age=31536000; includeSubDomains
+Content-Security-Policy: default-src 'self'
+```
+
+---
+
+## Rate Limiting
+
+```python
+from slowapi import Limiter
+from slowapi.util import get_remote_address
+
+limiter = Limiter(key_func=get_remote_address)
+
+@app.get("/api/search")
+@limiter.limit("10/minute")
+async def search(request: Request):
+    ...
+```
+
+---
+
+## Logging de Seguridad
+
+### Qué Logear
+
+```python
+# ✅ Logear
+logger.info("Login successful", extra={
+    "user_id": user.id,
+    "ip": request.client.host
+})
+
+logger.warning("Login failed", extra={
+    "email": email,  # No password
+    "ip": request.client.host,
+    "reason": "invalid_password"
+})
+
+# ❌ NUNCA logear
+logger.info(f"Login with password: {password}")  # Contraseñas
+logger.info(f"Card number: {card_number}")  # PII
+```
+
+---
+
+## Security Checklist
+
+```markdown
+## Para cada endpoint
+- [ ] Autenticación requerida
+- [ ] Autorización verificada
+- [ ] Input validado
+- [ ] Output sanitizado
+- [ ] Rate limiting
+
+## Para deployment
+- [ ] HTTPS obligatorio
+- [ ] Headers de seguridad
+- [ ] Secrets en env vars
+- [ ] Logs sin PII
+- [ ] Dependency audit
+
+## Periódico
+- [ ] Rotar secrets (90 días)
+- [ ] Actualizar dependencias
+- [ ] Revisar logs de auth
+- [ ] Penetration testing (anual)
+```
+
+---
+
+## Tools de Seguridad
+
+| Tool | Uso |
+|------|-----|
+| Bandit | Static analysis Python |
+| Safety | Dependency vulnerabilities |
+| Snyk | Multi-language security |
+| Trivy | Container scanning |
+| OWASP ZAP | Dynamic testing |
+
+---
+
+## ✅ Checklist de Validación (Security Review)
+
+### Código
+- [ ] Sin credenciales/secrets hardcodeados
+- [ ] Inputs validados con Pydantic/Zod
+- [ ] Queries SQL parametrizadas (no f-strings)
+- [ ] Outputs sanitizados (no XSS)
+
+### Auth
+- [ ] JWT con expiración corta (<= 15 min)
+- [ ] Passwords con bcrypt/argon2
+- [ ] RBAC implementado correctamente
+
+### Infra
+- [ ] HTTPS obligatorio
+- [ ] Headers de seguridad configurados
+- [ ] Rate limiting en endpoints públicos
+- [ ] Logs sin PII ni passwords

package/rules/stack.md

@@ -0,0 +1,395 @@
+# Stack Tecnológico - LMAgent
+
+> **Tipo**: `rule` | **Versión**: 2.1 | **Actualización**: 2026-01
+
+## 📌 Quick Reference
+
+| Capa | Tecnología Principal |
+|------|----------------------|
+| **Backend** | Python 3.11+ (FastAPI) o TypeScript (NestJS) |
+| **Database** | PostgreSQL 15+ (principal) + Redis 7+ (cache/colas) |
+| **ORM** | SQLModel (Python) o Prisma (TypeScript) |
+| **Validation** | Pydantic v2 |
+| **LLM** | GPT-4o (complejo) / Gemini Flash (rápido) / Claude Haiku (volumen) |
+| **AI Frameworks** | LangGraph (agentes) / LangChain (chains) |
+| **Automation** | n8n |
+| **Frontend** | React / Next.js |
+| **Mobile** | React Native / Expo |
+| **Deploy** | Docker + Dokploy |
+
+### 👥 Roles que usan esta regla
+`backend-engineer`, `frontend-engineer`, `devops-engineer`, `architect`
+
+---
+
+Este documento define el stack tecnológico base y las buenas prácticas para proyectos que usan LMAgent.
+
+## Stack Principal
+
+### Lenguajes
+| Lenguaje | Versión | Uso |
+|----------|---------|-----|
+| Python | 3.14+ | Backends, agentes IA, scripts |
+| TypeScript | 6.0+ | Backends Node, frontends |
+| JavaScript | ES2026+ | Scripts, n8n custom nodes |
+
+### Frameworks Backend
+
+#### Python (Preferido para APIs y Agentes)
+```
+FastAPI        - Framework web async
+SQLModel       - ORM + validación (combina SQLAlchemy + Pydantic)
+Pydantic       - Validación de datos
+Pydantic-Settings - Configuración via env vars
+Uvicorn        - Servidor ASGI
+```
+
+#### NodeJS/TypeScript (Cuando sea necesario)
+```
+NestJS         - Framework estructurado (preferido)
+Express        - Framework minimalista
+Prisma         - ORM para TypeScript
+```
+
+### Base de Datos
+| Componente | Tecnología | Uso |
+|------------|------------|-----|
+| Principal | PostgreSQL 18+ | Datos relacionales |
+| Cache | Redis 8+ | Cache, sesiones, colas |
+| Colas | Redis Streams | Mensajería async |
+| Búsqueda | PostgreSQL FTS | Búsqueda de texto |
+
+### Infraestructura
+| Componente | Tecnología | Uso |
+|------------|------------|-----|
+| Containers | Docker | Empaquetado |
+| Orquestación | Docker Compose | Desarrollo local |
+| Deployment | Dokploy | Deploy a producción |
+| CI/CD | GitHub Actions | Automatización |
+
+### Automatización e IA
+| Componente | Tecnología | Uso |
+|------------|------------|-----|
+| Orquestación | n8n | Workflows visuales |
+| LLM Primary | OpenAI GPT-4o | Tareas complejas |
+| LLM Fast | Gemini Flash | Tareas rápidas |
+| LLM Cost-effective | Claude Haiku | Alto volumen |
+| Agent Framework | LangGraph | Agentes stateful, grafos |
+| Chain Framework | LangChain | Chains, RAG, embeddings |
+| MCP | Model Context Protocol | Tool-use, integración de herramientas |
+
+### Frontend & Mobile
+| Componente | Tecnología | Uso |
+|------------|------------|-----|
+| Web Framework | React / Next.js | Interfaces web |
+| Mobile | React Native / Expo | Apps iOS y Android |
+| State | Zustand / Redux Toolkit | Estado global |
+| Styling | TailwindCSS / CSS Modules | Estilos |
+
+---
+
+## Estructura de Proyecto
+
+### Monorepo Multi-servicio
+```
+proyecto/
+├── .lmagent/              # Framework LMAgent
+├── backend-python/        # API principal (FastAPI)
+├── backend-node/          # Servicios Node (opcional)
+├── agents/                # Agentes de IA
+├── automations/           # Workflows n8n
+├── infra/                 # Docker, configs
+├── docs/                  # Documentación
+└── .github/               # CI/CD
+```
+
+### Estructura Backend Python
+```
+backend-python/
+├── app/
+│   ├── __init__.py
+│   ├── main.py           # Entry point FastAPI
+│   ├── config.py         # Configuración
+│   ├── routers/          # Endpoints (capa presentación)
+│   ├── services/         # Lógica de negocio
+│   ├── repositories/     # Acceso a datos
+│   ├── models/           # Modelos SQLModel
+│   ├── schemas/          # Schemas Pydantic
+│   └── core/             # Utilidades compartidas
+├── tests/
+├── Dockerfile
+└── requirements.txt
+```
+
+---
+
+## Patrones de Arquitectura
+
+### Capas de la Aplicación
+```
+┌─────────────────────────────────────┐
+│           Routers (API)             │  ← HTTP Request/Response
+├─────────────────────────────────────┤
+│           Services                  │  ← Lógica de negocio
+├─────────────────────────────────────┤
+│         Repositories                │  ← Acceso a datos
+├─────────────────────────────────────┤
+│         Models/Schemas              │  ← Estructuras de datos
+└─────────────────────────────────────┘
+```
+
+### Principios
+1. **Routers**: Solo manejan HTTP, sin lógica de negocio
+2. **Services**: Toda la lógica de negocio, sin acceso directo a DB
+3. **Repositories**: Acceso a datos, queries, transacciones
+4. **Models**: Representan entidades de la base de datos
+5. **Schemas**: Validación de input/output de API
+
+---
+
+## Configuración
+
+### Variables de Entorno (obligatorio)
+```python
+# config.py
+from pydantic_settings import BaseSettings
+
+class Settings(BaseSettings):
+    # Database
+    DATABASE_URL: str
+    
+    # Redis
+    REDIS_URL: str = "redis://localhost:6379"
+    
+    # Security
+    JWT_SECRET: str
+    JWT_ALGORITHM: str = "HS256"
+    JWT_EXPIRE_MINUTES: int = 30
+    
+    # API Keys (opcional)
+    OPENAI_API_KEY: str = ""
+    ANTHROPIC_API_KEY: str = ""
+    GOOGLE_API_KEY: str = ""
+    
+    # n8n
+    N8N_WEBHOOK_URL: str = ""
+    
+    # Environment
+    ENVIRONMENT: str = "development"
+    DEBUG: bool = False
+    
+    class Config:
+        env_file = ".env"
+        case_sensitive = True
+
+settings = Settings()
+```
+
+### .env.example
+```bash
+# Database
+DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+
+# Redis
+REDIS_URL=redis://localhost:6379
+
+# Security
+JWT_SECRET=your-super-secret-key-minimum-32-characters
+
+# LLM API Keys
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_API_KEY=...
+
+# n8n
+N8N_WEBHOOK_URL=https://n8n.yourserver.com/webhook
+
+# Environment
+ENVIRONMENT=development
+DEBUG=true
+```
+
+---
+
+## Buenas Prácticas
+
+### Obligatorias ✅
+- [ ] Configuración via variables de entorno (nunca hardcode)
+- [ ] Type hints en todas las funciones
+- [ ] Docstrings en funciones públicas
+- [ ] Tests para lógica de negocio (>80% coverage)
+- [ ] Logging estructurado (JSON en producción)
+- [ ] Manejo de errores con excepciones tipadas
+- [ ] Validación de input con Pydantic
+- [ ] Commits pequeños y descriptivos
+
+### Prohibidas ❌
+- [ ] Credenciales en código
+- [ ] `print()` en lugar de logging
+- [ ] `import *`
+- [ ] Lógica de negocio en routers
+- [ ] SQL sin parametrizar
+- [ ] Commits sin tests
+- [ ] PRs gigantes sin dividir
+
+### Recomendadas 💡
+- [ ] Usar async/await para I/O
+- [ ] Implementar health checks
+- [ ] Documentar APIs con OpenAPI
+- [ ] Usar dependency injection
+- [ ] Implementar rate limiting
+- [ ] Agregar métricas de observabilidad
+
+---
+
+## Dependencias
+
+### Python - requirements.txt base
+```
+# Framework
+fastapi>=0.109.0
+uvicorn[standard]>=0.27.0
+
+# Database
+sqlmodel>=0.0.14
+asyncpg>=0.29.0
+sqlalchemy[asyncio]>=2.0.0
+
+# Validation
+pydantic>=2.5.0
+pydantic-settings>=2.1.0
+
+# Redis
+redis>=5.0.0
+
+# HTTP Client
+httpx>=0.26.0
+
+# Security
+python-jose[cryptography]>=3.3.0
+passlib[bcrypt]>=1.7.4
+
+# Logging
+structlog>=24.1.0
+
+# Dev
+pytest>=8.0.0
+pytest-asyncio>=0.23.0
+pytest-cov>=4.1.0
+ruff>=0.2.0
+```
+
+### Node - package.json base
+```json
+{
+  "dependencies": {
+    "@nestjs/common": "^10.0.0",
+    "@nestjs/core": "^10.0.0",
+    "@nestjs/platform-express": "^10.0.0",
+    "@prisma/client": "^5.0.0",
+    "ioredis": "^5.3.0",
+    "class-validator": "^0.14.0",
+    "class-transformer": "^0.5.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "jest": "^29.0.0",
+    "eslint": "^8.0.0",
+    "prettier": "^3.0.0"
+  }
+}
+```
+
+---
+
+## Docker
+
+### Dockerfile Python (multi-stage)
+```dockerfile
+# Build stage
+FROM python:3.11-slim as builder
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir --user -r requirements.txt
+
+# Production stage
+FROM python:3.11-slim
+
+WORKDIR /app
+COPY --from=builder /root/.local /root/.local
+COPY ./app ./app
+
+ENV PATH=/root/.local/bin:$PATH
+ENV PYTHONUNBUFFERED=1
+
+EXPOSE 8000
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+```
+
+### docker-compose.yml
+```yaml
+version: "3.8"
+
+services:
+  backend:
+    build: ./backend-python
+    ports:
+      - "8000:8000"
+    environment:
+      - DATABASE_URL=postgresql://user:pass@db:5432/app
+      - REDIS_URL=redis://redis:6379
+    depends_on:
+      - db
+      - redis
+
+  db:
+    image: postgres:15-alpine
+    environment:
+      POSTGRES_USER: user
+      POSTGRES_PASSWORD: pass
+      POSTGRES_DB: app
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+  redis:
+    image: redis:7-alpine
+    volumes:
+      - redis_data:/data
+
+volumes:
+  postgres_data:
+  redis_data:
+```
+
+---
+
+## Referencias
+
+- [FastAPI Documentation](https://fastapi.tiangolo.com/)
+- [SQLModel Documentation](https://sqlmodel.tiangolo.com/)
+- [Pydantic Documentation](https://docs.pydantic.dev/)
+- [n8n Documentation](https://docs.n8n.io/)
+- [Docker Best Practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/)
+
+---
+
+## ✅ Checklist de Validación (Nuevo Proyecto)
+
+### Setup Inicial
+- [ ] Estructura de directorios según patrón definido
+- [ ] `.env.example` con todas las variables documentadas
+- [ ] `docker-compose.yml` con PostgreSQL + Redis
+- [ ] Config via pydantic-settings (no hardcode)
+
+### Código
+- [ ] Type hints en todas las funciones
+- [ ] Capas separadas: Routers → Services → Repositories
+- [ ] Sin credenciales en código
+- [ ] Logging con structlog (no print)
+
+### Calidad
+- [ ] Tests con pytest, coverage > 80%
+- [ ] Linting con ruff pasando
+- [ ] CI/CD con GitHub Actions configurado