feat: expose ArchiveIteratorBuilder::mtree_format opt-out

libarchive's mtree format handler is permissive — it matches free-form text such as a
plain gunzip'd text file and yields bogus entries for input that isn't really an mtree
specification. The default behavior preserves libarchive's output (including on the raw
entry points), but strict callers iterating with ArchiveIterator may want to reject the
match instead of acting on the invalid entries.

- Add ArchiveIteratorBuilder::mtree_format(bool); default true preserves libarchive's
  permissive behavior, false rejects entries whose archive_format base mask indicates
  ARCHIVE_FORMAT_MTREE
- Gate the rejection inside ArchiveIterator::unsafe_next_header on the new flag,
  delegating to a module-private reject_mtree_format helper only when the caller opted
  out
- Expose archive_format plus ARCHIVE_FORMAT_BASE_MASK / ARCHIVE_FORMAT_MTREE through the
  FFI bindings and generate-ffi script so the rejection can consult libarchive's format
  code
- Extend CHANGES.md and the crate-level docs to describe the iterator-only opt-out
- Add an integration test that feeds tests/fixtures/file.txt.gz through the iterator
  with mtree_format(false) and asserts that the surface errors out

Author: otavio

CHANGES.md

@@ -9,9 +9,12 @@
   `uncompress_archive`, `uncompress_archive_file`, `ArchiveIterator`, and
   their `_with_encoding` and async variants now return an error for input
   that isn't a real archive, instead of treating it as a single-entry
-  archive named `data`. `uncompress_data` still supports raw streams
-  (that is its purpose). Callers that want the old iterator behavior can
-  opt back in with `ArchiveIteratorBuilder::raw_format(true)` [#77]
+  archive named `data`. `uncompress_data` still supports raw streams (that
+  is its purpose). Callers that want the old iterator behavior for
+  non-archive bytes can opt back in with
+  `ArchiveIteratorBuilder::raw_format(true)`. Callers iterating with
+  `ArchiveIterator` can additionally opt out of libarchive's permissive
+  mtree matching with `ArchiveIteratorBuilder::mtree_format(false)` [#77]
 * Rewind the source reader at the start of every seekable entry point
   (`list_archive_files`, `list_archive_entries`, `uncompress_archive`,
   `uncompress_archive_file`, `ArchiveIterator`, and their `_with_encoding`

scripts/generate-ffi

@@ -40,6 +40,9 @@ bindgen \
     --allowlist-var "ARCHIVE_EXTRACT_OWNER" \
     --allowlist-var "ARCHIVE_EXTRACT_FFLAGS" \
     --allowlist-var "ARCHIVE_EXTRACT_XATTR" \
+    --allowlist-var "ARCHIVE_FORMAT_BASE_MASK" \
+    --allowlist-var "ARCHIVE_FORMAT_MTREE" \
+    --allowlist-function "archive_format" \
     --allowlist-function "archive_read_new" \
     --allowlist-function "archive_read_set_seek_callback" \
     --allowlist-function "archive_read_support_filter_all" \

src/ffi/generated.rs

@@ -15,6 +15,8 @@ pub(crate) const ARCHIVE_EXTRACT_TIME: u32 = 4;
 pub(crate) const ARCHIVE_EXTRACT_ACL: u32 = 32;
 pub(crate) const ARCHIVE_EXTRACT_FFLAGS: u32 = 64;
 pub(crate) const ARCHIVE_EXTRACT_XATTR: u32 = 128;
+pub(crate) const ARCHIVE_FORMAT_BASE_MASK: ::std::os::raw::c_int = 0xff0000;
+pub(crate) const ARCHIVE_FORMAT_MTREE: ::std::os::raw::c_int = 0x80000;
 pub(crate) type __dev_t = ::std::os::raw::c_ulong;
 pub(crate) type __uid_t = ::std::os::raw::c_uint;
 pub(crate) type __gid_t = ::std::os::raw::c_uint;
@@ -158,6 +160,9 @@ extern "C" {
 extern "C" {
     pub(crate) fn archive_errno(arg1: *mut archive) -> ::std::os::raw::c_int;
 }
+extern "C" {
+    pub(crate) fn archive_format(arg1: *mut archive) -> ::std::os::raw::c_int;
+}
 extern "C" {
     pub(crate) fn archive_error_string(arg1: *mut archive) -> *const ::std::os::raw::c_char;
 }

src/iterator.rs

@@ -79,6 +79,7 @@ pub struct ArchiveIterator<R: Read + Seek> {
     current_is_dir: bool,
     closed: bool,
     error: bool,
+    mtree_format: bool,
     filter: Option<Box<EntryFilterCallbackFn>>,
 
     _pipe: Box<HeapReadSeekerPipe<R>>,
@@ -176,6 +177,7 @@ impl<R: Read + Seek> ArchiveIterator<R> {
         filter: Option<Box<EntryFilterCallbackFn>>,
         password: Option<ArchivePassword>,
         raw_format: bool,
+        mtree_format: bool,
     ) -> Result<ArchiveIterator<R>>
     where
         R: Read + Seek,
@@ -252,6 +254,7 @@ impl<R: Read + Seek> ArchiveIterator<R> {
                 current_is_dir: false,
                 closed: false,
                 error: false,
+                mtree_format,
                 filter,
 
                 _pipe: pipe,
@@ -307,7 +310,7 @@ impl<R: Read + Seek> ArchiveIterator<R> {
     where
         R: Read + Seek,
     {
-        Self::new(source, decode, None, None, false)
+        Self::new(source, decode, None, None, false, true)
     }
 
     /// Iterate over the contents of an archive, streaming the contents of each
@@ -346,7 +349,7 @@ impl<R: Read + Seek> ArchiveIterator<R> {
     where
         R: Read + Seek,
     {
-        Self::new(source, crate::decode_utf8, None, None, false)
+        Self::new(source, crate::decode_utf8, None, None, false, true)
     }
 
     /// Close the iterator, freeing up the associated resources.
@@ -380,6 +383,11 @@ impl<R: Read + Seek> ArchiveIterator<R> {
         match ffi::archive_read_next_header(self.archive_reader, &mut self.archive_entry) {
             ffi::ARCHIVE_EOF => ArchiveContents::EndOfEntry,
             ffi::ARCHIVE_OK | ffi::ARCHIVE_WARN => {
+                if !self.mtree_format {
+                    if let Err(e) = reject_mtree_format(self.archive_reader) {
+                        return ArchiveContents::Err(e);
+                    }
+                }
                 let _utf8_guard = ffi::WindowsUTF8LocaleGuard::new();
                 let cstr = CStr::from_ptr(ffi::archive_entry_pathname(self.archive_entry));
                 let file_name = match (self.decode)(cstr.to_bytes()) {
@@ -428,6 +436,20 @@ impl<R: Read + Seek> ArchiveIterator<R> {
     }
 }
 
+// Must be called after a successful `archive_read_next_header`, since
+// libarchive only populates the format code once a header has been read.
+unsafe fn reject_mtree_format(archive_reader: *mut ffi::archive) -> Result<()> {
+    if ffi::archive_format(archive_reader) & ffi::ARCHIVE_FORMAT_BASE_MASK
+        == ffi::ARCHIVE_FORMAT_MTREE
+    {
+        return Err(Error::Extraction {
+            code: None,
+            details: "mtree specifications are not treated as archives".to_string(),
+        });
+    }
+    Ok(())
+}
+
 unsafe extern "C" fn libarchive_heap_seek_callback<R: Read + Seek>(
     _: *mut ffi::archive,
     client_data: *mut c_void,
@@ -483,6 +505,7 @@ where
     filter: Option<Box<EntryFilterCallbackFn>>,
     password: Option<ArchivePassword>,
     raw_format: bool,
+    mtree_format: bool,
 }
 
 /// A builder to generate an archive iterator over the contents of an
@@ -523,6 +546,7 @@ where
             filter: None,
             password: None,
             raw_format: false,
+            mtree_format: true,
         }
     }
 
@@ -560,6 +584,16 @@ where
         self
     }
 
+    /// Accept entries from libarchive's "mtree" format handler (default).
+    ///
+    /// libarchive's mtree parser is permissive and will match free-form
+    /// text (a plain gunzip'd text file is enough); pass `false` to
+    /// reject those matches and error out instead.
+    pub fn mtree_format(mut self, enable: bool) -> ArchiveIteratorBuilder<R> {
+        self.mtree_format = enable;
+        self
+    }
+
     /// Finish the builder and generate the configured `ArchiveIterator`.
     pub fn build(self) -> Result<ArchiveIterator<R>> {
         ArchiveIterator::new(
@@ -568,6 +602,7 @@ where
             self.filter,
             self.password,
             self.raw_format,
+            self.mtree_format,
         )
     }
 }

src/lib.rs

@@ -52,15 +52,16 @@
 //! Archive-listing and archive-extraction entry points (`list_archive_files`,
 //! `list_archive_entries`, `uncompress_archive`, `uncompress_archive_file`,
 //! `ArchiveIterator`, and their async/`_with_encoding` siblings) no longer
-//! register libarchive's "raw" format handler. They return an error for
-//! input that isn't a real archive instead of yielding a single entry
-//! called `data`, so callers can reliably distinguish archives from other
-//! files.
+//! register libarchive's "raw" format handler, so input that isn't a real
+//! archive errors out instead of yielding a single `data` entry.
 //!
 //! Use [`uncompress_data`] for decompressing a single stream (gzip, xz, …)
 //! — it continues to support raw input because that is its purpose. For
 //! streaming iteration that should accept arbitrary bytes, opt back in
-//! with [`ArchiveIteratorBuilder::raw_format`].
+//! with [`ArchiveIteratorBuilder::raw_format`]. libarchive's "mtree"
+//! handler remains enabled on all entry points; pass
+//! `ArchiveIteratorBuilder::mtree_format(false)` to the iterator if you
+//! need to reject mtree matches.
 
 #[cfg(feature = "async_support")]
 pub mod async_support;

tests/integration_test.rs

@@ -1408,14 +1408,32 @@ fn iterator_default_rejects_non_archive_bytes() {
     let source = Cursor::new(NON_ARCHIVE_BYTES);
     let saw_err = match ArchiveIterator::from_read(source) {
         Err(_) => true,
-        Ok(iter) => iter.into_iter().any(|c| matches!(c, ArchiveContents::Err(_))),
+        Ok(iter) => iter
+            .into_iter()
+            .any(|c| matches!(c, ArchiveContents::Err(_))),
     };
     assert!(
         saw_err,
         "strict iterator must surface an error on non-archive input"
     );
 }
 
+#[test]
+fn iterator_mtree_format_opt_out_rejects_gzip_text() {
+    let source = std::fs::File::open("tests/fixtures/file.txt.gz").unwrap();
+    let saw_err = match ArchiveIteratorBuilder::new(source)
+        .mtree_format(false)
+        .build()
+    {
+        Err(_) => true,
+        Ok(mut iter) => iter.any(|c| matches!(c, ArchiveContents::Err(_))),
+    };
+    assert!(
+        saw_err,
+        "mtree_format(false) must reject libarchive's permissive mtree match on plain text"
+    );
+}
+
 #[test]
 fn iterator_raw_format_opt_in_accepts_non_archive_bytes() {
     let source = Cursor::new(NON_ARCHIVE_BYTES);