@openclaw/fs-safe 0.16.0 → 0.18.0

package/dist/guarded-mkdir.js

@@ -149,6 +149,7 @@ export async function mkdirPathComponentsWithGuards(params) {
         if (params.revalidateParentAfterBeforeComponent) {
             await assertAsyncDirectoryGuard(parentGuard);
         }
+        let shouldCreate = true;
         if (params.beforeCreateComponent) {
             let missing = false;
             try {
@@ -159,6 +160,7 @@ export async function mkdirPathComponentsWithGuards(params) {
                     throw error;
                 missing = true;
             }
+            shouldCreate = missing;
             if (missing) {
                 let prospectiveParent = retainedParentPath;
                 if (!prospectiveParent) {
@@ -177,36 +179,12 @@ export async function mkdirPathComponentsWithGuards(params) {
                     if (!params.synchronousAuthorizationIncludesFence)
                         inspectGuardCurrent(parentGuard);
                 }
-                params.assertBeforeMutation?.();
-                // Authority callbacks are an explicit freshness boundary. Recheck the
-                // exact parent synchronously so no callback-observed authority is
-                // carried into a pathname mkdir after the parent was swapped.
-                inspectGuardCurrent(parentGuard);
-                try {
-                    if (params.private) {
-                        await createDirectoryWithAdmission(next, {
-                            private: true,
-                            mode: params.mode,
-                            assertBeforeMutation: params.assertBeforeMutation,
-                        }, {
-                            expectedParentIdentity: {
-                                dev: parentGuard.stat.dev, ino: parentGuard.stat.ino, realPath: parentGuard.realPath,
-                            },
-                        });
-                    }
-                    else {
-                        await fs.mkdir(next, { mode: params.mode });
-                    }
-                    created = true;
-                }
-                catch (error) {
-                    if (!isDirectoryCollision(error))
-                        throw error;
-                }
             }
         }
-        else {
+        if (shouldCreate) {
             params.assertBeforeMutation?.();
+            // Both policy and ordinary mkdir must renew the parent after callbacks.
+            inspectGuardCurrent(parentGuard);
             try {
                 if (params.private) {
                     await createDirectoryWithAdmission(next, {
@@ -222,6 +200,7 @@ export async function mkdirPathComponentsWithGuards(params) {
                 else {
                     await fs.mkdir(next, { mode: params.mode });
                 }
+                created = true;
             }
             catch (error) {
                 if (!isDirectoryCollision(error))

package/dist/guarded-mutation.d.ts

@@ -13,21 +13,15 @@ export declare function guardedRename(params: {
     onRenamed?: () => void;
     from: string;
     to: string;
-    targetRoot?: string;
-    verifyAfter?: boolean;
 }): Promise<void>;
 export declare function guardedRenameSync(params: {
     from: string;
     to: string;
-    targetRoot?: string;
-    verifyAfter?: boolean;
 }): void;
 export declare function guardedRm(params: {
     target: string;
     assertBeforeMutation?: () => void;
     recursive?: boolean;
-    force?: boolean;
-    verifyAfter?: boolean;
 }): Promise<void>;
 export declare function guardedRmSync(params: {
     target: string;
@@ -36,4 +30,3 @@ export declare function guardedRmSync(params: {
     force?: boolean;
     verifyAfter?: boolean;
 }): void;
-//# sourceMappingURL=guarded-mutation.d.ts.map

package/dist/guarded-mutation.js

@@ -1,7 +1,7 @@
 import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard, createNearestExistingSyncDirectoryGuard, createSyncDirectoryGuard, } from "./directory-guard.js";
+import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard, createAsyncDirectoryGuard, createSyncDirectoryGuard, } from "./directory-guard.js";
 export async function withAsyncDirectoryGuards(guards, mutate, options = {}) {
     for (const guard of guards) {
         await assertAsyncDirectoryGuard(guard);
@@ -44,9 +44,7 @@ export function withSyncDirectoryGuards(guards, mutate, options = {}) {
 }
 export async function guardedRename(params) {
     const sourceGuard = await createAsyncDirectoryGuard(path.dirname(params.from));
-    const targetGuard = params.targetRoot
-        ? await createNearestExistingDirectoryGuard(params.targetRoot, path.dirname(params.to))
-        : await createAsyncDirectoryGuard(path.dirname(params.to));
+    const targetGuard = await createAsyncDirectoryGuard(path.dirname(params.to));
     await withAsyncDirectoryGuards([sourceGuard, targetGuard], async () => {
         if (params.onSourceInspected) {
             params.onSourceInspected(fsSync.lstatSync(params.from, { bigint: true }));
@@ -55,14 +53,12 @@ export async function guardedRename(params) {
         params.assertBeforeRename?.();
         await fs.rename(params.from, params.to);
         params.onRenamed?.();
-    }, { verifyAfter: params.verifyAfter });
+    });
 }
 export function guardedRenameSync(params) {
     const sourceGuard = createSyncDirectoryGuard(path.dirname(params.from));
-    const targetGuard = params.targetRoot
-        ? createNearestExistingSyncDirectoryGuard(params.targetRoot, path.dirname(params.to))
-        : createSyncDirectoryGuard(path.dirname(params.to));
-    withSyncDirectoryGuards([sourceGuard, targetGuard], () => fsSync.renameSync(params.from, params.to), { verifyAfter: params.verifyAfter });
+    const targetGuard = createSyncDirectoryGuard(path.dirname(params.to));
+    withSyncDirectoryGuards([sourceGuard, targetGuard], () => fsSync.renameSync(params.from, params.to));
 }
 export async function guardedRm(params) {
     const guard = await createAsyncDirectoryGuard(path.dirname(params.target));
@@ -70,9 +66,8 @@ export async function guardedRm(params) {
         params.assertBeforeMutation?.();
         await fs.rm(params.target, {
             ...(params.recursive !== undefined ? { recursive: params.recursive } : {}),
-            ...(params.force !== undefined ? { force: params.force } : {}),
         });
-    }, { verifyAfter: params.verifyAfter });
+    });
 }
 export function guardedRmSync(params) {
     const guard = createSyncDirectoryGuard(path.dirname(params.target));

package/dist/guest-dispatch-python.d.ts

@@ -1,2 +1 @@
 export declare const GUEST_FILESYSTEM_DISPATCH_PYTHON: string;
-//# sourceMappingURL=guest-dispatch-python.d.ts.map

package/dist/guest-dispatch-python.js

@@ -1,5 +1,5 @@
 export const GUEST_FILESYSTEM_DISPATCH_PYTHON = [
-    "if operation == 'copy':",
+    "if operation in ('copy', 'rename'):",
     "    src_root_fd = open_dir(sys.argv[2])",
     "    dst_root_fd = open_dir(sys.argv[5])",
     "    src_parent_fd = None",
@@ -7,7 +7,10 @@ export const GUEST_FILESYSTEM_DISPATCH_PYTHON = [
     "    try:",
     "        src_parent_fd = walk_dir(src_root_fd, sys.argv[3], False)",
     "        dst_parent_fd = walk_dir(dst_root_fd, sys.argv[6], sys.argv[8] == '1')",
-    "        copy_file_atomic(src_parent_fd, sys.argv[4], dst_parent_fd, sys.argv[7])",
+    "        if operation == 'copy':",
+    "            copy_file_atomic(src_parent_fd, sys.argv[4], dst_parent_fd, sys.argv[7])",
+    "        else:",
+    "            move_entry(src_parent_fd, sys.argv[4], dst_parent_fd, sys.argv[7])",
     "    finally:",
     "        if src_parent_fd is not None:",
     "            os.close(src_parent_fd)",
@@ -15,103 +18,51 @@ export const GUEST_FILESYSTEM_DISPATCH_PYTHON = [
     "            os.close(dst_parent_fd)",
     "        os.close(src_root_fd)",
     "        os.close(dst_root_fd)",
-    "elif operation == 'write':",
+    "elif operation in ('write', 'create', 'read', 'readdir', 'mkdirp', 'remove'):",
     "    root_fd = open_dir(sys.argv[2])",
     "    parent_fd = None",
     "    try:",
-    "        parent_fd = walk_dir(root_fd, sys.argv[3], sys.argv[5] == '1')",
-    "        write_atomic(parent_fd, sys.argv[4], sys.stdin.buffer)",
-    "    finally:",
-    "        if parent_fd is not None:",
-    "            os.close(parent_fd)",
-    "        os.close(root_fd)",
-    "elif operation == 'create':",
-    "    root_fd = open_dir(sys.argv[2])",
-    "    parent_fd = None",
-    "    try:",
-    "        parent_fd = walk_dir(root_fd, sys.argv[3], sys.argv[5] == '1')",
-    "        try:",
-    "            create_exclusive(parent_fd, sys.argv[4], sys.stdin.buffer)",
-    "        except FileExistsError:",
-    "            sys.exit(SANDBOX_CREATE_EXISTS_EXIT_CODE)",
-    "    finally:",
-    "        if parent_fd is not None:",
-    "            os.close(parent_fd)",
-    "        os.close(root_fd)",
-    "elif operation == 'read':",
-    "    root_fd = open_dir(sys.argv[2])",
-    "    parent_fd = None",
-    "    try:",
-    "        parent_fd = walk_dir(root_fd, sys.argv[3], False)",
-    "        if len(sys.argv) > 5:",
-    "            read_file_bounded(parent_fd, sys.argv[4], int(sys.argv[5]))",
-    "        else:",
-    "            read_file(parent_fd, sys.argv[4])",
-    "    except FileNotFoundError:",
-    "        sys.exit(SANDBOX_READ_NOT_FOUND_EXIT_CODE)",
-    "    finally:",
-    "        if parent_fd is not None:",
-    "            os.close(parent_fd)",
-    "        os.close(root_fd)",
-    "elif operation == 'readdir':",
-    "    root_fd = open_dir(sys.argv[2])",
-    "    target_fd = None",
-    "    try:",
-    "        target_fd = walk_dir(root_fd, sys.argv[3], False)",
-    "        with os.scandir(target_fd) as entries:",
-    "            print(json.dumps([{'name': entry.name, 'isDirectory': entry.is_dir(follow_symlinks=False), 'isFile': entry.is_file(follow_symlinks=False)} for entry in entries]))",
-    "    finally:",
-    "        if target_fd is not None:",
-    "            os.close(target_fd)",
-    "        os.close(root_fd)",
-    "elif operation == 'mkdirp':",
-    "    root_fd = open_dir(sys.argv[2])",
-    "    target_fd = None",
-    "    try:",
-    "        target_fd = walk_dir(root_fd, sys.argv[3], True)",
-    "        os.fsync(target_fd)",
-    "    finally:",
-    "        if target_fd is not None:",
-    "            os.close(target_fd)",
-    "        os.close(root_fd)",
-    "elif operation == 'remove':",
-    "    root_fd = open_dir(sys.argv[2])",
-    "    parent_fd = None",
-    "    try:",
-    "        parent_fd = walk_dir(root_fd, sys.argv[3], False)",
-    "        try:",
-    "            if sys.argv[5] == '1':",
-    "                remove_tree(parent_fd, sys.argv[4])",
+    "        mkdir_enabled = operation == 'mkdirp' or (operation in ('write', 'create') and sys.argv[5] == '1')",
+    "        parent_fd = walk_dir(root_fd, sys.argv[3], mkdir_enabled)",
+    "        if operation == 'write':",
+    "            write_atomic(parent_fd, sys.argv[4], sys.stdin.buffer)",
+    "        elif operation == 'create':",
+    "            try:",
+    "                create_exclusive(parent_fd, sys.argv[4], sys.stdin.buffer)",
+    "            except FileExistsError:",
+    "                sys.exit(SANDBOX_CREATE_EXISTS_EXIT_CODE)",
+    "        elif operation == 'read':",
+    "            if len(sys.argv) > 5:",
+    "                read_file_bounded(parent_fd, sys.argv[4], int(sys.argv[5]))",
     "            else:",
-    "                entry_stat = os.lstat(sys.argv[4], dir_fd=parent_fd)",
-    "                if stat.S_ISDIR(entry_stat.st_mode) and not stat.S_ISLNK(entry_stat.st_mode):",
-    "                    os.rmdir(sys.argv[4], dir_fd=parent_fd)",
-    "                else:",
-    "                    os.unlink(sys.argv[4], dir_fd=parent_fd)",
+    "                read_file(parent_fd, sys.argv[4])",
+    "        elif operation == 'readdir':",
+    "            with os.scandir(parent_fd) as entries:",
+    "                print(json.dumps([{'name': entry.name, 'isDirectory': entry.is_dir(follow_symlinks=False), 'isFile': entry.is_file(follow_symlinks=False)} for entry in entries]))",
+    "        elif operation == 'mkdirp':",
     "            os.fsync(parent_fd)",
-    "        except FileNotFoundError:",
-    "            if sys.argv[6] != '1':",
-    "                raise",
+    "        elif operation == 'remove':",
+    "            try:",
+    "                if sys.argv[5] == '1':",
+    "                    remove_tree(parent_fd, sys.argv[4])",
+    "                else:",
+    "                    entry_stat = os.lstat(sys.argv[4], dir_fd=parent_fd)",
+    "                    if stat.S_ISDIR(entry_stat.st_mode) and not stat.S_ISLNK(entry_stat.st_mode):",
+    "                        os.rmdir(sys.argv[4], dir_fd=parent_fd)",
+    "                    else:",
+    "                        os.unlink(sys.argv[4], dir_fd=parent_fd)",
+    "                os.fsync(parent_fd)",
+    "            except FileNotFoundError:",
+    "                if sys.argv[6] != '1':",
+    "                    raise",
+    "    except FileNotFoundError:",
+    "        if operation == 'read':",
+    "            sys.exit(SANDBOX_READ_NOT_FOUND_EXIT_CODE)",
+    "        raise",
     "    finally:",
     "        if parent_fd is not None:",
     "            os.close(parent_fd)",
     "        os.close(root_fd)",
-    "elif operation == 'rename':",
-    "    src_root_fd = open_dir(sys.argv[2])",
-    "    dst_root_fd = open_dir(sys.argv[5])",
-    "    src_parent_fd = None",
-    "    dst_parent_fd = None",
-    "    try:",
-    "        src_parent_fd = walk_dir(src_root_fd, sys.argv[3], False)",
-    "        dst_parent_fd = walk_dir(dst_root_fd, sys.argv[6], sys.argv[8] == '1')",
-    "        move_entry(src_parent_fd, sys.argv[4], dst_parent_fd, sys.argv[7])",
-    "    finally:",
-    "        if src_parent_fd is not None:",
-    "            os.close(src_parent_fd)",
-    "        if dst_parent_fd is not None:",
-    "            os.close(dst_parent_fd)",
-    "        os.close(src_root_fd)",
-    "        os.close(dst_root_fd)",
     "else:",
     "    raise RuntimeError('unknown sandbox mutation operation: ' + operation)",
 ].join("\n");

package/dist/guest-native-python.d.ts

@@ -1,4 +1,3 @@
 export declare const GUEST_FILESYSTEM_CREATE_STAGING_PYTHON: string;
 export declare const GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON: string;
 export declare const GUEST_FILESYSTEM_CREATE_EXCLUSIVE_PYTHON: string;
-//# sourceMappingURL=guest-native-python.d.ts.map

package/dist/guest.d.ts

@@ -6,4 +6,3 @@ export declare const GUEST_FILESYSTEM_READ_NOT_FOUND_EXIT_CODE = 2;
 /** Python 3 source for the descriptor-relative guest filesystem protocol. See docs/guest.md. */
 export declare const GUEST_FILESYSTEM_PYTHON: string;
 export { GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON };
-//# sourceMappingURL=guest.d.ts.map

package/dist/home-dir.d.ts

@@ -9,4 +9,3 @@ export declare function resolveHomeRelativePath(input: string, opts?: {
     env?: NodeJS.ProcessEnv;
     homedir?: () => string;
 }): string;
-//# sourceMappingURL=home-dir.d.ts.map

package/dist/index.d.ts

@@ -4,4 +4,3 @@ export type { ContainmentGuarantee } from "./containment.js";
 export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, type FsSafePythonConfig, type FsSafeNativeConfig, type FsSafeNativeMode, } from "./native-config.js";
 export { writeExternalFileWithinRoot, type ExternalFileWriteOptions, type ExternalFileWriteResult, } from "./output.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/install-path.d.ts

@@ -23,4 +23,3 @@ export declare function assertCanonicalPathWithinBase(params: {
     candidatePath: string;
     boundaryLabel: string;
 }): Promise<void>;
-//# sourceMappingURL=install-path.d.ts.map

package/dist/install-path.js

@@ -15,11 +15,8 @@ export function safeDirName(input) {
 export function safePathSegmentHashed(input) {
     const trimmed = input.trim();
     const base = trimmed
-        .replaceAll(/[\\/]/g, "-")
-        .replaceAll(/[^a-zA-Z0-9._-]/g, "-")
-        .replaceAll(/-+/g, "-")
-        .replaceAll(/^-+/g, "")
-        .replaceAll(/-+$/g, "");
+        .replaceAll(/[^a-zA-Z0-9._]+/g, "-")
+        .replaceAll(/^-|-$/g, "");
     const normalized = base.length > 0 ? base : "skill";
     const safe = normalized === "." || normalized === ".." ? "skill" : normalized;
     if (safe !== trimmed || safe.length > 60) {

package/dist/json-document-store.d.ts

@@ -35,4 +35,3 @@ export type JsonStoreAdapter<T> = {
     }): Promise<void>;
 };
 export declare function createJsonStore<T>(adapter: JsonStoreAdapter<T>, options?: JsonFileStoreOptions): JsonStore<T>;
-//# sourceMappingURL=json-document-store.d.ts.map

package/dist/json-durable-queue-directory.d.ts

@@ -1,2 +1,14 @@
+export declare function queueDirectories(queueDir: string, failedDir: string): Promise<{
+    queue: QueueDirectory;
+    failed: QueueDirectory;
+}>;
+declare class QueueDirectory {
+    private readonly dir;
+    private readonly root;
+    private readonly allowSymlinkBase;
+    constructor(dir: string);
+    ensure(): Promise<void>;
+    assert(allowMissing?: boolean): Promise<void>;
+}
 export declare function syncQueueDirectoryCreation(dir: string, validationBase: string): Promise<void>;
-//# sourceMappingURL=json-durable-queue-directory.d.ts.map
+export {};

package/dist/json-durable-queue-directory.js

@@ -1,7 +1,141 @@
+import fs from "node:fs";
 import path from "node:path";
 import { syncDirectory } from "./directory-durability.js";
 import { isPathRelativeEscape } from "./path.js";
 import { realpathSync } from "./realpath.js";
+import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+export async function queueDirectories(queueDir, failedDir) {
+    const queue = new QueueDirectory(queueDir);
+    return { queue, failed: new QueueDirectory(failedDir) };
+}
+class QueueDirectory {
+    dir;
+    root;
+    allowSymlinkBase;
+    constructor(dir) {
+        this.dir = dir;
+        this.root = path.parse(resolveQueueFilesystemPath(dir)).root;
+        this.allowSymlinkBase = process.platform === "darwin";
+    }
+    async ensure() {
+        await this.assert(true);
+        await fs.promises.mkdir(recursiveMkdirPath(this.dir), { recursive: true, mode: 0o700 });
+        await this.assert();
+        await chmodQueueDirectory(this.dir);
+        await syncQueueDirectoryCreation(this.dir, this.root);
+    }
+    async assert(allowMissing = false) {
+        const dir = this.dir;
+        let base = resolveQueueFilesystemPath(this.root);
+        let target = resolveQueueFilesystemPath(dir);
+        let current = base;
+        let baseStat = fs.lstatSync(base);
+        if (baseStat.isSymbolicLink() && this.allowSymlinkBase) {
+            const relative = path.relative(base, target);
+            if (relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+                throw new Error(`durable queue path is not a directory: ${dir}`);
+            }
+            base = realpathSync.native(base);
+            target = path.join(base, ...relative.split(path.sep).filter(Boolean));
+            current = base;
+            baseStat = fs.lstatSync(base);
+        }
+        if (baseStat.isSymbolicLink() || !baseStat.isDirectory()) {
+            throw new Error(`durable queue path is not a directory: ${dir}`);
+        }
+        const segments = path.relative(base, target).split(path.sep).filter(Boolean);
+        for (let index = 0; index < segments.length; index++) {
+            const segment = segments[index];
+            if (segment === undefined) {
+                continue;
+            }
+            current = path.join(current, segment);
+            let stat;
+            try {
+                stat = fs.lstatSync(current);
+            }
+            catch (error) {
+                if (allowMissing && error.code === "ENOENT") {
+                    return;
+                }
+                throw error;
+            }
+            if (stat.isSymbolicLink() || !stat.isDirectory()) {
+                if (stat.isSymbolicLink() && this.allowSymlinkBase) {
+                    if (await isDarwinSystemAlias(current, stat)) {
+                        current = realpathSync.native(current);
+                        continue;
+                    }
+                }
+                throw new Error(`durable queue path is not a directory: ${dir}`);
+            }
+        }
+    }
+}
+async function isDarwinSystemAlias(dir, stat) {
+    if (process.platform !== "darwin" || !stat.isSymbolicLink()) {
+        return false;
+    }
+    const resolved = path.resolve(dir);
+    if (resolved !== "/tmp" && resolved !== "/var") {
+        return false;
+    }
+    try {
+        return realpathSync.native(resolved) === `/private${resolved}`;
+    }
+    catch {
+        return false;
+    }
+}
+async function chmodQueueDirectory(dir) {
+    const noFollow = typeof fs.constants.O_NOFOLLOW === "number" && process.platform !== "win32"
+        ? fs.constants.O_NOFOLLOW
+        : 0;
+    const directoryFlag = typeof fs.constants.O_DIRECTORY === "number" && process.platform !== "win32"
+        ? fs.constants.O_DIRECTORY
+        : 0;
+    if (noFollow || directoryFlag) {
+        let handle;
+        try {
+            handle = await fs.promises.open(dir, fs.constants.O_RDONLY | noFollow | directoryFlag);
+            const stat = fs.fstatSync(handle.fd);
+            if (!stat.isDirectory()) {
+                throw new Error(`durable queue path is not a directory: ${dir}`);
+            }
+            try {
+                await handle.chmod(0o700);
+            }
+            catch {
+                // Best-effort on platforms that do not enforce POSIX modes.
+            }
+            return;
+        }
+        finally {
+            try {
+                await handle?.close();
+            }
+            catch {
+                // Best-effort cleanup after chmod/open failures.
+            }
+        }
+    }
+    const stat = fs.lstatSync(dir);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error(`durable queue path is not a directory: ${dir}`);
+    }
+    try {
+        await fs.promises.chmod(dir, 0o700);
+    }
+    catch {
+        // Best-effort on platforms that do not enforce POSIX modes.
+    }
+}
+function resolveQueueFilesystemPath(value) {
+    const resolved = resolvePathPreservingWindowsRoot(value);
+    assertNoWindowsPathAlias(resolved);
+    return resolved;
+}
 export async function syncQueueDirectoryCreation(dir, validationBase) {
     const baseReal = realpathSync.native(validationBase);
     const targetReal = realpathSync.native(dir);

package/dist/json-durable-queue-ownership.d.ts

@@ -21,4 +21,3 @@ export declare function moveDurableQueueEntryToFailed(params: {
     failedPath: string;
 }): Promise<void>;
 export declare function getErrorCode(error: unknown): string | null;
-//# sourceMappingURL=json-durable-queue-ownership.d.ts.map