exarch-rs 0.1.1 → 0.1.2

package/index.d.ts

@@ -1,657 +0,0 @@
-/* auto-generated by NAPI-RS */
-/* eslint-disable */
-/**
- * Configuration for archive creation operations.
- *
- * Controls how archives are created from filesystem sources, including
- * security options, compression settings, and file filtering.
- *
- * # Defaults
- *
- * | Setting | Default Value |
- * |---------|--------------|
- * | `compression_level` | 6 (balanced) |
- * | `preserve_permissions` | true |
- * | `follow_symlinks` | false (secure) |
- * | `include_hidden` | false |
- * | `max_file_size` | None (no limit) |
- * | `exclude_patterns` | `[".git", ".DS_Store", "*.tmp"]` |
- */
-export declare class CreationConfig {
-  /** Creates a new `CreationConfig` with secure defaults. */
-  constructor()
-  /**
-   * Creates a `CreationConfig` with secure defaults.
-   *
-   * This is equivalent to calling `new CreationConfig()`.
-   */
-  static default(): CreationConfig
-  /**
-   * Sets the compression level (1-9).
-   *
-   * Higher values provide better compression but slower speed.
-   * Default: 6 (balanced).
-   *
-   * # Errors
-   *
-   * Returns error if level is not in range 1-9.
-   */
-  setCompressionLevel(level: number): this
-  /**
-   * Sets whether to preserve file permissions from source.
-   *
-   * Default: true.
-   */
-  setPreservePermissions(preserve?: boolean | undefined | null): this
-  /**
-   * Sets whether to follow symlinks when adding files.
-   *
-   * Default: false (store symlinks as symlinks).
-   *
-   * Security note: Following symlinks may include unintended files
-   * from outside the source directory.
-   */
-  setFollowSymlinks(follow?: boolean | undefined | null): this
-  /**
-   * Sets whether to include hidden files (files starting with '.').
-   *
-   * Default: false.
-   */
-  setIncludeHidden(include?: boolean | undefined | null): this
-  /**
-   * Sets maximum size for a single file in bytes.
-   *
-   * Files larger than this limit will be skipped.
-   *
-   * # Errors
-   *
-   * Returns error if size is negative.
-   */
-  setMaxFileSize(size: number): this
-  /**
-   * Adds an exclude pattern.
-   *
-   * Files matching this pattern will be skipped.
-   *
-   * # Errors
-   *
-   * Returns error if pattern contains null bytes.
-   */
-  addExcludePattern(pattern: string): this
-  /** Finalizes the configuration (for API consistency). */
-  build(): this
-  /** Compression level (1-9). */
-  get compressionLevel(): number | null
-  /** Whether to preserve permissions. */
-  get preservePermissions(): boolean
-  /** Whether to follow symlinks. */
-  get followSymlinks(): boolean
-  /** Whether to include hidden files. */
-  get includeHidden(): boolean
-  /** Maximum file size in bytes. */
-  get maxFileSize(): number | null
-  /** List of exclude patterns. */
-  get excludePatterns(): Array<string>
-}
-
-/**
- * Security configuration for archive extraction.
- *
- * All security features default to deny (secure-by-default policy).
- *
- * # Defaults
- *
- * | Setting | Default Value |
- * |---------|--------------|
- * | `max_file_size` | 50 MB (52,428,800 bytes) |
- * | `max_total_size` | 500 MB (524,288,000 bytes) |
- * | `max_compression_ratio` | 100.0 |
- * | `max_file_count` | 10,000 |
- * | `max_path_depth` | 32 |
- * | `allow_symlinks` | false |
- * | `allow_hardlinks` | false |
- * | `allow_absolute_paths` | false |
- * | `allow_world_writable` | false |
- * | `preserve_permissions` | false |
- * | `allowed_extensions` | empty (all allowed) |
- * | `banned_path_components` | `.git`, `.ssh` |
- */
-export declare class SecurityConfig {
-  /** Creates a new `SecurityConfig` with secure defaults. */
-  constructor()
-  /**
-   * Creates a `SecurityConfig` with secure defaults.
-   *
-   * This is equivalent to calling `new SecurityConfig()`.
-   */
-  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
-  /**
-   * Sets the maximum file size in bytes.
-   *
-   * # Errors
-   *
-   * Returns error if size is negative.
-   */
-  setMaxFileSize(size: number): this
-  /**
-   * Sets the maximum total size in bytes.
-   *
-   * # Errors
-   *
-   * Returns error if size is negative.
-   */
-  setMaxTotalSize(size: number): this
-  /**
-   * Sets the maximum compression ratio.
-   *
-   * # Errors
-   *
-   * Returns error if ratio is not a positive finite number.
-   */
-  setMaxCompressionRatio(ratio: number): this
-  /** Sets the maximum file count. */
-  setMaxFileCount(count: number): this
-  /** Sets the maximum path depth. */
-  setMaxPathDepth(depth: number): this
-  /** Allows or denies symlinks. */
-  setAllowSymlinks(allow?: boolean | undefined | null): this
-  /** Allows or denies hardlinks. */
-  setAllowHardlinks(allow?: boolean | undefined | null): this
-  /** Allows or denies absolute paths. */
-  setAllowAbsolutePaths(allow?: boolean | undefined | null): this
-  /** Allows or denies world-writable files. */
-  setAllowWorldWritable(allow?: boolean | undefined | null): this
-  /** Sets whether to preserve permissions from archive. */
-  setPreservePermissions(preserve?: boolean | undefined | null): this
-  /**
-   * Adds an allowed file extension.
-   *
-   * # Errors
-   *
-   * Returns error if extension exceeds maximum length or contains null
-   * bytes.
-   */
-  addAllowedExtension(ext: string): this
-  /**
-   * Adds a banned path component.
-   *
-   * # Errors
-   *
-   * Returns 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
-  /** Checks if a path component is allowed. */
-  isPathComponentAllowed(component: string): boolean
-  /** Checks if a file extension is allowed. */
-  isExtensionAllowed(extension: string): boolean
-  /** Maximum file size in bytes. */
-  get maxFileSize(): number
-  /** Maximum total size in bytes. */
-  get maxTotalSize(): number
-  /** Maximum compression ratio. */
-  get maxCompressionRatio(): number
-  /** Maximum file count. */
-  get maxFileCount(): number
-  /** Maximum path depth. */
-  get maxPathDepth(): number
-  /** Whether to preserve permissions from archive. */
-  get preservePermissions(): boolean
-  /** Whether symlinks are allowed. */
-  get allowSymlinks(): boolean
-  /** Whether hardlinks are allowed. */
-  get allowHardlinks(): boolean
-  /** Whether absolute paths are allowed. */
-  get allowAbsolutePaths(): boolean
-  /** Whether world-writable files are allowed. */
-  get allowWorldWritable(): boolean
-  /**
-   * List of allowed file extensions.
-   *
-   * Note: This getter clones the underlying data. For performance-critical
-   * code that only needs to count or check membership, use
-   * `getAllowedExtensionsCount()` or `hasAllowedExtension()` instead.
-   */
-  get allowedExtensions(): Array<string>
-  /** Returns the number of allowed extensions. */
-  getAllowedExtensionsCount(): number
-  /** Checks if a specific extension is in the allowed list. */
-  hasAllowedExtension(ext: string): boolean
-  /**
-   * List of banned path components.
-   *
-   * Note: This getter clones the underlying data. For performance-critical
-   * code that only needs to count or check membership, use
-   * `getBannedPathComponentsCount()` or `hasBannedPathComponent()` instead.
-   */
-  get bannedPathComponents(): Array<string>
-  /** Returns the number of banned path components. */
-  getBannedPathComponentsCount(): number
-  /** Checks if a specific component is in the banned list. */
-  hasBannedPathComponent(component: string): boolean
-}
-
-/**
- * Single entry in archive manifest.
- *
- * Contains metadata about a file, directory, symlink, or hardlink
- * without extracting it to disk.
- */
-export interface ArchiveEntry {
-  /** Entry path (relative, as stored in archive). */
-  path: string
-  /** Entry type ("File", "Directory", "Symlink", "Hardlink"). */
-  entryType: string
-  /** Uncompressed size in bytes (0 for directories). */
-  size: number
-  /** Compressed size in bytes (if available, ZIP only). */
-  compressedSize?: number
-  /** File permissions (Unix mode). */
-  mode?: number
-  /** Modification time (milliseconds since Unix epoch). */
-  modified?: number
-  /** Symlink target (if `entry_type` is "Symlink"). */
-  symlinkTarget?: string
-  /** Hardlink target (if `entry_type` is "Hardlink"). */
-  hardlinkTarget?: string
-}
-
-/**
- * Complete manifest of archive contents.
- *
- * Generated by `listArchive()`, contains metadata about all entries
- * without extracting them to disk.
- */
-export interface ArchiveManifest {
-  /** All entries in the archive (files, dirs, symlinks, hardlinks). */
-  entries: Array<ArchiveEntry>
-  /** Total number of entries. */
-  totalEntries: number
-  /** Total uncompressed size in bytes. */
-  totalSize: number
-  /** Archive format (e.g., `TarGz`, `Zip`). */
-  format: string
-}
-
-/**
- * Create an archive from source files and directories (async).
- *
- * # Arguments
- *
- * * `output_path` - Path to output archive file
- * * `sources` - Array of source files/directories to include
- * * `config` - Optional `CreationConfig` (uses defaults if omitted)
- *
- * # Returns
- *
- * Promise resolving to `CreationReport` with creation statistics
- *
- * # Errors
- *
- * Returns error if path validation fails, archive creation fails, or I/O
- * errors occur.
- *
- * # Examples
- *
- * ```javascript
- * // Use defaults
- * const report = await createArchive('output.tar.gz', ['source_dir/']);
- * console.log(`Created archive with ${report.filesAdded} files`);
- *
- * // Customize configuration
- * const config = new CreationConfig().compressionLevel(9);
- * const report = await createArchive('output.tar.gz', ['src/'], config);
- * ```
- */
-export declare function createArchive(outputPath: string, sources: Array<string>, config?: CreationConfig | undefined | null): Promise<CreationReport>
-
-/**
- * Create an archive from source files and directories (sync).
- *
- * Synchronous version of `createArchive`. Blocks the event loop until
- * creation completes. Prefer the async version for most use cases.
- *
- * # Arguments
- *
- * * `output_path` - Path to output archive file
- * * `sources` - Array of source files/directories to include
- * * `config` - Optional `CreationConfig` (uses defaults if omitted)
- *
- * # Returns
- *
- * `CreationReport` with creation statistics
- *
- * # Errors
- *
- * Returns error if path validation fails, archive creation fails, or I/O
- * errors occur.
- *
- * # Examples
- *
- * ```javascript
- * // Use defaults
- * const report = createArchiveSync('output.tar.gz', ['source_dir/']);
- * console.log(`Created archive with ${report.filesAdded} files`);
- * ```
- */
-export declare function createArchiveSync(outputPath: string, sources: Array<string>, config?: CreationConfig | undefined | null): CreationReport
-
-/**
- * Report of an archive creation operation.
- *
- * Contains statistics and metadata about the creation process.
- */
-export interface CreationReport {
-  /** Number of files added to the archive. */
-  filesAdded: number
-  /** Number of directories added to the archive. */
-  directoriesAdded: number
-  /** Number of symlinks added to the archive. */
-  symlinksAdded: number
-  /** Total bytes written to the archive (uncompressed). */
-  bytesWritten: number
-  /** Total bytes in the final archive (compressed). */
-  bytesCompressed: number
-  /** Duration of the creation operation in milliseconds. */
-  durationMs: number
-  /** Number of files skipped (due to filters or errors). */
-  filesSkipped: number
-  /** Warnings generated during creation. */
-  warnings: Array<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.
- *
- * # Security Considerations
- *
- * ## Thread Safety and TOCTOU
- *
- * The extraction runs on a libuv thread pool worker thread. This creates
- * a Time-Of-Check-Time-Of-Use (TOCTOU) race condition where the archive
- * file could be modified between validation and extraction. This is an
- * accepted tradeoff for async performance. For untrusted archives, ensure
- * exclusive access to the archive file during extraction.
- *
- * ## Input Validation
- *
- * - Paths containing null bytes are rejected (security)
- * - Paths exceeding 4096 bytes are rejected (`DoS` prevention)
- * - All validation happens at the Node.js boundary before calling core library
- *
- * # Arguments
- *
- * * `archive_path` - Path to the archive file
- * * `output_dir` - Directory where files will be extracted
- * * `config` - Optional `SecurityConfig` (uses secure defaults if omitted)
- *
- * # Returns
- *
- * Promise resolving to `ExtractionReport` with extraction statistics
- *
- * # Errors
- *
- * Returns error for security violations or I/O errors. Error messages are
- * prefixed with error codes for discrimination in JavaScript:
- *
- * - `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
- *
- * # Examples
- *
- * ```javascript
- * // 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 declare function extractArchive(archivePath: string, outputDir: string, config?: SecurityConfig | undefined | null): 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.
- *
- * # Arguments
- *
- * * `archive_path` - Path to the archive file
- * * `output_dir` - Directory where files will be extracted
- * * `config` - Optional `SecurityConfig` (uses secure defaults if omitted)
- *
- * # Returns
- *
- * `ExtractionReport` with extraction statistics
- *
- * # Errors
- *
- * Returns error for security violations or I/O errors. See `extract_archive`
- * for error code documentation.
- *
- * # Examples
- *
- * ```javascript
- * // 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 declare function extractArchiveSync(archivePath: string, outputDir: string, config?: SecurityConfig | undefined | null): ExtractionReport
-
-/**
- * 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: Array<string>
-}
-
-/**
- * List archive contents without extracting (async).
- *
- * # Arguments
- *
- * * `archive_path` - Path to archive file
- * * `config` - Optional `SecurityConfig` (uses secure defaults if omitted)
- *
- * # Returns
- *
- * Promise resolving to `ArchiveManifest` with entry metadata
- *
- * # Errors
- *
- * Returns error if path validation fails, archive is invalid, or I/O errors
- * occur.
- *
- * # Examples
- *
- * ```javascript
- * const manifest = await listArchive('archive.tar.gz');
- * for (const entry of manifest.entries) {
- *     console.log(`${entry.path}: ${entry.size} bytes`);
- * }
- * ```
- */
-export declare function listArchive(archivePath: string, config?: SecurityConfig | undefined | null): Promise<ArchiveManifest>
-
-/**
- * List archive contents without extracting (sync).
- *
- * Synchronous version of `listArchive`. Blocks the event loop until
- * listing completes. Prefer the async version for most use cases.
- *
- * # Arguments
- *
- * * `archive_path` - Path to archive file
- * * `config` - Optional `SecurityConfig` (uses secure defaults if omitted)
- *
- * # Returns
- *
- * `ArchiveManifest` with entry metadata
- *
- * # Errors
- *
- * Returns error if path validation fails, archive is invalid, or I/O errors
- * occur.
- *
- * # Examples
- *
- * ```javascript
- * const manifest = listArchiveSync('archive.tar.gz');
- * for (const entry of manifest.entries) {
- *     console.log(`${entry.path}: ${entry.size} bytes`);
- * }
- * ```
- */
-export declare function listArchiveSync(archivePath: string, config?: SecurityConfig | undefined | null): ArchiveManifest
-
-/** Single verification issue. */
-export interface VerificationIssue {
-  /** Issue severity level ("Critical", "High", "Medium", "Low", "Info"). */
-  severity: string
-  /** Issue category (`PathTraversal`, `SymlinkEscape`, etc.). */
-  category: string
-  /** Entry path that triggered issue (if applicable). */
-  entryPath?: string
-  /** Human-readable description. */
-  message: string
-  /** Optional context (compression ratio, target path, etc.). */
-  context?: string
-}
-
-/**
- * Result of archive verification.
- *
- * Generated by `verifyArchive()`, contains security and integrity checks
- * performed without extracting files to disk.
- */
-export interface VerificationReport {
-  /** Overall verification status ("Pass", "Fail", "Warning"). */
-  status: string
-  /** Integrity check result ("Pass", "Fail", "Warning", "Skipped"). */
-  integrityStatus: string
-  /** Security check result ("Pass", "Fail", "Warning", "Skipped"). */
-  securityStatus: string
-  /** List of all issues found (sorted by severity). */
-  issues: Array<VerificationIssue>
-  /** Total entries scanned. */
-  totalEntries: number
-  /** Entries flagged as suspicious. */
-  suspiciousEntries: number
-  /** Total uncompressed size. */
-  totalSize: number
-  /** Archive format (e.g., `TarGz`, `Zip`). */
-  format: string
-}
-
-/**
- * Verify archive integrity and security (async).
- *
- * # Arguments
- *
- * * `archive_path` - Path to archive file
- * * `config` - Optional `SecurityConfig` (uses secure defaults if omitted)
- *
- * # Returns
- *
- * Promise resolving to `VerificationReport` with validation results
- *
- * # Errors
- *
- * Returns error if path validation fails, archive is invalid, or I/O errors
- * occur.
- *
- * # Examples
- *
- * ```javascript
- * const report = await verifyArchive('archive.tar.gz');
- * if (report.status === 'PASS') {
- *     console.log('Archive is safe to extract');
- * } else {
- *     for (const issue of report.issues) {
- *         console.log(`[${issue.severity}] ${issue.message}`);
- *     }
- * }
- * ```
- */
-export declare function verifyArchive(archivePath: string, config?: SecurityConfig | undefined | null): Promise<VerificationReport>
-
-/**
- * Verify archive integrity and security (sync).
- *
- * Synchronous version of `verifyArchive`. Blocks the event loop until
- * verification completes. Prefer the async version for most use cases.
- *
- * # Arguments
- *
- * * `archive_path` - Path to archive file
- * * `config` - Optional `SecurityConfig` (uses secure defaults if omitted)
- *
- * # Returns
- *
- * `VerificationReport` with validation results
- *
- * # Errors
- *
- * Returns error if path validation fails, archive is invalid, or I/O errors
- * occur.
- *
- * # Examples
- *
- * ```javascript
- * const report = verifyArchiveSync('archive.tar.gz');
- * if (report.status === 'PASS') {
- *     console.log('Archive is safe to extract');
- * }
- * ```
- */
-export declare function verifyArchiveSync(archivePath: string, config?: SecurityConfig | undefined | null): VerificationReport