Validation — Riferimento approfondito

In sintesi

Il modulo Validation esegue policy di conformità strutturale predefinite, in sola lettura, sui byte grezzi del PDF. Compliance::assess() applica esattamente una CompliancePolicy e restituisce un ComplianceReport con finding partizionati per gravità e un disclaimer legale obbligatorio. Le policy sono disponibili per PDF/A-4 (comprese le varianti e e f), la struttura baseline PAdES, un profilo strutturale eIDAS, la salute LTV/DSS, ZUGFeRD / Factur-X, FDA 21 CFR Part 11 e l’archiviazione WORM SEC Rule 17a-4. Ogni policy è una funzione pura: byte in ingresso, finding in uscita. Validation non modifica mai il documento e non esegue mai alcuna verifica crittografica.

Disponibilità e licenza

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

La superficie Validation/Evidence è gestita dalla capacità enterprise.compliance.evidence. Un diritto negato nega la funzionalità anziché degradare silenziosamente.

Tier	Superficie Validation
Core	Validatori di byte-stream in-process e un cross-check grammaticale; un risultato con zero finding è un risultato verificato, non un certificato.
Pro	Convalida in-process EN 16931 / Factur-X / ZUGFeRD a livello di fattura elettronica; nessuna policy predefinita PDF/A-4, PAdES, LTV, FDA o SEC.
Enterprise	Policy strutturali predefinite per PDF/A-4, PAdES, LTV, ZUGFeRD, FDA Part 11 e SEC 17a-4 con un report unificato (questo modulo).

Il gateway external-sidecar di Enterprise Compliance è un modulo separato e distinto.

Superficie API pubblica

composer require nextpdf/enterprise:^3

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
Compliance::__construct	?ClockInterface $clock = null	Clock di sistema quando non viene iniettato alcun clock	—	—	Forma di istanza DI-friendly; il clock timbra validatedAt
Compliance::run	string $pdfData, CompliancePolicy $policy, array $context = []	Applica esattamente una policy e misura la durata wall-clock	ComplianceReport	Propaga le eccezioni delle policy custom; le policy integrate raccolgono i finding anziché sollevare eccezioni	Metodo di istanza
Compliance::assess (statico)	string $pdfData, CompliancePolicy $policy, array $context = []	Costruisce un’istanza predefinita e delega a run()	ComplianceReport	Come run()	Percorso rapido a configurazione zero
Policies::pdfA4 / ::pdfA4e / ::pdfA4f (statico)	—	Policy strutturale PDF/A-4 secondo ISO 19005-4:2020	CompliancePolicy	—	e consente annotazioni 3D/rich-media; f aggiunge i controlli sulle relazioni dei file incorporati
Policies::padesBaseline (statico)	—	Controlli strutturali PAdES B-B	CompliancePolicy	—	Solo struttura; nessuna verifica crittografica
Policies::eidasQualified (statico)	—	Controlli strutturali PAdES sotto un profilo etichettato eIDAS	CompliancePolicy	—	La qualificazione dipende dal TSP e dal certificato qualificato
Policies::ltvHealth (statico)	—	Controllo strutturale di salute del DSS	CompliancePolicy	—	La presenza del DSS è risolta dal grafo degli oggetti attivo, fail-closed
Policies::zugferd (statico)	string $profile = 'BASIC'	Normalizza l’alias di profilo e costruisce il validatore ZUGFeRD	CompliancePolicy	\ValueError (profilo sconosciuto)	Profili: MINIMUM, BASIC, BASIC_WL, EN16931, EXTENDED
Policies::fdaPart11 (statico)	—	Policy strutturale FDA 21 CFR Part 11	CompliancePolicy	—	Sette controlli strutturali, inclusa l’integrità della hash-chain dell’audit-trail
Policies::sec17a4 / ::sec17a4Compatible / ::sec17a4Structural / ::sec17a4PreSign (statico)	—	Policy WORM SEC 17a-4 alla rigidità nominata	CompliancePolicy	—	La rigidità mappa su WormComplianceLevel
CompliancePolicy (interfaccia)	—	Contratto strategy per uno standard	—	—	getName(), getIdentifier(), getStandardReference(), validate(); implementabile dal cliente
ComplianceReport	Value object readonly	Finding partizionati per gravità alla costruzione	—	—	passes(), fails(), totalFindings(), getDisclaimer(); pubblici findings, errors, warnings, infos, policyName, policyId, standard, validatedAt, durationMs
ComplianceFinding	Severity $severity, string $ruleId, string $message, string $clause = '', string $suggestion = ''	Un risultato di regola con riferimento di clausola e suggerimento di remediation	—	—	Statici error() / warning() / info(); isError()
Severity (enum)	3 casi string-backed	Error, Warning, Info	—	—	Solo Error fa fallire un report
WormComplianceLevel (enum)	4 casi string-backed	Full, Compatible, Structural, PreSign	—	—	requiresSignature(), requiresDocMdp(), requiresLtv(), maxDocMdpLevel()
PdfAPolicy, PadesValidator, LtvHealthCheck, ZugferdValidator, Sec17a4WormPolicy, Fda\FdaPart11Policy	Costruttori per classe	Implementano CompliancePolicy uno per ciascuno standard	list<ComplianceFinding> da validate()	—	Da ottenere via Policies; Sec17a4WormPolicy::getLevel() espone la rigidità configurata
Fda\FdaSigningIntent (enum)	6 casi string-backed	Authoring, Review, Approval, Certification, Verification, Rejection	—	—	toPdfReasonString() produce la stringa /Reason canonica
Fda\FdaAuditEvent::__construct	DateTimeImmutable $timestamp, string $actor, FdaSigningIntent $action, string $documentHash, string $certificateSerial, string $previousEventHash = ''	Calcola l’hash di catena SHA-256 alla costruzione	—	InvalidArgumentException (timestamp non UTC)	Pubblico eventHash; toXmpRdf() serializza un elemento di lista XMP
Fda\FdaAuditTrail::addEvent	FdaAuditEvent $event	Aggiunge l’evento quando il suo anello di catena corrisponde alla coda del trail	self	InvalidArgumentException (hash-chain interrotta)	Anche createEvent(), verifyChain(), getLastEventHash(), getEvents(), embedInMetadata()
Fda\FdaSignatureEnforcer::configureSeedValue	FdaSigningIntent $intent, string $tsaUrl	Costruisce una configurazione seed-value di firma vincolata FDA	SeedValueConfig	—	Richiede il set di ragioni FDA, un timestamp e digest SHA-256 o più forti
Fda\FdaSignatureEnforcer::applyTo	SequentialSigner $signer, SigningStrategy $strategy, string $signerName, FdaSigningIntent $intent, string $tsaUrl, string $fieldName = '', ?string $reason = null	Aggiunge un firmatario vincolato FDA a un SequentialSigner Pro	SequentialSigner	—	Serializza i vincoli nel campo firma prodotto

namespace NextPDF\Enterprise\Validation;

final readonly class Compliance
{
    public function __construct(?ClockInterface $clock = null);

    /** @param array<string, mixed> $context */
    public function run(string $pdfData, CompliancePolicy $policy, array $context = []): ComplianceReport;

    /** @param array<string, mixed> $context */
    public static function assess(string $pdfData, CompliancePolicy $policy, array $context = []): ComplianceReport;
}

final class Policies
{
    public static function pdfA4(): CompliancePolicy;      // also pdfA4e(), pdfA4f()
    public static function padesBaseline(): CompliancePolicy;
    public static function eidasQualified(): CompliancePolicy;
    public static function ltvHealth(): CompliancePolicy;
    public static function zugferd(string $profile = 'BASIC'): CompliancePolicy;
    public static function fdaPart11(): CompliancePolicy;
    public static function sec17a4(): CompliancePolicy;    // also sec17a4Compatible(), sec17a4Structural(), sec17a4PreSign()
}

interface CompliancePolicy
{
    public function getName(): string;

    public function getIdentifier(): string;

    public function getStandardReference(): string;

    /**
     * @param array<string, mixed> $context
     * @return list<ComplianceFinding>
     */
    public function validate(string $pdfData, array $context = []): array;
}

final readonly class ComplianceReport
{
    public const string LEGAL_DISCLAIMER;

    public function passes(): bool;

    public function fails(): bool;

    public function totalFindings(): int;

    public function getDisclaimer(): string;
}

Contratto di comportamento

Compliance::assess() (statico) e Compliance::run() (istanza, con un Psr\Clock\ClockInterface iniettabile) applicano esattamente una policy e restituiscono un ComplianceReport. Regole osservabili dall’esterno:

• Puramente in sola lettura. Ogni CompliancePolicy::validate() è una funzione pura: byte in ingresso, finding in uscita. Una policy non modifica mai i byte del PDF. Questo invariante architetturale mantiene la convalida distinta dall’auto-fix e dal modulo Evidence.
• Gate di gravità. ComplianceReport::passes() è true solo quando errors === []. I warning e gli info non fanno mai fallire un report. fails() è il complemento.
• Disclaimer obbligatorio. ComplianceReport::getDisclaimer() restituisce il testo costante del disclaimer legale. Renderlo visibile nell’output destinato all’utente è richiesto dal contratto.
• Provenienza del report. Il report riporta il nome, l’identificatore e il riferimento allo standard della policy, il timestamp di convalida dal clock iniettato o di sistema e la durata misurata in millisecondi.
• Raccogli, non interrompere. Le policy integrate eseguono tutti i controlli applicabili e raccolgono ogni finding anziché fermarsi al primo errore.
• Solo DSS raggiungibile dal catalogo. LtvHealthCheck risolve la presenza del DSS dal grafo degli oggetti attivo: trailer attivo, poi catalogo /Root, poi /DSS e le sue sotto-chiavi. I byte marcatori piazzati in commenti, stringhe, oggetti orfani o revisioni superate non contano. Un input non parsabile è trattato come assenza di DSS, quindi il controllo fallisce in modo fail-closed. Il controllo è strutturale; non verifica crittograficamente i dati OCSP/CRL incorporati.
• Controlli di firma strutturali. Policies::padesBaseline() e Policies::eidasQualified() convalidano la struttura PAdES solo a livello di PDF. La qualificazione sotto eIDAS dipende dal TSP e dal certificato qualificato, che sono al di fuori di questo modulo.
• Le policy per settori regolamentati sono strutturali. FdaPart11Policy verifica la presenza della firma, l’intento /Reason, il tempo di firma /M, l’identità /Name, l’assenza di JavaScript, il namespace dell’audit-trail FDA e l’integrità della hash-chain. Sec17a4WormPolicy verifica fino a 13 regole WORM; WormComplianceLevel seleziona la rigidità. Full richiede DocMDP livello 1, Compatible accetta il livello 2, e Structural / PreSign saltano le regole di firma, DocMDP e DSS. Nessuna delle due policy stabilisce la conformità legale.
• Contesto ZUGFeRD. Policies::zugferd() verifica sempre i requisiti a livello di PDF. Convalida l’XML della fattura solo quando il chiamante passa ['xml' => $xmlData] in $context; in caso contrario emette il finding informativo zugferd-xml-skipped.
• Audit-trail a prova di manomissione. FdaAuditTrail è una hash-chain SHA-256 append-only. addEvent() rifiuta un anello interrotto, verifyChain() ri-deriva ogni hash, ed embedInMetadata() scrive il trail in XMP sotto http://ns.nextpdf.dev/fda/1.0/ con uno schema di estensione PDF/A.

Casi limite e modalità di fallimento

• Un input non-PDF o vuoto produce finding di errore anziché un’eccezione nelle policy integrate. Verificare sempre passes() e rendere visibile il disclaimer.
• Policies::zugferd() normalizza gli alias di profilo (BASIC_WL, EN16931, EN_16931). Un profilo sconosciuto solleva \ValueError in fase di factory, prima che venga eseguita qualsiasi convalida.
• Un DSS con CRL ma senza risposte OCSP soddisfa il controllo del materiale di revoca; il finding annota l’alternativa accettabile. L’assenza di uno dei due non è un errore.
• Un dizionario /VRI mancante o un array /Certs assente producono warning, non errori; il report può comunque passare.
• FdaAuditEvent rifiuta qualsiasi timestamp non UTC con InvalidArgumentException alla costruzione.
• FdaAuditTrail::verifyChain() restituisce false su qualsiasi evento manomesso o riordinato; non solleva mai eccezioni.
• Le implementazioni custom di CompliancePolicy possono sollevare eccezioni da validate(); Compliance::run() non le cattura, quindi tali eccezioni si propagano al chiamante.

Comportamento in modalità FIPS

Questo modulo non esegue alcuna firma, alcuna verifica crittografica e alcuna custodia di chiavi. La policy di algoritmi in modalità FIPS è gestita dai moduli Security e Signature. I seed value di FdaSignatureEnforcer vincolano i campi firma legati a FDA ai metodi di digest SHA-256, SHA-384 o SHA-512.

Conformità

Queste policy verificano attributi strutturali rispetto agli standard nominati. Il verdetto di conformità per i profili ISO/ETSI resta una proprietà del file finale insieme a un validatore esterno.

Comportamento	Riferimento
Conformità determinata rispetto allo standard, non al produttore	ISO 19005-4:2020 §5.2
Dizionario della firma digitale / DSS per la convalida a lungo termine	ISO 32000-2:2020 §12.8
Il DSS è un dizionario detenuto dalla chiave DSS del catalogo del documento	ISO 32000-2:2020 §12.8.4.3
Livelli di firma baseline PAdES	ETSI EN 319 142-1 §5.4.3
Modello semantico del profilo EN 16931 (riferimento di supporto)	Factur-X 1.08 (EN 16931)

Le policy FDA 21 CFR Part 11 e SEC 17a-4 verificano solo attributi strutturali; tali normative sono al di fuori del corpus di verifica e non comportano alcuna affermazione di conformità verificata. Le stringhe di clausola all’interno dei finding FDA (per esempio §11.50, §11.10(e)) sono riferimenti di regola emessi dal prodotto. La riga EN 16931 è un riferimento di supporto al di sotto della soglia di recupero; non è una rivendicazione di conformità rigida. Il supporto di uno standard non equivale alla conformità a quello standard, e la conformità non equivale a una certificazione — NextPDF non detiene alcuna certificazione e non ne rilascia alcuna. Questo riferimento non è un parere legale; rivolgersi al proprio team di conformità per la sufficienza legale.

Note di sviluppo

• La convalida viene eseguita in-process e in locale, senza I/O di rete. Una policy non può alterare l’input.
• Trattare come ostili i byte del PDF provenienti da fonti non attendibili. Le policy integrate sono totali su byte arbitrari e falliscono in modo fail-closed dove la struttura non può essere risolta.
• Rendere visibile ComplianceReport::getDisclaimer() in ogni rendering destinato all’utente di un report.
• I report e i finding possono contenere dati personali provenienti da documenti firmati e metadati di audit-trail (nomi dei firmatari, numeri di serie dei certificati). L’operatore è responsabile dei controlli di conservazione e minimizzazione.
• Le policy custom implementano CompliancePolicy; mantenere getIdentifier() unico tra tutte le policy per la serializzazione e la cache.
• Questo modulo riguarda funzionalità crittografiche; trattarlo come sensibile per la sicurezza nella propria revisione.
• I dettagli dei meccanismi interni restano nella documentazione interna del repository sorgente e sono fuori ambito per questo manuale.

Confine di pubblicazione

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

Vedere anche

• Panoramica della capacità Validation
• Compliance — Riferimento approfondito
• Evidence — Riferimento approfondito
• Core Compliance
• Specifiche: PAdES