@openclaw/fs-safe 0.18.1 → 0.19.0

package/dist/temp-target.js

@@ -6,6 +6,7 @@ import { suffixWindowsReservedDeviceName } from "./filename.js";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { assertSafePathSegment, sanitizeSafePathSegment, trimHyphenEdges } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
+import { hasNodeErrorCode } from "./path.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 const HYPHEN_CHAR_CODE = 0x2d;
@@ -76,12 +77,6 @@ export function buildRandomTempFilePath(params) {
     assertNoWindowsPathAlias(filePath, "filesystem", "temp file path uses a Windows filesystem namespace alias");
     return filePath;
 }
-function isNodeErrorWithCode(err, code) {
-    return (typeof err === "object" &&
-        err !== null &&
-        "code" in err &&
-        err.code === code);
-}
 async function cleanupTempDir(dir, identity, onCleanupError) {
     try {
         const current = fsSync.lstatSync(dir, { bigint: true });
@@ -91,7 +86,7 @@ async function cleanupTempDir(dir, identity, onCleanupError) {
         await fs.rm(dir, { recursive: true, force: true });
     }
     catch (err) {
-        if (!isNodeErrorWithCode(err, "ENOENT")) {
+        if (!hasNodeErrorCode(err, "ENOENT")) {
             onCleanupError?.(err);
         }
     }
@@ -174,7 +169,7 @@ export async function createOwnedTempFile(params) {
                     await owner.cleanup();
                 }
                 catch (err) {
-                    if (!isNodeErrorWithCode(err, "ENOENT")) {
+                    if (!hasNodeErrorCode(err, "ENOENT")) {
                         params.onCleanupError?.(err);
                     }
                 }

package/dist/temp-workspace-admission.js

@@ -4,10 +4,9 @@ import path from "node:path";
 import { inspectDirectoryIdentitySync, observeDirectoryIdentitySync, } from "./directory-guard.js";
 import { admitTempWorkspaceChild, admitTempWorkspaceChildSync, assertTrustedTempWorkspaceDirectory, inspectTempWorkspaceDescriptorIdentitySync, projectTempWorkspaceNumericIdentity, TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-child-admission.js";
 import { FsSafeError } from "./errors.js";
-import { recordFileObservationFailure } from "./file-observation.js";
 import { realpathSync } from "./realpath.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
-import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { fileIdentityMismatchError, inspectFileIdentitySync } from "./strict-file-identity.js";
 const WINDOWS = process.platform === "win32";
 function effectiveOwner() {
     // Windows mode/uid fields do not describe ACL authority. The supplied root's
@@ -72,11 +71,6 @@ function assertCanonicalRoot(entry) {
         throw new FsSafeError("path-mismatch", "temp workspace root ancestry changed");
     }
 }
-function identityMismatch() {
-    const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
-    recordFileObservationFailure(error, "identity");
-    throw error;
-}
 function inspectSnapshotIdentity(entry) {
     const expected = entry.numericIdentity;
     if (!expected) {
@@ -87,21 +81,21 @@ function inspectSnapshotIdentity(entry) {
     const devKnown = Number.isSafeInteger(stat.dev) && stat.dev >= 0 && (!WINDOWS || stat.dev !== 0);
     if (devKnown) {
         if (stat.dev !== expected.dev)
-            identityMismatch();
+            throw fileIdentityMismatchError();
     }
     else if (WINDOWS)
         requiresExactRetry = true;
     else
-        identityMismatch();
+        throw fileIdentityMismatchError();
     const inoKnown = Number.isSafeInteger(stat.ino) && stat.ino >= 0 && (!WINDOWS || stat.ino !== 0);
     if (inoKnown) {
         if (stat.ino !== expected.ino)
-            identityMismatch();
+            throw fileIdentityMismatchError();
     }
     else if (WINDOWS)
         requiresExactRetry = true;
     else
-        identityMismatch();
+        throw fileIdentityMismatchError();
     if (!requiresExactRetry)
         return stat;
     // Read exact identity only once. The strict helper may re-check this constant
@@ -157,7 +151,7 @@ function canonicalAncestry(root) {
 }
 function exactIdentityMatches(current, expected) {
     if (current.dev !== expected.dev || current.ino !== expected.ino)
-        identityMismatch();
+        throw fileIdentityMismatchError();
 }
 function associateTempWorkspaceRoot(entry, ownerUid, descriptorFd) {
     const stat = inspectTempWorkspaceDescriptorIdentitySync(descriptorFd, entry.identity, entry.numericIdentity);

package/dist/temp-workspace-child-admission.js

@@ -2,8 +2,7 @@ import fsSync, {} from "node:fs";
 import { inspectDirectoryIdentitySync, observeDirectoryIdentitySync } from "./directory-guard.js";
 import { pinNodeDirectoryForMode, pinNodeDirectoryForModeSync } from "./directory-mode-node.js";
 import { FsSafeError } from "./errors.js";
-import { recordFileObservationFailure } from "./file-observation.js";
-import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { fileIdentityMismatchError, inspectFileIdentitySync } from "./strict-file-identity.js";
 export const TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY = process.platform === "linux" || process.platform === "darwin";
 export function projectTempWorkspaceNumericIdentity(identity) {
     const dev = Number(identity.dev);
@@ -14,15 +13,10 @@ export function projectTempWorkspaceNumericIdentity(identity) {
     }
     return Object.freeze({ dev, ino });
 }
-function identityMismatch() {
-    const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
-    recordFileObservationFailure(error, "identity");
-    throw error;
-}
 function inspectNumericIdentity(current, expected) {
     if (!Number.isSafeInteger(current.dev) || current.dev < 0 || current.dev !== expected.dev ||
         !Number.isSafeInteger(current.ino) || current.ino < 0 || current.ino !== expected.ino) {
-        identityMismatch();
+        throw fileIdentityMismatchError();
     }
     return current;
 }

package/dist/temp-workspace-descriptor.js

@@ -1,7 +1,6 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
-import { nodeDirectorySearchOnlyFlags } from "./directory-mode-node.js";
-import { assertOwnedDirectory } from "./directory-mode-owner.js";
+import { nodeDirectorySearchOnlyFlags, assertOwnedDirectory } from "./directory-mode-node.js";
 import { FsSafeError } from "./errors.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";

package/dist/test-hooks.d.ts

@@ -25,7 +25,7 @@ export type FsSafeTestHooks = {
     beforeTempWorkspaceNativeRemovalSync?: (quarantinePath: string) => void;
     beforeTrashMove?: (targetPath: string, destPath: string) => void;
     afterPublishTargetCreated?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;
-    beforePublishDirectorySync?: (method: "hardlink" | "exclusive-copy" | "rename-noreplace", targetPath: string, identity: FileIdentityStat) => Promise<void> | void;
+    beforePublishDirectorySync?: NonNullable<FsSafeTestHooks["afterPublishTargetCreated"]>;
 };
 export declare function getFsSafeTestHooks(): FsSafeTestHooks | undefined;
 export declare function __setFsSafeTestHooksForTest(hooks?: FsSafeTestHooks): void;

package/dist/windows-owner.d.ts

@@ -1,9 +1,9 @@
-import { type PermissionCommandFailure } from "./permission-exec.js";
+import { type PermissionFailureFields } from "./permission-exec.js";
 export type WindowsOwnerExec = (command: string, args: string[]) => Promise<{
     stdout: string;
     stderr: string;
 }>;
-export type WindowsOwnerSummary = {
+export type WindowsOwnerSummary = Omit<PermissionFailureFields & {
     sid?: string;
     currentUserSid?: string;
     daclPresent?: boolean;
@@ -11,10 +11,7 @@ export type WindowsOwnerSummary = {
     aclError?: string;
     remote?: boolean;
     trusted?: boolean;
-    error?: string;
-    errorDetail?: PermissionCommandFailure;
-    errorCause?: unknown;
-};
+}, never>;
 export type WindowsOwnerAce = {
     sid: string;
     mask: number;

package/dist/windows-security-bridge.cs

@@ -2,8 +2,6 @@
 // descriptor never passes through CommonSecurityDescriptor's ACE normalization.
 using System;
 using System.Collections.Generic;
-using System.ComponentModel;
-using System.IO;
 using System.Runtime.InteropServices;
 using System.Security.AccessControl;
 using System.Security.Principal;

package/dist/windows-security-command.js

@@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url";
 import { FsSafeError } from "./errors.js";
 import { DEFAULT_PERMISSION_EXEC_TIMEOUT_MS, PermissionCommandError } from "./permission-exec.js";
 import { resolveWindowsSystemCommand } from "./windows-command.js";
-import { parseWindowsSecurityCommandFacts } from "./windows-security-facts.js";
+import { parseWindowsSecurityCommandFacts, unverified } from "./windows-security-facts.js";
 const MAX_OUTPUT_BYTES = 1024 * 1024;
 const TERMINATION_GRACE_MS = 1_000;
 const FULL_IDENTITY = /^[0-9a-f]{16}:[0-9a-f]{32}$/;
@@ -50,9 +50,6 @@ function command(operation, params) {
         },
     };
 }
-function unverified(message, cause) {
-    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
-}
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }

package/dist/windows-security-facts.d.ts

@@ -1,4 +1,5 @@
 import type { NativeWindowsSecurityFacts } from "./native-binding.js";
+export declare function unverified(message: string, cause?: unknown): never;
 /** Raw reporting retains unknown flag bits; secure admission validates them below. */
 export declare function parseWindowsSecurityCommandFacts(value: unknown): NativeWindowsSecurityFacts;
 /** Native and command observations share the same fail-closed admission policy. */

package/dist/windows-security-facts.js

@@ -6,8 +6,8 @@ const WORLD_SIDS = new Set([
     "s-1-1-0", "s-1-5-11", "s-1-5-32-545", "s-1-5-7",
     "s-1-5-32-546", "s-1-5-4", "s-1-5-2",
 ]);
-function unverified(message) {
-    throw new FsSafeError("permission-unverified", message);
+export function unverified(message, cause) {
+    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
 }
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);

package/docs/archive.md

@@ -238,6 +238,8 @@ directory paths. For example, `./pkg//state\cache/value` is presented as
 `pkg/state/cache/value`, even with `stripComponents: 1`. Case and Unicode
 spelling are preserved. Local PAX `path`, GNU long-name, and supported ZIP
 Unicode Path names use the same canonicalization.
+A leading `~` is a literal archive entry name and is never expanded to the
+user's home directory during extraction, publication, or durability checks.
 Callbacks follow physical archive order, including ZIP names that look like
 integer object keys. The public ZIP loader's `files` object retains ordinary
 JavaScript object enumeration and mutation behavior.

package/docs/copy.md

@@ -74,6 +74,8 @@ Native Windows byte copies can store large zero-filled chunks as sparse ranges w
 
 The ReFS backend rejects files with alternate data streams and unsupported reparse-point types instead of silently losing their contents. Symbolic links and junctions are preserved.
 
+Failed ReFS clones attempt to remove their partial output through the retained directory handles. On Windows versions that reject the ignore-readonly deletion flag, clone rollback retries without that flag so ordinary output can be removed. It never clears readonly attributes: readonly output can remain, and the original clone error includes the cleanup failure. Other processes retaining output handles can delay deletion beyond settlement; a failed call does not guarantee an absent destination.
+
 XFS and ZFS preserve regular-file and directory modes, timestamps, extended attributes, and ACLs. They reject special files, symlink extended attributes, non-UTF-8 names, and directory nesting deeper than 128 levels. Hardlinked source files become independent reflinked files. Portable byte copying preserves file contents, empty directories, modes where supported, file and directory timestamps, and literal symbolic links; it does not promise ownership, ACL, extended-attribute, alternate-stream, or sparse-layout preservation. On Windows, byte copying rejects unresolved symbolic links because Node does not expose their file/directory link type; resolved links keep their literal target and source type. POSIX dangling links are preserved. Choose a copying policy that meets the caller's metadata requirements; automatic copying can select either path.
 
 `readCloneFileMetadata(files)` asynchronously reads APFS data-stream identities and file metadata in one native batch. Results correspond to input order; missing or unsupported entries return `undefined`. The returned `CloneFileMetadata` includes clone ID, device/inode, size, mode, ownership, and timestamps. These are point-in-time observations, not authorization or proof that later reads remain unchanged. Consumers such as Git index adapters must validate their own content and timestamp invariants. The reader does not follow leaf symbolic links.

package/docs/file-store.md

@@ -101,6 +101,11 @@ such as `internal space/a b.txt` are accepted. On POSIX, colons elsewhere, such
 as the timestamp in `logs/2026-08-02T10:30:00Z.log`, remain lexically valid;
 Windows rejects that spelling as stream syntax.
 
+Keys such as `~` and `~/state.json` name literal entries inside the store; they
+do not expand the user's home directory. Reads, writes, removal, and pruning
+all use that literal identity. The `Root` returned by `root()` retains its own
+home-expansion behavior.
+
 Validation retains each method's operation order. Async reads, `exists`, and
 `remove` open the root first: if the root is missing, strict methods report
 `not-found` and `readTextIfExists` / `readJsonIfExists` return `null`, even for an

package/docs/guest.md

@@ -119,7 +119,13 @@ publication failure preserves the existing destination and source link; ordinary
 failure cleanup removes the staging directory.
 
 Cross-device directory moves build a copy manifest and check it during source
-cleanup. Source changes can leave the published destination and some or all
+cleanup. Directory creation keeps the source mode subject to the guest's umask;
+mode `000` is not replaced with a default. A top-level mode-000 directory uses
+owner-only staging until publication, then restores zero through its retained
+descriptor. Reading a mode-000 source still requires sufficient OS privileges;
+the guest does not change source permissions to gain access. A permission error
+after publication preserves the source and published copy for reconciliation.
+Source changes can leave the published destination and some or all
 of the source. Regular-file and symlink move fallbacks unlink the source
 pathname after publication; they do not perform the directory manifest's
 identity checks. Directory cleanup also has check-to-unlink race windows.

package/docs/native-helper.md

@@ -107,6 +107,12 @@ normalization, and the decision to fall back.
 - macOS 15.4 and newer prefer `O_RESOLVE_BENEATH`; older kernels resolve components with `O_NOFOLLOW` and restart in-root symlinks from the pinned root descriptor. Both routes use an `F_GETPATH` post-open escape detector and report `best-effort` because directory rename races are not atomic with that check. Direct-child no-replace renames borrow already-retained parents without another `F_GETPATH`; deeper paths retain the guarded reopen. Publication uses `renameat` for replacement and `renameatx_np(RENAME_EXCL)` for no-replace; owned-tree cleanup uses descriptor-relative `openat`/`unlinkat`.
 - Windows uses handle-relative `NtCreateFile`, rejects reparse points during root-bounded traversal, and uses `FileRenameInfoEx` with replacement selected explicitly by the TypeScript policy layer. The dedicated retained-directory `renameNoReplaceWithIdentity` primitive compares its required exact source receipt with the handle opened for rename before mutation. Its internal mismatch status is normalized to public `path-mismatch`; the legacy four-argument `renameNoReplace` export and its other callers are unchanged. Owned trees are deleted through exact opened handles with `FileDispositionInfoEx`; symlink/reparse entries in owned trees are removed as leaves and never traversed. Descriptors crossing N-API are converted only by the host executable's paired `uv_get_osfhandle` and `uv_open_osfhandle` exports. A runtime without both exports is unsupported for these native operations; the binding never guesses a raw HANDLE or uses a foreign CRT descriptor table. Descriptor-producing operations also require that same host's synchronous libuv close and request-management APIs before exporting an owned descriptor.
 
+Linux root lookups reject negative descriptor sentinels before borrowing a handle or resolving a relative path; they never substitute the process working directory for an admitted root. Public Root operations already supply retained, admitted handles.
+
+On Linux and macOS, native asynchronous file-copy admission rejects negative source and parent descriptors before creating a stage, preserving source-before-parent error ordering. Callers must keep nonnegative source and parent descriptors open until the operation settles.
+
+Low-level Unix query, hash, copy, clone, staging, and owned-tree cleanup calls also reject negative descriptors before using them, preserving each operation's path-validation, cancellation, and cleanup order. Descriptor-relative mutations never accept a working-directory sentinel as a retained capability. On modern macOS, beneath opens reject negative roots with `EBADF` before calling `openat`, rather than returning `EIO` after an OS failure or working-directory operation. This check does not establish the validity of arbitrary nonnegative integers: callers must supply live descriptors and retain them until synchronous calls return or asynchronous operations settle.
+
 `replaceDirectoryAtomic()` requires `renameNoReplaceWithIdentity` before it
 creates a missing target parent. On POSIX the dedicated entry point keeps the
 existing pre-dispatch exact receipt fence but dispatches direct-child names

package/docs/root.md

@@ -24,7 +24,7 @@ type RootDefaults = {
   denyMutations?: DenyMutationPolicy; // absolute paths/prefixes mutation methods may not change
   maxBytes?: number;               // refuse reads larger than this many bytes; defaults to 16 MiB
   mkdir?: boolean;                 // create missing parent dirs on write/openWritable/append; default true
-  mode?: number;                   // file mode applied to new writes; per-call override available
+  mode?: number;                   // requested file mode; per-call override available
   nonBlockingRead?: boolean;       // compatibility hint; safe opens are already nonblocking where supported
   renameIdentity?: "strict" | "verify-content-with-lock"; // default "strict"
   symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root"; // read policy
@@ -117,6 +117,10 @@ created through a directory symlink or Windows junction. An absolute path
 outside the root is still rejected. On Windows, alternate casing is accepted
 only when the differently cased Root prefix has the Root's exact directory
 identity; the operation then continues under the trusted Root spelling.
+Absolute paths keep literal `~` components: `readAbsolute("/srv/root/~/file")`
+reads that entry under the root, without expanding the user's home directory.
+Relative `~/file` inputs still expand the home directory and must remain inside
+the Root; use `./~/file` for a literal relative `~` directory.
 
 ### Writes
 
@@ -153,6 +157,11 @@ await fs.create("private-data/credential", "synthetic credential", { private: tr
 
 `write`, `create`, `append`, `writeJson`, and `createJson` accept `mode?: number`; use `0o600` for credentials and other private state. `writeJson` also accepts the same options as `JSON.stringify` plus `trailingNewline?: boolean` (defaults `true` so the file ends in `\n`).
 
+For `append` and `openWritable`, `mode` only affects new-file creation: POSIX
+permissions remain subject to the process umask. These methods do not chmod
+existing files. Replacement and create-only writes apply their final mode
+through the retained descriptor; see [Writing](writing.md#write-options).
+
 Buffered `create` and `createJson` also accept `atomic?: boolean`. With `true`,
 complete content is staged before exclusive publication even in native-off mode;
 the fallback requires hardlinks. Omitted or `false` keeps the existing buffered

package/docs/secret-file.md

@@ -113,6 +113,10 @@ If an already validated descriptor fails while reading, both readers throw an
 operational `FsSafeError` with `code: "read-failed"`; inspect `cause` for the
 underlying Node filesystem code such as `EIO`.
 
+Caught `null` or `undefined` inspection and read failures are reported as
+structured errors with an `Error` cause carrying `"null"` or `"undefined"`,
+instead of an internal `TypeError` while inspecting the thrown value.
+
 A synchronous reader closes its descriptor once. A close failure preserves an
 earlier read or identity-validation error; after a successful read, the close
 failure is reported before trimming or rejecting empty content.
@@ -137,6 +141,11 @@ startWebhookVerifier(signingKey);
 
 Async. Creates the parent directory at `dirMode` (default `0o700`) if missing, writes content to a sibling temp file, finalizes `mode` (default `0o600`) through an owned descriptor after content writes, and atomically renames over the destination. Publication verification checks the final file identity and mode.
 
+Both secret writers capture top-level parameter values when called, before
+asynchronous filesystem preparation; a supplied byte buffer is captured by
+reference. A parameter getter throwing `null` or `undefined` rejects with that
+same value before filesystem inspection.
+
 On POSIX, both native and JavaScript writers verify actual `0o600` permission
 bits through the retained descriptor before writing content. A filesystem that
 reports successful chmod without enforcing those bits fails with
@@ -219,6 +228,15 @@ if anything already occupies the target path it throws
 `FsSafeError("secret-exists")` without modifying that entry. Use the distinct
 name when first-writer-wins is part of the credential protocol.
 
+Its `durable` option also accepts `"file"`, matching `Root.create()`. This
+requires every file `fsync` to succeed, including on `EPERM`, while parent-directory
+synchronization remains best effort. The default and boolean options retain their
+existing behavior. `writeSecretFileAtomic()` continues to accept boolean durability.
+
+Strict file synchronization preserves the existing publication strategy and
+identity-checked cleanup. A failed file flush before staged publication prevents
+publication; a failure after publication can leave the complete file present.
+
 Distinct leaves can share missing-parent creation without a `secret-exists`
 error. Concurrent creates at the same leaf still have exactly one winner;
 the loser receives `secret-exists` and leaves the winner's bytes intact.
@@ -235,6 +253,7 @@ try {
     rootDir: "/var/lib/app/credentials",
     filePath: "/var/lib/app/credentials/provider.refresh-token",
     content: refreshToken,
+    durable: "file",
   });
 } catch (error) {
   if (!(error instanceof FsSafeError) || error.code !== "secret-exists") throw error;

package/docs/sidecar-lock.md

@@ -267,6 +267,8 @@ Pass `lockRoot` to place sidecar create, read, verification, and removal behind
 an existing `Root` capability. `lockPath` must resolve inside that root.
 Identity-conditioned removal remains the only release and reclaim deletion
 path.
+Root mutation refusals during stale removal propagate unchanged, including
+`null`, `undefined`, and errors carrying `ENOENT`; they do not become missing-sidecar retries.
 
 Async Root-backed acquisition normalizes the target's parent without creating
 it, checking the retained Root before and after normalization. A deleted or

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

@@ -301,6 +301,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 });
@@ -522,6 +528,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.1",
+  "version": "0.19.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -169,13 +169,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.18.1",
-    "@openclaw/fs-safe-darwin-x64": "0.18.1",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.18.1",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.18.1",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.18.1",
-    "@openclaw/fs-safe-linux-x64-musl": "0.18.1",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.18.1",
+    "@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",
     "jszip": "^3.10.2"
   },
   "devDependencies": {

package/dist/directory-mode-owner.d.ts

@@ -1,20 +0,0 @@
-import type { BigIntStats, Stats } from "node:fs";
-export type DirectoryModeChecks = {
-    check?: () => void;
-    beforeChmod?: () => Promise<void>;
-};
-export type DirectoryModeOwner = {
-    verify(check?: () => void): Promise<void>;
-    apply(mode: number, checks?: DirectoryModeChecks): Promise<void>;
-    close(): Promise<void>;
-};
-export declare function assertOwnedDirectory(expected: Stats | BigIntStats, actual: Stats | BigIntStats): void;
-/** Serializes use and close: even a queued path-based fd operation retains its descriptor. */
-export declare function ownDirectoryMode(params: {
-    inspect: () => Promise<number>;
-    chmod: (mode: number) => Promise<void>;
-    prepareChmod?: () => Promise<void>;
-    verifyChmod?: () => Promise<void>;
-    close: () => Promise<void>;
-    ignoreChmodError?: boolean;
-}): DirectoryModeOwner;

package/dist/directory-mode-owner.js

@@ -1,78 +0,0 @@
-import { FsSafeError } from "./errors.js";
-import { sameFileIdentityForCleanup } from "./file-identity.js";
-export function assertOwnedDirectory(expected, actual) {
-    if (actual.isSymbolicLink() || !actual.isDirectory()) {
-        throw new FsSafeError("not-file", "directory mode target must be a real directory");
-    }
-    if (!sameFileIdentityForCleanup(expected, actual)) {
-        throw new FsSafeError("path-mismatch", "directory changed before its mode could be applied");
-    }
-}
-/** Serializes use and close: even a queued path-based fd operation retains its descriptor. */
-export function ownDirectoryMode(params) {
-    let pending = Promise.resolve();
-    let closing;
-    const enqueue = (run) => {
-        if (closing)
-            return Promise.reject(new FsSafeError("path-mismatch", "directory mode owner is closed"));
-        const operation = pending.then(run);
-        pending = operation.catch(() => undefined);
-        return operation;
-    };
-    return {
-        verify: (check) => enqueue(async () => {
-            check?.();
-            await params.inspect();
-            check?.();
-        }),
-        apply: (mode, checks = {}) => enqueue(async () => {
-            // inspect() reports permission bits only; chmod ignores file-type bits,
-            // so tolerate raw stat modes (e.g. S_IFDIR | 0o755) by masking up front.
-            mode &= 0o7777;
-            checks.check?.();
-            const currentMode = await params.inspect();
-            checks.check?.();
-            if (currentMode === mode && !checks.beforeChmod && !checks.check)
-                return;
-            if (currentMode !== mode) {
-                await params.prepareChmod?.();
-                checks.check?.();
-            }
-            await checks.beforeChmod?.();
-            checks.check?.();
-            // Hooks/ancestor checks can yield; recheck the original named association.
-            await params.inspect();
-            checks.check?.();
-            let dispatchDeadlineFailure;
-            if (currentMode !== mode) {
-                checks.check?.();
-                try {
-                    await params.chmod(mode);
-                }
-                catch (error) {
-                    if (!params.ignoreChmodError)
-                        throw error;
-                }
-                // Expiry cannot release the fd while post-dispatch verification is pending.
-                try {
-                    checks.check?.();
-                }
-                catch (error) {
-                    dispatchDeadlineFailure = { error };
-                }
-                await params.verifyChmod?.();
-            }
-            const finalMode = await params.inspect();
-            if (dispatchDeadlineFailure)
-                throw dispatchDeadlineFailure.error;
-            checks.check?.();
-            if (!params.ignoreChmodError && finalMode !== mode) {
-                throw new FsSafeError("path-mismatch", "directory final mode could not be verified");
-            }
-        }),
-        close() {
-            closing ??= pending.then(params.close);
-            return closing;
-        },
-    };
-}