Gabriele SalatiSysadmin, privacy e self-hosting

ProofBundle / project provenance

ProofBundle: verifiable project integrity with Merkle roots and signatures

ProofBundle is a local-first tool for creating portable cryptographic evidence bundles. It turns a file, zip archive, or directory into a deterministic manifest, a Merkle root, a signed author or custody claim, and optional OpenTimestamps evidence anchored to public blockchains.

Back to the blog Contact

What we are proving

For the projects I publish and discuss publicly, including the ones I present on LinkedIn, I want more than a repository link or a screenshot. The useful proof is technical: this exact project state existed, these files matched this manifest, this Merkle root represented the project, and a declared key signed the claim.

This is not copyright registration and it is not a legal shortcut. It is technical evidence of existence, integrity, temporal priority, and a signed author or custody claim.

How the bundle is built

  1. ProofBundle walks the target file, zip archive, or directory in a deterministic order.
  2. Each entry is hashed with SHA-256 and recorded in a canonical JSON manifest.
  3. The entry hashes are reduced into a Merkle tree, producing one Merkle root for the whole project snapshot.
  4. An author-claim document binds that root, the manifest hash, the project metadata, and the signing identity.
  5. The claim is signed with either the default Ed25519 key or an optional OpenPGP signature.
  6. When available, OpenTimestamps stamps the timestamp target and anchors it to public blockchains without uploading the original work or putting project contents on-chain.

Why Merkle roots matter

A project is rarely one file. Source code, documentation, images, datasets, music stems, and design assets often live as directories. A Merkle tree lets ProofBundle represent that whole state with one root while still keeping each file independently accountable.

If a file changes, its hash changes. If a leaf changes, the Merkle path changes. If the tree changes, the root changes. That makes tampering visible during verification.

OpenTimestamps and blockchain anchoring

OpenTimestamps adds the independent time component. ProofBundle prepares a timestamp target from the Merkle root and manifest hash, then the external ots client can anchor that digest to public blockchains.

The important detail is that the original work is not uploaded to ProofBundle and is not written on-chain. The blockchain only sees timestamping evidence for a digest. Later, the proof can show that the project root and manifest hash existed before the blockchain attestation matured.

This gives ProofBundle three separate checks: integrity through hashes and the Merkle root, identity or custody through the signature, and temporal evidence through OpenTimestamps blockchain anchoring.

Signing options: Ed25519, OpenPGP, and YubiKey

The default ProofBundle signer is Ed25519. It is modern, compact, and simple to verify, which makes it a good default for local proof generation.

For people who already use OpenPGP, ProofBundle can also create a detached OpenPGP signature over the author claim. That means an existing public identity can be reused instead of introducing a new verification habit.

OpenPGP signing can also be backed by a YubiKey. In that setup, the private signing key can remain hardware-backed and non-exportable. The YubiKey is optional, but it strengthens key custody because the signing operation happens through the hardware token instead of leaving a normal private key file on disk.

Example workflow

proofbundle create ./project --title "Project snapshot" --author "Gabriele Salati"
proofbundle verify project.proof.zip --work ./project

proofbundle create ./project \
  --signer openpgp \
  --signing-key 08BBBF34E279618861E2897D03E8E3F46FBDC8AA

Current public attestation

The ProofBundle repository itself has been attested with ProofBundle. A public Git snapshot was bound to a deterministic manifest, a Merkle root, a signed claim, and timestamp material.

  • Commit: 9564d3c
  • Merkle root: 17c826018d65bb03eb4017c07d7b2627f474270b61a93c566ee28983158f6acb
  • OpenPGP fingerprint: 08BBBF34E279618861E2897D03E8E3F46FBDC8AA

This does not ask anyone to trust the website. The point is that the bundle can be checked against the files, the root, and the signature.

What it does not prove

Good cryptographic proof should be explicit about its limits. ProofBundle does not prove legal ownership by itself, does not prove originality, and does not prove that nobody created the same work earlier. It also does not replace SIAE, courts, registries, or legal advice.

What it gives is a portable technical dossier: hashes, manifest, Merkle root, signed claim, optional OpenTimestamps proof, blockchain-anchored timestamp evidence, and offline verification.