roxify 1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,368 @@
+# RoxCompressor Transform
+
+> Encode binary data into PNG images and decode them back. Fast, efficient, with optional encryption.
+
+[![npm version](https://img.shields.io/npm/v/roxify.svg)](https://www.npmjs.com/package/roxify)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## Features
+
+- 🚀 **Fast**: Optimized Brotli compression (quality 1 by default) — encode 3.8 MB in ~1 second
+- 🔒 **Secure**: AES-256-GCM encryption support with PBKDF2 key derivation
+- 🎨 **Multiple modes**: Compact, chunk, pixel, and screenshot modes
+- 📦 **CLI & API**: Use as command-line tool or JavaScript library
+- 🔄 **Lossless**: Perfect roundtrip encoding/decoding
+- 📊 **Efficient**: Typically 20-30% of original size with compression
+- 📖 **Full TSDoc**: Complete TypeScript documentation
+
+## Documentation
+
+- 📘 **[CLI Documentation](./CLI.md)** - Complete command-line usage guide
+- 📗 **[JavaScript SDK](./JAVASCRIPT_SDK.md)** - Programmatic API reference with examples
+- 📙 **[Quick Start](#quick-start)** - Get started in 2 minutes
+
+## Installation
+
+### As CLI tool (npx)
+
+No installation needed! Use directly with npx:
+
+```bash
+  npx rox encode input.zip output.png
+  npx rox decode output.png original.zip
+```
+
+### As library
+
+```bash
+npm install roxify
+```
+
+## CLI Usage
+
+### Quick Start
+
+```bash
+# Encode a file
+  npx rox encode document.pdf document.png
+
+# Decode it back
+  npx rox decode document.png document.pdf
+
+# With encryption
+  npx rox encode secret.zip secret.png -p mypassword
+  npx rox decode secret.png secret.zip -p mypassword
+```
+
+### CLI Commands
+
+#### `encode` - Encode file to PNG
+
+```bash
+  npx rox encode <input> [output] [options]
+```
+
+**Options:**
+
+- `-p, --passphrase <pass>` - Encrypt with passphrase (AES-256-GCM)
+- `-m, --mode <mode>` - Encoding mode: `compact|chunk|pixel|screenshot` (default: `screenshot`)
+- `-q, --quality <0-11>` - Brotli compression quality (default: `1`)
+  - `0` = fastest, largest
+  - `11` = slowest, smallest
+- `-e, --encrypt <type>` - Encryption: `auto|aes|xor|none` (default: `aes` if passphrase)
+- `--no-compress` - Disable compression
+- `-o, --output <path>` - Output file path
+
+**Examples:**
+
+```bash
+# Basic encoding
+  npx rox encode data.bin output.png
+
+# Fast compression for large files
+  npx rox encode large-video.mp4 output.png -q 0
+
+# High compression for small files
+  npx rox encode config.json output.png -q 11
+
+# With encryption
+  npx rox encode secret.pdf secure.png -p "my secure password"
+
+# Compact mode (smallest PNG)
+  npx rox encode data.bin tiny.png -m compact
+
+# Screenshot mode (recommended, looks like a real image)
+  npx rox encode archive.tar.gz screenshot.png -m screenshot
+```
+
+#### `decode` - Decode PNG to file
+
+```bash
+  npx rox decode <input> [output] [options]
+```
+
+**Options:**
+
+- `-p, --passphrase <pass>` - Decryption passphrase
+- `-o, --output <path>` - Output file path (auto-detected from metadata if not provided)
+
+**Examples:**
+
+```bash
+# Basic decoding
+  npx rox decode encoded.png output.bin
+
+# Auto-detect filename from metadata
+  npx rox decode encoded.png
+
+# With decryption
+  npx rox decode encrypted.png output.pdf -p "my secure password"
+```
+
+## JavaScript API
+
+### Basic Usage
+
+```typescript
+import { encodeBinaryToPng, decodePngToBinary } from 'roxify';
+import { readFileSync, writeFileSync } from 'fs';
+
+// Encode
+const input = readFileSync('input.zip');
+const png = await encodeBinaryToPng(input, {
+  mode: 'screenshot',
+  name: 'input.zip',
+});
+writeFileSync('output.png', png);
+
+// Decode
+const encoded = readFileSync('output.png');
+const result = await decodePngToBinary(encoded);
+writeFileSync(result.meta?.name || 'output.bin', result.buf);
+```
+
+### With Encryption
+
+```typescript
+// Encode with AES-256-GCM
+const png = await encodeBinaryToPng(input, {
+  mode: 'screenshot',
+  passphrase: 'my-secret-password',
+  encrypt: 'aes',
+  name: 'secret.zip',
+});
+
+// Decode with passphrase
+const result = await decodePngToBinary(encoded, {
+  passphrase: 'my-secret-password',
+});
+```
+
+### Fast Compression
+
+```typescript
+// Optimize for speed (recommended for large files)
+const png = await encodeBinaryToPng(largeBuffer, {
+  mode: 'screenshot',
+  brQuality: 0, // Fastest
+  name: 'large-file.bin',
+});
+
+// Optimize for size (recommended for small files)
+const png = await encodeBinaryToPng(smallBuffer, {
+  mode: 'compact',
+  brQuality: 11, // Best compression
+  name: 'config.json',
+});
+```
+
+### Encoding Modes
+
+#### `screenshot` (Recommended)
+
+Encodes data as RGB pixel values, optimized for screenshot-like appearance. Best balance of size and compatibility.
+
+```typescript
+const png = await encodeBinaryToPng(data, { mode: 'screenshot' });
+```
+
+#### `compact` (Smallest)
+
+Minimal 1x1 PNG with data in custom chunk. Fastest and smallest.
+
+```typescript
+const png = await encodeBinaryToPng(data, { mode: 'compact' });
+```
+
+#### `pixel`
+
+Encodes data as RGB pixel values without screenshot optimization.
+
+```typescript
+const png = await encodeBinaryToPng(data, { mode: 'pixel' });
+```
+
+#### `chunk`
+
+Standard PNG with data in custom rXDT chunk.
+
+```typescript
+const png = await encodeBinaryToPng(data, { mode: 'chunk' });
+```
+
+## API Reference
+
+### `encodeBinaryToPng(input, options)`
+
+Encodes binary data into a PNG image.
+
+**Parameters:**
+
+- `input: Buffer` - The binary data to encode
+- `options?: EncodeOptions` - Encoding options
+
+**Returns:** `Promise<Buffer>` - The encoded PNG
+
+**Options:**
+
+```typescript
+interface EncodeOptions {
+  // Compression algorithm ('br' = Brotli, 'none' = no compression)
+  compression?: 'br' | 'none';
+
+  // Passphrase for encryption
+  passphrase?: string;
+
+  // Original filename to embed
+  name?: string;
+
+  // Encoding mode
+  mode?: 'compact' | 'chunk' | 'pixel' | 'screenshot';
+
+  // Encryption method
+  encrypt?: 'auto' | 'aes' | 'xor' | 'none';
+
+  // Output format
+  output?: 'auto' | 'png' | 'rox';
+
+  // Include filename in metadata (default: true)
+  includeName?: boolean;
+
+  // Brotli quality 0-11 (default: 1)
+  brQuality?: number;
+}
+```
+
+### `decodePngToBinary(pngBuf, options)`
+
+Decodes a PNG image back to binary data.
+
+**Parameters:**
+
+- `pngBuf: Buffer` - The PNG image to decode
+- `options?: DecodeOptions` - Decoding options
+
+**Returns:** `Promise<DecodeResult>` - The decoded data and metadata
+
+**Options:**
+
+```typescript
+interface DecodeOptions {
+  // Passphrase for decryption
+  passphrase?: string;
+}
+```
+
+**Result:**
+
+```typescript
+interface DecodeResult {
+  // Decoded binary data
+  buf: Buffer;
+
+  // Extracted metadata
+  meta?: {
+    // Original filename
+    name?: string;
+  };
+}
+```
+
+## Performance Tips
+
+### For Large Files (>10 MB)
+
+```bash
+# Use quality 0 for fastest encoding
+npx rox encode large.bin output.png -q 0
+```
+
+```typescript
+const png = await encodeBinaryToPng(largeFile, {
+  mode: 'screenshot',
+  brQuality: 0, // 10-20x faster than default
+});
+```
+
+### For Small Files (<1 MB)
+
+```bash
+# Use quality 11 for best compression
+npx rox encode small.json output.png -q 11 -m compact
+```
+
+```typescript
+const png = await encodeBinaryToPng(smallFile, {
+  mode: 'compact',
+  brQuality: 11, // Best compression ratio
+});
+```
+
+### Benchmark Results
+
+File: 3.8 MB binary
+
+- **Quality 0**: ~500-800ms, output ~1.2 MB
+- **Quality 1** (default): ~1-2s, output ~800 KB
+- **Quality 5**: ~8-12s, output ~750 KB
+- **Quality 11**: ~20-30s, output ~720 KB
+
+## Error Handling
+
+```typescript
+try {
+  const result = await decodePngToBinary(encoded, {
+    passphrase: 'wrong-password',
+  });
+} catch (err) {
+  if (err.message.includes('Incorrect passphrase')) {
+    console.error('Wrong password!');
+  } else if (err.message.includes('Invalid ROX format')) {
+    console.error('Not a valid RoxCompressor PNG');
+  } else {
+    console.error('Decode failed:', err.message);
+  }
+}
+```
+
+## Security
+
+- **AES-256-GCM**: Authenticated encryption with 100,000 PBKDF2 iterations
+- **XOR cipher**: Simple obfuscation (not cryptographically secure)
+- **No encryption**: Data is compressed but not encrypted
+
+⚠️ **Warning**: Use strong passphrases for sensitive data. The `xor` encryption mode is not secure and should only be used for obfuscation.
+
+## License
+
+MIT © RoxCompressor
+
+## Contributing
+
+Contributions welcome! Please open an issue or PR on GitHub.
+
+## Links
+
+- [GitHub Repository](https://github.com/RoxasYTB/RoxCompressor)
+- [npm Package](https://www.npmjs.com/package/roxify)
+- [Report Issues](https://github.com/RoxasYTB/RoxCompressor/issues)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'fs';
+import { basename, resolve } from 'path';
+import { cropAndReconstitute, DataFormatError, decodePngToBinary, encodeBinaryToPng, IncorrectPassphraseError, PassphraseRequiredError, } from './index.js';
+const VERSION = '1.0.4';
+function showHelp() {
+    console.log(`
+ROX CLI — Encode/decode binary in PNG
+
+Usage:
+  npx rox <command> [options]
+
+Commands:
+  encode <input> [output]   Encode file to PNG
+  decode <input> [output]   Decode PNG to original file
+
+Options:
+  -p, --passphrase <pass>   Use passphrase (AES-256-GCM)
+  -m, --mode <mode>         Mode: compact|chunk|pixel|screenshot (default: screenshot)
+  -q, --quality <0-11>      Brotli quality (default: 11)
+  -e, --encrypt <type>      auto|aes|xor|none
+  --no-compress             Disable compression
+  -o, --output <path>       Output file path
+  --view-reconst            Export the reconstituted PNG for debugging
+  -v, --verbose             Show detailed errors
+
+Run "npx rox help" for this message.
+`);
+}
+function parseArgs(args) {
+    const parsed = { _: [] };
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            const key = arg.slice(2);
+            if (key === 'no-compress') {
+                parsed.noCompress = true;
+                i++;
+            }
+            else if (key === 'verbose') {
+                parsed.verbose = true;
+                i++;
+            }
+            else if (key === 'view-reconst') {
+                parsed.viewReconst = true;
+                i++;
+            }
+            else if (key === 'debug-dir') {
+                parsed.debugDir = args[i + 1];
+                i += 2;
+            }
+            else {
+                const value = args[i + 1];
+                parsed[key] = value;
+                i += 2;
+            }
+        }
+        else if (arg.startsWith('-')) {
+            const flag = arg.slice(1);
+            const value = args[i + 1];
+            switch (flag) {
+                case 'p':
+                    parsed.passphrase = value;
+                    i += 2;
+                    break;
+                case 'm':
+                    parsed.mode = value;
+                    i += 2;
+                    break;
+                case 'q':
+                    parsed.quality = parseInt(value, 10);
+                    i += 2;
+                    break;
+                case 'e':
+                    parsed.encrypt = value;
+                    i += 2;
+                    break;
+                case 'o':
+                    parsed.output = value;
+                    i += 2;
+                    break;
+                case 'v':
+                    parsed.verbose = true;
+                    i += 1;
+                    break;
+                case 'd':
+                    parsed.debugDir = value;
+                    i += 2;
+                    break;
+                default:
+                    console.error(`Unknown option: ${arg}`);
+                    process.exit(1);
+            }
+        }
+        else {
+            parsed._.push(arg);
+            i++;
+        }
+    }
+    return parsed;
+}
+async function encodeCommand(args) {
+    const parsed = parseArgs(args);
+    const [inputPath, outputPath] = parsed._;
+    if (!inputPath) {
+        console.error('Error: Input file required');
+        console.log('Usage: npx rox encode <input> [output] [options]');
+        process.exit(1);
+    }
+    const resolvedInput = resolve(inputPath);
+    const resolvedOutput = parsed.output || outputPath || inputPath.replace(/(\.[^.]+)?$/, '.png');
+    try {
+        console.log(`Reading: ${resolvedInput}`);
+        const startRead = Date.now();
+        const inputBuffer = readFileSync(resolvedInput);
+        const readTime = Date.now() - startRead;
+        console.log(`Read ${(inputBuffer.length / 1024 / 1024).toFixed(2)} MB in ${readTime}ms`);
+        const options = {
+            mode: parsed.mode || 'screenshot',
+            name: basename(resolvedInput),
+            brQuality: parsed.quality !== undefined ? parsed.quality : 11,
+        };
+        if (parsed.noCompress) {
+            options.compression = 'none';
+        }
+        if (parsed.passphrase) {
+            options.passphrase = parsed.passphrase;
+            options.encrypt = parsed.encrypt || 'aes';
+        }
+        console.log(`Encoding ${basename(resolvedInput)} -> ${resolvedOutput}`);
+        const startEncode = Date.now();
+        const output = await encodeBinaryToPng(inputBuffer, options);
+        const encodeTime = Date.now() - startEncode;
+        writeFileSync(resolvedOutput, output);
+        const outputSize = (output.length / 1024 / 1024).toFixed(2);
+        const inputSize = (inputBuffer.length / 1024 / 1024).toFixed(2);
+        const ratio = ((output.length / inputBuffer.length) * 100).toFixed(1);
+        console.log(`\nSuccess!`);
+        console.log(`  Input:  ${inputSize} MB`);
+        console.log(`  Output: ${outputSize} MB (${ratio}% of original)`);
+        console.log(`  Time:   ${encodeTime}ms`);
+        console.log(`  Saved:  ${resolvedOutput}`);
+    }
+    catch (err) {
+        console.error('Error: Failed to encode file. Use --verbose for details.');
+        if (parsed.verbose)
+            console.error('Details:', err.stack || err.message);
+        process.exit(1);
+    }
+}
+async function decodeCommand(args) {
+    const parsed = parseArgs(args);
+    const [inputPath, outputPath] = parsed._;
+    if (!inputPath) {
+        console.error('Error: Input PNG file required');
+        console.log('Usage: npx rox decode <input> [output] [options]');
+        process.exit(1);
+    }
+    const resolvedInput = resolve(inputPath);
+    try {
+        let inputBuffer = readFileSync(resolvedInput);
+        let resolvedInputPath = resolvedInput;
+        try {
+            const reconst = await cropAndReconstitute(inputBuffer);
+            inputBuffer = reconst;
+            resolvedInputPath = resolvedInput.replace(/(\.\w+)?$/, '_reconst.png');
+            if (parsed.viewReconst) {
+                writeFileSync(resolvedInputPath, reconst);
+                console.log(`Reconst PNG: ${resolvedInputPath}`);
+            }
+        }
+        catch (e) {
+            console.log('Could not generate reconst PNG:', e.message);
+        }
+        console.log(`Reading: ${resolvedInputPath}`);
+        const options = {};
+        if (parsed.passphrase) {
+            options.passphrase = parsed.passphrase;
+        }
+        if (parsed.debugDir) {
+            options.debugDir = parsed.debugDir;
+        }
+        console.log(`Decoding...`);
+        const startDecode = Date.now();
+        if (parsed.verbose)
+            options.verbose = true;
+        const result = await decodePngToBinary(inputBuffer, options);
+        const decodeTime = Date.now() - startDecode;
+        const resolvedOutput = parsed.output || outputPath || result.meta?.name || 'decoded.bin';
+        writeFileSync(resolvedOutput, result.buf);
+        const outputSize = (result.buf.length / 1024 / 1024).toFixed(2);
+        console.log(`\nSuccess!`);
+        if (result.meta?.name) {
+            console.log(`  Original name: ${result.meta.name}`);
+        }
+        console.log(`  Output size:   ${outputSize} MB`);
+        console.log(`  Time:          ${decodeTime}ms`);
+        console.log(`  Saved:         ${resolvedOutput}`);
+    }
+    catch (err) {
+        if (err instanceof PassphraseRequiredError ||
+            (err.message && err.message.includes('passphrase') && !parsed.passphrase)) {
+            console.error('File appears to be encrypted. Provide a passphrase with -p');
+        }
+        else if (err instanceof IncorrectPassphraseError ||
+            (err.message && err.message.includes('Incorrect passphrase'))) {
+            console.error('Incorrect passphrase');
+        }
+        else if (err instanceof DataFormatError ||
+            (err.message &&
+                (err.message.includes('decompression failed') ||
+                    err.message.includes('missing ROX1') ||
+                    err.message.includes('Pixel payload truncated') ||
+                    err.message.includes('Marker START not found') ||
+                    err.message.includes('Brotli decompression failed')))) {
+            console.error('Data corrupted or unsupported format. Use --verbose for details.');
+        }
+        else {
+            console.error('Failed to decode file. Use --verbose for details.');
+        }
+        if (parsed.verbose)
+            console.error('Details:', err.stack || err.message);
+        process.exit(1);
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === 'help' || args[0] === '--help') {
+        showHelp();
+        return;
+    }
+    if (args[0] === 'version' || args[0] === '--version') {
+        console.log(VERSION);
+        return;
+    }
+    const command = args[0];
+    const commandArgs = args.slice(1);
+    switch (command) {
+        case 'encode':
+            await encodeCommand(commandArgs);
+            break;
+        case 'decode':
+            await decodeCommand(commandArgs);
+            break;
+        default:
+            console.error(`Unknown command: ${command}`);
+            console.log('Run "npx rox help" for usage information');
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});