restorable docs
Reference

Wire protocol

The v1 wire protocol is the contract between the agent, the orchestrator, and the ciphertext store. Every receipt Restorable has ever produced is an instance of this protocol.

The canonical spec lives with the open-source agent and verifier, at restorable/docs/wire-protocol.md in the public repository. The spec is the source of truth; any implementation, including ours, builds to match it.

Goals, in one sentence each

  • One protocol, multiple trust roots. The same format works whether the restore ran in a customer-owned agent or in a confidential-compute enclave. Attestation is a pluggable field, not a separate protocol.
  • Customer's key signs everything. Receipts are always signed by the customer's long-term Ed25519 key. Attestation is evidence inside the signed payload, not a replacement for the signature.
  • Zero plaintext at Restorable. The orchestrator stores ciphertext and metadata, never keys or plaintext.
  • Replay and downgrade resistant. Timestamps, version fields, and algorithm identifiers are inside the signed payload.
  • Auditable by third parties. A customer's auditor verifies receipts using only the customer's public key, no Restorable involvement.

Layered summary

The narrative in this docs site covers the customer-visible shape of each layer. For the exact field-level schema and the byte-level format, read the spec.

  • Entities: Organization, Agent, Source, Check, Backup Record, Ciphertext Blob, Receipt, Transparency Log.
  • Key material: Content Encryption Key (age), Signing Key (Ed25519), API Token. All held by the agent; none leave customer infrastructure.
  • Registration: auth-key flow, POST /api/bootstrap/attach. See Auth key setup.
  • Object store access: pre-signed URLs issued by the orchestrator, 15-minute TTL, scoped to one object.
  • Agent → orchestrator API: /api/bootstrap/attach, /v1/heartbeat, /v1/backups/upload-url, /v1/backups/<id>/download-url, /v1/backups, /v1/receipts, /v1/events, /v1/log/head. See API endpoints.
  • Receipt schema: DSSE envelope with Ed25519 signature wrapping an in-toto Statement v1; predicate carries backup, restore, result, checks array, attestation, issued_at, prev_receipt_id. Walked field by field in What a receipt proves.
  • Transparency log: per-org append-only Merkle log with hourly signed tree heads. Inclusion and consistency proofs via the verifier.

Versioning

Every signed payload carries v: 1. Breaking changes bump the version, but the orchestrator archives old-version verifiers so that historical receipts remain verifiable forever. A v1 receipt signed today is still verifiable decades from now using v1 code from that era.

New attestation types and new source kinds extend the enums without bumping the version.

Where to read it

The full spec is one file, restorable/docs/wire-protocol.md. It is customer-reviewable and auditor-reviewable by design; no internal spec, no private extensions.

The spec repo is Apache-2.0 for code and CC-BY-4.0 for docs. Flipped public on launch.