exarch-rs 0.1.0 → 0.1.1

package/index.d.ts

@@ -1,217 +1,377 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
 /**
- * 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.
+ * Configuration for archive creation operations.
  *
- * All security features default to deny (secure-by-default policy).
- *
- * @example
- * ```typescript
- * // Use secure defaults
- * const config = new SecurityConfig();
+ * Controls how archives are created from filesystem sources, including
+ * security options, compression settings, and file filtering.
  *
- * // Customize with builder pattern
- * const config = new SecurityConfig()
- *   .maxFileSize(100 * 1024 * 1024)
- *   .allowSymlinks(true);
+ * # Defaults
  *
- * // Use permissive configuration for trusted archives
- * const config = SecurityConfig.permissive();
- * ```
+ * | 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 class SecurityConfig {
+export declare class CreationConfig {
+  /** Creates a new `CreationConfig` with secure defaults. */
+  constructor()
   /**
-   * Creates a new SecurityConfig with secure defaults.
+   * Creates a `CreationConfig` with secure defaults.
+   *
+   * This is equivalent to calling `new CreationConfig()`.
    */
-  constructor();
-
+  static default(): CreationConfig
   /**
-   * Creates a SecurityConfig with secure defaults.
-   * Equivalent to calling the constructor.
+   * 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.
    */
-  static default(): SecurityConfig;
-
+  setCompressionLevel(level: number): this
   /**
-   * Creates a permissive configuration for trusted archives.
+   * Sets whether to preserve file permissions from source.
    *
-   * Enables: symlinks, hardlinks, absolute paths, world-writable files.
-   * Use only for archives from trusted sources.
+   * Default: true.
    */
-  static permissive(): SecurityConfig;
-
-  // Builder pattern methods (chainable)
-
+  setPreservePermissions(preserve?: boolean | undefined | null): this
   /**
-   * Sets the maximum file size in bytes.
-   * Default: 50 MB (52,428,800 bytes)
+   * 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.
    */
-  maxFileSize(size: number): this;
-
+  setFollowSymlinks(follow?: boolean | undefined | null): 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
+   * Sets whether to include hidden files (files starting with '.').
    *
-   * @throws Error if ratio is not a positive finite number
+   * Default: false.
    */
-  maxCompressionRatio(ratio: number): this;
-
+  setIncludeHidden(include?: boolean | undefined | null): this
   /**
-   * Sets the maximum file count.
-   * Default: 10,000
+   * Sets maximum size for a single file in bytes.
+   *
+   * Files larger than this limit will be skipped.
+   *
+   * # Errors
+   *
+   * Returns error if size is negative.
    */
-  maxFileCount(count: number): this;
-
+  setMaxFileSize(size: number): this
   /**
-   * Sets the maximum path depth.
-   * Default: 32
+   * Adds an exclude pattern.
+   *
+   * Files matching this pattern will be skipped.
+   *
+   * # Errors
+   *
+   * Returns error if pattern contains null bytes.
    */
-  maxPathDepth(depth: number): this;
+  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()
   /**
-   * Allows or denies symlinks.
-   * Default: false (deny)
+   * Creates a `SecurityConfig` with secure defaults.
+   *
+   * This is equivalent to calling `new SecurityConfig()`.
    */
-  allowSymlinks(allow?: boolean): this;
-
+  static default(): SecurityConfig
   /**
-   * Allows or denies hardlinks.
-   * Default: false (deny)
+   * Creates a permissive configuration for trusted archives.
+   *
+   * Enables: symlinks, hardlinks, absolute paths, world-writable files.
+   * Use only for archives from trusted sources.
    */
-  allowHardlinks(allow?: boolean): this;
-
+  static permissive(): SecurityConfig
   /**
-   * Allows or denies absolute paths.
-   * Default: false (deny)
+   * Sets the maximum file size in bytes.
+   *
+   * # Errors
+   *
+   * Returns error if size is negative.
    */
-  allowAbsolutePaths(allow?: boolean): this;
-
+  setMaxFileSize(size: number): this
   /**
-   * Allows or denies world-writable files.
-   * Default: false (deny)
+   * Sets the maximum total size in bytes.
+   *
+   * # Errors
+   *
+   * Returns error if size is negative.
    */
-  allowWorldWritable(allow?: boolean): this;
-
+  setMaxTotalSize(size: number): this
   /**
-   * Sets whether to preserve permissions from archive.
-   * Default: false
+   * Sets the maximum compression ratio.
+   *
+   * # Errors
+   *
+   * Returns error if ratio is not a positive finite number.
    */
-  preservePermissions(preserve?: boolean): this;
-
+  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.
    *
-   * @throws Error if extension exceeds maximum length or contains null bytes
+   * # Errors
+   *
+   * Returns error if extension exceeds maximum length or contains null
+   * bytes.
    */
-  addAllowedExtension(ext: string): this;
-
+  addAllowedExtension(ext: string): this
   /**
    * Adds a banned path component.
    *
-   * @throws Error if component exceeds maximum length or contains null bytes
+   * # Errors
+   *
+   * Returns error if component exceeds maximum length or contains null
+   * bytes.
    */
-  addBannedComponent(component: string): this;
-
+  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
-
+  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
   /**
-   * Checks if a path component is allowed.
+   * 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.
    */
-  isPathComponentAllowed(component: string): boolean;
-
+  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
   /**
-   * Checks if a file extension is allowed.
+   * 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.
    */
-  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[];
+  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
 }
 
 /**
- * Report of an archive extraction operation.
+ * Single entry in archive manifest.
  *
- * Contains statistics and metadata about the extraction process.
+ * Contains metadata about a file, directory, symlink, or hardlink
+ * without extracting it to disk.
  */
-export interface ExtractionReport {
-  /** Number of files successfully extracted */
-  filesExtracted: number;
-
-  /** Number of directories created */
-  directoriesCreated: number;
-
-  /** Number of symlinks created */
-  symlinksCreated: number;
+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
+}
 
-  /** Total bytes written to disk */
-  bytesWritten: number;
+/**
+ * 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
+}
 
-  /** Extraction duration in milliseconds */
-  durationMs: number;
+/**
+ * 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>
 
-  /** Number of files skipped due to security checks */
-  filesSkipped: number;
+/**
+ * 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
 
-  /** List of warning messages */
-  warnings: string[];
+/**
+ * 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>
 }
 
 /**
@@ -222,7 +382,37 @@ export interface ExtractionReport {
  * configuration that blocks symlinks, hardlinks, absolute paths, and
  * enforces resource quotas.
  *
- * Error codes in exception messages:
+ * # 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
@@ -234,14 +424,9 @@ export interface ExtractionReport {
  * - `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
+ * # Examples
  *
- * @example
- * ```typescript
+ * ```javascript
  * // Use secure defaults
  * const report = await extractArchive('archive.tar.gz', '/tmp/output');
  * console.log(`Extracted ${report.filesExtracted} files`);
@@ -251,26 +436,32 @@ export interface ExtractionReport {
  * const report = await extractArchive('archive.tar.gz', '/tmp/output', config);
  * ```
  */
-export function extractArchive(
-  archivePath: string,
-  outputDir: string,
-  config?: SecurityConfig
-): Promise<ExtractionReport>;
+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
+ * 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
+ * # 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
  *
- * @example
- * ```typescript
+ * `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`);
@@ -280,8 +471,187 @@ export function extractArchive(
  * const report = extractArchiveSync('archive.tar.gz', '/tmp/output', config);
  * ```
  */
-export function extractArchiveSync(
-  archivePath: string,
-  outputDir: string,
-  config?: SecurityConfig
-): ExtractionReport;
+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