Archive

Thursday, the 26th of February, 2026
Mickaël CANOUIL, Ph.D. ORCID
Independent Contractor

Archive Extraction Module

Unified archive extraction for ZIP and TAR.GZ formats.

Provides format detection, extraction, and cleanup utilities for archive files.

Interfaces

Functions

Archive Security Module

Shared security utilities for archive extraction.

Provides path traversal detection and size formatting used by both ZIP and TAR extractors.

Variables

Functions

TAR.GZ Archive Extraction Module

TAR.GZ archive extraction with security checks.

Includes protection against path traversal and oversized archives.

Interfaces

Functions

ZIP Archive Extraction Module

ZIP archive extraction with security checks.

Includes protection against path traversal and zip bomb attacks.

Interfaces

Functions

checkPathTraversal

TypeScript
function checkPathTraversal(filePath): void;

Defined in: packages/core/src/archive/security.ts:29

Check for path traversal attempts in archive entry paths.

Parameters

Parameter Type Description
filePath string Entry path from the archive

Returns

void

Throws

SecurityError if path traversal is detected

cleanupExtraction

TypeScript
function cleanupExtraction(extractDir): Promise<void>;

Defined in: packages/core/src/archive/extract.ts:243

Clean up a temporary extraction directory.

Parameters

Parameter Type Description
extractDir string Directory to remove

Returns

Promise<void>

detectArchiveFormat

TypeScript
function detectArchiveFormat(archivePath): "zip" | "tarball" | null;

Defined in: packages/core/src/archive/extract.ts:43

Detect archive format from file path.

Parameters

Parameter Type
archivePath string

Returns

"zip" | "tarball" | null

extractArchive

TypeScript
function extractArchive(archivePath, options?): Promise<ExtractResult>;

Defined in: packages/core/src/archive/extract.ts:64

Extract an archive to a temporary directory.

Parameters

Parameter Type Description
archivePath string Path to the archive file
options ExtractOptions Extraction options

Returns

Promise<ExtractResult>

Extraction result

extractTar

TypeScript
function extractTar(
   archivePath,
   destDir,
options?): Promise<string[]>;

Defined in: packages/core/src/archive/tar.ts:34

Extract a TAR.GZ archive to a directory.

Parameters

Parameter Type Description
archivePath string Path to the TAR.GZ file
destDir string Destination directory
options TarExtractOptions Extraction options

Returns

Promise<string[]>

List of extracted file paths

extractZip

TypeScript
function extractZip(
   archivePath,
   destDir,
options?): Promise<string[]>;

Defined in: packages/core/src/archive/zip.ts:34

Extract a ZIP archive to a directory.

Parameters

Parameter Type Description
archivePath string Path to the ZIP file
destDir string Destination directory
options ZipExtractOptions Extraction options

Returns

Promise<string[]>

List of extracted file paths

findAllExtensionRoots

TypeScript
function findAllExtensionRoots(extractDir): Promise<DiscoveredExtension[]>;

Defined in: packages/core/src/archive/extract.ts:204

Find all extension roots in an extracted archive.

Unlike findExtensionRoot which returns the first match, this function finds all extensions in the archive, useful for repositories that contain multiple extensions.

Parameters

Parameter Type Description
extractDir string Extraction directory

Returns

Promise<DiscoveredExtension[]>

Array of discovered extensions

findExtensionRoot

TypeScript
function findExtensionRoot(extractDir, depth?): Promise<string | null>;

Defined in: packages/core/src/archive/extract.ts:120

Find the extension root in an extracted archive.

GitHub archives typically have a top-level directory like “repo-tag/”. This function finds the directory containing _extension.yml.

Parameters

Parameter Type Default value Description
extractDir string undefined Extraction directory
depth number 0 Current recursion depth (internal use)

Returns

Promise<string | null>

Path to extension root or null if not found

formatSize

TypeScript
function formatSize(bytes): string;

Defined in: packages/core/src/archive/security.ts:70

Format a byte count for display.

Parameters

Parameter Type Description
bytes number Number of bytes

Returns

string

Human-readable size string

validateUrlProtocol

TypeScript
function validateUrlProtocol(url): void;

Defined in: packages/core/src/archive/security.ts:50

Validate that a URL uses an allowed protocol.

Prevents SSRF by rejecting file://, ftp://, and other non-HTTP protocols.

Parameters

Parameter Type Description
url string URL string to validate

Returns

void

Throws

SecurityError if the protocol is not allowed

DiscoveredExtension

Defined in: packages/core/src/archive/extract.ts:159

Information about a discovered extension in an archive.

Properties

Property Type Description Defined in
id object Extension ID derived from directory structure. packages/core/src/archive/extract.ts:165
id.name string - packages/core/src/archive/extract.ts:165
id.owner string | null - packages/core/src/archive/extract.ts:165
path string Absolute path to the extension root (directory containing _extension.yml). packages/core/src/archive/extract.ts:161
relativePath string Path relative to the extraction root (for display purposes). packages/core/src/archive/extract.ts:163

ExtractOptions

Defined in: packages/core/src/archive/extract.ts:21

Options for archive extraction.

Properties

Property Type Description Defined in
maxSize? number Maximum total extraction size in bytes. packages/core/src/archive/extract.ts:23
onProgress? (file) => void Progress callback. packages/core/src/archive/extract.ts:25

ExtractResult

Defined in: packages/core/src/archive/extract.ts:31

Result of archive extraction.

Properties

Property Type Description Defined in
extractDir string Path to the extraction directory. packages/core/src/archive/extract.ts:33
files string[] List of extracted file paths. packages/core/src/archive/extract.ts:35
format "zip" | "tarball" Detected archive format. packages/core/src/archive/extract.ts:37

TarExtractOptions

Defined in: packages/core/src/archive/tar.ts:19

Options for TAR extraction.

Properties

Property Type Description Defined in
maxSize? number Maximum total extraction size in bytes. packages/core/src/archive/tar.ts:21
onProgress? (file) => void Progress callback. packages/core/src/archive/tar.ts:23

ZipExtractOptions

Defined in: packages/core/src/archive/zip.ts:19

Options for ZIP extraction.

Properties

Property Type Description Defined in
maxSize? number Maximum total extraction size in bytes. packages/core/src/archive/zip.ts:21
onProgress? (file) => void Progress callback. packages/core/src/archive/zip.ts:23

DEFAULT_MAX_SIZE

TypeScript
const DEFAULT_MAX_SIZE: number;

Defined in: packages/core/src/archive/security.ts:15

Default maximum extraction size: 100 MB.

MAX_COMPRESSION_RATIO

TypeScript
const MAX_COMPRESSION_RATIO: 100 = 100;

Defined in: packages/core/src/archive/security.ts:18

Maximum compression ratio allowed.

MAX_FILE_COUNT

TypeScript
const MAX_FILE_COUNT: 10000 = 10_000;

Defined in: packages/core/src/archive/security.ts:21

Maximum number of entries allowed in an archive.

Back to top

Reuse

MIT