JWT en Node.js: firmar, verificar y proteger rutas Express

Un JWT (JSON Web Token) es un string de tres partes en base64url, header.payload.signature, que el servidor le da al usuario en el login y comprueba en cada petición posterior. La firma demuestra que el servidor emitió el token y que nadie lo ha cambiado, pero el payload solo está codificado, no cifrado, así que cualquiera puede leerlo. En Node.js creas uno con new SignJWT(payload).sign(secret) del paquete jose y lo compruebas con jwtVerify(token, secret).

import { SignJWT, jwtVerify } from 'jose';

// In a real app the secret comes from process.env.JWT_SECRET
const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');

const token = await new SignJWT({ role: 'admin' })
    .setProtectedHeader({ alg: 'HS256' })
    .setSubject('user-42')
    .setIssuedAt()
    .setExpirationTime('1h')
    .sign(secret);

console.log(token.split('.').length, 'parts');

const { payload } = await jwtVerify(token, secret);
console.log(payload.sub, payload.role);

Imprime 3 parts y luego user-42 admin: jwtVerify comprobó la firma y la expiración y devolvió el payload. Cambia un carácter del secreto que se pasa a jwtVerify y vuelve a ejecutarlo: la verificación falla con signature verification failed.

Qué hay dentro de un JWT

El header y el payload son JSON codificado en base64url. Decodificarlos no requiere ninguna clave, y por eso un JWT nunca debe contener una contraseña ni nada secreto.

import { SignJWT } from 'jose';

const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');
const token = await new SignJWT({ name: 'Ada', role: 'editor' })
    .setProtectedHeader({ alg: 'HS256' })
    .sign(secret);

const [header, payload, signature] = token.split('.');

console.log(Buffer.from(header, 'base64url').toString());
console.log(Buffer.from(payload, 'base64url').toString());
console.log(signature.length);

Las dos primeras líneas imprimen {"alg":"HS256"} y {"name":"Ada","role":"editor"}, que puede leer cualquiera que tenga el token. La firma (43 caracteres en HS256) es lo que impide modificarlo: cambia editor por admin y la firma deja de coincidir.

Expiración y verificación fallida

setExpirationTime('15m') escribe un claim exp, y jwtVerify rechaza un token que ya lo ha pasado. Cada rechazo es un error con un code, así que puedes distinguir un token expirado de uno falsificado.

import { SignJWT, jwtVerify } from 'jose';

const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');
const expired = await new SignJWT({ sub: 'user-42' })
    .setProtectedHeader({ alg: 'HS256' })
    .setExpirationTime(1700000000) // a moment in 2023, long past
    .sign(secret);

try {
    await jwtVerify(expired, secret);
} catch (err) {
    console.log(err.code);
}

const forged = expired.slice(0, -2) + 'xx';
try {
    await jwtVerify(forged, secret);
} catch (err) {
    console.log(err.code);
}

La primera comprobación falla con ERR_JWT_EXPIRED y la segunda, cuya firma se cambió, con ERR_JWS_SIGNATURE_VERIFICATION_FAILED. Para tu API los dos significan lo mismo (responde 401), pero registrar el código ayuda al depurar.

Proteger una ruta de Express con un Bearer token

El cliente hace login una vez, guarda el token y lo envía en el header Authorization como Bearer <token>. Un middleware lo verifica y pone el payload en req.user para la ruta.

// GET /me
import express from 'express';
import { SignJWT, jwtVerify } from 'jose';

const secret = new TextEncoder().encode('a-long-random-secret-of-32-chars!!');
const app = express();
app.use(express.json());

app.post('/login', async (req, res) => {
    const { username, password } = req.body ?? {};
    // A real app looks the user up and checks a hashed password
    if (username !== 'ada' || password !== 'lovelace') {
        return res.status(401).json({ error: 'Wrong username or password' });
    }
    const token = await new SignJWT({ name: username })
        .setProtectedHeader({ alg: 'HS256' })
        .setSubject('user-1')
        .setExpirationTime('15m')
        .sign(secret);
    res.json({ token });
});

async function requireAuth(req, res, next) {
    const header = req.get('authorization') ?? '';
    const token = header.startsWith('Bearer ') ? header.slice(7) : null;
    if (!token) return res.status(401).json({ error: 'Missing token' });
    try {
        const { payload } = await jwtVerify(token, secret);
        req.user = payload;
        next();
    } catch {
        res.status(401).json({ error: 'Invalid or expired token' });
    }
}

app.get('/me', requireAuth, (req, res) => {
    res.json({ id: req.user.sub, name: req.user.name });
});

app.listen(3000);

La primera petición, GET /me sin token, recibe 401 y Missing token. Envía POST /login con el body {"username": "ada", "password": "lovelace"}, copia el token de la respuesta y vuelve a enviar GET /me con el header Authorization: Bearer <token>: la respuesta es {"id":"user-1","name":"ada"}.

El paquete jsonwebtoken

jsonwebtoken (npm install jsonwebtoken) es la otra opción habitual. Sus sign y verify son síncronos (con callbacks opcionales) en lugar de devolver promesas:

const jwt = require('jsonwebtoken');

const token = jwt.sign({ role: 'admin' }, process.env.JWT_SECRET, {
    subject: 'user-42',
    expiresIn: '1h',
});

const payload = jwt.verify(token, process.env.JWT_SECRET); // throws if invalid

Usa jose en código nuevo: no tiene dependencias y además funciona en edge runtimes y navegadores. Los tokens de las dos librerías son JWT estándar, así que una puede verificar lo que firmó la otra.

Errores comunes

Usar decode en lugar de verify. jwt.decode y decodeJwt leen el payload sin comprobar la firma, así que un token falsificado pasa. Fíate solo de lo que devuelve verify.

Un secreto corto o subido al repositorio. Un secreto HS256 fácil de adivinar permite a un atacante firmar sus propios tokens. Usa al menos 32 bytes aleatorios, léelo de process.env y nunca lo subas al repositorio.

Tokens que nunca expiran. Sin exp, un token filtrado funciona para siempre. Pon siempre una expiración.