تخطَّ إلى المحتوى
kazma.
البحث في كاظمه والتوثيق
EN

سلسلة التوريد — التحقق من إصدار كاظمه

سلسلة التوريد — التحقق من إصدار كاظمه

Section titled “سلسلة التوريد — التحقق من إصدار كاظمه”

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

لذلك كل قطعة إصدار موقَّعة، وتحمل إثبات منشأ البناء (build provenance)، وتُشحن معها SBOM. هذه الصفحة هي كيف تتحقق من الثلاثة. ولا شيء من ذلك يتطلب حسابًا ولا مورّدًا ولا خدمة مدفوعة.


الملفما هو
kazma-<version>-py3-none-any.whlحزمة wheel
kazma-<version>.tar.gzالتوزيعة المصدرية
kazma-<version>.cdx.jsonSBOM بصيغة CycloneDX 1.6 لمجموعة التبعيات المثبّتة
kazma-<version>-windows-setup.exeمثبّت ويندوز (من الإصدار الذي يلي 0.21.2)، مبني من أرشيف المصدر أعلاه
SHA256SUMSبصمات تحقق (checksums) للملفات أعلاه
*.sigstore.jsonحزمة Sigstore لكل قطعة — التوقيع

شهادات إثبات المنشأ ليست ملفات في الإصدار؛ GitHub يخزنها ويجلبها لك gh attestation verify.


تُوزَّع كاظمه عبر إصدارات 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) أول إصدار ينشره سير العمل منذ ذلك الحين، وحزمته تجتاز الفحوص أدناه.

الأسماء هي 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، …)
OwnerMubder
Repository namekazma
Workflow namepypi-reserve.yml
Environment namepypi- والاسم (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.... راجع التشغيلة إن لم تكن متأكدًا أيها ينطبق.


نافذة طرفيّة
sha256sum -c SHA256SUMS

أضعف الثلاثة وهي وحدها — إذ يمكن استبدال ملف البصمات مع القطع. ويستحق التشغيل لأن SHA256SUMS موقَّع أيضًا، فالتحقق من حزمة Sigstore الخاصة به أولًا يجعل البصمات ذات معنى.


‏kazma-<version>.cdx.json بصيغة CycloneDX 1.6، مولَّد من uv.lock لا من بيئة آلة البناء. وهذا التمييز مهم: فهو يصف المجموعة المثبّتة الدقيقة التي يثبّتها لك uv sync، لا ما صادف أن حلّه مشغّل CI في ذلك اليوم. والمولِّد نفسه إصدار واحد محدد أيضًا (cyclonedx-bom==8.0.1)، وكذلك كل أداة يشغّلها سير عمل أو سكربت بناء عبر uvx أو npx: فدون رقم إصدار تشغّل ما يقدّمه السجلّ ذلك اليوم.

أطعمه لما تستخدمه مؤسستك أصلًا. ولنظرة سريعة:

نافذة طرفيّة
# Component count and licences
python - <<'PY'
import json
d = 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 scanner
grype sbom:kazma-0.21.2.cdx.json
trivy 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-client 2.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) في الصفحات داخل المتصفح أي سكربت من مضيف آخر.


يُبنى المثبّت في مهمة windows-installer من سير عمل الإصدارات، من أرشيف المصدر الذي صنعته مهمة build (يقرؤه scripts/windows_installer/build.py بقواعد المحدِّث نفسها)، ثم تُحسب بصمته ويُشهد عليه ويوقَّع عبر Sigstore مع بقية الملفات. أما ويندوز نفسه فيتحقق من توقيع آخر (Authenticode). تضيفه المهمة عبر Artifact Signing من Microsoft (المعروفة سابقًا بـ Trusted Signing) متى ضُبطت، وتنشر المثبّت غير موقّع حتى ذلك الحين (ويقول التشغيل ذلك). ولتفعيله، بعد إنشاء حساب Artifact Signing وإتمام التحقق من الهوية:

  1. في Azure: حساب Artifact Signing وملف تعريف شهادة (Public Trust)، وتسجيل تطبيق يُمنح دور Artifact Signing Certificate Profile Signer على ذلك الملف.
  2. في تسجيل التطبيق، بيانات اعتماد موحّدة لـ GitHub Actions: المنظمة Mubder، والمستودع kazma، والكيان Branch، والفرع main (فسير عمل الإصدارات يُطلق من main). بلا سرّ عميل.
  3. في إعدادات المستودع، ضمن 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 الخاص به.

يستحق القول بصراحة، لأن صفحة سلسلة توريد تبالغ في الوعود أسوأ من عدم وجودها أصلًا.

  • ليست بناءات قابلة لإعادة الإنتاج. إثبات المنشأ يثبت من بنى القطعة ومن أي إيداع. وهو لا يمكّنك من إعادة بنائها باستقلال والحصول على نتيجة متطابقة بايتًا-ببايت. ذلك عمل أكبر ولا يُدَّعى.
  • إثبات المنشأ ليس مراجعة كود. يثبت أن القطعة جاءت من هذا المستودع. ولا يقول شيئًا عن إن كان الكود في ذلك المستودع جيدًا أو آمنًا أو خاليًا من العلل. اقرأه؛ فلهذا هو مفتوح.
  • الـ SBOM يسرد التبعيات، لا الثغرات. هو مدخل لماسح، لا شهادة سلامة.
  • سجلّ Sigstore عام. التحقق لا يسرّب شيئًا، لكن كون إصدارًا موجودًا معلومة عامة بالتصميم.