JWT в Node.js: подпись, проверка и защита маршрутов Express

JWT (JSON Web Token) это строка из трёх частей в base64url, header.payload.signature, которую сервер выдаёт пользователю при входе и проверяет на каждом следующем запросе. Подпись доказывает, что токен выдал сервер и никто его не менял, но payload только закодирован, а не зашифрован, поэтому прочитать его может любой. В Node.js токен создают через new SignJWT(payload).sign(secret) из пакета jose и проверяют через 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);

Программа выводит 3 parts, затем user-42 admin: jwtVerify проверил подпись и срок действия и вернул payload. Измените на один символ секрет, который передаётся в jwtVerify, и запустите снова: проверка упадёт с signature verification failed.

Что внутри JWT

Header и payload это JSON, закодированный в base64url. Для декодирования ключ не нужен, поэтому в JWT нельзя класть пароль или любые другие секреты.

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

Первые две строки выводят {"alg":"HS256"} и {"name":"Ada","role":"editor"}, их может прочитать любой, у кого есть токен. Изменить их мешает подпись (43 символа для HS256): поменяйте editor на admin, и подпись перестанет совпадать.

Срок действия и неудачная проверка

setExpirationTime('15m') записывает claim exp, и jwtVerify отклоняет токен, срок которого истёк. Каждый отказ это ошибка с полем code, так что просроченный токен можно отличить от поддельного.

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

Первая проверка падает с ERR_JWT_EXPIRED, а вторая, где подпись изменена, с ERR_JWS_SIGNATURE_VERIFICATION_FAILED. Для вашего API оба случая значат одно и то же (ответ 401), но код в логах помогает при отладке.

Защитить маршрут Express Bearer токеном

Клиент один раз входит, сохраняет токен и отправляет его в заголовке Authorization в виде Bearer <token>. Middleware проверяет токен и кладёт payload в req.user для маршрута.

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

Первый запрос, GET /me без токена, получает 401 и Missing token. Отправьте POST /login с телом {"username": "ada", "password": "lovelace"}, скопируйте token из ответа и снова отправьте GET /me с заголовком Authorization: Bearer <token>: ответ будет {"id":"user-1","name":"ada"}.

Пакет jsonwebtoken

jsonwebtoken (npm install jsonwebtoken) это другой популярный вариант. Его sign и verify синхронные (с необязательными callback), а не возвращают промисы:

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

Для нового кода берите jose: у него нет зависимостей, и он работает также в edge runtime и в браузерах. Обе библиотеки выдают стандартные JWT, поэтому одна может проверить то, что подписала другая.

Частые ошибки

decode вместо verify. jwt.decode и decodeJwt читают payload без проверки подписи, так что поддельный токен пройдёт. Доверяйте только тому, что вернул verify.

Короткий или закоммиченный секрет. Угадываемый секрет HS256 позволяет атакующему подписывать свои токены. Используйте минимум 32 случайных байта, читайте секрет из process.env и никогда не коммитьте его.

Токены без срока действия. Без exp утёкший токен работает вечно. Всегда задавайте срок действия.