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

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

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

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

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

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

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

F:crates/recorder-envelope/src/envelope.rs L46-L92 F:crates/recorder-envelope/src/encoding.rs L252-L296 F:crates/recorder-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/recorder-core/src/identity.rs L31-L55 F:crates/recorder-core/src/identity.rs L205-L647 F:crates/recorder-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/recorder-envelope/src/envelope.rs L98-L131 F:crates/recorder-envelope/src/envelope.rs L46-L92

ثوابت الباني

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

هيكل الشريحة

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

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

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

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

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

F:crates/recorder-envelope/src/encoding.rs L19-L31 F:crates/recorder-envelope/src/encoding.rs L48-L77 F:crates/recorder-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/recorder-envelope/src/encoding.rs L239-L246 F:crates/recorder-envelope/src/encoding.rs L262-L273 F:crates/recorder-envelope/src/encoding.rs L285-L296

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

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

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

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

AttachmentRef و AttachmentData ترفض القيم الفارغة، والقيم التي تحتوي على مسافات فقط، والقيم التي تحتوي على أحرف تحكم في content_type، وتفرض الحد الأقصى للطول (255)، وتقوم بإلغاء تسلسل AttachmentRef من خلال التحقق من صحة المُنشئ. كما تتطلب AttachmentData أيضًا بايتات غير فارغة. F:crates/recorder-envelope/src/attachment.rs L35-L85 F:crates/recorder-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/recorder-core/src/signature.rs L131-L270 F:crates/recorder-core/src/signature.rs L301-L337

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

Ed25519Signer derives key ID as hex(SHA-256(public_key_bytes)) and signs content_hash. F:crates/recorder-envelope/src/signer.rs L68-L113
Ed25519SignatureVerifier uses strict verification. F:crates/recorder-envelope/src/signature.rs L32-L95
Verifier phase 6 uses trust-root lookup + algorithm dispatch and applies policy checks after per-envelope signature validation. F:crates/recorder/src/verifier.rs L509-L651

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

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

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

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

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

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

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