Data handling, PII, and telemetry

At a glance

This page describes how the core engine handles data: what it reads, what it keeps in process memory, what it writes, the deterministic personally identifiable information (PII)-scrubbing transform it applies to audit bundles, and the opt-in telemetry path.

Boundary. This page describes library behavior. Deployment-level data residency covers which jurisdiction processes your documents, where temporary files are stored, how long output is retained, and which telemetry backend, if any, receives spans. Those choices are the integrator’s responsibility. The engine gives you fail-closed defaults and a scrubbing transform; data-residency and lawful-basis decisions rest with the integrator.

Install

composer require nextpdf/core:^3

The PII scrubber and telemetry interceptor are part of the core package. The telemetry path stays inert unless an OpenTelemetry SDK is present and the caller wires the interceptor.

Conceptual overview

The engine acts as a processor for the data you hand it, in the ISO/IEC 29100 sense: it works on document content under the integrator’s instruction. It does not phone home, persist content beyond the output you request, or transmit document content to any NextPDF-operated endpoint.

The open-source Core described here has no licence client and makes no network calls at all. Premium editions add one narrow exception that never involves your content: on the ionCube delivery channel, NextPDF’s licence verification contacts the licence service periodically, sending only a licence identifier and a salted fingerprint hash — never document content, a raw fingerprint, or an IP address. See Two delivery channels.

Three data surfaces matter:

1. Document input/output (I/O). The engine reads input from the path or stream you provide and writes output to the path or stream you provide. Intermediate buffers stay in process memory for the duration of the render and are released when it completes.
2. Audit bundles. When auditing is enabled, the engine can emit a diagnostic bundle. Before serialization, that bundle passes through a deterministic PII scrubber.
3. Telemetry. An optional OpenTelemetry interceptor can emit spans and metrics. It remains off unless the SDK is installed and the interceptor is constructed; span attributes pass through an attribute sanitizer.

The privacy posture follows the GDPR Art. 32 principle that pseudonymisation and minimization are example safeguards. Applying those safeguards is the controller’s responsibility. The library supplies the scrubbing mechanism. The controller decides the lawful basis, retention, and residency.

API surface

The trust-relevant components are the default PII sanitizer applied to audit bundles and the OpenTelemetry interceptor’s attribute sanitizer. The sections below describe their effects; the full audit and telemetry APIs are documented in the Core audit module reference.

Code sample — Quick start

By default, nothing leaves the process: network egress happens only when you explicitly configure it.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

// Input read from disk, output written to disk. No telemetry SDK loaded,
// so the telemetry path completes in sub-microsecond no-ops. No content
// is transmitted anywhere.
$doc = Document::open('input.pdf');
$doc->save('output.pdf');

Code sample — Production

When an audit bundle is produced, the deterministic PII scrubber masks common categories before serialization. The transform is pure (no clocks, no randomness), so a bundle is byte-stable for a given input:

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Audit\DefaultPiiSanitiser;

$scrubber = new DefaultPiiSanitiser();
// E-mail → [EMAIL], IPv4 → [IPV4], IPv6 → [IPV6], X.500 DN attributes
// beyond CN → keyword preserved, value [REDACTED]. Deterministic.
$safe = $scrubber->sanitise($rawAuditField);

Edge cases & gotchas

• The scrubber masks defined categories. DefaultPiiSanitiser masks RFC 5321 e-mail addresses, IPv4/IPv6 addresses, and several RFC 4514 distinguished name (DN) attributes. Free-text content outside those patterns passes through unchanged, so treat the scrubber as a defense-in-depth layer and review audit bundles before sharing them.
• Temporary files are the deployment’s concern. The engine uses secure temporary-file handling. Where your TMPDIR resides, and whether TMPDIR is on encrypted storage in the right jurisdiction, are deployment decisions.
• Telemetry is opt-in and sanitized. When wired, the OpenTelemetry interceptor passes span attributes through an attribute sanitizer that enforces a zero-trust data policy. The backend you export to, and its retention and location, are the integrator’s choice.
• Lawful basis is a controller decision. The controller determines whether processing a given document is lawful, and on what basis, under GDPR / local law.

Performance

The PII scrubber uses pure regex transforms with no I/O. The telemetry interceptor checks for SDK presence once at construction and caches the result. When no SDK is installed, every telemetry call completes in sub-microsecond time, so the privacy-preserving default (telemetry off) is also the zero-overhead default.

Security notes

For reviewers, the data-handling boundary rules are:

1. No covert egress. The engine transmits no document content to any NextPDF-operated endpoint. Outbound network access happens only on explicitly enabled, scheme-restricted resource fetches and on configured time-stamp authority (TSA), Online Certificate Status Protocol (OCSP), and certificate revocation list (CRL) endpoints, each behind the server-side request forgery (SSRF) guard.
2. Deterministic, bounded scrubbing. The audit-bundle PII transform is deterministic and runs before serialization. It is a minimization aid in the spirit of GDPR Art. 32.
3. Residency is the integrator’s. Inventory and mapping of where data is processed are organizational activities per the NIST Privacy Framework; the library exposes the controls, and the integrator performs the mapping.
4. Roles are a deployment determination. Whether the deployment acts as a controller or a processor, and which obligations follow, is an ISO/IEC 29100 role determination made by the deploying organization.

Conformance

This page references GDPR Art. 32, ISO/IEC 29100, and the NIST Privacy Framework to locate the boundary between library behavior and controller responsibility. Compliance and certification determinations are made by the data controller at the deployment level.

See also

• Trust center
• Engine threat model
• Signature and encryption security model
• Core audit module reference