@litko/yara-x 0.2.1 → 0.3.0

package/README.md

@@ -244,11 +244,17 @@ const rules = compile(
     // Ignore specific modules
     ignoreModules: ["pe"],
 
-  :  // Error on potentially slow patterns
+    // Error on potentially slow patterns
     errorOnSlowPattern: true,
 
     // Error on potentially slow loops
     errorOnSlowLoop: true,
+
+    // Specify directories for include statements (v1.5.0+)
+    includeDirectories: ["./rules/includes", "./rules/common"],
+
+    // Enable or disable include statements (v1.5.0+)
+    enableIncludes: true,
   },
 );
 ```
@@ -359,6 +365,90 @@ if (warnings.length > 0) {
 }
 ```
 
+## Include Directories
+
+```javascript
+import { compile } from "@litko/yara-x";
+
+// Create a main rule that includes other rules
+const mainRule = `
+  include "common/strings.yar"
+  include "malware/pe_patterns.yar"
+
+  rule main_detection {
+    condition:
+      common_string_rule or pe_malware_rule
+  }
+`;
+
+// Compile with include directories
+const rules = compile(mainRule, {
+  includeDirectories: [
+    "./rules", // Base directory
+    "./rules/common", // Additional include path
+    "./rules/malware", // Another include path
+  ],
+});
+
+// Scan as usual
+const matches = rules.scan(Buffer.from("test data"));
+```
+
+## Scan Performance Options
+
+Control scanning behavior for better performance or safety.
+
+### Limiting Matches Per Pattern
+
+Prevent excessive memory usage by limiting the number of matches per pattern:
+
+```javascript
+import { compile } from "@litko/yara-x";
+
+const rules = compile(`
+  rule find_pattern {
+    strings:
+      $a = "pattern"
+    condition:
+      $a
+  }
+`);
+
+// Limit to 1000 matches per pattern
+rules.setMaxMatchesPerPattern(1000);
+
+// Scan data with many occurrences
+const data = Buffer.from("pattern ".repeat(10000));
+const matches = rules.scan(data);
+
+// Will only return up to 1000 matches per pattern
+console.log(`Found ${matches[0].matches.length} matches (limited to 1000)`);
+```
+
+### Memory-Mapped File Control
+
+Control whether to use memory-mapped files for scanning:
+
+```javascript
+import { compile } from "@litko/yara-x";
+
+const rules = compile(`
+  rule test {
+    strings:
+      $a = "test"
+    condition:
+      $a
+  }
+`);
+
+// Disable memory-mapped files for safer scanning
+// (slower but safer for untrusted files)
+rules.setUseMmap(false);
+
+// Scan file without memory mapping
+const matches = rules.scanFile("./sample.bin");
+```
+
 ## Performance Benchmarks
 
 `node-yara-x` delivers exceptional performance through intelligent scanner caching and optimized Rust implementation.
@@ -372,10 +462,10 @@ Methodology: Statistical analysis across multiple iterations with percentile rep
 
 | Rule Type      | Mean   | p50    | p95    | p99    |
 | -------------- | ------ | ------ | ------ | ------ |
-| Simple Rule    | 2.44ms | 2.42ms | 2.67ms | 3.00ms |
-| Complex Rule   | 2.79ms | 2.78ms | 3.00ms | 3.26ms |
-| Regex Rule     | 8.63ms | 8.63ms | 8.91ms | 9.34ms |
-| Multiple Rules | 2.42ms | 2.39ms | 2.69ms | 3.07ms |
+| Simple Rule    | 2.43ms | 2.41ms | 2.87ms | 3.11ms |
+| Complex Rule   | 2.57ms | 2.52ms | 2.96ms | 3.06ms |
+| Regex Rule     | 7.57ms | 7.47ms | 8.29ms | 8.70ms |
+| Multiple Rules | 2.05ms | 2.03ms | 2.24ms | 2.42ms |
 
 #### Scanning Performance by Data Size
 
@@ -383,10 +473,10 @@ Methodology: Statistical analysis across multiple iterations with percentile rep
 | --------- | -------------- | ----- | ---------- |
 | 64 bytes  | Simple         | 3μs   | ~21 MB/s   |
 | 100KB     | Simple         | 6μs   | ~16.7 GB/s |
-| 100KB     | Complex        | 71μs  | ~1.4 GB/s  |
+| 100KB     | Complex        | 73μs  | ~1.4 GB/s  |
 | 100KB     | Regex          | 7μs   | ~14.3 GB/s |
-| 100KB     | Multiple Rules | 71μs  | ~1.4 GB/s  |
-| 10MB      | Simple         | 196μs | ~51 GB/s   |
+| 100KB     | Multiple Rules | 73μs  | ~1.4 GB/s  |
+| 10MB      | Simple         | 204μs | ~49 GB/s   |
 
 #### Advanced Features Performance
 
@@ -394,7 +484,7 @@ Methodology: Statistical analysis across multiple iterations with percentile rep
 | ----------------- | ---- | -------------------------- |
 | Variable Scanning | 1μs  | Pre-compiled variables     |
 | Runtime Variables | 2μs  | Variables set at scan time |
-| Async Scanning    | 12μs | Non-blocking operations    |
+| Async Scanning    | 11μs | Non-blocking operations    |
 
 ## API Reference
 
@@ -407,7 +497,7 @@ Methodology: Statistical analysis across multiple iterations with percentile rep
 - `create()` - Creates an empty rules scanner to add rules incrementally.
 - `fromFile(rulePath: string, options?: CompilerOptions)` - Compiles yara rules from a file.
 
-### yarax Methods
+### YaraX Methods
 
 - `getWarnings()` - Get compiler warnings.
 - `scan(data: Buffer, variables?: Record<string, string | number>)` - Scan a buffer.
@@ -419,6 +509,21 @@ Methodology: Statistical analysis across multiple iterations with percentile rep
 - `addRuleSource(rules: string)` - Add rules from a string to an existing scanner.
 - `addRuleFile(filePath: string)` - Add rules from a file to an existing scanner.
 - `defineVariable(name: string, value: string)` - Define a variable for the YARA compiler.
+- `setMaxMatchesPerPattern(maxMatches: number)` - **(v1.7.0+)** Set the maximum number of matches per pattern.
+- `setUseMmap(useMmap: boolean)` - **(v1.6.0+)** Enable or disable memory-mapped files for scanning.
+
+### CompilerOptions
+
+- `defineVariables?: object` - Define global variables for the YARA rules.
+- `ignoreModules?: string[]` - List of module names to ignore during compilation.
+- `bannedModules?: BannedModule[]` - List of banned modules that cannot be used.
+- `features?: string[]` - List of features to enable for the YARA rules.
+- `relaxedReSyntax?: boolean` - Use relaxed regular expression syntax.
+- `conditionOptimization?: boolean` - Optimize conditions in the YARA rules.
+- `errorOnSlowPattern?: boolean` - Raise an error on slow patterns.
+- `errorOnSlowLoop?: boolean` - Raise an error on slow loops.
+- `includeDirectories?: string[]` - **(v1.5.0+)** Directories where the compiler should look for included files.
+- `enableIncludes?: boolean` - **(v1.5.0+)** Enable or disable include statements in YARA rules.
 
 ## Licenses
 

package/index.d.ts

@@ -1,29 +1,153 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
-/** YaraX struct represents the YARA rules and their associated data. */
+/**
+ * The main YARA-X scanner struct.
+ *
+ * This struct represents compiled YARA rules and provides methods for scanning
+ * data and files. It includes performance optimizations like scanner caching.
+ */
 export declare class YaraX {
+  /** Returns the compiler warnings generated during the compilation process. */
   getWarnings(): Array<CompilerWarning>
-  /** Scans the provided data using the compiled YARA rules. */
+  /**
+   * Sets the maximum number of matches per pattern.
+   *
+   * # Arguments
+   *
+   * * `max_matches` - The maximum number of matches per pattern
+   */
+  setMaxMatchesPerPattern(maxMatches: number): void
+  /**
+   * Sets whether to use memory-mapped files for scanning.
+   *
+   * # Arguments
+   *
+   * * `use_mmap` - Whether to use memory-mapped files
+   */
+  setUseMmap(useMmap: boolean): void
+  /**
+   * Scans the provided data using the compiled YARA rules.
+   *
+   * # Arguments
+   *
+   * * `env` - The N-API environment
+   * * `data` - The data to scan
+   * * `variables` - Optional variables to set for this scan
+   *
+   * # Returns
+   *
+   * A vector of matching rules
+   */
   scan(data: Buffer, variables?: Record<string, string | number>): Array<RuleMatch>
-  /** Scans a file using the compiled YARA rules. */
+  /**
+   * Scans a file using the compiled YARA rules.
+   *
+   * # Arguments
+   *
+   * * `env` - The N-API environment
+   * * `file_path` - Path to the file to scan
+   * * `variables` - Optional variables to set for this scan
+   *
+   * # Returns
+   *
+   * A vector of matching rules
+   */
   scanFile(filePath: string, variables?: Record<string, string | number>): Array<RuleMatch>
-  /** Emits a WASM file from the compiled YARA rules. */
+  /**
+   * Emits a WASM file from the compiled YARA rules.
+   *
+   * # Arguments
+   *
+   * * `output_path` - Path where the WASM file should be written
+   *
+   * # Returns
+   *
+   * Ok(()) on success, or an error if emission fails
+   */
   emitWasmFile(outputPath: string): void
-  /** Scans the provided data asynchronously using the compiled YARA rules. */
-  scanAsync(data: Buffer, variables?: object | undefined | null): Promise<unknown>
-  /** Scans a file asynchronously using the compiled YARA rules. */
-  scanFileAsync(filePath: string, variables?: object | undefined | null): Promise<unknown>
-  /** Emits a WASM file asynchronously from the compiled YARA rules. */
+  /**
+   * Scans the provided data asynchronously using the compiled YARA rules.
+   *
+   * # Arguments
+   *
+   * * `data` - The data to scan
+   * * `variables` - Optional variables to set for this scan
+   *
+   * # Returns
+   *
+   * An async task that resolves to a vector of matching rules
+   */
+  scanAsync(data: Buffer, variables?: object | undefined | null): Promise<Array<RuleMatch>>
+  /**
+   * Scans a file asynchronously using the compiled YARA rules.
+   *
+   * # Arguments
+   *
+   * * `file_path` - Path to the file to scan
+   * * `variables` - Optional variables to set for this scan
+   *
+   * # Returns
+   *
+   * An async task that resolves to a vector of matching rules
+   */
+  scanFileAsync(filePath: string, variables?: object | undefined | null): Promise<Array<RuleMatch>>
+  /**
+   * Emits a WASM file asynchronously from the compiled YARA rules.
+   *
+   * # Arguments
+   *
+   * * `output_path` - Path where the WASM file should be written
+   *
+   * # Returns
+   *
+   * An async task that completes when the WASM file is written
+   */
   emitWasmFileAsync(outputPath: string): Promise<unknown>
-  /** Adds a rule source to the YARA compiler. */
+  /**
+   * Adds a rule source to the YARA compiler.
+   *
+   * # Arguments
+   *
+   * * `rule_source` - The YARA rule source code to add
+   *
+   * # Returns
+   *
+   * Ok(()) on success, or an error if compilation fails
+   */
   addRuleSource(ruleSource: string): void
-  /** Adds a rule file to the YARA compiler. */
+  /**
+   * Adds a rule file to the YARA compiler.
+   *
+   * # Arguments
+   *
+   * * `file_path` - Path to the file containing YARA rules
+   *
+   * # Returns
+   *
+   * Ok(()) on success, or an error if reading or compilation fails
+   */
   addRuleFile(filePath: string): void
-  /** Defines a variable for the YARA compiler. */
+  /**
+   * Defines a variable for the YARA compiler.
+   *
+   * # Arguments
+   *
+   * * `name` - The variable name
+   * * `value` - The variable value
+   *
+   * # Returns
+   *
+   * Ok(()) on success, or an error if compilation fails
+   */
   defineVariable(name: string, value: string): void
 }
 
-/** BannedModule struct represents a module that is banned from being used in YARA rules. */
+/**
+ * Represents a module that is banned from being used in YARA rules.
+ *
+ * When a banned module is encountered, compilation will fail with the
+ * specified error message.
+ */
 export interface BannedModule {
   /** The name of the banned module. */
   name: string
@@ -33,13 +157,41 @@ export interface BannedModule {
   errorMessage: string
 }
 
-/** Compiles a YARA rule source string and returns a YaraX instance with the compiled rules. */
-export declare function compile(ruleSource: string, options?: CompilerOptions | undefined | null): YaraX
+/**
+ * Compiles a YARA rule source string and returns a YaraX instance with the compiled rules.
+ *
+ * # Arguments
+ *
+ * * `rule_source` - The YARA rule source code
+ * * `options` - Optional compiler options
+ *
+ * # Returns
+ *
+ * A YaraX instance with compiled rules
+ */
+export declare function compile(ruleSource: string, options?: CompilerOptionsType | undefined | null): YaraXImpl
 
-/** Compiles a YARA rule file to a WASM file. */
-export declare function compileFileToWasm(rulePath: string, outputPath: string, options?: CompilerOptions | undefined | null): void
+/**
+ * Compiles a YARA rule file to a WASM file.
+ *
+ * # Arguments
+ *
+ * * `rule_path` - Path to the file containing YARA rules
+ * * `output_path` - Path where the WASM file should be written
+ * * `options` - Optional compiler options
+ *
+ * # Returns
+ *
+ * Ok(()) on success, or an error if reading, compilation, or emission fails
+ */
+export declare function compileFileToWasm(rulePath: string, outputPath: string, options?: CompilerOptionsType | undefined | null): void
 
-/** CompilerError struct represents an error generated by the YARA compiler. */
+/**
+ * An error generated by the YARA compiler.
+ *
+ * Errors prevent successful compilation and must be resolved before
+ * the rules can be used.
+ */
 export interface CompilerError {
   /** The code of the error. */
   code: string
@@ -53,7 +205,12 @@ export interface CompilerError {
   column?: number
 }
 
-/** CompileResult struct represents the result of compiling YARA rules. */
+/**
+ * The result of compiling YARA rules.
+ *
+ * Contains any warnings or errors generated during the compilation process.
+ * If errors are present, the compilation failed.
+ */
 export interface CompileResult {
   /** Any warnings generated during the compilation process. */
   warnings: Array<CompilerWarning>
@@ -61,7 +218,12 @@ export interface CompileResult {
   errors: Array<CompilerError>
 }
 
-/** CompilerOptions struct represents the options for the YARA compiler. */
+/**
+ * Options for configuring the YARA compiler.
+ *
+ * These options control various aspects of rule compilation including
+ * module handling, optimization, and feature flags.
+ */
 export interface CompilerOptions {
   /** Defines global variables for the YARA rules. */
   defineVariables?: object
@@ -79,9 +241,18 @@ export interface CompilerOptions {
   errorOnSlowPattern?: boolean
   /** Whether to raise an error on slow loops. */
   errorOnSlowLoop?: boolean
+  /** A list of directories where the compiler should look for included files. */
+  includeDirectories?: Array<string>
+  /** Whether to enable include statements in YARA rules. */
+  enableIncludes?: boolean
 }
 
-/** CompilerWarning struct represents a warning generated by the YARA compiler. */
+/**
+ * A warning generated by the YARA compiler.
+ *
+ * Warnings indicate potential issues that don't prevent compilation
+ * but may indicate problems with the rules.
+ */
 export interface CompilerWarning {
   /** The code of the warning. */
   code: string
@@ -95,16 +266,49 @@ export interface CompilerWarning {
   column?: number
 }
 
-/** Compiles a YARA rule source string to a WASM file. */
-export declare function compileToWasm(ruleSource: string, outputPath: string, options?: CompilerOptions | undefined | null): void
+/**
+ * Compiles a YARA rule source string to a WASM file.
+ *
+ * # Arguments
+ *
+ * * `rule_source` - The YARA rule source code
+ * * `output_path` - Path where the WASM file should be written
+ * * `options` - Optional compiler options
+ *
+ * # Returns
+ *
+ * Ok(()) on success, or an error if compilation or emission fails
+ */
+export declare function compileToWasm(ruleSource: string, outputPath: string, options?: CompilerOptionsType | undefined | null): void
 
-/** Creates a new YaraX instance with empty rules and no source code. */
-export declare function create(): YaraX
+/**
+ * Creates a new YaraX instance with empty rules and no source code.
+ *
+ * # Returns
+ *
+ * A new YaraX instance with empty rules
+ */
+export declare function create(): YaraXImpl
 
-/** Creates a new YaraX instance from a file containing YARA rules. */
-export declare function fromFile(rulePath: string, options?: CompilerOptions | undefined | null): YaraX
+/**
+ * Creates a new YaraX instance from a file containing YARA rules.
+ *
+ * # Arguments
+ *
+ * * `rule_path` - Path to the file containing YARA rules
+ * * `options` - Optional compiler options
+ *
+ * # Returns
+ *
+ * A YaraX instance with compiled rules from the file
+ */
+export declare function fromFile(rulePath: string, options?: CompilerOptionsType | undefined | null): YaraXImpl
 
-/** MatchData struct represents a match found by a YARA rule. */
+/**
+ * Represents a match found by a YARA rule pattern.
+ *
+ * Contains information about where the match occurred and what data was matched.
+ */
 export interface MatchData {
   /** The offset of the match in the scanned data. */
   offset: number
@@ -116,7 +320,11 @@ export interface MatchData {
   identifier: string
 }
 
-/** RuleMatch struct represents a matching rule found during scanning. */
+/**
+ * Represents a matching rule found during scanning.
+ *
+ * Contains the rule's metadata, tags, and all pattern matches.
+ */
 export interface RuleMatch {
   /** The identifier of the rule that matched. */
   ruleIdentifier: string
@@ -130,8 +338,32 @@ export interface RuleMatch {
   matches: Array<MatchData>
 }
 
+/**
+ * Options for configuring scanning operations.
+ *
+ * These options control resource usage and performance characteristics
+ * during rule scanning.
+ */
+export interface ScanOptions {
+  /** Maximum number of matches per pattern. When a pattern reaches this limit, it won't produce more matches. */
+  maxMatchesPerPattern?: number
+  /** Whether to use memory-mapped files for scanning. Disabling this is safer but slower. */
+  useMmap?: boolean
+}
+
 /**
  * Compiles a YARA rule source string and returns any warnings or errors generated during the
  * compilation process.
+ *
+ * This function validates YARA rules without creating a scanner instance.
+ *
+ * # Arguments
+ *
+ * * `rule_source` - The YARA rule source code
+ * * `options` - Optional compiler options
+ *
+ * # Returns
+ *
+ * A CompileResult containing any warnings and errors
  */
-export declare function validate(ruleSource: string, options?: CompilerOptions | undefined | null): CompileResult
+export declare function validate(ruleSource: string, options?: CompilerOptionsType | undefined | null): CompileResult

package/index.js

@@ -66,7 +66,7 @@ const isMuslFromChildProcess = () => {
 function requireNative() {
   if (process.env.NAPI_RS_NATIVE_LIBRARY_PATH) {
     try {
-      nativeBinding = require(process.env.NAPI_RS_NATIVE_LIBRARY_PATH);
+      return require(process.env.NAPI_RS_NATIVE_LIBRARY_PATH);
     } catch (err) {
       loadErrors.push(err)
     }
@@ -78,7 +78,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-android-arm64')
+        const binding = require('@litko/yara-x-android-arm64')
+        const bindingPackageVersion = require('@litko/yara-x-android-arm64/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -89,7 +94,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-android-arm-eabi')
+        const binding = require('@litko/yara-x-android-arm-eabi')
+        const bindingPackageVersion = require('@litko/yara-x-android-arm-eabi/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -98,16 +108,39 @@ function requireNative() {
     }
   } else if (process.platform === 'win32') {
     if (process.arch === 'x64') {
+      if (process.report?.getReport?.()?.header?.osName?.startsWith?.('MINGW')) {
+        try {
+        return require('./yara-x.win32-x64-gnu.node')
+      } catch (e) {
+        loadErrors.push(e)
+      }
       try {
+        const binding = require('@litko/yara-x-win32-x64-gnu')
+        const bindingPackageVersion = require('@litko/yara-x-win32-x64-gnu/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
+      } catch (e) {
+        loadErrors.push(e)
+      }
+      } else {
+        try {
         return require('./yara-x.win32-x64-msvc.node')
       } catch (e) {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-win32-x64-msvc')
+        const binding = require('@litko/yara-x-win32-x64-msvc')
+        const bindingPackageVersion = require('@litko/yara-x-win32-x64-msvc/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
+      }
     } else if (process.arch === 'ia32') {
       try {
         return require('./yara-x.win32-ia32-msvc.node')
@@ -115,7 +148,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-win32-ia32-msvc')
+        const binding = require('@litko/yara-x-win32-ia32-msvc')
+        const bindingPackageVersion = require('@litko/yara-x-win32-ia32-msvc/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -126,7 +164,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-win32-arm64-msvc')
+        const binding = require('@litko/yara-x-win32-arm64-msvc')
+        const bindingPackageVersion = require('@litko/yara-x-win32-arm64-msvc/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -140,7 +183,12 @@ function requireNative() {
       loadErrors.push(e)
     }
     try {
-      return require('@litko/yara-x-darwin-universal')
+      const binding = require('@litko/yara-x-darwin-universal')
+      const bindingPackageVersion = require('@litko/yara-x-darwin-universal/package.json').version
+      if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+        throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+      }
+      return binding
     } catch (e) {
       loadErrors.push(e)
     }
@@ -151,7 +199,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-darwin-x64')
+        const binding = require('@litko/yara-x-darwin-x64')
+        const bindingPackageVersion = require('@litko/yara-x-darwin-x64/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -162,7 +215,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-darwin-arm64')
+        const binding = require('@litko/yara-x-darwin-arm64')
+        const bindingPackageVersion = require('@litko/yara-x-darwin-arm64/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -177,7 +235,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-freebsd-x64')
+        const binding = require('@litko/yara-x-freebsd-x64')
+        const bindingPackageVersion = require('@litko/yara-x-freebsd-x64/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -188,7 +251,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-freebsd-arm64')
+        const binding = require('@litko/yara-x-freebsd-arm64')
+        const bindingPackageVersion = require('@litko/yara-x-freebsd-arm64/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -204,7 +272,12 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          return require('@litko/yara-x-linux-x64-musl')
+          const binding = require('@litko/yara-x-linux-x64-musl')
+          const bindingPackageVersion = require('@litko/yara-x-linux-x64-musl/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
         } catch (e) {
           loadErrors.push(e)
         }
@@ -215,7 +288,12 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          return require('@litko/yara-x-linux-x64-gnu')
+          const binding = require('@litko/yara-x-linux-x64-gnu')
+          const bindingPackageVersion = require('@litko/yara-x-linux-x64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
         } catch (e) {
           loadErrors.push(e)
         }
@@ -228,7 +306,12 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          return require('@litko/yara-x-linux-arm64-musl')
+          const binding = require('@litko/yara-x-linux-arm64-musl')
+          const bindingPackageVersion = require('@litko/yara-x-linux-arm64-musl/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
         } catch (e) {
           loadErrors.push(e)
         }
@@ -239,7 +322,12 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          return require('@litko/yara-x-linux-arm64-gnu')
+          const binding = require('@litko/yara-x-linux-arm64-gnu')
+          const bindingPackageVersion = require('@litko/yara-x-linux-arm64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
         } catch (e) {
           loadErrors.push(e)
         }
@@ -252,7 +340,12 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          return require('@litko/yara-x-linux-arm-musleabihf')
+          const binding = require('@litko/yara-x-linux-arm-musleabihf')
+          const bindingPackageVersion = require('@litko/yara-x-linux-arm-musleabihf/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
         } catch (e) {
           loadErrors.push(e)
         }
@@ -263,7 +356,46 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          return require('@litko/yara-x-linux-arm-gnueabihf')
+          const binding = require('@litko/yara-x-linux-arm-gnueabihf')
+          const bindingPackageVersion = require('@litko/yara-x-linux-arm-gnueabihf/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      }
+    } else if (process.arch === 'loong64') {
+      if (isMusl()) {
+        try {
+          return require('./yara-x.linux-loong64-musl.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@litko/yara-x-linux-loong64-musl')
+          const bindingPackageVersion = require('@litko/yara-x-linux-loong64-musl/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
+        } catch (e) {
+          loadErrors.push(e)
+        }
+      } else {
+        try {
+          return require('./yara-x.linux-loong64-gnu.node')
+        } catch (e) {
+          loadErrors.push(e)
+        }
+        try {
+          const binding = require('@litko/yara-x-linux-loong64-gnu')
+          const bindingPackageVersion = require('@litko/yara-x-linux-loong64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
         } catch (e) {
           loadErrors.push(e)
         }
@@ -276,7 +408,12 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          return require('@litko/yara-x-linux-riscv64-musl')
+          const binding = require('@litko/yara-x-linux-riscv64-musl')
+          const bindingPackageVersion = require('@litko/yara-x-linux-riscv64-musl/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
         } catch (e) {
           loadErrors.push(e)
         }
@@ -287,7 +424,12 @@ function requireNative() {
           loadErrors.push(e)
         }
         try {
-          return require('@litko/yara-x-linux-riscv64-gnu')
+          const binding = require('@litko/yara-x-linux-riscv64-gnu')
+          const bindingPackageVersion = require('@litko/yara-x-linux-riscv64-gnu/package.json').version
+          if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+            throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+          }
+          return binding
         } catch (e) {
           loadErrors.push(e)
         }
@@ -299,7 +441,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-linux-ppc64-gnu')
+        const binding = require('@litko/yara-x-linux-ppc64-gnu')
+        const bindingPackageVersion = require('@litko/yara-x-linux-ppc64-gnu/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -310,7 +457,12 @@ function requireNative() {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-linux-s390x-gnu')
+        const binding = require('@litko/yara-x-linux-s390x-gnu')
+        const bindingPackageVersion = require('@litko/yara-x-linux-s390x-gnu/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -320,34 +472,49 @@ function requireNative() {
   } else if (process.platform === 'openharmony') {
     if (process.arch === 'arm64') {
       try {
-        return require('./yara-x.linux-arm64-ohos.node')
+        return require('./yara-x.openharmony-arm64.node')
       } catch (e) {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-linux-arm64-ohos')
+        const binding = require('@litko/yara-x-openharmony-arm64')
+        const bindingPackageVersion = require('@litko/yara-x-openharmony-arm64/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
     } else if (process.arch === 'x64') {
       try {
-        return require('./yara-x.linux-x64-ohos.node')
+        return require('./yara-x.openharmony-x64.node')
       } catch (e) {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-linux-x64-ohos')
+        const binding = require('@litko/yara-x-openharmony-x64')
+        const bindingPackageVersion = require('@litko/yara-x-openharmony-x64/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
     } else if (process.arch === 'arm') {
       try {
-        return require('./yara-x.linux-arm-ohos.node')
+        return require('./yara-x.openharmony-arm.node')
       } catch (e) {
         loadErrors.push(e)
       }
       try {
-        return require('@litko/yara-x-linux-arm-ohos')
+        const binding = require('@litko/yara-x-openharmony-arm')
+        const bindingPackageVersion = require('@litko/yara-x-openharmony-arm/package.json').version
+        if (bindingPackageVersion !== '0.3.0' && process.env.NAPI_RS_ENFORCE_VERSION_CHECK && process.env.NAPI_RS_ENFORCE_VERSION_CHECK !== '0') {
+          throw new Error(`Native binding package version mismatch, expected 0.3.0 but got ${bindingPackageVersion}. You can reinstall dependencies to fix this issue.`)
+        }
+        return binding
       } catch (e) {
         loadErrors.push(e)
       }
@@ -362,22 +529,32 @@ function requireNative() {
 nativeBinding = requireNative()
 
 if (!nativeBinding || process.env.NAPI_RS_FORCE_WASI) {
+  let wasiBinding = null
+  let wasiBindingError = null
   try {
-    nativeBinding = require('./yara-x.wasi.cjs')
+    wasiBinding = require('./yara-x.wasi.cjs')
+    nativeBinding = wasiBinding
   } catch (err) {
     if (process.env.NAPI_RS_FORCE_WASI) {
-      loadErrors.push(err)
+      wasiBindingError = err
     }
   }
   if (!nativeBinding) {
     try {
-      nativeBinding = require('@litko/yara-x-wasm32-wasi')
+      wasiBinding = require('@litko/yara-x-wasm32-wasi')
+      nativeBinding = wasiBinding
     } catch (err) {
       if (process.env.NAPI_RS_FORCE_WASI) {
+        wasiBindingError.cause = err
         loadErrors.push(err)
       }
     }
   }
+  if (process.env.NAPI_RS_FORCE_WASI === 'error' && !wasiBinding) {
+    const error = new Error('WASI binding not found and NAPI_RS_FORCE_WASI is set to error')
+    error.cause = wasiBindingError
+    throw error
+  }
 }
 
 if (!nativeBinding) {
@@ -386,7 +563,12 @@ if (!nativeBinding) {
       `Cannot find native binding. ` +
         `npm has a bug related to optional dependencies (https://github.com/npm/cli/issues/4828). ` +
         'Please try `npm i` again after removing both package-lock.json and node_modules directory.',
-      { cause: loadErrors }
+      {
+        cause: loadErrors.reduce((err, cur) => {
+          cur.cause = err
+          return cur
+        }),
+      },
     )
   }
   throw new Error(`Failed to load native binding`)

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@litko/yara-x",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "main": "index.js",
   "types": "index.d.ts",
-  "packageManager": "pnpm@10.13.1",
+  "packageManager": "pnpm@10.18.0",
   "napi": {
     "binaryName": "yara-x",
     "targets": [
@@ -14,9 +14,9 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@napi-rs/cli": "^3.0.0",
-    "@napi-rs/wasm-runtime": "^1.0.0",
-    "@types/node": "^22.13.10"
+    "@napi-rs/cli": "^3.3.0",
+    "@napi-rs/wasm-runtime": "^1.0.6",
+    "@types/node": "^24.6.2"
   },
   "engines": {
     "node": ">= 20"
@@ -59,8 +59,8 @@
     "rust"
   ],
   "optionalDependencies": {
-    "@litko/yara-x-darwin-x64": "0.2.1",
-    "@litko/yara-x-darwin-arm64": "0.2.1",
-    "@litko/yara-x-linux-x64-gnu": "0.2.1"
+    "@litko/yara-x-darwin-x64": "0.3.0",
+    "@litko/yara-x-darwin-arm64": "0.3.0",
+    "@litko/yara-x-linux-x64-gnu": "0.3.0"
   }
 }