exarch-rs 0.1.0 → 0.1.2

package/index.d.ts

@@ -1,287 +0,0 @@
-/**
- * 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;