exarch-rs 0.1.0

package/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "exarch-node"
+description = "Node.js bindings for exarch-core"
+version.workspace = true
+authors.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+repository.workspace = true
+homepage.workspace = true
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+exarch-core.workspace = true
+napi = { workspace = true, features = ["async", "napi4", "error_anyhow", "tokio_rt"] }
+napi-derive.workspace = true
+tokio.workspace = true
+
+[build-dependencies]
+napi-build.workspace = true
+
+[dev-dependencies]
+tokio = { workspace = true, features = ["macros", "rt"] }
+
+[lints]
+workspace = true

package/README.md

@@ -0,0 +1,235 @@
+# exarch-rs
+
+[![npm](https://img.shields.io/npm/v/exarch-rs)](https://www.npmjs.com/package/exarch-rs)
+[![Node](https://img.shields.io/node/v/exarch-rs)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
+[![CI](https://img.shields.io/github/actions/workflow/status/bug-ops/exarch/ci.yml?branch=main)](https://github.com/bug-ops/exarch/actions)
+[![License](https://img.shields.io/npm/l/exarch-rs)](../../LICENSE-MIT)
+
+Memory-safe archive extraction library for Node.js.
+
+> [!IMPORTANT]
+> **exarch** is designed as a secure replacement for vulnerable archive libraries like `tar-fs`, which has known CVEs with CVSS scores up to 9.4.
+
+This package provides Node.js bindings for [exarch-core](../exarch-core), a Rust library with built-in protection against common archive vulnerabilities.
+
+## Installation
+
+```bash
+# npm
+npm install exarch-rs
+
+# yarn
+yarn add exarch-rs
+
+# pnpm
+pnpm add exarch-rs
+
+# bun
+bun add exarch-rs
+```
+
+> [!NOTE]
+> This package includes TypeScript definitions. No need for separate `@types` package.
+
+## Requirements
+
+- Node.js >= 14
+
+## Quick Start
+
+```javascript
+const { extractArchive } = require('exarch-rs');
+
+// Async (recommended)
+const result = await extractArchive('archive.tar.gz', '/output/path');
+console.log(`Extracted ${result.filesExtracted} files`);
+```
+
+## Usage
+
+### Async API (Recommended)
+
+```javascript
+const { extractArchive } = require('exarch-rs');
+
+const result = await extractArchive('archive.tar.gz', '/output/path');
+
+console.log(`Files extracted: ${result.filesExtracted}`);
+console.log(`Bytes written: ${result.bytesWritten}`);
+console.log(`Duration: ${result.durationMs}ms`);
+```
+
+### Sync API
+
+```javascript
+const { extractArchiveSync } = require('exarch-rs');
+
+const result = extractArchiveSync('archive.tar.gz', '/output/path');
+console.log(`Extracted ${result.filesExtracted} files`);
+```
+
+> [!TIP]
+> Prefer the async API to avoid blocking the event loop during extraction.
+
+### ES Modules
+
+```javascript
+import { extractArchive } from 'exarch-rs';
+
+const result = await extractArchive('archive.tar.gz', '/output/path');
+```
+
+### TypeScript
+
+```typescript
+import { extractArchive, SecurityConfig, ExtractionReport } from 'exarch-rs';
+
+const result: ExtractionReport = await extractArchive('archive.tar.gz', '/output/path');
+console.log(`Extracted ${result.filesExtracted} files`);
+```
+
+### Custom Security Configuration
+
+```typescript
+import { extractArchive, SecurityConfig } from 'exarch-rs';
+
+const config = new SecurityConfig()
+  .maxFileSize(100 * 1024 * 1024)   // 100 MB per file
+  .maxTotalSize(1024 * 1024 * 1024) // 1 GB total
+  .maxFileCount(10_000);             // Max 10k files
+
+const result = await extractArchive('archive.tar.gz', '/output', config);
+```
+
+### Error Handling
+
+```javascript
+const { extractArchive } = require('exarch-rs');
+
+try {
+  const result = await extractArchive('archive.tar.gz', '/output');
+  console.log(`Success: ${result.filesExtracted} files`);
+} catch (error) {
+  // Error codes: PATH_TRAVERSAL, SYMLINK_ESCAPE, ZIP_BOMB, QUOTA_EXCEEDED, etc.
+  console.error(`Extraction failed: ${error.message}`);
+}
+```
+
+## API
+
+### `extractArchive(archivePath, outputDir, config?)`
+
+Extract an archive asynchronously with security validation.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `archivePath` | `string` | Path to the archive file |
+| `outputDir` | `string` | Directory where files will be extracted |
+| `config` | `SecurityConfig` | Optional security configuration |
+
+**Returns:** `Promise<ExtractionReport>`
+
+### `extractArchiveSync(archivePath, outputDir, config?)`
+
+Synchronous version. Blocks the event loop until extraction completes.
+
+**Returns:** `ExtractionReport`
+
+### `ExtractionReport`
+
+```typescript
+interface ExtractionReport {
+  filesExtracted: number;  // Number of files extracted
+  bytesWritten: number;    // Total bytes written
+  durationMs: number;      // Extraction duration in milliseconds
+}
+```
+
+### `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)
+```
+
+## Security Features
+
+The library provides built-in protection against:
+
+| Protection | Description |
+|------------|-------------|
+| Path traversal | Blocks `../` and absolute paths |
+| Symlink attacks | Prevents symlinks escaping extraction directory |
+| Hardlink attacks | Validates hardlink targets |
+| Zip bombs | Detects high compression ratios |
+| Permission sanitization | Strips setuid/setgid bits |
+| Size limits | Enforces file and total size limits |
+
+> [!CAUTION]
+> Unlike many Node.js archive libraries, exarch applies security validation by default.
+
+## Supported Formats
+
+| Format | Extensions |
+|--------|------------|
+| TAR | `.tar` |
+| TAR+GZIP | `.tar.gz`, `.tgz` |
+| TAR+BZIP2 | `.tar.bz2`, `.tbz2` |
+| TAR+XZ | `.tar.xz`, `.txz` |
+| TAR+ZSTD | `.tar.zst`, `.tzst` |
+| ZIP | `.zip` |
+
+## Comparison with tar-fs
+
+```javascript
+// UNSAFE - tar-fs has known vulnerabilities
+const tar = require('tar-fs');
+const fs = require('fs');
+fs.createReadStream('archive.tar')
+  .pipe(tar.extract('/output'));  // May extract outside target directory!
+
+// SAFE - exarch-rs validates all paths
+const { extractArchive } = require('exarch-rs');
+await extractArchive('archive.tar', '/output');  // Protected by default
+```
+
+## Development
+
+This package is built using [napi-rs](https://napi.rs/).
+
+```bash
+# Clone repository
+git clone https://github.com/bug-ops/exarch
+cd exarch/crates/exarch-node
+
+# Install dependencies
+npm install
+
+# Build native module
+npm run build
+
+# Run tests
+npm test
+```
+
+## Related Packages
+
+- [exarch-core](../exarch-core) — Core Rust library
+- [exarch (PyPI)](../exarch-python) — Python bindings
+
+## License
+
+Licensed under either of:
+
+- Apache License, Version 2.0 ([LICENSE-APACHE](../../LICENSE-APACHE))
+- MIT License ([LICENSE-MIT](../../LICENSE-MIT))
+
+at your option.

package/build.rs

@@ -0,0 +1,5 @@
+//! Build script for napi-rs bindings.
+
+fn main() {
+    napi_build::setup();
+}

package/index.d.ts

@@ -0,0 +1,287 @@
+/**
+ * exarch - Memory-safe archive extraction library
+ *
+ * Provides secure archive extraction with built-in protection against:
+ * - Path traversal attacks
+ * - Symlink escape attacks
+ * - Hardlink escape attacks
+ * - Zip bomb attacks
+ * - Invalid file permissions
+ * - Resource quota violations
+ */
+
+/**
+ * Security configuration for archive extraction.
+ *
+ * All security features default to deny (secure-by-default policy).
+ *
+ * @example
+ * ```typescript
+ * // Use secure defaults
+ * const config = new SecurityConfig();
+ *
+ * // Customize with builder pattern
+ * const config = new SecurityConfig()
+ *   .maxFileSize(100 * 1024 * 1024)
+ *   .allowSymlinks(true);
+ *
+ * // Use permissive configuration for trusted archives
+ * const config = SecurityConfig.permissive();
+ * ```
+ */
+export class SecurityConfig {
+  /**
+   * Creates a new SecurityConfig with secure defaults.
+   */
+  constructor();
+
+  /**
+   * Creates a SecurityConfig with secure defaults.
+   * Equivalent to calling the constructor.
+   */
+  static default(): SecurityConfig;
+
+  /**
+   * Creates a permissive configuration for trusted archives.
+   *
+   * Enables: symlinks, hardlinks, absolute paths, world-writable files.
+   * Use only for archives from trusted sources.
+   */
+  static permissive(): SecurityConfig;
+
+  // Builder pattern methods (chainable)
+
+  /**
+   * Sets the maximum file size in bytes.
+   * Default: 50 MB (52,428,800 bytes)
+   */
+  maxFileSize(size: number): this;
+
+  /**
+   * Sets the maximum total size in bytes.
+   * Default: 500 MB (524,288,000 bytes)
+   */
+  maxTotalSize(size: number): this;
+
+  /**
+   * Sets the maximum compression ratio.
+   * Default: 100.0
+   *
+   * @throws Error if ratio is not a positive finite number
+   */
+  maxCompressionRatio(ratio: number): this;
+
+  /**
+   * Sets the maximum file count.
+   * Default: 10,000
+   */
+  maxFileCount(count: number): this;
+
+  /**
+   * Sets the maximum path depth.
+   * Default: 32
+   */
+  maxPathDepth(depth: number): this;
+
+  /**
+   * Allows or denies symlinks.
+   * Default: false (deny)
+   */
+  allowSymlinks(allow?: boolean): this;
+
+  /**
+   * Allows or denies hardlinks.
+   * Default: false (deny)
+   */
+  allowHardlinks(allow?: boolean): this;
+
+  /**
+   * Allows or denies absolute paths.
+   * Default: false (deny)
+   */
+  allowAbsolutePaths(allow?: boolean): this;
+
+  /**
+   * Allows or denies world-writable files.
+   * Default: false (deny)
+   */
+  allowWorldWritable(allow?: boolean): this;
+
+  /**
+   * Sets whether to preserve permissions from archive.
+   * Default: false
+   */
+  preservePermissions(preserve?: boolean): this;
+
+  /**
+   * Adds an allowed file extension.
+   *
+   * @throws Error if extension exceeds maximum length or contains null bytes
+   */
+  addAllowedExtension(ext: string): this;
+
+  /**
+   * Adds a banned path component.
+   *
+   * @throws Error if component exceeds maximum length or contains null bytes
+   */
+  addBannedComponent(component: string): this;
+
+  /**
+   * Finalizes the configuration (for API consistency).
+   *
+   * This method is provided for builder pattern consistency but is optional.
+   * The configuration is always valid and can be used directly.
+   */
+  build(): this;
+
+  // Validation methods
+
+  /**
+   * Checks if a path component is allowed.
+   */
+  isPathComponentAllowed(component: string): boolean;
+
+  /**
+   * Checks if a file extension is allowed.
+   */
+  isExtensionAllowed(extension: string): boolean;
+
+  // Property getters
+
+  /** Maximum file size in bytes */
+  readonly maxFileSize: number;
+
+  /** Maximum total extraction size in bytes */
+  readonly maxTotalSize: number;
+
+  /** Maximum compression ratio */
+  readonly maxCompressionRatio: number;
+
+  /** Maximum number of files */
+  readonly maxFileCount: number;
+
+  /** Maximum path depth */
+  readonly maxPathDepth: number;
+
+  /** Whether file permissions are preserved from archive */
+  readonly preservePermissions: boolean;
+
+  /** Whether symlinks are allowed */
+  readonly allowSymlinks: boolean;
+
+  /** Whether hardlinks are allowed */
+  readonly allowHardlinks: boolean;
+
+  /** Whether absolute paths are allowed */
+  readonly allowAbsolutePaths: boolean;
+
+  /** Whether world-writable files are allowed */
+  readonly allowWorldWritable: boolean;
+
+  /** List of allowed file extensions */
+  readonly allowedExtensions: string[];
+
+  /** List of banned path components */
+  readonly bannedPathComponents: string[];
+}
+
+/**
+ * Report of an archive extraction operation.
+ *
+ * Contains statistics and metadata about the extraction process.
+ */
+export interface ExtractionReport {
+  /** Number of files successfully extracted */
+  filesExtracted: number;
+
+  /** Number of directories created */
+  directoriesCreated: number;
+
+  /** Number of symlinks created */
+  symlinksCreated: number;
+
+  /** Total bytes written to disk */
+  bytesWritten: number;
+
+  /** Extraction duration in milliseconds */
+  durationMs: number;
+
+  /** Number of files skipped due to security checks */
+  filesSkipped: number;
+
+  /** List of warning messages */
+  warnings: string[];
+}
+
+/**
+ * Extract an archive to the specified directory (async).
+ *
+ * This function provides secure archive extraction with configurable
+ * security policies. By default, it uses a restrictive security
+ * configuration that blocks symlinks, hardlinks, absolute paths, and
+ * enforces resource quotas.
+ *
+ * Error codes in exception messages:
+ * - `PATH_TRAVERSAL`: Path traversal attempt detected
+ * - `SYMLINK_ESCAPE`: Symlink points outside extraction directory
+ * - `HARDLINK_ESCAPE`: Hardlink target outside extraction directory
+ * - `ZIP_BOMB`: Potential zip bomb detected
+ * - `INVALID_PERMISSIONS`: File permissions are invalid or unsafe
+ * - `QUOTA_EXCEEDED`: Resource quota exceeded
+ * - `SECURITY_VIOLATION`: Security policy violation
+ * - `UNSUPPORTED_FORMAT`: Archive format not supported
+ * - `INVALID_ARCHIVE`: Archive is corrupted
+ * - `IO_ERROR`: I/O operation failed
+ *
+ * @param archivePath - Path to the archive file
+ * @param outputDir - Directory where files will be extracted
+ * @param config - Optional SecurityConfig (uses secure defaults if omitted)
+ * @returns Promise resolving to ExtractionReport with extraction statistics
+ * @throws Error for security violations or I/O errors
+ *
+ * @example
+ * ```typescript
+ * // Use secure defaults
+ * const report = await extractArchive('archive.tar.gz', '/tmp/output');
+ * console.log(`Extracted ${report.filesExtracted} files`);
+ *
+ * // Customize security settings
+ * const config = new SecurityConfig().maxFileSize(100 * 1024 * 1024);
+ * const report = await extractArchive('archive.tar.gz', '/tmp/output', config);
+ * ```
+ */
+export function extractArchive(
+  archivePath: string,
+  outputDir: string,
+  config?: SecurityConfig
+): Promise<ExtractionReport>;
+
+/**
+ * Extract an archive to the specified directory (sync).
+ *
+ * Synchronous version of extractArchive. Blocks the event loop until
+ * extraction completes. Prefer the async version for most use cases.
+ *
+ * @param archivePath - Path to the archive file
+ * @param outputDir - Directory where files will be extracted
+ * @param config - Optional SecurityConfig (uses secure defaults if omitted)
+ * @returns ExtractionReport with extraction statistics
+ * @throws Error for security violations or I/O errors
+ *
+ * @example
+ * ```typescript
+ * // Use secure defaults
+ * const report = extractArchiveSync('archive.tar.gz', '/tmp/output');
+ * console.log(`Extracted ${report.filesExtracted} files`);
+ *
+ * // Customize security settings
+ * const config = new SecurityConfig().maxFileSize(100 * 1024 * 1024);
+ * const report = extractArchiveSync('archive.tar.gz', '/tmp/output', config);
+ * ```
+ */
+export function extractArchiveSync(
+  archivePath: string,
+  outputDir: string,
+  config?: SecurityConfig
+): ExtractionReport;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "exarch-rs",
+  "version": "0.1.0",
+  "description": "Memory-safe archive extraction library",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "keywords": [
+    "archive",
+    "extraction",
+    "security",
+    "tar",
+    "zip",
+    "napi-rs",
+    "rust"
+  ],
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bug-ops/exarch"
+  },
+  "napi": {
+    "name": "exarch-rs",
+    "triples": {
+      "defaults": true
+    }
+  },
+  "scripts": {
+    "build": "napi build --platform --release",
+    "build:debug": "napi build --platform"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3.0.0"
+  },
+  "engines": {
+    "node": ">= 14"
+  }
+}