safe_unzip 0.1.3

Secure zip extraction. Prevents Zip Slip and Zip Bombs.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

mod error;
mod extractor;
mod limits;

// New architecture modules (v0.2)
pub mod adapter;
mod driver;
pub mod entry;
pub mod policy;

// Async API (requires `async` feature)
#[cfg(feature = "async")]
mod async_extractor;

/// Async extraction API.
///
/// This module provides async versions of the extraction functions. Requires the
/// `async` feature to be enabled.
///
/// ```toml
/// [dependencies]
/// safe_unzip = { version = "0.1", features = ["async"] }
/// ```
///
/// # Example
///
/// ```no_run
/// use safe_unzip::r#async::{extract_file, AsyncExtractor};
///
/// #[tokio::main]
/// async fn main() -> Result<(), safe_unzip::Error> {
///     // Simple extraction
///     let report = extract_file("/var/uploads", "archive.zip").await?;
///     
///     // With options
///     let report = AsyncExtractor::new("/var/uploads")?
///         .max_total_bytes(500 * 1024 * 1024)
///         .extract_file("archive.zip")
///         .await?;
///     
///     Ok(())
/// }
/// ```
#[cfg(feature = "async")]
pub mod r#async {
    pub use crate::async_extractor::*;
}

pub use error::Error;
pub use extractor::{EntryInfo, ExtractionMode, Extractor, OverwritePolicy, Report, SymlinkPolicy};
pub use limits::Limits;

// Re-export new types
pub use adapter::{TarAdapter, ZipAdapter};
pub use driver::{Driver, ExtractionReport, OverwriteMode, ValidationMode};
pub use entry::{Entry, EntryKind};
pub use policy::{Policy, PolicyChain, PolicyConfig, SymlinkBehavior};

/// Extract from a reader with default settings.
///
/// This is the "just works" convenience API. It creates the destination directory
/// if it doesn't exist. For more control, use [`Extractor`] directly.
///
/// # Destination Creation
///
/// Unlike [`Extractor::new`], this function creates the destination directory if
/// it doesn't exist. This is convenient but means typos like `/var/uplaods` will
/// silently create a wrong directory. For user-facing code where you want to catch
/// such errors, use [`Extractor::new`] instead.
///
/// # Seekable Reader Required
///
/// The reader must implement [`std::io::Seek`] because zip files store the central
/// directory at the end. For non-seekable streams, buffer into a [`std::io::Cursor`] first.
///
/// # Example
///
/// ```no_run
/// use std::io::Cursor;
/// use safe_unzip::extract;
///
/// let zip_bytes = std::fs::read("archive.zip")?;
/// let report = extract("/var/uploads", Cursor::new(zip_bytes))?;
/// # Ok::<(), safe_unzip::Error>(())
/// ```
pub fn extract<P, R>(destination: P, reader: R) -> Result<Report, Error>
where
    P: AsRef<std::path::Path>,
    R: std::io::Read + std::io::Seek,
{
    Extractor::new_or_create(destination)?.extract(reader)
}

/// Extract from a file path with default settings.
///
/// This is the "just works" convenience API. It creates the destination directory
/// if it doesn't exist. For more control, use [`Extractor`] directly.
///
/// # Destination Creation
///
/// Unlike [`Extractor::new`], this function creates the destination directory if
/// it doesn't exist. This is convenient but means typos like `/var/uplaods` will
/// silently create a wrong directory. For user-facing code where you want to catch
/// such errors, use [`Extractor::new`] instead.
///
/// # Example
///
/// ```no_run
/// use safe_unzip::extract_file;
///
/// let report = extract_file("/var/uploads", "archive.zip")?;
/// println!("Extracted {} files", report.files_extracted);
/// # Ok::<(), safe_unzip::Error>(())
/// ```
pub fn extract_file<P, F>(destination: P, file_path: F) -> Result<Report, Error>
where
    P: AsRef<std::path::Path>,
    F: AsRef<std::path::Path>,
{
    let file = std::fs::File::open(file_path)?;
    let reader = std::io::BufReader::new(file);
    Extractor::new_or_create(destination)?.extract(reader)
}