Prepare 4.1.2 release documentation

- Add 4.1.2 changelog: Docker, Pi wizard, unit tests, validation script - Add Raspberry Pi section to README with first-boot wizard info - Document new features: TUI setup, overclock presets, sanitize scripts 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update RPi banner styling: purple→blue gradient + gold logo
2026-01-05 22:10:02 -05:00 · 2026-01-05 22:06:35 -05:00 · 2026-01-05 22:00:01 -05:00 · 2026-01-05 21:53:42 -05:00 · 2026-01-05 21:32:41 -05:00 · 2026-01-05 21:30:35 -05:00
116 changed files with 14812 additions and 7363 deletions
--- a/.dockerignore
+++ b/.dockerignore
@@ -0,0 +1,39 @@
 # Git
 .git
 .gitignore
 # Python
 __pycache__
 *.py[cod]
 *.egg-info
 .eggs
 venv/
 .venv/
 # Instance data (user creates fresh)
 frontends/web/instance/
 frontends/web/certs/
 instance/
 # Test data
 test_data/
 tests/
 # Pi-specific
 rpi/
 *.img
 *.img.zst
 *.img.zst.zip
 # Docs
 *.md
 docs/
 # IDE
 .vscode/
 .idea/
 # Misc
 *.log
 *.tmp
 .DS_Store
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,98 @@
 name: Bug Report
 description: Report a bug or unexpected behavior
 title: "[Bug]: "
 labels: ["bug", "triage"]
 body:
  - type: markdown
    attributes:
      value: |
        Thanks for taking the time to report a bug! Please fill out the form below.
  - type: textarea
    id: description
    attributes:
      label: Bug Description
      description: A clear and concise description of what the bug is.
      placeholder: Describe the bug...
    validations:
      required: true
  - type: textarea
    id: reproduction
    attributes:
      label: Steps to Reproduce
      description: Steps to reproduce the behavior.
      placeholder: |
        1. Run command '...'
        2. Upload image '...'
        3. See error
    validations:
      required: true
  - type: textarea
    id: expected
    attributes:
      label: Expected Behavior
      description: What did you expect to happen?
    validations:
      required: true
  - type: textarea
    id: actual
    attributes:
      label: Actual Behavior
      description: What actually happened?
    validations:
      required: true
  - type: dropdown
    id: interface
    attributes:
      label: Interface
      description: Which interface are you using?
      options:
        - CLI
        - Web UI
        - REST API
        - Python Library
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Stegasoo Version
      description: Run `stegasoo --version` or check the web UI footer
      placeholder: "4.0.1"
    validations:
      required: true
  - type: input
    id: python-version
    attributes:
      label: Python Version
      description: Run `python --version`
      placeholder: "3.11.0"
    validations:
      required: true
  - type: input
    id: os
    attributes:
      label: Operating System
      placeholder: "Ubuntu 22.04 / Windows 11 / macOS 14"
    validations:
      required: true
  - type: textarea
    id: logs
    attributes:
      label: Error Logs
      description: Paste any relevant error messages or tracebacks.
      render: shell
  - type: textarea
    id: additional
    attributes:
      label: Additional Context
      description: Add any other context, screenshots, or files here.
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
 blank_issues_enabled: true
 contact_links:
  - name: Security Vulnerability
    url: https://github.com/adlee-was-taken/stegasoo/security/advisories/new
    about: Report security vulnerabilities privately
  - name: Documentation
    url: https://github.com/adlee-was-taken/stegasoo#readme
    about: Check the documentation before opening an issue
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -0,0 +1,62 @@
 name: Feature Request
 description: Suggest a new feature or enhancement
 title: "[Feature]: "
 labels: ["enhancement"]
 body:
  - type: markdown
    attributes:
      value: |
        Thanks for suggesting a feature! Please fill out the form below.
  - type: textarea
    id: problem
    attributes:
      label: Problem Statement
      description: Is your feature request related to a problem? Describe it.
      placeholder: I'm always frustrated when...
    validations:
      required: true
  - type: textarea
    id: solution
    attributes:
      label: Proposed Solution
      description: Describe the solution you'd like.
      placeholder: I would like to be able to...
    validations:
      required: true
  - type: textarea
    id: alternatives
    attributes:
      label: Alternatives Considered
      description: Describe any alternative solutions or features you've considered.
  - type: dropdown
    id: interface
    attributes:
      label: Affected Interface(s)
      description: Which interface(s) would this feature affect?
      multiple: true
      options:
        - CLI
        - Web UI
        - REST API
        - Python Library
        - Core Library
  - type: dropdown
    id: priority
    attributes:
      label: Priority
      description: How important is this feature to you?
      options:
        - Nice to have
        - Would improve my workflow
        - Critical for my use case
  - type: textarea
    id: context
    attributes:
      label: Additional Context
      description: Add any other context, mockups, or examples here.
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,46 @@
 ## Description
 <!-- Describe your changes in detail -->
 ## Type of Change
 <!-- Mark the relevant option with an 'x' -->
 - [ ] Bug fix (non-breaking change that fixes an issue)
 - [ ] New feature (non-breaking change that adds functionality)
 - [ ] Breaking change (fix or feature that would cause existing functionality to change)
 - [ ] Documentation update
 - [ ] Refactoring (no functional changes)
 - [ ] CI/CD or build changes
 ## Related Issues
 <!-- Link any related issues here -->
 Fixes #
 ## Testing
 <!-- Describe how you tested your changes -->
 - [ ] I have added tests that prove my fix/feature works
 - [ ] Existing tests pass locally with my changes
 - [ ] I have tested manually (describe below)
 ### Manual Testing Steps
 <!-- If applicable, describe manual testing performed -->
 ## Checklist
 - [ ] My code follows the project's style guidelines
 - [ ] I have performed a self-review of my code
 - [ ] I have commented my code, particularly in hard-to-understand areas
 - [ ] I have updated the documentation accordingly
 - [ ] I have updated CHANGELOG.md (if user-facing changes)
 - [ ] My changes generate no new warnings
 - [ ] Any dependent changes have been merged and published
 ## Screenshots
 <!-- If applicable, add screenshots to help explain your changes -->
--- a/.gitignore
+++ b/.gitignore
@@ -35,6 +35,12 @@ old_files/
 *.swp
 *.swo
 # Backup files
 *_old
 *_old.*
 *.bak
 *.orig
 # Testing
 .pytest_cache/
 .coverage
@@ -48,7 +54,7 @@ htmlcov/
 # Environment
 .env
-.env.*
+.env.local
 *.log
 # Distribution
@@ -58,6 +64,19 @@ htmlcov/
 # Output test files.
 test_data/*.png
-#Project root scripts.
+# Dev scripts (local convenience scripts - except validate-release.sh)
-rbld_containers.sh
+scripts/*
-quick_web.sh
+!scripts/validate-release.sh
 # Web UI auth database and SSL certs
 frontends/web/instance/
 frontends/web/certs/
 # Tests (private)
 tests/
 # RPi image build artifacts
 *.img
 *.img.xz
 *.img.zst
 pishrink.sh
--- a/.python-version
+++ b/.python-version
@@ -1 +1 @@
-3.12.0
+3.12
--- a/API.md
+++ b/API.md
@@ -1,4 +1,4 @@
-# Stegasoo REST API Documentation (v4.0.1)
+# Stegasoo REST API Documentation (v4.0.2)
 Complete REST API reference for Stegasoo steganography operations.
@@ -113,7 +113,7 @@ Check API status and configuration.
 ```json
 {
-  "version": "4.0.1",
+  "version": "4.0.2",
  "has_argon2": true,
  "has_qrcode_read": true,
  "has_dct": true,
@@ -462,7 +462,7 @@ X-Stegasoo-Capacity-Percent: 12.4
 X-Stegasoo-Embed-Mode: lsb
 X-Stegasoo-Channel-Mode: private
 X-Stegasoo-Channel-Fingerprint: ABCD-••••-...-3456
-X-Stegasoo-Version: 4.0.1
+X-Stegasoo-Version: 4.0.2
 <binary image data>
 ```
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -0,0 +1,189 @@
 # Changelog
 All notable changes to Stegasoo will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org).
 ## [4.1.2] - 2026-01-05
 ### Added
 - **Docker Deployment**: Production-ready containerization
  - `docker-compose.yml` for Web UI (port 5000) and REST API (port 8000)
  - Multi-stage builds with base image for faster rebuilds
  - Health checks, resource limits (768MB), and volume persistence
  - Comprehensive `DOCKER.md` documentation
 - **Raspberry Pi First-Boot Wizard**: Interactive TUI setup experience
  - `gum` TUI toolkit for styled prompts and spinners
  - WiFi configuration, HTTPS setup, channel key generation
  - Overclock presets (Pi 5: 2.8/3.0 GHz with cooling recommendations)
  - Port 443 redirect option for clean HTTPS URLs
  - Styled banners with purple→blue gradient and gold logo
 - **Pi Image Distribution**: Scripts for SD card imaging
  - `sanitize-for-image.sh` removes credentials, SSH keys, user data
  - Soft reset mode for testing without clearing WiFi
  - Auto-validates sanitization before imaging
 - **Unit Tests**: Comprehensive pytest test suite
  - Tests for encode/decode, LSB/DCT modes, channel keys
  - Validation, generation, compression, edge cases
  - 29 tests covering core library functionality
 - **Release Validation**: `scripts/validate-release.sh` for pre-release checks
 ### Changed
 - Pi MOTD shows CPU speed and temperature when overclocked
 - Mobile UI polish and responsive improvements
 - Standardized ASCII banners across all Pi scripts
 - Setup script uses pyenv for Python 3.12 (Pi OS ships 3.13)
 ### Fixed
 - DCT decode reliability improvements
 - Fixed `gum --inline` flag compatibility (not supported in all versions)
 - Wizard banner alignment and spacing issues
 ## [4.1.0] - 2026-01-04
 ### Added
 - **Admin Recovery System**: Password reset for locked-out admins
  - Recovery key generated during setup (32-char alphanumeric)
  - Multiple backup options: text file, QR code, stego image
  - QR codes obfuscated (XOR'd with magic header hash)
  - Stego backups hide key in an image using Stegasoo itself
  - CLI: `stegasoo admin recover --db path/to/db`
 - **EXIF Editor**: Full metadata editing in Tools page
  - View all EXIF fields from uploaded image
  - Inline editing of individual fields
  - Clear all metadata with one click
  - Download cleaned image
  - CLI: `stegasoo tools exif image.jpg [--clear] [--set Field=Value]`
 - **Multi-User Support**: Admin can create up to 16 additional users
  - Role-based access control (admin/user)
  - Admin user management page
  - Temp password generation for new users
 - **Saved Channel Keys**: Users can save/manage channel keys in account page
 ### Changed
 - **Architecture**: Consolidated `resolve_channel_key()` to library layer
  - Single source of truth in `src/stegasoo/channel.py`
  - CLI, API, WebUI now use thin wrappers
 - **DCT Pre-Check**: Fail fast with helpful error before expensive encoding
 - **Toast Notifications**: Auto-dismiss after 20 seconds with fade animation
 - `RECOVERY_OBFUSCATION_KEY` constant added to `constants.py`
 ### Fixed
 - DCT payload size error now caught early with clear message
 ## [4.0.2] - 2026-01-02
 ### Added
 - **Web UI Authentication**: Single-admin login with SQLite3 user storage
  - First-run setup wizard for admin account creation
  - Account management page for password changes
  - `@login_required` decorator protects encode/decode/generate routes
  - Argon2id password hashing (lighter 64MB for fast login)
 - **Optional HTTPS**: Auto-generated self-signed certificates for home network deployment
  - Configurable via `STEGASOO_HTTPS_ENABLED` environment variable
  - Certificates stored in `frontends/web/certs/`
 - New environment variables: `STEGASOO_AUTH_ENABLED`, `STEGASOO_HTTPS_ENABLED`, `STEGASOO_HOSTNAME`
 ### Changed
 - PIN entry column widened in encode/decode forms (col-md-4 → col-md-6)
 - Channel options column narrowed (col-md-8 → col-md-6)
 - QR preview panels enlarged for better text readability
 - Consistent font sizing across all preview panel banners (0.7rem filename, 0.6rem data, 0.65rem badges)
 ### Fixed
 - QR preview text too small to read in encode/decode templates
 - Inconsistent label sizes between reference/carrier/stego panels
 ## [4.0.1] - 2025-01-02
 ### Fixed
 - Fixed numpy binary incompatibility on Python 3.10 (jpegio/scipy)
 - Fixed BatchCredentials test failures with missing `reference_photo` parameter
 - Graceful handling when DCT dependencies have version mismatches
 ### Changed
 - Applied `ruff` linter fixes across entire codebase (~400 issues)
 - Applied `black` formatter to all Python files
 - Modernized type hints: `Optional[X]` → `X | None`
 - Updated ruff config to use `[tool.ruff.lint]` section
 - Moved documentation files to repository root
 ### Removed
 - Removed obsolete debug/diagnostic scripts
 - Cleaned up backup files and dev scripts
 ## [4.0.0] - 2024-12-29
 ### Added
 - Refreshed Web UI with modern, snazzy interface
 - Improved user experience across all pages
 ### Changed
 - Major version bump for breaking API changes
 - Simplified passphrase handling (single passphrase instead of day-based)
 - Removed date_str parameter from encoding
 ### Fixed
 - Various bug fixes for Web UI
 - CLI updates and improvements
 ## [3.2.0] - 2024-12-28
 ### Added
 - Big revamp of the encoding system
 - Home and about page improvements
 - UNDER_THE_HOOD.md documentation
 ### Changed
 - Renamed `phrase` → `passphrase` in API
 - Updated Web UI styling
 ## [3.0.2] - 2024-12-27
 ### Added
 - Full experimental DCT steganography support
 - jpegio integration for better JPEG manipulation
 - DCT/LSB mode selector in Web UI
 ## [3.0.0] - 2024-12-25
 ### Added
 - DCT (Discrete Cosine Transform) steganography mode
 - Support for JPEG carriers without quality loss
 - Channel key feature for private messaging
 ### Changed
 - Complete rewrite of steganography engine
 - New hybrid authentication system
 ## [2.0.0] - 2024-12-20
 ### Added
 - Web UI frontend
 - REST API (FastAPI)
 - Batch processing support
 - RSA key authentication option
 ### Changed
 - Migrated to hybrid photo + passphrase + PIN authentication
 ## [1.0.0] - 2024-12-15
 ### Added
 - Initial release
 - LSB steganography
 - AES-256-GCM encryption
 - CLI interface
 - Basic PIN authentication
 [4.1.2]: https://github.com/adlee-was-taken/stegasoo/compare/v4.1.0...v4.1.2
 [4.1.0]: https://github.com/adlee-was-taken/stegasoo/compare/v4.0.2...v4.1.0
 [4.0.2]: https://github.com/adlee-was-taken/stegasoo/compare/v4.0.1...v4.0.2
 [4.0.1]: https://github.com/adlee-was-taken/stegasoo/compare/v4.0.0...v4.0.1
 [4.0.0]: https://github.com/adlee-was-taken/stegasoo/compare/v3.2.0...v4.0.0
 [3.2.0]: https://github.com/adlee-was-taken/stegasoo/compare/v3.0.2...v3.2.0
 [3.0.2]: https://github.com/adlee-was-taken/stegasoo/compare/v3.0.0...v3.0.2
 [3.0.0]: https://github.com/adlee-was-taken/stegasoo/compare/v2.0.0...v3.0.0
 [2.0.0]: https://github.com/adlee-was-taken/stegasoo/compare/v1.0.0...v2.0.0
 [1.0.0]: https://github.com/adlee-was-taken/stegasoo/releases/tag/v1.0.0
--- a/CLI.md
+++ b/CLI.md
@@ -1,11 +1,11 @@
-# Stegasoo CLI Documentation (v4.0.1)
+# Stegasoo CLI Documentation (v4.1.0)
 Complete command-line interface reference for Stegasoo steganography operations.
 ## Table of Contents
 - [Installation](#installation)
- [What's New in v4.0.0](#whats-new-in-v400)
+- [What's New in v4.1.0](#whats-new-in-v410)
 - [Quick Start](#quick-start)
 - [Commands](#commands)
  - [generate](#generate-command)
@@ -13,10 +13,11 @@ Complete command-line interface reference for Stegasoo steganography operations.
  - [decode](#decode-command)
  - [verify](#verify-command)
  - [channel](#channel-command)
  - [admin](#admin-command)
  - [tools](#tools-command)
  - [info](#info-command)
  - [compare](#compare-command)
  - [modes](#modes-command)
  - [strip-metadata](#strip-metadata-command)
 - [Channel Keys](#channel-keys)
 - [Embedding Modes](#embedding-modes)
 - [Security Factors](#security-factors)
@@ -65,9 +66,28 @@ stegasoo channel show
 ---
 ## What's New in v4.1.0
 Version 4.1.0 adds **admin recovery** and **tools** commands:
 | Feature | Description |
 |---------|-------------|
 | Admin recovery | Reset admin password using recovery key |
 | EXIF tools | View, edit, and strip image metadata |
 | Peek tool | Quick stego detection check |
 | Strip tool | Remove hidden data from images |
 **New commands:**
 - `stegasoo admin recover` - Reset admin password with recovery key
 - `stegasoo tools exif` - View/edit EXIF metadata
 - `stegasoo tools peek` - Check for hidden data
 - `stegasoo tools strip` - Remove stego data from image
 ---
 ## What's New in v4.0.0
-Version 4.0.0 adds **channel key** support for deployment/group isolation:
+Version 4.0.0 added **channel key** support for deployment/group isolation:
 | Feature | Description |
 |---------|-------------|
@@ -76,14 +96,6 @@ Version 4.0.0 adds **channel key** support for deployment/group isolation:
 | CLI management | New `stegasoo channel` command group |
 | Flexible override | Use server config, explicit key, or public mode |
 **Key benefits:**
 - ✅ Isolate messages between teams, deployments, or groups
 - ✅ Same credentials can't decode messages from different channels
 - ✅ Backward compatible (public mode = no channel key)
 - ✅ Easy key distribution via environment variables or config files
 **Breaking change:** v4.0.0 messages (with channel key) cannot be decoded by v3.x installations.
 ---
 ## Quick Start
@@ -495,12 +507,150 @@ Now also displays channel key status.
 ---
-### Strip-Metadata Command
+### Admin Command
-Remove all metadata from an image.
+Manage Web UI admin accounts and recovery.
 #### Subcommands
 | Subcommand | Description |
 |------------|-------------|
 | `recover` | Reset admin password using recovery key |
 #### admin recover
 Reset the admin password for a Web UI database.
 ```bash
-stegasoo strip-metadata IMAGE [OPTIONS]
+stegasoo admin recover --db PATH [OPTIONS]
 ```
 | Option | Short | Type | Required | Description |
 |--------|-------|------|----------|-------------|
 | `--db` | `-d` | path | ✓ | Path to stegasoo.db file |
 | `--key` | `-k` | string | | Recovery key (prompted if not provided) |
 | `--password` | `-p` | string | | New password (prompted if not provided) |
 **Examples:**
 ```bash
 # Interactive mode (prompts for key and password)
 stegasoo admin recover --db frontends/web/instance/stegasoo.db
 # Non-interactive mode
 stegasoo admin recover \
  --db /path/to/stegasoo.db \
  --key "XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX" \
  --password "NewSecurePassword123"
 ```
 **Recovery process:**
 1. The recovery key is verified against the database hash
 2. If valid, the admin password is reset
 3. User can now log in with the new password
 **Note:** Recovery keys are instance-bound. A key from one database won't work on another.
 ---
 ### Tools Command
 Image utilities and analysis tools.
 #### Subcommands
 | Subcommand | Description |
 |------------|-------------|
 | `exif` | View/edit EXIF metadata |
 | `peek` | Check for hidden data |
 | `strip` | Remove stego data from image |
 #### tools exif
 View and edit EXIF metadata in images.
 ```bash
 stegasoo tools exif IMAGE [OPTIONS]
 ```
 | Option | Type | Description |
 |--------|------|-------------|
 | `--clear` | flag | Remove all EXIF metadata |
 | `--set FIELD=VALUE` | string | Set a specific EXIF field |
 | `--output` / `-o` | path | Output filename (default: overwrites input) |
 | `--json` | flag | Output as JSON |
 **Examples:**
 ```bash
 # View all EXIF data
 stegasoo tools exif photo.jpg
 # View as JSON
 stegasoo tools exif photo.jpg --json
 # Clear all metadata
 stegasoo tools exif photo.jpg --clear -o clean.jpg
 # Set specific fields
 stegasoo tools exif photo.jpg \
  --set "Artist=John Doe" \
  --set "Copyright=2026" \
  -o tagged.jpg
 # Remove GPS data only
 stegasoo tools exif photo.jpg \
  --set "GPSLatitude=" \
  --set "GPSLongitude=" \
  -o no-gps.jpg
 ```
 #### tools peek
 Check if an image contains hidden Stegasoo data.
 ```bash
 stegasoo tools peek IMAGE [OPTIONS]
 ```
 | Option | Type | Description |
 |--------|------|-------------|
 | `--json` | flag | Output as JSON |
 | `--quiet` / `-q` | flag | Exit code only (0=found, 1=not found) |
 **Examples:**
 ```bash
 # Check for hidden data
 stegasoo tools peek suspicious.png
 # Script-friendly check
 if stegasoo tools peek image.png -q; then
  echo "Contains hidden data"
 fi
 ```
 #### tools strip
 Remove hidden stego data from an image (destructive).
 ```bash
 stegasoo tools strip IMAGE [OPTIONS]
 ```
 | Option | Type | Description |
 |--------|------|-------------|
 | `--output` / `-o` | path | Output filename |
 | `--force` / `-f` | flag | Overwrite without confirmation |
 **Examples:**
 ```bash
 # Strip and save to new file
 stegasoo tools strip stego.png -o clean.png
 # Strip in place (with confirmation)
 stegasoo tools strip stego.png
 ```
 ---
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,54 @@
 # Code of Conduct
 ## Our Pledge
 We as members, contributors, and leaders pledge to make participation in our
 community a harassment-free experience for everyone, regardless of age, body
 size, visible or invisible disability, ethnicity, sex characteristics, gender
 identity and expression, level of experience, education, socio-economic status,
 nationality, personal appearance, race, religion, or sexual identity
 and orientation.
 We pledge to act and interact in ways that contribute to an open, welcoming,
 diverse, inclusive, and healthy community.
 ## Our Standards
 Examples of behavior that contributes to a positive environment:
 * Using welcoming and inclusive language
 * Being respectful of differing viewpoints and experiences
 * Gracefully accepting constructive criticism
 * Focusing on what is best for the community
 * Showing empathy towards other community members
 Examples of unacceptable behavior:
 * The use of sexualized language or imagery, and sexual attention or advances
 * Trolling, insulting or derogatory comments, and personal or political attacks
 * Public or private harassment
 * Publishing others' private information without explicit permission
 * Other conduct which could reasonably be considered inappropriate
 ## Enforcement Responsibilities
 Project maintainers are responsible for clarifying and enforcing our standards
 of acceptable behavior and will take appropriate and fair corrective action in
 response to any behavior that they deem inappropriate, threatening, offensive,
 or harmful.
 ## Scope
 This Code of Conduct applies within all community spaces, and also applies when
 an individual is officially representing the community in public spaces.
 ## Enforcement
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the project maintainers. All complaints will be reviewed and
 investigated promptly and fairly.
 ## Attribution
 This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
 version 2.0.
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -0,0 +1,165 @@
 # Contributing to Stegasoo
 Thank you for your interest in contributing to Stegasoo! This document provides guidelines and information for contributors.
 ## Getting Started
 ### Prerequisites
 - Python 3.10 or higher
 - Git
 - Docker (optional, for container testing)
 ### Development Setup
 1. **Clone the repository**
   ```bash
   git clone https://github.com/adlee-was-taken/stegasoo.git
   cd stegasoo
   ```
 2. **Create a virtual environment**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```
 3. **Install development dependencies**
   ```bash
   pip install -e ".[dev]"
   ```
 4. **Install pre-commit hooks**
   ```bash
   pre-commit install
   ```
 ## Development Workflow
 ### Code Style
 We use the following tools to maintain code quality:
 - **Black** - Code formatting (line length: 100)
 - **Ruff** - Linting
 - **MyPy** - Type checking
 Run all checks before committing:
 ```bash
 black src/ tests/ frontends/
 ruff check src/ tests/ frontends/
 mypy src/
 ```
 ### Running Tests
 ```bash
 # Run all tests
 pytest
 # Run with coverage
 pytest --cov=stegasoo --cov-report=term-missing
 # Run specific test file
 pytest tests/test_stegasoo.py
 ```
 ### Type Hints
 All new code should include type hints:
 ```python
 def encode_message(
    message: str,
    carrier_image: bytes,
    passphrase: str,
    pin: str = "",
 ) -> EncodeResult:
    ...
 ```
 ## Making Changes
 ### Branch Naming
 - `feature/description` - New features
 - `fix/description` - Bug fixes
 - `docs/description` - Documentation updates
 - `refactor/description` - Code refactoring
 ### Commit Messages
 Write clear, concise commit messages:
 ```
 Add channel key validation for private messaging
 - Implement validate_channel_key() function
 - Add tests for valid/invalid key formats
 - Update CLI to support --channel-key flag
 ```
 ### Pull Request Process
 1. **Create a feature branch** from `main`
 2. **Make your changes** with appropriate tests
 3. **Ensure all checks pass** (tests, linting, formatting)
 4. **Submit a PR** with a clear description
 5. **Address review feedback** promptly
 ### PR Checklist
 - [ ] Tests added/updated for changes
 - [ ] Documentation updated if needed
 - [ ] CHANGELOG.md updated for user-facing changes
 - [ ] All CI checks passing
 - [ ] No merge conflicts with `main`
 ## Project Structure
 ```
 stegasoo/
 ├── src/stegasoo/       # Core library
 │   ├── crypto.py       # Encryption/decryption
 │   ├── steganography.py # LSB embedding
 │   ├── dct_steganography.py # DCT embedding
 │   └── ...
 ├── frontends/
 │   ├── cli/            # Command-line interface
 │   ├── web/            # Flask web UI
 │   └── api/            # FastAPI REST API
 ├── tests/              # Test suite
 └── examples/           # Usage examples
 ```
 ## Reporting Issues
 ### Bug Reports
 Please include:
 - Python version and OS
 - Stegasoo version (`stegasoo --version`)
 - Minimal reproduction steps
 - Expected vs actual behavior
 - Error messages/tracebacks
 ### Feature Requests
 Please include:
 - Use case description
 - Proposed solution (if any)
 - Alternatives considered
 ## Security
 If you discover a security vulnerability, please see [SECURITY.md](SECURITY.md) for responsible disclosure guidelines. **Do not open a public issue for security vulnerabilities.**
 ## License
 By contributing, you agree that your contributions will be licensed under the MIT License.
 ## Questions?
 Feel free to open a discussion or issue if you have questions about contributing.
 Thank you for helping make Stegasoo better!
--- a/DOCKER.md
+++ b/DOCKER.md
@@ -0,0 +1,153 @@
 # Docker Deployment
 Stegasoo provides Docker images for both the Web UI and REST API.
 ## Quick Start
 ```bash
 # Build and start all services
 docker-compose up -d
 # Check status
 docker-compose ps
 ```
 Access:
 - **Web UI**: http://localhost:5000
 - **REST API**: http://localhost:8000
 ## Services
 | Service | Port | Description |
 |---------|------|-------------|
 | `web` | 5000 | Flask Web UI with authentication |
 | `api` | 8000 | FastAPI REST API |
 ## Configuration
 ### Environment Variables
 Create a `.env` file or set these variables:
 ```bash
 # Channel key for private group communication (optional)
 STEGASOO_CHANNEL_KEY=XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX
 # Web UI authentication (default: enabled)
 STEGASOO_AUTH_ENABLED=true
 # HTTPS support (default: disabled)
 STEGASOO_HTTPS_ENABLED=false
 STEGASOO_HOSTNAME=localhost
 ```
 ### Volume Mounts
 Persistent data is stored in Docker volumes:
 | Volume | Purpose |
 |--------|---------|
 | `stegasoo-web-data` | User database, session data |
 | `stegasoo-web-certs` | SSL certificates (if HTTPS enabled) |
 ## Building
 ### Standard Build (Recommended)
 Uses a pre-built base image with all dependencies:
 ```bash
 # First time only: build the base image
 docker build -f Dockerfile.base -t stegasoo-base:latest .
 # Build services (fast - only copies app code)
 docker-compose build
 ```
 ### Full Build (No Base Image)
 If you don't have the base image, the Dockerfile will build all dependencies (slower):
 ```bash
 docker-compose build
 ```
 ## Commands
 ```bash
 # Start services
 docker-compose up -d
 # View logs
 docker-compose logs -f
 # Stop services
 docker-compose down
 # Rebuild after code changes
 docker-compose build && docker-compose up -d
 # Full rebuild (no cache)
 docker-compose build --no-cache
 ```
 ## Resource Limits
 Each container is configured with:
 - **Memory limit**: 768 MB
 - **Memory reservation**: 384 MB
 This accounts for Argon2id's 256 MB RAM requirement during key derivation.
 ## Health Checks
 Both services include health checks:
 - Interval: 30 seconds
 - Timeout: 10 seconds
 - Start period: 5 seconds
 - Retries: 3
 Check health status:
 ```bash
 docker-compose ps
 ```
 ## Production Deployment
 For production, consider:
 1. **Enable HTTPS**:
   ```bash
   STEGASOO_HTTPS_ENABLED=true
   STEGASOO_HOSTNAME=your-domain.com
   ```
 2. **Use secrets for channel key**:
   ```bash
   # Don't commit .env files with secrets
   export STEGASOO_CHANNEL_KEY=your-key
   docker-compose up -d
   ```
 3. **Reverse proxy**: Put behind nginx/traefik for TLS termination
 4. **Backup volumes**:
   ```bash
   docker run --rm -v stegasoo-web-data:/data -v $(pwd):/backup \
     alpine tar czf /backup/stegasoo-backup.tar.gz /data
   ```
 ## Troubleshooting
 ### Container won't start
 ```bash
 # Check logs
 docker-compose logs web
 docker-compose logs api
 ```
 ### Out of memory
 Increase Docker's memory allocation or reduce worker count in Dockerfile.
 ### Permission errors
 The containers run as non-root user `stego` (UID 1000). Ensure volume permissions match.
--- a/4
+++ b/4
@@ -62,8 +62,8 @@ COPY src/ src/
 COPY data/ data/
 COPY frontends/web/ frontends/web/
-# Create upload directory
+# Create upload directory and instance directories (for volumes)
-RUN mkdir -p /tmp/stego_uploads
+RUN mkdir -p /tmp/stego_uploads /app/frontends/web/instance /app/frontends/web/certs
 # Create non-root user
 RUN useradd -m -u 1000 stego && chown -R stego:stego /app /tmp/stego_uploads
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -227,6 +227,23 @@ docker-compose logs -f
 docker-compose down
 ```
 #### Authentication Configuration (v4.0.2)
 The Web UI supports optional authentication. Configure via environment variables:
 ```bash
 # .env file (create in project root)
 STEGASOO_AUTH_ENABLED=true      # Enable login (default: true)
 STEGASOO_HTTPS_ENABLED=false    # Enable HTTPS (default: false)
 STEGASOO_HOSTNAME=localhost     # Hostname for SSL cert
 STEGASOO_CHANNEL_KEY=           # Optional channel key
 # Then run
 docker-compose up -d web
 ```
 On first access, you'll be prompted to create an admin account. The database and SSL certs are persisted in Docker volumes.
 #### Services
 | Service | URL | Description |
@@ -418,20 +435,121 @@ pip install stegasoo[all]
 ### Raspberry Pi
-Stegasoo works on Raspberry Pi 4 (2GB+ RAM recommended):
+Stegasoo works on Raspberry Pi 4/5 (4GB+ RAM recommended for Web UI).
 #### Step 1: Install System Dependencies
 ```bash
-# System dependencies
+sudo apt-get update
-sudo apt-get install python3-dev libzbar0 libjpeg-dev
+sudo apt-get install -y \
-
+  build-essential \
-# Install (may take a while to compile)
+  git \
-pip install stegasoo[cli]
+  libssl-dev \
-
+  zlib1g-dev \
-# For web/api, ensure enough RAM
+  libbz2-dev \
-pip install stegasoo[web]  # Needs ~768MB free
+  libreadline-dev \
  libsqlite3-dev \
  libncursesw5-dev \
  xz-utils \
  tk-dev \
  libxml2-dev \
  libxmlsec1-dev \
  libffi-dev \
  liblzma-dev \
  libzbar0 \
  libjpeg-dev
 ```
-**Note:** Argon2 operations will be slower on Pi due to memory-hardness.
+#### Step 2: Install Python 3.12 via pyenv
 Raspberry Pi OS ships with Python 3.13, which is **not compatible** with jpegio. Install Python 3.12:
 ```bash
 # Install pyenv
 curl https://pyenv.run | bash
 # Add to ~/.bashrc
 echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
 echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
 echo 'eval "$(pyenv init - bash)"' >> ~/.bashrc
 source ~/.bashrc
 # Install Python 3.12 (takes ~10 minutes on Pi 5)
 pyenv install 3.12
 pyenv global 3.12
 ```
 #### Step 3: Build jpegio for ARM
 The upstream jpegio has x86-specific build flags. Patch and build from source:
 ```bash
 # Clone jpegio
 git clone https://github.com/dwgoon/jpegio.git
 cd jpegio
 # Patch for ARM (removes x86-specific -m64 flag)
 sed -i "s/cargs.append('-m64')/pass  # ARM fix/" setup.py
 # Build and install
 pip install .
 cd ..
 ```
 #### Step 4: Install Stegasoo
 ```bash
 # Clone Stegasoo
 git clone https://github.com/adlee-was-taken/stegasoo.git
 cd stegasoo
 # Create venv with Python 3.12
 ~/.pyenv/versions/3.12.*/bin/python -m venv venv
 source venv/bin/activate
 # Install (jpegio already installed, skip it)
 pip install -e ".[web]" --no-deps
 pip install argon2-cffi cryptography pillow flask gunicorn scipy numpy pyzbar qrcode
 ```
 #### Step 5: Run the Web UI
 ```bash
 cd frontends/web
 # Optional: Enable authentication
 export STEGASOO_AUTH_ENABLED=true
 # Optional: Enable HTTPS for local network security
 export STEGASOO_HTTPS_ENABLED=true
 export STEGASOO_HOSTNAME=raspberrypi.local
 # Start server
 python app.py
 # Access at http://<pi-ip>:5000
 ```
 #### Verify Installation
 ```bash
 python -c "
 import stegasoo
 from stegasoo.dct_steganography import has_jpegio_support
 print(f'Stegasoo: {stegasoo.__version__}')
 print(f'Argon2: {stegasoo.has_argon2()}')
 print(f'DCT: {stegasoo.has_dct_support()}')
 print(f'jpegio: {has_jpegio_support()}')
 "
 # Expected: All True
 ```
 #### Notes
 - **RAM**: Web UI needs ~768MB free for Argon2 + scipy operations
 - **Performance**: Argon2 operations take 3-5 seconds on Pi 5 (vs ~2s on desktop)
 - **Python 3.13**: Not supported due to jpegio C extension incompatibility
 - **First run**: Will prompt you to create an admin account
 - **HTTPS**: Generates self-signed certificate (browsers will warn)
 ---
--- a/21
+++ b/21
@@ -0,0 +1,21 @@
 MIT License
 Copyright (c) 2024-2025 Aaron D. Lee
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
--- a/PLAN-4.1.0.md
+++ b/PLAN-4.1.0.md
@@ -0,0 +1,538 @@
 # Stegasoo 4.1.0 Plan
 ## Overview
 Version 4.1.0 is a feature release focusing on small-group deployment improvements and new utilities.
 ## Goals
 1. ~~**Multi-User Support** - Admin can create up to 16 users for shared deployments~~ ✅ DONE
 2. **Channel Key QR** - Easy visual sharing of channel keys via QR codes
 3. ~~**CLI Channel Commands** - Manage channel keys from command line~~ ✅ DONE
 4. **Advanced Tools** - Image/stego utilities (TBD)
 ---
 ## Feature 1: Multi-User Support ✅ COMPLETED
 > Implemented in commit 7b33501. All requirements met.
 ### Requirements
 - 16 users + 1 admin maximum (17 total)
 - First user created at setup is always admin
 - Admin can add/delete users, reset passwords
 - Regular users can only change their own password
 - No self-registration (admin-invite only)
 ### Database Changes
 **Update User model in `frontends/web/models.py`:**
 ```python
 class User(db.Model):
    id = Column(Integer, primary_key=True)
    username = Column(String(80), unique=True, nullable=False)
    password_hash = Column(String(255), nullable=False)
    role = Column(String(20), default='user')  # 'admin' or 'user'
    created_at = Column(DateTime, default=datetime.utcnow)
 ```
 **Migration:** Add `role` and `created_at` columns. Existing users get `role='admin'`.
 ### New Routes
 | Route | Method | Access | Description |
 |-------|--------|--------|-------------|
 | `/admin/users` | GET | admin | List all users |
 | `/admin/users/new` | GET, POST | admin | Create user form |
 | `/admin/users/<id>/delete` | POST | admin | Delete user |
 | `/admin/users/<id>/reset-password` | POST | admin | Generate temp password |
 ### New Decorator
 ```python
 # auth.py
 def admin_required(f):
    @wraps(f)
    def decorated(*args, **kwargs):
        if not current_user.is_authenticated:
            return redirect(url_for('login'))
        if current_user.role != 'admin':
            flash('Admin access required', 'error')
            return redirect(url_for('index'))
        return f(*args, **kwargs)
    return decorated
 ```
 ### UI Changes
 **Navigation (for admin users):**
 - Add "Users" link in navbar (visible only to admin)
 **Account page (`/account`):**
 - Admin sees link to user management
 - All users see their own password change form
 **New template: `templates/admin/users.html`:**
 - Table: Username | Role | Created | Actions
 - Actions: Reset Password, Delete (disabled for self)
 - "Add User" button (disabled if at 16 user limit)
 - Show count: "3 of 16 users"
 **New template: `templates/admin/user_new.html`:**
 - Username field (email-style allowed)
 - Password field (auto-populated with random 8-char, admin can override)
 - Submit → confirmation page shows password once with copy button
 ### Validation
 - Username: 3-80 chars, alphanumeric + underscore/hyphen + @/. for email-style
 - Password: 8+ chars (same as current)
 - Can't delete yourself
 - Can't demote the last admin
 - Deleting user immediately invalidates their sessions
 ---
 ## Feature 2: Channel Key QR
 ### Web UI
 **About page additions:**
 If `STEGASOO_CHANNEL_KEY` environment variable is set:
 ```
 ┌─────────────────────────────────────────┐
 │  Channel Key                            │
 │                                         │
 │  ██████████████    Your server uses a   │
 │  ██          ██    private channel key. │
 │  ██  ██████  ██    Share this QR with   │
 │  ██  ██████  ██    others to join.      │
 │  ██          ██                         │
 │  ██████████████    [Copy Key] [Download]│
 │                                         │
 │  Key: abc123...xyz                      │
 └─────────────────────────────────────────┘
 ```
 - QR generated server-side using `qrcode` library
 - "Copy Key" copies text to clipboard
 - "Download QR" saves as PNG
 **Implementation:**
 ```python
 # about route addition
@app.route('/about')
 def about():
    channel_key = os.environ.get('STEGASOO_CHANNEL_KEY', '')
    channel_qr_b64 = None
    if channel_key:
        # Generate QR as base64 PNG
        qr = qrcode.make(channel_key)
        buffer = BytesIO()
        qr.save(buffer, format='PNG')
        channel_qr_b64 = base64.b64encode(buffer.getvalue()).decode()
    return render_template('about.html',
                          channel_key=channel_key,
                          channel_qr=channel_qr_b64)
 ```
 ### CLI Commands
 **New command group: `stegasoo channel`**
 ```bash
 # Generate a new channel key
 stegasoo channel generate
 # Output:
 # Channel Key: stg_abc123...xyz789
 #
 # ██████████████████
 # ██              ██
 # ██  ██████████  ██
 # ...
 #
 # Set in environment: export STEGASOO_CHANNEL_KEY="stg_abc123..."
 # Show current key (from env or argument)
 stegasoo channel show
 # Output:
 # Channel Key: stg_abc123...xyz789
 # Display QR in terminal (ASCII)
 stegasoo channel qr
 # Output: ASCII QR code
 # Save QR as PNG
 stegasoo channel qr -o channel-key.png
 # Output: Saved to channel-key.png
 # Explicit format selection
 stegasoo channel qr --format ascii      # Terminal (default)
 stegasoo channel qr --format png -o -   # PNG to stdout
 ```
 **Implementation notes:**
 - Use `qrcode[pil]` for PNG output
 - Use `qrcode` with `print_ascii()` for terminal
 - Read key from `--key` argument or `STEGASOO_CHANNEL_KEY` env var
 - `generate` uses existing `generate_channel_key()` from `stegasoo.channel`
 ---
 ## File Changes Summary
 ### New Files
 | File | Description |
 |------|-------------|
 | `frontends/web/templates/admin/users.html` | User management page |
 | `frontends/web/templates/admin/user_new.html` | Add user form |
 ### Modified Files
 | File | Changes |
 |------|---------|
 | `frontends/web/models.py` | Add `role`, `created_at` to User |
 | `frontends/web/auth.py` | Add `@admin_required`, user management routes |
 | `frontends/web/templates/base.html` | Add Users link for admins |
 | `frontends/web/templates/account.html` | Add admin link |
 | `frontends/web/templates/about.html` | Add channel key QR section |
 | `src/stegasoo/cli.py` | Add `channel` command group |
 ---
 ## Testing Plan
 ### Multi-User
 1. Fresh install → first user is admin
 2. Admin can create users up to limit (16)
 3. Admin can't create 17th user (shows error)
 4. Regular user can log in, encode/decode
 5. Regular user can't access `/admin/users`
 6. Admin can reset user password
 7. Admin can delete user
 8. Admin can't delete self
 9. Existing 4.0.2 databases upgrade correctly (single user becomes admin)
 ### Channel Key QR
 1. About page shows nothing if no channel key
 2. About page shows QR + key if channel key set
 3. Copy button works
 4. Download gives valid PNG
 5. QR scans correctly to key value
 ### CLI
 1. `channel generate` creates valid key + shows QR
 2. `channel show` displays current key
 3. `channel qr` outputs ASCII to terminal
 4. `channel qr -o file.png` saves PNG
 5. Commands work with `--key` override
 6. Commands read from env var
 ---
 ## Feature 3: Advanced Tools
 ### Included Tools
 | Tool | Web | CLI | Description |
 |------|-----|-----|-------------|
 | **Capacity Calculator** | ✓ | ✓ | Upload image → show DCT/LSB capacity |
 | **Metadata Stripper** | ✓ | ✓ | Remove EXIF/metadata from image |
 | **Stego Detector** | ✓ | ✓ | Analyze image for signs of hidden data |
 | **Image Compare** | ✓ | - | Side-by-side before/after diff |
 | **Header Peek** | ✓ | ✓ | Check for Stegasoo header without decrypting |
 | **Batch Mode** | - | ✓ | Encode/decode multiple files |
 ### Web UI: `/tools` Page
 New page with card-based layout:
 ```
 ┌─────────────────────────────────────────────────────────────┐
 │  🛠️ Advanced Tools                                          │
 ├─────────────────────────────────────────────────────────────┤
 │                                                             │
 │  ┌─────────────────┐  ┌─────────────────┐                   │
 │  │ 📏 Capacity     │  │ 🧹 Metadata     │                   │
 │  │   Calculator    │  │   Stripper      │                   │
 │  │                 │  │                 │                   │
 │  │ Check how much  │  │ Remove EXIF     │                   │
 │  │ data fits       │  │ before encoding │                   │
 │  └─────────────────┘  └─────────────────┘                   │
 │                                                             │
 │  ┌─────────────────┐  ┌─────────────────┐                   │
 │  │ 🔍 Stego        │  │ 🔎 Header       │                   │
 │  │   Detector      │  │   Peek          │                   │
 │  │                 │  │                 │                   │
 │  │ Analyze image   │  │ Check for       │                   │
 │  │ for hidden data │  │ Stegasoo data   │                   │
 │  └─────────────────┘  └─────────────────┘                   │
 │                                                             │
 │  ┌─────────────────┐                                        │
 │  │ ⚖️ Image        │                                        │
 │  │   Compare       │                                        │
 │  │                 │                                        │
 │  │ Before/after    │                                        │
 │  │ diff view       │                                        │
 │  └─────────────────┘                                        │
 │                                                             │
 └─────────────────────────────────────────────────────────────┘
 ```
 Each card opens a modal or expands inline for the tool interface.
 ### CLI Structure
 ```bash
 # Capacity calculator
 stegasoo capacity image.jpg
 stegasoo capacity image.jpg --format json
 # Metadata stripper
 stegasoo strip image.jpg                    # Output to image_stripped.jpg
 stegasoo strip image.jpg -o clean.jpg       # Custom output
 stegasoo strip image.jpg --in-place         # Overwrite original
 # Stego detector
 stegasoo detect image.jpg
 stegasoo detect image.jpg --verbose         # Detailed analysis
 # Header peek
 stegasoo peek image.jpg
 # Output: "Stegasoo DCT header detected" or "No Stegasoo header found"
 # Batch mode
 stegasoo encode --batch manifest.json       # JSON with files + credentials
 stegasoo decode --batch input_dir/ --out output_dir/
 ```
 ### Tool Details
 #### Capacity Calculator
 - Input: Image file
 - Output: Dimensions, megapixels, DCT capacity, LSB capacity
 - Web: Upload zone + results panel
 - CLI: Table or JSON output
 #### Metadata Stripper
 - Input: Image file
 - Output: Clean image (EXIF/metadata removed)
 - Show what was removed (camera model, GPS, etc.)
 - Preserve image quality
 #### Stego Detector
 - Input: Image file
 - Analysis:
  - Chi-square analysis (LSB detection)
  - DCT coefficient histogram analysis
  - Visual inspection hints
 - Output: Likelihood score + findings
 - Note: Detection is probabilistic, not definitive
 #### Image Compare
 - Input: Two images (original + stego)
 - Output:
  - Side-by-side view
  - Difference overlay (amplified)
  - Pixel-level stats (PSNR, SSIM)
 - Web only (visual tool)
 #### Header Peek
 - Input: Image file
 - Output: Header found (yes/no), mode (DCT/LSB), embedded size estimate
 - Does NOT decrypt - just checks for valid header structure
 - Useful for "is this a stego image?" without credentials
 #### Batch Mode
 - CLI only
 - Manifest file (JSON) or directory-based
 - Progress bar for multiple files
 - Error handling per-file (continue on failure)
 ---
 ## Migration Notes
 ### Database Migration
 For existing 4.0.2 installations:
 ```python
 # migrations/add_user_role.py
 def upgrade():
    # Add columns with defaults
    op.add_column('user', sa.Column('role', sa.String(20), default='user'))
    op.add_column('user', sa.Column('created_at', sa.DateTime))
    # Set existing users as admin (they were the first user)
    op.execute("UPDATE user SET role = 'admin' WHERE role IS NULL")
    op.execute("UPDATE user SET created_at = datetime('now') WHERE created_at IS NULL")
 ```
 Or simpler: detect on startup, update schema automatically (current pattern).
 ---
 ## Out of Scope
 - Per-user channel keys
 - User groups/teams
 - API authentication tokens
 - User activity logging
 - Password complexity rules beyond length
 ---
 ## Estimated Effort
 | Component | Complexity |
 |-----------|------------|
 | Database schema change | Low |
 | Admin routes + templates | Medium |
 | Access control decorator | Low |
 | About page QR | Low |
 | CLI channel commands | Medium |
 | Advanced Tools (TBD) | Medium-High |
 | Testing | Medium |
 ---
 ## Decisions
 1. **Temp password flow:** Password field auto-populates with random 8-char password. Admin can override if desired. Show password once on confirmation page.
 2. **Session handling:** Yes - deleting a user immediately invalidates their active sessions (ban hammer).
 3. **Username rules:** Sane requirements, email-style allowed. Validation: 3-80 chars, alphanumeric, underscore, hyphen, @ and . for email-style.
 ---
 ## Approval
 - [x] Plan reviewed
 - [x] Questions resolved
 - [x] Ready to implement
 ## Progress
 - [x] Multi-User Support (commit 7b33501)
 - [x] Channel Key QR (Web UI) - added QR generator on About page
 - [x] CLI Channel Commands
 - [x] Saved Channel Keys (Web UI) - users can save/manage channel keys
 - [x] Advanced Tools - Image Security Toolkit
  - [x] CLI: `stegasoo tools capacity/strip/peek/exif`
  - [x] API: `/api/tools/capacity`, `/api/tools/peek`, `/api/tools/exif/*`
  - [x] WebUI: Tools page with tabbed interface
  - [x] EXIF Editor with inline editing, clear all, save/download
 ---
 ## Architectural Improvements (4.1.0)
 ### Consolidated Channel Key Resolution
 Moved `resolve_channel_key()` from 3 duplicate implementations to single source of truth in `src/stegasoo/channel.py`:
 ```python
 # Library: src/stegasoo/channel.py
 def resolve_channel_key(value, *, file_path=None, no_channel=False) -> str | None:
    """Unified channel key resolution - returns None (auto), "" (public), or key."""
 def get_channel_response_info(channel_key) -> dict:
    """Get channel info dict for API/WebUI responses."""
 ```
 Frontends now use thin wrappers that translate exceptions to their context (Click/HTTP).
 ### DCT Payload Pre-Check
 Added `will_fit_by_mode()` pre-check to WebUI encode to fail fast with helpful error message instead of cryptic exception deep in DCT processing.
 ### EXIF Tools (Library Layer)
 Added to `src/stegasoo/utils.py`:
 - `read_image_exif(image_data)` - Read EXIF metadata as dict
 - `write_image_exif(image_data, updates)` - Update EXIF fields (JPEG only)
 Dependencies added: `piexif>=1.1.0`
 ---
 ## Action Item: Architectural Review ✅ DONE
 Reviewed modules for consistency with Library → CLI → API → WebUI pattern:
 | Module | Library | CLI | API | WebUI | Status |
 |--------|---------|-----|-----|-------|--------|
 | encode | ✓ | ✓ | ✓ | ✓ | Consistent |
 | decode | ✓ | ✓ | ✓ | ✓ | Consistent |
 | channel | ✓ | ✓ | ✓ | ✓ | Consolidated resolve_channel_key |
 | tools | ✓ | ✓ | ✓ | ✓ | Complete |
 | generate | ✓ | ✓ | - | ✓ | CLI has `stegasoo generate` |
 Priority order: Developer/CLI → API integrator → WebUI end-user
 ---
 ## Admin Recovery System (4.1.0) ✅ DONE
 Password reset capability for locked-out admins with multiple backup options.
 ### Library Layer (`src/stegasoo/recovery.py`)
 ```python
 # Key generation and validation
 generate_recovery_key() -> str       # XXXX-XXXX-XXXX-... (32 chars)
 hash_recovery_key(key) -> str        # SHA-256 for storage
 verify_recovery_key(key, hash) -> bool
 # QR code (obfuscated - scans as gibberish)
 obfuscate_key(key) -> str            # XOR with RECOVERY_OBFUSCATION_KEY
 deobfuscate_key(data) -> str | None
 generate_recovery_qr(key) -> bytes   # PNG with obfuscated data
 extract_key_from_qr(image) -> str | None
 # Stego backup (hide key in an image)
 create_stego_backup(key, carrier_image) -> bytes
 extract_stego_backup(stego_image, reference) -> str | None
 ```
 ### Database (`app_settings` table)
 - `recovery_key_hash` - SHA-256 of recovery key (or null if disabled)
 ### Web Routes
 | Route | Method | Description |
 |-------|--------|-------------|
 | `/setup/recovery` | GET, POST | Step 2 of initial setup |
 | `/recover` | GET, POST | Password reset page |
 | `/recover/stego` | POST | Extract key from stego backup |
 | `/account/recovery/regenerate` | GET, POST | Generate new key |
 | `/account/recovery/disable` | POST | Remove recovery option |
 | `/account/recovery/stego-backup` | POST | Create stego backup |
 ### CLI Commands
 ```bash
 stegasoo admin recover --db path/to/stegasoo.db  # Reset password
 stegasoo admin generate-key [--qr]               # Generate key (reference)
 ```
 ### Security Model
 1. Recovery key shown once during setup - only hash stored
 2. QR codes XOR'd with `RECOVERY_OBFUSCATION_KEY` (fixed in constants.py)
 3. Stego backups use fixed internal passphrase/PIN - security is obscurity
 4. Instance-bound: recovery key hash must match in target database
 5. Options: text file, QR image, stego image, or no recovery (most secure)
--- a/PLAN-4.1.2.md
+++ b/PLAN-4.1.2.md
@@ -0,0 +1,250 @@
 # Stegasoo 4.1.2 Plan
 ## Release Theme
 Polish and UX improvements after the 4.1.1 stability release.
 ---
 ## 1. Real Progress Bar for Encode/Decode
 **Status:** Done
 **Problem:** Users see elapsed time but no indication of how far along the operation is. Long DCT encodes on Pi can take 2-3 minutes with no feedback.
 **Solution:** Polling + progress file approach
 ### Backend Changes
 1. **dct_steganography.py** - Write progress during block loop:
   ```python
   if progress_file and block_num % 50 == 0:
       with open(progress_file, 'w') as f:
           json.dump({"current": block_num, "total": total_blocks, "phase": "embedding"}, f)
   ```
 2. **app.py** - New endpoints:
   - `POST /encode` returns `job_id`, starts subprocess
   - `GET /encode/progress/<job_id>` returns progress JSON
   - `GET /encode/result/<job_id>` returns final result when done
 3. **Subprocess wrapper** - Pass progress file path to encode/decode functions
 ### Frontend Changes
 1. **stegasoo.js** - After form submit:
   - Show progress bar (Bootstrap progress component)
   - Poll `/encode/progress/{job_id}` every 500ms
   - Update bar width and percentage text
   - Show phase (hashing, embedding, encoding, etc.)
 2. **Templates** - Add progress bar markup to encode.html and decode.html
 ### Files to Modify
 - `src/stegasoo/dct_steganography.py`
 - `frontends/web/app.py`
 - `frontends/web/static/js/stegasoo.js`
 - `frontends/web/templates/encode.html`
 - `frontends/web/templates/decode.html`
 ---
 ## 2. Granular Decode Error Messages
 **Status:** Done
 **Problem:** Decode failures show generic "Decryption failed" - users don't know if it's wrong photo, wrong passphrase, wrong PIN, corrupted image, or format mismatch.
 **Solution:** Bubble up specific error types from library to UI
 ### Implementation
 - Added new exceptions: InvalidMagicBytesError, ReedSolomonError, NoDataFoundError, ModeMismatchError
 - DCT decode now raises InvalidMagicBytesError for wrong magic bytes
 - DCT decode now raises ReedSolomonError (renamed from reedsolo's) for corruption
 - app.py catches specific exceptions with user-friendly messages:
  - Invalid magic → "Try a different mode (LSB/DCT)"
  - RS error → "Image too corrupted, may have been re-saved"
  - Invalid header → "Image may have been modified"
  - Decryption error → "Wrong credentials"
 ### Files Modified
 - `src/stegasoo/exceptions.py` (new exceptions)
 - `src/stegasoo/__init__.py` (exports)
 - `src/stegasoo/dct_steganography.py` (raise specific exceptions)
 - `frontends/web/app.py` (catch and display)
 ---
 ## 3. Mobile-Responsive Polish
 **Status:** Done
 **Problem:** UI works on mobile but has rough edges - cramped buttons, hard-to-tap targets, awkward layouts on small screens.
 **Solution:** Targeted CSS/layout fixes for mobile breakpoints
 ### Areas to Improve
 1. **Encode/Decode Forms:**
   - Stack image drop zones vertically on mobile (currently side-by-side)
   - Larger touch targets for file inputs
   - Full-width buttons on small screens
   - Passphrase input readable at smaller sizes
 2. **Navigation:**
   - Hamburger menu for mobile navbar (if not already)
   - Sticky header doesn't eat too much screen
   - Easy thumb reach for main actions
 3. **Results/Output:**
   - Download buttons full-width on mobile
   - QR codes sized appropriately
   - Click-to-copy message box works well with touch
 4. **Drop Zones:**
   - Larger tap targets
   - Visual feedback for touch (not just hover)
   - Camera integration hint on mobile ("Tap to take photo or choose file")
 ### Testing Targets
 - iPhone SE (small)
 - iPhone 14 (medium)
 - iPad (tablet)
 - Android Chrome
 ### Files to Modify
 - `frontends/web/static/css/style.css` (or new mobile.css)
 - `frontends/web/templates/encode.html`
 - `frontends/web/templates/decode.html`
 - `frontends/web/templates/base.html` (navbar)
 ---
 ## Testing Checklist
 - [ ] Progress bar works on localhost
 - [ ] Progress bar works on Pi (slower, more visible)
 - [ ] Cancellation handling (what if user navigates away?)
 - [ ] Error states display correctly
 - [ ] Smoke test passes
 ---
 ## 4. Forced First-Login Setup
 **Status:** Done
 **Problem:** Users can navigate the app without creating an admin account first. Should force password setup before anything else.
 **Solution:** Middleware/decorator that redirects to setup page if no users exist.
 ### Implementation
 - Added `@app.before_request` hook that redirects to /setup if no users exist
 - Skips redirect for static files and setup-related routes
 ### Files Modified
 - `frontends/web/app.py` (added require_setup before_request hook)
 ---
 ## 5. Dropzone UX Fixes
 **Status:** Done
 **Problem:** Dropzone has some interaction bugs:
 - Dropzone doesn't clear properly if first QR image fails
 - Can't click on image preview to replace file (have to click surrounding border)
 **Solution:** Fix JS event handling and state management
 ### Implementation
 - Added click handler on preview images to trigger file input
 - Made entire drop zone clickable (not just label)
 - QR zone now resets after 2 seconds on error, allowing retry
 - Clear file input on QR error so same file can be re-selected
 ### Files Modified
 - `frontends/web/static/js/stegasoo.js`
 ---
 ## 6. Smoke Test Benchmarking
 **Status:** Done
 **Problem:** No way to measure encode/decode performance or track regressions.
 **Solution:** Add timing to smoke tests using `hyperfine` or `time`.
 ### Implementation
 - Added `--benchmark` flag to run encode/decode benchmarks after tests
 - Added `--runs=N` flag to customize number of benchmark runs (default: 5)
 - Uses hyperfine if available for precise timing with warmup
 - Falls back to manual timing with bc if hyperfine not installed
 - Outputs min/max/avg stats for both encode and decode operations
 ### Files Modified
 - `tests/smoke-test.sh`
 ---
 ## 7. Docker Cleanup
 **Status:** Done (4.1.1)
 **Problem:** Docker build context is larger than needed (includes test images, rpi scripts, etc.)
 **Solution:** Added `.dockerignore` and fixed volume permissions in Dockerfile
 ### Files Modified
 - `.dockerignore` (created)
 - `Dockerfile` (instance dir permissions)
 ---
 ## 8. Release Validation Script
 **Status:** Done
 **Problem:** Manual release checklist is error-prone. Need automated validation.
 **Solution:** Script that runs through testable checklist items
 ### Features
 - Run pytest
 - Build and test Docker image
 - SSH to Pi and run smoke test (optional, if PI_IP provided)
 - Report pass/fail summary
 ### Files to Create
 - `scripts/validate-release.sh`
 ---
 ## 9. Smoke Test Docker Support
 **Status:** Done
 **Problem:** Smoke test expects systemd service, doesn't auto-create admin for Docker.
 **Solution:** Make smoke test Docker-aware
 ### Features
 - Skip systemd checks if not on Pi/Linux with systemd
 - Auto-detect fresh Docker (no users) and create admin via /setup
 - Add `--docker` flag to skip Pi-specific checks
 ### Implementation
 - Added `--docker` flag that sets localhost and skips SSH/systemd checks
 - Docker health check verifies container responds with HTTP 200/302
 - Header shows "Docker Smoke Test" in Docker mode
 ### Files Modified
 - `rpi/smoke-test.sh`
 ---
 ## Notes
 - Keep 4.1.2 focused - 9 features (9 done)
 - Don't break DCT compatibility (4.1.1 RS format is stable)
 - Test on Pi before release
--- a/PLAN-4.1.3.md
+++ b/PLAN-4.1.3.md
@@ -0,0 +1,42 @@
 # Stegasoo 4.1.3 Plan
 ## Release Theme
 Performance and admin features.
 ---
 ## 1. DCT Performance Optimizations
 **Status:** Planned
 **Problem:** DCT encode/decode can be slow on Pi, especially for large images.
 **Ideas:**
 - Vectorize block processing with NumPy
 - Reduce Python loop overhead
 - Parallel block processing (multiprocessing?)
 - Profile and identify bottlenecks
 - Consider Cython for hot paths
 ---
 ## 2. User Management UI
 **Status:** Planned
 **Problem:** No way for admin to manage users via UI. Currently need direct DB access.
 **Features:**
 - List all users
 - Create new user (admin only)
 - Delete user (admin only)
 - Reset user password
 - User activity/last login
 ---
 ## Notes
 - These are heavier lifts than 4.1.2
 - Profile before optimizing
 - Consider security implications of user management
--- a/README.md
+++ b/README.md
@@ -2,429 +2,152 @@
 A secure steganography system for hiding encrypted messages in images using hybrid authentication.
 [![Tests](https://github.com/adlee-was-taken/stegasoo/actions/workflows/test.yml/badge.svg)](https://github.com/adlee-was-taken/stegasoo/actions/workflows/test.yml)
 [![Lint](https://github.com/adlee-was-taken/stegasoo/actions/workflows/lint.yml/badge.svg)](https://github.com/adlee-was-taken/stegasoo/actions/workflows/lint.yml)
 ![Python](https://img.shields.io/badge/Python-3.10--3.12-blue)
-![License](https://img.shields.io/badge/License-MIT-green)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 ![Security](https://img.shields.io/badge/Security-AES--256--GCM-red)
 ![Version](https://img.shields.io/badge/Version-4.0.1-purple)
 ## Features
- 🔐 **AES-256-GCM** authenticated encryption
+- **AES-256-GCM** authenticated encryption
- 🧠 **Argon2id** memory-hard key derivation (256MB RAM requirement)
+- **Argon2id** memory-hard key derivation (256MB RAM requirement)
- 🎲 **Pseudo-random pixel selection** defeats steganalysis
+- **Pseudo-random pixel selection** defeats steganalysis
- 🔑 **Multi-factor authentication**: PIN, RSA key, or both
+- **Multi-factor authentication**: Reference photo + passphrase + PIN/RSA key
- 🖼️ **Reference photo** as "something you have"
+- **Multiple interfaces**: CLI, Web UI, REST API
- 🌐 **Multiple interfaces**: CLI, Web UI, REST API
+- **File embedding**: Hide any file type (PDF, ZIP, documents)
- 📁 **File embedding** - Hide any file type (PDF, ZIP, documents)
+- **DCT steganography**: JPEG-resilient embedding for social media
- 📱 **QR code support** - Encode/decode RSA keys via QR codes
+- **Channel keys**: Private group communication channels
 - 🆕 **DCT steganography** - JPEG-resilient embedding for social media
 - 🆕 **Large image support** - Process images up to 14MB+
-## What's New in v4.0.0
+## Embedding Modes
 | Feature | Description |
 |---------|-------------|
 | **Simplified Auth** | Removed date dependency - encode/decode anytime without tracking dates |
 | **Passphrase** | Renamed from "day phrase" to "passphrase" (no more daily rotation) |
 | **Python 3.12** | Requires Python 3.10-3.12 (jpegio incompatible with 3.13) |
 | **Large Image Fix** | JPEG normalization prevents crashes with quality=100 images |
 | **Subprocess Isolation** | WebUI runs encode/decode in subprocesses for stability |
 | **4-Word Default** | Default passphrase increased from 3 to 4 words |
 ### Breaking Changes from v3.x
 - `day_phrase` parameter renamed to `passphrase` in all APIs
 - `date_str` parameter removed from encode/decode functions
 - Python 3.13 not supported (jpegio C extension incompatibility)
 ### Embedding Mode Comparison
 | Mode | Capacity (1080p) | JPEG Resilient | Best For |
 |------|------------------|----------------|----------|
-| **DCT** (default) | ~150 KB | ✅ Yes | Social media, messaging apps |
+| **DCT** (default) | ~150 KB | Yes | Social media, messaging apps |
-| **LSB** | ~750 KB | ❌ No | Email, file transfer |
+| **LSB** | ~750 KB | No | Email, direct file transfer |
-## WebUI Preview
+## Web UI
-| Front Page | Encode | Decode | Generate |
+| Home | Encode | Decode | Generate |
-|:----------:|:------:|:------:|:--------:|
+|:----:|:------:|:------:|:--------:|
-| ![Screenshot](https://github.com/adlee-was-taken/stegasoo/blob/main/data/WebUI.webp) | ![Screenshot](https://github.com/adlee-was-taken/stegasoo/blob/main/data/WebUI_Encode.webp) | ![Screenshot](https://github.com/adlee-was-taken/stegasoo/blob/main/data/WebUI_Decode.webp) | ![Screenshot](https://github.com/adlee-was-taken/stegasoo/blob/main/data/WebUI_Generate.webp) |
+| ![Home](data/WebUI.webp) | ![Encode](data/WebUI_Encode.webp) | ![Decode](data/WebUI_Decode.webp) | ![Generate](data/WebUI_Generate.webp) |
 ## Quick Start
 ```bash
-# Install with all features (requires Python 3.10-3.12)
+# Install (Python 3.10-3.12)
 pip install -e ".[all]"
-# Generate credentials (memorize these!)
+# Generate credentials
 stegasoo generate --pin --words 4
-# Encode a message (DCT mode - default, best for social media)
+# Encode a message
 stegasoo encode \
-  --ref photo.jpg \
+  --ref my_photo.jpg \
  --carrier meme.jpg \
  --passphrase "apple forest thunder mountain" \
  --pin 123456 \
  --message "Secret message"
-# Encode with LSB mode (higher capacity, for email/file transfer)
+# Decode
 stegasoo encode \
  --ref photo.jpg \
  --carrier meme.png \
  --passphrase "apple forest thunder mountain" \
  --pin 123456 \
  --message "Secret message" \
  --mode lsb
 # Decode (auto-detects mode)
 stegasoo decode \
-  --ref photo.jpg \
+  --ref my_photo.jpg \
-  --stego stego.png \
+  --stego stego_image.png \
  --passphrase "apple forest thunder mountain" \
  --pin 123456
 ```
-For detailed installation instructions, see **[INSTALL.md](INSTALL.md)**.
+## Interfaces
---
+| Interface | Start Command | Documentation |
 |-----------|---------------|---------------|
 | **CLI** | `stegasoo --help` | [CLI.md](CLI.md) |
 | **Web UI** | `cd frontends/web && python app.py` | [WEB_UI.md](WEB_UI.md) |
 | **REST API** | `cd frontends/api && uvicorn main:app` | [API.md](API.md) |
 ## Security Model
 Stegasoo uses multiple authentication factors combined with strong cryptography:
 ```
-┌─────────────────────────────────────────────────────────────────┐
+Reference Photo ──┐
-│                    AUTHENTICATION LAYERS                         │
+(~80-256 bits)    │
-├─────────────────────────────────────────────────────────────────┤
+                  ├──► Argon2id KDF ──► AES-256-GCM Key
-│                                                                 │
+Passphrase ───────┤    (256MB RAM)
-│   Reference Photo ──┐                                           │
+(~43-132 bits)    │
-│   (~80-256 bits)    │                                           │
+                  │
-│                     ├──► Argon2id KDF ──► AES-256-GCM Key       │
+PIN ──────────────┤
-│   Passphrase ───────┤    (256MB RAM)                            │
+(~20-30 bits)     │
-│   (~43-132 bits)    │                                           │
+                  │
-│                     │                                           │
+RSA Key ──────────┘
-│   Static PIN ───────┤                                           │
+(optional)
 │   (~20-30 bits)     │                                           │
 │                     │                                           │
 │   RSA Key ──────────┘                                           │
 │   (~128 bits)       (optional, adds another factor)             │
 │                                                                 │
 └─────────────────────────────────────────────────────────────────┘
 ```
 ### Entropy Summary
 | Component | Entropy | Purpose |
 |-----------|---------|---------|
 | Reference Photo | ~80-256 bits | Something you have |
 | Passphrase (3-12 words) | ~33-132 bits | Something you know |
 | PIN (6-9 digits) | ~20-30 bits | Something you know |
 | RSA Key (2048-4096 bit) | ~112-128 bits | Something you have (optional) |
 | **Combined** | **133-400+ bits** | **Beyond brute force** |
 ### Attack Resistance
 | Attack | Protection |
 |--------|------------|
 | Brute force | 2^133+ combinations minimum |
 | Rainbow tables | Random 16-byte salt per message |
 | Steganalysis | Pseudo-random pixel/coefficient selection |
 | GPU cracking | Argon2id requires 256MB RAM per attempt |
 | Side-channel | Constant-time operations in cryptography library |
 | JPEG recompression | DCT mode embeds in frequency domain |
 ### Security Configurations
 | Configuration | Entropy | Use Case |
 |--------------|---------|----------|
-| 3-word passphrase + 6-digit PIN | ~133 bits | Casual private messaging |
+| 4-word passphrase + 6-digit PIN | ~153 bits | Standard security |
-| 4-word passphrase + 9-digit PIN | ~176 bits | Standard security (recommended) |
+| 4-word passphrase + PIN + RSA | ~280+ bits | Maximum security |
 | 4-word passphrase + RSA 2048 | ~241 bits | File-based authentication |
 | 6-word passphrase + PIN + RSA 4096 | ~304 bits | Maximum security |
 ---
 ## Interfaces
 ### Command-Line Interface (CLI)
 Full-featured CLI with piping support:
 ```bash
 # Generate with RSA key
 stegasoo generate --rsa --rsa-bits 4096 -o mykey.pem -p "password"
 # Encode (DCT mode is now default)
 stegasoo encode -r ref.jpg -c carrier.jpg -p "passphrase words here" --pin 123456 -m "Message"
 # Encode with LSB mode for higher capacity
 stegasoo encode -r ref.jpg -c carrier.png -p "passphrase words here" --pin 123456 \
  -m "Message" --mode lsb
 # Encode a file
 stegasoo encode -r ref.jpg -c carrier.png -p "passphrase words here" --pin 123456 -f secret.txt
 # Decode to stdout (quiet mode)
 stegasoo decode -r ref.jpg -s stego.png -p "passphrase words here" --pin 123456 -q
 # Compare LSB vs DCT capacity for an image
 stegasoo compare carrier.png
 # Check available modes
 stegasoo modes
 ```
 📖 Full documentation: **[CLI.md](CLI.md)**
 ### Web UI
 Browser-based interface with drag-and-drop uploads:
 ```bash
 # Start the server
 cd frontends/web
 python app.py
 # Visit http://localhost:5000
 ```
 Features:
 - Drag-and-drop image uploads with scan animations
 - Real-time entropy calculator
 - Native mobile sharing (Web Share API)
 - DCT mode default with compact mode selector
 - Subprocess isolation for stability
 - Large image support (14MB+ tested)
 - Streamlined form flow (v3.3.0)
 📖 Full documentation: **[WEB_UI.md](WEB_UI.md)**
 ### REST API
 FastAPI-powered REST API with OpenAPI documentation:
 ```bash
 # Start the server
 cd frontends/api
 uvicorn main:app --host 0.0.0.0 --port 8000
 # Docs at http://localhost:8000/docs
 ```
 Example API calls:
 ```bash
 # Generate credentials
 curl -X POST http://localhost:8000/generate \
  -H "Content-Type: application/json" \
  -d '{"use_pin": true, "passphrase_words": 4}'
 # Encode (DCT mode is default)
 curl -X POST http://localhost:8000/encode/multipart \
  -F "message=Secret" \
  -F "passphrase=apple forest thunder mountain" \
  -F "pin=123456" \
  -F "reference_photo=@photo.jpg" \
  -F "carrier=@meme.jpg" \
  --output stego.jpg
 # Encode with LSB mode
 curl -X POST http://localhost:8000/encode/multipart \
  -F "message=Secret" \
  -F "passphrase=apple forest thunder mountain" \
  -F "pin=123456" \
  -F "embed_mode=lsb" \
  -F "reference_photo=@photo.jpg" \
  -F "carrier=@meme.png" \
  --output stego.png
 # Decode (auto-detects mode)
 curl -X POST http://localhost:8000/decode/multipart \
  -F "passphrase=apple forest thunder mountain" \
  -F "pin=123456" \
  -F "reference_photo=@photo.jpg" \
  -F "stego_image=@stego.jpg"
 ```
 📖 Full documentation: **[API.md](API.md)**
 ---
 ## Project Structure
 ```
 stegasoo/
 ├── src/stegasoo/           # Core library
 │   ├── __init__.py         # Public API
 │   ├── constants.py        # Configuration
 │   ├── crypto.py           # Encryption/decryption
 │   ├── steganography.py    # LSB image embedding
 │   ├── dct_steganography.py # DCT embedding
 │   ├── keygen.py           # Credential generation
 │   ├── validation.py       # Input validation
 │   ├── models.py           # Data classes
 │   ├── exceptions.py       # Custom exceptions
 │   ├── qr_utils.py         # QR code utilities
 │   └── utils.py            # Utilities
 │
 ├── frontends/
 │   ├── web/                # Flask web UI
 │   │   ├── app.py
 │   │   ├── subprocess_stego.py  # Subprocess isolation
 │   │   └── stego_worker.py      # Worker script
 │   ├── cli/                # Command-line interface
 │   └── api/                # FastAPI REST API
 │
 ├── data/
 │   └── bip39-words.txt     # BIP-39 wordlist
 │
 ├── pyproject.toml          # Package configuration
 ├── requirements.txt        # Dependencies
 ├── Dockerfile              # Multi-stage Docker build
 ├── docker-compose.yml      # Container orchestration
 │
 ├── README.md               # This file
 ├── INSTALL.md              # Installation guide
 ├── CLI.md                  # CLI documentation
 ├── API.md                  # API documentation
 ├── WEB_UI.md               # Web UI documentation
 ├── SECURITY.md             # Security documentation
 └── UNDER_THE_HOOD.md       # Technical deep-dive
 ```
 ---
 ## Requirements
-| Requirement | Version | Notes |
+| Requirement | Version |
-|-------------|---------|-------|
+|-------------|---------|
-| Python | 3.10-3.12 | **3.13 not supported** (jpegio incompatibility) |
+| Python | 3.10-3.12 |
-| RAM | 512 MB+ | 256MB for Argon2 operations |
+| RAM | 512 MB+ |
 | Disk | ~100 MB | |
 ### Key Dependencies
 | Package | Purpose |
 |---------|---------|
 | `cryptography` | AES-256-GCM encryption |
 | `Pillow` | Image processing |
 | `argon2-cffi` | Memory-hard key derivation |
 | `scipy` | DCT transforms |
 | `jpegio` | JPEG coefficient manipulation |
 | `numpy` | Array operations |
 ---
 ## Configuration
 ### Limits
 | Limit | Value |
 |-------|-------|
 | Max image size | Tested up to 14MB |
 | Max message size | 50 KB |
 | Max file upload | 5 MB |
 | PIN length | 6-9 digits |
 | Passphrase length | 3-12 words |
 | RSA key sizes | 2048, 3072, 4096 bits |
 ### Environment Variables
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `FLASK_ENV` | production | Flask environment |
 | `PYTHONPATH` | - | Include `src/` for development |
 ---
 ## Development
 ```bash
 # Install dev dependencies
 pip install -e ".[dev]"
 # Run tests
 pytest
-
+black src/ tests/ frontends/
-# Format code
+ruff check src/ tests/ frontends/
 black src/ frontends/
 ruff check src/ frontends/
 # Type checking
 mypy src/
 # Check DCT support
 python -c "from stegasoo import has_dct_support; print(f'DCT: {has_dct_support()}')"
 python -c "from stegasoo.dct_steganography import has_jpegio_support; print(f'jpegio: {has_jpegio_support()}')"
 ```
---
+## Docker
 ## Version History
 | Version | Changes |
 |---------|---------|
 | **4.0.1** | Lint cleanup, test fixes, Web UI improvements (channel key dropdown, LED indicators) |
 | **4.0.0** | Channel key support for deployment isolation, removed date dependency, renamed day_phrase→passphrase, Python 3.12 requirement, JPEG normalization fix, subprocess isolation, large image support |
 | **3.2.x** | DCT color mode, JPEG output fixes |
 | **3.0.x** | Added DCT steganography mode |
 | **2.2.x** | QR code support, file embedding |
 | **2.0.x** | Web UI, REST API, RSA keys |
 | **1.0.x** | Initial release, CLI only |
 ---
 ## Upgrading from v3.x
 ### Code Changes Required
 ```python
 # Old (v3.x)
 result = encode(
    message="secret",
    day_phrase="apple forest thunder",
    date_str="2024-01-15",
    ...
 )
 # New (v4.0)
 result = encode(
    message="secret",
    passphrase="apple forest thunder mountain",
    # No date_str needed!
    ...
 )
 ```
 ### CLI Changes
 ```bash
-# Old (v3.x)
+# Quick start
-stegasoo encode --phrase "words" --date 2024-01-15 ...
+docker-compose up -d
-# New (v4.0)
+# Access
-stegasoo encode --passphrase "words here more" ...
+# Web UI:   http://localhost:5000
-# or short form
+# REST API: http://localhost:8000
 stegasoo encode -p "words here more" ...
 ```
---
+See [DOCKER.md](DOCKER.md) for full documentation.
 ## Raspberry Pi
 Pre-built SD card images available for Pi 4/5:
 ```bash
 # Flash image (download from GitHub Releases)
 zstdcat stegasoo-rpi-*.img.zst | sudo dd of=/dev/sdX bs=4M status=progress
 # First boot runs interactive setup wizard:
 # - WiFi configuration
 # - HTTPS with port 443
 # - Channel key generation
 # - Optional overclocking
 ```
 See [rpi/README.md](rpi/README.md) for manual installation.
 ## Documentation
 - [INSTALL.md](INSTALL.md) - Installation guide
 - [DOCKER.md](DOCKER.md) - Docker deployment
 - [CLI.md](CLI.md) - Command-line reference
 - [API.md](API.md) - REST API documentation
 - [WEB_UI.md](WEB_UI.md) - Web interface guide
 - [SECURITY.md](SECURITY.md) - Security model details
 - [UNDER_THE_HOOD.md](UNDER_THE_HOOD.md) - Technical deep-dive
 - [CHANGELOG.md](CHANGELOG.md) - Version history
 - [CONTRIBUTING.md](CONTRIBUTING.md) - Contributor guide
 ## License
-MIT License - Use responsibly.
+MIT License - see [LICENSE](LICENSE). Use responsibly.
 ---
-## ⚠️ Disclaimer
+*This tool is for educational and legitimate privacy purposes. Users are responsible for complying with applicable laws.*
 This tool is for educational and legitimate privacy purposes only. Users are responsible for complying with applicable laws in their jurisdiction.
 ---
 ## See Also
 - **[INSTALL.md](INSTALL.md)** - Detailed installation instructions
 - **[CLI.md](CLI.md)** - Command-line interface reference
 - **[API.md](API.md)** - REST API documentation
 - **[WEB_UI.md](WEB_UI.md)** - Web interface guide
 - **[SECURITY.md](SECURITY.md)** - Security model and threat analysis
 - **[UNDER_THE_HOOD.md](UNDER_THE_HOOD.md)** - Technical implementation details
--- a/RELEASE-4.1.1.md
+++ b/RELEASE-4.1.1.md
@@ -0,0 +1,93 @@
 # Stegasoo 4.1.1 Release Notes
 **Release Date:** January 5, 2026
 ## Highlights
 - **Reed-Solomon Error Correction** - DCT steganography now includes RS error correction, making encoded images more resilient to minor corruption and compression artifacts
 - **Completely Rewritten Pi Setup** - Fresh install tested and validated, works reliably from scratch
 - **SSH Login Banner** - See your Stegasoo URL immediately on SSH login
 ## New Features
 ### Reed-Solomon Error Correction
 DCT-encoded images now include Reed-Solomon error correction codes, allowing recovery from minor image corruption. This significantly improves reliability when images are shared through platforms that may slightly modify them.
 ### SSH Login Banner (MOTD)
 When you SSH into your Stegasoo Pi, you'll now see:
 ```
  ___  _____  ___    ___    _    ___    ___    ___
 / __||_   _|| __|  / __|  /_\  / __|  / _ \  / _ \
 \__ \  | |  | _|  | (_ | / _ \ \__ \ | (_) || (_) |
 |___/  |_|  |___|  \___//_/ \_\|___/  \___/  \___/
 ● Stegasoo is running
   https://192.168.0.4
 ```
 ### Elapsed Time Counter
 Encode/decode buttons now show elapsed time during operations.
 ### Click-to-Copy Decoded Message
 Click the decoded message box to copy to clipboard (no button needed).
 ### Overclock Wizard Option
 First-boot wizard now offers optional CPU overclocking for Pi 4/5 with active cooling.
 ## Improvements
 ### Setup Script (setup.sh)
 - Fixed pyenv Python path resolution (handles 3.12 → 3.12.12 mapping)
 - Changed default install location to `/opt/stegasoo`
 - Fixed jpegio build order (clone stegasoo first, then build jpegio into venv)
 - Added python3-dev to dependencies
 - Added btop for system monitoring
 - Shows `/setup` URL at completion for admin account creation
 ### Sanitize Script
 - Now clears port 443 iptables redirect (clean slate for wizard)
 - Removes overclock settings before imaging
 ### Documentation
 - Updated all docs to reference `/opt/stegasoo` path
 - Added pre-setup steps (chown /opt, install git)
 - Added Pi 4 performance baseline (~60s for 10MB JPEG)
 ### About Page
 - Redesigned "Limits & Specs" section with key stats cards and accordion
 ## Bug Fixes
 - Fixed DCT steganography for non-8-aligned images
 - Fixed MOTD port detection (was using iptables which requires root)
 - Fixed smoke test `--443` flag parsing
 ## Performance
 On a Raspberry Pi 4 at 2GHz with USB 3.0 NVMe:
 - ~50 seconds to encode a 10MB JPEG
 - ~60 seconds to decode a 10MB JPEG
 - Full encryption: passphrase + PIN + reference photo
 ## Upgrade Notes
 If upgrading from 4.1.0:
 ```bash
 cd /opt/stegasoo  # or ~/stegasoo
 git pull origin 4.1
 ```
 For fresh installs, see the [Pi README](rpi/README.md).
 ## Pre-built Images
 - `stegasoo-rpi-4.1.1_20260105-2.img.zst` - Raspberry Pi 4/5 image
 Flash with:
 ```bash
 zstdcat stegasoo-rpi-4.1.1_20260105-2.img.zst | sudo dd of=/dev/sdX bs=4M status=progress
 ```
 ---
 Full changelog: [v4.1.0...v4.1.1](https://github.com/adlee-was-taken/stegasoo/compare/v4.1.0...v4.1.1)
--- a/RELEASE_CHECKLIST.md
+++ b/RELEASE_CHECKLIST.md
@@ -0,0 +1,44 @@
 # Stegasoo Release Checklist
 Pre-release validation checklist. Complete all items before tagging a release.
 ## Code Quality
 - [ ] All tests pass: `./venv/bin/pytest tests/ -v`
 - [ ] No lint errors: `./venv/bin/ruff check src/`
 - [ ] Version bumped in `pyproject.toml`
 - [ ] CHANGELOG.md updated
 ## Pi Image Validation
 - [ ] Fresh Pi OS install with setup.sh works
 - [ ] First-boot wizard completes successfully
 - [ ] MOTD shows correct URL on SSH login
 - [ ] Smoke test passes: `./rpi/smoke-test.sh --443 <PI_IP>`
 - [ ] Encode/decode works on large image (10MB+)
 - [ ] Sanitize script runs cleanly
 - [ ] Image created and compressed
 ## Docker Validation
 - [ ] Base image builds: `docker build -f Dockerfile.base -t stegasoo-base:latest .`
 - [ ] Web image builds: `docker-compose build web`
 - [ ] Container starts: `docker-compose up -d web`
 - [ ] Web UI accessible at http://localhost:5000
 - [ ] Encode/decode works in container
 - [ ] Container stops cleanly: `docker-compose down`
 ## Release Process
 - [ ] Merge feature branch to main
 - [ ] Create annotated tag: `git tag -a vX.Y.Z -m "message"`
 - [ ] Push tag: `git push origin vX.Y.Z`
 - [ ] Create GitHub Release with release notes
 - [ ] Upload Pi image (.img.zst.zip)
 - [ ] Verify download links work
 ## Post-Release
 - [ ] Delete old/obsolete releases if needed
 - [ ] Update any external documentation
 - [ ] Announce release (if applicable)
--- a/WEB_UI.md
+++ b/WEB_UI.md
@@ -1,17 +1,22 @@
-# Stegasoo Web UI Documentation (v4.0.1)
+# Stegasoo Web UI Documentation (v4.1.0)
 Complete guide for the Stegasoo web-based steganography interface.
 ## Table of Contents
 - [Overview](#overview)
- [What's New in v4.0.1](#whats-new-in-v401)
+- [What's New in v4.1.0](#whats-new-in-v410)
 - [Authentication & HTTPS](#authentication--https)
 - [Admin Recovery](#admin-recovery)
 - [Multi-User Support](#multi-user-support)
 - [Installation & Setup](#installation--setup)
 - [Pages & Features](#pages--features)
  - [Home Page](#home-page)
  - [Generate Credentials](#generate-credentials)
  - [Encode Message](#encode-message)
  - [Decode Message](#decode-message)
  - [Tools Page](#tools-page)
  - [Account Page](#account-page)
  - [About Page](#about-page)
 - [Embedding Modes](#embedding-modes)
  - [DCT Mode (Default)](#dct-mode-default)
@@ -53,24 +58,270 @@ Built with Flask, Bootstrap 5, and a modern dark theme.
 ---
-## What's New in v4.0.1
+## What's New in v4.1.0
-Version 4.0.1 adds channel key support and UI improvements:
+Version 4.1.0 adds admin recovery, multi-user support, and new tools:
 | Feature | Description |
 |---------|-------------|
-| Channel keys | 256-bit keys for deployment/group isolation |
+| **Admin Recovery** | Password reset using secure recovery key |
-| Channel dropdown | Select channel mode (Auto/Public/Custom) |
+| **Multi-User Support** | Up to 16 users with role-based access |
-| LED indicators | Visual status indicators for form fields |
+| **EXIF Editor** | View, edit, and strip image metadata |
-| Key capsule styling | Improved RSA key display |
+| **Saved Channel Keys** | Users can save/manage channel keys in account |
-| Streamlined layout | PIN + Channel key in same row |
+| **Toast Improvements** | Auto-dismiss after 20 seconds with fade |
 **Key benefits:**
- ✅ Channel key isolation - Different teams/deployments can't read each other's messages
+- ✅ Never get locked out - recovery key backup options
- ✅ Dropdown selection for channel mode instead of radio buttons
+- ✅ Share access with team members (admin/user roles)
- ✅ Visual LED indicators show field status
+- ✅ Full EXIF metadata control in Tools page
- ✅ Cleaner form layout with improved spacing
+- ✅ Persistent channel key storage per user
- ✅ Backward compatible - public mode works without channel key
+
 ---
 ## What's New in v4.0.2
 Version 4.0.2 added authentication and HTTPS support:
 | Feature | Description |
 |---------|-------------|
 | **Authentication** | Single-admin login with SQLite3 user storage |
 | **First-run setup** | Wizard to create admin account on first access |
 | **Account management** | Change password page |
 | **Optional HTTPS** | Auto-generated self-signed certificates |
 ---
 ## Authentication & HTTPS
 ### Overview
 v4.0.2 adds optional authentication and HTTPS for secure home network deployment.
 ### First-Run Setup
 On first access, you'll be prompted to create an admin account:
 1. Navigate to `http://localhost:5000`
 2. You'll be redirected to `/setup`
 3. Enter a username (e.g., "admin")
 4. Enter a password (minimum 8 characters)
 5. Confirm the password
 6. Click "Create Admin Account"
 The admin account is stored in `frontends/web/instance/stegasoo.db` (SQLite).
 ### Login
 After setup, protected pages require login:
 - **Protected routes:** `/encode`, `/decode`, `/generate`, `/account`, `/api/*`
 - **Public routes:** `/`, `/about`, `/login`, `/setup`
 ### Account Management
 Access `/account` to:
 - View current username
 - Change your password
 - Logout
 ### Environment Variables
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `STEGASOO_AUTH_ENABLED` | `true` | Enable/disable authentication |
 | `STEGASOO_HTTPS_ENABLED` | `false` | Enable HTTPS with self-signed certs |
 | `STEGASOO_HOSTNAME` | `localhost` | Hostname for certificate generation |
 ### Enabling HTTPS
 ```bash
 # Enable HTTPS
 export STEGASOO_HTTPS_ENABLED=true
 export STEGASOO_HOSTNAME=stegasoo.local  # Optional: your hostname
 cd frontends/web
 python app.py
 ```
 On first run with HTTPS enabled:
 - Generates RSA 2048-bit private key
 - Creates self-signed X.509 certificate (365 days validity)
 - Stores in `frontends/web/certs/`
 - Server starts on https://localhost:5000
 **Note:** Browsers will show a security warning for self-signed certificates. This is expected for home network use.
 **Tip:** To avoid browser warnings, use [mkcert](https://github.com/FiloSottile/mkcert) to generate locally-trusted certificates:
 ```bash
 # Install mkcert and create local CA (one-time)
 mkcert -install
 # Generate trusted certs for your Pi
 mkcert -key-file key.pem -cert-file cert.pem stegasoo.local localhost 127.0.0.1 YOUR_PI_IP
 # Copy to certs directory
 mv key.pem cert.pem frontends/web/certs/
 ```
 ### Disabling Authentication
 For development or trusted networks:
 ```bash
 export STEGASOO_AUTH_ENABLED=false
 cd frontends/web
 python app.py
 ```
 ### Docker Configuration
 ```yaml
 # docker-compose.yml
 services:
  web:
    environment:
      STEGASOO_AUTH_ENABLED: "true"
      STEGASOO_HTTPS_ENABLED: "true"
      STEGASOO_HOSTNAME: "stegasoo.local"
    volumes:
      - ./instance:/app/frontends/web/instance  # Persist user database
      - ./certs:/app/frontends/web/certs        # Persist SSL certs
 ```
 ### Security Notes
 - Passwords are hashed with Argon2id (time_cost=3, memory_cost=64MB)
 - Single admin user only (no registration)
 - Session-based authentication using Flask sessions
 - Database stored in `instance/stegasoo.db` (add to `.gitignore`)
 ---
 ## Admin Recovery
 ### Overview
 If you forget your admin password, the recovery key is the ONLY way to reset it. Generate and save your recovery key immediately after setup.
 ### Recovery Key Format
 ```
 XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX
 └──────────────────────────────────────┘
  32 alphanumeric characters (8 groups of 4)
 ```
 ### Backup Options
 The recovery key can be saved in multiple ways:
 | Method | Description | Security Level |
 |--------|-------------|----------------|
 | **Text file** | Plain text download | Low - store securely |
 | **QR code** | Obfuscated PNG image | Medium - XOR'd with magic hash |
 | **Stego image** | Hidden in carrier image | High - requires original image |
 ### Generating a Recovery Key
 **During first-run setup:**
 1. Complete the admin account wizard
 2. You'll be prompted to save your recovery key
 3. Choose backup method(s)
 4. Confirm you've saved the key
 **From Account page (admin only):**
 1. Navigate to `/account`
 2. Click "Generate Recovery Key" (or "Regenerate" if one exists)
 3. Save using your preferred method
 4. Check the confirmation box
 5. Click "Save New Key"
 ### QR Code Obfuscation
 QR codes are not plain text - they're XOR'd with a fixed obfuscation key derived from Stegasoo's magic headers. This prevents casual scanning from revealing the key.
 ### Stego Backup
 Hide your recovery key inside an image using Stegasoo itself:
 1. Upload a carrier image (JPG/PNG, 50KB-2MB)
 2. Click the "Stego" button
 3. Download the stego image
 4. **Important:** Keep the original carrier image - you'll need it for extraction
 ### Recovering Your Password
 **URL:** `/recover`
 1. Navigate to the login page
 2. Click "Forgot password?"
 3. **Option A:** Enter recovery key directly
 4. **Option B:** Extract from stego backup:
   - Expand "Extract from stego backup"
   - Upload your stego backup image
   - Upload the original carrier/reference image
   - Click "Extract Key"
 5. Enter and confirm your new password
 6. Click "Reset Password"
 ### CLI Recovery
 For locked-out scenarios where you can't access the web UI:
 ```bash
 stegasoo admin recover --db frontends/web/instance/stegasoo.db
 ```
 You'll be prompted for your recovery key and new password.
 ### Important Notes
 - Recovery keys are instance-bound (tied to the specific database)
 - Regenerating a key invalidates the previous one
 - Store backups in a secure, separate location
 - Without a recovery key, the only option is to delete the database and reconfigure
 ---
 ## Multi-User Support
 ### Overview
 Admins can create up to 16 additional users with role-based access control.
 ### Roles
 | Role | Permissions |
 |------|-------------|
 | **Admin** | Full access: encode, decode, generate, tools, user management, recovery |
 | **User** | Standard access: encode, decode, generate, account settings |
 ### User Management
 **URL:** `/admin/users` (admin only)
 #### Creating Users
 1. Click "Add User"
 2. Enter username
 3. Select role (admin/user)
 4. A temporary password is generated
 5. Share the temporary password securely with the new user
 6. User must change password on first login
 #### Managing Users
 - View all users and their roles
 - Reset user passwords (generates new temp password)
 - Change user roles
 - Delete users (except yourself)
 ### User Limits
 - Maximum 16 users total (including admin)
 - At least one admin must exist
 - Users can't delete or demote the last admin
 ---
@@ -441,6 +692,83 @@ If decryption fails:
 ---
 ### Tools Page
 **URL:** `/tools`
 The Tools page provides utilities for image analysis and manipulation.
 #### EXIF Editor
 View and edit image metadata (EXIF data).
 **Features:**
 - View all EXIF fields from uploaded image
 - Inline editing of individual fields
 - Clear all metadata with one click
 - Download cleaned image
 **Usage:**
 1. Upload an image (JPG recommended - richest EXIF data)
 2. View all metadata fields in a table
 3. Click any field to edit its value
 4. Click "Save" to apply changes
 5. Use "Clear All" to strip all metadata
 6. Download the modified image
 **Common EXIF fields:**
 | Field | Description |
 |-------|-------------|
 | Make/Model | Camera manufacturer and model |
 | DateTime | When the photo was taken |
 | GPSLatitude/GPSLongitude | Location coordinates |
 | Software | Editing software used |
 | Artist | Photographer name |
 **Privacy tip:** Always strip EXIF data before sharing images publicly to remove location and device information.
 #### Peek (Stego Detection)
 Quickly check if an image contains hidden data.
 #### Strip Metadata
 Remove all metadata from an image in one click.
 ---
 ### Account Page
 **URL:** `/account`
 Manage your account settings and preferences.
 #### Password Change
 1. Enter current password
 2. Enter new password (minimum 8 characters)
 3. Confirm new password
 4. Click "Change Password"
 #### Saved Channel Keys (v4.1.0)
 Users can save frequently-used channel keys for quick access:
 1. Click "Add Channel Key"
 2. Enter a name/label for the key
 3. Paste the channel key
 4. Click "Save"
 Saved keys appear in a dropdown during encode/decode operations.
 #### Recovery Key Management (Admin only)
 - View recovery key status (configured/not configured)
 - Generate or regenerate recovery key
 - Download backup options (text, QR, stego)
 ---
 ### About Page
 **URL:** `/about`
@@ -448,10 +776,10 @@ If decryption fails:
 Information about the Stegasoo project, security model, and credits.
 Includes:
- Version information (v3.3.0)
+- Version information (v4.1.0)
- Recent UI improvements
+- Feature highlights
 - Security model overview
- Dependency status (Argon2, QR code support)
+- Dependency status (Argon2, scipy/DCT, QR code support)
 ---
@@ -752,6 +1080,10 @@ Both modes use the same strong encryption (AES-256-GCM with Argon2id key derivat
 |----------|---------|-------------|
 | `FLASK_ENV` | production | Flask environment |
 | `PYTHONPATH` | - | Include `src/` for development |
 | `STEGASOO_AUTH_ENABLED` | `true` | Enable/disable authentication (v4.0.2) |
 | `STEGASOO_HTTPS_ENABLED` | `false` | Enable HTTPS with self-signed certs (v4.0.2) |
 | `STEGASOO_HOSTNAME` | `localhost` | Hostname for certificate CN (v4.0.2) |
 | `STEGASOO_CHANNEL_KEY` | - | Channel key for deployment isolation |
 ### Application Limits
@@ -808,12 +1140,23 @@ services:
      target: web
    ports:
      - "5000:5000"
    environment:
      STEGASOO_AUTH_ENABLED: "true"
      STEGASOO_HTTPS_ENABLED: "false"
      STEGASOO_CHANNEL_KEY: ${STEGASOO_CHANNEL_KEY:-}
    volumes:
      - stegasoo-web-data:/app/frontends/web/instance
      - stegasoo-web-certs:/app/frontends/web/certs
    deploy:
      resources:
        limits:
          memory: 768M
        reservations:
          memory: 384M
 volumes:
  stegasoo-web-data:
  stegasoo-web-certs:
 ```
 ---
--- a/build.sh
+++ b/build.sh
@@ -1,61 +0,0 @@
 #!/bin/bash
 # Stegasoo Build Script
 # Usage: ./build.sh [base|fast|full|clean]
 set -e
 case "${1:-fast}" in
    base)
        # Build base image with all dependencies (run once, or when deps change)
        echo "🔨 Building base image (this takes 5-10 minutes)..."
        docker build -f Dockerfile.base -t stegasoo-base:latest .
        echo "✅ Base image built! Future builds will be fast."
        echo ""
        echo "Optional: Push to registry for team use:"
        echo "  docker tag stegasoo-base:latest yourregistry/stegasoo-base:latest"
        echo "  docker push yourregistry/stegasoo-base:latest"
        ;;
    fast)
        # Fast build using pre-built base image
        if ! docker image inspect stegasoo-base:latest >/dev/null 2>&1; then
            echo "⚠️  Base image not found. Building it first (one-time)..."
            $0 base
        fi
        echo "🚀 Fast build using base image..."
        docker-compose build
        echo "✅ Done! Start with: docker-compose up -d"
        ;;
    full)
        # Full rebuild from scratch (slow, but no base image needed)
        echo "🐢 Full build from scratch (slow)..."
        docker-compose build --no-cache
        echo "✅ Done! Start with: docker-compose up -d"
        ;;
    clean)
        # Clean up everything
        echo "🧹 Cleaning up..."
        docker-compose down --rmi local -v 2>/dev/null || true
        docker rmi stegasoo-base:latest 2>/dev/null || true
        echo "✅ Cleaned!"
        ;;
    *)
        echo "Stegasoo Build Script"
        echo ""
        echo "Usage: $0 [command]"
        echo ""
        echo "Commands:"
        echo "  base   Build the base image (one-time, 5-10 min)"
        echo "  fast   Fast build using base image (default, ~10 sec)"
        echo "  full   Full rebuild from scratch (slow, no base needed)"
        echo "  clean  Remove all images and volumes"
        echo ""
        echo "Typical workflow:"
        echo "  1. First time:  $0 base"
        echo "  2. Daily dev:   $0 fast  (or just 'docker-compose build')"
        echo "  3. Deps change: $0 base  (rebuild base image)"
        ;;
 esac
--- a/check_scipy.py
+++ b/check_scipy.py
@@ -1,170 +0,0 @@
 #!/usr/bin/env python3
 """
 Diagnostic script to check for scipy/numpy issues.
 Run this BEFORE starting the web app.
 Usage:
    python check_scipy.py
 """
 import sys
 print(f"Python version: {sys.version}")
 print()
 # Check numpy
 try:
    import numpy as np
    print(f"NumPy version: {np.__version__}")
    print(f"NumPy config:")
    np.show_config()
 except ImportError as e:
    print(f"NumPy not installed: {e}")
 except Exception as e:
    print(f"NumPy error: {e}")
 print()
 print("-" * 50)
 print()
 # Check scipy
 try:
    import scipy
    print(f"SciPy version: {scipy.__version__}")
 except ImportError as e:
    print(f"SciPy not installed: {e}")
 print()
 # Check PIL
 try:
    from PIL import Image
    print(f"Pillow version: {Image.__version__}")
 except ImportError as e:
    print(f"Pillow not installed: {e}")
 print()
 print("-" * 50)
 print()
 # Test scipy DCT directly
 print("Testing scipy DCT...")
 try:
    from scipy.fftpack import dct, idct
    import numpy as np
    # Create test array
    test = np.random.rand(8, 8).astype(np.float64)
    print(f"Input array shape: {test.shape}, dtype: {test.dtype}")
    # Test 1D DCT
    row = test[0, :]
    result = dct(row, norm='ortho')
    print(f"1D DCT result shape: {result.shape}, dtype: {result.dtype}")
    # Test 2D DCT (the potentially problematic operation)
    result2d = dct(dct(test.T, norm='ortho').T, norm='ortho')
    print(f"2D DCT result shape: {result2d.shape}, dtype: {result2d.dtype}")
    # Test inverse
    recovered = idct(idct(result2d.T, norm='ortho').T, norm='ortho')
    error = np.max(np.abs(test - recovered))
    print(f"Round-trip error: {error}")
    if error < 1e-10:
        print("✓ scipy DCT working correctly")
    else:
        print("⚠ scipy DCT has precision issues")
 except Exception as e:
    print(f"✗ scipy DCT failed: {e}")
    import traceback
    traceback.print_exc()
 print()
 print("-" * 50)
 print()
 # Test with larger array (more like real image processing)
 print("Testing with larger arrays (512x512)...")
 try:
    from scipy.fftpack import dct, idct
    import numpy as np
    import gc
    # Simulate processing many 8x8 blocks
    large_array = np.random.rand(512, 512).astype(np.float64)
    print(f"Large array shape: {large_array.shape}, size: {large_array.nbytes} bytes")
    count = 0
    for y in range(0, 512, 8):
        for x in range(0, 512, 8):
            block = large_array[y:y+8, x:x+8].copy()
            dct_block = dct(dct(block.T, norm='ortho').T, norm='ortho')
            recovered = idct(idct(dct_block.T, norm='ortho').T, norm='ortho')
            large_array[y:y+8, x:x+8] = recovered
            count += 1
    print(f"Processed {count} blocks successfully")
    del large_array
    gc.collect()
    print("✓ Large array processing completed")
 except Exception as e:
    print(f"✗ Large array processing failed: {e}")
    import traceback
    traceback.print_exc()
 print()
 print("-" * 50)
 print()
 # Test PIL with large image
 print("Testing PIL with large image...")
 try:
    from PIL import Image
    import io
    # Create a large test image
    img = Image.new('RGB', (4000, 3000), color=(128, 128, 128))
    # Save to bytes
    buffer = io.BytesIO()
    img.save(buffer, format='PNG')
    img_bytes = buffer.getvalue()
    print(f"Test image size: {len(img_bytes)} bytes")
    # Re-open and process
    buffer2 = io.BytesIO(img_bytes)
    img2 = Image.open(buffer2)
    print(f"Re-opened image: {img2.size}, mode: {img2.mode}")
    # Convert to numpy array
    import numpy as np
    arr = np.array(img2)
    print(f"NumPy array: {arr.shape}, dtype: {arr.dtype}")
    # Clean up
    img.close()
    img2.close()
    buffer.close()
    buffer2.close()
    del arr
    gc.collect()
    print("✓ PIL large image test completed")
 except Exception as e:
    print(f"✗ PIL test failed: {e}")
    import traceback
    traceback.print_exc()
 print()
 print("=" * 50)
 print("Diagnostics complete")
 print()
 print("If no errors above but web app still crashes, try:")
 print("1. pip install --upgrade scipy numpy pillow")
 print("2. pip install scipy==1.11.4 numpy==1.26.4  # Known stable versions")
 print("3. Check if using conda vs pip (mixing can cause issues)")
--- a/data/WebUI.webp
+++ b/data/WebUI.webp
--- a/data/WebUI_About.webp
+++ b/data/WebUI_About.webp
--- a/data/WebUI_Account.webp
+++ b/data/WebUI_Account.webp
--- a/data/WebUI_Decode.webp
+++ b/data/WebUI_Decode.webp
--- a/data/WebUI_Encode.webp
+++ b/data/WebUI_Encode.webp
--- a/data/WebUI_Generate.webp
+++ b/data/WebUI_Generate.webp
--- a/data/WebUI_Login.webp
+++ b/data/WebUI_Login.webp
--- a/data/WebUI_Setup.webp
+++ b/data/WebUI_Setup.webp
--- a/debug_jpegio.py
+++ b/debug_jpegio.py
@@ -1,215 +0,0 @@
 #!/usr/bin/env python3
 """
 Debug script for DCT/jpegio extraction issues.
 Run from the stegasoo directory.
 """
 import sys
 import struct
 from pathlib import Path
 sys.path.insert(0, str(Path(__file__).parent / 'src'))
 import hashlib
 import numpy as np
 # Check for jpegio
 try:
    import jpegio as jio
    print("✓ jpegio available")
 except ImportError:
    print("✗ jpegio NOT available")
    sys.exit(1)
 def get_usable_positions(coef_array, min_magnitude=2):
    """Get positions of usable coefficients."""
    positions = []
    h, w = coef_array.shape
    for row in range(h):
        for col in range(w):
            # Skip DC coefficients (top-left of each 8x8 block)
            if (row % 8 == 0) and (col % 8 == 0):
                continue
            if abs(coef_array[row, col]) >= min_magnitude:
                positions.append((row, col))
    return positions
 def generate_order(num_positions, seed):
    """Generate pseudo-random order for coefficient selection."""
    hash_bytes = hashlib.sha256(seed + b"jpeg_coef_order").digest()
    rng = np.random.RandomState(int.from_bytes(hash_bytes[:4], 'big'))
    order = list(range(num_positions))
    rng.shuffle(order)
    return order
 def extract_bits(coef_array, positions, order, num_bits):
    """Extract bits from coefficients."""
    bits = []
    for i, pos_idx in enumerate(order):
        if i >= num_bits:
            break
        row, col = positions[pos_idx]
        coef = coef_array[row, col]
        bits.append(coef & 1)
    return bits
 def bits_to_bytes(bits):
    """Convert list of bits to bytes."""
    result = []
    for i in range(0, len(bits), 8):
        byte_bits = bits[i:i+8]
        if len(byte_bits) == 8:
            byte_val = sum(byte_bits[j] << (7-j) for j in range(8))
            result.append(byte_val)
    return bytes(result)
 def main():
    if len(sys.argv) < 3:
        print("Usage: python debug_jpegio.py <stego_image.jpg> <reference_photo>")
        print("\nOptional: add passphrase, pin, key path")
        print("  python debug_jpegio.py stego.jpg ref.jpg 'passphrase' '123456' key.pem")
        sys.exit(1)
    stego_path = sys.argv[1]
    ref_path = sys.argv[2]
    passphrase = sys.argv[3] if len(sys.argv) > 3 else "test"
    pin = sys.argv[4] if len(sys.argv) > 4 else ""
    key_path = sys.argv[5] if len(sys.argv) > 5 else None
    print(f"\n{'='*60}")
    print("JPEGIO DCT EXTRACTION DEBUG")
    print(f"{'='*60}")
    print(f"Stego image: {stego_path}")
    print(f"Reference:   {ref_path}")
    print(f"Passphrase:  '{passphrase}'")
    print(f"PIN:         '{pin}'")
    print(f"Key:         {key_path}")
    # Load stego image with jpegio
    print(f"\n[1] Loading stego image with jpegio...")
    try:
        jpeg = jio.read(stego_path)
        print(f"    ✓ jpegio.read() succeeded")
        print(f"    Number of components: {len(jpeg.coef_arrays)}")
        for i, arr in enumerate(jpeg.coef_arrays):
            print(f"    Component {i}: shape={arr.shape}, dtype={arr.dtype}")
    except Exception as e:
        print(f"    ✗ Failed: {e}")
        sys.exit(1)
    # Get coefficient array (channel 0)
    coef_array = jpeg.coef_arrays[0]
    print(f"\n[2] Coefficient array analysis...")
    print(f"    Shape: {coef_array.shape}")
    print(f"    Non-zero coefficients: {np.count_nonzero(coef_array)}")
    print(f"    Min value: {coef_array.min()}")
    print(f"    Max value: {coef_array.max()}")
    # Get usable positions
    print(f"\n[3] Finding usable positions (|coef| >= 2, non-DC)...")
    positions = get_usable_positions(coef_array)
    print(f"    Usable positions: {len(positions)}")
    print(f"    Capacity: ~{len(positions) // 8} bytes")
    # Generate seed (this needs to match the encode seed!)
    print(f"\n[4] Generating seed...")
    # Load reference photo
    ref_data = Path(ref_path).read_bytes()
    ref_hash = hashlib.sha256(ref_data).digest()
    print(f"    Reference hash: {ref_hash[:8].hex()}...")
    # Load RSA key if provided
    rsa_component = b""
    if key_path:
        try:
            from stegasoo import load_rsa_key
            key_data = Path(key_path).read_bytes()
            # Try without password first
            try:
                rsa_key = load_rsa_key(key_data, password=None)
            except:
                rsa_key = load_rsa_key(key_data, password="testpass")
            # Get public key bytes for seed
            from cryptography.hazmat.primitives import serialization
            pub_bytes = rsa_key.public_key().public_bytes(
                encoding=serialization.Encoding.DER,
                format=serialization.PublicFormat.SubjectPublicKeyInfo
            )
            rsa_component = hashlib.sha256(pub_bytes).digest()
            print(f"    RSA key loaded, hash: {rsa_component[:8].hex()}...")
        except Exception as e:
            print(f"    ✗ Could not load RSA key: {e}")
    # Build seed like stegasoo does
    # This is the critical part - must match encoding!
    seed_parts = [
        ref_hash,
        passphrase.encode('utf-8'),
        pin.encode('utf-8') if pin else b"",
        rsa_component,
    ]
    seed = hashlib.sha256(b"".join(seed_parts)).digest()
    print(f"    Combined seed: {seed[:8].hex()}...")
    # Generate order
    print(f"\n[5] Generating coefficient order...")
    order = generate_order(len(positions), seed)
    print(f"    First 10 indices: {order[:10]}")
    # Try to extract header
    print(f"\n[6] Extracting header (first 80 bits = 10 bytes)...")
    HEADER_SIZE = 10
    header_bits = extract_bits(coef_array, positions, order, HEADER_SIZE * 8)
    header_bytes = bits_to_bytes(header_bits)
    print(f"    Raw header bytes: {header_bytes.hex()}")
    print(f"    As ASCII (if printable): {repr(header_bytes)}")
    # Check for JPGS magic
    JPEGIO_MAGIC = b'JPGS'
    if header_bytes[:4] == JPEGIO_MAGIC:
        print(f"    ✓ Found JPEGIO magic bytes!")
        version = header_bytes[4]
        flags = header_bytes[5]
        data_length = struct.unpack('>I', header_bytes[6:10])[0]
        print(f"    Version: {version}")
        print(f"    Flags: {flags}")
        print(f"    Data length: {data_length} bytes")
        if data_length > 0 and data_length < len(positions) // 8:
            print(f"\n[7] Extracting payload ({data_length} bytes)...")
            total_bits = (HEADER_SIZE + data_length) * 8
            all_bits = extract_bits(coef_array, positions, order, total_bits)
            data_bits = all_bits[HEADER_SIZE * 8:]
            payload = bits_to_bytes(data_bits)
            print(f"    Payload (first 64 bytes): {payload[:64].hex()}")
            print(f"    This should be encrypted data starting with salt/IV")
        else:
            print(f"    ✗ Invalid data length: {data_length}")
    else:
        print(f"    ✗ No JPEGIO magic found")
        print(f"    Expected: {JPEGIO_MAGIC.hex()} ('JPGS')")
        print(f"    Got:      {header_bytes[:4].hex()} ('{header_bytes[:4]}')")
        # Try alternate interpretations
        print(f"\n[7] Trying alternate header interpretations...")
        # Maybe it's scipy DCT format?
        DCT_MAGIC = b'DCTS'
        if header_bytes[:4] == DCT_MAGIC:
            print(f"    Found SCIPY DCT magic - wrong extraction method!")
        else:
            # Show bit distribution
            print(f"    First 32 extracted bits: {header_bits[:32]}")
            # Check if bits look random or patterned
            ones = sum(header_bits[:80])
            print(f"    Bit distribution: {ones}/80 ones ({100*ones/80:.1f}%)")
    print(f"\n{'='*60}")
    print("DEBUG COMPLETE")
    print(f"{'='*60}\n")
 if __name__ == '__main__':
    main()
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -18,6 +18,14 @@ services:
    environment:
      <<: *common-env
      FLASK_ENV: production
      # Authentication (v4.0.2)
      STEGASOO_AUTH_ENABLED: ${STEGASOO_AUTH_ENABLED:-true}
      STEGASOO_HTTPS_ENABLED: ${STEGASOO_HTTPS_ENABLED:-false}
      STEGASOO_HOSTNAME: ${STEGASOO_HOSTNAME:-localhost}
    volumes:
      # Persist auth database and SSL certs (v4.0.2)
      - stegasoo-web-data:/app/frontends/web/instance
      - stegasoo-web-certs:/app/frontends/web/certs
    restart: unless-stopped
    deploy:
      resources:
@@ -45,3 +53,10 @@ services:
          memory: 768M
        reservations:
          memory: 384M
 # Named volumes for persistent data
 volumes:
  stegasoo-web-data:
    driver: local
  stegasoo-web-certs:
    driver: local
--- a/docs/TEMPLATES.md
+++ b/docs/TEMPLATES.md
@@ -0,0 +1,361 @@
 # Stegasoo Web Templates Specification
 Quick reference for all Jinja2 templates in `frontends/web/templates/`.
 ## Table of Contents
 - [Layout](#layout)
 - [Auth & Setup](#auth--setup)
 - [Core Features](#core-features)
 - [Tools & Account](#tools--account)
 - [Admin](#admin)
 ---
 ## Layout
 ### `base.html`
 **Purpose:** Master layout template - all pages extend this.
 | Block | Description |
 |-------|-------------|
 | `{% block title %}` | Page title |
 | `{% block content %}` | Main page content |
 | `{% block scripts %}` | Page-specific JS |
 **Key Elements:**
 - `nav.navbar` - Bootstrap 5 navbar with logo, links, auth buttons
 - `div.toast-container` - Flash message toasts (10s auto-dismiss)
 - `main.container` - Content wrapper
 - `footer` - Copyright + version
 **Variables:** `is_authenticated`, `username`, `is_admin`
 ---
 ## Auth & Setup
 ### `login.html`
 **Route:** `/login`
 **Form:** `POST /login`
 - `username` - text input
 - `password` - password input
 - "Forgot password?" link to `/recover`
 **JS:** `static/js/auth.js` - password toggle
 ---
 ### `setup.html`
 **Route:** `/setup` (first-run only)
 **Form:** `POST /setup`
 - `username` - admin username
 - `password` - password (min 8 chars)
 - `password_confirm` - confirmation
 **JS:** Password confirmation validation
 ---
 ### `setup_recovery.html`
 **Route:** `/setup/recovery`
 **Form:** `POST /setup/recovery`
 - `recovery_key` - hidden, pre-generated
 - `action` - "save" or "skip"
 - Checkbox confirmation required for save
 **Features:**
 - Recovery key display (readonly input)
 - Copy to clipboard button
 - QR code image (if available)
 - Download options: text file, QR image
 - Stego backup upload form
 ---
 ### `recover.html`
 **Route:** `/recover`
 **Form:** `POST /recover`
 - `recovery_key` - textarea for key input
 - `new_password` - new password
 - `new_password_confirm` - confirmation
 **Accordion:** "Extract from stego backup"
 - `POST /recover/stego` with `stego_image` + `reference_image`
 - Pre-fills recovery key on success
 ---
 ### `regenerate_recovery.html`
 **Route:** `/account/recovery/regenerate` (admin only)
 **Form:** `POST /account/recovery/regenerate`
 - `recovery_key` - hidden field
 - `action` - "save" or "cancel"
 - Confirmation checkbox
 **Features:**
 - New key display
 - QR code (obfuscated)
 - Download: text, QR, stego backup
 - Warning if replacing existing key
 ---
 ## Core Features
 ### `index.html`
 **Route:** `/`
 **Structure:**
 - Hero section with tagline
 - 3 action cards: Encode, Decode, Generate
 - "How It Works" explainer section
 ---
 ### `generate.html`
 **Route:** `/generate`
 **Form:** `POST /generate`
 - `words` - passphrase word count (3-12)
 - `use_pin` - checkbox
 - `pin_length` - PIN digits (6-9)
 - `use_rsa` - checkbox
 - `rsa_bits` - key size (2048/3072/4096)
 **Output panels:**
 - Passphrase display
 - PIN display (if enabled)
 - RSA key + QR (if enabled)
 - Entropy calculator
 **JS:** `static/js/generate.js`
 ---
 ### `encode.html`
 **Route:** `/encode`
 **Form:** `POST /encode` (multipart)
 - `reference_photo` - file upload (drag-drop zone)
 - `carrier_image` - file upload (drag-drop zone)
 - `mode` - radio: DCT (default) / LSB
 - `dct_format` - PNG / JPEG
 - `dct_color` - Color / Grayscale
 - `payload_type` - radio: Text / File
 - `message` - textarea (if text)
 - `embed_file` - file input (if file)
 - `passphrase` - text input
 - `pin` - text input
 - `rsa_key` / `rsa_key_qr` - file inputs
 - `rsa_key_password` - password
 - `channel_key` - select (saved keys) or manual input
 **Panels:**
 - Reference preview with "Hash Acquired" status
 - Carrier preview with capacity info
 - Character counter for message
 **JS:** `static/js/encode.js`, `static/js/stegasoo.js`
 ---
 ### `encode_result.html`
 **Route:** `/encode/result/<file_id>`
 **Elements:**
 - Success message
 - Stego image preview
 - Download button
 - Share button (Web Share API)
 - Mode/capacity info
 - "Encode Another" link
 **Variables:** `file_id`, `filename`, `mode`, `capacity_used`
 ---
 ### `decode.html`
 **Route:** `/decode`
 **Form:** `POST /decode` (multipart)
 - `reference_photo` - file upload
 - `stego_image` - file upload
 - `passphrase` - text input
 - `pin` - text input
 - `rsa_key` / `rsa_key_qr` - file inputs
 - `rsa_key_password` - password
 - `channel_key` - select or manual
 **Output:**
 - Decoded message display
 - File download (if file payload)
 **JS:** `static/js/decode.js`, `static/js/stegasoo.js`
 ---
 ## Tools & Account
 ### `tools.html`
 **Route:** `/tools`
 **Tabbed interface:**
 | Tab | Endpoint | Description |
 |-----|----------|-------------|
 | Capacity | `POST /api/tools/capacity` | Image capacity analysis |
 | Peek | `POST /api/tools/peek` | Check for Stegasoo header |
 | Strip | `POST /api/tools/strip` | Remove hidden data |
 | EXIF | `POST /api/tools/exif/*` | Metadata viewer/editor |
 **EXIF Editor features:**
 - Upload image → view all EXIF fields
 - Inline editing (click field to edit)
 - "Clear All" button
 - "Save" / "Download" buttons
 **JS:** `static/js/tools.js`
 ---
 ### `account.html`
 **Route:** `/account`
 **Sections:**
 1. **User Info** - Username, role badge, logout link
 2. **Recovery Key** (admin only)
   - Status: Configured / Not Set
   - Generate/Regenerate button
   - Disable button
 3. **Password Change**
   - `current_password`
   - `new_password`
   - `new_password_confirm`
 4. **Saved Channel Keys**
   - List of saved keys with edit/delete
   - "Add Key" form (name + key)
   - Max 10 keys per user
 **Variables:** `username`, `is_admin`, `has_recovery`, `channel_keys`
 ---
 ### `about.html`
 **Route:** `/about`
 **Sections:**
 - Version info + feature badges
 - Security model explanation
 - Channel key QR (if configured)
 - Dependency status table
 - Credits + links
 **Variables:** `version`, `has_dct`, `has_qr_write`, `has_qr_read`, `channel_key`, `channel_qr`
 ---
 ## Admin
 ### `admin/users.html`
 **Route:** `/admin/users`
 **Table columns:** Username | Role | Created | Actions
 **Actions per user:**
 - Reset Password button
 - Delete button (disabled for self)
 **Header:**
 - User count: "X of 16 users"
 - "Add User" button (modal trigger)
 **Modal:** Add User form
 - `username` input
 - `role` select (admin/user)
 - Auto-generated temp password display
 ---
 ### `admin/user_new.html`
 **Route:** `/admin/users/new`
 **Form:** `POST /admin/users/new`
 - `username` - text input
 - `role` - select (user/admin)
 Redirects to `user_created.html` on success.
 ---
 ### `admin/user_created.html`
 **Route:** `/admin/users/created`
 **Display:**
 - Success message
 - Username
 - Temporary password (copy button)
 - "User must change password on first login" notice
 - Back to users link
 ---
 ### `admin/password_reset.html`
 **Route:** `/admin/users/<id>/password-reset`
 **Display:**
 - Success message
 - New temporary password
 - Copy button
 - Back link
 ---
 ## Common Patterns
 ### Drag-Drop Upload Zones
 ```html
 <div class="upload-zone" id="referenceZone">
    <input type="file" name="reference_photo" accept="image/*">
    <div class="preview"></div>
    <div class="status"></div>
 </div>
 ```
 ### Password Toggle
 ```html
 <div class="input-group">
    <input type="password" id="passwordInput">
    <button onclick="togglePassword('passwordInput', this)">
        <i class="bi bi-eye"></i>
    </button>
 </div>
 ```
 ### Toast Flash Messages
 Rendered in `base.html`, auto-dismiss after 10 seconds:
 - `success` → green
 - `warning` → yellow
 - `error` → red
 ---
 ## External JS Files
 | File | Used By |
 |------|---------|
 | `static/js/stegasoo.js` | encode, decode, about |
 | `static/js/auth.js` | login, setup, recover, account |
 | `static/js/generate.js` | generate |
 | `static/js/encode.js` | encode |
 | `static/js/decode.js` | decode |
 | `static/js/tools.js` | tools |
--- a/examples/README.md
+++ b/examples/README.md
@@ -0,0 +1,48 @@
 # Stegasoo Examples
 This directory contains example scripts demonstrating how to use Stegasoo.
 ## Prerequisites
 Install Stegasoo first:
 ```bash
 pip install stegasoo
 # Or for development:
 pip install -e ".[all]"
 ```
 ## Examples
 ### basic_usage.py
 Basic encode/decode workflow with a text message.
 ```bash
 python basic_usage.py
 ```
 ### embed_file.py
 Embed and extract files (documents, images, etc.) inside carrier images.
 ```bash
 python embed_file.py
 ```
 ### channel_keys.py
 Use channel keys to create private communication channels for groups.
 ```bash
 python channel_keys.py
 ```
 ## Test Images
 You'll need to provide your own images:
 - `my_secret_photo.png` - Your reference photo (keep this secret!)
 - `carrier.png` - The image that will carry your hidden message
 For testing, you can use any PNG or BMP image. JPEG carriers are supported with DCT mode.
--- a/examples/basic_usage.py
+++ b/examples/basic_usage.py
@@ -0,0 +1,59 @@
 #!/usr/bin/env python3
 """
 Basic Stegasoo Usage Example
 This example demonstrates how to encode and decode a secret message
 using the Stegasoo library.
 """
 from pathlib import Path
 import stegasoo
 def main():
    # Load your images
    # The reference photo is your "key" - keep it secret!
    reference_photo = Path("my_secret_photo.png").read_bytes()
    carrier_image = Path("carrier.png").read_bytes()
    # Your secret message
    message = "This is my secret message!"
    # Your credentials
    passphrase = "correct horse battery staple"  # Use 4+ words
    pin = "123456"  # 6-9 digits
    # === ENCODE ===
    print("Encoding message...")
    result = stegasoo.encode(
        message=message,
        reference_photo=reference_photo,
        carrier_image=carrier_image,
        passphrase=passphrase,
        pin=pin,
    )
    # Save the stego image
    output_path = Path(f"secret_{result.suggested_filename}")
    output_path.write_bytes(result.stego_image)
    print(f"Saved to: {output_path}")
    print(f"Capacity used: {result.capacity_used_percent:.1f}%")
    # === DECODE ===
    print("\nDecoding message...")
    stego_image = output_path.read_bytes()
    decoded = stegasoo.decode(
        stego_image=stego_image,
        reference_photo=reference_photo,
        passphrase=passphrase,
        pin=pin,
    )
    print(f"Decoded message: {decoded.message}")
    print(f"Message type: {decoded.payload_type}")
 if __name__ == "__main__":
    main()
--- a/examples/channel_keys.py
+++ b/examples/channel_keys.py
@@ -0,0 +1,72 @@
 #!/usr/bin/env python3
 """
 Channel Keys Example
 Channel keys allow you to create private communication channels.
 Only people with the same channel key can decode messages.
 """
 from pathlib import Path
 import stegasoo
 from stegasoo.channel import generate_channel_key, get_channel_fingerprint
 def main():
    # Generate a channel key for your group
    channel_key = generate_channel_key()
    fingerprint = get_channel_fingerprint(channel_key)
    print("=== Channel Key Generated ===")
    print(f"Key: {channel_key}")
    print(f"Fingerprint: {fingerprint}")
    print("\nShare this key securely with your group members!")
    print("-" * 40)
    # Load images
    reference_photo = Path("my_secret_photo.png").read_bytes()
    carrier_image = Path("carrier.png").read_bytes()
    # Encode with channel key
    print("\nEncoding message with channel key...")
    result = stegasoo.encode(
        message="Secret group message!",
        reference_photo=reference_photo,
        carrier_image=carrier_image,
        passphrase="correct horse battery staple",
        pin="123456",
        channel_key=channel_key,  # Add the channel key
    )
    stego_data = result.stego_image
    print(f"Encoded successfully!")
    # Decode with correct channel key
    print("\nDecoding with correct channel key...")
    decoded = stegasoo.decode(
        stego_image=stego_data,
        reference_photo=reference_photo,
        passphrase="correct horse battery staple",
        pin="123456",
        channel_key=channel_key,  # Same channel key
    )
    print(f"Message: {decoded.message}")
    # Try to decode with wrong channel key
    print("\nTrying to decode with wrong channel key...")
    wrong_key = generate_channel_key()
    try:
        stegasoo.decode(
            stego_image=stego_data,
            reference_photo=reference_photo,
            passphrase="correct horse battery staple",
            pin="123456",
            channel_key=wrong_key,  # Different channel key
        )
        print("ERROR: Should have failed!")
    except (stegasoo.DecryptionError, stegasoo.ExtractionError):
        print("Correctly rejected - wrong channel key!")
 if __name__ == "__main__":
    main()
--- a/examples/embed_file.py
+++ b/examples/embed_file.py
@@ -0,0 +1,78 @@
 #!/usr/bin/env python3
 """
 File Embedding Example
 This example demonstrates how to embed a file (like a document or image)
 inside a carrier image using Stegasoo.
 """
 from pathlib import Path
 import stegasoo
 from stegasoo.models import FilePayload
 def main():
    # Load images
    reference_photo = Path("my_secret_photo.png").read_bytes()
    carrier_image = Path("carrier.png").read_bytes()
    # Load the file to embed
    secret_file = Path("secret_document.pdf")
    file_data = secret_file.read_bytes()
    # Create a FilePayload
    payload = FilePayload(
        filename=secret_file.name,
        data=file_data,
        mime_type="application/pdf",
    )
    # Credentials
    passphrase = "correct horse battery staple"
    pin = "123456"
    # Check capacity first
    capacity = stegasoo.calculate_capacity(carrier_image)
    print(f"Carrier capacity: {capacity['capacity_bytes']:,} bytes")
    print(f"File size: {len(file_data):,} bytes")
    if len(file_data) > capacity["capacity_bytes"]:
        print("Error: File too large for this carrier!")
        return
    # Encode the file
    print("\nEmbedding file...")
    result = stegasoo.encode(
        file_payload=payload,
        reference_photo=reference_photo,
        carrier_image=carrier_image,
        passphrase=passphrase,
        pin=pin,
    )
    output_path = Path(f"contains_file_{result.suggested_filename}")
    output_path.write_bytes(result.stego_image)
    print(f"Saved to: {output_path}")
    # Decode and extract the file
    print("\nExtracting file...")
    decoded = stegasoo.decode(
        stego_image=output_path.read_bytes(),
        reference_photo=reference_photo,
        passphrase=passphrase,
        pin=pin,
    )
    if decoded.payload_type == "file":
        extracted_path = Path(f"extracted_{decoded.filename}")
        extracted_path.write_bytes(decoded.file_data)
        print(f"Extracted: {extracted_path}")
        print(f"Original filename: {decoded.filename}")
        print(f"MIME type: {decoded.mime_type}")
    else:
        print(f"Unexpected payload type: {decoded.payload_type}")
 if __name__ == "__main__":
    main()
--- a/frontends/api/API_UPDATE_SUMMARY_V3.2.0.md
+++ b/frontends/api/API_UPDATE_SUMMARY_V3.2.0.md
@@ -1,500 +0,0 @@
 # API Update Summary for v3.2.0
 ## Overview
 The FastAPI REST API has been updated to align with Stegasoo v3.2.0's breaking changes:
 1. **Removed date dependency** - No `date_str` field in requests
 2. **Renamed day_phrase → passphrase** - Updated all request/response models
 3. **Updated generation** - Now generates single passphrase instead of daily phrases
 ## Breaking Changes
 ### Request Model Changes
 #### 1. EncodeRequest & EncodeFileRequest
 **Before (v3.1.0):**
 ```python
 class EncodeRequest(BaseModel):
    message: str
    reference_photo_base64: str
    carrier_image_base64: str
    day_phrase: str  # ← Changed to passphrase
    pin: str = ""
    rsa_key_base64: Optional[str] = None
    rsa_password: Optional[str] = None
    date_str: Optional[str] = None  # ← REMOVED
    embed_mode: EmbedModeType = "lsb"
 ```
 **After (v3.2.0):**
 ```python
 class EncodeRequest(BaseModel):
    message: str
    reference_photo_base64: str
    carrier_image_base64: str
    passphrase: str = Field(description="Passphrase (v3.2.0: renamed from day_phrase)")
    pin: str = ""
    rsa_key_base64: Optional[str] = None
    rsa_password: Optional[str] = None
    # date_str removed in v3.2.0
    embed_mode: EmbedModeType = "lsb"
    dct_output_format: DctOutputFormatType = "png"
    dct_color_mode: DctColorModeType = "grayscale"
 ```
 #### 2. DecodeRequest
 **Before (v3.1.0):**
 ```python
 class DecodeRequest(BaseModel):
    stego_image_base64: str
    reference_photo_base64: str
    day_phrase: str  # ← Changed to passphrase
    pin: str = ""
    rsa_key_base64: Optional[str] = None
    rsa_password: Optional[str] = None
    embed_mode: ExtractModeType = "auto"
 ```
 **After (v3.2.0):**
 ```python
 class DecodeRequest(BaseModel):
    stego_image_base64: str
    reference_photo_base64: str
    passphrase: str = Field(description="Passphrase (v3.2.0: renamed from day_phrase)")
    pin: str = ""
    rsa_key_base64: Optional[str] = None
    rsa_password: Optional[str] = None
    embed_mode: ExtractModeType = "auto"
 ```
 #### 3. GenerateRequest
 **Before (v3.1.0):**
 ```python
 class GenerateRequest(BaseModel):
    use_pin: bool = True
    use_rsa: bool = False
    pin_length: int = Field(default=6, ge=MIN_PIN_LENGTH, le=MAX_PIN_LENGTH)
    rsa_bits: int = Field(default=2048)
    words_per_phrase: int = Field(default=3, ge=MIN_PHRASE_WORDS, le=MAX_PHRASE_WORDS)
 ```
 **After (v3.2.0):**
 ```python
 class GenerateRequest(BaseModel):
    use_pin: bool = True
    use_rsa: bool = False
    pin_length: int = Field(default=6, ge=MIN_PIN_LENGTH, le=MAX_PIN_LENGTH)
    rsa_bits: int = Field(default=2048)
    words_per_passphrase: int = Field(
        default=DEFAULT_PASSPHRASE_WORDS,  # = 4, was 3
        ge=MIN_PASSPHRASE_WORDS,
        le=MAX_PASSPHRASE_WORDS,
        description="Words per passphrase (v3.2.0: default increased to 4)"
    )
 ```
 ### Response Model Changes
 #### 1. GenerateResponse
 **Before (v3.1.0):**
 ```python
 class GenerateResponse(BaseModel):
    phrases: dict[str, str]  # Monday -> phrase, Tuesday -> phrase, etc.
    pin: Optional[str] = None
    rsa_key_pem: Optional[str] = None
    entropy: dict[str, int]
 ```
 **After (v3.2.0):**
 ```python
 class GenerateResponse(BaseModel):
    passphrase: str = Field(description="Single passphrase (v3.2.0: no daily rotation)")
    pin: Optional[str] = None
    rsa_key_pem: Optional[str] = None
    entropy: dict[str, int]
    # Legacy field for compatibility
    phrases: Optional[dict[str, str]] = Field(
        default=None,
        description="Deprecated: Use 'passphrase' instead"
    )
 ```
 #### 2. EncodeResponse
 **Before (v3.1.0):**
 ```python
 class EncodeResponse(BaseModel):
    stego_image_base64: str
    filename: str
    capacity_used_percent: float
    date_used: str
    day_of_week: str
    embed_mode: str
    output_format: str = "png"
    color_mode: str = "color"
 ```
 **After (v3.2.0):**
 ```python
 class EncodeResponse(BaseModel):
    stego_image_base64: str
    filename: str
    capacity_used_percent: float
    embed_mode: str
    output_format: str = "png"
    color_mode: str = "color"
    # Legacy fields (no longer used in crypto)
    date_used: Optional[str] = Field(
        default=None,
        description="Deprecated: Date no longer used in v3.2.0"
    )
    day_of_week: Optional[str] = Field(
        default=None,
        description="Deprecated: Date no longer used in v3.2.0"
    )
 ```
 ### Endpoint Changes
 #### 1. POST /encode
 **Before (v3.1.0):**
 ```json
 {
  "message": "Secret message",
  "reference_photo_base64": "...",
  "carrier_image_base64": "...",
  "day_phrase": "apple forest thunder",
  "date_str": "2025-01-15",
  "pin": "123456",
  "embed_mode": "lsb"
 }
 ```
 **After (v3.2.0):**
 ```json
 {
  "message": "Secret message",
  "reference_photo_base64": "...",
  "carrier_image_base64": "...",
  "passphrase": "apple forest thunder mountain",
  "pin": "123456",
  "embed_mode": "lsb"
 }
 ```
 #### 2. POST /decode
 **Before (v3.1.0):**
 ```json
 {
  "stego_image_base64": "...",
  "reference_photo_base64": "...",
  "day_phrase": "apple forest thunder",
  "pin": "123456",
  "embed_mode": "auto"
 }
 ```
 **After (v3.2.0):**
 ```json
 {
  "stego_image_base64": "...",
  "reference_photo_base64": "...",
  "passphrase": "apple forest thunder mountain",
  "pin": "123456",
  "embed_mode": "auto"
 }
 ```
 #### 3. POST /generate
 **Response Before (v3.1.0):**
 ```json
 {
  "phrases": {
    "Monday": "apple forest thunder",
    "Tuesday": "banana river lightning",
    ...
  },
  "pin": "123456",
  "rsa_key_pem": null,
  "entropy": {
    "phrase": 33,
    "pin": 20,
    "rsa": 0,
    "total": 53
  }
 }
 ```
 **Response After (v3.2.0):**
 ```json
 {
  "passphrase": "apple forest thunder mountain",
  "pin": "123456",
  "rsa_key_pem": null,
  "entropy": {
    "passphrase": 44,
    "pin": 20,
    "rsa": 0,
    "total": 64
  },
  "phrases": null
 }
 ```
 #### 4. POST /encode/multipart
 **Form Fields Before (v3.1.0):**
 - `day_phrase` (required)
 - `date_str` (optional)
 - `reference_photo` (file)
 - `carrier` (file)
 - ...
 **Form Fields After (v3.2.0):**
 - `passphrase` (required) ← renamed from day_phrase
 - `reference_photo` (file)
 - `carrier` (file)
 - ... (date_str removed)
 **Response Headers Before (v3.1.0):**
 ```
 X-Stegasoo-Date: 2025-01-15
 X-Stegasoo-Day: Wednesday
 X-Stegasoo-Capacity-Percent: 25.5
 X-Stegasoo-Embed-Mode: lsb
 ```
 **Response Headers After (v3.2.0):**
 ```
 X-Stegasoo-Capacity-Percent: 25.5
 X-Stegasoo-Embed-Mode: lsb
 X-Stegasoo-Output-Format: png
 X-Stegasoo-Color-Mode: color
 X-Stegasoo-Version: 3.2.0
 ```
 ### New Status Endpoint Information
 #### GET /
 **Added to response:**
 ```json
 {
  "version": "3.2.0",
  ...
  "breaking_changes": {
    "date_removed": "No date_str parameter needed - encode/decode anytime",
    "passphrase_renamed": "day_phrase → passphrase (single passphrase, no daily rotation)",
    "format_version": 4,
    "backward_compatible": false
  }
 }
 ```
 ## Migration Guide for API Clients
 ### 1. Update Request Bodies
 **Find and replace in client code:**
 ```javascript
 // Before
 {
  day_phrase: "apple forest thunder",
  date_str: "2025-01-15"
 }
 // After
 {
  passphrase: "apple forest thunder mountain"
 }
 ```
 ### 2. Update Response Handling
 **Before:**
 ```javascript
 const response = await fetch('/encode', {
  method: 'POST',
  body: JSON.stringify({
    message: "secret",
    day_phrase: "words",
    date_str: "2025-01-15",
    ...
  })
 });
 const data = await response.json();
 console.log(data.date_used);  // "2025-01-15"
 console.log(data.day_of_week);  // "Wednesday"
 ```
 **After:**
 ```javascript
 const response = await fetch('/encode', {
  method: 'POST',
  body: JSON.stringify({
    message: "secret",
    passphrase: "longer words here now",
    // date_str removed
    ...
  })
 });
 const data = await response.json();
 // date_used and day_of_week are null in v3.2.0
 ```
 ### 3. Update Generate Endpoint Usage
 **Before:**
 ```javascript
 const creds = await fetch('/generate', {
  method: 'POST',
  body: JSON.stringify({ use_pin: true })
 }).then(r => r.json());
 // Use Monday's phrase
 const mondayPhrase = creds.phrases['Monday'];
 ```
 **After:**
 ```javascript
 const creds = await fetch('/generate', {
  method: 'POST',
  body: JSON.stringify({ use_pin: true })
 }).then(r => r.json());
 // Use single passphrase
 const passphrase = creds.passphrase;
 ```
 ### 4. Update Multipart Requests
 **Before (JavaScript fetch):**
 ```javascript
 const formData = new FormData();
 formData.append('day_phrase', 'apple forest thunder');
 formData.append('date_str', '2025-01-15');
 formData.append('reference_photo', refPhotoFile);
 formData.append('carrier', carrierFile);
 formData.append('message', 'secret');
 formData.append('pin', '123456');
 const response = await fetch('/encode/multipart', {
  method: 'POST',
  body: formData
 });
 ```
 **After (JavaScript fetch):**
 ```javascript
 const formData = new FormData();
 formData.append('passphrase', 'apple forest thunder mountain');
 // date_str removed
 formData.append('reference_photo', refPhotoFile);
 formData.append('carrier', carrierFile);
 formData.append('message', 'secret');
 formData.append('pin', '123456');
 const response = await fetch('/encode/multipart', {
  method: 'POST',
  body: formData
 });
 ```
 ## Testing Checklist
 ### Endpoints to Test
 - [ ] GET / - Returns v3.2.0 with breaking_changes info
 - [ ] GET /modes - Returns mode information
 - [ ] POST /generate - Returns single passphrase
 - [ ] POST /encode - Works without date_str
 - [ ] POST /encode/file - Works without date_str
 - [ ] POST /decode - Works without date_str
 - [ ] POST /encode/multipart - Accepts passphrase instead of day_phrase
 - [ ] POST /decode/multipart - Accepts passphrase instead of day_phrase
 - [ ] POST /compare - Still works
 - [ ] POST /will-fit - Still works
 - [ ] POST /image/info - Still works
 - [ ] POST /extract-key-from-qr - Still works
 ### Validation Tests
 - [ ] Reject requests with `day_phrase` field (should get validation error)
 - [ ] Reject requests with `date_str` field (should be ignored or error)
 - [ ] Accept requests with `passphrase` field
 - [ ] Generate response includes `passphrase` field
 - [ ] Generate response has `phrases` as null
 - [ ] Encode response has `date_used` and `day_of_week` as null
 - [ ] Multipart encode works with new field names
 - [ ] Response headers updated correctly
 ## OpenAPI/Swagger Documentation
 The FastAPI auto-generated documentation (/docs and /redoc) will automatically reflect the changes:
 1. **Models updated** - Request/response schemas show new field names
 2. **Descriptions updated** - Field descriptions mention v3.2.0 changes
 3. **Examples updated** - Interactive API explorer uses new field names
 Users can browse to `/docs` to see the updated API specification.
 ## Backward Compatibility
 **Breaking Change:** API v3.2.0 is NOT backward compatible with v3.1.0
 Clients using the old API will encounter:
 1. **Validation errors** - Missing required `passphrase` field
 2. **Unexpected responses** - `phrases` field will be null
 3. **Changed behavior** - Date fields no longer populated
 ### Migration Timeline Recommendation
 1. **Deploy v3.2.0 API** to staging
 2. **Update client applications** to use new field names
 3. **Test thoroughly** with staging API
 4. **Deploy v3.2.0 API** to production
 5. **Notify users** of breaking changes
 Alternatively, run v3.1.0 and v3.2.0 APIs side-by-side on different paths:
 - `/api/v3.1/` - Old API
 - `/api/v3.2/` - New API
 ## Constants Updates
 Used in validation:
 ```python
 from stegasoo.constants import (
    MIN_PASSPHRASE_WORDS,  # = 3
    MAX_PASSPHRASE_WORDS,  # = 12
    DEFAULT_PASSPHRASE_WORDS,  # = 4 (increased from 3)
 )
 ```
 ## Error Messages
 All error messages updated:
 - "day_phrase is required" → "passphrase is required"
 - References to "phrase" now mean "passphrase"
 ## Implementation Status
 ✅ All request models updated
 ✅ All response models updated
 ✅ All endpoints updated
 ✅ Multipart endpoints updated
 ✅ Status endpoint shows breaking changes
 ✅ Constants imported correctly
 ✅ Error handling updated
 ✅ No references to day_phrase in user-facing text
 ✅ No date_str parameters accepted
 Ready for deployment!
--- a/frontends/api/main.py
+++ b/frontends/api/main.py
@@ -49,7 +49,6 @@ from stegasoo import (
    generate_credentials,
    get_channel_status,
    has_argon2,
    has_channel_key,
    has_dct_support,
    set_channel_key,
    validate_channel_key,
@@ -406,11 +405,7 @@ def _resolve_channel_key(channel_key: str | None) -> str | None:
    """
    Resolve channel key from API parameter.
-    Args:
+    Wrapper around library's resolve_channel_key with HTTP exception handling.
        channel_key: API parameter value
            - None: Use server-configured key (auto mode)
            - "": Public mode (no channel key)
            - "XXXX-...": Explicit key
    Returns:
        Resolved channel key to pass to encode/decode
@@ -418,44 +413,27 @@ def _resolve_channel_key(channel_key: str | None) -> str | None:
    Raises:
        HTTPException: If key format is invalid
    """
-    if channel_key is None:
+    from stegasoo.channel import resolve_channel_key
        # Auto mode - use server config
        return None
-    if channel_key == "":
+    try:
-        # Public mode
+        return resolve_channel_key(channel_key)
-        return ""
+    except (ValueError, FileNotFoundError) as e:
-
+        raise HTTPException(400, str(e))
    # Explicit key - validate format
    if not validate_channel_key(channel_key):
        raise HTTPException(
            400, "Invalid channel key format. Expected: XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX"
        )
    return channel_key
 def _get_channel_info(channel_key: str | None) -> tuple[str, str | None]:
    """
    Get channel mode and fingerprint for response.
    Uses library's get_channel_response_info for consistent formatting.
    Returns:
        (mode, fingerprint) tuple
    """
-    if channel_key == "":
+    from stegasoo.channel import get_channel_response_info
        return "public", None
-    if channel_key is not None:
+    info = get_channel_response_info(channel_key)
-        # Explicit key
+    return info["mode"], info.get("fingerprint")
        fingerprint = f"{channel_key[:4]}-••••-••••-••••-••••-••••-••••-{channel_key[-4:]}"
        return "private", fingerprint
    # Auto mode - check server config
    if has_channel_key():
        status = get_channel_status()
        return "private", status.get("fingerprint")
    return "public", None
 # ============================================================================
--- a/frontends/cli/main.py
+++ b/frontends/cli/main.py
@@ -24,11 +24,31 @@ Usage:
    stegasoo channel [SUBCOMMAND]
 """
 import json
 import sys
 import tempfile
 import threading
 import time
 import uuid
 from pathlib import Path
 import click
 # Rich progress bar (optional)
 try:
    from rich.progress import (
        BarColumn,
        Progress,
        SpinnerColumn,
        TaskProgressColumn,
        TextColumn,
        TimeElapsedColumn,
    )
    HAS_RICH = True
 except ImportError:
    HAS_RICH = False
 # Add parent to path for development
 sys.path.insert(0, str(Path(__file__).parent.parent.parent / "src"))
@@ -168,37 +188,25 @@ def resolve_channel_key_option(
    """
    Resolve channel key from CLI options.
    Wrapper around library's resolve_channel_key with Click exception handling.
    Returns:
        None: Use server-configured key (auto mode)
        "": Public mode (no channel key)
        str: Explicit channel key
    """
-    if no_channel:
+    from stegasoo.channel import resolve_channel_key
        return ""  # Public mode
-    if channel_file:
+    try:
-        # Load from file
+        return resolve_channel_key(
-        path = Path(channel_file)
+            value=channel,
-        if not path.exists():
+            file_path=channel_file,
-            raise click.ClickException(f"Channel key file not found: {channel_file}")
+            no_channel=no_channel,
        key = path.read_text().strip()
        if not validate_channel_key(key):
            raise click.ClickException(f"Invalid channel key format in file: {channel_file}")
        return key
    if channel:
        if channel.lower() == "auto":
            return None  # Use server config
        # Explicit key provided
        if not validate_channel_key(channel):
            raise click.ClickException(
                "Invalid channel key format. Expected: XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX\n"
                "Generate a new key with: stegasoo channel generate"
        )
-        return channel
+    except FileNotFoundError as e:
-
+        raise click.ClickException(str(e))
-    # Default: use server-configured key (auto mode)
+    except ValueError as e:
-    return None
+        raise click.ClickException(str(e))
 def format_channel_status_line(quiet: bool = False) -> str | None:
@@ -610,6 +618,73 @@ def channel_clear(project, clear_all, force):
        click.echo("  Mode is now: PUBLIC")
 # ============================================================================
 # PROGRESS BAR UTILITIES (v4.1.2)
 # ============================================================================
 def _generate_progress_job_id() -> str:
    """Generate a unique job ID for progress tracking."""
    return str(uuid.uuid4())[:8]
 def _get_progress_file_path(job_id: str) -> str:
    """Get the progress file path for a job ID."""
    return str(Path(tempfile.gettempdir()) / f"stegasoo_progress_{job_id}.json")
 def _read_progress(job_id: str) -> dict | None:
    """Read progress from file for a job ID."""
    progress_file = _get_progress_file_path(job_id)
    try:
        with open(progress_file) as f:
            return json.load(f)
    except (FileNotFoundError, json.JSONDecodeError):
        return None
 def _cleanup_progress_file(job_id: str) -> None:
    """Remove progress file for a completed job."""
    progress_file = _get_progress_file_path(job_id)
    try:
        Path(progress_file).unlink(missing_ok=True)
    except Exception:
        pass
 def _run_encode_with_progress(encode_func, encode_kwargs: dict, progress_file: str) -> tuple:
    """
    Run encode in a thread and return result.
    Returns:
        (success, result_or_error)
    """
    result_holder = {"result": None, "error": None}
    def run():
        try:
            result_holder["result"] = encode_func(**encode_kwargs, progress_file=progress_file)
        except Exception as e:
            result_holder["error"] = e
    thread = threading.Thread(target=run)
    thread.start()
    return thread, result_holder
 def _format_phase(phase: str) -> str:
    """Format phase name for display."""
    phases = {
        "starting": "Starting",
        "initializing": "Initializing",
        "embedding": "Embedding",
        "saving": "Saving",
        "finalizing": "Finalizing",
        "complete": "Complete",
    }
    return phases.get(phase, phase.capitalize())
 # ============================================================================
 # ENCODE COMMAND
 # ============================================================================
@@ -654,6 +729,7 @@ def channel_clear(project, clear_all, force):
    help="DCT color mode: grayscale (default) or color (preserves original colors)",
 )
@click.option("--quiet", "-q", is_flag=True, help="Suppress output except errors")
@click.option("--progress", is_flag=True, help="Show progress bar (requires rich)")
 def encode_cmd(
    ref,
    carrier,
@@ -673,6 +749,7 @@ def encode_cmd(
    dct_output_format,
    dct_color_mode,
    quiet,
    progress,
 ):
    """
    Encode a secret message or file into an image.
@@ -820,19 +897,63 @@ def encode_cmd(
                click.echo(channel_status)
        # v4.0.0: Include channel_key parameter
-        result = encode(
+        # v4.1.2: Progress bar support
-            message=payload,
+        encode_kwargs = {
-            reference_photo=ref_photo,
+            "message": payload,
-            carrier_image=carrier_image,
+            "reference_photo": ref_photo,
-            passphrase=passphrase,
+            "carrier_image": carrier_image,
-            pin=pin or "",
+            "passphrase": passphrase,
-            rsa_key_data=rsa_key_data,
+            "pin": pin or "",
-            rsa_password=effective_key_password,
+            "rsa_key_data": rsa_key_data,
-            embed_mode=embed_mode,
+            "rsa_password": effective_key_password,
-            dct_output_format=dct_output_format,
+            "embed_mode": embed_mode,
-            dct_color_mode=dct_color_mode,
+            "dct_output_format": dct_output_format,
-            channel_key=resolved_channel_key,
+            "dct_color_mode": dct_color_mode,
            "channel_key": resolved_channel_key,
        }
        if progress and HAS_RICH:
            # Run with progress bar
            job_id = _generate_progress_job_id()
            progress_file = _get_progress_file_path(job_id)
            thread, result_holder = _run_encode_with_progress(encode, encode_kwargs, progress_file)
            with Progress(
                SpinnerColumn(),
                TextColumn("[progress.description]{task.description}"),
                BarColumn(),
                TaskProgressColumn(),
                TimeElapsedColumn(),
                transient=True,
            ) as progress_bar:
                task = progress_bar.add_task("Encoding...", total=100)
                while thread.is_alive():
                    prog = _read_progress(job_id)
                    if prog:
                        percent = prog.get("percent", 0)
                        phase = _format_phase(prog.get("phase", "processing"))
                        progress_bar.update(task, completed=percent, description=f"{phase}...")
                    time.sleep(0.1)
                # Final update
                progress_bar.update(task, completed=100, description="Complete!")
            _cleanup_progress_file(job_id)
            if result_holder["error"]:
                raise result_holder["error"]
            result = result_holder["result"]
        elif progress and not HAS_RICH:
            click.secho(
                "Warning: --progress requires 'rich' package. Install with: pip install rich",
                fg="yellow",
            )
            result = encode(**encode_kwargs)
        else:
            result = encode(**encode_kwargs)
        # Determine output path
        if output:
--- a/frontends/cli/main.py_old
+++ b/frontends/cli/main.py_old
--- a/frontends/web/.env.example
+++ b/frontends/web/.env.example
@@ -0,0 +1,16 @@
 # Stegasoo Web UI Configuration
 # Copy this file to .env and customize
 # Authentication (v4.0.2+)
 STEGASOO_AUTH_ENABLED=true
 STEGASOO_HTTPS_ENABLED=false
 STEGASOO_HOSTNAME=localhost
 STEGASOO_PORT=5000
 # Channel Key (format: XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX)
 # Generate with: stegasoo generate --channel-key
 # Leave empty for public mode
 STEGASOO_CHANNEL_KEY=
 # Flask settings
 FLASK_ENV=production
--- a/frontends/web/WEB_FRONTEND_UPDATE_SUMMARY_V3.2.0.md
+++ b/frontends/web/WEB_FRONTEND_UPDATE_SUMMARY_V3.2.0.md
@@ -1,426 +0,0 @@
 # Web Frontend Update Summary for v3.2.0
 ## Overview
 The Flask web frontend has been updated to align with Stegasoo v3.2.0's breaking changes:
 1. **Removed date dependency** - No date selection or tracking in UI
 2. **Renamed day_phrase → passphrase** - Updated all forms and templates
 3. **Increased default words** - From 3 to 4 for better security
 ## Key Changes
 ### 1. Form Parameter Changes
 #### Generate Page
 **Before (v3.1.0):**
 ```python
 words_per_phrase = int(request.form.get('words_per_phrase', 3))
 # Generated daily phrases for all days of the week
 ```
 **After (v3.2.0):**
 ```python
 words_per_passphrase = int(request.form.get('words_per_passphrase', 4))
 # Generates single passphrase
 ```
 **Template variables changed:**
 - `phrases` → `passphrase` (single string instead of dict)
 - `words_per_phrase` → `words_per_passphrase`
 - `phrase_entropy` → `passphrase_entropy`
 - Removed `days` variable (no longer needed)
 #### Encode Page
 **Before (v3.1.0):**
 ```python
 day_phrase = request.form.get('day_phrase', '')
 client_date = request.form.get('client_date', '').strip()
 day_of_week = get_today_day()  # Used in template
 encode_result = encode(
    ...,
    day_phrase=day_phrase,
    date_str=date_str,
    ...
 )
 ```
 **After (v3.2.0):**
 ```python
 passphrase = request.form.get('passphrase', '')
 # No client_date or day_of_week needed
 encode_result = encode(
    ...,
    passphrase=passphrase,  # Renamed
    # date_str removed
    ...
 )
 ```
 #### Decode Page
 **Before (v3.1.0):**
 ```python
 day_phrase = request.form.get('day_phrase', '')
 stego_date = request.form.get('stego_date', '').strip()
 decode_result = decode(
    ...,
    day_phrase=day_phrase,
    date_str=stego_date if stego_date else None,
    ...
 )
 ```
 **After (v3.2.0):**
 ```python
 passphrase = request.form.get('passphrase', '')
 # No stego_date needed
 decode_result = decode(
    ...,
    passphrase=passphrase,  # Renamed
    # date_str removed
    ...
 )
 ```
 ### 2. Template Context Updates
 **inject_globals() changes:**
 **Added:**
 ```python
 'min_passphrase_words': MIN_PASSPHRASE_WORDS,
 'recommended_passphrase_words': RECOMMENDED_PASSPHRASE_WORDS,
 'default_passphrase_words': DEFAULT_PASSPHRASE_WORDS,
 ```
 **Used for:**
 - Showing passphrase length requirements
 - Default values in generate form
 - Validation messages
 ### 3. Validation Updates
 **Added passphrase validation:**
 ```python
 from stegasoo import validate_passphrase
 # In encode_page()
 result = validate_passphrase(passphrase)
 if not result.is_valid:
    flash(result.error_message, 'error')
    return ...
 # Show warning if passphrase is short
 if result.warning:
    flash(result.warning, 'warning')
 ```
 ### 4. Error Message Updates
 **Before:**
 ```python
 flash('Day phrase is required', 'error')
 flash('Decryption failed. Check your phrase, PIN...', 'error')
 ```
 **After:**
 ```python
 flash('Passphrase is required', 'error')
 flash('Decryption failed. Check your passphrase, PIN...', 'error')
 ```
 ## Template Changes Needed
 These Flask routes will need corresponding template updates:
 ### generate.html
 **Changes needed:**
 ```html
 <!-- Before -->
 <label for="words_per_phrase">Words per phrase</label>
 <input type="number" name="words_per_phrase" value="3">
 {% if generated %}
  <h3>Daily Phrases</h3>
  {% for day in days %}
    <tr>
      <td>{{ day }}</td>
      <td>{{ phrases[day] }}</td>
    </tr>
  {% endfor %}
 {% endif %}
 <!-- After -->
 <label for="words_per_passphrase">Words per passphrase</label>
 <input type="number" name="words_per_passphrase" value="{{ default_passphrase_words }}">
 {% if generated %}
  <h3>Passphrase</h3>
  <div class="passphrase-display">
    <code>{{ passphrase }}</code>
    <p class="help-text">Use this passphrase to encode and decode messages (no date needed!)</p>
  </div>
 {% endif %}
 ```
 **Entropy display:**
 ```html
 <!-- Before -->
 <li>Phrase entropy: {{ phrase_entropy }} bits</li>
 <!-- After -->
 <li>Passphrase entropy: {{ passphrase_entropy }} bits ({{ words_per_passphrase }} words)</li>
 ```
 ### encode.html
 **Changes needed:**
 ```html
 <!-- Before -->
 <label for="day_phrase">Day Phrase</label>
 <input type="text" name="day_phrase" required>
 <label for="client_date">Encoding Date (Optional)</label>
 <input type="date" name="client_date">
 <p class="help-text">Defaults to today: {{ day_of_week }}</p>
 <!-- After -->
 <label for="passphrase">Passphrase</label>
 <input type="text" name="passphrase" required 
       placeholder="Enter at least {{ recommended_passphrase_words }} words">
 <p class="help-text">
  v3.2.0: No date needed! Use your passphrase anytime.
 </p>
 ```
 ### decode.html
 **Changes needed:**
 ```html
 <!-- Before -->
 <label for="day_phrase">Day Phrase</label>
 <input type="text" name="day_phrase" required>
 <label for="stego_date">Encoding Date</label>
 <input type="date" name="stego_date" id="stego_date">
 <p class="help-text">Will be auto-detected from filename if possible</p>
 <script>
 // Auto-detect date from filename
 stegoInput.addEventListener('change', function() {
  const filename = this.files[0]?.name || '';
  const dateMatch = filename.match(/_(\d{4})(\d{2})(\d{2})/);
  if (dateMatch) {
    document.getElementById('stego_date').value = 
      `${dateMatch[1]}-${dateMatch[2]}-${dateMatch[3]}`;
  }
 });
 </script>
 <!-- After -->
 <label for="passphrase">Passphrase</label>
 <input type="text" name="passphrase" required 
       placeholder="Enter your passphrase">
 <p class="help-text">
  v3.2.0: No date needed to decode!
 </p>
 <!-- Remove date detection script -->
 ```
 ### index.html
 **Changes needed:**
 ```html
 <!-- Before -->
 <p>Generate daily passphrases and security credentials</p>
 <p>Hide messages using day-specific phrases</p>
 <!-- After -->
 <p>Generate passphrases and security credentials</p>
 <p>v3.2.0: Simplified - no more daily rotation!</p>
 ```
 ### about.html
 **Add v3.2.0 section:**
 ```html
 <h2>Version 3.2.0 Changes</h2>
 <ul>
  <li><strong>No date dependency</strong> - Encode and decode anytime without tracking dates</li>
  <li><strong>Single passphrase</strong> - No more daily rotation, just remember one strong passphrase</li>
  <li><strong>Better security</strong> - Default passphrase length increased to 4 words</li>
  <li><strong>Asynchronous ready</strong> - Perfect for dead drops and delayed delivery</li>
 </ul>
 ```
 ## JavaScript Changes Needed
 ### Remove date-related code:
 ```javascript
 // REMOVE THIS (date detection from filename)
 function detectDateFromFilename(filename) {
  const match = filename.match(/_(\d{4})(\d{2})(\d{2})/);
  if (match) {
    return `${match[1]}-${match[2]}-${match[3]}`;
  }
  return null;
 }
 // REMOVE THIS (day-of-week display)
 function updateDayOfWeek() {
  const dateInput = document.getElementById('client_date');
  const dayDisplay = document.getElementById('day_display');
  // ...
 }
 ```
 ### Update validation:
 ```javascript
 // Before
 const dayPhrase = document.getElementById('day_phrase').value;
 if (!dayPhrase || dayPhrase.trim().length === 0) {
  alert('Day phrase is required');
  return false;
 }
 // After
 const passphrase = document.getElementById('passphrase').value;
 if (!passphrase || passphrase.trim().length === 0) {
  alert('Passphrase is required');
  return false;
 }
 // Add word count validation
 const words = passphrase.trim().split(/\s+/);
 if (words.length < {{ min_passphrase_words }}) {
  alert(`Passphrase should have at least {{ recommended_passphrase_words }} words`);
  return false;
 }
 ```
 ## CSS Updates
 Add styling for passphrase warnings:
 ```css
 .passphrase-display {
  background: #f5f5f5;
  padding: 15px;
  border-radius: 5px;
  margin: 10px 0;
 }
 .passphrase-display code {
  font-size: 1.2em;
  color: #2c3e50;
  word-break: break-word;
 }
 .help-text.v3-2-0 {
  color: #3498db;
  font-weight: bold;
 }
 .flash.warning {
  background-color: #fff3cd;
  border-left: 4px solid #ffc107;
  color: #856404;
 }
 ```
 ## Migration Notes for Users
 Add to templates:
 ```html
 <div class="alert alert-info">
  <h4>⚠️ v3.2.0 Breaking Changes</h4>
  <p>If you have messages encoded with v3.1.0:</p>
  <ul>
    <li>They cannot be decoded with v3.2.0</li>
    <li>You need the original v3.1.0 installation to decode them</li>
    <li>After decoding, you can re-encode with v3.2.0</li>
  </ul>
 </div>
 ```
 ## Form Field Summary
 ### Changed Field Names
 | Old Name (v3.1.0) | New Name (v3.2.0) | Type |
 |-------------------|-------------------|------|
 | `day_phrase` | `passphrase` | text input |
 | `words_per_phrase` | `words_per_passphrase` | number input |
 | `client_date` | (removed) | date input |
 | `stego_date` | (removed) | date input |
 ### New Validation Attributes
 ```html
 <input type="text" name="passphrase" 
       required
       minlength="{{ min_passphrase_words * 4 }}"
       placeholder="Enter at least {{ recommended_passphrase_words }} words"
       pattern="^\s*\S+(\s+\S+){3,}.*$"
       title="Please enter at least 4 words">
 ```
 ## Testing Checklist
 - [ ] Generate page creates single passphrase
 - [ ] Generate page shows correct entropy (4 words = 44 bits)
 - [ ] Generate page doesn't show day names
 - [ ] Encode page accepts passphrase (not day_phrase)
 - [ ] Encode page doesn't have date selection
 - [ ] Encode page shows v3.2.0 help text
 - [ ] Decode page accepts passphrase
 - [ ] Decode page doesn't have date input
 - [ ] Decode page doesn't auto-detect date from filename
 - [ ] Error messages say "passphrase" not "day phrase"
 - [ ] Validation shows warnings for short passphrases
 - [ ] QR code functionality still works
 - [ ] DCT mode options still work
 - [ ] All flash messages updated
 ## Implementation Status
 ✅ Flask routes updated
 ✅ Form parameter names changed
 ✅ Function calls updated
 ✅ Validation added for passphrases
 ✅ Error messages updated
 ✅ Template context updated
 ⏳ Templates need updating (generate.html, encode.html, decode.html, index.html, about.html)
 ⏳ JavaScript needs updating
 ⏳ CSS styling for v3.2.0 features
 ## Quick Reference
 **To test the Flask app:**
 ```bash
 cd frontends/web
 python app.py
 # Visit http://localhost:5000
 ```
 **Key user-facing changes:**
 1. Generate: Shows one passphrase, not 7 daily phrases
 2. Encode: No date selection, just passphrase
 3. Decode: No date needed, just passphrase
 **Benefits to highlight:**
 - ✅ Simpler UI (fewer fields)
 - ✅ No date tracking needed
 - ✅ Encode today, decode anytime
 - ✅ Perfect for asynchronous communications
--- a/frontends/web/app.py
+++ b/frontends/web/app.py
--- a/frontends/web/auth.py
+++ b/frontends/web/auth.py
@@ -0,0 +1,979 @@
 """
 Stegasoo Authentication Module (v4.1.0)
 Multi-user authentication with role-based access control.
 - Admin user created at first-run setup
 - Admin can create up to 16 additional users
 - Uses Argon2id password hashing
 - Flask sessions for authentication state
 - SQLite3 for user storage
 """
 import functools
 import secrets
 import sqlite3
 import string
 from dataclasses import dataclass
 from pathlib import Path
 from argon2 import PasswordHasher
 from argon2.exceptions import VerifyMismatchError
 from flask import current_app, flash, g, redirect, session, url_for
 # Argon2 password hasher (lighter than stegasoo's 256MB for faster login)
 ph = PasswordHasher(
    time_cost=3,
    memory_cost=65536,  # 64MB
    parallelism=4,
    hash_len=32,
    salt_len=16,
 )
 # Constants
 MAX_USERS = 16  # Plus 1 admin = 17 total
 MAX_CHANNEL_KEYS = 10  # Per user
 ROLE_ADMIN = "admin"
 ROLE_USER = "user"
@dataclass
 class User:
    """User data class."""
    id: int
    username: str
    role: str
    created_at: str
    @property
    def is_admin(self) -> bool:
        return self.role == ROLE_ADMIN
 def get_db_path() -> Path:
    """Get database path in Flask instance folder."""
    instance_path = Path(current_app.instance_path)
    instance_path.mkdir(parents=True, exist_ok=True)
    return instance_path / "stegasoo.db"
 def get_db() -> sqlite3.Connection:
    """Get database connection, cached on Flask g object."""
    if "db" not in g:
        g.db = sqlite3.connect(get_db_path())
        g.db.row_factory = sqlite3.Row
    return g.db
 def close_db(e=None):
    """Close database connection at end of request."""
    db = g.pop("db", None)
    if db is not None:
        db.close()
 def init_db():
    """Initialize database schema with migration support."""
    db = get_db()
    # Check if we need to migrate from old single-user schema
    cursor = db.execute(
        "SELECT name FROM sqlite_master WHERE type='table' AND name='admin_user'"
    )
    has_old_table = cursor.fetchone() is not None
    cursor = db.execute(
        "SELECT name FROM sqlite_master WHERE type='table' AND name='users'"
    )
    has_new_table = cursor.fetchone() is not None
    if has_old_table and not has_new_table:
        # Migrate from old schema
        _migrate_from_single_user(db)
    elif not has_new_table:
        # Fresh install - create new schema
        _create_schema(db)
    else:
        # Existing install - check for new tables (migrations)
        _ensure_channel_keys_table(db)
        _ensure_app_settings_table(db)
 def _create_schema(db: sqlite3.Connection):
    """Create the multi-user schema."""
    db.executescript("""
        CREATE TABLE IF NOT EXISTS users (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            username TEXT NOT NULL UNIQUE,
            password_hash TEXT NOT NULL,
            role TEXT NOT NULL DEFAULT 'user',
            created_at TEXT DEFAULT CURRENT_TIMESTAMP,
            updated_at TEXT DEFAULT CURRENT_TIMESTAMP
        );
        CREATE INDEX IF NOT EXISTS idx_users_username ON users(username);
        CREATE INDEX IF NOT EXISTS idx_users_role ON users(role);
        CREATE TABLE IF NOT EXISTS user_channel_keys (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            user_id INTEGER NOT NULL,
            name TEXT NOT NULL,
            channel_key TEXT NOT NULL,
            created_at TEXT DEFAULT CURRENT_TIMESTAMP,
            last_used_at TEXT,
            FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
            UNIQUE(user_id, channel_key)
        );
        CREATE INDEX IF NOT EXISTS idx_channel_keys_user ON user_channel_keys(user_id);
        -- App-level settings (v4.1.0)
        -- Stores recovery key hash and other instance-wide settings
        CREATE TABLE IF NOT EXISTS app_settings (
            key TEXT PRIMARY KEY,
            value TEXT NOT NULL,
            created_at TEXT DEFAULT CURRENT_TIMESTAMP,
            updated_at TEXT DEFAULT CURRENT_TIMESTAMP
        );
    """)
    db.commit()
 def _migrate_from_single_user(db: sqlite3.Connection):
    """Migrate from old single-user admin_user table to multi-user users table."""
    # Create new table
    _create_schema(db)
    # Copy admin user from old table
    old_user = db.execute(
        "SELECT username, password_hash, created_at FROM admin_user WHERE id = 1"
    ).fetchone()
    if old_user:
        db.execute(
            """
            INSERT INTO users (username, password_hash, role, created_at)
            VALUES (?, ?, 'admin', ?)
            """,
            (old_user["username"], old_user["password_hash"], old_user["created_at"]),
        )
        db.commit()
    # Drop old table
    db.execute("DROP TABLE admin_user")
    db.commit()
 def _ensure_channel_keys_table(db: sqlite3.Connection):
    """Ensure user_channel_keys table exists (migration for existing installs)."""
    cursor = db.execute(
        "SELECT name FROM sqlite_master WHERE type='table' AND name='user_channel_keys'"
    )
    if cursor.fetchone() is None:
        db.executescript("""
            CREATE TABLE IF NOT EXISTS user_channel_keys (
                id INTEGER PRIMARY KEY AUTOINCREMENT,
                user_id INTEGER NOT NULL,
                name TEXT NOT NULL,
                channel_key TEXT NOT NULL,
                created_at TEXT DEFAULT CURRENT_TIMESTAMP,
                last_used_at TEXT,
                FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
                UNIQUE(user_id, channel_key)
            );
            CREATE INDEX IF NOT EXISTS idx_channel_keys_user ON user_channel_keys(user_id);
        """)
        db.commit()
 def _ensure_app_settings_table(db: sqlite3.Connection):
    """Ensure app_settings table exists (v4.1.0 migration)."""
    cursor = db.execute(
        "SELECT name FROM sqlite_master WHERE type='table' AND name='app_settings'"
    )
    if cursor.fetchone() is None:
        db.executescript("""
            CREATE TABLE IF NOT EXISTS app_settings (
                key TEXT PRIMARY KEY,
                value TEXT NOT NULL,
                created_at TEXT DEFAULT CURRENT_TIMESTAMP,
                updated_at TEXT DEFAULT CURRENT_TIMESTAMP
            );
        """)
        db.commit()
 # =============================================================================
 # App Settings (v4.1.0)
 # =============================================================================
 def get_app_setting(key: str) -> str | None:
    """Get an app-level setting value."""
    db = get_db()
    row = db.execute(
        "SELECT value FROM app_settings WHERE key = ?", (key,)
    ).fetchone()
    return row["value"] if row else None
 def set_app_setting(key: str, value: str) -> None:
    """Set an app-level setting value."""
    db = get_db()
    db.execute(
        """
        INSERT INTO app_settings (key, value)
        VALUES (?, ?)
        ON CONFLICT(key) DO UPDATE SET value = ?, updated_at = CURRENT_TIMESTAMP
        """,
        (key, value, value),
    )
    db.commit()
 def delete_app_setting(key: str) -> bool:
    """Delete an app-level setting. Returns True if deleted."""
    db = get_db()
    cursor = db.execute("DELETE FROM app_settings WHERE key = ?", (key,))
    db.commit()
    return cursor.rowcount > 0
 # =============================================================================
 # Recovery Key Management (v4.1.0)
 # =============================================================================
 # Setting key for recovery hash
 RECOVERY_KEY_SETTING = "recovery_key_hash"
 def has_recovery_key() -> bool:
    """Check if a recovery key has been configured."""
    return get_app_setting(RECOVERY_KEY_SETTING) is not None
 def get_recovery_key_hash() -> str | None:
    """Get the stored recovery key hash."""
    return get_app_setting(RECOVERY_KEY_SETTING)
 def set_recovery_key_hash(key_hash: str) -> None:
    """Store a recovery key hash."""
    set_app_setting(RECOVERY_KEY_SETTING, key_hash)
 def clear_recovery_key() -> bool:
    """Remove the recovery key. Returns True if removed."""
    return delete_app_setting(RECOVERY_KEY_SETTING)
 def verify_and_reset_admin_password(recovery_key: str, new_password: str) -> tuple[bool, str]:
    """
    Verify recovery key and reset the first admin's password.
    Args:
        recovery_key: User-provided recovery key
        new_password: New password to set
    Returns:
        (success, message) tuple
    """
    from stegasoo.recovery import verify_recovery_key
    stored_hash = get_recovery_key_hash()
    if not stored_hash:
        return False, "No recovery key configured for this instance"
    if not verify_recovery_key(recovery_key, stored_hash):
        return False, "Invalid recovery key"
    # Find first admin user
    db = get_db()
    admin = db.execute(
        "SELECT id, username FROM users WHERE role = 'admin' ORDER BY id LIMIT 1"
    ).fetchone()
    if not admin:
        return False, "No admin user found"
    # Reset password
    new_hash = ph.hash(new_password)
    db.execute(
        "UPDATE users SET password_hash = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?",
        (new_hash, admin["id"]),
    )
    db.commit()
    # Invalidate all sessions for this user
    invalidate_user_sessions(admin["id"])
    return True, f"Password reset for '{admin['username']}'"
 # =============================================================================
 # User Queries
 # =============================================================================
 def any_users_exist() -> bool:
    """Check if any users have been created (for first-run detection)."""
    db = get_db()
    result = db.execute("SELECT 1 FROM users LIMIT 1").fetchone()
    return result is not None
 def user_exists() -> bool:
    """Alias for any_users_exist() for backwards compatibility."""
    return any_users_exist()
 def get_user_count() -> int:
    """Get total number of users."""
    db = get_db()
    result = db.execute("SELECT COUNT(*) FROM users").fetchone()
    return result[0] if result else 0
 def get_non_admin_count() -> int:
    """Get number of non-admin users."""
    db = get_db()
    result = db.execute("SELECT COUNT(*) FROM users WHERE role != 'admin'").fetchone()
    return result[0] if result else 0
 def can_create_user() -> bool:
    """Check if we can create more users (within limit)."""
    return get_non_admin_count() < MAX_USERS
 def get_user_by_id(user_id: int) -> User | None:
    """Get user by ID."""
    db = get_db()
    row = db.execute(
        "SELECT id, username, role, created_at FROM users WHERE id = ?", (user_id,)
    ).fetchone()
    if row:
        return User(
            id=row["id"],
            username=row["username"],
            role=row["role"],
            created_at=row["created_at"],
        )
    return None
 def get_user_by_username(username: str) -> User | None:
    """Get user by username."""
    db = get_db()
    row = db.execute(
        "SELECT id, username, role, created_at FROM users WHERE username = ?",
        (username,),
    ).fetchone()
    if row:
        return User(
            id=row["id"],
            username=row["username"],
            role=row["role"],
            created_at=row["created_at"],
        )
    return None
 def get_all_users() -> list[User]:
    """Get all users, admins first, then by creation date."""
    db = get_db()
    rows = db.execute(
        """
        SELECT id, username, role, created_at FROM users
        ORDER BY role = 'admin' DESC, created_at ASC
        """
    ).fetchall()
    return [
        User(
            id=row["id"],
            username=row["username"],
            role=row["role"],
            created_at=row["created_at"],
        )
        for row in rows
    ]
 def get_current_user() -> User | None:
    """Get the currently logged-in user from session."""
    user_id = session.get("user_id")
    if user_id:
        return get_user_by_id(user_id)
    return None
 def get_username() -> str:
    """Get current user's username (backwards compatibility)."""
    user = get_current_user()
    return user.username if user else "unknown"
 # =============================================================================
 # Authentication
 # =============================================================================
 def verify_user_password(username: str, password: str) -> User | None:
    """
    Verify password for a user.
    Returns User if valid, None if invalid.
    Also rehashes password if needed.
    """
    db = get_db()
    row = db.execute(
        "SELECT id, username, role, created_at, password_hash FROM users WHERE username = ?",
        (username,),
    ).fetchone()
    if not row:
        return None
    try:
        ph.verify(row["password_hash"], password)
        # Rehash if parameters changed
        if ph.check_needs_rehash(row["password_hash"]):
            new_hash = ph.hash(password)
            db.execute(
                "UPDATE users SET password_hash = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?",
                (new_hash, row["id"]),
            )
            db.commit()
        return User(
            id=row["id"],
            username=row["username"],
            role=row["role"],
            created_at=row["created_at"],
        )
    except VerifyMismatchError:
        return None
 def verify_password(password: str) -> bool:
    """Verify password for current user (backwards compatibility)."""
    user = get_current_user()
    if not user:
        return False
    result = verify_user_password(user.username, password)
    return result is not None
 def is_authenticated() -> bool:
    """Check if current session is authenticated."""
    return session.get("user_id") is not None
 def is_admin() -> bool:
    """Check if current user is an admin."""
    user = get_current_user()
    return user.is_admin if user else False
 def login_user(user: User):
    """Set up session for logged-in user."""
    session["user_id"] = user.id
    session["username"] = user.username
    session["role"] = user.role
    # Legacy compatibility
    session["authenticated"] = True
 def logout_user():
    """Clear session for logout."""
    session.clear()
 # =============================================================================
 # User Management
 # =============================================================================
 def generate_temp_password(length: int = 8) -> str:
    """Generate a random temporary password."""
    alphabet = string.ascii_letters + string.digits
    return "".join(secrets.choice(alphabet) for _ in range(length))
 def validate_username(username: str) -> tuple[bool, str]:
    """
    Validate username format.
    Rules: 3-80 chars, alphanumeric + underscore/hyphen + @/. for email-style
    """
    if not username:
        return False, "Username is required"
    if len(username) < 3:
        return False, "Username must be at least 3 characters"
    if len(username) > 80:
        return False, "Username must be at most 80 characters"
    # Allow: alphanumeric, underscore, hyphen, @, . (for email-style)
    allowed = set(string.ascii_letters + string.digits + "_-@.")
    if not all(c in allowed for c in username):
        return False, "Username can only contain letters, numbers, underscore, hyphen, @ and ."
    # Must start with letter or number
    if username[0] not in string.ascii_letters + string.digits:
        return False, "Username must start with a letter or number"
    return True, ""
 def validate_password(password: str) -> tuple[bool, str]:
    """Validate password requirements."""
    if not password:
        return False, "Password is required"
    if len(password) < 8:
        return False, "Password must be at least 8 characters"
    return True, ""
 def create_user(
    username: str, password: str, role: str = ROLE_USER
 ) -> tuple[bool, str, User | None]:
    """
    Create a new user.
    Returns (success, message, user).
    """
    # Validate username
    valid, msg = validate_username(username)
    if not valid:
        return False, msg, None
    # Validate password
    valid, msg = validate_password(password)
    if not valid:
        return False, msg, None
    # Check if username already exists
    if get_user_by_username(username):
        return False, "Username already exists", None
    # Check user limit (only for non-admin users)
    if role != ROLE_ADMIN and not can_create_user():
        return False, f"Maximum of {MAX_USERS} users reached", None
    # Create user
    password_hash = ph.hash(password)
    db = get_db()
    try:
        cursor = db.execute(
            """
            INSERT INTO users (username, password_hash, role)
            VALUES (?, ?, ?)
            """,
            (username, password_hash, role),
        )
        db.commit()
        user = get_user_by_id(cursor.lastrowid)
        return True, "User created successfully", user
    except sqlite3.IntegrityError:
        return False, "Username already exists", None
 def create_admin_user(username: str, password: str) -> tuple[bool, str]:
    """Create the initial admin user (first-run setup)."""
    if any_users_exist():
        return False, "Admin user already exists"
    success, msg, _ = create_user(username, password, ROLE_ADMIN)
    return success, msg
 def change_password(
    user_id: int, current_password: str, new_password: str
 ) -> tuple[bool, str]:
    """Change a user's password (requires current password)."""
    user = get_user_by_id(user_id)
    if not user:
        return False, "User not found"
    # Verify current password
    if not verify_user_password(user.username, current_password):
        return False, "Current password is incorrect"
    # Validate new password
    valid, msg = validate_password(new_password)
    if not valid:
        return False, msg
    # Update password
    new_hash = ph.hash(new_password)
    db = get_db()
    db.execute(
        "UPDATE users SET password_hash = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?",
        (new_hash, user_id),
    )
    db.commit()
    return True, "Password changed successfully"
 def reset_user_password(user_id: int, new_password: str) -> tuple[bool, str]:
    """Reset a user's password (admin function, no current password required)."""
    user = get_user_by_id(user_id)
    if not user:
        return False, "User not found"
    # Validate new password
    valid, msg = validate_password(new_password)
    if not valid:
        return False, msg
    # Update password
    new_hash = ph.hash(new_password)
    db = get_db()
    db.execute(
        "UPDATE users SET password_hash = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?",
        (new_hash, user_id),
    )
    db.commit()
    # Invalidate user's sessions
    invalidate_user_sessions(user_id)
    return True, "Password reset successfully"
 def delete_user(user_id: int, current_user_id: int) -> tuple[bool, str]:
    """
    Delete a user.
    Cannot delete yourself or the last admin.
    """
    if user_id == current_user_id:
        return False, "Cannot delete yourself"
    user = get_user_by_id(user_id)
    if not user:
        return False, "User not found"
    # Check if this is the last admin
    if user.role == ROLE_ADMIN:
        db = get_db()
        admin_count = db.execute(
            "SELECT COUNT(*) FROM users WHERE role = 'admin'"
        ).fetchone()[0]
        if admin_count <= 1:
            return False, "Cannot delete the last admin"
    # Invalidate user's sessions before deletion
    invalidate_user_sessions(user_id)
    # Delete user
    db = get_db()
    db.execute("DELETE FROM users WHERE id = ?", (user_id,))
    db.commit()
    return True, f"User '{user.username}' deleted"
 def invalidate_user_sessions(user_id: int):
    """
    Invalidate all sessions for a user.
    This is called when a user is deleted or their password is reset.
    Since we use server-side sessions, we increment a "session version"
    that's checked on each request.
    """
    # For Flask's default session (client-side), we can't truly invalidate.
    # But we can add a check - store a "valid_from" timestamp in the DB
    # and compare against session creation time.
    #
    # For now, we'll use a simpler approach: store invalidated user IDs
    # in app config (memory) which gets checked by login_required.
    #
    # This works for single-process deployments (like RPi).
    # For multi-process, would need Redis or DB-backed sessions.
    if "invalidated_users" not in current_app.config:
        current_app.config["invalidated_users"] = set()
    current_app.config["invalidated_users"].add(user_id)
 def is_session_valid() -> bool:
    """Check if current session is still valid (user not deleted/invalidated)."""
    user_id = session.get("user_id")
    if not user_id:
        return False
    # Check if user was invalidated
    invalidated = current_app.config.get("invalidated_users", set())
    if user_id in invalidated:
        return False
    # Check if user still exists
    if not get_user_by_id(user_id):
        return False
    return True
 # =============================================================================
 # Channel Keys
 # =============================================================================
@dataclass
 class ChannelKey:
    """Saved channel key data class."""
    id: int
    user_id: int
    name: str
    channel_key: str
    created_at: str
    last_used_at: str | None
 def get_user_channel_keys(user_id: int) -> list[ChannelKey]:
    """Get all saved channel keys for a user, most recently used first."""
    db = get_db()
    rows = db.execute(
        """
        SELECT id, user_id, name, channel_key, created_at, last_used_at
        FROM user_channel_keys
        WHERE user_id = ?
        ORDER BY last_used_at DESC NULLS LAST, created_at DESC
        """,
        (user_id,),
    ).fetchall()
    return [
        ChannelKey(
            id=row["id"],
            user_id=row["user_id"],
            name=row["name"],
            channel_key=row["channel_key"],
            created_at=row["created_at"],
            last_used_at=row["last_used_at"],
        )
        for row in rows
    ]
 def get_channel_key_by_id(key_id: int, user_id: int) -> ChannelKey | None:
    """Get a specific channel key (ensures user owns it)."""
    db = get_db()
    row = db.execute(
        """
        SELECT id, user_id, name, channel_key, created_at, last_used_at
        FROM user_channel_keys
        WHERE id = ? AND user_id = ?
        """,
        (key_id, user_id),
    ).fetchone()
    if row:
        return ChannelKey(
            id=row["id"],
            user_id=row["user_id"],
            name=row["name"],
            channel_key=row["channel_key"],
            created_at=row["created_at"],
            last_used_at=row["last_used_at"],
        )
    return None
 def get_channel_key_count(user_id: int) -> int:
    """Get count of saved channel keys for a user."""
    db = get_db()
    result = db.execute(
        "SELECT COUNT(*) FROM user_channel_keys WHERE user_id = ?", (user_id,)
    ).fetchone()
    return result[0] if result else 0
 def can_save_channel_key(user_id: int) -> bool:
    """Check if user can save more channel keys (within limit)."""
    return get_channel_key_count(user_id) < MAX_CHANNEL_KEYS
 def save_channel_key(
    user_id: int, name: str, channel_key: str
 ) -> tuple[bool, str, ChannelKey | None]:
    """
    Save a channel key for a user.
    Returns (success, message, key).
    """
    # Validate name
    name = name.strip()
    if not name:
        return False, "Key name is required", None
    if len(name) > 50:
        return False, "Key name must be at most 50 characters", None
    # Validate channel key format (hex string)
    channel_key = channel_key.strip().lower()
    if not channel_key:
        return False, "Channel key is required", None
    if not all(c in "0123456789abcdef" for c in channel_key):
        return False, "Invalid channel key format", None
    # Check limit
    if not can_save_channel_key(user_id):
        return False, f"Maximum of {MAX_CHANNEL_KEYS} saved keys reached", None
    db = get_db()
    try:
        cursor = db.execute(
            """
            INSERT INTO user_channel_keys (user_id, name, channel_key)
            VALUES (?, ?, ?)
            """,
            (user_id, name, channel_key),
        )
        db.commit()
        key = get_channel_key_by_id(cursor.lastrowid, user_id)
        return True, "Channel key saved", key
    except sqlite3.IntegrityError:
        return False, "This channel key is already saved", None
 def update_channel_key_name(
    key_id: int, user_id: int, new_name: str
 ) -> tuple[bool, str]:
    """Update the name of a saved channel key."""
    new_name = new_name.strip()
    if not new_name:
        return False, "Key name is required"
    if len(new_name) > 50:
        return False, "Key name must be at most 50 characters"
    key = get_channel_key_by_id(key_id, user_id)
    if not key:
        return False, "Channel key not found"
    db = get_db()
    db.execute(
        "UPDATE user_channel_keys SET name = ? WHERE id = ? AND user_id = ?",
        (new_name, key_id, user_id),
    )
    db.commit()
    return True, "Key name updated"
 def update_channel_key_last_used(key_id: int, user_id: int):
    """Update the last_used_at timestamp for a channel key."""
    db = get_db()
    db.execute(
        """
        UPDATE user_channel_keys
        SET last_used_at = CURRENT_TIMESTAMP
        WHERE id = ? AND user_id = ?
        """,
        (key_id, user_id),
    )
    db.commit()
 def delete_channel_key(key_id: int, user_id: int) -> tuple[bool, str]:
    """Delete a saved channel key."""
    key = get_channel_key_by_id(key_id, user_id)
    if not key:
        return False, "Channel key not found"
    db = get_db()
    db.execute(
        "DELETE FROM user_channel_keys WHERE id = ? AND user_id = ?",
        (key_id, user_id),
    )
    db.commit()
    return True, f"Key '{key.name}' deleted"
 # =============================================================================
 # Decorators
 # =============================================================================
 def login_required(f):
    """Decorator to require login for a route."""
    @functools.wraps(f)
    def decorated_function(*args, **kwargs):
        # Check if auth is enabled
        if not current_app.config.get("AUTH_ENABLED", True):
            return f(*args, **kwargs)
        # Check for first-run setup
        if not any_users_exist():
            return redirect(url_for("setup"))
        # Check authentication
        if not is_authenticated():
            return redirect(url_for("login"))
        # Check if session is still valid (user not deleted)
        if not is_session_valid():
            logout_user()
            flash("Your session has expired. Please log in again.", "warning")
            return redirect(url_for("login"))
        return f(*args, **kwargs)
    return decorated_function
 def admin_required(f):
    """Decorator to require admin role for a route."""
    @functools.wraps(f)
    def decorated_function(*args, **kwargs):
        # Check if auth is enabled
        if not current_app.config.get("AUTH_ENABLED", True):
            return f(*args, **kwargs)
        # Check for first-run setup
        if not any_users_exist():
            return redirect(url_for("setup"))
        # Check authentication
        if not is_authenticated():
            return redirect(url_for("login"))
        # Check if session is still valid
        if not is_session_valid():
            logout_user()
            flash("Your session has expired. Please log in again.", "warning")
            return redirect(url_for("login"))
        # Check admin role
        if not is_admin():
            flash("Admin access required", "error")
            return redirect(url_for("index"))
        return f(*args, **kwargs)
    return decorated_function
 # =============================================================================
 # App Initialization
 # =============================================================================
 def init_app(app):
    """Initialize auth module with Flask app."""
    app.teardown_appcontext(close_db)
    with app.app_context():
        init_db()
--- a/frontends/web/ssl_utils.py
+++ b/frontends/web/ssl_utils.py
@@ -0,0 +1,111 @@
 """
 SSL Certificate Utilities
 Auto-generates self-signed certificates for HTTPS.
 Uses cryptography library (already a dependency).
 """
 import datetime
 import ipaddress
 from pathlib import Path
 from cryptography import x509
 from cryptography.hazmat.primitives import hashes, serialization
 from cryptography.hazmat.primitives.asymmetric import rsa
 from cryptography.x509.oid import NameOID
 def get_cert_paths(base_dir: Path) -> tuple[Path, Path]:
    """Get paths for cert and key files."""
    cert_dir = base_dir / "certs"
    cert_dir.mkdir(parents=True, exist_ok=True)
    return cert_dir / "server.crt", cert_dir / "server.key"
 def certs_exist(base_dir: Path) -> bool:
    """Check if both cert files exist."""
    cert_path, key_path = get_cert_paths(base_dir)
    return cert_path.exists() and key_path.exists()
 def generate_self_signed_cert(
    base_dir: Path,
    hostname: str = "localhost",
    days_valid: int = 365,
 ) -> tuple[Path, Path]:
    """
    Generate self-signed SSL certificate.
    Args:
        base_dir: Base directory for certs folder
        hostname: Server hostname for certificate
        days_valid: Certificate validity in days
    Returns:
        Tuple of (cert_path, key_path)
    """
    cert_path, key_path = get_cert_paths(base_dir)
    # Generate RSA key
    key = rsa.generate_private_key(
        public_exponent=65537,
        key_size=2048,
    )
    # Create certificate
    subject = issuer = x509.Name([
        x509.NameAttribute(NameOID.ORGANIZATION_NAME, "Stegasoo"),
        x509.NameAttribute(NameOID.COMMON_NAME, hostname),
    ])
    # Subject Alternative Names
    san_list = [
        x509.DNSName(hostname),
        x509.DNSName("localhost"),
        x509.IPAddress(ipaddress.IPv4Address("127.0.0.1")),
    ]
    # Add the hostname as IP if it looks like one
    try:
        san_list.append(x509.IPAddress(ipaddress.IPv4Address(hostname)))
    except ipaddress.AddressValueError:
        pass
    now = datetime.datetime.now(datetime.timezone.utc)
    cert = (
        x509.CertificateBuilder()
        .subject_name(subject)
        .issuer_name(issuer)
        .public_key(key.public_key())
        .serial_number(x509.random_serial_number())
        .not_valid_before(now)
        .not_valid_after(now + datetime.timedelta(days=days_valid))
        .add_extension(
            x509.SubjectAlternativeName(san_list),
            critical=False,
        )
        .sign(key, hashes.SHA256())
    )
    # Write key file (chmod 600)
    key_path.write_bytes(
        key.private_bytes(
            encoding=serialization.Encoding.PEM,
            format=serialization.PrivateFormat.TraditionalOpenSSL,
            encryption_algorithm=serialization.NoEncryption(),
        )
    )
    key_path.chmod(0o600)
    # Write cert file
    cert_path.write_bytes(cert.public_bytes(serialization.Encoding.PEM))
    return cert_path, key_path
 def ensure_certs(base_dir: Path, hostname: str = "localhost") -> tuple[Path, Path]:
    """Ensure certificates exist, generating if needed."""
    if certs_exist(base_dir):
        return get_cert_paths(base_dir)
    print(f"Generating self-signed SSL certificate for {hostname}...")
    return generate_self_signed_cert(base_dir, hostname)
--- a/frontends/web/static/js/auth.js
+++ b/frontends/web/static/js/auth.js
@@ -0,0 +1,142 @@
 /**
 * Stegasoo Authentication Pages JavaScript
 * Handles login, setup, account, and admin user management pages
 */
 const StegasooAuth = {
    // ========================================================================
    // PASSWORD VISIBILITY TOGGLE
    // ========================================================================
    /**
     * Toggle password field visibility
     * @param {string} inputId - ID of the password input
     * @param {HTMLElement} btn - The toggle button element
     */
    togglePassword(inputId, btn) {
        const input = document.getElementById(inputId);
        const icon = btn.querySelector('i');
        if (!input) return;
        if (input.type === 'password') {
            input.type = 'text';
            icon?.classList.replace('bi-eye', 'bi-eye-slash');
        } else {
            input.type = 'password';
            icon?.classList.replace('bi-eye-slash', 'bi-eye');
        }
    },
    // ========================================================================
    // PASSWORD CONFIRMATION VALIDATION
    // ========================================================================
    /**
     * Initialize password confirmation validation on a form
     * @param {string} formId - ID of the form
     * @param {string} passwordId - ID of the password field
     * @param {string} confirmId - ID of the confirmation field
     */
    initPasswordConfirmation(formId, passwordId, confirmId) {
        const form = document.getElementById(formId);
        if (!form) return;
        form.addEventListener('submit', function(e) {
            const password = document.getElementById(passwordId)?.value;
            const confirm = document.getElementById(confirmId)?.value;
            if (password !== confirm) {
                e.preventDefault();
                alert('Passwords do not match');
            }
        });
    },
    // ========================================================================
    // COPY TO CLIPBOARD
    // ========================================================================
    /**
     * Copy field value to clipboard with visual feedback
     * @param {string} fieldId - ID of the input field to copy
     */
    copyField(fieldId) {
        const field = document.getElementById(fieldId);
        if (!field) return;
        field.select();
        navigator.clipboard.writeText(field.value).then(() => {
            const btn = field.nextElementSibling;
            if (!btn) return;
            const originalHTML = btn.innerHTML;
            btn.innerHTML = '<i class="bi bi-check"></i>';
            setTimeout(() => btn.innerHTML = originalHTML, 1000);
        });
    },
    // ========================================================================
    // PASSWORD GENERATION
    // ========================================================================
    /**
     * Generate a random password
     * @param {number} length - Password length (default 8)
     * @returns {string} Generated password
     */
    generatePassword(length = 8) {
        const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
        let password = '';
        for (let i = 0; i < length; i++) {
            password += chars.charAt(Math.floor(Math.random() * chars.length));
        }
        return password;
    },
    /**
     * Regenerate password and update input field
     * @param {string} inputId - ID of the password input
     * @param {number} length - Password length
     */
    regeneratePassword(inputId = 'passwordInput', length = 8) {
        const input = document.getElementById(inputId);
        if (input) {
            input.value = this.generatePassword(length);
        }
    },
    // ========================================================================
    // DELETE CONFIRMATION
    // ========================================================================
    /**
     * Confirm deletion with a prompt
     * @param {string} itemName - Name of item being deleted
     * @param {string} formId - ID of the form to submit if confirmed
     * @returns {boolean} True if confirmed
     */
    confirmDelete(itemName, formId = null) {
        const confirmed = confirm(`Are you sure you want to delete "${itemName}"? This cannot be undone.`);
        if (confirmed && formId) {
            const form = document.getElementById(formId);
            form?.submit();
        }
        return confirmed;
    }
 };
 // Make togglePassword available globally for onclick handlers
 function togglePassword(inputId, btn) {
    StegasooAuth.togglePassword(inputId, btn);
 }
 // Make copyField available globally for onclick handlers
 function copyField(fieldId) {
    StegasooAuth.copyField(fieldId);
 }
 // Make regeneratePassword available globally for onclick handlers
 function regeneratePassword() {
    StegasooAuth.regeneratePassword();
 }
--- a/frontends/web/static/js/generate.js
+++ b/frontends/web/static/js/generate.js
@@ -0,0 +1,285 @@
 /**
 * Stegasoo Generate Page JavaScript
 * Handles credential generation form and display
 */
 const StegasooGenerate = {
    // ========================================================================
    // FORM CONTROLS
    // ========================================================================
    /**
     * Initialize the words range slider
     */
    initWordsSlider() {
        const wordsRange = document.getElementById('wordsRange');
        const wordsValue = document.getElementById('wordsValue');
        wordsRange?.addEventListener('input', function() {
            const bits = this.value * 11;
            wordsValue.textContent = `${this.value} words (~${bits} bits)`;
        });
    },
    /**
     * Initialize PIN/RSA option toggles
     */
    initOptionToggles() {
        const usePinCheck = document.getElementById('usePinCheck');
        const useRsaCheck = document.getElementById('useRsaCheck');
        const pinOptions = document.getElementById('pinOptions');
        const rsaOptions = document.getElementById('rsaOptions');
        const rsaQrWarning = document.getElementById('rsaQrWarning');
        const rsaBitsSelect = document.getElementById('rsaBitsSelect');
        usePinCheck?.addEventListener('change', function() {
            pinOptions?.classList.toggle('d-none', !this.checked);
        });
        useRsaCheck?.addEventListener('change', function() {
            rsaOptions?.classList.toggle('d-none', !this.checked);
        });
        // RSA key size QR warning (>3072 bits)
        rsaBitsSelect?.addEventListener('change', function() {
            rsaQrWarning?.classList.toggle('d-none', parseInt(this.value) <= 3072);
        });
    },
    // ========================================================================
    // CREDENTIAL VISIBILITY
    // ========================================================================
    pinHidden: false,
    passphraseHidden: false,
    /**
     * Toggle PIN visibility
     */
    togglePinVisibility() {
        const pinDigits = document.getElementById('pinDigits');
        const icon = document.getElementById('pinToggleIcon');
        const text = document.getElementById('pinToggleText');
        this.pinHidden = !this.pinHidden;
        pinDigits?.classList.toggle('blurred', this.pinHidden);
        if (icon) icon.className = this.pinHidden ? 'bi bi-eye' : 'bi bi-eye-slash';
        if (text) text.textContent = this.pinHidden ? 'Show' : 'Hide';
    },
    /**
     * Toggle passphrase visibility
     */
    togglePassphraseVisibility() {
        const display = document.getElementById('passphraseDisplay');
        const icon = document.getElementById('passphraseToggleIcon');
        const text = document.getElementById('passphraseToggleText');
        this.passphraseHidden = !this.passphraseHidden;
        display?.classList.toggle('blurred', this.passphraseHidden);
        if (icon) icon.className = this.passphraseHidden ? 'bi bi-eye' : 'bi bi-eye-slash';
        if (text) text.textContent = this.passphraseHidden ? 'Show' : 'Hide';
    },
    // ========================================================================
    // MEMORY AID STORY GENERATION
    // ========================================================================
    currentStoryTemplate: 0,
    /**
     * Story templates organized by word count (3-12 words supported)
     */
    storyTemplates: {
        3: [
            w => `The ${w[0]} ${w[1]} ${w[2]}.`,
            w => `${w[0]} loves ${w[1]} and ${w[2]}.`,
            w => `A ${w[0]} found a ${w[1]} near the ${w[2]}.`,
            w => `${w[0]}, ${w[1]}, ${w[2]} — never forget.`,
            w => `The ${w[0]} hid the ${w[1]} under the ${w[2]}.`,
        ],
        4: [
            w => `${w[0]} and ${w[1]} discovered a ${w[2]} made of ${w[3]}.`,
            w => `The ${w[0]} ${w[1]} ate ${w[2]} for ${w[3]}.`,
            w => `In the ${w[0]}, a ${w[1]} met a ${w[2]} carrying ${w[3]}.`,
            w => `${w[0]} said "${w[1]}" while holding a ${w[2]} ${w[3]}.`,
            w => `The secret: ${w[0]}, ${w[1]}, ${w[2]}, ${w[3]}.`,
        ],
        5: [
            w => `${w[0]} traveled to ${w[1]} seeking the ${w[2]} of ${w[3]} and ${w[4]}.`,
            w => `The ${w[0]} ${w[1]} lived in a ${w[2]} house with ${w[3]} ${w[4]}.`,
            w => `"${w[0]}!" shouted ${w[1]} as the ${w[2]} ${w[3]} flew toward ${w[4]}.`,
            w => `Captain ${w[0]} sailed the ${w[1]} ${w[2]} searching for ${w[3]} ${w[4]}.`,
            w => `In ${w[0]} kingdom, ${w[1]} guards protected the ${w[2]} ${w[3]} ${w[4]}.`,
        ],
        6: [
            w => `${w[0]} met ${w[1]} at the ${w[2]}. Together they found ${w[3]}, ${w[4]}, and ${w[5]}.`,
            w => `The ${w[0]} ${w[1]} wore a ${w[2]} hat while eating ${w[3]} ${w[4]} ${w[5]}.`,
            w => `Detective ${w[0]} found ${w[1]} ${w[2]} near the ${w[3]} ${w[4]} ${w[5]}.`,
            w => `In the ${w[0]} ${w[1]}, a ${w[2]} ${w[3]} sang about ${w[4]} ${w[5]}.`,
            w => `Chef ${w[0]} combined ${w[1]}, ${w[2]}, ${w[3]}, ${w[4]}, and ${w[5]}.`,
        ],
        7: [
            w => `${w[0]} and ${w[1]} walked through the ${w[2]} ${w[3]} to find the ${w[4]} ${w[5]} ${w[6]}.`,
            w => `The ${w[0]} professor studied ${w[1]} ${w[2]} while drinking ${w[3]} ${w[4]} with ${w[5]} ${w[6]}.`,
            w => `"${w[0]} ${w[1]}!" yelled ${w[2]} as ${w[3]} ${w[4]} attacked the ${w[5]} ${w[6]}.`,
            w => `In ${w[0]}, King ${w[1]} decreed that ${w[2]} ${w[3]} must honor ${w[4]} ${w[5]} ${w[6]}.`,
        ],
        8: [
            w => `${w[0]} ${w[1]} and ${w[2]} ${w[3]} met at the ${w[4]} ${w[5]} to discuss ${w[6]} ${w[7]}.`,
            w => `The ${w[0]} ${w[1]} ${w[2]} traveled from ${w[3]} to ${w[4]} carrying ${w[5]} ${w[6]} ${w[7]}.`,
            w => `${w[0]} discovered that ${w[1]} ${w[2]} plus ${w[3]} ${w[4]} equals ${w[5]} ${w[6]} ${w[7]}.`,
        ],
        9: [
            w => `${w[0]} ${w[1]} ${w[2]} watched as ${w[3]} ${w[4]} ${w[5]} danced with ${w[6]} ${w[7]} ${w[8]}.`,
            w => `In the ${w[0]} ${w[1]} ${w[2]}, three friends — ${w[3]}, ${w[4]}, ${w[5]} — found ${w[6]} ${w[7]} ${w[8]}.`,
            w => `The recipe: ${w[0]}, ${w[1]}, ${w[2]}, ${w[3]}, ${w[4]}, ${w[5]}, ${w[6]}, ${w[7]}, ${w[8]}.`,
        ],
        10: [
            w => `${w[0]} ${w[1]} told ${w[2]} ${w[3]} about the ${w[4]} ${w[5]} ${w[6]} hidden in ${w[7]} ${w[8]} ${w[9]}.`,
            w => `The ${w[0]} ${w[1]} ${w[2]} ${w[3]} ${w[4]} lived beside ${w[5]} ${w[6]} ${w[7]} ${w[8]} ${w[9]}.`,
        ],
        11: [
            w => `${w[0]} ${w[1]} ${w[2]} and ${w[3]} ${w[4]} ${w[5]} discovered ${w[6]} ${w[7]} ${w[8]} ${w[9]} ${w[10]}.`,
            w => `In ${w[0]} ${w[1]}, the ${w[2]} ${w[3]} ${w[4]} sang of ${w[5]} ${w[6]} ${w[7]} ${w[8]} ${w[9]} ${w[10]}.`,
        ],
        12: [
            w => `${w[0]} ${w[1]} ${w[2]} met ${w[3]} ${w[4]} ${w[5]} at the ${w[6]} ${w[7]} ${w[8]} ${w[9]} ${w[10]} ${w[11]}.`,
            w => `The twelve treasures: ${w[0]}, ${w[1]}, ${w[2]}, ${w[3]}, ${w[4]}, ${w[5]}, ${w[6]}, ${w[7]}, ${w[8]}, ${w[9]}, ${w[10]}, ${w[11]}.`,
        ],
    },
    /**
     * Wrap word in highlight span
     */
    hl(word) {
        return `<span class="passphrase-word">${word}</span>`;
    },
    /**
     * Generate a memory story for given words
     * @param {string[]} words - Array of passphrase words
     * @param {number|null} idx - Template index (null for current)
     * @returns {string} HTML story
     */
    generateStory(words, idx = null) {
        const count = words.length;
        if (count === 0) return '';
        // Clamp to supported range (3-12)
        const templateKey = Math.max(3, Math.min(12, count));
        const templates = this.storyTemplates[templateKey];
        if (!templates || templates.length === 0) {
            // Fallback: just list the words
            return words.map(w => this.hl(w)).join(' &mdash; ');
        }
        const templateIdx = (idx ?? this.currentStoryTemplate) % templates.length;
        // Apply highlighting to words
        const highlighted = words.map(w => this.hl(w));
        return templates[templateIdx](highlighted);
    },
    /**
     * Toggle memory aid visibility
     * @param {string[]} words - Passphrase words array
     */
    toggleMemoryAid(words) {
        const container = document.getElementById('memoryAidContainer');
        const icon = document.getElementById('memoryAidIcon');
        const text = document.getElementById('memoryAidText');
        const isHidden = container?.classList.contains('d-none');
        container?.classList.toggle('d-none', !isHidden);
        if (icon) icon.className = isHidden ? 'bi bi-lightbulb-fill' : 'bi bi-lightbulb';
        if (text) text.textContent = isHidden ? 'Hide Aid' : 'Memory Aid';
        if (isHidden) {
            document.getElementById('memoryStory').innerHTML = this.generateStory(words);
        }
    },
    /**
     * Regenerate story with next template
     * @param {string[]} words - Passphrase words array
     */
    regenerateStory(words) {
        const count = words.length;
        const templateKey = Math.max(3, Math.min(12, count));
        const templates = this.storyTemplates[templateKey] || [];
        this.currentStoryTemplate = (this.currentStoryTemplate + 1) % Math.max(1, templates.length);
        document.getElementById('memoryStory').innerHTML = this.generateStory(words, this.currentStoryTemplate);
    },
    // ========================================================================
    // QR CODE PRINTING
    // ========================================================================
    /**
     * Print QR code in new window
     */
    printQrCode() {
        const qrImg = document.getElementById('qrCodeImage');
        if (!qrImg) return;
        const printWindow = window.open('', '_blank');
        printWindow.document.write(`<!DOCTYPE html>
 <html>
 <head>
    <title>Stegasoo RSA Key QR Code</title>
    <style>
        body { display: flex; flex-direction: column; align-items: center; justify-content: center; min-height: 100vh; margin: 0; font-family: sans-serif; }
        img { max-width: 400px; }
        .warning { margin-top: 20px; padding: 10px; border: 2px solid #ff9800; background: #fff3e0; max-width: 400px; text-align: center; font-size: 12px; }
    </style>
 </head>
 <body>
    <h2>Stegasoo RSA Private Key</h2>
    <img src="${qrImg.src}" alt="RSA Key QR Code">
    <div class="warning">
        <strong>Warning:</strong> This QR code contains your unencrypted RSA private key.
        Store securely and destroy after use.
    </div>
    <script>window.onload = function() { window.print(); }<\/script>
 </body>
 </html>`);
        printWindow.document.close();
    },
    // ========================================================================
    // INITIALIZATION
    // ========================================================================
    /**
     * Initialize generate form page
     */
    initForm() {
        this.initWordsSlider();
        this.initOptionToggles();
    }
 };
 // Global function wrappers for onclick handlers
 function togglePinVisibility() {
    StegasooGenerate.togglePinVisibility();
 }
 function togglePassphraseVisibility() {
    StegasooGenerate.togglePassphraseVisibility();
 }
 function printQrCode() {
    StegasooGenerate.printQrCode();
 }
 // Auto-init form controls
 document.addEventListener('DOMContentLoaded', () => {
    if (document.querySelector('[data-page="generate"]')) {
        StegasooGenerate.initForm();
    }
 });
--- a/frontends/web/static/js/stegasoo.js
+++ b/frontends/web/static/js/stegasoo.js
@@ -99,6 +99,23 @@ const Stegasoo = {
                    }
                });
            }
            // Make preview clickable to replace file
            if (preview) {
                preview.style.cursor = 'pointer';
                preview.addEventListener('click', (e) => {
                    e.stopPropagation();
                    input.click();
                });
            }
            // Make entire zone clickable (in case label/preview don't cover it)
            zone.addEventListener('click', (e) => {
                // Only trigger if not clicking directly on the input
                if (e.target !== input) {
                    input.click();
                }
            });
        });
    },
@@ -119,7 +136,11 @@ const Stegasoo = {
                if (isScanContainer || isPixelContainer) {
                    labelEl.classList.add('d-none');
                } else {
-                    labelEl.innerHTML = '<i class="bi bi-check-circle text-success me-1"></i>' + file.name;
+                    labelEl.textContent = '';
                    const icon = document.createElement('i');
                    icon.className = 'bi bi-check-circle text-success me-1';
                    labelEl.appendChild(icon);
                    labelEl.appendChild(document.createTextNode(file.name));
                }
            }
@@ -580,6 +601,17 @@ const Stegasoo = {
                        <span>No QR code detected</span>
                    `;
                }
                // Reset after delay so user can try again
                setTimeout(() => {
                    container.classList.remove('error');
                    container.classList.add('d-none');
                    label?.classList.remove('d-none');
                    // Clear the file input so same file can be re-selected
                    input.value = '';
                    // Remove loader
                    if (loader) loader.remove();
                }, 2000);
            });
        });
    },
@@ -761,18 +793,43 @@ const Stegasoo = {
        const customInputId = config.customInputId || 'channelCustomInput';
        const keyInputId = config.keyInputId || 'channelKeyInput';
        const generateBtnId = config.generateBtnId;
        const serverInfoId = config.serverInfoId || 'channelServerInfo';
        const select = document.getElementById(selectId);
        const customInput = document.getElementById(customInputId);
        const keyInput = document.getElementById(keyInputId);
        const generateBtn = generateBtnId ? document.getElementById(generateBtnId) : null;
        const serverInfo = document.getElementById(serverInfoId);
-        // Show/hide custom input based on selection
+        // Show/hide custom input and server info based on selection
        const updateVisibility = () => {
-            const isCustom = select?.value === 'custom';
+            const value = select?.value;
            const isCustom = value === 'custom';
            const isPublic = value === 'none';
            const isAuto = value === 'auto';
            // Custom input visibility
            customInput?.classList.toggle('d-none', !isCustom);
            if (isCustom && keyInput) {
                keyInput.focus();
                // Pulse highlight effect
                customInput?.classList.add('channel-highlight');
                setTimeout(() => customInput?.classList.remove('channel-highlight'), 400);
            }
            // Server info: show for auto, hide for custom, show "no key" for public
            if (serverInfo) {
                if (isAuto) {
                    serverInfo.innerHTML = '<i class="bi bi-shield-lock me-1"></i>Server: <code>' + (serverInfo.dataset.fingerprint || '••••-••••-···-••••-••••') + '</code>';
                    serverInfo.className = 'small text-success mt-2';
                    serverInfo.classList.remove('d-none');
                } else if (isPublic) {
                    serverInfo.innerHTML = '<i class="bi bi-globe me-1"></i>No channel key will be used';
                    serverInfo.className = 'small text-muted mt-2';
                    serverInfo.classList.remove('d-none');
                } else {
                    serverInfo.classList.add('d-none');
                }
            }
        };
@@ -815,6 +872,14 @@ const Stegasoo = {
            // Set the select value to the actual key for form submission
            select.value = keyInput.value;
        }
        // Track saved key usage (fire-and-forget)
        const selectedOption = select?.selectedOptions?.[0];
        const keyId = selectedOption?.dataset?.keyId;
        if (keyId) {
            fetch(`/api/channel/keys/${keyId}/use`, { method: 'POST' }).catch(() => {});
        }
        return true;
    },
@@ -851,6 +916,180 @@ const Stegasoo = {
        });
    },
    // ========================================================================
    // ASYNC ENCODE WITH PROGRESS (v4.1.2)
    // ========================================================================
    /**
     * Submit encode form asynchronously with progress tracking
     * @param {HTMLFormElement} form - The encode form
     * @param {HTMLElement} btn - The submit button
     */
    async submitEncodeAsync(form, btn) {
        const formData = new FormData(form);
        formData.append('async', 'true');
        // Show progress modal
        this.showProgressModal('Encoding');
        try {
            // Start encode job
            const response = await fetch('/encode', {
                method: 'POST',
                body: formData,
            });
            if (!response.ok) {
                throw new Error('Failed to start encode');
            }
            const result = await response.json();
            if (result.error) {
                throw new Error(result.error);
            }
            const jobId = result.job_id;
            // Poll for progress
            await this.pollEncodeProgress(jobId);
        } catch (error) {
            this.hideProgressModal();
            alert('Encode failed: ' + error.message);
            btn.disabled = false;
            btn.innerHTML = '<i class="bi bi-lock-fill me-2"></i>Encode';
        }
    },
    /**
     * Poll encode progress until complete
     * @param {string} jobId - The job ID
     */
    async pollEncodeProgress(jobId) {
        const progressBar = document.getElementById('progressBar');
        const progressText = document.getElementById('progressText');
        const phaseText = document.getElementById('progressPhase');
        const poll = async () => {
            try {
                // Check status first
                const statusResponse = await fetch(`/encode/status/${jobId}`);
                const statusData = await statusResponse.json();
                if (statusData.status === 'complete') {
                    // Done - redirect to result
                    this.updateProgress(100, 'Complete!');
                    setTimeout(() => {
                        window.location.href = `/encode/result/${statusData.file_id}`;
                    }, 500);
                    return;
                }
                if (statusData.status === 'error') {
                    throw new Error(statusData.error || 'Encode failed');
                }
                // Get progress
                const progressResponse = await fetch(`/encode/progress/${jobId}`);
                const progressData = await progressResponse.json();
                const percent = progressData.percent || 0;
                const phase = progressData.phase || 'processing';
                this.updateProgress(percent, this.formatPhase(phase));
                // Continue polling
                setTimeout(poll, 500);
            } catch (error) {
                this.hideProgressModal();
                alert('Encode failed: ' + error.message);
            }
        };
        await poll();
    },
    /**
     * Format phase name for display
     */
    formatPhase(phase) {
        const phases = {
            'starting': 'Starting...',
            'initializing': 'Initializing...',
            'embedding': 'Embedding data...',
            'saving': 'Saving image...',
            'finalizing': 'Finalizing...',
            'complete': 'Complete!',
        };
        return phases[phase] || phase;
    },
    /**
     * Show progress modal
     */
    showProgressModal(operation = 'Processing') {
        // Create modal if doesn't exist
        let modal = document.getElementById('progressModal');
        if (!modal) {
            modal = document.createElement('div');
            modal.id = 'progressModal';
            modal.className = 'modal fade';
            modal.setAttribute('data-bs-backdrop', 'static');
            modal.setAttribute('data-bs-keyboard', 'false');
            modal.innerHTML = `
                <div class="modal-dialog modal-dialog-centered">
                    <div class="modal-content bg-dark text-light">
                        <div class="modal-body p-4">
                            <h5 class="mb-3" id="progressTitle">${operation}...</h5>
                            <div class="progress mb-2" style="height: 24px;">
                                <div id="progressBar" class="progress-bar progress-bar-striped progress-bar-animated bg-success"
                                     role="progressbar" style="width: 0%"></div>
                            </div>
                            <div class="d-flex justify-content-between text-muted small">
                                <span id="progressPhase">Initializing...</span>
                                <span id="progressText">0%</span>
                            </div>
                        </div>
                    </div>
                </div>
            `;
            document.body.appendChild(modal);
        }
        // Reset progress
        this.updateProgress(0, 'Initializing...');
        // Show modal
        const bsModal = new bootstrap.Modal(modal);
        bsModal.show();
    },
    /**
     * Hide progress modal
     */
    hideProgressModal() {
        const modal = document.getElementById('progressModal');
        if (modal) {
            const bsModal = bootstrap.Modal.getInstance(modal);
            bsModal?.hide();
        }
    },
    /**
     * Update progress bar and text
     */
    updateProgress(percent, phase) {
        const progressBar = document.getElementById('progressBar');
        const progressText = document.getElementById('progressText');
        const phaseText = document.getElementById('progressPhase');
        if (progressBar) progressBar.style.width = percent + '%';
        if (progressText) progressText.textContent = Math.round(percent) + '%';
        if (phaseText) phaseText.textContent = phase;
    },
    // ========================================================================
    // INITIALIZATION HELPERS
    // ========================================================================
@@ -872,18 +1111,23 @@ const Stegasoo = {
            generateBtnId: 'channelKeyGenerate'
        });
-        // Form submission with channel key validation
+        // Form submission with async progress tracking (v4.1.2)
        const form = document.getElementById('encodeForm');
        const btn = document.getElementById('encodeBtn');
        form?.addEventListener('submit', (e) => {
            if (!this.validateChannelKeyOnSubmit(form, 'channelSelect', 'channelKeyInput')) {
            e.preventDefault();
            if (!this.validateChannelKeyOnSubmit(form, 'channelSelect', 'channelKeyInput')) {
                return false;
            }
            if (btn) {
                btn.disabled = true;
-                btn.innerHTML = '<span class="spinner-border spinner-border-sm me-2"></span>Encoding...';
+                btn.innerHTML = '<span class="spinner-border spinner-border-sm me-2"></span>Starting...';
            }
            // Use async submission with progress tracking
            this.submitEncodeAsync(form, btn);
        });
    },
@@ -900,7 +1144,8 @@ const Stegasoo = {
        this.initChannelKey({
            selectId: 'channelSelectDec',
            customInputId: 'channelCustomInputDec',
-            keyInputId: 'channelKeyInputDec'
+            keyInputId: 'channelKeyInputDec',
            serverInfoId: 'channelServerInfoDec'
        });
        // Form submission with channel key validation and mode display
@@ -914,7 +1159,16 @@ const Stegasoo = {
            const selectedMode = document.querySelector('input[name="embed_mode"]:checked')?.value || 'auto';
            if (btn) {
                btn.disabled = true;
-                btn.innerHTML = `<span class="spinner-border spinner-border-sm me-2"></span>Decoding (${selectedMode.toUpperCase()})...`;
+                const startTime = Date.now();
                const updateTimer = () => {
                    const elapsed = Math.floor((Date.now() - startTime) / 1000);
                    const mins = Math.floor(elapsed / 60);
                    const secs = elapsed % 60;
                    const timeStr = mins > 0 ? `${mins}:${secs.toString().padStart(2, '0')}` : `${secs}s`;
                    btn.innerHTML = `<span class="spinner-border spinner-border-sm me-2"></span>Decoding (${selectedMode.toUpperCase()})... ${timeStr}`;
                };
                updateTimer();
                setInterval(updateTimer, 1000);
            }
        });
    },
--- a/frontends/web/static/style.css
+++ b/frontends/web/static/style.css
@@ -6,8 +6,8 @@
   CSS Variables
   ---------------------------------------------------------------------------- */
 :root {
-    --gradient-start: #667eea;
+    --gradient-start: #4a2860;
-    --gradient-end: #764ba2;
+    --gradient-end: #5570d4;
    --bg-dark-1: #1a1a2e;
    --bg-dark-2: #16213e;
    --bg-dark-3: #0f3460;
@@ -16,6 +16,7 @@
    --overlay-dark: rgba(0, 0, 0, 0.3);
    --overlay-light: rgba(255, 255, 255, 0.05);
    --day-highlight: #E3FF54; /* Bright yellow/green for day of week */
    --header-gold: #fee862; /* Halfway between light straw and 24k gold */
 }
 /* ----------------------------------------------------------------------------
@@ -140,6 +141,67 @@ body {
    border-bottom: none;
 }
 .card-header h5 {
    color: var(--header-gold);
    text-shadow: 0 1px 2px rgba(0, 0, 0, 0.33);
 }
 .title-gold {
    color: var(--header-gold);
    text-shadow: 0 2px 6px rgba(0, 0, 0, 0.55);
 }
 /* Two-choice toggle buttons - gradient-matched colors + equal width */
 .btn-group .btn-outline-primary,
 .btn-group .btn-outline-secondary {
    flex: 1 1 0;
    transition: all 0.2s ease;
 }
 .btn-group .btn-outline-primary:hover,
 .btn-group .btn-outline-secondary:hover {
    background-color: rgba(255, 255, 255, 0.08);
 }
 /* Channel key highlight pulse */
 .channel-highlight {
    animation: channel-pulse 0.4s ease;
 }
@keyframes channel-pulse {
    0% { box-shadow: 0 0 0 0 rgba(254, 232, 98, 0); }
    20% { box-shadow: 0 0 9px 1px rgba(254, 232, 98, 0.19); }
    40% { box-shadow: 0 0 9px 1px rgba(254, 232, 98, 0.19); }
    100% { box-shadow: 0 0 0 0 rgba(254, 232, 98, 0); }
 }
 .btn-group .btn-outline-primary:first-of-type,
 .btn-group .btn-outline-secondary:first-of-type {
    color: #6b4d8a;
    border-color: #6b4d8a;
    border-right: 1px dashed rgba(255, 255, 255, 0.2);
 }
 .btn-group .btn-outline-primary:last-of-type,
 .btn-group .btn-outline-secondary:last-of-type {
    color: #4a62a8;
    border-color: #4a62a8;
 }
 .btn-group .btn-check:checked + .btn-outline-primary:first-of-type,
 .btn-group .btn-check:checked + .btn-outline-secondary:first-of-type {
    background-color: #6b4d8a;
    border-color: #6b4d8a;
    color: #fff;
 }
 .btn-group .btn-check:checked + .btn-outline-primary:last-of-type,
 .btn-group .btn-check:checked + .btn-outline-secondary:last-of-type {
    background-color: #4a62a8;
    border-color: #4a62a8;
    color: #fff;
 }
 /* Override small warning text to use header gold */
 .text-warning.small {
    color: var(--header-gold) !important;
    text-shadow: 0 1px 2px rgba(0, 0, 0, 0.33);
 }
 .card-link .card-header.text-center {
    padding-top: 0.5rem !important;
    padding-bottom: 0.5rem !important;
@@ -443,10 +505,10 @@ footer {
 /* Enhance the gradient on hover for dramatic effect */
 .card-link:hover .card-header.text-center {
    background: linear-gradient(135deg,
-        var(--gradient-start) 0%, 
+        #3d2050 0%,
-        #5a67d8 20%, 
+        var(--gradient-start) 30%,
-        var(--gradient-end) 80%, 
+        var(--gradient-end) 70%,
-        #8a2be2 100%);
+        #6680e0 100%);
    box-shadow: inset 0 0 20px rgba(255, 215, 0, 0.1);
 }
@@ -489,7 +551,7 @@ footer {
 .card-link:hover .feature-card {
    transform: translateY(-5px);
-    box-shadow: 0 10px 40px rgba(102, 126, 234, 0.3);
+    box-shadow: 0 10px 40px rgba(74, 40, 96, 0.4);
 }
 /* ----------------------------------------------------------------------------
@@ -724,6 +786,7 @@ footer {
 .scan-data-value {
    color: rgba(0, 255, 170, 1);
    font-weight: 600;
    font-size: 0.65rem;
 }
 .scan-hash-preview {
@@ -744,7 +807,7 @@ footer {
    border: 1px solid rgba(0, 255, 170, 0.4);
    border-radius: 3px;
    padding: 2px 6px;
-    font-size: 0.5rem;
+    font-size: 0.65rem;
    color: rgba(0, 255, 170, 1);
    text-transform: uppercase;
    letter-spacing: 0.3px;
@@ -1001,6 +1064,7 @@ footer {
 .pixel-data-value {
    color: #d4e157;
    font-weight: 600;
    font-size: 0.65rem;
 }
 .pixel-status-badge {
@@ -1010,7 +1074,7 @@ footer {
    border: 1px solid rgba(212, 225, 87, 0.4);
    border-radius: 3px;
    padding: 2px 6px;
-    font-size: 0.55rem;
+    font-size: 0.65rem;
    color: #d4e157;
    text-transform: uppercase;
    letter-spacing: 0.5px;
@@ -1047,10 +1111,10 @@ footer {
 /* Expand drop zone when showing scanned QR result */
 #rsaQrSection .drop-zone:has(.qr-scan-container:not(.d-none)) {
    width: auto;
-    min-width: 200px;
+    min-width: 280px;
-    max-width: 280px;
+    max-width: 400px;
    height: auto;
-    min-height: 200px;
+    min-height: 280px;
    aspect-ratio: auto;
 }
@@ -1070,9 +1134,9 @@ footer {
    overflow: visible;
    border-radius: 8px;
    background: rgba(0, 0, 0, 0.3);
-    min-height: 160px;
+    min-height: 220px;
-    min-width: 160px;
+    min-width: 220px;
-    padding: 10px;
+    padding: 12px;
    display: flex;
    justify-content: center;
    align-items: center;
@@ -1090,10 +1154,10 @@ footer {
 /* Cropped image - hidden until loaded, scales UP to fill container */
 .qr-scan-container .qr-cropped {
-    max-height: 180px;
+    max-height: 240px;
-    max-width: 180px;
+    max-width: 240px;
-    min-width: 140px;
+    min-width: 180px;
-    min-height: 140px;
+    min-height: 180px;
    width: auto;
    height: auto;
    object-fit: contain;
@@ -1259,7 +1323,7 @@ footer {
        rgba(10, 15, 30, 0.95) 0%,
        rgba(10, 15, 30, 0.6) 80%,
        transparent 100%);
-    padding: 4px 6px 3px 6px;
+    padding: 8px 10px 6px 10px;
    opacity: 0;
    transition: opacity 0.3s ease;
    border-radius: 0 0 6px 6px;
@@ -1282,10 +1346,10 @@ footer {
 /* QR Data Panel text styles */
 .qr-data-filename {
    font-family: 'Courier New', monospace;
-    font-size: 0.6rem;
+    font-size: 0.7rem;
    color: #fff;
    text-align: center;
-    margin-bottom: 2px;
+    margin-bottom: 3px;
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
@@ -1301,7 +1365,7 @@ footer {
    justify-content: space-between;
    align-items: center;
    font-family: 'Courier New', monospace;
-    font-size: 0.5rem;
+    font-size: 0.6rem;
    white-space: nowrap;
 }
@@ -1310,9 +1374,9 @@ footer {
    align-items: center;
    background: rgba(0, 255, 170, 0.15);
    border: 1px solid rgba(0, 255, 170, 0.4);
-    border-radius: 2px;
+    border-radius: 3px;
-    padding: 1px 4px;
+    padding: 2px 6px;
-    font-size: 0.45rem;
+    font-size: 0.65rem;
    color: rgba(0, 255, 170, 1);
    text-transform: uppercase;
    letter-spacing: 0.3px;
@@ -1321,7 +1385,7 @@ footer {
 .qr-data-value {
    color: rgba(0, 255, 170, 1);
    font-weight: 600;
-    font-size: 0.5rem;
+    font-size: 0.65rem;
 }
 /* ----------------------------------------------------------------------------
@@ -1378,3 +1442,260 @@ footer {
    padding: 0.35rem 0.75rem;
    background: rgba(0, 0, 0, 0.1);
 }
 /* ============================================================================
   MOBILE RESPONSIVE IMPROVEMENTS
   ============================================================================ */
 /* Mobile-specific drop zone improvements */
@media (max-width: 768px) {
    /* Larger drop zones on mobile for easier touch targets */
    .drop-zone {
        padding: 2rem 1.5rem;
        min-height: 140px;
    }
    /* Larger touch target for upload icons */
    .drop-zone-label i {
        font-size: 2.5rem !important;
    }
    /* Touch feedback - active state */
    .drop-zone:active {
        border-color: var(--gradient-start);
        background: rgba(102, 126, 234, 0.15);
        transform: scale(0.98);
    }
    /* Mode buttons - stack vertically on very small screens */
    .d-flex.gap-2:has(.mode-btn) {
        flex-direction: column;
    }
    .mode-btn {
        padding: 1rem;
        min-height: 56px; /* iOS touch target minimum */
    }
    /* Full-width primary buttons */
    .btn-primary.btn-lg {
        padding: 1rem 1.5rem;
        font-size: 1.1rem;
        min-height: 56px;
    }
    /* Security factor boxes - more padding for touch */
    .security-box {
        padding: 1.25rem;
    }
    /* Form controls - larger for touch */
    .form-control,
    .form-select {
        padding: 0.75rem 1rem;
        font-size: 1rem;
        min-height: 48px;
    }
    /* Input groups - consistent sizing */
    .input-group .form-control {
        min-height: 48px;
    }
    .input-group .btn {
        min-width: 48px;
        padding: 0.75rem;
    }
    /* Password toggle button - easier to tap */
    [data-toggle-password] {
        min-width: 52px;
    }
    /* PIN input - larger on mobile */
    .pin-input-container .form-control {
        font-size: 1.4rem;
        letter-spacing: 4px;
        padding: 0.875rem 1rem;
    }
    /* Passphrase input - comfortable mobile size */
    .passphrase-input {
        font-size: 1rem !important;
        padding: 0.875rem 1rem !important;
    }
    /* Card headers - compact on mobile */
    .card-header h5 {
        font-size: 1.1rem;
    }
    /* Alert info panel - readable text */
    .alert.small {
        font-size: 0.9rem;
    }
    /* Bottom info icons - larger tap targets */
    .row.text-center .col-4 {
        padding: 0.5rem;
    }
    .row.text-center .col-4 i {
        font-size: 2rem !important;
    }
    /* Capacity panel badges - easier to read */
    #capacityPanel .badge {
        font-size: 0.8rem;
        padding: 0.4rem 0.6rem;
    }
    /* Payload type toggle - full width buttons */
    .btn-group[role="group"] {
        flex-direction: row;
    }
    .btn-group .btn {
        padding: 0.75rem 0.5rem;
        font-size: 0.95rem;
    }
    /* Textarea - comfortable height */
    textarea.form-control {
        min-height: 120px;
    }
    /* Channel select - full width */
    #channelSelect {
        font-size: 1rem;
    }
 }
 /* Very small screens (iPhone SE, etc.) */
@media (max-width: 375px) {
    .drop-zone {
        padding: 1.5rem 1rem;
    }
    .mode-btn {
        padding: 0.875rem;
        font-size: 0.9rem;
    }
    .mode-btn .text-muted {
        display: none; /* Hide secondary text on tiny screens */
    }
    .card-header h5 {
        font-size: 1rem;
    }
    /* Stack security factor row */
    .row:has(.security-box) > .col-md-6 {
        margin-bottom: 1rem;
    }
 }
 /* Touch device optimizations */
@media (hover: none) and (pointer: coarse) {
    /* Remove hover effects that don't work on touch */
    .btn-primary:hover {
        transform: none;
    }
    .feature-card:hover {
        transform: none;
    }
    .card-link:hover .feature-card {
        transform: none;
    }
    /* Add active states instead */
    .btn-primary:active {
        transform: scale(0.98);
        box-shadow: 0 2px 10px rgba(102, 126, 234, 0.3);
    }
    .feature-card:active {
        transform: scale(0.98);
    }
    /* Drop zone active feedback */
    .drop-zone:active {
        border-color: var(--gradient-start);
        background: rgba(102, 126, 234, 0.1);
    }
    /* Mode button active state */
    .mode-btn:active {
        background: rgba(255, 255, 255, 0.12);
        border-color: var(--gradient-start);
    }
 }
 /* Camera hint for mobile - shows on file inputs */
@media (max-width: 768px) {
    .drop-zone-label span.text-muted {
        display: block;
    }
    /* Add camera icon hint on mobile */
    .drop-zone-label::after {
        content: "Tap to take photo or choose file";
        display: block;
        font-size: 0.75rem;
        color: rgba(255, 255, 255, 0.4);
        margin-top: 0.5rem;
    }
    /* Hide the default text and show mobile version */
    .drop-zone-label > span.text-muted {
        display: none;
    }
 }
 /* Navbar mobile adjustments */
@media (max-width: 768px) {
    .navbar {
        padding: 0.5rem 1rem;
    }
    .navbar-brand img {
        height: 32px;
    }
    /* Sticky header shouldn't eat too much space */
    .navbar.sticky-top {
        position: relative; /* Don't stick on mobile - saves screen space */
    }
 }
 /* Results page mobile adjustments */
@media (max-width: 768px) {
    /* Download button - full width on mobile */
    .btn-success.btn-lg,
    a.btn-success.btn-lg {
        width: 100%;
        padding: 1rem;
        font-size: 1.1rem;
    }
    /* QR codes - appropriate sizing */
    .qr-scan-container {
        max-width: 280px;
        margin: 0 auto;
    }
    /* Message display - readable on mobile */
    .alert-message {
        font-size: 0.9rem;
        padding: 1rem;
        word-break: break-word;
    }
    /* Result icon - slightly smaller on mobile */
    .result-icon {
        font-size: 3rem;
    }
 }
--- a/frontends/web/stegasoo_users.db
+++ b/frontends/web/stegasoo_users.db
--- a/frontends/web/stego_worker.py
+++ b/frontends/web/stego_worker.py
@@ -111,6 +111,7 @@ def encode_operation(params: dict) -> dict:
        dct_output_format=params.get("dct_output_format", "png"),
        dct_color_mode=params.get("dct_color_mode", "color"),
        channel_key=resolved_channel_key,  # v4.0.0
        progress_file=params.get("progress_file"),  # v4.1.2
    )
    # Build stats dict if available
--- a/frontends/web/subprocess_stego.py
+++ b/frontends/web/subprocess_stego.py
@@ -47,6 +47,8 @@ import base64
 import json
 import subprocess
 import sys
 import tempfile
 import uuid
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
@@ -233,6 +235,8 @@ class SubprocessStego:
        # Channel key (v4.0.0)
        channel_key: str | None = "auto",
        timeout: int | None = None,
        # Progress file (v4.1.2)
        progress_file: str | None = None,
    ) -> EncodeResult:
        """
        Encode a message or file into an image.
@@ -268,6 +272,7 @@ class SubprocessStego:
            "dct_output_format": dct_output_format,
            "dct_color_mode": dct_color_mode,
            "channel_key": channel_key,  # v4.0.0
            "progress_file": progress_file,  # v4.1.2
        }
        if file_data:
@@ -496,3 +501,42 @@ def get_subprocess_stego() -> SubprocessStego:
    if _default_stego is None:
        _default_stego = SubprocessStego()
    return _default_stego
 # =============================================================================
 # Progress File Utilities (v4.1.2)
 # =============================================================================
 def generate_job_id() -> str:
    """Generate a unique job ID for tracking encode/decode operations."""
    return str(uuid.uuid4())[:8]
 def get_progress_file_path(job_id: str) -> str:
    """Get the progress file path for a job ID."""
    return str(Path(tempfile.gettempdir()) / f"stegasoo_progress_{job_id}.json")
 def read_progress(job_id: str) -> dict | None:
    """
    Read progress from file for a job ID.
    Returns:
        Progress dict with current, total, percent, phase, or None if not found
    """
    progress_file = get_progress_file_path(job_id)
    try:
        with open(progress_file) as f:
            return json.load(f)
    except (FileNotFoundError, json.JSONDecodeError):
        return None
 def cleanup_progress_file(job_id: str) -> None:
    """Remove progress file for a completed job."""
    progress_file = get_progress_file_path(job_id)
    try:
        Path(progress_file).unlink(missing_ok=True)
    except Exception:
        pass
--- a/frontends/web/templates/about.html
+++ b/frontends/web/templates/about.html
@@ -65,7 +65,7 @@
                            <li class="mb-2">
                                <i class="bi bi-check-circle text-success me-2"></i>
                                <strong>Channel Keys</strong>
-                                <span class="badge bg-info ms-1">v4.0</span>
+                                <span class="badge bg-info ms-1">v4.1</span>
                                <br><small class="text-muted">Group/deployment isolation</small>
                            </li>
                        </ul>
@@ -100,6 +100,7 @@
                                    <li><strong>Output:</strong> JPEG or PNG</li>
                                    <li><strong>Color:</strong> Color or grayscale</li>
                                    <li><strong>Speed:</strong> ~2s</li>
                                    <li><strong>Error Correction:</strong> Reed-Solomon</li>
                                </ul>
                                <hr>
                                <div class="small">
@@ -250,7 +251,7 @@
            <div class="card-header">
                <h5 class="mb-0">
                    <i class="bi bi-broadcast me-2"></i>Channel Keys
-                    <span class="badge bg-info ms-2">v4.0</span>
+                    <span class="badge bg-info ms-2">v4.1</span>
                </h5>
            </div>
            <div class="card-body">
@@ -316,19 +317,55 @@
                </div>
                {% if channel_configured %}
-                <div class="alert alert-success mt-3 mb-0">
+                <div class="alert alert-success mt-3 mb-3">
                    <i class="bi bi-shield-lock me-2"></i>
                    <strong>This server has a channel key configured:</strong>
                    <code class="ms-2">{{ channel_fingerprint }}</code>
                    <span class="text-muted ms-2">({{ channel_source }})</span>
                </div>
                {% else %}
-                <div class="alert alert-info mt-3 mb-0">
+                <div class="alert alert-info mt-3 mb-3">
                    <i class="bi bi-info-circle me-2"></i>
                    This server is running in <strong>public mode</strong>.
                    Set <code>STEGASOO_CHANNEL_KEY</code> to enable server-wide channel isolation.
                </div>
                {% endif %}
                <!-- Channel Key QR Generator -->
                <div class="card bg-dark border-secondary">
                    <div class="card-header">
                        <i class="bi bi-qr-code me-2"></i>Share Channel Key via QR
                    </div>
                    <div class="card-body">
                        <p class="small text-muted mb-3">Generate a QR code to share a channel key with others.</p>
                        <div class="row g-2 align-items-end">
                            <div class="col-md-8">
                                <label class="form-label small">Channel Key</label>
                                <div class="input-group">
                                    <input type="text" class="form-control font-monospace" id="channelKeyQrInput"
                                           placeholder="Enter or generate a key">
                                    <button class="btn btn-outline-secondary" type="button" id="channelKeyQrGenerate"
                                            title="Generate random key">
                                        <i class="bi bi-shuffle"></i>
                                    </button>
                                </div>
                            </div>
                            <div class="col-md-4">
                                <button class="btn btn-primary w-100" type="button" id="channelKeyQrShow">
                                    <i class="bi bi-qr-code me-1"></i>Show QR
                                </button>
                            </div>
                        </div>
                        <div class="text-center mt-3 d-none" id="channelKeyQrContainer">
                            <canvas id="channelKeyQrCanvas" class="bg-white p-2 rounded"></canvas>
                            <div class="mt-2">
                                <button class="btn btn-sm btn-outline-secondary" type="button" id="channelKeyQrDownload">
                                    <i class="bi bi-download me-1"></i>Download PNG
                                </button>
                            </div>
                        </div>
                    </div>
                </div>
            </div>
        </div>
@@ -338,22 +375,42 @@
                <h5 class="mb-0"><i class="bi bi-clock-history me-2"></i>Version History</h5>
            </div>
            <div class="card-body">
-                <div class="table-responsive">
+                <!-- Current Version - Prominent -->
-                    <table class="table table-dark table-sm small">
+                <div class="alert alert-success mb-4">
-                        <thead>
+                    <div class="d-flex align-items-center">
-                            <tr>
+                        <span class="badge bg-success fs-6 me-3">v4.1.2</span>
-                                <th>Version</th>
+                        <div>
-                                <th>Changes</th>
+                            <strong>Progress bars</strong> for encode operations,
-                            </tr>
+                            <strong>mobile-responsive polish</strong>,
-                        </thead>
+                            DCT decode bug fix, release validation script
                        </div>
                    </div>
                </div>
                <!-- Previous Versions - Accordion -->
                <div class="accordion" id="versionAccordion">
                    <div class="accordion-item bg-dark">
                        <h2 class="accordion-header">
                            <button class="accordion-button collapsed bg-dark text-light py-2" type="button"
                                    data-bs-toggle="collapse" data-bs-target="#olderVersions">
                                <i class="bi bi-archive me-2"></i>Previous Versions
                            </button>
                        </h2>
                        <div id="olderVersions" class="accordion-collapse collapse" data-bs-parent="#versionAccordion">
                            <div class="accordion-body p-0">
                                <table class="table table-dark table-sm small mb-0">
                                    <tbody>
                                        <tr>
                                            <td width="80"><strong>4.1.1</strong></td>
                                            <td>DCT RS format stability, Docker cleanup, first-boot wizard</td>
                                        </tr>
                                        <tr>
                                            <td><strong>4.1.0</strong></td>
                                            <td>Reed-Solomon error correction for DCT, majority voting headers</td>
                                        </tr>
                                        <tr>
                                            <td><strong>4.0.0</strong></td>
-                                <td>
+                                            <td>Channel keys, DCT default, subprocess isolation</td>
                                    <strong>Channel keys</strong> for group/deployment isolation,
                                    DCT default, simplified auth, passphrase replaces day_phrase, 
                                    4-word default, JPEG fix, large image support, subprocess isolation, Python 3.10-3.12
                                </td>
                                        </tr>
                                        <tr>
                                            <td>3.2.0</td>
@@ -364,16 +421,8 @@
                                            <td>DCT mode, JPEG output, color preservation</td>
                                        </tr>
                                        <tr>
-                                <td>2.2.0</td>
+                                            <td>2.x</td>
-                                <td>QR code RSA key import/export</td>
+                                            <td>Web UI, REST API, RSA keys, QR codes, file embedding</td>
                            </tr>
                            <tr>
                                <td>2.1.0</td>
                                <td>File embedding, compression</td>
                            </tr>
                            <tr>
                                <td>2.0.0</td>
                                <td>Web UI, REST API, RSA keys</td>
                                        </tr>
                                        <tr>
                                            <td>1.0.0</td>
@@ -384,6 +433,9 @@
                            </div>
                        </div>
                    </div>
                </div>
            </div>
        </div>
        <div class="card mb-4">
            <div class="card-header">
@@ -469,28 +521,76 @@
                <h5 class="mb-0"><i class="bi bi-speedometer2 me-2"></i>Limits &amp; Specs</h5>
            </div>
            <div class="card-body">
-                <table class="table table-dark table-striped small">
+                <!-- Key Specs - Always Visible -->
                <div class="row text-center mb-4">
                    <div class="col-6 col-md-4 col-lg-2 mb-3">
                        <div class="p-3 bg-dark rounded h-100">
                            <i class="bi bi-file-earmark text-primary fs-3 d-block mb-2"></i>
                            <div class="small text-muted">Max Payload</div>
                            <strong>{{ max_payload_kb }} KB</strong>
                        </div>
                    </div>
                    <div class="col-6 col-md-4 col-lg-2 mb-3">
                        <div class="p-3 bg-dark rounded h-100">
                            <i class="bi bi-image text-info fs-3 d-block mb-2"></i>
                            <div class="small text-muted">Max Carrier</div>
                            <strong>24 MP</strong>
                        </div>
                    </div>
                    <div class="col-6 col-md-4 col-lg-2 mb-3">
                        <div class="p-3 bg-dark rounded h-100">
                            <i class="bi bi-soundwave text-warning fs-3 d-block mb-2"></i>
                            <div class="small text-muted">DCT Capacity</div>
                            <strong>~75 KB/MP</strong>
                        </div>
                    </div>
                    <div class="col-6 col-md-4 col-lg-2 mb-3">
                        <div class="p-3 bg-dark rounded h-100">
                            <i class="bi bi-grid-3x3 text-success fs-3 d-block mb-2"></i>
                            <div class="small text-muted">LSB Capacity</div>
                            <strong>~375 KB/MP</strong>
                        </div>
                    </div>
                    <div class="col-6 col-md-4 col-lg-2 mb-3">
                        <div class="p-3 bg-dark rounded h-100">
                            <i class="bi bi-shield-check text-danger fs-3 d-block mb-2"></i>
                            <div class="small text-muted">Encryption</div>
                            <strong>AES-256</strong>
                        </div>
                    </div>
                    <div class="col-6 col-md-4 col-lg-2 mb-3">
                        <div class="p-3 bg-dark rounded h-100">
                            <i class="bi bi-bandaid text-info fs-3 d-block mb-2"></i>
                            <div class="small text-muted">DCT ECC</div>
                            <strong>RS Code</strong>
                        </div>
                    </div>
                </div>
                <!-- Error Correction Detail -->
                <div class="alert alert-info small mb-4">
                    <i class="bi bi-info-circle me-2"></i>
                    <strong>Reed-Solomon Error Correction:</strong> DCT mode corrects up to 16 byte errors per 223-byte chunk.
                    Handles problematic carrier images with uniform areas that cause unstable DCT coefficients.
                </div>
                <!-- More Specs - Accordion -->
                <div class="accordion" id="specsAccordion">
                    <div class="accordion-item bg-dark">
                        <h2 class="accordion-header">
                            <button class="accordion-button collapsed bg-dark text-light py-2" type="button"
                                    data-bs-toggle="collapse" data-bs-target="#moreSpecs">
                                <i class="bi bi-list-ul me-2"></i>More Specifications
                            </button>
                        </h2>
                        <div id="moreSpecs" class="accordion-collapse collapse" data-bs-parent="#specsAccordion">
                            <div class="accordion-body p-0">
                                <table class="table table-dark table-striped small mb-0">
                                    <tbody>
                                        <tr>
                                            <td><i class="bi bi-file-text me-2"></i>Max text</td>
                                            <td><strong>2M characters</strong></td>
                                        </tr>
                        <tr>
                            <td><i class="bi bi-file-earmark me-2"></i>Max file</td>
                            <td><strong>{{ max_payload_kb }} KB</strong></td>
                        </tr>
                        <tr>
                            <td><i class="bi bi-image me-2"></i>Max carrier</td>
                            <td><strong>24 MP</strong> (~6000x4000)</td>
                        </tr>
                        <tr>
                            <td><i class="bi bi-soundwave me-2"></i>DCT capacity</td>
                            <td><strong>~75 KB/MP</strong></td>
                        </tr>
                        <tr>
                            <td><i class="bi bi-grid-3x3 me-2"></i>LSB capacity</td>
                            <td><strong>~375 KB/MP</strong></td>
                        </tr>
                                        <tr>
                                            <td><i class="bi bi-upload me-2"></i>Max upload</td>
                                            <td><strong>30 MB</strong></td>
@@ -517,13 +617,77 @@
                                        </tr>
                                        <tr>
                                            <td><i class="bi bi-box me-2"></i>Built with</td>
-                            <td>Flask, Pillow, NumPy, SciPy, jpegio, cryptography, argon2-cffi</td>
+                                            <td>Flask, Pillow, NumPy, SciPy, jpegio, reedsolo, cryptography, argon2-cffi</td>
                                        </tr>
                                    </tbody>
                                </table>
                            </div>
                        </div>
                    </div>
                </div>
            </div>
        </div>
    </div>
 </div>
 {% endblock %}
 {% block scripts %}
 <!-- QR Code library for channel key sharing -->
 <script src="https://cdn.jsdelivr.net/npm/qrcode@1.5.3/build/qrcode.min.js"></script>
 <script src="{{ url_for('static', filename='js/stegasoo.js') }}"></script>
 <script>
 document.addEventListener('DOMContentLoaded', function() {
    const input = document.getElementById('channelKeyQrInput');
    const generateBtn = document.getElementById('channelKeyQrGenerate');
    const showBtn = document.getElementById('channelKeyQrShow');
    const container = document.getElementById('channelKeyQrContainer');
    const canvas = document.getElementById('channelKeyQrCanvas');
    const downloadBtn = document.getElementById('channelKeyQrDownload');
    // Generate random key
    generateBtn?.addEventListener('click', function() {
        if (input && typeof Stegasoo !== 'undefined') {
            input.value = Stegasoo.generateChannelKey();
        }
    });
    // Show QR code
    showBtn?.addEventListener('click', function() {
        const key = input?.value?.trim().replace(/-/g, '');
        if (!key || key.length !== 32) {
            alert('Please enter a valid 32-character channel key');
            return;
        }
        // Format key with dashes for QR
        const formatted = key.match(/.{4}/g)?.join('-') || key;
        // Generate QR code
        if (typeof QRCode !== 'undefined' && canvas) {
            QRCode.toCanvas(canvas, formatted, {
                width: 200,
                margin: 2,
                color: { dark: '#000', light: '#fff' }
            }, function(error) {
                if (error) {
                    console.error('QR generation error:', error);
                    return;
                }
                container?.classList.remove('d-none');
            });
        }
    });
    // Download QR as PNG
    downloadBtn?.addEventListener('click', function() {
        if (canvas) {
            const link = document.createElement('a');
            link.download = 'stegasoo-channel-key.png';
            link.href = canvas.toDataURL('image/png');
            link.click();
        }
    });
 });
 </script>
 {% endblock %}
--- a/frontends/web/templates/account.html
+++ b/frontends/web/templates/account.html
@@ -0,0 +1,234 @@
 {% extends "base.html" %}
 {% block title %}Account - Stegasoo{% endblock %}
 {% block content %}
 <div class="row justify-content-center">
    <div class="col-md-6 col-lg-5">
        <div class="card">
            <div class="card-header">
                <h5 class="mb-0"><i class="bi bi-person-gear me-2"></i>Account Settings</h5>
            </div>
            <div class="card-body">
                <p class="text-muted mb-4">
                    Logged in as <strong>{{ username }}</strong>
                    {% if is_admin %}
                    <span class="badge bg-warning text-dark ms-2">
                        <i class="bi bi-shield-check me-1"></i>Admin
                    </span>
                    {% endif %}
                </p>
                {% if is_admin %}
                <div class="mb-4">
                    <a href="{{ url_for('admin_users') }}" class="btn btn-outline-primary w-100">
                        <i class="bi bi-people me-2"></i>Manage Users
                    </a>
                </div>
                <!-- Recovery Key Management (Admin only) -->
                <div class="card bg-dark mb-4">
                    <div class="card-body py-3">
                        <div class="d-flex justify-content-between align-items-center">
                            <div>
                                <i class="bi bi-shield-lock me-2"></i>
                                <strong>Recovery Key</strong>
                                {% if has_recovery %}
                                <span class="badge bg-success ms-2">Configured</span>
                                {% else %}
                                <span class="badge bg-secondary ms-2">Not Set</span>
                                {% endif %}
                            </div>
                            <div class="btn-group btn-group-sm">
                                <a href="{{ url_for('regenerate_recovery') }}" class="btn btn-outline-warning"
                                   onclick="return confirm('Generate a new recovery key? This will invalidate any existing key.')">
                                    <i class="bi bi-arrow-repeat me-1"></i>
                                    {{ 'Regenerate' if has_recovery else 'Generate' }}
                                </a>
                                {% if has_recovery %}
                                <form method="POST" action="{{ url_for('disable_recovery') }}" style="display:inline;">
                                    <button type="submit" class="btn btn-outline-danger"
                                            onclick="return confirm('Disable recovery? If you forget your password, you will NOT be able to recover your account.')">
                                        <i class="bi bi-x-lg"></i>
                                    </button>
                                </form>
                                {% endif %}
                            </div>
                        </div>
                        <small class="text-muted d-block mt-2">
                            {% if has_recovery %}
                            Allows password reset if you're locked out.
                            {% else %}
                            No recovery option - most secure, but no password reset possible.
                            {% endif %}
                        </small>
                    </div>
                </div>
                {% endif %}
                <h6 class="text-muted mb-3">Change Password</h6>
                <form method="POST" action="{{ url_for('account') }}" id="accountForm">
                    <div class="mb-3">
                        <label class="form-label">
                            <i class="bi bi-key me-1"></i> Current Password
                        </label>
                        <div class="input-group">
                            <input type="password" name="current_password" class="form-control"
                                   id="currentPasswordInput" required>
                            <button class="btn btn-outline-secondary" type="button"
                                    onclick="togglePassword('currentPasswordInput', this)">
                                <i class="bi bi-eye"></i>
                            </button>
                        </div>
                    </div>
                    <div class="mb-3">
                        <label class="form-label">
                            <i class="bi bi-key-fill me-1"></i> New Password
                        </label>
                        <div class="input-group">
                            <input type="password" name="new_password" class="form-control"
                                   id="newPasswordInput" required minlength="8">
                            <button class="btn btn-outline-secondary" type="button"
                                    onclick="togglePassword('newPasswordInput', this)">
                                <i class="bi bi-eye"></i>
                            </button>
                        </div>
                        <div class="form-text">Minimum 8 characters</div>
                    </div>
                    <div class="mb-4">
                        <label class="form-label">
                            <i class="bi bi-key-fill me-1"></i> Confirm New Password
                        </label>
                        <div class="input-group">
                            <input type="password" name="new_password_confirm" class="form-control"
                                   id="newPasswordConfirmInput" required minlength="8">
                            <button class="btn btn-outline-secondary" type="button"
                                    onclick="togglePassword('newPasswordConfirmInput', this)">
                                <i class="bi bi-eye"></i>
                            </button>
                        </div>
                    </div>
                    <button type="submit" class="btn btn-primary w-100">
                        <i class="bi bi-check-lg me-2"></i>Update Password
                    </button>
                </form>
            </div>
        </div>
        <!-- Saved Channel Keys Section -->
        <div class="card mt-4">
            <div class="card-header d-flex justify-content-between align-items-center">
                <h5 class="mb-0"><i class="bi bi-key-fill me-2"></i>Saved Channel Keys</h5>
                <span class="badge bg-secondary">{{ channel_keys|length }} / {{ max_channel_keys }}</span>
            </div>
            <div class="card-body">
                {% if channel_keys %}
                <div class="list-group list-group-flush mb-3">
                    {% for key in channel_keys %}
                    <div class="list-group-item d-flex justify-content-between align-items-center px-0">
                        <div>
                            <strong>{{ key.name }}</strong>
                            <br>
                            <code class="small text-muted">{{ key.channel_key[:4] }}...{{ key.channel_key[-4:] }}</code>
                            {% if key.last_used_at %}
                            <span class="text-muted small ms-2">Last used: {{ key.last_used_at[:10] }}</span>
                            {% endif %}
                        </div>
                        <div class="btn-group btn-group-sm">
                            <button type="button" class="btn btn-outline-secondary"
                                    onclick="renameKey({{ key.id }}, '{{ key.name }}')"
                                    title="Rename">
                                <i class="bi bi-pencil"></i>
                            </button>
                            <form method="POST" action="{{ url_for('account_delete_key', key_id=key.id) }}"
                                  style="display:inline;"
                                  onsubmit="return confirm('Delete key &quot;{{ key.name }}&quot;?')">
                                <button type="submit" class="btn btn-outline-danger" title="Delete">
                                    <i class="bi bi-trash"></i>
                                </button>
                            </form>
                        </div>
                    </div>
                    {% endfor %}
                </div>
                {% else %}
                <p class="text-muted mb-3">No saved channel keys. Save keys for quick access on encode/decode pages.</p>
                {% endif %}
                {% if can_save_key %}
                <hr>
                <h6 class="text-muted mb-3">Add New Key</h6>
                <form method="POST" action="{{ url_for('account_save_key') }}">
                    <div class="row g-2 mb-2">
                        <div class="col-5">
                            <input type="text" name="key_name" class="form-control form-control-sm"
                                   placeholder="Key name" required maxlength="50">
                        </div>
                        <div class="col-7">
                            <input type="text" name="channel_key" class="form-control form-control-sm font-monospace"
                                   placeholder="Channel key (32 hex chars)" required
                                   pattern="[0-9a-fA-F\-]{32,39}" title="32 hex characters">
                        </div>
                    </div>
                    <button type="submit" class="btn btn-sm btn-outline-primary">
                        <i class="bi bi-plus-lg me-1"></i>Save Key
                    </button>
                </form>
                {% else %}
                <div class="alert alert-info mb-0 small">
                    <i class="bi bi-info-circle me-1"></i>
                    Maximum of {{ max_channel_keys }} keys reached. Delete a key to add more.
                </div>
                {% endif %}
            </div>
        </div>
        <!-- Logout -->
        <div class="mt-4">
            <a href="{{ url_for('logout') }}" class="btn btn-outline-danger w-100">
                <i class="bi bi-box-arrow-left me-2"></i>Logout
            </a>
        </div>
    </div>
 </div>
 <!-- Rename Modal -->
 <div class="modal fade" id="renameModal" tabindex="-1">
    <div class="modal-dialog modal-sm">
        <div class="modal-content">
            <form method="POST" id="renameForm">
                <div class="modal-header">
                    <h6 class="modal-title">Rename Key</h6>
                    <button type="button" class="btn-close" data-bs-dismiss="modal"></button>
                </div>
                <div class="modal-body">
                    <input type="text" name="new_name" class="form-control" id="renameInput"
                           required maxlength="50">
                </div>
                <div class="modal-footer">
                    <button type="button" class="btn btn-sm btn-secondary" data-bs-dismiss="modal">Cancel</button>
                    <button type="submit" class="btn btn-sm btn-primary">Rename</button>
                </div>
            </form>
        </div>
    </div>
 </div>
 {% endblock %}
 {% block scripts %}
 <script src="{{ url_for('static', filename='js/auth.js') }}"></script>
 <script>
 StegasooAuth.initPasswordConfirmation('accountForm', 'newPasswordInput', 'newPasswordConfirmInput');
 function renameKey(keyId, currentName) {
    document.getElementById('renameInput').value = currentName;
    document.getElementById('renameForm').action = '/account/keys/' + keyId + '/rename';
    new bootstrap.Modal(document.getElementById('renameModal')).show();
 }
 </script>
 {% endblock %}
--- a/frontends/web/templates/admin/password_reset.html
+++ b/frontends/web/templates/admin/password_reset.html
@@ -0,0 +1,50 @@
 {% extends "base.html" %}
 {% block title %}Password Reset - Stegasoo{% endblock %}
 {% block content %}
 <div class="row justify-content-center">
    <div class="col-md-6 col-lg-5">
        <div class="card border-warning">
            <div class="card-header bg-warning text-dark">
                <i class="bi bi-key fs-4 me-2"></i>
                <span class="fs-5">Password Reset</span>
            </div>
            <div class="card-body">
                <div class="alert alert-warning">
                    <i class="bi bi-exclamation-triangle me-2"></i>
                    <strong>Important:</strong> This password will only be shown once.
                    Make sure to share it with <strong>{{ username }}</strong> securely.
                </div>
                <p class="text-muted">
                    The user's sessions have been invalidated. They will need to log in
                    again with the new password.
                </p>
                <div class="mb-4">
                    <label class="form-label text-muted small">New Password for {{ username }}</label>
                    <div class="input-group">
                        <input type="text" class="form-control form-control-lg font-monospace"
                               value="{{ password }}" readonly id="passwordField">
                        <button class="btn btn-outline-secondary" type="button"
                                onclick="copyField('passwordField')" title="Copy password">
                            <i class="bi bi-clipboard"></i>
                        </button>
                    </div>
                </div>
                <div class="d-grid">
                    <a href="{{ url_for('admin_users') }}" class="btn btn-primary">
                        <i class="bi bi-arrow-left me-2"></i>Back to Users
                    </a>
                </div>
            </div>
        </div>
    </div>
 </div>
 {% endblock %}
 {% block scripts %}
 <script src="{{ url_for('static', filename='js/auth.js') }}"></script>
 {% endblock %}
--- a/frontends/web/templates/admin/user_created.html
+++ b/frontends/web/templates/admin/user_created.html
@@ -0,0 +1,60 @@
 {% extends "base.html" %}
 {% block title %}User Created - Stegasoo{% endblock %}
 {% block content %}
 <div class="row justify-content-center">
    <div class="col-md-6 col-lg-5">
        <div class="card border-success">
            <div class="card-header bg-success text-white">
                <i class="bi bi-check-circle fs-4 me-2"></i>
                <span class="fs-5">User Created Successfully</span>
            </div>
            <div class="card-body">
                <div class="alert alert-warning">
                    <i class="bi bi-exclamation-triangle me-2"></i>
                    <strong>Important:</strong> This password will only be shown once.
                    Make sure to share it with the user securely.
                </div>
                <div class="mb-3">
                    <label class="form-label text-muted small">Username</label>
                    <div class="input-group">
                        <input type="text" class="form-control form-control-lg font-monospace"
                               value="{{ username }}" readonly id="usernameField">
                        <button class="btn btn-outline-secondary" type="button"
                                onclick="copyField('usernameField')" title="Copy username">
                            <i class="bi bi-clipboard"></i>
                        </button>
                    </div>
                </div>
                <div class="mb-4">
                    <label class="form-label text-muted small">Password</label>
                    <div class="input-group">
                        <input type="text" class="form-control form-control-lg font-monospace"
                               value="{{ password }}" readonly id="passwordField">
                        <button class="btn btn-outline-secondary" type="button"
                                onclick="copyField('passwordField')" title="Copy password">
                            <i class="bi bi-clipboard"></i>
                        </button>
                    </div>
                </div>
                <div class="d-grid gap-2">
                    <a href="{{ url_for('admin_user_new') }}" class="btn btn-primary">
                        <i class="bi bi-person-plus me-2"></i>Add Another User
                    </a>
                    <a href="{{ url_for('admin_users') }}" class="btn btn-outline-secondary">
                        <i class="bi bi-arrow-left me-2"></i>Back to Users
                    </a>
                </div>
            </div>
        </div>
    </div>
 </div>
 {% endblock %}
 {% block scripts %}
 <script src="{{ url_for('static', filename='js/auth.js') }}"></script>
 {% endblock %}
--- a/frontends/web/templates/admin/user_new.html
+++ b/frontends/web/templates/admin/user_new.html
@@ -0,0 +1,166 @@
 {% extends "base.html" %}
 {% block title %}Add User - Stegasoo{% endblock %}
 {% block content %}
 <div class="row justify-content-center">
    <div class="col-md-6 col-lg-5">
        <div class="card">
            <div class="card-header">
                <i class="bi bi-person-plus fs-4 me-2"></i>
                <span class="fs-5">Add New User</span>
            </div>
            <div class="card-body">
                <form id="createUserForm">
                    <div class="mb-3">
                        <label class="form-label">
                            <i class="bi bi-person me-1"></i> Username
                        </label>
                        <input type="text" name="username" id="usernameInput" class="form-control"
                               placeholder="e.g., john_doe or john@example.com"
                               pattern="[a-zA-Z0-9][a-zA-Z0-9_\-@.]{2,79}"
                               title="3-80 characters, letters/numbers/underscore/hyphen/@/."
                               required autofocus>
                        <div class="form-text">
                            Letters, numbers, underscore, hyphen, @ and . allowed.
                        </div>
                    </div>
                    <div class="mb-4">
                        <label class="form-label">
                            <i class="bi bi-key me-1"></i> Password
                        </label>
                        <div class="input-group">
                            <input type="text" name="password" id="passwordInput"
                                   class="form-control" value="{{ temp_password }}"
                                   minlength="8" required>
                            <button class="btn btn-outline-secondary" type="button"
                                    onclick="regeneratePassword()" title="Generate new password">
                                <i class="bi bi-arrow-repeat"></i>
                            </button>
                        </div>
                        <div class="form-text">
                            Auto-generated password. You can edit or regenerate it.
                        </div>
                    </div>
                    <div id="errorAlert" class="alert alert-danger d-none"></div>
                    <div class="d-flex gap-2">
                        <button type="submit" class="btn btn-primary flex-grow-1" id="createBtn">
                            <i class="bi bi-person-check me-2"></i>Create User
                        </button>
                        <a href="{{ url_for('admin_users') }}" class="btn btn-outline-secondary">
                            Cancel
                        </a>
                    </div>
                </form>
            </div>
        </div>
    </div>
 </div>
 <!-- Success Modal -->
 <div class="modal fade" id="successModal" tabindex="-1" data-bs-backdrop="static">
    <div class="modal-dialog modal-dialog-centered">
        <div class="modal-content border-success">
            <div class="modal-header bg-success text-white">
                <h5 class="modal-title">
                    <i class="bi bi-check-circle me-2"></i>User Created
                </h5>
            </div>
            <div class="modal-body">
                <div class="alert alert-warning mb-3 py-2">
                    <i class="bi bi-exclamation-triangle me-1"></i>
                    Password shown once. Copy it now.
                </div>
                <div class="row mb-3">
                    <div class="col-6">
                        <label class="form-label text-muted small mb-1">Username</label>
                        <div class="input-group">
                            <input type="text" class="form-control font-monospace"
                                   id="createdUsername" readonly>
                            <button class="btn btn-outline-secondary" type="button"
                                    onclick="copyField('createdUsername')" title="Copy">
                                <i class="bi bi-clipboard"></i>
                            </button>
                        </div>
                    </div>
                    <div class="col-6">
                        <label class="form-label text-muted small mb-1">Password</label>
                        <div class="input-group">
                            <input type="text" class="form-control font-monospace"
                                   id="createdPassword" readonly>
                            <button class="btn btn-outline-secondary" type="button"
                                    onclick="copyField('createdPassword')" title="Copy">
                                <i class="bi bi-clipboard"></i>
                            </button>
                        </div>
                    </div>
                </div>
                <div class="d-flex justify-content-end gap-2">
                    <button type="button" class="btn btn-primary" onclick="addAnother()">
                        <i class="bi bi-person-plus me-1"></i>Add Another
                    </button>
                    <a href="{{ url_for('admin_users') }}" class="btn btn-outline-secondary">
                        Done
                    </a>
                </div>
            </div>
        </div>
    </div>
 </div>
 {% endblock %}
 {% block scripts %}
 <script src="{{ url_for('static', filename='js/auth.js') }}"></script>
 <script>
 const form = document.getElementById('createUserForm');
 const errorAlert = document.getElementById('errorAlert');
 const createBtn = document.getElementById('createBtn');
 const successModal = new bootstrap.Modal(document.getElementById('successModal'));
 form.addEventListener('submit', async function(e) {
    e.preventDefault();
    errorAlert.classList.add('d-none');
    createBtn.disabled = true;
    createBtn.innerHTML = '<span class="spinner-border spinner-border-sm me-2"></span>Creating...';
    const formData = new FormData(form);
    try {
        const response = await fetch('{{ url_for("admin_user_new") }}', {
            method: 'POST',
            body: formData,
            headers: { 'X-Requested-With': 'XMLHttpRequest' }
        });
        const data = await response.json();
        if (data.success) {
            document.getElementById('createdUsername').value = data.username;
            document.getElementById('createdPassword').value = data.password;
            successModal.show();
        } else {
            errorAlert.textContent = data.error;
            errorAlert.classList.remove('d-none');
        }
    } catch (err) {
        errorAlert.textContent = 'An error occurred. Please try again.';
        errorAlert.classList.remove('d-none');
    }
    createBtn.disabled = false;
    createBtn.innerHTML = '<i class="bi bi-person-check me-2"></i>Create User';
 });
 function addAnother() {
    successModal.hide();
    document.getElementById('usernameInput').value = '';
    regeneratePassword();
    document.getElementById('usernameInput').focus();
 }
 </script>
 {% endblock %}
--- a/frontends/web/templates/admin/users.html
+++ b/frontends/web/templates/admin/users.html
@@ -0,0 +1,95 @@
 {% extends "base.html" %}
 {% block title %}Manage Users - Stegasoo{% endblock %}
 {% block content %}
 <div class="row justify-content-center">
    <div class="col-md-10 col-lg-8">
        <div class="card">
            <div class="card-header d-flex justify-content-between align-items-center">
                <div>
                    <i class="bi bi-people fs-4 me-2"></i>
                    <span class="fs-5">User Management</span>
                </div>
                <div class="text-muted small">
                    {{ user_count }} / {{ max_users }} users
                </div>
            </div>
            <div class="card-body">
                {% if can_create %}
                <div class="mb-4">
                    <a href="{{ url_for('admin_user_new') }}" class="btn btn-primary">
                        <i class="bi bi-person-plus me-2"></i>Add User
                    </a>
                </div>
                {% else %}
                <div class="alert alert-warning mb-4">
                    <i class="bi bi-exclamation-triangle me-2"></i>
                    Maximum of {{ max_users }} users reached.
                </div>
                {% endif %}
                <div class="table-responsive">
                    <table class="table table-hover mb-0">
                        <thead>
                            <tr>
                                <th>Username</th>
                                <th>Role</th>
                                <th>Created</th>
                                <th class="text-end">Actions</th>
                            </tr>
                        </thead>
                        <tbody>
                            {% for user in users %}
                            <tr>
                                <td>
                                    <i class="bi bi-person me-2"></i>
                                    {{ user.username }}
                                    {% if user.id == current_user.id %}
                                    <span class="badge bg-info ms-2">You</span>
                                    {% endif %}
                                </td>
                                <td>
                                    {% if user.is_admin %}
                                    <span class="badge bg-warning text-dark">
                                        <i class="bi bi-shield-check me-1"></i>Admin
                                    </span>
                                    {% else %}
                                    <span class="badge bg-secondary">User</span>
                                    {% endif %}
                                </td>
                                <td class="text-muted small">
                                    {{ user.created_at[:10] if user.created_at else 'Unknown' }}
                                </td>
                                <td class="text-end">
                                    {% if user.id != current_user.id %}
                                    <form method="POST" action="{{ url_for('admin_user_reset_password', user_id=user.id) }}"
                                          class="d-inline" onsubmit="return confirm('Reset password for {{ user.username }}?')">
                                        <button type="submit" class="btn btn-sm btn-outline-warning" title="Reset Password">
                                            <i class="bi bi-key"></i>
                                        </button>
                                    </form>
                                    <form method="POST" action="{{ url_for('admin_user_delete', user_id=user.id) }}"
                                          class="d-inline" onsubmit="return confirm('Delete user {{ user.username }}? This cannot be undone.')">
                                        <button type="submit" class="btn btn-sm btn-outline-danger" title="Delete User">
                                            <i class="bi bi-trash"></i>
                                        </button>
                                    </form>
                                    {% else %}
                                    <span class="text-muted small">-</span>
                                    {% endif %}
                                </td>
                            </tr>
                            {% endfor %}
                        </tbody>
                    </table>
                </div>
            </div>
            <div class="card-footer text-muted small">
                <i class="bi bi-info-circle me-1"></i>
                Admins can add up to {{ max_users }} regular users.
            </div>
        </div>
    </div>
 </div>
 {% endblock %}
--- a/frontends/web/templates/base.html
+++ b/frontends/web/templates/base.html
@@ -14,7 +14,10 @@
        <div class="container">
            <a class="navbar-brand d-flex align-items-center" href="/">
                <img src="{{ url_for('static', filename='logo.svg') }}" alt="Stegasoo" height="36" class="me-2">
-                <span class="fw-bold">Stegasoo</span>
+                <span style="position: relative; display: inline-block; margin-top: -14px;">
                    <span class="fw-bold title-gold">Stegasoo</span>
                    <span class="badge bg-success" style="position: absolute; font-size: 0.45rem; bottom: -8px; right: 6px;">v4.1</span>
                </span>
            </a>
            <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNav">
                <span class="navbar-toggler-icon"></span>
@@ -24,37 +27,66 @@
                    <li class="nav-item">
                        <a class="nav-link" href="/"><i class="bi bi-house me-1"></i> Home</a>
                    </li>
                    {% if not auth_enabled or is_authenticated %}
                    <li class="nav-item">
                        <a class="nav-link" href="/encode"><i class="bi bi-lock me-1"></i> Encode</a>
                    </li>
                    <li class="nav-item">
                        <a class="nav-link" href="/decode"><i class="bi bi-unlock me-1"></i> Decode</a>
                    </li>
                    <li class="nav-item">
                        <a class="nav-link" href="/generate"><i class="bi bi-key me-1"></i> Generate</a>
                    </li>
-
+                    {% endif %}
                    <li class="nav-item">
                        <a class="nav-link" href="/about"><i class="bi bi-info-circle me-1"></i> About</a>
                    </li>
                    <li class="nav-item">
                        <a class="nav-link" href="/tools"><i class="bi bi-tools me-1"></i> Tools</a>
                    </li>
                    {% if auth_enabled %}
                        {% if is_authenticated %}
                        <li class="nav-item dropdown">
                            <a class="nav-link dropdown-toggle" href="#" role="button" data-bs-toggle="dropdown">
                                <i class="bi bi-person-circle me-1"></i> {{ username }}
                            </a>
                            <ul class="dropdown-menu dropdown-menu-end dropdown-menu-dark">
                                <li><a class="dropdown-item" href="/account"><i class="bi bi-gear me-2"></i>Account</a></li>
                                {% if is_admin %}
                                <li><a class="dropdown-item" href="/admin/users"><i class="bi bi-people me-2"></i>Users</a></li>
                                {% endif %}
                                <li><hr class="dropdown-divider"></li>
                                <li><a class="dropdown-item" href="/logout"><i class="bi bi-box-arrow-left me-2"></i>Logout</a></li>
                            </ul>
                        </li>
                        {% else %}
                        <li class="nav-item">
                            <a class="nav-link" href="/login"><i class="bi bi-box-arrow-in-right me-1"></i> Login</a>
                        </li>
                        {% endif %}
                    {% endif %}
                </ul>
            </div>
        </div>
    </nav>
    <main class="container py-5">
        <!-- Toast notifications container -->
        <div class="toast-container position-fixed end-0 p-3" style="z-index: 1100; top: 70px;">
            {% with messages = get_flashed_messages(with_categories=true) %}
            {% if messages %}
                {% for category, message in messages %}
-                    <div class="alert alert-{{ 'danger' if category == 'error' else ('warning' if category == 'warning' else 'success') }} alert-dismissible fade show" role="alert">
+                    <div class="toast show align-items-center text-bg-{{ 'danger' if category == 'error' else ('warning' if category == 'warning' else 'success') }} border-0 fade" role="alert" data-bs-autohide="true" data-bs-delay="10000">
                        <div class="d-flex">
                            <div class="toast-body">
                                <i class="bi bi-{{ 'exclamation-triangle' if category == 'error' else ('exclamation-circle' if category == 'warning' else 'check-circle') }} me-2"></i>
                                {{ message }}
-                        <button type="button" class="btn-close" data-bs-dismiss="alert"></button>
+                            </div>
                            <button type="button" class="btn-close btn-close-white me-2 m-auto" data-bs-dismiss="toast"></button>
                        </div>
                    </div>
                {% endfor %}
            {% endif %}
            {% endwith %}
        </div>
        {% block content %}{% endblock %}
    </main>
@@ -69,6 +101,10 @@
    </footer>
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/js/bootstrap.bundle.min.js"></script>
    <script>
    // Initialize toasts (auto-hide after delay)
    document.querySelectorAll('.toast').forEach(el => new bootstrap.Toast(el));
    </script>
    {% block scripts %}{% endblock %}
 </body>
 </html>
--- a/frontends/web/templates/decode.html
+++ b/frontends/web/templates/decode.html
@@ -120,13 +120,11 @@
                    <h6><i class="bi bi-check-circle me-2"></i>Message Decrypted Successfully!</h6>
                </div>
-                <label class="form-label text-muted">Decoded Message:</label>
+                <label class="form-label text-muted">Decoded Message: <small class="text-secondary">(click to copy)</small></label>
-                <div class="alert-message p-3 rounded bg-dark border border-secondary mb-2" id="decodedContent" style="white-space: pre-wrap;">{{ decoded_message }}</div>
+                <div class="alert-message p-3 rounded bg-dark border border-secondary mb-3" id="decodedContent" style="white-space: pre-wrap; cursor: pointer; transition: border-color 0.2s;"
-                <div class="d-flex justify-content-end mb-3">
+                     onclick="navigator.clipboard.writeText(this.innerText).then(() => { this.style.borderColor = '#198754'; this.dataset.origText = this.innerHTML; this.innerHTML = '<i class=\'bi bi-check-circle text-success\'></i> Copied to clipboard!'; setTimeout(() => { this.innerHTML = this.dataset.origText; this.style.borderColor = ''; }, 1500); }).catch(() => alert('Failed to copy'))"
-                    <button class="btn btn-sm btn-outline-light" onclick="navigator.clipboard.writeText(document.getElementById('decodedContent').innerText).then(() => { this.innerHTML = '<i class=\'bi bi-check\'></i> Copied!'; setTimeout(() => this.innerHTML = '<i class=\'bi bi-clipboard\'></i> Copy', 2000); }).catch(() => alert('Failed to copy'))">
+                     onmouseover="this.style.borderColor = '#6c757d'"
-                        <i class="bi bi-clipboard"></i> Copy
+                     onmouseout="this.style.borderColor = ''">{{ decoded_message }}</div>
                    </button>
                </div>
                <a href="/decode" class="btn btn-outline-light w-100">
                    <i class="bi bi-arrow-repeat me-2"></i>Decode Another
@@ -327,11 +325,11 @@
                    <!-- PIN + Channel Row -->
                    <div class="row">
-                        <div class="col-md-4 mb-3">
+                        <div class="col-md-6 mb-3">
                          <div class="security-box h-100">
                            <label class="form-label"><i class="bi bi-123 me-1"></i> PIN</label>
                            <div class="input-group pin-input-container">
-                                <input type="password" name="pin" class="form-control" id="pinInput" placeholder="••••••" maxlength="9" style="max-width: 180px;">
+                                <input type="password" name="pin" class="form-control" id="pinInput" placeholder="••••••" maxlength="9">
                                <button class="btn btn-outline-secondary" type="button" data-toggle-password="pinInput">
                                    <i class="bi bi-eye"></i>
                                </button>
@@ -340,30 +338,37 @@
                          </div>
                        </div>
-                        <div class="col-md-8 mb-3">
+                        <div class="col-md-6 mb-3">
                          <div class="security-box h-100">
                            <label class="form-label">
                                <i class="bi bi-broadcast me-1"></i> Channel
-                                <span class="badge bg-info ms-1">v4.0</span>
+                                <span class="badge bg-info ms-1">v4.1</span>
                                <a href="/about#channel-keys" class="text-muted ms-1" title="Learn about channels"><i class="bi bi-info-circle"></i></a>
                            </label>
                            <select class="form-select" name="channel_key" id="channelSelectDec">
                                <option value="auto" selected>Auto{% if channel_configured %} (Server Key){% endif %}</option>
                                <option value="none">Public</option>
-                                <option value="custom">Custom</option>
+                                {% if saved_channel_keys %}
                                <optgroup label="Saved Keys">
                                    {% for key in saved_channel_keys %}
                                    <option value="{{ key.channel_key }}" data-key-id="{{ key.id }}">{{ key.name }} ({{ key.channel_key[:4] }}...)</option>
                                    {% endfor %}
                                </optgroup>
                                {% endif %}
                                <option value="custom">Custom...</option>
                            </select>
                            <!-- Server channel indicator (compact) -->
-                            {% if channel_configured %}
+                            <div class="small text-success mt-2 {% if not channel_configured %}d-none{% endif %}" id="channelServerInfoDec" data-fingerprint="{{ (channel_fingerprint[:4] if channel_fingerprint else '') }}-••••-···-••••-{{ channel_fingerprint[-4:] if channel_fingerprint else '' }}">
-                            <div class="small text-success mt-2">
+                                {% if channel_configured and channel_fingerprint %}
                                <i class="bi bi-shield-lock me-1"></i>
                                Server: <code>{{ channel_fingerprint[:4] }}-••••-···-••••-{{ channel_fingerprint[-4:] }}</code>
                            </div>
                                {% endif %}
                            </div>
                          </div>
                        </div>
                    </div>
                    <!-- Custom Channel Key Input (shown when Custom selected) -->
                    <div class="mb-4 d-none" id="channelCustomInputDec">
--- a/frontends/web/templates/encode.html
+++ b/frontends/web/templates/encode.html
@@ -394,11 +394,11 @@
                    <!-- PIN + Channel Row -->
                    <div class="row">
-                        <div class="col-md-4 mb-3">
+                        <div class="col-md-6 mb-3">
                          <div class="security-box h-100">
                            <label class="form-label"><i class="bi bi-123 me-1"></i> PIN</label>
                            <div class="input-group pin-input-container">
-                              <input type="password" name="pin" class="form-control" id="pinInput" placeholder="••••••" maxlength="9" style="max-width: 180px;">
+                              <input type="password" name="pin" class="form-control" id="pinInput" placeholder="••••••" maxlength="9">
                              <button class="btn btn-outline-secondary" type="button" data-toggle-password="pinInput">
                                <i class="bi bi-eye"></i>
                              </button>
@@ -407,30 +407,37 @@
                          </div>
                        </div>
-                        <div class="col-md-8 mb-3">
+                        <div class="col-md-6 mb-3">
                          <div class="security-box h-100">
                            <label class="form-label">
                                <i class="bi bi-broadcast me-1"></i> Channel
-                                <span class="badge bg-info ms-1">v4.0</span>
+                                <span class="badge bg-info ms-1">v4.1</span>
                                <a href="/about#channel-keys" class="text-muted ms-1" title="Learn about channels"><i class="bi bi-info-circle"></i></a>
                            </label>
                            <select class="form-select" name="channel_key" id="channelSelect">
                                <option value="auto" selected>Auto{% if channel_configured %} (Server Key){% endif %}</option>
                                <option value="none">Public</option>
-                                <option value="custom">Custom</option>
+                                {% if saved_channel_keys %}
                                <optgroup label="Saved Keys">
                                    {% for key in saved_channel_keys %}
                                    <option value="{{ key.channel_key }}" data-key-id="{{ key.id }}">{{ key.name }} ({{ key.channel_key[:4] }}...)</option>
                                    {% endfor %}
                                </optgroup>
                                {% endif %}
                                <option value="custom">Custom...</option>
                            </select>
                            <!-- Server channel indicator (compact) -->
-                            {% if channel_configured %}
+                            <div class="small text-success mt-2 {% if not channel_configured %}d-none{% endif %}" id="channelServerInfo" data-fingerprint="{{ (channel_fingerprint[:4] if channel_fingerprint else '') }}-••••-···-••••-{{ channel_fingerprint[-4:] if channel_fingerprint else '' }}">
-                            <div class="small text-success mt-2" id="channelServerInfo">
+                                {% if channel_configured and channel_fingerprint %}
                                <i class="bi bi-shield-lock me-1"></i>
                                Server: <code>{{ channel_fingerprint[:4] }}-••••-···-••••-{{ channel_fingerprint[-4:] }}</code>
                            </div>
                                {% endif %}
                            </div>
                          </div>
                        </div>
                    </div>
                    <!-- Custom Channel Key Input (shown when Custom selected) -->
                    <div class="mb-4 d-none" id="channelCustomInput">
--- a/frontends/web/templates/generate.html
+++ b/frontends/web/templates/generate.html
@@ -74,22 +74,32 @@
                        </div>
                    </div>
-                    <hr class="my-4">
+                    <button type="submit" class="btn btn-primary btn-lg w-100 mt-4">
                        <i class="bi bi-shuffle me-2"></i>Generate Credentials
                    </button>
                </form>
-                    <!-- Channel Key Generation (v4.0.0) -->
+                <!-- Channel Key Accordion (Advanced) -->
-                    <div class="mb-4">
+                <div class="accordion mt-4" id="advancedAccordion">
-                        <label class="form-label">
+                    <div class="accordion-item bg-dark">
-                            <i class="bi bi-broadcast me-1"></i> Channel Key
+                        <h2 class="accordion-header">
-                            <span class="badge bg-info ms-1">v4.0</span>
+                            <button class="accordion-button collapsed bg-dark text-light" type="button"
-                            <a href="{{ url_for('about') }}#channel-keys" class="text-muted ms-2" title="Learn about channel keys">
+                                    data-bs-toggle="collapse" data-bs-target="#channelKeyCollapse">
-                                <i class="bi bi-question-circle"></i>
+                                <i class="bi bi-broadcast me-2"></i>Channel Key
-                            </a>
+                                <span class="badge bg-info ms-2">Advanced</span>
-                        </label>
+                            </button>
                        </h2>
                        <div id="channelKeyCollapse" class="accordion-collapse collapse" data-bs-parent="#advancedAccordion">
                            <div class="accordion-body">
                                <p class="text-muted small mb-3">
                                    Channel keys create private encoding channels. Only users with the same key can decode each other's images.
                                    <a href="{{ url_for('about') }}#channel-keys" class="text-info">Learn more</a>
                                </p>
-                        <div class="input-group input-group-sm">
+                                <div class="input-group">
                                    <span class="input-group-text"><i class="bi bi-key"></i></span>
                                    <input type="text" class="form-control font-monospace" id="channelKeyGenerated"
-                                   placeholder="Click Generate" readonly>
+                                           placeholder="Click Generate to create a key" readonly>
                                    <button class="btn btn-outline-primary" type="button" id="generateChannelKeyBtn">
                                        <i class="bi bi-shuffle me-1"></i>Generate
                                    </button>
@@ -97,13 +107,14 @@
                                        <i class="bi bi-clipboard"></i>
                                    </button>
                                </div>
-                        <div class="form-text">For private groups: generate, then use <strong>Custom</strong> mode when encoding/decoding.</div>
+                                <div class="form-text mt-2">
                                    <i class="bi bi-info-circle me-1"></i>
                                    After generating, configure this key in your server's environment or use <strong>Custom</strong> channel mode when encoding/decoding.
                                </div>
                            </div>
                        </div>
                    </div>
                </div>
                    <button type="submit" class="btn btn-primary btn-lg w-100 mt-3">
                        <i class="bi bi-shuffle me-2"></i>Generate Credentials
                    </button>
                </form>
                {% else %}
                <!-- Generated Credentials Display -->
@@ -498,61 +509,12 @@
 {% block scripts %}
 <script src="{{ url_for('static', filename='js/stegasoo.js') }}"></script>
-<script>
+<script src="{{ url_for('static', filename='js/generate.js') }}"></script>
 // ============================================================================
 // GENERATE PAGE - Form Controls
 // ============================================================================
 // Words range slider
 const wordsRange = document.getElementById('wordsRange');
 const wordsValue = document.getElementById('wordsValue');
 wordsRange?.addEventListener('input', function() {
    const bits = this.value * 11;
    wordsValue.textContent = `${this.value} words (~${bits} bits)`;
 });
 // Toggle PIN/RSA options visibility
 const usePinCheck = document.getElementById('usePinCheck');
 const useRsaCheck = document.getElementById('useRsaCheck');
 const pinOptions = document.getElementById('pinOptions');
 const rsaOptions = document.getElementById('rsaOptions');
 const rsaQrWarning = document.getElementById('rsaQrWarning');
 const rsaBitsSelect = document.getElementById('rsaBitsSelect');
 usePinCheck?.addEventListener('change', function() {
    pinOptions?.classList.toggle('d-none', !this.checked);
 });
 useRsaCheck?.addEventListener('change', function() {
    rsaOptions?.classList.toggle('d-none', !this.checked);
 });
 // RSA key size QR warning (>3072 bits)
 rsaBitsSelect?.addEventListener('change', function() {
    rsaQrWarning?.classList.toggle('d-none', parseInt(this.value) <= 3072);
 });
 {% if generated %}
-// ============================================================================
+<script>
-// GENERATE PAGE - Credential Display
+// Page-specific data from Jinja
-// ============================================================================
+const passphraseWords = '{{ passphrase|default("", true) }}'.split(' ').filter(w => w.length > 0);
 // PIN visibility toggle
 let pinHidden = false;
 function togglePinVisibility() {
    const pinDigits = document.getElementById('pinDigits');
    const icon = document.getElementById('pinToggleIcon');
    const text = document.getElementById('pinToggleText');
    pinHidden = !pinHidden;
    pinDigits?.classList.toggle('blurred', pinHidden);
    if (icon) icon.className = pinHidden ? 'bi bi-eye' : 'bi bi-eye-slash';
    if (text) text.textContent = pinHidden ? 'Show' : 'Hide';
 }
 // Copy PIN
 function copyPin() {
    Stegasoo.copyToClipboard(
        '{{ pin|default("", true) }}',
@@ -561,21 +523,6 @@ function copyPin() {
    );
 }
 // Passphrase visibility toggle
 let passphraseHidden = false;
 function togglePassphraseVisibility() {
    const display = document.getElementById('passphraseDisplay');
    const icon = document.getElementById('passphraseToggleIcon');
    const text = document.getElementById('passphraseToggleText');
    passphraseHidden = !passphraseHidden;
    display?.classList.toggle('blurred', passphraseHidden);
    if (icon) icon.className = passphraseHidden ? 'bi bi-eye' : 'bi bi-eye-slash';
    if (text) text.textContent = passphraseHidden ? 'Show' : 'Hide';
 }
 // Copy passphrase
 function copyPassphrase() {
    Stegasoo.copyToClipboard(
        '{{ passphrase|default("", true) }}',
@@ -584,148 +531,13 @@ function copyPassphrase() {
    );
 }
 // ============================================================================
 // Memory Aid Story Generation - Templates by word count
 // ============================================================================
 const passphrase = '{{ passphrase|default("", true) }}';
 const passphraseWords = passphrase.split(' ').filter(w => w.length > 0);
 let currentStoryTemplate = 0;
 // Templates organized by word count (3-12 words supported)
 const storyTemplatesByLength = {
    3: [
        w => `The ${hl(w[0])} ${hl(w[1])} ${hl(w[2])}.`,
        w => `${hl(w[0])} loves ${hl(w[1])} and ${hl(w[2])}.`,
        w => `A ${hl(w[0])} found a ${hl(w[1])} near the ${hl(w[2])}.`,
        w => `${hl(w[0])}, ${hl(w[1])}, ${hl(w[2])} — never forget.`,
        w => `The ${hl(w[0])} hid the ${hl(w[1])} under the ${hl(w[2])}.`,
    ],
    4: [
        w => `${hl(w[0])} and ${hl(w[1])} discovered a ${hl(w[2])} made of ${hl(w[3])}.`,
        w => `The ${hl(w[0])} ${hl(w[1])} ate ${hl(w[2])} for ${hl(w[3])}.`,
        w => `In the ${hl(w[0])}, a ${hl(w[1])} met a ${hl(w[2])} carrying ${hl(w[3])}.`,
        w => `${hl(w[0])} said "${hl(w[1])}" while holding a ${hl(w[2])} ${hl(w[3])}.`,
        w => `The secret: ${hl(w[0])}, ${hl(w[1])}, ${hl(w[2])}, ${hl(w[3])}.`,
    ],
    5: [
        w => `${hl(w[0])} traveled to ${hl(w[1])} seeking the ${hl(w[2])} of ${hl(w[3])} and ${hl(w[4])}.`,
        w => `The ${hl(w[0])} ${hl(w[1])} lived in a ${hl(w[2])} house with ${hl(w[3])} ${hl(w[4])}.`,
        w => `"${hl(w[0])}!" shouted ${hl(w[1])} as the ${hl(w[2])} ${hl(w[3])} flew toward ${hl(w[4])}.`,
        w => `Captain ${hl(w[0])} sailed the ${hl(w[1])} ${hl(w[2])} searching for ${hl(w[3])} ${hl(w[4])}.`,
        w => `In ${hl(w[0])} kingdom, ${hl(w[1])} guards protected the ${hl(w[2])} ${hl(w[3])} ${hl(w[4])}.`,
    ],
    6: [
        w => `${hl(w[0])} met ${hl(w[1])} at the ${hl(w[2])}. Together they found ${hl(w[3])}, ${hl(w[4])}, and ${hl(w[5])}.`,
        w => `The ${hl(w[0])} ${hl(w[1])} wore a ${hl(w[2])} hat while eating ${hl(w[3])} ${hl(w[4])} ${hl(w[5])}.`,
        w => `Detective ${hl(w[0])} found ${hl(w[1])} ${hl(w[2])} near the ${hl(w[3])} ${hl(w[4])} ${hl(w[5])}.`,
        w => `In the ${hl(w[0])} ${hl(w[1])}, a ${hl(w[2])} ${hl(w[3])} sang about ${hl(w[4])} ${hl(w[5])}.`,
        w => `Chef ${hl(w[0])} combined ${hl(w[1])}, ${hl(w[2])}, ${hl(w[3])}, ${hl(w[4])}, and ${hl(w[5])}.`,
    ],
    7: [
        w => `${hl(w[0])} and ${hl(w[1])} walked through the ${hl(w[2])} ${hl(w[3])} to find the ${hl(w[4])} ${hl(w[5])} ${hl(w[6])}.`,
        w => `The ${hl(w[0])} professor studied ${hl(w[1])} ${hl(w[2])} while drinking ${hl(w[3])} ${hl(w[4])} with ${hl(w[5])} ${hl(w[6])}.`,
        w => `"${hl(w[0])} ${hl(w[1])}!" yelled ${hl(w[2])} as ${hl(w[3])} ${hl(w[4])} attacked the ${hl(w[5])} ${hl(w[6])}.`,
        w => `In ${hl(w[0])}, King ${hl(w[1])} decreed that ${hl(w[2])} ${hl(w[3])} must honor ${hl(w[4])} ${hl(w[5])} ${hl(w[6])}.`,
    ],
    8: [
        w => `${hl(w[0])} ${hl(w[1])} and ${hl(w[2])} ${hl(w[3])} met at the ${hl(w[4])} ${hl(w[5])} to discuss ${hl(w[6])} ${hl(w[7])}.`,
        w => `The ${hl(w[0])} ${hl(w[1])} ${hl(w[2])} traveled from ${hl(w[3])} to ${hl(w[4])} carrying ${hl(w[5])} ${hl(w[6])} ${hl(w[7])}.`,
        w => `${hl(w[0])} discovered that ${hl(w[1])} ${hl(w[2])} plus ${hl(w[3])} ${hl(w[4])} equals ${hl(w[5])} ${hl(w[6])} ${hl(w[7])}.`,
    ],
    9: [
        w => `${hl(w[0])} ${hl(w[1])} ${hl(w[2])} watched as ${hl(w[3])} ${hl(w[4])} ${hl(w[5])} danced with ${hl(w[6])} ${hl(w[7])} ${hl(w[8])}.`,
        w => `In the ${hl(w[0])} ${hl(w[1])} ${hl(w[2])}, three friends — ${hl(w[3])}, ${hl(w[4])}, ${hl(w[5])} — found ${hl(w[6])} ${hl(w[7])} ${hl(w[8])}.`,
        w => `The recipe: ${hl(w[0])}, ${hl(w[1])}, ${hl(w[2])}, ${hl(w[3])}, ${hl(w[4])}, ${hl(w[5])}, ${hl(w[6])}, ${hl(w[7])}, ${hl(w[8])}.`,
    ],
    10: [
        w => `${hl(w[0])} ${hl(w[1])} told ${hl(w[2])} ${hl(w[3])} about the ${hl(w[4])} ${hl(w[5])} ${hl(w[6])} hidden in ${hl(w[7])} ${hl(w[8])} ${hl(w[9])}.`,
        w => `The ${hl(w[0])} ${hl(w[1])} ${hl(w[2])} ${hl(w[3])} ${hl(w[4])} lived beside ${hl(w[5])} ${hl(w[6])} ${hl(w[7])} ${hl(w[8])} ${hl(w[9])}.`,
    ],
    11: [
        w => `${hl(w[0])} ${hl(w[1])} ${hl(w[2])} and ${hl(w[3])} ${hl(w[4])} ${hl(w[5])} discovered ${hl(w[6])} ${hl(w[7])} ${hl(w[8])} ${hl(w[9])} ${hl(w[10])}.`,
        w => `In ${hl(w[0])} ${hl(w[1])}, the ${hl(w[2])} ${hl(w[3])} ${hl(w[4])} sang of ${hl(w[5])} ${hl(w[6])} ${hl(w[7])} ${hl(w[8])} ${hl(w[9])} ${hl(w[10])}.`,
    ],
    12: [
        w => `${hl(w[0])} ${hl(w[1])} ${hl(w[2])} met ${hl(w[3])} ${hl(w[4])} ${hl(w[5])} at the ${hl(w[6])} ${hl(w[7])} ${hl(w[8])} ${hl(w[9])} ${hl(w[10])} ${hl(w[11])}.`,
        w => `The twelve treasures: ${hl(w[0])}, ${hl(w[1])}, ${hl(w[2])}, ${hl(w[3])}, ${hl(w[4])}, ${hl(w[5])}, ${hl(w[6])}, ${hl(w[7])}, ${hl(w[8])}, ${hl(w[9])}, ${hl(w[10])}, ${hl(w[11])}.`,
    ],
 };
 function hl(word) {
    return `<span class="passphrase-word">${word}</span>`;
 }
 function generateStory(idx = null) {
    const count = passphraseWords.length;
    if (count === 0) return '';
    // Clamp to supported range (3-12)
    const templateKey = Math.max(3, Math.min(12, count));
    const templates = storyTemplatesByLength[templateKey];
    if (!templates || templates.length === 0) {
        // Fallback: just list the words
        return passphraseWords.map(w => hl(w)).join(' &mdash; ');
    }
    const templateIdx = (idx ?? currentStoryTemplate) % templates.length;
    return templates[templateIdx](passphraseWords);
 }
 function toggleMemoryAid() {
-    const container = document.getElementById('memoryAidContainer');
+    StegasooGenerate.toggleMemoryAid(passphraseWords);
    const icon = document.getElementById('memoryAidIcon');
    const text = document.getElementById('memoryAidText');
    const isHidden = container?.classList.contains('d-none');
    container?.classList.toggle('d-none', !isHidden);
    if (icon) icon.className = isHidden ? 'bi bi-lightbulb-fill' : 'bi bi-lightbulb';
    if (text) text.textContent = isHidden ? 'Hide Aid' : 'Memory Aid';
    if (isHidden) {
        document.getElementById('memoryStory').innerHTML = generateStory();
    }
 }
 function regenerateStory() {
-    const count = passphraseWords.length;
+    StegasooGenerate.regenerateStory(passphraseWords);
    const templateKey = Math.max(3, Math.min(12, count));
    const templates = storyTemplatesByLength[templateKey] || [];
    currentStoryTemplate = (currentStoryTemplate + 1) % Math.max(1, templates.length);
    document.getElementById('memoryStory').innerHTML = generateStory(currentStoryTemplate);
 }
 // Print QR code
 function printQrCode() {
    const qrImg = document.getElementById('qrCodeImage');
    if (!qrImg) return;
    const printWindow = window.open('', '_blank');
    printWindow.document.write(`<!DOCTYPE html>
 <html>
 <head>
    <title>Stegasoo RSA Key QR Code</title>
    <style>
        body { display: flex; flex-direction: column; align-items: center; justify-content: center; min-height: 100vh; margin: 0; font-family: sans-serif; }
        img { max-width: 400px; }
        .warning { margin-top: 20px; padding: 10px; border: 2px solid #ff9800; background: #fff3e0; max-width: 400px; text-align: center; font-size: 12px; }
    </style>
 </head>
 <body>
    <h2>Stegasoo RSA Private Key</h2>
    <img src="${qrImg.src}" alt="RSA Key QR Code">
    <div class="warning">
        <strong>⚠️ SECURITY WARNING</strong><br>
        This QR code contains your unencrypted RSA private key.<br>
        Store securely and destroy after use.
    </div>
    <script>window.onload = function() { window.print(); }<\/script>
 </body>
 </html>`);
    printWindow.document.close();
 }
 {% endif %}
 </script>
 {% endif %}
 {% endblock %}
--- a/frontends/web/templates/index.html
+++ b/frontends/web/templates/index.html
@@ -9,9 +9,9 @@
        <div class="d-flex align-items-end justify-content-center gap-4">
            <img src="{{ url_for('static', filename='logo.svg') }}" alt="Stegasoo" height="155">
            <div style="margin-bottom: 40px;">
-                <h1 class="display-4 fw-bold mb-2">
+                <h1 class="display-4 fw-bold mb-2 title-gold">
                    Stegasoo
-                    <span class="badge bg-success fs-6 ms-2">v4.0</span>
+                    <span class="badge bg-success fs-6 ms-2">v4.1</span>
                </h1>
                <p class="lead text-muted mb-0">Hide encrypted data in plain sight.</p>
            </div>
@@ -162,7 +162,7 @@
                    <li class="mb-1">
                        <i class="bi bi-broadcast text-success me-2"></i>
                        <strong>Channel keys</strong> for group isolation
-                        <span class="badge bg-info ms-1">v4.0</span>
+                        <span class="badge bg-info ms-1">v4.1</span>
                    </li>
                </ul>
            </div>
--- a/frontends/web/templates/login.html
+++ b/frontends/web/templates/login.html
@@ -0,0 +1,55 @@
 {% extends "base.html" %}
 {% block title %}Login - Stegasoo{% endblock %}
 {% block content %}
 <div class="row justify-content-center">
    <div class="col-md-5 col-lg-4">
        <div class="card">
            <div class="card-header text-center">
                <i class="bi bi-shield-lock fs-1 d-block mb-2"></i>
                <h5 class="mb-0">Login</h5>
            </div>
            <div class="card-body">
                <form method="POST" action="{{ url_for('login') }}">
                    <div class="mb-3">
                        <label class="form-label">
                            <i class="bi bi-person me-1"></i> Username
                        </label>
                        <input type="text" name="username" class="form-control"
                               placeholder="Enter your username" required autofocus>
                    </div>
                    <div class="mb-4">
                        <label class="form-label">
                            <i class="bi bi-key me-1"></i> Password
                        </label>
                        <div class="input-group">
                            <input type="password" name="password" class="form-control"
                                   id="passwordInput" required>
                            <button class="btn btn-outline-secondary" type="button"
                                    onclick="togglePassword('passwordInput', this)">
                                <i class="bi bi-eye"></i>
                            </button>
                        </div>
                    </div>
                    <button type="submit" class="btn btn-primary w-100">
                        <i class="bi bi-box-arrow-in-right me-2"></i>Login
                    </button>
                </form>
                <div class="text-center mt-3">
                    <a href="{{ url_for('recover') }}" class="text-muted small">
                        <i class="bi bi-key me-1"></i> Forgot password?
                    </a>
                </div>
            </div>
        </div>
    </div>
 </div>
 {% endblock %}
 {% block scripts %}
 <script src="{{ url_for('static', filename='js/auth.js') }}"></script>
 {% endblock %}
--- a/frontends/web/templates/recover.html
+++ b/frontends/web/templates/recover.html
@@ -0,0 +1,129 @@
 {% extends "base.html" %}
 {% block title %}Password Recovery - Stegasoo{% endblock %}
 {% block content %}
 <div class="row justify-content-center">
    <div class="col-md-6 col-lg-5">
        <div class="card">
            <div class="card-header text-center">
                <i class="bi bi-shield-lock fs-1 d-block mb-2"></i>
                <h5 class="mb-0">Password Recovery</h5>
            </div>
            <div class="card-body">
                <p class="text-muted text-center mb-4">
                    Enter your recovery key to reset your admin password.
                </p>
                <!-- Extract from Stego Backup -->
                <div class="accordion mb-3" id="stegoAccordion">
                    <div class="accordion-item">
                        <h2 class="accordion-header">
                            <button class="accordion-button collapsed py-2" type="button"
                                    data-bs-toggle="collapse" data-bs-target="#stegoExtract">
                                <i class="bi bi-incognito me-2"></i>
                                <small>Extract from stego backup</small>
                            </button>
                        </h2>
                        <div id="stegoExtract" class="accordion-collapse collapse"
                             data-bs-parent="#stegoAccordion">
                            <div class="accordion-body py-2">
                                <form method="POST" action="{{ url_for('recover_from_stego') }}"
                                      enctype="multipart/form-data">
                                    <div class="mb-2">
                                        <label class="form-label small mb-1">Stego Image</label>
                                        <input type="file" name="stego_image"
                                               class="form-control form-control-sm"
                                               accept="image/*" required>
                                    </div>
                                    <div class="mb-2">
                                        <label class="form-label small mb-1">Original Reference</label>
                                        <input type="file" name="reference_image"
                                               class="form-control form-control-sm"
                                               accept="image/*" required>
                                    </div>
                                    <button type="submit" class="btn btn-sm btn-outline-primary w-100">
                                        <i class="bi bi-unlock me-1"></i> Extract Key
                                    </button>
                                </form>
                            </div>
                        </div>
                    </div>
                </div>
                <form method="POST" action="{{ url_for('recover') }}" id="recoverForm">
                    <!-- Recovery Key Input -->
                    <div class="mb-3">
                        <label class="form-label">
                            <i class="bi bi-key-fill me-1"></i> Recovery Key
                        </label>
                        <textarea name="recovery_key" class="form-control font-monospace"
                                  rows="2" required
                                  placeholder="XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX"
                                  style="font-size: 0.9em;">{{ prefilled_key or '' }}</textarea>
                        <div class="form-text">
                            Paste your full recovery key (with or without dashes)
                        </div>
                    </div>
                    <hr>
                    <!-- New Password -->
                    <div class="mb-3">
                        <label class="form-label">
                            <i class="bi bi-lock me-1"></i> New Password
                        </label>
                        <div class="input-group">
                            <input type="password" name="new_password" class="form-control"
                                   id="passwordInput" required minlength="8">
                            <button class="btn btn-outline-secondary" type="button"
                                    onclick="togglePassword('passwordInput', this)">
                                <i class="bi bi-eye"></i>
                            </button>
                        </div>
                        <div class="form-text">Minimum 8 characters</div>
                    </div>
                    <!-- Confirm Password -->
                    <div class="mb-4">
                        <label class="form-label">
                            <i class="bi bi-lock-fill me-1"></i> Confirm Password
                        </label>
                        <div class="input-group">
                            <input type="password" name="new_password_confirm" class="form-control"
                                   id="passwordConfirmInput" required minlength="8">
                            <button class="btn btn-outline-secondary" type="button"
                                    onclick="togglePassword('passwordConfirmInput', this)">
                                <i class="bi bi-eye"></i>
                            </button>
                        </div>
                    </div>
                    <button type="submit" class="btn btn-primary w-100">
                        <i class="bi bi-check-lg me-2"></i>Reset Password
                    </button>
                </form>
                <div class="text-center mt-3">
                    <a href="{{ url_for('login') }}" class="text-muted small">
                        <i class="bi bi-arrow-left me-1"></i> Back to Login
                    </a>
                </div>
            </div>
        </div>
        <div class="alert alert-warning mt-4 small">
            <i class="bi bi-exclamation-triangle me-2"></i>
            <strong>Note:</strong> This will reset the admin password. If you don't have a valid recovery key,
            you'll need to delete the database and reconfigure Stegasoo.
        </div>
    </div>
 </div>
 {% endblock %}
 {% block scripts %}
 <script src="{{ url_for('static', filename='js/auth.js') }}"></script>
 <script>
 StegasooAuth.initPasswordConfirmation('recoverForm', 'passwordInput', 'passwordConfirmInput');
 </script>
 {% endblock %}
--- a/frontends/web/templates/regenerate_recovery.html
+++ b/frontends/web/templates/regenerate_recovery.html
@@ -0,0 +1,183 @@
 {% extends "base.html" %}
 {% block title %}Regenerate Recovery Key - Stegasoo{% endblock %}
 {% block content %}
 <div class="row justify-content-center">
    <div class="col-md-8 col-lg-6">
        <div class="card">
            <div class="card-header text-center">
                <i class="bi bi-arrow-repeat fs-1 d-block mb-2"></i>
                <h5 class="mb-0">{{ 'Regenerate' if has_existing else 'Generate' }} Recovery Key</h5>
            </div>
            <div class="card-body">
                {% if has_existing %}
                <!-- Warning for existing key -->
                <div class="alert alert-warning">
                    <i class="bi bi-exclamation-triangle me-2"></i>
                    <strong>Warning:</strong> Your existing recovery key will be invalidated.
                    Make sure to save this new key before continuing.
                </div>
                {% else %}
                <!-- Info for first-time setup -->
                <div class="alert alert-info">
                    <i class="bi bi-info-circle me-2"></i>
                    <strong>What is a recovery key?</strong><br>
                    If you forget your admin password, this key is the ONLY way to reset it.
                </div>
                {% endif %}
                <!-- Recovery Key Display -->
                <div class="mb-4">
                    <label class="form-label">
                        <i class="bi bi-key-fill me-1"></i> Your New Recovery Key
                    </label>
                    <div class="input-group">
                        <input type="text" class="form-control font-monospace text-center"
                               id="recoveryKey" value="{{ recovery_key }}" readonly
                               style="font-size: 1.1em; letter-spacing: 0.5px;">
                        <button class="btn btn-outline-secondary" type="button"
                                onclick="copyToClipboard()" title="Copy to clipboard">
                            <i class="bi bi-clipboard" id="copyIcon"></i>
                        </button>
                    </div>
                </div>
                <!-- QR Code (if available) -->
                {% if qr_base64 %}
                <div class="mb-4 text-center">
                    <label class="form-label d-block">
                        <i class="bi bi-qr-code me-1"></i> QR Code
                    </label>
                    <img src="data:image/png;base64,{{ qr_base64 }}"
                         alt="Recovery Key QR Code" class="img-fluid border rounded"
                         style="max-width: 200px;" id="qrImage">
                </div>
                {% endif %}
                <!-- Download Options -->
                <div class="mb-4">
                    <label class="form-label">
                        <i class="bi bi-download me-1"></i> Download Options
                    </label>
                    <div class="d-flex gap-2 flex-wrap">
                        <button class="btn btn-outline-primary btn-sm" onclick="downloadTextFile()">
                            <i class="bi bi-file-text me-1"></i> Text File
                        </button>
                        {% if qr_base64 %}
                        <button class="btn btn-outline-primary btn-sm" onclick="downloadQRImage()">
                            <i class="bi bi-image me-1"></i> QR Image
                        </button>
                        {% endif %}
                    </div>
                </div>
                <!-- Stego Backup Option -->
                <div class="mb-4">
                    <label class="form-label">
                        <i class="bi bi-incognito me-1"></i> Hide in Image
                    </label>
                    <form method="POST" action="{{ url_for('create_stego_backup') }}"
                          enctype="multipart/form-data" class="d-flex gap-2 align-items-end">
                        <input type="hidden" name="recovery_key" value="{{ recovery_key }}">
                        <div class="flex-grow-1">
                            <input type="file" name="carrier_image" class="form-control form-control-sm"
                                   accept="image/jpeg,image/png" required>
                            <div class="form-text">JPG/PNG, 50KB-2MB</div>
                        </div>
                        <button type="submit" class="btn btn-outline-secondary btn-sm">
                            <i class="bi bi-download me-1"></i> Stego
                        </button>
                    </form>
                </div>
                <hr>
                <!-- Confirmation Form -->
                <form method="POST" id="recoveryForm">
                    <input type="hidden" name="recovery_key" value="{{ recovery_key }}">
                    <!-- Confirm checkbox -->
                    <div class="form-check mb-3">
                        <input class="form-check-input" type="checkbox" id="confirmSaved"
                               onchange="updateButtons()">
                        <label class="form-check-label" for="confirmSaved">
                            I have saved my recovery key in a secure location
                        </label>
                    </div>
                    <div class="d-flex gap-2 justify-content-between">
                        <!-- Cancel button -->
                        <button type="submit" name="action" value="cancel"
                                class="btn btn-outline-secondary">
                            <i class="bi bi-x-lg me-1"></i> Cancel
                        </button>
                        <!-- Save button -->
                        <button type="submit" name="action" value="save"
                                class="btn btn-primary" id="saveBtn" disabled>
                            <i class="bi bi-check-lg me-1"></i> Save New Key
                        </button>
                    </div>
                </form>
            </div>
        </div>
    </div>
 </div>
 {% endblock %}
 {% block scripts %}
 <script>
 // Copy recovery key to clipboard
 function copyToClipboard() {
    const keyInput = document.getElementById('recoveryKey');
    navigator.clipboard.writeText(keyInput.value).then(() => {
        const icon = document.getElementById('copyIcon');
        icon.className = 'bi bi-clipboard-check';
        setTimeout(() => { icon.className = 'bi bi-clipboard'; }, 2000);
    });
 }
 // Download as text file
 function downloadTextFile() {
    const key = document.getElementById('recoveryKey').value;
    const content = `Stegasoo Recovery Key
 =====================
 ${key}
 IMPORTANT:
 - Keep this file in a secure location
 - Anyone with this key can reset admin passwords
 - Do not store with your password
 Generated: ${new Date().toISOString()}
 `;
    const blob = new Blob([content], { type: 'text/plain' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'stegasoo-recovery-key.txt';
    a.click();
    URL.revokeObjectURL(url);
 }
 // Download QR as image
 function downloadQRImage() {
    const img = document.getElementById('qrImage');
    if (!img) return;
    const a = document.createElement('a');
    a.href = img.src;
    a.download = 'stegasoo-recovery-qr.png';
    a.click();
 }
 // Enable save button when checkbox is checked
 function updateButtons() {
    const checkbox = document.getElementById('confirmSaved');
    const saveBtn = document.getElementById('saveBtn');
    saveBtn.disabled = !checkbox.checked;
 }
 </script>
 {% endblock %}
--- a/frontends/web/templates/setup.html
+++ b/frontends/web/templates/setup.html
@@ -0,0 +1,76 @@
 {% extends "base.html" %}
 {% block title %}Setup - Stegasoo{% endblock %}
 {% block content %}
 <div class="row justify-content-center">
    <div class="col-md-6 col-lg-5">
        <div class="card">
            <div class="card-header text-center">
                <i class="bi bi-gear-fill fs-1 d-block mb-2"></i>
                <h5 class="mb-0">Initial Setup</h5>
            </div>
            <div class="card-body">
                <p class="text-muted text-center mb-4">
                    Welcome to Stegasoo! Create your admin account to get started.
                </p>
                <form method="POST" action="{{ url_for('setup') }}" id="setupForm">
                    <div class="mb-3">
                        <label class="form-label">
                            <i class="bi bi-person me-1"></i> Username
                        </label>
                        <input type="text" name="username" class="form-control"
                               value="admin" required minlength="3">
                    </div>
                    <div class="mb-3">
                        <label class="form-label">
                            <i class="bi bi-key me-1"></i> Password
                        </label>
                        <div class="input-group">
                            <input type="password" name="password" class="form-control"
                                   id="passwordInput" required minlength="8">
                            <button class="btn btn-outline-secondary" type="button"
                                    onclick="togglePassword('passwordInput', this)">
                                <i class="bi bi-eye"></i>
                            </button>
                        </div>
                        <div class="form-text">Minimum 8 characters</div>
                    </div>
                    <div class="mb-4">
                        <label class="form-label">
                            <i class="bi bi-key-fill me-1"></i> Confirm Password
                        </label>
                        <div class="input-group">
                            <input type="password" name="password_confirm" class="form-control"
                                   id="passwordConfirmInput" required minlength="8">
                            <button class="btn btn-outline-secondary" type="button"
                                    onclick="togglePassword('passwordConfirmInput', this)">
                                <i class="bi bi-eye"></i>
                            </button>
                        </div>
                    </div>
                    <button type="submit" class="btn btn-primary w-100">
                        <i class="bi bi-check-lg me-2"></i>Create Admin Account
                    </button>
                </form>
            </div>
        </div>
        <div class="alert alert-info mt-4 small">
            <i class="bi bi-info-circle me-2"></i>
            This is a single-user setup. The admin account has full access to all features.
        </div>
    </div>
 </div>
 {% endblock %}
 {% block scripts %}
 <script src="{{ url_for('static', filename='js/auth.js') }}"></script>
 <script>
 StegasooAuth.initPasswordConfirmation('setupForm', 'passwordInput', 'passwordConfirmInput');
 </script>
 {% endblock %}
--- a/frontends/web/templates/setup_recovery.html
+++ b/frontends/web/templates/setup_recovery.html
@@ -0,0 +1,176 @@
 {% extends "base.html" %}
 {% block title %}Recovery Key Setup - Stegasoo{% endblock %}
 {% block content %}
 <div class="row justify-content-center">
    <div class="col-md-8 col-lg-6">
        <div class="card">
            <div class="card-header text-center">
                <i class="bi bi-shield-lock fs-1 d-block mb-2"></i>
                <h5 class="mb-0">Recovery Key Setup</h5>
                <small class="text-muted">Step 2 of 2</small>
            </div>
            <div class="card-body">
                <!-- Explanation -->
                <div class="alert alert-info">
                    <i class="bi bi-info-circle me-2"></i>
                    <strong>What is a recovery key?</strong><br>
                    If you forget your admin password, this key is the ONLY way to reset it.
                    Save it somewhere safe - it will not be shown again.
                </div>
                <!-- Recovery Key Display -->
                <div class="mb-4">
                    <label class="form-label">
                        <i class="bi bi-key-fill me-1"></i> Your Recovery Key
                    </label>
                    <div class="input-group">
                        <input type="text" class="form-control font-monospace text-center"
                               id="recoveryKey" value="{{ recovery_key }}" readonly
                               style="font-size: 1.1em; letter-spacing: 0.5px;">
                        <button class="btn btn-outline-secondary" type="button"
                                onclick="copyToClipboard()" title="Copy to clipboard">
                            <i class="bi bi-clipboard" id="copyIcon"></i>
                        </button>
                    </div>
                </div>
                <!-- QR Code (if available) -->
                {% if qr_base64 %}
                <div class="mb-4 text-center">
                    <label class="form-label d-block">
                        <i class="bi bi-qr-code me-1"></i> QR Code
                    </label>
                    <img src="data:image/png;base64,{{ qr_base64 }}"
                         alt="Recovery Key QR Code" class="img-fluid border rounded"
                         style="max-width: 200px;" id="qrImage">
                    <div class="mt-2">
                        <small class="text-muted">Scan with your phone's camera app</small>
                    </div>
                </div>
                {% endif %}
                <!-- Download Options -->
                <div class="mb-4">
                    <label class="form-label">
                        <i class="bi bi-download me-1"></i> Download Options
                    </label>
                    <div class="d-flex gap-2 flex-wrap">
                        <button class="btn btn-outline-primary btn-sm" onclick="downloadTextFile()">
                            <i class="bi bi-file-text me-1"></i> Text File
                        </button>
                        {% if qr_base64 %}
                        <button class="btn btn-outline-primary btn-sm" onclick="downloadQRImage()">
                            <i class="bi bi-image me-1"></i> QR Image
                        </button>
                        {% endif %}
                    </div>
                </div>
                <hr>
                <!-- Confirmation Form -->
                <form method="POST" id="recoveryForm">
                    <input type="hidden" name="recovery_key" value="{{ recovery_key }}">
                    <!-- Confirm checkbox -->
                    <div class="form-check mb-3">
                        <input class="form-check-input" type="checkbox" id="confirmSaved"
                               onchange="updateButtons()">
                        <label class="form-check-label" for="confirmSaved">
                            I have saved my recovery key in a secure location
                        </label>
                    </div>
                    <div class="d-flex gap-2 justify-content-between">
                        <!-- Skip button (no recovery) -->
                        <button type="submit" name="action" value="skip"
                                class="btn btn-outline-secondary"
                                onclick="return confirm('Are you sure? Without a recovery key, there is NO way to reset your password if you forget it.')">
                            <i class="bi bi-skip-forward me-1"></i> Skip (No Recovery)
                        </button>
                        <!-- Save button (with key) -->
                        <button type="submit" name="action" value="save"
                                class="btn btn-primary" id="saveBtn" disabled>
                            <i class="bi bi-check-lg me-1"></i> Continue
                        </button>
                    </div>
                </form>
            </div>
        </div>
        <!-- Security Notes -->
        <div class="card mt-3">
            <div class="card-header">
                <i class="bi bi-shield-check me-2"></i>Security Notes
            </div>
            <div class="card-body small">
                <ul class="mb-0">
                    <li>The recovery key is <strong>not stored</strong> - only a hash is saved</li>
                    <li>Keep it separate from your password (different location)</li>
                    <li>Anyone with this key can reset admin passwords</li>
                    <li>If you lose it and forget your password, you must recreate the database</li>
                </ul>
            </div>
        </div>
    </div>
 </div>
 {% endblock %}
 {% block scripts %}
 <script>
 // Copy recovery key to clipboard
 function copyToClipboard() {
    const keyInput = document.getElementById('recoveryKey');
    navigator.clipboard.writeText(keyInput.value).then(() => {
        const icon = document.getElementById('copyIcon');
        icon.className = 'bi bi-clipboard-check';
        setTimeout(() => { icon.className = 'bi bi-clipboard'; }, 2000);
    });
 }
 // Download as text file
 function downloadTextFile() {
    const key = document.getElementById('recoveryKey').value;
    const content = `Stegasoo Recovery Key
 =====================
 ${key}
 IMPORTANT:
 - Keep this file in a secure location
 - Anyone with this key can reset admin passwords
 - Do not store with your password
 Generated: ${new Date().toISOString()}
 `;
    const blob = new Blob([content], { type: 'text/plain' });
    const url = URL.createObjectURL(blob);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'stegasoo-recovery-key.txt';
    a.click();
    URL.revokeObjectURL(url);
 }
 // Download QR as image
 function downloadQRImage() {
    const img = document.getElementById('qrImage');
    if (!img) return;
    const a = document.createElement('a');
    a.href = img.src;
    a.download = 'stegasoo-recovery-qr.png';
    a.click();
 }
 // Enable save button when checkbox is checked
 function updateButtons() {
    const checkbox = document.getElementById('confirmSaved');
    const saveBtn = document.getElementById('saveBtn');
    saveBtn.disabled = !checkbox.checked;
 }
 </script>
 {% endblock %}
--- a/frontends/web/templates/tools.html
+++ b/frontends/web/templates/tools.html
@@ -0,0 +1,756 @@
 {% extends "base.html" %}
 {% block title %}Tools - Stegasoo{% endblock %}
 {% block content %}
 <style>
 /* Tool drop zone - compact */
 .tool-drop-zone {
    position: relative;
    min-height: 120px;
    border: 2px dashed rgba(255, 255, 255, 0.2);
    border-radius: 8px;
    background: rgba(0, 0, 0, 0.2);
    transition: all 0.3s ease;
    overflow: hidden;
 }
 .tool-drop-zone.drag-over {
    border-color: #63b3ed;
    background: rgba(99, 179, 237, 0.1);
 }
 .tool-drop-zone input[type="file"] {
    position: absolute;
    inset: 0;
    opacity: 0;
    cursor: pointer;
    z-index: 10;
 }
 .tool-drop-zone .drop-label {
    text-align: center;
    padding: 25px 20px;
 }
 .tool-drop-zone .drop-icon {
    font-size: 2rem;
    color: rgba(255, 255, 255, 0.3);
    transition: all 0.3s ease;
 }
 .tool-drop-zone.drag-over .drop-icon {
    color: #63b3ed;
    transform: scale(1.1);
 }
 /* Preview state */
 .tool-drop-zone.has-file .drop-label {
    display: none;
 }
 .tool-drop-zone .preview-container {
    display: none;
    padding: 12px;
 }
 .tool-drop-zone.has-file .preview-container {
    display: flex;
    align-items: center;
    gap: 12px;
 }
 .tool-drop-zone .preview-thumb {
    width: 70px;
    height: 70px;
    object-fit: cover;
    border-radius: 6px;
    border: 2px solid rgba(99, 179, 237, 0.5);
 }
 .tool-drop-zone .preview-info {
    flex: 1;
    min-width: 0;
 }
 .tool-drop-zone .preview-name {
    font-weight: 600;
    color: #63b3ed;
    white-space: nowrap;
    overflow: hidden;
    text-overflow: ellipsis;
 }
 .tool-drop-zone .preview-meta {
    font-size: 0.8rem;
    color: rgba(255, 255, 255, 0.5);
 }
 .tool-drop-zone .preview-clear {
    position: absolute;
    top: 8px;
    right: 8px;
    z-index: 20;
    opacity: 0.7;
 }
 .tool-drop-zone .preview-clear:hover {
    opacity: 1;
 }
 /* Result panels */
 .result-panel {
    background: rgba(0, 0, 0, 0.3);
    border-radius: 8px;
    border: 1px solid rgba(255, 255, 255, 0.1);
 }
 /* EXIF table styling */
 .exif-table {
    font-size: 0.85rem;
 }
 .exif-table th {
    background: rgba(0, 0, 0, 0.3);
    position: sticky;
    top: 0;
 }
 .exif-table td {
    vertical-align: middle;
 }
 .exif-input {
    background: rgba(0, 0, 0, 0.3) !important;
    border: 1px solid rgba(99, 179, 237, 0.3) !important;
    color: #63b3ed !important;
    font-family: monospace;
    font-size: 0.8rem;
    padding: 4px 8px;
 }
 .exif-input:focus {
    border-color: #63b3ed !important;
    box-shadow: 0 0 10px rgba(99, 179, 237, 0.2) !important;
 }
 /* Processing state */
 .processing .tool-drop-zone {
    pointer-events: none;
    opacity: 0.6;
 }
 .processing .btn {
    pointer-events: none;
 }
 /* Tool section visibility */
 .tool-section { display: none; }
 .tool-section.active { display: block; }
 /* Green→amber gradient (12.5% lighter) */
 .tool-tabs .btn-outline-primary {
    background-color: rgba(0, 0, 0, 0.25);
 }
 .tool-tabs .btn-outline-primary:nth-of-type(1) {
    color: #40d770;
    border-color: #40d770;
 }
 .tool-tabs .btn-outline-primary:nth-of-type(2) {
    color: #96da2c;
    border-color: #96da2c;
 }
 .tool-tabs .btn-outline-primary:nth-of-type(3) {
    color: #fdda64;
    border-color: #fdda64;
 }
 .tool-tabs .btn-outline-primary:nth-of-type(1):hover {
    background-color: rgba(64, 215, 112, 0.15);
 }
 .tool-tabs .btn-outline-primary:nth-of-type(2):hover {
    background-color: rgba(150, 218, 44, 0.15);
 }
 .tool-tabs .btn-outline-primary:nth-of-type(3):hover {
    background-color: rgba(253, 218, 100, 0.15);
 }
 .tool-tabs .btn-check:checked + .btn-outline-primary:nth-of-type(1) {
    background-color: #40d770;
    border-color: #40d770;
    color: #1a1a2e;
 }
 .tool-tabs .btn-check:checked + .btn-outline-primary:nth-of-type(2) {
    background-color: #96da2c;
    border-color: #96da2c;
    color: #1a1a2e;
 }
 .tool-tabs .btn-check:checked + .btn-outline-primary:nth-of-type(3) {
    background-color: #fdda64;
    border-color: #fdda64;
    color: #1a1a2e;
 }
 </style>
 <div class="row justify-content-center">
    <div class="col-lg-8">
        <div class="card">
            <div class="card-header">
                <h5 class="mb-0"><i class="bi bi-tools me-2"></i>Image Security Toolkit</h5>
            </div>
            <div class="card-body">
                <!-- Tool Selector Tabs -->
                <div class="btn-group tool-tabs w-100 mb-4" role="group">
                    <input type="radio" class="btn-check" name="tool_type" id="toolCapacity" value="capacity" checked>
                    <label class="btn btn-outline-primary" for="toolCapacity">
                        <i class="bi bi-rulers me-1"></i> Capacity
                    </label>
                    <input type="radio" class="btn-check" name="tool_type" id="toolExif" value="exif">
                    <label class="btn btn-outline-primary" for="toolExif">
                        <i class="bi bi-card-text me-1"></i> EXIF
                    </label>
                    <input type="radio" class="btn-check" name="tool_type" id="toolStrip" value="strip">
                    <label class="btn btn-outline-primary" for="toolStrip">
                        <i class="bi bi-eraser me-1"></i> Strip
                    </label>
                </div>
                <!-- ============================================================ -->
                <!-- CAPACITY CALCULATOR -->
                <!-- ============================================================ -->
                <div class="tool-section active" id="capacitySection">
                    <p class="text-muted small mb-3">Check how much data can be hidden in an image</p>
                    <div class="tool-drop-zone" id="capacityZone">
                        <input type="file" accept="image/*" id="capacityFile">
                        <div class="drop-label">
                            <i class="bi bi-image drop-icon d-block mb-2"></i>
                            <span class="text-muted">Drop image or click to browse</span>
                        </div>
                        <div class="preview-container">
                            <img class="preview-thumb" id="capacityThumb">
                            <div class="preview-info">
                                <div class="preview-name" id="capacityName">image.jpg</div>
                                <div class="preview-meta" id="capacityMeta">-- × -- · -- MB</div>
                            </div>
                        </div>
                        <button type="button" class="btn btn-sm btn-outline-secondary preview-clear d-none" id="capacityClear">
                            <i class="bi bi-x"></i>
                        </button>
                    </div>
                    <!-- Results -->
                    <div class="result-panel p-3 mt-3 d-none" id="capacityResult">
                        <div class="row text-center">
                            <div class="col-6 col-md-3 mb-3 mb-md-0">
                                <div class="text-muted small">Dimensions</div>
                                <div class="fw-bold" id="capDimensions">--</div>
                            </div>
                            <div class="col-6 col-md-3 mb-3 mb-md-0">
                                <div class="text-muted small">Megapixels</div>
                                <div class="fw-bold" id="capMegapixels">--</div>
                            </div>
                            <div class="col-6 col-md-3">
                                <div class="text-muted small">LSB Capacity</div>
                                <div class="fw-bold text-primary" id="capLsb">--</div>
                            </div>
                            <div class="col-6 col-md-3">
                                <div class="text-muted small">DCT Capacity</div>
                                <div class="fw-bold text-warning" id="capDct">--</div>
                            </div>
                        </div>
                    </div>
                </div>
                <!-- ============================================================ -->
                <!-- EXIF EDITOR -->
                <!-- ============================================================ -->
                <div class="tool-section" id="exifSection">
                    <p class="text-muted small mb-3">View, edit, or remove image metadata</p>
                    <div class="tool-drop-zone" id="exifZone">
                        <input type="file" accept="image/*" id="exifFile">
                        <div class="drop-label">
                            <i class="bi bi-card-image drop-icon d-block mb-2"></i>
                            <span class="text-muted">Drop image or click to browse</span>
                        </div>
                        <div class="preview-container">
                            <img class="preview-thumb" id="exifThumb">
                            <div class="preview-info">
                                <div class="preview-name" id="exifName">image.jpg</div>
                                <div class="preview-meta"><span id="exifFieldCount">0</span> metadata fields</div>
                                <div id="exifNotEditable" class="text-warning small d-none">
                                    <i class="bi bi-exclamation-triangle me-1"></i>Non-JPEG: clear only
                                </div>
                            </div>
                        </div>
                        <button type="button" class="btn btn-sm btn-outline-secondary preview-clear d-none" id="exifClear">
                            <i class="bi bi-x"></i>
                        </button>
                    </div>
                    <!-- EXIF Data Editor -->
                    <div id="exifEditor" class="d-none mt-3">
                        <div class="table-responsive result-panel" style="max-height: 250px; overflow-y: auto;">
                            <table class="table table-sm table-dark table-hover exif-table mb-0">
                                <thead>
                                    <tr>
                                        <th style="width: 35%">Field</th>
                                        <th>Value</th>
                                        <th style="width: 40px"></th>
                                    </tr>
                                </thead>
                                <tbody id="exifTable"></tbody>
                            </table>
                        </div>
                        <div id="exifEmpty" class="result-panel text-muted text-center py-4 d-none">
                            <i class="bi bi-inbox fs-4 d-block mb-2"></i>No metadata found
                        </div>
                        <!-- Action Buttons -->
                        <div class="d-flex gap-2 mt-3 pt-3 border-top border-secondary">
                            <button type="button" class="btn btn-outline-danger" id="exifClearAll">
                                <i class="bi bi-trash me-1"></i>Clear All
                            </button>
                            <div class="ms-auto d-flex gap-2">
                                <button type="button" class="btn btn-outline-secondary" id="exifDiscard">
                                    Discard
                                </button>
                                <button type="button" class="btn btn-primary" id="exifSave" disabled>
                                    <i class="bi bi-download me-1"></i>Save
                                </button>
                            </div>
                        </div>
                    </div>
                </div>
                <!-- ============================================================ -->
                <!-- STRIP METADATA -->
                <!-- ============================================================ -->
                <div class="tool-section" id="stripSection">
                    <p class="text-muted small mb-3">Remove all EXIF data and get a clean image</p>
                    <div class="tool-drop-zone" id="stripZone">
                        <input type="file" accept="image/*" id="stripFile">
                        <div class="drop-label">
                            <i class="bi bi-file-earmark-x drop-icon d-block mb-2"></i>
                            <span class="text-muted">Drop image or click to browse</span>
                        </div>
                        <div class="preview-container">
                            <img class="preview-thumb" id="stripThumb">
                            <div class="preview-info">
                                <div class="preview-name" id="stripName">image.jpg</div>
                                <div class="preview-meta" id="stripMeta">--</div>
                            </div>
                        </div>
                        <button type="button" class="btn btn-sm btn-outline-secondary preview-clear d-none" id="stripClearBtn">
                            <i class="bi bi-x"></i>
                        </button>
                    </div>
                    <!-- Format selector and action -->
                    <div id="stripOptions" class="d-none mt-3">
                        <div class="d-flex align-items-center gap-3">
                            <label class="form-label mb-0 small text-muted">Output:</label>
                            <select class="form-select form-select-sm" id="stripFormat" style="width: auto;">
                                <option value="PNG" selected>PNG (lossless)</option>
                                <option value="JPEG">JPEG</option>
                            </select>
                            <button type="button" class="btn btn-danger ms-auto" id="stripAction">
                                <i class="bi bi-eraser me-1"></i>Strip & Download
                            </button>
                        </div>
                    </div>
                </div>
            </div>
        </div>
    </div>
 </div>
 {% endblock %}
 {% block scripts %}
 <script>
 // ============================================================================
 // TAB SWITCHING
 // ============================================================================
 const toolRadios = document.querySelectorAll('input[name="tool_type"]');
 const toolSections = {
    capacity: document.getElementById('capacitySection'),
    exif: document.getElementById('exifSection'),
    strip: document.getElementById('stripSection')
 };
 function switchTool() {
    const selected = document.querySelector('input[name="tool_type"]:checked').value;
    Object.entries(toolSections).forEach(([key, section]) => {
        section.classList.toggle('active', key === selected);
    });
 }
 toolRadios.forEach(radio => radio.addEventListener('change', switchTool));
 // ============================================================================
 // SHARED - Drop zone helpers
 // ============================================================================
 function setupDropZone(zoneId, fileInputId, onFile) {
    const zone = document.getElementById(zoneId);
    const input = document.getElementById(fileInputId);
    if (!zone || !input) return;
    zone.addEventListener('dragover', e => { e.preventDefault(); zone.classList.add('drag-over'); });
    zone.addEventListener('dragleave', () => zone.classList.remove('drag-over'));
    zone.addEventListener('drop', e => {
        e.preventDefault();
        zone.classList.remove('drag-over');
        if (e.dataTransfer.files[0]) {
            input.files = e.dataTransfer.files;
            input.dispatchEvent(new Event('change'));
        }
    });
    input.addEventListener('change', function() {
        if (this.files[0]) onFile(this.files[0]);
    });
 }
 function showPreview(zoneId, file, thumbId, nameId, metaText, clearBtnId) {
    const zone = document.getElementById(zoneId);
    const thumb = document.getElementById(thumbId);
    const name = document.getElementById(nameId);
    const clearBtn = document.getElementById(clearBtnId);
    zone.classList.add('has-file');
    name.textContent = file.name;
    if (metaText) {
        const metaEl = name.nextElementSibling;
        if (metaEl) metaEl.textContent = metaText;
    }
    const reader = new FileReader();
    reader.onload = e => thumb.src = e.target.result;
    reader.readAsDataURL(file);
    clearBtn?.classList.remove('d-none');
 }
 function clearDropZone(zoneId, fileInputId, clearBtnId, extraCleanup) {
    const zone = document.getElementById(zoneId);
    const input = document.getElementById(fileInputId);
    const clearBtn = document.getElementById(clearBtnId);
    zone?.classList.remove('has-file');
    if (input) input.value = '';
    clearBtn?.classList.add('d-none');
    if (extraCleanup) extraCleanup();
 }
 function formatBytes(bytes) {
    if (bytes < 1024) return bytes + ' B';
    if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + ' KB';
    return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
 }
 // ============================================================================
 // CAPACITY CALCULATOR
 // ============================================================================
 setupDropZone('capacityZone', 'capacityFile', async (file) => {
    showPreview('capacityZone', file, 'capacityThumb', 'capacityName', formatBytes(file.size), 'capacityClear');
    const formData = new FormData();
    formData.append('image', file);
    try {
        const res = await fetch('/api/tools/capacity', { method: 'POST', body: formData });
        const data = await res.json();
        if (data.success) {
            document.getElementById('capacityMeta').textContent =
                `${data.width} × ${data.height} · ${formatBytes(file.size)}`;
            document.getElementById('capDimensions').textContent = `${data.width} × ${data.height}`;
            document.getElementById('capMegapixels').textContent = data.megapixels + ' MP';
            document.getElementById('capLsb').textContent = data.lsb.capacity_kb.toFixed(1) + ' KB';
            document.getElementById('capDct').textContent = data.dct.available
                ? data.dct.capacity_kb.toFixed(1) + ' KB'
                : 'N/A';
            document.getElementById('capacityResult').classList.remove('d-none');
        }
    } catch (err) {
        console.error(err);
    }
 });
 document.getElementById('capacityClear')?.addEventListener('click', () => {
    clearDropZone('capacityZone', 'capacityFile', 'capacityClear', () => {
        document.getElementById('capacityResult').classList.add('d-none');
    });
 });
 // ============================================================================
 // EXIF EDITOR
 // ============================================================================
 let exifOriginalData = {};
 let exifCurrentData = {};
 let exifEditable = false;
 let exifCurrentFile = null;
 setupDropZone('exifZone', 'exifFile', async (file) => {
    exifCurrentFile = file;
    showPreview('exifZone', file, 'exifThumb', 'exifName', '', 'exifClear');
    const formData = new FormData();
    formData.append('image', file);
    try {
        const res = await fetch('/api/tools/exif', { method: 'POST', body: formData });
        const data = await res.json();
        if (data.success) {
            exifOriginalData = JSON.parse(JSON.stringify(data.exif));
            exifCurrentData = JSON.parse(JSON.stringify(data.exif));
            exifEditable = data.editable;
            document.getElementById('exifFieldCount').textContent = data.field_count;
            document.getElementById('exifNotEditable').classList.toggle('d-none', data.editable);
            document.getElementById('exifEditor').classList.remove('d-none');
            renderExifTable();
            updateSaveButton();
        }
    } catch (err) {
        console.error(err);
    }
 });
 document.getElementById('exifClear')?.addEventListener('click', () => {
    clearDropZone('exifZone', 'exifFile', 'exifClear', () => {
        document.getElementById('exifEditor').classList.add('d-none');
        exifCurrentFile = null;
        exifOriginalData = {};
        exifCurrentData = {};
    });
 });
 function renderExifTable() {
    const tbody = document.getElementById('exifTable');
    const empty = document.getElementById('exifEmpty');
    const entries = Object.entries(exifCurrentData).sort((a, b) => a[0].localeCompare(b[0]));
    if (entries.length === 0) {
        tbody.innerHTML = '';
        empty.classList.remove('d-none');
        return;
    }
    empty.classList.add('d-none');
    tbody.innerHTML = entries.map(([key, value]) => {
        let displayVal = typeof value === 'object' ? JSON.stringify(value) : value;
        if (typeof displayVal === 'string' && displayVal.length > 50) {
            displayVal = displayVal.substring(0, 47) + '...';
        }
        const editableFields = ['Make', 'Model', 'Software', 'Artist', 'Copyright', 'ImageDescription', 'DateTime', 'DateTimeOriginal', 'DateTimeDigitized', 'UserComment', 'LensMake', 'LensModel'];
        const canEdit = exifEditable && editableFields.includes(key) && typeof value === 'string';
        return `
            <tr data-field="${key}">
                <td class="text-muted small">${key}</td>
                <td class="font-monospace small">
                    ${canEdit
                        ? `<input type="text" class="form-control form-control-sm exif-input"
                             value="${String(value).replace(/"/g, '&quot;')}" data-field="${key}">`
                        : `<span title="${String(displayVal)}">${displayVal}</span>`
                    }
                </td>
                <td>
                    ${canEdit
                        ? `<button class="btn btn-sm btn-outline-danger border-0 exif-delete" data-field="${key}" title="Remove">
                             <i class="bi bi-x"></i>
                           </button>`
                        : ''
                    }
                </td>
            </tr>
        `;
    }).join('');
    tbody.querySelectorAll('.exif-input').forEach(input => {
        input.addEventListener('input', function() {
            exifCurrentData[this.dataset.field] = this.value;
            updateSaveButton();
        });
    });
    tbody.querySelectorAll('.exif-delete').forEach(btn => {
        btn.addEventListener('click', function() {
            delete exifCurrentData[this.dataset.field];
            renderExifTable();
            updateSaveButton();
        });
    });
 }
 function updateSaveButton() {
    const changed = JSON.stringify(exifCurrentData) !== JSON.stringify(exifOriginalData);
    document.getElementById('exifSave').disabled = !changed;
 }
 document.getElementById('exifClearAll')?.addEventListener('click', async function() {
    if (!exifCurrentFile) return;
    if (!confirm('Remove all metadata from this image?')) return;
    const formData = new FormData();
    formData.append('image', exifCurrentFile);
    formData.append('format', 'PNG');
    const btn = this;
    btn.disabled = true;
    btn.innerHTML = '<span class="spinner-border spinner-border-sm me-1"></span>Clearing...';
    try {
        const res = await fetch('/api/tools/exif/clear', { method: 'POST', body: formData });
        if (res.ok) {
            const blob = await res.blob();
            const url = URL.createObjectURL(blob);
            const a = document.createElement('a');
            a.href = url;
            a.download = res.headers.get('Content-Disposition')?.split('filename=')[1]?.replace(/"/g, '') || 'clean.png';
            document.body.appendChild(a);
            a.click();
            document.body.removeChild(a);
            URL.revokeObjectURL(url);
            exifCurrentData = {};
            exifOriginalData = {};
            renderExifTable();
        } else {
            alert('Failed to clear metadata');
        }
    } catch (err) {
        console.error(err);
        alert('Failed to clear metadata: ' + err.message);
    } finally {
        btn.disabled = false;
        btn.innerHTML = '<i class="bi bi-trash me-1"></i>Clear All';
    }
 });
 document.getElementById('exifDiscard')?.addEventListener('click', function() {
    exifCurrentData = JSON.parse(JSON.stringify(exifOriginalData));
    renderExifTable();
    updateSaveButton();
 });
 document.getElementById('exifSave')?.addEventListener('click', async function() {
    if (!exifCurrentFile || !exifEditable) return;
    const updates = {};
    for (const [key, val] of Object.entries(exifCurrentData)) {
        if (exifOriginalData[key] !== val) updates[key] = val;
    }
    for (const key of Object.keys(exifOriginalData)) {
        if (!(key in exifCurrentData)) updates[key] = null;
    }
    if (Object.keys(updates).length === 0) return;
    const formData = new FormData();
    formData.append('image', exifCurrentFile);
    formData.append('updates', JSON.stringify(updates));
    const btn = this;
    const originalHtml = btn.innerHTML;
    btn.disabled = true;
    btn.innerHTML = '<span class="spinner-border spinner-border-sm me-1"></span>Saving...';
    try {
        const res = await fetch('/api/tools/exif/update', { method: 'POST', body: formData });
        if (res.ok) {
            const blob = await res.blob();
            const url = URL.createObjectURL(blob);
            const a = document.createElement('a');
            a.href = url;
            a.download = res.headers.get('Content-Disposition')?.split('filename=')[1]?.replace(/"/g, '') || 'updated.jpg';
            document.body.appendChild(a);
            a.click();
            document.body.removeChild(a);
            URL.revokeObjectURL(url);
            exifOriginalData = JSON.parse(JSON.stringify(exifCurrentData));
            updateSaveButton();
        } else {
            alert('Failed to save');
        }
    } catch (err) {
        console.error(err);
        alert('Failed to save changes: ' + err.message);
    } finally {
        btn.disabled = false;
        btn.innerHTML = originalHtml;
        updateSaveButton();
    }
 });
 // ============================================================================
 // STRIP METADATA
 // ============================================================================
 let stripCurrentFile = null;
 setupDropZone('stripZone', 'stripFile', (file) => {
    stripCurrentFile = file;
    showPreview('stripZone', file, 'stripThumb', 'stripName', formatBytes(file.size), 'stripClearBtn');
    document.getElementById('stripMeta').textContent = formatBytes(file.size);
    document.getElementById('stripOptions').classList.remove('d-none');
 });
 document.getElementById('stripClearBtn')?.addEventListener('click', () => {
    clearDropZone('stripZone', 'stripFile', 'stripClearBtn', () => {
        document.getElementById('stripOptions').classList.add('d-none');
        stripCurrentFile = null;
    });
 });
 document.getElementById('stripAction')?.addEventListener('click', async function() {
    if (!stripCurrentFile) return;
    const format = document.getElementById('stripFormat').value;
    const formData = new FormData();
    formData.append('image', stripCurrentFile);
    formData.append('format', format);
    const btn = this;
    btn.disabled = true;
    btn.innerHTML = '<span class="spinner-border spinner-border-sm me-1"></span>Processing...';
    try {
        const res = await fetch('/api/tools/exif/clear', { method: 'POST', body: formData });
        if (res.ok) {
            const blob = await res.blob();
            const url = URL.createObjectURL(blob);
            const a = document.createElement('a');
            a.href = url;
            a.download = res.headers.get('Content-Disposition')?.split('filename=')[1]?.replace(/"/g, '') || `clean.${format.toLowerCase()}`;
            document.body.appendChild(a);
            a.click();
            document.body.removeChild(a);
            URL.revokeObjectURL(url);
        } else {
            alert('Failed to strip metadata');
        }
    } catch (err) {
        console.error(err);
        alert('Failed to strip metadata: ' + err.message);
    } finally {
        btn.disabled = false;
        btn.innerHTML = '<i class="bi bi-eraser me-1"></i>Strip & Download';
    }
 });
 </script>
 {% endblock %}
--- a/instance/.secret_key
+++ b/instance/.secret_key
@@ -0,0 +1 @@
 6a7378172fc0ec37143720f09a4ca34e83ec2409893aa8cd79ace5b78a64276c
--- a/instance/stegasoo.db
+++ b/instance/stegasoo.db
--- a/minimal_flask_crash.py
+++ b/minimal_flask_crash.py
@@ -1,289 +0,0 @@
 #!/usr/bin/env python3
 """
 Minimal Flask app to isolate the crash.
 Run with: python minimal_flask_crash.py
 Then test with:
  curl -X POST -F "carrier=@xx_2.jpg" http://localhost:5001/test1
  curl -X POST -F "carrier=@xx_2.jpg" http://localhost:5001/test2
  curl -X POST -F "carrier=@xx_2.jpg" http://localhost:5001/test3
 """
 import io
 import gc
 import os
 import sys
 import tempfile
 # Minimal imports first
 from flask import Flask, request, jsonify
 from PIL import Image
 import numpy as np
 app = Flask(__name__)
 app.config['MAX_CONTENT_LENGTH'] = 50 * 1024 * 1024  # 50MB
 # Check for jpegio
 try:
    import jpegio as jio
    HAS_JPEGIO = True
    print("jpegio: available")
 except ImportError:
    HAS_JPEGIO = False
    print("jpegio: NOT available")
@app.route('/test1', methods=['POST'])
 def test1_pil_only():
    """Test 1: PIL only, no jpegio, no scipy"""
    carrier = request.files.get('carrier')
    if not carrier:
        return jsonify({'error': 'No carrier'}), 400
    data = carrier.read()
    print(f"[test1] Read {len(data)} bytes")
    img = Image.open(io.BytesIO(data))
    width, height = img.size
    fmt = img.format
    img.close()
    print(f"[test1] Image: {width}x{height} {fmt}")
    gc.collect()
    print("[test1] Returning response...")
    return jsonify({
        'test': 'pil_only',
        'width': width,
        'height': height,
        'format': fmt,
    })
@app.route('/test2', methods=['POST'])
 def test2_multiple_opens():
    """Test 2: Open image multiple times like compare_modes does"""
    carrier = request.files.get('carrier')
    if not carrier:
        return jsonify({'error': 'No carrier'}), 400
    data = carrier.read()
    print(f"[test2] Read {len(data)} bytes")
    # First open
    img1 = Image.open(io.BytesIO(data))
    width, height = img1.size
    img1.close()
    print(f"[test2] Open 1: {width}x{height}")
    # Second open
    img2 = Image.open(io.BytesIO(data))
    pixels = img2.size[0] * img2.size[1]
    img2.close()
    print(f"[test2] Open 2: {pixels} pixels")
    # Third open
    img3 = Image.open(io.BytesIO(data))
    blocks = (img3.size[0] // 8) * (img3.size[1] // 8)
    img3.close()
    print(f"[test2] Open 3: {blocks} blocks")
    gc.collect()
    print("[test2] Returning response...")
    return jsonify({
        'test': 'multiple_opens',
        'width': width,
        'height': height,
        'pixels': pixels,
        'blocks': blocks,
    })
@app.route('/test3', methods=['POST'])
 def test3_with_jpegio():
    """Test 3: Include jpegio operations"""
    if not HAS_JPEGIO:
        return jsonify({'error': 'jpegio not available'}), 501
    carrier = request.files.get('carrier')
    if not carrier:
        return jsonify({'error': 'No carrier'}), 400
    data = carrier.read()
    print(f"[test3] Read {len(data)} bytes")
    # Check if JPEG
    img = Image.open(io.BytesIO(data))
    is_jpeg = img.format == 'JPEG'
    width, height = img.size
    img.close()
    print(f"[test3] Image: {width}x{height}, JPEG: {is_jpeg}")
    if not is_jpeg:
        return jsonify({'error': 'Not a JPEG'}), 400
    # Write to temp file
    fd, temp_path = tempfile.mkstemp(suffix='.jpg')
    os.write(fd, data)
    os.close(fd)
    print(f"[test3] Temp file: {temp_path}")
    try:
        # Read with jpegio
        jpeg = jio.read(temp_path)
        print(f"[test3] jpegio.read() OK")
        coef = jpeg.coef_arrays[0]
        coef_shape = coef.shape
        print(f"[test3] Coef shape: {coef_shape}")
        # Count positions like the real code does
        positions = 0
        h, w = coef.shape
        for row in range(h):
            for col in range(w):
                if (row % 8 == 0) and (col % 8 == 0):
                    continue
                if abs(coef[row, col]) >= 2:
                    positions += 1
        print(f"[test3] Usable positions: {positions}")
        # Cleanup
        del coef
        del jpeg
        print(f"[test3] Deleted jpegio objects")
    finally:
        os.unlink(temp_path)
        print(f"[test3] Removed temp file")
    gc.collect()
    print("[test3] Returning response...")
    return jsonify({
        'test': 'with_jpegio',
        'width': width,
        'height': height,
        'coef_shape': list(coef_shape),
        'positions': positions,
    })
@app.route('/test4', methods=['POST'])
 def test4_numpy_array_from_pil():
    """Test 4: Create numpy array from PIL image (like DCT does)"""
    carrier = request.files.get('carrier')
    if not carrier:
        return jsonify({'error': 'No carrier'}), 400
    data = carrier.read()
    print(f"[test4] Read {len(data)} bytes")
    img = Image.open(io.BytesIO(data))
    width, height = img.size
    print(f"[test4] Image: {width}x{height}")
    # Convert to grayscale and numpy array
    gray = img.convert('L')
    arr = np.array(gray, dtype=np.float64, copy=True)
    print(f"[test4] Array: {arr.shape} {arr.dtype}")
    # Close PIL images
    gray.close()
    img.close()
    print(f"[test4] PIL closed")
    # Do some numpy operations
    mean_val = float(np.mean(arr))
    std_val = float(np.std(arr))
    print(f"[test4] Stats: mean={mean_val:.2f}, std={std_val:.2f}")
    # Clear array
    del arr
    gc.collect()
    print("[test4] Returning response...")
    return jsonify({
        'test': 'numpy_from_pil',
        'width': width,
        'height': height,
        'mean': mean_val,
        'std': std_val,
    })
@app.route('/test5', methods=['POST'])
 def test5_file_read_keep_reference():
    """Test 5: Keep reference to file data in request scope"""
    carrier = request.files.get('carrier')
    if not carrier:
        return jsonify({'error': 'No carrier'}), 400
    # Don't read into local variable - read directly each time
    # This mimics potential issues with Flask's file handling
    print(f"[test5] File object: {carrier}")
    # Read once
    carrier.seek(0)
    data1 = carrier.read()
    print(f"[test5] First read: {len(data1)} bytes")
    img = Image.open(io.BytesIO(data1))
    width, height = img.size
    img.close()
    # Try to read again (should be empty or need seek)
    data2 = carrier.read()
    print(f"[test5] Second read (no seek): {len(data2)} bytes")
    carrier.seek(0)
    data3 = carrier.read()
    print(f"[test5] Third read (after seek): {len(data3)} bytes")
    gc.collect()
    print("[test5] Returning response...")
    return jsonify({
        'test': 'file_handling',
        'width': width,
        'height': height,
        'read1': len(data1),
        'read2': len(data2),
        'read3': len(data3),
    })
@app.after_request
 def after_request(response):
    """Log after each request"""
    print(f"[after_request] Response status: {response.status}")
    return response
@app.teardown_request
 def teardown_request(exception):
    """Log during teardown"""
    if exception:
        print(f"[teardown] Exception: {exception}")
    else:
        print("[teardown] Clean teardown")
    gc.collect()
 if __name__ == '__main__':
    print("\n" + "=" * 60)
    print("MINIMAL FLASK CRASH TEST")
    print("=" * 60)
    print("\nTest endpoints:")
    print("  /test1 - PIL only")
    print("  /test2 - Multiple PIL opens")
    print("  /test3 - With jpegio")
    print("  /test4 - NumPy array from PIL")
    print("  /test5 - File handling test")
    print("\nUsage:")
    print('  curl -X POST -F "carrier=@xx_2.jpg" http://localhost:5001/test1')
    print("=" * 60 + "\n")
    app.run(host='0.0.0.0', port=5001, debug=False, threaded=False)
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 [project]
 name = "stegasoo"
-version = "4.0.1"
+version = "4.1.2"
 description = "Secure steganography with hybrid photo + passphrase + PIN authentication"
 readme = "README.md"
 license = "MIT"
@@ -48,10 +48,13 @@ dct = [
    "numpy>=2.0.0",
    "scipy>=1.10.0",
    "jpegio>=0.2.0",
    "reedsolo>=1.7.0",
 ]
 cli = [
    "click>=8.0.0",
-    "qrcode>=7.30"
+    "qrcode>=7.30",
    "piexif>=1.1.0",
    "rich>=13.0.0",
 ]
 compression = [
    "lz4>=4.0.0",
@@ -61,10 +64,12 @@ web = [
    "gunicorn>=21.0.0",
    "qrcode>=7.3.0",
    "pyzbar>=0.1.9",
    "piexif>=1.1.0",
    # Include DCT support for web UI
    "numpy>=2.0.0",
    "scipy>=1.10.0",
    "jpegio>=0.2.0",
    "reedsolo>=1.7.0",
 ]
 api = [
    "fastapi>=0.100.0",
@@ -76,6 +81,7 @@ api = [
    "numpy>=2.0.0",
    "scipy>=1.10.0",
    "jpegio>=0.2.0",
    "reedsolo>=1.7.0",
 ]
 all = [
    "stegasoo[cli,web,api,dct,compression]",
--- a/quick_web.sh
+++ b/quick_web.sh
@@ -1,3 +0,0 @@
 #!/bin/bash
 cd ./frontends/web/
 python app.py
--- a/rbld_containers.sh
+++ b/rbld_containers.sh
@@ -1,4 +0,0 @@
 #!/bin/bash
 sudo docker-compose down
 sudo docker-compose build
 sudo docker-compose up -d
--- a/rpi/BUILD_IMAGE.md
+++ b/rpi/BUILD_IMAGE.md
@@ -0,0 +1,133 @@
 # Stegasoo Pi Image Build Workflow
 Quick reference for building a distributable SD card image.
 ## Step 1: Flash Fresh Raspbian
 Use rpi-imager with these settings:
 - **OS**: Raspberry Pi OS Lite (64-bit)
 - **Hostname**: `stegasoo`
 - **Enable SSH**: Yes (password auth)
 - **Username**: `admin`
 - **Password**: `stegasoo`
 - **WiFi**: Configure for your network (sanitize script removes it later)
 ## Step 2: Boot & SSH In
 ```bash
 # Wait for Pi to boot (~60 seconds), then:
 ssh admin@stegasoo.local
 # or use IP from router DHCP list
 ```
 ## Step 3: Pre-Setup
 ```bash
 # Take ownership of /opt (for pyenv, jpegio builds)
 sudo chown admin:admin /opt
 # Install git (not included in Lite image)
 sudo apt-get update && sudo apt-get install -y git
 ```
 ## Step 4: Clone & Run Setup
 ```bash
 cd /opt
 git clone -b 4.1 https://github.com/adlee-was-taken/stegasoo.git stegasoo
 cd stegasoo
 ./rpi/setup.sh
 ```
 This takes ~15-20 minutes and installs:
 - Python 3.12 via pyenv
 - jpegio (patched for ARM)
 - Stegasoo with web UI
 - Systemd service
 ## Step 5: Test It Works
 ```bash
 sudo systemctl start stegasoo
 curl -k https://localhost:5000
 # Should return HTML
 ```
 ## Step 6: Sanitize for Distribution
 ```bash
 # Full sanitize (for final image - removes WiFi, shuts down)
 sudo /opt/stegasoo/rpi/sanitize-for-image.sh
 # Or soft reset (for testing - keeps WiFi, reboots)
 sudo /opt/stegasoo/rpi/sanitize-for-image.sh --soft
 ```
 This removes:
 - WiFi credentials (unless `--soft`)
 - SSH host keys (regenerate on boot)
 - SSH authorized keys
 - Bash history
 - Stegasoo auth database
 - Logs and temp files
 The script validates all cleanup steps before finishing.
 ## Step 7: Copy the Image
 Remove SD card, insert into your Linux machine:
 ```bash
 # Find the SD card device (CAREFUL!)
 lsblk
 # Copy (replace sdX with actual device, e.g., sda)
 sudo dd if=/dev/sdX of=stegasoo-rpi-$(date +%Y%m%d).img bs=4M status=progress
 ```
 ## Step 8: Shrink & Compress
 ```bash
 # Optional: Shrink image (saves space)
 wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
 chmod +x pishrink.sh
 sudo ./pishrink.sh stegasoo-rpi-*.img
 # Compress (zstd is faster than xz with similar ratio)
 zstd -19 -T0 stegasoo-rpi-*.img
 ```
 ## Step 9: Distribute
 Upload `.img.zst` to GitHub Releases.
 Users can flash with:
 ```bash
 # Option 1: rpi-imager CLI (supports .zst.zip directly)
 sudo rpi-imager --cli --disable-verify stegasoo-rpi-*.img.zst.zip /dev/sdX
 # Option 2: flash-image.sh (auto-detects SD card, shows progress)
 sudo ./rpi/flash-image.sh stegasoo-rpi-*.img.zst.zip
 # Option 3: Manual dd
 zstdcat stegasoo-rpi-*.img.zst | sudo dd of=/dev/sdX bs=4M status=progress
 ```
 ---
 ## Quick Command Summary
 ```bash
 # On Pi (after SSH):
 sudo chown admin:admin /opt
 sudo apt-get update && sudo apt-get install -y git
 cd /opt && git clone -b 4.1 https://github.com/adlee-was-taken/stegasoo.git stegasoo
 cd stegasoo && ./rpi/setup.sh
 sudo systemctl start stegasoo
 curl -k https://localhost:5000
 sudo /opt/stegasoo/rpi/sanitize-for-image.sh
 # On your machine:
 sudo dd if=/dev/sdX of=stegasoo-rpi-$(date +%Y%m%d).img bs=4M status=progress
 zstd -19 -T0 stegasoo-rpi-*.img
 ```
--- a/rpi/README.md
+++ b/rpi/README.md
@@ -0,0 +1,209 @@
 # Stegasoo Raspberry Pi
 Scripts and resources for deploying Stegasoo on Raspberry Pi.
 ## Quick Install
 On a fresh Raspberry Pi OS Lite (64-bit) installation:
 ```bash
 # Pre-setup (git not included in Lite image)
 sudo chown $USER:$USER /opt
 sudo apt-get update && sudo apt-get install -y git
 # Clone and run setup
 cd /opt
 git clone -b 4.1 https://github.com/adlee-was-taken/stegasoo.git stegasoo
 cd stegasoo
 ./rpi/setup.sh
 ```
 ## What the Setup Script Does
 1. **Installs system dependencies** - build tools, libraries
 2. **Installs Python 3.12** - via pyenv (Pi OS ships with 3.13 which is incompatible)
 3. **Builds jpegio for ARM** - patches x86-specific flags
 4. **Installs Stegasoo** - with web UI and all dependencies
 5. **Creates systemd service** - auto-starts on boot
 6. **Enables the service** - ready to start
 ## Requirements
 - Raspberry Pi 4 or 5
 - Raspberry Pi OS Lite (64-bit) - Bookworm or later
 - 4GB+ RAM recommended (2GB minimum)
 - ~2GB free disk space
 - Internet connection
 ### Performance
 On a Pi 4 at 2GHz with USB 3.0 NVMe, expect ~60 seconds to encode/decode a 10MB JPEG with full encryption (passphrase + PIN + reference photo).
 ## Pre-built Image Defaults
 If using a pre-built image from GitHub Releases:
 - **Default login**: `admin` / `stegasoo`
 - **Hostname**: `stegasoo.local`
 - **First boot**: A setup wizard runs on first SSH login
 > **Security note**: Change the default password after setup with `passwd`
 ## After Installation
 ### Start the Service
 ```bash
 sudo systemctl start stegasoo
 ```
 ### Check Status
 ```bash
 sudo systemctl status stegasoo
 ```
 ### View Logs
 ```bash
 journalctl -u stegasoo -f
 ```
 ### Access Web UI
 Open in browser: `http://<pi-ip>:5000`
 On first access, you'll create an admin account.
 ## Configuration
 Edit the systemd service to change settings:
 ```bash
 sudo systemctl edit stegasoo
 ```
 Add overrides:
 ```ini
 [Service]
 Environment="STEGASOO_AUTH_ENABLED=true"
 Environment="STEGASOO_HTTPS_ENABLED=true"
 Environment="STEGASOO_HOSTNAME=stegasoo.local"
 ```
 Then reload:
 ```bash
 sudo systemctl daemon-reload
 sudo systemctl restart stegasoo
 ```
 ## Uninstall
 ```bash
 sudo systemctl stop stegasoo
 sudo systemctl disable stegasoo
 sudo rm /etc/systemd/system/stegasoo.service
 rm -rf /opt/stegasoo
 ```
 ## Pre-built Images
 Check [GitHub Releases](https://github.com/adlee-was-taken/stegasoo/releases) for pre-built SD card images.
 ---
 ## Building Your Own Image
 To create a distributable SD card image:
 ### 1. Flash Fresh Raspberry Pi OS
 Use rpi-imager to flash Raspberry Pi OS (64-bit) to an SD card.
 In advanced settings, set:
 - Hostname: `stegasoo`
 - Enable SSH (password auth for initial setup)
 - Username/password (temporary, will work for any user)
 - Skip WiFi for distributable image
 ### 2. Boot and Run Setup
 ```bash
 # SSH into the Pi
 ssh admin@stegasoo.local
 # Pre-setup
 sudo chown admin:admin /opt
 sudo apt-get update && sudo apt-get install -y git
 # Clone and run setup
 cd /opt
 git clone -b 4.1 https://github.com/adlee-was-taken/stegasoo.git stegasoo
 cd stegasoo
 ./rpi/setup.sh
 ```
 ### 3. Test It Works
 ```bash
 sudo systemctl start stegasoo
 curl -k https://localhost:5000  # Should return HTML
 ```
 ### 4. Sanitize for Distribution
 ```bash
 # Full sanitize (removes WiFi, shuts down for imaging)
 sudo /opt/stegasoo/rpi/sanitize-for-image.sh
 # Or soft reset (keeps WiFi for testing, reboots)
 sudo /opt/stegasoo/rpi/sanitize-for-image.sh --soft
 ```
 This removes:
 - WiFi credentials (unless `--soft`)
 - SSH host keys (regenerate on boot)
 - SSH authorized keys
 - Bash history
 - Stegasoo auth database (users create their own admin)
 - Logs and temp files
 The script validates cleanup and reports any issues.
 ### 5. Create the Image
 After Pi shuts down, remove SD card and on another Linux machine:
 ```bash
 # Find SD card device (BE CAREFUL - wrong device = data loss!)
 lsblk
 # Copy (replace sdX with your SD card)
 sudo dd if=/dev/sdX of=stegasoo-rpi-$(date +%Y%m%d).img bs=4M status=progress
 # Shrink the image (optional but recommended)
 wget https://raw.githubusercontent.com/Drewsif/PiShrink/master/pishrink.sh
 chmod +x pishrink.sh
 sudo ./pishrink.sh stegasoo-rpi-*.img
 # Compress (zstd is faster than xz with similar compression)
 zstd -19 -T0 stegasoo-rpi-*.img
 ```
 ### 6. Distribute
 Upload the `.img.zst` file to GitHub Releases.
 Users flash with:
 ```bash
 # Option 1: rpi-imager CLI (supports .zst.zip directly)
 sudo rpi-imager --cli --disable-verify stegasoo-rpi-*.img.zst.zip /dev/sdX
 # Option 2: flash-image.sh (auto-detects SD card, shows progress)
 sudo ./rpi/flash-image.sh stegasoo-rpi-*.img.zst.zip
 # Option 3: Manual dd
 zstdcat stegasoo-rpi-*.img.zst | sudo dd of=/dev/sdX bs=4M status=progress
 ```
--- a/rpi/first-boot-wizard.sh
+++ b/rpi/first-boot-wizard.sh
@@ -0,0 +1,428 @@
 #!/bin/bash
 #
 # Stegasoo First Boot Wizard
 # Runs on first SSH login to configure the pre-installed Stegasoo image
 #
 # This script is triggered by /etc/profile.d/stegasoo-wizard.sh
 # After completion, it removes itself to prevent re-running
 #
 # Uses gum (Charm.sh) for beautiful TUI - install with:
 #   sudo apt install gum  OR  go install github.com/charmbracelet/gum@latest
 #
 # Configuration
 INSTALL_DIR="/opt/stegasoo"
 FLAG_FILE="/etc/stegasoo-first-boot"
 PROFILE_HOOK="/etc/profile.d/stegasoo-wizard.sh"
 # Check if this is first boot
 if [ ! -f "$FLAG_FILE" ]; then
  exit 0
 fi
 # Check for gum, fall back to basic prompts if not available
 if ! command -v gum &>/dev/null; then
  echo "Error: gum not found. Install with: sudo apt install gum"
  exit 1
 fi
 # Gum styling - terminal green buttons with bold dark text
 export GUM_CONFIRM_SELECTED_BACKGROUND="46"
 export GUM_CONFIRM_SELECTED_FOREGROUND="232"
 export GUM_CONFIRM_SELECTED_BOLD="true"
 export GUM_CONFIRM_UNSELECTED_BACKGROUND="238"
 export GUM_CONFIRM_UNSELECTED_FOREGROUND="255"
 clear
 # =============================================================================
 # Welcome
 # =============================================================================
 echo ""
 echo -e "\033[38;5;93m══════════════\033[38;5;99m══════════════\033[38;5;105m══════════════\033[38;5;117m══════════════\033[0m"
 echo -e "\033[0;90m · .  · .  *  · .  *  · .  *  · .  *  · .  *  · .  ·\033[0m"
 echo -e "\033[38;5;220m    ___  _____  ___    ___    _    ___    ___    ___\033[0m"
 echo -e "\033[38;5;220m   / __||_   _|| __|  / __|  /_\\  / __|  / _ \\  / _ \\\\\033[0m"
 echo -e "\033[38;5;220m   \\__ \\  | |  | _|  | (_ | / _ \\ \\__ \\ | (_) || (_) |\033[0m"
 echo -e "\033[38;5;220m   |___/  |_|  |___|  \\___//_/ \\_\\|___/  \\___/  \\___/\033[0m"
 echo -e "\033[0;90m · .  · .  *  · .  *  · .  *  · .  *  · .  *  · .  ·\033[0m"
 echo -e "\033[38;5;93m══════════════\033[38;5;99m══════════════\033[38;5;105m══════════════\033[38;5;117m══════════════\033[0m"
 echo -e "\033[1;37m                    First Boot Wizard\033[0m"
 echo -e "\033[38;5;93m══════════════\033[38;5;99m══════════════\033[38;5;105m══════════════\033[38;5;117m══════════════\033[0m"
 echo ""
 gum style --foreground 245 "This wizard will help you configure your Stegasoo server."
 gum style --foreground 245 "You can reconfigure later by editing /etc/systemd/system/stegasoo.service"
 echo ""
 gum confirm "Ready to begin setup?" || exit 0
 # =============================================================================
 # Configuration Variables
 # =============================================================================
 ENABLE_HTTPS="false"
 USE_PORT_443="false"
 CHANNEL_KEY=""
 # =============================================================================
 # Step 1: HTTPS Configuration
 # =============================================================================
 clear
 gum style \
  --foreground 212 --bold \
  "Step 1 of 4: HTTPS Configuration"
 echo ""
 gum style --foreground 245 "\
 HTTPS encrypts all traffic between your browser and this server
 using a self-signed certificate.
 NOTE: Your browser will show a security warning because the
 certificate is self-signed. This is normal for home networks."
 echo ""
 if gum confirm "Enable HTTPS?" --default=true; then
  ENABLE_HTTPS="true"
  gum style --foreground 82 "✓ HTTPS will be enabled"
 else
  gum style --foreground 214 "→ Using HTTP (unencrypted)"
 fi
 sleep 0.5
 # =============================================================================
 # Step 2: Port Configuration (only if HTTPS)
 # =============================================================================
 if [ "$ENABLE_HTTPS" = "true" ]; then
  clear
  gum style \
    --foreground 212 --bold \
    "Step 2 of 4: Port Configuration"
  echo ""
  gum style --foreground 245 "\
 The standard HTTPS port is 443, which means you can access
 Stegasoo without specifying a port in the URL.
  Port 443:  https://stegasoo.local
  Port 5000: https://stegasoo.local:5000
 NOTE: Port 443 requires an iptables redirect rule."
  echo ""
  if gum confirm "Use standard port 443?" --default=true; then
    USE_PORT_443="true"
    gum style --foreground 82 "✓ Port 443 will be configured"
  else
    gum style --foreground 214 "→ Using port 5000"
  fi
  sleep 0.5
 fi
 # =============================================================================
 # Step 3: Channel Key Configuration
 # =============================================================================
 clear
 gum style \
  --foreground 212 --bold \
  "Step 3 of 4: Channel Key Configuration"
 echo ""
 gum style --foreground 245 "\
 A channel key creates a private encoding channel.
  WITHOUT a key: Anyone with Stegasoo can decode your images
  WITH a key:    Only people with YOUR key can decode
 This is useful if you want to share encoded images only with
 specific people (family, team, etc)."
 echo ""
 if gum confirm "Generate a private channel key?" --default=false; then
  echo ""
  # Generate key to temp file (gum spin doesn't capture stdout well)
  KEY_FILE=$(mktemp)
  ERR_FILE=$(mktemp)
  VENV_PYTHON="$INSTALL_DIR/venv/bin/python"
  gum spin --spinner dot --title "Generating channel key..." -- \
    bash -c "'$VENV_PYTHON' -c 'from stegasoo.channel import generate_channel_key; print(generate_channel_key())' > '$KEY_FILE' 2>'$ERR_FILE'"
  CHANNEL_KEY=$(cat "$KEY_FILE" 2>/dev/null | head -1)
  KEY_ERROR=$(cat "$ERR_FILE" 2>/dev/null)
  rm -f "$KEY_FILE" "$ERR_FILE"
  if [ -n "$CHANNEL_KEY" ] && [[ "$CHANNEL_KEY" =~ ^[A-Za-z0-9] ]]; then
    echo ""
    gum style --foreground 82 "✓ Channel key generated!"
    echo ""
    gum style \
      --border rounded \
      --border-foreground 226 \
      --padding "1 2" \
      --foreground 226 --bold \
      "$CHANNEL_KEY"
    echo ""
    gum style --foreground 196 --bold \
      "*** IMPORTANT: Write down or copy this key NOW! ***"
    gum style --foreground 196 \
      "You'll need to share it with anyone who should decode" \
      "your images. This key won't be shown again."
    echo ""
    gum confirm "I've saved the key" --default=true --affirmative="Continue" --negative=""
  else
    gum style --foreground 196 "Failed to generate key. Using public mode."
    if [ -n "$KEY_ERROR" ]; then
      echo ""
      gum style --foreground 245 "Error details:"
      echo "$KEY_ERROR"
    fi
    CHANNEL_KEY=""
    echo ""
    gum confirm "Continue" --default=true --affirmative="OK" --negative=""
  fi
 else
  gum style --foreground 214 "→ Using public mode"
  sleep 0.5
 fi
 # =============================================================================
 # Step 4: Overclock Configuration
 # =============================================================================
 ENABLE_OVERCLOCK="false"
 NEEDS_RESTART="false"
 # Detect Pi model
 PI_MODEL=$(cat /proc/device-tree/model 2>/dev/null | tr -d '\0')
 if [[ "$PI_MODEL" == *"Raspberry Pi 4"* ]] || [[ "$PI_MODEL" == *"Raspberry Pi 5"* ]]; then
  clear
  gum style \
    --foreground 212 --bold \
    "Step 4 of 4: Performance Tuning"
  echo ""
  gum style --foreground 245 "\
 Detected: $PI_MODEL
 Overclocking can improve DCT encode/decode performance.
 This is ONLY recommended if you have active cooling:
  • Heatsink + Fan
  • Active cooler case
 Without cooling, the Pi may throttle or become unstable."
  echo ""
  if gum confirm "Do you have active cooling (heatsink + fan)?" --default=false; then
    echo ""
    gum style --foreground 245 "\
 Recommended overclock settings:
  • Pi 4: 2.0 GHz (stock 1.5 GHz) - ~33% faster
  • Pi 5: 2.8 GHz (stock 2.4 GHz) - ~17% faster"
    echo ""
    if gum confirm "Enable overclock?" --default=true; then
      ENABLE_OVERCLOCK="true"
      NEEDS_RESTART="true"
      gum style --foreground 82 "✓ Overclock will be enabled (restart required)"
    else
      gum style --foreground 214 "→ Running at stock speed"
    fi
  else
    gum style --foreground 214 "→ Skipping overclock (no active cooling)"
  fi
  sleep 0.5
 else
  # Not a Pi 4/5, skip overclock
  :
 fi
 # =============================================================================
 # Apply Configuration
 # =============================================================================
 clear
 gum style \
  --foreground 212 --bold \
  "Applying Configuration..."
 echo ""
 # Find the stegasoo user (whoever owns the install dir)
 STEGASOO_USER=$(stat -c '%U' "$INSTALL_DIR" 2>/dev/null || echo "pi")
 gum spin --spinner dot --title "Updating systemd service..." -- bash -c "
 sudo tee /etc/systemd/system/stegasoo.service >/dev/null <<EOF
 [Unit]
 Description=Stegasoo Web UI
 After=network.target
 [Service]
 Type=simple
 User=$STEGASOO_USER
 WorkingDirectory=$INSTALL_DIR/frontends/web
 Environment=\"PATH=$INSTALL_DIR/venv/bin:/usr/bin\"
 Environment=\"STEGASOO_AUTH_ENABLED=true\"
 Environment=\"STEGASOO_HTTPS_ENABLED=$ENABLE_HTTPS\"
 Environment=\"STEGASOO_PORT=5000\"
 Environment=\"STEGASOO_CHANNEL_KEY=$CHANNEL_KEY\"
 ExecStart=$INSTALL_DIR/venv/bin/python app.py
 Restart=on-failure
 RestartSec=5
 [Install]
 WantedBy=multi-user.target
 EOF
 "
 gum style --foreground 82 "✓ Service configured"
 # Setup port 443 if requested
 if [ "$USE_PORT_443" = "true" ]; then
  gum spin --spinner dot --title "Setting up port 443 redirect..." -- bash -c "
        if ! command -v iptables &>/dev/null; then
            sudo apt-get install -y iptables >/dev/null 2>&1
        fi
        if ! sudo iptables -t nat -C PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 5000 2>/dev/null; then
            sudo iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 5000
        fi
        sudo sh -c 'iptables-save > /etc/iptables.rules'
        sudo tee /etc/systemd/system/iptables-restore.service >/dev/null <<EOF
 [Unit]
 Description=Restore iptables rules
 Before=network-pre.target
 [Service]
 Type=oneshot
 ExecStart=/sbin/iptables-restore /etc/iptables.rules
 [Install]
 WantedBy=multi-user.target
 EOF
        sudo systemctl enable iptables-restore.service >/dev/null 2>&1
    "
  gum style --foreground 82 "✓ Port 443 redirect configured"
 fi
 gum spin --spinner dot --title "Reloading systemd..." -- sudo systemctl daemon-reload
 gum style --foreground 82 "✓ Systemd reloaded"
 # Apply overclock if requested
 if [ "$ENABLE_OVERCLOCK" = "true" ]; then
  gum spin --spinner dot --title "Configuring overclock..." -- bash -c "
    CONFIG_FILE='/boot/firmware/config.txt'
    # Fallback for older Pi OS
    if [ ! -f \"\$CONFIG_FILE\" ]; then
      CONFIG_FILE='/boot/config.txt'
    fi
    # Check if overclock already configured
    if ! grep -q '^over_voltage=' \"\$CONFIG_FILE\" 2>/dev/null; then
      # Detect Pi model for appropriate settings
      PI_MODEL=\$(cat /proc/device-tree/model 2>/dev/null | tr -d '\0')
      echo '' | sudo tee -a \"\$CONFIG_FILE\" >/dev/null
      echo '# Overclock (configured by Stegasoo wizard)' | sudo tee -a \"\$CONFIG_FILE\" >/dev/null
      if [[ \"\$PI_MODEL\" == *'Raspberry Pi 5'* ]]; then
        # Pi 5 overclock
        echo 'over_voltage=4' | sudo tee -a \"\$CONFIG_FILE\" >/dev/null
        echo 'arm_freq=2800' | sudo tee -a \"\$CONFIG_FILE\" >/dev/null
      else
        # Pi 4 overclock
        echo 'over_voltage=6' | sudo tee -a \"\$CONFIG_FILE\" >/dev/null
        echo 'arm_freq=2000' | sudo tee -a \"\$CONFIG_FILE\" >/dev/null
        echo 'gpu_freq=700' | sudo tee -a \"\$CONFIG_FILE\" >/dev/null
      fi
    fi
  "
  gum style --foreground 82 "✓ Overclock configured"
 fi
 gum spin --spinner dot --title "Starting Stegasoo..." -- bash -c "sudo systemctl restart stegasoo && sleep 2"
 if systemctl is-active --quiet stegasoo; then
  gum style --foreground 82 "✓ Stegasoo started successfully"
 else
  gum style --foreground 196 "✗ Failed to start (check: journalctl -u stegasoo)"
 fi
 gum spin --spinner dot --title "Cleaning up wizard..." -- bash -c "
    sudo rm -f '$FLAG_FILE'
    sudo rm -f '$PROFILE_HOOK'
 "
 gum style --foreground 82 "✓ Wizard complete"
 sleep 1
 # =============================================================================
 # Final Summary
 # =============================================================================
 clear
 PI_IP=$(hostname -I | awk '{print $1}')
 HOSTNAME=$(hostname)
 # Build the access URL
 if [ "$ENABLE_HTTPS" = "true" ]; then
  if [ "$USE_PORT_443" = "true" ]; then
    ACCESS_URL="https://$PI_IP/setup"
    ACCESS_URL_LOCAL="https://$HOSTNAME.local/setup"
  else
    ACCESS_URL="https://$PI_IP:5000/setup"
    ACCESS_URL_LOCAL="https://$HOSTNAME.local:5000/setup"
  fi
 else
  ACCESS_URL="http://$PI_IP:5000/setup"
  ACCESS_URL_LOCAL="http://$HOSTNAME.local:5000/setup"
 fi
 echo ""
 echo ""
 echo -e "\033[38;5;93m══════════════\033[38;5;99m══════════════\033[38;5;105m══════════════\033[38;5;117m══════════════\033[0m"
 echo -e "\033[0;90m · .  · .  *  · .  *  · .  *  · .  *  · .  *  · .  ·\033[0m"
 echo -e "\033[38;5;220m    ___  _____  ___    ___    _    ___    ___    ___\033[0m"
 echo -e "\033[38;5;220m   / __||_   _|| __|  / __|  /_\\  / __|  / _ \\  / _ \\\\\033[0m"
 echo -e "\033[38;5;220m   \\__ \\  | |  | _|  | (_ | / _ \\ \\__ \\ | (_) || (_) |\033[0m"
 echo -e "\033[38;5;220m   |___/  |_|  |___|  \\___//_/ \\_\\|___/  \\___/  \\___/\033[0m"
 echo -e "\033[0;90m · .  · .  *  · .  *  · .  *  · .  *  · .  *  · .  ·\033[0m"
 echo -e "\033[38;5;93m══════════════\033[38;5;99m══════════════\033[38;5;105m══════════════\033[38;5;117m══════════════\033[0m"
 echo -e "\033[1;32m                      Setup Complete!\033[0m"
 echo -e "\033[38;5;93m══════════════\033[38;5;99m══════════════\033[38;5;105m══════════════\033[38;5;117m══════════════\033[0m"
 echo ""
 gum style --foreground 82 --bold "Create your admin account:"
 gum style --foreground 226 "  $ACCESS_URL"
 gum style --foreground 245 "  $ACCESS_URL_LOCAL (if mDNS works)"
 if [ -n "$CHANNEL_KEY" ]; then
  echo ""
  echo -e "\033[1;32mChannel Key:\033[0m \033[0;33m$CHANNEL_KEY\033[0m"
 fi
 echo ""
 gum style --foreground 82 --bold "First Steps:"
 gum style --foreground 255 "  1. Open URL → 2. Accept cert → 3. Create admin → 4. Encode!"
 echo ""
 gum style --foreground 245 "Commands: systemctl {status|restart} stegasoo, journalctl -u stegasoo -f"
 # Prompt for restart if overclock was enabled
 if [ "$NEEDS_RESTART" = "true" ]; then
  echo ""
  gum style --foreground 226 --bold "⚠ Restart required for overclock settings"
  if gum confirm "Restart now?" --default=true; then
    gum style --foreground 82 "Restarting in 3 seconds..."
    sleep 3
    sudo reboot
  else
    gum style --foreground 214 "Run 'sudo reboot' later to apply overclock."
  fi
 fi
 echo ""
 gum style --foreground 212 --bold "Enjoy Stegasoo!"
 echo ""
--- a/rpi/flash-image.sh
+++ b/rpi/flash-image.sh
@@ -0,0 +1,295 @@
 #!/bin/bash
 #
 # Flash Stegasoo image to SD card
 # Uses rpi-imager if available, falls back to dd
 #
 # Usage: ./flash-image.sh <image> [device]
 #
 # Supports: .img, .img.zst, .img.xz, .img.gz, .img.zst.zip (GitHub release format)
 # If device is specified, skips auto-detection (useful for NVMe/large drives)
 #
 set -e
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 BOLD='\033[1m'
 NC='\033[0m'
 # Check for required tools
 for cmd in dd lsblk; do
    if ! command -v $cmd &> /dev/null; then
        echo -e "${RED}Error: $cmd is required but not installed.${NC}"
        exit 1
    fi
 done
 # Check for optional tools
 HAS_RPI_IMAGER=false
 HAS_PV=false
 if command -v rpi-imager &> /dev/null; then
    HAS_RPI_IMAGER=true
 fi
 if command -v pv &> /dev/null; then
    HAS_PV=true
 fi
 if [ "$HAS_RPI_IMAGER" = false ] && [ "$HAS_PV" = false ]; then
    echo -e "${YELLOW}Warning: Neither rpi-imager nor pv found. Progress will not be shown.${NC}"
 fi
 # Check for root
 if [ "$EUID" -ne 0 ]; then
    echo -e "${RED}Error: Must run as root (sudo)${NC}"
    exit 1
 fi
 # Check for image argument
 if [ -z "$1" ]; then
    echo -e "${RED}Usage: $0 <image> [device]${NC}"
    echo ""
    echo "Supported formats: .img, .img.zst, .img.xz, .img.gz, .img.zst.zip"
    echo ""
    echo "Examples:"
    echo "  $0 stegasoo-rpi-4.1.1.img.zst             # auto-detect SD card"
    echo "  $0 stegasoo-rpi-4.1.1.img.zst.zip         # from GitHub release"
    echo "  $0 stegasoo-rpi-4.1.1.img.zst /dev/sdb    # specify device"
    exit 1
 fi
 IMAGE="$1"
 MANUAL_DEVICE="$2"
 if [ ! -f "$IMAGE" ]; then
    echo -e "${RED}Error: Image file not found: $IMAGE${NC}"
    exit 1
 fi
 # Handle .zst.zip wrapper (GitHub releases workaround)
 if [[ "$IMAGE" == *.zst.zip ]]; then
    echo -e "${YELLOW}Extracting .zst from zip wrapper...${NC}"
    if ! command -v unzip &> /dev/null; then
        echo -e "${RED}Error: unzip is required for .zst.zip files but not installed.${NC}"
        exit 1
    fi
    TEMP_DIR=$(mktemp -d)
    trap "rm -rf $TEMP_DIR" EXIT
    unzip -q "$IMAGE" -d "$TEMP_DIR"
    IMAGE=$(find "$TEMP_DIR" -name "*.zst" | head -1)
    if [ -z "$IMAGE" ]; then
        echo -e "${RED}Error: No .zst file found in zip archive${NC}"
        exit 1
    fi
    echo -e "${GREEN}Found: $(basename "$IMAGE")${NC}"
    echo ""
 fi
 # Detect compression
 COMPRESSED=false
 COMP_TYPE=""
 if [[ "$IMAGE" == *.xz ]]; then
    COMPRESSED=true
    COMP_TYPE="xz"
    if ! command -v xzcat &> /dev/null; then
        echo -e "${RED}Error: xz is required for .xz files but not installed.${NC}"
        exit 1
    fi
 elif [[ "$IMAGE" == *.zst ]]; then
    COMPRESSED=true
    COMP_TYPE="zst"
    if ! command -v zstdcat &> /dev/null; then
        echo -e "${RED}Error: zstd is required for .zst files but not installed.${NC}"
        exit 1
    fi
 elif [[ "$IMAGE" == *.gz ]]; then
    COMPRESSED=true
    COMP_TYPE="gz"
    if ! command -v zcat &> /dev/null; then
        echo -e "${RED}Error: gzip is required for .gz files but not installed.${NC}"
        exit 1
    fi
 fi
 echo -e "${BLUE}"
 echo "╔═══════════════════════════════════════════════════════════════╗"
 echo "║              Stegasoo SD Card Flasher                         ║"
 echo "╚═══════════════════════════════════════════════════════════════╝"
 echo -e "${NC}"
 echo -e "Image: ${YELLOW}$IMAGE${NC}"
 echo -e "Size:  ${YELLOW}$(du -h "$IMAGE" | awk '{print $1}')${NC}"
 if [ "$COMPRESSED" = true ]; then
    echo -e "Type:  ${YELLOW}Compressed (will decompress on-the-fly)${NC}"
 fi
 echo ""
 # Use manual device or auto-detect
 if [ -n "$MANUAL_DEVICE" ]; then
    # Manual device specified
    if [ ! -b "$MANUAL_DEVICE" ]; then
        echo -e "${RED}Error: $MANUAL_DEVICE is not a block device${NC}"
        exit 1
    fi
    SELECTED="$MANUAL_DEVICE"
    echo -e "Using specified device: ${YELLOW}$SELECTED${NC}"
    echo ""
    lsblk "$SELECTED" -o NAME,SIZE,TYPE,MODEL
    echo ""
 else
    # Auto-detect SD card candidates
    echo -e "${BOLD}Scanning for SD cards...${NC}"
    echo ""
    declare -a CANDIDATES
    declare -a CANDIDATE_INFO
    while IFS= read -r line; do
        DEV=$(echo "$line" | awk '{print $1}')
        SIZE=$(echo "$line" | awk '{print $2}')
        TYPE=$(echo "$line" | awk '{print $3}')
        TRAN=$(echo "$line" | awk '{print $4}')
        MODEL=$(echo "$line" | awk '{print $5" "$6" "$7}' | xargs)
        # Skip if it's the root filesystem
        if mount | grep -q "^/dev/${DEV}[0-9]* on / "; then
            continue
        fi
        # Skip if any partition is mounted as root
        ROOT_DEV=$(mount | grep " on / " | awk '{print $1}' | sed 's/[0-9]*$//')
        if [[ "/dev/$DEV" == "$ROOT_DEV" ]]; then
            continue
        fi
        # Get size in bytes for reliable comparison
        SIZE_BYTES=$(lsblk -b -d -o SIZE -n "/dev/$DEV" 2>/dev/null | tr -d ' ')
        SIZE_GB_INT=$((SIZE_BYTES / 1073741824))  # 1024^3
        # Check if size is in SD card range (8GB - 128GB)
        if [ "$SIZE_GB_INT" -ge 8 ] && [ "$SIZE_GB_INT" -le 128 ]; then
            CANDIDATES+=("/dev/$DEV")
            CANDIDATE_INFO+=("$SIZE $TYPE ${TRAN:-???} $MODEL")
        fi
    done < <(lsblk -d -o NAME,SIZE,TYPE,TRAN,MODEL -n | grep "disk")
    if [ ${#CANDIDATES[@]} -eq 0 ]; then
        echo -e "${RED}No SD card candidates found.${NC}"
        echo "Looking for USB/removable disks between 8GB and 128GB."
        echo ""
        echo "Available disks:"
        lsblk -d -o NAME,SIZE,TYPE,TRAN,MODEL
        echo ""
        echo -e "${YELLOW}Tip: Specify device manually: $0 $IMAGE /dev/sdX${NC}"
        exit 1
    fi
    echo -e "${GREEN}Found ${#CANDIDATES[@]} candidate(s):${NC}"
    echo ""
    for i in "${!CANDIDATES[@]}"; do
        echo -e "  ${BOLD}[$((i+1))]${NC} ${CANDIDATES[$i]} - ${CANDIDATE_INFO[$i]}"
    done
    echo ""
    if [ ${#CANDIDATES[@]} -eq 1 ]; then
        SELECTED="${CANDIDATES[0]}"
        echo -e "Auto-selected: ${YELLOW}$SELECTED${NC}"
    else
        read -p "Select device [1-${#CANDIDATES[@]}]: " -r
        if [[ ! $REPLY =~ ^[0-9]+$ ]] || [ "$REPLY" -lt 1 ] || [ "$REPLY" -gt ${#CANDIDATES[@]} ]; then
            echo -e "${RED}Invalid selection.${NC}"
            exit 1
        fi
        SELECTED="${CANDIDATES[$((REPLY-1))]}"
    fi
 fi
 # Show current partitions
 echo ""
 echo -e "${BOLD}Current partitions on $SELECTED:${NC}"
 lsblk "$SELECTED" -o NAME,SIZE,FSTYPE,LABEL,MOUNTPOINT
 echo ""
 # Unmount any mounted partitions
 MOUNTED=$(mount | grep "^${SELECTED}" | awk '{print $1}' || true)
 if [ -n "$MOUNTED" ]; then
    echo -e "${YELLOW}Unmounting partitions...${NC}"
    for part in $MOUNTED; do
        umount "$part" 2>/dev/null || true
    done
 fi
 # Final confirmation
 echo -e "${RED}╔═══════════════════════════════════════════════════════════════╗${NC}"
 echo -e "${RED}║  WARNING: ALL DATA ON THIS DEVICE WILL BE DESTROYED!          ║${NC}"
 echo -e "${RED}║  $SELECTED                                                  ║${NC}"
 echo -e "${RED}╚═══════════════════════════════════════════════════════════════╝${NC}"
 echo ""
 read -p "Type 'yes' to continue: " -r
 if [[ ! $REPLY == "yes" ]]; then
    echo "Aborted."
    exit 1
 fi
 echo ""
 echo -e "${GREEN}Flashing image to $SELECTED...${NC}"
 echo ""
 # Try rpi-imager first (faster, native support for compressed images)
 if command -v rpi-imager &> /dev/null; then
    echo -e "${YELLOW}Using rpi-imager...${NC}"
    if rpi-imager --cli --disable-verify "$IMAGE" "$SELECTED"; then
        # rpi-imager succeeded
        :
    else
        echo -e "${YELLOW}rpi-imager failed, falling back to dd...${NC}"
        # Fall through to dd
        USE_DD=true
    fi
 else
    USE_DD=true
 fi
 # Fallback to dd
 if [ "$USE_DD" = true ]; then
    if [ "$HAS_PV" = true ]; then
        echo -e "${YELLOW}Using dd with progress...${NC}"
        if [ "$COMPRESSED" = true ]; then
            case "$COMP_TYPE" in
                xz)  pv "$IMAGE" | xzcat | dd of="$SELECTED" bs=4M conv=fsync 2>/dev/null ;;
                zst) pv "$IMAGE" | zstdcat | dd of="$SELECTED" bs=4M conv=fsync 2>/dev/null ;;
                gz)  pv "$IMAGE" | zcat | dd of="$SELECTED" bs=4M conv=fsync 2>/dev/null ;;
            esac
        else
            pv "$IMAGE" | dd of="$SELECTED" bs=4M conv=fsync 2>/dev/null
        fi
    else
        echo -e "${YELLOW}Using dd (no progress - install pv for progress bar)...${NC}"
        if [ "$COMPRESSED" = true ]; then
            case "$COMP_TYPE" in
                xz)  xzcat "$IMAGE" | dd of="$SELECTED" bs=4M conv=fsync status=progress ;;
                zst) zstdcat "$IMAGE" | dd of="$SELECTED" bs=4M conv=fsync status=progress ;;
                gz)  zcat "$IMAGE" | dd of="$SELECTED" bs=4M conv=fsync status=progress ;;
            esac
        else
            dd if="$IMAGE" of="$SELECTED" bs=4M conv=fsync status=progress
        fi
    fi
 fi
 echo ""
 echo -e "${GREEN}Syncing...${NC}"
 sync
 echo ""
 echo -e "${GREEN}╔═══════════════════════════════════════════════════════════════╗${NC}"
 echo -e "${GREEN}║                    Flash Complete!                            ║${NC}"
 echo -e "${GREEN}╚═══════════════════════════════════════════════════════════════╝${NC}"
 echo ""
 echo -e "You can now remove the SD card and boot your Raspberry Pi."
 echo ""
 echo -e "${YELLOW}Tip:${NC} On first boot, SSH in and the setup wizard will run automatically."
 echo ""
--- a/rpi/inject-wifi.sh
+++ b/rpi/inject-wifi.sh
@@ -0,0 +1,200 @@
 #!/bin/bash
 #
 # Inject WiFi credentials into SD card for Raspberry Pi
 # Supports both Bookworm (NetworkManager) and older (wpa_supplicant)
 #
 # First-time setup:
 #   ./inject-wifi.sh --setup
 #
 # Then after flashing:
 #   sudo ./inject-wifi.sh              # auto-detect partitions
 #   sudo ./inject-wifi.sh /dev/sdb     # specify device (finds partitions)
 #
 set -e
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 NC='\033[0m'
 CONFIG_DIR="$HOME/.config/stegasoo"
 CONFIG_FILE="$CONFIG_DIR/wifi.conf"
 # Setup mode - save credentials
 if [ "$1" == "--setup" ]; then
    echo -e "${BLUE}Stegasoo WiFi Config Setup${NC}"
    echo ""
    read -p "WiFi SSID: " WIFI_SSID
    read -s -p "WiFi Password: " WIFI_PASS
    echo ""
    read -p "Country code [US]: " WIFI_COUNTRY
    WIFI_COUNTRY=${WIFI_COUNTRY:-US}
    # Generate hashed PSK for wpa_supplicant (legacy)
    if command -v wpa_passphrase &> /dev/null; then
        HASHED_PSK=$(wpa_passphrase "$WIFI_SSID" "$WIFI_PASS" | grep -E "^\s+psk=" | tr -d '\t' | cut -d= -f2)
    else
        HASHED_PSK=""
        echo -e "${YELLOW}Note: wpa_passphrase not found, legacy mode disabled${NC}"
    fi
    # Save config (includes plaintext for NetworkManager)
    mkdir -p "$CONFIG_DIR"
    chmod 700 "$CONFIG_DIR"
    cat > "$CONFIG_FILE" << EOF
 # Stegasoo WiFi config
 WIFI_SSID="$WIFI_SSID"
 WIFI_PASS="$WIFI_PASS"
 WIFI_PSK_HASH="$HASHED_PSK"
 WIFI_COUNTRY="$WIFI_COUNTRY"
 EOF
    chmod 600 "$CONFIG_FILE"
    echo ""
    echo -e "${GREEN}Config saved to $CONFIG_FILE${NC}"
    exit 0
 fi
 # Normal mode - inject credentials
 if [ "$EUID" -ne 0 ]; then
    echo -e "${RED}Error: Must run as root (sudo)${NC}"
    echo "Usage: sudo $0 [/dev/sdX]"
    echo ""
    echo "First-time setup (no sudo): $0 --setup"
    exit 1
 fi
 # Load config
 if [ -n "$SUDO_USER" ]; then
    USER_HOME=$(getent passwd "$SUDO_USER" | cut -d: -f6)
    CONFIG_FILE="$USER_HOME/.config/stegasoo/wifi.conf"
 fi
 if [ ! -f "$CONFIG_FILE" ]; then
    echo -e "${RED}Config not found: $CONFIG_FILE${NC}"
    echo ""
    echo "Run setup first (without sudo):"
    echo "  ./inject-wifi.sh --setup"
    exit 1
 fi
 source "$CONFIG_FILE"
 if [ -z "$WIFI_SSID" ] || [ -z "$WIFI_PASS" ]; then
    echo -e "${RED}Invalid config. Run --setup again.${NC}"
    exit 1
 fi
 # Find partitions
 MANUAL_DEV="$1"
 if [ -n "$MANUAL_DEV" ]; then
    # Strip partition number if given (e.g., /dev/sdb1 -> /dev/sdb)
    BASE_DEV=$(echo "$MANUAL_DEV" | sed 's/[0-9]*$//')
    BOOT_DEV="${BASE_DEV}1"
    ROOT_DEV="${BASE_DEV}2"
 else
    # Auto-detect by label
    BOOT_PART=$(lsblk -o NAME,FSTYPE,LABEL -rn | grep -E "vfat.*(bootfs|boot)" | head -1 | awk '{print $1}')
    ROOT_PART=$(lsblk -o NAME,FSTYPE,LABEL -rn | grep -E "ext4.*rootfs" | head -1 | awk '{print $1}')
    if [ -z "$BOOT_PART" ] || [ -z "$ROOT_PART" ]; then
        echo -e "${RED}Could not find boot/root partitions. Is the SD card inserted?${NC}"
        echo ""
        lsblk -o NAME,SIZE,FSTYPE,LABEL
        echo ""
        echo -e "${YELLOW}Tip: Specify device manually: sudo $0 /dev/sdX${NC}"
        exit 1
    fi
    BOOT_DEV="/dev/$BOOT_PART"
    ROOT_DEV="/dev/$ROOT_PART"
 fi
 echo -e "${GREEN}Found partitions:${NC}"
 echo -e "  Boot: ${YELLOW}$BOOT_DEV${NC}"
 echo -e "  Root: ${YELLOW}$ROOT_DEV${NC}"
 # Mount points
 BOOT_MNT="/tmp/stegasoo-boot-$$"
 ROOT_MNT="/tmp/stegasoo-root-$$"
 cleanup() {
    umount "$BOOT_MNT" 2>/dev/null || true
    umount "$ROOT_MNT" 2>/dev/null || true
    rmdir "$BOOT_MNT" "$ROOT_MNT" 2>/dev/null || true
 }
 trap cleanup EXIT
 mkdir -p "$BOOT_MNT" "$ROOT_MNT"
 # Mount partitions
 mount "$BOOT_DEV" "$BOOT_MNT"
 mount "$ROOT_DEV" "$ROOT_MNT"
 echo ""
 # 1. Write NetworkManager config (Bookworm+)
 NM_DIR="$ROOT_MNT/etc/NetworkManager/system-connections"
 if [ -d "$ROOT_MNT/etc/NetworkManager" ]; then
    mkdir -p "$NM_DIR"
    # NetworkManager connection file
    NM_FILE="$NM_DIR/stegasoo-wifi.nmconnection"
    cat > "$NM_FILE" << EOF
 [connection]
 id=$WIFI_SSID
 type=wifi
 autoconnect=true
 [wifi]
 mode=infrastructure
 ssid=$WIFI_SSID
 [wifi-security]
 auth-alg=open
 key-mgmt=wpa-psk
 psk=$WIFI_PASS
 [ipv4]
 method=auto
 [ipv6]
 method=auto
 EOF
    chmod 600 "$NM_FILE"
    echo -e "${GREEN}Created NetworkManager config (Bookworm)${NC}"
 fi
 # 2. Write wpa_supplicant.conf (legacy, boot partition)
 if [ -n "$WIFI_PSK_HASH" ]; then
    cat > "$BOOT_MNT/wpa_supplicant.conf" << EOF
 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
 update_config=1
 country=$WIFI_COUNTRY
 network={
    ssid="$WIFI_SSID"
    psk=$WIFI_PSK_HASH
 }
 EOF
    echo -e "${GREEN}Created wpa_supplicant.conf (legacy)${NC}"
 fi
 # 3. Set WiFi country in boot config
 if [ -f "$BOOT_MNT/config.txt" ]; then
    if ! grep -q "^dtparam=cfg80211" "$BOOT_MNT/config.txt"; then
        echo "" >> "$BOOT_MNT/config.txt"
        echo "# WiFi country" >> "$BOOT_MNT/config.txt"
        echo "dtparam=cfg80211" >> "$BOOT_MNT/config.txt"
    fi
 fi
 echo -e "  SSID: ${YELLOW}$WIFI_SSID${NC}"
 echo ""
 echo -e "${GREEN}Done! WiFi credentials injected for Bookworm + legacy.${NC}"
--- a/rpi/patches/README.md
+++ b/rpi/patches/README.md
@@ -0,0 +1,57 @@
 # RPi Patches
 This directory contains patches for dependencies that need modifications to build on ARM64.
 ## Structure
 ```
 patches/
  <package>/
    arm64.patch       # Standard unified diff patch file
    apply-patch.sh    # Script with fallback strategies
 ```
 ## How It Works
 The `apply-patch.sh` script tries multiple strategies in order:
 1. **Patch file** - Apply the `.patch` file using `patch -p1`
 2. **Sed fallback** - Use sed for simple string replacements
 3. **Python fallback** - Use regex for flexible pattern matching
 This layered approach handles:
 - Exact matches (patch file works)
 - Minor upstream changes (sed catches variations)
 - Significant changes (Python regex is most flexible)
 - Already patched files (detected and skipped)
 ## Adding a New Patch
 1. Create a directory: `patches/<package>/`
 2. Create the patch file: `git diff > arm64.patch`
 3. Create `apply-patch.sh` with appropriate fallback logic
 4. Update `setup.sh` to call the patch script
 ## jpegio Patch
 The jpegio library includes x86-specific `-m64` compiler flags that fail on ARM64.
 The patch removes these flags by replacing:
 ```python
 cargs.append('-m64')
 ```
 with:
 ```python
 pass  # ARM64: removed x86-specific -m64 flag
 ```
 ## Updating Patches
 When upstream changes break a patch:
 1. Clone the new version
 2. Make the necessary modifications
 3. Generate a new patch: `diff -u original modified > arm64.patch`
 4. Test on a fresh Pi install
--- a/rpi/patches/jpegio/apply-patch.sh
+++ b/rpi/patches/jpegio/apply-patch.sh
@@ -0,0 +1,111 @@
 #!/bin/bash
 #
 # Apply ARM64 patch to jpegio
 # This script tries multiple strategies to remove the x86-specific -m64 flag
 #
 # Usage: ./apply-patch.sh /path/to/jpegio
 #
 set -e
 JPEGIO_DIR="${1:-.}"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PATCH_FILE="$SCRIPT_DIR/arm64.patch"
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 NC='\033[0m'
 cd "$JPEGIO_DIR"
 echo "Applying ARM64 patch to jpegio..."
 # Fix CRLF line endings (jpegio uses Windows line endings)
 if file setup.py | grep -q CRLF; then
    echo "  Converting CRLF to LF..."
    sed -i 's/\r$//' setup.py
 fi
 # Strategy 1: Try the standard patch file
 if [ -f "$PATCH_FILE" ]; then
    echo "  Trying patch file..."
    if patch -p1 --dry-run < "$PATCH_FILE" >/dev/null 2>&1; then
        patch -p1 < "$PATCH_FILE"
        echo -e "  ${GREEN}✓ Patch applied successfully${NC}"
        exit 0
    else
        echo -e "  ${YELLOW}Patch file didn't apply cleanly, trying fallback...${NC}"
    fi
 fi
 # Strategy 2: Sed replacement (handles any number of occurrences)
 if grep -q "cargs.append('-m64')" setup.py 2>/dev/null; then
    echo "  Using sed fallback..."
    sed -i "s/cargs.append('-m64')/pass  # ARM64: removed x86-specific -m64 flag/g" setup.py
    # Verify the fix
    if grep -q "cargs.append('-m64')" setup.py; then
        echo -e "  ${RED}✗ Sed replacement failed${NC}"
        exit 1
    fi
    echo -e "  ${GREEN}✓ Sed fallback successful${NC}"
    exit 0
 fi
 # Strategy 3: Check if already patched
 if grep -q "ARM64: removed" setup.py 2>/dev/null; then
    echo -e "  ${GREEN}✓ Already patched${NC}"
    exit 0
 fi
 # Strategy 4: Python-based patching (most flexible)
 echo "  Using Python fallback..."
 python3 << 'PYTHON_PATCH'
 import re
 import sys
 with open('setup.py', 'r') as f:
    content = f.read()
 original = content
 # Pattern 1: Direct replacement
 content = re.sub(
    r"cargs\.append\(['\"]+-m64['\"]+\)",
    "pass  # ARM64: removed x86-specific -m64 flag",
    content
 )
 # Pattern 2: Handle variations with different quotes or spacing
 content = re.sub(
    r"cargs\.append\s*\(\s*['\"]+-m64['\"]+\s*\)",
    "pass  # ARM64: removed x86-specific -m64 flag",
    content
 )
 if content == original:
    # Check if already patched or pattern not found
    if "ARM64: removed" in content:
        print("Already patched")
        sys.exit(0)
    else:
        print("Warning: -m64 pattern not found in setup.py")
        print("This may indicate jpegio's structure has changed significantly")
        sys.exit(0)  # Don't fail - maybe they removed it upstream
 with open('setup.py', 'w') as f:
    f.write(content)
 print("Python patch applied")
 PYTHON_PATCH
 if [ $? -eq 0 ]; then
    echo -e "  ${GREEN}✓ Python fallback successful${NC}"
    exit 0
 fi
 echo -e "${RED}✗ All patching strategies failed${NC}"
 echo "Please check jpegio's setup.py manually"
 exit 1
--- a/rpi/patches/jpegio/arm64.patch
+++ b/rpi/patches/jpegio/arm64.patch
@@ -0,0 +1,20 @@
 --- a/setup.py
 +++ b/setup.py
@@ -64,7 +64,7 @@ elif sys.platform == 'darwin': # macOS
     largs.append('-mmacosx-version-min=10.9')
     if arch == 'x64':
 -        cargs.append('-m64')
 +        pass  # ARM64: removed x86-specific -m64 flag
 elif sys.platform == 'linux':
     cargs.extend(['-w', '-fPIC'])
@@ -68,7 +68,7 @@ elif sys.platform == 'linux':
     cargs.extend(['-w', '-fPIC'])
     if arch == 'x64':
 -        cargs.append('-m64')
 +        pass  # ARM64: removed x86-specific -m64 flag
     dname_libjpeg = 'libjpeg'
 # end of if-else
--- a/rpi/pull-image.sh
+++ b/rpi/pull-image.sh
@@ -0,0 +1,207 @@
 #!/bin/bash
 #
 # Pull Stegasoo image from SD card
 # Auto-detects SD card, copies with progress, shrinks, and compresses
 #
 # Usage: ./pull-image.sh [output-name] [device]
 #        Output will be: stegasoo-rpi-YYYYMMDD.img.zst (or custom name)
 #        Use .img extension to skip compression: ./pull-image.sh foo.img
 #
 # If device is specified, skips auto-detection (useful for large drives)
 #
 set -e
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 BOLD='\033[1m'
 NC='\033[0m'
 # Check for required tools
 for cmd in dd pv zstd lsblk; do
    if ! command -v $cmd &> /dev/null; then
        echo -e "${RED}Error: $cmd is required but not installed.${NC}"
        exit 1
    fi
 done
 # Check for root
 if [ "$EUID" -ne 0 ]; then
    echo -e "${RED}Error: Must run as root (sudo)${NC}"
    exit 1
 fi
 # Output filename and optional device
 if [ -n "$1" ]; then
    OUTPUT="$1"
 else
    OUTPUT="stegasoo-rpi-$(date +%Y%m%d).img.zst"
 fi
 MANUAL_DEVICE="$2"
 # Check if output ends in .img (skip compression) or .zst (compress)
 SKIP_COMPRESS=false
 if [[ "$OUTPUT" == *.img ]]; then
    IMG_FILE="$OUTPUT"
    SKIP_COMPRESS=true
 elif [[ "$OUTPUT" == *.zst ]]; then
    IMG_FILE="${OUTPUT%.zst}"
 else
    # No recognized extension, add .img.zst
    IMG_FILE="${OUTPUT}.img"
    OUTPUT="${OUTPUT}.img.zst"
 fi
 echo -e "${BLUE}"
 echo "╔═══════════════════════════════════════════════════════════════╗"
 echo "║              Stegasoo SD Card Image Puller                    ║"
 echo "╚═══════════════════════════════════════════════════════════════╝"
 echo -e "${NC}"
 # Use manual device or auto-detect
 if [ -n "$MANUAL_DEVICE" ]; then
    # Manual device specified
    if [ ! -b "$MANUAL_DEVICE" ]; then
        echo -e "${RED}Error: $MANUAL_DEVICE is not a block device${NC}"
        exit 1
    fi
    SELECTED="$MANUAL_DEVICE"
    echo -e "Using specified device: ${YELLOW}$SELECTED${NC}"
    echo ""
    lsblk "$SELECTED" -o NAME,SIZE,TYPE,MODEL
    echo ""
 else
    # Auto-detect SD card candidates
    # Looking for: USB/removable, 8-128GB, not mounted as root filesystem
    echo -e "${BOLD}Scanning for SD cards...${NC}"
    echo ""
    declare -a CANDIDATES
    declare -a CANDIDATE_INFO
    while IFS= read -r line; do
        DEV=$(echo "$line" | awk '{print $1}')
        SIZE=$(echo "$line" | awk '{print $2}')
        TYPE=$(echo "$line" | awk '{print $3}')
        TRAN=$(echo "$line" | awk '{print $4}')
        MODEL=$(echo "$line" | awk '{print $5" "$6" "$7}' | xargs)
        # Skip if it's the root filesystem
        if mount | grep -q "^/dev/${DEV}[0-9]* on / "; then
            continue
        fi
        # Skip if any partition is mounted as root
        ROOT_DEV=$(mount | grep " on / " | awk '{print $1}' | sed 's/[0-9]*$//')
        if [[ "/dev/$DEV" == "$ROOT_DEV" ]]; then
            continue
        fi
        # Get size in bytes for reliable comparison
        SIZE_BYTES=$(lsblk -b -d -o SIZE -n "/dev/$DEV" 2>/dev/null | tr -d ' ')
        SIZE_GB_INT=$((SIZE_BYTES / 1073741824))  # 1024^3
        # Check if size is in SD card range (8GB - 128GB)
        if [ "$SIZE_GB_INT" -ge 8 ] && [ "$SIZE_GB_INT" -le 128 ]; then
            CANDIDATES+=("/dev/$DEV")
            CANDIDATE_INFO+=("$SIZE $TYPE ${TRAN:-???} $MODEL")
        fi
    done < <(lsblk -d -o NAME,SIZE,TYPE,TRAN,MODEL -n | grep "disk")
    if [ ${#CANDIDATES[@]} -eq 0 ]; then
        echo -e "${RED}No SD card candidates found.${NC}"
        echo "Looking for USB/removable disks between 8GB and 128GB."
        echo ""
        echo "Available disks:"
        lsblk -d -o NAME,SIZE,TYPE,TRAN,MODEL
        echo ""
        echo -e "${YELLOW}Tip: Specify device manually: $0 output.img.zst /dev/sdX${NC}"
        exit 1
    fi
    echo -e "${GREEN}Found ${#CANDIDATES[@]} candidate(s):${NC}"
    echo ""
    for i in "${!CANDIDATES[@]}"; do
        echo -e "  ${BOLD}[$((i+1))]${NC} ${CANDIDATES[$i]} - ${CANDIDATE_INFO[$i]}"
    done
    echo ""
    if [ ${#CANDIDATES[@]} -eq 1 ]; then
        SELECTED="${CANDIDATES[0]}"
        echo -e "Auto-selected: ${YELLOW}$SELECTED${NC}"
    else
        read -p "Select device [1-${#CANDIDATES[@]}]: " -r
        if [[ ! $REPLY =~ ^[0-9]+$ ]] || [ "$REPLY" -lt 1 ] || [ "$REPLY" -gt ${#CANDIDATES[@]} ]; then
            echo -e "${RED}Invalid selection.${NC}"
            exit 1
        fi
        SELECTED="${CANDIDATES[$((REPLY-1))]}"
    fi
 fi
 # Show partitions
 echo ""
 echo -e "${BOLD}Partitions on $SELECTED:${NC}"
 lsblk "$SELECTED" -o NAME,SIZE,FSTYPE,LABEL,MOUNTPOINT
 echo ""
 # Final confirmation
 echo -e "${RED}╔═══════════════════════════════════════════════════════════════╗${NC}"
 echo -e "${RED}║  WARNING: This will read the ENTIRE device:                   ║${NC}"
 echo -e "${RED}║  $SELECTED                                                  ║${NC}"
 echo -e "${RED}╚═══════════════════════════════════════════════════════════════╝${NC}"
 echo ""
 echo -e "Output: ${YELLOW}$OUTPUT${NC}"
 echo ""
 read -p "Continue? [y/N] " -n 1 -r
 echo
 if [[ ! $REPLY =~ ^[Yy]$ ]]; then
    echo "Aborted."
    exit 1
 fi
 # Get device size for pv
 DEV_SIZE=$(blockdev --getsize64 "$SELECTED")
 echo ""
 echo -e "${GREEN}[1/3]${NC} Copying image from $SELECTED..."
 dd if="$SELECTED" bs=4M status=none | pv -s "$DEV_SIZE" > "$IMG_FILE"
 sync
 echo ""
 echo -e "${GREEN}[2/3]${NC} Shrinking image..."
 if command -v pishrink.sh &> /dev/null; then
    pishrink.sh "$IMG_FILE"
 elif [ -f "./pishrink.sh" ]; then
    bash ./pishrink.sh "$IMG_FILE"
 elif [ -f "../pishrink.sh" ]; then
    bash ../pishrink.sh "$IMG_FILE"
 else
    echo -e "${YELLOW}pishrink.sh not found, skipping shrink step.${NC}"
    echo "Download from: https://github.com/Drewsif/PiShrink"
 fi
 echo ""
 if [ "$SKIP_COMPRESS" = true ]; then
    echo -e "${GREEN}[3/3]${NC} Skipping compression (.img output)"
    FINAL_SIZE=$(du -h "$IMG_FILE" | awk '{print $1}')
    OUTPUT="$IMG_FILE"
 else
    echo -e "${GREEN}[3/3]${NC} Compressing with zstd..."
    pv "$IMG_FILE" | zstd -19 -T0 -q > "$OUTPUT"
    rm -f "$IMG_FILE"
    FINAL_SIZE=$(du -h "$OUTPUT" | awk '{print $1}')
 fi
 echo ""
 echo -e "${GREEN}╔═══════════════════════════════════════════════════════════════╗${NC}"
 echo -e "${GREEN}║                    Image Complete!                            ║${NC}"
 echo -e "${GREEN}╚═══════════════════════════════════════════════════════════════╝${NC}"
 echo ""
 echo -e "Output: ${YELLOW}$OUTPUT${NC}"
 echo -e "Size:   ${YELLOW}$FINAL_SIZE${NC}"
 echo ""
--- a/rpi/sanitize-for-image.sh
+++ b/rpi/sanitize-for-image.sh
@@ -0,0 +1,595 @@
 #!/bin/bash
 #
 # Sanitize Raspberry Pi for SD Card Image Distribution
 # Run this BEFORE creating an image with dd
 #
 # This script removes:
 #   - WiFi credentials (unless --soft)
 #   - SSH host keys (will regenerate on boot)
 #   - SSH authorized keys
 #   - User-specific data
 #   - Bash history
 #   - Logs
 #   - Stegasoo auth database (users will create their own admin)
 #
 # Usage:
 #   sudo ./sanitize-for-image.sh                 # Full sanitize for image distribution
 #   sudo ./sanitize-for-image.sh --soft          # Soft reset (keeps WiFi for testing)
 #   sudo ./sanitize-for-image.sh --soft --reboot # Soft reset and auto-reboot
 #   sudo ./sanitize-for-image.sh --reboot        # Full sanitize and auto-shutdown
 #
 set -e
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 CYAN='\033[0;36m'
 GRAY='\033[0;90m'
 BOLD='\033[1m'
 NC='\033[0m'
 # Show help
 show_help() {
    echo "Stegasoo Sanitize Script - Prepare Pi for SD Card Imaging"
    echo ""
    echo "Usage: sudo $0 [options]"
    echo ""
    echo "Options:"
    echo "  -h, --help     Show this help message"
    echo "  -s, --soft     Soft reset (keeps WiFi for testing)"
    echo "  -r, --reboot   Auto-reboot/shutdown when done"
    echo ""
    echo "Examples:"
    echo "  sudo $0                 # Full sanitize, prompts for shutdown"
    echo "  sudo $0 --soft          # Keep WiFi, reset everything else"
    echo "  sudo $0 --soft --reboot # Soft reset, auto-reboot"
    echo "  sudo $0 --reboot        # Full sanitize, auto-shutdown"
    echo ""
    echo "Config override:"
    echo "  Set STEGASOO_DIR to specify a custom install location:"
    echo "    export STEGASOO_DIR=\"/home/pi/stegasoo\""
    echo "    sudo -E $0"
    echo ""
    exit 0
 }
 SOFT_RESET=false
 AUTO_REBOOT=false
 for arg in "$@"; do
    case $arg in
        -h|--help) show_help ;;
        --soft|-s) SOFT_RESET=true ;;
        --reboot|-r) AUTO_REBOOT=true ;;
    esac
 done
 if [ "$EUID" -ne 0 ]; then
    echo -e "${RED}Error: Must run as root (sudo)${NC}"
    exit 1
 fi
 clear
 echo ""
 echo -e "\033[38;5;93m══════════════\033[38;5;99m══════════════\033[38;5;105m══════════════\033[38;5;117m══════════════\033[0m"
 echo -e "${GRAY} · .  · .  *  · .  *  · .  *  · .  *  · .  *  · .  ·${NC}"
 echo -e "\033[38;5;220m    ___  _____  ___    ___    _    ___    ___    ___\033[0m"
 echo -e "\033[38;5;220m   / __||_   _|| __|  / __|  /_\\\\  / __|  / _ \\\\  / _ \\\\\033[0m"
 echo -e "\033[38;5;220m   \\\\__ \\\\  | |  | _|  | (_ | / _ \\\\ \\\\__ \\\\ | (_) || (_) |\033[0m"
 echo -e "\033[38;5;220m   |___/  |_|  |___|  \\___|/_/ \\_\\\\|___/  \\\\___/  \\\\___/\033[0m"
 echo -e "${GRAY} · .  · .  *  · .  *  · .  *  · .  *  · .  *  · .  ·${NC}"
 echo -e "\033[38;5;93m══════════════\033[38;5;99m══════════════\033[38;5;105m══════════════\033[38;5;117m══════════════\033[0m"
 if [ "$SOFT_RESET" = true ]; then
    echo -e "\033[1;37m                  Soft Reset (Factory)\033[0m"
 else
    echo -e "\033[1;37m                  Sanitize for Imaging\033[0m"
 fi
 echo -e "\033[38;5;93m══════════════\033[38;5;99m══════════════\033[38;5;105m══════════════\033[38;5;117m══════════════\033[0m"
 echo ""
 if [ "$SOFT_RESET" = true ]; then
    echo "  WiFi credentials will be KEPT for continued testing."
    echo "  Everything else will be reset to first-boot state."
 else
    echo "  This will remove ALL personal data for imaging."
    echo "  The system will shut down when complete."
 fi
 echo ""
 if [ "$AUTO_REBOOT" = false ]; then
    # Flush input buffer before prompt
    read -t 0.1 -n 10000 discard </dev/tty 2>/dev/null || true
    read -p "Continue? This cannot be undone! [y/N] " -n 1 -r </dev/tty
    echo
    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
        echo "Aborted."
        exit 1
    fi
 fi
 # Track validation results
 VALIDATION_ERRORS=0
 # =============================================================================
 # Step 1: WiFi Credentials
 # =============================================================================
 if [ "$SOFT_RESET" = true ]; then
    echo -e "${GREEN}[1/11]${NC} Keeping WiFi credentials (soft reset)..."
    echo "  WiFi config preserved"
 else
    echo -e "${GREEN}[1/11]${NC} Removing WiFi credentials..."
    # Remove from rootfs
    if [ -f /etc/wpa_supplicant/wpa_supplicant.conf ]; then
        cat > /etc/wpa_supplicant/wpa_supplicant.conf << 'EOF'
 ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
 update_config=1
 country=US
 # Add your WiFi network here on first boot:
 # network={
 #     ssid="YourNetworkName"
 #     psk="YourPassword"
 # }
 EOF
        echo "  Cleared /etc/wpa_supplicant/wpa_supplicant.conf"
    fi
    # Remove from boot partition (headless setup file)
    BOOT_PART=$(findmnt -n -o SOURCE /boot/firmware 2>/dev/null || findmnt -n -o SOURCE /boot 2>/dev/null || echo "")
    if [ -n "$BOOT_PART" ]; then
        BOOT_MOUNT=$(findmnt -n -o TARGET "$BOOT_PART" 2>/dev/null || echo "/boot")
        rm -f "$BOOT_MOUNT/wpa_supplicant.conf" 2>/dev/null || true
        echo "  Removed boot partition WiFi config"
    fi
    # Remove NetworkManager connections (RPi OS Bookworm+)
    if [ -d /etc/NetworkManager/system-connections ]; then
        # Remove all WiFi connections (files containing type=wifi)
        for conn in /etc/NetworkManager/system-connections/*; do
            if [ -f "$conn" ] && grep -q "type=wifi" "$conn" 2>/dev/null; then
                rm -f "$conn"
                echo "  Removed NetworkManager: $(basename "$conn")"
            fi
        done
    fi
    # Remove netplan WiFi configs (Ubuntu-based systems)
    if [ -d /etc/netplan ]; then
        for np in /etc/netplan/*.yaml; do
            if [ -f "$np" ] && grep -q "wifis:" "$np" 2>/dev/null; then
                rm -f "$np"
                echo "  Removed netplan: $(basename "$np")"
            fi
        done
        # Also remove NM-generated netplan files (contain WiFi SSIDs)
        rm -f /etc/netplan/90-NM-*.yaml 2>/dev/null && echo "  Removed netplan NM configs"
    fi
 fi
 # =============================================================================
 # Step 2: SSH Authorized Keys
 # =============================================================================
 echo -e "${GREEN}[2/11]${NC} Removing SSH authorized keys..."
 for user_home in /home/*; do
    if [ -d "$user_home/.ssh" ]; then
        rm -f "$user_home/.ssh/authorized_keys"
        rm -f "$user_home/.ssh/known_hosts"
        echo "  Cleared $user_home/.ssh/"
    fi
 done
 rm -f /root/.ssh/authorized_keys /root/.ssh/known_hosts 2>/dev/null || true
 # =============================================================================
 # Step 3: SSH Host Keys
 # =============================================================================
 echo -e "${GREEN}[3/11]${NC} Removing SSH host keys (will regenerate on first boot)..."
 rm -f /etc/ssh/ssh_host_*
 # Create a first-boot service to regenerate SSH keys
 cat > /etc/systemd/system/regenerate-ssh-keys.service <<'SSHEOF'
 [Unit]
 Description=Regenerate SSH host keys on first boot
 Before=ssh.service
 ConditionPathExists=!/etc/ssh/ssh_host_ed25519_key
 [Service]
 Type=oneshot
 ExecStart=/usr/bin/ssh-keygen -A
 [Install]
 WantedBy=multi-user.target
 SSHEOF
 systemctl enable regenerate-ssh-keys.service 2>/dev/null || true
 echo "  SSH host keys removed (will regenerate on first boot)"
 # =============================================================================
 # Step 4: Bash History
 # =============================================================================
 echo -e "${GREEN}[4/11]${NC} Clearing bash history..."
 for user_home in /home/*; do
    rm -f "$user_home/.bash_history"
    rm -f "$user_home/.python_history"
 done
 rm -f /root/.bash_history /root/.python_history 2>/dev/null || true
 history -c 2>/dev/null || true
 # =============================================================================
 # Step 5: Stegasoo User Data
 # =============================================================================
 echo -e "${GREEN}[5/11]${NC} Removing Stegasoo user data..."
 # Remove auth database (users create their own admin on first run)
 rm -rf /opt/stegasoo/frontends/web/instance/ 2>/dev/null
 rm -rf /home/*/stegasoo/frontends/web/instance/
 # Remove SSL certs (will be regenerated)
 rm -rf /opt/stegasoo/frontends/web/certs/ 2>/dev/null
 rm -rf /home/*/stegasoo/frontends/web/certs/
 # Remove any .env files with channel keys
 rm -f /opt/stegasoo/frontends/web/.env 2>/dev/null
 rm -f /home/*/stegasoo/frontends/web/.env
 # Reset port 443 redirect (user reconfigures in wizard)
 if systemctl is-enabled --quiet iptables-restore 2>/dev/null; then
    systemctl disable iptables-restore 2>/dev/null || true
    rm -f /etc/systemd/system/iptables-restore.service
    rm -f /etc/iptables.rules
    iptables -t nat -F PREROUTING 2>/dev/null || true
    echo "  Port 443 redirect cleared"
 fi
 echo "  Stegasoo instance data cleared"
 # =============================================================================
 # Step 6: First-Boot Wizard Setup
 # =============================================================================
 echo -e "${GREEN}[6/11]${NC} Setting up first-boot wizard..."
 # Find stegasoo install directory (prefer /opt/stegasoo)
 STEGASOO_DIR=""
 if [ -d /opt/stegasoo ]; then
    STEGASOO_DIR="/opt/stegasoo"
 else
    STEGASOO_DIR=$(ls -d /home/*/stegasoo 2>/dev/null | head -1)
 fi
 if [ -z "$STEGASOO_DIR" ]; then
    # Last resort fallback
    if [ -d /root/stegasoo ]; then
        STEGASOO_DIR="/root/stegasoo"
    fi
 fi
 STEGASOO_USER=$(stat -c '%U' "$STEGASOO_DIR" 2>/dev/null || echo "pi")
 echo "  Stegasoo directory: $STEGASOO_DIR"
 echo "  Stegasoo user: $STEGASOO_USER"
 # Check and repair venv if needed (paths break when moving directories)
 if [ -n "$STEGASOO_DIR" ] && [ -d "$STEGASOO_DIR/venv" ]; then
    VENV_PYTHON="$STEGASOO_DIR/venv/bin/python"
    # Check if venv python works and has stegasoo installed
    if ! "$VENV_PYTHON" -c "import stegasoo" 2>/dev/null; then
        echo "  Venv broken or stegasoo not installed, rebuilding..."
        rm -rf "$STEGASOO_DIR/venv"
        # Find Python 3.12 (prefer pyenv, fall back to system)
        USER_HOME=$(eval echo "~$STEGASOO_USER")
        PYENV_PYTHON="$USER_HOME/.pyenv/versions/3.12*/bin/python"
        if compgen -G "$PYENV_PYTHON" > /dev/null 2>&1; then
            PYTHON_BIN=$(ls $PYENV_PYTHON 2>/dev/null | head -1)
            echo "  Using pyenv Python: $PYTHON_BIN"
        elif command -v python3.12 &>/dev/null; then
            PYTHON_BIN="python3.12"
            echo "  Using system Python 3.12"
        else
            PYTHON_BIN="python3"
            echo "  Warning: Python 3.12 not found, using $($PYTHON_BIN --version)"
        fi
        sudo -u "$STEGASOO_USER" "$PYTHON_BIN" -m venv "$STEGASOO_DIR/venv"
        sudo -u "$STEGASOO_USER" "$STEGASOO_DIR/venv/bin/pip" install --quiet --upgrade pip setuptools wheel
        # On ARM64, jpegio needs patching before install
        ARCH=$(uname -m)
        if [[ "$ARCH" == "aarch64" || "$ARCH" == "arm64" ]]; then
            echo "  Building jpegio for ARM64 (this may take a minute)..."
            # Install build deps
            sudo -u "$STEGASOO_USER" "$STEGASOO_DIR/venv/bin/pip" install --quiet cython numpy
            JPEGIO_DIR="/tmp/jpegio-build-$$"
            rm -rf "$JPEGIO_DIR"
            if git clone https://github.com/dwgoon/jpegio.git "$JPEGIO_DIR" 2>/dev/null; then
                # Apply patch to remove -m64 flag
                if [ -f "$STEGASOO_DIR/rpi/patches/jpegio/apply-patch.sh" ]; then
                    bash "$STEGASOO_DIR/rpi/patches/jpegio/apply-patch.sh" "$JPEGIO_DIR"
                else
                    sed -i "s/cargs.append('-m64')/pass  # ARM64 fix/g" "$JPEGIO_DIR/setup.py"
                fi
                # Change ownership so user can build
                chown -R "$STEGASOO_USER:$STEGASOO_USER" "$JPEGIO_DIR"
                sudo -u "$STEGASOO_USER" "$STEGASOO_DIR/venv/bin/pip" install "$JPEGIO_DIR"
                rm -rf "$JPEGIO_DIR"
            else
                echo "  Warning: Failed to clone jpegio, DCT mode may not work"
            fi
        fi
        sudo -u "$STEGASOO_USER" "$STEGASOO_DIR/venv/bin/pip" install --quiet -e "$STEGASOO_DIR[web]"
        echo "  Venv rebuilt and stegasoo installed"
    else
        echo "  Venv OK"
    fi
 fi
 # Ensure PATH hook exists for stegasoo CLI and scripts
 if [ ! -f /etc/profile.d/stegasoo-path.sh ]; then
    echo "  Creating PATH hook..."
    cat > /etc/profile.d/stegasoo-path.sh <<'PATHEOF'
 # Stegasoo CLI and scripts
 if [ -d /opt/stegasoo/venv/bin ]; then
    export PATH="/opt/stegasoo/venv/bin:$PATH"
 fi
 if [ -d /opt/stegasoo/rpi ]; then
    export PATH="/opt/stegasoo/rpi:$PATH"
 fi
 PATHEOF
    chmod 644 /etc/profile.d/stegasoo-path.sh
    echo "  Installed PATH hook to /etc/profile.d/"
 else
    echo "  PATH hook OK"
 fi
 if [ -n "$STEGASOO_DIR" ] && [ -f "$STEGASOO_DIR/rpi/stegasoo-wizard.sh" ]; then
    # Install the profile.d hook
    cp "$STEGASOO_DIR/rpi/stegasoo-wizard.sh" /etc/profile.d/stegasoo-wizard.sh
    chmod 644 /etc/profile.d/stegasoo-wizard.sh
    echo "  Installed wizard hook to /etc/profile.d/"
    # Create the first-boot flag
    touch /etc/stegasoo-first-boot
    echo "  Created /etc/stegasoo-first-boot flag"
    # Reset systemd service to defaults (wizard will reconfigure)
    cat > /etc/systemd/system/stegasoo.service <<EOF
 [Unit]
 Description=Stegasoo Web UI
 After=network.target
 [Service]
 Type=simple
 User=$STEGASOO_USER
 WorkingDirectory=$STEGASOO_DIR/frontends/web
 Environment="PATH=$STEGASOO_DIR/venv/bin:/usr/bin"
 Environment="STEGASOO_AUTH_ENABLED=true"
 Environment="STEGASOO_HTTPS_ENABLED=false"
 Environment="STEGASOO_PORT=5000"
 Environment="STEGASOO_CHANNEL_KEY="
 ExecStart=$STEGASOO_DIR/venv/bin/python app.py
 Restart=on-failure
 RestartSec=5
 [Install]
 WantedBy=multi-user.target
 EOF
    systemctl daemon-reload
    echo "  Reset systemd service to defaults"
 else
    echo -e "  ${RED}ERROR: Could not find wizard script${NC}"
    echo "  STEGASOO_DIR: $STEGASOO_DIR"
    VALIDATION_ERRORS=$((VALIDATION_ERRORS + 1))
 fi
 # =============================================================================
 # Step 7: Logs
 # =============================================================================
 echo -e "${GREEN}[7/11]${NC} Clearing logs..."
 journalctl --rotate 2>/dev/null || true
 journalctl --vacuum-time=1s 2>/dev/null || true
 rm -rf /var/log/*.log /var/log/*.gz /var/log/*.[0-9] 2>/dev/null || true
 rm -rf /var/log/apt/* 2>/dev/null || true
 rm -rf /var/log/journal/* 2>/dev/null || true
 find /var/log -type f -name "*.log" -delete 2>/dev/null || true
 echo "  Logs cleared"
 # =============================================================================
 # Step 8: Temporary Files
 # =============================================================================
 echo -e "${GREEN}[8/11]${NC} Clearing temporary files..."
 rm -rf /tmp/* 2>/dev/null || true
 rm -rf /var/tmp/* 2>/dev/null || true
 echo "  Temp files cleared"
 # =============================================================================
 # Step 9: Package Cache
 # =============================================================================
 echo -e "${GREEN}[9/11]${NC} Clearing package cache..."
 apt-get clean 2>/dev/null || true
 rm -rf /var/cache/apt/archives/* 2>/dev/null || true
 echo "  Package cache cleared"
 # =============================================================================
 # Step 10: Remove Overclock Settings
 # =============================================================================
 if [ "$SOFT_RESET" = true ]; then
    echo -e "${GREEN}[10/11]${NC} Keeping overclock settings (soft reset)..."
    echo "  Overclock config preserved"
 else
    echo -e "${GREEN}[10/11]${NC} Removing overclock settings..."
    CONFIG_FILE="/boot/firmware/config.txt"
    if [ ! -f "$CONFIG_FILE" ]; then
        CONFIG_FILE="/boot/config.txt"
    fi
    if [ -f "$CONFIG_FILE" ]; then
        # Remove overclock-related lines
        if grep -q "over_voltage\|arm_freq\|gpu_freq" "$CONFIG_FILE" 2>/dev/null; then
            # Create temp file without overclock lines
            grep -v "^over_voltage=\|^arm_freq=\|^gpu_freq=\|^# Overclock" "$CONFIG_FILE" > "${CONFIG_FILE}.tmp"
            mv "${CONFIG_FILE}.tmp" "$CONFIG_FILE"
            echo "  Removed overclock settings from $CONFIG_FILE"
        else
            echo "  No overclock settings found"
        fi
    else
        echo "  Config file not found, skipping"
    fi
 fi
 # =============================================================================
 # Step 11: Final Sync
 # =============================================================================
 echo -e "${GREEN}[11/11]${NC} Final sync..."
 rm -f /root/.bash_history 2>/dev/null || true
 sync
 echo "  Filesystem synced"
 # =============================================================================
 # Validation
 # =============================================================================
 echo ""
 echo -e "${CYAN}Validating sanitization...${NC}"
 # Check first-boot flag
 if [ -f /etc/stegasoo-first-boot ]; then
    echo -e "  ${GREEN}[PASS]${NC} First-boot flag exists"
 else
    echo -e "  ${RED}[FAIL]${NC} First-boot flag missing"
    VALIDATION_ERRORS=$((VALIDATION_ERRORS + 1))
 fi
 # Check profile.d hook
 if [ -f /etc/profile.d/stegasoo-wizard.sh ]; then
    echo -e "  ${GREEN}[PASS]${NC} Wizard hook installed"
 else
    echo -e "  ${RED}[FAIL]${NC} Wizard hook missing"
    VALIDATION_ERRORS=$((VALIDATION_ERRORS + 1))
 fi
 # Check SSH host keys removed
 if ls /etc/ssh/ssh_host_* 1>/dev/null 2>&1; then
    echo -e "  ${RED}[FAIL]${NC} SSH host keys still present"
    VALIDATION_ERRORS=$((VALIDATION_ERRORS + 1))
 else
    echo -e "  ${GREEN}[PASS]${NC} SSH host keys removed"
 fi
 # Check Stegasoo instance data removed
 DB_FOUND=false
 if ls /opt/stegasoo/frontends/web/instance/*.db 1>/dev/null 2>&1; then
    DB_FOUND=true
 fi
 if ls /home/*/stegasoo/frontends/web/instance/*.db 1>/dev/null 2>&1; then
    DB_FOUND=true
 fi
 if [ "$DB_FOUND" = true ]; then
    echo -e "  ${RED}[FAIL]${NC} Stegasoo database still present"
    VALIDATION_ERRORS=$((VALIDATION_ERRORS + 1))
 else
    echo -e "  ${GREEN}[PASS]${NC} Stegasoo database removed"
 fi
 # Check WiFi (only for full sanitize)
 if [ "$SOFT_RESET" = false ]; then
    WIFI_FOUND=false
    # Check wpa_supplicant
    if grep -q "psk=" /etc/wpa_supplicant/wpa_supplicant.conf 2>/dev/null; then
        WIFI_FOUND=true
    fi
    # Check NetworkManager
    for conn in /etc/NetworkManager/system-connections/*; do
        if [ -f "$conn" ] && grep -q "type=wifi" "$conn" 2>/dev/null; then
            WIFI_FOUND=true
            break
        fi
    done
    # Check netplan
    for np in /etc/netplan/*.yaml; do
        if [ -f "$np" ] && grep -q "wifis:" "$np" 2>/dev/null; then
            WIFI_FOUND=true
            break
        fi
    done
    # Check NM-generated netplan
    if ls /etc/netplan/90-NM-*.yaml 1>/dev/null 2>&1; then
        WIFI_FOUND=true
    fi
    if [ "$WIFI_FOUND" = true ]; then
        echo -e "  ${RED}[FAIL]${NC} WiFi credentials still present"
        VALIDATION_ERRORS=$((VALIDATION_ERRORS + 1))
    else
        echo -e "  ${GREEN}[PASS]${NC} WiFi credentials cleared"
    fi
 else
    echo -e "  ${YELLOW}[SKIP]${NC} WiFi check (soft reset mode)"
 fi
 # Check authorized_keys removed
 AUTH_KEYS_FOUND=false
 for user_home in /home/*; do
    if [ -f "$user_home/.ssh/authorized_keys" ]; then
        AUTH_KEYS_FOUND=true
        break
    fi
 done
 if [ "$AUTH_KEYS_FOUND" = true ]; then
    echo -e "  ${RED}[FAIL]${NC} SSH authorized_keys still present"
    VALIDATION_ERRORS=$((VALIDATION_ERRORS + 1))
 else
    echo -e "  ${GREEN}[PASS]${NC} SSH authorized_keys removed"
 fi
 # =============================================================================
 # Summary
 # =============================================================================
 echo ""
 if [ $VALIDATION_ERRORS -eq 0 ]; then
    echo -e "${BOLD}Sanitization Complete!${NC}"
    echo -e "${GREEN}-------------------------------------------------------${NC}"
    echo -e "  ${GREEN}All validation checks passed.${NC}"
 else
    echo -e "${BOLD}Sanitization Complete with Errors${NC}"
    echo -e "${RED}-------------------------------------------------------${NC}"
    echo -e "  ${RED}$VALIDATION_ERRORS validation check(s) failed${NC}"
 fi
 echo ""
 if [ "$SOFT_RESET" = true ]; then
    echo -e "${CYAN}Soft reset complete.${NC}"
    echo "You can now reboot to test the first-boot wizard."
    echo ""
    if [ "$AUTO_REBOOT" = true ]; then
        echo "Rebooting..."
        exec reboot
    fi
    # Flush input buffer and pause before prompt
    read -t 0.1 -n 10000 discard </dev/tty 2>/dev/null || true
    sleep 0.3
    read -p "Reboot now? [y/N] " -n 1 -r </dev/tty
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        exec reboot
    fi
 else
    echo "The system is ready for imaging."
    echo ""
    echo -e "${YELLOW}Next steps:${NC}"
    echo "  1. Shut down: sudo shutdown -h now"
    echo "  2. Remove SD card"
    echo "  3. On another machine, copy with:"
    echo "     sudo dd if=/dev/sdX of=stegasoo-rpi.img bs=4M status=progress"
    echo "  4. Compress: zstd -19 stegasoo-rpi.img"
    echo ""
    if [ "$AUTO_REBOOT" = true ]; then
        echo "Shutting down..."
        exec shutdown -h now
    fi
    # Flush input buffer and pause before prompt
    read -t 0.1 -n 10000 discard </dev/tty 2>/dev/null || true
    sleep 0.3
    read -p "Shut down now? [y/N] " -n 1 -r </dev/tty
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        exec shutdown -h now
    fi
 fi
--- a/rpi/setup.sh
+++ b/rpi/setup.sh
@@ -0,0 +1,556 @@
 #!/bin/bash
 #
 # Stegasoo Raspberry Pi Setup Script
 # Tested on: Raspberry Pi 4/5 with Raspberry Pi OS (64-bit)
 #
 # Usage:
 #   curl -sSL https://raw.githubusercontent.com/adlee-was-taken/stegasoo/4.1/rpi/setup.sh | bash
 #   # or
 #   wget -qO- https://raw.githubusercontent.com/adlee-was-taken/stegasoo/4.1/rpi/setup.sh | bash
 #
 # What this script does:
 #   1. Installs system dependencies
 #   2. Installs Python 3.12 via pyenv (Pi OS ships with 3.13 which is incompatible)
 #   3. Patches and builds jpegio for ARM
 #   4. Installs Stegasoo with web UI
 #   5. Creates systemd service for auto-start
 #   6. Enables the service
 #
 set -e
 # Colors for output
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 BLUE='\033[0;34m'
 CYAN='\033[0;36m'
 GRAY='\033[0;90m'
 BOLD='\033[1m'
 NC='\033[0m' # No Color
 # Show help
 show_help() {
    echo "Stegasoo Raspberry Pi Setup Script"
    echo ""
    echo "Usage: $0 [options]"
    echo ""
    echo "Options:"
    echo "  -h, --help    Show this help message"
    echo ""
    echo "Configuration:"
    echo "  Config files are loaded in order (later overrides earlier):"
    echo "    1. /etc/stegasoo.conf"
    echo "    2. ~/.config/stegasoo/stegasoo.conf"
    echo "    3. Environment variables"
    echo ""
    echo "  Available variables:"
    echo "    INSTALL_DIR       Install location (default: /opt/stegasoo)"
    echo "    PYTHON_VERSION    Python version (default: 3.12)"
    echo "    STEGASOO_REPO     Git repo URL"
    echo "    STEGASOO_BRANCH   Git branch (default: 4.1)"
    echo ""
    echo "  Example:"
    echo "    export INSTALL_DIR=\"/home/pi/stegasoo\""
    echo "    ./setup.sh"
    echo ""
    exit 0
 }
 # Parse args
 for arg in "$@"; do
    case $arg in
        -h|--help) show_help ;;
    esac
 done
 # Default configuration
 INSTALL_DIR="${INSTALL_DIR:-/opt/stegasoo}"
 PYTHON_VERSION="${PYTHON_VERSION:-3.12}"
 STEGASOO_REPO="${STEGASOO_REPO:-https://github.com/adlee-was-taken/stegasoo.git}"
 STEGASOO_BRANCH="${STEGASOO_BRANCH:-4.1}"
 JPEGIO_REPO="https://github.com/dwgoon/jpegio.git"
 # Load config files (system, then user - user overrides system)
 for config_file in "/etc/stegasoo.conf" "$HOME/.config/stegasoo/stegasoo.conf"; do
    if [ -f "$config_file" ]; then
        # shellcheck source=/dev/null
        source "$config_file"
    fi
 done
 clear
 echo ""
 echo -e "\033[38;5;93m══════════════\033[38;5;99m══════════════\033[38;5;105m══════════════\033[38;5;117m══════════════\033[0m"
 echo -e "${GRAY} · .  · .  *  · .  *  · .  *  · .  *  · .  *  · .  ·${NC}"
 echo -e "\033[38;5;220m    ___  _____  ___    ___    _    ___    ___    ___\033[0m"
 echo -e "\033[38;5;220m   / __||_   _|| __|  / __|  /_\\\\  / __|  / _ \\\\  / _ \\\\\033[0m"
 echo -e "\033[38;5;220m   \\\\__ \\\\  | |  | _|  | (_ | / _ \\\\ \\\\__ \\\\ | (_) || (_) |\033[0m"
 echo -e "\033[38;5;220m   |___/  |_|  |___|  \\___|/_/ \\_\\\\|___/  \\\\___/  \\\\___/\033[0m"
 echo -e "${GRAY} · .  · .  *  · .  *  · .  *  · .  *  · .  *  · .  ·${NC}"
 echo -e "\033[38;5;93m══════════════\033[38;5;99m══════════════\033[38;5;105m══════════════\033[38;5;117m══════════════\033[0m"
 echo -e "\033[1;37m                   Raspberry Pi Setup\033[0m"
 echo -e "\033[38;5;93m══════════════\033[38;5;99m══════════════\033[38;5;105m══════════════\033[38;5;117m══════════════\033[0m"
 echo ""
 echo "  This will install Stegasoo with full DCT support"
 echo "  Estimated time: 15-20 minutes on Pi 5"
 echo ""
 # Check if running on ARM
 ARCH=$(uname -m)
 if [[ "$ARCH" != "aarch64" && "$ARCH" != "arm64" ]]; then
    echo -e "${RED}Error: This script is for ARM64 systems (Raspberry Pi).${NC}"
    echo "Detected architecture: $ARCH"
    exit 1
 fi
 # Check available memory
 TOTAL_MEM=$(free -m | awk '/^Mem:/{print $2}')
 if [ "$TOTAL_MEM" -lt 2000 ]; then
    echo -e "${YELLOW}Warning: Less than 2GB RAM detected ($TOTAL_MEM MB).${NC}"
    echo "Stegasoo Web UI requires ~768MB for Argon2 operations."
    echo "Consider using a Pi with more RAM for best results."
    read -p "Continue anyway? [y/N] " -n 1 -r
    echo
    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
        exit 1
    fi
 fi
 # Create /opt/stegasoo with proper permissions
 echo -e "${GREEN}[1/12]${NC} Setting up install directory..."
 if [ ! -d "$INSTALL_DIR" ]; then
    sudo mkdir -p "$INSTALL_DIR"
    sudo chown "$USER:$USER" "$INSTALL_DIR"
    echo "  Created $INSTALL_DIR"
 else
    # Ensure current user owns it
    sudo chown "$USER:$USER" "$INSTALL_DIR"
    echo "  $INSTALL_DIR exists, updated ownership"
 fi
 echo -e "${GREEN}[2/12]${NC} Installing system dependencies..."
 sudo apt-get update
 sudo apt-get install -y \
    build-essential \
    git \
    curl \
    libssl-dev \
    zlib1g-dev \
    libbz2-dev \
    libreadline-dev \
    libsqlite3-dev \
    libncursesw5-dev \
    xz-utils \
    tk-dev \
    libxml2-dev \
    libxmlsec1-dev \
    libffi-dev \
    liblzma-dev \
    libzbar0 \
    libjpeg-dev \
    python3-dev \
    btop
 echo -e "${GREEN}[3/12]${NC} Installing gum (TUI toolkit)..."
 # Add Charm repo for gum
 if ! command -v gum &>/dev/null; then
    sudo mkdir -p /etc/apt/keyrings
    curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
    echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
    sudo apt-get update
    sudo apt-get install -y gum
 else
    echo "  gum already installed"
 fi
 echo -e "${GREEN}[4/12]${NC} Installing pyenv and Python $PYTHON_VERSION..."
 # Install pyenv if not present
 if [ ! -d "$HOME/.pyenv" ]; then
    curl https://pyenv.run | bash
    # Add pyenv to current shell
    export PYENV_ROOT="$HOME/.pyenv"
    export PATH="$PYENV_ROOT/bin:$PATH"
    eval "$(pyenv init -)"
    # Add to .bashrc if not already there
    if ! grep -q 'PYENV_ROOT' ~/.bashrc; then
        echo '' >> ~/.bashrc
        echo '# pyenv' >> ~/.bashrc
        echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
        echo '[[ -d $PYENV_ROOT/bin ]] && export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
        echo 'eval "$(pyenv init - bash)"' >> ~/.bashrc
    fi
 else
    echo "pyenv already installed, skipping..."
    export PYENV_ROOT="$HOME/.pyenv"
    export PATH="$PYENV_ROOT/bin:$PATH"
    eval "$(pyenv init -)"
 fi
 # Install Python 3.12 if not present
 if ! pyenv versions | grep -q "$PYTHON_VERSION"; then
    echo "Building Python $PYTHON_VERSION (this takes ~10 minutes)..."
    pyenv install $PYTHON_VERSION
 fi
 pyenv global $PYTHON_VERSION
 # Verify Python version
 INSTALLED_PY=$(python --version 2>&1 | cut -d' ' -f2 | cut -d'.' -f1,2)
 if [ "$INSTALLED_PY" != "$PYTHON_VERSION" ]; then
    echo -e "${RED}Error: Python $PYTHON_VERSION not active. Got: $INSTALLED_PY${NC}"
    exit 1
 fi
 echo -e "${GREEN}[5/12]${NC} Cloning Stegasoo..."
 # Clone Stegasoo first (needed for jpegio patch script)
 if [ -d "$INSTALL_DIR/.git" ]; then
    echo "  Stegasoo directory exists, updating..."
    cd "$INSTALL_DIR"
    git fetch origin
    git checkout "$STEGASOO_BRANCH"
    git pull origin "$STEGASOO_BRANCH"
 else
    git clone -b "$STEGASOO_BRANCH" "$STEGASOO_REPO" "$INSTALL_DIR"
    cd "$INSTALL_DIR"
 fi
 echo -e "${GREEN}[6/12]${NC} Creating Python virtual environment..."
 # Create venv with pyenv Python (not system Python)
 # Use pyenv which to get actual path (handles 3.12 -> 3.12.12 mapping)
 PYENV_PYTHON=$(pyenv which python)
 echo "  Using Python: $PYENV_PYTHON"
 if [ ! -d "venv" ]; then
    "$PYENV_PYTHON" -m venv venv
 fi
 source venv/bin/activate
 # Verify we're using the right Python
 VENV_PY=$(python --version 2>&1 | cut -d' ' -f2 | cut -d'.' -f1,2)
 echo "  venv Python: $VENV_PY"
 echo -e "${GREEN}[7/12]${NC} Building jpegio for ARM..."
 # Clone jpegio
 JPEGIO_DIR="/tmp/jpegio-build"
 rm -rf "$JPEGIO_DIR"
 git clone "$JPEGIO_REPO" "$JPEGIO_DIR"
 # Apply ARM64 patch
 if [ -f "$INSTALL_DIR/rpi/patches/jpegio/apply-patch.sh" ]; then
    bash "$INSTALL_DIR/rpi/patches/jpegio/apply-patch.sh" "$JPEGIO_DIR"
 else
    echo "  Applying inline ARM64 patch..."
    sed -i "s/cargs.append('-m64')/pass  # ARM64 fix/g" "$JPEGIO_DIR/setup.py"
 fi
 cd "$JPEGIO_DIR"
 # Build jpegio into venv
 pip install --upgrade pip setuptools wheel cython numpy
 pip install .
 cd "$INSTALL_DIR"
 rm -rf "$JPEGIO_DIR"
 echo -e "${GREEN}[8/12]${NC} Installing Stegasoo..."
 # Install dependencies (jpegio already in venv, won't re-download)
 pip install -e ".[web]"
 echo -e "${GREEN}[9/12]${NC} Creating systemd service..."
 # Create systemd service file
 sudo tee /etc/systemd/system/stegasoo.service > /dev/null <<EOF
 [Unit]
 Description=Stegasoo Web UI
 After=network.target
 [Service]
 Type=simple
 User=$USER
 WorkingDirectory=$INSTALL_DIR/frontends/web
 Environment="PATH=$INSTALL_DIR/venv/bin:/usr/bin"
 Environment="STEGASOO_AUTH_ENABLED=true"
 Environment="STEGASOO_HTTPS_ENABLED=false"
 Environment="STEGASOO_PORT=5000"
 ExecStart=$INSTALL_DIR/venv/bin/python app.py
 Restart=on-failure
 RestartSec=5
 [Install]
 WantedBy=multi-user.target
 EOF
 echo -e "${GREEN}[10/12]${NC} Enabling service..."
 sudo systemctl daemon-reload
 sudo systemctl enable stegasoo.service
 echo -e "${GREEN}[11/12]${NC} Setting up user environment..."
 # Add stegasoo venv and rpi scripts to PATH for all users
 sudo tee /etc/profile.d/stegasoo-path.sh > /dev/null <<'PATHEOF'
 # Stegasoo CLI and scripts
 if [ -d /opt/stegasoo/venv/bin ]; then
    export PATH="/opt/stegasoo/venv/bin:$PATH"
 fi
 if [ -d /opt/stegasoo/rpi ]; then
    export PATH="/opt/stegasoo/rpi:$PATH"
 fi
 PATHEOF
 sudo chmod 644 /etc/profile.d/stegasoo-path.sh
 echo "  Added stegasoo to PATH"
 # Install custom bashrc if not already customized
 if [ -f "$INSTALL_DIR/rpi/skel/.bashrc" ]; then
    if ! grep -q "Stegasoo Pi" ~/.bashrc 2>/dev/null; then
        cp "$INSTALL_DIR/rpi/skel/.bashrc" ~/.bashrc
        source ~/.bashrc 2>/dev/null || true
        echo "  Installed custom .bashrc"
    else
        echo "  Custom .bashrc already installed"
    fi
 fi
 echo -e "${GREEN}[12/12]${NC} Setting up login banner..."
 # Create dynamic MOTD script
 sudo tee /etc/profile.d/stegasoo-motd.sh > /dev/null <<'MOTDEOF'
 # Stegasoo login banner
 if systemctl is-active --quiet stegasoo 2>/dev/null; then
    PI_IP=$(hostname -I | awk '{print $1}')
    # Check if HTTPS and port 443 are configured
    if systemctl show stegasoo -p Environment 2>/dev/null | grep -q "STEGASOO_HTTPS_ENABLED=true"; then
        # Check for port 443 redirect (iptables-restore service means 443 is configured)
        if systemctl is-enabled --quiet iptables-restore 2>/dev/null; then
            STEGASOO_URL="https://$PI_IP"
        else
            STEGASOO_URL="https://$PI_IP:5000"
        fi
    else
        STEGASOO_URL="http://$PI_IP:5000"
    fi
    echo ""
    echo -e "\033[38;5;93m══════════════\033[38;5;99m══════════════\033[38;5;105m══════════════\033[38;5;117m══════════════\033[0m"
    echo -e "\033[0;90m · .  · .  *  · .  *  · .  *  · .  *  · .  *  · .  ·\033[0m"
    echo -e "\033[38;5;220m    ___  _____  ___    ___    _    ___    ___    ___\033[0m"
    echo -e "\033[38;5;220m   / __||_   _|| __|  / __|  /_\\  / __|  / _ \\  / _ \\\\\033[0m"
    echo -e "\033[38;5;220m   \\__ \\  | |  | _|  | (_ | / _ \\ \\__ \\ | (_) || (_) |\033[0m"
    echo -e "\033[38;5;220m   |___/  |_|  |___|  \\___//_/ \\_\\|___/  \\___/  \\___/\033[0m"
    echo -e "\033[0;90m · .  · .  *  · .  *  · .  *  · .  *  · .  *  · .  ·\033[0m"
    echo -e "\033[38;5;93m══════════════\033[38;5;99m══════════════\033[38;5;105m══════════════\033[38;5;117m══════════════\033[0m"
    echo -e " \033[0;32m●\033[0m Stegasoo is running"
    echo -e "   \033[0;33m$STEGASOO_URL\033[0m"
    # Show CPU stats if overclocked
    if grep -qE "^(arm_freq|over_voltage)" /boot/firmware/config.txt 2>/dev/null || \
       grep -qE "^(arm_freq|over_voltage)" /boot/config.txt 2>/dev/null; then
        CPU_FREQ=$(vcgencmd measure_clock arm 2>/dev/null | cut -d= -f2)
        CPU_TEMP=$(vcgencmd measure_temp 2>/dev/null | cut -d= -f2)
        if [ -n "$CPU_FREQ" ] && [ -n "$CPU_TEMP" ]; then
            CPU_MHZ=$((CPU_FREQ / 1000000))
            echo -e "   \033[0;35m⚡\033[0m ${CPU_MHZ} MHz  \033[0;35m🌡\033[0m ${CPU_TEMP}"
        fi
    fi
    echo ""
 else
    echo ""
    echo -e " \033[0;31m●\033[0m Stegasoo is not running"
    echo -e "   Start with: sudo systemctl start stegasoo"
    echo ""
 fi
 MOTDEOF
 sudo chmod 644 /etc/profile.d/stegasoo-motd.sh
 echo "  Created login banner"
 echo ""
 echo -e "${BOLD}Installation Complete!${NC}"
 echo -e "${BLUE}-------------------------------------------------------${NC}"
 echo ""
 echo -e "Stegasoo installed to: ${YELLOW}$INSTALL_DIR${NC}"
 echo ""
 # =============================================================================
 # Interactive Configuration
 # =============================================================================
 echo -e "${BOLD}Configuration${NC}"
 echo -e "${BLUE}-------------------------------------------------------${NC}"
 echo ""
 # Track configuration choices
 ENABLE_HTTPS="false"
 USE_PORT_443="false"
 CHANNEL_KEY=""
 # --- HTTPS Configuration ---
 echo -e "${GREEN}HTTPS Configuration${NC}"
 echo "  HTTPS encrypts traffic with a self-signed certificate."
 echo "  (Browser will show a security warning - this is normal for self-signed certs)"
 echo ""
 read -p "Enable HTTPS? [y/N] " -n 1 -r
 echo
 if [[ $REPLY =~ ^[Yy]$ ]]; then
    ENABLE_HTTPS="true"
    echo -e "  ${GREEN}✓${NC} HTTPS will be enabled"
    # --- Port 443 Configuration ---
    echo ""
    echo -e "${GREEN}Port Configuration${NC}"
    echo "  Standard HTTPS port is 443 (no port needed in URL)."
    echo "  This requires iptables to redirect 443 → 5000."
    echo ""
    read -p "Use standard port 443? [y/N] " -n 1 -r
    echo
    if [[ $REPLY =~ ^[Yy]$ ]]; then
        USE_PORT_443="true"
        echo -e "  ${GREEN}✓${NC} Port 443 will be configured"
    else
        echo -e "  ${YELLOW}→${NC} Using default port 5000"
    fi
 else
    echo -e "  ${YELLOW}→${NC} Using HTTP (unencrypted)"
 fi
 # --- Channel Key Configuration ---
 echo ""
 echo -e "${GREEN}Channel Key Configuration${NC}"
 echo "  A channel key creates a private encoding channel."
 echo "  Only users with the same key can decode each other's images."
 echo ""
 read -p "Generate a private channel key? [y/N] " -n 1 -r
 echo
 if [[ $REPLY =~ ^[Yy]$ ]]; then
    # Generate channel key using the CLI
    CHANNEL_KEY=$($INSTALL_DIR/venv/bin/python -c "from stegasoo.channel import generate_channel_key; print(generate_channel_key())")
    echo -e "  ${GREEN}✓${NC} Channel key generated: ${YELLOW}$CHANNEL_KEY${NC}"
    echo ""
    echo -e "  ${RED}IMPORTANT: Save this key!${NC} You'll need to share it with anyone"
    echo "  who should be able to decode your images."
 else
    echo -e "  ${YELLOW}→${NC} Using public mode (no channel isolation)"
 fi
 # =============================================================================
 # Apply Configuration
 # =============================================================================
 echo ""
 echo -e "${BLUE}Applying configuration...${NC}"
 # Update systemd service with configuration
 sudo tee /etc/systemd/system/stegasoo.service > /dev/null <<EOF
 [Unit]
 Description=Stegasoo Web UI
 After=network.target
 [Service]
 Type=simple
 User=$USER
 WorkingDirectory=$INSTALL_DIR/frontends/web
 Environment="PATH=$INSTALL_DIR/venv/bin:/usr/bin"
 Environment="STEGASOO_AUTH_ENABLED=true"
 Environment="STEGASOO_HTTPS_ENABLED=$ENABLE_HTTPS"
 Environment="STEGASOO_PORT=5000"
 Environment="STEGASOO_CHANNEL_KEY=$CHANNEL_KEY"
 ExecStart=$INSTALL_DIR/venv/bin/python app.py
 Restart=on-failure
 RestartSec=5
 [Install]
 WantedBy=multi-user.target
 EOF
 # Setup port 443 redirect if requested
 if [ "$USE_PORT_443" = "true" ]; then
    echo "  Setting up port 443 redirect..."
    # Install iptables if needed
    if ! command -v iptables &> /dev/null; then
        sudo apt-get install -y iptables
    fi
    # Add redirect rule
    sudo iptables -t nat -A PREROUTING -p tcp --dport 443 -j REDIRECT --to-port 5000
    sudo sh -c 'iptables-save > /etc/iptables.rules'
    # Create systemd service to restore rules on boot
    sudo tee /etc/systemd/system/iptables-restore.service > /dev/null <<EOF
 [Unit]
 Description=Restore iptables rules
 Before=network-pre.target
 [Service]
 Type=oneshot
 ExecStart=/sbin/iptables-restore /etc/iptables.rules
 [Install]
 WantedBy=multi-user.target
 EOF
    sudo systemctl enable iptables-restore.service
    echo -e "  ${GREEN}✓${NC} Port 443 redirect configured"
 fi
 sudo systemctl daemon-reload
 # =============================================================================
 # Final Summary
 # =============================================================================
 echo ""
 echo -e "${BOLD}Setup Complete!${NC}"
 echo -e "${BLUE}-------------------------------------------------------${NC}"
 echo ""
 PI_IP=$(hostname -I | awk '{print $1}')
 echo -e "${GREEN}Create your admin account:${NC}"
 if [ "$ENABLE_HTTPS" = "true" ]; then
    if [ "$USE_PORT_443" = "true" ]; then
        echo -e "  ${YELLOW}https://$PI_IP/setup${NC}"
    else
        echo -e "  ${YELLOW}https://$PI_IP:5000/setup${NC}"
    fi
 else
    echo -e "  ${YELLOW}http://$PI_IP:5000/setup${NC}"
 fi
 echo ""
 if [ -n "$CHANNEL_KEY" ]; then
    echo -e "${GREEN}Channel Key:${NC}"
    echo -e "  ${YELLOW}$CHANNEL_KEY${NC}"
    echo ""
 fi
 echo -e "${GREEN}Commands:${NC}"
 echo "  Start:   sudo systemctl start stegasoo"
 echo "  Stop:    sudo systemctl stop stegasoo"
 echo "  Status:  sudo systemctl status stegasoo"
 echo "  Logs:    journalctl -u stegasoo -f"
 echo ""
 # Offer to start now
 read -p "Start Stegasoo now? [Y/n] " -n 1 -r
 echo
 if [[ ! $REPLY =~ ^[Nn]$ ]]; then
    sudo systemctl start stegasoo
    sleep 2
    if systemctl is-active --quiet stegasoo; then
        echo -e "${GREEN}✓ Stegasoo is running!${NC}"
        if [ "$ENABLE_HTTPS" = "true" ]; then
            if [ "$USE_PORT_443" = "true" ]; then
                echo -e "  Create admin: ${YELLOW}https://$PI_IP/setup${NC}"
            else
                echo -e "  Create admin: ${YELLOW}https://$PI_IP:5000/setup${NC}"
            fi
        else
            echo -e "  Create admin: ${YELLOW}http://$PI_IP:5000/setup${NC}"
        fi
    else
        echo -e "${RED}✗ Failed to start. Check logs:${NC} journalctl -u stegasoo -f"
    fi
 fi
--- a/rpi/skel/.bashrc
+++ b/rpi/skel/.bashrc
@@ -0,0 +1,214 @@
 # ============================================================================
 # Stegasoo Pi - Bash Configuration
 # ============================================================================
 # If not running interactively, don't do anything
 case $- in
    *i*) ;;
      *) return;;
 esac
 # ============================================================================
 # History
 # ============================================================================
 HISTCONTROL=ignoreboth
 HISTSIZE=5000
 HISTFILESIZE=10000
 shopt -s histappend
 # ============================================================================
 # Shell Options
 # ============================================================================
 shopt -s checkwinsize
 shopt -s globstar 2>/dev/null
 shopt -s cdspell 2>/dev/null
 # ============================================================================
 # Colors
 # ============================================================================
 # Color definitions
 C_RESET='\[\e[0m\]'
 C_GREY='\[\e[38;5;241m\]'
 C_GREEN='\[\e[38;5;118m\]'
 C_YELLOW='\[\e[38;5;179m\]'
 C_BLUE='\[\e[38;5;69m\]'
 C_RED='\[\e[38;5;196m\]'
 C_BOLD='\[\e[1m\]'
 # Enable color support
 if [ -x /usr/bin/dircolors ]; then
    test -r ~/.dircolors && eval "$(dircolors -b ~/.dircolors)" || eval "$(dircolors -b)"
    alias ls='ls --color=auto'
    alias grep='grep --color=auto'
    alias fgrep='fgrep --color=auto'
    alias egrep='egrep --color=auto'
 fi
 # ============================================================================
 # Prompt
 # ============================================================================
 # Git branch in prompt (if git installed)
 _git_branch() {
    git branch 2>/dev/null | sed -e '/^[^*]/d' -e 's/* \(.*\)/ \xe2\x8e\x87 \1/'
 }
 # Two-line prompt similar to zsh theme
 # ┌｢user@host｣ ｢path｣ ｢git｣
 # └$
 _build_prompt() {
    local git_info="$(_git_branch)"
    if [ -n "$git_info" ]; then
        git_info="${C_GREEN}${git_info}${C_GREY}"
    fi
    PS1="${C_GREY}┌｢${C_GREEN}\u@\h${C_GREY}｣ ｢${C_YELLOW}\w${C_GREY}${git_info}｣\n${C_GREY}└${C_BOLD}${C_BLUE}\$ ${C_RESET}"
 }
 PROMPT_COMMAND='_build_prompt'
 # ============================================================================
 # Navigation
 # ============================================================================
 alias ..='cd ..'
 alias ...='cd ../..'
 alias ....='cd ../../..'
 alias ~='cd ~'
 # ============================================================================
 # Listing
 # ============================================================================
 alias ll='ls -lah'
 alias la='ls -A'
 alias l='ls -CF'
 alias lt='ls -lahtr'
 # ============================================================================
 # Safety
 # ============================================================================
 alias rm='rm -i'
 alias cp='cp -i'
 alias mv='mv -i'
 # ============================================================================
 # Shortcuts
 # ============================================================================
 alias h='history'
 alias c='clear'
 alias q='exit'
 alias reload='source ~/.bashrc'
 # ============================================================================
 # System
 # ============================================================================
 alias myip='curl -s ifconfig.me'
 alias ports='netstat -tulanp 2>/dev/null || ss -tulanp'
 alias df='df -h'
 alias du='du -h'
 alias free='free -h'
 alias temp='vcgencmd measure_temp 2>/dev/null || sensors 2>/dev/null | grep -i temp || echo "No temp sensor"'
 # ============================================================================
 # Stegasoo
 # ============================================================================
 alias steg='stegasoo'
 alias steglog='journalctl -u stegasoo -f'
 alias stegstatus='systemctl status stegasoo'
 alias stegrestart='sudo systemctl restart stegasoo'
 alias stegstop='sudo systemctl stop stegasoo'
 alias stegstart='sudo systemctl start stegasoo'
 # Quick access to stegasoo directories
 alias cdsteg='cd /opt/stegasoo'
 alias cdweb='cd /opt/stegasoo/frontends/web'
 # ============================================================================
 # Git (if available)
 # ============================================================================
 alias g='git'
 alias gs='git status'
 alias ga='git add'
 alias gc='git commit'
 alias gp='git push'
 alias gl='git pull'
 alias gd='git diff'
 alias gco='git checkout'
 alias glog='git log --oneline --graph --decorate -10'
 # ============================================================================
 # Functions
 # ============================================================================
 # Create directory and cd into it
 mkcd() { mkdir -p "$1" && cd "$1"; }
 # Find files by name
 ff() { find . -type f -iname "*$1*" 2>/dev/null; }
 # Find directories by name
 fdir() { find . -type d -iname "*$1*" 2>/dev/null; }
 # Quick backup
 backup() { cp "$1" "$1.backup-$(date +%Y%m%d-%H%M%S)"; }
 # Extract archives
 extract() {
    if [ ! -f "$1" ]; then
        echo "'$1' is not a valid file"
        return 1
    fi
    case "$1" in
        *.tar.bz2) tar xjf "$1" ;;
        *.tar.gz)  tar xzf "$1" ;;
        *.tar.xz)  tar xJf "$1" ;;
        *.bz2)     bunzip2 "$1" ;;
        *.gz)      gunzip "$1" ;;
        *.tar)     tar xf "$1" ;;
        *.tbz2)    tar xjf "$1" ;;
        *.tgz)     tar xzf "$1" ;;
        *.zip)     unzip "$1" ;;
        *.Z)       uncompress "$1" ;;
        *.7z)      7z x "$1" ;;
        *.zst)     zstd -d "$1" ;;
        *)         echo "'$1' cannot be extracted" ;;
    esac
 }
 # Show system info
 sysinfo() {
    echo -e "\e[1;32mHostname:\e[0m $(hostname)"
    echo -e "\e[1;32mUptime:\e[0m $(uptime -p)"
    echo -e "\e[1;32mMemory:\e[0m $(free -h | awk '/^Mem:/ {print $3 "/" $2}')"
    echo -e "\e[1;32mDisk:\e[0m $(df -h / | awk 'NR==2 {print $3 "/" $2 " (" $5 ")"}')"
    echo -e "\e[1;32mTemp:\e[0m $(vcgencmd measure_temp 2>/dev/null | cut -d= -f2 || echo 'N/A')"
    echo -e "\e[1;32mIP:\e[0m $(hostname -I | awk '{print $1}')"
 }
 # ============================================================================
 # Completion
 # ============================================================================
 if ! shopt -oq posix; then
    if [ -f /usr/share/bash-completion/bash_completion ]; then
        . /usr/share/bash-completion/bash_completion
    elif [ -f /etc/bash_completion ]; then
        . /etc/bash_completion
    fi
 fi
 # ============================================================================
 # Path
 # ============================================================================
 export PATH="$HOME/.local/bin:$PATH"
--- a/rpi/stegasoo-wizard.sh
+++ b/rpi/stegasoo-wizard.sh
@@ -0,0 +1,17 @@
 #!/bin/bash
 # Stegasoo First Boot Wizard Trigger
 # This file goes in /etc/profile.d/ and runs the wizard on first login
 if [ -f /etc/stegasoo-first-boot ]; then
    # Find the wizard script (check /opt first, then home dirs)
    WIZARD=""
    if [ -f /opt/stegasoo/rpi/first-boot-wizard.sh ]; then
        WIZARD="/opt/stegasoo/rpi/first-boot-wizard.sh"
    else
        WIZARD=$(ls /home/*/stegasoo/rpi/first-boot-wizard.sh 2>/dev/null | head -1)
    fi
    if [ -n "$WIZARD" ]; then
        bash "$WIZARD"
    fi
 fi
--- a/rpi/stegasoo.conf.example
+++ b/rpi/stegasoo.conf.example
@@ -0,0 +1,30 @@
 # Stegasoo Raspberry Pi Configuration
 # Copy this file to /etc/stegasoo.conf or ~/.config/stegasoo/stegasoo.conf
 #
 # You can also override these by exporting environment variables:
 #   export STEGASOO_INSTALL_DIR="/custom/path"
 #   ./setup.sh
 # Installation directory (default: /opt/stegasoo)
 #INSTALL_DIR="/opt/stegasoo"
 # Python version to install via pyenv (default: 3.12)
 #PYTHON_VERSION="3.12"
 # Git repository URL
 #STEGASOO_REPO="https://github.com/adlee-was-taken/stegasoo.git"
 # Git branch to checkout (default: 4.1)
 #STEGASOO_BRANCH="4.1"
 # Web UI port (default: 5000)
 #STEGASOO_PORT="5000"
 # Enable HTTPS (default: false, configured via wizard)
 #STEGASOO_HTTPS_ENABLED="false"
 # Enable authentication (default: true)
 #STEGASOO_AUTH_ENABLED="true"
 # Channel key for private channels (default: none)
 #STEGASOO_CHANNEL_KEY=""
--- a/scripts/validate-release.sh
+++ b/scripts/validate-release.sh
@@ -0,0 +1,307 @@
 #!/bin/bash
 # =============================================================================
 # Stegasoo Release Validation Script
 # =============================================================================
 # Automated pre-release validation to catch issues before tagging a release.
 #
 # Usage:
 #   ./scripts/validate-release.sh              # Local validation only
 #   ./scripts/validate-release.sh --pi         # Include Pi smoke test
 #   PI_IP=192.168.0.4 ./scripts/validate-release.sh --pi
 #
 # Exit codes:
 #   0 = All tests passed
 #   1 = One or more tests failed
 # =============================================================================
 # Don't use set -e as we need to handle test failures gracefully
 # Colors
 RED='\033[0;31m'
 GREEN='\033[0;32m'
 YELLOW='\033[0;33m'
 CYAN='\033[0;36m'
 NC='\033[0m'
 # Default Pi IP (can be overridden via environment)
 PI_IP="${PI_IP:-192.168.0.4}"
 PI_USER="${PI_USER:-alee}"
 INCLUDE_PI=false
 INCLUDE_DOCKER=true
 # Parse arguments
 while [[ $# -gt 0 ]]; do
    case $1 in
        --pi)
            INCLUDE_PI=true
            shift
            ;;
        --no-docker)
            INCLUDE_DOCKER=false
            shift
            ;;
        --help|-h)
            echo "Usage: $0 [--pi] [--no-docker]"
            echo ""
            echo "Options:"
            echo "  --pi         Include Pi smoke test (requires SSH access)"
            echo "  --no-docker  Skip Docker build/test"
            echo ""
            echo "Environment:"
            echo "  PI_IP        Pi IP address (default: 192.168.0.4)"
            echo "  PI_USER      Pi SSH user (default: alee)"
            exit 0
            ;;
        *)
            echo "Unknown option: $1"
            exit 1
            ;;
    esac
 done
 # Track results
 TESTS_RUN=0
 TESTS_PASSED=0
 TESTS_FAILED=0
 FAILED_TESTS=()
 # Helper functions
 pass() {
    echo -e "${GREEN}[PASS]${NC} $1"
    ((TESTS_PASSED++))
    ((TESTS_RUN++))
 }
 fail() {
    echo -e "${RED}[FAIL]${NC} $1"
    FAILED_TESTS+=("$1")
    ((TESTS_FAILED++))
    ((TESTS_RUN++))
 }
 skip() {
    echo -e "${YELLOW}[SKIP]${NC} $1"
 }
 section() {
    echo ""
    echo -e "${CYAN}━━━ $1 ━━━${NC}"
 }
 # =============================================================================
 # Header
 # =============================================================================
 echo -e "${CYAN}╔═══════════════════════════════════════════════════════════════╗${NC}"
 echo -e "${CYAN}║         Stegasoo Release Validation                           ║${NC}"
 echo -e "${CYAN}╚═══════════════════════════════════════════════════════════════╝${NC}"
 echo ""
 # Get version from pyproject.toml
 VERSION=$(grep '^version = ' pyproject.toml | head -1 | cut -d'"' -f2)
 echo -e "Version: ${YELLOW}${VERSION}${NC}"
 echo -e "Branch:  ${YELLOW}$(git branch --show-current)${NC}"
 echo ""
 # =============================================================================
 # 1. Code Quality Checks
 # =============================================================================
 section "Code Quality"
 # Ruff linting
 if command -v ./venv/bin/ruff &> /dev/null; then
    echo -n "Running ruff check... "
    if ./venv/bin/ruff check src/ frontends/ --quiet 2>/dev/null; then
        pass "Ruff linting"
    else
        fail "Ruff linting (run: ./venv/bin/ruff check src/ frontends/)"
    fi
 else
    skip "Ruff not installed"
 fi
 # =============================================================================
 # 2. Unit Tests (if they exist)
 # =============================================================================
 section "Unit Tests"
 if ls tests/test_*.py 1> /dev/null 2>&1; then
    echo -n "Running pytest... "
    if ./venv/bin/pytest tests/ -q --tb=no 2>/dev/null; then
        pass "Pytest unit tests"
    else
        fail "Pytest unit tests"
    fi
 else
    skip "No unit tests found (tests/test_*.py)"
 fi
 # =============================================================================
 # 3. Import Tests
 # =============================================================================
 section "Import Tests"
 # Test core library import
 echo -n "Testing stegasoo import... "
 if ./venv/bin/python -c "from stegasoo import encode, decode; print('OK')" 2>/dev/null | grep -q OK; then
    pass "Core library import"
 else
    fail "Core library import"
 fi
 # Test DCT support
 echo -n "Testing DCT support... "
 if ./venv/bin/python -c "from stegasoo import has_dct_support; assert has_dct_support(), 'No DCT'; print('OK')" 2>/dev/null | grep -q OK; then
    pass "DCT support available"
 else
    fail "DCT support (scipy/jpegio missing?)"
 fi
 # Test CLI import
 echo -n "Testing CLI import... "
 if ./venv/bin/python -c "from stegasoo.cli import main; print('OK')" 2>/dev/null | grep -q OK; then
    pass "CLI module import"
 else
    fail "CLI module import"
 fi
 # =============================================================================
 # 4. Encode/Decode Sanity Test
 # =============================================================================
 section "Encode/Decode Test"
 echo -n "Running encode/decode sanity check... "
 SANITY_RESULT=$(./venv/bin/python << 'EOF' 2>&1
 import sys
 sys.path.insert(0, 'src')
 from stegasoo import encode, decode
 with open('test_data/carrier.jpg', 'rb') as f:
    carrier = f.read()
 with open('test_data/ref.jpg', 'rb') as f:
    ref = f.read()
 # LSB test
 result = encode(message="sanity test", reference_photo=ref, carrier_image=carrier,
                passphrase="test", pin="123456", embed_mode="lsb")
 decoded = decode(stego_image=result.stego_image, reference_photo=ref,
                 passphrase="test", pin="123456", embed_mode="lsb")
 assert decoded.message == "sanity test", f"LSB mismatch: {decoded.message}"
 # DCT test
 result = encode(message="dct sanity", reference_photo=ref, carrier_image=carrier,
                passphrase="dct", pin="654321", embed_mode="dct")
 decoded = decode(stego_image=result.stego_image, reference_photo=ref,
                 passphrase="dct", pin="654321", embed_mode="dct")
 assert decoded.message == "dct sanity", f"DCT mismatch: {decoded.message}"
 print("OK")
 EOF
 )
 if echo "$SANITY_RESULT" | grep -q "OK"; then
    pass "Encode/decode sanity (LSB + DCT)"
 else
    fail "Encode/decode sanity: $SANITY_RESULT"
 fi
 # =============================================================================
 # 5. Docker Build & Test (optional)
 # =============================================================================
 if $INCLUDE_DOCKER; then
    section "Docker"
    if command -v docker &> /dev/null || command -v sudo &> /dev/null; then
        DOCKER_CMD="docker"
        if ! docker info &>/dev/null 2>&1; then
            DOCKER_CMD="sudo docker"
        fi
        echo -n "Building Docker image... "
        if $DOCKER_CMD build -t stegasoo:validate -q . >/dev/null 2>&1; then
            pass "Docker build"
            # Test container starts
            echo -n "Testing container startup... "
            CONTAINER_ID=$($DOCKER_CMD run -d -p 15000:5000 stegasoo:validate 2>/dev/null)
            sleep 3
            if curl -s -o /dev/null -w "%{http_code}" http://localhost:15000/ 2>/dev/null | grep -qE "200|302"; then
                pass "Container responds to HTTP"
            else
                fail "Container HTTP response"
            fi
            # Cleanup
            $DOCKER_CMD stop "$CONTAINER_ID" >/dev/null 2>&1 || true
            $DOCKER_CMD rm "$CONTAINER_ID" >/dev/null 2>&1 || true
        else
            fail "Docker build"
        fi
        # Cleanup test image
        $DOCKER_CMD rmi stegasoo:validate >/dev/null 2>&1 || true
    else
        skip "Docker not available"
    fi
 else
    skip "Docker tests (use --docker to enable)"
 fi
 # =============================================================================
 # 6. Pi Smoke Test (optional)
 # =============================================================================
 if $INCLUDE_PI; then
    section "Pi Smoke Test"
    echo -n "Testing SSH connectivity to $PI_USER@$PI_IP... "
    if ssh -o ConnectTimeout=5 -o BatchMode=yes "$PI_USER@$PI_IP" "echo OK" 2>/dev/null | grep -q OK; then
        pass "SSH connectivity"
        echo -n "Checking stegasoo service status... "
        if ssh "$PI_USER@$PI_IP" "systemctl is-active stegasoo" 2>/dev/null | grep -q active; then
            pass "Stegasoo service running"
            echo -n "Running smoke test on Pi... "
            SMOKE_RESULT=$(ssh "$PI_USER@$PI_IP" "cd /home/$PI_USER/stegasoo && bash tests/smoke-test.sh --quick 2>&1" || echo "FAILED")
            if echo "$SMOKE_RESULT" | grep -qE "All tests passed|PASS"; then
                pass "Pi smoke test"
            else
                fail "Pi smoke test"
            fi
        else
            fail "Stegasoo service not running"
        fi
    else
        fail "SSH connectivity to Pi"
    fi
 else
    skip "Pi smoke test (use --pi to enable)"
 fi
 # =============================================================================
 # Summary
 # =============================================================================
 echo ""
 echo -e "${CYAN}━━━ Summary ━━━${NC}"
 echo ""
 echo -e "Tests run:    ${TESTS_RUN}"
 echo -e "Passed:       ${GREEN}${TESTS_PASSED}${NC}"
 echo -e "Failed:       ${RED}${TESTS_FAILED}${NC}"
 if [ ${#FAILED_TESTS[@]} -gt 0 ]; then
    echo ""
    echo -e "${RED}Failed tests:${NC}"
    for test in "${FAILED_TESTS[@]}"; do
        echo -e "  - $test"
    done
 fi
 echo ""
 if [ $TESTS_FAILED -eq 0 ]; then
    echo -e "${GREEN}✓ All validation checks passed!${NC}"
    echo -e "  Ready to tag release ${VERSION}"
    exit 0
 else
    echo -e "${RED}✗ Validation failed - fix issues before release${NC}"
    exit 1
 fi
--- a/src/stegasoo/COMPLETE_CHANGE_SUMMARY_V3.2.0.md
+++ b/src/stegasoo/COMPLETE_CHANGE_SUMMARY_V3.2.0.md
@@ -1,374 +0,0 @@
 # Stegasoo v3.2.0 - Complete Change Summary
 ## Overview
 This update makes two major breaking changes to Stegasoo:
 1. **Remove date dependency** - Date no longer used in cryptographic operations
 2. **Rename day_phrase → passphrase** - Reflects removal of daily rotation requirement
 ## Version Information
 - **Previous**: v3.1.0 (date-dependent, day_phrase)
 - **Current**: v3.2.0 (date-independent, passphrase)
 - **Format Version**: 3 → 4 (breaking change)
 - **Compatibility**: NOT backward compatible with v3.1.0
 ## Files Modified
 ### Core Files (MUST UPDATE)
 1. **crypto.py** ✅ Updated
   - Removed `date_str` parameter from all functions
   - Renamed `day_phrase` → `passphrase` in all functions
   - Removed date from key derivation material
   - Simplified header format (no date field)
   - Updated error messages
 2. **constants.py** ✅ Updated
   - Version: `__version__ = "3.2.0"`
   - Format: `FORMAT_VERSION = 4`
   - Added passphrase constants:
     - `MIN_PASSPHRASE_WORDS = 3`
     - `MAX_PASSPHRASE_WORDS = 12`
     - `DEFAULT_PASSPHRASE_WORDS = 4` (increased from 3)
     - `RECOMMENDED_PASSPHRASE_WORDS = 4`
   - Kept legacy aliases for transition
 3. **models.py** ✅ Updated
   - `Credentials`: Changed from `phrases: dict` → `passphrase: str`
   - `EncodeInput`: Renamed `day_phrase` → `passphrase`, removed `date_str`
   - `DecodeInput`: Renamed `day_phrase` → `passphrase`
   - `EncodeResult`: Made `date_used` optional (cosmetic only)
   - `DecodeResult`: `date_encoded` always None in v3.2.0
   - `ValidationResult`: Added `warning` field
 4. **validation.py** ✅ Updated
   - Renamed `validate_phrase()` → `validate_passphrase()`
   - Added word count validation with warnings
   - Recommends 4+ words for good security
   - Updated error messages
 ### Files Needing Updates
 5. **__init__.py** - Public API
   - [ ] `encode()`: Remove `date_str`, rename `day_phrase` → `passphrase`
   - [ ] `encode_file()`: Same changes
   - [ ] `encode_bytes()`: Same changes
   - [ ] `decode()`: Remove `date_str`, rename `day_phrase` → `passphrase`
   - [ ] `decode_text()`: Same changes
   - [ ] Update all docstrings
 6. **keygen.py** - Key generation
   - [ ] `generate_day_phrases()` → `generate_passphrases()` or keep with new implementation
   - [ ] `generate_credentials()`: Update to use single passphrase
   - [ ] Update `Credentials` creation
 7. **batch.py** - Batch operations
   - [ ] `BatchCredentials`: Rename `day_phrase` → `passphrase`
   - [ ] Update all batch functions
 8. **cli.py** - Command line
   - [ ] `--phrase` → `--passphrase` (or keep `--phrase` for simplicity)
   - [ ] Update help text
   - [ ] Update credentials dict creation
 9. **steganography.py** - No changes needed
   - Uses keys from crypto module, doesn't directly handle phrases/dates
 10. **dct_steganography.py** - No changes needed
    - Uses keys from crypto module
 ### Optional/Documentation Files
 11. **utils.py** - Keep as-is (organizational functions)
 12. **debug.py** - No changes needed
 13. **exceptions.py** - No changes needed
 14. **compression.py** - No changes needed
 15. **qr_utils.py** - No changes needed
 ## Key Changes Breakdown
 ### 1. Function Signatures
 **Before (v3.1.0):**
 ```python
 def derive_hybrid_key(
    photo_data: bytes,
    day_phrase: str,
    date_str: str,
    salt: bytes,
    pin: str = "",
    rsa_key_data: Optional[bytes] = None
 ) -> bytes:
 ```
 **After (v3.2.0):**
 ```python
 def derive_hybrid_key(
    photo_data: bytes,
    passphrase: str,
    salt: bytes,
    pin: str = "",
    rsa_key_data: Optional[bytes] = None
 ) -> bytes:
 ```
 ### 2. Key Derivation Material
 **Before:**
 ```python
 key_material = (
    photo_hash +
    day_phrase.lower().encode() +
    pin.encode() +
    date_str.encode() +  # ← REMOVED
    salt
 )
 ```
 **After:**
 ```python
 key_material = (
    photo_hash +
    passphrase.lower().encode() +
    pin.encode() +
    salt
 )
 ```
 ### 3. Header Format
 **Before (v3.1.0):** 66+ bytes
 ```
 [Magic:4][Version:1][DateLen:1][Date:10][Salt:32][IV:12][Tag:16][Ciphertext]
 ```
 **After (v3.2.0):** 65 bytes
 ```
 [Magic:4][Version:1][Salt:32][IV:12][Tag:16][Ciphertext]
 ```
 ### 4. Public API
 **Before:**
 ```python
 # Encoding
 result = encode(
    message="Secret",
    reference_photo=photo,
    carrier_image=carrier,
    day_phrase="apple forest thunder",
    pin="123456",
    date_str="2025-01-15"
 )
 # Decoding
 decoded = decode(
    stego_image=stego,
    reference_photo=photo,
    day_phrase="apple forest thunder",
    pin="123456",
    date_str="2025-01-15"
 )
 ```
 **After:**
 ```python
 # Encoding
 result = encode(
    message="Secret",
    reference_photo=photo,
    carrier_image=carrier,
    passphrase="apple forest thunder mountain",
    pin="123456"
 )
 # Decoding
 decoded = decode(
    stego_image=stego,
    reference_photo=photo,
    passphrase="apple forest thunder mountain",
    pin="123456"
 )
 ```
 ## Migration Path
 ### For Users with v3.1.0 Messages
 1. **Before upgrading**, decode all messages with v3.1.0:
   ```bash
   # Using v3.1.0
   python decode_all.py
   ```
 2. Save the decoded content
 3. Upgrade to v3.2.0
 4. Re-encode with v3.2.0 if needed
 ### For Developers
 1. Update the 4 core files: crypto.py, constants.py, models.py, validation.py
 2. Update remaining files in order:
   - `__init__.py` (public API - critical)
   - `keygen.py` (credential generation)
   - `batch.py` (batch operations)
   - `cli.py` (command line)
 3. Run tests to verify:
   ```bash
   pytest tests/ -v
   ```
 4. Update documentation and examples
 ## Benefits
 ### Simplicity
 - ❌ Before: 3 parameters (day_phrase, pin, date)
 - ✅ After: 2 parameters (passphrase, pin)
 ### User Experience
 - ❌ Before: "What date did I encode this?" "Which day's phrase?"
 - ✅ After: Just use your passphrase
 ### Asynchronous Ready
 - ❌ Before: Must know encoding date
 - ✅ After: Decode anytime
 ### Less Metadata
 - ❌ Before: Date stored in header
 - ✅ After: No temporal metadata
 ## Security Considerations
 ### Entropy Comparison
 **v3.1.0:**
 - Photo hash: ~128 bits
 - Day phrase (3 words): ~33 bits
 - PIN (6 digits): ~20 bits
 - Date: ~33 bits (10 digits)
 - **Total: ~214 bits**
 **v3.2.0:**
 - Photo hash: ~128 bits
 - Passphrase (4 words): ~44 bits
 - PIN (6 digits): ~20 bits
 - **Total: ~192 bits**
 **Mitigation:** Recommend longer passphrases (4-5 words vs 3)
 ### Best Practices for v3.2.0
 1. **Use 4+ word passphrases** (increased from 3)
 2. **Keep using PINs** (additional 20 bits)
 3. **Protect reference photo** (still critical)
 4. **Consider RSA keys** for highest security
 ## Testing Checklist
 - [ ] Unit tests pass
 - [ ] Integration tests pass
 - [ ] Encode/decode round-trip works
 - [ ] File payloads work
 - [ ] LSB mode works
 - [ ] DCT mode works
 - [ ] Batch operations work
 - [ ] CLI commands work
 - [ ] Error messages are clear
 - [ ] Validation works correctly
 - [ ] No references to "day_phrase" remain
 - [ ] No date parameters remain (except cosmetic)
 ## Documentation Updates Needed
 - [ ] README.md - Update all examples
 - [ ] API documentation - Update function signatures
 - [ ] Tutorials - Remove date parameters
 - [ ] CHANGELOG.md - Add v3.2.0 entry
 - [ ] Migration guide - How to upgrade from v3.1.0
 - [ ] Examples directory - Update all scripts
 ## Backward Compatibility Strategy
 ### Option 1: Clean Break (Recommended)
 - No compatibility code
 - Clear version separation
 - Users must migrate manually
 ### Option 2: Temporary Wrapper
 ```python
 def encode(
    message,
    reference_photo,
    carrier_image,
    passphrase: str = None,
    day_phrase: str = None,  # Deprecated
    date_str: str = None,     # Deprecated
    pin: str = "",
    ...
 ):
    if day_phrase and not passphrase:
        import warnings
        warnings.warn("day_phrase deprecated, use passphrase", DeprecationWarning)
        passphrase = day_phrase
    if date_str:
        warnings.warn("date_str no longer used", DeprecationWarning)
    # ... rest of function
 ```
 ## Release Checklist
 - [ ] All files updated
 - [ ] Tests passing
 - [ ] Documentation updated
 - [ ] Migration guide written
 - [ ] CHANGELOG.md updated
 - [ ] Version bumped to 3.2.0
 - [ ] Git tag created: v3.2.0
 - [ ] PyPI package published
 - [ ] Release notes published
 - [ ] Users notified of breaking changes
 ## Quick Reference
 ### Search and Replace Patterns
 Safe to replace globally:
 - `day_phrase` → `passphrase`
 - `day phrase` → `passphrase`
 - `Day phrase` → `Passphrase`
 - `DEFAULT_PHRASE_WORDS` → `DEFAULT_PASSPHRASE_WORDS`
 Do NOT replace:
 - `DAY_NAMES` (keep for utilities)
 - `get_day_from_date` (keep for utilities)
 - `generate_day_phrases` (rename function itself)
 ### Error Message Updates
 - "Day phrase is required" → "Passphrase is required"
 - "Check your phrase, PIN" → "Check your passphrase, PIN"
 - "the day's phrase" → "the passphrase"
 - "today's passphrase" → "passphrase"
 ## Support
 For issues or questions during migration:
 1. Check the migration guide
 2. Review the comparison document
 3. Look at updated examples
 4. File an issue on GitHub
 ---
 **Status:** 
 ✅ Core files updated (crypto, constants, models, validation)
 ⏳ Remaining files need updates (__init__, keygen, batch, cli)
 📝 Documentation updates pending
--- a/src/stegasoo/init.py
+++ b/src/stegasoo/init.py
@@ -7,7 +7,7 @@ Changes in v4.0.0:
 - encode() and decode() now accept channel_key parameter
 """
-__version__ = "4.0.1"
+__version__ = "4.1.2"
 # Core functionality
 # Channel key management (v4.0.0)
@@ -45,6 +45,7 @@ from .image_utils import (
 # Steganography functions
 from .steganography import (
    calculate_capacity_by_mode,
    compare_modes,
    has_dct_support,
    will_fit_by_mode,
@@ -92,6 +93,7 @@ from .constants import (
    EMBED_MODE_LSB,
    FORMAT_VERSION,
    LOSSLESS_FORMATS,
    MAX_FILE_PAYLOAD_SIZE,
    MAX_IMAGE_PIXELS,
    MAX_MESSAGE_SIZE,
    MAX_PASSPHRASE_WORDS,
@@ -112,12 +114,16 @@ from .exceptions import (
    ExtractionError,
    ImageValidationError,
    InvalidHeaderError,
    InvalidMagicBytesError,
    KeyDerivationError,
    KeyGenerationError,
    KeyPasswordError,
    KeyValidationError,
    MessageValidationError,
    ModeMismatchError,
    NoDataFoundError,
    PinValidationError,
    ReedSolomonError,
    SecurityFactorError,
    SteganographyError,
    StegasooError,
@@ -145,6 +151,7 @@ from .validation import (
 MIN_MESSAGE_LENGTH = 1
 MAX_MESSAGE_LENGTH = MAX_MESSAGE_SIZE
 MAX_PAYLOAD_SIZE = MAX_MESSAGE_SIZE
 # MAX_FILE_PAYLOAD_SIZE imported from constants above
 SUPPORTED_IMAGE_FORMATS = LOSSLESS_FORMATS
 LSB_BYTES_PER_PIXEL = 3 / 8
 DCT_BYTES_PER_PIXEL = 0.125
@@ -184,6 +191,7 @@ __all__ = [
    "has_argon2",
    # Steganography
    "has_dct_support",
    "calculate_capacity_by_mode",
    "compare_modes",
    "will_fit_by_mode",
    # QR utilities
@@ -232,6 +240,10 @@ __all__ = [
    "ExtractionError",
    "EmbeddingError",
    "InvalidHeaderError",
    "InvalidMagicBytesError",
    "ReedSolomonError",
    "NoDataFoundError",
    "ModeMismatchError",
    # Constants
    "FORMAT_VERSION",
    "MIN_PASSPHRASE_WORDS",
@@ -244,6 +256,7 @@ __all__ = [
    "MAX_MESSAGE_LENGTH",
    "MAX_MESSAGE_SIZE",
    "MAX_PAYLOAD_SIZE",
    "MAX_FILE_PAYLOAD_SIZE",
    "MIN_IMAGE_PIXELS",
    "MAX_IMAGE_PIXELS",
    "SUPPORTED_IMAGE_FORMATS",
--- a/src/stegasoo/channel.py
+++ b/src/stegasoo/channel.py
@@ -372,6 +372,124 @@ def has_channel_key() -> bool:
    return get_channel_key() is not None
 def resolve_channel_key(
    value: str | None = None,
    *,
    file_path: str | Path | None = None,
    no_channel: bool = False,
 ) -> str | None:
    """
    Resolve a channel key from user input (unified for all frontends).
    This consolidates channel key resolution logic used by CLI, API, and WebUI.
    Args:
        value: Input value:
            - 'auto' or None: Use server-configured key
            - 'none' or '': Public mode (no channel key)
            - explicit key: Validate and use
        file_path: Path to file containing channel key
        no_channel: If True, return "" for public mode (overrides value)
    Returns:
        None: Use server-configured key (auto mode)
        "": Public mode (no channel key)
        str: Explicit valid channel key
    Raises:
        ValueError: If key format is invalid
        FileNotFoundError: If file_path doesn't exist
    Example:
        >>> resolve_channel_key("auto")  # -> None
        >>> resolve_channel_key("none")  # -> ""
        >>> resolve_channel_key(no_channel=True)  # -> ""
        >>> resolve_channel_key("ABCD-1234-...")  # -> "ABCD-1234-..."
        >>> resolve_channel_key(file_path="key.txt")  # reads from file
    """
    debug.print(f"resolve_channel_key: value={value}, file_path={file_path}, no_channel={no_channel}")
    # no_channel flag takes precedence
    if no_channel:
        debug.print("resolve_channel_key: public mode (no_channel=True)")
        return ""
    # Read from file if provided
    if file_path:
        path = Path(file_path)
        if not path.exists():
            raise FileNotFoundError(f"Channel key file not found: {file_path}")
        key = path.read_text().strip()
        if not validate_channel_key(key):
            raise ValueError(f"Invalid channel key format in file: {file_path}")
        debug.print(f"resolve_channel_key: from file -> {get_channel_fingerprint(key)}")
        return format_channel_key(key)
    # Handle value string
    if value is None or value.lower() == "auto":
        debug.print("resolve_channel_key: auto mode (server config)")
        return None
    if value == "" or value.lower() == "none":
        debug.print("resolve_channel_key: public mode (explicit none)")
        return ""
    # Explicit key - validate
    if validate_channel_key(value):
        formatted = format_channel_key(value)
        debug.print(f"resolve_channel_key: explicit key -> {get_channel_fingerprint(formatted)}")
        return formatted
    raise ValueError(
        "Invalid channel key format. Expected: XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX\n"
        "Generate a new key with: stegasoo channel generate"
    )
 def get_channel_response_info(channel_key: str | None) -> dict:
    """
    Get channel info for API/WebUI responses.
    Args:
        channel_key: Resolved channel key (None=auto, ""=public, str=explicit)
    Returns:
        Dict with mode, fingerprint, and display info
    Example:
        >>> info = get_channel_response_info("ABCD-1234-...")
        >>> info['mode']
        'explicit'
    """
    if channel_key is None:
        # Auto mode - check server config
        server_key = get_channel_key()
        if server_key:
            return {
                "mode": "private",
                "fingerprint": get_channel_fingerprint(server_key),
                "source": "server",
            }
        return {
            "mode": "public",
            "fingerprint": None,
            "source": "server",
        }
    if channel_key == "":
        return {
            "mode": "public",
            "fingerprint": None,
            "source": "explicit",
        }
    return {
        "mode": "private",
        "fingerprint": get_channel_fingerprint(channel_key),
        "source": "explicit",
    }
 # =============================================================================
 # CLI SUPPORT
 # =============================================================================
--- a/src/stegasoo/cli.py
+++ b/src/stegasoo/cli.py
@@ -56,7 +56,14 @@ def cli(ctx, json_output):
@cli.command()
-@click.argument("image", type=click.Path(exists=True))
+@click.argument("carrier", type=click.Path(exists=True))
@click.option(
    "-r",
    "--reference",
    required=True,
    type=click.Path(exists=True),
    help="Reference photo (shared secret)",
 )
@click.option("-m", "--message", help="Message to encode")
@click.option(
    "-f",
@@ -86,19 +93,22 @@ def cli(ctx, json_output):
@click.option("--dry-run", is_flag=True, help="Show capacity usage without encoding")
@click.pass_context
 def encode(
-    ctx, image, message, file_payload, output, passphrase, pin, compress, algorithm, dry_run
+    ctx, carrier, reference, message, file_payload, output, passphrase, pin, compress, algorithm, dry_run
 ):
    """
    Encode a message or file into an image.
    Examples:
-        stegasoo encode photo.png -m "Secret message" --passphrase --pin
+        stegasoo encode photo.png -r ref.jpg -m "Secret message" --passphrase --pin
-        stegasoo encode photo.png -f secret.pdf -o encoded.png
+        stegasoo encode photo.png -r ref.jpg -f secret.pdf -o encoded.png
    """
    from PIL import Image
    from .encode import encode as stegasoo_encode
    from .encode import encode_file as stegasoo_encode_file
    if not message and not file_payload:
        raise click.UsageError("Either --message or --file is required")
@@ -123,13 +133,14 @@ def encode(
        payload_type = "text"
    # Get image capacity
-    with Image.open(image) as img:
+    with Image.open(carrier) as img:
        width, height = img.size
        capacity_bytes = (width * height * 3 // 8) - 69  # v3.2.0: corrected overhead
    if dry_run:
        result = {
-            "image": image,
+            "carrier": carrier,
            "reference": reference,
            "dimensions": f"{width}x{height}",
            "capacity_bytes": capacity_bytes,
            "payload_type": payload_type,
@@ -142,7 +153,8 @@ def encode(
        if ctx.obj.get("json"):
            click.echo(json.dumps(result, indent=2))
        else:
-            click.echo(f"Image: {image} ({width}x{height})")
+            click.echo(f"Carrier: {carrier} ({width}x{height})")
            click.echo(f"Reference: {reference}")
            click.echo(f"Capacity: {capacity_bytes:,} bytes ({capacity_bytes//1024} KB)")
            click.echo(f"Payload: {payload_size:,} bytes ({payload_type})")
            click.echo(f"Compression: {algorithm_name(compression_algo)}")
@@ -150,16 +162,46 @@ def encode(
            click.echo(f"Status: {'✓ Fits' if result['fits'] else '✗ Too large'}")
        return
-    # Actual encoding would happen here
+    # Read input files
-    # For now, show what would be done
+    with open(reference, "rb") as f:
-    output = output or f"{Path(image).stem}_encoded.png"
+        reference_data = f.read()
    with open(carrier, "rb") as f:
        carrier_data = f.read()
    # Determine output path
    output = output or f"{Path(carrier).stem}_encoded.png"
    try:
        if file_payload:
            # Encode file
            result = stegasoo_encode_file(
                filepath=file_payload,
                reference_photo=reference_data,
                carrier_image=carrier_data,
                passphrase=passphrase,
                pin=pin,
            )
        else:
            # Encode message
            result = stegasoo_encode(
                message=message,
                reference_photo=reference_data,
                carrier_image=carrier_data,
                passphrase=passphrase,
                pin=pin,
            )
        # Write output
        with open(output, "wb") as f:
            f.write(result.stego_image)
        if ctx.obj.get("json"):
            click.echo(
                json.dumps(
                    {
                        "status": "success",
-                    "input": image,
+                        "carrier": carrier,
                        "reference": reference,
                        "output": output,
                        "payload_type": payload_type,
                        "compression": algorithm_name(compression_algo),
@@ -169,38 +211,110 @@ def encode(
            )
        else:
            click.echo(f"✓ Encoded {payload_type} to {output}")
            click.echo(f"  Reference: {reference}")
            click.echo(f"  Compression: {algorithm_name(compression_algo)}")
    except Exception as e:
        if ctx.obj.get("json"):
            click.echo(json.dumps({"status": "error", "error": str(e)}, indent=2))
        else:
            click.echo(f"✗ Encoding failed: {e}", err=True)
        raise SystemExit(1)
@cli.command()
@click.argument("image", type=click.Path(exists=True))
@click.option(
    "-r",
    "--reference",
    required=True,
    type=click.Path(exists=True),
    help="Reference photo (shared secret)",
 )
@click.option("--passphrase", prompt=True, hide_input=True, help="Passphrase")
@click.option("--pin", prompt=True, hide_input=True, help="PIN code")
@click.option("-o", "--output", type=click.Path(), help="Output path for file payloads")
@click.pass_context
-def decode(ctx, image, passphrase, pin, output):
+def decode(ctx, image, reference, passphrase, pin, output):
    """
    Decode a message or file from an image.
    Examples:
-        stegasoo decode encoded.png --passphrase --pin
+        stegasoo decode encoded.png -r ref.jpg --passphrase --pin
-        stegasoo decode encoded.png -o ./extracted/
+        stegasoo decode encoded.png -r ref.jpg -o ./extracted/
    """
-    # Actual decoding would happen here
+    from .decode import decode as stegasoo_decode
-    result = {
+
-        "status": "success",
+    # Read input files
-        "image": image,
+    with open(image, "rb") as f:
-        "payload_type": "text",
+        stego_data = f.read()
-        "message": "[Decoded message would appear here]",
+    with open(reference, "rb") as f:
-    }
+        reference_data = f.read()
    try:
        result = stegasoo_decode(
            stego_image=stego_data,
            reference_photo=reference_data,
            passphrase=passphrase,
            pin=pin,
        )
        if result.is_file:
            # File payload
            filename = result.filename or "decoded_file"
            output_path = Path(output) / filename if output else Path(filename)
            # Ensure output directory exists
            output_path.parent.mkdir(parents=True, exist_ok=True)
            with open(output_path, "wb") as f:
                f.write(result.file_data)
            if ctx.obj.get("json"):
-        click.echo(json.dumps(result, indent=2))
+                click.echo(
                    json.dumps(
                        {
                            "status": "success",
                            "image": image,
                            "reference": reference,
                            "payload_type": "file",
                            "filename": filename,
                            "output": str(output_path),
                            "size": len(result.file_data),
                        },
                        indent=2,
                    )
                )
            else:
                click.echo(f"✓ Extracted file: {output_path}")
                click.echo(f"  Size: {len(result.file_data):,} bytes")
        else:
            # Text message
            if ctx.obj.get("json"):
                click.echo(
                    json.dumps(
                        {
                            "status": "success",
                            "image": image,
                            "reference": reference,
                            "payload_type": "text",
                            "message": result.message,
                        },
                        indent=2,
                    )
                )
            else:
                click.echo(f"Decoded from {image}:")
-        click.echo(result["message"])
+                click.echo(result.message)
    except Exception as e:
        if ctx.obj.get("json"):
            click.echo(json.dumps({"status": "error", "error": str(e)}, indent=2))
        else:
            click.echo(f"✗ Decoding failed: {e}", err=True)
        raise SystemExit(1)
 # =============================================================================
@@ -398,16 +512,21 @@ def batch_check(ctx, images, recursive):
@click.option(
    "--pin-length", default=DEFAULT_PIN_LENGTH, help=f"PIN length (default: {DEFAULT_PIN_LENGTH})"
 )
@click.option(
    "--channel-key", is_flag=True, help="Also generate a 256-bit channel key"
 )
@click.pass_context
-def generate(ctx, words, pin_length):
+def generate(ctx, words, pin_length, channel_key):
    """
-    Generate random credentials (passphrase + PIN).
+    Generate random credentials (passphrase + PIN + optional channel key).
    Examples:
        stegasoo generate
        stegasoo generate --words 6 --pin-length 8
        stegasoo generate --channel-key
    """
    import secrets
@@ -451,11 +570,18 @@ def generate(ctx, words, pin_length):
        "pin_length": pin_length,
    }
    # Generate channel key if requested
    if channel_key:
        from .channel import generate_channel_key
        result["channel_key"] = generate_channel_key()
    if ctx.obj.get("json"):
        click.echo(json.dumps(result, indent=2))
    else:
        click.echo(f"Passphrase:   {passphrase}")
        click.echo(f"PIN:          {pin}")
        if channel_key:
            click.echo(f"Channel Key:  {result['channel_key']}")
        click.echo("\n⚠️  Save these credentials securely - they cannot be recovered!")
@@ -489,6 +615,627 @@ def info(ctx):
        click.echo(f"  • Max file payload: {MAX_FILE_PAYLOAD_SIZE:,} bytes")
 # =============================================================================
 # CHANNEL KEY COMMANDS
 # =============================================================================
@cli.group()
@click.pass_context
 def channel(ctx):
    """
    Manage channel keys for deployment isolation.
    Channel keys bind encode/decode operations to a specific group or deployment.
    Messages encoded with one channel key can only be decoded by systems with
    the same channel key.
    Examples:
        stegasoo channel generate
        stegasoo channel show
        stegasoo channel qr
        stegasoo channel qr -o channel-key.png
    """
    pass
@channel.command("generate")
@click.option("--save", is_flag=True, help="Save to project config file")
@click.option("--save-user", is_flag=True, help="Save to user config (~/.stegasoo/)")
@click.pass_context
 def channel_generate(ctx, save, save_user):
    """
    Generate a new random channel key.
    Examples:
        stegasoo channel generate
        stegasoo channel generate --save
        stegasoo channel generate --save-user
    """
    from .channel import generate_channel_key, set_channel_key
    key = generate_channel_key()
    if ctx.obj.get("json"):
        result = {"channel_key": key}
        if save or save_user:
            location = "user" if save_user else "project"
            path = set_channel_key(key, location)
            result["saved_to"] = str(path)
        click.echo(json.dumps(result, indent=2))
    else:
        click.echo("Generated channel key:")
        click.echo(f"  {key}")
        click.echo()
        if save or save_user:
            location = "user" if save_user else "project"
            path = set_channel_key(key, location)
            click.echo(f"Saved to: {path}")
        else:
            click.echo("To use this key:")
            click.echo(f'  export STEGASOO_CHANNEL_KEY="{key}"')
            click.echo()
            click.echo("Or save to config:")
            click.echo("  stegasoo channel generate --save")
@channel.command("show")
@click.option("--key", "explicit_key", help="Show this key instead of configured one")
@click.pass_context
 def channel_show(ctx, explicit_key):
    """
    Show the current channel key.
    Examples:
        stegasoo channel show
        stegasoo channel show --key "ABCD-1234-..."
    """
    from .channel import format_channel_key, get_channel_status, validate_channel_key
    if explicit_key:
        if not validate_channel_key(explicit_key):
            click.echo("Error: Invalid channel key format", err=True)
            raise SystemExit(1)
        key = format_channel_key(explicit_key)
        source = "command line"
    else:
        status = get_channel_status()
        if not status["configured"]:
            if ctx.obj.get("json"):
                click.echo(json.dumps({"configured": False, "mode": "public"}))
            else:
                click.echo("No channel key configured (public mode)")
            return
        key = status["key"]
        source = status["source"]
    if ctx.obj.get("json"):
        click.echo(json.dumps({"channel_key": key, "source": source}))
    else:
        click.echo(f"Channel key: {key}")
        click.echo(f"Source: {source}")
@channel.command("status")
@click.pass_context
 def channel_status(ctx):
    """
    Show channel key status and configuration.
    Examples:
        stegasoo channel status
        stegasoo --json channel status
    """
    from .channel import get_channel_status
    status = get_channel_status()
    if ctx.obj.get("json"):
        click.echo(json.dumps(status, indent=2))
    else:
        click.echo(f"Mode: {status['mode'].upper()}")
        if status["configured"]:
            click.echo(f"Fingerprint: {status['fingerprint']}")
            click.echo(f"Source: {status['source']}")
        else:
            click.echo("No channel key configured")
            click.echo()
            click.echo("To set up a channel key:")
            click.echo("  stegasoo channel generate --save")
@channel.command("qr")
@click.option("--key", "explicit_key", help="Generate QR for this key instead of configured one")
@click.option(
    "--format",
    "output_format",
    type=click.Choice(["ascii", "png"]),
    default="ascii",
    help="Output format (default: ascii)",
 )
@click.option("-o", "--output", type=click.Path(), help="Output file (PNG format, or - for stdout)")
@click.pass_context
 def channel_qr(ctx, explicit_key, output_format, output):
    """
    Display channel key as QR code.
    Examples:
        stegasoo channel qr
        stegasoo channel qr -o channel-key.png
        stegasoo channel qr --format png -o - > key.png
    """
    import sys
    from .channel import format_channel_key, get_channel_key, validate_channel_key
    # Get the key to display
    if explicit_key:
        if not validate_channel_key(explicit_key):
            click.echo("Error: Invalid channel key format", err=True)
            raise SystemExit(1)
        key = format_channel_key(explicit_key)
    else:
        key = get_channel_key()
        if not key:
            click.echo("Error: No channel key configured", err=True)
            click.echo("Generate one with: stegasoo channel generate", err=True)
            raise SystemExit(1)
    # Import qrcode
    try:
        import qrcode
    except ImportError:
        click.echo("Error: qrcode library not installed", err=True)
        click.echo("Install with: pip install qrcode[pil]", err=True)
        raise SystemExit(1)
    # Determine output mode
    if output:
        output_format = "png"  # Force PNG when output file specified
    if output_format == "png":
        # Generate PNG QR code (requires Pillow)
        try:
            import PIL  # noqa: F401 - check Pillow is available
        except ImportError:
            click.echo("Error: PIL/Pillow not installed for PNG output", err=True)
            click.echo("Install with: pip install Pillow", err=True)
            raise SystemExit(1)
        qr = qrcode.QRCode(
            version=1,
            error_correction=qrcode.constants.ERROR_CORRECT_M,
            box_size=10,
            border=4,
        )
        qr.add_data(key)
        qr.make(fit=True)
        img = qr.make_image(fill_color="black", back_color="white")
        if output == "-":
            # Write to stdout
            img.save(sys.stdout.buffer, format="PNG")
        elif output:
            # Write to file
            img.save(output)
            click.echo(f"Saved QR code to: {output}", err=True)
        else:
            # No output specified but PNG format requested - error
            click.echo("Error: PNG format requires -o/--output", err=True)
            raise SystemExit(1)
    else:
        # ASCII output to terminal
        qr = qrcode.QRCode(
            version=1,
            error_correction=qrcode.constants.ERROR_CORRECT_M,
            box_size=1,
            border=2,
        )
        qr.add_data(key)
        qr.make(fit=True)
        click.echo()
        click.echo(f"Channel Key: {key}")
        click.echo()
        qr.print_ascii(invert=True)
        click.echo()
        click.echo("Scan this QR code to share the channel key.")
@channel.command("clear")
@click.option("--project", is_flag=True, help="Only clear project config")
@click.option("--user", is_flag=True, help="Only clear user config")
@click.pass_context
 def channel_clear(ctx, project, user):
    """
    Remove channel key configuration.
    Examples:
        stegasoo channel clear
        stegasoo channel clear --project
        stegasoo channel clear --user
    """
    from .channel import clear_channel_key
    if project and user:
        location = "all"
    elif project:
        location = "project"
    elif user:
        location = "user"
    else:
        location = "all"
    deleted = clear_channel_key(location)
    if ctx.obj.get("json"):
        click.echo(json.dumps({"deleted": [str(p) for p in deleted]}))
    else:
        if deleted:
            click.echo(f"Removed channel key from: {', '.join(str(p) for p in deleted)}")
        else:
            click.echo("No channel key files found")
 # =============================================================================
 # TOOLS COMMANDS
 # =============================================================================
@cli.group()
@click.pass_context
 def tools(ctx):
    """Image security tools."""
    pass
@tools.command("capacity")
@click.argument("image", type=click.Path(exists=True))
@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
 def tools_capacity(image, as_json):
    """Show steganography capacity for an image.
    Example:
        stegasoo tools capacity photo.jpg
    """
    from .dct_steganography import estimate_capacity_comparison
    with open(image, "rb") as f:
        image_data = f.read()
    result = estimate_capacity_comparison(image_data)
    result["filename"] = Path(image).name
    result["megapixels"] = round((result["width"] * result["height"]) / 1_000_000, 2)
    if as_json:
        click.echo(json.dumps(result, indent=2))
    else:
        click.echo(f"\n  {result['filename']}")
        click.echo(f"  {'─' * 40}")
        click.echo(f"  Dimensions:   {result['width']} × {result['height']}")
        click.echo(f"  Megapixels:   {result['megapixels']} MP")
        click.echo(f"  {'─' * 40}")
        click.echo(f"  LSB Capacity: {result['lsb']['capacity_kb']:.1f} KB")
        if result['dct']['available']:
            click.echo(f"  DCT Capacity: {result['dct']['capacity_kb']:.1f} KB")
        else:
            click.echo("  DCT Capacity: N/A (scipy required)")
        click.echo()
@tools.command("strip")
@click.argument("image", type=click.Path(exists=True))
@click.option("-o", "--output", type=click.Path(), help="Output file (default: <name>_clean.png)")
@click.option("--format", "fmt", type=click.Choice(["png", "bmp"]), default="png", help="Output format")
 def tools_strip(image, output, fmt):
    """Strip EXIF/metadata from an image.
    Example:
        stegasoo tools strip photo.jpg
        stegasoo tools strip photo.jpg -o clean.png
    """
    from .utils import strip_image_metadata
    with open(image, "rb") as f:
        image_data = f.read()
    clean_data = strip_image_metadata(image_data, output_format=fmt.upper())
    if not output:
        stem = Path(image).stem
        output = f"{stem}_clean.{fmt}"
    with open(output, "wb") as f:
        f.write(clean_data)
    click.echo(f"Saved clean image to: {output}")
@tools.command("peek")
@click.argument("image", type=click.Path(exists=True))
@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
 def tools_peek(image, as_json):
    """Check if image contains Stegasoo hidden data.
    Example:
        stegasoo tools peek suspicious.jpg
    """
    from .steganography import peek_image
    with open(image, "rb") as f:
        image_data = f.read()
    result = peek_image(image_data)
    result["filename"] = Path(image).name
    if as_json:
        click.echo(json.dumps(result))
    else:
        if result["has_stegasoo"]:
            click.echo(f"\n  ✓ Stegasoo data detected in {result['filename']}")
            click.echo(f"    Mode: {result['mode'].upper()}")
        else:
            click.echo(f"\n  ✗ No Stegasoo header found in {result['filename']}")
        click.echo()
@tools.command("exif")
@click.argument("image", type=click.Path(exists=True))
@click.option("--clear", is_flag=True, help="Remove all EXIF metadata")
@click.option("--set", "set_fields", multiple=True, help="Set EXIF field (e.g. --set Artist=John)")
@click.option("-o", "--output", type=click.Path(), help="Output file (required for modifications)")
@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
 def tools_exif(image, clear, set_fields, output, as_json):
    """View or edit EXIF metadata.
    Examples:
        stegasoo tools exif photo.jpg
        stegasoo tools exif photo.jpg --clear -o clean.jpg
        stegasoo tools exif photo.jpg --set Artist="John Doe" -o updated.jpg
    """
    from .utils import read_image_exif, strip_image_metadata, write_image_exif
    with open(image, "rb") as f:
        image_data = f.read()
    # View mode (no modifications)
    if not clear and not set_fields:
        exif = read_image_exif(image_data)
        if as_json:
            click.echo(json.dumps(exif, indent=2, default=str))
        else:
            click.echo(f"\n  EXIF Metadata: {Path(image).name}")
            click.echo(f"  {'─' * 45}")
            if not exif:
                click.echo("  No EXIF metadata found")
            else:
                for key, value in sorted(exif.items()):
                    # Skip complex nested structures for display
                    if isinstance(value, dict):
                        click.echo(f"  {key}: [complex data]")
                    elif isinstance(value, list):
                        click.echo(f"  {key}: {value}")
                    else:
                        # Truncate long values
                        str_val = str(value)
                        if len(str_val) > 50:
                            str_val = str_val[:47] + "..."
                        click.echo(f"  {key}: {str_val}")
            click.echo()
        return
    # Modification mode - require output file
    if not output:
        raise click.UsageError("Output file required for modifications (use -o/--output)")
    if clear:
        # Strip all metadata
        clean_data = strip_image_metadata(image_data, output_format="JPEG")
        with open(output, "wb") as f:
            f.write(clean_data)
        click.echo(f"Cleared EXIF metadata, saved to: {output}")
    elif set_fields:
        # Parse field=value pairs
        updates = {}
        for field in set_fields:
            if "=" not in field:
                raise click.UsageError(f"Invalid format: {field} (use Field=Value)")
            key, val = field.split("=", 1)
            updates[key.strip()] = val.strip()
        try:
            updated_data = write_image_exif(image_data, updates)
            with open(output, "wb") as f:
                f.write(updated_data)
            click.echo(f"Updated {len(updates)} EXIF field(s), saved to: {output}")
        except ValueError as e:
            raise click.UsageError(str(e))
 # =============================================================================
 # ADMIN COMMANDS (Web UI administration)
 # =============================================================================
@cli.group()
@click.pass_context
 def admin(ctx):
    """Web UI administration commands."""
    pass
@admin.command("recover")
@click.option(
    "--db", "db_path",
    type=click.Path(exists=True),
    help="Path to stegasoo.db (default: frontends/web/instance/stegasoo.db)"
 )
@click.option("--password", prompt=True, hide_input=True, confirmation_prompt=True,
              help="New admin password")
 def admin_recover(db_path, password):
    """Reset admin password using recovery key.
    Allows password reset for Web UI admin account when locked out.
    Requires the recovery key that was saved during setup.
    Example:
        stegasoo admin recover --db /path/to/stegasoo.db
    """
    import sqlite3
    from argon2 import PasswordHasher
    from .recovery import verify_recovery_key
    # Try default paths if not specified
    if not db_path:
        candidates = [
            Path("frontends/web/instance/stegasoo.db"),
            Path("instance/stegasoo.db"),
            Path("/app/instance/stegasoo.db"),
        ]
        for candidate in candidates:
            if candidate.exists():
                db_path = str(candidate)
                break
    if not db_path or not Path(db_path).exists():
        raise click.UsageError(
            "Database not found. Use --db to specify path to stegasoo.db"
        )
    click.echo(f"Database: {db_path}")
    # Connect and check for recovery key
    db = sqlite3.connect(db_path)
    db.row_factory = sqlite3.Row
    # Get recovery key hash from app_settings
    cursor = db.execute(
        "SELECT value FROM app_settings WHERE key = 'recovery_key_hash'"
    )
    row = cursor.fetchone()
    if not row:
        db.close()
        raise click.ClickException(
            "No recovery key configured for this instance. "
            "Password reset is not possible."
        )
    stored_hash = row["value"]
    # Prompt for recovery key
    recovery_key = click.prompt(
        "Enter your recovery key",
        hide_input=False,  # Recovery keys are meant to be visible
    )
    # Verify recovery key
    if not verify_recovery_key(recovery_key, stored_hash):
        db.close()
        raise click.ClickException("Invalid recovery key")
    # Validate password
    if len(password) < 8:
        db.close()
        raise click.UsageError("Password must be at least 8 characters")
    # Hash new password with same settings as web UI
    ph = PasswordHasher(
        time_cost=3,
        memory_cost=65536,  # 64MB
        parallelism=4,
        hash_len=32,
        salt_len=16,
    )
    new_hash = ph.hash(password)
    # Find and update admin user
    admin = db.execute(
        "SELECT id, username FROM users WHERE role = 'admin' ORDER BY id LIMIT 1"
    ).fetchone()
    if not admin:
        db.close()
        raise click.ClickException("No admin user found in database")
    db.execute(
        "UPDATE users SET password_hash = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?",
        (new_hash, admin["id"]),
    )
    db.commit()
    db.close()
    click.echo(f"\nPassword reset successfully for admin '{admin['username']}'")
    click.echo("You can now login to the Web UI with your new password.")
@admin.command("generate-key")
@click.option("--qr", "show_qr", is_flag=True, help="Show QR code in terminal (if supported)")
 def admin_generate_key(show_qr):
    """Generate a new recovery key (for reference only).
    This generates a new random recovery key and displays it.
    To actually set the recovery key, use the Web UI.
    Example:
        stegasoo admin generate-key
        stegasoo admin generate-key --qr
    """
    from .recovery import generate_recovery_key, get_recovery_fingerprint
    key = generate_recovery_key()
    click.echo("\nNew Recovery Key:")
    click.echo("─" * 50)
    click.echo(f"  {key}")
    click.echo("─" * 50)
    click.echo(f"Fingerprint: {get_recovery_fingerprint(key)}")
    if show_qr:
        try:
            import qrcode
            qr = qrcode.QRCode(box_size=1, border=1)
            qr.add_data(key)
            qr.make()
            click.echo("\nQR Code:")
            qr.print_ascii(invert=True)
        except ImportError:
            click.echo("\n(qrcode library not installed for terminal QR)")
    click.echo("\nNote: Save this key securely. To set it in the Web UI,")
    click.echo("go to Account > Recovery Key > Regenerate")
 def main():
    """Entry point for CLI."""
    cli(obj={})
--- a/src/stegasoo/constants.py
+++ b/src/stegasoo/constants.py
@@ -1,9 +1,14 @@
 """
-Stegasoo Constants and Configuration (v4.0.1 - Channel Key Support)
+Stegasoo Constants and Configuration (v4.0.2 - Web UI Authentication)
 Central location for all magic numbers, limits, and crypto parameters.
 All version numbers, limits, and configuration values should be defined here.
 CHANGES in v4.0.2:
 - Added Web UI authentication with SQLite3 user storage
 - Added optional HTTPS with auto-generated self-signed certificates
 - UI improvements for QR preview panels and PIN/channel columns
 BREAKING CHANGES in v4.0.0:
 - Added channel key support for deployment/group isolation
 - FORMAT_VERSION bumped to 5 (adds flags byte to header)
@@ -20,7 +25,7 @@ from pathlib import Path
 # VERSION
 # ============================================================================
-__version__ = "4.0.1"
+__version__ = "4.1.2"
 # ============================================================================
 # FILE FORMAT
@@ -229,6 +234,14 @@ DCT_MAGIC_HEADER = b"\x89DCT"  # Magic header for DCT mode
 DCT_FORMAT_VERSION = 1
 DCT_STEP_SIZE = 8  # QIM quantization step
 # Recovery key obfuscation - FIXED value for admin recovery QR codes
 # SHA256("\x89ST3\x89DCT") - hardcoded so it never changes even if headers are added
 # Used to XOR recovery keys in QR codes so they scan as gibberish
 RECOVERY_OBFUSCATION_KEY = bytes.fromhex(
    "d6c70bce27780db942562550e9fe1459"
    "9dfdb8421f5acc79696b05db4e7afbd2"
 )  # 32 bytes
 # Valid embedding modes
 VALID_EMBED_MODES = {EMBED_MODE_LSB, EMBED_MODE_DCT}
--- a/src/stegasoo/dct_steganography.py
+++ b/src/stegasoo/dct_steganography.py
@@ -1,17 +1,22 @@
 """
-DCT Domain Steganography Module (v3.2.0-patch2)
+DCT Domain Steganography Module (v4.1.0)
 Embeds data in DCT coefficients with two approaches:
 1. PNG output: Scipy-based DCT transform (grayscale or color)
 2. JPEG output: jpegio-based coefficient manipulation (if available)
 v4.1.0 Changes:
 - Reed-Solomon error correction protects against bit errors in problematic blocks
 - Majority voting on length headers (3 copies) for additional robustness
 - RS can correct up to 16 byte errors per 223-byte chunk
 v3.2.0-patch2 Changes:
 - Chunked processing for large images to avoid heap corruption
 - Process image in vertical strips to limit memory per operation
 - Isolated DCT operations with fresh array allocations
 - Workaround for scipy.fftpack memory issues
-Requires: scipy (for PNG mode), optionally jpegio (for JPEG mode)
+Requires: scipy (for PNG mode), optionally jpegio (for JPEG mode), reedsolo (for error correction)
 """
 import gc
@@ -49,6 +54,34 @@ except ImportError:
    HAS_JPEGIO = False
    jio = None
 # Import custom exceptions
 from .exceptions import InvalidMagicBytesError
 from .exceptions import ReedSolomonError as StegasooRSError
 # Progress reporting interval (write every N blocks)
 PROGRESS_INTERVAL = 50
 def _write_progress(progress_file: str | None, current: int, total: int, phase: str = "embedding"):
    """Write progress to file for frontend polling."""
    if progress_file is None:
        return
    try:
        import json
        with open(progress_file, "w") as f:
            json.dump(
                {
                    "current": current,
                    "total": total,
                    "percent": round((current / total) * 100, 1) if total > 0 else 0,
                    "phase": phase,
                },
                f,
            )
    except Exception:
        pass  # Don't let progress writing break encoding
 # ============================================================================
 # CONSTANTS
@@ -102,6 +135,13 @@ JPEGIO_MAGIC = b"JPGS"
 JPEGIO_MIN_COEF_MAGNITUDE = 2
 JPEGIO_EMBED_CHANNEL = 0
 FLAG_COLOR_MODE = 0x01
 FLAG_RS_PROTECTED = 0x02  # Reed-Solomon error correction enabled
 # Reed-Solomon settings - 32 symbols can correct up to 16 byte errors per 223-byte chunk
 RS_NSYM = 32
 RS_LENGTH_HEADER_SIZE = 8  # 8 bytes: 4 for raw_payload_length + 4 for rs_payload_length
 RS_LENGTH_COPIES = 3  # Store length header 3 times for majority voting
 RS_LENGTH_PREFIX_SIZE = RS_LENGTH_HEADER_SIZE * RS_LENGTH_COPIES  # Total: 24 bytes
 # Chunking settings for large images
 MAX_CHUNK_HEIGHT = 512  # Process in 512-pixel tall strips
@@ -167,6 +207,44 @@ def has_jpegio_support() -> bool:
    return HAS_JPEGIO
 # ============================================================================
 # REED-SOLOMON ERROR CORRECTION
 # Protects against bit errors in problematic image blocks
 # ============================================================================
 # Check for reedsolo availability
 try:
    from reedsolo import ReedSolomonError, RSCodec
    HAS_REEDSOLO = True
 except ImportError:
    HAS_REEDSOLO = False
    RSCodec = None
    ReedSolomonError = None
 def _rs_encode(data: bytes) -> bytes:
    """Add Reed-Solomon error correction symbols to data."""
    if not HAS_REEDSOLO:
        return data  # No protection if reedsolo not available
    rs = RSCodec(RS_NSYM)
    return bytes(rs.encode(data))
 def _rs_decode(data: bytes) -> bytes:
    """Decode Reed-Solomon protected data, correcting errors if possible."""
    if not HAS_REEDSOLO:
        return data  # No decoding if reedsolo not available
    rs = RSCodec(RS_NSYM)
    try:
        decoded, _, errata_pos = rs.decode(data)
        if errata_pos:
            pass  # Errors were corrected
        return bytes(decoded)
    except ReedSolomonError as e:
        raise StegasooRSError(f"Image corrupted beyond repair: {e}") from e
 # ============================================================================
 # SAFE DCT FUNCTIONS
 # These create fresh arrays to avoid scipy memory corruption issues
@@ -360,7 +438,7 @@ def _parse_header(header_bits: list) -> tuple[int, int, int]:
    magic, version, flags, length = struct.unpack(">4sBBI", header_bytes)
    if magic != DCT_MAGIC:
-        raise ValueError("Invalid DCT stego magic bytes")
+        raise InvalidMagicBytesError("Not a Stegasoo image or wrong mode (try LSB instead of DCT)")
    return version, flags, length
@@ -411,7 +489,7 @@ def _jpegio_parse_header(header_bytes: bytes) -> tuple[int, int, int]:
        raise ValueError("Insufficient header data")
    magic, version, flags, length = struct.unpack(">4sBBI", header_bytes[:HEADER_SIZE])
    if magic != JPEGIO_MAGIC:
-        raise ValueError(f"Invalid JPEG stego magic: {magic}")
+        raise InvalidMagicBytesError("Not a Stegasoo JPEG or wrong mode")
    return version, flags, length
@@ -436,7 +514,17 @@ def calculate_dct_capacity(image_data: bytes) -> DCTCapacityInfo:
    bits_per_block = len(DEFAULT_EMBED_POSITIONS)
    total_bits = total_blocks * bits_per_block
    total_bytes = total_bits // 8
-    usable_bytes = max(0, total_bytes - HEADER_SIZE)
+    # Account for header and RS overhead
    # RS format: [24-byte length prefix (3 copies)] + RS(header + data)
    # RS adds RS_NSYM bytes per 223-byte chunk (255 - RS_NSYM = 223)
    # Conservatively estimate RS overhead as ~15% + one chunk minimum
    if HAS_REEDSOLO:
        # Overhead = 24 (prefix) + 10 (header) + RS overhead
        # Simplify: base overhead = 24 + 10 + 32 + 15% margin for larger data
        overhead = RS_LENGTH_PREFIX_SIZE + HEADER_SIZE + RS_NSYM + 20
    else:
        overhead = HEADER_SIZE
    usable_bytes = max(0, total_bytes - overhead)
    return DCTCapacityInfo(
        width=width,
@@ -496,6 +584,7 @@ def embed_in_dct(
    seed: bytes,
    output_format: str = OUTPUT_FORMAT_PNG,
    color_mode: str = "color",
    progress_file: str | None = None,
 ) -> tuple[bytes, DCTEmbedStats]:
    """Embed data using DCT coefficient modification."""
    if output_format not in (OUTPUT_FORMAT_PNG, OUTPUT_FORMAT_JPEG):
@@ -505,10 +594,12 @@ def embed_in_dct(
        color_mode = "color"
    if output_format == OUTPUT_FORMAT_JPEG and HAS_JPEGIO:
-        return _embed_jpegio(data, carrier_image, seed, color_mode)
+        return _embed_jpegio(data, carrier_image, seed, color_mode, progress_file)
    _check_scipy()
-    return _embed_scipy_dct_safe(data, carrier_image, seed, output_format, color_mode)
+    return _embed_scipy_dct_safe(
        data, carrier_image, seed, output_format, color_mode, progress_file
    )
 def _embed_scipy_dct_safe(
@@ -517,6 +608,7 @@ def _embed_scipy_dct_safe(
    seed: bytes,
    output_format: str,
    color_mode: str = "color",
    progress_file: str | None = None,
 ) -> tuple[bytes, DCTEmbedStats]:
    """
    Embed using scipy DCT with safe memory handling.
@@ -538,9 +630,20 @@ def _embed_scipy_dct_safe(
    flags = FLAG_COLOR_MODE if color_mode == "color" else 0
-    # Prepare payload bits
+    # Build raw payload (header + data)
    header = _create_header(len(data), flags)
-    payload = header + data
+    raw_payload = header + data
    # Apply Reed-Solomon error correction to entire payload if available
    if HAS_REEDSOLO:
        rs_payload = _rs_encode(raw_payload)
        # Format: [length_header x 3 for majority voting] + [RS-encoded payload]
        # Each length_header is 8 bytes: 4 for raw_payload_length + 4 for rs_payload_length
        length_header = struct.pack(">II", len(raw_payload), len(rs_payload))
        length_prefix = length_header * RS_LENGTH_COPIES  # Repeat 3 times
        payload = length_prefix + rs_payload
    else:
        payload = raw_payload
    bits = []
    for byte in payload:
        for i in range(7, -1, -1):
@@ -568,7 +671,7 @@ def _embed_scipy_dct_safe(
        gc.collect()
        # Embed in Y channel
-        Y_embedded = _embed_in_channel_safe(Y_padded, bits, block_order, blocks_x)
+        Y_embedded = _embed_in_channel_safe(Y_padded, bits, block_order, blocks_x, progress_file)
        del Y_padded
        gc.collect()
@@ -592,7 +695,7 @@ def _embed_scipy_dct_safe(
        del image
        gc.collect()
-        embedded = _embed_in_channel_safe(padded, bits, block_order, blocks_x)
+        embedded = _embed_in_channel_safe(padded, bits, block_order, blocks_x, progress_file)
        del padded
        gc.collect()
@@ -625,6 +728,7 @@ def _embed_in_channel_safe(
    bits: list,
    block_order: list,
    blocks_x: int,
    progress_file: str | None = None,
 ) -> np.ndarray:
    """
    Embed bits in channel using safe DCT operations.
@@ -637,8 +741,9 @@ def _embed_in_channel_safe(
    result = np.array(channel, dtype=np.float64, copy=True, order="C")
    bit_idx = 0
    total_blocks = len(block_order)
-    for block_num in block_order:
+    for block_idx, block_num in enumerate(block_order):
        if bit_idx >= len(bits):
            break
@@ -674,6 +779,14 @@ def _embed_in_channel_safe(
        # Clean up this iteration
        del block, dct_block, modified_block
        # Report progress periodically
        if progress_file and block_idx % PROGRESS_INTERVAL == 0:
            _write_progress(progress_file, block_idx, total_blocks, "embedding")
    # Final progress update
    if progress_file:
        _write_progress(progress_file, total_blocks, total_blocks, "finalizing")
    # Force garbage collection
    gc.collect()
@@ -730,6 +843,7 @@ def _embed_jpegio(
    carrier_image: bytes,
    seed: bytes,
    color_mode: str = "color",
    progress_file: str | None = None,
 ) -> tuple[bytes, DCTEmbedStats]:
    """Embed using jpegio for proper JPEG coefficient modification."""
    import os
@@ -761,8 +875,19 @@ def _embed_jpegio(
        all_positions = _jpegio_get_usable_positions(coef_array)
        order = _jpegio_generate_order(len(all_positions), seed)
        # Build raw payload (header + data)
        header = _jpegio_create_header(len(data), flags)
-        payload = header + data
+        raw_payload = header + data
        # Apply Reed-Solomon error correction to entire payload if available
        if HAS_REEDSOLO:
            rs_payload = _rs_encode(raw_payload)
            # Format: [length_header x 3 for majority voting] + [RS-encoded payload]
            length_header = struct.pack(">II", len(raw_payload), len(rs_payload))
            length_prefix = length_header * RS_LENGTH_COPIES
            payload = length_prefix + rs_payload
        else:
            payload = raw_payload
        bits = []
        for byte in payload:
@@ -776,6 +901,9 @@ def _embed_jpegio(
            )
        coefs_used = 0
        total_bits = len(bits)
        progress_interval = max(total_bits // 20, 100)  # Report ~20 times or every 100 bits
        for bit_idx, pos_idx in enumerate(order):
            if bit_idx >= len(bits):
                break
@@ -791,6 +919,14 @@ def _embed_jpegio(
            coefs_used += 1
            # Report progress periodically
            if progress_file and bit_idx % progress_interval == 0:
                _write_progress(progress_file, bit_idx, total_bits, "embedding")
        # Final progress before save
        if progress_file:
            _write_progress(progress_file, total_bits, total_bits, "saving")
        jio.write(jpeg, output_path)
        with open(output_path, "rb") as f:
@@ -851,9 +987,12 @@ def _extract_scipy_dct_safe(stego_image: bytes, seed: bytes) -> bytes:
    del channel
    gc.collect()
-    h, w = padded.shape
+    # Use ORIGINAL image dimensions for block calculations (must match embed)
-    blocks_x = w // BLOCK_SIZE
+    # Embed uses width // BLOCK_SIZE, not padded width
-    num_blocks = (h // BLOCK_SIZE) * blocks_x
+    h, w = padded.shape  # Padded dimensions for bounds checking
    blocks_x = width // BLOCK_SIZE
    blocks_y = height // BLOCK_SIZE
    num_blocks = blocks_y * blocks_x
    block_order = _generate_block_order(num_blocks, seed)
@@ -883,12 +1022,80 @@ def _extract_scipy_dct_safe(stego_image: bytes, seed: bytes) -> bytes:
                total_needed = (HEADER_SIZE + data_length) * 8
                if len(all_bits) >= total_needed:
                    break
-            except ValueError:
+            except (ValueError, InvalidMagicBytesError):
-                pass
+                pass  # RS-protected format has length prefix first, not magic bytes
    del padded
    gc.collect()
    # Try RS-protected format first (has 24-byte length prefix: 3 copies of 8-byte header)
    if HAS_REEDSOLO and len(all_bits) >= RS_LENGTH_PREFIX_SIZE * 8:
        # Extract length prefix (24 bytes: 3 copies of 8-byte header for majority voting)
        length_prefix_bits = all_bits[: RS_LENGTH_PREFIX_SIZE * 8]
        length_prefix_bytes = bytes(
            [
                sum(length_prefix_bits[i * 8 : (i + 1) * 8][j] << (7 - j) for j in range(8))
                for i in range(RS_LENGTH_PREFIX_SIZE)
            ]
        )
        # Extract 3 copies and use majority voting
        copies = []
        for i in range(RS_LENGTH_COPIES):
            start = i * RS_LENGTH_HEADER_SIZE
            end = start + RS_LENGTH_HEADER_SIZE
            copies.append(length_prefix_bytes[start:end])
        # Count occurrences of each unique copy
        from collections import Counter
        counter = Counter(copies)
        best_header, count = counter.most_common(1)[0]
        # Only proceed if we have at least 2 matching copies (majority)
        if count >= 2:
            raw_payload_length, rs_encoded_length = struct.unpack(">II", best_header)
        else:
            # No majority - try first copy as fallback
            raw_payload_length, rs_encoded_length = struct.unpack(">II", copies[0])
        # Sanity check: both lengths should be reasonable
        max_reasonable = (len(all_bits) // 8) - RS_LENGTH_PREFIX_SIZE
        if (
            raw_payload_length > 0
            and raw_payload_length <= max_reasonable
            and rs_encoded_length > 0
            and rs_encoded_length <= max_reasonable
            and rs_encoded_length >= raw_payload_length
        ):
            # This looks like RS-protected format
            total_bits_needed = (RS_LENGTH_PREFIX_SIZE + rs_encoded_length) * 8
            if len(all_bits) >= total_bits_needed:
                rs_bits = all_bits[RS_LENGTH_PREFIX_SIZE * 8 : total_bits_needed]
                rs_encoded = bytes(
                    [
                        sum(rs_bits[i * 8 : (i + 1) * 8][j] << (7 - j) for j in range(8))
                        for i in range(rs_encoded_length)
                    ]
                )
                try:
                    # RS decode to get header + data
                    raw_payload = _rs_decode(rs_encoded)
                    # Parse header from decoded payload
                    _, flags, data_length = _parse_header(
                        [((raw_payload[i // 8] >> (7 - i % 8)) & 1) for i in range(HEADER_SIZE * 8)]
                    )
                    # Extract data
                    data = raw_payload[HEADER_SIZE : HEADER_SIZE + data_length]
                    return data
                except (ValueError, struct.error):
                    pass  # Fall through to legacy format
    # Legacy format: header not protected by RS
    _, flags, data_length = _parse_header(all_bits)
    data_bits = all_bits[HEADER_SIZE * 8 : (HEADER_SIZE + data_length) * 8]
@@ -919,6 +1126,77 @@ def _extract_jpegio(stego_image: bytes, seed: bytes) -> bytes:
        all_positions = _jpegio_get_usable_positions(coef_array)
        order = _jpegio_generate_order(len(all_positions), seed)
        # Try RS-protected format first (has 24-byte length prefix: 3 copies for majority voting)
        if HAS_REEDSOLO and len(all_positions) >= RS_LENGTH_PREFIX_SIZE * 8:
            # Extract length prefix (24 bytes: 3 copies of 8-byte header)
            length_prefix_bits = []
            for pos_idx in order[: RS_LENGTH_PREFIX_SIZE * 8]:
                row, col = all_positions[pos_idx]
                coef = coef_array[row, col]
                length_prefix_bits.append(coef & 1)
            length_prefix_bytes = bytes(
                [
                    sum(length_prefix_bits[i * 8 : (i + 1) * 8][j] << (7 - j) for j in range(8))
                    for i in range(RS_LENGTH_PREFIX_SIZE)
                ]
            )
            # Extract 3 copies and use majority voting
            from collections import Counter
            copies = []
            for i in range(RS_LENGTH_COPIES):
                start = i * RS_LENGTH_HEADER_SIZE
                end = start + RS_LENGTH_HEADER_SIZE
                copies.append(length_prefix_bytes[start:end])
            counter = Counter(copies)
            best_header, count = counter.most_common(1)[0]
            if count >= 2:
                raw_payload_length, rs_encoded_length = struct.unpack(">II", best_header)
            else:
                raw_payload_length, rs_encoded_length = struct.unpack(">II", copies[0])
            # Sanity check
            max_reasonable = (len(all_positions) // 8) - RS_LENGTH_PREFIX_SIZE
            if (
                raw_payload_length > 0
                and raw_payload_length <= max_reasonable
                and rs_encoded_length > 0
                and rs_encoded_length <= max_reasonable
                and rs_encoded_length >= raw_payload_length
            ):
                total_bits_needed = (RS_LENGTH_PREFIX_SIZE + rs_encoded_length) * 8
                if len(all_positions) >= total_bits_needed:
                    # Extract RS-encoded data
                    all_bits = []
                    for bit_idx, pos_idx in enumerate(order):
                        if bit_idx >= total_bits_needed:
                            break
                        row, col = all_positions[pos_idx]
                        coef = coef_array[row, col]
                        all_bits.append(coef & 1)
                    rs_bits = all_bits[RS_LENGTH_PREFIX_SIZE * 8 :]
                    rs_encoded = bytes(
                        [
                            sum(rs_bits[i * 8 : (i + 1) * 8][j] << (7 - j) for j in range(8))
                            for i in range(rs_encoded_length)
                        ]
                    )
                    try:
                        raw_payload = _rs_decode(rs_encoded)
                        _, flags, data_length = _jpegio_parse_header(raw_payload[:HEADER_SIZE])
                        data = raw_payload[HEADER_SIZE : HEADER_SIZE + data_length]
                        return data
                    except (ValueError, struct.error):
                        pass  # Fall through to legacy format
        # Legacy format: header not protected by RS
        header_bits = []
        for pos_idx in order[: HEADER_SIZE * 8]:
            row, col = all_positions[pos_idx]
@@ -933,7 +1211,6 @@ def _extract_jpegio(stego_image: bytes, seed: bytes) -> bytes:
        )
        _, flags, data_length = _jpegio_parse_header(header_bytes)
        total_bits_needed = (HEADER_SIZE + data_length) * 8
        all_bits = []
@@ -945,7 +1222,6 @@ def _extract_jpegio(stego_image: bytes, seed: bytes) -> bytes:
            all_bits.append(coef & 1)
        data_bits = all_bits[HEADER_SIZE * 8 :]
        data = bytes(
            [
                sum(data_bits[i * 8 : (i + 1) * 8][j] << (7 - j) for j in range(8))
--- a/Show More
+++ b/Show More
		`@@ -0,0 +1 @@`
							`6a7378172fc0ec37143720f09a4ca34e83ec2409893aa8cd79ace5b78a64276c`