# 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