Arquitectura

Arquitectura de despliegue

MedSync se despliega como una aplicacion web: el usuario entra al frontend, el frontend llama a la API, la API consulta MySQL y se apoya en SMTP/storage cuando un flujo lo necesita.

Para autenticacion basada en cookies, la parte mas importante es esta: el browser no guarda tokens legibles. Las credenciales de sesion viajan en cookies HttpOnly; el frontend solo guarda estado de UI/runtime; y el backend decide si la sesion sigue viva.

Componentes

Componente	Tecnologia observada	Responsabilidad
Browser	Navegador moderno	Renderiza frontend, conserva cookies y ejecuta flujos clinicos.
Frontend	Vue 2 + Vue CLI, Vuetify, axios	UI de login, Super Admin, dashboard, pacientes, documentos y flujos clinicos.
Backend API	Node.js + Express + Sequelize + MySQL	Auth, sesiones, tenants, usuarios, pacientes, documentos, tratamientos, prescripciones y Super Admin.
Base de datos	MySQL via `mysql2` y `sequelize`	Persistencia de tenants, usuarios, sesiones, refresh tokens, permisos y datos de negocio/clinicos.
SMTP	Nodemailer SMTP	Recuperacion de password y correos transaccionales de firma/documentos si aplica.
Storage	AWS S3/Cloudinary segun variables configuradas	Archivos, imagenes, firmas, fotos, rayos X y perfiles cuando esos flujos esten activos.
Reverse proxy / LB	No hay config real en repo	Termina TLS, enruta dominios, aplica limites/timeouts y protege headers.
Observabilidad	No hay stack real definido	Debe recolectar logs backend, proxy, auth, CSRF, CORS, DB y alertas.
Backups	No hay sistema real definido	Requisito infra antes de produccion.

Diagrama logico

flowchart LR
  U[Browser] --> F[Frontend Vue app]
  F --> RP[Reverse proxy / Load balancer]
  RP --> API[Backend API Express]
  API --> DB[(MySQL DB)]
  API --> SMTP[SMTP provider]
  API --> STORAGE[Object storage]
  API --> LOGS[Logs / Monitoring]
DB --> BACKUP[(Encrypted backups)]

Flujo de una request normal

1. Browser carga https://app.<dominio>.
2. Frontend Vue pide CSRF y luego llama a https://api.<dominio>.
3. Browser adjunta cookies de autenticacion en requests a la API.
4. Backend valida cookie access, sesion activa, CSRF, CORS, rol, permisos y tenant.
5. Backend consulta MySQL y responde sin exponer tokens.
6. Logs y metricas registran status/ruta/latencia sin secretos.
7. Backups protegen DB/storage para restore.

Browser -> GET /api/auth/csrf
Browser -> POST /api/auth/login con X-CSRF-Token
API -> valida usuario/password/tenant
API -> crea session + refresh token v2
API -> Set-Cookie access/refresh HttpOnly
Frontend -> GET /api/auth/session
Frontend -> guarda usuario/rol/permisos en runtime

Fronteras de confianza

Frontera	Riesgo	Control minimo
Browser a frontend	XSS, storage persistente, recursos inseguros	CSP futuro, build con cookies, no tokens en storage, assets servidos por HTTPS.
Frontend a API	CSRF, CORS, cookies enviadas a origen incorrecto	`withCredentials`, CORS allowlist exacta, `X-CSRF-Token`, TLS.
API a DB	Credenciales DB filtradas, privilegios excesivos	Usuario DB minimo, secreto en secret manager, red privada, backups cifrados.
API a SMTP	Credenciales SMTP filtradas, abuso de correo	Secretos rotables, sandbox QA, rate limit, monitoreo de envio.
API a storage	Exposicion de archivos clinicos	Buckets privados, credenciales separadas, URLs temporales si aplica.
Proxy a API	Spoofing de host/proto/IP	`EXPRESS_TRUST_PROXY` controlado, headers forward correctos, allowlist de red.

Topologia de dominios recomendada

Frontend: https://app.<dominio>
API:      https://api.<dominio>
Docs:     https://docs.<dominio> opcional

Con app.<dominio> y api.<dominio> bajo el mismo dominio raiz, el navegador los trata como same-site. En esa topologia, SameSite=Lax es el default recomendado para cookies de autenticacion porque reduce exposicion cross-site y conserva UX razonable.

SameSite=None; Secure solo debe usarse si frontend y API son cross-site reales, por ejemplo dominios raiz distintos. Si se usa None, CSRF y Origin/Referer son aun mas criticos.

Decision sobre `__Host-`

Las cookies __Host-medsync_at, __Host-medsync_rt y __Host-medsync_csrf son recomendadas para production-like cuando se puede operar con cookies host-only:

Deben usar Secure.
Deben usar Path=/.
No pueden definir Domain.

No uses AUTH_COOKIE_DOMAIN con cookies __Host-. Si infraestructura exige compartir cookies entre hosts mediante Domain, se pierde la propiedad __Host-; esa decision debe quedar aprobada por seguridad y documentada.

Local vs production

Local HTTP puede usar cookies sin __Host- y AUTH_COOKIE_SECURE=false solo para desarrollo. Esa configuracion no prueba seguridad final.

Production-like debe usar HTTPS, cookies Secure, CORS exacto, CSRF activo, secretos fuertes y REQUIRE_ACTIVE_SESSION=true.

Decision practica

Para la validacion production-like previa a produccion, la arquitectura minima aceptable es:

https://app.<dominio> sirve el frontend.
https://api.<dominio> sirve la API.
API y frontend comparten raiz de dominio para usar SameSite=Lax.
Cookies auth usan Secure, HttpOnly, Path=/ y preferiblemente __Host-*.
CORS solo permite https://app.<dominio>.
CSRF solo permite https://app.<dominio>.
Logs, backups y rollback estan listos antes de exponer usuarios reales.