نموذج أدلة Arxi وهندسة النزاهة

Audience: Engineers implementing envelope ingestion, hashing, signing, الجمهور: المهندسون الذين يقومون بتنفيذ استيعاب الحزم، والتجزئة، والتوقيع، والتحقق من النزاهة.

جدول المحتويات

نظرة عامة تنفيذية
الهوية والبدائيات المخططية
نموذج الظرف والقطاع
ترميز قياسي وتجزئة
سلامة المرفقات
نموذج التوقيع
نتيجة التحقق الجبري
مرجع متقاطع ملف بملف

نظرة عامة تنفيذية

تُبنى نزاهة Arxi على بايتات معيارية بالإضافة إلى ارتباط تشفيري:

تجزئة محتوى الظرف على وجهات نظر قابلة للتجزئة مكونة من 11 حقلًا،
تجزئة السلسلة التي تربط كل ظرف بالحالة السابقة،
ربط أصل السلسلة ورأس السلسلة السابقين،
توقيعات الظرف الاختيارية فوق بايتات تجزئة المحتوى.

F:crates/arxi-envelope/src/envelope.rs L46-L92 F:crates/arxi-envelope/src/encoding.rs L252-L296 F:crates/arxi-envelope/src/segment.rs L39-L66

الهوية والبدائيات المخططية

معرفات مدعومة من UUIDv7: EnvelopeId, SegmentId, BundleId.
معرفات السلسلة مع التحقق: EventType, ActorId, EnvironmentId, إلخ.
String-backed IDs fail closed on empty, whitespace-only, and تفشل معرفات المدعومة بسلاسل النصوص في الإغلاق عند الإدخال الفارغ أو الذي يحتوي فقط على مسافات أو أحرف تحكم.
String-backed IDs enforce explicit max-length bounds (256 for تفرض معرفات المدعومة بسلاسل حدود الطول الأقصى الصريحة (256 لـ trace/session/actor/environment، 128 لـ event/adapter IDs).
String-backed ID serde paths are constructor-validated so hostile JSON cannot يتم التحقق من مسارات تسلسل معرفات المدعومة بسلاسل عند البناء، بحيث لا يمكن لـ JSON العدائي تجاوز الثوابت.
KeyId is strict canonical lowercase hex(SHA-256(public_key_bytes)) KeyId هو تمثيل صارم بحروف صغيرة hex(SHA-256(public_key_bytes)) (64 حرفًا).
SchemaVersion صريح ومثبت حاليًا على 1 (CURRENT_SCHEMA_VERSION).

F:crates/arxi-core/src/identity.rs L31-L55 F:crates/arxi-core/src/identity.rs L205-L647 F:crates/arxi-core/src/schema.rs L24-L49

نموذج الظرف والقطاع

حالات الظرف

UnsealedEnvelope: حقول قابلة للتجزئة مقدمة من المحول.
Envelope: recorder-sealed record with content_hash, chain_hash, Envelope: سجل مختوم بواسطة المسجل مع content_hash، chain_hash، sequence، segment_id، وتوقيع اختياري.

F:crates/arxi-envelope/src/envelope.rs L98-L131 F:crates/arxi-envelope/src/envelope.rs L46-L92

ثوابت الباني

EnvelopeBuilder يفرض الحقول المطلوبة، ووقت المطالبة بتوقيت UTC، وترتيب المرفقات المحدد قبل إنتاج UnsealedEnvelope. F:crates/arxi-envelope/src/envelope.rs L284-L328

هيكل الشريحة

SegmentGenesis هو بيانات وصفية هيكلية (ليس ظرفًا) ويؤسس حساب السلسلة الأولى؛ يجب تعيين حقول السلف بشكل مشترك أو أن تكون غائبة. recorder_id مقيد بنفس الطول الأقصى مثل ActorId ومسارات فك التسلسل تم التحقق منها بواسطة المُنشئ. F:crates/arxi-envelope/src/segment.rs L39-L109

SealRecord يلتقط حالة المقطع النهائي وSealReason تصنيف. F:crates/arxi-envelope/src/segment.rs L116-L170

ترميز قياسي وتجزئة

Arxi يستخدم JCS (serde_jcs) فوق هياكل العرض القابلة للتجزئة الخاصة. المتغيرات المهمة:

None يتم تسلسله كـ null في المخرجات القياسية.
تستخدم الطوابع الزمنية تنسيق UTC ثابت مكون من 9 أرقام نانوية.
مراجع المرفقات مرتبة حسب تجزئة الهش في العروض القياسية.

F:crates/arxi-envelope/src/encoding.rs L19-L31 F:crates/arxi-envelope/src/encoding.rs L48-L77 F:crates/arxi-envelope/src/encoding.rs L148-L162

نموذج التجزئة:

content_hash = H(canonical_bytes)
chain_hash = H(prev_chain_hash || content_hash)
تستخدم الظرف الأول في الجزء H(segment_genesis_hash || content_hash)

F:crates/arxi-envelope/src/encoding.rs L239-L246 F:crates/arxi-envelope/src/encoding.rs L262-L273 F:crates/arxi-envelope/src/encoding.rs L285-L296

تُعتبر دوال التجزئة محددة بواسطة الخوارزميات وقابلة للإضافة من خلال HashFunction. الإعداد الافتراضي الحالي هو Sha256HashFunction. F:crates/arxi-core/src/hash.rs L200-L274

سلامة المرفقات

تمثيلات مرفقات اثنين:

AttachmentData: بايتات مضمنة تم تقديمها عند الإدخال.
AttachmentRef: بيانات وصفية موجهة بالمحتوى مدمجة في الأظرف.

AttachmentRef و AttachmentData ترفض القيم الفارغة، والقيم التي تحتوي فقط على مسافات، والقيم التي تحتوي على أحرف تحكم في content_type، وتفرض الحد الأقصى للطول (255)، وتقوم بفك تسلسل AttachmentRef من خلال التحقق من صحة المُنشئ. كما تتطلب AttachmentData أيضًا بايتات غير فارغة. F:crates/arxi-envelope/src/attachment.rs L35-L85 F:crates/arxi-envelope/src/attachment.rs L99-L133

نموذج التوقيع

عقد أساسي:

EnvelopeSigner يوقع بايتات content_hash.
SignatureVerifier يتحقق من بايتات الرسالة تحت مفاتيح محددة حسب الخوارزمية.
TrustRoot and TrustPolicy define trusted key material and signature TrustRoot و TrustPolicy تحدد المواد الرئيسية الموثوقة وسياسة قبول التوقيع (AnyTrustedKey, AllMustSign, Threshold).

F:crates/arxi-core/src/signature.rs L131-L270 F:crates/arxi-core/src/signature.rs L301-L337

التنفيذ الحالي:

Ed25519Signer derives key ID as hex(SHA-256(public_key_bytes)) and signs content_hash. Ed25519Signer يستخرج معرف المفتاح كـ hex(SHA-256(public_key_bytes)) ويقوم بتوقيع content_hash. F:crates/arxi-envelope/src/signer.rs L68-L113
Ed25519SignatureVerifier uses strict verification. Ed25519SignatureVerifier يستخدم التحقق الصارم. F:crates/arxi-envelope/src/signature.rs L32-L95
Verifier phase 6 uses trust-root lookup + algorithm dispatch and applies policy checks after per-envelope signature validation. Verifier المرحلة 6 تستخدم بحث جذر الثقة + توزيع الخوارزمية وتطبق فحوصات السياسة بعد التحقق من صحة التوقيع لكل ظرف. F:crates/arxi-recorder/src/verifier.rs L509-L651

نتيجة التحقق الجبري

arxi-envelope يحدد أنواع بيانات التحقق، بينما يعمل التحقق الخوارزمي في arxi-recorder.

الهياكل الرئيسية:

VerificationManifest و ManifestSegmentEntry
VerificationVerdict و VerdictStatus
CheckResult، CheckType، والفحوصات المتخصصة لسلسلة/قطاعات متقاطعة/توقيع
VerificationWarning للنتائج غير القاتلة

F:crates/arxi-envelope/src/verification.rs L39-L79 F:crates/arxi-envelope/src/verification.rs L85-L132 F:crates/arxi-envelope/src/verification.rs L189-L266

مرجع متقاطع لكل ملف

المنطقة	الملف	الملاحظات
عقود الهوية	`crates/arxi-core/src/identity.rs`	التحقق من الهوية والتسلسل الثابت لأنواع جديدة.
عقود التجزئة	`crates/arxi-core/src/hash.rs`	أنواع التجزئة، المساواة في وقت ثابت، سجل الخوارزميات.
عقود التوقيع	`crates/arxi-core/src/signature.rs`	سمات الموقّع/المتحقق وشكل توقيع الظرف.
نموذج الظرف	`crates/arxi-envelope/src/envelope.rs`	الأشكال المختومة/غير المختومة وثوابت الباني.
الترميز القياسي	`crates/arxi-envelope/src/encoding.rs`	بايتات JCS القياسية وصيغ السلسلة.
نموذج المقطع	`crates/arxi-envelope/src/segment.rs`	بيانات الجينيس والختم.
المرفقات	`crates/arxi-envelope/src/attachment.rs`	مراجع المرفقات المعنونة بالمحتوى.
نموذج التحقق	`crates/arxi-envelope/src/verification.rs`	الجملة وجبر نتائج التحقق.
تحقق Ed25519	`crates/arxi-envelope/src/signature.rs`	تنفيذ صارم للتحقق من التوقيع.
توقيع Ed25519	`crates/arxi-envelope/src/signer.rs`	تنفيذ توقيع الظرف.