pdfblinder 0.1.0__tar.gz

pdfblinder-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 foivoskar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pdfblinder-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: pdfblinder
+Version: 0.1.0
+Summary: Reconstruct and sanitize PDFs for anonymous review.
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pikepdf<11,>=10.17
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=9; extra == "dev"
+Requires-Dist: Pillow>=10; extra == "dev"
+Dynamic: license-file
+
+# PDFblinder
+
+A Python command-line tool that reconstructs PDFs with Ghostscript,
+removes selected structural metadata and auxiliary objects with pikepdf,
+and verifies the serialized result before creating the destination file.
+
+Designed for preparing documents for double-blind review.
+
+## Requirements
+
+- Python 3.11 or newer.
+- Ghostscript installed separately.
+- Ghostscript available as `gs`, `gswin64c`, or `gswin32c`,
+  or supplied explicitly with `--gs`.
+
+The current local test run covers macOS. Linux and Windows compatibility
+must also be validated before claiming support on those systems.
+
+## Installation
+
+From the project directory, create a virtual environment:
+
+```sh
+python -m venv .venv
+```
+
+Activate it on macOS or Linux:
+
+```sh
+source .venv/bin/activate
+```
+
+Or activate it in Windows PowerShell:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+Install PDFblinder:
+
+```sh
+python -m pip install .
+```
+
+## Usage
+
+```sh
+pdfblinder input.pdf output.pdf
+```
+
+Paths containing spaces must be quoted:
+
+```sh
+pdfblinder "original manuscript.pdf" "review copy.pdf"
+```
+
+Select a Ghostscript executable or change its timeout:
+
+```sh
+pdfblinder --gs "/path/to/gs" --timeout 300 input.pdf output.pdf
+```
+
+The module entry point is also available:
+
+```sh
+python -m pdfblinder input.pdf output.pdf
+```
+
+The destination must not already exist. The original file is preserved.
+The output directory must already exist.
+
+Exit codes: `0` for success, `1` for processing failure,
+`2` for invalid command-line arguments, and `130` for interruption.
+
+## Processing and verification
+
+1. Copy the input into a private temporary working directory.
+2. Reject encrypted PDFs, empty documents, and documents with AcroForm
+   forms or signature fields.
+3. Reconstruct pages using Ghostscript's `pdfwrite` device.
+   Annotations are discarded rather than painted onto the pages.
+4. Create a new PDF from the reconstructed pages. Restrict page fields,
+   strip selected auxiliary dictionary fields, and remove unused resources.
+5. Reopen the serialized candidate. Check the page count, document catalog,
+   absence of document information metadata, forbidden fields and object
+   types, document identifiers, and PDF syntax.
+6. Create the destination exclusively and copy the verified bytes into it.
+
+Temporary working files are cleaned up on normal completion and handled
+exceptions. Abrupt process termination or power loss may leave temporary
+files or an incomplete destination.
+
+## Scope and limitations
+
+PDFblinder performs structural sanitation, not guaranteed anonymization.
+
+- Names, affiliations, acknowledgements, citations, watermarks, and other
+  identifying visible content remain.
+- Embedded font and image payloads are not exhaustively inspected or
+  anonymized. Reconstruction can retain distinctive document features.
+- The structural checks enforce a defined policy; they cannot prove that
+  every possible identifying byte or covert channel has been eliminated.
+- Comments, highlights, links, and other annotations are discarded.
+  Bookmarks, document tags, and accessibility structure are not preserved.
+- Forms and signature fields are rejected to avoid silently losing their
+  appearance or misrepresenting signatures.
+- Page count and syntax checks do not establish full visual equivalence.
+  Inspect every output before submission.
+- Output identifiers are newly generated; original identifiers are checked
+  for reuse. Filesystem timestamps and permissions are newly created.
+  The output filename is chosen by the user.
+- Ghostscript and pikepdf must be kept updated. Ghostscript's SAFER mode
+  is enabled, but it is not a complete operating-system sandbox.
+- The timeout applies to Ghostscript reconstruction, not the entire job.
+
+## Development
+
+```sh
+python -m pip install -e '.[dev]'
+python -m pytest -q
+```
+
+Tests cover reconstruction, sanitation, verification, CLI behavior,
+overwrite protection, failure handling, text preservation, and a rendered
+comparison of a synthetic page containing text and vector graphics.
+
+Test PDFs are generated in temporary directories. No private documents
+are needed in the repository.
+
+## License
+
+PDFblinder's original code and documentation are licensed under the
+[MIT License](LICENSE), copyright (c) 2026 foivoskar.
+
+Third-party dependencies retain their own licenses. Ghostscript is installed
+separately and is not bundled with PDFblinder. It is available under the
+GNU AGPL or a commercial license from Artifex.
+
+The MIT license for PDFblinder does not waive any third-party obligations.
+Before redistributing Ghostscript or deploying a hosted PDF-processing
+service, evaluate the applicable Ghostscript licensing terms:
+https://www.ghostscript.com/licensing/

pdfblinder-0.1.0/README.md

@@ -0,0 +1,142 @@
+# PDFblinder
+
+A Python command-line tool that reconstructs PDFs with Ghostscript,
+removes selected structural metadata and auxiliary objects with pikepdf,
+and verifies the serialized result before creating the destination file.
+
+Designed for preparing documents for double-blind review.
+
+## Requirements
+
+- Python 3.11 or newer.
+- Ghostscript installed separately.
+- Ghostscript available as `gs`, `gswin64c`, or `gswin32c`,
+  or supplied explicitly with `--gs`.
+
+The current local test run covers macOS. Linux and Windows compatibility
+must also be validated before claiming support on those systems.
+
+## Installation
+
+From the project directory, create a virtual environment:
+
+```sh
+python -m venv .venv
+```
+
+Activate it on macOS or Linux:
+
+```sh
+source .venv/bin/activate
+```
+
+Or activate it in Windows PowerShell:
+
+```powershell
+.\.venv\Scripts\Activate.ps1
+```
+
+Install PDFblinder:
+
+```sh
+python -m pip install .
+```
+
+## Usage
+
+```sh
+pdfblinder input.pdf output.pdf
+```
+
+Paths containing spaces must be quoted:
+
+```sh
+pdfblinder "original manuscript.pdf" "review copy.pdf"
+```
+
+Select a Ghostscript executable or change its timeout:
+
+```sh
+pdfblinder --gs "/path/to/gs" --timeout 300 input.pdf output.pdf
+```
+
+The module entry point is also available:
+
+```sh
+python -m pdfblinder input.pdf output.pdf
+```
+
+The destination must not already exist. The original file is preserved.
+The output directory must already exist.
+
+Exit codes: `0` for success, `1` for processing failure,
+`2` for invalid command-line arguments, and `130` for interruption.
+
+## Processing and verification
+
+1. Copy the input into a private temporary working directory.
+2. Reject encrypted PDFs, empty documents, and documents with AcroForm
+   forms or signature fields.
+3. Reconstruct pages using Ghostscript's `pdfwrite` device.
+   Annotations are discarded rather than painted onto the pages.
+4. Create a new PDF from the reconstructed pages. Restrict page fields,
+   strip selected auxiliary dictionary fields, and remove unused resources.
+5. Reopen the serialized candidate. Check the page count, document catalog,
+   absence of document information metadata, forbidden fields and object
+   types, document identifiers, and PDF syntax.
+6. Create the destination exclusively and copy the verified bytes into it.
+
+Temporary working files are cleaned up on normal completion and handled
+exceptions. Abrupt process termination or power loss may leave temporary
+files or an incomplete destination.
+
+## Scope and limitations
+
+PDFblinder performs structural sanitation, not guaranteed anonymization.
+
+- Names, affiliations, acknowledgements, citations, watermarks, and other
+  identifying visible content remain.
+- Embedded font and image payloads are not exhaustively inspected or
+  anonymized. Reconstruction can retain distinctive document features.
+- The structural checks enforce a defined policy; they cannot prove that
+  every possible identifying byte or covert channel has been eliminated.
+- Comments, highlights, links, and other annotations are discarded.
+  Bookmarks, document tags, and accessibility structure are not preserved.
+- Forms and signature fields are rejected to avoid silently losing their
+  appearance or misrepresenting signatures.
+- Page count and syntax checks do not establish full visual equivalence.
+  Inspect every output before submission.
+- Output identifiers are newly generated; original identifiers are checked
+  for reuse. Filesystem timestamps and permissions are newly created.
+  The output filename is chosen by the user.
+- Ghostscript and pikepdf must be kept updated. Ghostscript's SAFER mode
+  is enabled, but it is not a complete operating-system sandbox.
+- The timeout applies to Ghostscript reconstruction, not the entire job.
+
+## Development
+
+```sh
+python -m pip install -e '.[dev]'
+python -m pytest -q
+```
+
+Tests cover reconstruction, sanitation, verification, CLI behavior,
+overwrite protection, failure handling, text preservation, and a rendered
+comparison of a synthetic page containing text and vector graphics.
+
+Test PDFs are generated in temporary directories. No private documents
+are needed in the repository.
+
+## License
+
+PDFblinder's original code and documentation are licensed under the
+[MIT License](LICENSE), copyright (c) 2026 foivoskar.
+
+Third-party dependencies retain their own licenses. Ghostscript is installed
+separately and is not bundled with PDFblinder. It is available under the
+GNU AGPL or a commercial license from Artifex.
+
+The MIT license for PDFblinder does not waive any third-party obligations.
+Before redistributing Ghostscript or deploying a hosted PDF-processing
+service, evaluate the applicable Ghostscript licensing terms:
+https://www.ghostscript.com/licensing/

pdfblinder-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pdfblinder"
+version = "0.1.0"
+description = "Reconstruct and sanitize PDFs for anonymous review."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = ["pikepdf>=10.17,<11"]
+
+[project.optional-dependencies]
+dev = ["pytest>=9,<10", "Pillow>=10"]
+
+[project.scripts]
+pdfblinder = "pdfblinder.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pdfblinder-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pdfblinder-0.1.0/src/pdfblinder/__init__.py

@@ -0,0 +1 @@
+"""PDF reconstruction and sanitation for anonymous review."""

pdfblinder-0.1.0/src/pdfblinder/__main__.py

@@ -0,0 +1,86 @@
+"""Command-line entry point for PDFblinder."""
+
+import argparse
+from importlib.metadata import version
+import math
+from pathlib import Path
+
+import pikepdf
+
+from .core import InputError, blind_pdf
+from .ghostscript import GhostscriptError
+from .sanitize import SanitationError
+from .verify import VerificationError
+
+
+def positive_timeout(value: str) -> float:
+    try:
+        seconds = float(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(
+            "Timeout must be a positive number of seconds."
+        ) from exc
+    if not math.isfinite(seconds) or seconds <= 0:
+        raise argparse.ArgumentTypeError(
+            "Timeout must be finite and greater than zero."
+        )
+    return seconds
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="pdfblinder",
+        description="Reconstruct and structurally sanitize a PDF.",
+        epilog=(
+            "Annotations are discarded. Forms and encrypted PDFs are "
+            "rejected. Identifying visible content and embedded font/image "
+            "payloads are not anonymized. Review the output before submission."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {version('pdfblinder')}",
+    )
+    parser.add_argument("input", type=Path, help="Source PDF")
+    parser.add_argument(
+        "output", type=Path,
+        help="Destination PDF; must not already exist",
+    )
+    parser.add_argument(
+        "--gs", metavar="EXECUTABLE",
+        help="Ghostscript executable name or path",
+    )
+    parser.add_argument(
+        "--timeout", type=positive_timeout, default=120.0,
+        metavar="SECONDS",
+        help="Ghostscript time limit in seconds (default: 120)",
+    )
+    args = parser.parse_args()
+
+    try:
+        pages = blind_pdf(
+            args.input,
+            args.output,
+            executable=args.gs,
+            timeout=args.timeout,
+        )
+    except (
+        OSError,
+        pikepdf.PdfError,
+        InputError,
+        GhostscriptError,
+        SanitationError,
+        VerificationError,
+    ) as exc:
+        parser.exit(1, f"pdfblinder: error: {exc}\n")
+    except KeyboardInterrupt:
+        parser.exit(130, "pdfblinder: interrupted\n")
+
+    print(f"Created: {args.output} ({pages} pages)")
+    print("Structural verification passed. Review the output before submission.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pdfblinder-0.1.0/src/pdfblinder/core.py

@@ -0,0 +1,103 @@
+"""Complete PDFblinder processing pipeline."""
+
+import os
+from pathlib import Path
+import shutil
+from tempfile import TemporaryDirectory
+
+import pikepdf
+
+from .ghostscript import reconstructed_pdf
+from .sanitize import sanitize_intermediate
+from .verify import VerificationError, verify_pdf
+
+
+class InputError(ValueError):
+    """The input is unsupported or unsuitable for processing."""
+
+
+def blind_pdf(
+    source: Path,
+    destination: Path,
+    *,
+    executable: str | None = None,
+    timeout: float = 120,
+) -> int:
+    """Create a verified output without overwriting existing files.
+
+    Returns the page count. Structural sanitation does not remove
+    identifying visible content or guarantee complete anonymity.
+    """
+    source = Path(source).expanduser().resolve(strict=True)
+    destination = Path(destination).expanduser().absolute()
+
+    if not source.is_file():
+        raise InputError("Input must be a regular file.")
+    if destination.exists() or destination.is_symlink():
+        raise FileExistsError(f"Output already exists: {destination}")
+    if not destination.parent.is_dir():
+        raise FileNotFoundError(
+            f"Output directory does not exist: {destination.parent}"
+        )
+
+    with TemporaryDirectory(prefix="pdfblinder-job-") as directory:
+        work = Path(directory)
+        snapshot = work / "input.pdf"
+        candidate = work / "candidate.pdf"
+        shutil.copyfile(source, snapshot)
+
+        with pikepdf.Pdf.open(
+            snapshot, attempt_recovery=False
+        ) as original:
+            if original.is_encrypted:
+                raise InputError("Encrypted input PDFs are not supported.")
+            page_count = len(original.pages)
+            if page_count == 0:
+                raise InputError("Input PDF contains no pages.")
+            if "/AcroForm" in original.Root:
+                raise InputError(
+                    "PDFs with forms or signature fields are not supported. "
+                    "Export a static PDF first and check its appearance."
+                )
+            original_ids = tuple(
+                bytes(identifier)
+                for identifier in original.trailer.get("/ID", [])
+            )
+
+        with reconstructed_pdf(
+            snapshot, executable=executable, timeout=timeout
+        ) as intermediate:
+            with candidate.open("xb") as stream:
+                reconstructed_count = sanitize_intermediate(
+                    intermediate, stream
+                )
+
+        if reconstructed_count != page_count:
+            raise VerificationError(
+                "Reconstruction changed the number of pages."
+            )
+
+        verify_pdf(
+            candidate,
+            expected_pages=page_count,
+            original_ids=original_ids,
+        )
+
+        # Exclusive creation also prevents overwriting a file that
+        # appeared after the initial destination check.
+        descriptor = os.open(
+            destination,
+            os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+            0o600,
+        )
+        try:
+            with os.fdopen(descriptor, "wb") as output:
+                with candidate.open("rb") as verified:
+                    shutil.copyfileobj(verified, output)
+                output.flush()
+                os.fsync(output.fileno())
+        except BaseException:
+            destination.unlink(missing_ok=True)
+            raise
+
+    return page_count

pdfblinder-0.1.0/src/pdfblinder/ghostscript.py

@@ -0,0 +1,95 @@
+"""Ghostscript reconstruction into a temporary intermediate PDF."""
+
+from contextlib import contextmanager
+from pathlib import Path
+import shutil
+import subprocess
+from tempfile import TemporaryDirectory
+from typing import Iterator
+
+
+class GhostscriptError(RuntimeError):
+    """Ghostscript could not reconstruct the input."""
+
+
+def find_ghostscript(executable: str | None = None) -> str:
+    candidates = (
+        [executable] if executable is not None
+        else ["gs", "gswin64c", "gswin32c"]
+    )
+    for candidate in candidates:
+        resolved = shutil.which(candidate)
+        if resolved:
+            return resolved
+    raise GhostscriptError(
+        "Ghostscript was not found. Install it or specify its executable."
+    )
+
+
+@contextmanager
+def reconstructed_pdf(
+    source: Path,
+    *,
+    executable: str | None = None,
+    timeout: float = 120,
+) -> Iterator[Path]:
+    """Yield an intermediate PDF; remove temporary files on exit.
+
+    This stage alone does not establish anonymity.
+    """
+    source = Path(source).resolve(strict=True)
+    if not source.is_file():
+        raise ValueError("Input must be a regular file.")
+    if timeout <= 0:
+        raise ValueError("Timeout must be positive.")
+
+    gs = find_ghostscript(executable)
+    with TemporaryDirectory(prefix="pdfblinder-") as directory:
+        output = Path(directory) / "reconstructed.pdf"
+        command = [
+            gs,
+            "-dSAFER",
+            "-dBATCH",
+            "-dNOPAUSE",
+            "-dPDFSTOPONERROR",
+            "-dPDFSTOPONWARNING",
+            "-sDEVICE=pdfwrite",
+            "-dCompatibilityLevel=1.7",
+            "-dPreserveAnnots=false",
+            "-dShowAnnots=false",
+            "-dPreserveMarkedContent=false",
+            "-dDownsampleColorImages=false",
+            "-dDownsampleGrayImages=false",
+            "-dDownsampleMonoImages=false",
+            f"-sOutputFile={output}",
+            "-f",
+            str(source),
+        ]
+        try:
+            result = subprocess.run(
+                command,
+                capture_output=True,
+                timeout=timeout,
+                check=False,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise GhostscriptError(
+                f"Ghostscript exceeded the {timeout:g}-second timeout."
+            ) from exc
+        except OSError as exc:
+            raise GhostscriptError(
+                f"Could not execute Ghostscript: {exc}"
+            ) from exc
+
+        if result.returncode != 0:
+            details = (result.stdout + result.stderr).decode(
+                "utf-8", errors="replace"
+            ).strip()
+            raise GhostscriptError(
+                f"Ghostscript failed with exit code {result.returncode}.\n"
+                f"{details[-8000:]}"
+            )
+        if not output.is_file() or output.stat().st_size == 0:
+            raise GhostscriptError("Ghostscript produced no PDF output.")
+
+        yield output