stegasoo/CLAUDE.md

Stegasoo — Claude Code Project Guide

Stegasoo is a secure steganography toolkit with hybrid photo + passphrase + PIN authentication. Version 4.3.0 · Python >=3.11 · MIT License

Quick commands

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+)
  audio_steganography.py  LSB audio embedding/extraction (v4.3.0)
  spread_steganography.py Spread spectrum audio embedding (v4.3.0)
  audio_utils.py          Audio format detection, validation, transcoding (v4.3.0)
  debug.py                Structured logging for operations (v4.3.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:

# 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