Glossary
This glossary defines the terms the rest of the docs lean on, so a claim reads the same way wherever it appears. Each definition is drawn from the code or the format specification rather than from marketing prose, and the security-bearing terms are worded with the care the master accuracy rules require. It is written for an evaluator who wants the precise meaning behind a word before trusting a page that uses it.
Where a term has a subtle distinction that matters (the break-glass key versus the break-glass token, tamper-evident versus a stronger claim downpipes does not make), the definition states the distinction plainly. 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, drawn from engine/src/admin/identity.ts and engine/README.md.
| 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 per-downpipe alarms, 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 precise 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. |
The maker not equal to checker rule is the one worth stating on its own. Authorisation keys on a stable, immutable subject (an identity provider’s verified subject, or the engine’s own credential principal), never on the mutable email, so a reassigned email can never inherit a departed member’s role. The email is retained for display and the audit trail only.
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 a printed recovery sheet, and never reaches the vendor or Cloudflare. 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 Access is in place. |
| 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, drawn from the format specification and engine/src/admin/identity.ts.
| 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 now consumes directly, but it still 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, drawn from downpipe/docs/format/SPEC.md.
| 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 (containers, manifests, 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 (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 containers 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. |
State this precisely, because it is easy to overclaim. In the two-recipient posture the engine holds a decryption-capable operational private key, so it can decrypt by default. 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 load-bearing security words, drawn from downpipe/docs/format/SPEC.md and engine/README.md. They are worded to the master accuracy rules.
| 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, which is why the term is “evident” and not a stronger claim. |
| Master | A per-downpipe 32-byte secret, freshly generated per run, 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. It is customer-generated and escrowed; 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 from the wording. First, post-quantum hybrid is the only correct phrasing; the design is not described as resistant in a stronger, unqualified sense. 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, drawn from downpipe/README.md, engine/src/admin/identity.ts and engine/README.md.
| 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 signed record the offline reader can emit after a verify or restore, stating what was proven (the signer it checked against, the records handled, the exit code). |
| 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. |
The honest framing is the thing to carry away. 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. See prove recoverability and reports.
Coverage and configuration terms
These describe what is protected and the configuration backup, drawn from engine/README.md and the surface registry.
| Term | Definition |
|---|---|
| Source type | One of the eight live, 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 honest view of what is and is not protected. Coverage shown from the portal is the honest-unknown state when no inventory has been supplied: it never renders green for a resource whose protection it cannot confirm. |
| Honest-unknown | The deliberate display state for a resource downpipes cannot confirm is protected. It is shown as unknown rather than as covered, because claiming coverage it cannot back would be the dishonest outcome. |
| cf-config surfaces | The one registry of 313 Cloudflare config surfaces. Of these, 60 auto-restore in-band and the remaining 253 are backup-and-preview only, re-applied out of band by an operator rather than blind-written to production. |
| 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 60 in-band versus 253 preview split. |
| 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, drawn from engine/README.md and downpipe/README.md.
| 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 only public recipient keys plus the signer. 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 assurance plane, which is 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 only assurance features, 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, audited 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 its honest install story, drawn from downpipe/README.md and downpipe/docs/format/CONFORMANCE.md.
| 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, and is the moat: a recoverer never needs the vendor’s software running to get their data back. |
| Install | go install github.com/downpipes/downpipe/cmd/downpipe@latest (Go 1.26 or newer, needs network access) resolves to the complete reader, currently tag v0.2.0. Confirm it with downpipe --help before relying on it, since a cached module resolution can still hand you an older binary. For no network access at all, clone the repository and run go build -mod=vendor ./... against the dependencies checked into ./vendor. A GitHub Release exists for v0.2.0 with signed binaries, but it is a maintainer-reviewed draft, not yet a public download. |
| 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 install caution is to verify, not to avoid @latest. go install .../downpipe@latest resolves to v0.2.0, which carries prune, recombine and unseal-export, and a tag-drift check now guards the tag in CI. Still run downpipe --help after installing and confirm the three commands are listed, since that check protects the tag, not an install you already made. See the CLI command reference and prove recoverability.
Audit and SIEM terms
These name the audit trail and how it is consumed, drawn from engine/README.md and engine/src/admin/identity.ts.
| 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 is never described as free of 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 configured cap roll off oldest-first, and the engine warns before the cap is reached. |
| Logpush push versus audit-feed pull | Two distinct ways audit data leaves the engine. 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 important honesty note is that the audit feed carries operator identity, so it is never characterised as carrying no 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.
Precise claims and honesty
The honest phrasings behind the security-bearing terms and why each is worded the way it is.
Last updated .