> ## 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.

# حماية CLI

> سجل بصمات الملفات من حساب مستهلك أو مساحة عمل تجارية، ثم تحقق من الملف الأصلي.

سجل بصمة SHA-256 لملف وتحقق منها لاحقًا باستخدام Truthlocks. الملفات هي
تم تجزئته محليًا: يرسل CLI بصمة الإصبع وبيانات السجل الوصفية، وليس محتويات الملف.

**وقت التشغيل:** Node.js 18+ · **الحزمة:** `@truthlocks/protect` · **الأمر:** `truthlock-protect`

[Console](https://console.truthlocks.com) · [تطبيق المستهلك](https://verify.truthlocks.com) · [وثائق API](https://docs.truthlocks.com)

## التثبيت

```sh theme={null}
npm install --global @truthlocks/protect
truthlock-protect --help
```

يتم تثبيت الأمر `truthlocks` أيضًا كاسم مستعار. تسجل هذه الحزمة عبر الإنترنت
بصمات الأصابع؛ استخدم `@truthlocks/cli` للتحقق من حزمة الإثبات دون اتصال.

## اختر نوع حسابك

| الحساب | بيانات الاعتماد | إعداد التوقيع |
| - | - | - |
| مساحة عمل الأعمال | `TRUTHLOCKS_API_KEY` | مُصدر نشط ومفتاح متاح للتوقيع في وحدة التحكم. |
| حساب المستهلك | `TRUTHLOCK_TOKEN` | رمز حامل مستهلك مصرح به؛ تدير Truthlocks مفتاح التوقيع الخاص به. |

مفتاح API ليس رمز مستهلك. يستخدم CLI نقاط نهاية مختلفة لهذين الأمرين
سير العمل. تحدد مفاتيح API الاختبارية المضيف التجريبي. قم بتعيين `TRUTHLOCK_API_URL` فقط عندما
تحتاج عمدًا إلى أصل API مختلف.

## دليل البدء السريع لمساحة العمل

عيّن `TRUTHLOCKS_API_KEY` و `TRUTHLOCKS_ISSUER_ID` و `TRUTHLOCKS_KEY_ID` في بيئتك،
ثم حماية ملف موجود:

```sh theme={null}
truthlock-protect whoami
truthlock-protect protect ./report.pdf --title "Quarterly report" --idempotency-key report-release-2026-10-11 --output ./report.receipt.json --json
```

استبدل مفتاح إعادة المحاولة المثال بقيمة فريدة لهذه العملية. احتفظ به مع
تفاصيل الطلب وإعادة استخدامها فقط للطلب المتطابق. يحتوي الإخراج على
`attestation_id` و `payload_b64url`؛ احتفظ بهما. يحفظ خيار `--output` إيصالًا دون الكتابة فوق ملف موجود. تقوم هذه العملية بكتابة سجل.

يمكنك تحديد المصدر والمفتاح بشكل صريح بدلاً من ذلك:

```sh theme={null}
truthlock-protect protect ./report.pdf --issuer-id YOUR_ISSUER_UUID --key-id YOUR_SIGNING_KEY_ID --algorithm Ed25519 --json
```

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

تستخدم سجلات مساحة العمل مطالبات منظمة ببصمة `document.sha256` و
تجزئة مستند صريحة. تتبع قواعد الوصول إلى مساحة العمل/API؛ رؤية المستهلك
لا تنطبق العلامات على سير العمل هذا.

## دليل البدء السريع للمستهلك

عيّن `TRUTHLOCK_TOKEN` إلى رمز حامل مستهلك مصرح به، مع مفتاح API لمساحة العمل
متغيرات البيئة غير مضبوطة، ثم قم بالتشغيل:

```sh theme={null}
truthlock-protect whoami
truthlock-protect protect ./design.png --title "Design source" --private --output ./design.receipt.json --json
```

سجلات المستهلك خاصة بشكل افتراضي. استخدم `--public` فقط عندما تريد سجلًا عامًا
سجل المستهلك. تختار الخدمة مفتاح توقيع المستهلك؛ `--algorithm`،
`--issuer-id` و `--key-id` هما خياران لمساحة العمل ويتم رفضهما في وضع المستهلك.

## التحقق من سجل وملف

استخدم الإيصال المحفوظ والملف الأصلي. يوفر الإيصال البايتات الدقيقة
التي تم توقيعها؛ يوفر الملف بصمة الإصبع للمقارنة:

```sh theme={null}
truthlock-protect verify --receipt ./report.receipt.json --file ./report.pdf --json
```

لسجل المستهلك الحالي، يمكنك إعادة بناء personal-record-v2 المحدد الخاص به
الحمولة من الملف الأصلي:

```sh theme={null}
truthlock-protect verify YOUR_ATTESTATION_UUID --personal-record --file ./design.png --json
```

يتم هذا إعادة البناء تلقائيًا عند استخدام رمز مميز للمستهلك فقط مع `--file`.
لا يعيد بناء مطالبات مساحة العمل التعسفية أو تنسيقات الحمولة التاريخية.
لسجل مساحة عمل بدون إيصال محفوظ، قم بتوفير الحمولة الموقعة الأصلية
بايت باستخدام `--payload-file ./signed-payload.json`. لا تقم بإعادة تنسيق JSON هذا.

يتطلب رمز الخروج 0 كلاً من `verdict: VALID` و `signature_verified: true`.
تخرج الملفات المعدلة والإثباتات غير المكتملة بقيمة غير صفرية. لا يمكن لعملية بحث بالمعرف فقط التحقق
توقيع؛ فإنه يبلغ عن `INCOMPLETE` ما لم يتم تطبيق حالة أقوى مثل الإلغاء:

```sh theme={null}
truthlock-protect verify YOUR_ATTESTATION_UUID --json
```

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

## الأوامر

| الأمر | الغرض |
| - | - |
| `protect <file>` / `p <file>` | تسجيل بصمة ملف عادي واحد. |
| `verify [id] --receipt <path> --file <path>` | تحقق من الحمولة الموقعة المحتفظ بها وقارن بايتات الملف الأصلي. |
| `list [--limit 20] [--json]` | قراءة السجلات المتاحة للحساب المكوّن. |
| `whoami` | تحقق من الوصول إلى مساحة العمل أو معلومات حساب المستهلك. |
| `login --token <token>` | حفظ رمز المستهلك محليًا. تتجنب متغيرات البيئة حفظه. |
| `logout` | إزالة رمز المستهلك المحفوظ؛ تظل متغيرات البيئة وبيانات اعتماد مساحة العمل. |
| `register --email <email>` | تسجيل مساحة عمل للمطور وحفظ مفتاح API الخاص ببيئة الاختبار المعزولة. |

تسجيل المطور هو عملية إنشاء حساب منفصلة. لا ينشئ
جلسة مستهلك أو ضمان توفير مفتاح إصدار/توقيع بالفعل.

## الخيارات والتخزين المحلي

`protect` يقبل `--title`، `--description`، `--category`، `--content-type`، `--json`،
`--api-key`، `--issuer-id`، `--key-id`، `--algorithm`، `--idempotency-key` و `--output`.
`--public` و `--private` ينطبقان فقط على المستهلكين. يتم الكشف عن فئة الملف تلقائيًا ما لم يتم توفيرها. لا يتم دعم الدلائل.

لا يزال المتغير التاريخي `TRUTHLOCK_API_KEY` مقبولاً. علامات مفتاح API الصريحة
ومتغيرات البيئة لها الأولوية على مفتاح المطور المحفوظ. مفتاح صريح
متغير بيئة رمز المستهلك له الأولوية على مفتاح المطور المحفوظ عندما
لم يتم توفير متغير بيئة مفتاح API.

يعيش رمز المستهلك المحفوظ في `~/.truthlock/config.json`؛ تعيش بيانات اعتماد المطور
في `~/.truthlocks/credentials.json`. هذه ملفات اعتماد محلية. احتفظ بها بعيدًا
من المستودعات والنسخ الاحتياطية المخصصة للنشر.

## استكشاف الأخطاء وإصلاحها

| الرسالة أو النتيجة | الخطوة التالية |
| - | - |
| لا توجد بيانات اعتماد | قم بتكوين بيانات الاعتماد لنوع الحساب المقصود. |
| اختر مُصدرًا أو مفتاحًا | قم بتوفير المعرفات المعروضة في وحدة التحكم؛ تأكد من أن المفتاح يمكنه التوقيع. |
| عدم تطابق البيئة | طابق مفاتيح الاختبار/الإنتاج مع مضيف API الصحيح. |
| تتم إدارة مفاتيح توقيع المستهلك | إزالة العلامات الخاصة بمساحة العمل فقط أو استخدام مفتاح API لمساحة العمل. |
| `INCOMPLETE` | قم بتوفير الإيصال المحفوظ أو الحمولة الموقعة بالضبط؛ المعرف أو تجزئة الملف وحدهما غير كافيين لتوقيعات مساحة العمل. |
| `ALTERED` | تحقق من أنك قدمت الملف الأصلي بالضبط. |
| انتهت مهلة الطلب | تحقق من نتيجة العملية قبل إعادة المحاولة؛ احتفظ بمفتاح إعادة المحاولة الأصلي. |

تستخدم الطلبات مهلة 30 ثانية ويتم إرسالها مرة واحدة. يتم رفض عمليات إعادة التوجيه. حد المعدل
القيم المتبقية لا تُعرض كحصة شهرية.

## الترقية من الإصدار 1.0

يضيف الإصدار 1.1.1 حمولات موقعة محتفظ بها وتحققًا تشفيريًا باستخدام الملفات الأصلية. يصحح الإصدار 1.1 رؤوس مفتاح API، والمستهلك `content_hash`، وتوقيع مساحة العمل، والخاص
إعدادات المستهلك الافتراضية، ومخرجات JSON، وأسماء الأوامر المستعارة، والتحقق الحقيقي. الأمثلة السابقة
التي ادعت أن البحث عن الحماية كان تحققًا تشفيريًا يجب استبدالها.

ترخيص MIT.


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