@openclaw/fs-safe 0.5.1 → 0.5.2

package/docs/test-hooks.md

@@ -37,6 +37,7 @@ type FsSafeTestHooks = {
   beforeRootFallbackMutation?: (operation: "mkdir" | "move" | "remove", targetPath: string) => Promise<void> | void;
   afterPinnedWriteFallbackRename?: (targetPath: string) => Promise<void> | void;
   beforeSiblingTempWrite?: (tempPath: string) => Promise<void> | void;
+  beforeSidecarLockSnapshotOpen?: (lockPath: string) => Promise<void> | void;
   beforeTrashMove?: (targetPath: string, destPath: string) => void;
   afterPublishTargetCreated?: (method, targetPath, identity) => Promise<void> | void;
   beforePublishDirectorySync?: (method, targetPath, identity) => Promise<void> | void;
@@ -54,6 +55,7 @@ type FsSafeTestHooks = {
 | `beforeRootFallbackMutation` | A guarded JS root fallback is about to mkdir, move, or remove. |
 | `afterPinnedWriteFallbackRename` | A fallback rename committed and post-commit identity checks have not run yet. |
 | `beforeSiblingTempWrite` | A sibling temp file exists and its writer is about to run. |
+| `beforeSidecarLockSnapshotOpen` | A sidecar lock was inspected and is about to be opened for a bounded snapshot read. |
 | `beforeTrashMove` | Trash handling is about to move the target. |
 | `afterPublishTargetCreated` | Exclusive publication created its target and final fences have not run yet. |
 | `beforePublishDirectorySync` | Publication verified the target and is about to sync its parent directory. |

package/docs/types.md

@@ -2,6 +2,8 @@
 
 The types most callers reach for. Shared data shapes are exported from `@openclaw/fs-safe/types`; method-specific option/result types live next to their subpath.
 
+For atomic replacement, `ReplaceFileAtomicFileSystem` and `ReplaceFileAtomicSyncFileSystem` are exported from `@openclaw/fs-safe/atomic`. Async adapters use `chmod()` on the `FileHandle` returned by their required `open()` operation. The synchronous type adds optional `fchmodSync(fd, mode)`; custom sync adapters that explicitly request `mode` or `preserveExistingMode` must implement it. See [Atomic writes](atomic.md#test-injection).
+
 ```ts
 import type {
   BasePathOptions,
@@ -16,15 +18,24 @@ import type {
 
 ```ts
 type PathStat = {
-  kind: "file" | "directory" | "symlink" | "fifo" | "socket" | "blockDevice" | "characterDevice" | "unknown";
-  size: number;       // bytes
-  mtimeMs: number;    // milliseconds since epoch
-  mode: number;       // POSIX mode bits
-  nlink: number;      // hardlink count
+  dev: number;
+  gid: number;
+  ino: number;
+  isDirectory: boolean;
+  isFile: boolean;
+  isSymbolicLink: boolean;
+  mode: number;
+  mtimeMs: number;
+  nlink: number;
+  size: number;
+  uid: number;
 };
 ```
 
-The shape returned by `Root.stat()`. A trimmed view of `node:fs.Stats` — only the fields the boundary cares about. Use `kind` instead of inspecting the various `is*` methods on a Node `Stats` object; it covers every case in one switchable string.
+The shape returned by `Root.stat()`. It is a serializable view of the identity,
+ownership, mode, size, timestamp, link count, and three file-kind facts the
+boundary uses. Unlike Node's `Stats`, `isFile`, `isDirectory`, and
+`isSymbolicLink` are boolean fields rather than methods.
 
 ## `DirEntry`
 
@@ -34,21 +45,23 @@ type DirEntry = PathStat & {
 };
 ```
 
-Returned by `Root.list(rel, { withFileTypes: true })`. Includes the same `kind`/`size`/etc as `PathStat`, plus the entry's `name`.
+Returned by `Root.list(rel, { withFileTypes: true })`. Includes every
+`PathStat` field plus the entry's `name`.
 
 ## `BasePathOptions`
 
 ```ts
 type BasePathOptions = {
-  fastPathMode?: FastPathMode;
+  rootDir: string;
+  relativePath: string;
 };
 
 type FastPathMode = "auto" | "never" | "require";
 ```
 
-Options shared by helpers that can take a "fast path" (use cheaper syscalls when the input is already absolute and clearly inside scope). The default is `"auto"` — let the helper pick. Force `"never"` in tests if you want to exercise the slow path. Force `"require"` if you need to assert that the fast path is taken (the helper throws if it can't).
-
-Most callers don't need to touch this.
+`BasePathOptions` is the shared root-plus-relative-path record. `FastPathMode`
+is retained as a public compatibility union; no current exported options record
+consumes it, so setting a fast-path policy is not part of the current API.
 
 ## `SafeEncoding`
 
@@ -83,13 +96,16 @@ type ReadResult = {
 ## `RootDefaults` / `RootOptions`
 
 ```ts
+type RenameIdentityPolicy = "strict" | "verify-content-with-lock";
+
 type RootDefaults = {
   denyMutations?: DenyMutationPolicy;
   hardlinks?: "reject" | "allow";
   maxBytes?: number;
-  mkdir?: boolean;
+  mkdir?: boolean; // default true for mutation methods
   mode?: number;
   nonBlockingRead?: boolean;
+  renameIdentity?: RenameIdentityPolicy;
   symlinks?: "reject" | "follow-within-root";
 };
 
@@ -110,7 +126,7 @@ type RootOptions = {
 
 ```ts
 type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
-type RootWriteOptions = Pick<RootDefaults, "denyMutations" | "mkdir" | "mode"> & {
+type RootWriteOptions = Pick<RootDefaults, "denyMutations" | "mkdir" | "mode" | "renameIdentity"> & {
   encoding?: BufferEncoding;
   overwrite?: boolean;
 };
@@ -155,13 +171,14 @@ type FsSafeErrorCode =
   | "helper-unavailable" | "insecure-permissions" | "invalid-path"
   | "not-empty" | "not-file" | "not-found" | "not-owned"
   | "not-removable" | "outside-workspace" | "path-alias"
-  | "path-mismatch" | "permission-unverified" | "symlink"
+  | "path-mismatch" | "permission-unverified" | "secret-exists"
+  | "store-reentrant-update" | "symlink"
   | "timeout" | "too-large" | "unsupported-platform";
 ```
 
 Closed union you switch on. See the [Errors](errors.md) reference for what each one means.
 
-`FsSafeError.category` is `"policy"` for unsafe input/target-state failures and `"operational"` for environment/runtime failures.
+`FsSafeError.category` is `"policy"` for unsafe input or target state rejected by a safety policy and `"operational"` for routine filesystem outcomes or environment/runtime failures. `not-found`, `not-empty`, and `not-removable` are operational.
 
 ## See also
 

package/docs/writing.md

@@ -1,6 +1,11 @@
 # Writing
 
-The `Root` handle exposes a tight set of write verbs. Each one is atomic at the destination — no half-written intermediate state — and goes through the same boundary checks as reads.
+The `Root` handle exposes a tight set of mutation verbs. Replacement writes
+(`write`, `create`, `writeJson`, `createJson`, and `copyIn`) publish with a
+sibling-temp commit so no half-written replacement appears at the destination.
+`append` and `openWritable` intentionally modify an opened file in place;
+`move`, `remove`, and `mkdir` mutate directory entries rather than file bytes.
+Each verb applies the boundary checks appropriate to its operation.
 
 ```ts
 await fs.write("state.json", body);
@@ -13,16 +18,20 @@ await fs.remove("logs/yesterday.log");
 await fs.mkdir("snapshots/2026/05");
 ```
 
-## What every write does
+## What replacement writes do
 
 1. Resolve the relative target against the canonical root and reject anything that escapes (`outside-workspace`).
-2. If `mkdir: true`, create missing parent directories with the parent fd pinned.
-3. Pin or guard the parent directory for the selected mechanism. Native operations use a parent fd; guarded JavaScript verifies directory identity before and after mutation. Linux beneath opens are kernel-atomic, while macOS, Windows, and JavaScript routes retain the best-effort race boundaries in the [security model](security-model.md#containment-guarantees-by-platform).
+2. If `mkdir: true`, create missing parent directories relative to a pinned parent fd in the native path, or with per-component identity guards in the JavaScript fallback.
+3. Pin or guard the parent directory for the selected mechanism. Native operations use a parent fd; guarded JavaScript verifies directory identity before and after mutation. The JavaScript check cannot make the intervening pathname syscall atomic, so a same-privilege peer that can replace the parent may cause an out-of-root side effect before detection. Use native `require` mode for that threat model; see the [security model](security-model.md#symlinks-write-side).
 4. Write data to a sibling temp file in the same directory.
 5. Atomically rename the temp file over the destination.
 6. Stat the resulting fd and verify identity.
 
-A failure at any point either leaves the destination at its previous contents or surfaces an `FsSafeError` — never a partially-written file at the destination path.
+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
+write in place, or to lower-level atomic helpers when their explicitly
+non-atomic permission-error copy fallback is enabled.
 
 ## Denying mutations
 
@@ -53,7 +62,7 @@ await fs.write("state/last-run.json", JSON.stringify(run));
 await fs.write("notes/today.txt", "hello\n", { encoding: "utf8" });
 ```
 
-`data` accepts `string | Buffer`. `options` are `{ denyMutations?: DenyMutationPolicy; encoding?: BufferEncoding; mkdir?: boolean; mode?: number; overwrite?: boolean }`. `mode` sets the file's POSIX mode; if omitted, falls back to the `mode` from `RootDefaults` and then to umask. `overwrite` defaults to `true`; set it to `false` for the same no-clobber behavior as `create()`.
+`data` accepts `string | Buffer`. `options` are `{ denyMutations?: DenyMutationPolicy; encoding?: BufferEncoding; mkdir?: boolean; mode?: number; overwrite?: boolean; renameIdentity?: RenameIdentityPolicy }`. `mode` sets the file's POSIX mode. If neither the call nor `RootDefaults` supplies it, a replacement preserves the existing file mode and a new file uses `0o600`. `mkdir` and `overwrite` both default to `true`; set `overwrite: false` for the same no-clobber behavior as `create()`.
 
 ### `fs.create(rel, data, options?)`
 
@@ -79,10 +88,7 @@ await fs.writeJson("compact.json", state, { trailingNewline: false });
 Options:
 
 ```ts
-type RootWriteJsonOptions = {
-  encoding?: BufferEncoding;
-  mkdir?: boolean;
-  mode?: number;
+type RootWriteJsonOptions = RootWriteOptions & {
   replacer?: (this: any, key: string, value: any) => any | (number | string)[];
   space?: number | string;
   trailingNewline?: boolean; // default true
@@ -112,7 +118,9 @@ await fs.copyIn("inbox/upload.bin", "/tmp/incoming.bin", {
 });
 ```
 
-Options: `{ encoding?, mkdir?, maxBytes?, sourceHardlinks? }`. Use `sourceHardlinks: "reject"` to refuse if the source itself is a hardlinked alias.
+Options are `{ denyMutations?, maxBytes?, mkdir?, mode?, sourceHardlinks? }`.
+Use `sourceHardlinks: "reject"` to refuse if the source itself is a hardlinked
+alias. There is no encoding option: copying preserves source bytes.
 
 ### `fs.move(from, to, options?)`
 
@@ -167,7 +175,12 @@ try {
 }
 ```
 
-Options: `{ mkdir?, mode?, writeMode? }`, where `writeMode` is `"replace"` (default), `"append"`, or `"update"`. `replace` truncates existing files; `update` keeps existing contents. Streaming writes go directly to the destination — there is no atomic-rename step. If you need both streaming and atomicity, write to a sibling temp yourself and rename when done; the [`atomic`](atomic.md) helpers can do this for you.
+Options are `{ denyMutations?, mkdir?, mode?, writeMode? }`, where `writeMode`
+is `"replace"` (default), `"append"`, or `"update"`. `replace` truncates existing
+files; `update` keeps existing contents. Streaming writes go directly to the
+destination — there is no atomic-rename step. If you need both streaming and
+atomicity, write to a sibling temp yourself and rename when done; the
+[`atomic`](atomic.md) helpers can do this for you.
 
 ## Write defaults vs per-call options
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -29,6 +29,7 @@
     "dist/**/*.d.ts.map",
     "dist/native/**/*.node",
     "docs/**/*.md",
+    "docs/assets/readme-banner.jpg",
     "README.md",
     "CHANGELOG.md",
     "SECURITY.md",
@@ -129,11 +130,13 @@
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:security": "vitest run test/fs-safe.test.ts test/read-boundary-bypass.test.ts test/write-boundary-bypass.test.ts test/additional-boundary-bypass.test.ts test/adversarial-boundary-payloads.test.ts",
-    "check": "pnpm lint:file-size && pnpm lint:fs-boundary && pnpm build && pnpm test && node scripts/check-pack.mjs",
+    "check": "pnpm lint:file-size && pnpm lint:fs-boundary && pnpm build && pnpm docs:check && pnpm test && node scripts/check-pack.mjs",
+    "docs:check": "node scripts/check-doc-examples.mjs",
     "docs:site": "node scripts/build-docs-site.mjs",
     "native:build": "pnpm --filter @openclaw/fs-safe-native-build build",
     "native:test": "cargo test --manifest-path native/Cargo.toml",
     "pack:check": "pnpm build && node scripts/check-pack.mjs",
+    "public-api:update": "pnpm build && node scripts/check-pack.mjs --update-public-api",
     "package:smoke": "node scripts/check-release-packages.mjs --allow-host-only --output release-artifacts",
     "check:changed": "pnpm run check",
     "release:notes": "node scripts/release-notes.mjs",
@@ -148,9 +151,10 @@
     "tar": "7.5.22"
   },
   "devDependencies": {
-    "@napi-rs/cli": "3.8.1",
+    "@napi-rs/cli": "3.8.2",
     "@types/node": "^26.1.2",
     "@vitest/coverage-v8": "4.1.10",
+    "sigstore": "5.0.0",
     "typescript": "^7.0.2",
     "vite": "8.2.0",
     "vitest": "^4.1.10"

package/dist/archive-file-io.d.ts

@@ -1,9 +0,0 @@
-import type { FileHandle } from "node:fs/promises";
-import type { ExtractionDeadline } from "./archive-deadline.js";
-export declare function writeFileHandleFully(params: {
-    handle: FileHandle;
-    buffer: Buffer;
-    bytes: number;
-    deadline: ExtractionDeadline;
-}): Promise<void>;
-//# sourceMappingURL=archive-file-io.d.ts.map

package/dist/archive-file-io.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"archive-file-io.d.ts","sourceRoot":"","sources":["../src/archive-file-io.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAEhE,wBAAsB,oBAAoB,CAAC,MAAM,EAAE;IACjD,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,kBAAkB,CAAC;CAC9B,GAAG,OAAO,CAAC,IAAI,CAAC,CAchB"}

package/dist/archive-file-io.js

@@ -1,11 +0,0 @@
-export async function writeFileHandleFully(params) {
-    let offset = 0;
-    while (offset < params.bytes) {
-        params.deadline.check();
-        const { bytesWritten } = await params.handle.write(params.buffer, offset, params.bytes - offset);
-        if (bytesWritten <= 0) {
-            throw new Error("archive staging write made no progress");
-        }
-        offset += bytesWritten;
-    }
-}

package/dist/file-store-source.d.ts

@@ -1,5 +0,0 @@
-export declare function readFileStoreCopySource(params: {
-    sourcePath: string;
-    maxBytes?: number;
-}): Promise<Buffer>;
-//# sourceMappingURL=file-store-source.d.ts.map

package/dist/file-store-source.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"file-store-source.d.ts","sourceRoot":"","sources":["../src/file-store-source.ts"],"names":[],"mappings":"AAIA,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyBlB"}

package/dist/file-store-source.js

@@ -1,30 +0,0 @@
-import fs from "node:fs/promises";
-import { FsSafeError } from "./errors.js";
-import { readRegularFile } from "./regular-file.js";
-export async function readFileStoreCopySource(params) {
-    const sourceStat = await fs.lstat(params.sourcePath);
-    if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
-        throw new FsSafeError("not-file", "source path is not a file");
-    }
-    if (params.maxBytes !== undefined && sourceStat.size > params.maxBytes) {
-        throw new FsSafeError("too-large", `file exceeds maximum size of ${params.maxBytes} bytes`);
-    }
-    try {
-        return (await readRegularFile({ filePath: params.sourcePath, maxBytes: params.maxBytes }))
-            .buffer;
-    }
-    catch (error) {
-        const message = error instanceof Error ? error.message : String(error);
-        if (message.includes("regular file") || message.includes("not a regular file")) {
-            throw new FsSafeError("not-file", "source path is not a file", {
-                cause: error instanceof Error ? error : undefined,
-            });
-        }
-        if (params.maxBytes !== undefined && message.includes(`exceeds ${params.maxBytes} bytes`)) {
-            throw new FsSafeError("too-large", `file exceeds maximum size of ${params.maxBytes} bytes`, {
-                cause: error instanceof Error ? error : undefined,
-            });
-        }
-        throw error;
-    }
-}

package/dist/file-url.d.ts

@@ -1,2 +0,0 @@
-export * from "./local-file-access.js";
-//# sourceMappingURL=file-url.d.ts.map

package/dist/file-url.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"file-url.d.ts","sourceRoot":"","sources":["../src/file-url.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC"}

package/dist/file-url.js

@@ -1 +0,0 @@
-export * from "./local-file-access.js";

package/dist/path-stat.d.ts

@@ -1,4 +0,0 @@
-import type { Stats } from "node:fs";
-import type { PathStat } from "./types.js";
-export declare function pathStatFromStats(stat: Stats): PathStat;
-//# sourceMappingURL=path-stat.d.ts.map

package/dist/path-stat.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"path-stat.d.ts","sourceRoot":"","sources":["../src/path-stat.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,KAAK,GAAG,QAAQ,CAcvD"}

package/dist/path-stat.js

@@ -1,15 +0,0 @@
-export function pathStatFromStats(stat) {
-    return {
-        dev: Number(stat.dev),
-        gid: Number(stat.gid),
-        ino: Number(stat.ino),
-        isDirectory: stat.isDirectory(),
-        isFile: stat.isFile(),
-        isSymbolicLink: stat.isSymbolicLink(),
-        mode: stat.mode,
-        mtimeMs: stat.mtimeMs,
-        nlink: stat.nlink,
-        size: stat.size,
-        uid: stat.uid,
-    };
-}

package/dist/windows-permissions-native.d.ts

@@ -1,9 +0,0 @@
-import type { PermissionCheck, SafeStatResult } from "./permissions.js";
-export declare function inspectWindowsPermissionsNative(params: {
-    targetPath: string;
-    stat: SafeStatResult;
-    effectiveIsDir: boolean;
-    effectiveMode: number | null;
-    bits: number | null;
-}): PermissionCheck | undefined;
-//# sourceMappingURL=windows-permissions-native.d.ts.map

package/dist/windows-permissions-native.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"windows-permissions-native.d.ts","sourceRoot":"","sources":["../src/windows-permissions-native.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAExE,wBAAgB,+BAA+B,CAAC,MAAM,EAAE;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,cAAc,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB,GAAG,eAAe,GAAG,SAAS,CA2B9B"}

package/dist/windows-permissions-native.js

@@ -1,31 +0,0 @@
-import { getNativeBinding } from "./native.js";
-export function inspectWindowsPermissionsNative(params) {
-    const native = getNativeBinding();
-    if (!native)
-        return undefined;
-    try {
-        const facts = native.readOwnerAndDacl(params.targetPath);
-        if (facts.fallbackRequired)
-            return undefined;
-        return {
-            ok: true,
-            isSymlink: params.stat.isSymlink,
-            isDir: params.effectiveIsDir,
-            mode: params.effectiveMode,
-            bits: params.bits,
-            source: "windows-acl",
-            worldWritable: facts.worldWritable,
-            groupWritable: facts.groupWritable,
-            worldReadable: facts.worldReadable,
-            groupReadable: facts.groupReadable,
-            ownerSid: facts.ownerSid,
-            ownerTrusted: facts.ownerClass !== "foreign",
-            aclSummary: `native owner=${facts.ownerClass} world=` +
-                `${facts.worldReadable ? "r" : "-"}${facts.worldWritable ? "w" : "-"} ` +
-                `group=${facts.groupReadable ? "r" : "-"}${facts.groupWritable ? "w" : "-"}`,
-        };
-    }
-    catch {
-        return undefined;
-    }
-}