fs-local: POSIX-only mode-bit assertions, document Windows DACL-inheritance semantics

Windows drives only the read-only attribute through chmod and reports
synthetic stat mode bits, so writeFileAtomic's mode arguments are inert
there; write-in-progress privacy comes from the staging dir (created in
the target's parent) inheriting the destination directory's DACL.
Production is deliberately unchanged -- the chmod calls are benign
no-ops and platform-guarding them out buys nothing. Tests guard the
mode-bit expects to POSIX; there is no Windows ACL assertion because an
ACL check would pin OS inheritance plus the machine's %TEMP% ACL, not
this package. Decision and rejected alternatives (explicit DACLs,
Get-Acl/icacls test verification) recorded in the new RFC.
This commit is contained in:
Huanqi Cao
2026-07-05 21:15:46 +08:00
committed by imccyu
parent 715aa7372a
commit e47ae0643c
5 changed files with 49 additions and 6 deletions

View File

@@ -408,9 +408,11 @@ async function removeStagingDirOrThrow(stagingDir: string, originalError: unknow
/**
* Atomically replace a file through a private, synced staging file in the same directory.
* POSIX protects the staging directory and file with `0o700` and `0o600`; Windows
* inherits the destination directory's DACL because Node mode bits are synthetic there.
* @param absolutePath - destination; missing parent directories are created.
* @param content - the full UTF-8 text to write.
* @param mode - final mode, or `0o600` when omitted.
* @param mode - final POSIX mode, or `0o600` when omitted; inert on Windows.
* @param signal - cancellation checked before the final rename.
* @param internals - test seam for pinning temp names and observing the staged file.
*/