How contentauth/c2pa-python-example works
Project type and purpose
• This is a backend-only, containerized Python service (no HTML-based front end).
• It exposes a REST endpoint (POST /attach) via Flask to accept a JPEG, attach a C2PA manifest, and sign it using a KMS-backed certificate.
• It can run against real AWS KMS or a LocalStack container for local development and testing.
File structure
• Top level:
• app.py – Flask application entry point
• setup.py & scripts/ – CLI tasks for generating KMS keys, CSRs, and certificates
• Dockerfile, docker-compose.yaml, Makefile, local-setup.sh – container build & orchestration
• example-env.env / .env – environment-variable templates
• requirements.txt – Python dependencies (Flask, boto3, c2pa-python SDK, waitress, etc.)
• tests/ – integration tests and example client (tests/client.py)
• No “frontend” directory; it’s purely a signing microservice.
• docker-compose.yaml defines four containers:
1. localstack-main (mocked AWS infra)
2. local-setup (one-time infrastructure setup)
3. local-signer (Flask/Waitress signing server)
4. local-client (Python client to self-test signing)
Key insights from README
• The service interacts with AWS KMS (or LocalStack) via boto3.
• setup.py automates CSR and key management.
• Docker Compose orchestrates initialization (creating IAM user, KMS key, CSR, certificate chain) before launching the signer and client.
a. Main components:
• API Client (curl or tests/client.py / local-client container)
• Signing Service (Flask app in local-signer container)
• KMS Service (AWS KMS in real AWS or LocalStack in localstack-main container)
• Setup Batch Job (setup.py & local-setup container)
• Certificate Authority (external CA or self-signed root CA)
• Volumes: config_volume (stores CSR, chain.pem, env files), client_volume (signed images)
b. Relationships & interactions:
1. On make local, Docker Compose spins up localstack-main → local-setup runs setup.py scripts → writes keys, CSR, chain.pem into config_volume.
2. local-signer starts, reads .env, loads KMS_KEY_ID and chain.pem, serves HTTP on 0.0.0.0:5000.
3. Client (local-client container or external curl) POST /attach → Signing Service
4. Signing Service calls KMS via AWS SDK/boto3 (pointed at LocalStack endpoint) to sign nonce or derive keys.
5. Signing Service uses c2pa-python SDK to assemble manifest + signature → returns signed JPEG → client_volume.
c. Architectural patterns & principles:
• Microservices via isolated Docker containers
• Infrastructure as code: setup.py + local-setup.sh automate AWS/LocalStack provisioning
• Clear separation of concerns:
• Setup phase (infrastructure bootstrap)
• Runtime phase (signer service)
• Client testing phase
• Environment-driven configuration (.env, example-env.env)
d. Key technologies/frameworks:
• Python 3.10/3.12, Flask, Waitress (production WSGI), boto3, c2pa-python SDK
• Docker, Docker Compose, LocalStack
• OpenSSL for CSR & certificate chaining (scripts/digicert-create-cert.sh)