Module descriptors 

Op-layer for the backup-descriptor pattern (spec/vta/backup/*).

Five functions, one per trust-task URI. Each one:

1. Verifies super-admin auth.
2. (For non-initiate-* ops) verifies the caller-DID matches BundleRecord.created_by — without this a second super-admin could complete or abort the first’s in-flight backup.
3. Reads / mutates the BundleRecord in backup_bundles_ks.
4. For export: writes the staged .vtabak bytes to disk under backup_blob_dir. For import: reads them back at finalize.
5. Delegates the actual encrypt/decrypt to the existing export_backup / preview_import / apply_import helpers in the parent module.

See docs/05-design-notes/backup-descriptor-pattern.md for the full state machine and rationale.

Structs

DescriptorDeps

Borrowed deps for the descriptor ops. Avoids dragging the full AppState into the op layer (it’s a server-runtime type) while keeping the call surface tractable.

Constants

DEFAULT_BUNDLE_TTL_SECS

Default bundle TTL — 5 minutes per the design doc. Operators can override via the (future) VTA_BACKUP_BUNDLE_TTL_SECS env var; cap at 1 hour to prevent operator footguns.

MAX_BUNDLE_TTL_SECS

Hard ceiling on bundle TTL. 1 hour. A descriptor sitting around for hours invites token-replay attacks once the operator has closed their session.

MAX_OPEN_BUNDLES_PER_DID

Per-DID cap on simultaneously-open (non-terminal) bundles. Prevents one operator from tying up disk by spamming initiate-* without ever finalizing. v1: 3. Future: config-driven.

Functions

abort_bundle

Cancel an in-flight bundle in any non-terminal state. Idempotent on terminal — returns aborted: false instead of erroring so re-tries from the operator are safe.

complete_export

Optional ack from the client after a successful download. Idempotent on terminal states (returns downloaded reflecting whether the transfer actually happened).

finalize_import

Apply (or preview) the uploaded bytes for an import bundle. The state machine allows multiple preview calls but exactly one commit (the second commit attempt finds the bundle in ImportCommitted, which is terminal).

initiate_export

Stage the bytes for an export bundle and return the descriptor. Caller path: spec/vta/backup/initiate-export/1.0 trust-task handler.

initiate_import

Mint an upload slot for an import bundle. Returns the descriptor the client uses to POST bytes to the blob endpoint. Bytes aren’t validated until the subsequent finalize-import (since the upload happens out-of-band).