@openclaw/fs-safe 0.17.0 → 0.18.1

package/dist/guarded-mkdir.d.ts

@@ -1,6 +1,6 @@
 import { type RootBoundaryIdentity } from "./root-boundary.js";
 import { type MutationDirectoryObservation } from "./pinned-mutation-observation.js";
-import type { PinnedCreatedDirectoryReceipt, PinnedMutationAdmissionReceipt, PinnedMutationAuthorizationToken } from "./pinned-write.js";
+import type { PinnedCreatedDirectoryReceipt, PinnedMutationAdmissionReceipt, PinnedMutationAuthorizationToken } from "./pinned-write-types.js";
 /**
  * Creates each missing path component from `rootReal` down to `targetPath`,
  * guarding every step. Returns the real (symlink-resolved) path of the final
@@ -23,4 +23,3 @@ export declare function mkdirPathComponentsWithGuards(params: {
     retainedTargetPath?: string;
     rootIdentity?: RootBoundaryIdentity;
 }): Promise<string>;
-//# sourceMappingURL=guarded-mkdir.d.ts.map

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

@@ -1,7 +1,9 @@
-export { FsSafeError, categorizeFsSafeError, type FsSafeErrorCategory, type FsSafeErrorCode, type FsSafeErrorDetails, } from "./errors.js";
-export { DEFAULT_ROOT_MAX_BYTES, root, type DenyMutationPolicy, type HardlinkPolicy, type RenameIdentityPolicy, type OpenResult, type ReadResult, type Root, type RootAppendOptions, type RootCopyOptions, type RootCopySource, type RootCopyPublicationReceipt, type CopyCloneMode, type RootCreateJsonOptions, type RootCreateOptions, type RootCreateStreamOptions, type RootDefaults, type RootEntriesOptions, type RootMkdirOptions, type RootMoveOptions, type RootOpenOptions, type RootOpenWritableOptions, type RootOptions, type RootReadOptions, type RootRemoveOptions, type RootWriteJsonOptions, type RootWriteOptions, type RootWalkDataEntry, type RootWalkDataEntryKind, type RootWalkDirectoryErrorBehavior, type RootWalkEntry, type RootWalkEntryFilter, type RootWalkEntryFilterResult, type RootWalkEntryKind, type RootWalkLimitBehavior, type RootWalkOptions, type RootWalkSymlinkPolicy, type SymlinkPolicy, type MutationSymlinkPolicy, type WritableOpenMode, type WritableOpenResult, } from "./root.js";
-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
+export { FsSafeError, categorizeFsSafeError, } from "./errors.js";
+export type * from "./errors.js";
+export { DEFAULT_ROOT_MAX_BYTES, root, type Root, } from "./root.js";
+export type * from "./root-public-types.js";
+export { configureFsSafePython, configureFsSafeNative, getFsSafeNativeConfig, } from "./native-config.js";
+export type * from "./config.js";
+export { writeExternalFileWithinRoot, } from "./output.js";
+export type * from "./output.js";
+export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";

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/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