stegdoc 5.7.0 → 6.0.0

package/README.md

@@ -1,200 +1,325 @@
 # stegdoc
 
-> Hide files inside Office documents with AES-256 encryption and steganography
+> Hide a file inside a legitimate-looking Office document
 
 [![npm version](https://img.shields.io/npm/v/stegdoc.svg)](https://www.npmjs.com/package/stegdoc)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**stegdoc** is a CLI tool that encodes any file into legitimate-looking Office documents (Excel/Word). Your data is hidden within realistic server access logs and Hebrew incident reports — no hidden sheets, no suspicious content. Optionally protected with AES-256-GCM encryption.
+**stegdoc** encodes any file into an ordinary-looking Excel or Word document.
+The payload is spread across realistic nginx access log entries or Hebrew
+incident reports, so the cover survives casual inspection. Optionally protected
+with AES-256-GCM.
+
+The format engine is written in Rust. It ships as a prebuilt native addon for
+the CLI, and as WebAssembly for the single-file browser tool.
 
 ## Features
 
-- **Log-Based Steganography** — Payload is embedded directly in realistic nginx access log entries (URL tokens, UUIDs, trace IDs). No hidden sheets — the data IS the logs
-- **AES-256-GCM Encryption** — Military-grade encryption with PBKDF2 key derivation (100k iterations)
-- **Brotli Compression** — 15-25% better compression than gzip
-- **Dual Format Support**
-  - **XLSX** — Access log spreadsheet with realistic entries, any file size
-  - **DOCX** — Hebrew RTL incident report with log excerpts, files under 1 MB
-- **Multi-part Splitting** — Automatically split large files across multiple documents
-- **Integrity Verification** — SHA-256 hashing detects tampering
-- **Folder Support** — Encode entire directories (automatically zipped)
-- **Interactive Mode** — User-friendly prompts guide you through options
-- **Legacy Compatibility** — `--legacy` flag produces v4 format for older environments
-- **Backward Compatible** — Reads and decodes all previous format versions
-
-## Installation
+- **Log-based steganography** — the data *is* the logs; there is no hidden
+  sheet and nothing extra to notice
+- **AES-256-GCM** encryption, password-derived keys
+- **v6 by default** — Argon2id key derivation and tamper-evident metadata, with
+  `--v5` for older decoders
+- **Brotli** compression (quality 6), skipped for formats that are already
+  compressed
+- **XLSX and DOCX** covers — an access-log spreadsheet or a Hebrew RTL
+  incident report
+- **Multi-part splitting** for payloads larger than one document
+- **Integrity checking** with SHA-256, verified on decode
+- **ZIP, directory, or single-file input** on decode, discovered automatically
+- **Backward compatible** — the decoder reads every earlier format version
+
+## Install
 
 ```bash
 npm install -g stegdoc
 ```
 
-Or run directly with npx:
+The install pulls a prebuilt engine for the host platform (`win32-x64`,
+`linux-x64`, `linux-arm64`, `darwin-x64`, `darwin-arm64`). No compiler or Rust
+toolchain is required. If a platform package is missing, log-embed files cannot
+be decoded; the CLI says so instead of guessing.
+
+Or run it without installing:
 
 ```bash
-npx stegdoc encode myfile.pdf
+npx stegdoc encode myfile.pdf -p mypassword
 ```
 
-## Quick Start
+## Quick start
 
 ```bash
-# Encode a file with encryption (recommended)
+# Hide a file, encrypted
 stegdoc encode secret.pdf -p mypassword
 
-# Decode it back
+# Get it back
 stegdoc decode access_log_20260315_1200_A1B2_part1.xlsx -p mypassword
 
-# View file info without decoding
+# Inspect without decoding
 stegdoc info access_log_20260315_1200_A1B2_part1.xlsx
 
-# Verify file integrity
+# Check that it will decode
 stegdoc verify access_log_20260315_1200_A1B2_part1.xlsx -p mypassword
 ```
 
 ## Commands
 
-### `encode` — Hide a file in an Office document
-
-```bash
-stegdoc encode <file> [options]
-```
+### `encode <inputs...>`
 
 | Option | Description | Default |
 |--------|-------------|---------|
 | `-o, --output-dir <dir>` | Output directory | Current directory |
-| `-s, --chunk-size <size>` | Split size: `5MB`, `25MB`, `3 parts`, `max` | `5MB` |
-| `-f, --format <format>` | Output format: `xlsx` or `docx` | `xlsx` |
+| `--bundle-name <name>` | Filename recorded when several inputs are bundled | `bundle.zip` |
+| `-s, --chunk-size <size>` | Split size: `5MB`, `25MB`, `3 parts`, or `max` | `5MB` |
+| `-f, --format <format>` | Cover format: `xlsx` or `docx` | `xlsx` |
 | `-p, --password <pass>` | Encryption password | None (unencrypted) |
-| `--legacy` | Use v4 format for backward compatibility | Off |
-| `--no-limit` | Bypass DOCX 1 MB size limit | Off |
+| `--v5` | Emit the v5 format (PBKDF2) | Off (v6) |
+| `--v6` | Emit the v6 format (the default) | On |
+| `--legacy` | Emit the legacy v4 DOCX format | Off |
+| `--no-limit` | Bypass the DOCX 1 MB limit | Off |
 | `--force` | Overwrite existing files | Prompt |
 | `-q, --quiet` | Minimal output for scripting | Off |
 | `-y, --yes` | Skip interactive prompts | Off |
 
-**Examples:**
+A directory is zipped before encoding, and several inputs are bundled into one
+zip first, so a decode hands that archive back. `-s max` produces a single part;
+`-s "3 parts"` splits into roughly three.
 
 ```bash
-# Encode with password (produces access log spreadsheet)
-stegdoc encode document.pdf -p mysecret
-
-# Encode as Hebrew incident report (DOCX)
-stegdoc encode config.json -p mysecret -f docx
-
-# Split into 3 parts
-stegdoc encode large-file.zip -p mysecret -s "3 parts"
-
-# Legacy v4 format (for older environments)
-stegdoc encode data.bin -p mysecret --legacy
-
-# Encode a folder
-stegdoc encode ./my-folder -p mysecret
+stegdoc encode document.pdf -p mysecret                 # access log spreadsheet
+stegdoc encode config.json -p mysecret -f docx          # Hebrew incident report
+stegdoc encode large-file.zip -p mysecret -s "3 parts"  # three parts
+stegdoc encode ./my-folder -p mysecret                  # zipped first
+stegdoc encode a.pdf b.pdf --bundle-name pair.zip -p mysecret
 ```
 
-### `decode` — Recover the original file
-
-```bash
-stegdoc decode <file> [options]
-```
+### `decode <file>`
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `-o, --output <path>` | Output file path | Original filename |
+| `-o, --output <path>` | Output file or directory | Original filename |
 | `-p, --password <pass>` | Decryption password | Prompt if needed |
 | `--force` | Overwrite existing files | Prompt |
 | `-q, --quiet` | Minimal output | Off |
-| `-y, --yes` | Skip prompts, fail if password needed | Off |
+| `-y, --yes` | Skip prompts, fail if a password is needed | Off |
 
-**Examples:**
+Point `decode` at any one part, a directory holding the parts, or a ZIP of
+them; the rest are found automatically.
 
 ```bash
-# Decode with password
 stegdoc decode access_log_20260315_1200_A1B2_part1.xlsx -p mysecret
-
-# Decode DOCX
 stegdoc decode system_report_20260315_0800_CD42_part1.docx -p mysecret
-
-# Multi-part files auto-detected (just provide part 1)
-stegdoc decode access_log_20260315_1200_A1B2_part1.xlsx -p mysecret
+stegdoc decode stegdoc-parts.zip -p mysecret -o ./restored
 ```
 
-### `info` — View metadata without decoding
+### `info <file>`
 
-```bash
-stegdoc info <file>
-```
+Reads metadata without decoding: cover format and version, original filename
+and size, whether it is encrypted and compressed, the part count, and whether
+metadata is authenticated.
 
-### `verify` — Validate file integrity
+### `verify <file> [-p <pass>]`
 
-```bash
-stegdoc verify <file> [-p <password>]
-```
+Runs the structural and password checks without writing any output. It exits
+non-zero if the file will not decode.
 
-## How It Works
+## How it works
 
-### v5 Pipeline (default)
+### Pipeline
 
 ```
-Input File
-    |
-[Brotli Compression]
-    |
-[AES-256-GCM Encryption] (optional)
-    |
-[Log-Embed Encoding] -- payload distributed across log line fields
-    |
-[Office Wrapper] -- XLSX access logs or DOCX incident report
-    |
-Output File(s)
+Input
+  |
+[Brotli q6]              skipped for already-compressed types
+  |
+[AES-256-GCM]            optional
+  |
+[log-embed]              payload spread across log line fields
+  |
+[Office wrapper]         XLSX access logs or a DOCX incident report
+  |
+Output part(s)
 ```
 
-### Data Channels (per log line)
-
-Each nginx access log entry carries **114 bytes** of payload across 6 channels:
+Each log row carries **114 raw bytes** across six channels:
 
-| Channel | Format | Bytes |
-|---------|--------|-------|
+| Channel | Encoding | Bytes |
+|---------|----------|-------|
 | URL path segment | base64url | 21 |
 | Query param `token` | base64url | 21 |
 | Query param `state` | base64url | 21 |
 | Referer `ref` param | base64url | 21 |
-| X-Request-ID | UUID v4 (hex) | 14 |
-| X-Trace-ID | 32-char hex | 16 |
+| `X-Request-ID` | UUID v4 | 14 |
+| `X-Trace-ID` | 32-char hex | 16 |
+
+Metadata and encryption parameters travel in header lines marked by the
+`/api/v1/health` path, in a length-prefixed frame:
+
+```
+STGD06|<metaLen>|<encLen>|<kdfLen>|{metadataJson}{encryptionMeta}{kdfParams}
+```
+
+v5 uses the shorter `STGD05|<metaLen>|<encLen>|...` frame. The decoder
+dispatches on the marker.
 
-### Output Formats
+Decoding uses `payloadSize` and `dataLineCount` from the metadata to truncate
+the payload. Filler rows are appended for realism and ignored on decode.
 
-**XLSX** — Single "Access Logs" sheet with realistic nginx log entries. Columns: Remote Address, Timestamp, Method, Request, Status, Bytes, Referer, User-Agent, X-Request-ID, X-Trace-ID. No hidden sheets.
+### Covers
 
-**DOCX** — Hebrew RTL incident report with title, executive summary, timeline table, log excerpts in monospace code blocks, root cause analysis, and recommendations. Reports are procedurally generated (15 services x 12 incident types = thousands of unique variants).
+**XLSX** — a single "Access Logs" sheet of realistic nginx entries with columns
+for remote address, timestamp, method, request, status, bytes, referer,
+user-agent, `X-Request-ID`, and `X-Trace-ID`. No hidden sheets.
 
-### Encryption
+**DOCX** — a Hebrew RTL incident report: title, executive summary, timeline
+table, log excerpts in monospace blocks, root cause, and recommendations. The
+prose is generated deterministically from the payload hash, so covers do not
+repeat. DOCX refuses inputs over 1 MB unless `--no-limit` is given; use XLSX
+for large payloads.
 
-- **Algorithm**: AES-256-GCM (Galois/Counter Mode)
-- **Key Derivation**: PBKDF2-SHA256 with 100,000 iterations
-- **Key Size**: 256 bits
-- **IV**: 96 bits (randomly generated per part)
-- **Salt**: 128 bits (shared per session)
-- **Authentication**: 128-bit auth tag
+### Multi-part output
 
-### Filenames
+Large payloads are split across parts. Parts are built in parallel, each with
+its own IV and tag but a shared session salt, and the CLI prints progress.
+Decode finds the sibling parts automatically.
+
+Filenames are decoys:
 
 ```
 access_log_YYYYMMDD_HH00_XXXX[_partN].xlsx
 system_report_YYYYMMDD_HH00_XXXX[_partN].docx
 ```
 
-## Legacy Mode
+## Encryption
+
+Encryption is optional but recommended. Without `-p`, the payload is hidden but
+not encrypted.
+
+### v6 (default)
+
+v6 makes the metadata tamper-evident and uses a memory-hard KDF. The cover,
+channels, chunking, and filenames are identical to v5; only the header and
+crypto change.
+
+| | |
+|---|---|
+| Cipher | AES-256-GCM |
+| Key derivation | Argon2id, version 19, `m=65536` KiB, `t=3`, `p=1` |
+| Key | 256-bit |
+| IV | 96-bit, random per part |
+| Salt | 128-bit, shared per session |
+| Tag | 128-bit |
+
+The KDF parameters are recorded in the file and reproduced on decode. When
+encrypted, the AEAD associated data is the header frame minus the encryption
+parameters, so changing the original filename, size, content hash, or KDF
+parameters breaks decryption. The frame is
+`STGD06|<metaLen>|<encLen>|<kdfLen>|...`.
+
+### v5 (opt-in, `--v5`)
+
+v5 uses PBKDF2 and leaves the metadata unauthenticated. It exists for decoders
+that predate v6, and its read compatibility is permanent.
+
+| | |
+|---|---|
+| Cipher | AES-256-GCM |
+| Key derivation | PBKDF2-SHA256, 100,000 iterations |
+| Key | 256-bit |
+| IV | 96-bit, random per part |
+| Salt | 128-bit, shared per session |
+| Tag | 128-bit |
+
+v6 requires the native engine to produce; `--v5` is the only format the
+JavaScript fallback can emit. The decoder reads both versions without a flag.
+
+## Decode inputs
+
+`decode` accepts:
+
+- a single encoded `.xlsx`/`.docx`,
+- a directory containing the sibling parts,
+- a ZIP holding the parts.
+
+A ZIP is expanded, non-container entries are ignored, and the first complete
+part set is decoded. Only ZIP is supported; RAR and 7z would need extra
+decoders.
+
+## Browser tool
+
+The same engine also runs as WebAssembly in a single self-contained HTML file,
+for offline use where installing anything is not an option.
+
+```bash
+pnpm install
+pnpm build:web        # -> dist/stegdoc.html
+```
 
-Use `--legacy` to produce v4 format files (hidden sheet + gzip compression) for environments that haven't upgraded to stegdoc v5:
+Open `dist/stegdoc.html` in a browser. Encoding and decoding run in a Web Worker
+so the page stays responsive; nothing is uploaded and no network is used. The UI
+offers XLSX or DOCX, v6 or v5, an optional password, an optional chunk size, and
+Brotli compression. Several files can be selected at once and are bundled into
+one zip before encoding. When the browser supports the File System Access API,
+the page asks for an output folder and writes the documents straight into it;
+otherwise a single part downloads directly and a multi-part set downloads as one
+`stegdoc-parts.zip`. Input is held in memory, so the UI warns above 64 MiB and
+refuses past 128 MiB with a pointer to the CLI.
+
+## Security model
+
+- The native engine performs no filesystem writes. The CLI owns the output
+  path, the overwrite prompt, and the write.
+- The original filename in the metadata is untrusted. It is reduced to a bare
+  filename and cannot escape the chosen output directory.
+- Decompression output and ZIP expansion are bounded, so a crafted file fails
+  on the cap instead of exhausting memory or disk.
+- `contentHash` is verified after decoding and the output is deleted on
+  mismatch.
+- v6 binds the metadata to the ciphertext; v5 metadata is plaintext and its
+  integrity rests on `contentHash` and the path rules.
+
+The wire format is specified in [`spec/FORMAT.md`](spec/FORMAT.md).
+
+## Compatibility
+
+- The decoder auto-detects the version, so no flag is needed to read old files.
+- v6 is the default output. `--v5` emits the older format; both cover XLSX and
+  DOCX. `--legacy` produces v4 DOCX only; legacy XLSX is unsupported.
+- v3/v4 are read-only paths kept for old files.
+- Log-embed (v5/v6) decoding requires the native engine. Without it, the CLI
+  fails loudly rather than falling back to an incomplete reader.
+- Encoding and decoding are randomised, so two encodes of the same input are
+  not byte-identical; conformance is defined on the decode direction.
+
+## Building from source
+
+Requires Node.js >= 18 and a Rust toolchain.
 
 ```bash
-stegdoc encode data.bin -p mypass --legacy
+pnpm install
+pnpm build:native          # build the napi binding -> native/stegdoc.node
 ```
 
-The decoder auto-detects format version — it reads both v4 and v5 files without any flags.
+Then run the CLI directly with `node src/index.js <command>`.
+
+| Command | Purpose |
+|---------|---------|
+| `pnpm test` | conformance against the frozen fixtures (builds native first) |
+| `pnpm test:rust` | the Rust decoder against the same fixtures |
+| `pnpm test:interop` | Rust encode -> JavaScript decode |
+| `pnpm test:safety` | output-path traversal containment |
+| `pnpm test:contract` | CLI flags, exit codes, filenames |
+| `pnpm build:wasm` | the wasm binding -> `web/pkg` |
+| `pnpm build:web` | the single-file browser tool -> `dist/stegdoc.html` |
+| `pnpm test:wasm` | wasm round-trip, headless in Node |
+| `pnpm test:browser` | the built page, round-trip from `file://` |
+| `cargo test` | Rust unit and property tests |
 
 ## Requirements
 
-- Node.js 18.0.0 or higher
+- Node.js >= 18 for the CLI
+- A supported platform for the prebuilt engine (see Install)
 
 ## License
 
-MIT License — see [LICENSE](LICENSE) for details.
+MIT — see [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stegdoc",
-  "version": "5.7.0",
+  "version": "6.0.0",
   "description": "Hide files inside Office documents (XLSX/DOCX) with AES-256 encryption and steganography",
   "main": "src/index.js",
   "bin": {
@@ -9,7 +9,20 @@
   "scripts": {
     "start": "node src/index.js",
     "dev": "node src/index.js",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "fixtures": "node spec/tools/generate-fixtures.js",
+    "vectors": "node spec/tools/generate-channel-vectors.js",
+    "build:native": "node scripts/build-native.js",
+    "build:binding": "node scripts/build-binding.js",
+    "prepare-publish": "node scripts/prepare-publish.js",
+    "build:wasm": "node scripts/build-wasm.js",
+    "build:web": "node scripts/build-web.js",
+    "test": "pnpm build:native && node spec/tools/conformance.js",
+    "test:rust": "node spec/tools/conformance.js --bin target/debug/stegdoc",
+    "test:interop": "node spec/tools/interop.js",
+    "test:safety": "node spec/tools/safety.js",
+    "test:contract": "pnpm build:native && node spec/tools/contract.js",
+    "test:wasm": "node spec/tools/wasm-roundtrip.js",
+    "test:browser": "node spec/tools/browser.js"
   },
   "keywords": [
     "cli",
@@ -54,5 +67,15 @@
     "file-type": "^16.5.4",
     "inquirer": "^8.2.6",
     "ora": "^5.4.1"
+  },
+  "devDependencies": {
+    "playwright-core": "^1.63.0"
+  },
+  "optionalDependencies": {
+    "@stegdoc/binding-win32-x64-msvc": "6.0.0",
+    "@stegdoc/binding-linux-x64-gnu": "6.0.0",
+    "@stegdoc/binding-linux-arm64-gnu": "6.0.0",
+    "@stegdoc/binding-darwin-x64": "6.0.0",
+    "@stegdoc/binding-darwin-arm64": "6.0.0"
   }
 }