مصادقة HMAC والأمان

قم بتأمين روابط صور OG الموقّعة بـ HMAC باستخدام مصادقة HMAC-SHA256 من FastOG. يغطي هذا الدليل التوقيع والتحقق واستكشاف الأخطاء وإصلاحها لكل طلب، بحيث يمكنك نشر صور Open Graph الديناميكية بسرعة — مع تقييد بالاشتراك، وبدون حد أقصى شهري للعرض (لا حصة عرض شهرية ولا فوترة تجاوز). سجّل للحصول على حساب، واختر خطة Dynamic API، ثم أنشئ مفتاح API وسر HMAC في لوحة التحكم (عروض API المدفوعة نظيفة). وقّع على خادمك مرة واحدة ودمج في دقائق.

🚀 بدء سريع

جديد على توقيع HMAC؟ ابدأ من هنا:

1. دليل البدء السريع — ابدأ العمل في 5 دقائق
2. درس JavaScript — دليل شامل لمطوري Node.js/Next.js
3. جميع دروس الأطر البرمجية — اختر تقنيتك:
   • Next.js App Router
   • Next.js Pages Router
   • React
   • SvelteKit
   • Vue/Nuxt
   • Astro
   • Express
   • Vanilla Node.js
   • JavaScript
   • PHP/Laravel
   • Python
   • Ruby/Rails

📚 فهرس التوثيق

المفاهيم الأساسية

• دليل توقيع HMAC — مرجع كامل يتضمن تفاصيل الخوارزمية والمتطلبات وأمثلة بلغات JavaScript وPHP وPython
• التحقق من HMAC — تفاصيل التنفيذ من جانب الخادم، وميزات الأمان، واستجابات الأخطاء

الدروس التعليمية

• درس JavaScript/Node.js — دليل شامل يغطي:

  • البدء السريع (5 دقائق)
  • Next.js App Router (3 أنماط)
  • Next.js Pages Router
  • خادم Express.js
  • Node.js الأساسي
  • أنماط تكامل الواجهة الأمامية (SSG، SSR، Client-Side)
  • الاختبار وتصحيح الأخطاء
  • الأخطاء الشائعة

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Node.js الأساسي

• PHP/Laravel

• Python

• Ruby/Rails

مرجع سريع

الخوارزمية

method = "GET"
path = "/api/v1/og"
canonicalQuery = every query param EXCEPT `s` (including `key`): array values sorted too; each pair rfc3986Encode(key)=rfc3986Encode(value); pairs sorted lexicographically and joined with "&"

message = method + path + "\n" + canonicalQuery
signature = hex(HMAC-SHA256(message, hmac_secret))

URL: /api/v1/og?title=Hello&key=sk_quick_123abc&s=<signature>

معاملات الاستعلام

رموز الأخطاء

🎯 حالات الاستخدام

مقالات المدونات

أنشئ صور OG ديناميكية لمقالات المدونات:

const ogUrl = generateSignedOgUrl({
    template: "blog",
    title: post.title,
    subtitle: post.excerpt,
    author: post.author.name,
});

// <meta property="og:image" content="{ogUrl}" />

منتجات التجارة الإلكترونية

أنشئ صور OG لصفحات المنتجات:

const ogUrl = generateSignedOgUrl({
    template: "ecommerce",
    title: product.name,
    price: product.price,
    image: product.image,
});

آراء العملاء

أنشئ صور OG لاقتباسات آراء العملاء:

const ogUrl = generateSignedOgUrl({
    template: "testimonial",
    author_name: user.name,
    author_avatar: user.avatarUrl,
    quote: user.bio,
});

🔐 الأمان

أفضل الممارسات

1. خزّن الأسرار بشكل آمن — استخدم متغيرات البيئة أو مدير الأسرار
2. لا تعرّض سر HMAC في كود العميل أبدًا — وقّع على الخادم فقط
3. استخدم HTTPS — يمنع هجمات الوسيط (MITM)
4. بدّل الأسرار دوريًا — خاصة إذا تم اختراقها
5. راقب التوقيعات الفاشلة — قد تشير حالات الفشل المتكررة إلى هجمات
6. عزل لكل مستخدم — لكل مفتاح API سر HMAC خاص به

الحصول على سر HMAC الخاص بك

1. انتقل إلى لوحة التحكم ← مفاتيح API
2. أنشئ مفتاح API جديدًا
3. انسخ سر HMAC (يُعرض مرة واحدة فقط!)
4. خزّنه في متغيرات البيئة

# .env
FASTOG_HMAC_SECRET=<your-64-char-hex-secret>

🧪 الاختبار

توليد رابط الاختبار

# Node.js
node -e "
const crypto = require('crypto');
const enc = (s) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());
const all = { title: 'Test', key: 'sk_quick_123abc' };
const pairs = [];
for (const [k, v] of Object.entries(all)) for (const vv of Array.isArray(v) ? v : [v]) pairs.push(enc(k) + '=' + enc(vv));
pairs.sort();
const canonical = pairs.join('&');
const sig = crypto.createHmac('sha256', 'YOUR_HMAC_SECRET').update('GET/api/v1/og\n' + canonical).digest('hex');
console.log('https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=' + sig);
"

الاختبار باستخدام curl

curl "https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=<signature>"

الاستجابات المتوقعة

• ✅ توقيع صالح → يتم إرجاع صورة OG (أو 422 إذا كانت معاملات القالب غير صالحة)
• ❌ توقيع غير صالح → {"code": "invalid_signature"}
• ❌ معاملات مفقودة → {"code": "missing_signature"}

🛠 استكشاف الأخطاء وإصلاحها

التوقيع غير متطابق

1. تحقق من استخدامك لسر HMAC الصحيح (افحص مفتاح API في لوحة التحكم)
2. تحقق من الاستعلام الأساسي: كل معاملات الاستعلام باستثناء s (بما في ذلك key)، القيم مشفرة وفقًا لـ rfc3986، المفاتيح مرتبة أبجديًا
3. تحقق من أن التوقيع بصيغة hex صغيرة (64 حرفًا)

📖 موارد إضافية

• مرجع API — توثيق API الكامل
• أفضل ممارسات الأمان — دليل أمان مفصّل
• قاعدة المعرفة — تفاصيل التنفيذ التقني

❓ الأسئلة الشائعة

س: لماذا نستخدم معاملات الاستعلام بدلاً من الترويسات؟
ج: يتم جلب صور OG بواسطة برامج زحف الشبكات الاجتماعية (لينكد إن، تويتر، فيسبوك) التي لا ترسل ترويسات مخصصة. يجب أن يكون التوقيع في عنوان URL.

س: هل يمكنني استخدام نفس التوقيع لعدة طلبات؟
ج: نعم. يتم حساب التوقيع من الاستعلام المحدد (باستثناء s)، لذا يظل عنوان URL الموقّع صالحًا طالما لم تتغير المعاملات. غيّر أي معامل (بما في ذلك key) ويجب عليك إعادة التوقيع.

س: هل أحتاج إلى توقيع الطلبات لجميع القوالب؟
ج: نعم. جميع الطلبات إلى /api/v1/og تتطلب توقيعات HMAC.

س: ماذا يحدث إذا تم اختراق سر HMAC الخاص بي؟
ج: قم بإلغاء مفتاح API في لوحة التحكم وأنشئ مفتاحًا جديدًا. لكل مفتاح API سر HMAC خاص به.

س: هل يمكنني تعطيل التحقق من HMAC للخدمات الداخلية؟
ج: تواصل مع الدعم للحصول على حلول مخصصة. التحقق من HMAC إلزامي لجميع نقاط نهاية API العامة.

🆘 الدعم

هل تحتاج إلى مساعدة؟

• راجع JavaScript Tutorial للحصول على أمثلة كاملة للكود
• اطّلع على HMAC Signature Guide لتفاصيل الخوارزمية
• تواصل مع الدعم عبر [email protected]

ذات صلة

• التوثيق — جميع أدلة ومراجع FastOG
• مختبِر صور OG المجاني — معاينة بدون حساب
• دليل البدء السريع — ابدأ العمل في 5 دقائق
• دليل توقيع HMAC — تفاصيل الخوارزمية
• التحقق من HMAC — التحقق من جانب الخادم