fieldwitness/CLAUDE.md

# SooSeF — Claude Code Project Guide

SooSeF (Soo Security Fieldkit) is an offline-first security toolkit for journalists, NGOs,
and at-risk organizations. Monorepo consolidating Stegasoo and Verisoo as subpackages.

Version 0.2.0 · Python >=3.11 · MIT License

## Quick commands

```bash
# Development install (single command — stegasoo and verisoo are inlined subpackages)
pip install -e ".[dev]"

pytest                                       # Run tests
black src/ tests/ frontends/                 # Format code
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__
  _availability.py           Runtime checks for optional subpackages (has_stegasoo, has_verisoo)
  api.py                     Optional unified FastAPI app (uvicorn soosef.api:app)
  audit.py                   Audit logging
  cli.py                     Click CLI entry point (soosef command)
  paths.py                   All ~/.soosef/* path constants (single source of truth)
  config.py                  Unified config loader
  exceptions.py              SoosefError base exception
  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)

  stegasoo/                Steganography engine (inlined from stegasoo)
    encode.py / decode.py      Core encode/decode API
    generate.py                Cover image generation
    crypto.py                  AES-256-GCM encryption
    channel.py                 Channel key derivation
    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
    cli.py                     Stegasoo-specific CLI commands
    api.py / api_auth.py       Stegasoo REST API + auth
    carrier_tracker.py         Carrier image reuse tracking (warns on reuse)
    image_utils.py / audio_utils.py / video_utils.py
    keygen.py / qr_utils.py / recovery.py / debug.py / utils.py
    platform_presets.py        Social-media-aware encoding presets

  verisoo/                 Provenance attestation engine (inlined from verisoo)
    attestation.py             Core attestation creation
    verification.py            Attestation verification
    crypto.py                  Ed25519 signing
    hashing.py                 Perceptual + cryptographic hashing
    embed.py                   Attestation embedding in images
    merkle.py                  Merkle tree for batch attestation
    binlog.py                  Binary attestation log
    lmdb_store.py              LMDB-backed trust store
    storage.py                 Attestation storage abstraction
    federation.py              Federated attestation exchange
    models.py                  Attestation, Verification dataclasses
    exceptions.py              Verisoo-specific exceptions
    cli.py                     Verisoo-specific CLI commands
    api.py                     Verisoo REST API

  federation/              Federated attestation chain system
    chain.py                   Hash chain construction + key rotation/recovery/delivery-ack records
    entropy.py                 Entropy source for chain seeds
    models.py                  ChainEntry, ChainState dataclasses
    serialization.py           CBOR chain serialization + export
    anchors.py                 RFC 3161 timestamps + manual chain anchors
    exchange.py                Cross-org attestation bundle export/import

  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

  fieldkit/                Field security features
    killswitch.py              Emergency data destruction
    deadman.py                 Dead man's switch
    tamper.py                  File integrity monitoring
    usb_monitor.py             USB device whitelist (Linux/pyudev)
    geofence.py                GPS boundary enforcement

frontends/web/             Unified Flask web UI
  app.py                     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 for stegasoo
  stego_worker.py            Background stego processing
  stego_routes.py            Stego route helpers
  ssl_utils.py               Self-signed HTTPS cert generation
  blueprints/
    stego.py                   /encode, /decode, /generate
    attest.py                  /attest, /verify
    fieldkit.py                /fieldkit/* (killswitch, deadman, status)
    keys.py                    /keys/* (unified key management)
    admin.py                   /admin/* (user management)
    dropbox.py                 /dropbox/* (token-gated anonymous source upload)
  templates/dropbox/
    admin.html                 Drop box admin panel

frontends/cli/             CLI package init (main entry point is src/soosef/cli.py)
```

## Dependency model

Stegasoo and Verisoo are inlined subpackages, not separate pip packages:
- `from soosef.stegasoo import encode` for steganography
- `from soosef.verisoo import Attestation` for provenance attestation
- Never `import stegasoo` or `import verisoo` directly
- `_availability.py` provides `has_stegasoo()` / `has_verisoo()` 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
- **Extract-then-strip model**: Stego strips all EXIF (carrier is vessel); attestation
  extracts evidentiary EXIF then strips dangerous fields (device serial, etc.)
- **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
- **Offline-first**: All static assets vendored, no CDN. pip wheels bundled for airgap install
- **Flask blueprints**: stego, attest, fieldkit, keys, admin, dropbox — clean route separation
- **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**: `soosef.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**: Modules use `import soosef.paths as _paths` for --data-dir support
- **Two-way federation**: Delivery acknowledgment records enable handshake proof
- **Chain record types**: CONTENT_TYPE_KEY_ROTATION, CONTENT_TYPE_KEY_RECOVERY,
  CONTENT_TYPE_DELIVERY_ACK (in federation/chain.py)

## Code conventions

Black (100-char), Ruff, mypy, imperative commit messages.