From 06485879d2affe9870ce52cc3b062ff56f0382f4 Mon Sep 17 00:00:00 2001 From: "Aaron D. Lee" Date: Tue, 31 Mar 2026 14:21:30 -0400 Subject: [PATCH] Initial repo skeleton with pyproject.toml and project guide Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 76 ++++++++++++++++++++++++ pyproject.toml | 128 +++++++++++++++++++++++++++++++++++++++++ src/soosef/__init__.py | 14 +++++ 3 files changed, 218 insertions(+) create mode 100644 CLAUDE.md create mode 100644 pyproject.toml create mode 100644 src/soosef/__init__.py diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..e315524 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,76 @@ +# 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. diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..a1ba002 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,128 @@ +[build-system] +requires = ["hatchling"] +build-backend = "hatchling.build" + +[project] +name = "soosef" +version = "0.1.0" +description = "Soo Security Fieldkit — offline-first security toolkit for journalists, NGOs, and at-risk organizations" +readme = "README.md" +license = "MIT" +requires-python = ">=3.11" +authors = [ + { name = "Aaron D. Lee" } +] +keywords = [ + "steganography", + "provenance", + "attestation", + "security", + "privacy", + "fieldkit", + "airgap", + "offline", +] +classifiers = [ + "Development Status :: 2 - Pre-Alpha", + "Environment :: Console", + "Environment :: Web Environment", + "Intended Audience :: Developers", + "Intended Audience :: End Users/Desktop", + "License :: OSI Approved :: MIT License", + "Operating System :: OS Independent", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", + "Topic :: Security :: Cryptography", + "Topic :: Multimedia :: Graphics", +] + +dependencies = [ + "stegasoo>=4.3.0", + "verisoo>=0.1.0", + "pillow>=10.0.0", + "cryptography>=41.0.0", + "argon2-cffi>=23.0.0", +] + +[project.optional-dependencies] +web = [ + "flask>=3.0.0", + "gunicorn>=21.0.0", + # Stegasoo web extras + "stegasoo[web]", + # Verisoo storage + "lmdb>=1.4.0", + "imagehash>=4.3.0", + "exifread>=3.0.0", +] +cli = [ + "click>=8.0.0", + "rich>=13.0.0", + "stegasoo[cli]", + "verisoo[cli]", +] +fieldkit = [ + "watchdog>=4.0.0", + "pyudev>=0.24.0", +] +rpi = [ + "soosef[web,cli,fieldkit]", + "gpiozero>=2.0", +] +all = [ + "soosef[web,cli,fieldkit]", + "stegasoo[all]", + "verisoo[all]", +] +dev = [ + "soosef[all]", + "pytest>=7.0.0", + "pytest-cov>=4.0.0", + "black>=23.0.0", + "ruff>=0.1.0", + "mypy>=1.0.0", +] + +[project.scripts] +soosef = "soosef.cli:main" + +[project.urls] +Homepage = "https://github.com/alee/soosef" +Repository = "https://github.com/alee/soosef" + +[tool.hatch.build.targets.sdist] +include = [ + "/src", + "/frontends", +] + +[tool.hatch.build.targets.wheel] +packages = ["src/soosef", "frontends"] + +[tool.hatch.build.targets.wheel.sources] +"src" = "" + +[tool.pytest.ini_options] +testpaths = ["tests"] +python_files = ["test_*.py"] +addopts = "-v --cov=soosef --cov-report=term-missing" + +[tool.black] +line-length = 100 +target-version = ["py311", "py312", "py313"] + +[tool.ruff] +line-length = 100 + +[tool.ruff.lint] +select = ["E", "F", "I", "N", "W", "UP"] +ignore = ["E501"] + +[tool.mypy] +python_version = "3.11" +warn_return_any = true +warn_unused_configs = true +ignore_missing_imports = true diff --git a/src/soosef/__init__.py b/src/soosef/__init__.py new file mode 100644 index 0000000..7e3bf35 --- /dev/null +++ b/src/soosef/__init__.py @@ -0,0 +1,14 @@ +""" +SooSeF — Soo Security Fieldkit + +Offline-first security toolkit for journalists, NGOs, and at-risk organizations. +Combines Stegasoo (steganography) and Verisoo (provenance attestation) with +field-hardened security features. + +Part of the Soo Suite: +- Stegasoo: hide encrypted messages in media +- Verisoo: prove image provenance and authenticity +- SooSeF: unified fieldkit with killswitch, dead man's switch, and key management +""" + +__version__ = "0.1.0"