exarch-rs 0.4.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exarch-rs",
-  "version": "0.4.1",
+  "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 {
@@ -319,6 +342,13 @@ impl SecurityConfig {
         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
@@ -557,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,
@@ -851,6 +971,54 @@ mod tests {
         );
     }
 
+    #[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/lib.rs

@@ -54,6 +54,7 @@ mod report;
 mod utils;
 
 use config::CreationConfig;
+use config::ExtractionOptions;
 use config::SecurityConfig;
 use error::convert_error;
 use report::ArchiveManifest;
@@ -119,8 +120,12 @@ use utils::validate_path;
 /// console.log(`Extracted ${report.filesExtracted} files`);
 ///
 /// // Customize security settings
-/// const config = new SecurityConfig().maxFileSize(100 * 1024 * 1024);
+/// const config = new SecurityConfig().setMaxFileSize(100 * 1024 * 1024);
 /// const report = await extractArchive('archive.tar.gz', '/tmp/output', config);
+///
+/// // Customize extraction options
+/// const opts = new ExtractionOptions().withSkipDuplicates(false);
+/// const report = await extractArchive('archive.tar.gz', '/tmp/output', null, opts);
 /// ```
 #[napi]
 #[allow(clippy::needless_pass_by_value, clippy::trailing_empty_array)]
@@ -128,6 +133,7 @@ pub async fn extract_archive(
     archive_path: String,
     output_dir: String,
     config: Option<&SecurityConfig>,
+    options: Option<&ExtractionOptions>,
 ) -> Result<ExtractionReport> {
     // Validate paths at boundary
     // NOTE: Defense-in-depth - paths are validated here and again in core
@@ -136,9 +142,11 @@ pub async fn extract_archive(
     validate_path(&archive_path)?;
     validate_path(&output_dir)?;
 
-    // Get owned config - clone only when config is Some, use default otherwise
+    // Get owned config/options - clone only when Some, use default otherwise
     let config_owned: exarch_core::SecurityConfig =
         config.map(|c| c.as_core().clone()).unwrap_or_default();
+    let options_owned: exarch_core::ExtractionOptions =
+        options.map(|o| o.as_core().clone()).unwrap_or_default();
 
     // Run extraction on tokio thread pool
     //
@@ -153,8 +161,13 @@ pub async fn extract_archive(
     // or ensure exclusive file access (e.g., flock) during extraction.
     let report = tokio::task::spawn_blocking(move || {
         std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
-            exarch_core::extract_archive(&archive_path, &output_dir, &config_owned)
-                .map_err(convert_error)
+            exarch_core::extract_archive_with_options(
+                &archive_path,
+                &output_dir,
+                &config_owned,
+                &options_owned,
+            )
+            .map_err(convert_error)
         }))
         .map_err(|_| Error::from_reason("Internal panic during archive extraction"))
         .flatten()
@@ -194,7 +207,7 @@ pub async fn extract_archive(
 /// console.log(`Extracted ${report.filesExtracted} files`);
 ///
 /// // Customize security settings
-/// const config = new SecurityConfig().maxFileSize(100 * 1024 * 1024);
+/// const config = new SecurityConfig().setMaxFileSize(100 * 1024 * 1024);
 /// const report = extractArchiveSync('archive.tar.gz', '/tmp/output', config);
 /// ```
 #[napi]
@@ -203,6 +216,7 @@ pub fn extract_archive_sync(
     archive_path: String,
     output_dir: String,
     config: Option<&SecurityConfig>,
+    options: Option<&ExtractionOptions>,
 ) -> Result<ExtractionReport> {
     // Validate paths at boundary
     // NOTE: Defense-in-depth - paths are validated here and again in core
@@ -211,14 +225,21 @@ pub fn extract_archive_sync(
     validate_path(&archive_path)?;
     validate_path(&output_dir)?;
 
-    // Get config reference or use default
     let default_config = exarch_core::SecurityConfig::default();
     let config_ref = config.map_or(&default_config, |c| c.as_core());
 
+    let default_options = exarch_core::ExtractionOptions::default();
+    let options_ref = options.map_or(&default_options, |o| o.as_core());
+
     // Run extraction synchronously with panic safety
     // CRITICAL: Never panic across FFI boundary
     let report = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
-        exarch_core::extract_archive(&archive_path, &output_dir, config_ref)
+        exarch_core::extract_archive_with_options(
+            &archive_path,
+            &output_dir,
+            config_ref,
+            options_ref,
+        )
     }))
     .map_err(|_| Error::from_reason("Internal panic during archive extraction"))?
     .map_err(convert_error)?;
@@ -543,10 +564,10 @@ pub fn verify_archive_sync(
 /// 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
+/// - `total` — total number of entries as `number` (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`
+/// - `current` — 1-based index of the current entry as `number`
+/// - `bytesWritten` — cumulative bytes written to disk so far as `number`
 ///   (always 0 during extraction because the core library does not emit
 ///   byte-level progress events for extraction; only entry-level events fire)
 ///
@@ -558,8 +579,9 @@ pub fn verify_archive_sync(
 /// * `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`
+/// * `options` - Optional `ExtractionOptions` (uses defaults if omitted)
+/// * `progress` - Optional progress callback `(path: string, total: number,
+///   current: number, bytesWritten: number) => void`
 ///
 /// # Returns
 ///
@@ -578,6 +600,7 @@ pub fn verify_archive_sync(
 ///   'archive.tar.gz',
 ///   '/tmp/output',
 ///   null,
+///   null,
 ///   (path, total, current, bytesWritten) => {
 ///     console.log(`${current}/${total}: ${path}`);
 ///   },
@@ -590,6 +613,7 @@ pub async fn extract_archive_with_progress(
     archive_path: String,
     output_dir: String,
     config: Option<&SecurityConfig>,
+    options: Option<&ExtractionOptions>,
     progress: Option<ThreadsafeFunction<(String, i64, i64, i64)>>,
 ) -> Result<ExtractionReport> {
     validate_path(&archive_path)?;
@@ -597,11 +621,19 @@ pub async fn extract_archive_with_progress(
 
     let config_owned: exarch_core::SecurityConfig =
         config.map(|c| c.as_core().clone()).unwrap_or_default();
+    let options_owned: exarch_core::ExtractionOptions =
+        options.map(|o| o.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)
+            run_extract_with_optional_progress(
+                &archive_path,
+                &output_dir,
+                &config_owned,
+                &options_owned,
+                progress,
+            )
+            .map_err(convert_error)
         }))
         .map_err(|_| Error::from_reason("Internal panic during archive extraction with progress"))
         .flatten()
@@ -613,25 +645,33 @@ pub async fn extract_archive_with_progress(
     Ok(ExtractionReport::from(report))
 }
 
-/// Runs `extract_archive_with_progress` routing to the JS callback when present
-/// or to [`exarch_core::NoopProgress`] when absent.
+/// Runs `extract_archive_with_options_and_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,
+    options: &exarch_core::ExtractionOptions,
     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)
+            exarch_core::extract_archive_with_options_and_progress(
+                archive_path,
+                output_dir,
+                config,
+                options,
+                &mut noop,
+            )
         },
         |tsfn| {
             let mut callback = NodeProgressAdapter::new(tsfn);
-            exarch_core::extract_archive_with_progress(
+            exarch_core::extract_archive_with_options_and_progress(
                 archive_path,
                 output_dir,
                 config,
+                options,
                 &mut callback,
             )
         },
@@ -700,6 +740,7 @@ mod tests {
             "/tmp/test\0malicious.tar".to_string(),
             "/tmp/output".to_string(),
             None,
+            None,
         )
         .await;
 
@@ -716,6 +757,7 @@ mod tests {
             "/tmp/test.tar".to_string(),
             "/tmp/output\0malicious".to_string(),
             None,
+            None,
         )
         .await;
 
@@ -729,7 +771,7 @@ mod tests {
     #[tokio::test]
     async fn test_extract_archive_rejects_excessively_long_archive_path() {
         let long_path = "x".repeat(5000);
-        let result = extract_archive(long_path, "/tmp/output".to_string(), None).await;
+        let result = extract_archive(long_path, "/tmp/output".to_string(), None, None).await;
 
         assert!(result.is_err(), "should reject excessively long paths");
         assert!(
@@ -741,7 +783,7 @@ mod tests {
     #[tokio::test]
     async fn test_extract_archive_rejects_excessively_long_output_dir() {
         let long_path = "x".repeat(5000);
-        let result = extract_archive("/tmp/test.tar".to_string(), long_path, None).await;
+        let result = extract_archive("/tmp/test.tar".to_string(), long_path, None, None).await;
 
         assert!(result.is_err(), "should reject excessively long paths");
         assert!(
@@ -754,7 +796,7 @@ mod tests {
     async fn test_extract_archive_accepts_empty_paths() {
         // Empty paths should be accepted at boundary validation
         // Core library will handle actual path validation
-        let result = extract_archive("".to_string(), "".to_string(), None).await;
+        let result = extract_archive("".to_string(), "".to_string(), None, None).await;
 
         // If it fails, ensure it's not a boundary path validation error
         // (empty paths pass boundary validation; core handles semantic validation)
@@ -776,6 +818,7 @@ mod tests {
             "/tmp/test\0malicious.tar".to_string(),
             "/tmp/output".to_string(),
             None,
+            None,
         );
 
         assert!(result.is_err(), "should reject null bytes in archive path");
@@ -791,6 +834,7 @@ mod tests {
             "/tmp/test.tar".to_string(),
             "/tmp/output\0malicious".to_string(),
             None,
+            None,
         );
 
         assert!(result.is_err(), "should reject null bytes in output path");
@@ -803,7 +847,7 @@ mod tests {
     #[test]
     fn test_extract_archive_sync_rejects_excessively_long_archive_path() {
         let long_path = "x".repeat(5000);
-        let result = extract_archive_sync(long_path, "/tmp/output".to_string(), None);
+        let result = extract_archive_sync(long_path, "/tmp/output".to_string(), None, None);
 
         assert!(result.is_err(), "should reject excessively long paths");
         assert!(
@@ -815,7 +859,7 @@ mod tests {
     #[test]
     fn test_extract_archive_sync_rejects_excessively_long_output_dir() {
         let long_path = "x".repeat(5000);
-        let result = extract_archive_sync("/tmp/test.tar".to_string(), long_path, None);
+        let result = extract_archive_sync("/tmp/test.tar".to_string(), long_path, None, None);
 
         assert!(result.is_err(), "should reject excessively long paths");
         assert!(
@@ -833,6 +877,7 @@ mod tests {
             "/tmp/valid_test_path.tar".to_string(),
             "/tmp/valid_output_path".to_string(),
             None,
+            None,
         );
 
         // If it fails, ensure it's not a path validation error
@@ -854,6 +899,7 @@ mod tests {
             "relative_test.tar".to_string(),
             "relative_output".to_string(),
             None,
+            None,
         );
 
         // If it fails, ensure it's not a path validation error
@@ -878,6 +924,7 @@ mod tests {
             "custom_test.tar".to_string(),
             "custom_output".to_string(),
             Some(&config),
+            None,
         );
 
         // If it fails, ensure it's not a path validation error

package/tests/extraction-options.test.js

@@ -0,0 +1,133 @@
+/**
+ * Tests for ExtractionOptions class
+ */
+const { describe, it, beforeEach, afterEach } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { ExtractionOptions, extractArchiveSync, createArchiveSync } = require('../index.js');
+
+function createTempDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'exarch-test-'));
+}
+
+function createValidArchive(archivePath, tempDir) {
+  const sourceDir = path.join(tempDir, 'source');
+  fs.mkdirSync(sourceDir);
+  fs.writeFileSync(path.join(sourceDir, 'hello.txt'), 'Hello, World!');
+  createArchiveSync(archivePath, [sourceDir]);
+}
+
+describe('ExtractionOptions', () => {
+  describe('constructor', () => {
+    it('should create options with skipDuplicates defaulting to true', () => {
+      const opts = new ExtractionOptions();
+      assert.strictEqual(opts.skipDuplicates, true);
+    });
+  });
+
+  describe('static default()', () => {
+    it('should return options equivalent to constructor', () => {
+      const opts = ExtractionOptions.default();
+      assert.strictEqual(opts.skipDuplicates, true);
+    });
+  });
+
+  describe('withSkipDuplicates()', () => {
+    it('should set skipDuplicates to false', () => {
+      const opts = new ExtractionOptions();
+      opts.withSkipDuplicates(false);
+      assert.strictEqual(opts.skipDuplicates, false);
+    });
+
+    it('should set skipDuplicates to true', () => {
+      const opts = new ExtractionOptions();
+      opts.withSkipDuplicates(false);
+      opts.withSkipDuplicates(true);
+      assert.strictEqual(opts.skipDuplicates, true);
+    });
+
+    it('should default to true when called with no argument', () => {
+      const opts = new ExtractionOptions();
+      opts.withSkipDuplicates(false);
+      opts.withSkipDuplicates();
+      assert.strictEqual(opts.skipDuplicates, true);
+    });
+  });
+
+  describe('build()', () => {
+    it('should return self for builder consistency', () => {
+      const opts = new ExtractionOptions();
+      const result = opts.build();
+      assert.strictEqual(result, opts);
+    });
+  });
+
+  describe('withAtomic()', () => {
+    it('should have atomic defaulting to false', () => {
+      const opts = new ExtractionOptions();
+      assert.strictEqual(opts.atomic, false);
+    });
+
+    it('should set atomic to true via withAtomic', () => {
+      const opts = new ExtractionOptions();
+      opts.withAtomic(true);
+      assert.strictEqual(opts.atomic, true);
+    });
+  });
+
+  describe('withSkipDuplicates() round-trip', () => {
+    it('should have skipDuplicates defaulting to true', () => {
+      const opts = new ExtractionOptions();
+      assert.strictEqual(opts.skipDuplicates, true);
+    });
+
+    it('should set skipDuplicates to false via withSkipDuplicates', () => {
+      const opts = new ExtractionOptions();
+      opts.withSkipDuplicates(false);
+      assert.strictEqual(opts.skipDuplicates, false);
+    });
+  });
+});
+
+describe('extractArchiveSync with ExtractionOptions', () => {
+  let tempDir;
+  let archivePath;
+  let outputDir;
+
+  beforeEach(() => {
+    tempDir = createTempDir();
+    archivePath = path.join(tempDir, 'test.tar.gz');
+    outputDir = path.join(tempDir, 'output');
+    fs.mkdirSync(outputDir);
+    createValidArchive(archivePath, tempDir);
+  });
+
+  afterEach(() => {
+    if (tempDir && fs.existsSync(tempDir)) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it('should extract with default ExtractionOptions', () => {
+    const opts = new ExtractionOptions();
+    const report = extractArchiveSync(archivePath, outputDir, null, opts);
+
+    assert.strictEqual(report.filesExtracted, 1);
+    assert.ok(report.bytesWritten >= 13);
+  });
+
+  it('should extract with skip_duplicates=false on non-duplicate archive', () => {
+    const opts = new ExtractionOptions();
+    opts.withSkipDuplicates(false);
+    const report = extractArchiveSync(archivePath, outputDir, null, opts);
+
+    assert.strictEqual(report.filesExtracted, 1);
+  });
+
+  it('should extract without options (null) as before', () => {
+    const report = extractArchiveSync(archivePath, outputDir, null, null);
+    assert.strictEqual(report.filesExtracted, 1);
+  });
+});