@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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

@@ -1,24 +1,28 @@
 import { classifyArchiveParserError } from "./archive-parser-errors.js";
+import fsSync from "node:fs";
 import fs from "node:fs/promises";
-import { Readable } from "node:stream";
-import { readFileHandleBounded } from "./bounded-read.js";
+import { Readable, Writable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { readBoundedAsync } 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 { resolveArchiveKind } from "./archive-kind.js";
 import { DEFAULT_MAX_ARCHIVE_BYTES_ZIP, ArchiveLimitError, ARCHIVE_LIMIT_ERROR_CODE, } from "./archive-limits.js";
+import { isGzipBuffer } from "./archive-gzip-tail.js";
 import { inspectTar, replayTar } from "./archive-tar-stream.js";
-import { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
+import { loadAdmittedZipArchive } from "./archive-zip-loader.js";
 import { createZipIntegrityTransform, normalizeZipIntegrityError, } from "./archive-zip-integrity.js";
+import { isZipSymlinkEntry, zipEntryKind } from "./archive-zip-entry.js";
 import { FsSafeError } from "./errors.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { realpathSync } from "./realpath.js";
 import { getNativeBinding } from "./native.js";
 import { admitZipBuffer } from "./archive-zip-admission.js";
+import { validateNativeZipManifest } from "./archive-zip-manifest.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;
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 function canonicalEntryPath(entryPath) {
     validateArchiveEntryPath(entryPath, { escapeLabel: "archive root" });
     return stripArchivePath(entryPath, 0) ?? "";
@@ -30,69 +34,55 @@ function normalizedRequestedEntry(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 = [];
+async function readAdmittedTarPayload(stream, size) {
+    // Complete admission has bounded this exact range. Copy as it arrives so
+    // decoder chunks can be released before the caller receives the owned result.
+    const result = Buffer.allocUnsafe(size);
     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);
+        if (chunk.length > size - total) {
+            throw new ArchiveFormatError("invalid admitted TAR payload size");
         }
-        chunks.push(buffer);
+        chunk.copy(result, total);
+        total += chunk.length;
     }
-    return Buffer.concat(chunks, total);
+    if (total !== size)
+        throw new ArchiveFormatError("truncated admitted TAR range");
+    return result;
 }
-async function stageArchiveInput(archivePath) {
-    const resolved = await fs.realpath(archivePath);
+async function readArchiveInput(archivePath) {
+    assertNoWindowsPathAlias(archivePath);
+    const resolved = realpathSync.native(archivePath);
+    assertNoWindowsPathAlias(resolved);
     const before = await inspectFileIdentity(async () => {
-        const stat = await fs.lstat(archivePath, { bigint: true });
+        const stat = fsSync.lstatSync(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 });
+            const stat = fsSync.fstatSync(handle.fd, { 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 });
+            const stat = fsSync.lstatSync(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 };
+        // Native archive workers borrow this private buffer. A pooled allocation could
+        // share its ArrayBuffer with unrelated JS buffers while the worker runs.
+        return await readBoundedAsync(DEFAULT_MAX_ARCHIVE_BYTES_ZIP, async (buffer, length) => (await handle.read(buffer, 0, length, null)).bytesRead, { unpooled: true, observeRegularFileSize: () => {
+                const size = fsSync.fstatSync(handle.fd).size;
+                return Number.isSafeInteger(size) && size >= 0 ? size : undefined;
+            } });
     }
     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 });
         }
@@ -102,12 +92,8 @@ async function stageArchiveInput(archivePath) {
         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,
-    });
+async function readZipEntry(buffer, entryPath, maxBytes, admitted) {
+    const archive = await loadAdmittedZipArchive(buffer, admitted);
     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.
@@ -122,22 +108,42 @@ async function readZipEntry(buffer, entryPath, maxBytes) {
     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) {
+    if (isZipSymlinkEntry(entry)) {
         throw new Error(`archive entry is a link: ${formatErrorDetail(entryPath)}`);
     }
+    if (zipEntryKind(entry) !== "file")
+        throw new Error(`archive entry is not a file: ${formatErrorDetail(entryPath)}`);
+    const integrity = createZipIntegrityTransform(entry);
     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);
+    const chunks = [];
+    let total = 0;
+    const destination = new Writable({
+        write(chunk, _encoding, callback) {
+            total += chunk.length;
+            if (total > maxBytes) {
+                callback(new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT));
+                return;
+            }
+            chunks.push(chunk);
+            callback();
+        },
+    });
+    try {
+        // Iterator teardown can mask limit errors on Node 22; keep them in stream callbacks.
+        await pipeline(stream, integrity, destination);
+        return Buffer.concat(chunks, total);
+    }
+    catch (error) {
+        throw normalizeZipIntegrityError(error);
+    }
 }
-async function readTarEntry(archivePath, entryPath, maxBytes) {
+async function readTarEntry(archiveBuffer, entryPath, maxBytes, kind) {
     const seenPaths = new Set();
     let selected;
     const limits = resolveTarMeterLimits();
-    await inspectTar({ archivePath, limits, onMember(info) {
+    await inspectTar({ archiveBuffer, kind, limits, onMember(info) {
             const normalized = canonicalEntryPath(info.path);
             if (seenPaths.has(normalized)) {
                 throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(normalized)}`);
@@ -153,12 +159,68 @@ async function readTarEntry(archivePath, entryPath, maxBytes) {
     }
     if (selected.size > maxBytes)
         throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
+    if (kind === "tar" && !isGzipBuffer(archiveBuffer)) {
+        // Complete admission already validated this private snapshot through EOF.
+        // Copy the admitted payload so the result cannot expose or mutate its input.
+        const end = selected.offset + selected.size;
+        if (!Number.isSafeInteger(selected.offset) || selected.offset < 0 ||
+            !Number.isSafeInteger(end) || end < selected.offset || end > archiveBuffer.length) {
+            throw new ArchiveFormatError("invalid admitted TAR range");
+        }
+        return Buffer.from(archiveBuffer.subarray(selected.offset, end));
+    }
     let result;
-    await replayTar({ archivePath, limits, members: [selected], async consume(_member, payload) {
-            result = await readStreamBounded(payload, maxBytes);
+    await replayTar({ archiveBuffer, kind, limits, members: [selected], async consume(member, payload) {
+            result = await readAdmittedTarPayload(payload, member.size);
         } });
     return result;
 }
+function selectNativeEntry(manifest, requested, displayPath) {
+    const seen = new Set();
+    let selected;
+    for (const entry of manifest) {
+        const normalized = canonicalEntryPath(entry.path);
+        if (seen.has(normalized)) {
+            throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(normalized)}`);
+        }
+        seen.add(normalized);
+        if (normalized === requested) {
+            if (entry.kind !== "file")
+                throw new Error(`archive entry is not a file: ${formatErrorDetail(displayPath)}`);
+            selected = entry;
+        }
+    }
+    if (!selected)
+        throw new Error(`archive entry not found: ${formatErrorDetail(displayPath)}`);
+    return selected;
+}
+function throwNativeReadError(error) {
+    if (error instanceof Error) {
+        const mapped = classifyArchiveParserError(error.message, { cause: error });
+        if (mapped)
+            throw mapped;
+        if (isArchiveFormatErrorMessage(error.message))
+            throw new ArchiveFormatError(error.message, { cause: error });
+    }
+    throw error;
+}
+async function readNativeBufferEntry(native, buffer, kind, requested, displayPath, maxBytes, zipEntries) {
+    try {
+        const signal = new AbortController().signal;
+        const limits = resolveTarMeterLimits();
+        const reader = kind === "zip"
+            ? await native.openZipBufferNative(buffer, limits, AbortSignal.any([signal]))
+            : await native.openTarBufferNative(buffer, kind, limits, AbortSignal.any([signal]));
+        const manifest = reader.entries;
+        if (kind === "zip")
+            validateNativeZipManifest(manifest, zipEntries);
+        const selected = selectNativeEntry(manifest, requested, displayPath);
+        return await reader.readEntry(selected.index, maxBytes, AbortSignal.any([signal]));
+    }
+    catch (error) {
+        throwNativeReadError(error);
+    }
+}
 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");
@@ -168,58 +230,14 @@ export async function readArchiveEntry(archivePath, entryPath, options) {
         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();
-    }
+    assertNoWindowsPathAlias(archivePath, "filesystem", "archive source uses a Windows filesystem namespace alias");
+    const buffer = await readArchiveInput(archivePath);
+    const zipEntries = [];
+    if (kind === "zip")
+        admitZipBuffer(buffer, resolveExtractLimits(), entry => { zipEntries.push(entry); });
+    const native = getNativeBinding();
+    if (native)
+        return await readNativeBufferEntry(native, buffer, kind, requestedEntry, entryPath, options.maxBytes, zipEntries);
+    return kind === "zip" ? await readZipEntry(buffer, requestedEntry, options.maxBytes, zipEntries)
+        : await readTarEntry(buffer, requestedEntry, options.maxBytes, kind);
 }

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

@@ -1,9 +1,12 @@
+import { type BigIntStats } from "node:fs";
 import { type AsyncDirectoryGuard } from "./directory-guard.js";
 import { type ExtractionDeadline } from "./archive-deadline.js";
 import { ArchiveSecurityError } from "./archive-errors.js";
+export type ArchiveDirectoryGuard = AsyncDirectoryGuard<BigIntStats>;
 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 createDirectoryIdentityGuard(dir: string): Promise<ArchiveDirectoryGuard>;
+export declare function assertDirectoryIdentityGuard(guard: ArchiveDirectoryGuard): Promise<void>;
+export declare function prepareArchiveDestinationGuard(destDir: string): Promise<ArchiveDirectoryGuard>;
 export declare function prepareArchiveDestinationDir(destDir: string): Promise<string>;
 export declare function assertResolvedInsideDestination(params: {
     destinationRealDir: string;
@@ -20,7 +23,7 @@ type ArchiveOutputPathParams = {
     deadline?: ExtractionDeadline;
 };
 export declare function prepareArchiveOutputPath(params: ArchiveOutputPathParams): Promise<void>;
-export declare function preparePrivateArchiveOutputPath(params: ArchiveOutputPathParams, assertGuards?: () => Promise<void>): Promise<void>;
+export declare function preparePrivateArchiveOutputPath(params: ArchiveOutputPathParams, assertGuards?: () => Promise<void>, destinationGuard?: ArchiveDirectoryGuard): Promise<void>;
 export declare function withStagedArchiveDestination<T>(params: {
     destinationRealDir: string;
     stagingDirPrefix?: string;
@@ -28,4 +31,3 @@ export declare function withStagedArchiveDestination<T>(params: {
 }): 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.js

@@ -1,3 +1,4 @@
+import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
@@ -12,6 +13,9 @@ import { getFsSafeTestHooks } from "./test-hooks.js";
 import { mkdirPathComponentsWithGuards } from "./guarded-mkdir.js";
 import { expandRelativePathWithHome } from "./root-context.js";
 import { resolveRootPath } from "./root-path.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { realpathSync } from "./realpath.js";
 const ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK = "archive entry traverses symlink in destination";
 const ARCHIVE_STAGING_MODE = 0o700;
 function checkExtractionDeadline(deadline) {
@@ -22,8 +26,11 @@ function symlinkTraversalError(originalPath) {
     return new ArchiveSecurityError("destination-symlink-traversal", `${ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK}: ${formatErrorDetail(originalPath)}`);
 }
 export async function createDirectoryIdentityGuard(dir) {
+    assertNoWindowsPathAlias(dir);
     try {
-        return await createAsyncDirectoryGuard(dir);
+        const guard = await createAsyncDirectoryGuard(dir, { bigint: true });
+        assertNoWindowsPathAlias(guard.realPath);
+        return guard;
     }
     catch (err) {
         if (err instanceof FsSafeError && err.code === "not-file") {
@@ -37,32 +44,52 @@ export async function assertDirectoryIdentityGuard(guard) {
         await assertAsyncDirectoryGuard(guard);
     }
     catch (err) {
+        if (err instanceof FsSafeError || isNotFoundPathError(err)) {
+            throw new ArchiveSecurityError("destination-symlink-traversal", "archive destination changed during extraction");
+        }
+        throw err;
+    }
+}
+export async function prepareArchiveDestinationGuard(destDir) {
+    assertNoWindowsPathAlias(destDir);
+    let stat;
+    try {
+        stat = inspectFileIdentitySync(() => {
+            const observed = fsSync.lstatSync(destDir, { bigint: true });
+            if (observed.isSymbolicLink()) {
+                throw new ArchiveSecurityError("destination-symlink", "archive destination is a symlink");
+            }
+            if (!observed.isDirectory()) {
+                throw new ArchiveSecurityError("destination-not-directory", "archive destination is not a directory");
+            }
+            return observed;
+        });
+    }
+    catch (err) {
+        if (err instanceof ArchiveSecurityError)
+            throw err;
         if (err instanceof FsSafeError) {
             throw new ArchiveSecurityError("destination-symlink-traversal", "archive destination changed during extraction");
         }
         throw err;
     }
+    const realPath = realpathSync.native(destDir);
+    assertNoWindowsPathAlias(realPath);
+    const guard = { dir: destDir, realPath, stat };
+    try {
+        inspectFileIdentitySync(() => fsSync.statSync(realPath, { bigint: true }), stat);
+        inspectFileIdentitySync(() => fsSync.lstatSync(destDir, { bigint: true }), stat);
+    }
+    catch (err) {
+        if (err instanceof FsSafeError) {
+            throw new ArchiveSecurityError("destination-symlink-traversal", "archive destination changed during extraction");
+        }
+        throw err;
+    }
+    return guard;
 }
 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;
+    return (await prepareArchiveDestinationGuard(destDir)).realPath;
 }
 async function assertNoSymlinkTraversal(params) {
     const parts = params.relPath.split(/[\\/]+/).filter(Boolean);
@@ -71,7 +98,7 @@ async function assertNoSymlinkTraversal(params) {
         current = path.join(current, part);
         let stat;
         try {
-            stat = await fs.lstat(current);
+            stat = fsSync.lstatSync(current);
         }
         catch (err) {
             if (isNotFoundPathError(err)) {
@@ -85,9 +112,14 @@ async function assertNoSymlinkTraversal(params) {
     }
 }
 export async function assertResolvedInsideDestination(params) {
+    const destinationRealDir = params.destinationRealDir;
+    const targetPath = params.targetPath;
+    const originalPath = params.originalPath;
+    assertNoWindowsPathAlias(destinationRealDir);
+    assertNoWindowsPathAlias(targetPath);
     let resolved;
     try {
-        resolved = await fs.realpath(params.targetPath);
+        resolved = realpathSync.native(targetPath);
     }
     catch (err) {
         if (isNotFoundPathError(err)) {
@@ -95,8 +127,9 @@ export async function assertResolvedInsideDestination(params) {
         }
         throw err;
     }
-    if (!isPathInside(params.destinationRealDir, resolved)) {
-        throw symlinkTraversalError(params.originalPath);
+    assertNoWindowsPathAlias(resolved);
+    if (!isPathInside(destinationRealDir, resolved)) {
+        throw symlinkTraversalError(originalPath);
     }
 }
 async function mkdirArchiveOutput(params) {
@@ -110,14 +143,28 @@ async function mkdirArchiveOutput(params) {
         throw error;
     }
 }
+function ownArchiveOutputPathParams(params) {
+    const deadline = params.deadline;
+    checkExtractionDeadline(deadline);
+    const destinationDir = params.destinationDir;
+    const destinationRealDir = params.destinationRealDir;
+    const relPath = params.relPath;
+    const outPath = params.outPath;
+    const originalPath = params.originalPath;
+    const isDirectory = params.isDirectory;
+    assertNoWindowsPathAlias(destinationDir);
+    assertNoWindowsPathAlias(destinationRealDir);
+    assertNoWindowsPathAlias(relPath, "relative");
+    assertNoWindowsPathAlias(outPath);
+    return { destinationDir, destinationRealDir, relPath, outPath, originalPath, isDirectory, deadline };
+}
 export async function prepareArchiveOutputPath(params) {
-    await prepareOutputPath(params);
+    await prepareOutputPath(ownArchiveOutputPathParams(params));
 }
-export async function preparePrivateArchiveOutputPath(params, assertGuards) {
-    await prepareOutputPath(params, assertGuards, true);
+export async function preparePrivateArchiveOutputPath(params, assertGuards, destinationGuard) {
+    await prepareOutputPath(ownArchiveOutputPathParams(params), assertGuards, true, destinationGuard);
 }
-async function prepareOutputPath(params, assertGuards, privateWorkingMode = false) {
-    checkExtractionDeadline(params.deadline);
+async function prepareOutputPath(params, assertGuards, privateWorkingMode = false, existingDestinationGuard) {
     const targetRoot = privateWorkingMode ? {
         async mkdir(relativePath) {
             // Retain Root.mkdir's strict alias admission before the shared traversal,
@@ -136,16 +183,24 @@ async function prepareOutputPath(params, assertGuards, privateWorkingMode = fals
                 mode: 0o700,
                 rejectSymlinks: true,
                 beforeComponent: async () => {
-                    await assertDirectoryIdentityGuard(destinationGuard);
-                    checkExtractionDeadline(params.deadline);
-                    await assertGuards?.();
+                    await assertOutputGuards();
                     checkExtractionDeadline(params.deadline);
                 },
             });
         },
     } : await root(params.destinationRealDir);
     checkExtractionDeadline(params.deadline);
-    const destinationGuard = await createDirectoryIdentityGuard(params.destinationRealDir);
+    const destinationGuard = existingDestinationGuard ?? await createDirectoryIdentityGuard(params.destinationRealDir);
+    const assertOutputGuards = async () => {
+        // The merge's callback verifies this same original destination guard.
+        if (existingDestinationGuard && assertGuards)
+            await assertGuards();
+        else {
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
+            await assertGuards?.();
+        }
+    };
     checkExtractionDeadline(params.deadline);
     const relPath = params.relPath.split(path.sep).join(path.posix.sep);
     await assertNoSymlinkTraversal({
@@ -158,9 +213,7 @@ async function prepareOutputPath(params, assertGuards, privateWorkingMode = fals
         await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("mkdir", params.outPath);
         checkExtractionDeadline(params.deadline);
         await ownExtractionDestinationMutation(params.deadline, async () => {
-            await assertDirectoryIdentityGuard(destinationGuard);
-            checkExtractionDeadline(params.deadline);
-            await assertGuards?.();
+            await assertOutputGuards();
             checkExtractionDeadline(params.deadline);
             await mkdirArchiveOutput({
                 targetRoot,
@@ -184,9 +237,7 @@ async function prepareOutputPath(params, assertGuards, privateWorkingMode = fals
         await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("mkdir", path.dirname(params.outPath));
         checkExtractionDeadline(params.deadline);
         await ownExtractionDestinationMutation(params.deadline, async () => {
-            await assertDirectoryIdentityGuard(destinationGuard);
-            checkExtractionDeadline(params.deadline);
-            await assertGuards?.();
+            await assertOutputGuards();
             checkExtractionDeadline(params.deadline);
             await mkdirArchiveOutput({
                 targetRoot,
@@ -206,6 +257,7 @@ async function prepareOutputPath(params, assertGuards, privateWorkingMode = fals
     checkExtractionDeadline(params.deadline);
 }
 function assertSafeArchiveStagingPrefix(prefix) {
+    assertNoWindowsPathAlias(prefix, "relative");
     if (!prefix ||
         prefix === "." ||
         prefix === ".." ||
@@ -217,16 +269,22 @@ function assertSafeArchiveStagingPrefix(prefix) {
     return prefix;
 }
 export async function withStagedArchiveDestination(params) {
+    const destinationRealDir = params.destinationRealDir;
+    assertNoWindowsPathAlias(destinationRealDir);
     const stagingRoot = resolveSecureTempRoot({
         fallbackPrefix: "fs-safe-archive",
         unsafeFallbackLabel: "archive staging temp dir",
         warn: () => undefined,
     });
-    if (isPathInside(params.destinationRealDir, stagingRoot)) {
+    assertNoWindowsPathAlias(stagingRoot);
+    if (isPathInside(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 stagingDirPrefix = params.stagingDirPrefix;
+    const stagingPrefix = assertSafeArchiveStagingPrefix(stagingDirPrefix ?? "fs-safe-archive-");
+    const stagingPathPrefix = path.join(stagingRoot, stagingPrefix);
+    assertNoWindowsPathAlias(stagingPathPrefix);
+    const stagingDir = await fs.mkdtemp(stagingPathPrefix);
     const stagingGuard = await createDirectoryIdentityGuard(stagingDir);
     try {
         await fs.chmod(stagingDir, ARCHIVE_STAGING_MODE).catch(() => undefined);

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

@@ -1,18 +1,27 @@
+import type { ArchiveKind } from "./archive-kind.js";
 import type { TarMeterLimits } from "./archive-limits.js";
 import { type AdmittedTarMember } from "./archive-tar-wasm.js";
-export declare function inspectTar(params: {
+/** Buffers are private immutable snapshots, just like the staged file route. */
+type TarInput = {
     archivePath: string;
+    archiveBuffer?: never;
+} | {
+    archiveBuffer: Buffer;
+    archivePath?: never;
+};
+export declare function inspectTar(params: TarInput & {
     limits: TarMeterLimits;
     signal?: AbortSignal;
+    kind?: Exclude<ArchiveKind, "zip">;
     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;
+ * comes from complete admission of the immutable input. */
+export declare function replayTar<T extends AdmittedTarMember>(params: TarInput & {
     limits: TarMeterLimits;
     signal?: AbortSignal;
+    kind?: Exclude<ArchiveKind, "zip">;
     members: readonly T[];
     consume(member: T, payload: AsyncIterable<Buffer>): Promise<void>;
 }): Promise<void>;
-//# sourceMappingURL=archive-tar-stream.d.ts.map
+export {};