@openclaw/fs-safe 0.10.0 → 0.11.0

package/dist/archive-read.js

@@ -8,12 +8,14 @@ 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 { 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 { 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 { resolveExtractLimits, resolveTarMeterLimits } from "./archive-limits.js";
@@ -63,7 +65,7 @@ async function readStreamBounded(stream, maxBytes) {
     return Buffer.concat(chunks, total);
 }
 async function readArchiveInput(archivePath) {
-    const resolved = fsSync.realpathSync.native(archivePath);
+    const resolved = realpathSync.native(archivePath);
     const before = await inspectFileIdentity(async () => {
         const stat = fsSync.lstatSync(archivePath, { bigint: true });
         if (stat.isSymbolicLink() || !stat.isFile()) {
@@ -102,12 +104,8 @@ async function readArchiveInput(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, physicalCount) {
+    const archive = await loadAdmittedZipArchive(buffer, physicalCount);
     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.
@@ -153,6 +151,16 @@ async function readTarEntry(archiveBuffer, entryPath, maxBytes) {
     }
     if (selected.size > maxBytes)
         throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
+    if (!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({ archiveBuffer, limits, members: [selected], async consume(_member, payload) {
             result = await readStreamBounded(payload, maxBytes);
@@ -222,6 +230,6 @@ export async function readArchiveEntry(archivePath, entryPath, options) {
     if (native)
         return await readNativeBufferEntry(native, buffer, kind, requestedEntry, entryPath, options.maxBytes, physicalCount);
     assertPortableArchiveKind(kind);
-    return kind === "zip" ? await readZipEntry(buffer, requestedEntry, options.maxBytes)
+    return kind === "zip" ? await readZipEntry(buffer, requestedEntry, options.maxBytes, physicalCount)
         : await readTarEntry(buffer, requestedEntry, options.maxBytes);
 }

package/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>, destinationGuard?: AsyncDirectoryGuard): 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;

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

@@ -1 +1 @@
-{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAGA,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,EACnE,gBAAgB,CAAC,EAAE,mBAAmB,GACrC,OAAO,CAAC,IAAI,CAAC,CAEf;AAkHD,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"}
+{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAGnD,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;AAgB7B,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC;AAMrE,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAS1F,wBAAsB,4BAA4B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAS9F;AAED,wBAAsB,4BAA4B,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAY9F;AAED,wBAAsB,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAyCpG;AAED,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEnF;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,EACnE,gBAAgB,CAAC,EAAE,qBAAqB,GACvC,OAAO,CAAC,IAAI,CAAC,CAEf;AAkHD,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/dist/archive-staging.js

@@ -1,4 +1,4 @@
-import fsSync from "node:fs";
+import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
@@ -13,6 +13,8 @@ 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 { realpathSync } from "./realpath.js";
 const ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK = "archive entry traverses symlink in destination";
 const ARCHIVE_STAGING_MODE = 0o700;
 function checkExtractionDeadline(deadline) {
@@ -24,7 +26,7 @@ function symlinkTraversalError(originalPath) {
 }
 export async function createDirectoryIdentityGuard(dir) {
     try {
-        return await createAsyncDirectoryGuard(dir);
+        return await createAsyncDirectoryGuard(dir, { bigint: true });
     }
     catch (err) {
         if (err instanceof FsSafeError && err.code === "not-file") {
@@ -37,33 +39,51 @@ export async function assertDirectoryIdentityGuard(guard) {
     try {
         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) {
+    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);
+    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 = fsSync.lstatSync(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 = fsSync.realpathSync.native(destDir);
-    const realStat = fsSync.statSync(realPath);
-    const postStat = fsSync.lstatSync(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);
@@ -88,7 +108,7 @@ async function assertNoSymlinkTraversal(params) {
 export async function assertResolvedInsideDestination(params) {
     let resolved;
     try {
-        resolved = fsSync.realpathSync.native(params.targetPath);
+        resolved = realpathSync.native(params.targetPath);
     }
     catch (err) {
         if (isNotFoundPathError(err)) {

package/dist/archive-tar-stream.d.ts.map

@@ -1 +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;AAEhF,gFAAgF;AAChF,KAAK,QAAQ,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAuDhH,wBAAsB,UAAU,CAAC,MAAM,EAAE,QAAQ,GAAG;IAClD,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC7C,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC/C,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AAED;2DAC2D;AAC3D,wBAAsB,SAAS,CAAC,CAAC,SAAS,iBAAiB,EAAE,MAAM,EAAE,QAAQ,GAAG;IAC9E,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC7C,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"}
+{"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;AAGhF,gFAAgF;AAChF,KAAK,QAAQ,GAAG;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAuDhH,wBAAsB,UAAU,CAAC,MAAM,EAAE,QAAQ,GAAG;IAClD,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC7C,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;CAC/C,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AAED;2DAC2D;AAC3D,wBAAsB,SAAS,CAAC,CAAC,SAAS,iBAAiB,EAAE,MAAM,EAAE,QAAQ,GAAG;IAC9E,MAAM,EAAE,cAAc,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC7C,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"}

package/dist/archive-tar-stream.js

@@ -2,9 +2,10 @@ import fs from "node:fs";
 import { Readable, Writable } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { createGunzip } from "node:zlib";
-import { GzipInput, validateGzipBufferTail, validateGzipContainerTail } from "./archive-gzip-tail.js";
+import { GzipInput, isGzipBuffer, validateGzipBufferTail, validateGzipContainerTail } from "./archive-gzip-tail.js";
 import { ArchiveFormatError } from "./archive-errors.js";
 import { TarParserStream } from "./archive-tar-wasm.js";
+import { readFileWindowFully } from "./positional-read.js";
 function* bufferChunks(buffer) {
     for (let offset = 0; offset < buffer.length; offset += 65536)
         yield buffer.subarray(offset, offset + 65536);
@@ -13,8 +14,8 @@ async function gzipFile(filePath) {
     const handle = await fs.promises.open(filePath, "r");
     try {
         const magic = Buffer.alloc(2);
-        const { bytesRead } = await handle.read(magic, 0, 2, 0);
-        return bytesRead === 2 && magic[0] === 31 && magic[1] === 139;
+        const bytesRead = await readFileWindowFully(handle, magic, 0);
+        return bytesRead === 2 && isGzipBuffer(magic);
     }
     finally {
         await handle.close();
@@ -22,13 +23,13 @@ async function gzipFile(filePath) {
 }
 async function withTarStream(params, consume) {
     const buffer = params.archiveBuffer;
-    const gzip = buffer !== undefined ? buffer[0] === 31 && buffer[1] === 139 : await gzipFile(params.archivePath);
+    const gzip = buffer !== undefined ? isGzipBuffer(buffer) : await gzipFile(params.archivePath);
     const parser = new TarParserStream(params.limits, params.onMember);
     const input = buffer !== undefined
         ? Readable.from(bufferChunks(buffer), { objectMode: false, highWaterMark: 65536 })
         : fs.createReadStream(params.archivePath, { highWaterMark: 65536 });
-    // Match the WASM input window for buffered reads instead of emitting 16 KiB chunks.
-    const decoder = gzip ? createGunzip(buffer === undefined ? undefined : { chunkSize: 65536 }) : undefined;
+    // Match the WASM input window for both staged files and buffered reads.
+    const decoder = gzip ? createGunzip({ chunkSize: 65536 }) : undefined;
     const gzipInput = decoder ? new GzipInput(decoder) : undefined;
     const destroy = (error) => {
         input.destroy(error);

package/dist/archive-tar-wasm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-tar-wasm.d.ts","sourceRoot":"","sources":["../src/archive-tar-wasm.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAyClE,kFAAkF;AAClF,qBAAa,eAAgB,SAAQ,SAAS;IAER,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAD9D,OAAO,CAAC,GAAG,CAAkB;IAC7B,YAAY,MAAM,EAAE,cAAc,EAAmB,QAAQ,CAAC,GAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,aAAA,EAQjG;IACD,OAAO,CAAC,KAAK;IAQb,OAAO,CAAC,IAAI;IAIH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAkB/F;IACQ,MAAM,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAKjD;IACQ,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAKpF;CACF"}
+{"version":3,"file":"archive-tar-wasm.d.ts","sourceRoot":"","sources":["../src/archive-tar-wasm.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAyClE,kFAAkF;AAClF,qBAAa,eAAgB,SAAQ,SAAS;IAER,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC;IAD9D,OAAO,CAAC,GAAG,CAAkB;IAC7B,YAAY,MAAM,EAAE,cAAc,EAAmB,QAAQ,CAAC,GAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,aAAA,EAQjG;IACD,OAAO,CAAC,KAAK;IAQb,OAAO,CAAC,IAAI;IAIH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAqB/F;IACQ,MAAM,CAAC,QAAQ,EAAE,iBAAiB,GAAG,IAAI,CAKjD;IACQ,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAKpF;CACF"}

package/dist/archive-tar-wasm.js

@@ -53,21 +53,24 @@ export class TarParserStream extends Transform {
     _transform(chunk, _encoding, callback) {
         try {
             const abi = this.abi;
-            for (let offset = 0; offset < chunk.length;) {
+            for (let offset = 0; offset < chunk.length; offset += 65536) {
                 const length = Math.min(65536, chunk.length - offset);
                 this.bytes(abi.input_ptr(), length).set(chunk.subarray(offset, offset + length));
-                const used = abi.push(length);
-                if (used < 0)
-                    throw parserError(this.text());
-                if (used === 0 || used > length)
-                    throw new ArchiveFormatError("TAR WASM made no progress");
-                offset += used;
-                const type = abi.member_type();
-                if (type >= 0)
-                    this.onMember?.({
-                        path: this.text(), type: types.get(type) ?? "Unsupported", size: abi.member_size(),
-                        mode: abi.member_mode(), offset: abi.member_offset(),
-                    });
+                // A member event can stop before the end of this already-copied inbox.
+                for (let consumed = 0; consumed < length;) {
+                    const used = abi.push(consumed, length - consumed);
+                    if (used < 0)
+                        throw parserError(this.text());
+                    if (used === 0 || used > length - consumed)
+                        throw new ArchiveFormatError("TAR WASM made no progress");
+                    consumed += used;
+                    const type = abi.member_type();
+                    if (type >= 0)
+                        this.onMember?.({
+                            path: this.text(), type: types.get(type) ?? "Unsupported", size: abi.member_size(),
+                            mode: abi.member_mode(), offset: abi.member_offset(),
+                        });
+                }
             }
             callback(null, chunk);
         }

package/dist/archive-zip-admission.d.ts

@@ -3,6 +3,6 @@ import { type ResolvedArchiveExtractLimits } from "./archive-limits.js";
 import { type ZipDirectoryEntry } from "./archive-zip-directory.js";
 /** Admit physical records before a decoder can normalize or collapse names. */
 export declare function admitZipBuffer(input: Uint8Array, limits: ResolvedArchiveExtractLimits): number;
-/** The extraction input is already private and staged; read only bounded metadata. */
+/** The extraction input is private and immutable; read bounded metadata windows. */
 export declare function admitZipFile(archivePath: string, limits: ResolvedArchiveExtractLimits, deadline: ExtractionDeadline, onEntry?: (entry: ZipDirectoryEntry) => void): Promise<number>;
 //# sourceMappingURL=archive-zip-admission.d.ts.map

package/dist/archive-zip-admission.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-zip-admission.d.ts","sourceRoot":"","sources":["../src/archive-zip-admission.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAA+C,KAAK,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAErH,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAUtF,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,4BAA4B,GAAG,MAAM,CAU9F;AAED,sFAAsF;AACtF,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,4BAA4B,EAAE,QAAQ,EAAE,kBAAkB,EACvF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAC3C,OAAO,CAAC,MAAM,CAAC,CA+BjB"}
+{"version":3,"file":"archive-zip-admission.d.ts","sourceRoot":"","sources":["../src/archive-zip-admission.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAA+C,KAAK,4BAA4B,EAAE,MAAM,qBAAqB,CAAC;AAErH,OAAO,EAAoB,KAAK,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAUtF,+EAA+E;AAC/E,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,4BAA4B,GAAG,MAAM,CAU9F;AAMD,oFAAoF;AACpF,wBAAsB,YAAY,CAChC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,4BAA4B,EAAE,QAAQ,EAAE,kBAAkB,EACvF,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,GAC3C,OAAO,CAAC,MAAM,CAAC,CA8DjB"}

package/dist/archive-zip-admission.js

@@ -23,7 +23,9 @@ export function admitZipBuffer(input, limits) {
     }
     return step.value;
 }
-/** The extraction input is already private and staged; read only bounded metadata. */
+const METADATA_WINDOW_BYTES = 4096;
+const CACHED_READS_PER_YIELD = 32;
+/** The extraction input is private and immutable; read bounded metadata windows. */
 export async function admitZipFile(archivePath, limits, deadline, onEntry) {
     deadline.check();
     const opened = await openRootFile({
@@ -35,20 +37,54 @@ export async function admitZipFile(archivePath, limits, deadline, onEntry) {
     try {
         checkSize(opened.stat.size, limits);
         const scan = scanZipDirectory(opened.stat.size, limits, onEntry);
+        // Separate windows keep alternating central and local records hot. Never
+        // refill a buffer: the scanner can retain its views after cache eviction.
+        const windows = [];
+        let cachedReads = 0;
         let step = scan.next();
         while (!step.done) {
+            deadline.check();
             const { offset, length } = step.value;
-            const bytes = Buffer.alloc(length);
-            let received = 0;
-            while (received < length) {
-                deadline.check();
-                const count = await new Promise((resolve, reject) => {
-                    fs.read(opened.fd, bytes, received, length - received, offset + received, (error, count) => error ? reject(error) : resolve(count));
-                });
-                deadline.check();
-                if (!count)
-                    zipFormat("truncated staged record");
-                received += count;
+            const cached = windows.findIndex(window => offset >= window.offset &&
+                length <= window.bytes.length - (offset - window.offset));
+            let bytes;
+            if (cached !== -1) {
+                if (++cachedReads >= CACHED_READS_PER_YIELD) {
+                    cachedReads = 0;
+                    await new Promise(resolve => setImmediate(resolve));
+                    deadline.check();
+                }
+                const window = windows[cached];
+                if (cached === 1)
+                    windows.reverse();
+                bytes = window.bytes.subarray(offset - window.offset, offset - window.offset + length);
+            }
+            else {
+                const cacheable = length > 0 && length <= METADATA_WINDOW_BYTES;
+                const capacity = cacheable ? Math.min(METADATA_WINDOW_BYTES, opened.stat.size - offset) : length;
+                const buffer = Buffer.alloc(capacity);
+                let received = 0;
+                while (received < capacity) {
+                    deadline.check();
+                    const count = await new Promise((resolve, reject) => {
+                        fs.read(opened.fd, buffer, received, capacity - received, offset + received, (error, count) => error ? reject(error) : resolve(count));
+                    });
+                    cachedReads = 0;
+                    deadline.check();
+                    if (!count) {
+                        if (received < length)
+                            zipFormat("truncated staged record");
+                        break;
+                    }
+                    received += count;
+                }
+                const filled = buffer.subarray(0, received);
+                bytes = filled.subarray(0, length);
+                if (cacheable) {
+                    windows.unshift({ offset, bytes: filled });
+                    if (windows.length > 2)
+                        windows.pop();
+                }
             }
             step = scan.next(bytes);
         }

package/dist/archive-zip-loader.d.ts

@@ -0,0 +1,6 @@
+export type ZipArchiveWithFiles = {
+    files: Record<string, unknown>;
+};
+/** Internal: the caller has admitted these unchanged bytes and their physical count. */
+export declare function loadAdmittedZipArchive(buffer: Buffer | Uint8Array, entryCount: number): Promise<ZipArchiveWithFiles>;
+//# sourceMappingURL=archive-zip-loader.d.ts.map

package/dist/archive-zip-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"archive-zip-loader.d.ts","sourceRoot":"","sources":["../src/archive-zip-loader.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAMF,wFAAwF;AACxF,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,GAAG,UAAU,EAC3B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,mBAAmB,CAAC,CAoB9B"}

package/dist/archive-zip-loader.js

@@ -0,0 +1,38 @@
+import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
+import { validateArchiveEntryPath } from "./archive-entry.js";
+/** Internal: the caller has admitted these unchanged bytes and their physical count. */
+export async function loadAdmittedZipArchive(buffer, entryCount) {
+    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 });
+    }
+    const names = Object.keys(archive.files);
+    if (names.length !== entryCount) {
+        throw new ArchiveSecurityError("entry-path", "zip archive contains duplicate or colliding entry names");
+    }
+    for (const name of names)
+        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 });
+}

package/dist/archive-zip-names.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-zip-names.d.ts","sourceRoot":"","sources":["../src/archive-zip-names.ts"],"names":[],"mappings":"AAIA,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAEhD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAcjE;AA6BD,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAC9C,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACnB,GAAG,MAAM,GAAG,SAAS,CA8BrB"}
+{"version":3,"file":"archive-zip-names.d.ts","sourceRoot":"","sources":["../src/archive-zip-names.ts"],"names":[],"mappings":"AAIA,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,CAEhD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAK/D;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAcjE;AA+BD,wBAAgB,aAAa,CAAC,MAAM,EAAE;IACpC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAC9C,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACnB,GAAG,MAAM,GAAG,SAAS,CAiCrB"}

package/dist/archive-zip-names.js

@@ -31,9 +31,10 @@ 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");
@@ -42,10 +43,10 @@ function utf8(bytes) {
 function key(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(""));
+    validateArchiveEntryPath(rawName.replace(/[\x80-\xff]/g, "_"));
     if (!(flags & 0x800))
         return undefined;
     const decoded = utf8(name);
@@ -68,15 +69,19 @@ 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);
+    const centralRaw = central.toString("latin1");
+    const localRaw = local.toString("latin1");
+    const centralUtf8 = originalName(central, centralRaw, flags);
+    const localUtf8 = originalName(local, localRaw, flags);
     const centralUnicode = unicodeName(central, centralExtra);
     const localUnicode = unicodeName(local, localExtra);
-    if (key(central.toString("latin1")) !== key(local.toString("latin1"))) {
+    const centralKey = key(centralRaw);
+    if (centralKey !== key(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]))) {
+    const interpretationKey = interpretations.length ? key(interpretations[0]) : undefined;
+    if (interpretations.some((value) => key(value) !== interpretationKey)) {
         zipFormat("conflicting Unicode name interpretations");
     }
     // JSZip checks the central Unicode field against the local name. A slash-only
@@ -88,7 +93,7 @@ export function admitZipNames(params) {
     if (!centralUnicode && localUnicode && key(localUnicode) !== key(local.toString("utf8"))) {
         zipFormat("local-only Unicode override changes the name");
     }
-    const identities = new Set([key(central.toString("latin1"))]);
+    const identities = new Set([centralKey]);
     if (centralUnicode !== undefined)
         identities.add(key(Buffer.from(centralUnicode).toString("latin1")));
     if ([...identities].some((identity) => seen.has(identity))) {

package/dist/archive-zip-preflight.d.ts

@@ -1,7 +1,6 @@
 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/dist/archive-zip-preflight.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-zip-preflight.d.ts","sourceRoot":"","sources":["../src/archive-zip-preflight.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EAAE,iCAAiC,EAAE,MAAM,wBAAwB,CAAC;AAE3E,MAAM,MAAM,mBAAmB,GAAG;IAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC,CAAC;AAMF,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,MAAM,GAAG,UAAU,EAC3B,MAAM,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAwB9B"}
+{"version":3,"file":"archive-zip-preflight.d.ts","sourceRoot":"","sources":["../src/archive-zip-preflight.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,oBAAoB,EAC1B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC3F,OAAO,EAAE,iCAAiC,EAAE,MAAM,wBAAwB,CAAC;AAC3E,YAAY,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAEnE,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,MAAM,GAAG,UAAU,EAC3B,MAAM,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CAO9B"}

package/dist/archive-zip-preflight.js

@@ -1,7 +1,6 @@
 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);
@@ -9,36 +8,5 @@ export async function loadZipArchiveWithPreflight(buffer, limits) {
         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 });
+    return await loadAdmittedZipArchive(buffer, entryCount);
 }

package/dist/archive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AA4DA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACjF,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACpH,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,iCAAiC,EACjC,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EACL,kCAAkC,EAClC,iCAAiC,EACjC,4BAA4B,EAC5B,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,8BAA8B,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAC;AAiNpC,wBAAsB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6CjF"}
+{"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AA4DA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAGlE,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACjF,YAAY,EACV,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,wBAAwB,EACxB,gBAAgB,EAChB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC/F,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AACpH,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,6BAA6B,EAC7B,mBAAmB,EACnB,2BAA2B,EAC3B,uBAAuB,EACvB,4BAA4B,EAC5B,iCAAiC,EACjC,KAAK,oBAAoB,EACzB,KAAK,qBAAqB,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,EAAE,oBAAoB,EAAE,KAAK,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAC3F,OAAO,EACL,kCAAkC,EAClC,iCAAiC,EACjC,4BAA4B,EAC5B,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,8BAA8B,EAAE,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AACrF,OAAO,EACL,2BAA2B,EAC3B,iCAAiC,EACjC,KAAK,mBAAmB,GACzB,MAAM,4BAA4B,CAAC;AAiNpC,wBAAsB,cAAc,CAAC,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CA6CjF"}