@openclaw/fs-safe 0.7.0 → 0.7.2

package/dist/sidecar-lock-root.js

@@ -0,0 +1,76 @@
+import path from "node:path";
+import { inspectDirectoryIdentity } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { fileObservation } from "./file-observation.js";
+import { isNotFoundPathError } from "./path.js";
+import { resolveRootPath } from "./root-path.js";
+export async function openSidecarRoot(lockRoot, relative, discardObservation, onOpenFailure) {
+    const resolved = await lockRoot.resolve(relative);
+    const canonicalPath = async () => (await resolveRootPath({
+        absolutePath: resolved,
+        rootPath: lockRoot.rootReal,
+        rootCanonicalPath: lockRoot.rootReal,
+        boundaryLabel: "sidecar lock root",
+    })).canonicalPath;
+    const expectedRealPath = await canonicalPath();
+    if (expectedRealPath === lockRoot.rootReal)
+        throw new FsSafeError("not-file", "sidecar lock is a directory");
+    const parents = [];
+    let completeParents = true;
+    if (discardObservation) {
+        // Follow permitted in-root aliases first; receipts cover canonical ancestry.
+        for (let dir = path.dirname(expectedRealPath);; dir = path.dirname(dir)) {
+            try {
+                parents.push({ dir, stat: await inspectDirectoryIdentity(dir) });
+            }
+            catch (error) {
+                if (!isNotFoundPathError(error))
+                    throw error;
+                completeParents = false;
+            }
+            if (dir === lockRoot.rootReal)
+                break;
+        }
+    }
+    const observation = fileObservation();
+    try {
+        const opened = await observation.run(() => lockRoot.open(relative));
+        if (opened.realPath !== expectedRealPath) {
+            await opened.handle.close().catch(() => undefined);
+            throw new FsSafeError("path-mismatch", "sidecar lock path changed during open");
+        }
+        return opened;
+    }
+    catch (error) {
+        const openFailed = observation.has(error, `open:${resolved}`);
+        if (openFailed)
+            onOpenFailure?.(error);
+        const missing = openFailed && error instanceof FsSafeError && error.code === "not-found";
+        if (missing && !discardObservation)
+            return null;
+        const discardable = observation.has(error, `unlinked:${resolved}`) ||
+            (discardObservation === "changed" && observation.has(error, `changed:${resolved}`));
+        if (!discardObservation || (!missing && (!completeParents || !discardable)))
+            throw error;
+        try {
+            try {
+                const current = await lockRoot.stat(relative);
+                if (!current.isFile || current.isSymbolicLink || current.nlink !== 1)
+                    throw error;
+            }
+            catch (probeError) {
+                if (!(probeError instanceof FsSafeError && probeError.code === "not-found"))
+                    throw probeError;
+            }
+            for (const { dir, stat } of parents)
+                await inspectDirectoryIdentity(dir, stat);
+            await lockRoot.resolve(relative);
+            if (await canonicalPath() === expectedRealPath)
+                return null;
+        }
+        catch {
+            // Keep the original failure when directory or confinement proof fails.
+        }
+        throw error;
+    }
+}

package/dist/strict-file-identity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strict-file-identity.d.ts","sourceRoot":"","sources":["../src/strict-file-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAG3C,KAAK,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AA6B1D,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,iBAAiB,EACnE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,iBAAiB,EACjE,OAAO,EAAE,MAAM,CAAC,EAChB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,CAAC,CAOH"}
+{"version":3,"file":"strict-file-identity.d.ts","sourceRoot":"","sources":["../src/strict-file-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAI3C,KAAK,iBAAiB,GAAG,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC;AA+B1D,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,iBAAiB,EACnE,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACzB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAgB,uBAAuB,CAAC,CAAC,SAAS,iBAAiB,EACjE,OAAO,EAAE,MAAM,CAAC,EAChB,QAAQ,CAAC,EAAE,iBAAiB,EAC5B,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,CAAC,CAOH"}

package/dist/strict-file-identity.js

@@ -1,6 +1,9 @@
 import { FsSafeError } from "./errors.js";
+import { recordFileObservationFailure } from "./file-observation.js";
 function identityMismatch() {
-    return new FsSafeError("path-mismatch", "file identity changed or could not be verified");
+    const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
+    recordFileObservationFailure(error, "identity");
+    return error;
 }
 function identityCheck(expected, platform) {
     const known = {};

package/docs/archive.md

@@ -245,9 +245,13 @@ framing rules before parser normalization:
   padded sizes must fit `Number.MAX_SAFE_INTEGER`, even with PAX overrides,
   before member budgets are considered.
 
-Framing failures use `ArchiveFormatError("archive-header-invalid")`. PAX `x`
-and GNU long-name/long-link `L`/`K` payloads retain their existing support and
-metadata limits; the zero-body rule is not applied to all non-regular types.
+Framing failures use `ArchiveFormatError("archive-header-invalid")`, except
+invalid UTF-8 or nonzero bytes after the first NUL in fixed name, linkname,
+and USTAR prefix fields, which use `ArchiveSecurityError("entry-path")`.
+Missing linknames on links and nonempty linknames on non-links still use the
+format error. PAX `x` and GNU long-name/long-link `L`/`K` payloads retain their
+existing support and metadata limits; the zero-body rule is not applied to all
+non-regular types.
 PAX effective sizes still determine regular-member framing. Admission preserves
 the input bytes, and all entry/path/byte limits and extraction deadlines remain
 in force. Native inspection now completes this admission pass before parsing,
@@ -411,7 +415,11 @@ regular-file entry into a bounded `Buffer` without extracting a tree. It pins
 and privately stages the archive input, rejects link, directory, and duplicate
 entries, verifies ZIP CRC and declared size,
 and throws `ArchiveLimitError` if the requested entry's output exceeds
-`maxBytes`. For TAR, `maxBytes` applies only to that requested entry: a larger
+`maxBytes`. ZIP output within that cap must match the declared uncompressed
+size exactly; either a shorter or longer payload throws
+`ArchiveFormatError("archive-header-invalid")` before bytes are returned on
+both JavaScript and native backends.
+For TAR, `maxBytes` applies only to that requested entry: a larger
 unrequested member remains valid within the default archive admission limits.
 TAR traversal uses default entry-count, compressed-input, and metadata limits,
 plus the 768 MiB decoded ceiling derived from default extracted/archive byte

package/docs/atomic.md

@@ -209,6 +209,40 @@ throws `ESTALE` before commit when possible. If the destination has already
 been committed, cleanup still preserves the changed source entries and throws
 `ESTALE`.
 
+### Final rename authorization
+
+Pass `assertBeforeRename` when a move depends on a revocable lease or another
+caller-owned authorization. The helper captures this callback when called and
+runs it synchronously after asynchronous preparation and directory checks,
+immediately before each rename is dispatched:
+
+```ts
+type MovePathWithCopyFallbackOptions = {
+  from: string;
+  sourceHardlinks?: "allow" | "reject";
+  to: string;
+  assertBeforeRename?: () => void;
+};
+```
+
+Throw to refuse publication. The original error is propagated, including errors
+with `EXDEV` or `EPERM` codes; an authorization failure never starts a copy
+fallback. A genuine rename failure may still require a second authorization
+check before publishing the staged copy.
+
+The callback must return `undefined` synchronously. Returning a Promise, thenable,
+or any other value refuses the rename with a `TypeError`; rejected asynchronous
+results are consumed without authorizing the operation. Perform asynchronous
+policy checks before calling the helper and use this callback to recheck the
+current owner at the mutation boundary.
+
+A refused rename leaves the source and destination unchanged; any private
+staged copy follows the helper's normal cleanup. The check does not cancel an
+already-dispatched rename or make an external lease store atomic with the
+filesystem. Cleanup after a successful move retains the existing source-identity
+checks. Omitting the
+callback preserves the usual move behavior.
+
 ## Difference from `root()`
 
 | `Root` methods | `atomic` helpers |

package/docs/json.md

@@ -144,6 +144,9 @@ rename, so that fallback is temporarily non-atomic while retaining the staged
 file's `0600` mode; use the async `writeJson()`/`replaceFileAtomic()` surfaces
 when fallback policy must be explicit.
 
+Its private sibling temporary name is independent of the destination basename,
+so staging does not lengthen a valid destination filename.
+
 ```ts
 writeJsonSync("./prefs.json", { theme: "dark" });
 ```

package/docs/output.md

@@ -58,9 +58,12 @@ through the package's filename sanitizer; `fallbackFileName` supplies the name
 when nothing remains. This removes traversal, device-name, and invalid-character
 hazards but does not trim Windows-normalized trailing dots or spaces; reject or
 rewrite those when cross-platform filename uniqueness matters.
-The same sanitized basename is used for producer staging, guarded internal
-temps, the final rename target, and the returned `path`; raw and staged names
-never diverge.
+`staging: "workspace"` passes the sanitized basename to the producer.
+`staging: "sibling"` embeds that basename in its randomized temporary name.
+The final target and returned `path` use the destination basename, sanitized
+when needed as described above. Guarded temporary files used only inside
+fs-safe have independent names so their length does not grow with the
+destination basename.
 
 ## Choosing a staging mode
 

package/docs/sidecar-lock.md

@@ -94,16 +94,21 @@ type FileLockRetryOptions = {
 ```
 
 `payload` is a function so you can re-evaluate it on each retry (e.g. timestamp, PID).
+Errors thrown by `payload`, its JSON serialization (including `toJSON`), or
+`parsePayload` propagate unchanged without retrying the callback. Rethrowing an
+error saved from an earlier filesystem operation does not grant retry authority.
 Retry counts must be non-negative safe integers. Retry factors and delays must be finite and non-negative, and when both delay bounds are provided `minTimeout` cannot exceed `maxTimeout`. `timeoutMs` accepts a finite non-negative deadline or positive infinity for an unbounded wait; invalid numeric values reject before filesystem acquisition starts.
 `parsePayload` replaces JSON parsing for legacy or custom sidecars. Its `unknown`
 result is passed to `shouldReclaim` and `shouldRemoveStaleLock`, allowing PID,
 process-start, argv, or role schemas to remain application-owned.
 
 On Windows, a pathed `EPERM` from creating or opening the lock file can be a
-short teardown race after another holder unlinks it. The async lock retries that
-specific denial at most eight times. A parent-directory denial, a denial from a
-callback, or a ninth consecutive lock-file denial surfaces as the original
-`EPERM`; it is not converted to `file_lock_timeout`.
+short teardown race after another holder unlinks it. Both async and sync locks
+retry that specific open denial at most eight times per acquisition, within the
+caller's retry/deadline budget. A parent-directory denial, a callback/read/stat
+failure, or exhaustion of either budget surfaces the original error; a denied
+open is not converted to `file_lock_timeout`. Retrying always requires fresh
+exclusive creation and grants no ownership or removal authority.
 
 ## Owner-scoped reentrancy
 
@@ -155,6 +160,45 @@ an existing `Root` capability. `lockPath` must resolve inside that root.
 Identity-conditioned removal remains the only release and reclaim deletion
 path.
 
+An owner can finish releasing while another async acquirer inspects its record.
+Create-only Root writes do not open an existing record merely to inherit its
+mode. Once a pathname sample and opened descriptor agree, a failed acquisition
+snapshot can be discarded only when the original descriptor has exact identity,
+was not observed with multiple links, and proves it was unlinked (`nlink === 0`).
+This includes Windows resolver
+`EPERM`/`EBADF` failures, with evidence captured at the failing operation before
+closing the descriptor. The canonical in-root ancestor chain and Root are
+rechecked; permitted in-root parent symlinks are resolved before those checks.
+
+A contending waiter may also encounter a new holder between its pre-open
+pathname inspection and opening the file. It may discard that stale observation
+only when the old sample and opened descriptor have different, strictly known
+regular-file identities, neither was observed with multiple links, and the
+opened descriptor and complete canonical ancestry pass reinspection. This does
+not prove the old pathname sample was unlinked rather than moved. The new
+holder's payload is not read or adopted. Post-create admission never opts into
+this pre-open-change policy.
+
+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.
+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
+errors fail closed. Failure receipts belong only to the current Root observation,
+including during nested or concurrent acquisitions; historical error identity
+is not changed-file, unlink, or open-denial evidence.
+
+After creating a record, the async Root-backed acquirer checks the reopened
+bytes against its exact serialized payload and ownership token. A replacement
+is never adopted; a descriptor observed unlinked at the end of admission is
+never registered as held. Failed admission cleanup retains the original creator
+receipt, so it cannot remove a replacement using a later stat alone. Native
+mode changes the create mechanism, not these Root-backed admission checks.
+Non-Root and synchronous snapshots retain their descriptor/read/path checks
+and do not use the Root opened-path resolver.
+
 ## Release handle
 
 ```ts
@@ -184,6 +228,14 @@ compromise interval treats a thrown verification I/O error as a lost lock and
 invokes `onCompromised` once, matching the asynchronous `.catch(() => false)`
 contract. An explicit `verifyStillHeld()` call still propagates that I/O error.
 
+Windows synchronous lock parents use the same canonical path spelling as
+`root()`, including short-name expansion. With `lockRoot`, a failed parent
+canonicalization or an out-of-root parent still rejects. Missing-path observations from snapshot
+`lstat`/`open`, and identity-mismatched snapshots, consume the normal retry and
+deadline budget. Errors from descriptor reads/stats or parsing are not treated
+as missing snapshots, even when their code is `ENOENT`. Held verification,
+release, and reclaim do not retry open denials.
+
 Both synchronous helpers consume the [process-wide lock defaults](config.md#configurefssafelocks-config).
 A synchronous retry sleep is clamped to the remaining finite deadline, so a long or jittered backoff cannot extend the configured timeout or block forever.
 Per-call options take precedence, including zero values; a per-call `retry`

package/docs/writing.md

@@ -27,6 +27,9 @@ await fs.mkdir("snapshots/2026/05");
 5. Atomically rename the temp file over the destination.
 6. Stat the resulting fd and verify identity.
 
+Private sibling temporary names are independent of the destination basename,
+so staging does not add a suffix to an otherwise valid long filename.
+
 A failure before the final rename leaves the destination at its previous
 contents. A successful rename publishes the complete replacement. This
 old-or-new guarantee does not apply to `append()` or `openWritable()`, which
@@ -86,6 +89,9 @@ alone is never proof that the name still refers to the expected file.
 ### `fs.create(rel, data, options?)`
 
 Don't-clobber variant of `write()`. Throws `already-exists` if the target is there.
+Create-only preflight preserves boundary, alias, hardlink, and type checks without
+opening an existing target to inherit its mode; a fresh file uses the requested
+mode or the normal new-file default.
 
 ```ts
 try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -149,13 +149,13 @@
     "crabbox:warmup": "crabbox warmup"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.7.0",
-    "@openclaw/fs-safe-darwin-x64": "0.7.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.7.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.7.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.7.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.7.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.7.0",
+    "@openclaw/fs-safe-darwin-arm64": "0.7.2",
+    "@openclaw/fs-safe-darwin-x64": "0.7.2",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.7.2",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.7.2",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.7.2",
+    "@openclaw/fs-safe-linux-x64-musl": "0.7.2",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.7.2",
     "jszip": "^3.10.1",
     "tar": "7.5.22"
   },