Saltar al contenido principal

Seguridad

Este manual describe las medidas de seguridad implementadas en la Stellar Disbursement Platform (SDP) para proteger la integridad de la plataforma y sus usuarios. Al seguir estas directrices, puedes asegurarte de que tu uso de la SDP sea lo más seguro posible.

La seguridad es un aspecto crítico de la SDP. Las medidas descritas en este documento están diseñadas para mitigar riesgos y mejorar la seguridad de la plataforma. Se recomienda encarecidamente a los usuarios seguir estas directrices para proteger sus cuentas y operaciones.

Implementación de reCAPTCHA​

Se ha integrado el reCAPTCHA de Google en la SDP para evitar ataques automatizados y asegurar que las interacciones sean realizadas por humanos y no por bots.

El reCAPTCHA está habilitado por defecto y puede desactivarse configurando la variable de entorno DISABLE_RECAPTCHA a true.

La configuración está disponible en dos niveles:

  1. Predeterminado del entorno – Configura DISABLE_RECAPTCHA=true para aplicar la configuración globalmente a todos los tenants.
  2. Anulación por tenant – Cada organización puede habilitar o deshabilitar reCAPTCHA a través de sus propias configuraciones (UI o API). Cuando existe, la elección a nivel de tenant anula el valor predeterminado del entorno.

Usa las siguientes variables de entorno para controlar el comportamiento del reCAPTCHA:

  • CAPTCHA_TYPE – GOOGLE_RECAPTCHA_V2 (predeterminado) o GOOGLE_RECAPTCHA_V3.
  • RECAPTCHA_SITE_KEY – Clave de sitio de Google emitida para el tipo de CAPTCHA elegido.
  • RECAPTCHA_SITE_SECRET_KEY – Clave secreta de Google asociada con la clave de sitio.
  • RECAPTCHA_V3_MIN_SCORE – Puntuación mínima permitida (0.0–1.0, por defecto 0.5) cuando CAPTCHA_TYPE=GOOGLE_RECAPTCHA_V3.

Nota: Desactivar reCAPTCHA en los entornos de producción (pubnet) reduce sustancialmente la protección contra abusos automatizados. Esta configuración debe usarse solo cuando se aplican controles compensatorios equivalentes.

Aplicación de la Autenticación Multi-Factor​

La Autenticación Multi-Factor (MFA) proporciona una capa adicional de seguridad a las cuentas de usuario. Se aplica por defecto en la SDP y se basa en OTPs enviados al correo electrónico de la cuenta.

La MFA está habilitada por defecto y puede desactivarse en el entorno de desarrollo configurando la variable de entorno DISABLE_MFA a true.

Nota: La MFA no puede desactivarse en entornos de producción (pubnet) por riesgos de seguridad.

Limitación de Tasa de Solicitudes y Protecciones de Red​

La SDP aplica limitación de tasa en la capa HTTP para frenar abusos automatizados. Cada par único <IP, endpoint> está limitado a 40 solicitudes dentro de 20 segundos (ventana móvil). Las solicitudes que superen este umbral recibirán respuestas limitadas hasta que la ventana se reinicie.

Modelos de Autenticación y Autorización​

Todas las rutas API autenticadas requieren que los clientes presenten una clave API emitida por la SDP o un JWT derivado de los flujos SEP10/SEP24. Estos dos mecanismos funcionan en paralelo: los JWT son para usuarios interactivos, mientras que las claves API habilitan integraciones programáticas con su propio modelo de alcance.

Roles JWT​

Los JWT representan usuarios humanos que inician sesión a través de la UI. Después de la autenticación, la plataforma los autoriza según los roles asignados a su cuenta de usuario. Los roles principales son:

  • Owner – Control total, incluyendo creación de usuarios, asignación de roles y edición de configuración de la organización. Owner es el único rol que puede otorgar o revocar acceso a otros.
  • Financial Controller – Puede realizar todas las tareas operativas (carteras, activos, desembolsos, estadísticas) excepto la gestión de usuarios. Este rol es ideal para el personal financiero que ejecuta pagos.
  • Developer – Administra configuración técnica como carteras, activos y claves API, y puede ver estadísticas; no puede modificar usuarios ni flujos financieros.
  • Business – Solo lectura sobre datos comerciales (desembolsos, receptores, estadísticas) pero no tiene acceso a detalles de gestión de usuarios.
  • Initiator – Crea y guarda desembolsos pero no puede enviarlos. Mutuamente exclusivo del rol Approver para garantizar la separación de funciones.
  • Approver – Revisa y envía desembolsos pero no puede crear nuevos; mutuamente exclusivo con Initiator.

Cada endpoint API especifica qué roles JWT pueden acceder a él—por ejemplo, las rutas de gestión de claves API (/api-keys) requieren Owner o Developer, mientras que la creación de desembolsos requiere Initiator o Financial Controller y el envío requiere Approver o Financial Controller.

Permisos de la clave API​

Las claves API omiten los roles JWT e incluyen sus propios ámbitos de permisos. Cuando una solicitud incluye una clave API, el middleware valida la clave, confirma que la dirección IP del llamante esté permitida (si está restringida), verifica la expiración y finalmente asegura que la clave contenga los ámbitos requeridos por el endpoint. Las claves API se usan típicamente para automatización e integraciones entre servicios donde se necesita acceso preciso de lectura/escritura; crearlas o rotarlas sigue requiriendo un usuario con el rol JWT apropiado (Owner o Developer) para acceder a los endpoints /api-keys.

Los ámbitos disponibles mapean directamente a los principales recursos de la SDP:

  • read:all, write:all
  • read:disbursements, write:disbursements
  • read:receivers, write:receivers
  • read:payments, write:payments
  • read:organization, write:organization
  • read:users, write:users
  • read:wallets, write:wallets
  • read:statistics
  • read:exports

Configuración recomendada​

Para mejorar la seguridad, las responsabilidades de desembolso deberían distribuirse entre varios usuarios con el rol Financial Controller.

  1. Flujo de aprobación: Activa el flujo de aprobación en la página de la organización para requerir dos usuarios en el proceso de desembolso. El propietario puede hacerlo en Perfil > Organización > ... > Editar detalles > Flujo de aprobación > Confirmar.
  2. Rol Financial Controller: Crea dos usuarios con el rol Financial Controller en la página de la organización para aplicar la separación de funciones. El propietario puede hacerlo en Configuración > Miembros del equipo.
  3. Gestión de la cuenta Owner: Utiliza la cuenta Owner únicamente para la gestión de usuarios y la configuración de la organización. Evita usar la cuenta Owner para tareas de financial controller para minimizar la exposición de esa cuenta.

Buenas prácticas para la gestión de carteras​

La cartera de SDP debería usarse principalmente como una hot wallet con una cantidad limitada de fondos para minimizar posibles pérdidas.

Hot y Cold Wallets​

  • Una hot wallet está conectada a internet y permite transacciones rápidas.
  • Una cold wallet está desconectada y se usa para almacenar fondos de manera segura.
  • Aprende más sobre estos conceptos en Investopedia.