# 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

For maximum source protection, run FieldWitness as a Tor hidden service:

1. Install Tor on the server
2. Configure a hidden service in `torrc` pointing to `127.0.0.1:5000`
3. Share the `.onion` URL instead of a LAN address
4. The source's real IP is never visible to the server

> **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.