> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# تنسيق حزمة الإثبات

> مواصفات تنسيق حزمة إثبات Truthlocks المشفرة الإصدار 1.0.

تحمل **حزمة إثبات Truthlocks** أدلة للفحوصات التشفيرية المدعومة لسجل ما. تتطلب عملية التحقق دون اتصال الحمولة المقابلة، والتنسيق المدعوم، ومفاتيح الجهة المصدرة والسجل الموثوق بها بشكل مستقل. لا تثبت حالة الإلغاء الحالية، أو سلطة الجهة المصدرة، أو الحقيقة الواقعية، أو ما إذا كان إجراء حقيقي قد حدث.

المواصفات الإصدار 1.0

## 1. نظرة عامة

حزمة إثبات Truthlocks هي وثيقة إثبات محمولة. استخدم التنسيق والمحقق الموثقين لنقطة النهاية التي أنتجتها. دعم CBOR مدرج أدناه كامتداد مستقبلي، وليس ضمانًا للصادرات الحالية.

يمكن أن تتضمن الأدلة بيانات إثبات، ومراجع مفاتيح، وإثباتات سجل الشفافية. تحقق من التوقيع وتضمين السجل بشكل منفصل؛ يجب عدم الإبلاغ عن الأدلة الغائبة كفحص ناجح. لا تثق أبدًا بمفتاح عام لمجرد أنه مضمن في الحزمة: قم بتحديد المفتاح المصرح به عبر قناة موثوقة. المخطط أدناه هو وصف مرجعي؛ طابق إصدار التصدير الفعلي وعقد البايت الموقع الخاص به قبل تنفيذ أداة التحقق.

## 2. هيكل الحزمة

يتم تسلسل حزم الإثبات ككائنات JSON وتتبع هذا المخطط:

```json theme={null}
{
  "header": {
    "version": "1.0",
    "bundle_id": "bun_a1b2c3d4...",
    "generated_at": "2026-03-12T14:30:00Z",
    "format": "json",
    "tenant_id": "ten_x9y8z7..."
  },
  "attestation": {
    "id": "att_k7x2m9...",
    "type": "content_protection",
    "subject": "main.ts",
    "subject_type": "file",
    "content_hash": "sha256:a1b2c3d4e5f6...",
    "metadata": {
      "title": "My Project",
      "category": "code",
      "file_size": 4096
    },
    "issued_at": "2026-03-12T14:28:00Z",
    "issuer_id": "iss_p4q5r6...",
    "issuer_key_id": "key_m1n2o3...",
    "signature": "base64url-encoded-signature",
    "signature_format": "Ed25519",
    "status": "active"
  },
  "proofs": [
    {
      "log_id": "log_main",
      "tree_size": 42857,
      "leaf_index": 42856,
      "leaf_hash": "sha256:...",
      "inclusion_proof": ["sha256:...", "sha256:...", "..."],
      "root_hash": "sha256:...",
      "timestamp": "2026-03-12T14:28:01Z"
    }
  ],
  "issuer_certificate": {
    "issuer_id": "iss_p4q5r6...",
    "issuer_did": "did:truthlock:iss_p4q5r6...",
    "key_id": "key_m1n2o3...",
    "algorithm": "Ed25519",
    "public_key_der": "base64-encoded-public-key",
    "valid_from": "2026-01-01T00:00:00Z",
    "trust_anchor": "truthlocks-root-2026"
  },
  "bundle_hash_b64url": "base64url-encoded-sha256-of-bundle",
  "bundle_signature": {
    "key_id": "truthlocks-signing-key-2026",
    "algorithm": "Ed25519",
    "value": "base64-encoded-bundle-signature"
  }
}
```

## 3. تعريفات الحقول

### 3.1 الرأس

| الحقل | النوع | مطلوب | الوصف |
| :- | :- | :- | :- |
| `version` | string | نعم | إصدار تنسيق الحزمة (حاليًا "1.0") |
| `bundle_id` | string | نعم | معرف فريد لهذه الحزمة |
| `generated_at` | datetime | نعم | طابع زمني بتنسيق ISO 8601 لتوليد الحزمة |
| `format` | string | نعم | تنسيق الترميز: "json" أو "cbor" |
| `tenant_id` | string | نعم | المستأجر الذي يملك الإشهاد |

### 3.1.1 تجزئة سلامة الحزمة

| الحقل | النوع | مطلوب | الوصف |
| :- | :- | :- | :- |
| `bundle_hash_b64url` | string | نعم | تجزئة SHA-256 مشفرة بـ Base64url لجميع حقول الحزمة (باستثناء `bundle_hash_b64url` و `bundle_signature`). تُستخدم للكشف عن التلاعب — أي تعديل لمحتوى الحزمة يبطل هذه التجزئة. |

### 3.2 التصديق

| الحقل | النوع | مطلوب | الوصف |
| :- | :- | :- | :- |
| `id` | سلسلة أحرف | نعم | معرف الإثبات |
| `type` | سلسلة أحرف | نعم | نوع الإثبات (مثل content\_protection, identity.kyc) |
| `subject` | string | نعم | موضوع التصديق (اسم الملف، الشخص، إلخ) |
| `subject_type` | string | لا | تلميح نوع للموضوع (ملف، شخص، منظمة) |
| `content_hash` | string | نعم | تجزئة SHA-256 للمحتوى المصدق (مسبوقة بـ sha256:) |
| `document_hash` | string | لا | تجزئة SHA-256 محسوبة مسبقًا تم تمريرها وقت الإنشاء. عند توفيرها، تستخدم المنصة هذه القيمة بدلاً من حساب التجزئة داخليًا. |
| `metadata` | كائن | لا | بيانات وصفية إضافية حول التصديق |
| `issued_at` | datetime | نعم | متى تم سك التصديق |
| `valid_from` | datetime | لا | بداية فترة الصلاحية |
| `valid_until` | datetime | لا | نهاية فترة الصلاحية (null = لا يوجد انتهاء صلاحية) |
| `issuer_id` | string | نعم | معرف الكيان المُصدر |
| `issuer_key_id` | string | نعم | معرف المفتاح المستخدم لتوقيع الإشهاد |
| `signature` | string | نعم | توقيع مشفر بـ Base64url على حمولة التصديق |
| `signature_format` | string | نعم | الخوارزمية المستخدمة: Ed25519, ES256, RS256 |
| `status` | سلسلة أحرف | نعم | لقطة الحالة عند التصدير؛ قم بالتحديث للقبول الحالي |

### 3.3 البراهين (سجل الشفافية)

| الحقل | النوع | الوصف |
| :- | :- | :- |
| `log_id` | سلسلة أحرف | معرف سجل الشفافية |
| `tree_size` | عدد صحيح | حجم شجرة ميركل وقت الإدراج |
| `leaf_index` | عدد صحيح | موضع هذا الإدخال في الشجرة |
| `leaf_hash` | string | تجزئة SHA-256 لعقدة الورقة |
| `inclusion_proof` | string\[] | قائمة مرتبة من تجزئات الأشقاء التي تشكل مسار إثبات التضمين |
| `root_hash` | string | تجزئة جذر رأس الشجرة الموقعة وقت الإدراج |
| `timestamp` | datetime | متى تمت إضافة الإدخال إلى السجل |

### 3.4 شهادة المُصدر

| الحقل | النوع | الوصف |
| :- | :- | :- |
| `issuer_id` | string | UUID المُصدر |
| `issuer_did` | string | معرف لامركزي W3C (did:truthlock:...) |
| `key_id` | string | معرف المفتاح |
| `algorithm` | string | خوارزمية المفتاح: Ed25519, ES256, RS256 |
| `public_key_der` | string | مفتاح عام مشفر بـ Base64 بتنسيق DER |
| `valid_from` | datetime | بداية صلاحية المفتاح |
| `valid_until` | datetime | انتهاء صلاحية المفتاح (null = لا يوجد انتهاء صلاحية) |
| `trust_anchor` | string | مرجع إلى مرساة الثقة الجذرية |

## 4. خوارزمية التحقق

للتحقق من حزمة إثبات Truthlocks، اتبع الخطوات التالية بالترتيب. إذا فشلت أي خطوة، فإن الحزمة غير صالحة.

### الخطوة 1: التحقق من سلامة الحزمة

احسب تجزئة SHA-256 لجميع حقول الحزمة باستثناء `bundle_hash_b64url` و `bundle_signature`. فك ترميز Base64url لقيمة `bundle_hash_b64url` وقارنها بالتجزئة المحسوبة. إذا لم تتطابق، فقد تم التلاعب بالحزمة.

### الخطوة 2: التحقق من توقيع الإشهاد

باستخدام المفتاح العام من `issuer_certificate.public_key_der` والخوارزمية المحددة في `attestation.signature_format`، تحقق من `attestation.signature` مقابل حمولة التصديق القانونية (جميع حقول التصديق باستثناء `signature` و `status`).

### الخطوة 3: التحقق من تجزئة المحتوى

إذا كان لديك الملف الأصلي، فاحسب تجزئة SHA-256 الخاصة به وقارنها بـ `attestation.content_hash`. يؤكد هذا أن الملف لم يتم تعديله منذ التصديق.

إذا كانت قيمة `document_hash` موجودة، يمكنك أيضًا مقارنتها بالتجزئة المحسوبة لديك. `document_hash` هي تجزئة سداسية عشرية SHA-256 محسوبة مسبقًا قام المُنشئ بتمريرها وقت الإنشاء، مما يوفر فحصًا إضافيًا للسلامة مستقلاً عن ترميز الحمولة.

### الخطوة 4: التحقق من تضمين سجل الشفافية

لكل إدخال في `proofs`، تحقق من إثبات تضمين Merkle. بدءًا من `leaf_hash` في الموضع `leaf_index`، أعد حساب الجذر عن طريق التجزئة مع كل شقيق في `inclusion_proof`. يجب أن تتطابق النتيجة مع `root_hash`.

### الخطوة 5: التحقق من صلاحية المفتاح

تأكد من أن `issuer_certificate.valid_from` ≤ `attestation.issued_at` ≤ `issuer_certificate.valid_until` (إذا كانت موجودة).

## 5. الخوارزميات المدعومة

| الخوارزمية | نوع المفتاح | الاستخدام |
| :- | :- | :- |
| `Ed25519` | OKP (Curve25519) | الافتراضي لمصدري المستهلكين. توقيعات سريعة ومضغوطة. |
| `ES256` | EC (P-256) | ECDSA مع SHA-256. متوافق مع FIPS. |
| `RS256` | RSA (2048+) | RSA مع SHA-256. توافق قديم. |

## 6. أدوات التحقق

يمكن التحقق من حزم الإثبات باستخدام أي من هذه الطرق:

* **CLI**: `truthlock verify -b bundle.json -f original-file --trusted-log-key "$TRUTHLOCKS_LOG_PUBLIC_KEY" --trusted-issuer-key "$TRUTHLOCKS_ISSUER_PUBLIC_KEY"`. قم بتثبيت كلا المفتاحين العموميين بشكل مستقل عن الحزمة. لا تؤسس الفحوصات غير المتصلة بالإنترنت حالة الإلغاء الحالية.
* **الويب**: التحميل على `verify.truthlocks.com/proof/[id]`
* **SDK**: `client.verify.verifyBundle(bundleJson, fileBuffer)`
* **يدوي**: اتبع خوارزمية التحقق أعلاه مع أي مكتبة Ed25519/ECDSA

## 7. نقاط التوسع

الحقل `metadata` في كائن الشهادة قابل للتوسيع. يمكن أن تتضمن المخططات المخصصة حقولًا إضافية دون كسر التحقق. تعتمد خوارزمية التحقق الأساسية فقط على `content_hash` و`signature` وإثباتات سجل الشفافية.

قد تقدم إصدارات التنسيق المستقبلية:

* ترميز CBOR للتمثيل الثنائي المضغوط
* حزم الشهادات المتعددة (التحقق الدفعي)
* إثباتات الاتساق عبر السجلات
* إثباتات حالة الإلغاء (مضمنة)

## 8. مبادئ التصميم

* **ذاتي الاحتواء**: لا يتطلب الوصول إلى الشبكة للتحقق
* **تقليل الثقة**: قابل للتحقق حتى لو توقفت Truthlocks عن العمل
* **متوافق مع المستقبل**: يتم تجاهل الحقول غير المعروفة بواسطة أدوات التحقق الأقدم
* **حتمي**: يضمن ترميز JSON الكنسي تجزئة متسقة
* **مفتوح**: يستخدم بدائيات تشفير قياسية (لا توجد تنسيقات خاصة)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.