JPEG-Obscura Quick Reference

Child note of ideas/jpeg-obscura/project-index.

Repository

~/py/jpeg-obscura

Core Modules

All in src/jpeg_obscura/:

• geometry.py — Region validation & block grid snapping
• stream.py — HMAC-SHA256 random stream
• permutation.py — Fisher–Yates algorithm
• kdf.py — scrypt key derivation
• image.py — Pillow load/save
• transform.py — Block permutation
• metadata.py — APP15 encoding
• errors.py — Exception types

Running Tests

python3 test_integration.py — Core mechanics test

python3 demo_scramble_restore.py — End-to-end workflow

Test Images (~/tmp/)

test1.jpg — Original photo (3840×2160)

demo_detailed_scrambled.jpg — Scrambled version

demo_detailed_restored.jpg — Restored version

demo_comparison_strip.png — Visual proof (before/after)

Key Design Points

Pixel domain (v0.5): Pillow + NumPy only

Exact in-memory: Permutation is mathematically invertible

Lossy encode/decode: JPEG re-encoding unavoidable in v0.5

Deterministic stream: HMAC-SHA256 for reproducibility

Metadata in APP15: Embedded in JPEG (v1+); sidecar for v0.5

Known Limitations

Not secure: Permutation-only (v0.5); diffusion added in v1

Metadata-dependent: Needs salt + region geometry to restore

No resizing recovery: Changing dimensions breaks decoding

Next Phase: v1

Add keyed value-diffusion (first security milestone)

Estimated: +0.25 days of effort

Published test vectors for validation

See Also

Project index: ideas/jpeg-obscura/project-index

Implementation status: ideas/jpeg-obscura/v0.5-implementation

Test results: ideas/jpeg-obscura/test-results

Core design: ideas/jpeg-region-scrambling

v0.5 spec: ideas/jpeg-region-scrambling-v0.5-design