الإقليم ٧ — الهويّةُ بلا حالة: bcrypt و JWT من الصفر

النبذة

هنا نحلّ أقدمَ بذرةٍ في المنهج. الإقليم ٠ قال: HTTP عديمُ الذاكرة — الخادمُ ينساك بمجرّد أن يُغلَق الاتصال، وهذا عمداً كي يتوسّع أفقياً (أيُّ نسخةٍ تخدم أيَّ طلب). ومع ذلك GET /me يجب أن يعرفك، والتصحيحُ يجب أن يسمح للمسجَّل فقط. كيف يعرفك خادمٌ بلا ذاكرةٍ في كل طلبٍ مستقلّ، دون أن يحفظ جلسةً لكل مستخدمٍ (ما يكسر انعدامَ الحالة)؟ ومسألةٌ ثانيةٌ موازية: كيف تخزّن كلمةَ مرورٍ بحيث لا يمنح اختراقُ القاعدةِ المهاجمَ كلماتِ مرور الجميع؟ مسألتان، نبنيهما من جذرهما — وستخرج منهما بفهمٍ يجعلك لا تخاف JWT أبداً.

اللغز المستفزّ

الجزء الأول — كلمات المرور و bcrypt

ليش: التجزئة أحاديّةُ الاتّجاه، لا التشفير

التشفيرُ (encryption) قابلٌ للعكس بمفتاح — خطأٌ لكلمات المرور، لأن وجودَ مفتاحٍ يعني وجودَ بابٍ خلفيّ. ما تريده دالةُ تجزئةٍ أحاديّةُ الاتّجاه (hash): سهلةُ الحساب أماماً (كلمة → بصمة)، مستحيلةُ العكس (بصمة → كلمة). تخزّن البصمة. عند الدخول، تجزّئ المُدخَلَ وتقارن البصمتين. لا تسترجع شيئاً أبداً. حلَّ اللغز أ — لكن الشيطانُ في التفاصيل.

ليش لا تجزئةً سريعةً (مثل SHA-256)؟ لأنك تريدها بطيئةً عمداً

SHA-256 سريعةٌ جداً — وهذا عيبٌ هنا. المهاجمُ الذي سرق بصماتِك يجرّب مليارات التخمينات في الثانية على عتادٍ رخيص (أو يستعمل جداولَ قوس قزح: بصماتٌ محسوبةٌ مسبقاً لكلماتٍ شائعة). تريد دالةً بطيئةً ومكلفةً عمداً، فتخمينُ المهاجمِ يصير مؤلماً، بينما تحقّقُك الواحدُ عند الدخول يحتمل التأخيرَ البسيط.

كيف: bcrypt — ملحٌ + معاملُ كلفة

bcrypt دالةُ تجزئةٍ صُمِّمت لهذا:

• الملح (salt): قيمةٌ عشوائيةٌ فريدةٌ لكل كلمةِ مرور، تُدمَج قبل التجزئة وتُخزَّن مع البصمة. أثرُه: كلمتان متطابقتان تنتجان بصمتين مختلفتين (فلا يكشف المهاجمُ المستخدمين ذوي الكلمة نفسها)، وتبطل جداولُ قوس قزح كلّها (لأنها مبنيّةٌ على كلماتٍ بلا ملح).
• معاملُ الكلفة (cost / work factor): الرقم 10 في bcrypt.hash(password, 10) بمشروعك. يضبط عددَ الجولات أُسّياً (2^10)؛ كلّما زاد، أبطأ — تواكب به تسارعَ العتاد عبر السنين. مقايضةٌ واعية: أمنٌ أعلى مقابل زمنٍ أطول لكل تجزئة.

كيف: التحقّق (دون استرجاع)

ts
const hash = await bcrypt.hash(password, 10);              // التسجيل: خزّن hash (يحوي الملح)
const ok   = await bcrypt.compare(candidate, hash);        // الدخول: أعِد التجزئةَ بنفس الملح وقارن

compare يستخرج الملحَ من البصمة المخزّنة، يجزّئ المُدخَل به، ويقارن بزمنٍ ثابتٍ (constant-time — لا يُفشي طولَ التطابق عبر توقيتِ المقارنة، حمايةً من هجمات التوقيت). لا decrypt — لا وجودَ له. تدفّقُ الدخول: ابحث عن المستخدم بـ email/username (Prisma، ٥)، bcrypt.compare، فإن صحّ أصدِر إثباتَ هويّة. ما هذا الإثبات؟ الجزء الثاني.

الجزء الثاني — JWT من الصفر

ليش: لماذا token لا جلسةٌ على الخادم؟

طريقتان لتذكّر "من المُرسِل" فوق بروتوكولٍ بلا ذاكرة:

• جلسةٌ على الخادم (sessions): عند الدخول، يولّد الخادمُ session_id عشوائياً، يخزّن session_id → user في ذاكرته/Redis، ويعطي العميلَ المعرّفَ فقط. كلُّ طلبٍ يحمل المعرّف، فيبحث الخادمُ عنه. المشكلة: هذه حالةٌ على الخادم — تكسر انعدامَ الحالة (٠)، وتتطلّب مخزَناً مشتركاً بين كل النسخ (وإلّا "تلتصق" بنسخةٍ واحدة، فينهار التوسّعُ الأفقيّ الذي تعرفه).
• رمزٌ محمولٌ موقَّع (token): اجعل الإثباتَ يحمل ادّعاءاتِه بنفسه (من، أيُّ دور، متى ينتهي)، موقَّعاً بسرٍّ لا يملكه إلا الخادم. كلُّ طلبٍ يحمله؛ الخادمُ يتحقّق من التوقيع بسرّه ويصدّق الادّعاءات بلا أي بحثٍ أو تخزين. يبقى عديمَ الحالة، وأيُّ نسخةٍ تتحقّق فوراً. هذا JWT.

مقايضةٌ صادقة: الـ token صعبُ الإبطال قبل انتهائه (لا سجلَّ مركزياً تحذفه منه)، وحجمُه أكبر، ويُعاد إرسالُه كلَّ طلب. حلولٌ (انتهاءٌ قصير + refresh tokens) بذرةٌ لما بعد. لكن لانعدام الحالة والتوسّع، الـ token هو الجواب.

كيف: بنية JWT — ثلاثةُ أجزاءٍ بـ base64url

code
                header . payload . signature
   eyJhbGciOiJIUzI1NiJ9 . eyJzdWIiOiJ1MSIsInJvbGUiOiJVU0VSIn0 . 3Tb9aP...

• header: {"alg":"HS256","typ":"JWT"} — أيُّ خوارزميةِ توقيع.
• payload: الادّعاءات (claims) — sub (هويّةُ المستخدم)، role، iat (وقت الإصدار)، exp (وقت الانتهاء). بياناتُك.
• signature: HMAC-SHA256( base64url(header) + "." + base64url(payload), SECRET ). توقيعٌ على الجزأين الأولين بالسرّ.

كلُّ جزءٍ مُرمَّزٌ بـ base64url (تمثيلٌ نصّيٌّ آمنٌ للـ URL، ليس تشفيراً).

⚠️ الفهمُ الذي يفصل المحترفَ من غيره: التوقيع ≠ التشفير

كيف تمنع التزوير إذن؟ لو غيّر العميلُ "role":"USER" إلى "ADMIN"، تغيّر payload، فلم يعد التوقيعُ يطابق — والعميلُ لا يستطيع حسابَ توقيعٍ جديدٍ صحيحٍ لأنه لا يملك SECRET. الخادمُ يعيد حسابَ التوقيع بسرّه ويقارن؛ لا يطابق → رفض. هذا حلُّ اللغز ب: إثباتٌ محمولٌ، قابلُ القراءة، مستحيلُ التزوير بلا السرّ.

السرّ (JWT_SECRET) — كلُّ الأمن هنا

التوقيعُ والتحقّقُ يعتمدان على SECRET واحد. من يملكه يصنع رموزاً صالحةً لأي مستخدمٍ وأي دور — أي يصير أيَّ أحد. لهذا يأتي من process.env.JWT_SECRET (٢)، طويلاً عشوائياً، لا يُلتزَم في git أبداً (تذكّر Fix: Restored .env.example after security breach في تاريخ مشروعك — درسٌ حيّ على ثمنِ تسريب الأسرار).

كيف: الهويّةُ كـ middleware (تركيبٌ مع الإقليم ٣)

"كلُّ حدٍّ يحتاج بوّابة" (٦) — والهويّةُ بوّابةُ حدٍّ على المُرسِل. حلقتان في السلسلة:

ts
// authenticate: من أنت؟ تحقّق من الرمز أو 401
function authenticate(req, res, next) {
  const header = req.headers.authorization;            // "Bearer <token>"
  const token = header?.startsWith("Bearer ") ? header.slice(7) : null;
  if (!token) return res.status(401).json({ success: false, message: "no token" });
  try {
    req.user = verifyJWT(token, process.env.JWT_SECRET); // { sub, role, ... }
    next();
  } catch {
    return res.status(401).json({ success: false, message: "invalid token" });  // مزوَّر/منتهٍ
  }
}

// authorize: عرفتُك، لكن هل يُسمح لك؟ أو 403
function authorize(...roles) {
  return (req, res, next) =>
    roles.includes(req.user.role) ? next() : res.status(403).json({ success: false, message: "forbidden" });
}

استعمال: app.get("/me", authenticate, meController) و app.post("/curricula", authenticate, authorize("ADMIN"), createCurriculum).

فرقُ 401 و 403 (٠) يتجسّد: authenticate يردّ 401 (من أنت؟ لم تُثبت)؛ authorize يردّ 403 (عرفتُك، ممنوع). والسلسلةُ تكتمل: helmet → cors → json → rate-limit → validate(Zod) → authenticate → authorize → controller → service(Prisma).

الحاملُ: ترويسةٌ أم كوكي؟ (مشروعك يملك الاثنين)

أين يحفظ العميلُ الرمزَ ويرسله؟ مقايضةٌ صادقة:

• Authorization: Bearer <token>: بسيطٌ لتطبيقات الصفحة الواحدة (SPA)؛ لكن لو خُزِّن في JS (localStorage) فثغرةُ XSS قد تسرقه.
• كوكي httpOnly: لا يصلها JS (تقاوم سرقةَ XSS)، يرسلها المتصفّحُ تلقائياً؛ لكن تحتاج حمايةَ CSRF. (لهذا في تبعيّات مشروعك cookie-parser — الخيارُ متاح.)

مشروعك يميل لترويسة Bearer (README)، ويملك cookie-parser لو اختار الكوكي. لا حلَّ مثاليّ — قرارٌ تملكه الآن بفهمِ مقايضته.

اللغز / البناء من الصفر

الخلاصة — أين تتّصل هذه العقدة بالشجرة

الوصلة للواقع (نمط SelfLab)

تبعيّاتُ مشروعك تنكشف كنظامِ هويّةٍ كامل: bcrypt (التجزئة)، jsonwebtoken + @types/jsonwebtoken (الرموز، النسخةُ المكتبيّةُ لِما بنيتَه بيدك)، JWT_SECRET في .env.example (السرّ من البيئة)، cookie-parser (خيارُ الحامل)، express-rate-limit (يخنق تخمينَ كلمات المرور على login). والمتحكّمُ الحاليُّ يفعل password: await bcrypt.hash(password, 10) ويُسقِط password من select الردّ (٥) — لا تُسرَّب البصمةُ أبداً.

ما ينقص وصرتَ تبنيه: متحكّمُ login (findUnique → compare → sign)، ودالّتا authenticate/authorize كـ middleware، وحمايةُ GET /me وما بعده، واختيارُ الحامل (Bearer أم كوكي httpOnly). تملكها كلَّها الآن، بفهمِ كلِّ مقايضة.