Resumen
Sistema de autenticación y gestión de cuentas de usuario diseñado para entornos modernos y escalables. Implementa múltiples estrategias de autenticación, credenciales tradicionales, OAuth 2.0 con Google y JWT junto a un modelo de control de acceso basado en roles (RBAC).
La solución adopta una arquitectura modular orientada a microservicios, con una separación clara de responsabilidades mediante un patrón MVC extendido, favoreciendo mantenibilidad, seguridad y evolución del sistema.
Link del repositorio: https://github.com/jotacalderon90/cf.account
Stack Tecnológico
Framework Principal
-
Framework Custom:
cl.jotacalderon.cf.framework- Framework propietario que provee módulos core (logging, MongoDB, Redis, control de acceso).
- Sistema de ruteo basado en decoradores/comentarios:
@route,@method,@roles.
Librerías Externas (NPM)
- zod – Validación y parsing de esquemas con enfoque TypeScript-first.
- jsonwebtoken – Generación y validación de tokens JWT.
- argon2 – Hashing de contraseñas (algoritmo moderno y seguro).
- express-recaptcha – Integración con Google reCAPTCHA.
- googleapis – OAuth 2.0 y acceso a APIs de Google (Gmail, perfil).
Arquitectura del Sistema
Patrón Arquitectónico
El sistema sigue una arquitectura MVC + Service + Repository, asegurando desacoplamiento y reutilización de componentes.
- Router – Definición de rutas y políticas de acceso.
- Controller – Manejo de requests y responses HTTP.
- Service – Lógica de negocio.
- Repository – Acceso a datos (MongoDB).
- Validator – Validación de datos mediante Zod.
- Constants – Mensajes de error y constantes del dominio.
Módulos Principales
1. Vistas (SSR)
- Renderizado del lado del servidor (Server-Side Rendering).
- Gestión de flujos de autenticación y administración.
Rutas principales:
/– Página principal del usuario./login– Inicio de sesión./form– Registro de usuarios./forget//recovery– Recuperación de contraseña./admin/admin– Panel de administración (protegido por roles).
2. Usuario
| Método | Ruta | Descripción |
|---|---|---|
| POST | /api/account |
Creación y mantenimiento de cuentas. |
| GET | /api/account |
Obtención del usuario autenticado. |
| GET | /api/account/activate/:hash |
Activación de cuenta. |
| POST | /api/account/login |
Inicio de sesión. |
| GET | /api/account/logout |
Cierre de sesión. |
3. Administración
- Gestión completa de usuarios (CRUD).
- Paginación, búsqueda y filtros.
- Asignación de roles.
- Acceso restringido:
root,admin.
4. OAuth 2.0 – Google
| Método | Ruta | Descripción |
|---|---|---|
| GET | /api/google/oauth |
Obtención de URL de autorización. |
| GET | /api/google/oauth/callback |
Callback OAuth. |
| POST | /api/google/send |
Envío de correos vía Gmail API. |
Sistema de Sesiones y JWT
El sistema implementa un modelo híbrido de autenticación:
- Session-Based: JWT almacenado en cookies con tracking de sesión.
- Stateless JWT: Tokens sin estado, orientados a consumo API.
Sesiones Compartidas entre Subdominios
# .env
COOKIE_DOMAIN=.ejemplo.com
COOKIE_SAMESITE=Lax
Esta configuración permite autenticación compartida entre subdominios, funcionando como un SSO interno limitado al dominio raíz.
Seguridad
- Protección CSRF y XSS mediante cookies seguras.
- reCAPTCHA y rate limiting contra ataques de fuerza bruta.
- Contraseñas protegidas con Argon2id.
- JWT con expiración controlada y validación estricta.
- Control de acceso basado en roles (RBAC).
Conclusión
El sistema representa una solución moderna y robusta para la gestión de identidad, adecuada para plataformas SaaS, sistemas multi-tenant y arquitecturas distribuidas.
- Arquitectura modular y escalable.
- Seguridad alineada con estándares actuales.
- Soporte para autenticación social y tradicional.
- Preparado para integración con microservicios.
Documento generado a partir del análisis de código fuente – Febrero 2026