JsonWebToken في JavaScript (Node.js): دليل شامل مع أمثلة

ما هي JsonWebToken ولماذا تحتاجها؟

مكتبة JsonWebToken (غالبًا ما تُستخدم كـ jsonwebtoken أو jwt) هي واحدة من أشهر المكتبات للتعامل مع JSON Web Tokens (JWT) في بيئة Node.js. JWT هي طريقة مضغوطة ومكتفية ذاتيًا لنقل المعلومات بين الأطراف على شكل كائن JSON. يمكن التحقق من هذه المعلومات والوثوق بها لأنها موقعة بتوقيع رقمي. يمكن توقيع JWT باستخدام مفتاح سري (خوارزمية HMAC) أو زوج من المفاتيح العامة/الخاصة (خوارزميات RSA أو ECDSA).

الغرض الرئيسي من المكتبة هو تنفيذ آليات التفويض (Authorization) والمصادقة (Authentication) في تطبيقات الويب وواجهات API. عندما يسجل المستخدم الدخول بنجاح، يقوم الخادم بإنشاء JWT وإرساله إلى العميل. ثم يرسل العميل هذا الرمز مع كل طلب لاحق، مما يسمح للخادم بالتحقق من هوية المستخدم دون الحاجة إلى تخزين بيانات الجلسة على الخادم. وهذا يجعل JWT حلاً مثاليًا لبناء RESTful APIs، والهندسات المعمارية القائمة على الخدمات المصغرة، والتطبيقات ذات الصفحة الواحدة (SPA).

توفر مكتبة jsonwebtoken مجموعة كاملة من الأدوات لإنشاء (sign) والتحقق (verify) وفك تشفير (decode) الرموز. وهي تدعم جميع خوارزميات التوقيع القياسية، بما في ذلك HS256 وRS256 وES256، وتتيح ضبط مدة صلاحية الرمز بمرونة، وإضافة حقول مخصصة (claims)، والعمل مع المفاتيح العامة/الخاصة. بفضل موثوقيتها وبساطتها، تُستخدم هذه المكتبة في آلاف المشاريع حول العالم وتُعتبر المعيار الفعلي للتعامل مع JWT في نظام Node.js البيئي.

التثبيت

لتثبيت مكتبة JsonWebToken في مشروع Node.js الخاص بك، قم بتنفيذ الأمر التالي في الطرفية:

npm install jsonwebtoken

إذا كنت تستخدم Yarn:

yarn add jsonwebtoken

بعد التثبيت، يمكنك استيراد المكتبة في الكود الخاص بك:

const jwt = require('jsonwebtoken');
// أو لوحدات ES:
// import jwt from 'jsonwebtoken';

بداية سريعة — مثال عملي بسيط

لنقم بإنشاء مثال بسيط يوضح إنشاء والتحقق من رمز JWT:

const jwt = require('jsonwebtoken');

// المفتاح السري (في مشروع حقيقي، احفظه في ملف .env)
const secretKey = 'my-super-secret-key-123';

// البيانات التي نريد ترميزها في الرمز (payload)
const payload = {
  userId: 12345,
  username: 'john_doe',
  role: 'user'
};

// 1. إنشاء الرمز
const token = jwt.sign(payload, secretKey, { expiresIn: '1h' });
console.log('الرمز المُنشأ:', token);

// 2. التحقق من الرمز
try {
  const decoded = jwt.verify(token, secretKey);
  console.log('البيانات المُفككة:', decoded);
  // الناتج: { userId: 12345, username: 'john_doe', role: 'user', iat: ..., exp: ... }
} catch (err) {
  console.error('خطأ في التحقق من الرمز:', err.message);
}

// 3. فك التشفير بدون التحقق من التوقيع (غير موصى به للتفويض!)
const decodedWithoutVerify = jwt.decode(token);
console.log('تم فك التشفير بدون تحقق:', decodedWithoutVerify);

يوضح هذا المثال ثلاث عمليات رئيسية: إنشاء الرمز باستخدام sign()، والتحقق من صحته باستخدام verify()، وفك التشفير البسيط دون التحقق من التوقيع باستخدام decode().