@openclaw/fs-safe 0.16.0 → 0.18.0

package/dist/archive-options.d.ts

@@ -1,5 +1,6 @@
 import type { ArchiveKind } from "./archive-kind.js";
-import type { ArchiveExtractLimits } from "./archive-limits.js";
+import type { ExtractionDeadline } from "./archive-deadline.js";
+import type { ArchiveExtractLimits, ResolvedArchiveExtractLimits } from "./archive-limits.js";
 import type { ArchiveEntryFilter, ArchiveEntryModePolicy, ArchiveFilteredEntryPolicy } from "./archive-policy.js";
 export type ArchiveLogger = {
     info?: (message: string) => void;
@@ -17,7 +18,13 @@ export type ExtractArchiveOptions = {
     limits?: ArchiveExtractLimits;
     logger?: ArchiveLogger;
     entryModes?: ArchiveEntryModePolicy;
+    /** Remove these rwx bits from final entry modes. Defaults to zero. */
+    entryUmask?: number;
     entryFilter?: ArchiveEntryFilter;
     onFiltered?: ArchiveFilteredEntryPolicy;
 };
-//# sourceMappingURL=archive-options.d.ts.map
+/** Private executors receive owned options and an already-staged archive path. */
+export type StagedArchiveExtractOptions = Pick<ExtractArchiveOptions, "archivePath" | "destDir" | "durable" | "stripComponents" | "entryModes" | "entryUmask" | "entryFilter" | "onFiltered"> & {
+    limits: ResolvedArchiveExtractLimits;
+    deadline: ExtractionDeadline;
+};

package/dist/archive-parser-errors.d.ts

@@ -1,2 +1 @@
 export declare function classifyArchiveParserError(message: string, options?: ErrorOptions): Error | undefined;
-//# sourceMappingURL=archive-parser-errors.d.ts.map

package/dist/archive-plan.d.ts

@@ -1,5 +1,7 @@
 import type { ArchiveKind } from "./archive-kind.js";
+import { type ResolvedArchiveExtractLimits } from "./archive-limits.js";
 import type { ExtractArchiveOptions } from "./archive-options.js";
+import { type ArchiveEntryKind } from "./archive-policy.js";
 export type ArchiveMemberKind = "file" | "directory" | "symlink" | "hardlink" | "blocked" | "sparse" | "other";
 export type ArchivePlanEntry = {
     path: string;
@@ -11,10 +13,17 @@ export type ArchivePlanOptions = Pick<ExtractArchiveOptions, "stripComponents" |
     rootDir?: string;
     escapeLabel?: string;
 };
+export declare function createArchiveEntrySelector(params: ArchivePlanOptions): {
+    limits: ResolvedArchiveExtractLimits;
+    select(entry: {
+        path: string;
+        kind: ArchiveEntryKind;
+        size: number;
+    }): string | null;
+};
 export declare function createArchiveEntryPlanner(params: ArchivePlanOptions, archiveKind: ArchiveKind): (entry: {
     path: string;
     kind: ArchiveMemberKind;
     size: number;
     mode?: number;
 }) => ArchivePlanEntry | null;
-//# sourceMappingURL=archive-plan.d.ts.map

package/dist/archive-plan.js

@@ -3,34 +3,44 @@ import { createArchiveOutputPathTracker, resolveArchiveOutputPath, stripArchiveP
 import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, resolveExtractLimits, } from "./archive-limits.js";
 import { resolveArchiveEntryMode, shouldExtractArchiveEntry } from "./archive-policy.js";
 import { formatErrorDetail } from "./error-detail.js";
-// Inspection and both executors decide over the same admitted identities.
-// A destination is optional only for inspection; writers still prove containment.
-export function createArchiveEntryPlanner(params, archiveKind) {
+// Portable ZIP selects each entry immediately before streaming its payload;
+// manifest-backed routes add declared-byte admission through the planner below.
+export function createArchiveEntrySelector(params) {
     const strip = Math.max(0, Math.floor(params.stripComponents ?? 0));
     const limits = resolveExtractLimits(params.limits);
-    const budget = createByteBudgetTracker(limits);
     const trackOutputPath = createArchiveOutputPathTracker();
     let entryCount = 0;
+    return { limits, select(entry) {
+            assertArchiveEntryCountWithinLimit(++entryCount, limits);
+            validateArchiveEntryPath(entry.path, { escapeLabel: params.escapeLabel });
+            const canonicalPath = stripArchivePath(entry.path, 0);
+            if (!canonicalPath)
+                return null;
+            const relPath = strip === 0 ? canonicalPath : stripArchivePath(canonicalPath, strip);
+            if (!relPath)
+                return null;
+            validateArchiveEntryPath(relPath, { escapeLabel: params.escapeLabel });
+            assertArchiveEntryPathComponentsWithinLimit(relPath, limits);
+            trackOutputPath(relPath, entry.path);
+            if (params.rootDir !== undefined) {
+                resolveArchiveOutputPath({ rootDir: params.rootDir, relPath, originalPath: entry.path,
+                    escapeLabel: params.escapeLabel });
+            }
+            if (!shouldExtractArchiveEntry({ filter: params.entryFilter, onFiltered: params.onFiltered,
+                entry: { path: canonicalPath, kind: entry.kind, size: entry.size } }))
+                return null;
+            return relPath;
+        } };
+}
+// A destination is optional only for inspection; writers still prove containment.
+export function createArchiveEntryPlanner(params, archiveKind) {
+    const { select, limits } = createArchiveEntrySelector(params);
+    const budget = createByteBudgetTracker(limits);
     return (entry) => {
-        assertArchiveEntryCountWithinLimit(++entryCount, limits);
-        validateArchiveEntryPath(entry.path, { escapeLabel: params.escapeLabel });
-        const canonicalPath = stripArchivePath(entry.path, 0);
-        if (!canonicalPath)
-            return null;
-        const relPath = strip === 0 ? canonicalPath : stripArchivePath(canonicalPath, strip);
-        if (!relPath)
-            return null;
-        validateArchiveEntryPath(relPath, { escapeLabel: params.escapeLabel });
-        assertArchiveEntryPathComponentsWithinLimit(relPath, limits);
-        trackOutputPath(relPath, entry.path);
-        if (params.rootDir !== undefined) {
-            resolveArchiveOutputPath({ rootDir: params.rootDir, relPath, originalPath: entry.path,
-                escapeLabel: params.escapeLabel });
-        }
         const kind = entry.kind === "file" || entry.kind === "directory" ? entry.kind
             : entry.kind === "symlink" || entry.kind === "hardlink" ? "symlink" : "other";
-        if (!shouldExtractArchiveEntry({ filter: params.entryFilter, onFiltered: params.onFiltered,
-            entry: { path: canonicalPath, kind, size: entry.size } }))
+        const relPath = select({ path: entry.path, kind, size: entry.size });
+        if (relPath === null)
             return null;
         if (entry.kind === "sparse") {
             throw new ArchiveFormatError(`GNU sparse archive entry is not supported: ${formatErrorDetail(entry.path)}`);

package/dist/archive-policy.d.ts

@@ -19,4 +19,3 @@ export declare function shouldExtractArchiveEntry(params: {
     onFiltered?: ArchiveFilteredEntryPolicy;
     entry: Parameters<ArchiveEntryFilter>[0];
 }): boolean;
-//# sourceMappingURL=archive-policy.d.ts.map

package/dist/archive-read.d.ts

@@ -3,4 +3,3 @@ export declare function readArchiveEntry(archivePath: string, entryPath: string,
     maxBytes: number;
     kind?: ArchiveKind;
 }): Promise<Buffer>;
-//# sourceMappingURL=archive-read.d.ts.map

package/dist/archive-staging.d.ts

@@ -31,4 +31,3 @@ export declare function withStagedArchiveDestination<T>(params: {
 }): Promise<T>;
 export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
 export declare function createArchiveSymlinkTraversalError(originalPath: string): ArchiveSecurityError;
-//# sourceMappingURL=archive-staging.d.ts.map

package/dist/archive-tar-inspect.d.ts

@@ -4,4 +4,3 @@ export type InspectTarArchiveOptions = Pick<ExtractArchiveOptions, "archivePath"
 export type InspectedTarEntry = Readonly<Pick<ArchivePlanEntry, "path" | "kind" | "size">>;
 /** Complete TAR/gzip admission and zero-strip extraction policy, without output writes. */
 export declare function inspectTarArchive(params: InspectTarArchiveOptions): Promise<readonly InspectedTarEntry[]>;
-//# sourceMappingURL=archive-tar-inspect.d.ts.map

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

@@ -25,4 +25,3 @@ export declare function replayTar<T extends AdmittedTarMember>(params: TarInput
     consume(member: T, payload: AsyncIterable<Buffer>): Promise<void>;
 }): Promise<void>;
 export {};
-//# sourceMappingURL=archive-tar-stream.d.ts.map

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

@@ -27,4 +27,3 @@ export declare class TarParserStream extends Transform {
     _flush(callback: TransformCallback): void;
     _destroy(error: Error | null, callback: (error: Error | null) => void): void;
 }
-//# sourceMappingURL=archive-tar-wasm.d.ts.map

package/dist/archive-tar.d.ts

@@ -16,4 +16,3 @@ export declare function createTarEntryPreflightChecker(params: {
     entryFilter?: ArchiveEntryFilter;
     onFiltered?: ArchiveFilteredEntryPolicy;
 }): (entry: TarEntryInfo) => boolean;
-//# sourceMappingURL=archive-tar.d.ts.map

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

@@ -5,4 +5,3 @@ import { type ZipDirectoryEntry } from "./archive-zip-directory.js";
 export declare function admitZipBuffer(input: Uint8Array, limits: ResolvedArchiveExtractLimits, onEntry?: (entry: ZipDirectoryEntry) => void): number;
 /** 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-count.d.ts

@@ -1,2 +1 @@
 export declare function readZipCentralDirectoryEntryCount(buffer: Buffer | Uint8Array): number | null;
-//# sourceMappingURL=archive-zip-count.d.ts.map

package/dist/archive-zip-count.js

@@ -1,5 +1,6 @@
 // Conservative public count hint; strict admission must not rely on its fallback.
 const ZIP_EOCD_SIGNATURE = 0x06054b50;
+const ZIP_EOCD_SIGNATURE_BYTES = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
 const ZIP64_EOCD_SIGNATURE = 0x06064b50;
 const ZIP64_EOCD_LOCATOR_SIGNATURE = 0x07064b50;
 const ZIP_EOCD_MIN_BYTES = 22;
@@ -38,7 +39,26 @@ function findZipEndOfCentralDirectory(buffer) {
         return -1;
     }
     const minOffset = Math.max(0, buffer.byteLength - ZIP_EOCD_MIN_BYTES - ZIP_EOCD_MAX_COMMENT_BYTES);
-    for (let offset = buffer.byteLength - ZIP_EOCD_MIN_BYTES; offset >= minOffset; offset -= 1) {
+    const lastOffset = buffer.byteLength - ZIP_EOCD_MIN_BYTES;
+    if (buffer.readUInt32LE(lastOffset) === ZIP_EOCD_SIGNATURE &&
+        buffer.readUInt16LE(lastOffset + ZIP_EOCD_COMMENT_LENGTH_OFFSET) === 0) {
+        return lastOffset;
+    }
+    const tail = buffer.subarray(minOffset);
+    let from = lastOffset - minOffset - 1;
+    // Keep the latest valid record semantics of this count hint. Bound native
+    // searches so dense false signatures retain the byte scan's cost.
+    for (let candidates = 0; candidates < 16 && from >= 0; candidates += 1) {
+        const found = tail.lastIndexOf(ZIP_EOCD_SIGNATURE_BYTES, from);
+        if (found < 0)
+            return -1;
+        const offset = minOffset + found;
+        const commentLength = buffer.readUInt16LE(offset + ZIP_EOCD_COMMENT_LENGTH_OFFSET);
+        if (offset + ZIP_EOCD_MIN_BYTES + commentLength === buffer.byteLength)
+            return offset;
+        from = found - 1;
+    }
+    for (let offset = minOffset + from; offset >= minOffset; offset -= 1) {
         if (buffer.readUInt32LE(offset) !== ZIP_EOCD_SIGNATURE) {
             continue;
         }

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

@@ -19,4 +19,3 @@ export type ZipDirectoryEntry = {
     kind: ArchiveEntryKind;
 };
 export declare function scanZipDirectory(size: number, limits: ResolvedArchiveExtractLimits, onEntry?: (entry: ZipDirectoryEntry) => void): ZipScan;
-//# sourceMappingURL=archive-zip-directory.d.ts.map

package/dist/archive-zip-directory.js

@@ -19,7 +19,8 @@ function* read(offset, length, bound) {
         zipFormat("truncated record");
     return bytes;
 }
-function endOffset(tail) {
+const END_SIGNATURE = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
+function denseEndOffset(tail) {
     let found = -1;
     for (let offset = tail.length - 22; offset >= 0; offset--) {
         if (tail.readUInt32LE(offset) === 0x06054b50 && offset + 22 + tail.readUInt16LE(offset + 20) === tail.length) {
@@ -32,6 +33,27 @@ function endOffset(tail) {
         zipFormat("end record missing");
     return found;
 }
+function endOffset(tail) {
+    let found = -1;
+    let from = 0;
+    // Sparse signatures use native search; dense attacker-controlled markers
+    // retain the bounded byte scan instead of one native call per marker.
+    for (let candidates = 0; candidates < 16; candidates++) {
+        const offset = tail.indexOf(END_SIGNATURE, from);
+        if (offset < 0 || offset > tail.length - 22) {
+            if (found < 0)
+                zipFormat("end record missing");
+            return found;
+        }
+        if (offset + 22 + tail.readUInt16LE(offset + 20) === tail.length) {
+            if (found !== -1)
+                zipFormat("ambiguous end records");
+            found = offset;
+        }
+        from = offset + 1;
+    }
+    return denseEndOffset(tail);
+}
 function* zip64End(locator, locatorAt, size) {
     const advertised = zipUInt64(locator, 8);
     // Seek the advertised record, or the fixed ordinary record for a prefixed

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

@@ -22,4 +22,3 @@ export declare function isZipSymlinkEntry(entry: ZipEntry): boolean;
 export declare function zipEntryKind(entry: ZipEntry): ArchiveEntryKind;
 export declare function zipEntryMode(entry: ZipEntry, policy: ArchiveEntryModePolicy | undefined): number;
 export declare function zipEntryDeclaredSize(entry: ZipEntry): number;
-//# sourceMappingURL=archive-zip-entry.d.ts.map

package/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/dist/archive-zip-loader.d.ts

@@ -1,7 +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>;
-//# sourceMappingURL=archive-zip-loader.d.ts.map

package/dist/archive-zip-loader.js

@@ -2,6 +2,10 @@ 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");
 }
@@ -106,6 +110,7 @@ export async function loadAdmittedZipArchive(buffer, admitted) {
     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;
@@ -116,8 +121,10 @@ export async function loadAdmittedZipArchive(buffer, admitted) {
         }
         files[normalizedName] = entry;
         registerAdmittedZipEntry(entry, physical);
+        entries.push(entry);
     }
     archive.files = files;
+    orderedEntries.set(archive, entries);
     return archive;
 }
 async function importOptionalJsZip() {

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

@@ -2,4 +2,3 @@ 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;
-//# sourceMappingURL=archive-zip-manifest.d.ts.map

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

@@ -15,4 +15,3 @@ export declare function admitZipNames(params: {
     portableDirectory: boolean;
     directory: boolean;
 };
-//# sourceMappingURL=archive-zip-names.d.ts.map

package/dist/archive-zip-names.js

@@ -50,9 +50,12 @@ export function zipPathKey(name) {
 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(rawName.replace(/[\x80-\xff]/g, "_"));
+    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;
@@ -102,7 +105,9 @@ export function admitZipNames(params) {
         interpretations.some((value) => /[/\\]$/.test(value) !== directory)) {
         zipFormat("conflicting terminal directory markers");
     }
-    const interpretationKey = interpretations.length ? zipPathKey(interpretations[0]) : undefined;
+    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");
     }

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

@@ -3,4 +3,3 @@ import { type ZipArchiveWithFiles } from "./archive-zip-loader.js";
 export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
 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.d.ts

@@ -12,4 +12,3 @@ export { createArchiveSymlinkTraversalError, mergeExtractedTreeIntoDestination,
 export { createTarEntryPreflightChecker, type TarEntryInfo } from "./archive-tar.js";
 export { loadZipArchiveWithPreflight, readZipCentralDirectoryEntryCount, type ZipArchiveWithFiles, } from "./archive-zip-preflight.js";
 export declare function extractArchive(params: ExtractArchiveOptions): Promise<void>;
-//# sourceMappingURL=archive.d.ts.map