aeat.adapters.inbound.sanitizer._pipeline module

Top-level orchestrator for adapters.inbound.sanitizer.

Implements the canonical sanitiser pipeline:

  1. Open source bytes; refuse if signed; refuse if already sanitised.

  2. Strip dynamic surfaces (attachments, JS, OpenAction/AA, annotations, OCG, AcroForm).

  3. Drop page thumbnails.

  4. Drop outlines + page labels.

  5. Drop Root.StructTreeRoot (lossy).

  6. Rewrite content streams against the TokenMap.

  7. Scrub static metadata (DocInfo + XMP).

  8. Save with deterministic flags.

Order matters: dynamic surfaces precede the content rewrite so a JS action cannot re-inject PII the rewriter just stripped. The content rewrite precedes the metadata scrub because some XMP-write paths in pikepdf re-stamp metadata if they detect a content change. The deterministic save runs last so byte-stable output captures every prior mutation.

The library function is a pure transformer over bytes | Path plus a declarative token map. It returns sanitised bytes and an audit record; CLI or workflow code decides whether to write those bytes to disk.

sanitize_pdf(source, mapping, *, drop_attachments=True, drop_javascript=True, drop_annotations=True, drop_outlines=True, drop_optional_content_groups=True, drop_struct_tree=True, drop_acroform=False, scrub_docinfo_dict=True, scrub_xmp_packet=True, scrub_xmp_strategy='delete', refuse_if_already_sanitized=True)[source]

Strip PII from source against mapping.

Parameters:

  • source (bytes | Path) – Raw bytes of the source PDF, or a Path pointing to it. Path inputs are read once at the top of the function.

  • mapping (TokenMap) – Declarative cleartext-to-synthetic TokenMap. Real values are consumed in memory through SecretStr fields; callers must keep any serialized mapping files outside git.

  • drop_attachments (bool) – When True, removes every embedded file.

  • drop_javascript (bool) – When True, removes embedded JavaScript and document-level actions (OpenAction, AA).

  • drop_annotations (bool) – When True, drops every page annotation.

  • drop_outlines (bool) – When True, drops the outline tree.

  • drop_optional_content_groups (bool) – When True, removes Root.OCProperties.

  • drop_struct_tree (bool) – When True, drops Root.StructTreeRoot (and emits structtree_dropped_lossy warning when the tree was present).

  • drop_acroform (bool) – When True, deletes Root.AcroForm entirely; otherwise clears field values in place.

  • scrub_docinfo_dict (bool) – When True, deletes the legacy DocInfo dictionary.

  • scrub_xmp_packet (bool) – When True, scrubs the XMP packet via the scrub_xmp_strategy policy.

  • scrub_xmp_strategy (Literal['delete', 'rewrite']) – "delete" (default) drops the entire XMP packet; "rewrite" clears only the PII-bearing keys.

  • refuse_if_already_sanitized (bool) – When True, raises AlreadySanitizedError if source SHA-256 is in fixtures.SANITIZED_SHAS. Pass False to opt out (useful when intentionally re-sanitising an existing fixture against an extended TokenMap).

Return type:

SanitizationResult

Returns:

A SanitizationResult carrying the sanitised bytes, audit log, and warnings. The function itself does not write the PDF or audit record to disk.

Raises: