# SooSeF — 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.

Version 0.1.0 · Python >=3.11 · MIT 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]
pip install -e ".[dev]"

pytest                                       # Run tests
black src/ tests/ frontends/                 # Format code
ruff check src/ tests/ frontends/ --fix      # Lint
mypy src/                                    # Type check
```

## 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
  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 (from stegasoo)
  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
  blueprints/
    stego.py                   /encode, /decode, /generate (from stegasoo)
    attest.py                  /attest, /verify (wraps verisoo)
    fieldkit.py                /fieldkit/* (killswitch, deadman, status)
    keys.py                    /keys/* (unified key management)
    admin.py                   /admin/* (user management)

frontends/cli/             CLI entry point
  main.py                    Click CLI wrapping stegasoo + verisoo + soosef commands
```

## 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

## 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
- **Offline-first**: All static assets vendored, no CDN. pip wheels bundled for airgap install
- **Flask blueprints**: stego, attest, fieldkit, keys, admin — clean route separation

## Code conventions

Same as stegasoo: Black (100-char), Ruff, mypy, imperative commit messages.