Glossary
This glossary defines the terms the rest of the docs use.
Where a term has a subtle distinction that matters (the break-glass key versus the break-glass token, tamper-evident as detection rather than prevention), the definition states the distinction. A pointer at the end of each cluster sends you to the page that treats the term in depth.
Engine and governance terms
These name the parts of the in-account engine and its access model.
| Term | Definition |
|---|---|
| Admin API | The HTTP surface the console calls on the in-account engine (/admin/*), authenticated in-account and gated per route. It mutates only through POST and reads through GET. |
| SchedulerDO | The scheduler Durable Object that owns the per-downpipe due times, the run lock, the hash-chained audit log, the role tables and the RUNLOG index. It is the server-side authority every admin route forwards to. |
| Capability | The explicit unit of authority a route gates on, for example restore.apply or keys.ceremony. A route checks a capability, not a rank, so a narrow role can hold a specific subset of powers. |
| Role | A named bundle of capabilities. The four cumulative roles are viewer, operator, approver and owner; two narrow roles (restore-operator, access-admin) sit off the ladder and hold a deliberate subset; custom roles are account-defined bundles. |
| Owner-exclusive capability | A capability only the owner built-in holds and that may never be placed in a custom role: the key ceremony (keys.ceremony) and accepting a posture risk (posture.riskaccept). |
| Owner-action | A high-blast-radius owner operation that can be put behind dual control, so a second owner must approve a recorded action before the privileged step runs. A queued owner action is a not-yet-acted outcome, never a failure. |
| Plan hash | The engine’s server-recomputed binding of a specific restore plan. A restore approval is bound to one plan hash, and a changed plan produces a different hash that voids the prior approval. |
Authorisation keys on a stable subject, or on an identity provider group you map. For Cloudflare Access and a native OIDC or OAuth2 provider, the subject is the provider’s verified subject or immutable user id. A reassigned email at that provider does not inherit a departed member’s role. For SAML, the subject is the NameID, which must not be transient. For a passkey, the subject is the engine’s own credential principal, which comes from the email the passkey is bound to.
For the full role-by-capability matrix and how a session is verified, see roles and capabilities and authentication and authorisation.
Break-glass: the key and the token are different things
Two different things share the word “break-glass”, and conflating them is a real error. One is a cryptographic key that decrypts your archives offline. The other is a bearer credential that lets an operator into the admin API when single sign-on is unavailable. They protect different things and live in different places.
| Term | Definition |
|---|---|
| Break-glass key | The offline private half of the mandatory break-glass recipient. Its private key is held by the customer offline, on an encrypted drive, in a password manager or split across custodians, and never reaches the vendor or Cloudflare. It is never written onto the printed recovery sheet, which carries fingerprints only. It is the only key that can always open an archive, and it may be Shamir-split across several offline holders. |
| Break-glass token | The ADMIN_TOKEN bearer fallback for the admin API: an all-or-nothing owner login used when Cloudflare Access or single sign-on is not configured. It is email-less, so it is not attributable and resolves to the owner break-glass. It can be disabled once another sign-in method is in place: Cloudflare Access, a passkey, OIDC or SAML. |
| Recovery codes | Per-user one-time codes a passkey or Access user can use to sign in when their usual method is unavailable. They are an admin-API sign-in path, distinct from both the break-glass key and the ADMIN_TOKEN. |
The break-glass key is about reading data without anyone’s help; the break-glass token and recovery codes are about reaching the console when sign-in is degraded. The page on break-glass offline recovery covers the key, and session management covers the token and recovery-code sign-in paths.
Recovery, run and freshness terms
These describe what a backup run is and how the system decides which run is current.
| Term | Definition |
|---|---|
| Run | One execution of one downpipe, identified by a runId (a canonical 26-character ULID). A run is the unit a restore selects. |
| runId | The canonical uppercase Crockford base32 ULID that identifies a run and appears in its object paths. It is never lowercased in a path. |
| RUNLOG | The append-only, signed freshness anchor at _RECOVERY/RUNLOG. Freshness ordering is decided by the signed RUNLOG, never by a manifest timestamp, so a reader anchors “is this the latest run” on signed evidence. |
| Freshness | Whether a run is the newest good run for its downpipe. A reader checks it against the RUNLOG and can be told to proceed on an older run on purpose. Recovery is at run granularity: the recovery point is the newest good run, not an arbitrary instant. |
| The newest good run | The recovery objective downpipes actually offers. When you pick a moment to recover to, whether directly or via the restore screen’s calendar, the engine resolves it to the latest successful run completed at or before that moment, from a bounded per-downpipe history ring; there is no arbitrary timestamp to restore to, only a specific retained run. |
The point worth flagging is the last row. Point-in-time, by-timestamp resolution is an engine-API capability that the restore screen’s calendar consumes directly, and it resolves to a specific retained run, never an arbitrary instant: the console restore always picks a run by id. See recovery objectives for how RPO and RTO are framed, and runs and history for the retained ring.
Archive format terms
These name the structural pieces of the downpipe/0.1.0 archive.
| Term | Definition |
|---|---|
downpipe/0.1.0 archive | The content-addressed, self-describing archive format. The version string downpipe/0.1.0 is byte-identical wherever it appears, in the manifests and in the key-derivation labels. The format is versioned by semver: while the major is 0, any byte-level change bumps the minor and is a new format identity. |
| Record | One backed-up item, for example a KV key and its value, an R2 object, a secret, a database dump, a Cloudflare config surface, a Worker’s code and settings, or a Stream or Images inventory entry. A record has a stable per-run identity and a plaintextSha384 over its full reassembled value. |
An encrypted shard manifest (run/<runId>/manifest/<shardId>.dpe): newline-delimited record lines plus a preamble carrying the reconnaissance metadata kept out of the cleartext root. It is sealed under a key derived from the run master. | |
| Merkle root | The RFC 6962 Merkle root over the per-record hashes, signed in the root manifest. Because each record hash binds that record’s plaintext hash and name, the signature transitively covers the integrity of every record’s value and name. |
| Recipient set | The set of recipient public identities the per-run master is wrapped to in the master capsule. Every recipient is a hybrid X25519 plus ML-KEM-1024 identity, and every run carries the break-glass recipient at minimum. |
downpipe/0.1.0 (the archive format string) | The literal version string the manifests and labels carry. A reader accepts exactly the downpipe/0.1.x line, because a patch changes no byte-level rule. It is distinct from the tool version: the offline binary may report a different version (an unstamped build reports dev) while still reading a downpipe/0.1.0 archive. |
The recipient set is where the two recovery postures live, defined next. For the full byte-level contract see cryptography and the anatomy of a backup run.
The two recovery postures
A downpipe is configured in one of two postures, and the active posture changes who can decrypt under a full account compromise. The recovery sheet records which posture a downpipe uses.
| Term | Definition |
|---|---|
| Two-recipient posture | The run is wrapped to both an in-account operational recipient and the offline break-glass recipient. Either opens the capsule. The operational private key is a decryption-capable in-account identity by design, so it gives the live account a read-back and verification path. |
| Break-glass-only posture (the default) | The run is wrapped to the break-glass recipient alone, with no operational recipient. Only the offline key can open the archive, so a full account compromise yields no key that decrypts the data. The cost is that the engine cannot reopen a sealed run on its own, so the unattended work stops: scheduled restore tests, the automated drill and in-account retention pruning. Verification at seal and the canary still run, and an attended in-console restore still works with the break-glass key supplied to the browser. |
Where the optional operational key has been added, the engine holds its decryption-capable private half and can therefore open an archive on its own. In the default posture it holds no such key. What stays true in both postures is that the vendor holds nothing and the break-glass private key lives offline. See recovery postures and the no-custody trust model.
Cryptography terms
These are the cryptography and security terms.
| Term | Definition |
|---|---|
| Post-quantum hybrid | The construction combines a classical primitive with a post-quantum one so an archive stays safe if either half is later broken: a hybrid X25519 plus ML-KEM-1024 KEM for confidentiality, and a hybrid Ed25519 plus ML-DSA-87 signature with both halves required. It is a hedge against one half falling, not a guarantee that neither will. |
| Tamper-evident | A change to a signed or hash-chained object is detectable on verification: the manifests are signed, every segment is bound to its own identity and position, and the audit log is hash-chained. This is detection, not prevention. |
| Master | A per-run 32-byte secret, freshly generated for each run of a downpipe, wrapped to the recipient set in the master capsule, from which every per-unit file key is derived. It is never written in the clear. |
| Signer | The hybrid Ed25519 plus ML-DSA-87 keypair that signs the root manifest and the RUNLOG, both halves required with no downgrade. When the engine holds the signer, it also signs the assurance reports it generates. It is generated on the customer side, its private half is installed in the in-account engine, and the vendor never holds it. |
| Conformance vector | A normative test fixture under the format’s testdata/vectors. A reader is conformant when it recovers every positive vector and rejects every negative vector with the stated exit code; a writer is conformant when it reproduces the pinned bytes for the writer-authoritative object classes. |
Two cautions follow. First, post-quantum hybrid is a hedge against one half falling, not a guarantee that neither half will. Second, tamper-evident describes detection on verification, and verification of a report or an archive happens out of band, covered next.
Assurance and verification terms
These name how downpipes proves a backup is recoverable.
| Term | Definition |
|---|---|
| Keyless attestation | A proof that needs no decryption key and touches no record plaintext: it verifies the manifest signature, structural completeness (shard hashes and count), and the RUNLOG anti-rollback. An attestation is therefore an engine-side completeness and anti-rollback check, not a content read, and it runs even in the break-glass-only posture. |
| Blind restore test | A read-safe recoverability proof that decrypts every in-scope record to a discard sink, checks each plaintext hash, and writes nothing and surfaces no plaintext. It produces a restore digest over each record’s identity and plaintext hash so a repeat test proves the same data restores. |
| Restore receipt | A record the offline reader writes after a verify or restore when --receipt names a path. It states what was proven (the signer it checked against, the records handled, the exit code). It is signed only with --receipt-signer, and otherwise carries signed: false. |
| Restorability assurance | The capability family that proves an archive recovers without writing a byte back: it gates the blind restore test and the keyless attestation, and it is read-safe, granted from the viewer floor up. |
A captured snapshot is proven recoverable by the blind restore test or a keyless attestation, but full verification is out of band: the verifying key is not in the browser, so the console asserts a signature is present and well-formed rather than performing the cryptographic verification itself. From reader 0.3.4, downpipe verify-report checks the signature on an assurance report offline against your signer.pub. See prove recoverability and reports.
Coverage and configuration terms
These describe what is protected and the configuration backup.
| Term | Definition |
|---|---|
| Source type | One of the eight selectable kinds of resource a downpipe backs up: KV, R2, Secrets, D1, Cloudflare config (cf-config), Workers, Stream and Images. Binding sources (KV, R2, D1, Secrets) read through a Worker binding; the rest read through a single read-only discovery API token. A further union member, durable_object, is a declared placeholder that is not wired and cannot be selected. |
| Coverage | The view of what is and is not protected. With no inventory supplied, coverage shows unknown: it never renders green for a resource whose protection it cannot confirm. |
| Unknown (coverage) | The display state for a resource downpipes cannot confirm is protected. It shows as unknown, never as covered. |
| cf-config surfaces | The one registry of 313 Cloudflare config surfaces. Of these, 60 auto-restore in-band, 228 are backup-and-preview only and are re-applied out of band by an operator rather than blind-written to production, and 25 carry an off-by-default writer that a restore reaches only when the request names the surface. The named surfaces are bound into the plan hash, which an approver approves when restore dual control is on. A default restore therefore writes back 60 of them. |
| Restore tier (a different axis) | A separate classification of the same 313 surfaces by how they restore: idempotent (176), ordered (76) and reprovision (61). This tier axis is not the same as the in-band split, where 60 auto-restore. |
| Effective backup floor | The roughly fifteen-minute floor on how often a backup effectively runs on a schedule: the only scheduled dispatcher is the */15 reconciliation cron, so the floor is the cron interval, and the console floors the schedule picker at Hourly. A console Run now can start a single run between ticks on demand. |
The numbers matter here. The configuration registry is 313 surfaces with 60 auto-restoring in-band; the 176-76-61 split is the orthogonal restore-tier axis, not the in-band count. See the Cloudflare config surface reference and coverage.
Trust, licensing and the open-core boundary
These name the product’s trust and packaging model.
| Term | Definition |
|---|---|
| No-custody | The property that the vendor holds nothing: the engine runs entirely in the customer’s account, never sends data or a Cloudflare token to the vendor, and holds the signer and the public recipient keys. It holds a private recipient key only where the customer adds one: the optional operational key, or the config-recipient key that opens only the engine’s own configuration export. The vendor cannot read, verify or restore an archive. |
| Self-hosted | The deployment model: the engine and console run as Workers in the customer’s own Cloudflare account, reached on a custom domain, and customers run them themselves. |
| Open-core boundary | The line between the open-source MIT offline reader (the downpipe tool, the format specification and the conformance vectors) and the engine and console, which are source-available under the Elastic License 2.0 rather than MIT. Nothing in the format or the offline tool may require the vendor. |
| Fail-open licence | The licence behaviour: a bad, absent or expired licence yields tier community rather than blocking anything. The licence gates no product feature, and never the data path or the recovery path. |
| Compliance posture | downpipes holds no SOC 2 and no ISO 27001 (both demand-gated), and self-assesses against OWASP ASVS 5.0 at the Level 2 / Level 3-equivalent bar for its authentication component. No product makes you compliant; the compliance pages are mapping, not certification. |
The open-core boundary is what makes no-custody durable: recovery is delivered by a documented, open-source reader you can keep or re-implement, never by a vendor service. See the open-core boundary and compliance and evidence.
The offline reader and the Go CLI
These name the recovery tool and how to install it.
| Term | Definition |
|---|---|
downpipe (the offline tool) | The standalone, open-source MIT reader that verifies and restores archives from the destination bucket bytes plus the offline keys, with neither Cloudflare nor any vendor service in the loop. It is the Go reference reader the in-account TypeScript reader is built from, kept or rebuilt independently of the engine: a recoverer never needs the vendor’s software running to get their data back. |
| Install | The reader is built from source with Go 1.26 or newer. downpipes-io/downpipe is a public repository, so go install github.com/downpipes-io/downpipe/cmd/downpipe@latest resolves against the public module proxy and a plain git clone of the same path also works, with no account or engagement needed. For a real recovery, hold a copy in advance rather than fetching it during an incident: a break-glass recovery should not depend on the module proxy or GitHub being reachable at the time. From a copy you hold, go build -mod=vendor ./... builds against the dependencies checked into ./vendor with no module download, and with no network access at all provided the machine’s own Go already satisfies the toolchain go1.26.6 pin in go.mod. Confirm the binary with downpipe --help before relying on it. |
| Tool version versus format version | The tool’s reported version (an unstamped build reports dev) is distinct from the archive format string downpipe/0.1.0. A dev tool still reads and writes a downpipe/0.1.0 archive. |
| Discard sink | The offline reader’s restorability check: it decrypts and verifies every record through the full restore path and writes nothing, printing an attestation and a restore digest with no plaintext in any output. |
The caution is about the copy you hold, not about a version selector. go install ...@latest and a plain clone both resolve, but take your copy in advance and do not rely on either being reachable during a real recovery. Build it, then run downpipe --help and confirm prune, recombine and unseal-export are listed. See the CLI command reference and prove recoverability.
Audit and SIEM terms
These name the audit trail and how it is consumed.
| Term | Definition |
|---|---|
| Audit feed | The engine’s audit trail of admin actions. It carries operator identity (actor emails, source IP, role, approver emails and similar), so it is identity-bearing by design and contains personal data. It is tamper-evident through its hash chain. |
| Hash-chain | The construction that makes the audit log tamper-evident: each entry chains to the previous one, so an excision or an edit is detectable on verification. Entries beyond the fixed 10,000-entry cap roll off oldest-first, and the engine warns before the cap is reached. |
| Logpush push versus audit-feed pull | Two ways audit data leaves the engine that are easy to confuse. Logpush is a push the platform sends to a configured destination; the audit feed is a pull an operator or a SIEM reads from the engine. They are different directions and different surfaces. The engine can also push audit events itself to a configured SIEM push destination. |
Note that the audit feed carries operator identity, so it contains personal data. See the SIEM audit feed and the audit log.
Where this fits
These definitions are the vocabulary; the pages below are where each term does its work.
No-custody trust model
The trust property behind no-custody, self-hosted and the open-core boundary, in full.
Cryptography
The post-quantum hybrid construction, the master, the signer and the conformance vectors.
Recovery postures
The two-recipient posture and the break-glass-only posture, and what each means under compromise.
Security properties and limits
The limit on each security-bearing term, and what downpipes does not provide.
Last updated .