@openclaw/fs-safe 0.15.0 → 0.16.0

package/dist/creation-permissions.js

@@ -0,0 +1,125 @@
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { getFsSafeNativeConfig } from "./native-config.js";
+import { warnNativeFallback } from "./native-fallback-warning.js";
+import { inspectWindowsDirectoryCommand, inspectWindowsDirectoryCommandSync, protectPrivateWindowsFileCommand, protectPrivateWindowsFileCommandSync, verifyPrivateWindowsFileCommand, verifyPrivateWindowsFileCommandSync, } from "./windows-security-command.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+import { assertDarwinCreationDirectoryAcl, assertDarwinPrivateCreationAvailable, assertDarwinPrivateDirectoryMode } from "./creation-darwin.js";
+export function resolveCreationPermissions(options, directory) {
+    const privatePath = options.private;
+    const mode = options.mode;
+    if (privatePath !== undefined && typeof privatePath !== "boolean") {
+        throw new TypeError("private must be a boolean");
+    }
+    if (mode !== undefined && (!Number.isInteger(mode) || mode < 0 || mode > 0o7777)) {
+        throw new RangeError("mode must contain only permission bits");
+    }
+    if (privatePath && mode !== undefined && (mode & 0o7077) !== 0) {
+        throw new FsSafeError("insecure-permissions", "private creation requires owner-only permission bits");
+    }
+    if (privatePath)
+        assertDarwinPrivateCreationAvailable();
+    if (privatePath && directory)
+        assertDarwinPrivateDirectoryMode(mode ?? 0o700);
+    return { private: privatePath === true, mode: mode ?? (privatePath ? directory ? 0o700 : 0o600 : undefined) };
+}
+function assertPrivatePosixDirectory(stat) {
+    if (typeof process.getuid !== "function" || stat.uid !== BigInt(process.getuid())) {
+        throw new FsSafeError("not-owned", "private directory must belong to the current user");
+    }
+    if ((stat.mode & 3647n) !== 0n) {
+        throw new FsSafeError("insecure-permissions", "existing directory is not private");
+    }
+}
+function unavailable() {
+    throw new FsSafeError("helper-unavailable", "private Windows creation requires an up-to-date native helper");
+}
+export function assertPrivateFileCreationAvailable() {
+    const native = getNativeBinding();
+    if (process.platform !== "win32" || getFsSafeNativeConfig().mode !== "require")
+        return;
+    if (typeof native?.createPrivateDirectoryWithParentIdentity !== "function" ||
+        typeof native.inspectWindowsDirectory !== "function" ||
+        typeof native.protectPrivateWindowsFile !== "function" ||
+        typeof native.verifyPrivateWindowsFile !== "function")
+        unavailable();
+}
+function commandFallback() {
+    if (getFsSafeNativeConfig().mode === "require")
+        unavailable();
+    warnNativeFallback("windows-private-creation", "Private Windows creation uses a slower built-in system command.");
+}
+/** Full Windows identity, with security validation when requested; no repairs. */
+export function inspectCreationDirectorySync(targetPath, privatePath) {
+    assertNoWindowsPathAlias(targetPath, "filesystem");
+    const native = getNativeBinding();
+    if (typeof native?.inspectWindowsDirectory === "function") {
+        return native.inspectWindowsDirectory(targetPath, privatePath).identity;
+    }
+    commandFallback();
+    return inspectWindowsDirectoryCommandSync(targetPath, privatePath).identity;
+}
+export async function inspectCreationDirectory(targetPath, privatePath) {
+    assertNoWindowsPathAlias(targetPath, "filesystem");
+    const native = getNativeBinding();
+    if (typeof native?.inspectWindowsDirectory === "function") {
+        return native.inspectWindowsDirectory(targetPath, privatePath).identity;
+    }
+    commandFallback();
+    return (await inspectWindowsDirectoryCommand(targetPath, privatePath)).identity;
+}
+export function assertPrivateDirectorySync(targetPath) {
+    const stat = inspectDirectoryIdentitySync(targetPath);
+    if (process.platform === "win32")
+        inspectCreationDirectorySync(targetPath, true);
+    else {
+        assertPrivatePosixDirectory(stat);
+        assertDarwinCreationDirectoryAcl(targetPath, stat);
+    }
+    inspectDirectoryIdentitySync(targetPath, stat);
+}
+export async function assertPrivateDirectory(targetPath) {
+    const stat = inspectDirectoryIdentitySync(targetPath);
+    if (process.platform === "win32")
+        await inspectCreationDirectory(targetPath, true);
+    else {
+        assertPrivatePosixDirectory(stat);
+        assertDarwinCreationDirectoryAcl(targetPath, stat);
+    }
+    inspectDirectoryIdentitySync(targetPath, stat);
+}
+export function protectCreatedFileSync(fd, targetPath, parentIdentity) {
+    const native = getNativeBinding();
+    if (typeof native?.protectPrivateWindowsFile === "function") {
+        return native.protectPrivateWindowsFile(fd, targetPath, parentIdentity).identity;
+    }
+    commandFallback();
+    return protectPrivateWindowsFileCommandSync(fd, targetPath, parentIdentity).identity;
+}
+export async function protectCreatedFile(fd, targetPath, parentIdentity) {
+    const native = getNativeBinding();
+    if (typeof native?.protectPrivateWindowsFile === "function") {
+        return native.protectPrivateWindowsFile(fd, targetPath, parentIdentity).identity;
+    }
+    commandFallback();
+    return (await protectPrivateWindowsFileCommand(fd, targetPath, parentIdentity)).identity;
+}
+export function verifyCreatedFileSync(fd, targetPath, identity, parentIdentity, links = 1) {
+    const native = getNativeBinding();
+    if (typeof native?.verifyPrivateWindowsFile === "function") {
+        native.verifyPrivateWindowsFile(fd, targetPath, identity, parentIdentity, links);
+        return;
+    }
+    commandFallback();
+    verifyPrivateWindowsFileCommandSync(fd, targetPath, identity, parentIdentity, links);
+}
+export async function verifyCreatedFile(fd, targetPath, identity, parentIdentity, links = 1) {
+    const native = getNativeBinding();
+    if (typeof native?.verifyPrivateWindowsFile === "function") {
+        native.verifyPrivateWindowsFile(fd, targetPath, identity, parentIdentity, links);
+        return;
+    }
+    commandFallback();
+    await verifyPrivateWindowsFileCommand(fd, targetPath, identity, parentIdentity, links);
+}

package/dist/directory-durability.d.ts

@@ -1,5 +1,5 @@
 import { type Stats } from "node:fs";
-import { type FileIdentityStat } from "./file-identity.js";
+import type { FileIdentityStat } from "./file-identity.js";
 export type DirectorySyncOutcome = {
     status: "synced";
 } | {

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

@@ -1 +1 @@
-{"version":3,"file":"directory-durability.d.ts","sourceRoot":"","sources":["../src/directory-durability.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAM7C,OAAO,EAAoB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAI7E,MAAM,MAAM,oBAAoB,GAC5B;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,KAAK,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG;IACvD,UAAU,EAAE,oBAAoB,GAAG;QAAE,MAAM,EAAE,YAAY,CAAA;KAAE,CAAC;CAC7D,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wBAAwB,CAAC,EAAE,gBAAgB,CAAC;IAC5C,MAAM,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD,CAAC;AAwOF,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,eAAe,CAAC,CAe1B;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAqB/B;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,oBAAoB,CAyCtB;AAED,wBAAsB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAElF;AAED,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAMvE;AAiCD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CA2FlC"}
+{"version":3,"file":"directory-durability.d.ts","sourceRoot":"","sources":["../src/directory-durability.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAM7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAa3D,MAAM,MAAM,oBAAoB,GAC5B;IAAE,MAAM,EAAE,QAAQ,CAAA;CAAE,GACpB;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,KAAK,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG;IACvD,UAAU,EAAE,oBAAoB,GAAG;QAAE,MAAM,EAAE,YAAY,CAAA;KAAE,CAAC;CAC7D,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wBAAwB,CAAC,EAAE,gBAAgB,CAAC;IAC5C,MAAM,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD,CAAC;AAkHF,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,eAAe,CAAC,CAe1B;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,oBAAoB,CAAC,CAqB/B;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,GAAG,gBAAgB,EACpC,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,oBAAoB,CAkCtB;AAED,wBAAsB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAElF;AAED,wBAAgB,2BAA2B,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAMvE;AAiCD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,6BAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CA6FlC"}

package/dist/directory-durability.js

@@ -3,7 +3,8 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { ensureAbsoluteDirectory } from "./absolute-path.js";
 import { FsSafeError } from "./errors.js";
-import { sameFileIdentity } from "./file-identity.js";
+import { assertDirectoryReceiptCurrentSync, copyRetainedDirectoryReceipt, createDirectoryReceiptSync, directoryReceiptAuthority, directoryReceiptIdentity, ownDirectoryReceipt, } from "./directory-receipt.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
 import { realpathSync } from "./realpath.js";
 function directoryOpenFlags() {
@@ -38,81 +39,23 @@ function unsupportedOutcome(error) {
     const code = error.code;
     return code ? { status: "unsupported", code } : { status: "unsupported" };
 }
-function assertDirectory(identity, pathname, label) {
-    if (identity.isSymbolicLink() || !identity.isDirectory()) {
-        throw new FsSafeError("not-file", `${label} must be a real directory: ${pathname}`);
-    }
-}
-function ownDirectoryReceipt(receipt) {
-    const pathname = receipt.path;
-    const realPath = receipt.realPath;
-    const identity = receipt.identity;
-    return { path: pathname, realPath, identity };
-}
-function assertDirectoryReceiptPaths(receipt, label) {
-    assertNoWindowsPathAlias(receipt.path, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
-    assertNoWindowsPathAlias(receipt.realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
-}
 async function createDirectoryReceipt(directoryPath, label) {
-    assertNoWindowsPathAlias(directoryPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
-    const resolvedPath = resolvePathPreservingWindowsRoot(directoryPath);
-    assertNoWindowsPathAlias(resolvedPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
-    const operationPath = pathForWindowsFilesystem(resolvedPath);
-    const identity = fsSync.lstatSync(operationPath);
-    assertDirectory(identity, resolvedPath, label);
-    const realPath = realpathSync.native(operationPath);
-    assertNoWindowsPathAlias(realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
-    return {
-        path: resolvedPath,
-        realPath,
-        identity,
-    };
-}
-function createDirectoryReceiptSync(directoryPath, label) {
-    assertNoWindowsPathAlias(directoryPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
-    const resolvedPath = resolvePathPreservingWindowsRoot(directoryPath);
-    assertNoWindowsPathAlias(resolvedPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
-    const operationPath = pathForWindowsFilesystem(resolvedPath);
-    const identity = fsSync.lstatSync(operationPath);
-    assertDirectory(identity, resolvedPath, label);
-    const realPath = realpathSync(operationPath);
-    assertNoWindowsPathAlias(realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
-    return {
-        path: resolvedPath,
-        realPath,
-        identity,
-    };
+    return createDirectoryReceiptSync(directoryPath, label, realpathSync.native);
 }
 async function assertDirectoryReceiptCurrent(receipt, label) {
-    assertDirectoryReceiptPaths(receipt, label);
-    const operationPath = pathForWindowsFilesystem(receipt.path);
-    const currentIdentity = fsSync.lstatSync(operationPath);
-    assertDirectory(currentIdentity, receipt.path, label);
-    const realPath = realpathSync.native(operationPath);
-    assertNoWindowsPathAlias(realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
-    if (!sameFileIdentity(receipt.identity, currentIdentity) ||
-        realPath !== receipt.realPath) {
-        throw new FsSafeError("path-mismatch", `${label} changed during durable directory operation: ${receipt.path}`);
-    }
+    assertDirectoryReceiptCurrentSync(receipt, label, realpathSync.native);
 }
-function assertDirectoryReceiptCurrentSync(receipt, label) {
-    assertDirectoryReceiptPaths(receipt, label);
-    const operationPath = pathForWindowsFilesystem(receipt.path);
-    const currentIdentity = fsSync.lstatSync(operationPath);
-    assertDirectory(currentIdentity, receipt.path, label);
-    const realPath = realpathSync(operationPath);
-    assertNoWindowsPathAlias(realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
-    if (!sameFileIdentity(receipt.identity, currentIdentity) ||
-        realPath !== receipt.realPath) {
-        throw new FsSafeError("path-mismatch", `${label} changed during durable directory operation: ${receipt.path}`);
-    }
+function assertOpenDirectoryIdentity(descriptor, receipt, label) {
+    inspectFileIdentitySync(() => {
+        const opened = fsSync.fstatSync(descriptor, { bigint: true });
+        if (!opened.isDirectory()) {
+            throw new FsSafeError("not-file", `${label} must be a real directory: ${receipt.path}`);
+        }
+        return opened;
+    }, directoryReceiptAuthority(receipt).identity);
 }
 async function assertOpenDirectoryCurrent(handle, receipt, label) {
-    const openedIdentity = fsSync.fstatSync(handle.fd);
-    assertDirectory(openedIdentity, receipt.path, label);
-    if (!sameFileIdentity(receipt.identity, openedIdentity)) {
-        throw new FsSafeError("path-mismatch", `${label} handle changed during directory sync: ${receipt.path}`);
-    }
+    assertOpenDirectoryIdentity(handle.fd, receipt, label);
     await assertDirectoryReceiptCurrent(receipt, label);
 }
 class PinnedDirectoryImpl {
@@ -124,7 +67,7 @@ class PinnedDirectoryImpl {
     constructor(handle, receipt, label) {
         this.#handle = handle;
         this.#authority = receipt;
-        this.receipt = ownDirectoryReceipt(receipt);
+        this.receipt = copyRetainedDirectoryReceipt(receipt);
         this.#label = label;
     }
     async assertCurrent() {
@@ -213,11 +156,7 @@ export function syncDirectorySync(directory, options = {}) {
         return unsupportedOutcome(error);
     }
     try {
-        const openedIdentity = fsSync.fstatSync(descriptor);
-        assertDirectory(openedIdentity, receipt.path, label);
-        if (!sameFileIdentity(receipt.identity, openedIdentity)) {
-            throw new FsSafeError("path-mismatch", `${label} handle changed during directory sync: ${receipt.path}`);
-        }
+        assertOpenDirectoryIdentity(descriptor, receipt, label);
         assertDirectoryReceiptCurrentSync(receipt, label);
         try {
             fsSync.fsyncSync(descriptor);
@@ -273,13 +212,16 @@ export async function ensureDurableDirectory(options) {
     assertNoWindowsPathAlias(requestedDirectoryPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
     const directoryPath = resolvePathPreservingWindowsRoot(requestedDirectoryPath);
     assertNoWindowsPathAlias(directoryPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    const expectedInput = options.expectedExistingIdentity;
+    const expectedIdentity = expectedInput && directoryReceiptIdentity(expectedInput);
     const ancestorReceipt = await findExistingAncestorReceipt(directoryPath, label);
     const targetExists = ancestorReceipt.path === directoryPath;
-    const expectedExistingIdentity = options.expectedExistingIdentity;
-    if (expectedExistingIdentity &&
-        (!targetExists || !sameFileIdentity(expectedExistingIdentity, ancestorReceipt.identity))) {
+    if (expectedIdentity && !targetExists) {
         throw new FsSafeError("path-mismatch", `${label} changed before durable directory pinning: ${directoryPath}`);
     }
+    if (expectedIdentity) {
+        inspectFileIdentitySync(() => directoryReceiptAuthority(ancestorReceipt).identity, expectedIdentity);
+    }
     const ancestor = await pinDirectory(ancestorReceipt, { label });
     const pinnedDirectories = [ancestor];
     try {
@@ -336,7 +278,7 @@ export async function ensureDurableDirectory(options) {
         }
         await ancestor.assertCurrent();
         await assertDirectoryReceiptCurrent(finalReceipt, label);
-        return { ...finalReceipt, parentSync };
+        return Object.assign(copyRetainedDirectoryReceipt(finalReceipt), { parentSync });
     }
     finally {
         await Promise.all(pinnedDirectories.toReversed().map(async (directory) => directory.close()));

package/dist/directory-guard.d.ts

@@ -34,6 +34,9 @@ export declare function assertAsyncDirectoryGuard(guard: AnyAsyncDirectoryGuard)
 export declare function createSyncDirectoryGuard(dir: string): SyncDirectoryGuard;
 export declare function assertSyncDirectoryGuard(guard: SyncDirectoryGuard | AnyAsyncDirectoryGuard): void;
 export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string): Promise<AsyncDirectoryGuard>;
+export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string, options: {
+    bigint: true;
+}): Promise<AsyncDirectoryGuard<BigIntStats>>;
 export declare function createNearestExistingDirectoryGuard(rootReal: string, targetPath: string, options: {
     bigint: boolean;
 }): Promise<AnyAsyncDirectoryGuard>;

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

@@ -1 +1 @@
-{"version":3,"file":"directory-guard.d.ts","sourceRoot":"","sources":["../src/directory-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAelD,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC5B,MAAM,uBAAuB,CAAC;AAE/B,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,KAAK,GAAG,WAAW,GAAG,KAAK,IAAI;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,CAAC,CAAC;CACT,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,mBAAmB,CAAC,KAAK,GAAG,WAAW,CAAC,CAAC;AAE9E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CAAC;AAEH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAGnF;AAED,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,IAAI,CAAC,iBAAiB,EAAE,KAAK,GAAG,KAAK,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACvE,IAAI,CAaN;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,OAAO,CAAC,EAAE,WAAW,CAAA;CAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC,CAAC;AACpJ,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;AACnH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;AActH,wBAAsB,yBAAyB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB5F;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CASxE;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,kBAAkB,GAAG,sBAAsB,GAAG,IAAI,CAsBjG;AAED,wBAAgB,mCAAmC,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;AACxH,wBAAgB,mCAAmC,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAuBzJ,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,kBAAkB,CAgBpB;AAGD,wBAAsB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAM7H;AAOD,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,GACxB,WAAW,CAAC;AACf,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,GAC3B,KAAK,CAAC;AAaT,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,EAC3C,OAAO,CAAC,EAAE,WAAW,EACrB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,WAAW,CAMb;AAkBD,MAAM,MAAM,yBAAyB,GAAG,sBAAsB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnG,wBAAgB,+BAA+B,CAC7C,WAAW,EAAE,sBAAsB,EACnC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GACf,yBAAyB,CAK3B;AAID,wBAAgB,+BAA+B,CAC7C,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,sBAAsB,CAOxB;AAED,wBAAgB,8BAA8B,CAC5C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,iBAAiB,GAC1B,KAAK,GAAG,WAAW,CAOrB;AAED,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,yBAAyB,GAAG,IAAI,CAU1F"}
+{"version":3,"file":"directory-guard.d.ts","sourceRoot":"","sources":["../src/directory-guard.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAelD,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,sBAAsB,EAC5B,MAAM,uBAAuB,CAAC;AAE/B,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,KAAK,GAAG,WAAW,GAAG,KAAK,IAAI;IACvE,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,CAAC,CAAC;CACT,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAAG,mBAAmB,CAAC,KAAK,GAAG,WAAW,CAAC,CAAC;AAE9E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,KAAK,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CAAC;AAEH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAGnF;AAED,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,IAAI,CAAC,iBAAiB,EAAE,KAAK,GAAG,KAAK,CAAC,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GACvE,IAAI,CAaN;AAED,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,IAAI,CAAC;IAAC,OAAO,CAAC,EAAE,WAAW,CAAA;CAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC,CAAC;AACpJ,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;AACnH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;AActH,wBAAsB,yBAAyB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB5F;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CASxE;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,kBAAkB,GAAG,sBAAsB,GAAG,IAAI,CAsBjG;AAED,wBAAgB,mCAAmC,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;AACxH,wBAAgB,mCAAmC,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,WAAW,CAAC,CAAC,CAAC;AAChK,wBAAgB,mCAAmC,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;AAuBzJ,wBAAgB,uCAAuC,CACrD,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,kBAAkB,CAgBpB;AAGD,wBAAsB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAM7H;AAOD,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,MAAM,EAAE,IAAI,CAAA;CAAE,GACxB,WAAW,CAAC;AACf,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,GAC3B,KAAK,CAAC;AAaT,wBAAgB,4BAA4B,CAC1C,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,EAC3C,OAAO,CAAC,EAAE,WAAW,EACrB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,WAAW,CAMb;AAkBD,MAAM,MAAM,yBAAyB,GAAG,sBAAsB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnG,wBAAgB,+BAA+B,CAC7C,WAAW,EAAE,sBAAsB,EACnC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GACf,yBAAyB,CAK3B;AAID,wBAAgB,+BAA+B,CAC7C,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,iBAAiB,GAC3B,sBAAsB,CAOxB;AAED,wBAAgB,8BAA8B,CAC5C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,iBAAiB,GAC1B,KAAK,GAAG,WAAW,CAOrB;AAED,wBAAgB,mCAAmC,CAAC,KAAK,EAAE,yBAAyB,GAAG,IAAI,CAU1F"}

package/dist/directory-mode-node.d.ts

@@ -1,5 +1,7 @@
 import { type BigIntStats } from "node:fs";
 import { type DirectoryModeOwner } from "./directory-mode-owner.js";
+/** Darwin descriptor inspection avoids requesting directory-content reads. */
+export declare function nodeDarwinDirectoryMetadataFlags(): number;
 export declare function nodeDirectorySearchOnlyFlags(): {
     flags: number;
     proc: boolean;

package/dist/directory-mode-node.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"directory-mode-node.d.ts","sourceRoot":"","sources":["../src/directory-mode-node.ts"],"names":[],"mappings":"AAAA,OAAe,EAAa,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAK9D,OAAO,EAA0C,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE5G,wBAAgB,4BAA4B,IAAI;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAO3F;AAED,2FAA2F;AAC3F,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE,OAAO,CAAC,kBAAkB,CAAC,CAsE7B;AAED,mFAAmF;AACnF,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE;IAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAAC,KAAK,IAAI,IAAI,CAAA;CAAE,CAsFlE"}
+{"version":3,"file":"directory-mode-node.d.ts","sourceRoot":"","sources":["../src/directory-mode-node.ts"],"names":[],"mappings":"AAAA,OAAe,EAAa,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAK9D,OAAO,EAA0C,KAAK,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE5G,8EAA8E;AAC9E,wBAAgB,gCAAgC,IAAI,MAAM,CAMzD;AAED,wBAAgB,4BAA4B,IAAI;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAO3F;AAED,2FAA2F;AAC3F,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE,OAAO,CAAC,kBAAkB,CAAC,CAsE7B;AAED,mFAAmF;AACnF,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE;IAAE,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAAC,KAAK,IAAI,IAAI,CAAA;CAAE,CAsFlE"}

package/dist/directory-mode-node.js

@@ -4,6 +4,14 @@ import { FsSafeError } from "./errors.js";
 import { inspectDirectoryIdentity, inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertOwnedDirectory, ownDirectoryMode } from "./directory-mode-owner.js";
+/** Darwin descriptor inspection avoids requesting directory-content reads. */
+export function nodeDarwinDirectoryMetadataFlags() {
+    if (process.platform !== "darwin" || (process.arch !== "x64" && process.arch !== "arm64")) {
+        throw new FsSafeError("helper-unavailable", "Darwin directory metadata descriptors are unavailable");
+    }
+    // Darwin SDK O_EVTONLY; Node omits this flag from its exported constants.
+    return 0x8000 | constants.O_DIRECTORY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+}
 export function nodeDirectorySearchOnlyFlags() {
     if (process.arch !== "x64" && process.arch !== "arm64")
         return undefined;

package/dist/directory-receipt.d.ts

@@ -0,0 +1,24 @@
+import { type BigIntStats, type Stats } from "node:fs";
+import type { DirectoryReceipt } from "./directory-durability.js";
+import type { FileIdentityStat } from "./file-identity.js";
+type ExactIdentity = Readonly<Pick<BigIntStats, "dev" | "ino">>;
+declare const numericFields: readonly ["dev", "mode", "nlink", "uid", "gid", "rdev", "blksize", "ino", "size", "blocks"];
+declare const timeFields: readonly ["atime", "mtime", "ctime", "birthtime"];
+type DirectoryMetadata = Pick<Stats, typeof numericFields[number] | `${typeof timeFields[number]}Ms`>;
+type DirectoryProvenance = Readonly<{
+    identity: ExactIdentity;
+    metadata: Readonly<DirectoryMetadata>;
+}>;
+type DirectoryAuthority = DirectoryProvenance & Readonly<{
+    path: string;
+    realPath: string;
+}>;
+export declare function directoryReceiptIdentity(identity: FileIdentityStat): ExactIdentity;
+export declare function directoryReceiptAuthority(receipt: DirectoryReceipt): DirectoryAuthority;
+export declare function ownDirectoryReceipt(receipt: DirectoryReceipt): DirectoryReceipt;
+export declare function copyRetainedDirectoryReceipt(receipt: DirectoryReceipt): DirectoryReceipt;
+export declare function createDirectoryReceiptFromIdentity(pathname: string, realPath: string, exactStat: BigIntStats): DirectoryReceipt;
+export declare function createDirectoryReceiptSync(directoryPath: string, label: string, canonicalize?: (pathname: string) => string): DirectoryReceipt;
+export declare function assertDirectoryReceiptCurrentSync(receipt: DirectoryReceipt, label: string, canonicalize?: (pathname: string) => string): void;
+export {};
+//# sourceMappingURL=directory-receipt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"directory-receipt.d.ts","sourceRoot":"","sources":["../src/directory-receipt.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAGlE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAQ3D,KAAK,aAAa,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC;AAChE,QAAA,MAAM,aAAa,YAAI,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAU,CAAC;AAClH,QAAA,MAAM,UAAU,YAAI,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,CAAU,CAAC;AACrE,KAAK,iBAAiB,GAAG,IAAI,CAAC,KAAK,EAAE,OAAO,aAAa,CAAC,MAAM,CAAC,GAAG,GAAG,OAAO,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACtG,KAAK,mBAAmB,GAAG,QAAQ,CAAC;IAClC,QAAQ,EAAE,aAAa,CAAC;IACxB,QAAQ,EAAE,QAAQ,CAAC,iBAAiB,CAAC,CAAC;CACvC,CAAC,CAAC;AACH,KAAK,kBAAkB,GAAG,mBAAmB,GAAG,QAAQ,CAAC;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC,CAAC;AAOH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,aAAa,CAuBlF;AA8BD,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,gBAAgB,GAAG,kBAAkB,CAEvF;AAQD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CAE/E;AAED,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,gBAAgB,GAAG,gBAAgB,CAGxF;AA0BD,wBAAgB,kCAAkC,CAChD,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,WAAW,GACrB,gBAAgB,CAOlB;AAED,wBAAgB,0BAA0B,CACxC,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,MAAM,EACb,YAAY,GAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAqB,GACxD,gBAAgB,CASlB;AAED,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,MAAM,EACb,YAAY,GAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAqB,GACxD,IAAI,CAUN"}

package/dist/directory-receipt.js

@@ -0,0 +1,127 @@
+import fs, {} from "node:fs";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { realpathSync } from "./realpath.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+const numericFields = ["dev", "mode", "nlink", "uid", "gid", "rdev", "blksize", "ino", "size", "blocks"];
+const timeFields = ["atime", "mtime", "ctime", "birthtime"];
+// Live pins retain private authority. New admissions snapshot the supplied
+// fields and accept exact provenance only while its public identity is intact.
+const authorities = new WeakMap();
+const identities = new WeakMap();
+export function directoryReceiptIdentity(identity) {
+    if (!identity) {
+        throw new FsSafeError("path-mismatch", "directory receipt identity is missing");
+    }
+    const known = identities.get(identity);
+    const dev = identity.dev;
+    const ino = identity.ino;
+    if (known) {
+        const matches = (value, expected) => typeof value === "bigint" ? value === expected : value === Number(expected);
+        if (!matches(dev, known.identity.dev) || !matches(ino, known.identity.ino)) {
+            throw new FsSafeError("path-mismatch", "directory receipt identity changed");
+        }
+        return known.identity;
+    }
+    const exact = (value) => {
+        if ((typeof value !== "bigint" && !Number.isSafeInteger(value)) ||
+            (process.platform === "win32" && (value === 0 || value === 0n))) {
+            throw new FsSafeError("path-mismatch", "directory receipt identity could not be verified");
+        }
+        return BigInt(value);
+    };
+    return Object.freeze({ dev: exact(dev), ino: exact(ino) });
+}
+function snapshotDirectoryReceipt(receipt) {
+    const pathname = receipt?.path;
+    const realPath = receipt?.realPath;
+    const stat = receipt?.identity;
+    if (typeof pathname !== "string" || typeof realPath !== "string" || stat == null) {
+        throw new FsSafeError("path-mismatch", "directory receipt is incomplete");
+    }
+    assertNoWindowsPathAlias(pathname, "filesystem");
+    assertNoWindowsPathAlias(realPath, "filesystem");
+    const identity = directoryReceiptIdentity(stat);
+    const known = authorities.get(receipt);
+    if (known && (pathname !== known.path || realPath !== known.realPath ||
+        identity.dev !== known.identity.dev || identity.ino !== known.identity.ino)) {
+        throw new FsSafeError("path-mismatch", "directory receipt changed before admission");
+    }
+    const metadata = known?.metadata ?? identities.get(stat)?.metadata ?? snapshotDirectoryMetadata(stat, identity);
+    return Object.freeze({ path: pathname, realPath, identity, metadata });
+}
+function snapshotDirectoryMetadata(stat, identity) {
+    const metadata = {};
+    for (const field of numericFields) {
+        metadata[field] = field === "dev" || field === "ino" ? Number(identity[field]) : stat[field];
+    }
+    for (const field of timeFields)
+        metadata[`${field}Ms`] = stat[`${field}Ms`];
+    return Object.freeze(metadata);
+}
+export function directoryReceiptAuthority(receipt) {
+    return authorities.get(receipt) ?? snapshotDirectoryReceipt(receipt);
+}
+function rememberReceipt(receipt, authority) {
+    authorities.set(receipt, authority);
+    identities.set(receipt.identity, authority);
+    return receipt;
+}
+export function ownDirectoryReceipt(receipt) {
+    return receiptFromAuthority(snapshotDirectoryReceipt(receipt));
+}
+export function copyRetainedDirectoryReceipt(receipt) {
+    const authority = directoryReceiptAuthority(receipt);
+    return receiptFromAuthority(authority);
+}
+function receiptFromAuthority(authority) {
+    return rememberReceipt({
+        path: authority.path,
+        realPath: authority.realPath,
+        identity: Object.assign(Object.create(fs.Stats.prototype), authority.metadata),
+    }, authority);
+}
+function numericDirectoryMetadata(exact) {
+    // Keep metadata and authority from one observation. A second pathname stat
+    // can describe a replacement even when a later fence sees the original again.
+    const metadata = {};
+    for (const field of numericFields) {
+        metadata[field] = Number(exact[field]);
+    }
+    for (const field of timeFields) {
+        const nanoseconds = exact[`${field}Ns`];
+        const remainder = ((nanoseconds % 1000000000n) + 1000000000n) % 1000000000n;
+        metadata[`${field}Ms`] = Number((nanoseconds - remainder) / 1000000000n) * 1_000 + Number(remainder) / 1_000_000;
+    }
+    return Object.freeze(metadata);
+}
+// The caller already admitted the exact observation and its paths.
+export function createDirectoryReceiptFromIdentity(pathname, realPath, exactStat) {
+    return receiptFromAuthority(Object.freeze({
+        path: pathname,
+        realPath,
+        identity: Object.freeze({ dev: exactStat.dev, ino: exactStat.ino }),
+        metadata: numericDirectoryMetadata(exactStat),
+    }));
+}
+export function createDirectoryReceiptSync(directoryPath, label, canonicalize = realpathSync) {
+    assertNoWindowsPathAlias(directoryPath, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    const pathname = resolvePathPreservingWindowsRoot(directoryPath);
+    assertNoWindowsPathAlias(pathname, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    const exact = inspectDirectoryIdentitySync(pathname);
+    const operationPath = pathForWindowsFilesystem(pathname);
+    const realPath = canonicalize(operationPath);
+    assertNoWindowsPathAlias(realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
+    return createDirectoryReceiptFromIdentity(pathname, realPath, exact);
+}
+export function assertDirectoryReceiptCurrentSync(receipt, label, canonicalize = realpathSync) {
+    const authority = directoryReceiptAuthority(receipt);
+    assertNoWindowsPathAlias(authority.path, "filesystem", `${label} path uses a Windows filesystem namespace alias`);
+    assertNoWindowsPathAlias(authority.realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
+    inspectDirectoryIdentitySync(authority.path, authority.identity);
+    const realPath = canonicalize(pathForWindowsFilesystem(authority.path));
+    assertNoWindowsPathAlias(realPath, "filesystem", `${label} real path uses a Windows filesystem namespace alias`);
+    if (realPath !== authority.realPath) {
+        throw new FsSafeError("path-mismatch", `${label} changed during durable directory operation: ${authority.path}`);
+    }
+}

package/dist/file-cleanup.d.ts

@@ -0,0 +1,19 @@
+import { type BigIntStats } from "node:fs";
+import fs, { type FileHandle } from "node:fs/promises";
+import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
+export declare function hasErrorCode(error: unknown, expected: string): boolean;
+type OwnedPathCleanupStatus = "removed" | "name-absent" | "preserved";
+export declare function removeOwnedPath(params: {
+    fsModule: Pick<typeof fs, "lstat" | "unlink">;
+    pathname: string;
+    identity?: BigIntStats;
+}): Promise<OwnedPathCleanupStatus>;
+export declare function cleanupPinnedFilePath(params: {
+    pathname: string;
+    handle: Pick<FileHandle, "fd">;
+    identity?: BigIntStats;
+    parentGuard: AnyAsyncDirectoryGuard;
+    throwOnCleanupError?: boolean;
+}): Promise<OwnedPathCleanupStatus>;
+export {};
+//# sourceMappingURL=file-cleanup.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-cleanup.d.ts","sourceRoot":"","sources":["../src/file-cleanup.ts"],"names":[],"mappings":"AAAA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,EAAE,EAAE,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAA6B,KAAK,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAI9F,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAStE;AAED,KAAK,sBAAsB,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,CAAC;AAEtE,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,QAAQ,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,OAAO,GAAG,QAAQ,CAAC,CAAC;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAoBlC;AAGD,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAC/B,QAAQ,CAAC,EAAE,WAAW,CAAC;IACvB,WAAW,EAAE,sBAAsB,CAAC;IACpC,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAgClC"}

package/dist/file-cleanup.js

@@ -0,0 +1,78 @@
+import syncFs, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import { assertAsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+export function hasErrorCode(error, expected) {
+    if ((typeof error !== "object" || error === null) && typeof error !== "function") {
+        return false;
+    }
+    try {
+        return Reflect.get(error, "code") === expected;
+    }
+    catch {
+        return false;
+    }
+}
+export async function removeOwnedPath(params) {
+    if (!params.identity)
+        return "preserved";
+    try {
+        const current = params.fsModule === fs
+            ? syncFs.lstatSync(params.pathname, { bigint: true })
+            : await params.fsModule.lstat(params.pathname, { bigint: true });
+        if (current.isSymbolicLink() ||
+            !current.isFile() ||
+            current.nlink !== 1n ||
+            !sameFileIdentityForCleanup(current, params.identity)) {
+            return "preserved";
+        }
+        await params.fsModule.unlink(params.pathname);
+        return "removed";
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT"))
+            return "name-absent";
+        throw error;
+    }
+}
+// Borrowed handle: the caller retains it until guarded cleanup finishes.
+export async function cleanupPinnedFilePath(params) {
+    if (!params.identity)
+        return "preserved";
+    try {
+        const guard = params.parentGuard;
+        if ([guard.stat.dev, guard.stat.ino].some((value) => typeof value === "number" && !Number.isSafeInteger(value)))
+            return "preserved";
+        await assertAsyncDirectoryGuard(guard);
+        const parent = syncFs.lstatSync(guard.dir, { bigint: true });
+        if (parent.isSymbolicLink() || !parent.isDirectory() ||
+            !sameFileIdentityForCleanup(parent, guard.stat))
+            return "preserved";
+        const opened = syncFs.fstatSync(params.handle.fd, { bigint: true });
+        if (!opened.isFile() || opened.nlink !== 1n ||
+            !sameFileIdentityForCleanup(opened, params.identity))
+            return "preserved";
+    }
+    catch (error) {
+        // Unverifiable authority must preserve the path and the original write failure.
+        if (params.throwOnCleanupError &&
+            !(error instanceof FsSafeError && error.category === "policy") &&
+            !hasErrorCode(error, "ENOENT") && !hasErrorCode(error, "ENOTDIR") &&
+            !hasErrorCode(error, "ELOOP"))
+            throw error;
+        return "preserved";
+    }
+    try {
+        return await removeOwnedPath({
+            fsModule: fs,
+            pathname: params.pathname,
+            identity: params.identity,
+        });
+    }
+    catch (error) {
+        if (params.throwOnCleanupError)
+            throw error;
+        return "preserved";
+    }
+}

package/dist/file-observation.d.ts

@@ -1,4 +1,4 @@
-type FailureKind = "identity" | "resolution" | `open:${string}` | `exclusive-create:${string}` | `unlinked:${string}` | `changed:${string}` | `stat-leaf-missing:${string}`;
+type FailureKind = "identity" | "resolution" | `open:${string}` | `exclusive-create:${string}` | `unlinked:${string}` | `changed:${string}` | `stat-leaf-missing:${string}` | `stat-leaf-changed:${string}`;
 export declare function recordFileObservationFailure(error: unknown, kind: FailureKind): void;
 export declare function isFileObservationFailure(error: unknown, kind: FailureKind): boolean;
 export declare function fileObservation(): {

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

@@ -1 +1 @@
-{"version":3,"file":"file-observation.d.ts","sourceRoot":"","sources":["../src/file-observation.ts"],"names":[],"mappings":"AAEA,KAAK,WAAW,GAAG,UAAU,GAAG,YAAY,GAAG,QAAQ,MAAM,EAAE,GAAG,oBAAoB,MAAM,EAAE,GAAG,YAAY,MAAM,EAAE,GAAG,WAAW,MAAM,EAAE,GAAG,qBAAqB,MAAM,EAAE,CAAC;AAG5K,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAMpF;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAEnF;AAGD,wBAAgB,eAAe;IAG3B,GAAG,CAAC,CAAC,aAAa,MAAM,CAAC,GAAG,CAAC;IAC7B,GAAG,QAAQ,OAAO,QAAQ,WAAW,GAAG,OAAO;EAElD"}
+{"version":3,"file":"file-observation.d.ts","sourceRoot":"","sources":["../src/file-observation.ts"],"names":[],"mappings":"AAEA,KAAK,WAAW,GAAG,UAAU,GAAG,YAAY,GAAG,QAAQ,MAAM,EAAE,GAAG,oBAAoB,MAAM,EAAE,GAAG,YAAY,MAAM,EAAE,GAAG,WAAW,MAAM,EAAE,GAAG,qBAAqB,MAAM,EAAE,GAAG,qBAAqB,MAAM,EAAE,CAAC;AAG5M,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAMpF;AAED,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAEnF;AAGD,wBAAgB,eAAe;IAG3B,GAAG,CAAC,CAAC,aAAa,MAAM,CAAC,GAAG,CAAC;IAC7B,GAAG,QAAQ,OAAO,QAAQ,WAAW,GAAG,OAAO;EAElD"}