> ## 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. يعد فهم هذه المفاهيم ضروريًا للتكامل الفعال.

## المستأجرون

المستأجر هو الوحدة التنظيمية العليا في Truthlocks. يمثل كل مستأجر عميلاً أو مؤسسة مميزة مع عزل كامل للبيانات.

| الخاصية | الوصف |
| - | - |
| `id` | UUID فريد يحدد المستأجر |
| `name` | اسم المنظمة المقروء بشريًا |
| `slug` | معرف آمن لعنوان URL (مثل `acme-corp`) |
| `tier` | مستوى الاشتراك: FREE, STARTER, PROFESSIONAL, ENTERPRISE |
| `status` | نشط، معلق، أو محذوف |

### ضوابط تعدد المستأجرين

* **عزل البيانات:** يتم عزل بيانات كل مستأجر بالكامل على مستوى قاعدة البيانات
* **حدود الموارد:** يتم فرض حدود المعدل والحصص لكل مستأجر
* **تحديد نطاق مفتاح API:** مفاتيح API مرتبطة بمستأجر واحد ولا يمكنها الوصول إلى بيانات المستأجرين الآخرين
* **فصل التدقيق:** يتم تقسيم سجلات التدقيق حسب المستأجر

## المصدرون

المصدر هو كيان يمكنه إنشاء وتوقيع التصديقات. يمثل المصدرون منظمات أو مؤسسات أو خدمات تقدم مطالبات حول الموضوعات.

> [card] الهوية
>
> لكل مُصدر نطاق مُتحقق منه (مثل `acme.edu`) يؤسس هويته
> الهوية الحقيقية.

> [card] المفاتيح التشفيرية
>
> تسجل الجهات المصدرة مفاتيح Ed25519 العامة المستخدمة للتحقق من توقيعات الشهادات.

> [card] حالة الثقة
>
> يتم تفعيل الجهات المصدرة الجديدة فور إنشائها. تتطلب مستويات الثقة الأعلى مراجعة الطلب: نشط ← معلق.

> [card] مستوى الثقة
>
> أساسي، أو موثق، أو مميز بناءً على عمق التحقق من الهوية.

### دورة حياة المصدر

```text theme={null}
                    ┌──────────────┐
                    │   CREATED    │
                    └───────┬──────┘
                            │ auto-activated
                            ▼
                    ┌──────────────┐
                    │    ACTIVE    │  ← Ready to mint (BASIC trust)
                    └───────┬──────┘
                            │
            suspend │               │ apply for higher tier
                    ▼               ▼
            ┌──────────────┐  ┌──────────────┐
            │   SUSPENDED  │  │   IN REVIEW  │
            └──────────────┘  └───────┬──────┘
                                      │
                              approve │ reject
                              ▼               ▼
                      ┌──────────────┐  ┌──────────────┐
                      │    ACTIVE    │  │   REJECTED   │
                      │ (higher tier)│  │ (keeps BASIC)│
                      └──────────────┘  └──────────────┘
```

> [!NOTE]
>
> يتم تفعيل المصدرين الجدد فورًا بمستوى الثقة **الأساسي**. لا يلزم موافقة يدوية لبدء سك الإثباتات. للترقية إلى مستوى ثقة أعلى (مؤسسة معتمدة، كيان حكومي، أو مؤسسة معتمدة)، قدم [طلب مصدر](https://docs.truthlocks.com/ar/guides/issuer-applications.md) للمراجعة.

## الشهادات

التصديق هو مطالبة موقعة تشفيريًا يقدمها مصدر حول موضوع. التصديقات هي البدائية الأساسية لنظام Truthlocks.

### هيكل التصديق

```json theme={null}
{
  "id": "uuid", // Unique identifier
  "issuer_id": "uuid", // Who signed it
  "kid": "string", // Key used to sign
  "status": "VALID", // Current status
  "payload": {
    "subject": "string", // Who/what the claim is about
    "claim": "string", // Type of claim (e.g., "verified_email")
    "value": "any", // The actual claim data
    "metadata": {} // Optional additional data
  },
  "signature": "base64", // Ed25519 signature
  "log_index": 42, // Position in transparency log
  "created_at": "datetime"
}
```

### خصائص التصديق

| الخاصية | الوصف |
| - | - |
| **غير قابل للتغيير** | بمجرد إنشائه، لا يمكن تعديل الحمولة والتوقيع |
| **قابل للإلغاء** | يمكن للمصدرين إلغاء الشهادات، وتحديث الحالة إلى REVOKED |
| **قابل للإبطال** | يمكن للمصدرين [إبطال](https://docs.truthlocks.com/ar/api-reference/attestations/supersede.md) شهادة بإصدار جديد، مما ينشئ سلسلة تدقيق مع الحفاظ على الأصل |
| **محمول** | يمكن مشاركة معرف الشهادة والتحقق منه في أي مكان |
| **قابل للتدقيق** | يتم تسجيل كل عملية في سجل الشفافية |

## حماية المستهلك

إن **حماية المستهلك** هي شهادة تم إنشاؤها من خلال تدفق [سك العملات للمستهلك](https://docs.truthlocks.com/ar/api-reference/consumer/mint.md) المبسّط، والمصمم للمبدعين الأفراد. تقوم بتجزئة ملفك من جانب العميل (SHA-256) وتقديم التجزئة مع بيانات وصفية مثل العنوان والفئة ونوع المحتوى. يقوم Truthlocks بتوفير هوية التوقيع الخاصة بك تلقائيًا عند الاستخدام الأول.

يتضمن رد سك المستهلك:

| الحقل | الوصف |
| - | - |
| `protection_id` | معرف فريد لسجل الحماية |
| `attestation_id` | معرف التصديق الأساسي (المستخدم للتحقق) |
| `content_hash` | تجزئة SHA-256 التي أرسلتها، معادة للتأكيد |
| `protected_at` | الطابع الزمني الدقيق عندما تم حماية المحتوى |
| `verify_url` | عنوان URL لصفحة الإثبات العامة التي يمكنك مشاركتها مع أي شخص |
| `status` | حالة التأكيد (`protected`) |

ينشئ كل حماية صفحة إثبات عامة. يمكن لأي شخص جلب بيانات تعريف صفحة الإثبات عبر `GET /v1/public/proof/{attestation_id}` — لا يلزم المصادقة. تم تصميم نقطة النهاية هذه لعرض صفحات الإثبات وإنشاء معاينات روابط Open Graph لعنوان URL المشتركة. راجع [نقطة نهاية بيانات تعريف الإثبات](https://docs.truthlocks.com/ar/api-reference/consumer/proof-metadata.md) للحصول على التفاصيل.

## إشارات المخاطر

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

تتضمن كل إشارة:

| الحقل | الوصف |
| :- | :- |
| `signal_source` | من أين جاءت الإشارة (على سبيل المثال `device_fingerprint`، `ip_reputation`، `login`) |
| `signal_type` | ما تم اكتشافه (على سبيل المثال `velocity`، `geo_anomaly`، `ato`، `deepfake`) |
| `risk_score` | درجة المخاطر من `0` (آمن) إلى `100` (مخاطر عالية) — الدرجات التي تساوي أو تزيد عن 80 تؤدي إلى مراجعة تلقائية |
| `subject_id` | معرف الكيان الذي يتم تقييمه |
| `subject_type` | نوع الكيان: `user`، `issuer`، `session`، `device`، `ip`، أو `attestation` |
| `payload` | بيانات وصفية عشوائية (عناوين IP، تحديد الموقع الجغرافي، الأسباب) |

### تسوية الأحداث

بدلاً من إنشاء إشارات المخاطر يدويًا، يمكنك إرسال أحداث الهوية الأولية — عمليات تسجيل الدخول الفاشلة، التوقيعات غير الصالحة، المشتبه بهم في التزييف العميق — إلى `POST /v1/risk/events`. تقوم المنصة بربط كل حدث بنوع إشارة قانوني ودرجة مخاطر أساسية تلقائيًا. راجع [مرجع واجهة برمجة تطبيقات تطبيع أحداث الهوية](https://docs.truthlocks.com/ar/api-reference/risk/normalize-event.md).

إشارات المخاطر معزولة تمامًا للمستأجر باستخدام [أمان على مستوى الصف](https://docs.truthlocks.com/ar/security/rls.md) وتشكل أساس جدار حماية الهوية لمكافحة الاحتيال. راجع [دليل إشارات المخاطر](https://docs.truthlocks.com/ar/guides/risk-signals.md) للحصول على تفاصيل التكامل.

## وكلاء الآلة

إن **وكيل الآلة** هو وكيل ذكاء اصطناعي، أو روبوت، أو خدمة آلية مسجلة ببروتوكول [هوية وكيل الآلة (MAIP)](https://docs.truthlocks.com/ar/guides/machine-identity.md). يحصل كل وكيل على معرف فريد (`maip-agent:<ulid>`) وزوج مفاتيح Ed25519 لتوقيع الإيصالات.

| الحقل | الوصف |
| :- | :- |
| `agent_id` | معرف MAIP فريد للوكيل |
| `name` | اسم وكيل مقروء بشريًا (على سبيل المثال، `order-processor`) |
| `type` | نوع الوكيل: `autonomous`، `supervised`، `delegated`، أو `system` |
| `scopes` | نطاقات الأذونات التي يُصرح للوكيل باستخدامها |
| `status` | حالة دورة الحياة: `active`، `suspended`، أو `revoked` |
| `trust_score` | درجة ثقة سلوكية مستمرة من 0 إلى 100 |

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

راجع [دليل هوية الجهاز](https://docs.truthlocks.com/ar/guides/machine-identity.md) للإعداد و [دليل ترخيص الوكيل](https://docs.truthlocks.com/ar/guides/agent-authorization.md) لنموذج النطاق والجلسة.

## حزم الإثبات

إن **حزمة الإثبات** هي حزمة مكتفية ذاتيًا تتضمن كل ما يلزم للتحقق من شهادة دون اتصال بالإنترنت، دون الاتصال بخوادم Truthlocks.

```json theme={null}
{
  "attestation": { ... },       // Full attestation object
  "issuer": {
    "id": "uuid",
    "name": "Acme University",
    "domain": "acme.edu",
    "trust_level": "VERIFIED"
  },
  "public_key": {
    "kid": "ed-key-2026",
    "algorithm": "Ed25519",
    "public_key_pem": "-----BEGIN PUBLIC KEY-----..."
  },
  "transparency_proof": {
    "log_index": 42,
    "root_hash": "sha256:...",
    "inclusion_proof": ["hash1", "hash2", ...]
  }
}
```

> [!NOTE]
>
> **حالة الاستخدام:** حزم الإثبات مثالية للسيناريوهات التي قد يكون فيها المدققون
> غير متصل بالإنترنت أو تريد التحقق بشكل مستقل بدون استدعاءات API.

## نموذج التحقق

تتحقق Truthlocks من طبقات متعددة لتحديد ما إذا كان يجب الوثوق بشهادة:

**1. التحقق التشفيري**

تحقق من تطابق توقيع Ed25519 مع الحمولة باستخدام المفتاح العام للمصدر.
المفتاح.

**2. التحقق من الحالة**

تحقق مما إذا كانت الشهادة قد تم إلغاؤها أو استبدالها من قبل المصدر. ترتبط الشهادات المستبدلة ببديلها عبر `superseded_by_attestation_id`.

**3. حالة ثقة المُصدر**

تأكد من أن المصدر في حالة نشطة وغير معلق.

**4. صلاحية المفتاح**

تحقق من أن مفتاح التوقيع كان نشطًا وقت إنشاء الإثبات.

## الخطوات التالية

> [card] [البيئات](https://docs.truthlocks.com/environments.md)
>
> تعرف على بيئات التطوير مقابل الإنتاج والتكوين.

> [card] [المصادقة](https://docs.truthlocks.com/security/auth.md)
>
> تعمق في مفاتيح API، ورموز JWT، وتكامل OAuth.


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