JWT in Node.js: firmare, verificare e proteggere le route

Un JWT (JSON Web Token) è una stringa di tre parti base64url, header.payload.signature, che un server dà a un utente al login e controlla a ogni richiesta successiva. La firma dimostra che il token l'ha emesso il server e che nessuno l'ha modificato, ma il payload è solo codificato, non cifrato, quindi chiunque può leggerlo. In Node.js ne crei uno con new SignJWT(payload).sign(secret) dal pacchetto jose e lo controlli 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);

Stampa 3 parts, poi user-42 admin: jwtVerify ha controllato firma e scadenza e ha restituito il payload. Cambia di un carattere il secret passato a jwtVerify ed eseguilo di nuovo: la verifica fallisce con signature verification failed.

Cosa c'è dentro un JWT

Header e payload sono JSON codificato in base64url. Per decodificarli non serve nessuna chiave, ed è per questo che un JWT non deve mai contenere una password o altro di segreto.

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);

Le prime due righe stampano {"alg":"HS256"} e {"name":"Ada","role":"editor"}, leggibili da chiunque abbia il token. La firma (43 caratteri per HS256) è ciò che impedisce di modificarlo: cambia editor in admin e la firma non corrisponde più.

Scadenza e verifica fallita

setExpirationTime('15m') scrive un claim exp, e jwtVerify rifiuta un token scaduto. Ogni rifiuto è un errore con un code, così puoi distinguere un token scaduto da uno contraffatto.

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);
}

Il primo controllo fallisce con ERR_JWT_EXPIRED e il secondo, con la firma modificata, con ERR_JWS_SIGNATURE_VERIFICATION_FAILED. Per la tua API significano la stessa cosa (rispondere 401), ma scrivere il codice nel log aiuta nel debug.

Proteggere una route Express con un Bearer token

Il client fa il login una volta, conserva il token e lo invia nell'header Authorization come Bearer <token>. Un middleware lo verifica e mette il payload in req.user per la route.

// 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 prima richiesta, GET /me senza token, riceve 401 e Missing token. Invia POST /login con il body {"username": "ada", "password": "lovelace"}, copia il token dalla risposta, poi invia di nuovo GET /me con l'header Authorization: Bearer <token>: la risposta è {"id":"user-1","name":"ada"}.

Il pacchetto jsonwebtoken

jsonwebtoken (npm install jsonwebtoken) è l'altra scelta comune. I suoi sign e verify sono sincroni (con callback opzionali) invece di restituire promise:

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

Per il codice nuovo usa jose: non ha dipendenze e gira anche negli edge runtime e nei browser. I token di entrambe le librerie sono JWT standard, quindi una può verificare quello che ha firmato l'altra.

Errori comuni

Usare decode invece di verify. jwt.decode e decodeJwt leggono il payload senza controllare la firma, quindi un token contraffatto passa. Fidati solo di quello che restituisce verify.

Un secret corto o finito nel commit. Un secret HS256 indovinabile permette a un attaccante di firmare i suoi token. Usa almeno 32 byte casuali, leggilo da process.env e non metterlo mai in un commit.

Token che non scadono mai. Senza exp, un token trapelato funziona per sempre. Imposta sempre una scadenza.