Compare commits
21 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
0312204340 | ||
|
|
16318daea3 | ||
|
|
5b0d90eeaf | ||
|
|
3a9cb17a5a | ||
|
|
e4f68fc83a | ||
|
|
4a471ee31a | ||
|
|
2fd3e0e31d | ||
|
|
88f5571bf9 | ||
|
|
490f9d4a1d | ||
|
|
6325e86873 | ||
|
|
2629aabcc5 | ||
|
|
496198d49a | ||
|
|
2a6900abed | ||
|
|
428750e971 | ||
|
|
fef552b9c1 | ||
|
|
f557cac45a | ||
|
|
171e51643c | ||
|
|
9431033c72 | ||
|
|
7967d4b419 | ||
|
|
e50122e8e6 | ||
|
|
b7d4cbe286 |
@ -15,7 +15,7 @@ jobs:
|
||||
run: apt-get update && apt-get install -y --no-install-recommends git
|
||||
- name: Checkout
|
||||
run: |
|
||||
git clone --depth=1 --branch="${GITHUB_REF_NAME}" https://git.golfcards.club/alee/soosef.git "$GITHUB_WORKSPACE" || git clone --depth=1 https://git.golfcards.club/alee/soosef.git "$GITHUB_WORKSPACE"
|
||||
git clone --depth=1 --branch="${GITHUB_REF_NAME}" https://git.golfcards.club/alee/fieldwitness.git "$GITHUB_WORKSPACE" || git clone --depth=1 https://git.golfcards.club/alee/fieldwitness.git "$GITHUB_WORKSPACE"
|
||||
- run: pip install ruff black
|
||||
- name: Check formatting
|
||||
run: black --check --target-version py312 src/ tests/ frontends/
|
||||
@ -31,12 +31,12 @@ jobs:
|
||||
run: apt-get update && apt-get install -y --no-install-recommends git
|
||||
- name: Checkout
|
||||
run: |
|
||||
git clone --depth=1 --branch="${GITHUB_REF_NAME}" https://git.golfcards.club/alee/soosef.git "$GITHUB_WORKSPACE" || git clone --depth=1 https://git.golfcards.club/alee/soosef.git "$GITHUB_WORKSPACE"
|
||||
git clone --depth=1 --branch="${GITHUB_REF_NAME}" https://git.golfcards.club/alee/fieldwitness.git "$GITHUB_WORKSPACE" || git clone --depth=1 https://git.golfcards.club/alee/fieldwitness.git "$GITHUB_WORKSPACE"
|
||||
- run: pip install mypy
|
||||
- name: Typecheck
|
||||
run: mypy src/
|
||||
|
||||
# TODO: Re-enable once stegasoo/verisoo are available from git.golfcards.club
|
||||
# TODO: Re-enable once stego/attest are available from git.golfcards.club
|
||||
# test:
|
||||
# runs-on: ubuntu-latest
|
||||
# container:
|
||||
@ -46,8 +46,8 @@ jobs:
|
||||
# run: apt-get update && apt-get install -y --no-install-recommends git
|
||||
# - name: Checkout
|
||||
# run: |
|
||||
# git clone --depth=1 --branch="${GITHUB_REF_NAME}" https://git.golfcards.club/alee/soosef.git "$GITHUB_WORKSPACE" || git clone --depth=1 https://git.golfcards.club/alee/soosef.git "$GITHUB_WORKSPACE"
|
||||
# git clone --depth=1 --branch="${GITHUB_REF_NAME}" https://git.golfcards.club/alee/fieldwitness.git "$GITHUB_WORKSPACE" || git clone --depth=1 https://git.golfcards.club/alee/fieldwitness.git "$GITHUB_WORKSPACE"
|
||||
# - name: Install dependencies
|
||||
# run: pip install -e ".[dev]"
|
||||
# - name: Run tests
|
||||
# run: pytest --cov=soosef --cov-report=term-missing
|
||||
# run: pytest --cov=fieldwitness --cov-report=term-missing
|
||||
|
||||
274
CLAUDE.md
274
CLAUDE.md
@ -1,16 +1,19 @@
|
||||
# SooSeF — Claude Code Project Guide
|
||||
# FieldWitness -- Claude Code Project Guide
|
||||
|
||||
SooSeF (Soo Security Fieldkit) is an offline-first security toolkit for journalists, NGOs,
|
||||
and at-risk organizations. Part of the Soo Suite alongside Stegasoo and Verisoo.
|
||||
FieldWitness (FieldWitness) is an offline-first provenance attestation and gossip
|
||||
federation system for journalists, NGOs, and at-risk organizations. It establishes
|
||||
cryptographic chain-of-custody over evidence in airgapped and resource-constrained
|
||||
environments, syncs attestations across organizational boundaries via a gossip protocol
|
||||
with Merkle consistency proofs, and produces court-ready evidence packages with standalone
|
||||
verification. Steganography (Stego) and provenance attestation (Attest) are included
|
||||
as subpackages in this monorepo.
|
||||
|
||||
Version 0.1.0 · Python >=3.11 · MIT License
|
||||
Version 0.3.0 · Python >=3.11 · GPL-3.0 License
|
||||
|
||||
## Quick commands
|
||||
|
||||
```bash
|
||||
# Development install (requires stegasoo and verisoo installed first)
|
||||
pip install -e /path/to/stegasoo[web,dct,audio]
|
||||
pip install -e /path/to/verisoo[cli]
|
||||
# Development install (single command -- stego and attest are inlined subpackages)
|
||||
pip install -e ".[dev]"
|
||||
|
||||
pytest # Run tests
|
||||
@ -19,58 +22,253 @@ ruff check src/ tests/ frontends/ --fix # Lint
|
||||
mypy src/ # Type check
|
||||
```
|
||||
|
||||
### Pip extras
|
||||
|
||||
`stego-dct`, `stego-audio`, `stego-compression`, `attest`, `cli`, `web`, `api`,
|
||||
`fieldkit`, `federation`, `rpi`, `all`, `dev`
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
src/soosef/ Core library
|
||||
__init__.py Package init, __version__
|
||||
paths.py All ~/.soosef/* path constants (single source of truth)
|
||||
config.py Unified config loader
|
||||
exceptions.py SoosefError base exception
|
||||
src/fieldwitness/ Core library
|
||||
__init__.py Package init, __version__ (0.3.0)
|
||||
_availability.py Runtime checks for optional subpackages (has_stego, has_attest)
|
||||
api.py Optional unified FastAPI app (uvicorn fieldwitness.api:app)
|
||||
audit.py Append-only JSON-lines audit log (~/.fwmetadata/audit.jsonl)
|
||||
cli.py Click CLI entry point (fieldwitness command)
|
||||
paths.py All ~/.fwmetadata/* path constants (single source of truth, lazy resolution)
|
||||
config.py Unified config loader (FieldWitnessConfig dataclass + JSON)
|
||||
exceptions.py FieldWitnessError, ChainError, ChainIntegrityError, ChainAppendError, KeystoreError
|
||||
metadata.py Extract-then-strip EXIF pipeline with field classification
|
||||
evidence.py Self-contained evidence package export (ZIP with verify.py)
|
||||
archive.py Cold archive export for long-term preservation (OAIS-aligned)
|
||||
|
||||
stego/ Steganography engine (inlined from fieldwitness.stego v4.3.0)
|
||||
encode.py / decode.py Core encode/decode API
|
||||
generate.py Cover image generation
|
||||
crypto.py AES-256-GCM encryption, channel fingerprints
|
||||
channel.py Channel key derivation + management
|
||||
steganography.py LSB steganography core
|
||||
dct_steganography.py DCT-domain JPEG steganography
|
||||
spread_steganography.py MDCT spread-spectrum audio steganography
|
||||
audio_steganography.py Audio stego pipeline
|
||||
video_steganography.py Video stego pipeline
|
||||
backends/ Pluggable stego backend registry (lsb, dct, protocol)
|
||||
batch.py Batch operations
|
||||
compression.py Payload compression (zstd, lz4)
|
||||
steganalysis.py Detection resistance analysis
|
||||
validation.py Input validation
|
||||
models.py Data models
|
||||
constants.py Magic bytes, version constants, AUDIO_ENABLED, VIDEO_ENABLED
|
||||
cli.py Stego-specific CLI commands
|
||||
api.py / api_auth.py Stego REST API + auth
|
||||
carrier_tracker.py Carrier image reuse tracking (warns on reuse)
|
||||
platform_presets.py Social-media-aware encoding presets
|
||||
image_utils.py / audio_utils.py / video_utils.py
|
||||
keygen.py / qr_utils.py / recovery.py / debug.py / utils.py
|
||||
|
||||
attest/ Provenance attestation engine (inlined from fieldwitness.attest v0.2.0)
|
||||
attestation.py Core attestation creation + EXIF extraction
|
||||
verification.py Attestation verification
|
||||
crypto.py Ed25519 signing
|
||||
hashing.py Perceptual + cryptographic hashing (ImageHashes)
|
||||
embed.py Attestation embedding in images
|
||||
merkle.py Merkle tree + consistency/inclusion proofs
|
||||
binlog.py Binary attestation log
|
||||
lmdb_store.py LMDB-backed trust store
|
||||
storage.py Attestation storage abstraction (LocalStorage)
|
||||
federation.py GossipNode, HttpTransport, PeerInfo, SyncStatus
|
||||
peer_store.py SQLite-backed peer persistence for federation
|
||||
models.py Attestation, AttestationRecord, ImageHashes, Identity
|
||||
exceptions.py AttestError, AttestationError, VerificationError, FederationError
|
||||
cli.py Attest-specific CLI commands
|
||||
api.py Attest REST API + federation endpoints
|
||||
|
||||
federation/ Federated attestation chain system
|
||||
chain.py ChainStore -- append-only hash chain with key rotation/recovery/delivery-ack
|
||||
entropy.py Entropy source for chain seeds (sys_uptime, fs_snapshot, proc_entropy, boot_id)
|
||||
models.py AttestationChainRecord, ChainState, EntropyWitnesses (frozen dataclasses)
|
||||
serialization.py CBOR canonical encoding + compute_record_hash + serialize/deserialize
|
||||
anchors.py RFC 3161 timestamps + manual chain anchors
|
||||
exchange.py Cross-org attestation bundle export/import (JSON bundles)
|
||||
|
||||
keystore/ Unified key management
|
||||
manager.py Owns all key material (channel keys + Ed25519 identity)
|
||||
models.py KeyBundle, IdentityBundle dataclasses
|
||||
export.py Encrypted key bundle export/import
|
||||
manager.py KeystoreManager -- owns all key material (channel + identity + trust store + backup)
|
||||
models.py IdentityInfo, KeystoreStatus, RotationResult dataclasses
|
||||
export.py Encrypted key bundle export/import (SOOBNDL format)
|
||||
|
||||
c2pa_bridge/ C2PA (Content Authenticity) bridge
|
||||
__init__.py Public API: export, has_c2pa()
|
||||
cert.py Self-signed X.509 cert generation from Ed25519 key
|
||||
export.py AttestationRecord -> C2PA manifest
|
||||
vendor_assertions.py org.fieldwitness.* assertion schemas
|
||||
|
||||
fieldkit/ Field security features
|
||||
killswitch.py Emergency data destruction
|
||||
deadman.py Dead man's switch
|
||||
tamper.py File integrity monitoring
|
||||
killswitch.py Emergency data destruction (PurgeScope.KEYS_ONLY | ALL, deep forensic scrub)
|
||||
deadman.py Dead man's switch (webhook warning + auto-purge)
|
||||
tamper.py File integrity monitoring (baseline snapshots)
|
||||
usb_monitor.py USB device whitelist (Linux/pyudev)
|
||||
geofence.py GPS boundary enforcement
|
||||
geofence.py GPS boundary enforcement (gpsd integration)
|
||||
|
||||
frontends/web/ Unified Flask web UI
|
||||
app.py App factory (create_app())
|
||||
auth.py SQLite3 multi-user auth (from stegasoo)
|
||||
app.py App factory (create_app()), ~36k -- mounts all blueprints
|
||||
auth.py SQLite3 multi-user auth with lockout + rate limiting
|
||||
temp_storage.py File-based temp storage with expiry
|
||||
subprocess_stego.py Crash-safe subprocess isolation for stegasoo
|
||||
ssl_utils.py Self-signed HTTPS cert generation
|
||||
subprocess_stego.py Crash-safe subprocess isolation for stego
|
||||
stego_worker.py Background stego processing
|
||||
stego_routes.py Stego route helpers (~87k)
|
||||
ssl_utils.py Self-signed HTTPS cert generation (cover_name support)
|
||||
blueprints/
|
||||
stego.py /encode, /decode, /generate (from stegasoo)
|
||||
attest.py /attest, /verify (wraps verisoo)
|
||||
stego.py /encode, /decode, /generate
|
||||
attest.py /attest, /verify (~25k -- handles images + arbitrary files)
|
||||
fieldkit.py /fieldkit/* (killswitch, deadman, status)
|
||||
keys.py /keys/* (unified key management)
|
||||
keys.py /keys/* (unified key management, trust store)
|
||||
admin.py /admin/* (user management)
|
||||
dropbox.py /dropbox/* (token-gated anonymous source upload, ~13k)
|
||||
federation.py /federation/* (peer status dashboard, peer add/remove)
|
||||
templates/
|
||||
dropbox/admin.html Drop box admin panel
|
||||
federation/status.html Federation peer dashboard
|
||||
|
||||
frontends/cli/ CLI entry point
|
||||
main.py Click CLI wrapping stegasoo + verisoo + soosef commands
|
||||
frontends/cli/ CLI package init (main entry point is src/fieldwitness/cli.py)
|
||||
|
||||
deploy/ Deployment artifacts
|
||||
docker/ Dockerfile (multi-stage: builder, relay, server) + docker-compose.yml
|
||||
kubernetes/ namespace.yaml, server-deployment.yaml, relay-deployment.yaml
|
||||
live-usb/ build.sh + config/ for Debian Live USB (Tier 1)
|
||||
config-presets/ low-threat.json, medium-threat.json, high-threat.json, critical-threat.json
|
||||
|
||||
docs/ Documentation
|
||||
deployment.md Three-tier deployment guide (~1500 lines)
|
||||
federation.md Gossip protocol, peer setup, offline bundles, CLI commands
|
||||
evidence-guide.md Evidence packages, cold archives, selective disclosure
|
||||
source-dropbox.md Source drop box setup: tokens, EXIF pipeline, receipts
|
||||
architecture/
|
||||
federation.md System architecture overview (threat model, layers, key domains)
|
||||
chain-format.md Chain record spec (CBOR, entropy witnesses, serialization)
|
||||
export-bundle.md Export bundle spec (FIELDWITNESSX1 binary format, envelope encryption)
|
||||
federation-protocol.md Federation server protocol (CT-inspired, gossip, storage tiers)
|
||||
security/
|
||||
threat-model.md Adversary model, guarantees, non-guarantees, known limitations
|
||||
planning/
|
||||
why-fieldwitness.md Problem statement, positioning, scenarios
|
||||
c2pa-integration.md C2PA bridge architecture, concept mapping, implementation phases
|
||||
packaging-strategy.md Hosted demo, standalone binary, mobile app, onboarding flow
|
||||
gtm-feasibility.md Phased plan for credibility, funding, field testing
|
||||
training/
|
||||
reporter-quickstart.md One-page reporter quick-start for Tier 1 USB (print + laminate)
|
||||
reporter-field-guide.md Comprehensive reporter guide: attest, stego, killswitch, evidence
|
||||
emergency-card.md Laminated wallet card: emergency destruction reference
|
||||
admin-reference.md Admin CLI cheat sheet, hardening checklist, troubleshooting
|
||||
admin-operations-guide.md Full admin operations: users, dropbox, federation, incidents
|
||||
```
|
||||
|
||||
## Three-tier deployment model
|
||||
|
||||
```
|
||||
Tier 1: Field Device Tier 2: Org Server Tier 3: Federation Relay
|
||||
(Bootable USB + laptop) (Docker on mini PC / VPS) (Docker on VPS)
|
||||
Amnesic, LUKS-encrypted Persistent, full features Attestation sync only
|
||||
Reporter in the field Newsroom / NGO office Friendly jurisdiction
|
||||
```
|
||||
|
||||
- Tier 1 <-> Tier 2: sneakernet (USB drive) or LAN
|
||||
- Tier 2 <-> Tier 3: federation API (port 8000) over internet
|
||||
- Tier 2 <-> Tier 2: via Tier 3 relay, or directly via sneakernet
|
||||
|
||||
## Dependency model
|
||||
|
||||
Stegasoo and Verisoo are pip dependencies, not forks:
|
||||
- `import stegasoo` for steganography
|
||||
- `import verisoo` for provenance attestation
|
||||
- SooSeF adds: unified web UI, key management, fieldkit features
|
||||
Stego and Attest are inlined subpackages, not separate pip packages:
|
||||
- `from fieldwitness.stego import encode` for steganography
|
||||
- `from fieldwitness.attest import Attestation` for provenance attestation
|
||||
- Never `import fieldwitness.stego` or `import fieldwitness.attest` directly
|
||||
- `_availability.py` provides `has_stego()` / `has_attest()` for graceful degradation
|
||||
when optional extras are not installed
|
||||
|
||||
## Key design decisions
|
||||
|
||||
- **Two key domains, never merged**: Stegasoo AES-256-GCM (derived from factors) and
|
||||
Verisoo Ed25519 (signing identity) are separate security concerns
|
||||
- **subprocess_stego.py copies verbatim** from stegasoo — it's a crash-safety boundary
|
||||
- **All state under ~/.soosef/** — one directory to back up, one to destroy
|
||||
- **Two key domains, never merged**: Stego AES-256-GCM (derived from factors) and
|
||||
Attest Ed25519 (signing identity) are separate security concerns
|
||||
- **Extract-then-strip model**: Stego strips all EXIF (carrier is vessel); attestation
|
||||
extracts evidentiary EXIF (GPS, timestamp) then strips dangerous fields (device serial)
|
||||
- **subprocess_stego.py copies verbatim** from fieldwitness.stego -- it's a crash-safety boundary
|
||||
- **All state under ~/.fwmetadata/** -- one directory to back up, one to destroy.
|
||||
`FIELDWITNESS_DATA_DIR` env var relocates everything (cover mode, USB mode)
|
||||
- **Offline-first**: All static assets vendored, no CDN. pip wheels bundled for airgap install
|
||||
- **Flask blueprints**: stego, attest, fieldkit, keys, admin — clean route separation
|
||||
- **Flask blueprints**: stego, attest, fieldkit, keys, admin, dropbox, federation
|
||||
- **Flask-WTF**: CSRF protection on all form endpoints; drop box is CSRF-exempt (sources
|
||||
don't have sessions)
|
||||
- **Client-side SHA-256**: Drop box upload page uses SubtleCrypto for pre-upload hashing
|
||||
- **Waitress**: Production WSGI server (replaces dev-only Flask server)
|
||||
- **FastAPI option**: `fieldwitness.api` provides a REST API alternative to the Flask web UI
|
||||
- **Pluggable backends**: Stego backends (LSB, DCT) registered via `backends/registry.py`
|
||||
- **ImageHashes generalized**: phash/dhash now optional, enabling non-image attestation
|
||||
- **Lazy path resolution**: All paths in paths.py resolve lazily via `__getattr__` from
|
||||
`BASE_DIR` so that runtime overrides (--data-dir, FIELDWITNESS_DATA_DIR) propagate correctly
|
||||
- **Two-way federation**: Delivery acknowledgment records (`fieldwitness/delivery-ack-v1`)
|
||||
enable handshake proof
|
||||
- **Chain record types** (in federation/chain.py):
|
||||
- `CONTENT_TYPE_KEY_ROTATION = "fieldwitness/key-rotation-v1"` -- signed by OLD key
|
||||
- `CONTENT_TYPE_KEY_RECOVERY = "fieldwitness/key-recovery-v1"` -- signed by NEW key
|
||||
- `CONTENT_TYPE_DELIVERY_ACK = "fieldwitness/delivery-ack-v1"` -- signed by receiver
|
||||
- **Gossip federation** (attest/federation.py): GossipNode with async peer sync,
|
||||
consistency proofs, HttpTransport over aiohttp. PeerStore for SQLite-backed persistence
|
||||
- **Threat level presets**: deploy/config-presets/ with low/medium/high/critical configs
|
||||
- **Selective disclosure**: Chain records can be exported with non-selected records
|
||||
redacted to hashes only (for legal discovery)
|
||||
- **Evidence packages**: Self-contained ZIPs with verify.py that needs only Python + cryptography
|
||||
- **Cold archives**: OAIS-aligned full-state export with ALGORITHMS.txt
|
||||
- **Transport-aware stego**: --transport whatsapp|signal|telegram auto-selects DCT/JPEG
|
||||
and pre-resizes carrier for platform survival
|
||||
|
||||
## Data directory layout (`~/.fwmetadata/`)
|
||||
|
||||
```
|
||||
~/.fwmetadata/
|
||||
config.json Unified configuration (FieldWitnessConfig dataclass)
|
||||
audit.jsonl Append-only audit trail (JSON-lines)
|
||||
carrier_history.json Carrier reuse tracking database
|
||||
identity/ Ed25519 keypair (private.pem, public.pem, identity.meta.json)
|
||||
archived/ Timestamped old keypairs from rotations
|
||||
stego/ Channel key (channel.key)
|
||||
archived/ Timestamped old channel keys from rotations
|
||||
attestations/ Attest attestation store
|
||||
log.bin Binary attestation log
|
||||
index/ LMDB index
|
||||
peers.json Legacy peer file
|
||||
federation/ Federation state
|
||||
peers.db SQLite peer + sync history
|
||||
chain/ Hash chain (chain.bin, state.cbor)
|
||||
anchors/ External timestamp anchors (JSON files)
|
||||
auth/ Web UI auth databases
|
||||
fieldwitness.db User accounts
|
||||
dropbox.db Drop box tokens + receipts
|
||||
certs/ Self-signed TLS certificates (cert.pem, key.pem)
|
||||
fieldkit/ Fieldkit state
|
||||
deadman.json Dead man's switch timer
|
||||
tamper/baseline.json File integrity baselines
|
||||
usb/whitelist.json USB device whitelist
|
||||
geofence.json GPS boundary config
|
||||
temp/ Ephemeral file storage
|
||||
dropbox/ Source drop box submissions
|
||||
instance/ Flask instance (sessions, .secret_key)
|
||||
trusted_keys/ Collaborator Ed25519 public keys (trust store)
|
||||
<fingerprint>/ Per-key directory (public.pem + meta.json)
|
||||
last_backup.json Backup timestamp tracking
|
||||
```
|
||||
|
||||
## Code conventions
|
||||
|
||||
Same as stegasoo: Black (100-char), Ruff, mypy, imperative commit messages.
|
||||
Black (100-char), Ruff (E, F, I, N, W, UP), mypy (strict, ignore_missing_imports),
|
||||
imperative commit messages.
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
pytest # All tests with coverage
|
||||
pytest tests/test_chain.py # Chain-specific
|
||||
```
|
||||
|
||||
Test files: `test_chain.py`, `test_chain_security.py`, `test_deadman_enforcement.py`,
|
||||
`test_key_rotation.py`, `test_killswitch.py`, `test_serialization.py`,
|
||||
`test_stego_audio.py`, `test_stego.py`, `test_attest_hashing.py`
|
||||
|
||||
674
LICENSE
Normal file
674
LICENSE
Normal file
@ -0,0 +1,674 @@
|
||||
GNU GENERAL PUBLIC LICENSE
|
||||
Version 3, 29 June 2007
|
||||
|
||||
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
|
||||
Everyone is permitted to copy and distribute verbatim copies
|
||||
of this license document, but changing it is not allowed.
|
||||
|
||||
Preamble
|
||||
|
||||
The GNU General Public License is a free, copyleft license for
|
||||
software and other kinds of works.
|
||||
|
||||
The licenses for most software and other practical works are designed
|
||||
to take away your freedom to share and change the works. By contrast,
|
||||
the GNU General Public License is intended to guarantee your freedom to
|
||||
share and change all versions of a program--to make sure it remains free
|
||||
software for all its users. We, the Free Software Foundation, use the
|
||||
GNU General Public License for most of our software; it applies also to
|
||||
any other work released this way by its authors. You can apply it to
|
||||
your programs, too.
|
||||
|
||||
When we speak of free software, we are referring to freedom, not
|
||||
price. Our General Public Licenses are designed to make sure that you
|
||||
have the freedom to distribute copies of free software (and charge for
|
||||
them if you wish), that you receive source code or can get it if you
|
||||
want it, that you can change the software or use pieces of it in new
|
||||
free programs, and that you know you can do these things.
|
||||
|
||||
To protect your rights, we need to prevent others from denying you
|
||||
these rights or asking you to surrender the rights. Therefore, you have
|
||||
certain responsibilities if you distribute copies of the software, or if
|
||||
you modify it: responsibilities to respect the freedom of others.
|
||||
|
||||
For example, if you distribute copies of such a program, whether
|
||||
gratis or for a fee, you must pass on to the recipients the same
|
||||
freedoms that you received. You must make sure that they, too, receive
|
||||
or can get the source code. And you must show them these terms so they
|
||||
know their rights.
|
||||
|
||||
Developers that use the GNU GPL protect your rights with two steps:
|
||||
(1) assert copyright on the software, and (2) offer you this License
|
||||
giving you legal permission to copy, distribute and/or modify it.
|
||||
|
||||
For the developers' and authors' protection, the GPL clearly explains
|
||||
that there is no warranty for this free software. For both users' and
|
||||
authors' sake, the GPL requires that modified versions be marked as
|
||||
changed, so that their problems will not be attributed erroneously to
|
||||
authors of previous versions.
|
||||
|
||||
Some devices are designed to deny users access to install or run
|
||||
modified versions of the software inside them, although the manufacturer
|
||||
can do so. This is fundamentally incompatible with the aim of
|
||||
protecting users' freedom to change the software. The systematic
|
||||
pattern of such abuse occurs in the area of products for individuals to
|
||||
use, which is precisely where it is most unacceptable. Therefore, we
|
||||
have designed this version of the GPL to prohibit the practice for those
|
||||
products. If such problems arise substantially in other domains, we
|
||||
stand ready to extend this provision to those domains in future versions
|
||||
of the GPL, as needed to protect the freedom of users.
|
||||
|
||||
Finally, every program is threatened constantly by software patents.
|
||||
States should not allow patents to restrict development and use of
|
||||
software on general-purpose computers, but in those that do, we wish to
|
||||
avoid the special danger that patents applied to a free program could
|
||||
make it effectively proprietary. To prevent this, the GPL assures that
|
||||
patents cannot be used to render the program non-free.
|
||||
|
||||
The precise terms and conditions for copying, distribution and
|
||||
modification follow.
|
||||
|
||||
TERMS AND CONDITIONS
|
||||
|
||||
0. Definitions.
|
||||
|
||||
"This License" refers to version 3 of the GNU General Public License.
|
||||
|
||||
"Copyright" also means copyright-like laws that apply to other kinds of
|
||||
works, such as semiconductor masks.
|
||||
|
||||
"The Program" refers to any copyrightable work licensed under this
|
||||
License. Each licensee is addressed as "you". "Licensees" and
|
||||
"recipients" may be individuals or organizations.
|
||||
|
||||
To "modify" a work means to copy from or adapt all or part of the work
|
||||
in a fashion requiring copyright permission, other than the making of an
|
||||
exact copy. The resulting work is called a "modified version" of the
|
||||
earlier work or a work "based on" the earlier work.
|
||||
|
||||
A "covered work" means either the unmodified Program or a work based
|
||||
on the Program.
|
||||
|
||||
To "propagate" a work means to do anything with it that, without
|
||||
permission, would make you directly or secondarily liable for
|
||||
infringement under applicable copyright law, except executing it on a
|
||||
computer or modifying a private copy. Propagation includes copying,
|
||||
distribution (with or without modification), making available to the
|
||||
public, and in some countries other activities as well.
|
||||
|
||||
To "convey" a work means any kind of propagation that enables other
|
||||
parties to make or receive copies. Mere interaction with a user through
|
||||
a computer network, with no transfer of a copy, is not conveying.
|
||||
|
||||
An interactive user interface displays "Appropriate Legal Notices"
|
||||
to the extent that it includes a convenient and prominently visible
|
||||
feature that (1) displays an appropriate copyright notice, and (2)
|
||||
tells the user that there is no warranty for the work (except to the
|
||||
extent that warranties are provided), that licensees may convey the
|
||||
work under this License, and how to view a copy of this License. If
|
||||
the interface presents a list of user commands or options, such as a
|
||||
menu, a prominent item in the list meets this criterion.
|
||||
|
||||
1. Source Code.
|
||||
|
||||
The "source code" for a work means the preferred form of the work
|
||||
for making modifications to it. "Object code" means any non-source
|
||||
form of a work.
|
||||
|
||||
A "Standard Interface" means an interface that either is an official
|
||||
standard defined by a recognized standards body, or, in the case of
|
||||
interfaces specified for a particular programming language, one that
|
||||
is widely used among developers working in that language.
|
||||
|
||||
The "System Libraries" of an executable work include anything, other
|
||||
than the work as a whole, that (a) is included in the normal form of
|
||||
packaging a Major Component, but which is not part of that Major
|
||||
Component, and (b) serves only to enable use of the work with that
|
||||
Major Component, or to implement a Standard Interface for which an
|
||||
implementation is available to the public in source code form. A
|
||||
"Major Component", in this context, means a major essential component
|
||||
(kernel, window system, and so on) of the specific operating system
|
||||
(if any) on which the executable work runs, or a compiler used to
|
||||
produce the work, or an object code interpreter used to run it.
|
||||
|
||||
The "Corresponding Source" for a work in object code form means all
|
||||
the source code needed to generate, install, and (for an executable
|
||||
work) run the object code and to modify the work, including scripts to
|
||||
control those activities. However, it does not include the work's
|
||||
System Libraries, or general-purpose tools or generally available free
|
||||
programs which are used unmodified in performing those activities but
|
||||
which are not part of the work. For example, Corresponding Source
|
||||
includes interface definition files associated with source files for
|
||||
the work, and the source code for shared libraries and dynamically
|
||||
linked subprograms that the work is specifically designed to require,
|
||||
such as by intimate data communication or control flow between those
|
||||
subprograms and other parts of the work.
|
||||
|
||||
The Corresponding Source need not include anything that users
|
||||
can regenerate automatically from other parts of the Corresponding
|
||||
Source.
|
||||
|
||||
The Corresponding Source for a work in source code form is that
|
||||
same work.
|
||||
|
||||
2. Basic Permissions.
|
||||
|
||||
All rights granted under this License are granted for the term of
|
||||
copyright on the Program, and are irrevocable provided the stated
|
||||
conditions are met. This License explicitly affirms your unlimited
|
||||
permission to run the unmodified Program. The output from running a
|
||||
covered work is covered by this License only if the output, given its
|
||||
content, constitutes a covered work. This License acknowledges your
|
||||
rights of fair use or other equivalent, as provided by copyright law.
|
||||
|
||||
You may make, run and propagate covered works that you do not
|
||||
convey, without conditions so long as your license otherwise remains
|
||||
in force. You may convey covered works to others for the sole purpose
|
||||
of having them make modifications exclusively for you, or provide you
|
||||
with facilities for running those works, provided that you comply with
|
||||
the terms of this License in conveying all material for which you do
|
||||
not control copyright. Those thus making or running the covered works
|
||||
for you must do so exclusively on your behalf, under your direction
|
||||
and control, on terms that prohibit them from making any copies of
|
||||
your copyrighted material outside their relationship with you.
|
||||
|
||||
Conveying under any other circumstances is permitted solely under
|
||||
the conditions stated below. Sublicensing is not allowed; section 10
|
||||
makes it unnecessary.
|
||||
|
||||
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
|
||||
|
||||
No covered work shall be deemed part of an effective technological
|
||||
measure under any applicable law fulfilling obligations under article
|
||||
11 of the WIPO copyright treaty adopted on 20 December 1996, or
|
||||
similar laws prohibiting or restricting circumvention of such
|
||||
measures.
|
||||
|
||||
When you convey a covered work, you waive any legal power to forbid
|
||||
circumvention of technological measures to the extent such circumvention
|
||||
is effected by exercising rights under this License with respect to
|
||||
the covered work, and you disclaim any intention to limit operation or
|
||||
modification of the work as a means of enforcing, against the work's
|
||||
users, your or third parties' legal rights to forbid circumvention of
|
||||
technological measures.
|
||||
|
||||
4. Conveying Verbatim Copies.
|
||||
|
||||
You may convey verbatim copies of the Program's source code as you
|
||||
receive it, in any medium, provided that you conspicuously and
|
||||
appropriately publish on each copy an appropriate copyright notice;
|
||||
keep intact all notices stating that this License and any
|
||||
non-permissive terms added in accord with section 7 apply to the code;
|
||||
keep intact all notices of the absence of any warranty; and give all
|
||||
recipients a copy of this License along with the Program.
|
||||
|
||||
You may charge any price or no price for each copy that you convey,
|
||||
and you may offer support or warranty protection for a fee.
|
||||
|
||||
5. Conveying Modified Source Versions.
|
||||
|
||||
You may convey a work based on the Program, or the modifications to
|
||||
produce it from the Program, in the form of source code under the
|
||||
terms of section 4, provided that you also meet all of these conditions:
|
||||
|
||||
a) The work must carry prominent notices stating that you modified
|
||||
it, and giving a relevant date.
|
||||
|
||||
b) The work must carry prominent notices stating that it is
|
||||
released under this License and any conditions added under section
|
||||
7. This requirement modifies the requirement in section 4 to
|
||||
"keep intact all notices".
|
||||
|
||||
c) You must license the entire work, as a whole, under this
|
||||
License to anyone who comes into possession of a copy. This
|
||||
License will therefore apply, along with any applicable section 7
|
||||
additional terms, to the whole of the work, and all its parts,
|
||||
regardless of how they are packaged. This License gives no
|
||||
permission to license the work in any other way, but it does not
|
||||
invalidate such permission if you have separately received it.
|
||||
|
||||
d) If the work has interactive user interfaces, each must display
|
||||
Appropriate Legal Notices; however, if the Program has interactive
|
||||
interfaces that do not display Appropriate Legal Notices, your
|
||||
work need not make them do so.
|
||||
|
||||
A compilation of a covered work with other separate and independent
|
||||
works, which are not by their nature extensions of the covered work,
|
||||
and which are not combined with it such as to form a larger program,
|
||||
in or on a volume of a storage or distribution medium, is called an
|
||||
"aggregate" if the compilation and its resulting copyright are not
|
||||
used to limit the access or legal rights of the compilation's users
|
||||
beyond what the individual works permit. Inclusion of a covered work
|
||||
in an aggregate does not cause this License to apply to the other
|
||||
parts of the aggregate.
|
||||
|
||||
6. Conveying Non-Source Forms.
|
||||
|
||||
You may convey a covered work in object code form under the terms
|
||||
of sections 4 and 5, provided that you also convey the
|
||||
machine-readable Corresponding Source under the terms of this License,
|
||||
in one of these ways:
|
||||
|
||||
a) Convey the object code in, or embodied in, a physical product
|
||||
(including a physical distribution medium), accompanied by the
|
||||
Corresponding Source fixed on a durable physical medium
|
||||
customarily used for software interchange.
|
||||
|
||||
b) Convey the object code in, or embodied in, a physical product
|
||||
(including a physical distribution medium), accompanied by a
|
||||
written offer, valid for at least three years and valid for as
|
||||
long as you offer spare parts or customer support for that product
|
||||
model, to give anyone who possesses the object code either (1) a
|
||||
copy of the Corresponding Source for all the software in the
|
||||
product that is covered by this License, on a durable physical
|
||||
medium customarily used for software interchange, for a price no
|
||||
more than your reasonable cost of physically performing this
|
||||
conveying of source, or (2) access to copy the
|
||||
Corresponding Source from a network server at no charge.
|
||||
|
||||
c) Convey individual copies of the object code with a copy of the
|
||||
written offer to provide the Corresponding Source. This
|
||||
alternative is allowed only occasionally and noncommercially, and
|
||||
only if you received the object code with such an offer, in accord
|
||||
with subsection 6b.
|
||||
|
||||
d) Convey the object code by offering access from a designated
|
||||
place (gratis or for a charge), and offer equivalent access to the
|
||||
Corresponding Source in the same way through the same place at no
|
||||
further charge. You need not require recipients to copy the
|
||||
Corresponding Source along with the object code. If the place to
|
||||
copy the object code is a network server, the Corresponding Source
|
||||
may be on a different server (operated by you or a third party)
|
||||
that supports equivalent copying facilities, provided you maintain
|
||||
clear directions next to the object code saying where to find the
|
||||
Corresponding Source. Regardless of what server hosts the
|
||||
Corresponding Source, you remain obligated to ensure that it is
|
||||
available for as long as needed to satisfy these requirements.
|
||||
|
||||
e) Convey the object code using peer-to-peer transmission, provided
|
||||
you inform other peers where the object code and Corresponding
|
||||
Source of the work are being offered to the general public at no
|
||||
charge under subsection 6d.
|
||||
|
||||
A separable portion of the object code, whose source code is excluded
|
||||
from the Corresponding Source as a System Library, need not be
|
||||
included in conveying the object code work.
|
||||
|
||||
A "User Product" is either (1) a "consumer product", which means any
|
||||
tangible personal property which is normally used for personal, family,
|
||||
or household purposes, or (2) anything designed or sold for incorporation
|
||||
into a dwelling. In determining whether a product is a consumer product,
|
||||
doubtful cases shall be resolved in favor of coverage. For a particular
|
||||
product received by a particular user, "normally used" refers to a
|
||||
typical or common use of that class of product, regardless of the status
|
||||
of the particular user or of the way in which the particular user
|
||||
actually uses, or expects or is expected to use, the product. A product
|
||||
is a consumer product regardless of whether the product has substantial
|
||||
commercial, industrial or non-consumer uses, unless such uses represent
|
||||
the only significant mode of use of the product.
|
||||
|
||||
"Installation Information" for a User Product means any methods,
|
||||
procedures, authorization keys, or other information required to install
|
||||
and execute modified versions of a covered work in that User Product from
|
||||
a modified version of its Corresponding Source. The information must
|
||||
suffice to ensure that the continued functioning of the modified object
|
||||
code is in no case prevented or interfered with solely because
|
||||
modification has been made.
|
||||
|
||||
If you convey an object code work under this section in, or with, or
|
||||
specifically for use in, a User Product, and the conveying occurs as
|
||||
part of a transaction in which the right of possession and use of the
|
||||
User Product is transferred to the recipient in perpetuity or for a
|
||||
fixed term (regardless of how the transaction is characterized), the
|
||||
Corresponding Source conveyed under this section must be accompanied
|
||||
by the Installation Information. But this requirement does not apply
|
||||
if neither you nor any third party retains the ability to install
|
||||
modified object code on the User Product (for example, the work has
|
||||
been installed in ROM).
|
||||
|
||||
The requirement to provide Installation Information does not include a
|
||||
requirement to continue to provide support service, warranty, or updates
|
||||
for a work that has been modified or installed by the recipient, or for
|
||||
the User Product in which it has been modified or installed. Access to a
|
||||
network may be denied when the modification itself materially and
|
||||
adversely affects the operation of the network or violates the rules and
|
||||
protocols for communication across the network.
|
||||
|
||||
Corresponding Source conveyed, and Installation Information provided,
|
||||
in accord with this section must be in a format that is publicly
|
||||
documented (and with an implementation available to the public in
|
||||
source code form), and must require no special password or key for
|
||||
unpacking, reading or copying.
|
||||
|
||||
7. Additional Terms.
|
||||
|
||||
"Additional permissions" are terms that supplement the terms of this
|
||||
License by making exceptions from one or more of its conditions.
|
||||
Additional permissions that are applicable to the entire Program shall
|
||||
be treated as though they were included in this License, to the extent
|
||||
that they are valid under applicable law. If additional permissions
|
||||
apply only to part of the Program, that part may be used separately
|
||||
under those permissions, but the entire Program remains governed by
|
||||
this License without regard to the additional permissions.
|
||||
|
||||
When you convey a copy of a covered work, you may at your option
|
||||
remove any additional permissions from that copy, or from any part of
|
||||
it. (Additional permissions may be written to require their own
|
||||
removal in certain cases when you modify the work.) You may place
|
||||
additional permissions on material, added by you to a covered work,
|
||||
for which you have or can give appropriate copyright permission.
|
||||
|
||||
Notwithstanding any other provision of this License, for material you
|
||||
add to a covered work, you may (if authorized by the copyright holders of
|
||||
that material) supplement the terms of this License with terms:
|
||||
|
||||
a) Disclaiming warranty or limiting liability differently from the
|
||||
terms of sections 15 and 16 of this License; or
|
||||
|
||||
b) Requiring preservation of specified reasonable legal notices or
|
||||
author attributions in that material or in the Appropriate Legal
|
||||
Notices displayed by works containing it; or
|
||||
|
||||
c) Prohibiting misrepresentation of the origin of that material, or
|
||||
requiring that modified versions of such material be marked in
|
||||
reasonable ways as different from the original version; or
|
||||
|
||||
d) Limiting the use for publicity purposes of names of licensors or
|
||||
authors of the material; or
|
||||
|
||||
e) Declining to grant rights under trademark law for use of some
|
||||
trade names, trademarks, or service marks; or
|
||||
|
||||
f) Requiring indemnification of licensors and authors of that
|
||||
material by anyone who conveys the material (or modified versions of
|
||||
it) with contractual assumptions of liability to the recipient, for
|
||||
any liability that these contractual assumptions directly impose on
|
||||
those licensors and authors.
|
||||
|
||||
All other non-permissive additional terms are considered "further
|
||||
restrictions" within the meaning of section 10. If the Program as you
|
||||
received it, or any part of it, contains a notice stating that it is
|
||||
governed by this License along with a term that is a further
|
||||
restriction, you may remove that term. If a license document contains
|
||||
a further restriction but permits relicensing or conveying under this
|
||||
License, you may add to a covered work material governed by the terms
|
||||
of that license document, provided that the further restriction does
|
||||
not survive such relicensing or conveying.
|
||||
|
||||
If you add terms to a covered work in accord with this section, you
|
||||
must place, in the relevant source files, a statement of the
|
||||
additional terms that apply to those files, or a notice indicating
|
||||
where to find the applicable terms.
|
||||
|
||||
Additional terms, permissive or non-permissive, may be stated in the
|
||||
form of a separately written license, or stated as exceptions;
|
||||
the above requirements apply either way.
|
||||
|
||||
8. Termination.
|
||||
|
||||
You may not propagate or modify a covered work except as expressly
|
||||
provided under this License. Any attempt otherwise to propagate or
|
||||
modify it is void, and will automatically terminate your rights under
|
||||
this License (including any patent licenses granted under the third
|
||||
paragraph of section 11).
|
||||
|
||||
However, if you cease all violation of this License, then your
|
||||
license from a particular copyright holder is reinstated (a)
|
||||
provisionally, unless and until the copyright holder explicitly and
|
||||
finally terminates your license, and (b) permanently, if the copyright
|
||||
holder fails to notify you of the violation by some reasonable means
|
||||
prior to 60 days after the cessation.
|
||||
|
||||
Moreover, your license from a particular copyright holder is
|
||||
reinstated permanently if the copyright holder notifies you of the
|
||||
violation by some reasonable means, this is the first time you have
|
||||
received notice of violation of this License (for any work) from that
|
||||
copyright holder, and you cure the violation prior to 30 days after
|
||||
your receipt of the notice.
|
||||
|
||||
Termination of your rights under this section does not terminate the
|
||||
licenses of parties who have received copies or rights from you under
|
||||
this License. If your rights have been terminated and not permanently
|
||||
reinstated, you do not qualify to receive new licenses for the same
|
||||
material under section 10.
|
||||
|
||||
9. Acceptance Not Required for Having Copies.
|
||||
|
||||
You are not required to accept this License in order to receive or
|
||||
run a copy of the Program. Ancillary propagation of a covered work
|
||||
occurring solely as a consequence of using peer-to-peer transmission
|
||||
to receive a copy likewise does not require acceptance. However,
|
||||
nothing other than this License grants you permission to propagate or
|
||||
modify any covered work. These actions infringe copyright if you do
|
||||
not accept this License. Therefore, by modifying or propagating a
|
||||
covered work, you indicate your acceptance of this License to do so.
|
||||
|
||||
10. Automatic Licensing of Downstream Recipients.
|
||||
|
||||
Each time you convey a covered work, the recipient automatically
|
||||
receives a license from the original licensors, to run, modify and
|
||||
propagate that work, subject to this License. You are not responsible
|
||||
for enforcing compliance by third parties with this License.
|
||||
|
||||
An "entity transaction" is a transaction transferring control of an
|
||||
organization, or substantially all assets of one, or subdividing an
|
||||
organization, or merging organizations. If propagation of a covered
|
||||
work results from an entity transaction, each party to that
|
||||
transaction who receives a copy of the work also receives whatever
|
||||
licenses to the work the party's predecessor in interest had or could
|
||||
give under the previous paragraph, plus a right to possession of the
|
||||
Corresponding Source of the work from the predecessor in interest, if
|
||||
the predecessor has it or can get it with reasonable efforts.
|
||||
|
||||
You may not impose any further restrictions on the exercise of the
|
||||
rights granted or affirmed under this License. For example, you may
|
||||
not impose a license fee, royalty, or other charge for exercise of
|
||||
rights granted under this License, and you may not initiate litigation
|
||||
(including a cross-claim or counterclaim in a lawsuit) alleging that
|
||||
any patent claim is infringed by making, using, selling, offering for
|
||||
sale, or importing the Program or any portion of it.
|
||||
|
||||
11. Patents.
|
||||
|
||||
A "contributor" is a copyright holder who authorizes use under this
|
||||
License of the Program or a work on which the Program is based. The
|
||||
work thus licensed is called the contributor's "contributor version".
|
||||
|
||||
A contributor's "essential patent claims" are all patent claims
|
||||
owned or controlled by the contributor, whether already acquired or
|
||||
hereafter acquired, that would be infringed by some manner, permitted
|
||||
by this License, of making, using, or selling its contributor version,
|
||||
but do not include claims that would be infringed only as a
|
||||
consequence of further modification of the contributor version. For
|
||||
purposes of this definition, "control" includes the right to grant
|
||||
patent sublicenses in a manner consistent with the requirements of
|
||||
this License.
|
||||
|
||||
Each contributor grants you a non-exclusive, worldwide, royalty-free
|
||||
patent license under the contributor's essential patent claims, to
|
||||
make, use, sell, offer for sale, import and otherwise run, modify and
|
||||
propagate the contents of its contributor version.
|
||||
|
||||
In the following three paragraphs, a "patent license" is any express
|
||||
agreement or commitment, however denominated, not to enforce a patent
|
||||
(such as an express permission to practice a patent or covenant not to
|
||||
sue for patent infringement). To "grant" such a patent license to a
|
||||
party means to make such an agreement or commitment not to enforce a
|
||||
patent against the party.
|
||||
|
||||
If you convey a covered work, knowingly relying on a patent license,
|
||||
and the Corresponding Source of the work is not available for anyone
|
||||
to copy, free of charge and under the terms of this License, through a
|
||||
publicly available network server or other readily accessible means,
|
||||
then you must either (1) cause the Corresponding Source to be so
|
||||
available, or (2) arrange to deprive yourself of the benefit of the
|
||||
patent license for this particular work, or (3) arrange, in a manner
|
||||
consistent with the requirements of this License, to extend the patent
|
||||
license to downstream recipients. "Knowingly relying" means you have
|
||||
actual knowledge that, but for the patent license, your conveying the
|
||||
covered work in a country, or your recipient's use of the covered work
|
||||
in a country, would infringe one or more identifiable patents in that
|
||||
country that you have reason to believe are valid.
|
||||
|
||||
If, pursuant to or in connection with a single transaction or
|
||||
arrangement, you convey, or propagate by procuring conveyance of, a
|
||||
covered work, and grant a patent license to some of the parties
|
||||
receiving the covered work authorizing them to use, propagate, modify
|
||||
or convey a specific copy of the covered work, then the patent license
|
||||
you grant is automatically extended to all recipients of the covered
|
||||
work and works based on it.
|
||||
|
||||
A patent license is "discriminatory" if it does not include within
|
||||
the scope of its coverage, prohibits the exercise of, or is
|
||||
conditioned on the non-exercise of one or more of the rights that are
|
||||
specifically granted under this License. You may not convey a covered
|
||||
work if you are a party to an arrangement with a third party that is
|
||||
in the business of distributing software, under which you make payment
|
||||
to the third party based on the extent of your activity of conveying
|
||||
the work, and under which the third party grants, to any of the
|
||||
parties who would receive the covered work from you, a discriminatory
|
||||
patent license (a) in connection with copies of the covered work
|
||||
conveyed by you (or copies made from those copies), or (b) primarily
|
||||
for and in connection with specific products or compilations that
|
||||
contain the covered work, unless you entered into that arrangement,
|
||||
or that patent license was granted, prior to 28 March 2007.
|
||||
|
||||
Nothing in this License shall be construed as excluding or limiting
|
||||
any implied license or other defenses to infringement that may
|
||||
otherwise be available to you under applicable patent law.
|
||||
|
||||
12. No Surrender of Others' Freedom.
|
||||
|
||||
If conditions are imposed on you (whether by court order, agreement or
|
||||
otherwise) that contradict the conditions of this License, they do not
|
||||
excuse you from the conditions of this License. If you cannot convey a
|
||||
covered work so as to satisfy simultaneously your obligations under this
|
||||
License and any other pertinent obligations, then as a consequence you may
|
||||
not convey it at all. For example, if you agree to terms that obligate you
|
||||
to collect a royalty for further conveying from those to whom you convey
|
||||
the Program, the only way you could satisfy both those terms and this
|
||||
License would be to refrain entirely from conveying the Program.
|
||||
|
||||
13. Use with the GNU Affero General Public License.
|
||||
|
||||
Notwithstanding any other provision of this License, you have
|
||||
permission to link or combine any covered work with a work licensed
|
||||
under version 3 of the GNU Affero General Public License into a single
|
||||
combined work, and to convey the resulting work. The terms of this
|
||||
License will continue to apply to the part which is the covered work,
|
||||
but the special requirements of the GNU Affero General Public License,
|
||||
section 13, concerning interaction through a network will apply to the
|
||||
combination as such.
|
||||
|
||||
14. Revised Versions of this License.
|
||||
|
||||
The Free Software Foundation may publish revised and/or new versions of
|
||||
the GNU General Public License from time to time. Such new versions will
|
||||
be similar in spirit to the present version, but may differ in detail to
|
||||
address new problems or concerns.
|
||||
|
||||
Each version is given a distinguishing version number. If the
|
||||
Program specifies that a certain numbered version of the GNU General
|
||||
Public License "or any later version" applies to it, you have the
|
||||
option of following the terms and conditions either of that numbered
|
||||
version or of any later version published by the Free Software
|
||||
Foundation. If the Program does not specify a version number of the
|
||||
GNU General Public License, you may choose any version ever published
|
||||
by the Free Software Foundation.
|
||||
|
||||
If the Program specifies that a proxy can decide which future
|
||||
versions of the GNU General Public License can be used, that proxy's
|
||||
public statement of acceptance of a version permanently authorizes you
|
||||
to choose that version for the Program.
|
||||
|
||||
Later license versions may give you additional or different
|
||||
permissions. However, no additional obligations are imposed on any
|
||||
author or copyright holder as a result of your choosing to follow a
|
||||
later version.
|
||||
|
||||
15. Disclaimer of Warranty.
|
||||
|
||||
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
|
||||
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
|
||||
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
|
||||
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
|
||||
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
||||
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
|
||||
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
|
||||
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
|
||||
|
||||
16. Limitation of Liability.
|
||||
|
||||
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
|
||||
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
|
||||
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
|
||||
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
|
||||
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
|
||||
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
|
||||
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
|
||||
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
|
||||
SUCH DAMAGES.
|
||||
|
||||
17. Interpretation of Sections 15 and 16.
|
||||
|
||||
If the disclaimer of warranty and limitation of liability provided
|
||||
above cannot be given local legal effect according to their terms,
|
||||
reviewing courts shall apply local law that most closely approximates
|
||||
an absolute waiver of all civil liability in connection with the
|
||||
Program, unless a warranty or assumption of liability accompanies a
|
||||
copy of the Program in return for a fee.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
How to Apply These Terms to Your New Programs
|
||||
|
||||
If you develop a new program, and you want it to be of the greatest
|
||||
possible use to the public, the best way to achieve this is to make it
|
||||
free software which everyone can redistribute and change under these terms.
|
||||
|
||||
To do so, attach the following notices to the program. It is safest
|
||||
to attach them to the start of each source file to most effectively
|
||||
state the exclusion of warranty; and each file should have at least
|
||||
the "copyright" line and a pointer to where the full notice is found.
|
||||
|
||||
<one line to give the program's name and a brief idea of what it does.>
|
||||
Copyright (C) <year> <name of author>
|
||||
|
||||
This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation, either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||
|
||||
Also add information on how to contact you by electronic and paper mail.
|
||||
|
||||
If the program does terminal interaction, make it output a short
|
||||
notice like this when it starts in an interactive mode:
|
||||
|
||||
<program> Copyright (C) <year> <name of author>
|
||||
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
|
||||
This is free software, and you are welcome to redistribute it
|
||||
under certain conditions; type `show c' for details.
|
||||
|
||||
The hypothetical commands `show w' and `show c' should show the appropriate
|
||||
parts of the General Public License. Of course, your program's commands
|
||||
might be different; for a GUI interface, you would use an "about box".
|
||||
|
||||
You should also get your employer (if you work as a programmer) or school,
|
||||
if any, to sign a "copyright disclaimer" for the program, if necessary.
|
||||
For more information on this, and how to apply and follow the GNU GPL, see
|
||||
<https://www.gnu.org/licenses/>.
|
||||
|
||||
The GNU General Public License does not permit incorporating your program
|
||||
into proprietary programs. If your program is a subroutine library, you
|
||||
may consider it more useful to permit linking proprietary applications with
|
||||
the library. If this is what you want to do, use the GNU Lesser General
|
||||
Public License instead of this License. But first, please read
|
||||
<https://www.gnu.org/licenses/why-not-lgpl.html>.
|
||||
764
README.md
764
README.md
@ -1,27 +1,761 @@
|
||||
# SooSeF — Soo Security Fieldkit
|
||||
# FieldWitness -- FieldWitness
|
||||
|
||||
Offline-first security toolkit for journalists, NGOs, and at-risk organizations.
|
||||
**Offline-first provenance attestation with gossip federation for journalists, NGOs, and at-risk organizations.**
|
||||
|
||||
Part of the **Soo Suite**:
|
||||
- **Stegasoo** — hide encrypted messages in media (steganography)
|
||||
- **Verisoo** — prove image provenance and authenticity (attestation)
|
||||
- **SooSeF** — unified fieldkit with killswitch, dead man's switch, and key management
|
||||
<!-- badges -->
|
||||
|
||||
|
||||
|
||||
|
||||
## Status
|
||||
---
|
||||
|
||||
Pre-alpha. Phase 1 scaffolding complete.
|
||||
## What is FieldWitness?
|
||||
|
||||
## Install (development)
|
||||
FieldWitness is a field-deployable evidence integrity system. It lets journalists, human rights
|
||||
documenters, and NGOs establish cryptographic chain-of-custody over photos, documents, and
|
||||
sensor data -- in airgapped environments, across organizational boundaries, and in adversarial
|
||||
conditions where data may need to be destroyed on demand.
|
||||
|
||||
The core claim: a file attested with FieldWitness can be handed to a court or partner organization
|
||||
with proof that it has not been altered, proof of when it was captured (anchored externally
|
||||
via RFC 3161), and proof of who held it -- without requiring the verifying party to install
|
||||
FieldWitness or trust any central authority.
|
||||
|
||||
**Three-tier deployment model:**
|
||||
|
||||
```bash
|
||||
pip install -e /path/to/stegasoo[web,dct,audio,cli]
|
||||
pip install -e /path/to/verisoo[cli]
|
||||
pip install -e ".[web,cli]"
|
||||
```
|
||||
Tier 1: Field Device Tier 2: Org Server Tier 3: Federation Relay
|
||||
(Bootable USB + laptop) (Docker on mini PC / VPS) (Docker on VPS)
|
||||
|
||||
Reporter in the field Newsroom / NGO office Friendly jurisdiction
|
||||
Amnesic, LUKS-encrypted Persistent storage Attestation sync only
|
||||
Pull USB = zero trace Web UI + federation API Zero knowledge of keys
|
||||
\ | /
|
||||
\_____ sneakernet ____+____ gossip API ____/
|
||||
```
|
||||
|
||||
Stego (steganography, v4.3.0) and Attest (attestation, v0.2.0) are included as
|
||||
subpackages (`import fieldwitness.stego`, `import fieldwitness.attest`). Everything ships as one
|
||||
install: `pip install fieldwitness`.
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
soosef init # Generate identity + channel key, create ~/.soosef/
|
||||
soosef serve # Start the web UI
|
||||
pip install "fieldwitness[web,cli]"
|
||||
fieldwitness init
|
||||
fieldwitness serve
|
||||
```
|
||||
|
||||
This creates the `~/.fwmetadata/` directory structure, generates an Ed25519 identity and
|
||||
channel key, writes a default config, and starts an HTTPS web UI on
|
||||
`https://127.0.0.1:5000`.
|
||||
|
||||
---
|
||||
|
||||
## Features
|
||||
|
||||
### Attestation and Provenance (Attest)
|
||||
|
||||
- Ed25519 digital signatures for images and arbitrary files (CSV, documents, sensor data)
|
||||
- Perceptual hashing (pHash, dHash) for tamper-evident photo attestation -- identifies
|
||||
re-uploaded or re-compressed copies. SHA-256-only mode for non-image files
|
||||
- Append-only hash chain (CBOR-encoded) with Merkle tree verification -- every attestation
|
||||
is chained to all prior attestations, making retroactive tampering detectable
|
||||
- LMDB-backed attestation storage
|
||||
- Batch attestation for directories
|
||||
- **Investigation namespaces** -- tag and filter attestations by case or project
|
||||
- **Derived work lineage** -- parent-child attestation tracking for editorial workflows
|
||||
- **Chain position proof** -- verification receipts include the record's position in the
|
||||
hash chain
|
||||
|
||||
### Extract-Then-Strip EXIF Pipeline
|
||||
|
||||
Resolves the tension between protecting sources (strip everything) and proving provenance
|
||||
(preserve everything):
|
||||
|
||||
1. Extract all EXIF metadata from the original image bytes
|
||||
2. Classify fields as **evidentiary** (GPS coordinates, timestamp -- valuable for
|
||||
provenance) or **dangerous** (device serial number, firmware version -- could identify
|
||||
the source)
|
||||
3. Preserve evidentiary fields in the attestation record
|
||||
4. Strip all metadata from the stored/display copy
|
||||
|
||||
### Gossip Federation
|
||||
|
||||
- **Gossip protocol** -- nodes periodically exchange Merkle roots with peers. Divergence
|
||||
triggers a consistency proof request and incremental record fetch. No central
|
||||
coordinator, no consensus, no leader election -- just append-only logs that converge
|
||||
- **Attestation exchange** -- export signed bundles of attestation records and chain data
|
||||
for offline transfer (sneakernet) to partner organizations
|
||||
- **Delivery acknowledgments** -- when an organization imports a bundle, a
|
||||
`fieldwitness/delivery-ack-v1` chain record is signed and can be shared back, creating a
|
||||
two-way federation handshake
|
||||
- **Trust store** -- import collaborator Ed25519 public keys; only records signed by
|
||||
trusted keys are imported during federation
|
||||
- **Investigation filtering** -- export/import only records tagged with a specific
|
||||
investigation
|
||||
|
||||
### Evidence Packages
|
||||
|
||||
Self-contained ZIP bundles for handing evidence to lawyers, courts, or archives:
|
||||
|
||||
- Original images
|
||||
- Attestation records with full Ed25519 signatures
|
||||
- Chain segment with hash linkage
|
||||
- Signer's public key
|
||||
- `verify.py` -- standalone verification script that requires only Python 3.11+ and the
|
||||
`cryptography` pip package (no FieldWitness installation needed)
|
||||
- Human-readable README
|
||||
|
||||
### Cold Archive
|
||||
|
||||
Full-state export for long-term evidence preservation (10+ year horizon), aligned with
|
||||
OAIS (ISO 14721):
|
||||
|
||||
- Raw chain binary and state checkpoint
|
||||
- Attestation log and LMDB index
|
||||
- External timestamp anchors
|
||||
- Public key and trusted collaborator keys
|
||||
- Encrypted key bundle (optional, password-protected)
|
||||
- `ALGORITHMS.txt` documenting every cryptographic algorithm, parameter, and format used
|
||||
- `verify.py` standalone verifier
|
||||
- `manifest.json` with SHA-256 integrity hashes of key files
|
||||
|
||||
### External Timestamp Anchoring
|
||||
|
||||
Two mechanisms to prove the chain head existed before a given time:
|
||||
|
||||
- **RFC 3161 TSA** -- automated submission to any RFC 3161 Timestamping Authority (e.g.,
|
||||
FreeTSA). The signed timestamp token is saved alongside the chain
|
||||
- **Manual anchors** -- export the chain head hash as a compact string for manual
|
||||
submission to any external witness (blockchain transaction, newspaper classified, email
|
||||
to a TSA)
|
||||
|
||||
A single anchor for the chain head implicitly timestamps every record that preceded it,
|
||||
because the chain is append-only with hash linkage.
|
||||
|
||||
### Selective Disclosure
|
||||
|
||||
Produce verifiable proofs for specific chain records while keeping others redacted.
|
||||
Selected records are included in full; non-selected records appear only as hashes. A third
|
||||
party can verify that the disclosed records are part of an unbroken chain without seeing
|
||||
the contents of other records. Designed for legal discovery, court orders, and FOIA
|
||||
responses.
|
||||
|
||||
### Field Security (Fieldkit)
|
||||
|
||||
- **Killswitch** -- emergency destruction of all data under `~/.fwmetadata/`, ordered by
|
||||
sensitivity (keys first, then data, then logs). Includes:
|
||||
- **Deep forensic scrub** -- removes `__pycache__`, `.pyc`, pip `dist-info`, pip
|
||||
download cache, and scrubs shell history entries containing "fieldwitness"
|
||||
- **Self-uninstall** -- runs `pip uninstall -y fieldwitness` as the final step
|
||||
- **System log clearing** -- best-effort journald vacuum on Linux
|
||||
- **Dead man's switch** -- automated purge if check-in is missed, with a configurable
|
||||
grace period. During the grace period, a **webhook warning** is sent (POST to a
|
||||
configured URL) and a local warning file is written before the killswitch fires
|
||||
- **Tamper detection** -- file integrity monitoring with baseline snapshots
|
||||
- **USB whitelist** -- block or alert on unauthorized USB devices (Linux/pyudev)
|
||||
- **Geofence** -- GPS boundary enforcement with configurable radius. Supports live GPS via
|
||||
**gpsd** (`get_current_location()` connects to `127.0.0.1:2947`)
|
||||
- **Hardware killswitch** -- GPIO pin monitoring for Raspberry Pi physical button
|
||||
(configurable pin and hold duration)
|
||||
|
||||
### Source Drop Box
|
||||
|
||||
SecureDrop-style anonymous intake built into the FieldWitness web UI:
|
||||
|
||||
- Admin creates a time-limited upload token with a configurable file limit
|
||||
- Source opens the token URL (no account or FieldWitness branding -- source safety)
|
||||
- **Client-side SHA-256** via SubtleCrypto runs in the browser before upload, so the
|
||||
source can independently verify what they submitted
|
||||
- Files are run through the extract-then-strip EXIF pipeline and auto-attested on receipt
|
||||
- Source receives HMAC-derived receipt codes that prove delivery
|
||||
- Tokens and receipts are stored in SQLite; tokens auto-expire
|
||||
|
||||
### Key Rotation and Recovery
|
||||
|
||||
- **Key rotation** -- both identity (Ed25519) and channel (AES) keys can be rotated. The
|
||||
chain records the rotation as a `fieldwitness/key-rotation-v1` record signed by the OLD key,
|
||||
creating a cryptographic trust chain
|
||||
- **Identity recovery** -- after device loss, a new key can be introduced via a
|
||||
`fieldwitness/key-recovery-v1` chain record. The record carries the old fingerprint and
|
||||
optional cosigner fingerprints for audit
|
||||
- **Channel key only export** -- share just the channel key (not identity keys) with
|
||||
collaborators via encrypted file or QR code (`fieldwitness-channel:` URI scheme)
|
||||
- **Backup tracking** -- records when the last backup was taken and warns when overdue
|
||||
|
||||
### Cover / Duress Mode
|
||||
|
||||
- **Configurable certificate CN** -- set `cover_name` in config to replace "FieldWitness Local"
|
||||
in the self-signed TLS certificate
|
||||
- **Portable data directory** -- set `FIELDWITNESS_DATA_DIR` to relocate all state to an
|
||||
arbitrary path (e.g., an innocuously named directory on a USB stick). All paths resolve
|
||||
lazily from `BASE_DIR`, so runtime overrides propagate correctly
|
||||
|
||||
### Additional Tools: Steganography (Stego)
|
||||
|
||||
For situations requiring covert channels -- hiding communications or small payloads inside
|
||||
ordinary media files:
|
||||
|
||||
- **LSB encoding** -- bit-level message hiding in PNG images
|
||||
- **DCT encoding** -- frequency-domain hiding in JPEG images (requires `stego-dct` extra)
|
||||
- **Audio steganography** -- hide data in WAV/FLAC audio (requires `stego-audio` extra)
|
||||
- **Video steganography** -- frame-level encoding
|
||||
- **Transport-aware encoding** -- `--transport whatsapp|signal|telegram|discord|email|direct`
|
||||
auto-selects the right encoding mode and carrier resolution for lossy messaging
|
||||
platforms. WhatsApp/Signal/Telegram force DCT/JPEG mode and pre-resize the carrier to
|
||||
survive recompression
|
||||
- **Carrier reuse tracking** -- warns when a carrier image has been used before, since
|
||||
comparing two versions of the same carrier trivially reveals steganographic modification
|
||||
- AES-256-GCM encryption with Argon2id key derivation
|
||||
- EXIF stripping on encode to prevent metadata leakage
|
||||
- Compression support (zstandard, optional LZ4)
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
### Basic install (core library only)
|
||||
|
||||
```bash
|
||||
pip install fieldwitness
|
||||
```
|
||||
|
||||
### With extras
|
||||
|
||||
```bash
|
||||
pip install "fieldwitness[web,cli]" # Web UI + CLI (most common)
|
||||
pip install "fieldwitness[all]" # Everything except dev tools
|
||||
pip install "fieldwitness[dev]" # All + pytest, black, ruff, mypy
|
||||
```
|
||||
|
||||
### Available extras
|
||||
|
||||
| Extra | What it adds |
|
||||
|---|---|
|
||||
| `stego-dct` | DCT steganography (numpy, scipy, jpeglib, reedsolo) |
|
||||
| `stego-audio` | Audio steganography (pydub, soundfile, reedsolo) |
|
||||
| `stego-compression` | LZ4 compression support |
|
||||
| `attest` | Attestation features (imagehash, lmdb, exifread) |
|
||||
| `cli` | Click CLI with rich output, QR code support, piexif |
|
||||
| `web` | Flask web UI with Waitress/Gunicorn, pyzbar QR scanning, includes attest + stego-dct |
|
||||
| `api` | FastAPI REST API with uvicorn, includes stego-dct |
|
||||
| `fieldkit` | Tamper monitoring (watchdog) and USB whitelist (pyudev) |
|
||||
| `federation` | Peer-to-peer attestation federation (aiohttp) |
|
||||
| `rpi` | Raspberry Pi deployment (web + cli + fieldkit + gpiozero) |
|
||||
| `all` | All of the above |
|
||||
| `dev` | All + pytest, pytest-cov, black, ruff, mypy |
|
||||
|
||||
### Airgapped install
|
||||
|
||||
Bundle wheels on a networked machine, then install offline:
|
||||
|
||||
```bash
|
||||
# On networked machine
|
||||
pip download "fieldwitness[web,cli]" -d ./wheels
|
||||
|
||||
# Transfer ./wheels to target via USB
|
||||
# On airgapped machine
|
||||
pip install --no-index --find-links=./wheels "fieldwitness[web,cli]"
|
||||
fieldwitness init
|
||||
fieldwitness serve --host 0.0.0.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deployment
|
||||
|
||||
FieldWitness uses a three-tier deployment model designed for field journalism, organizational
|
||||
evidence management, and cross-organization federation.
|
||||
|
||||
**Tier 1 -- Field Device.** A bootable Debian Live USB stick. Boots into a minimal desktop
|
||||
with Firefox pointed at the local FieldWitness web UI. LUKS-encrypted persistent partition. Pull
|
||||
the USB and the host machine retains nothing.
|
||||
|
||||
**Tier 2 -- Org Server.** A Docker deployment on a mini PC or trusted VPS. Runs the full
|
||||
web UI (port 5000) and federation API (port 8000). Manages keys, attestations, and
|
||||
federation sync.
|
||||
|
||||
**Tier 3 -- Federation Relay.** A lightweight Docker container in a jurisdiction with
|
||||
strong press protections. Relays attestation records between organizations. Stores only
|
||||
hashes and signatures -- never keys, plaintext, or original media.
|
||||
|
||||
### Quick deploy
|
||||
|
||||
```bash
|
||||
# Tier 1: Build USB image
|
||||
cd deploy/live-usb && sudo ./build.sh
|
||||
|
||||
# Tier 2: Docker org server
|
||||
cd deploy/docker && docker compose up server -d
|
||||
|
||||
# Tier 3: Docker federation relay
|
||||
cd deploy/docker && docker compose up relay -d
|
||||
```
|
||||
|
||||
### Threat level configuration presets
|
||||
|
||||
FieldWitness ships four configuration presets at `deploy/config-presets/`:
|
||||
|
||||
| Preset | Session | Killswitch | Dead Man | Cover Name |
|
||||
|---|---|---|---|---|
|
||||
| `low-threat.json` | 30 min | Off | Off | None |
|
||||
| `medium-threat.json` | 15 min | On | 48h / 4h grace | "Office Document Manager" |
|
||||
| `high-threat.json` | 5 min | On | 12h / 1h grace | "Local Inventory Tracker" |
|
||||
| `critical-threat.json` | 3 min | On | 6h / 1h grace | "System Statistics" |
|
||||
|
||||
```bash
|
||||
cp deploy/config-presets/high-threat.json ~/.fwmetadata/config.json
|
||||
```
|
||||
|
||||
See [docs/deployment.md](docs/deployment.md) for the full deployment guide including
|
||||
security hardening, Kubernetes manifests, systemd services, and operational security notes.
|
||||
|
||||
---
|
||||
|
||||
## CLI Reference
|
||||
|
||||
All commands accept `--data-dir PATH` to override the default `~/.fwmetadata` directory,
|
||||
and `--json` for machine-readable output.
|
||||
|
||||
```
|
||||
fieldwitness [--data-dir PATH] [--json] COMMAND
|
||||
```
|
||||
|
||||
### Core commands
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `fieldwitness init` | Create directory structure, generate identity + channel key, write default config |
|
||||
| `fieldwitness serve` | Start the web UI (default: `https://127.0.0.1:5000`) |
|
||||
| `fieldwitness status` | Show instance status: identity, keys, chain, fieldkit, config |
|
||||
|
||||
### `fieldwitness serve` options
|
||||
|
||||
| Option | Default | Description |
|
||||
|---|---|---|
|
||||
| `--host` | `127.0.0.1` | Bind address |
|
||||
| `--port` | `5000` | Bind port |
|
||||
| `--no-https` | off | Disable HTTPS (use HTTP) |
|
||||
| `--debug` | off | Use Flask dev server instead of Waitress |
|
||||
| `--workers` | `4` | Number of Waitress/Gunicorn worker threads |
|
||||
|
||||
### Attestation commands (`fieldwitness attest`)
|
||||
|
||||
```bash
|
||||
# Attest an image (sign with Ed25519 identity)
|
||||
fieldwitness attest IMAGE photo.jpg
|
||||
fieldwitness attest IMAGE photo.jpg --caption "Field report" --location "Istanbul"
|
||||
|
||||
# Batch attest a directory
|
||||
fieldwitness attest batch ./photos/ --caption "Field report"
|
||||
|
||||
# Verify an image against the attestation log
|
||||
fieldwitness attest verify photo.jpg
|
||||
|
||||
# View attestation log
|
||||
fieldwitness attest log --limit 20
|
||||
```
|
||||
|
||||
### Chain commands (`fieldwitness chain`)
|
||||
|
||||
```bash
|
||||
fieldwitness chain status # Show chain head, length, integrity
|
||||
fieldwitness chain verify # Verify entire chain integrity (hashes + signatures)
|
||||
fieldwitness chain show INDEX # Show a specific chain record
|
||||
fieldwitness chain log --count 20 # Show recent chain entries
|
||||
fieldwitness chain backfill # Backfill existing attestations into chain
|
||||
|
||||
# Evidence export
|
||||
fieldwitness chain export --start 0 --end 100 -o chain.zip
|
||||
|
||||
# Selective disclosure (for legal discovery / court orders)
|
||||
fieldwitness chain disclose -i 5,12,47 -o disclosure.json
|
||||
|
||||
# External timestamp anchoring
|
||||
fieldwitness chain anchor # Manual anchor (prints hash for tweet/email/blockchain)
|
||||
fieldwitness chain anchor --tsa https://freetsa.org/tsr # RFC 3161 automated anchor
|
||||
```
|
||||
|
||||
### Fieldkit commands (`fieldwitness fieldkit`)
|
||||
|
||||
```bash
|
||||
fieldwitness fieldkit status # Show fieldkit state
|
||||
fieldwitness fieldkit checkin # Reset dead man's switch timer
|
||||
fieldwitness fieldkit check-deadman # Check if deadman timer has expired
|
||||
fieldwitness fieldkit purge --confirm # Activate killswitch (destroys all data)
|
||||
fieldwitness fieldkit geofence set --lat 48.8566 --lon 2.3522 --radius 1000
|
||||
fieldwitness fieldkit geofence check --lat 48.8600 --lon 2.3500
|
||||
fieldwitness fieldkit geofence clear
|
||||
fieldwitness fieldkit usb snapshot # Snapshot current USB devices as whitelist
|
||||
fieldwitness fieldkit usb check # Check for unauthorized USB devices
|
||||
```
|
||||
|
||||
### Key management commands (`fieldwitness keys`)
|
||||
|
||||
```bash
|
||||
fieldwitness keys show # Display current key info
|
||||
fieldwitness keys export -o backup.enc # Export encrypted key bundle
|
||||
fieldwitness keys import -b backup.enc # Import key bundle
|
||||
fieldwitness keys rotate-identity # Generate new Ed25519 identity (records rotation in chain)
|
||||
fieldwitness keys rotate-channel # Generate new channel key
|
||||
```
|
||||
|
||||
### Steganography commands (`fieldwitness stego`)
|
||||
|
||||
Stego uses multi-factor authentication: a **reference photo** (shared image both
|
||||
parties have), a **passphrase** (4+ words), and a **PIN** (6-9 digits). All three are
|
||||
required to encode or decode. The passphrase and PIN are prompted interactively
|
||||
(hidden input) if not provided via options.
|
||||
|
||||
```bash
|
||||
# Encode a text message into an image
|
||||
# CARRIER is the image to hide data in, -r is the shared reference photo
|
||||
fieldwitness stego encode cover.png -r shared_photo.jpg -m "Secret message"
|
||||
# Passphrase: **** (prompted, hidden)
|
||||
# PIN: **** (prompted, hidden)
|
||||
# -> writes encoded PNG to current directory
|
||||
|
||||
# Encode with explicit output path
|
||||
fieldwitness stego encode cover.png -r shared_photo.jpg -m "Secret" -o stego_output.png
|
||||
|
||||
# Encode a file instead of text
|
||||
fieldwitness stego encode cover.png -r shared_photo.jpg -f document.pdf
|
||||
|
||||
# Transport-aware encoding (auto-selects DCT/JPEG and resizes for the platform)
|
||||
fieldwitness stego encode cover.jpg -r shared.jpg -m "Secret" --transport whatsapp
|
||||
fieldwitness stego encode cover.jpg -r shared.jpg -m "Secret" --transport signal
|
||||
fieldwitness stego encode cover.jpg -r shared.jpg -m "Secret" --transport telegram
|
||||
fieldwitness stego encode cover.jpg -r shared.jpg -m "Secret" --transport email
|
||||
fieldwitness stego encode cover.jpg -r shared.jpg -m "Secret" --transport direct
|
||||
|
||||
# Dry run -- check capacity without encoding
|
||||
fieldwitness stego encode cover.png -r shared_photo.jpg -m "Secret" --dry-run
|
||||
|
||||
# Decode a message from a stego image (same reference + passphrase + PIN)
|
||||
fieldwitness stego decode stego_output.png -r shared_photo.jpg
|
||||
# Passphrase: ****
|
||||
# PIN: ****
|
||||
# -> prints decoded message or saves decoded file
|
||||
|
||||
# Decode and save file payload to specific path
|
||||
fieldwitness stego decode stego_output.png -r shared_photo.jpg -o recovered.pdf
|
||||
|
||||
# DCT mode for JPEG (survives social media compression)
|
||||
fieldwitness stego encode cover.jpg -r shared_photo.jpg -m "Secret" --platform telegram
|
||||
|
||||
# Audio steganography
|
||||
fieldwitness stego audio-encode audio.wav -r shared_photo.jpg -m "Hidden in audio"
|
||||
fieldwitness stego audio-decode stego.wav -r shared_photo.jpg
|
||||
|
||||
# Generate credentials
|
||||
fieldwitness stego generate # Generate passphrase + PIN
|
||||
fieldwitness stego generate --pin-length 8 # Longer PIN
|
||||
|
||||
# Channel key management
|
||||
fieldwitness stego channel status # Show current channel key
|
||||
fieldwitness stego channel generate # Generate new channel key
|
||||
|
||||
# Image info and capacity
|
||||
fieldwitness stego info cover.png # Image details + LSB/DCT capacity
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Web UI
|
||||
|
||||
Start with `fieldwitness serve`. The web UI provides authenticated access to all features
|
||||
through Flask blueprints. Served by **Waitress** (production WSGI server) by default.
|
||||
|
||||
### Routes
|
||||
|
||||
| Blueprint | Routes | Description |
|
||||
|---|---|---|
|
||||
| attest | `/attest`, `/verify` | Attestation signing and verification |
|
||||
| federation | `/federation/*` | Federation peer dashboard, peer add/remove |
|
||||
| fieldkit | `/fieldkit/*` | Killswitch, dead man's switch, status dashboard |
|
||||
| keys | `/keys/*` | Key management, rotation, export/import |
|
||||
| admin | `/admin/*` | User management (multi-user auth via SQLite) |
|
||||
| dropbox | `/dropbox/admin`, `/dropbox/upload/<token>` | Source drop box: token creation (admin), anonymous upload (source), receipt verification |
|
||||
| stego | `/encode`, `/decode`, `/generate` | Steganography operations |
|
||||
| health | `/health` | Capability reporting endpoint (see API section) |
|
||||
|
||||
<!-- TODO: screenshots -->
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
FieldWitness loads configuration from `~/.fwmetadata/config.json`. All fields have sensible defaults.
|
||||
`fieldwitness init` writes the default config file.
|
||||
|
||||
### Config fields
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|---|---|---|---|
|
||||
| `host` | string | `127.0.0.1` | Web UI bind address |
|
||||
| `port` | int | `5000` | Web UI bind port |
|
||||
| `https_enabled` | bool | `true` | Enable HTTPS with self-signed cert |
|
||||
| `auth_enabled` | bool | `true` | Require login for web UI |
|
||||
| `max_upload_mb` | int | `50` | Maximum upload size in MB |
|
||||
| `session_timeout_minutes` | int | `15` | Session expiry |
|
||||
| `login_lockout_attempts` | int | `5` | Failed logins before lockout |
|
||||
| `login_lockout_minutes` | int | `15` | Lockout duration |
|
||||
| `default_embed_mode` | string | `auto` | Stego encoding mode |
|
||||
| `killswitch_enabled` | bool | `false` | Enable killswitch functionality |
|
||||
| `deadman_enabled` | bool | `false` | Enable dead man's switch |
|
||||
| `deadman_interval_hours` | int | `24` | Check-in interval |
|
||||
| `deadman_grace_hours` | int | `2` | Grace period after missed check-in |
|
||||
| `deadman_warning_webhook` | string | `""` | URL to POST warning before auto-purge |
|
||||
| `usb_monitoring_enabled` | bool | `false` | Enable USB device whitelist enforcement |
|
||||
| `tamper_monitoring_enabled` | bool | `false` | Enable file integrity monitoring |
|
||||
| `chain_enabled` | bool | `true` | Enable attestation hash chain |
|
||||
| `chain_auto_wrap` | bool | `true` | Auto-wrap attestations in chain records |
|
||||
| `backup_reminder_days` | int | `7` | Days before backup reminder |
|
||||
| `cover_name` | string | `""` | If set, used for SSL cert CN instead of "FieldWitness Local" (cover/duress mode) |
|
||||
| `gpio_killswitch_pin` | int | `17` | Raspberry Pi GPIO pin for hardware killswitch |
|
||||
| `gpio_killswitch_hold_seconds` | float | `5.0` | Hold duration to trigger hardware killswitch |
|
||||
|
||||
### Environment variables
|
||||
|
||||
| Variable | Description |
|
||||
|---|---|
|
||||
| `FIELDWITNESS_DATA_DIR` | Override the data directory (default: `~/.fwmetadata`). Enables portable USB mode and cover/duress directory naming |
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
### Source layout
|
||||
|
||||
```
|
||||
src/fieldwitness/
|
||||
__init__.py Package init, __version__
|
||||
cli.py Click CLI (entry point: fieldwitness)
|
||||
paths.py All path constants (lazy resolution from BASE_DIR)
|
||||
config.py Unified config loader (dataclass + JSON)
|
||||
exceptions.py FieldWitnessError base exception
|
||||
metadata.py Extract-then-strip EXIF pipeline
|
||||
evidence.py Self-contained evidence package export
|
||||
archive.py Cold archive for long-term preservation (OAIS-aligned)
|
||||
attest/ Attestation engine (subpackage)
|
||||
models.py ImageHashes (images + arbitrary files), AttestationRecord
|
||||
keystore/
|
||||
manager.py Key material management (channel + identity + trust store + backup)
|
||||
models.py KeyBundle, IdentityBundle dataclasses
|
||||
export.py Full bundle export, channel-key-only export, QR code sharing
|
||||
federation/
|
||||
chain.py Append-only hash chain (key rotation, recovery, delivery ack, selective disclosure)
|
||||
anchors.py RFC 3161 timestamps + manual chain anchors
|
||||
exchange.py Cross-org attestation bundle export/import
|
||||
fieldkit/
|
||||
killswitch.py Emergency data destruction (deep forensic scrub, self-uninstall)
|
||||
deadman.py Dead man's switch (webhook warnings)
|
||||
tamper.py File integrity monitoring
|
||||
usb_monitor.py USB device whitelist (Linux/pyudev)
|
||||
geofence.py GPS boundary enforcement (gpsd integration)
|
||||
stego/ Steganography engine (subpackage)
|
||||
encode.py Transport-aware encoding (--transport flag)
|
||||
carrier_tracker.py Carrier reuse tracking and warnings
|
||||
|
||||
frontends/web/
|
||||
app.py Flask app factory (create_app())
|
||||
auth.py SQLite3 multi-user auth
|
||||
temp_storage.py File-based temp storage with expiry
|
||||
subprocess_stego.py Crash-safe subprocess isolation
|
||||
ssl_utils.py Self-signed HTTPS cert generation
|
||||
blueprints/
|
||||
attest.py /attest, /verify
|
||||
federation.py /federation/* (peer dashboard)
|
||||
fieldkit.py /fieldkit/*
|
||||
keys.py /keys/*
|
||||
admin.py /admin/*
|
||||
dropbox.py /dropbox/* (source drop box)
|
||||
stego.py /encode, /decode, /generate
|
||||
|
||||
deploy/ Deployment artifacts
|
||||
docker/ Dockerfile (multi-stage: builder, relay, server) + compose
|
||||
kubernetes/ Namespace, server, and relay deployments
|
||||
live-usb/ Debian Live USB build scripts (Tier 1)
|
||||
config-presets/ Threat level presets (low/medium/high/critical)
|
||||
```
|
||||
|
||||
### Data directory (`~/.fwmetadata/`)
|
||||
|
||||
```
|
||||
~/.fwmetadata/
|
||||
config.json Unified configuration
|
||||
audit.jsonl Append-only audit trail
|
||||
carrier_history.json Carrier reuse tracking database
|
||||
identity/ Ed25519 keypair (private.pem, public.pem, identity.meta.json)
|
||||
stego/ Channel key (channel.key)
|
||||
attestations/ Attest attestation store (log.bin, index/, peers.json)
|
||||
chain/ Hash chain (chain.bin, state.cbor, anchors/)
|
||||
auth/ Web UI auth database (fieldwitness.db, dropbox.db)
|
||||
certs/ Self-signed TLS certificates
|
||||
fieldkit/ Fieldkit state (deadman.json, tamper/, usb/, geofence.json)
|
||||
temp/ Ephemeral file storage (dropbox uploads)
|
||||
instance/ Flask instance (sessions, secret key)
|
||||
trusted_keys/ Collaborator Ed25519 public keys (trust store)
|
||||
```
|
||||
|
||||
Sensitive directories (`identity/`, `auth/`, `certs/`, and the root) are created with
|
||||
`0700` permissions.
|
||||
|
||||
---
|
||||
|
||||
## Security Model
|
||||
|
||||
**Two key domains, never merged.** Stego uses AES-256-GCM with keys derived via
|
||||
Argon2id from user-supplied factors. Attest uses Ed25519 for signing. These serve
|
||||
different security purposes and are kept strictly separate.
|
||||
|
||||
**Killswitch priority.** The killswitch destroys all data under `~/.fwmetadata/`, including
|
||||
the audit log. This is intentional -- in a field compromise scenario, data destruction
|
||||
takes precedence over audit trail preservation. The deep forensic scrub extends beyond
|
||||
the data directory to remove Python bytecache, pip metadata, pip download cache, shell
|
||||
history entries, and the fieldwitness package itself.
|
||||
|
||||
**Offline-first.** All static assets are vendored (no CDN calls). Pip wheels can be
|
||||
bundled for fully airgapped installation. No network access is required for any core
|
||||
functionality. RFC 3161 timestamping and webhook warnings are optional features that
|
||||
gracefully degrade when offline.
|
||||
|
||||
**Web UI hardening:**
|
||||
- CSRF protection via Flask-WTF
|
||||
- Session timeout (default: 15 minutes)
|
||||
- Login rate limiting with lockout (5 attempts, 15-minute lockout)
|
||||
- HTTPS by default with auto-generated self-signed certificates
|
||||
- EXIF stripping on steganographic encode to prevent metadata leakage
|
||||
- Dead man's switch webhook SSRF protection (blocks private/internal targets)
|
||||
|
||||
**Subprocess isolation.** Steganographic operations run in a subprocess boundary
|
||||
(`subprocess_stego.py`) to contain crashes and prevent memory corruption from affecting
|
||||
the main web server process.
|
||||
|
||||
**Chain integrity.** The append-only hash chain uses Ed25519 signatures and SHA-256
|
||||
linkage. Key rotation records create a verifiable trust chain; identity recovery records
|
||||
are auditable. Selective disclosure uses Merkle-style proofs so third parties can verify
|
||||
specific records without accessing the full chain.
|
||||
|
||||
---
|
||||
|
||||
## Cross-Domain Applications
|
||||
|
||||
While FieldWitness was designed for journalist and NGO field security, the attestation chain,
|
||||
federation, and evidence packaging capabilities apply to a range of domains:
|
||||
|
||||
- **Human rights documentation** -- field workers attest photos and videos of incidents
|
||||
with GPS and timestamps, federate evidence to international partners, and produce
|
||||
court-ready evidence packages
|
||||
- **Research integrity** -- researchers attest datasets (CSV, sensor readings) at
|
||||
collection time, creating a tamper-evident chain of custody. `ImageHashes.from_file()`
|
||||
supports arbitrary file types via SHA-256
|
||||
- **Election monitoring** -- observers attest ballot images and tally sheets with location
|
||||
metadata, anchor the chain to an RFC 3161 TSA for independent time proof, and use
|
||||
selective disclosure for audit requests
|
||||
- **Supply chain verification** -- attest inspection photos, sensor data, and certificates
|
||||
of origin at each stage. Federation enables multi-party chains across organizations
|
||||
- **Art authentication** -- attest high-resolution photographs of artworks with device and
|
||||
location metadata, creating provenance records that survive format conversion via
|
||||
perceptual hashing
|
||||
- **Corporate whistleblowing** -- the source drop box accepts anonymous uploads with
|
||||
client-side hashing. Cover mode (`cover_name`, `FIELDWITNESS_DATA_DIR`) disguises the
|
||||
installation. The killswitch provides emergency destruction if the instance is
|
||||
compromised
|
||||
- **Environmental monitoring** -- attest sensor data, satellite imagery, and field
|
||||
photographs. Cold archives with `ALGORITHMS.txt` ensure evidence remains verifiable
|
||||
decades later
|
||||
|
||||
---
|
||||
|
||||
## API
|
||||
|
||||
### `/health` endpoint
|
||||
|
||||
The web UI exposes a `/health` endpoint that reports installed capabilities:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"version": "0.3.0",
|
||||
"capabilities": ["stego-lsb", "stego-dct", "attest", "fieldkit", "chain"]
|
||||
}
|
||||
```
|
||||
|
||||
Useful for monitoring and for clients to discover which extras are installed.
|
||||
|
||||
### FastAPI (optional)
|
||||
|
||||
Install the `api` extra for a standalone FastAPI REST interface:
|
||||
|
||||
```bash
|
||||
pip install "fieldwitness[api]"
|
||||
```
|
||||
|
||||
This provides `fieldwitness.api` with a FastAPI application served by uvicorn, suitable for
|
||||
programmatic integration.
|
||||
|
||||
---
|
||||
|
||||
## Development
|
||||
|
||||
### Setup
|
||||
|
||||
```bash
|
||||
git clone https://github.com/alee/fieldwitness.git
|
||||
cd fieldwitness
|
||||
pip install -e ".[dev]"
|
||||
```
|
||||
|
||||
### Commands
|
||||
|
||||
```bash
|
||||
pytest # Run tests with coverage
|
||||
black src/ tests/ frontends/ # Format (100-char line length)
|
||||
ruff check src/ tests/ frontends/ --fix # Lint
|
||||
mypy src/ # Type check
|
||||
```
|
||||
|
||||
### Code style
|
||||
|
||||
- Black with 100-character line length
|
||||
- Ruff with E, F, I, N, W, UP rule sets
|
||||
- mypy strict mode with missing imports ignored
|
||||
- Imperative commit messages (e.g., "Add killswitch purge confirmation")
|
||||
|
||||
### Python support
|
||||
|
||||
Python 3.11, 3.12, 3.13, and 3.14.
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
| Document | Audience | Description |
|
||||
|---|---|---|
|
||||
| [docs/deployment.md](docs/deployment.md) | Field deployers, IT staff | Three-tier deployment guide, security hardening, troubleshooting |
|
||||
| [docs/federation.md](docs/federation.md) | System administrators | Gossip protocol, peer setup, offline bundles, federation API |
|
||||
| [docs/evidence-guide.md](docs/evidence-guide.md) | Investigators, legal teams | Evidence packages, cold archives, selective disclosure, anchoring |
|
||||
| [docs/source-dropbox.md](docs/source-dropbox.md) | Administrators | Source drop box setup, EXIF pipeline, receipt codes |
|
||||
| [docs/security/threat-model.md](docs/security/threat-model.md) | Security reviewers, contributors | Threat model, adversary model, trust boundaries, cryptographic primitives |
|
||||
| [docs/training/reporter-quickstart.md](docs/training/reporter-quickstart.md) | Field reporters | One-page quick-start card for Tier 1 USB users |
|
||||
| [docs/training/emergency-card.md](docs/training/emergency-card.md) | All users | Laminated wallet card: emergency destruction, dead man's switch |
|
||||
| [docs/training/admin-reference.md](docs/training/admin-reference.md) | Administrators | CLI cheat sheet, hardening checklist, troubleshooting |
|
||||
|
||||
Architecture documents (design-level, for contributors):
|
||||
|
||||
| Document | Description |
|
||||
|---|---|
|
||||
| [docs/architecture/federation.md](docs/architecture/federation.md) | System architecture overview, threat model, layer design |
|
||||
| [docs/architecture/chain-format.md](docs/architecture/chain-format.md) | Chain record spec (CBOR, entropy witnesses) |
|
||||
| [docs/architecture/export-bundle.md](docs/architecture/export-bundle.md) | Export bundle spec (binary format, envelope encryption) |
|
||||
| [docs/architecture/federation-protocol.md](docs/architecture/federation-protocol.md) | Federation server protocol (CT-inspired, gossip) |
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
GPL-3.0 License. See [LICENSE](LICENSE) for details.
|
||||
|
||||
46
deploy/config-presets/README.md
Normal file
46
deploy/config-presets/README.md
Normal file
@ -0,0 +1,46 @@
|
||||
# FieldWitness Threat Level Configuration Presets
|
||||
|
||||
Select a preset based on your operational environment. Copy the appropriate
|
||||
JSON file to `~/.fwmetadata/config.json` (or let the setup wizard choose one).
|
||||
|
||||
## Presets
|
||||
|
||||
### low-threat.json — Press Freedom Country
|
||||
Nordics, New Zealand, Canada. Risk is accidental data loss, not adversarial seizure.
|
||||
- No killswitch or dead man's switch
|
||||
- Relaxed session timeouts (30 min)
|
||||
- Backup reminders every 14 days
|
||||
- Chain enabled for provenance integrity
|
||||
|
||||
### medium-threat.json — Restricted Press
|
||||
Turkey, Hungary, India. Risk of legal pressure, device seizure at borders.
|
||||
- Killswitch available, dead man's switch at 48h/4h grace
|
||||
- USB monitoring enabled
|
||||
- Cover name: "Office Document Manager"
|
||||
- Backup reminders every 7 days
|
||||
|
||||
### high-threat.json — Active Conflict Zone
|
||||
Syria, Myanmar, Ethiopia, Iran. Risk of raids, equipment seizure, physical coercion.
|
||||
- 5-minute session timeout
|
||||
- Dead man's switch at 12h/1h grace
|
||||
- Tamper monitoring enabled
|
||||
- Cover name: "Local Inventory Tracker"
|
||||
- Daily backup reminders
|
||||
|
||||
### critical-threat.json — Targeted Surveillance
|
||||
Specific journalist or org targeted by state actor (Pegasus-level).
|
||||
- Web UI bound to 127.0.0.1 only (access via SSH tunnel)
|
||||
- 3-minute session timeout
|
||||
- Dead man's switch at 6h/1h grace
|
||||
- Cover name: "System Statistics"
|
||||
- All monitoring enabled
|
||||
- Consider: full-disk encryption, remove SSH after setup, Tor hidden service
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Copy preset to config location
|
||||
cp deploy/config-presets/high-threat.json ~/.fwmetadata/config.json
|
||||
|
||||
# Or via CLI (future: fieldwitness init --threat-level high)
|
||||
```
|
||||
20
deploy/config-presets/critical-threat.json
Normal file
20
deploy/config-presets/critical-threat.json
Normal file
@ -0,0 +1,20 @@
|
||||
{
|
||||
"host": "127.0.0.1",
|
||||
"port": 5000,
|
||||
"https_enabled": true,
|
||||
"auth_enabled": true,
|
||||
"session_timeout_minutes": 3,
|
||||
"login_lockout_attempts": 3,
|
||||
"login_lockout_minutes": 60,
|
||||
"killswitch_enabled": true,
|
||||
"deadman_enabled": true,
|
||||
"deadman_interval_hours": 6,
|
||||
"deadman_grace_hours": 1,
|
||||
"deadman_warning_webhook": "",
|
||||
"usb_monitoring_enabled": true,
|
||||
"tamper_monitoring_enabled": true,
|
||||
"chain_enabled": true,
|
||||
"chain_auto_wrap": true,
|
||||
"backup_reminder_days": 1,
|
||||
"cover_name": "System Statistics"
|
||||
}
|
||||
20
deploy/config-presets/high-threat.json
Normal file
20
deploy/config-presets/high-threat.json
Normal file
@ -0,0 +1,20 @@
|
||||
{
|
||||
"host": "0.0.0.0",
|
||||
"port": 5000,
|
||||
"https_enabled": true,
|
||||
"auth_enabled": true,
|
||||
"session_timeout_minutes": 5,
|
||||
"login_lockout_attempts": 3,
|
||||
"login_lockout_minutes": 30,
|
||||
"killswitch_enabled": true,
|
||||
"deadman_enabled": true,
|
||||
"deadman_interval_hours": 12,
|
||||
"deadman_grace_hours": 1,
|
||||
"deadman_warning_webhook": "",
|
||||
"usb_monitoring_enabled": true,
|
||||
"tamper_monitoring_enabled": true,
|
||||
"chain_enabled": true,
|
||||
"chain_auto_wrap": true,
|
||||
"backup_reminder_days": 1,
|
||||
"cover_name": "Local Inventory Tracker"
|
||||
}
|
||||
20
deploy/config-presets/low-threat.json
Normal file
20
deploy/config-presets/low-threat.json
Normal file
@ -0,0 +1,20 @@
|
||||
{
|
||||
"host": "0.0.0.0",
|
||||
"port": 5000,
|
||||
"https_enabled": true,
|
||||
"auth_enabled": true,
|
||||
"session_timeout_minutes": 30,
|
||||
"login_lockout_attempts": 10,
|
||||
"login_lockout_minutes": 5,
|
||||
"killswitch_enabled": false,
|
||||
"deadman_enabled": false,
|
||||
"deadman_interval_hours": 24,
|
||||
"deadman_grace_hours": 2,
|
||||
"deadman_warning_webhook": "",
|
||||
"usb_monitoring_enabled": false,
|
||||
"tamper_monitoring_enabled": false,
|
||||
"chain_enabled": true,
|
||||
"chain_auto_wrap": true,
|
||||
"backup_reminder_days": 14,
|
||||
"cover_name": ""
|
||||
}
|
||||
20
deploy/config-presets/medium-threat.json
Normal file
20
deploy/config-presets/medium-threat.json
Normal file
@ -0,0 +1,20 @@
|
||||
{
|
||||
"host": "0.0.0.0",
|
||||
"port": 5000,
|
||||
"https_enabled": true,
|
||||
"auth_enabled": true,
|
||||
"session_timeout_minutes": 15,
|
||||
"login_lockout_attempts": 5,
|
||||
"login_lockout_minutes": 15,
|
||||
"killswitch_enabled": true,
|
||||
"deadman_enabled": true,
|
||||
"deadman_interval_hours": 48,
|
||||
"deadman_grace_hours": 4,
|
||||
"deadman_warning_webhook": "",
|
||||
"usb_monitoring_enabled": true,
|
||||
"tamper_monitoring_enabled": false,
|
||||
"chain_enabled": true,
|
||||
"chain_auto_wrap": true,
|
||||
"backup_reminder_days": 7,
|
||||
"cover_name": "Office Document Manager"
|
||||
}
|
||||
10
deploy/docker/.dockerignore
Normal file
10
deploy/docker/.dockerignore
Normal file
@ -0,0 +1,10 @@
|
||||
.git
|
||||
.claude
|
||||
__pycache__
|
||||
*.pyc
|
||||
.coverage
|
||||
.pytest_cache
|
||||
docs
|
||||
deploy/live-usb
|
||||
test_data
|
||||
*.egg-info
|
||||
81
deploy/docker/Dockerfile
Normal file
81
deploy/docker/Dockerfile
Normal file
@ -0,0 +1,81 @@
|
||||
# FieldWitness Federation Server
|
||||
# Multi-stage build for minimal image size.
|
||||
#
|
||||
# Tier 2: Org server (full features — web UI, attestation, federation, stego)
|
||||
# docker build -t fieldwitness-server .
|
||||
# docker run -v fieldwitness-data:/data -p 5000:5000 -p 8000:8000 fieldwitness-server
|
||||
#
|
||||
# Tier 3: Federation relay (attestation + federation only, no stego, no web UI)
|
||||
# docker build --target relay -t fieldwitness-relay .
|
||||
# docker run -v relay-data:/data -p 8000:8000 fieldwitness-relay
|
||||
|
||||
# === Stage 1: Build dependencies ===
|
||||
FROM python:3.12-slim-bookworm AS builder
|
||||
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
gcc g++ gfortran \
|
||||
libjpeg62-turbo-dev zlib1g-dev libffi-dev libssl-dev \
|
||||
libopenblas-dev \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
WORKDIR /build
|
||||
COPY . .
|
||||
|
||||
# Install into a virtual environment for clean copying
|
||||
RUN python -m venv /opt/fieldwitness-env \
|
||||
&& /opt/fieldwitness-env/bin/pip install --no-cache-dir \
|
||||
".[web,cli,attest,stego-dct,api,federation]"
|
||||
|
||||
# === Stage 2: Federation relay (minimal) ===
|
||||
FROM python:3.12-slim-bookworm AS relay
|
||||
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
libjpeg62-turbo libopenblas0 \
|
||||
&& rm -rf /var/lib/apt/lists/* \
|
||||
&& useradd -m -s /bin/bash fieldwitness
|
||||
|
||||
COPY --from=builder /opt/fieldwitness-env /opt/fieldwitness-env
|
||||
|
||||
ENV PATH="/opt/fieldwitness-env/bin:$PATH" \
|
||||
FIELDWITNESS_DATA_DIR=/data \
|
||||
PYTHONUNBUFFERED=1
|
||||
|
||||
VOLUME /data
|
||||
EXPOSE 8000
|
||||
|
||||
USER fieldwitness
|
||||
|
||||
# Federation relay: only the attest API with federation endpoints
|
||||
CMD ["uvicorn", "fieldwitness.attest.api:app", "--host", "0.0.0.0", "--port", "8000"]
|
||||
|
||||
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
|
||||
CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"
|
||||
|
||||
# === Stage 3: Full org server ===
|
||||
FROM python:3.12-slim-bookworm AS server
|
||||
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
libjpeg62-turbo libopenblas0 \
|
||||
&& rm -rf /var/lib/apt/lists/* \
|
||||
&& useradd -m -s /bin/bash fieldwitness
|
||||
|
||||
COPY --from=builder /opt/fieldwitness-env /opt/fieldwitness-env
|
||||
|
||||
# Copy frontend templates and static assets
|
||||
COPY frontends/ /opt/fieldwitness-env/lib/python3.12/site-packages/frontends/
|
||||
|
||||
ENV PATH="/opt/fieldwitness-env/bin:$PATH" \
|
||||
FIELDWITNESS_DATA_DIR=/data \
|
||||
PYTHONUNBUFFERED=1
|
||||
|
||||
VOLUME /data
|
||||
EXPOSE 5000 8000
|
||||
|
||||
USER fieldwitness
|
||||
|
||||
# Init on first run, then start web UI (HTTPS by default with self-signed cert).
|
||||
# Use --no-https explicitly if running behind a TLS-terminating reverse proxy.
|
||||
CMD ["sh", "-c", "fieldwitness init 2>/dev/null; fieldwitness serve --host 0.0.0.0"]
|
||||
|
||||
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s \
|
||||
CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:5000/health')"
|
||||
51
deploy/docker/docker-compose.yml
Normal file
51
deploy/docker/docker-compose.yml
Normal file
@ -0,0 +1,51 @@
|
||||
# FieldWitness Docker Compose — Three-Tier Deployment
|
||||
#
|
||||
# Tier 2 (Org Server): Full web UI + attestation + federation
|
||||
# Tier 3 (Federation Relay): Lightweight attestation API only
|
||||
#
|
||||
# Usage:
|
||||
# Full org server: docker compose up server
|
||||
# Federation relay only: docker compose up relay
|
||||
# Both (e.g., testing): docker compose up
|
||||
|
||||
services:
|
||||
# === Tier 2: Organizational Server ===
|
||||
# Full FieldWitness instance with web UI, stego, attestation, federation.
|
||||
# Deploy on a mini PC in the newsroom or a trusted VPS.
|
||||
server:
|
||||
build:
|
||||
context: ../..
|
||||
dockerfile: deploy/docker/Dockerfile
|
||||
target: server
|
||||
ports:
|
||||
- "5000:5000" # Web UI (Flask/Waitress)
|
||||
- "8000:8000" # Federation API (FastAPI/uvicorn)
|
||||
volumes:
|
||||
- server-data:/data
|
||||
environment:
|
||||
- FIELDWITNESS_DATA_DIR=/data
|
||||
- FIELDWITNESS_GOSSIP_INTERVAL=60
|
||||
restart: unless-stopped
|
||||
|
||||
# === Tier 3: Federation Relay ===
|
||||
# Lightweight relay for cross-organization attestation sync.
|
||||
# Deploy on a VPS in a friendly jurisdiction (Iceland, Switzerland).
|
||||
# Stores only attestation records — no key material, no stego, no web UI.
|
||||
relay:
|
||||
build:
|
||||
context: ../..
|
||||
dockerfile: deploy/docker/Dockerfile
|
||||
target: relay
|
||||
ports:
|
||||
- "8001:8000" # Federation API
|
||||
volumes:
|
||||
- relay-data:/data
|
||||
environment:
|
||||
- FIELDWITNESS_DATA_DIR=/data
|
||||
restart: unless-stopped
|
||||
|
||||
volumes:
|
||||
server-data:
|
||||
driver: local
|
||||
relay-data:
|
||||
driver: local
|
||||
52
deploy/kubernetes/README.md
Normal file
52
deploy/kubernetes/README.md
Normal file
@ -0,0 +1,52 @@
|
||||
# FieldWitness Kubernetes Deployment
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Field Devices (Tier 1)
|
||||
(Bootable USB + laptop)
|
||||
|
|
||||
| LAN / sneakernet
|
||||
v
|
||||
┌───────────────────────┐
|
||||
│ Org Server (Tier 2) │ <-- server-deployment.yaml
|
||||
│ Full web UI + stego │
|
||||
│ + attestation + fed │
|
||||
│ Newsroom mini PC │
|
||||
└───────────┬───────────┘
|
||||
|
|
||||
| gossip / federation API
|
||||
v
|
||||
┌───────────────────────┐
|
||||
│ Fed Relay (Tier 3) │ <-- relay-deployment.yaml
|
||||
│ Attestation API only │
|
||||
│ VPS (Iceland, CH) │
|
||||
│ Zero key knowledge │
|
||||
└───────────────────────┘
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Build images
|
||||
docker build -t fieldwitness-server --target server -f deploy/docker/Dockerfile .
|
||||
docker build -t fieldwitness-relay --target relay -f deploy/docker/Dockerfile .
|
||||
|
||||
# Deploy to Kubernetes
|
||||
kubectl apply -f deploy/kubernetes/namespace.yaml
|
||||
kubectl apply -f deploy/kubernetes/server-deployment.yaml
|
||||
kubectl apply -f deploy/kubernetes/relay-deployment.yaml
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- **Single writer**: Both deployments use `replicas: 1` with `Recreate` strategy.
|
||||
FieldWitness uses SQLite and append-only binary logs that require single-writer access.
|
||||
Do not scale horizontally.
|
||||
- **PVCs**: Both deployments require persistent volumes. The server needs 10Gi,
|
||||
the relay needs 5Gi. Adjust based on expected attestation volume.
|
||||
- **Security**: The relay stores only attestation records (image hashes + signatures).
|
||||
It never sees encryption keys, plaintext messages, or original images.
|
||||
If the relay is seized, the attacker gets cryptographic hashes — nothing actionable.
|
||||
- **Ingress**: Not included. Configure your own ingress controller with TLS termination.
|
||||
The federation API should be TLS-encrypted in transit.
|
||||
6
deploy/kubernetes/namespace.yaml
Normal file
6
deploy/kubernetes/namespace.yaml
Normal file
@ -0,0 +1,6 @@
|
||||
apiVersion: v1
|
||||
kind: Namespace
|
||||
metadata:
|
||||
name: fieldwitness
|
||||
labels:
|
||||
app.kubernetes.io/name: fieldwitness
|
||||
85
deploy/kubernetes/relay-deployment.yaml
Normal file
85
deploy/kubernetes/relay-deployment.yaml
Normal file
@ -0,0 +1,85 @@
|
||||
# FieldWitness Federation Relay — Lightweight attestation sync relay.
|
||||
# Deploy on a VPS in a favorable jurisdiction for geographic redundancy.
|
||||
# Stores only attestation records — zero knowledge of encryption keys.
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: fieldwitness-relay
|
||||
namespace: fieldwitness
|
||||
labels:
|
||||
app.kubernetes.io/name: fieldwitness
|
||||
app.kubernetes.io/component: relay
|
||||
spec:
|
||||
replicas: 1
|
||||
strategy:
|
||||
type: Recreate
|
||||
selector:
|
||||
matchLabels:
|
||||
app.kubernetes.io/name: fieldwitness
|
||||
app.kubernetes.io/component: relay
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app.kubernetes.io/name: fieldwitness
|
||||
app.kubernetes.io/component: relay
|
||||
spec:
|
||||
securityContext:
|
||||
runAsUser: 1000
|
||||
runAsGroup: 1000
|
||||
fsGroup: 1000
|
||||
containers:
|
||||
- name: relay
|
||||
image: fieldwitness-relay:latest
|
||||
ports:
|
||||
- containerPort: 8000
|
||||
name: federation
|
||||
env:
|
||||
- name: FIELDWITNESS_DATA_DIR
|
||||
value: /data
|
||||
volumeMounts:
|
||||
- name: data
|
||||
mountPath: /data
|
||||
resources:
|
||||
requests:
|
||||
memory: "256Mi"
|
||||
cpu: "100m"
|
||||
limits:
|
||||
memory: "1Gi"
|
||||
cpu: "1000m"
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /health
|
||||
port: 8000
|
||||
initialDelaySeconds: 10
|
||||
periodSeconds: 30
|
||||
volumes:
|
||||
- name: data
|
||||
persistentVolumeClaim:
|
||||
claimName: relay-data
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: PersistentVolumeClaim
|
||||
metadata:
|
||||
name: relay-data
|
||||
namespace: fieldwitness
|
||||
spec:
|
||||
accessModes:
|
||||
- ReadWriteOnce
|
||||
resources:
|
||||
requests:
|
||||
storage: 5Gi
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: fieldwitness-relay
|
||||
namespace: fieldwitness
|
||||
spec:
|
||||
selector:
|
||||
app.kubernetes.io/name: fieldwitness
|
||||
app.kubernetes.io/component: relay
|
||||
ports:
|
||||
- name: federation
|
||||
port: 8000
|
||||
targetPort: 8000
|
||||
type: ClusterIP
|
||||
97
deploy/kubernetes/server-deployment.yaml
Normal file
97
deploy/kubernetes/server-deployment.yaml
Normal file
@ -0,0 +1,97 @@
|
||||
# FieldWitness Org Server — Full deployment with persistent storage.
|
||||
# For newsroom or trusted infrastructure deployment.
|
||||
apiVersion: apps/v1
|
||||
kind: Deployment
|
||||
metadata:
|
||||
name: fieldwitness-server
|
||||
namespace: fieldwitness
|
||||
labels:
|
||||
app.kubernetes.io/name: fieldwitness
|
||||
app.kubernetes.io/component: server
|
||||
spec:
|
||||
replicas: 1 # Single writer — do not scale horizontally
|
||||
strategy:
|
||||
type: Recreate # Not RollingUpdate — SQLite + append-only logs need single writer
|
||||
selector:
|
||||
matchLabels:
|
||||
app.kubernetes.io/name: fieldwitness
|
||||
app.kubernetes.io/component: server
|
||||
template:
|
||||
metadata:
|
||||
labels:
|
||||
app.kubernetes.io/name: fieldwitness
|
||||
app.kubernetes.io/component: server
|
||||
spec:
|
||||
securityContext:
|
||||
runAsUser: 1000
|
||||
runAsGroup: 1000
|
||||
fsGroup: 1000
|
||||
containers:
|
||||
- name: fieldwitness
|
||||
image: fieldwitness-server:latest
|
||||
ports:
|
||||
- containerPort: 5000
|
||||
name: web
|
||||
- containerPort: 8000
|
||||
name: federation
|
||||
env:
|
||||
- name: FIELDWITNESS_DATA_DIR
|
||||
value: /data
|
||||
- name: FIELDWITNESS_GOSSIP_INTERVAL
|
||||
value: "60"
|
||||
volumeMounts:
|
||||
- name: data
|
||||
mountPath: /data
|
||||
resources:
|
||||
requests:
|
||||
memory: "512Mi"
|
||||
cpu: "250m"
|
||||
limits:
|
||||
memory: "2Gi"
|
||||
cpu: "2000m"
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /health
|
||||
port: 5000
|
||||
initialDelaySeconds: 15
|
||||
periodSeconds: 30
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
path: /health
|
||||
port: 5000
|
||||
initialDelaySeconds: 10
|
||||
periodSeconds: 10
|
||||
volumes:
|
||||
- name: data
|
||||
persistentVolumeClaim:
|
||||
claimName: fieldwitness-data
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: PersistentVolumeClaim
|
||||
metadata:
|
||||
name: fieldwitness-data
|
||||
namespace: fieldwitness
|
||||
spec:
|
||||
accessModes:
|
||||
- ReadWriteOnce
|
||||
resources:
|
||||
requests:
|
||||
storage: 10Gi
|
||||
---
|
||||
apiVersion: v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: fieldwitness-server
|
||||
namespace: fieldwitness
|
||||
spec:
|
||||
selector:
|
||||
app.kubernetes.io/name: fieldwitness
|
||||
app.kubernetes.io/component: server
|
||||
ports:
|
||||
- name: web
|
||||
port: 5000
|
||||
targetPort: 5000
|
||||
- name: federation
|
||||
port: 8000
|
||||
targetPort: 8000
|
||||
type: ClusterIP
|
||||
47
deploy/live-usb/build.sh
Executable file
47
deploy/live-usb/build.sh
Executable file
@ -0,0 +1,47 @@
|
||||
#!/usr/bin/env bash
|
||||
# Build a bootable Debian Live USB image with FieldWitness pre-installed.
|
||||
#
|
||||
# Prerequisites:
|
||||
# apt install live-build
|
||||
#
|
||||
# Usage:
|
||||
# cd deploy/live-usb
|
||||
# sudo ./build.sh
|
||||
#
|
||||
# Output: live-image-amd64.hybrid.iso (flash to USB with dd or Balena Etcher)
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
|
||||
FIELDWITNESS_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
|
||||
|
||||
echo "=== FieldWitness Live USB Image Builder ==="
|
||||
echo "Source: $FIELDWITNESS_ROOT"
|
||||
echo
|
||||
|
||||
cd "$SCRIPT_DIR"
|
||||
|
||||
# Clean previous builds
|
||||
lb clean 2>/dev/null || true
|
||||
|
||||
# Configure live-build
|
||||
lb config \
|
||||
--distribution bookworm \
|
||||
--architectures amd64 \
|
||||
--binary-images iso-hybrid \
|
||||
--memtest none \
|
||||
--bootappend-live "boot=live components locales=en_US.UTF-8 keyboard-layouts=us" \
|
||||
--apt-indices false \
|
||||
--security true \
|
||||
--updates true
|
||||
|
||||
# Build
|
||||
echo "Building image (this takes 10-20 minutes)..."
|
||||
lb build
|
||||
|
||||
echo
|
||||
echo "=== Build complete ==="
|
||||
echo "Image: $(ls -lh live-image-*.iso 2>/dev/null || echo 'Check for .iso file')"
|
||||
echo
|
||||
echo "Flash to USB:"
|
||||
echo " sudo dd if=live-image-amd64.hybrid.iso of=/dev/sdX bs=4M status=progress"
|
||||
echo " (replace /dev/sdX with your USB device)"
|
||||
26
deploy/live-usb/config/hooks/live/0100-install-fieldwitness.hook.chroot
Executable file
26
deploy/live-usb/config/hooks/live/0100-install-fieldwitness.hook.chroot
Executable file
@ -0,0 +1,26 @@
|
||||
#!/bin/bash
|
||||
# Install FieldWitness and all dependencies into the live image.
|
||||
# This runs inside the chroot during image build.
|
||||
set -euo pipefail
|
||||
|
||||
echo "=== Installing FieldWitness ==="
|
||||
|
||||
# Create fieldwitness user
|
||||
useradd -m -s /bin/bash -G sudo fieldwitness
|
||||
echo "fieldwitness:fieldwitness" | chpasswd
|
||||
|
||||
# Create virtual environment
|
||||
python3 -m venv /opt/fieldwitness-env
|
||||
source /opt/fieldwitness-env/bin/activate
|
||||
|
||||
# Install fieldwitness with all extras (pre-built wheels from PyPI)
|
||||
pip install --no-cache-dir "fieldwitness[web,cli,attest,stego-dct,stego-audio,fieldkit]"
|
||||
|
||||
# Verify installation
|
||||
python3 -c "import fieldwitness; print(f'FieldWitness {fieldwitness.__version__} installed')"
|
||||
python3 -c "from fieldwitness.stego import encode; print('stego OK')"
|
||||
python3 -c "from fieldwitness.attest import Attestation; print('attest OK')"
|
||||
|
||||
deactivate
|
||||
|
||||
echo "=== FieldWitness installation complete ==="
|
||||
39
deploy/live-usb/config/hooks/live/0200-harden.hook.chroot
Executable file
39
deploy/live-usb/config/hooks/live/0200-harden.hook.chroot
Executable file
@ -0,0 +1,39 @@
|
||||
#!/bin/bash
|
||||
# Security hardening for the live image.
|
||||
set -euo pipefail
|
||||
|
||||
echo "=== Applying security hardening ==="
|
||||
|
||||
# Disable core dumps (Python doesn't zero memory — core dumps leak keys)
|
||||
echo "* hard core 0" >> /etc/security/limits.conf
|
||||
echo "fs.suid_dumpable = 0" >> /etc/sysctl.d/99-fieldwitness.conf
|
||||
echo "kernel.core_pattern=|/bin/false" >> /etc/sysctl.d/99-fieldwitness.conf
|
||||
|
||||
# Disable swap (keys persist in swap pages)
|
||||
systemctl mask swap.target || true
|
||||
echo "vm.swappiness = 0" >> /etc/sysctl.d/99-fieldwitness.conf
|
||||
|
||||
# Enable UFW with deny-all + allow web UI
|
||||
ufw default deny incoming
|
||||
ufw default allow outgoing
|
||||
ufw allow 5000/tcp comment "FieldWitness Web UI"
|
||||
ufw allow 22/tcp comment "SSH"
|
||||
ufw --force enable || true
|
||||
|
||||
# Disable unnecessary services
|
||||
systemctl disable bluetooth.service 2>/dev/null || true
|
||||
systemctl disable avahi-daemon.service 2>/dev/null || true
|
||||
systemctl disable cups.service 2>/dev/null || true
|
||||
|
||||
# Enable FieldWitness service
|
||||
systemctl enable fieldwitness.service
|
||||
|
||||
# Auto-login to openbox (so the browser opens without login prompt)
|
||||
mkdir -p /etc/lightdm/lightdm.conf.d
|
||||
cat > /etc/lightdm/lightdm.conf.d/50-autologin.conf << 'EOF'
|
||||
[Seat:*]
|
||||
autologin-user=fieldwitness
|
||||
autologin-user-timeout=0
|
||||
EOF
|
||||
|
||||
echo "=== Hardening complete ==="
|
||||
@ -0,0 +1,28 @@
|
||||
[Unit]
|
||||
Description=FieldWitness
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=fieldwitness
|
||||
Group=fieldwitness
|
||||
WorkingDirectory=/home/fieldwitness
|
||||
Environment=PATH=/opt/fieldwitness-env/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
|
||||
Environment=FIELDWITNESS_DATA_DIR=/home/fieldwitness/.fwmetadata
|
||||
ExecStartPre=/opt/fieldwitness-env/bin/fieldwitness init --no-identity --no-channel
|
||||
ExecStart=/opt/fieldwitness-env/bin/fieldwitness serve --host 0.0.0.0 --no-https
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
|
||||
# Security hardening
|
||||
NoNewPrivileges=yes
|
||||
ProtectSystem=strict
|
||||
ProtectHome=read-only
|
||||
ReadWritePaths=/home/fieldwitness/.fwmetadata
|
||||
PrivateTmp=yes
|
||||
ProtectKernelTunables=yes
|
||||
ProtectControlGroups=yes
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
@ -0,0 +1,4 @@
|
||||
# FieldWitness Live USB — auto-open web UI in Firefox
|
||||
# Wait for the FieldWitness server to start, then open the browser
|
||||
sleep 5
|
||||
firefox-esr --kiosk http://127.0.0.1:5000 &
|
||||
@ -0,0 +1,41 @@
|
||||
## System essentials
|
||||
python3
|
||||
python3-pip
|
||||
python3-venv
|
||||
python3-dev
|
||||
|
||||
## Build dependencies for Python packages with C extensions
|
||||
libjpeg62-turbo-dev
|
||||
zlib1g-dev
|
||||
libffi-dev
|
||||
libssl-dev
|
||||
gfortran
|
||||
libopenblas-dev
|
||||
|
||||
## FieldWitness runtime dependencies
|
||||
gpsd
|
||||
gpsd-clients
|
||||
cryptsetup
|
||||
ufw
|
||||
shred
|
||||
|
||||
## Useful tools
|
||||
curl
|
||||
wget
|
||||
git
|
||||
htop
|
||||
usbutils
|
||||
pciutils
|
||||
|
||||
## GUI (minimal — just a browser for the web UI)
|
||||
xorg
|
||||
openbox
|
||||
firefox-esr
|
||||
lightdm
|
||||
|
||||
## Firmware for common laptop hardware
|
||||
firmware-linux-free
|
||||
firmware-misc-nonfree
|
||||
firmware-iwlwifi
|
||||
firmware-realtek
|
||||
firmware-atheros
|
||||
@ -1,15 +1,9 @@
|
||||
# SooSeF Docker Image
|
||||
#
|
||||
# Requires stegasoo and verisoo source directories alongside soosef:
|
||||
# Sources/
|
||||
# ├── stegasoo/
|
||||
# ├── verisoo/
|
||||
# └── soosef/ ← build context is parent (Sources/)
|
||||
# FieldWitness Docker Image
|
||||
#
|
||||
# Build:
|
||||
# docker build -t soosef -f soosef/docker/Dockerfile .
|
||||
# docker build -t fieldwitness -f docker/Dockerfile .
|
||||
#
|
||||
# Or use docker-compose from soosef/docker/:
|
||||
# Or use docker-compose from docker/:
|
||||
# docker compose up
|
||||
|
||||
FROM python:3.12-slim
|
||||
@ -33,35 +27,21 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
|
||||
WORKDIR /app
|
||||
|
||||
# ── Install stegasoo ─────────────────────────────────────────────
|
||||
COPY stegasoo/pyproject.toml stegasoo/pyproject.toml
|
||||
COPY stegasoo/README.md stegasoo/README.md
|
||||
COPY stegasoo/src/ stegasoo/src/
|
||||
COPY stegasoo/data/ stegasoo/data/
|
||||
COPY stegasoo/frontends/ stegasoo/frontends/
|
||||
RUN pip install --no-cache-dir /app/stegasoo[web,dct,audio,cli]
|
||||
|
||||
# ── Install verisoo ──────────────────────────────────────────────
|
||||
COPY verisoo/pyproject.toml verisoo/pyproject.toml
|
||||
COPY verisoo/README.md verisoo/README.md
|
||||
COPY verisoo/src/ verisoo/src/
|
||||
RUN pip install --no-cache-dir /app/verisoo[cli]
|
||||
|
||||
# ── Install soosef ───────────────────────────────────────────────
|
||||
COPY soosef/pyproject.toml soosef/pyproject.toml
|
||||
COPY soosef/README.md soosef/README.md
|
||||
COPY soosef/src/ soosef/src/
|
||||
COPY soosef/frontends/ soosef/frontends/
|
||||
RUN pip install --no-cache-dir /app/soosef[web,cli]
|
||||
# ── Install fieldwitness ─────────────────────────────────────────
|
||||
COPY pyproject.toml pyproject.toml
|
||||
COPY README.md README.md
|
||||
COPY src/ src/
|
||||
COPY frontends/ frontends/
|
||||
RUN pip install --no-cache-dir /app[web,cli]
|
||||
|
||||
# ── Runtime setup ────────────────────────────────────────────────
|
||||
RUN mkdir -p /root/.soosef
|
||||
RUN mkdir -p /root/.fwmetadata
|
||||
|
||||
COPY soosef/docker/entrypoint.sh /app/entrypoint.sh
|
||||
COPY docker/entrypoint.sh /app/entrypoint.sh
|
||||
RUN chmod +x /app/entrypoint.sh
|
||||
|
||||
ENV SOOSEF_DATA_DIR=/root/.soosef
|
||||
WORKDIR /app/soosef
|
||||
ENV FIELDWITNESS_DATA_DIR=/root/.fwmetadata
|
||||
WORKDIR /app
|
||||
|
||||
EXPOSE 35811
|
||||
|
||||
|
||||
@ -1,19 +1,19 @@
|
||||
services:
|
||||
soosef:
|
||||
fieldwitness:
|
||||
build:
|
||||
context: ../.. # Sources/ directory (contains stegasoo/, verisoo/, soosef/)
|
||||
dockerfile: soosef/docker/Dockerfile
|
||||
container_name: soosef
|
||||
context: .. # Project root directory
|
||||
dockerfile: docker/Dockerfile
|
||||
container_name: fieldwitness
|
||||
ports:
|
||||
- "35811:35811"
|
||||
environment:
|
||||
SOOSEF_DATA_DIR: /root/.soosef
|
||||
SOOSEF_PORT: "35811"
|
||||
SOOSEF_WORKERS: "2"
|
||||
SOOSEF_HTTPS_ENABLED: "${SOOSEF_HTTPS_ENABLED:-false}"
|
||||
STEGASOO_CHANNEL_KEY: "${STEGASOO_CHANNEL_KEY:-}"
|
||||
FIELDWITNESS_DATA_DIR: /root/.fwmetadata
|
||||
FIELDWITNESS_PORT: "35811"
|
||||
FIELDWITNESS_WORKERS: "2"
|
||||
FIELDWITNESS_HTTPS_ENABLED: "${FIELDWITNESS_HTTPS_ENABLED:-false}"
|
||||
FIELDWITNESS_CHANNEL_KEY: "${FIELDWITNESS_CHANNEL_KEY:-}"
|
||||
volumes:
|
||||
- soosef-data:/root/.soosef
|
||||
- fieldwitness-data:/root/.fwmetadata
|
||||
restart: unless-stopped
|
||||
healthcheck:
|
||||
test: ["CMD", "curl", "-fs", "--max-time", "3", "http://localhost:35811/"]
|
||||
@ -29,5 +29,5 @@ services:
|
||||
memory: 512M
|
||||
|
||||
volumes:
|
||||
soosef-data:
|
||||
fieldwitness-data:
|
||||
driver: local
|
||||
|
||||
@ -2,24 +2,24 @@
|
||||
set -e
|
||||
|
||||
# Initialize if needed (generates identity + channel key + config)
|
||||
if [ ! -f "$SOOSEF_DATA_DIR/config.json" ]; then
|
||||
echo "First run — initializing SooSeF..."
|
||||
soosef init
|
||||
if [ ! -f "$FIELDWITNESS_DATA_DIR/config.json" ]; then
|
||||
echo "First run — initializing FieldWitness..."
|
||||
fieldwitness init
|
||||
echo "Initialization complete."
|
||||
fi
|
||||
|
||||
# Determine HTTPS mode
|
||||
HTTPS_FLAG=""
|
||||
if [ "${SOOSEF_HTTPS_ENABLED:-true}" = "false" ]; then
|
||||
if [ "${FIELDWITNESS_HTTPS_ENABLED:-true}" = "false" ]; then
|
||||
HTTPS_FLAG="--no-https"
|
||||
fi
|
||||
|
||||
echo "Starting SooSeF on port ${SOOSEF_PORT:-35811}..."
|
||||
echo "Starting FieldWitness on port ${FIELDWITNESS_PORT:-35811}..."
|
||||
|
||||
# Run with gunicorn for production
|
||||
exec gunicorn \
|
||||
--bind "0.0.0.0:${SOOSEF_PORT:-35811}" \
|
||||
--workers "${SOOSEF_WORKERS:-2}" \
|
||||
--bind "0.0.0.0:${FIELDWITNESS_PORT:-35811}" \
|
||||
--workers "${FIELDWITNESS_WORKERS:-2}" \
|
||||
--timeout 180 \
|
||||
--access-logfile - \
|
||||
--error-logfile - \
|
||||
|
||||
252
docs/architecture/chain-format.md
Normal file
252
docs/architecture/chain-format.md
Normal file
@ -0,0 +1,252 @@
|
||||
# Chain Format Specification
|
||||
|
||||
**Status**: Design
|
||||
**Version**: 1 (record format version)
|
||||
**Last updated**: 2026-04-01
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The attestation chain is an append-only sequence of signed records stored locally on the
|
||||
offline device. Each record includes a hash of the previous record, forming a tamper-evident
|
||||
chain analogous to git commits or blockchain blocks.
|
||||
|
||||
The chain wraps existing Attest attestation records. A Attest record's serialized bytes
|
||||
become the input to `content_hash`, preserving the original attestation while adding
|
||||
ordering, entropy witnesses, and chain integrity guarantees.
|
||||
|
||||
## 2. AttestationChainRecord
|
||||
|
||||
### Field Definitions
|
||||
|
||||
| Field | CBOR Key | Type | Size | Description |
|
||||
|---|---|---|---|---|
|
||||
| `version` | 0 | unsigned int | 1 byte | Record format version. Currently `1`. |
|
||||
| `record_id` | 1 | byte string | 16 bytes | UUID v7 (RFC 9562). Time-ordered unique identifier. |
|
||||
| `chain_index` | 2 | unsigned int | 8 bytes max | Monotonically increasing, 0-based. Genesis record is index 0. |
|
||||
| `prev_hash` | 3 | byte string | 32 bytes | SHA-256 of `canonical_bytes(previous_record)`. Genesis: `0x00 * 32`. |
|
||||
| `content_hash` | 4 | byte string | 32 bytes | SHA-256 of the wrapped content (e.g., Attest record bytes). |
|
||||
| `content_type` | 5 | text string | variable | MIME-like type identifier. `"attest/attestation-v1"` for Attest records. |
|
||||
| `metadata` | 6 | CBOR map | variable | Extensible key-value map. See §2.1. |
|
||||
| `claimed_ts` | 7 | integer | 8 bytes max | Unix timestamp in microseconds (µs). Signed integer to handle pre-epoch dates. |
|
||||
| `entropy_witnesses` | 8 | CBOR map | variable | System entropy snapshot. See §3. |
|
||||
| `signer_pubkey` | 9 | byte string | 32 bytes | Ed25519 raw public key bytes. |
|
||||
| `signature` | 10 | byte string | 64 bytes | Ed25519 signature over `canonical_bytes(record)` excluding the signature field. |
|
||||
|
||||
### 2.1 Metadata Map
|
||||
|
||||
The `metadata` field is an open CBOR map with text string keys. Defined keys:
|
||||
|
||||
| Key | Type | Description |
|
||||
|---|---|---|
|
||||
| `"backfilled"` | bool | `true` if this record was created by the backfill migration |
|
||||
| `"caption"` | text | Human-readable description of the attested content |
|
||||
| `"location"` | text | Location name associated with the attestation |
|
||||
| `"original_ts"` | integer | Original Attest timestamp (µs) if different from `claimed_ts` |
|
||||
| `"tags"` | array of text | User-defined classification tags |
|
||||
|
||||
Applications may add custom keys. Unknown keys must be preserved during serialization.
|
||||
|
||||
## 3. Entropy Witnesses
|
||||
|
||||
Entropy witnesses are system-state snapshots collected at record creation time. They serve
|
||||
as soft evidence that the claimed timestamp is plausible. Fabricating convincing witnesses
|
||||
for a backdated record requires simulating the full system state at the claimed time.
|
||||
|
||||
| Field | CBOR Key | Type | Source | Fallback (non-Linux) |
|
||||
|---|---|---|---|---|
|
||||
| `sys_uptime` | 0 | float64 | `time.monotonic()` | Same (cross-platform) |
|
||||
| `fs_snapshot` | 1 | byte string (16 bytes) | SHA-256 of `os.stat()` on chain DB, truncated to 16 bytes | SHA-256 of chain dir stat |
|
||||
| `proc_entropy` | 2 | unsigned int | `/proc/sys/kernel/random/entropy_avail` | `len(os.urandom(32))` (always 32, marker for non-Linux) |
|
||||
| `boot_id` | 3 | text string | `/proc/sys/kernel/random/boot_id` | `uuid.uuid4()` cached per process lifetime |
|
||||
|
||||
### Witness Properties
|
||||
|
||||
- **sys_uptime**: Monotonically increasing within a boot. Cannot decrease. A record with
|
||||
`sys_uptime < previous_record.sys_uptime` and `claimed_ts > previous_record.claimed_ts`
|
||||
is suspicious (reboot or clock manipulation).
|
||||
- **fs_snapshot**: Changes with every write to the chain DB. Hash includes mtime, ctime,
|
||||
size, and inode number.
|
||||
- **proc_entropy**: Varies naturally. On Linux, reflects kernel entropy pool state.
|
||||
- **boot_id**: Changes on every reboot. Identical `boot_id` across records implies same
|
||||
boot session — combined with `sys_uptime`, this constrains the timeline.
|
||||
|
||||
## 4. Serialization
|
||||
|
||||
### 4.1 Canonical Bytes
|
||||
|
||||
`canonical_bytes(record)` produces the deterministic byte representation used for hashing
|
||||
and signing. It is a CBOR map containing all fields **except** `signature`, encoded using
|
||||
CBOR canonical encoding (RFC 8949 §4.2):
|
||||
|
||||
- Map keys sorted by integer value (0, 1, 2, ..., 9)
|
||||
- Integers use minimal-length encoding
|
||||
- No indefinite-length items
|
||||
- No duplicate keys
|
||||
|
||||
```
|
||||
canonical_bytes(record) = cbor2.dumps({
|
||||
0: record.version,
|
||||
1: record.record_id,
|
||||
2: record.chain_index,
|
||||
3: record.prev_hash,
|
||||
4: record.content_hash,
|
||||
5: record.content_type,
|
||||
6: record.metadata,
|
||||
7: record.claimed_ts,
|
||||
8: {
|
||||
0: record.entropy_witnesses.sys_uptime,
|
||||
1: record.entropy_witnesses.fs_snapshot,
|
||||
2: record.entropy_witnesses.proc_entropy,
|
||||
3: record.entropy_witnesses.boot_id,
|
||||
},
|
||||
9: record.signer_pubkey,
|
||||
}, canonical=True)
|
||||
```
|
||||
|
||||
### 4.2 Record Hash
|
||||
|
||||
```
|
||||
compute_record_hash(record) = SHA-256(canonical_bytes(record))
|
||||
```
|
||||
|
||||
This hash is used as `prev_hash` in the next record and as Merkle tree leaves in export
|
||||
bundles.
|
||||
|
||||
### 4.3 Signature
|
||||
|
||||
```
|
||||
record.signature = Ed25519_Sign(private_key, canonical_bytes(record))
|
||||
```
|
||||
|
||||
Verification:
|
||||
```
|
||||
Ed25519_Verify(record.signer_pubkey, record.signature, canonical_bytes(record))
|
||||
```
|
||||
|
||||
### 4.4 Full Serialization
|
||||
|
||||
`serialize_record(record)` produces the full CBOR encoding including the signature field
|
||||
(CBOR key 10). This is used for storage and transmission.
|
||||
|
||||
```
|
||||
serialize_record(record) = cbor2.dumps({
|
||||
0: record.version,
|
||||
1: record.record_id,
|
||||
...
|
||||
9: record.signer_pubkey,
|
||||
10: record.signature,
|
||||
}, canonical=True)
|
||||
```
|
||||
|
||||
## 5. Chain Rules
|
||||
|
||||
### 5.1 Genesis Record
|
||||
|
||||
The first record in a chain (index 0) has:
|
||||
- `chain_index = 0`
|
||||
- `prev_hash = b'\x00' * 32` (32 zero bytes)
|
||||
|
||||
The **chain ID** is defined as `SHA-256(canonical_bytes(genesis_record))`. This permanently
|
||||
identifies the chain.
|
||||
|
||||
### 5.2 Append Rule
|
||||
|
||||
For record N (where N > 0):
|
||||
```
|
||||
record_N.chain_index == record_{N-1}.chain_index + 1
|
||||
record_N.prev_hash == compute_record_hash(record_{N-1})
|
||||
record_N.claimed_ts >= record_{N-1}.claimed_ts (SHOULD, not MUST — clock skew possible)
|
||||
```
|
||||
|
||||
### 5.3 Verification
|
||||
|
||||
Full chain verification checks, for each record from index 0 to head:
|
||||
1. `Ed25519_Verify(record.signer_pubkey, record.signature, canonical_bytes(record))` — signature valid
|
||||
2. `record.chain_index == expected_index` — no gaps or duplicates
|
||||
3. `record.prev_hash == compute_record_hash(previous_record)` — chain link intact
|
||||
4. All `signer_pubkey` values are identical within a chain (single-signer chain)
|
||||
|
||||
Violation of rule 4 indicates a chain was signed by multiple identities, which may be
|
||||
legitimate (key rotation) or malicious (chain hijacking). Key rotation is out of scope for
|
||||
v1; implementations should flag this as a warning.
|
||||
|
||||
## 6. Storage Format
|
||||
|
||||
### 6.1 chain.bin (Append-Only Log)
|
||||
|
||||
Records are stored sequentially as length-prefixed CBOR:
|
||||
|
||||
```
|
||||
┌─────────────────────────────┐
|
||||
│ uint32 BE: record_0 length │
|
||||
│ bytes: serialize(record_0) │
|
||||
├─────────────────────────────┤
|
||||
│ uint32 BE: record_1 length │
|
||||
│ bytes: serialize(record_1) │
|
||||
├─────────────────────────────┤
|
||||
│ ... │
|
||||
└─────────────────────────────┘
|
||||
```
|
||||
|
||||
- Length prefix is 4 bytes, big-endian unsigned 32-bit integer
|
||||
- Maximum record size: 4 GiB (practical limit much smaller)
|
||||
- File is append-only; records are never modified or deleted
|
||||
- File locking via `fcntl.flock(LOCK_EX)` for single-writer safety
|
||||
|
||||
### 6.2 state.cbor (Chain State Checkpoint)
|
||||
|
||||
A single CBOR map, atomically rewritten after each append:
|
||||
|
||||
```cbor
|
||||
{
|
||||
"chain_id": bytes[32], # SHA-256(canonical_bytes(genesis))
|
||||
"head_index": uint, # Index of the most recent record
|
||||
"head_hash": bytes[32], # Hash of the most recent record
|
||||
"record_count": uint, # Total records in chain
|
||||
"created_at": int, # Unix µs when chain was created
|
||||
"last_append_at": int # Unix µs of last append
|
||||
}
|
||||
```
|
||||
|
||||
This file is a performance optimization — the canonical state is always derivable from
|
||||
`chain.bin`. On corruption, `state.cbor` is rebuilt by scanning the log.
|
||||
|
||||
### 6.3 File Locations
|
||||
|
||||
```
|
||||
~/.fwmetadata/chain/
|
||||
chain.bin Append-only record log
|
||||
state.cbor Chain state checkpoint
|
||||
```
|
||||
|
||||
Paths are defined in `src/fieldwitness/paths.py`.
|
||||
|
||||
## 7. Migration from Attest-Only Attestations
|
||||
|
||||
Existing Attest attestations in `~/.fwmetadata/attestations/` are not modified. The chain
|
||||
is a parallel structure. Migration is performed by the `fieldwitness chain backfill` command:
|
||||
|
||||
1. Iterate all records in Attest's `LocalStorage` (ordered by timestamp)
|
||||
2. For each record, compute `content_hash = SHA-256(record.to_bytes())`
|
||||
3. Create a chain record with:
|
||||
- `content_type = "attest/attestation-v1"`
|
||||
- `claimed_ts` set to the original Attest timestamp
|
||||
- `metadata = {"backfilled": true, "original_ts": <attest_timestamp>}`
|
||||
- Entropy witnesses collected at migration time (not original time)
|
||||
4. Append to chain
|
||||
|
||||
Backfilled records are distinguishable via the `backfilled` metadata flag. Their entropy
|
||||
witnesses reflect migration time, not original attestation time — this is honest and
|
||||
intentional.
|
||||
|
||||
## 8. Content Types
|
||||
|
||||
The `content_type` field identifies what was hashed into `content_hash`. Defined types:
|
||||
|
||||
| Content Type | Description |
|
||||
|---|---|
|
||||
| `attest/attestation-v1` | Attest `AttestationRecord` serialized bytes |
|
||||
| `fieldwitness/raw-file-v1` | Raw file bytes (for non-image attestations, future) |
|
||||
| `fieldwitness/metadata-only-v1` | No file content; metadata-only attestation (future) |
|
||||
|
||||
New content types may be added without changing the record format version.
|
||||
319
docs/architecture/export-bundle.md
Normal file
319
docs/architecture/export-bundle.md
Normal file
@ -0,0 +1,319 @@
|
||||
# Export Bundle Specification
|
||||
|
||||
**Status**: Design
|
||||
**Version**: 1 (bundle format version)
|
||||
**Last updated**: 2026-04-01
|
||||
|
||||
## 1. Overview
|
||||
|
||||
An export bundle packages a contiguous range of chain records into a portable, encrypted
|
||||
file suitable for transfer across an air gap. The bundle format is designed so that:
|
||||
|
||||
- **Auditors** can verify chain integrity without decrypting content
|
||||
- **Recipients** with the correct key can decrypt and read attestation records
|
||||
- **Anyone** can detect tampering via Merkle root and signature verification
|
||||
- **Steganographic embedding** is optional — bundles can be hidden in JPEG images via DCT
|
||||
|
||||
The format follows the pattern established by `keystore/export.py` (SOOBNDL): magic bytes,
|
||||
version, structured binary payload.
|
||||
|
||||
## 2. Binary Layout
|
||||
|
||||
```
|
||||
Offset Size Field
|
||||
────── ───────── ──────────────────────────────────────
|
||||
0 8 magic: b"FIELDWITNESSX1"
|
||||
8 1 version: uint8 (1)
|
||||
9 4 summary_len: uint32 BE
|
||||
13 var chain_summary: CBOR (see §3)
|
||||
var 4 recipients_len: uint32 BE
|
||||
var var recipients: CBOR array (see §4)
|
||||
var 12 nonce: AES-256-GCM nonce
|
||||
var var ciphertext: AES-256-GCM(zstd(CBOR(records)))
|
||||
last 16 16 tag: AES-256-GCM authentication tag
|
||||
```
|
||||
|
||||
All multi-byte integers are big-endian. The total bundle size is:
|
||||
`9 + 4 + summary_len + 4 + recipients_len + 12 + ciphertext_len + 16`
|
||||
|
||||
### Parsing Without Decryption
|
||||
|
||||
To audit a bundle without decryption, read:
|
||||
1. Magic (8 bytes) — verify `b"FIELDWITNESSX1"`
|
||||
2. Version (1 byte) — verify `1`
|
||||
3. Summary length (4 bytes BE) — read the next N bytes as CBOR
|
||||
4. Chain summary — verify signature, inspect metadata
|
||||
|
||||
The encrypted payload and recipient list can be skipped for audit purposes.
|
||||
|
||||
## 3. Chain Summary
|
||||
|
||||
The chain summary sits **outside** the encryption envelope. It provides verifiable metadata
|
||||
about the bundle contents without revealing the actual attestation data.
|
||||
|
||||
CBOR map with integer keys:
|
||||
|
||||
| CBOR Key | Field | Type | Description |
|
||||
|---|---|---|---|
|
||||
| 0 | `bundle_id` | byte string (16) | UUID v7, unique bundle identifier |
|
||||
| 1 | `chain_id` | byte string (32) | SHA-256(genesis record) — identifies source chain |
|
||||
| 2 | `range_start` | unsigned int | First record index (inclusive) |
|
||||
| 3 | `range_end` | unsigned int | Last record index (inclusive) |
|
||||
| 4 | `record_count` | unsigned int | Number of records in bundle |
|
||||
| 5 | `first_hash` | byte string (32) | `compute_record_hash(first_record)` |
|
||||
| 6 | `last_hash` | byte string (32) | `compute_record_hash(last_record)` |
|
||||
| 7 | `merkle_root` | byte string (32) | Root of Merkle tree over record hashes (see §5) |
|
||||
| 8 | `created_ts` | integer | Bundle creation timestamp (Unix µs) |
|
||||
| 9 | `signer_pubkey` | byte string (32) | Ed25519 public key of bundle creator |
|
||||
| 10 | `bundle_sig` | byte string (64) | Ed25519 signature (see §3.1) |
|
||||
|
||||
### 3.1 Signature Computation
|
||||
|
||||
The signature covers all summary fields except `bundle_sig` itself:
|
||||
|
||||
```
|
||||
summary_bytes = cbor2.dumps({
|
||||
0: bundle_id,
|
||||
1: chain_id,
|
||||
2: range_start,
|
||||
3: range_end,
|
||||
4: record_count,
|
||||
5: first_hash,
|
||||
6: last_hash,
|
||||
7: merkle_root,
|
||||
8: created_ts,
|
||||
9: signer_pubkey,
|
||||
}, canonical=True)
|
||||
|
||||
bundle_sig = Ed25519_Sign(private_key, summary_bytes)
|
||||
```
|
||||
|
||||
### 3.2 Verification Without Decryption
|
||||
|
||||
An auditor verifies a bundle by:
|
||||
1. Parse chain summary
|
||||
2. `Ed25519_Verify(signer_pubkey, bundle_sig, summary_bytes)` — authentic summary
|
||||
3. `record_count == range_end - range_start + 1` — count matches range
|
||||
4. If previous bundles from the same `chain_id` exist, verify `first_hash` matches
|
||||
the expected continuation
|
||||
|
||||
The auditor now knows: "A chain with ID X contains records [start, end], the creator
|
||||
signed this claim, and the Merkle root commits to specific record contents." All without
|
||||
decrypting.
|
||||
|
||||
## 4. Envelope Encryption
|
||||
|
||||
### 4.1 Key Derivation
|
||||
|
||||
Ed25519 signing keys are converted to X25519 Diffie-Hellman keys for encryption:
|
||||
|
||||
```
|
||||
x25519_private = Ed25519_to_X25519_Private(ed25519_private_key)
|
||||
x25519_public = Ed25519_to_X25519_Public(ed25519_public_key_bytes)
|
||||
```
|
||||
|
||||
This uses the birational map between Ed25519 and X25519 curves, supported natively by
|
||||
the `cryptography` library.
|
||||
|
||||
### 4.2 DEK Generation
|
||||
|
||||
A random 32-byte data encryption key (DEK) is generated per bundle:
|
||||
|
||||
```
|
||||
dek = os.urandom(32) # AES-256 key
|
||||
```
|
||||
|
||||
### 4.3 DEK Wrapping (Per Recipient)
|
||||
|
||||
For each recipient, the DEK is wrapped using X25519 ECDH + HKDF + AES-256-GCM:
|
||||
|
||||
```
|
||||
1. shared_secret = X25519_ECDH(sender_x25519_private, recipient_x25519_public)
|
||||
2. derived_key = HKDF-SHA256(
|
||||
ikm=shared_secret,
|
||||
salt=bundle_id, # binds to this specific bundle
|
||||
info=b"fieldwitness-dek-wrap-v1",
|
||||
length=32
|
||||
)
|
||||
3. wrapped_dek = AES-256-GCM_Encrypt(
|
||||
key=derived_key,
|
||||
nonce=os.urandom(12),
|
||||
plaintext=dek,
|
||||
aad=bundle_id # additional authenticated data
|
||||
)
|
||||
```
|
||||
|
||||
### 4.4 Recipients Array
|
||||
|
||||
CBOR array of recipient entries:
|
||||
|
||||
```cbor
|
||||
[
|
||||
{
|
||||
0: recipient_pubkey, # byte string (32) — Ed25519 public key
|
||||
1: wrap_nonce, # byte string (12) — AES-GCM nonce for DEK wrap
|
||||
2: wrapped_dek, # byte string (48) — encrypted DEK (32) + GCM tag (16)
|
||||
},
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
### 4.5 Payload Encryption
|
||||
|
||||
```
|
||||
1. records_cbor = cbor2.dumps([serialize_record(r) for r in records], canonical=True)
|
||||
2. compressed = zstd.compress(records_cbor, level=3)
|
||||
3. nonce = os.urandom(12)
|
||||
4. ciphertext, tag = AES-256-GCM_Encrypt(
|
||||
key=dek,
|
||||
nonce=nonce,
|
||||
plaintext=compressed,
|
||||
aad=summary_bytes # binds ciphertext to this summary
|
||||
)
|
||||
```
|
||||
|
||||
The `summary_bytes` (same bytes that are signed) are used as additional authenticated
|
||||
data (AAD). This cryptographically binds the encrypted payload to the chain summary —
|
||||
modifying the summary invalidates the decryption.
|
||||
|
||||
### 4.6 Decryption
|
||||
|
||||
A recipient decrypts a bundle:
|
||||
|
||||
```
|
||||
1. Parse chain summary, verify bundle_sig
|
||||
2. Find own pubkey in recipients array
|
||||
3. shared_secret = X25519_ECDH(recipient_x25519_private, sender_x25519_public)
|
||||
(sender_x25519_public derived from summary.signer_pubkey)
|
||||
4. derived_key = HKDF-SHA256(shared_secret, salt=bundle_id, info=b"fieldwitness-dek-wrap-v1")
|
||||
5. dek = AES-256-GCM_Decrypt(derived_key, wrap_nonce, wrapped_dek, aad=bundle_id)
|
||||
6. compressed = AES-256-GCM_Decrypt(dek, nonce, ciphertext, aad=summary_bytes)
|
||||
7. records_cbor = zstd.decompress(compressed)
|
||||
8. records = [deserialize_record(r) for r in cbor2.loads(records_cbor)]
|
||||
9. Verify each record's signature and chain linkage
|
||||
```
|
||||
|
||||
## 5. Merkle Tree
|
||||
|
||||
The Merkle tree provides compact proofs that specific records are included in a bundle.
|
||||
|
||||
### 5.1 Construction
|
||||
|
||||
Leaves are the record hashes in chain order:
|
||||
|
||||
```
|
||||
leaf[i] = compute_record_hash(records[i])
|
||||
```
|
||||
|
||||
Internal nodes:
|
||||
|
||||
```
|
||||
node = SHA-256(left_child || right_child)
|
||||
```
|
||||
|
||||
If the number of leaves is not a power of 2, the last leaf is promoted to the next level
|
||||
(standard binary Merkle tree padding).
|
||||
|
||||
### 5.2 Inclusion Proof
|
||||
|
||||
An inclusion proof for record at index `i` is a list of `(sibling_hash, direction)` pairs
|
||||
from the leaf to the root. Verification:
|
||||
|
||||
```
|
||||
current = leaf[i]
|
||||
for (sibling, direction) in proof:
|
||||
if direction == "L":
|
||||
current = SHA-256(sibling || current)
|
||||
else:
|
||||
current = SHA-256(current || sibling)
|
||||
assert current == merkle_root
|
||||
```
|
||||
|
||||
### 5.3 Usage
|
||||
|
||||
- **Export bundles**: `merkle_root` in chain summary commits to exact record contents
|
||||
- **Federation servers**: Build a separate Merkle tree over bundle hashes (see federation-protocol.md)
|
||||
|
||||
These are two different trees:
|
||||
1. **Record tree** (this section) — leaves are record hashes within a bundle
|
||||
2. **Bundle tree** (federation) — leaves are bundle hashes across the federation log
|
||||
|
||||
## 6. Steganographic Embedding
|
||||
|
||||
Bundles can optionally be embedded in JPEG images using stego's DCT steganography:
|
||||
|
||||
```
|
||||
1. bundle_bytes = create_export_bundle(chain, start, end, private_key, recipients)
|
||||
2. stego_image = stego.encode(
|
||||
carrier=carrier_image,
|
||||
reference=reference_image,
|
||||
file_data=bundle_bytes,
|
||||
passphrase=passphrase,
|
||||
embed_mode="dct",
|
||||
channel_key=channel_key # optional
|
||||
)
|
||||
```
|
||||
|
||||
Extraction:
|
||||
```
|
||||
1. result = stego.decode(
|
||||
carrier=stego_image,
|
||||
reference=reference_image,
|
||||
passphrase=passphrase,
|
||||
channel_key=channel_key
|
||||
)
|
||||
2. bundle_bytes = result.file_data
|
||||
3. assert bundle_bytes[:8] == b"FIELDWITNESSX1"
|
||||
```
|
||||
|
||||
### 6.1 Capacity Considerations
|
||||
|
||||
DCT steganography has limited capacity relative to the carrier image size. Approximate
|
||||
capacities:
|
||||
|
||||
| Carrier Size | Approximate DCT Capacity | Records (est.) |
|
||||
|---|---|---|
|
||||
| 1 MP (1024x1024) | ~10 KB | ~20-40 records |
|
||||
| 4 MP (2048x2048) | ~40 KB | ~80-160 records |
|
||||
| 12 MP (4000x3000) | ~100 KB | ~200-400 records |
|
||||
|
||||
Record size varies (~200-500 bytes each after CBOR serialization, before compression).
|
||||
Zstd compression typically achieves 2-4x ratio on CBOR attestation data. Use
|
||||
`check_capacity()` before embedding.
|
||||
|
||||
### 6.2 Multiple Images
|
||||
|
||||
For large export ranges, split across multiple bundles embedded in multiple carrier images.
|
||||
Each bundle is self-contained with its own chain summary. The receiving side imports them
|
||||
in any order — the chain indices and hashes enable reassembly.
|
||||
|
||||
## 7. Recipient Management
|
||||
|
||||
### 7.1 Adding Recipients
|
||||
|
||||
Recipients are identified by their Ed25519 public keys. To encrypt a bundle for a
|
||||
recipient, the creator needs only their public key (no shared secret setup required).
|
||||
|
||||
### 7.2 Recipient Discovery
|
||||
|
||||
Recipients' Ed25519 public keys can be obtained via:
|
||||
- Direct exchange (QR code, USB transfer, verbal fingerprint verification)
|
||||
- Federation server identity registry (when available)
|
||||
- Attest's existing `peers.json` file
|
||||
|
||||
### 7.3 Self-Encryption
|
||||
|
||||
The bundle creator should always include their own public key in the recipients list.
|
||||
This allows them to decrypt their own exports (e.g., when restoring from backup).
|
||||
|
||||
## 8. Error Handling
|
||||
|
||||
| Error | Cause | Response |
|
||||
|---|---|---|
|
||||
| Bad magic | Not a FIELDWITNESSX1 bundle | Reject with `ExportError("not a FieldWitness export bundle")` |
|
||||
| Bad version | Unsupported format version | Reject with `ExportError("unsupported bundle version")` |
|
||||
| Signature invalid | Tampered summary or wrong signer | Reject with `ExportError("bundle signature verification failed")` |
|
||||
| No matching recipient | Decryptor's key not in recipients list | Reject with `ExportError("not an authorized recipient")` |
|
||||
| GCM auth failure | Tampered ciphertext or wrong key | Reject with `ExportError("decryption failed — bundle may be corrupted")` |
|
||||
| Decompression failure | Corrupted compressed data | Reject with `ExportError("decompression failed")` |
|
||||
| Chain integrity failure | Records don't link correctly | Reject with `ChainIntegrityError(...)` after decryption |
|
||||
565
docs/architecture/federation-protocol.md
Normal file
565
docs/architecture/federation-protocol.md
Normal file
@ -0,0 +1,565 @@
|
||||
# Federation Protocol Specification
|
||||
|
||||
**Status**: Design
|
||||
**Version**: 1 (protocol version)
|
||||
**Last updated**: 2026-04-01
|
||||
|
||||
## 1. Overview
|
||||
|
||||
The federation is a network of append-only log servers inspired by Certificate Transparency
|
||||
(RFC 6962). Each server acts as a "blind notary" — it stores encrypted attestation bundles,
|
||||
maintains a Merkle tree over them, and issues signed receipts proving when bundles were
|
||||
received. Servers gossip with peers to ensure consistency and replicate data.
|
||||
|
||||
Federation servers never decrypt attestation content. They operate at the "federation
|
||||
member" permission tier: they can verify chain summaries and signatures, but not read
|
||||
the underlying attestation data.
|
||||
|
||||
## 2. Terminology
|
||||
|
||||
| Term | Definition |
|
||||
|---|---|
|
||||
| **Bundle** | An encrypted export bundle (FIELDWITNESSX1 format) containing chain records |
|
||||
| **STH** | Signed Tree Head — a server's signed commitment to its current Merkle tree state |
|
||||
| **Receipt** | A server-signed proof that a bundle was included in its log at a specific time |
|
||||
| **Inclusion proof** | Merkle path from a leaf (bundle hash) to the tree root |
|
||||
| **Consistency proof** | Proof that an older tree is a prefix of a newer tree (no entries removed) |
|
||||
| **Gossip** | Peer-to-peer exchange of STHs and entries to maintain consistency |
|
||||
|
||||
## 3. Server Merkle Tree
|
||||
|
||||
### 3.1 Structure
|
||||
|
||||
The server maintains a single append-only Merkle tree. Each leaf is the SHA-256 hash
|
||||
of a received bundle's raw bytes:
|
||||
|
||||
```
|
||||
leaf[i] = SHA-256(bundle_bytes[i])
|
||||
```
|
||||
|
||||
Internal nodes follow standard Merkle tree construction:
|
||||
```
|
||||
node = SHA-256(0x01 || left || right) # internal node
|
||||
leaf = SHA-256(0x00 || data) # leaf node (domain separation)
|
||||
```
|
||||
|
||||
Domain separation prefixes (`0x00` for leaves, `0x01` for internal nodes) prevent
|
||||
second-preimage attacks, following CT convention (RFC 6962 §2.1).
|
||||
|
||||
### 3.2 Signed Tree Head (STH)
|
||||
|
||||
After each append (or periodically in batch mode), the server computes and signs a new
|
||||
tree head:
|
||||
|
||||
```cbor
|
||||
{
|
||||
0: tree_size, # uint — number of leaves
|
||||
1: root_hash, # bytes[32] — Merkle tree root
|
||||
2: timestamp, # int — Unix µs, server's clock
|
||||
3: server_id, # text — server identifier (domain or pubkey fingerprint)
|
||||
4: server_pubkey, # bytes[32] — Ed25519 public key
|
||||
5: signature, # bytes[64] — Ed25519(cbor(fields 0-4))
|
||||
}
|
||||
```
|
||||
|
||||
The STH is the server's signed commitment: "My tree has N entries with this root at this
|
||||
time." Clients and peers can verify the signature and use consistency proofs to ensure
|
||||
the tree only grows (never shrinks or forks).
|
||||
|
||||
### 3.3 Inclusion Proof
|
||||
|
||||
Proves a specific bundle is at index `i` in a tree of size `n`:
|
||||
|
||||
```
|
||||
proof = [(sibling_hash, direction), ...]
|
||||
```
|
||||
|
||||
Verification:
|
||||
```
|
||||
current = SHA-256(0x00 || bundle_bytes)
|
||||
for (sibling, direction) in proof:
|
||||
if direction == "L":
|
||||
current = SHA-256(0x01 || sibling || current)
|
||||
else:
|
||||
current = SHA-256(0x01 || current || sibling)
|
||||
assert current == sth.root_hash
|
||||
```
|
||||
|
||||
### 3.4 Consistency Proof
|
||||
|
||||
Proves that tree of size `m` is a prefix of tree of size `n` (where `m < n`). This
|
||||
guarantees the server hasn't removed or reordered entries.
|
||||
|
||||
The proof is a list of intermediate hashes that, combined with the old root, reconstruct
|
||||
the new root. Verification follows RFC 6962 §2.1.2.
|
||||
|
||||
## 4. API Endpoints
|
||||
|
||||
All endpoints use CBOR for request/response bodies. Content-Type: `application/cbor`.
|
||||
|
||||
### 4.1 Submit Bundle
|
||||
|
||||
```
|
||||
POST /v1/submit
|
||||
```
|
||||
|
||||
**Request body**: Raw bundle bytes (application/octet-stream)
|
||||
|
||||
**Processing**:
|
||||
1. Verify magic bytes `b"FIELDWITNESSX1"` and version
|
||||
2. Parse chain summary
|
||||
3. Verify `bundle_sig` against `signer_pubkey`
|
||||
4. Compute `bundle_hash = SHA-256(0x00 || bundle_bytes)`
|
||||
5. Check for duplicate (`bundle_hash` already in tree) — if duplicate, return existing receipt
|
||||
6. Append `bundle_hash` to Merkle tree
|
||||
7. Store bundle bytes (encrypted blob, as-is)
|
||||
8. Generate and sign receipt
|
||||
|
||||
**Response** (CBOR):
|
||||
```cbor
|
||||
{
|
||||
0: bundle_id, # bytes[16] — from chain summary
|
||||
1: bundle_hash, # bytes[32] — leaf hash
|
||||
2: tree_size, # uint — tree size after inclusion
|
||||
3: tree_index, # uint — leaf index in tree
|
||||
4: timestamp, # int — Unix µs, server's reception time
|
||||
5: inclusion_proof, # array of bytes[32] — Merkle path
|
||||
6: sth, # map — current STH (see §3.2)
|
||||
7: server_id, # text — server identifier
|
||||
8: server_pubkey, # bytes[32] — Ed25519 public key
|
||||
9: receipt_sig, # bytes[64] — Ed25519(cbor(fields 0-8))
|
||||
}
|
||||
```
|
||||
|
||||
**Auth**: Federation member token required.
|
||||
|
||||
**Errors**:
|
||||
- `400` — Invalid bundle format, bad signature
|
||||
- `401` — Missing or invalid auth token
|
||||
- `507` — Server storage full
|
||||
|
||||
### 4.2 Get Signed Tree Head
|
||||
|
||||
```
|
||||
GET /v1/sth
|
||||
```
|
||||
|
||||
**Response** (CBOR): STH map (see §3.2)
|
||||
|
||||
**Auth**: Public (no auth required).
|
||||
|
||||
### 4.3 Get Consistency Proof
|
||||
|
||||
```
|
||||
GET /v1/consistency-proof?old={m}&new={n}
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `old` — previous tree size (must be > 0)
|
||||
- `new` — current tree size (must be >= old)
|
||||
|
||||
**Response** (CBOR):
|
||||
```cbor
|
||||
{
|
||||
0: old_size, # uint
|
||||
1: new_size, # uint
|
||||
2: proof, # array of bytes[32]
|
||||
}
|
||||
```
|
||||
|
||||
**Auth**: Public.
|
||||
|
||||
### 4.4 Get Inclusion Proof
|
||||
|
||||
```
|
||||
GET /v1/inclusion-proof?hash={hex}&tree_size={n}
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `hash` — hex-encoded bundle hash (leaf hash)
|
||||
- `tree_size` — tree size for the proof (use current STH tree_size)
|
||||
|
||||
**Response** (CBOR):
|
||||
```cbor
|
||||
{
|
||||
0: tree_index, # uint — leaf index
|
||||
1: tree_size, # uint
|
||||
2: proof, # array of bytes[32]
|
||||
}
|
||||
```
|
||||
|
||||
**Auth**: Public.
|
||||
|
||||
### 4.5 Get Entries
|
||||
|
||||
```
|
||||
GET /v1/entries?start={s}&end={e}
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `start` — first tree index (inclusive)
|
||||
- `end` — last tree index (inclusive)
|
||||
- Maximum range: 1000 entries per request
|
||||
|
||||
**Response** (CBOR):
|
||||
```cbor
|
||||
{
|
||||
0: entries, # array of entry maps (see §4.5.1)
|
||||
}
|
||||
```
|
||||
|
||||
#### 4.5.1 Entry Map
|
||||
|
||||
```cbor
|
||||
{
|
||||
0: tree_index, # uint
|
||||
1: bundle_hash, # bytes[32]
|
||||
2: chain_summary, # CBOR map (from bundle, unencrypted)
|
||||
3: encrypted_blob, # bytes — full FIELDWITNESSX1 bundle
|
||||
4: receipt_ts, # int — Unix µs when received
|
||||
}
|
||||
```
|
||||
|
||||
**Auth**: Federation member token required.
|
||||
|
||||
### 4.6 Audit Summary
|
||||
|
||||
```
|
||||
GET /v1/audit/summary?bundle_id={hex}
|
||||
```
|
||||
|
||||
Returns the chain summary for a specific bundle without the encrypted payload.
|
||||
|
||||
**Response** (CBOR):
|
||||
```cbor
|
||||
{
|
||||
0: bundle_id, # bytes[16]
|
||||
1: chain_summary, # CBOR map (from bundle)
|
||||
2: tree_index, # uint
|
||||
3: receipt_ts, # int
|
||||
4: inclusion_proof, # array of bytes[32] (against current STH)
|
||||
}
|
||||
```
|
||||
|
||||
**Auth**: Public.
|
||||
|
||||
## 5. Permission Tiers
|
||||
|
||||
### 5.1 Public Auditor
|
||||
|
||||
**Access**: Unauthenticated.
|
||||
|
||||
**Endpoints**: `/v1/sth`, `/v1/consistency-proof`, `/v1/inclusion-proof`, `/v1/audit/summary`
|
||||
|
||||
**Can verify**:
|
||||
- The log exists and has a specific size at a specific time
|
||||
- A specific bundle is included in the log at a specific position
|
||||
- The log has not been forked (consistency proofs between STHs)
|
||||
- Chain summary metadata (record count, hash range) for any bundle
|
||||
|
||||
**Cannot see**: Encrypted content, chain IDs, signer identities, raw bundles.
|
||||
|
||||
### 5.2 Federation Member
|
||||
|
||||
**Access**: Bearer token issued by server operator. Tokens are Ed25519-signed
|
||||
credentials binding a public key to a set of permissions.
|
||||
|
||||
```cbor
|
||||
{
|
||||
0: token_id, # bytes[16] — UUID v7
|
||||
1: member_pubkey, # bytes[32] — member's Ed25519 public key
|
||||
2: permissions, # array of text — ["submit", "entries", "gossip"]
|
||||
3: issued_at, # int — Unix µs
|
||||
4: expires_at, # int — Unix µs (0 = no expiry)
|
||||
5: issuer_pubkey, # bytes[32] — server's Ed25519 public key
|
||||
6: signature, # bytes[64] — Ed25519(cbor(fields 0-5))
|
||||
}
|
||||
```
|
||||
|
||||
**Endpoints**: All public endpoints + `/v1/submit`, `/v1/entries`, gossip endpoints.
|
||||
|
||||
**Can see**: Everything a public auditor sees + chain IDs, signer public keys, full
|
||||
encrypted bundles (but not decrypted content).
|
||||
|
||||
### 5.3 Authorized Recipient
|
||||
|
||||
Not enforced server-side. Recipients hold Ed25519 private keys whose corresponding
|
||||
public keys appear in the bundle's recipients array. They can decrypt bundle content
|
||||
locally after retrieving the encrypted blob via the entries endpoint.
|
||||
|
||||
The server has no knowledge of who can or cannot decrypt a given bundle.
|
||||
|
||||
## 6. Gossip Protocol
|
||||
|
||||
### 6.1 Overview
|
||||
|
||||
Federation servers maintain a list of known peers. Periodically (default: every 5 minutes),
|
||||
each server initiates gossip with its peers to:
|
||||
|
||||
1. Exchange STHs — detect if any peer has entries the local server doesn't
|
||||
2. Verify consistency — ensure no peer is presenting a forked log
|
||||
3. Sync entries — pull missing entries from peers that have them
|
||||
|
||||
### 6.2 Gossip Flow
|
||||
|
||||
```
|
||||
Server A Server B
|
||||
│ │
|
||||
│── POST /v1/gossip/sth ──────────────>│ (A sends its STH)
|
||||
│ │
|
||||
│<── response: B's STH ───────────────│ (B responds with its STH)
|
||||
│ │
|
||||
│ (A compares tree sizes) │
|
||||
│ if B.tree_size > A.tree_size: │
|
||||
│ │
|
||||
│── GET /v1/consistency-proof ────────>│ (verify B's tree extends A's)
|
||||
│<── proof ────────────────────────────│
|
||||
│ │
|
||||
│ (verify consistency proof) │
|
||||
│ │
|
||||
│── GET /v1/entries?start=...&end=... >│ (pull missing entries)
|
||||
│<── entries ──────────────────────────│
|
||||
│ │
|
||||
│ (append entries to local tree) │
|
||||
│ (recompute STH) │
|
||||
│ │
|
||||
```
|
||||
|
||||
### 6.3 Gossip Endpoints
|
||||
|
||||
```
|
||||
POST /v1/gossip/sth
|
||||
```
|
||||
|
||||
**Request body** (CBOR): Sender's current STH.
|
||||
|
||||
**Response** (CBOR): Receiver's current STH.
|
||||
|
||||
**Auth**: Federation member token with `"gossip"` permission.
|
||||
|
||||
### 6.4 Fork Detection
|
||||
|
||||
If server A receives an STH from server B where:
|
||||
- `B.tree_size <= A.tree_size` but `B.root_hash != A.root_hash` at the same size
|
||||
|
||||
Then B is presenting a different history. This is a **fork** — a critical security event.
|
||||
The server should:
|
||||
|
||||
1. Log the fork with both STHs as evidence
|
||||
2. Alert the operator
|
||||
3. Continue serving its own tree (do not merge the forked tree)
|
||||
4. Refuse to gossip further with the forked peer until operator resolution
|
||||
|
||||
### 6.5 Convergence
|
||||
|
||||
Under normal operation (no forks), servers converge to identical trees. The convergence
|
||||
time depends on gossip interval and network topology. With a 5-minute interval and full
|
||||
mesh topology among N servers, convergence after a new entry takes at most 5 minutes.
|
||||
|
||||
## 7. Receipts
|
||||
|
||||
### 7.1 Purpose
|
||||
|
||||
A receipt is the federation's proof that a bundle was received and included in the log
|
||||
at a specific time. It is the critical artifact that closes the timestamp gap: the
|
||||
offline device's claimed timestamp + the federation receipt = practical proof of timing.
|
||||
|
||||
### 7.2 Receipt Format
|
||||
|
||||
```cbor
|
||||
{
|
||||
0: bundle_id, # bytes[16] — from chain summary
|
||||
1: bundle_hash, # bytes[32] — leaf hash in server's tree
|
||||
2: tree_size, # uint — tree size at inclusion
|
||||
3: tree_index, # uint — leaf position
|
||||
4: timestamp, # int — Unix µs, server's clock
|
||||
5: inclusion_proof, # array of bytes[32] — Merkle path
|
||||
6: sth, # map — STH at time of inclusion
|
||||
7: server_id, # text — server identifier
|
||||
8: server_pubkey, # bytes[32] — Ed25519 public key
|
||||
9: receipt_sig, # bytes[64] — Ed25519(cbor(fields 0-8))
|
||||
}
|
||||
```
|
||||
|
||||
### 7.3 Receipt Verification
|
||||
|
||||
To verify a receipt:
|
||||
|
||||
1. `Ed25519_Verify(server_pubkey, receipt_sig, cbor(fields 0-8))` — receipt is authentic
|
||||
2. Verify `inclusion_proof` against `sth.root_hash` with `bundle_hash` at `tree_index`
|
||||
3. Verify `sth.signature` — the STH itself is authentic
|
||||
4. `sth.tree_size >= tree_size` — STH covers the inclusion
|
||||
5. `sth.timestamp >= timestamp` — STH is at or after receipt time
|
||||
|
||||
### 7.4 Receipt Lifecycle
|
||||
|
||||
```
|
||||
1. Loader submits bundle to federation server
|
||||
2. Server issues receipt in submit response
|
||||
3. Loader stores receipt locally (receipts/ directory)
|
||||
4. Loader exports receipts to USB (CBOR file)
|
||||
5. Offline device imports receipts
|
||||
6. Receipt is stored alongside chain records as proof of federation timestamp
|
||||
```
|
||||
|
||||
### 7.5 Multi-Server Receipts
|
||||
|
||||
A bundle submitted to N servers produces N independent receipts. Each receipt is from a
|
||||
different server with a different timestamp and Merkle tree position. Multiple receipts
|
||||
strengthen the timestamp claim — an adversary would need to compromise all N servers to
|
||||
suppress evidence.
|
||||
|
||||
## 8. Storage Tiers
|
||||
|
||||
Federation servers manage bundle storage across three tiers based on age:
|
||||
|
||||
### 8.1 Hot Tier (0-30 days)
|
||||
|
||||
- **Format**: Individual files, one per bundle
|
||||
- **Location**: `data/hot/{tree_index}.bundle`
|
||||
- **Access**: Direct file read, O(1)
|
||||
- **Purpose**: Fast access for recent entries, active gossip sync
|
||||
|
||||
### 8.2 Warm Tier (30-365 days)
|
||||
|
||||
- **Format**: Zstd-compressed segments, 1000 bundles per segment
|
||||
- **Location**: `data/warm/segment-{start}-{end}.zst`
|
||||
- **Access**: Decompress segment, extract entry
|
||||
- **Compression**: Zstd level 3 (fast compression, moderate ratio)
|
||||
- **Purpose**: Reduced storage for medium-term retention
|
||||
|
||||
### 8.3 Cold Tier (>1 year)
|
||||
|
||||
- **Format**: Zstd-compressed segments, maximum compression
|
||||
- **Location**: `data/cold/segment-{start}-{end}.zst`
|
||||
- **Access**: Decompress segment, extract entry
|
||||
- **Compression**: Zstd level 19 (slow compression, best ratio)
|
||||
- **Purpose**: Archival storage, rarely accessed
|
||||
|
||||
### 8.4 Tier Promotion
|
||||
|
||||
A background compaction process runs periodically (default: every 24 hours):
|
||||
|
||||
1. Identify hot entries older than 30 days
|
||||
2. Group into segments of 1000
|
||||
3. Compress and write to warm tier
|
||||
4. Delete hot files
|
||||
5. Repeat for warm → cold at 365 days
|
||||
|
||||
### 8.5 Merkle Tree Preservation
|
||||
|
||||
The Merkle tree is independent of storage tiers. Leaf hashes and the tree structure
|
||||
are maintained in a separate data structure (compact tree format, stored in SQLite or
|
||||
flat file). Moving bundles between storage tiers does not affect the tree.
|
||||
|
||||
Inclusion proofs and consistency proofs remain valid across tier promotions — they
|
||||
reference the tree, not the storage location.
|
||||
|
||||
### 8.6 Metadata Database
|
||||
|
||||
SQLite database tracking all bundles:
|
||||
|
||||
```sql
|
||||
CREATE TABLE bundles (
|
||||
tree_index INTEGER PRIMARY KEY,
|
||||
bundle_id BLOB NOT NULL, -- UUID v7
|
||||
bundle_hash BLOB NOT NULL, -- leaf hash
|
||||
chain_id BLOB NOT NULL, -- source chain ID
|
||||
signer_pubkey BLOB NOT NULL, -- Ed25519 public key
|
||||
record_count INTEGER NOT NULL, -- records in bundle
|
||||
range_start INTEGER NOT NULL, -- first chain index
|
||||
range_end INTEGER NOT NULL, -- last chain index
|
||||
receipt_ts INTEGER NOT NULL, -- Unix µs reception time
|
||||
storage_tier TEXT NOT NULL DEFAULT 'hot', -- 'hot', 'warm', 'cold'
|
||||
storage_key TEXT NOT NULL, -- file path or segment reference
|
||||
created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
|
||||
);
|
||||
|
||||
CREATE INDEX idx_bundles_bundle_id ON bundles(bundle_id);
|
||||
CREATE INDEX idx_bundles_chain_id ON bundles(chain_id);
|
||||
CREATE INDEX idx_bundles_bundle_hash ON bundles(bundle_hash);
|
||||
CREATE INDEX idx_bundles_receipt_ts ON bundles(receipt_ts);
|
||||
```
|
||||
|
||||
## 9. Server Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"server_id": "my-server.example.org",
|
||||
"host": "0.0.0.0",
|
||||
"port": 8443,
|
||||
"data_dir": "/var/lib/fieldwitness-federation",
|
||||
"identity_key_path": "/etc/fieldwitness-federation/identity/private.pem",
|
||||
"peers": [
|
||||
{
|
||||
"url": "https://peer1.example.org:8443",
|
||||
"pubkey_hex": "abc123...",
|
||||
"name": "Peer One"
|
||||
}
|
||||
],
|
||||
"gossip_interval_seconds": 300,
|
||||
"hot_retention_days": 30,
|
||||
"warm_retention_days": 365,
|
||||
"compaction_interval_hours": 24,
|
||||
"max_bundle_size_bytes": 10485760,
|
||||
"max_entries_per_request": 1000,
|
||||
"member_tokens": [
|
||||
{
|
||||
"name": "loader-1",
|
||||
"pubkey_hex": "def456...",
|
||||
"permissions": ["submit", "entries"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 10. Error Codes
|
||||
|
||||
| HTTP Status | CBOR Error Code | Description |
|
||||
|---|---|---|
|
||||
| 400 | `"invalid_bundle"` | Bundle format invalid or signature verification failed |
|
||||
| 400 | `"invalid_range"` | Requested entry range is invalid |
|
||||
| 401 | `"unauthorized"` | Missing or invalid auth token |
|
||||
| 403 | `"forbidden"` | Token lacks required permission |
|
||||
| 404 | `"not_found"` | Bundle or entry not found |
|
||||
| 409 | `"duplicate"` | Bundle already in log (returns existing receipt) |
|
||||
| 413 | `"bundle_too_large"` | Bundle exceeds `max_bundle_size_bytes` |
|
||||
| 507 | `"storage_full"` | Server cannot accept new entries |
|
||||
|
||||
Error response format:
|
||||
```cbor
|
||||
{
|
||||
0: error_code, # text
|
||||
1: message, # text — human-readable description
|
||||
2: details, # map — optional additional context
|
||||
}
|
||||
```
|
||||
|
||||
## 11. Security Considerations
|
||||
|
||||
### 11.1 Server Compromise
|
||||
|
||||
A compromised server can:
|
||||
- Read bundle metadata (chain IDs, signer pubkeys, timestamps) — **expected at member tier**
|
||||
- Withhold entries from gossip — **detectable**: other servers will see inconsistent tree sizes
|
||||
- Present a forked tree — **detectable**: consistency proofs will fail
|
||||
- Issue false receipts — **detectable**: receipt's inclusion proof won't verify against other servers' STHs
|
||||
|
||||
A compromised server **cannot**:
|
||||
- Read attestation content (encrypted with recipient keys)
|
||||
- Forge attestation signatures (requires Ed25519 private key)
|
||||
- Modify bundle contents (GCM authentication would fail)
|
||||
- Reorder or remove entries from other servers' trees
|
||||
|
||||
### 11.2 Transport Security
|
||||
|
||||
All server-to-server and client-to-server communication should use TLS 1.3. The
|
||||
federation protocol provides its own authentication (Ed25519 signatures on STHs and
|
||||
receipts), but TLS prevents network-level attacks.
|
||||
|
||||
### 11.3 Clock Reliability
|
||||
|
||||
Federation server clocks should be synchronized via NTP. Receipt timestamps are only as
|
||||
reliable as the server's clock. Deploying servers across multiple time zones and operators
|
||||
provides cross-checks — wildly divergent receipt timestamps for the same bundle indicate
|
||||
clock problems or compromise.
|
||||
254
docs/architecture/federation.md
Normal file
254
docs/architecture/federation.md
Normal file
@ -0,0 +1,254 @@
|
||||
# Federated Attestation System — Architecture Overview
|
||||
|
||||
**Status**: Design
|
||||
**Version**: 0.3.0
|
||||
**Last updated**: 2026-04-01
|
||||
|
||||
## 1. Problem Statement
|
||||
|
||||
FieldWitness operates offline-first: devices create Ed25519-signed attestations without network
|
||||
access. This creates two fundamental challenges:
|
||||
|
||||
1. **Timestamp credibility** — An offline device's clock is untrusted. An adversary with
|
||||
physical access could backdate or postdate attestations.
|
||||
2. **Distribution** — Attestations trapped on a single device are vulnerable to seizure,
|
||||
destruction, or loss. They must be replicated to survive.
|
||||
|
||||
The system must solve both problems while preserving the offline-first constraint and
|
||||
protecting content confidentiality even from the distribution infrastructure.
|
||||
|
||||
## 2. Threat Model
|
||||
|
||||
### Adversaries
|
||||
|
||||
| Adversary | Capabilities | Goal |
|
||||
|---|---|---|
|
||||
| State actor | Physical device access, network surveillance, legal compulsion of server operators | Suppress or discredit attestations |
|
||||
| Insider threat | Access to one federation server | Fork the log, selectively omit entries, or read content |
|
||||
| Device thief | Physical access to offline device | Fabricate or backdate attestations |
|
||||
|
||||
### Security Properties
|
||||
|
||||
| Property | Guarantee | Mechanism |
|
||||
|---|---|---|
|
||||
| **Integrity** | Attestations cannot be modified after creation | Ed25519 signatures + hash chain |
|
||||
| **Ordering** | Attestations cannot be reordered or inserted | Hash chain (each record includes hash of previous) |
|
||||
| **Existence proof** | Attestation existed at or before time T | Federation receipt (server-signed timestamp) |
|
||||
| **Confidentiality** | Content is hidden from infrastructure | Envelope encryption; servers store encrypted blobs |
|
||||
| **Fork detection** | Log tampering is detectable | Merkle tree + consistency proofs (CT model) |
|
||||
| **Availability** | Attestations survive device loss | Replication across federation servers via gossip |
|
||||
|
||||
### Non-Goals
|
||||
|
||||
- **Proving exact creation time** — Impossible without a trusted time source. We prove
|
||||
ordering (hash chain) and existence-before (federation receipt). The gap between
|
||||
claimed time and receipt time is the trust window.
|
||||
- **Anonymity of attestors** — Federation members can see signer public keys. For anonymity,
|
||||
use a dedicated identity per context.
|
||||
- **Preventing denial of service** — Federation servers are assumed cooperative. Byzantine
|
||||
fault tolerance is out of scope for v1.
|
||||
|
||||
## 3. System Architecture
|
||||
|
||||
```
|
||||
OFFLINE DEVICE AIR GAP INTERNET
|
||||
────────────── ─────── ────────
|
||||
|
||||
┌──────────┐ ┌──────────────┐ ┌──────────┐ USB/SD ┌──────────┐ ┌────────────┐
|
||||
│ Attest │────>│ Hash Chain │────>│ Export │───────────────>│ Loader │────>│ Federation │
|
||||
│ Attest │ │ (Layer 1) │ │ Bundle │ │ (App) │ │ Server │
|
||||
└──────────┘ └──────────────┘ │ (Layer 2)│ └────┬─────┘ └─────┬──────┘
|
||||
└──────────┘ │ │
|
||||
│ │ ┌─────────┐ │
|
||||
Optional: │<───│ Receipt │<──┘
|
||||
DCT embed │ └─────────┘
|
||||
in JPEG │
|
||||
│ USB carry-back
|
||||
┌────v─────┐ │
|
||||
│ Stego │ ┌────v─────┐
|
||||
│ Image │ │ Offline │
|
||||
└──────────┘ │ Device │
|
||||
│ (receipt │
|
||||
│ stored) │
|
||||
└──────────┘
|
||||
```
|
||||
|
||||
### Layer 1: Hash-Chained Attestation Records (Local)
|
||||
|
||||
Each attestation is wrapped in a chain record that includes:
|
||||
- A hash of the previous record (tamper-evident ordering)
|
||||
- Entropy witnesses (system uptime, kernel state) that make timestamp fabrication expensive
|
||||
- An Ed25519 signature over the entire record
|
||||
|
||||
The chain lives on the offline device at `~/.fwmetadata/chain/`. It wraps existing Attest
|
||||
attestation records — the Attest record's bytes become the `content_hash` input.
|
||||
|
||||
**See**: [chain-format.md](chain-format.md)
|
||||
|
||||
### Layer 2: Encrypted Export Bundles
|
||||
|
||||
A range of chain records is packaged into a portable bundle:
|
||||
1. Records serialized as CBOR, compressed with zstd
|
||||
2. Encrypted with AES-256-GCM using a random data encryption key (DEK)
|
||||
3. DEK wrapped per-recipient via X25519 ECDH (derived from Ed25519 identities)
|
||||
4. An unencrypted `chain_summary` (record count, hash range, Merkle root, signature) allows
|
||||
auditing without decryption
|
||||
|
||||
Bundles can optionally be embedded in JPEG images via stego's DCT steganography,
|
||||
making them indistinguishable from normal photos on a USB stick.
|
||||
|
||||
**See**: [export-bundle.md](export-bundle.md)
|
||||
|
||||
### Layer 3: Federated Append-Only Log
|
||||
|
||||
Federation servers are "blind notaries" inspired by Certificate Transparency (RFC 6962):
|
||||
- They receive encrypted bundles, verify the chain summary signature, and append to a
|
||||
Merkle tree
|
||||
- They issue signed receipts with a federation timestamp (proof of existence)
|
||||
- They gossip Signed Tree Heads (STH) with peers to ensure consistency
|
||||
- They never decrypt content — they operate at the "federation member" permission tier
|
||||
|
||||
**See**: [federation-protocol.md](federation-protocol.md)
|
||||
|
||||
### The Loader (Air-Gap Bridge)
|
||||
|
||||
A separate application that runs on an internet-connected machine:
|
||||
1. Receives a bundle (from USB) or extracts one from a steganographic image
|
||||
2. Validates the bundle signature and chain summary
|
||||
3. Pushes to configured federation servers
|
||||
4. Collects signed receipts
|
||||
5. Receipts are carried back to the offline device on the next USB round-trip
|
||||
|
||||
The loader never needs signing keys — bundles are already signed. It is a transport mechanism.
|
||||
|
||||
## 4. Key Domains
|
||||
|
||||
FieldWitness maintains strict separation between two cryptographic domains:
|
||||
|
||||
| Domain | Algorithm | Purpose | Key Location |
|
||||
|---|---|---|---|
|
||||
| **Signing** | Ed25519 | Attestation signatures, chain records, bundle summaries | `~/.fwmetadata/identity/` |
|
||||
| **Encryption** | X25519 + AES-256-GCM | Bundle payload encryption (envelope) | Derived from Ed25519 via birational map |
|
||||
| **Steganography** | AES-256-GCM (from factors) | Stego channel encryption | `~/.fwmetadata/stego/channel.key` |
|
||||
|
||||
The signing and encryption domains share a key lineage (Ed25519 → X25519 derivation) but
|
||||
serve different purposes. The steganography domain remains fully independent — it protects
|
||||
the stego carrier, not the attestation content.
|
||||
|
||||
### Private Key Storage Policy
|
||||
|
||||
The Ed25519 private key is stored **unencrypted** on disk (protected by 0o600 file
|
||||
permissions). This is a deliberate design decision:
|
||||
|
||||
- The killswitch (secure deletion) is the primary defense for at-risk users, not key
|
||||
encryption. A password-protected key would require prompting on every attestation and
|
||||
chain operation, which is unworkable in field conditions.
|
||||
- The `password` parameter on `generate_identity()` exists for interoperability but is
|
||||
not used by default. Chain operations (`_wrap_in_chain`, `backfill`) assume unencrypted keys.
|
||||
- If the device is seized, the killswitch destroys key material. If the killswitch is not
|
||||
triggered, the adversary has physical access and can defeat key encryption via cold boot,
|
||||
memory forensics, or compelled disclosure.
|
||||
|
||||
## 5. Permission Model
|
||||
|
||||
Three tiers control who can see what:
|
||||
|
||||
| Tier | Sees | Can Verify | Typical Actor |
|
||||
|---|---|---|---|
|
||||
| **Public auditor** | Chain summaries, Merkle proofs, receipt timestamps | Existence, ordering, no forks | Anyone with server URL |
|
||||
| **Federation member** | + chain IDs, signer public keys | + who attested, chain continuity | Peer servers, authorized monitors |
|
||||
| **Authorized recipient** | + decrypted attestation content | Everything | Designated individuals with DEK access |
|
||||
|
||||
Federation servers themselves operate at the **federation member** tier. They can verify
|
||||
chain integrity and detect forks, but they cannot read attestation content.
|
||||
|
||||
## 6. Timestamp Credibility
|
||||
|
||||
Since the device is offline, claimed timestamps are inherently untrusted. The system
|
||||
provides layered evidence:
|
||||
|
||||
1. **Hash chain ordering** — Records are provably ordered. Even if timestamps are wrong,
|
||||
the sequence is authentic.
|
||||
2. **Entropy witnesses** — Each record includes system uptime, kernel entropy pool state,
|
||||
and boot ID. Fabricating a convincing set of witnesses for a backdated record requires
|
||||
simulating the full system state at the claimed time.
|
||||
3. **Federation receipt** — When the bundle reaches a federation server, the server signs
|
||||
a receipt with its own clock. This proves the chain existed at or before the receipt time.
|
||||
4. **Cross-device corroboration** — If two independent devices attest overlapping events,
|
||||
their independent chains corroborate each other's timeline.
|
||||
|
||||
The trust window is: `receipt_timestamp - claimed_timestamp`. A smaller window means
|
||||
more credible timestamps. Frequent USB sync trips shrink the window.
|
||||
|
||||
## 7. Data Lifecycle
|
||||
|
||||
```
|
||||
1. CREATE Offline device: attest file → sign → append to chain
|
||||
2. EXPORT Offline device: select range → compress → encrypt → bundle (→ optional stego embed)
|
||||
3. TRANSFER Physical media: USB/SD card carries bundle across air gap
|
||||
4. LOAD Internet machine: validate bundle → push to federation
|
||||
5. RECEIPT Federation server: verify → append to Merkle tree → sign receipt
|
||||
6. RETURN Physical media: receipt carried back to offline device
|
||||
7. REPLICATE Federation: servers gossip entries and STHs to each other
|
||||
8. AUDIT Anyone: verify Merkle proofs, check consistency across servers
|
||||
```
|
||||
|
||||
## 8. Failure Modes
|
||||
|
||||
| Failure | Impact | Mitigation |
|
||||
|---|---|---|
|
||||
| Device lost/seized | Local chain lost | Bundles already sent to federation survive; regular exports reduce data loss window |
|
||||
| USB intercepted | Adversary gets encrypted bundle (or stego image) | Encryption protects content; stego hides existence |
|
||||
| Federation server compromised | Adversary reads metadata (chain IDs, pubkeys, timestamps) | Content remains encrypted; other servers detect log fork via consistency proofs |
|
||||
| All federation servers down | No new receipts | Bundles queue on loader; chain integrity unaffected; retry when servers recover |
|
||||
| Clock manipulation on device | Timestamps unreliable | Entropy witnesses increase fabrication cost; federation receipt provides external anchor |
|
||||
|
||||
## 9. Dependencies
|
||||
|
||||
| Package | Version | Purpose |
|
||||
|---|---|---|
|
||||
| `cbor2` | >=5.6.0 | Canonical CBOR serialization (RFC 8949) |
|
||||
| `uuid-utils` | >=0.9.0 | UUID v7 generation (time-ordered) |
|
||||
| `zstandard` | >=0.22.0 | Zstd compression for bundles and storage tiers |
|
||||
| `cryptography` | >=41.0.0 | Ed25519, X25519, AES-256-GCM, HKDF, SHA-256 (already a dependency) |
|
||||
|
||||
## 10. File Layout
|
||||
|
||||
```
|
||||
src/fieldwitness/federation/
|
||||
__init__.py
|
||||
models.py Chain record and state dataclasses
|
||||
serialization.py CBOR canonical encoding
|
||||
entropy.py System entropy collection
|
||||
chain.py ChainStore — local append-only chain
|
||||
merkle.py Merkle tree implementation
|
||||
export.py Export bundle creation/parsing/decryption
|
||||
x25519.py Ed25519→X25519 derivation, envelope encryption
|
||||
stego_bundle.py Steganographic bundle embedding
|
||||
protocol.py Shared federation types
|
||||
loader/
|
||||
__init__.py
|
||||
loader.py Air-gap bridge application
|
||||
config.py Loader configuration
|
||||
receipt.py Receipt handling
|
||||
client.py Federation server HTTP client
|
||||
server/
|
||||
__init__.py
|
||||
app.py Federation server Flask app
|
||||
tree.py CT-style Merkle tree
|
||||
storage.py Tiered bundle storage
|
||||
gossip.py Peer synchronization
|
||||
permissions.py Access control
|
||||
config.py Server configuration
|
||||
|
||||
~/.fwmetadata/
|
||||
chain/ Local hash chain
|
||||
chain.bin Append-only record log
|
||||
state.cbor Chain state checkpoint
|
||||
exports/ Generated export bundles
|
||||
loader/ Loader state
|
||||
config.json Server list and settings
|
||||
receipts/ Federation receipts
|
||||
federation/ Federation server data (when running as server)
|
||||
servers.json Known peer servers
|
||||
```
|
||||
1485
docs/deployment.md
Normal file
1485
docs/deployment.md
Normal file
File diff suppressed because it is too large
Load Diff
283
docs/evidence-guide.md
Normal file
283
docs/evidence-guide.md
Normal file
@ -0,0 +1,283 @@
|
||||
# Evidence Guide
|
||||
|
||||
**Audience**: Journalists, investigators, and legal teams who need to create, export, and
|
||||
verify evidence packages from FieldWitness.
|
||||
|
||||
**Prerequisites**: A running FieldWitness instance with at least one attested image or file.
|
||||
Familiarity with basic CLI commands.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
FieldWitness provides three mechanisms for preserving and sharing evidence outside a running
|
||||
instance: evidence packages (for handing specific files to third parties), cold archives
|
||||
(full-state preservation for 10+ year horizons), and selective disclosure (proving specific
|
||||
records without revealing the rest of the chain). All three include standalone verification
|
||||
scripts that require no FieldWitness installation.
|
||||
|
||||
---
|
||||
|
||||
## Evidence Packages
|
||||
|
||||
An evidence package is a self-contained ZIP that bundles everything needed for independent
|
||||
verification of specific attested images or files.
|
||||
|
||||
### What is inside an evidence package
|
||||
|
||||
| File | Purpose |
|
||||
|---|---|
|
||||
| `images/` | Original image files |
|
||||
| `manifest.json` | Attestation records, chain data, and image hashes |
|
||||
| `public_key.pem` | Signer's Ed25519 public key |
|
||||
| `verify.py` | Standalone verification script |
|
||||
| `README.txt` | Human-readable instructions |
|
||||
|
||||
### Creating an evidence package
|
||||
|
||||
```bash
|
||||
# Package specific images with their attestation records
|
||||
$ fieldwitness evidence export photo1.jpg photo2.jpg --output evidence_package.zip
|
||||
|
||||
# Filter by investigation tag
|
||||
$ fieldwitness evidence export photo1.jpg --investigation "case-2026-001" \
|
||||
--output evidence_case001.zip
|
||||
```
|
||||
|
||||
### When to create evidence packages
|
||||
|
||||
- Before handing evidence to a legal team or court
|
||||
- When sharing with a partner organization that does not run FieldWitness
|
||||
- Before crossing a hostile checkpoint (create the package, send it to a trusted party,
|
||||
then activate the killswitch if needed)
|
||||
- When an investigation is complete and files must be archived independently
|
||||
|
||||
### Verifying an evidence package
|
||||
|
||||
The recipient does not need FieldWitness. They need only Python 3.11+ and the `cryptography`
|
||||
pip package:
|
||||
|
||||
```bash
|
||||
$ python3 -m venv verify-env
|
||||
$ source verify-env/bin/activate
|
||||
$ pip install cryptography
|
||||
$ cd evidence_package/
|
||||
$ python verify.py
|
||||
```
|
||||
|
||||
The verification script checks:
|
||||
|
||||
1. Image SHA-256 hashes match the attestation records in `manifest.json`
|
||||
2. Chain hash linkage is unbroken (each record's `prev_hash` matches the previous record)
|
||||
3. Ed25519 signatures are valid (if `public_key.pem` is included)
|
||||
|
||||
---
|
||||
|
||||
## Cold Archives
|
||||
|
||||
A cold archive is a full snapshot of the entire FieldWitness evidence store, designed for
|
||||
long-term preservation aligned with OAIS (ISO 14721). It is self-describing and includes
|
||||
everything needed to verify the evidence decades later, even if FieldWitness no longer exists.
|
||||
|
||||
### What is inside a cold archive
|
||||
|
||||
| File | Purpose |
|
||||
|---|---|
|
||||
| `chain/chain.bin` | Raw append-only hash chain binary |
|
||||
| `chain/state.cbor` | Chain state checkpoint |
|
||||
| `chain/anchors/` | External timestamp anchor files (RFC 3161 tokens, manual anchors) |
|
||||
| `attestations/log.bin` | Full attest attestation log |
|
||||
| `attestations/index/` | LMDB index files |
|
||||
| `keys/public.pem` | Signer's Ed25519 public key |
|
||||
| `keys/bundle.enc` | Encrypted key bundle (optional, password-protected) |
|
||||
| `keys/trusted/` | Trusted collaborator public keys |
|
||||
| `manifest.json` | Archive metadata and SHA-256 integrity hashes |
|
||||
| `verify.py` | Standalone verification script |
|
||||
| `ALGORITHMS.txt` | Cryptographic algorithm documentation |
|
||||
| `README.txt` | Human-readable description |
|
||||
|
||||
### Creating a cold archive
|
||||
|
||||
```bash
|
||||
# Full archive without encrypted key bundle
|
||||
$ fieldwitness archive export --output archive_20260401.zip
|
||||
|
||||
# Include encrypted key bundle (will prompt for passphrase)
|
||||
$ fieldwitness archive export --include-keys --output archive_20260401.zip
|
||||
```
|
||||
|
||||
> **Warning:** If you include the encrypted key bundle, store the passphrase separately
|
||||
> from the archive media. Write it on paper and keep it in a different physical location.
|
||||
|
||||
### When to create cold archives
|
||||
|
||||
- At regular intervals (weekly or monthly) as part of your backup strategy
|
||||
- Before key rotation (locks the existing chain state in the archive)
|
||||
- Before traveling with the device
|
||||
- Before anticipated risk events (raids, border crossings, legal proceedings)
|
||||
- When archiving a completed investigation
|
||||
|
||||
### Restoring from a cold archive
|
||||
|
||||
On a fresh FieldWitness instance:
|
||||
|
||||
```bash
|
||||
$ fieldwitness init
|
||||
$ fieldwitness archive import archive_20260401.zip
|
||||
```
|
||||
|
||||
### Long-term archival best practices
|
||||
|
||||
1. Store archives on at least two separate physical media (USB drives, optical discs)
|
||||
2. Keep one copy offsite (safe deposit box, trusted third party in a different jurisdiction)
|
||||
3. Include the encrypted key bundle in the archive with a strong passphrase
|
||||
4. Periodically verify archive integrity: unzip and run `python verify.py`
|
||||
5. The `ALGORITHMS.txt` file documents every algorithm and parameter used, so a verifier
|
||||
can be written from scratch even if FieldWitness no longer exists
|
||||
|
||||
### The ALGORITHMS.txt file
|
||||
|
||||
This file documents every cryptographic algorithm, parameter, and format used:
|
||||
|
||||
- **Signing**: Ed25519 (RFC 8032) -- 32-byte public keys, 64-byte signatures
|
||||
- **Hashing**: SHA-256 for content and chain linkage; pHash and dHash for perceptual image matching
|
||||
- **Encryption (key bundle)**: AES-256-GCM with Argon2id key derivation (time_cost=4, memory_cost=256MB, parallelism=4)
|
||||
- **Chain format**: Append-only binary log with uint32 BE length prefixes and CBOR (RFC 8949) records
|
||||
- **Attestation log**: Attest binary log format
|
||||
|
||||
---
|
||||
|
||||
## Selective Disclosure
|
||||
|
||||
Selective disclosure produces a verifiable proof for specific chain records while keeping
|
||||
others redacted. Designed for legal discovery, court orders, and FOIA responses.
|
||||
|
||||
### How it works
|
||||
|
||||
Selected records are included in full (content hash, content type, signature, metadata,
|
||||
signer public key). Non-selected records appear only as their record hash and chain index.
|
||||
The complete hash chain is included so a third party can verify that the disclosed records
|
||||
are part of an unbroken chain without seeing the contents of other records.
|
||||
|
||||
### Creating a selective disclosure
|
||||
|
||||
```bash
|
||||
# Disclose records at chain indices 5, 12, and 47
|
||||
$ fieldwitness chain disclose --indices 5,12,47 --output disclosure.json
|
||||
```
|
||||
|
||||
### Disclosure output format
|
||||
|
||||
```json
|
||||
{
|
||||
"proof_version": "1",
|
||||
"chain_state": {
|
||||
"chain_id": "a1b2c3...",
|
||||
"head_index": 100,
|
||||
"record_count": 101
|
||||
},
|
||||
"selected_records": [
|
||||
{
|
||||
"chain_index": 5,
|
||||
"content_hash": "...",
|
||||
"content_type": "attest/attestation-v1",
|
||||
"prev_hash": "...",
|
||||
"record_hash": "...",
|
||||
"signer_pubkey": "...",
|
||||
"signature": "...",
|
||||
"claimed_ts": 1711900000000000,
|
||||
"metadata": {}
|
||||
}
|
||||
],
|
||||
"redacted_count": 98,
|
||||
"hash_chain": [
|
||||
{"chain_index": 0, "record_hash": "...", "prev_hash": "..."},
|
||||
{"chain_index": 1, "record_hash": "...", "prev_hash": "..."}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Verifying a selective disclosure
|
||||
|
||||
A third party can verify:
|
||||
|
||||
1. **Chain linkage**: each entry in `hash_chain` has a `prev_hash` that matches the
|
||||
`record_hash` of the previous entry
|
||||
2. **Selected record integrity**: each selected record's `record_hash` matches its position
|
||||
in the hash chain
|
||||
3. **Signature validity**: each selected record's Ed25519 signature is valid for its
|
||||
canonical byte representation
|
||||
|
||||
### When to use selective disclosure vs. evidence packages
|
||||
|
||||
| Need | Use |
|
||||
|---|---|
|
||||
| Hand specific images to a lawyer | Evidence package |
|
||||
| Respond to a court order for specific records | Selective disclosure |
|
||||
| Full-state backup for long-term preservation | Cold archive |
|
||||
| Share attestations with a partner organization | Federation bundle |
|
||||
|
||||
---
|
||||
|
||||
## Chain Anchoring for Evidence
|
||||
|
||||
External timestamp anchoring strengthens evidence by proving that the chain existed before
|
||||
a given time. A single anchor for the chain head implicitly timestamps every record that
|
||||
preceded it, because the chain is append-only with hash linkage.
|
||||
|
||||
### RFC 3161 automated anchoring
|
||||
|
||||
If the device has internet access (even temporarily):
|
||||
|
||||
```bash
|
||||
$ fieldwitness chain anchor --tsa https://freetsa.org/tsr
|
||||
```
|
||||
|
||||
This sends the chain head digest to a Timestamping Authority, receives a signed timestamp
|
||||
token, and saves both as a JSON file under `~/.fwmetadata/chain/anchors/`. The TSA token is a
|
||||
cryptographically signed proof from a third party that the hash existed at the stated time.
|
||||
This is legally stronger than a self-asserted timestamp.
|
||||
|
||||
### Manual anchoring (airgapped)
|
||||
|
||||
Without `--tsa`:
|
||||
|
||||
```bash
|
||||
$ fieldwitness chain anchor
|
||||
```
|
||||
|
||||
This prints a compact text block. Publish it to any external witness:
|
||||
|
||||
- Tweet or public social media post (timestamped by the platform)
|
||||
- Email to a trusted third party (timestamped by the mail server)
|
||||
- Newspaper classified advertisement
|
||||
- Bitcoin OP_RETURN transaction
|
||||
- Notarized document
|
||||
|
||||
### Anchoring strategy for legal proceedings
|
||||
|
||||
1. Anchor the chain before disclosing evidence to any party
|
||||
2. Anchor at regular intervals (daily or weekly) to establish a timeline
|
||||
3. Anchor before and after major events in an investigation
|
||||
4. Anchor before key rotation
|
||||
5. Save anchor files alongside key backups on separate physical media
|
||||
|
||||
---
|
||||
|
||||
## Legal Discovery Workflow
|
||||
|
||||
For responding to a court order, subpoena, or legal discovery request:
|
||||
|
||||
1. **Selective disclosure** (`fieldwitness chain disclose`) when the request specifies particular
|
||||
records and you must not reveal the full chain
|
||||
2. **Evidence package** when the request requires original images with verification
|
||||
capability
|
||||
3. **Cold archive** when full preservation is required (e.g., an entire investigation)
|
||||
|
||||
All three formats include standalone verification scripts so the receiving party does not
|
||||
need FieldWitness installed. The verification scripts require only Python 3.11+ and the
|
||||
`cryptography` pip package.
|
||||
|
||||
> **Note:** Consult with legal counsel before producing evidence from FieldWitness. The selective
|
||||
> disclosure mechanism is designed to support legal privilege and proportionality, but its
|
||||
> application depends on your jurisdiction and the specific legal context.
|
||||
317
docs/federation.md
Normal file
317
docs/federation.md
Normal file
@ -0,0 +1,317 @@
|
||||
# Federation Guide
|
||||
|
||||
**Audience**: System administrators and technical leads setting up cross-organization
|
||||
attestation sync between FieldWitness instances.
|
||||
|
||||
**Prerequisites**: A running FieldWitness instance (Tier 2 org server or Tier 3 relay), familiarity
|
||||
with the CLI, and trusted public keys from partner organizations.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
FieldWitness federation synchronizes attestation records between organizations using a gossip
|
||||
protocol. Nodes periodically exchange Merkle roots, detect divergence, and fetch missing
|
||||
records. The system is eventually consistent with no central coordinator, no leader
|
||||
election, and no consensus protocol -- just append-only logs that converge.
|
||||
|
||||
Federation operates at two levels:
|
||||
|
||||
1. **Offline bundles** -- JSON export/import via sneakernet (USB drive). Works on all tiers
|
||||
including fully airgapped Tier 1 field devices.
|
||||
2. **Live gossip** -- HTTP-based periodic sync between Tier 2 org servers and Tier 3
|
||||
federation relays. Requires the `federation` extra (`pip install fieldwitness[federation]`).
|
||||
|
||||
> **Warning:** Federation shares attestation records (image hashes, Ed25519 signatures,
|
||||
> timestamps, and signer public keys). It never shares encryption keys, plaintext messages,
|
||||
> original images, or steganographic payloads.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Tier 1: Field Device Tier 2: Org Server A Tier 3: Relay (Iceland)
|
||||
(Bootable USB) (Docker / mini PC) (VPS, zero key knowledge)
|
||||
| |
|
||||
USB sneakernet ------> Port 5000 (Web UI) |
|
||||
Port 8000 (Federation API) <-----> Port 8000
|
||||
| |
|
||||
Tier 2: Org Server B <------------>
|
||||
(Docker / mini PC)
|
||||
```
|
||||
|
||||
Federation traffic flows:
|
||||
|
||||
- **Tier 1 to Tier 2**: USB sneakernet (offline bundles only)
|
||||
- **Tier 2 to Tier 3**: gossip API over HTTPS (port 8000)
|
||||
- **Tier 2 to Tier 2**: through a Tier 3 relay, or directly via sneakernet
|
||||
- **Tier 3 to Tier 3**: gossip between relays in different jurisdictions
|
||||
|
||||
---
|
||||
|
||||
## Gossip Protocol
|
||||
|
||||
### How sync works
|
||||
|
||||
1. Node A sends its Merkle root and log size to Node B via `GET /federation/status`
|
||||
2. If roots differ and B has more records, A requests a consistency proof via
|
||||
`GET /federation/consistency-proof?old_size=N`
|
||||
3. If the proof verifies (B's log is a valid extension of A's), A fetches the missing
|
||||
records via `GET /federation/records?start=N&count=50`
|
||||
4. A appends the new records to its local log
|
||||
5. B performs the same process in reverse (bidirectional sync)
|
||||
|
||||
Records are capped at 100 per request to protect memory on resource-constrained devices.
|
||||
|
||||
### Peer health tracking
|
||||
|
||||
Each peer tracks:
|
||||
|
||||
- `last_seen` -- timestamp of last successful contact
|
||||
- `last_root` -- most recent Merkle root received from the peer
|
||||
- `last_size` -- most recent log size
|
||||
- `healthy` -- marked `false` after 3 consecutive failures
|
||||
- `consecutive_failures` -- reset to 0 on success
|
||||
|
||||
Unhealthy peers are skipped during gossip rounds but remain registered. They are retried
|
||||
on the next full gossip round. Peer state persists in SQLite at
|
||||
`~/.fwmetadata/attestations/federation/peers.db`.
|
||||
|
||||
### Gossip interval
|
||||
|
||||
The default gossip interval is 60 seconds, configurable via the `FIELDWITNESS_GOSSIP_INTERVAL`
|
||||
environment variable. In Docker Compose, set it in the environment section:
|
||||
|
||||
```yaml
|
||||
environment:
|
||||
- FIELDWITNESS_GOSSIP_INTERVAL=60
|
||||
```
|
||||
|
||||
Lower intervals mean faster convergence but more network traffic.
|
||||
|
||||
---
|
||||
|
||||
## Setting Up Federation
|
||||
|
||||
### Step 1: Exchange trust keys
|
||||
|
||||
Before two organizations can federate, they must trust each other's Ed25519 identity keys.
|
||||
Always verify fingerprints out-of-band (in person or over a known-secure voice channel).
|
||||
|
||||
On Organization A:
|
||||
|
||||
```bash
|
||||
$ cp ~/.fwmetadata/identity/public.pem /media/usb/org-a-pubkey.pem
|
||||
```
|
||||
|
||||
On Organization B:
|
||||
|
||||
```bash
|
||||
$ fieldwitness keys trust --import /media/usb/org-a-pubkey.pem
|
||||
```
|
||||
|
||||
Repeat in both directions so each organization trusts the other.
|
||||
|
||||
> **Warning:** Do not skip fingerprint verification. If an adversary substitutes their
|
||||
> own public key, they can forge attestation records that your instance will accept as
|
||||
> trusted.
|
||||
|
||||
### Step 2: Register peers (live gossip)
|
||||
|
||||
Through the web UI at `/federation`, or via the peer store directly:
|
||||
|
||||
```bash
|
||||
# On Org A's server, register Org B's federation endpoint
|
||||
$ fieldwitness federation peer add \
|
||||
--url https://orgb.example.org:8000 \
|
||||
--fingerprint a1b2c3d4e5f6...
|
||||
```
|
||||
|
||||
Or through the web UI:
|
||||
|
||||
1. Navigate to `/federation`
|
||||
2. Enter the peer's federation API URL and Ed25519 fingerprint
|
||||
3. Click "Add Peer"
|
||||
|
||||
### Step 3: Start the gossip loop
|
||||
|
||||
The gossip loop starts automatically when the server starts. On Docker deployments, the
|
||||
federation API runs on port 8000. Ensure this port is accessible between peers (firewall,
|
||||
security groups, etc.).
|
||||
|
||||
For manual one-time sync:
|
||||
|
||||
```bash
|
||||
$ fieldwitness federation sync --peer https://orgb.example.org:8000
|
||||
```
|
||||
|
||||
### Step 4: Monitor sync status
|
||||
|
||||
The web UI at `/federation` shows:
|
||||
|
||||
- Local node status (Merkle root, log size, record count)
|
||||
- Registered peers with health indicators
|
||||
- Recent sync history (records received, errors)
|
||||
|
||||
---
|
||||
|
||||
## Offline Federation (Sneakernet)
|
||||
|
||||
For Tier 1 field devices and airgapped environments, use offline bundles.
|
||||
|
||||
### Exporting a bundle
|
||||
|
||||
```bash
|
||||
$ fieldwitness chain export --output /media/usb/bundle.zip
|
||||
```
|
||||
|
||||
To export only records from a specific investigation:
|
||||
|
||||
```bash
|
||||
$ fieldwitness chain export --investigation "case-2026-001" --output /media/usb/bundle.zip
|
||||
```
|
||||
|
||||
To export a specific index range:
|
||||
|
||||
```bash
|
||||
$ fieldwitness chain export --start 100 --end 200 --output /media/usb/partial.zip
|
||||
```
|
||||
|
||||
### Importing a bundle
|
||||
|
||||
On the receiving instance:
|
||||
|
||||
```bash
|
||||
$ fieldwitness chain import /media/usb/bundle.zip
|
||||
```
|
||||
|
||||
During import:
|
||||
|
||||
- Records signed by untrusted fingerprints are rejected
|
||||
- Duplicate records (matching SHA-256) are skipped
|
||||
- Imported records are tagged with `federated_from` metadata
|
||||
- A delivery acknowledgment record (`fieldwitness/delivery-ack-v1`) is automatically appended
|
||||
to the local chain
|
||||
|
||||
### Delivery acknowledgments
|
||||
|
||||
When a bundle is imported, FieldWitness signs a `fieldwitness/delivery-ack-v1` chain record that
|
||||
contains:
|
||||
|
||||
- The SHA-256 of the imported bundle file
|
||||
- The sender's fingerprint
|
||||
- The count of records received
|
||||
|
||||
This acknowledgment can be exported back to the sending organization as proof that the
|
||||
bundle was delivered and ingested. It creates a two-way federation handshake.
|
||||
|
||||
```bash
|
||||
# On receiving org: export the acknowledgment back
|
||||
$ fieldwitness chain export --start <ack_index> --end <ack_index> \
|
||||
--output /media/usb/delivery-ack.zip
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Federation API Endpoints
|
||||
|
||||
The federation API is served by FastAPI/uvicorn on port 8000.
|
||||
|
||||
| Method | Endpoint | Description |
|
||||
|---|---|---|
|
||||
| `GET` | `/federation/status` | Current Merkle root and log size |
|
||||
| `GET` | `/federation/records?start=N&count=M` | Fetch attestation records (max 100) |
|
||||
| `GET` | `/federation/consistency-proof?old_size=N` | Merkle consistency proof |
|
||||
| `POST` | `/federation/records` | Push records to this node |
|
||||
| `GET` | `/health` | Health check |
|
||||
|
||||
### Trust filtering on push
|
||||
|
||||
When records are pushed via `POST /federation/records`, the receiving node checks each
|
||||
record's `attestor_fingerprint` against its trust store. Records from unknown attestors
|
||||
are rejected. If no trust store is configured (empty trusted keys), all records are
|
||||
accepted (trust-on-first-use).
|
||||
|
||||
---
|
||||
|
||||
## Federation Relay (Tier 3)
|
||||
|
||||
The federation relay is a minimal Docker container that runs only the federation API.
|
||||
|
||||
### What the relay stores
|
||||
|
||||
- Attestation records: image SHA-256 hashes, perceptual hashes, Ed25519 signatures
|
||||
- Chain linkage data: prev_hash, chain_index, claimed_ts
|
||||
- Signer public keys
|
||||
|
||||
### What the relay never sees
|
||||
|
||||
- AES-256-GCM channel keys or Ed25519 private keys
|
||||
- Original images or media files
|
||||
- Steganographic payloads or plaintext messages
|
||||
- User credentials or session data
|
||||
- Web UI content
|
||||
|
||||
### Deploying a relay
|
||||
|
||||
```bash
|
||||
$ cd deploy/docker
|
||||
$ docker compose up relay -d
|
||||
```
|
||||
|
||||
The relay listens on port 8001 (mapped to internal 8000). See `docs/deployment.md`
|
||||
Section 3 for full deployment details.
|
||||
|
||||
### Jurisdiction considerations
|
||||
|
||||
Deploy relays in jurisdictions with strong press freedom protections:
|
||||
|
||||
- **Iceland** -- strong source protection laws, no mandatory data retention for this type of data
|
||||
- **Switzerland** -- strict privacy laws, resistance to foreign legal requests
|
||||
- **Netherlands** -- strong press freedom, EU GDPR protections
|
||||
|
||||
Consult with a press freedom lawyer for your specific situation.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Peer marked unhealthy**
|
||||
|
||||
After 3 consecutive sync failures, a peer is marked unhealthy and skipped. Check:
|
||||
|
||||
1. Is the peer's federation API reachable? `curl https://peer.example.org:8000/health`
|
||||
2. Is TLS configured correctly? The peer's API must be accessible over HTTPS in production.
|
||||
3. Are firewall rules open for port 8000?
|
||||
4. The peer will be retried on subsequent gossip rounds. Once a sync succeeds, the peer
|
||||
is marked healthy again.
|
||||
|
||||
**Records rejected on import**
|
||||
|
||||
Records are rejected if the signer's fingerprint is not in the local trust store. Import
|
||||
the sender's public key first:
|
||||
|
||||
```bash
|
||||
$ fieldwitness keys trust --import /path/to/sender-pubkey.pem
|
||||
```
|
||||
|
||||
**Consistency proof failure**
|
||||
|
||||
A consistency proof failure means the peer's log is not a valid extension of the local log.
|
||||
This indicates a potential fork -- the peer may have a different chain history. Investigate
|
||||
before proceeding:
|
||||
|
||||
1. Compare chain heads: `fieldwitness chain status` on both instances
|
||||
2. If a fork is confirmed, one instance's records must be exported and re-imported into a
|
||||
fresh chain
|
||||
|
||||
**Gossip not starting**
|
||||
|
||||
The gossip loop requires the `federation` extra:
|
||||
|
||||
```bash
|
||||
$ pip install "fieldwitness[federation]"
|
||||
```
|
||||
|
||||
This installs `aiohttp` for async HTTP communication.
|
||||
49
docs/index.md
Normal file
49
docs/index.md
Normal file
@ -0,0 +1,49 @@
|
||||
# FieldWitness Documentation
|
||||
|
||||
## For Reporters and Field Users
|
||||
|
||||
| Document | Description |
|
||||
|---|---|
|
||||
| [Reporter Quick-Start](training/reporter-quickstart.md) | One-page card for Tier 1 USB users. Print, laminate, keep with the USB. |
|
||||
| [Reporter Field Guide](training/reporter-field-guide.md) | Comprehensive guide: attesting photos, steganography, killswitch, backups, evidence packages. |
|
||||
| [Emergency Card](training/emergency-card.md) | Wallet-sized reference for emergency data destruction. Print and laminate. |
|
||||
|
||||
## For Administrators
|
||||
|
||||
| Document | Description |
|
||||
|---|---|
|
||||
| [Admin Quick Reference](training/admin-reference.md) | CLI cheat sheet, hardening checklist, troubleshooting table. |
|
||||
| [Admin Operations Guide](training/admin-operations-guide.md) | Full procedures: user management, drop box, federation, key rotation, incident response. |
|
||||
| [Deployment Guide](deployment.md) | Three-tier deployment: bootable USB, Docker org server, Kubernetes federation relay. Threat level presets, security hardening, systemd setup. |
|
||||
|
||||
## Feature Guides
|
||||
|
||||
| Document | Description |
|
||||
|---|---|
|
||||
| [Federation Guide](federation.md) | Gossip protocol setup, offline bundles, peer management, relay deployment. |
|
||||
| [Evidence Guide](evidence-guide.md) | Evidence packages, cold archives, selective disclosure, chain anchoring, legal discovery workflow. |
|
||||
| [Source Drop Box](source-dropbox.md) | Anonymous file intake: tokens, EXIF pipeline, receipt codes, operational security. |
|
||||
|
||||
## Security
|
||||
|
||||
| Document | Description |
|
||||
|---|---|
|
||||
| [Threat Model](security/threat-model.md) | Adversary model, security guarantees, non-guarantees, cryptographic primitives, key management, known limitations. |
|
||||
|
||||
## Architecture (Developer Reference)
|
||||
|
||||
| Document | Description |
|
||||
|---|---|
|
||||
| [Federation Architecture](architecture/federation.md) | System design: threat model, layers (chain, bundles, federation), key domains, permission tiers. |
|
||||
| [Chain Format Spec](architecture/chain-format.md) | CBOR record format, entropy witnesses, serialization, storage format, content types. |
|
||||
| [Export Bundle Spec](architecture/export-bundle.md) | FIELDWITNESSX1 binary format, envelope encryption (X25519 + AES-256-GCM), Merkle trees. |
|
||||
| [Federation Protocol Spec](architecture/federation-protocol.md) | CT-inspired server protocol: API endpoints, gossip, storage tiers, receipts, security model. |
|
||||
|
||||
## Planning
|
||||
|
||||
| Document | Description |
|
||||
|---|---|
|
||||
| [Why FieldWitness](planning/why-fieldwitness.md) | Problem statement, positioning, scenarios, and technical overview for non-technical audiences. |
|
||||
| [C2PA Integration](planning/c2pa-integration.md) | C2PA bridge architecture, concept mapping, implementation phases, privacy design. |
|
||||
| [Packaging Strategy](planning/packaging-strategy.md) | Hosted demo, standalone binary, mobile app, and onboarding flow design. |
|
||||
| [GTM Feasibility](planning/gtm-feasibility.md) | Phased plan for credibility, community engagement, funding, and field testing. |
|
||||
240
docs/planning/c2pa-integration.md
Normal file
240
docs/planning/c2pa-integration.md
Normal file
@ -0,0 +1,240 @@
|
||||
# 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
|
||||
|
||||
```toml
|
||||
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)
|
||||
214
docs/planning/gtm-feasibility.md
Normal file
214
docs/planning/gtm-feasibility.md
Normal file
@ -0,0 +1,214 @@
|
||||
# Go-to-Market Feasibility Plan
|
||||
|
||||
**Audience:** Internal planning (solo developer)
|
||||
**Status:** Active planning document
|
||||
**Last updated:** 2026-04-01
|
||||
|
||||
## Overview
|
||||
|
||||
Phased plan for building credibility and visibility for FieldWitness in the press freedom and
|
||||
digital security space. Constraints: solo developer, ~10-15 hrs/week, portfolio/learning
|
||||
project that should also produce real-world value.
|
||||
|
||||
---
|
||||
|
||||
## Current Strengths
|
||||
|
||||
- Federation layer is genuinely novel: gossip-based attestation sync across orgs with
|
||||
offline-first design and append-only hash chains
|
||||
- Three-tier deployment model maps to how press freedom orgs actually work
|
||||
- C2PA export is well-timed as CAI gains momentum
|
||||
- Working codebase with tests, deployment configs, documentation
|
||||
|
||||
## Core Challenges
|
||||
|
||||
- **Trust deficit:** "Some guy built a tool" is a warning sign in this space, not a
|
||||
selling point
|
||||
- **Chicken-and-egg:** Need audit for credibility, need credibility/money for audit,
|
||||
need adoption for money
|
||||
- **Limited bandwidth:** 10-15 hrs/week makes sequencing critical
|
||||
- **Stego perception risk:** Steganography angle can be a credibility liability if
|
||||
positioned as headline feature (perceived as "hacker toy")
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Foundation (Months 1-6)
|
||||
|
||||
**Goal:** Make the project legible to the ecosystem.
|
||||
|
||||
### Technical credibility (60% of time)
|
||||
|
||||
- Ship C2PA export as v0.3.0 headline feature (target: 8 weeks)
|
||||
- Write formal threat model document at `docs/security/threat-model.md`
|
||||
- Model after Signal protocol docs or Tor design doc
|
||||
- De-emphasize steganography in public surfaces -- lead with "offline-first provenance
|
||||
attestation with gossip federation"
|
||||
- Set up reproducible builds with pinned dependencies
|
||||
- Get CI/CD visibly working with test/lint/type-check/coverage badges
|
||||
|
||||
### Positioning and documentation (20% of time)
|
||||
|
||||
- Write "Why FieldWitness Exists" document (~1500 words): the problem, why existing tools
|
||||
don't solve it, what FieldWitness does differently, who it's for, what it needs
|
||||
- Create 2-minute demo video: field attestation -> sneakernet sync -> federation ->
|
||||
verification
|
||||
|
||||
### Community engagement (20% of time)
|
||||
|
||||
- Lurk on `liberationtech@lists.stanford.edu` -- do NOT announce tool cold; wait for
|
||||
relevant threads
|
||||
- GitHub engagement with adjacent projects (real contributions, not performative):
|
||||
- `guardian/proofmode-android`
|
||||
- `contentauth/c2pa-python`
|
||||
- `freedomofpress/securedrop`
|
||||
- Post Show HN when C2PA export ships
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Credibility Escalation (Months 7-12)
|
||||
|
||||
**Goal:** Get external validation from at least one recognized entity.
|
||||
|
||||
### OTF (Open Technology Fund) -- https://www.opentech.fund/
|
||||
|
||||
**Internet Freedom Fund:** $50K-$900K over 12-36 months. Solo developers eligible.
|
||||
Rolling applications.
|
||||
|
||||
**Red Team Lab:** FREE security audits commissioned through partner firms (Cure53, Trail
|
||||
of Bits, Radically Open Security). This is the single highest-leverage action.
|
||||
|
||||
**Usability Lab:** Free UX review.
|
||||
|
||||
**Application timeline:** 2-4 months from submission to decision.
|
||||
|
||||
**Strategy:** Apply to Red Team Lab for audit FIRST (lower commitment for OTF, validates
|
||||
you as "OTF-vetted").
|
||||
|
||||
### Compelling application elements
|
||||
|
||||
1. Lead with problem: "Provenance attestation tools assume persistent internet. For
|
||||
journalists in [specific scenario], this fails."
|
||||
2. Lead with differentiator: "Gossip federation for cross-org attestation sync,
|
||||
offline-first, bridges to C2PA."
|
||||
3. Be honest about status: "Working prototype at v0.3.0, needs audit and field testing."
|
||||
4. Budget: stipend, audit (if Red Team Lab unavailable), 1-2 conferences, federation
|
||||
relay hosting.
|
||||
|
||||
### Backup audit and funding paths
|
||||
|
||||
| Organization | URL | Notes |
|
||||
|---|---|---|
|
||||
| OSTIF | https://ostif.org/ | Funds audits for open-source projects; may be too early-stage |
|
||||
| Radically Open Security | https://www.radicallyopensecurity.com/ | Nonprofit, reduced rates for internet freedom projects; focused audit ~$15-30K |
|
||||
| NLnet Foundation | https://nlnet.nl/ | EUR 5-50K grants, lightweight process, solo devs welcome, includes audit funding |
|
||||
| Filecoin Foundation for Decentralized Web | https://fil.org/grants | Relevant to federation/provenance angle |
|
||||
|
||||
### Community building
|
||||
|
||||
- Submit talk to **IFF 2027** (Internet Freedom Festival, Valencia, ~March)
|
||||
- Open sessions and tool showcases have low barriers
|
||||
- Talk title: "Federated Evidence Chains: Offline Provenance for Journalists in
|
||||
Hostile Environments"
|
||||
- Cold outreach to 3-5 specific people:
|
||||
- Access Now Digital Security Helpline trainers
|
||||
- Harlo Holmes (FPF Director of Digital Security)
|
||||
- Guardian Project developers (ProofMode team)
|
||||
- Position as complementary, not competitive
|
||||
- Lead with "I want honest feedback"
|
||||
- Conferences:
|
||||
- **RightsCon** -- https://www.rightscon.org/
|
||||
- **IFF** -- https://internetfreedomfestival.org/
|
||||
- **USENIX Security / PETS** -- academic venues, for federation protocol paper
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Traction or Pivot (Months 13-24)
|
||||
|
||||
### Green lights (keep going)
|
||||
|
||||
- OTF Red Team Lab acceptance or any grant funding
|
||||
- A digital security trainer says "I could see using this"
|
||||
- A journalist or NGO runs it in any scenario
|
||||
- Another developer contributes a meaningful PR
|
||||
- Conference talk accepted
|
||||
|
||||
### Red lights (pivot positioning)
|
||||
|
||||
- Zero response from outreach after 6+ months
|
||||
- Funders say problem is already solved
|
||||
- Security reviewers find fundamental design flaws
|
||||
|
||||
### If green (months 13-24)
|
||||
|
||||
- Execute audit, publish results publicly (radical transparency)
|
||||
- Build pilot deployment guide
|
||||
- Apply for Internet Freedom Fund
|
||||
- Present at RightsCon 2027/2028
|
||||
|
||||
### If red (months 13-24)
|
||||
|
||||
- Reposition as reference implementation / research project
|
||||
- Write federation protocol as academic paper
|
||||
- Lean into portfolio angle
|
||||
|
||||
---
|
||||
|
||||
## Professional Portfolio Positioning
|
||||
|
||||
### Framing
|
||||
|
||||
"I designed and implemented a gossip-based federation protocol for offline-first
|
||||
provenance attestation, targeting field deployment in resource-constrained environments.
|
||||
The system uses Ed25519 signing, Merkle trees with consistency proofs, append-only hash
|
||||
chains with CBOR serialization, and bridges to the C2PA industry standard."
|
||||
|
||||
### Skills demonstrated
|
||||
|
||||
- Cryptographic protocol design
|
||||
- Distributed systems (gossip, consistency proofs)
|
||||
- Security engineering (threat modeling, audit prep, key management)
|
||||
- Systems architecture (three-tier, offline-first)
|
||||
- Domain expertise (press freedom, evidence integrity)
|
||||
- Grant writing (if pursued)
|
||||
|
||||
### Target roles
|
||||
|
||||
- Security engineer (FPF, EFF, Access Now, Signal, Cloudflare)
|
||||
- Protocol engineer (decentralized systems)
|
||||
- Developer advocate (security companies)
|
||||
- Infrastructure engineer
|
||||
|
||||
### Key portfolio artifacts
|
||||
|
||||
- Threat model document (shows security thinking)
|
||||
- Audit report, even with findings (shows maturity)
|
||||
- C2PA bridge (shows standards interop, not just NIH)
|
||||
|
||||
---
|
||||
|
||||
## Timeline (10-15 hrs/week)
|
||||
|
||||
| Month | Focus | Deliverable | Time split |
|
||||
|-------|-------|-------------|------------|
|
||||
| 1-2 | C2PA export + threat model | v0.3.0, `threat-model.md` | 12 code, 3 docs |
|
||||
| 3-4 | Demo video + "Why FieldWitness" + CI | Video, doc, badges | 8 code, 4 docs, 3 outreach |
|
||||
| 5-6 | OTF Red Team Lab app + community | Application submitted, Show HN | 5 code, 5 grants, 5 outreach |
|
||||
| 7-9 | Community + backup grants | Outreach emails, NLnet/FFDW apps | 8 code, 3 grants, 4 outreach |
|
||||
| 10-12 | IFF submission + traction check | Talk submitted, go/no-go decision | 8 code, 2 grants, 5 outreach |
|
||||
| 13-18 | (If green) Audit + pilot guide | Published audit, pilot doc | 10 code, 5 docs |
|
||||
| 19-24 | (If green) Conference + IFF app | Talk, major grant application | 5 code, 5 grant, 5 outreach |
|
||||
|
||||
---
|
||||
|
||||
## What NOT to Bother With
|
||||
|
||||
- Paid marketing, ads, PR
|
||||
- Product Hunt, startup directories, "launch" campaigns
|
||||
- Project website beyond clean README
|
||||
- Corporate partnerships
|
||||
- Whitepapers before audit
|
||||
- Mobile apps
|
||||
- Discord/Slack community (dead community is worse than none)
|
||||
- Press coverage (too early)
|
||||
- Competing with SecureDrop on source protection
|
||||
- General tech conference talks (domain-specific venues only)
|
||||
262
docs/planning/packaging-strategy.md
Normal file
262
docs/planning/packaging-strategy.md
Normal file
@ -0,0 +1,262 @@
|
||||
# Packaging Strategy
|
||||
|
||||
**Audience:** Internal planning (solo developer)
|
||||
**Status:** Active planning document
|
||||
**Last updated:** 2026-04-01
|
||||
|
||||
---
|
||||
|
||||
## The core problem
|
||||
|
||||
FieldWitness is a Python CLI and Flask web application installed via `pip install fieldwitness`. This requires:
|
||||
|
||||
- Python 3.11 or later installed on the system
|
||||
- Comfort with a terminal
|
||||
- Familiarity with pip, virtual environments, and dependency management
|
||||
- Willingness to debug installation issues (missing system libraries, wheel build failures, PATH problems)
|
||||
|
||||
This excludes an estimated 95%+ of the target audience. A journalist covering a school board meeting will not open a terminal. The feedback is consistent: journalists want, in order of preference, an iPhone app, a Mac drag-and-drop application, or a hosted web service. `pip install` is where they stop.
|
||||
|
||||
The attestation capability -- prove this file is mine, unaltered, timestamped -- is the product journalists would pay for. Everything else (federation, steganography, killswitch) is invisible or incomprehensible to this audience until the core attestation experience is accessible without developer tooling.
|
||||
|
||||
---
|
||||
|
||||
## Packaging tiers
|
||||
|
||||
Ordered by impact and feasibility for a solo developer working 10-15 hours per week.
|
||||
|
||||
### Tier 1: Hosted demo (lowest effort, highest reach)
|
||||
|
||||
**What it is.** A public web instance where journalists can upload a file and see attestation in action. No install. Just a URL.
|
||||
|
||||
**What it provides:**
|
||||
|
||||
- Immediate "try it" experience for anyone evaluating the tool
|
||||
- Eliminates every installation barrier simultaneously
|
||||
- Provides the demo for grant applications, conference talks, and blog posts
|
||||
- Gives the project a URL to share that is not a GitHub repository
|
||||
|
||||
**What it is NOT:**
|
||||
|
||||
- Not for production use with sensitive files. A public demo instance cannot make security guarantees about uploaded content. The demo page must state this clearly.
|
||||
- Not a replacement for self-hosted or local deployment for real operational use.
|
||||
|
||||
**Implementation:**
|
||||
|
||||
- Deploy the existing Flask web UI on a VPS (DigitalOcean droplet, Hetzner, or similar)
|
||||
- Restrict to attestation and verification only (disable fieldkit, stego, admin, drop box)
|
||||
- Add a prominent banner: "This is a public demo. Do not upload sensitive files."
|
||||
- Rate limit uploads (e.g., 10 per IP per hour, 50 MB max)
|
||||
- Auto-purge uploaded files after 24 hours
|
||||
- HTTPS via Let's Encrypt (not self-signed)
|
||||
- Minimal hardening: firewall, fail2ban, unattended-upgrades
|
||||
- Estimated hosting cost: $5-12/month
|
||||
|
||||
**Feasibility:** High. This is a deployment task, not a development task. The Flask web UI already handles attestation and verification. The work is configuration, hardening, and adding the demo-mode restrictions.
|
||||
|
||||
**Estimated effort:** 8-12 hours for initial deployment, then minimal ongoing maintenance.
|
||||
|
||||
**Priority:** Do this first. Before anything else. Every other packaging tier benefits from having a live URL to point people to.
|
||||
|
||||
### Tier 2: Standalone binary (medium effort)
|
||||
|
||||
**What it is.** A downloadable application that runs without Python, pip, or any developer tooling. Double-click to start.
|
||||
|
||||
**Options, in order of preference:**
|
||||
|
||||
**Option A: PyInstaller / PyApp standalone.**
|
||||
|
||||
- Bundle the Flask web UI into a single executable (Mac .app, Linux AppImage, Windows .exe)
|
||||
- User downloads, double-clicks, browser opens to `localhost:5000`
|
||||
- PyInstaller is mature and well-documented for Flask apps
|
||||
- Produces a ~50-100 MB download (Python runtime + all dependencies bundled)
|
||||
- Cross-platform builds require CI on each platform (GitHub Actions has Mac/Linux/Windows runners)
|
||||
- Code signing is needed for Mac (Apple notarization) and Windows (Authenticode) to avoid security warnings that will terrify the target audience. Mac notarization requires a $99/year Apple Developer account. Windows Authenticode signing requires a code signing certificate ($200-500/year or free via SignPath for open source).
|
||||
- Estimated effort: 20-30 hours including CI setup and platform testing
|
||||
|
||||
**Option B: Homebrew tap (Mac only).**
|
||||
|
||||
- `brew install fieldwitness` handles Python, dependencies, and PATH setup
|
||||
- Lower effort than PyInstaller (no bundling, just a formula)
|
||||
- But still requires users to have Homebrew installed, which requires a terminal
|
||||
- Better suited as a secondary distribution channel for Mac users who are slightly technical
|
||||
- Estimated effort: 4-6 hours
|
||||
|
||||
**Option C: curl-pipe-bash installer.**
|
||||
|
||||
- `curl -sSL https://fieldwitness.org/install.sh | bash`
|
||||
- Script installs Python if needed, creates a virtual environment, installs FieldWitness
|
||||
- Creates a desktop shortcut or menu entry
|
||||
- Common in developer tools (rustup, Homebrew itself) but asks users to paste terminal commands from the internet, which security-conscious users rightly distrust
|
||||
- Estimated effort: 8-12 hours
|
||||
|
||||
**Recommendation:** Start with Option A (PyInstaller) for Mac and Linux. Skip Windows initially -- the target audience skews heavily Mac. Add the Homebrew tap as a bonus for Mac users who prefer it.
|
||||
|
||||
### Tier 3: Mobile app (high effort, highest value)
|
||||
|
||||
**What it is.** An iPhone (and eventually Android) camera app that attests photos at the moment of capture.
|
||||
|
||||
**Why this matters:**
|
||||
|
||||
- Smartphones are where journalists capture evidence
|
||||
- Attestation at capture time is stronger than attestation after transfer to a laptop
|
||||
- This is the ProofMode competitor
|
||||
- This is the $10/month product -- the thing a journalist would put on an expense report
|
||||
- "Take a photo, it's automatically attested" is the simplest possible user experience
|
||||
|
||||
**What it would do:**
|
||||
|
||||
- Custom camera interface (or hook into the system camera via share sheet)
|
||||
- At capture: strip dangerous EXIF fields, preserve evidentiary fields, compute hashes, sign with on-device Ed25519 key, append to local chain
|
||||
- Store attestation records locally
|
||||
- When connected to Wi-Fi or organizational network: sync attestation records to Tier 2 org server
|
||||
- Export evidence packages for individual photos
|
||||
- Push notification reminders for dead man's switch check-in
|
||||
|
||||
**Technical approach:**
|
||||
|
||||
- **Swift (iOS) or Kotlin (Android)** for native apps, or **React Native / Flutter** for cross-platform
|
||||
- The cryptographic core (Ed25519, SHA-256, hash chain) would need to be reimplemented or wrapped via a shared library
|
||||
- The `cryptography` Python library that FieldWitness uses wraps OpenSSL, which is available on both platforms
|
||||
- Alternatively: Rust core library compiled to iOS/Android via FFI, with native UI layer
|
||||
- A pragmatic first step: use the phone's share sheet to send files to a local FieldWitness web UI running on the same network (Tier 2 server), avoiding native app development entirely
|
||||
|
||||
**Feasibility:** High effort. Likely requires grant funding to cover 3-6 months of focused development. A React Native approach with a Rust crypto core would minimize platform-specific work but still represents a major project.
|
||||
|
||||
**Estimated effort:** 200-400 hours for a minimum viable iOS app. Double for cross-platform.
|
||||
|
||||
**Prerequisites:** The hosted demo (Tier 1) must exist first. The standalone binary (Tier 2) should exist first. Building a mobile app before the desktop/web experience is solid would be premature optimization.
|
||||
|
||||
### Tier 4: Browser extension (speculative)
|
||||
|
||||
**What it is.** A browser extension that attests web pages, screenshots, and downloaded documents.
|
||||
|
||||
**Use case:** "Prove this web page existed in this form on this date." A Wayback Machine for individual journalists, creating locally-held proof rather than depending on the Internet Archive.
|
||||
|
||||
**Why it is speculative:**
|
||||
|
||||
- The Wayback Machine already exists and is widely trusted
|
||||
- Browser extensions have a difficult security model (broad permissions, update mechanisms, store review)
|
||||
- The overlap with the core FieldWitness audience is uncertain -- this is closer to OSINT tool than field evidence tool
|
||||
- Significant effort for uncertain adoption
|
||||
|
||||
**If pursued:** A minimal extension that captures the page HTML + screenshot, computes hashes, and sends to a local FieldWitness instance for attestation. Not a standalone attestation tool -- a bridge to the existing system.
|
||||
|
||||
**Estimated effort:** 40-80 hours for a minimal Chrome extension.
|
||||
|
||||
**Recommendation:** Do not build this until Tiers 1-3 are established and there is clear user demand.
|
||||
|
||||
---
|
||||
|
||||
## Onboarding flow design
|
||||
|
||||
The goal: a non-technical journalist goes from "what is this?" to "I just attested my first file" in under three minutes.
|
||||
|
||||
### The hosted demo flow (Tier 1)
|
||||
|
||||
1. Journalist arrives at `fieldwitness.org` (or wherever the demo is hosted)
|
||||
2. Landing page: one paragraph explaining what FieldWitness does (use the language from [why-fieldwitness.md](why-fieldwitness.md)), plus a prominent "Try it now" button
|
||||
3. Click "Try it now" -- goes directly to the attestation page
|
||||
4. Upload any file (photo, document, PDF)
|
||||
5. FieldWitness displays the attestation result:
|
||||
- The file's cryptographic fingerprint (SHA-256 hash, displayed as a short ID)
|
||||
- The timestamp
|
||||
- A "Download verification receipt" button
|
||||
6. The receipt is a small JSON file (or a one-page PDF) that includes everything needed to verify the attestation later
|
||||
7. Below the result: "Now try verifying it" -- a link to the verification page where they upload the file and the receipt, and see confirmation that the file matches
|
||||
|
||||
**The "aha moment"** is step 5-7: seeing the verification receipt for the first time and understanding that this receipt can prove the file's integrity to anyone, anywhere, without trusting FieldWitness or any third party.
|
||||
|
||||
### The installed flow (Tier 2+)
|
||||
|
||||
1. Download and open FieldWitness (double-click the .app on Mac)
|
||||
2. Browser opens to the local web UI
|
||||
3. First-run wizard: "FieldWitness needs to create a cryptographic identity. This is like a digital signature -- it proves attestations came from you." One button: "Create identity."
|
||||
4. Identity created. User sees their fingerprint (a short hex string) and a recommendation to back it up.
|
||||
5. "Attest your first file" -- same upload flow as the demo, but now signed with their identity
|
||||
6. Download evidence package -- a ZIP containing the original file, the attestation record, and a `verify.py` script that anyone can run
|
||||
|
||||
### What to avoid in onboarding
|
||||
|
||||
- Do not explain hash chains, Merkle trees, or Ed25519 during onboarding. These are details for the security architecture docs, not the first-run experience.
|
||||
- Do not require account creation, email verification, or any form of registration.
|
||||
- Do not show a dashboard, settings page, or feature list before the user has attested their first file. Get them to the core action immediately.
|
||||
- Do not use the word "cryptographic" in the UI. Use "digital fingerprint" and "digital signature" instead.
|
||||
|
||||
---
|
||||
|
||||
## Pricing model
|
||||
|
||||
All source code remains GPL-3.0. The open-source tool is and remains free. Revenue comes from hosted services, not software licenses.
|
||||
|
||||
### Free tier (current)
|
||||
|
||||
- CLI tool: `pip install fieldwitness`
|
||||
- Self-hosted web UI: `fieldwitness serve`
|
||||
- All features, no restrictions
|
||||
- User is responsible for their own deployment, backups, and security
|
||||
|
||||
### Hosted individual tier ($10/month)
|
||||
|
||||
- Hosted attestation at `app.fieldwitness.org` (or similar)
|
||||
- Persistent identity and attestation history
|
||||
- Evidence package export and download
|
||||
- Cloud backup of attestation records (not original files -- those stay local)
|
||||
- External timestamp anchoring (RFC 3161) included
|
||||
- C2PA export when available
|
||||
- Target audience: freelance journalists, Substack writers, independent investigators
|
||||
|
||||
### Hosted organization tier ($50/month)
|
||||
|
||||
- Everything in the individual tier
|
||||
- Multi-user with role-based access
|
||||
- Federation server (sync attestations with partner organizations)
|
||||
- Source drop box (token-gated anonymous upload)
|
||||
- Organizational identity key (attestations signed by the org, not individual reporters)
|
||||
- Admin dashboard for attestation management
|
||||
- Target audience: newsrooms, NGOs, human rights organizations
|
||||
|
||||
### What the pricing assumes
|
||||
|
||||
- The $10/month price point is based on the journalist feedback: this is an amount a freelancer could expense or justify personally
|
||||
- The $50/month org tier is intentionally low to encourage adoption by small NGOs
|
||||
- Revenue is not the primary goal in the first year -- adoption and feedback are. Pricing exists in the plan to demonstrate sustainability to grant reviewers.
|
||||
- Stripe or Paddle for payment processing. Do not build custom payment infrastructure.
|
||||
|
||||
### Revenue is not the first priority
|
||||
|
||||
The sequence is: users, then feedback, then audit, then trust, then revenue. Do not optimize for revenue before the free product has active users. The hosted demo (Tier 1) is free and should remain free indefinitely.
|
||||
|
||||
---
|
||||
|
||||
## What NOT to build
|
||||
|
||||
These constraints are load-bearing. Violating the sequence wastes limited development time on things that do not yet have an audience.
|
||||
|
||||
**Do not build a mobile app before the hosted demo exists.** The demo is the proof-of-concept that validates whether journalists care about this capability at all. Building a mobile app for a product nobody has tried is a months-long gamble.
|
||||
|
||||
**Do not build the standalone binary before the hosted demo exists.** Same reasoning. The demo validates demand. The binary is for users who have already tried the demo and want a local installation.
|
||||
|
||||
**Do not build a browser extension before the mobile app.** The browser extension serves a niche use case. The mobile app serves the primary use case (attesting photos at capture). Niche features wait until the core experience is established.
|
||||
|
||||
**Do not build paid features before the free product has users.** Stripe integration, subscription management, and payment UI are non-trivial and completely irrelevant if nobody is using the free tool.
|
||||
|
||||
**Do not build a custom landing page before the demo exists.** The demo IS the landing page. A marketing site without a working demo is vaporware.
|
||||
|
||||
**Do not build multi-platform simultaneously.** Start with Mac (the dominant platform for journalists in the US market). Add Linux for NGOs in resource-constrained environments. Add Windows only if there is demonstrated demand.
|
||||
|
||||
---
|
||||
|
||||
## Sequencing summary
|
||||
|
||||
| Phase | Deliverable | Effort | Prerequisite |
|
||||
|-------|-------------|--------|-------------|
|
||||
| 1 | Hosted demo instance | 8-12 hours | None |
|
||||
| 2 | "Why FieldWitness" narrative + demo link | 4-6 hours | Phase 1 |
|
||||
| 3 | PyInstaller Mac .app | 20-30 hours | Phase 1 |
|
||||
| 4 | Homebrew tap | 4-6 hours | Phase 3 |
|
||||
| 5 | Hosted individual tier (paid) | 20-40 hours | Phase 1 + users |
|
||||
| 6 | iOS app (MVP) | 200-400 hours | Phases 1-3 + funding |
|
||||
| 7 | Browser extension | 40-80 hours | Phases 1-6 + demand signal |
|
||||
|
||||
Total to reach a usable demo that journalists can try: **12-18 hours** (Phase 1 + 2). That is one to two weekends of focused work. Everything after that is incremental.
|
||||
149
docs/planning/why-fieldwitness.md
Normal file
149
docs/planning/why-fieldwitness.md
Normal file
@ -0,0 +1,149 @@
|
||||
# Why FieldWitness Exists
|
||||
|
||||
**Audience:** Non-technical first (journalists, editors, grant reviewers, advocates), with a technical appendix for developers and security reviewers.
|
||||
|
||||
---
|
||||
|
||||
## The problem
|
||||
|
||||
A journalist covering local government photographs a leaked budget document showing irregularities in public spending. She publishes the story. Six months later, the city's attorney writes a letter: "That photograph is fabricated. There is no evidence it existed before your article."
|
||||
|
||||
The journalist has the photo on her laptop. The file has a date stamp, but anyone with basic computer skills can change a file's date. She has it in iCloud, but Apple's timestamps prove when the file was uploaded, not when it was taken, and certainly not that it hasn't been altered since. She emailed it to her editor -- but that only proves she sent *something* to her editor, and both parties are considered interested. The metadata inside the photo could establish when and where it was taken, but metadata is trivially editable and routinely stripped by every messaging app and social media platform.
|
||||
|
||||
She has no proof. Not because she fabricated anything, but because none of the tools she uses were designed to prove she didn't.
|
||||
|
||||
This is not a war-zone problem. It is an every-newsroom problem. It happens at school board meetings, city council sessions, county commissioner hearings, and state legislature corridors. It happens every time a public official decides the easiest defense is to attack the evidence rather than address the substance.
|
||||
|
||||
---
|
||||
|
||||
## Why existing tools fail
|
||||
|
||||
**Cloud storage (iCloud, Google Drive, Dropbox).** These services record when a file was uploaded and synced. They do not prove a file's contents haven't changed. The timestamps belong to the cloud provider, not the journalist, and can be subpoenaed, disputed, or simply unavailable if the journalist changes services.
|
||||
|
||||
**Email.** Emailing yourself a file creates a record that something was sent at a certain time, but email headers are not cryptographically signed in a way courts consistently accept. And you're trusting Google, Microsoft, or whoever runs your mail server to testify on your behalf.
|
||||
|
||||
**Signal, WhatsApp, encrypted messaging.** These tools protect the privacy of your communications. They do not create verifiable records of what was communicated. Signal's disappearing messages are the opposite of evidence preservation. These tools solve a different and equally important problem.
|
||||
|
||||
**The Wayback Machine.** Useful for web pages, useless for photographs, documents, and files that were never published online.
|
||||
|
||||
**ProofMode (Guardian Project).** The closest existing tool to what FieldWitness does. ProofMode is Android-only, designed for individual use, and does not handle multi-reporter workflows or cross-organization chain of custody. It is a good tool solving a narrower problem.
|
||||
|
||||
**C2PA (Content Authenticity Initiative).** An emerging industry standard backed by Adobe, Microsoft, and the BBC. Primarily designed for camera manufacturers and publishing platforms -- not for field journalists working offline. FieldWitness is building a bridge to C2PA so that attestations can be exported in the industry-standard format (see the technical appendix).
|
||||
|
||||
None of these tools answer the question a lawyer actually asks: "Can you prove, to a standard a court would accept, that this file existed in exactly this form at the time you claim, and that it has not been altered since?"
|
||||
|
||||
---
|
||||
|
||||
## What FieldWitness does
|
||||
|
||||
When you attest a file with FieldWitness, it creates a cryptographic fingerprint that proves the file existed in this exact state at this exact time, signed with your identity. That proof is chained to every other attestation you have ever made, so tampering with one means tampering with all of them. The proof can be independently verified by anyone using the free verification tool -- no FieldWitness account or installation needed.
|
||||
|
||||
The key properties:
|
||||
|
||||
- **Tamper-evident.** If a single byte of the file changes, the fingerprint breaks and verification fails.
|
||||
- **Time-anchored.** Each attestation is chained to all previous attestations in sequence. External timestamps (from independent timestamping authorities) can anchor the chain to a provable point in time.
|
||||
- **Identity-bound.** Each attestation is signed with the journalist's cryptographic identity. The signature proves who attested the file without exposing their device, location, or personal information.
|
||||
- **Independently verifiable.** FieldWitness produces self-contained evidence packages -- ZIP files with the original file, the attestation record, and a standalone verification script. A court, a lawyer, or a colleague can verify the evidence with nothing but Python installed. No FieldWitness account. No internet connection. No trust in any third party.
|
||||
- **Works offline.** Every core function works without internet access. FieldWitness was built for environments where connectivity is unreliable, monitored, or dangerous.
|
||||
|
||||
---
|
||||
|
||||
## Three scenarios
|
||||
|
||||
### 1. Solo journalist protecting their evidence
|
||||
|
||||
Maria covers local government for a Substack newsletter. She attests every photo, document, and recording she collects. Her attestation chain grows over time, creating a continuous, tamper-evident record of her work. When a source's leaked memo is challenged, she exports an evidence package and hands it to her lawyer. The lawyer runs the verification script and confirms: this file was attested on this date, signed by Maria's identity, and its fingerprint is intact.
|
||||
|
||||
Maria does not need to understand cryptography. She opens FieldWitness in her browser, uploads a file, and clicks "Attest." The hard part is already done.
|
||||
|
||||
### 2. Newsroom with multiple reporters
|
||||
|
||||
A regional newspaper has five reporters covering a corruption investigation. Each reporter attests their own evidence. The newsroom runs an organizational FieldWitness server that collects and indexes all attestations. When the newspaper needs to produce evidence for a legal proceeding, it can export a complete, verifiable chain of custody showing which reporter attested which file, when, and that nothing has been altered.
|
||||
|
||||
The reporters work independently. The organizational server provides backup, coordination, and the ability to share verified evidence between reporters without breaking the chain of custody.
|
||||
|
||||
### 3. Cross-organization coalition
|
||||
|
||||
Three NGOs are documenting the same environmental disaster in different regions. Each organization runs its own FieldWitness server. Through federation -- a system where servers synchronize attestation records with each other -- they can verify each other's evidence without any central authority. When Organization A attests a water sample photograph and Organization B independently attests satellite imagery of the same site, both attestations can be presented together with a provable timeline and independent verification.
|
||||
|
||||
Federation works over the internet when available, or via physical USB transfer when it is not. The system was designed for exactly this kind of decentralized, trust-nothing collaboration.
|
||||
|
||||
---
|
||||
|
||||
## What FieldWitness does NOT do
|
||||
|
||||
**FieldWitness does not protect your communications.** Use Signal, Wire, or another end-to-end encrypted messenger for that. FieldWitness protects evidence, not conversations.
|
||||
|
||||
**FieldWitness does not anonymize your internet activity.** Use Tor or a VPN for that. FieldWitness can operate entirely offline, but it does not hide your network traffic when it is online.
|
||||
|
||||
**FieldWitness does not replace a lawyer.** It produces evidence that is cryptographically verifiable, but whether a court accepts that evidence depends on jurisdiction, the judge, and the legal arguments made. FieldWitness gives your lawyer better evidence to work with.
|
||||
|
||||
**FieldWitness does not require internet access.** It was built for environments where internet access is unavailable, unreliable, or actively dangerous. Every core function -- attestation, verification, evidence export -- works on an air-gapped laptop.
|
||||
|
||||
**FieldWitness does not store your files in the cloud.** All data stays on your device (or your organization's server). Nothing is sent anywhere unless you explicitly choose to federate with a partner organization.
|
||||
|
||||
---
|
||||
|
||||
## The deeper technical story
|
||||
|
||||
This section is for developers, security reviewers, and grant evaluators who want to understand the cryptographic foundations. If you are a journalist evaluating FieldWitness, you can safely skip this -- everything above is the complete picture of what the tool does for you.
|
||||
|
||||
### Cryptographic primitives
|
||||
|
||||
- **Ed25519 digital signatures** bind each attestation to a specific identity. Ed25519 is the same signature scheme used by Signal, SSH, and WireGuard.
|
||||
- **SHA-256 cryptographic hashes** fingerprint file contents. Any modification, no matter how small, produces a completely different hash.
|
||||
- **Perceptual hashes (pHash, dHash)** for images enable verification even after an image has been re-compressed, resized, or screenshotted -- common when evidence passes through messaging apps.
|
||||
|
||||
### Append-only hash chain
|
||||
|
||||
Every attestation is recorded in an append-only hash chain -- a structure where each record includes the hash of the previous record. This means altering any record in the chain would break the hash linkage of every subsequent record. The chain is encoded in CBOR (a compact binary format) and can be independently verified without FieldWitness.
|
||||
|
||||
### Merkle tree verification
|
||||
|
||||
The chain supports Merkle tree consistency and inclusion proofs. These allow a third party to verify that a specific attestation is part of the chain without needing to download the entire chain -- important for large-scale deployments with thousands of attestations.
|
||||
|
||||
### External timestamp anchoring
|
||||
|
||||
FieldWitness supports RFC 3161 timestamping, the same standard used by Adobe, DigiCert, and other certificate authorities. A single external timestamp for the chain head implicitly timestamps every preceding record, because the chain is append-only.
|
||||
|
||||
### C2PA bridge
|
||||
|
||||
FieldWitness is building export capability to the C2PA (Coalition for Content Provenance and Authenticity) standard. This means FieldWitness attestations can be embedded in images in the format that Adobe, Microsoft, and the BBC use for content provenance -- enabling interoperability with the broader industry ecosystem.
|
||||
|
||||
### Gossip federation
|
||||
|
||||
For cross-organization deployment, FieldWitness servers synchronize attestation records using a gossip protocol. Servers periodically compare their chain state using Merkle roots. When they detect divergence, they exchange only the missing records. This design requires no central coordinator, works over intermittent connections, and supports offline synchronization via USB transfer.
|
||||
|
||||
### Field security features
|
||||
|
||||
For high-risk deployments, FieldWitness includes a killswitch (emergency data destruction), a dead man's switch (automated purge if check-in is missed), tamper detection, USB device whitelisting, and GPS geofencing. These features exist because some users work in environments where being caught with evidence is more dangerous than losing it.
|
||||
|
||||
For the full threat model and security architecture, see [docs/security/threat-model.md](../security/threat-model.md).
|
||||
|
||||
---
|
||||
|
||||
## Current status and what is needed
|
||||
|
||||
FieldWitness is a working prototype. The core attestation system, hash chain, federation protocol, and field security features are implemented and tested. It runs as a Python command-line tool and a web application.
|
||||
|
||||
**What works today:**
|
||||
|
||||
- File attestation with Ed25519 signatures and SHA-256/perceptual hashing
|
||||
- Append-only hash chain with Merkle verification
|
||||
- Self-contained evidence packages with standalone verification
|
||||
- Cross-organization federation (gossip sync and offline USB transfer)
|
||||
- Emergency data destruction (killswitch and dead man's switch)
|
||||
- Cold archive export for long-term evidence preservation
|
||||
- Web UI for all core operations
|
||||
|
||||
**What is needed:**
|
||||
|
||||
- **Security audit.** The code has not been independently audited. For a tool that journalists may rely on in adversarial conditions, an audit is a prerequisite for responsible deployment. An application to the Open Technology Fund's Red Team Lab (which commissions free audits through firms like Cure53 and Trail of Bits) is planned.
|
||||
- **Packaging for non-developers.** FieldWitness currently requires Python and pip to install. This excludes the vast majority of the target audience. A hosted demo instance, standalone desktop applications, and eventually a mobile app are needed to reach working journalists. See the [packaging strategy](packaging-strategy.md) for the roadmap.
|
||||
- **C2PA export.** Bridging to the industry standard for content provenance is in progress. See the [C2PA integration plan](c2pa-integration.md).
|
||||
- **Field testing.** The tool needs to be used by real journalists in real workflows to identify usability problems, missing features, and incorrect assumptions.
|
||||
- **Institutional review.** Organizations like the Freedom of the Press Foundation, the Electronic Frontier Foundation, and the Committee to Protect Journalists have the expertise and credibility to evaluate whether FieldWitness meets the security bar for their constituents.
|
||||
|
||||
FieldWitness is open source (GPL-3.0) and welcomes collaboration -- from code contributions and security review to feedback on whether this tool solves a problem you actually have. The most valuable contribution right now is honest criticism from people who work in journalism, human rights documentation, or digital security.
|
||||
|
||||
Source code: [github.com/alee/fieldwitness](https://github.com/alee/fieldwitness)
|
||||
488
docs/security/threat-model.md
Normal file
488
docs/security/threat-model.md
Normal file
@ -0,0 +1,488 @@
|
||||
# FieldWitness Threat Model
|
||||
|
||||
**Status:** Living document -- updated as the design evolves and as external review
|
||||
identifies gaps. Version numbers track significant revisions.
|
||||
|
||||
**Document version:** 0.1 (2026-04-01)
|
||||
**Corresponds to:** FieldWitness v0.3.0
|
||||
|
||||
This document follows the style of the Signal Protocol specification and the Tor design
|
||||
document: it makes precise claims, distinguishes what is guaranteed from what is not, and
|
||||
does not use marketing language. Unresolved questions and known gaps are stated plainly.
|
||||
|
||||
**This document has not been externally audited.** Claims here reflect the designer's
|
||||
intent and analysis. An independent security review is planned as part of Phase 2 (see
|
||||
`docs/planning/gtm-feasibility.md`). Until that review is complete, treat this document
|
||||
as a design statement, not a security certification.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Intended Users](#1-intended-users)
|
||||
2. [Adversary Model](#2-adversary-model)
|
||||
3. [Assets Protected](#3-assets-protected)
|
||||
4. [Trust Boundaries](#4-trust-boundaries)
|
||||
5. [Security Guarantees](#5-security-guarantees)
|
||||
6. [Non-Guarantees](#6-non-guarantees)
|
||||
7. [Cryptographic Primitives](#7-cryptographic-primitives)
|
||||
8. [Key Management Model](#8-key-management-model)
|
||||
9. [Federation Trust Model](#9-federation-trust-model)
|
||||
10. [Known Limitations](#10-known-limitations)
|
||||
|
||||
---
|
||||
|
||||
## 1. Intended Users
|
||||
|
||||
FieldWitness is designed for three overlapping user populations:
|
||||
|
||||
**Field reporters and documenters.** Journalists, human rights monitors, and election
|
||||
observers working in environments where physical device seizure is a plausible risk.
|
||||
Operating assumption: the user may be detained, the device may be confiscated, and the
|
||||
operator at Tier 2 (the org server) may not be reachable in real time. The user needs to
|
||||
attest evidence locally on a Tier 1 (field device) and sync later -- or never, if the USB
|
||||
is destroyed.
|
||||
|
||||
**Organizational administrators.** IT staff and security-aware operators at newsrooms or
|
||||
NGOs running Tier 2 deployments. They manage keys, configure threat levels, operate the
|
||||
source drop box, and maintain federation peering with partner organizations. They are
|
||||
expected to understand basic operational security concepts but are not expected to be
|
||||
cryptographers.
|
||||
|
||||
**Partner organizations.** Organizations that receive attested evidence bundles from the
|
||||
primary organization and need to verify chain-of-custody without installing FieldWitness. They
|
||||
interact with standalone `verify.py` scripts included in evidence packages.
|
||||
|
||||
FieldWitness is **not** designed as a general-purpose secure communications tool, a replacement
|
||||
for SecureDrop's source protection model, or a consumer privacy application.
|
||||
|
||||
---
|
||||
|
||||
## 2. Adversary Model
|
||||
|
||||
### 2.1 Passive Network Observer
|
||||
|
||||
**Capability:** Can observe all network traffic between nodes, including Tier 2 to Tier 3
|
||||
communication and gossip federation traffic. Cannot break TLS or Ed25519.
|
||||
|
||||
**Goal:** Determine which organizations are communicating, the timing and volume of
|
||||
attestation syncs, and potentially correlate sync events with news events.
|
||||
|
||||
**FieldWitness's position:** Transport-level metadata (IP addresses, timing, volume) is not
|
||||
hidden. TLS (self-signed, port 8000) protects payload content. A passive observer can
|
||||
determine that two Tier 2 servers are federating; they cannot read the attestation records
|
||||
being exchanged without the relevant Ed25519 public keys.
|
||||
|
||||
**Gap:** No traffic padding, no onion routing, no anonymization of federation topology.
|
||||
Organizations with strong network-level adversaries should route federation traffic through
|
||||
Tor or a VPN. This is not built in.
|
||||
|
||||
### 2.2 Active Network Adversary
|
||||
|
||||
**Capability:** Can intercept, modify, replay, and drop traffic. Can present forged
|
||||
TLS certificates if the operator hasn't pinned the peer's certificate.
|
||||
|
||||
**Goal:** Inject forged attestation records into the federation, suppress legitimate
|
||||
records, or cause evidence to appear tampered.
|
||||
|
||||
**FieldWitness's position:** All attestation records are Ed25519-signed. A network adversary
|
||||
cannot forge a valid signature without the private key. The append-only hash chain makes
|
||||
retroactive injection detectable: inserting a record at position N requires recomputing all
|
||||
subsequent hashes. Consistency proofs during gossip sync detect log divergence.
|
||||
|
||||
**Gap:** Certificate pinning for federation peers is not implemented as of v0.3.0. The
|
||||
Tier 3 relay uses a self-signed certificate; operators should verify its fingerprint
|
||||
out-of-band. Gossip peers authenticate by Ed25519 fingerprint, not certificate, which
|
||||
provides a secondary check.
|
||||
|
||||
### 2.3 Physical Access
|
||||
|
||||
**Capability:** Has physical access to the field device (Tier 1 USB) or the org server
|
||||
(Tier 2). May have forensic tools.
|
||||
|
||||
**Goal:** Extract private keys, recover attested evidence, identify the operator, or
|
||||
determine what evidence was collected.
|
||||
|
||||
**FieldWitness's position:**
|
||||
|
||||
- Tier 1 is designed for amnesia: Debian Live USB with LUKS-encrypted persistent
|
||||
partition. Pulling the USB from the host leaves no trace on the host machine. If the USB
|
||||
itself is seized, LUKS protects the persistent partition.
|
||||
- The killswitch (`fieldwitness fieldkit purge`) destroys all key material and data under
|
||||
`~/.fwmetadata/` in sensitivity order. The deep forensic scrub removes Python bytecache, pip
|
||||
metadata, download cache, and shell history entries. The final step is `pip uninstall
|
||||
-y fieldwitness`.
|
||||
- The dead man's switch fires the killswitch automatically if check-in is missed.
|
||||
- Private keys are stored as PEM files with `0600` permissions. Key material is not
|
||||
additionally encrypted at rest beyond the filesystem (LUKS on Tier 1; operator-managed
|
||||
on Tier 2).
|
||||
|
||||
**Gap:** If the device is seized before the killswitch fires and LUKS has been unlocked
|
||||
(i.e., the device is running), private keys are accessible. Cold boot attacks against
|
||||
unlocked LUKS volumes are not mitigated. Key material is not stored in a hardware security
|
||||
module or OS keychain.
|
||||
|
||||
### 2.4 Legal Compulsion
|
||||
|
||||
**Capability:** Can compel the operator (or their legal jurisdiction) to produce data,
|
||||
keys, or records. May use court orders, search warrants, or jurisdiction-specific
|
||||
administrative processes.
|
||||
|
||||
**Goal:** Obtain attestation records or private keys under legal authority.
|
||||
|
||||
**FieldWitness's position:** FieldWitness provides tools (selective disclosure, evidence packages)
|
||||
for producing specific records under court order without revealing the full chain.
|
||||
The Federation Relay (Tier 3) stores only hashes and signatures -- never private keys or
|
||||
plaintext. Placing Tier 3 in a jurisdiction with strong press protections limits one
|
||||
compulsion surface.
|
||||
|
||||
**Gap:** If private keys are seized, all past and future attestations signed by those keys
|
||||
are attributable to the key holder. Key rotation limits forward exposure after a
|
||||
compromise, but prior records signed by the old key remain attributable. FieldWitness does not
|
||||
implement deniable authentication.
|
||||
|
||||
### 2.5 Insider Threat
|
||||
|
||||
**Capability:** Has legitimate access to the FieldWitness instance (e.g., a trusted
|
||||
administrator or a compromised org server). Can read key material, attestation records,
|
||||
and logs.
|
||||
|
||||
**Goal:** Selectively alter or delete records, export keys, or suppress evidence.
|
||||
|
||||
**FieldWitness's position:** The append-only hash chain makes deletion or modification of prior
|
||||
records detectable: the chain head hash changes and any external anchor (RFC 3161 TSA,
|
||||
blockchain transaction) will no longer match. Key rotation is logged in the chain as a
|
||||
`fieldwitness/key-rotation-v1` record signed by the old key, creating an auditable trail.
|
||||
|
||||
**Gap:** An insider with direct filesystem access can overwrite `chain.bin` entirely,
|
||||
including the chain head, before an external anchor is taken. The chain provides integrity
|
||||
guarantees only to the extent that external anchors are taken regularly and independently
|
||||
(by another party or a public TSA). Frequency of anchoring is an operational decision, not
|
||||
enforced by the software.
|
||||
|
||||
---
|
||||
|
||||
## 3. Assets Protected
|
||||
|
||||
The following assets are in scope for FieldWitness's security model:
|
||||
|
||||
| Asset | Description | Primary Protection |
|
||||
|---|---|---|
|
||||
| Attestation records | Ed25519-signed records linking a file hash to a time, identity, and optional metadata | Append-only chain, Ed25519 signatures |
|
||||
| Identity private key | Ed25519 private key used to sign attestations | `0600` filesystem permissions, LUKS on Tier 1, killswitch |
|
||||
| Channel key | AES-256-GCM key used for steganographic encoding | `0600` filesystem permissions, separate from identity key |
|
||||
| Source submissions | Anonymous uploads through the drop box | EXIF stripping, no-branding upload page, HMAC receipt codes |
|
||||
| Evidentiary metadata | GPS, timestamp, device model extracted from EXIF | Stored in attestation record, dangerous fields stripped |
|
||||
| Federation topology | Which organizations are peering | Not protected at network level (see 2.1) |
|
||||
|
||||
The following are **out of scope** (not protected by FieldWitness):
|
||||
|
||||
- Source identity beyond what is stripped from EXIF
|
||||
- Operator identity (FieldWitness does not provide anonymity)
|
||||
- Content of files beyond what is hashed and signed (files are not encrypted at rest
|
||||
unless encrypted before attestation)
|
||||
- The Tier 3 relay's knowledge of federation topology
|
||||
|
||||
---
|
||||
|
||||
## 4. Trust Boundaries
|
||||
|
||||
```
|
||||
[Field reporter / Tier 1] --- LUKS + killswitch --- [Seized device adversary]
|
||||
|
|
||||
[USB sneakernet or LAN]
|
||||
|
|
||||
[Org Server / Tier 2] ------- TLS (self-signed) ---- [Network adversary]
|
||||
| [Active attacker: no forged sigs]
|
||||
[Gossip federation]
|
||||
|
|
||||
[Federation Relay / Tier 3] - Stores hashes+sigs only, no keys
|
||||
|
|
||||
[Partner Org / Tier 2] ------ Ed25519 trust store -- [Untrusted peers rejected]
|
||||
|
|
||||
[Verifying party] ----------- standalone verify.py, cryptography package only
|
||||
```
|
||||
|
||||
**Tier 1 trusts:** Its own key material (generated locally), the Tier 2 server it was
|
||||
configured to sync with.
|
||||
|
||||
**Tier 2 trusts:** Its own key material, the Ed25519 public keys in its trust store
|
||||
(imported explicitly by the administrator), the Tier 3 relay for transport only (not
|
||||
content validation).
|
||||
|
||||
**Tier 3 trusts:** Nothing. It is a content-unaware relay. It cannot validate the
|
||||
semantic content of what it stores because it has no access to private keys.
|
||||
|
||||
**Verifying party trusts:** The signer's Ed25519 public key (received out-of-band, e.g.,
|
||||
in the evidence package), the `cryptography` Python package, and the chain linkage logic
|
||||
in `verify.py`.
|
||||
|
||||
---
|
||||
|
||||
## 5. Security Guarantees
|
||||
|
||||
The following are properties FieldWitness is designed to provide. Each is conditional on the
|
||||
named preconditions.
|
||||
|
||||
**G1: Attestation integrity.** Given an attestation record and the signer's Ed25519 public
|
||||
key, a verifier can determine whether the record has been modified since signing.
|
||||
_Precondition:_ The verifier has the correct public key and the `cryptography` package.
|
||||
_Mechanism:_ Ed25519 signature over deterministic JSON serialization of the record.
|
||||
|
||||
**G2: Chain append-only property.** If a record is in the chain at position N, it cannot
|
||||
be removed or modified without invalidating every subsequent record's hash linkage.
|
||||
_Precondition:_ The verifier has observed the chain head at some prior point or has an
|
||||
external anchor.
|
||||
_Mechanism:_ Each record includes `prev_hash = SHA-256(canonical_bytes(record[N-1]))`.
|
||||
|
||||
**G3: Timestamp lower bound.** If the chain head has been submitted to an RFC 3161 TSA
|
||||
and the token is preserved, all records prior to the anchored head provably existed before
|
||||
the TSA's signing time.
|
||||
_Precondition:_ The TSA's clock and signing key are trusted.
|
||||
_Mechanism:_ RFC 3161 timestamp tokens stored in `chain/anchors/`.
|
||||
|
||||
**G4: Selective disclosure soundness.** A selective disclosure bundle proves that the
|
||||
disclosed records are part of an unbroken chain without revealing the contents of
|
||||
non-disclosed records.
|
||||
_Precondition:_ The verifier has the chain head hash from an external source.
|
||||
_Mechanism:_ Non-selected records appear as hashes only; chain linkage is preserved.
|
||||
|
||||
**G5: Federation record authenticity.** Records received via federation are accepted only
|
||||
if signed by a key in the local trust store.
|
||||
_Precondition:_ The trust store contains only keys the operator has explicitly imported.
|
||||
_Mechanism:_ Ed25519 verification against trust store before appending federated records.
|
||||
|
||||
**G6: Source drop box anonymity (limited).** A source submitting via the drop box does
|
||||
not need an account, FieldWitness is not mentioned on the upload page, and dangerous EXIF fields
|
||||
are stripped before the file is stored.
|
||||
_Precondition:_ The source accesses the drop box URL over HTTPS without revealing their
|
||||
identity through other means (IP, browser fingerprint, etc.).
|
||||
_Limitation:_ FieldWitness does not route drop box traffic through Tor or any anonymization
|
||||
layer. Network-level anonymity is the source's responsibility.
|
||||
|
||||
---
|
||||
|
||||
## 6. Non-Guarantees
|
||||
|
||||
The following properties are explicitly **not** provided by FieldWitness. Including them here
|
||||
prevents users from assuming protection that does not exist.
|
||||
|
||||
**NG1: Operator anonymity.** FieldWitness does not hide the identity of the organization
|
||||
running the instance. The Tier 2 server has an IP address. The federation relay knows
|
||||
which Tier 2 servers are peering.
|
||||
|
||||
**NG2: Deniable authentication.** Attestation records are non-repudiably signed by
|
||||
Ed25519 keys. There is no plausible deniability about which key produced a signature.
|
||||
|
||||
**NG3: Forward secrecy for attestation keys.** Ed25519 identity keys are long-lived.
|
||||
If a private key is compromised, all attestations signed by that key are attributable to
|
||||
the key holder. Key rotation limits future exposure but does not retroactively remove
|
||||
attributability.
|
||||
|
||||
**NG4: Protection against a compromised Tier 2 before anchoring.** An insider with full
|
||||
Tier 2 access can rewrite the chain before any external anchor is taken. External anchors
|
||||
are the primary protection against insider tampering; their value is proportional to how
|
||||
frequently and independently they are taken.
|
||||
|
||||
**NG5: Content confidentiality.** FieldWitness does not encrypt attested files at rest. Files
|
||||
are hashed and signed, not encrypted. Encryption before attestation is the operator's
|
||||
responsibility.
|
||||
|
||||
**NG6: Source protection beyond EXIF stripping.** The drop box strips dangerous EXIF
|
||||
fields and does not log source IP addresses in attestation records. It does not provide
|
||||
the same source protection model as SecureDrop. Organizations with strong source
|
||||
protection requirements should use SecureDrop for intake and FieldWitness for evidence chain
|
||||
management.
|
||||
|
||||
**NG7: Auditability of the Tier 3 relay.** The relay stores only hashes and signatures,
|
||||
but FieldWitness does not currently provide a mechanism for operators to audit what the relay
|
||||
has and has not forwarded. The relay is trusted for availability, not integrity.
|
||||
|
||||
---
|
||||
|
||||
## 7. Cryptographic Primitives
|
||||
|
||||
All cryptographic choices are documented here to support independent review and long-term
|
||||
archival verifiability.
|
||||
|
||||
### Signing
|
||||
|
||||
| Primitive | Algorithm | Parameters | Use |
|
||||
|---|---|---|---|
|
||||
| Identity signing | Ed25519 | RFC 8032 | Sign attestation records, key rotation records, delivery acks |
|
||||
| Key storage | PEM | PKCS8 (private), SubjectPublicKeyInfo (public) | Disk format for identity keypair |
|
||||
|
||||
Ed25519 was chosen for: short key and signature sizes (32-byte public key, 64-byte
|
||||
signature), deterministic signing (no random oracle required per operation), strong
|
||||
security margins, and wide library support.
|
||||
|
||||
### Encryption (Stego channel key domain)
|
||||
|
||||
| Primitive | Algorithm | Parameters | Use |
|
||||
|---|---|---|---|
|
||||
| Symmetric encryption | AES-256-GCM | 256-bit key, 96-bit IV, 128-bit tag | Payload encryption in stego encode |
|
||||
| Key derivation | Argon2id | time=3, memory=65536, parallelism=4, saltlen=16 | Derive AES key from passphrase + PIN + reference photo fingerprint |
|
||||
|
||||
**Note:** The AES-256-GCM channel key domain (Stego) and the Ed25519 identity key
|
||||
domain (Attest) are kept strictly separate. They serve different security purposes and
|
||||
share no key material.
|
||||
|
||||
### Hashing
|
||||
|
||||
| Primitive | Algorithm | Use |
|
||||
|---|---|---|
|
||||
| Cryptographic hash | SHA-256 | Chain record linkage (`prev_hash`), content fingerprinting |
|
||||
| Content fingerprinting | SHA-256 | `ImageHashes.sha256` for all file types |
|
||||
| Perceptual hash | pHash (DCT-based) | Image tamper detection, survives compression |
|
||||
| Perceptual hash | dHash (difference hash) | Image tamper detection |
|
||||
| Perceptual hash | aHash (average hash) | Fuzzy matching, high tolerance |
|
||||
| Chain serialization | CBOR (RFC 7049) | Canonical encoding for chain records |
|
||||
| HMAC | HMAC-SHA256 | Drop box receipt code derivation |
|
||||
|
||||
### External Timestamping
|
||||
|
||||
| Mechanism | Standard | Use |
|
||||
|---|---|---|
|
||||
| RFC 3161 TSA | RFC 3161 | Automated, signed timestamp tokens |
|
||||
| Manual anchor | Any external witness | Chain head hash submitted to blockchain, email, etc. |
|
||||
|
||||
---
|
||||
|
||||
## 8. Key Management Model
|
||||
|
||||
### Key types and locations
|
||||
|
||||
| Key | Type | Location | Purpose |
|
||||
|---|---|---|---|
|
||||
| Identity private key | Ed25519 | `~/.fwmetadata/identity/private.pem` | Sign all attestation records |
|
||||
| Identity public key | Ed25519 | `~/.fwmetadata/identity/public.pem` | Shared with verifiers; included in evidence packages |
|
||||
| Channel key | AES-256-GCM | `~/.fwmetadata/stego/channel.key` | Stego encoding/decoding shared secret |
|
||||
| Trust store keys | Ed25519 (public only) | `~/.fwmetadata/trusted_keys/<fingerprint>/` | Verify federated records from partners |
|
||||
|
||||
### Key rotation
|
||||
|
||||
Identity rotation creates a `fieldwitness/key-rotation-v1` chain record signed by the **old**
|
||||
key, containing the new public key. This establishes a cryptographic chain of trust from
|
||||
the original key through all rotations. Verifiers following the rotation chain can confirm
|
||||
that new attestations come from the same organizational identity as old ones.
|
||||
|
||||
Channel (AES) key rotation creates a new key and archives the old one. Old channel keys
|
||||
are required to decode stego payloads encoded with them; archived keys are preserved under
|
||||
`~/.fwmetadata/stego/archived/`.
|
||||
|
||||
### Identity recovery
|
||||
|
||||
After device loss, a `fieldwitness/key-recovery-v1` chain record is signed by the **new** key,
|
||||
carrying the old key's fingerprint and optional cosigner fingerprints. This is an
|
||||
auditable assertion, not a cryptographic proof that the old key authorized the recovery
|
||||
(the old key is lost). The recovery record's legitimacy depends on out-of-band
|
||||
confirmation (e.g., cosigner verification, organizational attestation).
|
||||
|
||||
### Backup
|
||||
|
||||
The keystore manager (`fieldwitness/keystore/manager.py`) tracks backup state. Encrypted key
|
||||
bundles can be exported to the SOOBNDL format for cold storage. The backup reminder
|
||||
interval is configurable; the default is 7 days.
|
||||
|
||||
---
|
||||
|
||||
## 9. Federation Trust Model
|
||||
|
||||
### Peer authentication
|
||||
|
||||
Federation peers are identified by their Ed25519 public key fingerprint (first 16 bytes of
|
||||
SHA-256 of the public key, hex-encoded). Peering is established by explicit administrator
|
||||
action: the peer's public key fingerprint is configured locally. There is no automatic
|
||||
peer discovery or trust-on-first-use.
|
||||
|
||||
### Record acceptance
|
||||
|
||||
A record received via federation is accepted only if:
|
||||
1. It is signed by an Ed25519 key in the local trust store.
|
||||
2. The signature is valid over the record's canonical serialization.
|
||||
3. The record does not duplicate a record already in the local log (by record ID).
|
||||
|
||||
Records signed by unknown keys are silently dropped. There is no mechanism to accept
|
||||
records from temporarily trusted but unregistered peers.
|
||||
|
||||
### The Tier 3 relay
|
||||
|
||||
The Tier 3 relay is a content-unaware intermediary. It forwards attestation bundles between
|
||||
Tier 2 nodes but has no access to private keys and cannot validate the semantic content of
|
||||
records. It is trusted for availability (it should forward what it receives) but not for
|
||||
integrity (it cannot be used as an authority for whether records are authentic).
|
||||
|
||||
### Consistency proofs
|
||||
|
||||
During gossip sync, nodes exchange their current Merkle log root and size. If roots
|
||||
differ, the node with fewer records requests a consistency proof from the node with more
|
||||
records. The consistency proof proves that the smaller log is a prefix of the larger log,
|
||||
preventing log divergence. Records are fetched incrementally after the proof verifies.
|
||||
|
||||
The consistency proof implementation is in `src/fieldwitness/attest/merkle.py`.
|
||||
|
||||
---
|
||||
|
||||
## 10. Known Limitations
|
||||
|
||||
This section is a candid accounting of current gaps. Items here are candidates for future
|
||||
work, not dismissals.
|
||||
|
||||
**L1: No hardware key storage.** Private keys are stored as PEM files protected only by
|
||||
filesystem permissions and LUKS (on Tier 1). A hardware security module (HSM), TPM, or OS
|
||||
keychain would provide stronger protection against physical extraction from a running
|
||||
system. This is a significant gap for high-threat deployments.
|
||||
|
||||
**L2: No certificate pinning for federation.** Tier 2 to Tier 3 connections use TLS with
|
||||
self-signed certificates. The peer's certificate fingerprint is not currently pinned in
|
||||
configuration. An active network adversary with the ability to present a forged certificate
|
||||
could intercept federation traffic. The Ed25519 peer fingerprint provides a secondary check
|
||||
but is not a substitute.
|
||||
|
||||
**L3: Killswitch reliability.** The killswitch's effectiveness depends on the operating
|
||||
system's file deletion semantics. On HDDs without secure erase, file overwriting may not
|
||||
prevent forensic recovery. On SSDs with wear leveling, even overwriting does not guarantee
|
||||
physical deletion. The deep forensic scrub does multiple passes, but this is not
|
||||
equivalent to verified physical destruction. For critical-threat deployments, physical
|
||||
destruction of storage media is more reliable than software scrub.
|
||||
|
||||
**L4: Anchor frequency is an operational decision.** The chain's tamper-evidence
|
||||
properties against insider threats depend on how frequently external anchors are taken.
|
||||
FieldWitness does not enforce or automate anchor frequency. An organization that anchors
|
||||
infrequently has a larger window during which insider tampering is undetectable.
|
||||
|
||||
**L5: Gossip topology is not hidden.** The list of peers a node gossips with is visible
|
||||
to a network observer. For organizations where federation topology is itself sensitive
|
||||
information, all federation should be routed through Tor or equivalent.
|
||||
|
||||
**L6: No audit of Tier 3 relay behavior.** FieldWitness does not currently provide a way for
|
||||
operators to verify that the Tier 3 relay has faithfully forwarded all bundles it received.
|
||||
A malicious or compromised relay could suppress specific records. The design mitigation is
|
||||
to use the relay only for transport, never as an authoritative source -- but no
|
||||
verification mechanism is implemented.
|
||||
|
||||
**L7: Drop box source anonymity is limited -- Tor support available.** The drop box does
|
||||
not log source IP addresses in attestation records or require accounts. FieldWitness now
|
||||
includes built-in Tor hidden service support: starting the server with `--tor` exposes the
|
||||
drop box as a `.onion` address so that source IPs are never visible to the server operator.
|
||||
|
||||
Without `--tor`, a source's IP address is visible in web server access logs.
|
||||
Organizations with source-protection requirements should use the `--tor` flag and instruct
|
||||
sources to access the drop box only via Tor Browser. Operators should also configure any
|
||||
reverse proxy to suppress access logging for `/dropbox/upload/` paths.
|
||||
|
||||
Even with Tor, timing analysis and traffic correlation attacks are possible at the network
|
||||
level. Tor eliminates IP exposure at the server; it does not protect against a global
|
||||
adversary correlating traffic timing. See `docs/source-dropbox.md` for setup instructions.
|
||||
|
||||
**L8: Steganalysis resistance is not guaranteed.** The steganography backend includes a
|
||||
steganalysis module (`stego/steganalysis.py`) for estimating detection resistance, but
|
||||
stego channels are not guaranteed to be undetectable by modern ML-based steganalysis tools
|
||||
under all conditions. Stego should be treated as a covert channel with meaningful
|
||||
detection risk, not a guaranteed-invisible channel.
|
||||
|
||||
**L9: No formal security proof.** The security of FieldWitness's federation protocol, chain
|
||||
construction, and selective disclosure has not been formally analyzed. The design draws on
|
||||
established primitives (Ed25519, SHA-256, RFC 3161, Merkle trees) and patterns (gossip,
|
||||
append-only logs, Certificate Transparency-inspired consistency proofs), but informal
|
||||
design analysis is not a substitute for a formal proof or an independent security audit.
|
||||
349
docs/source-dropbox.md
Normal file
349
docs/source-dropbox.md
Normal file
@ -0,0 +1,349 @@
|
||||
# Source Drop Box Setup Guide
|
||||
|
||||
**Audience**: Administrators setting up FieldWitness's anonymous source intake feature.
|
||||
|
||||
**Prerequisites**: A running FieldWitness instance with web UI enabled (`fieldwitness[web]` extra),
|
||||
an admin account, and HTTPS configured (self-signed is acceptable).
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The source drop box is a SecureDrop-style anonymous file intake built into the FieldWitness web
|
||||
UI. Admins create time-limited upload tokens, sources open the token URL in a browser and
|
||||
submit files without creating an account. Files are processed through the extract-then-strip
|
||||
EXIF pipeline and automatically attested on receipt. Sources receive HMAC-derived receipt
|
||||
codes that prove delivery.
|
||||
|
||||
> **Warning:** The drop box protects source identity through design -- no accounts, no
|
||||
> branding, no IP logging. However, the security of the system depends on how the upload URL
|
||||
> is shared. Never send drop box URLs over unencrypted email or SMS.
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
Admin Source FieldWitness Server
|
||||
| | |
|
||||
|-- Create token ------------->| |
|
||||
| (label, expiry, max_files) | |
|
||||
| | |
|
||||
|-- Share URL (secure channel) | |
|
||||
| | |
|
||||
| |-- Open URL in browser --------->|
|
||||
| | (no login required) |
|
||||
| | |
|
||||
| |-- Select files |
|
||||
| | Browser computes SHA-256 |
|
||||
| | (SubtleCrypto, client-side) |
|
||||
| | |
|
||||
| |-- Upload files ---------------->|
|
||||
| | |-- Extract EXIF
|
||||
| | |-- Strip metadata
|
||||
| | |-- Attest originals
|
||||
| | |-- Save stripped copy
|
||||
| | |
|
||||
| |<-- Receipt codes ---------------|
|
||||
| | (HMAC of file hash + token) |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Setting Up the Drop Box
|
||||
|
||||
### Step 1: Ensure HTTPS is enabled
|
||||
|
||||
The drop box should always be served over HTTPS. Sources must be able to trust that their
|
||||
connection is not being intercepted.
|
||||
|
||||
```bash
|
||||
$ fieldwitness serve --host 0.0.0.0
|
||||
```
|
||||
|
||||
FieldWitness auto-generates a self-signed certificate on first HTTPS start. For production use,
|
||||
place a reverse proxy with a proper TLS certificate in front of FieldWitness.
|
||||
|
||||
### Step 2: Create an upload token
|
||||
|
||||
Navigate to `/dropbox/admin` in the web UI (admin login required), or use the admin panel.
|
||||
|
||||
Each token has:
|
||||
|
||||
| Field | Default | Description |
|
||||
|---|---|---|
|
||||
| **Label** | "Unnamed source" | Human-readable name for the source (stored server-side only, never shown to the source) |
|
||||
| **Expiry** | 24 hours | How long the upload link remains valid |
|
||||
| **Max files** | 10 | Maximum number of uploads allowed on this link |
|
||||
|
||||
After creating the token, the admin receives a URL of the form:
|
||||
|
||||
```
|
||||
https://<host>:<port>/dropbox/upload/<token>
|
||||
```
|
||||
|
||||
The token is a 32-byte cryptographically random URL-safe string.
|
||||
|
||||
### Step 3: Share the URL with the source
|
||||
|
||||
Share the upload URL over an already-secure channel:
|
||||
|
||||
- **Best**: in person, on paper
|
||||
- **Good**: encrypted messaging (Signal, Wire)
|
||||
- **Acceptable**: verbal dictation over a secure voice call
|
||||
- **Never**: unencrypted email, SMS, or any channel that could be intercepted
|
||||
|
||||
### Step 4: Source uploads files
|
||||
|
||||
The source opens the URL in their browser. The upload page is minimal -- no FieldWitness branding,
|
||||
no identifying marks, generic styling. The page works over Tor Browser with JavaScript
|
||||
enabled (no external resources, no CDN, no fonts, no analytics).
|
||||
|
||||
When files are selected:
|
||||
|
||||
1. The browser computes SHA-256 fingerprints client-side using SubtleCrypto
|
||||
2. The source sees the fingerprints and is prompted to save them before uploading
|
||||
3. On upload, the server processes each file through the extract-then-strip pipeline
|
||||
4. The source receives receipt codes for each file
|
||||
|
||||
### Step 5: Monitor submissions
|
||||
|
||||
The admin panel at `/dropbox/admin` shows:
|
||||
|
||||
- Active tokens with their usage counts
|
||||
- Token expiry times
|
||||
- Ability to revoke tokens immediately
|
||||
|
||||
---
|
||||
|
||||
## The Extract-Then-Strip Pipeline
|
||||
|
||||
Every file uploaded through the drop box is processed through FieldWitness's EXIF pipeline:
|
||||
|
||||
1. **Extract**: all EXIF metadata is read from the original image bytes
|
||||
2. **Classify**: fields are split into evidentiary (GPS coordinates, capture timestamp --
|
||||
valuable for provenance) and dangerous (device serial number, firmware version -- could
|
||||
identify the source's device)
|
||||
3. **Attest**: the original bytes are attested (Ed25519 signed) with evidentiary metadata
|
||||
included in the attestation record. The attestation hash matches what the source actually
|
||||
submitted.
|
||||
4. **Strip**: all metadata is removed from the stored copy. The stripped copy is saved to
|
||||
disk. No device fingerprint persists on the server's storage.
|
||||
|
||||
This resolves the tension between protecting the source (strip device-identifying metadata)
|
||||
and preserving evidence (retain GPS and timestamp for provenance).
|
||||
|
||||
---
|
||||
|
||||
## Receipt Codes
|
||||
|
||||
Each uploaded file generates an HMAC-derived receipt code:
|
||||
|
||||
```
|
||||
receipt_code = HMAC-SHA256(token, file_sha256)[:16]
|
||||
```
|
||||
|
||||
The receipt code proves:
|
||||
|
||||
- The server received the specific file (tied to the file's SHA-256)
|
||||
- The file was received under the specific token (tied to the token value)
|
||||
|
||||
Sources can verify their receipt by posting it to `/dropbox/verify-receipt`. This returns
|
||||
the filename, SHA-256, and reception timestamp if the receipt is valid.
|
||||
|
||||
> **Note:** Receipt codes are deterministic. The source can compute the expected receipt
|
||||
> themselves if they know the token value and the file's SHA-256 hash, providing
|
||||
> independent verification.
|
||||
|
||||
---
|
||||
|
||||
## Client-Side SHA-256
|
||||
|
||||
The upload page computes SHA-256 fingerprints in the browser before upload using the
|
||||
SubtleCrypto Web API. This gives the source a verifiable record of exactly what they
|
||||
submitted -- the hash is computed on their device, not the server.
|
||||
|
||||
The source should save these fingerprints before uploading. If the server later claims to
|
||||
have received different content, the source can prove what they actually submitted by
|
||||
comparing their locally computed hash with the server's receipt.
|
||||
|
||||
---
|
||||
|
||||
## Storage
|
||||
|
||||
| What | Where |
|
||||
|---|---|
|
||||
| Uploaded files (stripped) | `~/.fwmetadata/temp/dropbox/` (mode 0700) |
|
||||
| Token metadata | `~/.fwmetadata/auth/dropbox.db` (SQLite) |
|
||||
| Receipt codes | `~/.fwmetadata/auth/dropbox.db` (SQLite) |
|
||||
| Attestation records | `~/.fwmetadata/attestations/` (standard attestation log) |
|
||||
|
||||
Expired tokens are cleaned up automatically on every admin page load.
|
||||
|
||||
---
|
||||
|
||||
## Operational Security
|
||||
|
||||
### Source safety
|
||||
|
||||
- **No FieldWitness branding** on the upload page. Generic "Secure File Upload" title.
|
||||
- **No authentication required** -- sources never create accounts or reveal identity.
|
||||
- **No IP logging** -- FieldWitness does not log source IP addresses. Ensure your reverse proxy
|
||||
(if any) also does not log access requests to `/dropbox/upload/` paths.
|
||||
- **Self-contained page** -- inline CSS and JavaScript only. No external resources, CDN
|
||||
calls, web fonts, or analytics. Works with Tor Browser.
|
||||
- **CSRF exempt** -- the upload endpoint does not require CSRF tokens because sources do
|
||||
not have sessions.
|
||||
|
||||
### Token management
|
||||
|
||||
- **Short expiry** -- set token expiry as short as practical. 24 hours is the default; for
|
||||
high-risk sources, consider 1-4 hours.
|
||||
- **Low file limits** -- set `max_files` to the expected number of submissions.
|
||||
Once reached, the link stops accepting uploads.
|
||||
- **Revoke immediately** -- if a token is compromised or no longer needed, revoke it from
|
||||
the admin panel. This deletes the token and all associated receipt records from SQLite.
|
||||
- **Audit trail** -- token creation events are logged to `~/.fwmetadata/audit.jsonl` with the
|
||||
action `dropbox.token_created`.
|
||||
|
||||
### Running as a Tor hidden service
|
||||
|
||||
FieldWitness has built-in support for exposing the drop box as a Tor hidden service
|
||||
(a `.onion` address). When a source accesses the drop box over Tor, the server never
|
||||
sees their real IP address -- Tor's onion routing ensures that only the Tor network knows
|
||||
both the source and the destination.
|
||||
|
||||
#### Step 1: Install and configure Tor
|
||||
|
||||
```bash
|
||||
# Debian / Ubuntu
|
||||
sudo apt install tor
|
||||
|
||||
# macOS (Homebrew)
|
||||
brew install tor
|
||||
|
||||
# Fedora / RHEL
|
||||
sudo dnf install tor
|
||||
```
|
||||
|
||||
Enable the control port so FieldWitness can manage the hidden service. Add these lines
|
||||
to `/etc/tor/torrc`:
|
||||
|
||||
```
|
||||
ControlPort 9051
|
||||
CookieAuthentication 1
|
||||
```
|
||||
|
||||
Then restart Tor:
|
||||
|
||||
```bash
|
||||
sudo systemctl restart tor
|
||||
```
|
||||
|
||||
**Authentication note:** `CookieAuthentication 1` lets FieldWitness authenticate using the
|
||||
cookie file that Tor creates automatically. Alternatively, use a password:
|
||||
|
||||
```
|
||||
ControlPort 9051
|
||||
HashedControlPassword <hash produced by: tor --hash-password yourpassword>
|
||||
```
|
||||
|
||||
#### Step 2: Install the stem library
|
||||
|
||||
stem is an optional FieldWitness dependency. Install it alongside the fieldkit extra:
|
||||
|
||||
```bash
|
||||
pip install 'fieldwitness[tor]'
|
||||
# or, if already installed:
|
||||
pip install stem>=1.8.0
|
||||
```
|
||||
|
||||
#### Step 3: Start FieldWitness with --tor
|
||||
|
||||
```bash
|
||||
fieldwitness serve --host 127.0.0.1 --port 5000 --tor
|
||||
```
|
||||
|
||||
With a custom control port or password:
|
||||
|
||||
```bash
|
||||
fieldwitness serve --tor --tor-control-port 9051 --tor-password yourpassword
|
||||
```
|
||||
|
||||
For a one-off intake session where a fixed address is not needed:
|
||||
|
||||
```bash
|
||||
fieldwitness serve --tor --tor-transient
|
||||
```
|
||||
|
||||
On startup, FieldWitness will print the `.onion` address:
|
||||
|
||||
```
|
||||
============================================================
|
||||
TOR HIDDEN SERVICE ACTIVE
|
||||
============================================================
|
||||
.onion address : abc123def456ghi789jkl012mno345pq.onion
|
||||
Drop box URL : http://abc123def456ghi789jkl012mno345pq.onion/dropbox/upload/<token>
|
||||
Persistent : yes (key saved to ~/.fwmetadata/fieldkit/tor/)
|
||||
============================================================
|
||||
Sources must use Tor Browser to access the .onion URL.
|
||||
Share the drop box upload URL over a secure channel (Signal, in person).
|
||||
============================================================
|
||||
```
|
||||
|
||||
#### Step 4: Share the .onion drop box URL
|
||||
|
||||
Create a drop box token as usual (see Step 2 above), then construct the `.onion` upload URL:
|
||||
|
||||
```
|
||||
http://<onion-address>/dropbox/upload/<token>
|
||||
```
|
||||
|
||||
Share this URL with the source over Signal or in person. The source opens it in
|
||||
**Tor Browser** -- not in a regular browser.
|
||||
|
||||
#### Persistent vs. transient hidden services
|
||||
|
||||
| Mode | Command | Behaviour |
|
||||
|---|---|---|
|
||||
| **Persistent** (default) | `--tor` | Same `.onion` address on every restart. Key stored at `~/.fwmetadata/fieldkit/tor/hidden_service/`. |
|
||||
| **Transient** | `--tor --tor-transient` | New `.onion` address each run. No key written to disk. |
|
||||
|
||||
Use persistent mode when you want sources to bookmark the address or share it in advance.
|
||||
Use transient mode for single-session intake where address continuity does not matter.
|
||||
|
||||
#### Source instructions
|
||||
|
||||
Tell sources:
|
||||
|
||||
1. Install **Tor Browser** from [torproject.org](https://www.torproject.org/download/).
|
||||
2. Open Tor Browser and paste the full `.onion` URL into the address bar.
|
||||
3. Do not open the `.onion` URL in a regular browser -- your real IP will be visible.
|
||||
4. JavaScript must be enabled for the SHA-256 fingerprint feature to work.
|
||||
Set the Security Level to "Standard" in Tor Browser (shield icon in the toolbar).
|
||||
5. Save the SHA-256 fingerprints shown before clicking Upload.
|
||||
6. Save the receipt codes shown after upload.
|
||||
|
||||
#### Logging and access logs
|
||||
|
||||
Even with Tor, access logs on the server can record that *someone* connected -- the
|
||||
connection appears to come from a Tor exit relay (for regular Tor) or from a Tor internal
|
||||
address (for hidden services). For hidden services, the server sees no IP at all; the
|
||||
connection comes from the Tor daemon on localhost.
|
||||
|
||||
**Recommendation:** Set the web server or reverse proxy to not log access requests to
|
||||
`/dropbox/upload/` paths. If using FieldWitness directly (Waitress), access log output
|
||||
goes to stdout; redirect it to `/dev/null` or omit the log handler.
|
||||
|
||||
#### Killswitch and the hidden service key
|
||||
|
||||
The persistent hidden service key is stored under `~/.fwmetadata/fieldkit/tor/hidden_service/`
|
||||
and is treated as key material. The FieldWitness killswitch (`fieldwitness fieldkit purge`)
|
||||
destroys this directory during both `KEYS_ONLY` and `ALL` purge scopes. After a purge,
|
||||
the `.onion` address cannot be linked to the operator even if the server hardware is seized.
|
||||
|
||||
> **Warning:** Even with Tor, timing analysis and traffic correlation attacks are possible
|
||||
> at the network level. The drop box protects source identity at the application layer;
|
||||
> network-layer protection requires operational discipline beyond what software can provide.
|
||||
> Tor is not a silver bullet -- but it removes the most direct risk (IP address exposure)
|
||||
> that limitation L7 in the threat model describes.
|
||||
513
docs/training/admin-operations-guide.md
Normal file
513
docs/training/admin-operations-guide.md
Normal file
@ -0,0 +1,513 @@
|
||||
# FieldWitness Admin Operations Guide
|
||||
|
||||
**Audience**: IT administrators, system operators, and technically competent journalists
|
||||
responsible for deploying, configuring, and maintaining FieldWitness instances for their
|
||||
organization.
|
||||
|
||||
**Prerequisites**: Familiarity with Linux command line, Docker basics, and SSH. For Tier 1
|
||||
USB builds, familiarity with Debian `live-build`.
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide covers the operational tasks an admin performs after initial deployment. For
|
||||
installation and deployment, see [deployment.md](../deployment.md). For architecture
|
||||
details, see [docs/architecture/](../architecture/).
|
||||
|
||||
Your responsibilities as a FieldWitness admin:
|
||||
|
||||
1. Deploy and maintain FieldWitness instances (Tier 1 USB, Tier 2 server, Tier 3 relay)
|
||||
2. Manage user accounts and access
|
||||
3. Configure threat level presets for your environment
|
||||
4. Manage the source drop box
|
||||
5. Set up and maintain federation between organizations
|
||||
6. Monitor system health and perform backups
|
||||
7. Respond to security incidents
|
||||
|
||||
---
|
||||
|
||||
## 1. User Management
|
||||
|
||||
### Creating User Accounts
|
||||
|
||||
On first start, the web UI prompts for the first admin account. Additional users are
|
||||
created through the **Admin** panel at `/admin/`.
|
||||
|
||||
Each user has:
|
||||
- A username and password (stored as Argon2id hashes in SQLite)
|
||||
- An admin flag (admin users can manage other accounts and the drop box)
|
||||
|
||||
### Password Resets
|
||||
|
||||
From the admin panel, issue a temporary password for a locked-out user. The user should
|
||||
change it on next login. All password resets are recorded in the audit log
|
||||
(`~/.fwmetadata/audit.jsonl`).
|
||||
|
||||
### Account Lockout
|
||||
|
||||
After `login_lockout_attempts` (default: 5) failed logins, the account is locked for
|
||||
`login_lockout_minutes` (default: 15). Lockout state is in-memory and clears on server
|
||||
restart.
|
||||
|
||||
For persistent lockout (e.g., a compromised account), delete the user from the admin panel.
|
||||
|
||||
### Audit Trail
|
||||
|
||||
All admin actions are logged to `~/.fwmetadata/audit.jsonl` in JSON-lines format:
|
||||
|
||||
```json
|
||||
{"timestamp": "2026-04-01T12:00:00+00:00", "actor": "admin", "action": "user.create", "target": "user:reporter1", "outcome": "success", "source": "web"}
|
||||
```
|
||||
|
||||
Actions logged: `user.create`, `user.delete`, `user.password_reset`,
|
||||
`key.channel.generate`, `key.identity.generate`, `killswitch.fire`
|
||||
|
||||
> **Warning**: The audit log is destroyed by the killswitch. This is intentional --
|
||||
> in a field compromise, data destruction takes precedence over audit preservation.
|
||||
|
||||
---
|
||||
|
||||
## 2. Threat Level Configuration
|
||||
|
||||
FieldWitness ships four presets at `deploy/config-presets/`. Select based on your operational
|
||||
environment.
|
||||
|
||||
### Applying a Preset
|
||||
|
||||
```bash
|
||||
$ cp deploy/config-presets/high-threat.json ~/.fwmetadata/config.json
|
||||
```
|
||||
|
||||
Restart the server to apply.
|
||||
|
||||
### Preset Summary
|
||||
|
||||
| Preset | Session Timeout | Killswitch | Dead Man's Switch | USB Monitor | Cover Name |
|
||||
|---|---|---|---|---|---|
|
||||
| **Low** (press freedom) | 30 min | Off | Off | Off | None |
|
||||
| **Medium** (restricted press) | 15 min | On | 48h / 4h grace | On | "Office Document Manager" |
|
||||
| **High** (conflict zone) | 5 min | On | 12h / 1h grace | On | "Local Inventory Tracker" |
|
||||
| **Critical** (targeted surveillance) | 3 min | On | 6h / 1h grace | On | "System Statistics" |
|
||||
|
||||
### Custom Configuration
|
||||
|
||||
Edit `~/.fwmetadata/config.json` directly. All fields have defaults. Key fields for security:
|
||||
|
||||
| Field | What It Controls |
|
||||
|---|---|
|
||||
| `host` | Bind address. `127.0.0.1` = local only; `0.0.0.0` = LAN access |
|
||||
| `session_timeout_minutes` | How long before idle sessions expire |
|
||||
| `killswitch_enabled` | Whether the software killswitch is available |
|
||||
| `deadman_enabled` | Whether the dead man's switch is active |
|
||||
| `deadman_interval_hours` | Hours between required check-ins |
|
||||
| `deadman_grace_hours` | Grace period after missed check-in before auto-purge |
|
||||
| `deadman_warning_webhook` | URL to POST a JSON warning during grace period |
|
||||
| `cover_name` | CN for the self-signed TLS certificate (cover/duress mode) |
|
||||
| `backup_reminder_days` | Days before `fieldwitness status` warns about overdue backups |
|
||||
|
||||
> **Warning**: Setting `auth_enabled: false` disables all login requirements. Never
|
||||
> do this on a network-accessible instance.
|
||||
|
||||
---
|
||||
|
||||
## 3. Source Drop Box Operations
|
||||
|
||||
The drop box provides SecureDrop-style anonymous file intake.
|
||||
|
||||
### Creating Upload Tokens
|
||||
|
||||
1. Go to `/dropbox/admin` in the web UI (admin account required)
|
||||
2. Set a **label** (internal only -- the source never sees this)
|
||||
3. Set **expiry** in hours (default: 24)
|
||||
4. Set **max files** (default: 10)
|
||||
5. Click **Create Token**
|
||||
|
||||
You receive a URL like `https://<host>:<port>/dropbox/upload/<token>`.
|
||||
|
||||
### Sharing URLs With Sources
|
||||
|
||||
Share the URL over an already-secure channel only:
|
||||
|
||||
- **Best**: Hand-written on paper, in person
|
||||
- **Good**: Signal, Wire, or other end-to-end encrypted messenger
|
||||
- **Acceptable**: Encrypted email (PGP/GPG)
|
||||
- **Never**: Unencrypted email, SMS, or any channel you do not control
|
||||
|
||||
### What Happens When a Source Uploads
|
||||
|
||||
1. The source opens the URL in any browser (no account needed, no FieldWitness branding)
|
||||
2. Their browser computes SHA-256 hashes client-side before upload (SubtleCrypto)
|
||||
3. Files are uploaded and processed:
|
||||
- EXIF metadata is extracted (evidentiary fields: GPS, timestamp)
|
||||
- All metadata is stripped from the stored copy (protects source device info)
|
||||
- The original bytes are attested (signed) before stripping
|
||||
4. The source receives a receipt code (HMAC of file hash + token)
|
||||
5. Files are stored in `~/.fwmetadata/temp/dropbox/` with mode 0700
|
||||
|
||||
### Revoking Tokens
|
||||
|
||||
From `/dropbox/admin`, click **Revoke** on any active token. The token is immediately
|
||||
deleted from the database. Any source with the URL can no longer upload.
|
||||
|
||||
### Receipt Verification
|
||||
|
||||
Sources can verify their submission was received at `/dropbox/verify-receipt` by entering
|
||||
their receipt code. This returns the filename, SHA-256, and reception timestamp.
|
||||
|
||||
### Operational Security
|
||||
|
||||
- The upload page has no FieldWitness branding -- it is a minimal HTML form
|
||||
- No external resources are loaded (no CDN, fonts, analytics) -- Tor Browser compatible
|
||||
- FieldWitness does not log source IP addresses
|
||||
- If using a reverse proxy (nginx, Caddy), disable access logging for `/dropbox/upload/`
|
||||
- Tokens auto-expire and are cleaned up on every admin page load
|
||||
- For maximum source protection, run FieldWitness as a Tor hidden service
|
||||
|
||||
### Storage Management
|
||||
|
||||
Uploaded files accumulate in `~/.fwmetadata/temp/dropbox/`. Periodically review and process
|
||||
submissions, then remove them from the temp directory. The files are not automatically
|
||||
cleaned up (they persist until you act on them or the killswitch fires).
|
||||
|
||||
---
|
||||
|
||||
## 4. Key Management
|
||||
|
||||
### Two Key Domains
|
||||
|
||||
FieldWitness manages two independent key types:
|
||||
|
||||
| Key | Algorithm | Location | Purpose |
|
||||
|---|---|---|---|
|
||||
| **Identity key** | Ed25519 | `~/.fwmetadata/identity/` | Sign attestations, chain records |
|
||||
| **Channel key** | AES-256-GCM (Argon2id-derived) | `~/.fwmetadata/stego/channel.key` | Steganographic encoding |
|
||||
|
||||
These are never merged. Rotating one does not affect the other.
|
||||
|
||||
### Key Rotation
|
||||
|
||||
**Identity rotation** archives the old keypair and generates a new one. If the chain is
|
||||
enabled, a `fieldwitness/key-rotation-v1` record is signed by the OLD key, creating a
|
||||
verifiable trust chain.
|
||||
|
||||
```bash
|
||||
$ fieldwitness keys rotate-identity
|
||||
```
|
||||
|
||||
After rotating, immediately:
|
||||
1. Take a fresh backup (`fieldwitness keys export`)
|
||||
2. Notify all collaborators of the new fingerprint
|
||||
3. Update trusted-key lists at partner organizations
|
||||
|
||||
**Channel rotation** archives the old key and generates a new one:
|
||||
|
||||
```bash
|
||||
$ fieldwitness keys rotate-channel
|
||||
```
|
||||
|
||||
After rotating, share the new channel key with all stego correspondents.
|
||||
|
||||
### Trust Store
|
||||
|
||||
Import collaborator public keys so you can verify their attestations and accept their
|
||||
federation bundles:
|
||||
|
||||
```bash
|
||||
$ fieldwitness keys trust --import /media/usb/partner-pubkey.pem
|
||||
```
|
||||
|
||||
Always verify fingerprints out-of-band (in person or over a known-secure voice channel).
|
||||
|
||||
List trusted keys:
|
||||
|
||||
```bash
|
||||
$ fieldwitness keys show
|
||||
```
|
||||
|
||||
Remove a trusted key:
|
||||
|
||||
```bash
|
||||
$ fieldwitness keys untrust <fingerprint>
|
||||
```
|
||||
|
||||
### Backup Schedule
|
||||
|
||||
FieldWitness warns when backups are overdue (configurable via `backup_reminder_days`).
|
||||
|
||||
```bash
|
||||
# Create encrypted backup
|
||||
$ fieldwitness keys export -o /media/usb/backup.enc
|
||||
|
||||
# Check backup status
|
||||
$ fieldwitness status
|
||||
```
|
||||
|
||||
Store backups on separate physical media, in a different location from the device.
|
||||
|
||||
---
|
||||
|
||||
## 5. Federation Setup
|
||||
|
||||
Federation allows multiple FieldWitness instances to exchange attestation records.
|
||||
|
||||
### Adding Federation Peers
|
||||
|
||||
**Through the web UI:** Go to `/federation/`, click **Add Peer**, enter the peer's URL
|
||||
and Ed25519 fingerprint.
|
||||
|
||||
**Through the CLI or peer_store:**
|
||||
|
||||
```bash
|
||||
# Peers are managed via the web UI or programmatically through PeerStore
|
||||
```
|
||||
|
||||
### Trust Key Exchange
|
||||
|
||||
Before two organizations can federate, exchange public keys:
|
||||
|
||||
1. Export your public key: `cp ~/.fwmetadata/identity/public.pem /media/usb/our-pubkey.pem`
|
||||
2. Give it to the partner organization (physical handoff or secure channel)
|
||||
3. Import their key: `fieldwitness keys trust --import /media/usb/their-pubkey.pem`
|
||||
4. Verify fingerprints out-of-band
|
||||
|
||||
### Exporting Attestation Bundles
|
||||
|
||||
```bash
|
||||
# Export all records
|
||||
$ fieldwitness chain export --output /media/usb/bundle.zip
|
||||
|
||||
# Export a specific range
|
||||
$ fieldwitness chain export --start 100 --end 200 --output /media/usb/bundle.zip
|
||||
|
||||
# Export filtered by investigation
|
||||
# (investigation tag is set during attestation)
|
||||
```
|
||||
|
||||
### Importing Attestation Bundles
|
||||
|
||||
On the receiving instance, imported records are:
|
||||
- Verified against the trust store (untrusted signers are rejected)
|
||||
- Deduplicated by SHA-256 (existing records are skipped)
|
||||
- Tagged with `federated_from` metadata
|
||||
- Acknowledged via a delivery-ack chain record (two-way handshake)
|
||||
|
||||
### Gossip Sync (Tier 2 <-> Tier 3)
|
||||
|
||||
If the Tier 2 server and Tier 3 relay have network connectivity, gossip sync runs
|
||||
automatically at the configured interval (default: 60 seconds, set via
|
||||
`FIELDWITNESS_GOSSIP_INTERVAL` environment variable).
|
||||
|
||||
Gossip flow:
|
||||
1. Nodes exchange Merkle roots
|
||||
2. If roots differ, request consistency proof
|
||||
3. Fetch missing records
|
||||
4. Append to local log
|
||||
|
||||
Monitor sync status at `/federation/` in the web UI.
|
||||
|
||||
### Airgapped Federation
|
||||
|
||||
All federation is designed for sneakernet operation:
|
||||
|
||||
1. Export bundle to USB on sending instance
|
||||
2. Physically carry USB to receiving instance
|
||||
3. Import bundle
|
||||
4. Optionally export delivery acknowledgment back on USB
|
||||
|
||||
No network connectivity is required at any point.
|
||||
|
||||
---
|
||||
|
||||
## 6. Chain and Anchoring
|
||||
|
||||
### Chain Verification
|
||||
|
||||
Verify the full chain periodically:
|
||||
|
||||
```bash
|
||||
$ fieldwitness chain verify
|
||||
```
|
||||
|
||||
This checks all hash linkage and Ed25519 signatures. It also verifies key rotation
|
||||
records and tracks authorized signers.
|
||||
|
||||
### Timestamp Anchoring
|
||||
|
||||
Anchor the chain head to prove it existed before a given time:
|
||||
|
||||
```bash
|
||||
# Automated (requires network)
|
||||
$ fieldwitness chain anchor --tsa https://freetsa.org/tsr
|
||||
|
||||
# Manual (prints hash for external submission)
|
||||
$ fieldwitness chain anchor
|
||||
```
|
||||
|
||||
A single anchor implicitly timestamps every prior record (the chain is append-only).
|
||||
|
||||
**When to anchor:**
|
||||
- Before sharing evidence with third parties
|
||||
- At regular intervals (daily or weekly)
|
||||
- Before key rotation
|
||||
- Before and after major investigations
|
||||
|
||||
### Selective Disclosure
|
||||
|
||||
For legal discovery or court orders, produce a proof showing specific records while
|
||||
keeping others redacted:
|
||||
|
||||
```bash
|
||||
$ fieldwitness chain disclose -i 42,43,44 -o disclosure.json
|
||||
```
|
||||
|
||||
The output includes full records for selected indices and hash-only entries for everything
|
||||
else. A third party can verify the selected records are part of an unbroken chain.
|
||||
|
||||
---
|
||||
|
||||
## 7. Evidence Preservation
|
||||
|
||||
### Evidence Packages
|
||||
|
||||
For handing evidence to lawyers, courts, or organizations without FieldWitness:
|
||||
|
||||
Self-contained ZIP containing original images, attestation records, chain data, your
|
||||
public key, a standalone `verify.py`, and a README. The recipient verifies with:
|
||||
|
||||
```bash
|
||||
$ pip install cryptography
|
||||
$ python verify.py
|
||||
```
|
||||
|
||||
### Cold Archives
|
||||
|
||||
For long-term preservation (10+ year horizon), OAIS-aligned:
|
||||
|
||||
Full state export including chain binary, attestation log, LMDB index, anchors, public
|
||||
key, trusted keys, optional encrypted key bundle, `ALGORITHMS.txt`, and `verify.py`.
|
||||
|
||||
**When to create cold archives:**
|
||||
- Weekly or monthly as part of backup strategy
|
||||
- Before key rotation or travel
|
||||
- When archiving a completed investigation
|
||||
|
||||
Store on at least two separate physical media in different locations.
|
||||
|
||||
---
|
||||
|
||||
## 8. Monitoring and Health
|
||||
|
||||
### Health Endpoint
|
||||
|
||||
```bash
|
||||
# Web UI
|
||||
$ curl -k https://127.0.0.1:5000/health
|
||||
|
||||
# Federation API
|
||||
$ curl http://localhost:8000/health
|
||||
```
|
||||
|
||||
Returns capabilities (stego-lsb, stego-dct, attest, fieldkit, chain).
|
||||
|
||||
### System Status
|
||||
|
||||
```bash
|
||||
$ fieldwitness status --json
|
||||
```
|
||||
|
||||
Checks: identity key, channel key, chain integrity, dead man's switch state, backup
|
||||
status, geofence, trusted keys.
|
||||
|
||||
### Docker Monitoring
|
||||
|
||||
```bash
|
||||
# Service status
|
||||
$ docker compose ps
|
||||
|
||||
# Logs
|
||||
$ docker compose logs -f server
|
||||
|
||||
# Resource usage
|
||||
$ docker stats
|
||||
```
|
||||
|
||||
The Docker images include `HEALTHCHECK` directives that poll `/health` every 30 seconds.
|
||||
|
||||
---
|
||||
|
||||
## 9. Incident Response
|
||||
|
||||
### Device Seizure (Imminent)
|
||||
|
||||
1. Trigger killswitch: `fieldwitness fieldkit purge --confirm CONFIRM-PURGE`
|
||||
2. For Tier 1 USB: pull the USB stick and destroy it physically if possible
|
||||
3. Verify with a separate device that federation copies are intact
|
||||
|
||||
### Device Seizure (After the Fact)
|
||||
|
||||
1. Assume all local data is compromised
|
||||
2. Verify Tier 2/3 copies of attestation data
|
||||
3. Generate new keys on a fresh instance
|
||||
4. Record a key recovery event in the chain (if the old chain is still accessible)
|
||||
5. Notify all collaborators to update their trust stores
|
||||
|
||||
### Federation Peer Compromise
|
||||
|
||||
1. The compromised peer has attestation metadata (hashes, signatures, timestamps) but not
|
||||
decrypted content
|
||||
2. Remove the peer from your peer list (`/federation/` > Remove Peer)
|
||||
3. Assess what metadata exposure means for your organization
|
||||
4. Consider whether attestation patterns reveal sensitive information
|
||||
|
||||
### Dead Man's Switch Triggered Accidentally
|
||||
|
||||
Data is gone. Restore from the most recent backup:
|
||||
|
||||
```bash
|
||||
$ fieldwitness init
|
||||
$ fieldwitness keys import -b /media/usb/backup.enc
|
||||
```
|
||||
|
||||
Federation copies of attestation data are unaffected. Local attestations created since
|
||||
the last federation sync or backup are lost.
|
||||
|
||||
---
|
||||
|
||||
## 10. Maintenance Tasks
|
||||
|
||||
### Regular Schedule
|
||||
|
||||
| Task | Frequency | Command |
|
||||
|---|---|---|
|
||||
| Check system status | Daily | `fieldwitness status` |
|
||||
| Check in (if deadman armed) | Per interval | `fieldwitness fieldkit checkin` |
|
||||
| Backup keys | Per `backup_reminder_days` | `fieldwitness keys export` |
|
||||
| Verify chain integrity | Weekly | `fieldwitness chain verify` |
|
||||
| Anchor chain | Weekly | `fieldwitness chain anchor` |
|
||||
| Review drop box submissions | As needed | `/dropbox/admin` |
|
||||
| Clean temp files | Monthly | Remove processed files from `~/.fwmetadata/temp/` |
|
||||
| Create cold archive | Monthly | Export via CLI or web |
|
||||
| Update FieldWitness | As releases are available | `pip install --upgrade fieldwitness` |
|
||||
|
||||
### Docker Volume Backup
|
||||
|
||||
```bash
|
||||
$ docker compose stop server
|
||||
$ docker run --rm -v server-data:/data -v /backup:/backup \
|
||||
busybox tar czf /backup/fieldwitness-$(date +%Y%m%d).tar.gz -C /data .
|
||||
$ docker compose start server
|
||||
```
|
||||
|
||||
### Log Rotation
|
||||
|
||||
`audit.jsonl` grows indefinitely. On long-running Tier 2 servers, archive old entries
|
||||
periodically. The audit log is append-only; truncate by copying the tail:
|
||||
|
||||
```bash
|
||||
$ tail -n 10000 ~/.fwmetadata/audit.jsonl > ~/.fwmetadata/audit.jsonl.tmp
|
||||
$ mv ~/.fwmetadata/audit.jsonl.tmp ~/.fwmetadata/audit.jsonl
|
||||
```
|
||||
|
||||
> **Warning**: Truncating the audit log removes historical records. Archive the full
|
||||
> file before truncating if you need the history for compliance or legal purposes.
|
||||
219
docs/training/admin-reference.md
Normal file
219
docs/training/admin-reference.md
Normal file
@ -0,0 +1,219 @@
|
||||
# Administrator Quick Reference
|
||||
|
||||
**Audience**: IT staff and technical leads responsible for deploying and maintaining
|
||||
FieldWitness instances.
|
||||
|
||||
---
|
||||
|
||||
## Deployment Tiers
|
||||
|
||||
| Tier | Form Factor | Use Case | Key Feature |
|
||||
|---|---|---|---|
|
||||
| 1 -- Field Device | Bootable Debian Live USB | Reporter in the field | Amnesic, LUKS encrypted, pull USB = zero trace |
|
||||
| 2 -- Org Server | Docker on mini PC or VPS | Newsroom / NGO office | Persistent, web UI + federation API |
|
||||
| 3 -- Federation Relay | Docker on VPS | Friendly jurisdiction | Attestation sync only, zero knowledge of keys |
|
||||
|
||||
---
|
||||
|
||||
## Quick Deploy
|
||||
|
||||
### Tier 1: Build USB image
|
||||
|
||||
```bash
|
||||
$ sudo apt install live-build
|
||||
$ cd deploy/live-usb
|
||||
$ sudo ./build.sh
|
||||
$ sudo dd if=live-image-amd64.hybrid.iso of=/dev/sdX bs=4M status=progress
|
||||
```
|
||||
|
||||
### Tier 2: Docker org server
|
||||
|
||||
```bash
|
||||
$ cd deploy/docker
|
||||
$ docker compose up server -d
|
||||
```
|
||||
|
||||
Exposes port 5000 (web UI) and port 8000 (federation API).
|
||||
|
||||
### Tier 3: Docker federation relay
|
||||
|
||||
```bash
|
||||
$ cd deploy/docker
|
||||
$ docker compose up relay -d
|
||||
```
|
||||
|
||||
Exposes port 8001 (federation API only).
|
||||
|
||||
### Kubernetes
|
||||
|
||||
```bash
|
||||
$ docker build -t fieldwitness-server --target server -f deploy/docker/Dockerfile .
|
||||
$ docker build -t fieldwitness-relay --target relay -f deploy/docker/Dockerfile .
|
||||
$ kubectl apply -f deploy/kubernetes/namespace.yaml
|
||||
$ kubectl apply -f deploy/kubernetes/server-deployment.yaml
|
||||
$ kubectl apply -f deploy/kubernetes/relay-deployment.yaml
|
||||
```
|
||||
|
||||
Single-replica only. FieldWitness uses SQLite -- do not scale horizontally.
|
||||
|
||||
---
|
||||
|
||||
## Threat Level Presets
|
||||
|
||||
Copy the appropriate preset to configure FieldWitness for the operational environment:
|
||||
|
||||
```bash
|
||||
$ cp deploy/config-presets/<level>-threat.json ~/.fwmetadata/config.json
|
||||
```
|
||||
|
||||
| Level | Session | Killswitch | Dead Man | Cover Name |
|
||||
|---|---|---|---|---|
|
||||
| `low-threat` | 30 min | Off | Off | None |
|
||||
| `medium-threat` | 15 min | On | 48h / 4h grace | "Office Document Manager" |
|
||||
| `high-threat` | 5 min | On | 12h / 1h grace | "Local Inventory Tracker" |
|
||||
| `critical-threat` | 3 min | On | 6h / 1h grace | "System Statistics" |
|
||||
|
||||
---
|
||||
|
||||
## Essential CLI Commands
|
||||
|
||||
### System
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `fieldwitness init` | Create directory structure, generate keys, write default config |
|
||||
| `fieldwitness serve --host 0.0.0.0` | Start web UI (LAN-accessible) |
|
||||
| `fieldwitness status` | Pre-flight check: keys, chain, deadman, backup, geofence |
|
||||
| `fieldwitness status --json` | Machine-readable status output |
|
||||
|
||||
### Keys
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `fieldwitness keys show` | Display current key info and fingerprints |
|
||||
| `fieldwitness keys export -o backup.enc` | Export encrypted key bundle |
|
||||
| `fieldwitness keys import -b backup.enc` | Import key bundle from backup |
|
||||
| `fieldwitness keys rotate-identity` | Rotate Ed25519 identity (records in chain) |
|
||||
| `fieldwitness keys rotate-channel` | Rotate AES-256-GCM channel key |
|
||||
| `fieldwitness keys trust --import pubkey.pem` | Trust a collaborator's public key |
|
||||
|
||||
### Fieldkit
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `fieldwitness fieldkit status` | Show fieldkit state (deadman, geofence, USB, tamper) |
|
||||
| `fieldwitness fieldkit checkin` | Reset dead man's switch timer |
|
||||
| `fieldwitness fieldkit check-deadman` | Check if deadman timer expired (for cron) |
|
||||
| `fieldwitness fieldkit purge --confirm CONFIRM-PURGE` | Activate killswitch |
|
||||
| `fieldwitness fieldkit geofence set --lat X --lon Y --radius M` | Set GPS boundary |
|
||||
| `fieldwitness fieldkit usb snapshot` | Record USB whitelist baseline |
|
||||
| `fieldwitness fieldkit tamper baseline` | Record file integrity baseline |
|
||||
|
||||
### Chain and Evidence
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `fieldwitness chain status` | Show chain head, length, integrity |
|
||||
| `fieldwitness chain verify` | Verify full chain (hashes + signatures) |
|
||||
| `fieldwitness chain log --count 20` | Show recent chain entries |
|
||||
| `fieldwitness chain export -o bundle.zip` | Export attestation bundle |
|
||||
| `fieldwitness chain disclose -i 5,12,47 -o disclosure.json` | Selective disclosure |
|
||||
| `fieldwitness chain anchor` | Manual anchor (prints hash for external witness) |
|
||||
| `fieldwitness chain anchor --tsa https://freetsa.org/tsr` | RFC 3161 automated anchor |
|
||||
|
||||
---
|
||||
|
||||
## User Management
|
||||
|
||||
The web UI admin panel at `/admin` provides:
|
||||
|
||||
- Create user accounts
|
||||
- Delete user accounts
|
||||
- Reset passwords (temporary password issued)
|
||||
- View active sessions
|
||||
|
||||
User credentials are stored in SQLite at `~/.fwmetadata/auth/fieldwitness.db`.
|
||||
|
||||
---
|
||||
|
||||
## Backup Checklist
|
||||
|
||||
| What | How often | Command |
|
||||
|---|---|---|
|
||||
| Key bundle | After every rotation, weekly minimum | `fieldwitness keys export -o backup.enc` |
|
||||
| Cold archive | Weekly or before travel | `fieldwitness archive export --include-keys -o archive.zip` |
|
||||
| Docker volume | Before updates | `docker compose stop server && docker run --rm -v server-data:/data -v /backup:/backup busybox tar czf /backup/fieldwitness-$(date +%Y%m%d).tar.gz -C /data .` |
|
||||
|
||||
Store backups on separate physical media. Keep one copy offsite.
|
||||
|
||||
---
|
||||
|
||||
## Federation Setup
|
||||
|
||||
1. Exchange public keys between organizations (verify fingerprints out-of-band)
|
||||
2. Import collaborator keys: `fieldwitness keys trust --import /path/to/pubkey.pem`
|
||||
3. Register peers via web UI at `/federation` or via CLI
|
||||
4. Gossip starts automatically; monitor at `/federation`
|
||||
|
||||
For airgapped federation: `fieldwitness chain export` to USB, carry to partner, import there.
|
||||
|
||||
---
|
||||
|
||||
## Source Drop Box
|
||||
|
||||
1. Navigate to `/dropbox/admin` (admin login required)
|
||||
2. Create a token with label, expiry, and file limit
|
||||
3. Share the generated URL with the source over a secure channel
|
||||
4. Monitor submissions at `/dropbox/admin`
|
||||
5. Revoke tokens when no longer needed
|
||||
|
||||
---
|
||||
|
||||
## Hardening Checklist
|
||||
|
||||
- [ ] Disable or encrypt swap (`swapoff -a` or dm-crypt random-key swap)
|
||||
- [ ] Disable core dumps (`echo "* hard core 0" >> /etc/security/limits.conf`)
|
||||
- [ ] Configure firewall (UFW: allow 5000, 8000; deny all other incoming)
|
||||
- [ ] Disable unnecessary services (bluetooth, avahi-daemon)
|
||||
- [ ] Apply a threat level preset appropriate for the environment
|
||||
- [ ] Set `cover_name` in config if operating under cover
|
||||
- [ ] Set `FIELDWITNESS_DATA_DIR` to an inconspicuous path if needed
|
||||
- [ ] Enable HTTPS (default) or place behind a reverse proxy with TLS
|
||||
- [ ] Create systemd service for bare metal (see `docs/deployment.md` Section 7)
|
||||
- [ ] Set up regular backups (key bundle + cold archive)
|
||||
- [ ] Arm dead man's switch if appropriate for threat level
|
||||
- [ ] Take initial USB whitelist snapshot
|
||||
- [ ] Record tamper baseline
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting Quick Fixes
|
||||
|
||||
| Symptom | Check |
|
||||
|---|---|
|
||||
| Web UI unreachable from LAN | `host` must be `0.0.0.0`, not `127.0.0.1`. Check firewall. |
|
||||
| Docker container exits | `docker compose logs server` -- check for port conflict or volume permissions |
|
||||
| Dead man fires unexpectedly | Service crashed and exceeded interval+grace. Ensure `Restart=on-failure`. |
|
||||
| Permission errors on `~/.fwmetadata/` | Run FieldWitness as the same user who ran `fieldwitness init` |
|
||||
| Drop box tokens expire immediately | System clock wrong. Run `date -u` and fix if needed. |
|
||||
| Chain anchor TSA fails | Requires network. Use manual anchor on airgapped devices. |
|
||||
| Account locked out | Wait for lockout to expire, or restart the server. |
|
||||
| SSL cert shows wrong name | Delete `~/.fwmetadata/certs/cert.pem`, set `cover_name`, restart. |
|
||||
|
||||
---
|
||||
|
||||
## Health Checks
|
||||
|
||||
```bash
|
||||
# Web UI
|
||||
$ curl -k https://127.0.0.1:5000/health
|
||||
|
||||
# Federation API (Tier 2)
|
||||
$ curl http://localhost:8000/health
|
||||
|
||||
# Relay (Tier 3)
|
||||
$ curl http://localhost:8001/health
|
||||
|
||||
# Full system status
|
||||
$ fieldwitness status --json
|
||||
```
|
||||
79
docs/training/emergency-card.md
Normal file
79
docs/training/emergency-card.md
Normal file
@ -0,0 +1,79 @@
|
||||
# Emergency Reference Card
|
||||
|
||||
**Audience**: All FieldWitness users. Print, laminate, and carry in your wallet.
|
||||
|
||||
---
|
||||
|
||||
## EMERGENCY DATA DESTRUCTION
|
||||
|
||||
### Option 1: Pull the USB (Tier 1 -- fastest)
|
||||
|
||||
Remove the USB stick from the laptop. The laptop retains zero data.
|
||||
|
||||
### Option 2: Software killswitch
|
||||
|
||||
In the browser: **Fieldkit** > **Emergency Purge** > type `CONFIRM-PURGE` > click **Purge**
|
||||
|
||||
From a terminal:
|
||||
|
||||
```
|
||||
fieldwitness fieldkit purge --confirm CONFIRM-PURGE
|
||||
```
|
||||
|
||||
### Option 3: Hardware button (Raspberry Pi only)
|
||||
|
||||
Hold the physical button for 5 seconds.
|
||||
|
||||
---
|
||||
|
||||
## DESTRUCTION ORDER
|
||||
|
||||
The killswitch destroys data in this order (most critical first):
|
||||
|
||||
1. Ed25519 identity keys
|
||||
2. AES-256 channel key
|
||||
3. Session secrets
|
||||
4. User database
|
||||
5. Attestation log and chain
|
||||
6. Temp files and audit log
|
||||
7. Configuration
|
||||
8. System logs
|
||||
9. All forensic traces (bytecache, pip cache, shell history)
|
||||
10. Self-uninstall
|
||||
|
||||
On USB: the LUKS encryption header is destroyed instead (faster, more reliable on flash).
|
||||
|
||||
---
|
||||
|
||||
## DEAD MAN'S SWITCH
|
||||
|
||||
If enabled, you must check in before the deadline or all data will be destroyed.
|
||||
|
||||
**Check in**: Browser > **Fieldkit** > **Check In**
|
||||
|
||||
Or: `fieldwitness fieldkit checkin`
|
||||
|
||||
If you cannot check in, contact your editor. They may be able to disarm it remotely.
|
||||
|
||||
---
|
||||
|
||||
## KEY CONTACTS
|
||||
|
||||
| Role | Name | Contact |
|
||||
|---|---|---|
|
||||
| Admin | _________________ | _________________ |
|
||||
| Editor | _________________ | _________________ |
|
||||
| Legal | _________________ | _________________ |
|
||||
| Technical support | _________________ | _________________ |
|
||||
|
||||
Fill in before deploying. Keep this card current.
|
||||
|
||||
---
|
||||
|
||||
## REMEMBER
|
||||
|
||||
- Pull the USB = zero trace on the laptop
|
||||
- Keys are destroyed first = remaining data is useless without them
|
||||
- The killswitch cannot be undone
|
||||
- Back up your keys regularly -- if the USB is lost, the keys are gone
|
||||
- Never share your passphrase, PIN, or LUKS password over unencrypted channels
|
||||
263
docs/training/reporter-field-guide.md
Normal file
263
docs/training/reporter-field-guide.md
Normal file
@ -0,0 +1,263 @@
|
||||
# FieldWitness Reporter Field Guide
|
||||
|
||||
**Audience**: Reporters, field researchers, and documentarians using FieldWitness to protect
|
||||
and verify their work. No technical background required.
|
||||
|
||||
**Prerequisites**: A working FieldWitness instance (Tier 1 USB or web UI access to a Tier 2
|
||||
server). Your IT admin should have set this up for you.
|
||||
|
||||
---
|
||||
|
||||
## What FieldWitness Does For You
|
||||
|
||||
FieldWitness helps you do three things:
|
||||
|
||||
1. **Prove your photos and files are authentic** -- every photo you attest gets a
|
||||
cryptographic signature that proves you took it, when, and that it has not been
|
||||
tampered with since.
|
||||
2. **Hide messages in images** -- send encrypted messages that look like ordinary photos.
|
||||
3. **Destroy everything if compromised** -- if your device is about to be seized, FieldWitness
|
||||
can erase all evidence of itself and your data in seconds.
|
||||
|
||||
---
|
||||
|
||||
## Daily Workflow
|
||||
|
||||
### Attesting Photos
|
||||
|
||||
After taking photos in the field, attest them as soon as possible. Attestation creates a
|
||||
permanent, tamper-evident record.
|
||||
|
||||
**Through the web UI:**
|
||||
|
||||
1. Open Firefox (on Tier 1 USB, it opens automatically)
|
||||
2. Go to the **Attest** page
|
||||
3. Upload one or more photos
|
||||
4. Add a caption describing what the photo shows (optional but recommended)
|
||||
5. Add a location if relevant (optional)
|
||||
6. Click **Attest**
|
||||
|
||||
FieldWitness will:
|
||||
- Extract GPS coordinates and timestamp from the photo's EXIF data (for the provenance record)
|
||||
- Strip device-identifying information (serial numbers, firmware version) from the stored copy
|
||||
- Sign the photo with your Ed25519 identity key
|
||||
- Add the attestation to the hash chain
|
||||
|
||||
**Through the CLI (if available):**
|
||||
|
||||
```bash
|
||||
$ fieldwitness attest IMAGE photo.jpg --caption "Market protest, central square"
|
||||
```
|
||||
|
||||
> **Warning**: Attest the original, unedited photo. If you crop, filter, or resize
|
||||
> first, the attestation will not match the original file. Attest first, edit later.
|
||||
|
||||
### Batch Attestation
|
||||
|
||||
If you have a folder of photos from a field visit:
|
||||
|
||||
```bash
|
||||
$ fieldwitness attest batch ./field-photos/ --caption "Site visit 2026-04-01"
|
||||
```
|
||||
|
||||
### Checking Your Status
|
||||
|
||||
Run `fieldwitness status` or visit the web UI home page to see:
|
||||
- Whether your identity key is set up
|
||||
- How many attestations you have
|
||||
- Whether your dead man's switch needs a check-in
|
||||
- Whether your backup is overdue
|
||||
|
||||
---
|
||||
|
||||
## Sending Hidden Messages (Steganography)
|
||||
|
||||
Steganography hides an encrypted message inside an ordinary-looking image. To anyone who
|
||||
does not have the decryption credentials, the image looks completely normal.
|
||||
|
||||
### What You Need
|
||||
|
||||
Both you and the recipient must have:
|
||||
1. **A reference photo** -- the same image file, shared beforehand
|
||||
2. **A passphrase** -- at least 4 words, agreed in person
|
||||
3. **A PIN** -- 6 to 9 digits, agreed in person
|
||||
|
||||
All three are required to encode or decode. Share them in person, never over email or SMS.
|
||||
|
||||
### Encoding a Message
|
||||
|
||||
**Web UI:** Go to **Encode**, upload your carrier image and reference photo, enter your
|
||||
message, passphrase, and PIN.
|
||||
|
||||
**CLI:**
|
||||
|
||||
```bash
|
||||
$ fieldwitness stego encode vacation.jpg -r shared_photo.jpg -m "Meeting moved to Thursday"
|
||||
# Passphrase: (enter your passphrase, hidden)
|
||||
# PIN: (enter your PIN, hidden)
|
||||
```
|
||||
|
||||
The output is a normal-looking image file that contains your hidden message.
|
||||
|
||||
### Transport-Aware Encoding
|
||||
|
||||
If you are sending the image through a messaging app, tell FieldWitness which platform. The
|
||||
app will recompress images, so FieldWitness needs to use a survival-resistant encoding:
|
||||
|
||||
```bash
|
||||
$ fieldwitness stego encode photo.jpg -r shared.jpg -m "Safe house confirmed" --transport whatsapp
|
||||
$ fieldwitness stego encode photo.jpg -r shared.jpg -m "Safe house confirmed" --transport signal
|
||||
$ fieldwitness stego encode photo.jpg -r shared.jpg -m "Safe house confirmed" --transport telegram
|
||||
```
|
||||
|
||||
> **Warning**: Never reuse the same carrier image twice. FieldWitness will warn you if you
|
||||
> do. Comparing two versions of the same image trivially reveals steganographic changes.
|
||||
|
||||
### Decoding a Message
|
||||
|
||||
```bash
|
||||
$ fieldwitness stego decode received_image.jpg -r shared_photo.jpg
|
||||
# Passphrase: (same passphrase)
|
||||
# PIN: (same PIN)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Check-In (Dead Man's Switch)
|
||||
|
||||
If your admin has enabled the dead man's switch, you must check in regularly. If you miss
|
||||
your check-in window, FieldWitness assumes something has gone wrong and will eventually destroy
|
||||
all data to protect you.
|
||||
|
||||
**Check in through the web UI:** Visit the **Fieldkit** page and click **Check In**.
|
||||
|
||||
**Check in through the CLI:**
|
||||
|
||||
```bash
|
||||
$ fieldwitness fieldkit checkin
|
||||
```
|
||||
|
||||
> **Warning**: If you will be unable to check in (traveling without the device, planned
|
||||
> downtime), ask your admin to disarm the dead man's switch first. Forgetting to check in
|
||||
> will trigger the killswitch and destroy all your data permanently.
|
||||
|
||||
---
|
||||
|
||||
## Emergency: Triggering the Killswitch
|
||||
|
||||
If your device is about to be seized or compromised:
|
||||
|
||||
**CLI:**
|
||||
|
||||
```bash
|
||||
$ fieldwitness fieldkit purge --confirm CONFIRM-PURGE
|
||||
```
|
||||
|
||||
**Web UI:** Visit the **Fieldkit** page and use the emergency purge button.
|
||||
|
||||
**Tier 1 USB:** Pull the USB stick from the laptop. The laptop retains nothing (it
|
||||
was running from the USB). The USB stick is LUKS-encrypted and requires a passphrase to
|
||||
access.
|
||||
|
||||
**Raspberry Pi with hardware button:** Hold the killswitch button for 5 seconds (default).
|
||||
|
||||
### What gets destroyed
|
||||
|
||||
1. Your signing keys (without these, encrypted data is unrecoverable)
|
||||
2. Your channel key
|
||||
3. User accounts and session data
|
||||
4. All attestation records and chain data
|
||||
5. Temporary files and audit logs
|
||||
6. Configuration
|
||||
7. System log entries mentioning FieldWitness
|
||||
8. Python bytecache and pip metadata (to hide that FieldWitness was installed)
|
||||
9. The FieldWitness package itself
|
||||
|
||||
> **Warning**: This is irreversible. Make sure you have recent backups stored
|
||||
> separately before relying on the killswitch. See "Backups" below.
|
||||
|
||||
---
|
||||
|
||||
## Backups
|
||||
|
||||
Back up your keys regularly. FieldWitness will remind you if your backup is overdue.
|
||||
|
||||
### Creating a Backup
|
||||
|
||||
```bash
|
||||
$ fieldwitness keys export -o /media/usb/fieldwitness-backup.enc
|
||||
```
|
||||
|
||||
You will be prompted for a passphrase. This creates an encrypted bundle containing your
|
||||
identity key and channel key. Store the USB drive **in a different physical location**
|
||||
from your FieldWitness device.
|
||||
|
||||
### Restoring From Backup
|
||||
|
||||
On a fresh FieldWitness instance:
|
||||
|
||||
```bash
|
||||
$ fieldwitness init
|
||||
$ fieldwitness keys import -b /media/usb/fieldwitness-backup.enc
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Evidence Packages
|
||||
|
||||
When you need to hand evidence to a lawyer, a court, or a partner organization that does
|
||||
not use FieldWitness:
|
||||
|
||||
1. Go to the web UI or use the CLI to create an evidence package
|
||||
2. Select the photos to include
|
||||
3. FieldWitness creates a ZIP file containing:
|
||||
- Your original photos
|
||||
- Attestation records with signatures
|
||||
- The chain segment proving order and integrity
|
||||
- Your public key
|
||||
- A standalone verification script
|
||||
- A README with instructions
|
||||
|
||||
The recipient can verify the evidence using only Python -- they do not need FieldWitness.
|
||||
|
||||
---
|
||||
|
||||
## What To Do If...
|
||||
|
||||
**Your device is seized**: If you did not trigger the killswitch in time, assume all
|
||||
local data is compromised. Any attestation bundles you previously sent to your
|
||||
organization (Tier 2) or federated to relays (Tier 3) are safe and contain your full
|
||||
chain. Contact your organization's IT team.
|
||||
|
||||
**You lose your USB stick**: The USB is LUKS-encrypted, so the finder cannot read it
|
||||
without your passphrase. Restore from your backup on a new USB stick. All attestations
|
||||
that were already synced to Tier 2/3 are safe.
|
||||
|
||||
**You forget your stego passphrase or PIN**: There is no recovery. The message is
|
||||
encrypted with keys derived from the passphrase, PIN, and reference photo. If you lose
|
||||
any of the three, the message cannot be recovered.
|
||||
|
||||
**You need to share evidence with a court**: Use selective disclosure
|
||||
(`fieldwitness chain disclose`) to produce a proof that includes only the specific records
|
||||
requested. The court can verify these records are part of an authentic, unbroken chain
|
||||
without seeing your other work.
|
||||
|
||||
**Your check-in is overdue**: Check in immediately. During the grace period, a warning
|
||||
webhook fires (if configured) but data is not yet destroyed. After the grace period,
|
||||
the killswitch fires automatically.
|
||||
|
||||
---
|
||||
|
||||
## Security Reminders
|
||||
|
||||
- **Attest photos immediately** after taking them. The sooner you attest, the smaller
|
||||
the window during which someone could have tampered with the file.
|
||||
- **Never send stego credentials over digital channels.** Share the reference photo,
|
||||
passphrase, and PIN in person.
|
||||
- **Never reuse carrier images** for steganography.
|
||||
- **Check in on schedule** if the dead man's switch is armed.
|
||||
- **Back up regularly** and store backups in a separate physical location.
|
||||
- **Lock the browser** or close it when you walk away. Session timeouts help, but do not
|
||||
rely on them.
|
||||
- **Do not discuss FieldWitness by name** in environments where your communications may be
|
||||
monitored. If `cover_name` is configured, the tool presents itself under that name.
|
||||
105
docs/training/reporter-quickstart.md
Normal file
105
docs/training/reporter-quickstart.md
Normal file
@ -0,0 +1,105 @@
|
||||
# Reporter Quick-Start Card
|
||||
|
||||
**Audience**: Field reporters using a FieldWitness Tier 1 bootable USB device.
|
||||
No technical background assumed.
|
||||
|
||||
**Print this page on a single sheet, laminate it, and keep it with the USB stick.**
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. **Plug the USB** into any laptop
|
||||
2. **Boot from USB** (press F12 during startup, select the USB drive)
|
||||
3. **Enter your passphrase** when the blue screen appears (this unlocks your data)
|
||||
4. **Wait for the browser** to open automatically
|
||||
|
||||
You are now running FieldWitness. The laptop's own hard drive is never touched.
|
||||
|
||||
---
|
||||
|
||||
## Taking and Attesting a Photo
|
||||
|
||||
1. Transfer your photo to the laptop (USB cable, SD card, AirDrop, etc.)
|
||||
2. In the browser, click **Attest**
|
||||
3. Select your photo and click **Sign**
|
||||
4. The photo is now cryptographically signed with your identity
|
||||
|
||||
This proves you took this photo, where, and when. It cannot be forged later.
|
||||
|
||||
---
|
||||
|
||||
## Hiding a Message in a Photo
|
||||
|
||||
1. Click **Encode** in the browser
|
||||
2. Select a **carrier image** (the photo that will carry the hidden message)
|
||||
3. Select a **reference photo** (a photo both you and the recipient have)
|
||||
4. Type your **message**
|
||||
5. Enter your **passphrase** and **PIN** (the recipient needs the same ones)
|
||||
6. Click **Encode**
|
||||
|
||||
To send via WhatsApp, Signal, or Telegram, select the platform from the **Transport**
|
||||
dropdown before encoding. This ensures the message survives the platform's image
|
||||
compression.
|
||||
|
||||
---
|
||||
|
||||
## Checking In (Dead Man's Switch)
|
||||
|
||||
If your admin has enabled the dead man's switch, you must check in regularly.
|
||||
|
||||
1. Click **Fieldkit** in the browser
|
||||
2. Click **Check In**
|
||||
|
||||
Or from a terminal:
|
||||
|
||||
```
|
||||
fieldwitness fieldkit checkin
|
||||
```
|
||||
|
||||
If you miss your check-in window, the system will destroy all data after the grace period.
|
||||
|
||||
> **If you are unable to check in, contact your editor immediately.**
|
||||
|
||||
---
|
||||
|
||||
## Emergency: Destroying All Data
|
||||
|
||||
If you believe the device will be seized:
|
||||
|
||||
1. **Pull the USB stick** -- the laptop retains nothing
|
||||
2. If you cannot pull the USB: click **Fieldkit** then **Emergency Purge** and
|
||||
confirm with `CONFIRM-PURGE`
|
||||
|
||||
Everything is gone. Keys, photos, attestations, messages -- all destroyed.
|
||||
|
||||
---
|
||||
|
||||
## Shutting Down
|
||||
|
||||
1. **Close the browser**
|
||||
2. **Pull the USB stick**
|
||||
|
||||
The laptop returns to its normal state. No trace of FieldWitness remains.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Problem | Solution |
|
||||
|---|---|
|
||||
| Laptop does not boot from USB | Press F12 (or F2, Del) during startup to enter boot menu. Select the USB drive. Disable Secure Boot in BIOS if needed. |
|
||||
| "Certificate warning" in browser | Normal for self-signed certificates. Click "Advanced" then "Accept the risk" or "Proceed." |
|
||||
| Cannot connect to web UI | Wait 30 seconds after boot. Try refreshing the browser. The URL is `https://127.0.0.1:5000`. |
|
||||
| Forgot passphrase or PIN | You cannot recover encrypted data without the correct passphrase and PIN. Contact your admin. |
|
||||
| USB stick lost or broken | Get a new USB from your admin. If you had a backup, they can restore your keys onto the new stick. |
|
||||
|
||||
---
|
||||
|
||||
## Key Rules
|
||||
|
||||
1. **Never leave the USB in an unattended laptop**
|
||||
2. **Check in on time** if the dead man's switch is enabled
|
||||
3. **Back up your USB** -- your admin can help with this
|
||||
4. **Verify fingerprints** before trusting a collaborator's key
|
||||
5. **Use transport-aware encoding** when sending stego images through messaging apps
|
||||
@ -1,27 +1,27 @@
|
||||
"""
|
||||
SooSeF Web Frontend
|
||||
FieldWitness Web Frontend
|
||||
|
||||
Flask application factory that unifies Stegasoo (steganography) and Verisoo
|
||||
Flask application factory that unifies Stego (steganography) and Attest
|
||||
(provenance attestation) into a single web UI with fieldkit security features.
|
||||
|
||||
ARCHITECTURE
|
||||
============
|
||||
|
||||
The stegasoo web UI (3,600+ lines, 60 routes) is mounted wholesale via
|
||||
_register_stegasoo_routes() rather than being rewritten into a blueprint.
|
||||
The stego web UI (3,600+ lines, 60 routes) is mounted wholesale via
|
||||
_register_stego_routes() rather than being rewritten into a blueprint.
|
||||
This preserves the battle-tested subprocess isolation, async job management,
|
||||
and all existing route logic without modification.
|
||||
|
||||
SooSeF-native features (attest, fieldkit, keys) are clean blueprints.
|
||||
FieldWitness-native features (attest, fieldkit, keys) are clean blueprints.
|
||||
|
||||
Stegasoo routes (mounted at root):
|
||||
Stego routes (mounted at root):
|
||||
/encode, /decode, /generate, /tools, /api/*
|
||||
|
||||
SooSeF blueprints:
|
||||
FieldWitness blueprints:
|
||||
/attest, /verify → attest blueprint
|
||||
/fieldkit/* → fieldkit blueprint
|
||||
/keys/* → keys blueprint
|
||||
/admin/* → admin blueprint (extends stegasoo's)
|
||||
/admin/* → admin blueprint (extends stego's)
|
||||
"""
|
||||
|
||||
import io
|
||||
@ -42,18 +42,18 @@ from flask import (
|
||||
url_for,
|
||||
)
|
||||
|
||||
import soosef
|
||||
from soosef.config import SoosefConfig
|
||||
from soosef.paths import INSTANCE_DIR, SECRET_KEY_FILE, TEMP_DIR, ensure_dirs
|
||||
import fieldwitness
|
||||
from fieldwitness.config import FieldWitnessConfig
|
||||
from fieldwitness.paths import INSTANCE_DIR, SECRET_KEY_FILE, TEMP_DIR, ensure_dirs
|
||||
|
||||
# Suppress numpy/scipy warnings in subprocesses
|
||||
os.environ["NUMPY_MADVISE_HUGEPAGE"] = "0"
|
||||
os.environ["OMP_NUM_THREADS"] = "1"
|
||||
|
||||
|
||||
def create_app(config: SoosefConfig | None = None) -> Flask:
|
||||
def create_app(config: FieldWitnessConfig | None = None) -> Flask:
|
||||
"""Application factory."""
|
||||
config = config or SoosefConfig.load()
|
||||
config = config or FieldWitnessConfig.load()
|
||||
ensure_dirs()
|
||||
|
||||
web_dir = Path(__file__).parent
|
||||
@ -68,7 +68,7 @@ def create_app(config: SoosefConfig | None = None) -> Flask:
|
||||
app.config["MAX_CONTENT_LENGTH"] = config.max_upload_mb * 1024 * 1024
|
||||
app.config["AUTH_ENABLED"] = config.auth_enabled
|
||||
app.config["HTTPS_ENABLED"] = config.https_enabled
|
||||
app.config["SOOSEF_CONFIG"] = config
|
||||
app.config["FIELDWITNESS_CONFIG"] = config
|
||||
|
||||
# Session security: timeout + secure cookie flags
|
||||
from datetime import timedelta
|
||||
@ -84,7 +84,7 @@ def create_app(config: SoosefConfig | None = None) -> Flask:
|
||||
|
||||
csrf = CSRFProtect(app)
|
||||
|
||||
# Point temp_storage at ~/.soosef/temp/ before any routes run, so all
|
||||
# Point temp_storage at ~/.fieldwitness/temp/ before any routes run, so all
|
||||
# uploaded files land where the killswitch's destroy_temp_files step
|
||||
# expects them. Must happen after ensure_dirs() so the directory exists.
|
||||
import temp_storage as _ts
|
||||
@ -103,10 +103,10 @@ def create_app(config: SoosefConfig | None = None) -> Flask:
|
||||
|
||||
init_auth(app)
|
||||
|
||||
# ── Register stegasoo routes ──────────────────────────────────
|
||||
_register_stegasoo_routes(app)
|
||||
# ── Register stego routes ──────────────────────────────────
|
||||
_register_stego_routes(app)
|
||||
|
||||
# ── Register SooSeF-native blueprints ─────────────────────────
|
||||
# ── Register FieldWitness-native blueprints ─────────────────────────
|
||||
from frontends.web.blueprints.attest import bp as attest_bp
|
||||
from frontends.web.blueprints.fieldkit import bp as fieldkit_bp
|
||||
from frontends.web.blueprints.keys import bp as keys_bp
|
||||
@ -115,11 +115,23 @@ def create_app(config: SoosefConfig | None = None) -> Flask:
|
||||
app.register_blueprint(fieldkit_bp)
|
||||
app.register_blueprint(keys_bp)
|
||||
|
||||
from frontends.web.blueprints.dropbox import bp as dropbox_bp
|
||||
from frontends.web.blueprints.federation import bp as federation_bp
|
||||
|
||||
app.register_blueprint(dropbox_bp)
|
||||
app.register_blueprint(federation_bp)
|
||||
|
||||
# Exempt only the source-facing upload route from CSRF (sources don't have sessions).
|
||||
# The admin and verify-receipt routes in the dropbox blueprint retain CSRF protection.
|
||||
from frontends.web.blueprints.dropbox import upload as dropbox_upload
|
||||
|
||||
csrf.exempt(dropbox_upload)
|
||||
|
||||
# ── Context processor (injected into ALL templates) ───────────
|
||||
|
||||
@app.context_processor
|
||||
def inject_globals():
|
||||
from soosef.keystore import KeystoreManager
|
||||
from fieldwitness.keystore import KeystoreManager
|
||||
|
||||
ks = KeystoreManager()
|
||||
ks_status = ks.status()
|
||||
@ -127,7 +139,7 @@ def create_app(config: SoosefConfig | None = None) -> Flask:
|
||||
# Fieldkit alert level
|
||||
fieldkit_status = "ok"
|
||||
if config.deadman_enabled:
|
||||
from soosef.fieldkit.deadman import DeadmanSwitch
|
||||
from fieldwitness.fieldkit.deadman import DeadmanSwitch
|
||||
|
||||
dm = DeadmanSwitch()
|
||||
if dm.should_fire():
|
||||
@ -135,10 +147,10 @@ def create_app(config: SoosefConfig | None = None) -> Flask:
|
||||
elif dm.is_overdue():
|
||||
fieldkit_status = "warn"
|
||||
|
||||
# Stegasoo capabilities
|
||||
# Stego capabilities
|
||||
try:
|
||||
from soosef.stegasoo import HAS_AUDIO_SUPPORT, get_channel_status, has_dct_support
|
||||
from soosef.stegasoo.constants import (
|
||||
from fieldwitness.stego import HAS_AUDIO_SUPPORT, get_channel_status, has_dct_support
|
||||
from fieldwitness.stego.constants import (
|
||||
DEFAULT_PASSPHRASE_WORDS,
|
||||
MAX_FILE_PAYLOAD_SIZE,
|
||||
MAX_MESSAGE_CHARS,
|
||||
@ -154,7 +166,7 @@ def create_app(config: SoosefConfig | None = None) -> Flask:
|
||||
has_audio = HAS_AUDIO_SUPPORT
|
||||
channel_status = get_channel_status()
|
||||
|
||||
# Stegasoo-specific template vars (needed by stego templates)
|
||||
# Stego-specific template vars (needed by stego templates)
|
||||
stego_vars = {
|
||||
"has_dct": has_dct,
|
||||
"has_audio": has_audio,
|
||||
@ -176,13 +188,13 @@ def create_app(config: SoosefConfig | None = None) -> Flask:
|
||||
has_audio = False
|
||||
stego_vars = {}
|
||||
|
||||
# Verisoo availability
|
||||
# Attest availability
|
||||
try:
|
||||
import soosef.verisoo # noqa: F401
|
||||
import fieldwitness.attest # noqa: F401
|
||||
|
||||
has_verisoo = True
|
||||
has_attest = True
|
||||
except ImportError:
|
||||
has_verisoo = False
|
||||
has_attest = False
|
||||
|
||||
# Saved channel keys for authenticated users
|
||||
saved_channel_keys = []
|
||||
@ -197,8 +209,8 @@ def create_app(config: SoosefConfig | None = None) -> Flask:
|
||||
pass
|
||||
|
||||
base_vars = {
|
||||
"version": soosef.__version__,
|
||||
"has_verisoo": has_verisoo,
|
||||
"version": fieldwitness.__version__,
|
||||
"has_attest": has_attest,
|
||||
"has_fieldkit": config.killswitch_enabled or config.deadman_enabled,
|
||||
"fieldkit_status": fieldkit_status,
|
||||
"channel_configured": ks_status.has_channel_key,
|
||||
@ -228,23 +240,29 @@ def create_app(config: SoosefConfig | None = None) -> Flask:
|
||||
def health():
|
||||
"""System health and capability report.
|
||||
|
||||
Unauthenticated — returns what's installed, what's missing,
|
||||
and what's degraded. No secrets or key material exposed.
|
||||
Anonymous callers get only {"status": "ok"} — no operational
|
||||
intelligence. Authenticated users get the full report.
|
||||
"""
|
||||
# Anonymous callers get minimal response to prevent info leakage
|
||||
# (deadman status, key presence, memory, etc. are operational intel)
|
||||
if not is_authenticated():
|
||||
from flask import jsonify
|
||||
return jsonify({"status": "ok", "version": __import__("fieldwitness").__version__})
|
||||
|
||||
import platform
|
||||
import sys
|
||||
|
||||
from flask import jsonify
|
||||
|
||||
from soosef.keystore.manager import KeystoreManager
|
||||
from fieldwitness.keystore.manager import KeystoreManager
|
||||
|
||||
ks = KeystoreManager()
|
||||
|
||||
# Core modules
|
||||
modules = {}
|
||||
for name, import_path in [
|
||||
("stegasoo", "soosef.stegasoo"),
|
||||
("verisoo", "soosef.verisoo"),
|
||||
("stego", "fieldwitness.stego"),
|
||||
("attest", "fieldwitness.attest"),
|
||||
]:
|
||||
try:
|
||||
mod = __import__(import_path, fromlist=["__version__"])
|
||||
@ -257,27 +275,27 @@ def create_app(config: SoosefConfig | None = None) -> Flask:
|
||||
|
||||
# DCT steganography
|
||||
try:
|
||||
from soosef.stegasoo import has_dct_support
|
||||
from fieldwitness.stego import has_dct_support
|
||||
capabilities["stego_dct"] = {
|
||||
"status": "ok" if has_dct_support() else "unavailable",
|
||||
"hint": None if has_dct_support() else "Install soosef[stego-dct] (scipy, jpeglib, reedsolo)",
|
||||
"hint": None if has_dct_support() else "Install fieldwitness[stego-dct] (scipy, jpeglib, reedsolo)",
|
||||
}
|
||||
except ImportError:
|
||||
capabilities["stego_dct"] = {"status": "missing", "hint": "Install soosef[stego-dct]"}
|
||||
capabilities["stego_dct"] = {"status": "missing", "hint": "Install fieldwitness[stego-dct]"}
|
||||
|
||||
# Audio steganography
|
||||
try:
|
||||
from soosef.stegasoo import HAS_AUDIO_SUPPORT
|
||||
from fieldwitness.stego import HAS_AUDIO_SUPPORT
|
||||
capabilities["stego_audio"] = {
|
||||
"status": "ok" if HAS_AUDIO_SUPPORT else "unavailable",
|
||||
"hint": None if HAS_AUDIO_SUPPORT else "Install soosef[stego-audio] (soundfile, numpy)",
|
||||
"hint": None if HAS_AUDIO_SUPPORT else "Install fieldwitness[stego-audio] (soundfile, numpy)",
|
||||
}
|
||||
except ImportError:
|
||||
capabilities["stego_audio"] = {"status": "missing", "hint": "Install soosef[stego-audio]"}
|
||||
capabilities["stego_audio"] = {"status": "missing", "hint": "Install fieldwitness[stego-audio]"}
|
||||
|
||||
# Video steganography
|
||||
try:
|
||||
from soosef.stegasoo.constants import VIDEO_ENABLED
|
||||
from fieldwitness.stego.constants import VIDEO_ENABLED
|
||||
capabilities["stego_video"] = {
|
||||
"status": "ok" if VIDEO_ENABLED else "unavailable",
|
||||
"hint": None if VIDEO_ENABLED else "Requires ffmpeg in PATH",
|
||||
@ -285,33 +303,33 @@ def create_app(config: SoosefConfig | None = None) -> Flask:
|
||||
except (ImportError, AttributeError):
|
||||
capabilities["stego_video"] = {"status": "missing", "hint": "Requires ffmpeg"}
|
||||
|
||||
# LMDB (verisoo storage)
|
||||
# LMDB (attest storage)
|
||||
try:
|
||||
import lmdb # noqa: F401
|
||||
capabilities["lmdb"] = {"status": "ok"}
|
||||
except ImportError:
|
||||
capabilities["lmdb"] = {"status": "missing", "hint": "Install soosef[attest]"}
|
||||
capabilities["lmdb"] = {"status": "missing", "hint": "Install fieldwitness[attest]"}
|
||||
|
||||
# Perceptual hashing
|
||||
try:
|
||||
import imagehash # noqa: F401
|
||||
capabilities["imagehash"] = {"status": "ok"}
|
||||
except ImportError:
|
||||
capabilities["imagehash"] = {"status": "missing", "hint": "Install soosef[attest]"}
|
||||
capabilities["imagehash"] = {"status": "missing", "hint": "Install fieldwitness[attest]"}
|
||||
|
||||
# USB monitoring
|
||||
try:
|
||||
import pyudev # noqa: F401
|
||||
capabilities["usb_monitor"] = {"status": "ok"}
|
||||
except ImportError:
|
||||
capabilities["usb_monitor"] = {"status": "unavailable", "hint": "Install soosef[fieldkit] (Linux only)"}
|
||||
capabilities["usb_monitor"] = {"status": "unavailable", "hint": "Install fieldwitness[fieldkit] (Linux only)"}
|
||||
|
||||
# GPIO (RPi killswitch)
|
||||
try:
|
||||
import gpiozero # noqa: F401
|
||||
capabilities["gpio"] = {"status": "ok"}
|
||||
except ImportError:
|
||||
capabilities["gpio"] = {"status": "unavailable", "hint": "Install soosef[rpi] (Raspberry Pi only)"}
|
||||
capabilities["gpio"] = {"status": "unavailable", "hint": "Install fieldwitness[rpi] (Raspberry Pi only)"}
|
||||
|
||||
# Key status (existence only, no material)
|
||||
keys = {
|
||||
@ -332,7 +350,7 @@ def create_app(config: SoosefConfig | None = None) -> Flask:
|
||||
"chain_enabled": config.chain_enabled,
|
||||
}
|
||||
if config.deadman_enabled:
|
||||
from soosef.fieldkit.deadman import DeadmanSwitch
|
||||
from fieldwitness.fieldkit.deadman import DeadmanSwitch
|
||||
dm = DeadmanSwitch()
|
||||
dm_status = dm.status()
|
||||
fieldkit["deadman_armed"] = dm_status["armed"]
|
||||
@ -362,7 +380,7 @@ def create_app(config: SoosefConfig | None = None) -> Flask:
|
||||
|
||||
return jsonify({
|
||||
"status": "ok" if all_ok else "degraded",
|
||||
"version": __import__("soosef").__version__,
|
||||
"version": __import__("fieldwitness").__version__,
|
||||
"modules": modules,
|
||||
"capabilities": capabilities,
|
||||
"keys": keys,
|
||||
@ -390,26 +408,26 @@ except ImportError:
|
||||
_HAS_QRCODE_READ = False
|
||||
|
||||
|
||||
# ── Stegasoo route mounting ──────────────────────────────────────────
|
||||
# ── Stego route mounting ──────────────────────────────────────────
|
||||
|
||||
|
||||
def _register_stegasoo_routes(app: Flask) -> None:
|
||||
def _register_stego_routes(app: Flask) -> None:
|
||||
"""
|
||||
Mount all stegasoo web routes into the Flask app.
|
||||
Mount all stego web routes into the Flask app.
|
||||
|
||||
Rather than rewriting 3,600 lines of battle-tested route logic,
|
||||
we import stegasoo's app.py and re-register its routes.
|
||||
The stegasoo templates are in templates/stego/ and extend our base.html.
|
||||
we import fieldwitness.stego's app.py and re-register its routes.
|
||||
The stego templates are in templates/stego/ and extend our base.html.
|
||||
"""
|
||||
import temp_storage
|
||||
from auth import admin_required, login_required
|
||||
from soosef.stegasoo import (
|
||||
from fieldwitness.stego import (
|
||||
export_rsa_key_pem,
|
||||
generate_credentials,
|
||||
get_channel_status,
|
||||
load_rsa_key,
|
||||
)
|
||||
from soosef.stegasoo.constants import (
|
||||
from fieldwitness.stego.constants import (
|
||||
DEFAULT_PASSPHRASE_WORDS,
|
||||
MAX_PIN_LENGTH,
|
||||
MIN_PASSPHRASE_WORDS,
|
||||
@ -417,7 +435,7 @@ def _register_stegasoo_routes(app: Flask) -> None:
|
||||
TEMP_FILE_EXPIRY,
|
||||
VALID_RSA_SIZES,
|
||||
)
|
||||
from soosef.stegasoo.qr_utils import (
|
||||
from fieldwitness.stego.qr_utils import (
|
||||
can_fit_in_qr,
|
||||
generate_qr_code,
|
||||
)
|
||||
@ -425,7 +443,7 @@ def _register_stegasoo_routes(app: Flask) -> None:
|
||||
SubprocessStego,
|
||||
)
|
||||
|
||||
from soosef.audit import log_action
|
||||
from fieldwitness.audit import log_action
|
||||
|
||||
# Initialize subprocess wrapper
|
||||
subprocess_stego = SubprocessStego(timeout=180)
|
||||
@ -482,9 +500,11 @@ def _register_stegasoo_routes(app: Flask) -> None:
|
||||
username = request.form.get("username", "")
|
||||
password = request.form.get("password", "")
|
||||
|
||||
# Check lockout
|
||||
max_attempts = config.login_lockout_attempts
|
||||
lockout_mins = config.login_lockout_minutes
|
||||
# Check lockout — read from app.config since _register_stego_routes
|
||||
# is a module-level function without access to create_app's config.
|
||||
_fw_config = app.config.get("FIELDWITNESS_CONFIG")
|
||||
max_attempts = _fw_config.login_lockout_attempts if _fw_config else 5
|
||||
lockout_mins = _fw_config.login_lockout_minutes if _fw_config else 15
|
||||
now = time.time()
|
||||
window = lockout_mins * 60
|
||||
attempts = _login_attempts.get(username, [])
|
||||
@ -493,7 +513,7 @@ def _register_stegasoo_routes(app: Flask) -> None:
|
||||
_login_attempts[username] = attempts
|
||||
|
||||
if len(attempts) >= max_attempts:
|
||||
from soosef.audit import log_action
|
||||
from fieldwitness.audit import log_action
|
||||
|
||||
log_action(
|
||||
actor=username,
|
||||
@ -800,7 +820,7 @@ def _register_stegasoo_routes(app: Flask) -> None:
|
||||
io.BytesIO(qr_png),
|
||||
mimetype="image/png",
|
||||
as_attachment=True,
|
||||
download_name="soosef_rsa_key_qr.png",
|
||||
download_name="fieldwitness_rsa_key_qr.png",
|
||||
)
|
||||
except Exception as e:
|
||||
return f"Error generating QR code: {e}", 500
|
||||
@ -820,7 +840,7 @@ def _register_stegasoo_routes(app: Flask) -> None:
|
||||
private_key = load_rsa_key(key_pem.encode("utf-8"))
|
||||
encrypted_pem = export_rsa_key_pem(private_key, password=password)
|
||||
key_id = secrets.token_hex(4)
|
||||
filename = f"soosef_key_{private_key.key_size}_{key_id}.pem"
|
||||
filename = f"fieldwitness_key_{private_key.key_size}_{key_id}.pem"
|
||||
return send_file(
|
||||
io.BytesIO(encrypted_pem),
|
||||
mimetype="application/x-pem-file",
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
"""
|
||||
Stegasoo Authentication Module (v4.1.0)
|
||||
Stego Authentication Module (v4.1.0)
|
||||
|
||||
Multi-user authentication with role-based access control.
|
||||
- Admin user created at first-run setup
|
||||
@ -20,7 +20,7 @@ from argon2 import PasswordHasher
|
||||
from argon2.exceptions import VerifyMismatchError
|
||||
from flask import current_app, flash, g, redirect, session, url_for
|
||||
|
||||
# Argon2 password hasher (lighter than stegasoo's 256MB for faster login)
|
||||
# Argon2 password hasher (lighter than stego's 256MB for faster login)
|
||||
ph = PasswordHasher(
|
||||
time_cost=3,
|
||||
memory_cost=65536, # 64MB
|
||||
@ -51,8 +51,8 @@ class User:
|
||||
|
||||
|
||||
def get_db_path() -> Path:
|
||||
"""Get database path — uses soosef auth directory."""
|
||||
from soosef.paths import AUTH_DB
|
||||
"""Get database path — uses fieldwitness auth directory."""
|
||||
from fieldwitness.paths import AUTH_DB
|
||||
|
||||
AUTH_DB.parent.mkdir(parents=True, exist_ok=True)
|
||||
return AUTH_DB
|
||||
@ -273,7 +273,7 @@ def verify_and_reset_admin_password(recovery_key: str, new_password: str) -> tup
|
||||
Returns:
|
||||
(success, message) tuple
|
||||
"""
|
||||
from soosef.stegasoo.recovery import verify_recovery_key
|
||||
from fieldwitness.stego.recovery import verify_recovery_key
|
||||
|
||||
stored_hash = get_recovery_key_hash()
|
||||
if not stored_hash:
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
"""
|
||||
Admin routes are registered directly in app.py via _register_stegasoo_routes()
|
||||
Admin routes are registered directly in app.py via _register_stego_routes()
|
||||
alongside the auth routes (setup, login, logout, account, admin/users).
|
||||
"""
|
||||
|
||||
@ -1,10 +1,13 @@
|
||||
"""
|
||||
Attestation blueprint — attest and verify images via Verisoo.
|
||||
Attestation blueprint — attest and verify files via Attest.
|
||||
|
||||
Wraps verisoo's attestation and verification libraries to provide:
|
||||
- Image attestation: upload → hash → sign → store in append-only log
|
||||
- Image verification: upload → hash → search log → display matches
|
||||
Wraps attest's attestation and verification libraries to provide:
|
||||
- File attestation: upload → hash → sign → store in append-only log
|
||||
- File verification: upload → hash → search log → display matches
|
||||
- Verification receipt: same as verify but returns a downloadable JSON file
|
||||
|
||||
Supports any file type. Perceptual hashing (phash, dhash) is available for
|
||||
image files only. Non-image files are attested by SHA-256 hash.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@ -21,27 +24,27 @@ bp = Blueprint("attest", __name__)
|
||||
|
||||
|
||||
def _get_storage():
|
||||
"""Get verisoo LocalStorage pointed at soosef's attestation directory."""
|
||||
from soosef.verisoo.storage import LocalStorage
|
||||
"""Get attest LocalStorage pointed at fieldwitness's attestation directory."""
|
||||
from fieldwitness.attest.storage import LocalStorage
|
||||
|
||||
from soosef.paths import ATTESTATIONS_DIR
|
||||
from fieldwitness.paths import ATTESTATIONS_DIR
|
||||
|
||||
return LocalStorage(base_path=ATTESTATIONS_DIR)
|
||||
|
||||
|
||||
def _get_private_key():
|
||||
"""Load the Ed25519 private key from soosef identity directory."""
|
||||
from soosef.verisoo.crypto import load_private_key
|
||||
"""Load the Ed25519 private key from fieldwitness identity directory."""
|
||||
from fieldwitness.attest.crypto import load_private_key
|
||||
|
||||
from soosef.paths import IDENTITY_PRIVATE_KEY
|
||||
from fieldwitness.paths import IDENTITY_PRIVATE_KEY
|
||||
|
||||
if not IDENTITY_PRIVATE_KEY.exists():
|
||||
return None
|
||||
return load_private_key(IDENTITY_PRIVATE_KEY)
|
||||
|
||||
|
||||
def _wrap_in_chain(verisoo_record, private_key, metadata: dict | None = None):
|
||||
"""Wrap a Verisoo attestation record in the hash chain.
|
||||
def _wrap_in_chain(attest_record, private_key, metadata: dict | None = None):
|
||||
"""Wrap a Attest attestation record in the hash chain.
|
||||
|
||||
Returns the chain record, or None if chain is disabled.
|
||||
"""
|
||||
@ -49,23 +52,23 @@ def _wrap_in_chain(verisoo_record, private_key, metadata: dict | None = None):
|
||||
|
||||
from cryptography.hazmat.primitives.serialization import load_pem_private_key
|
||||
|
||||
from soosef.config import SoosefConfig
|
||||
from soosef.federation.chain import ChainStore
|
||||
from soosef.paths import CHAIN_DIR, IDENTITY_PRIVATE_KEY
|
||||
from fieldwitness.config import FieldWitnessConfig
|
||||
from fieldwitness.federation.chain import ChainStore
|
||||
from fieldwitness.paths import CHAIN_DIR, IDENTITY_PRIVATE_KEY
|
||||
|
||||
config = SoosefConfig.load()
|
||||
config = FieldWitnessConfig.load()
|
||||
if not config.chain_enabled or not config.chain_auto_wrap:
|
||||
return None
|
||||
|
||||
# Hash the verisoo record bytes as chain content
|
||||
# Hash the attest record bytes as chain content
|
||||
record_bytes = (
|
||||
verisoo_record.to_bytes()
|
||||
if hasattr(verisoo_record, "to_bytes")
|
||||
else str(verisoo_record).encode()
|
||||
attest_record.to_bytes()
|
||||
if hasattr(attest_record, "to_bytes")
|
||||
else str(attest_record).encode()
|
||||
)
|
||||
content_hash = hashlib.sha256(record_bytes).digest()
|
||||
|
||||
# Load Ed25519 key for chain signing (need the cryptography key, not verisoo's)
|
||||
# Load Ed25519 key for chain signing (need the cryptography key, not attest's)
|
||||
priv_pem = IDENTITY_PRIVATE_KEY.read_bytes()
|
||||
chain_private_key = load_pem_private_key(priv_pem, password=None)
|
||||
|
||||
@ -79,31 +82,51 @@ def _wrap_in_chain(verisoo_record, private_key, metadata: dict | None = None):
|
||||
store = ChainStore(CHAIN_DIR)
|
||||
return store.append(
|
||||
content_hash=content_hash,
|
||||
content_type="verisoo/attestation-v1",
|
||||
content_type="attest/attestation-v1",
|
||||
private_key=chain_private_key,
|
||||
metadata=chain_metadata,
|
||||
)
|
||||
|
||||
|
||||
def _allowed_image(filename: str) -> bool:
|
||||
_ALLOWED_EXTENSIONS: frozenset[str] = frozenset({
|
||||
# Images
|
||||
"png", "jpg", "jpeg", "bmp", "gif", "webp", "tiff", "tif", "heic", "heif", "raw",
|
||||
# Documents
|
||||
"pdf", "doc", "docx", "xls", "xlsx", "ppt", "pptx", "odt", "ods", "odp",
|
||||
"txt", "rtf", "csv", "tsv", "json", "xml", "html", "htm",
|
||||
# Audio
|
||||
"mp3", "wav", "m4a", "aac", "ogg", "flac", "opus", "wma",
|
||||
# Video
|
||||
"mp4", "mov", "avi", "mkv", "webm", "m4v", "wmv",
|
||||
# Archives / data
|
||||
"zip", "tar", "gz", "bz2", "xz", "7z",
|
||||
# Sensor / scientific data
|
||||
"gpx", "kml", "geojson", "npy", "parquet", "bin", "dat",
|
||||
})
|
||||
|
||||
_IMAGE_EXTENSIONS: frozenset[str] = frozenset({
|
||||
"png", "jpg", "jpeg", "bmp", "gif", "webp", "tiff", "tif", "heic", "heif",
|
||||
})
|
||||
|
||||
|
||||
def _allowed_file(filename: str) -> bool:
|
||||
"""Return True if the filename has an extension on the allowlist."""
|
||||
if not filename or "." not in filename:
|
||||
return False
|
||||
return filename.rsplit(".", 1)[1].lower() in {
|
||||
"png",
|
||||
"jpg",
|
||||
"jpeg",
|
||||
"bmp",
|
||||
"gif",
|
||||
"webp",
|
||||
"tiff",
|
||||
"tif",
|
||||
}
|
||||
return filename.rsplit(".", 1)[1].lower() in _ALLOWED_EXTENSIONS
|
||||
|
||||
|
||||
def _is_image_file(filename: str) -> bool:
|
||||
"""Return True if the filename is a known image type."""
|
||||
if not filename or "." not in filename:
|
||||
return False
|
||||
return filename.rsplit(".", 1)[1].lower() in _IMAGE_EXTENSIONS
|
||||
|
||||
|
||||
@bp.route("/attest", methods=["GET", "POST"])
|
||||
@login_required
|
||||
def attest():
|
||||
"""Create a provenance attestation for an image."""
|
||||
"""Create a provenance attestation for a file."""
|
||||
# Check identity exists
|
||||
private_key = _get_private_key()
|
||||
has_identity = private_key is not None
|
||||
@ -111,42 +134,78 @@ def attest():
|
||||
if request.method == "POST":
|
||||
if not has_identity:
|
||||
flash(
|
||||
"No identity configured. Run 'soosef init' or generate one from the Keys page.",
|
||||
"No identity configured. Run 'fieldwitness init' or generate one from the Keys page.",
|
||||
"error",
|
||||
)
|
||||
return redirect(url_for("attest.attest"))
|
||||
|
||||
image_file = request.files.get("image")
|
||||
if not image_file or not image_file.filename:
|
||||
flash("Please select an image to attest.", "error")
|
||||
evidence_file = request.files.get("image")
|
||||
if not evidence_file or not evidence_file.filename:
|
||||
flash("Please select a file to attest.", "error")
|
||||
return redirect(url_for("attest.attest"))
|
||||
|
||||
if not _allowed_image(image_file.filename):
|
||||
flash("Unsupported image format. Use PNG, JPG, WebP, TIFF, or BMP.", "error")
|
||||
if not _allowed_file(evidence_file.filename):
|
||||
flash(
|
||||
"Unsupported file type. Supported types include images, documents, "
|
||||
"audio, video, CSV, and sensor data files.",
|
||||
"error",
|
||||
)
|
||||
return redirect(url_for("attest.attest"))
|
||||
|
||||
try:
|
||||
image_data = image_file.read()
|
||||
file_data = evidence_file.read()
|
||||
is_image = _is_image_file(evidence_file.filename)
|
||||
|
||||
# Build optional metadata
|
||||
metadata = {}
|
||||
caption = request.form.get("caption", "").strip()
|
||||
location_name = request.form.get("location_name", "").strip()
|
||||
investigation = request.form.get("investigation", "").strip()
|
||||
parent_record_id = request.form.get("parent_record_id", "").strip()
|
||||
derivation_type = request.form.get("derivation_type", "").strip()
|
||||
if caption:
|
||||
metadata["caption"] = caption
|
||||
if location_name:
|
||||
metadata["location_name"] = location_name
|
||||
if investigation:
|
||||
metadata["investigation"] = investigation
|
||||
if parent_record_id:
|
||||
metadata["derived_from"] = parent_record_id
|
||||
metadata["derivation_type"] = derivation_type or "unspecified"
|
||||
|
||||
auto_exif = request.form.get("auto_exif", "on") == "on"
|
||||
strip_device = request.form.get("strip_device", "on") == "on"
|
||||
|
||||
# Create the attestation
|
||||
from soosef.verisoo.attestation import create_attestation
|
||||
# Extract-then-classify: get evidentiary metadata before attestation.
|
||||
# Only applicable to image files — silently skip for other types.
|
||||
if is_image and auto_exif and strip_device:
|
||||
try:
|
||||
from fieldwitness.metadata import extract_and_classify
|
||||
|
||||
extraction = extract_and_classify(file_data)
|
||||
# Merge evidentiary fields (GPS, timestamp) but exclude
|
||||
# dangerous device fields (serial, firmware version)
|
||||
for key, value in extraction.evidentiary.items():
|
||||
if key not in metadata: # User metadata takes precedence
|
||||
if hasattr(value, "isoformat"):
|
||||
metadata[f"exif_{key}"] = value.isoformat()
|
||||
elif isinstance(value, dict):
|
||||
metadata[f"exif_{key}"] = value
|
||||
else:
|
||||
metadata[f"exif_{key}"] = str(value)
|
||||
except Exception:
|
||||
pass # EXIF extraction is best-effort
|
||||
|
||||
# Create the attestation. create_attestation() calls hash_image()
|
||||
# internally; for non-image files we pre-compute hashes via
|
||||
# hash_file() and use create_attestation_from_hashes() instead.
|
||||
from fieldwitness.attest.attestation import create_attestation
|
||||
|
||||
attestation = create_attestation(
|
||||
image_data=image_data,
|
||||
image_data=file_data,
|
||||
private_key=private_key,
|
||||
metadata=metadata if metadata else None,
|
||||
auto_exif=auto_exif,
|
||||
auto_exif=is_image and auto_exif and not strip_device,
|
||||
)
|
||||
|
||||
# Store in the append-only log
|
||||
@ -162,20 +221,20 @@ def attest():
|
||||
|
||||
logging.getLogger(__name__).warning("Chain wrapping failed: %s", e)
|
||||
flash(
|
||||
"Attestation saved, but chain wrapping failed. " "Check chain configuration.",
|
||||
"Attestation saved, but chain wrapping failed. Check chain configuration.",
|
||||
"warning",
|
||||
)
|
||||
|
||||
# Save our own identity so we can look it up during verification
|
||||
from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
|
||||
from soosef.verisoo.models import Identity
|
||||
from fieldwitness.attest.models import Identity
|
||||
|
||||
pub_key = private_key.public_key()
|
||||
pub_bytes = pub_key.public_bytes(Encoding.Raw, PublicFormat.Raw)
|
||||
identity = Identity(
|
||||
public_key=pub_bytes,
|
||||
fingerprint=attestation.record.attestor_fingerprint,
|
||||
metadata={"name": "SooSeF Local Identity"},
|
||||
metadata={"name": "FieldWitness Local Identity"},
|
||||
)
|
||||
try:
|
||||
storage.save_identity(identity)
|
||||
@ -199,7 +258,8 @@ def attest():
|
||||
location_name=metadata.get("location_name", ""),
|
||||
exif_metadata=record.metadata,
|
||||
index=index,
|
||||
filename=image_file.filename,
|
||||
filename=evidence_file.filename,
|
||||
is_image=is_image,
|
||||
chain_index=chain_record.chain_index if chain_record else None,
|
||||
)
|
||||
|
||||
@ -213,18 +273,16 @@ def attest():
|
||||
@bp.route("/attest/batch", methods=["POST"])
|
||||
@login_required
|
||||
def attest_batch():
|
||||
"""Batch attestation — accepts multiple image files.
|
||||
"""Batch attestation — accepts multiple files of any supported type.
|
||||
|
||||
Returns JSON with results for each file (success/skip/error).
|
||||
Skips images already attested (by SHA-256 match).
|
||||
Skips files already attested (by SHA-256 match).
|
||||
"""
|
||||
import hashlib
|
||||
|
||||
from soosef.verisoo.hashing import hash_image
|
||||
|
||||
private_key = _get_private_key()
|
||||
if private_key is None:
|
||||
return {"error": "No identity key. Run soosef init first."}, 400
|
||||
return {"error": "No identity key. Run fieldwitness init first."}, 400
|
||||
|
||||
files = request.files.getlist("images")
|
||||
if not files:
|
||||
@ -236,23 +294,27 @@ def attest_batch():
|
||||
for f in files:
|
||||
filename = f.filename or "unknown"
|
||||
try:
|
||||
image_data = f.read()
|
||||
sha256 = hashlib.sha256(image_data).hexdigest()
|
||||
if not _allowed_file(filename):
|
||||
results.append({"file": filename, "status": "skipped", "reason": "unsupported file type"})
|
||||
continue
|
||||
|
||||
# Skip already-attested images
|
||||
file_data = f.read()
|
||||
sha256 = hashlib.sha256(file_data).hexdigest()
|
||||
|
||||
# Skip already-attested files
|
||||
existing = storage.get_records_by_image_sha256(sha256)
|
||||
if existing:
|
||||
results.append({"file": filename, "status": "skipped", "reason": "already attested"})
|
||||
continue
|
||||
|
||||
from soosef.verisoo.attestation import create_attestation
|
||||
from fieldwitness.attest.attestation import create_attestation
|
||||
|
||||
attestation = create_attestation(image_data, private_key)
|
||||
attestation = create_attestation(file_data, private_key)
|
||||
index = storage.append_record(attestation.record)
|
||||
|
||||
# Wrap in chain if enabled
|
||||
chain_index = None
|
||||
config = request.app.config.get("SOOSEF_CONFIG") if hasattr(request, "app") else None
|
||||
config = request.app.config.get("FIELDWITNESS_CONFIG") if hasattr(request, "app") else None
|
||||
if config and getattr(config, "chain_enabled", False) and getattr(config, "chain_auto_wrap", False):
|
||||
try:
|
||||
chain_record = _wrap_in_chain(attestation.record, private_key, {})
|
||||
@ -283,17 +345,72 @@ def attest_batch():
|
||||
}
|
||||
|
||||
|
||||
def _verify_image(image_data: bytes) -> dict:
|
||||
@bp.route("/verify/batch", methods=["POST"])
|
||||
@login_required
|
||||
def verify_batch():
|
||||
"""Batch verification — accepts multiple files of any supported type.
|
||||
|
||||
Returns JSON with per-file verification results. Uses SHA-256
|
||||
fast path before falling back to perceptual scan (images only).
|
||||
"""
|
||||
files = request.files.getlist("images")
|
||||
if not files:
|
||||
return {"error": "No files uploaded"}, 400
|
||||
|
||||
results = []
|
||||
for f in files:
|
||||
filename = f.filename or "unknown"
|
||||
try:
|
||||
file_data = f.read()
|
||||
result = _verify_file(file_data)
|
||||
|
||||
if result["matches"]:
|
||||
best = result["matches"][0]
|
||||
results.append({
|
||||
"file": filename,
|
||||
"status": "verified",
|
||||
"match_type": best["match_type"],
|
||||
"record_id": best["record"].short_id if hasattr(best["record"], "short_id") else "unknown",
|
||||
"matches": len(result["matches"]),
|
||||
})
|
||||
else:
|
||||
results.append({"file": filename, "status": "unverified", "matches": 0})
|
||||
except Exception as e:
|
||||
results.append({"file": filename, "status": "error", "error": str(e)})
|
||||
|
||||
verified = sum(1 for r in results if r["status"] == "verified")
|
||||
unverified = sum(1 for r in results if r["status"] == "unverified")
|
||||
errors = sum(1 for r in results if r["status"] == "error")
|
||||
|
||||
# Count by match type
|
||||
exact = sum(1 for r in results if r.get("match_type") == "exact")
|
||||
perceptual = verified - exact
|
||||
|
||||
return {
|
||||
"total": len(results),
|
||||
"verified": verified,
|
||||
"verified_exact": exact,
|
||||
"verified_perceptual": perceptual,
|
||||
"unverified": unverified,
|
||||
"errors": errors,
|
||||
"results": results,
|
||||
}
|
||||
|
||||
|
||||
def _verify_file(file_data: bytes) -> dict:
|
||||
"""Run the full verification pipeline against the attestation log.
|
||||
|
||||
Works for any file type. Images get SHA-256 + perceptual matching;
|
||||
non-image files get SHA-256 matching only.
|
||||
|
||||
Returns a dict with keys:
|
||||
query_hashes — ImageHashes object from verisoo
|
||||
query_hashes — ImageHashes object from fieldwitness.attest
|
||||
matches — list of match dicts (record, match_type, distances, attestor_name)
|
||||
record_count — total records searched
|
||||
"""
|
||||
from soosef.verisoo.hashing import compute_all_distances, hash_image, is_same_image
|
||||
from fieldwitness.attest.hashing import compute_all_distances, hash_file, is_same_image
|
||||
|
||||
query_hashes = hash_image(image_data)
|
||||
query_hashes = hash_file(file_data)
|
||||
storage = _get_storage()
|
||||
stats = storage.get_stats()
|
||||
|
||||
@ -306,15 +423,15 @@ def _verify_image(image_data: bytes) -> dict:
|
||||
for record in exact_records:
|
||||
matches.append({"record": record, "match_type": "exact", "distances": {}})
|
||||
|
||||
# Perceptual fallback
|
||||
# Perceptual fallback via LMDB index (O(index) not O(n) full scan)
|
||||
if not matches and query_hashes.phash:
|
||||
all_records = [storage.get_record(i) for i in range(stats.record_count)]
|
||||
for record in all_records:
|
||||
similar = storage.find_similar_images(query_hashes.phash, max_distance=10)
|
||||
for record, distance in similar:
|
||||
distances = compute_all_distances(query_hashes, record.image_hashes)
|
||||
same, match_type = is_same_image(
|
||||
query_hashes, record.image_hashes, perceptual_threshold=10
|
||||
)
|
||||
if same:
|
||||
distances = compute_all_distances(query_hashes, record.image_hashes)
|
||||
matches.append(
|
||||
{
|
||||
"record": record,
|
||||
@ -345,17 +462,22 @@ def verify():
|
||||
The log read here is read-only and reveals no key material.
|
||||
"""
|
||||
if request.method == "POST":
|
||||
image_file = request.files.get("image")
|
||||
if not image_file or not image_file.filename:
|
||||
flash("Please select an image to verify.", "error")
|
||||
evidence_file = request.files.get("image")
|
||||
if not evidence_file or not evidence_file.filename:
|
||||
flash("Please select a file to verify.", "error")
|
||||
return redirect(url_for("attest.verify"))
|
||||
|
||||
if not _allowed_image(image_file.filename):
|
||||
flash("Unsupported image format.", "error")
|
||||
if not _allowed_file(evidence_file.filename):
|
||||
flash(
|
||||
"Unsupported file type. Upload any image, document, audio, video, or data file.",
|
||||
"error",
|
||||
)
|
||||
return redirect(url_for("attest.verify"))
|
||||
|
||||
try:
|
||||
result = _verify_image(image_file.read())
|
||||
file_data = evidence_file.read()
|
||||
is_image = _is_image_file(evidence_file.filename)
|
||||
result = _verify_file(file_data)
|
||||
query_hashes = result["query_hashes"]
|
||||
matches = result["matches"]
|
||||
|
||||
@ -365,7 +487,8 @@ def verify():
|
||||
found=False,
|
||||
message="No attestations in the local log yet.",
|
||||
query_hashes=query_hashes,
|
||||
filename=image_file.filename,
|
||||
filename=evidence_file.filename,
|
||||
is_image=is_image,
|
||||
matches=[],
|
||||
)
|
||||
|
||||
@ -378,7 +501,8 @@ def verify():
|
||||
else "No matching attestations found."
|
||||
),
|
||||
query_hashes=query_hashes,
|
||||
filename=image_file.filename,
|
||||
filename=evidence_file.filename,
|
||||
is_image=is_image,
|
||||
matches=matches,
|
||||
)
|
||||
|
||||
@ -393,29 +517,29 @@ def verify():
|
||||
def verify_receipt():
|
||||
"""Return a downloadable JSON verification receipt for court or legal use.
|
||||
|
||||
Accepts the same image upload as /verify. Returns a JSON file attachment
|
||||
containing image hashes, all matching attestation records with full metadata,
|
||||
Accepts the same file upload as /verify. Returns a JSON file attachment
|
||||
containing file hashes, all matching attestation records with full metadata,
|
||||
the verification timestamp, and the verifier hostname.
|
||||
|
||||
Intentionally unauthenticated — same access policy as /verify.
|
||||
"""
|
||||
image_file = request.files.get("image")
|
||||
if not image_file or not image_file.filename:
|
||||
evidence_file = request.files.get("image")
|
||||
if not evidence_file or not evidence_file.filename:
|
||||
return Response(
|
||||
json.dumps({"error": "No image provided"}),
|
||||
json.dumps({"error": "No file provided"}),
|
||||
status=400,
|
||||
mimetype="application/json",
|
||||
)
|
||||
|
||||
if not _allowed_image(image_file.filename):
|
||||
if not _allowed_file(evidence_file.filename):
|
||||
return Response(
|
||||
json.dumps({"error": "Unsupported image format"}),
|
||||
json.dumps({"error": "Unsupported file type"}),
|
||||
status=400,
|
||||
mimetype="application/json",
|
||||
)
|
||||
|
||||
try:
|
||||
result = _verify_image(image_file.read())
|
||||
result = _verify_file(evidence_file.read())
|
||||
except Exception as e:
|
||||
return Response(
|
||||
json.dumps({"error": f"Verification failed: {e}"}),
|
||||
@ -460,17 +584,46 @@ def verify_receipt():
|
||||
}
|
||||
if safe_meta:
|
||||
rec_entry["metadata"] = safe_meta
|
||||
|
||||
# Chain position proof — look up this attestation in the hash chain
|
||||
try:
|
||||
from fieldwitness.config import FieldWitnessConfig
|
||||
from fieldwitness.federation.chain import ChainStore
|
||||
from fieldwitness.federation.serialization import compute_record_hash
|
||||
from fieldwitness.paths import CHAIN_DIR
|
||||
|
||||
chain_config = FieldWitnessConfig.load()
|
||||
if chain_config.chain_enabled:
|
||||
chain_store = ChainStore(CHAIN_DIR)
|
||||
# Search chain for a record whose content_hash matches this attestation
|
||||
content_hash_hex = getattr(record, "image_hashes", None)
|
||||
if content_hash_hex and hasattr(content_hash_hex, "sha256"):
|
||||
target_sha = content_hash_hex.sha256
|
||||
for chain_rec in chain_store:
|
||||
if chain_rec.content_hash.hex() == target_sha or chain_rec.metadata.get("attestor") == record.attestor_fingerprint:
|
||||
rec_entry["chain_proof"] = {
|
||||
"chain_id": chain_store.state().chain_id.hex() if chain_store.state() else None,
|
||||
"chain_index": chain_rec.chain_index,
|
||||
"prev_hash": chain_rec.prev_hash.hex(),
|
||||
"record_hash": compute_record_hash(chain_rec).hex(),
|
||||
"content_type": chain_rec.content_type,
|
||||
"claimed_ts": chain_rec.claimed_ts,
|
||||
}
|
||||
break
|
||||
except Exception:
|
||||
pass # Chain proof is optional — don't fail the receipt
|
||||
|
||||
matching_records.append(rec_entry)
|
||||
|
||||
receipt = {
|
||||
"schema_version": "2",
|
||||
"schema_version": "3",
|
||||
"verification_timestamp": verification_ts,
|
||||
"verifier_instance": verifier_instance,
|
||||
"queried_filename": image_file.filename,
|
||||
"image_hash": {
|
||||
"queried_filename": evidence_file.filename,
|
||||
"file_hash": {
|
||||
"sha256": query_hashes.sha256,
|
||||
"phash": query_hashes.phash,
|
||||
"dhash": getattr(query_hashes, "dhash", None),
|
||||
"phash": query_hashes.phash or None,
|
||||
"dhash": getattr(query_hashes, "dhash", None) or None,
|
||||
},
|
||||
"records_searched": result["record_count"],
|
||||
"matches_found": len(matching_records),
|
||||
@ -492,7 +645,9 @@ def verify_receipt():
|
||||
|
||||
receipt_json = json.dumps(receipt, indent=2, ensure_ascii=False)
|
||||
safe_filename = (
|
||||
image_file.filename.rsplit(".", 1)[0] if "." in image_file.filename else image_file.filename
|
||||
evidence_file.filename.rsplit(".", 1)[0]
|
||||
if "." in evidence_file.filename
|
||||
else evidence_file.filename
|
||||
)
|
||||
download_name = f"receipt_{safe_filename}_{datetime.now(UTC).strftime('%Y%m%dT%H%M%SZ')}.json"
|
||||
|
||||
@ -507,20 +662,44 @@ def verify_receipt():
|
||||
@bp.route("/attest/log")
|
||||
@login_required
|
||||
def log():
|
||||
"""List recent attestations."""
|
||||
"""List recent attestations with optional investigation filter."""
|
||||
investigation_filter = request.args.get("investigation", "").strip()
|
||||
try:
|
||||
storage = _get_storage()
|
||||
stats = storage.get_stats()
|
||||
records = []
|
||||
# Show last 50 records, newest first
|
||||
start = max(0, stats.record_count - 50)
|
||||
for i in range(stats.record_count - 1, start - 1, -1):
|
||||
# Scan records, newest first, collect up to 50 matching
|
||||
for i in range(stats.record_count - 1, -1, -1):
|
||||
if len(records) >= 50:
|
||||
break
|
||||
try:
|
||||
record = storage.get_record(i)
|
||||
if investigation_filter:
|
||||
rec_inv = getattr(record, "metadata", {}) or {}
|
||||
if isinstance(rec_inv, dict) and rec_inv.get("investigation") != investigation_filter:
|
||||
continue
|
||||
records.append({"index": i, "record": record})
|
||||
except Exception:
|
||||
continue
|
||||
return render_template("attest/log.html", records=records, total=stats.record_count)
|
||||
|
||||
# Collect known investigation names for filter dropdown
|
||||
investigations = set()
|
||||
for i in range(stats.record_count - 1, max(0, stats.record_count - 500) - 1, -1):
|
||||
try:
|
||||
rec = storage.get_record(i)
|
||||
meta = getattr(rec, "metadata", {}) or {}
|
||||
if isinstance(meta, dict) and meta.get("investigation"):
|
||||
investigations.add(meta["investigation"])
|
||||
except Exception:
|
||||
continue
|
||||
|
||||
return render_template(
|
||||
"attest/log.html",
|
||||
records=records,
|
||||
total=stats.record_count,
|
||||
investigation_filter=investigation_filter,
|
||||
investigations=sorted(investigations),
|
||||
)
|
||||
except Exception as e:
|
||||
flash(f"Could not read attestation log: {e}", "error")
|
||||
return render_template("attest/log.html", records=[], total=0)
|
||||
return render_template("attest/log.html", records=[], total=0, investigation_filter="", investigations=[])
|
||||
|
||||
360
frontends/web/blueprints/dropbox.py
Normal file
360
frontends/web/blueprints/dropbox.py
Normal file
@ -0,0 +1,360 @@
|
||||
"""
|
||||
Source drop box blueprint — anonymous, token-gated file submission.
|
||||
|
||||
Provides a SecureDrop-like intake that lives inside FieldWitness:
|
||||
- Admin creates a time-limited upload token
|
||||
- Source opens the token URL in a browser (no account needed)
|
||||
- Files are uploaded, EXIF-stripped, and auto-attested on receipt
|
||||
- Source receives a one-time receipt code to confirm delivery
|
||||
- Token self-destructs after use or timeout
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
import secrets
|
||||
from datetime import UTC, datetime, timedelta
|
||||
from pathlib import Path
|
||||
|
||||
from auth import admin_required, login_required
|
||||
from flask import Blueprint, Response, flash, redirect, render_template, request, url_for
|
||||
|
||||
from fieldwitness.audit import log_action
|
||||
from fieldwitness.paths import AUTH_DIR, TEMP_DIR
|
||||
|
||||
bp = Blueprint("dropbox", __name__, url_prefix="/dropbox")
|
||||
|
||||
_TOKEN_DIR = TEMP_DIR / "dropbox"
|
||||
_DB_PATH = AUTH_DIR / "dropbox.db"
|
||||
|
||||
|
||||
def _ensure_token_dir():
|
||||
_TOKEN_DIR.mkdir(parents=True, exist_ok=True)
|
||||
_TOKEN_DIR.chmod(0o700)
|
||||
|
||||
|
||||
def _get_db():
|
||||
"""Get SQLite connection for drop box tokens."""
|
||||
import sqlite3
|
||||
|
||||
_DB_PATH.parent.mkdir(parents=True, exist_ok=True)
|
||||
conn = sqlite3.connect(str(_DB_PATH))
|
||||
conn.row_factory = sqlite3.Row
|
||||
conn.execute("""CREATE TABLE IF NOT EXISTS tokens (
|
||||
token TEXT PRIMARY KEY,
|
||||
label TEXT NOT NULL,
|
||||
created_at TEXT NOT NULL,
|
||||
expires_at TEXT NOT NULL,
|
||||
max_files INTEGER NOT NULL,
|
||||
used INTEGER NOT NULL DEFAULT 0
|
||||
)""")
|
||||
conn.execute("""CREATE TABLE IF NOT EXISTS receipts (
|
||||
receipt_code TEXT PRIMARY KEY,
|
||||
token TEXT NOT NULL,
|
||||
filename TEXT,
|
||||
sha256 TEXT,
|
||||
received_at TEXT,
|
||||
FOREIGN KEY (token) REFERENCES tokens(token)
|
||||
)""")
|
||||
conn.commit()
|
||||
return conn
|
||||
|
||||
|
||||
def _get_token(token: str) -> dict | None:
|
||||
"""Load a token from SQLite. Returns dict or None if expired/missing."""
|
||||
conn = _get_db()
|
||||
row = conn.execute("SELECT * FROM tokens WHERE token = ?", (token,)).fetchone()
|
||||
if not row:
|
||||
conn.close()
|
||||
return None
|
||||
if datetime.fromisoformat(row["expires_at"]) < datetime.now(UTC):
|
||||
conn.execute("DELETE FROM tokens WHERE token = ?", (token,))
|
||||
conn.commit()
|
||||
conn.close()
|
||||
return None
|
||||
data = dict(row)
|
||||
# Load receipts
|
||||
receipts = conn.execute(
|
||||
"SELECT receipt_code FROM receipts WHERE token = ?", (token,)
|
||||
).fetchall()
|
||||
data["receipts"] = [r["receipt_code"] for r in receipts]
|
||||
conn.close()
|
||||
return data
|
||||
|
||||
|
||||
def _get_all_tokens() -> dict[str, dict]:
|
||||
"""Load all non-expired tokens."""
|
||||
conn = _get_db()
|
||||
now = datetime.now(UTC).isoformat()
|
||||
# Clean expired
|
||||
conn.execute("DELETE FROM tokens WHERE expires_at < ?", (now,))
|
||||
conn.commit()
|
||||
rows = conn.execute("SELECT * FROM tokens").fetchall()
|
||||
result = {}
|
||||
for row in rows:
|
||||
data = dict(row)
|
||||
receipts = conn.execute(
|
||||
"SELECT receipt_code FROM receipts WHERE token = ?", (row["token"],)
|
||||
).fetchall()
|
||||
data["receipts"] = [r["receipt_code"] for r in receipts]
|
||||
result[row["token"]] = data
|
||||
conn.close()
|
||||
return result
|
||||
|
||||
|
||||
@bp.route("/admin", methods=["GET", "POST"])
|
||||
@admin_required
|
||||
def admin():
|
||||
"""Admin panel for creating and managing drop box tokens."""
|
||||
if request.method == "POST":
|
||||
action = request.form.get("action")
|
||||
if action == "create":
|
||||
label = request.form.get("label", "").strip() or "Unnamed source"
|
||||
hours = int(request.form.get("hours", 24))
|
||||
max_files = int(request.form.get("max_files", 10))
|
||||
|
||||
token = secrets.token_urlsafe(32)
|
||||
conn = _get_db()
|
||||
conn.execute(
|
||||
"INSERT INTO tokens (token, label, created_at, expires_at, max_files, used) VALUES (?, ?, ?, ?, ?, 0)",
|
||||
(token, label, datetime.now(UTC).isoformat(), (datetime.now(UTC) + timedelta(hours=hours)).isoformat(), max_files),
|
||||
)
|
||||
conn.commit()
|
||||
conn.close()
|
||||
|
||||
log_action(
|
||||
actor=request.environ.get("REMOTE_USER", "admin"),
|
||||
action="dropbox.token_created",
|
||||
target=token[:8],
|
||||
outcome="success",
|
||||
source="web",
|
||||
)
|
||||
|
||||
upload_url = url_for("dropbox.upload", token=token, _external=True)
|
||||
flash(f"Drop box created. Share this URL with your source: {upload_url}", "success")
|
||||
|
||||
elif action == "revoke":
|
||||
tok = request.form.get("token", "")
|
||||
conn = _get_db()
|
||||
conn.execute("DELETE FROM receipts WHERE token = ?", (tok,))
|
||||
conn.execute("DELETE FROM tokens WHERE token = ?", (tok,))
|
||||
conn.commit()
|
||||
conn.close()
|
||||
flash("Token revoked.", "success")
|
||||
|
||||
return render_template("dropbox/admin.html", tokens=_get_all_tokens())
|
||||
|
||||
|
||||
def _validate_token(token: str) -> dict | None:
|
||||
"""Check if a token is valid. Returns token data or None."""
|
||||
data = _get_token(token)
|
||||
if data is None:
|
||||
return None
|
||||
if data["used"] >= data["max_files"]:
|
||||
return None
|
||||
return data
|
||||
|
||||
|
||||
@bp.route("/upload/<token>", methods=["GET", "POST"])
|
||||
def upload(token):
|
||||
"""Source-facing upload page. No authentication required."""
|
||||
token_data = _validate_token(token)
|
||||
if token_data is None:
|
||||
return Response(
|
||||
"This upload link has expired or is invalid.",
|
||||
status=404,
|
||||
content_type="text/plain",
|
||||
)
|
||||
|
||||
if request.method == "POST":
|
||||
files = request.files.getlist("files")
|
||||
if not files:
|
||||
return Response("No files provided.", status=400, content_type="text/plain")
|
||||
|
||||
_ensure_token_dir()
|
||||
receipts = []
|
||||
|
||||
for f in files:
|
||||
if token_data["used"] >= token_data["max_files"]:
|
||||
break
|
||||
|
||||
raw_data = f.read()
|
||||
if not raw_data:
|
||||
continue
|
||||
|
||||
# Extract-then-strip pipeline:
|
||||
# 1. Extract EXIF into attestation metadata (evidentiary fields)
|
||||
# 2. Attest the ORIGINAL bytes (hash matches what source submitted)
|
||||
# 3. Strip metadata from the stored copy (protect source device info)
|
||||
from fieldwitness.metadata import extract_strip_pipeline
|
||||
|
||||
extraction, stripped_data = extract_strip_pipeline(raw_data)
|
||||
|
||||
# SHA-256 of what the source actually submitted
|
||||
sha256 = extraction.original_sha256
|
||||
|
||||
# Save the stripped copy for display/storage (no device fingerprint on disk)
|
||||
dest = _TOKEN_DIR / f"{sha256[:16]}_{f.filename}"
|
||||
dest.write_bytes(stripped_data)
|
||||
|
||||
# Auto-attest the ORIGINAL bytes so the attestation hash matches
|
||||
# what the source submitted. Evidentiary EXIF (GPS, timestamp)
|
||||
# is preserved in the attestation metadata; dangerous fields
|
||||
# (device serial) are excluded.
|
||||
try:
|
||||
from fieldwitness.attest.attestation import create_attestation
|
||||
|
||||
from blueprints.attest import _get_private_key, _get_storage
|
||||
|
||||
attest_metadata = {
|
||||
"source": "dropbox",
|
||||
"label": token_data["label"],
|
||||
"stripped_sha256": extraction.stripped_sha256,
|
||||
}
|
||||
# Include evidentiary EXIF in attestation (GPS, timestamp)
|
||||
for key, value in extraction.evidentiary.items():
|
||||
if hasattr(value, "isoformat"):
|
||||
attest_metadata[key] = value.isoformat()
|
||||
elif hasattr(value, "__dataclass_fields__"):
|
||||
from dataclasses import asdict
|
||||
attest_metadata[key] = asdict(value)
|
||||
elif isinstance(value, dict):
|
||||
attest_metadata[key] = value
|
||||
else:
|
||||
attest_metadata[key] = str(value)
|
||||
|
||||
private_key = _get_private_key()
|
||||
if private_key:
|
||||
attestation = create_attestation(
|
||||
raw_data, private_key, metadata=attest_metadata
|
||||
)
|
||||
storage = _get_storage()
|
||||
storage.append_record(attestation.record)
|
||||
except Exception:
|
||||
pass # Attestation is best-effort; don't fail the upload
|
||||
|
||||
# Receipt code derived from file hash via HMAC with a server-side
|
||||
# secret. The source cannot pre-compute this (the token alone is
|
||||
# insufficient), making valid receipts unforgeable.
|
||||
import hmac
|
||||
|
||||
from fieldwitness.paths import SECRET_KEY_FILE
|
||||
|
||||
server_secret = SECRET_KEY_FILE.read_bytes() if SECRET_KEY_FILE.exists() else token.encode()
|
||||
receipt_code = hmac.new(
|
||||
server_secret, sha256.encode(), hashlib.sha256
|
||||
).hexdigest()[:16]
|
||||
|
||||
receipts.append({
|
||||
"filename": f.filename,
|
||||
"sha256": sha256,
|
||||
"receipt_code": receipt_code,
|
||||
"received_at": datetime.now(UTC).isoformat(),
|
||||
})
|
||||
|
||||
# Persist receipt and increment used count in SQLite
|
||||
conn = _get_db()
|
||||
conn.execute(
|
||||
"INSERT OR IGNORE INTO receipts (receipt_code, token, filename, sha256, received_at) VALUES (?, ?, ?, ?, ?)",
|
||||
(receipt_code, token, f.filename, sha256, datetime.now(UTC).isoformat()),
|
||||
)
|
||||
conn.execute("UPDATE tokens SET used = used + 1 WHERE token = ?", (token,))
|
||||
conn.commit()
|
||||
conn.close()
|
||||
token_data["used"] += 1
|
||||
|
||||
remaining = token_data["max_files"] - token_data["used"]
|
||||
|
||||
# Return receipt codes as plain text (minimal fingerprint)
|
||||
receipt_text = "FILES RECEIVED\n" + "=" * 40 + "\n\n"
|
||||
for r in receipts:
|
||||
receipt_text += f"File: {r['filename']}\n"
|
||||
receipt_text += f"Receipt: {r['receipt_code']}\n"
|
||||
receipt_text += f"SHA-256: {r['sha256']}\n\n"
|
||||
receipt_text += f"Remaining uploads on this link: {remaining}\n"
|
||||
receipt_text += "\nSave your receipt codes. They confirm your submission was received.\n"
|
||||
|
||||
return Response(receipt_text, content_type="text/plain")
|
||||
|
||||
# GET — show upload form with client-side SHA-256 hashing
|
||||
# Minimal page, no FieldWitness branding (source safety)
|
||||
remaining = token_data["max_files"] - token_data["used"]
|
||||
return f"""<!DOCTYPE html>
|
||||
<html><head><title>Secure Upload</title>
|
||||
<style>
|
||||
body{{font-family:sans-serif;max-width:600px;margin:40px auto;padding:20px;color:#333}}
|
||||
input[type=file]{{margin:10px 0}}
|
||||
button{{padding:10px 20px;font-size:16px}}
|
||||
#hashes{{background:#f5f5f5;padding:10px;border-radius:4px;font-family:monospace;
|
||||
font-size:12px;margin:10px 0;display:none;white-space:pre-wrap}}
|
||||
.hash-label{{color:#666;font-size:11px}}
|
||||
</style></head>
|
||||
<body>
|
||||
<h2>Secure File Upload</h2>
|
||||
<p>Select files to upload. You may upload up to {remaining} file(s).</p>
|
||||
<p>Your files will be fingerprinted in your browser before upload. Save the
|
||||
fingerprints — they prove exactly what you submitted.</p>
|
||||
<form method="POST" enctype="multipart/form-data" id="uploadForm">
|
||||
<input type="file" name="files" id="fileInput" multiple
|
||||
accept="image/*,.pdf,.doc,.docx,.txt"><br>
|
||||
<div id="hashes"></div>
|
||||
<button type="submit" id="submitBtn" disabled>Computing fingerprints...</button>
|
||||
</form>
|
||||
<p style="color:#666;font-size:12px">This link will expire automatically. Do not bookmark it.</p>
|
||||
<script>
|
||||
// Client-side SHA-256 via SubtleCrypto — runs in browser, no server round-trip
|
||||
async function hashFile(file) {{
|
||||
const buffer = await file.arrayBuffer();
|
||||
const hash = await crypto.subtle.digest('SHA-256', buffer);
|
||||
return Array.from(new Uint8Array(hash)).map(b => b.toString(16).padStart(2,'0')).join('');
|
||||
}}
|
||||
document.getElementById('fileInput').addEventListener('change', async function() {{
|
||||
const files = this.files;
|
||||
const hashDiv = document.getElementById('hashes');
|
||||
const btn = document.getElementById('submitBtn');
|
||||
if (!files.length) {{ hashDiv.style.display='none'; btn.disabled=true; return; }}
|
||||
btn.disabled = true;
|
||||
btn.textContent = 'Computing fingerprints...';
|
||||
hashDiv.style.display = 'block';
|
||||
hashDiv.innerHTML = '';
|
||||
for (const file of files) {{
|
||||
const hash = await hashFile(file);
|
||||
hashDiv.innerHTML += '<span class="hash-label">' + file.name + ':</span>\\n' + hash + '\\n\\n';
|
||||
}}
|
||||
hashDiv.innerHTML += '<span class="hash-label">Save these fingerprints before uploading.</span>';
|
||||
btn.disabled = false;
|
||||
btn.textContent = 'Upload';
|
||||
}});
|
||||
</script>
|
||||
</body></html>"""
|
||||
|
||||
|
||||
@bp.route("/verify-receipt", methods=["POST"])
|
||||
def verify_receipt():
|
||||
"""Let a source verify their submission was received by receipt code."""
|
||||
code = request.form.get("code", "").strip()
|
||||
if not code:
|
||||
return Response("No receipt code provided.", status=400, content_type="text/plain")
|
||||
|
||||
conn = _get_db()
|
||||
row = conn.execute(
|
||||
"SELECT filename, sha256, received_at FROM receipts WHERE receipt_code = ?", (code,)
|
||||
).fetchone()
|
||||
conn.close()
|
||||
|
||||
if row:
|
||||
return Response(
|
||||
f"Receipt {code} is VALID.\n"
|
||||
f"File: {row['filename']}\n"
|
||||
f"SHA-256: {row['sha256']}\n"
|
||||
f"Received: {row['received_at']}\n",
|
||||
content_type="text/plain",
|
||||
)
|
||||
|
||||
return Response(
|
||||
f"Receipt {code} was not found. It may have expired.",
|
||||
status=404,
|
||||
content_type="text/plain",
|
||||
)
|
||||
78
frontends/web/blueprints/federation.py
Normal file
78
frontends/web/blueprints/federation.py
Normal file
@ -0,0 +1,78 @@
|
||||
"""
|
||||
Federation blueprint — peer status dashboard and management.
|
||||
"""
|
||||
|
||||
from auth import admin_required, login_required
|
||||
from flask import Blueprint, flash, redirect, render_template, request, url_for
|
||||
|
||||
bp = Blueprint("federation", __name__, url_prefix="/federation")
|
||||
|
||||
|
||||
@bp.route("/")
|
||||
@login_required
|
||||
def status():
|
||||
"""Federation status dashboard."""
|
||||
from fieldwitness.attest.peer_store import PeerStore
|
||||
|
||||
store = PeerStore()
|
||||
peers = store.list_peers()
|
||||
history = store.get_sync_history(limit=20)
|
||||
|
||||
# Get local node info
|
||||
node_info = {"root": None, "size": 0}
|
||||
try:
|
||||
from fieldwitness.attest.storage import LocalStorage
|
||||
|
||||
import fieldwitness.paths as _paths
|
||||
|
||||
storage = LocalStorage(_paths.ATTESTATIONS_DIR)
|
||||
stats = storage.get_stats()
|
||||
merkle_log = storage.load_merkle_log()
|
||||
node_info = {
|
||||
"root": merkle_log.root_hash[:16] + "..." if merkle_log.root_hash else "empty",
|
||||
"size": merkle_log.size,
|
||||
"record_count": stats.record_count,
|
||||
}
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
return render_template(
|
||||
"federation/status.html",
|
||||
peers=peers,
|
||||
history=history,
|
||||
node_info=node_info,
|
||||
)
|
||||
|
||||
|
||||
@bp.route("/peer/add", methods=["POST"])
|
||||
@admin_required
|
||||
def peer_add():
|
||||
"""Add a federation peer."""
|
||||
from fieldwitness.attest.peer_store import PeerStore
|
||||
|
||||
url = request.form.get("url", "").strip()
|
||||
fingerprint = request.form.get("fingerprint", "").strip()
|
||||
|
||||
if not url or not fingerprint:
|
||||
flash("URL and fingerprint are required.", "error")
|
||||
return redirect(url_for("federation.status"))
|
||||
|
||||
store = PeerStore()
|
||||
store.add_peer(url, fingerprint)
|
||||
flash(f"Peer added: {url}", "success")
|
||||
return redirect(url_for("federation.status"))
|
||||
|
||||
|
||||
@bp.route("/peer/remove", methods=["POST"])
|
||||
@admin_required
|
||||
def peer_remove():
|
||||
"""Remove a federation peer."""
|
||||
from fieldwitness.attest.peer_store import PeerStore
|
||||
|
||||
url = request.form.get("url", "").strip()
|
||||
store = PeerStore()
|
||||
if store.remove_peer(url):
|
||||
flash(f"Peer removed: {url}", "success")
|
||||
else:
|
||||
flash(f"Peer not found: {url}", "error")
|
||||
return redirect(url_for("federation.status"))
|
||||
@ -5,7 +5,7 @@ Fieldkit blueprint — killswitch, dead man's switch, status dashboard.
|
||||
from auth import admin_required, get_username, login_required
|
||||
from flask import Blueprint, flash, redirect, render_template, request, url_for
|
||||
|
||||
from soosef.audit import log_action
|
||||
from fieldwitness.audit import log_action
|
||||
|
||||
bp = Blueprint("fieldkit", __name__, url_prefix="/fieldkit")
|
||||
|
||||
@ -14,7 +14,7 @@ bp = Blueprint("fieldkit", __name__, url_prefix="/fieldkit")
|
||||
@login_required
|
||||
def status():
|
||||
"""Fieldkit status dashboard — all monitors and system health."""
|
||||
from soosef.fieldkit.deadman import DeadmanSwitch
|
||||
from fieldwitness.fieldkit.deadman import DeadmanSwitch
|
||||
|
||||
deadman = DeadmanSwitch()
|
||||
return render_template(
|
||||
@ -39,7 +39,7 @@ def killswitch():
|
||||
flash("Killswitch requires password confirmation.", "danger")
|
||||
return render_template("fieldkit/killswitch.html")
|
||||
|
||||
from soosef.fieldkit.killswitch import PurgeScope, execute_purge
|
||||
from fieldwitness.fieldkit.killswitch import PurgeScope, execute_purge
|
||||
|
||||
actor = username
|
||||
result = execute_purge(PurgeScope.ALL, reason="web_ui")
|
||||
@ -71,7 +71,7 @@ def killswitch():
|
||||
@login_required
|
||||
def deadman_checkin():
|
||||
"""Record a dead man's switch check-in."""
|
||||
from soosef.fieldkit.deadman import DeadmanSwitch
|
||||
from fieldwitness.fieldkit.deadman import DeadmanSwitch
|
||||
|
||||
deadman = DeadmanSwitch()
|
||||
deadman.checkin()
|
||||
|
||||
@ -5,7 +5,7 @@ Key management blueprint — unified view of all key material.
|
||||
from auth import get_username, login_required
|
||||
from flask import Blueprint, flash, redirect, render_template, url_for
|
||||
|
||||
from soosef.audit import log_action
|
||||
from fieldwitness.audit import log_action
|
||||
|
||||
bp = Blueprint("keys", __name__, url_prefix="/keys")
|
||||
|
||||
@ -14,7 +14,7 @@ bp = Blueprint("keys", __name__, url_prefix="/keys")
|
||||
@login_required
|
||||
def index():
|
||||
"""Key management dashboard."""
|
||||
from soosef.keystore import KeystoreManager
|
||||
from fieldwitness.keystore import KeystoreManager
|
||||
|
||||
ks = KeystoreManager()
|
||||
return render_template("fieldkit/keys.html", keystore=ks.status())
|
||||
@ -24,7 +24,7 @@ def index():
|
||||
@login_required
|
||||
def generate_channel():
|
||||
"""Generate a new channel key."""
|
||||
from soosef.keystore import KeystoreManager
|
||||
from fieldwitness.keystore import KeystoreManager
|
||||
|
||||
ks = KeystoreManager()
|
||||
try:
|
||||
@ -54,7 +54,7 @@ def generate_channel():
|
||||
@login_required
|
||||
def generate_identity():
|
||||
"""Generate a new Ed25519 identity."""
|
||||
from soosef.keystore import KeystoreManager
|
||||
from fieldwitness.keystore import KeystoreManager
|
||||
|
||||
ks = KeystoreManager()
|
||||
try:
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
"""
|
||||
Steganography routes are registered directly in app.py via _register_stegasoo_routes()
|
||||
rather than as a blueprint, because the stegasoo route logic (3,600+ lines) uses
|
||||
Steganography routes are registered directly in app.py via _register_stego_routes()
|
||||
rather than as a blueprint, because the stego route logic (3,600+ lines) uses
|
||||
module-level state (ThreadPoolExecutor, jobs dict, subprocess_stego instance)
|
||||
that doesn't translate cleanly to a blueprint.
|
||||
|
||||
The stego templates are in templates/stego/ and extend the soosef base.html.
|
||||
The stego templates are in templates/stego/ and extend the fieldwitness base.html.
|
||||
"""
|
||||
|
||||
@ -83,7 +83,7 @@ def generate_self_signed_cert(
|
||||
# Create certificate
|
||||
subject = issuer = x509.Name(
|
||||
[
|
||||
x509.NameAttribute(NameOID.ORGANIZATION_NAME, "Stegasoo"),
|
||||
x509.NameAttribute(NameOID.ORGANIZATION_NAME, "FieldWitness"),
|
||||
x509.NameAttribute(NameOID.COMMON_NAME, hostname),
|
||||
]
|
||||
)
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
/**
|
||||
* Stegasoo Authentication Pages JavaScript
|
||||
* FieldWitness Authentication Pages JavaScript
|
||||
* Handles login, setup, account, and admin user management pages
|
||||
*/
|
||||
|
||||
const StegasooAuth = {
|
||||
const StegoAuth = {
|
||||
|
||||
// ========================================================================
|
||||
// PASSWORD VISIBILITY TOGGLE
|
||||
@ -128,15 +128,15 @@ const StegasooAuth = {
|
||||
|
||||
// Make togglePassword available globally for onclick handlers
|
||||
function togglePassword(inputId, btn) {
|
||||
StegasooAuth.togglePassword(inputId, btn);
|
||||
StegoAuth.togglePassword(inputId, btn);
|
||||
}
|
||||
|
||||
// Make copyField available globally for onclick handlers
|
||||
function copyField(fieldId) {
|
||||
StegasooAuth.copyField(fieldId);
|
||||
StegoAuth.copyField(fieldId);
|
||||
}
|
||||
|
||||
// Make regeneratePassword available globally for onclick handlers
|
||||
function regeneratePassword() {
|
||||
StegasooAuth.regeneratePassword();
|
||||
StegoAuth.regeneratePassword();
|
||||
}
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
/**
|
||||
* Stegasoo Frontend JavaScript
|
||||
* FieldWitness Frontend JavaScript
|
||||
* Shared functionality across encode, decode, and generate pages
|
||||
*/
|
||||
|
||||
const Stegasoo = {
|
||||
const Stego = {
|
||||
|
||||
// ========================================================================
|
||||
// PASSWORD/PIN VISIBILITY TOGGLES
|
||||
@ -97,10 +97,10 @@ const Stegasoo = {
|
||||
if (this.files && this.files[0]) {
|
||||
const file = this.files[0];
|
||||
if (file.type.startsWith('image/') && preview) {
|
||||
Stegasoo.showImagePreview(file, preview, label, zone);
|
||||
Stego.showImagePreview(file, preview, label, zone);
|
||||
} else if (file.type.startsWith('audio/') || !file.type.startsWith('image/')) {
|
||||
// Audio or non-image files: show file info instead of image preview
|
||||
Stegasoo.showAudioFileInfo(file, zone);
|
||||
Stego.showAudioFileInfo(file, zone);
|
||||
if (label) {
|
||||
label.classList.add('d-none');
|
||||
}
|
||||
@ -155,9 +155,9 @@ const Stegasoo = {
|
||||
|
||||
// Trigger appropriate animation
|
||||
if (isScanContainer) {
|
||||
Stegasoo.triggerScanAnimation(zone, file);
|
||||
Stego.triggerScanAnimation(zone, file);
|
||||
} else if (isPixelContainer) {
|
||||
Stegasoo.triggerPixelReveal(zone, file);
|
||||
Stego.triggerPixelReveal(zone, file);
|
||||
}
|
||||
};
|
||||
reader.readAsDataURL(file);
|
||||
@ -264,7 +264,7 @@ const Stegasoo = {
|
||||
|
||||
if (hashEl) {
|
||||
// Generate a deterministic fake hash preview from filename + size
|
||||
const fakeHash = Stegasoo.generateFakeHash(file.name + file.size);
|
||||
const fakeHash = Stego.generateFakeHash(file.name + file.size);
|
||||
hashEl.textContent = `SHA256: ${fakeHash.substring(0, 8)}····${fakeHash.substring(56)}`;
|
||||
}
|
||||
}
|
||||
@ -328,7 +328,7 @@ const Stegasoo = {
|
||||
tracesContainer.style.left = imgLeft + 'px';
|
||||
|
||||
// Generate Tron-style circuit traces covering the image
|
||||
Stegasoo.generateEmbedTraces(tracesContainer, imgWidth, imgHeight);
|
||||
Stego.generateEmbedTraces(tracesContainer, imgWidth, imgHeight);
|
||||
};
|
||||
|
||||
// Wait for image to be ready
|
||||
@ -349,7 +349,7 @@ const Stegasoo = {
|
||||
if (grid) grid.remove();
|
||||
|
||||
// Populate data panel
|
||||
Stegasoo.populatePixelDataPanel(container, file, preview);
|
||||
Stego.populatePixelDataPanel(container, file, preview);
|
||||
}, duration);
|
||||
},
|
||||
|
||||
@ -453,7 +453,7 @@ const Stegasoo = {
|
||||
|
||||
input.addEventListener('change', function() {
|
||||
if (this.files && this.files[0]) {
|
||||
Stegasoo.showImagePreview(this.files[0], preview, label, container);
|
||||
Stego.showImagePreview(this.files[0], preview, label, container);
|
||||
}
|
||||
});
|
||||
});
|
||||
@ -1602,7 +1602,7 @@ const Stegasoo = {
|
||||
// Webcam QR scanning for RSA key (v4.1.5)
|
||||
document.getElementById('rsaQrWebcam')?.addEventListener('click', () => {
|
||||
this.showQrScanner((text) => {
|
||||
// Check for raw PEM or compressed format (STEGASOO-Z: prefix)
|
||||
// Check for raw PEM or compressed format (legacy STEGASOO-Z: prefix)
|
||||
const isRawPem = text.includes('-----BEGIN') && text.includes('KEY-----');
|
||||
const isCompressed = text.startsWith('STEGASOO-Z:');
|
||||
if (isRawPem || isCompressed) {
|
||||
@ -1672,7 +1672,7 @@ const Stegasoo = {
|
||||
// Webcam QR scanning for RSA key (v4.1.5)
|
||||
document.getElementById('rsaQrWebcam')?.addEventListener('click', () => {
|
||||
this.showQrScanner((text) => {
|
||||
// Check for raw PEM or compressed format (STEGASOO-Z: prefix)
|
||||
// Check for raw PEM or compressed format (legacy STEGASOO-Z: prefix)
|
||||
const isRawPem = text.includes('-----BEGIN') && text.includes('KEY-----');
|
||||
const isCompressed = text.startsWith('STEGASOO-Z:');
|
||||
if (isRawPem || isCompressed) {
|
||||
@ -1721,10 +1721,10 @@ const Stegasoo = {
|
||||
document.addEventListener('DOMContentLoaded', () => {
|
||||
// Detect page and initialize
|
||||
if (document.getElementById('encodeForm')) {
|
||||
Stegasoo.initEncodePage();
|
||||
Stego.initEncodePage();
|
||||
} else if (document.getElementById('decodeForm')) {
|
||||
Stegasoo.initDecodePage();
|
||||
Stego.initDecodePage();
|
||||
} else if (document.querySelector('[data-page="generate"]')) {
|
||||
Stegasoo.initGeneratePage();
|
||||
Stego.initGeneratePage();
|
||||
}
|
||||
});
|
||||
@ -1,9 +1,9 @@
|
||||
/**
|
||||
* Stegasoo Generate Page JavaScript
|
||||
* FieldWitness Stego Generate Page JavaScript
|
||||
* Handles credential generation form and display
|
||||
*/
|
||||
|
||||
const StegasooGenerate = {
|
||||
const StegoGenerate = {
|
||||
|
||||
// ========================================================================
|
||||
// FORM CONTROLS
|
||||
@ -260,20 +260,20 @@ const StegasooGenerate = {
|
||||
|
||||
// Global function wrappers for onclick handlers
|
||||
function togglePinVisibility() {
|
||||
StegasooGenerate.togglePinVisibility();
|
||||
StegoGenerate.togglePinVisibility();
|
||||
}
|
||||
|
||||
function togglePassphraseVisibility() {
|
||||
StegasooGenerate.togglePassphraseVisibility();
|
||||
StegoGenerate.togglePassphraseVisibility();
|
||||
}
|
||||
|
||||
function printQrCode() {
|
||||
StegasooGenerate.printQrCode();
|
||||
StegoGenerate.printQrCode();
|
||||
}
|
||||
|
||||
// Auto-init form controls
|
||||
document.addEventListener('DOMContentLoaded', () => {
|
||||
if (document.querySelector('[data-page="generate"]')) {
|
||||
StegasooGenerate.initForm();
|
||||
StegoGenerate.initForm();
|
||||
}
|
||||
});
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
/* ============================================================================
|
||||
SooSeF - Main Stylesheet
|
||||
Adapted from Stegasoo's style.css — same dark theme, same patterns.
|
||||
FieldWitness - Main Stylesheet
|
||||
Dark theme stylesheet for the FieldWitness web UI.
|
||||
============================================================================ */
|
||||
|
||||
:root {
|
||||
@ -26,7 +26,7 @@
|
||||
letter-spacing: 0.05em;
|
||||
}
|
||||
|
||||
/* Nav icon + label pattern from stegasoo */
|
||||
/* Nav icon + label pattern */
|
||||
.nav-icons .nav-link {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
"""
|
||||
Stegasoo encode/decode/tools routes.
|
||||
Stego encode/decode/tools routes.
|
||||
|
||||
Ported from stegasoo's frontends/web/app.py. These routes handle:
|
||||
Ported from fieldwitness.stego's frontends/web/app.py. These routes handle:
|
||||
- Image encode with async progress tracking
|
||||
- Audio encode (v4.3.0)
|
||||
- Image/audio decode
|
||||
@ -33,7 +33,7 @@ from PIL import Image
|
||||
|
||||
|
||||
def register_stego_routes(app, **deps):
|
||||
"""Register all stegasoo encode/decode routes on the Flask app."""
|
||||
"""Register all stego encode/decode routes on the Flask app."""
|
||||
|
||||
# Unpack dependencies passed from app.py
|
||||
login_required = deps["login_required"]
|
||||
@ -41,7 +41,7 @@ def register_stego_routes(app, **deps):
|
||||
temp_storage = deps["temp_storage"]
|
||||
_has_qrcode_read = deps.get("has_qrcode_read", False)
|
||||
|
||||
from soosef.stegasoo import (
|
||||
from fieldwitness.stego import (
|
||||
HAS_AUDIO_SUPPORT,
|
||||
CapacityError,
|
||||
DecryptionError,
|
||||
@ -49,7 +49,7 @@ def register_stego_routes(app, **deps):
|
||||
InvalidHeaderError,
|
||||
InvalidMagicBytesError,
|
||||
ReedSolomonError,
|
||||
StegasooError,
|
||||
StegoError,
|
||||
generate_filename,
|
||||
has_dct_support,
|
||||
validate_file_payload,
|
||||
@ -60,13 +60,13 @@ def register_stego_routes(app, **deps):
|
||||
validate_rsa_key,
|
||||
validate_security_factors,
|
||||
)
|
||||
from soosef.stegasoo.channel import resolve_channel_key
|
||||
from soosef.stegasoo.constants import (
|
||||
from fieldwitness.stego.channel import resolve_channel_key
|
||||
from fieldwitness.stego.constants import (
|
||||
TEMP_FILE_EXPIRY,
|
||||
THUMBNAIL_QUALITY,
|
||||
THUMBNAIL_SIZE,
|
||||
)
|
||||
from soosef.stegasoo.qr_utils import (
|
||||
from fieldwitness.stego.qr_utils import (
|
||||
decompress_data,
|
||||
extract_key_from_qr,
|
||||
is_compressed,
|
||||
@ -152,7 +152,7 @@ def register_stego_routes(app, **deps):
|
||||
else:
|
||||
return f"{n/(1024*1024):.1f} MB"
|
||||
|
||||
# ── Routes below are extracted from stegasoo app.py ──
|
||||
# ── Routes below are extracted from fieldwitness.stego app.py ──
|
||||
|
||||
def _run_encode_job(job_id: str, encode_params: dict) -> None:
|
||||
"""Background thread function for async encode."""
|
||||
@ -686,7 +686,7 @@ def register_stego_routes(app, **deps):
|
||||
return _error_response(result.error_message)
|
||||
|
||||
# Pre-check payload capacity BEFORE encode (fail fast)
|
||||
from soosef.stegasoo.steganography import will_fit_by_mode
|
||||
from fieldwitness.stego.steganography import will_fit_by_mode
|
||||
|
||||
payload_size = (
|
||||
len(payload.data) if hasattr(payload, "data") else len(payload.encode("utf-8"))
|
||||
@ -770,7 +770,7 @@ def register_stego_routes(app, **deps):
|
||||
error_msg = encode_result.error or "Encoding failed"
|
||||
if "capacity" in error_msg.lower():
|
||||
raise CapacityError(error_msg)
|
||||
raise StegasooError(error_msg)
|
||||
raise StegoError(error_msg)
|
||||
|
||||
# Determine actual output format for filename and storage
|
||||
if embed_mode == "dct" and dct_output_format == "jpeg":
|
||||
@ -813,7 +813,7 @@ def register_stego_routes(app, **deps):
|
||||
|
||||
except CapacityError as e:
|
||||
return _error_response(str(e))
|
||||
except StegasooError as e:
|
||||
except StegoError as e:
|
||||
return _error_response(str(e))
|
||||
except Exception as e:
|
||||
return _error_response(f"Error: {e}")
|
||||
@ -1443,7 +1443,7 @@ def register_stego_routes(app, **deps):
|
||||
or decode_result.error_type == "DecryptionError"
|
||||
):
|
||||
raise DecryptionError(error_msg)
|
||||
raise StegasooError(error_msg)
|
||||
raise StegoError(error_msg)
|
||||
|
||||
if decode_result.is_file:
|
||||
# File content - store temporarily for download
|
||||
@ -1479,7 +1479,7 @@ def register_stego_routes(app, **deps):
|
||||
|
||||
except InvalidMagicBytesError:
|
||||
flash(
|
||||
"This doesn't appear to be a Stegasoo image. Try a different mode (LSB/DCT).",
|
||||
"This doesn't appear to be a Stego image. Try a different mode (LSB/DCT).",
|
||||
"warning",
|
||||
)
|
||||
return render_template("stego/decode.html", has_qrcode_read=_has_qrcode_read)
|
||||
@ -1501,7 +1501,7 @@ def register_stego_routes(app, **deps):
|
||||
"warning",
|
||||
)
|
||||
return render_template("stego/decode.html", has_qrcode_read=_has_qrcode_read)
|
||||
except StegasooError as e:
|
||||
except StegoError as e:
|
||||
flash(str(e), "error")
|
||||
return render_template("stego/decode.html", has_qrcode_read=_has_qrcode_read)
|
||||
except Exception as e:
|
||||
@ -1613,8 +1613,8 @@ def register_stego_routes(app, **deps):
|
||||
@app.route("/about")
|
||||
def about():
|
||||
from auth import get_current_user
|
||||
from soosef.stegasoo import has_argon2
|
||||
from soosef.stegasoo.channel import get_channel_status
|
||||
from fieldwitness.stego import has_argon2
|
||||
from fieldwitness.stego.channel import get_channel_status
|
||||
|
||||
channel_status = get_channel_status()
|
||||
current_user = get_current_user()
|
||||
@ -1644,7 +1644,7 @@ def register_stego_routes(app, **deps):
|
||||
@login_required
|
||||
def api_tools_capacity():
|
||||
"""Calculate image capacity for steganography."""
|
||||
from soosef.stegasoo.dct_steganography import estimate_capacity_comparison
|
||||
from fieldwitness.stego.dct_steganography import estimate_capacity_comparison
|
||||
|
||||
carrier = request.files.get("image")
|
||||
if not carrier:
|
||||
@ -1666,7 +1666,7 @@ def register_stego_routes(app, **deps):
|
||||
"""Strip EXIF/metadata from image."""
|
||||
import io
|
||||
|
||||
from soosef.stegasoo.utils import strip_image_metadata
|
||||
from fieldwitness.stego.utils import strip_image_metadata
|
||||
|
||||
image_file = request.files.get("image")
|
||||
if not image_file:
|
||||
@ -1689,7 +1689,7 @@ def register_stego_routes(app, **deps):
|
||||
@login_required
|
||||
def api_tools_exif():
|
||||
"""Read EXIF metadata from image."""
|
||||
from soosef.stegasoo.utils import read_image_exif
|
||||
from fieldwitness.stego.utils import read_image_exif
|
||||
|
||||
image_file = request.files.get("image")
|
||||
if not image_file:
|
||||
@ -1718,7 +1718,7 @@ def register_stego_routes(app, **deps):
|
||||
@login_required
|
||||
def api_tools_exif_update():
|
||||
"""Update EXIF fields in image."""
|
||||
from soosef.stegasoo.utils import write_image_exif
|
||||
from fieldwitness.stego.utils import write_image_exif
|
||||
|
||||
image_file = request.files.get("image")
|
||||
if not image_file:
|
||||
@ -1757,7 +1757,7 @@ def register_stego_routes(app, **deps):
|
||||
@login_required
|
||||
def api_tools_exif_clear():
|
||||
"""Remove all EXIF metadata from image."""
|
||||
from soosef.stegasoo.utils import strip_image_metadata
|
||||
from fieldwitness.stego.utils import strip_image_metadata
|
||||
|
||||
image_file = request.files.get("image")
|
||||
if not image_file:
|
||||
@ -2062,7 +2062,7 @@ def register_stego_routes(app, **deps):
|
||||
|
||||
@app.route("/test-capacity", methods=["POST"])
|
||||
def test_capacity():
|
||||
"""Minimal capacity test - no stegasoo code, just PIL."""
|
||||
"""Minimal capacity test - no stego code, just PIL."""
|
||||
carrier = request.files.get("carrier")
|
||||
if not carrier:
|
||||
return jsonify({"error": "No carrier image provided"}), 400
|
||||
@ -2095,7 +2095,7 @@ def register_stego_routes(app, **deps):
|
||||
|
||||
@app.route("/test-capacity-nopil", methods=["POST"])
|
||||
def test_capacity_nopil():
|
||||
"""Ultra-minimal test - no PIL, no stegasoo."""
|
||||
"""Ultra-minimal test - no PIL, no stego."""
|
||||
carrier = request.files.get("carrier")
|
||||
if not carrier:
|
||||
return jsonify({"error": "No carrier image provided"}), 400
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Stegasoo Subprocess Worker (v4.0.0)
|
||||
Stego Subprocess Worker (v4.0.0)
|
||||
|
||||
This script runs in a subprocess and handles encode/decode operations.
|
||||
If it crashes due to jpeglib/scipy issues, the parent Flask process survives.
|
||||
@ -25,12 +25,12 @@ import sys
|
||||
import traceback
|
||||
from pathlib import Path
|
||||
|
||||
# Ensure stegasoo is importable
|
||||
# Ensure stego is importable
|
||||
sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src"))
|
||||
sys.path.insert(0, str(Path(__file__).parent))
|
||||
|
||||
# Configure logging for worker subprocess
|
||||
_log_level = os.environ.get("STEGASOO_LOG_LEVEL", "").strip().upper()
|
||||
_log_level = os.environ.get("FIELDWITNESS_LOG_LEVEL", "").strip().upper()
|
||||
if _log_level and hasattr(logging, _log_level):
|
||||
logging.basicConfig(
|
||||
level=getattr(logging, _log_level),
|
||||
@ -38,19 +38,19 @@ if _log_level and hasattr(logging, _log_level):
|
||||
datefmt="%H:%M:%S",
|
||||
stream=sys.stderr,
|
||||
)
|
||||
elif os.environ.get("STEGASOO_DEBUG", "").strip() in ("1", "true", "yes"):
|
||||
elif os.environ.get("FIELDWITNESS_DEBUG", "").strip() in ("1", "true", "yes"):
|
||||
logging.basicConfig(
|
||||
level=logging.DEBUG,
|
||||
format="[%(asctime)s.%(msecs)03d] [%(levelname)s] [%(name)s] %(message)s",
|
||||
datefmt="%H:%M:%S",
|
||||
stream=sys.stderr,
|
||||
)
|
||||
logger = logging.getLogger("stegasoo.worker")
|
||||
logger = logging.getLogger("stego.worker")
|
||||
|
||||
|
||||
def _resolve_channel_key(channel_key_param):
|
||||
"""
|
||||
Resolve channel_key parameter to value for stegasoo.
|
||||
Resolve channel_key parameter to value for stego.
|
||||
|
||||
Args:
|
||||
channel_key_param: 'auto', 'none', explicit key, or None
|
||||
@ -73,7 +73,7 @@ def _get_channel_info(resolved_key):
|
||||
Returns:
|
||||
(mode, fingerprint) tuple
|
||||
"""
|
||||
from soosef.stegasoo import get_channel_status, has_channel_key
|
||||
from fieldwitness.stego import get_channel_status, has_channel_key
|
||||
|
||||
if resolved_key == "":
|
||||
return "public", None
|
||||
@ -94,7 +94,7 @@ def _get_channel_info(resolved_key):
|
||||
def encode_operation(params: dict) -> dict:
|
||||
"""Handle encode operation."""
|
||||
logger.debug("encode_operation: mode=%s", params.get("embed_mode", "lsb"))
|
||||
from soosef.stegasoo import FilePayload, encode
|
||||
from fieldwitness.stego import FilePayload, encode
|
||||
|
||||
# Decode base64 inputs
|
||||
carrier_data = base64.b64decode(params["carrier_b64"])
|
||||
@ -173,7 +173,7 @@ def _write_decode_progress(progress_file: str | None, percent: int, phase: str)
|
||||
def decode_operation(params: dict) -> dict:
|
||||
"""Handle decode operation."""
|
||||
logger.debug("decode_operation: mode=%s", params.get("embed_mode", "auto"))
|
||||
from soosef.stegasoo import decode
|
||||
from fieldwitness.stego import decode
|
||||
|
||||
progress_file = params.get("progress_file")
|
||||
|
||||
@ -227,7 +227,7 @@ def decode_operation(params: dict) -> dict:
|
||||
|
||||
def compare_operation(params: dict) -> dict:
|
||||
"""Handle compare_modes operation."""
|
||||
from soosef.stegasoo import compare_modes
|
||||
from fieldwitness.stego import compare_modes
|
||||
|
||||
carrier_data = base64.b64decode(params["carrier_b64"])
|
||||
result = compare_modes(carrier_data)
|
||||
@ -240,7 +240,7 @@ def compare_operation(params: dict) -> dict:
|
||||
|
||||
def capacity_check_operation(params: dict) -> dict:
|
||||
"""Handle will_fit_by_mode operation."""
|
||||
from soosef.stegasoo import will_fit_by_mode
|
||||
from fieldwitness.stego import will_fit_by_mode
|
||||
|
||||
carrier_data = base64.b64decode(params["carrier_b64"])
|
||||
|
||||
@ -259,7 +259,7 @@ def capacity_check_operation(params: dict) -> dict:
|
||||
def encode_audio_operation(params: dict) -> dict:
|
||||
"""Handle audio encode operation (v4.3.0)."""
|
||||
logger.debug("encode_audio_operation: mode=%s", params.get("embed_mode", "audio_lsb"))
|
||||
from soosef.stegasoo import FilePayload, encode_audio
|
||||
from fieldwitness.stego import FilePayload, encode_audio
|
||||
|
||||
carrier_data = base64.b64decode(params["carrier_b64"])
|
||||
reference_data = base64.b64decode(params["reference_b64"])
|
||||
@ -324,7 +324,7 @@ def encode_audio_operation(params: dict) -> dict:
|
||||
def decode_audio_operation(params: dict) -> dict:
|
||||
"""Handle audio decode operation (v4.3.0)."""
|
||||
logger.debug("decode_audio_operation: mode=%s", params.get("embed_mode", "audio_auto"))
|
||||
from soosef.stegasoo import decode_audio
|
||||
from fieldwitness.stego import decode_audio
|
||||
|
||||
progress_file = params.get("progress_file")
|
||||
_write_decode_progress(progress_file, 5, "reading")
|
||||
@ -370,9 +370,9 @@ def decode_audio_operation(params: dict) -> dict:
|
||||
|
||||
def audio_info_operation(params: dict) -> dict:
|
||||
"""Handle audio info operation (v4.3.0)."""
|
||||
from soosef.stegasoo import get_audio_info
|
||||
from soosef.stegasoo.audio_steganography import calculate_audio_lsb_capacity
|
||||
from soosef.stegasoo.spread_steganography import calculate_audio_spread_capacity
|
||||
from fieldwitness.stego import get_audio_info
|
||||
from fieldwitness.stego.audio_steganography import calculate_audio_lsb_capacity
|
||||
from fieldwitness.stego.spread_steganography import calculate_audio_spread_capacity
|
||||
|
||||
audio_data = base64.b64decode(params["audio_b64"])
|
||||
|
||||
@ -397,7 +397,7 @@ def audio_info_operation(params: dict) -> dict:
|
||||
|
||||
def channel_status_operation(params: dict) -> dict:
|
||||
"""Handle channel status check (v4.0.0)."""
|
||||
from soosef.stegasoo import get_channel_status
|
||||
from fieldwitness.stego import get_channel_status
|
||||
|
||||
status = get_channel_status()
|
||||
reveal = params.get("reveal", False)
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
"""
|
||||
Subprocess Steganography Wrapper (v4.0.0)
|
||||
|
||||
Runs stegasoo operations in isolated subprocesses to prevent crashes
|
||||
Runs stego operations in isolated subprocesses to prevent crashes
|
||||
from taking down the Flask server.
|
||||
|
||||
CHANGES in v4.0.0:
|
||||
@ -743,7 +743,7 @@ def generate_job_id() -> str:
|
||||
|
||||
def get_progress_file_path(job_id: str) -> str:
|
||||
"""Get the progress file path for a job ID."""
|
||||
return str(Path(tempfile.gettempdir()) / f"stegasoo_progress_{job_id}.json")
|
||||
return str(Path(tempfile.gettempdir()) / f"stego_progress_{job_id}.json")
|
||||
|
||||
|
||||
def read_progress(job_id: str) -> dict | None:
|
||||
|
||||
@ -12,7 +12,7 @@ Files are stored in a temp directory with:
|
||||
IMPORTANT: This module ONLY manages files in the temp directory.
|
||||
It does NOT touch instance/ (auth database) or any other directories.
|
||||
|
||||
All temp files are written to ~/.soosef/temp/ (soosef.paths.TEMP_DIR) so
|
||||
All temp files are written to ~/.fieldwitness/temp/ (fieldwitness.paths.TEMP_DIR) so
|
||||
that the killswitch's destroy_temp_files step covers them.
|
||||
"""
|
||||
|
||||
@ -24,9 +24,9 @@ import time
|
||||
from pathlib import Path
|
||||
from threading import Lock
|
||||
|
||||
import soosef.paths as paths
|
||||
import fieldwitness.paths as paths
|
||||
|
||||
# Default temp directory — always under ~/.soosef/temp/ so the killswitch
|
||||
# Default temp directory — always under ~/.fieldwitness/temp/ so the killswitch
|
||||
# (which purges paths.TEMP_DIR) can reach every file written here.
|
||||
DEFAULT_TEMP_DIR: Path = paths.TEMP_DIR
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block title %}Account - Stegasoo{% endblock %}
|
||||
{% block title %}Account - Stego{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
@ -269,16 +269,16 @@
|
||||
|
||||
{% block scripts %}
|
||||
<script src="{{ url_for('static', filename='js/auth.js') }}"></script>
|
||||
<script src="{{ url_for('static', filename='js/soosef.js') }}"></script>
|
||||
<script src="{{ url_for('static', filename='js/fieldwitness.js') }}"></script>
|
||||
{% if is_admin %}
|
||||
<script src="{{ url_for('static', filename='js/qrcode.min.js') }}"></script>
|
||||
{% endif %}
|
||||
<script>
|
||||
StegasooAuth.initPasswordConfirmation('accountForm', 'newPasswordInput', 'newPasswordConfirmInput');
|
||||
StegoAuth.initPasswordConfirmation('accountForm', 'newPasswordInput', 'newPasswordConfirmInput');
|
||||
|
||||
// Webcam QR scanning for channel key input (v4.1.5)
|
||||
document.getElementById('scanChannelKeyBtn')?.addEventListener('click', function() {
|
||||
Stegasoo.showQrScanner((text) => {
|
||||
Stego.showQrScanner((text) => {
|
||||
const input = document.getElementById('channelKeyInput');
|
||||
if (input) {
|
||||
// Clean and format the key
|
||||
@ -294,7 +294,7 @@ document.getElementById('scanChannelKeyBtn')?.addEventListener('click', function
|
||||
|
||||
// Format channel key input as user types
|
||||
document.getElementById('channelKeyInput')?.addEventListener('input', function() {
|
||||
Stegasoo.formatChannelKeyInput(this);
|
||||
Stego.formatChannelKeyInput(this);
|
||||
});
|
||||
|
||||
function renameKey(keyId, currentName) {
|
||||
@ -336,7 +336,7 @@ document.getElementById('qrDownload')?.addEventListener('click', function() {
|
||||
const keyName = document.getElementById('qrKeyName').textContent;
|
||||
if (canvas) {
|
||||
const link = document.createElement('a');
|
||||
link.download = 'stegasoo-channel-key-' + keyName.toLowerCase().replace(/\s+/g, '-') + '.png';
|
||||
link.download = 'stego-channel-key-' + keyName.toLowerCase().replace(/\s+/g, '-') + '.png';
|
||||
link.href = canvas.toDataURL('image/png');
|
||||
link.click();
|
||||
}
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block title %}Password Reset - Stegasoo{% endblock %}
|
||||
{% block title %}Password Reset - Stego{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
{% extends "base.html" %}
|
||||
{% block title %}Settings — SooSeF Admin{% endblock %}
|
||||
{% block title %}Settings — FieldWitness Admin{% endblock %}
|
||||
{% block content %}
|
||||
<h2><i class="bi bi-sliders me-2"></i>System Settings</h2>
|
||||
<div class="alert alert-info">
|
||||
<i class="bi bi-info-circle me-2"></i>
|
||||
System settings will be migrated from stegasoo's admin panel.
|
||||
System settings will be migrated from fieldwitness.stego's admin panel.
|
||||
</div>
|
||||
{% endblock %}
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block title %}User Created - Stegasoo{% endblock %}
|
||||
{% block title %}User Created - Stego{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block title %}Add User - Stegasoo{% endblock %}
|
||||
{% block title %}Add User - Stego{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block title %}Manage Users - Stegasoo{% endblock %}
|
||||
{% block title %}Manage Users - Stego{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
|
||||
@ -1,52 +1,56 @@
|
||||
{% extends "base.html" %}
|
||||
{% block title %}Attest Image — SooSeF{% endblock %}
|
||||
{% block title %}Attest File — FieldWitness{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
<div class="col-lg-8">
|
||||
<div class="card bg-dark border-secondary">
|
||||
<div class="card-header">
|
||||
<h5 class="mb-0"><i class="bi bi-patch-check me-2 text-info"></i>Attest Image</h5>
|
||||
<h5 class="mb-0"><i class="bi bi-patch-check me-2 text-info"></i>Attest File</h5>
|
||||
</div>
|
||||
<div class="card-body">
|
||||
<p class="text-muted">
|
||||
Create a cryptographic provenance attestation — sign an image with your Ed25519 identity
|
||||
to prove when and by whom it was captured.
|
||||
Create a cryptographic provenance attestation — sign any file with your Ed25519 identity
|
||||
to prove when and by whom it was captured or created. Supports photos, documents,
|
||||
sensor data, audio, video, and more.
|
||||
</p>
|
||||
|
||||
{% if not has_identity %}
|
||||
<div class="alert alert-warning">
|
||||
<i class="bi bi-exclamation-triangle me-2"></i>
|
||||
<strong>No identity configured.</strong> Generate one from the
|
||||
<a href="/keys" class="alert-link">Keys page</a> or run <code>soosef init</code>.
|
||||
<a href="/keys" class="alert-link">Keys page</a> or run <code>fieldwitness init</code>.
|
||||
</div>
|
||||
{% endif %}
|
||||
|
||||
<form method="POST" enctype="multipart/form-data">
|
||||
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}"/>
|
||||
<div class="mb-4">
|
||||
<label for="image" class="form-label"><i class="bi bi-image me-1"></i>Image to Attest</label>
|
||||
<input type="file" class="form-control" name="image" id="image"
|
||||
accept="image/png,image/jpeg,image/webp,image/tiff,image/bmp" required>
|
||||
<div class="form-text">Supports PNG, JPEG, WebP, TIFF, BMP.</div>
|
||||
<label for="image" class="form-label"><i class="bi bi-file-earmark me-1"></i>Evidence File</label>
|
||||
<input type="file" class="form-control" name="image" id="image" required>
|
||||
<div class="form-text">
|
||||
Accepts images (PNG, JPEG, WebP, TIFF), documents (PDF, DOCX, CSV, TXT),
|
||||
audio (MP3, WAV, FLAC), video (MP4, MOV, MKV), and sensor data files.
|
||||
Perceptual matching (pHash, dHash) is available for image files only.
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="mb-3">
|
||||
<label for="caption" class="form-label"><i class="bi bi-chat-text me-1"></i>Caption (optional)</label>
|
||||
<input type="text" class="form-control" name="caption" id="caption"
|
||||
placeholder="What does this image show?" maxlength="500">
|
||||
placeholder="What does this file document?" maxlength="500">
|
||||
</div>
|
||||
|
||||
<div class="mb-3">
|
||||
<label for="location_name" class="form-label"><i class="bi bi-geo-alt me-1"></i>Location (optional)</label>
|
||||
<input type="text" class="form-control" name="location_name" id="location_name"
|
||||
placeholder="Where was this taken?" maxlength="200">
|
||||
placeholder="Where was this captured?" maxlength="200">
|
||||
</div>
|
||||
|
||||
<div class="form-check form-switch mb-4">
|
||||
<input class="form-check-input" type="checkbox" name="auto_exif" id="autoExif" checked>
|
||||
<label class="form-check-label" for="autoExif">
|
||||
Extract EXIF metadata automatically (GPS, timestamp, device)
|
||||
Extract EXIF metadata automatically (GPS, timestamp, device) — images only
|
||||
</label>
|
||||
</div>
|
||||
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
{% extends "base.html" %}
|
||||
{% block title %}Attestation Log — SooSeF{% endblock %}
|
||||
{% block title %}Attestation Log — FieldWitness{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
@ -39,7 +39,7 @@
|
||||
{% else %}
|
||||
<div class="alert alert-secondary">
|
||||
<i class="bi bi-inbox me-2"></i>
|
||||
No attestations yet. <a href="/attest" class="alert-link">Attest your first image</a>.
|
||||
No attestations yet. <a href="/attest" class="alert-link">Attest your first file</a>.
|
||||
</div>
|
||||
{% endif %}
|
||||
</div>
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
{% extends "base.html" %}
|
||||
{% block title %}Attestation Record — SooSeF{% endblock %}
|
||||
{% block title %}Attestation Record — FieldWitness{% endblock %}
|
||||
{% block content %}
|
||||
<h2><i class="bi bi-file-earmark-check me-2"></i>Attestation Record</h2>
|
||||
<p class="text-muted">Record ID: <code>{{ record_id }}</code></p>
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
{% extends "base.html" %}
|
||||
{% block title %}Attestation Created — SooSeF{% endblock %}
|
||||
{% block title %}Attestation Created — FieldWitness{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
@ -7,9 +7,17 @@
|
||||
<div class="alert alert-success">
|
||||
<i class="bi bi-check-circle me-2"></i>
|
||||
<strong>Attestation created successfully!</strong>
|
||||
Image <code>{{ filename }}</code> has been attested and stored in the local log (index #{{ index }}).
|
||||
File <code>{{ filename }}</code> has been attested and stored in the local log (index #{{ index }}).
|
||||
</div>
|
||||
|
||||
{% if not is_image %}
|
||||
<div class="alert alert-info">
|
||||
<i class="bi bi-info-circle me-2"></i>
|
||||
This file is attested by cryptographic hash. Perceptual matching (pHash, dHash)
|
||||
is available for image files only.
|
||||
</div>
|
||||
{% endif %}
|
||||
|
||||
<div class="card bg-dark border-secondary mb-4">
|
||||
<div class="card-header">
|
||||
<h5 class="mb-0"><i class="bi bi-file-earmark-check me-2"></i>Attestation Record</h5>
|
||||
@ -38,7 +46,7 @@
|
||||
|
||||
<div class="card bg-dark border-secondary mb-4">
|
||||
<div class="card-header">
|
||||
<h6 class="mb-0"><i class="bi bi-hash me-2"></i>Image Hashes</h6>
|
||||
<h6 class="mb-0"><i class="bi bi-hash me-2"></i>File Hashes</h6>
|
||||
</div>
|
||||
<div class="card-body">
|
||||
<div class="mb-2">
|
||||
@ -84,7 +92,7 @@
|
||||
|
||||
<div class="d-grid gap-2">
|
||||
<a href="/attest" class="btn btn-outline-info">
|
||||
<i class="bi bi-plus-circle me-2"></i>Attest Another Image
|
||||
<i class="bi bi-plus-circle me-2"></i>Attest Another File
|
||||
</a>
|
||||
<a href="/attest/log" class="btn btn-outline-secondary">
|
||||
<i class="bi bi-journal-text me-2"></i>View Attestation Log
|
||||
|
||||
@ -1,30 +1,33 @@
|
||||
{% extends "base.html" %}
|
||||
{% block title %}Verify Image — SooSeF{% endblock %}
|
||||
{% block title %}Verify File — FieldWitness{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
<div class="col-lg-8">
|
||||
<div class="card bg-dark border-secondary">
|
||||
<div class="card-header">
|
||||
<h5 class="mb-0"><i class="bi bi-search me-2 text-info"></i>Verify Image</h5>
|
||||
<h5 class="mb-0"><i class="bi bi-search me-2 text-info"></i>Verify File</h5>
|
||||
</div>
|
||||
<div class="card-body">
|
||||
<p class="text-muted">
|
||||
Check an image against the local attestation log. Uses SHA-256 for exact matching
|
||||
and perceptual hashes (pHash, dHash) for robustness against compression and resizing.
|
||||
Check a file against the local attestation log. For image files, uses SHA-256 for
|
||||
exact matching and perceptual hashes (pHash, dHash) for robustness against
|
||||
compression and resizing. For all other file types, SHA-256 exact matching is used.
|
||||
</p>
|
||||
|
||||
<form method="POST" enctype="multipart/form-data">
|
||||
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}"/>
|
||||
<div class="mb-4">
|
||||
<label for="image" class="form-label"><i class="bi bi-image me-1"></i>Image to Verify</label>
|
||||
<input type="file" class="form-control" name="image" id="image"
|
||||
accept="image/png,image/jpeg,image/webp,image/tiff,image/bmp" required>
|
||||
<div class="form-text">Upload the image you want to verify against known attestations.</div>
|
||||
<label for="image" class="form-label"><i class="bi bi-file-earmark-search me-1"></i>Evidence File to Verify</label>
|
||||
<input type="file" class="form-control" name="image" id="image" required>
|
||||
<div class="form-text">
|
||||
Upload the file you want to verify against known attestations.
|
||||
Accepts images, documents, audio, video, and data files.
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<button type="submit" class="btn btn-info btn-lg w-100">
|
||||
<i class="bi bi-search me-2"></i>Verify Image
|
||||
<i class="bi bi-search me-2"></i>Verify File
|
||||
</button>
|
||||
</form>
|
||||
</div>
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
{% extends "base.html" %}
|
||||
{% block title %}Verification Result — SooSeF{% endblock %}
|
||||
{% block title %}Verification Result — FieldWitness{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
@ -16,10 +16,18 @@
|
||||
</div>
|
||||
{% endif %}
|
||||
|
||||
{# Query image hashes #}
|
||||
{% if not is_image %}
|
||||
<div class="alert alert-info">
|
||||
<i class="bi bi-info-circle me-2"></i>
|
||||
This file is attested by cryptographic hash. Perceptual matching (pHash, dHash)
|
||||
is available for image files only.
|
||||
</div>
|
||||
{% endif %}
|
||||
|
||||
{# Query file hashes #}
|
||||
<div class="card bg-dark border-secondary mb-4">
|
||||
<div class="card-header">
|
||||
<h6 class="mb-0"><i class="bi bi-hash me-2"></i>Image Hashes for <code>{{ filename }}</code></h6>
|
||||
<h6 class="mb-0"><i class="bi bi-hash me-2"></i>File Hashes for <code>{{ filename }}</code></h6>
|
||||
</div>
|
||||
<div class="card-body">
|
||||
<div class="mb-2">
|
||||
@ -103,13 +111,13 @@
|
||||
<div class="card-body">
|
||||
<p class="text-muted small mb-3">
|
||||
Generate a signed JSON receipt for legal or archival use.
|
||||
Re-upload the same image to produce the downloadable file.
|
||||
Re-upload the same file to produce the downloadable receipt.
|
||||
</p>
|
||||
<form action="/verify/receipt" method="post" enctype="multipart/form-data">
|
||||
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}"/>
|
||||
<div class="mb-3">
|
||||
<input class="form-control form-control-sm bg-dark text-light border-secondary"
|
||||
type="file" name="image" accept="image/*" required>
|
||||
type="file" name="image" required>
|
||||
</div>
|
||||
<button type="submit" class="btn btn-outline-warning btn-sm">
|
||||
Download Receipt (.json)
|
||||
@ -121,7 +129,7 @@
|
||||
|
||||
<div class="d-grid gap-2 mt-4">
|
||||
<a href="/verify" class="btn btn-outline-info">
|
||||
Verify Another Image
|
||||
Verify Another File
|
||||
</a>
|
||||
<a href="/attest/log" class="btn btn-outline-secondary">
|
||||
View Attestation Log
|
||||
|
||||
@ -3,7 +3,7 @@
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>{% block title %}SooSeF{% endblock %}</title>
|
||||
<title>{% block title %}FieldWitness{% endblock %}</title>
|
||||
<link rel="icon" type="image/svg+xml" href="{{ url_for('static', filename='favicon.svg') }}">
|
||||
<link href="{{ url_for('static', filename='vendor/css/bootstrap.min.css') }}" rel="stylesheet">
|
||||
<link href="{{ url_for('static', filename='vendor/css/bootstrap-icons.min.css') }}" rel="stylesheet">
|
||||
@ -13,7 +13,7 @@
|
||||
<nav class="navbar navbar-expand-lg navbar-dark">
|
||||
<div class="container-fluid">
|
||||
<a class="navbar-brand" href="/" style="padding-left: 6px; margin-right: 8px;">
|
||||
<strong>SooSeF</strong>
|
||||
<strong>FieldWitness</strong>
|
||||
</a>
|
||||
|
||||
{# Channel + Identity indicators #}
|
||||
@ -40,7 +40,7 @@
|
||||
</li>
|
||||
|
||||
{% if not auth_enabled or is_authenticated %}
|
||||
{# ── Stegasoo ── #}
|
||||
{# ── Stego ── #}
|
||||
<li class="nav-item">
|
||||
<a class="nav-link nav-expand" href="/encode"><i class="bi bi-lock"></i><span>Encode</span></a>
|
||||
</li>
|
||||
@ -51,8 +51,8 @@
|
||||
<a class="nav-link nav-expand" href="/generate"><i class="bi bi-key"></i><span>Generate</span></a>
|
||||
</li>
|
||||
|
||||
{# ── Verisoo ── #}
|
||||
{% if has_verisoo %}
|
||||
{# ── Attest ── #}
|
||||
{% if has_attest %}
|
||||
<li class="nav-item">
|
||||
<a class="nav-link nav-expand" href="/attest"><i class="bi bi-patch-check"></i><span>Attest</span></a>
|
||||
</li>
|
||||
@ -140,9 +140,9 @@
|
||||
<footer class="py-4 mt-5">
|
||||
<div class="container text-center text-muted">
|
||||
<small>
|
||||
SooSeF v{{ version }} — Soo Security Fieldkit
|
||||
FieldWitness v{{ version }} — FieldWitness
|
||||
<span class="mx-2">|</span>
|
||||
<span class="text-muted">Stegasoo + Verisoo</span>
|
||||
<span class="text-muted">Stego + Attest</span>
|
||||
</small>
|
||||
</div>
|
||||
</footer>
|
||||
|
||||
71
frontends/web/templates/dropbox/admin.html
Normal file
71
frontends/web/templates/dropbox/admin.html
Normal file
@ -0,0 +1,71 @@
|
||||
{% extends "base.html" %}
|
||||
{% block title %}Source Drop Box — FieldWitness{% endblock %}
|
||||
{% block content %}
|
||||
<h2><i class="bi bi-inbox me-2"></i>Source Drop Box</h2>
|
||||
<p class="text-muted">Create time-limited upload links for sources who cannot install FieldWitness.</p>
|
||||
|
||||
<div class="card bg-dark mb-4">
|
||||
<div class="card-body">
|
||||
<h5 class="card-title">Create Upload Token</h5>
|
||||
<form method="POST">
|
||||
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}"/>
|
||||
<input type="hidden" name="action" value="create">
|
||||
<div class="row g-3">
|
||||
<div class="col-md-4">
|
||||
<label class="form-label">Label (internal only)</label>
|
||||
<input type="text" name="label" class="form-control bg-dark text-light"
|
||||
placeholder="e.g., Gulf Ministry Source">
|
||||
</div>
|
||||
<div class="col-md-3">
|
||||
<label class="form-label">Expires in (hours)</label>
|
||||
<input type="number" name="hours" value="24" min="1" max="168"
|
||||
class="form-control bg-dark text-light">
|
||||
</div>
|
||||
<div class="col-md-3">
|
||||
<label class="form-label">Max files</label>
|
||||
<input type="number" name="max_files" value="10" min="1" max="100"
|
||||
class="form-control bg-dark text-light">
|
||||
</div>
|
||||
<div class="col-md-2 d-flex align-items-end">
|
||||
<button type="submit" class="btn btn-primary w-100">Create</button>
|
||||
</div>
|
||||
</div>
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{% if tokens %}
|
||||
<h5>Active Tokens</h5>
|
||||
<table class="table table-dark table-sm">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Label</th>
|
||||
<th>Token</th>
|
||||
<th>Used / Max</th>
|
||||
<th>Expires</th>
|
||||
<th></th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{% for token, data in tokens.items() %}
|
||||
<tr>
|
||||
<td>{{ data.label }}</td>
|
||||
<td><code>{{ token[:12] }}...</code></td>
|
||||
<td>{{ data.used }} / {{ data.max_files }}</td>
|
||||
<td>{{ data.expires_at[:16] }}</td>
|
||||
<td>
|
||||
<form method="POST" class="d-inline">
|
||||
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}"/>
|
||||
<input type="hidden" name="action" value="revoke">
|
||||
<input type="hidden" name="token" value="{{ token }}">
|
||||
<button type="submit" class="btn btn-sm btn-outline-danger">Revoke</button>
|
||||
</form>
|
||||
</td>
|
||||
</tr>
|
||||
{% endfor %}
|
||||
</tbody>
|
||||
</table>
|
||||
{% else %}
|
||||
<p class="text-muted">No active upload tokens.</p>
|
||||
{% endif %}
|
||||
{% endblock %}
|
||||
108
frontends/web/templates/federation/status.html
Normal file
108
frontends/web/templates/federation/status.html
Normal file
@ -0,0 +1,108 @@
|
||||
{% extends "base.html" %}
|
||||
{% block title %}Federation — FieldWitness{% endblock %}
|
||||
{% block content %}
|
||||
<h2><i class="bi bi-diagram-3 me-2"></i>Federation</h2>
|
||||
<p class="text-muted">Gossip-based attestation sync between FieldWitness instances.</p>
|
||||
|
||||
<div class="row mb-4">
|
||||
<div class="col-md-4">
|
||||
<div class="card bg-dark">
|
||||
<div class="card-body">
|
||||
<h6 class="card-subtitle text-muted">Local Node</h6>
|
||||
<p class="mb-1">Records: <strong>{{ node_info.size }}</strong></p>
|
||||
<p class="mb-0 text-muted small">Root: {{ node_info.root }}</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="col-md-4">
|
||||
<div class="card bg-dark">
|
||||
<div class="card-body">
|
||||
<h6 class="card-subtitle text-muted">Peers</h6>
|
||||
<p class="mb-0"><strong>{{ peers|length }}</strong> configured</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="col-md-4">
|
||||
<div class="card bg-dark">
|
||||
<div class="card-body">
|
||||
<h6 class="card-subtitle text-muted">Last Sync</h6>
|
||||
{% if history %}
|
||||
<p class="mb-0">{{ history[0].synced_at[:16] }}</p>
|
||||
{% else %}
|
||||
<p class="mb-0 text-muted">Never</p>
|
||||
{% endif %}
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h5>Peers</h5>
|
||||
{% if peers %}
|
||||
<table class="table table-dark table-sm">
|
||||
<thead>
|
||||
<tr><th>URL</th><th>Fingerprint</th><th>Records</th><th>Health</th><th>Last Seen</th><th></th></tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{% for p in peers %}
|
||||
<tr>
|
||||
<td><code>{{ p.url }}</code></td>
|
||||
<td><code>{{ p.fingerprint[:16] }}...</code></td>
|
||||
<td>{{ p.last_size }}</td>
|
||||
<td>{% if p.healthy %}<span class="text-success">OK</span>{% else %}<span class="text-danger">DOWN</span>{% endif %}</td>
|
||||
<td>{{ p.last_seen.strftime('%Y-%m-%d %H:%M') if p.last_seen else 'Never' }}</td>
|
||||
<td>
|
||||
<form method="POST" action="{{ url_for('federation.peer_remove') }}" class="d-inline">
|
||||
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}"/>
|
||||
<input type="hidden" name="url" value="{{ p.url }}">
|
||||
<button type="submit" class="btn btn-sm btn-outline-danger" title="Remove">
|
||||
<i class="bi bi-trash"></i>
|
||||
</button>
|
||||
</form>
|
||||
</td>
|
||||
</tr>
|
||||
{% endfor %}
|
||||
</tbody>
|
||||
</table>
|
||||
{% else %}
|
||||
<p class="text-muted">No peers configured. Add one below.</p>
|
||||
{% endif %}
|
||||
|
||||
<div class="card bg-dark mb-4">
|
||||
<div class="card-body">
|
||||
<h6 class="card-title">Add Peer</h6>
|
||||
<form method="POST" action="{{ url_for('federation.peer_add') }}">
|
||||
<input type="hidden" name="csrf_token" value="{{ csrf_token() }}"/>
|
||||
<div class="row g-2">
|
||||
<div class="col-md-5">
|
||||
<input type="url" name="url" class="form-control bg-dark text-light" placeholder="https://peer:8000" required>
|
||||
</div>
|
||||
<div class="col-md-5">
|
||||
<input type="text" name="fingerprint" class="form-control bg-dark text-light" placeholder="Ed25519 fingerprint" required>
|
||||
</div>
|
||||
<div class="col-md-2">
|
||||
<button type="submit" class="btn btn-primary w-100">Add</button>
|
||||
</div>
|
||||
</div>
|
||||
</form>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{% if history %}
|
||||
<h5>Sync History</h5>
|
||||
<table class="table table-dark table-sm">
|
||||
<thead>
|
||||
<tr><th>Time</th><th>Peer</th><th>Records</th><th>Status</th></tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{% for h in history %}
|
||||
<tr>
|
||||
<td>{{ h.synced_at[:19] }}</td>
|
||||
<td><code>{{ h.peer_url[:30] }}</code></td>
|
||||
<td>+{{ h.records_received }}</td>
|
||||
<td>{% if h.success %}<span class="text-success">OK</span>{% else %}<span class="text-danger">{{ h.error[:40] if h.error else 'Failed' }}</span>{% endif %}</td>
|
||||
</tr>
|
||||
{% endfor %}
|
||||
</tbody>
|
||||
</table>
|
||||
{% endif %}
|
||||
{% endblock %}
|
||||
@ -1,8 +1,8 @@
|
||||
{% extends "base.html" %}
|
||||
{% block title %}Keys — SooSeF{% endblock %}
|
||||
{% block title %}Keys — FieldWitness{% endblock %}
|
||||
{% block content %}
|
||||
<h2><i class="bi bi-key me-2"></i>Key Management</h2>
|
||||
<p class="text-muted">Manage Stegasoo channel keys and Verisoo Ed25519 identity.</p>
|
||||
<p class="text-muted">Manage Stego channel keys and Attest Ed25519 identity.</p>
|
||||
|
||||
<div class="row g-4">
|
||||
{# Channel Key #}
|
||||
@ -13,7 +13,7 @@
|
||||
{% if keystore.has_channel_key %}
|
||||
<p class="text-muted small">
|
||||
Fingerprint: <code>{{ keystore.channel_fingerprint }}</code><br>
|
||||
Used for Stegasoo deployment isolation.
|
||||
Used for Stego deployment isolation.
|
||||
</p>
|
||||
{% else %}
|
||||
<p class="text-muted small">No channel key configured.</p>
|
||||
@ -36,7 +36,7 @@
|
||||
{% if keystore.has_identity %}
|
||||
<p class="text-muted small">
|
||||
Fingerprint: <code>{{ keystore.identity_fingerprint }}</code><br>
|
||||
Used for Verisoo attestation signing.
|
||||
Used for Attest attestation signing.
|
||||
</p>
|
||||
{% else %}
|
||||
<p class="text-muted small">No identity configured.</p>
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
{% extends "base.html" %}
|
||||
{% block title %}Killswitch — SooSeF{% endblock %}
|
||||
{% block title %}Killswitch — FieldWitness{% endblock %}
|
||||
{% block content %}
|
||||
<h2 class="text-danger"><i class="bi bi-exclamation-octagon me-2"></i>Emergency Killswitch</h2>
|
||||
<p class="text-muted">Destroy all key material and sensitive data. This action is irreversible.</p>
|
||||
@ -9,7 +9,7 @@
|
||||
<h5 class="card-title text-danger">Destruction Order</h5>
|
||||
<ol class="text-muted small">
|
||||
<li>Ed25519 identity keys (signing identity)</li>
|
||||
<li>Stegasoo channel key (deployment binding)</li>
|
||||
<li>Stego channel key (deployment binding)</li>
|
||||
<li>Flask session secret (invalidates all sessions)</li>
|
||||
<li>Auth database (user accounts)</li>
|
||||
<li>Attestation log + index (provenance records)</li>
|
||||
|
||||
@ -1,5 +1,5 @@
|
||||
{% extends "base.html" %}
|
||||
{% block title %}Fieldkit Status — SooSeF{% endblock %}
|
||||
{% block title %}Fieldkit Status — FieldWitness{% endblock %}
|
||||
{% block content %}
|
||||
<h2><i class="bi bi-speedometer2 me-2"></i>Fieldkit Status</h2>
|
||||
<p class="text-muted">Security monitors and system health.</p>
|
||||
|
||||
@ -1,19 +1,19 @@
|
||||
{% extends "base.html" %}
|
||||
{% block title %}SooSeF — Soo Security Fieldkit{% endblock %}
|
||||
{% block title %}FieldWitness — FieldWitness{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="text-center mb-5">
|
||||
<h1 class="display-5 fw-bold">Soo Security Fieldkit</h1>
|
||||
<h1 class="display-5 fw-bold">FieldWitness</h1>
|
||||
<p class="lead text-muted">Offline-first security toolkit for field operations</p>
|
||||
</div>
|
||||
|
||||
<div class="row g-4">
|
||||
{# ── Stegasoo Card ── #}
|
||||
{# ── Stego Card ── #}
|
||||
<div class="col-md-6 col-lg-4">
|
||||
<div class="card h-100 bg-dark border-secondary">
|
||||
<div class="card-body">
|
||||
<h5 class="card-title"><i class="bi bi-lock me-2 text-primary"></i>Encode</h5>
|
||||
<p class="card-text text-muted">Hide encrypted messages in images or audio using Stegasoo's hybrid authentication.</p>
|
||||
<p class="card-text text-muted">Hide encrypted messages in images or audio using Stego's hybrid authentication.</p>
|
||||
<a href="/encode" class="btn btn-outline-primary btn-sm">Encode Message</a>
|
||||
</div>
|
||||
</div>
|
||||
@ -37,8 +37,8 @@
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{# ── Verisoo Cards ── #}
|
||||
{% if has_verisoo %}
|
||||
{# ── Attest Cards ── #}
|
||||
{% if has_attest %}
|
||||
<div class="col-md-6 col-lg-4">
|
||||
<div class="card h-100 bg-dark border-secondary">
|
||||
<div class="card-body">
|
||||
@ -102,10 +102,10 @@
|
||||
<i class="bi bi-image me-1"></i>DCT: {{ 'Available' if has_dct else 'Unavailable' }}
|
||||
</span>
|
||||
</div>
|
||||
{% if has_verisoo %}
|
||||
{% if has_attest %}
|
||||
<div class="col-auto">
|
||||
<span class="badge bg-success">
|
||||
<i class="bi bi-patch-check me-1"></i>Verisoo: Active
|
||||
<i class="bi bi-patch-check me-1"></i>Attest: Active
|
||||
</span>
|
||||
</div>
|
||||
{% endif %}
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block title %}Login - Stegasoo{% endblock %}
|
||||
{% block title %}Login - Stego{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block title %}Password Recovery - Stegasoo{% endblock %}
|
||||
{% block title %}Password Recovery - Stego{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
@ -116,7 +116,7 @@
|
||||
<div class="alert alert-warning mt-4 small">
|
||||
<i class="bi bi-exclamation-triangle me-2"></i>
|
||||
<strong>Note:</strong> This will reset the admin password. If you don't have a valid recovery key,
|
||||
you'll need to delete the database and reconfigure Stegasoo.
|
||||
you'll need to delete the database and reconfigure Stego.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
@ -125,6 +125,6 @@
|
||||
{% block scripts %}
|
||||
<script src="{{ url_for('static', filename='js/auth.js') }}"></script>
|
||||
<script>
|
||||
StegasooAuth.initPasswordConfirmation('recoverForm', 'passwordInput', 'passwordConfirmInput');
|
||||
StegoAuth.initPasswordConfirmation('recoverForm', 'passwordInput', 'passwordConfirmInput');
|
||||
</script>
|
||||
{% endblock %}
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block title %}Regenerate Recovery Key - Stegasoo{% endblock %}
|
||||
{% block title %}Regenerate Recovery Key - Stego{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
@ -142,7 +142,7 @@ function copyToClipboard() {
|
||||
// Download as text file
|
||||
function downloadTextFile() {
|
||||
const key = document.getElementById('recoveryKey').value;
|
||||
const content = `Stegasoo Recovery Key
|
||||
const content = `Stego Recovery Key
|
||||
=====================
|
||||
|
||||
${key}
|
||||
@ -158,7 +158,7 @@ Generated: ${new Date().toISOString()}
|
||||
const url = URL.createObjectURL(blob);
|
||||
const a = document.createElement('a');
|
||||
a.href = url;
|
||||
a.download = 'stegasoo-recovery-key.txt';
|
||||
a.download = 'stego-recovery-key.txt';
|
||||
a.click();
|
||||
URL.revokeObjectURL(url);
|
||||
}
|
||||
@ -170,7 +170,7 @@ function downloadQRImage() {
|
||||
|
||||
const a = document.createElement('a');
|
||||
a.href = img.src;
|
||||
a.download = 'stegasoo-recovery-qr.png';
|
||||
a.download = 'stego-recovery-qr.png';
|
||||
a.click();
|
||||
}
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block title %}Setup - Stegasoo{% endblock %}
|
||||
{% block title %}Setup - Stego{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
@ -12,7 +12,7 @@
|
||||
</div>
|
||||
<div class="card-body">
|
||||
<p class="text-muted text-center mb-4">
|
||||
Welcome to Stegasoo! Create your admin account to get started.
|
||||
Welcome to Stego! Create your admin account to get started.
|
||||
</p>
|
||||
|
||||
<form method="POST" action="{{ url_for('setup') }}" id="setupForm">
|
||||
@ -72,6 +72,6 @@
|
||||
{% block scripts %}
|
||||
<script src="{{ url_for('static', filename='js/auth.js') }}"></script>
|
||||
<script>
|
||||
StegasooAuth.initPasswordConfirmation('setupForm', 'passwordInput', 'passwordConfirmInput');
|
||||
StegoAuth.initPasswordConfirmation('setupForm', 'passwordInput', 'passwordConfirmInput');
|
||||
</script>
|
||||
{% endblock %}
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block title %}Recovery Key Setup - Stegasoo{% endblock %}
|
||||
{% block title %}Recovery Key Setup - Stego{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
@ -135,7 +135,7 @@ function copyToClipboard() {
|
||||
// Download as text file
|
||||
function downloadTextFile() {
|
||||
const key = document.getElementById('recoveryKey').value;
|
||||
const content = `Stegasoo Recovery Key
|
||||
const content = `Stego Recovery Key
|
||||
=====================
|
||||
|
||||
${key}
|
||||
@ -151,7 +151,7 @@ Generated: ${new Date().toISOString()}
|
||||
const url = URL.createObjectURL(blob);
|
||||
const a = document.createElement('a');
|
||||
a.href = url;
|
||||
a.download = 'stegasoo-recovery-key.txt';
|
||||
a.download = 'stego-recovery-key.txt';
|
||||
a.click();
|
||||
URL.revokeObjectURL(url);
|
||||
}
|
||||
@ -163,7 +163,7 @@ function downloadQRImage() {
|
||||
|
||||
const a = document.createElement('a');
|
||||
a.href = img.src;
|
||||
a.download = 'stegasoo-recovery-qr.png';
|
||||
a.download = 'stego-recovery-qr.png';
|
||||
a.click();
|
||||
}
|
||||
|
||||
|
||||
@ -1,17 +1,17 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block title %}About - Stegasoo{% endblock %}
|
||||
{% block title %}About - Stego{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
<div class="col-lg-10">
|
||||
<div class="card mb-4">
|
||||
<div class="card-header">
|
||||
<h5 class="mb-0"><i class="bi bi-info-circle me-2"></i>About Stegasoo</h5>
|
||||
<h5 class="mb-0"><i class="bi bi-info-circle me-2"></i>About Stego</h5>
|
||||
</div>
|
||||
<div class="card-body">
|
||||
<p class="lead">
|
||||
Stegasoo hides encrypted messages and files inside images using multi-factor authentication.
|
||||
Stego hides encrypted messages and files inside images using multi-factor authentication.
|
||||
</p>
|
||||
|
||||
<h6 class="text-primary mt-4 mb-3">Features</h6>
|
||||
@ -325,7 +325,7 @@
|
||||
<div class="alert alert-info mt-3 mb-0">
|
||||
<i class="bi bi-info-circle me-2"></i>
|
||||
This server is running in <strong>public mode</strong>.
|
||||
Set <code>STEGASOO_CHANNEL_KEY</code> to enable server-wide channel isolation.
|
||||
Set <code>FIELDWITNESS_CHANNEL_KEY</code> to enable server-wide channel isolation.
|
||||
</div>
|
||||
{% endif %}
|
||||
</div>
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block title %}Decode Message - Stegasoo{% endblock %}
|
||||
{% block title %}Decode Message - Stego{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<style>
|
||||
@ -487,7 +487,7 @@
|
||||
{% endblock %}
|
||||
|
||||
{% block scripts %}
|
||||
<script src="{{ url_for('static', filename='js/soosef.js') }}"></script>
|
||||
<script src="{{ url_for('static', filename='js/fieldwitness.js') }}"></script>
|
||||
<script>
|
||||
// ============================================================================
|
||||
// MODE HINT - Dynamic text based on selected extraction mode
|
||||
@ -677,6 +677,6 @@ if (document.getElementById('modeDct')?.disabled) {
|
||||
// LOADING STATE
|
||||
// ============================================================================
|
||||
|
||||
Stegasoo.initFormLoading('decodeForm', 'decodeBtn', 'Decoding...');
|
||||
Stego.initFormLoading('decodeForm', 'decodeBtn', 'Decoding...');
|
||||
</script>
|
||||
{% endblock %}
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block title %}Encode Message - Stegasoo{% endblock %}
|
||||
{% block title %}Encode Message - Stego{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<style>
|
||||
@ -507,7 +507,7 @@
|
||||
{% endblock %}
|
||||
|
||||
{% block scripts %}
|
||||
<script src="{{ url_for('static', filename='js/soosef.js') }}"></script>
|
||||
<script src="{{ url_for('static', filename='js/fieldwitness.js') }}"></script>
|
||||
<script>
|
||||
// ============================================================================
|
||||
// MODE HINT - Dynamic text based on selected embedding mode
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block title %}Encode Success - Stegasoo{% endblock %}
|
||||
{% block title %}Encode Success - Stego{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
@ -218,7 +218,7 @@ if (navigator.share && navigator.canShare) {
|
||||
try {
|
||||
await navigator.share({
|
||||
files: [file],
|
||||
title: 'Stegasoo Image',
|
||||
title: 'Stego Image',
|
||||
});
|
||||
} catch (err) {
|
||||
if (err.name !== 'AbortError') {
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block title %}Generate Credentials - Stegasoo{% endblock %}
|
||||
{% block title %}Generate Credentials - Stego{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center" data-page="generate">
|
||||
@ -500,7 +500,7 @@
|
||||
{% endblock %}
|
||||
|
||||
{% block scripts %}
|
||||
<script src="{{ url_for('static', filename='js/soosef.js') }}"></script>
|
||||
<script src="{{ url_for('static', filename='js/fieldwitness.js') }}"></script>
|
||||
<script src="{{ url_for('static', filename='js/generate.js') }}"></script>
|
||||
{% if generated %}
|
||||
<script>
|
||||
@ -508,7 +508,7 @@
|
||||
const passphraseWords = '{{ passphrase|default("", true) }}'.split(' ').filter(w => w.length > 0);
|
||||
|
||||
function copyPin() {
|
||||
Stegasoo.copyToClipboard(
|
||||
Stego.copyToClipboard(
|
||||
'{{ pin|default("", true) }}',
|
||||
document.getElementById('pinCopyIcon'),
|
||||
document.getElementById('pinCopyText')
|
||||
@ -516,7 +516,7 @@ function copyPin() {
|
||||
}
|
||||
|
||||
function copyPassphrase() {
|
||||
Stegasoo.copyToClipboard(
|
||||
Stego.copyToClipboard(
|
||||
'{{ passphrase|default("", true) }}',
|
||||
document.getElementById('passphraseCopyIcon'),
|
||||
document.getElementById('passphraseCopyText')
|
||||
@ -524,11 +524,11 @@ function copyPassphrase() {
|
||||
}
|
||||
|
||||
function toggleMemoryAid() {
|
||||
StegasooGenerate.toggleMemoryAid(passphraseWords);
|
||||
StegoGenerate.toggleMemoryAid(passphraseWords);
|
||||
}
|
||||
|
||||
function regenerateStory() {
|
||||
StegasooGenerate.regenerateStory(passphraseWords);
|
||||
StegoGenerate.regenerateStory(passphraseWords);
|
||||
}
|
||||
</script>
|
||||
{% endif %}
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
{% extends "base.html" %}
|
||||
|
||||
{% block title %}Tools - Stegasoo{% endblock %}
|
||||
{% block title %}Tools - Stego{% endblock %}
|
||||
|
||||
{% block content %}
|
||||
<div class="row justify-content-center">
|
||||
|
||||
@ -3,11 +3,11 @@ requires = ["hatchling"]
|
||||
build-backend = "hatchling.build"
|
||||
|
||||
[project]
|
||||
name = "soosef"
|
||||
version = "0.2.0"
|
||||
description = "Soo Security Fieldkit — offline-first security toolkit for journalists, NGOs, and at-risk organizations"
|
||||
name = "fieldwitness"
|
||||
version = "0.3.0"
|
||||
description = "FieldWitness — offline-first security toolkit for journalists, NGOs, and at-risk organizations"
|
||||
readme = "README.md"
|
||||
license = "MIT"
|
||||
license = "GPL-3.0-only"
|
||||
requires-python = ">=3.11"
|
||||
authors = [
|
||||
{ name = "Aaron D. Lee" }
|
||||
@ -28,7 +28,7 @@ classifiers = [
|
||||
"Environment :: Web Environment",
|
||||
"Intended Audience :: Developers",
|
||||
"Intended Audience :: End Users/Desktop",
|
||||
"License :: OSI Approved :: MIT License",
|
||||
"License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
|
||||
"Operating System :: OS Independent",
|
||||
"Programming Language :: Python :: 3",
|
||||
"Programming Language :: Python :: 3.11",
|
||||
@ -84,13 +84,13 @@ web = [
|
||||
"qrcode>=7.3.0",
|
||||
"pyzbar>=0.1.9",
|
||||
"piexif>=1.1.0",
|
||||
"soosef[attest,stego-dct]",
|
||||
"fieldwitness[attest,stego-dct]",
|
||||
]
|
||||
api = [
|
||||
"fastapi>=0.109.0",
|
||||
"uvicorn[standard]>=0.27.0",
|
||||
"python-multipart>=0.0.6",
|
||||
"soosef[stego-dct]",
|
||||
"fieldwitness[stego-dct]",
|
||||
]
|
||||
fieldkit = [
|
||||
"watchdog>=4.0.0",
|
||||
@ -99,28 +99,42 @@ fieldkit = [
|
||||
federation = [
|
||||
"aiohttp>=3.9.0",
|
||||
]
|
||||
tor = [
|
||||
"stem>=1.8.0",
|
||||
]
|
||||
c2pa = [
|
||||
"c2pa-python>=0.6.0",
|
||||
"fieldwitness[attest]",
|
||||
]
|
||||
evidence-pdf = [
|
||||
"xhtml2pdf>=0.2.11",
|
||||
]
|
||||
rpi = [
|
||||
"soosef[web,cli,fieldkit]",
|
||||
"fieldwitness[web,cli,fieldkit]",
|
||||
"gpiozero>=2.0",
|
||||
]
|
||||
all = [
|
||||
"soosef[stego-dct,stego-audio,stego-compression,attest,cli,web,api,fieldkit,federation]",
|
||||
"fieldwitness[stego-dct,stego-audio,stego-compression,attest,cli,web,api,fieldkit,federation,tor,c2pa,evidence-pdf]",
|
||||
]
|
||||
dev = [
|
||||
"soosef[all]",
|
||||
"fieldwitness[all]",
|
||||
"pytest>=7.0.0",
|
||||
"pytest-cov>=4.0.0",
|
||||
"black>=23.0.0",
|
||||
"ruff>=0.1.0",
|
||||
"mypy>=1.0.0",
|
||||
]
|
||||
test-e2e = [
|
||||
"pytest-playwright>=0.4.0",
|
||||
"playwright>=1.40.0",
|
||||
]
|
||||
|
||||
[project.scripts]
|
||||
soosef = "soosef.cli:main"
|
||||
fieldwitness = "fieldwitness.cli:main"
|
||||
|
||||
[project.urls]
|
||||
Homepage = "https://github.com/alee/soosef"
|
||||
Repository = "https://github.com/alee/soosef"
|
||||
Homepage = "https://github.com/alee/fieldwitness"
|
||||
Repository = "https://github.com/alee/fieldwitness"
|
||||
|
||||
[tool.hatch.build.targets.sdist]
|
||||
include = [
|
||||
@ -129,18 +143,21 @@ include = [
|
||||
]
|
||||
|
||||
[tool.hatch.build.targets.wheel]
|
||||
packages = ["src/soosef", "frontends"]
|
||||
packages = ["src/fieldwitness", "frontends"]
|
||||
|
||||
[tool.hatch.build.targets.wheel.sources]
|
||||
"src" = ""
|
||||
|
||||
[tool.hatch.build.targets.wheel.force-include]
|
||||
"src/soosef/stegasoo/data/bip39-words.txt" = "soosef/stegasoo/data/bip39-words.txt"
|
||||
"src/fieldwitness/stego/data/bip39-words.txt" = "fieldwitness/stego/data/bip39-words.txt"
|
||||
|
||||
[tool.pytest.ini_options]
|
||||
testpaths = ["tests"]
|
||||
python_files = ["test_*.py"]
|
||||
addopts = "-v --cov=soosef --cov-report=term-missing"
|
||||
addopts = "-v --cov=fieldwitness --cov-report=term-missing"
|
||||
markers = [
|
||||
"e2e: end-to-end Playwright browser tests (require `playwright install` and `pip install fieldwitness[test-e2e]`)",
|
||||
]
|
||||
|
||||
[tool.black]
|
||||
line-length = 100
|
||||
@ -155,11 +172,11 @@ ignore = ["E501"]
|
||||
|
||||
[tool.ruff.lint.per-file-ignores]
|
||||
# YCbCr colorspace variables (R, G, B, Y, Cb, Cr) are standard names
|
||||
"src/soosef/stegasoo/dct_steganography.py" = ["N803", "N806"]
|
||||
"src/fieldwitness/stego/dct_steganography.py" = ["N803", "N806"]
|
||||
# MDCT transform variables (N, X) are standard mathematical names
|
||||
"src/soosef/stegasoo/spread_steganography.py" = ["N803", "N806"]
|
||||
"src/fieldwitness/stego/spread_steganography.py" = ["N803", "N806"]
|
||||
# Package __init__.py has imports after try/except and aliases - intentional structure
|
||||
"src/soosef/stegasoo/__init__.py" = ["E402"]
|
||||
"src/fieldwitness/stego/__init__.py" = ["E402"]
|
||||
|
||||
[tool.mypy]
|
||||
python_version = "3.11"
|
||||
|
||||
14
src/fieldwitness/__init__.py
Normal file
14
src/fieldwitness/__init__.py
Normal file
@ -0,0 +1,14 @@
|
||||
"""
|
||||
FieldWitness — FieldWitness
|
||||
|
||||
Offline-first security toolkit for journalists, NGOs, and at-risk organizations.
|
||||
Combines Stego (steganography) and Attest (provenance attestation) with
|
||||
field-hardened security features.
|
||||
|
||||
Part of the Soo Suite:
|
||||
- Stego: hide encrypted messages in media
|
||||
- Attest: prove image provenance and authenticity
|
||||
- FieldWitness: unified fieldkit with killswitch, dead man's switch, and key management
|
||||
"""
|
||||
|
||||
__version__ = "0.3.0"
|
||||
47
src/fieldwitness/_availability.py
Normal file
47
src/fieldwitness/_availability.py
Normal file
@ -0,0 +1,47 @@
|
||||
"""Runtime availability checks for optional fieldwitness subpackages."""
|
||||
|
||||
|
||||
def has_stego() -> bool:
|
||||
"""Check if fieldwitness.stego is importable (core deps are always present)."""
|
||||
try:
|
||||
import fieldwitness.stego # noqa: F401
|
||||
|
||||
return True
|
||||
except ImportError:
|
||||
return False
|
||||
|
||||
|
||||
def has_attest() -> bool:
|
||||
"""Check if fieldwitness.attest is importable (requires [attest] extra)."""
|
||||
try:
|
||||
import fieldwitness.attest # noqa: F401
|
||||
|
||||
return True
|
||||
except ImportError:
|
||||
return False
|
||||
|
||||
|
||||
def has_c2pa() -> bool:
|
||||
"""Check if c2pa-python is importable (requires [c2pa] extra)."""
|
||||
try:
|
||||
import c2pa # noqa: F401
|
||||
|
||||
return True
|
||||
except ImportError:
|
||||
return False
|
||||
|
||||
|
||||
def has_tor() -> bool:
|
||||
"""Check if stem is importable and a Tor hidden service can be started.
|
||||
|
||||
stem is the Python controller library for Tor. It is an optional
|
||||
dependency installed via the ``[tor]`` extra. This function checks only
|
||||
that the library is present -- it does not verify that a Tor daemon is
|
||||
running. Use ``fieldwitness.fieldkit.tor.start_onion_service`` for that.
|
||||
"""
|
||||
try:
|
||||
import stem # noqa: F401
|
||||
|
||||
return True
|
||||
except ImportError:
|
||||
return False
|
||||
36
src/fieldwitness/api.py
Normal file
36
src/fieldwitness/api.py
Normal file
@ -0,0 +1,36 @@
|
||||
"""Optional unified FastAPI app combining stego and attest APIs.
|
||||
|
||||
Usage::
|
||||
|
||||
uvicorn fieldwitness.api:app --host 0.0.0.0 --port 8000
|
||||
|
||||
Requires the [api] extra: pip install fieldwitness[api]
|
||||
"""
|
||||
|
||||
from fastapi import FastAPI
|
||||
|
||||
app = FastAPI(
|
||||
title="FieldWitness API",
|
||||
version="0.2.0",
|
||||
description="Unified steganography and attestation API",
|
||||
)
|
||||
|
||||
try:
|
||||
from fieldwitness.stego.api import app as stego_api
|
||||
|
||||
app.mount("/stego", stego_api)
|
||||
except ImportError:
|
||||
pass
|
||||
|
||||
try:
|
||||
from fieldwitness.attest.api import app as attest_api
|
||||
|
||||
app.mount("/attest", attest_api)
|
||||
except ImportError:
|
||||
pass
|
||||
|
||||
|
||||
@app.get("/health")
|
||||
async def health():
|
||||
"""Health check endpoint."""
|
||||
return {"status": "ok"}
|
||||
209
src/fieldwitness/archive.py
Normal file
209
src/fieldwitness/archive.py
Normal file
@ -0,0 +1,209 @@
|
||||
"""
|
||||
Cold archive export for long-term evidence preservation.
|
||||
|
||||
Produces a self-describing archive containing everything needed to
|
||||
reconstitute a FieldWitness evidence store on a fresh instance or verify
|
||||
evidence decades later without any FieldWitness installation.
|
||||
|
||||
Designed for OAIS (ISO 14721) alignment: the archive is self-describing,
|
||||
includes its own verification code, and documents the cryptographic
|
||||
algorithms used.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
import json
|
||||
import zipfile
|
||||
from datetime import UTC, datetime
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def export_cold_archive(
|
||||
output_path: Path,
|
||||
include_keys: bool = True,
|
||||
key_password: bytes | None = None,
|
||||
) -> dict:
|
||||
"""Export a full cold archive of the FieldWitness evidence store.
|
||||
|
||||
Contents:
|
||||
- chain/chain.bin — raw append-only hash chain
|
||||
- chain/state.cbor — chain state checkpoint
|
||||
- chain/anchors/ — external timestamp anchors
|
||||
- attestations/log.bin — attest attestation log
|
||||
- attestations/index/ — LMDB index (if present)
|
||||
- keys/public.pem — signer's public key
|
||||
- keys/bundle.enc — encrypted key bundle (if include_keys + password)
|
||||
- keys/trusted/ — trusted collaborator keys
|
||||
- manifest.json — archive metadata and integrity hashes
|
||||
- verify.py — standalone verification script
|
||||
- ALGORITHMS.txt — cryptographic algorithm documentation
|
||||
- README.txt — human-readable description
|
||||
|
||||
Args:
|
||||
output_path: Where to write the ZIP.
|
||||
include_keys: Whether to include the encrypted key bundle.
|
||||
key_password: Password for encrypting the key bundle.
|
||||
|
||||
Returns:
|
||||
Summary dict with archive contents.
|
||||
"""
|
||||
import shutil
|
||||
|
||||
from fieldwitness.paths import (
|
||||
ATTESTATIONS_DIR,
|
||||
CHAIN_DIR,
|
||||
IDENTITY_DIR,
|
||||
IDENTITY_PUBLIC_KEY,
|
||||
TRUSTED_KEYS_DIR,
|
||||
)
|
||||
|
||||
ts = datetime.now(UTC)
|
||||
contents = []
|
||||
|
||||
with zipfile.ZipFile(output_path, "w", zipfile.ZIP_DEFLATED) as zf:
|
||||
|
||||
# Chain data
|
||||
chain_bin = CHAIN_DIR / "chain.bin"
|
||||
if chain_bin.exists():
|
||||
zf.write(chain_bin, "chain/chain.bin")
|
||||
contents.append("chain/chain.bin")
|
||||
|
||||
state_cbor = CHAIN_DIR / "state.cbor"
|
||||
if state_cbor.exists():
|
||||
zf.write(state_cbor, "chain/state.cbor")
|
||||
contents.append("chain/state.cbor")
|
||||
|
||||
anchors_dir = CHAIN_DIR / "anchors"
|
||||
if anchors_dir.exists():
|
||||
for anchor_file in anchors_dir.glob("*.json"):
|
||||
zf.write(anchor_file, f"chain/anchors/{anchor_file.name}")
|
||||
contents.append(f"chain/anchors/{anchor_file.name}")
|
||||
|
||||
# Attestation log
|
||||
log_bin = ATTESTATIONS_DIR / "log.bin"
|
||||
if log_bin.exists():
|
||||
zf.write(log_bin, "attestations/log.bin")
|
||||
contents.append("attestations/log.bin")
|
||||
|
||||
# LMDB index
|
||||
lmdb_dir = ATTESTATIONS_DIR / "index"
|
||||
if lmdb_dir.exists():
|
||||
for f in lmdb_dir.iterdir():
|
||||
if f.name != "lock.mdb": # Skip lock file
|
||||
zf.write(f, f"attestations/index/{f.name}")
|
||||
contents.append(f"attestations/index/{f.name}")
|
||||
|
||||
# Public key (always included — not secret)
|
||||
if IDENTITY_PUBLIC_KEY.exists():
|
||||
zf.write(IDENTITY_PUBLIC_KEY, "keys/public.pem")
|
||||
contents.append("keys/public.pem")
|
||||
|
||||
# Trusted keys
|
||||
trusted_dir = TRUSTED_KEYS_DIR
|
||||
if trusted_dir.exists():
|
||||
for key_dir in trusted_dir.iterdir():
|
||||
for f in key_dir.iterdir():
|
||||
arcname = f"keys/trusted/{key_dir.name}/{f.name}"
|
||||
zf.write(f, arcname)
|
||||
contents.append(arcname)
|
||||
|
||||
# Encrypted key bundle (optional)
|
||||
if include_keys and key_password:
|
||||
from fieldwitness.keystore.export import export_bundle
|
||||
from fieldwitness.paths import CHANNEL_KEY_FILE
|
||||
|
||||
import tempfile
|
||||
|
||||
with tempfile.NamedTemporaryFile(suffix=".enc", delete=False) as tmp:
|
||||
tmp_path = Path(tmp.name)
|
||||
try:
|
||||
export_bundle(IDENTITY_DIR, CHANNEL_KEY_FILE, tmp_path, key_password)
|
||||
zf.write(tmp_path, "keys/bundle.enc")
|
||||
contents.append("keys/bundle.enc")
|
||||
except Exception:
|
||||
pass
|
||||
finally:
|
||||
tmp_path.unlink(missing_ok=True)
|
||||
|
||||
# Algorithm documentation
|
||||
algorithms = """FIELDWITNESS CRYPTOGRAPHIC ALGORITHMS
|
||||
================================
|
||||
|
||||
This archive uses the following algorithms:
|
||||
|
||||
SIGNING
|
||||
- Ed25519 (RFC 8032): 32-byte public keys, 64-byte signatures
|
||||
- Used for: attestation records, chain records, verification receipts
|
||||
|
||||
HASHING
|
||||
- SHA-256: content hashing, chain linkage, fingerprints
|
||||
- pHash (DCT perceptual hash): image similarity matching
|
||||
- dHash (difference hash): image similarity matching
|
||||
|
||||
ENCRYPTION (key bundle only)
|
||||
- AES-256-GCM: authenticated encryption
|
||||
- Argon2id (RFC 9106): key derivation from password
|
||||
Parameters: time_cost=4, memory_cost=256MB, parallelism=4
|
||||
|
||||
CHAIN FORMAT
|
||||
- Append-only binary log: [uint32 BE length] [CBOR record]*
|
||||
- CBOR (RFC 8949): deterministic serialization
|
||||
- Each record signed by Ed25519, linked by prev_hash (SHA-256)
|
||||
|
||||
ATTESTATION LOG
|
||||
- Attest binary log: [magic "VERISOO\\x00"] [uint32 version] [records]
|
||||
- LMDB index: SHA-256, pHash, attestor fingerprint lookups
|
||||
|
||||
To verify this archive without FieldWitness:
|
||||
1. pip install cryptography cbor2
|
||||
2. python verify.py
|
||||
"""
|
||||
zf.writestr("ALGORITHMS.txt", algorithms)
|
||||
contents.append("ALGORITHMS.txt")
|
||||
|
||||
# Manifest
|
||||
manifest = {
|
||||
"archive_version": "1",
|
||||
"created_at": ts.isoformat(),
|
||||
"fieldwitness_version": "0.3.0",
|
||||
"contents": contents,
|
||||
"file_count": len(contents),
|
||||
"content_hashes": {},
|
||||
}
|
||||
|
||||
# Compute hashes of key files for integrity verification
|
||||
for name in ["chain/chain.bin", "attestations/log.bin"]:
|
||||
try:
|
||||
data = zf.read(name)
|
||||
manifest["content_hashes"][name] = hashlib.sha256(data).hexdigest()
|
||||
except KeyError:
|
||||
pass
|
||||
|
||||
zf.writestr("manifest.json", json.dumps(manifest, indent=2))
|
||||
contents.append("manifest.json")
|
||||
|
||||
# README
|
||||
readme = f"""FIELDWITNESS COLD ARCHIVE
|
||||
===================
|
||||
|
||||
Created: {ts.isoformat()}
|
||||
Files: {len(contents)}
|
||||
|
||||
This archive contains a complete snapshot of a FieldWitness evidence store.
|
||||
It is self-describing and includes everything needed to verify the
|
||||
evidence it contains, even if FieldWitness no longer exists.
|
||||
|
||||
See ALGORITHMS.txt for cryptographic algorithm documentation.
|
||||
Run verify.py to check archive integrity.
|
||||
|
||||
To restore on a fresh FieldWitness instance:
|
||||
fieldwitness archive import <this-file.zip>
|
||||
"""
|
||||
zf.writestr("README.txt", readme)
|
||||
|
||||
return {
|
||||
"path": str(output_path),
|
||||
"file_count": len(contents),
|
||||
"created_at": ts.isoformat(),
|
||||
}
|
||||
28
src/fieldwitness/attest/__init__.py
Normal file
28
src/fieldwitness/attest/__init__.py
Normal file
@ -0,0 +1,28 @@
|
||||
"""
|
||||
Attest - Decentralized image provenance and attestation.
|
||||
|
||||
Part of the Soo Suite:
|
||||
- Stego: covert communication, hiding encrypted messages in images
|
||||
- Attest: overt attestation, proving provenance and building decentralized reputation
|
||||
"""
|
||||
|
||||
__version__ = "0.2.0"
|
||||
|
||||
try:
|
||||
from .models import Attestation, AttestationRecord, Identity
|
||||
from .exceptions import AttestError, AttestationError, VerificationError
|
||||
|
||||
_AVAILABLE = True
|
||||
except ImportError:
|
||||
_AVAILABLE = False
|
||||
|
||||
__all__ = [
|
||||
"__version__",
|
||||
"_AVAILABLE",
|
||||
"Attestation",
|
||||
"AttestationRecord",
|
||||
"Identity",
|
||||
"AttestError",
|
||||
"AttestationError",
|
||||
"VerificationError",
|
||||
]
|
||||
@ -1,5 +1,5 @@
|
||||
"""
|
||||
FastAPI verification service for Verisoo.
|
||||
FastAPI verification service for Attest.
|
||||
|
||||
Lightweight REST API for:
|
||||
- Verifying images against attestation records
|
||||
@ -8,7 +8,7 @@ Lightweight REST API for:
|
||||
|
||||
Designed for media orgs and fact-checkers to integrate easily.
|
||||
|
||||
Run with: uvicorn verisoo.api:app --host 0.0.0.0 --port 8000
|
||||
Run with: uvicorn attest.api:app --host 0.0.0.0 --port 8000
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
@ -18,13 +18,15 @@ from datetime import datetime
|
||||
from pathlib import Path
|
||||
from typing import Annotated
|
||||
|
||||
import fieldwitness.paths as _fw_paths
|
||||
|
||||
try:
|
||||
from fastapi import FastAPI, File, Form, HTTPException, Query, UploadFile
|
||||
from fastapi.middleware.cors import CORSMiddleware
|
||||
from fastapi.responses import JSONResponse
|
||||
from pydantic import BaseModel
|
||||
except ImportError:
|
||||
raise ImportError("API requires fastapi: pip install verisoo[api]")
|
||||
raise ImportError("API requires fastapi: pip install attest[api]")
|
||||
|
||||
from .hashing import compute_all_distances, hash_image, is_same_image
|
||||
from .models import AttestationRecord, ImageHashes, ProofLink
|
||||
@ -32,13 +34,15 @@ from .storage import LocalStorage
|
||||
from .crypto import verify_signature, load_public_key_from_bytes
|
||||
|
||||
# Configuration via environment
|
||||
DATA_DIR = Path(os.environ.get("SOOSEF_DATA_DIR", Path.home() / ".soosef"))
|
||||
BASE_URL = os.environ.get("VERISOO_BASE_URL", "https://verisoo.io")
|
||||
# DATA_DIR defers to paths.BASE_DIR so that FIELDWITNESS_DATA_DIR and runtime
|
||||
# --data-dir overrides both propagate correctly without re-reading the env var here.
|
||||
DATA_DIR = _fw_paths.BASE_DIR
|
||||
BASE_URL = os.environ.get("FIELDWITNESS_BASE_URL", "https://attest.io")
|
||||
|
||||
app = FastAPI(
|
||||
title="Verisoo",
|
||||
title="Attest",
|
||||
description="Decentralized image provenance and attestation API",
|
||||
version="0.1.0",
|
||||
version="0.2.0",
|
||||
docs_url="/docs",
|
||||
redoc_url="/redoc",
|
||||
)
|
||||
@ -179,7 +183,7 @@ def record_to_attestation_response(
|
||||
async def root():
|
||||
"""API root - basic info."""
|
||||
return {
|
||||
"service": "Verisoo",
|
||||
"service": "Attest",
|
||||
"description": "Decentralized image provenance and attestation",
|
||||
"docs": "/docs",
|
||||
"verify": "POST /verify with image file",
|
||||
@ -274,7 +278,7 @@ async def get_proof_short(short_id: str):
|
||||
Get attestation proof by short ID.
|
||||
|
||||
This is the endpoint for shareable proof links:
|
||||
verisoo.io/v/a8f3c2d1e9b7
|
||||
attest.io/v/a8f3c2d1e9b7
|
||||
"""
|
||||
return await _get_proof(short_id)
|
||||
|
||||
@ -486,7 +490,7 @@ async def attest_from_mobile(
|
||||
from pathlib import Path
|
||||
import tempfile
|
||||
|
||||
# Check if we can embed (JPEG with stegasoo available)
|
||||
# Check if we can embed (JPEG with stego available)
|
||||
# Save image temporarily to check format
|
||||
with tempfile.NamedTemporaryFile(suffix=".jpg", delete=False) as f:
|
||||
f.write(image_data)
|
||||
@ -568,6 +572,143 @@ async def health():
|
||||
return {"status": "healthy"}
|
||||
|
||||
|
||||
# --- Federation endpoints ---
|
||||
# These 4 endpoints implement the PeerTransport protocol server side,
|
||||
# enabling gossip-based attestation sync between FieldWitness instances.
|
||||
|
||||
_storage_cache: LocalStorage | None = None
|
||||
|
||||
|
||||
def _get_cached_storage() -> LocalStorage:
|
||||
global _storage_cache
|
||||
if _storage_cache is None:
|
||||
_storage_cache = LocalStorage(DATA_DIR)
|
||||
return _storage_cache
|
||||
|
||||
|
||||
@app.get("/federation/status")
|
||||
async def federation_status():
|
||||
"""Return current merkle root and log size for gossip protocol."""
|
||||
storage = _get_cached_storage()
|
||||
stats = storage.get_stats()
|
||||
merkle_log = storage.load_merkle_log()
|
||||
return {
|
||||
"root": merkle_log.root_hash or "",
|
||||
"size": merkle_log.size,
|
||||
"record_count": stats.record_count,
|
||||
}
|
||||
|
||||
|
||||
@app.get("/federation/records")
|
||||
async def federation_records(start: int = 0, count: int = 50):
|
||||
"""Return attestation records for gossip sync.
|
||||
|
||||
Capped at 100 per request to protect RPi memory.
|
||||
"""
|
||||
count = min(count, 100)
|
||||
storage = _get_cached_storage()
|
||||
stats = storage.get_stats()
|
||||
|
||||
records = []
|
||||
for i in range(start, min(start + count, stats.record_count)):
|
||||
try:
|
||||
record = storage.get_record(i)
|
||||
records.append({
|
||||
"index": i,
|
||||
"image_hashes": record.image_hashes.to_dict(),
|
||||
"signature": record.signature.hex() if record.signature else "",
|
||||
"attestor_fingerprint": record.attestor_fingerprint,
|
||||
"timestamp": record.timestamp.isoformat(),
|
||||
"metadata": record.metadata if hasattr(record, "metadata") else {},
|
||||
})
|
||||
except Exception:
|
||||
continue
|
||||
|
||||
return {"records": records, "count": len(records)}
|
||||
|
||||
|
||||
@app.get("/federation/consistency-proof")
|
||||
async def federation_consistency_proof(old_size: int = 0):
|
||||
"""Return Merkle consistency proof for gossip sync."""
|
||||
storage = _get_cached_storage()
|
||||
merkle_log = storage.load_merkle_log()
|
||||
|
||||
if old_size < 0 or old_size > merkle_log.size:
|
||||
raise HTTPException(status_code=400, detail=f"Invalid old_size: {old_size}")
|
||||
|
||||
proof = merkle_log.consistency_proof(old_size)
|
||||
return {
|
||||
"old_size": proof.old_size,
|
||||
"new_size": proof.new_size,
|
||||
"proof_hashes": proof.proof_hashes,
|
||||
}
|
||||
|
||||
|
||||
@app.post("/federation/records")
|
||||
async def federation_push_records(body: dict):
|
||||
"""Accept attestation records from a peer.
|
||||
|
||||
Records are validated against the trust store before acceptance.
|
||||
"""
|
||||
import asyncio
|
||||
|
||||
records_data = body.get("records", [])
|
||||
if not records_data:
|
||||
return {"accepted": 0, "rejected": 0}
|
||||
|
||||
storage = _get_cached_storage()
|
||||
accepted = 0
|
||||
rejected = 0
|
||||
|
||||
# Load trusted fingerprints
|
||||
trusted_fps = set()
|
||||
try:
|
||||
from fieldwitness.keystore.manager import KeystoreManager
|
||||
|
||||
ks = KeystoreManager()
|
||||
for key in ks.get_trusted_keys():
|
||||
trusted_fps.add(key["fingerprint"])
|
||||
if ks.has_identity():
|
||||
trusted_fps.add(ks.get_identity().fingerprint)
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
for rec_data in records_data:
|
||||
fp = rec_data.get("attestor_fingerprint", "")
|
||||
|
||||
# Trust filter: reject unknown attestors (unless no trust store configured)
|
||||
if trusted_fps and fp not in trusted_fps:
|
||||
rejected += 1
|
||||
continue
|
||||
|
||||
# Deduplicate by SHA-256
|
||||
hashes = rec_data.get("image_hashes", {})
|
||||
sha256 = hashes.get("sha256", "")
|
||||
if sha256:
|
||||
existing = storage.get_records_by_image_sha256(sha256)
|
||||
if existing:
|
||||
continue # Skip duplicate silently
|
||||
|
||||
try:
|
||||
record = AttestationRecord(
|
||||
image_hashes=ImageHashes(
|
||||
sha256=hashes.get("sha256", ""),
|
||||
phash=hashes.get("phash", ""),
|
||||
dhash=hashes.get("dhash", ""),
|
||||
),
|
||||
signature=bytes.fromhex(rec_data["signature"]) if rec_data.get("signature") else b"",
|
||||
attestor_fingerprint=fp,
|
||||
timestamp=datetime.fromisoformat(rec_data["timestamp"]),
|
||||
metadata=rec_data.get("metadata", {}),
|
||||
)
|
||||
storage.append_record(record)
|
||||
accepted += 1
|
||||
except Exception:
|
||||
rejected += 1
|
||||
|
||||
return {"accepted": accepted, "rejected": rejected}
|
||||
|
||||
|
||||
# --- Run directly ---
|
||||
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
"""
|
||||
Attestation Creation Module for Verisoo.
|
||||
Attestation Creation Module for Attest.
|
||||
|
||||
This module is the core of Verisoo's provenance system. An attestation is a
|
||||
This module is the core of Attest's provenance system. An attestation is a
|
||||
cryptographic proof that binds together:
|
||||
|
||||
1. AN IMAGE - identified by multiple hashes (SHA-256 + perceptual)
|
||||
@ -59,7 +59,7 @@ Usage Example:
|
||||
from .crypto import load_private_key
|
||||
|
||||
# Load attestor's private key
|
||||
private_key = load_private_key("~/.verisoo/private.pem")
|
||||
private_key = load_private_key("~/.attest/private.pem")
|
||||
|
||||
# Create attestation with auto EXIF extraction
|
||||
attestation = create_attestation(
|
||||
@ -417,7 +417,7 @@ def create_attestation(
|
||||
- The signature covers ALL fields (hashes, fingerprint, timestamp, metadata)
|
||||
- Changing any field invalidates the signature
|
||||
- Timestamp is attestation time, not necessarily capture time
|
||||
- Verify attestations using verisoo.verification module
|
||||
- Verify attestations using attest.verification module
|
||||
"""
|
||||
# -------------------------------------------------------------------------
|
||||
# STEP 1: Establish attestation timestamp
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user