‏⁨Contracts⁩ — مرجع متعمّق

لمحة سريعة

وحدة ⁨Contracts⁩ هي وصلة التكامل في ⁨Enterprise⁩ لعملاء سلطة الطوابع الزمنية ⁨RFC 3161⁩ (Time Stamp Authority).

• TsaClientInterface يُعلِن عمليةً واحدة: طلب ⁨TimeStampToken⁩ مُرمَّز بصيغة ⁨DER⁩ من أجل بصمة مستند محسوبة مسبقًا.
• TsaClientAdapter يجسر عميل الطوابع الزمنية في ⁨Core⁩ — وهو صنف final — إلى تلك الواجهة دون تغيير السلوك.
• مكوّنات ⁨Enterprise⁩ مثل LtvManager وDocumentTimestamp تقبل الواجهة، فيصبح سلوك ⁨TSA⁩ قابلًا للحقن والاستبدال في الاختبارات.
• لا يعبر الوصلةَ سوى بصمة المستند؛ ولا يعبرها محتوى المستند إطلاقًا.

للحصول على إرشادات سير العمل، اقرأ أولًا صفحة قدرة ⁨Contracts⁩.

التوفّر والترخيص

تُشحن هذه القدرة ضمن ‏⁨NextPDF Enterprise⁩ (nextpdf/enterprise) وتُفعَّل بمظروف ترخيص من فئة ⁨Enterprise⁩. النشر الذي يفتقر إلى ذلك الاستحقاق لا يُحمِّل أصناف القدرة. قارن الإصدارات واحصل على ترخيص.

الواجهة لا تؤدي أي عمل ولا تبوّب أي شيء بذاتها. تفرض أسطح ⁨Enterprise⁩ المستهلِكة رموز قدراتها الخاصة، مثل enterprise.compliance.evidence على سطح أدلة الامتثال.

الفئة	يوفّر
Core	صنف TsaClient ملموس (final) يؤدي طلبات ⁨RFC 3161⁩
Pro	لا يوجد مكافئ في وحدة ⁨Contracts⁩
Enterprise	وصلة TsaClientInterface وجسر TsaClientAdapter

composer require nextpdf/enterprise:^3

سطح واجهة برمجة التطبيقات العامة

الرمز	المُعامِلات	السلوك الافتراضي	يُرجِع	يرمي أو يفشل بـ	ملاحظات
TsaClientInterface::getDocumentTimestamp()	string $documentHash	يُعلِن طلب طابع زمني لبصمة مستند محسوبة مسبقًا	string — ⁨TimeStampToken⁩ مُرمَّز بصيغة ⁨DER⁩	مُعرَّف حسب التنفيذ؛ الواجهة لا تُعلِن أي استثناء	العملية الوحيدة؛ يوثّق المصدر مُدخل بصمة ⁨SHA-256⁩
TsaClientAdapter::__construct()	TsaClient $client	يخزّن عميل الطوابع الزمنية في ⁨Core⁩	TsaClientAdapter	لا شيء مُعلَن	final readonly؛ ترقية مُعامِلات الباني
TsaClientAdapter::getDocumentTimestamp()	string $documentHash	يُمرِّر إلى TsaClient::getDocumentTimestamp() دون تغيير	string — ⁨TimeStampToken⁩ مُرمَّز بصيغة ⁨DER⁩	TsaException من عميل ⁨Core⁩، مُمرَّر دون تغيير	لا يضيف سلوكًا؛ ولا يبتلع شيئًا

namespace NextPDF\Enterprise\Contracts;

interface TsaClientInterface
{
    /**
     * Request a timestamp token for a document hash.
     *
     * @param string $documentHash SHA-256 digest of the document content
     *
     * @return string DER-encoded TimeStampToken
     */
    public function getDocumentTimestamp(string $documentHash): string;
}

namespace NextPDF\Enterprise\Contracts;

use NextPDF\Security\Timestamp\TsaClient;

final readonly class TsaClientAdapter implements TsaClientInterface
{
    public function __construct(
        private TsaClient $client,
    )

    public function getDocumentTimestamp(string $documentHash): string
}

عقد السلوك

TsaClientInterface::getDocumentTimestamp(string $documentHash): string يُرجِع ⁨TimeStampToken⁩ من ⁨RFC 3161⁩ مُرمَّزًا بصيغة ⁨DER⁩ مقابل بصمة مستند. القواعد القابلة للملاحظة خارجيًا:

• تُعلِن الواجهة عمليةً واحدة؛ وهي لا تتحقق من الطابع، ولا تكفل ⁨TSA⁩، ولا تدّعي أثرًا قانونيًا.
• TsaClientAdapter يُمرِّر الاستدعاء إلى عميل الطوابع الزمنية في ⁨Core⁩ دون تغيير — لا سلوك مضاف، ولا محاولات إعادة مضافة، ولا استثناءات مبتلَعة، ولا ضمانات إضافية. غرضه الوحيد هو تمكين عميل ⁨Core⁩ من نوع final من تلبية واجهة موجَّهة إلى ⁨Enterprise⁩ لأجل عكس الاعتمادية والاختبار.
• لا يعبر الحدَّ سوى بصمة المستند؛ ولا يُمرَّر أي محتوى للمستند.
• خلف المُهايئ، يرفض عميل ⁨Core⁩ أي بصمة لا يطابق طولها خوارزمية البصمة المُهيّأة لديه، فيرمي TsaException، بفشل مُغلق، قبل أي نشاط شبكي. فالبصمة المُوسَّمة خطأً كانت لولا ذلك ستُنتج طابعًا لا يستطيع أي مُدقِّق متوافق ربطه.
• الأسطح المستهلِكة: LtvManager يقبل TsaClientInterface اختياريًا ويشترطه لأجل ⁨PAdES B-LTA⁩. وDocumentTimestamp يستخدم العقد لملء /Contents في قاموس توقيع /DocTimeStamp. أما مُنفِّذ تجديد أرشيف ⁨LTV⁩ (LtvaRenewalExecutor) فيربط TsaClientAdapter حول عميل ⁨Core⁩ عند تجديد الطوابع الزمنية للمستندات.

الحالات الحدّية وأنماط الفشل

• يُمرِّر المُهايئ الاستثناءات من العميل الأساسي دون تغيير؛ ويجب معالجة إخفاقات ⁨TSA⁩ عند موضع الاستدعاء.
• يجب أن تكون البصمة بيانات ثنائية خام وفق خوارزمية البصمة المُهيّأة للعميل الملموس (الافتراضي ⁨SHA-256⁩، 32 بايت). البصمة المُرمَّزة ستّ عشريًا لها طول خاطئ وتُرفض قبل إرسال أي طلب.
• الطابع المُرجَع هو بايتات لا حكم؛ فتحقّق منه حيثما لزم.
• التنفيذ المخصص يملك سطح فشله الخاص. والعقد يثبّت شكل الإرجاع فقط: ⁨TimeStampToken⁩ مُرمَّز بصيغة ⁨DER⁩.

سلوك وضع ⁨FIPS⁩

هذه الوحدة لا تؤدي أي عمليات تعمية. اختيار الخوارزمية وسلوك وضع ⁨FIPS⁩ يحكمهما عميل ⁨TSA⁩ الملموس ووحدة ⁨Security⁩. راجع المرجع المتعمّق لـ FIPS 140.

المطابقة

السلوك	المرجع
طلب الطابع الزمني وربطه	IETF RFC 3161 §2
تحمل ⁨TimeStampReq⁩ حقل ⁨MessageImprint⁩: مُعرِّف خوارزمية تجزئة وبصمة البيانات المراد ختمها زمنيًا	IETF RFC 3161 §2.4.1
يجب أن يساوي حقل messageImprint في الطابع قيمة الطلب، مع مطابقة حجم البصمة للخوارزمية المُعرَّفة	IETF RFC 3161 §2.4.2

العقد مُصاغ حول ⁨RFC 3161⁩؛ أما طلب الطابع الفعلي وأي تحقق فيؤديهما العميل الملموس وأسطح ⁨Evidence/Signature⁩. الواجهة لا تقدّم أي ادّعاء مطابقة أو تصديق. ‏⁨NextPDF⁩ لا يقدّم أي ادّعاء اعتماد.

ملاحظات التطوير

• كلا النوعين يحمل @since 3.0.0؛ ويوثّق هذا المرجع السطح كما شُحن في nextpdf/enterprise 3.1.0.
• احقن TsaClientInterface في المكوّنات التي تحتاج طوابع زمنية؛ واربط TsaClientAdapter، أو تنفيذًا مخصصًا، عند جذر التركيب. واستبدل بديلًا اختباريًا في اختبارات الوحدة بدلًا من ⁨TSA⁩ حيّ.
• المُشغِّل يملك عميل ⁨TSA⁩ الملموس خلف المُهايئ: فمكان الإقامة، وحدود الثقة لنقطة نهاية ⁨TSA⁩، والتحقق من سلسلة الشهادات تنطبق على ذلك العميل، لا على هذه الواجهة.
• لا ينطبق أي قيد لضبط التصدير على سطح العقد هذا. والحصول على طابع زمني يدعم سير عمل التدقيق والتحقق طويل الأمد؛ وهو ليس تصديقًا قانونيًا ولا اعتمادًا. وهذا المرجع ليس رأيًا قانونيًا.
• تفاصيل الآلية الداخلية تبقى في التوثيق الداخلي لمستودع المصدر وهي خارج نطاق هذا الدليل.

حدود النشر

توثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وسطح واجهة برمجة التطبيقات العامة المدعوم فقط. أما مسارات فضاءات الأسماء الداخلية، والأصناف المساعِدة، وجداول الآلية، وأسماء ملفات كتيّبات التشغيل، وبادئات التذاكر فهي خارج النطاق.

انظر أيضًا

• ‏⁨Contracts⁩ — صفحة القدرة
• ‏⁨Evidence⁩ — مرجع متعمّق
• ‏⁨Archive⁩ — مرجع متعمّق
• ‏⁨Validation⁩ — مرجع متعمّق
• المواصفات: ⁨PAdES⁩