exarch-rs 0.4.0 → 0.5.0

package/index.d.ts

@@ -0,0 +1,789 @@
+/* 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>
+}
+
+/**
+ * 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` |
+ */
+export declare class ExtractionOptions {
+  /** Creates a new `ExtractionOptions` with defaults. */
+  constructor()
+  /**
+   * Creates an `ExtractionOptions` with defaults.
+   *
+   * This is equivalent to calling `new ExtractionOptions()`.
+   */
+  static default(): ExtractionOptions
+  /**
+   * 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.
+   */
+  withSkipDuplicates(skip?: boolean | undefined | null): this
+  /**
+   * 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.
+   */
+  withAtomic(atomic?: boolean | undefined | null): this
+  /** Finalizes the configuration (for API consistency). */
+  build(): this
+  /** Whether duplicate entries are skipped silently. */
+  get skipDuplicates(): boolean
+  /** Whether atomic extraction is enabled. */
+  get atomic(): boolean
+}
+
+/**
+ * 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
+  /**
+   * Allows or denies solid 7z archives.
+   *
+   * Solid archives require reading all preceding entries to decompress any
+   * entry, which may allow a crafted archive to consume excessive
+   * memory. Disabled by default.
+   */
+  setAllowSolidArchives(allow?: boolean | undefined | null): this
+  /**
+   * 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.
+   */
+  setMaxSolidBlockMemory(size: number): 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
+  /** Whether solid 7z archives are allowed. */
+  get allowSolidArchives(): boolean
+  /** Maximum memory in bytes for decompressing a solid 7z block. */
+  get maxSolidBlockMemory(): number
+  /**
+   * 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().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);
+ * ```
+ */
+export declare function extractArchive(archivePath: string, outputDir: string, config?: SecurityConfig | undefined | null, options?: ExtractionOptions | 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().setMaxFileSize(100 * 1024 * 1024);
+ * const report = extractArchiveSync('archive.tar.gz', '/tmp/output', config);
+ * ```
+ */
+export declare function extractArchiveSync(archivePath: string, outputDir: string, config?: SecurityConfig | undefined | null, options?: ExtractionOptions | undefined | null): ExtractionReport
+
+/**
+ * Extract an archive to the specified directory with a progress callback
+ * (async).
+ *
+ * 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 `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 `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)
+ *
+ * Extraction runs on the tokio blocking thread pool. The progress callback is
+ * dispatched back to the JavaScript thread via a threadsafe function.
+ *
+ * # Arguments
+ *
+ * * `archive_path` - Path to the archive file
+ * * `output_dir` - Directory where files will be extracted
+ * * `config` - Optional `SecurityConfig` (uses secure defaults if omitted)
+ * * `options` - Optional `ExtractionOptions` (uses defaults if omitted)
+ * * `progress` - Optional progress callback `(path: string, total: number,
+ *   current: number, bytesWritten: number) => void`
+ *
+ * # 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. See
+ * `extractArchive` for the full list of error codes.
+ *
+ * # Examples
+ *
+ * ```javascript
+ * const report = await extractArchiveWithProgress(
+ *   'archive.tar.gz',
+ *   '/tmp/output',
+ *   null,
+ *   null,
+ *   (path, total, current, bytesWritten) => {
+ *     console.log(`${current}/${total}: ${path}`);
+ *   },
+ * );
+ * console.log(`Extracted ${report.filesExtracted} files`);
+ * ```
+ */
+export declare function extractArchiveWithProgress(archivePath: string, outputDir: string, config?: SecurityConfig | undefined | null, options?: ExtractionOptions | undefined | null, progress?: (((err: Error | null, arg: [string, number, number, number]) => any)) | undefined | null): Promise<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