Add Image Security Toolkit (tools)

Library:
- Add peek_image() to detect Stegasoo headers without decrypting

CLI:
- stegasoo tools capacity <image> - show LSB/DCT capacity
- stegasoo tools strip <image> - remove EXIF metadata
- stegasoo tools peek <image> - detect hidden data

API:
- POST /api/tools/capacity
- POST /api/tools/strip-metadata
- POST /api/tools/peek

WebUI:
- /tools page with tabbed interface (login required)
- Basic implementation - needs polish (dropzones, better results)

Architecture: Library -> CLI -> API -> WebUI pattern

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

PLAN-4.1.0.md

@@ -426,6 +426,23 @@ Or simpler: detect on startup, update schema automatically (current pattern).
 ## Progress
 
 - [x] Multi-User Support (commit 7b33501)
-- [ ] Channel Key QR (Web UI)
+- [x] Channel Key QR (Web UI) - added QR generator on About page
 - [x] CLI Channel Commands
-- [ ] Advanced Tools
+- [x] Saved Channel Keys (Web UI) - users can save/manage channel keys
+- [ ] Advanced Tools (in progress)
+
+---
+
+## Action Item: Architectural Review
+
+Review other modules for consistency with the Library → CLI → API → WebUI pattern:
+
+| Module | Library | CLI | API | WebUI | Notes |
+|--------|---------|-----|-----|-------|-------|
+| encode | ✓ | ✓ | ✓ | ✓ | Review for consistency |
+| decode | ✓ | ✓ | ✓ | ✓ | Review for consistency |
+| channel | ✓ | ✓ | - | ✓ | Needs API layer? |
+| tools | ✓ | WIP | ✓ | WIP | Building now |
+| generate | ✓ | ? | - | ✓ | CLI for credential gen? |
+
+Priority order: Developer/CLI → API integrator → WebUI end-user

frontends/web/app.py

@@ -1288,6 +1288,88 @@ def about():
     return render_template("about.html", has_argon2=has_argon2(), has_qrcode_read=HAS_QRCODE_READ)
 
 
+# ============================================================================
+# TOOLS ROUTES (v4.1.0)
+# ============================================================================
+
+
+@app.route("/tools")
+@login_required
+def tools():
+    """Advanced tools page."""
+    return render_template("tools.html", has_dct=has_dct_support())
+
+
+@app.route("/api/tools/capacity", methods=["POST"])
+@login_required
+def api_tools_capacity():
+    """Calculate image capacity for steganography."""
+    from stegasoo.dct_steganography import estimate_capacity_comparison
+
+    carrier = request.files.get("image")
+    if not carrier:
+        return jsonify({"success": False, "error": "No image provided"}), 400
+
+    try:
+        image_data = carrier.read()
+        result = estimate_capacity_comparison(image_data)
+        result["success"] = True
+        result["filename"] = carrier.filename
+        result["megapixels"] = round((result["width"] * result["height"]) / 1_000_000, 2)
+        return jsonify(result)
+    except Exception as e:
+        return jsonify({"success": False, "error": str(e)}), 400
+
+
+@app.route("/api/tools/strip-metadata", methods=["POST"])
+@login_required
+def api_tools_strip_metadata():
+    """Strip EXIF/metadata from image."""
+    import io
+
+    from stegasoo.utils import strip_image_metadata
+
+    image_file = request.files.get("image")
+    if not image_file:
+        return jsonify({"success": False, "error": "No image provided"}), 400
+
+    try:
+        image_data = image_file.read()
+        clean_data = strip_image_metadata(image_data, output_format="PNG")
+
+        buffer = io.BytesIO(clean_data)
+        filename = image_file.filename.rsplit(".", 1)[0] + "_clean.png"
+
+        return send_file(
+            buffer,
+            mimetype="image/png",
+            as_attachment=True,
+            download_name=filename
+        )
+    except Exception as e:
+        return jsonify({"success": False, "error": str(e)}), 400
+
+
+@app.route("/api/tools/peek", methods=["POST"])
+@login_required
+def api_tools_peek():
+    """Check if image contains Stegasoo header."""
+    from stegasoo.steganography import peek_image
+
+    image_file = request.files.get("image")
+    if not image_file:
+        return jsonify({"success": False, "error": "No image provided"}), 400
+
+    try:
+        image_data = image_file.read()
+        result = peek_image(image_data)
+        result["success"] = True
+        result["filename"] = image_file.filename
+        return jsonify(result)
+    except Exception as e:
+        return jsonify({"success": False, "error": str(e)}), 400
+
+
 # Add these two test routes anywhere in app.py after the app = Flask(...) line:
 
 

frontends/web/templates/base.html

@@ -38,6 +38,9 @@
                     <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">

frontends/web/templates/tools.html

@@ -0,0 +1,172 @@
+{% extends "base.html" %}
+
+{% block title %}Tools - Stegasoo{% endblock %}
+
+{% block content %}
+<div class="row justify-content-center">
+    <div class="col-lg-8">
+        <h4 class="mb-4"><i class="bi bi-tools me-2"></i>Image Security Toolkit</h4>
+
+        <!-- Tool Tabs -->
+        <ul class="nav nav-pills mb-4" role="tablist">
+            <li class="nav-item" role="presentation">
+                <button class="nav-link active" data-bs-toggle="pill" data-bs-target="#capacity" type="button">
+                    <i class="bi bi-rulers me-1"></i>Capacity
+                </button>
+            </li>
+            <li class="nav-item" role="presentation">
+                <button class="nav-link" data-bs-toggle="pill" data-bs-target="#strip" type="button">
+                    <i class="bi bi-eraser me-1"></i>Strip EXIF
+                </button>
+            </li>
+            <li class="nav-item" role="presentation">
+                <button class="nav-link" data-bs-toggle="pill" data-bs-target="#peek" type="button">
+                    <i class="bi bi-search me-1"></i>Peek
+                </button>
+            </li>
+        </ul>
+
+        <!-- Tab Content -->
+        <div class="tab-content">
+
+            <!-- Capacity Calculator -->
+            <div class="tab-pane fade show active" id="capacity" role="tabpanel">
+                <div class="card">
+                    <div class="card-body">
+                        <p class="text-muted mb-3">Check how much data can be hidden in an image.</p>
+
+                        <div class="mb-3">
+                            <input type="file" class="form-control" id="capacityFile" accept="image/*">
+                        </div>
+
+                        <div id="capacityResult" class="d-none">
+                            <table class="table table-sm table-dark mb-0">
+                                <tbody>
+                                    <tr>
+                                        <td class="text-muted">Image</td>
+                                        <td id="capFilename" class="font-monospace"></td>
+                                    </tr>
+                                    <tr>
+                                        <td class="text-muted">Dimensions</td>
+                                        <td><span id="capDimensions"></span> (<span id="capMegapixels"></span> MP)</td>
+                                    </tr>
+                                    <tr>
+                                        <td class="text-muted">LSB Capacity</td>
+                                        <td id="capLsb" class="text-success font-monospace"></td>
+                                    </tr>
+                                    <tr>
+                                        <td class="text-muted">DCT Capacity</td>
+                                        <td id="capDct" class="font-monospace"></td>
+                                    </tr>
+                                </tbody>
+                            </table>
+                        </div>
+                    </div>
+                </div>
+            </div>
+
+            <!-- Strip EXIF -->
+            <div class="tab-pane fade" id="strip" role="tabpanel">
+                <div class="card">
+                    <div class="card-body">
+                        <p class="text-muted mb-3">Remove metadata (camera info, GPS, timestamps) from images.</p>
+
+                        <form id="stripForm" action="{{ url_for('api_tools_strip_metadata') }}" method="POST" enctype="multipart/form-data">
+                            <div class="mb-3">
+                                <input type="file" class="form-control" name="image" id="stripFile" accept="image/*" required>
+                            </div>
+                            <button type="submit" class="btn btn-primary">
+                                <i class="bi bi-eraser me-1"></i>Strip & Download
+                            </button>
+                        </form>
+                    </div>
+                </div>
+            </div>
+
+            <!-- Peek (Header Detection) -->
+            <div class="tab-pane fade" id="peek" role="tabpanel">
+                <div class="card">
+                    <div class="card-body">
+                        <p class="text-muted mb-3">Check if an image contains Stegasoo hidden data (without decrypting).</p>
+
+                        <div class="mb-3">
+                            <input type="file" class="form-control" id="peekFile" accept="image/*">
+                        </div>
+
+                        <div id="peekResult" class="d-none">
+                            <div id="peekFound" class="alert alert-success d-none">
+                                <i class="bi bi-check-circle me-2"></i>
+                                <strong>Stegasoo data detected!</strong>
+                                <br><span class="text-muted">Mode: <span id="peekMode" class="font-monospace"></span></span>
+                            </div>
+                            <div id="peekNotFound" class="alert alert-secondary d-none">
+                                <i class="bi bi-x-circle me-2"></i>
+                                No Stegasoo header detected in this image.
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+
+        </div>
+    </div>
+</div>
+{% endblock %}
+
+{% block scripts %}
+<script>
+// Capacity Calculator
+document.getElementById('capacityFile')?.addEventListener('change', async function() {
+    const file = this.files[0];
+    if (!file) return;
+
+    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('capFilename').textContent = data.filename;
+            document.getElementById('capDimensions').textContent = `${data.width} x ${data.height}`;
+            document.getElementById('capMegapixels').textContent = data.megapixels;
+            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 (scipy required)';
+            document.getElementById('capacityResult').classList.remove('d-none');
+        }
+    } catch (err) {
+        console.error(err);
+    }
+});
+
+// Peek (Header Detection)
+document.getElementById('peekFile')?.addEventListener('change', async function() {
+    const file = this.files[0];
+    if (!file) return;
+
+    const formData = new FormData();
+    formData.append('image', file);
+
+    try {
+        const res = await fetch('/api/tools/peek', { method: 'POST', body: formData });
+        const data = await res.json();
+
+        document.getElementById('peekResult').classList.remove('d-none');
+
+        if (data.has_stegasoo) {
+            document.getElementById('peekFound').classList.remove('d-none');
+            document.getElementById('peekNotFound').classList.add('d-none');
+            document.getElementById('peekMode').textContent = data.mode?.toUpperCase() || 'Unknown';
+        } else {
+            document.getElementById('peekFound').classList.add('d-none');
+            document.getElementById('peekNotFound').classList.remove('d-none');
+        }
+    } catch (err) {
+        console.error(err);
+    }
+});
+</script>
+{% endblock %}

src/stegasoo/cli.py

@@ -782,6 +782,111 @@ def channel_clear(ctx, project, user):
             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()
+
+
 def main():
     """Entry point for CLI."""
     cli(obj={})

src/stegasoo/steganography.py

@@ -930,3 +930,82 @@ def is_lossless_format(image_data: bytes) -> bool:
     is_lossless = fmt is not None and fmt.upper() in LOSSLESS_FORMATS
     debug.print(f"Image is lossless: {is_lossless} (format: {fmt})")
     return is_lossless
+
+
+def peek_image(image_data: bytes) -> dict:
+    """
+    Check if an image contains Stegasoo hidden data without decrypting.
+
+    Attempts to detect LSB and DCT headers by extracting the first few bytes
+    and looking for Stegasoo magic markers.
+
+    Args:
+        image_data: Raw image bytes
+
+    Returns:
+        dict with:
+            - has_stegasoo: bool - True if header detected
+            - mode: str or None - 'lsb', 'dct', or None
+            - confidence: str - 'high', 'low', or None
+
+    Example:
+        >>> result = peek_image(suspicious_image_bytes)
+        >>> if result['has_stegasoo']:
+        ...     print(f"Found {result['mode']} data!")
+    """
+    from .constants import EMBED_MODE_DCT, EMBED_MODE_LSB
+
+    result = {"has_stegasoo": False, "mode": None, "confidence": None}
+
+    # Try LSB extraction (look for header bytes)
+    try:
+        img = Image.open(io.BytesIO(image_data))
+        pixels = list(img.getdata())
+        img.close()
+
+        # Extract first 32 bits (4 bytes) from LSB
+        extracted = []
+        for i in range(32):
+            if i < len(pixels):
+                pixel = pixels[i]
+                if isinstance(pixel, tuple):
+                    extracted.append(pixel[0] & 1)
+                else:
+                    extracted.append(pixel & 1)
+
+        # Convert bits to bytes
+        header_bytes = bytearray()
+        for i in range(0, len(extracted), 8):
+            byte = 0
+            for j in range(8):
+                if i + j < len(extracted):
+                    byte = (byte << 1) | extracted[i + j]
+            header_bytes.append(byte)
+
+        # Check for LSB magic: \x89ST3
+        if bytes(header_bytes[:4]) == b"\x89ST3":
+            result["has_stegasoo"] = True
+            result["mode"] = EMBED_MODE_LSB
+            result["confidence"] = "high"
+            return result
+    except Exception:
+        pass
+
+    # Try DCT extraction (requires scipy/jpegio)
+    try:
+        from .dct_steganography import HAS_JPEGIO, HAS_SCIPY
+
+        if HAS_SCIPY or HAS_JPEGIO:
+            from .dct_steganography import extract_from_dct
+
+            # Extract first few bytes to check header
+            extracted = extract_from_dct(image_data, seed=b"\x00" * 32, length=4)
+            if extracted == b"\x89DCT":
+                result["has_stegasoo"] = True
+                result["mode"] = EMBED_MODE_DCT
+                result["confidence"] = "high"
+                return result
+    except Exception:
+        pass
+
+    return result