Metadata-Version: 2.4
Name: jpegtrust
Version: 0.1.0
Summary: Embed, extract, and verify JPEG Trust provenance metadata
Project-URL: Homepage, https://github.com/JPEG-Trust-Community/reference-software
Project-URL: Documentation, https://github.com/JPEG-Trust-Community/reference-software/tree/main/pip_package#readme
Project-URL: Repository, https://github.com/JPEG-Trust-Community/reference-software
Project-URL: Issues, https://github.com/JPEG-Trust-Community/reference-software/issues
Author: JPEG Trust NU Research Team
License-Expression: MIT
License-File: LICENSE
Keywords: c2pa,jpeg,jumbf,metadata,provenance,trust
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: c2pa-python>=0.32.0
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install jpegtrust
```

## Quick start

```python
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

```bash
# 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:

```yaml
---
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

```python
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
