@openclaw/openshell-sandbox 2026.9.2 → 2026.9.4

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

@@ -0,0 +1,391 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { readFileDescriptorBoundedSync, readFileHandleBounded } from "./bounded-read.js";
+import { normalizeMaxBytes } from "./byte-budget.js";
+import { assertNoUnsafeDeviceReadPath } from "./device-path.js";
+import { FsSafeError } from "./errors.js";
+import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
+import { isNotFoundPathError } from "./path.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { assertNoSymlinkParents, assertNoSymlinkParentsSync } from "./symlink-parents.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+import { isNonRegularWriteOpenError, isNonRegularWriteOpenErrorSync, resolveNonblockingWriteFlag, } from "./write-open-flags.js";
+export function resolveRegularFileAppendFlags(constants = fsSync.constants) {
+    const noFollow = constants.O_NOFOLLOW;
+    return (constants.O_CREAT |
+        constants.O_APPEND |
+        constants.O_WRONLY |
+        (typeof noFollow === "number" ? noFollow : 0) |
+        resolveNonblockingWriteFlag(constants));
+}
+function regularFileTooLargeError(filePath, maxBytes, cause) {
+    return new FsSafeError("too-large", `File exceeds ${maxBytes} bytes: ${filePath}`, { cause });
+}
+function translateBoundedReadOverflow(error, filePath, maxBytes) {
+    if (error instanceof FsSafeError && error.code === "too-large") {
+        throw regularFileTooLargeError(filePath, maxBytes, error);
+    }
+    throw error;
+}
+export async function statRegularFile(filePath) {
+    let stat;
+    try {
+        stat = fsSync.lstatSync(filePath);
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            return { missing: true };
+        }
+        throw err;
+    }
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new Error("path must be a regular file");
+    }
+    return { missing: false, stat };
+}
+export function statRegularFileSync(filePath) {
+    let stat;
+    try {
+        stat = fsSync.lstatSync(filePath);
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            return { missing: true };
+        }
+        throw err;
+    }
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new Error("path must be a regular file");
+    }
+    return { missing: false, stat };
+}
+export async function readRegularFile(params) {
+    const maxBytes = normalizeMaxBytes(params.maxBytes);
+    assertNoUnsafeDeviceReadPath(params.filePath);
+    const before = await inspectFileIdentity(async () => {
+        const stat = fsSync.lstatSync(params.filePath, { bigint: true });
+        assertRegularReadStat(stat, params.filePath, true);
+        return stat;
+    }).catch((error) => throwReadPreviewError(error, params.filePath));
+    if (maxBytes !== undefined && before.size > maxBytes) {
+        throw regularFileTooLargeError(params.filePath, maxBytes);
+    }
+    let handle;
+    try {
+        handle = await fs.open(params.filePath, resolveReadOpenFlags());
+    }
+    catch (err) {
+        if (isNotFoundPathError(err)) {
+            throw new FsSafeError("path-mismatch", `File changed during read: ${params.filePath}`);
+        }
+        throw err;
+    }
+    try {
+        const stat = fsSync.fstatSync(handle.fd);
+        const identity = await inspectFileIdentity(async () => {
+            const exact = fsSync.fstatSync(handle.fd, { bigint: true });
+            assertRegularReadStat(exact, params.filePath);
+            return exact;
+        }, before);
+        try {
+            await inspectFileIdentity(async () => {
+                const current = fsSync.lstatSync(params.filePath, { bigint: true });
+                assertRegularReadStat(current, params.filePath);
+                return current;
+            }, identity);
+        }
+        catch (err) {
+            if (isNotFoundPathError(err)) {
+                throw new FsSafeError("path-mismatch", `File changed during read: ${params.filePath}`);
+            }
+            throw err;
+        }
+        if (maxBytes !== undefined && stat.size > maxBytes) {
+            throw regularFileTooLargeError(params.filePath, maxBytes);
+        }
+        // With a byte cap, avoid readFile(): a raced file growth would allocate
+        // the oversized content before the post-read check could reject it.
+        let buffer;
+        try {
+            buffer =
+                maxBytes === undefined
+                    ? await handle.readFile()
+                    : await readFileHandleBounded(handle, maxBytes);
+        }
+        catch (error) {
+            if (maxBytes !== undefined) {
+                translateBoundedReadOverflow(error, params.filePath, maxBytes);
+            }
+            throw error;
+        }
+        return { buffer, stat };
+    }
+    finally {
+        await handle.close();
+    }
+}
+function throwReadPreviewError(error, filePath) {
+    if (isNotFoundPathError(error)) {
+        throw Object.assign(new Error(`File not found: ${filePath}`), { code: "ENOENT" });
+    }
+    throw error;
+}
+function assertRegularReadStat(stat, filePath, preview = false) {
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new Error(preview ? "path must be a regular file" : `File is not a regular file: ${filePath}`);
+    }
+}
+function readOpenedRegularFileSync(params) {
+    const stat = fsSync.fstatSync(params.fd);
+    const identity = inspectFileIdentitySync(() => {
+        const exact = fsSync.fstatSync(params.fd, { bigint: true });
+        assertRegularReadStat(exact, params.filePath);
+        return exact;
+    }, params.preOpenStat);
+    try {
+        inspectFileIdentitySync(() => {
+            const current = fsSync.lstatSync(params.filePath, { bigint: true });
+            assertRegularReadStat(current, params.filePath);
+            return current;
+        }, identity);
+    }
+    catch (error) {
+        if (isNotFoundPathError(error)) {
+            throw new FsSafeError("path-mismatch", `File changed during read: ${params.filePath}`);
+        }
+        throw error;
+    }
+    if (params.maxBytes !== undefined && stat.size > params.maxBytes) {
+        throw regularFileTooLargeError(params.filePath, params.maxBytes);
+    }
+    // Keep capped sync reads incremental for the same reason as async reads:
+    // readFileSync(fd) would buffer a raced oversized file before throwing.
+    let buffer;
+    try {
+        buffer =
+            params.maxBytes === undefined
+                ? fsSync.readFileSync(params.fd)
+                : readFileDescriptorBoundedSync(params.fd, params.maxBytes);
+    }
+    catch (error) {
+        if (params.maxBytes !== undefined) {
+            translateBoundedReadOverflow(error, params.filePath, params.maxBytes);
+        }
+        throw error;
+    }
+    return { buffer, stat };
+}
+export function readRegularFileSync(params) {
+    const maxBytes = normalizeMaxBytes(params.maxBytes);
+    assertNoUnsafeDeviceReadPath(params.filePath);
+    let before;
+    try {
+        before = inspectFileIdentitySync(() => {
+            const stat = fsSync.lstatSync(params.filePath, { bigint: true });
+            assertRegularReadStat(stat, params.filePath, true);
+            return stat;
+        });
+    }
+    catch (error) {
+        throwReadPreviewError(error, params.filePath);
+    }
+    if (maxBytes !== undefined && before.size > maxBytes) {
+        throw regularFileTooLargeError(params.filePath, maxBytes);
+    }
+    let fd;
+    try {
+        fd = fsSync.openSync(params.filePath, resolveReadOpenFlags());
+    }
+    catch (error) {
+        if (isNotFoundPathError(error)) {
+            throw new FsSafeError("path-mismatch", `File changed during read: ${params.filePath}`);
+        }
+        throw error;
+    }
+    try {
+        return readOpenedRegularFileSync({
+            fd,
+            filePath: params.filePath,
+            preOpenStat: before,
+            maxBytes,
+        });
+    }
+    finally {
+        fsSync.closeSync(fd);
+    }
+}
+function assertRegularAppendStat(stat, filePath) {
+    if (!stat.isFile()) {
+        throw new Error(`Refusing to append to non-file: ${filePath}`);
+    }
+    if (stat.nlink > 1n) {
+        throw new Error(`Refusing to append to hardlinked file: ${filePath}`);
+    }
+}
+function throwAppendIdentityError(error, filePath) {
+    if (isNotFoundPathError(error) ||
+        (error instanceof FsSafeError && error.code === "path-mismatch")) {
+        throw new Error(`Refusing to append after file changed: ${filePath}`, { cause: error });
+    }
+    throw error;
+}
+export async function appendRegularFile(options) {
+    if (options.rejectSymlinkParents === true) {
+        const resolvedDir = path.resolve(path.dirname(options.filePath));
+        await assertNoSymlinkParents({
+            rootDir: path.parse(resolvedDir).root,
+            targetPath: resolvedDir,
+            allowMissing: false,
+            allowRootChildSymlink: true,
+            requireDirectories: true,
+            messagePrefix: "Refusing to append under",
+        });
+    }
+    let preOpenStat;
+    try {
+        preOpenStat = await inspectFileIdentity(async () => {
+            const stat = fsSync.lstatSync(options.filePath, { bigint: true });
+            if (stat.isSymbolicLink()) {
+                throw new Error(`Refusing to append through symlink: ${options.filePath}`);
+            }
+            if (!stat.isFile()) {
+                throw new Error(`Refusing to append to non-file: ${options.filePath}`);
+            }
+            return stat;
+        });
+    }
+    catch (error) {
+        if (!isNotFoundPathError(error))
+            throw error;
+    }
+    const contentBytes = Buffer.isBuffer(options.content)
+        ? options.content.byteLength
+        : Buffer.byteLength(options.content, options.encoding ?? "utf8");
+    if (options.maxFileBytes !== undefined &&
+        Number(preOpenStat?.size ?? 0n) + contentBytes > options.maxFileBytes) {
+        return;
+    }
+    await getFsSafeTestHooks()?.beforeRegularFileAppendOpen?.(options.filePath);
+    const flags = resolveRegularFileAppendFlags();
+    let handle;
+    try {
+        handle = await fs.open(options.filePath, flags, options.mode ?? 0o600);
+    }
+    catch (error) {
+        if (await isNonRegularWriteOpenError(error, options.filePath, flags)) {
+            throw new Error(`Refusing to append to non-file: ${options.filePath}`);
+        }
+        throw error;
+    }
+    try {
+        let identity;
+        try {
+            identity = await inspectFileIdentity(async () => {
+                const stat = fsSync.fstatSync(handle.fd, { bigint: true });
+                assertRegularAppendStat(stat, options.filePath);
+                return stat;
+            }, preOpenStat);
+            await inspectFileIdentity(async () => {
+                const current = fsSync.lstatSync(options.filePath, { bigint: true });
+                assertRegularAppendStat(current, options.filePath);
+                return current;
+            }, identity);
+        }
+        catch (error) {
+            throwAppendIdentityError(error, options.filePath);
+        }
+        if (options.maxFileBytes !== undefined &&
+            Number(identity.size) + contentBytes > options.maxFileBytes) {
+            return;
+        }
+        const mode = options.mode ?? 0o600;
+        // Tighten before writing; restore explicit special bits only after content is complete.
+        await handle.chmod(mode);
+        await handle.appendFile(options.content, options.encoding ?? "utf8");
+        if (mode & 0o7000)
+            await handle.chmod(mode);
+    }
+    finally {
+        await handle.close();
+    }
+}
+export function appendRegularFileSync(options) {
+    if (options.rejectSymlinkParents === true) {
+        const resolvedDir = path.resolve(path.dirname(options.filePath));
+        assertNoSymlinkParentsSync({
+            rootDir: path.parse(resolvedDir).root,
+            targetPath: resolvedDir,
+            allowMissing: false,
+            allowRootChildSymlink: true,
+            requireDirectories: true,
+            messagePrefix: "Refusing to append under",
+        });
+    }
+    let preOpenStat;
+    try {
+        preOpenStat = inspectFileIdentitySync(() => {
+            const stat = fsSync.lstatSync(options.filePath, { bigint: true });
+            if (stat.isSymbolicLink()) {
+                throw new Error(`Refusing to append through symlink: ${options.filePath}`);
+            }
+            if (!stat.isFile()) {
+                throw new Error(`Refusing to append to non-file: ${options.filePath}`);
+            }
+            return stat;
+        });
+    }
+    catch (error) {
+        if (!isNotFoundPathError(error))
+            throw error;
+    }
+    const contentBuffer = typeof options.content === "string"
+        ? Buffer.from(options.content, options.encoding ?? "utf8")
+        : Buffer.from(options.content);
+    if (options.maxFileBytes !== undefined &&
+        Number(preOpenStat?.size ?? 0n) + contentBuffer.byteLength > options.maxFileBytes) {
+        return;
+    }
+    getFsSafeTestHooks()?.beforeRegularFileAppendOpenSync?.(options.filePath);
+    const flags = resolveRegularFileAppendFlags();
+    let fd;
+    try {
+        fd = fsSync.openSync(options.filePath, flags, options.mode ?? 0o600);
+    }
+    catch (error) {
+        if (isNonRegularWriteOpenErrorSync(error, options.filePath, flags)) {
+            throw new Error(`Refusing to append to non-file: ${options.filePath}`);
+        }
+        throw error;
+    }
+    try {
+        let identity;
+        try {
+            identity = inspectFileIdentitySync(() => {
+                const stat = fsSync.fstatSync(fd, { bigint: true });
+                assertRegularAppendStat(stat, options.filePath);
+                return stat;
+            }, preOpenStat);
+            inspectFileIdentitySync(() => {
+                const current = fsSync.lstatSync(options.filePath, { bigint: true });
+                assertRegularAppendStat(current, options.filePath);
+                return current;
+            }, identity);
+        }
+        catch (error) {
+            throwAppendIdentityError(error, options.filePath);
+        }
+        if (options.maxFileBytes !== undefined &&
+            Number(identity.size) + contentBuffer.byteLength > options.maxFileBytes) {
+            return;
+        }
+        const mode = options.mode ?? 0o600;
+        fsSync.fchmodSync(fd, mode);
+        fsSync.appendFileSync(fd, contentBuffer);
+        if (mode & 0o7000)
+            fsSync.fchmodSync(fd, mode);
+    }
+    finally {
+        fsSync.closeSync(fd);
+    }
+}

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

@@ -0,0 +1,7 @@
+export type ReplaceDirectoryAtomicOptions = {
+    stagedDir: string;
+    targetDir: string;
+    backupPrefix?: string;
+};
+export declare function replaceDirectoryAtomic(options: ReplaceDirectoryAtomicOptions): Promise<void>;
+//# sourceMappingURL=replace-directory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"replace-directory.d.ts","sourceRoot":"","sources":["../src/replace-directory.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,IAAI,CAAC,CAKf"}

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

@@ -0,0 +1,42 @@
+import { randomUUID } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { guardedRename, guardedRm } from "./guarded-mutation.js";
+import { assertSafePathPrefix } from "./safe-path-segment.js";
+import { serializePathWrite } from "./write-queue.js";
+export async function replaceDirectoryAtomic(options) {
+    const targetDir = path.resolve(options.targetDir);
+    await serializePathWrite(targetDir, async () => {
+        await replaceDirectoryAtomicUnserialized(options, targetDir);
+    });
+}
+async function replaceDirectoryAtomicUnserialized(options, targetDir) {
+    const stagedDir = path.resolve(options.stagedDir);
+    const parentDir = path.dirname(targetDir);
+    const backupPrefix = assertSafePathPrefix(options.backupPrefix ?? ".fs-safe-dir-backup-", { label: "atomic directory backup prefix" });
+    const backupDir = path.join(parentDir, `${backupPrefix}${process.pid}-${randomUUID()}`);
+    let backupCreated = false;
+    await fs.mkdir(parentDir, { recursive: true });
+    try {
+        await guardedRename({ from: targetDir, to: backupDir });
+        backupCreated = true;
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            throw err;
+        }
+    }
+    try {
+        await guardedRename({ from: stagedDir, to: targetDir });
+    }
+    catch (err) {
+        if (backupCreated) {
+            await guardedRename({ from: backupDir, to: targetDir }).catch(() => undefined);
+            backupCreated = false;
+        }
+        throw err;
+    }
+    if (backupCreated) {
+        await guardedRm({ target: backupDir, recursive: true, force: true, verifyAfter: false });
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/replace-file-copy-fallback.d.ts

@@ -0,0 +1,39 @@
+import syncFs, { type BigIntStats } from "node:fs";
+export type ReplaceFileDestinationHardlinkPolicy = "reject";
+export type ReplaceFileCopyFallbackRestorePolicy = "restore-original" | "none";
+export type ReplaceFileAtomicRestoreCleanup = "restored" | "restore-failed";
+export type ReplaceFileAtomicRestoreFailureDetails = {
+    cleanup: ReplaceFileAtomicRestoreCleanup;
+};
+type AsyncFallbackFs = {
+    lstat: typeof import("node:fs/promises").lstat;
+    open: typeof import("node:fs/promises").open;
+    rm: typeof import("node:fs/promises").rm;
+    unlink: typeof import("node:fs/promises").unlink;
+};
+type SyncFallbackFs = Pick<typeof syncFs, "closeSync" | "fstatSync" | "fsyncSync" | "ftruncateSync" | "lstatSync" | "openSync" | "readSync" | "rmSync" | "unlinkSync" | "writeSync">;
+export declare function assertDestinationHardlinkPolicy(fsModule: AsyncFallbackFs, dest: string, policy?: ReplaceFileDestinationHardlinkPolicy): Promise<void>;
+export declare function assertDestinationHardlinkPolicySync(fsModule: SyncFallbackFs, dest: string, policy?: ReplaceFileDestinationHardlinkPolicy): void;
+export declare function copyFallbackReplace(params: {
+    fsModule: AsyncFallbackFs;
+    src: string;
+    dest: string;
+    destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
+    restore: ReplaceFileCopyFallbackRestorePolicy;
+    maxRestoreBytes?: number;
+    expectedSourceIdentity?: BigIntStats;
+    sync: boolean;
+}): Promise<void>;
+export declare function copyFallbackReplaceSync(params: {
+    fsModule: SyncFallbackFs;
+    src: string;
+    dest: string;
+    destinationHardlinks?: ReplaceFileDestinationHardlinkPolicy;
+    restore: ReplaceFileCopyFallbackRestorePolicy;
+    maxRestoreBytes?: number;
+    expectedSourceIdentity?: BigIntStats;
+    fchmodSync?: (fd: number, mode: number) => void;
+    sync: boolean;
+}): void;
+export {};
+//# sourceMappingURL=replace-file-copy-fallback.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/replace-file-copy-fallback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replace-file-copy-fallback.d.ts","sourceRoot":"","sources":["../src/replace-file-copy-fallback.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,EAAE,EAAE,KAAK,WAAW,EAAc,MAAM,SAAS,CAAC;AAO/D,MAAM,MAAM,oCAAoC,GAAG,QAAQ,CAAC;AAC5D,MAAM,MAAM,oCAAoC,GAAG,kBAAkB,GAAG,MAAM,CAAC;AAC/E,MAAM,MAAM,+BAA+B,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAC5E,MAAM,MAAM,sCAAsC,GAAG;IACnD,OAAO,EAAE,+BAA+B,CAAC;CAC1C,CAAC;AAEF,KAAK,eAAe,GAAG;IACrB,KAAK,EAAE,cAAc,kBAAkB,EAAE,KAAK,CAAC;IAC/C,IAAI,EAAE,cAAc,kBAAkB,EAAE,IAAI,CAAC;IAC7C,EAAE,EAAE,cAAc,kBAAkB,EAAE,EAAE,CAAC;IACzC,MAAM,EAAE,cAAc,kBAAkB,EAAE,MAAM,CAAC;CAClD,CAAC;AAEF,KAAK,cAAc,GAAG,IAAI,CACxB,OAAO,MAAM,EACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,eAAe,GACf,WAAW,GACX,UAAU,GACV,UAAU,GACV,QAAQ,GACR,YAAY,GACZ,WAAW,CACd,CAAC;AAuFF,wBAAsB,+BAA+B,CACnD,QAAQ,EAAE,eAAe,EACzB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAqBf;AAED,wBAAgB,mCAAmC,CACjD,QAAQ,EAAE,cAAc,EACxB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,oCAAoC,GAC5C,IAAI,CAwBN;AAmID,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,QAAQ,EAAE,eAAe,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,OAAO,EAAE,oCAAoC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,WAAW,CAAC;IACrC,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,IAAI,CAAC,CAwDhB;AAED,wBAAgB,uBAAuB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,cAAc,CAAC;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,oCAAoC,CAAC;IAC5D,OAAO,EAAE,oCAAoC,CAAC;IAC9C,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sBAAsB,CAAC,EAAE,WAAW,CAAC;IACrC,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,IAAI,CAkEP"}