exarch-rs 0.4.0 → 0.5.0

package/package.json

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

package/src/config.rs

@@ -1,4 +1,4 @@
-//! Node.js bindings for `SecurityConfig`.
+//! Node.js bindings for `SecurityConfig` and `ExtractionOptions`.
 
 use exarch_core::SecurityConfig as CoreConfig;
 use napi::bindgen_prelude::Error;
@@ -30,7 +30,7 @@ const MAX_COMPONENT_LENGTH: usize = 255;
 /// | `allow_world_writable` | false |
 /// | `preserve_permissions` | false |
 /// | `allowed_extensions` | empty (all allowed) |
-/// | `banned_path_components` | `.git`, `.ssh` |
+/// | `banned_path_components` | `.git`, `.ssh`, `.gnupg`, `.aws`, `.kube`, `.docker`, `.env` |
 #[napi]
 #[derive(Debug, Clone)]
 pub struct SecurityConfig {
@@ -171,6 +171,29 @@ impl SecurityConfig {
         self
     }
 
+    /// Sets the maximum memory that may be used to decompress a solid 7z block.
+    ///
+    /// Solid archives decompress entire blocks into memory before individual
+    /// entries can be read. This limit caps that allocation to prevent
+    /// memory exhaustion from crafted archives. Default: 512 MB.
+    ///
+    /// # Errors
+    ///
+    /// Returns error if size is negative or zero.
+    #[napi(js_name = "setMaxSolidBlockMemory")]
+    pub fn set_max_solid_block_memory(&mut self, size: i64) -> Result<&Self> {
+        if size <= 0 {
+            return Err(Error::from_reason(
+                "max solid block memory must be a positive number",
+            ));
+        }
+        #[allow(clippy::cast_sign_loss)]
+        {
+            self.inner.max_solid_block_memory = size as u64;
+        }
+        Ok(self)
+    }
+
     /// Sets whether to preserve permissions from archive.
     #[napi(js_name = "setPreservePermissions")]
     pub fn set_preserve_permissions(&mut self, preserve: Option<bool>) -> &Self {
@@ -313,6 +336,19 @@ 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
+    }
+
+    /// Maximum memory in bytes for decompressing a solid 7z block.
+    #[napi(getter)]
+    #[allow(clippy::cast_possible_wrap)]
+    pub fn get_max_solid_block_memory(&self) -> i64 {
+        self.inner.max_solid_block_memory as i64
+    }
+
     /// List of allowed file extensions.
     ///
     /// Note: This getter clones the underlying data. For performance-critical
@@ -551,6 +587,96 @@ impl CreationConfig {
     }
 }
 
+/// Options controlling extraction behavior (non-security).
+///
+/// Separate from `SecurityConfig` to keep security settings focused.
+/// These options control operational behavior such as duplicate handling.
+///
+/// # Defaults
+///
+/// | Setting | Default Value |
+/// |---------|--------------|
+/// | `skipDuplicates` | `true` |
+/// | `atomic` | `false` |
+#[napi]
+#[derive(Debug, Clone)]
+pub struct ExtractionOptions {
+    inner: exarch_core::ExtractionOptions,
+}
+
+#[napi]
+impl ExtractionOptions {
+    /// Creates a new `ExtractionOptions` with defaults.
+    #[napi(constructor)]
+    pub fn new() -> Self {
+        Self {
+            inner: exarch_core::ExtractionOptions::default(),
+        }
+    }
+
+    /// Creates an `ExtractionOptions` with defaults.
+    ///
+    /// This is equivalent to calling `new ExtractionOptions()`.
+    #[napi(factory)]
+    pub fn default() -> Self {
+        Self::new()
+    }
+
+    /// Sets whether duplicate archive entries are skipped silently.
+    ///
+    /// When `true` (default), duplicate entries produce a warning in the
+    /// report. When `false`, a duplicate entry causes an error.
+    #[napi(js_name = "withSkipDuplicates")]
+    pub fn with_skip_duplicates(&mut self, skip: Option<bool>) -> &Self {
+        self.inner.skip_duplicates = skip.unwrap_or(true);
+        self
+    }
+
+    /// Sets whether extraction uses a temporary directory for atomic commits.
+    ///
+    /// When `true`, files are extracted to a temp dir in the same parent as
+    /// the output directory, then atomically renamed on completion. On failure
+    /// the temp dir is removed, leaving the output directory untouched.
+    /// Default: `false`.
+    ///
+    /// **Important:** atomic mode requires that the output directory does not
+    /// already exist. If it does, extraction fails with an
+    /// output-already-exists error. Non-atomic mode extracts into an
+    /// existing directory without error.
+    #[napi(js_name = "withAtomic")]
+    pub fn with_atomic(&mut self, atomic: Option<bool>) -> &Self {
+        self.inner.atomic = atomic.unwrap_or(true);
+        self
+    }
+
+    /// Finalizes the configuration (for API consistency).
+    #[napi]
+    pub fn build(&self) -> &Self {
+        self
+    }
+
+    /// Whether duplicate entries are skipped silently.
+    #[napi(getter)]
+    pub fn get_skip_duplicates(&self) -> bool {
+        self.inner.skip_duplicates
+    }
+
+    /// Whether atomic extraction is enabled.
+    #[napi(getter)]
+    pub fn get_atomic(&self) -> bool {
+        self.inner.atomic
+    }
+}
+
+impl ExtractionOptions {
+    /// Returns a reference to the inner `CoreExtractionOptions`.
+    ///
+    /// Used internally to pass options to the Rust extraction API.
+    pub fn as_core(&self) -> &exarch_core::ExtractionOptions {
+        &self.inner
+    }
+}
+
 #[cfg(test)]
 #[allow(
     clippy::unwrap_used,
@@ -829,6 +955,70 @@ 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_max_solid_block_memory_default() {
+        let config = SecurityConfig::new();
+        assert_eq!(
+            config.get_max_solid_block_memory(),
+            512 * 1024 * 1024,
+            "max_solid_block_memory should default to 512 MB"
+        );
+    }
+
+    #[test]
+    fn test_max_solid_block_memory_round_trip() {
+        let mut config = SecurityConfig::new();
+        let result = config.set_max_solid_block_memory(256 * 1024 * 1024);
+        assert!(result.is_ok());
+        assert_eq!(
+            config.get_max_solid_block_memory(),
+            256 * 1024 * 1024,
+            "getter should reflect set value"
+        );
+    }
+
+    #[test]
+    fn test_max_solid_block_memory_rejects_negative() {
+        let mut config = SecurityConfig::new();
+        let result = config.set_max_solid_block_memory(-1);
+        assert!(result.is_err(), "negative value should be rejected");
+        assert!(
+            result.unwrap_err().to_string().contains("positive"),
+            "error should mention positive requirement"
+        );
+    }
+
+    #[test]
+    fn test_max_solid_block_memory_rejects_zero() {
+        let mut config = SecurityConfig::new();
+        let result = config.set_max_solid_block_memory(0);
+        assert!(result.is_err(), "zero should be rejected");
+    }
+
+    #[test]
+    fn test_max_solid_block_memory_accepts_one_byte() {
+        let mut config = SecurityConfig::new();
+        let result = config.set_max_solid_block_memory(1);
+        assert!(result.is_ok(), "1 byte should be accepted");
+        assert_eq!(config.get_max_solid_block_memory(), 1);
+    }
+
     #[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: ");
@@ -183,9 +179,12 @@ pub fn convert_error(err: CoreError) -> Error {
             Error::new(Status::GenericFailure, msg)
         }
         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("PARTIAL_EXTRACTION: ");
             msg.push_str(&inner.reason);
             let _ = write!(
                 &mut msg,
@@ -333,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]
@@ -361,10 +362,12 @@ mod tests {
         assert!(err_str.contains("file not found"));
     }
 
-    /// Regression test for #210: `convert_error` must embed `filesExtracted`
-    /// and `bytesWritten` in the error message for `PartialExtraction`.
+    /// 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_node_message_format() {
+    fn test_partial_extraction_preserves_specific_code_with_report() {
         use exarch_core::ExtractionReport;
         use exarch_core::QuotaResource;
 
@@ -383,9 +386,11 @@ mod tests {
 
         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.contains("PARTIAL_EXTRACTION"),
-            "message must contain PARTIAL_EXTRACTION, got: {msg}"
+            msg.starts_with("QUOTA_EXCEEDED"),
+            "message must start with QUOTA_EXCEEDED, got: {msg}"
         );
         assert!(
             msg.contains("filesExtracted=3"),
@@ -396,4 +401,88 @@ mod tests {
             "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);
+    }
 }