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
Diopor servicio encore/network/, conbaseUrl= URL del entorno +/api/v1y un timeout corto. Las funciones API de los módulos usan rutas relativas. core/storage/token_storage.dartes 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: Bearersalvo en las peticiones conoptions: 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
SessionRenewerque guarda elFuturedel 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.darttraduce{"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_storagepuede 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.