Módulo de sesión (frontend)

Se encarga del inicio y cierre de sesión en la SPA, de la verificación en dos pasos (MFA) y de Mi cuenta. La seguridad real está en la API: el front solo decide qué mostrar y a dónde llevar a la persona. Las reglas del backend están en Módulo Auth.

Flujo

flowchart TD
  N[Navegar a una ruta] --> G{¿Ruta pública?}
  G -- Sí --> P{¿Ya tiene sesión y es el login?}
  P -- Sí --> H[Inicio]
  P -- No --> V[Mostrar la página]
  G -- No --> R{¿Hay usuario o un token<br>que la API reconoce?}
  R -- Sí --> V
  R -- No --> L["Login con ?volver=ruta"]
  L --> I[Ingresa] --> S{¿volver es interno?}
  S -- Sí --> D[Vuelve a esa ruta]
  S -- No --> H

• Al recargar la página queda el token en sessionStorage, pero no el usuario: la guarda lo pide a GET /auth/me antes de mostrar la ruta.
• Si esa consulta falla por otra razón (sin conexión, mantenimiento o el servidor tardó demasiado), la sesión no se borra: solo la API puede decir que ya no vale. La guarda lleva a /sin-conexion, que dice qué pasó con el mensaje del catálogo y ofrece “Reintentar”, volviendo a la página que se pedía.
• Si la API responde UNAUTHENTICATED en cualquier momento (sesión vencida, inactiva o revocada), el cliente HTTP borra el token. La guarda lleva al login con un aviso visible y recuerda la página para volver.
• Cerrar sesión revoca el token en la API. Si la API no responde, igual se borra en el navegador, y el token vence solo.

Pantalla de login

• Contenido:
  • Logo, título “Inicia sesión”, correo, contraseña (con botón para mostrarla u ocultarla) y el botón “Ingresar”.
  • Los errores van en un aviso siempre visible encima de los campos. Los de cada campo, debajo del campo.
• Validación visual: campos vacíos y forma del correo. No reemplaza a la API, solo evita un viaje innecesario.
• Mientras espera la respuesta, el botón queda bloqueado y un segundo envío se ignora, para no contar un intento de más.
• Si el ingreso falla, la contraseña se borra del campo.
• Autocompletado: username y current-password, para que funcionen los gestores de contraseñas.

Mensajes

Debajo de la contraseña está el enlace “¿Olvidaste tu contraseña?”, que lleva a la recuperación.

Verificación en dos pasos

Después de la contraseña, la API dice qué sigue (status):

• El token de un ingreso a medias vive solo en memoria (pending en el store), nunca en sessionStorage, y viaja solo en los pedidos del segundo paso. Si se recarga la página, se vuelve a ingresar.
• /ingresar/verificar: un campo para el código (AppCodeField: teclado numérico, autocompletado del teléfono y pegar “123 456” funciona). “¿No tienes tu teléfono? Usa un código de recuperación” cambia a un campo de texto. Un código incorrecto dice cuántos intentos quedan; al quinto, o si pasaron los 5 minutos, solo queda “Volver a ingresar”.
• /configurar-mfa: dentro del mismo marco del login. 1) QR (AppQrCode) y la clave en grupos de 4 con “Copiar” (AppCopyBlock); qué aplicaciones sirven va en el ícono de información. 2) El primer código y “Activar”. 3) Los 8 códigos de recuperación (RecoveryCodesPanel) con “Copiar todos” y “Descargar .txt” (se arma en el navegador), y “Continuar” solo después de marcar “Ya guardé mis códigos”. Llega de tres formas: obligatoria (con “Volver a ingresar”), sugerida (con “Configurar más tarde”) o desde Mi cuenta (con “Cancelar”).

Recuperar la contraseña

Tres pantallas dentro del mismo marco del login (AuthPanel):

• Nada queda guardado en el navegador: el correo, el pase y si hace falta el segundo factor viven solo en memoria (useRecoveryStore). Si se recarga a mitad de camino, las pantallas vuelven a /recuperar.
• Si el pase venció (PASSWORD_RESET_EXPIRED), el aviso ofrece pedir un código nuevo.
• Requisitos a la vista: NewPasswordFields muestra una lista que se marca mientras se escribe: el largo (12 a 128) y que las dos coincidan. Que no sea predecible (repeticiones, secuencias o datos personales) y que no esté filtrada solo lo puede decir la API: esos requisitos se muestran sin marca y, si fallan, el error con su motivo aparece debajo del campo. Sus reglas no se copian en el front.

Mi cuenta

/mi-cuenta, desde el menú de la persona. Una columna en celular y tablet; dos en portátil y monitor, donde “Tus datos” se estira hasta el alto de “Verificación en dos pasos” para que queden alineadas, y “Contraseña” va debajo de “Tus datos”.

• Tus datos: nombre, correo y rol.
• Contraseña: “Cambiar contraseña” abre un diálogo (ChangePasswordDialog) con la actual, la nueva y su confirmación. Una contraseña actual equivocada o una nueva igual a la actual se marcan en su campo, sin cerrar el diálogo. Al cambiarla, avisa que se cerraron las demás sesiones; la actual sigue abierta.
• Verificación en dos pasos: si está activa, cuántos códigos de recuperación quedan (con un aviso cuando quedan 2 o menos), “Generar códigos nuevos” y, si el rol no la exige, “Desactivar”. Las dos acciones piden el código actual en un diálogo (AppCodeDialog, compartido) que muestra el error sin cerrarse. Si no está activa, “Configurar”.

Redirección segura

Después del login se vuelve a la página indicada en ?volver=, solo si es una ruta interna (/algo). Las direcciones externas (https://…) y las que el navegador trata como otro dominio (//… o /\…) se ignoran y llevan al inicio. Así, un enlace manipulado no puede sacar a nadie de Trazo después de ingresar.

Menú según permisos

GET /auth/me y el login devuelven la lista de permisos. Cada entrada del menú puede declarar el permiso que necesita (permission en navigation.ts), y el menú muestra solo las permitidas. Ocultar una opción es comodidad, no protección: la API rechaza igual lo que no corresponde.

Capas

Los diálogos envuelven su formulario en un div: Quasar solo deja pasar los clics al primer div dentro de QDialog, y con un form en la raíz los clics caían al fondo y cerraban el diálogo.

Dónde está en el código

• frontend/src/modules/auth/
• frontend/src/app/layout/AppUserMenu.vue: menú de la persona conectada.
• frontend/src/app/navigation.ts: filtrado del menú por permisos.
• frontend/src/app/router/index.ts y frontend/src/app/bootstrap.ts: guarda de rutas y registro de mensajes.
• Pruebas: archivos *.spec.ts dentro del módulo.
• Decisiones: ADR-0015, ADR-0042, ADR-0049, ADR-0051 y ADR-0052