@openclaw/fs-safe 0.8.3 → 0.8.5

package/docs/archive.md

@@ -422,6 +422,63 @@ Normal link/filter policy still governs the described member. Canonical
 pre-strip filter paths, decoded-stream ceilings, and physical EOF checks apply
 to plain/gzip TAR and native zstd/bzip2 alike.
 
+## `inspectTarArchive`
+
+Inspect accepted TAR members without creating an extracted tree. This operation
+uses the same complete Rust/WASM admission and TypeScript extraction planner as
+`extractArchive`, with zero stripping. It detects plain TAR or gzip from the
+input bytes; ZIP, zstd, and bzip2 are not part of this inspection API.
+
+```ts
+import { inspectTarArchive } from "@openclaw/fs-safe/archive";
+
+const entries = await inspectTarArchive({
+  archivePath: "/srv/uploads/tree.tar.gz",
+  timeoutMs: 30_000,
+  limits: {
+    maxArchiveBytes: 16 * 1024 * 1024,
+    maxEntries: 5_000,
+    maxEntryBytes: 16 * 1024 * 1024,
+    maxExtractedBytes: 64 * 1024 * 1024,
+  },
+  entryFilter: ({ kind }) => kind === "file" || kind === "directory" ? "extract" : "skip",
+  onFiltered: "reject-archive",
+});
+```
+
+`InspectTarArchiveOptions` accepts `archivePath`, `timeoutMs`, `limits`,
+`entryFilter`, and `onFiltered`, with the same defaults and error classes as
+extraction. The result is a frozen array of frozen `InspectedTarEntry` records:
+`{ path: string; kind: "file" | "directory"; size: number }`, in archive order.
+`size` is the effective declared payload length. `path` is extraction's
+canonical pre-strip identity: case, Unicode spelling, BOM, and embedded LF are
+preserved, while separators and dot components follow the existing archive path
+contract. No human-readable tar listing or escape decoding is involved.
+
+Full framing, gzip integrity, EOF, metadata, decoded-byte, and manifest-budget
+validation finishes before the caller's filter runs. The shared planner then
+applies traversal, collision, depth, blocked-type, and accepted-payload limits.
+A failure returns no partial result. Filter callbacks are decisions, not admission
+receipts: later policy, collision, or budget checks can still reject the archive.
+Only the resolved Promise/result is authorization-worthy; do not perform
+irreversible actions from a filter callback.
+
+Root-only records count toward entry limits but produce no result; PAX/GNU metadata headers are not members. Only accepted
+file/directory members appear, not implicit parent directories. Unsupported
+records follow extraction's omission policy unless the filter rejects them, as
+in the example. AppleDouble records encoded as ordinary files are ordinary
+members, not hidden metadata.
+
+Inspection pins and privately stages its input, then cleans up that copy. It
+neither creates destination paths nor tests destination permissions or platform
+filename restrictions. Its result is evidence about those inspected bytes, not
+an extraction capability or a promise that a later file at `archivePath` is
+unchanged. Callers making authorization decisions must retain the same private
+immutable archive or verify byte identity before extracting with matching
+filter/limit settings. Extraction always performs its own admission and guarded
+publication. Native `off`, `auto`, and `require` retain their existing selection
+and availability semantics; inspection does not fall back after native failure.
+
 ## `resolveArchiveKind`
 
 ```ts

package/docs/atomic.md

@@ -200,6 +200,8 @@ await movePathWithCopyFallback({
 ```
 
 Use it when source and destination might live on different filesystems (containers, tmpfs, separate volumes).
+The hardlink policy is captured when the move starts. Changing or reusing the
+options object later does not change the policy of an in-flight move.
 `sourceHardlinks: "reject"` performs a recursive preflight capped at 50,000
 entries before any mutation. Because link count and rename cannot be one atomic
 portable operation, this mode always commits a fresh inode/tree through the

package/docs/reading.md

@@ -12,6 +12,8 @@ const opened = await fs.open("large.log");               // FileHandle for strea
 
 ## What every read does
 
+Identity and containment checks use brief synchronous metadata calls, like Node's module resolution, while file data is read asynchronously. Canonical paths retain Node's native realpath spelling, including expansion of Windows short paths.
+
 Regardless of shape, every read goes through the same boundary checks:
 
 1. Resolve the input lexically against the canonical real root.

package/docs/root.md

@@ -18,6 +18,7 @@ const fs = await root("/srv/workspace", {
 function root(rootDir: string, defaults?: RootDefaults): Promise<Root>;
 
 type RootDefaults = {
+  durable?: boolean;               // fsync write/create/writeJson/createJson/append; default true
   hardlinks?: "reject" | "allow";  // refuse files with nlink > 1 on read; defaults to "reject"
   denyMutations?: DenyMutationPolicy; // absolute paths/prefixes mutation methods may not change
   maxBytes?: number;               // refuse reads larger than this many bytes; defaults to 16 MiB
@@ -99,7 +100,7 @@ fs.write(rel, data, options?)            // overwrite-ok atomic write
 fs.create(rel, data, options?)           // throws "already-exists" if target exists
 fs.writeJson(rel, value, options?)       // JSON.stringify + atomic write
 fs.createJson(rel, value, options?)      // create() variant of writeJson
-fs.append(rel, data, options?)           // append text/buffer; syncs before close
+fs.append(rel, data, options?)           // append text/buffer; syncs before close by default
 fs.copyIn(rel, sourceAbsPath, options?)  // copy from outside the root, atomically, with size cap
 fs.openWritable(rel, options?)           // FileHandle for streaming writes; supports await using
 fs.move(from, to, options?)              // rename within the root; defaults to no clobber
@@ -110,6 +111,14 @@ fs.ensureRoot(options?)                  // accepts "" / "." as the root itself
 
 `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`).
 
+These five methods also accept `durable?: boolean`: the per-call value overrides
+`Root.defaults.durable`, which defaults to `true` when omitted. An explicitly
+`undefined` per-call value preserves the root default. `durable: false` keeps
+the existing publication behavior, modes, and identity checks but skips file
+and parent-directory fsync calls. Use it only for reconstructible data: a crash
+may lose the write or leave the previous file. See [Writing](writing.md#write-options)
+for platform details.
+
 `copyIn` is a one-shot ingest from a trusted absolute source path: it streams the source through the boundary, atomically renames into the root, and respects `maxBytes`.
 
 Root operations that choose a new destination reject a leading Windows

package/docs/types.md

@@ -100,6 +100,7 @@ type RenameIdentityPolicy = "strict" | "verify-content-with-lock";
 
 type RootDefaults = {
   denyMutations?: DenyMutationPolicy;
+  durable?: boolean; // default true for write/create/writeJson/createJson/append
   hardlinks?: "reject" | "allow";
   maxBytes?: number;
   mkdir?: boolean; // default true for mutation methods
@@ -126,7 +127,7 @@ type RootOptions = {
 
 ```ts
 type RootReadOptions = Pick<RootDefaults, "hardlinks" | "maxBytes" | "nonBlockingRead" | "symlinks">;
-type RootWriteOptions = Pick<RootDefaults, "denyMutations" | "mkdir" | "mode" | "renameIdentity"> & {
+type RootWriteOptions = Pick<RootDefaults, "denyMutations" | "durable" | "mkdir" | "mode" | "renameIdentity"> & {
   encoding?: BufferEncoding;
   overwrite?: boolean;
 };

package/docs/writing.md

@@ -77,14 +77,37 @@ 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; 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()`.
+`data` accepts `string | Buffer`. `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()`.
+
+#### Write options
+
+| Option | Type | Default / behavior |
+|---|---|---|
+| `denyMutations` | `DenyMutationPolicy` | Merged with root-level denies. |
+| `durable` | `boolean` | `true`; use `false` to skip file and parent fsync. |
+| `encoding` | `BufferEncoding` | `"utf8"` for strings. |
+| `mkdir` | `boolean` | `true`; creates missing parents. |
+| `mode` | `number` | Inherited on replacement, otherwise `0o600`. |
+| `overwrite` | `boolean` | `true`; `false` is create-only. |
+| `renameIdentity` | `RenameIdentityPolicy` | `"strict"`. |
+
+`write`, `create`, `writeJson`, `createJson`, and `append` accept `durable`.
+Precedence is per-call option, then `Root.defaults.durable`, then `true`;
+an explicitly `undefined` call option preserves the root default.
+`durable: false` keeps the sibling-temp replace/rename behavior of replacement
+writes but skips file and parent-directory fsync calls. Create-only and append
+publication behavior, permissions, identity checks, and error codes are unchanged.
+Use it only for reconstructible data: a crash may lose the write or leave the
+previous file. `copyIn`, `move`, and streaming `openWritable` do not use this option.
+The existing pure-JavaScript Windows writer performs no fsync calls in either
+setting; native Windows writes honor the option. Directory sync remains best-effort.
 
 POSIX modes without read permission, including `0o000` and `0o200`, succeed:
 final verification uses a descriptor retained by the writer rather than reopening
 the published file. The requested mode is not relaxed for verification.
 Publication verification compares exact bigint descriptor and pathname identities,
 including large file indexes that cannot be represented by a JavaScript number.
-Native publication syncs content before rename and always syncs the parent directory.
+With durability enabled (the default), native publication syncs content before rename and syncs the parent directory.
 Modes that retain owner read/write skip the extra mode-only file sync: after a
 crash, the file may retain staged mode `0o600` instead of the wider requested mode.
 Modes that remove owner read or write, and corrections of observed wider staging
@@ -143,7 +166,7 @@ type RootWriteJsonOptions = RootWriteOptions & {
 
 ### `fs.append(rel, data, options?)`
 
-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. Pass `prependNewlineIfNeeded: true` to insert a `\n` if the file does not already end in one.
+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.
 
 ```ts
 await fs.append("logs/today.log", `[${ts}] ${line}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.8.3",
+  "version": "0.8.5",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -156,13 +156,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.8.3",
-    "@openclaw/fs-safe-darwin-x64": "0.8.3",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.8.3",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.8.3",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.8.3",
-    "@openclaw/fs-safe-linux-x64-musl": "0.8.3",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.8.3",
+    "@openclaw/fs-safe-darwin-arm64": "0.8.5",
+    "@openclaw/fs-safe-darwin-x64": "0.8.5",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.8.5",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.8.5",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.8.5",
+    "@openclaw/fs-safe-linux-x64-musl": "0.8.5",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.8.5",
     "jszip": "^3.10.1"
   },
   "devDependencies": {