fs-safe
github.com/openclaw/fs-safe- Category
- Developer Tools
- Rank
- No. 900Tools index
- Pricing
- Open Source
- Type
- TOOL
- Builder
- openclaw
- GitHub
- 54 stars
- Latest release
- v0.8.6
- Date
About
Race-resistant root-bounded filesystem primitives for Node.js — safe by construction against directory traversal and TOCTOU bugs.
What it does
It gives Node.js applications a trusted directory handle for reads, writes, moves, deletion, JSON storage, temporary workspaces, and archive extraction. Operations stay relative to that directory, with checks against traversal, link tricks, rename races, unsafe device paths, and unintended replacement.
Why it's ranked here
A strong choice when application code accepts caller-controlled paths. Its value comes from a coherent boundary across many filesystem operations, explicit containment reporting, and native primitives where available. The verdict is tempered by weaker guarantees outside Linux native opens and by its clear status as a guardrail, not isolation.
What's good
The security model is unusually explicit. Results distinguish kernel-atomic containment from best-effort handling. Native mode pins directory descriptors for publication and replacement, while fallback mode retains canonical checks, no-follow opens, guarded temporary writes, and post-write identity verification. Archive handling also rejects links, duplicate paths, device entries, and configured size excesses.
Tradeoffs
Node 22 or newer is required. Bundling binaries for seven targets makes installation deterministic but enlarges the package. ZIP and TAR support depends on optional packages, while zstd and bzip2 archives require a supported native binding. macOS, Windows, and JavaScript containment remain best-effort against hostile concurrent mutation.
How to use it well
Use it in agents, plugins, upload handlers, and command-line tools that operate inside a trusted workspace while accepting untrusted relative paths. Require native mode when concurrent hostile mutation matters, and inspect the reported containment class. Keep containers, operating-system permissions, seccomp, or AppArmor for hostile-process isolation.
Technical notes+
package.json defines an ESM Node.js library requiring Node 22, publishes typed main and focused subpath exports, and lists jszip and tar as optional dependencies. Cargo.toml declares the native Rust workspace. src/index.ts exposes root handling, typed errors, native configuration, lock configuration, and external writes. src/containment.ts limits the reported guarantee to "kernel-atomic" or "best-effort". src/archive.ts stages extraction, applies deadlines and byte budgets, writes through sibling temporary files, and selects native or JavaScript paths. src/archive-tar.ts blocks links, devices, FIFOs, and sockets during preflight.
Observed
- License
- MIT
- Primary implementation
- TypeScript Node.js library with a Rust native workspace
- Package
- Public ESM npm package named @openclaw/fs-safe
- Runtime requirement
- Node.js 22 or newer
- Interface
- Library API with typed main and focused subpath exports
- Native packaging
- Prebuilt bindings for seven supported targets ship in the package without postinstall downloads or consumer Rust builds
- Platform guarantees
- Linux native opens report kernel-atomic containment; macOS, Windows, and guarded JavaScript paths report best-effort containment
Read from README.md, Cargo.toml, package.json, src/index.ts, src/atomic.ts, src/config.ts, src/archive.ts, src/advanced.ts, src/async-lock.ts, src/durability.ts, src/archive-tar.ts, src/containment.ts, src/device-path.ts, src/archive-kind.ts, src/archive-read.ts.
What it can do
Perform safe filesystem operations within a root directory boundary
File paths and root directory specification → Filesystem operations that cannot escape the root boundary
Prevent directory traversal attacks
User-provided file paths with potential traversal attempts → Validated paths that remain within allowed directories
Eliminate TOCTOU (Time-of-Check-Time-of-Use) race conditions
Concurrent filesystem operations → Race-resistant filesystem operations with consistent state
Validate file paths against root boundaries
File paths and root directory constraints → Boolean validation results or sanitized paths
Provide secure file reading operations
File paths within defined boundaries → File contents with security guarantees
Provide secure file writing operations
File paths and content within defined boundaries → Written files with path traversal protection
Tags
Tech Stack
Media
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.