@openclaw/fs-safe 0.4.6 → 0.5.0

package/docs/walk.md

@@ -67,7 +67,62 @@ type WalkDirectoryOptions = {
 
 Unreadable directories are skipped rather than throwing, but every skipped directory is recorded in `failedDirs`. This keeps the helper suitable for best-effort inventories while letting pruning jobs tell an incomplete scan from an empty one: a destructive reconcile that deletes state for paths missing from `entries` must first confirm `failedDirs` holds no real read failures, or a transient `EIO`/`EACCES` blip would be mistaken for mass deletion. Use a stricter root-bounded operation when every entry must be accounted for.
 
+## Root-bounded async iteration
+
+`Root.walk(rel, options)` is the root-bounded counterpart to these standalone
+inventory helpers. It yields `{ relativePath, kind, size }` incrementally and
+accepts `maxDepth`, `maxEntries`, `symlinkPolicy: "skip" |
+"follow-within-root"`, and an `AbortSignal`. The default budget behavior yields
+one `kind: "truncated"` marker and ends; pass `limitBehavior: "throw"` for a
+typed `FsSafeError("too-large")` instead.
+
+`entryFilter` is evaluated for each resolved file, directory, or other entry:
+
+```ts
+for await (const entry of capability.walk("", {
+  symlinkPolicy: "skip",
+  entryFilter: (entry) =>
+    entry.kind === "directory" && entry.relativePath === ".git"
+      ? "skip-subtree"
+      : "include",
+  onDirectoryError: "skip-and-report",
+})) {
+  if (entry.kind === "directory-error") {
+    console.warn("incomplete subtree", entry.relativePath, entry.error);
+    continue;
+  }
+  consume(entry);
+}
+```
+
+The result values are `"include"`, `"skip"`, and `"skip-subtree"`. Plain
+`"skip"` omits an entry but still descends when it is a directory;
+`"skip-subtree"` omits that directory and prunes its descendants. Returning
+`"skip-subtree"` for a non-directory is equivalent to `"skip"`.
+
+`onDirectoryError` defaults to `"throw"`, preserving the original fail-fast
+contract. `"skip-and-report"` yields a discriminated
+`{ kind: "directory-error", relativePath, size: 0, error }` marker for a
+directory that cannot be resolved or listed, then continues with its siblings.
+Every examined directory entry consumes `maxEntries` before filtering, so
+`"skip"` cannot turn the iterator into an unbounded traversal. Reporting and
+`"truncated"` markers describe already-reached state and do not authorize
+further descent.
+
+The pure-Node path validates every directory canonically inside the root,
+revalidates each listing through the normal `Root.list()` boundary, and tracks
+canonical directories to stop symlink cycles. It does not hold a descriptor
+for the entire tree, so it is not a process sandbox against a hostile peer that
+can continuously swap and restore directories. Each individual lookup retains
+the documented Node `Root` boundary checks.
+
+Unlike `walkDirectory()` and `walkDirectorySync()`, `Root.walk()` is
+root-bounded and reports failures inline because an async iterator has no final
+result summary. Its default remains to throw on unreadable or invalid
+directories.
+
 ## See also
 
 - [`fileStore`](file-store.md) — managed stores use bounded walking for pruning.
 - [Path scopes](path-scope.md) — boundary checks for known absolute paths.
+- [Migrating to 0.5](migrating-to-0.5.md) — adopting bounded pruning and partial-result handling.

package/docs/writing.md

@@ -17,7 +17,7 @@ await fs.mkdir("snapshots/2026/05");
 
 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. Open the parent directory by fd. Subsequent rename/unlink uses the parent fd, not the path string, so a parent-directory symlink swap mid-call cannot divert the write.
+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).
 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.
@@ -246,9 +246,9 @@ const fs = await root("/mnt/rclone-workspace", {
 await fs.write("state.json", body); // succeeds on rclone FUSE
 ```
 
-**How it works.** The full write runs under an exclusive per-target lock named `.fs-safe-write-<sha256>.lock` in the root. Keeping the lock in the already-canonical root avoids creating an unguarded lock path through a missing or raced target parent. The guarded Node fallback accepts the source-temp-to-destination inode mismatch only when the SHA-256 of the re-read bytes matches the SHA-256 of the bytes written. Subsequent path identity checks remain strict, so this mode requires an unchanged destination path to report stable identity. It deliberately bypasses the stricter fd-relative Python helper because that helper requires rename to preserve inode identity. The lock is released before the call returns.
+**How it works.** The full write runs under an exclusive per-target lock named `.fs-safe-write-<sha256>.lock` in the root. Keeping the lock in the already-canonical root avoids creating an unguarded lock path through a missing or raced target parent. The guarded Node fallback accepts the source-temp-to-destination inode mismatch only when the SHA-256 of the re-read bytes matches the SHA-256 of the bytes written. Subsequent path identity checks remain strict, so this mode requires an unchanged destination path to report stable identity. It deliberately stays on the guarded JavaScript path because content verification replaces the normal inode-preserving rename contract. The lock is released before the call returns.
 
-**Security note.** `verify-content-with-lock` proves that the bytes observed after rename match the requested write and prevents *cooperating* writers from interleaving. It does **not** prove that the destination still names the temp-file object, retain the Python helper's fd-relative parent pinning, or stop a same-UID process that ignores the advisory lock. Do not use this option on directories writable by untrusted same-UID processes. Strict identity verification remains the default.
+**Security note.** `verify-content-with-lock` proves that the bytes observed after rename match the requested write and prevents *cooperating* writers from interleaving. It does **not** prove that the destination still names the temp-file object, retain fd-relative parent pinning, or stop a same-UID process that ignores the advisory lock. Do not use this option on directories writable by untrusted same-UID processes. Strict identity verification remains the default.
 
 Lock recovery is fail-closed. If a process crashes and leaves the root-level `.fs-safe-write-<sha256>.lock`, a later write reports the stale lock instead of deleting it based on a host-local PID. Recover only under external authority that excludes every competing writer; see [File lock](sidecar-lock.md#stale-recovery-guarded-remove-if-unchanged).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -27,6 +27,7 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
+    "dist/native/**/*.node",
     "docs/**/*.md",
     "README.md",
     "CHANGELOG.md",
@@ -96,6 +97,10 @@
       "types": "./dist/atomic.d.ts",
       "default": "./dist/atomic.js"
     },
+    "./durability": {
+      "types": "./dist/durability.d.ts",
+      "default": "./dist/durability.js"
+    },
     "./archive": {
       "types": "./dist/archive.d.ts",
       "default": "./dist/archive.js"
@@ -116,6 +121,7 @@
   },
   "scripts": {
     "benchmark": "node scripts/benchmark.mjs",
+    "benchmark:publish": "pnpm build && node scripts/bench-publish.mjs",
     "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "lint:file-size": "node scripts/check-file-size.mjs",
     "lint:fs-boundary": "node scripts/check-fs-boundary-primitives.mjs",
@@ -125,7 +131,10 @@
     "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",
     "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",
+    "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",
     "test:changed": "pnpm run test",
@@ -136,9 +145,10 @@
   },
   "optionalDependencies": {
     "jszip": "^3.10.1",
-    "tar": "7.5.20"
+    "tar": "7.5.21"
   },
   "devDependencies": {
+    "@napi-rs/cli": "3.7.4",
     "@types/node": "^26.1.1",
     "@vitest/coverage-v8": "4.1.10",
     "typescript": "^7.0.2",

package/dist/pinned-helper.d.ts

@@ -1,9 +0,0 @@
-import type { DirEntry, PathStat } from "./types.js";
-import { isPinnedHelperUnavailable } from "./pinned-python.js";
-type HelperOperation = "stat" | "readdir" | "mkdirp" | "remove" | "rename";
-export { isPinnedHelperUnavailable };
-export declare function runPinnedHelper<T>(operation: HelperOperation, rootDir: string, payload: Record<string, unknown>): Promise<T>;
-export declare function helperStat(rootDir: string, relativePath: string): Promise<PathStat>;
-export declare function helperReaddir(rootDir: string, relativePath: string, withFileTypes: false): Promise<string[]>;
-export declare function helperReaddir(rootDir: string, relativePath: string, withFileTypes: true): Promise<DirEntry[]>;
-//# sourceMappingURL=pinned-helper.d.ts.map

package/dist/pinned-helper.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"pinned-helper.d.ts","sourceRoot":"","sources":["../src/pinned-helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACrD,OAAO,EACL,yBAAyB,EAG1B,MAAM,oBAAoB,CAAC;AAE5B,KAAK,eAAe,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE3E,OAAO,EAAE,yBAAyB,EAAE,CAAC;AAErC,wBAAsB,eAAe,CAAC,CAAC,EACrC,SAAS,EAAE,eAAe,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAOZ;AAED,wBAAsB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAEzF;AAED,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,KAAK,GACnB,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AACrB,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,IAAI,GAClB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC"}

package/dist/pinned-helper.js

@@ -1,19 +0,0 @@
-import { isPinnedHelperUnavailable, runPinnedPythonOperation, validatePinnedOperationPayload, } from "./pinned-python.js";
-export { isPinnedHelperUnavailable };
-export async function runPinnedHelper(operation, rootDir, payload) {
-    validatePinnedOperationPayload(payload);
-    return await runPinnedPythonOperation({
-        operation,
-        rootPath: rootDir,
-        payload,
-    });
-}
-export async function helperStat(rootDir, relativePath) {
-    return await runPinnedHelper("stat", rootDir, { relativePath });
-}
-export async function helperReaddir(rootDir, relativePath, withFileTypes) {
-    return await runPinnedHelper("readdir", rootDir, {
-        relativePath,
-        withFileTypes,
-    });
-}

package/dist/pinned-path.d.ts

@@ -1,7 +0,0 @@
-export declare function isPinnedPathHelperSpawnError(error: unknown): boolean;
-export declare function runPinnedPathHelper(params: {
-    operation: "mkdirp" | "remove";
-    rootPath: string;
-    relativePath: string;
-}): Promise<void>;
-//# sourceMappingURL=pinned-path.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"pinned-path.d.ts","sourceRoot":"","sources":["../src/pinned-path.ts"],"names":[],"mappings":"AAIA,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpE;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE;IAChD,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAahB"}

package/dist/pinned-path.js

@@ -1,21 +0,0 @@
-import { FsSafeError } from "./errors.js";
-import { canFallbackFromPythonError } from "./pinned-python-config.js";
-import { runPinnedHelper } from "./pinned-helper.js";
-export function isPinnedPathHelperSpawnError(error) {
-    return canFallbackFromPythonError(error);
-}
-export async function runPinnedPathHelper(params) {
-    try {
-        await runPinnedHelper(params.operation, params.rootPath, {
-            relativePath: params.relativePath,
-        });
-    }
-    catch (error) {
-        if (error instanceof FsSafeError) {
-            throw error;
-        }
-        throw new FsSafeError("helper-failed", "pinned path helper failed", {
-            cause: error instanceof Error ? error : undefined,
-        });
-    }
-}

package/dist/pinned-python-config.d.ts

@@ -1,9 +0,0 @@
-export type FsSafePythonMode = "auto" | "off" | "require";
-export type FsSafePythonConfig = {
-    mode: FsSafePythonMode;
-    pythonPath?: string;
-};
-export declare function configureFsSafePython(config: Partial<FsSafePythonConfig>): void;
-export declare function getFsSafePythonConfig(): FsSafePythonConfig;
-export declare function canFallbackFromPythonError(error: unknown): boolean;
-//# sourceMappingURL=pinned-python-config.d.ts.map

package/dist/pinned-python-config.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"pinned-python-config.d.ts","sourceRoot":"","sources":["../src/pinned-python-config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;AAE1D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,IAAI,EAAE,gBAAgB,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAqBF,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAE/E;AAED,wBAAgB,qBAAqB,IAAI,kBAAkB,CAc1D;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMlE"}

package/dist/pinned-python-config.js

@@ -1,38 +0,0 @@
-let overrideConfig = {};
-function parseMode(value) {
-    if (!value) {
-        return undefined;
-    }
-    const normalized = value.trim().toLowerCase();
-    if (normalized === "0" || normalized === "false" || normalized === "off" || normalized === "never") {
-        return "off";
-    }
-    if (normalized === "1" || normalized === "true" || normalized === "on" || normalized === "auto") {
-        return "auto";
-    }
-    if (normalized === "required" || normalized === "require") {
-        return "require";
-    }
-    return undefined;
-}
-export function configureFsSafePython(config) {
-    overrideConfig = { ...overrideConfig, ...config };
-}
-export function getFsSafePythonConfig() {
-    return {
-        mode: overrideConfig.mode ??
-            parseMode(process.env.FS_SAFE_PYTHON_MODE) ??
-            parseMode(process.env.OPENCLAW_FS_SAFE_PYTHON_MODE) ??
-            "auto",
-        pythonPath: overrideConfig.pythonPath ??
-            process.env.FS_SAFE_PYTHON ??
-            process.env.OPENCLAW_FS_SAFE_PYTHON ??
-            process.env.OPENCLAW_PINNED_PYTHON ??
-            process.env.OPENCLAW_PINNED_WRITE_PYTHON,
-    };
-}
-export function canFallbackFromPythonError(error) {
-    const code = error instanceof Error && "code" in error ? error.code : undefined;
-    return (getFsSafePythonConfig().mode !== "require" &&
-        (code === "helper-unavailable" || code === "unsupported-platform"));
-}

package/dist/pinned-python.d.ts

@@ -1,12 +0,0 @@
-type PinnedPythonOperation = "copy" | "stat" | "readdir" | "mkdirp" | "remove" | "rename" | "write";
-export declare function __resetPinnedPythonWorkerForTest(): void;
-export declare function runPinnedPythonOperation<T>(params: {
-    operation: PinnedPythonOperation;
-    rootPath: string;
-    payload: Record<string, unknown>;
-}): Promise<T>;
-export declare function assertPinnedPythonOperationAvailable(): void;
-export declare function validatePinnedOperationPayload(payload: Record<string, unknown>): void;
-export declare function isPinnedHelperUnavailable(error: unknown): boolean;
-export {};
-//# sourceMappingURL=pinned-python.d.ts.map

package/dist/pinned-python.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"pinned-python.d.ts","sourceRoot":"","sources":["../src/pinned-python.ts"],"names":[],"mappings":"AA2ZA,KAAK,qBAAqB,GACtB,MAAM,GACN,MAAM,GACN,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,QAAQ,GACR,OAAO,CAAC;AAiBZ,wBAAgB,gCAAgC,IAAI,IAAI,CAQvD;AAiOD,wBAAsB,wBAAwB,CAAC,CAAC,EAAE,MAAM,EAAE;IACxD,SAAS,EAAE,qBAAqB,CAAC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC,GAAG,OAAO,CAAC,CAAC,CAAC,CA4Bb;AAED,wBAAgB,oCAAoC,IAAI,IAAI,CAK3D;AAED,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAarF;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEjE"}