Saltar al contenido principal

SwapBits Packages

Este repositorio contiene los paquetes compartidos utilizados por los microservicios de la plataforma Swapbits. Centraliza modelos, DTOs, servicios, guards, middlewares y herramientas de seguridad para mantener el código desacoplado, reutilizable y escalable.

Versión: 3.0.0 – Última actualización: 24 de julio de 2025

� Estructura del repositorio​

packages/
├── controllers/          # Controladores compartidos (admin rate-limit, PIN)
├── dtos/                # Data Transfer Objects con validaciones
├── email/               # Servicio de email con templates
├── examples/            # Ejemplos de uso e implementación
├── guards/              # Guards de autenticación y autorización
├── interceptors/        # Interceptores para rate limiting y auditoría
├── jwt/                 # Módulo JWT compartido
├── logs/                # Sistema completo de auditoría
├── middleware/          # Middlewares de rate limiting
├── rate-limiting/       # Sistema de rate limiting avanzado
├── redis/               # Servicio centralizado de Redis
├── schemas/             # Mongoose Schemas para MongoDB
├── services/            # Servicios compartidos (notifications, IP blocking, PIN security)
├── tasks/               # Tareas programadas (cleanup, mantenimiento)
└── utils/               # Utilidades (códigos de error, HTTP helpers)

� Características Principales​

🛡️ Sistema de Seguridad Integrado​

  • ✅ Rate Limiting Inteligente - Por IP, usuario, email y API key
  • ✅ Sistema PIN Avanzado - Autenticación de segundo factor con sesiones
  • ✅ Guards Múltiples - JWT, KYC, PIN, Rate Limit, Roles
  • ✅ Protección Anti-Brute-Force - Bloqueos automáticos y escalables

📊 Auditoría y Monitoreo​

  • ✅ Auditoría Completa - Logging de todas las acciones críticas
  • ✅ Alertas Automáticas - Notificaciones a Discord/Slack
  • ✅ Baneos Automáticos - Escalación progresiva por comportamiento
  • ✅ Estadísticas en Tiempo Real - Dashboards y métricas

�️ Gestión de Datos​

  • ✅ Schemas Unificados - 22+ schemas para todos los microservicios
  • ✅ DTOs Validados - 15+ DTOs con class-validator
  • ✅ Cache Redis - Servicio optimizado para sesiones y rate limiting

⚡ Alto Rendimiento​

  • ✅ Docker Ready - Configuraciones optimizadas para producción
  • ✅ Escalabilidad - Redis clustering y MongoDB sharding ready
  • ✅ Async Processing - Tareas programadas y procesamiento en background

Componentes Principales​

🔐 Sistema de Autenticación​

JWT Auth Guard (guards/jwt-auth.guard.ts)​

  • Verificación JWT con Redis sessions
  • Integración automática de KYC
  • Sistema PIN incorporado
  • Auto-migración de usuarios

PIN Security System (services/pin-security.service.ts)​

  • PINs de 6 dígitos con hash bcrypt
  • Sesiones aprobadas con timeouts
  • Protección anti-brute-force (5 intentos/15min)
  • Tracking de sesiones por usuario
// Uso automático en todos los endpoints protegidos
@UseGuards(JwtAuthGuard) // Incluye JWT + KYC + PIN automáticamente

🛡️ Rate Limiting System​

Enhanced Rate Limit (middleware/enhanced-rate-limit.middleware.ts)​

  • Rate limiting por IP, usuario, endpoint
  • Escalación automática de baneos
  • Whitelist/Blacklist dinámicas
  • Headers estándar HTTP

Rate Limit Guard (guards/rate-limit.guard.ts)​

  • Decoradores para configuración granular
  • Bypass configurables
  • Integración con auditoría
@RateLimit(5, 15 * 60 * 1000, 'email') // 5 intentos por 15min por email
@SkipRateLimit() // Omitir rate limiting

📊 Sistema de Auditoría​

Audit Interceptor (logs/audit.interceptor.ts)​

  • Logging automático de requests/responses
  • Detección de eventos de seguridad
  • Integración con Discord/Slack

Audit Log Service (logs/audit-log-dc.service.ts)​

  • Almacenamiento en MongoDB
  • Queries optimizadas
  • Retención automática
@Audit('login_attempt', { sensitive: true })

🎯 Instalación y Uso​

1. Instalación en tu proyecto​

# Copiar packages necesarios
cp -r ./packages/* ./src/packages/

# Instalar dependencias
npm install @nestjs/mongoose @nestjs/schedule @nestjs/cache-manager
npm install mongoose redis cache-manager uuid axios bcrypt class-validator

2. Configuración del módulo principal​

import { Module } from '@nestjs/common';
import { RateLimitingModule } from './packages/rate-limiting';
import { LogsModule } from './packages/logs';
import { ServicesExtraModule } from './packages/services';
import { RedisModule } from './packages/redis';

@Module({
  imports: [
    MongooseModule.forRoot(process.env.MONGODB_URI),
    RedisModule,
    RateLimitingModule,
    LogsModule,
    ServicesExtraModule,
  ],
})
export class AppModule {}

3. Variables de entorno​

# Base de datos
MONGODB_URI=mongodb://localhost:27017/swapbits
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# Notificaciones
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR_WEBHOOK
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR_WEBHOOK

# JWT
JWT_SECRET=your-secret-key
JWT_EXPIRATION=24h

# Rate Limiting
RATE_LIMIT_GLOBAL=500
RATE_LIMIT_WINDOW=600000

📊 Schemas Disponibles​

Usuarios y Autenticación​

  • User - Schema principal de usuario con PIN security
  • OAuth2 - Configuración OAuth2 y KYC
  • UserActivity - Actividad y comportamiento del usuario
  • SessionAccess - Control de sesiones activas
  • LogoutRecord - Registro de logout y revocación

Seguridad y Control​

  • BlockedAccess - IPs y usuarios bloqueados
  • SecurityEvent - Eventos de seguridad detectados
  • FraudAlert / FraudRule - Sistema anti-fraude
  • RateLimit / RateLimitBan - Rate limiting y baneos
  • AuditLog - Auditoría completa de acciones

Transacciones y Wallets​

  • Transaction - Transacciones de la plataforma
  • Wallet / WalletContract - Wallets y contratos
  • OrderHistory - Historial de órdenes
  • PendingTransfer - Transferencias pendientes

Dispositivos y Acceso​

  • LinkedDevice - Dispositivos vinculados
  • History - Historial de login y accesos

📝 DTOs Principales​

Autenticación​

  • LoginUserDto - Login con validaciones
  • CreateUserDto - Registro de usuarios
  • UpdateUserDto - Actualización de perfil

PIN Security​

  • ConfigurePinDto - Configuración inicial PIN (6 dígitos)
  • VerifyPinDto - Verificación de PIN
  • CreatePinSessionDto - Crear sesión aprobada
  • UpdatePinDto - Cambio de PIN

Transacciones​

  • CreateOrderDto - Creación de órdenes
  • WithdrawDto - Retiros
  • ConvertDto - Conversiones
  • OrderHistoryQueryDto - Consultas de historial

Sistema​

  • CreateBridgeDto - Bridges de blockchain
  • CreateWalletDto - Creación de wallets
  • CryptoCurrencyDto - Información de cryptos

🔧 Servicios Globales​

Core Services​

  • PinSecurityService - Gestión completa de PIN security
  • NotificationService - Notificaciones multi-canal
  • IpBlockService - Bloqueo y gestión de IPs
  • LambdaService - Integración con AWS Lambda

Audit & Logging​

  • AuditLogService - Logging y consultas de auditoría
  • LogoutRecordService - Gestión de logout y sesiones

Rate Limiting​

  • RateLimitService - Rate limiting avanzado
  • RateLimitBanService - Gestión de baneos

🐳 Docker Support​

Configuración incluida:​

  • Dockerfile optimizado para producción
  • docker-compose.yml con MongoDB + Redis
  • Variables de entorno documentadas
  • Health checks configurados
# Quick start
version: '3.8'
services:
  app:
    build: .
    environment:
      - MONGODB_URI=mongodb://mongo:27017/swapbits
      - REDIS_HOST=redis
    depends_on:
      - mongo
      - redis

� Ejemplos de Uso​

Endpoint con protección completa:​

@Controller('auth')
export class AuthController {
  
  @Post('login')
  @RateLimit(5, 15 * 60 * 1000, 'email') // 5 intentos por 15min
  @Audit('login_attempt')
  @UseGuards(JwtAuthGuard) // JWT + KYC + PIN automático
  async login(@Body() loginDto: LoginDto) {
    return this.authService.login(loginDto);
  }

  @Post('pin/verify')
  @SkipRateLimit() // Configuración inicial
  async verifyPin(@Request() req, @Body() dto: VerifyPinDto) {
    const jti = req.user.jti;
    await this.pinSecurityService.verifyPin(req.user.id, dto.pin);
    return this.pinSecurityService.createApprovedSession(jti, req.user.id);
  }
}

Admin endpoint con estadísticas:​

@Get('admin/stats')
@SkipRateLimit()
@UseGuards(AdminGuard)
async getStats() {
  return this.rateLimitService.getGlobalStats();
}

🔄 Versionado y Migración​

Auto-migración incluida:​

  • Usuarios sin pinSecurity se migran automáticamente
  • Backwards compatibility con schemas antiguos
  • Migración incremental sin downtime

Versioning Strategy:​

  • Semantic Versioning (Major.Minor.Patch)
  • Backwards compatibility mantenida
  • Breaking changes solo en major versions

🤝 Contribuciones​

Guidelines:​

  1. Mantén cada paquete aislado y autocontenible
  2. Solo código reutilizable - no lógica de negocio específica
  3. PRs pequeños con documentación clara
  4. Tests incluidos para nuevas funcionalidades
  5. Tipos TypeScript completos y exportados

Estructura de commits:​

feat(guards): add device authentication guard
fix(pin): resolve session timeout issue
docs(readme): update installation guide
refactor(schemas): optimize user schema indexes

📈 Estadísticas del Proyecto​

  • 📁 22+ Schemas MongoDB optimizados
  • 📝 15+ DTOs con validaciones completas
  • 🛡️ 10+ Guards para autenticación y autorización
  • ⚙️ 8+ Services globales reutilizables
  • 📋 5+ Controllers de administración
  • 🔧 3+ Middlewares de seguridad avanzada

🛡️ Licencia​

MIT © Swapbits

Desarrollado con ❤️ por el equipo Swapbits
Para consultas técnicas: devops@swapbits.io

📌 Este documento se actualizará a medida que se añadan más detalles sobre los componentes internos de cada módulo.