fieldwitness/docs/planning/c2pa-integration.md

C2PA Integration Plan

Audience: FieldWitness developers and maintainers Status: Planning (pre-implementation) Last updated: 2026-04-01

Overview

FieldWitness needs C2PA (Coalition for Content Provenance and Authenticity) export/import capability. C2PA is the emerging industry standard for content provenance, backed by Adobe, Microsoft, Google, and the BBC. ProofMode, Guardian Project, and Starling Lab have all adopted C2PA. FieldWitness must speak C2PA to remain relevant in the provenance space.

---

C2PA Spec Essentials

• JUMBF-based provenance standard embedded in media files
• Core structures: Manifest Store > Manifest > Claim + Assertions + Ingredients + Signature
• Claims are CBOR maps with assertion references, signing algorithm, claim_generator, and timestamps
• Standard assertions:
  • c2pa.actions -- edit history
  • c2pa.hash.data -- hard binding (byte-range)
  • c2pa.location.broad -- city/region location
  • c2pa.exif -- EXIF metadata
  • c2pa.creative.work -- title, description, authorship
  • c2pa.training-mining -- AI training/mining consent
  • Vendor-specific assertions under reverse-DNS (e.g., org.fieldwitness.*)
• Signing uses COSE_Sign1 (RFC 9052)
  • Supported algorithms: Ed25519 (OKP), ES256/ES384/ES512 (ECDSA), PS256/PS384/PS512 (RSA-PSS)
• X.509 certificate chain required -- embedded in COSE unprotected header; raw public keys are not sufficient
• Offline validation works with pre-installed trust anchors; self-signed certs work in "local trust anchor" mode

Python Library: c2pa-python

• Canonical binding from C2PA org (PyPI: c2pa-python, GitHub: contentauth/c2pa-python)
• Rust extension (c2pa-rs via PyO3), not pure Python
• Version ~0.6.x, API not fully stable
• Platform wheels: manylinux2014 x86_64/aarch64, macOS, Windows
  • No armv6/armv7 wheels -- affects Tier 1 Raspberry Pi deployments
• Core API: c2pa.Reader, c2pa.Builder, builder.sign(), c2pa.create_signer()
• create_signer takes a callback, algorithm, certs PEM, optional timestamp URL
• timestamp_url=None skips RFC 3161 timestamping (acceptable for offline use)

---

Concept Mapping: FieldWitness to C2PA

Clean mappings

FieldWitness	C2PA
AttestationRecord	C2PA Manifest
attestor_fingerprint	Signer cert subject (wrapped in X.509)
AttestationRecord.timestamp	Claim created (ISO 8601)
CaptureMetadata.captured_at	c2pa.exif DateTimeOriginal
CaptureMetadata.location	c2pa.location.broad
CaptureMetadata.device	c2pa.exif Make/Model
CaptureMetadata.caption	c2pa.creative.work description
ImageHashes.sha256	c2pa.hash.data (hard binding)
Ed25519 private key	COSE_Sign1 signing key (needs X.509 wrapper)

FieldWitness has, C2PA does not

• Perceptual hashes (phash, dhash) -- map to vendor assertion org.fieldwitness.perceptual-hashes
• Merkle log inclusion proofs -- map to vendor assertion org.fieldwitness.merkle-proof
• Chain records with entropy witnesses -- map to vendor assertion org.fieldwitness.chain-record
• Delivery acknowledgment records (entirely FieldWitness-specific)
• Cross-org gossip federation
• Perceptual matching for verification (survives recompression)
• Selective disclosure / redaction

C2PA has, FieldWitness does not

• Hard file binding (byte-range exclusion zones)
• X.509 certificate trust chains
• Actions history (c2pa.actions: crop, rotate, AI-generate, etc.)
• AI training/mining consent
• Ingredient DAG (content derivation graph)

---

Privacy Design

Three tiers of identity disclosure:

1. Org-level cert (preferred): One self-signed X.509 cert per organization, not per person. Subject is org name. Individual reporters do not appear in the manifest.

2. Pseudonym cert: Subject is pseudonym or random UUID. Valid C2PA but unrecognized by external trust anchors.

3. No C2PA export: For critical-threat presets, evidence stays in FieldWitness format until reaching Tier 2.

GPS handling

C2PA's c2pa.location.broad is city/region level. FieldWitness captures precise GPS. On export, downsample to city-level unless the operator explicitly opts in. Precise GPS stays in FieldWitness record only.

Metadata handling

Strip all EXIF from the output file except what is intentionally placed in the c2pa.exif assertion.

---

Offline-First Constraints

• Tier 1 (field, no internet): C2PA manifests without RFC 3161 timestamp. FieldWitness chain record provides timestamp anchoring via vendor assertion.
• Tier 2 (org server, may have internet): Optionally contact TSA at export time. Connects to existing anchors.py infrastructure.
• Entropy witnesses embedded as vendor assertions provide soft timestamp evidence.
• Evidence packages include org cert PEM alongside C2PA manifest for offline verification.
• c2pa-python availability gated behind has_c2pa() -- not all hardware can run it.

---

Architecture

New module: src/fieldwitness/c2pa_bridge/

src/fieldwitness/c2pa_bridge/
    __init__.py          # Public API: export, import, has_c2pa()
    cert.py              # Self-signed X.509 cert generation from Ed25519 key
    export.py            # AttestationRecord -> C2PA manifest
    importer.py          # C2PA manifest -> AttestationRecord (best-effort)
    vendor_assertions.py # org.fieldwitness.* assertion schemas
    cli.py               # CLI subcommands: fieldwitness c2pa export / verify / import

Module relationships

• export.py reads from attest/models.py, federation/chain.py, keystore/manager.py; calls cert.py and vendor_assertions.py
• importer.py reads image bytes, writes AttestationRecord via attest/attestation.py, parses vendor assertions

Web UI

New routes in the attest.py blueprint:

• GET /attest/<record_id>/c2pa -- download C2PA-embedded image
• POST /attest/import-c2pa -- upload and import C2PA manifest

Evidence packages

evidence.py gains include_c2pa=True option. Adds C2PA-embedded file variants and org cert to the ZIP.

pyproject.toml extra

c2pa = ["c2pa-python>=0.6.0", "fieldwitness[attest]"]

---

Implementation Phases

Phase 0 -- Prerequisites (~1h)

• has_c2pa() in _availability.py
• c2pa extra in pyproject.toml

Phase 1 -- Certificate management (~3h)

• c2pa_bridge/cert.py
• Self-signed X.509 from Ed25519 identity key
• Configurable subject (org name default, pseudonym for high-threat)
• Store at ~/.fwmetadata/identity/c2pa_cert.pem
• Regenerate on key rotation

Phase 2 -- Export path (~6h)

• c2pa_bridge/export.py + vendor_assertions.py
• Core function export_c2pa() takes image data, AttestationRecord, key, cert, options
• Builds assertions: c2pa.actions, c2pa.hash.data, c2pa.exif, c2pa.creative.work, org.fieldwitness.perceptual-hashes, org.fieldwitness.chain-record, org.fieldwitness.attestation-id
• Vendor assertion schemas versioned (v1)

Phase 3 -- Import path (~5h)

• c2pa_bridge/importer.py
• import_c2pa() reads C2PA manifest, produces AttestationRecord
• Maps C2PA fields to FieldWitness model
• Returns C2PAImportResult with trust_status
• Creates new FieldWitness attestation record over imported data

Phase 4 -- CLI integration (~4h)

• fieldwitness c2pa export/verify/import/show subcommands
• Gated on has_c2pa()

Phase 5 -- Web UI + evidence packages (~5h)

• Blueprint routes for export/import
• Evidence package C2PA option

Phase 6 -- Threat-level presets (~2h)

• Add c2pa config block to each preset (export_enabled, privacy_level, include_precise_gps, timestamp_url)
• C2PAConfig sub-dataclass in FieldWitnessConfig

MVP scope

Phases 0-2 (~10h): Produces C2PA-compatible images viewable in Adobe Content Credentials and any C2PA verifier.

---

Key Decisions (Before Coding)

1. Use existing Ed25519 identity key for cert (not a separate key) -- preserves single-key-domain design.
2. Cert stored at ~/.fwmetadata/identity/c2pa_cert.pem, regenerated on key rotation.
3. Tier 1 ARM fallback: Tier 1 produces FieldWitness records; Tier 2 generates C2PA export on their behalf.
4. Pin c2pa-python>=0.6.0, add shim layer for API stability.
5. Hard binding computed by c2pa-python Builder automatically.

---

FieldWitness's Unique C2PA Value

• Cross-org chain of custody via gossip federation (delivery ack records as ingredients)
• Perceptual hash matching embedded in C2PA (survives JPEG recompression via WhatsApp/Telegram)
• Merkle log inclusion proofs in manifest (proves attestation committed to append-only log)
• Entropy witnesses as soft timestamp attestation (makes backdating harder without RFC 3161)
• Privacy-preserving by design (org certs, GPS downsampling, zero-identity mode)
• Fully offline end-to-end verification (bundled cert + c2pa-python, no network needed)