Integrity

Snapdir is built so that you never have to trust a store — you can check it. Because every object and manifest is content-addressed, its address is also a cryptographic proof of its contents. Verification is just re-hashing the bytes and comparing the digest to the address you expected. This runs automatically on every fetch and on demand via the verify commands.

The integrity guarantee

The default checksum function is BLAKE3. When snapdir hands you bytes for an address h, it re-computes the BLAKE3 hash of those bytes and asserts it equals h. Because BLAKE3 is a cryptographic hash, a match means the bytes are — to cryptographic certainty — exactly what was stored: no silent disk corruption, no truncated download, no tampering in transit or at rest.

This extends to whole trees. A directory's checksum is the merkle hash of its children's checksums, and the snapshot ID is the BLAKE3 hash of the entire manifest text. So verifying a manifest against its snapshot ID, and each object against its checksum, verifies the complete snapshot end to end — one corrupted byte anywhere changes some checksum, which changes its line, which changes the snapshot ID.

Verification on fetch

Integrity is not an optional afterthought; it is part of the transfer protocol. When snapdir fetches an object it:

1. downloads to a temporary path,
2. computes the BLAKE3 checksum of what arrived,
3. compares it to the requested address,
4. retries on mismatch (a corrupt or partial download is discarded), and
5. only then atomically renames the verified bytes into their sharded location.

A failed checksum therefore never becomes visible at its address. This is what makes fetches safe to retry and resume.

Verifying on demand

You can also verify proactively rather than waiting for a fetch:

• snapdir verify checks a snapshot's manifest and objects against their checksums.

• snapdir verify-cache re-hashes the contents of the local cache to detect on-disk corruption.

Checksum modes and what they are for

The checksum function used for the per-entry CHECKSUM field is configurable, but always produces a lowercase hex digest:

Mode	Purpose
BLAKE3 (default)	The security primitive and the basis of all guarantees.
--checksum md5	Legacy/external interop only.
--checksum sha256	Legacy/external interop only.
Keyed BLAKE3 (SNAPDIR_MANIFEST_CONTEXT)	Domain-separated hashing via a context string.

A few rules:

• md5 is not a security primitive. It is offered purely for interoperating with external tooling that already speaks md5; it must not be relied on to detect tampering, since md5 collisions are cheap to construct. sha256 is likewise primarily an interop choice. For any trust boundary, stay on BLAKE3.

• Keyed mode derives the hash from a context string, set via the SNAPDIR_MANIFEST_CONTEXT environment variable. Manifests produced under different contexts are intentionally non-interchangeable.

• The merkle rule and snapshot-ID derivation are hash-agnostic — they run unchanged under any mode — but snapdir id always uses default BLAKE3 regardless of the --checksum selection.

Where to go next

• Content addressing — why an address is a proof.

• Manifests — how checksums compose into a snapshot ID.

• Stores and cache — the push/fetch discipline around verification.

• Commands: snapdir verify, snapdir verify-cache.