@openclaw/fs-safe 0.15.0 → 0.17.0

package/docs/writing.md

@@ -6,11 +6,11 @@ half-written replacement appears at the destination. Create-only writes
 (`create`, `createJson`, and `write` with `overwrite: false`) use sibling-temp
 staging with an atomic no-replace rename only on backends that provide one —
 the native binding, which `require` mode guarantees and `auto` mode uses when
-the binding loads. The pure-JavaScript fallback has no atomic no-clobber
-rename and does not stage: it claims the final name exclusively with `O_EXCL`
-and writes content in place, so a concurrent observer can see the new file
-before its content is complete. Use `require` mode when that visibility window
-matters.
+the binding loads. Ordinary buffered creation in the pure-JavaScript fallback
+claims the final name exclusively with `O_EXCL` and writes content in place, so
+a concurrent observer can see the new file before its content is complete.
+Buffered `create` and `createJson` accept `atomic: true` to stage complete content
+on this fallback too. Streamed creation already stages before publication.
 `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.
@@ -113,6 +113,14 @@ Native and pure-JavaScript Windows writers honor the option. Replacement writes
 sync staged content before rename and the final mode through the retained file
 handle. Directory sync remains best-effort.
 
+For `create` and `createJson`, `durable: "file"` requires each file sync to succeed,
+including on `EPERM`; it overrides a disabled Root durability default. Parent
+directory synchronization retains the existing best-effort policy. This also
+applies to streamed creation and is independent of publication strategy. Boolean
+durability options keep their existing behavior, including compatibility paths
+that tolerate `EPERM`. A failed file sync before staged publication prevents
+publication; a failure after publication can leave the complete file present.
+
 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.
@@ -146,19 +154,61 @@ claimed exclusively first and content is written afterward, so observers can
 briefly see an empty file; failure cleanup removes a claimed file only when its
 identity is unchanged.
 
+After a successful create-only write, failure to close its owned file handle
+rejects the operation and leaves the complete file present. Ordinary buffered
+creation in the JavaScript fallback preserves an earlier write or verification
+failure if close also fails. Native, atomic, and streamed creation retain their
+existing publication and cleanup diagnostics.
+
 ```ts
 try {
   await fs.create("config/seed.json", initial);
 } catch (err) {
-  if (err instanceof FsSafeError && err.code !== "already-exists") throw err;
+  if (!(err instanceof FsSafeError) || err.code !== "already-exists") throw err;
 }
 ```
 
+### Atomic buffered creation
+
+```ts
+await fs.create("config/seed.json", initial, { atomic: true });
+await fs.createJson("config/settings.json", { enabled: true }, { atomic: true });
+await fs.create("config/flushed.json", initial, { atomic: true, durable: "file" });
+```
+
+`atomic: true` keeps the destination absent until all bytes have been written.
+The native backend uses its no-replace rename; the JavaScript fallback hardlinks
+the completed stage and unlinks its temporary name in the same JavaScript turn.
+The fallback requires hardlink support and fails without publishing partial bytes
+when that mechanism is unavailable. Other processes can briefly observe both
+names. Existing and raced entries are preserved, including dangling symlinks;
+ordinary confinement, type, hardlink, and symlink-policy rejections still apply.
+`assertBeforeMutation` retains its live checks through content writes and publication.
+
+Omitted or `false` preserves the existing buffered behavior. The option belongs
+to buffered `create` and `createJson`, not replacement writes or Root defaults.
+Streamed creation has no atomic opt-out. `atomic` changes visibility, not the
+existing `durable` file/directory synchronization policy; it does not turn
+best-effort synchronization into a strict crash-durability guarantee or strengthen
+JavaScript pathname containment.
+
+Atomic and streamed creates settle owned cleanup and close operations before
+returning. Failed or unverifiable cleanup is reported rather than silently
+discarded. Errors after publication and incomplete-settlement errors carry the
+existing `StagedFileFailureDetails` publication/cleanup receipts where the writer
+can establish them; native disposal can retain them inside a `SuppressedError`
+cause. Preserve those details when handling errors: a rejection can follow
+complete publication, and an indeterminate link or native rename must preserve names for
+recovery. A cleanup or close failure also retains the original operation failure.
+No later verification, mode, or synchronization failure authorizes deleting an
+already published complete destination. See [receipt meanings](staged-file.md).
+
 ### Streamed creation
 
 Pass an `AsyncIterable<Uint8Array>` to `create()` when bytes come from a database,
 network response, or another incremental producer. Buffers are accepted chunks.
-The writer consumes each chunk completely before requesting the next one; it
+The writer borrows `Uint8Array` slices without copying their payloads and counts
+their actual byte bounds. It consumes each chunk completely before requesting the next one; it
 does not collect the full input in memory or expose a writable descriptor.
 
 ```ts
@@ -202,6 +252,12 @@ forcibly interrupted, so cancellation waits for its pending work and cleanup to
 settle. Do not mutate a yielded chunk until the next pull. Producer errors retain
 their original value when cleanup succeeds.
 
+Streamed creation retains the `signal` and `assertBeforeMutation` callback
+selected when the call starts. Replacing or deleting those options during a
+producer wait does not change the in-flight operation. Abort the original signal
+or update the live authority state checked by the original callback to revoke
+it; the callback continues to receive the original options object as `this`.
+
 An aborted or failed operation can leave created parent directories. If a
 stage's identity or parent cannot be verified during cleanup, the existing
 guarded cleanup preserves it. After publication, later verification or cleanup
@@ -268,6 +324,10 @@ await fs.move("incoming/foo.txt", "archive/foo.txt", { overwrite: true });
 
 Both `from` and `to` are bounded; `..` in either is rejected.
 
+Mutation policy is captured at call start; changes to caller-owned denial arrays
+apply to later moves. For live cancellation or revocation, throw from
+`assertBeforeMutation` immediately before dispatch.
+
 The default no-clobber mode requires the native helper. It admits both parent
 directory descriptors and performs a descriptor-relative no-replace rename, so
 a competitor that creates the target first is preserved and the source remains
@@ -407,6 +467,19 @@ an atomic check-and-delete syscall. Use OS isolation for that threat model.
 await fs.mkdir("snapshots/2026/05");
 ```
 
+Pass `{ private: true }` to create missing components with private permissions.
+An existing requested directory must already satisfy that policy; fs-safe does
+not repair it or change existing ancestor permissions. Concurrent creators may
+reuse the winner only after it passes the same checks.
+
+Buffered, streamed, and JSON `create` calls also accept `private: true`.
+New POSIX directories default to `0700` and files to `0600`; conflicting
+group/world or privilege bits are rejected before creation. Restrictive
+owner-only file modes remain available through `mode`. On Windows, creation
+uses protected ACLs rather than interpreting POSIX mode bits as access rules.
+This does not change `create`'s no-overwrite behavior or select its durability
+policy. See [creation](creation.md) for supported backends and owned descriptors.
+
 ### `fs.ensureRoot()`
 
 Treats `""` / `"."` as the root itself. Useful when a generic helper computes a relative directory and might end up at the root.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -25,6 +25,8 @@
   },
   "files": [
     "dist/archive-parser.wasm",
+    "dist/windows-security-bridge.cs",
+    "dist/windows-security-bridge.ps1",
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
@@ -144,10 +146,10 @@
     "test:bun": "bun node_modules/vitest/vitest.mjs run --config scripts/bun-vitest.config.ts",
     "test:bun:native": "bun scripts/bun-native-proof.mjs && bun node_modules/vitest/vitest.mjs run --config scripts/bun-native-vitest.config.ts",
     "test:coverage": "vitest run --coverage",
-    "test:coverage:collect": "pnpm build && vitest run --coverage --coverage.reporter=json --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.statements=0 --coverage.thresholds.branches=0",
+    "test:coverage:collect": "pnpm build && pnpm archive:wasm:allocator-tests && vitest run --coverage --coverage.reporter=json --coverage.thresholds.lines=0 --coverage.thresholds.functions=0 --coverage.thresholds.statements=0 --coverage.thresholds.branches=0",
     "test:coverage:merge": "node scripts/merge-coverage.mjs",
     "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 docs:check && pnpm test && node scripts/check-pack.mjs",
+    "check": "pnpm lint:file-size && pnpm lint:fs-boundary && pnpm build && pnpm archive:wasm:allocator-tests && 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",
@@ -164,24 +166,25 @@
     "crabbox:stop": "crabbox stop",
     "crabbox:warmup": "crabbox warmup",
     "archive:wasm": "node scripts/build-archive-wasm.mjs",
+    "archive:wasm:allocator-tests": "node scripts/build-archive-wasm.mjs --allocator-tests",
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.15.0",
-    "@openclaw/fs-safe-darwin-x64": "0.15.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.15.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.15.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.15.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.15.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.15.0",
+    "@openclaw/fs-safe-darwin-arm64": "0.17.0",
+    "@openclaw/fs-safe-darwin-x64": "0.17.0",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.17.0",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.17.0",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.17.0",
+    "@openclaw/fs-safe-linux-x64-musl": "0.17.0",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.17.0",
     "jszip": "^3.10.2"
   },
   "devDependencies": {
     "@emnapi/runtime": "2.0.0-alpha.5",
-    "@napi-rs/cli": "3.10.0",
-    "@types/node": "^26.5.1",
+    "@napi-rs/cli": "3.10.3",
+    "@types/node": "^26.6.1",
     "@vitest/coverage-v8": "5.0.1",
-    "fast-check": "^4.9.0",
+    "fast-check": "^4.10.1",
     "istanbul-lib-coverage": "3.2.2",
     "istanbul-lib-report": "3.0.1",
     "istanbul-reports": "3.2.0",
@@ -189,10 +192,10 @@
     "tar": "7.5.22",
     "typescript": "^7.0.2",
     "vite": "8.3.0",
-    "vitest": "^5.0.0"
+    "vitest": "^5.0.1"
   },
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@11.25.0"
+  "packageManager": "pnpm@12.4.2"
 }