@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/root-directory-list.d.ts

@@ -1,9 +1,21 @@
-import type { Stats } from "node:fs";
+import type { BigIntStats, Stats } from "node:fs";
+import { type AsyncDirectoryGuard } from "./directory-guard.js";
 import { type RootContext } from "./root-context.js";
+import type { RootPathDirectoryObservationGuard, RootPathObservationReceipt, RootPathParentObservationReceipt } from "./root-path.js";
 import type { DirEntry, PathStat } from "./types.js";
-export declare function pathStatFromStats(stat: Stats): PathStat;
-export declare function listDirectoryPath(root: RootContext, directory: string, withFileTypes: true): Promise<DirEntry[]>;
-export declare function listDirectoryPath(root: RootContext, directory: string, withFileTypes: boolean): Promise<string[] | DirEntry[]>;
+export declare function pathStatFromStats(stat: Stats | BigIntStats): PathStat;
+export type RootDirectoryObservationGuard = AsyncDirectoryGuard<BigIntStats>;
+export declare function createRootDirectoryObservationGuard(root: RootContext, directory: string): Promise<RootDirectoryObservationGuard>;
+export declare function assertRootDirectoryObservationGuard(root: RootContext, guard: RootDirectoryObservationGuard | RootPathDirectoryObservationGuard): Promise<void>;
+/**
+ * Close an operation-local traversal receipt with fresh exact observations.
+ * Descendant canonical paths are admitted while the receipt is created. The
+ * final directory check repeats canonical admission; the Root-only case does
+ * both its identity and canonical check here.
+ */
+export declare function assertRootPathObservationReceiptCurrent(root: RootContext, receipt: RootPathObservationReceipt | RootPathParentObservationReceipt, finalTarget?: Stats | BigIntStats): void;
+export declare function listDirectoryPath(root: RootContext, directory: string, withFileTypes: true, receipt?: RootPathObservationReceipt): Promise<DirEntry[]>;
+export declare function listDirectoryPath(root: RootContext, directory: string, withFileTypes: boolean, receipt?: RootPathObservationReceipt): Promise<string[] | DirEntry[]>;
 export type RootDirectoryListing = {
     next(): Promise<{
         kind: "entry";

package/dist/root-directory-list.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-directory-list.d.ts","sourceRoot":"","sources":["../src/root-directory-list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAQ1C,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhF,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIrD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,KAAK,GAAG,QAAQ,CAcvD;AAWD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;AAClH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;AAqBhI,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;IAClG,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,KAAK,EAAE,QAAQ,GAAG,YAAY,CAAC;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,IAAI,OAAO,CAAC;CACvB,CAAC;AAEF,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,oBAAoB,CAAC,CAsJ/B"}
+{"version":3,"file":"root-directory-list.d.ts","sourceRoot":"","sources":["../src/root-directory-list.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAKvD,OAAO,EAKL,KAAK,mBAAmB,EAEzB,MAAM,sBAAsB,CAAC;AAQ9B,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhF,OAAO,KAAK,EACV,iCAAiC,EACjC,0BAA0B,EAC1B,gCAAgC,EACjC,MAAM,gBAAgB,CAAC;AAKxB,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAIrD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,KAAK,GAAG,WAAW,GAAG,QAAQ,CAmBrE;AAED,MAAM,MAAM,6BAA6B,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAAC;AAE7E,wBAAsB,mCAAmC,CACvD,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,6BAA6B,CAAC,CAaxC;AASD,wBAAsB,mCAAmC,CACvD,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,6BAA6B,GAAG,iCAAiC,GACvE,OAAO,CAAC,IAAI,CAAC,CAuBf;AAiCD;;;;;GAKG;AACH,wBAAgB,uCAAuC,CACrD,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,0BAA0B,GAAG,gCAAgC,EACtE,WAAW,CAAC,EAAE,KAAK,GAAG,WAAW,GAChC,IAAI,CAgCN;AAkBD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,IAAI,EACnB,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;AACvB,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,EACjB,aAAa,EAAE,OAAO,EACtB,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAAC,MAAM,EAAE,GAAG,QAAQ,EAAE,CAAC,CAAC;AAoElC,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAA;KAAE,GAAG;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAC;IAClG,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,KAAK,EAAE,QAAQ,GAAG,YAAY,CAAC;IAC/B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,IAAI,OAAO,CAAC;CACvB,CAAC;AAEF,wBAAsB,wBAAwB,CAC5C,IAAI,EAAE,WAAW,EACjB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,oBAAoB,CAAC,CAuI/B"}

package/dist/root-directory-list.js

@@ -2,14 +2,23 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { setImmediate as yieldToEventLoop } from "node:timers/promises";
-import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { assertAsyncDirectoryGuard, assertDirectoryObservationGuardSync, assertDirectoryObservationSync, createAsyncDirectoryGuard, } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
-import { isNotFoundPathError, isPathInside } from "./path.js";
+import { inspectNativeDirectoryObservation, isNativeDirectoryObservationGuard, } from "./native-directory-observation.js";
+import { isNotFoundPathError } from "./path.js";
 import { assertRootIdentityCurrent } from "./root-context.js";
 import { rootPathChangedError } from "./root-errors.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
 import { createSuppressedError } from "./suppressed-error.js";
+import { realpathSync } from "./realpath.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
 const METADATA_BATCH_SIZE = 32;
 export function pathStatFromStats(stat) {
+    const mtimeMs = typeof stat.mtimeMs === "bigint"
+        ? "mtimeNs" in stat && typeof stat.mtimeNs === "bigint"
+            ? Number(stat.mtimeNs) / 1_000_000
+            : stat.mtime.getTime()
+        : stat.mtimeMs;
     return {
         dev: Number(stat.dev),
         gid: Number(stat.gid),
@@ -17,13 +26,129 @@ export function pathStatFromStats(stat) {
         isDirectory: stat.isDirectory(),
         isFile: stat.isFile(),
         isSymbolicLink: stat.isSymbolicLink(),
-        mode: stat.mode,
-        mtimeMs: stat.mtimeMs,
-        nlink: stat.nlink,
-        size: stat.size,
-        uid: stat.uid,
+        mode: Number(stat.mode),
+        mtimeMs,
+        nlink: Number(stat.nlink),
+        size: Number(stat.size),
+        uid: Number(stat.uid),
     };
 }
+export async function createRootDirectoryObservationGuard(root, directory) {
+    const guard = await createAsyncDirectoryGuard(directory, { bigint: true });
+    const admittedRealPath = admitPathInsideRoot({
+        rootPath: root.rootReal,
+        candidatePath: guard.realPath,
+        rootIdentity: root.rootIdentity,
+    });
+    if (!admittedRealPath) {
+        throw new FsSafeError("outside-workspace", "directory is outside workspace root");
+    }
+    guard.dir = admittedRealPath.path;
+    guard.realPath = admittedRealPath.path;
+    return guard;
+}
+function directoryChangedError(error) {
+    if (error instanceof FsSafeError && error.code === "path-mismatch")
+        return error;
+    return new FsSafeError("path-mismatch", "directory changed during operation", {
+        cause: error instanceof Error ? error : undefined,
+    });
+}
+export async function assertRootDirectoryObservationGuard(root, guard) {
+    if (isNativeDirectoryObservationGuard(guard)) {
+        throw new FsSafeError("path-mismatch", "native directory observation cannot be revalidated");
+    }
+    const identity = "identity" in guard ? guard.identity : guard.stat;
+    const guardPinsRoot = guard.dir === root.rootReal &&
+        identity.dev === root.rootIdentity.dev && identity.ino === root.rootIdentity.ino;
+    if (guardPinsRoot) {
+        try {
+            if ("identity" in guard)
+                assertDirectoryObservationGuardSync(guard);
+            else
+                await assertAsyncDirectoryGuard(guard);
+        }
+        catch (error) {
+            throw rootPathChangedError(error instanceof Error ? error : undefined);
+        }
+        return;
+    }
+    await assertRootIdentityCurrent(root);
+    try {
+        if ("identity" in guard)
+            assertDirectoryObservationGuardSync(guard);
+        else
+            await assertAsyncDirectoryGuard(guard);
+    }
+    catch (error) {
+        throw directoryChangedError(error);
+    }
+}
+function sameObservationDirectory(left, right) {
+    return left.dir === right.dir && left.realPath === right.realPath &&
+        left.identity.dev === right.identity.dev && left.identity.ino === right.identity.ino;
+}
+function assertReceiptDirectoryGuardSync(root, guard, backend) {
+    if (backend) {
+        const observed = inspectNativeDirectoryObservation(backend, guard.dir, guard.identity);
+        const admitted = admitPathInsideRoot({
+            rootPath: root.rootReal,
+            candidatePath: observed.realPath,
+            rootIdentity: root.rootIdentity,
+        });
+        if (!admitted || admitted.path !== guard.realPath) {
+            throw new FsSafeError("path-mismatch", "directory changed during operation");
+        }
+        return;
+    }
+    if (isNativeDirectoryObservationGuard(guard)) {
+        throw new FsSafeError("path-mismatch", "native directory observation cannot be revalidated");
+    }
+    assertDirectoryObservationGuardSync(guard);
+}
+/**
+ * Close an operation-local traversal receipt with fresh exact observations.
+ * Descendant canonical paths are admitted while the receipt is created. The
+ * final directory check repeats canonical admission; the Root-only case does
+ * both its identity and canonical check here.
+ */
+export function assertRootPathObservationReceiptCurrent(root, receipt, finalTarget) {
+    const { rootGuard, directoryGuard } = receipt;
+    if (rootGuard.dir !== root.rootReal || rootGuard.realPath !== root.rootReal ||
+        rootGuard.identity.dev !== root.rootIdentity.dev || rootGuard.identity.ino !== root.rootIdentity.ino) {
+        throw rootPathChangedError();
+    }
+    if (sameObservationDirectory(rootGuard, directoryGuard)) {
+        try {
+            if (receipt.kind === "stat" && receipt.target === rootGuard && finalTarget &&
+                !receipt.directoryObserver) {
+                if (finalTarget.isSymbolicLink() || !finalTarget.isDirectory() ||
+                    realpathSync.native(rootGuard.dir) !== rootGuard.realPath) {
+                    throw new FsSafeError("path-mismatch", "root path changed during operation");
+                }
+            }
+            else {
+                assertReceiptDirectoryGuardSync(root, directoryGuard, receipt.directoryObserver);
+            }
+        }
+        catch (error) {
+            throw rootPathChangedError(error instanceof Error ? error : undefined);
+        }
+        return;
+    }
+    try {
+        assertDirectoryObservationSync(rootGuard.dir, rootGuard.identity);
+    }
+    catch (error) {
+        throw rootPathChangedError(error instanceof Error ? error : undefined);
+    }
+    try {
+        assertReceiptDirectoryGuardSync(root, directoryGuard, receipt.directoryObserver);
+    }
+    catch (error) {
+        throw directoryChangedError(error);
+    }
+}
 function normalizeDirectoryError(error) {
     if (isNotFoundPathError(error)) {
         return new FsSafeError("not-found", "directory not found", {
@@ -32,46 +157,70 @@ function normalizeDirectoryError(error) {
     }
     return error;
 }
-export async function listDirectoryPath(root, directory, withFileTypes) {
+function normalizeInitialDirectoryError(error) {
+    if (error instanceof FsSafeError && error.code === "not-file") {
+        return new FsSafeError("not-found", "directory not found", { cause: error });
+    }
+    return normalizeDirectoryError(error);
+}
+export async function listDirectoryPath(root, directory, withFileTypes, receipt) {
+    let guard;
+    if (receipt) {
+        if (receipt.kind !== "directory" || receipt.targetPath !== directory ||
+            receipt.directoryGuard.dir !== directory ||
+            receipt.target !== receipt.directoryGuard ||
+            (!isNativeDirectoryObservationGuard(receipt.directoryGuard) &&
+                !receipt.directoryGuard.stat.isDirectory())) {
+            throw new FsSafeError("path-mismatch", "directory observation receipt does not match target");
+        }
+        guard = receipt.directoryGuard;
+    }
+    else {
+        try {
+            guard = await createRootDirectoryObservationGuard(root, directory);
+        }
+        catch (error) {
+            throw normalizeInitialDirectoryError(error);
+        }
+    }
+    return await listGuardedDirectoryPath(root, guard, withFileTypes, receipt);
+}
+async function listGuardedDirectoryPath(root, guard, withFileTypes, receipt) {
+    let entries;
     try {
-        const names = (await fs.readdir(directory)).sort();
-        const entries = withFileTypes
+        const beforeObservation = getFsSafeTestHooks()?.beforeRootListObservation;
+        if (beforeObservation)
+            await beforeObservation(guard.realPath, withFileTypes);
+        const names = (await fs.readdir(guard.realPath)).sort();
+        entries = withFileTypes
             ? names.map(name => ({
                 name,
-                ...pathStatFromStats(fsSync.lstatSync(path.join(directory, name))),
+                ...pathStatFromStats(fsSync.lstatSync(path.join(guard.realPath, name))),
             }))
             : names;
-        await assertRootIdentityCurrent(root);
-        return entries;
     }
     catch (error) {
+        // Preserve ordinary observation errors only while the admitted directory is
+        // still current. A post-admission replacement is an identity failure.
+        if (receipt)
+            assertRootPathObservationReceiptCurrent(root, receipt);
+        else
+            await assertRootDirectoryObservationGuard(root, guard);
         throw normalizeDirectoryError(error);
     }
+    if (receipt)
+        assertRootPathObservationReceiptCurrent(root, receipt);
+    else
+        await assertRootDirectoryObservationGuard(root, guard);
+    return entries;
 }
 export async function openRootDirectoryListing(root, directory, options) {
-    const guard = await createAsyncDirectoryGuard(directory, { bigint: true }).catch((error) => {
+    const guard = await createRootDirectoryObservationGuard(root, directory).catch((error) => {
         throw normalizeDirectoryError(error);
     });
-    if (!isPathInside(root.rootReal, guard.realPath)) {
-        throw new FsSafeError("outside-workspace", "directory is outside workspace root");
-    }
-    const guardPinsRoot = guard.dir === root.rootReal &&
-        guard.stat.dev === root.rootIdentity.dev && guard.stat.ino === root.rootIdentity.ino;
     const assertCurrent = async () => {
         options.signal?.throwIfAborted();
-        if (guardPinsRoot) {
-            // One exact receipt proves both identities without dropping the canonical-path check.
-            try {
-                await assertAsyncDirectoryGuard(guard);
-            }
-            catch (error) {
-                throw rootPathChangedError(error instanceof Error ? error : undefined);
-            }
-        }
-        else {
-            await assertRootIdentityCurrent(root);
-            await assertAsyncDirectoryGuard(guard);
-        }
+        await assertRootDirectoryObservationGuard(root, guard);
         options.signal?.throwIfAborted();
     };
     let handle;
@@ -95,7 +244,7 @@ export async function openRootDirectoryListing(root, directory, options) {
             handle = await fs.opendir(guard.realPath, { bufferSize: 1 });
         }
         else if (options.snapshot) {
-            snapshot = await listDirectoryPath(root, guard.realPath, true);
+            snapshot = await listGuardedDirectoryPath(root, guard, true);
         }
         else if (options.maxNames !== undefined) {
             names = [];

package/dist/root-directory.d.ts

@@ -0,0 +1,23 @@
+import { FsSafeError } from "./errors.js";
+export type DirectoryResult = {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+    diagnostic?: FsSafeError;
+};
+export declare function resolveNearestExistingPath(targetPath: string): string;
+export declare function assertNoSymlinkSegments(params: {
+    rootDir: string;
+    targetPath: string;
+    scopeLabel: string;
+}): Promise<void>;
+export declare function ensureDirectoryWithinRoot(params: {
+    rootDir: string;
+    requestedPath: string;
+    scopeLabel: string;
+    defaultDirName?: string;
+    mode?: number;
+}): Promise<DirectoryResult>;
+//# sourceMappingURL=root-directory.d.ts.map

package/dist/root-directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-directory.d.ts","sourceRoot":"","sources":["../src/root-directory.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAiB1C,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,WAAW,CAAA;CAAE,CAAC;AAM3D,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAiBrE;AAED,wBAAsB,uBAAuB,CAAC,MAAM,EAAE;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BhB;AAED,wBAAsB,yBAAyB,CAAC,MAAM,EAAE;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,eAAe,CAAC,CAiF3B"}

package/dist/root-directory.js

@@ -0,0 +1,141 @@
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { formatErrorDetail } from "./error-detail.js";
+import { FsSafeError } from "./errors.js";
+import { assertNoNulPathInput, hasNodeErrorCode, isNodeError, isNotFoundPathError, isPathInside, isPathRelativeEscape, } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { resolvePathWithinRoot } from "./root-paths-lexical.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+function invalidPath(scopeLabel) {
+    return { ok: false, error: `Invalid path: must stay within ${scopeLabel}` };
+}
+export function resolveNearestExistingPath(targetPath) {
+    assertNoWindowsPathAlias(targetPath);
+    let current = resolvePathPreservingWindowsRoot(targetPath);
+    assertNoWindowsPathAlias(current);
+    while (true) {
+        try {
+            fsSync.lstatSync(pathForWindowsFilesystem(current));
+            return current;
+        }
+        catch (err) {
+            if (!isNotFoundPathError(err))
+                throw err;
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            throw new Error(`failed to resolve existing path for ${targetPath}`);
+        }
+        current = parent;
+    }
+}
+export async function assertNoSymlinkSegments(params) {
+    const relative = path.relative(params.rootDir, params.targetPath);
+    if (isPathRelativeEscape(relative)) {
+        throw new FsSafeError("outside-workspace", `Invalid path: must stay within ${params.scopeLabel}`);
+    }
+    let current = params.rootDir;
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        try {
+            const stat = fsSync.lstatSync(current);
+            if (stat.isSymbolicLink()) {
+                throw new FsSafeError("symlink", `Invalid path: must not traverse symlinks within ${params.scopeLabel}`);
+            }
+            if (!stat.isDirectory()) {
+                throw new FsSafeError("not-file", `Invalid path: existing segment must be a directory within ${params.scopeLabel}`);
+            }
+        }
+        catch (err) {
+            if (isNotFoundPathError(err))
+                return;
+            throw err;
+        }
+    }
+}
+export async function ensureDirectoryWithinRoot(params) {
+    const scopeLabel = formatErrorDetail(params.scopeLabel.slice(0, 80));
+    try {
+        const rootDirInput = params.rootDir;
+        const requestedPathInput = params.requestedPath;
+        const useDefault = !requestedPathInput.trim();
+        const defaultDirName = useDefault ? params.defaultDirName : undefined;
+        const mode = params.mode;
+        assertNoNulPathInput(rootDirInput);
+        assertNoNulPathInput(requestedPathInput);
+        if (useDefault)
+            assertNoNulPathInput(defaultDirName ?? "");
+        assertNoWindowsPathAlias(rootDirInput);
+        assertNoWindowsPathAlias(requestedPathInput);
+        if (useDefault)
+            assertNoWindowsPathAlias(defaultDirName ?? "");
+        const lexical = resolvePathWithinRoot({
+            rootDir: rootDirInput,
+            requestedPath: requestedPathInput,
+            scopeLabel,
+            defaultFileName: defaultDirName,
+        });
+        if (!lexical.ok)
+            return lexical;
+        const rootDir = resolvePathPreservingWindowsRoot(rootDirInput);
+        const targetPath = lexical.path;
+        const rootStat = fsSync.lstatSync(pathForWindowsFilesystem(rootDir));
+        if (rootStat.isSymbolicLink() || !rootStat.isDirectory())
+            return invalidPath(scopeLabel);
+        await assertNoSymlinkSegments({ rootDir, targetPath, scopeLabel });
+        const rootReal = realpathSync.native(pathForWindowsFilesystem(rootDir));
+        assertNoWindowsPathAlias(rootReal);
+        const nearestExistingPath = resolveNearestExistingPath(targetPath);
+        const nearestExistingReal = realpathSync.native(pathForWindowsFilesystem(nearestExistingPath));
+        assertNoWindowsPathAlias(nearestExistingReal);
+        if (!isPathInside(rootReal, nearestExistingReal))
+            return invalidPath(scopeLabel);
+        const relative = path.relative(rootDir, targetPath);
+        let current = rootDir;
+        for (const segment of relative.split(path.sep).filter(Boolean)) {
+            current = path.join(current, segment);
+            while (true) {
+                try {
+                    const stat = fsSync.lstatSync(current);
+                    if (stat.isSymbolicLink() || !stat.isDirectory())
+                        return invalidPath(scopeLabel);
+                    break;
+                }
+                catch (err) {
+                    if (!isNotFoundPathError(err))
+                        throw err;
+                    try {
+                        await fs.mkdir(current, { mode });
+                    }
+                    catch (mkdirErr) {
+                        if (hasNodeErrorCode(mkdirErr, "EEXIST"))
+                            continue;
+                        throw mkdirErr;
+                    }
+                }
+            }
+            const currentReal = realpathSync.native(current);
+            assertNoWindowsPathAlias(currentReal);
+            if (!isPathInside(rootReal, currentReal))
+                return invalidPath(scopeLabel);
+        }
+        const targetReal = realpathSync.native(pathForWindowsFilesystem(targetPath));
+        assertNoWindowsPathAlias(targetReal);
+        if (!isPathInside(rootReal, targetReal))
+            return invalidPath(scopeLabel);
+        return { ok: true, path: targetPath };
+    }
+    catch (cause) {
+        if ((cause instanceof FsSafeError && cause.category === "policy") ||
+            hasNodeErrorCode(cause, "ENOTDIR")) {
+            return invalidPath(scopeLabel);
+        }
+        const code = isNodeError(cause) && typeof cause.code === "string"
+            ? formatErrorDetail(cause.code.slice(0, 40)) : "filesystem operation failed";
+        const syscall = isNodeError(cause) && typeof cause.syscall === "string"
+            ? ` during ${formatErrorDetail(cause.syscall.slice(0, 40))}` : "";
+        const diagnostic = new FsSafeError("helper-failed", `Could not prepare ${scopeLabel}: ${code}${syscall}`, { cause });
+        return { ok: false, error: diagnostic.message, diagnostic };
+    }
+}

package/dist/root-errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-errors.d.ts","sourceRoot":"","sources":["../src/root-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAKnE,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,WAAW,CAI5F;AAED,wBAAgB,qBAAqB,IAAI,WAAW,CAEnD;AAED,wBAAgB,oBAAoB,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,WAAW,CAE/D;AAED,wBAAgB,mCAAmC,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,CAIhF;AAED,wBAAgB,6BAA6B,IAAI,WAAW,CAE3D;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAU/D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAQ5F;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAQ7F;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAe5F;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAQzE"}
+{"version":3,"file":"root-errors.d.ts","sourceRoot":"","sources":["../src/root-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAWnE,wBAAgB,iBAAiB,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,WAAW,CAI5F;AAED,wBAAgB,qBAAqB,IAAI,WAAW,CAEnD;AAED,wBAAgB,oBAAoB,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,WAAW,CAE/D;AAED,wBAAgB,mCAAmC,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,WAAW,CAIhF;AAED,wBAAgB,6BAA6B,IAAI,WAAW,CAE3D;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAe/D;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAQ5F;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAQ7F;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAe5F;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,CAQzE"}

package/dist/root-errors.js

@@ -1,6 +1,12 @@
 import { FsSafeError } from "./errors.js";
 import { hasNodeErrorCode, isNodeError, isNotFoundPathError } from "./path.js";
 const REMOVE_NOT_EMPTY_CODES = new Set(["ENOTEMPTY", "EEXIST"]);
+const PINNED_WRITE_ERRNO_MESSAGES = new Map([
+    ["EACCES", "permission denied"],
+    ["EPERM", "permission denied"],
+    ["EROFS", "read-only filesystem"],
+    ["ENOSPC", "no space left on device"],
+]);
 export function fileNotFoundError(cause, details) {
     return cause === undefined
         ? new FsSafeError("not-found", "file not found", { details })
@@ -30,7 +36,12 @@ export function normalizePinnedWriteError(error) {
     if (isNotFoundPathError(error)) {
         return fileNotFoundError(error instanceof Error ? error : undefined);
     }
-    return new FsSafeError("invalid-path", "path is not a regular file under root", {
+    const code = isNodeError(error) && typeof error.code === "string" && /^E[A-Z0-9_]+$/.test(error.code)
+        ? error.code : undefined;
+    const message = code
+        ? `${PINNED_WRITE_ERRNO_MESSAGES.get(code) ?? "filesystem write failed"} (${code})`
+        : "path is not a regular file under root";
+    return new FsSafeError("invalid-path", message, {
         cause: error instanceof Error ? error : undefined,
     });
 }

package/dist/root-file-final-admission.d.ts

@@ -0,0 +1,21 @@
+import fs from "node:fs";
+import type { PinnedOpenSyncFinalAdmission } from "./pinned-open.js";
+export type RootFileAdmissionFs = Pick<typeof fs, "lstatSync" | "realpathSync">;
+type ExactIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>;
+export type CanonicalRootObservation = {
+    ok: true;
+    path: string;
+    identity: ExactIdentity;
+} | {
+    ok: false;
+    error: unknown;
+};
+export declare function observeCanonicalRoot(ioFs: RootFileAdmissionFs, rootPath: string): CanonicalRootObservation;
+export declare function createRootFileFinalAdmission(ioFs: RootFileAdmissionFs, root: Extract<CanonicalRootObservation, {
+    ok: true;
+}>, boundaryLabel: string): PinnedOpenSyncFinalAdmission;
+export {};
+//# sourceMappingURL=root-file-final-admission.d.ts.map

package/dist/root-file-final-admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-file-final-admission.d.ts","sourceRoot":"","sources":["../src/root-file-final-admission.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAC;AAMrE,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,WAAW,GAAG,cAAc,CAAC,CAAC;AAEhF,KAAK,aAAa,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE5D,MAAM,MAAM,wBAAwB,GAChC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAA;CAAE,GACnD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAoClC,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,mBAAmB,EACzB,QAAQ,EAAE,MAAM,GACf,wBAAwB,CAe1B;AAMD,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,mBAAmB,EACzB,IAAI,EAAE,OAAO,CAAC,wBAAwB,EAAE;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,CAAC,EACrD,aAAa,EAAE,MAAM,GACpB,4BAA4B,CAsC9B"}

package/dist/root-file-final-admission.js

@@ -0,0 +1,83 @@
+import fs from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { realpathSync } from "./realpath.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-path-alias.js";
+function rootIdentityMismatch(cause) {
+    return new FsSafeError("path-mismatch", "canonical root directory identity changed or could not be verified", cause === undefined ? {} : { cause });
+}
+function isExpectedPathError(error) {
+    const code = typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : "";
+    return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP";
+}
+function inspectCanonicalRoot(ioFs, rootPath, expected) {
+    try {
+        assertNoWindowsPathAlias(rootPath);
+        const operationPath = ioFs === fs ? pathForWindowsFilesystem(rootPath) : rootPath;
+        return inspectFileIdentitySync(() => {
+            const stat = ioFs.lstatSync(operationPath, { bigint: true });
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                throw rootIdentityMismatch();
+            return stat;
+        }, expected);
+    }
+    catch (error) {
+        if (expected && isExpectedPathError(error))
+            throw rootIdentityMismatch(error);
+        throw error;
+    }
+}
+export function observeCanonicalRoot(ioFs, rootPath) {
+    try {
+        const stat = inspectCanonicalRoot(ioFs, rootPath);
+        const identity = Object.freeze({ dev: stat.dev, ino: stat.ino });
+        let observedPath = rootPath;
+        if (process.platform === "win32" && ioFs === fs) {
+            // Native leaf resolution expands Windows short names. Bind that root
+            // spelling before traversal without replacing the observed identity.
+            observedPath = realpathSync.native(pathForWindowsFilesystem(rootPath));
+            if (observedPath !== rootPath)
+                inspectCanonicalRoot(ioFs, observedPath, identity);
+        }
+        return { ok: true, path: observedPath, identity };
+    }
+    catch (error) {
+        return { ok: false, error };
+    }
+}
+function resolveConsumedPath(ioFs, filePath) {
+    return ioFs === fs ? realpathSync.native(filePath) : ioFs.realpathSync(filePath);
+}
+export function createRootFileFinalAdmission(ioFs, root, boundaryLabel) {
+    const inspectRoot = (candidateRootPath, expected) => {
+        inspectCanonicalRoot(ioFs, candidateRootPath, expected);
+    };
+    return ({ path: consumedPath, descriptorIdentity }) => {
+        inspectCanonicalRoot(ioFs, root.path, root.identity);
+        const canonicalPath = resolveConsumedPath(ioFs, consumedPath);
+        assertNoWindowsPathAlias(canonicalPath, "filesystem", "resolved file path uses a Windows filesystem namespace alias");
+        const admitted = admitPathInsideRoot({
+            rootPath: root.path,
+            candidatePath: canonicalPath,
+            rootIdentity: root.identity,
+            inspectCandidateRoot: inspectRoot,
+        });
+        if (!admitted) {
+            throw new FsSafeError("outside-workspace", `resolved path escapes ${boundaryLabel}`);
+        }
+        try {
+            inspectFileIdentitySync(() => ioFs.lstatSync(admitted.path, { bigint: true }), descriptorIdentity);
+        }
+        catch (error) {
+            if (isExpectedPathError(error)) {
+                throw new FsSafeError("path-mismatch", "canonical file identity changed or could not be verified", { cause: error });
+            }
+            throw error;
+        }
+        inspectCanonicalRoot(ioFs, root.path, root.identity);
+        return admitted.path;
+    };
+}

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

@@ -1 +1 @@
-{"version":3,"file":"root-file.d.ts","sourceRoot":"","sources":["../src/root-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAOzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACrF,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EACjC,MAAM,kBAAkB,CAAC;AAE1B,KAAK,cAAc,GAAG,IAAI,CACxB,OAAO,EAAE,EACP,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,GACV,cAAc,GACd,cAAc,CACjB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG,2BAA2B,GAAG,YAAY,CAAC;AAEnF,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,yBAAyB,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtE,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAE7E,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,WAAW,CAAC,EAAE,yBAAyB,CAAC;IACxC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,GAAG;IACxD,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAQF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAW3D;AASD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,kBAAkB,CAuBnF;AAED,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE;IACR,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,CAAC;IAC3C,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,CAAC;IACjD,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,CAAC;IACzC,QAAQ,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,CAAC;CAC/C,GACA,CAAC,CAUH;AAoDD,wBAAsB,YAAY,CAChC,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,kBAAkB,CAAC,CAwB7B"}
+{"version":3,"file":"root-file.d.ts","sourceRoot":"","sources":["../src/root-file.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAOzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACrF,OAAO,EAEL,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EACjC,MAAM,kBAAkB,CAAC;AAS1B,KAAK,cAAc,GAAG,IAAI,CACxB,OAAO,EAAE,EACP,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,GACV,cAAc,GACd,cAAc,CACjB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG,2BAA2B,GAAG,YAAY,CAAC;AAEnF,MAAM,MAAM,kBAAkB,GAC1B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAC5E;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,yBAAyB,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtE,MAAM,MAAM,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,EAAE;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAE7E,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,WAAW,CAAC,EAAE,yBAAyB,CAAC;IACxC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG,sBAAsB,GAAG;IACxD,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B,CAAC;AAqBF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAW3D;AASD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,kBAAkB,CAwCnF;AAED,wBAAgB,wBAAwB,CAAC,CAAC,EACxC,OAAO,EAAE,mBAAmB,EAC5B,QAAQ,EAAE;IACR,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,CAAC;IAC3C,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,CAAC;IACjD,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,CAAC;IACzC,QAAQ,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,CAAC,CAAC;CAC/C,GACA,CAAC,CAUH;AA6DD,wBAAsB,YAAY,CAChC,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,kBAAkB,CAAC,CAmD7B"}