Archive

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

TarExtractOptions

Functions

extractTar

ZIP Archive Extraction Module

ZIP archive extraction with security checks.

Includes protection against path traversal and zip bomb attacks.

Interfaces

ZipExtractOptions

Functions

extractZip

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:327

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:46

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:67

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

findExtensionRoot

TypeScript

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

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

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

readArchiveExtensions

TypeScript

function readArchiveExtensions(extractDir): Promise<ArchiveExtensions>;

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

Read the extensions an extracted archive offers, and the repository root they came from.

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

The repository’s own _extensions/ is the primary host: when it holds at least one extension, extensions found elsewhere in the archive are ignored, so a vendored copy under docs/_extensions/ is not offered for installation. Paths matched by the repository’s .quartoignore are dropped as well. Neither rule is allowed to empty the result, so an archive that only ships extensions in ignored locations still installs. discoverQuartoProjectRoots in the extension host applies the same two rules to a workspace folder; it checks the host first so it can skip scanning entirely, which is an ordering the fallback below makes immaterial.

Parameters

Parameter	Type	Description
`extractDir`	`string`	Extraction directory

Returns

Promise<ArchiveExtensions>

The repository root and the extensions on offer

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

ArchiveExtensions

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

What an extracted archive offers for installation.

Properties

Property	Type	Description	Defined in
`extensions`	`DiscoveredExtension[]`	Extensions the archive offers.	packages/core/src/archive/extract.ts:255
`root`	`string`	The repository root inside the extraction directory, with any archive wrapper directory stripped. Template files are relative to this, and it is where the repository declares `.quartoignore` and `_extensions/`.	packages/core/src/archive/extract.ts:253

DiscoveredExtension

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

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:173
`id.name`	`string`	-	packages/core/src/archive/extract.ts:173
`id.owner`	`string` \| `null`	-	packages/core/src/archive/extract.ts:173
`path`	`string`	Absolute path to the extension root (directory containing _extension.yml).	packages/core/src/archive/extract.ts:169
`relativePath`	`string`	Path relative to the extraction root (for display purposes).	packages/core/src/archive/extract.ts:171

ExtractOptions

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

Options for archive extraction.

Properties

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

ExtractResult

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

Result of archive extraction.

Properties

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

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.