كيفية تأمين وتوقيع مستندات PDF باستخدام TypeScript

يوضح هذا الدليل كيفية تشفير، تصديق، توقيع، والتحقق من مستندات PDF باستخدام Aspose.PDF FOSS لـ TypeScript. يتعامل Document.Save() وDocument.Open() مع تشفير المفتاح العام إلى شهادات المستلم، بينما يتعامل Document.Certify() وDocument.Sign() وDocument.VerifySignatures() مع التواقيع الرقمية بنمط PAdES. يتطلب Node.js 22 أو أحدث.

دليل خطوة بخطوة

الخطوة 1: تثبيت الحزمة

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build

تحقق من التثبيت عن طريق استيراد الفئة Document في ملف TypeScript جديد — يجب أن يتم حل هذا السطر دون خطأ بمجرد تثبيت الحزمة:

import { Document } from '@asposefoss/pdf';

الخطوة 2: استيراد الفئات المطلوبة

استورد Document لفتح الملف وحفظه وتوقيعه والتحقق منه؛ تمرّر خطوات التوقيع والتشفير أدناه كائنات خيارات بسيطة، لذا لا تحتاج إلى استيرادات إضافية:

import { Document } from '@asposefoss/pdf';

الخطوة 3: تشفير مستند إلى شهادات المستلمين

Document.Save() تقبل خيار encrypt يحمل واحدًا أو أكثر من recipients، كلٌ يُحدد بواسطة شهادة (سلسلة PEM أو بايتات DER)، وalgorithm، وpermissions المشتركة:

const doc = Document.OpenFile('report.pdf');

const bytes = doc.Save({
  encrypt: {
    recipients: [{ certificate: recipientCertPem }],
    algorithm: 'aes256', // 'aes256' (default) | 'aes128' | 'rc4'
    permissions: { copying: false }, // shared across all recipients
  },
});

الخطوة 4: فتح مستند مشفر

مرّر خيار recipient إلى Document.Open() إما بالمفتاح الخاص المطابق والشهادة، أو بحزمة PKCS#12:

const opened = Document.Open(bytes, {
  recipient: { privateKey, certificate: recipientCertPem },
  // or: recipient: { pkcs12: p12Bytes, passphrase: '…' },
});

console.log(opened.Permissions); // recovered permission flags (not enforced)

الخطوة 5: تصديق وتوقيع مستند

Document.Certify() وDocument.Sign() كلاهما غير متزامنان ويأخذان هوية (certificate + privateKey) بالإضافة إلى خيارات تصف حقل التوقيع والمظهر والسبب. يجب أن يتم التصديق أولاً، على كامل الملف؛ ثم تُضاف توقيعات الموافقة الإضافية تدريجيًا بعد ذلك:

async function certifyAndSign(sourcePath: string, signaturePageIndex: number): Promise<void> {
  const certifying = Document.OpenFile(sourcePath);
  await certifying.Certify(
    { certificate: authorCert, privateKey: authorKey },
    {
      permissions: 'form-fill',
      reason: 'Certifying the document',
      fieldName: 'Certification',
      appearance: { page: signaturePageIndex, rect: [400, 100, 550, 140] },
    },
  );
  const certifiedBytes = certifying.Save();

  const approving = Document.Open(certifiedBytes);
  await approving.Sign(
    { certificate: approverCert, privateKey: approverKey },
    { reason: 'Approved for publication', fieldName: 'Approval', subFilter: 'PAdES' },
  );
  approving.WriteTo('signed.pdf');
}

الخطوة 6: التحقق من التوقيعات

Document.VerifySignatures() غير متزامن ويعيد SignatureReport واحد لكل حقل توقيع، كلٌ يبلّغ عن التشفيري integrity، وصحة signature، وما إذا كان coversWholeFile:

async function verify(path: string): Promise<void> {
  const doc = Document.OpenFile(path);
  const reports = await doc.VerifySignatures();
  for (const r of reports) {
    console.log(`${r.name}: integrity=${r.integrity} signature=${r.signature} `
      + `coversWholeFile=${r.coversWholeFile} docMDP=${r.docMDP}`);
  }
}

المشكلات الشائعة والحلول

Document.Sign() / Document.Certify() إلقاء أو تعطل. كلاهما غير متزامن — await النداء. النسيان await يترك الـ promise المرتجع غير محلول وتحدث عملية الكتابة قبل إكمال التوقيع.

توقيع الموافقة اللاحق يبطل الشهادة. وقّع بشكل تدريجي: احفظ البايتات المصدّقة أولًا (certifying.Save()), أعد فتحها باستخدام Document.Open(), ثم استدعِ Sign() في ذلك المستند المعاد فتحه — كتابة إعادة كتابة كاملة بدلاً من إلحاق تدريجي تُعطِّل الشهادة /ByteRange الملخص.

VerifySignatures() reports coversWholeFile: false للتوقيع الأول لكن true للأخير. هذا متوقع لسلسلة certify-then- sign: تم توقيع الشهادة قبل إلحاق الموافقة، لذا فقط توقيع الأحدث /ByteRange يمتد إلى نهاية الملف.

فشل فك التشفير بالمفتاح الخاص الصحيح. تأكيد certificate تم تمريره إلى recipient يطابق الشهادة الدقيقة التي تم تشفير المستند إليها في Document.Save()الخاص بـ recipients القائمة — شهادة تم إعادة إصدارها بمفتاح جديد لن تقوم بفك تشفير البيانات المشفرة بالمفتاح القديم.

الأسئلة المتكررة

هل يمكن تشفير مستند لأكثر من مستلم؟

نعم — recipients في خيار encrypt الخاص بـ Document.Save() يقبل مصفوفة؛ أي مفتاح خاص يطابق المستلم يمكنه فتح الملف الناتج.

ما هو تنسيق التوقيع الذي ينتجه `Document.Sign()`؟

تمرير subFilter: 'PAdES' في خيارات التوقيع ينتج توقيعًا متوافقًا مع PAdES؛ إهماله يستخدم الفلتر الفرعي الافتراضي للتوقيع في المكتبة.

كيف يمكنني التحقق مما إذا كان المستند مُصدقًا أم مجرد موقع؟

افحص الحقل docMDP على SignatureReport الذي تُرجعه Document.VerifySignatures() — توقيع الشهادة يُبلغ عن حكم إذن DocMDP; التوقيع الذي يقتصر على الموافقة لا يفعل ذلك.

هل يتم تطبيق `Permissions` المستردة بعد `Document.Open()` بواسطة المكتبة؟

لا — opened.Permissions يُبلغ عن علامات الأذونات المسجلة في الملف المشفر للفحص؛ تطبيقها في التطبيق هو مسؤولية المستدعي.