Permisos: guardas en las aristas, no condicionales sueltos

Casi todas las aplicaciones empiezan su autorización con una línea razonable en un componente razonable, algo del estilo de comprobar si el rol del usuario es administrador antes de pintar un botón. El problema no es esa línea sino su descendencia: seis meses después existen cuarenta variantes suyas repartidas por la interfaz, tres de ellas ligeramente distintas, ninguna probada, y nadie en el equipo puede responder a la pregunta de quién puede aprobar un documento sin abrir el buscador. La autorización se ha vuelto invisible precisamente por estar en todas partes. Modelarla como guardas sobre las transiciones invierte esa dispersión: la regla se escribe una vez, con nombre, en el mismo sitio donde vive el resto del comportamiento, y todo lo demás la consulta en lugar de reproducirla.

La regla vive en la arista

Un permiso responde siempre a la misma forma de pregunta: si este usuario intenta esta acción en esta situación, ¿debe ocurrir algo? Esa forma es literalmente la de una guarda, un predicado que decide si una transición se toma. Cuando la comprobación está en el componente, la máquina acepta el evento y confía en que nadie se lo mande; cuando está en la arista, mandarlo es inofensivo porque no produce efecto. La diferencia práctica aparece el día que un evento llega por un camino nuevo —un atajo de teclado, una acción por lotes, una llamada desde otra máquina— y descubre que la única defensa estaba dibujada en un botón.

import { setup, assign, and, or, not } from 'xstate'

export const documento = setup({
  types: {
    context: {} as { permisos: ReadonlySet<string>; autor: string; yo: string },
    events: {} as
      | { type: 'EDITAR' } | { type: 'ENVIAR_A_REVISION' }
      | { type: 'APROBAR' } | { type: 'PUBLICAR' }
      | { type: 'PERMISOS_CAMBIADOS'; permisos: string[] },
  },
  guards: {
    tienePermiso: ({ context }, params: { clave: string }) => context.permisos.has(params.clave),
    esAutor: ({ context }) => context.autor === context.yo,
  },
}).createMachine({
  id: 'documento',
  initial: 'borrador',
  context: { permisos: new Set(), autor: '', yo: '' },
  on: {
    PERMISOS_CAMBIADOS: { actions: assign({ permisos: ({ event }) => new Set(event.permisos) }) },
  },
  states: {
    borrador: {
      on: {
        EDITAR: {
          guard: or(['esAutor', { type: 'tienePermiso', params: { clave: 'doc.editar.ajeno' } }]),
        },
        ENVIAR_A_REVISION: { target: 'enRevision', guard: 'esAutor' },
      },
    },
    enRevision: {
      on: {
        APROBAR: {
          target: 'aprobado',
          guard: and([{ type: 'tienePermiso', params: { clave: 'doc.aprobar' } }, not('esAutor')]),
        },
        EDITAR: { target: 'borrador', guard: { type: 'tienePermiso', params: { clave: 'doc.devolver' } } },
      },
    },
    aprobado: {
      on: {
        PUBLICAR: { target: 'publicado', guard: { type: 'tienePermiso', params: { clave: 'doc.publicar' } } },
      },
    },
    publicado: { type: 'final' },
  },
})

Hay tres decisiones de diseño en ese fragmento que conviene señalar. La primera es que las guardas comprueban permisos y no roles: el contexto guarda un conjunto de capacidades y el rol se queda fuera de la máquina, donde le corresponde, como una abreviatura que el servidor expande antes de entregar la sesión. Añadir un rol nuevo deja de tocar la máquina, que es exactamente la propiedad que se busca. La segunda es que la condición de aprobación combina tener permiso con no ser el autor, una regla de negocio real que ningún sistema de roles expresa por sí solo y que aquí queda escrita en una sola arista. La tercera es que los permisos se actualizan por evento en el nivel raíz, porque las capacidades cambian a mitad de sesión y una máquina que las lea una vez al arrancar se queda desfasada sin enterarse.

Componer en lugar de anidar

Las condiciones reales rara vez son atómicas, y ahí es donde el condicional disperso degenera más deprisa: una comparación se convierte en dos unidas por una conjunción, luego aparece una excepción, y en tres iteraciones nadie sabe leer la expresión. Los combinadores de guardas mantienen la legibilidad porque cada pieza conserva su nombre y la composición se lee como la frase del dominio que representa.

La última tarjeta apunta a un patrón que resuelve el problema más incómodo de este nivel: la autorización cruza dos dominios que evolucionan por separado, la sesión y el recurso. Modelarlos como regiones paralelas permite que una guarda del documento consulte en qué estado está la sesión sin que ninguna de las dos regiones dependa del ciclo de vida de la otra.

import { stateIn } from 'xstate'

PUBLICAR: {
  target: 'publicado',
  guard: and([
    stateIn({ sesion: 'autenticado' }),
    { type: 'tienePermiso', params: { clave: 'doc.publicar' } },
  ]),
},

stateDiagram-v2
[*] --> borrador
borrador --> enRevision: ENVIAR_A_REVISION si es el autor
borrador --> borrador: EDITAR si es autor o tiene permiso sobre ajenos
enRevision --> aprobado: APROBAR si tiene permiso y no es el autor
enRevision --> borrador: EDITAR si tiene permiso de devolucion
aprobado --> publicado: PUBLICAR si tiene permiso y la sesion sigue viva
publicado --> [*]

La interfaz pregunta en vez de deducir

Con las reglas en las aristas queda un cabo suelto que decide si todo el ejercicio sirve de algo: cómo sabe el botón si debe estar disponible. Reimplementar la condición en el componente devolvería la duplicación por la puerta de atrás, y esta vez con el agravante de que las dos copias parecerían coherentes hasta que dejaran de serlo. La respuesta es no deducir nada y preguntar directamente al actor si el evento produciría una transición.

const instantanea = actorDocumento.getSnapshot()

const acciones = [
  { evento: { type: 'ENVIAR_A_REVISION' } as const, etiqueta: 'Enviar a revision' },
  { evento: { type: 'APROBAR' } as const, etiqueta: 'Aprobar' },
  { evento: { type: 'PUBLICAR' } as const, etiqueta: 'Publicar' },
].filter((a) => instantanea.can(a.evento))

El método que interroga la instantánea evalúa el estado actual, las transiciones declaradas y las guardas asociadas, y responde si el evento sería aceptado. La consecuencia es que la política queda escrita una vez y la interfaz se convierte en su lector: añadir una capacidad, cambiar una condición o introducir un estado nuevo actualiza los botones sin tocar un solo componente. Es la misma relación que hay entre una gramática y un corrector, y explica por qué esta forma de autorizar envejece bien mientras la otra se pudre.

Afordancia no es autorización

Todo lo anterior describe lo que la aplicación ofrece, y ofrecer no es permitir. Un cliente puede ser modificado, una petición puede fabricarse a mano y una guarda del navegador no defiende nada frente a quien no usa el navegador. La máquina de permisos existe para que la interfaz sea coherente, comprensible y difícil de usar mal, no para proteger el recurso; la protección se verifica en el servidor, en cada petición, con la misma regla expresada en su propio dominio.

Esa duplicación entre cliente y servidor es legítima y hay que gestionarla con honestidad. Lo peligroso no es que la regla exista en dos sitios, sino que diverja sin que nadie lo note: la interfaz ofrece una acción que el servidor rechazará, o la esconde aunque estuviera permitida. La disciplina que mejor funciona es que el servidor sea la única fuente de las capacidades y las entregue con la sesión, de modo que el cliente no decida quién puede qué sino solo cómo presentar lo que el servidor ya decidió.