Audit: deterministische export van compliancebewijs

In het kort

De Audit-module zet de dataset met conformiteitsclaims van de engine om in een deterministische, PII-geschoonde bewijsbundel die geschikt is voor een compliance-auditor. De module sorteert elke verzameling voor byte-stabiele uitvoer, valideert de bundel aan de hand van een schema en kan de bundel naar een stabiele versie projecteren.

Stabiliteit: experimenteel. De exporter zelf is deterministisch en goed getest, maar de upstream claims.json-dataset die de module verwerkt, is een conformiteitsmatrix die nog in ontwikkeling is (zoals de eigen _status aangeeft). Totdat de bewijspijplijn GA bereikt, geldt de uitvoer van deze module als technisch bewijs, niet als een gecertificeerde verklaring.

Installatie

composer require nextpdf/core:^3

Conceptueel overzicht

AuditExporter is het enige toegangspunt. buildBundle() neemt een gedecodeerde claims-dataset plus een AuditExportContext en retourneert een AuditExportBundle. buildBundleFromFile() is de gemaksvariant die het bestand inleest. encode() serialiseert de bundel naar JSON. Het bouwen is puur functioneel. Met een vaste AuditExportContext::generatedAt (bijvoorbeeld via SOURCE_DATE_EPOCH) en een stabiele claims-dataset blijft de uitvoer in alle runs byte-identiek, omdat claims[] wordt gesorteerd op (standard, clause_id), evidence[] op ref_id en clause_hashes[] op clause_id. Daarom is het reproduceerbaarheidsprofiel bitwise.

De bundel is een getypeerde boomstructuur: AuditExportClaim (een conformiteitsclaim), AuditExportEvidence (het ondersteunende bewijsrecord), AuditExportClauseHash (de digest van de clausule-inhoud) en AuditExportContext (de generatiecontext). Elke klasse biedt een toArray() voor serialisatie.

De module is privacy-by-default. De constructor installeert een DefaultPiiSanitiser (een implementatie van PiiSanitiser) die bewijsmetadata-strings vóór serialisatie opschoont. Er kan een andere sanitiser worden geïnjecteerd. De exporter valideert clausulehashes, bewijsdigests en RAG-citatieankers aan de hand van een strikt SHA-256-patroon van 64 hextekens in kleine letters, en geeft een gestructureerde waarschuwing (in plaats van stil te verwijderen) wanneer bij een clausule een geldige hash of evaluator-metadata ontbreekt. validateAgainstSchema() controleert de opgebouwde bundel. projectToV1() levert een stabiele v1-projectie op. Het ontwerp van de exporter is afgestemd op OWASP ASVS V8.3, NIST CSF 2.0 PR.PT-1, NIST SP 800-53 r5 AU-2/AU-3 en ISO/IEC 27001 A.12.4 — dit zijn ontwerpafstemmingen die in de bron zijn gedocumenteerd, geen aan chunks vastgepinde normatieve claims.

API-oppervlak

Klasse	Belangrijkste members	Rol
`AuditExporter`	`buildBundle()`, `buildBundleFromFile()`, `encode()`, `validateAgainstSchema()`, `projectToV1()`	Deterministische bundel-builder/validator
`AuditExportBundle`	`toArray()`	De samengestelde bewijsbundel
`AuditExportClaim`	`toArray()`	Eén conformiteitsclaim-record
`AuditExportEvidence`	`toArray()`	Eén ondersteunend bewijsrecord
`AuditExportClauseHash`	`toArray()`	Een digest-record van de clausule-inhoud
`AuditExportContext`	`GENERATOR_VERSION`	Generatiecontext (pin het tijdstempel voor determinisme)
`PiiSanitiser` (interface)	`sanitise(string): string`	Pluggable scrubber voor bewijsmetadata (`@since 5.2.0`)
`DefaultPiiSanitiser`	`sanitise()`	Privacy-by-default sanitiser (`@since 5.2.0`)

Voer composer docs:generate-api-php -- --module=Audit uit voor de volledige PHPDoc-tabel.

Codevoorbeeld — Snelle start

Bouw een bundel op basis van een claims-bestand en encodeer die.

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

Codevoorbeeld — Productie

Valideer de bundel en behandel schema- of hash-waarschuwingen als harde blokkades.

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

Randgevallen en valkuilen

Determinisme vereist een gepinde AuditExportContext::generatedAt. Zonder zo’n pin varieert het tijdstempel en is de uitvoer niet byte-stabiel, waardoor het bitwise-profiel teniet wordt gedaan.
Een clausule zonder een geldige 64-hex clause_hash of evaluator-metadata wordt overgeslagen met een gestructureerde waarschuwing, niet stilzwijgend opgenomen. Controleer de waarschuwingen; als een clausule wordt overgeslagen, ontbreekt er bewijs. Dat is geen geslaagde toets.
De standaard PiiSanitiser wordt gebruikt, tenzij er een andere wordt geïnjecteerd. Het uitschakelen van de sanitisatie is een expliciete keuze met privacygevolgen — doe dit niet voor een gereguleerde export.
validateAgainstSchema() is alleen adviserend, tenzij er op basis van de retourwaarde wordt gehandeld. Behandel een niet-leeg resultaat in productie als een fout die publicatie blokkeert.
De bundel weerspiegelt de volwassenheid van de invoerdataset. Een WIP-claims-dataset levert een WIP-bundel op; de exporter verbetert de bewijskwaliteit niet.

Prestaties

Het bouwen is lineair in het aantal claims- en bewijsrecords, en wordt gedomineerd door het sorteren. Er is geen I/O in buildBundle() (de aanroeper beheert de bestandstoegang). De standaardreferentiewerklast blijft ruim binnen het budget van 1500 ms wandtijd / 64 MB piek. Het reproduceerbaarheidsprofiel is ontworpen als bitwise bij een gepinde context en stabiele invoer.

Beveiligingsnotities

Deze module verwerkt compliancebewijs, dat gevoelige metadata kan bevatten. PII-sanitisatie staat standaard aan (afstemming op GDPR art. 32). Houd dit aan voor elke extern gedeelde bundel. De exporter valideert elke digest en elk citatieanker aan de hand van een strikt SHA-256-patroon, zodat een misvormde of afgekapte hash wordt afgewezen in plaats van vertrouwd. Behandel de invoerclaims-dataset als de vertrouwensbasis: de exporter serialiseert getrouw wat hij aangeleverd krijgt, dus het bewijs is slechts zo betrouwbaar als die dataset. Zie het threat model van de engine in /modules/core/security/.

Conformiteit

Deze module doet geen normatieve claim over de PDF-specificatie. De module exporteert bewijs over conformiteit; zelf implementeert ze geen aangehaalde PDF-clausule. De ontwerpafstemmingen (OWASP ASVS V8.3, NIST CSF 2.0, NIST SP 800-53 r5, ISO/IEC 27001 A.12.4) zijn in de bron gedocumenteerd en zijn afstemmingen op controleframeworks, geen aan chunks vastgepinde PDF-citaties. De conformiteit die de bundel rapporteert wordt geproduceerd en gevalideerd door de oracle- en golden-suites die worden beschreven in /modules/core/conformance/.

Zie ook

Compliance-module — produceert de claims die deze module exporteert.
Metadata-module — de XMP-auditveld-emitter neemt de bundel op in het document.
Conformiteitsoverzicht
Beveiligingsmodel van de engine