jpegtrust 0.1.0

Embed, extract, and verify JPEG Trust provenance metadata

jpegtrust

Embed, extract, and verify JPEG Trust provenance metadata.

jpegtrust is a Python package for working with JPEG Trust provenance metadata based on the C2PA and JUMBF standards. It lets you embed signed metadata into JPEG images, extract it back out, and verify images against configurable trust profiles.

Installation

pip install jpegtrust

Quick start

from jpegtrust import embed_image, extract_from_file, verify_image, create_profile, save_profile

# Create a trust profile
profile = create_profile(template="newsroom", name="Wire Photo Policy")
save_profile(profile, "profile.yml")

# Embed metadata into an image
embed_image("photo.jpg", "metadata.json", "signed.jpg")

# Extract metadata
metadata = extract_from_file("signed.jpg")

# Verify against the profile
report = verify_image("signed.jpg", "profile.yml")
print(f"{report.status} | {report.score} | {report.passed_checks}/{report.total_checks}")

CLI

# Profile operations
jpegtrust profile list-templates
jpegtrust profile list-checks
jpegtrust profile create --template newsroom -o profile.yml

# Embed metadata
jpegtrust embed photo.jpg metadata.json -o signed.jpg

# Extract metadata
jpegtrust extract signed.jpg
jpegtrust extract signed.jpg -o metadata.json

# Verify
jpegtrust verify signed.jpg profile.yml
jpegtrust verify signed.jpg profile.yml --format json

# Batch operations
jpegtrust batch embed ./photos metadata.json -o ./signed
jpegtrust batch extract ./signed -o ./extracted
jpegtrust batch verify ./signed profile.yml

API reference

Embedding

Function	Description
embed_image(image, metadata, output)	Embed metadata from a file path or dict into a JPEG
embed_metadata(image_bytes, metadata_dict)	Embed metadata into raw JPEG bytes

Extraction

Function	Description
extract_from_file(image)	Extract and parse metadata from a JPEG file
extract_metadata(image_bytes)	Extract raw JSON string from JPEG bytes

Verification

Function	Description
verify(indicator, profile_yaml)	Verify an indicator dict against a profile YAML string
verify_image(image_path, profile_path)	Extract + verify in one call

Profiles

Function	Description
create_profile(template, name, issuer)	Create a profile from a predefined template
save_profile(profile, path)	Save profile as YAML
load_profile(path)	Load profile YAML from file
list_templates()	List available templates and their checks
list_checks()	List all available check definitions

Batch

Function	Description
batch_embed(input_dir, metadata, output_dir)	Embed metadata into all images in a directory
batch_extract(input_dir, output_dir)	Extract metadata from all images
batch_verify(input_dir, profile)	Verify all images against a profile

Templates

Template	Checks	Use case
newsroom	All 9 checks	Wire photos, editorial verification
insurance	signature, timestamp, author, edit history, GPS, pixel hash	Claims photo validation
creator	signature, author, copyright, AI declaration, pixel hash	Artist authenticity
ai-labelling	signature, AI declaration, digital source type, AI labelling, edit history, pixel hash, data mining	AI labelling
custom	None (you pick)	Build your own

Trust profiles

Trust profiles are multi-document YAML files that define verification rules. Each rule contains an expression evaluated against the image's metadata:

---
metadata:
  name: "My Profile"
  issuer: "My Organization"
  date: "2025-01-01T00:00:00Z"
  version: "1.0.0"
  language: en

---
- id: signature_check
  expression: >
    declaration.claim.signature_status == "claimSignature.validated"
  report_text:
    'true':
      en: "Valid signature"
    'false':
      en: "No valid signature"

Verification report

report = verify_image("signed.jpg", "profile.yml")

report.status        # "pass" | "warning" | "fail"
report.score         # 0.0 - 1.0
report.verdict       # "trusted" | "mostly_trusted" | "profile_mismatch"
report.passed        # ["signature_chain", "pixel_hash", ...]
report.failed        # ["gps_location", ...]
report.total_checks  # 9
report.passed_checks # 7
report.c2pa          # C2PA detection info
report.to_dict()     # Full report as a dict

License

MIT