La máquina de autenticación: el mapa completo

La autenticación es el dominio donde el estado disperso hace más daño y donde más veces se escribe igualmente disperso. Casi toda aplicación empieza con un usuario que puede ser nulo, un cargando que empieza en falso y un error que nadie limpia, y termina descubriendo que esas tres variables admiten ocho combinaciones de las cuales seis no significan nada. La máquina de autenticación no es un ejercicio de elegancia: es el reconocimiento de que una sesión atraviesa fases con reglas estrictas sobre qué puede ocurrir después de qué, y de que esas reglas son exactamente lo que un grafo expresa y una constelación de banderas jamás pudo. Este nivel entero se construye sobre el mapa que dibujamos aquí, así que conviene levantarlo completo antes de discutir ninguna de sus partes.

Seis estados, ni uno más

El primer instinto al modelar la autenticación es reducirla a dos situaciones, dentro o fuera, y tratar todo lo demás como ruido temporal. Ese instinto es el origen de casi todos los defectos del área, porque lo que llamamos ruido temporal es precisamente donde el usuario pasa los momentos críticos: el arranque, el envío de credenciales, la renovación silenciosa y la caducidad. Cada uno de esos momentos admite eventos distintos y exige una interfaz distinta, y eso es la definición operativa de un estado.

comprobando es el estado en el que la aplicación aún no sabe si hay sesión. No es anónimo con un indicador de carga encima: es una tercera situación epistémica que no debe confundirse con ninguna de las otras dos, y toda la lección siguiente gira alrededor de ella. anonimo es la ausencia confirmada de sesión, un estado estable donde el único evento significativo es el intento de entrar. autenticando es la ventana durante la cual las credenciales están en vuelo; su valor no es informativo sino normativo, porque es el estado donde el envío duplicado debe ser imposible. autenticado es el régimen normal de operación. refrescando es la renovación en curso, con la sesión aún válida pero la credencial en tránsito. Y expirado es la pérdida involuntaria de la sesión, que no es lo mismo que la salida deliberada por más que ambas terminen sin usuario.

import { setup, assign, fromPromise } from 'xstate'

type Sesion = { usuario: { id: string; nombre: string }; expiraEn: number }
type Credenciales = { correo: string; clave: string }

export const auth = setup({
  types: {
    context: {} as { sesion: Sesion | null; error: string | null; destino: string | null },
    events: {} as
      | { type: 'ENTRAR'; correo: string; clave: string }
      | { type: 'SALIR' }
      | { type: 'RENOVAR' },
  },
  actors: {
    restaurar: fromPromise(({ signal }): Promise<Sesion | null> => api.sesionActual(signal)),
    iniciar: fromPromise(({ input }: { input: Credenciales }) => api.entrar(input)),
    renovar: fromPromise(({ signal }): Promise<Sesion> => api.refrescar(signal)),
  },
  guards: {
    haySesion: ({ event }: any) => event.output !== null,
  },
  delays: {
    ANTES_DE_CADUCAR: ({ context }) =>
      Math.max(5_000, (context.sesion?.expiraEn ?? 0) - Date.now() - 60_000),
  },
}).createMachine({
  id: 'auth',
  initial: 'comprobando',
  context: { sesion: null, error: null, destino: null },
  states: {
    comprobando: {
      invoke: {
        src: 'restaurar',
        onDone: [
          { target: 'autenticado', guard: 'haySesion', actions: assign({ sesion: ({ event }) => event.output }) },
          { target: 'anonimo' },
        ],
        onError: 'anonimo',
      },
    },
    anonimo: {
      on: { ENTRAR: 'autenticando' },
    },
    autenticando: {
      entry: assign({ error: null }),
      invoke: {
        src: 'iniciar',
        input: ({ event }: any) => ({ correo: event.correo, clave: event.clave }),
        onDone: { target: 'autenticado', actions: assign({ sesion: ({ event }) => event.output }) },
        onError: { target: 'anonimo', actions: assign({ error: ({ event }) => String(event.error) }) },
      },
    },
    autenticado: {
      after: { ANTES_DE_CADUCAR: 'refrescando' },
      on: { SALIR: 'anonimo', RENOVAR: 'refrescando' },
    },
    refrescando: {
      invoke: {
        src: 'renovar',
        onDone: { target: 'autenticado', actions: assign({ sesion: ({ event }) => event.output }) },
        onError: 'expirado',
      },
      on: { SALIR: 'anonimo' },
    },
    expirado: {
      entry: assign({ sesion: null, error: 'sesion caducada' }),
      on: { ENTRAR: 'autenticando' },
    },
  },
})

Merece la pena detenerse en lo que este grafo no contiene, porque ahí está el trabajo real. No hay ninguna transición desde autenticando hacia autenticando, así que el segundo clic en el botón de entrar no dispara una segunda petición: el evento simplemente no existe en ese estado y el intérprete lo descarta. No hay ninguna arista desde anonimo hacia refrescando, así que ningún temporizador huérfano puede intentar renovar lo que no existe. Y comprobando no acepta ENTRAR, lo que impide la carrera clásica en la que el usuario envía el formulario mientras la restauración de sesión sigue en vuelo y ambas respuestas compiten por escribir el mismo contexto.

El grafo entero de un vistazo

stateDiagram-v2
[*] --> comprobando
comprobando --> autenticado: hay sesion restaurada
comprobando --> anonimo: no hay sesion
anonimo --> autenticando: ENTRAR
autenticando --> autenticado: credenciales validas
autenticando --> anonimo: credenciales rechazadas
autenticado --> refrescando: vence el margen o RENOVAR
autenticado --> anonimo: SALIR
refrescando --> autenticado: credencial renovada
refrescando --> expirado: el refresco falla
refrescando --> anonimo: SALIR
expirado --> autenticando: ENTRAR

La tabla de transiciones dice lo mismo en el registro que un revisor puede auditar línea a línea, y sirve además como contrato con quien escriba la interfaz, porque fija qué eventos tiene sentido ofrecer en cada pantalla.

Lo que el grafo elimina sin escribir una línea

Las cuatro tarjetas comparten una misma mecánica y conviene nombrarla, porque es el argumento central de todo el nivel: ninguno de esos fallos se corrige, se vuelve inexpresable. La diferencia es enorme en la práctica. Un fallo corregido depende de que la corrección siga presente después de cada refactorización, de cada nueva pantalla y de cada persona que se incorpora al equipo. Un fallo inexpresable no necesita mantenimiento, porque el código que lo produciría no compila o no tiene efecto.

Queda una advertencia importante antes de seguir. Todo lo anterior describe el cliente, y el cliente nunca es la autoridad. Este grafo modela lo que la aplicación cree sobre su sesión y qué le ofrece al usuario en consecuencia; la verdad sobre si una petición está permitida vive en el servidor y se verifica en cada llamada. Una máquina de autenticación bien hecha no sustituye la verificación remota: la vuelve innecesaria como mecanismo de interfaz, para que el servidor pueda dedicarse a ser autoridad en lugar de fuente de sorpresas.