7aeb26e003
CLAUDE.md gives Claude Code instant context on architecture, commands, conventions, security-critical modules, and public API surface. docs/CLAUDE_WORKTREES.md is a beginner-friendly guide to using Claude Code with git worktrees for isolated feature work. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
111 lines
5.3 KiB
Markdown
111 lines
5.3 KiB
Markdown
# Stegasoo — Claude Code Project Guide
|
|
|
|
Stegasoo is a secure steganography toolkit with hybrid photo + passphrase + PIN authentication.
|
|
Version 4.2.1 · Python >=3.11 · MIT License
|
|
|
|
## Quick commands
|
|
|
|
```bash
|
|
pip install -e ".[dev]" # Install for development (includes all extras)
|
|
pytest # Run tests (coverage reported automatically)
|
|
black src/ tests/ frontends/ # Format code
|
|
ruff check src/ tests/ frontends/ --fix # Lint (auto-fix)
|
|
mypy src/ # Type check
|
|
pre-commit run --all-files # Run all pre-commit hooks
|
|
PYTHONPATH=src python -m stegasoo.cli # Run CLI directly without install
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
src/stegasoo/ Core library
|
|
crypto.py Argon2id / PBKDF2 key derivation + AES-256-GCM encryption
|
|
steganography.py LSB spatial embedding
|
|
dct_steganography.py DCT domain embedding (JPEG-safe, needs [dct] extras)
|
|
validation.py Input validation for all security factors
|
|
constants.py All magic numbers, crypto params, limits
|
|
models.py Dataclasses (EncodeResult, DecodeResult, etc.)
|
|
encode.py / decode.py High-level encode/decode orchestration
|
|
channel.py Channel key management (v4.0+)
|
|
compression.py Zstandard / zlib / lz4 payload compression
|
|
cli.py Click CLI entry point
|
|
generate.py Credential generation (passphrase, PIN, RSA keys)
|
|
exceptions.py Exception hierarchy (all inherit StegasooError)
|
|
__init__.py Public API surface (__all__)
|
|
|
|
frontends/web/ Flask web UI (entry: app.py)
|
|
frontends/api/ FastAPI REST API (entry: main.py)
|
|
frontends/cli/ CLI extras
|
|
|
|
tests/ Pytest suite
|
|
test_stegasoo.py Single test file covering core library
|
|
```
|
|
|
|
### Entry points
|
|
|
|
| Interface | Entry point | Install extra |
|
|
|-----------|-------------|---------------|
|
|
| CLI | `stegasoo.cli:main` (`stegasoo` command) | `[cli]` |
|
|
| Web UI | `frontends/web/app.py` | `[web]` |
|
|
| REST API | `frontends/api/main.py` | `[api]` |
|
|
|
|
## Code conventions
|
|
|
|
- **Formatter**: Black, 100-char line length
|
|
- **Linter**: Ruff — rules E, F, I, N, W, UP (E501 ignored). N803/N806 suppressed in `dct_steganography.py` for colorspace variable names
|
|
- **Type hints**: Required on all new code. `mypy` with `ignore_missing_imports = true`
|
|
- **Pre-commit hooks**: ruff, ruff-format, trailing-whitespace, end-of-file-fixer, check-yaml, check-toml, check-added-large-files (1MB), check-merge-conflict, debug-statements, bandit (excludes tests/)
|
|
- **Branch naming**: `feature/`, `fix/`, `docs/`, `refactor/`
|
|
- **Commits**: Imperative mood, clear subject line. Include what + why
|
|
|
|
## Security-critical modules
|
|
|
|
These files implement the cryptographic and steganographic core. Changes require extra care, thorough test coverage, and careful review:
|
|
|
|
- **`crypto.py`** — Argon2id KDF (256 MB / 4 iterations / 4 parallelism) + PBKDF2 fallback (600K iterations) → AES-256-GCM authenticated encryption
|
|
- **`steganography.py`** — LSB spatial embedding/extraction
|
|
- **`dct_steganography.py`** — DCT domain embedding with Reed-Solomon error correction
|
|
- **`validation.py`** — Input validation for all security factors (PIN, passphrase, image, RSA key, channel key)
|
|
- **`constants.py`** — Crypto parameters (salt sizes, iteration counts, Argon2 memory cost, format versions). Do not change these casually — they affect backward compatibility and security margins
|
|
|
|
## Public API
|
|
|
|
`src/stegasoo/__init__.py` defines the full public API surface via `__all__`. Any new public function must be:
|
|
1. Imported in `__init__.py`
|
|
2. Added to the `__all__` list
|
|
|
|
## Testing
|
|
|
|
- Single test file: `tests/test_stegasoo.py`
|
|
- Requires `pip install -e ".[dev]"` (includes DCT dependencies)
|
|
- Coverage is reported automatically via pytest config (`--cov=stegasoo --cov-report=term-missing`)
|
|
- Run: `pytest` (no extra flags needed)
|
|
|
|
## Worktree workflow
|
|
|
|
When working on features or fixes that touch multiple files, prefer using a git worktree for isolation:
|
|
|
|
```bash
|
|
# Claude Code can create worktrees automatically via /worktree or EnterWorktree
|
|
# Manual creation:
|
|
git worktree add .claude/worktrees/<name> -b <branch-name>
|
|
```
|
|
|
|
### Guidelines for worktree usage
|
|
|
|
- **Use worktrees for**: multi-file refactors, experimental changes, anything that might need to be discarded
|
|
- **Worktree location**: `.claude/worktrees/` (gitignored by Claude Code)
|
|
- **Branch from**: always branch from `main` unless working on a version branch (e.g., `4.2`)
|
|
- **Naming**: use the same conventions as branches — `feature/description`, `fix/description`, etc.
|
|
- **Cleanup**: worktrees in `.claude/worktrees/` are ephemeral. Remove with `git worktree remove <path>` when done
|
|
- **Testing in worktrees**: run `pip install -e ".[dev]"` inside the worktree before running tests, since the editable install points to the worktree's source
|
|
- **Merging back**: create a PR from the worktree branch, or merge locally into `main`
|
|
|
|
## Useful context
|
|
|
|
- BIP-39 wordlist lives at `src/stegasoo/data/bip39-words.txt` (used for passphrase generation)
|
|
- Docker support: `src/stegasoo/Dockerfile` + `docs/DOCKER_QUICKSTART.md`
|
|
- Raspberry Pi builds: `rpi/` directory
|
|
- AUR packages: `aur/`, `aur-cli/`, `aur-api/`
|
|
- Version is defined in both `pyproject.toml` and `src/stegasoo/__init__.py` — keep them in sync
|