bitpeek
  1. Bitpeek
  2. Tools
  3. Patches

Offset-Aligned Binary Patches and Verification

Deterministic binary difference recording using absolute byte offsets, strict preconditions, and cryptographic SHA-256 verification.

Try binary diff tool Local processing notes

Why Offset-Aligned Binary Patches?

Traditional textual diff algorithms (such as Myers or unified diff) are designed for line-oriented text files. When applied to binaries, insert/delete shifts invalidate absolute offsets, making verification unreliable.

Bitpeek uses Offset-Aligned Binary Patches:

  • Operations reference absolute byte offsets in the source file.
  • Every mutation includes a precondition: the exact expected bytes that must exist at that offset in the source.
  • If any precondition fails, the patch application aborts immediately without corrupting the file.

Specification: Format v1 vs v2

Bitpeek supports two versions of the bitpeek-offset-patch specification:

  • Version 1 (Preconditions-Only): Legacy format recording target length and replacement operations with optional byte preconditions. Supported for backwards compatibility.
  • Version 2 (Cryptographic Integrity): Modern format requiring source file length, target file length, sourceSha256, and targetSha256. Patches can be independently verified before touching disk.

The 7-Step Atomic Apply Algorithm

Applying a verified patch follows a strict 7-step atomic pipeline:

  1. Source Stabilization: Acquire an immutable snapshot of source bytes.
  2. Schema & Budget Validation: Check that target length and operation counts are within resource limits.
  3. Source Integrity Verification: Validate source length and verify sourceSha256 if provided.
  4. Precondition Checks: Verify that every replacement offset matches the expected precondition bytes in the source.
  5. Target Assembly: Construct the target binary in a newly allocated buffer.
  6. Target Integrity Verification: Compute the SHA-256 hash of the generated target and assert that it matches targetSha256.
  7. Atomic Commit: Commit the new binary as a single transaction in UI history or write to a temporary file before renaming on disk.

Local processing and privacy

The Patches workflow opens the same Bitpeek browser workspace. Selected file bytes, file names, pasted input, searches, edits, hashes, and comparison data are processed in local browser memory and are not sent to a Bitpeek server.

The static guide itself can be read without opening a file or creating an account.

Frequently asked questions

What happens if a patch is applied to the wrong source file?

The patch fails immediately during source hash or precondition checks, leaving the original file completely untouched.

Can offset patches change the length of a file?

Yes. Target length can truncate or extend a binary; extensions append data, while mutations modify bytes at specified offsets.