Struct BinaryCache 

pub struct BinaryCache { /* private fields */ }

On-disk cache for downloaded, signature-verified upgrade archives.

Implementations

impl BinaryCache

pub fn new(cache_dir: PathBuf) -> Self

Create a new binary cache backed by the given directory.

Production constructor: the cache verifies cached archives against the pinned release public key embedded in the binary.

pub fn cached_archive_path(&self, version: &str) -> PathBuf

Path of the cached archive for version.

pub fn get_verified_archive( &self, version: &str, private_dir: &Path, ) -> Option<PathBuf>

Copy the cached archive into the caller-private private_dir, cryptographically re-verify that private copy, and return its path — or None if there is no usable, trusted cache entry.

On every call this:

1. loads the sibling metadata and checks the version matches,
2. copies the cached archive + signature into private_dir (a location only this process writes, e.g. the per-upgrade temp dir),
3. SHA-256 pre-checks the private copy against the metadata (fast corruption check), then
4. re-verifies the ML-DSA-65 signature over the private copy with the pinned release key — the actual security gate.

Verifying the private copy (not the shared cache file) closes the TOCTOU window: an attacker with write access to the shared cache dir cannot swap the bytes between verification and extraction, because the caller extracts from the returned private path, which is the exact byte sequence that was verified and is unreachable to the attacker.

Any failure (missing/corrupt metadata, copy error, hash mismatch, missing signature, or — critically — a signature that does not verify against the pinned release key) returns None, forcing a fresh, fully verified download.

The caller MUST extract the binary from the returned (private) archive path, so the executed bytes always derive from signature-verified input that no other principal could have modified post-verification.

private_dir is a load-bearing security invariant: it MUST be a process-private, mode-0o700 directory that no other principal can write to. The caller in apply.rs creates it via tempfile::Builder::permissions(0o700).tempdir_in(binary_dir) — any future caller MUST uphold the same invariant, otherwise the reopens by path in sha256_file and verify_archive would re- introduce a TOCTOU window.

pub fn store_archive( &self, version: &str, archive_path: &Path, signature_path: &Path, ) -> Result<()>

Store a signature-verified archive in the cache.

Both files are persisted (via write-to-temp-then-rename so readers never observe partial writes); the metadata file is written last so get_verified_archive only succeeds once every file is complete.

Defence in depth: this re-verifies the archive against its signature before caching, so a poisoned entry cannot be created through the supported path even if a caller forgot to verify first.

Errors

Returns an error if the signature does not verify, the inputs cannot be read, or the cache files cannot be written.

pub fn acquire_download_lock(&self) -> Result<DownloadLockGuard>

Acquire an exclusive download lock and return the guard.

This prevents multiple nodes from downloading the same archive concurrently — the first acquires the lock and downloads, the rest wait and then find the archive already cached.

The lock is released when the returned guard is dropped.

Note: lock_exclusive() blocks the calling thread. Callers in async contexts should wrap this call in tokio::task::spawn_blocking.

Errors

Returns an error if the lock file cannot be created or acquired.

Trait Implementations

impl Clone for BinaryCache

fn clone(&self) -> BinaryCache

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.