Core Services - Servicios Fundamentales

Los Core Services son los 4 pilares fundamentales del sistema SwapBits. Sin estos servicios, el sistema no puede funcionar.

---

🔐 Auth Service

Servicio Crítico

Puerto: 3001
Responsabilidad: Autenticación y autorización completa
Tecnología: NestJS + JWT + Passport + Redis

Propósito

El Auth Service es el guardián del sistema. Su única responsabilidad es verificar quién eres y qué puedes hacer.

¿Qué hace exactamente?

1. Registro de Usuarios

Pasos internos:

1. Valida que el email no exista
2. Valida que el username sea único
3. Hashea la contraseña con bcrypt (salt rounds: 10)
4. Crea el usuario en MongoDB con estado emailVerified: false
5. Genera un token de verificación
6. Envía email con link de verificación

2. Login (Email/Password)

Importante:

• El Access Token expira en 15 minutos (seguridad)
• El Refresh Token dura 7 días (conveniencia)
• Si falla 5 veces, bloquea cuenta por 15 minutos

3. Autenticación de Dos Factores (2FA)

Flujo de activación:

Flujo de login con 2FA:

1. Usuario envía email/password (correcto)
2. Auth Service responde: {requiresTwoFactor: true, tempToken: "xxx"}
3. Usuario envía código 2FA con tempToken
4. Auth Service verifica código y genera tokens finales

4. OAuth (Google)

Responsabilidades Detalladas

Acción	Descripción
Registro	Crear nuevos usuarios con validación
Login	Autenticar con email/password
OAuth	Login con Google, Facebook (futuro)
2FA/TOTP	Autenticación de dos factores
WebAuthn	Autenticación biométrica (huella, Face ID)
JWT Management	Generar, validar, refrescar tokens
Session Management	Crear y gestionar sesiones en Redis
Password Reset	Recuperación de contraseña
Email Verification	Verificar emails de nuevos usuarios

Endpoints Principales

POST   /auth/register          - Registrar usuario
POST   /auth/login             - Login email/password
POST   /auth/refresh           - Refrescar access token
POST   /auth/logout            - Cerrar sesión
GET    /auth/google            - Iniciar OAuth Google
POST   /auth/verify-email      - Verificar email
POST   /auth/forgot-password   - Solicitar reset password
POST   /auth/reset-password    - Resetear password
POST   /auth/2fa/enable        - Activar 2FA
POST   /auth/2fa/verify        - Verificar código 2FA
POST   /auth/webauthn/register - Registrar dispositivo WebAuthn
POST   /auth/webauthn/login    - Login con WebAuthn

Integración con Otros Servicios

Nota: Todos los servicios validan JWTs de forma independiente (no hacen request a Auth Service), pero verifican contra Redis si la sesión sigue activa.

Configuración de Seguridad

JWT_SECRET: Ultra-secreto en AWS Secrets Manager
JWT_EXPIRATION: 15m (access token)
JWT_REFRESH_EXPIRATION: 7d (refresh token)
BCRYPT_ROUNDS: 10
MAX_LOGIN_ATTEMPTS: 5
LOCKOUT_DURATION: 15m

---

👤 User Service

Gestión de Usuarios

Puerto: 3002
Responsabilidad: Gestión completa de usuarios y perfiles
Tecnología: NestJS + MongoDB + Redis

Propósito

El User Service gestiona toda la información de los usuarios después de que Auth Service los autentica.

¿Qué hace exactamente?

1. CRUD de Usuarios

Operaciones:

• Create: Normalmente lo hace Auth Service, pero User Service puede crear usuarios admin
• Read: Obtener perfil, listar usuarios con filtros, búsquedas
• Update: Actualizar nombre, teléfono, avatar, preferencias
• Delete: Desactivar cuenta (soft delete, no elimina realmente)

2. Rate Limiting (Control de Abuso)

El User Service implementa un sistema avanzado de rate limiting multicapa:

Límites por defecto:

• Por IP: 100 requests / 15 minutos
• Por Usuario: 1000 requests / hora
• Por Endpoint crítico (ej: cambiar password): 5 requests / hora
• Por Email (registro): 3 intentos / día

Implementación en Redis:

rate_limit:ip:192.168.1.1 → counter (expira en 15min)
rate_limit:user:user_123 → counter (expira en 1h)
rate_limit:endpoint:change_password:user_123 → counter

3. Gestión de Dispositivos

El User Service rastrea todos los dispositivos desde los que el usuario se conecta:

Información que guarda:

{
  deviceId: "fingerprint_hash",
  deviceName: "iPhone 12 Pro",
  deviceType: "mobile",
  os: "iOS 15.2",
  browser: "Safari",
  ip: "192.168.1.1",
  country: "US",
  trusted: true,
  lastUsed: "2025-10-20",
  createdAt: "2025-01-15"
}

4. Notificaciones de Usuario

El User Service gestiona preferencias de notificaciones:

Tipos de notificaciones:

• Transacciones (recibida, enviada, confirmada)
• Órdenes (ejecutada, cancelada)
• Seguridad (nuevo login, cambio de password)
• KYC (aprobado, rechazado)
• Marketing (opcional, desactivable)

5. Sistema de Auditoría

Cada acción importante se registra:

{
  userId: "user_123",
  action: "PASSWORD_CHANGED",
  ip: "192.168.1.1",
  device: "iPhone 12 Pro",
  timestamp: "2025-10-20T15:30:00Z",
  metadata: {
    oldPasswordHash: "...",
    method: "forgot_password_flow"
  }
}

Acciones auditadas:

• Login/Logout
• Cambio de password
• Cambio de email
• Activar/Desactivar 2FA
• Crear/Eliminar wallet
• Transacciones grandes
• Cambios de KYC

Responsabilidades Detalladas

Acción	Descripción
Profile Management	CRUD de datos de usuario
Rate Limiting	Control de abuso por IP/Usuario/Endpoint
Device Management	Registro y verificación de dispositivos
Notifications	Preferencias y envío de notificaciones
Audit Logging	Registro de acciones críticas
User Search	Búsqueda de usuarios (admin)
User Suspension	Bloquear/desbloquear usuarios
Analytics	Estadísticas de uso por usuario

Endpoints Principales

GET    /users/me                - Obtener perfil propio
PUT    /users/me                - Actualizar perfil
POST   /users/me/avatar         - Subir avatar
GET    /users/:id               - Obtener usuario (admin)
GET    /users                   - Listar usuarios (admin)
PUT    /users/:id/suspend       - Suspender usuario (admin)
GET    /users/me/devices        - Listar dispositivos
DELETE /users/me/devices/:id    - Remover dispositivo
GET    /users/me/audit-log      - Ver historial de acciones
PUT    /users/me/notifications  - Configurar notificaciones

Integración con Shared Packages

El User Service usa extensivamente los paquetes compartidos:

// Guards
@UseGuards(JwtAuthGuard, KycGuard, RateLimitGuard)

// Interceptors
@UseInterceptors(AnalyticsInterceptor, AuditInterceptor)

// Services
constructor(
  private readonly pinSecurityService: PinSecurityService,
  private readonly notificationService: NotificationService,
  private readonly analyticsService: AnalyticsService,
)

---

💰 Wallet Service

Gestión de Wallets

Puerto: 3007
Responsabilidad: Wallets multi-blockchain y transacciones
Tecnología: NestJS + MongoDB + AWS Lambda

Propósito

El Wallet Service gestiona carteras de criptomonedas en múltiples blockchains y coordina transacciones.

¿Qué hace exactamente?

1. Creación de Wallets

Blockchains soportadas:

• EVM: Ethereum, BSC, Polygon, Avalanche (misma address)
• Bitcoin: Direcciones SegWit nativas
• Solana: Ed25519 keypair
• Tron: Base58 address
• TON: Wallet V4 contract
• Ripple (XRP): Classic address
• Dogecoin: P2PKH address
• Litecoin: Bech32 address
• Polkadot: SS58 address
• Cardano: Shelley address

Nota crítica: Las private keys nunca se guardan en texto plano. Se hashean con SHA-256.

2. Consulta de Balances

Optimización:

• Los balances se cachean por 30 segundos
• Para balances en tiempo real, el frontend usa WebSocket

3. Envío de Transacciones

Validaciones antes de enviar:

1. Balance suficiente (incluyendo fees)
2. Address destino válida
3. PIN correcto (6 dígitos)
4. Rate limit no excedido (5 tx/hora)
5. Monto dentro de límites (min/max)
6. KYC aprobado para montos > $1000

4. Historial de Transacciones

Filtros disponibles:

• Por wallet
• Por coin (ETH, BTC, SOL, etc.)
• Por tipo (sent, received)
• Por estado (pending, confirmed, failed)
• Por fecha (rango)

5. Gestión Multi-Blockchain

El Wallet Service debe manejar peculiaridades de cada blockchain:

Blockchain	Tiempo confirmación	Finality	Fees
Ethereum	~15 segundos	12 bloques	Gas dinámico
BSC	~3 segundos	15 bloques	Gas bajo
Bitcoin	~10 minutos	6 bloques	UTXO fees
Solana	~0.4 segundos	32 slots	Fixed low
Tron	~3 segundos	19 bloques	Energy/Bandwidth
TON	~5 segundos	Instant	Nano fees

Estrategia:

• Cada blockchain tiene su adaptador específico
• El Wallet Service abstrae las diferencias
• El frontend no necesita saber los detalles

Responsabilidades Detalladas

Acción	Descripción
Create Wallet	Invocar Lambdas para crear wallets
Get Balance	Consultar balance en blockchain
Send Transaction	Coordinar envío vía Lambda
Transaction History	Listar transacciones del usuario
Multi-coin Support	Soportar 10+ blockchains
Fee Estimation	Calcular fees antes de enviar
Address Validation	Validar addresses destino
Rate Limiting	Limitar transacciones por tiempo

Endpoints Principales

POST   /wallets/create           - Crear nueva wallet
GET    /wallets                  - Listar wallets del usuario
GET    /wallets/:id              - Obtener wallet específica
GET    /wallets/:id/balance      - Consultar balance
POST   /wallets/:id/send         - Enviar transacción
GET    /wallets/:id/transactions - Historial de transacciones
POST   /wallets/:id/estimate-fee - Estimar fee de transacción
GET    /wallets/supported-coins  - Listar coins soportadas

Integración con Lambdas

// Invocar Lambda para crear wallet
const result = await this.lambdaClient.invoke({
  FunctionName: 'CreateWalletEVM',
  Payload: JSON.stringify({ userId: user.id })
});

// Invocar Lambda para enviar transacción
const result = await this.lambdaClient.invoke({
  FunctionName: 'SendHotWalletGlobal',
  Payload: JSON.stringify({
    from: wallet.address,
    to: dto.to,
    amount: dto.amount,
    coin: dto.coin,
    network: dto.network,
    privateKey: encryptedPrivateKey
  })
});

---

🏦 Bank Service

Servicios Bancarios

Puerto: 3005
Responsabilidad: Integración fiat ↔ crypto
Tecnología: NestJS + Manteca + Bridge

Propósito

El Bank Service es el puente entre el mundo tradicional y crypto. Permite a usuarios depositar dinero fiat y comprar crypto, o vender crypto y retirar fiat.

¿Qué hace exactamente?

1. Depósitos Fiat → Crypto

Flujo detallado:

1. Usuario solicita depositar $100 USD
2. Bank Service crea orden en Manteca
3. Manteca genera link de pago
4. Usuario paga con tarjeta o transferencia bancaria
5. Manteca envía webhook cuando pago se confirma
6. Bank Service acredita balance en la plataforma
7. Usuario puede usar ese balance para comprar crypto

2. Retiros Crypto → Fiat

Validaciones importantes:

• KYC debe estar aprobado
• Límite diario: $5,000 USD
• Límite mensual: $50,000 USD
• Balance suficiente
• Cuenta bancaria vinculada

3. Trading (Compra/Venta Directa)

Nota: El trading usa el spread de Manteca/Bridge (fee incluido en el precio).

4. Webhooks de Proveedores

El Bank Service recibe webhooks de:

Manteca:

• deposit.completed: Depósito confirmado
• deposit.failed: Depósito fallido
• withdrawal.completed: Retiro completado
• withdrawal.rejected: Retiro rechazado

Bridge:

• payment.success: Pago exitoso
• payment.failed: Pago fallido
• kyc.approved: KYC aprobado
• kyc.rejected: KYC rechazado

Verificación de webhooks:

// Cada webhook viene con firma HMAC
const signature = request.headers['x-webhook-signature'];
const payload = request.body;

const computedSignature = crypto
  .createHmac('sha256', WEBHOOK_SECRET)
  .update(JSON.stringify(payload))
  .digest('hex');

if (signature !== computedSignature) {
  throw new UnauthorizedException('Invalid signature');
}

Responsabilidades Detalladas

Acción	Descripción
Deposits	Crear órdenes de depósito fiat
Withdrawals	Procesar retiros a cuentas bancarias
Trading	Compra/venta directa de crypto
Quotes	Obtener precios en tiempo real
Order Management	Rastrear estado de órdenes
Webhook Processing	Recibir y procesar webhooks
KYC Integration	Verificar requisitos KYC
Limits Management	Aplicar límites diarios/mensuales

Endpoints Principales

POST   /bank/deposit              - Crear depósito fiat
POST   /bank/withdraw             - Solicitar retiro
POST   /bank/buy                  - Comprar crypto
POST   /bank/sell                 - Vender crypto
GET    /bank/quote                - Obtener cotización
GET    /bank/orders               - Listar órdenes
GET    /bank/orders/:id           - Obtener orden específica
POST   /bank/webhooks/manteca     - Webhook de Manteca
POST   /bank/webhooks/bridge      - Webhook de Bridge
GET    /bank/limits               - Consultar límites
GET    /bank/transactions         - Historial de transacciones

Integración con Proveedores

Manteca (Proveedor principal):

class MantecaAdapter {
  async createDeposit(amount: number, currency: string) {
    return await this.http.post('/deposits', {
      amount,
      currency,
      userId: this.userId,
      callbackUrl: 'https://api.swapbits.com/bank/webhooks/manteca'
    });
  }
  
  async createWithdrawal(amount: number, bankAccount: string) {
    return await this.http.post('/withdrawals', {
      amount,
      bankAccount,
      userId: this.userId
    });
  }
}

Bridge (Alternativo):

class BridgeAdapter {
  async buyAsset(coin: string, amount: number) {
    return await this.http.post('/orders/buy', {
      asset: coin,
      amount,
      userId: this.userId
    });
  }
}

---

Comunicación Entre Core Services

---

Resumen de Puertos

Servicio	Puerto	Función
Auth Service	3001	Autenticación
User Service	3002	Gestión de usuarios
Bank Service	3005	Servicios bancarios
Wallet Service	3007	Wallets y transacciones

---

Para Desarrolladores

Estos 4 servicios son el corazón del sistema. Si entiendes cómo funcionan, entiendes el 70% de SwapBits.

Regla de oro: Si un servicio cae, los demás siguen funcionando (tolerancia a fallos). Por eso están separados.

Debugging tip: Los logs están en MongoDB collection logs. Busca por serviceName y userId.