سلسلة التوريد — التحقق من إصدار كاظمه
سلسلة التوريد — التحقق من إصدار كاظمه
Section titled “سلسلة التوريد — التحقق من إصدار كاظمه”كاظمه ذاتية الاستضافة. تشغّلها على جهازك أنت، غالبًا مقابل خزنتك الخاصة، ومسموح لها لمس ملفاتك وصدفتك ومستودعك. والإصدار الذي لا تستطيع التحقق منه إصدار تأخذه على الثقة، و«ثق بي» هو الشيء الوحيد الذي ليس هذا المشروع مستعدًا لطلبه.
لذلك كل قطعة إصدار موقَّعة، وتحمل إثبات منشأ البناء (build provenance)، وتُشحن معها SBOM. هذه الصفحة هي كيف تتحقق من الثلاثة. ولا شيء من ذلك يتطلب حسابًا ولا مورّدًا ولا خدمة مدفوعة.
ما يحتويه الإصدار
Section titled “ما يحتويه الإصدار”| الملف | ما هو |
|---|---|
kazma-<version>-py3-none-any.whl | حزمة wheel |
kazma-<version>.tar.gz | التوزيعة المصدرية |
kazma-<version>.cdx.json | SBOM بصيغة CycloneDX 1.6 لمجموعة التبعيات المثبّتة |
kazma-<version>-windows-setup.exe | مثبّت ويندوز (من الإصدار الذي يلي 0.21.2)، مبني من أرشيف المصدر أعلاه |
SHA256SUMS | بصمات تحقق (checksums) للملفات أعلاه |
*.sigstore.json | حزمة Sigstore لكل قطعة — التوقيع |
شهادات إثبات المنشأ ليست ملفات في الإصدار؛ GitHub يخزنها ويجلبها لك
gh attestation verify.
كاظمه ليست على PyPI
Section titled “كاظمه ليست على PyPI”تُوزَّع كاظمه عبر إصدارات Mubder/kazma على GitHub وعبر المستودع نفسه، ولا
شيء غيرهما. وعلى PyPI يحجز المشروع kazma وkazma-core والأسماء التي حولها
بحزم محجوزة: الإصدار 0.0.1 من كل منها، بلا شيفرة، وفيها صفحة فقط تحيل القارئ
إلى إصدارات GitHub. فتثبيت إحداها لا يثبّت شيئًا، ولا يستطيع أحد غير المشروع أن
ينشر تحت الاسم. لا تثبّت أبدًا kazma (أو kazma[...]) بالاسم من PyPI لتحصل
على كاظمه. ثبّت الإضافة من مجلد كاظمه لديك (pip install -e ".[web]"، أو
الإعدادات ← الحزم) وحدّث باستخدام kazma update.
في التثبيت المأخوذ من حزمة wheel لإصدار، يقرأ kazma update أحدث إصدار من
واجهة GitHub البرمجية، وينزّل حزمة wheel الخاصة به من ذلك الإصدار، ولا يثبّتها
إلا إذا طابقت بصمةُ SHA-256 للملف ملفَّ SHA256SUMS في الإصدار، وبصمةَ GitHub
نفسه للملف حين يذكرها، و(منذ 2026-11) إذا صحّ التحقق من حزمة Sigstore الخاصة
بحزمة wheel: موصولة بسلسلة Sigstore، ومدوَّنة في سجلّ شفافيته، وعلى بصمة SHA-256
لحزمة wheel، وتسمّي .github/workflows/release.yml في Mubder/kazma مشغَّلًا من
main أو من وسم v* (kazma_cli/release_signature.py). فبصمات التحقق موجودة في
الإصدار نفسه الذي فيه حزمة wheel، فمن استطاع تغيير ملفاته استطاع تغييرها هي أيضًا؛
أما التوقيع فلا يمكن صنعه دون تشغيل سير عمل الإصدار هنا. والإصدار من 0.21.2 فما
بعده إن لم تكن معه حزمة توقيع لا يُثبَّت. أما v0.21.1 وما قبله فيُتحقق منها ببصمة
SHA-256 وحدها، ويقول الأمر ذلك؛ وحزمة التوقيع التي يحملها أحدها مع ذلك يُتحقق منها،
ولا تُتجاهل أبدًا. وإلا توقف وذكر صفحة الإصدار. ويأتي جذر الثقة في Sigstore من
مستودع TUF الخاص به، ويُقرأ عند كل فحص؛ ودون الشبكة تُستخدم النسخة التي على الجهاز،
ولا يُتخطى الفحص أبدًا. وتحمل حزمة wheel أيضًا الإصدارات التي اختُبر بها الإصدار
(kazma_cli/locked_versions.txt، أي uv.lock الذي صدّره سير عمل الإصدار قبل
البناء)، فيشملها التوقيع نفسه؛ ويثبّت التحديث تلك الإصدارات بعينها. ويقرأ فحص
التحديثات في الإعدادات الإصدار نفسه. حتى
2026-09-30 كان كلاهما يسأل PyPI، ثم كان kazma update يطلب من pip ترقية kazma
بالاسم.
يجب أن يُنشر الإصدار القادم عبر .github/workflows/release.yml
(Actions ← Release ← Run workflow، من main). فهذا السير هو الذي يوقّع الملفات
ويرفق حزم .sigstore.json؛ والإصدار الذي يُبنى ويُرفع يدويًا لا حزم له، ومن 0.21.2
فما بعده يرفضه kazma update في كل تثبيت من حزمة wheel. وقد وقّع سير العمل
v0.11.0؛ أما v0.12.0 إلى v0.21.1 فنُشرت يدويًا دون حزم توقيع، ولهذا يبدأ الاشتراط
بعدها (release_signature.SIGNED_FROM). وv0.21.2 (2026-11-12) أول إصدار ينشره سير العمل
منذ ذلك الحين، وحزمته تجتاز الفحوص أدناه.
كيف تُحجز الأسماء
Section titled “كيف تُحجز الأسماء”الأسماء هي kazma وkazma-cli وkazma-core وkazma-gateway وkazma-memory
(المتقاعد) وkazma-skills وkazma-tui وkazma-ui (يبني الحزم المحجوزة
scripts/pypi_reserve.py). ونُشرت الثمانية كلها في 2026-10-01: الإصدار 0.0.1 من
كلٍّ منها، بحزمة wheel وأرشيف مصدر. ورفعها سير العمل .github/workflows/pypi-reserve.yml
عبر النشر الموثوق (Trusted Publishing) في PyPI، فلا يوجد أي توكن لـPyPI في أي
مكان. ولا يعمل إلا يدويًا (Actions ← Reserve PyPI names)، ودون خانة «publish»
يكتفي ببناء الحزم وفحصها.
ولا يقبل PyPI أول رفع لاسم إلا من ناشر مسجَّل له، ثم يبقى الناشر مع المشروع. ولحجز
اسم آخر، أضفه إلى قائمة السكربت (يُبقي الفحص في tests/test_no_pypi_kazma.py تلك
القائمة مطابقة لأسماء حزم كاظمه)، ثم سجّله في pypi.org، من Account ← Publishing ←
Add a new pending publisher ← GitHub، بما يلي:
| الحقل | القيمة |
|---|---|
| PyPI Project Name | الاسم (kazma، ثم kazma-cli، …) |
| Owner | Mubder |
| Repository name | kazma |
| Workflow name | pypi-reserve.yml |
| Environment name | pypi- والاسم (pypi-kazma، ثم pypi-kazma-cli، …) |
ولكل اسم بيئته الخاصة لأن PyPI لا يُبقي الإعداد الواحد منتظرًا إلا لمشروع جديد واحد في الوقت نفسه. فإن تشاركت الأسماء البيئة نفسها قبل الأول ورفض الباقي: “A pending trusted publisher matching this configuration has already been registered for a different project name”.
ثم شغّل سير العمل مع تحديد «publish» وكتابة الاسم الجديد في خانة «names». يُرفع كل اسم في مهمة خاصة به، تحت بيئته الخاصة، فإن غاب ناشر اسمٍ ما أو لم يطابق فشل وحده (“invalid-publisher”)، ويمكن إعادة التشغيل لذلك الاسم وحده. ولا يحتفظ الحساب بأكثر من ثلاثة ناشرين منتظرين في وقت واحد، ولهذا رُفعت الأسماء الثمانية الأولى على أربع دفعات.
1. إثبات المنشأ — هل بُني هذا من هذا المستودع؟
Section titled “1. إثبات المنشأ — هل بُني هذا من هذا المستودع؟”هذا هو الفحص الأهم، وهو أمر واحد:
gh attestation verify kazma-0.21.2-py3-none-any.whl --repo Mubder/kazmaوالنجاح يعني أن سجلّ شفافية GitHub يقرّ بأن الملف أنتجه سير عمل Release في
Mubder/kazma، من إيداع محدد، في تشغيلة يمكنك الذهاب إليها وقراءتها. والملف الذي
أعاد أحدهم بناءه أو رقّعه أو أدخله يفشل هنا — فلا يمكن إعادة الشهادة له دون صلاحية
كتابة على هذا المستودع.
2. التوقيع — Sigstore بلا مفاتيح
Section titled “2. التوقيع — Sigstore بلا مفاتيح”التوقيع بلا مفاتيح (keyless): لا مفتاح خاص يحتفظ به المشرف، فلا مفتاح يتسرب أو يُدار أو يُفقد. والهوية المشهَد لها هي سير عمل GitHub Actions نفسه، والشهادة مدوَّنة في سجلّ شفافية Sigstore العام.
pip install sigstore
python -m sigstore verify github \ --repository Mubder/kazma \ --bundle kazma-0.21.2-py3-none-any.whl.sigstore.json \ kazma-0.21.2-py3-none-any.whlوالصيغة الصريحة، إن أردت تثبيت الهوية الدقيقة بدل ترك الأمر الفرعي github
يبنيها:
python -m sigstore verify identity \ --cert-identity "https://github.com/Mubder/kazma/.github/workflows/release.yml@refs/heads/main" \ --cert-oidc-issuer "https://token.actions.githubusercontent.com" \ --bundle kazma-0.21.2-py3-none-any.whl.sigstore.json \ kazma-0.21.2-py3-none-any.whlاللاحقة @refs/... هي مرجع git الذي شُغّل منه سير العمل. وسير عمل الإصدار يُشغَّل
يدويًا من main، فتقول حزمه @refs/heads/main (وهذا ما تقوله حزم v0.21.2، كما قالته حزم v0.11.0)؛ أما
التشغيل من وسم فسيقول @refs/tags/v.... راجع التشغيلة إن لم تكن متأكدًا أيها ينطبق.
3. بصمات التحقق
Section titled “3. بصمات التحقق”sha256sum -c SHA256SUMSأضعف الثلاثة وهي وحدها — إذ يمكن استبدال ملف البصمات مع القطع. ويستحق التشغيل
لأن SHA256SUMS موقَّع أيضًا، فالتحقق من حزمة Sigstore الخاصة به أولًا يجعل
البصمات ذات معنى.
4. الـ SBOM — ما فيه فعلًا
Section titled “4. الـ SBOM — ما فيه فعلًا”kazma-<version>.cdx.json بصيغة CycloneDX 1.6، مولَّد من uv.lock لا من بيئة
آلة البناء. وهذا التمييز مهم: فهو يصف المجموعة المثبّتة الدقيقة التي يثبّتها لك
uv sync، لا ما صادف أن حلّه مشغّل CI في ذلك اليوم. والمولِّد نفسه إصدار واحد
محدد أيضًا (cyclonedx-bom==8.0.1)، وكذلك كل أداة يشغّلها سير عمل أو سكربت بناء
عبر uvx أو npx: فدون رقم إصدار تشغّل ما يقدّمه السجلّ ذلك اليوم.
أطعمه لما تستخدمه مؤسستك أصلًا. ولنظرة سريعة:
# Component count and licencespython - <<'PY'import jsond = json.load(open("kazma-0.21.2.cdx.json", encoding="utf-8"))comps = d.get("components") or []print(f"{len(comps)} components, CycloneDX {d['specVersion']}")PY
# Known vulnerabilities, via any CycloneDX-aware scannergrype sbom:kazma-0.21.2.cdx.jsontrivy sbom kazma-0.21.2.cdx.jsonإعادة بناء الأصول المضمَّنة
Section titled “إعادة بناء الأصول المضمَّنة”ثلاثة أصول من طرف ثالث مُدرجة في المستودع بدل جلبها، لأن الواجهة يجب أن تُصيَّر على جهاز لا طريق له إلى الإنترنت:
- CodeMirror 5 (MIT) —
kazma-ui/kazma_ui/static/vendor/codemirror/. أعِد البناء بـpython scripts/vendor_codemirror.py؛ والنسخة المثبّتة تعيش في ذلك السكربت وفي ملفVERSIONبجوار الحزمة. - عميل LiveKit للمتصفح (
livekit-client2.23.0، Apache-2.0) —kazma-ui/kazma_ui/static/vendor/livekit/، للصوت المباشر ثنائي الاتجاه. أعِد البناء بـpython scripts/vendor_livekit.py، الذي يطابق الأرشيف مع بصمة السلامة (integrity) التي نشرها npm؛ والإصدار والمصدر وبصمة السلامة وبصمة SHA-256 لكل ملف موجودة فيvendored.jsonبجواره. وكان يُحمَّل من شبكة توصيل محتوى (CDN)، دون تثبيت إصداره، حتى 2026-11-11. - IBM Plex Sans Arabic (OFL) —
kazma-ui/kazma_ui/static/fonts/.
يفشل tests/test_editor_assets_offline.py البناء إن بدأ أي قالب بتحميل سكربت أو
أوراق أنماط بعيدة مجددًا، ويفشله tests/test_vendor_livekit.py إن فعل ذلك أي سكربت
صفحة، وترفض سياسة أمان المحتوى (Content-Security-Policy) في الصفحات داخل المتصفح أي
سكربت من مضيف آخر.
توقيع مثبّت ويندوز
Section titled “توقيع مثبّت ويندوز”يُبنى المثبّت في مهمة windows-installer من سير عمل الإصدارات، من أرشيف المصدر الذي
صنعته مهمة build (يقرؤه scripts/windows_installer/build.py بقواعد المحدِّث نفسها)،
ثم تُحسب بصمته ويُشهد عليه ويوقَّع عبر Sigstore مع بقية الملفات. أما ويندوز نفسه فيتحقق
من توقيع آخر (Authenticode). تضيفه المهمة عبر Artifact Signing من Microsoft (المعروفة
سابقًا بـ Trusted Signing) متى ضُبطت، وتنشر المثبّت غير موقّع حتى ذلك الحين (ويقول
التشغيل ذلك). ولتفعيله، بعد إنشاء حساب Artifact Signing وإتمام التحقق من الهوية:
- في Azure: حساب Artifact Signing وملف تعريف شهادة (Public Trust)، وتسجيل تطبيق يُمنح دور Artifact Signing Certificate Profile Signer على ذلك الملف.
- في تسجيل التطبيق، بيانات اعتماد موحّدة لـ GitHub Actions: المنظمة
Mubder، والمستودعkazma، والكيان Branch، والفرعmain(فسير عمل الإصدارات يُطلق منmain). بلا سرّ عميل. - في إعدادات المستودع، ضمن Secrets:
AZURE_SIGNING_CLIENT_IDوAZURE_SIGNING_TENANT_IDوAZURE_SIGNING_SUBSCRIPTION_ID. وضمن Variables:AZURE_SIGNING_ENDPOINT(نقطة نهاية منطقة الحساب، مثلhttps://weu.codesigning.azure.net)، وAZURE_SIGNING_ACCOUNT، وAZURE_SIGNING_PROFILE، وKAZMA_WINDOWS_SIGNING=artifact-signing.
ومن ثمّ توقّع المهمة المثبّت، وتختمه زمنيًا، وتفشل ما لم يقرأ ويندوز التوقيع صالحًا. ولا
تعتمد تحديثات كاظمه عليه: يتحقق kazma update من كل إصدار بتوقيع Sigstore الخاص به.
ما لا يثبته هذا
Section titled “ما لا يثبته هذا”يستحق القول بصراحة، لأن صفحة سلسلة توريد تبالغ في الوعود أسوأ من عدم وجودها أصلًا.
- ليست بناءات قابلة لإعادة الإنتاج. إثبات المنشأ يثبت من بنى القطعة ومن أي إيداع. وهو لا يمكّنك من إعادة بنائها باستقلال والحصول على نتيجة متطابقة بايتًا-ببايت. ذلك عمل أكبر ولا يُدَّعى.
- إثبات المنشأ ليس مراجعة كود. يثبت أن القطعة جاءت من هذا المستودع. ولا يقول شيئًا عن إن كان الكود في ذلك المستودع جيدًا أو آمنًا أو خاليًا من العلل. اقرأه؛ فلهذا هو مفتوح.
- الـ SBOM يسرد التبعيات، لا الثغرات. هو مدخل لماسح، لا شهادة سلامة.
- سجلّ Sigstore عام. التحقق لا يسرّب شيئًا، لكن كون إصدارًا موجودًا معلومة عامة بالتصميم.

