@openclaw/signal 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,149 @@
+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";
+export function zipFormat(message) {
+    throw new ArchiveFormatError(`invalid ZIP metadata: ${message}`);
+}
+export function zipUInt64(bytes, offset) {
+    if (offset + 8 > bytes.length)
+        zipFormat("truncated ZIP64 field");
+    const value = bytes.readBigUInt64LE(offset);
+    if (value > BigInt(Number.MAX_SAFE_INTEGER))
+        zipFormat("ZIP64 integer exceeds safe range");
+    return Number(value);
+}
+export function zipExtraFields(bytes) {
+    const critical = new Map();
+    for (let offset = 0; offset < bytes.length;) {
+        if (offset + 4 > bytes.length)
+            zipFormat("truncated extra field header");
+        const id = bytes.readUInt16LE(offset);
+        const length = bytes.readUInt16LE(offset + 2);
+        offset += 4;
+        if (length > bytes.length - offset)
+            zipFormat("truncated extra field value");
+        if (id === 1 || id === 0x7075) {
+            if (critical.has(id))
+                zipFormat("duplicate critical extra field");
+            critical.set(id, bytes.subarray(offset, offset + length));
+        }
+        offset += length;
+    }
+    return critical;
+}
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+function utf8(bytes) {
+    try {
+        return utf8Decoder.decode(bytes);
+    }
+    catch {
+        return zipFormat("invalid UTF-8 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, 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.
+    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;
+}
+function unicodeName(name, extra) {
+    const field = extra.get(0x7075);
+    if (!field)
+        return undefined;
+    if (field.length < 6 || field[0] !== 1)
+        zipFormat("invalid Unicode Path field");
+    if (field.readUInt32LE(1) !== updateCrc32(0, name))
+        zipFormat("Unicode Path CRC mismatch");
+    const decoded = utf8(field.subarray(5));
+    validateArchiveEntryPath(decoded);
+    return decoded;
+}
+export function admitZipNames(params) {
+    const { central, local, flags, centralExtra, localExtra, seen } = params;
+    if (!central.length || !local.length)
+        zipFormat("empty entry name");
+    // 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 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);
+    // 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) &&
+        zipPathKey(centralUnicode) !== zipPathKey(local.toString("utf8"))) {
+        zipFormat("Unicode override disagrees with local decoder name");
+    }
+    if (!centralUnicode && localUnicode && zipPathKey(localUnicode) !== zipPathKey(local.toString("utf8"))) {
+        zipFormat("local-only Unicode override changes the name");
+    }
+    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");
+    }
+    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

@@ -0,0 +1,4 @@
+import { type ArchiveExtractLimits } from "./archive-limits.js";
+import { type ZipArchiveAdmission, type ZipArchiveWithFiles } from "./archive-zip-loader.js";
+export declare function loadZipArchiveWithAdmission(buffer: Buffer | Uint8Array, limits?: ArchiveExtractLimits): Promise<ZipArchiveAdmission>;
+export declare function loadZipArchiveWithPreflight(buffer: Buffer | Uint8Array, limits?: ArchiveExtractLimits): Promise<ZipArchiveWithFiles>;

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

@@ -0,0 +1,21 @@
+import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, resolveExtractLimits, } from "./archive-limits.js";
+import { admitZipBuffer } from "./archive-zip-admission.js";
+import { loadAdmittedZipArchive } from "./archive-zip-loader.js";
+export function loadZipArchiveWithAdmission(buffer, limits) {
+    try {
+        const resolvedLimits = resolveExtractLimits(limits);
+        if (buffer.byteLength > resolvedLimits.maxArchiveBytes) {
+            throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ARCHIVE_SIZE_EXCEEDS_LIMIT);
+        }
+        const entries = [];
+        admitZipBuffer(buffer, resolvedLimits, entry => { entries.push(entry); });
+        return loadAdmittedZipArchive(buffer, entries);
+    }
+    catch (error) {
+        // Keep validation failures in the promise handed to the extraction deadline.
+        return Promise.reject(error);
+    }
+}
+export async function loadZipArchiveWithPreflight(buffer, limits) {
+    return (await loadZipArchiveWithAdmission(buffer, limits)).archive;
+}

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

@@ -0,0 +1,20 @@
+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 { 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-errors.js";
+export { createArchiveSymlinkTraversalError, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
+export { createTarEntryPreflightChecker, type TarEntryInfo } from "./archive-plan.js";
+export { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
+export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
+export type { ZipArchiveWithFiles } from "./archive-zip-loader.js";
+export declare function extractArchive(params: ExtractArchiveOptions): Promise<void>;
+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[]>;

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

@@ -0,0 +1,332 @@
+import { createTarEntryPlanner, createArchiveEntrySelector, resolveArchiveFilteredEntryPolicy, resolveArchiveEntryMode, createArchiveEntryPlanner, } from "./archive-plan.js";
+import { inspectTar, replayTar } from "./archive-tar-stream.js";
+import { runPinnedWriteHelper } from "./pinned-write.js";
+import { constants as fsConstants } from "node:fs";
+import fs, {} from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createPipelineTimeoutError, waitForDeadline, withExtractionDeadline, } from "./archive-deadline.js";
+import { assertArchiveEntryCountWithinLimit, createByteBudgetTracker, createExtractBudgetTransform, resolveExtractLimits, resolveTarMeterLimits, } from "./archive-limits.js";
+import { resolveArchiveKind } from "./archive-kind.js";
+import { prepareArchiveDestinationGuard, preparePrivateArchiveOutputPath, } from "./archive-staging.js";
+import { withStagedArchivePublication } from "./archive-merge.js";
+import { loadZipArchiveWithAdmission } from "./archive-zip-preflight.js";
+import { createZipIntegrityTransform, normalizeZipIntegrityError, } from "./archive-zip-integrity.js";
+import { ArchiveSecurityError, ArchiveFormatError, isArchiveFormatErrorMessage, } from "./archive-errors.js";
+import { stageArchiveFileForExtraction } from "./archive-input.js";
+import { getNativeBinding, } from "./native.js";
+import { writeSiblingTempFile } from "./sibling-temp.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { classifyArchiveParserError } from "./archive-parser-errors.js";
+import { validateArchiveEntryPath } from "./archive-entry.js";
+import { admitZipFile } from "./archive-zip-admission.js";
+import { validateNativeZipManifest } from "./archive-zip-manifest.js";
+export { isWindowsDrivePath, normalizeArchiveEntryPath, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
+export { resolveArchiveKind, resolvePackedRootDir } from "./archive-kind.js";
+export { readArchiveEntry } from "./archive-read.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, } from "./archive-limits.js";
+export { ArchiveFormatError } from "./archive-errors.js";
+export { ArchiveSecurityError } from "./archive-errors.js";
+export { createArchiveSymlinkTraversalError, prepareArchiveDestinationDir, prepareArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
+export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
+export { createTarEntryPreflightChecker } from "./archive-plan.js";
+export { loadZipArchiveWithPreflight } from "./archive-zip-preflight.js";
+export { readZipCentralDirectoryEntryCount } from "./archive-zip-count.js";
+const SUPPORTS_NOFOLLOW = process.platform !== "win32" && "O_NOFOLLOW" in fsConstants;
+const OPEN_WRITE_CREATE_FLAGS = fsConstants.O_WRONLY |
+    fsConstants.O_CREAT |
+    fsConstants.O_EXCL |
+    (SUPPORTS_NOFOLLOW ? fsConstants.O_NOFOLLOW : 0);
+async function readZipEntryStream(entry) {
+    if (typeof entry.nodeStream === "function") {
+        return entry.nodeStream();
+    }
+    // Old JSZip: fall back to buffering, but still extract via a stream.
+    const buf = await entry.async("nodebuffer");
+    return Readable.from(buf);
+}
+async function writeZipFileEntry(params) {
+    params.deadline.check();
+    params.budget.startEntry();
+    const readable = await readZipEntryStream(params.record.entry);
+    const destinationPath = params.outPath;
+    let tempHandle = null;
+    let handleClosedByStream = false;
+    try {
+        await writeSiblingTempFile({
+            dir: path.dirname(destinationPath),
+            chmodDir: false,
+            mode: 0o600,
+            syncTempFile: false,
+            syncParentDir: false,
+            writeTemp: async (tempPath) => {
+                tempHandle = await fs.open(tempPath, OPEN_WRITE_CREATE_FLAGS, 0o600);
+                const writable = tempHandle.createWriteStream();
+                writable.once("close", () => {
+                    handleClosedByStream = true;
+                });
+                try {
+                    await pipeline(readable, createExtractBudgetTransform({ onChunkBytes: params.budget.addBytes }), createZipIntegrityTransform(params.record), writable, { signal: params.deadline.signal });
+                }
+                catch (err) {
+                    throw normalizeZipIntegrityError(createPipelineTimeoutError(err, params.deadline));
+                }
+                params.deadline.check();
+                if (!handleClosedByStream) {
+                    await tempHandle.close();
+                    handleClosedByStream = true;
+                }
+                tempHandle = null;
+                return destinationPath;
+            },
+            resolveFinalPath: (filePath) => filePath,
+        });
+    }
+    catch (err) {
+        // Failures here happen before the temp has been committed. The destination
+        // parent may already be untrusted, so cleanup must stay limited to temp state.
+        throw err;
+    }
+    finally {
+        const openTempHandle = tempHandle;
+        if (openTempHandle && !handleClosedByStream) {
+            await openTempHandle.close().catch(() => undefined);
+        }
+    }
+}
+async function extractZip(params) {
+    const { limits, deadline } = params;
+    const destinationGuard = await prepareArchiveDestinationGuard(params.destDir);
+    deadline.check();
+    const buffer = await fs.readFile(params.archivePath, { signal: deadline.signal });
+    deadline.check();
+    const { entries } = await waitForDeadline(loadZipArchiveWithAdmission(buffer, limits), deadline);
+    deadline.check();
+    assertArchiveEntryCountWithinLimit(entries.size, limits);
+    const budget = createByteBudgetTracker(limits);
+    await withStagedArchivePublication({ ...params, destinationGuard }, async (stagingDir) => {
+        const { select } = createArchiveEntrySelector({ ...params, rootDir: stagingDir });
+        const acceptedEntries = [];
+        for (const record of entries.values()) {
+            deadline.check();
+            const { entry, kind: entryKind, size, mode: archivedMode } = record;
+            const relPath = select({ path: record.name, kind: entryKind, size });
+            if (relPath === null)
+                continue;
+            if (entryKind === "symlink") {
+                throw new ArchiveSecurityError("entry-link", `zip entry is a link: ${record.name}`);
+            }
+            if (entryKind === "other")
+                continue;
+            const mode = resolveArchiveEntryMode({
+                kind: entry.dir ? "directory" : "file",
+                archivedMode,
+                policy: params.entryModes,
+            });
+            acceptedEntries.push({ path: relPath, kind: entry.dir ? "directory" : "file", mode });
+            const outPath = path.join(stagingDir, relPath);
+            await preparePrivateArchiveOutputPath({
+                destinationDir: stagingDir,
+                destinationRealDir: stagingDir,
+                relPath,
+                outPath,
+                originalPath: record.name,
+                isDirectory: entry.dir,
+                deadline,
+            });
+            if (!entry.dir) {
+                await writeZipFileEntry({ record, outPath, budget, deadline });
+            }
+        }
+        return acceptedEntries;
+    });
+}
+export async function extractArchive(params) {
+    const archivePath = params.archivePath;
+    const destDir = params.destDir;
+    const { entryUmask = 0 } = params;
+    if (!Number.isInteger(entryUmask) || entryUmask < 0 || entryUmask > 0o777) {
+        throw new RangeError("archive entryUmask must be an integer between 0 and 0o777");
+    }
+    const onFiltered = resolveArchiveFilteredEntryPolicy(params.onFiltered);
+    const kind = params.kind ?? resolveArchiveKind(archivePath);
+    if (!kind) {
+        throw new Error(`unsupported archive: ${archivePath}`);
+    }
+    const label = kind === "zip" ? "extract zip" : "extract tar";
+    const limits = resolveExtractLimits(params.limits);
+    const tarLimits = resolveTarMeterLimits(limits);
+    const native = getNativeBinding();
+    assertNoWindowsPathAlias(archivePath, "filesystem", "archive source uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(destDir, "filesystem", "archive destination uses a Windows filesystem namespace alias");
+    // Read the declared public fields before private adapters copy options: class
+    // getters and inherited policy must survive identically on every backend.
+    const options = {
+        archivePath, destDir,
+        durable: params.durable,
+        stripComponents: params.stripComponents, limits,
+        entryModes: params.entryModes, entryUmask, entryFilter: params.entryFilter, onFiltered,
+    };
+    await withExtractionDeadline(params.timeoutMs, label, async (deadline) => {
+        const stagedArchive = await stageArchiveFileForExtraction({ archivePath, limits, deadline });
+        try {
+            deadline.check();
+            const stagedOptions = { ...options, archivePath: stagedArchive.path, deadline };
+            if (native)
+                await extractNativeArchive({ ...stagedOptions, binding: native, kind, tarLimits });
+            else if (kind === "zip")
+                await extractZip(stagedOptions);
+            else
+                await extractWasmTar({ ...stagedOptions, kind, tarLimits });
+        }
+        finally {
+            await stagedArchive.cleanup();
+        }
+    });
+}
+async function extractWasmTar(params) {
+    const { deadline, tarLimits } = params;
+    const manifest = [];
+    await inspectTar({ archivePath: params.archivePath, kind: params.kind, limits: tarLimits, signal: deadline.signal,
+        onMember: (entry) => { manifest.push(entry); } });
+    deadline.check();
+    const destinationGuard = await prepareArchiveDestinationGuard(params.destDir);
+    await withStagedArchivePublication({ ...params, destinationGuard }, async (stagingDir) => {
+        const planEntry = createTarEntryPlanner({ ...params, rootDir: destinationGuard.realPath });
+        const accepted = manifest.flatMap((entry) => {
+            deadline.check();
+            const planned = planEntry(entry);
+            return planned ? [{ ...entry, ...planned }] : [];
+        });
+        await replayTar({ archivePath: params.archivePath, kind: params.kind, limits: tarLimits, signal: deadline.signal, members: accepted,
+            async consume(member, payload) {
+                deadline.check();
+                await preparePrivateArchiveOutputPath({ destinationDir: stagingDir, destinationRealDir: stagingDir,
+                    relPath: member.path, outPath: path.join(stagingDir, member.path), originalPath: member.path,
+                    isDirectory: member.kind === "directory", deadline });
+                if (member.kind === "file") {
+                    await runPinnedWriteHelper({ rootPath: stagingDir, relativeParentPath: path.posix.dirname(member.path),
+                        basename: path.posix.basename(member.path), mkdir: false, mode: 0o600, overwrite: false,
+                        sync: false,
+                        maxBytes: member.size, input: { kind: "stream", stream: Readable.from(payload) } });
+                }
+                deadline.check();
+            },
+        });
+        return accepted;
+    });
+}
+function throwMappedNativeArchiveError(error) {
+    if (error instanceof Error) {
+        const mapped = classifyArchiveParserError(error.message, { cause: error });
+        if (mapped)
+            throw mapped;
+        if (isArchiveFormatErrorMessage(error.message)) {
+            throw new ArchiveFormatError(error.message, { cause: error });
+        }
+        if (error.code === "InvalidArg") {
+            throw new ArchiveFormatError(`invalid archive: ${error.message}`, { cause: error });
+        }
+    }
+    throw error;
+}
+async function extractNativeArchive(params) {
+    const { archivePath, limits, tarLimits, deadline } = params;
+    const zipEntries = [];
+    if (params.kind === "zip") {
+        await admitZipFile(archivePath, limits, deadline, (entry) => { zipEntries.push(entry); });
+    }
+    const destinationGuard = await prepareArchiveDestinationGuard(params.destDir);
+    await withStagedArchivePublication({ ...params, destinationGuard }, async (stagingDir) => {
+        deadline.check();
+        // N-API retains completed task state on its signal; each pass needs its own.
+        const manifest = await params.binding
+            .inspectArchiveNative(archivePath, params.kind, tarLimits, AbortSignal.any([deadline.signal]))
+            .catch(throwMappedNativeArchiveError);
+        deadline.check();
+        assertArchiveEntryCountWithinLimit(manifest.length, limits);
+        if (params.kind === "zip") {
+            validateNativeZipManifest(manifest, zipEntries);
+        }
+        // Recheck the native manifest before any caller callback observes an entry.
+        if (params.kind !== "zip") {
+            for (const entry of manifest)
+                validateArchiveEntryPath(entry.path);
+        }
+        const planEntry = createArchiveEntryPlanner({ ...params, rootDir: stagingDir }, params.kind);
+        const plan = [];
+        for (const entry of manifest) {
+            deadline.check();
+            const mode = params.kind === "zip"
+                ? zipEntries[entry.index].creatorSystem === 3
+                    ? zipEntries[entry.index].externalAttributes >>> 16
+                    : undefined
+                : entry.mode;
+            const accepted = planEntry({ ...entry, mode });
+            if (accepted)
+                plan.push({ ...accepted, index: entry.index });
+        }
+        const directory = await fs.open(stagingDir, fsConstants.O_RDONLY |
+            (typeof fsConstants.O_DIRECTORY === "number" ? fsConstants.O_DIRECTORY : 0));
+        try {
+            deadline.check();
+            await params.binding.extractArchiveNative(archivePath, params.kind, directory.fd, plan.map((entry) => ({ ...entry, mode: entry.kind === "directory" ? 0o700 : 0o600 })), tarLimits, AbortSignal.any([deadline.signal])).catch(throwMappedNativeArchiveError);
+        }
+        finally {
+            await directory.close().catch(() => undefined);
+        }
+        return plan;
+    });
+}
+/** Complete TAR/gzip admission and zero-strip extraction policy, without output writes. */
+export async function inspectTarArchive(params) {
+    const archivePath = params.archivePath;
+    const onFiltered = resolveArchiveFilteredEntryPolicy(params.onFiltered);
+    const limits = resolveExtractLimits(params.limits);
+    const tarLimits = resolveTarMeterLimits(limits);
+    const native = getNativeBinding();
+    assertNoWindowsPathAlias(archivePath, "filesystem", "archive source uses a Windows filesystem namespace alias");
+    return await withExtractionDeadline(params.timeoutMs, "inspect tar", async (deadline) => {
+        const staged = await stageArchiveFileForExtraction({ archivePath, limits, deadline });
+        try {
+            // Staging closes descriptors asynchronously; expiry there must not start a decoder.
+            deadline.check();
+            const entries = [];
+            const append = (entry) => {
+                if (entry)
+                    entries.push(Object.freeze({ path: entry.path, kind: entry.kind, size: entry.size }));
+            };
+            const policy = { limits, entryFilter: params.entryFilter, onFiltered };
+            if (native) {
+                const manifest = await native.inspectArchiveNative(staged.path, "tar", tarLimits, deadline.signal)
+                    .catch(throwMappedNativeArchiveError);
+                deadline.check();
+                // Match extraction's whole-manifest validation before caller policy runs.
+                for (const entry of manifest)
+                    validateArchiveEntryPath(entry.path);
+                const planEntry = createArchiveEntryPlanner(policy, "tar");
+                for (const entry of manifest) {
+                    deadline.check();
+                    append(planEntry(entry));
+                }
+            }
+            else {
+                const manifest = [];
+                await inspectTar({ archivePath: staged.path, limits: tarLimits, signal: deadline.signal,
+                    onMember: (entry) => { manifest.push(entry); } });
+                const planEntry = createTarEntryPlanner(policy);
+                for (const entry of manifest) {
+                    deadline.check();
+                    append(planEntry(entry));
+                }
+            }
+            deadline.check();
+            // This is bounded evidence about the staged bytes, not a reusable write plan.
+            return Object.freeze(entries);
+        }
+        finally {
+            await staged.cleanup();
+        }
+    });
+}

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

@@ -0,0 +1 @@
+export declare function createAsyncLock(): <T>(fn: () => Promise<T>) => Promise<T>;

package/node_modules/@openclaw/fs-safe/dist/async-lock.js

@@ -0,0 +1,17 @@
+export function createAsyncLock() {
+    let lock = Promise.resolve();
+    return async function withLock(fn) {
+        const prev = lock;
+        let release;
+        lock = new Promise((resolve) => {
+            release = resolve;
+        });
+        await prev;
+        try {
+            return await fn();
+        }
+        finally {
+            release?.();
+        }
+    };
+}

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

@@ -0,0 +1,6 @@
+export { replaceFileAtomic, replaceFileAtomicSync, type ReplaceFileAtomicFileSystem, type ReplaceFileAtomicOptions, type ReplaceFileAtomicResult, type ReplaceFileAtomicDestinationState, type ReplaceFileAtomicSyncFileSystem, type ReplaceFileAtomicSyncOptions, } from "./replace-file.js";
+export type { RenameIdentityPolicy } from "./pinned-write-types.js";
+export type { ReplaceFileAtomicRestoreCleanup, ReplaceFileAtomicRestoreFailureDetails, ReplaceFileCopyFallbackRestorePolicy, ReplaceFileDestinationHardlinkPolicy, } from "./replace-file-copy-fallback.js";
+export { writeTextAtomic, type WriteTextAtomicOptions } from "./text-atomic.js";
+export { replaceDirectoryAtomic, type ReplaceDirectoryAtomicOptions } from "./replace-directory.js";
+export { movePathWithCopyFallback, type MovePathPublicationReceipt, type MovePathWithCopyFallbackOptions, } from "./move-path.js";

package/node_modules/@openclaw/fs-safe/dist/atomic.js

@@ -0,0 +1,4 @@
+export { replaceFileAtomic, replaceFileAtomicSync, } from "./replace-file.js";
+export { writeTextAtomic } from "./text-atomic.js";
+export { replaceDirectoryAtomic } from "./replace-directory.js";
+export { movePathWithCopyFallback, } from "./move-path.js";

package/node_modules/@openclaw/fs-safe/dist/bounded-read-stream.d.ts

@@ -0,0 +1,2 @@
+import { Transform } from "node:stream";
+export declare function createByteLimitTransform(maxBytes: number, overflowError: (bytes: number) => Error): Transform;

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

@@ -0,0 +1,15 @@
+import { Transform } from "node:stream";
+export function createByteLimitTransform(maxBytes, overflowError) {
+    let bytes = 0;
+    return new Transform({
+        transform(chunk, _encoding, callback) {
+            const buffer = chunk instanceof Buffer ? chunk : Buffer.from(chunk);
+            bytes += buffer.byteLength;
+            if (bytes > maxBytes) {
+                callback(overflowError(bytes));
+                return;
+            }
+            callback(null, buffer);
+        },
+    });
+}

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

@@ -0,0 +1,25 @@
+import type { FileHandle } from "node:fs/promises";
+type ReadableFileHandle = Pick<FileHandle, "read">;
+export declare function readBoundedAsync(maxBytes: number, readChunk: (scratch: Buffer, length: number) => Promise<number>, options?: {
+    observeRegularFileSize?: () => number | undefined;
+    initialSize?: number;
+    createLimitError?: () => Error;
+    /** Keep the result outside Node's shared small-buffer allocation pool. */
+    unpooled?: boolean;
+}): Promise<Buffer>;
+/**
+ * Reads from the handle's current offset without closing it. A bounded read
+ * consumes at most maxBytes + 1 bytes so growth after an earlier stat cannot
+ * force an unbounded allocation.
+ */
+export declare function readFileHandleBounded(handle: ReadableFileHandle, maxBytes: number): Promise<Buffer>;
+/** Async bounded read from a numeric descriptor. The caller owns the descriptor. */
+export declare function readFileDescriptorBounded(fd: number, maxBytes: number): Promise<Buffer>;
+export declare function readBoundedSync(maxBytes: number, readChunk: (scratch: Buffer, length: number) => number, options?: {
+    observeRegularFileSize?: () => number | undefined;
+    initialSize?: number;
+    createLimitError?: () => Error;
+}): Buffer;
+/** Sync bounded read from a numeric descriptor. The caller owns the descriptor. */
+export declare function readFileDescriptorBoundedSync(fd: number, maxBytes: number): Buffer;
+export {};