restorable docs
Concepts

Agent, receipt, orchestrator

Three things carry the product. Get these straight and the rest of the docs sit on top of them.

The agent

A single Go binary running in your infrastructure. It holds your keys. It knows how to talk to your databases, take an encrypted backup, upload it, pull it back during a restore test, and run your checks against the restored copy.

The agent is the only thing in the system that ever sees your plaintext. Nothing else can, because nothing else has the keys. When you hear "Restorable cannot read your data," the mechanism behind that claim is the agent.

The agent is pull-driven. It opens an outbound HTTPS connection to the orchestrator on a heartbeat schedule and asks whether there is any work to do. No inbound firewall rules, no websocket, no long-lived connection. This matters because it means the agent works from anywhere your host can reach the internet.

The receipt

A DSSE envelope, signed with your agent's Ed25519 key, wrapping an in-toto Statement that records: at a specific time, a specific backup was restored into a scratch environment, your checks ran against that restore, and here is the result.

The receipt is the product. Everything else in Restorable exists to produce receipts and to make it easy to forward them. The weekly email you receive is a bundle of receipts. The dashboard shows receipts. The auditor you forward the email to verifies receipts.

A receipt is verifiable with nothing but your public key and the restorable-verify binary. No Restorable service is needed at verification time. That is what makes a receipt a piece of evidence instead of a status report.

The orchestrator

The service we run. It coordinates schedules, holds the ciphertext you upload, keeps the transparency log of events for your org, renders the weekly evidence email, and provides the dashboard you use to configure sources and read receipts.

The orchestrator never holds your decryption keys and never sees your plaintext. The backups it stores are age-encrypted by the agent before upload. The signed URLs it issues for upload and download are scoped to one object key and expire in fifteen minutes. Every operator action that touches your org's metadata is logged with a reason code and lands in the same transparency log the receipts do.

One cycle, end to end

Walk through a single restore test to tie the three together.

  1. Your agent's heartbeat arrives. The response includes the schedule for prod-db (e.g. weekly restore test, Sunday 04:00 UTC). The agent caches it.
  2. The cron boundary arrives. The agent's internal scheduler fires the restore test locally.
  3. The agent looks up which ciphertext to restore (most recent backup for prod-db) and calls POST /v1/backups/<id>/download-url. The orchestrator returns a 15-minute signed URL.
  4. The agent downloads the ciphertext, decrypts it with its age key, and spins up an ephemeral Postgres container. It runs pg_restore into that container.
  5. The agent runs every check configured on the source against the restored database. Each check returns a summary row; the agent evaluates the expect expression against it and records pass, fail, or error per check.
  6. The agent assembles the receipt: ids, hashes, per-check results, a roll-up result. It signs the receipt with its Ed25519 key, producing a DSSE envelope.
  7. The agent submits the envelope via POST /v1/receipts. The orchestrator verifies the signature, checks the schema, appends the event to the transparency log, and stores the receipt.
  8. The scratch container is destroyed. The plaintext vanishes.
  9. On Monday morning, the orchestrator renders the weekly digest from the receipts accumulated since the last send, including the current transparency-log tree head, and emails it to you.

That loop is the entire product, repeated on a schedule per source.

What lives where

Thing Where it lives Who can read it
Database plaintext Your database You
Signing key, age key Agent host, /var/lib/restorable/keys/ The agent process
Ciphertext backups Scaleway Object Storage, fr-par Anyone with a valid pre-signed URL for that object key
Backup metadata (size, sha, timestamp) Orchestrator Postgres The orchestrator and authorized dashboard users
Signed receipts Orchestrator Postgres + transparency log Anyone you share them with
Transparency log tree heads Orchestrator, sent in every weekly digest You; anyone you share heads with

If something in the "Who can read it" column surprises you, the next place to read is Trust model.