@openclaw/fs-safe 0.1.0

package/dist/archive-entry.js

@@ -0,0 +1,47 @@
+import path from "node:path";
+import { resolveSafeBaseDir } from "./path.js";
+export function isWindowsDrivePath(value) {
+    return /^[a-zA-Z]:[\\/]/.test(value);
+}
+export function normalizeArchiveEntryPath(raw) {
+    return raw.replaceAll("\\", "/");
+}
+export function validateArchiveEntryPath(entryPath, params) {
+    if (!entryPath || entryPath === "." || entryPath === "./") {
+        return;
+    }
+    if (isWindowsDrivePath(entryPath)) {
+        throw new Error(`archive entry uses a drive path: ${entryPath}`);
+    }
+    const normalized = path.posix.normalize(normalizeArchiveEntryPath(entryPath));
+    const escapeLabel = params?.escapeLabel ?? "destination";
+    if (normalized === ".." || normalized.startsWith("../")) {
+        throw new Error(`archive entry escapes ${escapeLabel}: ${entryPath}`);
+    }
+    if (path.posix.isAbsolute(normalized) || normalized.startsWith("//")) {
+        throw new Error(`archive entry is absolute: ${entryPath}`);
+    }
+}
+export function stripArchivePath(entryPath, stripComponents) {
+    const raw = normalizeArchiveEntryPath(entryPath);
+    if (!raw || raw === "." || raw === "./") {
+        return null;
+    }
+    const parts = raw.split("/").filter((part) => part.length > 0 && part !== ".");
+    const strip = Math.max(0, Math.floor(stripComponents));
+    const stripped = strip === 0 ? parts.join("/") : parts.slice(strip).join("/");
+    const result = path.posix.normalize(stripped);
+    if (!result || result === "." || result === "./") {
+        return null;
+    }
+    return result;
+}
+export function resolveArchiveOutputPath(params) {
+    const safeBase = resolveSafeBaseDir(params.rootDir);
+    const outPath = path.resolve(params.rootDir, params.relPath);
+    const escapeLabel = params.escapeLabel ?? "destination";
+    if (!outPath.startsWith(safeBase)) {
+        throw new Error(`archive entry escapes ${escapeLabel}: ${params.originalPath}`);
+    }
+    return outPath;
+}

package/dist/archive-kind.d.ts

@@ -0,0 +1,8 @@
+export type ArchiveKind = "tar" | "zip";
+export declare function resolveArchiveKind(filePath: string): ArchiveKind | null;
+type ResolvePackedRootDirOptions = {
+    rootMarkers?: string[];
+};
+export declare function resolvePackedRootDir(extractDir: string, options?: ResolvePackedRootDirOptions): Promise<string>;
+export {};
+//# sourceMappingURL=archive-kind.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-kind.d.ts","sourceRoot":"","sources":["../src/archive-kind.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,KAAK,CAAC;AAIxC,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CASvE;AAED,KAAK,2BAA2B,GAAG;IACjC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAkBF,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,2BAA2B,GACpC,OAAO,CAAC,MAAM,CAAC,CA4BjB"}

package/dist/archive-kind.js

@@ -0,0 +1,58 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
+const TAR_SUFFIXES = [".tgz", ".tar.gz", ".tar"];
+export function resolveArchiveKind(filePath) {
+    const lower = normalizeLowercaseStringOrEmpty(filePath);
+    if (lower.endsWith(".zip")) {
+        return "zip";
+    }
+    if (TAR_SUFFIXES.some((suffix) => lower.endsWith(suffix))) {
+        return "tar";
+    }
+    return null;
+}
+async function hasPackedRootMarker(extractDir, rootMarkers) {
+    for (const marker of rootMarkers) {
+        const trimmed = marker.trim();
+        if (!trimmed) {
+            continue;
+        }
+        try {
+            await fs.stat(path.join(extractDir, trimmed));
+            return true;
+        }
+        catch {
+            // ignore
+        }
+    }
+    return false;
+}
+export async function resolvePackedRootDir(extractDir, options) {
+    const direct = path.join(extractDir, "package");
+    try {
+        const stat = await fs.stat(direct);
+        if (stat.isDirectory()) {
+            return direct;
+        }
+    }
+    catch {
+        // ignore
+    }
+    if ((options?.rootMarkers?.length ?? 0) > 0) {
+        const hasMarker = await hasPackedRootMarker(extractDir, options?.rootMarkers ?? []);
+        if (hasMarker) {
+            return extractDir;
+        }
+    }
+    const entries = await fs.readdir(extractDir, { withFileTypes: true });
+    const dirs = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    if (dirs.length !== 1) {
+        throw new Error(`unexpected archive layout (dirs: ${dirs.join(", ")})`);
+    }
+    const onlyDir = dirs[0];
+    if (!onlyDir) {
+        throw new Error("unexpected archive layout (no package dir found)");
+    }
+    return path.join(extractDir, onlyDir);
+}

package/dist/archive-limits.d.ts

@@ -0,0 +1,40 @@
+import { Transform } from "node:stream";
+export type ArchiveExtractLimits = {
+    /**
+     * Max archive file bytes (compressed).
+     */
+    maxArchiveBytes?: number;
+    /** Max number of extracted entries (files + dirs). */
+    maxEntries?: number;
+    /** Max extracted bytes (sum of all files). */
+    maxExtractedBytes?: number;
+    /** Max extracted bytes for a single file entry. */
+    maxEntryBytes?: number;
+};
+export declare const DEFAULT_MAX_ARCHIVE_BYTES_ZIP: number;
+export declare const DEFAULT_MAX_ENTRIES = 50000;
+export declare const DEFAULT_MAX_EXTRACTED_BYTES: number;
+export declare const DEFAULT_MAX_ENTRY_BYTES: number;
+export declare const ARCHIVE_LIMIT_ERROR_CODE: {
+    readonly ARCHIVE_SIZE_EXCEEDS_LIMIT: "archive-size-exceeds-limit";
+    readonly ENTRY_COUNT_EXCEEDS_LIMIT: "archive-entry-count-exceeds-limit";
+    readonly ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT: "archive-entry-extracted-size-exceeds-limit";
+    readonly EXTRACTED_SIZE_EXCEEDS_LIMIT: "archive-extracted-size-exceeds-limit";
+};
+export type ArchiveLimitErrorCode = (typeof ARCHIVE_LIMIT_ERROR_CODE)[keyof typeof ARCHIVE_LIMIT_ERROR_CODE];
+export declare class ArchiveLimitError extends Error {
+    readonly code: ArchiveLimitErrorCode;
+    constructor(code: ArchiveLimitErrorCode);
+}
+export type ResolvedArchiveExtractLimits = Required<ArchiveExtractLimits>;
+export declare function resolveExtractLimits(limits?: ArchiveExtractLimits): ResolvedArchiveExtractLimits;
+export declare function assertArchiveEntryCountWithinLimit(entryCount: number, limits: ResolvedArchiveExtractLimits): void;
+export declare function createByteBudgetTracker(limits: ResolvedArchiveExtractLimits): {
+    startEntry: () => void;
+    addBytes: (bytes: number) => void;
+    addEntrySize: (size: number) => void;
+};
+export declare function createExtractBudgetTransform(params: {
+    onChunkBytes: (bytes: number) => void;
+}): Transform;
+//# sourceMappingURL=archive-limits.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-limits.d.ts","sourceRoot":"","sources":["../src/archive-limits.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC,MAAM,MAAM,oBAAoB,GAAG;IACjC;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,mDAAmD;IACnD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,6BAA6B,QAAoB,CAAC;AAC/D,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,eAAO,MAAM,2BAA2B,QAAoB,CAAC;AAC7D,eAAO,MAAM,uBAAuB,QAAoB,CAAC;AAEzD,eAAO,MAAM,wBAAwB;;;;;CAK3B,CAAC;AAEX,MAAM,MAAM,qBAAqB,GAC/B,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,OAAO,wBAAwB,CAAC,CAAC;AAU3E,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;gBAEzB,IAAI,EAAE,qBAAqB;CAKxC;AAED,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC,oBAAoB,CAAC,CAAC;AAU1E,wBAAgB,oBAAoB,CAClC,MAAM,CAAC,EAAE,oBAAoB,GAC5B,4BAA4B,CAQ9B;AAED,wBAAgB,kCAAkC,CAChD,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,4BAA4B,QAKrC;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,4BAA4B,GAAG;IAC7E,UAAU,EAAE,MAAM,IAAI,CAAC;IACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACtC,CAiCA;AAED,wBAAgB,4BAA4B,CAAC,MAAM,EAAE;IACnD,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC,GAAG,SAAS,CAYZ"}

package/dist/archive-limits.js

@@ -0,0 +1,92 @@
+import { Transform } from "node:stream";
+export const DEFAULT_MAX_ARCHIVE_BYTES_ZIP = 256 * 1024 * 1024;
+export const DEFAULT_MAX_ENTRIES = 50_000;
+export const DEFAULT_MAX_EXTRACTED_BYTES = 512 * 1024 * 1024;
+export const DEFAULT_MAX_ENTRY_BYTES = 256 * 1024 * 1024;
+export const ARCHIVE_LIMIT_ERROR_CODE = {
+    ARCHIVE_SIZE_EXCEEDS_LIMIT: "archive-size-exceeds-limit",
+    ENTRY_COUNT_EXCEEDS_LIMIT: "archive-entry-count-exceeds-limit",
+    ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT: "archive-entry-extracted-size-exceeds-limit",
+    EXTRACTED_SIZE_EXCEEDS_LIMIT: "archive-extracted-size-exceeds-limit",
+};
+const ARCHIVE_LIMIT_ERROR_MESSAGE = {
+    [ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT]: "archive size exceeds limit",
+    [ARCHIVE_LIMIT_ERROR_CODE.ENTRY_COUNT_EXCEEDS_LIMIT]: "archive entry count exceeds limit",
+    [ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT]: "archive entry extracted size exceeds limit",
+    [ARCHIVE_LIMIT_ERROR_CODE.EXTRACTED_SIZE_EXCEEDS_LIMIT]: "archive extracted size exceeds limit",
+};
+export class ArchiveLimitError extends Error {
+    code;
+    constructor(code) {
+        super(ARCHIVE_LIMIT_ERROR_MESSAGE[code]);
+        this.name = "ArchiveLimitError";
+        this.code = code;
+    }
+}
+function clampLimit(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return undefined;
+    }
+    const v = Math.floor(value);
+    return v > 0 ? v : undefined;
+}
+export function resolveExtractLimits(limits) {
+    // Defaults: defensive, but should not break normal installs.
+    return {
+        maxArchiveBytes: clampLimit(limits?.maxArchiveBytes) ?? DEFAULT_MAX_ARCHIVE_BYTES_ZIP,
+        maxEntries: clampLimit(limits?.maxEntries) ?? DEFAULT_MAX_ENTRIES,
+        maxExtractedBytes: clampLimit(limits?.maxExtractedBytes) ?? DEFAULT_MAX_EXTRACTED_BYTES,
+        maxEntryBytes: clampLimit(limits?.maxEntryBytes) ?? DEFAULT_MAX_ENTRY_BYTES,
+    };
+}
+export function assertArchiveEntryCountWithinLimit(entryCount, limits) {
+    if (entryCount > limits.maxEntries) {
+        throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_COUNT_EXCEEDS_LIMIT);
+    }
+}
+export function createByteBudgetTracker(limits) {
+    let entryBytes = 0;
+    let extractedBytes = 0;
+    const addBytes = (bytes) => {
+        const b = Math.max(0, Math.floor(bytes));
+        if (b === 0) {
+            return;
+        }
+        entryBytes += b;
+        if (entryBytes > limits.maxEntryBytes) {
+            throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
+        }
+        extractedBytes += b;
+        if (extractedBytes > limits.maxExtractedBytes) {
+            throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.EXTRACTED_SIZE_EXCEEDS_LIMIT);
+        }
+    };
+    return {
+        startEntry() {
+            entryBytes = 0;
+        },
+        addBytes,
+        addEntrySize(size) {
+            const s = Math.max(0, Math.floor(size));
+            if (s > limits.maxEntryBytes) {
+                throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
+            }
+            // Tar budgets are based on the header-declared size.
+            addBytes(s);
+        },
+    };
+}
+export function createExtractBudgetTransform(params) {
+    return new Transform({
+        transform(chunk, _encoding, callback) {
+            try {
+                const buf = chunk instanceof Buffer ? chunk : Buffer.from(chunk);
+                params.onChunkBytes(buf.byteLength);
+                callback(null, buf);
+            }
+            catch (err) {
+                callback(err instanceof Error ? err : new Error(String(err)));
+            }
+        },
+    });
+}

package/dist/archive-staging.d.ts

@@ -0,0 +1,26 @@
+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);
+}
+export declare function prepareArchiveDestinationDir(destDir: string): Promise<string>;
+export declare function prepareArchiveOutputPath(params: {
+    destinationDir: string;
+    destinationRealDir: string;
+    relPath: string;
+    outPath: string;
+    originalPath: string;
+    isDirectory: boolean;
+}): Promise<void>;
+export declare function withStagedArchiveDestination<T>(params: {
+    destinationRealDir: string;
+    stagingDirPrefix?: string;
+    run: (stagingDir: string) => Promise<T>;
+}): Promise<T>;
+export declare function mergeExtractedTreeIntoDestination(params: {
+    sourceDir: string;
+    destinationDir: string;
+    destinationRealDir: string;
+}): Promise<void>;
+export declare function createArchiveSymlinkTraversalError(originalPath: string): ArchiveSecurityError;
+//# sourceMappingURL=archive-staging.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,wBAAwB,GAChC,2BAA2B,GAC3B,qBAAqB,GACrB,+BAA+B,CAAC;AAEpC,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,IAAI,EAAE,wBAAwB,CAAC;gBAEnB,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAKpF;AASD,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYnF;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,CAwBhB;AAmBD,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,CAkBb;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,CAyDhB;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}

package/dist/archive-staging.js

@@ -0,0 +1,171 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { root } from "./root.js";
+import { isNotFoundPathError, isPathInside } from "./path.js";
+import { resolveSecureTempRoot } from "./secure-temp-dir.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";
+    }
+}
+function symlinkTraversalError(originalPath) {
+    return new ArchiveSecurityError("destination-symlink-traversal", `${ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK}: ${originalPath}`);
+}
+export async function prepareArchiveDestinationDir(destDir) {
+    const stat = await fs.lstat(destDir);
+    if (stat.isSymbolicLink()) {
+        throw new ArchiveSecurityError("destination-symlink", "archive destination is a symlink");
+    }
+    if (!stat.isDirectory()) {
+        throw new ArchiveSecurityError("destination-not-directory", "archive destination is not a directory");
+    }
+    return await fs.realpath(destDir);
+}
+async function assertNoSymlinkTraversal(params) {
+    const parts = params.relPath.split(/[\\/]+/).filter(Boolean);
+    let current = path.resolve(params.rootDir);
+    for (const part of parts) {
+        current = path.join(current, part);
+        let stat;
+        try {
+            stat = await fs.lstat(current);
+        }
+        catch (err) {
+            if (isNotFoundPathError(err)) {
+                continue;
+            }
+            throw err;
+        }
+        if (stat.isSymbolicLink()) {
+            throw symlinkTraversalError(params.originalPath);
+        }
+    }
+}
+async function assertResolvedInsideDestination(params) {
+    let resolved;
+    try {
+        resolved = await fs.realpath(params.targetPath);
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            return;
+        }
+        throw err;
+    }
+    if (!isPathInside(params.destinationRealDir, resolved)) {
+        throw symlinkTraversalError(params.originalPath);
+    }
+}
+export async function prepareArchiveOutputPath(params) {
+    await assertNoSymlinkTraversal({
+        rootDir: params.destinationDir,
+        relPath: params.relPath,
+        originalPath: params.originalPath,
+    });
+    if (params.isDirectory) {
+        await fs.mkdir(params.outPath, { recursive: true });
+        await assertResolvedInsideDestination({
+            destinationRealDir: params.destinationRealDir,
+            targetPath: params.outPath,
+            originalPath: params.originalPath,
+        });
+        return;
+    }
+    const parentDir = path.dirname(params.outPath);
+    await fs.mkdir(parentDir, { recursive: true });
+    await assertResolvedInsideDestination({
+        destinationRealDir: params.destinationRealDir,
+        targetPath: parentDir,
+        originalPath: params.originalPath,
+    });
+}
+async function applyStagedEntryMode(params) {
+    const destinationPath = path.join(params.destinationRealDir, params.relPath);
+    await assertResolvedInsideDestination({
+        destinationRealDir: params.destinationRealDir,
+        targetPath: destinationPath,
+        originalPath: params.originalPath,
+    });
+    if (params.mode !== 0) {
+        await fs.chmod(destinationPath, params.mode).catch(() => undefined);
+    }
+}
+export async function withStagedArchiveDestination(params) {
+    const stagingRoot = resolveSecureTempRoot({
+        fallbackPrefix: "fs-safe-archive",
+        unsafeFallbackLabel: "archive staging temp dir",
+        warn: () => undefined,
+    });
+    if (isPathInside(params.destinationRealDir, stagingRoot)) {
+        throw new Error(`archive staging root must be outside destination: ${stagingRoot}`);
+    }
+    const stagingDir = await fs.mkdtemp(path.join(stagingRoot, params.stagingDirPrefix ?? "fs-safe-archive-"));
+    try {
+        await fs.chmod(stagingDir, ARCHIVE_STAGING_MODE).catch(() => undefined);
+        return await params.run(stagingDir);
+    }
+    finally {
+        await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
+export async function mergeExtractedTreeIntoDestination(params) {
+    const targetRoot = await root(params.destinationRealDir);
+    const walk = async (currentSourceDir) => {
+        const entries = await fs.readdir(currentSourceDir, { withFileTypes: true });
+        for (const entry of entries) {
+            const sourcePath = path.join(currentSourceDir, entry.name);
+            const relPath = path.relative(params.sourceDir, sourcePath);
+            const originalPath = relPath.split(path.sep).join("/");
+            const destinationPath = path.join(params.destinationDir, relPath);
+            const sourceStat = await fs.lstat(sourcePath);
+            if (sourceStat.isSymbolicLink()) {
+                throw symlinkTraversalError(originalPath);
+            }
+            if (sourceStat.isDirectory()) {
+                await prepareArchiveOutputPath({
+                    destinationDir: params.destinationDir,
+                    destinationRealDir: params.destinationRealDir,
+                    relPath,
+                    outPath: destinationPath,
+                    originalPath,
+                    isDirectory: true,
+                });
+                await walk(sourcePath);
+                await applyStagedEntryMode({
+                    destinationRealDir: params.destinationRealDir,
+                    relPath,
+                    mode: sourceStat.mode & 0o777,
+                    originalPath,
+                });
+                continue;
+            }
+            if (!sourceStat.isFile()) {
+                throw new Error(`archive staging contains unsupported entry: ${originalPath}`);
+            }
+            await prepareArchiveOutputPath({
+                destinationDir: params.destinationDir,
+                destinationRealDir: params.destinationRealDir,
+                relPath,
+                outPath: destinationPath,
+                originalPath,
+                isDirectory: false,
+            });
+            await targetRoot.copyIn(relPath, sourcePath, { mkdir: true });
+            await applyStagedEntryMode({
+                destinationRealDir: params.destinationRealDir,
+                relPath,
+                mode: sourceStat.mode & 0o777,
+                originalPath,
+            });
+        }
+    };
+    await walk(params.sourceDir);
+}
+export function createArchiveSymlinkTraversalError(originalPath) {
+    return symlinkTraversalError(originalPath);
+}

package/dist/archive-tar.d.ts

@@ -0,0 +1,14 @@
+import { type ArchiveExtractLimits } from "./archive-limits.js";
+export type TarEntryInfo = {
+    path: string;
+    type: string;
+    size: number;
+};
+export declare function readTarEntryInfo(entry: unknown): TarEntryInfo;
+export declare function createTarEntryPreflightChecker(params: {
+    rootDir: string;
+    stripComponents?: number;
+    limits?: ArchiveExtractLimits;
+    escapeLabel?: string;
+}): (entry: TarEntryInfo) => void;
+//# sourceMappingURL=archive-tar.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-tar.d.ts","sourceRoot":"","sources":["../src/archive-tar.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAWxE,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,YAAY,CAkB7D;AAED,wBAAgB,8BAA8B,CAAC,MAAM,EAAE;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,oBAAoB,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CA6BhC"}

package/dist/archive-tar.js

@@ -0,0 +1,52 @@
+import { resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
+import { assertArchiveEntryCountWithinLimit, createByteBudgetTracker, resolveExtractLimits, } from "./archive-limits.js";
+const BLOCKED_TAR_ENTRY_TYPES = new Set([
+    "SymbolicLink",
+    "Link",
+    "BlockDevice",
+    "CharacterDevice",
+    "FIFO",
+    "Socket",
+]);
+export function readTarEntryInfo(entry) {
+    const p = typeof entry === "object" && entry !== null && "path" in entry
+        ? String(entry.path)
+        : "";
+    const t = typeof entry === "object" && entry !== null && "type" in entry
+        ? String(entry.type)
+        : "";
+    const s = typeof entry === "object" &&
+        entry !== null &&
+        "size" in entry &&
+        typeof entry.size === "number" &&
+        Number.isFinite(entry.size)
+        ? Math.max(0, Math.floor(entry.size))
+        : 0;
+    return { path: p, type: t, size: s };
+}
+export function createTarEntryPreflightChecker(params) {
+    const strip = Math.max(0, Math.floor(params.stripComponents ?? 0));
+    const limits = resolveExtractLimits(params.limits);
+    let entryCount = 0;
+    const budget = createByteBudgetTracker(limits);
+    return (entry) => {
+        validateArchiveEntryPath(entry.path, { escapeLabel: params.escapeLabel });
+        const relPath = stripArchivePath(entry.path, strip);
+        if (!relPath) {
+            return;
+        }
+        validateArchiveEntryPath(relPath, { escapeLabel: params.escapeLabel });
+        resolveArchiveOutputPath({
+            rootDir: params.rootDir,
+            relPath,
+            originalPath: entry.path,
+            escapeLabel: params.escapeLabel,
+        });
+        if (BLOCKED_TAR_ENTRY_TYPES.has(entry.type)) {
+            throw new Error(`tar entry is a link: ${entry.path}`);
+        }
+        entryCount += 1;
+        assertArchiveEntryCountWithinLimit(entryCount, limits);
+        budget.addEntrySize(entry.size);
+    };
+}

package/dist/archive-utils.d.ts

@@ -0,0 +1,3 @@
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, label: string): Promise<T>;
+export declare function fileExists(filePath: string): Promise<boolean>;
+//# sourceMappingURL=archive-utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"archive-utils.d.ts","sourceRoot":"","sources":["../src/archive-utils.ts"],"names":[],"mappings":"AAEA,wBAAsB,WAAW,CAAC,CAAC,EACjC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EACnB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,CAAC,CAAC,CAiBZ;AAED,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE"}

package/dist/archive-utils.js

@@ -0,0 +1,26 @@
+import fs from "node:fs/promises";
+export async function withTimeout(promise, timeoutMs, label) {
+    let timeoutId;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timeoutId = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+export async function fileExists(filePath) {
+    try {
+        await fs.stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/archive-zip-preflight.d.ts

@@ -0,0 +1,7 @@
+import { type ArchiveExtractLimits } from "./archive-limits.js";
+export type ZipArchiveWithFiles = {
+    files: Record<string, unknown>;
+};
+export declare function readZipCentralDirectoryEntryCount(buffer: Buffer | Uint8Array): number | null;
+export declare function loadZipArchiveWithPreflight(buffer: Buffer | Uint8Array, limits?: ArchiveExtractLimits): Promise<ZipArchiveWithFiles>;
+//# sourceMappingURL=archive-zip-preflight.d.ts.map

package/dist/archive-zip-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-zip-preflight.d.ts","sourceRoot":"","sources":["../src/archive-zip-preflight.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAE7B,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAiLF,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,IAAI,CAU5F;AAED,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,MAAM,GAAG,UAAU,EAC3B,MAAM,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAW9B"}