PixelFS 🖼️

PixelFS is an open-source, production-grade virtual filesystem embedded inside standard PNG images.

Unlike traditional steganography scripts that hide raw text bytes inside image pixels, PixelFS turns any PNG image into a miniature, encrypted, compressed storage device, complete with ext-style inodes, directory tables, bitmap allocators, AES-256-GCM encryption, Zstandard stream compression, fsck integrity checking, and recovery tools.

Crucially, the PNG file remains a 100% valid image. You can double-click it, view it in any image viewer (Windows Photos, Paint, Photoshop, macOS Preview), upload it, or view it on the web without breaking the image or corrupting the embedded filesystem.

---

How It Works

PNG decoders parse image chunks sequentially until reaching the IEND (End of Image) chunk. Standard image viewers stop reading immediately at IEND and ignore any trailing binary data.

PixelFS attaches a binary volume payload right after the IEND boundary. Standard image viewers open the image cleanly without error, while PixelFS mounts the hidden volume starting from that byte offset.

+-----------------------------------------------------------+
| PNG Image Header (IHDR, IDAT pixel chunks)                |
| (Rendered normally in all standard image viewers)         |
+-----------------------------------------------------------+
| PNG IEND Chunk (End of standard image stream)            |
+-----------------------------------------------------------+
| Volume Header (64 bytes: Magic 'PXFS', Version, UUID)     |
+-----------------------------------------------------------+
| Superblock (128 bytes: Capacity, Block Size, Counters)    |
+-----------------------------------------------------------+
| Allocation Bitmap (Tracks Free vs Allocated Blocks)       |
+-----------------------------------------------------------+
| Inode Table (Fixed 128-byte ext-style metadata records)   |
+-----------------------------------------------------------+
| Data Blocks (Directory entries & encrypted payload data)  |
+-----------------------------------------------------------+

---

Features

• Valid PNG Image Container: Embedded storage sits after the image stream. Visual pixel data is left completely untouched.
• Smart Image Creation: Formats existing PNG images or automatically prompts to create a new 512x512 PNG container if the file doesn't exist.
• Pluggable Backends: Storage backend supporting PNG images (PNGBackend) as well as raw memory or binary container files (RawBackend).
• ext-style Inodes: Filenames are stored inside directory tables, while fixed 128-byte inodes store file metadata, timestamps, SHA-256 digests, and block pointers.
• AES-256-GCM Encryption: Password-based key derivation using PBKDF2-HMAC-SHA256 with 16-byte random salts.
• Zstandard Stream Compression: Fast, high-efficiency transparent block stream compression (zstd).
• In-Memory Block Cache: LRU block caching layer to optimize read and write operations.
• Transactional Write Ordering: Crash-safe allocation ordering (Allocate -> Write Blocks -> Write Inode -> Write Directory -> Commit Superblock).
• Automatic Parent Directories: Uploading files or creating folders automatically creates missing parent directories (mkdir -p behavior).
• Integrity Verification and Repair: Built-in volume health diagnostic audit (pixelfs fsck) and conservative recovery engine (pixelfs repair) recovering orphan blocks and files into /lost+found.
• Rich CLI and Python API: Colored tables, visual folder tree rendering, search tools, and full Python library integration.

---

🖼️ Bring Your Own PNG Image Support

PixelFS works with any custom PNG image on your system (personal photos, wallpapers, logos, artwork, or screenshots).

When formatting your own image:

• Pixel Data Preserved: 100% of your photo's visual pixel data remains untouched.
• 100% Viewable: Your image still opens normally in Windows Photos, macOS Preview, Paint, Photoshop, or web browsers.
• Hidden Volume: The virtual storage payload is attached safely after the IEND chunk boundary.

Supported Stored File Types (100% Binary Compatible)

PixelFS handles file data at the binary block level, meaning you can store any file type inside your PNG image, including:

• Documents: PDF (.pdf), Word (.docx), Plain Text (.txt), Markdown (.md), Excel (.xlsx), PowerPoint (.pptx).
• Media: Audio (.mp3, .wav, .flac), Video (.mp4, .mkv), Images (.jpg, .png, .webp, .gif).
• Archives: Compressed archives (.zip, .tar.gz, .7z, .rar).
• Code and Web Apps: JavaScript / TypeScript (.js, .ts, .jsx, .tsx), HTML (.html), CSS (.css), Python (.py), C/C++, Rust, Go, Executables (.exe), SQLite (.sqlite, .db), JSON / YAML (.json, .yaml).
• Security Keys: Private keys (.pem, .key), certificates (.crt), credential backups.

All stored files are automatically compressed with Zstandard (zstd) and optionally encrypted with AES-256-GCM.

Example with your own custom image path:

# Format your personal PNG image
python -m pixelfs format "C:\Users\YourName\Pictures\my_photo.png" --capacity 10M

# Store a file inside your photo
python -m pixelfs put "C:\Users\YourName\Pictures\my_photo.png" Source/Input/secret_document.txt /my_secret.txt

# Extract the file back out of your photo
python -m pixelfs get "C:\Users\YourName\Pictures\my_photo.png" /my_secret.txt Source/Output/extracted.txt

---

🚀 Quick Start

Option 1: Native Installation (Python 3.12+)

pip install .

Option 2: Docker Container

# Build Docker image
docker build -t pixelfs .

# Run CLI inside Docker
docker run --rm -v $(pwd):/data pixelfs format /data/cover.png --capacity 10M -y

---

📂 Project Directory Structure

PixelFS comes pre-configured with a dedicated Source/Input and Source/Output workflow:

Source/
├── Input/
│   ├── sample_cover.png       # Base container PNG image
│   └── secret_document.txt    # Sample input text file
├── Output/
│   └── extracted_document.txt # Extracted output directory
└── demo.py                    # Automated end-to-end demo script

Run the automated workflow script:

python Source/demo.py

---

💻 Complete CLI Command Reference

Universal Compatibility Note: You can run CLI commands using either pixelfs <command> or python -m pixelfs <command>. python -m pixelfs works on any system without requiring environment PATH configuration.

1. Format Volume (pixelfs format or python -m pixelfs format)

# Universal command (works on any system without PATH setup)
python -m pixelfs format cover.png --capacity 10M

# Direct CLI command (when PATH is configured)
pixelfs format cover.png --capacity 10M

# Auto-create missing PNG container without prompt (-y / --yes)
python -m pixelfs format cover.png --capacity 10M -y

# Format with custom dimensions and color
python -m pixelfs format vault.png --capacity 20M --width 800 --height 600 --color "#1E40AF" -y

# Format with password encryption enabled
python -m pixelfs format secure.png --capacity 50M --password "MySecretPassphrase" -y

---

2. Inspect Storage Metadata (pixelfs inspect)

pixelfs inspect cover.png

---

3. Mount Volume Health Check (pixelfs mount)

pixelfs mount cover.png

---

4. Create Folders (pixelfs mkdir)

# Create nested directories (automatically creates parent folders!)
pixelfs mkdir cover.png /documents/projects/2026

---

5. Upload File into Volume (pixelfs put)

# Upload local file into PixelFS VFS (auto-creates parent directories if missing!)
pixelfs put cover.png Source/Input/secret_document.txt /documents/projects/notes.txt

# Upload file into password-protected volume
pixelfs put secure.png Source/Input/secret_document.txt /private/confidential.txt -p "MySecretPassphrase"

---

6. List Directory Contents (pixelfs ls)

# List root folder contents
pixelfs ls cover.png /

# List nested folder contents
pixelfs ls cover.png /documents/projects

# List password-protected volume contents
pixelfs ls secure.png /private -p "MySecretPassphrase"

---

7. Display Visual Tree View (pixelfs tree)

pixelfs tree cover.png

---

8. Search Files (pixelfs find)

# Search for files matching pattern
pixelfs find cover.png notes

# Search using pattern flag
pixelfs find cover.png -n "*.txt"

---

9. Extract Files to Local Disk (pixelfs get)

# Extract file from volume into local Output directory
pixelfs get cover.png /documents/projects/notes.txt Source/Output/extracted.txt

# Read extracted file content in PowerShell
Get-Content Source/Output/extracted.txt

# Extract file from password-protected volume
pixelfs get secure.png /private/confidential.txt Source/Output/decrypted.txt -p "MySecretPassphrase"

---

10. Copy, Move and Delete Files (cp, mv, rm)

# Copy file within VFS
pixelfs cp cover.png /documents/projects/notes.txt /documents/projects/backup.txt

# Rename/Move file within VFS
pixelfs mv cover.png /documents/projects/backup.txt /documents/projects/notes_v2.txt

# Remove file from VFS
pixelfs rm cover.png /documents/projects/notes_v2.txt

---

11. Health Check and Volume Repair (fsck and repair)

# Run read-only filesystem integrity audit
pixelfs fsck cover.png

# Run conservative repair engine (recovers orphan files into /lost+found)
pixelfs repair cover.png -y

---

🐍 Python Library API Usage

You can also use PixelFS directly inside your own Python programs:

from pixelfs.storage import PNGBackend
from pixelfs.container import ContainerManager
from pixelfs.filesystem import PixelFS

# 1. Format container image
backend = PNGBackend("Source/Input/sample_cover.png")
container_mgr = ContainerManager(backend)
container_mgr.format_container(
    capacity_bytes=10 * 1024 * 1024,
    fs_name="PythonVolume",
    enable_encryption=True,
    enable_compression=True,
)

# 2. Mount virtual filesystem with encryption password
fs = PixelFS(backend, password="MySecretPassword")

# 3. Create nested directory and put file (auto-creates parent directories!)
fs.mkdir("/work/projects")
fs.put("Source/Input/secret_document.txt", "/work/projects/notes.txt")

# 4. List folder contents
print("VFS Contents:")
for item in fs.ls("/work/projects"):
    print(f" - {item['name']} ({item['size_human']}, Inode: {item['inode_id']})")

# 5. Extract file back to disk
fs.get("/work/projects/notes.txt", "Source/Output/extracted_python.txt")

---

🧪 Testing and Verification

PixelFS includes a complete test suite of 22 automated unit and integration tests:

# Run pytest natively
python -m pytest -v

# Run pytest inside Docker
docker run --rm --entrypoint pytest pixelfs -v

---

🏛️ Architecture and Design Highlights

1. Transactional Safety: Metadata updates write blocks first, then inodes, then directory tables, and finally the superblock counter.
2. Orphan Recovery: If corruption occurs, pixelfs repair scans for unlinked inode blocks and safely isolates them into /lost+found.
3. Zero Pixel Modification: Operating strictly after IEND means lossy image re-compression software won't break image decoding, and visual fidelity is preserved 100%.

---

⚠️ Good Things to Know (Simple Limitations)

Here are a few quick tips to get the best experience with PixelFS:

1. Single File Size Limit (up to ~48 KB before compression) Each individual file stored inside an image can hold up to 48 KB of raw data. Because PixelFS compresses files automatically, text and code files fit easily. Support for multi-megabyte single files is coming in v2.

2. Total File and Folder Limit (default 128 items) A single PNG image volume can hold up to 128 total files and folders. If you plan to store hundreds of items, you can specify --max-inodes 1024 when formatting your image.

3. Sending Images Over Social Media Apps that re-compress photos (like WhatsApp photo mode or Twitter/X) strip hidden extra data appended to images. Tip: Always send image files as Document / File attachments (via Telegram Document, Google Drive, Email, or cloud storage) to keep your hidden storage intact.

4. One Modification at a Time Avoid adding or modifying files in the exact same PNG image from two different terminal windows at the exact same time.

---

🌐 Cloud Sharing and Messaging App Compatibility

Platform / Channel	Compatible?	Sharing Method & Details
Google Drive / Dropbox / OneDrive	Yes	Standard file upload & download preserves 100% of binary payload data.
WhatsApp (Send as Document)	Yes	Click Attachment -> Document (sends raw file untouched).
WhatsApp (Send as Photo)	No	WhatsApp photo mode converts PNGs to lossy JPEGs and strips trailing payloads.
Telegram (Send as File)	Yes	Send as uncompressed File attachment.
Email Attachments	Yes	Standard email attachments preserve binary files 100%.
Discord / Slack	Yes	Upload as file attachment.

---

License

MIT License.