التدقيق: تصدير حتمي لأدلة الامتثال

لمحة سريعة

تحوّل وحدة ⁨Audit⁩ مجموعة بيانات ادعاءات المطابقة الخاصة بالمحرك إلى حزمة أدلة حتمية ومنقّاة من معلومات التعريف الشخصية تصلح لمدقّق امتثال. وترتّب كل مجموعة لإنتاج مخرجات ثابتة على مستوى البايت، وتتحقق من الحزمة وفق مخطط، ويمكنها إسقاط الحزمة إلى إصدار مستقر.

الاستقرار: تجريبي. أداة التصدير نفسها حتمية ومُختبَرة جيدًا، لكن مجموعة بيانات claims.json الأولية التي تستهلكها لا تزال مصفوفة مطابقة قيد العمل (يعكس حقل _status الخاص بها ذلك). إلى أن يبلغ مسار الأدلة مرحلة ⁨GA⁩، عامِل مخرجات هذه الوحدة على أنها أدلة هندسية لا شهادة مُصادَقًا عليها.

التثبيت

composer require nextpdf/core:^3

نظرة مفاهيمية عامة

يمثّل AuditExporter نقطة الدخول الوحيدة. تأخذ buildBundle() مجموعة بيانات ادعاءات بعد فك ترميزها إلى جانب كائن AuditExportContext وتُعيد كائن AuditExportBundle. buildBundleFromFile() هي الدالة المُيسِّرة لتحميل الملف. تُسلسِل encode() الحزمة إلى ⁨JSON.⁩ عملية البناء وظيفية صرفة. عند تثبيت AuditExportContext::generatedAt (على سبيل المثال عبر SOURCE_DATE_EPOCH) واستخدام مجموعة بيانات ادعاءات مستقرة، تكون المخرجات متطابقة على مستوى البايت عبر مرات التشغيل لأن claims[] مرتّبة حسب (standard, clause_id)، وevidence[] حسب ref_id، وclause_hashes[] حسب clause_id. لذلك يكون ملف تعريف قابلية إعادة الإنتاج bitwise.

الحزمة شجرة مُحدَّدة الأنواع: AuditExportClaim (ادعاء مطابقة)، وAuditExportEvidence (سجل الأدلة الداعمة)، وAuditExportClauseHash (ملخص محتوى البند)، وAuditExportContext (سياق التوليد). ويتضمن كل نوع منها دالة toArray() لأغراض التسلسل.

تحمي الوحدة الخصوصية افتراضيًا. يُثبّت المُنشئ كائن DefaultPiiSanitiser (تطبيق لواجهة PiiSanitiser) لتنقية سلاسل البيانات الوصفية للأدلة قبل التسلسل. ويمكن حقن مُنقٍّ مختلف. تتحقق أداة التصدير من تجزئات البنود وملخصات الأدلة ومراسي اقتباس ⁨RAG⁩ وفق نمط ⁨SHA-256⁩ صارم مكوّن من 64 حرفًا سداسيًا بأحرف صغيرة، وتُصدر تحذيرًا مُنظَّمًا (بدلًا من الإسقاط الصامت) عندما يفتقر بند إلى تجزئة صالحة أو بيانات وصفية للمُقيِّم. تتحقق validateAgainstSchema() من الحزمة المبنية. تُنتج projectToV1() إسقاط ⁨v1⁩ مستقرًّا. يتوافق تصميم أداة التصدير مع ⁨OWASP ASVS V8.3⁩ و‏⁨NIST CSF 2.0 PR.PT-1⁩ و⁨NIST SP 800-53 r5 AU-2/AU-3⁩ و⁨ISO/IEC 27001 A.12.4⁩ — وهذه توافقات تصميمية مُوثَّقة في المصدر، وليست ادعاءات معيارية مُثبَّتة بمقاطع.

واجهة ⁨API⁩

الفئة	الأعضاء الرئيسية	الدور
`AuditExporter`	`buildBundle()`، `buildBundleFromFile()`، `encode()`، `validateAgainstSchema()`، `projectToV1()`	باني/مُدقِّق حتمي للحزمة ⁨builder/validator⁩
`AuditExportBundle`	`toArray()`	حزمة الأدلة المُجمَّعة
`AuditExportClaim`	`toArray()`	سجل ادعاء مطابقة واحد
`AuditExportEvidence`	`toArray()`	سجل أدلة داعمة واحد
`AuditExportClauseHash`	`toArray()`	سجل ملخّص لمحتوى البند
`AuditExportContext`	`GENERATOR_VERSION`	سياق التوليد (ثبّت الطابع الزمني لتحقيق الحتمية)
`PiiSanitiser` (واجهة)	`sanitise(string): string`	منقٍّ قابل للتوصيل لبيانات الأدلة الوصفية (`@since 5.2.0`)
`DefaultPiiSanitiser`	`sanitise()`	منقٍّ يحمي الخصوصية افتراضيًا (`@since 5.2.0`)

شغّل composer docs:generate-api-php -- --module=Audit للحصول على جدول ⁨PHPDoc⁩ الكامل.

نموذج برمجي — بداية سريعة

ابنِ حزمة ورمّزها من ملف ادعاءات.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Audit\AuditExportContext;
use NextPDF\Audit\AuditExporter;

$exporter = new AuditExporter();

$bundle = $exporter->buildBundleFromFile(
    '/srv/nextpdf/claims.json',
    new AuditExportContext(/* pin generatedAt for determinism */),
);

file_put_contents('/srv/out/audit-bundle.json', $exporter->encode($bundle));

نموذج برمجي — بيئة الإنتاج

تحقق من الحزمة وعامِل تحذيرات المخطط أو التجزئة على أنها بوابة صارمة.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Audit\AuditExportContext;
use NextPDF\Audit\AuditExporter;
use Psr\Log\LoggerInterface;

final readonly class EvidenceGate
{
    public function __construct(
        private AuditExporter $exporter,
        private LoggerInterface $logger,
    ) {}

    /** @param array<string, mixed> $claims Decoded claims dataset. */
    public function export(array $claims, AuditExportContext $context): string
    {
        $bundle = $this->exporter->buildBundle($claims, $context);
        $errors = $this->exporter->validateAgainstSchema($bundle->toArray());

        if ($errors !== []) {
            $this->logger->error('Audit bundle failed schema validation.', ['errors' => $errors]);

            throw new \RuntimeException('Audit evidence bundle is not schema-valid; refusing to publish.');
        }

        return $this->exporter->encode($bundle);
    }
}

الحالات الحدّية والمزالق

تتطلب الحتمية تثبيت AuditExportContext::generatedAt. فبدونه يتغير الطابع الزمني، ولا تبقى المخرجات ثابتة على مستوى البايت، ما يُبطل ملف تعريف bitwise.
البند الذي يفتقر إلى clause_hash صالح مكوّن من 64 رمزًا سداسيًا أو إلى بيانات وصفية للمُقيِّم يُتخطّى مع تحذير مُنظَّم، ولا يُدرَج بصمت. راجع التحذيرات؛ فالبند المُتخطَّى دليل مفقود، وليس حالة اجتياز.
يعمل PiiSanitiser الافتراضي ما لم تحقن غيره. تعطيل التنقية خيار صريح له تبعات على الخصوصية — لا تفعله في عملية تصدير خاضعة للتنظيم.
تُعدّ validateAgainstSchema() استشارية ما لم تتصرف بناءً على ما تُعيده. عامِل أي نتيجة غير فارغة على أنها خطأ يحجب النشر في بيئة الإنتاج.
تعكس الحزمة مدى نضج مجموعة بيانات الإدخال. إذا كانت مجموعة بيانات الادعاءات قيد العمل، فستكون الحزمة كذلك؛ فأداة التصدير لا ترفع جودة الأدلة.

الأداء

عملية البناء خطية بالنسبة إلى عدد الادعاءات وسجلات الأدلة، وتغلب عليها كلفة الترتيب. لا توجد عمليات إدخال/إخراج في buildBundle() (المُستدعي هو من يملك الوصول إلى الملفات). يقع حِمل العمل المرجعي الافتراضي بسهولة داخل ميزانية 1500 ⁨ms⁩ للزمن الفعلي / 64 ⁨MB⁩ للذروة. ملف تعريف قابلية إعادة الإنتاج هو bitwise عند تثبيت السياق واستقرار الإدخال، وذلك بحكم التصميم.

ملاحظات أمنية

تتعامل هذه الوحدة مع أدلة امتثال قد تحمل بيانات وصفية حساسة. تنقية معلومات التعريف الشخصية مُفعّلة افتراضيًا (بمحاذاة المادة 32 من ⁨GDPR⁩). أبقها مُفعّلة لأي حزمة تُشارَك خارجيًا. تتحقق أداة التصدير من كل ملخص ومرسى اقتباس وفق نمط ⁨SHA-256⁩ صارم، فتُرفض أي تجزئة مُشوَّهة أو مبتورة بدلًا من الوثوق بها. عامِل مجموعة بيانات الادعاءات المُدخَلة على أنها جذر الثقة: فأداة التصدير تُسلسِل ما يُعطى لها بأمانة، ولا تكون الأدلة جديرة بالثقة إلا بقدر ثقة تلك المجموعة. راجع نموذج تهديد المحرك في /modules/core/security/.

المطابقة

لا تؤكد هذه الوحدة أي ادعاء معياري من مواصفة ⁨PDF.⁩ إنها تُصدّر أدلة عن المطابقة؛ وهي لا تُنفّذ بنفسها أي بند ⁨PDF⁩ مُستشهَد به. توافقاتها التصميمية (⁨OWASP ASVS V8.3⁩ و‏⁨NIST CSF 2.0⁩ و⁨NIST SP 800-53 r5⁩ و⁨ISO/IEC 27001 A.12.4⁩) مُوثَّقة في المصدر، وهي توافقات مع أطر الضوابط، وليست استشهادات ⁨PDF⁩ مُثبَّتة بمقاطع. أما المطابقة التي تُبلّغ عنها الحزمة فتُنتجها وتتحقق منها مجموعات الاختبار المرجعية والذهبية الموصوفة في /modules/core/conformance/.

انظر أيضًا

وحدة ⁨Compliance⁩ — تُنتج الادعاءات التي تصدّرها هذه الوحدة.
وحدة ⁨Metadata⁩ — أداة لإصدار حقل تدقيق ⁨XMP⁩ يُضمِّن الحزمة داخل المستند.
نظرة عامة على المطابقة
نموذج أمان المحرك