@openclaw/signal 2026.9.5 → 2026.9.6

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

@@ -0,0 +1,119 @@
+import { ArchiveFormatError, ArchiveSecurityError } from "./archive-errors.js";
+import { createArchiveOutputPathTracker, resolveArchiveOutputPath, stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
+import { ARCHIVE_LIMIT_ERROR_CODE, ArchiveLimitError, assertArchiveEntryCountWithinLimit, assertArchiveEntryPathComponentsWithinLimit, createByteBudgetTracker, resolveExtractLimits, } from "./archive-limits.js";
+import { formatErrorDetail } from "./error-detail.js";
+// 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 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) => {
+        const kind = entry.kind === "file" || entry.kind === "directory" ? entry.kind
+            : entry.kind === "symlink" || entry.kind === "hardlink" ? "symlink" : "other";
+        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)}`);
+        }
+        if (kind === "symlink" || entry.kind === "blocked") {
+            const label = archiveKind === "zip" ? "zip" : "tar";
+            throw new ArchiveSecurityError("entry-link", `${label} entry is a link: ${formatErrorDetail(entry.path)}`);
+        }
+        if (!Number.isSafeInteger(entry.size) || entry.size < 0) {
+            throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
+        }
+        // Unsupported records remain visible to policy but cannot create outputs.
+        if (kind === "other")
+            return null;
+        if (kind === "file" || archiveKind !== "zip") {
+            budget.startEntry();
+            budget.addEntrySize(entry.size);
+        }
+        return { path: relPath, kind, size: entry.size,
+            mode: resolveArchiveEntryMode({ kind, archivedMode: entry.mode, policy: params.entryModes }) };
+    };
+}
+export function archiveEntryKindFromTarType(type) {
+    if (type === "Directory" || type === "GNUDumpDir")
+        return "directory";
+    if (type === "File" || type === "OldFile" || type === "ContiguousFile")
+        return "file";
+    if (type === "SymbolicLink" || type === "Link")
+        return "symlink";
+    return "other";
+}
+export function resolveArchiveEntryMode(params) {
+    const archivedMode = (params.archivedMode ?? 0) & 0o777;
+    if (params.policy === "preserve") {
+        return params.archivedMode == null ? (params.kind === "directory" ? 0o755 : 0o644) : archivedMode;
+    }
+    if (params.kind === "directory") {
+        return 0o755;
+    }
+    return archivedMode & 0o100 ? 0o755 : 0o644;
+}
+export function resolveArchiveFilteredEntryPolicy(value) {
+    if (value === undefined || value === "reject-archive")
+        return "reject-archive";
+    if (value === "skip-entry")
+        return "skip-entry";
+    throw new RangeError('archive onFiltered must be "reject-archive" or "skip-entry"');
+}
+export function shouldExtractArchiveEntry(params) {
+    const onFiltered = resolveArchiveFilteredEntryPolicy(params.onFiltered);
+    if (!params.filter || params.filter(params.entry) === "extract") {
+        return true;
+    }
+    if (onFiltered === "reject-archive") {
+        throw new ArchiveSecurityError("entry-filtered", `archive entry rejected by filter: ${formatErrorDetail(params.entry.path)}`);
+    }
+    return false;
+}
+const BLOCKED_TAR_ENTRY_TYPES = new Set([
+    "BlockDevice",
+    "CharacterDevice",
+    "FIFO",
+    "Socket",
+]);
+export function createTarEntryPlanner(params) {
+    // Preserve inherited/getter-backed public options and per-entry policy reads.
+    const plan = createArchiveEntryPlanner(params, "tar");
+    return (entry) => {
+        const kind = BLOCKED_TAR_ENTRY_TYPES.has(entry.type) ? "blocked" : archiveEntryKindFromTarType(entry.type);
+        // The public checker accepts structural entry objects, including class getters.
+        return plan({ path: entry.path, kind, size: entry.size, mode: entry.mode });
+    };
+}
+export function createTarEntryPreflightChecker(params) {
+    const plan = createTarEntryPlanner(params);
+    return (entry) => plan(entry) !== null;
+}

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

@@ -0,0 +1,5 @@
+import { type ArchiveKind } from "./archive-kind.js";
+export declare function readArchiveEntry(archivePath: string, entryPath: string, options: {
+    maxBytes: number;
+    kind?: ArchiveKind;
+}): Promise<Buffer>;

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

@@ -0,0 +1,243 @@
+import { classifyArchiveParserError } from "./archive-parser-errors.js";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import { Readable, Writable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { readBoundedAsync } from "./bounded-read.js";
+import { ArchiveFormatError, ArchiveSecurityError, isArchiveFormatErrorMessage, } from "./archive-errors.js";
+import { formatErrorDetail } from "./error-detail.js";
+import { stripArchivePath, validateArchiveEntryPath, } from "./archive-entry.js";
+import { 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 { loadAdmittedZipArchive } from "./archive-zip-loader.js";
+import { createZipIntegrityTransform, normalizeZipIntegrityError, } from "./archive-zip-integrity.js";
+import { isZipSymlinkEntry, zipEntryKind } from "./archive-zip-entry.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 { validateNativeZipManifest } from "./archive-zip-manifest.js";
+import { resolveExtractLimits, resolveTarMeterLimits } from "./archive-limits.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+function canonicalEntryPath(entryPath) {
+    validateArchiveEntryPath(entryPath, { escapeLabel: "archive root" });
+    return stripArchivePath(entryPath, 0) ?? "";
+}
+function normalizedRequestedEntry(entryPath) {
+    const normalized = canonicalEntryPath(entryPath);
+    if (!normalized || /[/\\]$/.test(entryPath)) {
+        throw new Error(`archive entry is not a file: ${formatErrorDetail(entryPath)}`);
+    }
+    return normalized;
+}
+async function readAdmittedTarPayload(stream, size) {
+    // Complete admission has bounded this exact range. Copy as it arrives so
+    // decoder chunks can be released before the caller receives the owned result.
+    const result = Buffer.allocUnsafe(size);
+    let total = 0;
+    for await (const chunk of stream) {
+        if (chunk.length > size - total) {
+            throw new ArchiveFormatError("invalid admitted TAR payload size");
+        }
+        chunk.copy(result, total);
+        total += chunk.length;
+    }
+    if (total !== size)
+        throw new ArchiveFormatError("truncated admitted TAR range");
+    return result;
+}
+async function readArchiveInput(archivePath) {
+    assertNoWindowsPathAlias(archivePath);
+    const resolved = realpathSync.native(archivePath);
+    assertNoWindowsPathAlias(resolved);
+    const before = await inspectFileIdentity(async () => {
+        const stat = fsSync.lstatSync(archivePath, { bigint: true });
+        if (stat.isSymbolicLink() || !stat.isFile()) {
+            throw new Error(`archive is not a regular file: ${archivePath}`);
+        }
+        return stat;
+    });
+    const handle = await fs.open(resolved, resolveReadOpenFlags());
+    try {
+        const opened = await inspectFileIdentity(async () => {
+            const stat = fsSync.fstatSync(handle.fd, { bigint: true });
+            if (!stat.isFile())
+                throw new Error("archive changed during validation");
+            return stat;
+        }, before);
+        await inspectFileIdentity(async () => {
+            const stat = fsSync.lstatSync(resolved, { bigint: true });
+            if (stat.isSymbolicLink() || !stat.isFile())
+                throw new Error("archive changed during validation");
+            return stat;
+        }, opened);
+        // Native archive workers borrow this private buffer. A pooled allocation could
+        // share its ArrayBuffer with unrelated JS buffers while the worker runs.
+        return await readBoundedAsync(DEFAULT_MAX_ARCHIVE_BYTES_ZIP, async (buffer, length) => (await handle.read(buffer, 0, length, null)).bytesRead, { unpooled: true, observeRegularFileSize: () => {
+                const size = fsSync.fstatSync(handle.fd).size;
+                return Number.isSafeInteger(size) && size >= 0 ? size : undefined;
+            } });
+    }
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "path-mismatch") {
+            throw new FsSafeError("path-mismatch", "archive changed during validation", { cause: error });
+        }
+        throw error;
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+async function readZipEntry(buffer, entryPath, maxBytes, admitted) {
+    const archive = await loadAdmittedZipArchive(buffer, admitted);
+    let entry;
+    // JSZip keys retain some aliases and may use Unicode Path metadata. Scan the
+    // effective entries once, after raw ZIP admission has rejected collisions.
+    for (const candidate of Object.values(archive.files)) {
+        if (canonicalEntryPath(candidate.name) !== entryPath)
+            continue;
+        if (entry) {
+            throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(entryPath)}`);
+        }
+        entry = candidate;
+    }
+    if (!entry || entry.dir) {
+        throw new Error(`archive entry not found: ${formatErrorDetail(entryPath)}`);
+    }
+    if (isZipSymlinkEntry(entry)) {
+        throw new Error(`archive entry is a link: ${formatErrorDetail(entryPath)}`);
+    }
+    if (zipEntryKind(entry) !== "file")
+        throw new Error(`archive entry is not a file: ${formatErrorDetail(entryPath)}`);
+    const integrity = createZipIntegrityTransform(entry);
+    const stream = typeof entry.nodeStream === "function"
+        ? entry.nodeStream()
+        : Readable.from(await entry.async("nodebuffer"));
+    const chunks = [];
+    let total = 0;
+    const destination = new Writable({
+        write(chunk, _encoding, callback) {
+            total += chunk.length;
+            if (total > maxBytes) {
+                callback(new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT));
+                return;
+            }
+            chunks.push(chunk);
+            callback();
+        },
+    });
+    try {
+        // Iterator teardown can mask limit errors on Node 22; keep them in stream callbacks.
+        await pipeline(stream, integrity, destination);
+        return Buffer.concat(chunks, total);
+    }
+    catch (error) {
+        throw normalizeZipIntegrityError(error);
+    }
+}
+async function readTarEntry(archiveBuffer, entryPath, maxBytes, kind) {
+    const seenPaths = new Set();
+    let selected;
+    const limits = resolveTarMeterLimits();
+    await inspectTar({ archiveBuffer, kind, limits, onMember(info) {
+            const normalized = canonicalEntryPath(info.path);
+            if (seenPaths.has(normalized)) {
+                throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(normalized)}`);
+            }
+            seenPaths.add(normalized);
+            if (normalized === entryPath)
+                selected = info;
+        } });
+    if (!selected)
+        throw new Error(`archive entry not found: ${formatErrorDetail(entryPath)}`);
+    if (!["File", "OldFile", "ContiguousFile"].includes(selected.type)) {
+        throw new Error(`archive entry is not a file: ${formatErrorDetail(entryPath)}`);
+    }
+    if (selected.size > maxBytes)
+        throw new ArchiveLimitError(ARCHIVE_LIMIT_ERROR_CODE.ENTRY_EXTRACTED_SIZE_EXCEEDS_LIMIT);
+    if (kind === "tar" && !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, kind, limits, members: [selected], async consume(member, payload) {
+            result = await readAdmittedTarPayload(payload, member.size);
+        } });
+    return result;
+}
+function selectNativeEntry(manifest, requested, displayPath) {
+    const seen = new Set();
+    let selected;
+    for (const entry of manifest) {
+        const normalized = canonicalEntryPath(entry.path);
+        if (seen.has(normalized)) {
+            throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(normalized)}`);
+        }
+        seen.add(normalized);
+        if (normalized === requested) {
+            if (entry.kind !== "file")
+                throw new Error(`archive entry is not a file: ${formatErrorDetail(displayPath)}`);
+            selected = entry;
+        }
+    }
+    if (!selected)
+        throw new Error(`archive entry not found: ${formatErrorDetail(displayPath)}`);
+    return selected;
+}
+function throwNativeReadError(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 });
+    }
+    throw error;
+}
+async function readNativeBufferEntry(native, buffer, kind, requested, displayPath, maxBytes, zipEntries) {
+    try {
+        const signal = new AbortController().signal;
+        const limits = resolveTarMeterLimits();
+        const reader = kind === "zip"
+            ? await native.openZipBufferNative(buffer, limits, AbortSignal.any([signal]))
+            : await native.openTarBufferNative(buffer, kind, limits, AbortSignal.any([signal]));
+        const manifest = reader.entries;
+        if (kind === "zip")
+            validateNativeZipManifest(manifest, zipEntries);
+        const selected = selectNativeEntry(manifest, requested, displayPath);
+        return await reader.readEntry(selected.index, maxBytes, AbortSignal.any([signal]));
+    }
+    catch (error) {
+        throwNativeReadError(error);
+    }
+}
+export async function readArchiveEntry(archivePath, entryPath, options) {
+    if (!Number.isSafeInteger(options.maxBytes) || options.maxBytes < 0) {
+        throw new RangeError("maxBytes must be a non-negative safe integer");
+    }
+    const kind = options.kind ?? resolveArchiveKind(archivePath);
+    if (!kind) {
+        throw new Error(`unsupported archive: ${archivePath}`);
+    }
+    const requestedEntry = normalizedRequestedEntry(entryPath);
+    assertNoWindowsPathAlias(archivePath, "filesystem", "archive source uses a Windows filesystem namespace alias");
+    const buffer = await readArchiveInput(archivePath);
+    const zipEntries = [];
+    if (kind === "zip")
+        admitZipBuffer(buffer, resolveExtractLimits(), entry => { zipEntries.push(entry); });
+    const native = getNativeBinding();
+    if (native)
+        return await readNativeBufferEntry(native, buffer, kind, requestedEntry, entryPath, options.maxBytes, zipEntries);
+    return kind === "zip" ? await readZipEntry(buffer, requestedEntry, options.maxBytes, zipEntries)
+        : await readTarEntry(buffer, requestedEntry, options.maxBytes, kind);
+}

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

@@ -0,0 +1,33 @@
+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<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;
+    targetPath: string;
+    originalPath: string;
+}): Promise<void>;
+type ArchiveOutputPathParams = {
+    destinationDir: string;
+    destinationRealDir: string;
+    relPath: string;
+    outPath: string;
+    originalPath: string;
+    isDirectory: boolean;
+    deadline?: ExtractionDeadline;
+};
+export declare function prepareArchiveOutputPath(params: ArchiveOutputPathParams): 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;
+    run: (stagingDir: string) => Promise<T>;
+}): Promise<T>;
+export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
+export declare function createArchiveSymlinkTraversalError(originalPath: string): ArchiveSecurityError;