Skip to content

PDF Document Stamping

PrimeStamp provides first-class support for stamping PDF documents, including metadata extraction, content hashing, and embedded proof attachment. PDF stamps capture both the binary content hash and structured metadata for comprehensive document authentication.

Quick Start

from primestamp.integrations.pdf_extract import PDFExtractor, PrimeStampPDF

extractor = PDFExtractor()
result = extractor.extract("document.pdf")

print(f"Pages: {result.page_count}")
print(f"Words: {result.word_count}")
print(f"Title: {result.metadata.get('title')}")
print(f"Author: {result.metadata.get('author')}")
print(f"Content hash: {result.content_hash}")

integration = PrimeStampPDF(extractor)
stamped = await integration.stamp_pdf(pdf_bytes, "report.pdf", preset="standard")

Dependencies

pip install pypdf
# or install with the integrations extra:
pip install "primestamp[integrations]"

Features

  • Text extraction with page-level granularity
  • Document structure detection (headings, paragraphs, tables)
  • Metadata extraction (title, author, creation date, keywords)
  • Content-based hashing that ignores rendering differences
  • Page-by-page Merkle tree for partial proofs
  • Form field extraction
  • Image reference cataloging
  • Encrypted PDF support (with password)
  • Large file streaming

Extraction Modes

Mode Description Use Case
text_only Extract raw text only Fast hashing, minimal overhead
structured Extract text with structural elements Content-aware fingerprinting
full Extract everything including form fields and annotations Archival stamping 
from primestamp.integrations.pdf_extract import ExtractionMode

result = extractor.extract("document.pdf", mode=ExtractionMode.STRUCTURED)

Structural Elements

Element Description
heading Section headings (detected via font size and weight)
paragraph Body text paragraphs
list_item Bulleted or numbered list items
table Table content with row/column structure
image_ref Image references (position and dimensions)
form_field Interactive form fields (text boxes, checkboxes)
annotation Comments, highlights, sticky notes
header Page header content
footer Page footer content

Page-Level Merkle Tree

For documents where you need to prove a specific page without revealing the entire document, PrimeStamp builds a Merkle tree over individual page hashes:

for i, page in enumerate(result.pages):
    print(f"Page {i+1}: {page.content_hash}")

print(f"Merkle root: {result.merkle_root}")

# Generate a proof for page 3
proof = result.generate_page_proof(page_index=2)

Metadata Extraction

metadata = result.metadata
print(f"Title: {metadata.get('title')}")
print(f"Author: {metadata.get('author')}")
print(f"Creator: {metadata.get('creator')}")
print(f"Producer: {metadata.get('producer')}")
print(f"Creation date: {metadata.get('creation_date')}")
print(f"Modification date: {metadata.get('modification_date')}")
print(f"Encrypted: {metadata.get('encrypted')}")

Content-Based vs. File-Based Hashing

PrimeStamp hashes the extracted text content rather than the raw PDF bytes. This means re-saving a PDF in a different viewer does not change the content hash as long as the text is identical. Metadata changes are captured separately.

# Content hash (text-based, stable across re-renders)
content_hash = result.content_hash

# File hash (raw bytes, any byte change alters it)
import hashlib
file_hash = hashlib.sha3_256(pdf_bytes).hexdigest()

Encrypted PDFs

result = extractor.extract("encrypted.pdf", password="secret123")

CLI Usage

# Stamp a PDF
primestamp stamp report.pdf --preset standard

# Extract and display metadata
primestamp fingerprint report.pdf --show-metadata

# Verify a stamped PDF
primestamp verify report.pdf

Stamping Pipeline

When PrimeStamp stamps a PDF, it:

  1. Extracts text content page by page
  2. Detects structural elements (headings, tables, etc.)
  3. Extracts metadata (author, title, dates)
  4. Computes a content hash from the extracted text
  5. Builds a Merkle tree over page hashes
  6. Optionally generates a Prime-Space fingerprint for structural similarity
  7. Creates a signed stamp with all extracted information
  8. Submits the hash to configured blockchain anchors