Privacy

At a glance

NextPDF Enterprise Privacy detects text matching configured PII patterns and either redacts it, suppresses the lines that contain it, or replaces it with reversible deterministic pseudonyms backed by an encrypted at-rest map. It removes content matching the configured rules as tested.

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

Detection is pattern-based. A detector scans text against a registry of regular-expression patterns and ships built-in patterns for email addresses, phone numbers, United States Social Security numbers, credit-card numbers, and Taiwan national-ID numbers. A deployment may register additional patterns. Detection finds the configured types only; a value that no pattern matches is not detected, and a scanned page with no text layer yields no matches.

A redaction policy controls behavior. In detect-only mode the engine returns findings without changing content. In redaction mode it replaces each matched span with a black-box, white-box, or text replacement. The de-identifier adds a suppression strategy that removes whole lines containing a match instead of masking individual spans. Each run returns the SHA-256 of the original text, the modified content, an itemized report, and a modified flag.

Pseudonymization is reversible by design. The engine replaces detected entities with deterministic, format-aware pseudonyms derived from an HMAC over the original value and a per-session seed, so the same value maps consistently within a session, while across sessions the tokens do not correlate by deterministic equality. The original-to-pseudonym map is serialized and encrypted at rest with AES-256-GCM and a versioned key, supporting key rotation. Rehydration restores original values, but only with the correct key and the matching encrypted map; without them the original values are not recoverable from the pseudonymized text alone.

These operations implement de-identification, which removes the association between the data and the person — ISO/IEC 29100:2024 §2. Pseudonymization replaces an identifier with an alias and is, by definition, reversible with the separately held mapping — ISO/IEC 29100:2024 §2. Anonymization aims to irreversibly prevent identification — ISO/IEC 29100:2024 §2; this Enterprise surface performs pattern-scoped redaction, suppression, and reversible pseudonymization, not anonymization. Residual re-identification risk depends on the attributes that remain after de-identification — ISO/IEC 29100:2024 §2, and de-identification reduces but does not eliminate that risk — ISO/IEC 29151:2017. Treat the output as content matching the configured rules removed or replaced as tested.

Why it works this way

Reversibility is the load-bearing choice. Pseudonyms are HMAC-SHA256 outputs over the original value and a per-session seed, so the same value maps to the same token throughout a session and the document’s internal relationships survive. A fresh random seed per session means the same value does not map to the same token across sessions, so the pseudonyms do not correlate by deterministic token equality across sessions, which reduces deterministic linkability without a central lookup. The mapping is deliberately kept — encrypted at rest with AES-256-GCM — so authorized rehydration can restore the originals; that reversibility is what makes this pseudonymization under ISO/IEC 29100:2024 §2, not anonymization. The tradeoff is accepted: the encrypted map, not the pseudonymized text, becomes the sensitive artifact, so confidentiality reduces to key custody. Format-aware tokens preserve each entity’s shape, so downstream parsers keep working, at the cost that checksum validators may reject a shaped-but-synthetic value.

Design background: Redaction is not a black rectangle.

API surface

Type	Kind	Role	Stability	Since
PiiDetector	class	Pattern-based PII detection; supports custom pattern registration	stable	2.2.0
RedactionEngine	class	Detect-only or destructive text redaction by policy	stable	2.2.0
DeIdentifier	class	Redact or line-suppress strategy dispatch	stable	2.2.0
RedactionPolicy	class	Target entity types, redaction toggle, replacement style	stable	2.2.0
PseudonymizationEngine	class	Deterministic, format-aware pseudonym replacement	stable	2.2.0
PrivacyGateway	class	Document-scoped pseudonymize/rehydrate with audit	stable	2.2.0
RehydrationService	class	Restores originals from an encrypted map	stable	2.2.0
EncryptedMapSerializer	class	AES-256-GCM at-rest map serialization with key versioning	stable	2.2.0
PrivacyAuditTrail	class	Append-only log of pseudonymize/rehydrate operations	stable	2.2.0
EntityType / RedactionStyle / DeIdentificationStrategy	enums	Entity, style, and strategy vocabulary	stable	2.2.0

The audit trail is append-only by contract: it logs a session id, operation, entity count, a policy hash, a timestamp, and a tenant id. It does not record the detected values.

Code sample — Quick start

Detect and redact configured PII

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Privacy\PiiDetector;
use NextPDF\Enterprise\Privacy\RedactionEngine;
use NextPDF\Enterprise\Privacy\RedactionPolicy;

/**
 * Redact every configured entity type from text content.
 *
 * @param string $content The text to process.
 *
 * @return string The redacted text.
 */
function redactAll(string $content): string
{
    $engine = new RedactionEngine(new PiiDetector());

    return $engine->redact($content, RedactionPolicy::allEntities())
        ->redactedContent;
}

RedactionPolicy::allEntities() targets the built-in types. A value that no configured pattern matches is not redacted.

Code sample — Production

Reversible pseudonymization with audit and safe logging

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Privacy\PrivacyGateway;
use NextPDF\Enterprise\Privacy\PrivacyPolicy;
use NextPDF\Enterprise\Privacy\EntityType;
use Psr\Log\LoggerInterface;

final readonly class DocumentDeidentifier
{
    public function __construct(
        private PrivacyGateway $gateway,
        private LoggerInterface $logger,
    ) {}

    /**
     * Pseudonymize a document and return the encrypted reversal map.
     *
     * @param non-empty-string                                      $text     Document text.
     * @param list<array{text: non-empty-string, type: EntityType}> $entities Detected entities.
     *
     * @return array{text: string, encrypted_map: non-empty-string}
     */
    public function process(string $text, array $entities): array
    {
        $policy = PrivacyPolicy::piiOnly('session-' . bin2hex(random_bytes(6)));
        $result = $this->gateway->pseudonymize($text, $entities, $policy);

        $this->logger->info('Pseudonymization complete', [
            'entityCount' => $result['entity_count'],
        ]);

        return ['text' => $result['text'], 'encrypted_map' => $result['encrypted_map']];
    }
}

The log record carries a count only. It does not carry the document text, the detected values, or the encrypted map.

Edge cases & gotchas

• Detection is pattern-scoped. A value no pattern matches is not detected.
• Scanned pages have no text layer. Text-pattern detection yields no matches; combine with the Intelligence searchable-overlay surface if text is required first.
• Pseudonymization is reversible by definition. Anyone with the correct key and the matching encrypted map can restore the originals. This is not anonymization; do not present pseudonymized output as irreversible.
• Format-aware pseudonyms preserve a shape (for example, an ID-like or email-like token). A downstream system that validates checksums may reject a pseudonym; that is expected.
• The encrypted map is the sensitive artifact. Losing it makes rehydration impossible; leaking it with its key makes the pseudonymization reversible by a third party. Treat key custody and map storage as a deployment responsibility.
• Redaction operates on the text content passed to it. It does not by itself flatten an image, remove a thumbnail, or strip document metadata; scope the pipeline accordingly.

Performance

Detection cost scales with the pattern count and the text length. Pseudonymization adds an HMAC per unique entity and an AES-256-GCM seal of the map. The 1500 ms wall budget covers a typical business document. The reproducibility profile is structural: pseudonyms are deterministic for a fixed seed, but the audit timestamp and the random session seed vary between runs, so two runs differ in those fields.

Security notes

The at-rest map uses authenticated encryption. The map is sealed with AES-256-GCM and a versioned key; rehydration is impossible without the correct key version. Key generation, custody, and rotation are the deployment’s responsibility; the library consumes a key, it does not manage a key store. The audit trail is append-only and records metadata, never detected values. Every normative source is paraphrased and none is reproduced.

Data residency & PII mitigations

Detection, redaction, and pseudonymization run in-process on the host. No document content leaves the host for any of these operations. The encrypted map and any rehydrated output are personal data; where they are stored, and which jurisdiction processes them, is a deployment responsibility outside the library’s boundary. The library performs pattern-scoped de-identification as tested, and it does not perform anonymization. Residual re-identification risk depends on the attributes that remain — ISO/IEC 29151:2017.

Safe telemetry & log scrubbing

The library raises typed exceptions with structural messages and never places detected values, document bytes, or the encrypted map into exception text. A deployment that logs around this surface must log counts and the policy hash — as shown in the production sample — and must not log the raw PDF payload, detected entity text, or the pseudonym map to logs or an APM backend. The append-only audit trail is the safe record to retain.

FIPS-mode behavior

The at-rest map uses AES-256-GCM through the platform crypto provider. When the host runs a FIPS-validated provider, that operation runs in the validated boundary. NextPDF Enterprise performs the structural assembly.

Conformance

Claim	Standard	Clause
De-identification removes the association between data and the person.	ISO/IEC 29100:2024	§2
Pseudonymization replaces an identifier with an alias and is reversible with the separate mapping.	ISO/IEC 29100:2024	§2
Anonymization aims to irreversibly prevent identification (this surface does not anonymize).	ISO/IEC 29100:2024	§2
Residual re-identification risk depends on the remaining attributes.	ISO/IEC 29100:2024	§2
Privacy controls are applied to PII.	ISO/IEC 29100:2024	§6.5
De-identification reduces but does not eliminate residual risk.	ISO/IEC 29151:2017	de-identification controls
Minimize linkability of de-identified data.	ISO/IEC 29151:2017	PII minimization
Controls are applied to protect PII.	ISO/IEC 29151:2017	controls

All clauses are paraphrased. NextPDF does not reproduce normative text. Consult the published standards for the authoritative wording.

Behavior contract

• Detection is pattern-scoped: it finds the configured types only; a value no pattern matches is not detected and a page with no text layer yields no matches.
• A redaction policy selects detect-only, span replacement (black-box / white-box / text), or whole-line suppression; each run returns the original-text SHA-256, the modified content, an itemized report, and a modified flag.
• Pseudonymization is reversible by design: deterministic HMAC-derived pseudonyms are consistent within a session, and rehydration requires the correct key version and the matching AES-256-GCM at-rest map.
• The append-only audit trail records session id, operation, entity count, policy hash, timestamp, and tenant id — never the detected values.
• Output is content matching the configured rules removed or replaced as tested.

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 PII detection, redaction, or pseudonymization surface — none; this capability has no Core-tier equivalent.

Pro fallback

NextPDF Pro ships a text-layer PII detection surface and generation-time masking; it does not provide reversible pseudonymization, the encrypted at-rest map, line suppression, or the append-only audit trail. Those ship in the nextpdf/enterprise package only.

Enterprise boundary note

Detection, redaction, suppression, and pseudonymization are described at the behavior level. The library consumes an encryption key; it does not manage a key store, and key generation, custody, and rotation internals are out of scope for the public surface.

Deployment boundary

The encrypted map and any rehydrated output are personal data; where they are stored and which jurisdiction processes them is a deployment responsibility outside the library’s boundary. Key generation, custody, and rotation are the deployment’s responsibility — the library consumes a key version, it does not manage a key store. Losing the map makes rehydration impossible; leaking it with its key makes the pseudonymization reversible by a third party.

Legal-compliance boundary

The at-rest map uses authenticated encryption. The library performs pattern-scoped de-identification as tested and does not perform anonymization. This documentation is not a legal opinion; consult your own compliance and legal advisers.

See also

• Privacy reference — the full public API surface for the Privacy module.
• Pro security — Pro masking and text-layer PII detection.
• Forensics — read-only revision-history analysis.
• NextPDF Enterprise — the full Enterprise feature surface.
• Privacy policy — the documentation program’s own data handling.
• PII · Pseudonymization · De-identification · AES-GCM — glossary terms.