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 من التوقيع ومن مدة الصلاحية وأعادت الحمولة. غيّر حرفًا واحدًا في السر الممرَّر إلى jwtVerify وشغّل من جديد: يفشل التحقق بـ signature verification failed.

ما الذي يحتويه JWT

الترويسة والحمولة بصيغة 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') المطالبة 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 ويضع الحمولة في 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 فيها متزامنتان (مع callbacks اختيارية) بدلًا من إعادة وعود:

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 وفي المتصفحات. الرموز الصادرة من أي من المكتبتين رموز JWT قياسية، فتستطيع إحداهما التحقق مما وقّعته الأخرى.

أخطاء شائعة

استخدام decode بدلًا من verify. تقرأ jwt.decode وdecodeJwt الحمولة دون فحص التوقيع، فيمر الرمز المزوّر. لا تثق إلا بما تعيده verify.

سر قصير أو مرفوع إلى المستودع. سر HS256 قابل للتخمين يتيح للمهاجمين توقيع رموزهم الخاصة. استخدم 32 بايتًا عشوائيًا على الأقل، واقرأه من process.env، ولا ترفعه إلى المستودع أبدًا.

رموز لا تنتهي صلاحيتها أبدًا. دون exp، يعمل الرمز المسرّب إلى الأبد. اضبط مدة الصلاحية دائمًا.