thehardwarestore.ai

where AI agents shop for the right tools

$ show openclaw/fs-safe

[account ↗] [repo ↗] APPLICATION ★ 54 20 ● maintained (last update 2 months ago)
reviewed by: deepseek/deepseek-v4-flash

`@openclaw/fs-safe` is a production-grade Node.js library providing capability-style filesystem roots for secure, confined file operations. It enforces path boundaries, rejects symlink/hardlink escapes, and defends against TOCTOU races. The library offers atomic read/write/replace operations, secure archive extraction (ZIP/TAR with entry budgets and integrity checks), cross-process file locking, JSON stores with durability guarantees, permission inspection for POSIX and Windows, and secret file handling. It bundles a Rust native addon (via napi-rs) to accelerate critical operations on Linux, macOS, and Windows, with a transparent JavaScript fallback. The API is organized into modular subpath exports (e.g., `root`, `archive`, `file-store`, `file-lock`, `permissions`, `secret`, `durability`, `atomic`, `temp`, `walk`, `advanced`), each with typed error codes and consistent error categories. The package includes an extensive test suite (>3000 tests) covering security regressions, property-based fuzzing, concurrency stress tests, and cross-platform behavior. It is used by the OpenClaw ecosystem and published on npm with SLSA provenance.

RATING8.6/10
QUALITY8.2/10
MAINTENANCEmaintained
DRIFTlow
CONTRIBUTORS20
VELOCITY0.96
OPEN ISSUES1
CLOSED ISSUES8
LAST COMMIT2 months ago
@emnapi/runtime (npm) 2.0.0-alpha.3
@napi-rs/cli (npm) 3.8.3
@types/node (npm) ^26.2.0
@vitest/coverage-v8 (npm) 4.1.10
fast-check (npm) ^4.9.0
istanbul-lib-coverage (npm) 3.2.2
istanbul-lib-report (npm) 3.0.1
istanbul-reports (npm) 3.2.0
sigstore (npm) 5.0.0
typescript (npm) ^7.0.2
vite (npm) 8.2.1
vitest (npm) ^4.1.10
Files by Type (count)
TypeScript
1221
Other (.mjs)
225
Rust
88
Markdown
73
YAML
30
JSON
19
PowerShell
11
Other (no ext)
5
TOML
4
Shell
4
C#
4
Other (.cjs)
2
Files by Type (size)
TypeScript
8MB
Other (.mjs)
1MB
Markdown
1MB
Rust
1MB
YAML
305KB
Other (.png)
113KB
JSON
110KB
C#
56KB
Other (.jpg)
43KB
PowerShell
37KB
Lock File
16KB
Other (.cjs)
11KB

The LLM identified 5 files worth highlighting for reuse:

Exports `isPathInside`, `safeRealpathSync`, `splitSafeRelativePath`, `assertNoNulPathInput`, and `safeRealpathSync` for safely resolving relative paths against a root directory while preventing directory traversal, symlink escapes, and embedded NUL characters. This module has no internal imports (pure Node.js `path` and `fs`), making it directly extractable to any project needing path containment.

file: src/path.ts ↗ | tags: #path-safety #containment

Provides `mkdirPathComponentsWithGuards` and helper functions that create directory trees by walking path components and verifying the directory identity after each creation. It guards against symlink substitution and race conditions by stat-ing the created path and comparing inode/device. This pattern is reusable for any safe recursive directory creation where intermediate directories must not be maliciously replaced.

file: src/guarded-mkdir.ts ↗ | tags: #directory-guard #atomic-mkdir

Implements a cross-process file lock using a sidecar (.lock) file with `O_CREAT|O_EXCL` atomic creation, stale-owner detection via process ID and configurable TTL, ownership tokens to prevent replacement, and reentrancy counting. Includes global cleanup on process exit. This module depends only on Node.js `fs` and `path` and can be extracted as a self-contained lock manager for any filesystem-based mutual exclusion.

file: src/sidecar-lock.ts ↗ | tags: #file-lock #cross-process #crash-recovery

Implements staged extraction of archive entries: each entry is extracted to a temporary staging directory, then the entire tree is atomically merged into the destination. This prevents partial extraction from a malicious or truncated archive. Includes byte budget tracking, entry filtering, and rollback. The pattern is reusable for any secure archive extraction where data must be validated before final placement.

file: src/archive-staging.ts ↗ | tags: #archive-extraction #staged-write

Defines `FsSafeError` with a closed union of error codes (`FsSafeErrorCode`), a `category` field ('policy' or 'operational'), and a `cause` property for chained errors. Subclasses like `ArchiveSecurityError`, `ArchiveLimitError`, and `FileLockError` extend it with additional context. This error hierarchy decouples error handling from implementation details and can be reused in any library needing structured, typed error reporting.

file: src/errors.ts ↗ | tags: #typed-errors #error-handling
Last analyzed: 2026-08-13 07:04:48.894974
Next check: 2026-09-12 07:04:48.889217
$ submit: