JWT no Node.js: gerar, validar e proteger rotas no Express

Um JWT (JSON Web Token) é uma string de três partes em base64url, header.payload.signature, que o servidor entrega ao usuário no login e confere em toda requisição seguinte. A assinatura prova que o servidor emitiu o token e que ninguém o alterou, mas o payload só está codificado, não criptografado, então qualquer um consegue ler. No Node.js você cria um com new SignJWT(payload).sign(secret) do pacote jose e confere com 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);

Ele imprime 3 parts, depois user-42 admin: o jwtVerify conferiu a assinatura e a expiração e retornou o payload. Mude um caractere do segredo passado para o jwtVerify e rode de novo: a verificação falha com signature verification failed.

O que tem dentro de um JWT

O header e o payload são JSON, codificados em base64url. Decodificá-los não exige chave nenhuma, e é por isso que um JWT nunca deve guardar uma senha ou qualquer outra coisa secreta.

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

As duas primeiras linhas imprimem {"alg":"HS256"} e {"name":"Ada","role":"editor"}, legíveis para qualquer um que tenha o token. A assinatura (43 caracteres no HS256) é o que impede que alguém os edite: troque editor por admin e a assinatura deixa de bater.

Expiração e verificação que falha

setExpirationTime('15m') escreve uma claim exp, e o jwtVerify rejeita um token que passou dela. Toda rejeição é um erro com um code, então você consegue diferenciar um token expirado de um 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);
}

A primeira verificação falha com ERR_JWT_EXPIRED e a segunda, cuja assinatura foi alterada, com ERR_JWS_SIGNATURE_VERIFICATION_FAILED. Para a sua API as duas significam o mesmo (responder 401), mas registrar o código ajuda na hora de depurar.

Proteger uma rota Express com Bearer token

O cliente faz login uma vez, guarda o token e o envia no header Authorization como Bearer <token>. Um middleware verifica o token e coloca o payload em req.user para a rota.

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

A primeira requisição, GET /me sem token, recebe 401 e Missing token. Envie POST /login com o body {"username": "ada", "password": "lovelace"}, copie o token da resposta e envie GET /me de novo com o header Authorization: Bearer <token>: a resposta é {"id":"user-1","name":"ada"}.

O pacote jsonwebtoken

O jsonwebtoken (npm install jsonwebtoken) é a outra escolha comum. O sign e o verify dele são síncronos (com callbacks opcionais) em vez de retornar promises:

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

Use jose em código novo: ele não tem dependências e também roda em edge runtimes e navegadores. Tokens das duas bibliotecas são JWTs padrão, então uma consegue verificar o que a outra assinou.

Erros comuns

Usar decode em vez de verify. jwt.decode e decodeJwt leem o payload sem conferir a assinatura, então um token falsificado passa. Só confie no que o verify retorna.

Um segredo curto ou commitado. Um segredo HS256 fácil de adivinhar deixa atacantes assinarem os próprios tokens. Use pelo menos 32 bytes aleatórios, leia de process.env e nunca faça commit dele.

Tokens que nunca expiram. Sem exp, um token vazado funciona para sempre. Sempre defina uma expiração.