@openclaw/fs-safe 0.10.0 → 0.11.0

package/dist/file-store.js

@@ -5,35 +5,19 @@ import { normalizeMaxBytes } from "./byte-budget.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { FsSafeError } from "./errors.js";
 import { assertFileStoreMaxBytes } from "./file-store-limit.js";
+import { assertRelativePath, resolveStorePath } from "./file-store-path.js";
 import { pruneExpiredStoreEntries } from "./file-store-prune.js";
 import { ensureParentInRoot, openPrivateStoreLockRoot, openWritableStoreRoot, writeStreamToTempSource, } from "./file-store-boundary.js";
 import { writeFileSyncAtomic } from "./file-store-sync-write.js";
 import { createJsonStore } from "./json-document-store.js";
 import { stringifyJsonDocument } from "./json-stringify.js";
-import { isNotFoundPathError, resolveSafeRelativePath, splitSafeRelativePath } from "./path.js";
+import { isNotFoundPathError } from "./path.js";
 import { throwFsSafeReadError } from "./root-errors.js";
 import { root } from "./root.js";
 import { DEFAULT_ROOT_MAX_BYTES } from "./root-impl.js";
 import { readRegularFile } from "./regular-file.js";
 import { matchRootFileOpenFailure, openRootFileSync } from "./root-file.js";
 import { writeSecretFileAtomic } from "./secret-file.js";
-function assertRelativePath(relativePath) {
-    const raw = relativePath.trim();
-    if (!raw || raw !== relativePath) {
-        throw new FsSafeError("invalid-path", "store key must be non-empty and unpadded");
-    }
-    const segments = splitSafeRelativePath(raw);
-    if (segments.length === 0 ||
-        segments.join("/") !== raw ||
-        raw.normalize("NFC") !== raw ||
-        segments.some((segment) => /[ .]$/u.test(segment))) {
-        throw new FsSafeError("invalid-path", "store key must use one canonical relative spelling");
-    }
-    return raw;
-}
-function resolveStorePath(rootDir, relativePath) {
-    return resolveSafeRelativePath(rootDir, assertRelativePath(relativePath));
-}
 function isNotFound(error) {
     return error instanceof FsSafeError ? error.code === "not-found" : isNotFoundPathError(error);
 }

package/dist/filename.d.ts.map

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

package/dist/filename.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { WINDOWS_RESERVED_DEVICE_NAMES } from "./device-path.js";
+import { maxNormalizedUtf8Bytes } from "./unicode-path.js";
 const INVALID_FILE_NAME_CHARACTERS = /[\u0000-\u001f\u007f-\u009f<>:"/\\|?*]/g;
 function trimWindowsIgnoredSuffix(value) {
     let end = value.length;
@@ -24,7 +25,7 @@ function suffixWindowsReservedDeviceName(fileName) {
 }
 const PORTABLE_FILE_NAME_BYTES = 255;
 function normalizedFileNameBytes(value) {
-    return Math.max(Buffer.byteLength(value.normalize("NFC"), "utf8"), Buffer.byteLength(value.normalize("NFD"), "utf8"));
+    return maxNormalizedUtf8Bytes(value, true);
 }
 /** Keeps short names exact and trims only the filename tail of a composite temp name. */
 export function fitFileNameToPortableComponent(params) {

package/dist/guarded-mkdir.d.ts.map

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

package/dist/guarded-mkdir.js

@@ -5,13 +5,14 @@ import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./director
 import { FsSafeError } from "./errors.js";
 import { isNotFoundPathError, isPathRelativeEscape } from "./path.js";
 import { directoryComponentNotDirectoryError } from "./root-errors.js";
+import { realpathSync } from "./realpath.js";
 function isSameOrChildPath(candidate, parent) {
     const parentPrefix = parent.endsWith(path.sep) ? parent : `${parent}${path.sep}`;
     return candidate === parent || candidate.startsWith(parentPrefix);
 }
 async function realpathOrThrowNotFile(target) {
     try {
-        return path.resolve(fsSync.realpathSync.native(target));
+        return path.resolve(realpathSync.native(target));
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
@@ -30,7 +31,7 @@ async function realpathOrThrowNotFile(target) {
  */
 export async function mkdirPathComponentsWithGuards(params) {
     const root = path.resolve(params.rootReal);
-    const rootCanonical = path.resolve(fsSync.realpathSync.native(root));
+    const rootCanonical = path.resolve(realpathSync.native(root));
     const target = path.resolve(params.targetPath);
     const relative = path.relative(root, target);
     if (isPathRelativeEscape(relative)) {

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"guest-dispatch-python.d.ts","sourceRoot":"","sources":["../src/guest-dispatch-python.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,gCAAgC,QAoHjC,CAAC"}

package/dist/guest-dispatch-python.js

@@ -0,0 +1,117 @@
+export const GUEST_FILESYSTEM_DISPATCH_PYTHON = [
+    "if operation == 'copy':",
+    "    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')",
+    "        copy_file_atomic(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)",
+    "elif operation == 'write':",
+    "    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)} 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])",
+    "            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",
+    "    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

@@ -0,0 +1,4 @@
+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-native-python.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guest-native-python.d.ts","sourceRoot":"","sources":["../src/guest-native-python.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sCAAsC,QA+BvC,CAAC;AAEb,eAAO,MAAM,yCAAyC,QAgD1C,CAAC;AAEb,eAAO,MAAM,wCAAwC,QAqDzC,CAAC"}

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,QAmZxB,CAAC;AAEb,OAAO,EAAE,yCAAyC,EAAE,CAAC"}