@openclaw/fs-safe 0.5.6 → 0.7.0

package/dist/archive-native.js

@@ -1,12 +1,13 @@
 import { constants as fsConstants } from "node:fs";
 import fs from "node:fs/promises";
-import { ArchiveFormatError, ArchiveSecurityError, isArchiveFormatErrorMessage, } from "./archive-errors.js";
+import { ArchiveFormatError, ArchiveSecurityError, isArchiveFormatErrorMessage, isArchiveTarPathErrorMessage, } from "./archive-errors.js";
 import { formatErrorDetail } from "./error-detail.js";
 import { createArchiveOutputPathTracker, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 import { stageArchiveFileForExtraction } from "./archive-input.js";
-import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, resolveExtractLimits, } from "./archive-limits.js";
+import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, } from "./archive-limits.js";
 import { resolveArchiveEntryMode, shouldExtractArchiveEntry } from "./archive-policy.js";
 import { mergeExtractedTreeIntoDestination, prepareArchiveDestinationDir, withStagedArchiveDestination, } from "./archive-staging.js";
+import { admitZipFile } from "./archive-zip-admission.js";
 function policyKind(kind) {
     if (kind === "file" || kind === "directory")
         return kind;
@@ -16,6 +17,9 @@ function policyKind(kind) {
 }
 function throwMappedNativeError(error) {
     if (error instanceof Error) {
+        if (isArchiveTarPathErrorMessage(error.message)) {
+            throw new ArchiveSecurityError("entry-path", error.message, { cause: error });
+        }
         for (const code of Object.values(ARCHIVE_LIMIT_ERROR_CODE)) {
             if (error.message.includes(code))
                 throw new ArchiveLimitError(code);
@@ -30,23 +34,35 @@ function throwMappedNativeError(error) {
     throw error;
 }
 export async function extractNativeArchive(params) {
-    const limits = resolveExtractLimits(params.limits);
+    const { limits, tarLimits } = params;
     const stagedArchive = await stageArchiveFileForExtraction({
         archivePath: params.archivePath,
         limits,
         deadline: params.deadline,
     });
     try {
+        const physicalCount = params.kind === "zip"
+            ? await admitZipFile(stagedArchive.path, limits, params.deadline)
+            : undefined;
         const destinationRealDir = await prepareArchiveDestinationDir(params.destDir);
         await withStagedArchiveDestination({
             destinationRealDir,
             run: async (stagingDir) => {
                 params.deadline.check();
                 const manifest = await params.binding
-                    .inspectArchiveNative(stagedArchive.path, params.kind, limits.maxEntries, limits.maxMetaEntryBytes, limits.maxArchiveBytes, params.deadline.signal)
+                    .inspectArchiveNative(stagedArchive.path, params.kind, tarLimits, params.deadline.signal)
                     .catch(throwMappedNativeError);
                 params.deadline.check();
                 assertArchiveEntryCountWithinLimit(manifest.length, limits);
+                if (physicalCount !== undefined && manifest.length !== physicalCount) {
+                    throw new ArchiveSecurityError("entry-path", "zip decoder collapsed entry names");
+                }
+                // Recheck the native manifest at the shared policy boundary before
+                // any caller callback observes an entry.
+                if (params.kind !== "zip") {
+                    for (const entry of manifest)
+                        validateArchiveEntryPath(entry.path);
+                }
                 const strip = Math.max(0, Math.floor(params.stripComponents ?? 0));
                 const budget = createByteBudgetTracker(limits);
                 const trackOutputPath = createArchiveOutputPathTracker();
@@ -54,7 +70,10 @@ export async function extractNativeArchive(params) {
                 for (const entry of manifest) {
                     params.deadline.check();
                     validateArchiveEntryPath(entry.path);
-                    const relPath = stripArchivePath(entry.path, strip);
+                    const canonicalPath = stripArchivePath(entry.path, 0);
+                    if (!canonicalPath)
+                        continue;
+                    const relPath = stripArchivePath(canonicalPath, strip);
                     if (!relPath)
                         continue;
                     validateArchiveEntryPath(relPath);
@@ -65,21 +84,22 @@ export async function extractNativeArchive(params) {
                     if (!shouldExtractArchiveEntry({
                         filter: params.entryFilter,
                         onFiltered: params.onFiltered,
-                        entry: { path: entry.path, kind, size: entry.size },
+                        entry: { path: canonicalPath, kind, size: entry.size },
                     })) {
                         continue;
                     }
                     if (entry.kind === "sparse") {
                         throw new ArchiveFormatError(`GNU sparse archive entry is not supported: ${formatErrorDetail(entry.path)}`);
                     }
-                    if (kind === "symlink") {
+                    if (kind === "symlink" || entry.kind === "blocked") {
                         const label = params.kind === "zip" ? "zip" : "tar";
                         throw new ArchiveSecurityError("entry-link", `${label} entry is a link: ${formatErrorDetail(entry.path)}`);
                     }
                     if (!Number.isSafeInteger(entry.size) || entry.size < 0) {
                         throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
                     }
-                    if (kind === "file") {
+                    // GNUDumpDir can carry a body; charge accepted TAR sizes as JS does.
+                    if (kind === "file" || (kind === "directory" && params.kind !== "zip")) {
                         budget.startEntry();
                         budget.addEntrySize(entry.size);
                     }
@@ -101,7 +121,7 @@ export async function extractNativeArchive(params) {
                     (typeof fsConstants.O_DIRECTORY === "number" ? fsConstants.O_DIRECTORY : 0));
                 try {
                     params.deadline.check();
-                    await params.binding.extractArchiveNative(stagedArchive.path, params.kind, directory.fd, plan, limits.maxMetaEntryBytes, params.deadline.signal).catch(throwMappedNativeError);
+                    await params.binding.extractArchiveNative(stagedArchive.path, params.kind, directory.fd, plan, tarLimits, params.deadline.signal).catch(throwMappedNativeError);
                 }
                 finally {
                     await directory.close().catch(() => undefined);
@@ -111,7 +131,9 @@ export async function extractNativeArchive(params) {
                     sourceDir: stagingDir,
                     destinationDir: params.destDir,
                     destinationRealDir,
+                    deadline: params.deadline,
                 });
+                params.deadline.check();
             },
         });
     }

package/dist/archive-policy.d.ts

@@ -2,6 +2,7 @@ export type ArchiveEntryKind = "file" | "directory" | "symlink" | "other";
 export type ArchiveEntryModePolicy = "clamp" | "preserve";
 export type ArchiveFilteredEntryPolicy = "reject-archive" | "skip-entry";
 export type ArchiveEntryFilter = (entry: {
+    /** Validated canonical archive path before stripping: / separators, no empty or . components. */
     path: string;
     kind: ArchiveEntryKind;
     size: number;
@@ -12,6 +13,7 @@ export declare function resolveArchiveEntryMode(params: {
     archivedMode?: number;
     policy?: ArchiveEntryModePolicy;
 }): number;
+export declare function resolveArchiveFilteredEntryPolicy(value: unknown): ArchiveFilteredEntryPolicy;
 export declare function shouldExtractArchiveEntry(params: {
     filter?: ArchiveEntryFilter;
     onFiltered?: ArchiveFilteredEntryPolicy;

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

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

package/dist/archive-policy.js

@@ -19,11 +19,19 @@ export function resolveArchiveEntryMode(params) {
     }
     return archivedMode & 0o100 ? 0o755 : 0o644;
 }
+export function resolveArchiveFilteredEntryPolicy(value) {
+    if (value === undefined || value === "reject-archive")
+        return "reject-archive";
+    if (value === "skip-entry")
+        return "skip-entry";
+    throw new RangeError('archive onFiltered must be "reject-archive" or "skip-entry"');
+}
 export function shouldExtractArchiveEntry(params) {
+    const onFiltered = resolveArchiveFilteredEntryPolicy(params.onFiltered);
     if (!params.filter || params.filter(params.entry) === "extract") {
         return true;
     }
-    if ((params.onFiltered ?? "reject-archive") === "reject-archive") {
+    if (onFiltered === "reject-archive") {
         throw new ArchiveSecurityError("entry-filtered", `archive entry rejected by filter: ${formatErrorDetail(params.entry.path)}`);
     }
     return false;

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

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

package/dist/archive-read.js

@@ -1,27 +1,32 @@
-import fsSync from "node:fs";
 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 { ArchiveFormatError, ArchiveSecurityError, isArchiveFormatErrorMessage, isArchiveTarPathErrorMessage, } from "./archive-errors.js";
 import { formatErrorDetail } from "./error-detail.js";
-import { normalizeArchiveEntryPath, validateArchiveEntryPath, } from "./archive-entry.js";
+import { stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 import { resolveArchiveKind } from "./archive-kind.js";
-import { DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_META_ENTRY_BYTES, ArchiveLimitError, ARCHIVE_LIMIT_ERROR_CODE, } from "./archive-limits.js";
+import { DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_META_ENTRY_BYTES, ArchiveLimitError, ARCHIVE_LIMIT_ERROR_CODE, } from "./archive-limits.js";
 import { readTarEntryInfo } from "./archive-tar.js";
 import { preflightTarMetadata } from "./archive-tar-meta.js";
-import { importOptionalTar, normalizeTarParserError } from "./archive-tar-runtime.js";
+import { importOptionalTar, NODE_TAR_RATIO_DISABLED, normalizeTarParserError } from "./archive-tar-runtime.js";
 import { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
 import { createZipIntegrityTransform, normalizeZipIntegrityError, } from "./archive-zip-integrity.js";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.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 normalizedRequestedEntry(entryPath) {
+function canonicalEntryPath(entryPath) {
     validateArchiveEntryPath(entryPath, { escapeLabel: "archive root" });
-    const normalized = normalizeArchiveEntryPath(entryPath).replace(/^\.\//, "");
-    if (!normalized || normalized.endsWith("/")) {
+    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;
@@ -60,30 +65,37 @@ async function readStreamBounded(stream, maxBytes) {
 }
 async function stageArchiveInput(archivePath) {
     const resolved = await fs.realpath(archivePath);
-    const before = await fs.lstat(archivePath);
-    if (before.isSymbolicLink() || !before.isFile()) {
-        throw new Error(`archive is not a regular file: ${archivePath}`);
-    }
-    const noFollow = process.platform !== "win32" && typeof fsSync.constants.O_NOFOLLOW === "number"
-        ? fsSync.constants.O_NOFOLLOW
-        : 0;
-    const handle = await fs.open(resolved, fsSync.constants.O_RDONLY | noFollow);
+    const 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());
     const staged = await tempFile({ prefix: "fs-safe-archive-read", fileName: "archive.bin" });
     try {
-        const opened = await handle.stat();
-        const current = await fs.lstat(resolved);
-        if (!opened.isFile() ||
-            !current.isFile() ||
-            !sameFileIdentity(before, opened) ||
-            !sameFileIdentity(current, opened)) {
-            throw new Error("archive changed during validation");
-        }
+        const 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 {
@@ -96,7 +108,17 @@ async function readZipEntry(buffer, entryPath, maxBytes) {
         maxEntryBytes: maxBytes,
         maxExtractedBytes: maxBytes,
     });
-    const entry = archive.files[entryPath];
+    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)}`);
     }
@@ -113,28 +135,41 @@ async function readZipEntry(buffer, entryPath, maxBytes) {
 }
 async function readTarEntry(archivePath, entryPath, maxBytes) {
     const tar = await importOptionalTar();
+    const seenPaths = new Set();
     await preflightTarMetadata({
         archivePath,
-        maxMetaEntryBytes: DEFAULT_MAX_META_ENTRY_BYTES,
+        limits: resolveTarMeterLimits(),
+        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 && !["File", "OldFile", "ContiguousFile"].includes(info.type)) {
+                throw new Error(`archive entry is not a file: ${formatErrorDetail(entryPath)}`);
+            }
+        },
     });
     let matched;
     let entryError;
-    const seenPaths = new Set();
     try {
         await tar.t({
             file: archivePath,
             strict: true,
             maxMetaEntrySize: DEFAULT_MAX_META_ENTRY_BYTES,
+            maxDecompressionRatio: NODE_TAR_RATIO_DISABLED,
             onReadEntry(entry) {
                 const info = readTarEntryInfo(entry);
-                validateArchiveEntryPath(info.path, { escapeLabel: "archive root" });
-                const normalized = normalizeArchiveEntryPath(info.path).replace(/^\.\//, "");
-                if (seenPaths.has(normalized)) {
-                    entryError ??= new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(normalized)}`);
+                let normalized;
+                try {
+                    normalized = canonicalEntryPath(info.path);
+                }
+                catch (error) {
+                    // Throws escaping node-tar's callback do not reject its promise.
+                    entryError ??= error instanceof Error ? error : new Error(String(error));
                     entry.resume();
                     return;
                 }
-                seenPaths.add(normalized);
                 if (normalized !== entryPath) {
                     entry.resume();
                     return;
@@ -175,16 +210,22 @@ export async function readArchiveEntry(archivePath, entryPath, options) {
     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 manifest = await native.inspectArchiveNative(staged.path, kind, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_META_ENTRY_BYTES, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, 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) {
-                    validateArchiveEntryPath(entry.path, { escapeLabel: "archive root" });
-                    const normalized = normalizeArchiveEntryPath(entry.path).replace(/^\.\//, "");
+                    const normalized = canonicalEntryPath(entry.path);
                     if (seenPaths.has(normalized)) {
                         throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(normalized)}`);
                     }
@@ -199,12 +240,17 @@ export async function readArchiveEntry(archivePath, entryPath, options) {
                 if (!rawEntryPath) {
                     throw new Error(`archive entry not found: ${formatErrorDetail(entryPath)}`);
                 }
-                return await native.readArchiveEntryNative(staged.path, kind, rawEntryPath, options.maxBytes, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_META_ENTRY_BYTES, signal);
+                return await native.readArchiveEntryNative(staged.path, kind, rawEntryPath, options.maxBytes, limits, signal);
             }
             catch (error) {
-                if (error instanceof Error &&
-                    error.message.includes(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT)) {
-                    throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
+                if (error instanceof Error && isArchiveTarPathErrorMessage(error.message)) {
+                    throw new ArchiveSecurityError("entry-path", error.message, { cause: error });
+                }
+                if (error instanceof Error) {
+                    for (const code of Object.values(ARCHIVE_LIMIT_ERROR_CODE)) {
+                        if (error.message.includes(code))
+                            throw new ArchiveLimitError(code);
+                    }
                 }
                 if (error instanceof Error && isArchiveFormatErrorMessage(error.message)) {
                     throw new ArchiveFormatError(error.message, { cause: error });
@@ -213,7 +259,8 @@ export async function readArchiveEntry(archivePath, entryPath, options) {
             }
         }
         if (kind === "tar-zstd" || kind === "tar-bzip2") {
-            throw new FsSafeError("helper-unavailable", `${kind} archives require a supported bundled native binding`);
+            throw new FsSafeError("helper-unavailable", `${kind} archives require the matching optional native platform package; ` +
+                "install @openclaw/fs-safe with optional dependencies enabled on a supported platform and use FS_SAFE_NATIVE_MODE=auto or require");
         }
         return kind === "zip"
             ? await readZipEntry(staged.buffer, requestedEntry, options.maxBytes)

package/dist/archive-staging.d.ts

@@ -1,3 +1,4 @@
+import { type ExtractionDeadline } from "./archive-deadline.js";
 import { ArchiveSecurityError } from "./archive-errors.js";
 export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-errors.js";
 export declare function prepareArchiveDestinationDir(destDir: string): Promise<string>;
@@ -8,6 +9,7 @@ export declare function prepareArchiveOutputPath(params: {
     outPath: string;
     originalPath: string;
     isDirectory: boolean;
+    deadline?: ExtractionDeadline;
 }): Promise<void>;
 export declare function withStagedArchiveDestination<T>(params: {
     destinationRealDir: string;
@@ -18,6 +20,7 @@ export declare function mergeExtractedTreeIntoDestination(params: {
     sourceDir: string;
     destinationDir: string;
     destinationRealDir: string;
+    deadline?: ExtractionDeadline;
 }): Promise<void>;
 export declare function createArchiveSymlinkTraversalError(originalPath: string): ArchiveSecurityError;
 //# sourceMappingURL=archive-staging.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,oBAAoB,EAErB,MAAM,qBAAqB,CAAC;AAW7B,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAkC1F,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BnF;AA4DD,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuChB;AAyHD,wBAAsB,4BAA4B,CAAC,CAAC,EAAE,MAAM,EAAE;IAC5D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzC,GAAG,OAAO,CAAC,CAAC,CAAC,CA6Bb;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,GAAG,OAAO,CAAC,IAAI,CAAC,CAkFhB;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}
+{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAOA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,oBAAoB,EAErB,MAAM,qBAAqB,CAAC;AAgB7B,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAkC1F,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BnF;AA4DD,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B,GAAG,OAAO,CAAC,IAAI,CAAC,CA6DhB;AAsID,wBAAsB,4BAA4B,CAAC,CAAC,EAAE,MAAM,EAAE;IAC5D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzC,GAAG,OAAO,CAAC,CAAC,CAAC,CA6Bb;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,kBAAkB,CAAC;CAC/B,GAAG,OAAO,CAAC,IAAI,CAAC,CA8FhB;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}