@openclaw/fs-safe 0.12.0 → 0.13.0

package/dist/pinned-mutation-observation.js

@@ -0,0 +1,142 @@
+import fs, {} from "node:fs";
+import path from "node:path";
+import { isNotFoundPathError } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+const checkedDirectoryObservation = Symbol("checked mutation directory observation");
+function identity(stat) {
+    return Object.freeze({ dev: stat.dev, ino: stat.ino, mode: stat.mode, nlink: stat.nlink });
+}
+function sameIdentity(left, right, directory = false) {
+    return left.dev === right.dev && left.ino === right.ino && left.mode === right.mode &&
+        // mkdir changes a parent's link count. File link counts remain live evidence.
+        (directory || left.nlink === right.nlink);
+}
+function directoryMode(mode) {
+    return (mode & 61440n) === 16384n;
+}
+function absent(pathname) {
+    try {
+        fs.lstatSync(pathname);
+        return false;
+    }
+    catch (error) {
+        // ENOTDIR is incomplete evidence, not a missing child of a directory.
+        return isNotFoundPathError(error) && error.code === "ENOENT";
+    }
+}
+export function missingMutationSegments(observation) {
+    return observation.missingSegments.length - observation.missingOffset;
+}
+export function nextMissingMutationPath(observation) {
+    const segment = observation.missingSegments[observation.missingOffset];
+    return segment === undefined ? undefined : path.join(observation.ancestor, segment);
+}
+// Callers may construct this only from their just-completed exact pathname and
+// canonical fences. The private brand prevents unverified structural objects
+// from advancing an admission epoch.
+export function checkedMutationDirectory(pathname, canonicalPath, stat) {
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new TypeError("mutation directory evidence must describe a real directory");
+    }
+    return Object.freeze({
+        path: pathname,
+        canonicalPath,
+        identity: identity(stat),
+        [checkedDirectoryObservation]: true,
+    });
+}
+function checkedDirectory(observation) {
+    return observation[checkedDirectoryObservation] === true &&
+        path.isAbsolute(observation.path) && path.isAbsolute(observation.canonicalPath) &&
+        directoryMode(observation.identity.mode);
+}
+export function mutationDirectoryObservationCurrent(observation) {
+    if (!checkedDirectory(observation))
+        return false;
+    try {
+        const stat = inspectFileIdentitySync(() => fs.lstatSync(observation.path, { bigint: true }));
+        return stat.isDirectory() && !stat.isSymbolicLink() &&
+            sameIdentity(observation.identity, stat) &&
+            realpathSync.native(observation.path) === observation.canonicalPath;
+    }
+    catch {
+        return false;
+    }
+}
+export function mutationObservationUsesDirectory(observation, directory) {
+    return checkedDirectory(directory) &&
+        observation.ancestor === directory.path &&
+        observation.canonicalAncestor === directory.canonicalPath &&
+        sameIdentity(observation.entry, directory.identity) &&
+        sameIdentity(observation.identity, directory.identity);
+}
+// Optional evidence only: failures select full admission, never a new error order.
+export function observeMutationPath(pathname) {
+    try {
+        let ancestor = pathname;
+        const reversedMissing = [];
+        while (absent(ancestor)) {
+            const parent = path.dirname(ancestor);
+            if (parent === ancestor)
+                return undefined;
+            reversedMissing.push(path.basename(ancestor));
+            ancestor = parent;
+        }
+        reversedMissing.reverse();
+        const missingSegments = Object.freeze(reversedMissing);
+        const entry = inspectFileIdentitySync(() => fs.lstatSync(ancestor, { bigint: true }));
+        const canonicalAncestor = realpathSync.native(ancestor);
+        const stat = canonicalAncestor === ancestor ? entry :
+            inspectFileIdentitySync(() => fs.lstatSync(canonicalAncestor, { bigint: true }));
+        if (stat.isSymbolicLink() || (missingSegments.length > 0 && !stat.isDirectory()))
+            return undefined;
+        const observation = Object.freeze({
+            path: pathname, ancestor, canonicalAncestor,
+            canonicalPath: path.join(canonicalAncestor, ...missingSegments),
+            entry: identity(entry), identity: identity(stat), missingSegments, missingOffset: 0,
+        });
+        return mutationObservationCurrent(observation) ? observation : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function mutationObservationCurrent(observation) {
+    try {
+        const entry = inspectFileIdentitySync(() => fs.lstatSync(observation.ancestor, { bigint: true }));
+        if (!sameIdentity(observation.entry, entry, entry.isDirectory()) ||
+            realpathSync.native(observation.ancestor) !== observation.canonicalAncestor)
+            return false;
+        const stat = observation.canonicalAncestor === observation.ancestor ? entry :
+            inspectFileIdentitySync(() => fs.lstatSync(observation.canonicalAncestor, { bigint: true }));
+        return sameIdentity(observation.identity, stat, stat.isDirectory()) &&
+            (missingMutationSegments(observation) === 0 ||
+                (stat.isDirectory() && absent(nextMissingMutationPath(observation))));
+    }
+    catch {
+        return false;
+    }
+}
+// This is deliberately a pure tentative update. The immediately following
+// parent authorization validates the complete epoch once before reusing it.
+export function advanceMutationObservation(observation, parent, child) {
+    const nextMissingPath = nextMissingMutationPath(observation);
+    if (nextMissingPath === undefined || nextMissingPath !== child.path)
+        return observation;
+    if (!checkedDirectory(parent) || !checkedDirectory(child) ||
+        observation.ancestor !== parent.path || observation.canonicalAncestor !== parent.canonicalPath ||
+        !sameIdentity(observation.entry, parent.identity, true) ||
+        !sameIdentity(observation.identity, parent.identity, true) ||
+        parent.path !== parent.canonicalPath || child.path !== child.canonicalPath ||
+        path.dirname(child.path) !== parent.path)
+        return undefined;
+    return Object.freeze({
+        ...observation,
+        ancestor: child.path,
+        canonicalAncestor: child.canonicalPath,
+        entry: child.identity,
+        identity: child.identity,
+        missingOffset: observation.missingOffset + 1,
+    });
+}

package/dist/pinned-mutation-shared-route.d.ts

@@ -0,0 +1,24 @@
+import type { DenyMutationPolicy } from "./deny-mutations.js";
+import type { RootBoundaryIdentity } from "./root-boundary.js";
+import type { MutationSymlinkPolicy } from "./root-symlink-policy.js";
+export type ExactRootIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>;
+type SharedMutationPolicy = Readonly<{
+    denyMutations?: DenyMutationPolicy;
+    mutationSymlinks?: MutationSymlinkPolicy;
+}>;
+export declare function ordinarySharedAbsoluteInsideRoot(rootReal: string, candidatePath: string, rootIdentity: ExactRootIdentity): boolean;
+export declare function simpleSharedRoute(params: {
+    rootReal: string;
+    rootIdentity?: RootBoundaryIdentity;
+    originalPath?: string;
+    selectedTarget: string;
+    policy: SharedMutationPolicy;
+}): {
+    route: string;
+    rootIdentity: ExactRootIdentity;
+} | undefined;
+export {};
+//# sourceMappingURL=pinned-mutation-shared-route.d.ts.map

package/dist/pinned-mutation-shared-route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pinned-mutation-shared-route.d.ts","sourceRoot":"","sources":["../src/pinned-mutation-shared-route.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAG9D,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAE/D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEtE,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEvE,KAAK,oBAAoB,GAAG,QAAQ,CAAC;IACnC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;CAC1C,CAAC,CAAC;AA+BH,wBAAgB,gCAAgC,CAC9C,QAAQ,EAAE,MAAM,EAChB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,iBAAiB,GAC9B,OAAO,CAeT;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,oBAAoB,CAAC;CAC9B,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,iBAAiB,CAAA;CAAE,GAAG,SAAS,CAqBjE"}

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":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,kCAAkC,CAAC;AAErF,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;AAElB,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;AAI5E,MAAM,MAAM,8BAA8B,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;AAI9D,MAAM,MAAM,gCAAgC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC;AAIhE,MAAM,MAAM,6BAA6B,GAAG,QAAQ,CAAC;IACnD,SAAS,EAAE,8BAA8B,CAAC;IAC1C,MAAM,EAAE,4BAA4B,CAAC;IACrC,KAAK,EAAE,4BAA4B,CAAC;CACrC,CAAC,CAAC;AAEH,MAAM,MAAM,+BAA+B,GAAG,QAAQ,CAAC;IACrD,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oBAAoB,CAAC,OAAO,EAAE,QAAQ,CAAC;QACrC,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,QAAQ,GAAG,eAAe,CAAC;KACnC,CAAC,EAAE,MAAM,EAAE,4BAA4B,GAAG,gCAAgC,GAAG,SAAS,CAAC;IACxF,SAAS,CAAC,OAAO,EAAE,QAAQ,CAAC;QAC1B,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,QAAQ,GAAG,eAAe,CAAC;KACnC,CAAC,GAAG,OAAO,CAAC,8BAA8B,GAAG,SAAS,CAAC,CAAC;IACzD,uBAAuB,CACrB,OAAO,EAAE,6BAA6B,GACrC,gCAAgC,GAAG,SAAS,CAAC;IAChD,OAAO,IAAI,IAAI,CAAC;CACjB,CAAC,CAAC;AAEH,MAAM,MAAM,4BAA4B,GAAG,QAAQ,CAAC;IAClD,oBAAoB,EAAE,OAAO,CAAC;IAC9B,eAAe,CAAC,IAAI,MAAM,GAAG,SAAS,CAAC;IACvC,qBAAqB,CAAC,IAAI,+BAA+B,GAAG,SAAS,CAAC;IACtE,oBAAoB,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC;QACtC,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,QAAQ,GAAG,eAAe,CAAC;KACnC,CAAC,EAAE,MAAM,EAAE,4BAA4B,GAAG,gCAAgC,GAAG,SAAS,CAAC;IACxF,SAAS,CAAC,OAAO,EAAE,QAAQ,CAAC;QAC1B,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,KAAK,EAAE,QAAQ,GAAG,eAAe,CAAC;KACnC,CAAC,GAAG,OAAO,CAAC,8BAA8B,GAAG,SAAS,CAAC,CAAC;IACzD,uBAAuB,CAAC,CACtB,OAAO,EAAE,6BAA6B,GACrC,gCAAgC,GAAG,SAAS,CAAC;CACjD,CAAC,CAAC;AAEH,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,iBAAiB,CAAC,EAAE,4BAA4B,CAAC;IACjD,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"}

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"}