@openclaw/fs-safe 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.1.2 - 2026-05-06
+
+### Fixes
+
+- Reject `fileStore()` and `fileStoreSync()` writes through symlinked parent directories so store commits cannot escape the configured root.
+
+### Tests
+
+- Increased filesystem edge coverage around secure temp fallback handling, sibling-temp cleanup, local-root resolution, file locks, and file identity checks.
+- Prevented POSIX test runs from leaving Windows-style secure-temp fallback paths in the repository root.
+
+### Docs
+
+- Added missing docs pages for `@openclaw/fs-safe/config`, `@openclaw/fs-safe/store`, `@openclaw/fs-safe/advanced`, and `@openclaw/fs-safe/test-hooks`.
+- Corrected path-helper docs for the synchronous `isPathInsideWithRealpath` and `safeRealpathSync` behavior.
+- Included the Markdown docs in the npm package so README links resolve after install.
+
+## 0.1.1 - 2026-05-06
+
+### Fixes
+
+- Preserve the caller's destination path spelling during staged archive merges so symlink-rebind checks catch alias races on macOS.
+- Reject archive writes that gain a hardlink alias during post-write verification and clean up the destination file.
+
 ## 0.1.0 - 2026-05-06
 
 ### Features

package/README.md

@@ -1,4 +1,10 @@
-# @openclaw/fs-safe
+# 🛡️ @openclaw/fs-safe
+
+[![npm](https://img.shields.io/npm/v/@openclaw/fs-safe.svg?color=10b981&label=npm)](https://www.npmjs.com/package/@openclaw/fs-safe)
+[![ci](https://github.com/openclaw/fs-safe/actions/workflows/ci.yml/badge.svg)](https://github.com/openclaw/fs-safe/actions/workflows/ci.yml)
+[![node](https://img.shields.io/node/v/@openclaw/fs-safe.svg?color=10b981)](https://nodejs.org)
+[![license](https://img.shields.io/npm/l/@openclaw/fs-safe.svg?color=10b981)](LICENSE)
+[![docs](https://img.shields.io/badge/docs-fs--safe.io-10b981)](https://fs-safe.io)
 
 Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.
 
@@ -14,6 +20,12 @@ await fs.write("../escape.txt", "x");            // throws FsSafeError("outside-
 
 That's the whole pitch. `root()` is the product; the rest of the package — JSON stores, atomic writes, secret files, archive extraction, temp workspaces — is supporting cast for the same boundary.
 
+Full docs and reference at **[fs-safe.io](https://fs-safe.io)**.
+
+## Contents
+
+[Why this exists](#why-this-exists) · [Not a sandbox](#not-a-sandbox) · [Install](#install) · [Quick start](#quick-start) · [Reading](#reading) · [Subpaths](#subpaths) · [Failure semantics](#failure-semantics-in-the-name) · [Atomic writes](#atomic-writes) · [Stores](#stores) · [Secure absolute reads](#secure-absolute-file-reads) · [Walking](#directory-walking) · [Archive extraction](#archive-extraction) · [Path scopes](#advanced-path-scopes) · [Errors](#errors) · [Safety model](#safety-model) · [Limitations](#limitations)
+
 ## Why this exists
 
 Most Node code that has to touch caller-controlled paths reaches for:
@@ -26,6 +38,13 @@ That validates a *string*. It does not pin the file you opened, defend against a
 
 The same idea has landed in other languages. Go [added `os.Root` and `OpenInRoot`](https://go.dev/blog/osroot); Rust has had [`cap-std`](https://github.com/bytecodealliance/cap-std) for years. Node's `fs` is path-string-oriented and exposes flags like `O_NOFOLLOW` but not an ergonomic "operate inside this root" API. `fs-safe` fills that gap.
 
+| | Root boundary | Atomic writes | Symlink/hardlink defense | TOCTOU resistance | Archive extraction |
+|---|---|---|---|---|---|
+| `path.resolve().startsWith()` | string check only | – | – | – | – |
+| [`write-file-atomic`](https://www.npmjs.com/package/write-file-atomic) | – | ✓ | – | – | – |
+| Go [`os.Root`](https://go.dev/blog/osroot) / Rust [`cap-std`](https://github.com/bytecodealliance/cap-std) | ✓ | platform | ✓ | ✓ | – |
+| **`@openclaw/fs-safe`** | **✓** | **✓** | **✓** | **✓ (POSIX fd-relative)** | **✓ (ZIP/TAR)** |
+
 ## Not a sandbox
 
 This is a **library-level guardrail**, not OS-level isolation. It does not replace containers, seccomp, AppArmor, or filesystem permissions. It is for code that already runs with the privileges of its workspace and wants to stop trivial path tricks from escaping it. If your threat model is a hostile process, you need OS isolation; if your threat model is "an agent, plugin, upload handler, or CLI will eventually be tricked into writing somewhere it shouldn't," `fs-safe` catches that.
@@ -241,8 +260,9 @@ const opened = await media.open("inbound/photo.jpg");
 await media.pruneExpired({ ttlMs: 10 * 60 * 1000, recursive: true });
 ```
 
-`tempWorkspace()` also exposes `writeText()`, `writeJson()`, and `copyIn()` for
-single-file scratch workflows without hand-rolled path joins.
+`tempWorkspace()` exposes `write()`, `writeText()`, `writeJson()`, `copyIn()`, and `read()` for
+single-file scratch workflows without hand-rolled path joins, plus a `store: FileStore` view of
+the workspace dir for the richer cases (`writeStream`, `readJsonIfExists`, `store.json<T>(rel)`).
 
 `tempFile()` is the smaller one-file temp helper. It is intentionally an
 advanced primitive: use `tempWorkspace()` for the stable temp surface and reach

package/dist/archive-staging.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,wBAAwB,GAChC,2BAA2B,GAC3B,qBAAqB,GACrB,+BAA+B,CAAC;AAEpC,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,IAAI,EAAE,wBAAwB,CAAC;gBAEnB,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAKpF;AASD,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYnF;AA6CD,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBhB;AAmBD,wBAAsB,4BAA4B,CAAC,CAAC,EAAE,MAAM,EAAE;IAC5D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzC,GAAG,OAAO,CAAC,CAAC,CAAC,CAkBb;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,GAAG,OAAO,CAAC,IAAI,CAAC,CAyDhB;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}
+{"version":3,"file":"archive-staging.d.ts","sourceRoot":"","sources":["../src/archive-staging.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,wBAAwB,GAChC,2BAA2B,GAC3B,qBAAqB,GACrB,+BAA+B,CAAC;AAEpC,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,IAAI,EAAE,wBAAwB,CAAC;gBAEnB,IAAI,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAKpF;AASD,wBAAsB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYnF;AA6CD,wBAAsB,wBAAwB,CAAC,MAAM,EAAE;IACrD,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACtB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBhB;AAqDD,wBAAsB,4BAA4B,CAAC,CAAC,EAAE,MAAM,EAAE;IAC5D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACzC,GAAG,OAAO,CAAC,CAAC,CAAC,CAkBb;AAED,wBAAsB,iCAAiC,CAAC,MAAM,EAAE;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;CAC5B,GAAG,OAAO,CAAC,IAAI,CAAC,CAyEhB;AAED,wBAAgB,kCAAkC,CAAC,YAAY,EAAE,MAAM,GAAG,oBAAoB,CAE7F"}

package/dist/archive-staging.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { FsSafeError } from "./errors.js";
 import { root } from "./root.js";
 import { isNotFoundPathError, isPathInside } from "./path.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
@@ -95,6 +96,32 @@ async function applyStagedEntryMode(params) {
         await fs.chmod(destinationPath, params.mode).catch(() => undefined);
     }
 }
+async function assertExtractedFileHasNoHardlinkAlias(params) {
+    const destinationPath = path.join(params.destinationRealDir, params.relPath);
+    await assertResolvedInsideDestination({
+        destinationRealDir: params.destinationRealDir,
+        targetPath: destinationPath,
+        originalPath: params.originalPath,
+    });
+    const stat = await fs.lstat(destinationPath);
+    if (stat.isFile() && stat.nlink > 1) {
+        throw symlinkTraversalError(params.originalPath);
+    }
+}
+async function removeExtractedDestinationFile(params) {
+    const destinationPath = path.join(params.destinationRealDir, params.relPath);
+    let resolved;
+    try {
+        resolved = await fs.realpath(destinationPath);
+    }
+    catch {
+        return;
+    }
+    if (!isPathInside(params.destinationRealDir, resolved)) {
+        return;
+    }
+    await fs.rm(destinationPath, { force: true }).catch(() => undefined);
+}
 export async function withStagedArchiveDestination(params) {
     const stagingRoot = resolveSecureTempRoot({
         fallbackPrefix: "fs-safe-archive",
@@ -155,13 +182,30 @@ export async function mergeExtractedTreeIntoDestination(params) {
                 originalPath,
                 isDirectory: false,
             });
-            await targetRoot.copyIn(relPath, sourcePath, { mkdir: true });
-            await applyStagedEntryMode({
-                destinationRealDir: params.destinationRealDir,
-                relPath,
-                mode: sourceStat.mode & 0o777,
-                originalPath,
-            });
+            try {
+                await targetRoot.copyIn(relPath, sourcePath, { mkdir: true });
+                await assertExtractedFileHasNoHardlinkAlias({
+                    destinationRealDir: params.destinationRealDir,
+                    relPath,
+                    originalPath,
+                });
+                await applyStagedEntryMode({
+                    destinationRealDir: params.destinationRealDir,
+                    relPath,
+                    mode: sourceStat.mode & 0o777,
+                    originalPath,
+                });
+            }
+            catch (err) {
+                await removeExtractedDestinationFile({
+                    destinationRealDir: params.destinationRealDir,
+                    relPath,
+                });
+                if (err instanceof FsSafeError && (err.code === "hardlink" || err.code === "path-alias")) {
+                    throw symlinkTraversalError(originalPath);
+                }
+                throw err;
+            }
         }
     };
     await walk(params.sourceDir);

package/dist/archive.js

@@ -168,7 +168,7 @@ async function extractZip(params) {
             }
             await mergeExtractedTreeIntoDestination({
                 sourceDir: stagingRealDir,
-                destinationDir: destinationRealDir,
+                destinationDir: params.destDir,
                 destinationRealDir,
             });
         },
@@ -223,7 +223,7 @@ export async function extractArchive(params) {
                     });
                     await mergeExtractedTreeIntoDestination({
                         sourceDir: stagingDir,
-                        destinationDir: destinationRealDir,
+                        destinationDir: params.destDir,
                         destinationRealDir,
                     });
                 },

package/dist/file-store-boundary.d.ts

@@ -0,0 +1,27 @@
+import { type Readable } from "node:stream";
+import { type Root } from "./root.js";
+export type SyncParentGuard = {
+    dir: string;
+    realPath: string;
+};
+export declare function ensureParentInRoot(scopedRoot: Root, relativePath: string, mode: number): Promise<void>;
+export declare function openWritableStoreRoot(params: {
+    rootDir: string;
+    dirMode: number;
+    maxBytes?: number;
+}): Promise<Root>;
+export declare function writeStreamToTempSource(params: {
+    stream: Readable;
+    maxBytes?: number;
+    mode: number;
+}): Promise<{
+    path: string;
+    cleanup: () => Promise<void>;
+}>;
+export declare function assertSyncDirectoryGuard(guard: SyncParentGuard): void;
+export declare function ensureParentSync(params: {
+    rootDir: string;
+    filePath: string;
+    mode: number;
+}): SyncParentGuard;
+//# sourceMappingURL=file-store-boundary.d.ts.map

package/dist/file-store-boundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-store-boundary.d.ts","sourceRoot":"","sources":["../src/file-store-boundary.ts"],"names":[],"mappings":"AAGA,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAIvD,OAAO,EAA4C,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAGhF,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAOF,wBAAsB,kBAAkB,CACtC,UAAU,EAAE,IAAI,EAChB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIhB;AA+CD,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,MAAM,EAAE,QAAQ,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC,CAuC1D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI,CASrE;AAUD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,eAAe,CAwClB"}

package/dist/file-store-boundary.js

@@ -0,0 +1,164 @@
+import syncFs from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { FsSafeError } from "./errors.js";
+import { isPathInside } from "./path.js";
+import { resolveOpenedFileRealPathForHandle, root } from "./root.js";
+import { resolveSecureTempRoot } from "./secure-temp-dir.js";
+function parentRelativePath(relativePath) {
+    const parent = path.posix.dirname(relativePath);
+    return parent === "." ? "" : parent;
+}
+export async function ensureParentInRoot(scopedRoot, relativePath, mode) {
+    const parent = parentRelativePath(relativePath);
+    if (!parent) {
+        return;
+    }
+    await scopedRoot.mkdir(parent);
+    await chmodDirectoryInRootBestEffort(scopedRoot, parent, mode).catch(() => undefined);
+}
+export async function openWritableStoreRoot(params) {
+    await fs.mkdir(params.rootDir, { recursive: true, mode: params.dirMode });
+    await fs.chmod(params.rootDir, params.dirMode).catch(() => undefined);
+    return await root(params.rootDir, { hardlinks: "reject", maxBytes: params.maxBytes });
+}
+async function chmodDirectoryInRootBestEffort(scopedRoot, relativePath, mode) {
+    const dirPath = await scopedRoot.resolve(relativePath);
+    const directoryFlag = "O_DIRECTORY" in syncFs.constants ? syncFs.constants.O_DIRECTORY : 0;
+    const noFollowFlag = process.platform !== "win32" && "O_NOFOLLOW" in syncFs.constants
+        ? syncFs.constants.O_NOFOLLOW
+        : 0;
+    const handle = await fs.open(dirPath, syncFs.constants.O_RDONLY | directoryFlag | noFollowFlag);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isDirectory()) {
+            return;
+        }
+        const realPath = await resolveOpenedFileRealPathForHandle(handle, dirPath);
+        if (!isPathInside(scopedRoot.rootWithSep, realPath)) {
+            throw new FsSafeError("outside-workspace", "directory is outside store root");
+        }
+        await handle.chmod(mode).catch(() => undefined);
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+function createMaxBytesTransform(maxBytes) {
+    if (maxBytes === undefined) {
+        return undefined;
+    }
+    let total = 0;
+    return new Transform({
+        transform(chunk, _encoding, callback) {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            total += buffer.byteLength;
+            if (total > maxBytes) {
+                callback(new FsSafeError("too-large", `file exceeds maximum size of ${maxBytes} bytes`));
+                return;
+            }
+            callback(null, buffer);
+        },
+    });
+}
+export async function writeStreamToTempSource(params) {
+    const tempRoot = resolveSecureTempRoot({
+        fallbackPrefix: "fs-safe-file-store",
+        unsafeFallbackLabel: "file store temp dir",
+        warn: () => undefined,
+    });
+    const dir = await fs.mkdtemp(path.join(tempRoot, "fs-safe-file-store-"));
+    const filePath = path.join(dir, "payload");
+    let handle = null;
+    let handleClosedByStream = false;
+    try {
+        handle = await fs.open(filePath, "wx", params.mode);
+        const writable = handle.createWriteStream();
+        writable.once("close", () => {
+            handleClosedByStream = true;
+        });
+        const limiter = createMaxBytesTransform(params.maxBytes);
+        if (limiter) {
+            await pipeline(params.stream, limiter, writable);
+        }
+        else {
+            await pipeline(params.stream, writable);
+        }
+        if (!handleClosedByStream) {
+            await handle.close().catch(() => undefined);
+        }
+        await fs.chmod(filePath, params.mode).catch(() => undefined);
+        return {
+            path: filePath,
+            cleanup: async () => {
+                await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
+            },
+        };
+    }
+    catch (err) {
+        if (handle && !handleClosedByStream) {
+            await handle.close().catch(() => undefined);
+        }
+        await fs.rm(dir, { recursive: true, force: true }).catch(() => undefined);
+        throw err;
+    }
+}
+export function assertSyncDirectoryGuard(guard) {
+    const stat = syncFs.lstatSync(guard.dir);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new FsSafeError("not-file", `store directory component must be a directory: ${guard.dir}`);
+    }
+    const realPath = syncFs.realpathSync(guard.dir);
+    if (realPath !== guard.realPath) {
+        throw new FsSafeError("path-mismatch", "store directory changed during write");
+    }
+}
+function chmodDirectorySyncBestEffort(dir, mode) {
+    try {
+        syncFs.chmodSync(dir, mode);
+    }
+    catch {
+        // Best-effort on platforms that do not enforce POSIX modes.
+    }
+}
+export function ensureParentSync(params) {
+    const rootDir = path.resolve(params.rootDir);
+    const dir = path.dirname(path.resolve(params.filePath));
+    const relative = path.relative(rootDir, dir);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        throw new FsSafeError("outside-workspace", "file path escapes store root");
+    }
+    syncFs.mkdirSync(rootDir, { recursive: true, mode: params.mode });
+    const rootStat = syncFs.lstatSync(rootDir);
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+        throw new FsSafeError("not-file", `store root must be a directory: ${rootDir}`);
+    }
+    const rootReal = syncFs.realpathSync(rootDir);
+    chmodDirectorySyncBestEffort(rootDir, params.mode);
+    let current = rootDir;
+    for (const segment of path.relative(rootDir, dir).split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        try {
+            const stat = syncFs.lstatSync(current);
+            if (stat.isSymbolicLink() || !stat.isDirectory()) {
+                throw new FsSafeError("not-file", `store directory component must be a directory: ${current}`);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+            syncFs.mkdirSync(current, { mode: params.mode });
+        }
+        const currentReal = syncFs.realpathSync(current);
+        if (!isPathInside(rootReal, currentReal)) {
+            throw new FsSafeError("outside-workspace", "store directory escapes root");
+        }
+        chmodDirectorySyncBestEffort(current, params.mode);
+    }
+    const guard = { dir, realPath: syncFs.realpathSync(dir) };
+    assertSyncDirectoryGuard(guard);
+    return guard;
+}

package/dist/file-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../src/file-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../src/file-store.ts"],"names":[],"mappings":"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"}

package/dist/file-store.js

@@ -2,13 +2,12 @@ import { randomUUID } from "node:crypto";
 import syncFs from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { pipeline } from "node:stream/promises";
 import { FsSafeError } from "./errors.js";
+import { assertSyncDirectoryGuard, ensureParentInRoot, ensureParentSync, openWritableStoreRoot, writeStreamToTempSource, } from "./file-store-boundary.js";
 import { createJsonStore } from "./json-document-store.js";
 import { isPathInside, resolveSafeRelativePath } from "./path.js";
 import { root } from "./root.js";
 import { writeSecretFileAtomic } from "./secret-file.js";
-import { writeSiblingTempFile } from "./sibling-temp.js";
 function assertRelativePath(relativePath) {
     const raw = relativePath.trim();
     if (!raw) {
@@ -24,11 +23,6 @@ function assertStoreFilePath(rootDir, filePath) {
         throw new FsSafeError("outside-workspace", "file path escapes store root");
     }
 }
-async function ensureParent(filePath, mode) {
-    const dir = path.dirname(filePath);
-    await fs.mkdir(dir, { recursive: true, mode });
-    await fs.chmod(dir, mode).catch(() => undefined);
-}
 function assertMaxBytes(size, maxBytes) {
     if (maxBytes !== undefined && size > maxBytes) {
         throw new FsSafeError("too-large", `file exceeds maximum size of ${maxBytes} bytes`);
@@ -41,26 +35,26 @@ function isNotFound(error) {
             error.code === "ENOTDIR";
 }
 async function copyIntoRoot(params) {
-    const destination = resolveStorePath(params.rootDir, params.relativePath);
+    const relativePath = assertRelativePath(params.relativePath);
+    const destination = resolveStorePath(params.rootDir, relativePath);
     const sourceStat = await fs.lstat(params.sourcePath);
     if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
         throw new FsSafeError("not-file", "source path is not a file");
     }
     assertMaxBytes(sourceStat.size, params.maxBytes);
-    await ensureParent(destination, params.dirMode ?? 0o700);
-    const result = await writeSiblingTempFile({
-        dir: path.dirname(destination),
-        dirMode: params.dirMode ?? 0o700,
+    const dirMode = params.dirMode ?? 0o700;
+    const scopedRoot = await openWritableStoreRoot({
+        rootDir: params.rootDir,
+        dirMode,
+        maxBytes: params.maxBytes,
+    });
+    await ensureParentInRoot(scopedRoot, relativePath, dirMode);
+    await scopedRoot.copyIn(relativePath, params.sourcePath, {
+        maxBytes: params.maxBytes,
+        mkdir: false,
         mode: params.mode ?? 0o600,
-        tempPrefix: params.tempPrefix ?? `.${path.basename(destination)}`,
-        writeTemp: async (tempPath) => {
-            await fs.copyFile(params.sourcePath, tempPath);
-        },
-        resolveFinalPath: () => destination,
-        syncTempFile: true,
-        syncParentDir: true,
     });
-    return result.filePath;
+    return destination;
 }
 export function fileStore(options) {
     const rootDir = path.resolve(options.rootDir);
@@ -72,7 +66,8 @@ export function fileStore(options) {
         return await root(rootDir, { hardlinks: "reject", maxBytes });
     }
     async function write(relativePath, data, writeOptions) {
-        const destination = resolveStorePath(rootDir, relativePath);
+        const safeRelativePath = assertRelativePath(relativePath);
+        const destination = resolveStorePath(rootDir, safeRelativePath);
         const content = Buffer.isBuffer(data) ? data : Buffer.from(data);
         assertMaxBytes(content.byteLength, writeOptions?.maxBytes ?? maxBytes);
         if (privateMode) {
@@ -85,20 +80,18 @@ export function fileStore(options) {
             });
             return destination;
         }
-        await ensureParent(destination, writeOptions?.dirMode ?? dirMode);
-        const result = await writeSiblingTempFile({
-            dir: path.dirname(destination),
-            dirMode: writeOptions?.dirMode ?? dirMode,
+        const writeDirMode = writeOptions?.dirMode ?? dirMode;
+        const scopedRoot = await openWritableStoreRoot({
+            rootDir,
+            dirMode: writeDirMode,
+            maxBytes: writeOptions?.maxBytes ?? maxBytes,
+        });
+        await ensureParentInRoot(scopedRoot, safeRelativePath, writeDirMode);
+        await scopedRoot.write(safeRelativePath, content, {
+            mkdir: false,
             mode: writeOptions?.mode ?? mode,
-            tempPrefix: writeOptions?.tempPrefix ?? `.${path.basename(destination)}`,
-            writeTemp: async (tempPath) => {
-                await fs.writeFile(tempPath, content);
-            },
-            resolveFinalPath: () => destination,
-            syncTempFile: true,
-            syncParentDir: true,
         });
-        return result.filePath;
+        return destination;
     }
     return {
         rootDir,
@@ -106,7 +99,8 @@ export function fileStore(options) {
         root: openRoot,
         write,
         writeStream: async (relativePath, stream, writeOptions) => {
-            const destination = resolveStorePath(rootDir, relativePath);
+            const safeRelativePath = assertRelativePath(relativePath);
+            const destination = resolveStorePath(rootDir, safeRelativePath);
             const limit = writeOptions?.maxBytes ?? maxBytes;
             if (privateMode) {
                 const chunks = [];
@@ -126,34 +120,26 @@ export function fileStore(options) {
                 });
                 return destination;
             }
-            await ensureParent(destination, writeOptions?.dirMode ?? dirMode);
-            let total = 0;
-            const result = await writeSiblingTempFile({
-                dir: path.dirname(destination),
-                dirMode: writeOptions?.dirMode ?? dirMode,
+            const staged = await writeStreamToTempSource({
+                stream,
+                maxBytes: limit,
                 mode: writeOptions?.mode ?? mode,
-                tempPrefix: writeOptions?.tempPrefix ?? `.${path.basename(destination)}`,
-                writeTemp: async (tempPath) => {
-                    const writable = await fs.open(tempPath, "w", writeOptions?.mode ?? mode);
-                    try {
-                        const out = writable.createWriteStream();
-                        stream.on("data", (chunk) => {
-                            total += Buffer.byteLength(chunk);
-                            if (limit !== undefined && total > limit) {
-                                stream.destroy(new FsSafeError("too-large", `file exceeds maximum size of ${limit} bytes`));
-                            }
-                        });
-                        await pipeline(stream, out);
-                    }
-                    finally {
-                        await writable.close().catch(() => undefined);
-                    }
-                },
-                resolveFinalPath: () => destination,
-                syncTempFile: true,
-                syncParentDir: true,
             });
-            return result.filePath;
+            try {
+                await copyIntoRoot({
+                    rootDir,
+                    relativePath: safeRelativePath,
+                    sourcePath: staged.path,
+                    maxBytes: limit,
+                    mode: writeOptions?.mode ?? mode,
+                    tempPrefix: writeOptions?.tempPrefix,
+                    dirMode: writeOptions?.dirMode ?? dirMode,
+                });
+            }
+            finally {
+                await staged.cleanup();
+            }
+            return destination;
         },
         copyIn: async (relativePath, sourcePath, writeOptions) => privateMode
             ? await (async () => {
@@ -274,16 +260,6 @@ export function fileStore(options) {
         },
     };
 }
-function ensureParentSync(filePath, mode) {
-    const dir = path.dirname(filePath);
-    syncFs.mkdirSync(dir, { recursive: true, mode });
-    try {
-        syncFs.chmodSync(dir, mode);
-    }
-    catch {
-        // Best-effort on platforms that do not enforce POSIX modes.
-    }
-}
 function ensurePrivateDirectorySync(rootDir, targetDir, mode) {
     const root = path.resolve(rootDir);
     const target = path.resolve(targetDir);
@@ -330,6 +306,7 @@ function ensurePrivateDirectorySync(rootDir, targetDir, mode) {
 function writeFileSyncAtomic(params) {
     const filePath = path.resolve(params.filePath);
     assertStoreFilePath(params.rootDir, filePath);
+    let parentGuard;
     if (params.privateMode) {
         ensurePrivateDirectorySync(params.rootDir, path.dirname(filePath), params.dirMode);
         try {
@@ -345,11 +322,18 @@ function writeFileSyncAtomic(params) {
         }
     }
     else {
-        ensureParentSync(filePath, params.dirMode);
+        parentGuard = ensureParentSync({
+            rootDir: params.rootDir,
+            filePath,
+            mode: params.dirMode,
+        });
     }
-    const tempPath = path.join(path.dirname(filePath), `.fs-safe-${process.pid}-${randomUUID()}.tmp`);
+    const tempPath = path.join(parentGuard?.dir ?? path.dirname(filePath), `.fs-safe-${process.pid}-${randomUUID()}.tmp`);
     let tempExists = false;
     try {
+        if (parentGuard) {
+            assertSyncDirectoryGuard(parentGuard);
+        }
         syncFs.writeFileSync(tempPath, params.content, { flag: "wx", mode: params.mode });
         tempExists = true;
         try {
@@ -358,8 +342,14 @@ function writeFileSyncAtomic(params) {
         catch {
             // Best-effort on platforms that do not enforce POSIX modes.
         }
+        if (parentGuard) {
+            assertSyncDirectoryGuard(parentGuard);
+        }
         syncFs.renameSync(tempPath, filePath);
         tempExists = false;
+        if (parentGuard) {
+            assertSyncDirectoryGuard(parentGuard);
+        }
         try {
             syncFs.chmodSync(filePath, params.mode);
         }

package/dist/path.d.ts

@@ -2,6 +2,7 @@ import fs from "node:fs";
 export declare function normalizeWindowsPathForComparison(input: string): string;
 export declare function isNodeError(value: unknown): value is NodeJS.ErrnoException;
 export declare function hasNodeErrorCode(value: unknown, code: string): boolean;
+export declare function assertNoNulPathInput(filePath: string, message?: string): void;
 export declare function isNotFoundPathError(value: unknown): boolean;
 export declare function isSymlinkOpenError(value: unknown): boolean;
 export declare function isPathInside(root: string, target: string): boolean;

package/dist/path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAWzB,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASvE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,cAAc,CAI1E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CA0BlE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAExE;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAa/F;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAChE,OAAO,CAUT;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,EAAE,CAAC,KAAK,GAAG,IAAI,CAMhE;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAyBpE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAOrF"}
+{"version":3,"file":"path.d.ts","sourceRoot":"","sources":["../src/path.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAWzB,wBAAgB,iCAAiC,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASvE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,cAAc,CAI1E;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,SAA6B,GAAG,IAAI,CAIjG;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE1D;AAED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CA0BlE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG1D;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAExE;AAED,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,IAAI,CAa/F;AAED,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAChE,OAAO,CAUT;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,EAAE,CAAC,KAAK,GAAG,IAAI,CAMhE;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAuBpE;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAOrF"}