Crate exarch_core

Expand description

Memory-safe archive extraction library with security validation.

exarch-core provides a safe API for extracting archive files (tar, zip) with built-in protection against common security vulnerabilities like path traversal, zip bombs, symlink attacks, and hardlink attacks.

§Examples

use exarch_core::SecurityConfig;
use exarch_core::extract_archive;

let config = SecurityConfig::default();
let report = extract_archive("archive.tar.gz", "/output/dir", &config)?;
println!("Extracted {} files", report.files_extracted);

Macros§

non_zero: Builds a NonZero value from a constant, failing the build when the constant is zero.
ratio_limit: Builds a RatioLimit from a constant, failing the build when it is not finite and positive.

Structs§

AdmittedSize: The size of a file the pipeline admitted: the bytes a QuotaPermit reserved for it.
AllowedFeatures: Feature flags controlling what archive features are allowed during extraction.
ArchiveEntry: Single entry in archive manifest.
ArchiveManifest: Complete manifest of archive contents.
ArchiveReader: An archive supplied as a reader.
ArchiveWriter: An archive destination supplied as a writer.
BoundaryPath: Validates a raw, caller-supplied path string before it enters the archive pipeline. Shared by exarch-python and exarch-node. A caller-supplied path string that passed the boundary checks.
CallbackSink: An EntrySink that delivers each entry to a closure as it is verified.
CentralRecordOrdinal: Position of a record in the raw central directory, counting records that the zip crate collapsed because they share a name.
CheckedLinkTarget: The target of a symlink that passed validation, borrowed from its SafeSymlink.
Compressed: A byte count as stored in the archive.
CompressionLevel: A compression level on exarch’s 1-9 scale; the default is 6.
CreateRequest: Creates an archive from files and directories.
CreationConfig: Configuration for archive creation operations.
CreationReport: Report of an archive creation operation.
DecompressionBudget: Upper bound on the bytes verify decodes to check payload integrity.
DestDir: A validated destination directory for archive extraction.
EntryCount: Proof that one entry was counted against max_file_count while its bytes are not yet charged.
EntryPattern: A glob pattern that selects archive entries, built once when the pattern is set.
EntryPosition: Where an entry sits in the operation: its 1-based number and the total.
EntrySelection: The entries of an archive an extraction takes, and how their paths are rewritten.
EntrySize: The declared sizes of one entry, as the validators consume them.
Extension: A file extension without its leading dot, ASCII-lowercased.
Extensions: A non-empty list of allowed Extensions.
ExtractRequest: Extracts an archive into a directory.
ExtractionOptions: Options controlling extraction behavior (non-security).
ExtractionReport: Report of an archive extraction operation.
FfiErrorMessage: Error data for FFI consumption.
FfiNameCollision: Two entry names the host filesystem treats as one, redacted for a binding.
FfiSourceFault: What a binding needs of an unreadable creation source, redacted like the rest of the message.
HardlinkTarget: A hardlink target that passed HardlinkTracker validation.
IntegrityGaps: What a requested integrity check left unverified.
IoContext: Pairs a static, non-path-bearing summary with the dynamic detail of an I/O failure constructed via std::io::Error::other.
Landing: A path extraction creates, with what put it there.
LandingPath: The destination-relative path an entry lands at, derived lexically.
ListOptions: Options controlling list behavior.
ListRequest: Lists the contents of an archive without extracting it.
ListedArchive: An archive that was listed and is ready to extract without decoding it again where that is possible.
ListedExtractOptions: The options of ListedArchive::extract: the knobs that may still vary after the archive was listed.
MemoryExtractRequest: How extract_reader_to_memory validates and stores an archive.
MemoryFile: The writer of a file being stored by a MemorySink.
MemoryLimit: The most bytes a MemorySink accepts, counted as its payload (file data, hardlink copies, symlink targets) plus, for every entry, the bytes of its path and MemorySink::ENTRY_OVERHEAD.
MemorySink: An EntrySink that keeps the extracted tree in memory.
NoopProgress: No-op implementation of ProgressCallback that does nothing.
OutputFile: The archive file a creation writes: its path, whether it may replace an existing file and how its format is chosen.
OversizedEntry: An entry whose path exceeds the host’s name limits.
Partial: An extraction that stopped after recording progress, or that left its staging directory behind.
PathComponentName: One normal path component that archive entries may not contain.
QuotaPermit: Proof that a file’s size was successfully reserved against a QuotaTracker.
RatioLimit: A compression ratio limit: finite and greater than zero.
RawMode: A Unix permission mode exactly as an archive header records it.
ReplaceFailure: Why replacing an existing destination failed, and what is left behind.
ReuseLimit: The most decoded bytes a ZIP extraction keeps for reuse.
SafePath: A validated path that is safe for extraction.
SafeSymlink: A validated symlink that is safe for extraction.
SanitizedMode: A Unix permission mode that has already passed through sanitize_permissions.
SecurityConfig: Security configuration with default-deny settings.
SinkExtractRequest: Extracts an archive read from a reader into an EntrySink.
SinkFull: The payload of the io::ErrorKind::QuotaExceeded error a sink returns when it has no room for an entry.
SinkOptions: What a sink extraction honours of ExtractionOptions.
Skip: One entry left out of an operation, with the reason.
Skips: Everything an operation left out: exact counts per SkipKind plus a bounded sample of the individual entries.
SolidBlock: Compressed and uncompressed totals of one solid block.
SolidLimits: Limits applied to a solid 7z archive that is admitted.
StagingLeftover: A staging directory that a failed replace left on disk.
StagingPlace: Where the staging entries of one output live, and the path a backup is renamed back to.
StripComponents: How many leading path components extraction drops from every entry.
Unclassified: A malformed-archive refusal that has no family of its own.
Uncompressed: A byte count after decoding.
UnixTime: A point in time as an offset from the Unix epoch, which may be negative.
UnverifiedEntry: One entry the integrity check could not verify, and why.
VerificationIssue: Single verification issue.
VerificationOptions: Options controlling verify behavior.
VerificationReport: Result of archive verification.
VerifyRequest: Verifies an archive’s security without extracting it.
ZipBombDetails: Sizes and scope of a rejected compression ratio.
ZipEntryIndex: Index of an entry in the zip crate’s entry map, which equals its position in the manifest listing.

Enums§

Admit: Whether an archive feature is admitted.
ArchiveError: Errors that can occur during archive operations (extraction, creation, listing, verification).
ArchiveType: Supported archive formats.
BackupIdentity: Whether the identity of a leftover backup was confirmed before its removal failed.
CallbackEntry: An entry delivered by a CallbackSink.
CallbackError: Why extract_reader_to_callback failed.
CheckStatus: Status of a specific check category.
CompressionCodec: Compression codec for archive files.
CompressionRatio: Compression ratio of a checked size pair.
ConfigProblem: Why a configuration value or input was refused.
ConfigSetting: A configuration value or required input that was refused.
CreatableFormat: Archive formats exarch can create.
CreationWarning: A condition of a creation worth surfacing that is not a skipped entry.
CreationWarningKind: The class of a CreationWarning, without its payload.
DecodeReuse: Where a ZIP extraction keeps decoded output between the structural check and the write, so a deflate entry is decoded once.
DecodeReuseKind: The mode of a DecodeReuse without its limit, as the front ends spell it.
DestinationCheck: What ListedArchive::check_destination requires of the paths the extraction would write.
DestinationState: Whether a destination is fresh: nothing exists at its final name and the directory that would hold it exists.
DestinationStep: The step of reaching a destination that failed.
Disposition: What extraction does with a listed entry.
DispositionKind: Which way a Disposition went, without its payload.
Durability: Whether a created archive is flushed to stable storage before it is reported as written.
EndRecordKind: Kind of end record found before an entry.
EntryCompression: How an archive entry’s data is compressed.
EntryTotal: How many entries an operation has, when it knows.
ErrorCode: Stable machine-readable identifier of an ArchiveError variant.
ExistingFiles: What extraction does with a destination path that is already occupied.
ExtensionFilter: Which file extensions extraction admits.
ExtractOnlyFormat: Archive formats exarch can read but not create.
ExtractionWarning: A condition of an extraction worth surfacing that is not a skipped entry.
ExtractionWarningKind: The class of an ExtractionWarning, without its payload.
FfiDetail: Structured data behind an FfiErrorMessage, one variant per error that carries some.
FfiKind: The error class of an FfiErrorMessage, with the payload that class carries.
FfiRestore: What became of the original destination after a failed replace, redacted for a binding.
Finding: What a VerificationIssue found.
Heuristic: An observation verify reports on its own, not as a refusal.
HiddenRegion: Part of a ZIP file in which an unmapped local header was found.
IntegrityCheck: Whether verify checks payload integrity.
IntegrityStatus: Result of the payload integrity check.
InvalidArchiveSubCode: Finer classification of an ErrorCode::InvalidArchive error.
IoKind: The kind of an I/O failure, spelled the same in every front end.
IssueCategory: Issue categories (maps to security checks).
IssueSeverity: Issue severity levels (ordered from least to most severe for Ord).
KindSource: Where a claim about a 7z entry’s kind was recorded.
LandingKind: What put a path in the landing set.
Limit: A positive bound, or no bound.
LinkKind: The kind of link a target belongs to; the host limits them differently.
LinkTarget: Link target of a manifest entry, as far as the listing could keep it.
LinkTargetState: What a LinkTarget holds, without the target itself.
Malformation: Why an archive, or one of its entries, is malformed.
ManifestEntryKind: Kind of a manifest entry; link kinds carry their target.
ManifestEntryType: Entry type in manifest (does NOT require validation).
MarkOutcome: What mark propagation did during one extraction.
MarkPropagation: Whether extraction copies the archive file’s download-origin mark onto the files it creates.
MarkState: The kind of a MarkOutcome, without its counts.
MemoryEntry: An entry held by a MemorySink.
MemoryEntryKind: What a MemoryEntry or a CallbackEntry holds.
NameCollisionKind: How two colliding names differ, which sets how serious the collision is.
NarrowingReason: Why the root of an atomic publication gives less access than the destination it replaces or fills.
NativeKind: What a 7z header itself says an entry is: a directory has no stream and is not flagged as an empty file.
OccupiedBy: Who made the entry that occupies a path a run was about to write.
OutputFormat: How the archive format of an OutputFile is chosen.
OutputPolicy: Whether creating an output file may replace one that already exists.
ParallelDecode: How much extra memory a 7z block may use to decode LZMA2 runs ahead on worker threads.
PartialOutcome: What happened to the output of an extraction that stopped part-way.
PartialWrites: Fate of the files recorded in a ArchiveError::PartialExtraction report.
PathModel: The path semantics an EntrySink is validated against.
PathOccupant: What already occupies a path an insert collided with.
PathRewrite: How a validated archive path becomes the path an entry lands at.
PatternRefusal: Why a glob entry pattern is refused.
PermissionPolicy: Whether file modes from the archive (or the source tree) are kept.
PolicySetting: The SecurityConfig setting whose current value refused an entry.
PortableHazard: Why a path component is hazardous on some supported platform but not necessarily on the host.
ProtectedPath: What makes a destination too important to replace as a whole.
QuotaKind: Payload-free discriminant of a QuotaResource.
QuotaResource: Represents a specific quota resource that was exceeded.
ReaderFormatError: Why the format of an archive supplied as a reader could not be used.
RequestedLevel: A compression level exactly as the caller asked for it.
Restore: What became of the original destination after a failed replace.
RestoreKind: The outcome of Restore without its payload.
SecurityViolationSubCode: Finer classification of an ErrorCode::SecurityViolation error.
SeekableFormat: A format that is read through a directory at the end of the archive, and so needs a seekable source.
SevenZHeaderTable: A table of a 7z header whose declared length is bounded before the header is parsed.
SkipKind: Why an entry was left out of an extraction or creation.
SolidArchives: Whether solid 7z archives are extracted, and under which limits.
SolidMemoryScope: What a refused solid decoded size was summed over.
SpecialFile: A Unix file type that exarch never creates.
StagedOutputKind: What a staged output is, which fixes how its destination is resolved.
Staging: How extraction stages its output before it is visible at the destination.
StoredTargets: Whether listing reads the symlink targets a format keeps in compressed entry data.
SubCode: The finer classification of an error, tagged with the class it refines.
TarAmbiguity: A TAR header or extension-header construct that readers such as bsdtar and Python tarfile resolve differently from the tar crate.
TarExtensionKind: An extension header whose body the tar crate merges into the next entry.
TarHeaderField: A numeric header field that must be plain.
TarNonRegularKind: A TAR entry type that has no data and must not declare a payload.
TarPathKey: The path-like PAX key that a GNU long record duplicates.
TarTrailerRefusal: Why the bytes after the end-of-archive marker of a compressed TAR were refused.
TrailerCorruption: What is wrong with the compressed stream after the TAR end-of-archive marker.
UnverifiedReason: Why part of the payload was not verified by the integrity check.
VerificationStatus: Overall verification status.
Violation: Why an operation was denied by security policy.
VolumeIdentity: How the destination volume tells two landings apart, which decides which repeated names extraction skips as duplicates.
ZipBombScope: What a zip bomb size check was measured over.
ZipConsistencyPolicy: How ZIP structure that different readers interpret differently is handled.
ZipHeaderField: Header field in which a ZIP local header disagrees with its central directory record.
ZipInconsistency: A structural finding that makes a ZIP archive ambiguous between readers.
ZipNonRegularKind: Kind of entry that is not a regular file but declares a payload.
ZipStreamUndecided: Why the end of an entry’s compressed stream could not be established.
ZipUncomparable: Why a ZIP local header could not be compared with its central directory record.

Constants§

BACKUP_PREFIX: The name prefix of the backup an atomic replace renames the previous destination to; it extends STAGING_PREFIX.
MAX_CONFIG_ENTRY_LENGTH: Maximum length, in bytes, of a single SecurityConfig entry — an allowed extension or a banned path component. Shared by exarch-python and exarch-node. Maximum length, in bytes, of a single SecurityConfig entry — an allowed extension or a banned path component.
MAX_PATH_LENGTH: Maximum length, in bytes, of a raw path string accepted at the FFI boundary. Shared by exarch-python and exarch-node. Maximum length, in bytes, of a raw path string accepted at the FFI boundary.
STAGING_PREFIX: The name prefix of every staging entry (a staging directory, or the temporary file of a staged archive) created next to a destination.

Traits§

ClosedEnum: An enum with a fixed set of variants and a stable string form for each.
EntrySink: Receives the validated entries of an archive in extraction order.
ProgressCallback: Callback trait for progress reporting during archive operations.

Functions§

bytes_text: Renders raw bytes of an archive name as text, by the rules of path_text.
create_archive: Creates an archive from source files and directories.
detect_format: Detects the archive type from a file path using two-phase detection.
extract_archive: Extracts an archive to the specified output directory.
extract_reader_to_callback: Extracts the archive in reader, handing every verified entry to on_entry.
extract_reader_to_memory: Extracts the archive in reader into a MemorySink.
format_entry_path_for_error: Formats an archive-relative, attacker-authored path for an FFI error message without redaction. Shared by exarch-python and exarch-node. Formats an archive-relative, attacker-authored path for inclusion in an FFI error message.
list_archive: Lists archive contents without extracting.
non_zero_u64: Parses a runtime byte count, refusing zero.
non_zero_usize: Parses a runtime count, refusing zero.
path_text: Renders a path as text so that two distinct paths never render alike.
positive_from_f64: Parses a floating-point number from a binding (a JavaScript number) into a positive whole count of at most 2^53 - 1.
positive_from_i128: Parses a signed integer from a binding, refusing zero, negative values and values above u64::MAX.
sanitize_io_error_for_error: Sanitizes a std::io::Error message for an FFI error message. Shared by exarch-python and exarch-node. Sanitizes I/O error messages for FFI error reporting.
sanitize_path_for_error: Redacts a host-derived filesystem path for an FFI error message in release builds. Shared by exarch-python and exarch-node. Formats a host-derived filesystem path for inclusion in an FFI error message.
staging_place: Resolves where the staging entries of output are created, by the rule the staging code of kind uses.
utf8_entry_path: The text of an archive entry path, or the refusal a front end must raise.
verify_archive: Verifies archive security without extracting.

Type Aliases§

Result: Result type alias using ArchiveError.

Crate exarch_core

Crate exarch_core Copy item path

§Examples

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Crate exarch_core