Evidence — Riferimento approfondito

In sintesi

Questa pagina è il riferimento approfondito per il modulo NextPDF\Enterprise\Evidence. Il modulo sigilla i risultati di convalida in un EvidencePackage immutabile, lo esporta come JSON deterministico con un digest SHA-256 stabile, lo persiste tramite un contratto di store innestabile e traccia le regressioni tra le esecuzioni con ContinuousMonitor. Il modulo consuma i findings prodotti dalle superfici Validation e Compliance; non esegue esso stesso alcun controllo di conformità. Per la guida ai flussi di lavoro, leggere prima la pagina della capability Evidence.

Disponibilità e licenza

Questa capability è inclusa in NextPDF Enterprise (nextpdf/enterprise) e si attiva con un envelope di licenza di tier Enterprise. Un deployment privo di tale entitlement non carica le classi della capability. Confronta le edizioni e ottieni una licenza.

La superficie è soggetta a licenza dalla capability enterprise.compliance.evidence; un entitlement negato nega la funzionalità. Core e Pro producono findings e report; sigillare i findings in un pacchetto immutabile, deterministico, opzionalmente con marca temporale e con tracciamento delle regressioni non ha alcun equivalente di tier Core o Pro.

Superficie API pubblica

composer require nextpdf/enterprise:^3

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
EvidencePortal::__construct	EvidenceStoreInterface $store, EvidenceExporter $exporter	Collega lo store e l’exporter	EvidencePortal	Nulla dichiarato	Entrambi i collaboratori sono iniettabili
EvidencePortal::generateEvidence	string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null	Conta i superamenti/fallimenti, sigilla un pacchetto con un nuovo id UUID e un generatedAt di orologio, lo persiste	EvidencePackage	Nulla dichiarato	Persiste tramite store(), non persistImmutable()
EvidencePortal::getEvidence	string $documentHash	Ultimo pacchetto memorizzato per l’hash	?EvidencePackage	Nulla dichiarato	null quando nessuno è memorizzato
EvidencePortal::getHistory	string $documentHash	Cronologia completa, dal più recente	list<EvidencePackage>	Nulla dichiarato	L’ordinamento è fornito dallo store
EvidencePortal::exportAsJson	EvidencePackage $package	Delega all’exporter	non-empty-string	JsonException	Stessi byte di EvidenceExporter::toJson
EvidencePackage::__construct	otto parametri nominati, vedere il blocco	Value object immutabile	EvidencePackage	Nulla dichiarato	I conteggi non sono convalidati rispetto a $records
EvidencePackage::allPassed	nessuno	failedCount === 0	bool	Nulla dichiarato	true per un pacchetto vuoto; usare totalFindings come gate
EvidencePackage::passRate	nessuno	passedCount / totalFindings	float	Nulla dichiarato	0.0 quando totalFindings === 0
EvidenceRecord::__construct	string $policyName, bool $passed, string $details, string $validatorVersion, DateTimeImmutable $timestamp	Risultato immutabile di un singolo controllo di policy	EvidenceRecord	Nulla dichiarato	Tutte le proprietà sono public readonly
EvidenceExporter::toJson	EvidencePackage $package	JSON con ordine di chiavi fisso; slash e Unicode non-escaped	non-empty-string	JsonException	L’ordine delle chiavi è portante
EvidenceExporter::exportHash	EvidencePackage $package	SHA-256 sui byte di toJson()	non-empty-string (64 esadecimali)	JsonException	Stabile per pacchetto
EvidenceStoreInterface::store	EvidencePackage $package	Appende; è consentita una cronologia per hash del documento	void	Definito dall’implementazione	Sono richieste semantiche append-only
EvidenceStoreInterface::persistImmutable	EvidencePackage $package	Scrittura WORM ove il backend la supporti	void	Definito dall’implementazione	I backend non-WORM si comportano come store()
EvidenceStoreInterface::findByDocumentHash	string $documentHash	Pacchetto più recente per l’hash	?EvidencePackage	Definito dall’implementazione
EvidenceStoreInterface::findAllByDocumentHash	string $documentHash	Tutti i pacchetti per l’hash, dal più recente	list<EvidencePackage>	Definito dall’implementazione
EvidenceStoreInterface::count	nessuno	Numero totale di pacchetti memorizzati	int<0, max>	Definito dall’implementazione
InMemoryEvidenceStore	classe	Store basato su array per test e sviluppo	n/d	n/d	Non durevole; nessuna semantica WORM
ContinuousMonitor::__construct	EvidenceStoreInterface $store	Collega lo store	ContinuousMonitor	Nulla dichiarato
ContinuousMonitor::check	EvidencePackage $currentEvidence, string $documentHash	Confronta i nomi di policy fallite con l’ultimo pacchetto memorizzato	MonitorResult	Nulla dichiarato	Il primo controllo tratta ogni fallimento corrente come nuovo
ContinuousMonitor::isDue	string $documentHash, MonitorSchedule $schedule	Dovuto quando non esistono evidenze precedenti, l’intervallo è trascorso, o le evidenze memorizzate hanno data futura	bool	Nulla dichiarato	Fail-safe sullo scostamento di orologio
MonitorResult::__construct	otto parametri nominati, vedere il blocco	Risultato immutabile del confronto	MonitorResult	Nulla dichiarato	Include entrambi i pacchetti e checkedAt
MonitorSchedule::__construct	MonitorFrequency $frequency, int $retentionDays = 90, bool $alertOnNewIssues = true	Value object di configurazione	MonitorSchedule	Nulla dichiarato	La conservazione e gli alert sono applicati dall’host
MonitorFrequency	enum backed da stringa	Casi Daily, Weekly, Monthly	n/d	n/d	Valori di backing daily, weekly, monthly
MonitorFrequency::intervalSeconds	nessuno	Intervallo per caso: 86400, 604800, 2592000	positive-int	Nulla dichiarato	Monthly è fissato a 30 giorni

Firme dei punti di ingresso

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
}

Contratto di comportamento

EvidencePortal::generateEvidence(string $documentHash, list<EvidenceRecord> $records, ?string $tsaTimestamp = null): EvidencePackage è il punto di ingresso per il sigillo. Regole osservabili dall’esterno:

1. Assemblaggio. generateEvidence conta i record superati e falliti e imposta totalFindings alla loro somma. Assegna un nuovo UUID versione 4 packageId, marca generatedAt con l’orologio, persiste il pacchetto tramite EvidenceStoreInterface::store e lo restituisce. La lista dei record è incorporata nell’ordine dato, non modificata.
2. Immutabilità. EvidencePackage è final readonly e non viene mai mutato dopo la costruzione; è adatto allo storage WORM. allPassed() è failedCount === 0. passRate() è passedCount / totalFindings, e 0.0 quando totalFindings === 0.
3. Esportazione deterministica. EvidenceExporter::toJson emette l’envelope e ciascun record con un ordine di chiavi fisso e scritto a mano; la sequenza dei record segue il pacchetto. La codifica è rigorosa e solleva un’eccezione in caso di fallimento, con slash e Unicode lasciati non-escaped (JSON_UNESCAPED_SLASHES). Le marche temporali sono serializzate con DateTimeInterface::RFC3339_EXTENDED, la forma estesa di RFC 3339 con secondi frazionari. exportHash restituisce il digest esadecimale SHA-256 di 64 caratteri su esattamente quei byte. Lo stesso pacchetto produce sempre lo stesso digest, su qualsiasi host, in qualsiasi momento. Rigenerare le evidenze per lo stesso documento produce un nuovo packageId e un nuovo generatedAt, quindi un nuovo digest: il determinismo è per pacchetto, non per documento.
4. La marca temporale è prova del tempo, non un verdetto. Un pacchetto può trasportare un token RFC 3161 facoltativo fornito dal chiamante (codificato in base64). Il token lega il dato del pacchetto a un valore temporale. Il modulo lo incorpora come stringa opaca; non recupera, analizza né verifica i token, e non garantisce per la TSA. La verifica del token spetta ai moduli Signature e Security.
5. Tracciamento delle regressioni. ContinuousMonitor::check carica l’ultimo pacchetto memorizzato per l’hash del documento e confronta i nomi di policy fallite univoci. I problemi sono categorizzati come newIssues (falliti ora, non prima), resolvedIssues (falliti prima, non ora) e unchangedIssues (falliti in entrambi). hasChanges è true solo quando esistono problemi nuovi o risolti; i soli fallimenti invariati riportano false. A un primo controllo, ogni fallimento corrente è nuovo.
6. Pianificazione. ContinuousMonitor::isDue restituisce true quando non esiste alcuna evidenza per l’hash, quando il tempo trascorso dal generatedAt memorizzato raggiunge l’intervallo della frequenza dello schedule, o quando l’evidenza memorizzata ha data futura rispetto all’host di polling. Il caso con data futura è fail-safe: al peggio un ricontrollo aggiuntivo, mai uno mancato.
7. Contratto dello store. Le implementazioni di EvidenceStoreInterface devono supportare semantiche append-only; più pacchetti per hash del documento formano la cronologia, dal più recente. persistImmutable è destinato ai backend con capacità WORM; le implementazioni non-WORM devono comportarsi esattamente come store.

Casi limite e modalità di fallimento

• Un pacchetto vuoto riporta allPassed() true e passRate() 0.0. Usare totalFindings > 0 come gate prima di trattare un pacchetto come un superamento.
• La costruzione diretta di EvidencePackage non convalida i conteggi rispetto a $records. Usare il portal, oppure mantenere i conteggi coerenti autonomamente.
• generateEvidence persiste prima di restituire. Eseguire ContinuousMonitor::check con il nuovo pacchetto prima di persisterlo; un controllo dopo la persistenza confronta il pacchetto con sé stesso e riporta nessun cambiamento.
• exportHash copre esattamente i byte di toJson. Un digest ricalcolato da qualsiasi altro serializzatore, ordine di chiavi o policy di escaping non corrisponderà.
• MonitorFrequency::Monthly è una finestra fissa di 30 giorni, non un mese di calendario.
• MonitorSchedule::$retentionDays e $alertOnNewIssues sono configurazione trasportata per gli scheduler dell’host. Il modulo non elimina mai le evidenze e non invia mai alert.
• InMemoryEvidenceStore è per test e sviluppo. I pacchetti sono persi all’uscita del processo, e il suo persistImmutable non ha semantica WORM.
• Le stringhe details dei record sono esportate verbatim; l’exporter non redige. Tenere segreti e dati personali regolamentati fuori da details. Residenza, conservazione e controllo degli accessi seguono l’implementazione di store dell’operatore.
• L’argomento tsaTimestamp è accettato come stringa opaca. Un token malformato è incorporato invariato ed emerge solo alla verifica a valle.

Comportamento in modalità FIPS

Questo modulo calcola digest SHA-256 e incorpora un token RFC 3161 fornito dal chiamante. Non esegue alcuna firma né custodia delle chiavi. Il comportamento in modalità FIPS è governato dai moduli Security e Signature.

Conformità

Affermazione	Standard	Clausola
Un token di marca temporale indica che un dato esisteva in un particolare momento nel tempo.	IETF RFC 3161	§2
Le marche temporali esportate usano il profilo Internet di data/ora di ISO 8601, con secondi frazionari.	IETF RFC 3339	§5.6
Il materiale di convalida incorporato all’interno di un PDF appartiene al Document Security Store; quella superficie è del modulo Signature, non di questo.	ISO 32000-2:2020	§12.8.4

Tutte le clausole sono parafrasate; NextPDF non riproduce il testo normativo. NextPDF non fa alcuna affermazione di certificazione. La cattura delle evidenze supporta i flussi di lavoro di audit; non è un’attestazione legale né una certificazione di audit. Un token di marca temporale è prova del solo tempo, e questo modulo non asserisce che alcun contenuto sia conforme. Validità e conformità restano proprietà del file finale più un validatore. Questo riferimento non è un parere legale; consultare i propri consulenti di conformità e legali.

Note di sviluppo

• Il sorgente del modulo riporta @since 2.2.0; questo riferimento documenta la superficie così come distribuita in nextpdf/enterprise 3.1.0.
• Tutto viene eseguito in-process sul proprio host. Il modulo non esegue alcun I/O di rete e non contatta mai esso stesso una TSA.
• L’ordine delle chiavi del literal di array dell’exporter è portante per progettazione. Riordinarlo cambierebbe exportHash e invaliderebbe i digest precedentemente memorizzati; il sorgente lo vieta.
• packageId è un UUID versione 4 assemblato dall’output di \random_bytes(16); gli identificatori sono univoci ma non riproducibili.
• La persistenza durevole è fornita dall’host. L’applicazione del WORM e il controllo degli accessi sono responsabilità dell’operatore; lo store in memoria è l’unica implementazione inclusa.
• MonitorResult è un value object final readonly; le sue otto proprietà sono public, incluso checkedAt, l’orario di orologio del controllo.

Confine di pubblicazione

Questa pagina documenta soltanto il comportamento osservabile dall’esterno e la superficie API pubblica supportata. Percorsi di namespace interni, classi helper, tabelle di meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.

Vedere anche

• Evidence — la pagina della capability con la guida ai flussi di lavoro.
• Validation — Riferimento approfondito
• Compliance — Riferimento approfondito
• AST audit trail — Riferimento approfondito
• Specifiche: PAdES