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

المرجع

السجل القابل للتحقق

تثبت التواقيع أن الإعدادات صادرة عن NanoFlags. ويذهب السجل القابل للتحقق أبعد من ذلك: كل مراجعة نُشرت تُسجَّل في سجلّ علني لا يقبل إلا الإضافة، تتحقق منه حزم SDK لديك وبيئة CI الخاصة بك، فلا يمكن تقديم إعدادات لبعض العملاء دون أن تظهر للجميع. وإذا فعّلت التوقيع المشترك، فلن يصل شيء إلى مستخدميك دون توقيعك أنت.

ما الذي يقدّمه

  • تاريخ واحد للجميع. تُضاف كل مراجعة منشورة في البيئة إلى شجرة لا تقبل إلا النمو، ويرى كل عميل وكل مدقّق التاريخ نفسه. وعرض إعدادات على عميل دون غيره يتطلب شجرة ثانية غير متسقة، وهو ما يكتشفه العملاء.
  • إثبات لا ثقة. مع verifyLog: true لا تطبّق حزمة JavaScript SDK أي إعدادات جديدة إلا بعد التحقق من وجودها في السجل بايتًا ببايت، تحت رأس شجرة موقّع من NanoFlags، وأن الشجرة الجديدة امتداد لما رأته من قبل.
  • مفتاحك وقواعدك (اختياري). مع التوقيع المشترك، يحتاج النشر إلى البيئة أيضًا توقيعًا بمفتاحك أنت من CI. وترفض حزم SDK المضبوطة بمفتاحك العام أي إعدادات بدونه، حتى لو كانت موقّعة توقيعًا صحيحًا من NanoFlags.
  • سجل تدقيق تشغّله بنفسك. ينزّل nanoflags log verify التاريخ كاملًا ويتحقق منه على جهازك، وnanoflags log monitor مهمة واحدة لـ CI تفشل إذا تفرّع التاريخ أو تقلّص أو أُعيدت كتابته.

كيف يعمل السجل

لكل بيئة سجلّها الخاص: شجرة ميركل تُحسب بصماتها كما في RFC 6962 / RFC 9162. الورقة نص قصير يصف مراجعة منشورة واحدة، والعقدة بصمة ابنيها. تصبح كل مراجعة موزَّعة ورقة فور توزيعها، وتوقّع NanoFlags رأس الشجرة — حجمها وبصمة جذرها ووقتها — بمفتاح Ed25519 نفسه الذي يوقّع الحزم (GET /v1/keys).

السطرالمحتوى
1nanoflags-log-v1
2–4معرّف البيئة ورقم المراجعة والمجموع الاختباري — القيم نفسها التي يغطيها توقيع الحزمة
5–6بصمة SHA-256 لبايتات الحزمة كما تُقدَّم لمفاتيح الخادم، ولتلك المقدَّمة لمفاتيح المتصفح
7وقت النشر (بالمللي ثانية منذ epoch)
8–10نوع المراجعة (publish أو kill)، والنمط (standard أو cosigned أو emergency)، ومعرّف مفتاح التوقيع المشترك أو -
  • إضافة فقط في قاعدة البيانات. يمكن إدراج الأوراق والرؤوس الموقّعة، ولا يمكن تعديلها أو حذفها أبدًا: ترفض المشغّلات UPDATE وDELETE وTRUNCATE، ولا يملك أي دور عميل صلاحية على الجداول. ويبقى التاريخ محفوظًا حتى بعد حذف البيئة (فهو يحوي بصمات وأرقامًا وأوقاتًا، لا إعداداتك).
  • يُفحص قبل توقيعه. تحسب قاعدة البيانات بصمات الأوراق والجذور والإثباتات، ويطابقها الناشر مع البايتات التي وقّعها قبل أن يوقّع الرأس، ولا تقبل قاعدة البيانات رأسًا إلا للجذر الذي حسبته.
  • إعادة التوقيع ظاهرة. إذا أُعيد توقيع مراجعة ببايتات جديدة (مثلًا بعد تغيير قواعد عرض المتصفح)، تصبح ورقة جديدة للمراجعة نفسها وتبقى القديمة.

التحقق في SDK

ts
import { createClient } from "@nanoflags/sdk";

const flags = createClient({
  sdkKey: process.env.NANOFLAGS_SDK_KEY!,
  baseUrl: "https://edge.nanoflags.io",
  verifyLog: true,
});
flags.on("error", (e) => console.warn(e.code, e.message)); // "log" when an update cannot be verified
  • يصل الدليل (الورقة وإثبات الاحتواء والرأس الموقّع) مع كل حزمة في الترويسة X-NanoFlags-Log. أما المراجعات المدفوعة فتصل قبل كتابة إدخالها، فتجلبه SDK من GET /v1/log/proof مع محاولات قصيرة متكررة.
  • تتذكر SDK أحدث رأس شجرة تحققت منه (في مخزنها الدائم أيضًا)، وتطابق كل رأس جديد معه بإثبات اتساق (GET /v1/log/consistency، طلب واحد لكل رأس جديد).
  • الإعدادات التي تفشل في أي فحص لا تُطبَّق: تبقى الإعدادات الحالية، ويُطلق error بالرمز log، وتعيد SDK المحاولة مع تباعد تدريجي. ولا تتعطل أبدًا.
  • يستلزم verifyLog التحقق من التواقيع مع require: true.

التدقيق بأداة سطر الأوامر

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

sh
NANOFLAGS_SDK_KEY=nf_srv_… npx @nanoflags/cli log verify --env <environment id> --state nanoflags-log.json

وفي مهمة CI مجدولة، يكتفي log monitor بالتحقق من أن الرأس الموقّع الحالي امتداد للرأس المحفوظ في ملف الحالة (احتفظ بالملف بين التشغيلات، في ذاكرة CI المؤقتة مثلًا). ويخرج بالرمز 1 إذا تفرّع السجل أو تقلّص أو أُعيدت كتابته:

sh
npx @nanoflags/cli log monitor --state .cache/nanoflags-log.json

يتحقق الأمران من تواقيع الرؤوس بالمفاتيح المضمّنة في الأداة للخدمة المستضافة، ويمكنك تمرير --public-keys keys.json لاستخدام نسختك المثبّتة. ويعرض log verify أيضًا المراجعات ذات التوقيع المشترك والمراجعات الطارئة وأرقام المراجعات التي لا إدخال لها (المنشورة قبل تفعيل السجل).

التوقيع المشترك من العميل

متاح في خطتي Scale وEnterprise. ما دام للبيئة مفتاح توقيع مشترك نشط، يجب أن يحمل كل نشر إليها توقيعك على السلاسل القانونية نفسها التي توقّعها NanoFlags (عرض الخادم وعرض المتصفح للمراجعة).

  • 1. أنشئ مفتاحًا في مكان آمن: npx @nanoflags/cli keygen --out ci-cosign.jwk --kid ci-2026. احفظ المفتاح الخاص في مخزن الأسرار لدى CI، ويطبع الأمر المفتاح العام.
  • 2. سجّل المفتاح العام (مالك أو مسؤول): لوحة التحكم ← الإعدادات ← البيئات ← الأمان ← التوقيع المشترك من العميل. تُسجَّل عمليات التسجيل والإيقاف في سجل النشاط، وتسجيل أول مفتاح يفعّل التوقيع المشترك.
  • 3. وقّع وانشر من CI بمفتاح مسؤول للبيئة:
sh
export NANOFLAGS_KEY=$NANOFLAGS_ADMIN_KEY
npx @nanoflags/cli sign --key ci-cosign.jwk --expect reviewed-bundle.json --out cosign.json
npx @nanoflags/cli publish --expected-revision 41 --cosign cosign.json

ينزّل sign المسودة ويحسب على جهازك البايتات نفسها التي سيوقّعها الناشر (فلا يوقّع بصمة سُلّمت إليه)، ويتأكد أن مفتاحك هو المسجّل بمعرّفه، ثم يوقّع. تحقّق مما توقّعه: المسودة تأتي من NanoFlags، والتوقيع المشترك موجود أصلًا للحالة التي لا يمكن فيها الوثوق بـ NanoFlags. مرّر --expect <bundle.json> (ملفًا فيه flags وsegments التي راجعها مسارك، من إعداداتك المكتوبة كشيفرة مثلًا أو من ملف --bundle-out لتشغيل مُراجَع) أو --expect-checksum <md5>: فيرفض sign التوقيع (رمز الخروج 1 دون كتابة أي ملف) إذا اختلفت المسودة، ويطبع الفروق علمًا علمًا. وتتحقق الحافة من التوقيعين قبل نشر أي شيء، وترفض قاعدة البيانات أي مراجعة للبيئة بلا توقيع مشترك، ويتحقق الناشر من التوقيعين مجددًا قبل توزيع أي مراجعة أو تسجيلها.

  • 4. اضبط حزم SDK بالمفتاح العام: coSignerKeys: [{ kty: "OKP", crv: "Ed25519", x: "…", kid: "ci-2026" }]. فترفض بعدها أي إعدادات بلا توقيع مشترك صحيح (الرمز cosign) وتحتفظ بما لديها.
  • التدوير: سجّل المفتاح الجديد، وانقل CI وحزم SDK إليه، ثم أوقف المفتاح القديم. وإيقاف آخر مفتاح يلغي اشتراط التوقيع المشترك.
نشر بيئة ذات توقيع مشترك
لا تحمل لوحة التحكم مفتاحك، فلا يمكنها نشر بيئة ذات توقيع مشترك (وتوضح ذلك). انشر من CI كما سبق. أما العمل الذي يحتاج إلى موافقة، كمسودة فيها تعديلات اقترحها وكيل ذكاء اصطناعي، فيُنشر عبر تغييره: بعد أن يوافق على التغيير في لوحة التحكم مالك أو مسؤول لم يكتبه ولم يعدّل مسودته، وقّع المسودة وأضف --change <change id> إلى publish. ولا يمكن الجمع بعد بين التوقيع المشترك واشتراط الموافقة في البيئة نفسها.

مفتاح الإيقاف والحالات الطارئة

يجب أن يبقى مفتاح الإيقاف عاملًا حين يتعذّر الوصول إلى مفتاح CI. لذلك تُقبل مراجعات مفتاح الإيقاف بتوقيع NanoFlags وحده، ويسجّلها السجل بالنمط emergency ظاهرةً لكل مدقّق. وتقبل حزم SDK المضبوطة بـ coSignerKeys هذه المراجعة فقط إذا كان allowEmergencyWithoutCosign مفعّلًا (وهو الافتراضي) وكانت لا تختلف عن الإعدادات الحالية إلا بأعلام أُوقفت، ومع verifyLog يجب أن يسجّلها السجل حالةً طارئة أيضًا. وأي شيء آخر بلا توقيعك يُرفض. اضبط allowEmergencyWithoutCosign: false لرفض مراجعات مفتاح الإيقاف أيضًا. والعميل الذي يبدأ دون إعدادات حالية لا يستطيع المقارنة، فلا يقبل مراجعة طارئة، وكذلك العميل الذي فاتته المراجعة ذات التوقيع المشترك السابقة لها مباشرة (إذ لا تقدّم الحافة إلا أحدث مراجعة). ويحتفظ كلاهما بما لديه (أو يبقى بلا إعدادات) حتى النشر التالي ذي التوقيع المشترك.

نقاط الوصول والصيغ

نقطة الوصولالإجابة
GET /v1/log/head{ environmentId, head: { size, root, timestamp, kid, signature } } — أحدث رأس شجرة موقّع
GET /v1/log/proof?revision=<n>{ index, leaf, proof, head } — احتواء أحدث ورقة للمراجعة في أحدث رأس
GET /v1/log/consistency?first=<m>&second=<n>{ first, second, proof, head } — إثبات اتساق وفق RFC 9162
GET /v1/log/entries?start=&limit=نصوص الأوراق، 1000 كحد أقصى في الطلب
  • المصادقة: Authorization: Bearer <أي مفتاح للبيئة>. ويُحدّ المعدل لكل مفتاح (ولكل شبكة عميل لمفاتيح المتصفح)، وبعده 429 مع Retry-After.
  • البصمات: بصمة الورقة = SHA-256(0x00 ‖ نص الورقة بترميز UTF-8)، وبصمة العقدة = SHA-256(0x01 ‖ اليسار ‖ اليمين)، والإثباتات قوائم بصمات ست عشرية بأحرف صغيرة من الأسفل إلى الأعلى.
  • نص الرأس الموقّع: nanoflags-log-head-v1\n<environment id>\n<size>\n<root hex>\n<timestamp ms>، بتوقيع Ed25519 بترميز base64url، ومعرّف المفتاح kid من /v1/keys.
  • تضيف /v1/bundle الترويسة X-NanoFlags-Log (JSON بترميز base64url لـ { index, leaf, proof, head })، وفي البيئات ذات التوقيع المشترك X-NanoFlags-Cosignature وX-NanoFlags-Cosigner-Key-Id للعرض المقدَّم. وتحمل الرسائل الحية cosignature وcosignerKid.

ما الذي يحمي منه، وما لا يحمي منه

السيناريوبدونهمع السجل القابل للتحقق (والتوقيع المشترك)
إعدادات تُقدَّم لبعض العملاء فقط (تلاعب موجّه)لا يُكتشف إن كان التوقيع صحيحًايُكتشف: يجب أن تكون في السجل الواحد الذي يفحصه كل عميل ومدقّق
إعادة كتابة التاريخ لاحقًالا يُكتشفتكتشفه إثباتات الاتساق (SDK) والمراقبة في CI
إساءة استخدام مفتاح توقيع NanoFlags أو حساب لديهايقبل العملاء الإعداداتيظهر في السجل، ومع التوقيع المشترك ترفضه حزم SDK لديك
مهاجم على الشبكة يغيّر حزمةتُرفض (التوقيع)تُرفض (التوقيع والسجل)
حجب التحديثات (إبقاء عميل على إعدادات قديمة)لا يُكتشفلا يُمنع، لكن المراقبة تعرض الرأس الحالي لتقارن

يثبت السجل ما نُشر، لا أنه ما قصدته: راجع إعداداتك كالمعتاد، ومع التوقيع المشترك قارن البايتات في CI قبل التوقيع.

الحدود والتوفر

  • سجل الشفافية متاح في كل الخطط، والتوقيع المشترك من العميل متاح في Scale وEnterprise.
  • الخيارات verifyLog وcoSignerKeys وallowEmergencyWithoutCosign متاحة في حزمة JavaScript SDK (@nanoflags/sdk). أما بقية الحزم فتتحقق من تواقيع الحزم دون السجل أو التوقيعات المشتركة حتى الآن، فاستخدم nanoflags log monitor في CI معها.
  • المراجعات المنشورة قبل تفعيل السجل لبيئتك ليست فيه.
  • تُقدَّم الإثباتات للسجلات التي لا تتجاوز 65,536 إدخالًا لكل بيئة.
  • حزم جلسات الاختبار لا تُسجَّل.

انظر أيضًا الأمان (المفاتيح وتوقيع الحزم) ومفتاح الإيقاف.