Aaron D. Lee 06485879d2 Initial repo skeleton with pyproject.toml and project guide

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-31 14:21:30 -04:00

3.3 KiB

Raw Blame History

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

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

3.3 KiB Raw Blame History