fieldwitness/docs/planning/packaging-strategy.md

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), 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.