Saltar a contenido

0008. Un Dio por servicio, tokens en almacenamiento seguro y una sola renovación de sesión

Estado: Propuesto Fecha: 2026-11-02 Autor: David Garcia Módulo(s) afectado(s): core/network/, core/storage/ Complementa a: ADR 0007

Contexto

El access token dura 15 minutos y el refresh 30 días. Cada POST /auth/refresh revoca el refresh usado y emite otro; si uno ya revocado vuelve a usarse, identidad revoca todas las sesiones del usuario (ADR 0030 de identidad). Si dos peticiones reciben 401 a la vez y cada una renueva, la segunda dispara ese replay y saca al promotor. La web resolvió lo mismo con una renovación compartida (ADR 0004 del frontend); en el teléfono no hay pestañas, pero sí peticiones simultáneas y una app que el sistema puede cerrar en cualquier momento.

Decisión

  • Un Dio por servicio en core/network/, con baseUrl = URL del entorno + /api/v1 y un timeout corto. Las funciones API de los módulos usan rutas relativas.
  • core/storage/token_storage.dart es el único que sabe dónde están los tokens: flutter_secure_storage (Keychain en iOS, Keystore en Android). Guarda primero y avisa después: la sesión se publica como un stream.
  • Interceptor común: adjunta Authorization: Bearer salvo en las peticiones con options: sinSesion (login, refresh, cambio de contraseña). Ante un 401 renueva y reintenta una sola vez.
  • Una renovación en curso para toda la app: todos los Dio comparten un SessionRenewer que guarda el Future del refresh en curso; los 401 simultáneos esperan ese mismo resultado.
  • Los tokens nuevos se guardan antes de usarse, para que un cierre de la app no deje en el teléfono un refresh ya revocado.
  • Rechazo del refresh (respuesta < 500) → se borran los tokens y el router lleva al login. Red caída o 5xx → se conserva la sesión y se propaga el error real.
  • Errores: core/network/errores.dart traduce {"detail": "..."} y los 422 de FastAPI a mensajes propios en español, y expone el status para decidir en código (409, 403).

Alternativas descartadas

  • Un solo Dio con URLs absolutas — mezcla servicios y su configuración.
  • Renovar por adelantado con un temporizador — en segundo plano el sistema lo suspende, y el 401 hay que manejarlo igual.
  • shared_preferences — guarda los tokens en texto plano.

Consecuencias

  • Todos los clientes dependen de la renovación de identidad; si otro servicio emitiera tokens propios, habría que separarla.
  • Si el sistema mata la app entre la respuesta del refresh y el guardado, el token viejo queda revocado y el promotor tiene que volver a entrar. Se acepta: la ventana es de milisegundos.
  • En Android, flutter_secure_storage puede perder los datos al restaurar un respaldo en otro equipo: el promotor vuelve a entrar.

Media página como máximo. Si el ADR crece más que eso, probablemente estás documentando el diseño completo del módulo, no una decisión puntual — separa.