428750e971
README.md (608 lines): - Added 11 new feature sections: extract-then-strip EXIF, federation, timestamp anchoring, selective disclosure, evidence packages, cold archives, source drop box, key rotation/recovery, cover mode - Expanded steganography (transport-aware, carrier tracking), attestation (non-image files, investigation namespaces, derivation lineage), fieldkit (forensic scrub, webhook, self-uninstall) - Added Cross-Domain Applications section (human rights, research, elections, supply chain, art, whistleblowing, environment) - Updated CLI reference with chain anchor/disclose/export commands - Updated architecture with all new modules and data directory layout CLAUDE.md (155 lines): - Added metadata.py, evidence.py, archive.py, carrier_tracker.py, anchors.py, exchange.py, dropbox blueprint to architecture tree - Added 7 new design decisions (extract-then-strip, CSRF exemption, client-side hashing, ImageHashes generalization, lazy paths, two-way federation, chain record types) docs/deployment.md (1139 lines): - Added 5 new operational sections: source drop box setup, chain anchoring procedures, cross-org federation, evidence/archive workflows, cover/duress mode - Updated killswitch section with full 10-step destruction sequence - Updated config table with all new fields - Added 5 new troubleshooting entries Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
156 lines
7.9 KiB
Markdown
156 lines
7.9 KiB
Markdown
# 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.
|