@openclaw/fs-safe 0.1.0

package/dist/archive-zip-preflight.js

@@ -0,0 +1,170 @@
+import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, assertArchiveEntryCountWithinLimit, resolveExtractLimits, } from "./archive-limits.js";
+const ZIP_EOCD_SIGNATURE = 0x06054b50;
+const ZIP64_EOCD_SIGNATURE = 0x06064b50;
+const ZIP64_EOCD_LOCATOR_SIGNATURE = 0x07064b50;
+const ZIP_EOCD_MIN_BYTES = 22;
+const ZIP_EOCD_MAX_COMMENT_BYTES = 0xffff;
+const ZIP64_ENTRY_COUNT_SENTINEL = 0xffff;
+const ZIP64_UINT32_SENTINEL = 0xffffffff;
+const ZIP_CENTRAL_FILE_HEADER_SIGNATURE = 0x02014b50;
+const ZIP_CENTRAL_FILE_HEADER_MIN_BYTES = 46;
+const ZIP_CENTRAL_FILE_HEADER_NAME_LENGTH_OFFSET = 28;
+const ZIP_CENTRAL_FILE_HEADER_EXTRA_LENGTH_OFFSET = 30;
+const ZIP_CENTRAL_FILE_HEADER_COMMENT_LENGTH_OFFSET = 32;
+const ZIP_EOCD_TOTAL_ENTRIES_OFFSET = 10;
+const ZIP_EOCD_CENTRAL_DIRECTORY_SIZE_OFFSET = 12;
+const ZIP_EOCD_CENTRAL_DIRECTORY_OFFSET_OFFSET = 16;
+const ZIP_EOCD_COMMENT_LENGTH_OFFSET = 20;
+const ZIP64_EOCD_LOCATOR_BYTES = 20;
+const ZIP64_EOCD_OFFSET_OFFSET = 8;
+const ZIP64_EOCD_TOTAL_ENTRIES_OFFSET = 32;
+const ZIP64_EOCD_CENTRAL_DIRECTORY_SIZE_OFFSET = 40;
+const ZIP64_EOCD_CENTRAL_DIRECTORY_OFFSET_OFFSET = 48;
+function asBufferView(buffer) {
+    if (Buffer.isBuffer(buffer)) {
+        return buffer;
+    }
+    return Buffer.from(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+}
+function readSafeUInt64LE(buffer, offset) {
+    const value = buffer.readBigUInt64LE(offset);
+    if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+        return Number.MAX_SAFE_INTEGER;
+    }
+    return Number(value);
+}
+function findZipEndOfCentralDirectory(buffer) {
+    if (buffer.byteLength < ZIP_EOCD_MIN_BYTES) {
+        return -1;
+    }
+    const minOffset = Math.max(0, buffer.byteLength - ZIP_EOCD_MIN_BYTES - ZIP_EOCD_MAX_COMMENT_BYTES);
+    for (let offset = buffer.byteLength - ZIP_EOCD_MIN_BYTES; offset >= minOffset; offset -= 1) {
+        if (buffer.readUInt32LE(offset) !== ZIP_EOCD_SIGNATURE) {
+            continue;
+        }
+        const commentLength = buffer.readUInt16LE(offset + ZIP_EOCD_COMMENT_LENGTH_OFFSET);
+        if (offset + ZIP_EOCD_MIN_BYTES + commentLength === buffer.byteLength) {
+            return offset;
+        }
+    }
+    return -1;
+}
+function readZip64CentralDirectoryInfo(buffer, eocdOffset) {
+    const locatorOffset = eocdOffset - ZIP64_EOCD_LOCATOR_BYTES;
+    if (locatorOffset < 0 || buffer.readUInt32LE(locatorOffset) !== ZIP64_EOCD_LOCATOR_SIGNATURE) {
+        return null;
+    }
+    const zip64EocdOffset = readSafeUInt64LE(buffer, locatorOffset + ZIP64_EOCD_OFFSET_OFFSET);
+    if (zip64EocdOffset < 0 ||
+        zip64EocdOffset + ZIP64_EOCD_CENTRAL_DIRECTORY_OFFSET_OFFSET + 8 > buffer.byteLength ||
+        buffer.readUInt32LE(zip64EocdOffset) !== ZIP64_EOCD_SIGNATURE) {
+        return null;
+    }
+    return {
+        declaredEntryCount: readSafeUInt64LE(buffer, zip64EocdOffset + ZIP64_EOCD_TOTAL_ENTRIES_OFFSET),
+        centralDirectorySize: readSafeUInt64LE(buffer, zip64EocdOffset + ZIP64_EOCD_CENTRAL_DIRECTORY_SIZE_OFFSET),
+        centralDirectoryOffset: readSafeUInt64LE(buffer, zip64EocdOffset + ZIP64_EOCD_CENTRAL_DIRECTORY_OFFSET_OFFSET),
+        endOfCentralDirectoryOffset: eocdOffset,
+    };
+}
+function readZipCentralDirectoryInfo(buffer) {
+    const eocdOffset = findZipEndOfCentralDirectory(buffer);
+    if (eocdOffset < 0) {
+        return null;
+    }
+    const declaredEntryCount = buffer.readUInt16LE(eocdOffset + ZIP_EOCD_TOTAL_ENTRIES_OFFSET);
+    const centralDirectorySize = buffer.readUInt32LE(eocdOffset + ZIP_EOCD_CENTRAL_DIRECTORY_SIZE_OFFSET);
+    const centralDirectoryOffset = buffer.readUInt32LE(eocdOffset + ZIP_EOCD_CENTRAL_DIRECTORY_OFFSET_OFFSET);
+    const usesZip64 = declaredEntryCount === ZIP64_ENTRY_COUNT_SENTINEL ||
+        centralDirectorySize === ZIP64_UINT32_SENTINEL ||
+        centralDirectoryOffset === ZIP64_UINT32_SENTINEL;
+    if (usesZip64) {
+        return (readZip64CentralDirectoryInfo(buffer, eocdOffset) ?? {
+            declaredEntryCount,
+            centralDirectoryOffset,
+            centralDirectorySize,
+            endOfCentralDirectoryOffset: eocdOffset,
+        });
+    }
+    return {
+        declaredEntryCount,
+        centralDirectoryOffset,
+        centralDirectorySize,
+        endOfCentralDirectoryOffset: eocdOffset,
+    };
+}
+function countZipCentralDirectoryHeaders(buffer, info) {
+    const start = info.centralDirectoryOffset;
+    const declaredEnd = start + info.centralDirectorySize;
+    const scanEnd = info.endOfCentralDirectoryOffset;
+    if (!Number.isSafeInteger(start) ||
+        !Number.isSafeInteger(declaredEnd) ||
+        !Number.isSafeInteger(scanEnd) ||
+        start < 0 ||
+        declaredEnd < start ||
+        scanEnd < start ||
+        scanEnd > buffer.byteLength) {
+        return null;
+    }
+    let offset = start;
+    let count = 0;
+    while (offset < scanEnd) {
+        if (scanEnd - offset < ZIP_CENTRAL_FILE_HEADER_MIN_BYTES) {
+            break;
+        }
+        if (buffer.readUInt32LE(offset) !== ZIP_CENTRAL_FILE_HEADER_SIGNATURE) {
+            break;
+        }
+        const nameLength = buffer.readUInt16LE(offset + ZIP_CENTRAL_FILE_HEADER_NAME_LENGTH_OFFSET);
+        const extraLength = buffer.readUInt16LE(offset + ZIP_CENTRAL_FILE_HEADER_EXTRA_LENGTH_OFFSET);
+        const commentLength = buffer.readUInt16LE(offset + ZIP_CENTRAL_FILE_HEADER_COMMENT_LENGTH_OFFSET);
+        const nextOffset = offset + ZIP_CENTRAL_FILE_HEADER_MIN_BYTES + nameLength + extraLength + commentLength;
+        if (nextOffset <= offset || nextOffset > scanEnd) {
+            return null;
+        }
+        count += 1;
+        offset = nextOffset;
+    }
+    return count > 0 || info.declaredEntryCount === 0 ? count : null;
+}
+export function readZipCentralDirectoryEntryCount(buffer) {
+    const view = asBufferView(buffer);
+    const info = readZipCentralDirectoryInfo(view);
+    if (!info) {
+        return null;
+    }
+    const countedEntryCount = countZipCentralDirectoryHeaders(view, info);
+    return countedEntryCount === null
+        ? info.declaredEntryCount
+        : Math.max(info.declaredEntryCount, countedEntryCount);
+}
+export async function loadZipArchiveWithPreflight(buffer, limits) {
+    const resolvedLimits = resolveExtractLimits(limits);
+    if (buffer.byteLength > resolvedLimits.maxArchiveBytes) {
+        throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
+    }
+    const entryCount = readZipCentralDirectoryEntryCount(buffer);
+    if (entryCount !== null) {
+        assertArchiveEntryCountWithinLimit(entryCount, resolvedLimits);
+    }
+    const JSZip = await importOptionalJsZip();
+    return await JSZip.loadAsync(buffer);
+}
+async function importOptionalJsZip() {
+    try {
+        const module = await import("jszip");
+        const candidate = typeof module === "function" ? module : module.default;
+        if ((typeof candidate !== "object" && typeof candidate !== "function") ||
+            candidate === null ||
+            typeof candidate.loadAsync !== "function") {
+            throw new Error('Optional archive dependency "jszip" does not expose loadAsync().');
+        }
+        return candidate;
+    }
+    catch (err) {
+        throw missingOptionalArchiveDependencyError("jszip", err);
+    }
+}
+function missingOptionalArchiveDependencyError(packageName, cause) {
+    return new Error(`Optional archive dependency "${packageName}" is not installed. Install it to use ZIP archive helpers from @openclaw/fs-safe/archive.`, { cause });
+}

package/dist/archive.d.ts

@@ -0,0 +1,24 @@
+import { type ArchiveExtractLimits } from "./archive-limits.js";
+import { type ArchiveKind } from "./archive-kind.js";
+export type ArchiveLogger = {
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+};
+export { isWindowsDrivePath, normalizeArchiveEntryPath, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
+export { resolveArchiveKind, resolvePackedRootDir, type ArchiveKind } from "./archive-kind.js";
+export { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_EXTRACTED_BYTES, DEFAULT_MAX_ENTRY_BYTES, type ArchiveExtractLimits, type ArchiveLimitErrorCode, } from "./archive-limits.js";
+export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-staging.js";
+export { createArchiveSymlinkTraversalError, mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+export { createTarEntryPreflightChecker, type TarEntryInfo } from "./archive-tar.js";
+export { loadZipArchiveWithPreflight, readZipCentralDirectoryEntryCount, type ZipArchiveWithFiles, } from "./archive-zip-preflight.js";
+export declare function extractArchive(params: {
+    archivePath: string;
+    destDir: string;
+    timeoutMs: number;
+    kind?: ArchiveKind;
+    stripComponents?: number;
+    tarGzip?: boolean;
+    limits?: ArchiveExtractLimits;
+    logger?: ArchiveLogger;
+}): Promise<void>;
+//# sourceMappingURL=archive.d.ts.map

package/dist/archive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AAYA,OAAO,EAOL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAgBzE,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,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EACL,kCAAkC,EAClC,iCAAiC,EACjC,4BAA4B,EAC5B,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,8BAA8B,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAC;AAiOpC,wBAAsB,cAAc,CAAC,MAAM,EAAE;IAC3C,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;CACxB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyEhB"}

package/dist/archive.js

@@ -0,0 +1,251 @@
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
+import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, assertArchiveEntryCountWithinLimit, createByteBudgetTracker, createExtractBudgetTransform, resolveExtractLimits, } from "./archive-limits.js";
+import { resolveArchiveKind } from "./archive-kind.js";
+import { mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+import { createTarEntryPreflightChecker, readTarEntryInfo, } from "./archive-tar.js";
+import { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
+import { isNotFoundPathError } from "./path.js";
+import { withTimeout } from "./timing.js";
+export { isWindowsDrivePath, normalizeArchiveEntryPath, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
+export { resolveArchiveKind, resolvePackedRootDir } from "./archive-kind.js";
+export { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_EXTRACTED_BYTES, DEFAULT_MAX_ENTRY_BYTES, } from "./archive-limits.js";
+export { ArchiveSecurityError } from "./archive-staging.js";
+export { createArchiveSymlinkTraversalError, mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+export { createTarEntryPreflightChecker } from "./archive-tar.js";
+export { loadZipArchiveWithPreflight, readZipCentralDirectoryEntryCount, } from "./archive-zip-preflight.js";
+const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
+const OPEN_WRITE_CREATE_FLAGS = fsConstants.O_WRONLY |
+    fsConstants.O_CREAT |
+    fsConstants.O_EXCL |
+    (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
+async function cleanupPartialRegularFile(filePath) {
+    let stat;
+    try {
+        stat = await fs.lstat(filePath);
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            return;
+        }
+        throw err;
+    }
+    if (stat.isFile()) {
+        await fs.unlink(filePath).catch(() => undefined);
+    }
+}
+function buildArchiveAtomicTempPath(targetPath) {
+    return path.join(path.dirname(targetPath), `.${path.basename(targetPath)}.${process.pid}.${randomUUID()}.tmp`);
+}
+const ZIP_UNIX_FILE_TYPE_MASK = 0o170000;
+const ZIP_UNIX_SYMLINK_TYPE = 0o120000;
+function isZipSymlinkEntry(entry) {
+    return (typeof entry.unixPermissions === "number" &&
+        (entry.unixPermissions & ZIP_UNIX_FILE_TYPE_MASK) === ZIP_UNIX_SYMLINK_TYPE);
+}
+async function readZipEntryStream(entry) {
+    if (typeof entry.nodeStream === "function") {
+        return entry.nodeStream();
+    }
+    // Old JSZip: fall back to buffering, but still extract via a stream.
+    const buf = await entry.async("nodebuffer");
+    return Readable.from(buf);
+}
+function resolveZipOutputPath(params) {
+    validateArchiveEntryPath(params.entryPath);
+    const relPath = stripArchivePath(params.entryPath, params.strip);
+    if (!relPath) {
+        return null;
+    }
+    validateArchiveEntryPath(relPath);
+    return {
+        relPath,
+        outPath: resolveArchiveOutputPath({
+            rootDir: params.destinationDir,
+            relPath,
+            originalPath: params.entryPath,
+        }),
+    };
+}
+async function prepareZipOutputPath(params) {
+    await prepareArchiveOutputPath(params);
+}
+async function writeZipFileEntry(params) {
+    params.budget.startEntry();
+    const readable = await readZipEntryStream(params.entry);
+    const destinationPath = params.outPath;
+    let tempHandle = null;
+    let tempPath = null;
+    let handleClosedByStream = false;
+    try {
+        tempPath = buildArchiveAtomicTempPath(destinationPath);
+        tempHandle = await fs.open(tempPath, OPEN_WRITE_CREATE_FLAGS, 0o666);
+        const writable = tempHandle.createWriteStream();
+        writable.once("close", () => {
+            handleClosedByStream = true;
+        });
+        await pipeline(readable, createExtractBudgetTransform({ onChunkBytes: params.budget.addBytes }), writable);
+        if (!handleClosedByStream) {
+            await tempHandle.close().catch(() => undefined);
+            handleClosedByStream = true;
+        }
+        tempHandle = null;
+        await fs.rename(tempPath, destinationPath);
+        tempPath = null;
+        // Best-effort permission restore for zip entries created on unix.
+        if (typeof params.entry.unixPermissions === "number") {
+            const mode = params.entry.unixPermissions & 0o777;
+            if (mode !== 0) {
+                await fs.chmod(destinationPath, mode).catch(() => undefined);
+            }
+        }
+    }
+    catch (err) {
+        if (tempPath) {
+            await fs.rm(tempPath, { force: true }).catch(() => undefined);
+        }
+        else {
+            await cleanupPartialRegularFile(destinationPath).catch(() => undefined);
+        }
+        throw err;
+    }
+    finally {
+        if (tempHandle && !handleClosedByStream) {
+            await tempHandle.close().catch(() => undefined);
+        }
+    }
+}
+async function extractZip(params) {
+    const limits = resolveExtractLimits(params.limits);
+    const destinationRealDir = await prepareArchiveDestinationDir(params.destDir);
+    const stat = await fs.stat(params.archivePath);
+    if (stat.size > limits.maxArchiveBytes) {
+        throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
+    }
+    const buffer = await fs.readFile(params.archivePath);
+    const zip = await loadZipArchiveWithPreflight(buffer, limits);
+    const entries = Object.values(zip.files);
+    const strip = Math.max(0, Math.floor(params.stripComponents ?? 0));
+    assertArchiveEntryCountWithinLimit(entries.length, limits);
+    const budget = createByteBudgetTracker(limits);
+    await withStagedArchiveDestination({
+        destinationRealDir,
+        run: async (stagingDir) => {
+            const stagingRealDir = await fs.realpath(stagingDir);
+            for (const entry of entries) {
+                const output = resolveZipOutputPath({
+                    entryPath: entry.name,
+                    strip,
+                    destinationDir: stagingRealDir,
+                });
+                if (!output) {
+                    continue;
+                }
+                await prepareZipOutputPath({
+                    destinationDir: stagingRealDir,
+                    destinationRealDir: stagingRealDir,
+                    relPath: output.relPath,
+                    outPath: output.outPath,
+                    originalPath: entry.name,
+                    isDirectory: entry.dir,
+                });
+                if (entry.dir) {
+                    continue;
+                }
+                if (isZipSymlinkEntry(entry)) {
+                    throw new Error(`zip entry is a link: ${entry.name}`);
+                }
+                await writeZipFileEntry({
+                    entry,
+                    outPath: output.outPath,
+                    budget,
+                });
+            }
+            await mergeExtractedTreeIntoDestination({
+                sourceDir: stagingRealDir,
+                destinationDir: destinationRealDir,
+                destinationRealDir,
+            });
+        },
+    });
+}
+export async function extractArchive(params) {
+    const kind = params.kind ?? resolveArchiveKind(params.archivePath);
+    if (!kind) {
+        throw new Error(`unsupported archive: ${params.archivePath}`);
+    }
+    const label = kind === "zip" ? "extract zip" : "extract tar";
+    if (kind === "tar") {
+        await withTimeout((async () => {
+            const tar = await importOptionalTar();
+            const limits = resolveExtractLimits(params.limits);
+            const stat = await fs.stat(params.archivePath);
+            if (stat.size > limits.maxArchiveBytes) {
+                throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
+            }
+            const destinationRealDir = await prepareArchiveDestinationDir(params.destDir);
+            await withStagedArchiveDestination({
+                destinationRealDir,
+                run: async (stagingDir) => {
+                    const checkTarEntrySafety = createTarEntryPreflightChecker({
+                        rootDir: destinationRealDir,
+                        stripComponents: params.stripComponents,
+                        limits,
+                    });
+                    // A canonical cwd is not enough here: tar can still follow
+                    // pre-existing child symlinks in the live destination tree.
+                    // Extract into a private staging dir first, then merge through
+                    // the same safe-open boundary checks used by direct file writes.
+                    await tar.x({
+                        file: params.archivePath,
+                        cwd: stagingDir,
+                        strip: Math.max(0, Math.floor(params.stripComponents ?? 0)),
+                        gzip: params.tarGzip,
+                        preservePaths: false,
+                        strict: true,
+                        onReadEntry(entry) {
+                            try {
+                                checkTarEntrySafety(readTarEntryInfo(entry));
+                            }
+                            catch (err) {
+                                const error = err instanceof Error ? err : new Error(String(err));
+                                // Node's EventEmitter calls listeners with `this` bound to the
+                                // emitter (tar.Unpack), which exposes Parser.abort().
+                                const emitter = this;
+                                emitter.abort?.(error);
+                            }
+                        },
+                    });
+                    await mergeExtractedTreeIntoDestination({
+                        sourceDir: stagingDir,
+                        destinationDir: destinationRealDir,
+                        destinationRealDir,
+                    });
+                },
+            });
+        })(), params.timeoutMs, label);
+        return;
+    }
+    await withTimeout(extractZip({
+        archivePath: params.archivePath,
+        destDir: params.destDir,
+        stripComponents: params.stripComponents,
+        limits: params.limits,
+    }), params.timeoutMs, label);
+}
+async function importOptionalTar() {
+    try {
+        return await import("tar");
+    }
+    catch (err) {
+        throw missingOptionalArchiveDependencyError("tar", err);
+    }
+}
+function missingOptionalArchiveDependencyError(packageName, cause) {
+    return new Error(`Optional archive dependency "${packageName}" is not installed. Install it to use TAR archive helpers from @openclaw/fs-safe/archive.`, { cause });
+}

package/dist/async-lock.d.ts

@@ -0,0 +1,2 @@
+export declare function createAsyncLock(): <T>(fn: () => Promise<T>) => Promise<T>;
+//# sourceMappingURL=async-lock.d.ts.map

package/dist/async-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-lock.d.ts","sourceRoot":"","sources":["../src/async-lock.ts"],"names":[],"mappings":"AAAA,wBAAgB,eAAe,KAEE,CAAC,EAAE,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAAC,CAapE"}

package/dist/async-lock.js

@@ -0,0 +1,17 @@
+export function createAsyncLock() {
+    let lock = Promise.resolve();
+    return async function withLock(fn) {
+        const prev = lock;
+        let release;
+        lock = new Promise((resolve) => {
+            release = resolve;
+        });
+        await prev;
+        try {
+            return await fn();
+        }
+        finally {
+            release?.();
+        }
+    };
+}

package/dist/atomic.d.ts

@@ -0,0 +1,5 @@
+export { replaceFileAtomic, replaceFileAtomicSync, type ReplaceFileAtomicFileSystem, type ReplaceFileAtomicOptions, type ReplaceFileAtomicResult, type ReplaceFileAtomicSyncFileSystem, type ReplaceFileAtomicSyncOptions, } from "./replace-file.js";
+export { writeTextAtomic, type WriteTextAtomicOptions } from "./text-atomic.js";
+export { replaceDirectoryAtomic, type ReplaceDirectoryAtomicOptions } from "./replace-directory.js";
+export { movePathWithCopyFallback, type MovePathWithCopyFallbackOptions } from "./move-path.js";
+//# sourceMappingURL=atomic.d.ts.map

package/dist/atomic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"atomic.d.ts","sourceRoot":"","sources":["../src/atomic.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,+BAA+B,EACpC,KAAK,4BAA4B,GAClC,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAChF,OAAO,EAAE,sBAAsB,EAAE,KAAK,6BAA6B,EAAE,MAAM,wBAAwB,CAAC;AACpG,OAAO,EAAE,wBAAwB,EAAE,KAAK,+BAA+B,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/atomic.js

@@ -0,0 +1,4 @@
+export { replaceFileAtomic, replaceFileAtomicSync, } from "./replace-file.js";
+export { writeTextAtomic } from "./text-atomic.js";
+export { replaceDirectoryAtomic } from "./replace-directory.js";
+export { movePathWithCopyFallback } from "./move-path.js";

package/dist/boundary-file-read.d.ts

@@ -0,0 +1,44 @@
+import fs from "node:fs";
+import type { PathAliasPolicy } from "./path-alias-guards.js";
+import { type SafeOpenSyncAllowedType, type SafeOpenSyncFailureReason } from "./safe-open-sync.js";
+type BoundaryReadFs = Pick<typeof fs, "closeSync" | "constants" | "fstatSync" | "lstatSync" | "openSync" | "readFileSync" | "realpathSync">;
+export type BoundaryFileOpenFailureReason = SafeOpenSyncFailureReason | "validation";
+export type BoundaryFileOpenResult = {
+    ok: true;
+    path: string;
+    fd: number;
+    stat: fs.Stats;
+    rootRealPath: string;
+} | {
+    ok: false;
+    reason: BoundaryFileOpenFailureReason;
+    error?: unknown;
+};
+export type BoundaryFileOpenFailure = Extract<BoundaryFileOpenResult, {
+    ok: false;
+}>;
+export type OpenBoundaryFileSyncParams = {
+    absolutePath: string;
+    rootPath: string;
+    boundaryLabel: string;
+    rootRealPath?: string;
+    maxBytes?: number;
+    rejectHardlinks?: boolean;
+    allowedType?: SafeOpenSyncAllowedType;
+    skipLexicalRootCheck?: boolean;
+    ioFs?: BoundaryReadFs;
+};
+export type OpenBoundaryFileParams = OpenBoundaryFileSyncParams & {
+    aliasPolicy?: PathAliasPolicy;
+};
+export declare function canUseBoundaryFileOpen(ioFs: typeof fs): boolean;
+export declare function openBoundaryFileSync(params: OpenBoundaryFileSyncParams): BoundaryFileOpenResult;
+export declare function matchBoundaryFileOpenFailure<T>(failure: BoundaryFileOpenFailure, handlers: {
+    path?: (failure: BoundaryFileOpenFailure) => T;
+    validation?: (failure: BoundaryFileOpenFailure) => T;
+    io?: (failure: BoundaryFileOpenFailure) => T;
+    fallback: (failure: BoundaryFileOpenFailure) => T;
+}): T;
+export declare function openBoundaryFile(params: OpenBoundaryFileParams): Promise<BoundaryFileOpenResult>;
+export {};
+//# sourceMappingURL=boundary-file-read.d.ts.map

package/dist/boundary-file-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boundary-file-read.d.ts","sourceRoot":"","sources":["../src/boundary-file-read.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAOzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAEL,KAAK,uBAAuB,EAC5B,KAAK,yBAAyB,EAC/B,MAAM,qBAAqB,CAAC;AAE7B,KAAK,cAAc,GAAG,IAAI,CACxB,OAAO,EAAE,EACP,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,GACV,cAAc,GACd,cAAc,CACjB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG,yBAAyB,GAAG,YAAY,CAAC;AAErF,MAAM,MAAM,sBAAsB,GAC9B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,6BAA6B,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE1E,MAAM,MAAM,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAErF,MAAM,MAAM,0BAA0B,GAAG;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,WAAW,CAAC,EAAE,uBAAuB,CAAC;IACtC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,0BAA0B,GAAG;IAChE,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAQF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAW/D;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,0BAA0B,GAAG,sBAAsB,CAuB/F;AAED,wBAAgB,4BAA4B,CAAC,CAAC,EAC5C,OAAO,EAAE,uBAAuB,EAChC,QAAQ,EAAE;IACR,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,CAAC,CAAC;IAC/C,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,CAAC,CAAC;IACrD,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,CAAC,CAAC;IAC7C,QAAQ,EAAE,CAAC,OAAO,EAAE,uBAAuB,KAAK,CAAC,CAAC;CACnD,GACA,CAAC,CAUH;AAoDD,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,sBAAsB,GAC7B,OAAO,CAAC,sBAAsB,CAAC,CAsBjC"}

package/dist/boundary-file-read.js

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import path from "node:path";
+import { resolveBoundaryPath, resolveBoundaryPathSync, } from "./boundary-path.js";
+import { openVerifiedFileSync, } from "./safe-open-sync.js";
+export function canUseBoundaryFileOpen(ioFs) {
+    return (typeof ioFs.openSync === "function" &&
+        typeof ioFs.closeSync === "function" &&
+        typeof ioFs.fstatSync === "function" &&
+        typeof ioFs.lstatSync === "function" &&
+        typeof ioFs.realpathSync === "function" &&
+        typeof ioFs.readFileSync === "function" &&
+        typeof ioFs.constants === "object" &&
+        ioFs.constants !== null);
+}
+export function openBoundaryFileSync(params) {
+    const ioFs = params.ioFs ?? fs;
+    const resolved = resolveBoundaryFilePathGeneric({
+        absolutePath: params.absolutePath,
+        resolve: (absolutePath) => resolveBoundaryPathSync({
+            absolutePath,
+            rootPath: params.rootPath,
+            rootCanonicalPath: params.rootRealPath,
+            boundaryLabel: params.boundaryLabel,
+            skipLexicalRootCheck: params.skipLexicalRootCheck,
+        }),
+    });
+    if (resolved instanceof Promise) {
+        return toBoundaryValidationError(new Error("Unexpected async boundary resolution"));
+    }
+    return finalizeBoundaryFileOpen({
+        resolved,
+        maxBytes: params.maxBytes,
+        rejectHardlinks: params.rejectHardlinks,
+        allowedType: params.allowedType,
+        ioFs,
+    });
+}
+export function matchBoundaryFileOpenFailure(failure, handlers) {
+    switch (failure.reason) {
+        case "path":
+            return handlers.path ? handlers.path(failure) : handlers.fallback(failure);
+        case "validation":
+            return handlers.validation ? handlers.validation(failure) : handlers.fallback(failure);
+        case "io":
+            return handlers.io ? handlers.io(failure) : handlers.fallback(failure);
+    }
+    return handlers.fallback(failure);
+}
+function openBoundaryFileResolved(params) {
+    const opened = openVerifiedFileSync({
+        filePath: params.absolutePath,
+        resolvedPath: params.resolvedPath,
+        rejectHardlinks: params.rejectHardlinks ?? true,
+        maxBytes: params.maxBytes,
+        allowedType: params.allowedType,
+        ioFs: params.ioFs,
+    });
+    if (!opened.ok) {
+        return opened;
+    }
+    return {
+        ok: true,
+        path: opened.path,
+        fd: opened.fd,
+        stat: opened.stat,
+        rootRealPath: params.rootRealPath,
+    };
+}
+function finalizeBoundaryFileOpen(params) {
+    if ("ok" in params.resolved) {
+        return params.resolved;
+    }
+    return openBoundaryFileResolved({
+        absolutePath: params.resolved.absolutePath,
+        resolvedPath: params.resolved.resolvedPath,
+        rootRealPath: params.resolved.rootRealPath,
+        maxBytes: params.maxBytes,
+        rejectHardlinks: params.rejectHardlinks,
+        allowedType: params.allowedType,
+        ioFs: params.ioFs,
+    });
+}
+export async function openBoundaryFile(params) {
+    const ioFs = params.ioFs ?? fs;
+    const maybeResolved = resolveBoundaryFilePathGeneric({
+        absolutePath: params.absolutePath,
+        resolve: (absolutePath) => resolveBoundaryPath({
+            absolutePath,
+            rootPath: params.rootPath,
+            rootCanonicalPath: params.rootRealPath,
+            boundaryLabel: params.boundaryLabel,
+            policy: params.aliasPolicy,
+            skipLexicalRootCheck: params.skipLexicalRootCheck,
+        }),
+    });
+    const resolved = maybeResolved instanceof Promise ? await maybeResolved : maybeResolved;
+    return finalizeBoundaryFileOpen({
+        resolved,
+        maxBytes: params.maxBytes,
+        rejectHardlinks: params.rejectHardlinks,
+        allowedType: params.allowedType,
+        ioFs,
+    });
+}
+function toBoundaryValidationError(error) {
+    return { ok: false, reason: "validation", error };
+}
+function mapResolvedBoundaryPath(absolutePath, resolved) {
+    return {
+        absolutePath,
+        resolvedPath: resolved.canonicalPath,
+        rootRealPath: resolved.rootCanonicalPath,
+    };
+}
+function resolveBoundaryFilePathGeneric(params) {
+    const absolutePath = path.resolve(params.absolutePath);
+    try {
+        const resolved = params.resolve(absolutePath);
+        if (resolved instanceof Promise) {
+            return resolved
+                .then((value) => mapResolvedBoundaryPath(absolutePath, value))
+                .catch((error) => toBoundaryValidationError(error));
+        }
+        return mapResolvedBoundaryPath(absolutePath, resolved);
+    }
+    catch (error) {
+        return toBoundaryValidationError(error);
+    }
+}