Evidence

At a glance

NextPDF Enterprise assembles per-document validation findings into a sealed, immutable package with a deterministic JSON form and a stable SHA-256 digest, optionally carrying an RFC 3161 timestamp token. Evidence capture supports audit workflows.

Availability & licensing

This capability ships in NextPDF Enterprise (nextpdf/enterprise) and activates with an Enterprise-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Compare editions and get a license.

Install

composer require nextpdf/enterprise:^3

Conceptual overview

EvidencePortal is the entry point. generateEvidence($documentHash, $records, $tsaTimestamp) assembles a list of EvidenceRecord instances into an EvidencePackage, computes pass/fail statistics, persists the package through an EvidenceStoreInterface, and returns the sealed package. An EvidenceRecord captures one policy check: policy name, pass flag, details, the validator version that produced it, and a timestamp.

EvidencePackage is immutable once constructed. It carries a package id, the SHA-256 of the validated document, the records, aggregate counts, a generation time, and an optional RFC 3161 timestamp token. allPassed() and passRate() summarize it. Its immutability makes a package suitable for write-once-read-many (WORM) storage.

EvidenceExporter serializes a package to a deterministic JSON string — fixed key order, reproducible — so exportHash() returns a stable 64-character SHA-256 digest for integrity verification. The same package always yields the same digest, independent of when or where it is computed.

ContinuousMonitor re-validates a document and diffs current evidence against the stored prior evidence by failed policy name, categorizing issues as new, resolved, or unchanged, and exposing a schedule check (isDue() / MonitorSchedule / MonitorFrequency). This supports drift detection across time; it reports what changed.

What “evidence” means here

This module packages and timestamps validation findings for audit workflows.

• An RFC 3161 timestamp token binds the package datum to a time value: it provides evidence the data existed before that time.
• A sealed package with allPassed() === true records that the included checks passed against the rules they implement.
• The deterministic digest proves integrity of the package bytes.

Evidence capture supports audit workflows. Validity and conformance remain properties of the final file plus a validator.

Tier boundary

Evidence packaging is an Enterprise-only surface. Core and Pro produce findings and reports; Enterprise Evidence seals those findings into an immutable, deterministic, optionally timestamped package and tracks regressions. It depends on findings produced elsewhere (the Validation or Compliance surfaces); it does not itself perform conformance checks.

Why it works this way

Evidence is only useful if it cannot be quietly rewritten afterwards, so EvidencePackage is a sealed readonly value with no mutators — safe for write-once-read-many storage. The exporter’s toJson() output follows a fixed key insertion order, not run-time sorting, so the same package always serializes to identical bytes. That byte-stability lets a stored exportHash() verify integrity later: any change to the package changes the digest. The RFC 3161 token is kept as embedded evidence of time, never a verdict, so a package proves when a check ran without asserting the document is compliant. Regression tracking then diffs by failed policy name against the prior package, so drift detection stays independent of check ordering or count.

Design background: Compliance you can hand to an auditor.

API surface

Class	Responsibility
EvidencePortal	Assemble, persist, and retrieve evidence packages.
EvidencePackage	Immutable sealed bundle of records with aggregate stats.
EvidenceRecord	One policy check result with validator version and timestamp.
EvidenceExporter	Deterministic JSON serialization; stable SHA-256 digest.
EvidenceStoreInterface	Persistence contract.
InMemoryEvidenceStore	Reference in-memory store implementation.
ContinuousMonitor	Re-validate and diff against prior evidence.
MonitorResult	New / resolved / unchanged issue categorization.
MonitorSchedule / MonitorFrequency	Schedule-based polling.

Code sample — Quick start

$package = $portal->generateEvidence($documentHash, $records);
$digest  = $exporter->exportHash($package); // 64-char SHA-256

Code sample — Production

$package = $portal->generateEvidence($documentHash, $records, $tsaToken);
$logger->info('evidence.sealed', [
    'package'   => $package->packageId,
    'digest'    => $exporter->exportHash($package),
    'pass_rate' => $package->passRate(),
]);

$delta = $monitor->check($package, $documentHash);
if ($delta->newIssues !== []) {
    $logger->warning('evidence.regression', ['count' => count($delta->newIssues)]);
}
// The package is audit-supporting evidence, not an attestation of compliance.

Edge cases & gotchas

• passRate() returns 0.0 when there are no findings; an empty package is not a pass.
• The export is deterministic only through EvidenceExporter; hashing arbitrary serializations breaks the stable-digest guarantee.
• A package without a TSA token is still valid evidence; the token adds a time binding, not a verdict.

Performance

Packaging and deterministic serialization scale linearly with record count. Digest computation is a single SHA-256 pass over the serialized JSON.

Security notes

The package digest provides tamper-evidence for the package bytes. The optional RFC 3161 token must come from a trusted TSA; this module embeds the token, it does not vouch for the TSA. Treat record details as potentially sensitive (see below).

Data residency & PII mitigations

Evidence records and document hashes may reference regulated content. Packaging is in-process; persistence is delegated to your EvidenceStoreInterface implementation, so residency follows your store. Apply retention and minimization controls to stored packages.

Safe telemetry & log scrubbing

Package metadata (ids, digests, counts) is safe to log. Record details may echo finding messages that contain extracted document strings; scrub those before forwarding to shared sinks.

Conformance

Behavior	Reference	Status
Time-stamp token binds a datum to a time	IETF RFC 3161 §2	Token embedded (TSA-supplied)
DSS / long-term validation context	ISO 32000-2:2020 §12.8	Referenced (consumed, not produced here)

This table records the specifications this module is built against. A timestamp token is evidence of time.

FIPS-mode behavior

This module computes SHA-256 over package bytes and embeds a caller-supplied RFC 3161 token. It performs no signing and no key custody; cryptographic operations and FIPS-mode behavior are handled by the Security and Signature modules.

Threat model

Inputs are findings and an optional TSA token. Mitigations: immutable packages, deterministic serialization with a stable integrity digest, and delegated persistence so the store enforces WORM and access control.

Behavior contract

• The portal assembles findings into an immutable, sealed package with a package id, the validated-document SHA-256, records, aggregate counts, generation time, and an optional RFC 3161 timestamp token.
• The exporter serializes a package to a deterministic JSON string with a fixed key order so the digest is a stable 64-character SHA-256, identical regardless of when or where it is computed.
• The continuous monitor re-validates and diffs current evidence against the stored prior evidence by failed policy name, categorizing issues as new, resolved, or unchanged.
• passRate() returns 0.0 when there are no findings — an empty package is not a pass; a package without a TSA token is still valid evidence.
• A timestamp token is evidence the data existed before a time.

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.

Core fallback

Core and Pro produce findings and reports; sealing those findings into an immutable, deterministic, optionally timestamped package with regression tracking has no Core-tier equivalent. The Enterprise surface depends on findings produced elsewhere; it does not itself perform conformance checks.

Pro fallback

Pro fallback — none; this capability has no Pro-tier equivalent. The sealed evidence package, the deterministic exporter, and the continuous monitor ship in the nextpdf/enterprise package only; the surface consumes findings from the Validation or Compliance surfaces.

Enterprise boundary note

The portal, package, exporter, and monitor are described at the behavior level. The reference in-memory store is documented; durable persistence is supplied by the host, and any internal store internals are out of scope for the public surface. This module embeds a caller-supplied TSA token; it does not vouch for the TSA.

Deployment boundary

Packaging and serialization are in-process. The operator supplies a durable store implementation, is responsible for WORM enforcement and access control, and supplies a TSA token from a trusted TSA. Evidence records and document hashes may reference regulated content; residency follows the operator’s store, and retention and minimization controls are the operator’s responsibility.

Legal-compliance boundary

Evidence capture supports audit workflows, and validity and conformance remain properties of the final file plus a validator.

See also

• Validation — produces the findings packaged here.
• Compliance — external validator results.
• AST audit trail — append-only mutation history.
• Specifications: PAdES — long-term validation context.
• Evidence — Deep Reference — full class-level API reference.