351b14a78c
CRITICAL fixes: - Restrict X-View-Tenant impersonation to global admin only (was any admin) - Add authorization to subscription endpoints (was open to any user) - Make webhook signature verification mandatory (was skippable) - Remove databaseName from JWT payload (resolve server-side with cache) - Reduce body size limit from 1GB to 10MB (50MB for bulk CFDI) - Restrict .env file permissions to 600 HIGH fixes: - Add authorization to SAT cron endpoints (global admin only) - Add Content-Security-Policy and Permissions-Policy headers - Centralize isGlobalAdmin() utility with caching - Add rate limiting on auth endpoints (express-rate-limit) - Require authentication on logout endpoint MEDIUM fixes: - Replace Math.random() with crypto.randomBytes for temp passwords - Remove console.log of temporary passwords in production - Remove DB credentials from admin notification email - Add escapeHtml() to email templates (prevent HTML injection) - Add file size validation on FIEL upload (50KB max) - Require TLS for SMTP connections - Normalize email to lowercase before uniqueness check - Remove hardcoded default for FIEL_ENCRYPTION_KEY Also includes: - Complete production deployment documentation - API reference documentation - Security audit report with remediation details - Updated README with v0.5.0 changelog - New client admin email template - Utility scripts (create-carlos, test-emails) - PM2 ecosystem config updates Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
221 lines
7.4 KiB
Markdown
221 lines
7.4 KiB
Markdown
# Horux360 SaaS
|
|
|
|
Plataforma de análisis financiero y gestión fiscal para empresas mexicanas.
|
|
|
|
## Descripción
|
|
|
|
Horux360 es una aplicación SaaS multi-tenant que permite a las empresas mexicanas:
|
|
|
|
- Gestionar sus CFDI (facturas electrónicas) con carga masiva de XML
|
|
- Controlar IVA e ISR automáticamente
|
|
- Sincronizar CFDIs directamente con el SAT usando FIEL
|
|
- Visualizar dashboards financieros en tiempo real
|
|
- Realizar conciliación bancaria
|
|
- Recibir alertas fiscales proactivas
|
|
- Generar reportes y proyecciones financieras
|
|
- Calendario de obligaciones fiscales
|
|
|
|
## Stack Tecnológico
|
|
|
|
| Capa | Tecnología |
|
|
|------|-----------|
|
|
| **Frontend** | Next.js 14 + TypeScript + Tailwind CSS + shadcn/ui |
|
|
| **Backend** | Node.js + Express + TypeScript + tsx |
|
|
| **Base de datos** | PostgreSQL 16 (database-per-tenant) |
|
|
| **ORM** | Prisma (central DB) + pg (tenant DBs con raw SQL) |
|
|
| **Autenticación** | JWT (access 15min + refresh 7d) |
|
|
| **Estado** | Zustand con persistencia |
|
|
| **Proceso** | PM2 (fork mode) |
|
|
| **Proxy** | Nginx con SSL (Let's Encrypt) |
|
|
| **Email** | Nodemailer + Gmail Workspace (STARTTLS) |
|
|
| **Pagos** | MercadoPago (suscripciones) |
|
|
|
|
## Estructura del Proyecto
|
|
|
|
```
|
|
horux360/
|
|
├── apps/
|
|
│ ├── web/ # Frontend Next.js 14
|
|
│ │ ├── app/ # Pages (App Router)
|
|
│ │ ├── components/ # Componentes UI
|
|
│ │ ├── lib/api/ # Cliente API
|
|
│ │ └── stores/ # Zustand stores
|
|
│ └── api/ # Backend Express
|
|
│ ├── src/
|
|
│ │ ├── config/ # ENV, database connections
|
|
│ │ ├── controllers/ # Request handlers
|
|
│ │ ├── middlewares/ # Auth, tenant, rate-limit, plan-limits
|
|
│ │ ├── routes/ # Express routes
|
|
│ │ ├── services/ # Business logic
|
|
│ │ │ ├── email/ # Templates + Nodemailer
|
|
│ │ │ ├── payment/ # MercadoPago
|
|
│ │ │ └── sat/ # SAT sync + FIEL crypto
|
|
│ │ ├── utils/ # Helpers (token, password, global-admin)
|
|
│ │ └── jobs/ # SAT sync cron job
|
|
│ └── prisma/ # Schema + migrations
|
|
├── packages/
|
|
│ └── shared/ # Tipos y constantes compartidas
|
|
├── deploy/
|
|
│ └── nginx/ # Configuración de Nginx
|
|
├── scripts/
|
|
│ └── backup.sh # Script de backup PostgreSQL
|
|
├── docs/
|
|
│ ├── architecture/ # Docs técnicos
|
|
│ ├── security/ # Auditorías de seguridad
|
|
│ └── plans/ # Documentación de diseño
|
|
└── ecosystem.config.js # PM2 config
|
|
```
|
|
|
|
## Arquitectura Multi-Tenant
|
|
|
|
Cada cliente tiene su propia base de datos PostgreSQL, asegurando aislamiento completo de datos:
|
|
|
|
```
|
|
horux360 (central) ← Tenants, Users, Subscriptions, RefreshTokens
|
|
horux_<rfc_cliente_1> ← CFDIs, Alertas, Calendario, IVA del cliente 1
|
|
horux_<rfc_cliente_2> ← CFDIs, Alertas, Calendario, IVA del cliente 2
|
|
...
|
|
```
|
|
|
|
El middleware de tenant resuelve la base de datos del cliente desde el `tenantId` del JWT, usando un caché de 5 minutos.
|
|
|
|
## Planes
|
|
|
|
| Plan | CFDI/mes | Usuarios | Características |
|
|
|------|----------|----------|-----------------|
|
|
| Starter | 100 | 1 | Dashboard, IVA/ISR, CFDI básico |
|
|
| Business | 500 | 3 | + Reportes, Alertas, Calendario |
|
|
| Professional | 2,000 | 10 | + Conciliación, Forecasting, SAT Sync |
|
|
| Enterprise | Ilimitado | Ilimitado | + API, Multi-empresa |
|
|
|
|
## Seguridad
|
|
|
|
- JWT con access token (15min) y refresh token rotation (7d)
|
|
- bcrypt con 12 salt rounds para passwords
|
|
- Rate limiting en auth (10 login/15min, 3 register/hora)
|
|
- FIEL encriptada con AES-256-GCM
|
|
- CSP, HSTS, y security headers vía Nginx + Helmet
|
|
- Admin global verificado por RFC (no solo por rol)
|
|
- Webhooks de MercadoPago con verificación HMAC-SHA256
|
|
- Body limits diferenciados (10MB general, 50MB bulk CFDI)
|
|
- TLS obligatorio para SMTP
|
|
|
|
Ver [Auditoría de Seguridad](docs/security/2026-03-18-security-audit-remediation.md) para detalles completos.
|
|
|
|
## Documentación
|
|
|
|
| Documento | Descripción |
|
|
|-----------|-------------|
|
|
| [Diseño SaaS](docs/plans/2026-01-22-horux360-saas-design.md) | Arquitectura original y decisiones de diseño |
|
|
| [Deployment](docs/architecture/deployment.md) | Guía completa de despliegue en producción |
|
|
| [API Reference](docs/architecture/api-reference.md) | Referencia de todos los endpoints |
|
|
| [Security Audit](docs/security/2026-03-18-security-audit-remediation.md) | Auditoría de seguridad y remediaciones |
|
|
| [SAT Sync](docs/SAT-SYNC-IMPLEMENTATION.md) | Implementación de sincronización con el SAT |
|
|
|
|
## Configuración Local
|
|
|
|
### Requisitos
|
|
- Node.js 20+
|
|
- pnpm 9+
|
|
- PostgreSQL 16
|
|
|
|
### Setup
|
|
```bash
|
|
# Instalar dependencias
|
|
pnpm install
|
|
|
|
# Configurar variables de entorno
|
|
cp apps/api/.env.example apps/api/.env
|
|
cp apps/web/.env.example apps/web/.env.local
|
|
|
|
# Ejecutar migraciones
|
|
cd apps/api && pnpm prisma migrate dev
|
|
|
|
# Desarrollo
|
|
pnpm dev
|
|
```
|
|
|
|
### Variables de Entorno (API)
|
|
|
|
```env
|
|
NODE_ENV=development
|
|
PORT=4000
|
|
DATABASE_URL="postgresql://user:pass@localhost:5432/horux360"
|
|
JWT_SECRET=<min-32-chars>
|
|
JWT_EXPIRES_IN=15m
|
|
JWT_REFRESH_EXPIRES_IN=7d
|
|
CORS_ORIGIN=http://localhost:3000
|
|
FRONTEND_URL=http://localhost:3000
|
|
FIEL_ENCRYPTION_KEY=<min-32-chars>
|
|
FIEL_STORAGE_PATH=/var/horux/fiel
|
|
```
|
|
|
|
### Variables de Entorno (Web)
|
|
```env
|
|
NEXT_PUBLIC_API_URL=http://localhost:4000/api
|
|
```
|
|
|
|
## Roles
|
|
|
|
| Rol | Acceso |
|
|
|-----|--------|
|
|
| **admin** | Todo dentro de su tenant + invitar usuarios |
|
|
| **contador** | CFDI, impuestos, reportes, dashboard |
|
|
| **visor** | Solo lectura |
|
|
| **admin global** | Admin del tenant CAS2408138W2 — gestión de clientes, suscripciones, SAT cron |
|
|
|
|
## Producción
|
|
|
|
- **URL:** https://horuxfin.com
|
|
- **Hosting:** Servidor dedicado
|
|
- **SSL:** Let's Encrypt (auto-renewal)
|
|
- **Process:** PM2 con auto-restart
|
|
- **Backups:** Diarios a las 01:00 AM
|
|
|
|
Ver [Guía de Deployment](docs/architecture/deployment.md) para instrucciones completas.
|
|
|
|
## Changelog
|
|
|
|
### v0.5.0 (2026-03-18)
|
|
- Auditoría de seguridad completa y remediación de 20 vulnerabilidades
|
|
- Rate limiting en endpoints de autenticación
|
|
- Content Security Policy (CSP) y headers de seguridad mejorados
|
|
- `databaseName` removido del JWT (resolución server-side)
|
|
- Restricción de impersonación a admin global únicamente
|
|
- Autorización en endpoints de suscripción y SAT cron
|
|
- Verificación obligatoria de firma en webhooks
|
|
- Body limits reducidos (10MB default, 50MB bulk)
|
|
- Passwords temporales criptográficamente seguros
|
|
- Validación de tamaño en upload de FIEL
|
|
- SMTP con TLS obligatorio
|
|
- Documentación completa de producción
|
|
|
|
### v0.4.0 (2026-01-22)
|
|
- Carga masiva de XML CFDI (hasta 50MB)
|
|
- Selector de período mes/año en dashboards
|
|
- Fix: Persistencia de sesión en refresh de página
|
|
- Fix: Clasificación ingreso/egreso basada en RFC
|
|
- Fix: Cálculo de IVA desde XML
|
|
- Mejoras en reportes con manejo de errores
|
|
- Soporte CORS para múltiples orígenes
|
|
|
|
### v0.3.0 (2026-01-22)
|
|
- Sistema multi-tenant con gestión de clientes
|
|
- Temas visuales (4 layouts diferentes)
|
|
|
|
### v0.2.0 (2026-01-22)
|
|
- Dashboard principal con KPIs
|
|
- Módulo de CFDI
|
|
- Control de IVA/ISR
|
|
- Calendario fiscal
|
|
- Sistema de alertas
|
|
|
|
### v0.1.0 (2026-01-22)
|
|
- Autenticación JWT
|
|
- Estructura multi-tenant
|
|
- Configuración inicial del proyecto
|
|
|
|
## Licencia
|
|
|
|
Propietario - Consultoría AS
|