@openclaw/openshell-sandbox 2026.9.1 → 2026.9.3

package/node_modules/@openclaw/fs-safe/dist/file-store.js

@@ -0,0 +1,357 @@
+import syncFs from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { readFileDescriptorBoundedSync } from "./bounded-read.js";
+import { FsSafeError } from "./errors.js";
+import { assertFileStoreMaxBytes } from "./file-store-limit.js";
+import { pruneExpiredStoreEntries } from "./file-store-prune.js";
+import { ensureParentInRoot, openPrivateStoreLockRoot, openWritableStoreRoot, writeStreamToTempSource, } from "./file-store-boundary.js";
+import { writeFileSyncAtomic } from "./file-store-sync-write.js";
+import { createJsonStore } from "./json-document-store.js";
+import { stringifyJsonDocument } from "./json-stringify.js";
+import { isNotFoundPathError, resolveSafeRelativePath, splitSafeRelativePath } from "./path.js";
+import { throwFsSafeReadError } from "./root-errors.js";
+import { root } from "./root.js";
+import { DEFAULT_ROOT_MAX_BYTES } from "./root-impl.js";
+import { readRegularFile } from "./regular-file.js";
+import { matchRootFileOpenFailure, openRootFileSync } from "./root-file.js";
+import { writeSecretFileAtomic } from "./secret-file.js";
+function assertRelativePath(relativePath) {
+    const raw = relativePath.trim();
+    if (!raw || raw !== relativePath) {
+        throw new FsSafeError("invalid-path", "store key must be non-empty and unpadded");
+    }
+    const segments = splitSafeRelativePath(raw);
+    if (segments.length === 0 ||
+        segments.join("/") !== raw ||
+        raw.normalize("NFC") !== raw ||
+        segments.some((segment) => /[ .]$/u.test(segment))) {
+        throw new FsSafeError("invalid-path", "store key must use one canonical relative spelling");
+    }
+    return raw;
+}
+function resolveStorePath(rootDir, relativePath) {
+    return resolveSafeRelativePath(rootDir, assertRelativePath(relativePath));
+}
+function isNotFound(error) {
+    return error instanceof FsSafeError ? error.code === "not-found" : isNotFoundPathError(error);
+}
+function handleSyncStoreReadOpenFailure(opened) {
+    return matchRootFileOpenFailure(opened, {
+        path: (failure) => {
+            if (isNotFound(failure.error)) {
+                return null;
+            }
+            throw new FsSafeError("path-mismatch", "store target changed during read", {
+                cause: failure.error instanceof Error ? failure.error : undefined,
+            });
+        },
+        validation: (failure) => {
+            if (failure.error instanceof FsSafeError) {
+                throw failure.error;
+            }
+            // Validation failures mean the path existed but violated store policy
+            // (directory, hardlink, symlink race). Do not report them as missing.
+            throw new FsSafeError("path-mismatch", "store target failed read validation", {
+                cause: failure.error instanceof Error ? failure.error : undefined,
+            });
+        },
+        io: (failure) => throwFsSafeReadError(failure.error, "store"),
+        fallback: (failure) => {
+            throw new FsSafeError("path-mismatch", "store target changed during read", {
+                cause: failure.error instanceof Error ? failure.error : undefined,
+            });
+        },
+    });
+}
+async function readFileStoreCopySource(params) {
+    const sourceStat = syncFs.lstatSync(params.sourcePath);
+    if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
+        throw new FsSafeError("not-file", "source path is not a file");
+    }
+    assertFileStoreMaxBytes(sourceStat.size, params.maxBytes);
+    try {
+        return (await readRegularFile({ filePath: params.sourcePath, maxBytes: params.maxBytes }))
+            .buffer;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("regular file") || message.includes("not a regular file")) {
+            throw new FsSafeError("not-file", "source path is not a file", {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+        if (params.maxBytes !== undefined && message.includes(`exceeds ${params.maxBytes} bytes`)) {
+            throw new FsSafeError("too-large", `file exceeds maximum size of ${params.maxBytes} bytes`, {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+        throw error;
+    }
+}
+async function copyIntoRoot(params) {
+    const relativePath = assertRelativePath(params.relativePath);
+    const destination = resolveStorePath(params.rootDir, relativePath);
+    const sourceStat = syncFs.lstatSync(params.sourcePath);
+    if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
+        throw new FsSafeError("not-file", "source path is not a file");
+    }
+    assertFileStoreMaxBytes(sourceStat.size, params.maxBytes);
+    const dirMode = params.dirMode ?? 0o700;
+    const scopedRoot = await openWritableStoreRoot({
+        rootDir: params.rootDir,
+        dirMode,
+        maxBytes: params.maxBytes,
+    });
+    await ensureParentInRoot(scopedRoot, relativePath, dirMode);
+    await scopedRoot.copyIn(relativePath, params.sourcePath, {
+        maxBytes: params.maxBytes,
+        mkdir: false,
+        mode: params.mode ?? 0o600,
+    });
+    return destination;
+}
+export function fileStore(options) {
+    const rootDir = path.resolve(options.rootDir);
+    const privateMode = options.private ?? false;
+    const dirMode = options.dirMode ?? 0o700;
+    const mode = options.mode ?? 0o600;
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
+    async function openRoot() {
+        return await root(rootDir, { hardlinks: "reject", maxBytes });
+    }
+    async function write(relativePath, data, writeOptions) {
+        const safeRelativePath = assertRelativePath(relativePath);
+        const destination = resolveStorePath(rootDir, safeRelativePath);
+        const content = Buffer.isBuffer(data) ? data : Buffer.from(data);
+        const writeMaxBytes = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
+        assertFileStoreMaxBytes(content.byteLength, writeMaxBytes);
+        if (privateMode) {
+            await writeSecretFileAtomic({
+                rootDir,
+                filePath: destination,
+                content,
+                dirMode: writeOptions?.dirMode ?? dirMode,
+                mode: writeOptions?.mode ?? mode,
+            });
+            return destination;
+        }
+        const writeDirMode = writeOptions?.dirMode ?? dirMode;
+        const scopedRoot = await openWritableStoreRoot({
+            rootDir,
+            dirMode: writeDirMode,
+            maxBytes: writeMaxBytes,
+        });
+        await ensureParentInRoot(scopedRoot, safeRelativePath, writeDirMode);
+        await scopedRoot.write(safeRelativePath, content, {
+            mkdir: false,
+            mode: writeOptions?.mode ?? mode,
+        });
+        return destination;
+    }
+    return {
+        rootDir,
+        path: (relativePath) => resolveStorePath(rootDir, relativePath),
+        root: openRoot,
+        write,
+        writeStream: async (relativePath, stream, writeOptions) => {
+            const safeRelativePath = assertRelativePath(relativePath);
+            const destination = resolveStorePath(rootDir, safeRelativePath);
+            const configuredLimit = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
+            const limit = configuredLimit ?? (privateMode ? DEFAULT_ROOT_MAX_BYTES : undefined);
+            if (privateMode) {
+                const chunks = [];
+                let total = 0;
+                for await (const chunk of stream) {
+                    const buffer = typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk);
+                    total += buffer.byteLength;
+                    assertFileStoreMaxBytes(total, limit);
+                    chunks.push(buffer);
+                }
+                await writeSecretFileAtomic({
+                    rootDir,
+                    filePath: destination,
+                    content: Buffer.concat(chunks),
+                    dirMode: writeOptions?.dirMode ?? dirMode,
+                    mode: writeOptions?.mode ?? mode,
+                });
+                return destination;
+            }
+            const staged = await writeStreamToTempSource({
+                stream,
+                maxBytes: limit,
+                mode: writeOptions?.mode ?? mode,
+            });
+            try {
+                await copyIntoRoot({
+                    rootDir,
+                    relativePath: safeRelativePath,
+                    sourcePath: staged.path,
+                    maxBytes: limit,
+                    mode: writeOptions?.mode ?? mode,
+                    tempPrefix: writeOptions?.tempPrefix,
+                    dirMode: writeOptions?.dirMode ?? dirMode,
+                });
+            }
+            finally {
+                await staged.cleanup();
+            }
+            return destination;
+        },
+        copyIn: async (relativePath, sourcePath, writeOptions) => {
+            const configuredLimit = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
+            if (privateMode) {
+                const buffer = await readFileStoreCopySource({
+                    sourcePath,
+                    maxBytes: configuredLimit ?? DEFAULT_ROOT_MAX_BYTES,
+                });
+                return await write(relativePath, buffer, writeOptions);
+            }
+            return await copyIntoRoot({
+                rootDir,
+                relativePath,
+                sourcePath,
+                dirMode: writeOptions?.dirMode ?? dirMode,
+                maxBytes: configuredLimit,
+                mode: writeOptions?.mode ?? mode,
+                tempPrefix: writeOptions?.tempPrefix,
+            });
+        },
+        open: async (relativePath, readOptions) => await (await openRoot()).open(assertRelativePath(relativePath), readOptions),
+        read: async (relativePath, readOptions) => await (await openRoot()).read(assertRelativePath(relativePath), readOptions),
+        readBytes: async (relativePath, readOptions) => await (await openRoot()).readBytes(assertRelativePath(relativePath), readOptions),
+        readText: async (relativePath, readOptions) => {
+            const { encoding = "utf8", ...options } = readOptions ?? {};
+            return (await (await openRoot()).read(assertRelativePath(relativePath), options)).buffer
+                .toString(encoding);
+        },
+        readTextIfExists: async (relativePath, readOptions) => {
+            try {
+                return await (await openRoot()).readText(assertRelativePath(relativePath), readOptions);
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throwFsSafeReadError(error, "store");
+            }
+        },
+        readJson: async (relativePath, readOptions) => {
+            const { encoding = "utf8", ...options } = readOptions ?? {};
+            return JSON.parse((await (await openRoot()).read(assertRelativePath(relativePath), options)).buffer
+                .toString(encoding));
+        },
+        readJsonIfExists: async (relativePath, readOptions) => {
+            try {
+                return await (await openRoot()).readJson(assertRelativePath(relativePath), readOptions);
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    return null;
+                }
+                throwFsSafeReadError(error, "store");
+            }
+        },
+        remove: async (relativePath) => {
+            await (await openRoot()).remove(assertRelativePath(relativePath));
+        },
+        exists: async (relativePath) => await (await openRoot()).exists(assertRelativePath(relativePath)),
+        writeText: async (relativePath, data, writeOptions) => await write(relativePath, data, writeOptions),
+        writeJson: async (relativePath, data, writeOptions) => {
+            const json = stringifyJsonDocument(data, null, 2);
+            return await write(relativePath, writeOptions?.trailingNewline === false ? json : `${json}\n`, writeOptions);
+        },
+        json: (relativePath, jsonOptions) => {
+            const filePath = resolveStorePath(rootDir, relativePath);
+            return createJsonStore({
+                filePath,
+                ...(privateMode ? {
+                    prepareLock: () => openPrivateStoreLockRoot({ rootDir, filePath, mode, dirMode }),
+                } : {}),
+                readIfExists: async () => {
+                    try {
+                        return await (await openRoot()).readJson(assertRelativePath(relativePath));
+                    }
+                    catch (error) {
+                        if (isNotFound(error)) {
+                            return undefined;
+                        }
+                        throw error;
+                    }
+                },
+                readRequired: async () => await (await openRoot()).readJson(assertRelativePath(relativePath)),
+                write: async (value, options) => {
+                    const json = stringifyJsonDocument(value, null, 2);
+                    await write(relativePath, options?.trailingNewline === false ? json : `${json}\n`);
+                },
+            }, jsonOptions);
+        },
+        pruneExpired: async (pruneOptions) => {
+            await pruneExpiredStoreEntries({ rootDir, dirMode, options: pruneOptions });
+        },
+    };
+}
+export function fileStoreSync(options) {
+    const rootDir = path.resolve(options.rootDir);
+    const privateMode = options.private ?? false;
+    const dirMode = options.dirMode ?? 0o700;
+    const mode = options.mode ?? 0o600;
+    const maxBytes = normalizeMaxBytes(options.maxBytes);
+    function write(relativePath, data, writeOptions) {
+        const destination = resolveStorePath(rootDir, relativePath);
+        const content = Buffer.isBuffer(data) ? data : Buffer.from(data);
+        const writeMaxBytes = normalizeMaxBytes(writeOptions?.maxBytes, { defaultValue: maxBytes });
+        assertFileStoreMaxBytes(content.byteLength, writeMaxBytes);
+        return writeFileSyncAtomic({
+            rootDir,
+            filePath: destination,
+            content,
+            privateMode,
+            dirMode: writeOptions?.dirMode ?? dirMode,
+            mode: writeOptions?.mode ?? mode,
+        });
+    }
+    return {
+        rootDir,
+        path: (relativePath) => resolveStorePath(rootDir, relativePath),
+        readTextIfExists: (relativePath, readOptions) => {
+            const limit = normalizeMaxBytes(readOptions?.maxBytes, { defaultValue: maxBytes });
+            const targetPath = resolveStorePath(rootDir, relativePath);
+            const opened = openRootFileSync({
+                absolutePath: targetPath,
+                rootPath: rootDir,
+                boundaryLabel: "store root",
+                rejectHardlinks: true,
+            });
+            if (!opened.ok) {
+                return handleSyncStoreReadOpenFailure(opened);
+            }
+            try {
+                assertFileStoreMaxBytes(opened.stat.size, limit);
+                try {
+                    return limit === undefined
+                        ? syncFs.readFileSync(opened.fd, "utf8")
+                        : readFileDescriptorBoundedSync(opened.fd, limit).toString("utf8");
+                }
+                catch (error) {
+                    throwFsSafeReadError(error, "store");
+                }
+            }
+            finally {
+                syncFs.closeSync(opened.fd);
+            }
+        },
+        readJsonIfExists: (relativePath, readOptions) => {
+            const raw = fileStoreSync({ rootDir, private: privateMode, dirMode, mode, maxBytes })
+                .readTextIfExists(relativePath, readOptions);
+            return raw === null ? null : JSON.parse(raw);
+        },
+        write,
+        writeText: (relativePath, data, writeOptions) => write(relativePath, data, writeOptions),
+        writeJson: (relativePath, data, writeOptions) => {
+            const json = stringifyJsonDocument(data, null, 2);
+            return write(relativePath, writeOptions?.trailingNewline === false ? json : `${json}\n`, writeOptions);
+        },
+    };
+}

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

@@ -0,0 +1,5 @@
+import fs from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+export declare function syncFileBestEffort(handle: Pick<FileHandle, "sync">): Promise<void>;
+export declare function syncFileBestEffortSync(fd: number, fsModule?: Pick<typeof fs, "fsyncSync">): void;
+//# sourceMappingURL=file-sync.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/file-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-sync.d.ts","sourceRoot":"","sources":["../src/file-sync.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAMxF;AAED,wBAAgB,sBAAsB,CACpC,EAAE,EAAE,MAAM,EACV,QAAQ,GAAE,IAAI,CAAC,OAAO,EAAE,EAAE,WAAW,CAAM,GAC1C,IAAI,CAMN"}

package/node_modules/@openclaw/fs-safe/dist/file-sync.js

@@ -0,0 +1,19 @@
+import fs from "node:fs";
+export async function syncFileBestEffort(handle) {
+    try {
+        await handle.sync();
+    }
+    catch (error) {
+        if (error?.code !== "EPERM")
+            throw error;
+    }
+}
+export function syncFileBestEffortSync(fd, fsModule = fs) {
+    try {
+        fsModule.fsyncSync(fd);
+    }
+    catch (error) {
+        if (error?.code !== "EPERM")
+            throw error;
+    }
+}

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

@@ -0,0 +1,8 @@
+/** Keeps short names exact and trims only the filename tail of a composite temp name. */
+export declare function fitFileNameToPortableComponent(params: {
+    prefix: string;
+    fileName: string;
+    suffix: string;
+}): string;
+export declare function sanitizeUntrustedFileName(fileName: string, fallbackName: string): string;
+//# sourceMappingURL=filename.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"filename.d.ts","sourceRoot":"","sources":["../src/filename.ts"],"names":[],"mappings":"AAqCA,yFAAyF;AACzF,wBAAgB,8BAA8B,CAAC,MAAM,EAAE;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CA8BT;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAgCxF"}

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

@@ -0,0 +1,91 @@
+import path from "node:path";
+import { WINDOWS_RESERVED_DEVICE_NAMES } from "./device-path.js";
+const WINDOWS_INVALID_FILE_NAME_CHARACTERS = new Set('<>:"/\\|?*');
+function trimWindowsIgnoredSuffix(value) {
+    let end = value.length;
+    while (end > 0) {
+        const character = value.charCodeAt(end - 1);
+        if (character !== 0x20 && character !== 0x2e) {
+            break;
+        }
+        end -= 1;
+    }
+    return end === value.length ? value : value.slice(0, end);
+}
+function suffixWindowsReservedDeviceName(fileName) {
+    const extensionIndex = fileName.indexOf(".");
+    const baseNameEnd = extensionIndex < 0 ? fileName.length : extensionIndex;
+    const baseName = fileName.slice(0, baseNameEnd);
+    const deviceBaseName = trimWindowsIgnoredSuffix(baseName);
+    if (!WINDOWS_RESERVED_DEVICE_NAMES.has(deviceBaseName.toUpperCase())) {
+        return fileName;
+    }
+    return `${baseName}_${fileName.slice(baseNameEnd)}`;
+}
+const PORTABLE_FILE_NAME_BYTES = 255;
+function normalizedFileNameBytes(value) {
+    return Math.max(Buffer.byteLength(value.normalize("NFC"), "utf8"), Buffer.byteLength(value.normalize("NFD"), "utf8"));
+}
+/** Keeps short names exact and trims only the filename tail of a composite temp name. */
+export function fitFileNameToPortableComponent(params) {
+    const complete = `${params.prefix}${params.fileName}${params.suffix}`;
+    if (normalizedFileNameBytes(complete) <= PORTABLE_FILE_NAME_BYTES) {
+        return params.fileName;
+    }
+    if (normalizedFileNameBytes(`${params.prefix}${params.suffix}`) > PORTABLE_FILE_NAME_BYTES) {
+        // Preserve the existing OS error for a caller-supplied prefix that cannot fit.
+        return params.fileName;
+    }
+    const extension = path.extname(params.fileName);
+    const preserveExtension = normalizedFileNameBytes(`${params.prefix}${extension}${params.suffix}`) <=
+        PORTABLE_FILE_NAME_BYTES;
+    const tailSuffix = preserveExtension ? extension : "";
+    const stem = preserveExtension
+        ? params.fileName.slice(0, params.fileName.length - extension.length)
+        : params.fileName;
+    const codePoints = Array.from(stem);
+    let low = 0;
+    let high = codePoints.length;
+    while (low < high) {
+        const length = Math.ceil((low + high) / 2);
+        const candidate = `${params.prefix}${codePoints.slice(0, length).join("")}${tailSuffix}${params.suffix}`;
+        if (normalizedFileNameBytes(candidate) <= PORTABLE_FILE_NAME_BYTES) {
+            low = length;
+        }
+        else {
+            high = length - 1;
+        }
+    }
+    return `${codePoints.slice(0, low).join("")}${tailSuffix}`;
+}
+export function sanitizeUntrustedFileName(fileName, fallbackName) {
+    const trimmed = typeof fileName === "string" ? fileName.trim() : "";
+    if (!trimmed) {
+        return fallbackName;
+    }
+    let base = path.posix.basename(trimmed);
+    base = path.win32.basename(base);
+    let cleaned = "";
+    for (let i = 0; i < base.length; i++) {
+        const code = base.charCodeAt(i);
+        if (code < 0x20 ||
+            (code >= 0x7f && code <= 0x9f) ||
+            WINDOWS_INVALID_FILE_NAME_CHARACTERS.has(base[i])) {
+            continue;
+        }
+        cleaned += base[i];
+    }
+    base = cleaned.trim();
+    if (!base || base === "." || base === "..") {
+        return fallbackName;
+    }
+    base = suffixWindowsReservedDeviceName(base);
+    if (base.length > 200) {
+        base = base.slice(0, 200);
+        const trailingCodeUnit = base.charCodeAt(base.length - 1);
+        if (trailingCodeUnit >= 0xd800 && trailingCodeUnit <= 0xdbff) {
+            base = base.slice(0, -1);
+        }
+    }
+    return base;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Returns true when `fs.stat()` can stat the path.
+ *
+ * This follows stat semantics: broken symlinks return false, while symlinks to
+ * existing targets return true.
+ */
+export declare function pathExists(filePath: string): Promise<boolean>;
+/**
+ * Synchronous counterpart to `pathExists()`, with the same `fs.statSync()`
+ * semantics.
+ */
+export declare function pathExistsSync(filePath: string): boolean;
+//# sourceMappingURL=fs.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../src/fs.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOxD"}

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

@@ -0,0 +1,30 @@
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+/**
+ * Returns true when `fs.stat()` can stat the path.
+ *
+ * This follows stat semantics: broken symlinks return false, while symlinks to
+ * existing targets return true.
+ */
+export async function pathExists(filePath) {
+    try {
+        await fsp.stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Synchronous counterpart to `pathExists()`, with the same `fs.statSync()`
+ * semantics.
+ */
+export function pathExistsSync(filePath) {
+    try {
+        fs.statSync(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

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

@@ -0,0 +1,14 @@
+/**
+ * Creates each missing path component from `rootReal` down to `targetPath`,
+ * guarding every step. Returns the real (symlink-resolved) path of the final
+ * component so callers can guard/use that path directly instead of
+ * re-deriving it from the original, possibly-symlinked, lexical path.
+ */
+export declare function mkdirPathComponentsWithGuards(params: {
+    rootReal: string;
+    targetPath: string;
+    beforeComponent?: (componentPath: string) => Promise<void> | void;
+    mode?: number;
+    rejectSymlinks?: boolean;
+}): Promise<string>;
+//# sourceMappingURL=guarded-mkdir.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/guarded-mkdir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guarded-mkdir.d.ts","sourceRoot":"","sources":["../src/guarded-mkdir.ts"],"names":[],"mappings":"AA0BA;;;;;GAKG;AACH,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,GAAG,OAAO,CAAC,MAAM,CAAC,CAuDlB"}

package/node_modules/@openclaw/fs-safe/dist/guarded-mkdir.js

@@ -0,0 +1,87 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { isNotFoundPathError, isPathRelativeEscape } from "./path.js";
+import { directoryComponentNotDirectoryError } from "./root-errors.js";
+function isSameOrChildPath(candidate, parent) {
+    const parentPrefix = parent.endsWith(path.sep) ? parent : `${parent}${path.sep}`;
+    return candidate === parent || candidate.startsWith(parentPrefix);
+}
+async function realpathOrThrowNotFile(target) {
+    try {
+        return path.resolve(fsSync.realpathSync.native(target));
+    }
+    catch (error) {
+        if (isNotFoundPathError(error)) {
+            // A dangling symlink (or a component removed between lstat and
+            // realpath) is not a usable directory component.
+            throw directoryComponentNotDirectoryError(error instanceof Error ? error : undefined);
+        }
+        throw error;
+    }
+}
+/**
+ * Creates each missing path component from `rootReal` down to `targetPath`,
+ * guarding every step. Returns the real (symlink-resolved) path of the final
+ * component so callers can guard/use that path directly instead of
+ * re-deriving it from the original, possibly-symlinked, lexical path.
+ */
+export async function mkdirPathComponentsWithGuards(params) {
+    const root = path.resolve(params.rootReal);
+    const rootCanonical = path.resolve(fsSync.realpathSync.native(root));
+    const target = path.resolve(params.targetPath);
+    const relative = path.relative(root, target);
+    if (isPathRelativeEscape(relative)) {
+        throw new FsSafeError("outside-workspace", "directory is outside workspace root");
+    }
+    let current = root;
+    for (const part of relative.split(path.sep).filter(Boolean)) {
+        const next = path.join(current, part);
+        const parentGuard = await createAsyncDirectoryGuard(current);
+        await assertAsyncDirectoryGuard(parentGuard);
+        await params.beforeComponent?.(next);
+        try {
+            await fs.mkdir(next, { mode: params.mode });
+        }
+        catch (error) {
+            if (!error || typeof error !== "object" || !("code" in error) || error.code !== "EEXIST") {
+                throw error;
+            }
+        }
+        const stat = fsSync.lstatSync(next);
+        if ((params.rejectSymlinks && stat.isSymbolicLink()) || (!stat.isSymbolicLink() && !stat.isDirectory())) {
+            throw directoryComponentNotDirectoryError();
+        }
+        // Node's recursive mkdir follows symlinks in missing components. Build one
+        // segment at a time and realpath-check each segment before descending.
+        const nextReal = await realpathOrThrowNotFile(next);
+        if (!isSameOrChildPath(nextReal, rootCanonical)) {
+            throw new FsSafeError("outside-workspace", "directory escaped workspace root");
+        }
+        if (stat.isSymbolicLink()) {
+            // An existing path component may legitimately be a symlink to a real
+            // directory inside the root (e.g. a skill-bank layout). We already
+            // verified above that it resolves inside the root, so treat the
+            // resolved real path as the directory for the rest of this walk
+            // instead of rejecting it outright. Guard checks from here on operate
+            // on the real (non-symlink) path, preserving TOCTOU protection for
+            // every subsequent segment. Callers that need the final directory
+            // (e.g. to guard it themselves after this function returns) must use
+            // the returned resolved path, not their own lexical parent path.
+            const targetStat = fsSync.statSync(nextReal);
+            if (!targetStat.isDirectory()) {
+                throw directoryComponentNotDirectoryError();
+            }
+            await createAsyncDirectoryGuard(nextReal);
+            await assertAsyncDirectoryGuard(parentGuard);
+            current = nextReal;
+            continue;
+        }
+        await createAsyncDirectoryGuard(next);
+        await assertAsyncDirectoryGuard(parentGuard);
+        current = next;
+    }
+    return current;
+}