Enterprise edition

Forensics — Deep Reference

At a glance

This deep reference documents how revisions are bounded, how object changes are classified across the revision chain, and how events are grouped.

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.

The analyzer is read-only and does not modify the input.

Behavior contract

ForensicAnalyzer::analyze parses every cross-reference section, derives a per-revision byte boundary (start, end, size), and builds a per-revision summary. It then walks from the newest revision toward the oldest, and for each revision compares its cross-reference entries against the next older revision:

An object present now but absent in the older revision, and not a free entry, is classified Added.
An object that is a free entry now but was not free before is classified Deleted, with the previous revision recorded.
An object active in both revisions whose byte offset differs is classified Modified, with the previous revision recorded.

Object changes are grouped per revision into events: a signature revision that was not signed in the older revision yields SignatureAdded; a root update yields CatalogUpdated; an encryption dictionary that appears yields EncryptionChanged; and added, modified, or deleted object sets yield the corresponding object events. Signature presence is a structural heuristic (a Document Security Store entry in the trailer): it is existence detection, not validation, and not a tamper-proof determination of integrity.

An update’s cross-reference section lists only objects added, modified, or deleted in that update (ISO 32000-2:2020 §7.5.5); a changed object is appended as a new copy and its offset overrides the older one (§7.5.6); a Document Security Store may appear in a later revision (§12.8.4).

Public API surface

NextPDF\Enterprise\Forensics\ForensicAnalyzer, NextPDF\Enterprise\Forensics\ForensicReport, NextPDF\Enterprise\Forensics\RevisionSummary, NextPDF\Enterprise\Forensics\ForensicEvent, NextPDF\Enterprise\Forensics\ForensicEventType, NextPDF\Enterprise\Forensics\ObjectChange, NextPDF\Enterprise\Forensics\ObjectChangeType. Signatures are listed on the public page.

Conformance

The classification mirrors the incremental-update model of ISO 32000-2:2020 §7.5.5–§7.5.6. The analyzer reports the parser’s view of the chain; it does not certify integrity and is not court-admissible evidence on its own.

Edge cases & FIPS-mode behavior

A Deleted classification is a free-entry transition; an older copy of the object may still be resolvable. It is not a guarantee of unrecoverability.
Trailer info is filtered to a safe key set; sensitive keys are noted as present without exposing their values.
No cryptographic operation occurs in this module, so there is no FIPS-mode-specific behavior.

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

NextPDF Core (Apache-2.0) has no revision-history forensic analyzer — none; this capability has no Core-tier equivalent. Core supplies the authoritative signature-validation surface, which the analyzer composes with but does not replace.

Pro fallback

NextPDF Pro has no revision-history forensic analyzer — none; this capability has no Pro-tier equivalent. The per-object change classification and the JSON-serializable report ship in the nextpdf/enterprise package only.

Enterprise boundary note

The revision-boundary derivation, the object-change classification rules, and the event-timeline grouping are described at the behavior level. Signature presence is a structural heuristic only; signature validity is deliberately out of scope here — it is the Core signing surface’s responsibility. Trailer info is filtered to a safe key set and sensitive keys are noted as present without exposing their values.

Deployment boundary

Analysis runs in-process on the host that holds the PDF; no document content leaves the host. Whether the input PDF or the report contains personal data, and where each is stored, is a deployment responsibility outside the library’s boundary. The operator draws conclusions from the report; the library reports the parser’s view of the revision chain and does not certify integrity.

Legal-compliance boundary

No export-control restriction applies to this surface. The report is not court-admissible evidence on its own and must not be presented as a certified determination of document integrity. This reference is not a legal opinion.