@stonyx/utils 0.2.3-alpha.33 → 0.2.3-alpha.34

package/README.md

@@ -81,7 +81,7 @@ Updates a file atomically by writing to a sibling swap file first, then renaming
 
 **Concurrency: last writer wins.** Concurrent `updateFile` calls on the same path are safe — each uses a swap file unique to its process and call, so neither caller's swap file can collide with the other's. The rename-time `ENOENT` and the silent cross-caller byte clobber of [#44](https://github.com/abofs/stonyx-utils/issues/44) are both gone. (`updateFile` still throws `ENOENT` from its own precondition when the target does not exist — that is the documented contract above, and it is unrelated to concurrency.) Calls are not serialized: the surviving value is whichever caller renames last.
 
-**File mode is preserved; other inode metadata is not.** The swap file is created with the target's permission bits and `chmod`ed to them before the rename, so a `0600` file stays `0600`. ACLs, extended attributes, hard links and ownership are *not* carried across — the target necessarily gets a new inode.
+**File mode is preserved; other inode metadata is not.** The swap file is created with the target's permission bits and `chmod`ed to them before the rename, so a `0600` file stays `0600`. The `chmod` addresses the open file descriptor rather than the swap path, so it cannot be redirected onto another file by anyone who can write to the directory. ACLs, extended attributes, hard links and ownership are *not* carried across — the target necessarily gets a new inode.
 
 **Swap files after abnormal termination.** Cleanup runs on every failure path `updateFile` controls, but a process killed between the write and the rename leaves a `<path>.temp-<pid>-<token>` sibling behind, and no module ships a sweeper. This is a deliberate trade against the previous whole-second swap name, which was reused — and reuse is exactly the collision that caused #44, so uniqueness has to win. Be precise about what that costs: the old name only ever collapsed two orphans that were abandoned within the *same whole second*, so at any ordinary crash cadence it reclaimed nothing either (measured: five crashes 1200 ms apart leave five orphans under both names). The accumulation uniqueness genuinely adds is confined to a sub-second crash loop. Consumers that persist into a directory they scan, sync or commit should sweep or ignore `*.temp-*` siblings of their targets; an app that runs `git add` over its data directory will otherwise commit one.
 

package/dist/file.d.ts

@@ -41,9 +41,12 @@ export declare function createFile(filePath: string, data: string | Record<strin
  *
  * The target's mode is read before the write and reapplied to the swap file, so
  * the rename does not widen a deliberately restrictive file (a `0600` database
- * would otherwise become `0666 & ~umask`). Other inode-bound metadata — ACLs,
- * extended attributes, hard links, ownership — is *not* carried across; the
- * target gets a new inode by construction.
+ * would otherwise become `0666 & ~umask`). It is applied to the open file
+ * *descriptor*, never to the swap path: a path-based `chmod` follows symlinks,
+ * so an attacker holding write access to the directory could hijack the swap
+ * path mid-write and have the mode land on a file of their choosing. Other
+ * inode-bound metadata — ACLs, extended attributes, hard links, ownership — is
+ * *not* carried across; the target gets a new inode by construction.
  *
  * `rename` is atomic against concurrent *readers*, not against power loss:
  * there is no `fsync`, so this is namespace atomicity, not crash durability.

package/dist/file.js

@@ -35,9 +35,12 @@ export async function createFile(filePath, data, options = {}) {
  *
  * The target's mode is read before the write and reapplied to the swap file, so
  * the rename does not widen a deliberately restrictive file (a `0600` database
- * would otherwise become `0666 & ~umask`). Other inode-bound metadata — ACLs,
- * extended attributes, hard links, ownership — is *not* carried across; the
- * target gets a new inode by construction.
+ * would otherwise become `0666 & ~umask`). It is applied to the open file
+ * *descriptor*, never to the swap path: a path-based `chmod` follows symlinks,
+ * so an attacker holding write access to the directory could hijack the swap
+ * path mid-write and have the mode land on a file of their choosing. Other
+ * inode-bound metadata — ACLs, extended attributes, hard links, ownership — is
+ * *not* carried across; the target gets a new inode by construction.
  *
  * `rename` is atomic against concurrent *readers*, not against power loss:
  * there is no `fsync`, so this is namespace atomicity, not crash durability.
@@ -108,16 +111,25 @@ export async function updateFile(filePath, data, options = {}) {
             //
             // Exactly one case is not ours to remove: the `wx` open lost a race, so
             // the swap file is another writer's and unlinking it would reintroduce
-            // #44. That is EEXIST *from the write stage* — both halves matter.
-            //   - Code alone is not enough: `rename` surfaces EEXIST on Windows and
-            //     some network filesystems, and that file is one we created.
-            //   - Stage alone is not enough: `rename` is the only stage after the
-            //     open that can raise EEXIST at all, and by then the file is ours —
-            //     so a stage flag that answered "did the write finish?" would send
-            //     an ENOSPC/EDQUOT/EIO mid-write down the skip path and reinstate
-            //     the orphaned partial payload this PR exists to close. `created` is
-            //     set the instant the `wx` open returns, which is the only reading
-            //     of the stage that means "this call owns the path".
+            // #44.
+            //
+            // The stage is the half that decides it, and only because `created` is
+            // set the instant the `wx` open returns. That is the sole reading of the
+            // stage that means "this call owns the path": a flag set after the write
+            // instead would answer "did the write finish?", and an ENOSPC mid-write
+            // would take the skip path and reinstate the orphaned partial payload
+            // this PR exists to close. Splitting `writeFile` into an `open` and a
+            // write is what makes the correct reading expressible at all.
+            //
+            // The code half is kept as a narrowing guard, not because the stage is
+            // insufficient. Measured: mutating this to `!created` alone survives the
+            // suite, because `O_EXCL` cannot create and then fail, so a false
+            // `created` means no file exists and the unlink would be a no-op anyway.
+            // It earns its place by refusing to widen if the open and the write are
+            // ever re-merged — and note that the code alone does *not* hold up:
+            // mutating to the code alone reds `an EEXIST raised after the swap file
+            // was created is still cleaned up`, because `rename` surfaces EEXIST on
+            // Windows and some network filesystems and that file is one we created.
             const lostTheOpenRace = !created && isNodeError(swapError) && swapError.code === 'EEXIST';
             if (!lostTheOpenRace) {
                 await fsp.unlink(swapFile).catch(() => { });

package/package.json

@@ -3,7 +3,7 @@
   "keywords": [
     "stonyx-module"
   ],
-  "version": "0.2.3-alpha.33",
+  "version": "0.2.3-alpha.34",
   "description": "Utils module for Stonyx Framework",
   "repository": {
     "type": "git",