تصميم الرمز Secured والتوقيع HMAC
المسار: تطوير نظام إدارة الأعراس ودعوات QR الوحدة: توليد وقراءة رموز QR
مدخل إلى الدرس: تصميم الرمز Secured والتوقيع HMAC
تصميم الرمز Secured والتوقيع HMAC — نظام إدارة الأعراس والمناسبات ودعوات QR | Next.js وPrisma | أديب الصلوي
طريقة الدراسة: اقرأ التعريف، تتبّع المثال في الشرح، نفّذه بنفسك، ثم اختبر النتيجة والحالات الاستثنائية قبل الانتقال.
خريطة بصرية للمفهوم
flowchart LR
A["طلبات المناسبة"]
B["إدارة الدعوات"]
C["إصدار QR"]
D["التحقق من الدعوة"]
E["متابعة الحضور"]
A --> B
B --> C
C --> D
D --> Eالتسلسل: طلبات المناسبة ← إدارة الدعوات ← إصدار QR ← التحقق من الدعوة ← متابعة الحضور.
أهداف هذا الدرس
- تصميم محتوى الرمز: token + sig داخل رابط واحد.
- بناء مكتبة tsign.ts كاملة (إنشاء، هاش، توقيع، تحقق).
- النقاش العقلي: لماذا HMAC وليس توقيعاً عاماً/خاصاً هنا.
مثال
// lib/tsign.ts — المكتبة الكاملة
import { createHmac, randomBytes, timingSafeEqual } from "crypto";
const SECRET = process.env.SIGNING_SECRET!;
export function makeToken() {
return randomBytes(24).toString("base64url"); // 192 bits
}
export function tokenHashOf(token: string) {
return createHmac("sha256", SECRET).update(token).digest("hex");
}
export function signatureOf(token: string) {
return createHmac("sha256", SECRET).update("guest:" + token).digest("hex");
}
export function verifySignature(token: string, signature: string) {
const expected = signatureOf(token);
const a = Buffer.from(expected, "hex");
const b = Buffer.from(signature, "hex");
return a.length === b.length && timingSafeEqual(a, b);
}المخطط: تشريح الرابط الموقّع للدعوة
flowchart LR
U["https://site.com/i/"] --> T["VjGk3Z6q..."]
U --> S["?sig=9f2c...e1"]
T --> TN["token (مبدّل)
نبحث به عن الضيف"]
S --> SN["توقيع HMAC(SECRET, guest:token)
يثبت أن الرابط من خادمنا"]
لماذا HMAC وليس RSA؟
- HMAC توقيع متماثل السر سريع جداً وجيد لروابط جميع الدعوات.
- RSA/PSS يحتاج زوج مفاتيح ونشر عام — ضروري فقط لو فحصت جهات خارجية موثوقة.
- لا نحتاج لتوثيق عام خارجي هنا، فالخادم السري هو سؤال الجهة الوحيدة للمستخدم.
إدارة الأسرار
يُخزَّن السر في متغير بيئة SIGNING_SECRET ويتاح للخادم فقط. أيَّ نشر ثانٍ بقاعدة نسخة يحتاج نفس السر، وإلا فكروابط قديمة فساداً.
تمرين تطبيقي: ابدأ من نص exp: بعد وصول خبرة من قاعدة البيانات أعد بناء دالة تحقق بمساواة نصية (==) ثم استبدلها بـ timingSafeEqual مع مراعاة اختلاف الأطوال.
أخطاء شائعة يجب تفاديها
- مضاعفة التوقيع في query بالكامل دون استخدام — يضيع فرصة الأمان.
- تخزين SECRET في الكود الثابت أو في repo — كشف مستمر.
- مقارنة توقيع بـ === عادية فيضيف نافذة زمنية توقيعية.
معجم مصطلحات الدرس
- HMAC
- رمز تحقق مبنياً على دالة تجزئة وسر مشترك.
- base64url
- تمثيل بايتات آمن في الروابط.
- timingSafeEqual
- مقارنة متساوية الأمد لتقليل الاستخراج الزمني.
مراجعة وتمرين تثبيت المهارة
اختبار سريع: اشرح بعبارتك معنى «تصميم الرمز Secured والتوقيع HMAC»، ثم بيّن أين ستستخدمه داخل نظام تسجيل حضور دعوات مناسبة عبر رمز QR، وما الخطأ الذي يجب اختباره قبل الاعتماد على الحل.
تحدٍّ إضافي: غيّر شرطًا واحدًا في التطبيق، وتوقع النتيجة، ثم نفّذ الاختبار وفسّر الاختلاف.
الدرس التالي: توليد صورة QR من قاعدة الدعوة. من الأفضل إنهاء التجربة الحالية قبل متابعة الدرس التالي.
