Comprehensive documentation for v0.2.0 release

README.md (700 lines): - Three-tier deployment model with ASCII diagram - Federation blueprint in web UI routes - deploy/ directory in architecture tree - Documentation index linking all guides CLAUDE.md (256 lines): - Updated architecture tree with all new docs and deploy files New guides: - docs/federation.md (317 lines) — gossip protocol mechanics, peer setup, trust filtering, offline bundles, relay deployment, jurisdiction - docs/evidence-guide.md (283 lines) — evidence packages, cold archives, selective disclosure, chain anchoring, legal discovery workflow - docs/source-dropbox.md (220 lines) — token management, client-side hashing, extract-then-strip pipeline, receipt mechanics, opsec - docs/index.md — documentation hub linking all guides Training materials: - docs/training/reporter-quickstart.md (105 lines) — printable one-page card: boot USB, attest photo, encode message, check-in, emergency - docs/training/emergency-card.md (79 lines) — wallet-sized laminated card: three destruction methods, 10-step order, key contacts - docs/training/admin-reference.md (219 lines) — deployment tiers, CLI tables, backup checklist, hardening checklist, troubleshooting Also includes existing architecture docs from the original repos. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-01 23:31:47 -04:00
parent 2629aabcc5
commit 6325e86873
15 changed files with 3670 additions and 54 deletions
--- a/docs/training/admin-operations-guide.md
+++ b/docs/training/admin-operations-guide.md
@@ -0,0 +1,513 @@
+# SooSeF Admin Operations Guide
+
+**Audience**: IT administrators, system operators, and technically competent journalists
+responsible for deploying, configuring, and maintaining SooSeF 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 SooSeF admin:
+
+1. Deploy and maintain SooSeF 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
+(`~/.soosef/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 `~/.soosef/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
+
+SooSeF ships four presets at `deploy/config-presets/`. Select based on your operational
+environment.
+
+### Applying a Preset
+
+```bash
+$ cp deploy/config-presets/high-threat.json ~/.soosef/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 `~/.soosef/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 `soosef 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 SooSeF 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 `~/.soosef/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 SooSeF branding -- it is a minimal HTML form
+- No external resources are loaded (no CDN, fonts, analytics) -- Tor Browser compatible
+- SooSeF 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 SooSeF as a Tor hidden service
+
+### Storage Management
+
+Uploaded files accumulate in `~/.soosef/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
+
+SooSeF manages two independent key types:
+
+| Key | Algorithm | Location | Purpose |
+|---|---|---|---|
+| **Identity key** | Ed25519 | `~/.soosef/identity/` | Sign attestations, chain records |
+| **Channel key** | AES-256-GCM (Argon2id-derived) | `~/.soosef/stegasoo/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 `soosef/key-rotation-v1` record is signed by the OLD key, creating a
+verifiable trust chain.
+
+```bash
+$ soosef keys rotate-identity
+```
+
+After rotating, immediately:
+1. Take a fresh backup (`soosef 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
+$ soosef 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
+$ soosef 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
+$ soosef keys show
+```
+
+Remove a trusted key:
+
+```bash
+$ soosef keys untrust <fingerprint>
+```
+
+### Backup Schedule
+
+SooSeF warns when backups are overdue (configurable via `backup_reminder_days`).
+
+```bash
+# Create encrypted backup
+$ soosef keys export -o /media/usb/backup.enc
+
+# Check backup status
+$ soosef status
+```
+
+Store backups on separate physical media, in a different location from the device.
+
+---
+
+## 5. Federation Setup
+
+Federation allows multiple SooSeF 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 ~/.soosef/identity/public.pem /media/usb/our-pubkey.pem`
+2. Give it to the partner organization (physical handoff or secure channel)
+3. Import their key: `soosef keys trust --import /media/usb/their-pubkey.pem`
+4. Verify fingerprints out-of-band
+
+### Exporting Attestation Bundles
+
+```bash
+# Export all records
+$ soosef chain export --output /media/usb/bundle.zip
+
+# Export a specific range
+$ soosef 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
+`VERISOO_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
+$ soosef 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)
+$ soosef chain anchor --tsa https://freetsa.org/tsr
+
+# Manual (prints hash for external submission)
+$ soosef 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
+$ soosef 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 SooSeF:
+
+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
+$ soosef 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: `soosef 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
+$ soosef init
+$ soosef 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 | `soosef status` |
+| Check in (if deadman armed) | Per interval | `soosef fieldkit checkin` |
+| Backup keys | Per `backup_reminder_days` | `soosef keys export` |
+| Verify chain integrity | Weekly | `soosef chain verify` |
+| Anchor chain | Weekly | `soosef chain anchor` |
+| Review drop box submissions | As needed | `/dropbox/admin` |
+| Clean temp files | Monthly | Remove processed files from `~/.soosef/temp/` |
+| Create cold archive | Monthly | Export via CLI or web |
+| Update SooSeF | As releases are available | `pip install --upgrade soosef` |
+
+### Docker Volume Backup
+
+```bash
+$ docker compose stop server
+$ docker run --rm -v server-data:/data -v /backup:/backup \
+    busybox tar czf /backup/soosef-$(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 ~/.soosef/audit.jsonl > ~/.soosef/audit.jsonl.tmp
+$ mv ~/.soosef/audit.jsonl.tmp ~/.soosef/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.
--- a/docs/training/admin-reference.md
+++ b/docs/training/admin-reference.md
@@ -0,0 +1,219 @@
+# Administrator Quick Reference
+
+**Audience**: IT staff and technical leads responsible for deploying and maintaining
+SooSeF 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 soosef-server --target server -f deploy/docker/Dockerfile .
+$ docker build -t soosef-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. SooSeF uses SQLite -- do not scale horizontally.
+
+---
+
+## Threat Level Presets
+
+Copy the appropriate preset to configure SooSeF for the operational environment:
+
+```bash
+$ cp deploy/config-presets/<level>-threat.json ~/.soosef/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 |
+|---|---|
+| `soosef init` | Create directory structure, generate keys, write default config |
+| `soosef serve --host 0.0.0.0` | Start web UI (LAN-accessible) |
+| `soosef status` | Pre-flight check: keys, chain, deadman, backup, geofence |
+| `soosef status --json` | Machine-readable status output |
+
+### Keys
+
+| Command | Description |
+|---|---|
+| `soosef keys show` | Display current key info and fingerprints |
+| `soosef keys export -o backup.enc` | Export encrypted key bundle |
+| `soosef keys import -b backup.enc` | Import key bundle from backup |
+| `soosef keys rotate-identity` | Rotate Ed25519 identity (records in chain) |
+| `soosef keys rotate-channel` | Rotate AES-256-GCM channel key |
+| `soosef keys trust --import pubkey.pem` | Trust a collaborator's public key |
+
+### Fieldkit
+
+| Command | Description |
+|---|---|
+| `soosef fieldkit status` | Show fieldkit state (deadman, geofence, USB, tamper) |
+| `soosef fieldkit checkin` | Reset dead man's switch timer |
+| `soosef fieldkit check-deadman` | Check if deadman timer expired (for cron) |
+| `soosef fieldkit purge --confirm CONFIRM-PURGE` | Activate killswitch |
+| `soosef fieldkit geofence set --lat X --lon Y --radius M` | Set GPS boundary |
+| `soosef fieldkit usb snapshot` | Record USB whitelist baseline |
+| `soosef fieldkit tamper baseline` | Record file integrity baseline |
+
+### Chain and Evidence
+
+| Command | Description |
+|---|---|
+| `soosef chain status` | Show chain head, length, integrity |
+| `soosef chain verify` | Verify full chain (hashes + signatures) |
+| `soosef chain log --count 20` | Show recent chain entries |
+| `soosef chain export -o bundle.zip` | Export attestation bundle |
+| `soosef chain disclose -i 5,12,47 -o disclosure.json` | Selective disclosure |
+| `soosef chain anchor` | Manual anchor (prints hash for external witness) |
+| `soosef 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 `~/.soosef/auth/soosef.db`.
+
+---
+
+## Backup Checklist
+
+| What | How often | Command |
+|---|---|---|
+| Key bundle | After every rotation, weekly minimum | `soosef keys export -o backup.enc` |
+| Cold archive | Weekly or before travel | `soosef 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/soosef-$(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: `soosef 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: `soosef 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 `SOOSEF_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 `~/.soosef/` | Run SooSeF as the same user who ran `soosef 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 `~/.soosef/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
+$ soosef status --json
+```
--- a/docs/training/emergency-card.md
+++ b/docs/training/emergency-card.md
@@ -0,0 +1,79 @@
+# Emergency Reference Card
+
+**Audience**: All SooSeF 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:
+
+```
+soosef 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: `soosef 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
--- a/docs/training/reporter-field-guide.md
+++ b/docs/training/reporter-field-guide.md
@@ -0,0 +1,263 @@
+# SooSeF Reporter Field Guide
+
+**Audience**: Reporters, field researchers, and documentarians using SooSeF to protect
+and verify their work. No technical background required.
+
+**Prerequisites**: A working SooSeF instance (Tier 1 USB or web UI access to a Tier 2
+server). Your IT admin should have set this up for you.
+
+---
+
+## What SooSeF Does For You
+
+SooSeF 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, SooSeF
+   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**
+
+SooSeF 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
+$ soosef 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
+$ soosef attest batch ./field-photos/ --caption "Site visit 2026-04-01"
+```
+
+### Checking Your Status
+
+Run `soosef 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
+$ soosef 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 SooSeF which platform. The
+app will recompress images, so SooSeF needs to use a survival-resistant encoding:
+
+```bash
+$ soosef stego encode photo.jpg -r shared.jpg -m "Safe house confirmed" --transport whatsapp
+$ soosef stego encode photo.jpg -r shared.jpg -m "Safe house confirmed" --transport signal
+$ soosef stego encode photo.jpg -r shared.jpg -m "Safe house confirmed" --transport telegram
+```
+
+> **Warning**: Never reuse the same carrier image twice. SooSeF will warn you if you
+> do. Comparing two versions of the same image trivially reveals steganographic changes.
+
+### Decoding a Message
+
+```bash
+$ soosef 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, SooSeF 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
+$ soosef 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
+$ soosef 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 SooSeF
+8. Python bytecache and pip metadata (to hide that SooSeF was installed)
+9. The SooSeF 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. SooSeF will remind you if your backup is overdue.
+
+### Creating a Backup
+
+```bash
+$ soosef keys export -o /media/usb/soosef-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 SooSeF device.
+
+### Restoring From Backup
+
+On a fresh SooSeF instance:
+
+```bash
+$ soosef init
+$ soosef keys import -b /media/usb/soosef-backup.enc
+```
+
+---
+
+## Evidence Packages
+
+When you need to hand evidence to a lawyer, a court, or a partner organization that does
+not use SooSeF:
+
+1. Go to the web UI or use the CLI to create an evidence package
+2. Select the photos to include
+3. SooSeF 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 SooSeF.
+
+---
+
+## 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
+(`soosef 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 SooSeF by name** in environments where your communications may be
+  monitored. If `cover_name` is configured, the tool presents itself under that name.
--- a/docs/training/reporter-quickstart.md
+++ b/docs/training/reporter-quickstart.md
@@ -0,0 +1,105 @@
+# Reporter Quick-Start Card
+
+**Audience**: Field reporters using a SooSeF 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 SooSeF. 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:
+
+```
+soosef 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 SooSeF 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