@openclaw/fs-safe 0.18.2 → 0.20.0

package/docs/testing.md

@@ -1,5 +1,33 @@
 # Testing
 
+## Linux openat2 fallback
+
+Build the host addon and package first. The test hook is cached with the native
+capability probe; set it before starting the process, rather than changing it
+between tests in one process:
+
+```bash
+pnpm native:build
+pnpm build
+FS_SAFE_TEST_NO_OPENAT2=1 FS_SAFE_NATIVE_MODE=require pnpm test test/linux-openat2-fallback.test.ts test/root-move-noreplace.test.ts test/root-move-native-integration.test.ts test/native-write-containment.test.ts
+```
+
+On Linux, the seccomp harness also exercises the real syscall failure without
+the environment hook. It needs a C compiler and permission to install an
+unprivileged seccomp filter; it affects only its child process:
+
+```bash
+cc test/fixtures/deny-openat2.c -o /tmp/fs-safe-deny-openat2
+/tmp/fs-safe-deny-openat2 ENOSYS node test/fixtures/linux-openat2-fallback.mjs "$PWD/native/fs-safe-native.linux-x64-gnu.node"
+/tmp/fs-safe-deny-openat2 EPERM node test/fixtures/linux-openat2-fallback.mjs "$PWD/native/fs-safe-native.linux-x64-gnu.node"
+```
+
+Use the matching native artifact filename on other Linux architectures/libcs.
+The fixture proves nested moves, collisions, read/write, traversal, symlink and
+hardlink rejection, cached selection, and `helper-unavailable` for strict
+bounded cleanup. Bounded-cleanup success tests require real `openat2`; run the
+full suite with the environment hook unset.
+
 `@openclaw/fs-safe/test-hooks` exposes test-only injection points. Registration
 is allowed only when `process.env.NODE_ENV === "test"` or
 `process.env.VITEST === "true"`; registering a non-empty hook set elsewhere

package/docs/walk.md

@@ -113,6 +113,18 @@ typed `FsSafeError("too-large")` instead.
 
 For followed symlinks, both `kind` and `size` describe the resolved target.
 
+The caller's starting path retains Root home shorthand: `~` and `~/dir` expand
+the home directory when iteration starts and must resolve inside the Root.
+Home-started walks report actual Root-relative paths, such as `home/dir/file`,
+rather than `~/dir/file`. Use `./~/dir` to start at a literal `~` directory.
+An alias within a home-started path is reported under its admitted canonical
+target; ordinary non-home starting aliases retain their caller-supplied spelling.
+
+Entry names remain literal filesystem data, including a directory named `~`
+and its descendants. To reuse an entry path in another Root method without
+home-directory expansion, prefix it with `./`, as in
+`capability.open("./" + entry.relativePath)`.
+
 The default `order: "sorted"` visits each directory's names in lexicographic
 order before descending depth first. It reads and sorts all names in each
 visited directory. With `maxEntries`, it prepares small metadata batches capped

package/docs/writing.md

@@ -211,6 +211,11 @@ can establish them; native disposal can retain them inside a `SuppressedError`
 cause. Preserve those details when handling errors: a rejection can follow
 complete publication, and an indeterminate link or native rename must preserve names for
 recovery. A cleanup or close failure also retains the original operation failure.
+The JavaScript fallback checks the destination again immediately before attempting
+publication. A collision observed there leaves publication unattempted and cleans
+the owned stage. A later collision or other error from the link call remains
+indeterminate, including `EEXIST`; the error code alone does not prove that the
+filesystem left both names unchanged.
 No later verification, mode, or synchronization failure authorizes deleting an
 already published complete destination. See [receipt meanings](staged-file.md).
 
@@ -301,6 +306,12 @@ type RootWriteJsonOptions = RootWriteOptions & {
 
 Open in append mode, write, sync the file handle, and close. Honors `mkdir` for the parent directory and syncs the parent directory when the append creates the file. `durable: false` skips both syncs. Pass `prependNewlineIfNeeded: true` to insert a `\n` if the file does not already end in one.
 
+`mode` selects the creation mode, defaulting to `0o600` when neither the call nor
+the Root supplies it. On POSIX, the process umask can further restrict that mode;
+for example, `mode: 0o640` with umask `0o077` creates a `0o600` file. Existing
+files are not chmodded, even when an explicit `mode` is supplied. Empty appends
+use the same creation rules.
+
 ```ts
 await fs.append("logs/today.log", `[${ts}] ${line}\n`);
 await fs.append("notes/scratch.md", "* new bullet", { prependNewlineIfNeeded: true });
@@ -348,6 +359,11 @@ replacing rename. After dispatch it rechecks both parent identities, so a
 post-operation rejection can mean the no-replace rename completed. Directory
 moves continue to require `overwrite: true`.
 
+Linux without `openat2` uses the [guarded native parent walk](native.md#linux-without-openat2).
+The move still uses `renameat2(RENAME_NOREPLACE)` and preserves collisions;
+parent resolution reports the documented `best-effort` containment class.
+Disabling the addon still makes no-clobber moves unavailable.
+
 Both selected canonical endpoints are admitted inside the retained Root after
 native parent admission. With `mutationSymlinks: "reject"`, both full operation
 paths are rechecked after the live mutation-authority callback and before
@@ -522,6 +538,11 @@ destination — there is no atomic-rename step. For exclusive publication of a
 complete stream, use [`create()`](#streamed-creation). For streamed replacement,
 the [`atomic`](atomic.md) helpers provide a staged writer.
 
+For all three write modes, `mode` only selects new-file creation permissions,
+defaulting to `0o600` when neither the call nor the Root supplies it. POSIX
+permissions remain subject to the process umask; existing files are not chmodded.
+The returned numeric `stat` records the admitted descriptor before caller writes.
+
 On POSIX, existing-target opens use `O_NONBLOCK` as an admission safeguard so
 a no-reader FIFO cannot stall regular-file validation. This does not change
 ordinary regular-file write semantics. `replace` and `update` remain write-only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.18.2",
+  "version": "0.20.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -169,18 +169,18 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.18.2",
-    "@openclaw/fs-safe-darwin-x64": "0.18.2",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.18.2",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.18.2",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.18.2",
-    "@openclaw/fs-safe-linux-x64-musl": "0.18.2",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.18.2",
+    "@openclaw/fs-safe-darwin-arm64": "0.20.0",
+    "@openclaw/fs-safe-darwin-x64": "0.20.0",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.20.0",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.20.0",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.20.0",
+    "@openclaw/fs-safe-linux-x64-musl": "0.20.0",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.20.0",
     "jszip": "^3.10.2"
   },
   "devDependencies": {
     "@emnapi/runtime": "2.0.0-alpha.5",
-    "@napi-rs/cli": "3.10.3",
+    "@napi-rs/cli": "3.10.5",
     "@types/node": "^26.6.1",
     "@vitest/coverage-v8": "5.0.1",
     "fast-check": "^4.10.1",