Audit: deterministyczny eksport dowodów zgodności

W skrócie

Moduł Audit przekształca zbiór deklaracji zgodności silnika w deterministyczny, oczyszczony z danych PII pakiet dowodów przeznaczony dla audytora zgodności. Sortuje każdą kolekcję, aby wynik był stabilny bajtowo, waliduje pakiet względem schematu i może rzutować go na stabilną wersję.

Stabilność: eksperymentalna. Sam eksporter jest deterministyczny i dobrze przetestowany, ale nadrzędny zbiór danych claims.json, który przetwarza, jest nieukończoną macierzą zgodności (odzwierciedla to jego własne pole _status). Dopóki potok dowodów nie osiągnie wersji GA, traktuj wynik modułu jako dowód inżynierski, a nie certyfikowane poświadczenie.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

AuditExporter to jedyny punkt wejścia. buildBundle() przyjmuje zdekodowany zbiór danych claims oraz AuditExportContext i zwraca AuditExportBundle. buildBundleFromFile() to wygodna metoda pomocnicza ładująca dane z pliku. encode() serializuje pakiet do formatu JSON. Proces budowania jest czysto funkcyjny. Przy ustalonym AuditExportContext::generatedAt (na przykład za pomocą SOURCE_DATE_EPOCH) oraz stabilnym zbiorze danych claims wynik jest identyczny bajtowo w kolejnych uruchomieniach, ponieważ claims[] są sortowane według (standard, clause_id), evidence[] według ref_id, a clause_hashes[] według clause_id. Dlatego profil odtwarzalności to bitwise.

Pakiet jest typowanym drzewem: AuditExportClaim (deklaracja zgodności), AuditExportEvidence (rekord dowodu potwierdzającego), AuditExportClauseHash (skrót treści klauzuli) oraz AuditExportContext (kontekst generowania). Każdy typ udostępnia metodę toArray() do serializacji.

Moduł działa zgodnie z zasadą privacy-by-default (prywatność domyślnie). Konstruktor ustawia DefaultPiiSanitiser (implementację PiiSanitiser), który oczyszcza ciągi znaków w metadanych dowodów przed serializacją. Można wstrzyknąć inny sanitizer. Eksporter waliduje skróty klauzul, skróty dowodów oraz kotwice cytowań RAG względem rygorystycznego wzorca SHA-256 składającego się z 64 znaków szesnastkowych zapisanych małymi literami i emituje ustrukturyzowane ostrzeżenie (zamiast cichego pominięcia), gdy klauzuli brakuje prawidłowego skrótu lub metadanych ewaluatora. validateAgainstSchema() sprawdza zbudowany pakiet. projectToV1() tworzy stabilną projekcję v1. Projekt eksportera jest zgodny z OWASP ASVS V8.3, NIST CSF 2.0 PR.PT-1, NIST SP 800-53 r5 AU-2/AU-3 oraz ISO/IEC 27001 A.12.4 — są to zgodności projektowe udokumentowane w źródle, a nie deklaracje normatywne przypięte do fragmentów.

Powierzchnia API

Klasa	Kluczowe składowe	Rola
AuditExporter	buildBundle(), buildBundleFromFile(), encode(), validateAgainstSchema(), projectToV1()	Deterministyczny builder/validator pakietu
AuditExportBundle	toArray()	Złożony pakiet dowodów
AuditExportClaim	toArray()	Pojedynczy rekord deklaracji zgodności
AuditExportEvidence	toArray()	Pojedynczy rekord dowodu potwierdzającego
AuditExportClauseHash	toArray()	Rekord skrótu treści klauzuli
AuditExportContext	GENERATOR_VERSION	Kontekst generowania (ustal znacznik czasu dla determinizmu)
PiiSanitiser (interfejs)	sanitise(string): string	Wymienny mechanizm oczyszczający metadane dowodów (@since 5.2.0)
DefaultPiiSanitiser	sanitise()	Mechanizm oczyszczający działający zgodnie z zasadą privacy-by-default (@since 5.2.0)

Uruchom composer docs:generate-api-php -- --module=Audit, aby uzyskać pełną tabelę PHPDoc.

Przykład kodu — szybki start

Zbuduj pakiet na podstawie pliku claims i zakoduj go.

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

Przykład kodu — produkcja

Zwaliduj pakiet i traktuj ostrzeżenia dotyczące schematu lub skrótów jako twardy warunek blokujący.

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

Przypadki brzegowe i pułapki

• Determinizm wymaga ustalonego AuditExportContext::generatedAt. Bez tego znacznik czasu będzie się zmieniał, a wynik nie będzie stabilny bajtowo, co niweczy profil bitwise.
• Klauzula bez prawidłowego clause_hash o długości 64 znaków szesnastkowych lub bez metadanych ewaluatora jest pomijana wraz z ustrukturyzowanym ostrzeżeniem, a nie po cichu dołączana. Sprawdzaj ostrzeżenia; pominięta klauzula oznacza brakujący dowód, a nie wynik pozytywny.
• Domyślny PiiSanitiser pozostaje aktywny, dopóki nie wstrzykniesz innego. Wyłączenie oczyszczania to świadoma decyzja niosąca konsekwencje dla prywatności — nie rób tego w przypadku eksportu objętego regulacjami.
• validateAgainstSchema() ma charakter doradczy, dopóki nie zareagujesz na zwrócony wynik. W środowisku produkcyjnym traktuj niepusty wynik jako błąd blokujący publikację.
• Pakiet odzwierciedla dojrzałość wejściowego zbioru danych. Niedokończony zbiór danych claims daje niedokończony pakiet; eksporter nie podnosi jakości dowodów.

Wydajność

Budowanie ma złożoność liniową względem liczby deklaracji i rekordów dowodów, a kosztowo dominuje w nim sortowanie. W buildBundle() nie ma operacji wejścia-wyjścia (dostęp do pliku należy do wywołującego). Domyślne obciążenie referencyjne mieści się z dużym zapasem w budżecie 1500 ms czasu rzeczywistego / 64 MB szczytowego zużycia pamięci. Profil odtwarzalności ma z założenia wartość bitwise przy ustalonym kontekście i stabilnym wejściu.

Uwagi dotyczące bezpieczeństwa

Ten moduł obsługuje dowody zgodności, które mogą zawierać wrażliwe metadane. Oczyszczanie danych PII jest domyślnie włączone (zgodność z GDPR Art. 32). Pozostaw je włączone dla każdego pakietu udostępnianego na zewnątrz. Eksporter waliduje każdy skrót i każdą kotwicę cytowania względem rygorystycznego wzorca SHA-256, dzięki czemu zniekształcony lub obcięty skrót jest odrzucany, a nie traktowany jako zaufany. Traktuj wejściowy zbiór danych claims jako korzeń zaufania: eksporter wiernie serializuje to, co otrzymuje, więc dowody są tak wiarygodne, jak ten zbiór danych. Zobacz model zagrożeń silnika w /modules/core/security/.

Zgodność

Ten moduł nie formułuje żadnej deklaracji normatywnej dotyczącej specyfikacji PDF. Eksportuje dowody dotyczące zgodności; sam nie implementuje cytowanej klauzuli PDF. Jego zgodności projektowe (OWASP ASVS V8.3, NIST CSF 2.0, NIST SP 800-53 r5, ISO/IEC 27001 A.12.4) są udokumentowane w źródle i są zgodnościami z frameworkami kontrolnymi, a nie cytowaniami PDF przypiętymi do fragmentów. Zgodność, którą pakiet raportuje, jest wytwarzana i walidowana przez oracle oraz złote zestawy testów opisane w /modules/core/conformance/.

Zobacz także

• Moduł Compliance — wytwarza deklaracje, które ten moduł eksportuje.
• Moduł Metadata — generator pól audytu XMP osadza pakiet w dokumencie.
• Przegląd zgodności
• Model bezpieczeństwa silnika