🌲 Black Forest

Universal Steganography Engine — Hide any file inside any carrier file format safely.

🎯 What is this?

Black Forest is a zero-dependency Node.js steganography engine that lets you hide any file inside any carrier file. The carrier remains fully functional — images still open, videos still play, documents still read.

Key Features

• 🔐 AES-256-GCM encryption with PBKDF2 key derivation (600K iterations)
• 📁 Universal overlay mode — works with ANY file format
• 🖼️ PNG LSB embedding — hides data in pixel least-significant bits
• 📸 JPEG post-EOI injection — stores data after End-of-Image marker
• 🌊 Streaming support — handles files > 50 MB without memory issues
• 🔍 Auto-detection — scans files for hidden data
• 🛡️ Integrity verification — CRC32 header checks + GCM auth tags
• 📊 Capacity estimation — know before you embed
• 🎯 Zero dependencies for core functionality (pngjs optional for PNG mode)

📦 Installation

# Global install (recommended for CLI)
npm install -g black-forest

# Local install
npm install black-forest

# From source
git clone https://github.com/your-username/black-forest.git
cd black-forest
npm install
npm link   # Makes CLI available globally

Optional Dependencies

# For PNG LSB steganography mode
npm install pngjs

🚀 CLI Usage

Hide a File

# Basic overlay mode (works with any file type)
black-forest hide -f secret.pdf -c photo.jpg -o output.jpg -p "mypassword"

# Short alias
bf hide -f secret.pdf -c photo.jpg -o output.jpg -p "mypassword"

# Specify mode explicitly
black-forest hide -f data.txt -c image.png -o stego.png -p "pass" --mode png

# JPEG mode
black-forest hide -f payload.zip -c vacation.jpg -o vacation_out.jpg -p "secure123" --mode jpeg

Extract a Hidden File

# Auto-detect mode
black-forest extract -i output.jpg -p "mypassword"

# Specify output location
black-forest extract -i stego.png -p "pass" -o ./extracted/

# Specify mode
black-forest extract -i stego.png -p "pass" --mode png

Inspect a File

# Check if a file contains hidden data
black-forest inspect suspicious_file.jpg

Check Capacity

# Estimate how much data a carrier can hold
black-forest capacity photo.png --mode png
black-forest capacity video.mp4 --mode overlay

📚 Programmatic API

const stego = require('black-forest');

// Hide a file
const hideResult = await stego.hide({
  inputFile: 'secret.pdf',
  carrierFile: 'photo.jpg',
  outputFile: 'output.jpg',
  password: 'mypassword',
  mode: 'auto',           // auto, overlay, png, jpeg
  onProgress: (percent, message) => {
    console.log(`${percent}% - ${message}`);
  },
});

console.log(hideResult);
// {
//   success: true,
//   mode: 'overlay',
//   outputFile: 'output.jpg',
//   payloadSize: 12345,
//   encryptedSize: 12361,
//   overhead: 12449,
//   ...
// }

// Extract a file
const extractResult = await stego.extract({
  inputFile: 'output.jpg',
  password: 'mypassword',
  mode: 'auto',
  outputDir: './extracted/',
});

console.log(extractResult);
// {
//   success: true,
//   extractedFile: './extracted/secret.pdf',
//   originalFilename: 'secret.pdf',
//   fileSize: 12345,
// }

// Inspect a file
const info = await stego.inspect('output.jpg');
console.log(info.hasEmbeddedData); // true
console.log(info.embeddedFilename); // 'secret.pdf'

// Check capacity
const cap = await stego.capacity('image.png', 'png');
console.log(cap.maxPayloadHuman); // '1.23 MB'

🏗️ Architecture

black-forest/
├── core/
│   ├── encrypt.js     # AES-256-GCM encryption + PBKDF2 key derivation
│   ├── decrypt.js     # Decryption with authentication verification
│   ├── header.js      # Binary header serialization (magic bytes, CRC32)
│   └── scanner.js     # Reverse file scanner for header detection
├── modes/
│   ├── overlay.js     # Universal overlay mode (any file format)
│   ├── png-lsb.js     # PNG least-significant-bit embedding
│   └── jpeg-dct.js    # JPEG post-EOI injection
├── utils/
│   ├── capacity.js    # Carrier capacity estimation
│   └── filecheck.js   # File type detection via magic bytes
├── index.js           # CLI entry point
├── lib.js             # Library API
└── test/
    └── test.js        # Test suite

🔐 How It Works

Overlay Mode (Primary)

The overlay mode works by appending encrypted data after the carrier file's original content:

┌──────────────────────┬──────────────────────────┬────────────────┐
│   Original Carrier   │   Encrypted Payload      │  USTG Header   │
│   (unchanged)        │   (AES-256-GCM)          │  (metadata)    │
└──────────────────────┴──────────────────────────┴────────────────┘

1. The carrier file is copied to the output
2. The payload is encrypted with AES-256-GCM
3. A binary header with metadata, salt, IV, and auth tag is created
4. Encrypted payload + header are appended to the carrier
5. The carrier remains fully functional (images open, videos play, etc.)

Header Format

┌──────────────────────────────────────────────────────────────────┐
│ Field            │ Size (bytes)  │ Description                   │
├──────────────────┼───────────────┼───────────────────────────────┤
│ Magic Bytes      │ 4             │ "USTG" identifier             │
│ Version          │ 1             │ Protocol version              │
│ Mode             │ 1             │ Embedding mode                │
│ Filename Length  │ 2             │ Original filename length      │
│ Filename         │ variable      │ UTF-8 encoded filename        │
│ Payload Size     │ 8             │ Encrypted payload size        │
│ Salt             │ 32            │ PBKDF2 salt                   │
│ IV               │ 16            │ AES-GCM initialization vector │
│ Auth Tag         │ 16            │ GCM authentication tag        │
│ Header CRC       │ 4             │ CRC32 integrity check         │
│ Header Sentinel  │ 4             │ "HEND" end marker             │
└──────────────────────────────────────────────────────────────────┘

PNG LSB Mode

Hides data in the least significant bits of RGB pixel values. Changes are imperceptible to the human eye.

Original pixel:  R=10110110  G=11001010  B=01111001
Hidden bit:                ↓           ↓           ↓
Modified pixel:  R=10110111  G=11001011  B=01111000

JPEG Mode

Stores data after the JPEG End-of-Image (EOI) marker. Most image viewers ignore post-EOI data.

🔒 Security Considerations

Strengths

| Feature | Detail | |---------|--------| | Encryption | AES-256-GCM (authenticated encryption) | | Key Derivation | PBKDF2 with 600,000 iterations (OWASP 2023) | | Salt | 256-bit random salt per file | | IV | 128-bit random IV per file | | Integrity | GCM auth tag + CRC32 header verification | | Memory | Keys are zeroed after use |

Limitations

• Overlay mode is detectable by checking if file size exceeds expected format size
• PNG LSB changes pixel values slightly (detectable by statistical analysis tools like StegExpose)
• JPEG post-EOI detection is trivial if someone looks for data after EOI marker
• This tool provides encryption-level security, not deniability
• Metadata (filename, size) is encrypted within the AES payload but header structure is visible

Best Practices

1. Use strong passwords (12+ characters, mixed case, numbers, symbols)
2. Use carriers that naturally vary in size (photos, videos)
3. Keep the payload small relative to the carrier to reduce suspicion
4. For PNG LSB mode, prefer photographic images over flat graphics (noise hides changes)
5. Never reuse the same carrier for multiple embeddings

⚡ Performance

| Operation | 1 MB file | 10 MB file | 100 MB file | |-----------|-----------|------------|-------------| | Hide (overlay) | ~1.2s | ~2.5s | ~8s (streaming) | | Extract (overlay) | ~1.1s | ~2.3s | ~7s | | Hide (PNG LSB) | ~2s | N/A* | N/A* |

*PNG LSB capacity is limited by image dimensions.

Key derivation (PBKDF2 with 600K iterations) takes ~0.8-1.2s — this is intentional for security.

Tips for Large Files

• Files > 50 MB automatically use streaming mode (overlay)
• Streaming mode processes data in chunks to avoid memory exhaustion
• PNG and JPEG modes load the full carrier into memory

🧪 Testing

# Run test suite
npm test

# Run with debug output
DEBUG=1 npm test

🛣️ Roadmap

• [ ] PDF object stream injection
• [ ] MP4 metadata atom injection
• [ ] EXE PE overlay section injection
• [ ] Argon2 key derivation (via native addon)
• [ ] Chunk splitting across multiple carriers
• [ ] Steganography detection/analysis tools
• [ ] Web UI for browser-based usage
• [ ] WASM build for cross-platform support

📄 License

MIT © Black Forest Contributors

⚠️ Disclaimer

This tool is for educational and legitimate privacy purposes only. The authors are not responsible for any misuse. Always comply with applicable laws and regulations regarding data encryption and steganography in your jurisdiction.