Module backup_bundle_store 

Fjall-backed storage for in-flight backup bundles.

See docs/05-design-notes/backup-descriptor-pattern.md for the full state machine. Brief recap: every initiate-export / initiate-import mints a BundleRecord, the bytes live separately on disk under ${data_dir}/backups/{bundle_id}.vtabak, and a background sweeper transitions expired records to Expired (terminal) and deletes the on-disk bytes.

Tokens are stored as SHA-256(token_b64) so a leaked database does not yield usable bearer credentials. Validation in the blob endpoint uses constant-time comparison via subtle::ConstantTimeEq.

Structs

BundleRecord

Persistent record for an in-flight backup bundle. The token_hash is SHA-256(token_b64_url) — the plaintext token is returned to the client exactly once at mint time and never stored.

BundleToken

Plaintext token returned to the client at descriptor mint time. Zeroized on drop so it doesn’t linger in memory after the descriptor is built.

Enums

BundleKind

Bundle kind — export bytes flow VTA → operator, import bytes flow operator → VTA. Encoded on the record so the same keyspace can hold both directions without separate prefixes.

BundleState

Per-bundle state machine. Transitions are recorded in docs/05-design-notes/backup-descriptor-pattern.md §“State machine”.

Functions

delete_bundle

Remove a bundle record. Called by the sweeper after a terminal state ages out of the 24h audit retention window.

get_bundle

Fetch a bundle record by id.

hash_token

Hash a bearer token to the form persisted in BundleRecord::token_hash. Plain SHA-256 over the UTF-8 bytes of the base64url-encoded token. Used both at mint time and at validation time so the two values are guaranteed to be derived the same way.

list_bundles

Enumerate every persisted bundle. The sweeper iterates this to find candidates for TTL expiry and post-terminal cleanup. Operator audit tooling can also consult it to inspect open transfers.

mint_token

Mint a fresh bearer token for a new bundle.

store_bundle

Insert or replace a bundle record. Called at every state transition (mint, blob-endpoint hit, finalize, sweeper expiry).

verify_token

Constant-time check that the caller-supplied X-Backup-Token matches a stored hash. Returns true on match. Returns false without revealing where the mismatch is (no early return on a per-byte loop).