@openclaw/signal 2026.9.5 → 2026.9.7

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

@@ -0,0 +1,308 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
+import { ownExtractionDestinationMutation, } from "./archive-deadline.js";
+import { ArchiveSecurityError, } from "./archive-errors.js";
+import { FsSafeError } from "./errors.js";
+import { formatErrorDetail } from "./error-detail.js";
+import { root } from "./root.js";
+import { isNotFoundPathError, isPathInside } from "./path.js";
+import { resolveSecureTempRoot } from "./secure-temp-dir.js";
+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 { assertNoWindowsPathAlias } from "./windows-path-alias.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) {
+    deadline?.check();
+}
+function symlinkTraversalError(originalPath) {
+    return new ArchiveSecurityError("destination-symlink-traversal", `${ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK}: ${formatErrorDetail(originalPath)}`);
+}
+export async function createDirectoryIdentityGuard(dir) {
+    assertNoWindowsPathAlias(dir);
+    try {
+        const guard = await createAsyncDirectoryGuard(dir, { bigint: true });
+        assertNoWindowsPathAlias(guard.realPath);
+        return guard;
+    }
+    catch (err) {
+        if (err instanceof FsSafeError && err.code === "not-file") {
+            throw new ArchiveSecurityError("destination-symlink", "archive destination is a symlink");
+        }
+        throw err;
+    }
+}
+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) {
+    assertNoWindowsPathAlias(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);
+    assertNoWindowsPathAlias(realPath);
+    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) {
+    return (await prepareArchiveDestinationGuard(destDir)).realPath;
+}
+async function assertNoSymlinkTraversal(params) {
+    const parts = params.relPath.split(/[\\/]+/).filter(Boolean);
+    let current = path.resolve(params.rootDir);
+    for (const part of parts) {
+        current = path.join(current, part);
+        let stat;
+        try {
+            stat = fsSync.lstatSync(current);
+        }
+        catch (err) {
+            if (isNotFoundPathError(err)) {
+                continue;
+            }
+            throw err;
+        }
+        if (stat.isSymbolicLink()) {
+            throw symlinkTraversalError(params.originalPath);
+        }
+    }
+}
+export async function assertResolvedInsideDestination(params) {
+    const destinationRealDir = params.destinationRealDir;
+    const targetPath = params.targetPath;
+    const originalPath = params.originalPath;
+    assertNoWindowsPathAlias(destinationRealDir);
+    assertNoWindowsPathAlias(targetPath);
+    let resolved;
+    try {
+        resolved = realpathSync.native(targetPath);
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            return;
+        }
+        throw err;
+    }
+    assertNoWindowsPathAlias(resolved);
+    if (!isPathInside(destinationRealDir, resolved)) {
+        throw symlinkTraversalError(originalPath);
+    }
+}
+async function mkdirArchiveOutput(params) {
+    try {
+        const relativePath = params.relativePath;
+        // Archive names are literal; retain Root.mkdir's admission without home expansion.
+        await params.targetRoot.mkdir(relativePath === "~" || relativePath.startsWith("~/") ? `./${relativePath}` : relativePath);
+    }
+    catch (error) {
+        if (error instanceof FsSafeError) {
+            throw symlinkTraversalError(params.originalPath);
+        }
+        throw error;
+    }
+}
+function ownArchiveOutputPathParams(params) {
+    const deadline = params.deadline;
+    checkExtractionDeadline(deadline);
+    const destinationDir = params.destinationDir;
+    const destinationRealDir = params.destinationRealDir;
+    const relPath = params.relPath;
+    const outPath = params.outPath;
+    const originalPath = params.originalPath;
+    const isDirectory = params.isDirectory;
+    assertNoWindowsPathAlias(destinationDir);
+    assertNoWindowsPathAlias(destinationRealDir);
+    assertNoWindowsPathAlias(relPath, "relative");
+    assertNoWindowsPathAlias(outPath);
+    return { destinationDir, destinationRealDir, relPath, outPath, originalPath, isDirectory, deadline };
+}
+export async function prepareArchiveOutputPath(params) {
+    await prepareOutputPath(ownArchiveOutputPathParams(params));
+}
+export async function preparePrivateArchiveOutputPath(params, assertGuards, destinationGuard) {
+    await prepareOutputPath(ownArchiveOutputPathParams(params), assertGuards, true, destinationGuard);
+}
+async function prepareOutputPath(params, assertGuards, privateWorkingMode = false, existingDestinationGuard) {
+    const targetRoot = privateWorkingMode ? {
+        async mkdir(relativePath) {
+            // Retain Root.mkdir's strict alias admission before the shared traversal,
+            // while selecting private creation modes without adding a public option.
+            const resolved = await resolveRootPath({
+                absolutePath: path.resolve(params.destinationRealDir, await expandRelativePathWithHome(relativePath)),
+                rootPath: params.destinationRealDir,
+                rootCanonicalPath: params.destinationRealDir,
+                boundaryLabel: "archive destination",
+                rejectSymlinks: true,
+            });
+            checkExtractionDeadline(params.deadline);
+            await mkdirPathComponentsWithGuards({
+                rootReal: params.destinationRealDir,
+                targetPath: resolved.canonicalPath,
+                mode: 0o700,
+                rejectSymlinks: true,
+                beforeComponent: async () => {
+                    await assertOutputGuards();
+                    checkExtractionDeadline(params.deadline);
+                },
+            });
+        },
+    } : await root(params.destinationRealDir);
+    checkExtractionDeadline(params.deadline);
+    const destinationGuard = existingDestinationGuard ?? await createDirectoryIdentityGuard(params.destinationRealDir);
+    const assertOutputGuards = async () => {
+        // The merge's callback verifies this same original destination guard.
+        if (existingDestinationGuard && assertGuards)
+            await assertGuards();
+        else {
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
+            await assertGuards?.();
+        }
+    };
+    checkExtractionDeadline(params.deadline);
+    const relPath = params.relPath.split(path.sep).join(path.posix.sep);
+    await assertNoSymlinkTraversal({
+        rootDir: params.destinationDir,
+        relPath,
+        originalPath: params.originalPath,
+    });
+    checkExtractionDeadline(params.deadline);
+    if (params.isDirectory) {
+        await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("mkdir", params.outPath);
+        checkExtractionDeadline(params.deadline);
+        await ownExtractionDestinationMutation(params.deadline, async () => {
+            await assertOutputGuards();
+            checkExtractionDeadline(params.deadline);
+            await mkdirArchiveOutput({
+                targetRoot,
+                relativePath: relPath,
+                originalPath: params.originalPath,
+            });
+            checkExtractionDeadline(params.deadline);
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
+            await assertResolvedInsideDestination({
+                destinationRealDir: params.destinationRealDir,
+                targetPath: params.outPath,
+                originalPath: params.originalPath,
+            });
+            checkExtractionDeadline(params.deadline);
+        });
+        return;
+    }
+    const parentRel = path.posix.dirname(relPath);
+    if (parentRel !== ".") {
+        await getFsSafeTestHooks()?.beforeArchiveOutputMutation?.("mkdir", path.dirname(params.outPath));
+        checkExtractionDeadline(params.deadline);
+        await ownExtractionDestinationMutation(params.deadline, async () => {
+            await assertOutputGuards();
+            checkExtractionDeadline(params.deadline);
+            await mkdirArchiveOutput({
+                targetRoot,
+                relativePath: parentRel,
+                originalPath: params.originalPath,
+            });
+            checkExtractionDeadline(params.deadline);
+            await assertDirectoryIdentityGuard(destinationGuard);
+            checkExtractionDeadline(params.deadline);
+        });
+    }
+    await assertResolvedInsideDestination({
+        destinationRealDir: params.destinationRealDir,
+        targetPath: path.dirname(params.outPath),
+        originalPath: params.originalPath,
+    });
+    checkExtractionDeadline(params.deadline);
+}
+function assertSafeArchiveStagingPrefix(prefix) {
+    assertNoWindowsPathAlias(prefix, "relative");
+    if (!prefix ||
+        prefix === "." ||
+        prefix === ".." ||
+        prefix.includes("/") ||
+        prefix.includes("\\") ||
+        path.basename(prefix) !== prefix) {
+        throw new Error("archive staging prefix must be a single path segment");
+    }
+    return prefix;
+}
+export async function withStagedArchiveDestination(params) {
+    const destinationRealDir = params.destinationRealDir;
+    assertNoWindowsPathAlias(destinationRealDir);
+    const stagingRoot = resolveSecureTempRoot({
+        fallbackPrefix: "fs-safe-archive",
+        unsafeFallbackLabel: "archive staging temp dir",
+        warn: () => undefined,
+    });
+    assertNoWindowsPathAlias(stagingRoot);
+    if (isPathInside(destinationRealDir, stagingRoot)) {
+        throw new Error(`archive staging root must be outside destination: ${stagingRoot}`);
+    }
+    const stagingDirPrefix = params.stagingDirPrefix;
+    const stagingPrefix = assertSafeArchiveStagingPrefix(stagingDirPrefix ?? "fs-safe-archive-");
+    const stagingPathPrefix = path.join(stagingRoot, stagingPrefix);
+    assertNoWindowsPathAlias(stagingPathPrefix);
+    const stagingDir = await fs.mkdtemp(stagingPathPrefix);
+    const stagingGuard = await createDirectoryIdentityGuard(stagingDir);
+    try {
+        await fs.chmod(stagingDir, ARCHIVE_STAGING_MODE).catch(() => undefined);
+        await assertDirectoryIdentityGuard(stagingGuard);
+        return await params.run(stagingDir);
+    }
+    finally {
+        try {
+            await assertDirectoryIdentityGuard(stagingGuard);
+            await fs.rm(stagingDir, { recursive: true, force: true }).catch(() => undefined);
+        }
+        catch {
+            // The staging path identity changed; deleting by name could target data
+            // outside the private temp tree, so fail closed and leave it for OS cleanup.
+        }
+    }
+}
+export function createArchiveSymlinkTraversalError(originalPath) {
+    return symlinkTraversalError(originalPath);
+}

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

@@ -0,0 +1,27 @@
+import type { ArchiveKind } from "./archive-kind.js";
+import type { TarMeterLimits } from "./archive-limits.js";
+import { type AdmittedTarMember } from "./archive-tar-wasm.js";
+/** Buffers are private immutable snapshots, just like the staged file route. */
+type TarInput = {
+    archivePath: string;
+    archiveBuffer?: never;
+} | {
+    archiveBuffer: Buffer;
+    archivePath?: never;
+};
+export declare function inspectTar(params: TarInput & {
+    limits: TarMeterLimits;
+    signal?: AbortSignal;
+    kind?: Exclude<ArchiveKind, "zip">;
+    onMember?: (entry: AdmittedTarMember) => void;
+}): Promise<void>;
+/** Replay in physical order, retaining at most one decoded chunk. Every range
+ * comes from complete admission of the immutable input. */
+export declare function replayTar<T extends AdmittedTarMember>(params: TarInput & {
+    limits: TarMeterLimits;
+    signal?: AbortSignal;
+    kind?: Exclude<ArchiveKind, "zip">;
+    members: readonly T[];
+    consume(member: T, payload: AsyncIterable<Buffer>): Promise<void>;
+}): Promise<void>;
+export {};

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

@@ -0,0 +1,127 @@
+import fs from "node:fs";
+import { Readable, Writable } from "node:stream";
+import { finished, pipeline } from "node:stream/promises";
+import { createGunzip } from "node:zlib";
+import { GzipInput, isGzipBuffer, validateGzipBufferTail, validateGzipContainerTail } from "./archive-gzip-tail.js";
+import { ArchiveFormatError } from "./archive-errors.js";
+import { TarParserStream, TarWasmSession } 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);
+}
+async function gzipFile(filePath) {
+    const handle = await fs.promises.open(filePath, "r");
+    try {
+        const magic = Buffer.alloc(2);
+        const bytesRead = await readFileWindowFully(handle, magic, 0);
+        return bytesRead === 2 && isGzipBuffer(magic);
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function withTarStream(params, consume) {
+    const buffer = params.archiveBuffer;
+    const kind = params.kind ?? "tar";
+    const gzip = kind === "tar" && (buffer !== undefined ? isGzipBuffer(buffer) : await gzipFile(params.archivePath));
+    const session = new TarWasmSession(params.limits);
+    try {
+        const parser = new TarParserStream(params.limits, params.onMember, session);
+        const input = buffer !== undefined
+            ? Readable.from(bufferChunks(buffer), { objectMode: false, highWaterMark: 65536 })
+            : fs.createReadStream(params.archivePath, { highWaterMark: 65536 });
+        // 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);
+            gzipInput?.destroy(error);
+            decoder?.destroy(error);
+            parser.destroy(error);
+        };
+        // A pipeline with an async-generator stage can settle before its file's
+        // asynchronous close. Join the actual close events before freeing WASM.
+        const closed = Promise.all([input, parser, ...(decoder ? [decoder] : []), ...(gzipInput ? [gzipInput] : [])].map(stream => {
+            const closing = new Promise(resolve => { stream.once("close", resolve); });
+            return finished(stream, { cleanup: true }).then(() => undefined, (cause) => cause instanceof Error ? cause : new Error(String(cause))).then(async (error) => { await closing; return error; });
+        }));
+        const pumps = decoder && gzipInput
+            ? [pipeline(decoder, parser, { signal: params.signal }), pipeline(input, gzipInput, { signal: params.signal })]
+            : kind !== "tar"
+                ? [pipeline(input, (source) => session.decode(source, kind, params.signal), parser, { signal: params.signal })]
+                : [pipeline(input, parser, { signal: params.signal })];
+        // Either pump tears down both routes; join every pump even after the first failure.
+        const settled = Promise.all(pumps.map((pump) => pump.then(() => undefined, (cause) => {
+            const error = cause instanceof Error ? cause : new Error(String(cause));
+            destroy(error);
+            return error;
+        }))).then((errors) => errors.find((error) => error !== undefined));
+        try {
+            const result = await consume(parser);
+            const error = await settled;
+            if (error)
+                throw error;
+            const closeError = (await closed).find(error => error !== undefined);
+            if (closeError)
+                throw closeError;
+            if (gzipInput) {
+                if (buffer !== undefined)
+                    await validateGzipBufferTail(buffer, gzipInput.tailOffset, params.signal);
+                else
+                    await validateGzipContainerTail(params.archivePath, gzipInput.tailOffset, params.signal);
+            }
+            return result;
+        }
+        finally {
+            destroy();
+            await settled;
+            await closed;
+        }
+    }
+    finally {
+        session.dispose();
+    }
+}
+export async function inspectTar(params) {
+    await withTarStream(params, async (parser) => {
+        await pipeline(parser, new Writable({ write(_chunk, _encoding, callback) { callback(); } }));
+    });
+}
+/** Replay in physical order, retaining at most one decoded chunk. Every range
+ * comes from complete admission of the immutable input. */
+export async function replayTar(params) {
+    await withTarStream(params, async (parser) => {
+        const iterator = parser[Symbol.asyncIterator]();
+        let chunk = Buffer.alloc(0);
+        let position = 0;
+        async function* take(length) {
+            while (length > 0) {
+                if (!chunk.length) {
+                    const next = await iterator.next();
+                    if (next.done)
+                        throw new ArchiveFormatError("truncated admitted TAR range");
+                    chunk = next.value;
+                }
+                const count = Math.min(length, chunk.length);
+                const bytes = chunk.subarray(0, count);
+                chunk = chunk.subarray(count);
+                position += count;
+                length -= count;
+                yield bytes;
+            }
+        }
+        for (const member of params.members) {
+            if (member.offset < position)
+                throw new ArchiveFormatError("invalid admitted TAR range order");
+            for await (const _ of take(member.offset - position)) { /* Skip admitted gaps. */ }
+            const payload = take(member.size);
+            await params.consume(member, payload);
+            for await (const _ of payload) { /* Directories may carry ignored dump data. */ }
+            if (position !== member.offset + member.size)
+                throw new ArchiveFormatError("incomplete TAR range consumption");
+        }
+        // Includes unrequested/skipped members, trailer checks, and physical EOF.
+        while (!(await iterator.next()).done) { /* Drain the bounded parser stream. */ }
+    });
+}

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

@@ -0,0 +1,29 @@
+import { Transform, type TransformCallback } from "node:stream";
+import type { TarMeterLimits } from "./archive-limits.js";
+import type { TarEntryInfo } from "./archive-plan.js";
+export type AdmittedTarMember = TarEntryInfo & {
+    offset: number;
+};
+/** One bounded memory domain owns both admission and decompression. Its owner
+ * must join the decoder and parser before disposing this shared instance. */
+export declare class TarWasmSession {
+    private abi;
+    constructor(limits: TarMeterLimits);
+    private bytes;
+    private text;
+    parse(chunk: Buffer, onMember?: (entry: AdmittedTarMember) => void): void;
+    finish(): void;
+    private codecError;
+    decode(source: AsyncIterable<Buffer>, kind: "tar-zstd" | "tar-bzip2", signal?: AbortSignal): AsyncGenerator<Buffer>;
+    dispose(): void;
+}
+/** Backpressure-aware transport only; all TAR semantics live in the Rust core. */
+export declare class TarParserStream extends Transform {
+    private readonly onMember?;
+    private readonly session;
+    private readonly ownsSession;
+    constructor(limits: TarMeterLimits, onMember?: ((entry: AdmittedTarMember) => void) | undefined, session?: TarWasmSession);
+    _transform(chunk: Buffer, _encoding: BufferEncoding, callback: TransformCallback): void;
+    _flush(callback: TransformCallback): void;
+    _destroy(error: Error | null, callback: (error: Error | null) => void): void;
+}