Skip to content
downpipes docs

Hand an auditor proof that a restore was correct

An applied restore produces a restore receipt: a per-record statement that what landed is what the archive said it should be. A dry run produces none, because it writes nothing and there is nothing to attest.

The receipt is the artefact to hand to an auditor asking “prove that restore worked”, and the reason it is worth handing over rather than summarising is that it distinguishes five different strengths of proof and does not present them as one.

What one line says

Each restored record contributes a line carrying its name, its source type, the expected hash from the signed manifest, the hash actually computed, whether the two match, and which method produced the comparison.

That last field is the honest part. Not every resource can be re-read after a write, so not every line is the same claim.

The five proof strengths

A large R2 object: the persisted object is re-read and re-hashed. A true proof of the bytes that landed.

A small R2 object: written whole, then re-read and re-hashed. Also a true proof of the landed bytes.

An image: the re-upload keeps its original id, so the live image is read back and re-hashed. A true proof of the landed bytes.

KV, Secrets and D1: no readback. These resources expose no API to read the object back, so the engine performs an atomic write of bytes it has already verified and records that hash. This proves what was written, not what landed. It is a genuinely weaker claim than the three above, and the receipt says so rather than presenting it as equivalent.

A video: the uid resolves. Stream transcodes an uploaded asset to a new object with a new id, so a byte-for-byte comparison is impossible in principle: the stored bytes are not the bytes that were sent. The engine instead proves the new object is live and queryable. There is no hash on this line, and “verified” means the new asset resolved, which is the strongest proof available on a transcoded asset.

If you are assessing coverage, that is the table to read. Four of the five prove the landed bytes; the KV, Secrets and D1 line proves the write; the video line proves existence. None of them claims to be one of the others.

Tamper evidence, and the two words that differ

The receipt is protected two ways, and the distinction between them is stated on the artefact rather than left for you to infer.

It is always anchored into the audit chain. The receipt’s canonical digest is written into the engine’s tamper-evident audit log as a restore-verified entry carrying that digest, the run id, the record count and whether everything verified. So altering the receipt afterwards breaks against a chain you cannot rewrite.

When the engine’s signer key is reachable, it also carries a detached hybrid signature, Ed25519 with ML-DSA-87, the same scheme the archive manifest uses, over the canonicalised receipt core. You verify it against the signer’s public halves you already pinned.

When no signer is reachable, the receipt describes itself as audit-anchored rather than key-signed. That is a deliberate choice worth knowing about: the engine does not fall back to some improvised signing scheme or mint a key to make the artefact look stronger than it is. You get the anchor, and the artefact says that is what you got.

So an auditor’s first question about a receipt is which of those two it is, and the receipt answers it.

Reading the summary honestly

The summary’s all-verified flag is true only when every line verified. A single mismatch flips it false, and a record whose readback ran and disagreed appears in the receipt with its verdict as well as in the failures, so a bad landing is visible in the artefact rather than only in the error path.

A record that failed to write at all is in the failures and not in the receipt, because the receipt is a statement about what was restored.

What it does not contain

Names, hashes and counts. No values, no keys, no credentials. The record name is your own key name, which you already know; nothing else about the content is in there.

That is what makes it safe to hand to an auditor, or to attach to a ticket, without a redaction pass first.

Where this fits

Last updated .