@openclaw/fs-safe 0.14.0 → 0.16.0

package/dist/creation-file-state.js

@@ -0,0 +1,118 @@
+import fs, {} from "node:fs";
+import fsAsync from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { hasUnsettledWindowsSecurityCommand } from "./windows-security-command.js";
+import { assertDarwinCreationAcl } from "./creation-darwin.js";
+export function assertCreationFile(fd, pathname, expected) {
+    const opened = inspectFileIdentitySync(() => fs.fstatSync(fd, { bigint: true }), expected);
+    const named = inspectFileIdentitySync(() => fs.lstatSync(pathname, { bigint: true }), opened);
+    if (!opened.isFile() || !named.isFile() || named.isSymbolicLink() || opened.nlink !== 1n || named.nlink !== 1n) {
+        throw new FsSafeError("path-mismatch", "created file is not the expected single-linked regular file");
+    }
+    return opened;
+}
+export function assertPrivateCreationFile(stat, fd) {
+    if (process.platform === "win32")
+        return;
+    if (typeof process.getuid !== "function" || stat.uid !== BigInt(process.getuid())) {
+        throw new FsSafeError("not-owned", "created private file must belong to the current user");
+    }
+    if ((stat.mode & 3647n) !== 0n) {
+        throw new FsSafeError("insecure-permissions", "created private file is not owner-only");
+    }
+    assertDarwinCreationAcl(fd);
+}
+function assertRecordedFile(current, identity) {
+    if (!current.isFile() || current.isSymbolicLink() || !sameFileIdentityForCleanup(current, identity)) {
+        throw new FsSafeError("path-mismatch", "created file cleanup preserved a replacement");
+    }
+}
+export function removeRecordedCreationFileSync(pathname, identity, assertParent) {
+    assertParent();
+    let current;
+    try {
+        current = fs.lstatSync(pathname, { bigint: true });
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return;
+        throw error;
+    }
+    assertRecordedFile(current, identity);
+    fs.unlinkSync(pathname);
+}
+export async function removeRecordedCreationFile(pathname, identity, assertParent) {
+    assertParent();
+    let current;
+    try {
+        current = await fsAsync.lstat(pathname, { bigint: true });
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return;
+        throw error;
+    }
+    assertParent();
+    assertRecordedFile(current, identity);
+    // Recheck after the awaited observation before dispatching the unlink.
+    assertRecordedFile(fs.lstatSync(pathname, { bigint: true }), identity);
+    await fsAsync.unlink(pathname);
+}
+export function creationPublicationAfterFailure(error, recorded) {
+    if (error instanceof FsSafeError) {
+        const publication = error.details?.publication;
+        if (publication && typeof publication === "object" && "status" in publication &&
+            publication.status === "indeterminate")
+            return "indeterminate";
+    }
+    return recorded;
+}
+export function hasPreservedCreationArtifacts(error) {
+    if (!(error instanceof FsSafeError))
+        return false;
+    if (error.details?.cleanup === "preserved" || error.details?.cleanup === "failed")
+        return true;
+    const publication = error.details?.publication;
+    return publication !== null && typeof publication === "object" && "status" in publication &&
+        (publication.status === "published" || publication.status === "indeterminate");
+}
+export function rethrowPrivateStageCreationFailure(error, path, stageDirectory) {
+    if (error instanceof FsSafeError && error.code === "already-exists") {
+        throw new FsSafeError("helper-failed", "private file staging path already exists", {
+            cause: error, details: { publication: { status: "not-published" }, path, stageDirectory },
+        });
+    }
+    const publication = error instanceof FsSafeError ? error.details?.publication : undefined;
+    const created = error instanceof FsSafeError && error.details?.path === stageDirectory &&
+        publication !== null && typeof publication === "object" && "status" in publication &&
+        publication.status === "published";
+    let unconfirmed = hasUnsettledWindowsSecurityCommand(error);
+    if (error !== null && (typeof error === "object" || typeof error === "function")) {
+        try {
+            const outcome = Object.getOwnPropertyDescriptor(error, "creationOutcome");
+            unconfirmed ||= Boolean(outcome && "value" in outcome && outcome.value === "unconfirmed");
+        }
+        catch {
+            unconfirmed = true;
+        }
+    }
+    if (created || unconfirmed) {
+        throw privateFileSettlementFailure({
+            primary: error, cleanup: [], publication: "not-published", path, stageDirectory, preserved: true,
+        });
+    }
+    throw error;
+}
+export function privateFileSettlementFailure(params) {
+    return new FsSafeError("helper-failed", "file creation or staging settlement failed", {
+        cause: params.cleanup.length
+            ? new AggregateError([params.primary, ...params.cleanup], "file creation and cleanup failed")
+            : params.primary,
+        details: {
+            publication: { status: params.publication }, path: params.path, stageDirectory: params.stageDirectory,
+            cleanup: params.preserved || params.publication === "indeterminate" ? "preserved" : params.cleanup.length ? "failed" : "removed",
+        },
+    });
+}

package/dist/creation-path.d.ts

@@ -0,0 +1,21 @@
+import { type BigIntStats } from "node:fs";
+import { type AsyncDirectoryGuard, type AnyAsyncDirectoryGuard } from "./directory-guard.js";
+export type CreationParentIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+    realPath?: string;
+}>;
+export type CreationPath = {
+    target: string;
+    parent: AsyncDirectoryGuard<BigIntStats>;
+    assertParent(): void;
+};
+export declare function creationAdmissionFromParent(parent: AnyAsyncDirectoryGuard): {
+    expectedParentIdentity: CreationParentIdentity;
+};
+export declare function prepareCreationPath(input: string, expectedParent?: CreationParentIdentity): CreationPath;
+export declare function creationCollision(error: unknown): unknown;
+/** Remove only the recorded empty stage; never traverse a replaced directory. */
+export declare function removeCreationDirectory(directory: string, identity: BigIntStats, assertParent: () => void): void;
+export declare function removeCreationDirectoryAsync(directory: string, identity: BigIntStats, assertParent: () => void): Promise<void>;
+//# sourceMappingURL=creation-path.d.ts.map

package/dist/creation-path.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"creation-path.d.ts","sourceRoot":"","sources":["../src/creation-path.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAG/C,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC5B,MAAM,sBAAsB,CAAC;AAM9B,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IACzC,YAAY,IAAI,IAAI,CAAC;CACtB,CAAC;AAEF,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,sBAAsB,GAAG;IAAE,sBAAsB,EAAE,sBAAsB,CAAA;CAAE,CAO9H;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,sBAAsB,GAAG,YAAY,CAuBxG;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAKzD;AAED,iFAAiF;AACjF,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,IAAI,GAAG,IAAI,CAQhH;AAED,wBAAsB,4BAA4B,CAChD,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,IAAI,GACjE,OAAO,CAAC,IAAI,CAAC,CAQf"}

package/dist/creation-path.js

@@ -0,0 +1,71 @@
+import fs, {} from "node:fs";
+import fsAsync from "node:fs/promises";
+import path from "node:path";
+import { assertDirectoryIdentitySync, inspectDirectoryIdentitySync, } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { assertNoNulPathInput } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
+export function creationAdmissionFromParent(parent) {
+    const { dev, ino } = parent.stat;
+    if (typeof dev !== "bigint" || typeof ino !== "bigint") {
+        throw new FsSafeError("path-mismatch", "private creation requires an exact parent identity");
+    }
+    const identity = inspectDirectoryIdentitySync(parent.dir, { dev, ino });
+    return { expectedParentIdentity: { dev: identity.dev, ino: identity.ino, realPath: parent.realPath } };
+}
+export function prepareCreationPath(input, expectedParent) {
+    expectedParent = expectedParent && { dev: expectedParent.dev, ino: expectedParent.ino, realPath: expectedParent.realPath };
+    assertNoNulPathInput(input);
+    assertNoWindowsPathAlias(input, "filesystem");
+    if (process.platform === "win32" && input.replaceAll("/", "\\").split("\\")
+        .some(component => component.endsWith(".") || component.endsWith(" "))) {
+        throw new FsSafeError("invalid-path", "creation path contains an ambiguous Windows component");
+    }
+    const target = resolvePathPreservingWindowsRoot(input);
+    const directory = path.dirname(target);
+    if (target === directory || input.length === 0) {
+        throw new FsSafeError("invalid-path", "creation requires a child name");
+    }
+    if (expectedParent)
+        assertDirectoryIdentitySync(directory, expectedParent);
+    const stat = inspectDirectoryIdentitySync(directory);
+    const realPath = realpathSync.native(directory);
+    const parent = { dir: directory, realPath, stat };
+    const assertParent = () => {
+        assertDirectoryIdentitySync(directory, { dev: stat.dev, ino: stat.ino, realPath });
+        if (expectedParent)
+            assertDirectoryIdentitySync(directory, expectedParent);
+    };
+    assertParent();
+    return { target, parent, assertParent };
+}
+export function creationCollision(error) {
+    if (error?.code === "EEXIST") {
+        return new FsSafeError("already-exists", "creation target already exists", { cause: error });
+    }
+    return error;
+}
+/** Remove only the recorded empty stage; never traverse a replaced directory. */
+export function removeCreationDirectory(directory, identity, assertParent) {
+    assertParent();
+    try {
+        assertDirectoryIdentitySync(directory, identity);
+        fs.rmdirSync(directory);
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+    }
+}
+export async function removeCreationDirectoryAsync(directory, identity, assertParent) {
+    assertParent();
+    try {
+        assertDirectoryIdentitySync(directory, identity);
+        await fsAsync.rmdir(directory);
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+    }
+}

package/dist/creation-permissions.d.ts

@@ -0,0 +1,19 @@
+export type CreationPermissions = {
+    private?: boolean;
+    mode?: number;
+};
+export declare function resolveCreationPermissions(options: CreationPermissions, directory: boolean): {
+    private: boolean;
+    mode: number | undefined;
+};
+export declare function assertPrivateFileCreationAvailable(): void;
+/** Full Windows identity, with security validation when requested; no repairs. */
+export declare function inspectCreationDirectorySync(targetPath: string, privatePath: boolean): string;
+export declare function inspectCreationDirectory(targetPath: string, privatePath: boolean): Promise<string>;
+export declare function assertPrivateDirectorySync(targetPath: string): void;
+export declare function assertPrivateDirectory(targetPath: string): Promise<void>;
+export declare function protectCreatedFileSync(fd: number, targetPath: string, parentIdentity: string): string;
+export declare function protectCreatedFile(fd: number, targetPath: string, parentIdentity: string): Promise<string>;
+export declare function verifyCreatedFileSync(fd: number, targetPath: string, identity: string, parentIdentity: string, links?: number): void;
+export declare function verifyCreatedFile(fd: number, targetPath: string, identity: string, parentIdentity: string, links?: number): Promise<void>;
+//# sourceMappingURL=creation-permissions.d.ts.map

package/dist/creation-permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"creation-permissions.d.ts","sourceRoot":"","sources":["../src/creation-permissions.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,mBAAmB,GAAG;IAAE,OAAO,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,mBAAmB,EAC5B,SAAS,EAAE,OAAO,GACjB;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAehD;AAeD,wBAAgB,kCAAkC,IAAI,IAAI,CAOzD;AAOD,kFAAkF;AAClF,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,MAAM,CAQ7F;AAED,wBAAsB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAQxG;AAED,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAQnE;AAED,wBAAsB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ9E;AAED,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAOrG;AAED,wBAAsB,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAOhH;AAED,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,SAAI,GAClF,IAAI,CAQN;AAED,wBAAsB,iBAAiB,CACrC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,KAAK,SAAI,GAClF,OAAO,CAAC,IAAI,CAAC,CAQf"}

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":"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"}
+{"version":3,"file":"directory-guard.d.ts","sourceRoot":"","sources":["../src/directory-guard.ts"],"names":[],"mappings":"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"}

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-mode-owner.js

@@ -43,10 +43,10 @@ export function ownDirectoryMode(params) {
             // Hooks/ancestor checks can yield; recheck the original named association.
             await params.inspect();
             checks.check?.();
-            let dispatchDeadlineError;
+            let dispatchDeadlineFailure;
             if (currentMode !== mode) {
+                checks.check?.();
                 try {
-                    checks.check?.();
                     await params.chmod(mode);
                 }
                 catch (error) {
@@ -58,13 +58,13 @@ export function ownDirectoryMode(params) {
                     checks.check?.();
                 }
                 catch (error) {
-                    dispatchDeadlineError = error;
+                    dispatchDeadlineFailure = { error };
                 }
                 await params.verifyChmod?.();
             }
             const finalMode = await params.inspect();
-            if (dispatchDeadlineError)
-                throw dispatchDeadlineError;
+            if (dispatchDeadlineFailure)
+                throw dispatchDeadlineFailure.error;
             checks.check?.();
             if (!params.ignoreChmodError && finalMode !== mode) {
                 throw new FsSafeError("path-mismatch", "directory final mode could not be verified");