@openclaw/fs-safe 0.12.0 → 0.13.1

package/dist/pinned-mutation-shared-route.js

@@ -0,0 +1,70 @@
+import path from "node:path";
+import { WINDOWS_RESERVED_DEVICE_NAMES } from "./device-path.js";
+import { admitPathInsideRoot } from "./root-boundary.js";
+import { isSafePathSegment } from "./safe-path-segment.js";
+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 ordinaryWindowsSegments(relativePath) {
+    if (relativePath === "" || relativePath.includes("/") || relativePath.includes("\0"))
+        return false;
+    const segments = relativePath.split("\\");
+    return segments.every((segment) => isSafePathSegment(segment, { allowDotPrefix: true }) &&
+        !segment.endsWith(".") && !segment.endsWith(" ") &&
+        !windowsReservedDeviceSegment(segment));
+}
+function ordinaryPosixSegments(relativePath) {
+    return relativePath !== "" && !relativePath.includes("\\") &&
+        relativePath.split("/").every((segment) => isSafePathSegment(segment, { allowDotPrefix: true }));
+}
+function exactNonzeroRootIdentity(identity) {
+    return typeof identity?.dev === "bigint" && typeof identity.ino === "bigint" &&
+        identity.dev !== 0n && identity.ino !== 0n
+        ? Object.freeze({ dev: identity.dev, ino: identity.ino })
+        : undefined;
+}
+export function ordinarySharedAbsoluteInsideRoot(rootReal, candidatePath, rootIdentity) {
+    if (!path.isAbsolute(candidatePath) || candidatePath.includes("\0") ||
+        path.resolve(candidatePath) !== candidatePath ||
+        (process.platform === "win32"
+            ? candidatePath.startsWith("\\\\") || candidatePath.includes("/")
+            : candidatePath.includes("\\")))
+        return false;
+    const admitted = admitPathInsideRoot({
+        rootPath: rootReal,
+        candidatePath,
+        rootIdentity,
+    });
+    return admitted?.admission === "exact" && admitted.path === candidatePath &&
+        (admitted.relativePath === "" || (process.platform === "win32"
+            ? ordinaryWindowsSegments(admitted.relativePath)
+            : ordinaryPosixSegments(admitted.relativePath)));
+}
+export function simpleSharedRoute(params) {
+    if (process.versions.bun ||
+        params.policy.mutationSymlinks !== "reject" || !params.originalPath ||
+        params.originalPath.startsWith("~") || path.isAbsolute(params.originalPath) ||
+        !(process.platform === "win32"
+            ? ordinaryWindowsSegments(params.originalPath) &&
+                !params.rootReal.startsWith("\\\\") && !params.rootReal.includes("/")
+            : ordinaryPosixSegments(params.originalPath) && !params.rootReal.includes("\\")) ||
+        path.resolve(params.rootReal) !== params.rootReal)
+        return undefined;
+    const rootIdentity = exactNonzeroRootIdentity(params.rootIdentity);
+    if (!rootIdentity)
+        return undefined;
+    const route = path.resolve(params.rootReal, params.originalPath);
+    if (route !== params.selectedTarget ||
+        !ordinarySharedAbsoluteInsideRoot(params.rootReal, route, rootIdentity))
+        return undefined;
+    const policyEntries = [
+        ...(params.policy.denyMutations?.paths ?? []),
+        ...(params.policy.denyMutations?.prefixes ?? []),
+    ];
+    if (policyEntries.some((entry) => entry !== path.resolve(entry) ||
+        !ordinarySharedAbsoluteInsideRoot(params.rootReal, entry, rootIdentity)))
+        return undefined;
+    return { route, rootIdentity };
+}

package/dist/pinned-open.d.ts

@@ -11,6 +11,11 @@ export type PinnedOpenSyncResult = {
     error?: unknown;
 };
 export type PinnedOpenSyncAllowedType = "file" | "directory";
+export type PinnedOpenSyncFinalAdmission = (params: {
+    path: string;
+    preRealpathIdentity: fs.BigIntStats;
+    descriptorIdentity: fs.BigIntStats;
+}) => string;
 export type PinnedOpenSyncFs = Pick<typeof fs, "constants" | "lstatSync" | "realpathSync" | "openSync" | "fstatSync" | "closeSync">;
 export declare function openPinnedFileSync(params: {
     filePath: string;
@@ -20,5 +25,6 @@ export declare function openPinnedFileSync(params: {
     maxBytes?: number;
     allowedType?: PinnedOpenSyncAllowedType;
     ioFs?: PinnedOpenSyncFs;
+    finalAdmission?: PinnedOpenSyncFinalAdmission;
 }): PinnedOpenSyncResult;
 //# sourceMappingURL=pinned-open.d.ts.map

package/dist/pinned-open.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pinned-open.d.ts","sourceRoot":"","sources":["../src/pinned-open.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAOzB,MAAM,MAAM,2BAA2B,GAAG,MAAM,GAAG,YAAY,GAAG,IAAI,CAAC;AAEvE,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAA;CAAE,GACtD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,2BAA2B,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAExE,MAAM,MAAM,yBAAyB,GAAG,MAAM,GAAG,WAAW,CAAC;AAE7D,MAAM,MAAM,gBAAgB,GAAG,IAAI,CACjC,OAAO,EAAE,EACT,WAAW,GAAG,WAAW,GAAG,cAAc,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,CACpF,CAAC;AAQF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,yBAAyB,CAAC;IACxC,IAAI,CAAC,EAAE,gBAAgB,CAAC;CACzB,GAAG,oBAAoB,CAqDvB"}
+{"version":3,"file":"pinned-open.d.ts","sourceRoot":"","sources":["../src/pinned-open.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAQzB,MAAM,MAAM,2BAA2B,GAAG,MAAM,GAAG,YAAY,GAAG,IAAI,CAAC;AAEvE,MAAM,MAAM,oBAAoB,GAC5B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAA;CAAE,GACtD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,2BAA2B,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAExE,MAAM,MAAM,yBAAyB,GAAG,MAAM,GAAG,WAAW,CAAC;AAE7D,MAAM,MAAM,4BAA4B,GAAG,CAAC,MAAM,EAAE;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,mBAAmB,EAAE,EAAE,CAAC,WAAW,CAAC;IACpC,kBAAkB,EAAE,EAAE,CAAC,WAAW,CAAC;CACpC,KAAK,MAAM,CAAC;AAEb,MAAM,MAAM,gBAAgB,GAAG,IAAI,CACjC,OAAO,EAAE,EACT,WAAW,GAAG,WAAW,GAAG,cAAc,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,CACpF,CAAC;AAQF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,yBAAyB,CAAC;IACxC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACxB,cAAc,CAAC,EAAE,4BAA4B,CAAC;CAC/C,GAAG,oBAAoB,CAuEvB"}

package/dist/pinned-open.js

@@ -3,49 +3,67 @@ import { isUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { realpathSync } from "./realpath.js";
 function isExpectedPathError(error) {
     const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "";
     return code === "ENOENT" || code === "ENOTDIR" || code === "ELOOP";
 }
 export function openPinnedFileSync(params) {
+    const filePath = params.filePath;
+    const resolvedPath = params.resolvedPath;
     const ioFs = params.ioFs ?? fs;
     const allowedType = params.allowedType ?? "file";
+    const rejectPathSymlink = params.rejectPathSymlink === true;
+    const statPolicy = {
+        rejectHardlinks: params.rejectHardlinks,
+        maxBytes: params.maxBytes,
+    };
     const openReadFlags = resolveReadOpenFlags({ constants: ioFs.constants });
     let fd = null;
     try {
-        if (isUnsafeDeviceReadPath(params.filePath)) {
+        assertNoWindowsPathAlias(filePath, "filesystem", "file path uses a Windows filesystem namespace alias");
+        if (resolvedPath !== undefined) {
+            assertNoWindowsPathAlias(resolvedPath, "filesystem", "resolved path uses a Windows filesystem namespace alias");
+        }
+        if (isUnsafeDeviceReadPath(filePath)) {
             return { ok: false, reason: "validation" };
         }
-        if (params.rejectPathSymlink) {
-            const candidateStat = ioFs.lstatSync(params.filePath);
+        if (rejectPathSymlink) {
+            const candidateStat = ioFs.lstatSync(filePath);
             if (candidateStat.isSymbolicLink()) {
                 return { ok: false, reason: "validation" };
             }
         }
-        const realPath = params.resolvedPath ??
-            (ioFs === fs ? realpathSync(params.filePath) : ioFs.realpathSync(params.filePath));
+        const realPath = resolvedPath ??
+            (ioFs === fs ? realpathSync(filePath) : ioFs.realpathSync(filePath));
+        assertNoWindowsPathAlias(realPath, "filesystem", "resolved path uses a Windows filesystem namespace alias");
         if (isUnsafeDeviceReadPath(realPath)) {
             return { ok: false, reason: "validation" };
         }
         const preOpenStat = inspectFileIdentitySync(() => {
             const stat = ioFs.lstatSync(realPath, { bigint: true });
-            assertAllowedStat(stat, allowedType, params);
+            assertAllowedStat(stat, allowedType, statPolicy);
             return stat;
         });
         fd = ioFs.openSync(realPath, openReadFlags);
         const openedStat = ioFs.fstatSync(fd);
         const identity = inspectFileIdentitySync(() => {
             const stat = ioFs.fstatSync(fd, { bigint: true });
-            assertAllowedStat(stat, allowedType, params);
+            assertAllowedStat(stat, allowedType, statPolicy);
             return stat;
         }, preOpenStat);
-        inspectFileIdentitySync(() => {
+        const pathIdentity = inspectFileIdentitySync(() => {
             const stat = ioFs.lstatSync(realPath, { bigint: true });
-            assertAllowedStat(stat, allowedType, params);
+            assertAllowedStat(stat, allowedType, statPolicy);
             return stat;
         }, identity);
-        const opened = { ok: true, path: realPath, fd, stat: openedStat };
+        const admittedPath = params.finalAdmission?.({
+            path: realPath,
+            preRealpathIdentity: pathIdentity,
+            descriptorIdentity: identity,
+        }) ?? realPath;
+        const opened = { ok: true, path: admittedPath, fd, stat: openedStat };
         fd = null;
         return opened;
     }

package/dist/pinned-write-types.d.ts

@@ -0,0 +1,75 @@
+import type { CopyFileInput } from "./copy-file-input.js";
+import type { AnyAsyncDirectoryGuard } from "./directory-guard.js";
+import type { FileIdentityStat } from "./file-identity.js";
+import type { MutationDirectoryObservation } from "./pinned-mutation-observation.js";
+export type PinnedWriteInput = {
+    kind: "buffer";
+    data: string | Buffer;
+    encoding?: BufferEncoding;
+} | {
+    kind: "stream";
+    stream: AsyncIterable<Uint8Array | string>;
+    stageBeforePublish?: boolean;
+} | CopyFileInput;
+export type RenameIdentityPolicy = "strict" | "verify-content-with-lock";
+export type PublishedWriteIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>;
+export type PinnedMutationAdmissionReceipt = Readonly<object>;
+export type PinnedMutationAuthorizationToken = Readonly<object>;
+export type PinnedCreatedDirectoryReceipt = Readonly<{
+    admission: PinnedMutationAdmissionReceipt;
+    parent: MutationDirectoryObservation;
+    child: MutationDirectoryObservation;
+}>;
+export type PinnedMutationParentWalkSession = Readonly<{
+    retainedTargetPath: string;
+    tryAuthorizeAtParent(request: Readonly<{
+        targetPath: string;
+        mutationPath: string;
+        phase: "parent" | "parent-create";
+    }>, parent: MutationDirectoryObservation): PinnedMutationAuthorizationToken | undefined;
+    authorize(request: Readonly<{
+        targetPath: string;
+        mutationPath: string;
+        phase: "parent" | "parent-create";
+    }>): Promise<PinnedMutationAdmissionReceipt | undefined>;
+    advanceCreatedDirectory(receipt: PinnedCreatedDirectoryReceipt): PinnedMutationAuthorizationToken | undefined;
+    dispose(): void;
+}>;
+export type PinnedWriteMutationAdmission = Readonly<{
+    rejectParentSymlinks: boolean;
+    beginParentWalk?(): string | undefined;
+    beginSharedParentWalk?(): PinnedMutationParentWalkSession | undefined;
+    tryAuthorizeAtParent?(request: Readonly<{
+        targetPath: string;
+        mutationPath: string;
+        phase: "parent" | "parent-create";
+    }>, parent: MutationDirectoryObservation): PinnedMutationAuthorizationToken | undefined;
+    authorize(request: Readonly<{
+        targetPath: string;
+        mutationPath: string;
+        phase: "parent" | "parent-create";
+    }>): Promise<PinnedMutationAdmissionReceipt | undefined>;
+    advanceCreatedDirectory?(receipt: PinnedCreatedDirectoryReceipt): PinnedMutationAuthorizationToken | undefined;
+}>;
+export type PinnedWriteParams = {
+    rootPath: string;
+    relativeParentPath: string;
+    basename: string;
+    mkdir: boolean;
+    mode: number;
+    sync?: boolean;
+    overwrite?: boolean;
+    assertBeforeMutation?: () => void;
+    rejectFinalSymlink?: boolean;
+    maxBytes?: number;
+    input: PinnedWriteInput;
+    rootIdentity?: FileIdentityStat;
+    mutationAdmission?: PinnedWriteMutationAdmission;
+    onRenameIdentityMismatch?: "verify-content";
+    onPublished?: (identity: PublishedWriteIdentity) => void;
+    verifyPublished?: (fd: number, identity: PublishedWriteIdentity, parentGuard: AnyAsyncDirectoryGuard) => Promise<void>;
+};
+//# sourceMappingURL=pinned-write-types.d.ts.map

package/dist/pinned-write-types.d.ts.map

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

package/dist/pinned-write-types.js

@@ -0,0 +1 @@
+export {};

package/dist/pinned-write.d.ts

@@ -1,40 +1,14 @@
-import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
 import type { FileIdentityStat } from "./file-identity.js";
-import { type CopyFileInput } from "./copy-file-input.js";
-export type PinnedWriteInput = {
-    kind: "buffer";
-    data: string | Buffer;
-    encoding?: BufferEncoding;
-} | {
-    kind: "stream";
-    stream: AsyncIterable<Uint8Array | string>;
-    stageBeforePublish?: boolean;
-} | CopyFileInput;
-export type RenameIdentityPolicy = "strict" | "verify-content-with-lock";
-export type PublishedWriteIdentity = Readonly<{
-    dev: bigint;
-    ino: bigint;
-}>;
-export type PinnedWriteParams = {
-    rootPath: string;
-    relativeParentPath: string;
-    basename: string;
-    mkdir: boolean;
-    mode: number;
-    sync?: boolean;
-    overwrite?: boolean;
-    assertBeforeMutation?: () => void;
-    rejectFinalSymlink?: boolean;
-    maxBytes?: number;
-    input: PinnedWriteInput;
-    rootIdentity?: FileIdentityStat;
-    onRenameIdentityMismatch?: "verify-content";
-    onPublished?: (identity: PublishedWriteIdentity) => void;
-    verifyPublished?: (fd: number, identity: PublishedWriteIdentity, parentGuard: AnyAsyncDirectoryGuard) => Promise<void>;
-};
+import type { PinnedWriteParams, RenameIdentityPolicy } from "./pinned-write-types.js";
+export type { PinnedWriteInput, RenameIdentityPolicy, PublishedWriteIdentity, PinnedMutationAdmissionReceipt, PinnedMutationAuthorizationToken, PinnedCreatedDirectoryReceipt, PinnedMutationParentWalkSession, PinnedWriteMutationAdmission, PinnedWriteParams, } from "./pinned-write-types.js";
 export declare function runPinnedWriteHelper(params: PinnedWriteParams): Promise<FileIdentityStat>;
 export declare function runPinnedWriteWithRenamePolicy(params: PinnedWriteParams & {
     targetPath: string;
     renameIdentity?: RenameIdentityPolicy;
 }): Promise<FileIdentityStat>;
+export declare function withPinnedWriteRenameIdentityLock<T>(params: {
+    rootPath: string;
+    targetPath: string;
+    relativeTargetPath: string;
+}, run: () => Promise<T>): Promise<T>;
 //# sourceMappingURL=pinned-write.d.ts.map

package/dist/pinned-write.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pinned-write.d.ts","sourceRoot":"","sources":["../src/pinned-write.ts"],"names":[],"mappings":"AAOA,OAAO,EAA4F,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAG7J,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAa3D,OAAO,EAAE,KAAK,aAAa,EAAqB,MAAM,sBAAsB,CAAC;AAG7E,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,cAAc,CAAA;CAAE,GACpE;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,aAAa,CAAC,UAAU,GAAG,MAAM,CAAC,CAAC;IAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5F,aAAa,CAAC;AA4ClB,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,0BAA0B,CAAC;AAEzE,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE5E,MAAM,MAAM,iBAAiB,GAAG;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,IAAI,CAAC;IAClC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,gBAAgB,CAAC;IACxB,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC,wBAAwB,CAAC,EAAE,gBAAgB,CAAC;IAC5C,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,sBAAsB,KAAK,IAAI,CAAC;IAEzD,eAAe,CAAC,EAAE,CAChB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,sBAAsB,EAChC,WAAW,EAAE,sBAAsB,KAChC,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB,CAAC;AAEF,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAgB/F;AAED,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,iBAAiB,GAAG;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC,GACA,OAAO,CAAC,gBAAgB,CAAC,CA2B3B"}
+{"version":3,"file":"pinned-write.d.ts","sourceRoot":"","sources":["../src/pinned-write.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAiB3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACvF,YAAY,EACV,gBAAgB,EAAE,oBAAoB,EAAE,sBAAsB,EAC9D,8BAA8B,EAAE,gCAAgC,EAChE,6BAA6B,EAAE,+BAA+B,EAC9D,4BAA4B,EAAE,iBAAiB,GAChD,MAAM,yBAAyB,CAAC;AAgFjC,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAsD/F;AAED,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,iBAAiB,GAAG;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,oBAAoB,CAAC;CACvC,GACA,OAAO,CAAC,gBAAgB,CAAC,CAkB3B;AAED,wBAAsB,iCAAiC,CAAC,CAAC,EACvD,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAA;CAAE,EAC5E,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,CAiBZ"}

package/dist/pinned-write.js

@@ -4,7 +4,7 @@ import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { normalizeMaxBytes } from "./byte-budget.js";
-import { createAsyncDirectoryGuard, createNearestExistingDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.js";
+import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, createNearestExistingDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { syncDirectoryBestEffort } from "./directory-durability.js";
 import { sameFileIdentity, sha256Hex } from "./file-identity.js";
@@ -21,6 +21,7 @@ import { writeAllToFile } from "./write-file-handle.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
 import { writeCopyFileToFd } from "./copy-file-input.js";
 import { publishCopyStage } from "./publish-copy-stage.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 function byteLength(input, encoding) {
     return typeof input === "string"
         ? Buffer.byteLength(input, encoding ?? "utf8")
@@ -31,6 +32,7 @@ function assertSafeBasename(basename) {
         basename === "." ||
         basename === ".." ||
         basename.includes("/") ||
+        (process.platform === "win32" && basename.includes("\\")) ||
         basename.includes("\0")) {
         throw new FsSafeError("invalid-path", "invalid target path");
     }
@@ -40,6 +42,10 @@ function assertWithinMaxBytes(bytes, maxBytes) {
         throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${bytes})`);
     }
 }
+function fastParentGuardDeopt(error) {
+    return error instanceof FsSafeError &&
+        (error.code === "path-mismatch" || error.code === "not-file");
+}
 async function writeStreamToHandle(stream, handle, maxBytes, assertBeforeMutation) {
     let bytes = 0;
     for await (const chunk of stream) {
@@ -49,12 +55,54 @@ async function writeStreamToHandle(stream, handle, maxBytes, assertBeforeMutatio
         await writeAllToFile(handle, buffer, { assertBeforeMutation });
     }
 }
+const PINNED_WRITE_SNAPSHOT_KEYS = [
+    "rootPath", "relativeParentPath", "basename", "maxBytes", "rootIdentity",
+];
+const RENAME_POLICY_SNAPSHOT_KEYS = ["targetPath", "renameIdentity"];
+function copyOwnEnumerableExcept(source, excluded) {
+    const owned = {};
+    for (const key of Reflect.ownKeys(source)) {
+        // Node 22's object-rest fast path can read excluded accessors eagerly.
+        // Exclude before even inspecting the descriptor so named authority and
+        // pathname fields remain single-read snapshots on every supported Node.
+        if (excluded.includes(key))
+            continue;
+        if (!Object.getOwnPropertyDescriptor(source, key)?.enumerable)
+            continue;
+        Object.defineProperty(owned, key, {
+            value: Reflect.get(source, key),
+            enumerable: true,
+            writable: true,
+            configurable: true,
+        });
+    }
+    return owned;
+}
 export async function runPinnedWriteHelper(params) {
-    const normalizedParams = { ...params, maxBytes: normalizeMaxBytes(params.maxBytes) };
-    assertSafeBasename(params.basename);
+    const { rootPath, relativeParentPath, basename, maxBytes, rootIdentity } = params;
+    const ownedParams = copyOwnEnumerableExcept(params, PINNED_WRITE_SNAPSHOT_KEYS);
+    const normalizedParams = {
+        ...ownedParams,
+        rootPath,
+        relativeParentPath,
+        basename,
+        maxBytes: normalizeMaxBytes(maxBytes),
+        rootIdentity,
+    };
+    assertSafeBasename(normalizedParams.basename);
     validatePinnedOperationPayload({
-        relativeParentPath: params.relativeParentPath,
+        relativeParentPath: normalizedParams.relativeParentPath,
     });
+    assertNoWindowsPathAlias(normalizedParams.rootPath, "filesystem", "pinned write root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(normalizedParams.relativeParentPath, "relative", "pinned write parent uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(normalizedParams.basename, "relative", "pinned write basename uses a Windows filesystem namespace alias");
+    if (rootIdentity !== undefined) {
+        normalizedParams.rootIdentity = { dev: rootIdentity.dev, ino: rootIdentity.ino };
+    }
+    if (normalizedParams.mutationAdmission) {
+        const targetPath = path.join(normalizedParams.rootPath, ...normalizedParams.relativeParentPath.split("/").filter(Boolean), normalizedParams.basename);
+        await getFsSafeTestHooks()?.beforePinnedWriteParentAdmission?.(targetPath);
+    }
     // The explicit compatibility policy uses the guarded Node fallback, where
     // content verification can replace the strict post-rename inode check.
     if (normalizedParams.onRenameIdentityMismatch === "verify-content") {
@@ -67,51 +115,137 @@ export async function runPinnedWriteHelper(params) {
     return await runPinnedWriteFallback(normalizedParams);
 }
 export async function runPinnedWriteWithRenamePolicy(params) {
-    const { targetPath, renameIdentity, ...writeParams } = params;
+    const { targetPath, renameIdentity } = params;
+    const writeParams = copyOwnEnumerableExcept(params, RENAME_POLICY_SNAPSHOT_KEYS);
     if (renameIdentity !== "verify-content-with-lock") {
         return await runPinnedWriteHelper(writeParams);
     }
     const relativeTargetPath = writeParams.relativeParentPath
         ? `${writeParams.relativeParentPath}/${writeParams.basename}`
         : writeParams.basename;
-    const lockPath = path.join(writeParams.rootPath, `.fs-safe-write-${sha256Hex(relativeTargetPath)}.lock`);
-    return await withSidecarLock(writeParams.rootPath, {
-        managerKey: `fs-safe.write:${targetPath}`,
+    return await withPinnedWriteRenameIdentityLock({
+        rootPath: writeParams.rootPath, targetPath, relativeTargetPath,
+    }, async () => await runPinnedWriteHelper({
+        ...writeParams,
+        onRenameIdentityMismatch: "verify-content",
+    }));
+}
+export async function withPinnedWriteRenameIdentityLock(params, run) {
+    const lockPath = path.join(params.rootPath, `.fs-safe-write-${sha256Hex(params.relativeTargetPath)}.lock`);
+    return await withSidecarLock(params.rootPath, {
+        managerKey: `fs-safe.write:${params.targetPath}`,
         lockPath,
         staleMs: 30_000,
         timeoutMs: 5_000,
         payload: () => ({ pid: process.pid, createdAt: new Date().toISOString() }),
         retry: { retries: 5, minTimeout: 100, maxTimeout: 2_000, factor: 2 },
-    }, async () => await runPinnedWriteHelper({
-        ...writeParams,
-        onRenameIdentityMismatch: "verify-content",
-    }));
+    }, run);
 }
 async function runPinnedWriteFallback(params) {
     const exactRoot = typeof params.rootIdentity?.dev === "bigint" && typeof params.rootIdentity.ino === "bigint"
         ? { dev: params.rootIdentity.dev, ino: params.rootIdentity.ino } : undefined;
+    const mutationAdmission = params.mutationAdmission;
     if (exactRoot)
         await inspectDirectoryIdentity(params.rootPath, exactRoot);
     let parentPath = params.relativeParentPath
         ? path.join(params.rootPath, ...params.relativeParentPath.split("/"))
         : params.rootPath;
-    if (params.mkdir) {
+    let parentGuard;
+    let parentAdmitted = false;
+    const initialTargetPath = path.join(parentPath, params.basename);
+    const retainedTargetPath = mutationAdmission?.beginParentWalk?.();
+    const ordinaryRetainedTarget = retainedTargetPath !== undefined &&
+        path.relative(path.resolve(retainedTargetPath), path.resolve(initialTargetPath)) === "";
+    let fastGuardClassifierFailure;
+    if (ordinaryRetainedTarget) {
+        try {
+            parentGuard = await createAsyncDirectoryGuard(parentPath, { bigint: true });
+        }
+        catch (error) {
+            // Only a genuinely missing complete parent may enter the component
+            // creator. ENOTDIR, permission, identity, and canonicalization failures
+            // retain their original fail-closed result.
+            if (error?.code !== "ENOENT") {
+                if (!fastParentGuardDeopt(error))
+                    throw error;
+                fastGuardClassifierFailure = error;
+            }
+        }
+        if (parentGuard) {
+            await mutationAdmission.authorize(Object.freeze({
+                targetPath: initialTargetPath,
+                mutationPath: initialTargetPath,
+                phase: "parent",
+            }));
+            await assertAsyncDirectoryGuard(parentGuard);
+            parentAdmitted = true;
+        }
+    }
+    if (fastGuardClassifierFailure) {
+        // The optimized exact-guard classifier runs before policy admission. Let
+        // the established resolver restore deny/symlink precedence before using
+        // the guarded walker or reporting the classifier failure. Because this
+        // was not an ENOENT probe, it may never authorize a newly missing parent.
+        await mutationAdmission.authorize(Object.freeze({
+            targetPath: initialTargetPath,
+            mutationPath: initialTargetPath,
+            phase: "parent",
+        }));
+    }
+    if (params.mkdir && !parentGuard) {
         // mkdirPathComponentsWithGuards may resolve the final component through
         // an in-root symlink (e.g. a skill-bank layout). Use its returned real
         // path for the subsequent guard and target path so we don't re-check the
         // original, possibly-symlinked, lexical path and reject it outright.
-        parentPath = await mkdirPathComponentsWithGuards({
+        const mkdirParams = {
             rootReal: params.rootPath,
             targetPath: parentPath,
             rootIdentity: params.rootIdentity,
             assertBeforeMutation: params.assertBeforeMutation,
-            beforeComponent: async (componentPath) => await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath),
-        });
+            beforeComponent: async (componentPath) => {
+                await getFsSafeTestHooks()?.beforeRootFallbackMutation?.("mkdir", componentPath);
+            },
+        };
+        parentPath = await mkdirPathComponentsWithGuards(mutationAdmission ? {
+            ...mkdirParams,
+            rejectSymlinks: mutationAdmission.rejectParentSymlinks,
+            revalidateParentAfterBeforeComponent: true,
+            synchronousAuthorizationIncludesFence: true,
+            retainedTargetPath,
+            afterCreateComponent: mutationAdmission.advanceCreatedDirectory,
+            beforeCreateComponent: (componentPath, prospectiveParentPath, retainedTarget, parent) => {
+                if (fastGuardClassifierFailure)
+                    throw fastGuardClassifierFailure;
+                const request = Object.freeze({
+                    targetPath: retainedTarget ?? path.join(prospectiveParentPath, params.basename),
+                    mutationPath: componentPath,
+                    phase: "parent-create",
+                });
+                return mutationAdmission.tryAuthorizeAtParent?.(request, parent) ??
+                    mutationAdmission.authorize(request);
+            },
+            beforeUseComponent: async (_componentPath, prospectiveParentPath, retainedTarget) => {
+                const targetPath = retainedTarget ?? path.join(prospectiveParentPath, params.basename);
+                await mutationAdmission.authorize(Object.freeze({
+                    targetPath,
+                    mutationPath: targetPath,
+                    phase: "parent",
+                }));
+            },
+        } : mkdirParams);
     }
-    const parentGuard = params.mkdir
+    parentGuard ??= params.mkdir
         ? await createAsyncDirectoryGuard(parentPath, { bigint: true })
         : await createNearestExistingDirectoryGuard(params.rootPath, parentPath, { bigint: true });
     const targetPath = path.join(parentPath, params.basename);
+    if (mutationAdmission && !parentAdmitted) {
+        await mutationAdmission.authorize(Object.freeze({
+            targetPath,
+            mutationPath: targetPath,
+            phase: "parent",
+        }));
+        await assertAsyncDirectoryGuard(parentGuard);
+    }
     if (params.overwrite === false && (params.input.kind === "buffer" ||
         (params.input.kind === "stream" && !params.input.stageBeforePublish))) {
         const assertBeforeMutation = () => {

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

@@ -1 +1 @@
-{"version":3,"file":"private-directory.d.ts","sourceRoot":"","sources":["../src/private-directory.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B,CAAC;AAEF,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,6BAA6B,GACtC,OAAO,CAAC,IAAI,CAAC,CAkBf"}
+{"version":3,"file":"private-directory.d.ts","sourceRoot":"","sources":["../src/private-directory.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,6BAA6B,GAAG;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B,CAAC;AAEF,wBAAsB,sBAAsB,CAC1C,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,6BAA6B,GACtC,OAAO,CAAC,IAAI,CAAC,CAyBf"}

package/dist/private-directory.js

@@ -1,10 +1,12 @@
 import { FsSafeError } from "./errors.js";
 import { getNativeBinding } from "./native.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export async function createPrivateDirectory(targetPath, options) {
     const platform = options?.platform ?? process.platform;
     if (platform !== "win32") {
         throw new FsSafeError("helper-unavailable", "private-directory creation is supported only on Windows");
     }
+    assertNoWindowsPathAlias(targetPath, "filesystem", "private directory path uses a Windows filesystem namespace alias", platform);
     const native = getNativeBinding();
     if (!native) {
         throw new FsSafeError("helper-unavailable", "private Windows directory creation requires the matching optional native platform package; " +

package/dist/private-producer-handoff.d.ts

@@ -0,0 +1,16 @@
+import { type BigIntStats } from "node:fs";
+import { type FileHandle } from "node:fs/promises";
+import { type TempPathRegistration } from "./temp-cleanup.js";
+export type PrivateProducerHandoff = {
+    handle: FileHandle;
+    identity: BigIntStats;
+    unregister: TempPathRegistration;
+};
+export declare function handoffPrivateProducerFile(params: {
+    sourcePath: string;
+    targetPath: string;
+    assertSourceParent: () => void;
+    assertTargetParent: () => void;
+    readWrite: boolean;
+}): Promise<PrivateProducerHandoff>;
+//# sourceMappingURL=private-producer-handoff.d.ts.map

package/dist/private-producer-handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"private-producer-handoff.d.ts","sourceRoot":"","sources":["../src/private-producer-handoff.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAW,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAKvD,OAAO,EAEL,KAAK,oBAAoB,EAC1B,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,sBAAsB,GAAG;IACnC,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,WAAW,CAAC;IACtB,UAAU,EAAE,oBAAoB,CAAC;CAClC,CAAC;AA2OF,wBAAsB,0BAA0B,CAAC,MAAM,EAAE;IACvD,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,kBAAkB,EAAE,MAAM,IAAI,CAAC;IAC/B,SAAS,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CA6HlC"}