fsteg 0.1.0__py3-none-any.whl

fsteg/__init__.py

@@ -0,0 +1,3 @@
+from .main import capacity, embed, extract, main
+
+__all__ = ["main", "embed", "extract", "capacity"]

fsteg/main.py

@@ -0,0 +1,318 @@
+#!/usr/bin/env python3
+"""
+FFT Block Steganography — hide text inside images
+==================================================
+Hides or extracts a UTF-8 text message by quantising the magnitudes of
+mid-frequency DFT coefficients inside every non-overlapping 8×8 block of
+the image's luma (Y) channel.
+
+Key features
+------------
+* Self-correcting embed: each block is verified through a uint8 round-trip
+  so decoded bits always match, even after saving as PNG.
+* CRC-32 integrity check on extraction.
+* 4-byte length prefix + 8-byte sentinel so extraction never needs to
+  know the message length in advance.
+* Works on PNG, BMP, TIFF (lossless formats). JPEG is not recommended
+  because re-encoding breaks the embedded bits.
+
+Usage
+-----
+  Embed:
+      python fft_steg.py embed  cover.png "Your secret message" stego.png
+      python fft_steg.py embed  cover.png "$(cat secret.txt)"  stego.png
+
+  Extract:
+      python fft_steg.py extract stego.png
+
+  Capacity check (see how many bytes an image can hold):
+      python fft_steg.py capacity image.png
+
+Dependencies: Pillow, numpy   (pip install Pillow numpy)
+"""
+
+import sys
+import struct
+import zlib
+import argparse
+import numpy as np
+from PIL import Image
+
+if sys.platform.startswith("win") and hasattr(sys.stdout, "reconfigure"):
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
+# ── tunables ───────────────────────────────────────────────────────────────────
+STEP        = 32      # quantisation step (must stay fixed between embed/extract)
+END_MARKER  = b"\x00\xFF\x00\xFF\xDE\xAD\xBE\xEF"  # 8-byte payload sentinel
+
+# Mid-frequency positions in an unshifted 8×8 DFT
+# DC (0,0) excluded; high-frequency corners avoided for robustness
+MID_FREQ = [
+    (1,0),(2,0),(3,0),
+    (0,1),(1,1),(2,1),(3,1),
+    (0,2),(1,2),(2,2),(3,2),
+    (0,3),(1,3),(2,3),
+]
+BITS_PER_BLOCK = len(MID_FREQ)   # 14 usable bits per 8×8 block
+
+# ── bit / byte helpers ─────────────────────────────────────────────────────────
+
+def _to_bits(data: bytes) -> list[int]:
+    bits = []
+    for byte in data:
+        for shift in range(7, -1, -1):
+            bits.append((byte >> shift) & 1)
+    return bits
+
+
+def _to_bytes(bits: list[int]) -> bytes:
+    out = bytearray()
+    for i in range(0, len(bits) - 7, 8):
+        byte = 0
+        for b in bits[i:i+8]:
+            byte = (byte << 1) | b
+        out.append(byte)
+    return bytes(out)
+
+
+def _conj(r: int, c: int) -> tuple[int, int]:
+    """Conjugate-symmetric DFT position (ensures real IFFT output)."""
+    return (8 - r) % 8, (8 - c) % 8
+
+
+def _capacity(channel: np.ndarray) -> int:
+    H, W = channel.shape
+    return (H // 8) * (W // 8) * BITS_PER_BLOCK
+
+# ── core block operations ──────────────────────────────────────────────────────
+
+def _embed_block(block: np.ndarray, bits: list) -> np.ndarray:
+    """
+    Embed up to BITS_PER_BLOCK bits into one 8×8 float block.
+
+    Uses a self-correcting loop: after embedding and doing an IFFT, the block
+    is converted to uint8 and back, then its DFT is re-examined.  Any
+    coefficient whose parity flipped during that round-trip is nudged one
+    quantisation level further from the boundary and the check is repeated
+    (up to 5 times, which is always sufficient in practice).
+    """
+    S = np.fft.fft2(block)
+
+    for _attempt in range(5):
+        # ── embed pass ──
+        for idx, (r, c) in enumerate(MID_FREQ):
+            bit = bits[idx]
+            if bit is None:
+                continue
+            cr, cc  = _conj(r, c)
+            mag     = abs(S[r, c])
+            phase   = np.angle(S[r, c])
+            q       = round(mag / STEP)
+            if bit == 1:
+                if q % 2 == 0: q += 1
+            else:
+                if q % 2 == 1: q += 1
+            nm = max(q * STEP, STEP)
+            S[r,  c]  = nm * np.exp( 1j * phase)
+            S[cr, cc] = nm * np.exp(-1j * phase)
+
+        # ── uint8 round-trip check ──
+        pixels   = np.clip(np.fft.ifft2(S).real, 0, 255)
+        pixels8  = pixels.astype(np.uint8).astype(float)
+        S_rt     = np.fft.fft2(pixels8)
+
+        all_ok = True
+        for idx, (r, c) in enumerate(MID_FREQ):
+            bit = bits[idx]
+            if bit is None:
+                continue
+            q_rt = round(abs(S_rt[r, c]) / STEP)
+            if q_rt % 2 != bit:
+                # Parity flipped — nudge this coefficient one step further
+                all_ok  = False
+                cr, cc  = _conj(r, c)
+                phase   = np.angle(S_rt[r, c])
+                q_fix   = q_rt + 1
+                if q_fix % 2 != bit: q_fix += 1
+                nm = max(q_fix * STEP, STEP)
+                # Update S from the round-tripped version so corrections stack
+                S[r,  c]  = nm * np.exp( 1j * phase)
+                S[cr, cc] = nm * np.exp(-1j * phase)
+
+        if all_ok:
+            break
+
+    return np.fft.ifft2(S).real
+
+
+def _decode_block(block: np.ndarray) -> list[int]:
+    """Read BITS_PER_BLOCK embedded bits from one 8×8 float block."""
+    S = np.fft.fft2(block)
+    return [round(abs(S[r, c]) / STEP) % 2 for r, c in MID_FREQ]
+
+# ── high-level API ─────────────────────────────────────────────────────────────
+
+def embed(cover_path: str, message: str, output_path: str) -> None:
+    """Embed *message* into *cover_path* and write the stego image to *output_path*."""
+
+    img   = Image.open(cover_path).convert("YCbCr")
+    arr   = np.array(img, dtype=float)          # H × W × 3  (Y, Cb, Cr)
+    y_arr = arr[:, :, 0]
+
+    # ── build payload: CRC32 | length | UTF-8 text | sentinel ──
+    msg_bytes = message.encode("utf-8")
+    crc       = zlib.crc32(msg_bytes) & 0xFFFFFFFF
+    payload   = struct.pack(">II", crc, len(msg_bytes)) + msg_bytes + END_MARKER
+    all_bits  = _to_bits(payload)
+
+    cap = _capacity(y_arr)
+    if len(all_bits) > cap:
+        max_msg = (cap // 8) - len(END_MARKER) - 8   # 8 bytes = crc + length
+        raise ValueError(
+            f"Message too long ({len(msg_bytes)} bytes encoded to {len(all_bits)} bits).\n"
+            f"This image can hide at most ~{max_msg} bytes of text."
+        )
+
+    H, W      = y_arr.shape
+    stego_y   = y_arr.copy()
+    bits_iter = iter(all_bits)
+
+    for i in range(H // 8):
+        for j in range(W // 8):
+            # Collect this block's worth of bits (pad with None at the end)
+            block_bits = []
+            for _ in MID_FREQ:
+                try:    block_bits.append(next(bits_iter))
+                except StopIteration: block_bits.append(None)
+
+            block    = y_arr[i*8:(i+1)*8, j*8:(j+1)*8].copy()
+            modified = _embed_block(block, block_bits)
+            stego_y[i*8:(i+1)*8, j*8:(j+1)*8] = np.clip(modified, 0, 255)
+
+    # ── reconstruct and save ──
+    arr[:, :, 0] = stego_y
+    stego_img    = Image.fromarray(arr.clip(0, 255).astype(np.uint8), "YCbCr")
+    stego_img.convert("RGB").save(output_path)
+
+    max_delta = np.abs(stego_y - y_arr).max()
+    pct_used  = 100 * len(all_bits) / cap
+    print(f"[✓] Message embedded successfully → '{output_path}'")
+    print(f"    Hidden text size     : {len(msg_bytes)} bytes")
+    print(f"    Bits written         : {len(all_bits)}")
+    print(f"    Image capacity used  : {pct_used:.1f}%  ({len(all_bits)}/{cap} bits)")
+    print(f"    Max luma pixel shift : {max_delta:.2f} / 255")
+
+
+def extract(stego_path: str) -> str:
+    """Extract and return the hidden UTF-8 message from *stego_path*."""
+
+    img   = Image.open(stego_path).convert("YCbCr")
+    y_arr = np.array(img, dtype=float)[:, :, 0]
+    H, W  = y_arr.shape
+
+    all_bits = []
+    for i in range(H // 8):
+        for j in range(W // 8):
+            block = y_arr[i*8:(i+1)*8, j*8:(j+1)*8]
+            all_bits.extend(_decode_block(block))
+
+    raw = _to_bytes(all_bits)
+
+    # ── locate sentinel ──
+    pos = raw.find(END_MARKER)
+    if pos < 0:
+        raise ValueError(
+            "No hidden message found.  The image may not contain one, "
+            "or it was saved with lossy compression (e.g. JPEG)."
+        )
+
+    if pos < 8:
+        raise ValueError("Payload header is truncated — cannot extract message.")
+
+    # ── parse header: CRC (4 bytes) + length (4 bytes) ──
+    stored_crc, msg_len = struct.unpack(">II", raw[:8])
+    msg_bytes = raw[8 : 8 + msg_len]
+
+    if len(msg_bytes) < msg_len:
+        raise ValueError(
+            f"Payload truncated: expected {msg_len} bytes, recovered {len(msg_bytes)}."
+        )
+
+    # ── integrity check ──
+    actual_crc = zlib.crc32(msg_bytes) & 0xFFFFFFFF
+    if actual_crc != stored_crc:
+        raise ValueError(
+            f"CRC-32 mismatch (stored {stored_crc:#010x}, computed {actual_crc:#010x}). "
+            "The image may have been modified after embedding."
+        )
+
+    return msg_bytes.decode("utf-8")
+
+
+def capacity(image_path: str) -> None:
+    """Print the hiding capacity of an image."""
+    img   = Image.open(image_path)
+    w, h  = img.size
+    cap   = (h // 8) * (w // 8) * BITS_PER_BLOCK
+    overhead = len(END_MARKER) + 8    # sentinel + crc + length
+    usable   = cap // 8 - overhead
+    print(f"Image size    : {w} × {h} px")
+    print(f"8×8 blocks    : {(h//8) * (w//8)}")
+    print(f"Total capacity: {cap} bits  ({cap//8} bytes)")
+    print(f"Usable for text: ~{usable} bytes  (~{usable} UTF-8 characters)")
+
+# ── CLI ────────────────────────────────────────────────────────────────────────
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="FFT block steganography — hide text inside images.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    em = sub.add_parser("embed",    help="Embed a message into a cover image.")
+    em.add_argument("cover",   help="Input cover image (PNG/BMP/TIFF recommended).")
+    em.add_argument("message", help='Text to hide. Wrap in quotes: "Hello world"')
+    em.add_argument("output",  help="Output stego image (e.g. stego.png).")
+
+    ex = sub.add_parser("extract", help="Extract a hidden message from a stego image.")
+    ex.add_argument("stego", help="Stego image to read from.")
+
+    cap = sub.add_parser("capacity", help="Show the hiding capacity of an image.")
+    cap.add_argument("image", help="Image file to inspect.")
+
+    args = parser.parse_args()
+
+    if args.cmd == "embed":
+        try:
+            embed(args.cover, args.message, args.output)
+        except Exception as exc:
+            print(f"[✗] Embed failed: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    elif args.cmd == "extract":
+        try:
+            msg = extract(args.stego)
+            print("[✓] Hidden message extracted:")
+            print()
+            print(msg)
+        except Exception as exc:
+            print(f"[✗] Extract failed: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    elif args.cmd == "capacity":
+        try:
+            capacity(args.image)
+        except Exception as exc:
+            print(f"[✗] {exc}", file=sys.stderr)
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
+

fsteg-0.1.0.dist-info/METADATA

@@ -0,0 +1,512 @@
+Metadata-Version: 2.5
+Name: fsteg
+Version: 0.1.0
+Summary: High-fidelity FFT block-based frequency domain steganography CLI & library
+Project-URL: Homepage, https://github.com/Kishan-Agarwal-28/fsteg
+Project-URL: Repository, https://github.com/Kishan-Agarwal-28/fsteg.git
+Project-URL: Issues, https://github.com/Kishan-Agarwal-28/fsteg/issues
+Author-email: Kishan Agarwal <kishanagarwal028@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: block,cli,dft,fft,frequency-domain,image,security,steganography
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: Image Processing
+Classifier: Topic :: Security
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: numpy>=2.4.6
+Requires-Dist: pillow>=12.3.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# 🛰️ fsteg — FFT Block-Based Frequency Domain Steganography
+
+[![Python Version](https://img.shields.io/badge/Python-3.11%2B-blue.svg?logo=python&logoColor=white)](https://python.org)
+[![Fast Fourier Transform](https://img.shields.io/badge/Algorithm-2D--FFT%20%2F%20DFT-orange.svg)](https://en.wikipedia.org/wiki/Discrete_Fourier_transform)
+[![Integrity Validation](https://img.shields.io/badge/Integrity-CRC--32-green.svg)](https://en.wikipedia.org/wiki/Cyclic_redundancy_check)
+[![Package Manager](https://img.shields.io/badge/uv-compatible-purple.svg?logo=astral)](https://github.com/astral-sh/uv)
+[![License](https://img.shields.io/badge/License-MIT-lightgrey.svg)](LICENSE)
+
+A high-fidelity, frequency-domain steganography engine in Python. **`fsteg`** embeds arbitrary UTF-8 text messages inside digital images by quantising the magnitude spectrum of mid-frequency Discrete Fourier Transform (DFT) coefficients across non-overlapping $8 \times 8$ blocks of the image's luma ($Y$) channel.
+
+Unlike naive spatial-domain steganography (such as LSB substitution) which can be trivially detected via statistical histograms or chi-squared attacks, `fsteg` distributes the secret signal across orthogonal 2D sinusoidal basis functions. It features an adaptive **self-correcting round-trip verification engine** that resolves spatial discretization and clipping errors, ensuring 100% bit recovery upon extraction.
+
+---
+
+## 📑 Table of Contents
+
+- [Motivation & Comparison](#-motivation--comparison)
+- [Key Features](#-key-features)
+- [System Architecture & Theory](#-system-architecture--theory)
+  - [1. YCbCr Luma Channel Isolation](#1-ycbcr-luma-channel-isolation)
+  - [2. 8×8 Block Tiling & 2D Discrete Fourier Transform](#2-88-block-tiling--2d-discrete-fourier-transform)
+  - [3. Mid-Frequency Coefficient Selection](#3-mid-frequency-coefficient-selection)
+  - [4. Hermitian (Conjugate) Symmetry Enforcement](#4-hermitian-conjugate-symmetry-enforcement)
+  - [5. Quantization Index Modulation (QIM)](#5-quantization-index-modulation-qim)
+  - [6. The Self-Correcting uint8 Round-Trip Loop](#6-the-self-correcting-uint8-round-trip-loop)
+- [Protocol & Binary Framing](#-protocol--binary-framing)
+- [Payload Capacity & Sizing Guide](#-payload-capacity--sizing-guide)
+- [Installation & Setup](#-installation--setup)
+- [CLI Reference & Usage](#-cli-reference--usage)
+  - [Check Capacity](#1-check-image-capacity)
+  - [Embed Message](#2-embed-a-message)
+  - [Extract Message](#3-extract-a-hidden-message)
+- [Programmatic Python API](#-programmatic-python-api)
+- [Lossless vs. Lossy Carrier Formats](#-lossless-vs-lossy-carrier-formats)
+- [Security & Operational Best Practices](#-security--operational-best-practices)
+- [Troubleshooting & FAQs](#-troubleshooting--faqs)
+- [Project Layout](#-project-layout)
+- [License](#-license)
+
+---
+
+## 💡 Motivation & Comparison
+
+| Characteristic | Spatial LSB Substitution | Frequency-Domain (`fsteg` FFT) |
+| :--- | :--- | :--- |
+| **Embedding Domain** | Spatial pixel intensity bitplanes | 2D Fourier magnitude spectrum |
+| **Perceptual Invisibility** | High in high-noise regions; poor in smooth gradients | Outstanding across all image regions |
+| **Statistical Steganalysis** | Vulnerable to Chi-Square, RS analysis, and Sample Pair Analysis | Resilient to spatial histogram and pixel-difference steganalysis |
+| **Energy Distribution** | Confined to individual pixels | Dispersed over entire $8 \times 8$ spatial block |
+| **Bit-Discretization Handling** | Trivial (direct integer manipulation) | **Self-correcting iterative feedback loop** |
+| **Integrity Assurance** | Often none (raw bit insertion) | Built-in **CRC-32 checksum** with length header & sentinel |
+
+---
+
+## ✨ Key Features
+
+- **Adaptive Self-Correction**: When floating-point Inverse FFT values are clipped to $[0, 255]$ and discretized to `uint8`, quantization noise can invert frequency coefficient parities. `fsteg` simulates this round-trip on each block up to 5 times, iteratively nudging coefficients away from decision boundaries until convergence is achieved.
+- **Hermitian Conjugate Symmetry Preservation**: Automatically mirrors spectral modifications to conjugate coordinates $(8-r, 8-c)$, guaranteeing that the inverse transform remains strictly real-valued without imaginary artifacts.
+- **Mid-Frequency Band Allocation**: Exactly 14 bits embedded per $8 \times 8$ block. Low-frequency DC $(0,0)$ is preserved to avoid perceptual shifts in luminance, and extreme high-frequency corners are avoided for stability.
+- **Blind Extraction**: Embeds a 4-byte big-endian message length prefix and an 8-byte hexadecimal end marker (`0x00FF00FFDEADBEEF`), eliminating the need for the receiver to know payload length beforehand.
+- **Tamper Detection via CRC-32**: Automatically computes and verifies an IEEE 802.3 32-bit CRC. Extraction aborts with an informative diagnostic error if the payload was modified or corrupted.
+
+---
+
+## 🔬 System Architecture & Theory
+
+```
+[ Cover Image ] ──────► Convert to YCbCr ──────► Extract Y Channel (Luma)
+                                                         │
+                                               Partition into 8×8 Blocks
+                                                         │
+[ Secret Message ]                                       ▼
+        │                              ┌───────────────────────────────────┐
+Compute CRC-32 + Pack Length Prefix    │ For each 8×8 block:               │
+        │                              │  1. Compute 2D FFT: S = FFT2(B)   │
+        ▼                              │  2. Quantize 14 mid-freq coefs    │
+[ Payload Stream + 8-Byte Sentinel ] ─►│  3. Enforce conjugate symmetry    │
+                                       │  4. Run self-correcting IFFT loop │
+                                       └───────────────────────────────────┘
+                                                         │
+                                              Reassemble Stego Y Channel
+                                                         │
+[ Stego Image ] ◄────── Convert to RGB ◄──────── Merge Y with original Cb, Cr
+```
+
+### 1. YCbCr Luma Channel Isolation
+The human visual system (HVS) possesses significantly greater sensitivity to variations in luminance than to chromaticity (color difference). `fsteg` transforms the input cover image from RGB to YCbCr:
+
+$$Y = 0.299\,R + 0.587\,G + 0.114\,B$$
+
+The embedding logic is applied **exclusively to the $Y$ (luma) channel**, while $Cb$ and $Cr$ remain unchanged, minimizing perceptible color cast.
+
+### 2. 8×8 Block Tiling & 2D Discrete Fourier Transform
+The luminance plane $Y$ is tiled into non-overlapping blocks $B_{i, j}$ of dimension $8 \times 8$ pixels ($0 \le m, n \le 7$). The 2D Discrete Fourier Transform converts each spatial block into its 2D spectral components:
+
+$$S[u, v] = \sum_{m=0}^{7} \sum_{n=0}^{7} B[m, n] \cdot e^{-j 2\pi \left( \frac{um}{8} + \frac{vn}{8} \right)}$$
+
+Each complex coefficient $S[u, v]$ possesses a magnitude $M = |S[u, v]|$ and phase $\phi = \arg(S[u, v])$.
+
+### 3. Mid-Frequency Coefficient Selection
+Each $8 \times 8$ block holds exactly **14 usable bits**. The coordinates selected in the unshifted DFT matrix are:
+
+```
+        v ->   0      1      2      3      4      5      6      7
+   u +------------------------------------------------------------
+   0 |        DC    bit3   bit7  bit11     .      .      .      .
+   1 |      bit0    bit4   bit8  bit12     .      .      .      .
+   2 |      bit1    bit5   bit9  bit13     .      .      .      .
+   3 |      bit2    bit6  bit10     .      .      .      .      .
+   4 |         .       .      .     .      .      .      .      .
+   5 |         .       .      .     .      .      .      .      .
+   6 |         .       .      .     .      .      .      .      .
+   7 |         .       .      .     .      .      .      .      .
+```
+
+- **DC component $(0, 0)$ is omitted**: Modifying DC alters the average block brightness, leading to blocky artifacts.
+- **High frequencies are omitted**: High frequencies carry little energy and are vulnerable to mild spatial perturbations.
+- **Selected coordinates**: `(1,0), (2,0), (3,0), (0,1), (1,1), (2,1), (3,1), (0,2), (1,2), (2,2), (3,2), (0,3), (1,3), (2,3)`.
+
+### 4. Hermitian (Conjugate) Symmetry Enforcement
+Because spatial pixel values are real numbers, their Fourier transform must satisfy Hermitian symmetry:
+
+$$S[(8 - u) \pmod 8, (8 - v) \pmod 8] = S^*[u, v]$$
+
+Whenever the magnitude at $(u, v)$ is altered, `fsteg` calculates the conjugate coordinate $(u^*, v^*) = ((8-u)\%8, (8-v)\%8)$ and assigns:
+
+$$S[u, v] = M_{\text{new}} \cdot e^{j \phi}, \qquad S[u^*, v^*] = M_{\text{new}} \cdot e^{-j \phi}$$
+
+This prevents the Inverse FFT from producing non-zero imaginary residuals.
+
+### 5. Quantization Index Modulation (QIM)
+A uniform quantizer with step size $\Delta = 32$ is applied to coefficient magnitudes:
+
+$$q = \text{round}\left(\frac{|S[u, v]|}{\Delta}\right)$$
+
+Data bits are encoded into the **parity** of the quantization integer $q$:
+- **Bit 1**: $q$ must be **odd** ($q \pmod 2 = 1$). If even, $q \leftarrow q + 1$.
+- **Bit 0**: $q$ must be **even** ($q \pmod 2 = 0$). If odd, $q \leftarrow q + 1$.
+
+The modulated magnitude is computed as $M' = \max(q \cdot \Delta, \Delta)$, preserving original phase $\phi$.
+
+### 6. The Self-Correcting uint8 Round-Trip Loop
+A common point of failure in frequency-domain steganography is the conversion back to the spatial integer domain:
+
+$$\text{pixels} = \text{clip}\left(\text{Re}(\text{IFFT2}(S)), 0, 255\right) \xrightarrow{\text{round}} \text{uint8}$$
+
+Quantization to 8-bit integers and edge clipping introduces broadband spatial noise $e[m, n]$. When taking $\text{FFT2}(\text{pixels}_{\text{uint8}})$, the reconstructed magnitude $M_{\text{rt}}$ may shift across the decision boundary:
+
+$$\text{round}\left(\frac{M_{\text{rt}}}{\Delta}\right) \pmod 2 \neq \text{embedded bit}$$
+
+To solve this, `fsteg` implements an **iterative self-correction feedback loop** in `_embed_block()`:
+1. Synthesizes spatial block via `ifft2` and converts to `uint8`.
+2. Computes `fft2` on the quantized `uint8` block to check the recovered parity.
+3. For any coefficient where parity flipped, nudges the quantization level $q_{\text{fix}}$ further away from the decision boundary.
+4. Updates the spectral matrix and repeats (converges in 1–2 iterations, guaranteed within 5 passes).
+
+---
+
+## 📦 Protocol & Binary Framing
+
+The binary payload is structured with strict network big-endian serialization:
+
+```
+ 0                   1                   2                   3
+ 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                       CRC-32 (4 Bytes)                        |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                  Payload Length L (4 Bytes)                   |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                                                               |
++                    Payload Data (L Bytes)                     +
+|                                                               |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+|                                                               |
++              Sentinel (8 Bytes: 0x00FF00FFDEADBEEF)           +
+|                                                               |
++-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+```
+
+- **CRC-32** (4 bytes, `uint32_t`, big-endian): Verifies payload authenticity.
+- **Length $L$** (4 bytes, `uint32_t`, big-endian): Byte length of the UTF-8 text string.
+- **Payload** ($L$ bytes): Raw UTF-8 encoded text.
+- **Sentinel** (8 bytes): `\x00\xFF\x00\xFF\xDE\xAD\xBE\xEF` used to demarcate end of payload during streaming extraction.
+- **Fixed Framing Overhead**: $4 + 4 + 8 = 16\text{ bytes}$ ($128\text{ bits}$).
+
+---
+
+## 📊 Payload Capacity & Sizing Guide
+
+The maximum data that can be embedded in an image depends strictly on its pixel dimensions:
+
+$$\text{Capacity}_{\text{raw}} = \left\lfloor\frac{H}{8}\right\rfloor \times \left\lfloor\frac{W}{8}\right\rfloor \times 14\text{ bits}$$
+
+$$\text{Capacity}_{\text{usable}} \approx \left\lfloor\frac{\text{Capacity}_{\text{raw}}}{8}\right\rfloor - 16\text{ bytes}$$
+
+### Reference Table
+
+| Resolution | Dimensions ($W \times H$) | $8 \times 8$ Blocks | Raw Capacity (Bits) | Usable Capacity (Bytes) | Typical Payload Fit |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Small Avatar** | $256 \times 256$ | $1,024$ | $14,336$ | **$1,776$ B** | Small paragraphs, private keys |
+| **Standard** | $512 \times 512$ | $4,096$ | $57,344$ | **$7,152$ B** | Multi-page text, code snippets |
+| **HD 720p** | $1280 \times 720$ | $14,400$ | $201,600$ | **$25,184$ B** | Short articles, scripts |
+| **Full HD 1080p** | $1920 \times 1080$ | $32,400$ | $453,600$ | **$56,684$ B** | Complete document / chapter |
+| **CTF Sample** | $2500 \times 1343$ | $52,104$ | $729,456$ | **$91,166$ B** | Comprehensive archive, book chapter |
+| **4K UHD** | $3840 \times 2160$ | $129,600$ | $1,814,400$ | **$226,784$ B** | Medium-length novella |
+
+---
+
+---
+
+## 🚀 Installation & Setup
+
+### ⚡ One-Line Standalone Install (No Python Required)
+
+#### Linux & macOS:
+```bash
+curl -fsSL https://raw.githubusercontent.com/Kishan-Agarwal-28/fsteg/main/scripts/install.sh | bash
+```
+
+#### Windows (PowerShell):
+```powershell
+irm https://raw.githubusercontent.com/Kishan-Agarwal-28/fsteg/main/scripts/install.ps1 | iex
+```
+
+---
+
+### 📦 System Package Managers
+
+#### Python Package Index (PyPI):
+```bash
+pip install fsteg
+# or via uv:
+uv tool install fsteg
+```
+
+#### Homebrew (macOS & Linux):
+```bash
+brew tap Kishan-Agarwal-28/tap
+brew install fsteg
+```
+
+#### Chocolatey (Windows):
+```powershell
+choco install fsteg
+```
+
+#### Scoop (Windows):
+```powershell
+scoop install https://github.com/Kishan-Agarwal-28/fsteg/releases/latest/download/fsteg.json
+```
+
+#### Windows Package Manager (WinGet):
+```powershell
+winget install fsteg
+```
+
+#### Debian / Ubuntu (APT):
+```bash
+# Download latest .deb from GitHub Releases
+curl -LO https://github.com/Kishan-Agarwal-28/fsteg/releases/latest/download/fsteg_amd64.deb
+sudo dpkg -i fsteg_amd64.deb
+```
+
+#### Arch Linux (AUR / Pacman):
+```bash
+# Using makepkg from release PKGBUILD:
+curl -LO https://github.com/Kishan-Agarwal-28/fsteg/releases/latest/download/PKGBUILD
+makepkg -si
+```
+
+---
+
+### 🛠️ Developer Setup (from source)
+
+#### Using `uv`:
+```bash
+git clone https://github.com/Kishan-Agarwal-28/fsteg.git
+cd fsteg
+uv sync
+uv run fsteg --help
+```
+
+#### Using `pip` and `venv`:
+```bash
+git clone https://github.com/Kishan-Agarwal-28/fsteg.git
+cd fsteg
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\Activate.ps1
+pip install -e .
+```
+
+---
+
+## 💻 CLI Reference & Usage
+
+`main.py` provides a clean command-line interface with three primary subcommands:
+
+```
+usage: main.py [-h] {embed,extract,capacity} ...
+```
+
+### 1. Check Image Capacity
+Determine the exact number of bytes a carrier image can accommodate before attempting to embed:
+
+```bash
+# Usage: python main.py capacity <image_path>
+python main.py capacity cover.png
+```
+
+**Example Output:**
+```text
+Image size    : 1920 × 1080 px
+8×8 blocks    : 32400
+Total capacity: 453600 bits  (56700 bytes)
+Usable for text: ~56684 bytes  (~56684 UTF-8 characters)
+```
+
+---
+
+### 2. Embed a Message
+Embed a string or file content into a cover image and write the resulting stego image.
+
+#### Single-line string:
+```bash
+# Usage: python main.py embed <cover_image> "<message>" <output_image>
+python main.py embed cover.png "Project Titan: Launch window confirmed for 0400 UTC." stego.png
+```
+
+#### Multi-line text or file contents:
+```bash
+# Linux / macOS (Bash):
+python main.py embed cover.png "$(cat classified_brief.txt)" stego.png
+
+# Windows (PowerShell):
+python main.py embed cover.png (Get-Content -Raw classified_brief.txt) stego.png
+```
+
+**Example Output:**
+```text
+[✓] Message embedded successfully → 'stego.png'
+    Hidden text size     : 48 bytes
+    Bits written         : 512
+    Image capacity used  : 0.1%  (512/453600 bits)
+    Max luma pixel shift : 2.84 / 255
+```
+
+---
+
+### 3. Extract a Hidden Message
+Recover and verify the concealed payload from a stego image:
+
+```bash
+# Usage: python main.py extract <stego_image>
+python main.py extract stego.png
+```
+
+**Example Output:**
+```text
+[✓] Hidden message extracted:
+
+Project Titan: Launch window confirmed for 0400 UTC.
+```
+
+---
+
+## 🐍 Programmatic Python API
+
+You can also import `fsteg` as a module directly inside your Python projects or automated scripts:
+
+```python
+from main import embed, extract, capacity
+
+# 1. Inspect image hiding headroom
+capacity("carrier.png")
+
+# 2. Embed secret data
+secret_message = "Confidential coordinates: 37.7749° N, 122.4194° W"
+embed(
+    cover_path="carrier.png",
+    message=secret_message,
+    output_path="carrier_stego.png"
+)
+
+# 3. Extract and verify data
+recovered = extract("carrier_stego.png")
+print("Recovered Message:", recovered)
+assert recovered == secret_message
+```
+
+---
+
+## 🖼️ Lossless vs. Lossy Carrier Formats
+
+> [!IMPORTANT]
+> Always use **lossless image formats** such as **PNG**, **BMP**, or **TIFF** for `fsteg`.
+
+### Why JPEG Re-Encoding Fails
+Standard JPEG compression operates by partitioning images into $8 \times 8$ blocks, computing the Discrete Cosine Transform (DCT), and dividing by a lossy quantization table:
+
+$$C_{\text{quantized}}[u, v] = \text{round}\left(\frac{C_{\text{DCT}}[u, v]}{Q[u, v]}\right)$$
+
+This step discards subtle high- and mid-frequency fluctuations to minimize file size. This lossy quantization corrupts the precise DFT magnitude parities established by `fsteg`, resulting in CRC mismatch or an undetectable sentinel. 
+
+*(Note: If a JPEG carrier is saved at uncompressed/maximum 100% quality settings, the data may occasionally survive, but PNG/BMP/TIFF are strongly recommended for guaranteed fidelity.)*
+
+---
+
+## 🛡️ Security & Operational Best Practices
+
+1. **Steganography vs. Cryptography**:
+   - Steganography hides the *existence* of communication.
+   - Cryptography protects the *confidentiality* of the content.
+   - **Recommendation**: Always encrypt your message prior to embedding (e.g., using AES-GCM or ChaCha20-Poly1305). If intercepted, an adversary inspecting spectral coefficients will extract only ciphertext.
+2. **Visual Fidelity**:
+   - `STEP = 32` yields an average pixel shift $\Delta_{\text{pixel}} \approx 1\text{ to }3$ intensity levels out of $255$. This remains completely imperceptible to human inspection.
+3. **Carrier Selection**:
+   - Select cover images with rich natural textures (landscapes, urban photography, textured surfaces) rather than artificial flat color backgrounds. Natural texture energy in the frequency spectrum provides superior camouflage.
+
+---
+
+## 🔧 Troubleshooting & FAQs
+
+### Q: UnicodeEncodeError: `'charmap' codec can't encode character '\u2713'` (Windows PowerShell / CMD)
+**Cause:** Windows command terminals often default to legacy code pages (e.g., `cp1252`).  
+**Fix:** Force UTF-8 encoding in Python before running:
+```powershell
+$env:PYTHONIOENCODING="utf-8"
+python main.py extract stego.png
+```
+Or switch console code page: `chcp 65001`.
+
+---
+
+### Q: `ValueError: Message too long (...)`
+**Cause:** The message byte size exceeds the image's capacity.  
+**Fix:** Run `python main.py capacity <image>` to check the limits. Use a higher-resolution cover image or compress the payload (e.g., `gzip`) before embedding.
+
+---
+
+### Q: `ValueError: No hidden message found`
+**Cause:** The 8-byte sentinel marker was not found in the decoded bitstream.  
+**Common reasons:**
+- The image was converted or re-saved using lossy compression (JPEG, WebP).
+- The image was cropped, resized, rotated, or color-adjusted.
+- The image does not contain an `fsteg` payload.
+
+---
+
+### Q: `ValueError: CRC-32 mismatch (stored 0x..., computed 0x...)`
+**Cause:** The sentinel was discovered, but one or more bits in the payload were flipped.  
+**Common reasons:**
+- Minor spatial alterations, noise injection, or compression artifacts occurred after embedding.
+
+---
+
+## 📂 Project Layout
+
+```text
+fft-steg/
+├── .gitignore             # Standard Python / uv gitignore rules
+├── .python-version        # Locked Python interpreter version (3.11+)
+├── pyproject.toml         # PEP 518/621 project metadata & dependencies
+├── uv.lock                # Deterministic dependency lockfile
+├── main.py                # Core steganography engine & CLI entrypoint
+├── stego.jpg              # Sample carrier image
+└── README.md              # Project documentation
+```
+
+---
+
+## 📜 License
+
+Distributed under the **MIT License**. See `LICENSE` for more information.

fsteg-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+fsteg/__init__.py,sha256=VB_xCtKcAxFrhhde9zHQTt1PAea0PB0aYbXt8QtFQ7Q,101
+fsteg/main.py,sha256=EMGY6ZDCInWjBhM11IvpmXaZ-fH2XGJkArzE1kG--v8,11822
+fsteg-0.1.0.dist-info/METADATA,sha256=f6vEsT7EzToSxUjUzoXLmSKo8h_XSS9beKQrIJRrIwM,22823
+fsteg-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+fsteg-0.1.0.dist-info/entry_points.txt,sha256=-A1oFIo3698Az7EUaK37CTXYZduLdLDjTeFis-XWVME,42
+fsteg-0.1.0.dist-info/licenses/LICENSE,sha256=tfAKsp3J2SrqdQi2RtTgVd3dn6cMJwm1ZB4qZlZtRzQ,1071
+fsteg-0.1.0.dist-info/RECORD,,

fsteg-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

fsteg-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fsteg = fsteg.main:main

fsteg-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kishan Agarwal
+
+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.