@openclaw/fs-safe 0.4.7 → 0.5.0

package/dist/archive-native.d.ts

@@ -0,0 +1,18 @@
+import type { ExtractionDeadline } from "./archive-deadline.js";
+import type { ArchiveKind } from "./archive-kind.js";
+import { type ArchiveExtractLimits } from "./archive-limits.js";
+import type { ExtractArchiveOptions } from "./archive-options.js";
+import type { NativeBinding } from "./native.js";
+export declare function extractNativeArchive(params: {
+    binding: NativeBinding;
+    archivePath: string;
+    destDir: string;
+    kind: ArchiveKind;
+    stripComponents?: number;
+    limits?: ArchiveExtractLimits;
+    deadline: ExtractionDeadline;
+    entryModes?: ExtractArchiveOptions["entryModes"];
+    entryFilter?: ExtractArchiveOptions["entryFilter"];
+    onFiltered?: ExtractArchiveOptions["onFiltered"];
+}): Promise<void>;
+//# sourceMappingURL=archive-native.d.ts.map

package/dist/archive-native.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-native.d.ts","sourceRoot":"","sources":["../src/archive-native.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAOL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAOlE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAoBjD,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,OAAO,EAAE,aAAa,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,UAAU,CAAC,EAAE,qBAAqB,CAAC,YAAY,CAAC,CAAC;IACjD,WAAW,CAAC,EAAE,qBAAqB,CAAC,aAAa,CAAC,CAAC;IACnD,UAAU,CAAC,EAAE,qBAAqB,CAAC,YAAY,CAAC,CAAC;CAClD,GAAG,OAAO,CAAC,IAAI,CAAC,CAsHhB"}

package/dist/archive-native.js

@@ -0,0 +1,115 @@
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
+import { resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath } from "./archive-entry.js";
+import { stageArchiveFileForExtraction } from "./archive-input.js";
+import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, resolveExtractLimits, } from "./archive-limits.js";
+import { resolveArchiveEntryMode, shouldExtractArchiveEntry } from "./archive-policy.js";
+import { mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, withStagedArchiveDestination, } from "./archive-staging.js";
+function policyKind(kind) {
+    if (kind === "file" || kind === "directory")
+        return kind;
+    if (kind === "symlink" || kind === "hardlink")
+        return "symlink";
+    return "other";
+}
+function throwMappedNativeError(error) {
+    if (error instanceof Error) {
+        for (const code of Object.values(ARCHIVE_LIMIT_ERROR_CODE)) {
+            if (error.message.includes(code))
+                throw new ArchiveLimitError(code);
+        }
+        if (error.message.includes("archive-header-invalid")) {
+            throw new ArchiveFormatError(error.message, { cause: error });
+        }
+    }
+    throw error;
+}
+export async function extractNativeArchive(params) {
+    const limits = resolveExtractLimits(params.limits);
+    const stagedArchive = await stageArchiveFileForExtraction({
+        archivePath: params.archivePath,
+        limits,
+        deadline: params.deadline,
+    });
+    try {
+        const destinationRealDir = await prepareArchiveDestinationDir(params.destDir);
+        await withStagedArchiveDestination({
+            destinationRealDir,
+            run: async (stagingDir) => {
+                params.deadline.check();
+                const manifest = await params.binding
+                    .inspectArchiveNative(stagedArchive.path, params.kind, limits.maxEntries, limits.maxMetaEntryBytes, limits.maxArchiveBytes, params.deadline.signal)
+                    .catch(throwMappedNativeError);
+                params.deadline.check();
+                assertArchiveEntryCountWithinLimit(manifest.length, limits);
+                const strip = Math.max(0, Math.floor(params.stripComponents ?? 0));
+                const budget = createByteBudgetTracker(limits);
+                const plan = [];
+                for (const entry of manifest) {
+                    params.deadline.check();
+                    validateArchiveEntryPath(entry.path);
+                    const relPath = stripArchivePath(entry.path, strip);
+                    if (!relPath)
+                        continue;
+                    validateArchiveEntryPath(relPath);
+                    assertArchiveEntryPathComponentsWithinLimit(relPath, limits);
+                    resolveArchiveOutputPath({ rootDir: stagingDir, relPath, originalPath: entry.path });
+                    const kind = policyKind(entry.kind);
+                    if (!shouldExtractArchiveEntry({
+                        filter: params.entryFilter,
+                        onFiltered: params.onFiltered,
+                        entry: { path: entry.path, kind, size: entry.size },
+                    })) {
+                        continue;
+                    }
+                    if (entry.kind === "sparse") {
+                        throw new ArchiveFormatError(`GNU sparse archive entry is not supported: ${entry.path}`);
+                    }
+                    if (kind === "symlink") {
+                        const label = params.kind === "zip" ? "zip" : "tar";
+                        throw new ArchiveSecurityError("entry-link", `${label} entry is a link: ${entry.path}`);
+                    }
+                    if (!Number.isSafeInteger(entry.size) || entry.size < 0) {
+                        throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
+                    }
+                    if (kind === "file") {
+                        budget.startEntry();
+                        budget.addEntrySize(entry.size);
+                    }
+                    if (kind === "file" || kind === "directory") {
+                        plan.push({
+                            index: entry.index,
+                            path: relPath,
+                            kind,
+                            size: entry.size,
+                            mode: resolveArchiveEntryMode({
+                                kind,
+                                archivedMode: entry.mode,
+                                policy: params.entryModes,
+                            }),
+                        });
+                    }
+                }
+                const directory = await fs.open(stagingDir, fsConstants.O_RDONLY |
+                    (typeof fsConstants.O_DIRECTORY === "number" ? fsConstants.O_DIRECTORY : 0));
+                try {
+                    params.deadline.check();
+                    await params.binding.extractArchiveNative(stagedArchive.path, params.kind, directory.fd, plan, limits.maxMetaEntryBytes, params.deadline.signal);
+                }
+                finally {
+                    await directory.close().catch(() => undefined);
+                }
+                params.deadline.check();
+                await mergeExtractedTreeIntoDestination({
+                    sourceDir: stagingDir,
+                    destinationDir: params.destDir,
+                    destinationRealDir,
+                });
+            },
+        });
+    }
+    finally {
+        await stagedArchive.cleanup();
+    }
+}

package/dist/archive-options.d.ts

@@ -0,0 +1,21 @@
+import type { ArchiveKind } from "./archive-kind.js";
+import type { ArchiveExtractLimits } from "./archive-limits.js";
+import type { ArchiveEntryFilter, ArchiveEntryModePolicy, ArchiveFilteredEntryPolicy } from "./archive-policy.js";
+export type ArchiveLogger = {
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+};
+export type ExtractArchiveOptions = {
+    archivePath: string;
+    destDir: string;
+    timeoutMs: number;
+    kind?: ArchiveKind;
+    stripComponents?: number;
+    tarGzip?: boolean;
+    limits?: ArchiveExtractLimits;
+    logger?: ArchiveLogger;
+    entryModes?: ArchiveEntryModePolicy;
+    entryFilter?: ArchiveEntryFilter;
+    onFiltered?: ArchiveFilteredEntryPolicy;
+};
+//# sourceMappingURL=archive-options.d.ts.map

package/dist/archive-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-options.d.ts","sourceRoot":"","sources":["../src/archive-options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChE,OAAO,KAAK,EACV,kBAAkB,EAClB,sBAAsB,EACtB,0BAA0B,EAC3B,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,UAAU,CAAC,EAAE,sBAAsB,CAAC;IACpC,WAAW,CAAC,EAAE,kBAAkB,CAAC;IACjC,UAAU,CAAC,EAAE,0BAA0B,CAAC;CACzC,CAAC"}

package/dist/archive-options.js

@@ -0,0 +1 @@
+export {};

package/dist/archive-policy.d.ts

@@ -0,0 +1,20 @@
+export type ArchiveEntryKind = "file" | "directory" | "symlink" | "other";
+export type ArchiveEntryModePolicy = "clamp" | "preserve";
+export type ArchiveFilteredEntryPolicy = "reject-archive" | "skip-entry";
+export type ArchiveEntryFilter = (entry: {
+    path: string;
+    kind: ArchiveEntryKind;
+    size: number;
+}) => "extract" | "skip";
+export declare function archiveEntryKindFromTarType(type: string): ArchiveEntryKind;
+export declare function resolveArchiveEntryMode(params: {
+    kind: "file" | "directory";
+    archivedMode?: number;
+    policy?: ArchiveEntryModePolicy;
+}): number;
+export declare function shouldExtractArchiveEntry(params: {
+    filter?: ArchiveEntryFilter;
+    onFiltered?: ArchiveFilteredEntryPolicy;
+    entry: Parameters<ArchiveEntryFilter>[0];
+}): boolean;
+//# sourceMappingURL=archive-policy.d.ts.map

package/dist/archive-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-policy.d.ts","sourceRoot":"","sources":["../src/archive-policy.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC;AAC1E,MAAM,MAAM,sBAAsB,GAAG,OAAO,GAAG,UAAU,CAAC;AAC1D,MAAM,MAAM,0BAA0B,GAAG,gBAAgB,GAAG,YAAY,CAAC;AACzE,MAAM,MAAM,kBAAkB,GAAG,CAAC,KAAK,EAAE;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,gBAAgB,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd,KAAK,SAAS,GAAG,MAAM,CAAC;AAEzB,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,CAK1E;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,sBAAsB,CAAC;CACjC,GAAG,MAAM,CAST;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE;IAChD,MAAM,CAAC,EAAE,kBAAkB,CAAC;IAC5B,UAAU,CAAC,EAAE,0BAA0B,CAAC;IACxC,KAAK,EAAE,UAAU,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;CAC1C,GAAG,OAAO,CAWV"}

package/dist/archive-policy.js

@@ -0,0 +1,29 @@
+import { ArchiveSecurityError } from "./archive-errors.js";
+export function archiveEntryKindFromTarType(type) {
+    if (type === "Directory" || type === "GNUDumpDir")
+        return "directory";
+    if (type === "File" || type === "OldFile" || type === "ContiguousFile")
+        return "file";
+    if (type === "SymbolicLink" || type === "Link")
+        return "symlink";
+    return "other";
+}
+export function resolveArchiveEntryMode(params) {
+    const archivedMode = (params.archivedMode ?? 0) & 0o777;
+    if (params.policy === "preserve") {
+        return archivedMode || (params.kind === "directory" ? 0o755 : 0o644);
+    }
+    if (params.kind === "directory") {
+        return 0o755;
+    }
+    return archivedMode & 0o100 ? 0o755 : 0o644;
+}
+export function shouldExtractArchiveEntry(params) {
+    if (!params.filter || params.filter(params.entry) === "extract") {
+        return true;
+    }
+    if ((params.onFiltered ?? "reject-archive") === "reject-archive") {
+        throw new ArchiveSecurityError("entry-filtered", `archive entry rejected by filter: ${params.entry.path}`);
+    }
+    return false;
+}

package/dist/archive-read.d.ts

@@ -0,0 +1,6 @@
+import { type ArchiveKind } from "./archive-kind.js";
+export declare function readArchiveEntry(archivePath: string, entryPath: string, options: {
+    maxBytes: number;
+    kind?: ArchiveKind;
+}): Promise<Buffer>;
+//# sourceMappingURL=archive-read.d.ts.map

package/dist/archive-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-read.d.ts","sourceRoot":"","sources":["../src/archive-read.ts"],"names":[],"mappings":"AASA,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAkLzE,wBAAsB,gBAAgB,CACpC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,WAAW,CAAA;CAAE,GAChD,OAAO,CAAC,MAAM,CAAC,CAwEjB"}

package/dist/archive-read.js

@@ -0,0 +1,200 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import { Readable } from "node:stream";
+import { readFileHandleBounded } from "./bounded-read.js";
+import { ArchiveFormatError } from "./archive-errors.js";
+import { normalizeArchiveEntryPath, validateArchiveEntryPath, } from "./archive-entry.js";
+import { resolveArchiveKind } from "./archive-kind.js";
+import { DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_META_ENTRY_BYTES, ArchiveLimitError, ARCHIVE_LIMIT_ERROR_CODE, } from "./archive-limits.js";
+import { readTarEntryInfo } from "./archive-tar.js";
+import { preflightTarMetadata } from "./archive-tar-meta.js";
+import { importOptionalTar } from "./archive-tar-runtime.js";
+import { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentity } from "./file-identity.js";
+import { getNativeBinding } from "./native.js";
+import { tempFile } from "./temp-target.js";
+const ZIP_UNIX_FILE_TYPE_MASK = 0o170000;
+const ZIP_UNIX_SYMLINK_TYPE = 0o120000;
+function normalizedRequestedEntry(entryPath) {
+    validateArchiveEntryPath(entryPath, { escapeLabel: "archive root" });
+    const normalized = normalizeArchiveEntryPath(entryPath).replace(/^\.\//, "");
+    if (!normalized || normalized.endsWith("/")) {
+        throw new Error(`archive entry is not a file: ${entryPath}`);
+    }
+    return normalized;
+}
+async function readStreamBounded(stream, maxBytes) {
+    if (!(Symbol.asyncIterator in Object(stream))) {
+        return await new Promise((resolve, reject) => {
+            const readable = stream;
+            const chunks = [];
+            let total = 0;
+            readable.on("data", (chunk) => {
+                const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                total += buffer.length;
+                if (total > maxBytes) {
+                    readable.pause();
+                    reject(new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT));
+                    return;
+                }
+                chunks.push(buffer);
+            });
+            readable.once("end", () => resolve(Buffer.concat(chunks, total)));
+            readable.once("error", reject);
+        });
+    }
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of stream) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buffer.length;
+        if (total > maxBytes) {
+            throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks, total);
+}
+async function stageArchiveInput(archivePath) {
+    const resolved = await fs.realpath(archivePath);
+    const before = await fs.lstat(archivePath);
+    if (before.isSymbolicLink() || !before.isFile()) {
+        throw new Error(`archive is not a regular file: ${archivePath}`);
+    }
+    const noFollow = process.platform !== "win32" && typeof fsSync.constants.O_NOFOLLOW === "number"
+        ? fsSync.constants.O_NOFOLLOW
+        : 0;
+    const handle = await fs.open(resolved, fsSync.constants.O_RDONLY | noFollow);
+    const staged = await tempFile({ prefix: "fs-safe-archive-read", fileName: "archive.bin" });
+    try {
+        const opened = await handle.stat();
+        const current = await fs.lstat(resolved);
+        if (!opened.isFile() ||
+            !current.isFile() ||
+            !sameFileIdentity(before, opened) ||
+            !sameFileIdentity(current, opened)) {
+            throw new Error("archive changed during validation");
+        }
+        const buffer = await readFileHandleBounded(handle, DEFAULT_MAX_ARCHIVE_BYTES_ZIP);
+        await fs.writeFile(staged.path, buffer, { flag: "wx", mode: 0o600 });
+        return { path: staged.path, buffer, cleanup: staged.cleanup };
+    }
+    catch (error) {
+        await staged.cleanup().catch(() => undefined);
+        throw error;
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+async function readZipEntry(buffer, entryPath, maxBytes) {
+    const archive = await loadZipArchiveWithPreflight(buffer, {
+        maxArchiveBytes: DEFAULT_MAX_ARCHIVE_BYTES_ZIP,
+        maxEntryBytes: maxBytes,
+        maxExtractedBytes: maxBytes,
+    });
+    const entry = archive.files[entryPath];
+    if (!entry || entry.dir) {
+        throw new Error(`archive entry not found: ${entryPath}`);
+    }
+    if (typeof entry.unixPermissions === "number" &&
+        (entry.unixPermissions & ZIP_UNIX_FILE_TYPE_MASK) === ZIP_UNIX_SYMLINK_TYPE) {
+        throw new Error(`archive entry is a link: ${entryPath}`);
+    }
+    const stream = typeof entry.nodeStream === "function"
+        ? entry.nodeStream()
+        : Readable.from(await entry.async("nodebuffer"));
+    return await readStreamBounded(stream, maxBytes);
+}
+async function readTarEntry(archivePath, entryPath, maxBytes) {
+    const tar = await importOptionalTar();
+    await preflightTarMetadata({
+        archivePath,
+        maxMetaEntryBytes: DEFAULT_MAX_META_ENTRY_BYTES,
+    });
+    let matched;
+    await tar.t({
+        file: archivePath,
+        strict: true,
+        maxMetaEntrySize: DEFAULT_MAX_META_ENTRY_BYTES,
+        onReadEntry(entry) {
+            const info = readTarEntryInfo(entry);
+            validateArchiveEntryPath(info.path, { escapeLabel: "archive root" });
+            const normalized = normalizeArchiveEntryPath(info.path).replace(/^\.\//, "");
+            if (normalized !== entryPath) {
+                entry.resume();
+                return;
+            }
+            if (info.type !== "File" && info.type !== "OldFile" && info.type !== "ContiguousFile") {
+                matched = Promise.reject(new Error(`archive entry is not a file: ${entryPath}`));
+                entry.resume();
+                return;
+            }
+            if (info.size > maxBytes) {
+                matched = Promise.reject(new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT));
+                entry.resume();
+                return;
+            }
+            matched = readStreamBounded(entry, maxBytes);
+        },
+    });
+    if (!matched) {
+        throw new Error(`archive entry not found: ${entryPath}`);
+    }
+    return await matched;
+}
+export async function readArchiveEntry(archivePath, entryPath, options) {
+    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0) {
+        throw new RangeError("maxBytes must be a non-negative safe integer");
+    }
+    const kind = options.kind ?? resolveArchiveKind(archivePath);
+    if (!kind) {
+        throw new Error(`unsupported archive: ${archivePath}`);
+    }
+    const requestedEntry = normalizedRequestedEntry(entryPath);
+    const staged = await stageArchiveInput(archivePath);
+    try {
+        const native = getNativeBinding();
+        if (native) {
+            try {
+                const signal = new AbortController().signal;
+                const manifest = await native.inspectArchiveNative(staged.path, kind, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_META_ENTRY_BYTES, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, signal);
+                let rawEntryPath;
+                for (const entry of manifest) {
+                    validateArchiveEntryPath(entry.path, { escapeLabel: "archive root" });
+                    const normalized = normalizeArchiveEntryPath(entry.path).replace(/^\.\//, "");
+                    if (normalized === requestedEntry) {
+                        if (entry.kind !== "file") {
+                            throw new Error(`archive entry is not a file: ${entryPath}`);
+                        }
+                        rawEntryPath = entry.path;
+                        break;
+                    }
+                }
+                if (!rawEntryPath)
+                    throw new Error(`archive entry not found: ${entryPath}`);
+                return await native.readArchiveEntryNative(staged.path, kind, rawEntryPath, options.maxBytes, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_META_ENTRY_BYTES, signal);
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    error.message.includes(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT)) {
+                    throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
+                }
+                if (error instanceof Error && error.message.includes("archive-header-invalid")) {
+                    throw new ArchiveFormatError(error.message, { cause: error });
+                }
+                throw error;
+            }
+        }
+        if (kind === "tar-zstd" || kind === "tar-bzip2") {
+            throw new FsSafeError("helper-unavailable", `${kind} archives require a supported bundled native binding`);
+        }
+        return kind === "zip"
+            ? await readZipEntry(staged.buffer, requestedEntry, options.maxBytes)
+            : await readTarEntry(staged.path, requestedEntry, options.maxBytes);
+    }
+    finally {
+        await staged.cleanup();
+    }
+}

package/dist/archive-staging.d.ts

@@ -1,8 +1,5 @@
-export type ArchiveSecurityErrorCode = "destination-not-directory" | "destination-symlink" | "destination-symlink-traversal";
-export declare class ArchiveSecurityError extends Error {
-    code: ArchiveSecurityErrorCode;
-    constructor(code: ArchiveSecurityErrorCode, message: string, options?: ErrorOptions);
-}
+import { ArchiveSecurityError } from "./archive-errors.js";
+export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-errors.js";
 export declare function prepareArchiveDestinationDir(destDir: string): Promise<string>;
 export declare function prepareArchiveOutputPath(params: {
     destinationDir: string;

package/dist/archive-staging.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,wBAAwB,GAChC,2BAA2B,GAC3B,qBAAqB,GACrB,+BAA+B,CAAC;AAEpC,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,IAAI,EAAE,wBAAwB,CAAC;IAE/B,YAAY,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,EAIlF;CACF;AAkCD,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BnF;AA6CD,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmChB;AAyHD,wBAAsB,4BAA4B,CAAC,CAAC,EAAE,MAAM,EAAE;IAC5D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzC,GAAG,OAAO,CAAC,CAAC,CAAC,CA6Bb;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,GAAG,OAAO,CAAC,IAAI,CAAC,CAgFhB;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}
+{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,oBAAoB,EAErB,MAAM,qBAAqB,CAAC;AAU7B,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAkC1F,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BnF;AA4DD,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuChB;AAyHD,wBAAsB,4BAA4B,CAAC,CAAC,EAAE,MAAM,EAAE;IAC5D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzC,GAAG,OAAO,CAAC,CAAC,CAAC,CA6Bb;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,GAAG,OAAO,CAAC,IAAI,CAAC,CAgFhB;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}

package/dist/archive-staging.js

@@ -2,6 +2,7 @@ import fs from "node:fs/promises";
 import fsSync from "node:fs";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
+import { ArchiveSecurityError, } from "./archive-errors.js";
 import { FsSafeError } from "./errors.js";
 import { resolveOpenedFileRealPathForHandle, root } from "./root.js";
 import { isNotFoundPathError, isPathInside } from "./path.js";
@@ -9,14 +10,7 @@ import { resolveSecureTempRoot } from "./secure-temp-dir.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 const ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK = "archive entry traverses symlink in destination";
 const ARCHIVE_STAGING_MODE = 0o700;
-export class ArchiveSecurityError extends Error {
-    code;
-    constructor(code, message, options) {
-        super(message, options);
-        this.code = code;
-        this.name = "ArchiveSecurityError";
-    }
-}
+export { ArchiveSecurityError } from "./archive-errors.js";
 function symlinkTraversalError(originalPath) {
     return new ArchiveSecurityError("destination-symlink-traversal", `${ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK}: ${originalPath}`);
 }
@@ -98,6 +92,17 @@ async function assertResolvedInsideDestination(params) {
         throw symlinkTraversalError(params.originalPath);
     }
 }
+async function mkdirArchiveOutput(params) {
+    try {
+        await params.targetRoot.mkdir(params.relativePath);
+    }
+    catch (error) {
+        if (error instanceof FsSafeError) {
+            throw symlinkTraversalError(params.originalPath);
+        }
+        throw error;
+    }
+}
 export async function prepareArchiveOutputPath(params) {
     const targetRoot = await root(params.destinationRealDir);
     const destinationGuard = await createDirectoryIdentityGuard(params.destinationRealDir);
@@ -110,7 +115,7 @@ export async function prepareArchiveOutputPath(params) {
     if (params.isDirectory) {
         await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("mkdir", params.outPath);
         await assertDirectoryIdentityGuard(destinationGuard);
-        await targetRoot.mkdir(relPath);
+        await mkdirArchiveOutput({ targetRoot, relativePath: relPath, originalPath: params.originalPath });
         await assertDirectoryIdentityGuard(destinationGuard);
         await assertResolvedInsideDestination({
             destinationRealDir: params.destinationRealDir,
@@ -123,7 +128,11 @@ export async function prepareArchiveOutputPath(params) {
     if (parentRel !== ".") {
         await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("mkdir", path.dirname(params.outPath));
         await assertDirectoryIdentityGuard(destinationGuard);
-        await targetRoot.mkdir(parentRel);
+        await mkdirArchiveOutput({
+            targetRoot,
+            relativePath: parentRel,
+            originalPath: params.originalPath,
+        });
         await assertDirectoryIdentityGuard(destinationGuard);
     }
     await assertResolvedInsideDestination({

package/dist/archive-tar-meta.d.ts

@@ -0,0 +1,6 @@
+export declare function preflightTarMetadata(params: {
+    archivePath: string;
+    maxMetaEntryBytes: number;
+    signal?: AbortSignal;
+}): Promise<void>;
+//# sourceMappingURL=archive-tar-meta.d.ts.map

package/dist/archive-tar-meta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-tar-meta.d.ts","sourceRoot":"","sources":["../src/archive-tar-meta.ts"],"names":[],"mappings":"AAuIA,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB"}