Metadata-Version: 2.4
Name: secure-stegano
Version: 1.1.4
Summary: Bibliothèque Python unifiée de stéganographie d'images et de stéganalyse, du LSB au deep learning.
Author: TPI Steganograph-IA
License: MIT
Keywords: steganography,steganalysis,image-processing,lsb,s-uniward,f5,hidden,deep-learning
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.26
Requires-Dist: Pillow>=10.0
Requires-Dist: scipy>=1.11
Requires-Dist: torch>=2.1
Requires-Dist: huggingface_hub>=0.20
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: hypothesis>=6.90; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1.7; extra == "dev"
Provides-Extra: notebooks
Requires-Dist: jupyterlab>=4.0; extra == "notebooks"
Requires-Dist: matplotlib>=3.8; extra == "notebooks"
Requires-Dist: seaborn>=0.13; extra == "notebooks"

# secure-stegano

Bibliothèque Python unifiée de stéganographie d'images et de stéganalyse, du LSB historique au deep learning moderne.

> Moteur algorithmique du projet TPI. Voir le [cahier des charges](../documentation/cahier_de_charge.md) pour le périmètre détaillé et l'[état de l'art](../documentation/etat_de_l_art.md) pour le cadrage théorique.

## Vue d'ensemble

Le package implémente :

- **Embedding / extraction** — LSB, LSBMR, S-UNIWARD (spatial), F5 (JPEG), HiDDeN (deep).
- **Stéganalyse** — chi-square, RS analysis, SRNet (CNN pré-entraîné).
- **Métriques** — PSNR, SSIM, BER, capacité.
- **Canaux réseaux sociaux** — Facebook, Instagram, Twitter, WhatsApp (simulateurs).
- **Signature de traçabilité** — HMAC embarqué pour identification d'origine.

## Conventions de nommage

| Aspect              | Valeur            | Pourquoi                                  |
| ------------------- | ----------------- | ----------------------------------------- |
| Dossier             | `secure-stegano`  | Convention PyPI (tiret).                  |
| Distribution        | `secure-stegano`  | Idem, c'est ce qu'on installe via pip.    |
| Nom d'import Python | `secure_stegano`  | Python interdit les tirets dans les modules. |

```python
import secure_stegano
from secure_stegano.spatial import lsb  # à venir en Phase A1
```

## Installation

Prérequis : **Python 3.11+**.

```bash
cd algorithms/secure-stegano
pip install -e ".[dev]"
```

Avec les notebooks d'exploration :

```bash
pip install -e ".[dev,notebooks]"
```

## Utilisation rapide (CLI)

```bash
# Aide
python -m secure_stegano --help

# Cacher un message (lsb, lsbmr, s-uniward)
python -m secure_stegano encode --algorithm lsb --cover cover.png --payload "hello" --out stego.png

# Extraire — sans --algorithm : décodage aveugle (algo lu dans l'en-tête)
python -m secure_stegano decode --stego stego.png

# Simuler le passage par Facebook
python -m secure_stegano channel --profile facebook --input stego.png --out stego_after_fb.jpg
```

Via la façade Python :

```python
import secure_stegano
from secure_stegano.core import load_image, save_image

res = secure_stegano.embed(load_image("cover.png"), b"hello", "lsb")
save_image(res.stego, "stego.png")
assert secure_stegano.extract(load_image("stego.png")) == b"hello"  # aveugle
```

> **État Phase A1 (+ A5/A6) :** `encode`/`decode`/`channel` opérationnels pour
> LSB, LSBMR (aller-retour réel) et S-UNIWARD (simulateur d'embedding, non
> extractible). `analyze` (stéganalyse), F5 et HiDDeN lèvent encore
> `NotImplementedError`.

## Tests et qualité

```bash
pytest              # suite de tests   (barrière bloquante)
ruff check src      # lint              (barrière bloquante)
mypy src            # types — NON strict (cf. note Structure ci-dessous)
```

## Structure

Structuration **par rôle pipeline** (regroupement `codecs/` et `evaluation/`) :

```
src/                 (mappé sur le paquet « secure_stegano » par setuptools)
├── __init__.py      Re-export de la façade (embed/extract/sign/verify)
├── api.py           FAÇADE centrale — seul point d'entrée à appeler
├── __main__.py      CLI = fin appelant de api.py
├── core/            types, io, payload (conteneur auto-descriptif + permutation)
├── codecs/          chaque module = encode() + decode()
│   ├── spatial/     lsb.py, lsbmr.py, s_uniward.py
│   ├── jpeg/        f5 (stub — hors périmètre)
│   └── deep/        hidden (stub — hors périmètre)
├── analysis/        stéganalyse (stub — hors périmètre)
├── evaluation/      mesure & benchmark
│   ├── metrics/     psnr, ssim, ber, capacity
│   └── channels/    facebook, instagram, twitter, whatsapp, generic
└── signature/       hmac_sig — filigrane de traçabilité
```

> **Divergence assumée vs cahier §10.** Le cahier prévoit une arborescence
> plate (un sous-paquet par concern). Nous regroupons plutôt par rôle :
> `codecs/` (chaque codec fait `encode`+`decode` ; « extraire » est la fonction
> inverse, pas un dossier), `evaluation/` (métriques + canaux), et une façade
> `api.py` qui centralise le dispatch (« backend fin, package gras », cahier §3).
> Le décodage **aveugle** s'appuie sur l'en-tête auto-descriptif
> (`MAGIC + algo_id + CRC32`) écrit par `core/payload.py`.

> **Layout `src/` plat (choix assumé).** Le contenu vit directement dans
> `src/` (pas de `src/secure_stegano/`). `setuptools` remappe le nom d'import
> `secure_stegano` sur `src/` via `[tool.setuptools] package-dir`. Conséquence :
> `mypy` ne peut pas résoudre le paquet par le système de fichiers (le remap
> n'existe qu'à l'install) → **typage non strict assumé**. `pytest` et `ruff`
> restent la barrière qualité bloquante. Le layout standard
> `src/secure_stegano/` rétablirait `mypy --strict` si besoin un jour.

## Feuille de route Phase A

| Tâche | Périmètre                                           | État        |
| ----- | --------------------------------------------------- | ----------- |
| A0    | Scaffolding (ce commit)                              | ✅ fait     |
| A1    | LSB, LSBMR, S-UNIWARD + tests + CLI branchée         | ✅ fait     |
| A2    | F5 JPEG                                              | à venir     |
| A3    | Stéganalyse (chi-square, RS, SRNet)                  | à venir     |
| A4    | HiDDeN inférence                                     | à venir     |
| A5    | Module signature HMAC                                | ✅ fait     |
| A6    | Canaux réseaux sociaux                               | ✅ fait     |
| A7    | Métriques + benchmarks reproductibles                | à venir     |
| A8    | Doc et notebooks                                     | à venir     |

Détails dans le [cahier des charges §11](../documentation/cahier_de_charge.md#11-estimation-de-charge).
