exarch_core/
lib.rs

1//! Memory-safe archive extraction library with security validation.
2//!
3//! `exarch-core` provides a safe API for extracting archive files (tar, zip)
4//! with built-in protection against common security vulnerabilities like
5//! path traversal, zip bombs, symlink attacks, and hardlink attacks.
6//!
7//! # Examples
8//!
9//! ```no_run
10//! use exarch_core::SecurityConfig;
11//! use exarch_core::extract_archive;
12//!
13//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
14//! let config = SecurityConfig::default();
15//! let report = extract_archive("archive.tar.gz", "/output/dir", &config)?;
16//! println!("Extracted {} files", report.files_extracted);
17//! # Ok(())
18//! # }
19//! ```
20
21#![deny(unsafe_code)]
22#![warn(missing_docs)]
23
24pub mod api;
25pub mod archive;
26pub(crate) mod closed_enum;
27pub mod config;
28pub(crate) mod copy;
29pub mod creation;
30pub mod error;
31pub mod formats;
32pub mod inspection;
33#[cfg(test)]
34use exarch_testkit::raw_zip;
35pub mod report;
36pub mod security;
37#[cfg(test)]
38pub(crate) mod test_utils;
39pub mod types;
40
41// Re-export main API types
42pub use api::create_archive;
43pub use api::create_archive_with_progress;
44pub use api::extract_archive;
45pub use api::extract_archive_with_options;
46pub use api::extract_archive_with_options_and_progress;
47pub use api::extract_archive_with_progress;
48pub use api::list_archive;
49pub use api::list_archive_with_options;
50pub use api::verify_archive;
51pub use api::verify_archive_with_options;
52pub use archive::Archive;
53pub use archive::ArchiveBuilder;
54pub use config::DecompressionBudget;
55pub use config::ExtractionOptions;
56pub use config::IntegrityCheck;
57pub use config::ListOptions;
58pub use config::ParallelDecode;
59pub use config::SecurityConfig;
60pub use config::StoredTargets;
61pub use config::Unvalidated;
62pub use config::Validated;
63pub use config::VerificationOptions;
64pub use config::ZipConsistencyPolicy;
65pub use error::ArchiveError;
66pub use error::CentralRecordOrdinal;
67pub use error::CompressionRatio;
68pub use error::EndRecordKind;
69pub use error::FfiErrorMessage;
70pub use error::HiddenRegion;
71pub use error::IoContext;
72pub use error::PartialWrites;
73pub use error::PolicySetting;
74pub use error::QuotaResource;
75pub use error::Result;
76pub use error::ZipBombDetails;
77pub use error::ZipBombScope;
78pub use error::ZipEntryIndex;
79pub use error::ZipHeaderField;
80pub use error::ZipInconsistency;
81pub use error::ZipUncomparable;
82/// Formats an archive-relative, attacker-authored path for an FFI error
83/// message without redaction. Shared by `exarch-python` and `exarch-node`.
84pub use error::redaction::format_entry_path_for_error;
85/// Sanitizes a `std::io::Error` message for an FFI error message. Shared by
86/// `exarch-python` and `exarch-node`.
87pub use error::redaction::sanitize_io_error_for_error;
88/// Redacts a host-derived filesystem path for an FFI error message in
89/// release builds. Shared by `exarch-python` and `exarch-node`.
90pub use error::redaction::sanitize_path_for_error;
91pub use report::ExtractionReport;
92pub use report::NoopProgress;
93pub use report::ProgressCallback;
94
95// Re-export creation types
96pub use creation::ArchiveCreator;
97pub use creation::CreationConfig;
98pub use creation::CreationReport;
99pub use formats::traits::FormatCreator;
100
101// Re-export inspection types
102pub use inspection::ArchiveEntry;
103pub use inspection::ArchiveManifest;
104pub use inspection::CheckStatus;
105pub use inspection::EntryCompression;
106pub use inspection::IntegrityGaps;
107pub use inspection::IntegrityStatus;
108pub use inspection::IssueCategory;
109pub use inspection::IssueSeverity;
110pub use inspection::LinkTarget;
111pub use inspection::ManifestEntryKind;
112pub use inspection::ManifestEntryType;
113pub use inspection::OversizedEntry;
114pub use inspection::SolidBlock;
115pub use inspection::UnverifiedEntry;
116pub use inspection::UnverifiedReason;
117pub use inspection::VerificationIssue;
118pub use inspection::VerificationReport;
119pub use inspection::VerificationStatus;
120pub use security::fs_view::LinkKind;
121
122// Re-export security types
123/// Summary statistics produced by the validation pipeline; see
124/// [`security::ValidationReport`].
125pub use security::ValidationReport;
126/// Maximum length, in bytes, of a single `SecurityConfig` entry — an
127/// allowed extension or a banned path component. Shared by `exarch-python`
128/// and `exarch-node`.
129pub use security::boundary::MAX_CONFIG_ENTRY_LENGTH;
130/// Maximum length, in bytes, of a raw path string accepted at the FFI
131/// boundary. Shared by `exarch-python` and `exarch-node`.
132pub use security::boundary::MAX_PATH_LENGTH;
133/// Validates a single caller-supplied `SecurityConfig` entry string.
134/// Shared by `exarch-python` and `exarch-node`.
135pub use security::boundary::validate_config_entry;
136/// Validates a raw, caller-supplied path string before it enters the
137/// archive pipeline. Shared by `exarch-python` and `exarch-node`.
138pub use security::boundary::validate_raw_path_str;
139
140// Re-export types module for easier access
141pub use types::DestDir;
142pub use types::EntryType;
143pub use types::SafePath;
144pub use types::SafeSymlink;
exarch_core/lib.rs

exarch_core/
lib.rs
