$ show openclaw/fs-safe
`@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.
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.
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.
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.
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.
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.