@openclaw/fs-safe 0.19.0 → 0.20.0

package/docs/security-model.md

@@ -232,13 +232,16 @@ The library does not modify or constrain the global Node.js `fs` namespace, and
 
 | Mechanism | Reported containment | Boundary |
 |---|---|---|
-| Linux native | `kernel-atomic` | `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)` resolves and opens under the root in one kernel operation. |
+| Linux native with `openat2` | `kernel-atomic` | `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)` resolves and opens under the root in one kernel operation. |
+| Linux native without `openat2` | `best-effort` | A no-follow `openat` component walk retains each parent and verifies exact identity associations before and after the final open; all symlink components are rejected. |
 | macOS native | `best-effort` | macOS 15.4 and newer use `O_RESOLVE_BENEATH` first; older kernels use the guarded `openat(O_NOFOLLOW)` component walk. Both verify the opened descriptor with `F_GETPATH`. |
 | Windows native | `best-effort` | Handle-relative `NtCreateFile` rejects reparse points, but this package does not claim a Linux-style atomic beneath guarantee. |
 | JavaScript fallback | `best-effort` | Canonical checks, no-follow opens where Node exposes them, and post-open identity checks form a check-then-use sequence. |
 
 The macOS `F_GETPATH` verification is an escape detector, not a race-atomic guarantee. A hostile same-UID process can rename a directory after `O_RESOLVE_BENEATH` or the manual walk and race the post-open sample or a later descriptor-relative mutation. The native result therefore remains `best-effort` on macOS even when the kernel flag is available. No policy decision is attached to these labels; callers can inspect the fact and decide what their own threat model requires.
 
+The Linux fallback's identity checks are also detection-based: a directory can be renamed between chain samples or before a later descriptor-relative mutation. It cannot provide atomic resolution, and rejection after a mutating open does not promise rollback. See [Linux without openat2](native.md#linux-without-openat2) for the cached capability probe, conservative symlink rejection, and operations that remain unavailable.
+
 The public `OpenResult`, `ReadResult`, and `WritableOpenResult` expose `containment`. Those root APIs currently report `best-effort`; direct native `openBeneath()` reports the platform value above. No-replace publication uses `renameat2(RENAME_NOREPLACE)` on Linux, `renameatx_np(RENAME_EXCL)` on macOS, and `FileRenameInfoEx` with replacement disabled on Windows, but those separate mutation semantics do not upgrade an open result's containment label.
 
 ## Limitations to keep in mind

package/docs/sidecar-lock.md

@@ -63,6 +63,8 @@ Exit cleanup tolerates shared managers created by older package copies that lack
 
 Each new sidecar also carries an internal random ownership token encoded as JSON trailing whitespace. `JSON.parse()` and every payload callback still see exactly the caller-provided object. Only the process that successfully created the sidecar keeps that token as release authority; merely reading token-shaped bytes from disk does not enable this mode. Release compares the in-memory token and exact serialized bytes, and requires the pathname to remain a regular file, instead of requiring an opened descriptor and pathname lookup to report the same inode identity. This preserves ownership checks on filesystems such as Docker Desktop VirtioFS where those two views can legitimately differ. Sidecars created by older releases have no token and retain the legacy identity-plus-content check. If Windows reports a zero device or inode for either identity observation, that check is inconclusive and removal is skipped.
 
+Last-chance raw-lock exit cleanup requires known Windows device and inode values from both pathname observations and the opened descriptor. A zero value leaves the sidecar in place, including for token-owned locks. Known descriptor/path identity differences remain supported; a pathname identity change during the read still prevents cleanup.
+
 The raw sidecar bytes are not a canonical JSON representation: tools that trim or rewrite the trailing whitespace invalidate the ownership token, so release leaves the changed sidecar in place and fails closed. The token distinguishes cooperating acquisitions; it is not a secret and does not make pathname compare-and-remove atomic against a hostile process that can replace files outside the lock protocol.
 
 `release()` propagates an I/O failure that prevents deletion of an unchanged, owned sidecar; it never reports successful cleanup while leaving that lock behind. The handle and manager retain the exact cleanup receipt after a failure, so the same handle can retry `release()` and `manager.drain()` can retry retained cleanup. A changed sidecar remains an ownership mismatch rather than a deletion failure and is left untouched. If both a `withFileLock()` or `withFileLockSync()` callback and release fail, the release error is the primary `SuppressedError.error` and the callback failure remains available as `SuppressedError.suppressed`. Failed asynchronous acquisition cleanup uses the same shape, with the cleanup error primary and the acquisition failure suppressed. On Node runtimes without the global `SuppressedError` constructor, fs-safe returns the equivalent `Error` shape with the same name and properties.

package/docs/staged-symlink.md

@@ -0,0 +1,123 @@
+---
+title: Retained symlink publication
+description: "Admit and retain an identified staged symlink for no-replace publication and explicit recovery."
+---
+
+# Retained symlink publication
+
+`retainSymlinkInDirectory()` from `@openclaw/fs-safe/advanced` admits an
+**existing** direct-child symlink against caller-captured identity, ownership,
+change time and target. It holds a no-follow descriptor to that inode and its
+parent until cleanup. It does not create a symlink or infer ownership from a
+same-target pathname observation. This dedicated lifecycle does not relax
+`Root.move()` or regular-file staging's symlink rejection.
+
+The caller owns staging and admission evidence. Create and inspect the stage
+under the application's cooperative writer lock, and keep that lock through
+admission. A historical stat is not a lifetime handle: if peers can recycle
+inodes between capture and admission, identity numbers alone cannot establish
+historical ownership. Once admitted, the retained descriptor prevents inode
+reuse until this owner closes. Failed admission closes descriptors without
+unlinking anything; all staging cleanup remains with the caller.
+
+Linux uses `O_PATH | O_NOFOLLOW`; macOS uses metadata-only `O_EVTONLY | O_SYMLINK`
+with nonblocking/no-controlling-terminal flags. A non-following preflight rejects
+observed special files before open; the opened descriptor must still match.
+Windows, native mode off, and missing or older bindings reject before namespace
+mutation. No fallback interpreter, copy, following open, or public descriptor
+is used. Symlinks must have one link and a UTF-8 target; their targets are never
+opened or confined by this API. The application must authorize the target.
+
+## Example
+
+```ts
+import {
+  retainSymlinkInDirectory,
+  type StagedSymlinkExpected,
+  type PublishedSymlinkReceipt,
+} from "@openclaw/fs-safe/advanced";
+import type { DirectoryReceipt } from "@openclaw/fs-safe/durability";
+
+// Application owns stage creation, capture, locking and transaction policy.
+export async function publishInstallerLink(options: {
+  directory: DirectoryReceipt;
+  stagedBasename: string;
+  expected: StagedSymlinkExpected;
+  finalBasename: string;
+  assertAuthorizedAndCurrent(): void;
+}): Promise<PublishedSymlinkReceipt> {
+  await using staged = await retainSymlinkInDirectory({
+    directory: options.directory,
+    basename: options.stagedBasename,
+    expected: options.expected,
+    assertBeforeMutation: options.assertAuthorizedAndCurrent,
+  });
+  return await staged.publish(options.finalBasename);
+}
+```
+
+`expected` requires exact bigint `dev`, `ino`, `ctimeNs`, integer `uid`
+and `gid`, and `target`. Admission snapshots these values and the parent
+receipt. The frozen returned receipt contains `directory`,
+`temporaryBasename`, `target`, and preparation-time `identity` metadata,
+like [regular-file staging](staged-file.md). Rename may change timestamps;
+the original receipt is never replaced by a post-publication identity.
+
+## Lifetime and outcomes
+
+- `assertCurrent()` checks the admitted parent pathname, original name, retained
+  inode, single-link count, ownership, mode and target before publication.
+- `publish(basename)` accepts a distinct portable direct-child name. It performs
+  the synchronous authority assertion, rechecks source and parent, and dispatches
+  guarded native no-replace rename. An existing file, symlink or directory is
+  never overwritten, and the link is never nested inside a destination directory.
+- Successful dispatch is recorded as `published` **before** fallible postchecks.
+  A foreign same-target replacement fails verification without becoming owned.
+  `assertPublished()` checks against the still-retained inode.
+- `removePublished()` is an explicit recovery action, not automatic rollback.
+  It reasserts authority and removes only an observed matching published link
+  through the retained original parent. It returns `removed`, `name-absent`,
+  or `preserved`. Its outcome or error is cached: it never retries an uncertain
+  unlink or touches a later replacement. It does not restore an old destination.
+- `cleanup()` removes only an unattempted, still-owned stage, then closes both
+  handles. Published names are preserved. Indeterminate publication preserves
+  both names. Authority rejection during cleanup preserves the stage and still
+  closes handles. Repeated cleanup replays the cached result/error without
+  touching descriptor numbers.
+- `await using` invokes cleanup and raises on a `preserved` outcome. Invocation
+  order serializes descriptor work; reentrant calls from the authority callback
+  reject. Callbacks must be synchronous; returned thenables are refused.
+
+Errors carry `StagedSymlinkFailureDetails` in `FsSafeError.details`: the phase,
+recorded `publication`, and a cleanup receipt when applicable. Publication is
+`not-published`, `published` (with the precaptured receipt), or
+`indeterminate` (with the attempted name). Native errno, including a collision,
+does not rule out a committed remote rename whose response was lost. Only
+pre-dispatch rejection leaves publication `not-published`. After an indeterminate
+result, this owner cannot publish again or remove the possibly published name.
+If inspecting a native rename error itself fails, publication is likewise
+`indeterminate`; the original thrown value remains the reported cause.
+
+Cleanup records `temporaryBasename`, `publication`, `resources`
+(`closed` or `close-failed`), and `status` (`removed`, `name-absent`,
+`preserved`, `failed`, or `not-needed`). Failure closes every retained handle
+once and aggregates cleanup/close errors. A failed explicit recovery unlink is
+reported to its caller and is not converted into successful recovery by cleanup.
+Thrown values whose error metadata cannot be inspected are reported as
+`helper-failed` with the original value as `cause`; cleanup and recovery still
+cache their terminal error without retrying callbacks or descriptor closes.
+
+## Limits
+
+This is directory-relative targeting, **not CAS**. Identity checks followed by
+rename or unlink are not atomic conditional mutations. An uncooperative writer
+can replace a child in the final syscall gap; observed substitutes are preserved,
+but callers must coordinate writers to exclude that gap. The retained parent
+prevents redirection into a replacement parent; a parent move can still cause
+publication in the moved original and a `published` postcheck failure.
+
+No receipt promises crash durability or recovery after process death, arbitrary
+renames, permission revocation or I/O failure. This API does not sync directories
+or persist descriptors. Caller journals, state capture, conditional restoration,
+durability, and transaction settlement remain separate requirements. Keep the
+owner alive until the application's publication or recovery decision settles.

package/docs/store.md

@@ -62,7 +62,9 @@ const pending = await loadPendingJsonDurableQueueEntries({ queueDir, tempPrefix:
 
 `id` must be a single safe path segment: non-empty, not dot-prefixed, and made
 from letters, numbers, `_`, `-`, and `.`. Slashes, backslashes, NUL bytes, `.`,
-and `..` are rejected.
+`..`, and Windows reserved device names such as `CON`, `NUL`, and `COM1` are
+rejected on every platform so queue IDs remain portable. Temporary filenames
+continue to suffix reserved stems (for example, `CON.txt` becomes `CON_.txt`).
 
 Use `ackJsonDurableQueueEntry()` after durable processing succeeds and
 `moveJsonDurableQueueEntryToFailed()` when the caller wants to quarantine an

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/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).
 
@@ -354,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.19.0",
+  "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.19.0",
-    "@openclaw/fs-safe-darwin-x64": "0.19.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.19.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.19.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.19.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.19.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.19.0",
+    "@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",