@openclaw/fs-safe 0.10.0 → 0.12.0

package/dist/guest-native-python.js

@@ -0,0 +1,135 @@
+export const GUEST_FILESYSTEM_CREATE_STAGING_PYTHON = [
+    "def create_staging_dir(parent_fd):",
+    "    # This helper guarantees descriptor-relative confinement and no-replace",
+    "    # publication, not content integrity against same-UID peers; they can",
+    "    # also rewrite the destination immediately after publication.",
+    "    prefix = '.openclaw-create-'",
+    "    for _ in range(128):",
+    "        candidate = prefix + secrets.token_hex(6)",
+    "        try:",
+    "            os.mkdir(candidate, 0o700, dir_fd=parent_fd)",
+    "        except FileExistsError:",
+    "            continue",
+    "        created_identity = entry_identity(os.lstat(candidate, dir_fd=parent_fd))",
+    "        staging_fd = None",
+    "        try:",
+    "            staging_fd = open_dir(candidate, dir_fd=parent_fd)",
+    "            if not same_identity(created_identity, os.fstat(staging_fd)):",
+    "                raise OSError(errno.ESTALE, 'create staging directory changed', candidate)",
+    "            return candidate, staging_fd",
+    "        except Exception:",
+    "            if staging_fd is not None:",
+    "                os.close(staging_fd)",
+    "            try:",
+    "                current = os.lstat(candidate, dir_fd=parent_fd)",
+    "                if same_identity(created_identity, current):",
+    "                    os.rmdir(candidate, dir_fd=parent_fd)",
+    "                    os.fsync(parent_fd)",
+    "            except FileNotFoundError:",
+    "                pass",
+    "            raise",
+    "    raise RuntimeError('failed to allocate sandbox create staging directory')",
+].join("\n");
+export const GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON = [
+    "def rename_no_replace(src_parent_fd, src_basename, dst_parent_fd, dst_basename):",
+    "    libc = ctypes.CDLL(None, use_errno=True)",
+    "    is_linux = sys.platform.startswith('linux')",
+    "    if is_linux:",
+    "        rename_fn = getattr(libc, 'renameat2', None)",
+    "        if rename_fn is None:",
+    "            os.link(",
+    "                src_basename,",
+    "                dst_basename,",
+    "                src_dir_fd=src_parent_fd,",
+    "                dst_dir_fd=dst_parent_fd,",
+    "                follow_symlinks=False,",
+    "            )",
+    "            return",
+    "        flags = 1  # RENAME_NOREPLACE",
+    "    elif sys.platform == 'darwin':",
+    "        rename_fn = getattr(libc, 'renameatx_np', None)",
+    "        flags = 0x00000004  # RENAME_EXCL",
+    "    else:",
+    "        rename_fn = None",
+    "        flags = 0",
+    "    if rename_fn is None:",
+    "        raise OSError(errno.ENOSYS, 'atomic no-replace rename is unavailable')",
+    "    rename_fn.argtypes = [ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_uint]",
+    "    rename_fn.restype = ctypes.c_int",
+    "    result = rename_fn(",
+    "        src_parent_fd,",
+    "        os.fsencode(src_basename),",
+    "        dst_parent_fd,",
+    "        os.fsencode(dst_basename),",
+    "        flags,",
+    "    )",
+    "    if result != 0:",
+    "        error_code = ctypes.get_errno()",
+    "        unsupported_codes = {errno.ENOSYS, errno.EINVAL, errno.ENOTSUP}",
+    "        if hasattr(errno, 'EOPNOTSUPP'):",
+    "            unsupported_codes.add(errno.EOPNOTSUPP)",
+    "        if is_linux and error_code in unsupported_codes:",
+    "            os.link(",
+    "                src_basename,",
+    "                dst_basename,",
+    "                src_dir_fd=src_parent_fd,",
+    "                dst_dir_fd=dst_parent_fd,",
+    "                follow_symlinks=False,",
+    "            )",
+    "            return",
+    "        raise OSError(error_code, os.strerror(error_code), dst_basename)",
+].join("\n");
+export const GUEST_FILESYSTEM_CREATE_EXCLUSIVE_PYTHON = [
+    "def create_exclusive(parent_fd, basename, stdin_buffer):",
+    "    staging_fd = None",
+    "    staging_name = None",
+    "    temp_fd = None",
+    "    temp_name = 'payload'",
+    "    temp_inode = None",
+    "    try:",
+    "        try:",
+    "            os.lstat(basename, dir_fd=parent_fd)",
+    "        except FileNotFoundError:",
+    "            pass",
+    "        else:",
+    "            raise FileExistsError(errno.EEXIST, os.strerror(errno.EEXIST), basename)",
+    "        staging_name, staging_fd = create_staging_dir(parent_fd)",
+    "        temp_fd = os.open(temp_name, WRITE_FLAGS, 0o600, dir_fd=staging_fd)",
+    "        while True:",
+    "            chunk = stdin_buffer.read(65536)",
+    "            if not chunk:",
+    "                break",
+    "            write_all(temp_fd, chunk)",
+    "        # exclusive create payload is durable before publication",
+    "        os.fsync(temp_fd)",
+    "        temp_inode = inode_identity(os.fstat(temp_fd))",
+    "        # Publish with a native atomic no-replace rename.",
+    "        rename_no_replace(staging_fd, temp_name, parent_fd, basename)",
+    "        target_stat = os.lstat(basename, dir_fd=parent_fd)",
+    "        if temp_inode != inode_identity(target_stat):",
+    "            raise OSError(errno.ESTALE, 'exclusive publication source changed', basename)",
+    "        os.fsync(parent_fd)",
+    "    finally:",
+    "        if temp_fd is not None:",
+    "            os.close(temp_fd)",
+    "        if staging_fd is not None:",
+    "            # Cleanup stays relative to the private pinned directory, so a",
+    "            # parent-path substitution cannot redirect payload deletion.",
+    "            try:",
+    "                os.unlink(temp_name, dir_fd=staging_fd)",
+    "            except FileNotFoundError:",
+    "                pass",
+    "            staging_identity = entry_identity(os.fstat(staging_fd))",
+    "            os.close(staging_fd)",
+    "            staging_removed = False",
+    "            if staging_name is not None:",
+    "                try:",
+    "                    current_staging = os.lstat(staging_name, dir_fd=parent_fd)",
+    "                    if same_identity(staging_identity, current_staging):",
+    "                        os.rmdir(staging_name, dir_fd=parent_fd)",
+    "                        staging_removed = True",
+    "                except FileNotFoundError:",
+    "                    pass",
+    "            if staging_removed:",
+    "                os.fsync(parent_fd)",
+].join("\n");

package/dist/guest.d.ts

@@ -0,0 +1,9 @@
+import { GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON } from "./guest-native-python.js";
+/** Exclusive create found an existing destination, including a lost publication race. */
+export declare const GUEST_FILESYSTEM_CREATE_EXISTS_EXIT_CODE = 17;
+/** Read found a missing parent or file after the admitted root was opened. */
+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/guest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guest.d.ts","sourceRoot":"","sources":["../src/guest.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,yCAAyC,EAC1C,MAAM,0BAA0B,CAAC;AAElC,yFAAyF;AACzF,eAAO,MAAM,wCAAwC,KAAK,CAAC;AAC3D,8EAA8E;AAC9E,eAAO,MAAM,yCAAyC,IAAI,CAAC;AAE3D,gGAAgG;AAChG,eAAO,MAAM,uBAAuB,QA2ZxB,CAAC;AAEb,OAAO,EAAE,yCAAyC,EAAE,CAAC"}

package/dist/guest.js

@@ -0,0 +1,421 @@
+// Adapted from OpenClaw's guest filesystem program. Copyright OpenClaw Foundation; MIT.
+import { GUEST_FILESYSTEM_DISPATCH_PYTHON } from "./guest-dispatch-python.js";
+import { GUEST_FILESYSTEM_CREATE_EXCLUSIVE_PYTHON, GUEST_FILESYSTEM_CREATE_STAGING_PYTHON, GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON, } from "./guest-native-python.js";
+/** Exclusive create found an existing destination, including a lost publication race. */
+export const GUEST_FILESYSTEM_CREATE_EXISTS_EXIT_CODE = 17;
+/** Read found a missing parent or file after the admitted root was opened. */
+export const GUEST_FILESYSTEM_READ_NOT_FOUND_EXIT_CODE = 2;
+/** Python 3 source for the descriptor-relative guest filesystem protocol. See docs/guest.md. */
+export const GUEST_FILESYSTEM_PYTHON = [
+    `SANDBOX_CREATE_EXISTS_EXIT_CODE = ${GUEST_FILESYSTEM_CREATE_EXISTS_EXIT_CODE}`,
+    `SANDBOX_READ_NOT_FOUND_EXIT_CODE = ${GUEST_FILESYSTEM_READ_NOT_FOUND_EXIT_CODE}`,
+    "import ctypes",
+    "import errno",
+    "import json",
+    "import os",
+    "import secrets",
+    "import stat",
+    "import sys",
+    "",
+    "operation = sys.argv[1]",
+    "",
+    "DIR_FLAGS = os.O_RDONLY",
+    "if hasattr(os, 'O_DIRECTORY'):",
+    "    DIR_FLAGS |= os.O_DIRECTORY",
+    "if hasattr(os, 'O_NOFOLLOW'):",
+    "    DIR_FLAGS |= os.O_NOFOLLOW",
+    "",
+    "READ_FLAGS = os.O_RDONLY",
+    "if hasattr(os, 'O_NOFOLLOW'):",
+    "    READ_FLAGS |= os.O_NOFOLLOW",
+    "if hasattr(os, 'O_NONBLOCK'):",
+    "    READ_FLAGS |= os.O_NONBLOCK",
+    "",
+    "WRITE_FLAGS = os.O_WRONLY | os.O_CREAT | os.O_EXCL",
+    "if hasattr(os, 'O_NOFOLLOW'):",
+    "    WRITE_FLAGS |= os.O_NOFOLLOW",
+    "",
+    "def split_relative(path_value):",
+    "    segments = []",
+    "    for segment in path_value.split('/'):",
+    "        if not segment or segment == '.':",
+    "            continue",
+    "        if segment == '..':",
+    "            raise OSError(errno.EPERM, 'path traversal is not allowed', segment)",
+    "        segments.append(segment)",
+    "    return segments",
+    "",
+    "def open_dir(path_value, dir_fd=None):",
+    "    return os.open(path_value, DIR_FLAGS, dir_fd=dir_fd)",
+    "",
+    "def walk_dir(root_fd, rel_path, mkdir_enabled):",
+    "    current_fd = os.dup(root_fd)",
+    "    try:",
+    "        for segment in split_relative(rel_path):",
+    "            try:",
+    "                next_fd = open_dir(segment, dir_fd=current_fd)",
+    "            except FileNotFoundError:",
+    "                if not mkdir_enabled:",
+    "                    raise",
+    "                os.mkdir(segment, 0o777, dir_fd=current_fd)",
+    "                next_fd = open_dir(segment, dir_fd=current_fd)",
+    "            os.close(current_fd)",
+    "            current_fd = next_fd",
+    "        return current_fd",
+    "    except Exception:",
+    "        os.close(current_fd)",
+    "        raise",
+    "",
+    "def create_temp_file(parent_fd):",
+    "    prefix = '.openclaw-write-'",
+    "    for _ in range(128):",
+    "        candidate = prefix + secrets.token_hex(6)",
+    "        try:",
+    "            fd = os.open(candidate, WRITE_FLAGS, 0o600, dir_fd=parent_fd)",
+    "            return candidate, fd",
+    "        except FileExistsError:",
+    "            continue",
+    "    raise RuntimeError('failed to allocate sandbox temp file')",
+    "",
+    "def create_temp_dir(parent_fd, mode):",
+    "    prefix = '.openclaw-move-'",
+    "    for _ in range(128):",
+    "        candidate = prefix + secrets.token_hex(6)",
+    "        try:",
+    "            os.mkdir(candidate, mode, dir_fd=parent_fd)",
+    "            return candidate",
+    "        except FileExistsError:",
+    "            continue",
+    "    raise RuntimeError('failed to allocate sandbox temp directory')",
+    "",
+    GUEST_FILESYSTEM_CREATE_STAGING_PYTHON,
+    "",
+    "def existing_regular_file_mode(parent_fd, basename):",
+    "    try:",
+    "        target_stat = os.lstat(basename, dir_fd=parent_fd)",
+    "    except FileNotFoundError:",
+    "        return None",
+    "    if stat.S_ISREG(target_stat.st_mode):",
+    "        return stat.S_IMODE(target_stat.st_mode)",
+    "    return None",
+    "",
+    "def write_all(file_fd, data):",
+    "    view = memoryview(data)",
+    "    while view:",
+    "        written = os.write(file_fd, view)",
+    "        if written <= 0:",
+    "            raise OSError(errno.EIO, 'failed to write copied file')",
+    "        view = view[written:]",
+    "",
+    GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON,
+    "",
+    "def copy_regular_file(src_parent_fd, src_basename, dst_parent_fd, dst_basename):",
+    "    src_fd = os.open(src_basename, READ_FLAGS, dir_fd=src_parent_fd)",
+    "    dst_fd = None",
+    "    destination_created = False",
+    "    copy_completed = False",
+    "    try:",
+    "        src_stat = os.fstat(src_fd)",
+    "        if not stat.S_ISREG(src_stat.st_mode):",
+    "            raise OSError(errno.EPERM, 'only regular files are allowed', src_basename)",
+    "        if src_stat.st_nlink > 1:",
+    "            raise OSError(errno.EPERM, 'hardlinked file is not allowed', src_basename)",
+    "        dst_fd = os.open(dst_basename, WRITE_FLAGS, stat.S_IMODE(src_stat.st_mode), dir_fd=dst_parent_fd)",
+    "        destination_created = True",
+    "        while True:",
+    "            chunk = os.read(src_fd, 65536)",
+    "            if not chunk:",
+    "                break",
+    "            write_all(dst_fd, chunk)",
+    "        try:",
+    "            os.fchmod(dst_fd, stat.S_IMODE(src_stat.st_mode))",
+    "        except AttributeError:",
+    "            pass",
+    "        os.fsync(dst_fd)",
+    "        copy_completed = True",
+    "        return entry_identity(src_stat)",
+    "    finally:",
+    "        if dst_fd is not None:",
+    "            os.close(dst_fd)",
+    "        if destination_created and not copy_completed:",
+    "            try:",
+    "                os.unlink(dst_basename, dir_fd=dst_parent_fd)",
+    "            except FileNotFoundError:",
+    "                pass",
+    "        os.close(src_fd)",
+    "",
+    "def copy_file_atomic(src_parent_fd, src_basename, dst_parent_fd, dst_basename):",
+    "    prefix = '.openclaw-copy-'",
+    "    temp_name = None",
+    "    try:",
+    "        for _ in range(128):",
+    "            candidate = prefix + secrets.token_hex(6)",
+    "            try:",
+    "                copy_regular_file(src_parent_fd, src_basename, dst_parent_fd, candidate)",
+    "                temp_name = candidate",
+    "                break",
+    "            except FileExistsError:",
+    "                continue",
+    "        if temp_name is None:",
+    "            raise RuntimeError('failed to allocate sandbox copy temp file')",
+    "        os.replace(temp_name, dst_basename, src_dir_fd=dst_parent_fd, dst_dir_fd=dst_parent_fd)",
+    "        temp_name = None",
+    "        os.fsync(dst_parent_fd)",
+    "    finally:",
+    "        if temp_name is not None:",
+    "            try:",
+    "                os.unlink(temp_name, dir_fd=dst_parent_fd)",
+    "            except FileNotFoundError:",
+    "                pass",
+    "",
+    "def write_atomic(parent_fd, basename, stdin_buffer):",
+    "    target_mode = existing_regular_file_mode(parent_fd, basename)",
+    "    temp_fd = None",
+    "    temp_name = None",
+    "    try:",
+    "        temp_name, temp_fd = create_temp_file(parent_fd)",
+    "        while True:",
+    "            chunk = stdin_buffer.read(65536)",
+    "            if not chunk:",
+    "                break",
+    "            write_all(temp_fd, chunk)",
+    "        if target_mode is not None:",
+    "            try:",
+    "                os.fchmod(temp_fd, target_mode)",
+    "            except AttributeError:",
+    "                pass",
+    "        os.fsync(temp_fd)",
+    "        os.close(temp_fd)",
+    "        temp_fd = None",
+    "        os.replace(temp_name, basename, src_dir_fd=parent_fd, dst_dir_fd=parent_fd)",
+    "        temp_name = None",
+    "        os.fsync(parent_fd)",
+    "    finally:",
+    "        if temp_fd is not None:",
+    "            os.close(temp_fd)",
+    "        if temp_name is not None:",
+    "            try:",
+    "                os.unlink(temp_name, dir_fd=parent_fd)",
+    "            except FileNotFoundError:",
+    "                pass",
+    "",
+    GUEST_FILESYSTEM_CREATE_EXCLUSIVE_PYTHON,
+    "",
+    "def read_file_impl(parent_fd, basename, max_bytes):",
+    "    file_fd = os.open(basename, READ_FLAGS, dir_fd=parent_fd)",
+    "    try:",
+    "        file_stat = os.fstat(file_fd)",
+    "        if not stat.S_ISREG(file_stat.st_mode):",
+    "            raise OSError(errno.EPERM, 'only regular files are allowed', basename)",
+    "        if file_stat.st_nlink > 1:",
+    "            raise OSError(errno.EPERM, 'hardlinked file is not allowed', basename)",
+    "        if max_bytes is not None and file_stat.st_size > max_bytes:",
+    "            raise OSError(errno.EFBIG, 'file exceeds bounded read limit', basename)",
+    "        bytes_read = 0",
+    "        while True:",
+    "            read_size = 65536 if max_bytes is None else min(65536, max_bytes - bytes_read + 1)",
+    "            chunk = os.read(file_fd, read_size)",
+    "            if not chunk:",
+    "                break",
+    "            bytes_read += len(chunk)",
+    "            if max_bytes is not None and bytes_read > max_bytes:",
+    "                raise OSError(errno.EFBIG, 'file exceeds bounded read limit', basename)",
+    "            write_all(1, chunk)",
+    "    finally:",
+    "        os.close(file_fd)",
+    "",
+    "def read_file(parent_fd, basename):",
+    "    read_file_impl(parent_fd, basename, None)",
+    "",
+    "def read_file_bounded(parent_fd, basename, max_bytes):",
+    "    if max_bytes < 0:",
+    "        raise OSError(errno.EINVAL, 'read limit must be non-negative', basename)",
+    "    read_file_impl(parent_fd, basename, max_bytes)",
+    "",
+    "def remove_tree(parent_fd, basename):",
+    "    entry_stat = os.lstat(basename, dir_fd=parent_fd)",
+    "    if not stat.S_ISDIR(entry_stat.st_mode) or stat.S_ISLNK(entry_stat.st_mode):",
+    "        os.unlink(basename, dir_fd=parent_fd)",
+    "        return",
+    "    dir_fd = open_dir(basename, dir_fd=parent_fd)",
+    "    try:",
+    "        for child in os.listdir(dir_fd):",
+    "            remove_tree(dir_fd, child)",
+    "    finally:",
+    "        os.close(dir_fd)",
+    "    os.rmdir(basename, dir_fd=parent_fd)",
+    "",
+    "def entry_identity(entry_stat):",
+    "    return (",
+    "        entry_stat.st_dev,",
+    "        entry_stat.st_ino,",
+    "        entry_stat.st_mode,",
+    "        entry_stat.st_size,",
+    "        getattr(entry_stat, 'st_mtime_ns', int(entry_stat.st_mtime * 1000000000)),",
+    "        getattr(entry_stat, 'st_ctime_ns', int(entry_stat.st_ctime * 1000000000)),",
+    "    )",
+    "",
+    "def inode_identity(entry_stat):",
+    "    return (entry_stat.st_dev, entry_stat.st_ino)",
+    "",
+    "def same_identity(expected, entry_stat):",
+    "    return expected == entry_identity(entry_stat)",
+    "",
+    "def source_changed_error(basename):",
+    "    return OSError(getattr(errno, 'ESTALE', errno.EIO), 'source changed during move fallback cleanup', basename)",
+    "",
+    "def copy_entry(src_parent_fd, src_basename, dst_parent_fd, dst_basename):",
+    "    src_stat = os.lstat(src_basename, dir_fd=src_parent_fd)",
+    "    if stat.S_ISDIR(src_stat.st_mode) and not stat.S_ISLNK(src_stat.st_mode):",
+    "        os.mkdir(dst_basename, stat.S_IMODE(src_stat.st_mode) or 0o755, dir_fd=dst_parent_fd)",
+    "        copied_children = []",
+    "        src_dir_fd = None",
+    "        dst_dir_fd = None",
+    "        try:",
+    "            src_dir_fd = open_dir(src_basename, dir_fd=src_parent_fd)",
+    "            src_stat = os.fstat(src_dir_fd)",
+    "            dst_dir_fd = open_dir(dst_basename, dir_fd=dst_parent_fd)",
+    "            for child in os.listdir(src_dir_fd):",
+    "                copied_children.append((child, copy_entry(src_dir_fd, child, dst_dir_fd, child)))",
+    "        except Exception:",
+    "            if dst_dir_fd is not None:",
+    "                os.close(dst_dir_fd)",
+    "                dst_dir_fd = None",
+    "            try:",
+    "                remove_tree(dst_parent_fd, dst_basename)",
+    "            except FileNotFoundError:",
+    "                pass",
+    "            raise",
+    "        finally:",
+    "            if src_dir_fd is not None:",
+    "                os.close(src_dir_fd)",
+    "            if dst_dir_fd is not None:",
+    "                os.close(dst_dir_fd)",
+    "        return ('dir', entry_identity(src_stat), copied_children)",
+    "    if stat.S_ISLNK(src_stat.st_mode):",
+    "        link_target = os.readlink(src_basename, dir_fd=src_parent_fd)",
+    "        os.symlink(link_target, dst_basename, dir_fd=dst_parent_fd)",
+    "        return ('leaf', entry_identity(src_stat), None)",
+    "    return ('leaf', copy_regular_file(src_parent_fd, src_basename, dst_parent_fd, dst_basename), None)",
+    "",
+    "def remove_copied_entry(parent_fd, basename, manifest):",
+    "    kind, expected_identity, children = manifest",
+    "    current_stat = os.lstat(basename, dir_fd=parent_fd)",
+    "    if not same_identity(expected_identity, current_stat):",
+    "        raise source_changed_error(basename)",
+    "    if kind != 'dir':",
+    "        os.unlink(basename, dir_fd=parent_fd)",
+    "        return",
+    "    dir_fd = open_dir(basename, dir_fd=parent_fd)",
+    "    try:",
+    "        for child, child_manifest in children:",
+    "            remove_copied_entry(dir_fd, child, child_manifest)",
+    "    finally:",
+    "        os.close(dir_fd)",
+    "    os.rmdir(basename, dir_fd=parent_fd)",
+    "",
+    "def move_entry(src_parent_fd, src_basename, dst_parent_fd, dst_basename):",
+    "    try:",
+    "        os.rename(src_basename, dst_basename, src_dir_fd=src_parent_fd, dst_dir_fd=dst_parent_fd)",
+    "        os.fsync(dst_parent_fd)",
+    "        os.fsync(src_parent_fd)",
+    "        return",
+    "    except OSError as err:",
+    "        if err.errno != errno.EXDEV:",
+    "            raise",
+    "    src_stat = os.lstat(src_basename, dir_fd=src_parent_fd)",
+    "    if stat.S_ISDIR(src_stat.st_mode) and not stat.S_ISLNK(src_stat.st_mode):",
+    "        temp_dir_name = create_temp_dir(dst_parent_fd, stat.S_IMODE(src_stat.st_mode) or 0o755)",
+    "        copied_children = []",
+    "        temp_dir_fd = None",
+    "        src_dir_fd = None",
+    "        try:",
+    "            temp_dir_fd = open_dir(temp_dir_name, dir_fd=dst_parent_fd)",
+    "            src_dir_fd = open_dir(src_basename, dir_fd=src_parent_fd)",
+    "            src_stat = os.fstat(src_dir_fd)",
+    "            for child in os.listdir(src_dir_fd):",
+    "                copied_children.append((child, copy_entry(src_dir_fd, child, temp_dir_fd, child)))",
+    "            os.close(src_dir_fd)",
+    "            src_dir_fd = None",
+    "            os.close(temp_dir_fd)",
+    "            temp_dir_fd = None",
+    "            os.rename(temp_dir_name, dst_basename, src_dir_fd=dst_parent_fd, dst_dir_fd=dst_parent_fd)",
+    "        except Exception:",
+    "            if src_dir_fd is not None:",
+    "                os.close(src_dir_fd)",
+    "            if temp_dir_fd is not None:",
+    "                os.close(temp_dir_fd)",
+    "            try:",
+    "                remove_tree(dst_parent_fd, temp_dir_name)",
+    "            except FileNotFoundError:",
+    "                pass",
+    "            raise",
+    "        remove_copied_entry(src_parent_fd, src_basename, ('dir', entry_identity(src_stat), copied_children))",
+    "        os.fsync(dst_parent_fd)",
+    "        os.fsync(src_parent_fd)",
+    "        return",
+    "    if stat.S_ISLNK(src_stat.st_mode):",
+    "        link_target = os.readlink(src_basename, dir_fd=src_parent_fd)",
+    "        temp_dir_name, temp_dir_fd = create_staging_dir(dst_parent_fd)",
+    "        try:",
+    "            os.symlink(link_target, 'link', dir_fd=temp_dir_fd)",
+    "            os.replace('link', dst_basename, src_dir_fd=temp_dir_fd, dst_dir_fd=dst_parent_fd)",
+    "        finally:",
+    "            try:",
+    "                try:",
+    "                    os.unlink('link', dir_fd=temp_dir_fd)",
+    "                except FileNotFoundError:",
+    "                    pass",
+    "            finally:",
+    "                os.close(temp_dir_fd)",
+    "            os.rmdir(temp_dir_name, dir_fd=dst_parent_fd)",
+    "        os.unlink(src_basename, dir_fd=src_parent_fd)",
+    "        os.fsync(dst_parent_fd)",
+    "        os.fsync(src_parent_fd)",
+    "        return",
+    "    src_fd = os.open(src_basename, READ_FLAGS, dir_fd=src_parent_fd)",
+    "    temp_fd = None",
+    "    temp_name = None",
+    "    try:",
+    "        src_file_stat = os.fstat(src_fd)",
+    "        if not stat.S_ISREG(src_file_stat.st_mode):",
+    "            raise OSError(errno.EPERM, 'only regular files are allowed', src_basename)",
+    "        if src_file_stat.st_nlink > 1:",
+    "            raise OSError(errno.EPERM, 'hardlinked file is not allowed', src_basename)",
+    "        temp_name, temp_fd = create_temp_file(dst_parent_fd)",
+    "        while True:",
+    "            chunk = os.read(src_fd, 65536)",
+    "            if not chunk:",
+    "                break",
+    "            write_all(temp_fd, chunk)",
+    "        try:",
+    "            os.fchmod(temp_fd, stat.S_IMODE(src_stat.st_mode))",
+    "        except AttributeError:",
+    "            pass",
+    "        os.fsync(temp_fd)",
+    "        os.close(temp_fd)",
+    "        temp_fd = None",
+    "        os.replace(temp_name, dst_basename, src_dir_fd=dst_parent_fd, dst_dir_fd=dst_parent_fd)",
+    "        temp_name = None",
+    "        os.unlink(src_basename, dir_fd=src_parent_fd)",
+    "        os.fsync(dst_parent_fd)",
+    "        os.fsync(src_parent_fd)",
+    "    finally:",
+    "        if temp_fd is not None:",
+    "            os.close(temp_fd)",
+    "        if temp_name is not None:",
+    "            try:",
+    "                os.unlink(temp_name, dir_fd=dst_parent_fd)",
+    "            except FileNotFoundError:",
+    "                pass",
+    "        os.close(src_fd)",
+    "",
+    "basename_indexes = (4, 7) if operation in ('copy', 'rename') else (4,) if operation in ('read', 'write', 'create', 'remove') else ()",
+    "for basename_index in basename_indexes:",
+    "    basename = sys.argv[basename_index]",
+    "    if not basename or basename in ('.', '..') or '/' in basename or '\\x00' in basename:",
+    "        raise OSError(errno.EINVAL, 'invalid basename', basename)",
+    "",
+    GUEST_FILESYSTEM_DISPATCH_PYTHON,
+].join("\n");
+export { GUEST_FILESYSTEM_RENAME_NO_REPLACE_PYTHON };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 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 RootDefaults, 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 { 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";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,IAAI,EACJ,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,0BAA0B,EAC/B,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,8BAA8B,EACnC,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,2BAA2B,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,IAAI,EACJ,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,IAAI,EACT,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,0BAA0B,EAC/B,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,8BAA8B,EACnC,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAC1B,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EACL,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,2BAA2B,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,KAAK,gBAAgB,GACtB,MAAM,kBAAkB,CAAC"}

package/dist/install-path.d.ts

@@ -1,5 +1,11 @@
 export declare function safeDirName(input: string): string;
+/** Legacy readable encoding; distinct IDs can share a result. Use V2 for untrusted IDs. */
 export declare function safePathSegmentHashed(input: string): string;
+/**
+ * Versioned install-ID encoding: every trimmed ID receives a domain-separated
+ * SHA-256 digest. Only surrounding whitespace is intentionally equivalent.
+ */
+export declare function safePathSegmentHashedV2(input: string): string;
 export declare function resolveSafeInstallDir(params: {
     baseDir: string;
     id: string;

package/dist/install-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install-path.d.ts","sourceRoot":"","sources":["../src/install-path.ts"],"names":[],"mappings":"AAKA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiB3D;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAe5D;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDhB"}
+{"version":3,"file":"install-path.d.ts","sourceRoot":"","sources":["../src/install-path.ts"],"names":[],"mappings":"AAMA,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAED,2FAA2F;AAC3F,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiB3D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO7D;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;CACtC,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAe5D;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAkDhB"}

package/dist/install-path.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import fsSync from "node:fs";
 import path from "node:path";
 import { isPathInside } from "./path.js";
+import { realpathSync } from "./realpath.js";
 export function safeDirName(input) {
     const trimmed = input.trim();
     if (!trimmed) {
@@ -9,6 +10,7 @@ export function safeDirName(input) {
     }
     return trimmed.replaceAll("/", "__").replaceAll("\\", "__");
 }
+/** Legacy readable encoding; distinct IDs can share a result. Use V2 for untrusted IDs. */
 export function safePathSegmentHashed(input) {
     const trimmed = input.trim();
     const base = trimmed
@@ -25,6 +27,18 @@ export function safePathSegmentHashed(input) {
     }
     return safe;
 }
+/**
+ * Versioned install-ID encoding: every trimmed ID receives a domain-separated
+ * SHA-256 digest. Only surrounding whitespace is intentionally equivalent.
+ */
+export function safePathSegmentHashedV2(input) {
+    const hash = createHash("sha256")
+        .update("@openclaw/fs-safe:install-path:v2\0", "utf8")
+        // UTF-16LE preserves every JavaScript code unit, including lone surrogates.
+        .update(input.trim(), "utf16le")
+        .digest("hex");
+    return `id-v2-${hash}`;
+}
 export function resolveSafeInstallDir(params) {
     const encodedName = (params.nameEncoder ?? safeDirName)(params.id);
     const targetDir = path.join(params.baseDir, encodedName);
@@ -55,7 +69,7 @@ export async function assertCanonicalPathWithinBase(params) {
     else if (!baseLstat.isDirectory()) {
         throw new Error(`Invalid ${params.boundaryLabel}: base directory must be a directory`);
     }
-    const baseRealPath = fsSync.realpathSync.native(baseDir);
+    const baseRealPath = realpathSync.native(baseDir);
     const validateDirectory = async (dirPath) => {
         const resolvedDirPath = path.resolve(dirPath);
         const dirLstat = fsSync.lstatSync(dirPath);
@@ -71,7 +85,7 @@ export async function assertCanonicalPathWithinBase(params) {
         else if (!dirLstat.isDirectory()) {
             throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
         }
-        const dirRealPath = fsSync.realpathSync.native(dirPath);
+        const dirRealPath = realpathSync.native(dirPath);
         if (!isPathInside(baseRealPath, dirRealPath)) {
             throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
         }