Security model

fs-safe is a library-level guardrail: a capability-style root handle for Node.js code that handles untrusted relative paths. It assumes the calling process already has whatever filesystem permissions it needs and aims to stop trivial path tricks from broadening that authority. It is not a sandbox and does not replace operating-system isolation.

The same shape exists in other languages: Go's os.Root / OpenInRoot and Rust's cap-std both expose a root handle whose operations refuse to escape it. fs-safe is the Node-side equivalent: a single root() capability that carries the boundary across every read, write, move, and remove, instead of leaving each call site to redo path.resolve(...).startsWith(...) and hope.

#Affected versions / exposure

In published releases through 0.4.7, the exported resolveRootPath() and resolveRootPathSync() helpers validated a lexically normalized path spelling. A caller-supplied path traversing an in-root symlink could therefore pass validation while resolving outside the root. Version 0.5 fixes this with component-wise alias resolution, resolving each alias before applying later path components.

root() handles were not affected: their operations have contained this case since 5ddca80. Exposure is limited to consumers that call resolveRootPath() or resolveRootPathSync() directly.

#Threat model

You hand a root() boundary to a piece of code that takes caller-controlled relative paths. The library defends against a caller that:

• supplies .. traversal segments to escape the boundary
• supplies an absolute path outside a configured root, or to an API whose input

contract is strictly relative/portable

• replaces a path component with a symlink between check and use (TOCTOU)
• replaces the destination directory with a symlink right before a write
• creates a hardlink that aliases an out-of-tree inode and asks you to read or replace it
• asks a read/open primitive to target a known unsafe device or process-fd path
• uses an NTFS alternate-stream or directory-index pathname to alias a different

Windows filesystem object than the visible path suggests

• triggers a partial write that leaves a half-written file at the destination
• ships an archive with .. paths, absolute paths, or symlinks pointing outside the destination

It does not defend against:

• a process running with permissions to write anywhere on the filesystem and choosing to ignore the library
• another process with the same UID racing to mutate the same directory between two separate fs-safe calls — the boundary is per-call, not per-session
• arbitrary traversal across filesystem boundaries, bind mounts, or virtual filesystems beyond the known unsafe read device paths
• container escape, TOCTOU between fork and exec of helpers, or kernel-level vulnerabilities
• semantic content checks: file types, archive payload schemas, signature verification

If you need full sandboxing, run the worker under reduced privileges (uid, container, seccomp, chroot, jail) and use fs-safe inside the sandbox to keep the worker honest about its own workspace.

#Defenses, by failure mode

#Path traversal and absolute paths

Every path is resolved against the canonicalized real path of the root, then checked at that boundary. On Windows, an exact-case structural Root prefix stays on the lexical fast path; a prefix accepted only by case folding must have the Root's exact directory identity and is rebased onto the trusted Root spelling before use. Alias resolution walks components before applying a later .., so a symlink cannot change what that parent segment means after validation. Parent traversal, an absolute spelling, or any alias whose canonical result is outside the root throws outside-workspace; absolute spellings that remain inside the root are accepted.

Guarded pathname APIs reject Windows : namespace aliases before normalization or filesystem access. The only colon admitted in a Windows filesystem path is the rooted ASCII drive designator (including extended-drive syntax); relative paths admit none. This rule does not authorize device or network paths, which retain their independent restrictions. Pure formatters, descriptor-only calls, and walkDirectory (documented as a non-boundary traversal helper) are outside this pathname-admission guarantee. Output helpers continue to sanitize an untrusted basename, then validate the resulting path.

The low-level existing-object readers openRootFile() and openRootFileSync() preserve their historical Windows drive-relative input: they anchor its leading drive designator before this admission check. The raw suffix remains unnormalized, and any additional colon is still rejected before filesystem access.

Trusted-path standalone publication APIs retain the same drive-relative compatibility. This includes the atomic file, text, JSON, JSON store/direct queue writer, directory-replacement, move, and exclusive-publication helpers. They capture the drive's current directory at publication entry and carry the anchored spelling through their remaining checks, locks, callbacks, receipts, publication, and cleanup. File writers preserve the raw suffix. Root-relative APIs and caller-constructed relative directory receipts continue to reject drive designators.

#Symlinks (read side)

open() and read() use fs.open with O_NOFOLLOW on POSIX where available. The library then fstats the open fd and realpaths the original input, asserting the two refer to the same inode. A symlink swap that happens between resolve and open will fail at the identity check rather than silently following the new target.

Per-call symlinks: "follow-within-root" allows symlinks whose final target is still inside the root. The default is "reject".

symlinks: "follow-parents-within-root" allows contained parent directory aliases while rejecting a final symlink, including dangling links. Reads open the checked canonical parent plus the final basename with the usual no-follow and identity checks, so callers do not need their own parent canonicalization.

Guarded root reads compare lossless bigint identities from before open, the opened descriptor, the input path, and the canonical target; numeric public Stats receipts are not used as identity evidence. Before returning a handle or reading bytes, one best-effort final admission fence checks the originally captured root identity, freshly compares the policy-aware pathname with the opened descriptor, canonicalizes and re-admits that current target inside the captured root, compares the canonical target's exact bigint identity without following a final symlink with the descriptor, and checks the root identity again. The two final pathname observations remain independent even when the spellings match. Unknown Windows device/inode values receive one re-inspection without reopening the file. A definite mismatch or persistent unknown identity rejects with path-mismatch; escaped fresh containment rejects with outside-workspace. This is not an atomic kernel pathname/open primitive, so the namespace can still change after the final observation.

Other regular-file readers, root-file adapters, and archive input staging retain their documented descriptor/path admission. The exported unrooted openLocalFileSafely() and readLocalFileSafely() helpers have no captured Root identity and therefore do not provide the replacement-root fence. copyIn() retains the admitted source identity for its checks before and after copying, independently of its numeric metadata receipt.

The low-level openRootFile() adapters additionally retain the canonical root's exact identity from before component traversal. After their existing pathname and descriptor checks, they verify the root, freshly resolve and re-admit the consumed pathname, compare that canonical leaf with the descriptor, and verify the root again before returning ownership. A failed final fence closes the descriptor without reading. The checks detect substitutions at each observation boundary; they do not make pathname confinement atomic against a continuously racing peer.

#Symlinks (write side)

With the native binding loaded, write(), create(), and copyIn() use a sibling temp file and create parents and publish the target relative to pinned directory descriptors. Replacement uses descriptor-relative rename just like no-replace publication, so replacing the parent pathname does not divert the mutation.

When either denyMutations or an explicit mutationSymlinks policy applies, the POSIX writer binds that exact policy snapshot to parent admission. An existing parent is canonicalized and identity-matched to its retained descriptor before the actual destination is authorized. A missing-parent walk authorizes each prospective directory before mkdirat, opens it without following a newly introduced link, and authorizes the opened object before continuing. This prevents a contained Linux openat2(RESOLVE_BENEATH | RESOLVE_NO_MAGICLINKS) redirect from reusing policy approval for a different in-root subtree. For an ordinary unchanged route, operation-local observations may carry that admission across a direct-child creation only after exact parent and child fences and a synchronous full-epoch validation. The resulting operation-local token authorizes the opened child without an intervening await; stale, redirected, incomplete, or foreign evidence returns to the full ordered admission. An already-complete fallback parent is likewise retained only after full target admission and a fresh exact guard fence. Native acceleration additionally requires an exclusive direct-child mkdir result proving that this syscall created the name; a collision, legacy helper, or malformed result performs the guarded walk but cannot advance the receipt. That boolean is admission provenance only and does not grant ownership for cleanup by pathname.

The opt-in mutationSymlinks policy applies independently of read policy. "reject" rejects symlink components; "follow-parents-within-root" resolves contained directory aliases and rejects final symlinks. Publication checks the final component again after awaited staging and parent fences, immediately before the rename or exclusive open. These are best-effort symlink checks, not an atomic expected-entry/CAS replacement: a concurrent process can still replace the final entry between its check and rename. Existing parent containment guarantees remain as described below. Omitting mutationSymlinks preserves existing mutation behavior.

The JavaScript fallback used by off, by auto when no binding loads, and by the explicit renameIdentity: "verify-content-with-lock" compatibility policy cannot provide that guarantee because Node exposes no mkdirat or renameat. It asserts directory identity around a pathname mutation and detects many swaps, but detection occurs after the kernel may already have followed a new parent symlink. A same-privilege peer with write access to the parent can therefore cause an out-of-root side effect before the operation throws. Use native require mode when concurrent hostile mutation is in scope.

The separate retained-directory staging lifecycle keeps abort cleanup anchored to the original directory after a parent or ancestor move. It preserves observed substituted temporary entries and never cleans a recorded publication. Directory anchoring is not expected-inode/CAS replacement, and identity-check-then-unlink is not atomic conditional unlink. The guarantee requires the temporary name to remain owned and removal to remain permitted; application authorization and cooperative coordination remain necessary.

#Hardlink aliasing

When hardlinks: "reject" is set, reads stat the target and refuse if nlink > 1, on the conservative assumption that a hardlinked file might alias an out-of-tree inode. This is defense-in-depth: the link count check is best-effort and platform-dependent. Treat it as a tripwire, not authorization.

#TOCTOU between resolve and use

resolve(), exists(), stat(), and list() are explicitly advisory — they answer a question and return. stat() checks the exact selected target and parent while collecting metadata, and list() checks the exact selected directory around its complete batch, so detectable descendant redirection rejects before results are returned. Those checks do not preserve identity after the call. To act on a path with operation-local identity checks, use read(), open(), write(), create(), copyIn(), move(), or remove(). The containment table below states which opens are kernel-atomic and which remain best-effort.

A root() handle also remembers the canonical root directory identity. Calls fail with path-mismatch if that canonical pathname is replaced, including advisory inspection and walking calls, rather than following a replacement root into another tree.

#Denied mutations

denyMutations is an opt-in application policy for root() mutation methods. It blocks exact absolute paths with paths and whole subtrees with prefixes, merging root defaults with per-call entries so a call cannot clear root-level denies. POSIX pinned write, create, and copyIn copy the merged entries before awaiting preflight and reapply them to their admitted canonical parent, including before missing parent creation. This is not an OS permission boundary: code with access to node:fs, a shell, or another process with the same filesystem privileges can bypass it.

#Atomic writes

replaceFileAtomic writes to a sibling temp file in the destination directory, optionally fsyncs it, optionally fsyncs the parent directory after rename, and atomically renames over the destination. On failure mid-write, the destination is either the old contents (rename never happened) or the new contents (rename succeeded). There is no half-written intermediate state visible at the destination path unless the caller explicitly enables copyFallbackOnPermissionError, whose default copyFallbackRestore: "none" contract may leave a partial destination after a failed in-place fallback.

Within one process, async writes to the same target are queued so their temp-write/rename phases do not overlap. Cross-process writers still need an external protocol such as the sidecar lock helpers.

#Directory durability

pinDirectory() opens a directory without following its final component on POSIX, verifies the descriptor against the pathname identity and canonical path, and repeats those checks around synchronization. ensureDurableDirectory() pins the nearest existing ancestor and each newly created segment before synchronizing every new directory edge from the leaf upward.

Known Windows directory-flush limitations are returned as an explicit unsupported outcome. POSIX and other I/O failures propagate from the strict API. The separately named best-effort helpers intentionally provide no crash durability guarantee.

#Archive extraction

extractArchive first stages into a private temp directory (mode 0700) outside the destination, validates each entry path against .. and absolute prefixes, refuses link-type entries by default, enforces entry count and byte budgets, and only then merges the staged tree into the destination through the same boundary checks used by direct writes.

TAR extraction and bounded reads validate the complete decompressed raw framing before parser normalization: directory/link sizes must be zero, EOF must contain two consecutive zero blocks, and only zero padding may follow EOF. This rejects hidden headers and body/header smuggling consistently across the JavaScript and native backends. The meter checks logical member count before consuming bodies, even for unrequested or filtered members. Per-entry/cumulative payload budgets apply only to entries accepted after strip/filter policy, outside the raw meter. A separate absolute decoded cap includes every member body, headers, metadata, all padding, and EOF, closing cumulative-metadata and zero-tail bypasses. Native extraction/read passes drain through physical EOF before publication or returning selected bytes, even when the TAR parser stops earlier. Bounded reads use default archive admission limits and keep maxBytes scoped to the requested output. Metadata retains its per-record bound. See archive framing for supported metadata and compression formats.

#What "library-level" means

A library cannot revoke its own caller's authority. If your code chooses to bypass fs-safe and call fs.writeFile directly with the same path, you bypass the defenses too. The contract fs-safe enforces is: every filesystem operation that touches caller-controlled input goes through the boundary. That contract is yours to keep.

The library does not modify or constrain the global Node.js fs namespace, and it does not patch the runtime. Other code in the same process retains its normal filesystem authority.

#Containment guarantees by platform

openBeneath() and JavaScript open results report one of two factual containment classes:

The macOS F_GETPATH verification is an escape detector, not a race-atomic guarantee. A hostile same-UID process can rename a directory after O_RESOLVE_BENEATH or the manual walk and race the post-open sample or a later descriptor-relative mutation. The native result therefore remains best-effort on macOS even when the kernel flag is available. No policy decision is attached to these labels; callers can inspect the fact and decide what their own threat model requires.

The public OpenResult, ReadResult, and WritableOpenResult expose containment. Those root APIs currently report best-effort; direct native openBeneath() reports the platform value above. No-replace publication uses renameat2(RENAME_NOREPLACE) on Linux, renameatx_np(RENAME_EXCL) on macOS, and FileRenameInfoEx with replacement disabled on Windows, but those separate mutation semantics do not upgrade an open result's containment label.

#Limitations to keep in mind

#Recommended deployment shape

• Run worker code under a dedicated UID with the smallest filesystem privileges that still allow the worker to do its job.
• Mount the workspace directory writable; mount everything else read-only or not at all.
• Use fs-safe's root() for that workspace.
• For credentials, use secret files (mode 0600 in mode-0700 dirs) rather than the workspace.
• For scratch space, use a private temp workspace — don't reuse the workspace root.

#Reporting issues

Suspected security issues belong in private disclosure first. See SECURITY.md in the repo for the current contact path.