@openclaw/openshell-sandbox 2026.9.1 → 2026.9.3

package/node_modules/@openclaw/fs-safe/dist/archive-read.js

@@ -0,0 +1,225 @@
+import { classifyArchiveParserError } from "./archive-parser-errors.js";
+import fs from "node:fs/promises";
+import { Readable } from "node:stream";
+import { readFileHandleBounded } from "./bounded-read.js";
+import { ArchiveFormatError, ArchiveSecurityError, isArchiveFormatErrorMessage, } from "./archive-errors.js";
+import { formatErrorDetail } from "./error-detail.js";
+import { stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
+import { assertPortableArchiveKind, resolveArchiveKind } from "./archive-kind.js";
+import { DEFAULT_MAX_ARCHIVE_BYTES_ZIP, ArchiveLimitError, ARCHIVE_LIMIT_ERROR_CODE, } from "./archive-limits.js";
+import { inspectTar, replayTar } from "./archive-tar-stream.js";
+import { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
+import { createZipIntegrityTransform, normalizeZipIntegrityError, } from "./archive-zip-integrity.js";
+import { FsSafeError } from "./errors.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { getNativeBinding } from "./native.js";
+import { admitZipBuffer } from "./archive-zip-admission.js";
+import { resolveExtractLimits, resolveTarMeterLimits } from "./archive-limits.js";
+import { tempFile } from "./temp-target.js";
+const ZIP_UNIX_FILE_TYPE_MASK = 0o170000;
+const ZIP_UNIX_SYMLINK_TYPE = 0o120000;
+function canonicalEntryPath(entryPath) {
+    validateArchiveEntryPath(entryPath, { escapeLabel: "archive root" });
+    return stripArchivePath(entryPath, 0) ?? "";
+}
+function normalizedRequestedEntry(entryPath) {
+    const normalized = canonicalEntryPath(entryPath);
+    if (!normalized || /[/\\]$/.test(entryPath)) {
+        throw new Error(`archive entry is not a file: ${formatErrorDetail(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 inspectFileIdentity(async () => {
+        const stat = await fs.lstat(archivePath, { bigint: true });
+        if (stat.isSymbolicLink() || !stat.isFile()) {
+            throw new Error(`archive is not a regular file: ${archivePath}`);
+        }
+        return stat;
+    });
+    const handle = await fs.open(resolved, resolveReadOpenFlags());
+    let staged;
+    try {
+        staged = await tempFile({ prefix: "fs-safe-archive-read", fileName: "archive.bin" });
+        const opened = await inspectFileIdentity(async () => {
+            const stat = await handle.stat({ bigint: true });
+            if (!stat.isFile())
+                throw new Error("archive changed during validation");
+            return stat;
+        }, before);
+        await inspectFileIdentity(async () => {
+            const stat = await fs.lstat(resolved, { bigint: true });
+            if (stat.isSymbolicLink() || !stat.isFile())
+                throw new Error("archive changed during validation");
+            return stat;
+        }, opened);
+        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);
+        if (error instanceof FsSafeError && error.code === "path-mismatch") {
+            throw new FsSafeError("path-mismatch", "archive changed during validation", { cause: error });
+        }
+        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,
+    });
+    let entry;
+    // JSZip keys retain some aliases and may use Unicode Path metadata. Scan the
+    // effective entries once, after raw ZIP admission has rejected collisions.
+    for (const candidate of Object.values(archive.files)) {
+        if (canonicalEntryPath(candidate.name) !== entryPath)
+            continue;
+        if (entry) {
+            throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(entryPath)}`);
+        }
+        entry = candidate;
+    }
+    if (!entry || entry.dir) {
+        throw new Error(`archive entry not found: ${formatErrorDetail(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: ${formatErrorDetail(entryPath)}`);
+    }
+    const stream = typeof entry.nodeStream === "function"
+        ? entry.nodeStream()
+        : Readable.from(await entry.async("nodebuffer"));
+    const integrity = createZipIntegrityTransform(entry);
+    stream.once("error", (error) => integrity.destroy(normalizeZipIntegrityError(error)));
+    return await readStreamBounded(stream.pipe(integrity), maxBytes);
+}
+async function readTarEntry(archivePath, entryPath, maxBytes) {
+    const seenPaths = new Set();
+    let selected;
+    const limits = resolveTarMeterLimits();
+    await inspectTar({ archivePath, limits, onMember(info) {
+            const normalized = canonicalEntryPath(info.path);
+            if (seenPaths.has(normalized)) {
+                throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(normalized)}`);
+            }
+            seenPaths.add(normalized);
+            if (normalized === entryPath)
+                selected = info;
+        } });
+    if (!selected)
+        throw new Error(`archive entry not found: ${formatErrorDetail(entryPath)}`);
+    if (!["File", "OldFile", "ContiguousFile"].includes(selected.type)) {
+        throw new Error(`archive entry is not a file: ${formatErrorDetail(entryPath)}`);
+    }
+    if (selected.size > maxBytes)
+        throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
+    let result;
+    await replayTar({ archivePath, limits, members: [selected], async consume(_member, payload) {
+            result = await readStreamBounded(payload, maxBytes);
+        } });
+    return result;
+}
+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 physicalCount = kind === "zip"
+            ? admitZipBuffer(staged.buffer, resolveExtractLimits())
+            : undefined;
+        const native = getNativeBinding();
+        if (native) {
+            try {
+                const signal = new AbortController().signal;
+                const limits = resolveTarMeterLimits();
+                const manifest = await native.inspectArchiveNative(staged.path, kind, limits, signal);
+                let rawEntryPath;
+                if (physicalCount !== undefined && manifest.length !== physicalCount) {
+                    throw new ArchiveSecurityError("entry-path", "zip decoder collapsed entry names");
+                }
+                const seenPaths = new Set();
+                for (const entry of manifest) {
+                    const normalized = canonicalEntryPath(entry.path);
+                    if (seenPaths.has(normalized)) {
+                        throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(normalized)}`);
+                    }
+                    seenPaths.add(normalized);
+                    if (normalized === requestedEntry) {
+                        if (entry.kind !== "file") {
+                            throw new Error(`archive entry is not a file: ${formatErrorDetail(entryPath)}`);
+                        }
+                        rawEntryPath = entry.path;
+                    }
+                }
+                if (!rawEntryPath) {
+                    throw new Error(`archive entry not found: ${formatErrorDetail(entryPath)}`);
+                }
+                return await native.readArchiveEntryNative(staged.path, kind, rawEntryPath, options.maxBytes, limits, signal);
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    const mapped = classifyArchiveParserError(error.message, { cause: error });
+                    if (mapped)
+                        throw mapped;
+                }
+                if (error instanceof Error && isArchiveFormatErrorMessage(error.message)) {
+                    throw new ArchiveFormatError(error.message, { cause: error });
+                }
+                throw error;
+            }
+        }
+        assertPortableArchiveKind(kind);
+        return kind === "zip"
+            ? await readZipEntry(staged.buffer, requestedEntry, options.maxBytes)
+            : await readTarEntry(staged.path, requestedEntry, options.maxBytes);
+    }
+    finally {
+        await staged.cleanup();
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/archive-staging.d.ts

@@ -0,0 +1,31 @@
+import { type AsyncDirectoryGuard } from "./directory-guard.js";
+import { type ExtractionDeadline } from "./archive-deadline.js";
+import { ArchiveSecurityError } from "./archive-errors.js";
+export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-errors.js";
+export declare function createDirectoryIdentityGuard(dir: string): Promise<AsyncDirectoryGuard>;
+export declare function assertDirectoryIdentityGuard(guard: AsyncDirectoryGuard): Promise<void>;
+export declare function prepareArchiveDestinationDir(destDir: string): Promise<string>;
+export declare function assertResolvedInsideDestination(params: {
+    destinationRealDir: string;
+    targetPath: string;
+    originalPath: string;
+}): Promise<void>;
+type ArchiveOutputPathParams = {
+    destinationDir: string;
+    destinationRealDir: string;
+    relPath: string;
+    outPath: string;
+    originalPath: string;
+    isDirectory: boolean;
+    deadline?: ExtractionDeadline;
+};
+export declare function prepareArchiveOutputPath(params: ArchiveOutputPathParams): Promise<void>;
+export declare function preparePrivateArchiveOutputPath(params: ArchiveOutputPathParams, assertGuards?: () => Promise<void>): Promise<void>;
+export declare function withStagedArchiveDestination<T>(params: {
+    destinationRealDir: string;
+    stagingDirPrefix?: string;
+    run: (stagingDir: string) => Promise<T>;
+}): Promise<T>;
+export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
+export declare function createArchiveSymlinkTraversalError(originalPath: string): ArchiveSecurityError;
+//# sourceMappingURL=archive-staging.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/archive-staging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EAErB,MAAM,qBAAqB,CAAC;AAkB7B,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAS1F,wBAAsB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAS5F;AAED,wBAAsB,4BAA4B,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAY5F;AAED,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BnF;AA0BD,wBAAsB,+BAA+B,CAAC,MAAM,EAAE;IAC5D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAahB;AAiBD,KAAK,uBAAuB,GAAG;IAC7B,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;IACrB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B,CAAC;AAEF,wBAAsB,wBAAwB,CAAC,MAAM,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7F;AAED,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,uBAAuB,EAAE,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAClE,OAAO,CAAC,IAAI,CAAC,CAEf;AA8GD,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,OAAO,EAAE,iCAAiC,EAAE,MAAM,oBAAoB,CAAC;AAEvE,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}

package/node_modules/@openclaw/fs-safe/dist/archive-staging.js

@@ -0,0 +1,250 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
+import { ownExtractionDestinationMutation, } from "./archive-deadline.js";
+import { ArchiveSecurityError, } from "./archive-errors.js";
+import { FsSafeError } from "./errors.js";
+import { formatErrorDetail } from "./error-detail.js";
+import { root } from "./root.js";
+import { isNotFoundPathError, isPathInside } from "./path.js";
+import { resolveSecureTempRoot } from "./secure-temp-dir.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
+import { expandRelativePathWithHome } from "./root-context.js";
+import { resolveRootPath } from "./root-path.js";
+const ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK = "archive entry traverses symlink in destination";
+const ARCHIVE_STAGING_MODE = 0o700;
+function checkExtractionDeadline(deadline) {
+    deadline?.check();
+}
+export { ArchiveSecurityError } from "./archive-errors.js";
+function symlinkTraversalError(originalPath) {
+    return new ArchiveSecurityError("destination-symlink-traversal", `${ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK}: ${formatErrorDetail(originalPath)}`);
+}
+export async function createDirectoryIdentityGuard(dir) {
+    try {
+        return await createAsyncDirectoryGuard(dir);
+    }
+    catch (err) {
+        if (err instanceof FsSafeError && err.code === "not-file") {
+            throw new ArchiveSecurityError("destination-symlink", "archive destination is a symlink");
+        }
+        throw err;
+    }
+}
+export async function assertDirectoryIdentityGuard(guard) {
+    try {
+        await assertAsyncDirectoryGuard(guard);
+    }
+    catch (err) {
+        if (err instanceof FsSafeError) {
+            throw new ArchiveSecurityError("destination-symlink-traversal", "archive destination changed during extraction");
+        }
+        throw err;
+    }
+}
+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");
+    }
+    const realPath = await fs.realpath(destDir);
+    const realStat = await fs.stat(realPath);
+    const postStat = await fs.lstat(destDir);
+    if (realStat.dev !== stat.dev ||
+        realStat.ino !== stat.ino ||
+        postStat.isSymbolicLink() ||
+        !postStat.isDirectory() ||
+        postStat.dev !== stat.dev ||
+        postStat.ino !== stat.ino) {
+        throw new ArchiveSecurityError("destination-symlink-traversal", "archive destination changed during extraction");
+    }
+    return realPath;
+}
+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);
+        }
+    }
+}
+export 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);
+    }
+}
+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) {
+    await prepareOutputPath(params);
+}
+export async function preparePrivateArchiveOutputPath(params, assertGuards) {
+    await prepareOutputPath(params, assertGuards, true);
+}
+async function prepareOutputPath(params, assertGuards, privateWorkingMode = false) {
+    checkExtractionDeadline(params.deadline);
+    const targetRoot = privateWorkingMode ? {
+        async mkdir(relativePath) {
+            // Retain Root.mkdir's strict alias admission before the shared traversal,
+            // while selecting private creation modes without adding a public option.
+            const resolved = await resolveRootPath({
+                absolutePath: path.resolve(params.destinationRealDir, await expandRelativePathWithHome(relativePath)),
+                rootPath: params.destinationRealDir,
+                rootCanonicalPath: params.destinationRealDir,
+                boundaryLabel: "archive destination",
+                rejectSymlinks: true,
+            });
+            checkExtractionDeadline(params.deadline);
+            await mkdirPathComponentsWithGuards({
+                rootReal: params.destinationRealDir,
+                targetPath: resolved.canonicalPath,
+                mode: 0o700,
+                rejectSymlinks: true,
+                beforeComponent: async () => {
+                    await assertDirectoryIdentityGuard(destinationGuard);
+                    checkExtractionDeadline(params.deadline);
+                    await assertGuards?.();
+                    checkExtractionDeadline(params.deadline);
+                },
+            });
+        },
+    } : await root(params.destinationRealDir);
+    checkExtractionDeadline(params.deadline);
+    const destinationGuard = await createDirectoryIdentityGuard(params.destinationRealDir);
+    checkExtractionDeadline(params.deadline);
+    const relPath = params.relPath.split(path.sep).join(path.posix.sep);
+    await assertNoSymlinkTraversal({
+        rootDir: params.destinationDir,
+        relPath,
+        originalPath: params.originalPath,
+    });
+    checkExtractionDeadline(params.deadline);
+    if (params.isDirectory) {
+        await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("mkdir", params.outPath);
+        checkExtractionDeadline(params.deadline);
+        await ownExtractionDestinationMutation(params.deadline, async () => {
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
+            await assertGuards?.();
+            checkExtractionDeadline(params.deadline);
+            await mkdirArchiveOutput({
+                targetRoot,
+                relativePath: relPath,
+                originalPath: params.originalPath,
+            });
+            checkExtractionDeadline(params.deadline);
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
+            await assertResolvedInsideDestination({
+                destinationRealDir: params.destinationRealDir,
+                targetPath: params.outPath,
+                originalPath: params.originalPath,
+            });
+            checkExtractionDeadline(params.deadline);
+        });
+        return;
+    }
+    const parentRel = path.posix.dirname(relPath);
+    if (parentRel !== ".") {
+        await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("mkdir", path.dirname(params.outPath));
+        checkExtractionDeadline(params.deadline);
+        await ownExtractionDestinationMutation(params.deadline, async () => {
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
+            await assertGuards?.();
+            checkExtractionDeadline(params.deadline);
+            await mkdirArchiveOutput({
+                targetRoot,
+                relativePath: parentRel,
+                originalPath: params.originalPath,
+            });
+            checkExtractionDeadline(params.deadline);
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
+        });
+    }
+    await assertResolvedInsideDestination({
+        destinationRealDir: params.destinationRealDir,
+        targetPath: path.dirname(params.outPath),
+        originalPath: params.originalPath,
+    });
+    checkExtractionDeadline(params.deadline);
+}
+function assertSafeArchiveStagingPrefix(prefix) {
+    if (!prefix ||
+        prefix === "." ||
+        prefix === ".." ||
+        prefix.includes("/") ||
+        prefix.includes("\\") ||
+        path.basename(prefix) !== prefix) {
+        throw new Error("archive staging prefix must be a single path segment");
+    }
+    return prefix;
+}
+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 stagingPrefix = assertSafeArchiveStagingPrefix(params.stagingDirPrefix ?? "fs-safe-archive-");
+    const stagingDir = await fs.mkdtemp(path.join(stagingRoot, stagingPrefix));
+    const stagingGuard = await createDirectoryIdentityGuard(stagingDir);
+    try {
+        await fs.chmod(stagingDir, ARCHIVE_STAGING_MODE).catch(() => undefined);
+        await assertDirectoryIdentityGuard(stagingGuard);
+        return await params.run(stagingDir);
+    }
+    finally {
+        try {
+            await assertDirectoryIdentityGuard(stagingGuard);
+            await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => undefined);
+        }
+        catch {
+            // The staging path identity changed; deleting by name could target data
+            // outside the private temp tree, so fail closed and leave it for OS cleanup.
+        }
+    }
+}
+export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
+export function createArchiveSymlinkTraversalError(originalPath) {
+    return symlinkTraversalError(originalPath);
+}

package/node_modules/@openclaw/fs-safe/dist/archive-tar-inspect.d.ts

@@ -0,0 +1,7 @@
+import type { ExtractArchiveOptions } from "./archive-options.js";
+import { type ArchivePlanEntry } from "./archive-plan.js";
+export type InspectTarArchiveOptions = Pick<ExtractArchiveOptions, "archivePath" | "timeoutMs" | "limits" | "entryFilter" | "onFiltered">;
+export type InspectedTarEntry = Readonly<Pick<ArchivePlanEntry, "path" | "kind" | "size">>;
+/** Complete TAR/gzip admission and zero-strip extraction policy, without output writes. */
+export declare function inspectTarArchive(params: InspectTarArchiveOptions): Promise<readonly InspectedTarEntry[]>;
+//# sourceMappingURL=archive-tar-inspect.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/archive-tar-inspect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-tar-inspect.d.ts","sourceRoot":"","sources":["../src/archive-tar-inspect.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAOrF,MAAM,MAAM,wBAAwB,GAAG,IAAI,CAAC,qBAAqB,EAC/D,aAAa,GAAG,WAAW,GAAG,QAAQ,GAAG,aAAa,GAAG,YAAY,CAAC,CAAC;AACzE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC,IAAI,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;AAE3F,2FAA2F;AAC3F,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,wBAAwB,GAAG,OAAO,CAAC,SAAS,iBAAiB,EAAE,CAAC,CA2C/G"}

package/node_modules/@openclaw/fs-safe/dist/archive-tar-inspect.js

@@ -0,0 +1,59 @@
+import { withExtractionDeadline } from "./archive-deadline.js";
+import { validateArchiveEntryPath } from "./archive-entry.js";
+import { stageArchiveFileForExtraction } from "./archive-input.js";
+import { resolveExtractLimits, resolveTarMeterLimits } from "./archive-limits.js";
+import { throwMappedNativeArchiveError } from "./archive-native.js";
+import { createArchiveEntryPlanner } from "./archive-plan.js";
+import { resolveArchiveFilteredEntryPolicy } from "./archive-policy.js";
+import { createTarEntryPlanner } from "./archive-tar.js";
+import { inspectTar } from "./archive-tar-stream.js";
+import { getNativeBinding } from "./native.js";
+/** Complete TAR/gzip admission and zero-strip extraction policy, without output writes. */
+export async function inspectTarArchive(params) {
+    const onFiltered = resolveArchiveFilteredEntryPolicy(params.onFiltered);
+    const limits = resolveExtractLimits(params.limits);
+    const tarLimits = resolveTarMeterLimits(limits);
+    const native = getNativeBinding();
+    return await withExtractionDeadline(params.timeoutMs, "inspect tar", async (deadline) => {
+        const staged = await stageArchiveFileForExtraction({ archivePath: params.archivePath, limits, deadline });
+        try {
+            // Staging closes descriptors asynchronously; expiry there must not start a decoder.
+            deadline.check();
+            const entries = [];
+            const append = (entry) => {
+                if (entry)
+                    entries.push(Object.freeze({ path: entry.path, kind: entry.kind, size: entry.size }));
+            };
+            const policy = { limits, entryFilter: params.entryFilter, onFiltered };
+            if (native) {
+                const manifest = await native.inspectArchiveNative(staged.path, "tar", tarLimits, deadline.signal)
+                    .catch(throwMappedNativeArchiveError);
+                deadline.check();
+                // Match extraction's whole-manifest validation before caller policy runs.
+                for (const entry of manifest)
+                    validateArchiveEntryPath(entry.path);
+                const planEntry = createArchiveEntryPlanner(policy, "tar");
+                for (const entry of manifest) {
+                    deadline.check();
+                    append(planEntry(entry));
+                }
+            }
+            else {
+                const manifest = [];
+                await inspectTar({ archivePath: staged.path, limits: tarLimits, signal: deadline.signal,
+                    onMember: (entry) => { manifest.push(entry); } });
+                const planEntry = createTarEntryPlanner(policy);
+                for (const entry of manifest) {
+                    deadline.check();
+                    append(planEntry(entry));
+                }
+            }
+            deadline.check();
+            // This is bounded evidence about the staged bytes, not a reusable write plan.
+            return Object.freeze(entries);
+        }
+        finally {
+            await staged.cleanup();
+        }
+    });
+}

package/node_modules/@openclaw/fs-safe/dist/archive-tar-stream.d.ts

@@ -0,0 +1,18 @@
+import type { TarMeterLimits } from "./archive-limits.js";
+import { type AdmittedTarMember } from "./archive-tar-wasm.js";
+export declare function inspectTar(params: {
+    archivePath: string;
+    limits: TarMeterLimits;
+    signal?: AbortSignal;
+    onMember?: (entry: AdmittedTarMember) => void;
+}): Promise<void>;
+/** Replay in physical order, retaining at most one decoded chunk. Every range
+ * comes from complete admission of the immutable staged input. */
+export declare function replayTar<T extends AdmittedTarMember>(params: {
+    archivePath: string;
+    limits: TarMeterLimits;
+    signal?: AbortSignal;
+    members: readonly T[];
+    consume(member: T, payload: AsyncIterable<Buffer>): Promise<void>;
+}): Promise<void>;
+//# sourceMappingURL=archive-tar-stream.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/archive-tar-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-tar-stream.d.ts","sourceRoot":"","sources":["../src/archive-tar-stream.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,EAAmB,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AA4ChF,wBAAsB,UAAU,CAAC,MAAM,EAAE;IACvC,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAClE,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC/C,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AAED;kEACkE;AAClE,wBAAsB,SAAS,CAAC,CAAC,SAAS,iBAAiB,EAAE,MAAM,EAAE;IACnE,WAAW,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAClE,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;IACtB,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8BhB"}