Denetim: deterministik uyumluluk kanıtı dışa aktarımı

Bir bakışta

Audit modülü, motorun uyumluluk iddiaları veri kümesini uyumluluk denetçilerine uygun, deterministik ve PII’den arındırılmış bir kanıt paketine dönüştürür. Bayt düzeyinde kararlı çıktı için tüm koleksiyonları sıralar, paketi bir şemaya göre doğrular ve kararlı bir sürüme izdüşürebilir.

Kararlılık: deneysel. Dışa aktarıcının kendisi deterministik ve iyi test edilmiştir, ancak tükettiği yukarı akış claims.json veri kümesi, üzerinde çalışılmakta olan bir uyumluluk matrisidir (kendi _status alanı bunu yansıtır). Kanıt boru hattı GA’ya ulaşana kadar, bu modülün çıktısını mühendislik kanıtı olarak değerlendirin, sertifikalı bir tasdik olarak değil.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

AuditExporter tek giriş noktasıdır. buildBundle(), çözümlenmiş bir claims veri kümesi ve bir AuditExportContext alır, ardından bir AuditExportBundle döndürür. buildBundleFromFile(), dosyadan yüklemeyi kolaylaştırır. encode(), paketi JSON’a serileştirir. Oluşturma işlemi saf işlevseldir. Sabit bir AuditExportContext::generatedAt (örneğin SOURCE_DATE_EPOCH aracılığıyla) ve kararlı bir claims veri kümesiyle çıktı, çalıştırmalar arasında bayt düzeyinde aynıdır; çünkü claims[] (standard, clause_id) ölçütüne göre, evidence[] ref_id ölçütüne göre ve clause_hashes[] clause_id ölçütüne göre sıralanır. Yeniden üretilebilirlik profilinin bitwise olmasının nedeni budur.

Paket, türlendirilmiş bir ağaçtır: AuditExportClaim (bir uyumluluk iddiası), AuditExportEvidence (destekleyici kanıt kaydı), AuditExportClauseHash (madde içeriği özeti) ve AuditExportContext (oluşturma bağlamı). Her biri, serileştirme için bir toArray() sunar.

Modül, varsayılan olarak gizliliği esas alır. Kurucu, serileştirmeden önce kanıt meta verisi dizelerini temizleyen bir DefaultPiiSanitiser (bir PiiSanitiser uygulaması) yükler. Farklı bir temizleyici enjekte edilebilir. Dışa aktarıcı; madde karmalarını, kanıt özetlerini ve RAG alıntı bağlantı noktalarını katı, 64 karakterli küçük harfli onaltılık bir SHA-256 desenine göre doğrular ve bir maddede geçerli bir karma ya da değerlendirici meta verisi eksik olduğunda (sessizce geçiştirmek yerine) yapılandırılmış bir uyarı üretir. validateAgainstSchema(), oluşturulan paketi denetler. projectToV1(), kararlı bir v1 izdüşümü üretir. Dışa aktarıcının tasarımı; OWASP ASVS V8.3, NIST CSF 2.0 PR.PT-1, NIST SP 800-53 r5 AU-2/AU-3 ve ISO/IEC 27001 A.12.4 ile hizalıdır — bunlar, kaynakta belgelenen tasarım hizalamalarıdır; parçaya sabitlenmiş normatif iddialar değildir.

API yüzeyi

Sınıf	Temel üyeler	Rol
`AuditExporter`	`buildBundle()`, `buildBundleFromFile()`, `encode()`, `validateAgainstSchema()`, `projectToV1()`	Deterministik paket builder/validator
`AuditExportBundle`	`toArray()`	Birleştirilmiş kanıt paketi
`AuditExportClaim`	`toArray()`	Tek bir uyumluluk iddiası kaydı
`AuditExportEvidence`	`toArray()`	Tek bir destekleyici kanıt kaydı
`AuditExportClauseHash`	`toArray()`	Bir madde içeriği özeti kaydı
`AuditExportContext`	`GENERATOR_VERSION`	Oluşturma bağlamı (determinizm için zaman damgasını sabitleyin)
`PiiSanitiser` (arayüz)	`sanitise(string): string`	Takılabilir kanıt meta verisi temizleyici (`@since 5.2.0`)
`DefaultPiiSanitiser`	`sanitise()`	Varsayılan olarak gizliliği esas alan temizleyici (`@since 5.2.0`)

Tam PHPDoc tablosu için composer docs:generate-api-php -- --module=Audit komutunu çalıştırın.

Kod örneği — hızlı başlangıç

Bir claims dosyasından paket oluşturun ve kodlayın.

<?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));

Kod örneği — üretim

Paketi doğrulayın; şema veya karma uyarılarını kesin engel olarak değerlendirin.

<?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);
    }
}

Sınır durumları ve dikkat edilmesi gerekenler

Determinizm, sabitlenmiş bir AuditExportContext::generatedAt gerektirir. Bu olmadan zaman damgası değişir ve çıktı bayt düzeyinde kararlı olmaz; bu da bitwise profilini geçersiz kılar.
Geçerli 64 karakterlik onaltılık clause_hash ya da değerlendirici meta verisi eksik olan bir madde, sessizce dahil edilmek yerine yapılandırılmış bir uyarıyla atlanır. Uyarıları kontrol edin; atlanan bir madde, geçer durum değil, eksik kanıt anlamına gelir.
Başka birini enjekte etmediğiniz sürece varsayılan PiiSanitiser çalışır. Temizlemeyi devre dışı bırakmak, gizlilik açısından sonuçlar doğuran açık bir tercihtir — düzenlemeye tabi bir dışa aktarımda bunu yapmayın.
validateAgainstSchema(), dönüş değerine göre işlem yapmadığınız sürece yalnızca bilgi sağlar. Üretimde boş olmayan bir sonucu, yayımlamayı engelleyen bir hata olarak değerlendirin.
Paket, girdi veri kümesinin olgunluğunu yansıtır. Geliştirme aşamasındaki bir claims veri kümesi, geliştirme aşamasındaki bir paket üretir; dışa aktarıcı kanıt kalitesini yükseltmez.

Performans

Oluşturma işlemi, iddia ve kanıt kayıtlarının sayısıyla doğrusal ölçeklenir; belirleyici maliyet sıralamadır. buildBundle() içinde G/Ç yoktur (dosya erişimi çağırana aittir). Varsayılan referans iş yükü, 1500 ms duvar süresi / 64 MB tepe bellek bütçesinin oldukça altındadır. Yeniden üretilebilirlik profili, sabitlenmiş bir bağlam ve kararlı bir girdi verildiğinde, tasarım gereği bitwise şeklindedir.

Güvenlik notları

Bu modül, hassas meta veri taşıyabilen uyumluluk kanıtlarını işler. PII temizleme varsayılan olarak açıktır (GDPR Madde 32 uyumu). Dışarıyla paylaşılan herhangi bir paket için bunu açık tutun. Dışa aktarıcı, her özeti ve alıntı bağlantı noktasını katı bir SHA-256 desenine göre doğrular; böylece hatalı biçimlendirilmiş veya kesilmiş bir karma, güvenilmek yerine reddedilir. Girdi olarak kullanılan claims veri kümesini güven kökü olarak değerlendirin: dışa aktarıcı, kendisine verileni olduğu gibi serileştirir; bu nedenle kanıt yalnızca o veri kümesi kadar güvenilirdir. Motor tehdit modeli için /modules/core/security/ bölümüne bakın.

Uyumluluk

Bu modül, herhangi bir PDF spesifikasyonu normatif iddiasında bulunmaz. Uyumluluk hakkında kanıt dışa aktarır; kendisi atıfta bulunulan bir PDF maddesini uygulamaz. Tasarım hizalamaları (OWASP ASVS V8.3, NIST CSF 2.0, NIST SP 800-53 r5, ISO/IEC 27001 A.12.4) kaynakta belgelenmiştir ve kontrol çerçevesi hizalamalarıdır; parçaya sabitlenmiş PDF alıntıları değildir. Paketin raporladığı uyumluluk, /modules/core/conformance/ bölümünde açıklanan oracle ve golden setleri tarafından üretilir ve doğrulanır.

Ayrıca bkz.

Compliance modülü — bu modülün dışa aktardığı iddiaları üretir.
Metadata modülü — XMP denetim alanı yayıcısı, paketi belgenin içine gömer.
Uyumluluk genel bakışı
Motor güvenlik modeli