@openclaw/fs-safe 0.11.0 → 0.13.0

package/dist/root-write-admission.js

@@ -0,0 +1,322 @@
+import fsSync from "node:fs";
+import path from "node:path";
+import { assertMutationNotDenied } from "./deny-mutations.js";
+import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard, createAsyncDirectoryGuard, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { isNotFoundPathError } from "./path.js";
+import { assertNoPathAliasEscape } from "./path-policy.js";
+import { preparePinnedWriteMutationAdmission, snapshotPinnedMutationPolicy, } from "./pinned-mutation-admission.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { resolvePathInRoot } from "./root-context.js";
+import { hardlinkedPathNotAllowedError, outsideWorkspaceError } from "./root-errors.js";
+import { inheritWriteTargetMode } from "./root-write-mode.js";
+import { mutationSymlinkResolution, } from "./root-symlink-policy.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { realpathSync } from "./realpath.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+import { assertPreparedRootWriteParentCurrent, } from "./root-write-complete-parent.js";
+const retainedRootWriteSelections = new WeakMap();
+export function retainRootWriteSelection(owner, selection) {
+    retainedRootWriteSelections.set(owner, selection);
+}
+export function createRootWriteSelectionForFd(selection, fd) {
+    const stat = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }));
+    return Object.freeze({
+        ...selection,
+        identity: Object.freeze({ dev: stat.dev, ino: stat.ino }),
+    });
+}
+export function takeRootWriteSelection(owner) {
+    const selection = retainedRootWriteSelections.get(owner);
+    retainedRootWriteSelections.delete(owner);
+    return selection;
+}
+function writeSelectionChanged(cause) {
+    return new FsSafeError("path-mismatch", "write target changed during operation", {
+        cause: cause instanceof Error ? cause : undefined,
+    });
+}
+function inspectRegularSelectionPath(pathname, expected, follow) {
+    let observed;
+    try {
+        observed = inspectFileIdentitySync(() => follow
+            ? fsSync.statSync(pathname, { bigint: true })
+            : fsSync.lstatSync(pathname, { bigint: true }), expected);
+    }
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "path-mismatch")
+            throw error;
+        throw writeSelectionChanged(error);
+    }
+    if ((!follow && observed.isSymbolicLink()) || !observed.isFile()) {
+        throw writeSelectionChanged();
+    }
+    if (observed.nlink > 1n)
+        throw hardlinkedPathNotAllowedError();
+    return observed;
+}
+function sameNormalizedPathSpelling(left, right) {
+    // Windows can expose case-sensitive directories, so normalize separators
+    // and roots without using path.relative's case-folding comparison.
+    return path.resolve(left) === path.resolve(right);
+}
+function inspectSelectionBindingSync(root, selection, fd) {
+    inspectRegularSelectionPath(selection.selectedPath, selection.identity, false);
+    if (!sameNormalizedPathSpelling(selection.operationTargetPath, selection.selectedPath)) {
+        let operationRealPath;
+        try {
+            operationRealPath = realpathSync.native(selection.operationTargetPath);
+        }
+        catch (error) {
+            throw writeSelectionChanged(error);
+        }
+        const admitted = admitPathInsideRoot({
+            rootPath: root.rootReal,
+            candidatePath: operationRealPath,
+            rootIdentity: root.rootIdentity,
+        });
+        if (!admitted)
+            throw outsideWorkspaceError();
+        inspectRegularSelectionPath(admitted.path, selection.identity, true);
+    }
+    if (fd !== undefined) {
+        try {
+            inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }), selection.identity);
+        }
+        catch (error) {
+            if (error instanceof FsSafeError && error.code === "path-mismatch")
+                throw error;
+            throw writeSelectionChanged(error);
+        }
+    }
+}
+export function assertRootWritePathSelectionSync(root, selection) {
+    if (!sameNormalizedPathSpelling(selection.operationTargetPath, selection.selectedPath)) {
+        let operationRealPath;
+        try {
+            operationRealPath = realpathSync.native(selection.operationTargetPath);
+        }
+        catch (error) {
+            throw writeSelectionChanged(error);
+        }
+        const admitted = admitPathInsideRoot({
+            rootPath: root.rootReal,
+            candidatePath: operationRealPath,
+            rootIdentity: root.rootIdentity,
+        });
+        if (!admitted)
+            throw outsideWorkspaceError();
+        const selected = inspectRegularSelectionPath(selection.selectedPath, undefined, false);
+        inspectRegularSelectionPath(admitted.path, selected, true);
+    }
+    assertSyncDirectoryGuard(selection.parentGuard);
+}
+export function assertRootWriteSelectionSync(root, selection, verifyBinding, fd) {
+    if (verifyBinding)
+        inspectSelectionBindingSync(root, selection, fd);
+    assertSyncDirectoryGuard(selection.parentGuard);
+}
+async function authorizeRootWritePathSelection(selection, afterAwait) {
+    const selectedAdmissionPending = !sameNormalizedPathSpelling(selection.operationTargetPath, selection.selectedPath);
+    await selection.mutationAdmission.authorize(Object.freeze({
+        targetPath: selection.operationTargetPath,
+        mutationPath: selection.operationTargetPath,
+        phase: "parent",
+    }));
+    afterAwait?.(selectedAdmissionPending);
+    if (selectedAdmissionPending) {
+        await selection.selectedTargetAdmission.authorize(selection.selectedPath);
+        afterAwait?.(false);
+    }
+}
+export async function prepareRootWritePathSelection(params) {
+    const { preparedParent, ...selectionParams } = params;
+    if (preparedParent && (!sameNormalizedPathSpelling(preparedParent.operationTargetPath, params.operationTargetPath) ||
+        !sameNormalizedPathSpelling(preparedParent.parentGuard.dir, path.dirname(params.operationTargetPath))))
+        throw writeSelectionChanged();
+    const selection = Object.freeze({
+        ...selectionParams,
+        parentGuard: preparedParent?.parentGuard ??
+            await createAsyncDirectoryGuard(path.dirname(params.selectedPath), { bigint: true }),
+    });
+    await authorizeRootWritePathSelection(selection, preparedParent
+        ? (selectedAdmissionPending) => assertPreparedRootWriteParentCurrent(preparedParent, !selectedAdmissionPending)
+        : undefined);
+    if (preparedParent) {
+        if (!sameNormalizedPathSpelling(preparedParent.selectedTargetPath, params.selectedPath)) {
+            throw writeSelectionChanged();
+        }
+    }
+    else {
+        await assertAsyncDirectoryGuard(selection.parentGuard);
+    }
+    return selection;
+}
+export async function prepareGuardedRootWritePathSelection(guarded, selectedPath, operationTargetPath = selectedPath, preparedParent) {
+    if (!guarded?.mutationAdmission)
+        return undefined;
+    if (!guarded.selectedTargetAdmission)
+        throw writeSelectionChanged();
+    return await prepareRootWritePathSelection({
+        mutationAdmission: guarded.mutationAdmission,
+        selectedTargetAdmission: guarded.selectedTargetAdmission,
+        operationTargetPath,
+        selectedPath,
+        preparedParent,
+    });
+}
+export async function refreshRootWritePathSelection(selection) {
+    await authorizeRootWritePathSelection(selection);
+    await assertAsyncDirectoryGuard(selection.parentGuard);
+}
+/**
+ * Re-authorize a retained shared-JavaScript destination without recapturing
+ * either its pathname binding or its exact parent fence.
+ */
+export async function refreshRootWriteSelection(root, selection, verifyBinding, fd) {
+    await authorizeRootWritePathSelection(selection);
+    if (verifyBinding)
+        inspectSelectionBindingSync(root, selection, fd);
+    await assertAsyncDirectoryGuard(selection.parentGuard);
+}
+export async function refreshRetainedRootWriteAdmission(root, selection, verifyBinding, fd) {
+    await getFsSafeTestHooks()?.beforePinnedWriteParentAdmission?.(selection.operationTargetPath);
+    await refreshRootWriteSelection(root, selection, verifyBinding, fd);
+}
+export async function resolveGuardedWritePathInRoot(root, params) {
+    const resolvedPath = await resolvePathInRoot(root, params.relativePath, {
+        aliasErrorCode: "path-alias",
+        rejectAmbiguousParents: true,
+        allowFinalSymlink: params.allowFinalSymlink,
+        ...mutationSymlinkResolution(params.mutationSymlinks),
+    });
+    await assertMutationNotDenied(resolvedPath.resolved, params.denyMutations, params.protectDeniedAncestors ? { protectAncestors: true } : undefined);
+    if (await (params.shouldAssertNoPathAlias?.(resolvedPath) ?? true)) {
+        try {
+            await assertNoPathAliasEscape({
+                absolutePath: resolvedPath.resolved,
+                rootPath: resolvedPath.rootReal,
+                boundaryLabel: "root",
+            });
+        }
+        catch (error) {
+            throw new FsSafeError("path-alias", "path alias escape blocked", {
+                cause: error instanceof Error ? error : undefined,
+            });
+        }
+    }
+    return resolvedPath;
+}
+export async function resolveGuardedWriteTargetInRoot(root, params) {
+    const policy = params.denyMutations === undefined && params.mutationSymlinks === undefined
+        ? undefined
+        : snapshotPinnedMutationPolicy(params.denyMutations, params.mutationSymlinks);
+    const resolveCurrent = async () => await resolveGuardedWritePathInRoot(root, {
+        ...params,
+        denyMutations: policy?.denyMutations,
+        mutationSymlinks: policy?.mutationSymlinks,
+    });
+    const resolvedPath = await resolveCurrent();
+    if (!policy)
+        return { resolvedPath, targetPath: resolvedPath.resolved };
+    const relativeParent = path.relative(resolvedPath.rootReal, path.dirname(resolvedPath.resolved));
+    const prepared = await preparePinnedWriteMutationAdmission({
+        rootReal: resolvedPath.rootReal,
+        rootWithSep: resolvedPath.rootWithSep,
+        rootIdentity: root.rootIdentity,
+        resolvedTargetPath: resolvedPath.resolved,
+        originalPath: params.relativePath,
+        defaultRelativeParentPath: relativeParent
+            ? relativeParent.split(path.sep).join(path.posix.sep)
+            : "",
+        policy,
+        resolveCurrent,
+    });
+    const selectedTargetAdmission = Object.freeze({
+        async authorize(selectedTargetPath) {
+            const admitted = admitPathInsideRoot({
+                rootPath: root.rootReal,
+                candidatePath: selectedTargetPath,
+                rootIdentity: root.rootIdentity,
+            });
+            if (!admitted)
+                throw outsideWorkspaceError();
+            await resolveGuardedWritePathInRoot(root, {
+                relativePath: admitted.relativePath,
+                denyMutations: policy.denyMutations,
+                mutationSymlinks: policy.mutationSymlinks,
+            });
+        },
+    });
+    const targetPath = path.join(resolvedPath.rootReal, ...prepared.relativeParentPath.split("/").filter(Boolean), path.basename(resolvedPath.resolved));
+    return {
+        resolvedPath,
+        targetPath,
+        mutationAdmission: prepared.mutationAdmission,
+        selectedTargetAdmission,
+    };
+}
+export async function resolvePinnedWriteTargetInRoot(root, relativePath, requestedMode, denyMutations, overwrite = true, mutationSymlinks) {
+    // Snapshot mutable caller-owned policy before preflight so every admission
+    // in this operation authorizes the same rules.
+    const policy = denyMutations === undefined && mutationSymlinks === undefined
+        ? undefined
+        : snapshotPinnedMutationPolicy(denyMutations, mutationSymlinks);
+    const resolveCurrent = policy
+        ? async () => await resolveGuardedWritePathInRoot(root, {
+            relativePath,
+            denyMutations: policy.denyMutations,
+            mutationSymlinks: policy.mutationSymlinks,
+        })
+        : undefined;
+    const { rootReal, rootWithSep, resolved } = resolveCurrent
+        ? await resolveCurrent()
+        : await resolveGuardedWritePathInRoot(root, { relativePath });
+    const relativeResolved = path.relative(rootReal, resolved);
+    if (path.isAbsolute(relativeResolved))
+        throw outsideWorkspaceError();
+    const relativePosix = relativeResolved
+        ? relativeResolved.split(path.sep).join(path.posix.sep)
+        : "";
+    const basename = path.posix.basename(relativePosix);
+    if (!basename || basename === "." || basename === "/") {
+        throw new FsSafeError("invalid-path", "invalid target path");
+    }
+    if (!overwrite) {
+        try {
+            const existing = fsSync.statSync(resolved);
+            if (!existing.isFile())
+                throw new FsSafeError("not-file", "not a file");
+            if (existing.nlink > 1)
+                throw hardlinkedPathNotAllowedError();
+            throw new FsSafeError("already-exists", "file already exists");
+        }
+        catch (error) {
+            if (!isNotFoundPathError(error))
+                throw error;
+        }
+    }
+    const mode = overwrite
+        ? await inheritWriteTargetMode({
+            targetPath: resolved,
+            rootWithSep,
+            rootIdentity: root.rootIdentity,
+            requestedMode,
+        })
+        : requestedMode ?? 0o600;
+    let relativeParentPath = path.posix.dirname(relativePosix) === "." ? "" : path.posix.dirname(relativePosix);
+    let mutationAdmission;
+    if (policy) {
+        ({ relativeParentPath, mutationAdmission } = await preparePinnedWriteMutationAdmission({
+            rootReal,
+            rootWithSep,
+            rootIdentity: root.rootIdentity,
+            resolvedTargetPath: resolved,
+            originalPath: relativePath,
+            defaultRelativeParentPath: relativeParentPath,
+            policy,
+            resolveCurrent: resolveCurrent,
+        }));
+    }
+    return { rootReal, targetPath: resolved, relativeParentPath, basename, mode, mutationAdmission };
+}

package/dist/root-write-compatibility.d.ts

@@ -0,0 +1,13 @@
+import { type RootBoundaryIdentity } from "./root-boundary.js";
+export declare function assertRootFallbackWritePath(expected: string | undefined, actual: string): void;
+export declare function withRootFallbackCompatibilityLock<T>(params: {
+    rootPath: string;
+    targetPath: string;
+    rootIdentity?: RootBoundaryIdentity;
+    assertBeforeMutation?: () => void;
+}, run: (binding: {
+    targetPath: string;
+    relativePath: string;
+    assertBeforeMutation: () => void;
+}) => Promise<T>): Promise<T>;
+//# sourceMappingURL=root-write-compatibility.d.ts.map

package/dist/root-write-compatibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-write-compatibility.d.ts","sourceRoot":"","sources":["../src/root-write-compatibility.ts"],"names":[],"mappings":"AAIA,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AA6CpF,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAI9F;AAED,wBAAsB,iCAAiC,CAAC,CAAC,EACvD,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC;IAAC,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,EACxH,GAAG,EAAE,CAAC,OAAO,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,oBAAoB,EAAE,MAAM,IAAI,CAAA;CAAE,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3G,OAAO,CAAC,CAAC,CAAC,CAkBZ"}

package/dist/root-write-compatibility.js

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import { FsSafeError } from "./errors.js";
+import { isNotFoundPathError } from "./path.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { withPinnedWriteRenameIdentityLock } from "./pinned-write.js";
+import { realpathSync } from "./realpath.js";
+import { serializePathWrite } from "./write-queue.js";
+function unsupportedSpelling() {
+    return new FsSafeError("path-alias", "Windows compatibility writes require lower-case ASCII destination components");
+}
+// The caller first applies the Root's ordinary path and mutation policies. This
+// extra admission rule is deliberately narrower than general Windows filenames:
+// the existing lock protocol has no portable case/Unicode equivalence key for a
+// missing name. Do not guess one, or switch keys when a placeholder appears.
+function effectiveDestination(rootPath, targetPath, rootIdentity) {
+    let effective;
+    try {
+        effective = realpathSync.native(targetPath);
+    }
+    catch (error) {
+        if (!isNotFoundPathError(error))
+            throw error;
+        let cursor = targetPath;
+        const missing = [];
+        for (;;) {
+            try {
+                fs.lstatSync(cursor);
+                break;
+            }
+            catch (error) {
+                if (!isNotFoundPathError(error) || cursor === rootPath)
+                    throw error;
+                const parent = path.dirname(cursor);
+                if (parent === cursor)
+                    throw error;
+                missing.unshift(path.basename(cursor));
+                cursor = parent;
+            }
+        }
+        // An existing dangling link must fail resolution, not become a missing
+        // lexical component. Keep the fallback bounded by the retained Root.
+        effective = path.join(realpathSync.native(cursor), ...missing);
+    }
+    const admitted = admitPathInsideRoot({ rootPath, candidatePath: effective, rootIdentity });
+    if (!admitted)
+        throw unsupportedSpelling();
+    const relative = admitted.relativePath;
+    if (!relative || !relative.split(path.sep).every(component => /^[a-z0-9._-]+$/.test(component) && !component.endsWith(".")))
+        throw unsupportedSpelling();
+    return admitted.path;
+}
+export function assertRootFallbackWritePath(expected, actual) {
+    if (expected !== undefined && actual !== expected) {
+        throw new FsSafeError("path-mismatch", "compatibility write destination changed after lock selection");
+    }
+}
+export async function withRootFallbackCompatibilityLock(params, run) {
+    const targetPath = effectiveDestination(params.rootPath, params.targetPath, params.rootIdentity);
+    const relativePath = path.relative(params.rootPath, targetPath).split(path.sep).join("/");
+    const assertCurrent = () => assertRootFallbackWritePath(targetPath, effectiveDestination(params.rootPath, targetPath, params.rootIdentity));
+    // Sidecars are reentrant within one manager; aliases also need the same local
+    // queue before acquisition. The outer Root queue uses the caller's spelling.
+    return await serializePathWrite(targetPath, async () => await withPinnedWriteRenameIdentityLock({
+        rootPath: params.rootPath, targetPath, relativeTargetPath: relativePath,
+    }, async () => {
+        // The guarded open resolves again under the lock; each mutation rechecks
+        // below. Lock selection is never reused as post-lock filesystem authority.
+        return await run({
+            targetPath, relativePath,
+            assertBeforeMutation: () => { params.assertBeforeMutation?.(); assertCurrent(); },
+        });
+    }));
+}

package/dist/root-write-complete-parent.d.ts

@@ -0,0 +1,42 @@
+import type { BigIntStats } from "node:fs";
+import { type AsyncDirectoryGuard } from "./directory-guard.js";
+import type { RootContext } from "./root-context.js";
+import type { GuardedRootWriteTarget } from "./root-write-admission.js";
+type PreparedWriteTargetObservation = Readonly<{
+    exists: false;
+} | {
+    exists: true;
+    stat: BigIntStats;
+}>;
+/**
+ * Exact, operation-local evidence that an ordinary shared-JavaScript write
+ * already has a complete parent. Path selection consumes this instead of
+ * recapturing the same parent after a component walk.
+ */
+export type PreparedRootWriteParent = Readonly<{
+    operationTargetPath: string;
+    selectedTargetPath: string;
+    parentGuard: AsyncDirectoryGuard<BigIntStats>;
+    rootPath: string;
+    rootIdentity: Readonly<{
+        dev: bigint;
+        ino: bigint;
+    }>;
+    nativeMode: string;
+    target: PreparedWriteTargetObservation;
+}>;
+type SharedRootWriteTargetParams = Readonly<{
+    relativePath: string;
+    guardedTarget: GuardedRootWriteTarget;
+    mkdir?: boolean;
+    assertBeforeMutation?: () => void;
+}>;
+export type SharedRootWriteTarget = Readonly<{
+    targetPath: string;
+    mutationAdmission: GuardedRootWriteTarget["mutationAdmission"];
+    preparedParent?: PreparedRootWriteParent;
+}>;
+export declare function assertPreparedRootWriteParentCurrent(prepared: PreparedRootWriteParent, verifyTarget?: boolean): void;
+export declare function prepareSharedRootWriteTarget(root: RootContext, params: SharedRootWriteTargetParams): Promise<SharedRootWriteTarget>;
+export {};
+//# sourceMappingURL=root-write-complete-parent.d.ts.map

package/dist/root-write-complete-parent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"root-write-complete-parent.d.ts","sourceRoot":"","sources":["../src/root-write-complete-parent.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3C,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,sBAAsB,CAAC;AAO9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAKxE,KAAK,8BAA8B,GAAG,QAAQ,CAC1C;IAAE,MAAM,EAAE,KAAK,CAAA;CAAE,GACjB;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CACtC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,QAAQ,CAAC;IAC7C,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,WAAW,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,QAAQ,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,8BAA8B,CAAC;CACxC,CAAC,CAAC;AAEH,KAAK,2BAA2B,GAAG,QAAQ,CAAC;IAC1C,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,sBAAsB,CAAC;IACtC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;CACnC,CAAC,CAAC;AAEH,MAAM,MAAM,qBAAqB,GAAG,QAAQ,CAAC;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,sBAAsB,CAAC,mBAAmB,CAAC,CAAC;IAC/D,cAAc,CAAC,EAAE,uBAAuB,CAAC;CAC1C,CAAC,CAAC;AA2GH,wBAAgB,oCAAoC,CAClD,QAAQ,EAAE,uBAAuB,EACjC,YAAY,UAAQ,GACnB,IAAI,CAqBN;AAwCD,wBAAsB,4BAA4B,CAChD,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,2BAA2B,GAClC,OAAO,CAAC,qBAAqB,CAAC,CAqBhC"}

package/dist/root-write-complete-parent.js

@@ -0,0 +1,195 @@
+import fsSync from "node:fs";
+import path from "node:path";
+import { assertDirectoryIdentitySync, createAsyncDirectoryGuard, inspectDirectoryIdentitySync, } from "./directory-guard.js";
+import { WINDOWS_RESERVED_DEVICE_NAMES } from "./device-path.js";
+import { FsSafeError } from "./errors.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { hasNodeErrorCode } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { prepareRootWriteTarget } from "./root-directory-creation.js";
+import { isSafePathSegment } from "./safe-path-segment.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { getFsSafeTestHooks } from "./test-hooks.js";
+function writeSelectionChanged(cause) {
+    return new FsSafeError("path-mismatch", "write target changed during operation", {
+        cause: cause instanceof Error ? cause : undefined,
+    });
+}
+function sameNormalizedPathSpelling(left, right) {
+    // Windows can expose case-sensitive directories, so normalize separators
+    // and roots without using path.relative's case-folding comparison.
+    return path.resolve(left) === path.resolve(right);
+}
+function windowsReservedDeviceSegment(segment) {
+    const extension = segment.indexOf(".");
+    const stem = segment.slice(0, extension < 0 ? segment.length : extension).toUpperCase();
+    return WINDOWS_RESERVED_DEVICE_NAMES.has(stem);
+}
+function ordinarySharedWriteRoute(root, relativePath, operationTargetPath) {
+    if (process.versions.bun || relativePath === "" || relativePath.startsWith("~") ||
+        relativePath.includes("\0") || path.isAbsolute(relativePath))
+        return false;
+    const separator = process.platform === "win32" ? "\\" : "/";
+    const alternateSeparator = process.platform === "win32" ? "/" : "\\";
+    if (relativePath.includes(alternateSeparator))
+        return false;
+    const segments = relativePath.split(separator);
+    if (segments.some((segment) => segment === "" || segment === "." || segment === ".." ||
+        (process.platform === "win32" &&
+            (!isSafePathSegment(segment, { allowDotPrefix: true }) ||
+                segment.endsWith(".") || segment.endsWith(" ") ||
+                windowsReservedDeviceSegment(segment)))))
+        return false;
+    const routed = path.resolve(root.rootReal, relativePath);
+    const admitted = admitPathInsideRoot({
+        rootPath: root.rootReal,
+        candidatePath: routed,
+        rootIdentity: root.rootIdentity,
+    });
+    return admitted?.admission === "exact" &&
+        sameNormalizedPathSpelling(admitted.path, routed) &&
+        sameNormalizedPathSpelling(routed, operationTargetPath);
+}
+// Preparation is optional evidence. An exact identity mismatch is conclusive
+// and remains fail-closed; every other probe failure must let the established
+// ordered component admission classify the same filesystem state.
+function deoptPreparationFailure(error) {
+    if (error instanceof FsSafeError && error.code === "path-mismatch")
+        throw error;
+    return undefined;
+}
+function capturePreparedTargetObservation(targetPath) {
+    let stat;
+    try {
+        stat = inspectFileIdentitySync(() => fsSync.lstatSync(targetPath, { bigint: true }));
+    }
+    catch (error) {
+        if (hasNodeErrorCode(error, "ENOENT"))
+            return Object.freeze({ exists: false });
+        return deoptPreparationFailure(error);
+    }
+    // Final aliases retain the established full component walk and selected-path
+    // admission. The shortcut is intentionally limited to an ordinary spelling.
+    if (stat.isSymbolicLink())
+        return undefined;
+    let realPath;
+    try {
+        realPath = realpathSync.native(targetPath);
+    }
+    catch (error) {
+        return deoptPreparationFailure(error);
+    }
+    if (!sameNormalizedPathSpelling(realPath, targetPath))
+        return undefined;
+    return Object.freeze({ exists: true, stat });
+}
+function samePreparedTargetFacts(left, right) {
+    return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode &&
+        left.nlink === right.nlink;
+}
+function assertPreparedTargetCurrent(prepared) {
+    if (!prepared.target.exists) {
+        try {
+            fsSync.lstatSync(prepared.selectedTargetPath, { bigint: true });
+        }
+        catch (error) {
+            if (hasNodeErrorCode(error, "ENOENT"))
+                return;
+            throw writeSelectionChanged(error);
+        }
+        throw writeSelectionChanged();
+    }
+    try {
+        const current = inspectFileIdentitySync(() => fsSync.lstatSync(prepared.selectedTargetPath, { bigint: true }), prepared.target.stat);
+        if (current.isSymbolicLink() || !samePreparedTargetFacts(prepared.target.stat, current)) {
+            throw writeSelectionChanged();
+        }
+    }
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "path-mismatch")
+            throw error;
+        throw writeSelectionChanged(error);
+    }
+}
+export function assertPreparedRootWriteParentCurrent(prepared, verifyTarget = false) {
+    try {
+        if (getFsSafeNativeConfig().mode !== prepared.nativeMode)
+            throw writeSelectionChanged();
+        if (!sameNormalizedPathSpelling(prepared.parentGuard.dir, prepared.rootPath)) {
+            assertDirectoryIdentitySync(prepared.rootPath, prepared.rootIdentity);
+        }
+        else if (prepared.parentGuard.stat.dev !== prepared.rootIdentity.dev ||
+            prepared.parentGuard.stat.ino !== prepared.rootIdentity.ino) {
+            throw writeSelectionChanged();
+        }
+        const parent = inspectDirectoryIdentitySync(prepared.parentGuard.dir, prepared.parentGuard.stat);
+        if (parent.mode !== prepared.parentGuard.stat.mode ||
+            parent.nlink !== prepared.parentGuard.stat.nlink ||
+            !sameNormalizedPathSpelling(realpathSync.native(prepared.parentGuard.dir), prepared.parentGuard.realPath))
+            throw writeSelectionChanged();
+        if (verifyTarget)
+            assertPreparedTargetCurrent(prepared);
+    }
+    catch (error) {
+        if (error instanceof FsSafeError && error.code === "path-mismatch")
+            throw error;
+        throw writeSelectionChanged(error);
+    }
+}
+async function prepareCompleteRootWriteParent(root, guarded, relativePath) {
+    if (!guarded.mutationAdmission || !guarded.selectedTargetAdmission ||
+        typeof root.rootIdentity.dev !== "bigint" || typeof root.rootIdentity.ino !== "bigint" ||
+        !ordinarySharedWriteRoute(root, relativePath, guarded.targetPath) ||
+        !sameNormalizedPathSpelling(guarded.resolvedPath.resolved, guarded.targetPath))
+        return undefined;
+    const parentPath = path.dirname(guarded.targetPath);
+    const admittedParent = admitPathInsideRoot({
+        rootPath: root.rootReal,
+        candidatePath: parentPath,
+        rootIdentity: root.rootIdentity,
+    });
+    if (admittedParent?.admission !== "exact" ||
+        !sameNormalizedPathSpelling(admittedParent.path, parentPath))
+        return undefined;
+    let parentGuard;
+    try {
+        parentGuard = await createAsyncDirectoryGuard(parentPath, { bigint: true });
+    }
+    catch (error) {
+        return deoptPreparationFailure(error);
+    }
+    if (!sameNormalizedPathSpelling(parentGuard.dir, parentPath) ||
+        !sameNormalizedPathSpelling(parentGuard.realPath, parentPath))
+        return undefined;
+    const target = capturePreparedTargetObservation(guarded.targetPath);
+    if (!target)
+        return undefined;
+    return Object.freeze({
+        operationTargetPath: guarded.targetPath,
+        selectedTargetPath: guarded.targetPath,
+        parentGuard,
+        rootPath: root.rootReal,
+        rootIdentity: Object.freeze({ dev: root.rootIdentity.dev, ino: root.rootIdentity.ino }),
+        nativeMode: getFsSafeNativeConfig().mode,
+        target,
+    });
+}
+export async function prepareSharedRootWriteTarget(root, params) {
+    const { guardedTarget } = params;
+    const resolvedPath = guardedTarget.resolvedPath.resolved;
+    const mutationAdmission = guardedTarget.mutationAdmission;
+    const beforeParentAdmission = mutationAdmission
+        ? getFsSafeTestHooks()?.beforePinnedWriteParentAdmission
+        : undefined;
+    if (mutationAdmission)
+        await beforeParentAdmission?.(resolvedPath);
+    const preparedParent = params.mkdir !== false &&
+        params.assertBeforeMutation === undefined && beforeParentAdmission === undefined
+        ? await prepareCompleteRootWriteParent(root, guardedTarget, params.relativePath)
+        : undefined;
+    const targetPath = params.mkdir === false
+        ? guardedTarget.targetPath
+        : preparedParent?.selectedTargetPath ?? await prepareRootWriteTarget(root, resolvedPath, params.assertBeforeMutation, mutationAdmission);
+    return { targetPath, mutationAdmission, preparedParent };
+}

package/dist/root-write-mode.d.ts

@@ -1,6 +1,8 @@
+import { type RootBoundaryIdentity } from "./root-boundary.js";
 export declare function inheritWriteTargetMode(params: {
     targetPath: string;
     rootWithSep: string;
+    rootIdentity?: RootBoundaryIdentity;
     requestedMode?: number;
 }): Promise<number>;
 //# sourceMappingURL=root-write-mode.d.ts.map

package/dist/root-write-mode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"root-write-mode.d.ts","sourceRoot":"","sources":["../src/root-write-mode.ts"],"names":[],"mappings":"AAUA,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsClB"}
+{"version":3,"file":"root-write-mode.d.ts","sourceRoot":"","sources":["../src/root-write-mode.ts"],"names":[],"mappings":"AAQA,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAGpF,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,GAAG,OAAO,CAAC,MAAM,CAAC,CAkDlB"}