feat(transform): add bitimage transform #58

oritwoen · 2026-01-05T13:24:00Z

Summary

Implements the Bitimage puzzle key derivation algorithm, enabling vuke to derive Bitcoin keys from arbitrary file contents using the same method as the Bitimage puzzles.

Closes #45

Changes

BitimageDeriver (src/bitimage.rs): Core algorithm - file bytes → base64 → SHA256 → BIP39 mnemonic (24 words) → seed with passphrase → HD derive
BitimageTransform (src/transform/bitimage.rs): Transform trait implementation with configurable path, passphrase, and derive count
FilesSource (src/source/files.rs): New input source supporting --file for single files and --dir for recursive directory traversal (skips symlinks)
Input.blob field: Extended Input struct to carry arbitrary binary data
CLI integration: Added --bitimage-path, --bitimage-passphrase, --bitimage-passphrase-wordlist, --bitimage-derive-count options to both Generate and Scan commands
Documentation: Updated README with usage examples and architecture

Testing

Unit tests for BitimageTransform (determinism, passphrase handling, derive count)
Unit tests for FilesSource (recursive traversal, symlink skipping)
Manual end-to-end test: vuke generate --transform=bitimage files --file test.txt
All 223 existing tests pass

Co-Authored-By: Aei [email protected]

Implements the Bitimage puzzle key derivation algorithm: - file bytes → base64 → SHA256 → BIP39 mnemonic → HD derive New components: - BitimageDeriver: core derivation logic with passphrase support - BitimageTransform: Transform trait implementation - FilesSource: reads files from --file or --dir (recursive) - Input.blob field: supports arbitrary binary data CLI options: - --bitimage-path: HD derivation path (default: m/84'/0'/0'/0/0) - --bitimage-passphrase: BIP39 passphrase - --bitimage-passphrase-wordlist: brute-force passphrases - --bitimage-derive-count: derive multiple addresses per file Closes #45

codspeed-hq · 2026-01-05T13:27:24Z

CodSpeed Performance Report

Merging #58 will not alter performance

_{Comparing feat/bitimage-transform (25bb812) with main (1304b63)}

Summary

✅ 7 untouched

cubic-dev-ai

3 issues found across 25 files

Prompt for AI agents (all issues)


Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="src/source/files.rs">

<violation number="1" location="src/source/files.rs:110">
P2: When file reads fail, they&#39;re silently skipped but still counted in `inputs_processed`. This causes inaccurate stats reporting. Consider tracking successfully processed files separately, or at minimum logging skipped files via `tracing::warn!`.</violation>
</file>

<file name="src/bitimage.rs">

<violation number="1" location="src/bitimage.rs:102">
P1: Missing BIP32 index range validation. Derivation path indices must be &lt; 2^31 (2147483648) per BIP32 spec. Indices &gt;= 2^31 will cause incorrect hardened derivation behavior.</violation>
</file>

<file name="src/transform/bitimage.rs">

<violation number="1" location="src/transform/bitimage.rs:41">
P2: Silent error swallowing: `.filter_map(Result::ok)` discards I/O errors when reading the wordlist. If lines fail to read (invalid UTF-8, I/O errors), they&#39;re silently skipped. Consider using `.collect::&lt;Result&lt;Vec&lt;_&gt;,_&gt;&gt;()?` to propagate errors, or at minimum log skipped lines.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

src/source/files.rs

src/bitimage.rs

src/transform/bitimage.rs

greptile-apps · 2026-01-05T13:32:57Z

Greptile Summary

This PR implements the Bitimage puzzle key derivation algorithm, enabling vuke to derive Bitcoin keys from arbitrary file contents using the same method as the Bitimage puzzles (file → base64 → SHA256 → BIP39 mnemonic → HD key derivation).

Key changes:

Added BitimageDeriver in src/bitimage.rs implementing the core algorithm with proper BIP39/BIP32 derivation
Added BitimageTransform implementing the Transform trait with configurable path, passphrase, and derive count
Added FilesSource supporting single file (--file) and recursive directory (--dir) input modes with symlink skipping
Extended Input struct with blob field for arbitrary binary data
Added CLI options: --bitimage-path, --bitimage-passphrase, --bitimage-passphrase-wordlist, --bitimage-derive-count
Updated documentation with usage examples

The implementation follows existing patterns in the codebase (Source trait, Transform trait, builder patterns) and includes comprehensive unit tests.

Confidence Score: 5/5

This PR is safe to merge with minimal risk - well-structured implementation following existing patterns with comprehensive tests
The implementation is clean, follows existing codebase patterns (Source/Transform traits), includes proper error handling, has comprehensive unit tests, and the cryptographic operations use established libraries (secp256k1, sha2, hmac). The code has good separation of concerns with the core algorithm in bitimage.rs and the transform adapter in transform/bitimage.rs.
No files require special attention

Important Files Changed

Filename	Overview
src/bitimage.rs	Core Bitimage derivation algorithm implementing file→base64→SHA256→BIP39→HD key derivation with proper error handling and comprehensive tests
src/transform/bitimage.rs	BitimageTransform implementing Transform trait with builder pattern; minor inconsistency in with_passphrase_wordlist method signature (takes &mut self vs self)
src/source/files.rs	FilesSource for single file or recursive directory processing with symlink skip, parallel processing via Rayon, proper error handling
src/main.rs	CLI integration adding bitimage options and Files source command with proper clap conflicts_with configuration
src/transform/mod.rs	TransformType enum extended with Bitimage variant, proper factory method implementation with error handling for wordlist loading
src/transform/input.rs	Input struct extended with blob field for arbitrary binary data, new from_blob constructor for file-based transforms
README.md	Documentation updated with bitimage usage examples and architecture references

Sequence Diagram

sequenceDiagram
    participant User
    participant CLI as CLI (main.rs)
    participant FS as FilesSource
    participant BT as BitimageTransform
    participant BD as BitimageDeriver
    participant Out as Output

    User->>CLI: "vuke generate --transform=bitimage files --file image.jpg"
    CLI->>FS: "FilesSource::from_file(path)"
    FS->>FS: "read_file_contents()"
    FS->>BT: "apply_batch with Input containing blob"
    BT->>BD: "BitimageDeriver::from_file_bytes(data, passphrase)"
    BD->>BD: "base64::encode(data)"
    BD->>BD: "SHA256(base64)"
    BD->>BD: "entropy_to_mnemonic(hash)"
    BD->>BD: "mnemonic_to_seed(mnemonic, passphrase)"
    BD->>BD: "seed_to_master_key(seed)"
    BT->>BD: "derive_path(m/84h/0h/0h/0/0)"
    BD->>BD: "BIP32 child derivation"
    BD-->>BT: "private key bytes"
    BT-->>FS: "source and key pairs"
    FS->>Out: "output.key(source, bitimage, derived)"
    Out-->>User: "Display result"

greptile-apps

Additional Comments (4)

src/source/mod.rs, line 42-48 (link)

logic: Missing Files variant in SourceType enum - this would be needed for CLI integration of the new FilesSource

Should the Files variant be added to this enum to support the new FilesSource?
src/transform/armory.rs, line 96 (link)

syntax: The check for input.bytes_be should use pattern matching instead of if let Some(be) = input.bytes_be since bytes_be appears to be an array field, not an Option
src/transform/double_sha256.rs, line 61-70 (link)

logic: This processes byte representations for ALL inputs, not just those that failed GPU processing. This may create duplicate outputs - bytes should only be processed for inputs that weren't handled by GPU or were in cpu_fallback.
src/transform/sha256.rs, line 59-66 (link)

logic: Binary data processing in GPU fallback duplicates all inputs instead of only unprocessed ones, potentially causing duplicate outputs

_{24 files reviewed, 6 comments}

_{Edit Code Review Agent Settings | Greptile}

src/transform/bitimage.rs

src/main.rs

- Add BIP32 index validation (must be < 2^31) with tests - Log warnings for file read failures in FilesSource - Log warnings for wordlist line read errors in BitimageTransform

greptile-apps

Additional Comments (3)

src/source/mod.rs, line 42-48 (link)

logic: Missing Files variant in SourceType enum. The FilesSource is exported but not included in the clap ValueEnum, making it inaccessible via CLI.
src/transform/double_sha256.rs, line 61-70 (link)

logic: All inputs are being processed for binary data even after GPU processing, potentially creating duplicate keys. This loop should only process inputs that weren't handled by the GPU pipeline or exclude inputs already processed in the GPU results.
src/transform/sha256.rs, line 59-66 (link)

logic: This processes byte arrays for ALL inputs, including those already processed by GPU. This will create duplicate hash entries for inputs that were GPU-processed since those inputs already had their byte arrays processed in the GPU pipeline. Should byte array processing only apply to inputs that weren't processed by GPU to avoid duplicates?

_{24 files reviewed, 4 comments}

_{Edit Code Review Agent Settings | Greptile}

src/source/files.rs

inputs_processed now counts only files that were read successfully, not all discovered files including those that failed to read.

oritwoen self-assigned this Jan 5, 2026

cubic-dev-ai bot reviewed Jan 5, 2026

View reviewed changes

src/source/files.rs Show resolved Hide resolved

src/bitimage.rs Show resolved Hide resolved

src/transform/bitimage.rs Outdated Show resolved Hide resolved

greptile-apps bot reviewed Jan 5, 2026

View reviewed changes

src/transform/bitimage.rs Show resolved Hide resolved

src/main.rs Show resolved Hide resolved

fix: address code review feedback

36988e0

- Add BIP32 index validation (must be < 2^31) with tests - Log warnings for file read failures in FilesSource - Log warnings for wordlist line read errors in BitimageTransform

greptile-apps bot reviewed Jan 5, 2026

View reviewed changes

src/source/files.rs Show resolved Hide resolved

fix: track only successfully processed files in stats

25bb812

inputs_processed now counts only files that were read successfully, not all discovered files including those that failed to read.

oritwoen merged commit 20d8997 into main Jan 5, 2026
4 checks passed

oritwoen deleted the feat/bitimage-transform branch January 5, 2026 14:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(transform): add bitimage transform #58

feat(transform): add bitimage transform #58

Uh oh!

oritwoen commented Jan 5, 2026

Uh oh!

codspeed-hq bot commented Jan 5, 2026 •

edited

Loading

Uh oh!

cubic-dev-ai bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps bot commented Jan 5, 2026 •

edited

Loading

Uh oh!

greptile-apps bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

greptile-apps bot left a comment •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

feat(transform): add bitimage transform #58

feat(transform): add bitimage transform #58

Uh oh!

Conversation

oritwoen commented Jan 5, 2026

Summary

Changes

Testing

Uh oh!

codspeed-hq bot commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

CodSpeed Performance Report

Merging #58 will not alter performance

Summary

Uh oh!

cubic-dev-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

greptile-apps bot commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Additional Comments (4)

Uh oh!

Uh oh!

Uh oh!

greptile-apps bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Additional Comments (3)

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

codspeed-hq bot commented Jan 5, 2026 •

edited

Loading

greptile-apps bot commented Jan 5, 2026 •

edited

Loading

greptile-apps bot left a comment •

edited

Loading

greptile-apps bot left a comment •

edited

Loading