eggup-archive 0.2.0

Bounded allowlisted local archive extraction for Eggup (no transport, authenticity, or live-installation policy)
Documentation

eggup-archive

Optional local extraction for already verified tar.gz and zip files. Callers declare the exact archive members and output names, and provide finite entry, path, per-member, aggregate decompressed-byte, and archive-file bounds.

The extractor writes only declared regular files into one exclusive private directory. It uses exclusive file creation, never overwrites, hashes while streaming, checks expected size/digest facts when supplied, and empties its owned incomplete directory after failure. Dropping an unused extraction result best-effort empties it; persist() transfers cleanup responsibility (and the retained directory handle) to the caller.

Member materialization is authorized by the same retained directory handle, not by the recorded root pathname: tar and zip handlers share one ExtractionScope authority object and create each declared file with fs_at::OpenOptions (read + write + create-new + no-follow, 0600 on Unix) via open_at(root_handle, output_name). The returned member File carries read authority on the same object from creation, so no later step regains readability by reopening a name. It is the authoritative target for streaming, hashing, flushing, and validation. A root rename/replacement before or between member writes therefore cannot redirect bytes into a foreign directory, symlink, or reparse point.

Cleanup is authorized by a retained directory handle, not by a pathname check: the extraction root is created via mkdir_at from the parent handle (mode 0700 on Unix) and the returned File handle is carried through DirectoryGuard into PersistedExtraction. Recursive content deletion uses only fs_at handle-relative operations (read_dir, open_dir_at, unlink_at, rmdir_at); symlinks and reparse points are unlinked, never followed. No recursive operation traverses the replacement pathname, so a foreign directory, file, symlink, or reparse point installed after any handle operation cannot be recursively deleted. No object-bound root unlink exists on all supported platforms, so cleanup empties only the owned tree and never falls back to fs::remove_dir_all(path).

All four cleanup() entry points — ExtractedArchive::cleanup, PersistedExtraction::cleanup, BoundExtraction::cleanup, and DeferredCleanup::cleanup — share one contract:

  • Ok(()) means the owned root object held no entries at the final handle-relative listing: the owned tree was emptied.
  • Err(..) with kind() == ExtractionErrorKind::CleanupFailed means the owned root could not be fully emptied. The residue may be partially emptied and its emptiness is not guaranteed; residue_path() names the recorded root path.

The crate never removes the root directory itself, on any path, and offers no convenience that removes it by pathname. The residual empty directory is the caller's to remove: because cleanup() consumes the value, capture the residual path from root() before the cleanup call. The recorded root path is advisory — if the root was renamed or replaced by a third party, the crate emptied the owned object and left whatever occupies the recorded pathname untouched. Drop best-effort empties the same way and never falls back to fs::remove_dir_all(path).

ExtractedArchive and PersistedExtraction retain a std::fs::File handle and are therefore Send but not Sync. BoundMember, BoundExtraction, and DeferredCleanup own member/root handles the same way and are likewise move-only handle owners.

Handle-backed source handoff (Archive M001d): the recorded ExtractedMember::path() (root.join(output_name)) is advisory diagnostics only, never staging authority — after a root rename it may dangle into a foreign replacement while the bytes remain in the handle-owned directory. PersistedExtraction::into_bound_sources() converts each member into a BoundMember owning its already-open readable object (rewound to byte zero); BoundExtraction::into_members() splits staging sources from deferred DeferredCleanup. Staging through eggup-core BoundSources + InstallPlan::prepare_with_bound_sources reads each object from byte zero with no pathname or member-name lookup after the handoff boundary, so a member-entry replacement or root rename cannot redirect staged bytes, and the foreign replacement stays untouched. Member handles are single-owner and move-only: never clone a bound handle and assume an independent cursor. Supported order is stage, then close/consume handles, then handle-authorized cleanup. A failed bound stage copy never reopens the recorded path as fallback. Egress M006 and Eggpack M002 stay blocked until M001d closes with hosted qualification.

This crate performs no network access, authenticity policy, external process invocation, live installation mutation, metadata restoration, or service lifecycle work. Extracted files are inputs for a later caller-owned ArtifactSet; extraction does not provide destination ownership. Flushing makes completed files visible to later reads, but crash durability is not promised.

eggup-core remains independent of archive formats.