@openclaw/openshell-sandbox 2026.9.3 → 2026.9.5

package/node_modules/@openclaw/fs-safe/docs/security-model.md

@@ -28,6 +28,8 @@ You hand a `root()` boundary to a piece of code that takes caller-controlled rel
 - replaces the destination directory with a symlink right before a write
 - creates a hardlink that aliases an out-of-tree inode and asks you to read or replace it
 - asks a read/open primitive to target a known unsafe device or process-fd path
+- uses an NTFS alternate-stream or directory-index pathname to alias a different
+  Windows filesystem object than the visible path suggests
 - triggers a partial write that leaves a half-written file at the destination
 - ships an archive with `..` paths, absolute paths, or symlinks pointing outside the destination
 
@@ -45,7 +47,31 @@ If you need full sandboxing, run the worker under reduced privileges (uid, conta
 
 ### Path traversal and absolute paths
 
-Every path is resolved against the canonicalized real path of the root, then checked with `isPathInside`. Alias resolution walks components before applying a later `..`, so a symlink cannot change what that parent segment means after validation. Parent traversal, an absolute spelling, or any alias whose canonical result is outside the root throws `outside-workspace`; absolute spellings that remain inside the root are accepted.
+Every path is resolved against the canonicalized real path of the root, then checked at that boundary. On Windows, an exact-case structural Root prefix stays on the lexical fast path; a prefix accepted only by case folding must have the Root's exact directory identity and is rebased onto the trusted Root spelling before use. Alias resolution walks components before applying a later `..`, so a symlink cannot change what that parent segment means after validation. Parent traversal, an absolute spelling, or any alias whose canonical result is outside the root throws `outside-workspace`; absolute spellings that remain inside the root are accepted.
+
+Guarded pathname APIs reject Windows `:` namespace aliases before normalization
+or filesystem access. The only colon admitted in a Windows filesystem path is
+the rooted ASCII drive designator (including extended-drive syntax); relative
+paths admit none. This rule does not authorize device or network paths, which
+retain their independent restrictions. Pure formatters, descriptor-only calls,
+and `walkDirectory` (documented as a non-boundary traversal helper) are outside
+this pathname-admission guarantee. Output helpers continue to sanitize an
+untrusted basename, then validate the resulting path.
+
+The low-level existing-object readers `openRootFile()` and
+`openRootFileSync()` preserve their historical Windows drive-relative input:
+they anchor its leading drive designator before this admission check. The raw
+suffix remains unnormalized, and any additional colon is still rejected before
+filesystem access.
+
+Trusted-path standalone publication APIs retain the same drive-relative
+compatibility. This includes the atomic file, text, JSON, JSON store/direct
+queue writer, directory-replacement, move, and exclusive-publication helpers.
+They capture the drive's current directory at publication entry and carry the
+anchored spelling through their remaining checks, locks, callbacks, receipts,
+publication, and cleanup. File writers preserve the raw suffix. Root-relative
+APIs and caller-constructed relative directory receipts continue to reject
+drive designators.
 
 ### Symlinks (read side)
 
@@ -53,14 +79,40 @@ Every path is resolved against the canonicalized real path of the root, then che
 
 Per-call `symlinks: "follow-within-root"` allows symlinks whose final target is still inside the root. The default is `"reject"`.
 
+`symlinks: "follow-parents-within-root"` allows contained parent directory aliases
+while rejecting a final symlink, including dangling links. Reads open the checked
+canonical parent plus the final basename with the usual no-follow and identity
+checks, so callers do not need their own parent canonicalization.
+
 Guarded root reads compare lossless bigint identities from before open, the opened
 descriptor, the input path, and the canonical target; numeric public `Stats`
-receipts are not used as identity evidence. Unknown Windows device/inode values
-receive one re-inspection without reopening the file. A definite mismatch or
-persistent unknown identity rejects with `path-mismatch` before reading bytes.
-Regular-file readers, root-file adapters, and archive input staging use the same
-exact admission policy. `copyIn()` retains the admitted source identity for its
-checks before and after copying, independently of its numeric metadata receipt.
+receipts are not used as identity evidence. Before returning a handle or reading
+bytes, one best-effort final admission fence checks the originally captured root
+identity, freshly compares the policy-aware pathname with the opened descriptor,
+canonicalizes and re-admits that current target inside the captured root, compares
+the canonical target's exact bigint identity without following a final symlink
+with the descriptor, and checks the root identity again. The two final pathname
+observations remain independent even when the spellings match. Unknown Windows
+device/inode values receive one re-inspection without reopening the file.
+A definite mismatch or persistent unknown identity
+rejects with `path-mismatch`; escaped fresh containment rejects with
+`outside-workspace`. This is not an atomic kernel pathname/open primitive, so the
+namespace can still change after the final observation.
+
+Other regular-file readers, root-file adapters, and archive input staging retain
+their documented descriptor/path admission. The exported unrooted
+`openLocalFileSafely()` and `readLocalFileSafely()` helpers have no captured `Root`
+identity and therefore do not provide the replacement-root fence. `copyIn()`
+retains the admitted source identity for its checks before and after copying,
+independently of its numeric metadata receipt.
+
+The low-level `openRootFile()` adapters additionally retain the canonical root's
+exact identity from before component traversal. After their existing pathname and
+descriptor checks, they verify the root, freshly resolve and re-admit the consumed
+pathname, compare that canonical leaf with the descriptor, and verify the root
+again before returning ownership. A failed final fence closes the descriptor
+without reading. The checks detect substitutions at each observation boundary;
+they do not make pathname confinement atomic against a continuously racing peer.
 
 ### Symlinks (write side)
 
@@ -70,6 +122,35 @@ directory descriptors. Replacement uses descriptor-relative rename just like
 no-replace publication, so replacing the parent pathname does not divert the
 mutation.
 
+When either `denyMutations` or an explicit `mutationSymlinks` policy applies,
+the POSIX writer binds that exact policy snapshot to parent admission. An existing
+parent is canonicalized and identity-matched to its retained descriptor before
+the actual destination is authorized. A missing-parent walk authorizes each
+prospective directory before `mkdirat`, opens it without following a newly
+introduced link, and authorizes the opened object before continuing. This
+prevents a contained Linux `openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS)`
+redirect from reusing policy approval for a different in-root subtree.
+For an ordinary unchanged route, operation-local observations may carry that
+admission across a direct-child creation only after exact parent and child
+fences and a synchronous full-epoch validation. The resulting operation-local
+token authorizes the opened child without an intervening await; stale,
+redirected, incomplete, or foreign evidence returns to the full ordered
+admission. An already-complete fallback parent is likewise retained only after
+full target admission and a fresh exact guard fence. Native acceleration additionally requires an exclusive
+direct-child mkdir result proving that this syscall created the name; a
+collision, legacy helper, or malformed result performs the guarded walk but
+cannot advance the receipt. That boolean is admission provenance only and does
+not grant ownership for cleanup by pathname.
+
+The opt-in `mutationSymlinks` policy applies independently of read policy.
+`"reject"` rejects symlink components; `"follow-parents-within-root"` resolves
+contained directory aliases and rejects final symlinks. Publication checks the
+final component again after awaited staging and parent fences, immediately before
+the rename or exclusive open. These are best-effort symlink checks, not an atomic
+expected-entry/CAS replacement: a concurrent process can still replace the final
+entry between its check and rename. Existing parent containment guarantees remain
+as described below. Omitting `mutationSymlinks` preserves existing mutation behavior.
+
 The JavaScript fallback used by `off`, by `auto` when no binding loads, and by
 the explicit `renameIdentity: "verify-content-with-lock"` compatibility policy
 cannot provide that guarantee because Node exposes no `mkdirat` or `renameat`.
@@ -93,13 +174,13 @@ When `hardlinks: "reject"` is set, reads stat the target and refuse if `nlink >
 
 ### TOCTOU between resolve and use
 
-`resolve()`, `exists()`, `stat()`, and `list()` are explicitly advisory — they answer a question and return. To act on a path with operation-local identity checks, use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()`. The containment table below states which opens are kernel-atomic and which remain best-effort.
+`resolve()`, `exists()`, `stat()`, and `list()` are explicitly advisory — they answer a question and return. `stat()` checks the exact selected target and parent while collecting metadata, and `list()` checks the exact selected directory around its complete batch, so detectable descendant redirection rejects before results are returned. Those checks do not preserve identity after the call. To act on a path with operation-local identity checks, use `read()`, `open()`, `write()`, `create()`, `copyIn()`, `move()`, or `remove()`. The containment table below states which opens are kernel-atomic and which remain best-effort.
 
 A `root()` handle also remembers the canonical root directory identity. Calls fail with `path-mismatch` if that canonical pathname is replaced, including advisory inspection and walking calls, rather than following a replacement root into another tree.
 
 ### Denied mutations
 
-`denyMutations` is an opt-in application policy for `root()` mutation methods. It blocks exact absolute paths with `paths` and whole subtrees with `prefixes`, merging root defaults with per-call entries so a call cannot clear root-level denies. This is not an OS permission boundary: code with access to `node:fs`, a shell, or another process with the same filesystem privileges can bypass it.
+`denyMutations` is an opt-in application policy for `root()` mutation methods. It blocks exact absolute paths with `paths` and whole subtrees with `prefixes`, merging root defaults with per-call entries so a call cannot clear root-level denies. POSIX pinned `write`, `create`, and `copyIn` copy the merged entries before awaiting preflight and reapply them to their admitted canonical parent, including before missing parent creation. This is not an OS permission boundary: code with access to `node:fs`, a shell, or another process with the same filesystem privileges can bypass it.
 
 ### Atomic writes
 

package/node_modules/@openclaw/fs-safe/docs/sidecar-lock.md

@@ -2,6 +2,13 @@
 
 `acquireFileLock()` and `withFileLock()` provide a cross-process file lock with retry and process-exit cleanup. The lock is implemented as a sidecar file (e.g. `state.json` ↔ `state.json.lock`) — only one acquirer can create the sidecar with `O_CREAT | O_EXCL` at a time.
 
+On Windows, both the target and an explicitly supplied `lockPath` reject NTFS
+alternate-stream and directory-index namespace spellings before parent creation,
+in-process reentrant lookup, or sidecar access. Rooted drive paths retain their
+normal meaning, and ordinary colon-bearing POSIX paths remain valid.
+
+JavaScript raw-sidecar creation passes mode `0o600` to that exclusive open. On POSIX, the process umask may further restrict the new file but cannot add group or other access. No pathname `chmod` fallback is used.
+
 ```ts
 import { acquireFileLock } from "@openclaw/fs-safe/file-lock";
 
@@ -25,11 +32,13 @@ On natural event-loop shutdown, a globally deduplicated `process.on("beforeExit"
 
 Always release locks in a `finally` block. Application-managed graceful shutdown can await `release()` or `manager.drain()` before terminating. Explicit `process.exit()`, uncaught failures, crashes, default signal handling, and fatal termination (including `SIGKILL`) do not reliably run asynchronous Root cleanup and may leave sidecars. Recover only after an application-owned liveness policy proves the holder cannot still be writing.
 
+Exit cleanup tolerates shared managers created by older package copies that lack reclaim-guard state, and continues through later manager domains. Handler ownership remains first-registration-wins: loading an updated copy does not replace an older copy's registered handler. Restart with the updated copy registering first to obtain the fix. After building, `node scripts/legacy-lock-exit-proof.mjs` checks clean exit, removal of legacy and modern raw locks, and preservation of a retained lock using synthetic temporary files.
+
 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.
 
 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()` callback and release fail, the release error is the primary `SuppressedError.error` and the callback failure remains available as `SuppressedError.suppressed`. Failed 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.
+`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()` 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.
 
 ## API
 
@@ -59,7 +68,7 @@ function withFileLockSync<T, TPayload>(targetPath: string, options: FileLockSync
 type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
   managerKey?: string;                   // optional in-process manager namespace
   lockPath?: string;                     // override; defaults to `${targetPath}.lock`
-  staleMs?: number;                      // default 30_000
+  staleMs?: number;                      // non-negative or Infinity; default 30_000
   timeoutMs?: number;                    // overall acquire deadline; default unbounded
   retry?: FileLockRetryOptions;
   staleRecovery?: "fail-closed" | "remove-if-unchanged"; // default "fail-closed"
@@ -84,7 +93,7 @@ type FileLockAcquireOptions<TPayload extends Record<string, unknown>> = {
   lockRoot?: Root;
   retainOnExit?: boolean;               // keep the sidecar across process exit (default false)
   onCompromised?: (info: { lockPath: string; normalizedTargetPath: string }) => void;
-  compromiseCheckIntervalMs?: number;
+  compromiseCheckIntervalMs?: number;    // 0/omitted disables; otherwise 1..2_147_483_647
 };
 
 type FileLockRetryOptions = {
@@ -98,6 +107,16 @@ type FileLockRetryOptions = {
 
 `payload` is a function so you can re-evaluate it on each retry (e.g. timestamp, PID).
 
+Asynchronous acquisition snapshots `targetPath`, an explicit `lockPath`, and
+`lockRoot` before its first asynchronous operation. Cwd-dependent path spellings
+are resolved using Node's platform path-resolution rules at that point, and the
+resulting absolute paths remain fixed through retries, stale recovery,
+verification, and release even if the process later changes its working
+directory. An explicit, fully qualified `lockPath` retains its caller-supplied
+spelling; current-drive-rooted and drive-relative Windows paths are resolved at
+the snapshot boundary. The snapshot adds no normalization beyond what is
+required to remove that cwd or current-drive dependency.
+
 The complete serialized sidecar must fit within 1 MiB (1,048,576 UTF-8 bytes),
 including pretty-printed JSON, newlines, and the internal ownership token's
 trailing whitespace. The limit counts bytes, not string characters. Oversized
@@ -211,6 +230,11 @@ Discarding an acquisition observation is not proof that the pathname is absent:
 another owner may already have created the next record. Every discarded
 observation consumes the normal retry/deadline budget and requires fresh
 exclusive creation. It supplies no release, reclaim, or held-lock authority.
+If that successor disappears during the recovery metadata probe, the waiter
+may discard the probe only with an operation-local receipt for an admitted
+regular file with one link, followed by current Root and canonical ancestor
+checks. A generic metadata error does not permit this retry, and public
+`Root.stat()` still rejects a file that changes during observation.
 Generic `Root.open()` and held-owner/reclaim reads still reject failed opens.
 Moving an already-matched pinned descriptor without unlinking it, unknown or
 inexact identities, retargeted ancestors, and unrelated filesystem or caller
@@ -243,7 +267,14 @@ type FileLockHandle = {
 captured at acquisition. Set `compromiseCheckIntervalMs` together with
 `onCompromised` for a cheap periodic check; the callback fires once after the
 sidecar no longer matches or after a verification I/O failure. This is
-detection, not revocation of work already in progress.
+detection, not revocation of work already in progress. Asynchronous checks are
+serialized, so a slow verification never overlaps the next timer tick.
+
+The compromise-check interval is validated before payload evaluation or
+filesystem acquisition. Omit it or pass `0` to disable monitoring; enabled
+intervals must be finite and between 1 and 2,147,483,647 milliseconds. Values
+outside that range are rejected instead of being clamped by Node.js to an
+unexpectedly tight polling loop.
 
 ## Synchronous locks
 
@@ -291,6 +322,13 @@ try {
 }
 ```
 
+Failed synchronous acquisition attempts close the created descriptor once even
+if its metadata cannot be read. Cleanup leaves the sidecar in place without an
+exact descriptor identity. A metadata-capture failure does not replace the
+acquisition error; if close or identity-checked removal also fails, the
+`SuppressedError.error` is the acquisition error and `suppressed` is the cleanup
+error.
+
 The sync payload, reclaim, and parsing callbacks must also be synchronous. This
 shape is appropriate for a short boot migration; it is a poor fit for a server
 request because retry backoff uses a blocking wait.

package/node_modules/@openclaw/fs-safe/docs/store.md

@@ -32,7 +32,7 @@ import {
 | Durable JSON queue helpers | Append/load/ack JSON entry files using atomic writes and delivered markers. |
 | [Private file-store mode](private-file-store.md) | `fileStore({ private: true })` for credentials, tokens, and per-agent state at `0600` files under `0700` directories. |
 
-`fileStore().json("rel.json")` and `jsonStore({ filePath })` are intentionally separate primitives. Use `fileStore().json(...)` when JSON state lives alongside other files in the same managed directory; use `jsonStore({ filePath })` when you have a single absolute path and want the keyed JSON shape directly.
+`fileStore().json("rel.json")` and `jsonStore({ filePath })` are intentionally separate primitives. Use `fileStore().json(...)` when JSON state lives alongside other files in the same managed directory; use `jsonStore({ filePath })` when you have one trusted path, resolved to an absolute path at construction, and want the keyed JSON shape directly.
 
 ## Picking a shape
 
@@ -72,12 +72,37 @@ Loading serializes consumers for one ID through a sidecar lock, then creates `pr
 
 Queue and failed directory creation fsyncs every newly-created parent edge from the leaf toward the trusted root. Enqueue and migration writes fsync the temp file and parent; claim, acknowledgement, quarantine, delivered-marker cleanup, and retirement transitions fsync every affected directory and propagate real sync failures. A transition may already be visible when a post-mutation sync fails, so retry the same operation to complete its crash-recovery state. Acknowledgement retries resync the queue directory even when both `.processing` and `.delivered` marker names are already absent, before reporting completion or rejecting a newer pending generation; quarantine retries with only failed evidence resync that destination before repairing the vanished queue source.
 
-`writeJsonDurableQueueEntry()` and migrations share strict parent synchronization inside the atomic writer's retained descriptor and per-path serialization lifetime, followed by published-file identity verification. If sync fails after publication, the write rejects without rolling back the published JSON; retrying writes the entry again and must complete its own sync. This is not a rollback, deduplication, or exactly-once guarantee. The generic `replaceFileAtomic({ syncParentDir: true })` option remains best-effort.
+`writeJsonDurableQueueEntry()` and migrations share strict parent synchronization inside the atomic writer's retained descriptor and per-path serialization lifetime, followed by published-file identity verification. If sync fails after publication, the write rejects without rolling back the published JSON; retrying `writeJsonDurableQueueEntry()` writes the entry again and must complete its own sync. Loader retries resync an existing processing claim's parent under the transfer lock before calling `read`, even when a version-dependent callback would no longer request migration. Fresh claims and same-directory source retirement already complete that sync. This is not a rollback, deduplication, or exactly-once guarantee. The generic `replaceFileAtomic({ syncParentDir: true })` option remains best-effort.
+
+The direct queue writer accepts trusted relative paths. On Windows it anchors
+an ordinary drive-relative `filePath` before publication and strict parent
+sync. Other queue lifecycle APIs retain their own root/path admission contracts.
 
 Batch loading skips invalid entry names, malformed, oversized, or unreadable entry content, and caller `read` callback failures. Initially unowned pending entries (hardlinks or unverifiable identities), symlinks, non-files, and absent pending entries are also skipped. Claim, transfer-lock, retirement, and migration write/publication/durability failures reject the batch with the original error, even if earlier entries succeeded. Migration in both loaders strictly syncs the parent directory after successful publication. Visible transitions and earlier processing claims remain for retry; a rejected batch does not acknowledge or roll them back.
 
 Failed destinations are create-only. Quarantine publishes the claimed file by hardlink, so the queue and failed directories must share a filesystem with hardlink support. If `failed/<id>.json` already exists, quarantine rejects while preserving both that earlier evidence and the current claimed entry instead of overwriting either file. The `read` callback continues to receive the logical `.json` path even though bytes are read and migrations are written through the claimed path.
 
+Migrations stay bound to the exact processing file opened for that load. The
+read descriptor remains pinned while the callback runs outside the transfer
+lock; after the callback returns, migration reacquires the lock and rechecks the
+claim before publication. If another consumer acknowledged, quarantined, or
+replaced that claim, the migration rejects with `FsSafeError("path-mismatch")`
+and leaves the newer generation or failed evidence intact. A stale migration
+rejects both single and batch loads; ordinary callback failures retain their
+existing single-load rejection and batch-skip behavior.
+
+On Windows, migration releases its read pin once at this publication boundary
+because an open target can block replacement. It rechecks the exact pathname
+identity after the asynchronous close while still holding the transfer lock.
+POSIX retains the read pin through publication. Other readers keep ownership
+of their handles; Windows sharing denials still reject and can be retried after
+those readers close.
+
+Generation arbitration requires consumers to use the transfer lock. As with
+[atomic writes](atomic.md#beforerename), identity checks and pathname replacement
+are separate operations; use a trusted writable parent or OS isolation against
+processes that ignore the lock and mutate queue paths concurrently.
+
 Queue entry reads verify lossless file identities before opening, on the opened
 descriptor, and at the current pathname before reading bytes. POSIX opens are
 nonblocking, so a raced FIFO is rejected rather than stalling a consumer. On Windows, an