انتقل إلى المحتوى
NanoFlags
ابدأ مجانًا

كل المقالات

المدونة والأدلة

حزم الأعلام الموقّعة: لماذا وكيف

لماذا توقّع NanoFlags كل إعداد منشور بخوارزمية Ed25519، وما الذي يغطيه التوقيع بالضبط، وكيف تتحقق منه حِزم SDK افتراضيًا، وكيف تُدوَّر مفاتيح التوقيع دون أن تتعطل العملاء، وما الذي لا يثبته التوقيع.

فريق هندسة NanoFlagsنُشر في 3 دقائق قراءة

علم الميزة (feature flag) مفتاح يُتحكَّم فيه عن بُعد داخل تطبيقك. ومن يستطيع تغيير الإعداد الذي يحمّله الـ SDK يستطيع تغيير ما يراه مستخدموك، دون نشر للكود ودون مراجعة. لذا يستحق سؤال «هل هذا فعلًا الإعداد الذي نُشر؟» إجابة تشفيرية، لا أملًا في أن يحسن كل مخزن مؤقت ووسيط على الطريق التصرّف.

ما الذي يوقَّع

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

يغطي التوقيع (64 بايت بترميز base64url) بايتات UTF-8 لنص قانوني قصير:

النص القانوني
nanoflags-bundle-v1
<environment id>
<revision>
<checksum>
<sha256 hex of the bundle JSON text, exactly as sent>

ربط معرّف البيئة ورقم النسخة داخل الرسالة يعني أنه لا يمكن إعادة تقديم حزمة صالحة لبيئة على أنها لبيئة أخرى، ولا إعادة وسمها برقم نسخة مختلف. وحساب البصمة لنص الحزمة كما أُرسل تمامًا يتجنّب كل مزالق إعادة تسلسل JSON: لا يحتاج العميل أبدًا إلى إعادة إنتاج تنسيقنا، بل يحسب بصمة البايتات التي استلمها.

لماذا Ed25519

  • مفاتيح وتواقيع صغيرة (مفتاح عام 32 بايت وتوقيع 64 بايت)، فيتّسع المفتاح العام لإصدار SDK ولترويسة HTTP.
  • تواقيع حتمية: النص نفسه بالمفتاح نفسه يعطي دائمًا التوقيع نفسه. لذا يستطيع مساران في خدمة النشر (الدفع المباشر وصندوق الصادر الدائم) توقيع النسخة نفسها باستقلال وإنتاج كائنات متطابقة.
  • متاحة أصلًا في WebCrypto على Node.js 20+‎ والمتصفحات الحالية وCloudflare Workers وDeno وBun، فيتحقق SDK جافاسكريبت دون تضمين مكتبة تشفير.

التحقق مفعَّل افتراضيًا

بدءًا من SDK جافاسكريبت 0.4.0، وفي حِزم Python وGo منذ 0.1.0، يتحقق الـ SDK من كل حزمة عندما يقرأ من الحافة الرسمية (https://edge.nanoflags.io) ويرفض الحزم غير الموقّعة هناك. تأتي الحِزم مزوّدة بالمفاتيح العامة للإنتاج، وتحمّل GET /v1/keys مرة واحدة عندما تذكر حزمةٌ معرّف مفتاح لا تعرفه.

  • الحزمة ذات التوقيع الخاطئ تُرفض، وتبقى الحزمة السابقة قيد الاستخدام، ويُطلق الـ SDK حدث error بالقيمة signature.
  • لا تُطبَّق حزمة يتعذّر التحقق منها بصمت. وعلى بيئة تشغيل لا تدعم Ed25519 في WebCrypto يجب أن تختار التعطيل صراحةً بـ verify: false.
  • إن كنت تجلب الحزم عبر وسيطك أو مخزنك المؤقت الخاص، فثبّت المفاتيح بنفسك واشترط التوقيع:
مفاتيح مثبّتة
const flags = createClient({
  sdkKey, baseUrl,
  verify: {
    publicKeys: [{ kty: "OKP", crv: "Ed25519", x: "wQu1EsaE-yTjqpUbibGyBrajy3IiRb7LyaiqeYRxG4U", kid: "k1" }],
    require: true,
  },
});

ويستطيع أي عميل آخر التحقق أيضًا. هذا هو الفحص كاملًا بلغة Node.js الصرفة:

verify.mjs (Node 20+)
import { createHash, createPublicKey, verify } from "node:crypto";

const base = "https://edge.nanoflags.io";
const res = await fetch(`${base}/v1/bundle`, { headers: { Authorization: `Bearer ${process.env.NANOFLAGS_SDK_KEY}` } });
const text = await res.text(); // keep the raw text: the signature covers the bundle bytes exactly as sent

if (res.headers.get("x-nanoflags-signed") !== "true") throw new Error("unsigned bundle");
const { revision, checksum } = JSON.parse(text);
const marker = '"bundle":';
const bundleText = text.slice(text.indexOf(marker) + marker.length, text.lastIndexOf("}"));
const message = ["nanoflags-bundle-v1", res.headers.get("x-nanoflags-environment-id"), revision, checksum,
  createHash("sha256").update(bundleText, "utf8").digest("hex")].join("\n");

const { keys } = await (await fetch(`${base}/v1/keys`)).json(); // or pin the key in your build
const jwk = keys.find((k) => k.kid === res.headers.get("x-nanoflags-key-id"));
const ok = verify(null, Buffer.from(message, "utf8"),
  createPublicKey({ key: { kty: jwk.kty, crv: jwk.crv, x: jwk.x }, format: "jwk" }),
  Buffer.from(res.headers.get("x-nanoflags-signature"), "base64url"));

تدوير مفتاح التوقيع

مفتاح توقيع لا يمكن تغييره عبءٌ لا ميزة. لذا تسرد GET /v1/keys كل مفتاح عام مع معرّف kid وحالة status (‏active أو retiring)، وكل حزمة موقّعة تذكر معرّف المفتاح الذي وُقّعت به:

sh
$ curl -s https://edge.nanoflags.io/v1/keys
{"keys":[{"kty":"OKP","crv":"Ed25519","x":"wQu1EsaE-yTjqpUbibGyBrajy3IiRb7LyaiqeYRxG4U","kid":"k1","alg":"EdDSA","use":"sig","status":"active"}]}

يجري التدوير بترتيب لا يترك عميلًا أبدًا يحمل توقيعًا لا يستطيع التحقق منه:

  1. توليد زوج مفاتيح جديد ونشر المفتاح العام الجديد بجانب الحالي، وكلاهما active. ثم الانتظار خمس دقائق على الأقل، وهي مدة التخزين المؤقت لـ /v1/keys.
  2. تحويل خدمة النشر إلى معرّف المفتاح الجديد ومفتاحه الخاص في عملية نشر واحدة. وترفض خدمة النشر التوقيع إذا لم يطابق معرّفُ المفتاح الخاص المعرّفَ المضبوط، فلا يمكن لتدوير نصف منجز أن ينتج تواقيع تحت معرّف خاطئ.
  3. إعادة توقيع ما يُقدَّم حاليًا، لتحمل النسخة الحالية لكل بيئة معرّف المفتاح الجديد.
  4. وسم المفتاح القديم بـ retiring، وعدم إزالته إلا بعد أطول مدة قد يحتفظ فيها SDK بحزمة مخزّنة موقّعة به (نخطّط افتراضيًا لـ 30 يومًا).

وتواصل الحِزم التي لا تعرف إلا المفتاح القديم العمل طوال الوقت: تصادف معرّفًا مجهولًا فتحمّل /v1/keys مرة واحدة وتقبل المفتاح الجديد منها. وحتى كتابة هذه السطور، k1 هو مفتاح الإنتاج الوحيد ولم يُجرَ أي تدوير في الإنتاج بعد؛ الإجراء منفَّذ ومختبَر، وسنذكر أول تدوير في سجل التغييرات.

ما لا يثبته التوقيع

  • المفاتيح المجلوبة من /v1/keys موثوقة بقدر الحافة التي قدّمتها فقط. فإن كانت الحافة نفسها ضمن نموذج التهديد لديك، فثبّت المفتاح العام في البناء كما في المثال أعلاه.
  • حزم جلسات الاختبار المشتركة غير موقّعة.
  • التوقيع يحمي ما يتدفق من NanoFlags إلى حِزم SDK. أما من يحق له تغيير الإعداد أصلًا فضابط منفصل: الأدوار، والتغييرات المراجَعة، وفحوص السيناريوهات.

العقد الدقيق (الترويسات والنص القانوني ورسائل الاتصال الحي) في مرجع واجهة الحافة، وإدارة المفاتيح في الأمان.

  • security
  • ed25519
  • signing
  • key rotation