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

صُمّمت الواجهة بافتراض أن كل طلب له تأثير مالي مباشر وقد يصل إلى بيانات اعتماد خوادم حساسة. لذلك فإن المتطلبات الأمنية تتجاوز كثيراً المعايير المعتادة في REST.

الضوابط المطبَّقة

• HMAC-SHA256: كل طلب موقّع بـ HMAC-SHA256 على الطريقة، المسار، الطابع الزمني، الـ Nonce، وتجزئة الجسم. التحقق بزمن ثابت (hash_equals).
• AES-256-GCM: يُحفظ السر فقط كنص مُشفّر بـ AES-256-GCM (libsodium). المفتاح الرئيسي خارج قاعدة البيانات في /etc/kh-reseller-api/master.key.v{N}.
• Replay protection: نافذة طابع زمني ±300 ثانية، ذاكرة Nonce 600 ثانية. لا يمكن إعادة إرسال طلب موقّع بنجاح.
• Scope-based authorization: قائمة نطاقات صريحة لكل مفتاح API. يجب تفعيل النطاقات الكتابية والحساسة صراحةً.
• IP whitelist (optional): قائمة بيضاء لعناوين IP اختيارية لكل مفتاح API (تدوين CIDR، IPv4 وIPv6).
• Rate limit: متعدد الطبقات: لكل مفتاح API (دقيقة + يوم) ولكل عنوان IP (دقيقة). دلو رموز مع تسامح الدفعات.
• Idempotency: تتطلب الطلبات وإجراءات الخدمة التدميرية ترويسة Idempotency-Key. حماية لمدة 24 ساعة من إعادة محاولات الشبكة.
• Tenant isolation: كل استعلام في قاعدة البيانات يُرشَّح بصرامة على معرّف حسابك. الوصول بين المستأجرين مستحيل بحكم البناء.
• Tamper-evident audit log: يُسجَّل كل طلب في سجل التدقيق بتجزئة سلسلية (chain_hash[n] = sha256(chain_hash[n-1] || row_n)). أي عبث رجعي يُكتشَف عبر كسر التجزئة.
• Credentials.read alerting: كل استدعاء credentials.read يُنتج إدخال تدقيق مخصصاً مع بريد تأكيد اختياري إلى مالك الحساب.
• SSRF-guarded webhooks: يُتحقَّق من عناوين Webhook قبل التخزين: HTTPS حصراً، ويجب أن يُرجِع تحليل DNS عناوين IP عامة فقط (لا RFC1918، لا link-local).

أفضل الممارسات لدى الموزّع

• احفظ السر في مدير أسرار (HashiCorp Vault، AWS Secrets Manager، Doppler، 1Password)، وليس في الشيفرة أو مستودع Git.
• دوّر السر بانتظام (سنوياً على الأقل أو بعد تغيّر الموظفين). تدوير بنقرة واحدة في البوابة، ويُلغى السر القديم فوراً.
• مفتاح API مخصص لكل حالة استخدام بأقل نطاق ممكن (للقراءة فقط إن أمكن). بلا مفاتيح "وضع الإله".
• إن كانت تكاملاتك تعمل من عناوين IP ثابتة (سحابة، بوابة قفز): فعّل قائمة بيضاء لعناوين IP.
• ولّد Idempotency-Key على الخادم واحفظه؛ ولا تولّده من جديد عند كل إعادة محاولة. التوصية: UUIDv4 لكل طلبية منطقية.
• عيّن Webhook على عنوانك الخاص، وراقب على الأقل order.created وcredentials.read كتدفق أحداث.

الإفصاح الأمني

يرجى الإبلاغ عن الثغرات الأمنية بسرية إلى security@kernelhost.com. مفتاح PGP عند الطلب. استجابة مضمونة خلال 24 ساعة. برنامج bug-bounty قيد التحضير.