@openclaw/openshell-sandbox 2026.9.4 → 2026.9.6

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

@@ -1,27 +1,42 @@
-import { resolveArchiveEntryMode, } from "./archive-policy.js";
+import { resolveArchiveEntryMode, } from "./archive-plan.js";
+const admittedMetadata = new WeakMap();
+/** Internal: register only after the complete decoder/admission association. */
+export function registerAdmittedZipEntry(entry, physical) {
+    const mode = physical.creatorSystem === 3 ? physical.externalAttributes >>> 16 : undefined;
+    admittedMetadata.set(entry, { kind: physical.kind, mode, size: physical.size });
+    entry.dir = physical.kind === "directory";
+    // Previously unsupported non-UNIX symlinks must also be recognizable to
+    // public preflight consumers using JSZip's conventional type inspection.
+    entry.unixPermissions = mode ?? (physical.kind === "symlink" ? 0o120000 : null);
+    entry.dosPermissions = physical.creatorSystem === 0 ? physical.externalAttributes & 0x3f : null;
+}
 export function zipEntryIntegrityMetadata(entry) {
     const data = entry._data;
     if (!data || "then" in data)
         return undefined;
     return data;
 }
-export function hasDeferredEmptyZipData(entry) {
-    const data = entry._data;
-    return Boolean(data && "then" in data);
-}
 const ZIP_UNIX_FILE_TYPE_MASK = 0o170000;
 const ZIP_UNIX_SYMLINK_TYPE = 0o120000;
 export function isZipSymlinkEntry(entry) {
-    return (typeof entry.unixPermissions === "number" &&
-        (entry.unixPermissions & ZIP_UNIX_FILE_TYPE_MASK) === ZIP_UNIX_SYMLINK_TYPE);
+    return zipEntryKind(entry) === "symlink";
+}
+export function zipEntryKind(entry) {
+    const metadata = admittedMetadata.get(entry);
+    if (metadata)
+        return metadata.kind;
+    return typeof entry.unixPermissions === "number" &&
+        (entry.unixPermissions & ZIP_UNIX_FILE_TYPE_MASK) === ZIP_UNIX_SYMLINK_TYPE
+        ? "symlink" : entry.dir ? "directory" : "file";
 }
 export function zipEntryMode(entry, policy) {
+    const metadata = admittedMetadata.get(entry);
     return resolveArchiveEntryMode({
         kind: entry.dir ? "directory" : "file",
-        archivedMode: entry.unixPermissions,
+        archivedMode: metadata ? metadata.mode : entry.unixPermissions,
         policy,
     });
 }
 export function zipEntryDeclaredSize(entry) {
-    return Math.max(0, Math.floor(zipEntryIntegrityMetadata(entry)?.uncompressedSize ?? 0));
+    return admittedMetadata.get(entry)?.size ?? Math.max(0, Math.floor(zipEntryIntegrityMetadata(entry)?.uncompressedSize ?? 0));
 }

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

@@ -2,4 +2,3 @@ import { Transform } from "node:stream";
 import { type ZipEntry } from "./archive-zip-entry.js";
 export declare function normalizeZipIntegrityError(error: unknown): Error;
 export declare function createZipIntegrityTransform(entry: ZipEntry): Transform;
-//# sourceMappingURL=archive-zip-integrity.d.ts.map

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

@@ -1,6 +1,6 @@
 import { Transform } from "node:stream";
 import { ArchiveFormatError } from "./archive-errors.js";
-import { hasDeferredEmptyZipData, zipEntryIntegrityMetadata, } from "./archive-zip-entry.js";
+import { zipEntryIntegrityMetadata, } from "./archive-zip-entry.js";
 import { updateCrc32 } from "./archive-crc32.js";
 export function normalizeZipIntegrityError(error) {
     if (error instanceof Error &&
@@ -11,9 +11,8 @@ export function normalizeZipIntegrityError(error) {
 }
 export function createZipIntegrityTransform(entry) {
     const metadata = zipEntryIntegrityMetadata(entry);
-    const deferredEmpty = hasDeferredEmptyZipData(entry);
-    const expectedCrc32 = deferredEmpty ? 0 : metadata?.crc32;
-    const expectedSize = deferredEmpty ? 0 : metadata?.uncompressedSize;
+    const expectedCrc32 = metadata?.crc32;
+    const expectedSize = metadata?.uncompressedSize;
     if (typeof expectedCrc32 !== "number" ||
         !Number.isInteger(expectedCrc32) ||
         typeof expectedSize !== "number" ||

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

@@ -0,0 +1,8 @@
+import type { ZipDirectoryEntry } from "./archive-zip-directory.js";
+import { type ZipEntry } from "./archive-zip-entry.js";
+export type ZipArchiveWithFiles = {
+    files: Record<string, unknown>;
+};
+export declare function admittedZipEntries(archive: ZipArchiveWithFiles): readonly ZipEntry[];
+/** Internal: the caller has admitted these unchanged bytes and their metadata. */
+export declare function loadAdmittedZipArchive(buffer: Buffer | Uint8Array, admitted: ZipDirectoryEntry[]): Promise<ZipArchiveWithFiles>;

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

@@ -0,0 +1,147 @@
+import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
+import { validateArchiveEntryPath } from "./archive-entry.js";
+import { registerAdmittedZipEntry } from "./archive-zip-entry.js";
+import { zipPathKey } from "./archive-zip-names.js";
+const orderedEntries = new WeakMap();
+export function admittedZipEntries(archive) {
+    return orderedEntries.get(archive) ?? disagreement();
+}
+function disagreement() {
+    throw new ArchiveFormatError("ZIP decoder disagrees with admitted directory metadata");
+}
+function collision() {
+    throw new ArchiveSecurityError("entry-path", "zip archive contains duplicate or colliding entry names");
+}
+function matchesData(value, physical) {
+    if (!value || typeof value !== "object")
+        return false;
+    const data = value;
+    return Number.isInteger(data.crc32) && data.crc32 >= -0x80000000 && data.crc32 <= 0xffffffff &&
+        (data.crc32 >>> 0) === physical.crc32 && data.uncompressedSize === physical.size &&
+        data.compressedSize === physical.compressedSize && typeof data.getContentWorker === "function" &&
+        data.compression?.magic === String.fromCharCode(physical.compressionMethod & 255, physical.compressionMethod >>> 8);
+}
+/** Internal: the caller has admitted these unchanged bytes and their metadata. */
+export async function loadAdmittedZipArchive(buffer, admitted) {
+    const physicalByPath = new Map();
+    for (const entry of admitted) {
+        if (physicalByPath.has(entry.portableKey))
+            collision();
+        physicalByPath.set(entry.portableKey, entry);
+    }
+    const JSZip = await importOptionalJsZip();
+    const archive = new JSZip();
+    const originalFile = archive.file;
+    const originalDescriptor = Object.getOwnPropertyDescriptor(archive, "file");
+    const inserted = new Map();
+    const remaining = new Map(physicalByPath);
+    // JSZip's fileAdd can misclassify UNIX type bits as directories, rename an
+    // entry, and erase its payload. Intercept only this private instance's load.
+    Object.defineProperty(archive, "file", { configurable: true, writable: true,
+        value: function (...args) {
+            if (args.length === 1)
+                return originalFile.apply(this, args);
+            const [name, data, options] = args;
+            if (this !== archive || args.length !== 3 || typeof name !== "string" || !options || typeof options !== "object")
+                disagreement();
+            validateArchiveEntryPath(name);
+            const key = zipPathKey(name);
+            const physical = remaining.get(key);
+            if (!physical) {
+                if (physicalByPath.has(key))
+                    collision();
+                disagreement();
+            }
+            const fields = options;
+            const unixMode = physical.creatorSystem === 3 ? physical.externalAttributes >>> 16 : null;
+            const dosMode = physical.creatorSystem === 0 ? physical.externalAttributes & 0x3f : null;
+            const decoderDirectory = Boolean(physical.externalAttributes & 0x10) || physical.portableDirectory;
+            if (physical.index !== inserted.size || fields.unixPermissions !== unixMode || fields.dosPermissions !== dosMode ||
+                fields.dir !== decoderDirectory || !matchesData(data, physical))
+                disagreement();
+            const result = originalFile.call(this, name, data, {
+                ...fields, dir: false, unixPermissions: null, dosPermissions: null, createFolders: false,
+            });
+            const entry = archive.files[name];
+            if (!entry || typeof entry !== "object" || inserted.has(entry))
+                disagreement();
+            // fileAdd also substitutes an empty promise for declared-zero contents.
+            // Retain the original decoder object so size/CRC checks still read bytes.
+            entry._data = data;
+            inserted.set(entry, { physical, data });
+            remaining.delete(key);
+            return result;
+        },
+    });
+    try {
+        const loaded = await archive.loadAsync(buffer, { createFolders: false });
+        if (loaded !== archive)
+            disagreement();
+    }
+    catch (error) {
+        if (error instanceof ArchiveFormatError || error instanceof ArchiveSecurityError)
+            throw error;
+        throw new ArchiveFormatError(`invalid ZIP archive: ${error instanceof Error ? error.message : String(error)}`, { cause: error instanceof Error ? error : undefined });
+    }
+    finally {
+        if (originalDescriptor)
+            Object.defineProperty(archive, "file", originalDescriptor);
+        else
+            Reflect.deleteProperty(archive, "file");
+    }
+    const names = Object.keys(archive.files);
+    if (names.length !== admitted.length)
+        collision();
+    const normalized = [];
+    for (const name of names) {
+        validateArchiveEntryPath(name);
+        const entry = archive.files[name];
+        if (!entry || typeof entry.name !== "string")
+            disagreement();
+        validateArchiveEntryPath(entry.name);
+        const insertion = inserted.get(entry);
+        if (!insertion || zipPathKey(name) !== insertion.physical.portableKey || zipPathKey(entry.name) !== insertion.physical.portableKey ||
+            entry.dir !== false || entry.unixPermissions !== null || entry.dosPermissions !== null ||
+            entry._data !== insertion.data || !matchesData(entry._data, insertion.physical))
+            disagreement();
+        normalized[insertion.physical.index] = [name, entry, insertion.physical];
+        inserted.delete(entry);
+    }
+    if (remaining.size || inserted.size)
+        disagreement();
+    const files = Object.create(null);
+    const entries = [];
+    for (const [name, entry, physical] of normalized) {
+        const appendSlash = physical.kind === "directory" && !name.endsWith("/");
+        const normalizedName = appendSlash ? `${name}/` : name;
+        if (Object.hasOwn(files, normalizedName))
+            collision();
+        if (appendSlash) {
+            entry.name = `${entry.name}/`;
+        }
+        files[normalizedName] = entry;
+        registerAdmittedZipEntry(entry, physical);
+        entries.push(entry);
+    }
+    archive.files = files;
+    orderedEntries.set(archive, entries);
+    return archive;
+}
+async function importOptionalJsZip() {
+    try {
+        const module = await import("jszip");
+        const candidate = typeof module === "function" ? module : module.default;
+        if (typeof candidate !== "function" ||
+            typeof candidate.prototype?.file !== "function" ||
+            typeof candidate.prototype?.loadAsync !== "function") {
+            throw new Error('Optional archive dependency "jszip" does not expose its constructor, file(), and 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/node_modules/@openclaw/fs-safe/dist/archive-zip-manifest.d.ts

@@ -0,0 +1,4 @@
+import type { NativeArchiveEntry } from "./native-binding.js";
+import type { ZipDirectoryEntry } from "./archive-zip-directory.js";
+/** Associate all native entries with physical admission before exposing any. */
+export declare function validateNativeZipManifest(manifest: NativeArchiveEntry[], admitted: ZipDirectoryEntry[]): void;

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

@@ -0,0 +1,22 @@
+import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
+import { stripArchivePath } from "./archive-entry.js";
+/** Associate all native entries with physical admission before exposing any. */
+export function validateNativeZipManifest(manifest, admitted) {
+    if (manifest.length !== admitted.length) {
+        throw new ArchiveSecurityError("entry-path", "zip decoder collapsed entry names");
+    }
+    for (const [ordinal, entry] of manifest.entries()) {
+        const physical = admitted[ordinal];
+        const physicalPath = physical?.path;
+        const pathMatches = physicalPath === undefined || entry.path === physicalPath ||
+            stripArchivePath(entry.path, 0) === stripArchivePath(physicalPath, 0);
+        // Native indices are physical central-directory ordinals. Legacy name
+        // decoding remains native-selected; compare names when admission knows them.
+        if (!physical || physical.index !== ordinal || entry.index !== ordinal ||
+            entry.size !== physical.size || entry.kind !== physical.kind ||
+            !pathMatches ||
+            (physical.creatorSystem === 3 && entry.mode !== physical.externalAttributes >>> 16)) {
+            throw new ArchiveFormatError("ZIP decoder disagrees with admitted directory metadata");
+        }
+    }
+}

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

@@ -1,6 +1,7 @@
 export declare function zipFormat(message: string): never;
 export declare function zipUInt64(bytes: Buffer, offset: number): number;
 export declare function zipExtraFields(bytes: Buffer): Map<number, Buffer>;
+export declare function zipPathKey(name: string): string;
 export declare function admitZipNames(params: {
     central: Buffer;
     local: Buffer;
@@ -8,5 +9,9 @@ export declare function admitZipNames(params: {
     centralExtra: Map<number, Buffer>;
     localExtra: Map<number, Buffer>;
     seen: Set<string>;
-}): string | undefined;
-//# sourceMappingURL=archive-zip-names.d.ts.map
+}): {
+    path?: string;
+    portableKey: string;
+    portableDirectory: boolean;
+    directory: boolean;
+};

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

@@ -1,3 +1,4 @@
+import { types } from "node:util";
 import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
 import { stripArchivePath, validateArchiveEntryPath } from "./archive-entry.js";
 import { updateCrc32 } from "./archive-crc32.js";
@@ -31,23 +32,30 @@ export function zipExtraFields(bytes) {
     }
     return critical;
 }
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
 function utf8(bytes) {
     try {
-        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+        return utf8Decoder.decode(bytes);
     }
     catch {
         return zipFormat("invalid UTF-8 name");
     }
 }
-function key(name) {
+// Canonical identity only; this does not replace raw path validation.
+export function zipPathKey(name) {
+    if (name && name !== "." && !name.includes("/") && !name.includes("\\"))
+        return name;
     return stripArchivePath(name, 0) ?? "";
 }
-function originalName(name, flags) {
+function originalName(name, rawName, flags) {
     // ASCII path syntax is encoding-independent. Do not reinterpret legacy bytes
     // as UTF-8 (native ZIP uses CP437); the selected decoder still validates its name.
-    validateArchiveEntryPath(Array.from(name, (byte) => byte < 128 ? String.fromCharCode(byte) : "_").join(""));
+    const asciiName = rawName.replace(/[\x80-\xff]/g, "_");
+    validateArchiveEntryPath(asciiName);
     if (!(flags & 0x800))
         return undefined;
+    if (asciiName === rawName && !types.isSharedArrayBuffer(name.buffer))
+        return rawName;
     const decoded = utf8(name);
     validateArchiveEntryPath(decoded);
     return decoded;
@@ -68,33 +76,74 @@ export function admitZipNames(params) {
     const { central, local, flags, centralExtra, localExtra, seen } = params;
     if (!central.length || !local.length)
         zipFormat("empty entry name");
-    const centralUtf8 = originalName(central, flags);
-    const localUtf8 = originalName(local, flags);
+    // Reuse only within this synchronous call; shared backing bytes can change
+    // concurrently even though admission does not yield while checking names.
+    const sameName = !types.isSharedArrayBuffer(central.buffer) &&
+        !types.isSharedArrayBuffer(local.buffer) && central.equals(local);
+    const centralRaw = central.toString("latin1");
+    const localRaw = sameName ? centralRaw : local.toString("latin1");
+    const centralUtf8 = originalName(central, centralRaw, flags);
+    const localUtf8 = sameName ? centralUtf8 : originalName(local, localRaw, flags);
     const centralUnicode = unicodeName(central, centralExtra);
-    const localUnicode = unicodeName(local, localExtra);
-    if (key(central.toString("latin1")) !== key(local.toString("latin1"))) {
+    const centralField = centralExtra.get(0x7075);
+    const localField = localExtra.get(0x7075);
+    // Only immutable identical fields share their CRC-bound name admission.
+    const sameUnicode = (!centralField || !types.isSharedArrayBuffer(centralField.buffer)) &&
+        (!localField || !types.isSharedArrayBuffer(localField.buffer)) &&
+        (centralField === localField ||
+            (centralField !== undefined && localField !== undefined && centralField.equals(localField)));
+    const localUnicode = sameName && sameUnicode ? centralUnicode : unicodeName(local, localExtra);
+    const centralKey = zipPathKey(centralRaw);
+    if (!sameName && centralKey !== zipPathKey(localRaw)) {
         zipFormat("central and local names disagree");
     }
     const interpretations = [centralUtf8, localUtf8, centralUnicode, localUnicode].filter((value) => value !== undefined);
-    if (interpretations.some((value) => key(value) !== key(interpretations[0]))) {
+    // Canonical paths erase terminal separators. Preserve their kind meaning in
+    // every interpretation, including Unicode overrides of legacy-encoded names.
+    const directory = /[/\\]$/.test(centralRaw);
+    if (/[/\\]$/.test(localRaw) !== directory ||
+        interpretations.some((value) => /[/\\]$/.test(value) !== directory)) {
+        zipFormat("conflicting terminal directory markers");
+    }
+    const firstInterpretation = interpretations[0];
+    const interpretationKey = firstInterpretation === undefined ? undefined
+        : firstInterpretation === centralRaw ? centralKey : zipPathKey(firstInterpretation);
+    if (interpretations.some((value) => value !== interpretations[0] && zipPathKey(value) !== interpretationKey)) {
         zipFormat("conflicting Unicode name interpretations");
     }
     // JSZip checks the central Unicode field against the local name. A slash-only
     // spelling difference must not make one decoder ignore a meaningful override.
     if (centralUnicode && !central.equals(local) &&
-        key(centralUnicode) !== key(local.toString("utf8"))) {
+        zipPathKey(centralUnicode) !== zipPathKey(local.toString("utf8"))) {
         zipFormat("Unicode override disagrees with local decoder name");
     }
-    if (!centralUnicode && localUnicode && key(localUnicode) !== key(local.toString("utf8"))) {
+    if (!centralUnicode && localUnicode && zipPathKey(localUnicode) !== zipPathKey(local.toString("utf8"))) {
         zipFormat("local-only Unicode override changes the name");
     }
-    const identities = new Set([key(central.toString("latin1"))]);
-    if (centralUnicode !== undefined)
-        identities.add(key(Buffer.from(centralUnicode).toString("latin1")));
-    if ([...identities].some((identity) => seen.has(identity))) {
+    const unicodeKey = centralUnicode === undefined
+        ? undefined : zipPathKey(Buffer.from(centralUnicode).toString("latin1"));
+    if (seen.has(centralKey) ||
+        (unicodeKey !== undefined && unicodeKey !== centralKey && seen.has(unicodeKey))) {
         throw new ArchiveSecurityError("entry-path", "zip archive contains duplicate or colliding entry names");
     }
-    for (const identity of identities)
-        seen.add(identity);
-    return centralUnicode ?? centralUtf8 ?? (central.every((byte) => byte < 128) ? central.toString("ascii") : undefined);
+    seen.add(centralKey);
+    if (unicodeKey !== undefined && unicodeKey !== centralKey)
+        seen.add(unicodeKey);
+    const path = centralUnicode ?? centralUtf8 ?? (central.every((byte) => byte < 128) ? central.toString("ascii") : undefined);
+    const portablePath = centralUnicode ?? localUtf8 ?? (sameName && path !== undefined ? path : local.toString("utf8"));
+    // Reuse the admitted interpretation, never the Latin-1 Unicode collision key.
+    // Unflagged legacy names can decode differently and need their own key.
+    const portableKey = portablePath === centralRaw ? centralKey
+        : interpretations.includes(portablePath) ? interpretationKey : zipPathKey(portablePath);
+    // JSZip prioritizes flagged local UTF-8 and checks a central Unicode field
+    // against local bytes. Canonically equal names can end in different separators.
+    const decoderPath = flags & 0x800 ? localUtf8
+        : centralUnicode !== undefined && (sameName || centralField.readUInt32LE(1) === updateCrc32(0, local))
+            ? centralUnicode : local.toString("utf8");
+    return {
+        path,
+        portableKey,
+        portableDirectory: decoderPath.endsWith("/"),
+        directory,
+    };
 }

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

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

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

@@ -1,44 +1,13 @@
 import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, resolveExtractLimits, } from "./archive-limits.js";
-import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
 import { admitZipBuffer } from "./archive-zip-admission.js";
-import { validateArchiveEntryPath } from "./archive-entry.js";
+import { loadAdmittedZipArchive } from "./archive-zip-loader.js";
 export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
 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 = admitZipBuffer(buffer, resolvedLimits);
-    const JSZip = await importOptionalJsZip();
-    let archive;
-    try {
-        archive = await JSZip.loadAsync(buffer);
-    }
-    catch (error) {
-        throw new ArchiveFormatError(`invalid ZIP archive: ${error instanceof Error ? error.message : String(error)}`, { cause: error instanceof Error ? error : undefined });
-    }
-    if (Object.keys(archive.files).length !== entryCount) {
-        throw new ArchiveSecurityError("entry-path", "zip archive contains duplicate or colliding entry names");
-    }
-    for (const name of Object.keys(archive.files))
-        validateArchiveEntryPath(name);
-    return archive;
-}
-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 });
+    const entries = [];
+    admitZipBuffer(buffer, resolvedLimits, entry => { entries.push(entry); });
+    return await loadAdmittedZipArchive(buffer, entries);
 }

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

@@ -1,15 +1,17 @@
-import type { ExtractArchiveOptions } from "./archive-options.js";
-export type { ArchiveLogger, ExtractArchiveOptions } from "./archive-options.js";
-export type { ArchiveEntryFilter, ArchiveEntryKind, ArchiveEntryModePolicy, ArchiveFilteredEntryPolicy, } from "./archive-policy.js";
+import { type ExtractArchiveOptions, type ArchivePlanEntry } from "./archive-plan.js";
+export type { ArchiveLogger, ExtractArchiveOptions } from "./archive-plan.js";
+export type { ArchiveEntryFilter, ArchiveEntryKind, ArchiveEntryModePolicy, ArchiveFilteredEntryPolicy, } from "./archive-plan.js";
 export { isWindowsDrivePath, normalizeArchiveEntryPath, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
 export { resolveArchiveKind, resolvePackedRootDir, type ArchiveKind } from "./archive-kind.js";
 export { readArchiveEntry } from "./archive-read.js";
-export { inspectTarArchive, type InspectTarArchiveOptions, type InspectedTarEntry } from "./archive-tar-inspect.js";
 export { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, DEFAULT_MAX_ARCHIVE_BYTES_ZIP, DEFAULT_MAX_ENTRIES, DEFAULT_MAX_EXTRACTED_BYTES, DEFAULT_MAX_ENTRY_BYTES, DEFAULT_MAX_META_ENTRY_BYTES, DEFAULT_MAX_ENTRY_PATH_COMPONENTS, type ArchiveExtractLimits, type ArchiveLimitErrorCode, } from "./archive-limits.js";
 export { ArchiveFormatError, type ArchiveFormatErrorCode } from "./archive-errors.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 { createTarEntryPreflightChecker, type TarEntryInfo } from "./archive-plan.js";
 export { loadZipArchiveWithPreflight, readZipCentralDirectoryEntryCount, type ZipArchiveWithFiles, } from "./archive-zip-preflight.js";
 export declare function extractArchive(params: ExtractArchiveOptions): Promise<void>;
-//# sourceMappingURL=archive.d.ts.map
+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[]>;