exarch-core

Memory-safe archive extraction and creation library with security validation.

This crate is part of the exarch workspace.

Installation

[dependencies]
exarch-core = "0.2"

[!IMPORTANT] Requires Rust 1.89.0 or later (Edition 2024).

Usage

use exarch_core::{extract_archive, SecurityConfig};

fn main() -> Result<(), exarch_core::ExtractionError> {
    let config = SecurityConfig::default();
    let report = extract_archive("archive.tar.gz", "/output/dir", &config)?;

    println!("Extracted {} files ({} bytes)",
        report.files_extracted,
        report.bytes_written);
    Ok(())
}

Custom Security Configuration

use exarch_core::SecurityConfig;

let config = SecurityConfig {
    max_file_size: 100 * 1024 * 1024,    // 100 MB per file
    max_total_size: 1024 * 1024 * 1024,  // 1 GB total
    max_file_count: 10_000,               // Max 10k files
    max_compression_ratio: 50.0,          // 50x compression limit
    ..Default::default()
};

Builder Pattern

use exarch_core::ArchiveBuilder;

let mut archive = ArchiveBuilder::new()
    .max_file_size(50 * 1024 * 1024)
    .max_compression_ratio(100.0)
    .open("archive.tar.gz")?;

let report = archive.extract("/output/path")?;

Security Features

exarch-core provides defense-in-depth protection against common archive vulnerabilities:

[!CAUTION] Default configuration blocks symlinks and hardlinks. Enable only when you trust the archive source.

Archive Creation

Create archives with secure defaults:

use exarch_core::{create_archive, CreationConfig};

// Simple creation with defaults
let config = CreationConfig::default();
let report = create_archive("backup.tar.gz", &["src/", "Cargo.toml"], &config)?;
println!("Created {} files", report.files_added);

Builder Pattern

use exarch_core::ArchiveCreator;

let report = ArchiveCreator::new()
    .output("project.tar.gz")
    .add_source("src/")
    .add_source("Cargo.toml")
    .add_source("README.md")
    .compression_level(9)
    .exclude("*.log")
    .exclude("target/")
    .create()?;

CreationConfig Options

Supported Formats

[!NOTE] 7z creation is not yet supported. Solid and encrypted 7z archives are rejected for security reasons.

API Overview

Main Types

Error Handling

use exarch_core::{extract_archive, ExtractionError, SecurityConfig};

match extract_archive("archive.tar.gz", "/output", &SecurityConfig::default()) {
    Ok(report) => println!("Extracted {} files", report.files_extracted),
    Err(ExtractionError::PathTraversal { path, .. }) => {
        eprintln!("Blocked path traversal: {}", path.display());
    }
    Err(ExtractionError::QuotaExceeded { resource }) => {
        eprintln!("Resource limit exceeded: {:?}", resource);
    }
    Err(e) => eprintln!("Extraction failed: {}", e),
}

Performance

Optimized for throughput with:

• Directory caching — FxHashSet caching reduces mkdir syscalls by ~95%
• Atomic permission setting — Sets Unix permissions during file creation (1 syscall vs 2)
• Streaming extraction (no full archive buffering)
• Reusable 64KB copy buffers per archive
• Buffered I/O for file writes
• SmallVec for hardlink tracking (avoids heap allocation for typical archives)
• Fast-path quota checks for unlimited quotas

Throughput targets:

• TAR extraction: 2,136 MB/s (target: 500 MB/s)
• ZIP extraction: 1,444 MB/s (target: 300 MB/s)

Related Crates

• exarch-python — Python bindings via PyO3
• exarch-node — Node.js bindings via napi-rs

MSRV Policy

[!NOTE] Minimum Supported Rust Version: 1.89.0. MSRV increases are minor version bumps.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.