exarch-rs 0.3.1 → 0.4.1

package/README.md

@@ -161,19 +161,51 @@ interface ExtractionReport {
 }
 ```
 
+### `extractArchiveWithProgress(archivePath, outputDir, config?, progress?)`
+
+Async extraction with an optional progress callback.
+
+```typescript
+import { extractArchiveWithProgress } from 'exarch-rs';
+
+const result = await extractArchiveWithProgress(
+  'archive.tar.gz',
+  '/output/path',
+  undefined,  // SecurityConfig or undefined
+  (path, total, current, bytesWritten) => {
+    console.log(`[${current}/${total}] ${path} (${bytesWritten} bytes)`);
+  }
+);
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `archivePath` | `string` | Path to the archive file |
+| `outputDir` | `string` | Directory where files will be extracted |
+| `config` | `SecurityConfig \| undefined` | Optional security configuration |
+| `progress` | `(path: string, total: bigint, current: bigint, bytesWritten: bigint) => void \| undefined` | Optional progress callback |
+
+**Returns:** `Promise<ExtractionReport>`
+
 ### `SecurityConfig`
 
 Builder-style security configuration.
 
 ```typescript
 const config = new SecurityConfig()
-  .maxFileSize(bytes)              // Max size per file
-  .maxTotalSize(bytes)             // Max total extraction size
-  .maxFileCount(count)             // Max number of files
-  .maxCompressionRatio(n)          // Max compression ratio (zip bomb detection)
-  .setAllowSolidArchives(true);    // Allow solid 7z archives (default: false)
+  .maxFileSize(bytes)                        // Max size per file
+  .maxTotalSize(bytes)                       // Max total extraction size
+  .maxFileCount(count)                       // Max number of files
+  .maxCompressionRatio(n)                    // Max compression ratio (zip bomb detection)
+  .allowedExtensions([".txt", ".md"])        // Restrict to a set of extensions
+  .bannedPathComponents(["__MACOSX"])        // Skip these path components
+  .setAllowSolidArchives(true);              // Allow solid 7z archives (default: false)
 ```
 
+**Getters:** `allowSymlinks`, `allowHardlinks`, `allowAbsolutePaths`, `allowWorldWritable`, `allowSolidArchives` — each returns the corresponding boolean policy value.
+
 ## Security Features
 
 The library provides built-in protection against:
@@ -203,6 +235,8 @@ The library provides built-in protection against:
 
 **Note:** 7z creation is not yet supported. Solid and encrypted 7z archives are rejected for security reasons. Unix symlinks inside 7z archives are reported as regular files (sevenz-rust2 API limitation).
 
+**Note:** Since v0.4.0, partial extraction failures return the `ExtractionReport` accumulated up to the failure point without the inner error text being duplicated, and the report is now correctly delivered across the FFI boundary instead of being dropped early.
+
 ## Comparison with tar-fs
 
 ```javascript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exarch-rs",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Memory-safe archive extraction library with built-in security validation",
   "main": "index.js",
   "types": "index.d.ts",

package/src/config.rs

@@ -313,6 +313,12 @@ impl SecurityConfig {
         self.inner.allowed.world_writable
     }
 
+    /// Whether solid 7z archives are allowed.
+    #[napi(getter)]
+    pub fn get_allow_solid_archives(&self) -> bool {
+        self.inner.allow_solid_archives
+    }
+
     /// List of allowed file extensions.
     ///
     /// Note: This getter clones the underlying data. For performance-critical
@@ -829,6 +835,22 @@ mod tests {
         );
     }
 
+    #[test]
+    fn test_allow_solid_archives_default_and_round_trip() {
+        let config = SecurityConfig::new();
+        assert!(
+            !config.get_allow_solid_archives(),
+            "allow_solid_archives should default to false"
+        );
+
+        let mut config = SecurityConfig::new();
+        config.set_allow_solid_archives(Some(true));
+        assert!(
+            config.get_allow_solid_archives(),
+            "allow_solid_archives getter should reflect setter value"
+        );
+    }
+
     #[test]
     fn test_allowed_extensions_getter_after_add() {
         let mut config = SecurityConfig::new();

package/src/error.rs

@@ -1,6 +1,6 @@
 //! Error conversion for Node.js bindings.
 
-use exarch_core::ExtractionError as CoreError;
+use exarch_core::ArchiveError as CoreError;
 use exarch_core::QuotaResource as CoreQuotaResource;
 use napi::bindgen_prelude::*;
 use std::path::Path;
@@ -123,10 +123,6 @@ pub fn convert_error(err: CoreError) -> Error {
             msg.push_str(&reason);
             Error::new(Status::GenericFailure, msg)
         }
-        CoreError::UnsupportedFormat => Error::new(
-            Status::GenericFailure,
-            "UNSUPPORTED_FORMAT: unsupported archive format",
-        ),
         CoreError::InvalidArchive(archive_msg) => {
             let mut msg = String::with_capacity(30 + archive_msg.len());
             msg.push_str("INVALID_ARCHIVE: invalid archive: ");
@@ -182,7 +178,21 @@ pub fn convert_error(err: CoreError) -> Error {
             msg.push_str(&reason);
             Error::new(Status::GenericFailure, msg)
         }
-        CoreError::PartialExtraction { source, .. } => convert_error(*source),
+        CoreError::PartialExtraction { source, report } => {
+            // Preserve the specific error code (SYMLINK_ESCAPE, QUOTA_EXCEEDED, etc.) from
+            // the inner source so JavaScript callers can distinguish the error type. The
+            // partial-extraction report fields from #210 are appended for caller
+            // inspection.
+            let inner = convert_error(*source);
+            let mut msg = String::with_capacity(inner.reason.len() + 64);
+            msg.push_str(&inner.reason);
+            let _ = write!(
+                &mut msg,
+                " | filesExtracted={}, bytesWritten={}",
+                report.files_extracted, report.bytes_written
+            );
+            Error::new(Status::GenericFailure, msg)
+        }
     }
 }
 
@@ -322,12 +332,14 @@ mod tests {
     }
 
     #[test]
-    fn test_unsupported_format_conversion() {
-        let err = CoreError::UnsupportedFormat;
+    fn test_unknown_format_conversion() {
+        let err = CoreError::UnknownFormat {
+            path: std::path::PathBuf::from("archive.rar"),
+        };
         let napi_err = convert_error(err);
         let err_str = napi_err.to_string();
-        assert!(err_str.contains("UNSUPPORTED_FORMAT"));
-        assert!(err_str.contains("unsupported archive format"));
+        assert!(err_str.contains("UNKNOWN_FORMAT"));
+        assert!(err_str.contains("cannot determine archive format"));
     }
 
     #[test]
@@ -349,4 +361,128 @@ mod tests {
         assert!(err_str.contains("IO_ERROR"));
         assert!(err_str.contains("file not found"));
     }
+
+    /// Regression test for #251 + #210: `convert_error` must preserve the
+    /// specific error code from the inner source (e.g. `QUOTA_EXCEEDED`,
+    /// not `PARTIAL_EXTRACTION`), while still appending `filesExtracted`
+    /// and `bytesWritten` for caller inspection.
+    #[test]
+    fn test_partial_extraction_preserves_specific_code_with_report() {
+        use exarch_core::ExtractionReport;
+        use exarch_core::QuotaResource;
+
+        let report = ExtractionReport {
+            files_extracted: 3,
+            bytes_written: 1024,
+            ..ExtractionReport::default()
+        };
+        let source = CoreError::QuotaExceeded {
+            resource: QuotaResource::FileCount { current: 4, max: 3 },
+        };
+        let err = CoreError::PartialExtraction {
+            source: Box::new(source),
+            report,
+        };
+
+        let napi_err = convert_error(err);
+        let msg = napi_err.reason.clone();
+        // Must carry the specific error code, not the generic PARTIAL_EXTRACTION
+        // prefix.
+        assert!(
+            msg.starts_with("QUOTA_EXCEEDED"),
+            "message must start with QUOTA_EXCEEDED, got: {msg}"
+        );
+        assert!(
+            msg.contains("filesExtracted=3"),
+            "message must contain filesExtracted=3, got: {msg}"
+        );
+        assert!(
+            msg.contains("bytesWritten=1024"),
+            "message must contain bytesWritten=1024, got: {msg}"
+        );
+    }
+
+    // Regression tests for #251: security error variants must also preserve
+    // their specific error code and carry the #210 report fields.
+    //
+    // Helper that asserts the produced error reason starts with the given code
+    // and contains the expected report fields.
+    fn assert_partial_node_report(napi_err: &Error, expected_code: &str, files: usize, bytes: u64) {
+        let msg = &napi_err.reason;
+        assert!(
+            msg.starts_with(expected_code),
+            "message must start with {expected_code}, got: {msg}"
+        );
+        assert!(
+            msg.contains(&format!("filesExtracted={files}")),
+            "message must contain filesExtracted={files}, got: {msg}"
+        );
+        assert!(
+            msg.contains(&format!("bytesWritten={bytes}")),
+            "message must contain bytesWritten={bytes}, got: {msg}"
+        );
+    }
+
+    #[test]
+    fn test_partial_extraction_symlink_escape_preserves_code_and_report() {
+        use exarch_core::ExtractionReport;
+
+        let report = ExtractionReport {
+            files_extracted: 2,
+            bytes_written: 512,
+            ..ExtractionReport::default()
+        };
+        let source = CoreError::SymlinkEscape {
+            path: PathBuf::from("/etc/passwd"),
+        };
+        let err = CoreError::PartialExtraction {
+            source: Box::new(source),
+            report,
+        };
+
+        let napi_err = convert_error(err);
+        assert_partial_node_report(&napi_err, "SYMLINK_ESCAPE", 2, 512);
+    }
+
+    #[test]
+    fn test_partial_extraction_hardlink_escape_preserves_code_and_report() {
+        use exarch_core::ExtractionReport;
+
+        let report = ExtractionReport {
+            files_extracted: 2,
+            bytes_written: 512,
+            ..ExtractionReport::default()
+        };
+        let source = CoreError::HardlinkEscape {
+            path: PathBuf::from("/etc/shadow"),
+        };
+        let err = CoreError::PartialExtraction {
+            source: Box::new(source),
+            report,
+        };
+
+        let napi_err = convert_error(err);
+        assert_partial_node_report(&napi_err, "HARDLINK_ESCAPE", 2, 512);
+    }
+
+    #[test]
+    fn test_partial_extraction_security_violation_preserves_code_and_report() {
+        use exarch_core::ExtractionReport;
+
+        let report = ExtractionReport {
+            files_extracted: 2,
+            bytes_written: 512,
+            ..ExtractionReport::default()
+        };
+        let source = CoreError::SecurityViolation {
+            reason: "test policy violation".to_string(),
+        };
+        let err = CoreError::PartialExtraction {
+            source: Box::new(source),
+            report,
+        };
+
+        let napi_err = convert_error(err);
+        assert_partial_node_report(&napi_err, "SECURITY_VIOLATION", 2, 512);
+    }
 }

package/src/lib.rs

@@ -44,6 +44,8 @@
 #![allow(clippy::trailing_empty_array)]
 
 use napi::bindgen_prelude::*;
+use napi::threadsafe_function::ThreadsafeFunction;
+use napi::threadsafe_function::ThreadsafeFunctionCallMode;
 use napi_derive::napi;
 
 mod config;
@@ -150,11 +152,16 @@ pub async fn extract_archive(
     // For maximum security with untrusted archives, use extractArchiveSync()
     // or ensure exclusive file access (e.g., flock) during extraction.
     let report = tokio::task::spawn_blocking(move || {
-        exarch_core::extract_archive(&archive_path, &output_dir, &config_owned)
+        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            exarch_core::extract_archive(&archive_path, &output_dir, &config_owned)
+                .map_err(convert_error)
+        }))
+        .map_err(|_| Error::from_reason("Internal panic during archive extraction"))
+        .flatten()
     })
     .await
-    .map_err(|e| Error::from_reason(format!("task execution failed: {e}")))?
-    .map_err(convert_error)?;
+    .map_err(|e| Error::from_reason(format!("task join error: {e}")))
+    .flatten()?;
 
     Ok(ExtractionReport::from(report))
 }
@@ -264,12 +271,17 @@ pub async fn create_archive(
         config.map(|c| c.as_core().clone()).unwrap_or_default();
 
     let report = tokio::task::spawn_blocking(move || {
-        let sources_refs: Vec<&str> = sources.iter().map(String::as_str).collect();
-        exarch_core::create_archive(&output_path, &sources_refs, &config_owned)
+        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            let sources_refs: Vec<&str> = sources.iter().map(String::as_str).collect();
+            exarch_core::create_archive(&output_path, &sources_refs, &config_owned)
+                .map_err(convert_error)
+        }))
+        .map_err(|_| Error::from_reason("Internal panic during archive creation"))
+        .flatten()
     })
     .await
-    .map_err(|e| Error::from_reason(format!("task execution failed: {e}")))?
-    .map_err(convert_error)?;
+    .map_err(|e| Error::from_reason(format!("task join error: {e}")))
+    .flatten()?;
 
     Ok(CreationReport::from(report))
 }
@@ -364,11 +376,15 @@ pub async fn list_archive(
         config.map(|c| c.as_core().clone()).unwrap_or_default();
 
     let manifest = tokio::task::spawn_blocking(move || {
-        exarch_core::list_archive(&archive_path, &config_owned)
+        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            exarch_core::list_archive(&archive_path, &config_owned).map_err(convert_error)
+        }))
+        .map_err(|_| Error::from_reason("Internal panic during archive listing"))
+        .flatten()
     })
     .await
-    .map_err(|e| Error::from_reason(format!("task execution failed: {e}")))?
-    .map_err(convert_error)?;
+    .map_err(|e| Error::from_reason(format!("task join error: {e}")))
+    .flatten()?;
 
     Ok(ArchiveManifest::from(manifest))
 }
@@ -461,11 +477,15 @@ pub async fn verify_archive(
         config.map(|c| c.as_core().clone()).unwrap_or_default();
 
     let report = tokio::task::spawn_blocking(move || {
-        exarch_core::verify_archive(&archive_path, &config_owned)
+        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            exarch_core::verify_archive(&archive_path, &config_owned).map_err(convert_error)
+        }))
+        .map_err(|_| Error::from_reason("Internal panic during archive verification"))
+        .flatten()
     })
     .await
-    .map_err(|e| Error::from_reason(format!("task execution failed: {e}")))?
-    .map_err(convert_error)?;
+    .map_err(|e| Error::from_reason(format!("task join error: {e}")))
+    .flatten()?;
 
     Ok(VerificationReport::from(report))
 }
@@ -517,10 +537,151 @@ pub fn verify_archive_sync(
     Ok(VerificationReport::from(report))
 }
 
-// NOTE: Progress callback support (createArchiveWithProgress) is planned for
-// a future release. The napi-rs 3.x ThreadsafeFunction API requires additional
-// work to properly bridge Rust ProgressCallback trait to JavaScript callbacks.
-// For now, use createArchive/createArchiveSync without progress tracking.
+/// Extract an archive to the specified directory with a progress callback
+/// (async).
+///
+/// The `progress` callback is called once per entry with
+/// `(path, total, current, bytesWritten)` where:
+/// - `path` — entry path inside the archive
+/// - `total` — total number of entries as `bigint` (0 for TAR-family formats
+///   because the entry count is unknown until the stream is fully read)
+/// - `current` — 1-based index of the current entry as `bigint`
+/// - `bytesWritten` — cumulative bytes written to disk so far as `bigint`
+///   (always 0 during extraction because the core library does not emit
+///   byte-level progress events for extraction; only entry-level events fire)
+///
+/// Extraction runs on the tokio blocking thread pool. The progress callback is
+/// dispatched back to the JavaScript thread via a threadsafe function.
+///
+/// # Arguments
+///
+/// * `archive_path` - Path to the archive file
+/// * `output_dir` - Directory where files will be extracted
+/// * `config` - Optional `SecurityConfig` (uses secure defaults if omitted)
+/// * `progress` - Optional progress callback `(path: string, total: bigint,
+///   current: bigint, bytesWritten: bigint) => void`
+///
+/// # Returns
+///
+/// Promise resolving to `ExtractionReport` with extraction statistics
+///
+/// # Errors
+///
+/// Returns error for security violations or I/O errors. Error messages are
+/// prefixed with error codes for discrimination in JavaScript. See
+/// `extractArchive` for the full list of error codes.
+///
+/// # Examples
+///
+/// ```javascript
+/// const report = await extractArchiveWithProgress(
+///   'archive.tar.gz',
+///   '/tmp/output',
+///   null,
+///   (path, total, current, bytesWritten) => {
+///     console.log(`${current}/${total}: ${path}`);
+///   },
+/// );
+/// console.log(`Extracted ${report.filesExtracted} files`);
+/// ```
+#[napi]
+#[allow(clippy::needless_pass_by_value, clippy::trailing_empty_array)]
+pub async fn extract_archive_with_progress(
+    archive_path: String,
+    output_dir: String,
+    config: Option<&SecurityConfig>,
+    progress: Option<ThreadsafeFunction<(String, i64, i64, i64)>>,
+) -> Result<ExtractionReport> {
+    validate_path(&archive_path)?;
+    validate_path(&output_dir)?;
+
+    let config_owned: exarch_core::SecurityConfig =
+        config.map(|c| c.as_core().clone()).unwrap_or_default();
+
+    let report = tokio::task::spawn_blocking(move || {
+        std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+            run_extract_with_optional_progress(&archive_path, &output_dir, &config_owned, progress)
+                .map_err(convert_error)
+        }))
+        .map_err(|_| Error::from_reason("Internal panic during archive extraction with progress"))
+        .flatten()
+    })
+    .await
+    .map_err(|e| Error::from_reason(format!("task join error: {e}")))
+    .flatten()?;
+
+    Ok(ExtractionReport::from(report))
+}
+
+/// Runs `extract_archive_with_progress` routing to the JS callback when present
+/// or to [`exarch_core::NoopProgress`] when absent.
+fn run_extract_with_optional_progress(
+    archive_path: &str,
+    output_dir: &str,
+    config: &exarch_core::SecurityConfig,
+    progress: Option<ThreadsafeFunction<(String, i64, i64, i64)>>,
+) -> exarch_core::Result<exarch_core::ExtractionReport> {
+    progress.map_or_else(
+        || {
+            let mut noop = exarch_core::NoopProgress;
+            exarch_core::extract_archive_with_progress(archive_path, output_dir, config, &mut noop)
+        },
+        |tsfn| {
+            let mut callback = NodeProgressAdapter::new(tsfn);
+            exarch_core::extract_archive_with_progress(
+                archive_path,
+                output_dir,
+                config,
+                &mut callback,
+            )
+        },
+    )
+}
+
+/// Adapter that calls a JavaScript progress callback from a Rust worker thread.
+///
+/// The JavaScript callback receives `(path: string, total: number, current:
+/// number, bytesWritten: number)` where `bytesWritten` is the number of bytes
+/// written **for the current entry so far** (starts at 0 when the entry begins,
+/// grows as chunks are flushed to disk; always 0 during extraction because the
+/// core library does not emit byte-level progress events for extraction).
+struct NodeProgressAdapter {
+    tsfn: ThreadsafeFunction<(String, i64, i64, i64)>,
+    current_entry_bytes: i64,
+    total: usize,
+}
+
+impl NodeProgressAdapter {
+    fn new(tsfn: ThreadsafeFunction<(String, i64, i64, i64)>) -> Self {
+        Self {
+            tsfn,
+            current_entry_bytes: 0,
+            total: 0,
+        }
+    }
+}
+
+impl exarch_core::ProgressCallback for NodeProgressAdapter {
+    fn on_entry_start(&mut self, path: &std::path::Path, total: usize, current: usize) {
+        self.current_entry_bytes = 0;
+        self.total = total;
+        let path_str = path.to_string_lossy().into_owned();
+        let total_i64 = i64::try_from(total).unwrap_or(i64::MAX);
+        let current_i64 = i64::try_from(current).unwrap_or(i64::MAX);
+        self.tsfn.call(
+            Ok((path_str, total_i64, current_i64, self.current_entry_bytes)),
+            ThreadsafeFunctionCallMode::NonBlocking,
+        );
+    }
+
+    fn on_bytes_written(&mut self, bytes: u64) {
+        self.current_entry_bytes = self.current_entry_bytes.saturating_add(bytes.cast_signed());
+    }
+
+    fn on_entry_complete(&mut self, _path: &std::path::Path) {}
+
+    fn on_complete(&mut self) {}
+}
 
 #[cfg(test)]
 #[allow(

package/tests/security-config.test.js

@@ -112,6 +112,19 @@ describe('SecurityConfig', () => {
       assert.strictEqual(config.allowWorldWritable, true);
     });
 
+    it('should default allowSolidArchives to false', () => {
+      const config = new SecurityConfig();
+
+      assert.strictEqual(config.allowSolidArchives, false);
+    });
+
+    it('should set allow solid archives', () => {
+      const config = new SecurityConfig();
+      config.setAllowSolidArchives(true);
+
+      assert.strictEqual(config.allowSolidArchives, true);
+    });
+
     it('should set preserve permissions', () => {
       const config = new SecurityConfig();
       config.setPreservePermissions(true);