Evidence — Diepe referentie

In één oogopslag

Deze pagina is de diepe referentie voor de NextPDF\Enterprise\Evidence-module. De module verzegelt validatiebevindingen in een onveranderlijk EvidencePackage, exporteert dit als deterministische JSON met een stabiele SHA-256-digest, persisteert het via een pluggable store-contract en volgt regressies tussen runs met ContinuousMonitor. De module consumeert bevindingen die door de Validation- en Compliance-oppervlakken worden geproduceerd; hij voert zelf geen conformiteitscontroles uit. Lees voor workflowbegeleiding eerst de Evidence-capaciteitspagina.

Beschikbaarheid en licenties

Deze capaciteit wordt meegeleverd in NextPDF Enterprise (nextpdf/enterprise) en wordt geactiveerd met een licentie-envelop op Enterprise-niveau. Een deployment zonder dat entitlement laadt de klassen van de capaciteit niet. Vergelijk edities en vraag een licentie aan.

Het oppervlak wordt gelicentieerd door de capaciteit enterprise.compliance.evidence; een geweigerd entitlement weigert de functie. Core en Pro produceren bevindingen en rapporten; het verzegelen van bevindingen tot een onveranderlijk, deterministisch, optioneel van een tijdstempel voorzien pakket met regressietracking heeft geen equivalent op Core- of Pro-niveau.

Publiek API-oppervlak

composer require nextpdf/enterprise:^3

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
EvidencePortal::__construct	EvidenceStoreInterface $store, EvidenceExporter $exporter	Koppelt de store en exporter	EvidencePortal	Niets gedeclareerd	Beide collaborators zijn injecteerbaar
EvidencePortal::generateEvidence	string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null	Telt geslaagd/mislukt, verzegelt een pakket met een vers UUID-id en wandkloktijd generatedAt, persisteert het	EvidencePackage	Niets gedeclareerd	Persisteert via store(), niet persistImmutable()
EvidencePortal::getEvidence	string $documentHash	Laatst opgeslagen pakket voor de hash	?EvidencePackage	Niets gedeclareerd	null wanneer er niets is opgeslagen
EvidencePortal::getHistory	string $documentHash	Volledige historie, nieuwste eerst	list<EvidencePackage>	Niets gedeclareerd	De volgorde wordt geleverd door de store
EvidencePortal::exportAsJson	EvidencePackage $package	Delegeert naar de exporter	non-empty-string	JsonException	Dezelfde bytes als EvidenceExporter::toJson
EvidencePackage::__construct	acht benoemde parameters, zie fence	Onveranderlijk value object	EvidencePackage	Niets gedeclareerd	Tellingen worden niet gevalideerd tegen $records
EvidencePackage::allPassed	geen	failedCount === 0	bool	Niets gedeclareerd	true voor een leeg pakket; gate op totalFindings
EvidencePackage::passRate	geen	passedCount / totalFindings	float	Niets gedeclareerd	0.0 wanneer totalFindings === 0
EvidenceRecord::__construct	string $policyName, bool $passed, string $details, string $validatorVersion, DateTimeImmutable $timestamp	Onveranderlijk resultaat van één beleidscontrole	EvidenceRecord	Niets gedeclareerd	Alle properties zijn public readonly
EvidenceExporter::toJson	EvidencePackage $package	JSON met vaste sleutelvolgorde; niet-ge-escapete slashes en Unicode	non-empty-string	JsonException	De sleutelvolgorde is dragend
EvidenceExporter::exportHash	EvidencePackage $package	SHA-256 over de toJson()-bytes	non-empty-string (64 hex)	JsonException	Stabiel per pakket
EvidenceStoreInterface::store	EvidencePackage $package	Voegt toe; historie per documenthash is toegestaan	void	Implementatie-afhankelijk	Append-only-semantiek vereist
EvidenceStoreInterface::persistImmutable	EvidencePackage $package	WORM-schrijfactie waar de backend dit ondersteunt	void	Implementatie-afhankelijk	Niet-WORM-backends gedragen zich als store()
EvidenceStoreInterface::findByDocumentHash	string $documentHash	Meest recente pakket voor de hash	?EvidencePackage	Implementatie-afhankelijk
EvidenceStoreInterface::findAllByDocumentHash	string $documentHash	Alle pakketten voor de hash, nieuwste eerst	list<EvidencePackage>	Implementatie-afhankelijk
EvidenceStoreInterface::count	geen	Totaal aantal opgeslagen pakketten	int<0, max>	Implementatie-afhankelijk
InMemoryEvidenceStore	klasse	Array-gebaseerde store voor tests en ontwikkeling	n.v.t.	n.v.t.	Niet duurzaam; geen WORM-semantiek
ContinuousMonitor::__construct	EvidenceStoreInterface $store	Koppelt de store	ContinuousMonitor	Niets gedeclareerd
ContinuousMonitor::check	EvidencePackage $currentEvidence, string $documentHash	Vergelijkt namen van mislukt beleid met het laatst opgeslagen pakket	MonitorResult	Niets gedeclareerd	De eerste controle behandelt elke huidige mislukking als nieuw
ContinuousMonitor::isDue	string $documentHash, MonitorSchedule $schedule	Verschuldigd wanneer er geen eerder bewijs is, het interval is verstreken of het opgeslagen bewijs in de toekomst is gedateerd	bool	Niets gedeclareerd	Fail-safe bij klokafwijking
MonitorResult::__construct	acht benoemde parameters, zie fence	Onveranderlijk diff-resultaat	MonitorResult	Niets gedeclareerd	Bevat beide pakketten en checkedAt
MonitorSchedule::__construct	MonitorFrequency $frequency, int $retentionDays = 90, bool $alertOnNewIssues = true	Configuratie-value object	MonitorSchedule	Niets gedeclareerd	Retentie en alerting worden door de host afgedwongen
MonitorFrequency	string-backed enum	Cases Daily, Weekly, Monthly	n.v.t.	n.v.t.	Achterliggende waarden daily, weekly, monthly
MonitorFrequency::intervalSeconds	geen	Interval per case: 86400, 604800, 2592000	positive-int	Niets gedeclareerd	Monthly is een vaste 30 dagen

Entry-point-signaturen

final class EvidencePortal
{
    public function __construct(
        private readonly EvidenceStoreInterface $store,
        private readonly EvidenceExporter $exporter,
    )

    public function generateEvidence(string $documentHash, array $records, ?string $tsaTimestamp = null): EvidencePackage

    public function getEvidence(string $documentHash): ?EvidencePackage

    public function getHistory(string $documentHash): array

    public function exportAsJson(EvidencePackage $package): string
}

final readonly class EvidencePackage
{
    public function __construct(
        public string $packageId,
        public string $documentHash,
        public array $records,
        public int $totalFindings,
        public int $passedCount,
        public int $failedCount,
        public DateTimeImmutable $generatedAt,
        public ?string $tsaTimestamp = null,
    )

    public function allPassed(): bool

    public function passRate(): float
}

final readonly class EvidenceRecord
{
    public function __construct(
        public string $policyName,
        public bool $passed,
        public string $details,
        public string $validatorVersion,
        public DateTimeImmutable $timestamp,
    )
}

final readonly class EvidenceExporter
{
    public function toJson(EvidencePackage $package): string

    public function exportHash(EvidencePackage $package): string
}

interface EvidenceStoreInterface
{
    public function store(EvidencePackage $package): void;

    public function persistImmutable(EvidencePackage $package): void;

    public function findByDocumentHash(string $documentHash): ?EvidencePackage;

    public function findAllByDocumentHash(string $documentHash): array;

    public function count(): int;
}

final class ContinuousMonitor
{
    public function __construct(
        private readonly EvidenceStoreInterface $store,
    )

    public function check(EvidencePackage $currentEvidence, string $documentHash): MonitorResult

    public function isDue(string $documentHash, MonitorSchedule $schedule): bool
}

final readonly class MonitorSchedule
{
    public function __construct(
        public MonitorFrequency $frequency,
        public int $retentionDays = 90,
        public bool $alertOnNewIssues = true,
    )
}

enum MonitorFrequency: string
{
    case Daily = 'daily';
    case Weekly = 'weekly';
    case Monthly = 'monthly';

    public function intervalSeconds(): int
}

Gedragscontract

EvidencePortal::generateEvidence(string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null): EvidencePackage is het entry point voor het verzegelen. Extern waarneembare regels:

1. Samenstelling. generateEvidence telt geslaagde en mislukte records en zet totalFindings op hun som. Het kent een verse version-4 UUID packageId toe, stempelt generatedAt met de wandklok, persisteert het pakket via EvidenceStoreInterface::store en retourneert het. De recordlijst wordt in de gegeven volgorde ingebed, ongewijzigd.
2. Onveranderlijkheid. EvidencePackage is final readonly en wordt nooit gemuteerd na constructie; het is geschikt voor WORM-opslag. allPassed() is failedCount === 0. passRate() is passedCount / totalFindings, en 0.0 wanneer totalFindings === 0.
3. Deterministische export. EvidenceExporter::toJson geeft de envelop en elk record uit met een vaste, handgeschreven sleutelvolgorde; de recordvolgorde volgt het pakket. De codering is strikt en gooit bij falen, met slashes en Unicode niet ge-escaped (JSON_UNESCAPED_SLASHES). Tijdstempels serialiseren met DateTimeInterface::RFC3339_EXTENDED, de uitgebreide RFC 3339-vorm met fractionele seconden. exportHash retourneert de SHA-256-hex-digest van 64 tekens over exact die bytes. Hetzelfde pakket levert altijd dezelfde digest op, op elke host, op elk moment. Het opnieuw genereren van bewijs voor hetzelfde document levert een nieuwe packageId en generatedAt op, dus een nieuwe digest: determinisme is per pakket, niet per document.
4. Tijdstempel is bewijs van tijd, geen oordeel. Een pakket kan een optioneel, door de aanroeper aangeleverd RFC 3161-token dragen (base64-gecodeerd). Het token bindt het pakketdatum aan een tijdwaarde. De module bedt het in als een ondoorzichtige string; het haalt, parseert of verifieert geen tokens en staat niet garant voor de TSA. Tokenverificatie hoort bij de Signature- en Security-modules.
5. Regressietracking. ContinuousMonitor::check laadt het laatst opgeslagen pakket voor de documenthash en vergelijkt unieke namen van mislukt beleid. Problemen worden gecategoriseerd als newIssues (nu mislukt, eerder niet), resolvedIssues (eerder mislukt, nu niet) en unchangedIssues (in beide mislukt). hasChanges is alleen true wanneer er nieuwe of opgeloste problemen zijn; ongewijzigde mislukkingen alleen rapporteren false. Bij een eerste controle is elke huidige mislukking nieuw.
6. Planning. ContinuousMonitor::isDue retourneert true wanneer er geen bewijs voor de hash bestaat, wanneer de verstreken tijd sinds de opgeslagen generatedAt het frequentie-interval van de planning bereikt, of wanneer het opgeslagen bewijs in de toekomst is gedateerd ten opzichte van de pollende host. Het geval van toekomstdatering is fail-safe: in het slechtste geval een extra hercontrole, nooit een gemiste.
7. Store-contract. EvidenceStoreInterface-implementaties moeten append-only-semantiek ondersteunen; meerdere pakketten per documenthash vormen de historie, nieuwste eerst. persistImmutable richt zich op WORM-capabele backends; niet-WORM-implementaties moeten zich precies als store gedragen.

Randgevallen en foutmodi

• Een leeg pakket rapporteert allPassed() true en passRate() 0.0. Gate op totalFindings > 0 voordat je een pakket als geslaagd behandelt.
• Directe constructie van EvidencePackage valideert de tellingen niet tegen $records. Gebruik de portal, of houd de tellingen zelf consistent.
• generateEvidence persisteert voordat het retourneert. Voer ContinuousMonitor::check uit met het nieuwe pakket voordat je het persisteert; een controle na persistentie vergelijkt het pakket met zichzelf en rapporteert geen wijzigingen.
• exportHash dekt exact de toJson-bytes. Een digest die opnieuw wordt berekend door een andere serializer, sleutelvolgorde of escaping-policy komt niet overeen.
• MonitorFrequency::Monthly is een vast venster van 30 dagen, geen kalendermaand.
• MonitorSchedule::$retentionDays en $alertOnNewIssues zijn configuratie die wordt meegedragen voor host-schedulers. De module verwijdert nooit bewijs en verstuurt nooit alerts.
• InMemoryEvidenceStore is voor tests en ontwikkeling. Pakketten gaan verloren bij het afsluiten van het proces, en zijn persistImmutable heeft geen WORM-semantiek.
• details-strings van records worden letterlijk geëxporteerd; de exporter redigeert niet. Houd geheimen en gereguleerde persoonsgegevens buiten details. Gegevenslocatie, retentie en toegangscontrole volgen de store-implementatie van de operator.
• Het tsaTimestamp-argument wordt geaccepteerd als een ondoorzichtige string. Een misvormd token wordt ongewijzigd ingebed en komt pas bij downstream-verificatie aan het licht.

FIPS-modusgedrag

Deze module berekent SHA-256-digests en bedt een door de aanroeper aangeleverd RFC 3161-token in. Het voert geen ondertekening en geen sleutelbewaring uit. Het FIPS-modusgedrag wordt beheerd door de Security- en Signature-modules.

Conformiteit

Bewering	Standaard	Clausule
Een tijdstempeltoken geeft aan dat een datum op een bepaald tijdstip bestond.	IETF RFC 3161	§2
Geëxporteerde tijdstempels gebruiken het internet-datum/tijd-profiel van ISO 8601, met fractionele seconden.	IETF RFC 3339	§5.6
Validatiemateriaal dat in een PDF is ingebed hoort bij de Document Security Store; dat oppervlak is dat van de Signature-module, niet van deze.	ISO 32000-2:2020	§12.8.4

Alle clausules zijn geparafraseerd; NextPDF reproduceert geen normatieve tekst. NextPDF doet geen enkele certificeringsclaim. Bewijsvastlegging ondersteunt auditworkflows; het is geen juridische attestatie en geen auditcertificering. Een tijdstempeltoken is uitsluitend bewijs van tijd, en deze module beweert niet dat enige inhoud conform is. Geldigheid en conformiteit blijven eigenschappen van het uiteindelijke bestand plus een validator. Deze referentie is geen juridisch advies; raadpleeg je eigen compliance- en juridische adviseurs.

Ontwikkelnotities

• De modulebron draagt @since 2.2.0; deze referentie documenteert het oppervlak zoals meegeleverd in nextpdf/enterprise 3.1.0.
• Alles draait in-process op je host. De module voert geen netwerk-I/O uit en neemt zelf nooit contact op met een TSA.
• De sleutelvolgorde van het array-literal van de exporter is dragend door ontwerp. Het herordenen ervan zou exportHash veranderen en eerder opgeslagen digests ongeldig maken; de bron verbiedt dit.
• packageId is een version-4 UUID samengesteld uit de output van \random_bytes(16); identifiers zijn uniek maar niet reproduceerbaar.
• Duurzame persistentie wordt geleverd door de host. WORM-handhaving en toegangscontrole zijn de verantwoordelijkheid van de operator; de in-memory store is de enige meegeleverde implementatie.
• MonitorResult is een final readonly value object; zijn acht properties zijn public, inclusief checkedAt, de wandkloktijd van de controle.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.

Zie ook

• Evidence — de capaciteitspagina met workflowbegeleiding.
• Validation — Diepe referentie
• Compliance — Diepe referentie
• AST-audittrail — Diepe referentie
• Specificaties: PAdES