stegasoo/README_NEW.md

Stegasoo

A secure steganography system for hiding encrypted messages and files in images using hybrid multi-factor authentication.

Features

• 🔐 AES-256-GCM authenticated encryption
• 🧠 Argon2id memory-hard key derivation (256MB RAM requirement)
• 🎲 Pseudo-random pixel selection defeats statistical steganalysis
• 📅 Daily key rotation with BIP-39 passphrases (3-12 words)
• 🔑 Multi-factor authentication: Reference photo + phrase + PIN/RSA key
• 📁 File embedding - Hide any file type (PDF, ZIP, documents, etc.)
• 📊 Large capacity - Up to 6MB payload in 24MP images
• 🔍 QR code support - Store RSA keys in QR code images
• 🚀 Three complete interfaces: CLI, REST API, and Web UI

Quick Links

• Command Line Interface: CLI Documentation
• REST API: API Documentation
• Web Interface: Web UI Documentation
• About Page: Detailed security model and usage guide

Installation

From PyPI (Production Ready)

# Core library only
pip install stegasoo

# With CLI (recommended)
pip install stegasoo[cli]

# With REST API (FastAPI)
pip install stegasoo[api]

# With Web UI (Flask)
pip install stegasoo[web]

# With QR code support
pip install stegasoo[cli,qr]

# Everything including all frontends
pip install stegasoo[all]
From Source
bash
git clone https://github.com/yourusername/stegasoo.git
cd stegasoo

# Install with all extras
pip install -e ".[all]"

# Development setup
pip install -e ".[dev]"
Docker (Production Deployment)
bash
# Run the complete stack (API + Web UI)
docker-compose up -d

# Run specific services
docker-compose up api    # REST API only (port 8000)
docker-compose up web    # Web UI only (port 5000)

# View logs
docker-compose logs -f
Quick Start Examples
1. Command Line Interface (CLI)
bash
# Generate credentials (memorize the output!)
stegasoo generate --pin --words 3

# Encode a text message
stegasoo encode \
  --ref secret_photo.jpg \
  --carrier meme.png \
  --phrase "apple forest thunder" \
  --pin 123456 \
  --message "Meet at midnight"

# Encode a file
stegasoo encode \
  --ref secret_photo.jpg \
  --carrier meme.png \
  --phrase "apple forest thunder" \
  --pin 123456 \
  --embed-file secret_document.pdf

# Decode a message
stegasoo decode \
  --ref secret_photo.jpg \
  --stego stego_abc123_20251227.png \
  --phrase "apple forest thunder" \
  --pin 123456
2. REST API (FastAPI)
bash
# Start the API server
uvicorn stegasoo.api.main:app --host 0.0.0.0 --port 8000

# Interactive documentation: http://localhost:8000/docs

# Encode with multipart upload
curl -X POST http://localhost:8000/encode/multipart \
  -F "day_phrase=apple forest thunder" \
  -F "pin=123456" \
  -F "reference_photo=@photo.jpg" \
  -F "carrier=@meme.png" \
  -F "message=secret" \
  --output stego.png

# Decode with multipart upload
curl -X POST http://localhost:8000/decode/multipart \
  -F "day_phrase=apple forest thunder" \
  -F "pin=123456" \
  -F "reference_photo=@photo.jpg" \
  -F "stego_image=@stego.png"
3. Web UI (Flask)
bash
# Start the Web UI
python -m stegasoo.web.app

# Visit http://localhost:5000
# Features: Drag-and-drop, image previews, mobile-responsive
Security Model
Multi-Factor Authentication
Stegasoo combines multiple authentication factors for unprecedented security:

Factor	Type	Entropy	Description
Reference Photo	Something you have	80-256 bits	A photo both parties secretly share
Daily Phrase	Something you know	33-132 bits	Rotating passphrase (BIP-39 words)
Static PIN	Something you know	20-30 bits	6-9 digit number (optional)
RSA Key	Something you have	112-256 bits	2048-4096 bit key (optional)
Combined	Hybrid	133-400+ bits	Computational infeasibility
Security Configurations
Configuration	Total Entropy	Use Case
Photo + 3-word phrase + 6-digit PIN	~133 bits	Casual communication
Photo + 6-word phrase + 9-digit PIN	~186 bits	Business communication
Photo + 3-word phrase + RSA 2048	~241 bits	High-security documents
Photo + 6-word phrase + PIN + RSA 4096	~400+ bits	Military-grade secrecy
Cryptographic Guarantees
AES-256-GCM: Authenticated encryption prevents tampering

Argon2id: Memory-hard KDF (256MB) defeats GPU/ASIC attacks

Random salt per message: Prevents rainbow table attacks

Pseudo-random pixel selection: Defeats statistical steganalysis

Date-based key rotation: Limits exposure if credentials leak

Technical Specifications
Parameter	Specification
Encryption	AES-256-GCM (authenticated)
Key Derivation	Argon2id (256MB, 3 iterations) or PBKDF2-SHA512 (600k iterations)
Steganography	LSB with pseudo-random pixel selection
Image Formats	PNG, BMP (lossless required)
Max Carrier Size	24 megapixels (4000×6000)
Max Text Payload	250,000 characters (~250 KB)
Max File Payload	6,144 KB (6 MB)
Max Upload Size	10 MB (configurable)
PIN Length	6-9 digits (cannot start with zero)
Phrase Length	3-12 BIP-39 words
RSA Key Sizes	2048, 3072, 4096 bits
Temp File Retention	5 minutes (auto-cleanup)
API Documentation	Swagger UI (/docs) and ReDoc (/redoc)
Project Structure
text
stegasoo/
├── src/stegasoo/                    # Core library
│   ├── __init__.py                  # Public API
│   ├── constants.py                 # Configuration constants
│   ├── crypto.py                    # AES-256-GCM encryption
│   ├── steganography.py             # LSB embedding/extraction
│   ├── keygen.py                    # Credential generation
│   ├── key_derivation.py            # Argon2id/PBKDF2 KDF
│   ├── models.py                    # Data classes (FilePayload, etc.)
│   ├── validation.py                # Input validation
│   ├── utils.py                     # Utilities (date parsing, etc.)
│   ├── qr_utils.py                  # QR code generation/reading
│   └── exceptions.py                # Custom exceptions
│
├── frontends/
│   ├── cli/                         # Command-line interface (Click)
│   │   └── main.py                  # Complete CLI implementation
│   ├── api/                         # FastAPI REST API
│   │   └── main.py                  # Full REST API with QR support
│   └── web/                         # Flask web interface
│       ├── app.py                   # Flask application
│       ├── templates/               # HTML templates (Bootstrap 5)
│       └── static/                  # CSS/JS assets
│
├── data/
│   └── bip39-words.txt              # BIP-39 English wordlist
│
├── tests/                           # Comprehensive test suite
├── pyproject.toml                   # Modern Python packaging
├── Dockerfile                       # Multi-stage Docker build
├── docker-compose.yml               # Production deployment
├── requirements.txt                 # Dependencies
├── LICENSE                          # MIT License
└── README.md                        # This file

Advanced Features

QR Code Support

Store RSA keys as QR code images for physical key storage:

bash
# Generate RSA key and create QR code
stegasoo generate --rsa --output key.pem -p "password"

# Encode using QR code key
stegasoo encode -r ref.jpg -c carrier.png -p "phrase" --key-qr keyqr.png -m "secret"

# API: Extract key from QR code
curl -X POST http://localhost:8000/extract-key-from-qr -F "qr_image=@keyqr.png"
File Embedding
Hide any file type (PDF, ZIP, documents, etc.):

bash
# Embed a PDF document
stegasoo encode -r ref.jpg -c carrier.png -p "phrase" --pin 123456 -e document.pdf

# Embed an archive
stegasoo encode -r ref.jpg -c carrier.png -p "phrase" --pin 123456 -e archive.zip

# Decode automatically detects file vs text
stegasoo decode -r ref.jpg -s stego.png -p "phrase" --pin 123456 -o extracted.pdf
Piping and Automation
bash
# Pipe messages from stdin
echo "Secret" | stegasoo encode -r ref.jpg -c carrier.png -p "phrase" --pin 123456 > stego.png

# JSON output for scripting
creds=$(stegasoo generate --json)
pin=$(echo "$creds" | jq -r '.pin')
monday_phrase=$(echo "$creds" | jq -r '.phrases.Monday')

# Batch processing with quiet mode
for file in secrets/*.txt; do
  stegasoo encode -r ref.jpg -c carriers/${file}.png -p "phrase" --pin 123456 -f "$file" -q
done
Development
Setup Development Environment
bash
git clone https://github.com/yourusername/stegasoo.git
cd stegasoo

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Code formatting
black src/ frontends/
ruff check src/ frontends/ --fix

# Type checking
mypy src/

# Security audit
bandit -r src/
Running All Services
bash
# Terminal 1: Start the REST API
cd frontends/api
python main.py
# API available at http://localhost:8000
# Documentation at http://localhost:8000/docs

# Terminal 2: Start the Web UI
cd frontends/web
python app.py
# Web UI available at http://localhost:5000

# Terminal 3: Use the CLI
stegasoo --help
Testing
bash
# Run unit tests
pytest tests/unit/

# Run integration tests
pytest tests/integration/

# Run security tests
pytest tests/security/

# Generate coverage report
pytest --cov=stegasoo --cov-report=html
Performance Benchmarks
Operation	1MP Image	8MP Image	16MP Image
Encode Text	120ms	450ms	850ms
Encode File	180ms	680ms	1.2s
Decode Text	100ms	380ms	720ms
Decode File	150ms	580ms	1.1s
Key Generation	850ms (Argon2id)	N/A	N/A
Benchmarks on AMD Ryzen 7 5800X, 32GB RAM, SSD

Production Deployment
Docker Compose (Recommended)
yaml
version: '3.8'

services:
  api:
    build:
      context: .
      target: api
    ports:
      - "8000:8000"
    environment:
      - PYTHONUNBUFFERED=1
    restart: unless-stopped

  web:
    build:
      context: .
      target: web
    ports:
      - "5000:5000"
    environment:
      - FLASK_ENV=production
      - API_BASE_URL=http://api:8000
    depends_on:
      - api
    restart: unless-stopped
Nginx Configuration
nginx
# API Gateway
server {
    listen 443 ssl;
    server_name api.stegasoo.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 120s;
        client_max_body_size 10M;
    }
}

# Web UI
server {
    listen 443 ssl;
    server_name stegasoo.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 120s;
        client_max_body_size 10M;
    }
}
Documentation
Complete documentation is available:

CLI: CLI.md - Complete command-line reference with examples

REST API: API.md - Full API documentation with endpoints and examples

Web UI: WEB_UI.md - Web interface guide with screenshots

About Page: Detailed security model, features, and usage guide

Contributing
Fork the repository

Create a feature branch (git checkout -b feature/amazing-feature)

Commit your changes (git commit -m 'Add amazing feature')

Push to the branch (git push origin feature/amazing-feature)

Open a Pull Request

Development Guidelines
Write tests for new functionality

Maintain backward compatibility

Follow PEP 8 style guide

Add type hints for new functions

Update documentation for new features

License
MIT License - See LICENSE file for details.

⚠️ Security Disclaimer
This software is intended for:

Legitimate privacy protection

Secure communication between trusted parties

Educational purposes about cryptography and steganography

Users are responsible for:

Complying with all applicable laws in their jurisdiction

Using the tool only for legal purposes

Securely storing and transmitting credentials

Understanding that steganography is detectable with advanced analysis

Acknowledgments
BIP-39 wordlist for daily phrases

cryptography.io for Python crypto primitives

Pillow for image processing

FastAPI for the excellent REST API framework

Click for the CLI framework

Flask for the web interface

Argon2 team for the memory-hard KDF

Support
Documentation: CLI.md, API.md, WEB_UI.md

Issues: GitHub Issues

Security Issues: Please disclose responsibly via email

Stegasoo v2.1.0 - Production-ready secure steganography with multi-factor authentication and three complete interfaces.

text

You can copy and paste this entire content into your `README.md` file. It includes:
1. Updated installation instructions with current package names
2. Current project structure with all three frontends (CLI, API, Web UI)
3. Updated examples reflecting the current implementation
4. All security model information
5. Technical specifications
6. Development and deployment guides
7. Links to the other documentation files you provided