@openclaw/fs-safe 0.5.5 → 0.6.0

package/docs/staged-file.md

@@ -0,0 +1,178 @@
+---
+title: Retained-directory staging
+description: "Prepare and publish one file while retaining its original directory for abort cleanup."
+---
+
+# Retained-directory staging
+
+`stageFileInDirectory()` from `@openclaw/fs-safe/advanced` prepares one file in
+an existing directory and keeps that directory open until cleanup or disposal.
+It requires the native binding on Linux or macOS, even in native mode `auto`.
+Native off, an unavailable binding, or a binding without the required mechanism
+fails before file creation. Windows is explicitly unsupported for this API.
+Existing root, output, temp, lock, and durability APIs retain their documented
+platform and fallback contracts.
+
+```ts
+import type { DirectoryReceipt } from "@openclaw/fs-safe/durability";
+import {
+  stageFileInDirectory,
+  type PublishedFileReceipt,
+} from "@openclaw/fs-safe/advanced";
+
+// Call while holding the application's cooperative writer lock. The caller
+// supplies its authorization, manager, snapshot, and fingerprint checks.
+export async function publishReviewedUpdate(options: {
+  directory: DirectoryReceipt;
+  basename: string;
+  bytes: Uint8Array;
+  assertAuthorizedAndCurrent(): Promise<void>;
+}): Promise<PublishedFileReceipt> {
+  await options.assertAuthorizedAndCurrent();
+  await using staged = await stageFileInDirectory({
+    directory: options.directory,
+    content: options.bytes,
+  });
+  await options.assertAuthorizedAndCurrent();
+  await staged.assertCurrent();
+  return await staged.publish(options.basename, { overwrite: true });
+}
+```
+
+`await using` always disposes, including on exceptions. If both the body and
+disposal fail, JavaScript preserves both errors in a `SuppressedError`. A
+successful return means publication was observed and verified, not that a
+separate application transaction committed. Application rollback and recovery
+remain with the caller.
+
+## API
+
+```ts
+function stageFileInDirectory(options: {
+  directory: string | DirectoryReceipt;
+  content: string | Uint8Array;
+  mode?: number;
+}): Promise<StagedFile>;
+
+interface StagedFile extends AsyncDisposable {
+  readonly receipt: StagedFileReceipt;
+  assertCurrent(): Promise<void>;
+  publish(basename: string, options: { overwrite: boolean }): Promise<PublishedFileReceipt>;
+  cleanup(): Promise<StagedFileCleanupReceipt>;
+}
+```
+
+Strings are UTF-8. `mode` is the requested **published** mode and defaults to
+`0600`; exact final modes, including `000`, are supported. The unpublished file
+stays at `0600` throughout preparation and any awaited application checks.
+After rename succeeds and the published entry passes identity validation, the
+owner applies the requested mode through its retained file descriptor and
+synchronizes the file. No parent is created or chmodded.
+Creation uses an exclusive, no-follow, close-on-exec open of a generated direct
+child name. Writes use that descriptor. Inspection uses non-following metadata
+operations, never a potentially blocking reopen of the leaf.
+
+A supplied directory receipt must still match at admission. Its numeric
+identity must be exactly representable; ambiguous identity fails closed.
+Returned receipts are frozen descriptive snapshots, not mutable authority.
+Changing a supplied receipt after admission cannot retarget the lifecycle.
+
+`StagedFileReceipt` contains `directory` (`path`, `realPath`, and exact bigint
+`identity.dev`/`identity.ino`), `temporaryBasename`, and the prepared file's
+`identity` (`dev`, `ino`, `size`, `nlink`, `mtimeNs`, `ctimeNs` as bigint;
+`mode`, `uid`, `gid` as numbers). This is a preparation-time snapshot of the
+private stage: its mode is `0600`. Publication does not refresh this snapshot;
+neither its mode nor its timestamps are a final-file fingerprint. No raw
+descriptors are exposed.
+
+`assertCurrent()` verifies the original pathname's directory identity and the
+staged name against the retained file. A failed check does not disable cleanup.
+After successful publication there is no staged name to check, so further
+checks or publication reject. Cleanup closes the lifecycle; later checks and
+publication reject before descriptor use. Rejected publication still carries its
+phase, cause, and recorded publication outcome after closure. Concurrent calls
+are serialized in invocation order, including cleanup and disposal. Repeated
+cleanup returns the recorded outcome, or repeats the recorded error, without
+touching descriptors.
+
+## Publication and failure evidence
+
+`publish()` requires an explicit boolean `overwrite` and one direct-child
+basename. Empty, dot, dotdot, separators, absolute paths, NUL, control characters,
+drive-relative spellings, and the stage's own name are rejected.
+
+With `overwrite: false`, publication is genuine kernel no-replace rename; a
+collision leaves both names unchanged and raises `FsSafeError("already-exists")`.
+The stage may then be cleaned or published under another name. With
+`overwrite: true`, publication is plain atomic replacement. Neither route
+copies. Both source and destination resolve through the retained original
+parent, with checks immediately before rename and after publication.
+
+`PublishedFileReceipt` has `status: "published"`, `staged`, `basename`, and
+`overwrite`. Its `staged` field retains the private preparation snapshot, not
+final metadata. Errors from publication carry typed `StagedFileFailureDetails`
+in `FsSafeError.details`, including `phase` and `publication`. Publication is
+`not-published`, `published` (with its receipt), or `indeterminate` (with the
+attempted basename and overwrite policy) if a rename error cannot establish
+whether it committed. The underlying error remains in `cause`.
+
+A parent move after the final pre-check cannot divert the rename to a
+replacement parent. It can publish inside the moved original and then fail
+post-validation. Successful rename is recorded before those checks; cleanup
+never deletes or rolls back a published final name. Indeterminate publication
+also preserves names for caller-directed recovery.
+
+The same rule applies if applying the published mode, synchronizing, or a later
+check fails: the error reports `published`, and cleanup preserves the final
+name. The file may still have mode `0600` or may already have the requested
+mode, depending on which operation failed. A `published` failure receipt records
+rename success, not successful permission finalization.
+
+## Cleanup guarantee and limits
+
+If the temporary basename still names the object created by this lifecycle and
+filesystem removal remains permitted, moving or replacing the actual parent
+(or an ancestor) does not strand the unpublished temp. Cleanup resolves through
+the retained original directory, even after `assertCurrent()` rejects drift.
+Same-name sentinels in the replacement parent are not touched.
+
+`StagedFileCleanupReceipt` records `temporaryBasename`, `publication`,
+`resources` (`closed` or `close-failed`), and `status`:
+
+| Status | Meaning |
+|---|---|
+| `removed` | The owned recorded name was unlinked through the retained directory. |
+| `name-absent` | That name was absent in the original directory; this does not prove the inode has no other names. |
+| `preserved` | An observed substitute or an indeterminate publication was left alone. |
+| `failed` | Inspection or removal failed. |
+| `not-needed` | Publication was recorded, or preparation failed before creating a file. |
+
+Explicit cleanup returns preservation outcomes. Removal or close failures throw
+an `FsSafeError` with the receipt in `details.cleanup` and underlying errors in
+`cause`. Disposal also throws for preservation, so ignoring its return value
+cannot hide incomplete cleanup. Setup failures preserve the original error;
+when cleanup also fails, an aggregate cause retains both failures. Descriptors
+are closed on every cleanup outcome, with no retry through recycled numbers.
+
+This is **directory-relative targeting**, not expected-destination-inode/CAS
+publication. Checking an identity before rename does not make rename CAS.
+Likewise, the identity check followed by `unlinkat` is not an atomic conditional
+unlink: an adversary can replace the leaf in that final syscall gap. Observed
+substitutions are preserved, but this API does not guarantee recovery after
+arbitrary child renames, permission revocation, I/O failure, or process death.
+Keep application authorization, manager checks, snapshots, fingerprints,
+cooperative locks, and conditional rollback.
+
+Namespace cleanup is not crash durability. Staging retains the native writer's
+file synchronization behavior, and publication synchronizes its directory
+(with the existing `EPERM` exception); cleanup does not promise a durable unlink.
+No successful receipt promises survival across a crash. See [Directory
+durability](durability.md) when an application needs a separate durability proof.
+`pinDirectory().assertCurrent()` and `.sync()` still require a current pathname;
+they do not gain this cleanup authority.
+
+## Related pages
+
+- [Advanced composition](advanced.md)
+- [Native architecture](native.md)
+- [Security model](security-model.md)

package/docs/testing.md

@@ -17,7 +17,7 @@ The double-underscore prefix is a deliberate "hands off" signal: production code
 ## When to reach for hooks
 
 - Reproduce a TOCTOU race deterministically: simulate a symlink swap between resolve and open, or between write and rename.
-- Force guarded JavaScript behavior without removing bundled binaries from your runners.
+- Force guarded JavaScript behavior without removing platform packages from your runners.
 - Inject latency to test cancellation/timeout paths.
 
 If you don't need to inject a race, you don't need hooks — most tests should drive the library through normal calls and assert on observable behavior.

package/docs/writing.md

@@ -33,6 +33,10 @@ 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.
 
+Post-publication verification can still reject after a complete replacement has
+been committed. Rejection does not promise that a successful rename was rolled
+back; the published file or a raced replacement may remain at the destination.
+
 ## Denying mutations
 
 All mutation verbs accept `denyMutations?: DenyMutationPolicy`, either as a root default or per-call option:
@@ -64,6 +68,21 @@ 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()`.
 
+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.
+Later reads still obey OS permissions, and access checks on a pre-existing
+destination are unchanged. The explicit FUSE compatibility policy still requires
+a readable destination to prove matching content when rename changes its identity.
+
+When Windows cannot report a pathname's identity, the publication verifier reopens
+the name and compares that descriptor's exact identity with the original retained
+file, without reading bytes. It also rechecks links and root/parent containment.
+This write-specific proof does not relax ordinary reads: unknown pathname metadata
+alone is never proof that the name still refers to the expected file.
+
 ### `fs.create(rel, data, options?)`
 
 Don't-clobber variant of `write()`. Throws `already-exists` if the target is there.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.5.5",
+  "version": "0.6.0",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -27,7 +27,6 @@
     "dist/**/*.js",
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
-    "dist/native/**/*.node",
     "docs/**/*.md",
     "docs/assets/readme-banner.jpg",
     "README.md",
@@ -139,6 +138,7 @@
     "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:collect": "node scripts/check-release-packages.mjs --output release-artifacts",
     "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",
@@ -149,25 +149,32 @@
     "crabbox:warmup": "crabbox warmup"
   },
   "optionalDependencies": {
+    "@openclaw/fs-safe-darwin-arm64": "0.6.0",
+    "@openclaw/fs-safe-darwin-x64": "0.6.0",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.6.0",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.6.0",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.6.0",
+    "@openclaw/fs-safe-linux-x64-musl": "0.6.0",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.6.0",
     "jszip": "^3.10.1",
     "tar": "7.5.22"
   },
   "devDependencies": {
-    "@emnapi/runtime": "2.0.0-alpha.3",
-    "@napi-rs/cli": "3.8.2",
-    "@types/node": "^26.2.0",
-    "@vitest/coverage-v8": "4.1.10",
+    "@emnapi/runtime": "2.0.0-alpha.4",
+    "@napi-rs/cli": "3.8.6",
+    "@types/node": "^26.3.0",
+    "@vitest/coverage-v8": "4.1.11",
     "fast-check": "^4.9.0",
     "istanbul-lib-coverage": "3.2.2",
     "istanbul-lib-report": "3.0.1",
     "istanbul-reports": "3.2.0",
     "sigstore": "5.0.0",
     "typescript": "^7.0.2",
-    "vite": "8.2.1",
-    "vitest": "^4.1.10"
+    "vite": "8.2.2",
+    "vitest": "^4.1.11"
   },
   "engines": {
     "node": ">=22"
   },
-  "packageManager": "pnpm@10.34.5"
+  "packageManager": "pnpm@11.24.0"
 }